@repo-os/repoos 0.5.74 → 0.5.76

package/README.md

@@ -1,9 +1,9 @@
 # RepoOS
 
-**The repo is the operating system.**
+**The repo is the operating system. Your AI dev team, living in your repo, for CTOs and builders.**
 
 RepoOS is a lightweight, repo-native way to track work that lives as markdown
-files inside your monorepo. Tasks, specs, bugs, and feature requests are plain
+files inside your repo. Tasks, specs, bugs, and feature requests are plain
 `.md` files with YAML frontmatter — versioned in git, readable by humans, and
 designed to be consumed directly by AI coding agents.
 
@@ -50,7 +50,8 @@ curl -fsSL https://repoos.org/install | bash
 ```
 
 It runs on Bun when available (recommended), otherwise requires Node.js >=
-20.6.0. It installs to `~/.repoos` and links `repoos` into `~/.local/bin`.
+20.6.0. It installs to `~/.local/share/repoos` and links `repoos` into
+`~/.local/bin`. Machine state stays in `~/.repoos`.
 
 ### Homebrew
 
@@ -76,22 +77,18 @@ bun add -g @repo-os/repoos
 pnpm add -g @repo-os/repoos
 ```
 
-### mise
+mise is not a recommended install method. See `docs/install-layout.md`.
 
