peaks-loop 4.0.36 → 4.0.38

package/dist/services/web/web-login-staging.js

@@ -0,0 +1,173 @@
+/**
+ * Where a captured session LANDS: the staging publish (user decision UD-7,
+ * 2026-09-10; `browser-workflow.md`'s staging carve-out).
+ *
+ * Split out of `web-login-profile.ts` in the S4 repair round 5, which pushed
+ * that file past the 800-line scan limit. The seam is the publish itself:
+ * everything here runs between "the session is in memory" and "the artifact on
+ * disk is the new one".
+ *
+ * WHY STAGING AT ALL: `writeFileSync`'s default flag `w` is `O_TRUNC`, so a
+ * plain overwrite empties `storageState.json` AT OPEN — before its first byte. A
+ * mid-write `ENOSPC`/`EIO` therefore destroyed a working login, while the
+ * failure message called it "unchanged". Staging the bytes beside the artifact
+ * and `renameSync`-ing them on (one filesystem operation within one directory)
+ * means the artifact is either the previous profile or the complete new one, so
+ * what the caller is told is a fact rather than an assertion.
+ *
+ * THE STAGING NAME IS PER-RUN: `<statePath>.<pid>.staging` (S4 repair R5). It
+ * used to be the fixed `<statePath>.staging`, which two `peaks web login` runs
+ * on the same profile shared — A's rename could install B's bytes while A
+ * reported A's counts, and B was then told the artifact "is unchanged" when it
+ * had in fact been replaced. The pid separates them: one login is one process
+ * and its publish is synchronous, so no other discriminator has to hold.
+ *
+ * `browser-workflow.md` sanctions a staging file under three conditions, all
+ * kept here: it lives in the profile directory, it is deleted on every failure
+ * path (and swept by the next run when a kill left one behind), and nothing ever
+ * READS it as a profile.
+ */
+import { chmodSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+/**
+ * The artifact's mode: owner-only, best-effort. `writeFileSync`'s `mode` applies
+ * at creation only, which is why the staging file is chmod'ed explicitly after
+ * the write, and why `renameSync` then carries that mode onto the artifact — so
+ * this is also what owner-onlys a RE-login over an existing file.
+ *
+ * WHAT THIS IS WORTH ON WINDOWS, PLAINLY: the `mode` is INERT there.
+ * `chmodSync(file, 0o600)` RETURNS WITHOUT THROWING while leaving the mode at
+ * 0666 [reproduced], so on Windows this code does not make the staging file or
+ * the artifact owner-only and no warning says so. The protection on this repo's
+ * first platform is the ACL of the user profile these files live in
+ * (`%USERPROFILE%`, not readable by other standard users), NOT this call. On
+ * POSIX the call is what it looks like.
+ */
+const PROFILE_FILE_MODE = 0o600;
+/** The suffix the carve-out names; every staging file this module handles ends in it. */
+const STAGING_SUFFIX = '.staging';
+/**
+ * THIS RUN's staging sibling: `<statePath>.<pid>.staging`, inside the profile
+ * directory, `0600`, and read by nothing (see the module docstring).
+ */
+function stagingPathFor(statePath) {
+    return `${statePath}.${String(process.pid)}${STAGING_SUFFIX}`;
+}
+/**
+ * Publish the captured session ATOMICALLY (UD-7): stage the bytes beside the
+ * artifact, then `renameSync` them onto it.
+ *
+ * A rename within one directory is one filesystem operation, so
+ * `storageState.json` is either the previous profile or the complete new one —
+ * never a truncated half of either. That is what makes the failure message
+ * honest: a thrown write or a thrown rename leaves the artifact as it was, so
+ * "this run did not modify it" is a fact rather than an assertion.
+ *
+ * The staging file never survives this call: the `catch` unlinks it before
+ * rethrowing, and `runHeadedLogin`'s `finally` sweeps it on every path out.
+ * Nothing may ever READ the staging path; it exists only between these two
+ * calls.
+ */
+export function publishState(statePath, snapshot, warnings) {
+    const stagingPath = stagingPathFor(statePath);
+    try {
+        writeFileSync(stagingPath, JSON.stringify(snapshot), { mode: PROFILE_FILE_MODE });
+        restrictToOwner(stagingPath, warnings);
+        renameSync(stagingPath, statePath);
+    }
+    catch (error) {
+        discardStaging(statePath, warnings);
+        throw error;
+    }
+}
+/**
+ * Delete this run's staging file, and sweep any a KILLED run left behind.
+ *
+ * Called on EVERY path out of `runHeadedLogin` — a thrown write, a failed
+ * rename, a timeout, a never-captured close, and after a successful publish
+ * (where the rename has already consumed the file, making this a no-op). The
+ * staging file holds live session cookies, and the carve-out allows it only
+ * while a publish is in flight: it must never outlive the command that created
+ * it.
+ */
+export function discardStaging(statePath, warnings) {
+    unlinkStaging(stagingPathFor(statePath), warnings);
+    for (const stale of staleStagingPaths(statePath)) {
+        unlinkStaging(stale, warnings);
+    }
+}
+/** `rmSync` with `force`: a missing file is a no-op, and a failure is REPORTED. */
+function unlinkStaging(path, warnings) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch (error) {
+        warnings.push(`could not remove the staging file ${path}: ${getErrorMessage(error)}`);
+    }
+}
+/**
+ * The staging files a run that was KILLED left in this profile directory.
+ *
+ * A process that is killed runs no `finally`, so its staging file — live
+ * cookies — survives it, and the next login on this profile is what clears it.
+ *
+ * ONLY files whose pid is GONE qualify. A concurrent login that is still alive
+ * owns its staging file until its own rename consumes it, and deleting that
+ * would make the rename fail and hand that run a failure message about an
+ * artifact it in fact replaced — the false invariant the per-run name exists to
+ * remove.
+ */
+function staleStagingPaths(statePath) {
+    const directory = dirname(statePath);
+    const prefix = `${basename(statePath)}.`;
+    let entries;
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        // No profile directory at all: nothing can be stale inside it.
+        return [];
+    }
+    const stale = [];
+    for (const entry of entries) {
+        if (!entry.startsWith(prefix) || !entry.endsWith(STAGING_SUFFIX)) {
+            continue;
+        }
+        const pid = entry.slice(prefix.length, -STAGING_SUFFIX.length);
+        if (/^\d+$/.test(pid) && !pidIsAlive(Number(pid))) {
+            stale.push(join(directory, entry));
+        }
+    }
+    return stale;
+}
+/**
+ * Whether `pid` is still running. `process.kill(pid, 0)` sends no signal; ESRCH
+ * is the only answer that PROVES the process is gone, so anything else — a live
+ * pid, and equally a permission error on one this process may not signal —
+ * counts as alive. That is the safe direction: it can leave a stale file on
+ * disk, never delete a live run's.
+ */
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+/**
+ * Owner-only the cookie jar, best-effort. A platform (or filesystem) that will
+ * not take the mode is REPORTED rather than swallowed — note that on Windows
+ * this call does not throw and does not restrict anything (see
+ * `PROFILE_FILE_MODE`), so the report covers only the paths that do fail.
+ */
+function restrictToOwner(path, warnings) {
+    try {
+        chmodSync(path, PROFILE_FILE_MODE);
+    }
+    catch (error) {
+        warnings.push(`could not restrict the permissions of ${path}: ${getErrorMessage(error)}`);
+    }
+}

