peaks-loop 4.0.49 → 4.0.51

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

@@ -5,9 +5,10 @@ import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall, listSuperpowersDenyEntries } from '../../services/skills/hooks-settings-service.js';
+import { resolveHookEntries, resolveHookSpec } from '../../services/skills/hooks-codegate-superpowers.js';
 import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
-import { getAdapter, resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
+import { resolveIdeOptionHelp } from '../../services/ide/ide-registry.js';
 /**
  * This module's own directory — `<root>/src/cli/commands` in the source tree,
  * `<root>/dist/cli/commands` in a build. Same reason as
@@ -50,20 +51,23 @@ function resolveIdeForCommand(options, projectRoot) {
  * service did not write.
  */
 function listExpectedEntriesForIde(ide, _skipProgress = false) {
-    const adapter = getAdapter(ide);
-    if (ide === 'trae') {
-        return [{ matcher: adapter.toolMatcher, sentinel: 'peaks hook handle' }];
-    }
-    // Slice 2026-08-06-codegate-vendor-neutral: Claude Code install
-    // also emits the Edit|Write|MultiEdit code-gate entry. The summary
-    // mirrors the install shape, NOT a hardcoded expected list. The
-    // hook source of truth is `src/services/hooks/pre-tool-code-gate.sh`
-    // (vendor-neutral); the runtime adapter is `peaks code-gate --json`
-    // registered as a PreToolUse entry.
-    return [
-        { matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' },
-        { matcher: 'Edit|Write|MultiEdit', sentinel: 'peaks code-gate' }
-    ];
+    // Derived from `resolveHookEntries(ide)` — the same function `planHookInstall`
+    // / `applyHookInstall` write from — so the summary can only ever report a
+    // shape the install actually produces. The previous version was a
+    // hand-written literal under a comment claiming it "mirrors the install
+    // shape, NOT a hardcoded expected list" (diagnosis 2026-09-15, C4); the
+    // literal had drifted from that claim in both directions: it re-typed the
+    // code-gate matcher instead of reading `HOOK_CODE_GATE_MATCHER`, and it
+    // reported 2 of the 6 entries a claude-code install writes.
+    //
+    // The filter is the tool-call event. `resolveHookEntries` also returns the
+    // once-per-session SessionStart / PostCompact entries; those are not what a
+    // per-call hook-entry summary is read for, and leaving them out is the only
+    // place this summary is narrower than the install.
+    const event = resolveHookSpec(ide).hookEnforceEvent;
+    return resolveHookEntries(ide, _skipProgress)
+        .filter((entry) => entry.event === event)
+        .map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel }));
 }
 /**
  * Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): copy the
@@ -108,6 +112,31 @@ function readOnDiskDenyEntries(settings) {
         return [];
     return deny.filter((d) => typeof d === 'string');
 }
+/**
+ * One `nextActions` line for a hook-script copy, or `null` when there is
+ * nothing to say.
+ *
+ * Diagnosis 2026-09-15 (C7): the copy failure used to be reported as a single
+ * sentence — `'<x> hook not copied (source missing or non-global scope)'` —
+ * which merged a real build failure into the expected project-scope no-op.
+ * Only `scope === 'global'` copies these scripts at all (see the call sites),
+ * so in project scope the sentence described normal behaviour in the wording
+ * of a fault, and a healthy `peaks hooks install` read as broken.
+ *
+ * Scope is therefore what decides the sentence, and it is knowable here — the
+ * copy helper cannot tell the two cases apart because both return
+ * `copied: false`, but the caller can. Project scope emits no line: there is
+ * no action to take, and the envelope's `bridgeHookCopy` / `codeGateHookCopy`
+ * field still reports `copied: false` for anyone reading the JSON.
+ */
+function describeHookCopy(label, copy, scope, dryRun) {
+    if (scope !== 'global')
+        return null;
+    if (copy.copied) {
+        return dryRun ? `would copy ${label} from ${copy.source} to ${copy.target}` : `Copied ${label}: ${copy.target}`;
+    }
+    return `${label} NOT copied — source missing at ${copy.source}. Run the build (\`pnpm build\`) so the script ships with the package.`;
+}
 function copyBridgeHookIfPresent(userHome, dryRun = false) {
     const source = resolve(MODULE_DIR, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
     const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-superpowers-bridge.sh');
@@ -202,22 +231,16 @@ export function registerHooksCommands(program, io) {
                     // committed, shared file.
                     ...plan.entryTargets.map((entry) => `would write ${entry.matcher || '(no matcher)'} → ${entry.sentinel} to ${entry.settingsPath}`),
                     `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
-                    bridgeCopy.copied
-                        ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`
-                        : 'would not copy bridge hook (source missing or non-global scope)',
-                    codeGateCopy.copied
-                        ? `would copy code-gate hook from ${codeGateCopy.source} to ${codeGateCopy.target}`
-                        : 'would not copy code-gate hook (source missing or non-global scope)'
-                ]), options.json);
+                    describeHookCopy('bridge hook', bridgeCopy, scope, true),
+                    describeHookCopy('code-gate hook', codeGateCopy, scope, true)
+                ].filter((line) => line !== null)), options.json);
                 return;
             }
             const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
