smol-symphony 0.2.0 → 0.3.1

package/WORKFLOW.yaml

@@ -0,0 +1,487 @@
+# WORKFLOW.yaml — symphony dispatched against smol-symphony itself.
+#
+# Run with:
+#
+#   npx symphony WORKFLOW.yaml
+#
+# The per-issue workspace clones from this repo's `.git` directory and the agent
+# has no network credentials. The remote PR flow is configured in-file via
+# `workspace.github_repo` below (dizk/smol-symphony): on a terminal transition
+# the Done-state actions push the per-issue branch and open a PR. `gh` on the
+# host must be authenticated (`gh auth status` clean); the token never enters
+# the VM.
+#
+# For a fully local setup (branch left in the workspace until cleanup, nothing
+# pushed), set `workspace.github_repo: none`. The SYMPHONY_REPO env var still
+# overrides the in-file value when exported.
+#
+# Every section and option is documented in WORKFLOW.template.yaml.
+
+# Declared workflow states. Drives dispatch eligibility (role: active),
+# terminal cleanup (role: terminal), and the propose_issue landing directory
+# (role: holding). This map is the single source of truth — there are no
+# separate active/terminal lists to keep in sync.
+#
+# Per-state `adapter` / `model` / `max_turns` override the workflow-level
+# `acp.*` and `agent.max_turns` defaults at dispatch time, and `max_concurrent`
+# caps how many agents run at once in this state (the global
+# `agent.max_concurrent_agents` stays the cross-state host ceiling).
+# `allowed_transitions` narrows the targets the agent can pass to
+# `symphony.transition` while operating in this state (omit for "any declared
+# state is reachable").
+states:
+  Todo:
+    role: active
+    # Per-state prompt body. The shell loader wraps this file in the shared
+    # `prompt.preamble_file` + `prompt.footer_file` (below) and renders it for
+    # Todo dispatches — replacing the old inline `{% case issue.state %}` branch.
+    prompt_file: prompts/Todo.md
+    adapter: claude
+    # Opus 4.8, 1M-context variant. The plain `claude-opus-4-7` is the 200K
+    # variant — a γ-class refactor dispatch hit two mid-turn compactions before
+    # reaching the edit phase; `[1m]` gives ~30x headroom and removes the stall.
+    # The suffix is Claude Code's model-selection convention, forwarded to the
+    # adapter via ANTHROPIC_MODEL. Review stays on codex (cross-model review).
+    model: claude-opus-4-8[1m]
+    max_turns: 10
+    # Per-state concurrency cap (issue 137): at most one implementer agent at a
+    # time. Lives on the state now, symmetric with max_turns; the global
+    # `agent.max_concurrent_agents` below remains the cross-state host ceiling.
+    max_concurrent: 1
+  Review:
+    # Codex picks up the implementer's branch and approves or rejects. On
+    # approval it transitions the issue to Done with PR-body notes; on
+    # rejection it transitions back to Todo with rework instructions.
+    role: active
+    prompt_file: prompts/Review.md
+    adapter: codex
+    # codex-acp accepts the model via `-c model="..."` argv (TOML); see
+    # src/agent/adapters.ts. `gpt-5-codex` was historically rejected with the
+    # ChatGPT-account user, so leave `model` unset and let codex-acp pick its
+    # own default code-review model. Operators with an API-key Codex setup can
+    # pin a specific model here once that's known-good.
+    max_turns: 6
+    allowed_transitions: [Todo, Done]
+  Reflect:
+    # Sleep cycle (issue 122) as a recurring STATE that SPAWNS ephemeral
+    # reflection issues — not one immortal ticket. When the `spawn:` trigger below
+    # fires, the orchestrator MINTS a fresh issue into Reflect; it runs once and
+    # terminates in `Reflected` (a per-cycle audit trail), like every other
+    # ticket. eval_mode binds the read-only /symphony/issues (all state dirs,
+    # including the Done/*.md handoff transcripts) and /symphony/logs (per-issue
+    # JSONL run logs) mounts so the agent can mine finished work for *recurring*
+    # harness friction, distil lessons, and file improvement proposals via
+    # propose_issue (which land in Triage — the human gate). It reflects on *how
+    # symphony runs work* (the WORKFLOW.yaml `prompt_file` bodies under prompts/,
+    # per-state model/max_turns/effort/actions, the gondolin image config,
+    # acceptance criteria, timeouts), NOT the product code under review. See the
+    # Reflect prompt file (prompts/Reflect.md) for the read → distil → propose
+    # loop and the guardrails. Cadence: the operator / an external cron / a real
+    # dashboard "reflect now" button can mint a cycle by creating a Reflect issue,
+    # and the orchestrator auto-spawns on idle or after N terminal transitions
+    # (see this state's `spawn:` block below).
+    role: active
+    prompt_file: prompts/Reflect.md
+    adapter: claude
+    # 1M-context Opus: a reflection turn reads many Done/*.md transcripts plus
+    # the relevant logs/<id>.jsonl, so the large-context variant avoids mid-turn
+    # compaction (same rationale as the Todo state).
+    model: claude-opus-4-8[1m]
+    # Higher than Todo/Review: reading the history, distilling patterns, and
+    # filing one proposal per lesson takes more turns than a single edit/review.
+    max_turns: 20
+    # Bind the read-only /symphony/issues + /symphony/logs mounts for this state.
+    eval_mode: true
+    # The reflector may ONLY terminate in Reflected — it cannot route itself into
+    # Todo/Review/Done. A guardrail on this self-modifying loop; filing
+    # improvements happens through propose_issue (→ Triage), which is
+    # independent of allowed_transitions. Reflected is a DEDICATED terminal (NOT
+    # Done): Done carries the PR autopilot actions, and a minted reflection lands
+    # on an empty branch — terminating in Done would try to open a PR off it.
+    allowed_transitions: [Reflected]
+    # Recurring spawn trigger. This active state mints a FRESH ephemeral
+    # reflection issue into itself: `on_idle` when the orchestrator is idle and
+    # >=1 issue reached a terminal state since the last cycle, and `after_terminal`
+    # as a backstop once that many issues have reached a terminal state since the
+    # last cycle. The terminal-transition counter resets to 0 on a successful mint.
+    # `max_in_flight: 1` is load-bearing — it replaces the immortal ticket's
+    # built-in "one location = one reflection" mutex, so a busy stretch never mints
+    # a second cycle while one is still live. `title` stamps the mint time
+    # (`{{ stamp }}`); the generated body carries the trigger + counter provenance.
+    # GUARDRAILS (carried over from issue 122): spawning ONLY mints the reflection
+    # — the proposals it files still land in Triage and still require human
+    # approve/discard, so this does not bypass the human gate.
+    spawn:
+      on_idle: true
+      after_terminal: 10
+      title: "Reflection {{ stamp }}"
+      max_in_flight: 1
+  Done:
+    role: terminal
+    # PR autopilot routing (issue 38; moved onto the state in issue 139). Done
+    # is the merge state: a MERGEABLE Done-state PR has GitHub auto-merge armed
+    # with `squash` (matches the repo's `NN: title (#PR)` history); a
+    # CONFLICTING one is routed back to `on_conflict.route_to` (Todo) for the
+    # dispatched agent to rebase. The host-global on/off switch + poll TTL live
+    # in the top-level `pr:` block below; the merge/close/route targets are
+    # derived by scanning states for this `pr:` field (no named-string sibling
+    # block). While the engine is enabled, transitions into Done no longer fire
+    # the standard terminal workspace cleanup — the pr resource owns the
+    # workspace until its PR merges or closes.
+    pr:
+      auto_merge: squash
+      on_conflict:
+        route_to: Todo
+    # Issue 36 (reconciler v2 / typed action DAG): the legacy `after_run`
+    # shell that pushed the branch and opened a PR is replaced by two typed
+    # actions. The host pre-stages SYMPHONY_PR_TITLE / SYMPHONY_PR_BODY_FILE /
+    # SYMPHONY_BRANCH (the same values the old shell read); the action
+    # executor exposes them as $pr_title / $pr_body_file / $branch /
+    # $base_branch / $repo in the fixed template namespace
+    # (src/actions/types.ts → ActionContext). The `if: $repo` predicate
+    # matches the old `[ -n "${SYMPHONY_REPO:-}" ] || exit 0` short-circuit
+    # so the local-only mode is still a no-op. Per-action retry/snapshot
+    # plumbing replaces the opaque shell-exit-code surface; on rate-limit
+    # the create_pr_if_missing action shows "retrying in 60s" on the
+    # dashboard instead of a silent failure.
+    #
+    # on_error route (issue 235): a Done handoff that fails — `push_branch`
+    # server-side-declined (e.g. a `.github/workflows/` edit the Workflows:write-less
+    # PAT can't push), or `create_pr_if_missing` erroring after its retries — must
+    # NOT dead-end silently in terminal Done with no branch on the remote and no PR.
+    # Each action reroutes the issue OUT of Done into the `HandoffFailed` holding
+    # state (below) with the failure reason appended, so the stranded handoff is
+    # operator-visible on the dashboard instead of surfacing only as a log line. The
+    # per-issue workspace is retained (issue 234's handoff-pending marker) so the
+    # completed commit survives for a manual push. The default retry (count 3) still
+    # applies first — a transient `create_pr_if_missing` rate-limit recovers without
+    # routing; only a still-failing handoff reroutes.
+    actions:
+      - kind: push_branch
+        name: push-branch
+        remote: origin
+        ref: $branch
+        if: $repo
+        on_error:
+          then: { route_to: HandoffFailed }
+      - kind: create_pr_if_missing
+        name: open-pr
+        base: $base_branch
+        head: $branch
+        title_from: $pr_title
+        body_from: $pr_body_file
+        if: $repo
+        on_error:
+          then: { route_to: HandoffFailed }
+  Cancelled:
+    role: terminal
+    # Cancelled means the work was abandoned; no patch, no PR. The workspace is
+    # cleaned up after the run unwinds and the commits are discarded with it.
+    # PR autopilot close state (issue 139): when the engine is enabled, an open
+    # PR for a Cancelled issue is closed without merge and its remote branch is
+    # best-effort-deleted. Unlike the merge state, the close path needs no
+    # workspace, so standard terminal cleanup still runs on transition in.
+    pr:
+      close: true
+  Reflected:
+    # Dedicated terminal for a completed sleep-cycle reflection (replaces the old
+    # Dormant parking state). Each minted reflection issue lands here after filing
+    # its proposals, so the column is a browsable per-cycle audit trail — one issue
+    # per run — instead of one ever-growing immortal ticket. Deliberately carries
+    # NO `pr:` and NO `actions:`: a reflection runs on an empty branch (it only
+    # files propose_issue → Triage), so the Done-state PR autopilot must NOT fire
+    # — that's the whole reason this is a separate terminal from Done. Standard
+    # terminal workspace cleanup runs on transition in.
+    role: terminal
+  Triage:
+    # Landing directory for `symphony.propose_issue`. Never dispatched; the
+    # operator approves or discards from the dashboard. Declared FIRST among
+    # holding states so it stays the `propose_issue` landing + triage target
+    # (both resolve the first declared holding state).
+    role: holding
+  HandoffFailed:
+    # Landing state for a Done handoff that FAILED (issue 235). The agent already
+    # transitioned the issue to Done, but the Done `actions:` handoff (push_branch /
+    # create_pr_if_missing) couldn't land — most commonly a `.github/workflows/`
+    # edit the shared fine-grained PAT can't push (Workflows:write is intentionally
+    # withheld; that diff is a deliberate manual SSH-push step). Rather than dead-end
+    # invisibly in terminal Done with no branch on the remote and no PR, the failing
+    # action's `on_error.then.route_to` (states.Done.actions, above) reroutes the
+    # issue here with the failure reason appended to its body. Holding → never
+    # dispatched: it parks for an operator to push the `agent/<id>` branch by hand
+    # (the per-issue workspace is RETAINED by issue 234's handoff-pending marker, so
+    # the completed commit survives) and then move the issue back to Done, or to
+    # Cancelled. Declared AFTER Triage so Triage stays the `propose_issue` landing
+    # (the first declared holding state).
+    role: holding
+
+# Shared prompt-assembly files (per-state prompt split). Each active state above
+# names its own `prompt_file`; the loader wraps that body in this shared header
+# and footer and renders the result for that state — so the config above reads as
+# the shape of the workflow, and each prompt is edited in its own file under
+# `prompts/` instead of one 800-line `{% case issue.state %}`. Both paths are
+# resolved relative to this file. There is no inline prompt body anymore —
+# workflow files are pure YAML. A dispatched state that declares no `prompt_file`
+# (or omitting this block) falls back to a generic built-in prompt
+# ("You are working on an issue."), so every active state should name one.
+prompt:
+  preamble_file: prompts/_preamble.md
+  footer_file: prompts/_footer.md
+
+tracker:
+  kind: local
+  # Operator-scoped tracker root (outside the repo). State transitions and
+  # propose_issue writes don't dirty the codebase's git status. Symphony
+  # auto-mkdirs every declared state directory under this root on startup.
+  root: ~/.symphony/trackers/smol-symphony
+
+# PR autopilot engine toggle (issue 38, simplified by issue 101; routing moved
+# onto states in issue 139). This is the slim host-global half only — the
+# on/off switch and the per-PR `gh pr view` cache TTL. The merge/close/route
+# targets and the auto-merge strategy now live ON the states they describe:
+# `states.Done.pr` (merge state — auto_merge + on_conflict.route_to) and
+# `states.Cancelled.pr` (close state — close: true), above. The reconciler
+# derives those by scanning states; there is no named-string sibling block.
+#
+# Enabled 2026-05-25 so MERGEABLE Done-state PRs have GitHub auto-merge armed
+# and CONFLICTING ones are routed back to Todo for the dispatched agent to
+# rebase (the host runs `git fetch origin <base>` before each dispatch so
+# `origin/<base>` is current, and the Todo prompt's first step is
+# `git rebase origin/<base>`). There is no autopilot-side rebase machinery and
+# no consecutive-failure circuit breaker.
+#
+# PREREQUISITE: `gh pr merge --auto` requires at least one branch-protection
+# rule on `main`, or arming auto-merge errors. Ensure one exists in the repo's
+# GitHub settings. To disable, set `enabled: false` (the resource is then never
+# constructed and Done-state behavior reverts to the actions-block PR-create +
+# operator merge).
+pr:
+  enabled: true
+  poll_interval_ms: 30000
+
+polling:
+  interval_ms: 5000
+
+# The canonical clone + base-branch checkout + `agent/<id>` branch cut +
+# origin/identity setup is owned by the orchestrator's TypeScript
+# `setupWorkspaceDir` action (issue 34 / reconciler stage 3) — there is no
+# shell `hooks:` surface. The per-issue workspace arrives at the dispatched
+# agent with:
+#
+#   • a hardlinked `git clone --local` of the source repo on the base branch
+#     (`workspace.base_branch`, or the SYMPHONY_BASE_BRANCH env override,
+#     default `main`) at the source repo's current local base SHA
+#   • all network remotes stripped (in-VM `git push`/`git fetch` fail closed)
+#   • when `workspace.github_repo` (or the SYMPHONY_REPO env override) is set:
+#     `origin` restored to the canonical HTTPS URL so the host's Done-state
+#     `push_branch` action can push (`gh auth setup-git` runs best-effort on the
+#     host so the push has credentials; the token never enters the VM)
+#   • `user.name = symphony-agent` / `user.email = agent@symphony.local`
+#   • `agent/<id>` checked out
+#
+# The source repo's local `<base>` is the single source of truth for the
+# workspace's base ref. To pick up a new base, update the source repo
+# (`git pull` / `git fetch && git checkout <base>`) before the next dispatch;
+# symphony does not implicitly fetch from `origin/<base>` at setup time.
+#
+# Need extra per-VM tooling on top of that? Bake it into the agent image
+# (`images/agents/`), or run arbitrary guest commands from a state's `actions:`
+# via `run_in_vm`. The post-attempt push + PR-create handoff is the Done
+# state's `actions:` block above.
+workspace:
+  # Explicit in-repo workspace root (the new unset default is
+  # ~/.symphony/workspaces/<project>). Kept explicit here so in-flight per-issue
+  # working trees aren't relocated mid-burndown; drop this line to inherit home.
+  root: ./.symphony/workspaces
+  # PR/push target for the dogfood (symphony-on-symphony) setup: the Done-state
+  # actions push the per-issue branch + open a PR against this repo. Set to
+  # `none` for local-only (branch left in the workspace). The SYMPHONY_REPO env
+  # var still overrides this if exported.
+  github_repo: dizk/smol-symphony
+  # Branch the per-issue workspace clones from + targets as the PR base. The
+  # SYMPHONY_BASE_BRANCH env var still overrides this if exported.
+  base_branch: main
+
+# Per-issue JSONL run logs plus an orchestrator-side `symphony.log` mirror.
+# One JSONL file per issue, appended across attempts and process restarts;
+# captures every ACP JSON-RPC frame to/from the VM, raw adapter stderr,
+# typed-action output, and orchestrator lifecycle events — intended for
+# later evaluation by another agent. The sibling `symphony.log` captures the
+# orchestrator's structured log (dispatch, actions, reconciler, shutdown) in the
+# same `key=value` format so a post-hoc review has both surfaces in one
+# directory. While the file sink is active the console shows only the startup
+# banner; `tail -f symphony.log` follows the detail, and `--verbose` mirrors it
+# back to the console. See WORKFLOW.template.yaml for the full schema.
+logs:
+  # Operator-scoped run-log root (outside the repo), matching the home default
+  # (~/.symphony/logs/<project>) and the operator-scoped tracker.root above.
+  # Durable, expensive-to-rebuild run logs survive a delete / re-clone of the repo
+  # instead of living inside the working tree. (Leaving this unset would inherit
+  # the same path, since github_repo derives <project> = smol-symphony.)
+  root: ~/.symphony/logs/smol-symphony
+
+agent:
+  # SERIALIZED to 1 (2026-05-27) to stop the FC/IS burn-down conflict storm:
+  # every burn-down PR edits the same policy files (package.json --max-warnings
+  # ratchet, .dependency-cruiser.cjs, eslint.config.js), so any two in flight
+  # conflict by construction. Serial dispatch makes each PR rebase on the prior
+  # merge. Revert to 2 once the arch-burndown queue drains.
+  max_concurrent_agents: 1
+  max_turns: 6
+  max_retry_backoff_ms: 120000
+
+acp:
+  # Selecting "claude" is enough: symphony probes ~/.claude/.credentials.json
+  # on the host at startup and auto-generates a launch command for the in-VM
+  # agent. There is no `command` escape hatch under the ACP WebSocket transport —
+  # the launch shape is fixed; fork scripts/vm-agent.mjs if you need to customize
+  # what the agent spawns.
+  adapter: claude
+  # Credentials never enter the VM (issue 113; codex generalized in 116). The
+  # guest holds only a token-shaped placeholder; the host substitutes the real
+  # upstream credential into the outbound request at Gondolin egress (TLS-MITM):
+  # for claude, the Anthropic OAuth access token; for codex (the Review state's
+  # adapter), the OpenAI credential read from ~/.codex/auth.json (access token or
+  # OPENAI_API_KEY, never the refresh token). Every credential-bearing var is
+  # stripped from the forwarded VM boot env, so no real credential lands in the VM.
+  # Reasoning effort forwarded to claude-agent-acp via a staged settings.json
+  # (`{"effortLevel": "xhigh"}`) copied into /root/.claude/settings.json before the
+  # adapter starts. xhigh is the second-highest tier under Opus 4.7 (max is the top
+  # but is meaningfully slower); operators on a Haiku-backed model must drop this
+  # because Haiku rejects xhigh at adapter startup. Valid set is `low|medium|high|xhigh|max`,
+  # model-gated by claude-agent-acp's `supportedEffortLevels`.
+  effort: xhigh
+  shell: bash
+  # Hard cap on a single session/prompt regardless of activity. Raised from 30min to
+  # 60min (the code default) because a heavy refactor turn at effort=xhigh can run a
+  # single uninterrupted turn past 30min — issue 103's healthy attempt was killed
+  # mid-edit at the old 1800000 cap with turns_completed:0. Distinct from
+  # stall_timeout_ms below (which only trips on NO activity).
+  prompt_timeout_ms: 3600000
+  read_timeout_ms: 30000
+  # ACP rides the unified HTTP server: the in-VM agent (the injected launcher at
+  # `/opt/symphony/vm-agent.mjs` — see the BYO-image contract under `gondolin:`) dials
+  # back the `/acp` WebSocket through the SAME `tcp.hosts` tunnel MCP uses
+  # (`ws://symphony-mcp:7001/acp`) and authenticates with a per-dispatch bearer sent as the
+  # first WebSocket message. No separate ACP listener / bind port — the raw-TCP bridge is
+  # retired. `connect_timeout_ms` bounds how long to wait for that dial-back (default 30000).
+  # connect_timeout_ms: 30000
+  # ACP-over-WebSocket liveness heartbeat. Both ends of the `/acp` socket send an
+  # application-level ping every `heartbeat_interval_ms` and tear the socket down (a typed
+  # `transport_error`, which feeds the consecutive circuit breaker — NOT a refusal) if no
+  # inbound traffic arrives for `heartbeat_timeout_ms`. This surfaces a half-open socket in
+  # seconds instead of waiting for `prompt_timeout_ms` or the stall reaper. The heartbeat is
+  # INDEPENDENT of ACP frames, so a long silent tool call stays alive; the conservative
+  # defaults (interval 15000 / timeout 45000 ≈ 3 intervals) keep a slow KVM host from
+  # false-positiving a live-but-quiet peer mid-turn. Raise the timeout if a heavily loaded
+  # host legitimately pauses the guest event loop past 45s.
+  # heartbeat_interval_ms: 15000
+  # heartbeat_timeout_ms: 45000
+  # Time between any ACP event from the adapter before symphony kills the attempt as stalled.
+  # Raised from the 5-minute default because Opus 4.7 at effort=xhigh can take many minutes to
+  # produce its first thought chunk on a heavy prompt. If a real wedge happens, attempts will
+  # die at this longer threshold; if the agent is just thinking, we let it finish.
+  stall_timeout_ms: 1800000
+
+gondolin:
+  # Per-issue microVM (Gondolin substrate). `image` is the agent rootfs the VM
+  # boots. The value is a Gondolin image selector: a content-addressed build id, a
+  # `name:tag` ref like `symphony-agents:latest`, or a path to an exported asset
+  # directory. Build the reference image with `npm run build:image` (see images/agents/).
+  #
+  # IMAGE CONTRACT (issue 209 — mise-only base): the image ships ONLY the `mise`
+  # binary (+ glibc essentials). node + the agent CLIs are NOT baked — they come from a
+  # mise SYSTEM config symphony STAGES at /etc/mise/config.toml at dispatch
+  # (assets/symphony-mise.system.toml), installed via `mise install` into a
+  # warm-cached data dir (see `mise:` below). The in-VM launcher (`scripts/vm-agent.mjs`)
+  # is likewise INJECTED at dispatch (read off the host's own disk, SHA-256 logged), so
+  # neither a CLI bump nor a launcher/transport change needs an image rebuild + repin.
+  # A pre-launch probe fails fast with a precise error (not an opaque ENOENT) if unmet.
+  #
+  # The image MUST provide ONLY:
+  #   1. the `mise` binary on PATH (node + the agent CLIs are mise-installed; the agent
+  #      runtime node is resolved system-scoped via `mise which node`, kept ≥ 21 for the
+  #      launcher's global WebSocket). mise provisioning is the ONLY toolchain path
+  #      (issue 233) — there is no opt-out, so the base image need not bake node;
+  #   2. /bin/sh + base64 + mkdir/chmod (coreutils — present in any Debian/Alpine base)
+  #      for the staging write;
+  #   3. a writable rootfs overlay (Gondolin default `cow`; a deliberately
+  #      readonly-manifest image transparently falls back to a /tmp tmpfs path);
+  #   4. distro CA files left intact (Gondolin injects its MITM CA at boot — the image
+  #      must not shadow /etc/ssl).
+  # Symphony injects everything else: the mise SYSTEM config, the launcher, the
+  # bind-mount-trust gitconfig, the fake-cred placeholder files, and all SYMPHONY_* /
+  # PATH / GIT_CONFIG_GLOBAL launch env.
+  #
+  # The agent-CLI pins live in assets/symphony-mise.system.toml (claude-code,
+  # codex, claude-agent-acp, codex-acp) — bump THERE + restart, no rebuild.
+  # mise-only base (issue 209). #2 (PR #211) installs the agent toolchain onto the guest
+  # ROOTFS at dispatch — sandboxfs silently drops chmod, so an executable can't be born on
+  # the bind mount; the persistent download cache stays on the bind mount (data only).
+  # `rootfs_size` grows the ephemeral install fs past the ~593 MB default. Bump an agent CLI
+  # in assets/symphony-mise.system.toml + restart — no image rebuild (only a base/mise bump needs
+  # `npm run build:image` + a repin here). NB the codex reviewer egress needed the
+  # chatgpt-backend route swap scoped to the platform host (credential-hooks.ts) to reach
+  # npm/nodejs — see docs/research/codex-route-hook-host-rewrite-rca.md.
+  rootfs_size: 3G
+  image: e8a1562b-ea57-54c6-9f0a-ea9aa6f1d40d
+  cpus: 2
+  mem_mib: 4096
+  # Absolute guest path the injected launcher is staged + exec'd at. Default
+  # `/opt/symphony/vm-agent.mjs` (the historical bake path). The same value is the write
+  # target AND the exec arg, so they can never drift; a readonly-rootfs image falls back
+  # to a /tmp path automatically. Override only for an unusual image layout.
+  # guest_agent_path: /opt/symphony/vm-agent.mjs
+  # The node binary the launcher is exec'd with. Default bare `node` (the pre-launch
+  # probe resolves it to an absolute path so the exec is PATH-independent). Set this for
+  # an image that ships node under a non-PATH name (e.g. /opt/node/bin/node).
+  # node_bin: node
+  # No runtime bind-mounts. The launcher is INJECTED (staged per-dispatch), not mounted,
+  # so it needs no `volumes` entry. Keeping `volumes` empty leaves room for an eval_mode
+  # state's two read-only mounts (/symphony/issues + /symphony/logs) on top of the
+  # auto-mounted workspace. Credentials never mount: the host substitutes the real token
+  # at Gondolin egress; the tracker is reached via the symphony MCP server (or the
+  # eval_mode mount).
+  volumes: []
+  # forward_env is a generic passthrough into the VM boot env, but the runner
+  # strips EVERY credential-bearing var before boot (the guest holds only a
+  # placeholder Gondolin substitutes at egress) — so listing OPENAI_API_KEY here
+  # does NOT plant the real key in a VM.
+  forward_env:
+    - OPENAI_API_KEY
+    - ANTHROPIC_API_KEY
+
+egress:
+  # General dev-tooling firewall for the in-VM agent. Gondolin denies guest egress
+  # by default; the agent can always reach its own inference host (handled by the
+  # credential layer), and these hosts are additionally opened so gates can run
+  # (`npm install`, git-based deps, release binaries). SECURITY: nothing here ever
+  # gets a real token substituted — listing a host grants plain network egress
+  # only. The real upstream token is substituted solely on each adapter's inference
+  # host (see src/agent/credential-secrets.ts).
+  allowed_hosts:
+    - nodejs.org                     # mise node prebuilts (issue 209)
+    - registry.npmjs.org             # npm install + mise npm: backend (the agent CLIs)
+    - mise.jdx.dev                   # mise registry redirect (issue 209)
+    - mise-versions.jdx.dev          # mise precompiled tool version lists (node@N, etc.; issue 223)
+    - github.com                     # git-based deps / release pages
+    - codeload.github.com            # GitHub tarball fetch
+    - objects.githubusercontent.com  # release-binary downloads
+
+server:
+  # Pinned to 8787 for stable local/tailscale access (bookmarks, forwards,
+  # scripts). #160 made the port ephemeral by default — so two instances never
+  # collide on the HTTP port — and banners the bound port. This project runs a
+  # single instance, so a fixed, predictable port is preferable. Omit `port:`
+  # (or pass `--port N`) to return to ephemeral. Takes effect on next restart.
+  port: 8787
+  # Bound to all interfaces because access is gated by tailscale, not by the
+  # HTTP server itself. The endpoint has no auth; only expose it inside a
+  # trusted network boundary.
+  host: 0.0.0.0
+
+mcp:
+  # Gondolin maps a synthetic guest host to the host's loopback (`tcp.hosts`), so
+  # 127.0.0.1 from inside the VM hits the host's listener. Override only if
+  # your VMM has a different host alias.
+  host: 127.0.0.1

