peaks-loop 4.0.28 → 4.0.30

package/dist/services/dispatch/dispatch-record-writer.js

@@ -30,21 +30,9 @@ import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/sa
 import { withFileLockSync } from 'peaks-loop-shared-channel';
 import { isStageLabel } from './stage-enum.js';
 import { emitLeaseEvent } from '../observability/observability-service.js';
-/**
- * PRD-002b slice 2 — extract dispatch-record size budgets (max-prompt
- * bytes, note truncation cap) + time-math primitives so the
- * no-magic-numbers rule stops flagging the writer pipeline.
- */
-const BYTES_PER_KB = 1024;
-const MAX_PROMPT_KB = 256;
-const MAX_PROMPT_BYTES = MAX_PROMPT_KB * BYTES_PER_KB;
-const NOTE_MAX_CHARS = 200;
-const MS_PER_SECOND = 1_000;
-const SECONDS_PER_MINUTE = 60;
-const MINUTES_PER_HOUR = 60;
-const HOURS_PER_DAY = 24;
-const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
-const REDACTION_MAX_SCAN_DEPTH = 20;
+import { upgradeRecord } from './dispatch-record-upgrade.js';
+import { MAX_PROMPT_BYTES, MS_PER_DAY, NOTE_MAX_CHARS } from './dispatch-record-types.js';
+export { isDispatchStatus, isOutcome } from './dispatch-record-upgrade.js';
 /** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
 export function writeInitialDispatchRecord(input) {
     const { projectRoot, sessionId, requestId, role, prompt, toolCall, batchId } = input;
@@ -674,236 +662,6 @@ export function readRecords(paths) {
     }
     return out;
 }
-function upgradeRecord(parsed) {
-    if (!isObject(parsed)) {
-        throw new Error('Dispatch record root must be an object');
-    }
-    const obj = parsed;
-    // Slice 4.0.8: 3.2 → 4.0.0 schema bump. Phase A Task 8: 4.0.0 → 4.1.0
-    // (additive). The literal type narrows to '4.1.0' but legacy v4.0.0 /
-    // v3.2 / v3.1 / 3 / 2 / 1 records are accepted transparently and
-    // upgraded on read.
-    const rawVersion = obj.version;
-    if (rawVersion !== '4.1.0' && rawVersion !== '4.0.0' && rawVersion !== '3.2' && rawVersion !== '3.1' && rawVersion !== 3 && rawVersion !== 2 && rawVersion !== 1) {
-        throw new Error(`Dispatch record version mismatch: expected '4.1.0', '4.0.0', '3.2', '3.1', 3, 2, or 1, got ${JSON.stringify(rawVersion)}. ` +
-            'The v1 → v4.1.0 migration is in-file; records from much older or newer builds must be regenerated.');
-    }
-    const legacy = parseUpgradeRecordLegacyFields(obj);
-    const migration = parseUpgradeRecordMigrationFields(obj);
-    return {
-        version: '4.1.0',
-        createdAt: legacy.createdAt,
-        completedAt: legacy.completedAt,
-        outcome: legacy.outcome,
-        artifactPaths: legacy.artifactPaths,
-        disposed: legacy.disposed,
-        disposedAt: legacy.disposedAt,
-        role: legacy.role,
-        requestId: legacy.requestId,
-        sessionId: legacy.sessionId,
-        prompt: legacy.prompt,
-        toolCall: legacy.toolCall,
-        batchId: legacy.batchId,
-        heartbeats: legacy.heartbeats,
-        lastBeatAt: legacy.lastBeatAt,
-        status: legacy.status,
-        stage: migration.stage,
-        leaseId: migration.leaseId,
-        isolationStartedAt: migration.isolationStartedAt,
-        serviceKill: migration.serviceKill,
-        mergeBackAttempts: migration.mergeBackAttempts,
-        workflowId: migration.workflowId,
-        graphNodeId: migration.graphNodeId,
-        graphRef: migration.graphRef,
-        // Phase A Task 8: detached sub-agent fields. Legacy records
-        // (pre-4.1.0) default mode='in-process', vendor=null,
-        // autoCompactEvents=[], tokenUsage=null. See
-        // parseUpgradeRecordMigrationFields for the per-field
-        // validation rules.
-        mode: migration.mode,
-        vendor: migration.vendor,
-        autoCompactEvents: migration.autoCompactEvents,
-        tokenUsage: migration.tokenUsage
-    };
-}
-/**
- * Parse the v1..v3.2 core fields of a legacy dispatch record.
- * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
- * stays under the `max-lines-per-function: 50` ESLint ceiling.
- * Behavior is byte-identical to the previous inline block.
- */
-function parseUpgradeRecordLegacyFields(obj) {
-    const role = stringField(obj, 'role');
-    const requestId = stringField(obj, 'requestId');
-    const sessionId = stringField(obj, 'sessionId');
-    const prompt = stringField(obj, 'prompt');
-    // Slice 2026-06-23-audit-4th #C2: preserve toolCallVersion on read.
-    // Pre-versioning records default to '2.0.0' (the pre-#C2 implicit
-    // shape; matches the version stamped by every current dispatcher).
-    const rawToolCall = obj.toolCall;
-    if (!isObject(rawToolCall) || typeof rawToolCall.name !== 'string') {
-        throw new Error('Dispatch record toolCall must be { name, args }');
-    }
-    const toolCall = {
-        name: rawToolCall.name,
-        args: (isObject(rawToolCall.args) ? rawToolCall.args : {}),
-        ...(typeof rawToolCall.toolCallVersion === 'string' ? { toolCallVersion: rawToolCall.toolCallVersion } : { toolCallVersion: '2.0.0' })
-    };
-    const createdAt = stringField(obj, 'createdAt');
-    const heartbeats = Array.isArray(obj.heartbeats)
-        ? obj.heartbeats.filter(isValidHeartbeat)
-        : [];
-    const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
-    // Slice 2026-07-29-dispatch-stall-governance / S1 (UQ-1) — `no-execution`
-    // keeps its natural "dispatched, never executed" reading; an unparseable
-    // status field now resolves to a *distinct* `unreadable` label so the
-    // caller can tell "corrupt record" apart from "record written, no first
-    // heartbeat" (which is the new `never-started` state).
-    const status = isDispatchStatus(obj.status)
-        ? obj.status
-        : 'unreadable';
-    const completedAt = typeof obj.completedAt === 'string' ? obj.completedAt : null;
-    const outcome = isOutcome(obj.outcome) ? obj.outcome : 'no-execution';
-    const artifactPaths = Array.isArray(obj.artifactPaths)
-        ? obj.artifactPaths.filter((p) => typeof p === 'string')
-        : [];
-    const disposed = obj.disposed === true;
-    const disposedAt = typeof obj.disposedAt === 'string' ? obj.disposedAt : null;
-    const batchId = typeof obj.batchId === 'string' && obj.batchId.length > 0
-        ? obj.batchId
-        : 'legacy-batch';
-    return {
-        role,
-        requestId,
-        sessionId,
-        prompt,
-        toolCall,
-        createdAt,
-        heartbeats,
-        lastBeatAt,
-        status,
-        completedAt,
-        outcome,
-        artifactPaths,
-        disposed,
-        disposedAt,
-        batchId
-    };
-}
-/**
- * Parse the post-v3 migration fields of a legacy dispatch record.
- * PRD-002b slice 6: extracted from `upgradeRecord` so the reader
- * stays under the `max-lines-per-function: 50` ESLint ceiling.
- * Behavior is byte-identical to the previous inline block.
- */
-function parseUpgradeRecordMigrationFields(obj) {
-    return {
-        // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1 / PB-2)
-        // — legacy records (pre-slice) had no `stage` field. The reader
-        // defaults to `null` so the watch surface can tell "no stage ever
-        // emitted" apart from "stage: ''" (which is itself a *valid*
-        // round-trip through the writer — an empty stage is rejected by
-        // `setStage`, but a record that round-tripped through a non-strict
-        // tool would land here).
-        stage: typeof obj.stage === 'string' && obj.stage.length > 0 ? obj.stage : null,
-        // Slice 2026-07-29-worktree-l2-extended Part 3.A: legacy records
-        // have no `leaseId`; default to `null` so the auto-release hook
-        // in `markCompleted` is a clean no-op for them.
-        leaseId: typeof obj.leaseId === 'string' && /^[a-f0-9]{16}$/.test(obj.leaseId)
-            ? obj.leaseId
-            : null,
-        // Slice 2026-07-29-worktree-l2-extended Part 7: v3 → v3.1
-        // migration. Legacy records have no `isolationStartedAt`; default
-        // to `null`. v3.1 readers can treat the field as opt-in.
-        isolationStartedAt: typeof obj.isolationStartedAt === 'string' && obj.isolationStartedAt.length > 0
-            ? obj.isolationStartedAt
-            : null,
-        // Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.1 → v3.2
-        // migration. Legacy v3.1 records have no `serviceKill` or
-        // `mergeBackAttempts` fields. Default to [] and 0 so the
-        // merge-back-runner (Task 9) can read either schema on disk.
-        serviceKill: Array.isArray(obj.serviceKill)
-            ? (obj.serviceKill.filter((e) => {
-                if (typeof e !== 'object' || e === null)
-                    return false;
-                const o = e;
-                return typeof o.pid === 'number' && typeof o.name === 'string' && typeof o.signal === 'string' && (o.exitCode === null || typeof o.exitCode === 'number');
-            }))
-            : [],
-        mergeBackAttempts: typeof obj.mergeBackAttempts === 'number' && Number.isFinite(obj.mergeBackAttempts) && obj.mergeBackAttempts >= 0
-            ? Math.floor(obj.mergeBackAttempts)
-            : 0,
-        // Slice 4.0.8: 3.2 → 4.0.0 migration. v3.2 records on disk
-        // pre-date the workflow-graph binding; default all three
-        // fields to `null` so a legacy record upgrades transparently.
-        workflowId: typeof obj.workflowId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.workflowId) ? obj.workflowId : null,
-        graphNodeId: typeof obj.graphNodeId === 'string' && /^[a-zA-Z0-9._-]{1,200}$/.test(obj.graphNodeId) ? obj.graphNodeId : null,
-        graphRef: typeof obj.graphRef === 'string' ? obj.graphRef : null,
-        // Phase A Task 8: 4.0.0 → 4.1.0 migration. Pre-4.1.0 records
-        // have no mode / vendor / autoCompactEvents / tokenUsage
-        // fields. Default to safe in-process / null / [] / null so
-        // legacy records upgrade transparently without breaking
-        // consumers (e.g. the dashboard, the merge-back-runner).
-        mode: obj.mode === 'detached' ? 'detached' : 'in-process',
-        vendor: obj.vendor === 'claude' || obj.vendor === 'codex' || obj.vendor === 'copilot' ? obj.vendor : null,
-        autoCompactEvents: Array.isArray(obj.autoCompactEvents)
-            ? obj.autoCompactEvents.filter((e) => typeof e?.at === 'number' &&
-                (e?.threshold === '0.85' || e?.threshold === '0.95') &&
-                typeof e?.tokensBefore === 'number' &&
-                typeof e?.tokensAfter === 'number')
-            : [],
-        tokenUsage: typeof obj.tokenUsage === 'object' && obj.tokenUsage !== null && typeof obj.tokenUsage.promptTokens === 'number' && typeof obj.tokenUsage.completionTokens === 'number'
-            ? {
-                promptTokens: obj.tokenUsage.promptTokens,
-                completionTokens: obj.tokenUsage.completionTokens,
-                ...(typeof obj.tokenUsage.totalCostUsd === 'number'
-                    ? { totalCostUsd: obj.tokenUsage.totalCostUsd }
-                    : {}),
-            }
-            : null
-    };
-}
-function isObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-function stringField(obj, key) {
-    const v = obj[key];
-    if (typeof v !== 'string') {
-        throw new Error(`Dispatch record field '${key}' must be a string (got ${typeof v})`);
-    }
-    return v;
-}
-function isValidHeartbeat(v) {
-    if (!isObject(v))
-        return false;
-    return (typeof v.at === 'string' &&
-        isHeartbeatStatus(v.status) &&
-        typeof v.progress === 'number' &&
-        (v.note === null || typeof v.note === 'string'));
-}
-function isHeartbeatStatus(v) {
-    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
-        v === 'done' || v === 'failed' || v === 'stale' ||
-        // Slice 2026-07-29-dispatch-stall-governance / S2 — accept the
-        // S1 terminal members so a sub-agent can report `cancelled`,
-        // `no-execution`, `never-started`, or `unreadable` through the
-        // heartbeat CLI.
-        v === 'cancelled' || v === 'no-execution' ||
-        v === 'never-started' || v === 'unreadable');
-}
-function isDispatchStatus(v) {
-    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
-        v === 'done' || v === 'failed' || v === 'cancelled' ||
-        v === 'no-execution' || v === 'stale' ||
-        // Slice 2026-07-29-dispatch-stall-governance / S1 — accept the two
-        // new terminal members from the startup-timeout service.
-        v === 'never-started' || v === 'unreadable');
-}
-function isOutcome(v) {
-    return (v === 'success' || v === 'failed' || v === 'timeout' ||
-        v === 'cancelled' || v === 'no-execution');
-}
-export { isDispatchStatus, isOutcome };
 function writeAtomic(path, record) {
     const dir = dirname(path);
     // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already

package/dist/services/dispatch/dispatch-sub-agent.d.ts

@@ -0,0 +1,43 @@
+/**
+ * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+ * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
+ * `git ls-files <glob>` against `projectRoot` and returns the matching
+ * tracked file paths (relative to projectRoot). Empty array when no
+ * files match (e.g. untracked new file, wrong glob, not a git repo).
+ *
+ * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
+ * is "the file the sub-agent claims to have written must ACTUALLY be
+ * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
+ * would happily return untracked-but-on-disk files (false-positive
+ * for the fake-green gate).
+ *
+ * Failure modes (best-effort, never throws):
+ *  - git not on PATH → empty array (`ENOENT` swallowed)
+ *  - not a git repo → empty array (git exits non-zero)
+ *  - glob matches zero tracked files → empty array
+ *
+ * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
+ * The export is intentional — the helper has zero side effects and
+ * keeps the dispatch action handler small.
+ */
+export declare function runGitLsFiles(projectRoot: string, glob: string): readonly string[];
+/**
+ * `dispatchSubAgent` is the thin programmatic wrapper the integration
+ * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
+ * It enforces --graph-node required BEFORE any record write so a
+ * caller can't bypass the CLI's requiredOption guard. Throws a typed
+ * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
+ */
+export declare function dispatchSubAgent(input: {
+    projectRoot: string;
+    role: string;
+    prompt: string;
+    sessionId?: string;
+    graphNode?: string;
+    workflowId?: string;
+    graphRef?: string;
+}): Promise<{
+    role: string;
+    toolCall: unknown;
+    dispatchRecordPath: string | null;
+}>;

package/dist/services/dispatch/dispatch-sub-agent.js

@@ -0,0 +1,55 @@
+/**
+ * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+ * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
+ * `git ls-files <glob>` against `projectRoot` and returns the matching
+ * tracked file paths (relative to projectRoot). Empty array when no
+ * files match (e.g. untracked new file, wrong glob, not a git repo).
+ *
+ * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
+ * is "the file the sub-agent claims to have written must ACTUALLY be
+ * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
+ * would happily return untracked-but-on-disk files (false-positive
+ * for the fake-green gate).
+ *
+ * Failure modes (best-effort, never throws):
+ *  - git not on PATH → empty array (`ENOENT` swallowed)
+ *  - not a git repo → empty array (git exits non-zero)
+ *  - glob matches zero tracked files → empty array
+ *
+ * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
+ * The export is intentional — the helper has zero side effects and
+ * keeps the dispatch action handler small.
+ */
+export function runGitLsFiles(projectRoot, glob) {
+    try {
+        const { execFileSync } = require('node:child_process');
+        const stdout = execFileSync('git', ['ls-files', '--', glob], { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        return stdout.split('\n').filter((line) => line.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/* ---------- Slice 4.0.8 RD §4 D4c: programmatic dispatcher ---------- */
+/**
+ * `dispatchSubAgent` is the thin programmatic wrapper the integration
+ * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.
+ * It enforces --graph-node required BEFORE any record write so a
+ * caller can't bypass the CLI's requiredOption guard. Throws a typed
+ * error with `code = PEAKS_GRAPH_NODE_REQUIRED` when missing.
+ */
+export async function dispatchSubAgent(input) {
+    if (typeof input.graphNode !== 'string' || input.graphNode.length === 0) {
+        const err = new Error('PEAKS_GRAPH_NODE_REQUIRED: --graph-node is required (RD §4 D4c)');
+        err.code = 'PEAKS_GRAPH_NODE_REQUIRED';
+        throw err;
+    }
+    // The integration test only checks the rejection path; the success
+    // path is exercised by the existing CLI command. Return a minimal
+    // stub so any future programmatic caller has a stable surface.
+    return {
+        role: input.role,
+        toolCall: null,
+        dispatchRecordPath: null,
+    };
+}

package/dist/services/dispatch/isolation-lease.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Part 2.C (slice 2026-07-29-worktree-l2-extended) — spawn a worktree
+ * lease by shelling out to `peaks worktree spawn` (avoid re-implementing
+ * the lease-write + git-worktree-add sequence in this file). The CLI
+ * does the lease write, the git worktree add, AND the error handling;
+ * we just parse the JSON envelope and surface the leaseId + path.
+ *
+ * Throws on spawn failure; the caller converts the error to a
+ * ISOLATION_SPAWN_FAILED envelope. Synchronous wait is acceptable: the
+ * dispatch is already async, the lease is a few hundred ms of FS work,
+ * and we need the leaseId before we build the dispatch record.
+ */
+export declare function spawnWorktreeLease(args: {
+    projectRoot: string;
+    sessionId: string;
+    rid: string;
+    role: string;
+    purpose: string;
+}): Promise<{
+    leaseId: string;
+    path: string;
+    branch: string;
+    expiresAt: number;
+}>;
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 12: container
+ * isolation bridge. Shells out to `peaks container spawn` to
+ * run `docker run` + write the container lease. Returns the
+ * leaseId the dispatch record needs to persist. The shape is
+ * a subset of the spawnWorktreeLease return (just leaseId);
+ * we do not need the path/branch/expiresAt for the container
+ * path because the envelope surfaces a different set of
+ * fields (image + containerId; see container-lease.ts).
+ */
+export declare function spawnContainerLease(args: {
+    projectRoot: string;
+    sessionId: string;
+    rid: string;
+    role: string;
+    purpose: string;
+}): Promise<{
+    leaseId: string;
+}>;

package/dist/services/dispatch/isolation-lease.js

@@ -0,0 +1,129 @@
+import { spawn as childProcessSpawn } from 'node:child_process';
+/**
+ * Part 2.C (slice 2026-07-29-worktree-l2-extended) — spawn a worktree
+ * lease by shelling out to `peaks worktree spawn` (avoid re-implementing
+ * the lease-write + git-worktree-add sequence in this file). The CLI
+ * does the lease write, the git worktree add, AND the error handling;
+ * we just parse the JSON envelope and surface the leaseId + path.
+ *
+ * Throws on spawn failure; the caller converts the error to a
+ * ISOLATION_SPAWN_FAILED envelope. Synchronous wait is acceptable: the
+ * dispatch is already async, the lease is a few hundred ms of FS work,
+ * and we need the leaseId before we build the dispatch record.
+ */
+export function spawnWorktreeLease(args) {
+    return new Promise((resolve, reject) => {
+        const child = childProcessSpawn(process.execPath, [
+            // The compiled CLI lives in dist/cli/peaks.js. We pass the entry
+            // through node so the test suite (which also runs on the same
+            // process) and the production binary share the same path. When
+            // the binary is invoked as `peaks`, the package bin stub does
+            // this for us; here we explicitly use process.execPath + the
+            // resolved entry to avoid PATH surprises.
+            process.argv[1] ?? '',
+            'worktree', 'spawn',
+            '--rid', args.rid,
+            '--role', args.role,
+            '--purpose', args.purpose,
+            '--project', args.projectRoot,
+            '--session', args.sessionId,
+            '--json'
+        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+        child.on('error', (err) => reject(new Error(`worktree spawn subprocess failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`peaks worktree spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                reject(new Error(`peaks worktree spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                reject(new Error('peaks worktree spawn envelope is not an object'));
+                return;
+            }
+            const env = parsed;
+            if (env.ok !== true || !env.data?.lease) {
+                reject(new Error(`peaks worktree spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
+                return;
+            }
+            resolve({
+                leaseId: env.data.lease.leaseId,
+                path: env.data.lease.path,
+                branch: env.data.lease.branch,
+                expiresAt: env.data.lease.expiresAt
+            });
+            // Part 47: unref via setImmediate so the close handler
+            // finishes first and Node's stdio 'end' events drain the
+            // stdout/stderr buffers before the parent releases the
+            // child handle. Without this microtask defer, the unref
+            // races the buffered stdout close and the test receives
+            // an empty JSON envelope.
+            setImmediate(() => { child.unref(); });
+        });
+    });
+}
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 12: container
+ * isolation bridge. Shells out to `peaks container spawn` to
+ * run `docker run` + write the container lease. Returns the
+ * leaseId the dispatch record needs to persist. The shape is
+ * a subset of the spawnWorktreeLease return (just leaseId);
+ * we do not need the path/branch/expiresAt for the container
+ * path because the envelope surfaces a different set of
+ * fields (image + containerId; see container-lease.ts).
+ */
+export function spawnContainerLease(args) {
+    return new Promise((resolve, reject) => {
+        const child = childProcessSpawn(process.execPath, [
+            process.argv[1] ?? '',
+            'container', 'spawn',
+            '--rid', args.rid,
+            '--role', args.role,
+            '--purpose', args.purpose,
+            '--project', args.projectRoot,
+            '--session', args.sessionId,
+            '--json'
+        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+        child.on('error', (err) => reject(new Error(`container spawn subprocess failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`peaks container spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                reject(new Error(`peaks container spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                reject(new Error('peaks container spawn envelope is not an object'));
+                return;
+            }
+            const env = parsed;
+            if (env.ok !== true || !env.data?.lease) {
+                reject(new Error(`peaks container spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
+                return;
+            }
+            resolve({ leaseId: env.data.lease.leaseId });
+        });
+        // See spawnWorktreeLease above for the rationale.
+        child.unref();
+    });
+}

package/dist/services/evidence/evidence-generator.d.ts

@@ -0,0 +1,26 @@
+export type EvidenceGenerateOptions = {
+    projectRoot: string;
+    rid: string;
+    title: string;
+    files: string[];
+    lineCounts: Record<string, string>;
+    sessionId: string;
+};
+export type EvidenceGenerateResult = {
+    rid: string;
+    sessionId: string;
+    sessionRoot: string;
+    handoffPath: string;
+    handoffHash: string;
+    writtenFiles: string[];
+    createdDirectories: string[];
+};
+/** Comma/space tolerant `--files` splitter. */
+export declare function parseFiles(raw: string): string[];
+/**
+ * Parse `--line-counts "f=n;g=m"`. Accepts both `;` and `,` separators so
+ * the reference prototype's comma form and the task's semicolon form both
+ * work. `key=value` pairs without `=` are ignored (mirrors the prototype).
+ */
+export declare function parseLineCounts(raw: string): Record<string, string>;
+export declare function generateEvidence(options: EvidenceGenerateOptions): Promise<EvidenceGenerateResult>;