peaks-loop 4.0.28 → 4.0.30

package/dist/services/codegraph/codegraph-preflight-service.js

@@ -0,0 +1,226 @@
+// src/services/codegraph/codegraph-preflight-service.ts
+//
+// Slice 2026-09-03-codegraph-preread (Option A) — pre-dispatch codegraph
+// preflight for RD planning. peaks-code's RD dispatch path calls
+// `buildCodegraphPreflightBlock` BEFORE composing the RD sub-agent prompt
+// (src/cli/commands/dispatch-commands.ts) so the RD plans against the real
+// module/file topology in the codegraph index, not LLM memory.
+//
+// The service does three things, all best-effort and fail-soft (it NEVER
+// throws — every failure returns `{ available: false, note }` so the caller
+// degrades to a "codegraph unavailable — proceeding on project-scan only"
+// note and dispatch proceeds):
+//
+//   1. Ensure the schema exists: when `<projectRoot>/.codegraph/` is
+//      absent, run `codegraph init` + `codegraph index` (best-effort).
+//   2. Skip-when-fresh: when `.codegraph/` already carries the
+//      peaks-loop marker, do NOT re-init / re-index on every dispatch
+//      (index is incremental; the sibling rid-2026-09-03-codegraph-autorefresh
+//      owns post-slice refresh). A foreign-schema `.codegraph/` is never
+//      clobbered — we fail-soft instead.
+//   3. Read a BOUNDED project-structure summary from the index
+//      (`codegraph files --json`) and render it as a `## Codegraph
+//      structure` markdown block.
+//
+// Bounded-output contract: the rendered block never exceeds a safe prompt
+// budget. The pure renderer `renderCodegraphStructureBlock` caps the
+// directory histogram at CODEGRAPH_STRUCTURE_MAX_DIRS rows and the root-file
+// listing at CODEGRAPH_STRUCTURE_MAX_ROOT_FILES entries; anything beyond
+// those caps is summarized with a "… and N more" line and a `truncated: true`
+// flag. Documented caps:
+//   - CODEGRAPH_STRUCTURE_MAX_DIRS        = 40  directory rows
+//   - CODEGRAPH_STRUCTURE_MAX_ROOT_FILES  = 12  bare root files
+import { mkdirSync } from 'node:fs';
+import { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, writeCodegraphMarker, } from './codegraph-service.js';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+/** Cap for the directory histogram in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_DIRS = 40;
+/** Cap for bare root files listed in the rendered structure block. */
+export const CODEGRAPH_STRUCTURE_MAX_ROOT_FILES = 12;
+/** Strip a leading `./` (upstream codegraph paths may carry it). */
+function normalizeCodegraphPath(path) {
+    return path.startsWith('./') ? path.slice(2) : path;
+}
+/**
+ * Pure renderer: turn the codegraph `files --json` payload into a bounded
+ * `## Codegraph structure` block. Files are aggregated into a directory
+ * histogram (immediate parent dir; bare root files bucket separately),
+ * sorted by file count descending then name ascending, and capped at
+ * `maxDirs` rows / `maxRootFiles` root entries. Exported separately so the
+ * bounded-output contract is unit-testable without a filesystem.
+ */
+export function renderCodegraphStructureBlock(files, options = {}) {
+    const maxDirs = options.maxDirs ?? CODEGRAPH_STRUCTURE_MAX_DIRS;
+    const maxRootFiles = options.maxRootFiles ?? CODEGRAPH_STRUCTURE_MAX_ROOT_FILES;
+    const dirCounts = new Map();
+    const rootFiles = [];
+    let total = 0;
+    for (const file of files) {
+        const raw = normalizeCodegraphPath(file.path).replace(/\\/g, '/');
+        if (raw.length === 0)
+            continue;
+        total += 1;
+        const slash = raw.lastIndexOf('/');
+        if (slash === -1) {
+            rootFiles.push(raw);
+            continue;
+        }
+        const dir = raw.slice(0, slash);
+        dirCounts.set(dir, (dirCounts.get(dir) ?? 0) + 1);
+    }
+    const sortedDirs = [...dirCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+    const shownDirs = sortedDirs.slice(0, maxDirs);
+    const truncatedDirs = sortedDirs.length > maxDirs;
+    const sortedRoot = [...rootFiles].sort((a, b) => a.localeCompare(b));
+    const shownRoot = sortedRoot.slice(0, maxRootFiles);
+    const truncatedRoot = sortedRoot.length > maxRootFiles;
+    const lines = ['## Codegraph structure', ''];
+    lines.push(total === 0
+        ? 'No files are indexed yet. Run `peaks codegraph index` before dispatching planning work for symbol-accurate structure.'
+        : `${total} file${total === 1 ? '' : 's'} indexed in the codegraph index:`);
+    for (const [dir, count] of shownDirs) {
+        lines.push(`- \`${dir}/\` — ${count} file${count === 1 ? '' : 's'}`);
+    }
+    if (truncatedDirs) {
+        lines.push(`- … and ${sortedDirs.length - maxDirs} more director${sortedDirs.length - maxDirs === 1 ? 'y' : 'ies'}`);
+    }
+    if (sortedRoot.length > 0) {
+        lines.push(`- (root) — ${shownRoot.map((f) => `\`${f}\``).join(', ')}${truncatedRoot ? ' …' : ''}`);
+    }
+    const block = lines.join('\n').replace(/\s+$/, '') + '\n\n';
+    return { block, total, truncated: truncatedDirs || truncatedRoot };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function firstMeaningfulLine(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 'no upstream output';
+    const first = trimmed.split(/\r?\n/)[0];
+    return first !== undefined ? first.slice(0, 200) : 'no upstream output';
+}
+function parseFilesPayload(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed)) {
+            const entries = parsed
+                .filter((entry) => typeof entry === 'object' && entry !== null && 'path' in entry)
+                .map((entry) => ({ path: typeof entry.path === 'string' ? entry.path : '' }))
+                .filter((entry) => entry.path.length > 0);
+            return { ok: true, entries };
+        }
+        // JSON but not an array — not the shape we expect.
+        return { ok: false, entries: [] };
+    }
+    catch {
+        // Not JSON at all — e.g. the upstream text path ("No files indexed…").
+        return { ok: false, entries: [] };
+    }
+}
+async function readStructure(projectRoot, runner) {
+    let result;
+    try {
+        const invocation = createCodegraphInvocation({ subcommand: 'files', project: projectRoot, json: true });
+        result = await executeCodegraphInvocation(invocation, runner);
+    }
+    catch (error) {
+        return { available: false, note: `codegraph files unavailable: ${errorMessage(error)}` };
+    }
+    if (result.exitCode !== 0) {
+        return {
+            available: false,
+            note: `codegraph files failed (exit ${String(result.exitCode)}): ${firstMeaningfulLine(result.stderr || result.stdout)}`,
+        };
+    }
+    const { ok, entries } = parseFilesPayload(result.stdout);
+    if (!ok) {
+        return {
+            available: false,
+            note: 'codegraph files returned no parseable structure — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    if (entries.length === 0) {
+        return {
+            available: false,
+            note: 'codegraph index has no files — run `peaks codegraph index` before dispatch for symbol-accurate structure.',
+        };
+    }
+    const summary = renderCodegraphStructureBlock(entries);
+    return {
+        available: true,
+        block: summary.block,
+        fileCount: summary.total,
+        truncated: summary.truncated,
+    };
+}
+/**
+ * Pre-dispatch codegraph preflight. Returns a `## Codegraph structure`
+ * block when the index is (or becomes) readable; otherwise an
+ * `{ available: false, note }` result. NEVER throws — the caller must be
+ * able to degrade gracefully on every failure path.
+ *
+ * Behavior matrix (acceptance criteria):
+ * - `.codegraph/` absent  → init + index (best-effort), then read.
+ * - `.codegraph/` present with peaks-loop marker → skip init/index
+ *   (fresh), read directly. No redundant re-index on every dispatch.
+ * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
+ *   never clobber a foreign store.
+ *
+ * The optional `runner` mirrors `CodegraphProcessRunner` and is the ONLY
+ * injected boundary (tests fake the upstream binary).
+ */
+export async function buildCodegraphPreflightBlock(projectRoot, runner) {
+    const processRunner = runner ?? defaultCodegraphProcessRunner;
+    const guard = defaultCodegraphInitGuard(projectRoot);
+    if (guard.status === 'conflict-foreign-schema') {
+        return {
+            available: false,
+            note: `codegraph unavailable: ${CODEGRAPH_DIR_NAME}/ exists with a non-peaks-loop schema and was not touched. Move or rename the foreign directory, then re-run \`peaks codegraph init\` to enable pre-dispatch structure reads.`,
+        };
+    }
+    if (guard.status === 'fresh') {
+        // 1. init (best-effort). Upstream creates the `.codegraph/` dir; we
+        //    stamp the peaks-loop marker afterwards so the NEXT dispatch hits
+        //    the noop (skip-when-fresh) branch.
+        try {
+            const initResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'init', project: projectRoot }), processRunner);
+            if (initResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph init failed (exit ${String(initResult.exitCode)}): ${firstMeaningfulLine(initResult.stderr || initResult.stdout)}`,
+                };
+            }
+            try {
+                // Upstream init creates `.codegraph/`; mkdir is a no-op in the real
+                // path and lets the marker write succeed even when the runner is
+                // faked (tests). Best-effort: failure must not undo the init.
+                mkdirSync(guard.codegraphDir, { recursive: true });
+                writeCodegraphMarker(guard.codegraphDir);
+            }
+            catch {
+                // Best-effort: a marker-write failure must not undo the init.
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph init unavailable: ${errorMessage(error)}` };
+        }
+        // 2. index (best-effort).
+        try {
+            const indexResult = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'index', project: projectRoot, quiet: true }), processRunner);
+            if (indexResult.exitCode !== 0) {
+                return {
+                    available: false,
+                    note: `codegraph index failed (exit ${String(indexResult.exitCode)}): ${firstMeaningfulLine(indexResult.stderr || indexResult.stdout)}`,
+                };
+            }
+        }
+        catch (error) {
+            return { available: false, note: `codegraph index unavailable: ${errorMessage(error)}` };
+        }
+    }
+    // guard.status === 'noop-already-peaks-loop' (or we just initialized):
+    // the schema exists — do NOT re-index, go straight to the bounded read.
+    return readStructure(projectRoot, processRunner);
+}

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -28,6 +28,46 @@ export interface DispatchPromptInput {
      * a byte-counted estimate.
      */
     contextProbe?: ContextPercentProbe | null;
+    /**
+     * Slice 2026-09-03-codegraph-preread (Option A): pre-composed
+     * `## Codegraph structure` markdown block, read from the codegraph
+     * index BEFORE the RD sub-agent's task body is composed so the RD
+     * plans against real module/file topology, not LLM memory.
+     *
+     * - `undefined` → no codegraph block (legacy callers unchanged).
+     * - `null` → codegraph was attempted but is unavailable; the composer
+     *   renders a fixed "codegraph unavailable — proceeding on project-scan
+     *   only" note (fail-soft; never hard-blocks a dispatch).
+     * - `string` → the block, rendered verbatim between the context window
+     *   and the memory/task content.
+     */
+    codegraphBlock?: string | null;
+    /**
+     * Slice 2026-09-06-ui-lib-dispatch-priority: pre-composed
+     * `## Project stack` markdown block, rendered from the detected
+     * project context (component library + CSS framework + build tool) by
+     * the dispatch site BEFORE the sub-agent's task body is composed so
+     * the RD/UI sub-agent sees the library-first directive in-context.
+     *
+     * - `undefined` → no project-stack block (legacy callers unchanged).
+     * - `null` → the project has no detected component library; the
+     *   composer renders nothing (byte-identical degradation).
+     * - `string` → the block, rendered verbatim between the codegraph
+     *   block and the memory/task content.
+     */
+    projectStackBlock?: string | null;
+    /**
+     * Slice 2026-09-07-search-first-preflight: the orchestrator-synthesized
+     * `## Fresh context` block (≤5 binding directives from a Context7 →
+     * WebSearch preflight), read from `.peaks/_runtime/<sessionId>/fresh-context.md`.
+     *
+     * - `undefined` → no fresh-context block (legacy callers unchanged).
+     * - `null` → the block is unavailable (missing file / no `## Fresh context`
+     *   heading); the composer renders nothing (byte-identical degradation).
+     * - `string` → the block, rendered verbatim after the project-stack block
+     *   and before the memory/task content.
+     */
+    freshContextBlock?: string | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
@@ -88,6 +128,10 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -99,3 +143,11 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * refusal is in scope before any task-specific prose arrives.
  */
 export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): string;
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export declare const CODEGRAPH_UNAVAILABLE_BLOCK = "## Codegraph structure\n\ncodegraph unavailable \u2014 proceeding on project-scan only.\n";

