peaks-loop 4.0.36 → 4.0.37

package/dist/cli/commands/job-commands.js

@@ -1,4 +1,5 @@
 // src/cli/commands/job-commands.ts
+import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
 import { fail, ok } from 'peaks-loop-shared/result';
@@ -18,6 +19,30 @@ function projectRoot(opts) {
     // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
     return opts.project ?? process.cwd();
 }
+/**
+ * D6: every job subcommand resolves a job root, so every one of them must be
+ * able to name the session that holds the job. Same precedence as the rest of
+ * the CLI (`peaks sub-agent dispatch`, `peaks web *`, `peaks share *`), except
+ * that job state has no "unknown-sid" location to land in — an unresolvable
+ * session is an error, not a silent fallback.
+ */
+const SESSION_ID_HELP = 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback: NO_ACTIVE_SESSION error)';
+/**
+ * The session (a direct child of `<project>/.peaks/_runtime/`) that holds
+ * `jobId`, or null. Only used to explain a miss: a job that lives in another
+ * session must be reported by name so the caller can re-run with --session-id.
+ */
+function findSessionHoldingJob(project, jobId) {
+    const runtimeDir = join(project, '.peaks', '_runtime');
+    if (!existsSync(runtimeDir))
+        return null;
+    for (const entry of readdirSync(runtimeDir, { withFileTypes: true })) {
+        if (entry.isDirectory() && existsSync(join(runtimeDir, entry.name, 'job', jobId, 'state.json'))) {
+            return entry.name;
+        }
+    }
+    return null;
+}
 /**
  * Resolves the on-disk root for Job state files.
  *
@@ -27,20 +52,50 @@ function projectRoot(opts) {
  * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
  * compute the canonical root here (per-call) so the store can stay layout-agnostic.
  *
- * Resolution order:
+ * Resolution order (D6 — a job must stay addressable while the single per-project
+ * `.peaks/_runtime/session.json` binding points at another session):
  * 1. `--session-id` flag (explicit override)
- * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-code
- * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ * 2. `PEAKS_SESSION_ID` env var
+ * 3. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json`
+ * 4. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ *
+ * When `jobId` is passed and it is absent from the resolved session, the thrown
+ * error names the session that does hold it (if any), instead of leaving the
+ * caller with a bare "no state for <job> at <other-sid>" path.
  */
-function resolveJobStateRoot(opts) {
+function resolveJobStateRoot(opts, jobId) {
     const project = projectRoot(opts);
-    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    const sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
     if (!sessionId) {
         throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-code session via peaks workspace init');
     }
     const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    if (jobId && !existsSync(join(rootDir, jobId, 'state.json'))) {
+        const other = findSessionHoldingJob(project, jobId);
+        throw new Error(other
+            ? `JOB_NOT_IN_SESSION: no job "${jobId}" in session "${sessionId}"; it lives in session "${other}" — re-run with --session-id ${other}`
+            : `JOB_NOT_IN_SESSION: no job "${jobId}" in session "${sessionId}" (and no other session under .peaks/_runtime/ has it)`);
+    }
     return { rootDir, sessionId, projectRoot: project };
 }
+/**
+ * D7: slices are keyed `slice-NNN`, but `peaks job init --slice-list "S1,…"`
+ * takes labels, so the natural string to pass back to `--slice-id` is that same
+ * label. Resolve an exact sliceId OR an exact label to the canonical sliceId;
+ * anything else is a hard error listing the valid ids, so a mistyped
+ * `slice-04` can never be accepted as a silent no-op that leaves the slice
+ * pending.
+ */
+function resolveSliceId(store, jobId, sliceId) {
+    const slices = store.load(jobId).slices;
+    const hit = slices.find((sl) => sl.sliceId === sliceId || sl.label === sliceId);
+    if (hit)
+        return { sliceId: hit.sliceId };
+    return {
+        message: `no slice "${sliceId}" in job ${jobId}; valid ids: ${slices.map((sl) => `${sl.sliceId} (${sl.label})`).join(', ')}`,
+        validSliceIds: slices.map((sl) => sl.sliceId),
+    };
+}
 export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
     const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-code Step 0.8+)');
     job
@@ -51,14 +106,14 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .option('--exit-policy <strict|best-effort>', 'strict')
         .option('--main-loop-strategy <single|rotating>', 'rotating')
         .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
-        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
         const project = projectRoot(opts);
-        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > canonical session binding > FAIL.
         // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
         // a random UUID would scatter state across dirs and break resume/auto-compact.
