@orkestrel/scaffold 0.0.106 → 0.0.108

package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts

@@ -2,14 +2,21 @@
 //   node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --report
 //   node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --tmp [--older-than MINUTES]
 //   node .agents/skills/orkestrel-dispatch/scripts/sweep.ts --unit UNIT [--delete]
-// --report lists leftovers under tmp/ and .orkestrel/ by age and deletes nothing.
+// --report lists leftovers under tmp/ and .orkestrel/ by age and deletes nothing. It also checks
+// every .md file under .orkestrel/: a backticked repository-relative path that git ignores prints
+// `<file>:<line> cites ignored path <path>` (a path git tracks is never reported, nor is a glob or
+// placeholder whose literal prefix git tracks), and an absolute machine path on a line prints
+// `<file>:<line> names a machine path`. Both lines are report-only.
 // --tmp deletes launch files older than the threshold (default 60 minutes), removes emptied
 // directories, and refuses while any launch file changed in the last 2 minutes.
 // --unit lists one accepted unit's files under the launch directories (the brief, report, claims,
 // journal, errors, status, pid, and last-message files whose name is UNIT followed by `-` or `.`), and
 // --delete removes them, refusing while one changed in the last 2 minutes.
+// --tmp and --unit --delete never delete a file git tracks: each prints `kept tracked <path>` and the
+// refusal ignores a tracked file; --unit alone marks a tracked file in its listing.
 // Exit 0 on success, 2 when a deletion is refused, 64 on usage.
