peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/dispatch/heartbeat-truncator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * G6.4 / RL-16 — heartbeat truncation helper.
+ *
+ * Each dispatch record keeps an append-only `heartbeats[]` array so
+ * reducers / auditors can reconstruct what the sub-agent did. Without
+ * a cap, a long-running sub-agent can blow the record JSON past 1 MB
+ * (a 30s cadence over a 1-hour run = 120 entries * ~120 bytes = ~14 KB;
+ * a 5s cadence over 24h = 17 000 entries * ~120 bytes = ~2 MB). The
+ * 100-entry cap is LLM-friendly: stale heartbeats are not informative
+ * once the poller has read them, so dropping the oldest ones is a
+ * non-event.
+ *
+ * Pure helper; no IO. The writer in `dispatch-record-writer.ts` calls
+ * this on every `appendHeartbeat`. Exposed as a separate module so
+ * tests can pin the contract.
+ */
+import type { Heartbeat } from './dispatch-record-writer.js';
+export declare const HEARTBEAT_TRUNCATE_LIMIT = 100;
+export interface TruncationResult {
+    readonly heartbeats: readonly Heartbeat[];
+    readonly truncated: boolean;
+    /** The number of entries dropped by this truncation. */
+    readonly dropped: number;
+}
+/** Apply the 100-entry cap. Returns the most recent N entries + a flag. */
+export declare function truncateHeartbeats(entries: readonly Heartbeat[]): TruncationResult;

package/dist/services/dispatch/heartbeat-truncator.js

@@ -0,0 +1,13 @@
+export const HEARTBEAT_TRUNCATE_LIMIT = 100;
+/** Apply the 100-entry cap. Returns the most recent N entries + a flag. */
+export function truncateHeartbeats(entries) {
+    if (entries.length <= HEARTBEAT_TRUNCATE_LIMIT) {
+        return { heartbeats: [...entries], truncated: false, dropped: 0 };
+    }
+    const start = entries.length - HEARTBEAT_TRUNCATE_LIMIT;
+    return {
+        heartbeats: entries.slice(start),
+        truncated: true,
+        dropped: start
+    };
+}

package/dist/services/dispatch/leak-detector.d.ts

@@ -0,0 +1,11 @@
+import { type DispatchRecord } from './dispatch-record-writer.js';
+export declare const DEFAULT_LEAK_THRESHOLD_MS: number;
+export interface LeakedRecord {
+    readonly path: string;
+    readonly record: DispatchRecord;
+    readonly ageMs: number;
+}
+export declare function findLeakedDispatchRecords(projectRoot: string, sessionId: string, options?: {
+    now?: () => Date;
+    thresholdMs?: number;
+}): readonly LeakedRecord[];

package/dist/services/dispatch/leak-detector.js

