peaks-loop 3.0.0

package/dist/src/services/solo/auto-compact-orchestrator.js

@@ -0,0 +1,343 @@
+/**
+ * Auto-compact orchestrator (v2.13.0 AC-2 + AC-3 + AC-4).
+ *
+ * Closes the loop between `peaks context now` (AC-1) and the IDE's
+ * native compact capability (AC-3). peaks-cli is project-aware: it
+ * knows the current plan, open questions, recent decisions, in-flight
+ * batches, todo state, git status, and active skills. That context is
+ * strictly more valuable than what `/compact` can synthesize from raw
+ * conversation history — so peaks-cli drives the entire compaction:
+ *
+ *   1. Read current context % (via IDE adapter's `readContextPercent`).
+ *   2. If ratio ≥ 0.95 (RED LINE): synchronous gate — peaks-cli
+ *      refuses sub-agent dispatch and forces IDE compact immediately.
+ *      The LLM cannot opt out (compact red line — keeps the runner
+ *      alive).
+ *   3. If 0.85 ≤ ratio < 0.95 (pre-compact zone): peaks-cli prepares
+ *      the convergence toolkit (checkpoint + auto-decisions log +
+ *      IDE-dispatch handle) and surfaces it to the LLM. The LLM
+ *      DECIDES when to fire `peaks solo auto-compact --execute`;
+ *      peaks-cli does NOT auto-fire. The toolkit is ready so the
+ *      LLM doesn't lose context to a last-second `/compact` panic.
+ *   4. If ratio < 0.85: skip — return a one-line info row.
+ *
+ * Why two tiers (vs. one): the LLM uses the 0.85–0.95 zone for
+ * intelligent convergence — wait for in-flight sub-agents, finish
+ * the current todo row, persist a checkpoint, then compact. At 0.95
+ * the window is gone; peaks-cli takes over synchronously. Net effect:
+ * the LLM-runner keeps working with context < 95% without human
+ * intervention.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { getSessionIdCanonical } from '../session/session-manager.js';
+import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_RED_LINE_RATIO, AUTO_COMPACT_THRESHOLD_RATIO } from '../context/auto-compact-types.js';
+const PRE_COMPACT_REASON = 'pre-compact-auto';
+/**
+ * Map a context ratio to a `CompactTrigger` action. Pure; the side
+ * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
+ * tiers:
+ *
+ *   - ratio < 0.85 → 'none' or 'soft-warn'
+ *   - ratio ≥ 0.85 → 'pre-compact' (async-friendly path)
+ *   - ratio ≥ 0.95 → 'red-line' (synchronous gate)
+ */
+export function evaluateCompactTrigger(ratio) {
+    if (ratio < AUTO_COMPACT_PRE_COMPACT_RATIO) {
+        return ratio < 0.5
+            ? { kind: 'none' }
+            : {
+                kind: 'soft-warn',
+                ratio,
+                message: `Context at ${(ratio * 100).toFixed(1)}%; below the 85% pre-compact threshold.`
+            };
+    }
+    if (ratio >= AUTO_COMPACT_RED_LINE_RATIO) {
+        return {
+            kind: 'red-line',
+            ratio,
+            message: `Context at ${(ratio * 100).toFixed(1)}% ≥ 95% red line. Synchronous compact REQUIRED (LLM cannot opt out).`
+        };
+    }
+    // 0.85 ≤ ratio < 0.95: pre-compact zone — toolkit ready, LLM decides.
+    return {
+        kind: 'pre-compact',
+        ratio,
+        toolkitReady: true,
+        message: `Context at ${(ratio * 100).toFixed(1)}% in pre-compact zone (0.85–0.95). Convergence toolkit is ready; LLM decides when to fire \`peaks solo auto-compact --execute\`.`
+    };
+}
+/**
+ * Decide whether to run the auto-compact flow. Pure function for the
+ * decision; side effects (checkpoint + IDE dispatch) live in
+ * `runAutoCompact` below. Zero human / zero LLM intervention:
+ *
+ *   - ratio < 0.85           → skip (LLM keeps working; no action)
+ *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
+ *                                present, defer (D6.e); else dispatch
+ *                                IDE compact asynchronously.
+ *   - ratio ≥ 0.95           → red-line; ALWAYS dispatch synchronously
+ *                                regardless of in-flight batch.
+ */
+export function evaluateAutoCompactDecision(input) {
+    const trigger = evaluateCompactTrigger(input.ratio);
+    if (trigger.kind === 'none' || trigger.kind === 'soft-warn') {
+        return { shouldCompact: false, reason: 'below-threshold', trigger };
+    }
+    if (trigger.kind === 'red-line') {
+        // Red line: ignore in-flight batch — synchronous dispatch wins.
+        return { shouldCompact: true, reason: 'red-line', trigger };
+    }
+    // pre-compact zone (0.85 ≤ ratio < 0.95): honor D6.e in-flight deferral.
+    if (input.inFlightBatch?.hasInFlightBatch === true) {
+        return { shouldCompact: false, reason: 'in-flight-batch', trigger };
+    }
+    if (input.force) {
+        return { shouldCompact: true, reason: 'pre-compact', trigger };
+    }
+    // Default: peaks-cli drives pre-compact autonomously.
+    return { shouldCompact: true, reason: 'pre-compact', trigger };
+}
+/**
+ * Build the convergence plan that D7's post-compact-detect will read
+ * back. Includes the current plan, open questions, recent decisions,
+ * todo state, and recent artifact paths — strictly more than what a
+ * raw `/compact` would preserve.
+ */
+export function buildConvergencePlan(input) {
+    return {
+        schemaVersion: 1,
+        sessionId: input.sessionId,
+        projectRoot: input.projectRoot,
+        createdAt: new Date().toISOString(),
+        ratio: input.ratio,
+        checkpointPath: input.checkpointPath,
+        nextActions: [...input.nextActions],
+        resumeHint: input.redLine === true
+            ? 'RED-LINE compact: post-compact-detect must confirm ratio < 0.85 before resuming work.'
+            : 'post-compact-detect shouldAutoResume → resume pre-compact plan from checkpoint'
+    };
+}
+/**
+ * Append a one-row convergence decision to the LLM-readable log.
+ * The LLM reads this on the post-compact turn to pick up exactly
+ * where it left off (vs. blindly trusting the IDE's compressed
+ * transcript).
+ */
+function appendAutoDecisionLog(input) {
+    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'txt');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const logPath = join(dir, 'auto-decisions.md');
+    const row = [
+        '',
+        `## Auto-compact decision — ${input.plan.createdAt}`,
+        `- ratio: ${(input.plan.ratio * 100).toFixed(1)}%`,
+        `- checkpoint: ${input.plan.checkpointPath}`,
+        `- next-actions: ${input.plan.nextActions.join(' | ')}`,
+        `- resume-hint: ${input.plan.resumeHint}`,
+        ''
+    ].join('\n');
+    if (!existsSync(logPath)) {
+        writeFileSync(logPath, `# peaks-solo auto-decisions log\n${row}`, 'utf8');
+        return;
+    }
+    const existing = readFileSync(logPath, 'utf8');
+    writeFileSync(logPath, `${existing}${row}`, 'utf8');
+}
+/**
+ * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): write the
+ * main-session compact intent so the main-session LLM picks it up on
+ * its next turn and fires `/compact` in-band. Without this file the
+ * orchestrator's "main-session compact" request is invisible to the
+ * main Claude Code window (defeats the whole point of auto-compact
+ * for the main context).
+ *
+ * The file is gitignored under `.peaks/_runtime/<sessionId>/txt/` and
+ * is one-shot: the LLM should `mv` it to `.consumed` after firing
+ * `/compact`. A re-run will overwrite.
+ */
+function writeMainSessionCompactIntent(input) {
+    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'txt');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'auto-compact-pending.json');
+    const payload = {
+        schemaVersion: 1,
+        pending: true,
+        target: 'main',
+        requestedAt: input.now.toISOString(),
+        ratio: input.ratio,
+        redLine: input.redLine,
+        nextAction: 'next LLM turn MUST fire `/compact` then `mv .peaks/_runtime/<sid>/txt/auto-compact-pending.json .peaks/_runtime/<sid>/txt/auto-compact-pending.consumed.json`'
+    };
+    writeFileSync(path, JSON.stringify(payload, null, 2), 'utf8');
+}
+/**
+ * Write a pre-compact checkpoint. The shape mirrors `peaks session
+ * checkpoint` so D7's post-compact-detect picks it up unchanged.
+ */
+function writePreCompactCheckpoint(input) {
+    const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'checkpoints');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const prefix = input.redLine === true ? 'red-line-' : 'pre-compact-';
+    const filename = `${prefix}${input.now.toISOString().replace(/[:.]/g, '-')}.json`;
+    const path = join(dir, filename);
+    const content = {
+        schemaVersion: 1,
+        reason: input.redLine === true ? 'pre-compact-red-line' : PRE_COMPACT_REASON,
+        sessionId: input.sessionId,
+        createdAt: input.now.toISOString(),
+        // D7 reads `mode`, `currentPlan`, `openQuestions`, `recentDecisions`
+        // out of this JSON. We seed empty arrays; the post-compact LLM
+        // rehydrates from the auto-decisions log + open question list.
+        mode: 'full-auto',
+        currentPlan: input.redLine === true
+            ? 'RED-LINE compact just executed; confirm ratio < 0.85 before resuming work'
+            : 'auto-compact in progress; resume from auto-decisions.md',
+        openQuestions: [],
+        recentDecisions: [],
+        recentArtifactPaths: [],
+        gitStatus: '',
+        skillsActive: ['peaks-solo'],
+        todoState: []
+    };
+    writeFileSync(path, JSON.stringify(content, null, 2), 'utf8');
+    return path;
+}
+/**
+ * Execute the auto-compact flow.
+ *
+ * Steps (orchestration):
+ *   1. Resolve session id.
+ *   2. Read current ratio via AC-1 (`readContextPercent`).
+ *   3. Evaluate trigger via `evaluateCompactTrigger`.
+ *   4. If trigger.kind === 'none' / 'soft-warn' → return skip.
+ *   5. If trigger.kind === 'pre-compact' AND in-flight batch → wait.
+ *   6. If trigger.kind === 'pre-compact' → async dispatch (write
+ *      checkpoint + IDE compact; orchestrator returns immediately).
+ *   7. If trigger.kind === 'red-line' → synchronous gate: refuse
+ *      sub-agent dispatch, dispatch IDE compact, mark `redLineGated`.
+ *
+ * The caller (CLI or skill body) handles the actual return — D7's
+ * post-compact-detect will pick up the checkpoint on the next turn.
+ * For red-line, the caller MUST block further tool calls until the
+ * post-compact probe confirms ratio < 0.85.
+ */
+export async function runAutoCompact(input) {
+    const sessionId = input.sessionId ?? getSessionIdCanonical(input.projectRoot);
+    if (sessionId === null) {
+        return {
+            ok: false,
+            code: 'AUTO_COMPACT_NO_SESSION',
+            message: 'No active session; cannot run auto-compact. Run `peaks workspace init` first.',
+            nextActions: ['Run `peaks workspace init --change-id <id>` to bind a session']
+        };
+    }
+    // Lazy import to avoid the AC-1 module depending on the orchestrator.
+    const { readContextPercent } = await import('../context/auto-compact-reader.js');
+    const probe = readContextPercent({
+        projectRoot: input.projectRoot,
+        sessionId,
+        env: input.env
+    });
+    const decision = evaluateAutoCompactDecision({
+        ratio: probe.ratio,
+        inFlightBatch: input.inFlightBatch,
+        force: input.force,
+        bypassRedLine: input.bypassRedLine
+    });
+    if (!decision.shouldCompact) {
+        return {
+            ok: true,
+            code: decision.reason === 'in-flight-batch' ? 'AUTO_COMPACT_WAIT' : 'AUTO_COMPACT_SKIP',
+            message: decision.trigger.kind === 'soft-warn'
+                ? decision.trigger.message
+                : decision.reason === 'in-flight-batch'
+                    ? `In-flight batch detected; deferring pre-compact (ratio=${(probe.ratio * 100).toFixed(1)}%); next probe will re-evaluate.`
+                    : `Context at ${(probe.ratio * 100).toFixed(1)}%; below ${(AUTO_COMPACT_THRESHOLD_RATIO * 100).toFixed(0)}% threshold.`,
+            data: {
+                sessionId,
+                ratio: probe.ratio,
+                source: probe.source,
+                decision: decision.reason === 'in-flight-batch' ? 'in-flight-batch' : 'below-threshold'
+            }
+        };
+    }
+    const isRedLine = decision.reason === 'red-line';
+    const now = input.now ?? new Date();
+    const checkpointPath = writePreCompactCheckpoint({
+        projectRoot: input.projectRoot,
+        sessionId,
+        now,
+        redLine: isRedLine
+    });
+    const nextActions = isRedLine
+        ? [
+            'RED-LINE compact dispatched — further sub-agent dispatch BLOCKED until ratio < 0.85',
+            'Post-compact resume picks up the convergence plan from auto-decisions.md',
+            'Next `peaks context now` probe will confirm ratio dropped below 0.85'
+        ]
+        : [
+            'Pre-compact dispatched — IDE compact in progress (async)',
+            'Post-compact resume picks up the convergence plan from auto-decisions.md',
+            'Next `peaks context now` probe will confirm ratio dropped below 0.85'
+        ];
+    const plan = buildConvergencePlan({
+        sessionId,
+        projectRoot: input.projectRoot,
+        ratio: probe.ratio,
+        checkpointPath,
+        nextActions,
+        redLine: isRedLine
+    });
+    appendAutoDecisionLog({ projectRoot: input.projectRoot, sessionId, plan });
+    // Lazy import to keep AC-3 (IDE dispatch) pluggable; tests mock this module.
+    const { dispatchIdeCompact } = await import('../context/auto-compact-dispatcher.js');
+    const target = input.target ?? 'main';
+    // Slice 2026-06-28: when targeting the main session, write an
+    // intent record so the next main-session LLM turn fires `/compact`
+    // in-band. Without this record the LLM has no signal that the
+    // orchestrator asked for compact; the dispatcher alone would have
+    // been a no-op against the main Claude Code window.
+    if (target === 'main') {
+        writeMainSessionCompactIntent({
+            projectRoot: input.projectRoot,
+            sessionId,
+            ratio: probe.ratio,
+            redLine: isRedLine,
+            now
+        });
+    }
+    const dispatch = await dispatchIdeCompact({
+        projectRoot: input.projectRoot,
+        sessionId,
+        env: input.env,
+        target
+    });
+    return {
+        ok: dispatch.ok,
+        code: dispatch.ok
+            ? (isRedLine ? 'AUTO_COMPACT_RED_LINE' : 'AUTO_COMPACT_DISPATCHED')
+            : 'AUTO_COMPACT_DISPATCH_FAILED',
+        message: dispatch.ok
+            ? isRedLine
+                ? `RED-LINE compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target}); checkpoint at ${checkpointPath}. Further sub-agent dispatch is BLOCKED until ratio < 0.85.`
+                : `Auto-compact dispatched (${dispatch.ide} / ${dispatch.pathway} / target=${target}); checkpoint at ${checkpointPath}.`
+            : `Auto-compact checkpoint written but IDE dispatch failed: ${dispatch.message}`,
+        data: {
+            sessionId,
+            ratio: probe.ratio,
+            source: probe.source,
+            checkpointPath,
+            convergencePlan: plan,
+            dispatch,
+            target,
+            redLineGated: isRedLine
+        }
+    };
+}
+// Keep dirname import live for symmetry with sibling services that
+// use it for path joins; tree-shaking removes it in builds.
+void dirname;

