@hecer/yoke 1.3.0 → 1.4.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Cross-agent coding harness: one curated skill canon (TDD, brainstorming, plans, reviews, shipping, design verification) plus mechanical safety gates and an autonomous loop via the yoke CLI.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Cross-agent coding discipline, mechanical gates, and release workflows",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.4.0 — 2026-08-15
+
+### Added
+- `yoke loop run --parallel=N` now executes dependency-ready, non-colliding stories through real provider subprocess workers, isolated worktrees, leased claims, and a FIFO integration queue with fresh integrated-system gates.
+- Reference-driven quality declarations can collect screenshots, files, command output, or benchmark results and run a schema-validated blind critic with bounded repair rounds, elapsed-time limits, blocking or advisory policy, and retained proof.
+- `--candidates=N` can fan out up to five isolated implementations, discard mechanically red candidates, select one green candidate through identity-blind pairwise comparison, and preserve selected/loser evidence before cleanup.
+- Loop status now exposes dispatcher, worker, integrator, candidate lifecycle, worktree, queue, integration, reopen, quality-round, repair-budget, and trusted provider/model provenance data.
+
+### Changed
+- Provider subprocesses use explicit lifecycle contracts and incarnation-aware process records so worker cancellation and cleanup target only the process tree Yoke actually started.
+- Parallel and candidate runs disable adaptive routing, honor story-level provider affinity, latch pause requests across the whole dispatcher, and rerun quality plus review after integration.
+- `yoke loop cleanup` retains Yoke worktrees unless `--remove-worktrees` is explicit, while still reaping recorded orphan runners and stale locks safely.
+
+### Fixed
+- Expired claims, worker crashes, merge conflicts, pause races, and integration failures now release ownership deterministically, retain terminal proof, and reopen stories without leaking worktrees or marking false completion.
+- Quality repair fails closed on malformed critic output, reference drift, provider/model provenance mismatch, candidate identity leakage, unavailable critics, exhausted limits, and mechanically red repairs.
+- The watchdog resolves its TypeScript loader from both source and built npm layouts on Node 20+, and read-only Codex comparisons can run in disposable candidate worktrees without weakening normal repository checks.
+
+### Security
+- Blind comparison requests expose only opaque labels and digests while binding every verdict to the trusted judge provider, model, prompt, rubric, reference, and candidate provenance.
+- Cleanup and cancellation use project-scoped leases, owner tokens, PID birth/incarnation checks, and recorded process handles rather than machine-wide process-name matching.
+
 ## 1.3.0 — 2026-08-09
 
 ### Added

package/README.md

@@ -2,8 +2,8 @@
 
 # 🐂 Yoke
 
-<!-- yoke:version:start -->1.3.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->657<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.4.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->928<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->29<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-657%20passing-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-928%20passing-brightgreen.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -25,7 +25,11 @@
 
 </div>
 
-> **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it story by story behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. If any gate is red, nothing is committed. When a story is done, there's a photo of it in `.yoke/proof/<story>/`.
+> **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
+
+Yoke 1.4 adds opt-in parallel workers and a bounded, reference-driven quality gauntlet without
+changing existing serial loop defaults. See [the 1.4 migration guide](docs/MIGRATING-TO-1.4.md)
+for the new flags, configuration, cleanup behavior, and review-verdict contract.
 
 Yoke 1.1 is safe-by-default: provider CLIs use autonomous sandbox profiles unless `--unsafe`
 is explicit; reviews require a schema-valid verdict and a different model unless
@@ -72,7 +76,7 @@ $ ls reading-app/.yoke/proof/STORY-2/
 home.png  list.png                            # photographic evidence, labelled per story
 ```
 
-Every claim in that transcript is enforced by code paths with tests behind them — 657 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
+Every claim in that transcript is enforced by code paths with tests behind them — 928 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -87,7 +91,7 @@ yoke loop on my-app && yoke loop run my-app --isolate
 # — or retrofit an existing project —
 yoke setup /path/to/project                                  # interactive: agents, graph, loop, runner, decisions, routing
 yoke validate canon                                          # sanity-check the canon
-yoke loop run /path/to/project --isolate --reviewer=codex --max=20
+yoke loop run /path/to/project --isolate --parallel=3 --reviewer=codex --max=20
 ```
 
 > Requires Node ≥ 20 and git. No global install? `node /path/to/yoke/dist/cli.js …` or `npm --prefix /path/to/yoke run yoke -- …` work too. The MCP tools (rtk, graphify/Serena, Playwright MCP) are wired by Yoke but installed separately — the generated config is a clearly-labelled, adjustable template.
