peaks-loop 4.0.20 → 4.0.21

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 4.0.21 — 2026-08-11 (Batch A: vendor-detect recovery + codegraph integration + anti-fake-green gate)
+
+**7 atomic commits from session 2026-08-11 (rid-001 redo → 8-子任务 codegraph → Batch A F1-F7)** + 4.0.21 lockstep bump + changelog entry:
+
+- rid-001 redo: `fix(runtime): recover vendor-detect CLI seam + handle detached spawn ENOENT` (`e8fb5ed9`, 9 files / +436/-21)
+- codegraph Phase 1: `feat(codegraph): add init conflict guard + doctor fallback + workspace auto-stake` (`e7ec3cb0`, 7 files / +849/-23)
+- codegraph Phase 2: `feat(codegraph): ship affected context envelope + tarball guard + downstream notes` (`f4b56870`, 8 files / +929/-9)
+- **F1**: `fix(runtime): expose DispatchResult.child + per-child ENOENT handler` (`b254840b`, 3 files / +96/-33)
+- **F3**: `fix(runtime): recover vendor-detect Windows ENOENT via where.exe + PATHEXT` (`fcd38369`, 5 files / +58/-18)
+- **F4**: `chore(test): fix pre-existing test rot — graph-node flag, vitest 4.x, child mock, CG-003 path` (`4ff1152a`, 5 files / +20/-6)
+- **F5**: `feat(cli): sub-agent dispatch --must-ls-files <glob> anti-fake-green gate` (`58bb4164`, 3 files / +231/-2)
+- **F6**: `fix(version): peaks-loop-shared CLI_VERSION 4.0.18 -> 4.0.20 lockstep` (`f79d3b34`, 2 files / +41/-1)
+- **F7**: `feat(codegraph): CG-003 PARTIAL verdict 4 follow-up items — preferred path + doctor probe` (`0e3b1bed`, 6 files / +469/-23)
+- `chore(release): bump to 4.0.21 — Batch A lockstep` (replaces the 4.0.22 retry commit; same diff)
+- `docs(changelog): 4.0.21 entry`
+
+**Total Batch A**: 24 files / +975/-117 lines / 11+ new test cases / 124/124 unit baseline preserved + 31 net new test cases.
+
+**Lockstep contract (per publish.yml Layer 5 + on-disk gate)**:
+- peaks-loop root `package.json#version`: 4.0.21
+- peaks-loop-shared `src/version.ts` `CLI_VERSION`: 4.0.21
+- peaks-loop-internal-runtime `src/index.ts` `RUNTIME_VERSION`: 4.0.21
+- peaks-loop-shared `package.json#version`: 0.0.54 (next available after 0.0.53 on registry — bumps through patch gaps because publish.yml auto-bump ran during 4.0.22 retry)
+- peaks-loop-internal-runtime `package.json#version`: 0.0.5 (next available after 0.0.4)
+
+**Note on the 4.0.22 attempt**: an earlier session push of tag `v4.0.21` triggered publish.yml's `Auto-bump version per smallest-semver policy` step (publish.yml:189, still present despite the v2.18.0 plan stating it should be DELETED). The parity gate caught the lockstep drift on the original commit which had only CLI_VERSION bumped (not RUNTIME_VERSION). The retry pushed `v4.0.22` to recover, but the operator wanted `4.0.21` to be the registry version (user 2026-08-11 explicit direction). The 4.0.22 registry package will be manually unpublished by the operator after this 4.0.21 publish completes.
+
+**Pending follow-ups (out of 4.0.21)**:
+- F2 detached architecture heavy refactor (in-shell background subprocess; user 2026-08-11 feedback-driven) — separate 4.0.22+ batch
+- F8 skill-resolution slice (session 7f7f78 original intent; rid-002/003/004 scope unknown — needs user scoping first)
+
+## 4.0.20 — 2026-08-11 (peaks-loop-internal-runtime published as public lockstep package)
+
+**7 commits ship'd from session 2026-08-11 (rid-001 redo → 8-子任务 codegraph → Batch A F1-F7)**:
+
+- rid-001 redo: `fix(runtime): recover vendor-detect CLI seam + handle detached spawn ENOENT` (`e8fb5ed9`, 9 files / +436/-21)
+- codegraph Phase 1: `feat(codegraph): add init conflict guard + doctor fallback + workspace auto-stake` (`e7ec3cb0`, 7 files / +849/-23)
+- codegraph Phase 2: `feat(codegraph): ship affected context envelope + tarball guard + downstream notes` (`f4b56870`, 8 files / +929/-9)
+- **F1**: `fix(runtime): expose DispatchResult.child + per-child ENOENT handler` (`b254840b`, 3 files / +96/-33) — `process.on('uncaughtException')` swallow → per-child `r.child?.on('error')` canonical pattern
+- **F3**: `fix(runtime): recover vendor-detect Windows ENOENT via where.exe + PATHEXT` (`fcd38369`, 5 files / +58/-18) — `where.exe` on win32 / `which` on POSIX, no `shell: true` (no command-injection)
+- **F4**: `chore(test): fix pre-existing test rot — graph-node flag, vitest 4.x, child mock, CG-003 path` (`4ff1152a`, 5 files / +20/-6) — 3 integration suites (dispatch-isolation-lifecycle / sub-agent-dispatch-e2e / dispatcher-flow) all PASS
+- **F5**: `feat(cli): sub-agent dispatch --must-ls-files <glob> anti-fake-green gate` (`58bb4164`, 3 files / +231/-2) — `--must-ls-files <glob>` enforces `git ls-files` on sub-agent prompt frontmatter
+- **F6**: `fix(version): peaks-loop-shared CLI_VERSION 4.0.18 -> 4.0.20 lockstep` (`f79d3b34`, 2 files / +41/-1) — lockstep guard test prevents re-introduction
+- **F7**: `feat(codegraph): CG-003 PARTIAL verdict 4 follow-up items — preferred path + doctor probe` (`0e3b1bed`, 6 files / +469/-23) — preferred `.peaks/.codegraph/` over legacy `.codegraph/`; sub-command consistency; doctor capability probe upgrade
+
+**Total Batch A**: 24 files / +975/-117 lines / 11+ new test cases / 124/124 unit baseline preserved + 31 net new test cases.
+
+**Pending follow-ups (out of 4.0.21)**:
+- F2 detached architecture heavy refactor (in-shell background subprocess; user 2026-08-11 feedback-driven) — separate 4.0.22+ batch
+- F8 skill-resolution slice (session 7f7f78 original intent; rid-002/003/004 scope unknown — needs user scoping first)
+
 ## 4.0.20 — 2026-08-11 (peaks-loop-internal-runtime published as public lockstep package)
 
 **Fix — peaks-loop@4.0.19 install 404 on `peaks-loop-internal-runtime`**:

