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

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -1,147 +0,0 @@
-import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
-import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
-import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
-import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
-import { requiredSkillNames } from '../../shared/paths.js';
-import { getSkillPresence } from '../skills/skill-presence-service.js';
-const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
-/**
- * Resolves the user-facing `ok` field. `workspace-only` (default) returns true
- * when the runbook / workspace layout is healthy, even if 1-2 non-blocking
- * doctor checks fail. `strict` returns false when the doctor aggregate fails.
- * The CLI default is `workspace-only`; `peaks project dashboard --strict`
- * restores the legacy aggregate semantics.
- */
-export function resolveDashboardOk(args) {
-    if (args.okPolicy === 'strict') {
-        return { ok: args.doctor.ok && args.runbookHealth.ok, okPolicy: 'strict' };
-    }
-    return { ok: args.runbookHealth.ok, okPolicy: 'workspace-only' };
-}
-function defaultClock() {
-    return new Date().toISOString();
-}
-function groupRequestsByRole(items) {
-    const byRole = { prd: [], ui: [], rd: [], qa: [], sc: [] };
-    for (const item of items) {
-        byRole[item.role].push(item);
-    }
-    return byRole;
-}
-function countRequestsByState(items) {
-    const counts = {};
-    for (const item of items) {
-        counts[item.state] = (counts[item.state] ?? 0) + 1;
-    }
-    return counts;
-}
-async function loadDoctorAndRunbookHealth(doctorOverride, runbookOverride) {
-    if (doctorOverride !== undefined && runbookOverride !== undefined) {
-        return { doctor: doctorOverride, runbookHealth: runbookOverride };
-    }
-    if (doctorOverride !== undefined) {
-        return {
-            doctor: doctorOverride,
-            runbookHealth: { ok: true, required: 0, healthy: 0, missingRunbook: [], applyNoteFailed: [] }
-        };
-    }
-    const { runDoctor } = await import('../doctor/doctor-service.js');
-    const report = await runDoctor();
-    return {
-        doctor: { ok: report.summary.ok, passed: report.summary.passed, failed: report.summary.failed },
-        runbookHealth: runbookOverride ?? summarizeRunbookHealth(report.checks)
-    };
-}
-function summarizeRunbookHealth(checks) {
-    const missingRunbook = [];
-    const applyNoteFailed = [];
-    for (const check of checks) {
-        if (!check.ok && check.id.startsWith('skill-runbook:')) {
-            missingRunbook.push(check.id.slice('skill-runbook:'.length));
-        }
-        if (!check.ok && check.id.startsWith('skill-apply-note:')) {
-            applyNoteFailed.push(check.id.slice('skill-apply-note:'.length));
-        }
-    }
-    const required = requiredSkillNames.length;
-    const healthy = Math.max(0, required - missingRunbook.length - applyNoteFailed.length);
-    return {
-        ok: missingRunbook.length === 0 && applyNoteFailed.length === 0,
-        required,
-        healthy,
-        missingRunbook,
-        applyNoteFailed
-    };
-}
-function buildCapabilitiesSummary(sampleSize) {
-    const items = seedCapabilityItems;
-    return {
-        count: items.length,
-        sample: items.slice(0, sampleSize).map((item) => ({
-            capabilityId: item.capabilityId,
-            name: item.name,
-            itemType: item.itemType,
-            category: item.category
-        }))
-    };
-}
-function buildSkillPresenceSummary(presence, projectRoot) {
-    // When the caller doesn't supply presence, resolve it from the dashboard's
-    // project root rather than the process cwd.
-    const resolved = presence === undefined ? getSkillPresence(projectRoot) : presence;
-    if (resolved === null) {
-        return { active: false, fresh: true };
-    }
-    const setAtMs = Date.parse(resolved.setAt);
-    const fresh = !Number.isNaN(setAtMs) && Date.now() - setAtMs <= SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS;
-    return {
-        active: true,
-        fresh,
-        skill: resolved.skill,
-        ...(resolved.mode !== undefined ? { mode: resolved.mode } : {}),
-        ...(resolved.gate !== undefined ? { gate: resolved.gate } : {}),
-        setAt: resolved.setAt
-    };
-}
-export async function loadProjectDashboard(options) {
-    const clock = options.clock ?? defaultClock;
-    const sampleSize = options.sampleCapabilities ?? 8;
-    const okPolicy = options.okPolicy ?? 'workspace-only';
-    const [items, openspecReport, understandReport, doctorAndRunbook] = await Promise.all([
-        listRequestArtifacts({ projectRoot: options.projectRoot }),
-        scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
-        scanUnderstandAnything({ projectRoot: options.projectRoot }),
-        loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
-    ]);
-    const okVerdict = resolveDashboardOk({
-        okPolicy,
-        doctor: doctorAndRunbook.doctor,
-        runbookHealth: doctorAndRunbook.runbookHealth
-    });
-    return {
-        generatedAt: clock(),
-        projectRoot: options.projectRoot,
-        ok: okVerdict.ok,
-        okPolicy: okVerdict.okPolicy,
-        requests: {
-            count: items.length,
-            byRole: groupRequestsByRole(items),
-            byState: countRequestsByState(items)
-        },
-        openspec: {
-            exists: openspecReport.exists,
-            count: openspecReport.changes.length,
-            changes: openspecReport.changes
-        },
-        understand: {
-            exists: understandReport.exists,
-            graphExists: understandReport.graph.exists,
-            graphPath: understandReport.graph.path,
-            ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
-        },
-        doctor: doctorAndRunbook.doctor,
-        runbookHealth: doctorAndRunbook.runbookHealth,
-        capabilities: buildCapabilitiesSummary(sampleSize),
-        skillPresence: buildSkillPresenceSummary(options.skillPresence, options.projectRoot)
-    };
-}