-import { existsSync, readdirSync, rmSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
 import { basename, join } from 'node:path'
 import { listFiles, readMissingFlags, readOption } from './helpers.ts'
 
@@ -27,6 +34,27 @@ const RECENT_MS = 2 * 60_000
 // A launch directory holds nothing a walk skips, so every file beneath it counts.
 const NOTHING_SKIPPED: ReadonlySet<string> = new Set()
 
+// Git's output is bounded by the repository's file count, so a generous buffer is the only limit.
+const GIT_BUFFER = 64 * 1024 * 1024
+
+// An absolute machine path: a drive-letter path, or one that opens `/Users/`, `/home/`, or `~/`. The
+// lookbehind keeps `https://`, `src/home/`, and `./home/` from matching.
+const MACHINE_PATH = /(?<![\w.-])(?:[A-Za-z]:[\\/]|\/(?:Users|home)\/|~\/)/u
+const BACKTICKED = /`([^`\n]+)`/gu
+const PLACEHOLDER = /[*?<{]/u
+
+interface Citation {
+	readonly path: string
+	readonly directory: boolean
+	readonly prefix: string | undefined
+}
+
+interface Finding {
+	readonly file: string
+	readonly line: number
+	readonly citation: Citation | undefined
+}
+
 function formatDay(modified: number): string {
 	return new Date(modified).toISOString().slice(0, 10)
 }
@@ -68,6 +96,102 @@ function readThreshold(argv: readonly string[]): number | undefined {
 	return Number.isFinite(value) && value > 0 ? value : undefined
 }
 
+// Lists the files git tracks beneath the scope (the whole repository when empty), as forward-slash
+// paths from the root. Any git failure reads as nothing tracked, so the run keeps its old behavior.
+function listTracked(scope: readonly string[]): readonly string[] {
+	const args = ['ls-files', '-z', ...(scope.length === 0 ? [] : ['--', ...scope])]
+	const run = spawnSync('git', args, { encoding: 'utf8', windowsHide: true, maxBuffer: GIT_BUFFER })
+	if (run.status !== 0) return []
+	return run.stdout.split('\0').filter((path) => path !== '')
+}
+
+// Names the probes git ignores, from one batched `git check-ignore`: status 0 and 1 both answer,
+// and any other status reads as nothing ignored.
+function readIgnored(probes: readonly string[]): ReadonlySet<string> {
+	if (probes.length === 0) return new Set()
+	const run = spawnSync('git', ['check-ignore', '--stdin', '-z'], {
+		encoding: 'utf8',
+		windowsHide: true,
+		maxBuffer: GIT_BUFFER,
+		input: probes.join('\0'),
+	})
+	if (run.status !== 0 && run.status !== 1) return new Set()
+	return new Set(run.stdout.split('\0').filter((path) => path !== ''))
+}
+
+// Reads a backticked token as a repository-relative citation. A token counts when it has no
+// whitespace, contains `/`, and is no URL; the path stops at its first glob or placeholder character
+// and drops a trailing `/`. A machine path, a path outside the repository, and a backslash path are
+// no citation.
+function readCitation(token: string): Citation | undefined {
+	if (/\s/u.test(token) || !token.includes('/') || token.includes('://')) return undefined
+	const stop = token.search(PLACEHOLDER)
+	const cut = (stop === -1 ? token : token.slice(0, stop)).replace(/^\.\//u, '')
+	const path = cut.replace(/\/+$/u, '')
+	if (path === '' || /^(?:\/|~|\.\.(?:\/|$)|-|[A-Za-z]:)/u.test(path) || path.includes('\\')) {
+		return undefined
+	}
+	return { path, directory: cut.endsWith('/'), prefix: stop === -1 ? undefined : cut }
+}
+
+function listFindings(file: string): readonly Finding[] {
+	const lines = readFileSync(file, 'utf8').split(/\r\n|\n/u)
+	return lines.flatMap((text, index) => {
+		const line = index + 1
+		const machine = MACHINE_PATH.test(text) ? [{ file, line, citation: undefined }] : []
+		const cited = [...text.matchAll(BACKTICKED)].flatMap((match) => {
+			const citation = readCitation(match[1] ?? '')
+			return citation === undefined ? [] : [{ file, line, citation }]
+		})
+		return [...machine, ...cited]
+	})
+}
+
+function probeOf(citation: Citation): string {
+	return citation.directory ? `${citation.path}/` : citation.path
+}
+
+// A citation is covered when git tracks the path, a file beneath it, or a file its glob prefix opens.
+function isCovered(citation: Citation, tracked: readonly string[]): boolean {
+	return tracked.some(
+		(path) =>
+			path === citation.path ||
+			path.startsWith(`${citation.path}/`) ||
+			(citation.prefix !== undefined && path.startsWith(citation.prefix)),
+	)
+}
+
+function reportCitations(): readonly string[] {
+	if (!existsSync('.orkestrel')) return []
+	const findings = listFiles('.orkestrel', NOTHING_SKIPPED)
+		.map((file) => file.path)
+		.filter((path) => /\.md$/iu.test(path))
+		.sort()
+		.flatMap((path) => listFindings(path))
+	const probes = new Set<string>()
+	for (const finding of findings) {
+		if (finding.citation !== undefined) probes.add(probeOf(finding.citation))
+	}
+	const ignored = readIgnored([...probes])
+	const tracked = ignored.size === 0 ? [] : listTracked([])
+	const seen = new Set<string>()
+	const lines: string[] = []
+	for (const { file, line, citation } of findings) {
+		const text =
+			citation === undefined
+				? 'names a machine path'
+				: ignored.has(probeOf(citation)) && !isCovered(citation, tracked)
+					? `cites ignored path ${citation.path}`
+					: undefined
+		if (text === undefined) continue
+		const key = `${file}:${line} ${text}`
+		if (seen.has(key)) continue
+		seen.add(key)
+		lines.push(`sweep: ${key}`)
+	}
+	return lines
+}
+
 function runReport(): number {
 	for (const directory of [...LAUNCH_DIRECTORIES, ...listCampaignDirectories()]) {
 		const line = reportDirectory(directory)
@@ -75,20 +199,26 @@ function runReport(): number {
 	}
 	const files = reportCampaignFiles()
 	if (files !== undefined) console.log(files)
+	for (const line of reportCitations()) console.log(line)
 	return 0
 }
 
 function runSweep(thresholdMinutes: number): number {
 	const now = Date.now()
 	const present = LAUNCH_DIRECTORIES.filter((directory) => existsSync(directory))
+	const tracked = new Set(listTracked(LAUNCH_DIRECTORIES))
 	const files = present.flatMap((directory) => listFiles(directory, NOTHING_SKIPPED))
-	if (files.some((file) => now - file.modified < RECENT_MS)) {
+	if (files.some((file) => !tracked.has(file.path) && now - file.modified < RECENT_MS)) {
 		console.error('sweep: a launch file changed within the last 2 minutes; refusing to delete')
 		return 2
 	}
 	const cutoff = now - thresholdMinutes * 60_000
 	for (const file of files) {
 		if (file.modified > cutoff) continue
+		if (tracked.has(file.path)) {
+			console.log(`sweep: kept tracked ${file.path}`)
+			continue
+		}
 		rmSync(file.path, { force: true })
 		console.log(`sweep: deleted ${file.path}`)
 	}
@@ -111,11 +241,21 @@ function runUnit(unit: string | undefined, remove: boolean): number {
 		return 64
 	}
 	const files = listUnitFiles(unit)
-	if (remove && files.some((file) => Date.now() - file.modified < RECENT_MS)) {
+	const tracked = new Set(listTracked(LAUNCH_DIRECTORIES))
+	if (
+		remove &&
+		files.some((file) => !tracked.has(file.path) && Date.now() - file.modified < RECENT_MS)
+	) {
 		console.error(`sweep: a file of ${unit} changed within the last 2 minutes; refusing to delete`)
 		return 2
 	}
 	for (const file of files) {
+		if (tracked.has(file.path)) {
+			console.log(
+				remove ? `sweep: kept tracked ${file.path}` : `sweep: found ${file.path} (tracked)`,
+			)
+			continue
+		}
 		if (remove) rmSync(file.path, { force: true })
 		console.log(`sweep: ${remove ? 'deleted' : 'found'} ${file.path}`)
 	}

package/dist/host/agents/skills/orkestrel-parallel/SKILL.md

@@ -1,72 +1,139 @@
 ---
 name: orkestrel-parallel
 description: >-
-  Run several writer lanes in one checkout at the same time, coordinated by messages: writers edit owned regions in phases, one runner lane owns every test and check process, and the Orchestrator rules and mediates. Use when a campaign has three or more units whose files are mostly disjoint and whose shared files are a few kind files, guides, or entry tests. Do not use it when two units rewrite the same region, when a unit needs a quiet tree for a measurement, or when the harness gives lanes no shared file system or no message channel that wakes an idle lane.
+  Run parallel work: lanes inside one session (subagents, child tasks, background commands) and peer sessions that share a checkout, a machine, or an execution lane. Use when units can progress in parallel, when another session works on the same machine or checkout, or before the first lane on a harness. Bound the host, keep lanes visible, coordinate writers through messages with one runner for checks, and hand a shared execution lane over in one message. Each harness page records its mechanics and quirks; a harness with no page carries no writer or runner lane until its bring-up questions are answered on one.
 ---
 
 # Parallel lanes
 
-## Lanes
+## Choose the scope
 
-| Lane               | Role                                                                                               | Owns                                                                                                                  | Never                                                |
-| ------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Orchestrator       | the harness's own engine                                                                           | the protocol, the roster, launches, rulings, holds, acceptance, commits                                               | delegates acceptance                                 |
-| `runner`           | `verifier` on the native small engine                                                              | every test, typecheck, lint, format, build, and citation process; its log, run files, and result files under `coord/` | writes outside `coord/`; runs an unrequested command |
-| writer (`w<unit>`) | `builder`, `astra`, or `opus` by `.agents/orchestration.md` § Routing                              | its owned files, its owned regions of shared files, and its log                                                       | runs a test, check, lint, format, or build process   |
-| reviewer           | `analyst` or `reviewer`, independent of the lane's writer per `.agents/orchestration.md` § Engines | a read-only verdict on the work the size gate sends it                                                                | edits, writes, runs, or messages                     |
+| Scope              | Lanes                                                                                          | Coordinate through                                                                                        |
+| ------------------ | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Within one session | subagents, child tasks, and background commands the session launches                           | launch results and completion notices                                                                     |
+| 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 |
 
-- Run at most three writers and one runner. Keep every live lane, reviewers included, inside the harness's concurrency limit (`references/harnesses.md`), and queue a lane that does not fit.
-- Before launch, assign every file region to exactly one writer. A shared file is owned by region (a doc block, a table, a guide section, a list entry), never as a whole.
+- 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.
+- Apply `.agents/orchestration.md` for routing, session reuse, consultation, independence, and acceptance.
 
-## Set up
+## Bound the host
 
-1. Commit the accepted state; every lane starts from one commit.
-2. Write `tmp/units/<round>/coord/protocol.md`: the path of this skill, the round's lanes, each writer's owned files and regions, and each writer's acceptance commands. Write `coord/roster.md` (lane, role, address, Orchestrator address). Create `coord/results/` and `coord/runs/`.
-3. Launch the runner first. Its first turn logs `ready` with its address and ends.
-4. Launch the writers one at a time. Fill each roster row from its launch result; after launch, send each lane that messages peers their addresses.
-5. For a lane already running, send one in-flight message naming the protocol, its lane name, its log, and its next request number.
+The host budget counts every lane on the machine: this session's, each peer session's, and the Orchestrator's own commands.
 
-## Channels
+- 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.
+- Count running lanes and owned test processes at each launch.
+- 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.
+- Find the cause of an interrupted run before relaunching it.
+- 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.
+- While a timing or live-model measurement runs, start no other test, build, or model work on the host.
 
-- File channel: each writer and the runner append only to their own log, `coord/<lane>.md`, one line per event: `<lane> | <request or phase> | <kind> | <text>`. Never write another lane's log. A reviewer returns its verdict to the Orchestrator and writes nothing.
-- Push channel (`references/harnesses.md`): requests queue to the runner one turn each, in arrival order; replies and rulings join the receiver's running turn or start one.
-- Number requests from 1 per lane across the whole round, fix units included, and never reuse a number.
-- Results: the runner writes each result under a temporary name in `coord/results/`, renames it to `coord/results/<lane>-<n>.md` when it is complete, then replies. A waiting writer polls for that file; a lost message does not stall it.
-- Request format:
+## Keep lanes visible
 
-```
-REQUEST <lane>-<n>
-from: <lane> <address>
-commands:
-1. <exact command>
-expect: <red or green per command, with case names>
-```
+- Launch every lane through the channel where the user can see it and stop it; the harness page's Visibility row names that channel. Run a hidden direct CLI only as a capped command inside a visible lane.
+- Report each lane's role, engine, and objective at launch, and its result or failure when it returns.
+
+## Assign lanes
 
-- Escalation: send the Orchestrator `ESCALATE <lane>: expected, found, evidence, proposed action`. Continue the work the question does not block. The ruling arrives in your turn; record any scope extension in your report.
-- A writer can message another writer a cross-lane fact (a line it added, a window it opens). Rulings come only from the Orchestrator.
+| Lane         | Responsibility                                                   | Write boundary                                                        |
+| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Orchestrator | Own the protocol, roster, scope, rulings, holds, and acceptance. | Assigned coordination records and serial integration.                 |
+| Runner       | Run requested tests, checks, and builds as the verifier.         | Assigned evidence and declared command outputs; never source repairs. |
+| Writer       | Implement its bounded unit under its assigned role.              | Owned files and regions, plus its own log.                            |
+| Reviewer     | Independently assess the subject the size gate names.            | None; return the verdict to the Orchestrator.                         |
 
-## Writers
+- Keep active lanes within the harness limit and § Bound the host. Reserve capacity for the runner; queue work that does not fit.
+- Assign every editable region to one writer. Name shared regions by their declarations or sections. Serialize units that rewrite the same region.
+- Choose each lane's channel from its harness page; the page owns start, continuation, wake, and tracking.
 
-- Work in phases and log each: `types` (types and API docs), `red` (failing-first cases, then a red-run request), `source` (the change, then a green-run request), `docs` (guide sentences).
-- In a shared file, edit small, complete hunks inside your owned regions. Re-read the region immediately before each patch, never rewrite a whole file, and leave every hunk syntactically complete. When a patch fails on changed context, re-read and re-apply.
-- Request every test, check, lint, format, and build process from the runner. Read-only shell and search commands stay yours.
-- Run no formatter. Fix a format finding by hand; when the finding names only a file, ask the Orchestrator for the exact hunk.
-- Before a temporary mutation (a mutation proof), ask the runner to hold unrelated runs and each lane that owns a region of the mutated file to hold its edits, and mutate only after each has logged `held`. Restore the exact text, confirm with `git diff`, log `restored`, and tell them.
-- When done and green, log `done`, send the runner `FINAL <lane>`, write your report, and end your task.
+## Prepare the round
 
-## Runner
+1. Commit the accepted baseline before a writing dispatch.
+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.
+3. Write `coord/roster.md` with each lane's roster fields per `.agents/orchestration.md` § Sessions and consultation. Create `coord/results/` and `coord/runs/`.
+4. Resume a suitable runner or launch one. Require its ready acknowledgment, then let its idle turn end.
+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.
+6. When adopting a running lane, send the protocol, ownership, log path, and next request number. Require acknowledgment before coordinated work begins.
 
-- Before each command, wait until no test or typecheck process runs in this checkout, excluding editor language services. Bound the wait by the request's expected run time. When any conflicting process exceeds that budget, report its recorded ownership, process id, and command line to the Orchestrator and suspend the request for a ruling. Never kill a process yourself. For a capped run, have the Orchestrator apply the `orkestrel-dispatch` skill's launch reference § Kill and relaunch before releasing the affected files or starting another command.
-- Launch each command through `node .agents/skills/orkestrel-dispatch/scripts/launch.ts` under a cap sized from prior runs, with `--journal coord/runs/<lane>-<n>-<k>.txt` and `--errors coord/runs/<lane>-<n>-<k>.err`, and log the process id it prints. When the shell returns before the launcher ends, resume its tracked shell session until the launcher exits, then read both files and require the terminal exit record. Track descendant process ids while their parent lives, and confirm that the command and its descendants have ended before publishing completion; otherwise escalate under the preceding wait rule.
-- Report each finding only to the lane that owns its file.
-- Serve the commands each writer's acceptance criteria name, plus the standing list: the root typecheck, the scoped typecheck, the guide parity check, the package entry test, and lint or format checks over paths the writer names. Run each read-only; none writes the tree.
-- After every writer's current `FINAL` has arrived, wait for the Orchestrator's closing request naming a unique gate number and confirming acknowledged write holds. Run the root typecheck, scoped typecheck, every acceptance test file alone, the guide parity check, and lint and format checks over every path `git status --porcelain` lists. Publish the complete result atomically as `coord/results/closing-<k>.md`, reply with that gate number, and end your task.
+## Exchange requests and results
 
-## Orchestrator
+- Append only to your own `coord/<lane>.md` log: `<lane> | <request or phase> | <kind> | <text>`. Reviewers write no log.
+- Number requests monotonically per lane across continuations and fixes. Preserve earlier requests and results.
+- Send each request through the wake-capable channel in the request shape that closes this section.
+- 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.
+- 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.
+- Escalate per `.agents/orchestration.md` § Deviation protocol. Continue independent work. Share cross-lane facts directly; only the Orchestrator changes scope or rules on acceptance.
+- 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.
+- 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.
+
+Use this request shape:
+
+```text
+REQUEST <lane>-<request>
+from: <lane> <address>
+source: <commit and changed input identity>
+inputs: <files or bounded population read by the commands>
+holds: <affected owners and exclusive resources>
+commands:
+1. <exact command>
+expect: <red or green, named cases, required artifact>
+```
 
-- Before ruling on an escalation, reproduce its evidence at its cited lines. Bound every ruling: what to change, what to leave.
-- When a format check names only a file, inspect the file and send the writer the exact formatting hunk. After the writer applies it, request a read-only format check from the runner.
-- Run the review `.agents/orchestration.md` § Size gate names, and supply its diff and status. A unit's review can start read-only when its lane logs `done`, while the others write; a campaign's `orkestrel-falsify` round runs on the integrated result after the closing gate.
-- Before resuming a writer for a fix unit, send the runner that lane's `FINAL` invalidation and wait for acknowledgment; every other lane's `FINAL` stands. Follow `references/harnesses.md` to resume the writer's lane or dispatch its successor. If a closing gate is active, keep the reopened writer read-only until that gate completes.
-- Before requesting a closing gate, obtain write-hold acknowledgments from every live writer and hold your own source edits. Allocate a gate number never used earlier in the round. Keep those holds until the matching complete result is published. After a fix unit, request another gate covering the affected checks and acceptance tests.
-- After the last green gate and the review the size gate names, commit. When shared files mix several units' hunks, commit the batch once and name each unit, its engine, and each fix unit in the message.
+## Implement in phases
+
+- Log the applicable phases: types, failing proof, source, and documentation. Request the corresponding checks from the runner.
+- Read a shared region immediately before each small, syntactically complete patch. On a context mismatch, reread and reapply only the owned hunk.
+- Keep read-only shell searches within § Bound the host. Send every test, check, lint, format, and build request to the runner.
+- Run no formatter. Apply the exact formatting hunk the Orchestrator supplies, then request a read-only format check.
+- 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.
+- 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.
+
+## Run evidence commands
+
+- 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.
+- 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.
+- 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.
+- State in each long command's request which line is its terminal record; that line ends the wait.
+- 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.
+- 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.
+- 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.
+- 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.
+- 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.
+
+## Integrate and close
+
+- Before ruling on an escalation, inspect its cited evidence. Bound the ruling to the changed claim and affected owners.
+- When the format check reports only a filename, inspect the difference and send the writer the exact hunk.
+- 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.
+- 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.
+- 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.
+- Commit after the required gates and review pass. When shared hunks form one integration, commit the batch and identify its units and fixes.
+
+## Share an execution lane between sessions
+
+Apply this section when two sessions on one machine share the tests, checks, builds, and captures the host can run at once.
+
+- One session runs process-running commands at a time. Ask the holder for the lane in one message; the holder hands it over in one message as soon as its running command exits. Silence is no handover.
+- While another session holds the lane, edit your own files, read, and queue your commands.
+- Hand the lane over by naming the last command's exit and that none of your processes still runs. Set no clock windows and send no per-command acknowledgments.
+- Record contention from another session as a host limit, not a test failure. Rerun the interrupted unit alone after the window clears.
+- When the user stops work, send the stop to every affected session. Withdraw queued work by its id and preserve finished evidence.
+- When no message channel reaches a peer session, coordinate through one tracked record holding owned paths and a dated log. Read its latest entry before each unit, log each landing, and delete the record when the shared work closes.
+- A session that finds another session's hand-off record without the user's go-ahead reads it for context only.
+
+## Bring up a harness
+
+Answer each question on the harness's page under `references/`, from measurement on the host, before the harness carries a writer or runner lane:
+
+1. Start: how does a lane start, and which role, model, and options does it accept?
+2. Continue: how does an idle lane resume with its context, and what makes a resume valid?
+3. Wake versus deliver: which send wakes an idle lane, and which only delivers?
+4. Track: which identities must be retained (task, session, thread, process), and which change between launches?
+5. Background: how does a long command run, what is its cap, and what happens at the cap and when the shell yields early?
+6. Isolation: does a lane share the checkout, and how does it get its own?
+7. Tools: which tools does a lane hold (shell, file write, messaging), and which actions does the harness refuse?
+8. Limits: what happens to running lanes at a usage limit and after an idle period?
+9. Host effects: does a lane's shell open windows or leave processes behind, and where does each shell call start?
+10. Capability map: which engine serves each capability of `.agents/orchestration.md` § Roles? Record the map where that section's bullets direct.
+11. Visibility: which launch channel shows the lane to the user, and can the user stop it there?
+
+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.

package/dist/host/agents/skills/orkestrel-parallel/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Orkestrel Parallel'
-  short_description: 'Coordinate writer lanes and one runner in a shared checkout'
-  default_prompt: 'Use $orkestrel-parallel to coordinate writers in one checkout with owned regions, queued checks, and Orchestrator rulings.'
+  short_description: 'Run parallel lanes and peer sessions within one host budget'
+  default_prompt: 'Use $orkestrel-parallel to run lanes in one session or across sessions with a host budget, visible lanes, owned regions, queued checks, and Orchestrator rulings.'

package/dist/host/agents/skills/orkestrel-parallel/references/claude.md

@@ -0,0 +1,32 @@
+# Claude Code as a lane host
+
+Lanes that Claude Code starts in its own session. `.claude/AGENTS.md` owns loading, models, cache, and wiring; `.agents/transports/claude-cli.md` owns the Claude CLI as a bench; `.agents/platforms/` owns the host shell.
+
+## Mechanics
+
+| Question            | Claude Code                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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. |
+| 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.                                   |
+| Wake versus deliver | A finished subagent, Workflow, or background command wakes the session with a notification.                                                                                                                                                                                                                                                                                                                                                        |
+| 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.                                                                                                                                            |
+| 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.                                                                                                                                                                                                                 |
+| Isolation           | Agents share the session's checkout; `isolation: worktree` gives one agent its own worktree.                                                                                                                                                                                                                                                                                                                                                       |
+| 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.                                                                                                                                                                                                     |
+| Limits              | At the account's usage limit, running agents and Workflow agents stop mid-run and keep the edits they made.                                                                                                                                                                                                                                                                                                                                        |
+| 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).                                                                                                                                                                                                                                                                           |
+| 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.                                                                                                                                                                                                           |
+| Capability map      | `.agents/orchestration.md` § Roles, Claude column; `.claude/AGENTS.md` § Models owns the aliases.                                                                                                                                                                                                                                                                                                                                                  |
+
+## Quirks
+
+- When independent review or a blind design round needs an agent, create it in a clean context on its assigned model; never `fork`, which inherits the session's model and context.
+- When a unit needs continuation, start a named custom role, never a one-shot `Explore` or `Plan` agent.
+- When a Workflow starts, record its `scriptPath` and `runId` before doing anything else. When a usage limit stops it (2026-10-21), launch no further lane, do independent hand work until the reset, then resume with `resumeFromRunId` rather than relaunching.
+- When a usage limit stops a writing agent, relaunch it from the edits it left in its checkout (2026-10-15 and 2026-10-16).
+- When an in-process unit must build, test, or run gates, confirm its shell first; otherwise give it edits only and run its command list through a lane that holds a shell.
+- When an in-process agent must produce a report, check its tools first; when the harness refuses its file write, brief the agent to return the report as text, and the Orchestrator files it.
+- When an agent works outside the session root, give it absolute paths, and check the root's `git status` for strays after it returns.
+- When read-only fan-out runs on a host where child CLIs open windows, prefer in-process agents and Workflow nodes.
+- 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.
+- 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).

package/dist/host/agents/skills/orkestrel-parallel/references/codex.md

@@ -0,0 +1,28 @@
+# Codex as a lane host
+
+Native Codex agents, and Codex lanes another harness hosts. `.codex/config.toml` owns loading and roles; `.agents/transports/codex.md` owns the Codex CLI as a bench; `.agents/platforms/` owns the host shell.
+
+## Mechanics
+
+| Question            | Codex                                                                                                                                                                                               |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Start               | A native Codex agent when it supports the selected model and no model options are requested or inherited; otherwise the hosting harness's child-task channel (`references/t3.md`) or the CLI bench. |
+| Continue            | `followup_task` resumes an idle native agent. A CLI bench resumes with its recorded session's resume command.                                                                                       |
+| Wake versus deliver | `followup_task` wakes an idle agent; `send_message` delivers information and wakes no idle agent.                                                                                                   |
+| Track               | The native agent id or the CLI session id, kept apart from a long command's shell session and process ids.                                                                                          |
+| Background          | The shell tool yields after a short interval and leaves the command running (about 30 seconds on `npm run check`, 2026-10-22). It takes a yield interval and no timeout.                            |
+| Isolation           | Lanes share the checkout unless the host harness creates a worktree.                                                                                                                                |
+| Tools               | The sandbox mode decides shell access by host; `.agents/transports/codex.md` § Sandbox by host owns it.                                                                                             |
+| Limits              | At the account's usage limit, a run ends with a `turn.failed` event that names the reset time, and later launches fail until then; record the bench dark and its reset time.                        |
+| Host effects        | Codex lanes leaked no console host beside a leaking Cursor lane (2026-10-19).                                                                                                                       |
+| Visibility          | A CLI bench is hidden; run it only as a capped command inside a visible lane. Not measured for a native agent.                                                                                      |
+| Capability map      | `.agents/orchestration.md` § Roles, Codex column.                                                                                                                                                   |
+
+## Quirks
+
+- When a Codex lane runs a long command, brief the yield fallback before launch: the longest yield interval, output to a file, process-list reads until the tracked command exits, and no kill. The lane cannot set a timeout; brief it to proceed without asking for one.
+- 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).
+- 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).
+- 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.
+- 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`).
+- 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.

