From edb63d35f66084debae72d1632a64e48542ab37a Mon Sep 17 00:00:00 2001 From: Sami Fouad Date: Wed, 14 Oct 2026 17:03:25 -0600 Subject: [PATCH 1/3] VM pty: every listener gets the output, early output and exit are held; detached sessions keep their output after exit --- scripts/fixtures/detach-harness.py | 6 ++++ src/isolation/session.test.ts | 52 ++++++++++++++++++++++++++++++ src/isolation/session.ts | 37 +++++++++++++++------ src/spawn-attach.ts | 18 +++++++++-- src/spawn-detach.test.ts | 39 ++++++++++++++++++++-- src/spawn-detach.ts | 44 +++++++++++++++++++++++-- src/spawn-vm.ts | 5 ++- 7 files changed, 181 insertions(+), 20 deletions(-) diff --git a/scripts/fixtures/detach-harness.py b/scripts/fixtures/detach-harness.py index 03357da..aeabeb9 100644 --- a/scripts/fixtures/detach-harness.py +++ b/scripts/fixtures/detach-harness.py @@ -206,6 +206,12 @@ def states(): check(not (SESSIONS / 'stubborn').exists() and not (SESSIONS / 'stubborn.sock').exists(), 'stubborn left files') r = cli('stop', 'stubborn') check(r.returncode == 1 and b'No live session stubborn' in r.stderr, r) + # The output outlives the session: private, and readable with attach --watch. + kept = SESSIONS / 'stubborn.output.log' + check(kept.exists() and b'"ready": true' in kept.read_bytes(), 'output not kept') + check(kept.stat().st_mode & 0o777 == 0o600, oct(kept.stat().st_mode)) + r = cli('attach', '--watch', 'stubborn') + check(r.returncode == 0 and b'"ready": true' in r.stdout and b'stubborn has ended' in r.stderr, r) else: raise SystemExit(f'unknown case {CASE}') print(json.dumps({'case': CASE, 'passed': True})) diff --git a/src/isolation/session.test.ts b/src/isolation/session.test.ts index ced0e73..d246afb 100644 --- a/src/isolation/session.test.ts +++ b/src/isolation/session.test.ts @@ -5,6 +5,7 @@ import { REBUILD_HINT, checkGuestProtocol, guestPing, + guestPty, type Opener, } from './session' @@ -60,3 +61,54 @@ test('a newer agent is refused too, and a matching one passes', async () => { test('sync-back needs protocol 2 or later (list and get)', () => { expect(GUEST_PROTOCOL).toBeGreaterThanOrEqual(2) }) + +/** A guest agent whose pty prints `early` as soon as it starts; `say` and + * `exit` drive it afterwards. */ +function ptyAgent(early: string[]) { + let data: (c: Buffer) => void = () => {} + const framed = (value: unknown) => { + const body = Buffer.from(JSON.stringify(value)) + const head = Buffer.alloc(4) + head.writeUInt32BE(body.length) + return Buffer.concat([head, body]) + } + const say = (c: string) => + data(framed({ t: 'out', d: Buffer.from(c).toString('base64') })) + const opener: Opener = async () => ({ + // Replies arrive synchronously, before guestPty's caller can listen. + write: () => early.forEach(say), + onData: (cb) => (data = cb), + onClose() {}, + close() {}, + }) + return { opener, say, exit: (code: number) => data(framed({ t: 'exit', code })) } +} +const request = { + argv: ['bash'], + env: {}, + cwd: '/workspace', + cols: 80, + rows: 24, +} + +test('every guest pty listener gets the output, and the first one gets what came before it', async () => { + const agent = ptyAgent(['EARLY ']) + const pty = await guestPty(agent.opener, request) + // A detached session listens twice: the output log, then the quiet detector. + const log: string[] = [], + quiet: string[] = [] + pty.onData((d) => log.push(d.toString())) + pty.onData((d) => quiet.push(d.toString())) + agent.say('Linux (none) 5.10') + expect(log.join('')).toBe('EARLY Linux (none) 5.10') + expect(quiet.join('')).toBe('Linux (none) 5.10') +}) + +test('a guest pty exit before anyone listens is replayed to onExit', async () => { + const agent = ptyAgent([]) + const pty = await guestPty(agent.opener, request) + agent.exit(3) + const codes: number[] = [] + pty.onExit((c) => codes.push(c)) + expect(codes).toEqual([3]) +}) diff --git a/src/isolation/session.ts b/src/isolation/session.ts index 931e8b9..676ba9b 100644 --- a/src/isolation/session.ts +++ b/src/isolation/session.ts @@ -297,14 +297,22 @@ export async function guestPty( request: PtyRequest, ): Promise { const ch = await open() + // Every onData listener sees every byte (a detached session has two: the + // output log and the quiet detector). Output that arrives before the first + // listener is held for it, and an exit that comes before onExit is replayed. let buf = Buffer.alloc(0), - exited = false, - dataCb: (d: Buffer) => void = () => {}, - exitCb: (code: number) => void = () => {} + exitCode: number | undefined, + pending: Buffer[] | undefined = [] + const dataCbs: ((d: Buffer) => void)[] = [], + exitCbs: ((code: number) => void)[] = [] + const emit = (d: Buffer) => { + if (pending) pending.push(d) + else for (const cb of dataCbs) cb(d) + } const done = (code: number) => { - if (exited) return - exited = true - exitCb(code) + if (exitCode !== undefined) return + exitCode = code + for (const cb of exitCbs) cb(code) } ch.onData((chunk) => { buf = Buffer.concat([buf, chunk]) @@ -312,10 +320,10 @@ export async function guestPty( const n = buf.readUInt32BE(0) const r = JSON.parse(buf.subarray(4, 4 + n).toString()) as Reply buf = buf.subarray(4 + n) - if (r.t === 'out') dataCb(Buffer.from(r.d, 'base64')) + if (r.t === 'out') emit(Buffer.from(r.d, 'base64')) else if (r.t === 'exit') done(r.code) else if (r.t === 'error') { - dataCb(Buffer.from(`gild: ${r.message}\r\n`)) + emit(Buffer.from(`gild: ${r.message}\r\n`)) done(127) } } @@ -326,8 +334,17 @@ export async function guestPty( write: (d) => ch.write(frame({ t: 'in', d: Buffer.from(d).toString('base64') })), resize: (cols, rows) => ch.write(frame({ t: 'resize', cols, rows })), - onData: (cb) => (dataCb = cb), - onExit: (cb) => (exitCb = cb), + onData: (cb) => { + dataCbs.push(cb) + if (!pending) return + const held = pending + pending = undefined + for (const d of held) cb(d) + }, + onExit: (cb) => { + exitCbs.push(cb) + if (exitCode !== undefined) cb(exitCode) + }, close: () => ch.close(), } } diff --git a/src/spawn-attach.ts b/src/spawn-attach.ts index 71b9c10..9537a15 100644 --- a/src/spawn-attach.ts +++ b/src/spawn-attach.ts @@ -1,7 +1,8 @@ import type { ChildProcess, SpawnOptions } from 'node:child_process' import { createConnection } from 'node:net' import { Command, InvalidArgumentError } from 'commander' -import type { StartMessage } from './spawn-detach' +import { readFile } from 'node:fs/promises' +import { endedLogPath, type StartMessage } from './spawn-detach' import { privateSessionsDirectory, socketPath } from './spawn-sessions' /** Caller side of detached sessions: `gild spawn --detach`, `gild attach`, @@ -120,7 +121,20 @@ export async function attachSession(id: string, watch: boolean) { ) socket.on('error', (error) => { cleanup() - reject(sessionError(id, error)) + const failure = sessionError(id, error) + if (failure === error) return reject(failure) + // An ended session: show the output it left behind. + const path = endedLogPath(directory, id) + readFile(path).then( + (log) => { + process.stdout.write(log) + process.stderr.write( + `\r\n[${id} has ended; its output is kept in ${path}]\r\n`, + ) + resolve() + }, + () => reject(failure), + ) }) const show = (data: Buffer) => { if (data.length && !process.stdout.write(data)) socket.pause() diff --git a/src/spawn-detach.test.ts b/src/spawn-detach.test.ts index 2b1aad9..917b066 100644 --- a/src/spawn-detach.test.ts +++ b/src/spawn-detach.test.ts @@ -1,7 +1,21 @@ import { expect, test } from 'bun:test' -import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises' +import { + mkdir, + mkdtemp, + readFile, + readdir, + rm, + stat, + utimes, + writeFile, +} from 'node:fs/promises' import { join, resolve } from 'node:path' -import { OutputLog, OutputRing } from './spawn-detach' +import { + OutputLog, + OutputRing, + endedLogPath, + pruneEndedLogs, +} from './spawn-detach' test('the output ring keeps only the most recent bytes, in order', () => { const ring = new OutputRing(10) @@ -66,3 +80,24 @@ for (const scenario of ['no-tty', 'send', 'attach', 'stop']) { } }, 55000) } + +test('only the newest ended-session logs are kept', async () => { + await mkdir(resolve('.tmp'), { recursive: true }) + const root = await mkdtemp(resolve('.tmp/ended-')) + try { + for (let i = 0; i < 4; i++) { + const path = endedLogPath(root, `s${i}`) + await writeFile(path, `${i}`) + await utimes(path, 1000 + i, 1000 + i) + } + await writeFile(join(root, 'live.sock.txt'), 'not a log') + pruneEndedLogs(root, 2) + expect((await readdir(root)).sort()).toEqual([ + 'live.sock.txt', + 's2.output.log', + 's3.output.log', + ]) + } finally { + await rm(root, { recursive: true, force: true }) + } +}) diff --git a/src/spawn-detach.ts b/src/spawn-detach.ts index 56e725c..a53bb8b 100644 --- a/src/spawn-detach.ts +++ b/src/spawn-detach.ts @@ -1,14 +1,17 @@ import { chmodSync, closeSync, + existsSync, fchmodSync, mkdirSync, openSync, + readdirSync, renameSync, rmSync, + statSync, writeSync, } from 'node:fs' -import { join } from 'node:path' +import { basename, dirname, join } from 'node:path' import type { Socket } from 'node:net' import type { RecoveryLocation } from './isolation/sync' @@ -19,6 +22,30 @@ export const DEFAULT_ROWS = 40 export const RING_BYTES = 256 * 1024 export const LOG_BYTES = 8 * 1024 * 1024 const MAX_VIEWER_BACKLOG = 1024 * 1024 +/** Ended sessions whose output is kept (newest first); each is at most LOG_BYTES. */ +export const KEPT_LOGS = 10 +const ENDED_LOG = '.output.log' + +/** Where an ended session's output stays: `/.output.log` (0600). */ +export const endedLogPath = (sessions: string, id: string) => + join(sessions, id + ENDED_LOG) + +/** Keep only the newest `keep` ended-session logs in `sessions`. */ +export function pruneEndedLogs(sessions: string, keep = KEPT_LOGS) { + const logs = readdirSync(sessions) + .filter((name) => name.endsWith(ENDED_LOG)) + .map((name) => { + const path = join(sessions, name) + try { + return { path, mtime: statSync(path).mtimeMs } + } catch { + return undefined + } + }) + .filter((log) => log !== undefined) + .sort((a, b) => b.mtime - a.mtime) + for (const { path } of logs.slice(keep)) rmSync(path, { force: true }) +} /** The most recent PTY output, bounded; replayed to whoever attaches. */ export class OutputRing { @@ -207,10 +234,21 @@ export class DetachedHost { this.viewers.clear() return sockets } - /** Removes the log with the rest of the session's private files. */ + /** Removes the session's private files but keeps its latest output as + * `/.output.log`, so it can be read after the session ended + * (`gild attach --watch `); only the newest KEPT_LOGS are kept. */ cleanup() { this.log?.close() - if (this.directory) rmSync(this.directory, { recursive: true, force: true }) + if (!this.directory) return + const log = this.log?.path + if (log && existsSync(log)) { + const sessions = dirname(this.directory) + try { + renameSync(log, endedLogPath(sessions, basename(this.directory))) + pruneEndedLogs(sessions) + } catch {} + } + rmSync(this.directory, { recursive: true, force: true }) } } diff --git a/src/spawn-vm.ts b/src/spawn-vm.ts index 0705260..073e6fc 100644 --- a/src/spawn-vm.ts +++ b/src/spawn-vm.ts @@ -248,8 +248,6 @@ export async function startVmChild(opts: { cols: opts.cols, rows: opts.rows, }) - let exitCb: (e: { exitCode: number }) => void = () => {} - pty.onExit((code) => exitCb({ exitCode: code })) const conflictDir = join( await privateSessionsDirectory(), `${opts.sessionId}.conflicts`, @@ -288,7 +286,8 @@ export async function startVmChild(opts: { write: (d) => pty.write(d), resize: (c, r) => pty.resize(c, r), onData: (cb) => pty.onData(cb), - onExit: (cb) => (exitCb = cb), + // guestPty replays an exit that happened before this listener. + onExit: (cb) => pty.onExit((code) => cb({ exitCode: code })), pause() {}, resume() {}, kill: () => pty.close(), From 17804d58fec907da6798badb7f61d45b7ffae4d2 Mon Sep 17 00:00:00 2001 From: Sami Fouad Date: Wed, 14 Oct 2026 17:24:48 -0600 Subject: [PATCH 2/3] Bundle Firecracker with the Linux x64 package; git trusts /workspace in the guest; docs: VM backends and the edit-in-VM, push-from-host design --- CHANGELOG.md | 8 ++++ README.md | 25 ++++++----- docs/VM.md | 71 ++++++++++++++++++++++++++++--- scripts/firecracker.json | 11 +++++ scripts/pack.mjs | 14 +++++- scripts/packed-packages.mjs | 18 +++++++- scripts/vendor-firecracker.mjs | 61 ++++++++++++++++++++++++++ src/isolation/firecracker.test.ts | 28 +++++++++++- src/isolation/firecracker.ts | 17 +++++++- src/isolation/index.ts | 6 ++- src/isolation/session.test.ts | 6 ++- src/spawn-detach.ts | 3 +- src/spawn-vm.test.ts | 22 +++++++++- src/spawn-vm.ts | 15 ++++++- src/spawn-worker.ts | 21 ++++++--- src/spawn.ts | 2 +- 16 files changed, 292 insertions(+), 36 deletions(-) create mode 100644 scripts/firecracker.json create mode 100644 scripts/vendor-firecracker.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index 090225e..343edcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.6.13 + +- 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.12 - `gild setup` sets up your own gild in your Cloudflare account from a terminal (the same steps as gild desktop): it asks for the API token (not saved), the account, your name and email, and makes your gild key the owner. Running it again upgrades in place. 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