package/dist/services/web/web-protocol.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The `peaks web` daemon contract — on-disk (`daemon.json`) and on-the-wire
+ * (`POST /op`) in one place (slice S1, files 5/6).
+ *
+ * `parseDaemonInfo` validates both shape and `PROTOCOL_VERSION`, so a daemon
+ * left over from an older protocol is rejected (and therefore killed and
+ * respawned) rather than mis-called.
+ */
+/** Bumped whenever `WebOpRequest` / `WebOpResponse` / `WebDaemonInfo` change shape. */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * The full `peaks web` verb surface. S1 implements the first six.
+ *
+ * `whoami` is the CLI's ownership proof: it answers with the daemon's OWN
+ * identity, behind the bearer check, so `peaks web stop` can tell "the daemon
+ * this record describes" from "some local listener that happens to answer 2xx".
+ */
+export type WebOp = 'open' | 'text' | 'snap' | 'click' | 'shot' | 'metrics' | 'login' | 'install' | 'status' | 'stop' | 'whoami';
+/** Contents of `web/daemon/daemon.json` — the only way to reach a live daemon. */
+export interface WebDaemonInfo {
+    readonly protocolVersion: number;
+    readonly pid: number;
+    readonly port: number;
+    /** 32 random bytes, hex. Sent as `Authorization: Bearer <token>`. */
+    readonly token: string;
+    /** `peaks-loop` version that wrote the file. */
+    readonly version: string;
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly startedAt: string;
+}
+/** Body of `POST /op`. */
+export interface WebOpRequest {
+    readonly op: WebOp;
+    readonly args: Readonly<Record<string, unknown>>;
+}
+/** Response of `POST /op`. */
+export interface WebOpResponse<T = unknown> {
+    readonly ok: boolean;
+    readonly data: T | null;
+    readonly code: string | null;
+    readonly message: string | null;
+    readonly warnings: readonly string[];
+    readonly nextActions: readonly string[];
+}
+/**
+ * Parse and validate a `daemon.json` body. Returns `null` for malformed JSON,
+ * a wrong `protocolVersion`, or any missing/mistyped/out-of-range field — never
+ * throws.
+ *
+ * Every field is checked against how the caller will USE it, not just its type:
+ * `port` is bounded to the TCP range because it is interpolated into a URL, and
+ * `pid` is a positive integer because it is passed to `process.kill`. Ownership
+ * (`projectRoot` / `sessionId` vs the caller's) is deliberately NOT checked here
+ * — this function has no caller to compare against; `daemon-registry.readDaemonInfo`
+ * is where that comparison belongs.
+ */
+export declare function parseDaemonInfo(raw: string): WebDaemonInfo | null;