package/dist/host/agents/skills/orkestrel-parallel/references/cursor.md

@@ -0,0 +1,29 @@
+# Cursor as a lane host
+
+Cursor lanes, through the Cursor CLI or a hosting harness. `.cursor/rules/orchestration.mdc` owns loading; `.agents/transports/cursor.md` owns the Cursor CLI as a bench; `.agents/platforms/` owns the host shell.
+
+## Mechanics
+
+| Question            | Cursor                                                                                                                                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Start               | The CLI bench per `.agents/transports/cursor.md`, or the hosting harness's child-task channel (`references/t3.md`).                                                                                                 |
+| 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.                                               |
+| Wake versus deliver | No peer-message wake channel is demonstrated.                                                                                                                                                                       |
+| Track               | The session id from the `init` event and the journal path.                                                                                                                                                          |
+| 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).                                             |
+| Isolation           | Lanes share the checkout.                                                                                                                                                                                           |
+| 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).                                                                        |
+| Limits              | At the account's usage limit, the bench reads dark; record it and use the native reader per `.agents/orchestration.md` § Benches.                                                                                   |
+| 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). |
+| Visibility          | The CLI bench is hidden; run it only as a capped command inside a visible lane.                                                                                                                                     |
+| Capability map      | Reader only: the `grok` role.                                                                                                                                                                                       |
+
+## Quirks
+
+- When a Cursor lane is briefed, forbid every shell command and give it one file in and one file out; read and search tools carry absorption work.
+- When a lane must return a long distillate, ask for bounded slices and continue the session for each; one final message was cut at 11.4 KB mid-sentence (2026-10-01).
+- When a Cursor lane runs, count console and window processes at each launch, and clear orphans only when none of your lanes is live.
+- When a lane would write source, run checks, or wait for messages, route it elsewhere; Cursor has no demonstrated wake channel.
+- When a Cursor lane's duration matters, read the harness's actual cap; a stated timeout did not stop a lane.
+- When a hosting harness launches a Cursor lane, pass no model options (`references/t3.md`).
+- When a lane needs another family's model, launch it through that family's own harness, per `.cursor/rules/orchestration.mdc`; a Claude lane through Cursor failed at launch twice (2026-10-20).