@@ -156,7 +160,7 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
 | `yoke context init\|status [dir]` | Durable context layer (`PROJECT/DECISIONS/KNOWLEDGE.md`) | `0` |
-| `yoke loop on\|off\|status\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `run` is unlimited by default and `--max=N` creates an intentional batch cap; `decision` shows a critical stop, `answer` records it and resumes, `resume` retries a failed restart with the preserved safety options | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
+| `yoke loop on\|off\|status\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `run` supports `--parallel=N`, bounded reference-driven `--quality`, and blind `--candidates=N` selection; `--max=N` creates an intentional batch cap; `cleanup` retains worktrees unless `--remove-worktrees` is explicit | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
 | `yoke review [dir] [--reviewer=] [--base=] [--focus=] [--json] [--allow-self-review]` | An independent model writes a schema-valid verdict | `0` approved · `1` findings/invalid verdict · `2` no independent reviewer |
 | `yoke audit [dir] [--json]` | Dependency, high-confidence secret, and sensitive-change audit | `0` green · `1` blocking findings · `2` not runnable |
 | `yoke design-scan [dir] [--max=N] [--report]` | Static AI-slop design gate | `0` within budget · `1` over |
@@ -337,6 +341,7 @@ yoke loop run . \
   --runner=codex \               # implement with Codex…
   --reviewer=claude \            # …review with Claude (role separation)
   --isolate \                    # each story in a throwaway git worktree
+  --parallel=3 \                  # run dependency-ready, non-colliding stories concurrently
   --decision-policy=critical     # pause only for high-impact decisions; routine choices stay autonomous
 # Optional: add --max=20 only when this run should stop after a bounded batch.
 yoke loop off .                 # disable
@@ -370,6 +375,49 @@ closes the mechanical false-done paths—targeted evidence, coverage review, cle
 and integrated journeys—while the project still owns the correctness of its tests and production
 observability.
 
+### Parallel workers and the quality gauntlet
+
+`--parallel=N` dispatches dependency-ready stories concurrently. Claims carry leases, workers use
+isolated worktrees, collision areas are serialized, and only a mechanically green candidate enters
+the FIFO integration queue. Integration repeats the project gates against the merged tree; a worker
+success can never bypass a red integrated result. `yoke loop status` reports the dispatcher,
+workers, providers, worktrees, lifecycle, queue, integrations, and reopened stories.
+
+Quality is reference-driven and opt-in. Declare what one story should match:
+
+```yaml
+quality:
+  reference: { name: approved-home, source: design/home.png, kind: file }
+  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
+  rubric: Match the approved layout, hierarchy, spacing, and states.
+  policy: blocking                 # or advisory
+```
+
+Configure project defaults, then enable the gauntlet for a run:
+
+```yaml
+quality:
+  enabled: false                   # keep opt-in, or make it the project default
+  policy: blocking
+  maxRounds: 3
+  maxMinutes: 60
+  consistencyChecks: 2
+  maxParallelCandidates: 2
+  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
+  repair: { agent: claude }
+```
+
+```bash
+yoke loop run . --quality --quality-rounds=3 --quality-minutes=60
+yoke loop run . --quality --candidates=2   # blind pairwise selection; stories need quality declarations
+```
+
+The critic compares opaque candidate/reference labels, writes schema-validated provenance, and
+cannot modify the project. Blocking findings enter a bounded repair loop and rerun every mechanical
+gate; advisory findings are retained without blocking. `--quality-policy=`, `--no-quality`, and
+`--quality-unbounded` override defaults for one run. Unbounded mode is explicit and warned because
+it removes repair limits, not Yoke's watchdog, isolation, verification, or commit safety.
+
 State lives **outside the model context** — the PRD file plus git — so each iteration is fresh.
 Use `yoke change add` at any time. Its ignored append-only inbox is consumed at the next story
 boundary. A separate coverage pass must confirm that every requested outcome maps to behavioral