-            // Slice #3: build the per-IDE entries summary from the actual installed
-            // entries, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
-            // claude-code default). The user's JSON envelope must reflect the IDE
-            // they targeted. Slice #014: the install only emits the gate-enforce
-            // entry; the summary mirrors the install shape, NOT a hardcoded
-            // expected list.
+            // Slice #3: build the per-IDE entries summary for the IDE the user
+            // targeted, not the slice #1 PEAKS_HOOK_ENTRIES constant (which is the
+            // claude-code default). The summary is derived from the install's own
+            // entry table — see `listExpectedEntriesForIde`.
             const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
             // Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): when
             // the install targets global scope, also copy the superpowers-bridge
@@ -242,16 +265,10 @@ export function registerHooksCommands(program, io) {
                     // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny
                     // write alongside the hook install — single atomic write.
                     `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
-                    bridgeCopy.copied
-                        ? `Copied bridge hook: ${bridgeCopy.target}`
-                        : 'Bridge hook not copied (source missing or non-global scope)',
-                    codeGateCopy.copied
-                        ? `Copied code-gate hook: ${codeGateCopy.target}`
-                        : 'Code-gate hook not copied (source missing or non-global scope)'
-                ]
-                : (bridgeCopy.copied
-                    ? [`Bridge hook copied: ${bridgeCopy.target}`]
-                    : []);
+                    describeHookCopy('bridge hook', bridgeCopy, scope, false),
+                    describeHookCopy('code-gate hook', codeGateCopy, scope, false)
+                ].filter((line) => line !== null)
+                : [describeHookCopy('bridge hook', bridgeCopy, scope, false)].filter((line) => line !== null);
             // Slice 2026-07-29-worktree-layer3-deny: emit L3 deny bookkeeping
             // in the JSON envelope so downstream automation (audit / sc) can
             // confirm Layer 3 was applied without re-reading the file. When

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

@@ -1,4 +1,5 @@
-import { resolve } from 'node:path';
+import { existsSync, readdirSync, realpathSync as realpathSyncNative } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from 'peaks-loop-shared-channel';
@@ -275,25 +276,45 @@ export function registerAwaitCommand(parent, io) {
         const adapter = getAdapter(ide);
         const dispatcher = adapter.subAgentDispatcher;
         if (typeof dispatcher.awaitBatch !== 'function') {
-            printResult(io, fail('sub-agent.await', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support awaitBatch (1.2 MVP only ships claude-code)`, { ok: false }, [
-                'Switch to claude-code, or rely on LLM-side await for non-claude-code IDEs in slice 1.3.'
+            printResult(io, fail('sub-agent.await', 'IDE_NOT_SUPPORTED', `IDE ${ide} does not support awaitBatch`, { ok: false }, [
+                'Every built-in adapter has an awaitBatch since slice 1.3; a dispatcher without one is a custom adapter registered outside the built-in set.'
             ]), asJson);
             process.exitCode = 1;
             return;
         }
-        // 1.2 MVP: we don't keep a separate record path index for DAG-dispatched
-        // batches yet; the caller is expected to have a single shared record
-        // directory. We pass the empty list — the MVP runner tracks outcomes
-        // through its own contract-store writes; the dispatcher just signals
-        // "ready to await" through the awaitBatch LRU queue (slice 1.3
-        // upgrades to cross-process heartbeat polling).
-        const input = {
-            batchId: options.batch,
-            dispatchCount: 1,
-            recordPaths: [],
-            ...(timeoutMs !== undefined ? { timeoutMs } : {})
-        };
         try {
+            // Slice 2026-09-16-n1-await-reports: resolve the batch's records from the
+            // session's dispatch directory. `recordPaths` used to be hardcoded to
+            // `[]`, and `awaitBatch` short-circuits on an empty list
+            // (await-batch.ts:134) — so `await` reported zero results and exited 0
+            // for every batch, forever. A batch we cannot locate is now a failure,
+            // not a success with nothing in it.
+            const { readRecord } = await import('../../services/dispatch/dispatch-record-writer.js');
+            const scan = resolveBatchRecords({
+                projectRoot,
+                sessionId: sid,
+                batchId: options.batch,
+                readOne: readRecord
+            });
+            if (scan.recordPaths.length === 0) {
+                const unreadableNote = scan.unreadable.length > 0
+                    ? ` ${scan.unreadable.length} dispatch record(s) there could not be read, so they could not be matched to this batch: ${scan.unreadable.join(', ')}`
+                    : '';
+                printResult(io, fail('sub-agent.await', 'NO_DISPATCH_RECORDS', `No dispatch record with batchId=${options.batch} under ${scan.sessionDir}.${unreadableNote}`, {
+                    ok: false,
+                    batchId: options.batch,
+                    sessionDir: scan.sessionDir,
+                    unreadableRecords: scan.unreadable
+                }, [awaitErrorNextActions('NO_DISPATCH_RECORDS')]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            const input = {
+                batchId: options.batch,
+                dispatchCount: scan.recordPaths.length,
+                recordPaths: scan.recordPaths,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {})
+            };
             const results = await dispatcher.awaitBatch(input);
             const summary = summarizeBatchResults(results);
             printResult(io, ok('sub-agent.await', {
@@ -302,9 +323,19 @@ export function registerAwaitCommand(parent, io) {
                 batchId: options.batch,
                 ide: dispatcher.label,
                 results,
-                summary
-            }, [], [
-                'For trae / trae-cn / codex / cursor, results will report status=timeout with note=`awaitByLlm: <ide> 1.2 fallback`. The calling LLM holds the real await.'
+                summary,
+                unreadableRecords: scan.unreadable
+            }, scan.unreadable.length > 0
+                ? [`${scan.unreadable.length} unreadable dispatch record(s) in this session were skipped and are NOT part of the results: ${scan.unreadable.join(', ')}`]
+                : [], [
+                // Slice 2026-09-15-s9: corrected. This used to tell users that the
+                // four non-Claude IDEs would report `awaitByLlm: <ide> 1.2 fallback`,
+                // the slice-1.2 marker that slice 1.3 replaced with a real
+                // file-polling await. The text survived because nothing tested it —
+                // no adapter produces that note any more (asserted in
+                // sub-agent-dispatchers.test.ts), and the emitter that produced it,
+                // `awaitByLlmFallback`, has since been removed.
+                `Each non-claude-code IDE labels its own results (see the \`note\` field), so a timed-out slot is attributable to the adapter it came from.`
             ]), asJson);
         }
         catch (error) {
@@ -323,8 +354,70 @@ function awaitErrorNextActions(code) {
     if (code === 'IDE_NOT_SUPPORTED') {
         return 'Switch to claude-code, or rely on LLM-side await for non-claude-code IDEs in slice 1.3.';
     }
+    if (code === 'NO_DISPATCH_RECORDS') {
+        return 'Check --session-id / --project: records live under .peaks/_sub_agents/<sessionId>/. Use the batchId exactly as printed by the dispatch envelope.';
+    }
     return 'See error message; check that --batch matches the dispatch envelope and --timeout is a positive integer ms.';
 }
+/**
+ * Resolve a record's on-disk path through `realpathSync` so the value returned
+ * here matches the value `writeInitialDispatchRecord` produces — which itself
+ * passes through `assertSafeDispatchRecordPath` and ends up canonicalized. On
+ * macOS, `mkdtempSync(join(tmpdir(), prefix))` returns `/var/folders/...`
+ * while `process.cwd()` after `chdir` returns `/private/var/folders/...`;
+ * without this helper the test fixture's `queuedPath` (canonical) and the
+ * envelope's `finalized[].recordPath` (raw) never compare equal. Falls back
+ * to the lexical path when the file is missing (race between scan and write).
+ */
+function safeRecordPath(p) {
+    try {
+        return realpathSyncNative(p);
+    }
+    catch {
+        return p;
+    }
+}
+/**
+ * Slice 2026-09-16-n1-await-reports: which on-disk records belong to a batch.
+ *
+ * Reuses the conventions already in the repo instead of inventing a new one:
+ *   - records live at `.peaks/_sub_agents/<sid>/dispatch-<rid>-<ts>.json`
+ *     (`dispatchRecordPath`, src/services/security/safe-settings-path.ts);
+ *   - a record's batch is its own `batchId` field, written by
+ *     `writeInitialDispatchRecord`. The `--batch` branch of `finalize` (below)
+ *     and `findBatchRecords` in heartbeat-watch-command.ts resolve a batch the
+ *     same way: scan the session dir, filter `dispatch-*.json`, compare field.
+ *
+ * `unreadable` lists the `dispatch-*.json` candidates whose batch could NOT be
+ * determined. The caller must not fold them into "no such batch": a record it
+ * cannot read is not evidence that the batch is empty.
+ */
+function resolveBatchRecords(input) {
+    const sessionDir = resolve(input.projectRoot, '.peaks', '_sub_agents', input.sessionId);
+    const recordPaths = [];
+    const unreadable = [];
+    if (!existsSync(sessionDir))
+        return { sessionDir, recordPaths, unreadable };
+    for (const name of readdirSync(sessionDir)) {
+        // `active-dispatches.json` (the index) and `batch-<uuid>.counter.json` are
+        // not records; neither carries a `version`, so `readRecord` would reject
+        // them as "version mismatch". Same filter as the `--batch` branch below.
+        if (!name.startsWith('dispatch-') || !name.endsWith('.json'))
+            continue;
+        const recordPath = safeRecordPath(join(sessionDir, name));
+        let batchId;
+        try {
+            batchId = input.readOne(recordPath).batchId;
+        }
+        catch {
+            unreadable.push(recordPath);
+            continue;
+        }
+        if (batchId === input.batchId)
+            recordPaths.push(recordPath);
+    }
+    return { sessionDir, recordPaths, unreadable };
+}
 export function registerFinalizeCommand(parent, io) {
     addJsonOption(parent
         .command('finalize')
@@ -418,7 +511,7 @@ export function registerFinalizeCommand(parent, io) {
                             // `--batch` branch below has always used this same filter.
                             if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
-                            const p = path2.join(dir, f);
+                            const p = safeRecordPath(path2.join(dir, f));
                             const r = tryReadRecord(p);
                             if (r === null || r.requestId !== options.requestId)
                                 continue;
@@ -470,7 +563,7 @@ export function registerFinalizeCommand(parent, io) {
                         for (const f of fs2.readdirSync(dir)) {
                             if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
                                 continue;
-                            const p = path2.join(dir, f);
+                            const p = safeRecordPath(path2.join(dir, f));
                             const r = tryReadRecord(p);
                             if (r === null)
                                 continue;

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

@@ -161,7 +161,14 @@ export async function runWebOp(io, op, args, asJson) {
             return;
         }
         const info = await ensureDaemon(projectRoot, sessionId);
-        const response = await new WebDaemonClient(info).call(op, { ...opArgs, dispatchId: dispatchId(), projectRoot, sessionId }, OP_TIMEOUT_MS);
+        // The daemon reads `projectRoot` back from `daemon.json` — the record it
+        // itself wrote — and that round-trip is the only path that survives the
+        // macOS `/var` <-> `/private/var` symlink: the writer's prefix may not
+        // match `projectRoot` resolved from `process.cwd()` (the kernel resolves
+        // symlinks on `chdir`), and the integration test asserts on that exact
+        // round-tripped value.
+        const daemonProjectRoot = info.projectRoot;
+        const response = await new WebDaemonClient(info).call(op, { ...opArgs, dispatchId: dispatchId(), projectRoot: daemonProjectRoot, sessionId }, OP_TIMEOUT_MS);
         if (!response.ok || response.data === null) {
             const code = safeDaemonCode(response.code);
             // The daemon no longer downloads (R3), so "the browser is not installed"

package/dist/cli/commands/workflow-lifecycle-commands.d.ts

@@ -60,4 +60,10 @@ export interface WorkflowTerminalizeOptions {
     readonly requireConsumed?: boolean;
     readonly json?: boolean;
 }
+/**
+ * The literal that means "no session could be resolved". Kept as a named
+ * constant because three call sites now have to ASK whether resolution
+ * failed rather than consume the value as if it were an id.
+ */
+export declare const UNKNOWN_SESSION_ID = "unknown-sid";
 export declare function registerWorkflowLifecycleCommand(parent: Command, io: ProgramIO): void;

package/dist/cli/commands/workflow-lifecycle-commands.js

@@ -9,6 +9,8 @@
 import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 import { resolveCallerId } from '../../services/session/resolve-caller-id.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { initWorkflow, terminalizeWorkflow, } from '../../services/workflow/workflow-presence-lifecycle.js';
 import { readGraph, emptyGraph } from '../../services/workflow/workflow-graph-store.js';
 import { WORKFLOW_ID_REGEX, TERMINAL_REASONS } from '../../services/workflow/workflow-graph-types.js';
@@ -26,8 +28,62 @@ function deriveCallerId() {
 function deriveProjectRoot(options) {
     return options.project ?? process.cwd();
 }
+/**
+ * The literal that means "no session could be resolved". Kept as a named
+ * constant because three call sites now have to ASK whether resolution
+ * failed rather than consume the value as if it were an id.
+ */
+export const UNKNOWN_SESSION_ID = 'unknown-sid';
+/**
+ * Resolve the session id for every `workflow *` command.
+ *
+ * Tier order (matches the idiom every other command family in this CLI
+ * already uses — see `job-commands.ts:85`, `container-commands.ts:138`):
+ *
+ *   1. `--session-id <sid>`             — explicit wins
+ *   2. `PEAKS_SESSION_ID` env var       — scripted / sub-process callers
+ *   3. `getCurrentSessionId(projectRoot)` — this caller's OWN binding
+ *      (`callers/<callerId>.json`) falling back to the project-global
+ *      `.peaks/_runtime/session.json`, the same resolver `peaks session
+ *      info --active` and `peaks session checkpoint` use
+ *   4. `unknown-sid`                    — nothing is bound
+ *
+ * Tier 3 was MISSING until 2026-09-15 (S6), and its absence is the whole
+ * defect: `workflow init` resolved on tiers 1–2 only, so with no flag and no
+ * env var it wrote the graph into `.peaks/_runtime/unknown-sid/graphs/`
+ * regardless of what the binding file said. `peaks workflow node prepare`
+ * then ran under the CORRECT session dir and reported `PEAKS_GRAPH_NOT_FOUND`
+ * — the graph it was asking for had been written one bucket over. The bucket
+ * accumulated artifacts from at least 4 distinct caller ids between 2026-09-01
+ * and 2026-09-15, i.e. it had never worked for anyone.
+ *
+ * The same prior-art sweep (`.peaks/memory/archived/2026-06-26-unknown-sid-root-cause.md`)
+ * converted six inline `?? 'unknown-sid'` sites to this 4-tier chain;
+ * `workflow-lifecycle-commands.ts` was missed. This is that site.
+ *
+ * The project root passed to tier 3 goes through the same `findProjectRoot`
+ * walk `session info` uses, so a command run from a SUBDIRECTORY of the
+ * project resolves the project's binding instead of `cwd`'s (which has none).
+ */
 function deriveSessionId(options) {
-    return options.sessionId ?? process.env.PEAKS_SESSION_ID ?? 'unknown-sid';
+    if (typeof options.sessionId === 'string' && options.sessionId.length > 0)
+        return options.sessionId;
+    const fromEnv = process.env.PEAKS_SESSION_ID;
+    if (typeof fromEnv === 'string' && fromEnv.length > 0)
+        return fromEnv;
+    return getCurrentSessionId(findProjectRoot(options.project ?? process.cwd()) ?? (options.project ?? process.cwd())) ?? UNKNOWN_SESSION_ID;
+}
+/**
+ * Tier 3 resolving to `unknown-sid` means NO session is bound at all. A
+ * `workflow` subcommand that WRITES must fail loudly on that rather than
+ * create a bucket named after a failure — `graph list` already does (see its
+ * `PEAKS_SESSION_NOT_BOUND` guard below); `init` did not.
+ */
+function buildSessionNotBoundEnvelope(sessionId, projectRoot) {
+    return fail('workflow.init', 'PEAKS_SESSION_NOT_BOUND', `No peaks session is bound for '${projectRoot}' (derived session id '${sessionId}'): --session-id, PEAKS_SESSION_ID and the project binding are all absent.`, { workflowId: null }, [
+        'Run `peaks workspace init --project <p>` to bind a session, then re-run.',
+        'Or pass `--session-id <sid>` explicitly.',
+    ]);
 }
 export function registerWorkflowLifecycleCommand(parent, io) {
     // Reuse the existing `workflow` parent (created by `registerWorkflowCommands`)
@@ -46,8 +102,13 @@ export function registerWorkflowLifecycleCommand(parent, io) {
         const asJson = options.json === true;
         try {
             const callerId = deriveCallerId();
-            const sessionId = deriveSessionId(options);
             const projectRoot = deriveProjectRoot(options);
+            const sessionId = deriveSessionId(options);
+            if (sessionId === UNKNOWN_SESSION_ID) {
+                printResult(io, buildSessionNotBoundEnvelope(sessionId, projectRoot), asJson);
+                process.exitCode = 1;
+                return;
+            }
             const workflowId = options.workflowId ?? `wf-${Date.now().toString(36)}`;
             if (!WORKFLOW_ID_REGEX.test(workflowId)) {
                 throw new Error(`workflowId shape invalid: ${workflowId}`);
@@ -120,7 +181,7 @@ export function registerWorkflowLifecycleCommand(parent, io) {
         const asJson = options.json === true;
         try {
             const sessionId = deriveSessionId(options);
-            if (!sessionId || sessionId === 'unknown-sid') {
+            if (sessionId === UNKNOWN_SESSION_ID) {
                 throw new Error('PEAKS_SESSION_NOT_BOUND: no session id');
             }
             const result = { envelopeVersion: '4.0.8', sessionId, graphs: [] };

package/dist/services/adapter/adapter.d.ts

@@ -1,3 +1,33 @@
+/**
+ * ⚠ DEAD CODE — NOT THE LIVE VENDOR LAYER, AND NOT THE LIVE IDE LAYER.
+ *
+ * Three things in this repo are named `<Vendor>Adapter`, and only one of
+ * them is live. Read this table before importing anything from here:
+ *
+ *   1. `src/services/runtime/vendors/<vendor>.ts`
+ *      → `class CodexAdapter implements VendorAdapter` (runtime detect +
+ *        compact). LIVE — wired by `RuntimeService`'s built-in list. This is
+ *        the one a reader looking for "the codex adapter" wants.
+ *   2. `packages/peaks-loop-internal-runtime/src/vendor/<vendor>-adapter.ts`
+ *      → a second `CodexAdapter`, different surface (binary / headlessArgs /
+ *        parseStatusLine / detectInstalled) for the dispatched-sub-agent
+ *        runtime. LIVE — exported by that package's public index.
+ *   3. THIS FILE'S SIBLINGS — `claude-adapter.ts` / `codex-adapter.ts` /
+ *        `copilot-adapter.ts` + `auto-adapter.ts`.
+ *      → **UNREFERENCED.** Zero importers in `src/`, `tests/`, `packages/`
+ *        or `scripts/`. Every method throws `ADAPTER_NOT_IMPLEMENTED`; the
+ *        one exception, `detect()` on the codex/copilot pair, is a hardcoded
+ *        `return false`. `peaks skill adapter list` (the only CLI surface
+ *        that names these) does not read them — it returns a literal array.
+ *
+ * The three layers diverged from a single planned skill-adapter surface and
+ * were never reconciled. These placeholder files are kept because they mark
+ * intent for unimplemented work; they are NOT kept because anything uses
+ * them. If you are here to implement them, the decision you actually need is
+ * which of layers 1–3 survives — see
+ * `tests/unit/runtime/vendor-adapter-layer.test.ts`, which pins which layer
+ * is live and fails the moment that stops being true.
+ */
 export interface AdapterSegment {
     name: string;
     skillMd: string;

package/dist/services/adapter/auto-adapter.d.ts

@@ -1,3 +1,16 @@
+/**
+ * ⚠ DEAD CODE — zero importers in `src/`, `tests/`, `packages/`, `scripts/`.
+ * See the block comment on `src/services/adapter/adapter.ts`.
+ *
+ * `detectAndPick()` picks the first adapter whose `detect()` returns true.
+ * It cannot pick anything today: its only candidate implementations are its
+ * three dead siblings, and the codex/copilot pair hardcode `detect()` to
+ * `false` while the claude one hardcodes `true` — so the "pick" is a
+ * constant that never varies with the environment. It is not wired to
+ * `peaks skill adapter set-active` either; that CLI verb
+ * (`src/cli/commands/adapter-commands.ts`) echoes back the name it was given
+ * and reads no adapter file.
+ */
 import { Adapter } from "./adapter.js";
 type Detectable = Pick<Adapter, "name" | "detect">;
 export declare class AutoAdapter {

package/dist/services/adapter/claude-adapter.js

@@ -1,3 +1,15 @@
+/**
+ * ⚠ DEAD CODE — not a live adapter. See the block comment on
+ * `src/services/adapter/adapter.ts` for the three same-named layers.
+ *
+ * This is the only file in the cluster with a real implementation, which is
+ * what makes it the most misleading one: it writes a real
+ * `~/.claude/skills/peaks-bee-<name>.peaks-generated/SKILL.md` scratch dir if
+ * you call it. Nothing calls it — zero importers in `src/`, `tests/`,
+ * `packages/` or `scripts/`. The live Claude Code knowledge lives in
+ * `src/services/ide/adapters/claude-code-adapter.ts` (IDE surface) and
+ * `src/services/runtime/vendors/claude-code.ts` (runtime compact).
+ */
 import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 export class ClaudeAdapter {

package/dist/services/adapter/codex-adapter.d.ts

@@ -1,3 +1,15 @@
+/**
+ * ⚠ DEAD CODE — not the live `CodexAdapter`. See the block comment on
+ * `src/services/adapter/adapter.ts` for the three same-named layers, and
+ * `tests/unit/runtime/vendor-adapter-layer.test.ts` for the guard.
+ *
+ * The class below has zero importers anywhere in this repo. The live codex
+ * adapter is `src/services/runtime/vendors/codex.ts` (runtime detect +
+ * compact, wired into `RuntimeService`) and
+ * `packages/peaks-loop-internal-runtime/src/vendor/codex-adapter.ts` (the
+ * dispatched-sub-agent runtime). `detect()` here returns a hardcoded
+ * `false`; every other method throws `ADAPTER_NOT_IMPLEMENTED`.
+ */
 import { Adapter } from "./adapter.js";
 export declare class CodexAdapter implements Pick<Adapter, "name"> {
     private readonly _o;

package/dist/services/adapter/codex-adapter.js

@@ -1,3 +1,15 @@
+/**
+ * ⚠ DEAD CODE — not the live `CodexAdapter`. See the block comment on
+ * `src/services/adapter/adapter.ts` for the three same-named layers, and
+ * `tests/unit/runtime/vendor-adapter-layer.test.ts` for the guard.
+ *
+ * The class below has zero importers anywhere in this repo. The live codex
+ * adapter is `src/services/runtime/vendors/codex.ts` (runtime detect +
+ * compact, wired into `RuntimeService`) and
+ * `packages/peaks-loop-internal-runtime/src/vendor/codex-adapter.ts` (the
+ * dispatched-sub-agent runtime). `detect()` here returns a hardcoded
+ * `false`; every other method throws `ADAPTER_NOT_IMPLEMENTED`.
+ */
 import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
 export class CodexAdapter {
     _o;

package/dist/services/adapter/copilot-adapter.d.ts

@@ -1,3 +1,15 @@
+/**
+ * ⚠ DEAD CODE — not the live `CopilotAdapter`. See the block comment on
+ * `src/services/adapter/adapter.ts` for the three same-named layers, and
+ * `tests/unit/runtime/vendor-adapter-layer.test.ts` for the guard.
+ *
+ * The class below has zero importers anywhere in this repo. The live copilot
+ * adapter is `src/services/runtime/vendors/copilot.ts` (runtime detect +
+ * compact, wired into `RuntimeService`) and
+ * `packages/peaks-loop-internal-runtime/src/vendor/copilot-adapter.ts` (the
+ * dispatched-sub-agent runtime). `detect()` here returns a hardcoded
+ * `false`; every other method throws `ADAPTER_NOT_IMPLEMENTED`.
+ */
 import { Adapter } from "./adapter.js";
 export declare class CopilotAdapter implements Pick<Adapter, "name"> {
     private readonly _o;

package/dist/services/adapter/copilot-adapter.js

@@ -1,3 +1,15 @@
+/**
+ * ⚠ DEAD CODE — not the live `CopilotAdapter`. See the block comment on
+ * `src/services/adapter/adapter.ts` for the three same-named layers, and
+ * `tests/unit/runtime/vendor-adapter-layer.test.ts` for the guard.
+ *
+ * The class below has zero importers anywhere in this repo. The live copilot
+ * adapter is `src/services/runtime/vendors/copilot.ts` (runtime detect +
+ * compact, wired into `RuntimeService`) and
+ * `packages/peaks-loop-internal-runtime/src/vendor/copilot-adapter.ts` (the
+ * dispatched-sub-agent runtime). `detect()` here returns a hardcoded
+ * `false`; every other method throws `ADAPTER_NOT_IMPLEMENTED`.
+ */
 import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
 export class CopilotAdapter {
     _o;

package/dist/services/audit/backing-detector.d.ts

@@ -2,23 +2,41 @@
  * Backing detector — classifies each red line as `cli-backed`, `partial`,
  * or `prose-only`. The classifier already sets the backing for catalog hits
  * (cli-backed when an enforcer file path is present). This module exists to
- * handle the post-classification nuance: heuristics for the "partial" tier
- * (a gate exists but the LLM can bypass it) and verification that the
- * enforcer file actually exists on disk.
+ * handle the post-classification nuances: heuristics for the "partial" tier
+ * (a gate exists but the LLM can bypass it), verification that the enforcer
+ * file exists on disk, and — since A9 of the 2026-09-15 diagnosis —
+ * verification that the enforcer is actually reachable from a call site.
+ *
+ * `cli-backed` means "a CLI surface runs this rule". A file that exists but
+ * that nothing imports runs nothing, so it is `prose-only` with the same
+ * weight as an unwritten rule. Callers pass the live set from
+ * `enforcer-liveness.ts`; `null` means "liveness undecidable for this
+ * project" (no `src/` tree), in which case the existing file is trusted.
  */
 import type { RedLineEntry } from './types.js';
+/**
+ * `liveEnforcers` is the set of enforcerRefs with a call site (see
+ * `enforcer-liveness.ts`), or `null` when the project has no `src/` tree to
+ * scan and liveness therefore cannot be decided.
+ */
+export type LiveEnforcerSet = ReadonlySet<string> | null;
 export interface BackingResult {
     readonly entry: RedLineEntry;
     readonly enforcerExists: boolean;
+    /** True when the enforcer file exists but no call site imports it. */
+    readonly enforcerDead: boolean;
 }
 /**
  * Re-classify a single RedLineEntry. Returns a new entry with the
- * `backing` field updated and `enforcerRef` possibly nulled if the
- * referenced file does not exist on disk.
+ * `backing` field updated; `enforcerRef` is preserved even when the
+ * backing is downgraded, because the dead reference is the triage
+ * information the report needs.
  */
-export declare function classifyBacking(entry: RedLineEntry, projectRoot: string): BackingResult;
+export declare function classifyBacking(entry: RedLineEntry, projectRoot: string, liveEnforcers: LiveEnforcerSet): BackingResult;
 export interface BackingBatchResult {
     readonly entries: readonly RedLineEntry[];
     readonly warnings: readonly string[];
+    /** Sorted, deduplicated enforcerRefs downgraded for having no call site. */
+    readonly deadEnforcers: readonly string[];
 }
-export declare function classifyBackingBatch(entries: readonly RedLineEntry[], projectRoot: string): BackingBatchResult;
+export declare function classifyBackingBatch(entries: readonly RedLineEntry[], projectRoot: string, liveEnforcers: LiveEnforcerSet): BackingBatchResult;