package/dist/host/agents/skills/orkestrel-parallel/references/t3.md

@@ -0,0 +1,31 @@
+# T3 as a lane host
+
+T3 hosts Claude, Codex, and Cursor lanes as app-owned child tasks of a thread, and runs top-level threads beside it. Each provider's own page adds its quirks; `.agents/platforms/` owns the host shell.
+
+## Mechanics
+
+| Question            | T3                                                                                                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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. |
+| 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.                                                |
+| 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).                                                                                                                            |
+| 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.                    |
+| 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).                                                                                                   |
+| Isolation           | `shared` uses the parent's checkout; `worktree` creates one from the parent's local commit, without uncommitted edits.                                                                                                                                    |
+| Tools               | Codex children reach `t3_thread_send`, `t3_thread_read`, and `t3_thread_wait` (probed 2026-10-22).                                                                                                                                                        |
+| 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.                                                  |
+| Host effects        | Each child's shell opened console windows on a Windows host; six concurrent children made it unusable (2026-10-21).                                                                                                                                       |
+| 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).                                                                                                |
+| Capability map      | The Claude and Codex columns of `.agents/orchestration.md` § Roles; Cursor lanes are readers.                                                                                                                                                             |
+
+## Quirks
+
+- When an independent review round starts, call `delegate_task` with a distinct `clientRequestId`, and reuse that id only to retry the same round's uncertain launch. Supply the original brief, prior findings, responses, and unresolved objections. Never continue a review round through `t3_thread_send`.
+- When an ordinary follow-up starts, use a stable `clientRequestId` and retain the returned task id beside, never in place of, the original result. A completed task and a later turn in its child thread are distinct results.
+- When a queued turn's result is needed and no notice came, read the durable result file or `task_status` with the full task id once.
+- When a launch's reply is missing or ambiguous, inspect the recorded task before retrying. A timeout on a parent wait cancels no child work.
+- When a lane must be interrupted and restarted, use `restart`; never use it as a resume. Create no ordinary top-level thread as a delegated lane.
+- When a child would launch processes beside another, get the user's go-ahead until a quiet single-lane trial passes on that host.
+- When a run must outlive the idle window, start it under `.agents/skills/orkestrel-dispatch/references/launch.md` § Launch ownership, or keep the session in its turn.
+- When delegation is refused, record the refusal and whether a child was created, then use the permitted fallback with its actual model disclosed.
+- When a Cursor lane launches, pass no model options; the registry refused `fastMode`, `reasoning_effort`, and `contextWindow` with "AI Model Not Found" (2026-10-21).