-        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        let sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
         if (!sessionId) {
             return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, [
                 'Re-run with --session-id <sid>',
@@ -105,9 +160,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .requiredOption('--job-id <jid>')
         .option('--watch', 'poll every 3s')
         .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const s = orch.status(opts.jobId);
         if (opts.watch) {
@@ -134,9 +190,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
     // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
     job.command('rotate-now')
         .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
         const r = await rotation.rotateNow(opts.jobId);
         printResult(io, ok('rotate-now', r), opts);
@@ -146,9 +203,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .requiredOption('--job-id <jid>')
         .requiredOption('--batch-id <bid>')
         .option('--force')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir), async () => ({ batchId: opts.batchId }));
         const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
         printResult(io, ok('subagent-cleanup', r), opts);
     });
@@ -161,6 +219,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .requiredOption('--state <done|failed|skipped>')
         .option('--commit-sha <sha>')
         .option('--reason <text>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
         const parsed = JobCheckpointInputSchema.safeParse({
@@ -170,15 +229,25 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         });
         if (!parsed.success)
             return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
-        const jobRoot = resolveJobStateRoot(opts);
+        const jobRoot = resolveJobStateRoot(opts, opts.jobId);
         const store = new JobStateStore(jobRoot.rootDir);
+        // D7: `--slice-id` accepts the canonical `slice-NNN` or the slice's label
+        // ("S1"); an id that matches no slice is rejected here, BEFORE any write,
+        // so progress.json is never touched by a checkpoint that matched nothing.
+        const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
+        if ('message' in slice) {
+            return printResult(io, fail('checkpoint', 'SLICE_NOT_FOUND', slice.message, {
+                jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, validSliceIds: slice.validSliceIds,
+            }, ['Re-run with one of the valid slice ids']), opts);
+        }
+        const sliceId = slice.sliceId;
         const orch = new JobOrchestrator(store);
         // 2026-09-03-codegraph-autorefresh: set on --state done so the ok
         // envelope carries a non-blocking `codegraph` result; null for
         // failed/skipped (no slice-complete boundary).
         let codegraph = null;
         if (parsed.data.state === 'done') {
-            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
             // v3.1.2: after each --state done, mirror slice progress to
             // .peaks/_runtime/<sessionId>/job/<jid>/progress.json so the
             // next LLM turn (or peaks code gate-step-08 hook) can read it.
@@ -203,12 +272,12 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
             }
         }
         else if (parsed.data.state === 'skipped') {
-            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId, reason: parsed.data.reason });
         }
         else {
-            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId, reason: parsed.data.reason });
         }
-        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state, codegraph }), opts);
+        printResult(io, ok('checkpoint', { sliceId, status: parsed.data.state, codegraph }), opts);
     });
     addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
     job
@@ -216,6 +285,7 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .requiredOption('--job-id <jid>')
         .requiredOption('--slice-id <rid>')
         .requiredOption('--reason <text>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
         const parsed = JobBlockInputSchema.safeParse({
@@ -224,18 +294,27 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         });
         if (!parsed.success)
             return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+        // D7 (same silent no-op as checkpoint): resolve label → sliceId, reject a
+        // miss before any write.
+        const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
+        if ('message' in slice) {
+            return printResult(io, fail('block', 'SLICE_NOT_FOUND', slice.message, {
+                jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, validSliceIds: slice.validSliceIds,
+            }, ['Re-run with one of the valid slice ids']), opts);
+        }
         const orch = new JobOrchestrator(store);
-        await orch.blockSlice(parsed.data);
-        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+        await orch.blockSlice({ ...parsed.data, sliceId: slice.sliceId });
+        printResult(io, ok('block', { blocked: slice.sliceId, reason: parsed.data.reason }), opts);
     });
     addJsonOption(job.commands.find(c => c.name() === 'block'));
     job
         .command('continue')
         .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const r = orch.continueNow(opts.jobId);
         printResult(io, ok('continue', r), opts);
@@ -244,9 +323,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
     job
         .command('resume')
         .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const s = orch.status(opts.jobId);
         printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
