peaks-loop 4.0.42 → 4.0.43

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.0.43 — 2026-09-12 (一个从来拦不住东西的闸门 + 前端接口防腐层)
+
+**Highlights**:
+
+1. **`peaks audit goal` 是门面 —— 现在是真的了。** 它是所有 peaks-* 工作流的入口闸门:把一个需求变成 6 维审计加一个目标,并在审计不完整时**拒绝**让自主工作继续。而它无论输入什么都返回同一个 `scaffold-only` 空壳,所以它什么都没拦。校验服务本身是好的,**缺的只是 provider 绑定**。本版建了 peaks-loop 的第一个 LLM 客户端:读会话已经带着的环境(`ANTHROPIC_BASE_URL`;`ANTHROPIC_AUTH_TOKEN` 或 `ANTHROPIC_API_KEY`;`ANTHROPIC_MODEL` 或 `CLAUDE_CODE_SUBAGENT_MODEL`),走全局 `fetch`,**零新增运行时依赖**。
+
+   - **一个静默回退会让这个闸门和以前一样假**,所以凭据缺失时它响亮失败:exit 1,并指名缺失的那个变量。`stub` 保留给 CI,且明确标注自己是 stub。
+   - 真机跑出的第一份审计暴露了第二个洞:**提示词从没写过 `severity` 的合法取值**,模型于是自己发明了 `high` —— 而闸门放它过去了。也就是说它验了**覆盖**和**字段存在**,没验**取值合法**。现在提示词明写合法值,解析器真校验,并**从不规整坏值**:把坏值改写成好值,正是让枚举变成装饰品的做法。
+
+2. **同一个项目开两个窗口会互相串 session —— 已修。** `getCurrentSessionId` 只读一个项目级全局文件,最后开窗口的赢;而 **17 个命令**从它解析 session(job / dispatch / worktree / share / vm / web / slice-* …)。报出来的症状只是无害的那一半(`peaks job status` 报 `JOB_NOT_IN_SESSION`);有害的一半是**两个窗口各有同名 job 或 slice 时,写入落到另一个窗口的目录树里,而且不报错**。现在 caller 优先 —— 由 `peaks session info --active` 用的同一个来源解析 —— 没有绑定时回退全局文件,所以 CI 与非 IDE 调用的行为逐字节不变,且**17 个调用点一行未改**。
+
+   - 对抗 QA 随后发现底下的信任模型没有防护:绑定指向的 session 目录已不存在时仍被信任,而轮转从不清理绑定,于是轮转后 `peaks job init` 会解析到旧 id、并在其下重建 job 目录树。现在绑定分 `bound | stale | absent`,目录不存在即视为陈旧,且**回落这件事是可观测的**。
+   - `lastActivityAt` **删除而非启用**,理由值得记下:它的写入侧本来就是坏的(只在首次绑定和显式重绑时写、复用时不写),所以时间戳在一个**活着的**窗口上照常变老 —— 做 TTL 反而会把"活着但空闲"的窗口解绑,复活刚修掉的那个串档。而时钟也看不见它报的两个缺陷(目录没了、轮转)。
+
+3. **前端/全栈的接口防腐层。** 新增 `peaks scan api-diff <doc>`:解析 OpenAPI 3.x 文档,与项目**已经**产出的三份东西对账(mock-plan、`*-api.types.ts`、TXT handoff 端点清单),输出分成**精确段**(两侧都解析过)与**候选段**(名字 grep,明标会过报漏报)。不建新产物、不做 codegen、不加运行时依赖。
+
+   - 关键取舍写在**输出里**而不是文档里:**生成的类型只能保证"文档↔代码",永远保证不了"文档↔服务器"。** 如果文档本身过时,类型、客户端、mapper 会从**同一份错文档**重新生成、**编译干净通过**、页面渲染 `undefined` —— 而"文档到手"正是这个需求的触发点。所以**诚实的边界是功能的一部分**,不是免责声明。
+   - 两侧遵循同一条规则:**读不全就不说。** 任何无法完整读取的接口或位置都被压制,并附一条能定位到文件/接口/操作 + 原因的 note。这条规则必须同时应用在记录侧**和**文档侧 —— 两者不对称是最后被发现的那处结构性缺口。
+   - 配套:项目扫描新增**三态**集成模式(`full-stack` / `prd-plus-interface-doc` / `prd-only`,从已有信号确定性推导,不新增探测)、缺失的 `## API` 扫描节、RD **按模式路由**(否则三态只是个没人读的死字段)、以及读取 hook **内容**并报告观察到的约定,以**不一致**为信号。
+   - 明确**不做**的事:不检测"组件直接消费 DTO"。那是**类型流**性质,正则表达式只会命中唯一合法的 mapper import、却漏掉真正的违规 —— 一条会打偏的规则比没有规则更糟。
+
+4. **`peaks test <file>` 在 Windows 上从来就没跑通过。** 它 spawn 裸名 `vitest`,而 Windows 上 runner 是 `node_modules/.bin/vitest.cmd` —— 而**这个命令自己的文档**写着"会替你解析本地二进制,Windows 感知"。现在解析项目本地 runner。两种形式都是**实测而非猜测**:直接 spawn `.CMD` 返回 `EINVAL`,而那个"显然的修法" `{shell:true}` 会**破坏 argv**(`tests/a b/x.test.ts` 会变成 3 个参数),所以走显式 `cmd.exe`。找不到 runner 时列出**每一条探过的路径**加修法,而不是抛裸 `ENOENT`。
+
+5. **一处三方分歧:生成的 `frontendOnly` 写在一个标题下、模板写在另一个、读取方从第三个读。** 实际是**四方** —— 找出来的第四方是一份**写入指令**,不改它,下一次 LLM 写的扫描就会重新制造这个漂移。生成器已对齐,新守卫**同时断言该行存在、且在旧位置缺席**(只断言存在的守卫,正是这一整类缺陷反复出厂的原因)。
+
+**验证**:三个版本常量一致(**4.0.43**);`tsc -p tsconfig.build.json` exit 0;宽 `tsconfig.json` 保持 **142** 基线;`tests/unit` **201 files / 1975 passed / 3 skipped / 0 failed**;`pnpm build` 的 `build-integrity` OK。
+
 ## 4.0.42 — 2026-09-12 (peaks 自己的钩子在每次编辑时报错)
 
 **Highlights**:

