peaks-loop 4.0.29 → 4.0.31

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

@@ -31,7 +31,7 @@
 //   - 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 { CODEGRAPH_DIR_NAME, createCodegraphInvocation, defaultCodegraphInitGuard, executeCodegraphInvocation, isCodegraphInitialized, 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;
@@ -163,8 +163,11 @@ async function readStructure(projectRoot, runner) {
  *
  * 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 with peaks-loop marker AND `codegraph.db` →
+ *   skip init/index (fresh), read directly. No redundant re-index on
+ *   every dispatch.
+ * - `.codegraph/` present with peaks-loop marker but NO `codegraph.db`
+ *   (dangling) → init + index (self-heal), then read.
  * - `.codegraph/` present WITHOUT marker (foreign schema) → fail-soft;
  *   never clobber a foreign store.
  *
@@ -180,7 +183,10 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             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') {
+    // 'fresh' (no dir) OR a dangling peaks-loop dir (marker present, no
+    // codegraph.db) → run init + index. An initialized peaks-loop dir
+    // (`noop-already-peaks-loop` with codegraph.db) skips straight to read.
+    if (guard.status === 'fresh' || !isCodegraphInitialized(projectRoot)) {
         // 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.
@@ -220,7 +226,8 @@ export async function buildCodegraphPreflightBlock(projectRoot, runner) {
             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.
+    // guard.status === 'noop-already-peaks-loop' with codegraph.db (or we
+    // just initialized): the schema exists — do NOT re-index, go straight
+    // to the bounded read.
     return readStructure(projectRoot, processRunner);
 }

package/dist/services/codegraph/codegraph-service.d.ts

@@ -55,6 +55,12 @@ export declare const CODEGRAPH_DIR_NAME = ".codegraph";
  * etc. all happily use the same directory name).
  */
 export declare const CODEGRAPH_MARKER_NAME = ".peaks-loop-marker";
+/**
+ * Upstream SQLite schema filename. `isCodegraphInitialized` mirrors
+ * `@colbymchenry/codegraph`'s `isInitialized`, which requires this file
+ * (not just the `.codegraph/` directory) to exist.
+ */
+export declare const CODEGRAPH_DB_NAME = "codegraph.db";
 export declare const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
 export type ResolvedCodegraphLocation = {
     readonly source: 'root';
@@ -88,10 +94,19 @@ export declare class CodegraphInitConflictError extends Error {
     constructor(message: string, codegraphDir: string);
 }
 export type CodegraphInitGuard = (projectRoot: string) => CodegraphInitGuardResult;
+/**
+ * True when `<projectRoot>/.codegraph/codegraph.db` exists. Mirrors
+ * upstream `@colbymchenry/codegraph` `isInitialized`: the `.codegraph/`
+ * directory alone (or with only the peaks-loop marker) is NOT initialized.
+ * Pure fs probe; never throws.
+ */
+export declare function isCodegraphInitialized(projectRoot: string): boolean;
 /**
  * Root-only init guard: probes `<projectRoot>/.codegraph/`. 'fresh'
- * is returned when the directory does not exist yet, so the next
- * `peaks codegraph init` creates the root `.codegraph/` directory.
+ * is returned when the directory does not exist yet OR when it exists
+ * with the peaks-loop marker but no `codegraph.db` (dangling), so the
+ * next `peaks codegraph init` creates the root `.codegraph/` directory
+ * and its SQLite schema.
  */
 export declare function defaultCodegraphInitGuard(projectRoot: string): CodegraphInitGuardResult;
 /**

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

@@ -180,6 +180,12 @@ export const CODEGRAPH_DIR_NAME = '.codegraph';
  * etc. all happily use the same directory name).
  */
 export const CODEGRAPH_MARKER_NAME = '.peaks-loop-marker';
+/**
+ * Upstream SQLite schema filename. `isCodegraphInitialized` mirrors
+ * `@colbymchenry/codegraph`'s `isInitialized`, which requires this file
+ * (not just the `.codegraph/` directory) to exist.
+ */
+export const CODEGRAPH_DB_NAME = 'codegraph.db';
 export const CODEGRAPH_INIT_CONFLICT_EXIT_CODE = 73;
 /**
  * Root-only resolver: peaks-loop always manages
@@ -205,6 +211,15 @@ export class CodegraphInitConflictError extends Error {
         this.name = 'CodegraphInitConflictError';
     }
 }
+/**
+ * True when `<projectRoot>/.codegraph/codegraph.db` exists. Mirrors
+ * upstream `@colbymchenry/codegraph` `isInitialized`: the `.codegraph/`
+ * directory alone (or with only the peaks-loop marker) is NOT initialized.
+ * Pure fs probe; never throws.
+ */
+export function isCodegraphInitialized(projectRoot) {
+    return existsSync(join(projectRoot, CODEGRAPH_DIR_NAME, CODEGRAPH_DB_NAME));
+}
 /**
  * Inspect a candidate codegraph directory and return its guard
  * status. A file (or symlink-to-file) at the path counts as a
@@ -223,14 +238,24 @@ function inspectCandidateCodegraphDir(codegraphDir) {
     }
     const markerPath = join(codegraphDir, CODEGRAPH_MARKER_NAME);
     if (existsSync(markerPath)) {
+        // Marker present but no codegraph.db → the dangling state left by the
+        // pre-fix rid-CG-001 auto-stake (marker stamped without running
+        // upstream init). Report 'fresh' so consumers re-run upstream init
+        // (idempotent, creates the db) instead of treating the schema as
+        // fully initialized.
+        if (!existsSync(join(codegraphDir, CODEGRAPH_DB_NAME))) {
+            return { status: 'fresh', codegraphDir };
+        }
         return { status: 'noop-already-peaks-loop', codegraphDir };
     }
     return { status: 'conflict-foreign-schema', codegraphDir };
 }
 /**
  * Root-only init guard: probes `<projectRoot>/.codegraph/`. 'fresh'
- * is returned when the directory does not exist yet, so the next
- * `peaks codegraph init` creates the root `.codegraph/` directory.
+ * is returned when the directory does not exist yet OR when it exists
+ * with the peaks-loop marker but no `codegraph.db` (dangling), so the
+ * next `peaks codegraph init` creates the root `.codegraph/` directory
+ * and its SQLite schema.
  */
 export function defaultCodegraphInitGuard(projectRoot) {
     const codegraphDir = join(projectRoot, CODEGRAPH_DIR_NAME);

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

@@ -42,6 +42,32 @@ export interface DispatchPromptInput {
      *   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

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

@@ -98,13 +98,15 @@ 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, codegraphBlock } = 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}${codegraphText}${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}${codegraphText}${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
@@ -133,6 +135,39 @@ function renderCodegraphBlock(codegraphBlock) {
     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
  * `## Context window` block with the authoritative ratio so the

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;

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

@@ -0,0 +1,5 @@
+import type { DispatchOutcome, DispatchRecord, DispatchRecordStatus } from './dispatch-record-types.js';
+export declare function upgradeRecord(parsed: unknown): DispatchRecord;
+declare function isDispatchStatus(v: unknown): v is DispatchRecordStatus;
+declare function isOutcome(v: unknown): v is DispatchOutcome;
+export { isDispatchStatus, isOutcome };