package/dist/src/services/dispatch/batch-counter.d.ts

@@ -1,27 +0,0 @@
-export declare const BATCH_LIMIT = 6;
-export declare const BATCH_OVER_LIMIT_CODE = "BATCH_OVER_LIMIT";
-export type BatchCounterWarning = {
-    readonly code: typeof BATCH_OVER_LIMIT_CODE;
-    readonly batchId: string;
-    readonly dispatched: number;
-    readonly limit: number;
-    readonly message: string;
-};
-/** Build the per-batch counter file path. */
-export declare function batchCounterPath(projectRoot: string, sid: string, batchId: string): string;
-/** A single batch counter record. */
-export interface BatchCounterRecord {
-    readonly batchId: string;
-    readonly sessionId: string;
-    readonly createdAt: string;
-    readonly count: number;
-}
-/** Read the current counter; returns 0 if no file yet. */
-export declare function readBatchCount(projectRoot: string, sid: string, batchId: string): number;
-/** Increment the counter and return the new value (with any warning). */
-export declare function noteDispatched(projectRoot: string, sid: string, batchId: string, now?: () => Date): {
-    count: number;
-    warning: BatchCounterWarning | null;
-};
-/** Reset a batch counter (called by the reducer when starting a new batch). */
-export declare function resetBatch(projectRoot: string, sid: string, batchId: string): void;

package/dist/src/services/dispatch/batch-counter.js

