pmx-canvas 0.1.26 → 0.1.27

package/docs/cli.md

@@ -125,6 +125,48 @@ pmx-canvas ax focus node-1 node-2      # Set AX focus
 pmx-canvas ax focus --clear           # Clear AX focus
 ```
 
+### AX primitives
+
+Host-agnostic agent-experience primitives. Timeline commands persist for
+diagnostics (retention-bounded, not snapshotted); work items, approval gates,
+and review annotations are canvas-bound and ride snapshots/restore.
+
+```bash
+# Timeline
+pmx-canvas ax event add --kind tool-start --summary "ran tests"
+pmx-canvas ax steer "focus on the failing test first"
+pmx-canvas ax evidence add --kind test-output --title "unit pass"
+pmx-canvas ax timeline --limit 50
+
+# Work items (canvas-bound)
+pmx-canvas ax work add --title "Wire up auth" --status in-progress node-1
+pmx-canvas ax work update <id> --status done
+pmx-canvas ax work list
+
+# Approval gates (canvas-bound; pending → approved/rejected)
+pmx-canvas ax approval request --title "Deploy to prod" --action deploy.prod
+pmx-canvas ax approval resolve <id> --decision approved
+pmx-canvas ax approval list
+
+# Review annotations (canvas-bound)
+pmx-canvas ax review add --body "off-by-one" --kind finding --severity error --file src/x.ts
+pmx-canvas ax review list
+
+# Host capability (own partition; survives clear)
+pmx-canvas ax host report --host copilot --canvas --session-messaging
+pmx-canvas ax host status
+```
+
+## Copilot adapter
+
+Install the bundled GitHub Copilot extension adapter into a repo. The adapter
+maps onto the same neutral AX surfaces (it never makes the core GitHub-specific).
+
+```bash
+pmx-canvas copilot install-extension --dry-run   # Preview target, writes nothing
+pmx-canvas copilot install-extension --yes        # Install/overwrite into .github/extensions/pmx-canvas/
+```
+
 ## WebView automation
 
 Drive a headless Bun.WebView (Chromium or WebKit) pointed at the workbench:

package/docs/http-api.md

@@ -117,6 +117,70 @@ curl -X PATCH http://localhost:4313/api/canvas/ax \
   -d '{"focus":{"nodeIds":["node-1"],"source":"api"}}'
 ```
 
