peaks-loop 4.0.35 → 4.0.37

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

@@ -0,0 +1,413 @@
+/**
+ * All Playwright operations for `peaks web` (slice S1, file 11).
+ *
+ * One browser process per session; one browser CONTEXT per dispatch (Q8). The
+ * context is what isolates cookies/localStorage between dispatches, which is
+ * why the per-dispatch `pw-profiles/<dispatchId>` convention stores a
+ * Playwright `storageState.json` and never a Chromium `userDataDir`
+ * (orchestrator decision C1 — `launchPersistentContext` would spawn one browser
+ * process per dispatch and violate Q8).
+ *
+ * Every write target is passed through `assertUnder` and every screenshot uses
+ * an explicit absolute `path`, so nothing can land in the project root (AC1).
+ *
+ * `open` may additionally name a user-level LOGIN PROFILE (design §2:
+ * `peaks web open <url> [--profile <name>]`, the only verb that takes one). That
+ * profile is **READ-ONLY here**: it is loaded into the dispatch's context and is
+ * never written back. Whether an automated browse should refresh a user-level
+ * credential file is an undecided design question, so this module does not
+ * decide it — see `contextFor`.
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { capText, MAX_SNAP_BYTES, MAX_SNAP_DEPTH, MAX_TEXT_BYTES } from './bounded-output.js';
+import { pruneAriaSnapshot, renderSnapshot } from './snapshot-pruner.js';
+import { assertUnder, userWebProfilesDir, webContextStatePath, webDir, webProfilesDir, webShotPath } from './web-artifact-paths.js';
+import { loginStorageStatePath, resolveProfileName } from './web-login-profile.js';
+/**
+ * Core Web Vitals need observers registered BEFORE the page loads
+ * (orchestrator decision C4), so this is installed as a context init script
+ * rather than run after navigation.
+ */
+const VITALS_INIT_SCRIPT = `(() => {
+  if (globalThis.__peaksWebVitals) return;
+  const vitals = (globalThis.__peaksWebVitals = { lcp: null, cls: 0, inp: null });
+  try {
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      if (entries.length > 0) vitals.lcp = entries[entries.length - 1].startTime;
+    }).observe({ type: 'largest-contentful-paint', buffered: true });
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (!entry.hadRecentInput) vitals.cls += entry.value;
+      }
+    }).observe({ type: 'layout-shift', buffered: true });
+    new PerformanceObserver((list) => {
+      const entries = list.getEntries();
+      if (entries.length > 0) {
+        vitals.inp = Math.max(vitals.inp ?? 0, entries[entries.length - 1].duration);
+      }
+    }).observe({ type: 'event', buffered: true, durationThreshold: 16 });
+  } catch {
+    // Observer types unsupported by this engine: metrics stays unavailable.
+  }
+})();`;
+/**
+ * Total budget for one teardown, and the budget for any single step inside it.
+ *
+ * `stopDaemon` waits `STOP_EXIT_TIMEOUT_MS = 10 s` for the daemon to leave and
+ * then falls back to `SIGTERM`, which on Windows is `TerminateProcess`: it kills
+ * the daemon mid-teardown and orphans its chromium. An unbounded `closeAll` /
+ * `browser.close` therefore converts a SLOW teardown into a LEAKED browser — so
+ * every step is bounded, and the whole thing finishes inside the waiter.
+ *
+ * Retuned after the S3 acceptance run recorded
+ * `teardown step failed: WEB_TEARDOWN_TIMEOUT: browser.close did not finish
+ * within 1500 ms` on a loaded machine. Measured here: an idle `browser.close()`
+ * on the headless shell takes **102 ms**, so the old step budget left only ~15×
+ * on a quiet box and ran out when the machine was busy. The step budget is now
+ * 2 000 ms.
+ *
+ * The loop budget stays ABOVE the step budget — that ordering is a separate
+ * guarantee, tested by its own case: after ONE wedged step is abandoned, the
+ * loop must still reach the remaining contexts. So the constant that moved to
+ * pay for the larger step is the waiter, not the loop:
+ *
+ *     loop 3 000 + 4 x step 2 000 = 11 000 ms  <  STOP_EXIT_TIMEOUT_MS = 15 000 ms
+ *
+ * (worst case: the loop's last iteration starts just under its deadline and
+ * runs two steps, then `browser.close`, then `stopListening`). The waiter polls,
+ * so a normal teardown returns as soon as the process exits and pays nothing for
+ * the larger ceiling; what it buys is that a slow-but-bounded teardown is no
+ * longer SIGTERM'd mid-way, which is what orphans a chromium (AC6). The failure
+ * stays visible either way: `reportTeardownFailure` writes every overrun to
+ * `daemon.log`, which is how this one was found.
+ */
+const TEARDOWN_BUDGET_MS = 3_000;
+const TEARDOWN_STEP_TIMEOUT_MS = 2_000;
+/**
+ * The most distinct dispatch contexts one daemon will hold open.
+ *
+ * A `dispatchId` comes off the wire and there is deliberately no idle-exit
+ * (Q7), so an unbounded map would let a token-holder grow the daemon's memory
+ * one context at a time for its whole life. Past the cap the op is refused by
+ * name rather than silently evicting a context a live dispatch is still using.
+ */
+const MAX_DISPATCH_CONTEXTS = 32;
+/**
+ * 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 function boundedTeardownStep(work, label) {
+    return new Promise((settle, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`WEB_TEARDOWN_TIMEOUT: ${label} did not finish within ${String(TEARDOWN_STEP_TIMEOUT_MS)} ms`));
+        }, TEARDOWN_STEP_TIMEOUT_MS);
+        work.then((value) => {
+            clearTimeout(timer);
+            settle(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export class BrowserSessionManager {
+    browser;
+    projectRoot;
+    sessionId;
+    sessions = new Map();
+    constructor(browser, options) {
+        this.browser = browser;
+        this.projectRoot = options.projectRoot;
+        this.sessionId = options.sessionId;
+    }
+    /**
+     * 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.
+     */
+    async contextFor(dispatchId, rawProfile) {
+        // Resolved before the dedup check, so the value compared below is the
+        // canonical, ≤64-char name and never the raw text off the wire.
+        const profile = rawProfile === undefined ? null : resolveProfileName(rawProfile);
+        const existing = this.sessions.get(dispatchId);
+        if (existing !== undefined) {
+            if (profile !== null && profile !== existing.profile) {
+                // Not a silent wrong answer: this dispatch already has a context and it
+                // was NOT built from the profile just asked for, so reusing it would
+                // serve a request for one profile with a browser logged in as another
+                // (or as nobody).
+                throw new Error(`WEB_PROFILE_CONFLICT: dispatch ${dispatchId} already has a browser context ` +
+                    (existing.profile === null
+                        ? 'that was not created from a profile'
+                        : `created from profile "${existing.profile}"`) +
+                    `; it cannot be reopened as "${profile}" — use a fresh dispatch id or stop the daemon`);
+            }
+            return existing.context;
+        }
+        if (this.sessions.size >= MAX_DISPATCH_CONTEXTS) {
+            throw new Error(`WEB_DISPATCH_LIMIT: this daemon already holds ${String(MAX_DISPATCH_CONTEXTS)} dispatch contexts; ` +
+                'stop the daemon to release them');
+        }
+        const statePath = webContextStatePath(this.projectRoot, this.sessionId, dispatchId);
+        // The state file lives under `pw-profiles/`, a SIBLING of `web/` — guarding
+        // it with `webDir` rejects every dispatch.
+        assertUnder(statePath, webProfilesDir(this.projectRoot, this.sessionId));
+        const profileStatePath = profile === null ? null : existingProfileStatePath(profile);
+        const context = await this.browser.newContext({
+            acceptDownloads: false,
+            ...(profileStatePath !== null
+                ? { storageState: profileStatePath }
+                : existsSync(statePath)
+                    ? { storageState: statePath }
+                    : {})
+        });
+        await context.addInitScript(VITALS_INIT_SCRIPT);
+        this.sessions.set(dispatchId, { context, profile, page: null });
+        return context;
+    }
+    async open(dispatchId, url, profile) {
+        assertNavigableUrl(url);
+        const page = await this.pageFor(dispatchId, profile);
+        await page.goto(url, { waitUntil: 'load' });
+        // `url()` after redirects and `title()` are both page-controlled.
+        return {
+            url: capText(page.url(), MAX_TEXT_BYTES).text,
+            title: capText(await page.title(), MAX_TEXT_BYTES).text
+        };
+    }
+    async text(dispatchId, selector) {
+        const page = await this.pageFor(dispatchId);
+        const raw = await page.locator(selector ?? 'body').innerText();
+        const capped = capText(raw, MAX_TEXT_BYTES);
+        return { text: capped.text, truncated: capped.truncated, droppedBytes: capped.droppedBytes };
+    }
+    /**
+     * 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.
+     */
+    async snap(dispatchId, selector) {
+        const page = await this.pageFor(dispatchId);
+        const locator = page.locator(selector ?? 'body');
+        const captureJson = locator.ariaSnapshotJSON?.bind(locator);
+        if (captureJson === undefined) {
+            throw new Error(`WEB_SNAP_UNSUPPORTED: locator.ariaSnapshotJSON is missing (peaks web pins playwright@1.63.0)`);
+        }
+        const raw = await captureJson({ mode: 'default', depth: MAX_SNAP_DEPTH });
+        const pruned = pruneAriaSnapshot(asAriaNodes(raw));
+        const capped = capText(renderSnapshot(pruned.nodes), MAX_SNAP_BYTES);
+        return {
+            snapshot: capped.text,
+            droppedNodes: pruned.droppedNodes,
+            depthCapped: pruned.depthCapped,
+            nodeCapped: pruned.nodeCapped,
+            truncated: capped.truncated,
+            droppedBytes: capped.droppedBytes
+        };
+    }
+    async click(dispatchId, selector) {
+        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 };
+    }
+    /**
+     * 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).
+     */
+    async shot(dispatchId, selector) {
+        const page = await this.pageFor(dispatchId);
+        const target = webShotPath(this.projectRoot, this.sessionId, shotTimestamp());
+        assertUnder(target, webDir(this.projectRoot, this.sessionId));
+        mkdirSync(dirname(target), { recursive: true });
+        if (selector === undefined) {
+            await page.screenshot({ path: target, type: 'png' });
+        }
+        else {
+            await page.locator(selector).screenshot({ path: target, type: 'png' });
+        }
+        return { path: target, bytes: statSync(target).size };
+    }
+    /**
+     * 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).
+     */
+    async metrics(dispatchId) {
+        const session = this.sessions.get(dispatchId);
+        if (session === undefined || session.page === null) {
+            return { available: false, reason: 'no-observation-window', values: null };
+        }
+        const values = readVitals(await session.page.evaluate('globalThis.__peaksWebVitals ?? null'));
+        if (values === null) {
+            return { available: false, reason: 'no-observation-window', values: null };
+        }
+        return { available: true, reason: null, values };
+    }
+    /**
+     * 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).
+     */
+    async closeAll() {
+        let closedContexts = 0;
+        const stateWriteFailures = [];
+        const deadline = Date.now() + TEARDOWN_BUDGET_MS;
+        for (const [dispatchId, session] of this.sessions) {
+            if (Date.now() >= deadline) {
+                // Out of budget: `browser.close()` below is what reaps the remaining
+                // contexts, and it must still get its turn before the caller's
+                // SIGTERM. `closedContexts` keeps counting only what really closed.
+                break;
+            }
+            const statePath = webContextStatePath(this.projectRoot, this.sessionId, dispatchId);
+            try {
+                assertUnder(statePath, webProfilesDir(this.projectRoot, this.sessionId));
+                mkdirSync(dirname(statePath), { recursive: true });
+                await boundedTeardownStep(session.context.storageState({ path: statePath }), `storageState for dispatch ${dispatchId}`);
+            }
+            catch (error) {
+                stateWriteFailures.push({ dispatchId, reason: getErrorMessage(error) });
+            }
+            try {
+                await boundedTeardownStep(session.context.close(), `context close for dispatch ${dispatchId}`);
+                closedContexts += 1;
+            }
+            catch {
+                // Already closed, or wedged past its budget: teardown must still reach
+                // the remaining dispatches and the final `browser.close()`.
+            }
+        }
+        this.sessions.clear();
+        return { closedContexts, stateWriteFailures };
+    }
+    async pageFor(dispatchId, profile) {
+        // Called on EVERY path, not only when the dispatch has no session yet:
+        // `contextFor` is already the dedup lookup (it returns the existing
+        // context), and reuse is where a profile mismatch has to be caught.
+        await this.contextFor(dispatchId, profile);
+        const active = this.sessions.get(dispatchId);
+        if (active === undefined) {
+            throw new Error(`WEB_CONTEXT_MISSING: no browser context for dispatch ${dispatchId}`);
+        }
+        if (active.page === null) {
+            active.page = await active.context.newPage();
+        }
+        return active.page;
+    }
+}
+/**
+ * The storage state a named profile loads: `~/.peaks/web-profiles/<name>/storageState.json`.
+ *
+ * READ-ONLY by construction: this function only ever READS the path it returns,
+ * and the module never writes one.
+ *
+ * `name` is already canonical (the caller ran `resolveProfileName`); the
+ * resolver inside `loginStorageStatePath` is idempotent on a canonical name, so
+ * the path literal stays in one place. The read is anchored with `assertUnder`
+ * the same way the write site is, and `resolveProfileName`'s own `assertUnder`
+ * has already rejected a name that climbs out of the profile root.
+ *
+ * A missing profile is a NAMED failure. The `existsSync`-guarded spread in
+ * `contextFor` is what it must never become: that pattern silently yields an
+ * unauthenticated context, which is the one answer a caller who asked for a
+ * profile must not be given.
+ */
+function existingProfileStatePath(name) {
+    const statePath = loginStorageStatePath(name);
+    assertUnder(statePath, userWebProfilesDir());
+    if (!existsSync(statePath)) {
+        throw new Error(`WEB_PROFILE_NOT_FOUND: there is no login profile "${name}" at ${statePath} — create it ` +
+            `with \`peaks web login --profile ${name}\``);
+    }
+    return statePath;
+}
+/** `YYYYMMDDTHHMMSSmmmZ` — no colons, so the file name is Windows-safe (§7.1). */
+function shotTimestamp(now = new Date()) {
+    return now.toISOString().replace(/[-:.]/g, '');
+}
+/**
+ * The aria payload as nodes. A shape mismatch is an explicit error, matching
+ * `snap`'s policy for a missing API: an empty-but-`ok` snapshot would be read
+ * as "the page is empty" rather than "the response was not a node array".
+ * An empty array stays valid — that is a genuinely empty page.
+ */
+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');
+    if (nodes.length !== raw.length) {
+        throw new Error(`WEB_SNAP_SHAPE_UNEXPECTED: ariaSnapshotJSON returned ${raw.length - nodes.length} node(s) without a string role`);
+    }
+    return nodes;
+}
+/** The only vitals keys `metrics` reports (orchestrator decision C4's contract). */
+const VITALS_KEYS = ['lcp', 'cls', 'inp'];
+/**
+ * The page's vitals, read as DATA we bounded ourselves. `addInitScript`
+ * installs the object, but a page may replace it afterwards, so nothing is
+ * copied through: only C4's three keys, and only finite numbers. A payload
+ * without a single numeric metric is not an observation window at all.
+ */
+function readVitals(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const source = raw;
+    const values = {};
+    let observed = false;
+    for (const key of VITALS_KEYS) {
+        const value = source[key];
+        const numeric = typeof value === 'number' && Number.isFinite(value);
+        values[key] = numeric ? value : null;
+        observed = observed || numeric;
+    }
+    return observed ? values : null;
+}
+/** The only schemes `open` will navigate to. */
+const ALLOWED_URL_SCHEMES = new Set(['http:', 'https:']);
+/**
+ * `page.goto` would follow `file:` (a local-disk read) and any loopback or
+ * cloud-metadata host, so the scheme is allowlisted at the argument — before a
+ * context exists. Host policy belongs to S3's disable gate, not here.
+ */
+function assertNavigableUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`WEB_URL_INVALID: ${raw} is not an absolute URL`);
+    }
+    if (!ALLOWED_URL_SCHEMES.has(parsed.protocol)) {
+        throw new Error(`WEB_URL_SCHEME_REJECTED: ${parsed.protocol} is not http: or https:`);
+    }
+}