package/dist/services/web/web-protocol.js

@@ -0,0 +1,58 @@
+/**
+ * The `peaks web` daemon contract — on-disk (`daemon.json`) and on-the-wire
+ * (`POST /op`) in one place (slice S1, files 5/6).
+ *
+ * `parseDaemonInfo` validates both shape and `PROTOCOL_VERSION`, so a daemon
+ * left over from an older protocol is rejected (and therefore killed and
+ * respawned) rather than mis-called.
+ */
+/** Bumped whenever `WebOpRequest` / `WebOpResponse` / `WebDaemonInfo` change shape. */
+export const PROTOCOL_VERSION = 1;
+/**
+ * Parse and validate a `daemon.json` body. Returns `null` for malformed JSON,
+ * a wrong `protocolVersion`, or any missing/mistyped/out-of-range field — never
+ * throws.
+ *
+ * Every field is checked against how the caller will USE it, not just its type:
+ * `port` is bounded to the TCP range because it is interpolated into a URL, and
+ * `pid` is a positive integer because it is passed to `process.kill`. Ownership
+ * (`projectRoot` / `sessionId` vs the caller's) is deliberately NOT checked here
+ * — this function has no caller to compare against; `daemon-registry.readDaemonInfo`
+ * is where that comparison belongs.
+ */
+export function parseDaemonInfo(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const { protocolVersion, pid, port, token, version, projectRoot, sessionId, startedAt } = parsed;
+    if (protocolVersion !== PROTOCOL_VERSION) {
+        return null;
+    }
+    if (!isPositiveInteger(pid) || !isTcpPort(port)) {
+        return null;
+    }
+    if (!isNonEmptyString(token) || !isNonEmptyString(version)) {
+        return null;
+    }
+    if (!isNonEmptyString(projectRoot) || !isNonEmptyString(sessionId) || !isNonEmptyString(startedAt)) {
+        return null;
+    }
+    return { protocolVersion, pid, port, token, version, projectRoot, sessionId, startedAt };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/** 1..65535 — the range `fetch('http://127.0.0.1:<port>')` can actually mean. */
+function isTcpPort(value) {
+    return isPositiveInteger(value) && value <= 65_535;
+}

package/dist/services/web/web-status-report.d.ts

@@ -0,0 +1,33 @@
+import { type BrowserProbe } from './web-install-service.js';
+/**
+ * `live` = reachable, `orphaned` = alive but not answering, `stale` = the pid
+ * is gone. Only `live` may be reported as usable.
+ */
+export type WebInstanceState = 'live' | 'orphaned' | 'stale';
+export interface WebStatusInstance {
+    readonly pid: number;
+    readonly port: number;
+    readonly state: WebInstanceState;
+    readonly startedAt: string;
+}
+export interface WebStatusReport {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /**
+     * At most one entry: there is one daemon per `(projectRoot, sessionId)`
+     * (design §10.2). It is a list because a leftover record and a live daemon
+     * can coexist until the record is reaped.
+     */
+    readonly instances: readonly WebStatusInstance[];
+    /**
+     * The same thing, unsugared: `instances[0]` or `null`. AC5's matrix reads
+     * `data.instance === null` for a session with no daemon, and `instances: []`
+     * is the list — one of the two has to be the caller-visible answer.
+     */
+    readonly instance: WebStatusInstance | null;
+    /** S3: the diagnosis path must be able to say WHY nothing will run. */
+    readonly disabled: boolean;
+    readonly browser: BrowserProbe;
+}
+/** Probe this session's daemon records. Never throws: a probe failure is a state, not an error. */
+export declare function buildStatusReport(projectRoot: string, sessionId: string): Promise<WebStatusReport>;

package/dist/services/web/web-status-report.js

@@ -0,0 +1,47 @@
+/**
+ * `peaks web status` — which daemon instances exist for this session, and which
+ * of them are still real (slice S2, file 17).
+ *
+ * The three states are the three states of the loopback protocol (tech-doc
+ * §1.3): `live` (pid alive AND `/health` answers), `orphaned` (pid alive,
+ * `/health` dead — the daemon was SIGKILLed or wedged mid-startup, R3), `stale`
+ * (pid dead — a `daemon.json` left behind by a clean-free crash).
+ *
+ * This is a diagnosis path and nothing else: it opens no browser, downloads
+ * nothing, and never spawns. `peaks web stop` and `peaks web status` are the
+ * two verbs that keep working under S3's disable gate for exactly that reason
+ * (decision C2) — the gate is READ here (to report the flag) but never applied,
+ * and the browser probe it triggers is spawn- and download-free (R6).
+ *
+ * S3 extends the report with the browser-cache probe (`probeBrowserInstalled`),
+ * the `disabled` flag and the single `instance` view; the `instances` half here
+ * is S2's AC3/AC6 surface.
+ */
+import { isProcessAlive, listSessionDaemons } from './daemon-registry.js';
+import { WebDaemonClient } from './web-client.js';
+import { isWebDisabled, probeBrowserInstalled } from './web-install-service.js';
+/** Probe this session's daemon records. Never throws: a probe failure is a state, not an error. */
+export async function buildStatusReport(projectRoot, sessionId) {
+    const instances = [];
+    for (const info of listSessionDaemons(projectRoot, sessionId)) {
+        const alive = isProcessAlive(info.pid);
+        // `/health` is probed only for a live pid: a dead pid's port may have been
+        // reused by an unrelated listener, and that must not read as our daemon
+        // answering.
+        const healthy = alive && (await new WebDaemonClient(info).health());
+        instances.push({
+            pid: info.pid,
+            port: info.port,
+            startedAt: info.startedAt,
+            state: !alive ? 'stale' : healthy ? 'live' : 'orphaned'
+        });
+    }
+    return {
+        projectRoot,
+        sessionId,
+        instances,
+        instance: instances[0] ?? null,
+        disabled: isWebDisabled(process.env),
+        browser: await probeBrowserInstalled()
+    };
+}

package/dist/services/workspace/claude-settings-template.d.ts

@@ -14,10 +14,12 @@
  * the in-memory template byte-for-byte.
  *
  * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a node one-liner that path-matches
- *      `.peaks/_runtime/` and `.peaks/_runtime/<sessionId>/`. Exits 0 (allow)
- *      for those paths, non-zero (deny → fall through to gate) for
- *      everything else.
+ *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
+ *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
+ *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
+ *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
+ *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
+ *      bash-specific and therefore could not take a platform `shell` pin.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -55,14 +57,41 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *           gate). The existing Write|Edit|MultiEdit matcher is
  *           preserved. The new matcher's exit code is the load-bearing
  *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
