smol-symphony 0.1.0 → 0.2.0

package/AGENTS.md

@@ -1,35 +1,77 @@
 # AGENTS.md
 
-Standing instructions for any AI agent (Claude Code, Codex, OpenCode, etc.)
-working on this repo. Short list; keep it that way.
+Standing instructions and a small map for any AI agent (Claude Code, Codex,
+OpenCode, etc.) working on this repo. Keep it short.
+
+## Where things live
+
+- `src/orchestrator.ts` — top-level wiring; per-issue dispatch lifecycle entry.
+- `src/agent/runner.ts` — per-issue runner; owns the running-entry state the
+  Done-state action context is built from.
+- `src/mcp.ts` — MCP tools exposed to in-VM agents (`symphony.transition`,
+  `symphony.request_human_steering`, `symphony.propose_issue`).
+- `src/workflow.ts` — workflow file parser; the contract `WORKFLOW.template.md`
+  documents.
+- `src/trackers/local.ts` — local markdown tracker (only kind today).
+- `src/acp-bridge.ts` + `scripts/vm-agent.mjs` — host↔VM ACP transport.
+- `images/agents/` — the agent rootfs image (Node + the ACP coding-agent CLIs +
+  the in-VM `/opt/symphony/vm-agent.mjs` launcher), built **once** via
+  `npm run build:image`. Selected by `WORKFLOW.md`'s `gondolin.image` (a build
+  id or `name:tag` ref). See `images/agents/README.md`.
+- `src/http.ts` — HTTP dashboard + MCP endpoint listener.
+- `WORKFLOW.md` — canonical workflow this repo dispatches against itself.
+- `WORKFLOW.template.md` — annotated reference for workflow file syntax.
+- Handoff (push + PR) is documented in `README.md` § "After-run handoff".
 
 ## Workflow template stays in sync
 
-The repo ships two workflow files:
-
-- `WORKFLOW.md` — the canonical workflow used to dispatch agents against this
-  project.
-- `WORKFLOW.template.md` — the annotated reference covering every supported
-  option, its type, default, and example.
-
 **When you change anything that affects workflow file syntax or semantics,
 update `WORKFLOW.template.md` in the same commit.** Concretely:
 
 - Adding a new YAML key under `tracker:`, `polling:`, `workspace:`, `hooks:`,
-  `agent:`, `acp:`, `smolvm:`, `server:`, or `mcp:` → document it in the
+  `agent:`, `acp:`, `gondolin:`, `server:`, or `mcp:` → document it in the
   matching section of the template.
 - Renaming or removing a key → rename or remove it in the template too.
-- Changing a default value in `src/workflow.ts` (or whichever parser becomes
-  authoritative) → update the `Default:` annotation in the template.
-- Introducing a new top-level section → add a new section block to the
-  template.
-- Adding a new hook env var or Liquid context field → list it in the template
-  alongside the existing ones (under `hooks:` or under the prompt-body
-  comment).
+- Changing a default value in `src/workflow.ts` → update the `Default:`
+  annotation in the template.
+- Adding a new typed action-context variable (`$branch`, `$pr_title`, …) or
+  Liquid prompt-context field → list it in the template alongside the existing
+  ones.
 
 If you find the template already drifted from the parser at the start of your
