peaks-loop 4.1.1 → 4.1.3

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.js

@@ -1,5 +1,4 @@
 /**
- * `peaks sub-agent dispatch --from-dag <file>` — slice 2026-06-23-audit-3rd #7.
  *
  * Pulled out of `dispatch-commands.ts` to honor the 800-line file cap
  * (Karpathy #2 Simplicity First). The single-dispatch action stays in
@@ -37,7 +36,6 @@ export async function runDispatchFromDag(role, options, asJson, io) {
     if (!options.fromDag)
         return;
     const projectRoot = options.project ?? process.cwd();
-    // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
     // Auto-resolve sid from .peaks/_runtime/session.json before falling back.
     const sid = options.sessionId ??
         process.env.PEAKS_SESSION_ID ??
@@ -136,7 +134,6 @@ export async function runDispatchFromDag(role, options, asJson, io) {
     // end-to-end, but they are NOT surfaced in the CLI envelope (the LLM
     // sees them only after re-invoking with fresh level-1 contracts).
     const firstLevelIds = new Set(levelArr[0] ?? []);
-    // Slice 2026-09-10-dispatch-token-and-swarm §3: 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
     // in the envelope; the topological dispatch flow itself is unchanged.
@@ -244,7 +241,6 @@ export async function runDispatchFromDag(role, options, asJson, io) {
         return;
     }
     printResult(io, ok('sub-agent.dispatch', {
-        // Slice 2026-06-23-audit-4th #E1: envelopeVersion marker
         envelopeVersion: '2.1.0',
         role,
         ide: dispatcher.label,

package/dist/cli/commands/dispatch-isolation-lease.d.ts

@@ -0,0 +1,17 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import type { DispatchOptions } from './sub-agent-shared.js';
+export interface IsolationLeaseInput {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    batchId: string;
+    asJson: boolean;
+}
+export interface IsolationLease {
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    worktreePath: string | null;
+    worktreeBranch: string | null;
+}
+export declare function resolveIsolationLease(io: ProgramIO, options: DispatchOptions, input: IsolationLeaseInput): Promise<IsolationLease | null>;

package/dist/cli/commands/dispatch-isolation-lease.js

@@ -0,0 +1,149 @@
+// The `--isolation` lease set-up of `peaks sub-agent dispatch`. Validates the mode,
+// spawns the container/worktree lease, and hands the handles back; `vm` fail-fasts
+// because the runtime is not implemented yet.
+import { fail, getErrorMessage } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { spawnWorktreeLease, spawnContainerLease } from '../../services/dispatch/isolation-lease.js';
+function rejectInvalidIsolation(io, isolation, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'INVALID_ISOLATION', `--isolation only accepts "worktree" | "container" | "vm" (got "${isolation}")`, {
+        role,
+        toolCall: null,
+        dispatchRecordPath: null
+    }, ['Drop --isolation or pass --isolation worktree / --isolation container / --isolation vm.']), asJson);
+    process.exitCode = 1;
+    return null;
+}
+async function spawnContainerIsolation(io, input) {
+    const { projectRoot, sid, rid, role, batchId, asJson } = input;
+    // isolation is now live (Part 8 contract was the
+    // bridge; Part 12 is the runtime). Shell out to
+    // `peaks container spawn` to run `docker run` and
+    // write the container lease.
+    const isolationMode = 'container';
+    try {
+        const spawnResult = await spawnContainerLease({
+            projectRoot,
+            sessionId: sid,
+            rid,
+            role,
+            purpose: `auto-spawned by dispatch --isolation container (batch=${batchId})`
+        });
+        // Reuse the leaseId variable — same field semantically
+        // (id of the isolation surface the dispatch owns).
+        return {
+            isolationMode,
+            leaseId: spawnResult.leaseId,
+            worktreePath: null,
+            worktreeBranch: null
+        };
+    }
+    catch (error) {
+        printResult(io, fail('sub-agent.dispatch', 'ISOLATION_CONTAINER_SPAWN_FAILED', getErrorMessage(error), {
+            role,
+            toolCall: null,
+            dispatchRecordPath: null
+        }, [
+            'The dispatch aborts when --isolation container lease spawn fails; retry without --isolation or fix the underlying docker error.',
+            'For environments without a docker daemon, use --isolation worktree (the L2 production path).'
+        ]), asJson);
+        process.exitCode = 1;
+        return null;
+    }
+}
+async function spawnWorktreeIsolation(io, input) {
+    const { projectRoot, sid, rid, role, batchId, asJson } = input;
+    const isolationMode = 'worktree';
+    try {
+        const spawnResult = await spawnWorktreeLease({
+            projectRoot,
+            sessionId: sid,
+            rid,
+            role,
+            purpose: `auto-spawned by dispatch --isolation worktree (batch=${batchId})`
+        });
+        return {
+            isolationMode,
+            leaseId: spawnResult.leaseId,
+            worktreePath: spawnResult.path,
+            worktreeBranch: spawnResult.branch
+        };
+    }
+    catch (error) {
+        printResult(io, fail('sub-agent.dispatch', 'ISOLATION_SPAWN_FAILED', getErrorMessage(error), {
+            role,
+            toolCall: null,
+            dispatchRecordPath: null
+        }, [
+            'The dispatch aborts when --isolation worktree lease spawn fails; retry without --isolation or fix the underlying git error.'
+        ]), asJson);
+        process.exitCode = 1;
+        return null;
+    }
+}
+function rejectVmIsolation(io, input) {
+    const { role, asJson } = input;
+    // VM isolation mode is the L4 follow-up to L4 container.
+    // The CLI contract is shipped (--isolation vm is accepted
+    // by the dispatch parser and reflected in the envelope's
+    // isolationMode type). The VM runtime (Linux KVM / macOS
+    // HyperKit / Windows Hyper-V) is a much larger follow-up
+    // and is intentionally not implemented yet — we
+    // fail-fast with ISOLATION_VM_NOT_YET_IMPLEMENTED so
+    // operators see a clear "this is a placeholder" signal
+    // rather than a silent fallback to worktree.
+    //
+    // The full implementation lives in a future rid; the
+    // design is:
+    //   1. New service: src/services/vm/vm-lease.ts (parallels
+    //      worktree-lease.ts / container-lease.ts) — pure lease
+    //      store with vmId + hypervisor + status.
+    //   2. CLI: 'peaks vm spawn --hypervisor kvm|hyperkit|hyperv
+    //      --image <name> --rid <rid> --role <role>' — runs
+    //      virsh create / hvftool / hvcreate, captures the
+    //      vm id, writes the lease.
+    //   3. CLI: 'peaks vm release --lease-id <id>' — virsh
+    //      destroy + cleanup.
+    //   4. dispatch --isolation vm: shells out to peaks vm
+    //      spawn, injects PEAKS_VM_LEASE_ID env (parallel
+    //      to PEAKS_CONTAINER_LEASE_ID).
+    //   5. PreToolUse gate: when the env var is set AND the
+    //      tool call is bash-with-vm-bearing-command,
+    //      allow via the vm lease.
+    //
+    // Until then: fail-fast.
+    printResult(io, fail('sub-agent.dispatch', 'ISOLATION_VM_NOT_YET_IMPLEMENTED', '--isolation vm is the L4 follow-up to --isolation container (Part 25 contract); the VM runtime (KVM / HyperKit / Hyper-V) is a much larger follow-up rid and is intentionally not implemented yet. Drop --isolation or pass --isolation worktree / --isolation container for now.', {
+        role,
+        toolCall: null,
+        dispatchRecordPath: null
+    }, [
+        'The VM contract is shipped (--isolation vm is accepted by the dispatch parser); the runtime is the next rid.',
+        'Use --isolation worktree (L2 production) or --isolation container (L4 docker, Part 12) for now.'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+export async function resolveIsolationLease(io, options, input) {
+    const { role, asJson } = input;
+    // auto-spawns a worktree lease and injects PEAKS_WORKTREE_LEASE_ID
+    // into the sub-agent dispatch envelope. This is the bridge that
+    // makes the lease-aware gate (Part 2.B) work for sub-agents:
+    // without this injection, the gate has no leaseId to consult and
+    // the sub-agent would need a separate `peaks worktree auth grant`.
+    if (typeof options.isolation === 'string' && options.isolation.length > 0) {
+        if (options.isolation !== 'worktree' &&
+            options.isolation !== 'container' &&
+            options.isolation !== 'vm') {
+            return rejectInvalidIsolation(io, options.isolation, role, asJson);
+        }
+        if (options.isolation === 'container') {
+            return spawnContainerIsolation(io, input);
+        }
+        if (options.isolation === 'worktree') {
+            return spawnWorktreeIsolation(io, input);
+        }
+        else if (options.isolation === 'vm') {
+            return rejectVmIsolation(io, input);
+        }
+    }
+    return { isolationMode: null, leaseId: null, worktreePath: null, worktreeBranch: null };
+}

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

@@ -0,0 +1,7 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ContextGuardDecision } from '../../services/context/context-guard.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+export declare function preflightDispatch(io: ProgramIO, role: string, options: DispatchOptions, asJson: boolean): {
+    decision: ContextGuardDecision;
+    prompt: string;
+} | null;

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

@@ -0,0 +1,105 @@
+// The `peaks sub-agent dispatch` preflight: every refusal that can be decided from
+// the argv alone, before the session id, the lease or the prompt blocks are touched.
+// Returns the prompt-size decision, or `null` when a refusal was already printed.
+import { printResult } from '../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+import { TEST_TOOL_DETECTION_BLOCK } from '../../services/dispatch/test-tool-detection.js';
+import { PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
+function rejectInvalidRole(io, role, validation, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'INVALID_ROLE', validation, { role, toolCall: null, dispatchRecordPath: null }, [
+        'Use a non-empty role string with no control characters.',
+        `Recommended: ${RECOMMENDED_ROLES}.`
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectRemovedAgentRole(io, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'ROLE_REMOVED', 'The agent role was removed in Slice 3', {
+        role,
+        reason: 'role-removed-in-slice-3',
+        toolCall: null,
+        dispatchRecordPath: null
+    }, []), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectMissingPrompt(io, role, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'MISSING_PROMPT', '--prompt is required when --from-dag is not provided', { role, toolCall: null, dispatchRecordPath: null }, [
+        'Re-run with either:',
+        '  • `--prompt <text>` for single-role dispatch, OR',
+        '  • `--from-dag <file>` for DAG-aware multi-slice dispatch (no --prompt needed; the per-slice prompt is generated from the DAG nodes).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+// DOGFOOD ONLY: --prompt-length overrides the actual prompt content with
+// a synthetic prompt of the given size in bytes. The original --prompt
+// is still required (commander needs it). This avoids ARG_MAX limits
+// on Windows when the dogfood prompt is > 200KB.
+function applyPromptLengthOverride(options) {
+    if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+        const len = Number.parseInt(options.promptLength, 10);
+        if (Number.isInteger(len) && len > 0) {
+            options.prompt = 'x'.repeat(len);
+        }
+    }
+}
+function rejectPromptTooLarge(io, role, promptLength, asJson) {
+    printResult(io, fail('sub-agent.dispatch', 'PROMPT_TOO_LARGE', `prompt exceeds ${PROMPT_LIMIT_BYTES} bytes (got ${promptLength})`, { role, toolCall: null, dispatchRecordPath: null }, [
+        'Truncate the prompt or split into multiple dispatches.',
+        'Pass --force to override the 80% threshold at CLI (NOT allowed at hook layer).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+function rejectGuardDecision(io, role, args, asJson) {
+    const { promptLength, decision } = args;
+    printResult(io, fail('sub-agent.dispatch', decision.code, `prompt size ${promptLength} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`, {
+        role,
+        toolCall: null,
+        dispatchRecordPath: null
+    }, [
+        decision.suggest ?? 'Trim prompt or pass --force to override at CLI.',
+        'PreToolUse hook layer will still reject regardless of --force (RL-30 strict).'
+    ]), asJson);
+    process.exitCode = 1;
+    return null;
+}
+export function preflightDispatch(io, role, options, asJson) {
+    const validation = validateRole(role);
+    if (validation !== null) {
+        return rejectInvalidRole(io, role, validation, asJson);
+    }
+    // Slice 3 (on-demand-ecc) D-012: the `agent` role was removed in
+    // 4.0.0-beta.11 — there is no longer a subprocess path for it
+    // (the upstream ECC v2.0.0 ships no `ecc` binary). This guard
+    // sits AFTER role validation but BEFORE the missing-prompt
+    // check so an action-path dispatch with a valid prompt still
+    // returns a clear ROLE_REMOVED envelope + exit 1. Note that
+    // Commander short-circuits `--help` BEFORE `.action()` fires,
+    // so `peaks sub-agent dispatch agent --help` continues to
+    // exit 0 with the help text — that is intentional, not a bug.
+    if (role === 'agent') {
+        return rejectRemovedAgentRole(io, role, asJson);
+    }
+    if (!options.prompt || options.prompt.length === 0) {
+        return rejectMissingPrompt(io, role, asJson);
+    }
+    // Slice 4.0.8 RD §4 D4c required `--graph-node` here, before the session
+    // id existed, so the only recovery it could offer was prose. The node is
+    // now provisioned inside the try block below, once `sid` is known.
+    applyPromptLengthOverride(options);
+    if (options.prompt.length + TEST_TOOL_DETECTION_BLOCK.length > PROMPT_LIMIT_BYTES) {
+        return rejectPromptTooLarge(io, role, options.prompt.length, asJson);
+    }
+    // G9 CLI 兜底 — evaluate prompt size against the threshold table.
+    const decision = evaluatePromptSize(options.prompt.length, { force: options.force === true });
+    if (!decision.allow) {
+        return rejectGuardDecision(io, role, { promptLength: options.prompt.length, decision }, asJson);
+    }
+    // The prompt the caller composes with: the `--prompt` the caller passed, or the
+    // synthetic one `--prompt-length` substituted for it. Handed back explicitly so a
+    // caller that has only the argv cannot mistake an absent prompt for an empty one.
+    return { decision, prompt: options.prompt };
+}

package/dist/cli/commands/dispatch-prompt-blocks.d.ts

@@ -0,0 +1,10 @@
+import { type DispatchOptions } from './sub-agent-shared.js';
+export declare function buildIsolationBlock(isolationMode: 'worktree' | 'container' | 'vm' | null, leaseId: string | null, worktreePath: string | null, worktreeBranch: string | null): string;
+export declare function buildMustLsFilesBlock(options: DispatchOptions, projectRoot: string): {
+    mustLsFilesVerification: {
+        path: string;
+        exists: boolean;
+        files: readonly string[];
+    } | null;
+    mustLsFilesBlock: string;
+};

package/dist/cli/commands/dispatch-prompt-blocks.js

@@ -0,0 +1,56 @@
+// The two prompt blocks `composeDispatchPrompt` prepends: the Part 2.C worktree
+// isolation envelope and the F5 `must_ls_files` anti-fake-green enforcement
+// block. Split out of `dispatch-prompt-composition.ts` when compressing that
+// module's long function pushed it past the 300-line cap; both bodies are the
+// originals, moved verbatim.
+import { runGitLsFiles } from '../../services/dispatch/dispatch-sub-agent.js';
+// Part 2.C: when --isolation worktree, prepend an isolation envelope
+// block so the sub-agent sees the lease id + worktree path. The block
+// is short (a few lines). We deliberately do NOT set
+// process.env.PEAKS_WORKTREE_LEASE_ID here — sub-agents are spawned
+// by the LLM in its own environment, not as children of this CLI;
+// the lease id travels through the dispatch record + prompt body.
+export function buildIsolationBlock(isolationMode, leaseId, worktreePath, worktreeBranch) {
+    return isolationMode !== null && leaseId !== null
+        ? `\n## Worktree isolation (Part 2.C)\n` +
+            `leaseId: ${leaseId}\n` +
+            `worktreePath: ${worktreePath}\n` +
+            `branch: ${worktreeBranch}\n` +
+            `You MAY ` +
+            '`git worktree add` ' +
+            `and ` +
+            '`git worktree remove` ' +
+            `against this lease without a separate ` +
+            '`peaks worktree auth grant` ' +
+            `— the PreToolUse gate reads the lease file. Run ` +
+            '`peaks worktree release --lease-id ${leaseId}` ' +
+            `when done.\n`
+        : '';
+}
+// F5 follow-up: anti-fake-green gate. When `--must-ls-files <glob>`
+// is supplied, run `git ls-files <glob>` upfront, surface the
+// result in the envelope as `mustLsFilesVerification: { path,
+// exists, files }`, and prepend a `## must_ls_files enforcement`
+// frontmatter block to the sub-agent prompt that mandates the
+// file-existence verification as the LLM's FIRST action (before
+// any "completed"/"PASS" claim). When the flag is absent the
+// field is `null` and no block is injected — old call sites
+export function buildMustLsFilesBlock(options, projectRoot) {
+    let mustLsFilesVerification = null;
+    let mustLsFilesBlock = '';
+    if (typeof options.mustLsFiles === 'string' && options.mustLsFiles.length > 0) {
+        const glob = options.mustLsFiles;
+        const files = runGitLsFiles(projectRoot, glob);
+        const exists = files.length > 0;
+        mustLsFilesVerification = { path: glob, exists, files };
+        mustLsFilesBlock =
+            `\n## must_ls_files enforcement (F5 anti-fake-green)\n` +
+                `glob: ${glob}\n` +
+                `verification: ${exists ? `EXISTS (${files.length} file${files.length === 1 ? '' : 's'} found)` : 'MISSING (no files matched the glob)'}\n` +
+                (exists ? `first match: ${files[0] ?? ''}\n` : '') +
+                `BEFORE any claim that work is "completed" or "PASS", you MUST run \`git ls-files ${glob}\` from the project root and ` +
+                `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
+                `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
+    }
+    return { mustLsFilesVerification, mustLsFilesBlock };
+}

package/dist/cli/commands/dispatch-prompt-composition.d.ts

@@ -0,0 +1,30 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import type { ContextGuardDecision } from '../../services/context/context-guard.js';
+import { type DispatchOptions } from './sub-agent-shared.js';
+export interface ComposeDispatchPromptInput {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+    role: string;
+    options: DispatchOptions;
+    /** The prompt the sub-agent receives, as `preflightDispatch` resolved it. */
+    prompt: string;
+    isolationMode: 'worktree' | 'container' | 'vm' | null;
+    leaseId: string | null;
+    worktreePath: string | null;
+    worktreeBranch: string | null;
+    decision: ContextGuardDecision;
+    asJson: boolean;
+}
+export interface ComposedDispatchPrompt {
+    adapter: ReturnType<typeof getAdapter>;
+    effectivePrompt: string;
+    warnings: string[];
+    mustLsFilesVerification: {
+        path: string;
+        exists: boolean;
+        files: readonly string[];
+    } | null;
+}
+export declare function composeDispatchPrompt(io: ProgramIO, input: ComposeDispatchPromptInput): Promise<ComposedDispatchPrompt | null>;