package/dist/host/agents/skills/orkestrel-publish/references/wave.md

@@ -141,7 +141,8 @@ registry copy over any staged tip, so every consumer stays red until that tip is
 
 ## Prepare a layer
 
-- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor and move the package's CI floor row with it.
+- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor.
+- When a package still carries `.github/workflows/ci.yml`, delete it in that visit; the ecosystem runs no hosted CI.
 - Before the release, rule the package's guide and source comments against `.claude/rules/writing.md` § Substitutions and reword each hit its rows name; identifiers stay.
 - Compare release packs between hosts by paths, sizes, and content hashes, and report executable-mode differences separately; a pack made on Windows records `0644` for an entry git tracks as `100755`.
 

package/dist/host/agents/templates/brief.md

@@ -4,7 +4,9 @@ Fill every section. Write `none` in an empty one. Replace each `UPPER_SNAKE_CASE
 
 ## Role and engine
 
-ROLE on ENGINE, reached as TRANSPORT. Executor: NATIVE_SUBAGENT | BENCH_ENGINE | BRIDGE_DRIVER.
+ROLE on ENGINE with MODEL_OPTIONS, reached as TRANSPORT. Executor: NATIVE_SUBAGENT | BENCH_ENGINE | BRIDGE_DRIVER.
+
+**Continuity.** Resume SESSION_ID for RELATED_RESPONSIBILITY, or start fresh because REASON, per `.agents/orchestration.md` § Sessions and consultation. On a resume, name PRIOR_BRIEF_AND_RESULT, CHANGED_FACTS, and SOURCE_IDENTITY.
 
 ## Objective
 
@@ -28,7 +30,7 @@ UNKNOWN and how the unit reports it.
 - **Shared (report-only).** FILES; return an exact patch.
 - **Off-limits.** FILES. Never list `tmp/probes/` here.
 - **Made false by this change.** FILES, derived by running the suite or by a named search bound.
-- **Tools and limits.** ALLOWED_TOOLS; scoped validation only; no tree-wide mutating command.
+- **Tools and limits.** ALLOWED_TOOLS; scoped validation only; no tree-wide source-mutating command. For a verifier, declare each permitted output path per `.agents/orchestration.md` § Permission floor.
 
 ## Execution