peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/dispatch-dag-envelope.d.ts

@@ -0,0 +1,41 @@
+import type { SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { SliceComplexity } from '../../services/dispatch/slice-dag-types.js';
+/** Everything the `--from-dag` success envelope reports, already resolved. */
+export type DagEnvelopeInput = {
+    readonly role: string;
+    readonly ide: string;
+    readonly fromDag: string;
+    readonly batchId: string;
+    readonly levelsTotal: number;
+    readonly emittedSliceIds: readonly string[];
+    readonly emittedToolCalls: readonly SubAgentToolCall[];
+    readonly firstLevelWaves: unknown;
+    readonly existingContractCount: number;
+    readonly dag: SliceDag;
+    readonly isSliceComplexity: (value: string) => value is SliceComplexity;
+};
+/** The `ok('sub-agent.dispatch', …)` envelope for a completed `--from-dag` run. */
+export declare function buildDagSuccessEnvelope(input: DagEnvelopeInput): import("peaks-loop-shared/result").ResultEnvelope<{
+    envelopeVersion: string;
+    role: string;
+    ide: string;
+    fromDag: string;
+    batchId: string;
+    dispatchCount: number;
+    levelsTotal: number;
+    firstLevel: readonly string[];
+    firstLevelWaves: unknown;
+    toolCalls: readonly SubAgentToolCall[];
+    existingContractCount: number;
+    expectedCompletionSeconds: number;
+    artifactsPublicPaths: never[];
+    orchestratorVisibleHint: string;
+    sliceMeta: {
+        id: string;
+        foundation: boolean;
+        upstreamSync: boolean;
+        complexity: SliceComplexity | null;
+    }[];
+    nextActions: string[];
+}>;

package/dist/cli/commands/dispatch-dag-envelope.js

@@ -0,0 +1,49 @@
+import { ok } from 'peaks-loop-shared/result';
+/**
+ * Per-slice scheduling metadata (foundation / upstreamSync / complexity) for
+ * the level-1 slices the envelope surfaces.
+ */
+function sliceMetaFor(ids, dag, isSliceComplexity) {
+    return ids.map((id) => {
+        const node = dag.nodes.find((n) => n.id === id);
+        return {
+            id,
+            foundation: node?.foundation === true,
+            upstreamSync: node?.upstreamSync === true,
+            complexity: node?.complexity !== undefined && isSliceComplexity(node.complexity)
+                ? node.complexity
+                : null
+        };
+    });
+}
+/** The `ok('sub-agent.dispatch', …)` envelope for a completed `--from-dag` run. */
+export function buildDagSuccessEnvelope(input) {
+    const { role, ide, fromDag, batchId, levelsTotal, emittedSliceIds, emittedToolCalls, firstLevelWaves, existingContractCount, dag, isSliceComplexity } = input;
+    const dispatchCount = emittedSliceIds.length;
+    return ok('sub-agent.dispatch', {
+        envelopeVersion: '2.1.0',
+        role,
+        ide,
+        fromDag,
+        batchId,
+        dispatchCount,
+        levelsTotal,
+        firstLevel: emittedSliceIds,
+        firstLevelWaves,
+        toolCalls: emittedToolCalls,
+        existingContractCount,
+        expectedCompletionSeconds: 60,
+        artifactsPublicPaths: [],
+        orchestratorVisibleHint: `⏳ Spawning ${dispatchCount} sub-agents via Task tool from DAG ${fromDag}, batch-id=${batchId} (ETA ~60s)`,
+        sliceMeta: sliceMetaFor(emittedSliceIds, dag, isSliceComplexity),
+        nextActions: [
+            'Execute each toolCall in your IDE; on completion, write the slice contract to .peaks/_runtime/<sid>/dispatch/contracts/<slice-id>.json.',
+            'Re-invoke `peaks sub-agent dispatch --from-dag <file>` with the same batch-id to advance to the next level once all current-level slices have written contracts.'
+        ]
+    }, [], [
+        'MVP (1.2) plans the first level via runLayeredDag orchestrator (cancel-on-fail path active); the LLM drives subsequent levels by re-invoking this command after contract writes.',
+        existingContractCount > 0
+            ? `Injected ${existingContractCount} upstream contract(s) into downstream-level prompts via formatContractInjection.`
+            : 'No upstream contracts found; first-level prompts have empty ancestor blocks.'
+    ]);
+}

package/dist/cli/commands/dispatch-dag-failure.d.ts

@@ -0,0 +1,18 @@
+import { type ProgramIO } from '../cli-helpers.js';
+/** One refusal from the `--from-dag` path, as the fields the envelope needs. */
+export type DagFailure = {
+    readonly role: string;
+    readonly code: string;
+    readonly message: string;
+    readonly extra?: Record<string, unknown>;
+    readonly nextActions: readonly string[];
+};
+/**
+ * Emit a `sub-agent.dispatch` failure envelope and mark the process failed.
+ *
+ * Returns `null` so every caller can read `if (readDag(...) === null) return;`
+ * — the three statements (print, exit code, return) are one decision and stay
+ * together, which is also what keeps each call site inside
+ * `max-lines-per-function`.
+ */
+export declare function emitDagFailure(io: ProgramIO, asJson: boolean, failure: DagFailure): null;

package/dist/cli/commands/dispatch-dag-failure.js

@@ -0,0 +1,16 @@
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+/**
+ * Emit a `sub-agent.dispatch` failure envelope and mark the process failed.
+ *
+ * Returns `null` so every caller can read `if (readDag(...) === null) return;`
+ * — the three statements (print, exit code, return) are one decision and stay
+ * together, which is also what keeps each call site inside
+ * `max-lines-per-function`.
+ */
+export function emitDagFailure(io, asJson, failure) {
+    const { role, code, message, extra, nextActions } = failure;
+    printResult(io, fail('sub-agent.dispatch', code, message, { role, toolCall: null, dispatchRecordPath: null, ...extra }, [...nextActions]), asJson);
+    process.exitCode = 1;
+    return null;
+}

package/dist/cli/commands/dispatch-dag-preflight.d.ts

@@ -0,0 +1,51 @@
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { ProgramIO } from '../cli-helpers.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+/** The three things every refusal in this path needs to be emitted. */
+export type DagScope = {
+    readonly role: string;
+    readonly asJson: boolean;
+    readonly io: ProgramIO;
+};
+/** Identity every `--from-dag` envelope is stamped with. */
+export type DagIds = {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    readonly batchId: string;
+};
+/**
+ * Resolve the project root + the four ids the DAG envelope reports.
+ *
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel; the rid keeps its `unknown-rid` default
+ * when the caller passed none.
+ */
+export declare function resolveDagIds(options: DispatchOptions): DagIds;
+/**
+ * Lazy-load the three heavy modules only when `--from-dag` is actually used.
+ *
+ * The warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf); the dynamic-import promise resolves on first
+ * call and ESM caches the module for subsequent calls in the same process.
+ */
+export declare function loadDagRuntime(): Promise<{
+    readFileSync: typeof import("fs").readFileSync;
+    validateDag: typeof import("../../services/dispatch/slice-dag.js").validateDag;
+    topologicalLevels: typeof import("../../services/dispatch/slice-dag.js").topologicalLevels;
+    isSliceComplexity: typeof import("../../services/dispatch/slice-dag-types.js").isSliceComplexity;
+    runLayeredDag: typeof import("../../services/code/dag-orchestrator.js").runLayeredDag;
+    listContracts: typeof import("../../services/dispatch/contract-store.js").listContracts;
+    hashContract: typeof import("../../services/dispatch/contract-store.js").hashContract;
+}>;
+export type DagRuntime = Awaited<ReturnType<typeof loadDagRuntime>>;
+/** Read + `JSON.parse` + `validateDag` the DAG file; `null` once refused. */
+export declare function readDagOrFail(runtime: DagRuntime, fromDag: string, scope: DagScope): SliceDag | null;
+/**
+ * Each DAG node must map to an explicitly prepared workflow graph node before
+ * sub-agent dispatch. The mapping is the `graphNode` annotation on the node,
+ * or — as a back-compat fallback — the node id itself.
+ */
+export declare function assertGraphNodesMapped(dag: SliceDag, scope: DagScope): true | null;
+/** Topologically order the DAG's nodes; `null` once the failure is emitted. */
+export declare function topologicalLevelsOrFail(runtime: DagRuntime, dag: SliceDag, fromDag: string, scope: DagScope): readonly (readonly string[])[] | null;

package/dist/cli/commands/dispatch-dag-preflight.js

@@ -0,0 +1,105 @@
+import { randomUUID } from 'node:crypto';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { emitDagFailure } from './dispatch-dag-failure.js';
+/**
+ * Resolve the project root + the four ids the DAG envelope reports.
+ *
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel; the rid keeps its `unknown-rid` default
+ * when the caller passed none.
+ */
+export function resolveDagIds(options) {
+    const projectRoot = options.project ?? process.cwd();
+    return {
+        projectRoot,
+        sid: options.sessionId ??
+            process.env.PEAKS_SESSION_ID ??
+            getCurrentSessionId(projectRoot) ??
+            'unknown-sid',
+        rid: options.requestId ?? 'unknown-rid',
+        batchId: options.batchId ?? randomUUID()
+    };
+}
+/**
+ * Lazy-load the three heavy modules only when `--from-dag` is actually used.
+ *
+ * The warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf); the dynamic-import promise resolves on first
+ * call and ESM caches the module for subsequent calls in the same process.
+ */
+export async function loadDagRuntime() {
+    const [{ readFileSync }, sliceDagMod, dagOrchestratorMod, contractStoreMod] = await Promise.all([
+        import('node:fs'),
+        import('../../services/dispatch/slice-dag.js'),
+        import('../../services/code/dag-orchestrator.js'),
+        import('../../services/dispatch/contract-store.js')
+    ]);
+    return {
+        readFileSync,
+        validateDag: sliceDagMod.validateDag,
+        topologicalLevels: sliceDagMod.topologicalLevels,
+        isSliceComplexity: sliceDagMod.isSliceComplexity,
+        runLayeredDag: dagOrchestratorMod.runLayeredDag,
+        listContracts: contractStoreMod.listContracts,
+        hashContract: contractStoreMod.hashContract
+    };
+}
+/** Read + `JSON.parse` + `validateDag` the DAG file; `null` once refused. */
+export function readDagOrFail(runtime, fromDag, scope) {
+    try {
+        const raw = runtime.readFileSync(fromDag, 'utf8');
+        const parsed = JSON.parse(raw);
+        runtime.validateDag(parsed);
+        return parsed;
+    }
+    catch (err) {
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'INVALID_DAG',
+            message: `failed to read or validate DAG from ${fromDag}: ${err.message}`,
+            nextActions: [
+                'Check the JSON file at the given path; the DAG must have {nodes, edges} and pass validateDag().'
+            ]
+        });
+    }
+}
+/**
+ * Each DAG node must map to an explicitly prepared workflow graph node before
+ * sub-agent dispatch. The mapping is the `graphNode` annotation on the node,
+ * or — as a back-compat fallback — the node id itself.
+ */
+export function assertGraphNodesMapped(dag, scope) {
+    for (const node of dag.nodes) {
+        const graphNodeId = node.graphNode;
+        const candidate = typeof graphNodeId === 'string' && graphNodeId.length > 0 ? graphNodeId : node.id;
+        if (typeof candidate === 'string' && candidate.length > 0)
+            continue;
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'PEAKS_GRAPH_NODE_REQUIRED',
+            message: `DAG node ${node.id} has no graph-node mapping (RD §4 D4c)`,
+            extra: { dagNodeId: node.id },
+            nextActions: [
+                'Annotate the DAG node with `graphNode: "<id>"` so each dispatch can bind a prepared graph node.'
+            ]
+        });
+    }
+    return true;
+}
+/** Topologically order the DAG's nodes; `null` once the failure is emitted. */
+export function topologicalLevelsOrFail(runtime, dag, fromDag, scope) {
+    try {
+        return runtime.topologicalLevels(dag);
+    }
+    catch (err) {
+        return emitDagFailure(scope.io, scope.asJson, {
+            role: scope.role,
+            code: 'INVALID_DAG',
+            message: `topologicalLevels failed for ${fromDag}: ${err.message}`,
+            nextActions: [
+                'The DAG passed validateDag() but topologicalLevels threw (likely a cycle that slipped past validateDag, or a runtime invariant).',
+                'Inspect the DAG file with the editor and re-invoke dispatch. (No peaks scan dag CLI ships in 2.7.0; if you need a programmatic DAG validator, import validateDag / topologicalLevels from src/services/dispatch/slice-dag.ts directly.)'
+            ]
+        });
+    }
+}