@@ -0,0 +1,72 @@
+/**
+ * Slice #009 / G5 RL-7 — dispatch record leak detector.
+ *
+ * After peaks-code's reducer consumes a batch, any dispatch record that
+ * is still `disposed === false` AND was created more than `thresholdMs`
+ * ago is a **leak**. This helper scans the on-disk records under
+ * `.peaks/_sub_agents/<sid>/` and returns the leaked ones. The CLI or
+ * the reducer's next-batch step emits a user-visible warning when the
+ * list is non-empty.
+ *
+ * Threshold: 1h (configurable). Rationale: the longest empirical
+ * peaks-rd / peaks-qa fan-out + reducer cycle is < 60s; the threshold
+ * gives slow slices headroom without hiding leaks for the next session.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDispatchStatus, isOutcome } from './dispatch-record-writer.js';
+export const DEFAULT_LEAK_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
+export function findLeakedDispatchRecords(projectRoot, sessionId, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const thresholdMs = options.thresholdMs ?? DEFAULT_LEAK_THRESHOLD_MS;
+    const nowMs = now().getTime();
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+            continue;
+        const fullPath = join(dir, entry);
+        let raw;
+        try {
+            raw = readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            continue; // skip unreadable files
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue; // skip malformed files
+        }
+        if (!isRecordShape(parsed))
+            continue;
+        if (parsed.disposed === true)
+            continue;
+        const createdMs = Date.parse(parsed.createdAt);
+        if (Number.isNaN(createdMs))
+            continue;
+        const ageMs = nowMs - createdMs;
+        if (ageMs < thresholdMs)
+            continue;
+        out.push({ path: fullPath, record: parsed, ageMs });
+    }
+    return out;
+}
+function isRecordShape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const obj = v;
+    return (typeof obj.createdAt === 'string' &&
+        typeof obj.role === 'string' &&
+        typeof obj.requestId === 'string' &&
+        typeof obj.sessionId === 'string' &&
+        typeof obj.prompt === 'string' &&
+        isOutcome(obj.outcome) &&
+        isDispatchStatus(obj.status) &&
+        typeof obj.disposed === 'boolean' &&
+        Array.isArray(obj.artifactPaths));
+}

package/dist/services/dispatch/slice-dag.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Slice complexity tier (v2.15.0 follow-up, G2 in 12 Gaps).
+ * Used by Code to schedule complex slices during user-attended hours
+ * and trivial / simple slices overnight.
+ */
+export type SliceComplexity = 'trivial' | 'simple' | 'complex';
+export declare const SLICE_COMPLEXITIES: readonly SliceComplexity[];
+export declare function isSliceComplexity(value: string): value is SliceComplexity;
+export interface SliceNode {
+    readonly id: string;
+    readonly role: string;
+    /** Human-readable label, optional. */
+    readonly label?: string;
+    /** Optional prompt override; dispatch falls back to a default placeholder. */
+    readonly prompt?: string;
+    /**
+     * v2.15.0 follow-up — G12: foundation slice. Foundation slices run before
+     * business slices in the layered DAG. Business slices do NOT wait for
+     * ALL foundation slices — they wait only for the foundation subset
+     * they declare as `dependsOn`. Optional; default false.
+     */
+    readonly foundation?: boolean;
+    /**
+     * v2.15.0 follow-up — G11: upstream sync slice. Marks a slice that
+     * syncs an upstream fork (e.g. hermes) to a new tag. UpstreamSync
+     * slices take priority within their topological level. Optional.
+     */
+    readonly upstreamSync?: boolean;
+    /**
+     * v2.15.0 follow-up — G2: complexity tier. Drives Code's scheduling
+     * (complex = user-attended, simple/trivial = overnight). Optional.
+     */
+    readonly complexity?: SliceComplexity;
+}
+export interface DependsOn {
+    readonly from: string;
+    readonly to: string;
+}
+export interface SliceDag {
+    readonly nodes: readonly SliceNode[];
+    readonly edges: readonly DependsOn[];
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export declare class InvalidSliceDagError extends Error {
+    readonly path?: readonly string[] | undefined;
+    readonly code: "INVALID_SLICE_DAG";
+    constructor(message: string, path?: readonly string[] | undefined);
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export declare class SliceDagCycleError extends Error {
+    readonly cyclePath: readonly string[];
+    readonly code: "SLICE_DAG_CYCLE";
+    constructor(cyclePath: readonly string[]);
+}
+/**
+ * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
+ * Pure. Cheap. No I/O.
+ */
+export declare function validateDag(dag: SliceDag): void;
+/**
+ * Compute topological levels. Each level is an array of node IDs that can
+ * run in parallel. Throws `SliceDagCycleError` on cycle (defensive;
+ * `validateDag` should have caught it).
+ *
+ * Algorithm: Kahn's algorithm. O(V + E).
+ */
+export declare function topologicalLevels(dag: SliceDag): readonly (readonly string[])[];
+/**
+ * Return the next set of node IDs that are ready to run given the set of
+ * completed node IDs. A node is ready when all of its `from` predecessors
+ * are in `completed`.
+ */
+export declare function sliceReadyToRun(dag: SliceDag, completed: ReadonlySet<string>): readonly string[];
+/**
+ * Serialize the DAG into a deterministic JSON string. Node IDs are sorted;
+ * edges are sorted by `(from, to)`. The result is suitable for SHA-256
+ * hashing and for byte-stable diffs.
+ */
+export declare function serializeDag(dag: SliceDag): string;
+/** SHA-256 hash of the serialized DAG. Stable across runs. */
+export declare function hashDag(dag: SliceDag): string;
+/**
+ * Knobs for wave planning + artifact-pass behaviour.
+ *
+ * - `maxConcurrency`: hard cap on how many slices a single Wave can hold.
+ *   Each topological level is chunked into Waves of at most this many
+ *   slice IDs (default 6 per `2026-07-28-24h-loop-audit.md` E direction).
+ * - `passArtifacts`: when true, each Wave's prompt is augmented with a
+ *   `WaveArtifact` envelope (contracts of preceding Waves). Default
+ *   false — the existing `runDag` ancestor-injection path already covers
+ *   per-slice contract coverage.
+ */
+export interface WaveOptions {
+    readonly maxConcurrency: number;
+    readonly passArtifacts: boolean;
+}
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export declare const DEFAULT_MAX_CONCURRENCY = 6;
+export declare const DEFAULT_WAVE_OPTIONS: WaveOptions;
+/**
+ * Artifact envelope emitted when a Wave completes successfully.
+ *
+ * - `waveIndex`: sequential, 0-based across the whole plan.
+ * - `completedLeaves`: slice IDs that finished (`status: 'done'`). Failed
+ *    or cancelled leaves are NOT included.
+ * - `contracts`: per-slice public contract snapshot (sliceId → record).
+ *    Stored verbatim so a downstream Wave can re-inject this without
+ *    re-reading the disk-side contract store.
+ * - `passedAt`: ISO timestamp of Wave completion (caller-supplied to keep
+ *    the surface pure).
+ */
+export interface WaveArtifact {
+    readonly waveIndex: number;
+    readonly completedLeaves: readonly string[];
+    readonly contracts: Readonly<Record<string, unknown>>;
+    readonly passedAt: string;
+}
+/**
+ * A single dispatch Wave. Holds the slice IDs that must execute together,
+ * respecting `WaveOptions.maxConcurrency`. Waves are emitted in
+ * topological order; downstream consumers may treat `waveIndex` as a
+ * monotonic cursor.
+ */
+export interface Wave {
+    readonly waveIndex: number;
+    readonly slices: readonly string[];
+}

package/dist/services/dispatch/slice-dag.js

@@ -0,0 +1,244 @@
+/**
+ * Slice DAG model — 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a).
+ *
+ * Pure function module. No I/O. No external state.
+ *
+ * Types:
+ *   - `SliceNode` — a single unit of work (e.g. "implement CLI dispatch").
+ *   - `DependsOn` — directed edge from `to` to `from` (i.e. `to` runs after `from`).
+ *   - `SliceDag` — `{ nodes, edges }`. The graph MUST be a DAG.
+ *
+ * Constraints (validated by `validateDag`):
+ *   1. No cycles.
+ *   2. Node IDs are globally unique.
+ *   3. Every edge endpoints reference existing node IDs.
+ *   4. Node `role` is a non-empty string (whitelist hint, not a strict check).
+ *
+ * Why this lives outside `sub-agent-dispatcher.ts`:
+ *   The dispatcher is a per-IDE adapter; the DAG is a logical plan. Keeping
+ *   them split keeps the adapter file IDE-shape-focused and the DAG file
+ *   plan-shape-focused. Both are pure.
+ *
+ * Hash stability:
+ *   `serializeDag` sorts nodes by `id` and edges by `(from, to)` so the
+ *   resulting JSON string is stable across object-literal ordering. The
+ *   SHA-256 hash is therefore reproducible for the same logical DAG.
+ */
+import { createHash } from 'node:crypto';
+export const SLICE_COMPLEXITIES = [
+    'trivial',
+    'simple',
+    'complex'
+];
+export function isSliceComplexity(value) {
+    return SLICE_COMPLEXITIES.includes(value);
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export class InvalidSliceDagError extends Error {
+    path;
+    code = 'INVALID_SLICE_DAG';
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'InvalidSliceDagError';
+    }
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export class SliceDagCycleError extends Error {
+    cyclePath;
+    code = 'SLICE_DAG_CYCLE';
+    constructor(cyclePath) {
+        super(`cycle detected in slice DAG: ${cyclePath.join(' -> ')}`);
+        this.cyclePath = cyclePath;
+        this.name = 'SliceDagCycleError';
+    }
+}
+/**
+ * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
+ * Pure. Cheap. No I/O.
+ */
+export function validateDag(dag) {
+    if (!dag || !Array.isArray(dag.nodes) || !Array.isArray(dag.edges)) {
+        throw new InvalidSliceDagError('dag must have nodes and edges arrays');
+    }
+    if (dag.nodes.length === 0) {
+        throw new InvalidSliceDagError('dag must have at least one node');
+    }
+    const seen = new Set();
+    for (const n of dag.nodes) {
+        if (!n || typeof n.id !== 'string' || n.id.length === 0) {
+            throw new InvalidSliceDagError('every node must have a non-empty id');
+        }
+        if (typeof n.role !== 'string' || n.role.length === 0) {
+            throw new InvalidSliceDagError(`node ${n.id} must have a non-empty role`);
+        }
+        if (seen.has(n.id)) {
+            throw new InvalidSliceDagError(`duplicate node id: ${n.id}`);
+        }
+        seen.add(n.id);
+    }
+    for (const e of dag.edges) {
+        if (!e || typeof e.from !== 'string' || typeof e.to !== 'string') {
+            throw new InvalidSliceDagError('every edge must have string from/to');
+        }
+        if (!seen.has(e.from)) {
+            throw new InvalidSliceDagError(`edge references unknown node: ${e.from}`);
+        }
+        if (!seen.has(e.to)) {
+            throw new InvalidSliceDagError(`edge references unknown node: ${e.to}`);
+        }
+        if (e.from === e.to) {
+            throw new InvalidSliceDagError(`self-loop not allowed: ${e.from}`);
+        }
+    }
+    // v2.15.0 follow-up — G12: validate optional new fields ONLY when present
+    // (老 DAG 不强制要求新字段,保持向后兼容).
+    for (const n of dag.nodes) {
+        if (n.foundation !== undefined && typeof n.foundation !== 'boolean') {
+            throw new InvalidSliceDagError(`node ${n.id} foundation must be boolean when present`);
+        }
+        if (n.upstreamSync !== undefined && typeof n.upstreamSync !== 'boolean') {
+            throw new InvalidSliceDagError(`node ${n.id} upstreamSync must be boolean when present`);
+        }
+        if (n.complexity !== undefined && !isSliceComplexity(n.complexity)) {
+            throw new InvalidSliceDagError(`node ${n.id} complexity must be one of ${SLICE_COMPLEXITIES.join('|')} when present`);
+        }
+    }
+    // v2.15.0 follow-up — G12 defensive rule: foundation slice can only
+    // depend on another foundation slice. Business depending on foundation
+    // is the main use case; foundation depending on business is a smell.
+    const foundationSet = new Set(dag.nodes.filter((n) => n.foundation === true).map((n) => n.id));
+    for (const e of dag.edges) {
+        if (foundationSet.has(e.to) && !foundationSet.has(e.from)) {
+            throw new InvalidSliceDagError(`foundation slice ${e.to} cannot depend on non-foundation slice ${e.from}`);
+        }
+    }
+}
+/**
+ * Compute topological levels. Each level is an array of node IDs that can
+ * run in parallel. Throws `SliceDagCycleError` on cycle (defensive;
+ * `validateDag` should have caught it).
+ *
+ * Algorithm: Kahn's algorithm. O(V + E).
+ */
+export function topologicalLevels(dag) {
+    validateDag(dag);
+    const indeg = new Map();
+    const adj = new Map();
+    // v2.15.0 follow-up — G12: priority sets for foundation / upstreamSync.
+    const foundationSet = new Set(dag.nodes.filter((n) => n.foundation === true).map((n) => n.id));
+    const upstreamSyncSet = new Set(dag.nodes.filter((n) => n.upstreamSync === true).map((n) => n.id));
+    for (const n of dag.nodes) {
+        indeg.set(n.id, 0);
+        adj.set(n.id, []);
+    }
+    for (const e of dag.edges) {
+        // Edge `from -> to` means `to` depends on `from`; `to` has one more incoming.
+        indeg.set(e.to, (indeg.get(e.to) ?? 0) + 1);
+        adj.get(e.from)?.push(e.to);
+    }
+    const levels = [];
+    let frontier = dag.nodes.map((n) => n.id).filter((id) => (indeg.get(id) ?? 0) === 0);
+    const consumed = new Set();
+    while (frontier.length > 0) {
+        // v2.15.0 follow-up — G12: sort frontier by (foundation desc,
+        // upstreamSync desc, id asc). Stable across calls.
+        const sortedFrontier = [...frontier].sort((a, b) => {
+            const aF = foundationSet.has(a) ? 1 : 0;
+            const bF = foundationSet.has(b) ? 1 : 0;
+            if (aF !== bF)
+                return bF - aF;
+            const aU = upstreamSyncSet.has(a) ? 1 : 0;
+            const bU = upstreamSyncSet.has(b) ? 1 : 0;
+            if (aU !== bU)
+                return bU - aU;
+            return a < b ? -1 : a > b ? 1 : 0;
+        });
+        levels.push(sortedFrontier);
+        const next = [];
+        for (const id of sortedFrontier) {
+            consumed.add(id);
+            for (const succ of adj.get(id) ?? []) {
+                const d = (indeg.get(succ) ?? 0) - 1;
+                indeg.set(succ, d);
+                if (d === 0 && !consumed.has(succ)) {
+                    next.push(succ);
+                }
+            }
+        }
+        frontier = next;
+    }
+    if (consumed.size !== dag.nodes.length) {
+        // Find a cycle path for the error message.
+        const remaining = dag.nodes.map((n) => n.id).filter((id) => !consumed.has(id));
+        throw new SliceDagCycleError(remaining);
+    }
+    return levels;
+}
+/**
+ * Return the next set of node IDs that are ready to run given the set of
+ * completed node IDs. A node is ready when all of its `from` predecessors
+ * are in `completed`.
+ */
+export function sliceReadyToRun(dag, completed) {
+    validateDag(dag);
+    const done = new Set(completed);
+    const predecessors = new Map();
+    for (const n of dag.nodes) {
+        predecessors.set(n.id, []);
+    }
+    for (const e of dag.edges) {
+        predecessors.get(e.to)?.push(e.from);
+    }
+    const ready = [];
+    for (const n of dag.nodes) {
+        if (done.has(n.id))
+            continue;
+        const preds = predecessors.get(n.id) ?? [];
+        if (preds.every((p) => done.has(p))) {
+            ready.push(n.id);
+        }
+    }
+    return ready.sort();
+}
+/**
+ * Serialize the DAG into a deterministic JSON string. Node IDs are sorted;
+ * edges are sorted by `(from, to)`. The result is suitable for SHA-256
+ * hashing and for byte-stable diffs.
+ */
+export function serializeDag(dag) {
+    validateDag(dag);
+    const nodes = [...dag.nodes]
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map((n) => ({
+        id: n.id,
+        role: n.role,
+        ...(n.label !== undefined ? { label: n.label } : {}),
+        ...(n.prompt !== undefined ? { prompt: n.prompt } : {}),
+        // v2.15.0 follow-up — G12: include new fields in serialization
+        // (only when present, preserving hash stability for old DAGs).
+        ...(n.foundation !== undefined ? { foundation: n.foundation } : {}),
+        ...(n.upstreamSync !== undefined ? { upstreamSync: n.upstreamSync } : {}),
+        ...(n.complexity !== undefined ? { complexity: n.complexity } : {})
+    }));
+    const edges = [...dag.edges]
+        .sort((a, b) => {
+        if (a.from !== b.from)
+            return a.from < b.from ? -1 : 1;
+        if (a.to !== b.to)
+            return a.to < b.to ? -1 : 1;
+        return 0;
+    })
+        .map((e) => ({ from: e.from, to: e.to }));
+    return JSON.stringify({ nodes, edges });
+}
+/** SHA-256 hash of the serialized DAG. Stable across runs. */
+export function hashDag(dag) {
+    return createHash('sha256').update(serializeDag(dag)).digest('hex');
+}
+/** Default wave options: 6 leaves per wave; artifact-pass off. */
+export const DEFAULT_MAX_CONCURRENCY = 6;
+export const DEFAULT_WAVE_OPTIONS = {
+    maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+    passArtifacts: false
+};

package/dist/services/dispatch/stage-enum.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 — bounded stage
+ * vocabulary.
+ *
+ * Why a bounded enum (not a free-form string):
+ *   - a free-form `stage` recreates the `note` field, which already
+ *     exists and did not solve visibility.
+ *   - the watch surface renders a stage label inline (`role 30%
+ *     (5s ago) [planning]`); an unbounded vocabulary would let typos
+ *     and near-duplicates spread across the swarm.
+ *   - the LLM-side runner can validate the stage at write time
+ *     (`setStage` rejects unknown values with `INVALID_STAGE`).
+ *
+ * The enum is intentionally small and stable. Adding a new stage is a
+ * deliberate code change (this file + the `setStage` validation) so a
+ * future user cannot accidentally flood the watch with `awaiting-coffee`
+ * or `idk`.
+ *
+ * `null` is NOT a stage — it is the absence of a stage. Records that
+ * have not yet been promoted carry `stage: null`; the watch surface
+ * renders no marker.
+ */
+export declare const STAGE_LABELS: readonly ["intake", "planning", "gathering", "analyzing", "writing", "testing", "reviewing", "finalizing"];
+export type StageLabel = (typeof STAGE_LABELS)[number];
+export declare const DEFAULT_STAGE_LABELS: readonly StageLabel[];
+export declare function isStageLabel(value: unknown): value is StageLabel;
+export declare function normalizeStage(value: string | null | undefined): StageLabel | null;

package/dist/services/dispatch/stage-enum.js

@@ -0,0 +1,48 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 — bounded stage
+ * vocabulary.
+ *
+ * Why a bounded enum (not a free-form string):
+ *   - a free-form `stage` recreates the `note` field, which already
+ *     exists and did not solve visibility.
+ *   - the watch surface renders a stage label inline (`role 30%
+ *     (5s ago) [planning]`); an unbounded vocabulary would let typos
+ *     and near-duplicates spread across the swarm.
+ *   - the LLM-side runner can validate the stage at write time
+ *     (`setStage` rejects unknown values with `INVALID_STAGE`).
+ *
+ * The enum is intentionally small and stable. Adding a new stage is a
+ * deliberate code change (this file + the `setStage` validation) so a
+ * future user cannot accidentally flood the watch with `awaiting-coffee`
+ * or `idk`.
+ *
+ * `null` is NOT a stage — it is the absence of a stage. Records that
+ * have not yet been promoted carry `stage: null`; the watch surface
+ * renders no marker.
+ */
+export const STAGE_LABELS = [
+    'intake',
+    'planning',
+    'gathering',
+    'analyzing',
+    'writing',
+    'testing',
+    'reviewing',
+    'finalizing'
+];
+export const DEFAULT_STAGE_LABELS = STAGE_LABELS;
+export function isStageLabel(value) {
+    return typeof value === 'string' && STAGE_LABELS.includes(value);
+}
+export function normalizeStage(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (isStageLabel(trimmed))
+        return trimmed;
+    return null;
+}

package/dist/services/dispatch/startup-timeout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S1 — startup-timeout service.
+ *
+ * Why a separate module (vs adding the logic inline to
+ * `dispatch-record-writer.ts`):
+ *   - the writer is the on-disk format owner; the eval logic is a small
+ *     pure function over a `DispatchRecord` snapshot.
+ *   - keeps the writer surface unchanged (no extra `markStartupTimeout`
+ *     method) so other consumers (heartbeat, watch, batch poller) do not
+ *     have to learn a new mutation API.
+ *   - a future `markStartupTimeout` writer helper, if added, would import
+ *     this module's STARTUP_OUTCOME / DEFAULT_STARTUP_BUDGET_MS so the
+ *     CLI help text and the eval share a single source of truth.
+ *
+ * Contract (see tests/unit/dispatch/startup-timeout.test.ts for the
+ * pinned assertions):
+ *
+ *   evaluateStartupTimeout(record, now, opts) → StartupTimeoutEvaluation
+ *
+ *     - `outcome: 'within-budget' | 'never-started' | 'unreadable'`
+ *     - `targetStatus: DispatchRecordStatus` — the status to write when
+ *       `marked === true`. Distinct from `stale` (heartbeat seen, gone
+ *       quiet) and from `no-execution` (the pre-slice silent default).
+ *     - `marked: boolean` — whether the caller should write
+ *       `targetStatus` to the record.
+ *     - `reason: string` — short human-readable rationale, rendered in
+ *       the watcher text line and in the dispatch envelope's
+ *       `notes[]`.
+ *
+ *   DEFAULT_STARTUP_BUDGET_MS = 60_000
+ *     - 1 order of magnitude above the measured 4–6s cold-start figure
+ *       from .peaks/memory/2026-07-28-sub-agent-visibility-issue.md
+ *     - well below the 5-minute heartbeat stale threshold so this
+ *       fires first
+ *     - configurable via opts.budgetMs
+ *
+ *   STARTUP_OUTCOME = { NEVER_STARTED: 'never-started', UNREADABLE:
+ *   'unreadable' }
+ *     - exported so the CLI help text, the watch command, and the
+ *       reader's legacy fallback all reference the same strings.
+ */
+import type { DispatchRecord, DispatchRecordStatus } from './dispatch-record-writer.js';
+/**
+ * Default budget: 60s. 1 order of magnitude above the measured 4–6s
+ * cold-start figure from .peaks/memory/2026-07-28-sub-agent-visibility-
+ * issue.md; well below the 5-min heartbeat stale threshold so this
+ * fires first.
+ */
+export declare const DEFAULT_STARTUP_BUDGET_MS = 60000;
+/**
+ * String constants for the new terminal statuses. Distinct from the
+ * pre-slice `stale` (heartbeat seen, then quiet) and `no-execution`
+ * (legacy silent fallback). These are added to the writer's
+ * `DispatchRecordStatus` union in the same slice; the constants here
+ * are the canonical source so the CLI help / watch / writer all
+ * reference the same strings.
+ */
+export declare const STARTUP_OUTCOME: {
+    readonly NEVER_STARTED: "never-started";
+    readonly UNREADABLE: "unreadable";
+};
+export type StartupTimeoutOutcome = 'within-budget' | 'never-started' | 'unreadable';
+export interface StartupTimeoutOptions {
+    /** Override the default 60s budget. */
+    readonly budgetMs?: number;
+    /**
+     * Test seam: when true, the record is treated as if its body is
+     * corrupt (status field unparseable). The function returns
+     * `{ outcome: 'unreadable', ... }` and recommends writing the
+     * `unreadable` status. The CLI never sets this; the read path does.
+     */
+    readonly corrupt?: boolean;
+}
+export interface StartupTimeoutEvaluation {
+    readonly outcome: StartupTimeoutOutcome;
+    readonly marked: boolean;
+    readonly targetStatus: DispatchRecordStatus;
+    readonly reason: string;
+    readonly ageMs: number;
+    readonly budgetMs: number;
+}
+/**
+ * Pure eval. Returns a typed triple; the caller decides whether to
+ * write `targetStatus` to the record.
+ */
+export declare function evaluateStartupTimeout(record: DispatchRecord, now?: () => Date, options?: StartupTimeoutOptions): StartupTimeoutEvaluation;