-task, fix it as part of your change. The template is the contract for what
-operators can write; an out-of-date template is a bug, not paperwork.
+task, fix it as part of your change. An out-of-date template is a bug, not
+paperwork.
+
+## Where behavior belongs: orchestrator, typed actions, the image
+
+State-machine logic — new transitions, anything that mutates tracker files the
+orchestrator wrote, anything the runner must re-detect afterward — belongs in
+the orchestrator (runner / MCP / `src/orchestrator.ts`) behind typed APIs with
+tests. It is not an extension point you bolt on from the outside.
+
+Repo-local glue that fires on a transition (push the branch, open a PR) belongs
+in a state's typed `actions:` block — declarative records like `push_branch`,
+`create_pr_if_missing`, and `run_in_vm` that the action executor runs against a
+fixed context (`$branch`, `$base_branch`, `$pr_title`, `$pr_body_file`,
+`$repo`). See `states.Done.actions` in `WORKFLOW.md` for the canonical
+push-branch + open-PR pair, and `WORKFLOW.template.md` for the full kind list.
+
+Per-VM tooling — the CLIs and runtimes the agent needs at runtime — belongs in
+the agent image under `images/agents/`, baked once via `npm run build:image`.
+Canonical workspace setup (clone, base checkout, `agent/<id>` branch cut,
+remote stripping) is owned by the orchestrator's TypeScript `setupWorkspaceDir`;
+the surviving shell `hooks:` (`after_create` / `before_run` / `before_remove`)
+are only for additional repo-local prep on top of that, never for state-machine
+behavior.
+
+If you find yourself adding a `SYMPHONY_*` env var so a shell hook can reach
+into orchestrator-owned state, or writing a hook the runner then has to
+re-detect via a post-hook scan, that is the signal the logic is on the wrong
+side of the seam — surface it as a typed call (a transition, an MCP tool, or a
+typed action) instead. Issue bodies sometimes sketch a shell-shaped solution
+under an `after_run:` heading; `after_run` is no longer a hook kind (it was
+replaced by the typed `actions:` block above), so treat that as a sketch to
+re-express, not a directive.
 
 ## Build, test, and check before declaring done
 
@@ -37,30 +79,55 @@ operators can write; an out-of-date template is a bug, not paperwork.
 - `npm test` — must pass.
 - `npm run build` — must pass.
 
-Run all three before calling `symphony.mark_done`.
-
-## Handoff: patch bundle vs. pull request
+Run all three before calling `symphony.transition` into a terminal state.
 
-`after_run` in `WORKFLOW.md` ships in two modes:
+## Filing tracker issues
 
-- **Patch bundle (default).** Writes `git format-patch` to
-  `.symphony/patches/<branch>.patch` for human review. No remote needed.
-  This is what fires when no GitHub remote is wired up.
-- **Pull request.** Triggered when `SYMPHONY_REPO=<owner>/<repo>` is exported
-  before launch AND the working repo has an `origin` remote. The hook then
-  pushes the per-issue branch and runs `gh pr create`. `gh auth status` must
-  be clean on the host; the token never enters the VM.
-
-To switch this project to PR mode:
+When asked to file an issue against this repo's own tracker (the local Markdown
+tracker at `~/.symphony/trackers/smol-symphony/<state>/`), POST to the running
+symphony HTTP server rather than hand-writing the file or guessing the next
+identifier:
 
 ```
-git remote add origin git@github.com:<owner>/smol-symphony.git
-git push -u origin main
-SYMPHONY_REPO=<owner>/smol-symphony npx symphony WORKFLOW.md
+curl -s -X POST http://127.0.0.1:8787/api/v1/issues \
+  -H "content-type: application/json" \
+  --data-binary @/tmp/issue.json
+```
+
+Body shape (from `decideCreateIssue` in `src/http-handlers.ts`):
+
+```json
+{
+  "title": "required, non-empty",
+  "state": "Todo",              // optional; defaults to first declared active state
+  "identifier": "108",          // optional; auto-picked as next free integer
+  "description": "markdown body, written below the YAML front matter",
+  "priority": 2,                // optional integer; omitted ⇒ no `priority:` key
+  "labels": ["refactor"],       // optional
+  "blocked_by": ["107"]         // optional
+}
 ```
 
-`SYMPHONY_BASE_BRANCH` (default `main`) overrides the base the agent branches
-from and the PR opens against.
+State must be a declared non-terminal state (`active` or `holding`); terminals
+are closed to direct creation. The server stamps `created_at` / `updated_at`,
+allocates the next free numeric identifier when one isn't supplied, and writes
+`<tracker.root>/<state>/<identifier>.md`. Response is `201` with
+`{ path, identifier, state }`. Conflicts (duplicate identifier, bad state) come
+back as `400`/`409` with a typed error code.
+
+The HTTP server (`server.port` in `WORKFLOW.md`, currently `8787`) is unauthenticated
+inside the trusted tailscale boundary — no bearer, no CSRF on JSON POSTs from curl.
+If the server isn't running, hand-writing `~/.symphony/trackers/smol-symphony/<state>/<n>.md`
+with the same YAML front-matter shape (`id`, `identifier`, `title`, `created_at`,
+`updated_at`, optional `priority`/`labels`) is equivalent — see existing files
+under `Done/` for canonical examples.
+
+Issue bodies on this tracker follow a four-section shape: **Problem** (what's
+wrong / why now), **Change** (concrete edits, with file paths and line ranges
+where known), **allowed_paths** (the workspace scope the dispatched agent is
+permitted to touch), **Acceptance** (the checks that must pass before
+`symphony.transition` into a terminal state). Look at recent `Done/*.md` for the
+shape — these are the prompts the dispatched agent sees, so be specific.
 
 ## Don't write to generated state
 