package/dist/cli/commands/dispatch-dag-runners.d.ts

@@ -0,0 +1,48 @@
+import type { SubAgentDispatcher, SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { DispatchSpec, SliceOutcome } from '../../services/code/dag-orchestrator.js';
+import type { SliceContract, WriteContractInput } from '../../services/dispatch/contract-store.js';
+/** What the CLI runner collected while `runLayeredDag` walked the levels. */
+export type DagEmissions = {
+    readonly toolCalls: SubAgentToolCall[];
+    readonly sliceIds: string[];
+};
+/** The resolved IDE + sub-agent dispatcher the `--from-dag` path runs on. */
+export type DagDispatcher = {
+    readonly ide: string;
+    readonly dispatcher: SubAgentDispatcher;
+};
+/** Detect the IDE and resolve its sub-agent dispatcher. */
+export declare function resolveDagDispatcher(projectRoot: string): DagDispatcher;
+/**
+ * When every first-level node declares `files`, refine the level into
+ * file-overlap waves so the LLM fans out without serializing on a shared
+ * file. Emitted additively; nodes without `files` yield `null` (legacy
+ * envelope).
+ */
+export declare function planFirstLevelWaves(dag: SliceDag, levelArr: readonly (readonly string[])[]): readonly import("../../services/dispatch/file-overlap-wave-planner.js").FileOverlapWave[] | null;
+/**
+ * The CLI runner: emit the per-slice `buildToolCall` descriptor for the first
+ * topological level, then return `done`.
+ *
+ * Returning `done` (not `cancelled`) exercises `runLayeredDag`'s join barrier
+ * and cancel-on-fail path end to end; the placeholder `publicSurface` is
+ * intentionally empty because the real surface arrives later via
+ * `peaks contract write`.
+ */
+export declare function makeCliRunner(args: {
+    firstLevelIds: ReadonlySet<string>;
+    dispatcher: SubAgentDispatcher;
+    ids: {
+        readonly rid: string;
+        readonly sid: string;
+    };
+    emissions: DagEmissions;
+}): (spec: DispatchSpec) => Promise<SliceOutcome>;
+/**
+ * Placeholder contract writer. The CLI writes nothing to disk here — the
+ * LLM-side runner does that via `peaks contract write` — but the returned
+ * placeholder must stay shape-valid: `contractHash` has to be a real SHA-256
+ * hex string computed from the slice identity (`sliceId|sessionId`).
+ */
+export declare function makeNoopWriter(hashContract: (partial: WriteContractInput) => string, sid: string): (sliceId: string) => SliceContract;

package/dist/cli/commands/dispatch-dag-runners.js

@@ -0,0 +1,73 @@
+import { detectInstalledIde } from '../../services/ide/ide-detector.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
+/** Detect the IDE and resolve its sub-agent dispatcher. */
+export function resolveDagDispatcher(projectRoot) {
+    const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
+    return { ide, dispatcher: getAdapter(ide).subAgentDispatcher };
+}
+/**
+ * When every first-level node declares `files`, refine the level into
+ * file-overlap waves so the LLM fans out without serializing on a shared
+ * file. Emitted additively; nodes without `files` yield `null` (legacy
+ * envelope).
+ */
+export function planFirstLevelWaves(dag, levelArr) {
+    const descriptors = [...(levelArr[0] ?? [])].map((id) => ({
+        id,
+        files: dag.nodes.find((n) => n.id === id)?.files ?? []
+    }));
+    const allHaveFiles = descriptors.every((d) => d.files.length > 0);
+    return descriptors.length > 0 && allHaveFiles ? planFileOverlapWaves(descriptors).waves : null;
+}
+/**
+ * The CLI runner: emit the per-slice `buildToolCall` descriptor for the first
+ * topological level, then return `done`.
+ *
+ * Returning `done` (not `cancelled`) exercises `runLayeredDag`'s join barrier
+ * and cancel-on-fail path end to end; the placeholder `publicSurface` is
+ * intentionally empty because the real surface arrives later via
+ * `peaks contract write`.
+ */
+export function makeCliRunner(args) {
+    const { firstLevelIds, dispatcher, ids, emissions } = args;
+    return async (spec) => {
+        const toolCall = dispatcher.buildToolCall({
+            role: spec.role,
+            prompt: spec.prompt,
+            requestId: ids.rid,
+            sessionId: ids.sid
+        });
+        if (firstLevelIds.has(spec.sliceId)) {
+            emissions.toolCalls.push(toolCall);
+            emissions.sliceIds.push(spec.sliceId);
+        }
+        return { status: 'done', publicSurface: { exports: [], types: [], publicSignatures: [] } };
+    };
+}
+/**
+ * Placeholder contract writer. The CLI writes nothing to disk here — the
+ * LLM-side runner does that via `peaks contract write` — but the returned
+ * placeholder must stay shape-valid: `contractHash` has to be a real SHA-256
+ * hex string computed from the slice identity (`sliceId|sessionId`).
+ */
+export function makeNoopWriter(hashContract, sid) {
+    return (sliceId) => {
+        const partial = {
+            sliceId,
+            sessionId: sid,
+            exports: [],
+            types: [],
+            publicSignatures: []
+        };
+        return {
+            sliceId,
+            sessionId: sid,
+            completedAt: new Date(0).toISOString(),
+            exports: [],
+            types: [],
+            publicSignatures: [],
+            contractHash: hashContract(partial)
+        };
+    };
+}

package/dist/cli/commands/dispatch-detached-branch.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { DispatchOptions } from './sub-agent-shared.js';
+export declare function runDetachedDispatch(io: ProgramIO, role: string, options: DispatchOptions, asJson: boolean): Promise<void>;

package/dist/cli/commands/dispatch-detached-branch.js

@@ -0,0 +1,58 @@
+// The `--mode detached` short-circuit of `peaks sub-agent dispatch`. It is lazy
+// (the handler is imported on first use) and it returns before the warm-path
+// in-process pipeline runs, so it lives in its own module.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+function resolveMaxConcurrent(options) {
+    return typeof options.maxConcurrent === 'string' && options.maxConcurrent.length > 0
+        ? Number.parseInt(options.maxConcurrent, 10)
+        : undefined;
+}
+function reportDetachedResult(io, result, asJson) {
+    // The handler's `ok` is the launch outcome (a vendor CLI that is not
+    // installed is a failure, not a footnote) — the caller must not
+    // re-wrap it as `ok()` unconditionally, which is how `ok: true` with
+    // `pid: -1` reached the orchestrator.
+    if (result.ok) {
+        printResult(io, ok(result.command, result.data, result.warnings ?? [], result.nextActions ?? []), asJson);
+    }
+    else {
+        printResult(io, fail(result.command, 'DISPATCH_DETACHED_SPAWN_FAILED', `Could not launch the vendor CLI for a detached dispatch; nothing was started.`, result.data, result.nextActions ?? []), asJson);
+        process.exitCode = 1;
+    }
+}
+function reportDetachedError(io, role, error, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'DISPATCH_DETACHED_ERROR', getErrorMessage(error), {
+        role,
+        toolCall: null,
+        dispatchRecordPath: null
+    }, [
+        'If --mode detached fails on import, the peaks-loop-internal-runtime package may be missing; reinstall and retry.',
+        'For environments without a vendor CLI on PATH, drop --mode to fall back to the default in-process dry-run.'
+    ]), asJson);
+    process.exitCode = 1;
+}
+export async function runDetachedDispatch(io, role, options, asJson) {
+    try {
+        const { dispatch: detachedDispatch } = await import('./sub-agent/detached.js');
+        const projectRoot = options.project ?? process.cwd();
+        const maxConcurrent = resolveMaxConcurrent(options);
+        const result = await detachedDispatch({
+            role,
+            prompt: typeof options.prompt === 'string' ? options.prompt : '',
+            requestId: options.requestId ?? 'unknown-rid',
+            mode: 'detached',
+            ...(typeof options.vendor === 'string' ? { vendor: options.vendor } : {}),
+            project: projectRoot,
+            json: asJson,
+            ...(options.noThrottle === true ? { noThrottle: true } : {}),
+            ...(typeof maxConcurrent === 'number' && Number.isInteger(maxConcurrent) && maxConcurrent > 0
+                ? { maxConcurrent }
+                : {})
+        });
+        reportDetachedResult(io, result, asJson);
+    }
+    catch (error) {
+        reportDetachedError(io, role, error, asJson);
+    }
+}

