peaks-loop 4.0.35 → 4.0.37

package/dist/services/slice/slice-decompose-runners.js

@@ -19,6 +19,12 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, relative, dirname } from 'node:path';
+import { resolveNpxInvocation } from '../lint/npx-resolver.js';
+// 2026-09-10: the D1 fix (`orchestrator-can-do.ts`) resolved this tree's own CLI
+// entry so a bare `peaks` never had to be resolved through a Windows `.cmd`
+// shim. `runCodegraph` below needs exactly that, so it reuses the same helper
+// rather than growing a second mechanism.
+import { cliEntryPath, interpreterArgs } from '../web/daemon-supervisor.js';
 export function defaultCodegraphRunner() {
     return {
         async query(text, projectRoot) {
@@ -88,34 +94,31 @@ export function defaultCodegraphRunner() {
     };
 }
 function runCodegraph(args, projectRoot) {
+    const execOptions = {
+        cwd: projectRoot,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 60_000,
+        maxBuffer: 32 * 1024 * 1024
+    };
     // Use `peaks codegraph` (the peaks wrapper), which adds --project support.
-    // Falls back to raw `codegraph` (no --project) if peaks is not on PATH.
-    const isWin = process.platform === 'win32';
-    // Try `peaks codegraph` first (the wrapper that understands --project).
+    // 2026-09-10: no shell. `peaks` on Windows is a `.cmd` shim, which Node >= 20
+    // refuses to spawn without `shell: true` — and `shell: true` concatenates the
+    // argv unescaped, so `--project <projectRoot>` was split at the first space in
+    // the project path (the same defect that made `peaks slice check` report a
+    // phantom failure on such a project). Resolving this tree's own CLI entry and
+    // running it through `process.execPath` needs no shim and no shell, so a
+    // spaced `projectRoot` is just an argument again.
     try {
-        return execFileSync('peaks', ['codegraph', ...args], {
-            cwd: projectRoot,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            shell: isWin,
-            timeout: 60_000,
-            maxBuffer: 32 * 1024 * 1024
-        }).toString('utf8');
+        return execFileSync(process.execPath, [...interpreterArgs(cliEntryPath()), 'codegraph', ...args], execOptions).toString('utf8');
     }
     catch (error) {
         const err = error;
         if (err.code === 'ENOENT') {
-            // Fallback: raw `codegraph` (won't accept --project, drop it)
+            // Fallback: raw `codegraph` (won't accept --project, drop it), reached
+            // through the npx resolver so the local `.bin` shim is never spawned.
             const fallbackArgs = args.filter((a) => a !== '--project' && !a.startsWith('--project='));
-            const localBin = join(projectRoot, 'node_modules', '.bin', 'codegraph');
-            const command = existsSync(localBin) ? localBin : 'npx';
-            const finalArgs = command === 'npx' ? ['codegraph', ...fallbackArgs] : fallbackArgs;
-            return execFileSync(command, finalArgs, {
-                cwd: projectRoot,
-                stdio: ['ignore', 'pipe', 'pipe'],
-                shell: isWin,
-                timeout: 60_000,
-                maxBuffer: 32 * 1024 * 1024
-            }).toString('utf8');
+            const { command, args: npxArgs, baseEnv } = resolveNpxInvocation(['codegraph', ...fallbackArgs]);
+            return execFileSync(command, npxArgs, { ...execOptions, env: baseEnv }).toString('utf8');
         }
         throw error;
     }

package/dist/services/sop/sop-check-service.js

@@ -118,7 +118,18 @@ function evaluateCommand(projectRoot, run, expectExitZero, allowCommands, timeou
     }
     let exitCode;
     try {
-        execFileSync(bin, args, { cwd: resolve(projectRoot), timeout: timeoutMs, stdio: 'ignore' });
+        // Windows: this spawn is reachable from `peaks gate enforce` (the
+        // PreToolUse hook, which forces `allowCommands: true` below), so it runs
+        // on a per-Bash-call budget. Without `windowsHide` the child gets its own
+        // visible console window on Windows — one window per guarded Bash call.
+        // The option is inert on POSIX (libuv reads it only on Windows), which is
+        // why it is set unconditionally rather than platform-branched.
+        execFileSync(bin, args, {
+            cwd: resolve(projectRoot),
+            timeout: timeoutMs,
+            stdio: 'ignore',
+            windowsHide: true
+        });
         exitCode = 0;
     }
     catch (error) {

package/dist/services/web/bounded-output.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Byte-aware output caps for `peaks web` (slice S1, AC2).
+ *
+ * `capText` is the only absolute guarantee in the snapshot pipeline: the
+ * pruner (`snapshot-pruner.ts`) bounds node count and depth, but only a byte
+ * ceiling bounds the rendered string. These are module constants, not options
+ * (tech-doc §12).
+ */
+/** Hard ceiling for page text returned by `peaks web text`. */
+export declare const MAX_TEXT_BYTES = 8192;
+/** Hard ceiling for the rendered snapshot returned by `peaks web snap`. */
+export declare const MAX_SNAP_BYTES = 4096;
+/** Maximum number of real (non-marker) nodes emitted by the pruner. */
+export declare const MAX_SNAP_NODES = 120;
+/** Maximum tree depth emitted by the pruner. */
+export declare const MAX_SNAP_DEPTH = 6;
+export interface CappedText {
+    readonly text: string;
+    readonly truncated: boolean;
+    /** UTF-8 bytes removed from the input. `0` when nothing was truncated. */
+    readonly droppedBytes: number;
+}
+/**
+ * Cut `text` down to at most `capBytes` UTF-8 bytes.
+ *
+ * Three properties the AC2 tests pin:
+ *   - the returned string's byte length is **never** greater than `capBytes`
+ *     (the truncation marker is reserved out of the budget, not added on top);
+ *   - a multi-byte codepoint is never split (the cut backs off the UTF-8
+ *     continuation bytes), so the result is always valid UTF-8;
+ *   - the cut lands on a line boundary when one exists, so the caller never
+ *     gets a half-line.
+ */
+export declare function capText(text: string, capBytes: number): CappedText;

package/dist/services/web/bounded-output.js

@@ -0,0 +1,68 @@
+/**
+ * Byte-aware output caps for `peaks web` (slice S1, AC2).
+ *
+ * `capText` is the only absolute guarantee in the snapshot pipeline: the
+ * pruner (`snapshot-pruner.ts`) bounds node count and depth, but only a byte
+ * ceiling bounds the rendered string. These are module constants, not options
+ * (tech-doc §12).
+ */
+/** Hard ceiling for page text returned by `peaks web text`. */
+export const MAX_TEXT_BYTES = 8192;
+/** Hard ceiling for the rendered snapshot returned by `peaks web snap`. */
+export const MAX_SNAP_BYTES = 4096;
+/** Maximum number of real (non-marker) nodes emitted by the pruner. */
+export const MAX_SNAP_NODES = 120;
+/** Maximum tree depth emitted by the pruner. */
+export const MAX_SNAP_DEPTH = 6;
+/** The marker appended to a truncated payload. Counted INSIDE the ceiling. */
+function truncationMarker(droppedBytes) {
+    return `\n…[truncated ${droppedBytes} bytes]`;
+}
+/**
+ * Cut `text` down to at most `capBytes` UTF-8 bytes.
+ *
+ * Three properties the AC2 tests pin:
+ *   - the returned string's byte length is **never** greater than `capBytes`
+ *     (the truncation marker is reserved out of the budget, not added on top);
+ *   - a multi-byte codepoint is never split (the cut backs off the UTF-8
+ *     continuation bytes), so the result is always valid UTF-8;
+ *   - the cut lands on a line boundary when one exists, so the caller never
+ *     gets a half-line.
+ */
+export function capText(text, capBytes) {
+    const total = Buffer.byteLength(text, 'utf8');
+    if (total <= capBytes) {
+        return { text, truncated: false, droppedBytes: 0 };
+    }
+    // Reserve the WIDEST possible marker (the one whose byte count equals the
+    // whole input) so the ceiling holds on the first pass: the reported marker
+    // can only be narrower than the reserved one.
+    const reservedMarkerBytes = Buffer.byteLength(truncationMarker(total), 'utf8');
+    if (capBytes < reservedMarkerBytes) {
+        // The marker alone would blow the ceiling. The invariant is unconditional,
+        // so for a cap too narrow to hold it the whole payload goes.
+        return { text: '', truncated: true, droppedBytes: total };
+    }
+    const kept = cutAtLineBoundary(text, capBytes - reservedMarkerBytes);
+    const droppedBytes = total - Buffer.byteLength(kept, 'utf8');
+    return { text: kept + truncationMarker(droppedBytes), truncated: true, droppedBytes };
+}
+/**
+ * Largest valid-UTF-8 byte prefix of `text` at or below `budget`, backed off
+ * to the last line break. `text` without any newline keeps the raw byte cut.
+ */
+function cutAtLineBoundary(text, budget) {
+    if (budget <= 0) {
+        return '';
+    }
+    const bytes = Buffer.from(text, 'utf8');
+    let end = Math.min(budget, bytes.length);
+    // A continuation byte (0b10xxxxxx) at the cut point means the codepoint that
+    // started earlier would be split, so walk back until it is not one.
+    while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) {
+        end -= 1;
+    }
+    const prefix = bytes.subarray(0, end).toString('utf8');
+    const lastBreak = prefix.lastIndexOf('\n');
+    return lastBreak > 0 ? prefix.slice(0, lastBreak) : prefix;
+}

package/dist/services/web/browser-acquire.d.ts

@@ -0,0 +1,14 @@
+import { type PwBrowser } from './playwright-loader.js';
+export interface AcquiredChromium {
+    readonly browser: PwBrowser;
+    readonly version: string;
+}
+/**
+ * The ordered gate: disable → resolve → cache probe → launch-or-refuse.
+ *
+ * Every exit here is off the download path, by design — see the module
+ * docstring. The `CODE: detail` shape is `web-daemon-service`'s
+ * `failureResponse` convention, so the caller gets `WEB_INSTALL_REQUIRED` and
+ * not a collapsed `WEB_OP_FAILED`.
+ */
+export declare function acquireChromium(): Promise<AcquiredChromium>;

package/dist/services/web/browser-acquire.js

@@ -0,0 +1,84 @@
+/**
+ * Acquire the chromium browser (slice S1, file 10; S3 adds the ordered gate).
+ *
+ * The order is load-bearing and is the whole of AC5's first half (tech-doc §5.1):
+ *
+ *   1. `PEAKS_WEB_DISABLED=1` → refuse, BEFORE any resolve, any lock file and
+ *      any cache touch. A gate evaluated after a spawn is not a gate.
+ *   2. resolve the pinned Playwright (no npx, no shell — `playwright-loader`).
+ *   3. probe the cache. This is spawn-free and download-free (R6): it answers
+ *      about the artifact `launchOnce` actually starts — the headless shell —
+ *      so "is an install needed" never costs 700 MB to ask, and never answers
+ *      about a browser this code will not launch.
+ *   4. launch, or refuse with `WEB_INSTALL_REQUIRED`.
+ *
+ * **Step 4 is a refusal, not a download** (R3). Installing here meant a blocking
+ * `spawnSync` on the daemon's request loop for up to 20 minutes: `/health`
+ * starved, `status` reported the daemon `orphaned`, `stop` could not prove
+ * ownership and left it running, and the CLI gave up at 30 s and called the op
+ * failed while the download carried on invisibly. The download now belongs to
+ * `peaks web install`, which runs in the caller's own process, on the caller's
+ * terminal, and prints its size before it blocks. The daemon answers the op with
+ * the tier-3 envelope instead.
+ *
+ * We never delete anything in the Playwright cache; recovery is delegated to
+ * Playwright's own `install --force` (design §10.1).
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { loadPlaywright } from './playwright-loader.js';
+import { installCommandLine, isWebDisabled, probeBrowserInstalled } from './web-install-service.js';
+/** The message Playwright raises when the browser binary was never downloaded. */
+const MISSING_EXECUTABLE_RE = /Executable doesn't exist/i;
+/**
+ * The ordered gate: disable → resolve → cache probe → launch-or-refuse.
+ *
+ * Every exit here is off the download path, by design — see the module
+ * docstring. The `CODE: detail` shape is `web-daemon-service`'s
+ * `failureResponse` convention, so the caller gets `WEB_INSTALL_REQUIRED` and
+ * not a collapsed `WEB_OP_FAILED`.
+ */
+export async function acquireChromium() {
+    assertWebEnabled();
+    const playwright = await loadPlaywright();
+    const probe = await probeBrowserInstalled();
+    if (!probe.installed) {
+        throw new Error(`WEB_INSTALL_REQUIRED: ${installRequiredDetail(probe.version)}`);
+    }
+    try {
+        return await launchOnce(playwright);
+    }
+    catch (error) {
+        if (!MISSING_EXECUTABLE_RE.test(getErrorMessage(error))) {
+            throw error;
+        }
+        // The probe named an existing executable that launch still would not take —
+        // a half-written or corrupt revision. `--force` is the documented recovery
+        // (R6), and the caller has to run it: this process must not download.
+        throw new Error(`WEB_INSTALL_REQUIRED: --force ${installRequiredDetail(probe.version)}`);
+    }
+}
+/** One sentence, shared by both refusal paths, naming the command that fixes it. */
+function installRequiredDetail(version) {
+    const held = version === null ? 'the pinned Playwright is not resolvable' : `playwright@${version} is cached`;
+    return (`${held} but its browser is not launched-ready; run \`peaks web install\` ` +
+        `(\`npx ${installCommandLine().join(' ')}\`)`);
+}
+/** Step 1. `PEAKS_WEB_DISABLED=1` means no browser, no spawn, no cache touch. */
+function assertWebEnabled() {
+    if (isWebDisabled(process.env)) {
+        throw new Error('WEB_DISABLED: PEAKS_WEB_DISABLED=1 — the local browser path is switched off for this process');
+    }
+}
+/**
+ * Launch with no options: `headless` defaults true and Playwright resolves
+ * `chromium-headless-shell` (`registry.getExecutableName`). That is deliberate —
+ * the full `chromium` build under new-headless mode was measured on this machine
+ * at **15 101 ms to `close()`**, against **102 ms** for the shell, and S2's
+ * teardown has to finish inside `STOP_EXIT_TIMEOUT_MS = 10 s` or the daemon is
+ * SIGTERM'd mid-teardown and its browser is orphaned (AC6). `probeBrowserInstalled`
+ * is what had to change, not this.
+ */
+async function launchOnce(playwright) {
+    const browser = await playwright.chromium.launch();
+    return { browser, version: browser.version() };
+}

package/dist/services/web/browser-session-manager.d.ts

@@ -0,0 +1,111 @@
+import type { PwBrowser, PwContext } from './playwright-loader.js';
+export interface BrowserSessionManagerOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+}
+export interface WebTextResult {
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly droppedBytes: number;
+}
+export interface WebSnapResult {
+    readonly snapshot: string;
+    readonly droppedNodes: number;
+    readonly depthCapped: boolean;
+    readonly nodeCapped: boolean;
+    readonly truncated: boolean;
+    readonly droppedBytes: number;
+}
+export interface WebMetricsResult {
+    readonly available: boolean;
+    readonly reason: string | null;
+    readonly values: Readonly<Record<string, unknown>> | null;
+}
+/** One dispatch whose storage state could not be persisted at teardown. */
+export interface StateWriteFailure {
+    readonly dispatchId: string;
+    readonly reason: string;
+}
+/**
+ * Resolve with `work`, or reject once the step has taken longer than the step
+ * budget. The late settlement of `work` is consumed here, so a step that
+ * finishes after its deadline cannot become an unhandled rejection.
+ */
+export declare function boundedTeardownStep<T>(work: Promise<T>, label: string): Promise<T>;
+export interface CloseAllResult {
+    /** Contexts closed during this call. */
+    readonly closedContexts: number;
+    /** Never silent: teardown still proceeds, but the caller can report this. */
+    readonly stateWriteFailures: readonly StateWriteFailure[];
+}
+export declare class BrowserSessionManager {
+    private readonly browser;
+    private readonly projectRoot;
+    private readonly sessionId;
+    private readonly sessions;
+    constructor(browser: PwBrowser, options: BrowserSessionManagerOptions);
+    /**
+     * The context for a dispatch, created on first use and reused afterwards.
+     *
+     * `profile` names a user-level login profile (`peaks web login --profile`) to
+     * build the context from. When given it REPLACES the dispatch's own state: a
+     * context holds one storage state, so "start from the profile" and "start from
+     * the per-dispatch state" are alternatives, not layers.
+     *
+     * The profile is **READ-ONLY**. This module reads it into the context and
+     * never writes, refreshes or trims it — write-back is an undecided design
+     * question (it would keep a login fresh without re-running `login`, and it
+     * would also let an automated browse silently rewrite a user-level credential
+     * file), so this slice does not decide it. `closeAll` still persists the
+     * dispatch's OWN `pw-profiles/<dispatchId>/storageState.json`; nothing under
+     * `~/.peaks/web-profiles/` is ever created or modified from here.
+     *
+     * The name is validated HERE and not only in the CLI, because it arrives off
+     * the wire: `resolveProfileName` is the SAME resolver `login` uses (folds to
+     * lower case, refuses a traversing name, a leading dot, a device name), and
+     * the read is anchored with `assertUnder`. A profile that does not exist is a
+     * NAMED failure — falling through to an unauthenticated context would answer
+     * "open this with my profile" with a logged-out browser and no signal.
+     */
+    contextFor(dispatchId: string, rawProfile?: string): Promise<PwContext>;
+    open(dispatchId: string, url: string, profile?: string): Promise<{
+        url: string;
+        title: string;
+    }>;
+    text(dispatchId: string, selector?: string): Promise<WebTextResult>;
+    /**
+     * Primary path is `locator.ariaSnapshotJSON()` (Playwright 1.63, our exact
+     * pin). We do NOT re-derive the tree from the YAML form: parsing YAML by
+     * indentation is the fragile option, and under an exact pin the JSON API is
+     * always present (tech-doc §4.1/§4.2). A missing API is an explicit error
+     * rather than a silent degradation.
+     */
+    snap(dispatchId: string, selector?: string): Promise<WebSnapResult>;
+    click(dispatchId: string, selector: string): Promise<{
+        result: string;
+    }>;
+    /**
+     * Screenshot to an absolute path under `web/`. Always an explicit `path`:
+     * never the Playwright default, and never a Buffer we write ourselves
+     * (tech-doc §7.2 rule 3).
+     */
+    shot(dispatchId: string, selector?: string): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    /**
+     * Core Web Vitals for the dispatch's page. Returns `available: false` with a
+     * reason — never fabricated zeros — when there is no observation window
+     * (orchestrator decision C4), and never echoes the page's object back: only
+     * the three contract keys, only finite numbers (R2).
+     */
+    metrics(dispatchId: string): Promise<WebMetricsResult>;
+    /**
+     * Persist each dispatch's storage state, then close every context exactly
+     * once. A state file that cannot be written must not block shutdown — but it
+     * must be reported: a silent skip here kills S4's persistence with no signal
+     * anywhere (R1).
+     */
+    closeAll(): Promise<CloseAllResult>;
+    private pageFor;
+}