peaks-loop 4.0.35 → 4.0.37

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

@@ -0,0 +1,321 @@
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { stopDaemon } from '../../services/web/daemon-supervisor.js';
+import { degradedEnvelope } from '../../services/web/web-fallback.js';
+import { INSTALL_SIZE_WARNING, installChromium, isWebDisabled, probeBrowserInstalled } from '../../services/web/web-install-service.js';
+import { buildStatusReport } from '../../services/web/web-status-report.js';
+import { cappedEcho, loginStorageStatePath, resolveProfileName, runHeadedLogin } from '../../services/web/web-login-profile.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerWebLifecycleCommands(web, io) {
+    addJsonOption(web
+        .command('status')
+        .description('Report this session\'s web daemon instances (live / orphaned / stale). Works with no ' +
+        'daemon running and never starts one.')).action(async (options) => {
+        await runWebStatus(io, options.json === true);
+    });
+    addJsonOption(web
+        .command('stop')
+        .description("Stop this session's web daemon and close its browser. Scoped to this project root and " +
+        'session; another worktree is untouched, and a process that cannot be proven to be this ' +
+        "session's daemon is left running rather than signalled.")).action(async (options) => {
+        await runWebStop(io, options.json === true);
+    });
+    addJsonOption(web
+        .command('install')
+        .description('Download the pinned chromium for `peaks web` (one time, ~700 MB on disk). Needed only ' +
+        'before the first browser op — a read-only verb never downloads. Refuses while ' +
+        'PEAKS_WEB_DISABLED=1.')
+        .option('--force', "reinstall even if the browser is already present (Playwright's own recovery path)")).action(async (options) => {
+        await runWebInstall(io, options.json === true, options.force === true);
+    });
+    addJsonOption(web
+        .command('login')
+        .description('Open a HEADED browser so the user can log in themselves, then persist that session to ' +
+        '~/.peaks/web-profiles/<name>/storageState.json. Run it only when the user asks for a ' +
+        'persistent login: it writes live session cookies to disk. --profile is required, and ' +
+        'without it nothing is persisted.')
+        .option('--profile <name>', 'the login profile to persist (required; [a-z0-9._-], 1-64 chars — upper case folds to lower)')).action(async (options) => {
+        await runWebLogin(io, options.json === true, options.profile);
+    });
+}
+/** Resolve this project's session, or report `NO_SESSION` exactly once. */
+function resolveSession() {
+    const projectRoot = resolveCanonicalProjectRoot(process.cwd());
+    const sessionId = getCurrentSessionId(projectRoot);
+    return sessionId === null ? null : { projectRoot, sessionId };
+}
+/** The shared `NO_SESSION` envelope for both lifecycle verbs. */
+function noSession(command) {
+    return fail(command, 'NO_SESSION', 'No peaks session is bound to this project root', {}, [
+        'Bind a session first (the LLM runs `peaks workspace init` on your behalf)'
+    ]);
+}
+/** Everything `stop` did NOT clean, said out loud rather than left implicit. */
+function stopWarnings(result) {
+    const warnings = [];
+    const stuck = result.pids.length - result.stopped;
+    if (stuck > 0) {
+        warnings.push(`${String(stuck)} daemon process(es) did not exit after the stop request; they are recorded, ` +
+            'so a later `peaks web stop` can try again');
+    }
+    if (result.orphanedPids.length > 0) {
+        warnings.push(`${String(result.orphanedPids.length)} daemon instance(s) are alive but could not be proven ` +
+            'to be this session\'s daemon (no authenticated identity); the processes were left running, ' +
+            'because a pid that cannot be proven is never signalled, and their records are kept so ' +
+            '`peaks web status` and a later `stop` still see them');
+    }
+    return warnings;
+}
+export async function runWebStatus(io, asJson) {
+    const command = 'peaks.web.status';
+    try {
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, noSession(command), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok(command, await buildStatusReport(session.projectRoot, session.sessionId)), asJson);
+    }
+    catch (error) {
+        printResult(io, fail(command, 'WEB_STATUS_FAILED', `peaks web status failed: ${getErrorMessage(error)}`, {}, []), asJson);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Stop the daemon and clear its records. `stopped` counts the daemons whose
+ * process is confirmed GONE by return — not merely the ones we signalled — so a
+ * caller that checks the process table right after this returns is not racing
+ * the teardown (AC6).
+ */
+export async function runWebStop(io, asJson) {
+    const command = 'peaks.web.stop';
+    try {
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, noSession(command), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const result = await stopDaemon(session.projectRoot, session.sessionId);
+        printResult(io, ok(command, {
+            stopped: result.stopped,
+            pids: [...result.pids],
+            orphanedPids: [...result.orphanedPids]
+        }, stopWarnings(result)), asJson);
+    }
+    catch (error) {
+        printResult(io, fail(command, 'WEB_STOP_FAILED', `peaks web stop failed: ${getErrorMessage(error)}`, {}, []), asJson);
+        process.exitCode = 1;
+    }
+}
+/** The MCP fallback for `install`, named so the LLM can act on it (decision C3). */
+const WEB_DISABLED_ACTIONS = [
+    'Unset PEAKS_WEB_DISABLED to install locally',
+    'Or call mcp__playwright__browser_install instead'
+];
+/** The same fallback, minus the gate, for a download that failed on its own. */
+const INSTALL_FAILED_ACTIONS = [
+    'Retry `peaks web install`, or `peaks web install --force` after a partial download',
+    'Or call mcp__playwright__browser_install instead'
+];
+/**
+ * `peaks web install` — the explicit form of the lazy download, plus R6's
+ * recovery path (`--force`).
+ *
+ * The gate is step 1 of the ordered gate (tech-doc §5.1): checked BEFORE the
+ * session lookup, before any lock and before anything that could touch the
+ * browser cache, so this verb cannot download under `PEAKS_WEB_DISABLED=1` even
+ * if every later step is broken (C2's matrix).
+ */
+export async function runWebInstall(io, asJson, force) {
+    const command = 'peaks.web.install';
+    try {
+        if (isWebDisabled(process.env)) {
+            printResult(io, fail(command, 'WEB_DISABLED', '`peaks web install` will not download anything while PEAKS_WEB_DISABLED=1', {}, WEB_DISABLED_ACTIONS), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, noSession(command), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // R6's other half: a missing executable is the only reason to download, so
+        // an already-complete install is reported without spawning anything. The
+        // shortcut still names `--force`, because it is the only escape if a browser
+        // op keeps failing against a probe that says otherwise (R7).
+        const before = await probeBrowserInstalled();
+        if (before.installed && !force) {
+            printResult(io, ok(command, {
+                installed: true,
+                downloaded: false,
+                version: before.version,
+                executablePath: before.executablePath
+            }, [], ['If browser ops still fail, re-run `peaks web install --force`']), asJson);
+            return;
+        }
+        // R2: name the size on the human channel BEFORE the blocking download —
+        // this is the only point at which "before" is still available.
+        io.stderr(`warning: ${INSTALL_SIZE_WARNING}`);
+        const outcome = await installChromium({ force });
+        if (!outcome.ok) {
+            // R2: a failed download is a structured tier-3 envelope, never a stack.
+            printResult(io, degradedEnvelope('install', `${outcome.code}: ${outcome.message}`), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // `after.installed` is CONSULTED, not merely carried (R7). An installer
+        // that exits 0 without landing the browser — a proxy that filters the CDN, a
+        // pinned npx resolving into a different cache root, a partial install — used
+        // to report `ok: true, downloaded: true, installed: false` with exit 0 and
+        // nothing to do next.
+        const after = await probeBrowserInstalled();
+        if (!after.installed) {
+            printResult(io, degradedEnvelope('install', 'WEB_INSTALL_INCOMPLETE: `playwright install chromium` exited 0 but the browser it ' +
+                'names is still missing'), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok(command, {
+            installed: true,
+            downloaded: true,
+            version: after.version,
+            executablePath: after.executablePath
+        }, [...outcome.warnings]), asJson);
+    }
+    catch (error) {
+        printResult(io, fail(command, 'WEB_INSTALL_FAILED', `peaks web install failed: ${getErrorMessage(error)}`, {}, INSTALL_FAILED_ACTIONS), asJson);
+        process.exitCode = 1;
+    }
+}
+/** What a caller can actually do after a refusal or an unclosed login. */
+const LOGIN_NEXT_ACTIONS = [
+    'Re-run `peaks web login --profile <name>` when the user is ready to log in',
+    'Close the headed browser window when the login is finished — closing it is what saves the session'
+];
+/**
+ * The fold, said out loud on the one path that CANNOT fold (S4 repair, code F5 /
+ * security S5).
+ *
+ * The gate is statement #1 (tech-doc §5.1), so on this path the name was never
+ * validated and never folded — which is exactly why this refusal must not look
+ * like it disagrees with a live run about the profile. It reports what happened
+ * (nothing was folded, this is what was typed) rather than implying a canonical
+ * name was used, and it claims nothing about whether the name would be accepted.
+ * The echo is capped by the same helper the guard uses.
+ */
+function gateFoldNotice(rawProfile) {
+    if (rawProfile === undefined || rawProfile === rawProfile.toLowerCase()) {
+        return [];
+    }
+    return [
+        `--profile ${JSON.stringify(cappedEcho(rawProfile))} was NOT folded: PEAKS_WEB_DISABLED is ` +
+            'checked before the profile name, so this refusal echoes what was typed, not a canonical ' +
+            'profile. A run that gets past the gate lower-cases the name first.'
+    ];
+}
+/**
+ * `peaks web login --profile <name>` — the only path that persists a login
+ * (design §2/§5, PRD R7).
+ *
+ * `--profile` is enforced HERE rather than with commander's `requiredOption`,
+ * because `requiredOption` refuses before this handler runs — and then the
+ * `PEAKS_WEB_DISABLED` gate would no longer be statement #1 (tech-doc §5.1,
+ * AC5). A profile-less login refuses without touching the profile root: no
+ * directory, no storage state, no browser.
+ */
+export async function runWebLogin(io, asJson, rawProfile) {
+    const command = 'peaks.web.login';
+    // Declared out here so the CATCH can report it too (S4 repair, security S5 /
+    // code F3): a launch failure happens AFTER the name was resolved, so a run
+    // that dies on `WEB_LAUNCH_FAILED` knows the canonical name just as well as
+    // one that succeeds, and must not be the one path where the fold is silent.
+    let foldWarnings = [];
+    try {
+        if (isWebDisabled(process.env)) {
+            const gateEnvelope = degradedEnvelope('login', 'PEAKS_WEB_DISABLED=1', 3, rawProfile === undefined ? {} : { profile: cappedEcho(rawProfile) });
+            printResult(io, { ...gateEnvelope, warnings: [...gateEnvelope.warnings, ...gateFoldNotice(rawProfile)] }, asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (rawProfile === undefined || rawProfile === '') {
+            printResult(io, fail(command, 'WEB_PROFILE_REQUIRED', '`peaks web login` requires --profile <name>: it is the only verb that persists a login, ' +
+                'and there is no default profile — without a name nothing is written', {}, LOGIN_NEXT_ACTIONS), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        let profile;
+        try {
+            profile = resolveProfileName(rawProfile);
+        }
+        catch (error) {
+            // The helper's own message already begins with the code, and `fail()`
+            // puts the code in front of the message again — strip it, so human output
+            // does not read `WEB_PROFILE_NAME_INVALID: WEB_PROFILE_NAME_INVALID: …`.
+            const detail = getErrorMessage(error).replace(/^WEB_PROFILE_NAME_INVALID:\s*/, '');
+            printResult(io, fail(command, 'WEB_PROFILE_NAME_INVALID', detail, {}, LOGIN_NEXT_ACTIONS), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // The fold (see `resolveProfileName`) is never silent: `--profile Work` and
+        // `--profile work` are one profile, and the caller is told which name was
+        // used. The two sides are deliberately not the same value — the left is what
+        // the caller TYPED (echoed through `cappedEcho`, since it is still caller
+        // input), the right is the canonical name the run uses from here on.
+        foldWarnings =
+            rawProfile === profile
+                ? []
+                : [`--profile ${JSON.stringify(cappedEcho(rawProfile))} resolved to the profile "${profile}"`];
+        const outcome = await runHeadedLogin({
+            profile,
+            announce: () => {
+                io.stderr([
+                    `peaks web login: a headed browser is open for profile "${profile}" — log in there yourself.`,
+                    'Close the browser window when you are done: that is what saves the session, to ' +
+                        `${loginStorageStatePath(profile)}.`,
+                    'The session is captured while the window is open, so the saved state can be up to a ' +
+                        'second older than what you see — finish logging in before you close it.'
+                ].join('\n'));
+            }
+        });
+        if (!outcome.ok) {
+            // S1's F1. This is the ONLY path on which the runner returns `ok: false`
+            // AND a warning (a login whose context never opened and whose headed
+            // browser then refused to close — a browser nothing can then stop,
+            // because `stop` is daemon-scoped). `fail()` hard-codes `warnings: []`, so
+            // the warning is spread back over it, the shape `degradedEnvelope` uses.
+            printResult(io, {
+                ...fail(command, outcome.code, outcome.message, {}, LOGIN_NEXT_ACTIONS),
+                warnings: [...foldWarnings, ...outcome.warnings]
+            }, asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // Counts, never the values: the file holds live session cookies and this
+        // envelope reaches a terminal (and a transcript).
+        const envelope = ok(command, {
+            profile: outcome.profile,
+            storageStatePath: outcome.storageStatePath,
+            bytes: outcome.bytes,
+            cookies: outcome.cookies,
+            origins: outcome.origins
+        }, [...foldWarnings, ...outcome.warnings]);
+        // R5: a capture that was written but could not be read back is `ok` — the
+        // file did land, so it is not a failure — but it is not a clean success
+        // either. The code is what an ok-only consumer cannot miss.
+        printResult(io, outcome.code === '' ? envelope : { ...envelope, code: outcome.code }, asJson);
+    }
+    catch (error) {
+        printResult(io, {
+            ...fail(command, 'WEB_LOGIN_FAILED', `peaks web login failed: ${getErrorMessage(error)}`, {}, LOGIN_NEXT_ACTIONS),
+            // A run that reached `resolveProfileName` knows the canonical name, so a
+            // failure before the browser was even up reports the fold like every
+            // other path (S4 repair, code F5 / security S5).
+            warnings: foldWarnings
+        }, asJson);
+        process.exitCode = 1;
+    }
+}

package/dist/services/best-practice/scan-orchestrator.d.ts

@@ -12,6 +12,14 @@
  * the orchestrator's source-priority logic is testable end-to-end.
  * Real MCP wiring is a future slice — the stubs are clearly marked.
  *
+ * Because a stub result is indistinguishable from a real one by shape,
+ * every result carries `synthetic`: true when the fragments came from a
+ * built-in stub rather than a caller-injected lookup (`context7Lookup` /
+ * `webSearchLookup`). Callers MUST NOT present a synthetic result as a
+ * scan result — `source` alone says which transport answered, not whether
+ * anything real was consulted. The stub seam stays injectable so the real
+ * wiring (and its tests) can replace it without touching this contract.
+ *
  * The orchestrator emits structured log lines via the injected `io`
  * (stdout for progress, stderr for warnings) so a CLI caller can see
  * which fallback path was taken.
@@ -28,6 +36,12 @@ export type ScanResult = {
     readonly fragments: readonly DocFragment[];
     readonly source: ScanSource;
     readonly elapsedMs: number;
+    /**
+     * `true` when the fragments came from the built-in stub lookups instead
+     * of a real documentation lookup. A synthetic result is not a scan
+     * result: it must never be rendered as one or gated on.
+     */
+    readonly synthetic: boolean;
 };
 export type ScanOptions = {
     readonly intent: string;
@@ -35,5 +49,13 @@ export type ScanOptions = {
     readonly projectRoot: string;
     readonly io: ProgramIO;
     readonly context7TimeoutMs?: number;
+    /** Test / real-wiring seam: replaces the priority-1 Context7 stub. */
+    readonly context7Lookup?: LookupFn;
+    /** Test / real-wiring seam: replaces the priority-2 WebSearch stub. */
+    readonly webSearchLookup?: LookupFn;
 };
+export type LookupFn = (intent: string, language: string) => Promise<{
+    readonly ok: boolean;
+    readonly results: readonly DocFragment[];
+}>;
 export declare function scanBestPractice(opts: ScanOptions): Promise<ScanResult>;

package/dist/services/best-practice/scan-orchestrator.js

@@ -35,11 +35,17 @@ const defaultWebSearchLookup = async (intent, language) => {
 export async function scanBestPractice(opts) {
     const timeoutMs = opts.context7TimeoutMs ?? DEFAULT_CONTEXT7_TIMEOUT_MS;
     const startedAt = Date.now();
+    const context7Lookup = opts.context7Lookup ?? defaultContext7Lookup;
+    const webSearchLookup = opts.webSearchLookup ?? defaultWebSearchLookup;
+    // A branch is synthetic when the lookup that answered it is a stub. The
+    // fallback branch counts as synthetic if ANY stub took part in the chain.
+    const context7Stub = opts.context7Lookup === undefined;
+    const webSearchStub = opts.webSearchLookup === undefined;
     opts.io.stdout(`[scan-orchestrator] querying context7 for "${opts.intent}" (${opts.language})`);
     let context7Outcome = null;
     let context7Error = null;
     try {
-        const ctxPromise = defaultContext7Lookup(opts.intent, opts.language);
+        const ctxPromise = context7Lookup(opts.intent, opts.language);
         const ctxTimer = new Promise((_, reject) => {
             setTimeout(() => reject(new Error(`context7 timeout after ${timeoutMs}ms`)), timeoutMs).unref();
         });
@@ -54,14 +60,15 @@ export async function scanBestPractice(opts) {
             results: context7Outcome.results,
             fragments: context7Outcome.results,
             source: 'context7',
-            elapsedMs: Date.now() - startedAt
+            elapsedMs: Date.now() - startedAt,
+            synthetic: context7Stub
         };
     }
     opts.io.stdout(`[scan-orchestrator] falling back to websearch for "${opts.intent}" (${opts.language})`);
     let webOutcome = null;
     let webError = null;
     try {
-        webOutcome = await defaultWebSearchLookup(opts.intent, opts.language);
+        webOutcome = await webSearchLookup(opts.intent, opts.language);
     }
     catch (err) {
         webError = err instanceof Error ? err.message : String(err);
@@ -72,7 +79,8 @@ export async function scanBestPractice(opts) {
             results: webOutcome.results,
             fragments: webOutcome.results,
             source: 'websearch',
-            elapsedMs: Date.now() - startedAt
+            elapsedMs: Date.now() - startedAt,
+            synthetic: webSearchStub
         };
     }
     opts.io.stderr('[scan-orchestrator] both sources empty; returning empty fallback');
@@ -80,6 +88,7 @@ export async function scanBestPractice(opts) {
         results: [],
         fragments: [],
         source: 'fallback',
-        elapsedMs: Date.now() - startedAt
+        elapsedMs: Date.now() - startedAt,
+        synthetic: context7Stub || webSearchStub
     };
 }

package/dist/services/code/orchestrator-can-do.js

@@ -35,7 +35,28 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
+// 2026-09-10 D1: both probes used to spawn a bare `peaks`. On Windows that name
+// resolves to a `.cmd` shim, which `execFile` cannot run: it does not apply
+// PATHEXT, and Node >= 20 refuses to spawn `.cmd`/`.bat` at all without
+// `shell: true` (CVE-2024-27980). So Q2 reported "sub-agent dispatch
+// unavailable" and Q4 reported ratio 0 for every slice-spec on Windows —
+// phantom blockers produced by the spawn, not by the CLI. Running this tree's
+// own CLI entry through `process.execPath` needs no shell and no shim.
+import { cliEntryPath, interpreterArgs } from '../web/daemon-supervisor.js';
 const execFileAsync = promisify(execFile);
+/** Sentinel: no explicit binary was injected, so resolve this tree's own CLI. */
+const DEFAULT_PEAKS_BIN = 'peaks';
+/**
+ * Spawn argv for the peaks CLI. An explicitly injected `peaksBin` (the
+ * `--peaks-bin` test seam) is spawned verbatim; the default sentinel resolves
+ * to this tree's own CLI entry, interpreted by the running Node.
+ */
+function peaksSpawn(peaksBin) {
+    if (peaksBin !== DEFAULT_PEAKS_BIN) {
+        return { command: peaksBin, args: [] };
+    }
+    return { command: process.execPath, args: interpreterArgs(cliEntryPath()) };
+}
 /** Slice 2026-08-05-orchestrator-can-do-probe: red-line threshold. */
 export const ORCHESTRATOR_REDLINE_RATIO = 0.95;
 /** Slice 2026-08-05-orchestrator-can-do-probe: pre-compact threshold. */
@@ -126,9 +147,10 @@ export function detectRequiresUserDecision(sliceSpec) {
  * true when the subprocess exits 0. Resolves to false on spawn
  * failure or non-zero exit.
  */
-export async function probeSubAgentAvailable(projectRoot, peaksBin = 'peaks') {
+export async function probeSubAgentAvailable(projectRoot, peaksBin = DEFAULT_PEAKS_BIN) {
     try {
-        await execFileAsync(peaksBin, ['sub-agent', 'dispatch', '--role', 'rd', '--help'], {
+        const { command, args } = peaksSpawn(peaksBin);
+        await execFileAsync(command, [...args, 'sub-agent', 'dispatch', '--role', 'rd', '--help'], {
             cwd: projectRoot,
             timeout: 5000,
         });
@@ -143,9 +165,10 @@ export async function probeSubAgentAvailable(projectRoot, peaksBin = 'peaks') {
  * field. Falls back to {ratio: 0, source: 'unavailable'} when the
  * subprocess fails or returns malformed JSON.
  */
-export async function probeContextRatio(projectRoot, peaksBin = 'peaks') {
+export async function probeContextRatio(projectRoot, peaksBin = DEFAULT_PEAKS_BIN) {
     try {
-        const { stdout } = await execFileAsync(peaksBin, ['code', 'context-now', '--project', projectRoot, '--json'], {
+        const { command, args } = peaksSpawn(peaksBin);
+        const { stdout } = await execFileAsync(command, [...args, 'code', 'context-now', '--project', projectRoot, '--json'], {
             cwd: projectRoot,
             timeout: 10000,
         });

package/dist/services/context/build-dispatch-system-prompt.d.ts

@@ -68,6 +68,22 @@ export interface DispatchPromptInput {
      *   and before the memory/task content.
      */
     freshContextBlock?: string | null;
+    /**
+     * Slice 2026-09-10-dispatch-token-and-swarm §4: session capsule
+     * published by the orchestrator through `peaks sub-agent share`.
+     *
+     * - `undefined` / `null` → no capsule pointer, no precedence line
+     *   (byte-identical legacy prompt).
+     * - `{ batchId, key, bytes }` → a `shared-read` pointer plus the
+     *   mandatory precedence line: the capsule is ADVISORY BACKGROUND only
+     *   and the task spec wins on conflict. Nothing the sub-agent must act
+     *   on may live only in the capsule.
+     */
+    capsule?: {
+        readonly batchId: string;
+        readonly key: string;
+        readonly bytes: number;
+    } | null;
 }
 /**
  * Slice 2026-07-29-worktree-l1: Layer 1 of the 3-layer worktree governance
@@ -91,7 +107,7 @@ export interface DispatchPromptInput {
  * fallback path is `peaks worktree auth grant --rid <id> --reason <text>
  * --ttl <5m>` (already shipped). Update the prose once `spawn` lands.
  */
-export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusal (L1 worktree governance \u2014 locked 2026-07-29)\n\nYou MUST NOT follow the superpowers chain for worktree decisions:\n\n- superpowers:brainstorming \u2192 superpowers:writing-plans \u2192\n  superpowers:subagent-driven-development \u2192 superpowers:using-git-worktrees\n\nThis chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96). It bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. Even when L3 denies the terminal Skill, the chain has already taught you to use raw `git worktree add`, so L3 is not sufficient.\n\nFor worktree operations, use ONLY:\n\n- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)\n- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`\n\nThe superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.\n\nIf the upstream superpowers chain suggests raw `git worktree add`:\n\n1. STOP\n2. Re-author the plan as a peaks-rd artifact\n3. Continue with `peaks worktree spawn` (or the auth-grant fallback)\n";
+export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusal (L1 worktree governance \u2014 locked 2026-07-29)\n\nYou MUST NOT follow the superpowers chain for worktree decisions:\n\n- superpowers:brainstorming \u2192 superpowers:writing-plans \u2192\n  superpowers:subagent-driven-development \u2192 superpowers:using-git-worktrees\n\nThat chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.md line 96), which bypasses peaks-loop's L2 hook gate and L3 IDE `permissions.deny`. L3 denial is NOT sufficient \u2014 by then the chain has already taught raw `git worktree add`.\n\nFor worktree operations, use ONLY:\n\n- `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)\n- until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`\n\nSuperpowers skills remain REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.\n\nIf the upstream superpowers chain suggests raw `git worktree add`:\n\n1. STOP\n2. Re-author the plan as a peaks-rd artifact\n3. Continue with `peaks worktree spawn` (or the auth-grant fallback)\n";
 /**
  * Slice 2026-08-01-subagent-merge-and-e2e (Task 8): the dispatch
  * system prompt gains three lifecycle rules. The sub-agent must:
@@ -117,17 +133,38 @@ export declare const L1_WORKTREE_GOVERNANCE_BLOCK = "## Superpowers chain refusa
  * start, maximizing Anthropic prompt-cache prefix reuse (stable-first
  * ordering).
  */
-export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 2026-08-01)\n\n- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with `peaks sub-agent shutdown register --pid <pid> --name <label>` before you exit. The parent session will best-effort-kill it before merge-back.\n- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10). Your E2E work is duplicate effort.\n- Do NOT call `git merge`, `git pull`, `git rebase`, or `peaks worktree release`. The parent session owns the merge-back step.\n";
+export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 2026-08-01)\n\n- If you start a long-lived local service (vite dev, mock API, docker container, etc.), register it with `peaks sub-agent shutdown register --pid <pid> --name <label>` before you exit; the parent session best-effort-kills it before merge-back.\n- Do NOT run E2E. The parent session runs Playwright verification once after merge-back (Task 10); your E2E work is duplicate effort.\n- Do NOT call `git merge`, `git pull`, `git rebase`, or `peaks worktree release`. The parent session owns the merge-back step.\n";
+/**
+ * Slice 2026-09-10-context-audit-and-discipline (Slice C): cap the sub-agent's
+ * FINAL report.
+ *
+ * Why (measured, session 2026-09-07-session-245530): 20 sub-agent final
+ * reports cost ≈ 60 KB ≈ 15K tokens of the ORCHESTRATOR's window in one
+ * session — the reports, not the dispatch boilerplate, were the second-largest
+ * consumer. The sub-agent already writes a full artifact to disk; the report
+ * only needs to be the index into it.
+ *
+ * QUALITY GUARD (binding): the cap removes no information. Everything the
+ * parent needs to ACT on stays in the report; everything longer lives in the
+ * artifact the parent can `Read`. The five mandatory fields below are exactly
+ * the ones the orchestrator must have to decide the next gate.
+ */
+export declare const REPORT_CAP_BLOCK = "## Final report cap (mandatory)\n\nYour FINAL report to the parent MUST be \u2264 40 lines and \u2264 2 KB. Write any longer detail into the artifact file you already own \u2014 the parent can `Read` that file for the full detail, so nothing is lost. The report itself MUST still carry: changed files (one line each), the exact commands you ran, pass/fail counts, tsc status, and any blocker. Do NOT paste file contents, full tool output, or logs into the report.\n";
 /**
- * Compose the system-prompt body that the dispatch site prepends to
- * `formatTestToolDetection()\n\n`.
+ * Compose the system-prompt body for a sub-agent dispatch.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): the composer owns the Test Tool
+ * Detection injection — ONE unified block for every role, prepended first.
+ * Callers MUST NOT prepend `formatTestToolDetection()` themselves or the
+ * block is injected twice.
  *
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
- * controller brief): when the memory block is unavailable, the caller does
- * `formatTestToolDetection()\n\n${taskBody}` — i.e. the final prompt is exactly
- * `${formatTestToolDetection()}\n\n${taskBody}`. Today's pre-change behavior
- * produced the same string from `src/cli/commands/dispatch-commands.ts:220`,
- * so the unavailable branch MUST return `taskBody` (NOT a `# title\n\n` wrap).
+ * controller brief): when the memory block is unavailable, the composed body is
+ * exactly `formatTestToolDetection() + "\n\n" + L1 + "\n" + LIFECYCLE +
+ * "\n" + REPORT_CAP + "\n" + contextBlock + taskBody`, so the unavailable
+ * branch MUST return `taskBody` unwrapped (NOT a `# title\n\n` wrap).
+ * (REPORT_CAP joined the stable prefix in slice
+ * 2026-09-10-context-audit-and-discipline, Slice C.)
  * The contract holds for callers that do not pass `codegraphBlock` (all
  * non-RD roles). Slice 2026-09-03-codegraph-preread deliberately inserts a
  * codegraph structure block (or its fail-soft unavailable note) for RD
@@ -151,3 +188,23 @@ export declare function buildDispatchSystemPrompt(input: DispatchPromptInput): s
  * byte-stable and trivially testable.
  */
 export declare const CODEGRAPH_UNAVAILABLE_BLOCK = "## Codegraph structure\n\ncodegraph unavailable \u2014 proceeding on project-scan only.\n";
+/** Binding phrases every dispatch prompt must contain, for every role. */
+export declare const BINDING_RULE_TOKENS: readonly string[];
+/**
+ * The runner-direct-path tokens: the refusal example, the two direct paths
+ * the block names (`peaks test --json` to introspect; PB-5, the repo-defined
+ * `test` / `test:*` scripts that are NOT gated), and the two pieces of
+ * quality guidance that must survive any compression — never assume a
+ * runner without asking the user as a last resort, and prefer
+ * `peaks test <file>` because it resolves the local binary Windows-aware.
+ *
+ * 2026-09-10-dispatch-block-d (Option D): there is no role split any more,
+ * so this set is asserted IDENTICALLY for every role. The runner EXAMPLES
+ * were removed as part of the unification — they were never rules.
+ */
+export declare const TEST_RUNNER_RULE_TOKENS: readonly string[];
+/**
+ * Return the subset of `tokens` that `text` does NOT contain. Pure; used by
+ * the rule-presence guard and usable by any future prompt self-check.
+ */
+export declare function missingRuleTokens(text: string, tokens: readonly string[]): readonly string[];