package/dist/src/services/solo/batch-heartbeat-poller.d.ts

@@ -0,0 +1,51 @@
+import { summarize, type SubAgentLiveView } from './status-line-renderer.js';
+export declare const DEFAULT_POLL_INTERVAL_MS = 10000;
+export declare const DEFAULT_STALE_THRESHOLD_MS: number;
+export type PollRecord = {
+    readonly path: string;
+    readonly role: string;
+};
+export type PollerStatusEvent = {
+    readonly kind: 'status';
+    readonly line: string;
+    readonly summary: ReturnType<typeof summarize>;
+    readonly views: readonly SubAgentLiveView[];
+};
+export type PollerStaleEvent = {
+    readonly kind: 'stale';
+    readonly path: string;
+    readonly role: string;
+    readonly lastBeatAgoSec: number;
+    readonly thresholdSec: number;
+};
+export type PollerDoneEvent = {
+    readonly kind: 'done';
+    readonly summary: ReturnType<typeof summarize>;
+};
+export type PollerEvent = PollerStatusEvent | PollerStaleEvent | PollerDoneEvent;
+export type PollerHandlers = {
+    onStatus?: (event: PollerStatusEvent) => void;
+    onStale?: (event: PollerStaleEvent) => void;
+    onDone?: (event: PollerDoneEvent) => void;
+    onError?: (error: unknown) => void;
+};
+export type PollerOptions = {
+    prefix: string;
+    intervalMs?: number;
+    staleThresholdMs?: number;
+    now?: () => Date;
+};
+export declare class BatchHeartbeatPoller {
+    private readonly records;
+    private readonly handlers;
+    private readonly options;
+    private timer;
+    private prevStale;
+    private prevSummaryDone;
+    private running;
+    constructor(records: readonly PollRecord[], handlers: PollerHandlers, options: PollerOptions);
+    start(): void;
+    stop(): void;
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick(): void;
+}

