peaks-loop 4.0.36 → 4.0.38

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

@@ -0,0 +1,416 @@
+/**
+ * The `peaks web` daemon: loopback HTTP server, op routing, shutdown
+ * (slice S2, file 16).
+ *
+ * One daemon per `(projectRoot, sessionId)` (design §10.2). It binds
+ * `127.0.0.1:0` — an OS-assigned port, loopback only — and writes
+ * `web/daemon/daemon.json` with pid/port/token/version (tech-doc §1.3).
+ *
+ * Two deliberate properties:
+ *
+ *   - **Chromium is acquired lazily**, on the first op that needs a page. A
+ *     daemon that launched a browser at boot would make `peaks web status` and
+ *     a cold `stop` pay ~700 MB and a process per session for a session
+ *     that may never touch a page — and would make AC6's "no browser survives
+ *     the session" unverifiable, because booting would already have started
+ *     one.
+ *   - **`routeOp` is exported and takes the manager as an argument**, so the
+ *     whole op surface is testable without a listening socket.
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+import { acquireChromium } from './browser-acquire.js';
+import { boundedTeardownStep, BrowserSessionManager } from './browser-session-manager.js';
+import { removeDaemonInfo, writeDaemonInfo } from './daemon-registry.js';
+import { PROTOCOL_VERSION } from './web-protocol.js';
+/** Loopback only: the bearer token is the second lock, not the only one. */
+export const DAEMON_HOST = '127.0.0.1';
+/**
+ * Largest `/op` body we will buffer. Args are a URL, a selector and a
+ * dispatch id; 64 KiB is orders of magnitude above the real payload and stops
+ * an unrelated local process from growing the daemon's heap.
+ */
+const MAX_REQUEST_BYTES = 64 * 1024;
+/** The request's `dispatchId` when the caller sent none — same default as the CLI. */
+const DEFAULT_DISPATCH_ID = 'current';
+/**
+ * Start the daemon. Resolves once the server is listening and `daemon.json`
+ * exists, so the caller (and every poller in `ensureDaemon`) can treat the
+ * resolution as "reachable".
+ */
+export async function startWebDaemon(config) {
+    const { projectRoot, sessionId } = config;
+    const token = randomBytes(32).toString('hex');
+    let browser = null;
+    let manager = null;
+    let shutdown = null;
+    /** Set synchronously by `close()` before it awaits anything. */
+    let shuttingDown = false;
+    /**
+     * The first PERMANENT acquisition failure, remembered for the daemon's whole
+     * lifetime.
+     *
+     * `managerFor` used to retry on every op, and the `MISSING_EXECUTABLE` branch
+     * of `acquireChromium` re-ran `playwright install chromium` — a blocking,
+     * network-touching `spawnSync`. One attempt per daemon lifetime, then fail
+     * fast, is still right for a failure that cannot heal (`PLAYWRIGHT_NOT_
+     * RESOLVABLE`: nothing on this machine holds the pin).
+     *
+     * It is NOT right for a failure the next minute can fix (R5). `WEB_INSTALL_
+     * BUSY` is "someone else is downloading right now"; `WEB_INSTALL_REQUIRED` is
+     * "the user has not run `peaks web install` yet". Latching either poisoned the
+     * daemon for its whole life: after the CLI's install finished successfully,
+     * every browser op still failed until the daemon was stopped. Those codes are
+     * re-attempted instead — and re-attempting is now cheap, because acquisition
+     * spawns nothing (R3).
+     */
+    let acquireFailure = null;
+    /**
+     * The acquisition already under way, so two ops arriving together share one
+     * launch instead of both passing the `manager === null` check and starting a
+     * browser each — the loser's handle would be overwritten and never closed.
+     */
+    let acquiring = null;
+    const managerFor = async () => {
+        if (acquireFailure !== null) {
+            throw acquireFailure;
+        }
+        if (manager === null) {
+            // The shutdown check lives INSIDE the shared promise, so it runs once for
+            // every caller waiting on it.
+            acquiring ??= (async () => {
+                let acquired;
+                try {
+                    acquired = await acquireChromium();
+                }
+                catch (error) {
+                    // Only a failure that cannot heal is latched; a transient one is
+                    // re-attempted on the next op (R5, see the field's docstring).
+                    if (!isTransientAcquireFailure(error)) {
+                        acquireFailure = error;
+                    }
+                    throw error;
+                }
+                if (shuttingDown) {
+                    // `close()` ran while chromium was launching, so it snapshotted
+                    // `browser === null` and would never close this one. Without this the
+                    // op returns into a daemon that is about to `process.exit(0)`, and
+                    // the fresh chromium outlives it — AC6's false pass.
+                    await acquired.browser.close();
+                    throw new Error('WEB_DAEMON_SHUTTING_DOWN: the daemon is closing; the acquired browser was closed');
+                }
+                return acquired;
+            })();
+            let acquired;
+            try {
+                acquired = await acquiring;
+            }
+            finally {
+                // Released on FAILURE too. Leaving a rejected promise in place meant
+                // every later op awaited it and re-threw the same error without ever
+                // retrying, so a transient failure was permanent in practice whatever
+                // the latch did (R5).
+                acquiring = null;
+            }
+            browser = acquired.browser;
+            manager = new BrowserSessionManager(acquired.browser, { projectRoot, sessionId });
+        }
+        return manager;
+    };
+    const close = async () => {
+        shuttingDown = true;
+        if (shutdown !== null) {
+            return shutdown;
+        }
+        shutdown = (async () => {
+            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 —
+                // the exact false pass AC6 is written against.
+                await boundedTeardownStep(browser.close(), 'browser.close').catch(reportTeardownFailure);
+            }
+            await boundedTeardownStep(stopListening(server), 'stopListening').catch(reportTeardownFailure);
+            removeDaemonInfo(projectRoot, sessionId);
+            return closed;
+        })();
+        return shutdown;
+    };
+    const server = createServer((request, response) => {
+        void handleRequest(request, response).catch((error) => {
+            sendJson(response, 500, failureResponse(error));
+        });
+    });
+    async function handleRequest(request, response) {
+        const url = request.url ?? '';
+        // `/health` is unauthenticated by contract (tech-doc §1.3): it answers
+        // liveness, and the caller already proved ownership by reading daemon.json.
+        if (request.method === 'GET' && url === '/health') {
+            sendJson(response, 200, { ok: true });
+            return;
+        }
+        if (request.method !== 'POST' || url !== '/op') {
+            sendJson(response, 404, failureResponse(new Error('WEB_DAEMON_NOT_FOUND: no such endpoint')));
+            return;
+        }
+        if (!isAuthorized(request, token)) {
+            sendJson(response, 401, failureResponse(new Error('WEB_DAEMON_UNAUTHORIZED: bad or missing bearer token')));
+            return;
+        }
+        const request_ = parseOpRequest(await readBody(request));
+        if (request_ === null) {
+            sendJson(response, 400, failureResponse(new Error('WEB_DAEMON_BAD_REQUEST: body is not a WebOpRequest')));
+            return;
+        }
+        if (request_.op === 'whoami') {
+            // The ownership proof `stopDaemon` needs, answered from this process's
+            // own identity. Handled here rather than in `routeOp` for the same reason
+            // `stop` is: it must answer without ever acquiring a browser, and only the
+            // daemon knows who it is. It sits behind the bearer check above, which is
+            // what makes it evidence and `/health` not.
+            sendJson(response, 200, succeeded({ pid: process.pid, projectRoot, sessionId }));
+            return;
+        }
+        if (request_.op === 'stop') {
+            // Answer FIRST, then tear down: the caller must learn that the stop was
+            // accepted even though the socket is about to disappear.
+            sendJson(response, 200, {
+                ok: true,
+                data: null,
+                code: null,
+                message: null,
+                warnings: [],
+                nextActions: []
+            });
+            response.once('finish', () => {
+                void close()
+                    .catch((error) => {
+                    process.stderr.write(`peaks web: daemon shutdown failed: ${getErrorMessage(error)}\n`);
+                })
+                    .then(() => {
+                    // Re-raise the signal instead of exiting here: `daemon-entry.ts`'s
+                    // handler is the single place that ends the process, so the
+                    // graceful HTTP path and an OS signal take the same route. In a
+                    // test (no listener) this is a no-op and the teardown above is
+                    // what the assertions see.
+                    process.emit('SIGTERM');
+                });
+            });
+            return;
+        }
+        sendJson(response, 200, await routeOp(request_.op, request_.args, managerFor));
+    }
+    const port = await listen(server);
+    writeDaemonInfo(projectRoot, sessionId, {
+        protocolVersion: PROTOCOL_VERSION,
+        pid: process.pid,
+        port,
+        token,
+        version: config.version,
+        projectRoot,
+        sessionId,
+        startedAt: new Date().toISOString()
+    });
+    // One line per boot, on the daemon's stderr (= `daemon.log`). It is the only
+    // surviving record of how many daemons have started for this session:
+    // `daemon.json` holds the LAST writer, so a second, racing daemon would
+    // otherwise leave no trace beyond an orphaned port.
+    process.stderr.write(`peaks web daemon listening on ${DAEMON_HOST}:${String(port)} (pid ${String(process.pid)}, session ${sessionId})\n`);
+    return { port, token, close };
+}
+/**
+ * Serve one op. Exported separately from the server so every verb's payload
+ * shape and failure code are unit-testable without a socket.
+ *
+ * The manager arrives as a PROVIDER, not a value: acquiring it is what launches
+ * chromium, so it must happen only for ops that actually need a page. An op the
+ * daemon does not serve (`install`, `login`, a typo) must answer without
+ * starting a browser at all.
+ */
+export async function routeOp(op, args, managerFor) {
+    const dispatchId = stringArg(args['dispatchId']) || DEFAULT_DISPATCH_ID;
+    try {
+        switch (op) {
+            case 'open': {
+                const manager = await managerFor();
+                // The ONLY verb that accepts a profile (design §2). The name is passed
+                // down raw and validated again in the manager: it arrives off the wire,
+                // so the CLI's own check is not evidence here (same rule as S1's
+                // `assertUnder` / sid-slug pair). A mistyped optional arg means "not
+                // provided", never `[object Object]` — like every other optional arg.
+                return succeeded(await manager.open(dispatchId, stringArg(args['url']), optionalArg(args['profile'])));
+            }
+            case 'text': {
+                const manager = await managerFor();
+                return succeeded(await manager.text(dispatchId, optionalArg(args['selector'])));
+            }
+            case 'snap': {
+                const manager = await managerFor();
+                return succeeded(await manager.snap(dispatchId, optionalArg(args['selector'])));
+            }
+            case 'click': {
+                const manager = await managerFor();
+                return succeeded(await manager.click(dispatchId, stringArg(args['selector'])));
+            }
+            case 'shot': {
+                const manager = await managerFor();
+                return succeeded(await manager.shot(dispatchId, optionalArg(args['selector'])));
+            }
+            case 'metrics': {
+                const manager = await managerFor();
+                return succeeded(await manager.metrics(dispatchId));
+            }
+            default:
+                // `install` / `login` are S3/S4's; the slot exists so they can be
+                // added here as one `case` each rather than by reshaping the router.
+                return failureResponse(new Error(`WEB_OP_UNSUPPORTED: the daemon does not serve '${op}' yet`));
+        }
+    }
+    catch (error) {
+        // Covers both the op itself and chromium acquisition (a missing download,
+        // a resolvable-but-broken playwright).
+        return failureResponse(error);
+    }
+}
+/**
+ * The failure codes that mean "try again later", not "this can never work".
+ *
+ * `acquireChromium` raises the first when the browser simply is not installed
+ * yet and the second when another process holds the install lock — both are
+ * facts about this minute, not about this machine (R5). Everything else
+ * (`PLAYWRIGHT_NOT_RESOLVABLE`, a broken package) is permanent for the daemon's
+ * lifetime and is latched.
+ */
+const TRANSIENT_ACQUIRE_FAILURE_RE = /^(WEB_INSTALL_REQUIRED|WEB_INSTALL_BUSY|WEB_INSTALL_TIMEOUT)\b/;
+function isTransientAcquireFailure(error) {
+    return TRANSIENT_ACQUIRE_FAILURE_RE.test(getErrorMessage(error));
+}
+/**
+ * A bounded teardown step that ran out of budget must not abort the rest of the
+ * teardown — the record removal and the exit are what stop a wedged daemon from
+ * becoming invisible — but it must not be silent either, so it says so on the
+ * daemon's stderr (= `daemon.log`).
+ */
+function reportTeardownFailure(error) {
+    process.stderr.write(`peaks web daemon: teardown step failed: ${getErrorMessage(error)}\n`);
+}
+/** `{ok:true}` with the op payload as `data`. */
+function succeeded(data) {
+    return { ok: true, data, code: null, message: null, warnings: [], nextActions: [] };
+}
+/**
+ * Map a thrown error onto the envelope. S1's modules signal their failure code
+ * as a `CODE: detail` prefix, so the code survives the trip to the CLI instead
+ * of collapsing every daemon failure into one opaque `WEB_OP_FAILED`.
+ */
+function failureResponse(error) {
+    const message = getErrorMessage(error);
+    const match = /^([A-Z][A-Z0-9_]{0,63}):\s*([\s\S]*)$/.exec(message);
+    return {
+        ok: false,
+        data: null,
+        code: match?.[1] ?? 'WEB_OP_FAILED',
+        message: match?.[2] ?? message,
+        warnings: [],
+        nextActions: []
+    };
+}
+/**
+ * Constant-time bearer check. `timingSafeEqual` needs equal byte lengths, so
+ * the length is compared first — a length mismatch is not a secret (the token
+ * is a fixed 64 hex chars) and the comparison is otherwise byte-for-byte.
+ */
+function isAuthorized(request, token) {
+    const header = request.headers.authorization ?? '';
+    const presented = header.startsWith('Bearer ') ? header.slice('Bearer '.length) : '';
+    const expected = Buffer.from(token, 'utf8');
+    const actual = Buffer.from(presented, 'utf8');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+/** Read the body, refusing anything past `MAX_REQUEST_BYTES`. */
+async function readBody(request) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const bytes = chunk;
+        size += bytes.length;
+        if (size > MAX_REQUEST_BYTES) {
+            throw new Error(`WEB_DAEMON_BODY_TOO_LARGE: body exceeds ${String(MAX_REQUEST_BYTES)} bytes`);
+        }
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/** `{op, args}` or `null` when the body is not shaped like a `WebOpRequest`. */
+function parseOpRequest(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const { op, args } = parsed;
+    if (typeof op !== 'string' || op.length === 0) {
+        return null;
+    }
+    return {
+        op: op,
+        args: typeof args === 'object' && args !== null && !Array.isArray(args)
+            ? args
+            : {}
+    };
+}
+function stringArg(value) {
+    return typeof value === 'string' ? value : '';
+}
+/** An absent OR mistyped optional argument means "not provided", never `[object Object]`. */
+function optionalArg(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function sendJson(response, status, body) {
+    if (response.headersSent) {
+        response.end();
+        return;
+    }
+    const payload = JSON.stringify(body);
+    response.writeHead(status, {
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(payload, 'utf8')
+    });
+    response.end(payload);
+}
+/** Bind, and report the OS-assigned port. */
+function listen(server) {
+    return new Promise((settle, reject) => {
+        server.once('error', reject);
+        server.listen(0, DAEMON_HOST, () => {
+            server.removeListener('error', reject);
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('WEB_DAEMON_BIND_FAILED: no TCP address after listen'));
+                return;
+            }
+            settle(address.port);
+        });
+    });
+}
+/**
+ * Stop accepting work and release the socket. Idle keep-alive connections are
+ * dropped first: `fetch` keeps its connection open, and `server.close()` alone
+ * would wait for it until its own timeout.
+ */
+function stopListening(server) {
+    return new Promise((settle) => {
+        server.close(() => {
+            settle();
+        });
+        server.closeAllConnections();
+    });
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The degradation chain, in one place (slice S3, file 19; AC5, tech-doc §5.4).
+ *
+ * Design §6 orders the chain: 1 local browser → 2 lazy download → 3 MCP
+ * fallback → 4 explicit error + install guidance. Orchestrator decision C3 is
+ * binding on how tiers 3 and 4 are represented here: they are **not a branch
+ * this process can take**. Whether `mcp__playwright__*` is available is harness
+ * state — the CLI is a subprocess and cannot see the caller's tool list — so
+ * the envelope carries BOTH the MCP fallback action and the install
+ * instruction, and the calling LLM picks. Naming the MCP tool explicitly, and
+ * saying where a screenshot taken through it lands, is what keeps the two
+ * options distinguishable; a blob that reads as one undifferentiated warning
+ * would defeat the purpose (C3's "consequence to keep").
+ *
+ * `installHint` is derived from `installCommandLine()`'s pin so the guidance
+ * and the command that is actually run cannot drift apart.
+ */
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+import type { WebOp } from './web-protocol.js';
+/** 3 = fall back to MCP and/or install locally; 4 = nothing available. */
+export type DegradationTier = 3 | 4;
+/**
+ * The MCP tool that replaces each op on the fallback path.
+ *
+ * `status` / `stop` / `whoami` have no browser path at all, so they have no MCP
+ * equivalent and no degradation envelope: C2's matrix keeps them working
+ * (`status` reports the disabled flag, `stop` stops a process). The empty
+ * string is that "no fallback exists" answer, and `degradedEnvelope` — the only
+ * caller — says so rather than naming a tool that cannot do the job.
+ *
+ * `login` is empty for the SAME reason, and it is the one browser op where that
+ * is not obvious (S4 R3). No `mcp__playwright__*` tool persists a storage state,
+ * so `browser_navigate` was a dead end for the only verb whose whole purpose is
+ * persistence: an envelope that told a caller to call it would contradict its own
+ * `nextActions`. The machine-readable field now agrees with the human-readable
+ * one.
+ */
+export declare const MCP_TOOL_FOR_OP: Record<WebOp, string>;
+/**
+ * Design §6 tier-3 wording. Two approved artifacts spell it two ways — the
+ * design says 截图会落根目录, `qa/test-cases/peaks-web.md` §5 quotes
+ * 截图会落项目根目录 as "原文" — so both are carried, rather than picking one and
+ * failing the other's assertion. The second half says it in English for the
+ * same reason.
+ */
+export declare const MCP_ROOT_DIR_WARNING = "MCP fallback screenshots land in the project root\uFF08\u622A\u56FE\u4F1A\u843D\u6839\u76EE\u5F55 / \u622A\u56FE\u4F1A\u843D\u9879\u76EE\u6839\u76EE\u5F55\uFF09";
+/** The command a user or the LLM would run to get the local path back. */
+export declare const INSTALL_HINT = "npx --yes --package playwright@1.63.0 -- playwright install chromium";
+export interface DegradedData {
+    readonly tier: DegradationTier;
+    /** Empty when the op has no MCP equivalent (see `MCP_TOOL_FOR_OP`). */
+    readonly mcpTool: string;
+    readonly installHint: string;
+    /**
+     * The op's own arguments, carried so the fallback is *actionable* (R9).
+     * "Call `mcp__playwright__browser_navigate` instead" is not something a caller
+     * can execute without the URL; `browser_evaluate` for `text`/`metrics` is not
+     * something a caller can execute without the selector. Only string arguments
+     * are carried — they are the op surface, and dropping the rest keeps a
+     * `dispatchId`-shaped value from leaking into a fallback blob.
+     */
+    readonly args: Readonly<Record<string, string>>;
+}
+/**
+ * One envelope for the whole tier-3/4 branch (C3): `ok:false`, a code, the
+ * fallback tool, the install command, the op's own arguments, and the two things
+ * a caller must know — the local path was skipped and where the MCP path puts
+ * its screenshots.
+ */
+export declare function degradedEnvelope(op: WebOp, reason: string, tier?: DegradationTier, opArgs?: Readonly<Record<string, unknown>>): ResultEnvelope<DegradedData>;

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

@@ -0,0 +1,121 @@
+/**
+ * The degradation chain, in one place (slice S3, file 19; AC5, tech-doc §5.4).
+ *
+ * Design §6 orders the chain: 1 local browser → 2 lazy download → 3 MCP
+ * fallback → 4 explicit error + install guidance. Orchestrator decision C3 is
+ * binding on how tiers 3 and 4 are represented here: they are **not a branch
+ * this process can take**. Whether `mcp__playwright__*` is available is harness
+ * state — the CLI is a subprocess and cannot see the caller's tool list — so
+ * the envelope carries BOTH the MCP fallback action and the install
+ * instruction, and the calling LLM picks. Naming the MCP tool explicitly, and
+ * saying where a screenshot taken through it lands, is what keeps the two
+ * options distinguishable; a blob that reads as one undifferentiated warning
+ * would defeat the purpose (C3's "consequence to keep").
+ *
+ * `installHint` is derived from `installCommandLine()`'s pin so the guidance
+ * and the command that is actually run cannot drift apart.
+ */
+import { fail } from 'peaks-loop-shared/result';
+import { PLAYWRIGHT_VERSION_PIN } from './playwright-loader.js';
+/**
+ * The MCP tool that replaces each op on the fallback path.
+ *
+ * `status` / `stop` / `whoami` have no browser path at all, so they have no MCP
+ * equivalent and no degradation envelope: C2's matrix keeps them working
+ * (`status` reports the disabled flag, `stop` stops a process). The empty
+ * string is that "no fallback exists" answer, and `degradedEnvelope` — the only
+ * caller — says so rather than naming a tool that cannot do the job.
+ *
+ * `login` is empty for the SAME reason, and it is the one browser op where that
+ * is not obvious (S4 R3). No `mcp__playwright__*` tool persists a storage state,
+ * so `browser_navigate` was a dead end for the only verb whose whole purpose is
+ * persistence: an envelope that told a caller to call it would contradict its own
+ * `nextActions`. The machine-readable field now agrees with the human-readable
+ * one.
+ */
+export const MCP_TOOL_FOR_OP = {
+    open: 'mcp__playwright__browser_navigate',
+    text: 'mcp__playwright__browser_evaluate',
+    snap: 'mcp__playwright__browser_snapshot',
+    click: 'mcp__playwright__browser_click',
+    shot: 'mcp__playwright__browser_take_screenshot',
+    metrics: 'mcp__playwright__browser_evaluate',
+    login: '',
+    install: 'mcp__playwright__browser_install',
+    status: '',
+    stop: '',
+    whoami: ''
+};
+/**
+ * Design §6 tier-3 wording. Two approved artifacts spell it two ways — the
+ * design says 截图会落根目录, `qa/test-cases/peaks-web.md` §5 quotes
+ * 截图会落项目根目录 as "原文" — so both are carried, rather than picking one and
+ * failing the other's assertion. The second half says it in English for the
+ * same reason.
+ */
+export const MCP_ROOT_DIR_WARNING = 'MCP fallback screenshots land in the project root（截图会落根目录 / 截图会落项目根目录）';
+/** The command a user or the LLM would run to get the local path back. */
+export const INSTALL_HINT = `npx --yes --package playwright@${PLAYWRIGHT_VERSION_PIN} -- playwright install chromium`;
+/**
+ * `CODE: detail` — the same prefix convention `web-daemon-service`'s
+ * `failureResponse` parses, reused here so a caller can pass either a bare
+ * reason (the gate) or a coded failure (`WEB_INSTALL_FAILED: …`) and get the
+ * right `code` on the envelope without a second parameter.
+ */
+const CODE_PREFIX_RE = /^([A-Z][A-Z0-9_]{0,63}):\s*/;
+/**
+ * One envelope for the whole tier-3/4 branch (C3): `ok:false`, a code, the
+ * fallback tool, the install command, the op's own arguments, and the two things
+ * a caller must know — the local path was skipped and where the MCP path puts
+ * its screenshots.
+ */
+export function degradedEnvelope(op, reason, tier = 3, opArgs = {}) {
+    const mcpTool = MCP_TOOL_FOR_OP[op];
+    const code = CODE_PREFIX_RE.exec(reason)?.[1] ?? (tier === 4 ? 'WEB_UNAVAILABLE' : 'WEB_DISABLED');
+    const detail = reason.replace(CODE_PREFIX_RE, '') || reason;
+    return {
+        ...fail(`peaks.web.${op}`, code, `peaks web ${op} did not run locally: ${detail}`, { tier, mcpTool, installHint: INSTALL_HINT, args: stringArgs(opArgs) }, nextActions(op, mcpTool)),
+        warnings: [`local browser skipped (${detail})`, MCP_ROOT_DIR_WARNING]
+    };
+}
+/** The op's own string arguments — `selector`, `url` — and nothing else. */
+function stringArgs(opArgs) {
+    const args = {};
+    for (const [key, value] of Object.entries(opArgs)) {
+        if (typeof value === 'string' && value.length > 0) {
+            args[key] = value;
+        }
+    }
+    return args;
+}
+function nextActions(op, mcpTool) {
+    // `install`'s own next action is a RE-run with `--force`: the recovery path
+    // R6 names, and the only thing that helps when the installer exited 0 without
+    // landing the browser (R7).
+    if (op === 'install') {
+        return [
+            'Re-run `peaks web install --force` to re-download the browser',
+            'Or call mcp__playwright__browser_install instead'
+        ];
+    }
+    const install = 'Run `peaks web install` for the local path';
+    // `login` is the one browser op its MCP fallback cannot stand in for: no
+    // `mcp__playwright__*` tool persists a storage state, so naming
+    // `browser_navigate` would send the caller to a dead end for the only verb
+    // whose whole purpose is persistence (S4 R3). The gate is the real recovery.
+    if (op === 'login') {
+        return [
+            'Unset PEAKS_WEB_DISABLED and re-run `peaks web login --profile <name>` — ' +
+                'the MCP fallback cannot save a login profile',
+            install
+        ];
+    }
+    if (mcpTool === '') {
+        return [install];
+    }
+    return [
+        `Call ${mcpTool} directly instead (MCP fallback for \`peaks web ${op}\`; ` +
+            'screenshots taken that way land in the project root)',
+        install
+    ];
+}