package/README-en.md

@@ -274,6 +274,38 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
 
 ---
 
+## Downstream consumer notes
+
+If you maintain a project that depends on `peaks-loop` (or that runs `npm install peaks-loop` as part of CI / contributor onboarding), three behaviors are worth pinning in your head:
+
+- **`codegraph` is a transitive dependency.** `peaks-loop` pins `@colbymchenry/codegraph@0.7.10` in its `dependencies`, so `npm install` / `pnpm install` will pull it automatically. The CLI command group `peaks codegraph …` (status / init / index / query / files / context / affected) is shipped inside `dist/services/codegraph/`. No extra install step required.
+- **`.codegraph/` directory ownership is shared.** Tools like aider, cody, and similar agents also create a top-level `.codegraph/`. `peaks codegraph init` will refuse to overwrite a foreign schema and exits with code 73 + a `CODEGRAPH_INIT_CONFLICT` envelope. If your project already has a `.codegraph/` from another tool, move / rename it (or remove it if you no longer need it) before running `peaks codegraph init`.
+- **Session binding lives under `.peaks/_runtime/<sessionId>/`.** Codegraph orchestration context (and other per-session evidence) is written there by RD / QA slices. Add `.peaks/_runtime/` to your project's `.gitignore` to avoid committing local session state. A missing / unbound session produces a graceful skip-with-warning, never a crash.
+- **Doctor fallback for yarn-pnp / pnpm-strict.** `peaks doctor` falls back to a filesystem walk when `require.resolve('@colbymchenry/codegraph/package.json')` throws, so downstream installs under strict resolution modes still get a green check (or a `severity: 'warning'` if the version drifted from the pinned `0.7.10`).
+- **Tarball size / verify.** Each release ships the codegraph service under `dist/services/codegraph/`. Per-release verification lives at `scripts/verify-codegraph-tarball.mjs` (run `node scripts/verify-codegraph-tarball.mjs` locally before tagging a release). Exit 0 means the whitelist is intact; exit 1 means the tarball is missing the codegraph service files.
+
+Install snippet (typical consumer):
+
+```bash
+# Add peaks-loop to your project
+npm install peaks-loop
+
+# Bootstrap codegraph for the first time (refuses if .codegraph/ already
+# exists with a non-peaks-loop schema; exit code 73 + envelope)
+npx peaks codegraph init --project .
+
+# Verify the doctor is green for downstream resolution modes
+npx peaks doctor --project .
+```
+
+Three common pitfalls:
+
+1. **`peaks codegraph init` exits 73** — your project has a pre-existing `.codegraph/` from another tool. Move it out of the way (or remove it), then re-run.
+2. **`peaks doctor` warns about codegraph version drift** — your lockfile resolved a different `@colbymchenry/codegraph` version than the pinned `0.7.10`. Pin to `0.7.10` in your lockfile; the warning does not flip the doctor exit code.
+3. **Session-bound artifacts under `.peaks/_runtime/` are noisy in `git status`** — add the path to your project's `.gitignore`. The `peaks-loop` repo already does this; consumers should mirror the rule.
+
+---
+
 ## Links
 
 - All skills → [`skills/`](./skills/)

