@repo-os/repoos 0.5.67 → 0.5.68

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "93934ce20f177f2d06114caa9df33fcc13b17c9f8b1694247b2cb6282628fab8",
-  "version": "0.5.67",
+  "hash": "a50a11bbcdcbcbedd23ed2410aa902333da0a7c6a5f48a204f67758d061c71d1",
+  "version": "0.5.68",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-10-07T10:18:27.380Z"
+  "generatedAt": "2026-10-09T03:35:17.984Z"
 }

package/dist/cli/api-route-parity.js

@@ -18,6 +18,9 @@ const CONTROL_API_MATCHERS = [
     exact("POST", "/api/remote-validation/test"),
     exact("GET", "/api/agents/running"),
     exact("GET", "/api/stats/board"),
+    exact("GET", "/api/driver/brief"),
+    exact("GET", "/api/events"),
+    exact("POST", "/api/cto/heartbeat"),
     // `repoos review` → PATCH status=review; `repoos override` → PATCH overrides
     re("PATCH", /^\/api\/tasks\/([^/]+)$/.source),
 ];
@@ -65,6 +68,7 @@ const UI_ONLY_MATCHERS = [
     exact("GET", "/api/system/run-tests"),
     exact("POST", "/api/system/run-tests"),
     exact("GET", "/api/attention"),
+    exact("GET", "/api/decisions"),
     exact("GET", "/api/check-runs"),
     (r) => r.pattern.startsWith("/api/integration"),
     exact("GET", "/api/close-out/outcomes"),

package/dist/cli/help.js

@@ -8,9 +8,9 @@
  * usage line lives in per-command help rather than inline.
  */
 import { readVersion } from "../core/version.js";
-import { PRIORITIES, TASK_TYPES } from "../core/types.js";
 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"]);
 const GROUPS = [
@@ -48,9 +48,9 @@ const GROUPS = [
             { name: "show", usage: "show <id>", desc: "Show a task's full spec" },
             {
                 name: "new",
-                usage: `new "<title>" [--ai --type ${TASK_TYPES.join("|")} --area <a> --priority ${PRIORITIES.join("|")} --body <b>]`,
+                usage: 'new "<title>" ' + flagUsageTokens(NEW_FLAG_HELP).join(" "),
                 desc: "Create a task",
-                flags: `--ai · --type · --area · --priority · --body`,
+                flags: flagSummary(NEW_FLAG_HELP),
             },
             {
                 name: "new-doc",
@@ -140,6 +140,18 @@ const GROUPS = [
                 desc: "Board spend summary (GET /api/stats/board)",
                 flags: "--json · --port",
             },
+            {
+                name: "watch",
+                usage: "watch [--json] [--task <id>] [--port N]",
+                desc: "Stream board SSE events for external driver sessions (GET /api/events)",
+                flags: "--json · --task · --port",
+            },
+            {
+                name: "driver",
+                usage: "driver brief [--json] [--port N]",
+                desc: "Print the CTO's board brief from live state (GET /api/driver/brief)",
+                flags: "--json · --port",
+            },
             {
                 name: "rm",
                 usage: "rm <id> --yes",
@@ -148,9 +160,15 @@ const GROUPS = [
             },
             {
                 name: "update",
-                usage: "update <id> [flags]",
+                usage: "update <id> " + flagUsageTokens(UPDATE_FLAG_HELP).join(" "),
                 desc: "Edit a task's metadata or body",
-                flags: `--title · --area · --priority ${PRIORITIES.join("|")} · --type ${TASK_TYPES.join("|")} · --body · --branch · --assigned-to`,
+                flags: flagSummary(UPDATE_FLAG_HELP),
+            },
+            {
+                name: "story",
+                usage: 'story new "<name>" --body <text|-> | story list | story show <number|name> | story update <number|name> [--name …] [--body <text|->]',
+                desc: "Create, list, show or update story definitions verbatim (no PM agent)",
+                flags: "new/show/update: --body - · list/show: --json",
             },
             {
                 name: "index",
@@ -263,6 +281,12 @@ const EXAMPLES = [
     { cmd: 'repoos mv 0012 active --note "Fix the regression in checkout; see review"' },
     { cmd: 'repoos note 0012 "Handle the reviewer\'s suggestions before the next review"' },
     { cmd: 'repoos update 0012 --title "New title" --area web,core' },
+    {
+        cmd: 'repoos story new "Project updates email" --body "Why this slice exists, scope and non-goals"',
+        comment: "verbatim story, no PM",
+    },
+    { cmd: "repoos story list", comment: "registered stories, with numbers" },
+    { cmd: "repoos story show 0007", comment: "definition + member tasks and their statuses" },
     { cmd: "repoos list ready" },
     { cmd: "repoos outline src/server/agents.ts", comment: "then read only the range you need" },
     { cmd: "repoos doctor", comment: "passing checks are hidden; --verbose shows all" },
@@ -282,6 +306,7 @@ const ALIASES = {
     add: "new",
     reindex: "index",
     server: "serve",
+    stories: "story",
 };
 /** Resolve an alias to its canonical command name (identity when not an alias). */
 export function canonicalCommand(name) {

package/dist/cli/index.js

@@ -6,6 +6,7 @@
 import { cmdInit } from "../commands/init.js";
 import { cmdList, cmdShow, cmdMv, cmdRm, cmdUpdate, cmdNew, cmdIndex, cmdNote, } from "../commands/tasks.js";
 import { cmdDocs, cmdNewDoc } from "../commands/docs.js";
+import { cmdStory } from "../commands/stories.js";
 import { cmdGc } from "../commands/gc.js";
 import { cmdOutline } from "../commands/outline.js";
 import { cmdCheck } from "../commands/check.js";
@@ -20,7 +21,9 @@ import { cmdDoctor } from "../commands/doctor.js";
 import { cmdCertify } from "../commands/certify.js";
 import { cmdSupport } from "../commands/support.js";
 import { cmdService } from "../commands/service.js";
-import { cmdAgentsRunning, cmdConfig, cmdDone, cmdMessage, cmdOverride, cmdPause, cmdPreview, cmdReview, cmdRunners, cmdStart, cmdStats, } from "../commands/control-api.js";
+import { cmdAgentsRunning, cmdConfig, cmdDone, cmdMessage, cmdOverride, cmdPause, cmdPreview, cmdReview, cmdRunners, cmdStart, cmdStats, cmdDecisions, } from "../commands/control-api.js";
+import { cmdWatch } from "../commands/watch.js";
+import { cmdDriver } from "../commands/driver.js";
 import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
 import { reexecAfterStaleBuild, reexecUnderBunIfRequested } from "../core/runtime.js";
@@ -170,6 +173,10 @@ function main() {
         case "docs":
             void cmdDocs(rest);
             break;
+        case "story":
+        case "stories":
+            cmdStory(rest);
+            break;
         case "index":
         case "reindex":
             cmdIndex(rest);
@@ -259,6 +266,25 @@ function main() {
                     process.exitCode = code;
             });
             break;
+        case "decisions":
+        case "attention":
+            void cmdDecisions(rest).then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            });
+            break;
+        case "watch":
+            void cmdWatch(rest).then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            });
+            break;
+        case "driver":
+            void cmdDriver(rest).then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            });
+            break;
         case "shot":
             void cmdShot(rest)
                 .then((code) => {

package/dist/cli/repoos-api.d.ts

@@ -37,6 +37,10 @@ export declare class RepoOsApi {
     private buildHeaders;
     private devBackdoorLogin;
     health(): Promise<boolean>;
+    /** Re-run dev backdoor login after a 401 (e.g. server reload). */
+    reauthenticate(): Promise<boolean>;
+    /** Open `GET /api/events` with the same auth as other CLI calls. */
+    fetchEventStream(): Promise<Response>;
     request(method: string, path: string, body?: unknown, opts?: {
         retryAuth?: boolean;
     }): Promise<{

package/dist/cli/repoos-api.js

@@ -104,6 +104,21 @@ export class RepoOsApi {
             return false;
         }
     }
+    /** Re-run dev backdoor login after a 401 (e.g. server reload). */
+    async reauthenticate() {
+        return this.devBackdoorLogin();
+    }
+    /** Open `GET /api/events` with the same auth as other CLI calls. */
+    async fetchEventStream() {
+        try {
+            return await fetch(`${this.baseUrl}/api/events`, {
+                headers: { ...this.buildHeaders(false), accept: "text/event-stream" },
+            });
+        }
+        catch (err) {
+            throw new RepoOsApiError(`Can't reach the RepoOS server at ${this.baseUrl}. Is \`repoos serve\` running? ${err.message}`, 0);
+        }
+    }
     async request(method, path, body, opts = {}) {
         const jsonBody = body !== undefined;
         const doFetch = async () => {

package/dist/cli/sse-client.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Minimal SSE frame parser for CLI consumers (#0728).
+ */
+export declare function parseSseChunk(buffer: string, onData: (jsonText: string) => void): string;
+export declare function consumeSseResponse(res: Response, onJson: (data: unknown) => void, shouldContinue: () => boolean): Promise<void>;

package/dist/cli/sse-client.js

@@ -0,0 +1,42 @@
+/**
+ * Minimal SSE frame parser for CLI consumers (#0728).
+ */
+export function parseSseChunk(buffer, onData) {
+    let rest = buffer;
+    let split = rest.indexOf("\n\n");
+    while (split !== -1) {
+        const frame = rest.slice(0, split);
+        rest = rest.slice(split + 2);
+        const dataLine = frame.split("\n").find((line) => line.startsWith("data: "));
+        if (dataLine)
+            onData(dataLine.slice(6));
+        split = rest.indexOf("\n\n");
+    }
+    return rest;
+}
+export async function consumeSseResponse(res, onJson, shouldContinue) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (shouldContinue()) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            buffer = parseSseChunk(buffer, (text) => {
+                try {
+                    onJson(JSON.parse(text));
+                }
+                catch {
+                    /* ignore partial frames */
+                }
+            });
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}

package/dist/cli/task-flags.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The full valid value sets for `--priority` / `--type`, rendered into the
+ * usage/help text so accepted values are obvious at the point of use (#0656).
+ */
+export declare const PRIORITY_USAGE: string;
+export declare const TYPE_USAGE: string;
+/** One flag's help metadata. */
+export interface TaskFlagHelp {
+    /** Placeholder rendered after the flag (e.g. `true|false`); omit for a boolean flag. */
+    value?: string;
+    /** One-line description, shown by `repoos <cmd> --help`. */
+    desc: string;
+}
+/** Every flag `repoos new` accepts, in help order. */
+export declare const NEW_FLAG_HELP: Record<string, TaskFlagHelp>;
+/** Every flag `repoos update` accepts, in help order. */
+export declare const UPDATE_FLAG_HELP: Record<string, TaskFlagHelp>;
+/** One `--flag` / `--flag value` token, as used in a usage line. */
+export declare function flagToken(name: string, help: TaskFlagHelp): string;
+/** Ordered `--flag [value]` tokens for every entry in a help map. */
+export declare function flagUsageTokens(help: Record<string, TaskFlagHelp>): string[];
+/** The dim `flags:` summary line: `--flag value · --other`, in declaration order. */
+export declare function flagSummary(help: Record<string, TaskFlagHelp>): string;

package/dist/cli/task-flags.js

@@ -0,0 +1,79 @@
+/**
+ * Flag help metadata for `repoos new` / `repoos update` (#0699).
+ *
+ * The parse tables live in `src/commands/tasks.ts` (`NEW_FLAGS`, derived from
+ * `NEW_FLAG_HELP`, and `UPDATE_FLAGS`). These ordered maps are the single
+ * source of truth for help text: `renderHelp` (the top-level Tasks group) and
+ * `printCommandHelp` both render from them, so a flag can no longer be accepted
+ * without a one-line description. A test asserts every key of `UPDATE_FLAGS`
+ * has an entry here, which makes "added a flag, forgot the help" fail the gate.
+ *
+ * `UPDATE_FLAG_HELP` intentionally covers the flags `cmdUpdate` handles
+ * specially (`shots`, `section`, `section-body`, `clear-questions`, `force`),
+ * not just the `UPDATE_FLAGS` parse map.
+ */
+import { PRIORITIES, TASK_TYPES } from "../core/types.js";
+/**
+ * The full valid value sets for `--priority` / `--type`, rendered into the
+ * usage/help text so accepted values are obvious at the point of use (#0656).
+ */
+export const PRIORITY_USAGE = PRIORITIES.join("|");
+export const TYPE_USAGE = TASK_TYPES.join("|");
+/** Every flag `repoos new` accepts, in help order. */
+export const NEW_FLAG_HELP = {
+    ai: { desc: "Assign the task to an AI engineer" },
+    type: { value: TYPE_USAGE, desc: "Task type" },
+    area: { value: "web,core", desc: "Area(s), comma-separated" },
+    story: { value: '"name"', desc: "Tag the task as part of a story (delivery slice)" },
+    "depends-on": { value: "ids", desc: "Comma-separated task ids that must land first" },
+    priority: { value: PRIORITY_USAGE, desc: "Priority" },
+    "needs-input": { value: "true|false", desc: "Flag the task as needing human input" },
+    questions: { value: '"Q1\\nQ2"', desc: "Open questions for the human (newline or JSON list)" },
+    hold: { value: "true|false", desc: "Hold the task out of auto-dispatch" },
+    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)" },
+};
+/** Every flag `repoos update` accepts, in help order. */
+export const UPDATE_FLAG_HELP = {
+    title: { value: '"..."', desc: "Task title" },
+    area: { value: "web,core", desc: "Area(s), comma-separated" },
+    story: { value: '"name"', desc: "Tag the task as part of a story (delivery slice)" },
+    "depends-on": { value: "ids", desc: "Comma-separated task ids that must land first" },
+    priority: { value: PRIORITY_USAGE, desc: "Priority" },
+    type: { value: TYPE_USAGE, desc: "Task type" },
+    body: { value: '"..."|-', desc: "Replace the body; `-` reads it from stdin" },
+    branch: { value: "b", desc: "Branch name" },
+    "assigned-to": { value: "ai|human", desc: "Assignee" },
+    "needs-input": { value: "true|false", desc: "Flag the task as needing human input" },
+    "needs-merge": { value: "true|false", desc: "Flag the task as needing a merge" },
+    hold: { value: "true|false", desc: "Hold the task out of auto-dispatch" },
+    paths: { value: "a,b", desc: "Files the task touches, e.g. src/a.ts,src/b.ts" },
+    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)" },
+    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" },
+    agent: { value: "name", desc: "Engineer agent override (empty clears)" },
+    cli: { value: "name", desc: "Engineer CLI override (empty clears)" },
+    model: { value: "name", desc: "Engineer model override (empty clears)" },
+    "pm-agent": { value: "name", desc: "PM agent override (empty clears)" },
+    "pm-cli": { value: "name", desc: "PM CLI override (empty clears)" },
+    "pm-model": { value: "name", desc: "PM model override (empty clears)" },
+    "review-agent": { value: "name", desc: "Reviewer agent override (empty clears)" },
+    "review-cli": { value: "name", desc: "Reviewer CLI override (empty clears)" },
+    "review-model": { value: "name", desc: "Reviewer model override (empty clears)" },
+};
+/** One `--flag` / `--flag value` token, as used in a usage line. */
+export function flagToken(name, help) {
+    return help.value ? `--${name} ${help.value}` : `--${name}`;
+}
+/** Ordered `--flag [value]` tokens for every entry in a help map. */
+export function flagUsageTokens(help) {
+    return Object.entries(help).map(([name, h]) => flagToken(name, h));
+}
+/** The dim `flags:` summary line: `--flag value · --other`, in declaration order. */
+export function flagSummary(help) {
+    return flagUsageTokens(help).join(" · ");
+}

package/dist/commands/check.d.ts

@@ -69,25 +69,28 @@ export declare function resolveBareRequireRoots(configured: string[] | undefined
  * stale screenshot churn). Product image assets — UI, icons, logos, docs —
  * live outside those folders and stay tracked.
  *
- * The folder names come from `repoos.toml` (`workDir`/`inputsDir`) so a managed
- * repo that renames them still gets the guard; they default to `work`/`inputs`.
+ * The folder names come from `repoos.toml` (`workDir`/`inputsDir`/`storiesDir`)
+ * so a managed repo that renames them still gets the guard; they default to
+ * `work`/`inputs`/`stories`.
  *
  * Pure (takes the tracked-file list) so it is unit-testable; the check block
  * feeds it `git ls-files`.
  */
 /**
- * Normalize a configured guard directory (`workDir`/`inputsDir`) for prefix
- * matching against `git ls-files` output, which is always repo-root-relative:
- * strip any leading `./` and trailing slashes. Returns empty for anything that
- * can't be a repo-relative directory — an explicit `""`, `"."`/`"./"`, an
- * absolute path, a home-relative `~/…`, or a path containing a `..` segment.
- * Those would all silently match nothing (or, for `""`, fatal git's pathspec),
- * so callers must treat empty as unusable rather than as "match everything".
+ * Normalize a configured guard directory (`workDir`/`inputsDir`/`storiesDir`)
+ * for prefix matching against `git ls-files` output, which is always
+ * repo-root-relative: strip any leading `./` and trailing slashes. Returns
+ * empty for anything that can't be a repo-relative directory — an explicit
+ * `""`, `"."`/`"./"`, an absolute path, a home-relative `~/…`, or a path
+ * containing a `..` segment. Those would all silently match nothing (or, for
+ * `""`, fatal git's pathspec), so callers must treat empty as unusable rather
+ * than as "match everything".
  */
 export declare function normalizeGuardDir(d: string): string;
 export declare function taskAssetOffenders(trackedPaths: string[], dirs?: {
     workDir?: string;
     inputsDir?: string;
+    storiesDir?: string;
 }): string[];
 /** Marker that allowlists a hard-coded color; must carry a reason. */
 export declare const HARDCODED_COLOR_MARKER = "hardcode-ok";

package/dist/commands/check.js

@@ -45,7 +45,7 @@ import { mainCheckoutRoot } from "../core/git.js";
 import { Logger } from "../core/logger.js";
 import { boardRootForEngineerRemote, boardTaskAbsPath, commitWipCheckpointForRemoteGate, isManagedEngineerCheck, runEngineerRemoteSelfCheckGate, } from "../server/engineer-remote-self-check.js";
 import { createRemoteValidator } from "../server/remote-validation.js";
-import { runRemotePreReviewGate, standaloneCliCanUseRemote, remoteValidationAlreadyAttempted, uncommittedFilesBlockingRemoteGate, shouldRunCliRemotePreReviewGate, summarizeRemoteFallbackDetail, REPOOS_REMOTE_FALLBACK_DETAIL, } from "../server/pre-review-remote-gate.js";
+import { runRemotePreReviewGate, standaloneCliCanUseRemote, remoteValidationAlreadyAttempted, uncommittedFilesBlockingRemoteGate, shouldRunCliRemotePreReviewGate, summarizeRemoteFallbackDetail, REPOOS_REMOTE_FALLBACK_DETAIL, REPOOS_CHECK_GATE_NOTE, } from "../server/pre-review-remote-gate.js";
 /**
  * Split a CSS selector list on top-level commas (respecting parentheses,
  * so `:not(.a,.b)` stays one group).
@@ -402,20 +402,22 @@ function dedupeRoots(roots) {
  * stale screenshot churn). Product image assets — UI, icons, logos, docs —
  * live outside those folders and stay tracked.
  *
- * The folder names come from `repoos.toml` (`workDir`/`inputsDir`) so a managed
- * repo that renames them still gets the guard; they default to `work`/`inputs`.
+ * The folder names come from `repoos.toml` (`workDir`/`inputsDir`/`storiesDir`)
+ * so a managed repo that renames them still gets the guard; they default to
+ * `work`/`inputs`/`stories`.
  *
  * Pure (takes the tracked-file list) so it is unit-testable; the check block
  * feeds it `git ls-files`.
  */
 /**
- * Normalize a configured guard directory (`workDir`/`inputsDir`) for prefix
- * matching against `git ls-files` output, which is always repo-root-relative:
- * strip any leading `./` and trailing slashes. Returns empty for anything that
- * can't be a repo-relative directory — an explicit `""`, `"."`/`"./"`, an
- * absolute path, a home-relative `~/…`, or a path containing a `..` segment.
- * Those would all silently match nothing (or, for `""`, fatal git's pathspec),
- * so callers must treat empty as unusable rather than as "match everything".
+ * Normalize a configured guard directory (`workDir`/`inputsDir`/`storiesDir`)
+ * for prefix matching against `git ls-files` output, which is always
+ * repo-root-relative: strip any leading `./` and trailing slashes. Returns
+ * empty for anything that can't be a repo-relative directory — an explicit
+ * `""`, `"."`/`"./"`, an absolute path, a home-relative `~/…`, or a path
+ * containing a `..` segment. Those would all silently match nothing (or, for
+ * `""`, fatal git's pathspec), so callers must treat empty as unusable rather
+ * than as "match everything".
  */
 export function normalizeGuardDir(d) {
     let trimmed = d;
@@ -431,7 +433,11 @@ export function normalizeGuardDir(d) {
 }
 export function taskAssetOffenders(trackedPaths, dirs = {}) {
     const IMG = /\.(png|jpe?g|gif|webp|avif|bmp|svg|ico|pdf)$/i;
-    const prefixes = [dirs.workDir ?? "work", dirs.inputsDir ?? "inputs"]
+    const prefixes = [
+        dirs.workDir ?? "work",
+        dirs.inputsDir ?? "inputs",
+        dirs.storiesDir ?? "stories",
+    ]
         .map(normalizeGuardDir)
         .filter(Boolean)
         .map((d) => `${d}/`);
@@ -1189,12 +1195,13 @@ async function stepBareRequire(ctx) {
     };
 }
 async function stepTaskAssets(ctx) {
-    // Folder names are configurable (`workDir`/`inputsDir`), so a repo that
-    // renames them is still guarded.
+    // Folder names are configurable (`workDir`/`inputsDir`/`storiesDir`), so a
+    // repo that renames them is still guarded.
     const config = ctx.cfg;
     const dirs = [
         { label: "workDir", raw: config.workDir ?? "work" },
         { label: "inputsDir", raw: config.inputsDir ?? "inputs" },
+        { label: "storiesDir", raw: config.storiesDir ?? "stories" },
     ];
     const usable = [];
     const broken = [];
@@ -1231,6 +1238,7 @@ async function stepTaskAssets(ctx) {
     const offenders = taskAssetOffenders(tracked, {
         workDir: config.workDir,
         inputsDir: config.inputsDir,
+        storiesDir: config.storiesDir,
     });
     const labels = usable.map((d) => `${d}/`).join(" or ");
     if (offenders.length === 0)
@@ -1335,9 +1343,15 @@ async function triageIsolatedFailures(ctx, base, testScript, output, env) {
 }
 async function stepTests(ctx) {
     // The close-out pipeline can hand the suite to the Remote Validation Runner
-    // and then run only the cheap local guards (REPOOS_SKIP_TESTS=1).
+    // and then run only the cheap local guards (REPOOS_SKIP_TESTS=1), or reuse a
+    // handoff-proven result entirely (#0724). Either way the step is skipped —
+    // say which, so the Checks tab is not misleading.
     if (process.env.REPOOS_SKIP_TESTS === "1") {
-        return skipped("skipped — test suite ran on the remote validation runner (REPOOS_SKIP_TESTS=1)");
+        const reuseNote = process.env[REPOOS_CHECK_GATE_NOTE]?.trim();
+        const viaReuse = reuseNote ? /reus|identical|bookkeeping/i.test(reuseNote) : false;
+        return skipped(viaReuse
+            ? `skipped — full suite reused from the handoff gate (${reuseNote})`
+            : "skipped — test suite ran on the remote validation runner (REPOOS_SKIP_TESTS=1)");
     }
     const hasTestScript = Boolean(ctx.scriptPkg.scripts?.test);
     const hasTestFiles = ["test", "__tests__", "tests"].some((d) => existsSync(join(ctx.cwd, d)));
@@ -2123,12 +2137,21 @@ export async function cmdCheck(argv = []) {
         detail: (() => {
             const fallback = process.env[REPOOS_REMOTE_FALLBACK_DETAIL]?.trim();
             const stepDetail = gatingFailures[0]?.detail ?? null;
-            if (!fallback)
-                return stepDetail;
-            const summary = summarizeRemoteFallbackDetail(fallback);
-            if (!stepDetail)
-                return summary;
-            return `${summary} — ${stepDetail}`;
+            // #0724: which close-out gate mode ran and why, so the Checks tab is
+            // auditable ("reused from handoff check <sha>" / "scoped N files").
+            const gateNote = process.env[REPOOS_CHECK_GATE_NOTE]?.trim();
+            const fallbackPart = (() => {
+                if (!fallback)
+                    return null;
+                const summary = summarizeRemoteFallbackDetail(fallback);
+                if (!stepDetail)
+                    return summary;
+                return `${summary} — ${stepDetail}`;
+            })();
+            const base = fallbackPart ?? stepDetail;
+            if (!gateNote)
+                return base;
+            return base ? `${gateNote} — ${base}` : gateNote;
         })(),
         // The stored detail is a short log tail that routinely loses the failing
         // test's name; keep the names themselves so "which test?" is a query.

package/dist/commands/control-api.d.ts

@@ -8,6 +8,7 @@ export declare function cmdPreview(args: string[]): Promise<number>;
 export declare function cmdConfig(args: string[]): Promise<number>;
 export declare function cmdRunners(args: string[]): Promise<number>;
 export declare function cmdAgentsRunning(args: string[]): Promise<number>;
+export declare function cmdDecisions(args: string[]): Promise<number>;
 export declare function cmdStats(args: string[]): Promise<number>;
 /** Shared server-down check for tests. */
 export declare function controlApiServerDownMessage(port: number): Promise<string>;

package/dist/commands/control-api.js

@@ -4,6 +4,7 @@
 import { c } from "../cli/colors.js";
 import { pollUntil, RepoOsApi, RepoOsApiError, resolveControlPlaneBase, } from "../cli/repoos-api.js";
 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 rest = [];
@@ -192,7 +193,7 @@ export async function cmdReview(args) {
                 throw new RepoOsApiError(reason, 400, t);
             }
             return null;
-        }, { label: `handoff for #${id}`, timeoutMs: 600_000 });
+        }, { label: `handoff for #${id}`, timeoutMs: HANDOFF_DEADLINE_MS });
         if (opts.json)
             printJson({ ok: true, task: result });
         else
@@ -487,6 +488,45 @@ export async function cmdAgentsRunning(args) {
         return 1;
     }
 }
+export async function cmdDecisions(args) {
+    const { opts, error } = parseCommonFlags(args);
+    if (error) {
+        printErr(error);
+        return 1;
+    }
+    const api = new RepoOsApi({ port: opts.port });
+    try {
+        await ensureServer(api);
+        const data = await api.requestOk("GET", "/api/decisions");
+        if (opts.json) {
+            printJson(data);
+            return 0;
+        }
+        const digest = data;
+        const items = digest.items ?? [];
+        if (!items.length) {
+            console.log(c.green("  ✓ ") + c.dim("No decisions waiting — policy and CTO have the board."));
+            return 0;
+        }
+        const paused = digest.automationPaused ? " (automation paused)" : "";
+        console.log(c.yellow(`  ${items.length} item(s) need a decision${paused}:`));
+        for (const item of items) {
+            const id = item.taskId ? `#${item.taskId}` : item.kind;
+            console.log(`  · ${id} — ${item.cause.headline}`);
+            const auto = item.actions.filter((a) => a.policyAutomatic).map((a) => a.label);
+            const human = item.actions.filter((a) => !a.policyAutomatic).map((a) => a.label);
+            if (auto.length)
+                console.log(c.dim(`      CTO/policy: ${auto.join("; ")}`));
+            if (human.length)
+                console.log(c.dim(`      You: ${human.join("; ")}`));
+        }
+        return 0;
+    }
+    catch (e) {
+        printErr(e.message);
+        return 1;
+    }
+}
 export async function cmdStats(args) {
     const { opts, error } = parseCommonFlags(args);
     if (error) {

package/dist/commands/driver.d.ts

@@ -0,0 +1 @@
+export declare function cmdDriver(args: string[]): Promise<number>;