@@ -261,11 +341,12 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .description('v3.1.2: read the on-disk slice progress mirror (.peaks/_runtime/<sid>/job/<jid>/progress.json). ' +
         'Returns { jobId, done, total, currentSlice, lastCommitSha, updatedAt }.')
         .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .option('--allow-missing', 'return done=0/total=0 envelope instead of failing when progress.json is absent')
         .action(async (opts) => {
         try {
-            const jobRoot = resolveJobStateRoot(opts);
+            const jobRoot = resolveJobStateRoot(opts, opts.jobId);
             const sessId = jobRoot.sessionId;
             const project = projectRoot(opts);
             const progress = opts.allowMissing === true
@@ -292,9 +373,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
     job
         .command('handoff')
         .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .option('--project <repo>')
         .action(async (opts) => {
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
         const orch = new JobOrchestrator(store);
         const s = orch.status(opts.jobId);
         printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
@@ -305,10 +387,10 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         .description('Read the slice\'s rd/karpathy-review.md and decide whether to downgrade a block gateAction to warn (slice 2026-07-30-karpathy-cost-self-review).')
         .requiredOption('--review-file <path>', 'path to rd/karpathy-review.md (or its .json sibling if the file is JSON)')
         .option('--project <repo>')
-        .option('--session-id <sid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
         .action(async (opts) => {
         const project = projectRoot(opts);
-        const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        const sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
         if (!sessionId) {
             return printResult(io, fail('karpathy-cost-check', 'NO_ACTIVE_SESSION', 'karpathy-cost-check requires --session-id (or an active peaks-code session)', { project }, [
                 'Re-run with --session-id <sid>',

package/dist/cli/commands/scan-commands.js

@@ -198,7 +198,7 @@ export function registerScanCommands(program, io) {
     });
     addJsonOption(scan
         .command('file-size')
-        .description('Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First")')
+        .description('Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First"; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)')
         .requiredOption('--project <path>', 'target project root')
         .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')
         .option('--threshold <n>', `line count threshold (default: ${DEFAULT_FILE_SIZE_THRESHOLD})`)).action((options) => {

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

@@ -0,0 +1,28 @@
+/**
+ * `peaks web open|text|snap|click|shot|metrics` — the S1 command surface.
+ *
+ * Layer rule (tech-doc §1.1): this file owns commander wiring, option parsing,
+ * `--json`, `printResult` and `process.exitCode`. It owns ZERO path
+ * construction and ZERO Playwright calls — those live in `src/services/web/*`.
+ *
+ * The envelope is built once, in `runWebOp`, and that is also the single place
+ * `WRAPPED_OPS` is applied — one place, not six. Every page- or daemon-derived
+ * string that leaves this process (payload, diagnostic, warning) is capped and
+ * wrapped here, because this is the boundary the model actually reads.
+ */
+import type { Command } from 'commander';
+import type { WebOp } from '../../services/web/web-protocol.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWebCommands(program: Command, io: ProgramIO): void;
+/**
+ * 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-commands.js

@@ -0,0 +1,327 @@
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { capText, MAX_TEXT_BYTES } from '../../services/web/bounded-output.js';
+import { ensureDaemon } from '../../services/web/daemon-supervisor.js';
+import { wrapUntrusted, WRAPPED_OPS } from '../../services/web/untrusted-envelope.js';
+import { WebDaemonClient } from '../../services/web/web-client.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 { addJsonOption, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { registerWebLifecycleCommands } from './web-lifecycle-commands.js';
+/** A browser op is user-visible latency; 30 s is generous but bounded. */
+const OP_TIMEOUT_MS = 30_000;
+/**
+ * The option text names the read-only half out loud: a caller who browses with a
+ * profile must not assume the profile was refreshed by it.
+ */
+const PROFILE_OPTION_DESCRIPTION = 'navigate with a saved login profile (`peaks web login --profile <name>`): [a-z0-9._-], ' +
+    '1-64 chars, upper case folds to lower. The profile is READ-ONLY here — this run loads it ' +
+    'and never writes it back, so browser activity is not saved into it.';
+const WEB_VERBS = [
+    {
+        name: 'open',
+        op: 'open',
+        description: 'Navigate the dispatch browser context to <url>. With --profile, the page loads that ' +
+            'saved login.',
+        argument: { name: '<url>', description: 'absolute URL to load' },
+        takesProfile: true,
+        toArgs: (positional, profile) => ({
+            url: positional[0] ?? '',
+            ...(profile === undefined ? {} : { profile })
+        })
+    },
+    {
+        name: 'text',
+        op: 'text',
+        description: 'Return the visible text of the page (or of [selector]), byte-capped.',
+        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'snap',
+        op: 'snap',
+        description: 'Return a pruned ARIA snapshot of the page (or of [selector]), byte-capped.',
+        argument: { name: '[selector]', description: 'CSS selector (default: body)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'click',
+        op: 'click',
+        description: 'Click the element matching <selector> in the dispatch browser context.',
+        argument: { name: '<selector>', description: 'CSS selector to click' },
+        toArgs: (positional) => ({ selector: positional[0] ?? '' })
+    },
+    {
+        name: 'shot',
+        op: 'shot',
+        description: 'Screenshot the page (or [selector]) into the session web/ directory.',
+        argument: { name: '[selector]', description: 'CSS selector (default: full page)' },
+        toArgs: (positional) => ({ selector: positional[0] })
+    },
+    {
+        name: 'metrics',
+        op: 'metrics',
+        description: 'Return Core Web Vitals for the dispatch page, or why they are unavailable.',
+        argument: null,
+        toArgs: () => ({})
+    }
+];
+export function registerWebCommands(program, io) {
+    const web = program
+        .command('web')
+        .description('Bounded, isolated browser access driven by a pinned local Playwright. This is the primary ' +
+        'browser path; `peaks playwright` is kept as the MCP fallback. Every artifact lands under ' +
+        '.peaks/_runtime/<sessionId>/web/ — never in the project root.');
+    for (const verb of WEB_VERBS) {
+        const takesArgument = verb.argument !== null;
+        let command = web.command(verb.name).description(verb.description);
+        if (verb.argument !== null) {
+            command = command.argument(verb.argument.name, verb.argument.description);
+        }
+        if (verb.takesProfile === true) {
+            command = command.option('--profile <name>', PROFILE_OPTION_DESCRIPTION);
+        }
+        command = addJsonOption(command);
+        // Commander calls the handler as (…declaredArgs, options, command), so the
+        // options object sits at the declared-argument count — not at the end.
+        command.action(async (...actionArgs) => {
+            const options = actionArgs[takesArgument ? 1 : 0];
+            const rawArgument = actionArgs[0];
+            const positional = takesArgument
+                ? [typeof rawArgument === 'string' ? rawArgument : undefined]
+                : [];
+            await runWebOp(io, verb.op, verb.toArgs(positional, options?.profile), options?.json === true);
+        });
+    }
+    registerWebLifecycleCommands(web, io);
+}
+/**
+ * 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)) {
+            // 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).
+            const gateArgs = typeof args['profile'] === 'string'
+                ? { ...args, profile: cappedEcho(args['profile']) }
+                : args;
+            printResult(io, degradedEnvelope(op, 'PEAKS_WEB_DISABLED=1', 3, gateArgs), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        // 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.
+        let profile;
+        if (typeof args['profile'] === 'string') {
+            const typed = args['profile'];
+            try {
+                profile = resolveProfileName(typed);
+            }
+            catch (error) {
+                printResult(io, fail(command, 'WEB_PROFILE_NAME_INVALID', profileRefusal(error), {}, PROFILE_NEXT_ACTIONS), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (profile !== typed) {
+                foldWarnings = [
+                    `--profile ${JSON.stringify(cappedEcho(typed))} resolved to the profile "${profile}"`
+                ];
+            }
+        }
+        const opArgs = profile === undefined ? args : { ...args, profile };
+        const projectRoot = resolveCanonicalProjectRoot(process.cwd());
+        const sessionId = getCurrentSessionId(projectRoot);
+        if (sessionId === null) {
+            printResult(io, withFold(fail(command, 'NO_SESSION', 'No peaks session is bound to this project root', {}, [
+                'Bind a session first (the LLM runs `peaks workspace init` on your behalf)'
+            ]), foldWarnings), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const info = await ensureDaemon(projectRoot, sessionId);
+        const response = await new WebDaemonClient(info).call(op, { ...opArgs, dispatchId: dispatchId(), projectRoot, sessionId }, OP_TIMEOUT_MS);
+        if (!response.ok || response.data === null) {
+            const code = safeDaemonCode(response.code);
+            // 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.
+            printResult(io, code === 'WEB_INSTALL_REQUIRED'
+                ? withFold(degradedEnvelope(op, `WEB_INSTALL_REQUIRED: ${response.message ?? ''}`, 3, opArgs), foldWarnings)
+                : withFold(fail(command, code, failureMessage(op, response.message, response.nextActions), {}, []), foldWarnings), 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, withFold(fail(command, 'WEB_OP_FAILED', failureMessage(op, redactSensitiveErrorMessage(getErrorMessage(error)), []), {}, []), foldWarnings), asJson);
+        process.exitCode = 1;
+    }
+}
+/**
+ * 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.
+ */
+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).
+ */
+function profileRefusal(error) {
+    return getErrorMessage(error).replace(/^WEB_PROFILE_NAME_INVALID:\s*/, '');
+}
+/** 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] };
+}
+/**
+ * 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. */
+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.
+ */
+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.
+ */
+function safeDaemonCode(value) {
+    return typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value) ? value : 'WEB_OP_FAILED';
+}
+/**
+ * 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.
+ */
+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.
+ */
+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';
+}
+function dispatchId() {
+    return process.env['PEAKS_DISPATCH_ID'] ?? 'current';
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function count(value) {
+    return typeof value === 'number' ? value : 0;
+}