peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/dispatch/contract-store.d.ts

@@ -0,0 +1,63 @@
+/** Public surface of a finished slice. */
+export interface SliceContract {
+    readonly sliceId: string;
+    readonly sessionId: string;
+    readonly completedAt: string;
+    /** Public exports (function / class / const / var names). */
+    readonly exports: readonly string[];
+    /** Public type names. */
+    readonly types: readonly string[];
+    /** Public function / method signatures, e.g. `"validateDag(dag: SliceDag): void"`. */
+    readonly publicSignatures: readonly string[];
+    /** Optional: which downstream slice IDs the contract is broadcast-ready for. */
+    readonly broadcastTo?: readonly string[];
+    /** SHA-256 hash of the contract payload (key-sorted, JSON-canonicalized). */
+    readonly contractHash: string;
+}
+export type WriteContractInput = Omit<SliceContract, 'completedAt' | 'contractHash'> & {
+    readonly completedAt?: string;
+};
+/** Thrown when contract IO fails. */
+export declare class ContractStoreError extends Error {
+    readonly code: "CONTRACT_STORE_ERROR";
+    constructor(message: string);
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for slice contracts. */
+export declare const CONTRACT_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this contract an orphan
+ * (older than CONTRACT_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` and `isOrphanDispatchRecord` so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export declare function isOrphanContract(opts: {
+    projectRoot: string;
+    sessionId: string;
+    sliceId: string;
+    now?: Date;
+}): boolean;
+/** Resolve the contracts directory for a session. */
+export declare function contractsDir(projectRoot: string, sessionId: string): string;
+/** Resolve a single contract file path. */
+export declare function contractPath(projectRoot: string, sessionId: string, sliceId: string): string;
+/** Hash a contract payload. */
+export declare function hashContract(c: WriteContractInput | SliceContract): string;
+/**
+ * Persist a slice's public contract. Returns the absolute path on disk.
+ * Idempotent: re-writing the same contract overwrites in place.
+ */
+export declare function writeContract(projectRoot: string, sessionId: string, input: WriteContractInput): {
+    path: string;
+    contract: SliceContract;
+};
+/** Read a contract from disk. Returns null if missing. */
+export declare function readContract(projectRoot: string, sessionId: string, sliceId: string): SliceContract | null;
+/** List all contracts for a session. */
+export declare function listContracts(projectRoot: string, sessionId: string): readonly SliceContract[];
+/**
+ * Format a prompt-injection block from a set of contracts. The block is a
+ * stable, human-readable summary suitable for splicing into a downstream
+ * slice's dispatch prompt.
+ */
+export declare function formatContractInjection(contracts: readonly SliceContract[]): string;

package/dist/services/dispatch/contract-store.js

@@ -0,0 +1,157 @@
+/**
+ * Contract broadcast store — 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a).
+ *
+ * When slice A finishes, A's public contract (exports / types / signatures)
+ * is written to `.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json`.
+ * Downstream slices (B, C, D) have their dispatch prompt auto-injected with
+ * the contract content for any ancestor slice already in `completed`.
+ *
+ * Why this exists:
+ *   Reading the source code of A from B's prompt inflates the prompt by
+ *   kilobytes. Contracts are a stable summary: just the public surface.
+ *
+ * Path layout (cross-platform safe):
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json`
+ *
+ * All paths are constructed with `path.join` (homedir + join style via
+ * Node `path.join`) to keep Windows / macOS / Linux interop.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Thrown when contract IO fails. */
+export class ContractStoreError extends Error {
+    code = 'CONTRACT_STORE_ERROR';
+    constructor(message) {
+        super(message);
+        this.name = 'ContractStoreError';
+    }
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for slice contracts. */
+export const CONTRACT_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this contract an orphan
+ * (older than CONTRACT_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` and `isOrphanDispatchRecord` so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export function isOrphanContract(opts) {
+    const path = contractPath(opts.projectRoot, opts.sessionId, opts.sliceId);
+    if (!existsSync(path))
+        return true;
+    const s = statSync(path);
+    const now = opts.now ?? new Date();
+    const ageMs = now.getTime() - s.mtimeMs;
+    const ttlMs = CONTRACT_TTL_DAYS * 24 * 60 * 60 * 1000;
+    return ageMs > ttlMs;
+}
+/** Resolve the contracts directory for a session. */
+export function contractsDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'dispatch', 'contracts');
+}
+/** Resolve a single contract file path. */
+export function contractPath(projectRoot, sessionId, sliceId) {
+    return join(contractsDir(projectRoot, sessionId), `${sliceId}.json`);
+}
+/** Canonicalize a contract for hashing. Keys sorted; arrays preserved. */
+function canonicalize(c) {
+    const obj = {
+        sliceId: c.sliceId,
+        sessionId: c.sessionId,
+        exports: [...c.exports].sort(),
+        types: [...c.types].sort(),
+        publicSignatures: [...c.publicSignatures].sort()
+    };
+    if ('completedAt' in c && c.completedAt !== undefined) {
+        obj.completedAt = c.completedAt;
+    }
+    if (c.broadcastTo !== undefined) {
+        obj.broadcastTo = [...c.broadcastTo].sort();
+    }
+    return JSON.stringify(obj);
+}
+/** Hash a contract payload. */
+export function hashContract(c) {
+    return createHash('sha256').update(canonicalize(c)).digest('hex');
+}
+/**
+ * Persist a slice's public contract. Returns the absolute path on disk.
+ * Idempotent: re-writing the same contract overwrites in place.
+ */
+export function writeContract(projectRoot, sessionId, input) {
+    if (!projectRoot || !sessionId) {
+        throw new ContractStoreError('projectRoot and sessionId are required');
+    }
+    if (!input.sliceId || input.sliceId.length === 0) {
+        throw new ContractStoreError('sliceId is required');
+    }
+    if (!Array.isArray(input.exports) || !Array.isArray(input.types) || !Array.isArray(input.publicSignatures)) {
+        throw new ContractStoreError('exports, types, publicSignatures must be arrays');
+    }
+    const completedAt = input.completedAt ?? new Date().toISOString();
+    const partial = { ...input, completedAt };
+    const contractHash = hashContract(partial);
+    const contract = {
+        sliceId: input.sliceId,
+        sessionId,
+        completedAt,
+        exports: [...input.exports],
+        types: [...input.types],
+        publicSignatures: [...input.publicSignatures],
+        ...(input.broadcastTo !== undefined ? { broadcastTo: [...input.broadcastTo] } : {}),
+        contractHash
+    };
+    const dir = contractsDir(projectRoot, sessionId);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const path = contractPath(projectRoot, sessionId, input.sliceId);
+    writeFileSync(path, JSON.stringify(contract, null, 2) + '\n', 'utf8');
+    return { path, contract };
+}
+/** Read a contract from disk. Returns null if missing. */
+export function readContract(projectRoot, sessionId, sliceId) {
+    const path = contractPath(projectRoot, sessionId, sliceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ContractStoreError(`failed to parse contract at ${path}: ${err.message}`);
+    }
+}
+/** List all contracts for a session. */
+export function listContracts(projectRoot, sessionId) {
+    const dir = contractsDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+    const out = [];
+    for (const f of files) {
+        const sliceId = f.replace(/\.json$/, '');
+        const c = readContract(projectRoot, sessionId, sliceId);
+        if (c !== null)
+            out.push(c);
+    }
+    // Stable order: by sliceId
+    return out.sort((a, b) => (a.sliceId < b.sliceId ? -1 : a.sliceId > b.sliceId ? 1 : 0));
+}
+/**
+ * Format a prompt-injection block from a set of contracts. The block is a
+ * stable, human-readable summary suitable for splicing into a downstream
+ * slice's dispatch prompt.
+ */
+export function formatContractInjection(contracts) {
+    if (contracts.length === 0)
+        return '';
+    const blocks = ['## Ancestor slice contracts (do not import source — use this surface)'];
+    for (const c of contracts) {
+        blocks.push('', `### slice ${c.sliceId} (completed ${c.completedAt}, hash=${c.contractHash.slice(0, 12)})`, `- exports: ${c.exports.length === 0 ? '(none)' : c.exports.join(', ')}`, `- types: ${c.types.length === 0 ? '(none)' : c.types.join(', ')}`, '- publicSignatures:', ...(c.publicSignatures.length === 0
+            ? ['  - (none)']
+            : c.publicSignatures.map((s) => `  - \`${s}\``)));
+    }
+    return blocks.join('\n');
+}

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

