peaks-loop 4.0.54 → 4.1.1

package/dist/services/vm/vm-lease.js

@@ -22,7 +22,9 @@ import { randomBytes } from 'node:crypto';
 import { posix as path } from 'node:path';
 import { normalizePath } from '../../shared/path-utils.js';
 export const VM_HYPERVISORS = Object.freeze([
-    'kvm', 'hyperkit', 'hyperv'
+    'kvm',
+    'hyperkit',
+    'hyperv'
 ]);
 // PRD-002b slice 2 — extract lease-TTL primitives (same shape as
 // container-lease.ts / worktree-lease.ts). See config diff comment.
@@ -90,8 +92,18 @@ export function deserializeVmLease(raw) {
     }
     const obj = parsed;
     const required = [
-        'leaseId', 'rid', 'role', 'path', 'hypervisor', 'image', 'vmId',
-        'createdAt', 'expiresAt', 'purpose', 'status', 'consumedBySubAgents'
+        'leaseId',
+        'rid',
+        'role',
+        'path',
+        'hypervisor',
+        'image',
+        'vmId',
+        'createdAt',
+        'expiresAt',
+        'purpose',
+        'status',
+        'consumedBySubAgents'
     ];
     for (const k of required) {
         if (!(k in obj))

package/dist/services/web/aria-node.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `ariaSnapshotJSON()` node type (slice S1, AC2 — the mechanism).
+ *
+ * Split out of `snapshot-pruner.ts` to keep the pruner under the
+ * 300-raw-line file cap; it is the data model the pruner, the renderer and
+ * external consumers (browser-session-manager, tests) all share. The pruner
+ * re-exports this name, so importers keep using `snapshot-pruner.js`
+ * unchanged.
+ */
+export interface AriaNode {
+    readonly role: string;
+    readonly name?: string;
+    readonly text?: string;
+    readonly children?: readonly AriaNode[];
+    readonly checked?: boolean | 'mixed';
+    readonly disabled?: boolean;
+    readonly expanded?: boolean;
+    readonly active?: boolean;
+    readonly invalid?: boolean | 'mixed';
+    readonly level?: number;
+    readonly pressed?: boolean | 'mixed';
+    readonly selected?: boolean;
+    readonly url?: string;
+    readonly placeholder?: string;
+    readonly ref?: string;
+    readonly cursor?: string;
+}

package/dist/services/web/aria-node.js

@@ -0,0 +1 @@
+export {};

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

@@ -59,7 +59,9 @@ export async function acquireChromium() {
 }
 /** 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`;
+    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(' ')}\`)`);
 }

package/dist/services/web/browser-cache-probe.d.ts

@@ -0,0 +1,18 @@
+import type { BrowserProbe } from './web-install-types.js';
+/**
+ * Is the pinned browser on disk? Never throws, never spawns, never downloads.
+ *
+ * **It answers about the artifact `launch()` starts** (R6). `executablePath()`
+ * names the `chromium` build, but `chromium.launch()` with no options and
+ * `headless` defaulting true resolves `chromium-headless-shell`
+ * (`registry.getExecutableName`) — a SEPARATE ~271 MiB download. Probing the
+ * full chromium therefore answered "installed" for a machine on which no op
+ * could launch: `launch()` failed, S1's net downloaded, the probe kept saying
+ * installed, and `peaks web install` short-circuited to a no-op success. See
+ * `headlessShellDir` for how the right path is obtained.
+ *
+ * `version` is reported even when the executable is missing, because "the
+ * package is cached but its browser is not" is a different diagnosis from
+ * "nothing is installed" — the first is one `peaks web install` away.
+ */
+export declare function probeBrowserInstalled(): Promise<BrowserProbe>;

package/dist/services/web/browser-cache-probe.js

@@ -0,0 +1,110 @@
+/**
+ * `src/services/web/browser-cache-probe.ts`
+ *
+ * The browser-cache probe (slice S3, file 18; R6, tech-doc §5.3): it asks the
+ * resolved Playwright package where its executable WOULD be and checks the
+ * filesystem — no download, no spawn, so `peaks web status` can report cache
+ * state on a machine with nothing installed. Moved verbatim (wave 3, file-size
+ * cap campaign) together with the two path derivations and the readdir guard it
+ * depends on, so `web-install-service.ts` stays under the 300 raw-line cap.
+ * `web-install-service.ts` re-exports `probeBrowserInstalled` so importers keep
+ * resolving it from `web-install-service.js` unchanged; the three helpers were
+ * module-private there and are not re-exported.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { loadPlaywright, playwrightVersion } from './playwright-loader.js';
+/**
+ * Is the pinned browser on disk? Never throws, never spawns, never downloads.
+ *
+ * **It answers about the artifact `launch()` starts** (R6). `executablePath()`
+ * names the `chromium` build, but `chromium.launch()` with no options and
+ * `headless` defaulting true resolves `chromium-headless-shell`
+ * (`registry.getExecutableName`) — a SEPARATE ~271 MiB download. Probing the
+ * full chromium therefore answered "installed" for a machine on which no op
+ * could launch: `launch()` failed, S1's net downloaded, the probe kept saying
+ * installed, and `peaks web install` short-circuited to a no-op success. See
+ * `headlessShellDir` for how the right path is obtained.
+ *
+ * `version` is reported even when the executable is missing, because "the
+ * package is cached but its browser is not" is a different diagnosis from
+ * "nothing is installed" — the first is one `peaks web install` away.
+ */
+export async function probeBrowserInstalled() {
+    const version = await playwrightVersion();
+    if (version === null) {
+        return { installed: false, version: null, executablePath: null };
+    }
+    try {
+        const chromiumPath = (await loadPlaywright()).chromium.executablePath();
+        const shellDir = headlessShellDir(chromiumPath);
+        if (shellDir === null) {
+            // Not a registry shape we recognise: answer about the path Playwright
+            // handed us, exactly as this probe did before R6, rather than about a
+            // directory we invented.
+            return { installed: existsSync(chromiumPath), version, executablePath: chromiumPath };
+        }
+        // Absent is the answer, and the whole point: `null` here is what steers
+        // `peaks web install` to download and `acquireChromium` to refuse.
+        const executablePath = headlessShellExecutable(shellDir);
+        return { installed: executablePath !== null, version, executablePath };
+    }
+    catch {
+        // The package resolved but would not load — a broken cache, not a download.
+        return { installed: false, version, executablePath: null };
+    }
+}
+/**
+ * The `chromium_headless_shell-<rev>` directory that sits beside
+ * `chromiumExecutablePath`'s own revision directory, or `null` when the path is
+ * not shaped like Playwright's registry.
+ *
+ * Playwright's public API cannot name the shell — `BrowserType.executablePath()`
+ * takes no options and always answers with the `chromium` build — so it is
+ * derived from the one path Playwright does hand out. One naming rule is
+ * assumed, and it is the one the cache itself shows: `<rev>` directories are
+ * named after the browser, `chromium-1243` beside `chromium_headless_shell-1243`.
+ */
+function headlessShellDir(chromiumExecutablePath) {
+    const segments = chromiumExecutablePath.split(/[\\/]/);
+    let revision = -1;
+    for (let i = segments.length - 1; i > 0; i -= 1) {
+        if (/^chromium-\d+$/.test(segments[i] ?? '')) {
+            revision = i;
+            break;
+        }
+    }
+    const revisionDir = segments[revision];
+    if (revision <= 0 || revisionDir === undefined) {
+        return null;
+    }
+    return join(segments.slice(0, revision).join(sep), revisionDir.replace('chromium-', 'chromium_headless_shell-'));
+}
+/**
+ * The shell executable inside `shellDir`, or `null`.
+ *
+ * The shell's own platform directory is deliberately NOT assumed — it is
+ * `chrome-headless-shell-<platform>` where chromium's is `chrome-<platform>` —
+ * so the file is looked for rather than named from a copy of Playwright's
+ * per-platform path table.
+ */
+function headlessShellExecutable(shellDir) {
+    for (const entry of safeReaddir(shellDir)) {
+        const platformDir = join(shellDir, entry);
+        for (const file of safeReaddir(platformDir)) {
+            if (/^chrome-headless-shell(\.exe)?$/.test(file)) {
+                return join(platformDir, file);
+            }
+        }
+    }
+    return null;
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        // Absent is the normal case on a machine that never installed the shell.
+        return [];
+    }
+}

