peaks-loop 4.0.36 → 4.0.37

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

@@ -28,49 +28,75 @@ const HEAD_LINES_IN_TAIL = 3;
 const AUDIT_MIN_RED_LINES = 60;
 const REVIEW_FILE_MIN_BYTES = 20;
 /**
- * Resolve a CLI binary to a project-local path, falling back to
- * the system `npx`. pnpm (and npm/yarn) all create
- * `node_modules/.bin/<name>`:
- *
- *   - On Unix, this is a symlink to the package's executable.
- *   - On Windows, this is a `.cmd` shim; `execFileSync` only
- *     resolves `.cmd` through the shell (PATHEXT), so we pass
- *     `shell: true` when invoking one. Without this, the
- *     Windows `npx ENOENT` false-positive from
- *     observations 2317 + 2792 reproduces for every local
- *     binary.
+ * 2026-09-10 D1-follow-up (G5): `tsconfig.build.json` is the type contract the
+ * package actually ships (`src/**` only) and it is clean, so the typecheck
+ * stage GATES on it. The wider `tsconfig.json` adds `tests/**`, which still
+ * carries errors this slice did not cause — 142 as measured on 2026-09-10
+ * (`pnpm exec tsc -p tsconfig.json --noEmit 2>&1 | grep -c "error TS"`), all
+ * of them under `tests/`, none under `src/`. That count is therefore a
+ * baseline, not a gate: the stage fails only when it GROWS, which is the
+ * question "did this slice add a type error anywhere?". Re-measure and update
+ * this constant when the residue is paid down.
+ */
+export const TYPECHECK_PREEXISTING_BASELINE = 142;
+/**
+ * 2026-09-10 D1-follow-up (C6): each name resolves to the JS entry its package
+ * declares, as a path relative to `node_modules/` — the same files
+ * `node_modules/.bin/<name>` shims point at.
  *
- * Returns the command + args + a `shell` flag that the
- * `runCommand` helper threads into `execFileSync`.
+ * The `.bin` shim these used to spawn is a `.cmd` on Windows, and a `.cmd`
+ * cannot be spawned without `shell: true` (EINVAL, Node >= 20). `shell: true`
+ * re-parses the command line, so a project path containing a space was split
+ * at the space and the stage reported a phantom typecheck/test failure.
+ * Running the JS entry through `process.execPath` needs no shell — a spaced
+ * path is just an argument — and is the shape the D1 fix uses for `peaks`
+ * itself (`orchestrator-can-do.ts`).
+ */
+const LOCAL_CLI_ENTRIES = {
+    tsc: ['typescript', 'bin', 'tsc'],
+    vitest: ['vitest', 'vitest.mjs']
+};
+/** Named code for "the CLI this stage needs is not installed". */
+export const BINARY_UNRESOLVED_CODE = 'SLICE_CHECK_BINARY_UNRESOLVED';
+function localCliPath(projectRoot, name) {
+    return join(projectRoot, 'node_modules', ...LOCAL_CLI_ENTRIES[name]);
+}
+/**
+ * Resolve a CLI to the interpreter + JS entry `runCommand` needs, or `null`
+ * when that entry is not on disk. Never returns a shell: the returned command
+ * is always `process.execPath`.
  */
 function resolveLocalBinary(projectRoot, name) {
-    // pnpm creates `node_modules/.bin/<name>` (symlink on Unix,
-    // `.cmd` shim on Windows). We probe both shapes; the
-    // `process.platform === 'win32'` extension probe is the most
-    // portable approach.
-    const isWin = process.platform === 'win32';
-    const candidateNames = isWin ? [`${name}.cmd`, `${name}.ps1`, `${name}`] : [name];
-    for (const candidate of candidateNames) {
-        const cmdPath = join(projectRoot, 'node_modules', '.bin', candidate);
-        if (existsSync(cmdPath)) {
-            return { command: cmdPath, args: [], shell: isWin };
-        }
-    }
-    // Fallback: system npx. On Windows this still has the ENOENT
-    // issue, but the fallback is at least informative when it
-    // fires (the user can see "npx not found" instead of a
-    // silent exit 1).
-    return { command: 'npx', args: [name], shell: false };
+    const entry = localCliPath(projectRoot, name);
+    if (!existsSync(entry))
+        return null;
+    return { command: process.execPath, args: [entry] };
 }