@@ -0,0 +1,260 @@
+import type { SubAgentToolCall } from './sub-agent-dispatcher.js';
+import { type StageLabel } from './stage-enum.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.
+     */
+    /**
+     * Slice 2026-07-29-rid-prose-only-sweep Part 34: schema v3.1
+     * is the explicit minor bump that records the
+     * `isolationStartedAt` (Part 7) and `leaseId` (Part 3.A.1 +
+     * Part 4.C) fields as part of the canonical schema. v3
+     * records on disk upgrade transparently — see `upgradeRecord`
+     * in this file. The literal type ('3.1') is the source of
+     * truth for "this record is v3.1-form"; readers check
+     * `version === '3.1'` for forward-compatible dispatching.
+     */
+    readonly version: '3.1';
+    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;
+}
+/** 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;
+};
+/** 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;
+};
+/** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
+export declare function writeInitialDispatchRecord(input: WriteInitialDispatchInput): {
+    path: string;
+    record: DispatchRecord;
+};
+/**
+ * Active-dispatches index. Per-session JSON file at
+ * `.peaks/_sub_agents/<sid>/active-dispatches.json`. Map<recordPath,
+ * ActiveDispatchEntry>. Updated on dispatch + completion.
+ */
+export interface ActiveDispatchEntry {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly role: string;
+    readonly batchId: string;
+    readonly createdAt: string;
+    readonly status: 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'stale' | 'no-execution' | 'never-started' | 'unreadable';
+}
+/**
+ * Slice 2026-06-23-audit-4th #A4: read the active-dispatches index
+ * for a session. Returns the current map<recordPath, entry>. Used
+ * by the LLM-side runner to discover in-flight records on restart.
+ * Returns an empty map when the index file is missing or corrupt
+ * (the on-disk records directory is the next fallback).
+ */
+export declare function readActiveDispatchIndex(projectRoot: string, sessionId: string): Record<string, ActiveDispatchEntry>;
+/** Slice 2026-06-23-audit-4th #A3: default TTL for dispatch records. */
+export declare const DISPATCH_RECORD_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this dispatch record an orphan
+ * (older than DISPATCH_RECORD_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` in shared-channel.ts so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export declare function isOrphanDispatchRecord(opts: {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    recordPath: string;
+    now?: Date;
+}): boolean;
+/** Append a heartbeat (G6). Idempotent on (at, status) — append-only. */
+export declare function appendHeartbeat(input: AppendHeartbeatInput): {
+    record: DispatchRecord;
+    truncated: boolean;
+};
+/** Apply truncation: keep most recent 100, mark truncated flag. */
+export declare function applyTruncation(entries: readonly Heartbeat[]): {
+    heartbeats: Heartbeat[];
+    truncated: boolean;
+};
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 3.A: fire-and-forget
+ * auto-release for the lease owned by a dispatch. Called from
+ * `markCompleted` (terminal status) and from the heartbeat CLI
+ * (`--status done`).
+ *
+ * Design:
+ * - The release subprocess is spawned ASYNC and detached. The
+ *   finalize-time caller (heartbeat / share / dispatch reducer)
+ *   does NOT await it; the caller's job is to record the
+ *   finalization, not to wait for the lease cleanup.
+ * - Failures are swallowed (best-effort, same as `git worktree
+ *   remove` inside `peaks worktree release` itself). The next
+ *   `peaks worktree gc` pass is the safety net.
+ * - Idempotent: re-calling with the same leaseId is a no-op on
+ *   the release side (the CLI refuses to re-release an already-
+ *   released lease; see Part 1 release command).
+ * - The leaseId MUST be 16-hex (same regex the gate uses). Any
+ *   other value is silently ignored — we never shell out to
+ *   `peaks worktree release` with attacker-controlled input.
+ */
+export declare function tryAutoReleaseLease(args: {
+    projectRoot: string;
+    sessionId: string;
+    leaseId: string;
+    /** Best-effort logging hook (e.g. logger.writeLogEntry). Returns null on failure. */
+    logger?: (line: string) => void;
+}): void;
+/** Mark a record as completed (success / failed / cancelled / no-execution). */
+export declare function markCompleted(input: LifecycleInput): {
+    record: DispatchRecord;
+};
+/** Mark a record as disposed (reducer ran). */
+export declare function markDisposed(recordPath: string, now?: () => Date): {
+    record: DispatchRecord;
+};
+/**
+ * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.1) — promote
+ * the record's `stage` field. Rejects unknown values with
+ * `INVALID_STAGE`; the LLM-side runner surfaces the error so the
+ * sub-agent can pick from the bounded enum in ./stage-enum.ts.
+ *
+ * Atomic via the same `withFileLockSync` lock as `appendHeartbeat` /
+ * `markCompleted`. `null` is a valid argument ("clear the stage")
+ * but unknown strings are not.
+ */
+export declare function setStage(input: {
+    recordPath: string;
+    stage: StageLabel | null;
+    now?: () => Date;
+}): {
+    record: DispatchRecord;
+};
+/**
+ * Read a dispatch record with backward-compat defaults. Old records
+ * missing G5 / G6 fields are upgraded on read (no error, no overwrite).
+ */
+export declare function readRecord(recordPath: string): DispatchRecord;
+/** Read multiple records from a list of paths. Tolerates missing files. */
+export declare function readRecords(paths: readonly string[]): DispatchRecord[];
+declare function isDispatchStatus(v: unknown): v is DispatchRecordStatus;
+declare function isOutcome(v: unknown): v is DispatchOutcome;
+export { isDispatchStatus, isOutcome };