diff --git a/CHANGELOG.md b/CHANGELOG.md index 05aedca..5ef675a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.6.14 + +- Linux x64: Firecracker v1.17.0 ships inside `@gildforge/cli-linux-x64` next to `gild` (Apache-2.0; LICENSE, NOTICE and THIRD-PARTY in `vendor/firecracker/`), checked against a pinned sha256 and the one Firecracker publishes. gild uses `vm.firecracker` from isolation.json, then the bundled one, then `firecracker` on PATH. +- `gild spawn --vm --detach` output reaches `output.log` and `gild attach`: the guest terminal fed only its last listener, so the log stayed empty. Output from before the first listener and an exit before anyone listened are kept too. +- A detached session's output outlives it as `~/.gild/sessions/.output.log` (0600, newest 10 kept), and `gild attach --watch ` prints it after the session ended. Short `--vm --detach` runs no longer vanish without a trace. +- Git works in a Firecracker guest: `/workspace` keeps the host uid while the agent runs as root, which stopped every git command at "detected dubious ownership"; the guest now trusts `/workspace`. +- docs/VM.md: which VM `--vm` uses where (Multipass on macOS by default, vz only with a `vm` block in isolation.json), and that Firecracker guests have no network by default, so the agent edits in the VM and the host commits and pushes. + ## 0.6.13 - `gild spawn --vm` works on Apple silicon: gild publishes a linux-arm64 build (`@gildforge/cli-linux-arm64`, with its node-pty prebuild), so the agent inside the arm64 Multipass VM has its own `gild` for git credentials and pull requests. Before, every `gild` call in that VM failed with "no build for linux-arm64". diff --git a/README.md b/README.md index f7e5feb..e08c35a 100644 --- a/README.md +++ b/README.md @@ -248,7 +248,10 @@ for `attach` to replay and appends everything to `~/.gild/sessions//output.log` (0600, 8 MiB, one rotation to `output.log.1`). Keystrokes from `attach` go through the same input tracking as an attached spawn, so an unsent draft still holds injected messages. Detaching never stops -the agent; `gild stop` does, and removes the socket, settings and log with it. +the agent; `gild stop` does, and removes the socket and settings with it. The +output outlives the session as `~/.gild/sessions/.output.log` (0600; the +newest 10 ended sessions are kept), and `gild attach --watch ` prints it +once the session has ended. `--detach` combines with `--vm`: `gild spawn --vm --detach --name bob claude` runs the child in a microVM with no terminal, and `send`, `attach`, `sync` and @@ -256,16 +259,16 @@ runs the child in a microVM with no terminal, and `send`, `attach`, `sync` and ### microVM sessions (`--vm`) -`gild spawn --vm` runs the agent in a Firecracker microVM on a copy of the -working directory (`gild sync ` brings changes back; exit does too). Build -the guest image once per gild version on an x86_64 Linux host with Docker: - -```sh -bun run vm:image # in a gildforge/cli checkout; writes ~/.config/gild/vm/ -``` - -A guest image built for another gild version is refused at boot with that same -command as the fix. Details: [docs/VM.md](docs/VM.md). +`gild spawn --vm` runs the agent in a VM: Firecracker on Linux, Multipass on +macOS and Windows (vz on macOS only when isolation.json sets up a `vm`). On +Linux the npm package ships Firecracker next to `gild`, and the guest image is +downloaded on first use; you need `/dev/kvm` and `mke2fs`. The guest works on a +copy of the working directory with no network by default: the agent edits +there, its file changes come back to the host (`gild sync `, and at exit), +and the host commits and pushes. Commits made in the guest stay in the guest +(host Git metadata is protected). Multipass VMs push from inside. Details, and +building the guest image yourself: [docs/VM.md](docs/VM.md). A guest image +built for another gild version is refused at boot. Automatic sync protects host Git metadata and retains incomplete work for recovery. Published images currently cover Linux x64 and Apple Silicon; they diff --git a/docs/VM.md b/docs/VM.md index af15ddc..79e7a0d 100644 --- a/docs/VM.md +++ b/docs/VM.md @@ -1,9 +1,63 @@ # microVM guest image -`gild spawn --vm` and `gild runner start --isolation vm` boot a microVM -(Firecracker on Linux, Virtualization.framework on macOS) from a kernel and a -read-only ext4 root filesystem holding `gild-guest-agent` and `/init-gild.sh`. -All of it comes out of this repository. +`gild spawn --vm` and `gild runner start --isolation vm` boot a microVM from a +kernel and a read-only ext4 root filesystem holding `gild-guest-agent` and +`/init-gild.sh`. All of it comes out of this repository. + +Which VM `--vm` uses: + +| host | backend | +|---|---| +| Linux x64 | Firecracker (shipped with gild, below) | +| macOS, Windows | Multipass: one Ubuntu VM, made on first use and kept | +| macOS with a `vm` block in `/isolation.json` | Virtualization.framework (`vz`), the guest image below | + +## Firecracker ships with gild (Linux x64) + +`@gildforge/cli-linux-x64`, the package npm installs for `gildforge` on Linux +x64, carries `bin/firecracker` next to `bin/gild`: Firecracker v1.17.0 +(Apache-2.0; its `LICENSE`, `NOTICE` and `THIRD-PARTY` are in +`vendor/firecracker/`). `scripts/vendor-firecracker.mjs` takes it from the +upstream release tarball when the packages are built, and refuses it unless +the tarball matches both the pin in `scripts/firecracker.json` and the sha256 +Firecracker publishes beside it. + +gild runs, in this order: `vm.firecracker` from `isolation.json`, the +`firecracker` next to the gild executable, then `firecracker` on `PATH`. The +host still needs `/dev/kvm` (read and write for your user) and `mke2fs` +(e2fsprogs). + +## Network, git and getting work out + +A Firecracker guest has **no network device** unless the owner ran +`sudo scripts/vm-network-setup.sh` once (a `gildbr0` bridge and tap devices +that allow the internet and deny the host, the LAN and metadata addresses); +`gild spawn --vm` prints which one applies: + +``` +gild: vm network: none, egress blocked (no gildbr0 bridge; enable with: sudo scripts/vm-network-setup.sh) +``` + +So on Linux the agent **edits in the VM and the host commits and pushes**: + +- The working directory, `.git` included, is copied into the guest at + `/workspace`. Git works there (gild sets `safe.directory=/workspace` for the + guest, whose files keep your uid while the agent runs as root), so the agent + can diff, branch and commit locally. +- File changes come back to the host at exit and with `gild sync `, + three-way against what was copied in; a file you changed on the host + meanwhile is kept and the guest's copy saved aside. +- Changes under `.git` never come back (host Git metadata is protected): a + commit made in the guest stays in the guest, and the session keeps its VM + workspace for recovery (`~/.gild/sessions/.vm-*`, `recovery.json`) and + exits nonzero. Have the agent leave its changes uncommitted, then commit, + push and open the pull request on the host (`gild pr create … --agent