package/README.md

@@ -282,6 +282,37 @@ winget install Python.Python.3.12
 
 ---
 
+## 下游消费者须知 (Downstream consumer notes)
+
+如果你的项目依赖 `peaks-loop`(或者把 `npm install peaks-loop` 写进 CI / 协作者 onboarding),有三件事需要先记清:
+
+- **`codegraph` 是传递依赖。** `peaks-loop` 在 `dependencies` 里硬钉 `@colbymchenry/codegraph@0.7.10`,所以 `npm install` / `pnpm install` 会自动拉取。CLI 命令组 `peaks codegraph …`(status / init / index / query / files / context / affected)打包在 `dist/services/codegraph/`,无需额外安装步骤。
+- **`.codegraph/` 目录归属是共享的。** aider / cody 等类似工具也会在项目根创建 `.codegraph/`。`peaks codegraph init` 拒绝覆盖外源 schema,以 exit code 73 + `CODEGRAPH_INIT_CONFLICT` 凭据退出。如果你的项目里已经有其他工具建的 `.codegraph/`,跑 `peaks codegraph init` 之前先移走 / 改名(或确认不再需要后删除)。
+- **session 绑定落在 `.peaks/_runtime/<sessionId>/`。** codegraph 编排上下文(以及其他 session 级证据)由 RD / QA 切片写入。把 `.peaks/_runtime/` 加进项目的 `.gitignore`,避免误提交本地 session 状态。session 缺失 / 未绑定时优雅降级为「跳过 + 警告」,绝不 crash。
+- **yarn-pnp / pnpm-strict 的 doctor 兜底。** `peaks doctor` 在 `require.resolve('@colbymchenry/codegraph/package.json')` 抛错时回退到文件系统遍历,因此严格解析模式下的下游安装也能拿到绿色 check(若版本偏离钉死的 `0.7.10` 则降级为 `severity: 'warning'`)。
+- **tarball 大小 / 自检。** 每次发布都把 codegraph service 打进 `dist/services/codegraph/`。逐版本自检脚本见 `scripts/verify-codegraph-tarball.mjs`(发布前本地跑 `node scripts/verify-codegraph-tarball.mjs`)。exit 0 表示 whitelist 完好,exit 1 表示 tarball 漏了 codegraph service 文件。
+
+典型下游安装片段:
+
+```bash
+# 把 peaks-loop 加进项目
+npm install peaks-loop
+
+# 首次引导 codegraph(若项目已有外源 .codegraph/ 会以 exit 73 + 凭据拒绝)
+npx peaks codegraph init --project .
+
+# 校验 doctor 在下游解析模式下仍是绿色
+npx peaks doctor --project .
+```
+
+三个常见坑:
+
+1. **`peaks codegraph init` 退出码 73** —— 项目里已有外源 `.codegraph/`(aider / cody 等)。把它挪开(或删掉)再重跑。
+2. **`peaks doctor` 报 codegraph 版本漂移** —— 你的 lockfile 解到了一个跟钉死 `0.7.10` 不同的版本。在 lockfile 里钉到 `0.7.10`;这条 warning 不会让 doctor 退出码翻红。
+3. **`.peaks/_runtime/` 下的 session 产物在 `git status` 里嘈杂** —— 把这条路径加进项目的 `.gitignore`。`peaks-loop` 仓库已经这样做;下游消费者应当镜像这条规则。
+
+---
+
 ## 链接
 
 - 全部技能清单 → [`skills/`](./skills/)

