smol-symphony 0.2.0 → 0.3.1

package/dist/types/schedule/orchestrator-loop.js

@@ -0,0 +1,10 @@
+// FCIS rewrite — the dependency contract the orchestrator poll/dispatch loop
+// driver (src/shell/orchestrator-loop.ts) receives from the composition root.
+//
+// The loop itself is an imperative shell value (the OrchestratorLoop class lives
+// in src/shell); only the *shapes* it is wired with live here (the
+// exported-types-live-in-src/types invariant). The shell re-exports
+// `OrchestratorLoopDeps` so importers (the composition root) keep their original
+// specifier.
+export {};
+//# sourceMappingURL=orchestrator-loop.js.map

package/dist/types/schedule/orchestrator-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator-loop.js","sourceRoot":"","sources":["../../../src/types/schedule/orchestrator-loop.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,EAAE;AACF,iFAAiF;AACjF,mEAAmE;AACnE,oEAAoE;AACpE,iFAAiF;AACjF,aAAa"}

package/dist/types/schedule/sleep-cycle.js

@@ -0,0 +1,4 @@
+// Sleep-cycle (recurring reflection spawn) decision shapes (declarations only).
+// The pure decisions over these live in src/core/schedule/sleep-cycle.ts.
+export {};
+//# sourceMappingURL=sleep-cycle.js.map

package/dist/types/schedule/sleep-cycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-cycle.js","sourceRoot":"","sources":["../../../src/types/schedule/sleep-cycle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,0EAA0E"}

package/dist/types/schedule/slots.js

@@ -0,0 +1,8 @@
+// FCIS rewrite — types for src/core/schedule/slots.ts (pure slot accounting).
+//
+// Pure declarations only (the exported-types-live-in-src/types invariant). The
+// slot-accounting DECISIONS live in src/core/schedule/slots.ts, which re-exports
+// these types so existing importers (tick.ts, the unit test) keep the original
+// specifier.
+export {};
+//# sourceMappingURL=slots.js.map

package/dist/types/schedule/slots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.js","sourceRoot":"","sources":["../../../src/types/schedule/slots.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,+EAA+E;AAC/E,aAAa"}

package/dist/types/schedule/tick.js

@@ -0,0 +1,9 @@
+// FCIS rewrite — data types for the orchestrator scheduler reducer
+// (src/core/schedule/tick.ts).
+//
+// The reducer in core is pure runtime (it produces these shapes); the shapes
+// themselves live here so core/shell only declare values, not exported types
+// (the exported-types-live-in-src/types invariant). The core module re-exports
+// these so importers keep their original specifier.
+export {};
+//# sourceMappingURL=tick.js.map

package/dist/types/schedule/tick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick.js","sourceRoot":"","sources":["../../../src/types/schedule/tick.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,+BAA+B;AAC/B,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,+EAA+E;AAC/E,oDAAoD"}

package/dist/types/server/mcp-runtime.js

@@ -0,0 +1,8 @@
+// FCIS rewrite — types mirror for the per-issue MCP runtime (shell slice
+// src/shell/server/mcp-runtime.ts). Declarations only; the runtime + effect
+// interpreter live in the shell. Kept here so the "exported types belong in
+// src/types" gate holds and the composition root + interpreter share one
+// vocabulary. The shell modules re-export these so importers keep their
+// `server/mcp-runtime` specifier.
+export {};
+//# sourceMappingURL=mcp-runtime.js.map

package/dist/types/server/mcp-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-runtime.js","sourceRoot":"","sources":["../../../src/types/server/mcp-runtime.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,wEAAwE;AACxE,kCAAkC"}

package/dist/types/workflow/parse.js

@@ -0,0 +1,4 @@
+// Type surface for the pure WORKFLOW.yaml parser (src/core/workflow/parse.ts).
+// Declarations only — the core re-exports these so importers keep their specifier.
+export {};
+//# sourceMappingURL=parse.js.map