package/dist/src/services/solo/batch-heartbeat-poller.js

@@ -0,0 +1,88 @@
+import { readRecords } from '../dispatch/dispatch-record-writer.js';
+import { renderStatusLine, summarize, viewSubAgent } from './status-line-renderer.js';
+export const DEFAULT_POLL_INTERVAL_MS = 10_000;
+export const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+const TERMINAL_STATUSES = ['done', 'failed'];
+const TERMINAL_RECORD_STATUSES = [
+    'done',
+    'failed',
+    'cancelled',
+    'no-execution'
+];
+export class BatchHeartbeatPoller {
+    records;
+    handlers;
+    options;
+    timer = null;
+    prevStale = new Set();
+    prevSummaryDone = 0;
+    running = false;
+    constructor(records, handlers, options) {
+        this.records = records;
+        this.handlers = handlers;
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.tick();
+        const interval = this.options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.timer = setInterval(() => this.tick(), interval);
+        // Don't keep the process alive just for the poller.
+        this.timer.unref?.();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** Force a tick (testing seam + low-level access for explicit invocation). */
+    tick() {
+        let recs;
+        try {
+            recs = readRecords(this.records.map((r) => r.path));
+        }
+        catch (error) {
+            this.handlers.onError?.(error);
+            return;
+        }
+        const now = this.options.now ?? (() => new Date());
+        const summary = summarize(recs);
+        const views = recs.map((r) => viewSubAgent(r, now));
+        const line = renderStatusLine(this.options.prefix, recs, now);
+        this.handlers.onStatus?.({ kind: 'status', line, summary, views });
+        const staleThresholdSec = Math.floor((this.options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS) / 1000);
+        for (const rec of recs) {
+            const v = viewSubAgent(rec, now);
+            if (v.isStale) {
+                const key = `${rec.role}::${rec.requestId}`;
+                if (!this.prevStale.has(key)) {
+                    this.prevStale.add(key);
+                    this.handlers.onStale?.({
+                        kind: 'stale',
+                        path: this.records.find((p) => p.role === rec.role)?.path ?? '',
+                        role: rec.role,
+                        lastBeatAgoSec: v.lastBeatAgoSec ?? -1,
+                        thresholdSec: staleThresholdSec
+                    });
+                }
+            }
+        }
+        if (summary.total > 0 && summary.done === summary.total && this.prevSummaryDone !== summary.done) {
+            this.prevSummaryDone = summary.done;
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else if (recs.length > 0 &&
+            recs.every((r) => TERMINAL_RECORD_STATUSES.includes(r.status) || TERMINAL_STATUSES.includes(r.status))) {
+            this.handlers.onDone?.({ kind: 'done', summary });
+            this.stop();
+        }
+        else {
+            this.prevSummaryDone = summary.done;
+        }
+    }
+}

package/dist/src/services/solo/dag-orchestrator.d.ts

@@ -0,0 +1,128 @@
+/**
+ * DAG orchestrator — 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a).
+ *
+ * The pure planner. Given a `SliceDag`, the orchestrator decides which
+ * slices to dispatch next (in topological order), drives the join barrier,
+ * and rolls back on any leaf failure.
+ *
+ * Design:
+ *  - **Pure dispatcher contract**: the orchestrator never calls an LLM
+ *    directly; it returns `DispatchSpec[]` per topological level and lets
+ *    the caller (the CLI / peaks-solo LLM) execute the per-IDE tool calls.
+ *    This keeps the orchestrator testable end-to-end with mock sub-agents.
+ *  - **Join barrier**: between levels, the orchestrator awaits the
+ *    results of all dispatched leaves and refuses to advance if any
+ *    leaf failed.
+ *  - **Failure rollback**: a leaf failure cancels all other in-flight
+ *    slices in the same level. The orchestrator surfaces a `DagRollback`
+ *    event so the caller can re-plan.
+ *  - **Contract broadcast**: when a slice finishes successfully, the
+ *    orchestrator writes its public contract to disk via `writeContract`,
+ *    and the next dispatch's prompt is built with `formatContractInjection`.
+ *
+ * Why this lives in `services/solo/`:
+ *  `peaks-solo` is the natural caller. The CLI surface (`peaks sub-agent
+ *  dispatch --from-dag`) consumes the planner's output but the planner
+ *  itself is a library.
+ */
+import { type SliceDag } from '../dispatch/slice-dag.js';
+import { type SliceContract } from '../dispatch/contract-store.js';
+export interface DispatchSpec {
+    readonly sliceId: string;
+    readonly role: string;
+    readonly label: string | null;
+    readonly prompt: string;
+    /** Optional contract block to splice into the prompt. */
+    readonly contractBlock: string;
+}
+export interface RunDagOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /**
+     * Reserved for slice 1.3 — when the per-IDE `awaitBatch` join barrier
+     * moves into the orchestrator, this will cap how long `runDag` waits
+     * for a single leaf before issuing `cancel`. Unused in 1.2 MVP
+     * (per-IDE await is delegated to the LLM-side runner); declared here
+     * so the public surface stays stable across the 1.2 → 1.3 transition.
+     */
+    readonly timeoutMs?: number;
+    /** Test seam: replace the runner (default: a no-op that returns `done`). */
+    readonly runSlice?: (spec: DispatchSpec) => Promise<SliceOutcome>;
+    /** Test seam: replace the contract writer (default: `writeContract`). */
+    readonly writeContractFn?: (sliceId: string, publicSurface: PublicSurface) => SliceContract;
+    /**
+     * Pre-existing contracts from upstream slices (e.g. already completed in
+     * a prior `peaks sub-agent dispatch --from-dag` invocation). The
+     * orchestrator splices these into downstream dispatch prompts via
+     * `formatContractInjection(ancestors)` — matching AC-4.c: "B / C / D
+     * dispatch prompt 自动注入 A 契约".
+     */
+    readonly existingContracts?: readonly SliceContract[];
+}
+export type SliceOutcome = {
+    readonly status: 'done';
+    readonly publicSurface: PublicSurface;
+} | {
+    readonly status: 'failed';
+    readonly reason: string;
+} | {
+    readonly status: 'cancelled';
+};
+export interface PublicSurface {
+    readonly exports: readonly string[];
+    readonly types: readonly string[];
+    readonly publicSignatures: readonly string[];
+    readonly broadcastTo?: readonly string[];
+}
+export interface DagRunResult {
+    readonly dagHash: string;
+    readonly completed: readonly string[];
+    readonly failed: readonly {
+        sliceId: string;
+        reason: string;
+    }[];
+    readonly cancelled: readonly string[];
+    readonly contracts: readonly SliceContract[];
+}
+/** Thrown when the DAG has no feasible plan (validation error). */
+export declare class DagPlanError extends Error {
+    readonly code: "DAG_PLAN_ERROR";
+    constructor(message: string);
+}
+/**
+ * Build a single dispatch spec for `sliceId` given the current contract set.
+ *
+ * When `node.prompt` is set on the DAG node, that wins verbatim (the
+ * caller controls per-slice prompt content). Otherwise we fall back to
+ * `defaultPrompt`, then to a structured MVP prompt covering: the slice's
+ * role + id + label, the injected ancestor-contract block (if any), the
+ * MVP scope statement, and the explicit handoff protocol the LLM-side
+ * runner must follow (write contract, then re-invoke for the next
+ * topological level).
+ */
+export declare function buildDispatchSpec(dag: SliceDag, sliceId: string, contracts: readonly SliceContract[], defaultPrompt?: string): DispatchSpec;
+/**
+ * Run a slice DAG end-to-end. Returns a summary; throws `DagPlanError`
+ * on validation failure; any leaf failure causes an in-flight cancel
+ * signal but the function still resolves with the partial result so the
+ * caller can re-plan.
+ */
+export declare function runDag(dag: SliceDag, opts: RunDagOptions): Promise<DagRunResult>;
+/**
+ * v2.15.0 follow-up — G12: layered DAG runner (foundation-first,
+ * business-parallel, upstreamSync-priority). Behavior:
+ *
+ *   1. Foundation slices run first (topological order).
+ *   2. As foundation slices complete, business slices that depend ONLY
+ *      on the completed foundation subset can start — they do NOT wait
+ *      for ALL foundation slices to complete. This is the layered-
+ *      parallelism speedup (saves 2-3 days on a 1-week+ requirement).
+ *   3. upstreamSync slices take priority within their topological
+ *      level (handled by `topologicalLevels` priority sort).
+ *   4. Cancel-on-fail semantics are preserved: any leaf failure
+ *      cancels in-flight siblings and breaks the loop.
+ *
+ * Pure planner; same I/O contract as `runDag`. The caller (CLI /
+ * peaks-solo LLM) executes the per-IDE tool calls.
+ */
+export declare function runLayeredDag(dag: SliceDag, opts: RunDagOptions): Promise<DagRunResult>;