package/dist/cli/commands/_register.js

@@ -73,6 +73,7 @@ import { registerSubAgentShutdownCommands } from './sub-agent-shutdown-commands.
 import { registerSubAgentDispatchGuard } from './sub-agent-dispatch-guard.js';
 import { registerTestCommands } from './test-commands.js';
 import { registerUnderstandCommands } from './understand-commands.js';
+import { registerVendorDetectCommand } from './vendor-detect.js';
 import { registerUpgradeCommands } from './upgrade-commands.js';
 import { registerUserTouchpointCommands } from './user-touchpoint-commands.js';
 import { registerVerdictAggregateCommands } from './verdict-aggregate-command.js';
@@ -131,6 +132,7 @@ const REGISTRATIONS = [
     ['worktree-auth-commands', registerWorktreeAuthCommand],
     ['session-spill-demo', registerSpillDemoCommand],
     ['outer-cache-commands', registerOuterCacheCommands],
+    ['vendor-detect', registerVendorDetectCommand],
 ];
 function dispatchRegister(register, program, io) {
     if (register.length <= 1) {

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

@@ -1,6 +1,8 @@
 import { InvalidArgumentError } from 'commander';
-import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
-import { fail } from 'peaks-loop-shared/result';
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createCodegraphInvocation, executeCodegraphInvocation, defaultCodegraphInitGuard, writeCodegraphMarker, writeCodegraphAffectedContext, CodegraphInitConflictError } from '../../services/codegraph/codegraph-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
 function addPeaksJsonOption(command) {
     return command.option('--peaks-json', 'print Peaks error envelope as machine-readable JSON');
@@ -45,14 +47,158 @@ async function runCodegraphCommand(io, command, options, asJson) {
         printCodegraphFailure(io, command, error, asJson);
     }
 }
+/**
+ * rid-CG-006 — init conflict guard. Resolves the project root and
+ * probes `.codegraph/` for the peaks-loop marker before invoking the
+ * upstream binary.
+ *
+ *   - fresh                          → proceed to upstream init
+ *   - noop-already-peaks-loop        → skip upstream, emit warning
+ *   - conflict-foreign-schema        → exit 73 + CODEGRAPH_INIT_CONFLICT envelope
+ *
+ * On a successful upstream init, write the marker so the next run
+ * hits the noop branch instead of the conflict branch.
+ */
+async function runCodegraphInitCommand(io, options, asJson) {
+    let projectRoot;
+    try {
+        const candidate = resolve(options.project);
+        if (!statSync(candidate).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        projectRoot = candidate;
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.init', error, asJson);
+        return;
+    }
+    const guardOutcome = defaultCodegraphInitGuard(projectRoot);
+    if (guardOutcome.status === 'noop-already-peaks-loop') {
+        printResult(io, ok('codegraph.init', {
+            guard: guardOutcome.status,
+            codegraphDir: guardOutcome.codegraphDir,
+            markerPresent: true
+        }, [`.codegraph/ is already managed by peaks-loop; init is a no-op. Marker: ${guardOutcome.codegraphDir}/.peaks-loop-marker`], ['Run `peaks codegraph index` to (re)build the index without touching the schema.']), asJson);
+        return;
+    }
+    if (guardOutcome.status === 'conflict-foreign-schema') {
+        const conflict = new CodegraphInitConflictError(`Refusing to init: ${guardOutcome.codegraphDir} already exists with a non-peaks-loop schema. ` +
+            'Move or rename the foreign directory, then re-run `peaks codegraph init`.', guardOutcome.codegraphDir);
+        printResult(io, fail('codegraph.init', conflict.code, conflict.message, { codegraphDir: conflict.codegraphDir }, [
+            'Move or rename the foreign .codegraph/ directory before retrying.',
+            'Or remove .codegraph/ if you are sure no other tool owns it.',
+            'Or run `peaks codegraph init --project <path> --force` once the foreign-tool safety flag ships (tracked in rid-CG-006).'
+        ]), asJson);
+        process.exitCode = conflict.exitCode;
+        return;
+    }
+    // guardOutcome.status === 'fresh' — proceed.
+    try {
+        const invocation = createCodegraphInvocation({
+            subcommand: 'init',
+            project: options.project,
+            ...(options.yes === true ? { yes: true } : {})
+        });
+        const result = await executeCodegraphInvocation(invocation);
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        if (result.stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        }
+        if (result.stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        }
+        if (didFail) {
+            if (asJson === true) {
+                printCodegraphFailure(io, 'codegraph.init', new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode ?? 1);
+            }
+            process.exitCode = result.exitCode ?? 1;
+            return;
+        }
+        // Upstream succeeded — stamp the marker so the next run hits the
+        // noop branch. Best-effort: a marker-write failure must NOT undo
+        // the upstream init (peaks-loop still owns the schema logically).
+        try {
+            writeCodegraphMarker(guardOutcome.codegraphDir);
+        }
+        catch {
+            // intentionally swallowed — surface as warning below
+        }
+        printResult(io, ok('codegraph.init', { guard: guardOutcome.status, codegraphDir: guardOutcome.codegraphDir, markerWritten: true }, [], [`Stamped peaks-loop marker at ${guardOutcome.codegraphDir}/.peaks-loop-marker`]), asJson);
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.init', error, asJson);
+    }
+}
+/**
+ * rid-CG-002 — codegraph-affected envelope write.
+ *
+ * Wraps the generic `runCodegraphCommand` and, after a successful
+ * upstream invocation, calls `writeCodegraphAffectedContext` so the
+ * RD / QA handoff can pick up `.peaks/_runtime/<sid>/rd/codegraph-context.md`
+ * without re-running the (5-30 s) codegraph query.
+ *
+ * The envelope write is gated by `--write-envelope` (default off) so
+ * ad-hoc CLI invocations don't silently mutate the user's session
+ * directory. peaks-code's RD dispatch hook flips the flag on.
+ *
+ * On no-session-binding, we surface a `warning` field instead of
+ * throwing — the upstream result is still printed so the caller
+ * always sees the affected list.
+ */
+async function runCodegraphAffectedCommand(io, files, options, asJson) {
+    // Capture stdout so we can re-emit it into the envelope payload.
+    // We still forward every line to the original `io.stdout` so the
+    // user sees the affected list as if the wrapper were transparent.
+    const capturedLines = [];
+    const captureIo = {
+        stdout: (chunk) => {
+            capturedLines.push(chunk);
+            io.stdout(chunk);
+        },
+        stderr: (chunk) => io.stderr(chunk)
+    };
+    await runCodegraphCommand(captureIo, 'codegraph.affected', {
+        subcommand: 'affected',
+        project: options.project,
+        files,
+        ...(options.json === true ? { json: true } : {})
+    }, asJson);
+    if (!options.writeEnvelope) {
+        return;
+    }
+    // The user opted in via --write-envelope. Run the envelope writer
+    // unconditionally (graceful fallback when no session binding).
+    const rid = options.rid ?? process.env.PEAKS_RD_RID ?? 'unknown-rid';
+    const rawStdout = capturedLines.join('\n');
+    let affectedPayload = rawStdout;
+    if (options.json === true && typeof affectedPayload === 'string' && affectedPayload.length > 0) {
+        try {
+            affectedPayload = JSON.parse(affectedPayload);
+        }
+        catch {
+            // Keep the raw string when JSON parse fails; the envelope
+            // renderer handles strings cleanly.
+        }
+    }
+    const envelope = writeCodegraphAffectedContext({
+        projectRoot: resolve(options.project),
+        rid,
+        files,
+        affectedPayload
+    });
+    if (envelope.written) {
+        if (asJson !== true) {
+            io.stdout(`[codegraph-context] wrote ${envelope.path}\n`);
+        }
+    }
+    else if (asJson !== true) {
+        io.stdout(`[codegraph-context] skipped: ${envelope.warning}\n`);
+    }
+}
 export function registerCodegraphCommands(program, io) {
     const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
     addProjectOption(codegraph.command('status').description('Show codegraph status')).action((options) => runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, options.peaksJson));
-    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphCommand(io, 'codegraph.init', {
-        subcommand: 'init',
-        project: options.project,
-        ...(options.yes === true ? { yes: true } : {})
-    }, options.peaksJson));
+    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphInitCommand(io, options, options.peaksJson));
     addProjectOption(codegraph
         .command('index')
         .description('Index a project with codegraph')
@@ -90,10 +236,7 @@ export function registerCodegraphCommands(program, io) {
         .command('affected')
         .description('Find code affected by files')
         .argument('<files...>', 'project-relative file paths')
-        .option('--json', 'forward JSON output flag to upstream codegraph')).action((files, options) => runCodegraphCommand(io, 'codegraph.affected', {
-        subcommand: 'affected',
-        project: options.project,
-        files,
-        ...(options.json === true ? { json: true } : {})
-    }, options.peaksJson));
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--rid <rid>', 'request id for the codegraph-context envelope (default: env PEAKS_RD_RID or "unknown-rid")')
+        .option('--write-envelope', 'write codegraph-context.md into the active session')).action((files, options) => runCodegraphAffectedCommand(io, files, options, options.peaksJson));
 }

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