+## AX primitives (timeline, work, host)
+
+Host-agnostic agent-experience primitives across three state partitions.
+Canvas-bound state (work items, approval gates, review annotations) rides
+canvas snapshots; timeline state (events, evidence, steering) persists for
+diagnostics but is retention-bounded and not restored by snapshots; the host
+capability is reported by adapters and survives `canvas_clear`.
+
+```bash
+# Timeline — record a normalized agent-event
+curl -X POST http://localhost:4313/api/canvas/ax/event \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"tool-start","summary":"ran tests","source":"api"}'
+
+# Timeline — send a steering message to the active agent session
+curl -X POST http://localhost:4313/api/canvas/ax/steer \
+  -H "Content-Type: application/json" \
+  -d '{"message":"focus on the failing test first","source":"api"}'
+
+# Timeline — record an evidence item (logs/tool-result/screenshot/file/diff/test-output)
+curl -X POST http://localhost:4313/api/canvas/ax/evidence \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"test-output","title":"unit pass","source":"api"}'
+
+# Timeline — read the bounded timeline (default limit 50, max 200)
+curl "http://localhost:4313/api/canvas/ax/timeline?limit=50"
+
+# Canvas-bound — add / update a work item
+curl -X POST http://localhost:4313/api/canvas/ax/work \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Wire up auth","status":"in-progress","nodeIds":["node-1"],"source":"api"}'
+curl -X PATCH http://localhost:4313/api/canvas/ax/work/<id> \
+  -H "Content-Type: application/json" \
+  -d '{"status":"done"}'
+curl http://localhost:4313/api/canvas/ax/work
+
+# Canvas-bound — request / resolve an approval gate (pending → approved/rejected)
+curl -X POST http://localhost:4313/api/canvas/ax/approval \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Deploy to prod","action":"deploy.prod","source":"api"}'
+curl -X POST http://localhost:4313/api/canvas/ax/approval/<id>/resolve \
+  -H "Content-Type: application/json" \
+  -d '{"decision":"approved","source":"api"}'
+curl http://localhost:4313/api/canvas/ax/approval
+
+# Canvas-bound — add a review annotation (comment/finding) anchored to node/file/region
+curl -X POST http://localhost:4313/api/canvas/ax/review \
+  -H "Content-Type: application/json" \
+  -d '{"body":"off-by-one","kind":"finding","severity":"error","anchorType":"file","file":"src/x.ts","source":"api"}'
+curl http://localhost:4313/api/canvas/ax/review
+
+# Host/session — report and read host capability
+curl -X PUT http://localhost:4313/api/canvas/ax/host-capability \
+  -H "Content-Type: application/json" \
+  -d '{"host":"copilot","canvas":true,"sessionMessaging":true,"source":"api"}'
+curl http://localhost:4313/api/canvas/ax/host-capability
+```
+
+Validation: `/ax/event` requires a valid `kind` + `summary` (400 otherwise);
+`/ax/evidence` requires `kind` + `title`; `/ax/steer`, `/ax/work`,
+`/ax/approval`, `/ax/review` require their primary field; `PATCH /ax/work/:id`
+and `PATCH /ax/review/:id` return 404 for unknown IDs; approval resolve returns
+404 if the gate is missing or already resolved.
+
 ## Diagrams (Excalidraw preset)
 
 ```bash

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP reference
 
-PMX Canvas ships an MCP stdio server with **45 tools** + **9 core resources**,
+PMX Canvas ships an MCP stdio server with **56 tools** + **12 core resources**,
 plus per-skill resources at `canvas://skills/<name>`. The server emits
 `notifications/resources/updated` when canvas state changes — humans pin
 nodes in the browser, agents are notified immediately.
@@ -35,7 +35,8 @@ The canvas auto-starts on first tool call.
 | `canvas_validate_spec` | Validate a json-render spec, graph payload, or HTML primitive payload without creating a node |
 | `canvas_refresh_webpage_node` | Re-fetch and update a webpage node from its stored URL |
 | `canvas_add_json_render_node` | Create a native json-render node from a validated spec |
-| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `canvas_stream_json_render_node` | Progressively build a json-render node from SpecStream JSON-Patch ops (live/streaming panels) |
+| `canvas_add_graph_node` | Create a native graph node (line, bar, pie, area, scatter, radar, stacked-bar, composed, sparkline, dot-plot, bullet, slopegraph) |
 | `canvas_build_web_artifact` | Build a bundled HTML artifact and open it on the canvas |
 
 `canvas_add_html_node` accepts optional `summary`, `agentSummary`, `embeddedNodeIds`, and
@@ -51,8 +52,19 @@ searchable and readable in pinned/spatial context.
 | `canvas_arrange` | Auto-arrange (grid/column/flow) |
 | `canvas_validate` | Validate collisions, containment, and missing edge endpoints |
 | `canvas_focus_node` | Pan viewport to a node; use CLI `focus --no-pan` when you only need to select/raise |
-| `canvas_get_ax` | Read the PMX AX state plus pinned/focused context |
+| `canvas_fit_view` | Fit the canvas viewport to all nodes or a selected subset |
+| `canvas_get_ax` | Read the PMX AX state (focus, work items, approvals, review annotations, host capability) plus pinned/focused context |
 | `canvas_set_ax_focus` | Set the host-agnostic AX focus node set; adapters can pass a source such as `codex` |
