@orkestrel/scaffold 0.0.108 → 0.0.110

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +326 -91
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +110 -14
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +280 -0
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +188 -26
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +142 -43
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +240 -62
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +323 -0
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +169 -32
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +290 -69
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +560 -0
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +1052 -205
  12. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +361 -0
  13. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +455 -80
  14. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +327 -0
  15. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +298 -51
  16. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +170 -13
  17. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +956 -191
  18. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +707 -112
  19. package/dist/agents/skills/orkestrel-publish/scripts/window.js +235 -41
  20. package/dist/agents/skills/orkestrel-scout/scripts/map.js +341 -54
  21. package/dist/agents/templates/brief.md +6 -2
  22. package/dist/bin/main.js +51 -46
  23. package/dist/bin/main.js.map +1 -1
  24. package/dist/host/AGENTS.md +23 -21
  25. package/dist/host/agents/orchestration.md +85 -54
  26. package/dist/host/agents/platforms/windows.md +8 -3
  27. package/dist/host/agents/skills/orkestrel-align/SKILL.md +10 -13
  28. package/dist/host/agents/skills/orkestrel-align/references/fleet.md +4 -10
  29. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  30. package/dist/host/agents/skills/orkestrel-build/SKILL.md +16 -48
  31. package/dist/host/agents/skills/orkestrel-build/agents/openai.yaml +1 -1
  32. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +19 -16
  33. package/dist/host/agents/skills/orkestrel-debrief/agents/openai.yaml +1 -1
  34. package/dist/host/agents/skills/orkestrel-debrief/references/field-testing.md +15 -28
  35. package/dist/host/agents/skills/orkestrel-debrief/references/instruction-audit.md +5 -6
  36. package/dist/host/agents/skills/orkestrel-debrief/references/retention.md +4 -6
  37. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +36 -25
  38. package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +4 -5
  39. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +366 -75
  40. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +126 -16
  41. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +323 -0
  42. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +220 -31
  43. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +176 -33
  44. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +294 -59
  45. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +401 -0
  46. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +199 -34
  47. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +330 -69
  48. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +14 -12
  49. package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -5
  50. package/dist/host/agents/skills/orkestrel-falsify/references/reconcile.md +2 -1
  51. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +701 -0
  52. package/dist/host/agents/skills/orkestrel-harden/SKILL.md +31 -24
  53. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +23 -81
  54. package/dist/host/agents/skills/orkestrel-harden/references/centralization.md +4 -5
  55. package/dist/host/agents/skills/orkestrel-harden/references/contract.md +2 -0
  56. package/dist/host/agents/skills/orkestrel-harden/references/document.md +33 -0
  57. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +6 -3
  58. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +34 -18
  59. package/dist/host/agents/skills/orkestrel-harden/references/research.md +2 -0
  60. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +1272 -279
  61. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +425 -0
  62. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +603 -98
  63. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +79 -98
  64. package/dist/host/agents/skills/orkestrel-journey/references/captures.md +54 -17
  65. package/dist/host/agents/skills/orkestrel-journey/references/decide.md +1 -20
  66. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +21 -31
  67. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +1 -1
  68. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +33 -29
  69. package/dist/host/agents/skills/orkestrel-parallel/references/claude.md +15 -13
  70. package/dist/host/agents/skills/orkestrel-parallel/references/cloud.md +28 -0
  71. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  72. package/dist/host/agents/skills/orkestrel-parallel/references/cursor.md +13 -13
  73. package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +13 -13
  74. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +389 -0
  75. package/dist/host/agents/skills/orkestrel-polish/SKILL.md +16 -20
  76. package/dist/host/agents/skills/orkestrel-polish/references/capture-harness.md +16 -26
  77. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +12 -26
  78. package/dist/host/agents/skills/orkestrel-publish/agents/openai.yaml +2 -2
  79. package/dist/host/agents/skills/orkestrel-publish/references/adopt.md +23 -0
  80. package/dist/host/agents/skills/orkestrel-publish/references/release.md +4 -4
  81. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +13 -10
  82. package/dist/host/agents/skills/orkestrel-publish/references/window.md +21 -26
  83. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +348 -59
  84. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +202 -22
  85. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +1061 -191
  86. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +812 -140
  87. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +280 -38
  88. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  89. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +428 -70
  90. package/dist/host/agents/templates/brief.md +6 -2
  91. package/dist/host/agents/transports/claude-cli.md +3 -3
  92. package/dist/host/agents/transports/codex.md +3 -8
  93. package/dist/host/agents/transports/cursor.md +2 -3
  94. package/dist/host/claude/AGENTS.md +2 -3
  95. package/dist/host/claude/agents/analyst.md +3 -3
  96. package/dist/host/claude/agents/astra.md +4 -4
  97. package/dist/host/claude/agents/builder.md +4 -3
  98. package/dist/host/claude/agents/checker.md +1 -1
  99. package/dist/host/claude/agents/distiller.md +1 -1
  100. package/dist/host/claude/agents/grok.md +1 -1
  101. package/dist/host/claude/agents/opus.md +3 -3
  102. package/dist/host/claude/agents/orkestrel.md +57 -90
  103. package/dist/host/claude/agents/researcher.md +1 -1
  104. package/dist/host/claude/agents/reviewer.md +6 -2
  105. package/dist/host/claude/agents/scout.md +1 -1
  106. package/dist/host/claude/agents/verifier.md +2 -2
  107. package/dist/host/claude/rules/application.md +14 -21
  108. package/dist/host/claude/rules/architecture.md +34 -44
  109. package/dist/host/claude/rules/browser.md +3 -4
  110. package/dist/host/claude/rules/campaign.md +3 -2
  111. package/dist/host/claude/rules/documentation.md +25 -12
  112. package/dist/host/claude/rules/names.md +9 -4
  113. package/dist/host/claude/rules/patterns.md +6 -7
  114. package/dist/host/claude/rules/portability.md +1 -1
  115. package/dist/host/claude/rules/quality.md +7 -6
  116. package/dist/host/claude/rules/styles.md +2 -2
  117. package/dist/host/claude/rules/tests.md +68 -115
  118. package/dist/host/claude/rules/typescript.md +7 -9
  119. package/dist/host/claude/rules/workspace.md +27 -26
  120. package/dist/host/claude/rules/writing.md +2 -5
  121. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  122. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  123. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -1
  124. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  125. package/dist/host/codex/agents/analyst.toml +9 -3
  126. package/dist/host/codex/agents/astra.toml +10 -7
  127. package/dist/host/codex/agents/builder.toml +4 -4
  128. package/dist/host/codex/agents/opus.toml +6 -6
  129. package/dist/host/codex/agents/orkestrel.toml +1 -1
  130. package/dist/host/codex/agents/researcher.toml +2 -2
  131. package/dist/host/codex/agents/reviewer.toml +2 -2
  132. package/dist/host/codex/agents/verifier.toml +4 -4
  133. package/dist/host/codex/config.toml +1 -1
  134. package/dist/host/configs/helpers.ts +21 -1
  135. package/dist/host/configs/policy.ts +299 -15
  136. package/dist/host/cursor/rules/orchestration.mdc +1 -1
  137. package/dist/host/dotfiles/oxlintrc.json +137 -3
  138. package/dist/host/guides/agent.md +111 -134
  139. package/dist/host/guides/capture.md +801 -0
  140. package/dist/host/guides/probe.md +27 -8
  141. package/dist/host/guides/scaffold.md +97 -19
  142. package/dist/host/guides/study.md +534 -440
  143. package/dist/host/guides/test.md +111 -44
  144. package/dist/host/manifest.json +170 -244
  145. package/dist/host/tests/config.test.ts +977 -187
  146. package/dist/host/tests/policy.test.ts +165 -1
  147. package/dist/host/tests/setupPolicy.ts +1246 -33
  148. package/dist/src/core/index.cjs +222 -90
  149. package/dist/src/core/index.cjs.map +1 -1
  150. package/dist/src/core/index.d.cts +126 -40
  151. package/dist/src/core/index.d.ts +126 -40
  152. package/dist/src/core/index.js +217 -89
  153. package/dist/src/core/index.js.map +1 -1
  154. package/dist/src/server/index.cjs +20 -27
  155. package/dist/src/server/index.cjs.map +1 -1
  156. package/dist/src/server/index.js +21 -28
  157. package/dist/src/server/index.js.map +1 -1
  158. package/package.json +11 -11
  159. package/dist/agents/skills/orkestrel-dispatch/scripts/helpers.js +0 -283
  160. package/dist/host/agents/skills/orkestrel-dispatch/references/bench.md +0 -25
  161. package/dist/host/agents/skills/orkestrel-dispatch/scripts/helpers.ts +0 -333
  162. package/dist/host/guides/supervisor.md +0 -4890