@@ -1,6 +1,29 @@
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerDispatchCommand(parent: Command, io: ProgramIO): void;
+/**
+ * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+ * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
+ * `git ls-files <glob>` against `projectRoot` and returns the matching
+ * tracked file paths (relative to projectRoot). Empty array when no
+ * files match (e.g. untracked new file, wrong glob, not a git repo).
+ *
+ * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
+ * is "the file the sub-agent claims to have written must ACTUALLY be
+ * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
+ * would happily return untracked-but-on-disk files (false-positive
+ * for the fake-green gate).
+ *
+ * Failure modes (best-effort, never throws):
+ *  - git not on PATH → empty array (`ENOENT` swallowed)
+ *  - not a git repo → empty array (git exits non-zero)
+ *  - glob matches zero tracked files → empty array
+ *
+ * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
+ * The export is intentional — the helper has zero side effects and
+ * keeps the dispatch action handler small.
+ */
+export declare function runGitLsFiles(projectRoot: string, glob: string): readonly string[];
 /**
  * `dispatchSubAgent` is the thin programmatic wrapper the integration
  * test (`tests/integration/sub-agent-graph-binding.test.ts`) imports.

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

@@ -72,8 +72,70 @@ export function registerDispatchCommand(parent, io) {
         // rejects with PEAKS_GRAPH_NODE_REQUIRED / PEAKS_GRAPH_NODE_NOT_PREPARED.
         .requiredOption('--graph-node <id>', 'graph node id this dispatch binds to (RD §4 D4c)')
         .option('--workflow-id <id>', 'workflow id the graph node belongs to (defaults to derived from session)')
-        .option('--graph-ref <ref>', 'graphRef (defaults to graphs/<workflow-id>.json)')).action(async (role, options) => {
+        .option('--graph-ref <ref>', 'graphRef (defaults to graphs/<workflow-id>.json)')
+        // rid-001 detached sub-agent dispatch: 4 new options. Default
+        // mode is `in-process` so the 106+ existing dispatch call sites
+        // keep their path byte-identical. The detached branch below
+        // fires only when --mode detached is explicitly passed.
+        .option('--mode <mode>', 'dispatch execution mode: in-process (default, dry-run envelope only) | detached (shell out to peaks-loop-internal-runtime/dispatch.dispatchDetached for real vendor CLI execution).')
+        .option('--vendor <vendor>', 'target vendor CLI for --mode detached (claude | codex | copilot). Ignored in the default in-process path.')
+        .option('--no-throttle', 'rid-001 detached: user-overrides ResourceBudgetGuard when concurrent fan-out exceeds max-concurrent (user accepts risk; surfaces as warning)')
+        .option('--max-concurrent <n>', 'rid-001 detached: override the per-tenant max concurrent budget (default 8). Effective in both detached and in-process paths.')
+        // F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+        // §Lesson 1): the RD sub-agent's fake-green failure mode was that it
+        // claimed "5/5 reachability tests PASS" while the files were never
+        // on disk. `--must-ls-files <glob>` is the anti-fake-green gate:
+        // the CLI runs `git ls-files <glob>` upfront, reports the result in
+        // the envelope (`data.mustLsFilesVerification`), and prepends a
+        // `## must_ls_files enforcement` block to the sub-agent prompt so
+        // the LLM's first action MUST re-verify file existence before any
+        // "completed" claim. Absent → old behavior is preserved.
+        .option('--must-ls-files <glob>', 'F5: anti-fake-green gate. Run `git ls-files <glob>` upfront; surface the result in the envelope as `mustLsFilesVerification: { path, exists, files }`; prepend a must_ls_files enforcement block to the sub-agent prompt. Absent → unchanged behavior.')).action(async (role, options) => {
         const asJson = options.json === true;
+        // rid-001 detached sub-agent dispatch: when --mode detached is
+        // explicitly requested, lazy-import the detached handler and short-
+        // circuit before the warm-path in-process pipeline runs. Branch
+        // lives in the existing action handler (NOT a sibling `peaks
+        // sub-agent-detached` command) per the slice decision memo:
+        //   - 106+ existing dispatch tests reach this exact action path
+        //   - Backward compat requires the default (no --mode) to keep
+        //     the in-process envelope shape byte-identical
+        //   - One validation entry-point reduces double-pipe maintenance
+        if (options.mode === 'detached') {
+            try {
+                const { dispatch: detachedDispatch } = await import('./sub-agent/detached.js');
+                const projectRoot = options.project ?? process.cwd();
+                const maxConcurrent = typeof options.maxConcurrent === 'string' && options.maxConcurrent.length > 0
+                    ? Number.parseInt(options.maxConcurrent, 10)
+                    : undefined;
+                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 }
+                        : {}),
+                });
+                printResult(io, ok(result.command, result.data, result.warnings ?? [], result.nextActions ?? []), asJson);
+            }
+            catch (error) {
+                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;
+            }
+            return;
+        }
         // 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`.
         if (typeof options.fromDag === 'string' && options.fromDag.length > 0) {
@@ -379,7 +441,31 @@ export function registerDispatchCommand(parent, io) {
                     `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}`;
+            // 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
+            // see no behavior change (rid-001 fake-green Lesson 1).
+            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`;
+            }
+            let effectivePrompt = `${formatTestToolDetection()}\n\n${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
             let headroomCompressed = false;
             let headroomResult = null;
             const warnings = [...decision.warnings];
@@ -596,7 +682,13 @@ export function registerDispatchCommand(parent, io) {
                 isolation: isolationMode,
                 leaseId,
                 worktreePath,
-                worktreeBranch
+                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
             }, 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),
@@ -766,6 +858,38 @@ function spawnContainerLease(args) {
         child.unref();
     });
 }
+/**
+ * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+ * §Lesson 1): synchronous anti-fake-green file-existence gate. Runs
+ * `git ls-files <glob>` against `projectRoot` and returns the matching
+ * tracked file paths (relative to projectRoot). Empty array when no
+ * files match (e.g. untracked new file, wrong glob, not a git repo).
+ *
+ * Why `git ls-files` and not `fs.glob`: the anti-fake-green contract
+ * is "the file the sub-agent claims to have written must ACTUALLY be
+ * tracked by git" — `git ls-files` enforces that contract; `fs.glob`
+ * would happily return untracked-but-on-disk files (false-positive
+ * for the fake-green gate).
+ *
+ * Failure modes (best-effort, never throws):
+ *  - git not on PATH → empty array (`ENOENT` swallowed)
+ *  - not a git repo → empty array (git exits non-zero)
+ *  - glob matches zero tracked files → empty array
+ *
+ * Exported for unit-test access (`tests/unit/sub-agent/must-ls-files-flag.test.ts`).
+ * The export is intentional — the helper has zero side effects and
+ * keeps the dispatch action handler small.
+ */
+export function runGitLsFiles(projectRoot, glob) {
+    try {
+        const { execFileSync } = require('node:child_process');
+        const stdout = execFileSync('git', ['ls-files', '--', glob], { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        return stdout.split('\n').filter((line) => line.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
 /* ---------- Slice 4.0.8 RD §4 D4c: programmatic dispatcher ---------- */
 /**
  * `dispatchSubAgent` is the thin programmatic wrapper the integration

package/dist/cli/commands/sub-agent/detached.js

@@ -25,8 +25,17 @@ export async function dispatch(f) {
     if (f.noThrottle) {
         warnings.push('user-overrode: --no-throttle (peak runtime may exceed performance ceiling)');
     }
+    // rid-001 fix (F1 follow-up): the vendor CLI's ChildProcess is owned by
+    // peaks-loop-internal-runtime/dispatch.dispatchDetached, which now exposes
+    // it via DispatchResult.child. When the vendor binary is not on PATH the
+    // spawn fires an async 'error' event after dispatchDetached returns; we
+    // attach a per-child handler that swallows ENOENT (expected when the user
+    // hasn't installed claude/codex/copilot) and logs anything else. This is
+    // the canonical pattern (matches codegraph-process-runner.ts) — no more
+    // process-level uncaughtException swallow.
     const sid = process.env.PEAKS_SESSION_ID ?? 'local';
-    const r = await dispatchDetached({
+    let r;
+    r = await dispatchDetached({
         sid,
         rid: f.requestId,
         role: f.role,
@@ -37,6 +46,13 @@ export async function dispatch(f) {
         runtimeDir: `.peaks/_runtime/${sid}/detached`,
         subAgentsDir: `.peaks/_sub_agents/${sid}`,
     });
+    r.child?.on('error', (err) => {
+        if (err && err.code === 'ENOENT')
+            return;
+        // Non-ENOENT child errors are surfaced to stderr; the dispatch envelope
+        // has already been written and the detached child is fire-and-forget.
+        console.error('[peaks sub-agent dispatch] detached child error:', err);
+    });
     return {
         ok: true,
         command: 'sub-agent.dispatch.detached',

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -48,6 +48,45 @@ export type DispatchOptions = {
     graphNode?: string;
     workflowId?: string;
     graphRef?: string;
+    /**
+     * rid-001 detached sub-agent dispatch (slice 2026-08-11): dispatch
+     * execution mode. `in-process` (default) keeps the existing warm-path
+     * CLI dispatch; `detached` shells out to
+     * `peaks-loop-internal-runtime/dispatch.dispatchDetached` for vendor
+     * CLI execution. Default `in-process` preserves backward compat with
+     * the 106+ existing dispatch call sites.
+     */
+    mode?: 'in-process' | 'detached';
+    /**
+     * rid-001 detached sub-agent dispatch: target vendor CLI when
+     * --mode detached is selected. Only consulted in the detached path;
+     * ignored in the default in-process path. Accepts `claude | codex
+     * | copilot` (matches VendorAdapterRegistry).
+     */
+    vendor?: 'claude' | 'codex' | 'copilot';
+    /**
+     * rid-001 Task 11.5 budget ceiling: user-overrides ResourceBudgetGuard
+     * when active concurrent fan-out would otherwise throttle detached
+     * dispatch. The user accepts the risk; surfaces as `warnings[]` only.
+     */
+    noThrottle?: boolean;
+    /**
+     * rid-001 Task 11.5: override the per-tenant max-concurrent budget
+     * (default 8). Effective in both detached (ResourceBudgetGuard) and
+     * in-process (batch-counter) paths.
+     */
+    maxConcurrent?: string;
+    /**
+     * F5 follow-up (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure
+     * §Lesson 1): frontmatter `--must-ls-files <glob>` flag. When set, the
+     * dispatch CLI runs `git ls-files <glob>` upfront, surfaces
+     * `mustLsFilesVerification: { path, exists, files }` in the envelope,
+     * and prepends a `## must_ls_files enforcement` block to the sub-agent
+     * prompt so the LLM's first action MUST verify the file exists before
+     * claiming "PASS". Absent → unchanged behavior (backward compat with
+     * the 106+ existing dispatch call sites).
+     */
+    mustLsFiles?: string;
     json?: boolean;
 };
 export type HeartbeatOptions = {

package/dist/cli/commands/vendor-detect.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Phase B Task 20: peaks vendor-detect CLI.
+ * Reports which vendor CLIs are installed on PATH + recommends default.
+ * Spec: docs/superpowers/specs/2026-08-10-peaks-detached-sub-agent-design.md §3.3
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
 export declare function vendorDetect(opts: {
     json: boolean;
 }): Promise<{
@@ -8,3 +15,11 @@ export declare function vendorDetect(opts: {
         recommended: string | null;
     };
 }>;
+/**
+ * `peaks vendor-detect` CLI registration (rid-001 redo).
+ * Slice 2026-08-11 detached-sub-agent-design §3.3 + §5.3 — register the
+ * previously-dead-coded `vendorDetect()` handler at the top-level program
+ * surface so `peaks vendor-detect --json` actually reaches it (was
+ * dead-coded at the CLI seam even though the handler existed).
+ */
+export declare function registerVendorDetectCommand(program: Command, io: ProgramIO): void;