peaks-loop 4.0.36 → 4.0.37

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

@@ -0,0 +1,49 @@
+/**
+ * `peaks web status|stop|install|login` — the daemon-lifecycle, acquisition and
+ * persistent-login verbs (slice S2, file 13; S3 adds `install`; S4 adds `login`).
+ *
+ * Attaches to the `web` parent handed in by `web-commands.ts` rather than
+ * looking it up: the lookup needs a fallback branch for "parent not registered
+ * yet" that cannot happen here, and one less branch is one less path to test.
+ *
+ * None of the four goes through the daemon. `status` must work when the daemon
+ * is dead or wedged — that IS its job (AC6) — and `stop` must work when the
+ * daemon answers nothing at all. Both therefore read the filesystem and the
+ * loopback port directly, and both keep working under S3's
+ * `PEAKS_WEB_DISABLED` gate (decision C2). `install` is a local download, so it
+ * needs no daemon either, and `login` opens its own headed browser (the daemon's
+ * is headless) for a user-level profile that is deliberately cross-project
+ * (design §10.2) — which is why it needs no session binding.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWebLifecycleCommands(web: Command, io: ProgramIO): void;
+export declare function runWebStatus(io: ProgramIO, asJson: boolean): Promise<void>;
+/**
+ * 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 declare function runWebStop(io: ProgramIO, asJson: boolean): Promise<void>;
+/**
+ * `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 declare function runWebInstall(io: ProgramIO, asJson: boolean, force: boolean): Promise<void>;
+/**
+ * `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 declare function runWebLogin(io: ProgramIO, asJson: boolean, rawProfile: string | undefined): Promise<void>;

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/context-audit-hint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Slice 2026-09-10-three-fixes (Slice 2) — proactive context-consumer hint.
+ *
+ * `peaks code context-audit` (Slice A, same day) already reports WHAT fills
+ * the window, but only when someone remembers to run it. The Step 0.8
+ * PreToolUse gate (`peaks code gate-step-08`) runs before every Bash call, so
+ * it is the natural place to surface the single largest consumer — provided
+ * that costs nothing measurable.
+ *
+ * Cost contract (the whole point of this module):
+ *   - The ratio probe is the cheap, adapter-driven `readContextPercent`
+ *     (env-var → statusline file read; the transcript fallback is a
+ *     bounded backwards scan, never a whole-file read).
+ *   - The expensive part — the transcript scan inside `auditContext` — runs
+ *     at most ONCE per TTL window. Its result is cached under
+ *     `.peaks/_runtime/<sid>/context-audit-hint.json`; a fresh entry
+ *     short-circuits the scan entirely.
+ *   - Every failure is fail-soft: a missing/corrupt cache, an unavailable
+ *     transcript, an adapter that cannot locate one — all yield `null`
+ *     (emit nothing). The gate never blocks and never gains more than ONE
+ *     line.
+ *
+ * The cache deliberately records FAILED audits too (with `available:false`),
+ * so a broken transcript cannot turn every Bash call back into a scan.
+ */
+import { type ContextAuditInput, type ContextAuditResult } from './context-audit.js';
+/** Only surface a hint once the window is this full. */
+export declare const CONTEXT_HINT_RATIO_THRESHOLD = 0.7;
+/** Minimum cache TTL — a fresh entry must skip the transcript scan. */
+export declare const CONTEXT_HINT_CACHE_TTL_MS: number;
+/** Per-session cache file name (under `.peaks/_runtime/<sid>/`). */
+export declare const CONTEXT_HINT_CACHE_FILE_NAME = "context-audit-hint.json";
+/** Cached top-consumer snapshot — one audit result, no transcript content. */
+export interface ContextHintCacheEntry {
+    /** Epoch ms when the audit ran (TTL anchor). */
+    readonly cachedAt: number;
+    /** False when the audit could not read the transcript. */
+    readonly available: boolean;
+    /** Ratio observed when the audit ran (informational). */
+    readonly ratio: number;
+    readonly tool: string | null;
+    readonly key: string | null;
+    readonly bytes: number;
+    readonly pctOfTotal: number;
+    readonly count: number;
+}
+export interface ContextAuditHintInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly outerSessionId?: string | null | undefined;
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Clock override (test seam). */
+    readonly nowMs?: number | undefined;
+    /** Cache path override (test seam; default is per-session under `_runtime`). */
+    readonly cachePath?: string | undefined;
+    /** Ratio probe override (test seam). Returns null when unknown. */
+    readonly probeRatio?: (() => number | null) | undefined;
+    /** Audit runner override (test seam; lets a test count scans). */
+    readonly runAudit?: ((input: ContextAuditInput) => ContextAuditResult) | undefined;
+}
+/**
+ * `<projectRoot>/.peaks/_runtime/<sid>/context/context-audit-hint.json`
+ * (gitignored). The `context/` bucket mirrors the existing `<sid>/txt/`
+ * convention so session-id artifacts stay under `.peaks/_runtime/<sid>/`.
+ */
+export declare function contextHintCachePath(projectRoot: string, sessionId: string): string;
+/**
+ * The single line the gate may append. Names ONE consumer — the largest by
+ * tool-result bytes — plus the share and call count that justify the number.
+ */
+export declare function formatContextHintLine(entry: ContextHintCacheEntry): string;
+/**
+ * Build the ONE optional hint line for the Step 0.8 gate.
+ *
+ * Returns `null` when: the ratio is unknown or below 0.70, the cache (fresh)
+ * says the audit was unavailable, the fresh audit found no groups, or
+ * anything throws. Never throws, never blocks.
+ */
+export declare function buildContextAuditHint(input: ContextAuditHintInput): string | null;