smol-symphony 0.1.0 → 0.3.0

package/WORKFLOW.template.yaml

@@ -0,0 +1,1100 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# WORKFLOW.template.yaml — annotated reference for symphony workflow files.
+#
+# A workflow file is pure YAML config. The orchestrator parses it into
+# ServiceConfig (see src/types/config.ts) and, per dispatched issue, renders the
+# active state's prompt — its `prompt_file` wrapped in the shared
+# `prompt.preamble_file` / `prompt.footer_file` — with the Liquid context
+# `{ issue, attempt }`.
+#
+# This document lists every supported section, every option within it, the
+# parser default, and a small example. For a complete worked example, see
+# WORKFLOW.yaml in this repo. For the smallest thing that runs — what
+# `npx smol-symphony` scaffolds by default — see WORKFLOW.minimal.yaml; reach for
+# the options below only when you want a power feature it omits.
+#
+# Notation:
+#   • Required keys are marked (required).
+#   • Types: `string`, `int`, `bool`, `path` (string resolved relative to the
+#     workflow file's directory unless absolute), `string[]`, `map<K, V>`.
+#   • Defaults are what the parser writes when the key is absent.
+# ─────────────────────────────────────────────────────────────────────────────
+# ─────────────────────────────────────────────────────────────────────────────
+# tracker — where issues come from.
+# ─────────────────────────────────────────────────────────────────────────────
+tracker:
+  # kind (required): currently the only supported value is 'local' (markdown
+  # files under `root`, one per issue, organized by state subdirectory).
+  kind: local
+
+  # root (path): directory containing `<state>/<id>.md` files. Optional.
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/trackers/<project> — durable tracker state lives
+  # OUTSIDE the repo working tree by default, so it survives a delete / re-clone
+  # of the repo. <project> is the `workspace.github_repo` slug's repo name
+  # (owner/repo → repo), falling back to this workflow file's directory basename;
+  # sanitized so two different projects on one machine never collide.
+  # root: ~/.symphony/trackers/my-project
+
+# ─────────────────────────────────────────────────────────────────────────────
+# states — per-state configuration map. REQUIRED. Every workflow must declare
+# at least one `active`, one `terminal`, and one `holding` state; a workflow
+# missing the `states:` block (or missing any of those roles) is rejected at
+# parse time. This map is the only place state names and roles are configured;
+# there are no separate active/terminal lists to keep in sync.
+#
+# Keys are state names; values are config objects with these fields:
+#   role (required, enum):
+#     active   — orchestrator dispatches issues in this state.
+#     terminal — orchestrator treats issues in this state as complete; the
+#                workspace is removed after the run unwinds.
+#     holding  — directory exists on disk, but the orchestrator never
+#                dispatches issues from it. Triage is the canonical example
+#                and the landing directory for `symphony.propose_issue`.
+#   adapter   (string, optional): override the workflow-level `acp.adapter` for
+#             agents dispatched in this state. Must be a known profile (claude,
+#             codex). Both use host-side credential substitution at Gondolin
+#             egress and are startup-probed so a missing credential fails fast.
+#             claude has a single host credential file
+#             (~/.claude/.credentials.json) that is probed for readability; codex
+#             passes when either ~/.codex/auth.json holds a token (ChatGPT-OAuth
+#             tokens.access_token or a top-level OPENAI_API_KEY) or the host
+#             OPENAI_API_KEY env var is set.
+#   prompt_file (path): this state's prompt template, in its own file. The shell
+#             loader reads it and assembles `prompt.preamble_file` + this file +
+#             `prompt.footer_file` (see the top-level `prompt:` block below) into
+#             the template rendered for issues in this state. Every active
+#             (dispatched) state should declare one; a state without `prompt_file`
+#             renders the generic fallback prompt. Resolved relative to the
+#             workflow file. A missing/unparseable file fails at startup (and
+#             `symphony doctor`), not mid-dispatch.
+#   model     (string, optional): override `acp.model` for this state.
+#             Blank or whitespace-only values normalize to "use the adapter
+#             default" (same as the workflow-level acp.model semantics).
+#   effort    (string, optional): override `acp.effort` for this state. Same
+#             undefined-vs-null semantics as `model`: omit to inherit
+#             `acp.effort`; blank/whitespace normalizes to null ("use the
+#             adapter default for this state"). Valid values are adapter- and
+#             model-specific (see `acp.effort`).
+#   max_turns (int, optional): override `agent.max_turns` for this state.
+#   max_concurrent (int, optional): cap on agents the orchestrator runs
+#             simultaneously for issues in THIS state. Symmetric with
+#             `max_turns` — concurrency and turn budget both live on the state.
+#             Omit for "no per-state cap; only the global
+#             `agent.max_concurrent_agents` ceiling applies". The sum of every
+#             state's `max_concurrent` must not exceed that global ceiling
+#             (validated at startup).
+#   allowed_transitions (string[]|null, optional): when set, restricts which
+#             states agents in this state may transition to via the MCP
+#             `transition` tool. Each entry must be a declared state. Omit (or
+#             explicitly set to null) for "any declared state is reachable".
+#             An empty list (`allowed_transitions: []`) means "no transitions
+#             allowed out of this state" — the agent's `transition` calls will
+#             always be rejected with `transition_not_allowed`. Useful for
+#             review-style states that should pause until a human re-routes.
+#   eval_mode (bool, optional): when true, the runner adds two extra read-only
+#             bind mounts to every per-issue VM dispatched in this state so an
+#             in-VM agent can inspect symphony's own state for evaluation /
+#             debugging:
+#               • `tracker.root` → `/symphony/issues` (every issue file across
+#                 every state directory)
+#               • `logs.root`    → `/symphony/logs`   (per-issue JSONL run-log
+#                 transcripts captured by RunLog — ACP frames, stderr,
+#                 typed-action output, system events — plus the compact
+#                 `<key>.summary.json` outcome records the reflector reads; see
+#                 the `logs:` block below)
+#             Either mount is skipped silently if the corresponding root is
+#             unset. Each VFS mount has a cost, so this is opt-in per state rather
+#             than a workflow-wide default — flip it on for a dedicated eval
+#             state, not for the routine implement/review flow. Default: false.
+#             The canonical consumer is the "sleep cycle" reflection pattern —
+#             see the SLEEP CYCLE section below the states block.
+#   actions   (list, optional): typed action DAG (issue 36, reconciler v2).
+#             The single glue mechanism attached to a state — there is no shell
+#             `hooks:` surface. When set on a `terminal` state, this list runs
+#             on transition INTO the state (the canonical Done-state pair is
+#             push_branch + create_pr_if_missing). For arbitrary in-sandbox
+#             commands use a `run_in_vm` action; per-VM tooling belongs in the
+#             agent image (`images/agents/`); first-creation workspace setup is
+#             owned by the orchestrator's `setupWorkspaceDir`.
+#             Each entry is a closed-kind record:
+#
+#                 - kind: push_branch
+#                   remote: origin
+#                   ref: $branch
+#                   if: $repo
+#
+#             Recognized kinds:
+#               push_branch          { remote, ref }
+#               create_pr_if_missing { base, head, title_from, body_from }
+#               run_in_vm            { name, cmd: [...], env?, timeout? }
+#
+#             Templating: `$varname` references the fixed ActionContext
+#             namespace ($identifier, $workspace, $branch, $base_branch,
+#             $issue_title, $issue_body, $repo, $pr_title, $pr_body_file).
+#             Unknown $vars throw at run-time (no silent "" expansion).
+#
+#             Conditional: optional `if:` field supports three predicates
+#               - `if: $repo`                       (env-var-truthy)
+#               - `if: { branch_exists: <ref> }`    (workspace branch)
+#               - `if: { file_present: <path> }`    (workspace file)
+#
+#             Retry: optional `on_error.retry: { count, backoff_ms }`. Default
+#             policy is 3 retries with exponential backoff starting at 1s,
+#             then abort. `on_error.then: { route_to: <state> }` reroutes the
+#             issue OUT of the action's state into <state> (which must be
+#             declared — validated at parse time) instead of aborting; the
+#             runner moves the tracker file there with the failure reason
+#             appended as notes. The canonical use is the Done handoff (issue
+#             235): a `push_branch` / `create_pr_if_missing` that fails after
+#             its retries reroutes into a `HandoffFailed` holding state so a
+#             stranded handoff (no branch on the remote, no PR) is operator-
+#             visible instead of dead-ending silently in terminal Done. A
+#             rerouted handoff also RETAINS the per-issue workspace (the
+#             handoff-pending marker, issue 234) so the unpushed commit
+#             survives for a manual push. A `.github/workflows/`-touching push
+#             is the common trigger: the shared fine-grained PAT is not granted
+#             Workflows:write, so GitHub server-side-declines it and the routed
+#             reason is rewritten to an actionable "manual SSH push required".
+#
+#             run_in_vm runs uncached: every dispatch into the state re-execs
+#             the command on the live per-issue VM. `name` labels its run-log
+#             output (no caching layer; the action is the plain escape hatch).
+#   pr        (map, optional): PR autopilot routing for this state (issue 139).
+#             Valid only on a `terminal` state, and only acts when the
+#             top-level `pr:` engine block (below) has `enabled: true`. This is
+#             where the routing the engine used to name by string now lives —
+#             on the state it describes. Two shapes:
+#               • Merge state:  pr: { auto_merge: squash|merge|rebase,
+#                                     on_conflict: { route_to: <active state> } }
+#                 A MERGEABLE PR for an issue in this state has GitHub
+#                 auto-merge armed with `auto_merge`; a CONFLICTING one is
+#                 routed back to `on_conflict.route_to` (defaults to the first
+#                 declared active state when omitted) for the dispatched agent
+#                 to rebase. While the engine is enabled, transitions INTO this
+#                 state do not fire the standard terminal workspace cleanup —
+#                 the pr resource owns the workspace until the PR merges/closes.
+#               • Close state:  pr: { close: true }
+#                 An open PR for an issue in this state is closed without merge
+#                 and its remote branch is best-effort-deleted. Standard
+#                 terminal cleanup still runs (the close path needs no workspace).
+#             The merge/close/route targets are DERIVED by scanning states for
+#             this field — there is no named-string sibling block. At most one
+#             terminal state may declare `auto_merge`, and at most one may
+#             declare `close`; an `on_conflict.route_to` naming an undeclared
+#             state is rejected at parse time.
+#   spawn     (map, optional): recurring-spawn trigger for this state (the sleep
+#             cycle as a recurring STATE). Valid only on an `active` state. When
+#             a trigger fires the orchestrator MINTS a FRESH ephemeral issue into
+#             this state (it runs once and terminates in a dedicated terminal),
+#             instead of re-arming one immortal parked ticket. Fields:
+#               • on_idle (bool): spawn when the orchestrator is idle AND >=1
+#                 issue reached a terminal state since the last cycle (the ">=1
+#                 since last cycle" gate is load-bearing — without it an idle
+#                 orchestrator re-spawns in a tight loop with nothing new to
+#                 mine). Default false.
+#               • after_terminal (int): a backstop for busy stretches that never
+#                 go idle — spawn once this many issues have reached a terminal
+#                 state (Done/Cancelled/the spawn's terminal) since the last
+#                 cycle. 0 disables the count trigger. Default 0.
+#               • title (string): title template for the minted issue;
+#                 `{{ stamp }}` → the mint timestamp (e.g. "2026-06-03 12:00").
+#                 Default "Reflection {{ stamp }}".
+#               • body (string, optional): lead-in line for the GENERATED
+#                 provenance body (the trigger + counter + timestamp the static
+#                 prompt can't know are always appended). Default: a generic
+#                 "Auto-spawned reflection cycle." lead-in.
+#               • max_in_flight (int): never mint a second issue while this many
+#                 are already live in the spawn state. Load-bearing — it replaces
+#                 the immortal ticket's built-in "one location = one reflection"
+#                 mutex, so a busy-stretch after_terminal trigger can't pile up
+#                 cycles. Default 1.
+#             The terminal-transition counter resets to 0 on a successful mint
+#             and is held in orchestrator memory only (a restart resets it). At
+#             most one active state may declare `spawn` (so the spawn state is
+#             unambiguous). The spawn's terminal must be a DEDICATED terminal
+#             with no `pr:` / `actions:` — a minted issue runs on an empty branch,
+#             so a Done-style PR autopilot would try to open a PR off nothing.
+#             See the SLEEP CYCLE section below for the full pattern.
+#
+# Declaration order matters: role-filtered listings (active states, terminal
+# states) follow it, and the dashboard renders state columns in the same order.
+# ─────────────────────────────────────────────────────────────────────────────
+states:
+  Todo:
+    role: active
+    prompt_file: prompts/Todo.md   # this state's prompt template (see `prompt:` below)
+    adapter: claude
+    model: claude-opus-4-7
+    effort: xhigh
+    max_turns: 10
+    max_concurrent: 1          # at most one implementer agent at a time
+  Review:
+    role: active
+    prompt_file: prompts/Review.md
+    adapter: codex
+    model: gpt-5-codex
+    max_turns: 4
+    allowed_transitions: [Todo, Done]
+  Done:
+    role: terminal
+    # PR autopilot merge state (issue 139). Acts only when the top-level `pr:`
+    # engine block (below) is enabled. Derived as the merge state because it
+    # declares `auto_merge`.
+    # pr:
+    #   auto_merge: squash
+    #   on_conflict: { route_to: Todo }
+    # Terminal-state handoff via typed actions (issue 36). On transition into
+    # Done, push the branch (if SYMPHONY_REPO is set → $repo non-empty) and
+    # open a PR if one does not already exist. Templates resolve against the
+    # fixed ActionContext namespace; the orchestrator stages $pr_title and
+    # $pr_body_file from the issue file before firing.
+    # A handoff that fails after its retries reroutes the issue OUT of Done into
+    # the HandoffFailed holding state (issue 235) via `on_error.then.route_to`,
+    # so a stranded handoff is operator-visible instead of silently terminal-Done.
+    # actions:
+    #   - kind: push_branch
+    #     remote: origin
+    #     ref: $branch
+    #     if: $repo
+    #     on_error: { then: { route_to: HandoffFailed } }
+    #   - kind: create_pr_if_missing
+    #     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
+    # PR autopilot close state (issue 139). Derived as the close state because
+    # it declares `close: true` — an open PR is closed without merge.
+    # pr:
+    #   close: true
+  Triage:
+    role: holding
+  HandoffFailed:
+    # Landing state for a Done handoff that FAILED (issue 235): the failing
+    # action's `on_error.then.route_to` (above) reroutes the issue here with the
+    # reason appended. Holding → never dispatched; it parks for an operator to
+    # push the branch by hand (the workspace is retained by issue 234's marker)
+    # and 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
+
+# ─────────────────────────────────────────────────────────────────────────────
+# prompt — shared prompt-assembly files (per-state prompt split). OPTIONAL.
+#
+# When an active state declares a `prompt_file` (see the states block above), the
+# shell loader builds that state's prompt by concatenating, in order:
+#
+#     prompt.preamble_file   (shared header)
+#   + the state's prompt_file (the state-specific body)
+#   + prompt.footer_file     (shared footer)
+#
+# and renders the result — so the config reads as the shape of the workflow and
+# each state's prompt lives in its own file under `prompts/`. The Liquid context
+# is `{ issue, attempt }`; each file is an ordinary Liquid template fragment.
+#
+# Both keys are paths resolved relative to the workflow file, and both are
+# optional: omit `preamble_file`/`footer_file` to wrap a state body in nothing.
+# A workflow file is pure YAML config — there is no inline prompt body. Every
+# active state names its own `prompt_file`; a state without one renders the
+# generic fallback prompt, so give each dispatched state a `prompt_file`. See
+# WORKFLOW.minimal.yaml for the smallest example and WORKFLOW.yaml in this repo
+# for a full worked example.
+#
+#   prompt:
+#     preamble_file: prompts/_preamble.md
+#     footer_file:   prompts/_footer.md
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SLEEP CYCLE — a recurring reflection STATE that mines finished work for harness
+# improvements (issue 122). Optional, opt-in pattern; layered on top of the
+# states block above. The shipped smol-symphony WORKFLOW.yaml wires it for the
+# dogfooding (symphony-on-symphony) setup.
+#
+# The idea: every dispatch starts from the same static prompt + config, no
+# matter what the last 100 issues taught us about where agents stall, get
+# rejected, burn their turn budget, or fight the harness. A periodic
+# "reflection" turn closes that feedback loop — it reads completed-task history
+# (the read-only mounts `eval_mode` exposes), distils *recurring* friction, and
+# files improvement proposals against the HARNESS (this WORKFLOW.yaml's prompt
+# branches and per-state model/max_turns/allowed_transitions/effort/actions, the
+# gondolin image config, acceptance criteria, timeouts) — never the product code under
+# review. Proposals land in Triage via `propose_issue`, so a human stays the
+# gate. This is the "self-improving agent" pattern aimed at the harness rather
+# than the product.
+#
+# SHAPE: recurring STATE, NOT an immortal ticket. The cycle is modelled as a
+# recurring state that SPAWNS ephemeral reflection issues. There is no parked
+# "Sleep cycle" ticket that ping-pongs between two states forever: when a trigger
+# fires the orchestrator MINTS a fresh issue into the spawn state; it runs once
+# and terminates in a dedicated terminal, like every other ticket. Two states
+# implement it:
+#
+#   Reflect (role: active, eval_mode: true, spawn: {...}):
+#     - eval_mode binds /symphony/issues (all state dirs, incl. the Done/*.md
+#       handoff transcripts) + /symphony/logs (per-issue JSONL run logs)
+#       read-only into the VM. No extra mount plumbing — it reuses the existing
+#       eval_mode mounts.
+#     - Give it a capable adapter/model (large context helps: a reflection turn
+#       reads many transcripts + logs) and a higher max_turns than your
+#       implement/review states.
+#     - allowed_transitions: [Reflected] — the reflector may ONLY terminate in
+#       its dedicated terminal. It cannot route itself into the
+#       implement/review/done flow. Filing improvements goes through
+#       propose_issue (→ Triage), which is independent of allowed_transitions.
+#     - The `spawn:` block (see the states-field docs above) declares the
+#       triggers (on_idle / after_terminal), the minted-issue title template, and
+#       max_in_flight. This is what makes the cycle recurring — no cron needed.
+#     - The Reflect state's `prompt_file` encodes the
+#       read → distil → propose loop and the GUARDRAILS below.
+#
+#   Reflected (role: terminal):
+#     - DEDICATED terminal for a completed reflection — NOT Done. Done carries the
+#       PR autopilot `actions:` (push_branch + create_pr_if_missing); a minted
+#       reflection runs on an empty branch (it only files propose_issue), so
+#       terminating in Done would try to open a PR off nothing. So `Reflected`
+#       declares NO `pr:` and NO `actions:`. Each cycle lands here as a browsable,
+#       per-run audit trail — one issue per cycle — instead of one ever-growing
+#       immortal ticket body.
+#
+# GUARDRAILS (this is a self-modifying loop — keep the human in it):
+#   - Output is proposals into Triage (holding, never auto-dispatched). The
+#     operator approves/discards. Do not bypass this gate.
+#   - Constrain the proposal surface to harness config. Forbid any proposal that
+#     weakens the Review state, the test/lint gates, or the Triage gate itself.
+#   - Each proposal must cite the issue ids that motivated it, so the operator
+#     checks the lesson against the evidence rather than the reflector's summary.
+#
+# CADENCE: the orchestrator auto-spawns a fresh reflection issue from the
+# Reflect state's `spawn:` block — `on_idle` (idle with >=1 issue finished since
+# the last cycle) or `after_terminal` (a backstop once N issues have reached a
+# terminal state since the last cycle). The counter resets on a successful mint;
+# `max_in_flight: 1` prevents a second cycle while one is live. An operator can
+# also mint a cycle by hand by creating a Reflect issue (a real dashboard
+# "reflect now" button or a `symphony reflect` verb is a natural fit) — a clean
+# replacement for the old "re-arm by mv/cron" path.
+#
+# Example states to add (names are yours to choose):
+#
+#   states:
+#     # ... your active/terminal states ...
+#     Reflect:
+#       role: active
+#       adapter: claude
+#       model: claude-opus-4-8[1m]   # large context for reading transcripts
+#       max_turns: 20                # higher than implement/review
+#       eval_mode: true
+#       allowed_transitions: [Reflected]
+#       spawn:
+#         on_idle: true
+#         after_terminal: 10         # backstop for busy stretches (0 disables)
+#         title: "Reflection {{ stamp }}"
+#         max_in_flight: 1           # never two reflections live at once
+#     Triage:
+#       role: holding
+#     Reflected:
+#       role: terminal               # dedicated terminal — NO pr:/actions:
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# pr — PR autopilot engine toggle: arm GitHub auto-merge when a terminal-state
+# PR is mergeable; route non-mergeable PRs back to the implementing state.
+#
+# Optional. 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 live ON the terminal states they describe, as
+# `states.<name>.pr` (see the `pr:` field doc in the states block above):
+#   • the MERGE state declares `pr: { auto_merge: <strategy>,
+#     on_conflict: { route_to: <active state> } }`
+#   • the CLOSE state declares `pr: { close: true }`
+# The reconciler derives the targets by scanning states for that field — there
+# is no named-string sibling block here.
+#
+# When `enabled: true` the reconciler grows a `pr` resource that, on every tick,
+# looks up each issue in the merge state via `gh pr list --head agent/<id>`,
+# fetches its detail with `gh pr view`, and:
+#
+#   • Arms GitHub's auto-merge when the PR is `mergeable: MERGEABLE`
+#     (`gh pr merge --auto --<strategy> --delete-branch`, where `<strategy>` is
+#     the merge state's `pr.auto_merge`). GitHub merges as soon as required
+#     checks pass and review requirements are satisfied.
+#   • When the PR is `mergeable: CONFLICTING`, appends a structured notes block
+#     to the issue file and routes the issue from the merge state back to that
+#     state's `pr.on_conflict.route_to` (default: the first declared
+#     `role: active` state). The workspace + `agent/<id>` branch are preserved.
+#     Before the next dispatch symphony runs `git fetch origin <base>` so
+#     `origin/<base>` is current, and the Todo prompt's first step is
+#     `git rebase origin/<base>` — resolving the conflict is the agent's normal
+#     flow, not an out-of-band autopilot operation.
+#   • For an issue in the close state with an open PR, closes the PR without
+#     merge and best-effort-deletes the remote branch.
+#
+# Requires `gh` authenticated on the host (`gh auth status` clean). The token
+# never enters the VM. Auto-merge ALSO requires at least one branch protection
+# rule on the base branch, or `gh pr merge --auto` will error — set one in
+# the repo's GitHub settings before flipping `enabled: true`.
+#
+# When `enabled: false` (or the block is absent) the autopilot is fully inert:
+# the resource is never constructed and the orchestrator's existing Done-state
+# behavior (workspace cleanup + the Done-state `actions:` block that pushes the
+# branch and opens the PR + operator-merge) is unchanged.
+#
+# Workspace lifecycle gotcha: when `enabled: true`, transitions into the merge
+# state no longer fire the standard terminal workspace cleanup. The pr resource
+# owns the workspace from that point on and removes it once the PR has merged
+# (or been closed). Transitions into the close state (and any other terminal
+# state) keep the standard cleanup-on-transition behavior.
+# ─────────────────────────────────────────────────────────────────────────────
+pr:
+  # enabled (bool): master switch. Default false.
+  enabled: false
+
+  # poll_interval_ms (int): per-PR GitHub view cache TTL, milliseconds. The
+  # reconciler may tick more often than this; a single PR view is reused
+  # within the window. Default 30000.
+  poll_interval_ms: 30000
+# ----------------------------------------------------------------------------
+# SLEEP CYCLE (recurring spawn) — the recurrence lives in the `spawn:` block on
+# the active reflection state (see the states-field docs + the SLEEP CYCLE
+# section above). There is NO top-level `sleep_cycle:` block and NO `arm:` block;
+# instead of re-arming one immortal parked ticket, the orchestrator MINTS a fresh
+# ephemeral reflection issue when a trigger fires:
+#
+#   states:
+#     Reflect:
+#       role: active
+#       allowed_transitions: [Reflected]
+#       spawn:
+#         on_idle: true            # spawn when idle with >=1 terminal since last cycle
+#         after_terminal: 10       # spawn after N terminal transitions (0 disables)
+#         title: "Reflection {{ stamp }}"
+#         max_in_flight: 1         # never two reflections live at once
+#     Reflected:
+#       role: terminal             # dedicated terminal — NO pr:/actions:
+#
+# SEMANTICS:
+#   - on_idle: spawn when the orchestrator is idle (nothing running, claimed, or
+#     pending retry, and no active candidate this poll) AND >=1 issue has reached
+#     a terminal state since the last cycle. The ">=1 since last cycle" gate is
+#     load-bearing: without it an idle orchestrator re-spawns in a tight loop with
+#     nothing new to mine.
+#   - after_terminal: a backstop for busy stretches that never go idle — spawn
+#     once this many issues have reached a terminal state since the last cycle.
+#     0 disables the count trigger.
+#   - max_in_flight: never mint a second issue while this many are already live in
+#     the spawn state (replaces the immortal ticket's built-in one-at-a-time
+#     mutex). Default 1.
+# The terminal-transition counter resets to 0 on a successful mint (and is
+# restored if the mint fails) and is held in orchestrator memory only (a restart
+# resets it). A finished reflection's OWN terminal move (out of the spawn state)
+# is excluded from the counter, so a completed cycle never counts toward spawning
+# the next.
+#
+# VALIDATION (structural, from each state's own role — no dedicated re-validator):
+# `spawn:` is only valid on an `active` state, and at most one active state may
+# declare `spawn`. Unlike the retired `arm:` block it needs no parked issue and
+# no from-state.
+#
+# GUARDRAILS: spawning ONLY mints the reflection issue. The proposals the
+# reflector files still land in Triage and still require human approve/discard —
+# spawning does not bypass the human gate.
+# ----------------------------------------------------------------------------
+
+# ─────────────────────────────────────────────────────────────────────────────
+# polling — how often to poll the tracker.
+# ─────────────────────────────────────────────────────────────────────────────
+polling:
+  # interval_ms (int): tick interval, milliseconds.
+  # Default: 30000
+  interval_ms: 5000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# workspace — per-issue working directory.
+# ─────────────────────────────────────────────────────────────────────────────
+workspace:
+  # root (path): parent directory holding `<issue-id>/` working trees.
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/workspaces/<project> (same <project> derivation
+  # as tracker.root above).
+  # root: ~/.symphony/workspaces/my-project
+
+  # github_repo (string | null): the GitHub `owner/repo` slug symphony pushes the
+  # per-issue `agent/<id>` branch to and opens a PR against on the Done-state
+  # transition. This is the config-file home for what was previously the
+  # `SYMPHONY_REPO` env var only.
+  #   • unset / null / "none" → LOCAL-ONLY mode: no `origin` is restored, nothing
+  #     is pushed, and the branch is left in the workspace for `git log agent/<id>`.
+  #   • "owner/repo"          → PR mode: the canonical workspace setup restores an
+  #     `origin` at https://github.com/<owner>/<repo>.git and the Done-state
+  #     actions push + `gh pr create`. Requires `gh auth status` clean on the host
+  #     (the token never enters the VM).
+  # GitHub-only by construction (the origin URL and `gh` are hardwired). There is
+  # NO auto-detection — set the literal slug or leave it local-only. A malformed
+  # value (a URL, a bare name, extra slashes/whitespace) is REJECTED at parse time
+  # rather than silently falling back to local-only.
+  #
+  # Precedence: the `SYMPHONY_REPO` env var, when set non-empty, OVERRIDES this
+  # field (so existing exports keep working); otherwise this value is used.
+  # Default: null.
+  # github_repo: owner/repo
+
+  # base_branch (string): the branch the per-issue workspace clones from and
+  # (in PR mode) targets as the PR base. The source repo's local
+  # `<base_branch>` is the canonical base ref — symphony does NOT implicitly
+  # fetch `origin/<base_branch>` at setup time; update the source repo before
+  # the next dispatch to move the base.
+  # Precedence: the `SYMPHONY_BASE_BRANCH` env var, when set non-empty,
+  # OVERRIDES this field; otherwise this value is used.
+  # Default: main.
+  base_branch: main
+
+# ─────────────────────────────────────────────────────────────────────────────
+# logs — per-issue JSONL run logs (everything to/from the VM, plus typed-action
+# output) AND the orchestrator-side text log mirrored to disk for offline debugging.
+#
+# Per-issue: one file per issue at `<root>/<sanitized-identifier>.jsonl`,
+# appended across attempts AND across symphony process restarts. Each line is
+# a self-describing JSON object with `ts`, `issue_id`, `attempt`, and a
+# `channel` discriminator:
+#
+#   channel: "acp"     — JSON-RPC frame between host and the in-VM adapter.
+#                        `direction` ("host_to_vm" | "vm_to_host") and `frame`
+#                        (parsed JSON) — or `kind: "unparseable"` + `raw`.
+#   channel: "stderr"  — raw byte chunk from the adapter / VM stderr.
+#   channel: "hook"    — stdout/stderr chunk from a terminal-state `actions:`
+#                        run, plus a final `kind: "result"` line (exit_code,
+#                        signal, timed_out). The `hook` field names the action
+#                        group (e.g. `actions`). (The channel name is a holdover
+#                        from the retired workflow-hook surface.)
+#   channel: "system"  — orchestrator lifecycle events (attempt_started — which
+#                        also carries the per-state `max_turns` budget,
+#                        attempt_ended, transition, reconciliation_terminating,
+#                        etc.). The `transition` event records each state move
+#                        (from_state, to_state, notes, actor, terminal,
+#                        rerouted) so the trajectory is reconstructable.
+#
+# Per-issue run summary (for the sleep-cycle reflector): alongside each
+# `<root>/<key>.jsonl`, the orchestrator writes a compact, versioned
+# `<root>/<key>.summary.json` at the issue's terminal unwind. It is a pure
+# REDUCTION over the lifecycle (`system`) events already in the JSONL — no extra
+# hot-path logging — so a reflection turn can read dozens of summaries without
+# re-parsing multi-MB frame logs. Fields (schema_version 1):
+#   • state_path        — distinct states visited, terminal appended
+#                         (e.g. ["Todo","Review","Todo","Review","Done"]);
+#   • attempts          — total dispatched attempts;
+#   • per_state[]       — {state, attempts, turns_used, max_turns,
+#                         budget_exhausted, wall_clock_ms};
+#   • review_rejections + rejection_notes[] — count and each reviewer kick-back's
+#                         notes (a non-reroute transition back to the INITIAL
+#                         implementing state, i.e. a Review→Todo rework);
+#   • turn_budget_exhausted, timeouts[] (stall / prompt_timeout / transport);
+#   • conflict_routes[] — PR-autopilot / action reroutes (rebase churn);
+#   • terminal_state + terminal_outcome (completed | cancelled | incomplete);
+#   • pr_number / pr_url (best-effort, scraped from the Done-state actions
+#                         stdout; null when unavailable);
+#   • first/last_event_at, wall_clock_ms_total, generated_at.
+# Graceful absence / backfill: the summary is best-effort. Issues that closed
+# BEFORE this feature shipped have no `*.summary.json`; a write failure or a
+# mid-issue process restart (the in-memory accumulator only sees post-restart
+# attempts) can leave it missing or partial. The reflector MUST treat an absent
+# or partial summary as "no signal for this issue" and fall back to the raw
+# JSONL (or skip the issue) — never as an error. No backfill job is run; old
+# issues simply carry no summary.
+#
+# Orchestrator-side: a single `<root>/symphony.log` (created on demand) gets
+# every structured log line symphony emits — workflow loads, dispatch
+# decisions, action results, reconciler ticks, shutdown — in `key=value` text
+# format. Lets an agent reviewing a finished run (typically with
+# `.symphony/logs/` mounted into a VM) replay orchestrator-side events
+# alongside the per-issue JSONL traces in the same directory. Set the
+# `SYMPHONY_LOG_FILE` env var to override the path; set it to the empty
+# string to disable the file sink entirely (stderr remains).
+#
+# Console routing: while the file sink is active (the default), the structured
+# stream goes to the file ONLY — the console shows just the startup banner
+# (workflow, tracker root, dashboard URL, MCP endpoint, ACP `/acp` WebSocket
+# endpoint, log-file path). The dashboard/MCP/ACP all share the one HTTP port,
+# which defaults to ephemeral, so the banner is how the operator learns which
+# port got bound. `tail -f` the
+# log file to follow the detail. Pass `--verbose` (alias `--foreground`) to mirror
+# the structured stream back onto the console for interactive debugging. With
+# no file sink configured, the structured stream stays on stderr.
+#
+# Intended for later evaluation — typically by another agent running inside a VM
+# — so the schema is verbose on purpose. Writes are best-effort: a failure to
+# write a log line never crashes the orchestrator.
+# ─────────────────────────────────────────────────────────────────────────────
+logs:
+  # root (path): directory holding per-issue JSONL files and symphony.log.
+  # An explicit value resolves absolute as-is, `~`-expanded against $HOME, or
+  # (relative) against the workflow file's directory.
+  # Default (unset): ~/.symphony/logs/<project> (same <project> derivation as
+  # tracker.root above) — durable run logs live OUTSIDE the repo tree by default.
+  # root: ~/.symphony/logs/my-project
+
+# ─────────────────────────────────────────────────────────────────────────────
+# workspace lifecycle — no shell `hooks:` surface.
+#
+# Symphony has no `hooks:` block (workflow-level or per-state). The behaviors
+# the old `after_create` / `before_run` / `after_run` / `before_remove` hooks
+# covered now live in typed, testable homes:
+#
+#   • First-creation workspace setup (clone + base checkout + `agent/<id>`
+#     branch cut + origin/identity) is owned by the orchestrator's TypeScript
+#     `setupWorkspaceDir`. The workspace arrives at the agent with: a hardlinked
+#     `git clone --local --no-tags` of the source repo (`SYMPHONY_SOURCE_REPO`,
+#     default: the dir containing WORKFLOW.yaml) on the base branch
+#     (`SYMPHONY_BASE_BRANCH`, default `main`); all network remotes stripped; an
+#     `origin` restored to the canonical HTTPS URL when `workspace.github_repo`
+#     (or the `SYMPHONY_REPO` env override) is set (so the Done-state push can
+#     reach a remote — `gh auth setup-git` runs host-side; the token never
+#     enters the VM); pinned `--local` git identity;
+#     and `agent/<id>` checked out off the base SHA.
+#   • Per-VM tooling (extra CLIs, language runtimes, dependency bootstrap) is
+#     baked into the agent image — see `gondolin.image` and `images/agents/`.
+#   • Arbitrary in-sandbox commands run from a state's `actions:` via a
+#     `run_in_vm` action (executes inside the per-issue VM, not on the host).
+#   • The post-attempt handoff (push branch, open PR) is the Done state's
+#     `actions:` block — see `states.Done.actions` above for the canonical pair
+#     (push_branch + create_pr_if_missing). The action executor exposes
+#     `$branch`, `$base_branch`, `$pr_title`, `$pr_body_file`, `$repo`.
+#
+# Workspace removal is a plain best-effort `rm -rf` of the per-issue dir once
+# the run unwinds; there is no pre-removal artifact-rescue hook (rescue what you
+# need via a terminal-state action before transitioning).
+# ─────────────────────────────────────────────────────────────────────────────
+
+# ─────────────────────────────────────────────────────────────────────────────
+# agent — concurrency and turn budget.
+# ─────────────────────────────────────────────────────────────────────────────
+agent:
+  # max_concurrent_agents (int): GLOBAL host ceiling on simultaneously-running
+  # agents across the whole workflow. This is the cross-state RAM bound that
+  # memory admission clamps (see memory_admission_enabled below); the sum of
+  # every state's `max_concurrent` is validated against it at startup. It stays
+  # top-level — not on a state — because it bounds total host memory across all
+  # VMs at once. Default: 10
+  max_concurrent_agents: 2
+
+  # max_turns (int): hard ceiling on autonomous turns per issue. Steering-reply
+  # turns are free; only autonomous turns count. Default: 20
+  max_turns: 6
+
+  # max_retry_backoff_ms (int): exponential backoff cap for retried dispatches
+  # after recoverable failures. Default: 300000
+  max_retry_backoff_ms: 120000
+
+  # memory_admission_enabled (bool): when true, before each dispatch the
+  # orchestrator reads `/proc/meminfo` (MemAvailable) and clamps the effective
+  # concurrency cap to what currently fits at `gondolin.mem_mib` per VM after
+  # subtracting `host_memory_reserve_mib`. This is a defense-in-depth backstop
+  # for hosts where the static `max_concurrent_agents` is set generously: when
+  # MemAvailable drops, new dispatches are gated so a misconfigured cap can't
+  # walk the host into OOM (issue 27). On hosts without `/proc/meminfo`
+  # (macOS, BSD) the probe degrades gracefully and the static cap is used
+  # unchanged. Default: true.
+  memory_admission_enabled: true
+
+  # host_memory_reserve_mib (int): headroom (MiB) the memory admission cap
+  # keeps for the orchestrator process itself, the per-VM Gondolin runners, and
+  # the kernel's own working set. Only consulted when
+  # `memory_admission_enabled` is true. Raise on hosts with heavy non-symphony
+  # workloads; lower on dedicated worker hosts. Default: 2048.
+  host_memory_reserve_mib: 2048
+
+  # circuit_breaker_threshold (int): after this many CONSECUTIVE dispatch
+  # attempts fail with the *same* (normalized) reason, the orchestrator stops
+  # retrying the issue and routes it to a holding state (the first declared
+  # `role: holding` state) for a human to inspect, instead of looping forever
+  # on a deterministically-failing dispatch (issue 128 — a persistent
+  # `401 invalid_api_key` once looped ~324 attempts over ~13h). The streak
+  # resets the moment an attempt fails with a different reason or exits
+  # cleanly, so transient/varied failures still retry under the normal backoff
+  # (`max_retry_backoff_ms`). The tripped issue's body gets a diagnostic note
+  # explaining the trip so the dashboard shows "stuck on identical failure"
+  # rather than a silent loop. Set to 0 to disable; must otherwise be >= 2
+  # (1 would trip on the first failure, never retrying). Default: 5.
+  circuit_breaker_threshold: 5
+
+# ─────────────────────────────────────────────────────────────────────────────
+# acp — Agent Client Protocol adapter selection.
+# ─────────────────────────────────────────────────────────────────────────────
+acp:
+  # adapter (string): one of symphony's known profiles. Default: 'claude'.
+  #   claude   — claude-agent-acp. The guest holds a placeholder bearer; the host
+  #              substitutes the real Anthropic OAuth token at Gondolin egress.
+  #              No real credential enters the VM.
+  #   codex    — codex-acp (issue 116). Same model: the guest holds a placeholder
+  #              bearer (in a fake ~/.codex/auth.json); the host substitutes the
+  #              real OpenAI/ChatGPT token at egress. No real credential — and no
+  #              real OPENAI_API_KEY — enters the VM.
+  adapter: claude
+
+  # Credentials never enter the VM (issue 113; codex generalized in 116). The
+  # guest holds only a token-shaped placeholder; on every outbound request the
+  # host substitutes the real upstream credential at Gondolin egress (TLS-MITM,
+  # see src/agent/credential-secrets.ts). The real refresh/durable token always
+  # stays host-side.
+  #
+  # For claude: the host reads the live access token from
+  # ~/.claude/.credentials.json (refreshing host-side via `claude -p "ok"` under
+  # flock when the cache is stale) and injects it at egress to api.anthropic.com.
+  # A minimal ~/.claude.json is staged for identity only — NO refreshToken, NO
+  # accessToken on the VM.
+  #
+  # For codex: the host reads the live credential (`tokens.access_token` from
+  # ~/.codex/auth.json, with an OPENAI_API_KEY env fallback — NEVER the refresh
+  # token) and injects it at egress to chatgpt.com / api.openai.com. A COMPLETE
+  # fake ~/.codex/auth.json is staged (JWT-shaped placeholder tokens + the
+  # non-secret account_id/auth_mode/last_refresh codex's completeness check needs),
+  # so codex-acp runs in its native mode without an in-VM OAuth handshake or
+  # refresh (both stay host-side). Every credential-bearing var is stripped from
+  # the forwarded VM boot env.
+
+  # model (string | null): optional model selector forwarded to the chosen adapter.
+  # Each adapter profile knows how to surface it natively:
+  #   claude  — exported as ANTHROPIC_MODEL on the adapter process. Accepts anything
+  #             claude-agent-acp would (aliases like "opus", "sonnet", or full IDs
+  #             like "claude-opus-4-7").
+  #   codex   — passed as `-c model="<value>"` argv to codex-acp (parsed as TOML).
+  # Leave unset / null to use the adapter's own default model. Default: null.
+  # model: claude-opus-4-7
+
+  # effort (string | null): optional reasoning-effort lever forwarded to the chosen
+  # adapter. Profile-specific surface:
+  #   claude  — written into a staged `settings.json` ({"effortLevel": "<value>"})
+  #             copied to /root/.claude/settings.json in the VM before claude-agent-acp
+  #             starts. Valid values are `low|medium|high|xhigh|max`, gated per-model
+  #             by claude-agent-acp's `supportedEffortLevels` (Opus supports `xhigh` and
+  #             `max`; Haiku does not). Symphony does not validate the value — the
+  #             adapter rejects unsupported choices at startup, which keeps symphony
+  #             from drifting from the adapter's own supported list.
+  #   codex   — not wired (codex-acp has no first-class effort knob on the wrapper);
+  #             setting `acp.effort` for a codex-backed state is a no-op.
+  # Leave unset / null for the adapter's own default. Default: null.
+  # effort: xhigh
+
+  # NOTE: the launch shape is fixed (an in-VM agent dials back the `/acp` WebSocket
+  # and spawns the chosen adapter). Customizing what the agent spawns requires
+  # forking that agent and rebuilding the VM image with the fork in place.
+
+  # shell (string): shell used to run the ACP launch command. Default: 'bash'.
+  shell: bash
+
+  # prompt_timeout_ms (int): max wall time for a single ACP `session/prompt`
+  # call (one symphony turn). Default: 3600000 (1 hour).
+  prompt_timeout_ms: 1800000
+
+  # read_timeout_ms (int): max time between bytes on the ACP stdio. Bumped from
+  # a small default because VM cold-boot + adapter startup can take ~10s on
+  # first use. Default: 30000
+  read_timeout_ms: 30000
+
+  # stall_timeout_ms (int): max time the adapter can be idle (no events) before
+  # the turn is killed and retried. Default: 300000
+  stall_timeout_ms: 300000
+
+  # ACP transport — the in-VM agent dials back a `/acp` WebSocket on symphony's unified
+  # HTTP server (the SAME listener that serves the dashboard + MCP), reached through the
+  # SAME `tcp.hosts` tunnel MCP uses (the guest dials `ws://symphony-mcp:7001/acp`). It
+  # authenticates with a per-dispatch bearer sent as the first WebSocket message, then ACP
+  # JSON-RPC frames flow as WebSocket frames; the in-VM agent (`/opt/symphony/vm-agent.mjs`)
+  # spawns the adapter via `child_process.spawn` with kernel pipes and pumps the frames to
+  # the adapter's stdio. There is NO separate ACP listener / bind port — the raw-TCP bridge
+  # (`acp.bridge.*`: bind_host/bind_port/reach_host/reach_url) was retired; those keys are
+  # ignored if present.
+
+  # connect_timeout_ms (int): how long to wait for the in-VM agent to dial back the `/acp`
+  # WebSocket after the sandbox is launched, before failing the attempt. Default: 30000
+  connect_timeout_ms: 30000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# credentials — host credential lifecycle (issue 113). The host substitutes the
+# real OAuth access token into each VM's outbound request at Gondolin egress; the
+# ticker keeps the host's cached access token warm by periodically running
+# `claude -p "ok"` — Claude Code's own OAuth path detects the stale token,
+# refreshes against Anthropic, and atomically writes the rotated tuple back to
+# `~/.claude/.credentials.json`. Symphony never implements OAuth; Anthropic's own
+# client does.
+# ─────────────────────────────────────────────────────────────────────────────
+credentials:
+  # ticker_interval_ms (int): how often the host ticker spawns `claude -p "ok"`
+  # to refresh the OAuth cache. Each live VM also refreshes proactively before its
+  # cached token expires, so the ticker is belt-to-the-braces for idle periods.
+  # Set to 0 to disable the in-symphony ticker entirely (operator runs their own
+  # systemd timer instead). Default: 21600000 (6 hours).
+  ticker_interval_ms: 21600000
+
+  # refresh_margin_ms (int): how far ahead of a token's expiry the host refreshes it.
+  # Drives BOTH the per-VM proactive tick (scheduled at `expiresAt - margin`) AND the
+  # egress request-side lazy refresh (a request bound for a credential host within this
+  # margin of expiry awaits a fresh token before going out). Must comfortably cover the
+  # refresh round-trip (`claude -p ok` rotate + re-read + fan-out) plus any in-flight long
+  # request, or a token expiring mid-dispatch loses the refresh/request race and 401s the
+  # egress (issue 214). Default: 300000 (5 minutes).
+  refresh_margin_ms: 300000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# gondolin — microVM execution environment (Gondolin substrate).
+# ─────────────────────────────────────────────────────────────────────────────
+gondolin:
+  # image: the agent rootfs source. THREE forms, in precedence order
+  # (image > oci_image > managed):
+  #
+  #   1. `managed` (the DEFAULT when neither `image` nor `oci_image` is set, and what a
+  #      fresh scaffold emits): FETCH a prebuilt Gondolin asset published to symphony's
+  #      OWN GitHub releases for the running symphony version + host arch (issue 224).
+  #      No docker, no `npm run build:image`, no local convert — onboarding is
+  #      `scaffold → run`. On the first poll the orchestrator downloads + verifies (against
+  #      the published `.sha256`) + imports the asset ONCE (the dashboard shows the
+  #      one-time fetch) and HOLDS VM dispatch until it's ready, then boots the cached
+  #      asset. Published for x86_64 and arm64/aarch64 (the `release.yml` agent-image
+  #      matrix); any OTHER arch makes the managed source inert and the doctor FAILs
+  #      with an unsupported-arch message.
+  #      Override `SYMPHONY_RELEASE_REPO` to fetch from a fork/staging release.
+  #
+  #   2. a PRE-CONVERTED asset selector — the low-level escape hatch. Build it ONCE with
+  #      `npm run build:image` (see images/agents/); the build prints a content-addressed
+  #      build id (a digest) — pin that here for an immutable reference. A `name:tag` ref
+  #      (e.g. `symphony-agents:latest`) or a path to an exported asset directory also
+  #      work. WINS over `oci_image` and the managed source when set.
+  #
+  #   3. `oci_image` (below): a normal OCI ref symphony auto-converts on first reconcile.
+  #
+  # The image ships only `mise`; node + the ACP CLIs (claude-agent-acp, codex-acp)
+  # are mise-installed at dispatch and the in-VM launcher is staged at
+  # /opt/symphony/vm-agent.mjs — so dispatch needs no runtime mounts. Default: managed.
+  image: managed
+
+  # oci_image (string | null): a NORMAL OCI image reference (a docker/podman repo
+  # string, optionally `:tag` or `@sha256:…`) that symphony auto-converts + caches into
+  # a Gondolin asset as part of the reconcile loop (issue 206) — no manual
+  # `npm run build:image` step. On the first poll where the asset isn't cached, the
+  # orchestrator converts it ONCE (the dashboard shows a "building microVM image
+  # (one-time setup)" banner) and HOLDS VM dispatch until it's ready; the cache key is
+  # the resolved OCI digest, re-checked cheaply each reconcile tick (a read-only LOCAL
+  # resolve, no pull), so a moving tag whose locally-resolved digest changes (e.g. after
+  # a re-pull) reconverts before dispatch resumes — readiness tracks the live digest, not
+  # a ref string that converted once. `oci_pull_policy` governs the one-time conversion
+  # pull, not this readiness check. Once converted, dispatch boots the cached asset
+  # automatically — set ONLY
+  # this key and go; you do NOT also need to set `image`. The MVP targets the "golden"
+  # path — a published ref that already bakes the guest contract (Node ≥ 21 + the ACP
+  # CLIs on PATH; the launcher is staged at dispatch). `image` stays the escape hatch
+  # for an asset you converted yourself, and WINS when both are set: when `image` is
+  # set the reconcile gate boots IT and the `oci_image` auto-convert path is bypassed
+  # entirely — dispatch is never held and no one-time build runs. Default: null.
+  # oci_image: ghcr.io/your-org/symphony-agents:1.0.0
+
+  # oci_pull_policy (if-not-present | always | never): how the OCI image is pulled
+  # while resolving its digest for the one-time conversion. `if-not-present` pulls
+  # only when the ref isn't already in the local container store; `always` re-pulls
+  # even when it IS present locally, so a moving tag (`repo:latest`) picks up its
+  # fresh registry digest (and reconverts when that digest changed); `never` never
+  # pulls and requires the image to already be in the local store. The cache key and
+  # the converted asset are always keyed on the POST-pull digest, so `always` can't
+  # cache against a stale local one. Only consulted when `oci_image` is set (and not
+  # by the per-tick readiness probe, which is always pull-free). Default: if-not-present.
+  # oci_pull_policy: if-not-present
+
+  # oci_runtime (docker | podman | null): container runtime used for the conversion
+  # pull/export. null = auto-detect (prefers docker, falls back to podman). Only
+  # consulted when `oci_image` is set. Default: null (auto-detect).
+  # oci_runtime: docker
+
+  # cpus (int): vCPU count per VM. Default: 2.
+  cpus: 2
+
+  # mem_mib (int): RAM per VM in MiB. Default: 2048.
+  mem_mib: 4096
+
+  # rootfs_size (string): guest rootfs virtual-disk size (qemu size syntax, e.g. "3G"),
+  # passed to the VM substrate as the MINIMUM rootfs size. The agent toolchain installs
+  # onto the guest ROOTFS each dispatch (chmod works there; the sandboxfs bind mount
+  # silently drops it — issue 222), so the rootfs must be big enough for the ephemeral
+  # install: node alone is ~123 MB plus the agent CLIs, and the default ~593 MB rootfs
+  # leaves too little headroom. Default: "3G".
+  # rootfs_size: 3G
+
+  # volumes (list): additional host:guest VFS mounts beyond the auto-mounted
+  # workspace. Gondolin's VFS is programmable (no hard per-VM mount cap), but keep
+  # this lean — if ANY state sets `eval_mode: true` it adds two read-only mounts
+  # (/symphony/issues + /symphony/logs) on top of the workspace. Prefer baking
+  # static tooling into the image over a runtime mount. Each entry:
+  # { host: path, guest: path, readonly?: bool }. Default: [].
+  volumes:
+    - host: ~/.cache/npm
+      guest: /root/.npm
+      readonly: false
+
+  # forward_env (string[]): host env vars forwarded into the VM exec.
+  # Default: [OPENAI_API_KEY, ANTHROPIC_API_KEY]
+  # NOTE: the runner strips EVERY credential-bearing var from the forwarded boot
+  # env before launch — the guest holds only a token-shaped placeholder that
+  # Gondolin substitutes with the real token at egress — so listing a credential
+  # var here does NOT plant the real key in the VM's PID-1 env.
+  forward_env:
+    - OPENAI_API_KEY
+    - ANTHROPIC_API_KEY
+
+  # mise (jdx/mise) toolchain provisioning. This is ALWAYS ON and is the ONLY toolchain
+  # path (issue 233) — there is no enable/disable toggle. The agent image ships ONLY the
+  # `mise` binary (+ glibc essentials); node + the agent CLIs (claude-code, codex,
+  # claude-agent-acp, codex-acp) come from a mise SYSTEM config symphony
+  # STAGES into the guest at /etc/mise/config.toml at dispatch, and a consuming repo's
+  # own `mise.toml` / `.tool-versions` (higher precedence) ADDS project toolchains
+  # (rust, go, kotlin+gradle, a different node, …) on top. `mise install` runs once
+  # per dispatch, installing the toolchain onto the guest ROOTFS at /opt/symphony/mise-data
+  # (EPHEMERAL per VM — see below); the agent runtime node is resolved system-scoped via
+  # `mise which node` (so a project mise.toml can't downgrade the agent below the Node ≥ 21
+  # the launcher needs). Bumping an agent CLI is a one-line edit to
+  # assets/symphony-mise.system.toml + a restart — NO image rebuild + digest repin.
+  #
+  # WHY the rootfs, not a bind mount (issue 222): the gondolin sandboxfs bind mount has no
+  # chmod opcode (chmod is a silent no-op there), so mise's create-then-chmod extractor +
+  # npm postinstall would produce NON-executable binaries on it; the guest rootfs (ext4)
+  # honors chmod, so installs land there executable. Grow it via `gondolin.rootfs_size`
+  # (default 3G) so the per-VM install fits. Only the pure downloads (node tarballs + the
+  # npm package cache) persist across dispatches, on the bind-mounted `data_dir` below.
+  #
+  # The only tunable here is `data_dir` (the download cache location).
+  mise:
+    # data_dir (string): host directory bind-mounted RW → /opt/symphony/mise-cache as the
+    # persistent mise DOWNLOAD CACHE (node tarballs + the npm package cache) — NOT the
+    # install dir (issue 222): installs need chmod, which the sandboxfs bind mount silently
+    # drops, so the toolchain installs onto the ephemeral guest rootfs and only the pure
+    # downloads live here (so a cold install isn't re-downloaded every dispatch). SHARED
+    # across every VM; host-isolated from your own ~/.local/share/mise. Absolute as-is,
+    # `~`/`$VAR`-expanded, relative → resolved against the workflow-file dir.
+    # Default: ~/.symphony/mise.
+    # data_dir: ~/.symphony/mise
+
+# ─────────────────────────────────────────────────────────────────────────────
+# egress — general dev-tooling firewall for the in-VM agent.
+#
+# Gondolin denies guest egress to non-allowlisted hosts by default. The agent can
+# always reach its own inference host (that is handled by the credential layer,
+# which substitutes the real upstream token at egress). This block additionally
+# opens the dev-tooling hosts the agent needs so gates can run inside the VM —
+# `npm install`, git-based dependencies, release-binary downloads.
+#
+# SECURITY: this is the firewall ONLY. No credential is ever substituted for a host
+# listed here — the real token substitutes solely on each adapter's inference host
+# (see src/agent/credential-secrets.ts `substitutionHosts`). The effective
+# per-adapter allowlist handed to Gondolin is THIS list UNION that adapter's
+# substitution host(s). Listing a host therefore grants plain network egress, never
+# a token. Keep the list tight — every entry widens the network surface of
+# semi-trusted in-VM code.
+# ─────────────────────────────────────────────────────────────────────────────
+egress:
+  # allowed_hosts (string[]): hostnames the in-VM agent may reach for dev tooling.
+  # Default: the mise provisioning hosts [nodejs.org, registry.npmjs.org, mise.jdx.dev,
+  # mise-versions.jdx.dev] — ALWAYS, since mise provisioning is unconditional (issue 233)
+  # — so `mise install` of the staged SYSTEM config isn't firewall-blocked. Bare
+  # hostnames ONLY — no scheme, port, or path (`github.com`, not
+  # `https://github.com/...`). A malformed entry fails safe (the host simply stays
+  # blocked, never opened). Each entry is matched against the request host exactly.
+  #
+  # An explicit list REPLACES the default — so if you set `allowed_hosts`, re-list all
+  # four mise hosts here alongside your own (omitting mise-versions.jdx.dev re-hits the
+  # cold-cache node@<N> resolution failure issue 223 documents). PROJECT toolchains pull
+  # from their own hosts; add those too (rust → static.rust-lang.org, gradle →
+  # services.gradle.org, JDK → api.adoptium.net, …).
+  allowed_hosts:
+    - nodejs.org                     # mise node prebuilts
+    - registry.npmjs.org             # npm install + mise npm: backend (agent CLIs)
+    - mise.jdx.dev                   # mise registry redirect
+    - mise-versions.jdx.dev          # mise precompiled tool version lists (node@N, etc.)
+    - github.com                     # git-based deps / release pages
+    - codeload.github.com            # GitHub tarball fetch
+    - objects.githubusercontent.com  # release-binary downloads
+
+# ─────────────────────────────────────────────────────────────────────────────
+# server — HTTP dashboard + MCP endpoint listener.
+# ─────────────────────────────────────────────────────────────────────────────
+server:
+  # port (int | null): HTTP listener port. `--port <n>` on the CLI overrides
+  # this. When both are unset symphony binds an ephemeral port (0 → the kernel
+  # picks a free port), so it "just works" with no config and two concurrent
+  # instances never collide; the actually-bound port + dashboard URL are printed
+  # to stdout at startup. Set a value here to pin a fixed port. Default: null
+  # (ephemeral).
+  # port: 8787
+
+  # host (string): bind address. Default: '127.0.0.1'. Bind to '0.0.0.0' only
+  # inside a trusted network boundary; the dashboard has no built-in auth.
+  host: 0.0.0.0
+
+# ─────────────────────────────────────────────────────────────────────────────
+# mcp — Model Context Protocol server exposed to in-VM agents.
+#
+# The orchestrator runs a JSON-RPC endpoint scoped to each active issue at
+# /api/v1/issues/<id>/mcp, gated by a per-dispatch bearer token. Three tools
+# live there:
+#
+#   • symphony.transition({ to_state, notes? })
+#     — canonical (and only) exit verb. Moves the issue into another declared
+#       state, optionally appending `notes` (markdown) to the issue body before
+#       the move so the next agent (in `to_state`) reads them as part of
+#       `issue.description`. Terminal targets clean the workspace; active and
+#       holding targets preserve it so the same `agent/<id>` git branch
+#       survives the handoff. Rejected transitions return MCP tool-result
+#       errors (isError:true) the agent can read and retry.
+#   • symphony.request_human_steering({ question, context? })
+#   • symphony.propose_issue({ title, description?, labels?, priority? })
+#     — drops a new issue into the first declared `role: holding` state
+#       directory (literal Triage if none declared). The orchestrator does NOT
+#       dispatch it; the operator approves or discards from the dashboard. The
+#       calling issue is recorded as proposed_by in the new file's
+#       front-matter.
+# ─────────────────────────────────────────────────────────────────────────────
+mcp:
+  # enabled (bool): when false, the orchestrator refuses to dispatch (MCP is
+  # required for completion signaling). Default: true.
+  enabled: true
+
+  # host (string): hostname or IP the agent uses to reach the orchestrator
+  # from inside the VM. The port is resolved at runtime from the
+  # actually-bound HTTP server. Default: '127.0.0.1' (Gondolin maps VM
+  # loopback to host loopback; verified empirically).
+  host: 127.0.0.1
+
+  # host_url (string | null): full-URL override. When set, used verbatim and
+  # `host` + bound port are ignored. Use only when the VM cannot reach the
+  # orchestrator through the host gateway (e.g. bridge networking with a
+  # fixed reverse-proxy URL). Default: null.
+  host_url: null
+
+# ─────────────────────────────────────────────────────────────────────────────
+# prompts — per-state files (there is NO inline prompt body).
+#
+# A workflow file is pure YAML config; it carries no prompt body. Each active
+# state's prompt is its `states.<name>.prompt_file` (a Liquid template) wrapped
+# in the shared `prompt.preamble_file` / `prompt.footer_file` (see the `prompt:`
+# and `states:` sections above). The runner renders the matching state's
+# assembled template fresh on every dispatch, so each state's agent sees only its
+# own instructions plus the shared preamble / footer.
+#
+# Liquid context available to every prompt file ({ issue, attempt }):
+#   issue.identifier   — the issue's external id (e.g. "DEMO-42").
+#   issue.title        — issue title (string).
+#   issue.state        — current state (string, matches a key in `states:`).
+#   issue.description  — body text (string or empty). `symphony.transition`
+#                        appends its `notes` block here before the file moves, so
+#                        the next state's agent reads the previous state's handoff
+#                        message verbatim.
+#   issue.priority     — number or null.
+#   issue.labels       — list of strings (lowercased).
+#   attempt            — int, 1-based attempt counter; absent on first attempt.
+#
+# Available Liquid filters: standard Shopify Liquid plus `escape_once`.
+#
+# See prompts/ alongside WORKFLOW.yaml in this repo for worked prompt files, and
+# WORKFLOW.minimal.yaml for the smallest single-state example.
+# ─────────────────────────────────────────────────────────────────────────────