@@ -69,5 +136,5 @@ Skip these when staging commits unless the user asks:
 - `.agents/`, `.claude/`, `.impeccable/` — local tooling state.
 - `issues*/Done/`, `issues*/Cancelled/`, `issues*/In Progress/` — runtime
   tracker artifacts from prior symphony runs.
-- `.symphony/` — workspaces, patch bundles, runtime caches.
+- `.symphony/` — workspaces, runtime caches.
 - `skills-lock.json` — auto-generated.

package/PRODUCT.md

@@ -23,7 +23,8 @@ process is logging.
 
 smol-symphony is a small TypeScript orchestrator that takes Markdown issues off a
 local tracker, prepares per-issue workspaces, and runs coding agents
-(Claude Code, Codex, OpenCode) inside isolated smolvm microVMs over ACP. The
+(Claude Code, Codex, OpenCode) inside isolated per-issue Gondolin microVMs over
+ACP. The
 HTTP dashboard exists to do two things well:
 
 1. **Dispatch** — create issues into the tracker without dropping back to the

package/README.md

@@ -1,77 +1,130 @@
 # smol-symphony
 
+> **Disclaimer:** this project is written using AI — the orchestrator
+> dispatches AI coding agents at itself, and the bulk of the code in this
+> repository was authored by those agents under human review.
+
 A small TypeScript orchestrator that reads issues off a local Markdown tracker,
 prepares per-issue workspaces, and runs coding agents (Claude Code, Codex,
-OpenCode) inside isolated [smolvm](https://smolmachines.com/) microVMs over the
-[Agent Client Protocol](https://agentclientprotocol.com).
+OpenCode) inside isolated per-issue [Gondolin](https://github.com/earendil-works/gondolin)
+microVMs over the [Agent Client Protocol](https://agentclientprotocol.com).
 
-The agent signals completion through an injected MCP server (`mark_done`,
-`request_human_steering`); the orchestrator handles state, retry, concurrency,
-and produces either a pull request or a `git format-patch` bundle per issue.
+The agent signals progress through an injected MCP server (`transition`,
+`request_human_steering`, `propose_issue`); the orchestrator handles state,
+retry, concurrency, and opens a pull request per issue when configured for
+a GitHub remote. In local-only mode the per-issue branch is left in the
+workspace for review.
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  symphony (node host)                                                    │
 │                                                                          │
-│   issues/<state>/*.md  ─┐                                                │
-│      WORKFLOW.md       ─┼──▶  orchestrator  ──▶  agent runner            │
-│      WORKFLOW.template.md │   (poll → reconcile → dispatch)              │
-│                          │                          │                    │
-│                          │                          ▼  ACP (JSON-RPC)    │
-│                          │                  ┌──────────────────────────┐ │
-│                          │                  │ smolvm (per-issue VM)    │ │
-│                          │                  │   adapter binary         │ │
-│                          │                  │   workspace mount        │ │
-│                          │                  │   mcp client ←───────────┼─┼─▶ symphony MCP
-│                          │                  └──────────────────────────┘ │     mark_done
-│                          ▼                                               │     request_human_steering
-│   HTTP dashboard (HTMX):  /                                              │
-│     attention · sessions · on disk · new issue · totals                  │
+│    ./issues/<state>/*.md  ──┐                                            │
+│    ./WORKFLOW.md            ├──▶  orchestrator  ──▶  agent runner        │
+│    ./WORKFLOW.template.md ──┘     poll · reconcile · dispatch            │
+│                                                          │               │
+│                                                          ▼  ACP/RPC      │
+│                                       ┌───────────────────────────────┐  │
+│                                       │ Gondolin  (per-issue VM)      │  │
+│                                       │   adapter (claude / codex)    │  │
+│                                       │   workspace mount             │  │
+│                                       │   mcp client  ────────────────┼─┐│
+│                                       └───────────────────────────────┘ ││
+│                                                                         ││
+│              symphony MCP server  ◀─────────────────────────────────────┘│
+│      ( transition · request_human_steering · propose_issue )             │
+│                                                                          │
+│    HTTP dashboard (HTMX):  /                                             │
+│      attention · sessions · on disk · new issue · totals                 │
 └──────────────────────────────────────────────────────────────────────────┘
 ```
 
+`SPEC.md` documents the contracts this repo's code references; for the
+original architectural narrative, see
+[openai/symphony/SPEC.md](https://github.com/openai/symphony/blob/main/SPEC.md).
+
 ## Quick start
 
 Prerequisites:
 
 - Node.js ≥ 20.
-- A `smolvm` binary on `$PATH` with the server reachable on the configured
-  endpoint (e.g. `smolvm serve start --listen unix:///run/user/$UID/smolvm.sock`).
-- A packed VM image (one-time): `bash scripts/build-vm.sh` produces
-  `.vm/symphony.smolmachine.smolmachine` (~1.1 GB; ships `claude-agent-acp`,
-  `codex-acp`, and `opencode` on the guest `$PATH`).
+- The agent rootfs image. Gondolin is the in-process microVM substrate
+  (`@earendil-works/gondolin`), so there is no separate VM daemon to run. The
+  agent image is built **once** from `images/agents/` via `npm run build:image`:
+  it starts from `node:24-bookworm-slim`, installs base CLI tooling, npm-installs
+  every ACP-capable coding agent (`claude-agent-acp`, `codex-acp`, `opencode`),
+  and bakes the in-VM stdio launcher at `/opt/symphony/vm-agent.mjs` into the
+  image. The build prints a content-addressed build id; pin it (or a
+  `name:tag` ref like `symphony-agents:latest`) in `WORKFLOW.md`'s
+  `gondolin.image`. See [images/agents/README.md](./images/agents/README.md)
+  for the build steps and requirements.
 - For the default `acp.adapter: claude`: a credentials file at
-  `~/.claude/.credentials.json` on the host (symphony reads and stages it; the
-  host directory is **not** bind-mounted into the VM).
+  `~/.claude/.credentials.json` on the host. Symphony reads it only on the
+  host side: the guest holds only a token-shaped placeholder, and the host
+  substitutes the real OAuth access token into the outbound request at
+  Gondolin egress (TLS-MITM). The credential file itself is never staged into
+  the VM.
 
-Run:
+Run, against an existing workflow file in the current directory:
 
 ```bash
-npm install
-npm run build
-npx symphony WORKFLOW.md
+npx smol-symphony WORKFLOW.md
 ```
 
+(Or `npm i -g smol-symphony` and then `symphony WORKFLOW.md` to skip the
+fetch.) Both invoke the `symphony` bin shipped in this package.
+
 Open the dashboard at `http://127.0.0.1:8787/`. Drop issues into
 `issues/Todo/` from the filesystem or the dashboard's `new issue` form;
 symphony dispatches them on the next poll.
 
+The console stays quiet: with the default log file configured, symphony prints
+a one-line-per-field startup banner (workflow, tracker root, dashboard URL,
+log-file path) and routes the structured `key=value` stream to
+`.symphony/logs/symphony.log` only. `tail -f` that file to follow the detail.
+Pass `--verbose` (alias `--foreground`) to mirror the structured stream back to
+the console for interactive debugging. With no log file configured (the
+`SYMPHONY_LOG_FILE=""` override), the structured stream stays on stderr.
+
+### From a checkout
+
+If you're hacking on symphony itself:
+
+```bash
+git clone https://github.com/dizk/smol-symphony.git
+cd smol-symphony
+npm install
+npm run build
+npx symphony WORKFLOW.md     # the local bin
+```
+
+`npm run dev` (via `tsx watch`) reruns on source edits.
+
 ## Local Markdown tracker
 
 Issues live as `.md` files under `tracker.root`. The parent directory is the
-issue state.
+issue state; the set of valid state directories comes from the `states:` block
+in `WORKFLOW.md` (see below) and is auto-mkdir'd on startup.
 
 ```
 issues/
 ├── Todo/
-│   ├── ABC-1.md
-│   └── ABC-2.md
-├── In Progress/
-│   └── ABC-3.md
-└── Done/
-    └── ABC-4.md
+│   ├── 1.md
+│   └── 2.md
+├── Review/
+│   └── 3.md
+├── Done/
+│   └── 4.md
+└── Triage/
+    └── 5.md
 ```
 
+The basename is the issue identifier. When a caller (dashboard form, MCP
+`propose_issue`) omits an explicit identifier, the tracker picks the next free
+positive integer by scanning every state directory under `tracker.root`.
+Operator-supplied identifiers (e.g. `CACHE-7.md`) pass through unchanged and
+coexist with the numeric ones.
+
 Each file has YAML front matter and an optional body:
 
 ```markdown
@@ -79,16 +132,16 @@ Each file has YAML front matter and an optional body:
 title: "Fix the login bug"
 priority: 2
 labels: [bug, auth]
-blocked_by: [ABC-5]
+blocked_by: [5]
 ---
 Long-form description in the body.
 ```
 
 State comparison is case-insensitive. Moving the file between state
 directories is the canonical state transition; the orchestrator does this
-itself in response to `mark_done`. The agent inside the VM does **not** have
-filesystem access to the tracker root: it signals completion through the
-MCP server and the orchestrator does the file move.
+itself in response to `symphony.transition`. The agent inside the VM does
+**not** have filesystem access to the tracker root: it signals progress
+through the MCP server and the orchestrator does the file move.
 
 ## WORKFLOW.md
 
@@ -98,9 +151,19 @@ this repo is the canonical project workflow; see
 [WORKFLOW.template.md](./WORKFLOW.template.md) for the annotated reference
 covering every supported option, its type, default, and example.
 
-Symphony watches the file and re-applies poll interval, concurrency, hooks,
-prompt body, smolvm settings, etc. on change without restart. In-flight runs
-keep the settings they started with.
+The workflow is a **state machine**. A required top-level `states:` block
+declares every state an issue can occupy, its `role` (`active` — dispatched;
+`terminal` — triggers cleanup and handoff; `holding` — sits outside the
+dispatch loop, e.g. `Triage`), and optional per-state `adapter`, `model`,
+`max_turns`, and `allowed_transitions` overrides. A single issue can travel
+through any number of states with distinct adapters and instructions; the
+prompt body can branch on the current state with Liquid
+`{% case issue.state %}`. The shipped workflow uses a two-stage
+`Todo → Review → Done` flow (Claude implements, Codex reviews).
+
+Symphony watches the file and re-applies poll interval, concurrency, typed
+actions, prompt body, gondolin settings, etc. on change without restart.
+In-flight runs keep the settings they started with.
 
 ## Dashboard
 
@@ -130,35 +193,45 @@ API clients. CSRF-relevant content types (`text/plain`,
 
 Symphony injects an MCP server into each ACP session at
 `http://<host>:<bound-port>/api/v1/issues/<id>/mcp`, gated by a per-dispatch
-bearer token. Two tools:
-
-- **`symphony.mark_done({ title, summary })`** — call once at end of a
-  successful run. `title` is a single-line imperative summary (≤72 chars);
-  `summary` is a one- to three-paragraph narrative. The orchestrator
-  atomically moves the issue file to the terminal state and stops
-  dispatching. The pair lands in
-  `<workspace>/.git/symphony-runtime/mark_done.md` (or
-  `<workspace>/.symphony-runtime/mark_done.md` when the workspace doesn't
-  have its own `.git/`) for the `after_run` hook to consume.
+bearer token. Three tools:
+
+- **`symphony.transition({ to_state, notes? })`** — canonical (and only)
+  exit verb. Moves the issue into another declared state, optionally
+  appending markdown `notes` to the issue body before the move so the next
+  agent (in `to_state`) reads them as part of `issue.description`. A
+  transition into a `role: terminal` state ends the run and triggers
+  workspace cleanup; transitions between active/holding states preserve the
+  workspace so the same `agent/<id>` git branch survives the handoff.
+  Rejected transitions (unknown target, disallowed by
+  `allowed_transitions`) return MCP tool-result errors the agent can read
+  and retry.
 - **`symphony.request_human_steering({ question, context? })`** — call
   when blocked on something only a human can answer. The turn ends
   immediately; the human's reply arrives as the prompt for the next turn.
   Steering-reply turns don't count against `agent.max_turns`.
-
-In smolvm, the VM's `127.0.0.1` transparently reaches the host's
+- **`symphony.propose_issue({ title, description?, labels?, priority? })`** —
+  call when the agent notices work that is out of scope for its current
+  task. The proposal lands in the `Triage/` state directory, which the
+  orchestrator does **not** dispatch; the operator approves (→ first active
+  state) or discards (→ first terminal state, prefers `Cancelled`) from the
+  dashboard. The calling issue's identifier and a timestamp are stamped into
+  the proposal's front-matter as `proposed_by` / `proposed_at` so provenance
+  is visible.
+
+In Gondolin, the VM's `127.0.0.1` transparently reaches the host's
 `127.0.0.1` (verified empirically), so the agent reaches the orchestrator
 without any mount or special host alias.
 
 ## ACP — adapter registry
 
 One ACP client (symphony's `agent/acp.ts`), two shipped adapter profiles.
-Each profile encodes the binary symphony launches and the host credential
-file it stages into the workspace before exec:
+Each profile encodes the binary symphony launches and the credential path
+the adapter reaches for inside the VM:
 
-| Adapter   | Binary             | Host credential file              |
+| Adapter   | Binary             | Credential surface                |
 | --------- | ------------------ | --------------------------------- |
-| `claude`  | `claude-agent-acp` | `~/.claude/.credentials.json`     |
-| `codex`   | `codex-acp`        | `~/.codex/auth.json`              |
+| `claude`  | `claude-agent-acp` | placeholder + host egress swap    |
+| `codex`   | `codex-acp`        | placeholder + host egress swap    |
 
 `WORKFLOW.md`:
 
@@ -171,44 +244,64 @@ acp:
   stall_timeout_ms: 300000
 ```
 
-Selecting an adapter is enough — symphony auto-derives the launch command
-that stages the credential into the workspace's runtime dir and copies it
-into the adapter's expected guest path before exec. Set `command:` only to
-override (testing a forked adapter, a non-standard binary path); doing so
-opts out of automatic credential staging.
-
-Credentials are **never bind-mounted from the host**. Symphony copies the
-single credential file into a per-workspace location (under `.git/` when
-the workspace has its own clone, else `.symphony-runtime/`) and refuses to
-operate on workspaces inside the credential file's ancestor repo.
-
-## After-run handoff: PR or patch
-
-`WORKFLOW.md`'s `after_run` hook ships in two modes:
-
-- **Pull request mode.** Triggered when `SYMPHONY_REPO=<owner>/<repo>` is
-  exported. The hook pushes the per-issue branch to GitHub and runs
-  `gh pr create --base $SYMPHONY_BASE_BRANCH ...`. Requires `gh auth status`
-  to be clean on the host. The token never enters the VM.
-- **Patch bundle mode** (default). Writes
-  `.symphony/patches/<branch>.patch` via `git format-patch` so you can
-  review and apply with `git am`. No remote required.
-
-The agent's `mark_done.md` provides the PR title/body or commit message; the
-hook reads it from the workspace's runtime dir.
-
-See [AGENTS.md](./AGENTS.md) for the env-var contract and switch-over
-commands.
+Selecting an adapter is enough — symphony auto-derives the launch command.
+For `claude`, a per-VM identity file (organization + account UUIDs only,
+no tokens) is staged into the workspace runtime dir and copied to
+`~/.claude.json` inside the VM; the guest holds only a token-shaped
+placeholder, and the host substitutes the real access token into the
+outbound request at Gondolin egress. For `codex`, no identity file is
+staged (OpenAI ships no third-party fingerprint check); the VM is launched
+with `OPENAI_API_KEY=<placeholder>`, and the host substitutes the real
+OpenAI credential at egress. Set `command:` only to override (testing a
+forked adapter, a non-standard binary path).
+
+Credentials **never enter the VM** for either adapter. For `claude`, the
+host's `~/.claude/.credentials.json` is read only on the host side; the VM
+sees `~/.claude.json` (identity-only) plus the placeholder value in its
+`Authorization` header, which the host swaps for the real token at egress.
+For `codex`, the host's `~/.codex/auth.json` (access token /
+`OPENAI_API_KEY`, **never** the refresh token) is read only host-side; the
+real `OPENAI_API_KEY` is stripped from the forwarded VM boot env, so the VM
+holds only the placeholder.
+
+## After-run handoff: pull request
+
+On transition into the Done state the orchestrator runs that state's typed
+`actions:` block — two records, `push_branch` then `create_pr_if_missing` —
+which push the per-issue branch and open a PR when a GitHub repo is configured:
+set `workspace.github_repo: <owner>/<repo>` in `WORKFLOW.md` (or export
+`SYMPHONY_REPO=<owner>/<repo>`, which overrides the file). Each action's
+`if: $repo` predicate short-circuits to a no-op in local-only mode (neither
+set), so the branch is simply left in the workspace until cleanup; pick the
+commits up with `git log agent/<id>` against your local clone. The PR is opened with `gh pr create --base
+$base_branch ...`, which requires `gh auth status` to be clean on the host; the
+token never enters the VM.
+
+The orchestrator stages the action context — `$branch`, `$base_branch`,
+`$pr_title` (already id-prefixed), and `$pr_body_file` (a temp file holding the
+current issue body) — before the block fires, so the PR description carries
+every `symphony.transition` notes block accumulated across the run, the full
+handoff thread from implementer through reviewer to approval. Per-action retry
+and snapshot plumbing replaces the old opaque shell-exit surface: on a
+rate-limit the `create_pr_if_missing` action surfaces "retrying in 60s" on the
+dashboard rather than failing silently.
+
+See `states.Done.actions` in [WORKFLOW.md](./WORKFLOW.md) for the canonical
+record pair and [WORKFLOW.template.md](./WORKFLOW.template.md) for the
+typed-action reference.
 
 ## Trust posture
 
-Sandbox isolation comes from running each agent inside a smolvm microVM.
-The VM has no network credentials (only the agent's API key is forwarded
-via `smolvm.forward_env`), no tracker filesystem access (the tracker is
-reached only through the MCP server), and stripped git remotes (set by
-`after_create`).
+Sandbox isolation comes from running each agent inside a Gondolin microVM.
+The VM has no OAuth refresh tokens or long-lived access tokens: for both
+`claude` and `codex`, the guest holds only a token-shaped placeholder and
+the host substitutes the real credential into the outbound request at
+Gondolin egress, so no real Anthropic or OpenAI credential is present in
+the VM. The VM has no tracker filesystem access (the tracker is reached
+only through the MCP server) and stripped git remotes (set by the
+orchestrator's `setupWorkspaceDir`).
 
-Within the ACP session, the orchestrator follows SPEC §10.5's "high-trust"
+Within the ACP session, the orchestrator follows SPEC §6.1's "high-trust"
 posture:
 
 - Command execution and file change approvals: auto-approve.
@@ -220,12 +313,16 @@ posture:
 
 ```bash
 npm run typecheck    # tsc --noEmit
-npm test             # 67 tests across workflow, tracker, prompt, workspace,
-                     # adapters, http, and mcp surfaces
+npm test             # 170 tests across workflow, tracker, prompt, workspace,
+                     # adapters, http, mcp, acp-bridge, orchestrator, run log,
+                     # runner state resolution, and tool-call summary surfaces
 npm run build        # tsc emit to dist/
 ```
 
-An end-to-end smoke run needs a real smolvm + VM image.
+An end-to-end smoke run needs the built agent image (see `images/agents/`).
+
+See [CHANGELOG.md](./CHANGELOG.md) for operator-visible changes between
+releases.
 
 ## License