peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/code/dag-orchestrator.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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-code 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/code/`:
+ *  `peaks-code` 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, type Wave, type WaveArtifact, type WaveOptions } 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-code LLM) executes the per-IDE tool calls.
+ */
+export declare function runLayeredDag(dag: SliceDag, opts: RunDagOptions): Promise<DagRunResult>;
+/**
+ * Plan a slice DAG into ordered dispatch Waves.
+ *
+ * Each topological level is split into chunks of at most
+ * `opts.maxConcurrency` slice IDs (default 6). Wave ordering follows
+ * topological level order; within each level, slices preserve
+ * `topologicalLevels`'s foundation / upstreamSync / id-asc priority sort.
+ */
+export declare function planDispatchWaves(dag: SliceDag, opts?: WaveOptions): readonly Wave[];
+/**
+ * Backward-compat wrapper: flatten `planDispatchWaves(dag)` into a flat
+ * sequence of stub `DispatchSpec`s. The original `runDag` /
+ * `runLayeredDag` do NOT consume this; the wrapper exists only so
+ * external callers that imported `planDispatch(dag)` keep their shape.
+ */
+export declare function planDispatch(dag: SliceDag): readonly DispatchSpec[];
+/**
+ * Run a single Wave: dispatch `wave.slices` in parallel, return a
+ * `WaveArtifact` envelope on success. On any per-slice failure or
+ * cancellation, REJECTS with `DagPlanError` — caller treats the
+ * rejection as a barrier violation and rolls back siblings.
+ *
+ * `passArtifacts`: when true, the returned envelope includes each
+ * slice's public surface (callers splice into downstream Wave prompts).
+ *
+ * `priorArtifacts` is reserved for future artifact-injection. This MVP
+ * accepts the shape but does not yet splice it into the prompt.
+ */
+export declare function runWaveWithArtifacts(dag: SliceDag, wave: Wave, runner: (spec: DispatchSpec) => Promise<SliceOutcome>, priorArtifacts?: readonly WaveArtifact[], opts?: WaveOptions): Promise<WaveArtifact>;

package/dist/services/code/dag-orchestrator.js

@@ -0,0 +1,409 @@
+/**
+ * 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-code 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/code/`:
+ *  `peaks-code` 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 { hashDag, InvalidSliceDagError, topologicalLevels, validateDag, DEFAULT_WAVE_OPTIONS } from '../dispatch/slice-dag.js';
+import { formatContractInjection, writeContract } from '../dispatch/contract-store.js';
+import { formatTestToolDetection } from '../dispatch/test-tool-detection.js';
+/** Thrown when the DAG has no feasible plan (validation error). */
+export class DagPlanError extends Error {
+    code = 'DAG_PLAN_ERROR';
+    constructor(message) {
+        super(message);
+        this.name = 'DagPlanError';
+    }
+}
+/** Default runner for tests / mocks. Returns `done` with an empty surface. */
+const defaultRunner = async (_spec) => ({
+    status: 'done',
+    publicSurface: { exports: [], types: [], publicSignatures: [] }
+});
+const defaultWriter = (projectRoot, sessionId) => (sliceId, publicSurface) => {
+    const r = writeContract(projectRoot, sessionId, {
+        sliceId,
+        sessionId,
+        exports: publicSurface.exports,
+        types: publicSurface.types,
+        publicSignatures: publicSurface.publicSignatures,
+        ...(publicSurface.broadcastTo !== undefined ? { broadcastTo: publicSurface.broadcastTo } : {})
+    });
+    return r.contract;
+};
+/**
+ * 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 function buildDispatchSpec(dag, sliceId, contracts, defaultPrompt) {
+    const node = dag.nodes.find((n) => n.id === sliceId);
+    if (!node) {
+        throw new DagPlanError(`unknown slice id: ${sliceId}`);
+    }
+    const ancestors = contracts.filter((c) => c.broadcastTo?.includes(sliceId) ?? false);
+    const contractBlock = formatContractInjection(ancestors);
+    if (node.prompt !== undefined) {
+        return {
+            sliceId,
+            role: node.role,
+            label: node.label ?? null,
+            prompt: `${formatTestToolDetection()}\n\n${node.prompt}`,
+            contractBlock
+        };
+    }
+    if (defaultPrompt !== undefined) {
+        return {
+            sliceId,
+            role: node.role,
+            label: node.label ?? null,
+            prompt: defaultPrompt,
+            contractBlock
+        };
+    }
+    // MVP (1.2) structured fallback prompt. Slice 1.4 will land per-domain
+    // prompt templates (one per role), but for the MVP dogfood we ship a
+    // single structured prompt that:
+    //   1. names the slice id + role + label (so the LLM knows what to do)
+    //   2. states the MVP scope explicitly (avoid confusion with full prod)
+    //   3. includes the ancestor contract injection (so downstream slices
+    //      see their inputs)
+    //   4. states the handoff protocol (write contract, re-invoke for next level)
+    const labelFragment = node.label ? ` — ${node.label}` : '';
+    const ancestorFragment = contractBlock
+        ? `\n\n${contractBlock}`
+        : '';
+    const prompt = [
+        formatTestToolDetection(),
+        '',
+        `[slice-dag-dispatcher MVP 1.2] execute slice "${sliceId}" (role=${node.role})${labelFragment}.`,
+        '',
+        'Scope: this is the 2.7.0 MVP dogfood of peaks-loop DAG-aware dispatch. You are one leaf in a multi-slice plan; the orchestrator has already validated the DAG, built a topological order, and injected your upstream contracts above.',
+        '',
+        'Handoff protocol (REQUIRED — orchestrator depends on this):',
+        '  1. Execute the slice to completion.',
+        `  2. Write your public contract via \`peaks contract write --project <root> --session-id <sid> --slice-id ${sliceId} --exports <...> --types <...> --signatures <...>\`. The orchestrator will pick it up on the next dispatch run.`,
+        '  3. Do NOT re-invoke `peaks sub-agent dispatch --from-dag` yourself — the parent orchestrator (peaks-code) drives level advancement.',
+        '',
+        `After your contract is on disk, the orchestrator will auto-advance to the next topological level (if any) by re-invoking \`peaks sub-agent dispatch --from-dag\` with the same batch-id. Your slice will appear in its ancestors via \`formatContractInjection\`.${ancestorFragment}`
+    ].join('\n');
+    return {
+        sliceId,
+        role: node.role,
+        label: node.label ?? null,
+        prompt,
+        contractBlock
+    };
+}
+/**
+ * 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 async function runDag(dag, opts) {
+    try {
+        validateDag(dag);
+    }
+    catch (err) {
+        if (err instanceof InvalidSliceDagError) {
+            throw new DagPlanError(err.message);
+        }
+        throw err;
+    }
+    const levels = topologicalLevels(dag);
+    const dagHash = hashDag(dag);
+    const runner = opts.runSlice ?? defaultRunner;
+    const writer = opts.writeContractFn ?? defaultWriter(opts.projectRoot, opts.sessionId);
+    const completed = new Set();
+    const contracts = [...(opts.existingContracts ?? [])];
+    const failed = [];
+    const cancelled = [];
+    const inflight = new Set();
+    for (const level of levels) {
+        const ready = level.filter((id) => !completed.has(id) && !failed.some((f) => f.sliceId === id));
+        if (ready.length === 0)
+            continue;
+        for (const id of ready)
+            inflight.add(id);
+        const settled = await Promise.all(ready.map(async (sliceId) => {
+            const spec = buildDispatchSpec(dag, sliceId, contracts);
+            try {
+                const outcome = await runner(spec);
+                return { sliceId, outcome };
+            }
+            catch (err) {
+                return {
+                    sliceId,
+                    outcome: { status: 'failed', reason: err.message }
+                };
+            }
+        }));
+        let levelHasFailure = false;
+        for (const { sliceId, outcome } of settled) {
+            inflight.delete(sliceId);
+            if (outcome.status === 'done') {
+                completed.add(sliceId);
+                const contract = writer(sliceId, outcome.publicSurface);
+                contracts.push(contract);
+            }
+            else if (outcome.status === 'failed') {
+                failed.push({ sliceId, reason: outcome.reason });
+                levelHasFailure = true;
+            }
+            else {
+                cancelled.push(sliceId);
+                levelHasFailure = true;
+            }
+        }
+        if (levelHasFailure) {
+            for (const id of inflight) {
+                cancelled.push(id);
+                inflight.delete(id);
+            }
+            break;
+        }
+    }
+    return {
+        dagHash,
+        completed: Array.from(completed).sort(),
+        failed,
+        cancelled: cancelled.sort(),
+        contracts
+    };
+}
+/**
+ * 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-code LLM) executes the per-IDE tool calls.
+ */
+export async function runLayeredDag(dag, opts) {
+    try {
+        validateDag(dag);
+    }
+    catch (err) {
+        if (err instanceof InvalidSliceDagError) {
+            throw new DagPlanError(err.message);
+        }
+        throw err;
+    }
+    const levels = topologicalLevels(dag);
+    const dagHash = hashDag(dag);
+    const runner = opts.runSlice ?? defaultRunner;
+    const writer = opts.writeContractFn ?? defaultWriter(opts.projectRoot, opts.sessionId);
+    const completed = new Set();
+    const contracts = [...(opts.existingContracts ?? [])];
+    const failed = [];
+    const cancelled = [];
+    const inflight = new Set();
+    for (const level of levels) {
+        // G12 layered parallelism: a business slice only blocks until its
+        // OWN `dependsOn` subset is complete, not all foundation slices.
+        const ready = level.filter((id) => {
+            if (completed.has(id))
+                return false;
+            if (failed.some((f) => f.sliceId === id))
+                return false;
+            // Check if all ancestors of this slice are in `completed` OR
+            // (already in `failed` — then it would never run, but we filter
+            // by `failed` above).
+            const node = dag.nodes.find((n) => n.id === id);
+            if (!node)
+                return false;
+            const ancestors = dag.edges.filter((e) => e.to === id).map((e) => e.from);
+            return ancestors.every((a) => completed.has(a));
+        });
+        if (ready.length === 0)
+            continue;
+        for (const id of ready)
+            inflight.add(id);
+        const settled = await Promise.all(ready.map(async (sliceId) => {
+            const spec = buildDispatchSpec(dag, sliceId, contracts);
+            try {
+                const outcome = await runner(spec);
+                return { sliceId, outcome };
+            }
+            catch (err) {
+                return {
+                    sliceId,
+                    outcome: { status: 'failed', reason: err.message }
+                };
+            }
+        }));
+        let levelHasFailure = false;
+        for (const { sliceId, outcome } of settled) {
+            inflight.delete(sliceId);
+            if (outcome.status === 'done') {
+                completed.add(sliceId);
+                const contract = writer(sliceId, outcome.publicSurface);
+                contracts.push(contract);
+            }
+            else if (outcome.status === 'failed') {
+                failed.push({ sliceId, reason: outcome.reason });
+                levelHasFailure = true;
+            }
+            else {
+                cancelled.push(sliceId);
+                levelHasFailure = true;
+            }
+        }
+        if (levelHasFailure) {
+            for (const id of inflight) {
+                cancelled.push(id);
+                inflight.delete(id);
+            }
+            break;
+        }
+    }
+    return {
+        dagHash,
+        completed: Array.from(completed).sort(),
+        failed,
+        cancelled: cancelled.sort(),
+        contracts
+    };
+}
+/* ──────────────────────────────────────────────────────────────────────────
+ * Slice 2026-07-28 — DAG wave + barrier (rid-029 E direction).
+ *
+ * The original `runDag` + `runLayeredDag` above dispatch an ENTIRE
+ * topological level in one `Promise.all` burst. For 24-hour scenarios
+ * with >=20 sub-agents this saturates the host. The wave planner below
+ * chunks each level into Waves of at most `maxConcurrency` slice IDs,
+ * and `runWaveWithArtifacts` runs one Wave at a time, returning a
+ * `WaveArtifact` envelope that downstream Waves can consume.
+ *
+ * Backward-compat: the original flat-dispatch APIs above are untouched;
+ * `planDispatchWaves` + `runWaveWithArtifacts` are purely additive.
+ * ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Plan a slice DAG into ordered dispatch Waves.
+ *
+ * Each topological level is split into chunks of at most
+ * `opts.maxConcurrency` slice IDs (default 6). Wave ordering follows
+ * topological level order; within each level, slices preserve
+ * `topologicalLevels`'s foundation / upstreamSync / id-asc priority sort.
+ */
+export function planDispatchWaves(dag, opts = DEFAULT_WAVE_OPTIONS) {
+    validateDag(dag);
+    if (opts.maxConcurrency <= 0) {
+        throw new DagPlanError(`WaveOptions.maxConcurrency must be > 0 (got ${opts.maxConcurrency})`);
+    }
+    const levels = topologicalLevels(dag);
+    const waves = [];
+    let waveIndex = 0;
+    for (const level of levels) {
+        for (let i = 0; i < level.length; i += opts.maxConcurrency) {
+            const chunk = level.slice(i, i + opts.maxConcurrency);
+            waves.push({ waveIndex, slices: chunk });
+            waveIndex += 1;
+        }
+    }
+    return waves;
+}
+/**
+ * Backward-compat wrapper: flatten `planDispatchWaves(dag)` into a flat
+ * sequence of stub `DispatchSpec`s. The original `runDag` /
+ * `runLayeredDag` do NOT consume this; the wrapper exists only so
+ * external callers that imported `planDispatch(dag)` keep their shape.
+ */
+export function planDispatch(dag) {
+    const waves = planDispatchWaves(dag);
+    const out = [];
+    for (const w of waves) {
+        for (const sliceId of w.slices) {
+            out.push({ sliceId, role: '', label: null, prompt: '', contractBlock: '' });
+        }
+    }
+    return out;
+}
+/**
+ * Run a single Wave: dispatch `wave.slices` in parallel, return a
+ * `WaveArtifact` envelope on success. On any per-slice failure or
+ * cancellation, REJECTS with `DagPlanError` — caller treats the
+ * rejection as a barrier violation and rolls back siblings.
+ *
+ * `passArtifacts`: when true, the returned envelope includes each
+ * slice's public surface (callers splice into downstream Wave prompts).
+ *
+ * `priorArtifacts` is reserved for future artifact-injection. This MVP
+ * accepts the shape but does not yet splice it into the prompt.
+ */
+export async function runWaveWithArtifacts(dag, wave, runner, priorArtifacts = [], opts = DEFAULT_WAVE_OPTIONS) {
+    validateDag(dag);
+    if (wave.slices.length === 0) {
+        throw new DagPlanError(`runWaveWithArtifacts: wave ${wave.waveIndex} has no slices`);
+    }
+    const collectedContracts = {};
+    const completedLeaves = [];
+    const settled = await Promise.all(wave.slices.map(async (sliceId) => {
+        const spec = buildDispatchSpec(dag, sliceId, []);
+        try {
+            const outcome = await runner(spec);
+            return { sliceId, outcome };
+        }
+        catch (err) {
+            return {
+                sliceId,
+                outcome: { status: 'failed', reason: err.message }
+            };
+        }
+    }));
+    for (const { sliceId, outcome } of settled) {
+        if (outcome.status === 'done') {
+            completedLeaves.push(sliceId);
+            if (opts.passArtifacts) {
+                collectedContracts[sliceId] = outcome.publicSurface;
+            }
+        }
+        else {
+            void priorArtifacts;
+            throw new DagPlanError(`wave ${wave.waveIndex} aborted on slice ${sliceId}: ${outcome.status === 'failed' ? outcome.reason : outcome.status}`);
+        }
+    }
+    return {
+        waveIndex: wave.waveIndex,
+        completedLeaves,
+        contracts: collectedContracts,
+        passedAt: new Date().toISOString()
+    };
+}

package/dist/services/code/emit-handoff.d.ts

@@ -0,0 +1,49 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in code-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+export declare const JOB_NOT_INITIALIZED: "JOB_NOT_INITIALIZED";
+export declare const JOB_REMAINING_BLOCKED: "JOB_REMAINING_BLOCKED";
+export type EmitHandoffVerdict = {
+    readonly kind: 'allow-not-job';
+} | {
+    readonly kind: 'allow-done';
+    readonly remaining: number;
+} | {
+    readonly kind: 'allow-force-override';
+    readonly remaining: number;
+} | {
+    readonly kind: 'block-not-initialized';
+    readonly code: typeof JOB_NOT_INITIALIZED;
+    readonly jobId: string;
+} | {
+    readonly kind: 'block-remaining';
+    readonly code: typeof JOB_REMAINING_BLOCKED;
+    readonly jobId: string;
+    readonly remaining: number;
+};
+export interface EvaluateEmitHandoffInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** Suggested job id — read from job-shape.json when omitted. */
+    readonly jobId?: string;
+    readonly forceUnderJob?: boolean;
+}
+export declare function evaluateEmitHandoff(input: EvaluateEmitHandoffInput): EmitHandoffVerdict;