+| `canvas_record_ax_event` | Record a normalized timeline `agent-event` (prompt/assistant-message/tool-start/tool-result/failure/approval/steering) |
+| `canvas_send_steering` | Record a `steering-message`: a user instruction from the surface to the active agent session |
+| `canvas_get_ax_timeline` | Read the bounded AX timeline (events, evidence, steering) plus counts |
+| `canvas_add_work_item` | Add a canvas-bound `work-item` (visible task/plan/status tied to nodes) |
+| `canvas_update_work_item` | Update a work item's title/status/detail/nodeIds by ID |
+| `canvas_request_approval` | Request human approval via an `approval-gate` (pending) before a high-impact action |
+| `canvas_resolve_approval` | Resolve a pending approval gate (`approved`/`rejected`) |
+| `canvas_add_evidence` | Record an `evidence-item` on the timeline (logs/tool-result/screenshot/file/diff/test-output) |
+| `canvas_add_review_annotation` | Add a canvas-bound `review-annotation` (comment/finding) anchored to a node, file, or region |
+| `canvas_report_host_capability` | Report a host/session `host-capability` for diagnostics |
 | `canvas_pin_nodes` | Pin nodes to include in agent context |
 | `canvas_clear` | Clear all nodes and edges |
 | `canvas_snapshot` | Save current canvas as a named snapshot |
@@ -82,8 +94,10 @@ Individual bundled skills are also readable at `canvas://skills/<name>`.
 | Resource | Description |
 |----------|-------------|
 | `canvas://pinned-context` | Content of pinned nodes + nearby unpinned neighbors |
-| `canvas://ax` | PMX AX state, currently including persisted focus |
-| `canvas://ax-context` | Agent-readable pinned and focused AX context |
+| `canvas://ax` | PMX AX state: focus, work items, approval gates, review annotations |
+| `canvas://ax-context` | Agent-readable pinned and focused AX context, plus timeline summary and host capability |
+| `canvas://ax-work` | Canvas-bound AX work: work items, approval gates, review annotations |
+| `canvas://ax-timeline` | Bounded AX timeline: recent agent-events, evidence, and steering messages |
 | `canvas://schema` | Running-server create schemas and json-render catalog metadata |
 | `canvas://layout` | Full canvas state (all nodes, edges, viewport) |
 | `canvas://summary` | Compact overview: counts, pinned titles, viewport |
@@ -99,6 +113,10 @@ changes:
 
 - Pin changes notify `canvas://pinned-context`, `canvas://ax`, and `canvas://ax-context`
 - AX focus changes notify `canvas://ax` and `canvas://ax-context`
+- Canvas-bound AX mutations (work items, approval gates, review annotations,
+  host capability) notify `canvas://ax`, `canvas://ax-work`, and `canvas://ax-context`
+- AX timeline mutations (agent-events, evidence, steering) notify
+  `canvas://ax-timeline` and `canvas://ax-context`
 - All mutations notify `canvas://layout`, `canvas://summary`,
   `canvas://spatial-context`, `canvas://history`, and `canvas://code-graph`
 

package/docs/node-types.md

@@ -19,7 +19,7 @@ see [MCP tools](mcp.md), [HTTP API](http-api.md), and [SDK](sdk.md).
 | `webpage` | Persisted webpage snapshot with stored URL, extracted text, refresh |
 | `mcp-app` | Tool-backed hosted MCP App iframes (Excalidraw, etc.) |
 | `json-render` | Structured UI from JSON specs (cards, tables, forms) |
-| `graph` | Charts (line, bar, pie, area, scatter, radar, stacked-bar, composed) |
+| `graph` | Charts (line, bar, pie, area, scatter, radar, stacked-bar, composed, plus Tufte primitives: sparkline, dot-plot, bullet, slopegraph) |
 | `html` | Self-contained HTML/JS in a sandboxed iframe |
 | `web-artifact` | Bundled React/Tailwind artifact (full single-file app) |
 | `group` | Spatial container/frame around other nodes |

package/docs/sdk.md

@@ -85,9 +85,27 @@ console.log(canvas.validate());
 console.log(canvas.getLayout());
 
 // AX context for host adapters