package/dist/services/web/browser-session-manager.js

@@ -233,7 +233,9 @@ export class BrowserSessionManager {
         const page = await this.pageFor(dispatchId);
         await page.locator(selector).click();
         // The interpolated title is page-controlled; only the selector is ours.
-        return { result: capText(`clicked ${selector} (page: ${await page.title()})`, MAX_TEXT_BYTES).text };
+        return {
+            result: capText(`clicked ${selector} (page: ${await page.title()})`, MAX_TEXT_BYTES).text
+        };
     }
     /**
      * Screenshot to an absolute path under `web/`. Always an explicit `path`:
@@ -363,7 +365,9 @@ function asAriaNodes(raw) {
     if (!Array.isArray(raw)) {
         throw new Error(`WEB_SNAP_SHAPE_UNEXPECTED: ariaSnapshotJSON returned ${typeof raw}, not a node array`);
     }
-    const nodes = raw.filter((node) => typeof node === 'object' && node !== null && typeof node.role === 'string');
+    const nodes = raw.filter((node) => typeof node === 'object' &&
+        node !== null &&
+        typeof node.role === 'string');
     if (nodes.length !== raw.length) {
         throw new Error(`WEB_SNAP_SHAPE_UNEXPECTED: ariaSnapshotJSON returned ${raw.length - nodes.length} node(s) without a string role`);
     }

package/dist/services/web/daemon-registry.js

@@ -45,7 +45,10 @@ export function writeDaemonInfo(projectRoot, sessionId, info) {
     const target = webDaemonInfoPath(projectRoot, sessionId);
     assertUnder(target, webDaemonDir(projectRoot, sessionId));
     mkdirSync(dirname(target), { recursive: true, mode: DAEMON_DIR_MODE });
-    writeFileSync(target, JSON.stringify(info, null, 2), { encoding: 'utf8', mode: DAEMON_FILE_MODE });
+    writeFileSync(target, JSON.stringify(info, null, 2), {
+        encoding: 'utf8',
+        mode: DAEMON_FILE_MODE
+    });
 }
 /**
  * Read + validate `daemon.json`. `null` when absent, malformed, a stale

package/dist/services/web/playwright-loader.d.ts

@@ -1,79 +1,11 @@
+import type { PlaywrightModule, PwBrowser, PwContext, PwLocator, PwPage } from './playwright-types.js';
 /**
  * Exact pin, no caret (tech-doc §3.2). AC2 is a BYTE-COUNT contract and the
  * aria engine moves with the version, so upgrading is a deliberate,
  * re-measured change — never a floating range.
  */
 export declare const PLAYWRIGHT_VERSION_PIN = "1.63.0";