package/README-en.md

@@ -140,7 +140,7 @@ Every lane opens with **one slash command**.
 
 | | |
 | --- | --- |
-| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.42 (2026-09-12) |
+| **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.43 (2026-09-12) |
 | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
 | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
 | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |

package/README.md

@@ -140,7 +140,7 @@ npm i -g peaks-loop
 
 | | |
 | --- | --- |
-| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.42(2026-09-12) |
+| **最新版本** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.0.43(2026-09-12) |
 | **覆盖域** | 代码(`peaks-code`) · 内容(`peaks-content`) · 项目健康(`peaks-doctor`) · 批量修 issue(`peaks-issue-fix-orchestrator`) · 自定义 SOP(`peaks-sop`) · 通用原语(`peaks-solo` 分诊 / `peaks-resume` 续 / `peaks-status` 看 / `peaks-test` 测 / `peaks-slice-decompose` 切片) |
 | **沉淀池** | `~/.peaks/` 本地池 · 跑两次自动晋升成 bee · 跑翻车让你重定义 · bee 跟着你的口味长 |
 | **测试套件** | 1096 cases · 4 packages (peaks-loop 1015 / runtime 39 / mut 22 / shared-channel 20) · **CI 首次全绿**(ubuntu + windows) · 14 BDD caller-binding coverage |

package/dist/cli/commands/_register.js

@@ -60,6 +60,7 @@ import { registerReviewerCommands } from './reviewer-commands.js';
 import { registerRoleCommands } from './role-commands.js';
 import { registerRuntimeCommands } from './runtime-commands.js';
 import { registerScanCommands } from './scan-commands.js';
+import { registerApiDiffCommands } from './api-diff-commands.js';
 import { registerShadcnCommands } from './shadcn-commands.js';
 import { registerSecurityAuditCommands } from './security-audit-commands.js';
 import { registerSedimentCommands } from './sediment-commands.js';
