@hecer/yoke 1.2.1 → 1.4.0

package/canon/loop/loop-spec.md

@@ -1,36 +1,65 @@
 # Loop Specification (Ralph + GSD)
 
-The autonomous loop is OPTIONAL and toggle-able:
+The autonomous loop is optional and toggle-able:
 
-- `yoke loop on` / `yoke loop off` — enable/disable (recorded in `.yoke/config.yaml`, default off).
-- `yoke loop status` — show enabled state + PRD progress.
-- `yoke loop run [--max=N] [--isolate] [--decision-policy=auto|critical]` — run the loop (default cap 25 iterations).
-- `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop; answering records a human-owned, decision-file-only commit and resumes by default with the original runner, isolation, review, permission, timeout, and policy settings. `yoke loop resume` retries a restart that could not begin without weakening those settings.
+- `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] [--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 run each iteration in a fresh git worktree: the agent works on a throwaway checkout, and only a verified, committed story is fast-forwarded back into the main tree. A failed iteration never touches your working tree. Requires `.yoke/prd.yaml` to be committed to git, since the worktree is a checkout of HEAD.
+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 `--parallel=N` to dispatch ready, non-colliding stories
+concurrently. Pass `--json` for NDJSON status on stdout.
 
-Pass `--review` (or `--reviewer=<claude|codex|gemini>` for a different agent) to add a role-separated review step: after the tests pass, an independent reviewer agent must approve the change before the story is committed and marked done. A rejection blocks the story (no commit). The reviewer is a fresh agent pass — the implementer never reviews its own work.
+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.
 
-Pass `--json` for machine mode: each status transition is emitted as one NDJSON line on stdout (the `.yoke/loop-status.json` shape, tagged `"type":"status"`) instead of the human narrative, so a supervisor can consume the stream instead of polling the file.
+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
+coverage-review pass must account for every distinct requested outcome before Yoke validates
+strict criterion evidence, appends the stories itself, commits only the PRD, and leaves existing
+stories untouched. The request stays pending on any failure or uncovered outcome.
 
-When enabled and run, each iteration:
+For each story:
 
-1. Pre-dispatch gate: the git worktree must be clean, else `blocked`.
-2. Pick the highest-priority unfinished PRD story (`.yoke/prd.yaml`).
-3. Stop-the-Line gate: the story must have acceptance criteria, else `blocked`.
-4. Run a fresh agent to implement ONE story. Runner precedence is explicit `--runner`, configured `runner.agent`, active agent host, then the first configured agent. The loop refuses to start if that CLI is not installed.
-   With `decisionPolicy: auto`, routine ambiguity is resolved from the approved plan and project conventions. With `critical`, only high-impact architecture, security/privacy, destructive data, material-cost, compliance, or irreversible choices may produce `.yoke/decision-request.yaml`; the loop validates its bounded single-line fields, unique options, and active story ID, blocks before verify, and preserves it for `yoke loop answer`.
-5. Run the project's verify command (config `verify.command`, or detected `npm test`).
-   **Verify is the source of truth** — the agent's exit code is advisory, so a spurious
-   non-zero exit (e.g. a Windows `.cmd` wrapper) cannot block a story whose tests are green.
-   A failing verify is retried up to `verify.retries` times (default 1) so a transient flake
-   self-heals; a real failure still fails. Only if verify passes is the story marked
-   `passes: true`, committed atomically, and a decision logged. If verify fails: `blocked`.
-6. Stop when all stories `passes: true` (`complete`), or the iteration cap is reached (`cap-reached`).
+1. Require a clean git worktree.
+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.
+4. Run a fresh configured provider to implement exactly one story. Under the `critical`
+   decision policy, only high-impact architecture, security/privacy, destructive data,
+   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 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.
+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`: at the next story boundary (before the next story is selected — the running story always finishes) the loop consumes the file, records `paused` in the status file and log, and exits with code `3`. Running `yoke loop run` again resumes.
+A supervisor can pause the loop by creating `.yoke/loop.pause`. The running story finishes;
+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 the model context: the PRD file + git. The agent runner is pluggable. The PRD is re-read from disk at every story boundary, so stories appended to `.yoke/prd.yaml` mid-run are picked up at the next iteration without a restart.
+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
+restart.
 
 ## Limitations
-- The loop verifies via the project's test command and an optional agent review; it has no formal merge-queue or multi-reviewer quorum.
+
+Yoke cannot infer the correct end-to-end journey command. Projects that need integrated
+readiness must configure `completion.command`, for example a Playwright journey suite.

package/canon/loop/prd.schema.md

@@ -1,6 +1,6 @@
 # PRD Schema
 
-The loop is driven by a versioned PRD file. Each story:
+The loop is driven by a continuous PRD backlog. Each story:
 
 ```yaml
 - id: STORY-1
@@ -9,11 +9,35 @@ The loop is driven by a versioned PRD file. Each story:
   needs: []              # optional dependency IDs; no unknown IDs, self-links, or cycles
   area: api              # optional collision domain for parallel scheduling
   agent: codex           # optional claude|codex|gemini affinity
-  acceptance:            # Definition of Done (required before implementation)
-    - The endpoint returns 200 for a valid request.
-  passes: false          # set true only when acceptance is met and tests are green
+  acceptance:
+    - id: valid-request-returns-200
+      text: The endpoint returns 200 for a valid request.
+      verify: [npm run test:valid-request-returns-200]
+    - id: invalid-request-returns-400
+      text: The endpoint returns 400 for an invalid request.
+      verify: [npm run test:invalid-request-returns-400]
+  passes: false          # Yoke-owned; true only after all gates pass and the commit lands
 ```
 
-Stop condition: every story has `passes: true`.
+Each new story has 2–5 acceptance criteria. Every criterion has a stable `id`, observable
+behavioral `text`, and one or more executable `verify` commands. Each entry is one approved test
+command, contains the normalized criterion ID, and contains no shell control operator. Yoke runs and records each criterion separately in
+`.yoke/proof/<story>/evidence.json`; a broad green suite cannot stand in for an untested
+criterion. Legacy string criteria remain readable, but `verify.requireCriteria: true` blocks
+them.
 
-Stories without `needs`, `area`, or `agent` retain the serial pre-1.0 behavior. A story is ready only when every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously active areas, and uses `agent` as an affinity hint.
+The binding is deliberately mechanical, not an oracle for product meaning: Yoke can require a
+criterion-targeted test command and a separate coverage review, but it cannot prove that arbitrary
+test code faithfully models the real world. Critical cross-component behavior therefore also
+belongs in a trusted `completion.command` journey suite.
+
+`sourceChange` is an optional Yoke-owned request ID. The change inbox uses it to append new
+stories idempotently; authors normally omit it.
+
+Stories without `needs`, `area`, or `agent` retain serial behavior. A story is ready only when
+every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously
+active areas, and uses `agent` as an affinity hint.
+
+The backlog is continuous, not a release object. A momentary stop condition is every story
+having `passes: true`; if configured, `completion.command` must then prove the integrated
+system before the loop reports `complete`.

package/canon/manifest.yaml

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

package/canon/skills/authoring-prd/SKILL.md

@@ -1,38 +1,27 @@
 ---
 name: authoring-prd
-description: Use when turning a product idea into a loop-ready .yoke/prd.yaml — slice the idea into small, independently shippable stories with testable behavioral acceptance criteria; greenfield STORY-1 scaffolds the project and wires verify.command.
+description: Use when turning a product idea or change into a loop-ready continuous backlog with small stories and executable behavioral evidence.
 ---
 
 # Authoring a PRD
 
-The Yoke loop is only as good as its stories. Bad stories ("build the app") stall it;
-good stories (small, testable, ordered) let it run overnight.
+The Yoke loop is only as good as its stories. Keep the backlog continuous: new requests become
+new stories; they do not require a release object.
 
 ## Story rules
 
-1. **One iteration per story.** If you can't imagine an agent finishing it in one sitting,
-   split it. Prefer 5-12 stories over 3 epics.
-2. **Independently shippable.** After any story, the project builds and tests pass.
-3. **Acceptance = observable behavior**, never implementation:
-   - Good: "GET /health returns 200", "the CLI prints the sum of its arguments"
-   - Bad: "create a HealthController class", "use express"
-   2-5 criteria per story. Each must be checkable by a test or a command.
-4. **Dense priorities from 1**; lower runs first. Order by dependency, then by risk.
-5. **Greenfield: STORY-1 scaffolds.** Project skeleton + runnable test suite + a criterion
-   that the verify command (`verify.command` in `.yoke/config.yaml`) exits 0. Every later
-   story stands on a green pipeline.
-6. **Performance requirements are acceptance criteria — with numbers.** "Should be fast" is
-   a vibe the loop cannot gate; "imports 1M rows in < 2s (asserted by the bench test)" is a
-   criterion. If the whole project has a budget, wire `perf.command` in `.yoke/config.yaml`
-   (see the `performance` skill) instead of repeating it per story.
-7. **Ask everything now.** Clarifying questions belong in this planning round — a loop run
-   is unattended. A criterion that still contains `TBD` or another placeholder is not
-   loop-ready, and `yoke prd check` rejects it. During implementation,
-   `loop.decisionPolicy: auto` resolves routine ambiguity; `critical` pauses only for
-   high-impact choices and resumes after `yoke loop answer` records the answer.
-8. **Model real dependencies.** Add `needs` only for hard prerequisites, `area` for files or
-   subsystems that must not be edited concurrently, and `agent` only as an affinity hint.
-   Dependency IDs must exist; self-dependencies and cycles are invalid.
+1. One iteration per story. Prefer 5–12 small stories over a few epics.
+2. Each story leaves the project buildable and testable.
+3. Acceptance describes observable behavior, never implementation. Give each of 2–5 criteria
+   a stable `id`, behavioral `text`, and `verify` list with one or more real commands proving
+   that exact outcome.
+4. Use dense priorities from 1; order by dependency, then risk.
+5. Greenfield `STORY-1` creates the skeleton, runnable suite, and `verify.command`.
+6. Express performance with numbers and executable benchmarks, not words such as “fast”.
+7. Resolve planning questions before unattended execution. `yoke prd check` rejects unresolved
+   placeholders; critical irreversible choices use the structured decision channel.
+8. Use `needs` only for hard prerequisites, `area` for collision domains, and `agent` only as
+   a Claude/Codex/Gemini affinity hint.
 
 ## Format (`.yoke/prd.yaml`)
 
@@ -41,8 +30,12 @@ good stories (small, testable, ordered) let it run overnight.
   title: scaffold a TypeScript CLI with vitest
   priority: 1
   acceptance:
-    - "npm test exits 0 with at least one passing test"
-    - "verify.command is set in .yoke/config.yaml"
+    - id: cli-help-runs
+      text: the CLI help command exits 0 and prints usage
+      verify: [npm run test:cli-help-runs]
+    - id: test-runner-starts
+      text: the project test runner starts and reports at least one passing test
+      verify: [npm run test:test-runner-starts]
   passes: false
 - id: STORY-2
   title: add the sum command
@@ -51,9 +44,15 @@ good stories (small, testable, ordered) let it run overnight.
   area: cli
   agent: codex
   acceptance:
-    - "cli sum 1 2 prints 3"
-    - "non-numeric input exits 1 with an error message"
+    - id: sum-valid
+      text: cli sum 1 2 prints 3
+      verify: [npm run test:sum-valid]
+    - id: sum-invalid
+      text: non-numeric input exits 1 with an error message
+      verify: [npm run test:sum-invalid]
   passes: false
 ```
 
-`passes` is owned by the loop — always start `false`. Validate with `yoke prd check`.
+Every story has 2–5 structured criteria. Each `verify` entry is one approved test command whose
+normalized text contains its criterion ID; never use shell operators or a broad unrelated suite.
+`passes` is owned by the loop and always starts false. Validate with `yoke prd check`.

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;
+}