-/**
- * The structural slice of the Playwright API this feature actually calls.
- * Typed locally because the package is not a dependency and therefore has no
- * importable type declarations.
- */
-export interface PwLocator {
-    ariaSnapshotJSON?(options?: {
-        boxes?: boolean;
-        depth?: number;
-        mode?: 'ai' | 'default';
-        timeout?: number;
-    }): Promise<unknown>;
-    click(): Promise<void>;
-    innerText(): Promise<string>;
-    screenshot(options?: {
-        path?: string;
-        type?: 'png' | 'jpeg';
-    }): Promise<Buffer>;
-}
-export interface PwPage {
-    goto(url: string, options?: {
-        waitUntil?: string;
-        timeout?: number;
-    }): Promise<unknown>;
-    title(): Promise<string>;
-    url(): string;
-    locator(selector: string): PwLocator;
-    screenshot(options?: {
-        path?: string;
-        type?: 'png' | 'jpeg';
-    }): Promise<Buffer>;
-    evaluate<T>(expression: string): Promise<T>;
-}
-export interface PwContext {
-    newPage(): Promise<PwPage>;
-    addInitScript(script: string): Promise<void>;
-    storageState(options?: {
-        path?: string;
-    }): Promise<unknown>;
-    close(): Promise<void>;
-}
-export interface PwBrowser {
-    newContext(options?: Record<string, unknown>): Promise<PwContext>;
-    version(): string;
-    /**
-     * `disconnected` is the only signal that the user CLOSED the headed window
-     * (S4 repair), which is what completes a login: once the browser is gone a
-     * non-persistent context cannot be read, so the wait has to end here.
-     *
-     * OPTIONAL: the doubles that exercise the other verbs have no disconnect to
-     * report, and demanding the method made three of them type-broken. A browser
-     * that cannot report the event is treated as never disconnecting (S4 repair,
-     * code review F1).
-     */
-    on?(event: 'disconnected', listener: () => void): void;
-    /**
-     * Whether the browser is still connected. Real Playwright exposes it; the
-     * login checks it ONCE before the wait starts, so a browser that is already
-     * gone fails fast instead of running out the full ten-minute bound — the
-     * `disconnected` event is not replayed for it (S4 repair, code review F3).
-     */
-    isConnected?(): boolean;
-    close(): Promise<void>;
-}
-export interface PlaywrightModule {
-    chromium: {
-        launch(options?: Record<string, unknown>): Promise<PwBrowser>;
-        executablePath(): string;
-    };
-}
+export type { PlaywrightModule, PwBrowser, PwContext, PwLocator, PwPage };
 /**
  * Absolute path of the `playwright` main entry.
  *

package/dist/services/web/playwright-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The structural slice of the Playwright API this feature actually calls
+ * (slice S1, file 9).
+ *
+ * Split out of `playwright-loader.ts` to keep the loader under the
+ * 300-raw-line file cap — types only, no resolution or admission behaviour
+ * lives here. The loader re-exports every name below, so importers keep
+ * using `playwright-loader.js` unchanged. Typed locally because the package
+ * is not a dependency and therefore has no importable type declarations.
+ */
+export interface PwLocator {
+    ariaSnapshotJSON?(options?: {
+        boxes?: boolean;
+        depth?: number;
+        mode?: 'ai' | 'default';
+        timeout?: number;
+    }): Promise<unknown>;
+    click(): Promise<void>;
+    innerText(): Promise<string>;
+    screenshot(options?: {
+        path?: string;
+        type?: 'png' | 'jpeg';
+    }): Promise<Buffer>;
+}
+export interface PwPage {
+    goto(url: string, options?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<unknown>;
+    title(): Promise<string>;
+    url(): string;
+    locator(selector: string): PwLocator;
+    screenshot(options?: {
+        path?: string;
+        type?: 'png' | 'jpeg';
+    }): Promise<Buffer>;
+    evaluate<T>(expression: string): Promise<T>;
+}
+export interface PwContext {
+    newPage(): Promise<PwPage>;
+    addInitScript(script: string): Promise<void>;
+    storageState(options?: {
+        path?: string;
+    }): Promise<unknown>;
+    close(): Promise<void>;
+}
+export interface PwBrowser {
+    newContext(options?: Record<string, unknown>): Promise<PwContext>;
+    version(): string;
+    /**
+     * `disconnected` is the only signal that the user CLOSED the headed window
+     * (S4 repair), which is what completes a login: once the browser is gone a
+     * non-persistent context cannot be read, so the wait has to end here.
+     *
+     * OPTIONAL: the doubles that exercise the other verbs have no disconnect to
+     * report, and demanding the method made three of them type-broken. A browser
+     * that cannot report the event is treated as never disconnecting (S4 repair,
+     * code review F1).
+     */
+    on?(event: 'disconnected', listener: () => void): void;
+    /**
+     * Whether the browser is still connected. Real Playwright exposes it; the
+     * login checks it ONCE before the wait starts, so a browser that is already
+     * gone fails fast instead of running out the full ten-minute bound — the
+     * `disconnected` event is not replayed for it (S4 repair, code review F3).
+     */
+    isConnected?(): boolean;
+    close(): Promise<void>;
+}
+export interface PlaywrightModule {
+    chromium: {
+        launch(options?: Record<string, unknown>): Promise<PwBrowser>;
+        executablePath(): string;
+    };
+}

package/dist/services/web/playwright-types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/web/snapshot-pruner.d.ts

@@ -1,26 +1,5 @@
-/**
- * A node of the `ariaSnapshotJSON()` tree. Fields follow the documented format
- * (`role` is `"text"` for static text fragments; state flags and element
- * attributes are optional).
- */
-export interface AriaNode {
-    readonly role: string;
-    readonly name?: string;
-    readonly text?: string;
-    readonly children?: readonly AriaNode[];
-    readonly checked?: boolean | 'mixed';
-    readonly disabled?: boolean;
-    readonly expanded?: boolean;
-    readonly active?: boolean;
-    readonly invalid?: boolean | 'mixed';
-    readonly level?: number;
-    readonly pressed?: boolean | 'mixed';
-    readonly selected?: boolean;
-    readonly url?: string;
-    readonly placeholder?: string;
-    readonly ref?: string;
-    readonly cursor?: string;
-}
+import type { AriaNode } from './aria-node.js';
+export type { AriaNode };
 /**
  * Roles that carry no information on their own. A node of one of these roles
  * is removed and its children are hoisted into its parent when it also has no

package/dist/services/web/snapshot-pruner.js

@@ -48,7 +48,10 @@ export function pruneAriaSnapshot(nodes) {
     });
     const nodeCapped = droppedByNodeCap > 0;
     const pruned = nodeCapped
-        ? [...cappedNodes, { role: 'text', text: `${TRUNCATION_TEXT} [${droppedByNodeCap} more nodes]` }]
+        ? [
+            ...cappedNodes,
+            { role: 'text', text: `${TRUNCATION_TEXT} [${droppedByNodeCap} more nodes]` }
+        ]
         : cappedNodes;
     return {
         nodes: pruned,
@@ -91,7 +94,7 @@ function isDroppable(node) {
 function dropAndHoist(list, counter) {
     const root = [];
     const stack = [
-        { source: list, index: 0, out: root },
+        { source: list, index: 0, out: root }
     ];
     while (stack.length > 0) {
         const frame = stack[stack.length - 1];
@@ -148,7 +151,9 @@ function applyNodeCap(list, maxNodes, state, onDrop) {
         }
         state.emitted += 1;
         const children = node.children ?? [];
-        out.push(children.length > 0 ? { ...node, children: applyNodeCap(children, maxNodes, state, onDrop) } : node);
+        out.push(children.length > 0
+            ? { ...node, children: applyNodeCap(children, maxNodes, state, onDrop) }
+            : node);
     }
     return out;
 }

package/dist/services/web/web-daemon-service.js

@@ -124,9 +124,7 @@ export async function startWebDaemon(config) {
             return shutdown;
         }
         shutdown = (async () => {
-            const closed = manager === null
-                ? { closedContexts: 0, stateWriteFailures: [] }
-                : await manager.closeAll();
+            const closed = manager === null ? { closedContexts: 0, stateWriteFailures: [] } : await manager.closeAll();
             if (browser !== null) {
                 // Closing the browser ends the chromium process. Without this the
                 // daemon could record a clean stop while the browser outlived it —

package/dist/services/web/web-install-service.d.ts

@@ -1,3 +1,6 @@
+import { type InstallOutcome } from './web-install-types.js';
+export { probeBrowserInstalled } from './browser-cache-probe.js';
+export type { BrowserProbe, InstallOutcome } from './web-install-types.js';
 /**
  * R2: the size of the one-time download, named so it is never a surprise.
  *
@@ -8,44 +11,12 @@
  * each pin bump adds another ~700 MiB beside the old one (1.4 GiB held here).
  */
 export declare const INSTALL_SIZE_WARNING = "downloading chromium (~700 MB on disk, one time)";
-/** What the cache says, without downloading anything (tech-doc §5.3). */
-export interface BrowserProbe {
-    readonly installed: boolean;
-    /** The resolved Playwright PACKAGE version, or `null` when the package is absent. */
-    readonly version: string | null;
-    readonly executablePath: string | null;
-}
-export interface InstallOutcome {
-    readonly ok: boolean;
-    /** `''` on success, otherwise `WEB_INSTALL_BUSY` | `WEB_INSTALL_FAILED` | `WEB_INSTALL_TIMEOUT`. */
-    readonly code: string;
-    readonly message: string;
-    /** The size warning whenever this call actually ran the installer. */
-    readonly warnings: readonly string[];
-}
 /**
  * `PEAKS_WEB_DISABLED=1`, and nothing else. `'0'`, `'true'`, `''` and `'1 '`
  * are all "not disabled" — the flag is an explicit opt-out, so a typo must fail
  * towards the local browser rather than silently skipping it.
  */
 export declare function isWebDisabled(env: NodeJS.ProcessEnv): boolean;
-/**
- * Is the pinned browser on disk? Never throws, never spawns, never downloads.
- *
- * **It answers about the artifact `launch()` starts** (R6). `executablePath()`
- * names the `chromium` build, but `chromium.launch()` with no options and
- * `headless` defaulting true resolves `chromium-headless-shell`
- * (`registry.getExecutableName`) — a SEPARATE ~271 MiB download. Probing the
- * full chromium therefore answered "installed" for a machine on which no op
- * could launch: `launch()` failed, S1's net downloaded, the probe kept saying
- * installed, and `peaks web install` short-circuited to a no-op success. See
- * `headlessShellDir` for how the right path is obtained.
- *
- * `version` is reported even when the executable is missing, because "the
- * package is cached but its browser is not" is a different diagnosis from
- * "nothing is installed" — the first is one `peaks web install` away.
- */
-export declare function probeBrowserInstalled(): Promise<BrowserProbe>;
 /**
  * The exact argv of the one-time download (tech-doc §3.3):
  * `npx --yes --package playwright@<pin> -- playwright install chromium`, with