@repo-os/repoos 0.5.60 → 0.5.62

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "cf6db5df542f115cccfac9cdfcfbd0703be0f1fa5628e248d1aa85ff48bf2c09",
-  "version": "0.5.60",
+  "hash": "0264ffb217828c3c1e53be5b58abbe310ff9b749bb8bd2c916d4d22e6dd164ac",
+  "version": "0.5.62",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-30T14:26:04.444Z"
+  "generatedAt": "2026-10-02T12:12:44.891Z"
 }

package/dist/commands/certify.d.ts

@@ -5,6 +5,8 @@ export interface CertifyCliArgs {
     missingCli: boolean;
     /** Explicit binary path — skips PATH resolution and probes this binary directly. */
     binary: string | null;
+    /** Model for the probe's runs (`--model <id>`), or null for the harness default. */
+    model: string | null;
 }
 export declare function parseCertifyArgs(argv: string[]): CertifyCliArgs;
 export declare function cmdCertify(argv: string[]): Promise<void>;

package/dist/commands/certify.js

@@ -22,9 +22,11 @@ export function parseCertifyArgs(argv) {
     const json = argv.includes("--json");
     const binaryIdx = argv.indexOf("--binary");
     const binary = binaryIdx !== -1 ? (argv[binaryIdx + 1] ?? null) : null;
-    const positional = argv.filter((a, i) => !a.startsWith("--") && argv[i - 1] !== "--binary");
+    const modelIdx = argv.indexOf("--model");
+    const model = modelIdx !== -1 ? (argv[modelIdx + 1] ?? null) : null;
+    const positional = argv.filter((a, i) => !a.startsWith("--") && argv[i - 1] !== "--binary" && argv[i - 1] !== "--model");
     const cli = positional[0] ?? null;
-    return { cli, yes, json, missingCli: !cli, binary };
+    return { cli, yes, json, missingCli: !cli, binary, model };
 }
 /** Locate the live manifest file on disk (src or dist). */
 function findManifestPath() {
@@ -56,7 +58,7 @@ function saveManifest(path, manifest) {
     writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
 }
 export async function cmdCertify(argv) {
-    const { cli, yes, json: asJson, missingCli, binary } = parseCertifyArgs(argv);
+    const { cli, yes, json: asJson, missingCli, binary, model } = parseCertifyArgs(argv);
     if (missingCli || !cli) {
         console.error(c.red("  repoos certify needs a harness id, e.g. `repoos certify opencode`."));
         console.error(c.dim("    Use --binary <path> to probe a specific binary instead of PATH resolution."));
@@ -99,6 +101,7 @@ export async function cmdCertify(argv) {
         cli,
         mode: "live",
         ...(binary ? { bin: binary } : {}),
+        ...(model ? { model } : {}),
     });
     if (asJson) {
         console.log(JSON.stringify(result, null, 2));

package/dist/commands/doctor.d.ts

@@ -8,6 +8,8 @@ export interface DoctorCliArgs {
     probe: string | null;
     /** True when `--probe` was given without a value (or before another flag). */
     probeMissingValue: boolean;
+    /** Model for the probe's runs (`--model <id>`), or null for the harness default. */
+    model: string | null;
     /** Explicit binary path for the probe — bypasses PATH resolution. */
     binary: string | null;
 }
@@ -38,5 +40,5 @@ export interface DoctorRenderOptions {
  */
 export declare function formatDoctor(report: DoctorReport, opts?: DoctorRenderOptions): string;
 export declare function renderDoctor(report: DoctorReport, opts?: DoctorRenderOptions): void;
-/** `repoos doctor [--json] [--verbose] [--probe <cli>] [--yes]` */
+/** `repoos doctor [--json] [--verbose] [--probe <cli> [--model <id>]] [--yes]` */
 export declare function cmdDoctor(argv: string[]): Promise<void>;

package/dist/commands/doctor.js

@@ -1,5 +1,5 @@
 /**
- * `repoos doctor [--json] [--verbose] [--probe <cli>] [--yes]` — human and
+ * `repoos doctor [--json] [--verbose] [--probe <cli> [--model <id>]] [--yes]` — human and
  * machine rendering of the readiness preflight built in `src/core/doctor.ts`.
  *
  * The command adds no diagnostic logic of its own: it runs the engine, prints
@@ -31,15 +31,17 @@ export function parseDoctorArgs(argv) {
     const yes = argv.includes("--yes");
     const binaryIdx = argv.indexOf("--binary");
     const binary = binaryIdx !== -1 ? (argv[binaryIdx + 1] ?? null) : null;
+    const modelIdx = argv.indexOf("--model");
+    const model = modelIdx !== -1 ? (argv[modelIdx + 1] ?? null) : null;
     const probeArg = argv.indexOf("--probe");
     if (probeArg === -1) {
-        return { json, verbose, yes, probe: null, probeMissingValue: false, binary };
+        return { json, verbose, yes, probe: null, probeMissingValue: false, model, binary };
     }
     const value = argv[probeArg + 1];
     if (!value || value.startsWith("--")) {
-        return { json, verbose, yes, probe: null, probeMissingValue: true, binary };
+        return { json, verbose, yes, probe: null, probeMissingValue: true, model, binary };
     }
-    return { json, verbose, yes, probe: value, probeMissingValue: false, binary };
+    return { json, verbose, yes, probe: value, probeMissingValue: false, model, binary };
 }
 function severityColor(severity, text) {
     if (severity === "pass")
@@ -153,16 +155,16 @@ export function formatDoctor(report, opts = {}) {
 export function renderDoctor(report, opts = {}) {
     console.log(formatDoctor(report, opts));
 }
-/** `repoos doctor [--json] [--verbose] [--probe <cli>] [--yes]` */
+/** `repoos doctor [--json] [--verbose] [--probe <cli> [--model <id>]] [--yes]` */
 export async function cmdDoctor(argv) {
-    const { json: asJson, yes, probe: probeCli, probeMissingValue, binary, verbose, } = parseDoctorArgs(argv);
+    const { json: asJson, yes, probe: probeCli, probeMissingValue, binary, model, verbose, } = parseDoctorArgs(argv);
     if (probeMissingValue) {
         console.error(c.red("  repoos doctor --probe needs a harness id, e.g. `--probe opencode`."));
         process.exitCode = 1;
         return;
     }
     if (probeCli) {
-        await cmdProbe(probeCli, { asJson, yes, binary });
+        await cmdProbe(probeCli, { asJson, yes, binary, model });
         return;
     }
     try {
@@ -228,6 +230,7 @@ async function cmdProbe(cli, opts) {
             cli,
             mode: "live",
             ...(opts.binary ? { bin: opts.binary } : {}),
+            ...(opts.model ? { model: opts.model } : {}),
         });
         if (opts.asJson) {
             console.log(JSON.stringify(result, null, 2));

package/dist/commands/init.js

@@ -255,6 +255,37 @@ RepoOS validates the request against your live run, starts the preview from
 your worktree, probes it server-side, and records the preview URL and probe
 result in your task transcript. The preview is reaped when the task leaves
 active/review.
+
+## Declaring evidence shots (## Shots)
+
+A task body may carry a \`## Shots\` section with a fenced JSON list of capture
+entries (see \`src/core/shot-plan.ts\`). Each entry has \`target\`, \`route\`, an
+optional \`selector\` (element crop — the exception), an optional \`highlight\`
+CSS selector (outlines changed elements), a \`label\`, and optional ordered
+\`steps\` (click/fill/wait, plain CSS selectors). Use \`repoos update <id>
+--shots '<JSON list>'\` to declare it (the CLI validates the JSON and writes the
+fenced section) without touching the rest of the body — a full \`--body\` replace that drops
+Problem / Desired UX / Acceptance criteria / Notes for AI is refused unless
+\`--force\` is passed.
+
+For tabbed views (e.g. Agents), prefer \`?tab=<id>\` routes
+(\`/agents?tab=detected\`) over click steps to reach the right tab, and always
+set \`highlight\` to the changed elements. A declared \`highlight\` or \`selector\`
+that matches nothing at capture time records a visible warning — capture still
+succeeds. Declared shots default to the whole visible window (\`fullPage:
+false\`) with changed elements outlined via \`highlight\`; \`selector\` (element
+crop) is the exception and \`fullPage\` stays off.
+
+## Section body edits
+
+To replace a single \`## Section\` without touching the rest of the body (the
+Activity log is always preserved), use:
+
+    repoos update <id> --section "Section Name" --section-body "new content"
+
+A full \`--body\` replace that would drop Problem / Desired UX / Acceptance
+criteria / Notes for AI is refused unless \`--force\` is passed; the error
+message points at this section form.
 `;
 /** Marker makes the optional existing-repo addition safe to offer repeatedly. */
 export const REPOOS_AGENTS_SECTION_MARKER = "<!-- repoos:managed-instructions -->";
@@ -400,6 +431,9 @@ const ENV_EXAMPLE = `# Copy to .env and fill in what you need — .env is gitign
 # --- Model providers / voice-to-text transcription ---
 # REPOOS_OPENROUTER_API_KEY=...
 # REPOOS_OPENCODE_GO_API_KEY=...
+# REPOOS_DEEPINFRA_API_KEY=...
+# REPOOS_GITHUB_COPILOT_TOKEN=...         # classic PAT — billing endpoints reject fine-grained tokens
+# REPOOS_GITHUB_COPILOT_SCOPE=            # empty = personal plan; org:<name> / enterprise:<name> for centrally billed
 # REPOOS_WHISPER_KEY=...                  # or GROQ_API_KEY / OPENAI_API_KEY directly
 
 # --- Infrastructure ---

package/dist/commands/shot.d.ts

@@ -1,3 +1,4 @@
+import { type CaptureEntry } from "../core/shot-plan.js";
 interface CmdShotOptions {
     route?: string;
     target?: string;
@@ -23,6 +24,48 @@ interface CmdShotOptions {
 export declare function isShotCaptureUnavailable(err: unknown): boolean;
 /** Parse `repoos shot [<route|url>] [flags]`; unknown/malformed args set `error`. */
 export declare function parseShotArgs(args: string[]): CmdShotOptions;
+/** Everything the capture plan for one `repoos shot` invocation depends on. */
+export interface CliShotPlanInput {
+    /** The task body, read for its `## Shots` declaration. */
+    body: string;
+    /** The positional route, when the caller typed one (not an absolute URL). */
+    route?: string;
+    /** `--selector`, when given. */
+    selector?: string;
+    /** Target names resolved from changed paths / the task's area / `--target`. */
+    targets: string[];
+    /** Per-target matched globs, for the fallback caption (#0603). */
+    matchedGlobs: ReadonlyMap<string, string[]>;
+    /** Targets whose matched files are docs content only (#0603). */
+    docsContentOnly: ReadonlySet<string>;
+}
+/** The plan plus the visible notes `cmdShot` prints alongside it. */
+export interface CliShotPlan {
+    entries: CaptureEntry[];
+    /** Problems with the task's declared `## Shots` list itself. */
+    declaredErrors: string[];
+    /** Per-entry problems the plan builder reported. */
+    errors: string[];
+    /** Visible skip notes (docs-content-only targets, …). */
+    skips: string[];
+}
+/**
+ * The capture plan for one `repoos shot` run, as a pure function of the task
+ * body, the CLI flags and the resolved targets (#0610). Pulled out of
+ * `cmdShot` so the wiring is testable without a server, git or a browser: the
+ * bug it fixes — a typed route losing to the `/` fallback — lived in the single
+ * line that picked between two candidate plans, so no plan-level test could
+ * reach it.
+ *
+ * Precedence, documented in `user-docs/cli.md` and `repoos shot --help`: an
+ * explicit route/selector replaces the WHOLE declared list. A declared entry
+ * carries steps, a highlight and a label authored for its own route, so
+ * re-pointing entry #2 at a route the engineer typed would click selectors that
+ * may not exist there. The flag says "shoot this", not "shoot this instead of
+ * that entry" — and the fallback then carries the requested route to every
+ * resolved target, which is what it always meant.
+ */
+export declare function buildCliShotPlan(input: CliShotPlanInput): CliShotPlan;
 /**
  * `repoos shot` entrypoint. Returns the process exit code: 0 on success (or a
  * clean skip has already been reported), 1 on a real failure.

package/dist/commands/shot.js

@@ -21,8 +21,8 @@ import { findRepoRoot, loadConfig, mainCheckoutRoot, resolveServePort } from "..
 import { changedPathsVsBase, currentBranch } from "../core/git.js";
 import { createRepoOS } from "../core/repoos.js";
 import { captureShotPage } from "../core/shot-page.js";
-import { buildCapturePlan, parseShotPlan } from "../core/shot-plan.js";
-import { formatTargetList, resolveShotTargets, } from "../core/shot-targets.js";
+import { buildCapturePlan, parseShotPlan, provenanceCaption, } from "../core/shot-plan.js";
+import { describeTargetPathMatches, formatTargetList, resolveShotTargets, } from "../core/shot-targets.js";
 import { readServeLocks } from "./status.js";
 import { readLocalCliToken } from "../server/local-token.js";
 import { launchWebkit } from "./ui-harness.js";
@@ -137,6 +137,38 @@ function normalizedRoute(route) {
         return "/";
     return route.startsWith("/") ? route : `/${route}`;
 }
+/**
+ * The capture plan for one `repoos shot` run, as a pure function of the task
+ * body, the CLI flags and the resolved targets (#0610). Pulled out of
+ * `cmdShot` so the wiring is testable without a server, git or a browser: the
+ * bug it fixes — a typed route losing to the `/` fallback — lived in the single
+ * line that picked between two candidate plans, so no plan-level test could
+ * reach it.
+ *
+ * Precedence, documented in `user-docs/cli.md` and `repoos shot --help`: an
+ * explicit route/selector replaces the WHOLE declared list. A declared entry
+ * carries steps, a highlight and a label authored for its own route, so
+ * re-pointing entry #2 at a route the engineer typed would click selectors that
+ * may not exist there. The flag says "shoot this", not "shoot this instead of
+ * that entry" — and the fallback then carries the requested route to every
+ * resolved target, which is what it always meant.
+ */
+export function buildCliShotPlan(input) {
+    const pinned = Boolean(input.route || input.selector);
+    const declared = pinned ? { shots: [], errors: [] } : parseShotPlan(input.body);
+    const built = buildCapturePlan(input.targets, declared.shots, {
+        matchedGlobs: input.matchedGlobs,
+        docsContentOnly: input.docsContentOnly,
+        route: input.route,
+        selector: input.selector,
+    });
+    return {
+        entries: built.entries,
+        declaredErrors: declared.errors,
+        errors: built.errors,
+        skips: built.autoSkips,
+    };
+}
 /** The task on the main checkout's board whose branch is `branch`, or by id. */
 function findTask(mainRoot, branch, taskId) {
     const index = createRepoOS(mainRoot).reindex();
@@ -208,9 +240,11 @@ async function uploadShot(port, taskId, token, input) {
                 target: input.target,
                 route: input.route,
                 ...(input.label ? { label: input.label } : {}),
+                ...(input.provenance ? { provenance: input.provenance } : {}),
                 name: input.target,
                 mime: "image/png",
                 data: input.data,
+                ...(input.warnings?.length ? { warnings: input.warnings } : {}),
             }),
         });
     }
@@ -239,13 +273,24 @@ export async function cmdShot(args) {
   Which page or state to capture can be declared in the task body: a
   "## Shots" section holding a fenced JSON list, one entry per shot:
 
-    {"target": "default", "route": "/board", "label": "Board",
+    {"target": "default", "route": "/repository", "label": "Task drawer",
+     "highlight": ".drawer .task-title",
      "steps": [{"click": "button.new-task"}, {"waitMs": 300}]}
 
-  (target/route/selector/label/steps; steps are click, fill + text,
-  waitFor, or waitMs, using plain CSS selectors). The same list drives
-  the server's automatic capture at handoff. Without it, "/" is captured
-  per resolved target.
+  (target/route/selector/label/highlight/steps; steps are click, fill + text,
+  waitFor, or waitMs, using plain CSS selectors; highlight is an optional
+  selector outlined around the changed element before capture — say what
+  changed). The same list drives the server's automatic capture at handoff.
+  Without it, "/" is captured per resolved target — by this command when you
+  run it, and by the automatic capture only when the diff touches a UI
+  target's paths; diffs touching just tests or task notes stand down with a
+  visible "shots: skipped — no UI change to capture" note instead.
+
+  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
+  route you typed. A named route also counts as the justification a
+  docs-content-only target needs, so it is captured instead of skipped.
 
   Arguments:
     <route|url>        Route to capture on the preview (default "/"), or an
@@ -297,6 +342,8 @@ export async function cmdShot(args) {
                 target: targets[0],
                 route: opts.route,
                 ...(opts.selector ? { selector: opts.selector } : {}),
+                // An absolute URL is the subject by construction; nothing to attribute.
+                provenance: { kind: "auto" },
             },
         ];
     }
@@ -325,25 +372,43 @@ export async function cmdShot(args) {
         }
         // The task's own `## Shots` declaration wins when the CLI flags did not
         // pin a route/selector — the engineer knows which page/state is visible.
-        const declared = opts.route || opts.selector
-            ? { shots: [], errors: [] }
-            : parseShotPlan(task.body);
-        for (const error of declared.errors) {
+        // Provenance + docs gate need the same match detail the server uses (#0603):
+        // which globs matched per target, and which targets matched docs content
+        // only (for those, a route-less declared shot or the blind `/` fallback is
+        // skipped — a docs home page shows the site, not the change; a route the
+        // caller typed by hand is the justification that skip asks for, so it is
+        // captured).
+        const matchedGlobs = new Map();
+        const docsContentOnly = new Set();
+        for (const match of describeTargetPathMatches(worktreeConfig.preview, changed)) {
+            matchedGlobs.set(match.target, match.globs);
+            if (match.contentOnly)
+                docsContentOnly.add(match.target);
+        }
+        // #0610: the requested route/selector is part of the plan, not a separate
+        // candidate that lost to the fallback's `/`.
+        const built = buildCliShotPlan({
+            body: task.body,
+            route: opts.route,
+            selector: opts.selector,
+            targets,
+            matchedGlobs,
+            docsContentOnly,
+        });
+        for (const error of built.declaredErrors) {
             console.error(c.yellow("  · ") + `declared shot list: ${error}`);
         }
-        const built = buildCapturePlan(targets, declared.shots);
         for (const error of built.errors) {
             console.error(c.yellow("  · ") + error);
         }
-        plan = built.entries.length
-            ? built.entries
-            : targets.map((target) => ({
-                target,
-                route: normalizedRoute(opts.route),
-                ...(opts.selector ? { selector: opts.selector } : {}),
-            }));
-        if (built.entries.length) {
-            console.log(c.dim(`  plan: ${built.entries.map((e) => `${e.target}${e.label ? ` – ${e.label}` : ""}`).join(", ")}`));
+        for (const skip of built.skips) {
+            console.error(c.yellow("  · ") + `skipped: ${skip}`);
+        }
+        plan = built.entries;
+        if (plan.length > 0) {
+            console.log(c.dim(`  plan: ${plan
+                .map((e) => `${e.target}${e.route === "/" ? "" : ` ${e.route}`}${e.label ? ` – ${e.label}` : ""}`)
+                .join(", ")}`));
         }
     }
     // Preview lifecycle is server-owned; the CLI only reaches it over HTTP. Prefer
@@ -406,11 +471,17 @@ export async function cmdShot(args) {
                 : `${currentPreviewUrl}${normalizedRoute(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,
+                png = await captureShotPage(page, pageUrl, entry, { waitMs: opts.waitMs, fullPage: opts.fullPage }, (selector, route) => {
+                    warnings.push(`highlight ${selector} matched nothing on ${route}`);
+                    console.error(c.yellow("  · ") +
+                        `highlight "${selector}" matched nothing on ${route} — capture went ahead unhighlighted`);
+                }, (selector, route) => {
+                    warnings.push(`selector ${selector} matched nothing on ${route}`);
+                    console.error(c.yellow("  · ") +
+                        `selector "${selector}" matched nothing on ${route} — capture used the whole window`);
                 });
             }
             catch (err) {
@@ -424,7 +495,9 @@ export async function cmdShot(args) {
                 target: entry.target,
                 route: entry.route.startsWith("/") ? normalizedRoute(entry.route) : entry.route,
                 ...(entry.label ? { label: entry.label } : {}),
+                provenance: provenanceCaption(entry.provenance),
                 data: png.toString("base64"),
+                ...(warnings.length ? { warnings } : {}),
             });
             if (!uploaded.ok) {
                 console.error(c.red("  ✗ ") + `storing the shot failed: ${uploaded.error}`);
@@ -438,7 +511,7 @@ export async function cmdShot(args) {
                 url: uploaded.shot.url,
             });
             console.log(c.green("  ✔ ") +
-                `${entry.target}${entry.label ? ` – ${entry.label}` : ""} → ${c.cyan(uploaded.shot.path)} ${c.dim(`(${Math.round(png.length / 1024)} KB)`)}`);
+                `${entry.target}${entry.highlight ? " · highlighted" : ""}${entry.label ? ` – ${entry.label}` : ""} → ${c.cyan(uploaded.shot.path)} ${c.dim(`(${Math.round(png.length / 1024)} KB)`)}`);
         }
         if (saved.length === 0) {
             console.error(c.yellow("  · ") + "No shots captured.");

package/dist/commands/tasks.d.ts

@@ -72,15 +72,20 @@ export declare function cmdNote(args: string[]): void;
 /**
  * `repoos update <id> [--title ...] [--area ...] [--story ...] [--priority ...]
  *   [--type ...] [--body ... | --body -] [--branch ...] [--assigned-to ai|human]
- *   [--needs-input true|false] [--questions "Question one\nQuestion two"]`
+ *   [--needs-input true|false] [--questions "Question one\nQuestion two"] [--depends-on ids]
+ *   [--shots '<JSON list>' | --section "<heading>" --section-body ... | --force]`
  *
  * Writes directly via patchTaskFile (same path the server's PATCH route uses),
  * so it works with no HTTP round-trip and no session auth — this is the path
  * agents/scripts should use to edit task metadata instead of hitting the API.
  * `--body -` reads the new body from stdin, for large/multiline bodies.
+ * `--shots '<JSON list>'` validates and formats `## Shots` without clobbering
+ * the rest of the body. A full `--body` that drops spec headings (Problem /
+ * Desired UX / Acceptance criteria / Notes for AI) is refused unless `--force`
+ * is passed.
  */
 export declare function cmdUpdate(args: string[]): void;
-/** `repoos new <title> [--ai] [--needs-input true] [--questions "..."]` */
+/** `repoos new <title> [--ai] [--needs-input true] [--questions "..."] [--depends-on ids]` */
 export declare function cmdNew(args: string[]): void;
 /** `repoos index [--json]` — rebuild cache; optionally print machine-readable JSON. */
 export declare function cmdIndex(args: string[]): void;