package/dist/services/web/daemon-entry.d.ts

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

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

@@ -0,0 +1,65 @@
+/**
+ * The `peaks web` daemon process entry (slice S2, file 15).
+ *
+ * This file IS the process: it is what `spawnDaemon` launches, so it must run
+ * under plain `node` (built tree) as well as under `tsx` (source tree). It is
+ * deliberately a thin shell — read the environment, start the service, register
+ * with the parent, wire the signals. Everything worth testing lives in
+ * `web-daemon-service.ts`.
+ *
+ * stdout and stderr are already redirected to `web/daemon/daemon.log` by
+ * `spawnDaemon`, which is why every diagnostic here is a plain stderr write and
+ * never a `console.log` to a terminal (tech-doc §7.2 rule 6).
+ */
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { CLI_VERSION } from 'peaks-loop-shared/version';
+import { registerWithParent } from './daemon-supervisor.js';
+import { webDir } from './web-artifact-paths.js';
+import { startWebDaemon } from './web-daemon-service.js';
+function fatal(reason) {
+    process.stderr.write(`peaks web daemon: ${reason}\n`);
+    process.exit(1);
+}
+async function main() {
+    const projectRoot = process.env['PEAKS_WEB_PROJECT_ROOT'] ?? '';
+    const sessionId = process.env['PEAKS_WEB_SESSION_ID'] ?? '';
+    if (projectRoot === '' || sessionId === '') {
+        fatal('PEAKS_WEB_PROJECT_ROOT and PEAKS_WEB_SESSION_ID are both required');
+    }
+    // The artifact dir is derived, never taken on trust: a mis-set env would make
+    // the daemon write outside this session's `web/` tree (AC1), and the failure
+    // would surface as a mystery `WEB_PATH_ESCAPE` much later.
+    const derivedArtifactDir = webDir(projectRoot, sessionId);
+    const declaredArtifactDir = process.env['PEAKS_WEB_ARTIFACT_DIR'] ?? '';
+    if (declaredArtifactDir !== derivedArtifactDir) {
+        fatal(`PEAKS_WEB_ARTIFACT_DIR ${JSON.stringify(declaredArtifactDir)} does not match this session's web dir ${JSON.stringify(derivedArtifactDir)}`);
+    }
+    const daemon = await startWebDaemon({ projectRoot, sessionId, version: CLI_VERSION });
+    // Q7: reuse the existing sub-agent shutdown registry, best-effort. Lifetime
+    // is register + parent kill + `peaks web stop` — there is no idle-exit.
+    registerWithParent(process.pid, process.env['PEAKS_DISPATCH_ID'] ?? 'current');
+    let closing = false;
+    const shutdown = async () => {
+        if (closing) {
+            return;
+        }
+        closing = true;
+        const closed = await daemon.close();
+        // Never silent: a dispatch whose `storageState.json` did not persist is
+        // silent data loss for S4's login profile, and the daemon's stderr is the
+        // only channel that reaches `daemon.log` (R1).
+        for (const failure of closed.stateWriteFailures) {
+            process.stderr.write(`peaks web daemon: could not persist storageState for dispatch ${failure.dispatchId}: ${failure.reason}\n`);
+        }
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+}
+main().catch((error) => {
+    fatal(`startup failed: ${getErrorMessage(error)}`);
+});

package/dist/services/web/daemon-registry.d.ts

@@ -0,0 +1,42 @@
+import { type WebDaemonInfo } from './web-protocol.js';
+/** The token's directory: readable only by its owner, same reasoning as above. */
+export declare const DAEMON_DIR_MODE = 448;
+export declare function writeDaemonInfo(projectRoot: string, sessionId: string, info: WebDaemonInfo): void;
+/**
+ * Read + validate `daemon.json`. `null` when absent, malformed, a stale
+ * protocol, or — R6 — when the file claims to describe a DIFFERENT
+ * `(projectRoot, sessionId)` than the caller's.
+ *
+ * The ownership comparison belongs here rather than in `parseDaemonInfo`,
+ * because only the caller knows what the record is supposed to describe. A
+ * planted `daemon.json` naming someone else's session would otherwise redirect
+ * every op (page URL, selectors, bearer token) to a port of the attacker's
+ * choosing, and — via `stopDaemon` — aim `process.kill` at an unrelated pid.
+ */
+export declare function readDaemonInfo(projectRoot: string, sessionId: string): WebDaemonInfo | null;
+/** Remove `daemon.json`. Idempotent: a missing file is not an error. */
+export declare function removeDaemonInfo(projectRoot: string, sessionId: string): void;
+/**
+ * `process.kill(pid, 0)` is the cross-platform existence probe: it throws
+ * `ESRCH` when no such process exists and `EPERM` when one exists but belongs
+ * to another user and so may not be signalled. Only `ESRCH` means dead — an
+ * alive-but-unsignalable pid must not be reported as dead, or `stopDaemon`
+ * skips the kill and `acquireSpawnLock` reclaims a lock whose owner still
+ * holds it.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Take the cold-start lock (O_EXCL create). Returns `false` when another
+ * process holds a live lock, and reclaims a STALE one — owner pid dead, or
+ * older than `SPAWN_LOCK_STALE_MS` — before retrying once (tech-doc §1.4).
+ */
+export declare function acquireSpawnLock(projectRoot: string, sessionId: string): boolean;
+/** Release the spawn lock, but only when this process is its owner. */
+export declare function releaseSpawnLock(projectRoot: string, sessionId: string): void;
+/**
+ * The daemon instances for a session. There is one daemon per
+ * `(projectRoot, sessionId)` (design §10.2), so this list holds at most one
+ * entry; it is an array because the S2 status report folds it together with the
+ * lock and `/health` classification of each instance.
+ */
+export declare function listSessionDaemons(projectRoot: string, sessionId: string): WebDaemonInfo[];