-function runCommand(command, args, cwd, timeoutMs, shell = false) {
+/**
+ * Failed stage for an unresolvable CLI. The previous fallback spawned `npx`
+ * and reported whatever came back — an ENOENT-shaped "exited 1" that reads
+ * exactly like a genuine typecheck/test failure. This names the code and the
+ * path that was searched instead.
+ */
+function unresolvedBinaryStage(stage, cli, projectRoot, durationMs) {
+    const expected = localCliPath(projectRoot, cli);
+    return {
+        name: stage,
+        description: `${cli}: binary unresolved (${BINARY_UNRESOLVED_CODE})`,
+        status: 'fail',
+        durationMs,
+        detail: `${BINARY_UNRESOLVED_CODE}: ${cli} not found at ${expected}. Install dependencies (pnpm install) so that entry exists.`,
+        data: { code: BINARY_UNRESOLVED_CODE, cli, expected }
+    };
+}
+function runCommand(command, args, cwd, timeoutMs) {
     const start = Date.now();
     try {
         const stdout = execFileSync(command, args, {
             cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: timeoutMs,
-            maxBuffer: EXEC_MAX_BUFFER_BYTES,
-            shell
+            maxBuffer: EXEC_MAX_BUFFER_BYTES
         }).toString('utf8');
         return {
             status: 'pass',
@@ -105,22 +131,52 @@ function tailLines(text, max) {
 async function runTypecheck(projectRoot) {
     const start = Date.now();
     // Per Windows npx ENOENT (observations 2317+2792 from
-    // 2026-06-09), prefer the project-local `node_modules/.bin/tsc`
-    // (symlink on Unix, .cmd on Windows). The local binary is
-    // installed by pnpm at workspace-install time and avoids the
-    // npx PATH-lookup issue.
+    // 2026-06-09), prefer the project-local tsc; it is installed by
+    // pnpm at workspace-install time and avoids the npx PATH-lookup
+    // issue. 2026-09-10 C6: that local binary is now the package's
+    // JS entry run through `process.execPath`, not the `.bin` shim.
     const tsc = resolveLocalBinary(projectRoot, 'tsc');
-    const result = runCommand(tsc.command, [...tsc.args, '--noEmit'], projectRoot, TYPECHECK_TIMEOUT_MS, tsc.shell);
-    const testFiles = result.stdout.match(/(tests?\/.*\.test\.ts)/g) ?? [];
+    if (tsc === null) {
+        return unresolvedBinaryStage('typecheck', 'tsc', projectRoot, Date.now() - start);
+    }
+    // 2026-09-10 G5: this stage used to run a bare `tsc --noEmit`, which picked
+    // up the DEFAULT tsconfig.json (src/** + tests/**) and its 142 pre-existing
+    // test-side errors — so the stage was permanently red and its one real
+    // signal was buried. The gate is now the build tsconfig, which covers
+    // exactly what ships.
+    const buildConfig = 'tsconfig.build.json';
+    const hasBuildConfig = existsSync(join(projectRoot, buildConfig));
+    const gate = runCommand(tsc.command, [...tsc.args, '-p', hasBuildConfig ? buildConfig : 'tsconfig.json', '--noEmit'], projectRoot, TYPECHECK_TIMEOUT_MS);
+    // Measure the wider count so the residue is surfaced rather than hidden.
+    // The baseline comparison only applies when a clean build tsconfig gives it
+    // a meaning; without one the gate above already IS this run.
+    const wide = hasBuildConfig
+        ? runCommand(tsc.command, [...tsc.args, '-p', 'tsconfig.json', '--noEmit'], projectRoot, TYPECHECK_TIMEOUT_MS)
+        : gate;
+    const wideErrors = (wide.stdout + wide.stderr).match(/error TS\d+/g)?.length ?? 0;
+    const wideLabel = hasBuildConfig ? 'tsconfig.json (src/** + tests/**)' : 'tsconfig.json';
+    const regressed = hasBuildConfig && gate.status === 'pass' && wideErrors > TYPECHECK_PREEXISTING_BASELINE;
+    const reason = gate.status !== 'pass'
+        ? `tsc -p ${hasBuildConfig ? buildConfig : 'tsconfig.json'} --noEmit exited ${gate.exitCode}`
+        : regressed
+            ? `typecheck errors grew to ${wideErrors} (pre-existing baseline ${TYPECHECK_PREEXISTING_BASELINE})`
+            : '';
     return {
         name: 'typecheck',
-        description: `${tsc.command} --noEmit (no JS emit, type-only check)`,
-        status: result.status,
-        durationMs: result.durationMs,
-        detail: result.status === 'pass'
-            ? `Typecheck passed in ${result.durationMs}ms.`
-            : tailLines(result.stdout + result.stderr, TYPECHECK_TAIL_LINES) || `tsc exited with code ${result.exitCode}.`,
-        data: { exitCode: result.exitCode }
+        description: hasBuildConfig
+            ? `tsc -p ${buildConfig} --noEmit (gate) + -p tsconfig.json (baseline report)`
+            : `tsc --noEmit (no JS emit, type-only check)`,
+        status: reason.length === 0 ? 'pass' : 'fail',
+        durationMs: Date.now() - start,
+        detail: reason.length === 0
+            ? `${hasBuildConfig ? `${buildConfig} (src/**) clean; ` : ''}${wideLabel}: ${wideErrors} pre-existing error(s), baseline ${TYPECHECK_PREEXISTING_BASELINE} — reported, not hidden.`
+            : `${reason}. ${tailLines(gate.status !== 'pass' ? gate.stdout + gate.stderr : wide.stdout + wide.stderr, TYPECHECK_TAIL_LINES)}`,
+        data: {
+            exitCode: gate.exitCode,
+            wideTsconfigErrors: wideErrors,
+            preExistingBaseline: hasBuildConfig ? TYPECHECK_PREEXISTING_BASELINE : null,
+            ...(regressed ? { regression: wideErrors - TYPECHECK_PREEXISTING_BASELINE } : {})
+        }
     };
 }
 function parseVitestSummary(stdout, fallbackDuration) {
@@ -147,15 +203,19 @@ async function runUnitTests(projectRoot, runTests) {
     // `tests/unit/slice-check-service.test.ts` for the regression net.
     // Per Windows npx ENOENT (observations 2317+2792), resolve
     // the project-local vitest binary instead of shelling out
-    // through npx.
+    // through npx. 2026-09-10 C6: that binary is the package's JS
+    // entry run through `process.execPath`, not the `.bin` shim.
     const vitest = resolveLocalBinary(projectRoot, 'vitest');
+    if (vitest === null) {
+        return unresolvedBinaryStage('unit-tests', 'vitest', projectRoot, Date.now() - start);
+    }
     const vitestArgs = runTests
         ? ['run', '--reporter=default', '--coverage=false']
         : ['run', '--changed', '--reporter=default', '--coverage=false'];
     const description = runTests
-        ? `${vitest.command} run (full test suite, coverage off)`
-        : `${vitest.command} run --changed (tests for git-changed files only, coverage off)`;
-    const result = runCommand(vitest.command, [...vitest.args, ...vitestArgs], projectRoot, UNIT_TESTS_TIMEOUT_MS, vitest.shell);
+        ? `vitest run (full test suite, coverage off)`
+        : `vitest run --changed (tests for git-changed files only, coverage off)`;
+    const result = runCommand(vitest.command, [...vitest.args, ...vitestArgs], projectRoot, UNIT_TESTS_TIMEOUT_MS);
     const summary = parseVitestSummary(result.stdout, result.durationMs);
     // Vitest doesn't always print the per-bucket counts cleanly; infer "passed"
     // as total - failed - skipped when failed/skipped buckets are present.

package/dist/services/slice/slice-check-types.d.ts

@@ -6,10 +6,15 @@
  * 4 self-checks that must pass at slice end before the slice is handed
  * off to peaks-qa:
  *
- *   1. typecheck (`npx tsc --noEmit`)
+ *   1. typecheck — the project-local TypeScript entry
+ *      (`node_modules/typescript/bin/tsc`) run as `node <entry>`: no
+ *      `npx`, no shell. Gates on `-p tsconfig.build.json --noEmit`; the
+ *      wider `-p tsconfig.json --noEmit` count is reported against
+ *      `TYPECHECK_PREEXISTING_BASELINE` and gates only if it grows.
  *   2. unit tests — by default the **changed-only** suite
- *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
- *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      (`vitest run --changed`, same `node <entry>` shape via
+ *      `node_modules/vitest/vitest.mjs`). Pass `--run-tests` to opt in to
+ *      the full suite (`vitest run`); pass `--skip-tests` to skip
  *      entirely (e.g. docs-only or config-only slices).
  *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
  *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
@@ -48,8 +53,8 @@ export type SliceCheckResult = {
     stages: SliceCheckStage[];
     /**
      * Which unit-test mode actually ran. One of:
-     * - `"changed"` — default: `npx vitest run --changed` (tests for git-changed files only)
-     * - `"full"` — opt-in via `--run-tests`: `npx vitest run` (full suite)
+     * - `"changed"` — default: `vitest run --changed` (tests for git-changed files only)
+     * - `"full"` — opt-in via `--run-tests`: `vitest run` (full suite)
      * - `"skipped"` — opt-in via `--skip-tests` (stage not executed)
      * - `"overridden"` — full mode + `--allow-pre-existing-failures` and the run failed;
      *   stage downgraded to `skipped` with the pre-existing-failure reason
@@ -73,9 +78,9 @@ export type SliceCheckOptions = {
      */
     refreshFanout: boolean;
     /**
-     * When true, run the **full** `npx vitest run` suite at the boundary.
+     * When true, run the **full** `vitest run` suite at the boundary.
      * When false (the default), run the **changed-only** suite
-     * (`npx vitest run --changed`) which only exercises tests related to
+     * (`vitest run --changed`) which only exercises tests related to
      * git-changed files. The changed-only mode is the new default as of
      * run 017 — full suite costs 30s+ on this repo; the changed-only
      * mode costs ~1-3s in steady state and is what catches the

package/dist/services/slice/slice-check-types.js

@@ -6,10 +6,15 @@
  * 4 self-checks that must pass at slice end before the slice is handed
  * off to peaks-qa:
  *
- *   1. typecheck (`npx tsc --noEmit`)
+ *   1. typecheck — the project-local TypeScript entry
+ *      (`node_modules/typescript/bin/tsc`) run as `node <entry>`: no
+ *      `npx`, no shell. Gates on `-p tsconfig.build.json --noEmit`; the
+ *      wider `-p tsconfig.json --noEmit` count is reported against
+ *      `TYPECHECK_PREEXISTING_BASELINE` and gates only if it grows.
  *   2. unit tests — by default the **changed-only** suite
- *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
- *      full suite (`npx vitest run`); pass `--skip-tests` to skip
+ *      (`vitest run --changed`, same `node <entry>` shape via
+ *      `node_modules/vitest/vitest.mjs`). Pass `--run-tests` to opt in to
+ *      the full suite (`vitest run`); pass `--skip-tests` to skip
  *      entirely (e.g. docs-only or config-only slices).
  *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
  *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)

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() };
+}