peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/web-login-command.js

@@ -0,0 +1,189 @@
+// src/cli/commands/web-login-command.ts
+//
+// `peaks web login --profile <name>` — the only path that persists a login.
+// Split out of `web-lifecycle-commands.ts`; the verb name, its options, the
+// gate-first order, the fold notices and every envelope shape are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { degradedEnvelope } from '../../services/web/web-fallback.js';
+import { isWebDisabled } from '../../services/web/web-install-service.js';
+import { cappedEcho, loginStorageStatePath, resolveProfileName, runHeadedLogin } from '../../services/web/web-login-profile.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+/** The `degradedEnvelope` tier a disabled-web refusal reports (tech-doc §5.1). */
+const WEB_DISABLED_TIER = 3;
+/** What a caller can actually do after a refusal or an unclosed login. */
+const LOGIN_NEXT_ACTIONS = [
+    'Re-run `peaks web login --profile <name>` when the user is ready to log in',
+    'Close the headed browser window when the login is finished — closing it is what saves the session'
+];
+/**
+ * The fold, said out loud on the one path that CANNOT fold (S4 repair, code F5 /
+ * security S5).
+ *
+ * The gate is statement #1 (tech-doc §5.1), so on this path the name was never
+ * validated and never folded — which is exactly why this refusal must not look
+ * like it disagrees with a live run about the profile. It reports what happened
+ * (nothing was folded, this is what was typed) rather than implying a canonical
+ * name was used, and it claims nothing about whether the name would be accepted.
+ * The echo is capped by the same helper the guard uses.
+ */
+function gateFoldNotice(rawProfile) {
+    if (rawProfile === undefined || rawProfile === rawProfile.toLowerCase()) {
+        return [];
+    }
+    return [
+        `--profile ${JSON.stringify(cappedEcho(rawProfile))} was NOT folded: PEAKS_WEB_DISABLED is ` +
+            'checked before the profile name, so this refusal echoes what was typed, not a canonical ' +
+            'profile. A run that gets past the gate lower-cases the name first.'
+    ];
+}
+/** The disabled-web refusal, with the fold notice appended when there is one. */
+function webDisabledLoginEnvelope(rawProfile) {
+    const gateEnvelope = degradedEnvelope('login', 'PEAKS_WEB_DISABLED=1', WEB_DISABLED_TIER, rawProfile === undefined ? {} : { profile: cappedEcho(rawProfile) });
+    return { ...gateEnvelope, warnings: [...gateEnvelope.warnings, ...gateFoldNotice(rawProfile)] };
+}
+function profileRequiredEnvelope() {
+    return fail('peaks.web.login', 'WEB_PROFILE_REQUIRED', '`peaks web login` requires --profile <name>: it is the only verb that persists a login, ' +
+        'and there is no default profile — without a name nothing is written', {}, LOGIN_NEXT_ACTIONS);
+}
+/**
+ * `resolveProfileName`'s canonical name, or the refusal envelope to print.
+ * The helper's own message already begins with the code, and `fail()` puts the
+ * code in front of the message again — strip it, so human output does not read
+ * `WEB_PROFILE_NAME_INVALID: WEB_PROFILE_NAME_INVALID: …`.
+ */
+function resolveLoginProfile(rawProfile) {
+    try {
+        return { profile: resolveProfileName(rawProfile) };
+    }
+    catch (error) {
+        const detail = getErrorMessage(error).replace(/^WEB_PROFILE_NAME_INVALID:\s*/, '');
+        return {
+            refusal: fail('peaks.web.login', 'WEB_PROFILE_NAME_INVALID', detail, {}, LOGIN_NEXT_ACTIONS)
+        };
+    }
+}
+/**
+ * The two sides are deliberately not the same value — the left is what the
+ * caller TYPED (echoed through `cappedEcho`, since it is still caller input),
+ * the right is the canonical name the run uses from here on.
+ */
+function loginFoldWarnings(rawProfile, profile) {
+    return rawProfile === profile
+        ? []
+        : [`--profile ${JSON.stringify(cappedEcho(rawProfile))} resolved to the profile "${profile}"`];
+}
+/** The headed-browser instructions the user reads while the login is open. */
+function announceHeadedLogin(io, profile) {
+    return () => {
+        io.stderr([
+            `peaks web login: a headed browser is open for profile "${profile}" — log in there yourself.`,
+            'Close the browser window when you are done: that is what saves the session, to ' +
+                `${loginStorageStatePath(profile)}.`,
+            'The session is captured while the window is open, so the saved state can be up to a ' +
+                'second older than what you see — finish logging in before you close it.'
+        ].join('\n'));
+    };
+}
+/**
+ * S1's F1. This is the ONLY path on which the runner returns `ok: false` AND a
+ * warning (a login whose context never opened and whose headed browser then
+ * refused to close — a browser nothing can then stop, because `stop` is
+ * daemon-scoped). `fail()` hard-codes `warnings: []`, so the warning is spread
+ * back over it, the shape `degradedEnvelope` uses.
+ */
+function loginFailedEnvelope(command, outcome, foldWarnings) {
+    return {
+        ...fail(command, outcome.code, outcome.message, {}, LOGIN_NEXT_ACTIONS),
+        warnings: [...foldWarnings, ...outcome.warnings]
+    };
+}
+/**
+ * The success envelope — counts, never the values: the file holds live session
+ * cookies and this envelope reaches a terminal (and a transcript).
+ *
+ * R5: a capture that was written but could not be read back is `ok` — the file
+ * did land, so it is not a failure — but it is not a clean success either. The
+ * code is what an ok-only consumer cannot miss.
+ */
+function loginResultEnvelope(command, outcome, foldWarnings) {
+    const envelope = ok(command, {
+        profile: outcome.profile,
+        storageStatePath: outcome.storageStatePath,
+        bytes: outcome.bytes,
+        cookies: outcome.cookies,
+        origins: outcome.origins
+    }, [...foldWarnings, ...outcome.warnings]);
+    return outcome.code === '' ? envelope : { ...envelope, code: outcome.code };
+}
+/**
+ * The catch-all failure envelope. A run that reached `resolveProfileName` knows
+ * the canonical name, so a failure before the browser was even up reports the
+ * fold like every other path (S4 repair, code F5 / security S5).
+ */
+function loginThrewEnvelope(command, error, foldWarnings) {
+    return {
+        ...fail(command, 'WEB_LOGIN_FAILED', `peaks web login failed: ${getErrorMessage(error)}`, {}, LOGIN_NEXT_ACTIONS),
+        warnings: [...foldWarnings]
+    };
+}
+/**
+ * `peaks web login --profile <name>` — the only path that persists a login
+ * (design §2/§5, PRD R7).
+ *
+ * `--profile` is enforced HERE rather than with commander's `requiredOption`,
+ * because `requiredOption` refuses before this handler runs — and then the
+ * `PEAKS_WEB_DISABLED` gate would no longer be statement #1 (tech-doc §5.1,
+ * AC5). A profile-less login refuses without touching the profile root: no
+ * directory, no storage state, no browser.
+ */
+export async function runWebLogin(io, asJson, rawProfile) {
+    const command = 'peaks.web.login';
+    // Declared out here so the CATCH can report it too (S4 repair, security S5 /
+    // code F3): a launch failure happens AFTER the name was resolved, so a run
+    // that dies on `WEB_LAUNCH_FAILED` knows the canonical name just as well as
+    // one that succeeds, and must not be the one path where the fold is silent.
+    let foldWarnings = [];
+    try {
+        if (isWebDisabled(process.env)) {
+            printResult(io, webDisabledLoginEnvelope(rawProfile), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        if (rawProfile === undefined || rawProfile === '') {
+            printResult(io, profileRequiredEnvelope(), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const resolved = resolveLoginProfile(rawProfile);
+        if ('refusal' in resolved) {
+            printResult(io, resolved.refusal, asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const profile = resolved.profile;
+        foldWarnings = loginFoldWarnings(rawProfile, profile);
+        const outcome = await runHeadedLogin({
+            profile,
+            announce: announceHeadedLogin(io, profile)
+        });
+        if (!outcome.ok) {
+            printResult(io, loginFailedEnvelope(command, outcome, foldWarnings), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, loginResultEnvelope(command, outcome, foldWarnings), asJson);
+    }
+    catch (error) {
+        printResult(io, loginThrewEnvelope(command, error, foldWarnings), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWebLoginCommand(web, io) {
+    addJsonOption(web
+        .command('login')
+        .description('Open a HEADED browser so the user can log in themselves, then persist that session to ' +
+        '~/.peaks/web-profiles/<name>/storageState.json. Run it only when the user asks for a ' +
+        'persistent login: it writes live session cookies to disk. --profile is required, and ' +
+        'without it nothing is persisted.')
+        .option('--profile <name>', 'the login profile to persist (required; [a-z0-9._-], 1-64 chars — upper case folds to lower)')).action((options) => runWebLogin(io, options.json === true, options.profile));
+}

package/dist/cli/commands/web-op-payload.d.ts

@@ -0,0 +1,22 @@
+import type { ResultEnvelope } from 'peaks-loop-shared/result';
+import type { WebOp } from '../../services/web/web-protocol.js';
+import { type ProgramIO } from '../cli-helpers.js';
+interface WrappedPayload {
+    readonly data: Record<string, unknown>;
+    /** Raw human-mode stdout, or `null` for verbs whose output is not page content. */
+    readonly human: string | null;
+}
+/**
+ * Wrap the page-controlled part of each verb's payload (AC4 / §6.2) and pick
+ * the bytes that human mode prints verbatim. `shot` is unwrapped: its path and
+ * byte count are ours, not the page's.
+ */
+export declare function wrapPageData(op: WebOp, raw: Record<string, unknown>): WrappedPayload;
+/**
+ * Print the envelope. Failures and `--json` go through `printResult`; a
+ * successful wrapped op in human mode prints its payload RAW, because the
+ * UNTRUSTED delimiters must stay on their own lines (AC4) and AC2 measures the
+ * byte count of exactly this stdout.
+ */
+export declare function emit<T>(io: ProgramIO, result: ResultEnvelope<T>, asJson: boolean, humanPayload: string | null): void;
+export {};

package/dist/cli/commands/web-op-payload.js

@@ -0,0 +1,89 @@
+// src/cli/commands/web-op-payload.ts
+//
+// How one `peaks web` op's daemon payload becomes stdout: the per-verb wrap of
+// the page-controlled fields, the human-mode renderer for `metrics`, and the
+// printer that keeps the UNTRUSTED delimiters on their own lines. Split out of
+// `web-commands.ts`; every branch and every byte cap is unchanged.
+import { capText, MAX_TEXT_BYTES } from '../../services/web/bounded-output.js';
+import { wrapUntrusted, WRAPPED_OPS } from '../../services/web/untrusted-envelope.js';
+import { printResult } from '../cli-helpers.js';
+import { count, text } from './web-command-shared.js';
+/**
+ * Wrap the page-controlled part of each verb's payload (AC4 / §6.2) and pick
+ * the bytes that human mode prints verbatim. `shot` is unwrapped: its path and
+ * byte count are ours, not the page's.
+ */
+export function wrapPageData(op, raw) {
+    if (!WRAPPED_OPS.has(op)) {
+        return { data: raw, human: null };
+    }
+    switch (op) {
+        case 'open': {
+            const title = wrapUntrusted(text(raw['title']));
+            return { data: { url: wrapUntrusted(text(raw['url'])), title }, human: title };
+        }
+        case 'text': {
+            const value = wrapUntrusted(text(raw['text']));
+            return {
+                data: {
+                    text: value,
+                    truncated: raw['truncated'] === true,
+                    droppedBytes: count(raw['droppedBytes'])
+                },
+                human: value
+            };
+        }
+        case 'snap': {
+            const snapshot = wrapUntrusted(text(raw['snapshot']));
+            return {
+                data: {
+                    snapshot,
+                    droppedNodes: count(raw['droppedNodes']),
+                    depthCapped: raw['depthCapped'] === true,
+                    nodeCapped: raw['nodeCapped'] === true,
+                    truncated: raw['truncated'] === true,
+                    droppedBytes: count(raw['droppedBytes'])
+                },
+                human: snapshot
+            };
+        }
+        case 'click': {
+            const result = wrapUntrusted(text(raw['result']));
+            return { data: { result }, human: result };
+        }
+        case 'metrics': {
+            // The rendered lines come from the daemon's payload, so they are capped
+            // here as well as at the producer: this is the boundary that reaches
+            // stdout, and the ceiling must hold whatever the daemon sends.
+            const metrics = wrapUntrusted(capText(renderMetrics(raw), MAX_TEXT_BYTES).text);
+            return { data: { metrics }, human: metrics };
+        }
+        default:
+            return { data: raw, human: null };
+    }
+}
+/**
+ * Print the envelope. Failures and `--json` go through `printResult`; a
+ * successful wrapped op in human mode prints its payload RAW, because the
+ * UNTRUSTED delimiters must stay on their own lines (AC4) and AC2 measures the
+ * byte count of exactly this stdout.
+ */
+export function emit(io, result, asJson, humanPayload) {
+    if (!result.ok || asJson || humanPayload === null) {
+        printResult(io, result, asJson);
+        return;
+    }
+    io.stdout(humanPayload);
+    for (const warning of result.warnings) {
+        io.stderr(`warning: ${warning}`);
+    }
+}
+/** `available: false` is reported as such — never as fabricated zeros (C4). */
+function renderMetrics(raw) {
+    if (raw['available'] !== true) {
+        return `available: false\nreason: ${text(raw['reason']) || 'unavailable'}`;
+    }
+    const values = (raw['values'] ?? {});
+    const lines = Object.entries(values).map(([key, value]) => `${key}: ${String(value)}`);
+    return lines.length > 0 ? lines.join('\n') : 'available: true';
+}

package/dist/cli/commands/web-op-refusals.d.ts

@@ -0,0 +1,37 @@
+import { fail } from 'peaks-loop-shared/result';
+import type { WebOp } from '../../services/web/web-protocol.js';
+/**
+ * What a caller can do after a refused `--profile` — the same sentence `login`
+ * gives, because it is the same mistake and the same verb fixes it.
+ */
+export declare const PROFILE_NEXT_ACTIONS: string[];
+/**
+ * The resolver's own message begins with the code, and `fail()` puts the code in
+ * front of the message again — strip it, so human output does not read
+ * `WEB_PROFILE_NAME_INVALID: WEB_PROFILE_NAME_INVALID: …` (the `login` verb does
+ * the same).
+ */
+export declare function profileRefusal(error: unknown): string;
+/** Every daemon warning, capped and wrapped. Empty entries are dropped. */
+export declare function wrapDiagnostics(values: readonly string[]): string[];
+/**
+ * Our own static sentence, then the daemon's own words as a wrapped, capped
+ * block. The daemon's `nextActions` are folded into that block rather than
+ * forwarded: `printResult` prints `nextActions` to STDOUT as `next: …`, the
+ * channel the notice calls instruction, and the daemon's text is not ours to
+ * promote there.
+ */
+export declare function failureMessage(op: WebOp, message: unknown, nextActions: readonly string[]): string;
+/**
+ * A daemon-supplied `code` is printed on the envelope's first line, so only a
+ * protocol-shaped identifier is accepted; anything else falls back to ours.
+ */
+export declare function safeDaemonCode(value: unknown): string;
+/** The unusable-daemon envelope: a named code, or the generic op failure. */
+export declare function daemonFailureEnvelope(input: {
+    readonly op: WebOp;
+    readonly command: string;
+    readonly code: string;
+    readonly message: unknown;
+    readonly nextActions: readonly string[];
+}): ReturnType<typeof fail>;

package/dist/cli/commands/web-op-refusals.js

@@ -0,0 +1,73 @@
+// src/cli/commands/web-op-refusals.ts
+//
+// How a `peaks web` op refuses: the diagnostic channel, the daemon failure
+// envelope, and the refused-`--profile` pair of sentences. Split out of
+// `web-commands.ts`; every wrap, every cap and every sentence is unchanged.
+import { fail } from 'peaks-loop-shared/result';
+import { capText, MAX_TEXT_BYTES } from '../../services/web/bounded-output.js';
+import { wrapUntrusted } from '../../services/web/untrusted-envelope.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { text } from './web-command-shared.js';
+/**
+ * What a caller can do after a refused `--profile` — the same sentence `login`
+ * gives, because it is the same mistake and the same verb fixes it.
+ */
+export const PROFILE_NEXT_ACTIONS = [
+    'Re-run with a name matching [a-z0-9._-], 1-64 chars',
+    'Or run `peaks web login --profile <name>` to create that profile'
+];
+/**
+ * The resolver's own message begins with the code, and `fail()` puts the code in
+ * front of the message again — strip it, so human output does not read
+ * `WEB_PROFILE_NAME_INVALID: WEB_PROFILE_NAME_INVALID: …` (the `login` verb does
+ * the same).
+ */
+export function profileRefusal(error) {
+    return getErrorMessage(error).replace(/^WEB_PROFILE_NAME_INVALID:\s*/, '');
+}
+/**
+ * A daemon- or page-derived diagnostic is DATA, never an instruction: it is
+ * byte-capped and wrapped before it can reach `message` or `warnings` (AC4 /
+ * R4 — the envelope must cover the diagnostic channel, not only `data`).
+ *
+ * This matters because Playwright's own error messages embed the matched
+ * elements' HTML, so a page with two elements matching a selector can put
+ * arbitrary text on a channel the CLI would otherwise print verbatim to stdout.
+ */
+function wrapDiagnostic(raw) {
+    const capped = capText(text(raw), MAX_TEXT_BYTES).text;
+    return capped === '' ? '' : wrapUntrusted(capped);
+}
+/** Every daemon warning, capped and wrapped. Empty entries are dropped. */
+export function wrapDiagnostics(values) {
+    return values.map((value) => wrapDiagnostic(value)).filter((value) => value !== '');
+}
+/**
+ * Our own static sentence, then the daemon's own words as a wrapped, capped
+ * block. The daemon's `nextActions` are folded into that block rather than
+ * forwarded: `printResult` prints `nextActions` to STDOUT as `next: …`, the
+ * channel the notice calls instruction, and the daemon's text is not ours to
+ * promote there.
+ */
+export function failureMessage(op, message, nextActions) {
+    const detail = [text(message), ...nextActions.map((action) => text(action))]
+        .filter((line) => line !== '')
+        .join('\n');
+    const wrapped = wrapDiagnostic(detail);
+    return wrapped === ''
+        ? `peaks web ${op} failed in the daemon`
+        : `peaks web ${op} failed in the daemon\n${wrapped}`;
+}
+/**
+ * A daemon-supplied `code` is printed on the envelope's first line, so only a
+ * protocol-shaped identifier is accepted; anything else falls back to ours.
+ */
+export function safeDaemonCode(value) {
+    return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value)
+        ? value
+        : 'WEB_OP_FAILED';
+}
+/** The unusable-daemon envelope: a named code, or the generic op failure. */
+export function daemonFailureEnvelope(input) {
+    return fail(input.command, input.code, failureMessage(input.op, input.message, input.nextActions), {}, []);
+}

package/dist/cli/commands/web-op-runner.d.ts

@@ -0,0 +1,14 @@
+import type { WebOp } from '../../services/web/web-protocol.js';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * Resolve the session, ensure a daemon, invoke one op, and emit exactly one
+ * envelope. `WRAPPED_OPS` is applied here, after the byte caps the daemon
+ * already imposed, so the UNTRUSTED markers are never themselves truncated.
+ *
+ * The `PEAKS_WEB_DISABLED` gate is the FIRST thing that happens (tech-doc §5.1
+ * step 1, AC5). Before the session lookup, so a project with no binding still
+ * gets `WEB_DISABLED` rather than `NO_SESSION`; before `ensureDaemon`, so
+ * nothing is spawned and no lock is taken; and therefore before anything that
+ * could touch the browser cache.
+ */
+export declare function runWebOp(io: ProgramIO, op: WebOp, args: Record<string, unknown>, asJson: boolean): Promise<void>;

package/dist/cli/commands/web-op-runner.js

@@ -0,0 +1,166 @@
+// src/cli/commands/web-op-runner.ts
+//
+// `runWebOp` — resolve the session, ensure a daemon, invoke one op, and emit
+// exactly one envelope. Split out of `web-commands.ts`, where this one function
+// had reached 117 lines; the gates, their order and every envelope are
+// unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { ensureDaemon } from '../../services/web/daemon-supervisor.js';
+import { degradedEnvelope } from '../../services/web/web-fallback.js';
+import { isWebDisabled } from '../../services/web/web-install-service.js';
+import { cappedEcho, resolveProfileName } from '../../services/web/web-login-profile.js';
+import { WebDaemonClient } from '../../services/web/web-client.js';
+import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { noSession, resolveSession } from './web-command-shared.js';
+import { emit, wrapPageData } from './web-op-payload.js';
+import { daemonFailureEnvelope, PROFILE_NEXT_ACTIONS, profileRefusal, safeDaemonCode, wrapDiagnostics } from './web-op-refusals.js';
+/** A browser op is user-visible latency; 30 s is generous but bounded. */
+const OP_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the session, ensure a daemon, invoke one op, and emit exactly one
+ * envelope. `WRAPPED_OPS` is applied here, after the byte caps the daemon
+ * already imposed, so the UNTRUSTED markers are never themselves truncated.
+ *
+ * The `PEAKS_WEB_DISABLED` gate is the FIRST thing that happens (tech-doc §5.1
+ * step 1, AC5). Before the session lookup, so a project with no binding still
+ * gets `WEB_DISABLED` rather than `NO_SESSION`; before `ensureDaemon`, so
+ * nothing is spawned and no lock is taken; and therefore before anything that
+ * could touch the browser cache.
+ */
+export async function runWebOp(io, op, args, asJson) {
+    const command = `peaks.web.${op}`;
+    // Declared outside the try so the CATCH reports the fold too (S4's F5/S5 rule
+    // for `login`, applied here): a run that dies after the name was resolved
+    // knows the canonical name just as well as a successful one.
+    let foldWarnings = [];
+    try {
+        if (isWebDisabled(process.env)) {
+            printResult(io, webDisabledEnvelope(op, args), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const profile = resolveWebProfile(command, args);
+        foldWarnings = profile.warnings;
+        if (profile.envelope !== null) {
+            printResult(io, profile.envelope, asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, withFold(noSession(command), foldWarnings), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const response = await callWebDaemon(op, profile.args, session.projectRoot, session.sessionId);
+        if (!response.ok || response.data === null) {
+            const refusal = daemonRefusal({ op, command, response, opArgs: profile.args, foldWarnings });
+            printResult(io, refusal, asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const wrapped = wrapPageData(op, response.data);
+        emit(io, ok(command, wrapped.data, [...foldWarnings, ...wrapDiagnostics(response.warnings)]), asJson, wrapped.human);
+    }
+    catch (error) {
+        printResult(io, webOpFailure(op, command, error, foldWarnings), asJson);
+        process.exitCode = 1;
+    }
+}
+/** The `WEB_OP_FAILED` envelope for a throw anywhere in the run, fold included. */
+function webOpFailure(op, command, error, foldWarnings) {
+    return withFold(daemonFailureEnvelope({
+        op,
+        command,
+        code: 'WEB_OP_FAILED',
+        message: redactSensitiveErrorMessage(getErrorMessage(error)),
+        nextActions: []
+    }), foldWarnings);
+}
+/**
+ * The `PEAKS_WEB_DISABLED` gate's envelope. The gate is statement #1, so a
+ * `--profile` has NOT been through the resolver yet and is still unbounded
+ * caller text; `degradedEnvelope` carries every string arg into the payload, so
+ * it is capped here — the same cap the `login` gate applies, for the same reason
+ * (S1's bounded output is a property of the envelope, not only of stdout).
+ */
+function webDisabledEnvelope(op, args) {
+    return degradedEnvelope(op, 'PEAKS_WEB_DISABLED=1', 3, cappedProfileArg(args));
+}
+/**
+ * The unusable-daemon envelope. The daemon no longer downloads (R3), so "the
+ * browser is not installed" arrives as a refusal: it is AC5's tier-3 branch,
+ * not an opaque op failure — the caller must be handed the same envelope (MCP
+ * tool, install command, screenshot consequence) that the gate produces.
+ */
+function daemonRefusal(input) {
+    const code = safeDaemonCode(input.response.code);
+    if (code === 'WEB_INSTALL_REQUIRED') {
+        const reason = `WEB_INSTALL_REQUIRED: ${input.response.message ?? ''}`;
+        return withFold(degradedEnvelope(input.op, reason, 3, input.opArgs), input.foldWarnings);
+    }
+    return withFold(daemonFailureEnvelope({
+        op: input.op,
+        command: input.command,
+        code,
+        message: input.response.message,
+        nextActions: input.response.nextActions
+    }), input.foldWarnings);
+}
+/** Prepend the fold notice to an envelope's warnings; never rewrite them away. */
+function withFold(envelope, warnings) {
+    return warnings.length === 0
+        ? envelope
+        : { ...envelope, warnings: [...warnings, ...envelope.warnings] };
+}
+/** The `PEAKS_WEB_DISABLED` gate's args: a `--profile` still raw, so still capped. */
+function cappedProfileArg(args) {
+    return typeof args['profile'] === 'string'
+        ? { ...args, profile: cappedEcho(args['profile']) }
+        : args;
+}
+/**
+ * A caller-supplied `--profile` is validated HERE, before anything is sent, and
+ * the daemon runs the SAME resolver again on the payload it receives (a value
+ * off the wire is not trusted). `resolveProfileName` folds to lower case, so the
+ * canonical name is what travels, and the fold is reported rather than silent —
+ * the contract `login` honours.
+ */
+function resolveWebProfile(command, args) {
+    if (typeof args['profile'] !== 'string') {
+        return { args, warnings: [], envelope: null };
+    }
+    const typed = args['profile'];
+    let profile;
+    try {
+        profile = resolveProfileName(typed);
+    }
+    catch (error) {
+        return {
+            args,
+            warnings: [],
+            envelope: fail(command, 'WEB_PROFILE_NAME_INVALID', profileRefusal(error), {}, PROFILE_NEXT_ACTIONS)
+        };
+    }
+    const warnings = profile === typed
+        ? []
+        : [`--profile ${JSON.stringify(cappedEcho(typed))} resolved to the profile "${profile}"`];
+    return { args: { ...args, profile }, warnings, envelope: null };
+}
+/**
+ * Ensure the daemon and invoke one op. The daemon reads `projectRoot` back from
+ * `daemon.json` — the record it itself wrote — and that round-trip is the only
+ * path that survives the macOS `/var` <-> `/private/var` symlink: the writer's
+ * prefix may not match `projectRoot` resolved from `process.cwd()` (the kernel
+ * resolves symlinks on `chdir`), and the integration test asserts on that exact
+ * round-tripped value.
+ */
+async function callWebDaemon(op, args, projectRoot, sessionId) {
+    const info = await ensureDaemon(projectRoot, sessionId);
+    return new WebDaemonClient(info).call(op, {
+        ...args,
+        dispatchId: process.env['PEAKS_DISPATCH_ID'] ?? 'current',
+        projectRoot: info.projectRoot,
+        sessionId
+    }, OP_TIMEOUT_MS);
+}

package/dist/cli/commands/web-status-command.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function runWebStatus(io: ProgramIO, asJson: boolean): Promise<void>;
+export declare function registerWebStatusCommand(web: Command, io: ProgramIO): void;

package/dist/cli/commands/web-status-command.js

@@ -0,0 +1,32 @@
+// src/cli/commands/web-status-command.ts
+//
+// `peaks web status` — this session's daemon instances (live / orphaned /
+// stale), read from the filesystem and the loopback port, never from the daemon.
+// Split out of `web-lifecycle-commands.ts`; the verb name, its options and the
+// envelope shape are unchanged.
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { buildStatusReport } from '../../services/web/web-status-report.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { noSession, resolveSession } from './web-command-shared.js';
+export async function runWebStatus(io, asJson) {
+    const command = 'peaks.web.status';
+    try {
+        const session = resolveSession();
+        if (session === null) {
+            printResult(io, noSession(command), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok(command, await buildStatusReport(session.projectRoot, session.sessionId)), asJson);
+    }
+    catch (error) {
+        printResult(io, fail(command, 'WEB_STATUS_FAILED', `peaks web status failed: ${getErrorMessage(error)}`, {}, []), asJson);
+        process.exitCode = 1;
+    }
+}
+export function registerWebStatusCommand(web, io) {
+    addJsonOption(web
+        .command('status')
+        .description("Report this session's web daemon instances (live / orphaned / stale). Works with no " +
+        'daemon running and never starts one.')).action((options) => runWebStatus(io, options.json === true));
+}

package/dist/cli/commands/web-stop-command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+/**
+ * Stop the daemon and clear its records. `stopped` counts the daemons whose
+ * process is confirmed GONE by return — not merely the ones we signalled — so a
+ * caller that checks the process table right after this returns is not racing
+ * the teardown (AC6).
+ */
+export declare function runWebStop(io: ProgramIO, asJson: boolean): Promise<void>;
+export declare function registerWebStopCommand(web: Command, io: ProgramIO): void;