@@ -13,16 +13,22 @@ description: >-
13
13
  | Within one session | subagents, child tasks, and background commands the session launches | launch results and completion notices |
14
14
  | Across sessions | separate top-level sessions on one machine sharing a checkout, the host, or the execution lane | messages that wake the receiving session; one tracked coordination record when no such channel reaches it |
15
15
 
16
- - Read the page for each harness that hosts a lane before its first launch: `references/claude.md`, `references/codex.md`, `references/cursor.md`, or `references/t3.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
16
+ - Read the page for each harness that hosts a lane before its first launch: `references/claude.md`, `references/codex.md`, `references/cursor.md`, `references/t3.md`, or `references/cloud.md`. A harness without a page carries no writer or runner lane until § Bring up a harness is answered on a page of its own.
17
17
  - Apply `.agents/orchestration.md` for routing, session reuse, consultation, independence, and acceptance.
18
18
 
19
+ ## Scripts
20
+
21
+ Run from the checkout root. The script's opening comment owns its behavior.
22
+
23
+ - `scripts/cases.ts --report FILE.json [--passed NAME ...] [--failed NAME ...]` reads a Vitest `--reporter=json` report and requires every case a `--passed` name matches to have passed and every case a `--failed` name matches to have failed. A name matches a case's full name or its own title exactly; both flags repeat. A name that matches no case is missing, and a failed case no name matches is refused, as is a test file that failed with no failed case (it did not collect, or a hook threw) and a report whose `success` is false while nothing in it failed. It prints one summary line, each difference, and `ok` or `differences=N`. Exit 0 when the report matches, 3 when it does not, 2 when the report cannot be read as a Vitest report, 64 usage.
24
+
19
25
  ## Bound the host
20
26
 
21
27
  The host budget counts every lane on the machine: this session's, each peer session's, and the Orchestrator's own commands.
22
28
 
23
- - Set the lane bound in the plan before the first dispatch. Run one process-running lane at a time on the host: tests, checks, builds, browsers, captures, and launchers, the Orchestrator's included. Report to the user before a launch that would start a second. Lanes that run no shell command run beside it.
29
+ - Set the lane bound in the plan before the first dispatch. Run one process-running lane at a time on the host: count as a process-running lane every lane that runs a test, a build, a browser, a capture, or a launcher, the Orchestrator's included; an owned-file format check, lint, type check, or `policy` run that reads only its owned paths' violations runs beside it. Report to the user before a launch that would start a second. Lanes that run no shell command run beside it.
24
30
  - Count running lanes and owned test processes at each launch.
25
- - Limit terminal launches: chain commands that do not gate each other into one launch, write long output to a file and read it once, never poll with repeated short calls, never retry a run in a loop, and check once for owned leftovers before a launch.
31
+ - Limit terminal launches: chain commands that do not gate each other into one launch (as a plan for `.agents/skills/orkestrel-dispatch/scripts/chain.ts`), write long output to a file and read it once, never poll with repeated short calls, never retry a run in a loop, and check once for owned leftovers before a launch.
26
32
  - Find the cause of an interrupted run before relaunching it.
27
33
  - While a lane that runs shell commands is live, count orphaned console and window processes. Brief a lane that needs no shell to run no command. Kill only a recorded process id, and clear orphans only when none of your lanes is live. Never kill another session's or lane's process; ask the user.
28
34
  - While a timing or live-model measurement runs, start no other test, build, or model work on the host.
@@ -34,12 +40,12 @@ The host budget counts every lane on the machine: this session's, each peer sess
34
40
 
35
41
  ## Assign lanes
36
42
 
37
- | Lane | Responsibility | Write boundary |
38
- | ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
39
- | Orchestrator | Own the protocol, roster, scope, rulings, holds, and acceptance. | Assigned coordination records and serial integration. |
40
- | Runner | Run requested tests, checks, and builds as the verifier. | Assigned evidence and declared command outputs; never source repairs. |
41
- | Writer | Implement its bounded unit under its assigned role. | Owned files and regions, plus its own log. |
42
- | Reviewer | Independently assess the subject the size gate names. | None; return the verdict to the Orchestrator. |
43
+ | Lane | Responsibility | Write boundary |
44
+ | ------------ | -------------------------------------------------------- | --------------------------------------------------------------------- |
45
+ | Orchestrator | Own the roster, scope, rulings, holds, and acceptance. | Assigned coordination records and serial integration. |
46
+ | Runner | Run requested tests, checks, and builds as the verifier. | Assigned evidence and declared command outputs; never source repairs. |
47
+ | Writer | Implement its bounded unit under its assigned role. | Owned files and regions. |
48
+ | Reviewer | Independently assess the subject the size gate names. | None; return the verdict to the Orchestrator. |
43
49
 
44
50
  - Keep active lanes within the harness limit and § Bound the host. Reserve capacity for the runner; queue work that does not fit.
45
51
  - Assign every editable region to one writer. Name shared regions by their declarations or sections. Serialize units that rewrite the same region.
@@ -48,21 +54,19 @@ The host budget counts every lane on the machine: this session's, each peer sess
48
54
  ## Prepare the round
49
55
 
50
56
  1. Commit the accepted baseline before a writing dispatch.
51
- 2. Write `tmp/units/<round>/coord/protocol.md`: the skill path, baseline, lanes, owned regions, dependencies, acceptance commands, and exclusive resources. Mark each command whose input set must be held while it runs.
52
- 3. Write `coord/roster.md` with each lane's roster fields per `.agents/orchestration.md` § Sessions and consultation. Create `coord/results/` and `coord/runs/`.
53
- 4. Resume a suitable runner or launch one. Require its ready acknowledgment, then let its idle turn end.
54
- 5. Resume or launch writers as capacity permits. Fill each roster row from the actual launch or continuation result, never from an earlier session's pattern, and send each lane the peer addresses it messages.
55
- 6. When adopting a running lane, send the protocol, ownership, log path, and next request number. Require acknowledgment before coordinated work begins.
57
+ 2. Write `tmp/units/<round>/coord/roster.md`: each lane's roster fields per `.agents/orchestration.md` § Sessions and consultation, plus the baseline, owned regions, dependencies, acceptance commands, and exclusive resources. Create `coord/runs/` for journals, errors, and results.
58
+ 3. Resume a suitable runner or launch one, and start it with its first request.
59
+ 4. Resume or launch writers as capacity permits. Fill each roster row from the actual launch or continuation result, never from an earlier session's pattern, and send each lane the peer addresses it messages.
60
+ 5. When a running lane joins the round, put the roster path, its ownership, and its next request number in the first request you send it.
56
61
 
57
62
  ## Exchange requests and results
58
63
 
59
- - Append only to your own `coord/<lane>.md` log: `<lane> | <request or phase> | <kind> | <text>`. Reviewers write no log.
60
64
  - Number requests monotonically per lane across continuations and fixes. Preserve earlier requests and results.
61
- - Send each request through the wake-capable channel in the request shape that closes this section.
62
- - The runner publishes a result by writing it under a temporary name and renaming it to `coord/results/<lane>-<request>.md` after command exit and cleanup, then sends its path and request identity to the requester and the Orchestrator.
65
+ - Send each request through the wake-capable channel in the request shape that closes this section. Name each hold in `holds:` and proceed on send; the named owners stop edits to the held inputs until the result arrives. Nobody acknowledges a request, a hold, or a withdrawn `FINAL`.
66
+ - The runner writes a result to `coord/runs/<lane>-<request>.md` after command exit and cleanup, then sends its path and request identity to the requester and the Orchestrator.
63
67
  - Wait for the harness's completion or message notice; run no watcher agent and no file-poll loop. When the notice is missing and the result is needed, read that request's durable result or task status once, reconcile the request identity, and suspend an unresolved delivery rather than launching duplicate work.
64
68
  - Escalate per `.agents/orchestration.md` § Deviation protocol. Continue independent work. Share cross-lane facts directly; only the Orchestrator changes scope or rules on acceptance.
65
- - End an idle runner turn after acknowledging readiness or publishing a result, so queued requests reach it. Never hold the runner in a wait for requests.
69
+ - End the runner's turn after it sends a result, so queued requests reach it. Never hold the runner in a wait for requests.
66
70
  - After compaction or a harness restart, reconcile the roster against the live session and process state. When continuation is unsupported or unavailable, dispatch a successor brief that carries the prior evidence and unresolved work.
67
71
 
68
72
  Use this request shape:
@@ -80,32 +84,32 @@ expect: <red or green, named cases, required artifact>
80
84
 
81
85
  ## Implement in phases
82
86
 
83
- - Log the applicable phases: types, failing proof, source, and documentation. Request the corresponding checks from the runner.
87
+ - At each applicable phase (types, failing proof, source, and documentation), request the corresponding checks from the runner.
84
88
  - Read a shared region immediately before each small, syntactically complete patch. On a context mismatch, reread and reapply only the owned hunk.
85
- - Keep read-only shell searches within § Bound the host. Send every test, check, lint, format, and build request to the runner.
86
- - Run no formatter. Apply the exact formatting hunk the Orchestrator supplies, then request a read-only format check.
87
- - Before a temporary mutation, obtain the runner's hold on conflicting commands and each affected writer's hold on edits. Mutate only after their acknowledgments. Restore the exact input, verify the restoration, and release the holds through the runner.
89
+ - Keep read-only shell searches within § Bound the host. A writer runs the read-only checks its charter grants on its owned files (the format check, a non-fix lint, the scoped type check), and, when it edits an instruction file, the `policy` project reading only the violations on its owned paths, as observations and sends every test, build, and tree-wide gate to the runner.
90
+ - Run no formatter. Apply the exact formatting hunk the Orchestrator supplies, then run a read-only format check.
91
+ - Before a temporary mutation, send the runner a request whose `holds:` names the conflicting commands and each affected writer, and mutate after the command then running returns its result. Restore the exact input, verify the restoration, and release the holds in the next request.
88
92
  - When the unit's required checks pass, send `FINAL <lane>` with source identity and evidence, write the report, and end the turn. Preserve the session for suitable follow-up work.
89
93
 
90
94
  ## Run evidence commands
91
95
 
92
96
  - Before a command, verify its input holds and exclusive resources. Hold all writers when the command reads the whole tree; otherwise hold every owner in its input closure. Do not infer that closure from the requesting writer's files alone.
93
97
  - When a conflicting process occupies a declared resource, record its owner, process id, command, and a bounded wait based on the expected work. If it remains after that wait, suspend the request for an Orchestrator ruling. Never terminate another lane's or repository's process.
94
- - Launch through `node .agents/skills/orkestrel-dispatch/scripts/launch.ts` with a cap grounded in prior runs, separate journal and error paths under `coord/runs/`, and the request identity in each filename. Follow the `orkestrel-dispatch` skill's reference Long-running commands for ownership, process tracking, and cleanup.
98
+ - Launch through `node .agents/skills/orkestrel-dispatch/scripts/launch.ts` with a cap grounded in prior runs, journal and error paths under `coord/runs/` carrying the request identity in each filename. Follow the `orkestrel-dispatch` skill's reference Long-running commands for ownership, process tracking, and cleanup.
95
99
  - State in each long command's request which line is its terminal record; that line ends the wait.
96
100
  - When the shell yields before the command exits, keep its output in the assigned file and resume its tracked session per the harness page until the terminal record arrives. Start nothing else meanwhile, and never replace the command with a second launch. Confirm owned descendants have exited before publishing completion. Escalate incomplete cleanup before releasing files or starting another command.
97
- - Run the commands the accepted unit and the size gate require, narrowest first, and add no standing root, guide, or entry check beyond the request. Preserve receipts and rerun checks per `.agents/orchestration.md` § Parallelism.
98
- - Stop on the first unexpected failure. Return the complete diagnostic and the owning file, and classify the failure as an assertion failure, an invocation error, a reporting failure, a cap, or an interruption. Preserve every receipt obtained before the stop.
101
+ - Run the commands the accepted unit and the size gate require, narrowest first, and add no standing root, guide, or entry check beyond the request. Preserve receipts and rerun checks per `.agents/orchestration.md` § Pace.
102
+ - Stop on the first unexpected failure. Return the complete diagnostic and the owning file, and classify the failure as an assertion failure, an invocation error, a reporting failure, a cap, or an interruption. Preserve every receipt obtained before the stop. Check an `expect:` that names cases against the command's `--reporter=json` report with `scripts/cases.ts`.
99
103
  - Record the command's input identity and expected outputs before launch. When an input changes during the run, report that result as invalid and retain each result whose input set stayed stable.
100
- - After every writer's current `FINAL`, the integrated review, and the acknowledged write holds, run the Orchestrator's closing acceptance request under a unique gate number. Publish `coord/results/closing-<gate>.md`, reply with that identity, and end the turn.
104
+ - After every writer's current `FINAL` and the integrated review, run the Orchestrator's closing acceptance request under a unique gate number. Write `coord/runs/closing-<gate>.md`, reply with that identity, and end the turn.
101
105
 
102
106
  ## Integrate and close
103
107
 
104
108
  - Before ruling on an escalation, inspect its cited evidence. Bound the ruling to the changed claim and affected owners.
105
109
  - When the format check reports only a filename, inspect the difference and send the writer the exact hunk.
106
110
  - Run the size gate's independent review on a pinned subject; a unit review can overlap unrelated writing only while its whole subject stays unchanged. Use unit evidence for the integrated review, then run the closing acceptance gate in the order `.agents/orchestration.md` § Campaign fixes: Audit, then Verify.
107
- - Before reopening a writer, invalidate that lane's `FINAL` with the runner and require acknowledgment. Keep every other valid `FINAL` result. Release the reopened writer only when no active gate reads its inputs.
108
- - Before a closing request, obtain affected write-hold acknowledgments and hold your own source edits. Keep them until the matching complete result arrives. After a fix, request only the checks invalidated by that fix plus any unmet acceptance requirement.
111
+ - Before reopening a writer, tell the runner in the next request that the lane's `FINAL` is withdrawn. Keep every other valid `FINAL` result. Release the reopened writer only when no active gate reads its inputs.
112
+ - Name every affected writer in the closing request's `holds:` and hold your own source edits until the matching complete result arrives. After a fix, request only the checks invalidated by that fix plus any unmet acceptance requirement.
109
113
  - Commit after the required gates and review pass. When shared hunks form one integration, commit the batch and identify its units and fixes.
110
114
 
111
115
  ## Share an execution lane between sessions
@@ -136,4 +140,4 @@ Answer each question on the harness's page under `references/`, from measurement
136
140
  10. Capability map: which engine serves each capability of `.agents/orchestration.md` § Roles? Record the map where that section's bullets direct.
137
141
  11. Visibility: which launch channel shows the lane to the user, and can the user stop it there?
138
142
 
139
- A page holds the answers in its § Mechanics table, one row per question, and the field lessons under § Quirks, one "When X, do Y" directive per lesson; a measurement keeps its date. `.agents/transports/<harness>.md` owns a harness's CLI as a bench, and `.agents/platforms/<platform>.md` owns the host shell.
143
+ `references/cloud.md` holds the answers for a cloud sandbox host. A page holds the answers in its § Mechanics table, one row per question, and the field lessons under § Quirks, one "When X, do Y" directive per lesson; a measurement keeps its date. `.agents/transports/<harness>.md` owns a harness's CLI as a bench, and `.agents/platforms/<platform>.md` owns the host shell.
@@ -4,19 +4,19 @@ Lanes that Claude Code starts in its own session. `.claude/AGENTS.md` owns loadi
4
4
 
5
5
  ## Mechanics
6
6
 
7
- | Question | Claude Code |
8
- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | Start | The Agent tool for one unit or when the next step depends on the result, with a role from `.claude/agents/` as `subagent_type`; never `general-purpose`, `Plan`, `claude`, or `fork`. A Workflow for a fan-out of small units, a staged pipeline, or a loop, its nodes configured per `.claude/AGENTS.md` § Dispatch. The built-in `Explore` agent for an exact bounded lookup, per `.claude/AGENTS.md` § Dispatch; it loads no instruction files. |
10
- | Continue | Resume a custom subagent by its agent id through the installed tool's resume or message interface; a team teammate is not a custom subagent, so verify which one the installed version resumes. Recover an interrupted Workflow with `resumeFromRunId`; its journal replays the finished agents. A surviving transcript file is no continuation route, and a one-shot `Explore` or `Plan` agent cannot continue. |
11
- | Wake versus deliver | A finished subagent, Workflow, or background command wakes the session with a notification. |
12
- | Track | The agent id, not its display name, and the parent session that can recover it. A Workflow's `scriptPath` and `runId`, recorded at launch; its journal writes only at agent start and result, so read its liveness from the newest subagent transcript. A background command's task id and output file. |
13
- | Background | A foreground shell call is capped at 10 minutes. A background command runs to its own timeout, at most 2 hours, then stops. Run anything longer under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership. |
14
- | Isolation | Agents share the session's checkout; `isolation: worktree` gives one agent its own worktree. |
15
- | Tools | A role's frontmatter lists its tools, and the host can still withhold one: in-process roles in the desktop host ran with no shell although their charter listed one (2026-10-03), and the harness can refuse an in-process agent's file write. |
16
- | Limits | At the account's usage limit, running agents and Workflow agents stop mid-run and keep the edits they made. |
17
- | Host effects | Agents and Workflow nodes run inside the session's process and open no window (2026-10-21). An agent's shell can restart in the session root between calls (2026-10-17). |
18
- | Visibility | Agent tool calls, Workflow runs, and background commands appear in the session the user watches, where the user can stop them; a CLI started from a shell shows only its command line, so run it as a capped command inside such a lane. |
19
- | Capability map | `.agents/orchestration.md` § Roles, Claude column; `.claude/AGENTS.md` § Models owns the aliases. |
7
+ | Question | Claude Code |
8
+ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Start | The Agent tool for one unit or when the next step depends on the result, with a role from `.claude/agents/` as `subagent_type`; never `general-purpose`, `Plan`, `claude`, `fork`, or `Explore`. A Workflow for a fan-out of small units, a staged pipeline, or a loop, its nodes configured per `.claude/AGENTS.md` § Dispatch. `scout` for an exact bounded lookup, per `.agents/orchestration.md` § Routing. |
10
+ | Continue | Resume a custom subagent by its agent id through the installed tool's resume or message interface; a team teammate is not a custom subagent, so verify which one the installed version resumes. Recover an interrupted Workflow with `resumeFromRunId`; its journal replays the finished agents. A surviving transcript file is no continuation route, and a one-shot `Explore` or `Plan` agent cannot continue. |
11
+ | Wake versus deliver | A finished subagent, Workflow, or background command wakes the session with a notification. |
12
+ | Track | The agent id, not its display name, and the parent session that can recover it. A Workflow's `scriptPath` and `runId`, recorded at launch; its journal writes only at agent start and result, so read its liveness from the newest subagent transcript. A background command's task id and output file. |
13
+ | Background | A foreground shell call is capped at 10 minutes. A background command runs to its own timeout, at most 2 hours, then stops. Run anything longer under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership. |
14
+ | Isolation | Agents share the session's checkout; `isolation: worktree` gives one agent its own worktree. |
15
+ | Tools | A role's frontmatter lists its tools, and the host can still withhold one: in-process roles in the desktop host ran with no shell although their charter listed one (2026-10-03), and the harness can refuse an in-process agent's file write. |
16
+ | Limits | At the account's usage limit, running agents and Workflow agents stop mid-run and keep the edits they made. |
17
+ | Host effects | Agents and Workflow nodes run inside the session's process and open no window (2026-10-21). An agent's shell can restart in the session root between calls (2026-10-17). |
18
+ | Visibility | Agent tool calls, Workflow runs, and background commands appear in the session the user watches, where the user can stop them; a CLI started from a shell shows only its command line, so run it as a capped command inside such a lane. |
19
+ | Capability map | `.agents/orchestration.md` § Roles, Claude column; `.claude/AGENTS.md` § Models owns the aliases. |
20
20
 
21
21
  ## Quirks
22
22
 
@@ -29,4 +29,6 @@ Lanes that Claude Code starts in its own session. `.claude/AGENTS.md` owns loadi
29
29
  - When an agent works outside the session root, give it absolute paths, and check the root's `git status` for strays after it returns.
30
30
  - When read-only fan-out runs on a host where child CLIs open windows, prefer in-process agents and Workflow nodes.
31
31
  - When the Edit or Write tool must reproduce a literal Unicode escape in source (a backslash, the letter `u`, and four hexadecimal digits), write that backslash itself as a Unicode escape (code point 5C). The tools decode every such escape you type before matching or writing, so a typed escape for a backtick lands as a backtick (2026-10-27). Never fall back to a shell edit.
32
+ - When a command carries a program, keep it in a TypeScript file run by `node`: a heredoc, `node -e`, an `&&` chain, or a `${...}` argument trips the harness's approval classifier on a Windows host; a one-shot read-only check can run inline.
33
+ - When a `Remove-Item` runs on a Windows host, run it as its own short command with a relative path: the approval classifier blocks a command that pairs it with a path-like literal elsewhere, such as a `'\'` string. Verify with `git status`.
32
34
  - When a claim about caching, resume, or team behavior matters, verify it against the installed version and the official [subagent documentation](https://code.claude.com/docs/en/sub-agents), [team limitations](https://code.claude.com/docs/en/agent-teams), and [prompt-cache documentation](https://code.claude.com/docs/en/prompt-caching).
@@ -0,0 +1,28 @@
1
+ # Cloud sandbox as a lane host
2
+
3
+ A cloud sandbox session that runs Claude Code on a remote machine. `.claude/AGENTS.md` § Cloud owns its setup hooks; `.agents/transports/codex.md` owns the Codex sandbox on POSIX and Cloud; `.agents/platforms/` owns the host shell.
4
+
5
+ ## Mechanics
6
+
7
+ A row marked unmeasured carries no lane until a measurement on the host answers it.
8
+
9
+ | Question | Cloud sandbox |
10
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | Start | The parent starts a session through the remote trigger. A subagent cannot load the remote trigger (2026-10-28). |
12
+ | Continue | Unmeasured. |
13
+ | Wake versus deliver | Unmeasured. |
14
+ | Track | The session identity the trigger returns. The parent reads the session's log itself; the log reader truncates a long final report (2026-10-28). |
15
+ | Background | Unmeasured. |
16
+ | Isolation | The sandbox refuses `git checkout`, `clean`, `reset`, `restore`, and `stash drop`, so a lane cannot restore its own checkout; give each trial phase a fresh clone or scratch copy (2026-10-28). |
17
+ | Tools | Shell and file tools inside the sandbox; the git refusals above. The stop hook asks to commit and push (2026-10-28). |
18
+ | Limits | Unmeasured. |
19
+ | Host effects | Unmeasured. |
20
+ | Visibility | Unmeasured. |
21
+ | Capability map | Unmeasured. |
22
+
23
+ ## Quirks
24
+
25
+ - When a trial needs a clean tree, run each phase in a fresh clone or scratch copy; the sandbox refuses `git checkout`, `clean`, `reset`, `restore`, and `stash drop`.
26
+ - When the stop hook asks to commit and push, a dispatched role never commits or pushes, and a peer session's brief says whether it does.
27
+ - When a session's result is needed, the parent reads the session's log itself; a subagent cannot load the remote trigger.
28
+ - When a session's final report may run long, ask in the brief for a short structured summary as the last message; the log reader truncates a long final report.
@@ -24,5 +24,6 @@ Native Codex agents, and Codex lanes another harness hosts. `.codex/config.toml`
24
24
  - When the shell yields before the command exits, start nothing else, and confirm no owned leftover remains before the next lane; a lane that started the next test file broke the one-runner bound (2026-10-22).
25
25
  - When a brief launches a long command, name its terminal record, such as the launcher's `exit=` line; a lane read a finished step as running and polled it for six minutes (2026-10-22).
26
26
  - When a review brief describes risks in offensive-security wording, the provider's filter can end the lane without a verdict (2026-10-20). Brief the review as quality assurance of the user's own code in neutral words, require an early verdict file, retry once, then use a recorded fallback.
27
+ - When a `codex exec` run is killed, treat it as dead only when its `codex-code-mode-host` child is gone too.
27
28
  - When a Codex child runs through a hosting harness, it can reach that harness's messaging tools; probe them before a writer or runner depends on them (`references/t3.md`).
28
29
  - When a launch fails on a tool server's handshake timeout, relaunch that lane alone; a lane beside it started with the same server (2026-10-19). Stagger launches that start the same server.
@@ -4,19 +4,19 @@ Cursor lanes, through the Cursor CLI or a hosting harness. `.cursor/rules/orches
4
4
 
5
5
  ## Mechanics
6
6
 
7
- | Question | Cursor |
8
- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | Start | The CLI bench per `.agents/transports/cursor.md`, or the hosting harness's child-task channel (`references/t3.md`). |
10
- | Continue | The CLI's `--resume` option with the session id from the `init` event continues the session with its read context intact (2026-10-01); probe it before its first use. |
11
- | Wake versus deliver | No peer-message wake channel is demonstrated. |
12
- | Track | The session id from the `init` event and the journal path. |
13
- | Background | The CLI runs under `.agents/skills/orkestrel-dispatch/scripts/launch.ts` with a cap. A lane outlived its stated 600-second timeout by running 764 seconds (2026-09-30). |
14
- | Isolation | Lanes share the checkout. |
15
- | Tools | The bench runs in ask mode, read-only. It reads images: it read a capture's heading, captions, and fills exactly in 36 seconds (2026-10-16). |
16
- | Limits | At the account's usage limit, the bench reads dark; record it and use the native reader per `.agents/orchestration.md` § Benches. |
17
- | Host effects | A Grok lane that ran shell commands leaked about one orphaned `conhost.exe` a second on a Windows host (838 in 12 minutes, 8.8 GB, 2026-10-19). Briefs that forbade every command ran ten lanes clean (2026-10-21). |
18
- | Visibility | The CLI bench is hidden; run it only as a capped command inside a visible lane. |
19
- | Capability map | Reader only: the `grok` role. |
7
+ | Question | Cursor |
8
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
9
+ | Start | The CLI bench per `.agents/transports/cursor.md`, or the hosting harness's child-task channel (`references/t3.md`). |
10
+ | Continue | The CLI's `--resume` option with the session id from the `init` event continues the session with its read context intact (2026-10-01); probe it before its first use. |
11
+ | Wake versus deliver | No peer-message wake channel is demonstrated. |
12
+ | Track | The session id from the `init` event and the journal path. |
13
+ | Background | The CLI runs under `.agents/skills/orkestrel-dispatch/scripts/launch.ts` with a cap. A lane outlived its stated 600-second timeout by running 764 seconds (2026-09-30). |
14
+ | Isolation | Lanes share the checkout. |
15
+ | Tools | The bench runs in ask mode, read-only. It reads images: it read a capture's heading, captions, and fills exactly (2026-10-16). |
16
+ | Limits | At the account's usage limit, the bench reads dark; record it and use the native reader per `.agents/orchestration.md` § Benches. |
17
+ | Host effects | A Grok lane that ran shell commands leaked `conhost.exe` processes on a Windows host (2026-10-19; see `.agents/platforms/windows.md` § Processes). Briefs that forbade every command ran clean (2026-10-21). |
18
+ | Visibility | The CLI bench is hidden; run it only as a capped command inside a visible lane. |
19
+ | Capability map | Reader only: the `grok` role. |
20
20
 
21
21
  ## Quirks
22
22
 
@@ -4,19 +4,19 @@ T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, a
4
4
 
5
5
  ## Mechanics
6
6
 
7
- | Question | T3 |
8
- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | Start | Read providers, models, options, and limits from `orchestrator_capabilities`. Use `delegate_task` for app-owned children, cross-provider work, requested model options, or worktree isolation. Create a top-level thread only when the user asks for one. |
10
- | Continue | Send an ordinary continuation to the child's `childThreadId` through `t3_thread_send`: `queue` for a separate request turn, `auto` for a reply or idle continuation, `steer` only for an in-flight change. |
11
- | Wake versus deliver | An async child's completion wakes the parent thread with a notification. A queued turn can finish with no notice (2026-10-23). |
12
- | Track | The full `taskId` the launch returns, the `childThreadId`, and the provider, model, and options actually applied. The `clientRequestId` is no lookup key. Thread ids change when the tool session changes, sometimes between launches. |
13
- | Background | A child runs commands through its provider's shell. T3 stops an idle provider session's process tree about 30 minutes after its last turn (2026-10-15). |
14
- | Isolation | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits. |
15
- | Tools | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22). |
16
- | Limits | A provider's usage limit acts as that provider's page states. T3 refuses delegation with `parent_not_active` while the parent thread is not active (2026-10-24); the Background row holds the idle stop. |
17
- | Host effects | Each child's shell opened console windows on a Windows host; six concurrent children made it unusable (2026-10-21). |
18
- | Visibility | A `delegate_task` child appears in the T3 app, where the user can stop it; a CLI started from a child's shell is hidden (the user's ruling of 2026-10-19). |
19
- | Capability map | The Claude and Codex columns of `.agents/orchestration.md` § Roles; Cursor lanes are readers. |
7
+ | Question | T3 |
8
+ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Start | Read providers, models, options, and limits from `orchestrator_capabilities`. Use `delegate_task` for app-owned children, cross-provider work, requested model options, or worktree isolation. Create a top-level thread only when the user asks for one. A child task names its role and reads that role's charter first, or the brief inlines the charter's Do, Refuse, and Return lines, and the launch records the model and options actually applied beside the role. |
10
+ | Continue | Send an ordinary continuation to the child's `childThreadId` through `t3_thread_send`: `queue` for a separate request turn, `auto` for a reply or idle continuation, `steer` only for an in-flight change. Send a continuation that changes scope, acceptance, or authorization as a pointer to its `<unit>-brief-<n>.md`; send a bare message only for an unchanged objective. |
11
+ | Wake versus deliver | An async child's completion wakes the parent thread with a notification. A queued turn can finish with no notice (2026-10-23). |
12
+ | Track | The full `taskId` the launch returns, the `childThreadId`, and the provider, model, and options actually applied. The `clientRequestId` is no lookup key. Thread ids change when the tool session changes, sometimes between launches. |
13
+ | Background | A child runs commands through its provider's shell. T3 stops an idle provider session's process tree about 30 minutes after its last turn (2026-10-15). |
14
+ | Isolation | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits. |
15
+ | Tools | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22). |
16
+ | Limits | A provider's usage limit acts as that provider's page states. T3 refuses delegation with `parent_not_active` while the parent thread is not active (2026-10-24); the Background row holds the idle stop. |
17
+ | Host effects | Each child's shell opened console windows on a Windows host; six concurrent children made it unusable (2026-10-21). |
18
+ | Visibility | A `delegate_task` child appears in the T3 app, where the user can stop it; a CLI started from a child's shell is hidden. |
19
+ | Capability map | The Claude and Codex columns of `.agents/orchestration.md` § Roles; Cursor lanes are readers. |
20
20
 
21
21
  ## Quirks
22
22