package/dist/services/context/build-dispatch-system-prompt.js

@@ -83,6 +83,10 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
  * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
  * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * The contract holds for callers that do not pass `codegraphBlock` (all
+ * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
+ * codegraph structure block (or its fail-soft unavailable note) for RD
+ * dispatches between the context window and the memory/task content.
  *
  * Available branch prepends the memory block before the `## Task` heading so
  * `## Project memory …` always sits above the task brief (never pushed below
@@ -94,12 +98,75 @@ export const LIFECYCLE_RULES = `## Sub-agent lifecycle rules (locked 2026-08-01)
  * refusal is in scope before any task-specific prose arrives.
  */
 export function buildDispatchSystemPrompt(input) {
-    const { taskBody, memoryBlock, contextProbe } = input;
+    const { taskBody, memoryBlock, contextProbe, codegraphBlock, projectStackBlock, freshContextBlock } = input;
     const contextBlock = renderContextBlock(contextProbe ?? null);
+    const codegraphText = renderCodegraphBlock(codegraphBlock);
+    const projectStackText = renderProjectStackBlock(projectStackBlock);
+    const freshContextText = renderFreshContextBlock(freshContextBlock);
     if (memoryBlock.available === true && typeof memoryBlock.block === 'string') {
-        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${memoryBlock.block}\n## Task\n${taskBody}`;
+        return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${memoryBlock.block}\n## Task\n${taskBody}`;
     }
-    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${taskBody}`;
+    return `${L1_WORKTREE_GOVERNANCE_BLOCK}\n${LIFECYCLE_RULES}\n${contextBlock}${codegraphText}${projectStackText}${freshContextText}${taskBody}`;
+}
+/**
+ * Slice 2026-09-03-codegraph-preread: fixed degradation string emitted
+ * when the RD dispatch preflight requested a codegraph structure read but
+ * the index could not be resolved (absent + init failure, foreign schema,
+ * unparseable output). Kept as a constant so the unavailable branch is
+ * byte-stable and trivially testable.
+ */
+export const CODEGRAPH_UNAVAILABLE_BLOCK = '## Codegraph structure\n\ncodegraph unavailable — proceeding on project-scan only.\n';
+/**
+ * Render the codegraph insertion for a dispatch prompt.
+ *
+ * - `undefined` → empty (the composer is byte-identical to the legacy
+ *   shape for callers that did not opt into a codegraph pre-read).
+ * - `null` → the fixed CODEGRAPH_UNAVAILABLE_BLOCK note.
+ * - `string` → the pre-composed block from the codegraph preflight
+ *   service, verbatim.
+ *
+ * Every non-empty variant is normalized to end on its own paragraph
+ * (`\n\n`) so the following block (project memory or task body) starts
+ * cleanly regardless of the caller's trailing newline habits.
+ */
+function renderCodegraphBlock(codegraphBlock) {
+    if (codegraphBlock === undefined)
+        return '';
+    const text = codegraphBlock === null ? CODEGRAPH_UNAVAILABLE_BLOCK : codegraphBlock;
+    return `${text.replace(/\s+$/, '')}\n\n`;
+}
+/**
+ * Render the project-stack insertion for a dispatch prompt.
+ *
+ * - `undefined` / `null` → empty (the composer is byte-identical to the
+ *   legacy shape — no dangling "Project stack" heading).
+ * - `string` → the pre-composed block from the dispatch site, verbatim.
+ *
+ * Mirrors `renderCodegraphBlock`: every non-empty variant is normalized
+ * to end on its own paragraph (`\n\n`) so the following block (project
+ * memory or task body) starts cleanly.
+ */
+function renderProjectStackBlock(projectStackBlock) {
+    if (projectStackBlock === undefined || projectStackBlock === null)
+        return '';
+    return `${projectStackBlock.replace(/\s+$/, '')}\n\n`;
+}
+/**
+ * Render the fresh-context insertion for a dispatch prompt.
+ *
+ * - `undefined` / `null` → empty (the composer is byte-identical to the
+ *   legacy shape — no dangling "Fresh context" heading).
+ * - `string` → the pre-composed block from the fresh-context preflight
+ *   synthesis, verbatim.
+ *
+ * Mirrors `renderProjectStackBlock`: every non-empty variant is normalized
+ * to end on its own paragraph (`\n\n`) so the following block (project
+ * memory or task body) starts cleanly.
+ */
+function renderFreshContextBlock(freshContextBlock) {
+    if (freshContextBlock === undefined || freshContextBlock === null)
+        return '';
+    return `${freshContextBlock.replace(/\s+$/, '')}\n\n`;
 }
 /**
  * Slice 2026-07-29-context-evaluation-accuracy: emit a

package/dist/services/dispatch/dispatch-record-types.d.ts

@@ -0,0 +1,278 @@
+import type { SubAgentToolCall } from './sub-agent-dispatcher.js';
+/** G6.3 Heartbeat entry — single update written by a running sub-agent. */
+export interface Heartbeat {
+    readonly at: string;
+    readonly status: HeartbeatStatus;
+    readonly progress: number;
+    readonly note: string | null;
+}
+export type HeartbeatStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'stale' | 'cancelled' | 'no-execution' | 'never-started' | 'unreadable';
+export type DispatchRecordStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'no-execution' | 'stale' | 'never-started' | 'unreadable';
+export type DispatchOutcome = 'success' | 'failed' | 'timeout' | 'cancelled' | 'no-execution';
+/** G2+G5+G6 dispatch record schema (AC-26 + AC-34). */
+export interface DispatchRecord {
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 4.C: schema v3 makes
+     * `leaseId` a structurally required field (was `leaseId?: string | null`
+     * in v2). The v3 upgrade is a "fill in" migration: every dispatch
+     * writer knows its lease id at construction time (Part 2.C's
+     * --isolation worktree spawns it; non-isolation dispatches stamp
+     * `null`). Readers tolerate both v2 and v3 on disk (see
+     * `upgradeRecord`); the `?` was a Part 4.A ergonomic concession
+     * to keep 4 unit-test literal sites from breaking the build. v3
+     * moves the optional off the type and adds the field to the
+     * 4 literal sites in one pass.
+     *
+     * Slice 2026-07-29-worktree-l2-extended Part 7: schema v3.1 adds
+     * `isolationStartedAt: string | null` for the L4 isolation
+     * bridge (Part 8 container POC). It's the ISO timestamp of
+     * when the isolation mode was set up (e.g. when the worktree
+     * was spawned). `null` means the dispatch did not request
+     * isolation. The `version` field stays at 3 because the
+     * v3 → v3.1 transition is additive; the new field is
+     * defaulted to `null` on read so v3 records upgrade cleanly.
+     */
+    /**
+     * Phase A Task 8: schema bumped to v4.1.0 (additive). The bump
+     * is purely additive — new fields (`mode`, `vendor`,
+     * `autoCompactEvents`, `tokenUsage`) all default safely on
+     * read for legacy v4.0.0 / v3.2 / v3.1 / v3 / v2 / v1 records.
+     * No existing field semantics changed.
+     */
+    readonly version: '4.1.0';
+    readonly createdAt: string;
+    readonly completedAt: string | null;
+    readonly outcome: DispatchOutcome;
+    readonly artifactPaths: readonly string[];
+    readonly disposed: boolean;
+    readonly disposedAt: string | null;
+    readonly role: string;
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly prompt: string;
+    readonly toolCall: SubAgentToolCall;
+    /** G5 batch id (AC-27) — uuid-like opaque token grouping one batch. */
+    readonly batchId: string;
+    /** G6 fields (AC-34) — backward compat: defaults on read. */
+    readonly heartbeats: readonly Heartbeat[];
+    readonly lastBeatAt: string | null;
+    readonly status: DispatchRecordStatus;
+    readonly stage: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 3.A + Part 4.C: the
+     * worktree lease id stamped on this dispatch (via `peaks sub-agent
+     * dispatch --isolation worktree`). The release hook (see
+     * markCompleted + `peaks sub-agent heartbeat --status done`)
+     * reads this field to auto-call `peaks worktree release` when
+     * the sub-agent finalizes. `null` means the dispatch did not
+     * request isolation and no release will fire. Persisted for
+     * audit + idempotency so a re-read of an old record still
+     * surfaces the lease id even if the on-disk lease file has since
+     * been gc'd.
+     *
+     * v3 (Part 4.C) makes this structurally required. v2 records
+     * missing the field upgrade to `null` on read (see
+     * `upgradeRecord`).
+     */
+    readonly leaseId: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 7: ISO timestamp of
+     * when the isolation mode was set up. For `--isolation worktree`
+     * this is the moment `peaks worktree spawn` returned; for
+     * `--isolation container` (Part 8) it's when the container
+     * runtime reported the container as running. `null` when the
+     * dispatch did not request isolation. Lets the dashboard
+     * compute isolation duration (now - isolationStartedAt) without
+     * cross-referencing the metrics stream.
+     */
+    readonly isolationStartedAt: string | null;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. One entry per pid the parent best-effort-killed during
+     * the service-shutdown phase of the merge-back pipeline (see
+     * src/services/dispatch/service-shutdown.ts). Empty array when
+     * the sub-agent did not register any services. The shape is the
+     * union of ServiceKillOutcome (skipped=false) and
+     * ServiceKillSkipped (skipped=true) — kept as a plain object
+     * here so the on-disk schema does not lock onto the helper's
+     * narrower union. The reader (merge-back-runner.ts) interprets
+     * each entry based on the `skipped` field.
+     */
+    readonly serviceKill: ReadonlyArray<{
+        readonly pid: number;
+        readonly name: string;
+        readonly signal: string;
+        readonly exitCode: number | null;
+        readonly skipped?: boolean;
+        readonly reason?: string;
+    }>;
+    /**
+     * Slice 2026-08-01-subagent-merge-and-e2e (Task 7): v3.2 schema
+     * bump. Counts how many merge attempts the parent session has
+     * made against this dispatch's branch. The conflict-replay
+     * orchestrator bumps this on each retry (bounded to ONE re-dispatch
+     * per merge attempt; multi-conflict cases escalate). Persisted so
+     * the dashboard can render the retry count without replaying the
+     * merge transcript.
+     */
+    readonly mergeBackAttempts: number;
+    /**
+     * Slice 4.0.8 RD §4 D4c (presence-lease-graph): the workflow id +
+     * graph node id + graphRef this dispatch is bound to. Persisted
+     * directly in the dispatch record (NOT in a sidecar) so the
+     * envelope-writer `markCompleted` can auto-transition the bound
+     * graph node to `envelope-received` with `ackStatus=pending` in
+     * one protected update.
+     *
+     * The schema bump from `3.2 → 4.0.0` is BREAKING in the sense
+     * that the literal type is narrowed. The optional `?` keeps back-
+     * compat for old records that pre-date the binding (the
+     * `upgradeRecord` reader defaults them to `null`).
+     */
+    readonly workflowId: string | null;
+    readonly graphNodeId: string | null;
+    readonly graphRef: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. `in-process` is the
+     * current behavior (LLM-side runner, no separate OS process).
+     * `detached` is the new path: `peaks sub-agent dispatch --mode
+     * detached` spawns a real child OS process running a different
+     * LLM vendor (claude / codex / copilot) and reports back via
+     * the dispatch record. v4.1.0 is the additive bump; legacy v4.0.0
+     * records upgrade to `in-process` on read.
+     */
+    readonly mode: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. `null` when
+     * the dispatch is in-process. Reserved for future use; current
+     * detached sub-agents use `claude` but the schema also accepts
+     * `codex` and `copilot` for the vendor-neutral adapter layer.
+     */
+    readonly vendor: 'claude' | 'codex' | 'copilot' | null;
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM during a detached run. Each event records the threshold
+     * that fired (0.85 = first warning, 0.95 = second warning) plus
+     * token counts before/after. Empty for in-process dispatches
+     * and for legacy records upgraded on read.
+     */
+    readonly autoCompactEvents: ReadonlyArray<{
+        readonly at: number;
+        readonly threshold: '0.85' | '0.95';
+        readonly tokensBefore: number;
+        readonly tokensAfter: number;
+        readonly scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting for detached sub-agents.
+     * Detached runs have "unlimited spend but recorded" semantics —
+     * the cost is recorded for audit but not enforced. `null` when
+     * the dispatch is in-process (no detached accounting) or for
+     * legacy records upgraded on read.
+     */
+    readonly tokenUsage: {
+        readonly promptTokens: number;
+        readonly completionTokens: number;
+        readonly totalCostUsd?: number;
+    } | null;
+}
+/** Input for the initial write. */
+export type WriteInitialDispatchInput = {
+    projectRoot: string;
+    sessionId: string;
+    requestId: string;
+    role: string;
+    prompt: string;
+    toolCall: SubAgentToolCall;
+    batchId: string;
+    /** Override the timestamp (testing). */
+    now?: () => Date;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 3.A: the worktree
+     * lease id this dispatch owns (set by `peaks sub-agent dispatch
+     * --isolation worktree`). Persisted so the finalize-time release
+     * hook in `markCompleted` can fire even after the dispatch
+     * process exits. Optional; absent when the dispatch did not
+     * request isolation.
+     */
+    leaseId?: string | null;
+    /**
+     * Slice 2026-07-29-worktree-l2-extended Part 7: ISO timestamp
+     * when the isolation mode was set up. Optional on the input
+     * (defaults to `null`); dispatch-commands.ts passes the spawn
+     * time when `--isolation` is requested.
+     */
+    isolationStartedAt?: string | null;
+    /**
+     * Slice 4.0.8: workflow graph binding for the dispatch. Defaults
+     * to `null` so a non-graph dispatch (legacy CLI flow, ad-hoc
+     * dispatch) still writes a v4.0.0 record.
+     */
+    workflowId?: string | null;
+    graphNodeId?: string | null;
+    graphRef?: string | null;
+    /**
+     * Phase A Task 8: dispatch execution mode. Default `'in-process'`
+     * preserves the current LLM-side runner behavior. `'detached'`
+     * triggers the new real-OS-process path via
+     * `peaks sub-agent dispatch --mode detached`.
+     */
+    mode?: 'in-process' | 'detached';
+    /**
+     * Phase A Task 8: vendor id when `mode='detached'`. Required by
+     * the adapter layer to know which CLI / runtime to spawn. The
+     * schema accepts the three vendors peaks-loop has adapters for
+     * (claude / codex / copilot). Ignored when `mode='in-process'`.
+     */
+    vendor?: 'claude' | 'codex' | 'copilot';
+    /**
+     * Phase A Task 8: G8 autoCompact events accumulated by the child
+     * LLM. Optional on input — most dispatches start with an empty
+     * array and the detached runner appends events as they fire.
+     */
+    autoCompactEvents?: Array<{
+        at: number;
+        threshold: '0.85' | '0.95';
+        tokensBefore: number;
+        tokensAfter: number;
+        scratchFile?: string;
+    }>;
+    /**
+     * Phase A Task 8: G8 token-usage accounting. Detached runs
+     * record spend for audit (unlimited, but persisted). Optional
+     * on input; the detached runner fills this in as it streams
+     * usage from the vendor API.
+     */
+    tokenUsage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalCostUsd?: number;
+    };
+};
+/** Heartbeat write input. */
+export type AppendHeartbeatInput = {
+    recordPath: string;
+    status: HeartbeatStatus;
+    progress: number;
+    note?: string;
+    now?: () => Date;
+};
+/** Lifecycle transition input. */
+export type LifecycleInput = {
+    recordPath: string;
+    outcome: DispatchOutcome;
+    status: DispatchRecordStatus;
+    artifactPaths?: readonly string[];
+    now?: () => Date;
+    /**
+     * Slice 2026-06-23-audit-4th #A4: trusted project root. Required
+     * so the active-dispatches index can be updated without deriving
+     * the root from the recordPath (the same anti-pattern that
+     * audit-3rd #1 fixed for heartbeat). The CLI / LLM-side runner
+     * passes this from `--project` or `process.cwd()`.
+     */
+    projectRoot?: string;
+};
+export declare const MAX_PROMPT_BYTES: number;
+export declare const NOTE_MAX_CHARS = 200;
+export declare const MS_PER_DAY: number;

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

@@ -0,0 +1,15 @@
+/**
+ * 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;
+export const MAX_PROMPT_BYTES = MAX_PROMPT_KB * BYTES_PER_KB;
+export 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;
+export const MS_PER_DAY = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+const REDACTION_MAX_SCAN_DEPTH = 20;