-```bash
-mise use --global npm:@repo-os/repoos
-```
-
-This uses mise's built-in npm backend and records RepoOS in your global mise
-configuration. Make sure [mise shell activation](https://mise.jdx.dev/getting-started.html)
-is enabled so its `repoos` shim is on your PATH.
+Bun installs `bun` into `~/.bun/bin`; add that directory to `PATH` before
+`bun add -g`. pnpm on a clean account needs `SHELL` set and `pnpm setup`
+before a global install.
 
 Use the same tool to update a package-manager install: `npm update -g
 @repo-os/repoos`, `bun update -g @repo-os/repoos`, `pnpm update -g
-@repo-os/repoos`, `mise upgrade npm:@repo-os/repoos`, or `brew update && brew
-upgrade repo-os/tap/repoos`. A standalone install updates with `repoos upgrade`
-and removes with `repoos uninstall`. When run from a recognised package-manager
-install, `repoos upgrade` prints the matching package-manager command instead.
+@repo-os/repoos`, or `brew update && brew upgrade repo-os/tap/repoos`. A
+standalone install updates with `repoos upgrade` and removes with
+`repoos uninstall`. When run from a recognised package-manager install,
+`repoos upgrade` prints the matching package-manager command instead.
 
 Then in any repo:
 

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "acb4fde7b3c6e297f938786a4607f68999d8c272283c2b7d27f1d821525ef5dd",
-  "version": "0.5.74",
+  "hash": "ee6f28bc85995205fba9c8e23d6fc9802ccba3ff85045ffd94eaba4a635c603f",
+  "version": "0.5.76",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-10-30T16:08:37.438Z"
+  "generatedAt": "2026-11-05T04:53:41.853Z"
 }

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

@@ -18,6 +18,8 @@ const CONTROL_API_MATCHERS = [
     re("POST", /^\/api\/tasks\/([^/]+)\/needs-input\/dismiss$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/review\/again$/.source),
     re("GET", /^\/api\/tasks\/([^/]+)\/landable$/.source),
+    // Non-blocking handoff outcome for `repoos handoff-status` (#1028).
+    re("GET", /^\/api\/tasks\/([^/]+)\/handoff-status$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/preview$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/preview\/stop$/.source),
     // `repoos shot` single-entry capture through the browser-capture policy (#0874).
@@ -73,6 +75,11 @@ const FILE_CLI_MATCHERS = [
 ];
 /** UI-only, SSE/hub, auth, or internal routes — no CLI required. */
 const UI_ONLY_MATCHERS = [
+    // Task-card-only explicit cancellation of a stalled, registered local check.
+    re("POST", /^\/api\/tasks\/([^/]+)\/cancel-check$/.source),
+    // Read-only task engineering-report history used by the Dev tab.
+    re("GET", /^\/api\/tasks\/([^/]+)\/engineering-reports$/.source),
+    re("GET", /^\/api\/tasks\/([^/]+)\/engineering-reports\/([^/]+)$/.source),
     under("/api/auth/"),
     under("/api/hub/"),
     under("/api/telegram/"),
@@ -111,6 +118,7 @@ const UI_ONLY_MATCHERS = [
     exact("GET", "/api/attention"),
     exact("GET", "/api/decisions"),
     exact("GET", "/api/check-runs"),
+    exact("GET", "/api/check-run-test-cases"),
     exact("GET", "/api/local-check-slots"),
     re("POST", /^\/api\/local-check-slots\/(\d+)\/release\/(\d+)$/.source),
     exact("GET", "/api/resource-queues"),
@@ -118,6 +126,7 @@ const UI_ONLY_MATCHERS = [
     re("GET", /^\/api\/tasks\/([^/]+)\/integration-job$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/worktree-handoff\/discard$/.source),
     re("GET", /^\/api\/tasks\/([^/]+)\/review$/.source),
+    re("GET", /^\/api\/tasks\/([^/]+)\/review\/passes\/([^/]+)$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/review\/message$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/pm\/message$/.source),
     re("POST", /^\/api\/tasks\/([^/]+)\/pm\/interrupt$/.source),

package/dist/cli/help.js

@@ -157,7 +157,13 @@ const GROUPS = [
             {
                 name: "landable",
                 usage: "landable <id> [--json] [--port N]",
-                desc: "Read-only landing pre-checks (verdict, lock, worktree, merge, scope, main) — exits non-zero when not landable (GET /api/tasks/:id/landable)",
+                desc: "Read-only checks before merging (verdict, lock, worktree, merge, scope, main) — exits non-zero when the task is not ready to merge (GET /api/tasks/:id/landable)",
+                flags: "--json · --port",
+            },
+            {
+                name: "handoff-status",
+                usage: "handoff-status <id> [--json] [--port N]",
+                desc: "Non-blocking state of the latest handoff attempt: not requested, running, passed, failed or deferred (GET /api/tasks/:id/handoff-status)",
                 flags: "--json · --port",
             },
             {
@@ -304,8 +310,9 @@ const GROUPS = [
             },
             {
                 name: "checks timings",
-                usage: "checks timings",
-                desc: "Show recent check durations and the slowest test files",
+                usage: "checks timings [--tests] [--run-id ID] [--recent-runs N] [--limit N] [--offset N] [--json]",
+                desc: "Recent check durations, slowest test files, and slow individual test cases",
+                flags: "--tests · --run-id ID · --recent-runs N · --limit N · --offset N · --json",
             },
             {
                 name: "checks slots",

package/dist/cli/index.js

@@ -27,7 +27,7 @@ import { cmdCertify } from "../commands/certify.js";
 import { cmdSupport } from "../commands/support.js";
 import { cmdService } from "../commands/service.js";
 import { cmdServers } from "../commands/servers.js";
-import { cmdAgentsRunning, cmdConfig, cmdDone, cmdLandable, cmdMessage, cmdSendBack, cmdOverride, cmdPause, cmdPreview, cmdDev, cmdReview, cmdVerify, cmdRunners, cmdStart, cmdSync, cmdStats, cmdDecisions, cmdApi, cmdIntegration, cmdAttention, cmdHold, cmdUnhold, } from "../commands/control-api.js";
+import { cmdAgentsRunning, cmdConfig, cmdDone, cmdLandable, cmdHandoffStatus, cmdMessage, cmdSendBack, cmdOverride, cmdPause, cmdPreview, cmdDev, cmdReview, cmdVerify, cmdRunners, cmdStart, cmdSync, cmdStats, cmdDecisions, cmdApi, cmdIntegration, cmdAttention, cmdHold, cmdUnhold, } from "../commands/control-api.js";
 import { cmdWatch } from "../commands/watch.js";
 import { cmdDriver } from "../commands/driver.js";
 import { cmdBundle } from "../commands/bundle.js";
@@ -327,6 +327,12 @@ function main() {
                     process.exitCode = code;
             });
             break;
+        case "handoff-status":
+            void cmdHandoffStatus(rest).then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            });
+            break;
         case "override":
             void cmdOverride(rest).then((code) => {
                 if (code !== 0)

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

@@ -43,6 +43,7 @@ export declare class RepoOsApi {
     fetchEventStream(): Promise<Response>;
     request(method: string, path: string, body?: unknown, opts?: {
         retryAuth?: boolean;
+        timeoutMs?: number;
     }): Promise<{
         status: number;
         body: ApiJson;

package/dist/cli/repoos-api.js

@@ -127,6 +127,7 @@ export class RepoOsApi {
                     method,
                     headers: this.buildHeaders(jsonBody),
                     body: jsonBody ? JSON.stringify(body) : undefined,
+                    signal: opts.timeoutMs && opts.timeoutMs > 0 ? AbortSignal.timeout(opts.timeoutMs) : undefined,
                 });
             }
             catch (err) {

package/dist/commands/check.d.ts

@@ -1,4 +1,5 @@
 import { type TestFileTiming } from "../core/test-file-timings.js";
+import { type TestCaseTiming } from "../core/test-case-timings.js";
 import type { CheckContrastPair, CheckThemeScope, RepoOSConfig } from "../core/types.js";
 import { type CheckPlan, type CheckStep } from "../core/check-plan.js";
 import { type StepRunResult, type StepStatus } from "../core/check-runner.js";
@@ -275,6 +276,7 @@ interface StepContext {
 /** What a built-in `kind` handler returns. */
 interface BuiltinOutcome {
     testFileTimings?: TestFileTiming[];
+    testCaseTimings?: TestCaseTiming[];
     status: StepStatus;
     /** The command it resolved to (so the results block can name it). */
     command?: string;

package/dist/commands/check.js

@@ -33,6 +33,7 @@ import { cpus, totalmem } from "node:os";
 import { isAbsolute, join, relative, sep } from "node:path";
 import { c } from "../cli/colors.js";
 import { TestFileTimingCollector, testFileTimings, formatSlowestTestFiles, } from "../core/test-file-timings.js";
+import { TestCaseTimingCollector, formatSlowestTestCases, mergeTestCaseTimings, pushTimingOutputChunk, } from "../core/test-case-timings.js";
 import { checkBuildForRoot } from "../core/build.js";
 import { findRepoRoot, loadConfig } from "../core/config.js";
 import { availableMemBytes } from "../core/sysmem.js";
@@ -1403,6 +1404,10 @@ async function stepTests(ctx) {
             : "skipped — test suite ran on the remote validation runner (REPOOS_SKIP_TESTS=1)");
     }
     const fileTimingCollector = new TestFileTimingCollector();
+    const caseTimingCollector = new TestCaseTimingCollector();
+    const onTimingChunk = (chunk) => {
+        pushTimingOutputChunk(chunk, fileTimingCollector, caseTimingCollector);
+    };
     const hasTestScript = Boolean(ctx.scriptPkg.scripts?.test);
     const hasTestFiles = ["test", "__tests__", "tests"].some((d) => existsSync(join(ctx.cwd, d)));
     if (!hasTestScript && !hasTestFiles)
@@ -1441,7 +1446,7 @@ async function stepTests(ctx) {
         console.log(c.dim(`  · previously-failed test file(s) first · ${priorFiles.join(", ")}`));
         const pre = await runCommand({
             command: preflight,
-            onChunk: (chunk) => fileTimingCollector.push(chunk),
+            onChunk: onTimingChunk,
             cwd: ctx.cwd,
             timeoutMs: 300_000,
             env,
@@ -1455,6 +1460,7 @@ async function stepTests(ctx) {
                 status: pre.status === "timeout" ? "timeout" : "failed",
                 command: preflight,
                 testFileTimings: fileTimingCollector.values(),
+                testCaseTimings: caseTimingCollector.values(),
                 detail: `previously-failed test file(s) still fail — ${why}`,
                 output: pre.output,
             };
@@ -1478,13 +1484,14 @@ async function stepTests(ctx) {
         timeoutMs,
         env,
         echo: ctx.echo,
-        onChunk: (chunk) => fileTimingCollector.push(chunk),
+        onChunk: onTimingChunk,
     });
     if (res.status === "passed") {
         return {
             status: "passed",
             command,
             testFileTimings: fileTimingCollector.values(),
+            testCaseTimings: caseTimingCollector.values(),
             detail: changedRef ? `scoped to changed vs ${changedRef} plus always-run suites` : undefined,
             output: res.output,
         };
@@ -1493,6 +1500,7 @@ async function stepTests(ctx) {
         return {
             status: "timeout",
             testFileTimings: fileTimingCollector.values(),
+            testCaseTimings: caseTimingCollector.values(),
             command,
             detail: `timed out after ${timeoutLabel(timeoutMs)}`,
             output: res.output,
@@ -1504,6 +1512,7 @@ async function stepTests(ctx) {
     return {
         status: "failed",
         testFileTimings: fileTimingCollector.values(),
+        testCaseTimings: caseTimingCollector.values(),
         command,
         detail: outputTail(res.output) ?? `Tests failed (exit ${res.exitCode})`,
         output: res.output,
@@ -1822,6 +1831,7 @@ export async function runCheckPlan(plan, opts) {
             required: step.required,
             isolationNote: outcome.isolationNote,
             testFileTimings: outcome.testFileTimings,
+            testCaseTimings: outcome.testCaseTimings,
         });
     }
     return results;
@@ -2142,12 +2152,27 @@ export async function cmdCheck(argv = []) {
         console.log(c.red(`\n  ✗ ${msg}\n`));
         const holders = inspectCrossProcessSlots(localCheckLockRoot(repoRoot, cfg.cacheDir ?? ".repoos"));
         for (const holder of holders) {
-            console.log(c.dim(`  slot ${holder.slot}: pid ${holder.pid ?? "unknown"}, ${Math.round(holder.ageMs / 1000)}s${holder.dead ? " (dead; reclaiming)" : holder.wedged ? " (possibly wedged)" : ""}`));
+            console.log(c.dim(`  slot ${holder.slot}: pid ${holder.pid ?? "unknown"}, ${Math.round(holder.ageMs / 1000)}s${holder.dead ? " (process exited; reclaiming)" : holder.wedged ? ` (no recent heartbeat; last seen ${Math.round(holder.heartbeatAgeMs / 1000)}s ago)` : ""}`));
         }
         process.exit(1);
     }
     waitRecord = waits.finish();
     const runStartedAt = new Date();
+    // Persist a provisional row before running steps. If this process is killed,
+    // the durable history still shows an interrupted run instead of no run.
+    const historyRunId = recordRunHistoryRow({
+        root: checkStoreRoot,
+        cacheDir: cfg.cacheDir,
+        attribution: runContext,
+        scope: changedRef ? `changed:${changedRef}` : "full",
+        worktree: repoRoot,
+        startedAt: runStartedAt.toISOString(),
+        durationMs: 0,
+        outcome: "cancelled",
+        failedStep: "check",
+        skippedSteps: [],
+        detail: "Check was interrupted before completion.",
+    });
     // Failed-first ordering (#0655): only interactive/CLI and pre-review runs
     // reorder. Close-out and release run their selected suite from a clean
     // slate, and the remote close-out gate never reaches this point. Attribution
@@ -2231,6 +2256,7 @@ export async function cmdCheck(argv = []) {
             skippedSteps: [],
             steps: completedSteps,
             detail: `check crashed before completing: ${e.message}`,
+            updateId: historyRunId,
         });
         throw e;
     }
@@ -2290,9 +2316,17 @@ export async function cmdCheck(argv = []) {
         }
     }
     const fileTimings = results.flatMap((r) => r.testFileTimings ?? testFileTimings(r.output ?? ""));
+    // Individual case history comes only from Vitest's structured reporter
+    // events. Step output is intentionally bounded and must never be its source.
+    const caseTimings = mergeTestCaseTimings(results.flatMap((r) => r.testCaseTimings ?? []));
     if (fileTimings.length) {
         heading("Slowest test files");
         console.log(formatSlowestTestFiles(fileTimings));
+        console.log(c.dim("  File totals include hook time in that file; they are not the sum of individual cases below."));
+    }
+    if (caseTimings.length) {
+        heading("Slowest test cases");
+        console.log(formatSlowestTestCases(caseTimings));
     }
     // Persist the run for the Checks surface (#0447) before exiting. Fail-soft:
     // visibility only, never a reason to fail an otherwise-green gate.
@@ -2352,6 +2386,7 @@ export async function cmdCheck(argv = []) {
             durationMs: r.durationMs,
             output: r.output,
             testFileTimings: r.testFileTimings,
+            testCaseTimings: r.testCaseTimings,
             detail: r.detail,
             required: r.required,
         })),
@@ -2377,6 +2412,7 @@ export async function cmdCheck(argv = []) {
         stepsDone: finalProgress?.stepsDone ?? null,
         stepsTotal: finalProgress?.stepsTotal ?? null,
         testFileTimings: fileTimings,
+        testCaseTimings: caseTimings,
         testsDone: testProgress?.testsDone ?? null,
         testsTotal: testProgress?.testsTotal ?? null,
         detail: (() => {
@@ -2403,6 +2439,7 @@ export async function cmdCheck(argv = []) {
         failedTests: gatingFailures.flatMap((r) => extractFailedTests(r.output ?? "")),
         // Informational isolation label (#0655) — never part of the outcome.
         isolationNote: results.find((r) => r.isolationNote)?.isolationNote ?? null,
+        updateId: historyRunId,
     });
     process.exit(gatingFailures.length > 0 ? 1 : 0);
 }
@@ -2438,7 +2475,8 @@ export function previousFailedTestsForRun(opts) {
 function recordRunHistoryRow(row) {
     try {
         const { taskId, phase } = row.attribution;
-        getCheckStore(row.root, row.cacheDir).record({
+        const store = getCheckStore(row.root, row.cacheDir);
+        const input = {
             taskId,
             phase,
             worktree: row.worktree,
@@ -2463,10 +2501,17 @@ function recordRunHistoryRow(row) {
             testsTotal: row.testsTotal,
             steps: row.steps,
             testFileTimings: row.testFileTimings,
-        });
+            testCaseTimings: row.testCaseTimings,
+        };
+        if (row.updateId != null) {
+            store.update(row.updateId, input);
+            return row.updateId;
+        }
+        return store.record(input);
     }
     catch {
         /* never fail the gate on a history write */
+        return null;
     }
 }
 /**

package/dist/commands/checks.js

@@ -1,32 +1,110 @@
-import { getCheckStore } from "../core/check-store.js";
+import { DEFAULT_TEST_CASE_LIST_LIMIT, getCheckStore, MAX_TEST_CASE_LIST_LIMIT, } from "../core/check-store.js";
 import { formatSlowestTestFiles } from "../core/test-file-timings.js";
+import { formatSlowestTestCases } from "../core/test-case-timings.js";
 import { c } from "../cli/colors.js";
 import { loadConfig } from "../core/config.js";
 import { inspectCrossProcessSlots, listSlotWaiterPids, localCheckLockRoot, releaseLocalCheckSlot, } from "../core/cross-process-slots.js";
 import { currentQueueMarkers, readQueueMarkers } from "../core/local-queue-marker.js";
 import { mainCheckoutRoot } from "../core/git.js";
 import { heavySlotLimit } from "../core/resource-limits.js";
-export function cmdChecks(args) {
-    if (args[0] === "timings") {
-        const config = loadConfig();
-        let root = config.root;
-        try {
-            root = mainCheckoutRoot(root);
+function resolveChecksRoot() {
+    const config = loadConfig();
+    try {
+        return mainCheckoutRoot(config.root);
+    }
+    catch {
+        return config.root;
+    }
+}
+function parseTimingsFlags(args) {
+    let json = false;
+    let tests = false;
+    let runId;
+    let recentRuns = 10;
+    let limit = DEFAULT_TEST_CASE_LIST_LIMIT;
+    let offset = 0;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            json = true;
+        else if (a === "--tests" || a === "tests")
+            tests = true;
+        else if (a === "--run-id" || a === "--run") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                runId = Math.floor(n);
+        }
+        else if (a === "--recent-runs" || a === "--recent") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                recentRuns = Math.min(100, Math.floor(n));
         }
-        catch {
-            /* standalone */
+        else if (a === "--limit") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n > 0)
+                limit = Math.min(MAX_TEST_CASE_LIST_LIMIT, Math.floor(n));
         }
-        for (const run of getCheckStore(root, config.cacheDir).list({ limit: 10 })) {
-            console.log(`${run.startedAt} · ${run.phase} · ${run.machine ?? "local"} · ${run.scope} · ${((run.durationMs ?? 0) / 1000).toFixed(1)}s`);
-            if (run.testFileTimings?.length) {
-                console.log("Slowest test files (test + hook time):");
-                console.log(formatSlowestTestFiles(run.testFileTimings));
-            }
+        else if (a === "--offset") {
+            const n = Number(args[++i]);
+            if (Number.isFinite(n) && n >= 0)
+                offset = Math.floor(n);
         }
+    }
+    return { json, tests, runId, recentRuns, limit, offset };
+}
+function cmdChecksTimings(args) {
+    const config = loadConfig();
+    const root = resolveChecksRoot();
+    const flags = parseTimingsFlags(args);
+    const store = getCheckStore(root, config.cacheDir);
+    if (flags.tests) {
+        const result = store.listSlowTestCases({
+            runId: flags.runId,
+            recentRuns: flags.recentRuns,
+            limit: flags.limit,
+            offset: flags.offset,
+        });
+        if (flags.json) {
+            console.log(JSON.stringify({ ok: true, ...result }, null, 0));
+            return;
+        }
+        const scope = flags.runId != null
+            ? `run #${flags.runId}`
+            : `last ${result.recentRuns ?? flags.recentRuns} run(s)`;
+        console.log(`Slowest test cases (including beforeEach/afterEach hooks) · ${scope} · limit ${result.limit} offset ${result.offset}`);
+        if (!result.cases.length) {
+            console.log("  (no recorded cases — run repoos check after upgrading)");
+            return;
+        }
+        console.log(formatSlowestTestCases(result.cases.map(({ file, name, durationMs, result: outcome, retry, caseId }) => ({
+            file,
+            name,
+            caseId,
+            retry,
+            durationMs,
+            result: outcome,
+        })), result.limit));
+        if (result.hasMore) {
+            console.log(c.dim(`  … more rows available (hasMore)`));
+        }
+        return;
+    }
+    for (const run of store.list({ limit: 10 })) {
+        console.log(`${run.startedAt} · ${run.phase} · ${run.machine ?? "local"} · ${run.scope} · ${((run.durationMs ?? 0) / 1000).toFixed(1)}s · run #${run.id}`);
+        if (run.testFileTimings?.length) {
+            console.log("Slowest test files (test + hook time in file):");
+            console.log(formatSlowestTestFiles(run.testFileTimings));
+        }
+    }
+    console.log(c.dim("\nIndividual cases: repoos checks timings --tests [--run-id ID] [--recent-runs N] [--limit N] [--offset N] [--json]"));
+}
+export function cmdChecks(args) {
+    if (args[0] === "timings") {
+        cmdChecksTimings(args.slice(1));
         return;
     }
     if (args[0] !== "slots") {
-        console.error("Usage: repoos checks timings | slots [--release SLOT --confirm PID]");
+        console.error("Usage: repoos checks timings [--tests] [--run-id ID] [--recent-runs N] [--limit N] [--offset N] [--json] | slots [--release SLOT --confirm PID]");
         process.exitCode = 2;
         return;
     }
@@ -54,7 +132,7 @@ export function cmdChecks(args) {
             const holder = inspectCrossProcessSlots(root, heavySlotLimit(config), config.localChecks?.staleAfterMs).find((item) => item.slot === slot);
             if (!holder?.pid)
                 throw new Error(`slot ${slot} is free`);
-            console.log(`Releasing slot ${slot}, held by task #${String(holder.meta?.taskId ?? "unknown")} check, PID ${holder.pid}${holder.dead ? ", dead" : holder.wedged ? ", wedged" : ", alive"}.`);
+            console.log(`Releasing slot ${slot}, held by task #${String(holder.meta?.taskId ?? "unknown")} check, PID ${holder.pid}${holder.dead ? ", process exited" : holder.wedged ? `, no recent heartbeat (last seen ${Math.round(holder.heartbeatAgeMs / 1000)}s ago)` : ", alive"}.`);
             releaseLocalCheckSlot(root, slot, pid, config.localChecks?.staleAfterMs);
             console.log(c.green("  ✔ Slot released."));
         }
@@ -70,7 +148,7 @@ export function cmdChecks(args) {
             ? `#${String(holder.meta.taskId)} check`
             : "unattributed check";
         console.log(holder.pid
-            ? `slot ${holder.slot}: ${task}, pid ${holder.pid}, ${holder.dead ? "dead, reclaiming" : holder.wedged ? "wedged" : "alive"}, held ${Math.round(holder.ageMs / 1000)}s, heartbeat ${Math.round(holder.heartbeatAgeMs / 1000)}s ago`
+            ? `slot ${holder.slot}: ${task}, pid ${holder.pid}, ${holder.dead ? "process exited, reclaiming" : holder.wedged ? `no recent heartbeat (last seen ${Math.round(holder.heartbeatAgeMs / 1000)}s ago)` : "alive"}, held ${Math.round(holder.ageMs / 1000)}s, heartbeat ${Math.round(holder.heartbeatAgeMs / 1000)}s ago`
             : `slot ${holder.slot}: free`);
     }
     const queue = currentQueueMarkers(readQueueMarkers(boardRoot, cacheDir).filter((entry) => entry.kind === "local-check"), listSlotWaiterPids(root));

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

@@ -83,6 +83,12 @@ interface StatsGitJobView {
     ageMs?: number;
 }
 export declare function printSystemSummary(system: StatsSystemView): void;
+/**
+ * `repoos handoff-status <id>` (#1028): print the latest handoff attempt's
+ * state immediately. Never waits for, starts, or alters a handoff — safe to
+ * call from an engineer that is unsure whether its request reached the server.
+ */
+export declare function cmdHandoffStatus(args: string[]): Promise<number>;
 /**
  * `repoos landable <id>` (#0867): print the read-only landing pre-checks and
  * exit 0 only when every check passes. Never edits, commits or moves status.

package/dist/commands/control-api.js

@@ -179,9 +179,9 @@ export async function cmdHold(args) {
         return 1;
     }
     const api = new RepoOsApi({ port: opts.port });
-    // #0960 input validation (mirrors the API guard): a hold needs a reason so it
-    // is visible on the board, and `--until` must be a real date or it would
-    // never auto-release and become a permanent hold.
+    // #0960: the CLI still requires `--reason`. The HTTP hold route accepts a
+    // missing reason (#1033). `--until` must be a real date or it would never
+    // auto-release and become a permanent hold.
     if (!opts.reason || !opts.reason.trim()) {
         printErr("hold requires a --reason (free text documenting why the task is parked)");
         return 1;
@@ -738,7 +738,7 @@ export async function cmdDone(args) {
                 console.log(`${result.status >= 200 && result.status < 300 ? c.green("  ✓ ") : c.yellow("  · ")}${message} (HTTP ${result.status})`);
             return (result.status >= 200 && result.status < 300) || result.status === 409 ? 0 : 1;
         }
-        const started = await api.request("POST", `/api/tasks/${id}/done`, { commitDirty });
+        const started = await api.request("POST", `/api/tasks/${id}/done`, { commitDirty }, { timeoutMs: 0 });
         if (started.status === 409 && started.body.needsCommit) {
             throw new RepoOsApiError(started.body.error ?? "close-out blocked on dirty tree", 409, started.body);
         }
@@ -1506,6 +1506,56 @@ function landableIcon(status) {
         return c.yellow("!");
     return c.red("✗");
 }
+/**
+ * `repoos handoff-status <id>` (#1028): print the latest handoff attempt's
+ * state immediately. Never waits for, starts, or alters a handoff — safe to
+ * call from an engineer that is unsure whether its request reached the server.
+ */
+export async function cmdHandoffStatus(args) {
+    const { rest, opts, error } = parseCommonFlags(args);
+    if (error) {
+        printErr(error);
+        return 1;
+    }
+    const id = rest[0];
+    if (!id) {
+        printErr("Usage: repoos handoff-status <id> [--json] [--port N]");
+        return 1;
+    }
+    const api = new RepoOsApi({ port: opts.port });
+    try {
+        await ensureServer(api);
+        const status = (await api.requestOk("GET", `/api/tasks/${id}/handoff-status`));
+        if (opts.json) {
+            printJson(status);
+            return 0;
+        }
+        const label = status.state === "passed"
+            ? c.green("passed")
+            : status.state === "failed"
+                ? c.red("failed")
+                : status.state === "running"
+                    ? c.yellow("running")
+                    : status.state === "deferred"
+                        ? c.yellow("deferred")
+                        : c.dim("not requested");
+        console.log(`  ${c.bold(`#${id}`)} handoff: ${label}`);
+        if (status.step)
+            console.log(`    step:   ${status.step}`);
+        if (status.reason)
+            console.log(`    reason: ${status.reason}`);
+        if (status.updatedAt)
+            console.log(`    at:     ${status.updatedAt}`);
+        if (status.state === "not_requested") {
+            console.log(c.dim(`    no handoff has been requested for this task (request it with \`repoos mv ${id} review\`)`));
+        }
+        return 0;
+    }
+    catch (e) {
+        printErr(e.message);
+        return 1;
+    }
+}
 /**
  * `repoos landable <id>` (#0867): print the read-only landing pre-checks and
  * exit 0 only when every check passes. Never edits, commits or moves status.
@@ -1529,8 +1579,8 @@ export async function cmdLandable(args) {
             printJson(result);
         else {
             const verdict = result.landable
-                ? c.green(`#${id} is landable`)
-                : c.red(`#${id} is not landable yet`);
+                ? c.green(`#${id} is ready to merge`)
+                : c.red(`#${id} is not ready to merge yet`);
             console.log(`  ${verdict}`);
             for (const check of result.checks) {
                 console.log(`    ${landableIcon(check.status)} ${c.bold(check.label)} — ${check.detail}`);

package/dist/commands/docs.js

@@ -5,6 +5,7 @@ import { readFileSync } from "node:fs";
 import { createDocument, createFreeformDocument, docFreeformPrompt, parseGeneratedDocument, } from "../core/docs.js";
 import { loadConfig } from "../core/config.js";
 import { c } from "../cli/colors.js";
+import { repoAgentRunTmpOpts } from "../core/agent-run-tmpdir.js";
 import { resolvePmAgent, runPrompt, recordOneShotSession } from "../server/agents.js";
 import { currentDocsDir, importDocsInto, scaffoldDocsInto } from "./docs-io.js";
 /** `repoos new-doc "<description>"` or `repoos new-doc --path docs/foo.md --content-file x.md` */
@@ -34,6 +35,7 @@ export async function cmdNewDoc(args) {
             const docResult = await createFreeformDocument(config, description, async (desc) => {
                 const result = await runPrompt(pm, docFreeformPrompt(desc), {
                     cwd: config.root,
+                    ...repoAgentRunTmpOpts(config),
                 });
                 // Freeform doc authoring is real PM spend that belongs to no task (0311).
                 recordOneShotSession(config.root, pm, result, { sessionType: "pm", taskId: null });