package/assets/skills/symphony-issues/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: symphony-issues
+description: Author well-formed issues for a symphony tracker, and decompose a large task into a blocked_by DAG of small one-PR issues. Trigger when asked to "file a symphony issue", "open/create a tracker issue", "break this task into issues", or "decompose into a DAG of issues".
+---
+
+# Filing symphony issues
+
+This project is driven by **symphony**: a coding agent picks up one tracker
+issue, works it on a per-issue branch, and opens exactly one PR. **The issue
+body IS the dispatched agent's prompt** — write every issue for that reader.
+
+Anything project-specific (the HTTP port, the tracker root, the state names)
+lives in this repo's `WORKFLOW.yaml`. Read it from there; this skill never
+hardcodes it.
+
+## The four-section issue body
+
+Every issue body uses the same four sections, in this order:
+
+- **Problem** — what's wrong and why now. The motivation the agent needs to
+  make the judgement calls the Change leaves open.
+- **Change** — the concrete edits. Name file paths and line ranges where you
+  know them; describe the *shape* of the change, not just the goal.
+- **allowed_paths** — the workspace scope the dispatched agent is permitted to
+  touch, one path per line.
+- **Acceptance** — the checks that must pass before the agent transitions the
+  issue to a terminal state. Usually the build/test/lint gate plus the
+  issue-specific assertions that prove this change works.
+
+Why this shape, plainly: **the body is the prompt, `allowed_paths` is the
+leash, and Acceptance is the definition of done.** A vague body yields a vague
+PR; a missing `allowed_paths` lets the agent wander into unrelated files; a
+missing Acceptance leaves "done" undefined and the reviewer with nothing to
+check against.
+
+## How to file
+
+Find `server.port` in this repo's `WORKFLOW.yaml`, then POST JSON to the running
+symphony HTTP server:
+
+```bash
+curl -s -X POST http://127.0.0.1:<server.port>/api/v1/issues \
+  -H "content-type: application/json" \
+  --data-binary @/tmp/issue.json
+```
+
+Body shape:
+
+```json
+{
+  "title": "required, non-empty",
+  "state": "Todo",
+  "identifier": "108",
+  "description": "markdown body — the four sections above, below the front matter",
+  "priority": 2,
+  "labels": ["refactor"],
+  "blocked_by": ["107"]
+}
+```
+
+- `title` is the only required field.
+- `state` is optional — it defaults to the **first active state** declared in
+  `WORKFLOW.yaml`. Any declared **non-terminal** state is a valid explicit target:
+  both active states and holding states (e.g. a Triage holding state) can be
+  created into. Only **terminal** states are closed to direct creation.
+- `identifier` is optional — the server allocates the next free integer.
+- `priority`, `labels`, and `blocked_by` are optional.
+- The server stamps `created_at` / `updated_at` and returns `201` with
+  `{ path, identifier, state }`. Duplicate ids / bad states come back `4xx`.
+
+**Disk fallback** (server not running): hand-write a file at
+`<tracker.root>/<State>/<n>.md` — read `tracker.root` and the state names from
+your `WORKFLOW.yaml` — with the same YAML front matter (`title`, optional
+`priority` / `labels` / `blocked_by`) and the four-section body below it. The
+**disk is canonical for reading**; the API is just the filing front door, so
+look at neighbouring files under the tracker root for the exact front-matter
+shape this project uses.
+
+## Decomposing a large task into a `blocked_by` DAG
+
+This is the high-leverage move, and the reason to reach for this skill. Don't
+file one giant issue — model the task as a **dependency graph of small issues,
+one PR per node.**
+
+- `blocked_by: ["<id>", …]` makes an issue **ineligible to dispatch** until
+  every blocker has reached a **terminal** tracker state.
+- **Serialize work that shares a file or artifact.** Two agents editing the
+  same file in parallel collide and invalidate each other's branch — chain
+  those nodes `A ← B ← C` (B `blocked_by` A, C `blocked_by` B) so they land in
+  order.
+- **Parallelize only genuinely independent work** (disjoint files / artifacts).
+  File those with no `blocked_by` so they fan out across the concurrency cap and
+  run at once.
+
+### Two gotchas to design around
+
+1. **Terminal ≠ merged.** `blocked_by` unblocks the moment a blocker hits a
+   *terminal tracker state*, which can **precede the blocker's PR actually
+   merging**. A downstream node may therefore dispatch off a base branch that
+   still lacks the upstream change. Fast-forward / rebase the base between
+   merges so each node starts from its blockers' landed code.
+2. **Keep downstream specs at intent altitude.** Don't pin line numbers in a
+   node that won't dispatch until several upstream PRs have landed — they'll
+   have drifted by then. Say *"locate by name"* or *"run the relevant check for
+   the current count"* instead of `src/foo.ts:412`.
+
+### Worked example: rename an API across many call sites
+
+```
+discover  (enumerate every call site)
+   ├── transform-call-site-A ─┐
+   ├── transform-call-site-B ─┤  (parallel — disjoint files)
+   └── transform-call-site-C ─┘
+                               └── verify  (typecheck + test the whole tree)
+```
+
+1. **`discover`** — one issue that enumerates every call site and lists them in
+   its handoff notes. No `blocked_by` — it dispatches immediately.
+2. **N transform issues** — one per call site, each `blocked_by` the discover
+   issue and each touching **disjoint files**, so they run in parallel:
+
+   ```json
+   { "title": "Rename API in module A",
+     "blocked_by": ["<discover-id>"], "labels": ["refactor"] }
+   ```
+3. **`verify`** — one issue blocked on *all* the transforms, asserting the whole
+   tree still typechecks and tests after every call site moved:
+
+   ```json
+   { "title": "Verify API rename across the tree",
+     "blocked_by": ["<A-id>", "<B-id>", "<C-id>"] }
+   ```
+
+The transforms fan out once `discover` is terminal; `verify` waits for all
+three. Keep `verify`'s spec at intent altitude (gotcha 2) — it dispatches last,
+after the others have drifted the line numbers it would otherwise have pinned.