@@ -393,6 +441,8 @@ Every iteration emits token-free, harness-side feedback (Node console + local fi
     implementing · iteration 20 · 19/45 (42%) · updated 30s ago
     ~1h44m remaining (Ø 4m/story)
   ```
+- **Parallel + quality detail** — active workers include provider, candidate ID, worktree,
+  lifecycle, phase, quality round, and repair budget; the integrator is shown separately.
 - **`.yoke/loop.log`** — an append-only timeline of every phase transition.
 - **`--json`** — machine mode for supervisors: every status write is *also* emitted as one
   NDJSON line on stdout (`{"type":"status","state":"running","phase":"verifying",…}` — the
@@ -561,10 +611,11 @@ stale takeover is serialized by `.yoke/loop.lock.takeover`. A second invocation
 `Another loop is already running here (pid …). If that is wrong, run: yoke loop cleanup`. A lock
 whose holder process is dead is taken over automatically (with a warning).
 
-**`yoke loop cleanup [dir]`** removes what a crashed loop leaves behind: every worktree under
-`.yoke/worktrees/` (via `git worktree remove --force` + `prune` — user-created worktrees are
-never touched) and a **stale** lock file. A live lock is reported and left alone. Exits `0`
-when everything cleaned, `1` if any removal failed. If a machine/process crash leaves the cleanup
+**`yoke loop cleanup [dir]`** reaps only runner process trees recorded by this project and removes
+a stale lock. Yoke-created worktrees are **retained by default** and listed in the output; pass
+`--remove-worktrees` to remove `.yoke/worktrees/*` with `git worktree remove --force` + `prune`.
+User-created worktrees are never touched. A live lock is reported and left alone. Exits `0` when
+cleanup succeeds, `1` if any requested removal fails. If a machine/process crash leaves the cleanup
 recovery lease itself behind, an operator can run
 `yoke loop cleanup . --discard-stale-recovery`; Yoke refuses while its recorded PID is alive, and
 the force flag must not be run concurrently.
@@ -725,6 +776,7 @@ src/
   change/         # append-only change inbox · planning · independent coverage review
   retrofit/       # detect · plan · apply · planners (claude/codex/gemini) · tools
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
+  quality/        # reference collection · blind critic · bounded repair · candidate comparison
   new/            # yoke new — greenfield bootstrap
   prd/            # yoke prd draft|check — idea → stories + lint gate
   review/         # yoke review — cross-model diff gate
@@ -736,14 +788,14 @@ docs/superpowers/ # the spec and every component's implementation plan
 
 ## 🗺️ Roadmap
 
-Yoke 1.1's completed release work moved to the changelog. Remaining, explicitly scoped work
-is tracked in [`TODOS.md`](TODOS.md), including provider subprocess wiring for the tested
-parallel dispatcher, broader benchmark samples, native output schemas, and release provenance.
+Completed release work lives in the changelog. Remaining, explicitly scoped work is tracked in
+[`TODOS.md`](TODOS.md), including broader benchmark samples, native output schemas, and signed
+release provenance.
 
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (657 tests)
+npm test          # vitest (928 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/TODOS.md

@@ -1,8 +1,5 @@
 # Yoke follow-up work
 
-- Wire the tested async parallel dispatcher to provider subprocess workers. Until then the CLI
-  rejects `--parallel=N` for `N > 1`; scheduler, claims, and merge queue APIs are available
-  without claiming a CLI speed-up.
 - Add provider-native output schemas when all three CLIs expose compatible stable APIs.
 - Expand benchmark fixtures and collect multiple authenticated samples per provider/model.
 - Add signed provenance and attestations to npm and GitHub releases.

package/canon/loop/loop-spec.md

@@ -4,13 +4,21 @@ The autonomous loop is optional and toggle-able:
 
 - `yoke loop on` / `yoke loop off` — enable or disable it in `.yoke/config.yaml`.
 - `yoke loop status` — show enabled state and backlog progress.
-- `yoke loop run [--max=N] [--isolate] [--decision-policy=auto|critical]` — run until the current backlog is green or a gate blocks.
+- `yoke loop run [--max=N] [--parallel=N] [--isolate] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — run until the current backlog is green or a gate blocks.
 - `yoke change add --idea="..."` — queue a product change at any time, including while the loop is running.
 - `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop.
 
 Pass `--isolate` to implement each story in a fresh git worktree. Only a verified, committed
 story is fast-forwarded to the main tree. Pass `--review` or `--reviewer=<provider>` to require
-a separate, schema-validated review. Pass `--json` for NDJSON status on stdout.
+a separate, schema-validated review. Pass `--parallel=N` to dispatch ready, non-colliding stories
+concurrently. Pass `--json` for NDJSON status on stdout.
+
+Stories may declare a reference, candidate artifact, rubric, and blocking/advisory quality policy.
+`--quality` runs a read-only blind critic plus bounded repair before review; every repair reruns the
+mechanical gates. `--candidates=N` requires quality declarations and dispatches multiple isolated
+implementations, rejects mechanically red candidates, selects one green candidate through opaque
+pairwise handles, and retains every candidate's terminal proof before cleanup. Parallel/candidate
+runs do not combine with adaptive routing.
 
 At every story boundary, Yoke consumes at most one queued change. The configured Claude,
 Codex, or Gemini provider may propose only new stories in a separate runtime file. A fresh
@@ -21,7 +29,8 @@ stories untouched. The request stays pending on any failure or uncovered outcome
 For each story:
 
 1. Require a clean git worktree.
-2. Pick the highest-priority ready unfinished story.
+2. Pick the highest-priority ready unfinished story, or claim multiple dependency-ready stories
+   whose collision areas do not overlap when parallel dispatch is enabled.
 3. Stop the line if acceptance is empty. With `verify.requireCriteria: true`, every criterion
    must be structured. Every structured criterion, including in compatible legacy projects,
    must use a single approved test command containing its criterion ID and no shell operators.
@@ -30,16 +39,21 @@ For each story:
    material cost, compliance, or irreversible choices may pause for a human decision.
 5. Run every structured criterion's targeted commands and write
    `.yoke/proof/<story>/evidence.json`. Then run project-wide `verify.command` (or detected
-   `npm test`). Performance, audit, and independent review gates follow when configured. Any
-   failure blocks, and no proof command runs after review.
-6. Only after all gates pass, mark the story `passes: true`, log the decision, and commit
+   `npm test`). Performance and audit follow when configured. If quality is enabled, collect the
+   declared artifact, run the blind critic, and repair within the configured round/time bounds.
+   Independent review follows. Any blocking failure stops the candidate.
+6. Parallel workers enqueue green candidate commits. The integrator applies one at a time and
+   reruns mechanical gates, fresh quality, and review against the integrated tree. Failed
+   integration reopens the story and retains proof.
+7. Only after all gates pass, mark the story `passes: true`, log the decision, and commit
    atomically. A failed commit restores the PRD state.
-7. When all current stories pass, run optional `completion.command` against the integrated
+8. When all current stories pass, run optional `completion.command` against the integrated
    system. Only a green result reports `complete`; otherwise the loop blocks. This readiness
    result is ephemeral, not a release and not a freeze on future changes.
 
 A supervisor can pause the loop by creating `.yoke/loop.pause`. The running story finishes;
-the signal is consumed at the next story boundary and the process exits with code `3`.
+the dispatcher latches the signal, stops launching new workers, lets active workers reach safe
+terminal proof/cleanup, and exits with code `3` before another story is integrated.
 
 State lives outside model context: PRD, git, and the ignored `.yoke/changes/` inbox. All are
 re-read at story boundaries, so a request queued mid-run becomes additional stories without a

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.2.0
+version: 1.4.0
 agents: [claude, codex, gemini]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology }

package/dist/agents/contracts.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+export const PermissionProfileSchema = z.enum(['safe', 'unsafe', 'read-only']);
+export const ModelSelectionSchema = z.object({
+    model: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/).optional(),
+    reasoningEffort: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/).optional(),
+    nativeMultiAgent: z.boolean().optional(),
+    bare: z.boolean().optional(),
+});
+export const AgentInvocationSchema = z.object({
+    command: z.string().min(1),
+    args: z.array(z.string()),
+    input: z.string(),
+    cwd: z.string().min(1),
+});
+const ProviderTokenUsageSchema = z.object({
+    inputTokens: z.number().nonnegative(),
+    cachedInputTokens: z.number().nonnegative().optional(),
+    cacheWriteInputTokens: z.number().nonnegative().optional(),
+    outputTokens: z.number().nonnegative(),
+    reasoningOutputTokens: z.number().nonnegative().optional(),
+    totalCostUsd: z.number().nonnegative().optional(),
+    model: z.string().min(1).optional(),
+});
+export const ProviderTelemetrySchema = z.object({
+    usageAvailable: z.boolean(),
+    tokens: ProviderTokenUsageSchema.optional(),
+}).superRefine((telemetry, ctx) => {
+    if (telemetry.usageAvailable && !telemetry.tokens) {
+        ctx.addIssue({ code: 'custom', path: ['tokens'], message: 'usageAvailable telemetry requires token totals' });
+    }
+});
+const MachineRoleSchema = z.enum([
+    'route',
+    'review',
+    'quality',
+    'decomposition',
+    'candidate-selection',
+    'telemetry',
+]);
+export const MachineEnvelopeSchema = z.object({
+    schemaVersion: z.literal(1),
+    provider: AgentSchema,
+    model: z.string().min(1).optional(),
+    role: MachineRoleSchema,
+    durationMs: z.number().int().nonnegative(),
+    permissions: PermissionProfileSchema,
+    usage: ProviderTokenUsageSchema.optional(),
+    raw: z.record(z.unknown()).optional(),
+});

package/dist/agents/process-incarnation.js

@@ -0,0 +1,15 @@
+import { execFileSync } from 'node:child_process';
+const queryProcessIdentity = (command, args, options) => execFileSync(command, args, { stdio: 'pipe', ...options }).toString();
+export function processIncarnation(pid, platform = process.platform, query = queryProcessIdentity) {
+    try {
+        if (platform === 'win32') {
+            const output = query('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', '(Get-CimInstance Win32_Process -Filter "ProcessId = $env:YOKE_PROCESS_PID").CreationDate'], { env: { ...process.env, YOKE_PROCESS_PID: String(pid) } }).trim();
+            return output ? `win32:${output}` : undefined;
+        }
+        const output = query('ps', ['-o', 'lstart=', '-p', String(pid)]).trim();
+        return output ? `posix:${output}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/agents/process-record.js

@@ -0,0 +1,65 @@
+import { randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function createProviderProcessRecord(targetDir, childPid, workerId, startedAt = new Date().toISOString()) {
+    const worker = workerId?.replace(/[^A-Za-z0-9_-]/gu, '_') || 'call';
+    return {
+        path: join(targetDir, '.yoke', 'provider-processes', `${worker}-${randomUUID()}.json`),
+        version: 1,
+        owner: 'provider-process',
+        targetDir,
+        childPid,
+        startedAt,
+        ...(workerId ? { workerId } : {}),
+    };
+}
+export const filesystemProviderProcessRecordAdapter = {
+    publish(record) {
+        const directory = join(record.targetDir, '.yoke', 'provider-processes');
+        mkdirSync(directory, { recursive: true });
+        const temporary = `${record.path}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({
+            version: record.version,
+            owner: record.owner,
+            targetDir: record.targetDir,
+            childPid: record.childPid,
+            startedAt: record.startedAt,
+            ...(record.workerId ? { workerId: record.workerId } : {}),
+        }), { flag: 'wx' });
+        try {
+            linkSync(temporary, record.path);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    },
+    remove(path) {
+        rmSync(path, { force: true });
+    },
+};
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseProviderProcessRecord(value) {
+    if (!isRecord(value))
+        return null;
+    const workerId = value.workerId;
+    if (value.version !== 1 ||
+        value.owner !== 'provider-process' ||
+        typeof value.targetDir !== 'string' ||
+        typeof value.childPid !== 'number' ||
+        !Number.isInteger(value.childPid) ||
+        value.childPid <= 0 ||
+        typeof value.startedAt !== 'string' ||
+        value.startedAt.length === 0 ||
+        (workerId !== undefined && typeof workerId !== 'string'))
+        return null;
+    return {
+        version: 1,
+        owner: 'provider-process',
+        targetDir: value.targetDir,
+        childPid: value.childPid,
+        startedAt: value.startedAt,
+        ...(typeof workerId === 'string' ? { workerId } : {}),
+    };
+}

package/dist/agents/process-streams.js

@@ -0,0 +1,40 @@
+import { parseProviderTelemetry } from './telemetry.js';
+export function createBoundedOutput(limitBytes) {
+    let text = '';
+    let truncated = false;
+    return {
+        append(next) {
+            const combined = `${text}${next}`;
+            if (Buffer.byteLength(combined) <= limitBytes) {
+                text = combined;
+                return;
+            }
+            text = Buffer.from(combined).subarray(-limitBytes).toString('utf8');
+            truncated = true;
+        },
+        get text() { return text; },
+        get truncated() { return truncated; },
+    };
+}
+export function createTelemetryAccumulator(agent) {
+    let trailing = '';
+    let telemetry = { usageAvailable: false };
+    const update = (lines) => {
+        const next = parseProviderTelemetry(agent, [...lines]);
+        if (next.usageAvailable)
+            telemetry = next;
+    };
+    return {
+        append(text) {
+            const parts = `${trailing}${text}`.split(/\r?\n/u);
+            trailing = parts.pop() ?? '';
+            update(parts);
+        },
+        finish() {
+            if (trailing)
+                update([trailing]);
+            trailing = '';
+            return telemetry;
+        },
+    };
+}

package/dist/agents/process.js

@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { killProcessTreeForCleanup } from '../loop/watchdog.js';
+import { createProviderProcessRecord, filesystemProviderProcessRecordAdapter, } from './process-record.js';
+import { createBoundedOutput, createTelemetryAccumulator } from './process-streams.js';
+import { processIncarnation } from './process-incarnation.js';
+function cancellationReason(signal) {
+    return typeof signal.reason === 'string' && signal.reason.length > 0
+        ? signal.reason
+        : 'provider process cancellation requested';
+}
+export function providerSpawnOptions(invocation, platform = process.platform) {
+    const windowsCommandShim = !/[\\/]/u.test(invocation.command) || /\.(?:bat|cmd)$/iu.test(invocation.command);
+    return {
+        command: invocation.command,
+        args: invocation.args,
+        cwd: invocation.cwd,
+        shell: platform === 'win32' && windowsCommandShim,
+        detached: platform !== 'win32',
+    };
+}
+export function startProviderProcess(agent, invocation, options = {}) {
+    const spawnOptions = providerSpawnOptions(invocation);
+    const child = spawn(spawnOptions.command, [...spawnOptions.args], {
+        cwd: spawnOptions.cwd,
+        shell: spawnOptions.shell,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: spawnOptions.detached,
+    });
+    const targetDir = resolve(invocation.cwd);
+    const pid = child.pid;
+    const startedAt = pid === undefined ? `unverified:${new Date().toISOString()}` : processIncarnation(pid) ?? `unverified:${new Date().toISOString()}`;
+    const record = createProviderProcessRecord(targetDir, pid ?? 0, options.workerId, startedAt);
+    const recordAdapter = options.recordAdapter ?? filesystemProviderProcessRecordAdapter;
+    const terminateProcessTree = options.terminateProcessTree ?? ((processPid) => killProcessTreeForCleanup(processPid));
+    let recordPublished = false;
+    const stdout = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
+    const stderr = createBoundedOutput(options.outputLimitBytes ?? 1_048_576);
+    const telemetry = createTelemetryAccumulator(agent);
+    const idleTimeoutMs = options.idleTimeoutMs ?? 0;
+    const terminationGraceMs = options.terminationGraceMs ?? 5_000;
+    let termination;
+    let idleTimer;
+    let forceTimer;
+    let recordFailure;
+    let terminationConfirmed = false;
+    let settled = false;
+    let resolveCompletion = () => { };
+    const completion = new Promise(resolveCompletionValue => {
+        resolveCompletion = resolveCompletionValue;
+    });
+    const removeRecord = () => {
+        if (recordPublished)
+            recordAdapter.remove(record.path);
+    };
+    const clearTimers = () => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        if (forceTimer)
+            clearTimeout(forceTimer);
+        idleTimer = undefined;
+        forceTimer = undefined;
+    };
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimers();
+        options.signal?.removeEventListener('abort', onAbort);
+        if (!termination || terminationConfirmed)
+            removeRecord();
+        resolveCompletion(result);
+    };
+    const evidence = () => ({
+        invocation,
+        pid,
+        stdout: stdout.text,
+        stderr: stderr.text,
+        stdoutTruncated: stdout.truncated,
+        stderrTruncated: stderr.truncated,
+        telemetry: telemetry.finish(),
+    });
+    const finalize = (exitCode) => {
+        const details = evidence();
+        if (recordFailure) {
+            finish({ ...details, kind: 'spawn-failed', error: recordFailure });
+            return;
+        }
+        if (termination?.kind === 'timed-out') {
+            finish({ ...details, kind: 'timed-out', reason: termination.reason });
+            return;
+        }
+        if (termination?.kind === 'cancelled') {
+            finish({ ...details, kind: 'cancelled', reason: termination.reason });
+            return;
+        }
+        if (exitCode === 0) {
+            finish({ ...details, kind: 'succeeded', exitCode });
+            return;
+        }
+        finish({ ...details, kind: 'failed', exitCode });
+    };
+    const terminate = (next) => {
+        if (termination || settled)
+            return false;
+        termination = next;
+        if (pid !== undefined)
+            terminationConfirmed = terminateProcessTree(pid, false);
+        forceTimer = setTimeout(() => {
+            if (pid !== undefined && !settled)
+                terminationConfirmed = terminateProcessTree(pid, true);
+        }, terminationGraceMs);
+        return true;
+    };
+    const armIdleTimer = () => {
+        if (idleTimeoutMs <= 0 || termination || settled)
+            return;
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => {
+            terminate({ kind: 'timed-out', reason: 'provider process produced no output before its idle timeout' });
+        }, idleTimeoutMs);
+    };
+    const onAbort = () => {
+        if (options.signal)
+            terminate({ kind: 'cancelled', reason: cancellationReason(options.signal) });
+    };
+    const onOutput = (stream, chunk) => {
+        const text = String(chunk);
+        if (stream === 'stdout') {
+            stdout.append(text);
+            telemetry.append(text);
+        }
+        else {
+            stderr.append(text);
+        }
+        options.onOutput?.({ stream, text });
+        armIdleTimer();
+    };
+    child.stdout?.on('data', chunk => { onOutput('stdout', chunk); });
+    child.stderr?.on('data', chunk => { onOutput('stderr', chunk); });
+    child.stdin?.on('error', () => { });
+    child.on('close', code => { finalize(code); });
+    child.on('error', error => {
+        finish({ ...evidence(), kind: 'spawn-failed', error: recordFailure ?? error.message });
+    });
+    if (pid !== undefined) {
+        try {
+            recordAdapter.publish(record);
+            recordPublished = true;
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            recordFailure = `process ownership record failure: ${reason}`;
+            child.stdin?.end();
+            terminate({ kind: 'cancelled', reason: recordFailure });
+        }
+    }
+    const handle = {
+        pid,
+        invocation,
+        recordPath: record.path,
+        completion,
+        cancel(reason) {
+            return terminate({ kind: 'cancelled', reason });
+        },
+    };
+    if (recordFailure)
+        return handle;
+    child.stdin?.end(invocation.input);
+    if (options.signal?.aborted)
+        onAbort();
+    else
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+    armIdleTimer();
+    return handle;
+}