peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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

@@ -0,0 +1,460 @@
+/**
+ * Dispatch record writer — slice 2026-06-07-sub-agent-dispatch-decouple (G2 + G5 + G6).
+ *
+ * Owns the on-disk format of `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`:
+ *   - G2: atomic write helper (mkdirSync recursive + tmp + rename) and
+ *     R-2 guard (path must live under `.peaks/_sub_agents/<sid>/`).
+ *   - G5: lifecycle schema (`createdAt` / `completedAt` / `outcome` /
+ *     `artifactPaths` / `disposed` / `disposedAt`) per AC-26 + RL-6..RL-9.
+ *   - G6: heartbeat schema upgrade per AC-33/AC-34 — `heartbeats[]` +
+ *     `lastBeatAt` + `status` aggregate. Read-side backward compat
+ *     supplies defaults for old records missing the G6 fields.
+ *
+ * The write helpers are intentionally small and pure:
+ *   - `writeInitialDispatchRecord`: append a new dispatch record at the
+ *     start of a sub-agent dispatch (called by `peaks sub-agent dispatch`).
+ *   - `appendHeartbeat`: append one heartbeat to an existing record
+ *     (called by `peaks sub-agent heartbeat`).
+ *   - `markCompleted` / `markFailed` / `markCancelled` / `markNoExecution`:
+ *     lifecycle transitions called by the reducer.
+ *
+ * All writes are atomic (tmp + rename) so a process crash mid-write
+ * cannot leave a half-truncated JSON file. All reads tolerate missing
+ * G6 fields (backward compat) and the G5 schema fields default to
+ * `null` / `false` / `'no-execution'` if the file was written by an
+ * older peaks build.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { assertSafeDispatchRecordPath, dispatchRecordPath } from '../security/safe-settings-path.js';
+import { withFileLockSync } from '../filesystem/file-lock.js';
+const MAX_PROMPT_BYTES = 256 * 1024;
+/** Write a new dispatch record (G2 + G5 + G6). Returns the absolute path. */
+export function writeInitialDispatchRecord(input) {
+    const { projectRoot, sessionId, requestId, role, prompt, toolCall, batchId } = input;
+    const now = input.now ?? (() => new Date());
+    if (prompt.length > MAX_PROMPT_BYTES) {
+        const err = new Error(`prompt exceeds ${MAX_PROMPT_BYTES} bytes (got ${prompt.length}); ` +
+            `truncate or split into multiple dispatches`);
+        err.code = 'PROMPT_TOO_LARGE';
+        throw err;
+    }
+    const path = dispatchRecordPath(projectRoot, sessionId, requestId, now());
+    const safePath = assertSafeDispatchRecordPath(path, projectRoot);
+    const record = {
+        version: 2,
+        createdAt: now().toISOString(),
+        completedAt: null,
+        outcome: 'no-execution',
+        artifactPaths: [],
+        disposed: false,
+        disposedAt: null,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        // Slice 2026-06-23-audit-4th #C2: propagate toolCallVersion.
+        // The dispatcher's buildToolCall already stamps it (claude-code 2.0.0
+        // etc.); we re-default to '2.0.0' if absent so the on-disk record
+        // is self-describing without reading the dispatcher source.
+        toolCall: { ...toolCall, toolCallVersion: toolCall.toolCallVersion ?? '2.0.0' },
+        batchId,
+        heartbeats: [],
+        lastBeatAt: null,
+        status: 'queued'
+    };
+    writeAtomic(safePath, record);
+    // Slice 2026-06-23-audit-4th #A4: register the path in the
+    // session's active-dispatches index so a future restart can
+    // discover in-flight records without scanning the directory.
+    // The index is best-effort (no lock): the on-disk record is the
+    // source of truth; the index is purely a hint for the LLM-side
+    // runner. A crash between writeAtomic and the index write is
+    // non-fatal — the next restart scans the directory anyway.
+    registerActiveDispatch({
+        projectRoot,
+        sessionId,
+        recordPath: safePath,
+        requestId,
+        role,
+        batchId,
+        now
+    });
+    return { path: safePath, record };
+}
+function activeDispatchIndexPath(projectRoot, sessionId) {
+    return resolve(projectRoot, '.peaks', '_sub_agents', sessionId, 'active-dispatches.json');
+}
+function registerActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    const dir = dirname(indexPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    let index = {};
+    try {
+        if (existsSync(indexPath)) {
+            const raw = readFileSync(indexPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === 'object' && parsed !== null) {
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                        index[k] = v;
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Corrupt index — start fresh. The on-disk record is the source of truth.
+        index = {};
+    }
+    index[input.recordPath] = {
+        recordPath: input.recordPath,
+        requestId: input.requestId,
+        role: input.role,
+        batchId: input.batchId,
+        createdAt: input.now().toISOString(),
+        status: 'queued'
+    };
+    const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+    renameSync(tmp, indexPath);
+}
+function unregisterActiveDispatch(input) {
+    const indexPath = activeDispatchIndexPath(input.projectRoot, input.sessionId);
+    if (!existsSync(indexPath))
+        return;
+    let index = {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null) {
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === 'object' && v !== null && 'recordPath' in v) {
+                    index[k] = v;
+                }
+            }
+        }
+    }
+    catch {
+        return;
+    }
+    if (input.recordPath in index) {
+        index[input.recordPath] = { ...index[input.recordPath], status: input.status };
+        if (input.status === 'done' || input.status === 'failed' || input.status === 'cancelled' || input.status === 'no-execution') {
+            delete index[input.recordPath];
+        }
+        const tmp = `${indexPath}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(index, null, 2) + '\n', 'utf8');
+        renameSync(tmp, indexPath);
+    }
+}
+/**
+ * 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 function readActiveDispatchIndex(projectRoot, sessionId) {
+    const indexPath = activeDispatchIndexPath(projectRoot, sessionId);
+    if (!existsSync(indexPath))
+        return {};
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === 'object' && v !== null && 'recordPath' in v && 'role' in v) {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for dispatch records. */
+export 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 function isOrphanDispatchRecord(opts) {
+    if (!existsSync(opts.recordPath))
+        return true;
+    const s = statSync(opts.recordPath);
+    const now = opts.now ?? new Date();
+    const ageMs = now.getTime() - s.mtimeMs;
+    const ttlMs = DISPATCH_RECORD_TTL_DAYS * 24 * 60 * 60 * 1000;
+    return ageMs > ttlMs;
+}
+/** Append a heartbeat (G6). Idempotent on (at, status) — append-only. */
+export function appendHeartbeat(input) {
+    const { recordPath, status, progress, note } = input;
+    const now = input.now ?? (() => new Date());
+    if (!Number.isInteger(progress) || progress < 0 || progress > 100) {
+        const err = new Error(`progress must be integer 0..100 (got ${progress})`);
+        err.code = 'INVALID_PROGRESS';
+        throw err;
+    }
+    if (note !== undefined && note.length > 200) {
+        const err = new Error(`note must be ≤ 200 chars (got ${note.length})`);
+        err.code = 'NOTE_TOO_LONG';
+        throw err;
+    }
+    const existing = readRecord(recordPath);
+    const entry = {
+        at: now().toISOString(),
+        status,
+        progress,
+        note: note ?? null
+    };
+    const { heartbeats, truncated } = applyTruncation([...existing.heartbeats, entry]);
+    const next = {
+        ...existing,
+        heartbeats,
+        lastBeatAt: entry.at,
+        status: mapStatusToAggregate(status, existing.status)
+    };
+    // Slice 2026-06-23-audit-3rd #3: wrap the read-then-write in a file
+    // lock. Without the lock, a heartbeat arriving 100ms before
+    // markCompleted can be silently discarded — the parent's view of the
+    // sub-agent shows "completed" but the last progress update is lost.
+    return withFileLockSync(recordPath, () => {
+        // Re-read under the lock — the file may have been mutated between
+        // our pre-lock `readRecord` above and lock acquisition (heartbeats
+        // and markCompleted share the same record file).
+        const lockedExisting = readRecord(recordPath);
+        const lockedHeartbeats = applyTruncation([
+            ...lockedExisting.heartbeats,
+            entry
+        ]).heartbeats;
+        const lockedNext = {
+            ...lockedExisting,
+            heartbeats: lockedHeartbeats,
+            lastBeatAt: entry.at,
+            status: mapStatusToAggregate(status, lockedExisting.status)
+        };
+        writeAtomic(recordPath, lockedNext);
+        // Recompute truncated flag from the locked-read result so the
+        // caller sees the actual post-lock truncation state.
+        return {
+            record: lockedNext,
+            truncated: lockedHeartbeats.length < lockedExisting.heartbeats.length + 1
+        };
+    });
+}
+/** Apply truncation: keep most recent 100, mark truncated flag. */
+export function applyTruncation(entries) {
+    if (entries.length <= 100) {
+        return { heartbeats: [...entries], truncated: false };
+    }
+    return { heartbeats: entries.slice(-100), truncated: true };
+}
+function mapStatusToAggregate(latest, current) {
+    // 'stale' is a poller-driven warning and must not be overwritten by
+    // a normal heartbeat that arrives after the stale flag was set.
+    if (current === 'stale') {
+        return 'stale';
+    }
+    return latest;
+}
+/** Mark a record as completed (success / failed / cancelled / no-execution). */
+export function markCompleted(input) {
+    // Slice 2026-06-23-audit-3rd #3: lock + re-read so a concurrent
+    // heartbeat arriving just before markCompleted is preserved in the
+    // final record.
+    const result = withFileLockSync(input.recordPath, () => {
+        const existing = readRecord(input.recordPath);
+        const next = {
+            ...existing,
+            completedAt: (input.now ?? (() => new Date()))().toISOString(),
+            outcome: input.outcome,
+            status: input.status,
+            artifactPaths: input.artifactPaths ?? existing.artifactPaths
+        };
+        writeAtomic(input.recordPath, next);
+        return { record: next };
+    });
+    // Slice 2026-06-23-audit-4th #A4: update the active-dispatches
+    // index. Best-effort (the on-disk record is the source of truth);
+    // we only attempt the update when the trusted projectRoot is
+    // available so a malicious recordPath cannot redirect the index
+    // write (audit-3rd #1 anti-pattern).
+    if (typeof input.projectRoot === 'string' && input.projectRoot.length > 0) {
+        try {
+            unregisterActiveDispatch({
+                projectRoot: input.projectRoot,
+                sessionId: result.record.sessionId,
+                recordPath: input.recordPath,
+                status: input.status
+            });
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort */
+        }
+    }
+    return result;
+}
+/** Mark a record as disposed (reducer ran). */
+export function markDisposed(recordPath, now = () => new Date()) {
+    // Lock + re-read (see markCompleted).
+    return withFileLockSync(recordPath, () => {
+        const existing = readRecord(recordPath);
+        const next = {
+            ...existing,
+            disposed: true,
+            disposedAt: now().toISOString()
+        };
+        writeAtomic(recordPath, next);
+        return { record: next };
+    });
+}
+/**
+ * Read a dispatch record with backward-compat defaults. Old records
+ * missing G5 / G6 fields are upgraded on read (no error, no overwrite).
+ */
+export function readRecord(recordPath) {
+    if (!existsSync(recordPath)) {
+        const err = new Error(`Dispatch record not found: ${recordPath}`);
+        err.code = 'RECORD_NOT_FOUND';
+        err.path = recordPath;
+        throw err;
+    }
+    const raw = readFileSync(recordPath, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const err = new Error(`Invalid dispatch record JSON: ${error.message}`);
+        err.code = 'INVALID_RECORD_JSON';
+        throw err;
+    }
+    return upgradeRecord(parsed);
+}
+/** Read multiple records from a list of paths. Tolerates missing files. */
+export function readRecords(paths) {
+    const out = [];
+    for (const p of paths) {
+        try {
+            out.push(readRecord(p));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'RECORD_NOT_FOUND') {
+                continue;
+            }
+            throw error;
+        }
+    }
+    return out;
+}
+function upgradeRecord(parsed) {
+    if (!isObject(parsed)) {
+        throw new Error('Dispatch record root must be an object');
+    }
+    const obj = parsed;
+    const role = stringField(obj, 'role');
+    const requestId = stringField(obj, 'requestId');
+    const sessionId = stringField(obj, 'sessionId');
+    const prompt = stringField(obj, 'prompt');
+    // Slice 2026-06-23-audit-4th #C2: preserve toolCallVersion on read.
+    // Pre-versioning records default to '2.0.0' (the pre-#C2 implicit
+    // shape; matches the version stamped by every current dispatcher).
+    const rawToolCall = obj.toolCall;
+    if (!isObject(rawToolCall) || typeof rawToolCall.name !== 'string') {
+        throw new Error('Dispatch record toolCall must be { name, args }');
+    }
+    const toolCall = {
+        name: rawToolCall.name,
+        args: (isObject(rawToolCall.args) ? rawToolCall.args : {}),
+        ...(typeof rawToolCall.toolCallVersion === 'string' ? { toolCallVersion: rawToolCall.toolCallVersion } : { toolCallVersion: '2.0.0' })
+    };
+    const createdAt = stringField(obj, 'createdAt');
+    const heartbeats = Array.isArray(obj.heartbeats)
+        ? obj.heartbeats.filter(isValidHeartbeat)
+        : [];
+    const lastBeatAt = typeof obj.lastBeatAt === 'string' ? obj.lastBeatAt : null;
+    const status = isDispatchStatus(obj.status) ? obj.status : 'no-execution';
+    const completedAt = typeof obj.completedAt === 'string' ? obj.completedAt : null;
+    const outcome = isOutcome(obj.outcome) ? obj.outcome : 'no-execution';
+    const artifactPaths = Array.isArray(obj.artifactPaths)
+        ? obj.artifactPaths.filter((p) => typeof p === 'string')
+        : [];
+    const disposed = obj.disposed === true;
+    const disposedAt = typeof obj.disposedAt === 'string' ? obj.disposedAt : null;
+    const batchId = typeof obj.batchId === 'string' && obj.batchId.length > 0
+        ? obj.batchId
+        : 'legacy-batch';
+    return {
+        version: 2,
+        createdAt,
+        completedAt,
+        outcome,
+        artifactPaths,
+        disposed,
+        disposedAt,
+        role,
+        requestId,
+        sessionId,
+        prompt,
+        toolCall,
+        batchId,
+        heartbeats,
+        lastBeatAt,
+        status
+    };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function stringField(obj, key) {
+    const v = obj[key];
+    if (typeof v !== 'string') {
+        throw new Error(`Dispatch record field '${key}' must be a string (got ${typeof v})`);
+    }
+    return v;
+}
+function isValidHeartbeat(v) {
+    if (!isObject(v))
+        return false;
+    return (typeof v.at === 'string' &&
+        isHeartbeatStatus(v.status) &&
+        typeof v.progress === 'number' &&
+        (v.note === null || typeof v.note === 'string'));
+}
+function isHeartbeatStatus(v) {
+    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
+        v === 'done' || v === 'failed' || v === 'stale');
+}
+function isDispatchStatus(v) {
+    return (v === 'queued' || v === 'running' || v === 'finalizing' ||
+        v === 'done' || v === 'failed' || v === 'cancelled' ||
+        v === 'no-execution' || v === 'stale');
+}
+function isOutcome(v) {
+    return (v === 'success' || v === 'failed' || v === 'timeout' ||
+        v === 'cancelled' || v === 'no-execution');
+}
+export { isDispatchStatus, isOutcome };
+function writeAtomic(path, record) {
+    const dir = dirname(path);
+    // Slice 2026-06-23-audit-3rd #11: skip mkdirSync when the dir already
+    // exists (every heartbeat + every dispatch read-modify-write).
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    const safeTmp = resolve(dir, tmp.split(/[\\/]/).pop());
+    writeFileSync(safeTmp, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    renameSync(safeTmp, path);
+}

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,81 @@
+/**
+ * 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;