@@ -1,102 +0,0 @@
-/**
- * G5.1 / RL-1 — batch size counter.
- *
- * Empirical upper bound for one Dispatcher × one batch: 6 sub-agents.
- * Above 6, the LLM / human is encouraged to split into multiple
- * batches with an explicit reducer step in between. peaks-code's
- * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
- * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
- * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"
- * subdivisions (3-way + 3-way = 6) without crossing the line.
- *
- * The counter is in-memory per process. The Dispatcher is expected
- * to call `noteDispatched` once per `peaks sub-agent dispatch` and
- * reset between batches. The CLI also persists a small per-sid
- * counter file so that sub-agent spawns invoked across multiple
- * `peaks sub-agent dispatch` processes within the same batch can be
- * tallied (the batch id ties them together).
- *
- * `BATCH_OVER_LIMIT` is a warning, not a hard fail. The user has been
- * explicit: "RL-1 is empirical; if you have a real reason to go to 7,
- * that's your call". A warning is the right surface — let the LLM /
- * human read the reason and decide.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { withFileLockSync } from '../filesystem/file-lock.js';
-export const BATCH_LIMIT = 6;
-export const BATCH_OVER_LIMIT_CODE = 'BATCH_OVER_LIMIT';
-/** Build the per-batch counter file path. */
-export function batchCounterPath(projectRoot, sid, batchId) {
-    return resolve(projectRoot, '.peaks', '_sub_agents', sid, `batch-${batchId}.counter.json`);
-}
-/** Read the current counter; returns 0 if no file yet. */
-export function readBatchCount(projectRoot, sid, batchId) {
-    const path = batchCounterPath(projectRoot, sid, batchId);
-    if (!existsSync(path))
-        return 0;
-    try {
-        const parsed = JSON.parse(readFileSync(path, 'utf8'));
-        return typeof parsed.count === 'number' && parsed.count >= 0 ? parsed.count : 0;
-    }
-    catch {
-        return 0;
-    }
-}
-/** Increment the counter and return the new value (with any warning). */
-export function noteDispatched(projectRoot, sid, batchId, now = () => new Date()) {
-    const path = batchCounterPath(projectRoot, sid, batchId);
-    // Slice 2026-06-23-audit-4th #A1: wrap the read-modify-write in a
-    // file lock. Two concurrent `peaks sub-agent dispatch` invocations
-    // for the same (sid, batchId) would otherwise race — both call
-    // readBatchCount first, both see the same N, both write N+1, and
-    // the second write clobbers the first (lost update). The BATCH_OVER_LIMIT
-    // warning fires for the wrong threshold when this happens. The lock
-    // serializes the writes; contention is rare (only when a single
-    // batch is dispatched in parallel from the same LLM) so the spin-wait
-    // cost is bounded by MAX_LOCK_RETRIES * LOCK_RETRY_MAX_MS.
-    return withFileLockSync(path, () => {
-        const previous = readBatchCount(projectRoot, sid, batchId);
-        const next = {
-            batchId,
-            sessionId: sid,
-            createdAt: now().toISOString(),
-            count: previous + 1
-        };
-        // mkdirSync is conditional via the lock helper (it ensures the
-        // parent dir exists), but the counter file may live in a session
-        // sub-dir that the lock helper's recursive mkdir handles. Belt +
-        // suspenders: keep the explicit mkdir here so the path resolves
-        // even if withFileLockSync's mkdir is bypassed in the future.
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
-        if (next.count > BATCH_LIMIT) {
-            return {
-                count: next.count,
-                warning: {
-                    code: BATCH_OVER_LIMIT_CODE,
-                    batchId,
-                    dispatched: next.count,
-                    limit: BATCH_LIMIT,
-                    message: `per RL-1, batch size 6 is empirical upper bound; you have ` +
-                        `${next.count}. If you need more, split into multiple batches ` +
-                        `with an explicit reducer step between them.`
-                }
-            };
-        }
-        return { count: next.count, warning: null };
-    });
-}
-/** Reset a batch counter (called by the reducer when starting a new batch). */
-export function resetBatch(projectRoot, sid, batchId) {
-    const path = batchCounterPath(projectRoot, sid, batchId);
-    if (existsSync(path)) {
-        try {
-            const { unlinkSync } = require('node:fs');
-            unlinkSync(path);
-        }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            /* best-effort; counter file is informational */
-        }
-    }
-}

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

@@ -1,63 +0,0 @@
-/** 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/src/services/dispatch/contract-store.js

@@ -1,157 +0,0 @@
-/**
- * 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/src/services/dispatch/dispatch-record-writer.d.ts

@@ -1,138 +0,0 @@
-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';
-export type DispatchRecordStatus = 'queued' | 'running' | 'finalizing' | 'done' | 'failed' | 'cancelled' | 'no-execution' | 'stale';
-export type DispatchOutcome = 'success' | 'failed' | 'timeout' | 'cancelled' | 'no-execution';
-/** G2+G5+G6 dispatch record schema (AC-26 + AC-34). */
-export interface DispatchRecord {
-    readonly version: 2;
-    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;
-}
-/** 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;
-};
-/** 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';
-}
-/**
- * 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;
-};
-/** 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;
-};
-/**
- * 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 };