@repo-os/repoos 0.5.69 → 0.5.71

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "b009708e237c666064aee174b838afdb790721e2fdef67d53c2317781afd5073",
-  "version": "0.5.69",
+  "hash": "eacca03dfc8be35b1f9d1238a9ac18cbdaf50c0d39cab898568df9fc589d514a",
+  "version": "0.5.71",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-10-11T01:57:56.517Z"
+  "generatedAt": "2026-10-13T19:22:09.840Z"
 }

package/dist/cli/help.js

@@ -12,7 +12,7 @@ import { c } from "./colors.js";
 import { table, termWidth, visibleWidth, wrap } from "./layout.js";
 import { NEW_FLAG_HELP, UPDATE_FLAG_HELP, flagSummary, flagUsageTokens } from "./task-flags.js";
 /** Commands whose own argument parser already handles `--help`. */
-export const SELF_HELP_COMMANDS = new Set(["support", "tunnel", "shot", "uninstall"]);
+export const SELF_HELP_COMMANDS = new Set(["support", "tunnel", "shot", "uninstall", "override"]);
 const GROUPS = [
     {
         name: "Setup",
@@ -88,9 +88,9 @@ const GROUPS = [
             },
             {
                 name: "message",
-                usage: 'message <id> "<text>" [--json] [--port N]',
-                desc: "Send a follow-up to the task agent (POST /api/tasks/:id/message)",
-                flags: "--json · --port",
+                usage: 'message <id> "<text>" [--now] [--json] [--port N]',
+                desc: "Send a follow-up to the task agent; queues while busy, --now interrupts the turn and delivers immediately (POST /api/tasks/:id/message)",
+                flags: "--now · --json · --port",
             },
             {
                 name: "review",
@@ -107,7 +107,7 @@ const GROUPS = [
             {
                 name: "override",
                 usage: "override <id> [--cli <name>] [--model <model>] [--json] [--port N]",
-                desc: "Set per-task engineer overrides (PATCH /api/tasks/:id)",
+                desc: "Set per-task engineer overrides (PATCH /api/tasks/:id). --help prints the agent-driver budget allowlist",
                 flags: "--cli · --model · --json · --port",
             },
             {

package/dist/cli/task-flags.js

@@ -33,6 +33,14 @@ export const NEW_FLAG_HELP = {
     paths: { value: "a,b", desc: "Files the task touches, e.g. src/a.ts,src/b.ts" },
     body: { value: '"..."|-', desc: "Task body; `-` reads it from stdin" },
     shots: { value: '"<JSON list>"|-', desc: "Declare the ## Shots section (validated JSON)" },
+    screenshot: {
+        value: "path.png",
+        desc: "Attach a local image to ## Screenshots (repeatable)",
+    },
+    caption: {
+        value: '"..."',
+        desc: "Alt text for a single --screenshot image",
+    },
 };
 /** Every flag `repoos update` accepts, in help order. */
 export const UPDATE_FLAG_HELP = {
@@ -52,6 +60,14 @@ export const UPDATE_FLAG_HELP = {
     questions: { value: '"Q1\\nQ2"', desc: "Open questions for the human (newline or JSON list)" },
     "clear-questions": { desc: "Clear the recorded questions" },
     shots: { value: '"<JSON list>"|-', desc: "Declare the ## Shots section (validated JSON)" },
+    screenshot: {
+        value: "path.png",
+        desc: "Attach a local image to ## Screenshots (repeatable)",
+    },
+    caption: {
+        value: '"..."',
+        desc: "Alt text for a single --screenshot image",
+    },
     section: { value: '"heading"', desc: "Replace/create one ## section (pair with --section-body)" },
     "section-body": { value: '"..."|-', desc: "Body for --section; `-` reads it from stdin" },
     force: { desc: "Allow a --body replace that drops spec headings" },

package/dist/commands/control-api.js

@@ -6,7 +6,7 @@ import { pollUntil, RepoOsApi, RepoOsApiError, resolveControlPlaneBase, } from "
 import { effectiveEngineerFromApi } from "../cli/effective-from-api.js";
 import { HANDOFF_DEADLINE_MS } from "../server/handoff.js";
 function parseCommonFlags(args) {
-    const opts = { json: false, wait: false };
+    const opts = { json: false, wait: false, now: false };
     const rest = [];
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
@@ -14,6 +14,8 @@ function parseCommonFlags(args) {
             opts.json = true;
         else if (a === "--wait")
             opts.wait = true;
+        else if (a === "--now")
+            opts.now = true;
         else if (a === "--port") {
             const p = args[++i];
             const n = Number(p);
@@ -29,6 +31,21 @@ function parseCommonFlags(args) {
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+/**
+ * Print the agent-driver budget allowlist so a driver can choose an allowed
+ * pair before running `repoos override` (#0764). Reads the local config file —
+ * no server round-trip.
+ */
+function printBudgetAllowlist(config) {
+    const rows = config.budget?.allowlist ?? [];
+    if (!rows.length) {
+        console.log(c.dim("  Budget allowlist: (empty — agent drivers are not restricted to any agent+model pair)"));
+        return;
+    }
+    console.log(c.dim("  Budget allowlist for agent drivers — allowed agent + model pairs:"));
+    for (const row of rows)
+        console.log(`  · ${row.cli} + ${row.models.join(", ")}`);
+}
 function printErr(message) {
     console.error(c.red("  ✗ ") + message);
 }
@@ -133,18 +150,30 @@ export async function cmdMessage(args) {
     const id = rest[0];
     const text = rest.slice(1).join(" ").trim();
     if (!id || !text) {
-        printErr('Usage: repoos message <id> "<text>" [--json] [--port N]');
+        printErr('Usage: repoos message <id> "<text>" [--now] [--json] [--port N]');
         return 1;
     }
     const api = new RepoOsApi({ port: opts.port });
     try {
         await ensureServer(api);
-        const data = await api.requestOk("POST", `/api/tasks/${id}/message`, { text });
+        const data = await api.requestOk("POST", `/api/tasks/${id}/message`, {
+            text,
+            ...(opts.now ? { now: true } : {}),
+        });
         if (opts.json)
             printJson(data);
+        else if (data?.queued) {
+            const why = data.now
+                ? (data.reason ?? "agent still busy after the interrupt")
+                : "agent busy — delivers when the turn ends";
+            console.log(c.green("  ✓ ") + c.dim(`message queued to #${id} (${why})`));
+        }
+        else if (data?.deliveredNow) {
+            const how = data.interrupted ? " (interrupted the running turn)" : " (agent was idle)";
+            console.log(c.green("  ✓ ") + c.dim(`message delivered now to #${id}${how}`));
+        }
         else {
-            const status = data?.queued ? "queued" : "sent";
-            console.log(c.green("  ✓ ") + c.dim(`message ${status} to #${id}`));
+            console.log(c.green("  ✓ ") + c.dim(`message sent to #${id}`));
         }
         return 0;
     }
@@ -290,10 +319,14 @@ export async function cmdOverride(args) {
         printErr(error);
         return 1;
     }
-    const id = rest[0];
-    if (!id) {
-        printErr("Usage: repoos override <id> [--cli <name>] [--model <model>] [--json] [--port N]");
-        return 1;
+    const wantsHelp = rest.includes("--help") || rest.includes("-h");
+    const id = rest.find((a) => !a.startsWith("-"));
+    if (!id || wantsHelp) {
+        const { config } = resolveControlPlaneBase({ port: opts.port });
+        console.log(c.cyan("Usage:") +
+            " repoos override <id> [--cli <name>] [--model <model>] [--json] [--port N]");
+        printBudgetAllowlist(config);
+        return wantsHelp ? 0 : 1;
     }
     let cli;
     let model;

package/dist/commands/init.js

@@ -253,6 +253,15 @@ a candidate merge. Do not erase a task's branch metadata to force this path.
   must use those same RepoOS CLI commands or HTTP API endpoints for task body,
   metadata, and status changes; it must never edit task Markdown directly.
 - **Never** deploy to production without human sign-off.
+- **Attach the human's screenshots to the task.** When a task comes from a
+  request that included images, pass every one with
+  \`repoos new "<title>" --screenshot path.png\` (repeat \`--screenshot\` per
+  image) or \`repoos update <id> --screenshot path.png\` (\`--caption "..."\`
+  labels a single image). The command stores the files under the gitignored
+  \`${workDir}/.attachments/<id>/\` and writes the task's \`## Screenshots\`
+  section itself — never \`git add\` the pixels, never hand-copy them, never
+  edit that section by hand. Say in your reply which images you attached.
+  An image the human gave you is an image that lands on the task.
 - Keep frontmatter tidy; \`repoos\` will normalize key order on write.
 - One task = one focused worktree.
 - **Never invent evidence.** Do not fabricate device sessions, live API results,
@@ -452,6 +461,16 @@ function previewTargetRows(areas) {
         `# areas = ${areaList}`,
         `# command = "bun run dev --port {port} --host {host}"`,
         `# readyTimeoutMs = 240000                 # raise for a command that also builds`,
+        "",
+        "# No dev server (native macOS, iOS/Android, desktop)? Declare a command",
+        "# capture target instead — the command renders image files into",
+        "# REPOOS_SHOT_DIR and RepoOS collects them as the task's evidence shots.",
+        "# [[shot.targets]]",
+        `# name = "macOS app"`,
+        `# areas = ${areaList}`,
+        `# paths = ["Sources/**"]                  # changed files that make this the target`,
+        `# command = "swift test --filter RenderShots"`,
+        `# outputGlob = ["*.png"]`,
     ].join("\n");
 }
 const ENV_EXAMPLE = `# Copy to .env and fill in what you need — .env is gitignored, this file is

package/dist/commands/screenshot-flag.d.ts

@@ -0,0 +1,36 @@
+import type { RepoOSConfig, Task } from "../core/types.js";
+import { type ScreenshotMeta } from "../server/attachments.js";
+/** One local image read from disk, ready for `saveScreenshot`. */
+export interface ScreenshotInput {
+    name: string;
+    mime: string;
+    /** Base64-encoded file bytes. */
+    data: string;
+}
+/**
+ * Read and validate one local image file. Validation mirrors the upload route:
+ * the extension must map to an allowed MIME type, the file must exist and be a
+ * regular file, be non-empty, and be within the size limit. Never throws —
+ * problems come back as `{ error }` with the offending path named.
+ */
+export declare function readScreenshotFile(filePath: string): ScreenshotInput | {
+    error: string;
+};
+/** Read every `--screenshot` path, failing fast on the first bad one. */
+export declare function readScreenshotFiles(paths: string[]): {
+    inputs: ScreenshotInput[];
+} | {
+    error: string;
+};
+/**
+ * Store every local image on a task and extend its `## Screenshots` section in
+ * one patch (numbering continues from whatever the task already has). The
+ * images are gitignored storage under `work/.attachments/<id>/`; only the
+ * markdown links land in the task file. Reports the first failure rather than
+ * leaving a partial attach silent, and never half-writes the body.
+ */
+export declare function attachScreenshots(config: RepoOSConfig, task: Task, paths: string[], caption?: string): {
+    metas: ScreenshotMeta[];
+} | {
+    error: string;
+};

package/dist/commands/screenshot-flag.js

@@ -0,0 +1,99 @@
+/**
+ * `--screenshot` support for `repoos new` / `repoos update` (#0763).
+ *
+ * An agent that is handed images in chat needs a way to attach them when it
+ * creates or updates the task, without hand-copying files into
+ * `work/.attachments/<id>/` and guessing at the `## Screenshots` markdown. This
+ * module is the one place that turns local image paths into stored attachments:
+ * it validates each file against the SAME allowlist and size limit the HTTP
+ * upload route uses ({@link saveScreenshot}), stores them through the same
+ * storage helper, and extends the task body through the same
+ * `patchTaskFile({ addScreenshots })` path the API route uses. No storage logic
+ * is duplicated here.
+ *
+ * The write is local, exactly like the rest of `repoos new` / `repoos update`:
+ * it works with no server running, and equally against a running server (which
+ * picks the file change up through its work-dir watcher). A caller that wants
+ * the server to have the task in the same request can post `attachments` to
+ * `POST /api/tasks` instead — both paths land in the same storage.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname } from "node:path";
+import { MAX_SCREENSHOT_BYTES, mimeForExtension, saveScreenshot, } from "../server/attachments.js";
+import { patchTaskFile } from "../server/write.js";
+/** How many bytes are too many, as human words for the error message. */
+function maxMb() {
+    return Math.round(MAX_SCREENSHOT_BYTES / 1024 / 1024);
+}
+/**
+ * Read and validate one local image file. Validation mirrors the upload route:
+ * the extension must map to an allowed MIME type, the file must exist and be a
+ * regular file, be non-empty, and be within the size limit. Never throws —
+ * problems come back as `{ error }` with the offending path named.
+ */
+export function readScreenshotFile(filePath) {
+    if (!filePath || filePath.trim() === "") {
+        return { error: "empty --screenshot path" };
+    }
+    if (!existsSync(filePath)) {
+        return { error: `image not found: ${filePath}` };
+    }
+    const stat = statSync(filePath);
+    if (!stat.isFile()) {
+        return { error: `not a file: ${filePath}` };
+    }
+    const mime = mimeForExtension(filePath);
+    if (!mime) {
+        return {
+            error: `unsupported image type "${extname(filePath) || filePath}" — supported: .png, .jpg, .jpeg, .gif, .webp, .avif, .bmp`,
+        };
+    }
+    const bytes = readFileSync(filePath);
+    if (bytes.length === 0) {
+        return { error: `image is empty: ${filePath}` };
+    }
+    if (bytes.length > MAX_SCREENSHOT_BYTES) {
+        return { error: `image is too large (max ${maxMb()} MB): ${filePath}` };
+    }
+    return { name: filePath, mime, data: bytes.toString("base64") };
+}
+/** Read every `--screenshot` path, failing fast on the first bad one. */
+export function readScreenshotFiles(paths) {
+    const inputs = [];
+    for (const path of paths) {
+        const result = readScreenshotFile(path);
+        if ("error" in result)
+            return { error: result.error };
+        inputs.push(result);
+    }
+    return { inputs };
+}
+/** Trim a caption into safe markdown alt text, or null when blank. */
+function normalizeCaption(caption) {
+    const trimmed = (caption ?? "").replace(/[[\]]/g, "").replace(/\s+/g, " ").trim();
+    return trimmed || null;
+}
+/**
+ * Store every local image on a task and extend its `## Screenshots` section in
+ * one patch (numbering continues from whatever the task already has). The
+ * images are gitignored storage under `work/.attachments/<id>/`; only the
+ * markdown links land in the task file. Reports the first failure rather than
+ * leaving a partial attach silent, and never half-writes the body.
+ */
+export function attachScreenshots(config, task, paths, caption) {
+    const read = readScreenshotFiles(paths);
+    if ("error" in read)
+        return { error: read.error };
+    const label = normalizeCaption(caption);
+    const metas = [];
+    for (const input of read.inputs) {
+        const saved = saveScreenshot(config, task, input);
+        if ("error" in saved)
+            return { error: saved.error };
+        metas.push(label ? { ...saved, name: label } : saved);
+    }
+    if (metas.length === 0)
+        return { metas };
+    patchTaskFile(config, task.absPath, { addScreenshots: metas });
+    return { metas };
+}

package/dist/commands/shot.d.ts

@@ -11,6 +11,10 @@ interface CmdShotOptions {
         height: number;
     };
     fullPage: boolean;
+    /** Extra env for a command capture target (#0769), from repeated `--env KEY=VAL`. */
+    env?: Record<string, string>;
+    /** Per-entry output glob for a command capture target (#0769), from `--glob`. */
+    glob?: string;
     /** Set when an argument is unknown or malformed; cmdShot prints and exits. */
     error?: string;
     /** Set for `-h`/`--help`; cmdShot prints usage and exits 0. */
@@ -38,6 +42,12 @@ export interface CliShotPlanInput {
     matchedGlobs: ReadonlyMap<string, string[]>;
     /** Targets whose matched files are docs content only (#0603). */
     docsContentOnly: ReadonlySet<string>;
+    /** Command capture target names (#0761) — no route, run a command instead. */
+    commandTargets?: ReadonlySet<string>;
+    /** Extra env for a command capture target (#0769), from `--env KEY=VAL`. */
+    env?: Record<string, string>;
+    /** Per-entry output glob for a command capture target (#0769), from `--glob`. */
+    glob?: string;
 }
 /** The plan plus the visible notes `cmdShot` prints alongside it. */
 export interface CliShotPlan {

package/dist/commands/shot.js

@@ -15,15 +15,18 @@
  * overrides; area resolution is the fallback. Missing Playwright is a clean
  * skip with install advice, not a crash.
  */
-import { basename } from "node:path";
+import { basename, extname, join } from "node:path";
+import { rmSync } from "node:fs";
 import { c } from "../cli/colors.js";
 import { findRepoRoot, loadConfig, mainCheckoutRoot, resolveServePort } from "../core/config.js";
 import { changedPathsVsBase, currentBranch } from "../core/git.js";
 import { createRepoOS } from "../core/repoos.js";
 import { shotCapturePageUrl } from "../core/shot-fixtures.js";
 import { captureShotPage } from "../core/shot-page.js";
+import { runShotCommand, slugName } from "../core/shot-command.js";
+import { shotsDir } from "../server/shots.js";
 import { buildCapturePlan, parseShotPlan, provenanceCaption, } from "../core/shot-plan.js";
-import { describeTargetPathMatches, formatTargetList, resolveShotTargets, } from "../core/shot-targets.js";
+import { describeShotTargetPathMatches, describeTargetPathMatches, formatTargetList, resolveShotTargets, shotTargetByName, } from "../core/shot-targets.js";
 import { readServeLocks } from "./status.js";
 import { readLocalCliToken } from "../server/local-token.js";
 import { launchWebkit } from "./ui-harness.js";
@@ -74,6 +77,24 @@ export function parseShotArgs(args) {
                 return opts;
             opts.selector = v;
         }
+        else if (a === "--env") {
+            const v = value(a);
+            if (v === undefined)
+                return opts;
+            const eq = v.indexOf("=");
+            const key = eq > 0 ? v.slice(0, eq) : "";
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+                opts.error = `--env expects KEY=VALUE with a valid variable name, got "${v}"`;
+                return opts;
+            }
+            opts.env = { ...opts.env, [key]: v.slice(eq + 1) };
+        }
+        else if (a === "--glob") {
+            const v = value(a);
+            if (v === undefined)
+                return opts;
+            opts.glob = v;
+        }
         else if (a === "--task") {
             const v = value(a);
             if (v === undefined)
@@ -160,8 +181,11 @@ export function buildCliShotPlan(input) {
     const built = buildCapturePlan(input.targets, declared.shots, {
         matchedGlobs: input.matchedGlobs,
         docsContentOnly: input.docsContentOnly,
+        ...(input.commandTargets ? { commandTargets: input.commandTargets } : {}),
         route: input.route,
         selector: input.selector,
+        ...(input.env ? { env: input.env } : {}),
+        ...(input.glob ? { glob: input.glob } : {}),
     });
     return {
         entries: built.entries,
@@ -239,11 +263,12 @@ async function uploadShot(port, taskId, token, input) {
             headers: cliHeaders(token, true),
             body: JSON.stringify({
                 target: input.target,
-                route: input.route,
+                ...(input.route ? { route: input.route } : {}),
+                ...(input.command ? { command: input.command } : {}),
                 ...(input.label ? { label: input.label } : {}),
                 ...(input.provenance ? { provenance: input.provenance } : {}),
-                name: input.target,
-                mime: "image/png",
+                name: input.name ?? input.target,
+                mime: input.mime ?? "image/png",
                 data: input.data,
                 ...(input.warnings?.length ? { warnings: input.warnings } : {}),
             }),
@@ -287,6 +312,14 @@ export async function cmdShot(args) {
   target's paths; diffs touching just tests or task notes stand down with a
   visible "shots: skipped — no UI change to capture" note instead.
 
+  A repo with no dev server (a native macOS, iOS/Android or desktop app) can
+  declare a command capture target in repoos.toml as a [[shot.targets]] row —
+  a command that renders image files into REPOOS_SHOT_DIR. --target <name>
+  selects one, and its images are stored like any other shot; no browser is
+  needed. --env KEY=VALUE and --glob narrow what such a target renders and which
+  produced files are kept (a declared ## Shots entry can carry the same as
+  "env"/"args"/"glob"). See user-docs/configuration.md.
+
   An explicit <route> or --selector replaces the declared list outright, and
   applies to every resolved target: declared entries carry steps, a highlight
   and a label written for their own route, so they are never re-pointed at a
@@ -300,6 +333,9 @@ export async function cmdShot(args) {
   Flags:
     --target <name>    Preview target to capture (overrides path/area resolution)
     --selector <css>   Capture one element instead of the whole page
+    --env KEY=VAL      (command target) pass an env var to the capture command;
+                       repeat per variable, e.g. --env DIVOT_SNAPSHOT_ONLY=worldclock
+    --glob <glob>      (command target) collect only produced files matching this glob
     --task <id>        Task to shoot (defaults to the current worktree's branch)
     --base <ref>       Base branch for changed-path resolution (default "main")
     --wait <ms>        Settle time after load before capturing (default 900)
@@ -309,7 +345,7 @@ export async function cmdShot(args) {
     }
     if (opts.error) {
         console.error(c.red("  ✗ ") + opts.error);
-        console.error(c.dim("    usage: repoos shot [<route|url>] [--target <name>] [--selector <css>]"));
+        console.error(c.dim("    usage: repoos shot [<route|url>] [--target <name>] [--selector <css>] [--env K=V] [--glob <glob>]"));
         return 1;
     }
     const cwdRoot = findRepoRoot();
@@ -355,7 +391,7 @@ export async function cmdShot(args) {
             console.error(c.red("  ✗ ") + `Base ref "${opts.base}" is not a commit — cannot resolve changed paths.`);
             return 1;
         }
-        const resolution = resolveShotTargets(worktreeConfig.preview, task.area, changed, opts.target);
+        const resolution = resolveShotTargets(worktreeConfig.preview, task.area, changed, opts.target, worktreeConfig.shot);
         if (resolution.names.length === 0) {
             console.error(c.red("  ✗ ") + (resolution.reason ?? "No preview target resolved."));
             if (resolution.detected.length > 0) {
@@ -386,6 +422,12 @@ export async function cmdShot(args) {
             if (match.contentOnly)
                 docsContentOnly.add(match.target);
         }
+        for (const match of describeShotTargetPathMatches(worktreeConfig.shot, changed)) {
+            matchedGlobs.set(match.target, match.globs);
+            if (match.contentOnly)
+                docsContentOnly.add(match.target);
+        }
+        const commandTargets = new Set((worktreeConfig.shot?.targets ?? []).map((t) => t.name));
         // #0610: the requested route/selector is part of the plan, not a separate
         // candidate that lost to the fallback's `/`.
         const built = buildCliShotPlan({
@@ -395,6 +437,9 @@ export async function cmdShot(args) {
             targets,
             matchedGlobs,
             docsContentOnly,
+            commandTargets,
+            ...(opts.env ? { env: opts.env } : {}),
+            ...(opts.glob ? { glob: opts.glob } : {}),
         });
         for (const error of built.declaredErrors) {
             console.error(c.yellow("  · ") + `declared shot list: ${error}`);
@@ -431,29 +476,34 @@ export async function cmdShot(args) {
             `RepoOS server is not reachable on ${baseUrl}. Start it with \`repoos serve\`.`);
         return 1;
     }
+    const commandTargets = new Set((worktreeConfig.shot?.targets ?? []).map((t) => t.name));
+    const webPlan = plan.filter((e) => !commandTargets.has(e.target));
+    const commandPlan = plan.filter((e) => commandTargets.has(e.target));
     let browser;
     let context;
     const saved = [];
     try {
-        try {
-            browser = await launchWebkit();
-            context = await browser.newContext({ serviceWorkers: "block" });
-        }
-        catch (err) {
-            const msg = err.message;
-            if (isShotCaptureUnavailable(err)) {
-                console.error(c.yellow("  · ") + "Screenshot capture skipped — Playwright/WebKit unavailable");
-                console.error(c.dim(`    ${msg.split("\n")[0]}`));
-                console.error(c.dim(`    ${INSTALL_ADVICE}`));
+        if (webPlan.length > 0) {
+            try {
+                browser = await launchWebkit();
+                context = await browser.newContext({ serviceWorkers: "block" });
             }
-            else {
-                console.error(c.red("  ✗ ") + `could not launch the browser: ${msg.split("\n")[0]}`);
+            catch (err) {
+                const msg = err.message;
+                if (isShotCaptureUnavailable(err)) {
+                    console.error(c.yellow("  · ") + "Screenshot capture skipped — Playwright/WebKit unavailable");
+                    console.error(c.dim(`    ${msg.split("\n")[0]}`));
+                    console.error(c.dim(`    ${INSTALL_ADVICE}`));
+                }
+                else {
+                    console.error(c.red("  ✗ ") + `could not launch the browser: ${msg.split("\n")[0]}`);
+                }
+                return 1;
             }
-            return 1;
         }
         let currentTarget;
         let currentPreviewUrl = "";
-        for (const entry of plan) {
+        for (const entry of webPlan) {
             // Only one preview runs per task, so a different target must replace
             // the running one before it can start (#0379/#0271). Same-target
             // entries reuse the running preview — no restart, no churn.
@@ -467,26 +517,27 @@ export async function cmdShot(args) {
                 currentPreviewUrl = started.url.replace(/\/$/, "");
                 currentTarget = entry.target;
             }
-            const pageUrl = absolute ? entry.route : shotCapturePageUrl(currentPreviewUrl, entry);
+            const route = entry.route ?? "/";
+            const pageUrl = absolute ? route : shotCapturePageUrl(currentPreviewUrl, { ...entry, route });
             const page = (await context.newPage());
             let png;
             const warnings = [];
             try {
                 await page.setViewportSize(opts.viewport);
                 png = await captureShotPage(page, pageUrl, entry, { waitMs: opts.waitMs, fullPage: opts.fullPage }, {
-                    onHighlightMiss: (selector, route) => {
-                        warnings.push(`highlight ${selector} matched nothing on ${route}`);
+                    onHighlightMiss: (selector, r) => {
+                        warnings.push(`highlight ${selector} matched nothing on ${r}`);
                         console.error(c.yellow("  · ") +
-                            `highlight "${selector}" matched nothing on ${route} — capture went ahead unhighlighted`);
+                            `highlight "${selector}" matched nothing on ${r} — capture went ahead unhighlighted`);
                     },
-                    onSelectorMiss: (selector, route) => {
-                        warnings.push(`selector ${selector} matched nothing on ${route}`);
+                    onSelectorMiss: (selector, r) => {
+                        warnings.push(`selector ${selector} matched nothing on ${r}`);
                         console.error(c.yellow("  · ") +
-                            `selector "${selector}" matched nothing on ${route} — capture used the whole window`);
+                            `selector "${selector}" matched nothing on ${r} — capture used the whole window`);
                     },
-                    onStepMiss: (message, route) => {
-                        warnings.push(`${message} on ${route}`);
-                        console.error(c.yellow("  · ") + `${message} on ${route} — capture went ahead`);
+                    onStepMiss: (message, r) => {
+                        warnings.push(`${message} on ${r}`);
+                        console.error(c.yellow("  · ") + `${message} on ${r} — capture went ahead`);
                     },
                 });
             }
@@ -499,7 +550,7 @@ export async function cmdShot(args) {
             await page.close();
             const uploaded = await uploadShot(port, task.id, token, {
                 target: entry.target,
-                route: entry.route.startsWith("/") ? normalizedRoute(entry.route) : entry.route,
+                route: route.startsWith("/") ? normalizedRoute(route) : route,
                 ...(entry.label ? { label: entry.label } : {}),
                 provenance: provenanceCaption(entry.provenance),
                 data: png.toString("base64"),
@@ -519,6 +570,52 @@ export async function cmdShot(args) {
             console.log(c.green("  ✔ ") +
                 `${entry.target}${entry.highlight ? " · highlighted" : ""}${entry.label ? ` – ${entry.label}` : ""} → ${c.cyan(uploaded.shot.path)} ${c.dim(`(${Math.round(png.length / 1024)} KB)`)}`);
         }
+        for (const entry of commandPlan) {
+            const target = shotTargetByName(worktreeConfig.shot, entry.target);
+            if (!target) {
+                console.error(c.red("  ✗ ") + `command capture target "${entry.target}" is not configured`);
+                return 1;
+            }
+            const outputDir = join(shotsDir(worktreeRoot, worktreeConfig.workDir, task.id), "cmd", slugName(entry.target));
+            const outcome = runShotCommand(target, worktreeRoot, outputDir, {
+                ...(entry.env ? { env: entry.env } : {}),
+                ...(entry.args ? { args: entry.args } : {}),
+                ...(entry.glob ? { outputGlob: [entry.glob] } : {}),
+            });
+            if (outcome.status !== "captured") {
+                console.error(c.yellow("  · ") + `shots: ${outcome.status} — ${outcome.reason}`);
+                continue;
+            }
+            for (const msg of outcome.warnings) {
+                console.error(c.yellow("  · ") + msg);
+            }
+            for (const file of outcome.files) {
+                const uploaded = await uploadShot(port, task.id, token, {
+                    target: entry.target,
+                    command: "command",
+                    ...(entry.label ? { label: entry.label } : {}),
+                    provenance: provenanceCaption(entry.provenance),
+                    name: `${entry.target}-${basename(file.name, extname(file.name))}`,
+                    mime: file.mime,
+                    data: file.data.toString("base64"),
+                });
+                if (!uploaded.ok) {
+                    console.error(c.red("  ✗ ") + `storing the shot failed: ${uploaded.error}`);
+                    return 1;
+                }
+                saved.push({
+                    target: entry.target,
+                    ...(entry.label ? { label: entry.label } : {}),
+                    file: uploaded.shot.name,
+                    path: uploaded.shot.path,
+                    url: uploaded.shot.url,
+                });
+                console.log(c.green("  ✔ ") +
+                    `${entry.target}${entry.label ? ` – ${entry.label}` : ""} → ${c.cyan(uploaded.shot.path)} ${c.dim(`(${Math.round(file.data.length / 1024)} KB)`)}`);
+            }
+            // The raw command output is transient — the server now owns the bytes.
+            rmSync(outputDir, { recursive: true, force: true });
+        }
         if (saved.length === 0) {
             console.error(c.yellow("  · ") + "No shots captured.");
             return 1;