peaks-loop 4.0.36 → 4.0.38

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/build-dispatch-system-prompt.d.ts

@@ -150,6 +150,40 @@ export declare const LIFECYCLE_RULES = "## Sub-agent lifecycle rules (locked 202
  * 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";
+/**
+ * Slice 2026-09-10-fact-force-gate-adaptation: stand IN FRONT of an external
+ * `PreToolUse` gate instead of explaining its denial after the fact.
+ *
+ * ECC (a third-party plugin under `~/.claude/plugins/`) registers
+ * `gateguard-fact-force.js` on `Edit|Write|MultiEdit`. It denies the first
+ * edit of a file whose facts the agent has not established, and its four-item
+ * message never says two things the agent needs: that the file must be READ
+ * first, and that the edit was NOT applied. Measured failure mode
+ * (session 2026-09-10-session-528a63): the sub-agent reads the denial as
+ * "the tool is broken" and abandons the edit.
+ *
+ * So the block below leads with the STANDING RULE (read before you edit) and
+ * names the paths it covers, and mentions the denial only as the consequence
+ * of skipping that rule. A sub-agent that has never seen the gate can read
+ * this once and never trip it.
+ *
+ * The gate itself is untouched: peaks-loop adapts to it, and does NOT disable,
+ * bypass, or re-implement it. Nor is `ECC_GATEGUARD=off` part of this.
+ *
+ * Always rendered — no opt-out flag and no role split. Every role edits files
+ * outside `.peaks/**`, and only sub-agent #1 of a session sees a denial (the
+ * gate fires once per file), so a role-scoped or opt-in block would leave the
+ * rest of the fleet untold. It joins the stable boilerplate prefix: constant
+ * bytes for every dispatch, prompt-cache friendly.
+ *
+ * The `.peaks/**` exemption is real and pre-dates this slice — peaks-loop
+ * materialises `.claude/settings.local.json` so the gate skips `.peaks/**`
+ * (slice 2.0.1-bug3-fact-forcing-bypass; see
+ * `src/cli/commands/workspace/init-command.ts`).
+ */
+export declare const FACT_FORCE_GATE_BLOCK = "## Read before you edit (Fact-Forcing Gate)\n\nRead a file BEFORE your first `Edit` / `Write` / `MultiEdit` on it \u2014 the normal way to work here, not an optional step. It applies to every path OUTSIDE `.peaks/**` (source, tests, docs, config); `.peaks/**` writes are exempt.\n\nSkipping that read trips a `PreToolUse` plugin gate (ECC's \"Fact-Forcing Gate\"), which denies the edit. A denial is NOT a failure and the tool is NOT broken \u2014 your edit was NOT applied. Read the file, state the four facts the gate asks for (importers, affected API, data schemas if any, the user's verbatim instruction), then retry the same operation. Do not switch tools, do not give up, do not re-attempt blindly.\n";
+/** Always-on renderer for {@link FACT_FORCE_GATE_BLOCK}. */
+export declare function renderFactForceGateBlock(): string;
 /**
  * Compose the system-prompt body for a sub-agent dispatch.
  *
@@ -161,7 +195,7 @@ export declare const REPORT_CAP_BLOCK = "## Final report cap (mandatory)\n\nYour
  * Byte-identical degradation contract (slice 2026-07-22-orchestrator-memory-preflight
  * 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
+ * "\n" + REPORT_CAP + "\n" + FACT_FORCE_GATE + "\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.)