peaks-loop 4.0.35 → 4.0.37

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

@@ -0,0 +1,164 @@
+/**
+ * File + lock IO for the `peaks web` daemon (slice S1, file 7).
+ *
+ * Isolated from the HTTP client so each is testable alone (tech-doc §2). Every
+ * WRITE goes through `assertUnder` first — the slice-wide guard against an
+ * artifact escaping `<root>/.peaks/_runtime/<sid>/web/` (AC1).
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { assertUnder, webDaemonDir, webDaemonInfoPath, webSpawnLockPath } from './web-artifact-paths.js';
+import { parseDaemonInfo } from './web-protocol.js';
+/** A spawn lock older than this is reclaimed even if its owner pid is alive. */
+const SPAWN_LOCK_STALE_MS = 120_000;
+/**
+ * `daemon.json` holds the 64-hex bearer token that is the ONLY lock on the
+ * loopback port — 127.0.0.1 is reachable by every local user, so the file mode
+ * is the boundary. 0644 would let any local account read the token and drive
+ * the browser (`open`/`text`/`snap`/`shot`) with it. The repo's other
+ * secret-bearing writers already use `0o600`
+ * (`src/services/ide/shared/atomic-json.ts`, `logger.ts`, `config-safety.ts`).
+ */
+const DAEMON_FILE_MODE = 0o600;
+/** The token's directory: readable only by its owner, same reasoning as above. */
+export const DAEMON_DIR_MODE = 0o700;
+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 });
+}
+/**
+ * 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 function readDaemonInfo(projectRoot, sessionId) {
+    const target = webDaemonInfoPath(projectRoot, sessionId);
+    if (!existsSync(target)) {
+        return null;
+    }
+    try {
+        const info = parseDaemonInfo(readFileSync(target, 'utf8'));
+        if (info === null || info.projectRoot !== projectRoot || info.sessionId !== sessionId) {
+            return null;
+        }
+        return info;
+    }
+    catch {
+        return null;
+    }
+}
+/** Remove `daemon.json`. Idempotent: a missing file is not an error. */
+export function removeDaemonInfo(projectRoot, sessionId) {
+    const target = webDaemonInfoPath(projectRoot, sessionId);
+    if (!existsSync(target)) {
+        return;
+    }
+    try {
+        unlinkSync(target);
+    }
+    catch {
+        // Another process removed it between the probe and the unlink.
+    }
+}
+/**
+ * `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 function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * 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 function acquireSpawnLock(projectRoot, sessionId) {
+    const target = webSpawnLockPath(projectRoot, sessionId);
+    assertUnder(target, webDaemonDir(projectRoot, sessionId));
+    mkdirSync(dirname(target), { recursive: true, mode: DAEMON_DIR_MODE });
+    if (tryCreateSpawnLock(target)) {
+        return true;
+    }
+    const existing = readSpawnLock(target);
+    const ageMs = existing === null ? Number.NaN : Date.now() - Date.parse(existing.startedAt);
+    if (existing !== null && isProcessAlive(existing.pid) && ageMs <= SPAWN_LOCK_STALE_MS) {
+        return false;
+    }
+    try {
+        unlinkSync(target);
+    }
+    catch {
+        // Racers: whoever wins the unlink still has to win the O_EXCL create below.
+    }
+    return tryCreateSpawnLock(target);
+}
+/** Release the spawn lock, but only when this process is its owner. */
+export function releaseSpawnLock(projectRoot, sessionId) {
+    const target = webSpawnLockPath(projectRoot, sessionId);
+    const existing = readSpawnLock(target);
+    if (existing !== null && existing.pid !== process.pid) {
+        return;
+    }
+    try {
+        unlinkSync(target);
+    }
+    catch {
+        // Already released (or never held).
+    }
+}
+/**
+ * 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 function listSessionDaemons(projectRoot, sessionId) {
+    const info = readDaemonInfo(projectRoot, sessionId);
+    return info === null ? [] : [info];
+}
+function tryCreateSpawnLock(target) {
+    const body = { pid: process.pid, startedAt: new Date().toISOString() };
+    try {
+        writeFileSync(target, JSON.stringify(body), { flag: 'wx', encoding: 'utf8' });
+        return true;
+    }
+    catch {
+        // `EEXIST` (held) and any other write failure both mean "not acquired".
+        // The caller either waits for the holder or surfaces a readiness timeout.
+        return false;
+    }
+}
+function readSpawnLock(target) {
+    try {
+        const parsed = JSON.parse(readFileSync(target, 'utf8'));
+        const { pid, startedAt } = parsed;
+        if (typeof pid !== 'number' || typeof startedAt !== 'string') {
+            return null;
+        }
+        return { pid, startedAt };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,144 @@
+import type { WebDaemonInfo } from './web-protocol.js';
+export interface StopDaemonResult {
+    /** Daemons confirmed GONE at return — not merely asked to stop. */
+    readonly stopped: number;
+    /** Every pid we asked to stop (gracefully or by signal). */
+    readonly pids: readonly number[];
+    /** Alive but not answering `/health`: recorded, deliberately not signalled. */
+    readonly orphanedPids: readonly number[];
+}
+/**
+ * Absolute path of the daemon entry. The NAME is fixed by the tree we are
+ * running from, so the two supported modes each get a target that exists:
+ * `dist/services/web/daemon-entry.js` after `pnpm build`, and
+ * `src/services/web/daemon-entry.ts` for `pnpm dev` / the test suite.
+ */
+export declare function daemonEntryPath(): string;
+/**
+ * Absolute path of the peaks CLI entry — the file that owns
+ * `sub-agent shutdown register`.
+ *
+ * Explicit, never `process.argv[1]`: the caller of `registerWithParent` is the
+ * DAEMON, whose `argv[1]` is the daemon entry, so spawning it with CLI
+ * arguments boots a second daemon instead of registering anything (R8).
+ */
+export declare function cliEntryPath(): string;
+/**
+ * Arguments that make `node` run `entry`.
+ *
+ * A `.ts` entry needs the TypeScript loader, and it is attached with
+ * `--require preflight.cjs --import loader.mjs` — the exact flags `tsx` passes
+ * to its own child — rather than by running the `tsx` CLI.
+ *
+ * That distinction is not cosmetic. `windowsHide` applies to the process we
+ * spawn and to nothing it spawns in turn: launching `node tsx-cli.mjs entry.ts`
+ * makes tsx spawn a GRANDCHILD, and the grandchild has no `windowsHide` of ours
+ * — so on Windows every dev-mode `peaks web` cold start popped a console window
+ * the user could not close. Invoking the loader directly keeps it one process,
+ * so the flag we already pass covers everything.
+ *
+ * Exported so the race test's caller process is launched through the same
+ * shape as the daemon: two copies of these flags would drift.
+ *
+ * Both callers prepend `process.execPath` themselves, so this returns ONLY the
+ * interpreter flags and the entry.
+ */
+export declare function interpreterArgs(entry: string): string[];
+/**
+ * Whether this Node spells the ESM loader flag `--import`.
+ *
+ * It arrived in 20.6.0 (backported to 18.19.0); below that the spelling is
+ * `--loader`, and passing `--import` is a bad option that kills the daemon at
+ * startup — inside a `READY_TIMEOUT_MS = 20 s` wait whose only diagnosis is a
+ * line in `daemon.log`. `package.json` declares `engines.node >= 20.0.0`, which
+ * includes 20.0–20.5, so the flag cannot be unconditional. `tsx` gates its own
+ * child the same way and this mirrors it.
+ */
+export declare function supportsImportFlag(nodeVersion?: string): boolean;
+/**
+ * The exact command `spawnDaemon` hands to `spawn`, resolved without launching
+ * anything so a test can assert its shape.
+ *
+ * `process.execPath` directly — never `npx`, and therefore never the
+ * `cmd.exe /d /s /c node …` that npm's own `run-script` puts between us and the
+ * daemon (`@npmcli/run-script/lib/make-spawn-args.js` spawns with `shell: true`
+ * and no `windowsHide`). That layer was three processes per cold start instead
+ * of one, it re-parsed our `--require` / `--import` paths through a command
+ * string, it cost 2.8–7.1 s of the ~3 s cold start, and the two intermediate
+ * processes ignored `windowsHide` — the console-window incident, one layer down.
+ */
+export declare function daemonSpawnCommand(): {
+    command: string;
+    args: string[];
+};
+/**
+ * Spawn the detached daemon. Both stdio pipes are redirected to
+ * `web/daemon/daemon.log` — a daemon that inherited our stdout, or wrote to
+ * `cwd`, would be the sneakiest way to break AC1 (tech-doc §7.2 rule 6).
+ */
+export declare function spawnDaemon(projectRoot: string, sessionId: string): {
+    pid: number | undefined;
+};
+/**
+ * Return a healthy daemon for this `(projectRoot, sessionId)`, spawning one only
+ * when the session has none. A record whose pid is GONE is replaced (a stale
+ * file from a SIGKILLed parent, R3); a record whose pid is ALIVE is never
+ * replaced, even when `/health` does not answer — see `DaemonProbe`.
+ *
+ * Cold start is **double-checked locking**: the record, its pid liveness and
+ * `/health` are re-probed AFTER the lock is acquired, with the same oracle the
+ * pre-lock check used, and the lock is held across the spawn AND the readiness
+ * wait. Q10 lets the orchestrator and a sub-agent call
+ * `peaks web` at the same moment, and `spawnDaemon` returns as soon as `spawn()`
+ * does, so releasing the lock there left the whole ~20 s startup window
+ * unprotected: both callers would see no daemon, take the lock in turn, and
+ * launch a browser each — two processes per session in violation of Q8, one of
+ * them unreachable by `peaks web stop`. With the lock held, the loser waits for
+ * the winner's daemon instead of spawning its own.
+ */
+export declare function ensureDaemon(projectRoot: string, sessionId: string): Promise<WebDaemonInfo>;
+/**
+ * Stop this session's daemon and clear its records. Scoped to
+ * `(projectRoot, sessionId)` by construction — another worktree's daemon is
+ * untouched (design §10.2).
+ *
+ * Ownership is proven before asking the process to stop (R6/R7): a planted
+ * `daemon.json` naming an unrelated pid must not make `peaks web stop` kill a
+ * process the caller does not own, and on Windows `SIGTERM` is
+ * `TerminateProcess` with no chance to say "no". `/health` is NOT evidence —
+ * it is answered before the auth check, so any unrelated local listener that
+ * returns 2xx for a `GET` satisfies it. The proof is an AUTHENTICATED `/op`
+ * whose reply reports the very identity the record claims (`isOwnDaemon`): a
+ * recycled pid pointing at somebody else's dev server cannot produce it.
+ *
+ * The graceful path comes FIRST, and it is not a nicety: on Windows a signal
+ * cannot be handled, so signalling would terminate the daemon without running
+ * its teardown, leaving its chromium process behind — the exact false pass
+ * AC6 is written against. `/op {op:'stop'}` lets the daemon close every context,
+ * persist storage state, close the browser and exit on its own terms; the
+ * signal is only the fallback for a daemon that accepts the request and then
+ * fails to leave.
+ *
+ * An instance that is alive but cannot be proven ours is **not** signalled and
+ * **not** de-recorded. Its record is the only handle on a running process:
+ * clearing it would leave the daemon and its chromium detached with no verb
+ * able to reach them, and would let the next cold start spawn a second daemon
+ * beside a live one (Q8). It is reported in `orphanedPids`, and a daemon that
+ * survives its own stop request stays recorded too, so `status` and a second
+ * `stop` still see it.
+ */
+export declare function stopDaemon(projectRoot: string, sessionId: string): Promise<StopDaemonResult>;
+/**
+ * Best-effort registration with the existing sub-agent shutdown registry
+ * (Q7 / tech-doc §7.3).
+ *
+ * The entry point is `cliEntryPath()`, not `process.argv[1]`: this is called by
+ * the daemon, whose `argv[1]` is the daemon entry, so using it spawned a second
+ * daemon-entry with CLI arguments instead of registering anything (R8).
+ *
+ * Registration failing is non-fatal — the caller keeps running — but it must
+ * not be silent: the daemon's stderr is `web/daemon/daemon.log`
+ * (see `spawnDaemon`), so a spawn failure is written there. A detached child
+ * whose `error` event has no listener would otherwise crash the daemon.
+ */
+export declare function registerWithParent(daemonPid: number, dispatchId: string): void;