package/dist/agents/providers.js

@@ -1,3 +1,5 @@
+import { ModelSelectionSchema } from './contracts.js';
+export { providerSpawnOptions, startProviderProcess, } from './process.js';
 const argsFor = (agent, permissions) => {
     if (agent === 'claude') {
         const mode = permissions === 'unsafe' ? 'bypassPermissions' : permissions === 'read-only' ? 'plan' : 'auto';
@@ -19,18 +21,19 @@ const argsFor = (agent, permissions) => {
     return ['--approval-mode', approval, '--sandbox'];
 };
 export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe', selection = {}) {
+    const parsedSelection = ModelSelectionSchema.parse(selection);
     const args = argsFor(agent, permissions);
-    if (selection.model)
-        args.push('--model', selection.model);
-    if (selection.reasoningEffort) {
+    if (parsedSelection.model)
+        args.push('--model', parsedSelection.model);
+    if (parsedSelection.reasoningEffort) {
         if (agent === 'claude')
-            args.push('--effort', selection.reasoningEffort);
+            args.push('--effort', parsedSelection.reasoningEffort);
         else if (agent === 'codex')
-            args.push('--config', `model_reasoning_effort=${selection.reasoningEffort}`);
+            args.push('--config', `model_reasoning_effort=${parsedSelection.reasoningEffort}`);
     }
-    if (agent === 'codex' && selection.nativeMultiAgent === false)
+    if (agent === 'codex' && parsedSelection.nativeMultiAgent === false)
         args.push('--disable', 'multi_agent');
-    if (selection.bare) {
+    if (parsedSelection.bare) {
         if (agent === 'codex')
             args.push('--ignore-user-config');
         else if (agent === 'claude')