+ *   1.4.0 — added the `peaks gate enforce` `Bash` PreToolUse entry. It
+ *           lives here (machine-local, gitignored file) rather than in
+ *           the committed `.claude/settings.json` because its `shell`
+ *           is machine-specific: on Windows the default Git-Bash shell
+ *           force-allocates a console window on every Bash tool call.
+ *           This template is the second writer of that file, so it must
+ *           emit the entry too — otherwise `peaks workspace init` would
+ *           overwrite whatever `peaks hooks install` put there.
+ *   1.5.0 — pinned the same platform `shell` on the `peaks code
+ *           gate-step-08` handler. It runs on the same `Bash` matcher,
+ *           so leaving it un-pinned left the console-window defect in
+ *           place for half of every Bash tool call.
+ *   1.6.0 — the `Write|Edit|MultiEdit` handler no longer inlines its
+ *           JavaScript as `node -e "<js>"`. It invokes the shipped script
+ *           `src/services/hooks/write-gate.js` instead, so the command
+ *           string carries no shell-escaped payload at all and the handler
+ *           can take the same platform `shell` pin as its siblings. The
+ *           decision itself is a verbatim relocation — see that file.
+ *   1.7.0 — added the `env` block declaring Peaks' workspace tree exempt
+ *           from a THIRD-PARTY PreToolUse fact-forcing gate
+ *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
+ *           on-disk file to declare those exemptions too, so a project
+ *           installed by an earlier release refreshes once and converges.
  */