@@ -99,6 +100,9 @@ const REGISTRATIONS = [
     ['project-commands', registerProjectCommands], ['prd-commands', registerPrdCommands],
     ['request-commands', registerRequestCommands], ['retrospective-commands', registerRetrospectiveCommands],
     ['scan-commands', registerScanCommands], ['shadcn-commands', registerShadcnCommands],
+    // Registered after `scan-commands` on purpose: it attaches `scan api-diff`
+    // to the existing parent instead of creating a second `scan` command.
+    ['api-diff-commands', registerApiDiffCommands],
     ['slice-commands', registerSliceCommands],
     ['sop-commands', registerSopCommands], ['feedback-commands', registerFeedbackCommands],
     ['fork-commands', registerForkCommands], ['impact-commands', registerImpactCommands],

package/dist/cli/commands/api-diff-commands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * S1 / rid=api-diff-report — `peaks scan api-diff <doc>`.
+ *
+ * Group choice: `scan`, not a new top-level `api` group. `scan` already hosts
+ * `api-surface` — a read-only, `--project`-scoped API analysis that writes no
+ * artifact — so `api-diff` is a sibling of an existing command with identical
+ * semantics and an identical option shape. A new `peaks api` group would be a
+ * brand-new verb family whose cost the design (docs/superpowers/specs/
+ * 2026-09-12-frontend-acl-contract-design.md §3/§5) records as medium and
+ * acknowledged; nothing about this slice needs it.
+ *
+ * The command is read-only: it creates no contract artifact and writes no file.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerApiDiffCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/api-diff-commands.js

@@ -0,0 +1,55 @@
+/**
+ * S1 / rid=api-diff-report — `peaks scan api-diff <doc>`.
+ *
+ * Group choice: `scan`, not a new top-level `api` group. `scan` already hosts
+ * `api-surface` — a read-only, `--project`-scoped API analysis that writes no
+ * artifact — so `api-diff` is a sibling of an existing command with identical
+ * semantics and an identical option shape. A new `peaks api` group would be a
+ * brand-new verb family whose cost the design (docs/superpowers/specs/
+ * 2026-09-12-frontend-acl-contract-design.md §3/§5) records as medium and
+ * acknowledged; nothing about this slice needs it.
+ *
+ * The command is read-only: it creates no contract artifact and writes no file.
+ */
+import { ApiDiffInputError, diffApiDocument, formatApiDiffText } from '../../services/scan/api-diff-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerApiDiffCommands(program, io) {
+    // Reuse the existing `scan` parent — the add-a-new-subcommand-check-for-
+    // existing-top-level-first rule (same guard as bee-commands / asset-commands).
+    const scan = program.commands.find((c) => c.name() === 'scan') ?? program
+        .command('scan')
+        .description('Read-only project scans for tech-doc and RD handoffs');
+    addJsonOption(scan
+        .command('api-diff')
+        .description('Diff an OpenAPI 3.x document (.json/.yaml/.yml) against what this project already recorded — ' +
+        'the mock-plan, the recorded *-api.types.ts interfaces, and the TXT handoff endpoint list. ' +
+        'Read-only: creates no contract artifact. Output separates an Exact section (both sides parsed) ' +
+        'from a Candidate mentions section (name-grep, may over- and under-report), and always prints ' +
+        'what this command cannot detect.')
+        .argument('<doc>', 'path to the OpenAPI 3.x document (relative to --project, or absolute)')
+        .option('--project <path>', 'consumer project root (default: cwd)')).action((doc, options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const asJson = options.json ?? false;
+        try {
+            const report = diffApiDocument({ projectRoot, docPath: doc });
+            const nextActions = report.notes.length > 0
+                ? ['Read the notes: at least one recorded source was missing, so the Exact section is partial by construction.']
+                : [];
+            if (asJson) {
+                printResult(io, ok('scan.api-diff', report, [], nextActions), true);
+                return;
+            }
+            io.stdout(`${formatApiDiffText(report)}\n`);
+        }
+        catch (error) {
+            // A non-OpenAPI input must exit non-zero AND produce no diff output — a
+            // silent empty report is the exact failure this command exists to prevent.
+            const code = error instanceof ApiDiffInputError ? error.code : 'API_DIFF_FAILED';
+            printResult(io, fail('scan.api-diff', code, error.message, { document: doc }, [
+                'Pass a path to an OpenAPI 3.x document: a top-level `openapi: 3.x` string plus a non-empty `paths` object.'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -10,14 +10,27 @@
 import { Command } from 'commander';
 import { type AgentShieldState } from '../../services/audit/static-service.js';
 import { type ProgramIO } from '../cli-helpers.js';
+import type { AuditGoalOutput } from '../../services/audit/audit-goal-types.js';
 import type { RedLineAudit } from '../../services/audit/types.js';
 import { type AuditDecisionRecord } from '../../services/audit/decision-writer.js';
+/** `audit-failed` is a failure envelope's status — never a scaffold, never a success. */
+export type AuditGoalStatus = 'audit-complete' | 'scaffold-only' | 'audit-failed';
 export interface AuditGoalData {
-    readonly status: 'scaffold-only';
-    readonly serviceWired: true;
-    readonly providerBinding: 'pending-follow-up-slice';
+    readonly status: AuditGoalStatus;
+    /** Which LLM produced (or failed to produce) the audit. `unresolved` = rejected before binding. */
+    readonly providerBinding: 'anthropic-messages-api' | 'stub' | 'unresolved';
     readonly need: string;
     readonly projectRoot: string;
+    /** The validated 6-dimension audit. Present on success only. */
+    readonly result?: AuditGoalOutput;
+    /** The bound model. Present on a real run only. */
+    readonly model?: string;
+    /**
+     * Environment variables the binding needed and did not find. Present on a
+     * binding failure only, and verbatim: `fail()` redacts `message`, so this
+     * is the channel that reliably names what the operator must set.
+     */
+    readonly missingEnv?: readonly string[];
 }
 export interface StaticAuditData {
     readonly audit: RedLineAudit;

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

@@ -11,6 +11,9 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
 import { runStaticAudit } from '../../services/audit/static-service.js';
+import { auditGoal, IncompleteAuditError } from '../../services/audit/audit-goal-service.js';
+import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig, } from '../../services/llm/anthropic-runner.js';
+import { createStubRunner } from '../../services/llm/stub-runner.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { writeAuditDecision } from '../../services/audit/decision-writer.js';
@@ -26,7 +29,13 @@ function isSupportedArtifactKind(value) {
     return SUPPORTED_ARTIFACT_KINDS.includes(value);
 }
 /** Whitelist of supported `--llm-provider` values for `peaks audit goal`. */
-const SUPPORTED_LLM_PROVIDERS = ['stub'];
+const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
+/**
+ * The real provider is the default: `peaks audit goal` is the entry gate for
+ * every peaks-* workflow, so it must audit by default and only scaffold when
+ * a caller explicitly asks for `stub`.
+ */
+const DEFAULT_LLM_PROVIDER = 'anthropic';
 function isSupportedLlmProvider(value) {
     return SUPPORTED_LLM_PROVIDERS.includes(value);
 }
@@ -195,47 +204,69 @@ export function registerAuditCommands(program, io) {
             process.exitCode = 1;
         }
     });
-    // Fix M1 (W5) — `peaks audit goal` CLI wrapper around `auditGoal()`.
-    // The service is correctly implemented but is NOT yet wired to a real
-    // LLM provider; this CLI exposes the route with a `stub` provider that
-    // returns a scaffold envelope. A follow-up slice will bind a real
-    // provider. Until then, non-stub providers fail loudly with
-    // `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently no-op.
+    // Slice 2026-09-12-llm-provider-binding — `peaks audit goal` now runs the
+    // gate it advertises. `auditGoal()` was already correct (one `LlmRunner`
+    // call, 6-dimension validation, `IncompleteAuditError` on a partial audit);
+    // what was missing was a provider binding, so the command answered with a
+    // fixed `scaffold-only` envelope no matter what it was asked.
+    //
+    // `anthropic` is now the default and reads the session's own environment
+    // (see `resolveAnthropicConfig`). `stub` stays for CI/tests but is
+    // reported as a scaffold, and a missing credential fails loudly — a silent
+    // fall back to the scaffold envelope would leave the gate exactly as fake
+    // as it was before this slice.
     addJsonOption(audit
         .command('goal')
         .description('Audit a human need across 6 dimensions and propose a goal (peaks-audit primitive)')
         .requiredOption('--project <path>', 'target project root')
         .requiredOption('--need <text>', 'the human need to audit (becomes input.need for auditGoal())')
-        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (options) => {
+        .option('--llm-provider <name>', `LLM provider (${SUPPORTED_LLM_PROVIDERS.join(' | ')}); stub performs no audit`, DEFAULT_LLM_PROVIDER)).action(async (options) => {
         const validation = validateProjectRoot(options.project);
         if (!validation.ok) {
-            printResult(io, fail('audit.goal', validation.code, validation.message, emptyAuditGoalData(options.need, options.project), ['Verify the project path exists and is a directory']), options.json);
+            printResult(io, fail('audit.goal', validation.code, validation.message, auditGoalFailureData(options.need, options.project), ['Verify the project path exists and is a directory']), options.json);
             process.exitCode = 1;
             return;
         }
-        const provider = options.llmProvider ?? 'stub';
+        const provider = options.llmProvider ?? DEFAULT_LLM_PROVIDER;
         if (!isSupportedLlmProvider(provider)) {
-            printResult(io, fail('audit.goal', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyAuditGoalData(options.need, validation.projectRoot), [
-                'Re-run with `--llm-provider stub` (default) to exercise the wired route.',
-                'Real provider binding is tracked as a follow-up slice; see peaks-audit skill notes.'
+            printResult(io, fail('audit.goal', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, auditGoalFailureData(options.need, validation.projectRoot), [
+                `Re-run with \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for a real audit, or \`--llm-provider stub\` for an offline scaffold.`
             ]), options.json);
             process.exitCode = 1;
             return;
         }
-        // Stub provider: surface a structured "scaffold ready" envelope so the
-        // CLI route is wired and a CI test can verify it without a real LLM.
-        const data = {
-            status: 'scaffold-only',
-            serviceWired: true,
-            providerBinding: 'pending-follow-up-slice',
-            need: options.need,
-            projectRoot: validation.projectRoot,
-        };
-        const envelope = ok('audit.goal', data, [], [
-            'auditGoal() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
-            'A follow-up slice will bind a real LLM provider; until then, non-stub providers fail loudly with `LLM_PROVIDER_NOT_IMPLEMENTED`.'
-        ]);
-        printResult(io, envelope, options.json);
+        const isStub = provider === 'stub';
+        const providerBinding = isStub ? 'stub' : 'anthropic-messages-api';
+        try {
+            let model;
+            let llmRunner;
+            if (isStub) {
+                llmRunner = createStubRunner();
+            }
+            else {
+                const config = resolveAnthropicConfig();
+                model = config.model;
+                llmRunner = createAnthropicRunner(config);
+            }
+            const result = await auditGoal({ need: options.need }, llmRunner);
+            const data = {
+                status: isStub ? 'scaffold-only' : 'audit-complete',
+                providerBinding,
+                need: options.need,
+                projectRoot: validation.projectRoot,
+                result,
+                ...(model === undefined ? {} : { model }),
+            };
+            const envelope = ok('audit.goal', data, [], isStub
+                ? [`Stub provider: the 6 dimensions below are placeholders, not findings. Re-run with \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for a real audit.`]
+                : [`Audit produced by ${providerBinding}${model === undefined ? '' : ` (model: ${model})`}.`]);
+            printResult(io, envelope, options.json);
+        }
+        catch (error) {
+            const code = auditGoalErrorCode(error);
+            printResult(io, fail('audit.goal', code, getErrorMessage(error), auditGoalFailureData(options.need, validation.projectRoot, providerBinding, error instanceof LlmBindingError ? error.missingEnv : undefined), auditGoalNextActions(code)), options.json);
+            process.exitCode = 1;
+        }
     });
     // ---------------------------------------------------------------------------
     // peaks audit artifact write — Slice 2026-06-26-audit-artifact-writer-generalization
@@ -387,15 +418,37 @@ function emptyStaticAuditData() {
         },
     };
 }
-function emptyAuditGoalData(need, projectRoot) {
+function auditGoalFailureData(need, projectRoot, providerBinding = 'unresolved', missingEnv) {
     return {
-        status: 'scaffold-only',
-        serviceWired: true,
-        providerBinding: 'pending-follow-up-slice',
+        status: 'audit-failed',
+        providerBinding,
         need,
         projectRoot,
+        ...(missingEnv === undefined ? {} : { missingEnv }),
     };
 }
+/** The slice-owned error codes are carried verbatim so callers can gate on them. */
+function auditGoalErrorCode(error) {
+    if (error instanceof IncompleteAuditError || error instanceof LlmBindingError || error instanceof LlmRequestError) {
+        return error.code;
+    }
+    return 'AUDIT_GOAL_FAILED';
+}
+function auditGoalNextActions(code) {
+    switch (code) {
+        case 'LLM_CREDENTIAL_MISSING':
+            return [
+                'Export ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) in the environment that launches peaks, then re-run.',
+                'For an offline scaffold instead of an audit, re-run with `--llm-provider stub` — it performs NO audit.',
+            ];
+        case 'LLM_MODEL_MISSING':
+            return ['Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.'];
+        case 'INCOMPLETE_AUDIT':
+            return ['The LLM reply omitted a required dimension; re-run so autonomous work never proceeds on a partial audit.'];
+        default:
+            return ['Inspect the failure above, then re-run with the same --need.'];
+    }
+}
 function emptyProseRatioResult() {
     return {
         totalRedLines: 0,

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

@@ -56,7 +56,8 @@ function findSessionHoldingJob(project, jobId) {
  * `.peaks/_runtime/session.json` binding points at another session):
  * 1. `--session-id` flag (explicit override)
  * 2. `PEAKS_SESSION_ID` env var
- * 3. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json`
+ * 3. `getCurrentSessionId(project)` — this caller's session binding, falling back
+ *    to `.peaks/_runtime/session.json` when no caller binding is resolvable
  * 4. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
  *
  * When `jobId` is passed and it is absent from the resolved session, the thrown
@@ -110,7 +111,8 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .option('--project <repo>')
         .action(async (opts) => {
         const project = projectRoot(opts);
-        // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > canonical session binding > FAIL.
+        // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > caller-first session binding
+        // (this caller's binding, else the project-global session.json) > FAIL.
         // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
         // a random UUID would scatter state across dirs and break resume/auto-compact.
         let sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);

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

@@ -30,7 +30,7 @@ export function registerScanCommands(program, io) {
     const scan = program.command('scan').description('Deterministic project scans (archetype, existing system) for Peaks workflows');
     addJsonOption(scan
         .command('archetype')
-        .description('Detect project archetype, frontend-only mode, and supporting signals from the filesystem (read-only)')
+        .description('Detect project archetype, integration mode (three scenarios), frontend-only mode, and supporting signals from the filesystem (read-only)')
         .requiredOption('--project <path>', 'target project root')).action(async (options) => {
         try {
             const report = await scanArchetype({ projectRoot: options.project });

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

@@ -6,14 +6,18 @@
  *
  *   1. Auto-detects the framework from package.json (devDependencies +
  *      dependencies) via detectTestFramework().
- *   2. Spawns the framework's CLI with --cache enabled (overriding any
+ *   2. Resolves the project-LOCAL runner binary (node_modules) and spawns
+ *      that, so the command works where the runner is not on PATH — notably
+ *      Windows, where node_modules/.bin/vitest.cmd is not spawnable without
+ *      a shell. PATH is a last resort and is reported, not silent.
+ *   3. Spawns the framework's CLI with --cache enabled (overriding any
  *      --no-cache in the consumer's `test` script). The user can
  *      opt back into no-cache via `peaks test --no-cache` or
  *      `peaks test --passthrough`.
- *   3. Skips tests where (fileMtime, fileSha256) is unchanged AND the
+ *   4. Skips tests where (fileMtime, fileSha256) is unchanged AND the
  *      previous run status was 'passed' (per-test fingerprint cache at
  *      `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json`).
- *   4. Exits 0 on all-pass / all-skip; exits 1 on any failure.
+ *   5. Exits 0 on all-pass / all-skip; exits 1 on any failure.
  *
  * The CLI is invoked by USER (not just by skill) per slice 2.5.0
  * sub-fix B (G16) — a documented exception to the
@@ -29,6 +33,7 @@
  *   peaks test --passthrough          — do NOT override the consumer's argv
  *   peaks test --framework <name>     — force a specific framework
  */
+import { spawn } from 'node:child_process';
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import { type TestFramework } from '../../services/test-cache/test-cache-service.js';
@@ -44,4 +49,56 @@ export declare function buildRunnerArgv(framework: TestFramework, patterns: stri
     cache?: boolean;
     passthrough?: boolean;
 }): string[];
+/** Successful resolution — everything `spawn` needs, plus provenance. */
+export type RunnerFound = {
+    ok: true;
+    /** Executable to spawn: node itself, a local shim, or a PATH hit. */
+    command: string;
+    /** argv for `command` (includes the JS entry when spawning node). */
+    args: string[];
+    /** How the runner was found — named in the PATH-fallback notice. */
+    via: string;
+    /** True only for the PATH fallback, which the caller surfaces visibly. */
+    fromPath: boolean;
+};
+export type RunnerResolution = RunnerFound | {
+    ok: false;
+    searched: string[];
+};
+/** Injection seams for tests — production passes nothing. */
+export type ResolveRunnerDeps = {
+    platform?: NodeJS.Platform;
+    existsSync?: (path: string) => boolean;
+    readFileSync?: (path: string) => string;
+    env?: NodeJS.ProcessEnv;
+    /** Node executable used to run the runner's JS entry. */
+    nodeExecPath?: string;
+};
+export type RunRunnerDeps = ResolveRunnerDeps & {
+    spawnFn?: typeof spawn;
+};
+/**
+ * Resolve the consumer project's LOCAL runner, and the form of it that
+ * `spawn` can actually launch on this platform.
+ *
+ * Probed, in order (every probe is reported when nothing is found):
+ *   1. `<root>/node_modules/.bin/<runner>` (+ `.cmd`/`.exe` on Windows) —
+ *      the project-local runner the command documents.
+ *   2. `<root>/node_modules/<runner>/package.json` → its `bin` JS entry.
+ *   3. PATH — last resort only; the caller prints a visible notice.
+ *
+ * Between 1 and 2 the **JS entry** wins: `spawn` runs it as
+ * `node <entry> …`, which is identical on Windows and POSIX and never
+ * routes argv through a shell. The `.cmd` shim is only a fallback because
+ * it needs cmd.exe to launch it (see `toSpawnable`).
+ */
+export declare function resolveRunner(framework: TestFramework, argv: string[], projectRoot: string, deps?: ResolveRunnerDeps): RunnerResolution;
+/** Actionable message for the no-runner case — never a raw ENOENT. */
+export declare function formatRunnerNotFound(framework: TestFramework, searched: string[]): string;
+export declare function runRunner(framework: TestFramework, argv: string[], projectRoot: string, deps?: RunRunnerDeps): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+    notice: string | null;
+}>;
 export declare function registerTestCommands(program: Command, _io: ProgramIO): void;

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

@@ -6,14 +6,18 @@
  *
  *   1. Auto-detects the framework from package.json (devDependencies +
  *      dependencies) via detectTestFramework().
- *   2. Spawns the framework's CLI with --cache enabled (overriding any
+ *   2. Resolves the project-LOCAL runner binary (node_modules) and spawns
+ *      that, so the command works where the runner is not on PATH — notably
+ *      Windows, where node_modules/.bin/vitest.cmd is not spawnable without
+ *      a shell. PATH is a last resort and is reported, not silent.
+ *   3. Spawns the framework's CLI with --cache enabled (overriding any
  *      --no-cache in the consumer's `test` script). The user can
  *      opt back into no-cache via `peaks test --no-cache` or
  *      `peaks test --passthrough`.
- *   3. Skips tests where (fileMtime, fileSha256) is unchanged AND the
+ *   4. Skips tests where (fileMtime, fileSha256) is unchanged AND the
  *      previous run status was 'passed' (per-test fingerprint cache at
  *      `<projectRoot>/.peaks/_runtime/test-cache/<hash>.json`).
- *   4. Exits 0 on all-pass / all-skip; exits 1 on any failure.
+ *   5. Exits 0 on all-pass / all-skip; exits 1 on any failure.
  *
  * The CLI is invoked by USER (not just by skill) per slice 2.5.0
  * sub-fix B (G16) — a documented exception to the
@@ -30,6 +34,8 @@
  *   peaks test --framework <name>     — force a specific framework
  */
 import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { getErrorMessage } from '../cli-helpers.js';
 import { clearTestCache, detectTestFramework } from '../../services/test-cache/test-cache-service.js';
@@ -81,10 +87,120 @@ export function buildRunnerArgv(framework, patterns, options) {
     // mocha — no built-in --cache flag; we just pass the patterns.
     return [...patterns];
 }
-function runRunner(framework, argv, projectRoot) {
+/** `<pkg>/package.json#bin`, resolved to the absolute JS entry it points at. */
+function readBinEntry(pkgJsonPath, name, read) {
+    let pkg = {};
+    try {
+        pkg = JSON.parse(read(pkgJsonPath));
+    }
+    catch {
+        // Not fatal: fall through to the `.bin` shim below, and the not-found
+        // error still names this package.json in `searched`.
+        pkg = {};
+    }
+    const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[name];
+    if (typeof rel !== 'string' || rel.length === 0)
+        return null;
+    return resolve(dirname(pkgJsonPath), rel);
+}
+/**
+ * Convert a resolved executable + argv into a form `spawn` can launch with
+ * `shell: false`.
+ *
+ * A Windows `.cmd`/`.bat` shim cannot be spawned directly (spawn → EINVAL).
+ * The obvious fix, `spawn(shim, argv, { shell: true })`, re-splits argv inside
+ * cmd.exe: a pattern `tests/a b/x.test.ts` arrives as THREE args (measured).
+ * Invoking cmd.exe ourselves with `/d /s /c` keeps argv intact.
+ */
+function toSpawnable(exe, argv, platform, env) {
+    if (platform === 'win32' && /\.(?:cmd|bat)$/i.test(exe)) {
+        return { command: env.ComSpec ?? 'cmd.exe', args: ['/d', '/s', '/c', exe, ...argv] };
+    }
+    return { command: exe, args: argv };
+}
+/** Spawnable PATH hits, in preference order (`where`/`which` avoided so this
+ * stays in-process and testable). */
+function resolveFromPath(name, platform, env, exists) {
+    const dirs = (env.PATH ?? '').split(platform === 'win32' ? ';' : ':').filter((d) => d.length > 0);
+    const exts = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const candidate = join(dir, name + ext);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the consumer project's LOCAL runner, and the form of it that
+ * `spawn` can actually launch on this platform.
+ *
+ * Probed, in order (every probe is reported when nothing is found):
+ *   1. `<root>/node_modules/.bin/<runner>` (+ `.cmd`/`.exe` on Windows) —
+ *      the project-local runner the command documents.
+ *   2. `<root>/node_modules/<runner>/package.json` → its `bin` JS entry.
+ *   3. PATH — last resort only; the caller prints a visible notice.
+ *
+ * Between 1 and 2 the **JS entry** wins: `spawn` runs it as
+ * `node <entry> …`, which is identical on Windows and POSIX and never
+ * routes argv through a shell. The `.cmd` shim is only a fallback because
+ * it needs cmd.exe to launch it (see `toSpawnable`).
+ */
+export function resolveRunner(framework, argv, projectRoot, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const exists = deps.existsSync ?? existsSync;
+    const read = deps.readFileSync ?? ((path) => readFileSync(path, 'utf8'));
+    const env = deps.env ?? process.env;
+    const nodeExec = deps.nodeExecPath ?? process.execPath;
+    const searched = [];
+    // 1. Project-local `.bin` shim.
+    const binDir = join(projectRoot, 'node_modules', '.bin');
+    const shimExts = platform === 'win32' ? ['.cmd', '.exe'] : [''];
+    let shim = null;
+    for (const ext of shimExts) {
+        const candidate = join(binDir, framework + ext);
+        searched.push(candidate);
+        if (shim === null && exists(candidate))
+            shim = candidate;
+    }
+    // 2. Project-local package entry.
+    const pkgJsonPath = join(projectRoot, 'node_modules', framework, 'package.json');
+    searched.push(pkgJsonPath);
+    const entry = exists(pkgJsonPath) ? readBinEntry(pkgJsonPath, framework, read) : null;
+    if (entry !== null && exists(entry)) {
+        return { ok: true, command: nodeExec, args: [entry, ...argv], via: `local ${entry}`, fromPath: false };
+    }
+    if (shim !== null) {
+        return { ok: true, ...toSpawnable(shim, argv, platform, env), via: `local ${shim}`, fromPath: false };
+    }
+    // 3. PATH — last resort.
+    const onPath = resolveFromPath(framework, platform, env, exists);
+    searched.push(`PATH lookup for "${framework}"`);
+    if (onPath !== null) {
+        return { ok: true, ...toSpawnable(onPath, argv, platform, env), via: `PATH: ${onPath}`, fromPath: true };
+    }
+    return { ok: false, searched };
+}
+/** Actionable message for the no-runner case — never a raw ENOENT. */
+export function formatRunnerNotFound(framework, searched) {
+    return [
+        `RUNNER_NOT_FOUND: no ${framework} runner found for this project. Looked for:`,
+        ...searched.map((p) => `  - ${p}`),
+        `Install it (e.g. \`npm i -D ${framework}\`) or pass --framework <name>.`
+    ].join('\n');
+}
+export function runRunner(framework, argv, projectRoot, deps = {}) {
+    const resolution = resolveRunner(framework, argv, projectRoot, deps);
+    if (!resolution.ok) {
+        return Promise.reject(new Error(formatRunnerNotFound(framework, resolution.searched)));
+    }
+    const notice = resolution.fromPath
+        ? `[peaks test] no local ${framework} under ${join(projectRoot, 'node_modules')}; falling back to ${resolution.via}\n`
+        : null;
     return new Promise((resolveRun, reject) => {
-        const cmd = framework === 'vitest' ? 'vitest' : framework === 'jest' ? 'jest' : 'mocha';
-        const proc = spawn(cmd, argv, {
+        const spawnFn = deps.spawnFn ?? spawn;
+        const proc = spawnFn(resolution.command, resolution.args, {
             cwd: projectRoot,
             env: process.env,
             stdio: ['ignore', 'pipe', 'pipe']
@@ -95,7 +211,7 @@ function runRunner(framework, argv, projectRoot) {
         proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
         proc.on('error', (err) => reject(err));
         proc.on('close', (code) => {
-            resolveRun({ code: code ?? 0, stdout, stderr });
+            resolveRun({ code: code ?? 0, stdout, stderr, notice });
         });
     });
 }
@@ -173,6 +289,8 @@ export function registerTestCommands(program, _io) {
             });
             // Stream the runner's output to the user.
             const result = await runRunner(framework, argv, projectRoot);
+            if (result.notice !== null)
+                process.stderr.write(result.notice);
             process.stdout.write(result.stdout);
             process.stderr.write(result.stderr);
             if (result.code !== 0) {