-canvas.setAxFocus({ nodeIds: [n1], source: 'sdk' });
+canvas.setAxFocus([n1], { source: 'sdk' });
 console.log(canvas.getAxState());
 console.log(canvas.getAxContext());
+
+// AX primitives — host-agnostic agent-experience layer
+// Timeline (persisted for diagnostics, retention-bounded, not snapshotted)
+canvas.recordAxEvent({ kind: 'tool-start', summary: 'ran tests' }, { source: 'sdk' });
+canvas.addEvidence({ kind: 'test-output', title: 'unit pass' }, { source: 'sdk' });
+canvas.sendSteering('focus on the failing test first', { source: 'sdk' });
+console.log(canvas.getAxTimeline({ limit: 50 }));
+
+// Canvas-bound (rides snapshots + restore, cleared by canvas.clear())
+const work = canvas.addWorkItem({ title: 'Wire up auth', status: 'in-progress', nodeIds: [n1] }, { source: 'sdk' });
+canvas.updateWorkItem(work.id, { status: 'done' });
+const gate = canvas.requestApproval({ title: 'Deploy to prod', action: 'deploy.prod' }, { source: 'sdk' });
+canvas.resolveApproval(gate.id, 'approved', { source: 'sdk' });
+canvas.addReviewAnnotation({ body: 'off-by-one', kind: 'finding', severity: 'error', anchorType: 'file', file: 'src/x.ts' }, { source: 'sdk' });
+
+// Host/session capability (own table, survives clear)
+canvas.reportHostCapability({ host: 'copilot', canvas: true, sessionMessaging: true }, { source: 'sdk' });
+console.log(canvas.getHostCapability());
 ```
 
 ## WebView automation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmx-canvas",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Spatial canvas workbench for coding agents — infinite 2D canvas with agent-native CLI, MCP integration, nodes, edges, file watching, and snapshots",
   "type": "module",
   "main": "./src/server/index.ts",
@@ -56,18 +56,21 @@
   },
   "dependencies": {
     "@joplin/turndown-plugin-gfm": "^1.0.64",
-    "@json-render/core": "^0.14.1",
-    "@json-render/mcp": "^0.14.1",
-    "@json-render/react": "^0.14.1",
-    "@json-render/shadcn": "^0.14.1",
+    "@json-render/core": "0.19.0",
+    "@json-render/devtools": "0.19.0",
+    "@json-render/devtools-react": "0.19.0",
+    "@json-render/directives": "0.19.0",
+    "@json-render/mcp": "0.19.0",
+    "@json-render/react": "0.19.0",
+    "@json-render/shadcn": "0.19.0",
     "@modelcontextprotocol/ext-apps": "^1.3.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@preact/signals": "^2.0.0",
     "@types/turndown": "^5.0.6",
     "marked": "^15.0.0",
     "preact": "^10.25.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "recharts": "^3.2.1",
     "turndown": "^7.2.4",
     "zod": "^4.3.6"

package/skills/control-session-orchestrator/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: control-session-orchestrator
+description: >
+  Control-plane workflow for coordinating multi-agent, multi-session project work from a single
+  Codex, GitHub Copilot, or agent-app control session. Use this skill whenever the user asks to
+  orchestrate agents, create or steer worker sessions, run a workflow-like effort, fan out
+  audits/research/migrations, coordinate parallel implementation streams, monitor other project
+  sessions, or compare this control-session pattern to Claude Code dynamic workflows. This skill is
+  especially relevant when the current session can spawn persistent project sessions and those
+  sessions can spawn their own subagents, creating a two-level orchestration hierarchy.
+---
+
+# Control Session Orchestrator
+
+Use the current session as the control plane for project work that is too broad, risky, or
+stateful for one conversation. The control session owns intent, decomposition, routing, status,
+verification, and consolidation. Worker sessions own scoped execution. Worker subagents are local
+implementation/research/audit helpers inside each worker session.
+
+## Mental model
+
+```
+User
+  -> Control session (strategy, dispatch, tracking, integration)
+       -> Worker project session A (persistent branch/workstream)
+            -> Subagents for research, implementation, review, tests
+       -> Worker project session B (persistent branch/workstream)
+            -> Subagents for local fan-out
+       -> Verifier/reviewer session (optional independent gate)
+```
+
+This is similar to dynamic workflows, but the orchestration is human-readable and session-native
+instead of a runtime script. Use it when persistence, branches, PRs, human steering, or cross-session
+continuity matter more than fully automated fan-out.
+
+A code runtime gets reliability for free (validated results, barriers, budgets, dedup, resume). A
+prompt-driven control plane only gets it if you make state machine-checkable. Two contracts do that
+without a runtime: a required **worker result block** and a durable **control-state manifest** (see
+[Machine-checkable contracts](#machine-checkable-contracts)). Everything else in this skill keys off
+those two artifacts — without them, "is this worker done and passing?" is a guess, not a field read.
+
+## Supported control apps
+
+This skill is app-agnostic. First discover which orchestration tools are available in the current
+session, then adapt the same control workflow to that surface.
+
+| Capability | Codex app | GitHub Copilot app | Fallback |
+|---|---|---|---|
+| Find worker sessions | List/search project threads | List/search app sessions | Ask user for target session links/IDs |
+| Create persistent workstreams | Create or reuse Codex threads/worktrees when available | Create or reuse Copilot app sessions/workspaces when available | Use local subagents only |
+| Steer an existing workstream | Send a follow-up prompt to the thread | Send a follow-up prompt to the session | Ask user to paste the prompt into the worker |
+| Local fan-out | Spawn subagents from this session or ask workers to spawn their own | Use Copilot's available agent/session tools | Keep work local |
+| Tracking | Thread titles, pins, branches, PRs, canvas nodes, compact status tables | Session names, branches, PRs, issues, canvas nodes, compact status tables | Markdown status table |
+
+Do not assume the GitHub Copilot or Codex tool names. Use the tools exposed in the current
+environment, and say which control surface is active before dispatching workers.
+
+## When to use
+
+Use this skill for:
+
+- Codebase-wide audits, migrations, or parity checks
+- Parallel investigation across modules, services, features, or PRs
+- Work that benefits from independent implementer and verifier sessions
+- Large features where design, implementation, testing, and review should be split
+- Project-control prompts like "coordinate agents", "spin up sessions", "run a workflow",
+  "make workers handle this", "monitor the other sessions", or "act as control"
+- Situations where worker sessions may themselves use subagents for local research, coding, or review
+
+Do not use it for a simple one-file fix, a quick answer, or a task where a single local subagent is
+enough. Orchestration has overhead; spend it only when coordination reduces risk or increases
+throughput.
+
+## Machine-checkable contracts
+
+These are the session-native analog of a runtime's typed results and durable run state. They stay
+human-readable, but they are **required**, not advisory — the control session parses them instead of
+re-reading prose.
+
+### Worker result block
+
+Every worker MUST end its report with a fenced ` ```json ` block tagged `control-result`. The control
+session reads this block (never the surrounding prose) to update state, dedup, and decide routing.
+
+```json control-result
+{
+  "worker_id": "auth-api",
+  "wave_id": "w1",
+  "unit_key": "service/auth",
+  "scope": "src/auth/** — refresh-token rotation",
+  "status": "complete",
+  "files_changed": ["src/auth/rotate.ts"],
+  "verification": { "command": "pnpm test auth", "result": "pass", "evidence": "42 passed" },
+  "subagents_used": "2 — one research, one test author",
+  "risks": ["rotation interacts with logout; covered by test"],
+  "next_step": "ready for review session",
+  "report_ref": "thread/PR/path to the full report"
+}
+```
+
+The block must be **strict JSON** (no comments/trailing commas) so it parses. `status` is one of
+`complete | blocked | needs-decision | failed`; `verification.result` is one of `pass | fail | not-run`.
+
+### Control-state manifest
+
+One durable artifact that **is** the source of truth for the mission — a pinned control thread, a
+tracking-issue body, a canvas node, or a committed `control/state.json`. Re-read and update it every
+turn; keep the conversation for decisions, not state. One row per **unit** (unit-keyed, so the same
+unit is never dispatched twice — this is the dedup ledger).
+
+```json
+{
+  "mission": "MCP tool parity audit",
+  "non_goals": ["no behavior changes"],
+  "success_criteria": ["every tool present in server, HTTP, SDK, docs or flagged"],
+  "budget": { "max_concurrent_workers": 5, "max_total_workers": 25, "spawned": 0, "in_flight": 0 },
+  "convergence": { "rule": "single-pass", "k_empty": 2, "empty_streak": 0, "target": null, "current": 0 },
+  "workers": [
+    {
+      "unit_key": "surface/http",
+      "worker_id": "http-audit",
+      "session_ref": "thread-or-session id/link",
+      "scope": "HTTP API surface",
+      "branch_or_pr": "—",
+      "status": "pending",
+      "wave_id": "w1",
+      "last_update": "ISO-8601",
+      "evidence_ref": "report_ref from the result block"
+    }
+  ],
+  "decisions": [],
+  "open_followups": []
+}
+```
+
+Rules:
+
+- **Worker status** (what a worker self-reports in its result block): `complete | blocked |
+  needs-decision | failed`.
+- **Manifest unit status** (the superset the control session maintains): `pending | dispatched |
+  needs-decision | blocked | stalled | complete | failed | dropped`. Worker-reported values are a
+  subset of these, so setting a unit's status from a worker block (Step 5) is always valid.
+- **Terminal** states — a unit is closed — are `complete | failed | dropped`. Everything else is
+  non-terminal and must be resolved, or explicitly converted to `dropped` with a reason, before the
+  mission closes (Step 8).
+- `budget.in_flight` is the number of rows currently `dispatched`. Increment `spawned` and `in_flight`
+  on dispatch; decrement `in_flight` when a unit leaves `dispatched`; recompute it from the rows on
+  rehydrate.
+- `convergence.rule` is one of `single-pass | loop-until-dry | loop-until-budget |
+  accumulate-to-target`. `k_empty`/`empty_streak` are used only by `loop-until-dry`; `target`/`current`
+  only by `accumulate-to-target` (`target` = the count or coverage goal, `current` = progress so far).
+- dropped/failed units MUST carry a reason in `open_followups`.
+
+This manifest is what a fresh control session rehydrates from (Step 0).
+
+## Control workflow
+
+### 0. Rehydrate (resume an in-flight mission)
+
+On session start, look for an existing control-state manifest for this mission. If one exists:
+
+- Load it; treat it as the source of truth.
+- Re-attach to workers by `session_ref` and reconcile each worker's *real* status (read the thread/PR)
+  before any new dispatch.
+- Recompute `budget.in_flight` from the rows still marked `dispatched`.
+- Do NOT re-dispatch a unit whose status is `dispatched` or `complete` — route a follow-up instead.
+
+If no manifest exists, this is a new mission — create one during Step 1.
+
+### 1. Frame the mission
+
+Before spawning anything, capture (and write into the manifest):
+
+- Objective and non-goals
+- Repositories, branches, PRs, or issues in scope
+- File or subsystem boundaries for each workstream
+- Success criteria and verification gates
+- Merge/integration expectations
+- Any "do not touch" constraints
+
+Also set explicit limits up front (manifest `budget` and `convergence`):
+
+- `max_concurrent_workers` (default ~4–6) — never more in flight at once
+- `max_total_workers` — a lifetime backstop for the whole mission (e.g. 25)
+- optional token / cost / time ceiling
+- the convergence rule: `single-pass` for bounded missions; `loop-until-dry`, `loop-until-budget`,
+  or `accumulate-to-target` for open-ended audits/migrations/parity sweeps
+
+If any boundary is ambiguous and could cause conflicting edits, ask before dispatch.
+
+### 2. Detect the control surface
+
+Before dispatch, identify the available app tools:
+
+- Codex app: thread/session tools such as list, create/read, send-message, rename, pin/archive, plus
+  optional local subagent tools.
+- GitHub Copilot app: session or workspace tools exposed by the app connector, plus any available
+  GitHub issue/PR/branch controls.
+- Generic agent app: any combination of session, task, subagent, branch, issue, PR, or automation
+  tools.
+
+If no persistent-session tools are available, downgrade to a local multi-agent plan and explain the
+limitation. Do not invent a backend.
+
+### 3. Choose the topology
+
+Pick the smallest useful topology:
+
+- **One worker**: isolated implementation or bug fix that should live in its own project session
+- **Parallel workers**: independent modules, packages, endpoints, tests, or docs
+- **Research then implementation**: exploratory sessions report findings before coding starts
+- **Implementer + verifier**: one session changes code, another reviews or verifies independently
+- **Control-only**: no workers yet; just inspect state, list sessions, or plan the dispatch
+
+Prefer separate sessions when workers may edit overlapping history, need different branches, or need
+long-running context. Prefer local subagents inside one session when the task is exploratory and does
+not need persistent branch state.
+
+### 4. Dispatch workers with complete prompts
+
+Respect the budget: **never dispatch while `in_flight >= max_concurrent_workers`** — queue the unit
+(`status: pending`) and log it. On reaching `max_total_workers` or a token/cost ceiling, STOP
+dispatching and surface a *Decision needed* rather than spawning more. Dispatch is an **atomic
+manifest update**: set the unit's row to `status: dispatched` (with `session_ref`, `worker_id`,
+`wave_id`, `last_update`) and increment `spawned` and `in_flight` together; if the dispatch fails to
+start, leave the row `pending` and advance neither counter. Decrement `in_flight` when a unit leaves
+`dispatched` (it reaches a terminal state, or returns to `needs-decision`/`blocked`/`stalled`) so
+queued units can start. This keeps `in_flight` equal to the count of `dispatched` rows that Step 0
+recomputes.
+
+Each worker prompt should be self-contained. Include:
+
+- The mission and exact scope (and its `unit_key`)
+- Files, subsystems, issue/PR links, and branch expectations
+- What the worker may and may not change
+- Verification commands or acceptance criteria
+- Whether it may create commits, PRs, or only report back
+- The required result block
+
+Worker prompt template:
+
+```text
+You are worker <name> for <project>.
+
+Mission: <specific outcome>
+unit_key / wave_id: <key> / <wave>
+Scope: <files/subsystems/issue/PR>
+Do not touch: <boundaries>
+Approach: <expected plan or constraints>
+Verification: <commands/checks/evidence>
+
+You MAY use your own subagents for local research, implementation, and review, but you remain
+accountable for this scope and the final report. Do NOT create or steer further persistent project
+sessions — if the work needs another full workstream, say so in next_step.
+
+End your report with a fenced ```json control-result block (see the contract). Populate every field;
+record subagents you used in subagents_used. The control session reads only that block.
+```
+
+When using Codex app controls, prefer to rename and pin important worker/control threads so the
+session graph stays legible. When using GitHub Copilot app controls, use the corresponding session or
+workspace labels if exposed.
+
+### 5. Track state centrally
+
+The control-state manifest is the single source of truth — update it every turn, not the
+conversation. From each worker's result block, set the unit's `status`, `branch_or_pr`,
+`last_update`, and `evidence_ref`. Keep the control session's context focused on summaries and
+decisions, not full transcripts; the full report lives at `report_ref`.
+
+Track at least, per unit: `unit_key`, `worker_id`, `session_ref`, scope, status, branch/PR, last
+update, blocker, and verification state. Canvas nodes or a SQL/todo table are good backends for the
+manifest when the app exposes them.
+
+### 6. Route follow-ups (result-gate)
+
+When a worker reports, first run the **result-gate**:
+
+- Parse the `control-result` block. If a required field is missing or malformed, or the status is
+  inconsistent with evidence (e.g. `status: complete` with `verification.result != pass`), do NOT
+  accept it — send exactly one standardized re-prompt asking only for the corrected block. Cap at 2
+  retries, then escalate to the user.
+- Accept completed work only when the block validates AND meets the success criteria.
+
+Then route:
+
+- Send targeted follow-ups for missing verification, scope drift, or blockers.
+- Avoid duplicating a worker's investigation unless its result is incomplete or suspect (check the
+  unit ledger first).
+- If two or more workers conflict, pause integration and resolve ownership before more edits happen.
+
+### 7. Iterate waves to convergence
+
+For multi-wave missions, after routing a wave's follow-ups, apply the declared `convergence.rule`
+before consolidating:
+
+- **single-pass** — one wave; skip to consolidate.
+- **loop-until-dry** — keep opening units until `k_empty` consecutive waves produce zero *new*
+  (deduped) units; maintain `empty_streak` in the manifest.
+- **loop-until-budget** — stop when a budget cap is hit.
+- **accumulate-to-target** — stop when the target count/coverage is reached.
+
+"New" and "dry" are measured against the manifest's set of `unit_key`s, not memory. Never stop
+silently — write why iteration ended (`open_followups` / `decisions`).
+
+### 8. Verify and consolidate
+
+Before declaring the mission done:
+
+- Run or delegate the agreed verification gate.
+- Review diffs or ask an independent reviewer session for high-signal findings.
+- Ensure worker outputs are integrated in the right branch/session.
+
+**Wave-join / completeness gate:** the mission is complete only when **every** manifest worker row is
+in a **terminal** state — `complete`, `failed`, or `dropped`. Non-terminal rows (`pending`,
+`dispatched`, `needs-decision`, `blocked`, `stalled`) must first be resolved; a unit that cannot be —
+e.g. a worker that never reported by its checkpoint, marked `stalled` — must be explicitly converted
+to `dropped` with a reason. Only then may the mission be declared *"complete with N dropped: <ids +
+reasons>"*. Never close with a non-terminal row, and never drop silently. Enumerate every dispatched
+unit in the final summary.
+
+**Pull cadence (no push signal):** a session-native control plane has no "worker done" event to wake
+it. After dispatching a wave, define the next checkpoint trigger — a follow-up turn, a status-table
+poll, or a user ping — and never leave a wave un-joined.
+
+For PR-bound work, keep the control session responsible for final PR readiness and review routing.
+
+## Safety rules
+
+- Do not spawn workers for trivial tasks.
+- Do not let multiple workers edit the same files unless explicitly coordinated.
+- Do not assume a named app connector exists; discover it and fall back honestly.
+- Do not silently create branches, commits, pushes, or PRs; follow the user's consent and repo rules.
+- Do not ask workers to share secrets or sensitive data across sessions.
+- Worker subagents are leaf helpers — they MUST NOT create or steer further persistent sessions. The
+  hierarchy is exactly two levels (control -> worker -> subagents); a worker that needs another full
+  workstream reports that need to control.
+- Enforce the concurrency and total-fan-out caps; never exceed them silently. Dropped, skipped, or
+  failed units MUST be recorded with a reason (no silent truncation).
+- If using an in-place checkout, be extra careful: other user-owned changes may already exist.
+- If the plan changes materially, update the user and the workers before continuing.
+
+## Recommended reporting format
+
+Use a compact control-plane update (rows derived from the manifest):
+
+```markdown
+**Status:** <on track | blocked | needs decision | complete>
+**Budget:** in-flight <X/Y> · spawned <A/B> · wave <N> (empty-streak <E>)
+
+| Workstream | Session | Scope | State | Evidence |
+|---|---|---|---|---|
+| <name> | <id/name> | <scope> | <state> | <test/report/PR> |
+
+**Decision needed:** <only if blocked>
+```
+
+Keep user-facing updates concise. The control session should make coordination legible, not flood the
+user with every worker's transcript.