-export declare const TEMPLATE_VERSION = "1.3.0";
+export declare const TEMPLATE_VERSION = "1.7.0";
 /**
- * Compare two serialized template strings for semantic equivalence.
+ * Compare two serialized template strings for semantic equivalence: does the
+ * on-disk file already declare everything the generated template declares?
  *
  * Returns `true` iff both strings parse to objects whose
  * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match).
+ * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) AND the
+ * on-disk `env` already carries every exemption the template declares (extra
+ * on-disk keys and extra globs are allowed — a user may exempt other trees,
+ * and a requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -72,9 +101,25 @@ export declare const TEMPLATE_VERSION = "1.3.0";
  * refresh a stale `.peaks/.claude-settings-template.json` on disk.
  */
 export declare function templateContentMatches(generated: string, onDisk: string): boolean;
+/**
+ * Absolute path of the shipped Write|Edit|MultiEdit gate script.
+ *
+ * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
+ * single relative filename resolves in BOTH trees: `src/services/hooks/` for
+ * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
+ * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
+ * `package.json#files` already ships it).
+ *
+ * Separators are normalized to `/` so the emitted command contains no
+ * backslash at all. That is what makes the handler shell-agnostic: bash
+ * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
+ * backslash in the string is one dialect's problem waiting to happen.
+ */
+export declare function writeGateScriptPath(): string;
 type ClaudeHookCommand = {
     type: 'command';
     command: string;
+    shell?: string;
 };
 type ClaudePreToolUseEntry = {
     matcher: string;
@@ -84,6 +129,13 @@ type ClaudeSettingsLocal = {
     hooks: {
         PreToolUse: ClaudePreToolUseEntry[];
     };
+    /**
+     * Exemptions declared to the third-party PreToolUse gate peaks does not own
+     * (`EXTERNAL_GATE_EXEMPT_ENV`). They belong in THIS file because it is
+     * machine-local and gitignored: a third-party variable name in the committed
+     * shared `settings.json` would be pushed to every consumer of the project.
+     */
+    env: Record<string, string>;
 };
 /**
  * Build the full template object. The shape is the subset of Claude