package/dist/types/workflow/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/types/workflow/parse.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mFAAmF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smol-symphony",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TypeScript orchestrator that runs coding agents (Claude, Codex, OpenCode) in per-issue Gondolin microVMs over ACP.",
   "keywords": [
     "orchestrator",
@@ -29,26 +29,37 @@
   },
   "files": [
     "dist/",
-    "WORKFLOW.md",
-    "WORKFLOW.template.md",
+    "patches/",
+    "WORKFLOW.yaml",
+    "WORKFLOW.minimal.yaml",
+    "WORKFLOW.template.yaml",
+    "assets/",
+    "prompts/",
+    "prompts-minimal/",
     "AGENTS.md",
     "SPEC.md",
     "PRODUCT.md",
     "DESIGN.md",
+    "scripts/postinstall.mjs",
     "scripts/vm-agent.mjs",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
-    "start": "tsx src/bin/symphony.ts",
-    "symphony": "tsx src/bin/symphony.ts WORKFLOW.md",
-    "dev": "tsx watch src/bin/symphony.ts",
+    "postinstall": "node scripts/postinstall.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "tsx src/shell/main.ts",
+    "symphony": "tsx src/shell/main.ts WORKFLOW.yaml",
+    "dev": "tsx watch src/shell/main.ts",
     "typecheck": "tsc --noEmit",
-    "test": "node --test --import tsx tests/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "lint": "eslint src --max-warnings 0",
-    "lint:arch": "depcruise src --ts-config tsconfig.json --ignore-known",
+    "lint:arch": "depcruise src --ts-config tsconfig.json",
+    "check:ratio": "node scripts/check-core-ratio.mjs",
+    "check:pokes": "node scripts/check-state-pokes.mjs",
+    "check:io": "node scripts/check-shell-io.mjs",
+    "test": "node --test --import tsx $(find tests -name '*.test.ts')",
+    "verify": "npm run typecheck && npm run lint && npm run lint:arch && npm run check:ratio && npm run check:pokes && npm run check:io && npm test",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build && node -e \"require('node:fs').accessSync('dist/bin/symphony.js')\"",
     "build:image": "bash images/agents/build-image-oci.sh"
   },
   "dependencies": {
@@ -56,6 +67,7 @@
     "@earendil-works/gondolin": "^0.12.0",
     "chokidar": "^4.0.3",
     "liquidjs": "^10.21.1",
+    "patch-package": "^8.0.1",
     "yaml": "^2.6.1"
   },
   "devDependencies": {

package/patches/@earendil-works+gondolin+0.12.0.patch

@@ -0,0 +1,173 @@
+diff --git a/node_modules/@earendil-works/gondolin/dist/src/qemu/network-stack.js b/node_modules/@earendil-works/gondolin/dist/src/qemu/network-stack.js
+index f08a11f..b8603bd 100644
+--- a/node_modules/@earendil-works/gondolin/dist/src/qemu/network-stack.js
++++ b/node_modules/@earendil-works/gondolin/dist/src/qemu/network-stack.js
+@@ -10,6 +10,35 @@ const IP_PROTO_ICMP = 1;
+ function makeTcpNatKey(srcIP, srcPort, dstIP, dstPort) {
+     return `TCP:${srcIP}:${srcPort}:${dstIP}:${dstPort}`;
+ }
++// TCP sequence and acknowledgement numbers are 32 bits wide and wrap at 2^32.
++// We keep every stored counter (mySeq/myAck/vmSeq/vmAck) masked into [0, 2^32)
++// and compare them with RFC 1982 serial-number arithmetic instead of raw </>,
++// which break across the wrap boundary. Skipping either half re-introduces the
++// `writeUInt32BE` overflow crash or silent reassembly desync near 0xFFFFFFFF.
++/** Fold a value into the 32-bit TCP sequence space [0, 2^32). */
++function wrapSeq(value) {
++    return value >>> 0;
++}
++/**
++ * Signed RFC 1982 distance between two sequence numbers: > 0 when `a` is "after"
++ * `b`, < 0 when "before", 0 when equal. ToInt32 (`| 0`) folds the difference into
++ * the [-2^31, 2^31) serial window so comparisons stay correct across wrap.
++ */
++function seqDistance(a, b) {
++    return (a - b) | 0;
++}
++/** `a` is strictly after `b` in serial-number order. */
++function seqGt(a, b) {
++    return seqDistance(a, b) > 0;
++}
++/** `a` is strictly before `b` in serial-number order. */
++function seqLt(a, b) {
++    return seqDistance(a, b) < 0;
++}
++/** `a` is at or before `b` in serial-number order. */
++function seqLe(a, b) {
++    return seqDistance(a, b) <= 0;
++}
+ const HTTP_METHODS = [
+     "GET",
+     "POST",
+@@ -503,7 +532,7 @@ export class NetworkStack extends EventEmitter {
+                 vmSeq: seq,
+                 vmAck: ack,
+                 mySeq: Math.floor(Math.random() * 0x0fffffff),
+-                myAck: seq + 1,
++                myAck: wrapSeq(seq + 1),
+                 peerWindow: window,
+                 pendingOutbound: Buffer.alloc(0),
+                 endPending: false,
+@@ -527,14 +556,14 @@ export class NetworkStack extends EventEmitter {
+         }
+         if (!session) {
+             if (!SYN) {
+-                this.sendTCP(srcIP, srcPort, dstIP, dstPort, 0, seq + (payload.length || 1), 0x04);
++                this.sendTCP(srcIP, srcPort, dstIP, dstPort, 0, wrapSeq(seq + (payload.length || 1)), 0x04);
+             }
+             return;
+         }
+         const prevPeerWindow = session.peerWindow;
+         session.peerWindow = window;
+         let shouldDrainOutbound = false;
+-        if (ack > session.vmAck && ack <= session.mySeq) {
++        if (seqGt(ack, session.vmAck) && seqLe(ack, session.mySeq)) {
+             session.vmAck = ack;
+             shouldDrainOutbound = true;
+         }
+@@ -553,12 +582,12 @@ export class NetworkStack extends EventEmitter {
+             // This matters for SSH in particular: duplicating bytes can desync the
+             // protocol and trigger errors like "Bad packet length".
+             const expectedSeq = session.myAck;
+-            if (seq > expectedSeq) {
++            if (seqGt(seq, expectedSeq)) {
+                 // Out-of-order: re-ACK what we've already seen.
+                 this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x10);
+                 return;
+             }
+-            const skip = Math.max(0, expectedSeq - seq);
++            const skip = Math.max(0, seqDistance(expectedSeq, seq));
+             if (skip >= payload.length) {
+                 // Pure retransmit (or segment contains only already-acked bytes)
+                 this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x10);
+@@ -568,7 +597,7 @@ export class NetworkStack extends EventEmitter {
+             }
+             const newPayload = payload.subarray(skip);
+             let sendBuffer = null;
+-            const nextAck = expectedSeq + newPayload.length;
++            const nextAck = wrapSeq(expectedSeq + newPayload.length);
+             if (!session.flowProtocol) {
+                 session.pendingData = Buffer.concat([session.pendingData, newPayload]);
+                 if (session.allowRawTcp) {
+@@ -635,20 +664,20 @@ export class NetworkStack extends EventEmitter {
+         if (FIN) {
+             // FIN consumes one sequence number, so only accept it once the sequence
+             // space up to the FIN is fully received.
+-            const finSeq = seq + payload.length;
+-            if (finSeq > session.myAck) {
++            const finSeq = wrapSeq(seq + payload.length);
++            if (seqGt(finSeq, session.myAck)) {
+                 // Out-of-order FIN: keep ACKing the last in-order byte.
+                 this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x10);
+                 return;
+             }
+-            if (finSeq < session.myAck) {
++            if (seqLt(finSeq, session.myAck)) {
+                 // Duplicate FIN (already acked)
+                 this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x10);
+                 return;
+             }
+             // finSeq === session.myAck
+             this.callbacks.onTcpClose({ key, destroy: false });
+-            session.myAck++;
++            session.myAck = wrapSeq(session.myAck + 1);
+             this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x10);
+             if (session.state === "CLOSED_BY_REMOTE" ||
+                 session.state === "FIN_WAIT") {
+@@ -664,8 +693,10 @@ export class NetworkStack extends EventEmitter {
+         const header = Buffer.alloc(20);
+         header.writeUInt16BE(srcPort, 0);
+         header.writeUInt16BE(dstPort, 2);
+-        header.writeUInt32BE(seq, 4);
+-        header.writeUInt32BE(ack, 8);
++        // Counters are kept wrapped at their mutation sites; mask again here so the
++        // serialization boundary can never emit an out-of-range uint32 (the crash).
++        header.writeUInt32BE(wrapSeq(seq), 4);
++        header.writeUInt32BE(wrapSeq(ack), 8);
+         header[12] = 0x50;
+         header[13] = flags;
+         header.writeUInt16BE(65535, 14);
+@@ -925,7 +956,7 @@ export class NetworkStack extends EventEmitter {
+             }
+             return;
+         }
+-        const inFlight = Math.max(0, session.mySeq - session.vmAck);
++        const inFlight = Math.max(0, seqDistance(session.mySeq, session.vmAck));
+         const maxInFlight = Math.max(0, Math.min(session.peerWindow, this.TCP_MAX_IN_FLIGHT_BYTES));
+         if (inFlight < maxInFlight) {
+             this.txFlowPaused.delete(key);
+@@ -945,7 +976,7 @@ export class NetworkStack extends EventEmitter {
+         }
+         const MSS = 1460;
+         let bytesBurstThisTick = 0;
+-        let inFlight = Math.max(0, session.mySeq - session.vmAck);
++        let inFlight = Math.max(0, seqDistance(session.mySeq, session.vmAck));
+         const maxInFlight = Math.max(0, Math.min(session.peerWindow, this.TCP_MAX_IN_FLIGHT_BYTES));
+         while (session.pendingOutbound.length > 0 &&
+             inFlight < maxInFlight &&
+@@ -963,7 +994,7 @@ export class NetworkStack extends EventEmitter {
+             if (!isLiveSession()) {
+                 return;
+             }
+-            session.mySeq += chunk.length;
++            session.mySeq = wrapSeq(session.mySeq + chunk.length);
+             inFlight += chunk.length;
+             bytesBurstThisTick += chunk.length;
+         }
+@@ -990,7 +1021,7 @@ export class NetworkStack extends EventEmitter {
+                 if (!isLiveSession()) {
+                     return;
+                 }
+-                session.mySeq++;
++                session.mySeq = wrapSeq(session.mySeq + 1);
+                 session.state = "FIN_WAIT";
+                 session.endPending = false;
+                 inFlight += 1;
+@@ -1012,7 +1043,7 @@ export class NetworkStack extends EventEmitter {
+             return;
+         session.state = "ESTABLISHED";
+         this.sendTCP(session.srcIP, session.srcPort, session.dstIP, session.dstPort, session.mySeq, session.myAck, 0x12);
+-        session.mySeq++;
++        session.mySeq = wrapSeq(session.mySeq + 1);
+     }
+     handleTcpData(message) {
+         const session = this.natTable.get(message.key);

package/prompts/Reflect.md

@@ -0,0 +1,91 @@
+You are the **reflector** running symphony's *sleep cycle*. You are not
+implementing or reviewing a product change. Your job: mine symphony's own
+finished work for *recurring* friction in **how it runs work**, distil concrete
+lessons, and file one harness-improvement proposal per lesson into Triage —
+where a human operator decides whether to adopt it. Then close out this cycle.
+
+You are a single-run, ephemeral reflection issue: you were spawned for this one
+cycle, you run once, and you terminate in `Reflected`. There is no parked ticket
+to re-arm — the orchestrator mints a fresh reflection issue for the next cycle.
+
+This is a self-modifying loop: you read agent-authored transcripts and then
+propose changes to *your own* operating instructions. The guardrails below are
+load-bearing — follow them exactly.
+
+**What you can read** (read-only mounts present only in this state):
+
+- `/symphony/issues/` — every issue file across every state directory. The
+  richest signal is `/symphony/issues/Done/*.md`: each file is the full handoff
+  thread (every `symphony.transition` notes block from implementer → reviewer →
+  approval is appended to the body), so a Done file shows how the work actually
+  went, not just the final result. `Triage/`, `Cancelled/`, and the active
+  state dirs are visible too.
+- `/symphony/logs/<id>.jsonl` — the per-issue run log: every ACP frame, adapter
+  stderr line, typed-action output, and orchestrator lifecycle event for that issue.
+  This is where stalls, turn-budget exhaustion, retries, and timeouts show up
+  in detail.
+- Your workspace is a clone of the symphony repo, so you can read `WORKFLOW.yaml`,
+  `WORKFLOW.template.yaml`, `src/`, `images/agents/`, etc. to ground each proposal
+  in the concrete knob it would change.
+
+If structured per-issue run summaries exist (companion issue #123), start from
+those as an index; otherwise skim `Done/*.md` and open the
+`/symphony/logs/<id>.jsonl` for the issues that look anomalous.
+
+**What to look for — *recurring* patterns, not one-offs.** One bad run is
+noise; the same failure shape across several issues is signal. For example:
+
+- repeated `Review → Todo` rejects with the same root cause (the reviewer keeps
+  catching the same class of mistake the implementer prompt doesn't prevent);
+- turn-budget exhaustion (a state hits `max_turns` before it can transition);
+- stalls / timeouts (`stall_timeout_ms` / `prompt_timeout_ms` trips);
+- rebase / merge-conflict churn on re-dispatch;
+- credential re-login loops;
+- acceptance-criteria misses a sharper prompt or checklist would have caught;
+- prompt ambiguity that forced `request_human_steering`.
+
+**For each distilled lesson, file exactly one `symphony.propose_issue` call**
+(one per fix — never batch multiple fixes into one proposal; Triage is
+per-item). Each proposal must:
+
+- name a single concrete change to the **harness / operating config**: a
+  per-state `prompt_file`, a per-state `model` / `max_turns` /
+  `allowed_transitions` / `effort` / `actions`, the `gondolin` image config, an
+  acceptance criterion, or a timeout;
+- include a **before → after** (what the config/prompt says now, what you'd
+  change it to);
+- cite the **evidence** — the issue ids (and, where useful, the log lines or
+  Done-file quotes) that motivated it — so the operator can check the lesson
+  against the trajectories rather than trusting your summary.
+
+**Hard guardrails — a proposal that violates any of these must NOT be filed:**
+
+- Propose changes to the **harness only** — `WORKFLOW.yaml` /
+  `WORKFLOW.template.yaml`, per-state config (including `actions:`), the `gondolin`
+  image config, acceptance criteria, timeouts. Do **not** propose edits to product/source code under
+  `src/` as a "fix" for a trajectory; if a genuine product bug is the root
+  cause, that is an ordinary `propose_issue` for an implementer, not a harness
+  change, and you should frame it that way.
+- Never propose anything that **weakens a quality gate.** Do not weaken or
+  remove the Review state, the `npm run typecheck` / `npm test` /
+  `npm run lint:arch` / `npm run lint` gates, or the Triage human-approval gate
+  itself. The whole point of this loop is that a human stays in it; proposals
+  that would let the loop dispatch its own changes without review are
+  forbidden, even if the trajectories seem to "justify" them.
+- One fix per proposal, each with cited evidence. No proposal without issue ids.
+
+When you have filed your proposals — or concluded there is no recurring pattern
+worth acting on this cycle — hand off by terminating in `Reflected`:
+
+```
+symphony.transition({
+  to_state: "Reflected",
+  notes: "<one-paragraph log of this cycle: how many issues you reviewed, the
+          patterns you found, and the proposal titles you filed (or 'no
+          actionable pattern this cycle')>"
+})
+```
+
+Then end your turn; do not call any further tools. This issue is archived in the
+`Reflected` column as a per-cycle audit trail; the orchestrator mints a fresh
+reflection issue for the next cycle.

package/prompts/Review.md

@@ -0,0 +1,97 @@
+You are the **reviewer**. The implementer has committed work to the per-issue
+branch (`agent/{{ issue.identifier }}`) and handed off. Their summary is in
+the issue description above. Your job: decide whether the work is correct and
+either approve (→ Done) or send it back (→ Todo) with specific findings.
+
+1. Read the implementer's notes in the issue description carefully — title,
+   summary, files claimed touched. (Follow-ups belong in `propose_issue`,
+   not the notes; if you see a "Follow-ups not done" section in the notes,
+   reject and ask the implementer to file each item as a separate
+   `propose_issue` call instead.)
+2. Inspect the diff against the freshly-fetched base. The host fetched
+   `origin/main` (or whatever base branch `SYMPHONY_BASE_BRANCH` names — `main`
+   is the default here) into this workspace before the dispatch, and the
+   implementer rebased onto it, so `origin/main` is the true base:
+
+   ```
+   git log --oneline origin/main..HEAD
+   git diff origin/main..HEAD
+   ```
+
+   Diff against `origin/main`, **not** the local `main` ref: your workspace's
+   local `main` is frozen at clone time and goes **stale** as sibling PRs merge
+   — `origin/main` advances but local `main` does not. Diffing `main..HEAD` then
+   surfaces commits already on base as if they were the implementer's change,
+   and can make a correctly-based branch look like it *reverts* recently-landed
+   work. (Local-only mode — no `origin` remote — has no such drift, so `main`
+   stays the correct base there.) If `HEAD`'s merge-base is behind `origin/main`
+   (e.g. `git merge-tree --write-tree HEAD origin/main` reports conflicts),
+   reject to `Todo` asking the implementer to rebase onto `origin/main` — don't
+   agonize over an apparent revert.
+
+   Look at each file the implementer claimed to touch. Spot-check tests and
+   typecheck pass:
+
+   ```
+   npm run typecheck
+   npm test
+   ```
+
+3. Placement check — is the change on the right side of the seam?
+
+   The orchestrator (`src/agent/runner.ts`, `src/mcp.ts`, `src/orchestrator.ts`)
+   owns the state machine and tracker. Repo-local glue (`git push`, `gh pr
+   create`, rescuing artifacts) lives in a state's typed `actions:` block
+   (or a `run_in_vm` action for arbitrary guest commands). Reject when the
+   diff crosses that line:
+
+   - An action implements a new state transition, or mutates the tracker
+     filesystem the orchestrator owns (e.g. `mv issues/<state>/<id>.md
+     issues/<other-state>/<id>.md`).
+   - An action mutates runtime state the orchestrator committed earlier (e.g.
+     undoing a cleanup flag) and the runner now has to re-detect what the
+     action did via a post-action scan.
+   - A new `SYMPHONY_*` env var is added so an action can reach into
+     orchestrator-owned state. The contract is growing because the logic is
+     on the wrong side; surface it as a typed call in the runner/MCP layer
+     instead.
+
+   If any of the above fires, reject with a pointer to the right home
+   (runner, MCP tool, or orchestrator). Action-only diffs that stay within
+   repo-local glue (push/PR/format-patch) are fine — this check is
+   about state-machine logic leaking into a state's `actions:`.
+
+4. Decide:
+
+   - **Approve**: the change is correct, tests pass, no blocking issues. Call
+
+     ```
+     symphony.transition({
+       to_state: "Done",
+       notes: "<approval rationale; this becomes the PR body>"
+     })
+     ```
+
+     Your notes are appended to the issue body and feed straight into the PR
+     description the host opens against the base branch. Be specific about
+     what you verified.
+
+   - **Reject**: the change is wrong, incomplete, or has issues that need
+     rework. Call
+
+     ```
+     symphony.transition({
+       to_state: "Todo",
+       notes: "<specific findings: file paths, line numbers, what's wrong,
+               what needs to change. Be concrete — the implementer will see
+               this as their next prompt.>"
+     })
+     ```
+
+     The issue goes back to Todo with your findings appended. The same
+     workspace and `agent/{{ issue.identifier }}` branch survive the round
+     trip, so the next implementer dispatch sees both your notes and their
+     prior commits.
+
+   Either way, end your turn after the transition call. Do not call any
+   further tools.

package/prompts/Todo.md

@@ -0,0 +1,96 @@
+You are the **implementer**. Your job: turn the issue into a working change on
+the per-issue branch, then hand off to the reviewer.
+
+1. **Rebase onto a fresh base first.** Symphony has just fetched
+   `origin/main` into your workspace (or whatever base branch
+   `SYMPHONY_BASE_BRANCH` names — `main` is the default and matches this
+   project). The very first thing to do is rebase your branch onto it:
+
+   ```
+   git rebase origin/main
+   ```
+
+   - On a fresh issue this is a no-op (you're already on top of base).
+   - On a re-dispatch where base has advanced this picks up the new commits.
+   - If `git rebase` reports conflicts, **resolve them in-tree as part of
+     this turn** (reconcile your change with what landed on base), `git add`
+     the resolved files, and `git rebase --continue` (repeat per replayed
+     commit). Then proceed to step 2. There is no separate conflict state
+     to route to — handling the conflict is part of normal implementation
+     work, just like any other rebase you'd do on your own machine.
+2. Read enough of the codebase to understand the change you need to make.
+3. Decide where the change belongs before writing it. The orchestrator
+   (`src/agent/runner.ts`, `src/mcp.ts`, `src/orchestrator.ts`) owns the
+   state machine and the tracker. Repo-local glue (`git push`, `gh pr
+   create`, rescuing artifacts) lives in a state's typed `actions:` block
+   (or, for arbitrary guest commands, a `run_in_vm` action); workspace
+   setup is the orchestrator's `setupWorkspaceDir`, and per-VM tooling is
+   baked into the agent image. State-machine behavior (new transitions,
+   anything that mutates tracker files or runtime entry state) belongs in
+   the orchestrator with typed APIs and tests — not in an action. If you
+   find yourself adding a `SYMPHONY_*` env var so an action can reach into
+   orchestrator state, or writing an action that the runner then has to
+   re-detect via a post-action scan, that is the signal you are on the wrong
+   side of the seam: stop and put the logic in the runner/MCP layer
+   instead. The issue body may sketch a shell-shaped solution; treat that
+   as one option, not a directive.
+4. Make the smallest correct change for the issue's stated scope, and keep it
+   focused. If you notice work beyond what the issue states, call
+   `symphony.propose_issue` for it rather than expanding this change to swallow
+   follow-up work. Add or update tests where the change is testable. Before
+   handing off, run `npm run typecheck`, `npm test`, `npm run lint:arch`, and
+   `npm run lint` — all must pass. `node_modules` may be absent on dispatch;
+   if you `npm install` to run those gates, the image's npm can rewrite
+   `package-lock.json` (e.g. bumping the root package `engines.node` from
+   `>=20` to `>=23.6.0`). That drift is unrelated to your change — before
+   handing off, run `git status` and `git checkout -- package-lock.json` to
+   drop any incidental lockfile churn you did not intend. The handoff tree
+   must be clean.
+   **Do NOT edit the `--max-warnings` ratchet in `package.json`** — leave that line
+   exactly as-is. It is tightened in one pass at the end of the burn-down. Your change
+   only needs to keep `npm run lint` green at the *current* ratchet (it will, as long
+   as you reduce or hold the warning count). Lowering it yourself just collides with
+   every other in-flight issue's `package.json` and forces manual conflict resolution.
+5. Commit your work to the per-issue branch with a short message.
+6. **Re-read the issue's Acceptance criteria and confirm your diff satisfies
+   every bullet before handing off.** An acceptance bullet you've left unmet —
+   because closing it would touch a path outside the stated `allowed_paths`, or
+   because you'd rather defer it to a `symphony.propose_issue` follow-up — means
+   the issue is **not done**. `allowed_paths` describes where the change
+   *normally* lands; it is not license to hand off an unmet acceptance bullet.
+   Satisfy the criterion (touch the extra path and say why in your notes — the
+   way you would for a required `CHANGELOG.md` edit), and do **not**
+   `symphony.propose_issue` work the acceptance criteria require of *this*
+   issue. If a criterion genuinely cannot be met within scope (it conflicts
+   with another constraint, or needs a decision only a human can make), call
+   `symphony.request_human_steering` rather than handing off a partial change
+   with the gap described in the notes. (If satisfying a bullet here means new
+   edits, re-run the gates from step 4 and amend your commit before handing
+   off.)
+7. Hand off to the reviewer by calling:
+
+   ```
+   symphony.transition({
+     to_state: "Review",
+     notes: "# <imperative-voice title, ≤72 chars>\n\n<one- to three-paragraph
+             summary of what you changed, why, files touched, and tests added>"
+   })
+   ```
+
+   The notes describe **this change**. Out-of-scope items you noticed —
+   unrelated bugs, refactors, follow-ups, a future ticket someone should
+   size — go through `symphony.propose_issue` (see the shared section below).
+   Do not park them in a "Follow-ups not done" section in the notes; that
+   surface dies in `Done/<id>.md` and no agent ever sees it again.
+
+   Don't include a verification section restating that
+   `npm run typecheck` / `npm test` / `npm run build` passed — that's an
+   AGENTS.md requirement and the reviewer re-runs them. Mention test count
+   or extra commands only when something is atypical (test count dropped,
+   you ran a smoke against a live service, etc.).
+
+   The notes block is appended to the issue body **before** the file moves to
+   `Review/`, so the reviewer sees it as part of `issue.description` on the
+   next dispatch. Write it as if it were the PR body — because if the reviewer
+   approves, the entire issue body (including this block) becomes the PR
+   description. Then end your turn; do not call any further tools.

package/prompts/_footer.md

@@ -0,0 +1,41 @@
+If you genuinely cannot proceed — ambiguous requirements, missing context that
+only a human can supply, a design decision that needs human input — call
+`symphony.request_human_steering({ question, context })` instead of guessing.
+Your turn will end immediately and the human's response will arrive as your
+next prompt.
+
+Steering tips:
+
+- The operator's dashboard already shows the original issue title and body
+  alongside your question. Do **not** restate or paraphrase the issue body in
+  `question`; ask the specific thing you need answered.
+- Use `context` for facts the operator wouldn't otherwise see: what you've
+  inspected, what you've already tried, what constraint is forcing the
+  question.
+
+If during your work you notice something worth fixing that is **out of scope**
+for your current task — an unrelated bug, a follow-up the operator should
+size, a refactor a future agent could pick up — call
+`symphony.propose_issue({ title, description?, labels?, priority? })`. The
+proposal lands in a Triage state directory that the orchestrator does **not**
+dispatch; the operator approves or discards it from the dashboard. Your
+current issue is automatically recorded as the proposal's parent — do not
+paste it into the body. Use this instead of grafting unrelated changes onto
+your current task; keep your branch focused.
+
+File **one `propose_issue` call per follow-up**, not a batched call with
+multiple items in one body. Triage is per-item triage; the operator's
+approve/discard verb is per-issue, so a batched proposal forces an
+all-or-nothing decision and loses the individual sizing/priority each
+follow-up deserves. The "Follow-ups not done" pattern of writing a bulleted
+list in the handoff notes is the wrong surface — those notes ride into the
+PR and then die in `Done/<id>.md`; only `propose_issue` puts the items in
+front of the operator on the dashboard.
+
+{% if attempt -%}
+This is continuation/retry attempt {{ attempt }}. Inspect the workspace before
+making new edits; your previous run may have left commits on the branch. Check
+`git log agent/{{ issue.identifier }}` to see what's there. If the work is
+already complete in the current state, call `symphony.transition` with the
+appropriate next state and notes summarising what was already done, then stop.
+{%- endif %}