package/dist/cli/commands/dispatch-envelope.d.ts

@@ -0,0 +1,36 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ArtifactMeta } from '../../services/context/artifact-meta.js';
+import type { ContextGuardDecision } from '../../services/context/context-guard.js';
+import type { getAdapter } from '../../services/ide/ide-registry.js';
+import type { SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+import { type IsolationLease } from './dispatch-isolation-lease.js';
+import { type DispatchRecordWrite } from './dispatch-record-write.js';
+export interface DispatchContext {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    batchId: string;
+    asJson: boolean;
+}
+export interface DispatchEnvelopeInput {
+    ctx: DispatchContext;
+    options: DispatchOptions;
+    prompt: string;
+    adapter: ReturnType<typeof getAdapter>;
+    effectivePrompt: string;
+    toolCall: SubAgentToolCall;
+    dispatchRecordPath: string;
+    counter: DispatchRecordWrite['counter'];
+    decision: ContextGuardDecision;
+    artifactMeta: ArtifactMeta | null;
+    mustLsFilesVerification: {
+        path: string;
+        exists: boolean;
+        files: readonly string[];
+    } | null;
+    lease: IsolationLease;
+}
+export declare function emitDispatchEnvelope(io: ProgramIO, input: DispatchEnvelopeInput, warnings: string[], asJson: boolean): void;
+export declare function writeDispatchLogEntry(ctx: DispatchContext, dispatchedInBatch: number, forcedAt: string | null): void;

package/dist/cli/commands/dispatch-envelope.js

@@ -0,0 +1,104 @@
+// The `peaks sub-agent dispatch` output surface: the envelope `data` record, the
+// `nextActions` list, the `printResult` call and the best-effort log line.
+// Split out of `dispatch-commands.ts` when compressing its long functions pushed
+// that file past the 300-line cap; the bodies are byte-for-byte the originals.
+import { ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { BATCH_LIMIT } from '../../services/dispatch/batch-counter.js';
+import { buildContextImpact } from '../../services/context/artifact-meta.js';
+import { writeLogEntry } from '../../services/log/logger.js';
+function buildDispatchNextActions(counter, dispatchRecordPath) {
+    const nextActions = [
+        'Tool call is dry-run; LLM must execute the tool to actually dispatch the sub-agent.',
+        'After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record ' +
+            dispatchRecordPath +
+            '` periodically.'
+    ];
+    if (counter.warning) {
+        nextActions.push(`Batch is over the RL-1 limit (${BATCH_LIMIT}); consider splitting into multiple batches.`);
+    }
+    return nextActions;
+}
+function buildDispatchEnvelopeData(input, contextImpact) {
+    const { ctx, options, lease } = input;
+    const expectedCompletionSeconds = 45;
+    const artifactsPublicPaths = typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0
+        ? [options.writeArtifact]
+        : [];
+    const orchestratorVisibleHint = `⏳ Spawning sub-agent via Task tool: ${ctx.role} for rid=${ctx.rid}, batch-id=${ctx.batchId} (ETA ~${expectedCompletionSeconds}s)`;
+    return {
+        // an envelopeVersion marker so consumers can detect contract
+        // changes (the previous #4 dropped `data.prompt` silently).
+        envelopeVersion: '2.3.0',
+        role: ctx.role,
+        ide: input.adapter.subAgentDispatcher.label,
+        // Prompts can carry user content (sometimes test credentials /
+        // internal URLs) that has no business landing in shell history,
+        // log aggregators, or tmux scrollback. The dispatch record on
+        // disk (gitignored under .peaks/_sub_agents/) keeps the prompt
+        // for the sub-agent to read; CLI stdout stays metadata-only.
+        // Surface promptSize + originalPromptSize so the LLM-side
+        // runner can reason about the size delta without seeing the
+        // content.
+        originalPromptSize: input.prompt.length,
+        promptSize: input.effectivePrompt.length,
+        toolCall: input.toolCall,
+        dispatchRecordPath: input.dispatchRecordPath,
+        batchId: ctx.batchId,
+        dispatchedInBatch: input.counter.count,
+        forcedAt: input.decision.forcedAt,
+        contextImpact,
+        artifactMetas: input.artifactMeta ? [input.artifactMeta] : [],
+        orchestratorVisibleHint,
+        artifactsPublicPaths,
+        expectedCompletionSeconds,
+        // Part 2.C: when --isolation worktree, surface the lease
+        // handle to the LLM-side runner so it can call
+        // `peaks worktree release --lease-id <id>` after the sub-agent
+        // finishes (or rely on the next gc pass to clean up). When
+        // isolation is not requested, isolation === null.
+        isolation: lease.isolationMode,
+        leaseId: lease.leaseId,
+        worktreePath: lease.worktreePath,
+        worktreeBranch: lease.worktreeBranch,
+        // F5: anti-fake-green gate envelope surface. When
+        // `--must-ls-files <glob>` is supplied this carries the
+        // pre-dispatch verification result so the orchestrator can
+        // surface "the file exists" (or "missing — block") before
+        // spawning the sub-agent. Null when the flag is absent.
+        mustLsFilesVerification: input.mustLsFilesVerification
+    };
+}
+export function emitDispatchEnvelope(io, input, warnings, asJson) {
+    const contextImpact = buildContextImpact({
+        promptSize: input.effectivePrompt.length,
+        artifactSizes: input.artifactMeta ? [input.artifactMeta.size] : []
+    });
+    const nextActions = buildDispatchNextActions(input.counter, input.dispatchRecordPath);
+    printResult(io, ok('sub-agent.dispatch', buildDispatchEnvelopeData(input, contextImpact), warnings, nextActions), asJson);
+}
+export function writeDispatchLogEntry(ctx, dispatchedInBatch, forcedAt) {
+    // Best-effort: writeLogEntry swallows its own errors (logger.ts:155-159),
+    // so a full disk or missing ~/.peaks/logs/ dir never blocks the dispatch.
+    try {
+        writeLogEntry({
+            ts: new Date().toISOString(),
+            level: 'info',
+            command: 'sub-agent.dispatch',
+            msg: 'dispatched',
+            sessionId: ctx.sid,
+            batchId: ctx.batchId,
+            data: {
+                rid: ctx.rid,
+                role: ctx.role,
+                batchId: ctx.batchId,
+                dispatchedInBatch,
+                forcedAt
+            }
+        });
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort */
+    }
+}

package/dist/cli/commands/dispatch-from-dag.d.ts

@@ -1,3 +1,30 @@
+/**
+ * The `--from-dag` path of `peaks sub-agent dispatch`.
+ *
+ * Pulled out of `dispatch-commands.ts` to honor the file-size cap (Karpathy #2
+ * Simplicity First). The single-dispatch action stays in `dispatch-commands.ts`;
+ * the DAG-dispatch path lives here because the two share no logic — the
+ * warm-path single dispatch does NOT load slice-dag / dag-orchestrator /
+ * contract-store (slice 9 perf), while the `--from-dag` codepath loads all
+ * three on first call.
+ *
+ * 2.7.0 slice-dag-dispatcher MVP: read a SliceDag from a file and run it
+ * through `runLayeredDag`. The orchestrator's `runSlice` is a thin wrapper
+ * that emits the per-IDE `buildToolCall` envelope for each topological level.
+ *
+ * 1.2 MVP scope: this dispatches the FIRST topological level synchronously
+ * (returns the dispatch specs); subsequent levels are not surfaced in the CLI
+ * envelope because the LLM-side runner must actually execute each
+ * `buildToolCall` and write the resulting contract before level 2+ can be
+ * safely auto-advanced. The LLM re-invokes `peaks sub-agent dispatch --from-dag
+ * <file> --batch-id <id>` after writing level-1 contracts, which causes
+ * `runLayeredDag` to plan level 2+ with the level-1 ancestor contracts spliced
+ * into their dispatch prompts.
+ *
+ * Internally, `runLayeredDag` DOES iterate all levels so its join-barrier +
+ * cancel-on-fail path is exercised end-to-end during the MVP emit; only the
+ * CLI envelope is filtered to level-1 toolCalls (see `firstLevelIds`).
+ */
 import { type ProgramIO } from '../cli-helpers.js';
 import { type DispatchOptions } from './sub-agent-shared.js';
 export declare function runDispatchFromDag(role: string, options: DispatchOptions, asJson: boolean, io: ProgramIO): Promise<void>;