peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -16,7 +16,8 @@
  */
 import { existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { spawn as childProcessSpawn } from 'node:child_process';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { detectInstalledIde } from '../../services/ide/ide-detector.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
@@ -27,7 +28,7 @@ import { writeInitialDispatchRecord } from '../../services/dispatch/dispatch-rec
 import { evaluatePromptSize } from '../../services/context/context-guard.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { buildArtifactMeta, buildContextImpact } from '../../services/context/artifact-meta.js';
-import { assertSafeArtifactPath } from '../../services/context/dispatch-context-guard.js';
+import { assertSafeArtifactPath } from 'peaks-loop-shared-channel';
 import { compressPrompt } from '../../services/context/headroom-client.js';
 import { resolveHeadroomOptions } from '../../services/context/headroom-prefs.js';
 import { loadPreferences } from '../../services/preferences/preferences-service.js';
@@ -36,6 +37,8 @@ import { writeLogEntry } from '../../services/log/logger.js';
 import { HEADROOM_MODES, PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
 import { runDispatchFromDag } from './dispatch-from-dag.js';
 import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
+import { MemoryPreflightService } from '../../services/context/memory-preflight-service.js';
+import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch-system-prompt.js';
 export function registerDispatchCommand(parent, io) {
     addJsonOption(parent
         .command('dispatch')
@@ -61,7 +64,8 @@ export function registerDispatchCommand(parent, io) {
         .option('--use-headroom', 'G7.7/G9: compress the prompt via headroom-ai before dispatch (opt-in; falls back to G7 metadata-only if headroom unavailable)')
         .option('--headroom-mode <mode>', `G7.7: headroom mode (${HEADROOM_MODES.join(' | ')}); default balanced`)
         .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
-        .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')).action(async (role, options) => {
+        .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
+        .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')).action(async (role, options) => {
         const asJson = options.json === true;
         // 2.7.0 slice-dag-dispatcher MVP: --from-dag short-circuits the single
         // sub-agent path and runs the full DAG plan via `dag-orchestrator`.
@@ -78,6 +82,20 @@ export function registerDispatchCommand(parent, io) {
             process.exitCode = 1;
             return;
         }
+        // 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') {
+            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;
+        }
         if (!options.prompt || options.prompt.length === 0) {
             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:',
@@ -134,13 +152,136 @@ export function registerDispatchCommand(parent, io) {
                 ?? 'unknown-sid';
             const rid = options.requestId ?? 'unknown-rid';
             const batchId = options.batchId ?? randomUUID();
+            // Slice 2026-07-29-worktree-l2-extended Part 2.C: --isolation worktree
+            // 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`.
+            let isolationMode = null;
+            let leaseId = null;
+            let worktreePath = null;
+            let worktreeBranch = null;
+            if (typeof options.isolation === 'string' && options.isolation.length > 0) {
+                if (options.isolation !== 'worktree' && options.isolation !== 'container' && options.isolation !== 'vm') {
+                    printResult(io, fail('sub-agent.dispatch', 'INVALID_ISOLATION', `--isolation only accepts "worktree" | "container" | "vm" (got "${options.isolation}")`, {
+                        role,
+                        toolCall: null,
+                        dispatchRecordPath: null
+                    }, ['Drop --isolation or pass --isolation worktree / --isolation container / --isolation vm.']), asJson);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (options.isolation === 'container') {
+                    // Slice 2026-07-29-worktree-l2-extended Part 12: container
+                    // 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.
+                    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).
+                        leaseId = spawnResult.leaseId;
+                    }
+                    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;
+                    }
+                }
+                if (options.isolation === 'worktree') {
+                    isolationMode = 'worktree';
+                    try {
+                        const spawnResult = await spawnWorktreeLease({
+                            projectRoot,
+                            sessionId: sid,
+                            rid,
+                            role,
+                            purpose: `auto-spawned by dispatch --isolation worktree (batch=${batchId})`
+                        });
+                        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;
+                    }
+                }
+                else if (options.isolation === 'vm') {
+                    // Slice 2026-07-29-worktree-l2-extended Part 25: the
+                    // 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;
+                }
+            }
             // G7.7 / G9: resolve headroom options from preferences + CLI overrides.
             // Preferences hard-block when headroom.enabled=false (returns HEADROOM_DISABLED_BY_PREFERENCE).
             // loadPreferences can throw on schema mismatch; we fall back to defaults to avoid
             // breaking the dispatch on a stale preferences.json file.
+            let projectPrefs = DEFAULT_PREFERENCES;
             let headroomPrefs = DEFAULT_PREFERENCES.headroom;
             try {
-                headroomPrefs = loadPreferences(projectRoot).headroom;
+                projectPrefs = loadPreferences(projectRoot);
+                headroomPrefs = projectPrefs.headroom;
             }
             catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                 // Keep default preferences; the user can re-run with explicit --headroom-mode
@@ -173,7 +314,56 @@ export function registerDispatchCommand(parent, io) {
             }
             // G7.7 headroom compress (opt-in). If headroom fails or is unavailable,
             // fall back to the original prompt + emit warning.
-            let effectivePrompt = `${formatTestToolDetection()}\n\n${options.prompt}`;
+            // Slice 2026-07-22-orchestrator-memory-preflight (Task 5): prepend the
+            // memory preflight block (or silently skip when unavailable) via the
+            // pure-function builder, BEFORE the headroom-ai compress step so the
+            // compressor sees the augmented payload.
+            const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
+            const memoryBlock = await preflightService.fetchBlock(role);
+            // Slice 2026-07-29-context-evaluation-accuracy: capture the
+            // authoritative context-fill probe before composing the
+            // dispatch prompt. The probe is token-counted (IDE adapter's
+            // `compact` env-var), not a byte estimate. The composer
+            // prepends a `## Context window` block so the dispatched
+            // sub-agent reads the actual ratio instead of guessing
+            // from message length (char/4 estimates diverge by 2-4x
+            // and have caused false "context too low" reports at 60%+
+            // free).
+            let contextProbe = null;
+            try {
+                const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+                contextProbe = readContextPercent({
+                    projectRoot,
+                    sessionId: sid,
+                    env: process.env
+                });
+            }
+            catch {
+                // Probe is best-effort; the composer renders a
+                // "no probe available" hint instead of failing the
+                // dispatch.
+            }
+            const memoryAugmentedBody = buildDispatchSystemPrompt({
+                taskTitle: role,
+                taskBody: options.prompt,
+                memoryBlock,
+                contextProbe
+            });
+            // Part 2.C: when --isolation worktree, prepend an isolation envelope
+            // block so the sub-agent sees the lease id + worktree path BEFORE
+            // headroom-ai compress. The block is short (a few lines) and the
+            // compressor is expected to keep it. 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.
+            const isolationBlock = 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`
+                : '';
+            let effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}`;
             let headroomCompressed = false;
             let headroomResult = null;
             const warnings = [...decision.warnings];
@@ -190,6 +380,22 @@ export function registerDispatchCommand(parent, io) {
             let toolCall;
             try {
                 toolCall = adapter.subAgentDispatcher.buildToolCall({ role, prompt: effectivePrompt, requestId: rid, sessionId: sid });
+                // Part 2.C: stamp the toolCall with `isolation` + a sub-agent
+                // env block so adapters that surface it (Claude Code's Task
+                // tool) propagate the lease id to the spawned process. The
+                // env block is the canonical hook the PreToolUse gate reads
+                // (gate-commands.ts: process.env.PEAKS_WORKTREE_LEASE_ID).
+                if (isolationMode !== null && leaseId !== null) {
+                    const existingEnv = toolCall.args['env'] ?? {};
+                    toolCall = {
+                        ...toolCall,
+                        args: {
+                            ...toolCall.args,
+                            isolation: 'worktree',
+                            env: { ...existingEnv, PEAKS_WORKTREE_LEASE_ID: leaseId }
+                        }
+                    };
+                }
                 // Slice C of v2.11.1 — observability hook #2/7. Fire-and-forget
                 // per PRD Q4 (full-auto must never fail-loud). The
                 // synchronous emit returns {written:false} on disk-full; we
@@ -253,7 +459,20 @@ export function registerDispatchCommand(parent, io) {
                 role,
                 prompt: effectivePrompt,
                 toolCall,
-                batchId
+                batchId,
+                // Slice 2026-07-29-worktree-l2-extended Part 3.A: persist the
+                // lease id on the dispatch record so the finalize-time
+                // release hook (markCompleted / heartbeat --status done) can
+                // auto-fire `peaks worktree release` when the sub-agent
+                // completes. Null when --isolation was not requested.
+                leaseId,
+                // Slice 2026-07-29-worktree-l2-extended Part 7: stamp the
+                // ISO timestamp when the isolation mode was set up. Null
+                // when --isolation was not requested. The dashboard reads
+                // this directly off the dispatch record to compute
+                // isolation duration without cross-referencing the
+                // metrics stream.
+                isolationStartedAt: isolationMode !== null ? new Date().toISOString() : null
             });
             const counter = noteDispatched(projectRoot, sid, batchId);
             if (counter.warning) {
@@ -273,11 +492,16 @@ export function registerDispatchCommand(parent, io) {
             if (headroomResult && headroomResult.warning === 'HEADROOM_UNAVAILABLE') {
                 nextActions.push('Headroom daemon unavailable; dispatched with G7 metadata-only fallback.');
             }
+            const expectedCompletionSeconds = 45;
+            const artifactsPublicPaths = typeof options.writeArtifact === 'string' && options.writeArtifact.length > 0
+                ? [options.writeArtifact]
+                : [];
+            const orchestratorVisibleHint = `⏳ Spawning sub-agent via Task tool: ${role} for rid=${rid}, batch-id=${batchId} (ETA ~${expectedCompletionSeconds}s)`;
             printResult(io, ok('sub-agent.dispatch', {
                 // Slice 2026-06-23-audit-4th #E1: every CLI envelope carries
                 // an envelopeVersion marker so consumers can detect contract
                 // changes (the previous #4 dropped `data.prompt` silently).
-                envelopeVersion: '2.2.0',
+                envelopeVersion: '2.3.0',
                 role,
                 ide: adapter.subAgentDispatcher.label,
                 // Slice 2026-06-23-audit-3rd #4: do NOT echo `prompt` in stdout.
@@ -307,7 +531,19 @@ export function registerDispatchCommand(parent, io) {
                     : null,
                 forcedAt: decision.forcedAt,
                 contextImpact,
-                artifactMetas: artifactMeta ? [artifactMeta] : []
+                artifactMetas: artifactMeta ? [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: isolationMode,
+                leaseId,
+                worktreePath,
+                worktreeBranch
             }, warnings, nextActions), asJson);
             // Slice 2026-06-23-audit-4th #B1: structured log on success path.
             // Best-effort: writeLogEntry swallows its own errors (logger.ts:155-159),
@@ -349,3 +585,131 @@ export function registerDispatchCommand(parent, io) {
  * module loads (slice-dag / dag-orchestrator / contract-store) to the
  * --from-dag codepath only.
  */
+/**
+ * Part 2.C (slice 2026-07-29-worktree-l2-extended) — spawn a worktree
+ * lease by shelling out to `peaks worktree spawn` (avoid re-implementing
+ * the lease-write + git-worktree-add sequence in this file). The CLI
+ * does the lease write, the git worktree add, AND the error handling;
+ * we just parse the JSON envelope and surface the leaseId + path.
+ *
+ * Throws on spawn failure; the caller converts the error to a
+ * ISOLATION_SPAWN_FAILED envelope. Synchronous wait is acceptable: the
+ * dispatch is already async, the lease is a few hundred ms of FS work,
+ * and we need the leaseId before we build the dispatch record.
+ */
+function spawnWorktreeLease(args) {
+    return new Promise((resolve, reject) => {
+        const child = childProcessSpawn(process.execPath, [
+            // The compiled CLI lives in dist/cli/peaks.js. We pass the entry
+            // through node so the test suite (which also runs on the same
+            // process) and the production binary share the same path. When
+            // the binary is invoked as `peaks`, the package bin stub does
+            // this for us; here we explicitly use process.execPath + the
+            // resolved entry to avoid PATH surprises.
+            process.argv[1] ?? '',
+            'worktree', 'spawn',
+            '--rid', args.rid,
+            '--role', args.role,
+            '--purpose', args.purpose,
+            '--project', args.projectRoot,
+            '--session', args.sessionId,
+            '--json'
+        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+        child.on('error', (err) => reject(new Error(`worktree spawn subprocess failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`peaks worktree spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                reject(new Error(`peaks worktree spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                reject(new Error('peaks worktree spawn envelope is not an object'));
+                return;
+            }
+            const env = parsed;
+            if (env.ok !== true || !env.data?.lease) {
+                reject(new Error(`peaks worktree spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
+                return;
+            }
+            resolve({
+                leaseId: env.data.lease.leaseId,
+                path: env.data.lease.path,
+                branch: env.data.lease.branch,
+                expiresAt: env.data.lease.expiresAt
+            });
+            // Part 47: unref via setImmediate so the close handler
+            // finishes first and Node's stdio 'end' events drain the
+            // stdout/stderr buffers before the parent releases the
+            // child handle. Without this microtask defer, the unref
+            // races the buffered stdout close and the test receives
+            // an empty JSON envelope.
+            setImmediate(() => { child.unref(); });
+        });
+    });
+}
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 12: container
+ * isolation bridge. Shells out to `peaks container spawn` to
+ * run `docker run` + write the container lease. Returns the
+ * leaseId the dispatch record needs to persist. The shape is
+ * a subset of the spawnWorktreeLease return (just leaseId);
+ * we do not need the path/branch/expiresAt for the container
+ * path because the envelope surfaces a different set of
+ * fields (image + containerId; see container-lease.ts).
+ */
+function spawnContainerLease(args) {
+    return new Promise((resolve, reject) => {
+        const child = childProcessSpawn(process.execPath, [
+            process.argv[1] ?? '',
+            'container', 'spawn',
+            '--rid', args.rid,
+            '--role', args.role,
+            '--purpose', args.purpose,
+            '--project', args.projectRoot,
+            '--session', args.sessionId,
+            '--json'
+        ], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: true });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString('utf8'); });
+        child.stderr.on('data', (d) => { stderr += d.toString('utf8'); });
+        child.on('error', (err) => reject(new Error(`container spawn subprocess failed: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`peaks container spawn exited ${code}; stderr: ${stderr.trim() || '(empty)'}`));
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch (err) {
+                reject(new Error(`peaks container spawn produced unparseable JSON: ${err.message}; stdout: ${stdout.slice(0, 400)}`));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                reject(new Error('peaks container spawn envelope is not an object'));
+                return;
+            }
+            const env = parsed;
+            if (env.ok !== true || !env.data?.lease) {
+                reject(new Error(`peaks container spawn envelope missing lease; got: ${stdout.slice(0, 200)}`));
+                return;
+            }
+            resolve({ leaseId: env.data.lease.leaseId });
+        });
+        // See spawnWorktreeLease above for the rationale.
+        child.unref();
+    });
+}

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

@@ -28,7 +28,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { detectInstalledIde } from '../../services/ide/ide-detector.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
@@ -225,6 +225,9 @@ export async function runDispatchFromDag(role, options, asJson, io) {
         firstLevel: emittedSliceIds,
         toolCalls: emittedToolCalls,
         existingContractCount: existingContracts.length,
+        expectedCompletionSeconds: 60,
+        artifactsPublicPaths: [],
+        orchestratorVisibleHint: `⏳ Spawning ${emittedSliceIds.length} sub-agents via Task tool from DAG ${options.fromDag}, batch-id=${batchId} (ETA ~60s)`,
         // v2.15.0 follow-up — G12/G11/G2: per-slice metadata (foundation /
         // upstreamSync / complexity) for downstream scheduling decisions.
         sliceMeta: emittedSliceIds.map((id) => {

package/dist/cli/commands/doc-commands.js

@@ -9,7 +9,7 @@
 import { resolve as resolvePath } from 'node:path';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { generateSkillFromCommands, gitLogSince, renderSkillMarkdown, suggestChangelog } from '../../services/doc/doc-generator.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerDocCommands(program, io) {
     const doc = program

package/dist/cli/commands/ecc-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `peaks ecc install|status|ls|show` — Slice 3 of 4.0.0-beta.11.
+ *
+ * Drop-in replacement for the deleted `peaks agent run|list`
+ * surface. The pre-Slice-3 implementation shelled out to
+ * `npx ecc agent run ...`, but the upstream `affaan-m/everything-claude-code`
+ * v2.0.0 release has NO `ecc` binary — the repo is `agents/*.md`
+ * flat files plus SKILL.md descriptors.
+ *
+ * The new flow:
+ *   - `peaks ecc install [--ref <tag>]` downloads the ECC tarball
+ *     into `~/.peaks/cache/ecc-<sha>/agents/` (selective extract,
+ *     agents/*.md only).
+ *   - `peaks ecc status` reports the cache manifest state.
+ *   - `peaks ecc ls` lists cached agents from `<cache>/agents/*.md`,
+ *     parsing YAML frontmatter (with D-009 fallback to filename +
+ *     first body line when frontmatter is malformed).
+ *   - `peaks ecc show <name> [--section H] [--max-lines N]` prints
+ *     the SKILL.md body to stdout — this is the Skill-first path
+ *     the LLM consumes directly.
+ *
+ * The `--section` filter extracts a single H1 (`# heading`)
+ * through the next H1 — useful when the SKILL.md is large.
+ *
+ * Per the "Enhancement, not new AI CLI" tenet: this command is a
+ * download + read-only access layer. There is no `peaks ecc run`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerEccCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/ecc-commands.js

@@ -0,0 +1,119 @@
+import { downloadToCache, listCachedAgents, readAgentSkill, readCacheManifest, } from 'peaks-loop-mut';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+export function registerEccCommands(program, io) {
+    const ecc = program
+        .command('ecc')
+        .description('affaan-m/everything-claude-code cache: download + read-only access for the LLM (no subprocess; no peaks agent run).');
+    addJsonOption(ecc
+        .command('install')
+        .description('Download affaan-m/ECC to ~/.peaks/cache/ecc-<sha>/ (selective extract: agents/ subtree only).')
+        .option('--ref <tag>', 'release tag (default: latest)')).action(async (options) => {
+        const asJson = options.json === true;
+        try {
+            const result = await downloadToCache(options.ref !== undefined && options.ref.length > 0 ? { ref: options.ref } : {});
+            const envelope = ok('ecc.install', result, [], [
+                `Cache landed at ~/.peaks/cache/ecc-${result.sha}/agents/`,
+                `Inspect with: peaks ecc ls`,
+                `Consume one agent with: peaks ecc show <name>`,
+            ]);
+            printResult(io, envelope, asJson);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('ecc.install', 'FETCH_FAILED', message, { ref: options.ref ?? 'latest' }, [
+                'Network failure during ECC download. Manual fallback:',
+                '  git clone https://github.com/affaan-m/everything-claude-code.git',
+                '  Copy <repo>/agents/*.md into ~/.peaks/cache/ecc-<sha>/agents/.',
+                '  Drop a minimal ecc-installed.json manifest into ~/.peaks/cache/.',
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(ecc
+        .command('status')
+        .description('Show ECC cache state (version, sha, fetchedAt, agent count).')).action((options) => {
+        const asJson = options.json === true;
+        const manifest = readCacheManifest();
+        if (manifest === null) {
+            printResult(io, fail('ecc.status', 'NO_CACHE', 'No ECC cache found. Run `peaks ecc install` first.', { installed: false }, ['Run `peaks ecc install [--ref <tag>]` to populate ~/.peaks/cache/ecc-<sha>/agents/.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('ecc.status', manifest, [], [
+            `Inspect agents with: peaks ecc ls`,
+            `Print one agent with: peaks ecc show <name>`,
+        ]), asJson);
+    });
+    addJsonOption(ecc
+        .command('ls')
+        .description('List cached agents from <cache>/agents/*.md with parsed frontmatter.')).action((options) => {
+        const asJson = options.json === true;
+        const agents = listCachedAgents();
+        printResult(io, ok('ecc.ls', { agents }, [], [
+            'Print one with: `peaks ecc show <name>`',
+        ]), asJson);
+    });
+    addJsonOption(ecc
+        .command('show <name>')
+        .description('Print agent SKILL.md to stdout (LLM-consumable; Skill-first path).')
+        .option('--section <heading>', 'extract only the named H1 section (# <heading> through next # )')
+        .option('--max-lines <n>', 'cap stdout at N lines (default: unlimited)')).action((name, options) => {
+        const asJson = options.json === true;
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            printResult(io, fail('ecc.show', 'INVALID_NAME', `agent name must match ^[a-z][a-z0-9-]*$ (got "${name}")`, { name }, [
+                'Run `peaks ecc ls` to see valid agent names.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const body = readAgentSkill(name);
+        if (body === null) {
+            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the cache`, { name }, [
+                'Run `peaks ecc ls` to see available agents.',
+                'Or run `peaks ecc install` to (re-)populate the cache.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        let filtered = body;
+        if (typeof options.section === 'string' && options.section.length > 0) {
+            const heading = options.section.trim();
+            const lines = body.split(/\r?\n/);
+            const startIdx = lines.findIndex((line) => new RegExp(`^#\\s+${escapeRegExp(heading)}\\s*$`).test(line));
+            if (startIdx === -1) {
+                printResult(io, fail('ecc.show', 'SECTION_NOT_FOUND', `section "# ${heading}" not found in ${name}.md`, { name, section: heading }, [
+                    'Open the file directly to see section names.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            let endIdx = lines.length;
+            for (let i = startIdx + 1; i < lines.length; i += 1) {
+                const line = lines[i] ?? '';
+                if (/^#\s+/.test(line)) {
+                    endIdx = i;
+                    break;
+                }
+            }
+            filtered = lines.slice(startIdx, endIdx).join('\n');
+        }
+        if (typeof options.maxLines === 'string' && options.maxLines.length > 0) {
+            const cap = Number.parseInt(options.maxLines, 10);
+            if (Number.isInteger(cap) && cap > 0) {
+                const lines = filtered.split(/\r?\n/);
+                if (lines.length > cap)
+                    filtered = lines.slice(0, cap).join('\n');
+            }
+        }
+        if (asJson) {
+            printResult(io, ok('ecc.show', { name, body: filtered }, [], []), asJson);
+            return;
+        }
+        // Human-readable path: raw SKILL.md body to stdout (LLM-consumable).
+        io.stdout(filtered);
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}