@repo-os/repoos 0.5.73 → 0.5.75

package/dist/.build-info.json

@@ -1,5 +1,5 @@
 {
-  "hash": "54182298d418b9bcc12c138af5d99c0470fb3a54a8a573775e600c2e37ab1669",
-  "version": "0.5.73",
+  "hash": "bd7090b8a9f41e6d39058987c990b663fd2d8e51ec58782d6dafbb41fd7e540a",
+  "version": "0.5.75",
   "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-10-29T21:23:55.474Z"
+  "generatedAt": "2026-11-04T03:49:23.103Z"
 }

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

@@ -73,6 +73,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 +116,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 +124,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,7 @@ 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",
             },
             {
@@ -304,8 +304,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/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, localCheckLockRoot, releaseLocalCheckSlot, } from "../core/cross-process-slots.js";
-import { readQueueMarkers } from "../core/local-queue-marker.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));
+        }
+        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));
+        }
+        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;
         }
-        catch {
-            /* standalone */
+        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;
         }
-        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));
-            }
+        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,13 +148,12 @@ 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`);
     }
-    for (const marker of readQueueMarkers(boardRoot, cacheDir)
-        .filter((entry) => entry.kind === "local-check")
-        .sort((a, b) => a.position - b.position)) {
+    const queue = currentQueueMarkers(readQueueMarkers(boardRoot, cacheDir).filter((entry) => entry.kind === "local-check"), listSlotWaiterPids(root));
+    queue.forEach((marker) => {
         const waitingMs = Math.max(0, Date.now() - Date.parse(marker.since));
         console.log(`queue position ${marker.position}: #${marker.taskId}, waiting ${Math.round(waitingMs / 1000)}s`);
-    }
+    });
 }

package/dist/commands/control-api.js

@@ -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);
         }
@@ -1529,8 +1529,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 });

package/dist/commands/gc.js

@@ -3,29 +3,37 @@
  *
  * Runs against the MAIN checkout (via `boardRoot()`), never a linked worktree.
  *
- *   repoos gc              prune `repoos/integrate/*` candidates + stale metadata
- *                          now, and PREVIEW the feature worktrees `--yes` would take
- *   repoos gc --yes        also remove feature worktrees/branches for done/absent
- *                          tasks (skips any with uncommitted or unmerged work)
- *   repoos gc --dry-run    show everything that would be collected, touch nothing
+ * Cleanup is automatic and safe by construction (#1004): the same sweep runs at
+ * boot and after every close-out. An operator can still inspect or force a run:
+ *
+ *   repoos gc              run the safe sweep now (candidates + resolved,
+ *                          provably-redundant feature worktrees)
+ *   repoos gc --yes        accepted for compatibility; identical to the above
+ *   repoos gc --dry-run    show candidates, retained reasons, and external
+ *                          worktrees, touching nothing
  */
 import { createRepoOS } from "../core/repoos.js";
 import { boardRoot } from "../core/config.js";
 import { c } from "../cli/colors.js";
-import { sweepStaleWorktrees } from "../core/worktree-gc.js";
+import { formatGcEntryDetails, sweepStaleWorktrees } from "../core/worktree-gc.js";
 function printReport(report, title) {
     console.log(c.bold(`  ${title}`));
-    if (report.removedWorktrees.length === 0 &&
-        report.keptDirty.length === 0 &&
-        report.errors.length === 0) {
-        console.log(c.dim("    nothing to collect"));
-    }
+    const counts = report.summary;
+    console.log(c.dim(`    ${counts.candidates} safe candidate${counts.candidates === 1 ? "" : "s"} · ` +
+        `${counts.retained} retained · ${counts.external} outside RepoOS`));
     for (const w of report.removedWorktrees) {
         const verb = report.dryRun ? "would remove" : "removed";
-        console.log(`    ${c.green(verb)} ${w.branch || c.dim("(detached)")} ${c.dim(w.path)}`);
+        console.log(`    ${c.green(verb)} ${w.branch || c.dim("(detached)")} ${c.dim(w.path)}` +
+            c.dim(` — ${w.reason}`));
     }
-    for (const k of report.keptDirty) {
+    for (const k of report.retained) {
         console.log(`    ${c.yellow("kept")}    ${k.branch || c.dim("(detached)")} ${c.dim(`— ${k.reason}`)}`);
+        const detail = formatGcEntryDetails(k);
+        if (detail)
+            console.log(c.dim(`            ${detail}`));
+    }
+    for (const e of report.external) {
+        console.log(`    ${c.dim("external")} ${e.branch || c.dim("(detached)")} ${c.dim(e.path)}`);
     }
     for (const e of report.errors) {
         console.log(`    ${c.red("error")}   ${e}`);
@@ -35,23 +43,13 @@ function printReport(report, title) {
 }
 export function cmdGc(argv) {
     const dryRun = argv.includes("--dry-run") || argv.includes("-n");
-    const yes = argv.includes("--yes") || argv.includes("-y");
+    // `--yes` is accepted as a no-op compatibility alias: the default sweep is
+    // already the same safe policy, with the same fail-closed guards.
     const { root } = boardRoot();
     const { config } = createRepoOS(root);
     if (dryRun) {
         printReport(sweepStaleWorktrees(config, { mode: "full", dryRun: true }), "gc — dry run");
         return;
     }
-    if (yes) {
-        printReport(sweepStaleWorktrees(config, { mode: "full" }), "gc");
-        return;
-    }
-    // Default: do the safe part for real, preview the rest.
-    printReport(sweepStaleWorktrees(config, { mode: "integrate-only" }), "gc — candidates + stale metadata");
-    const preview = sweepStaleWorktrees(config, { mode: "full", dryRun: true });
-    const pendingFeature = preview.removedWorktrees.filter((w) => !w.branch.startsWith("repoos/integrate/"));
-    if (pendingFeature.length || preview.keptDirty.length) {
-        console.log();
-        printReport({ ...preview, removedWorktrees: pendingFeature }, "feature worktrees — run `repoos gc --yes` to apply");
-    }
+    printReport(sweepStaleWorktrees(config, { mode: "full" }), "gc");
 }

package/dist/commands/init.js

@@ -1249,7 +1249,7 @@ async function offerAreaVocabulary(root) {
     if (areas.length === 0)
         return;
     console.log(c.dim("  Preview targets route a task preview by its area — the picker and"));
-    console.log(c.dim("  the PM prompt offer target areas automatically; see user-docs/configuration.md's Previews section."));
+    console.log(c.dim("  the PM prompt offer target areas automatically; see https://docs.repoos.org/configuration (Previews)."));
     const previewStub = await confirm("  Scaffold commented preview-target stubs for these areas?", false);
     // Do not clobber a config changed while the prompt was open.
     if (readFileSync(tomlPath, "utf8") !== original) {
@@ -1706,7 +1706,7 @@ async function guidedNewRepo(opts) {
     }
     if (areas.length) {
         console.log(c.dim("  Preview targets route a task preview by its area — the picker and"));
-        console.log(c.dim("  the PM prompt offer target areas automatically; see user-docs/configuration.md's Previews section."));
+        console.log(c.dim("  the PM prompt offer target areas automatically; see https://docs.repoos.org/configuration (Previews)."));
     }
     // Preview targets reinforce areas ("define them together"): when an area
     // vocabulary was given, offer to scaffold the commented `[[preview.targets]]`

package/dist/commands/status.d.ts

@@ -99,20 +99,49 @@ export interface StatusSnapshot {
         active: StatusActiveTask[];
     };
     worktrees: {
-        /** Registered worktrees including the main checkout. */
+        /** Registered worktrees including the main checkout and external ones. */
         count: number;
+        /** Registered worktrees RepoOS manages (excludes external ones). */
+        managedCount: number;
         warnThreshold: number;
         /** What `repoos gc --dry-run` would collect (same sweep, same inputs). */
-        leaked: Array<{
+        candidates: Array<{
             branch: string;
             path: string;
+            reason: string;
+            taskId?: string;
+            taskStatus?: string;
+            commitsAhead?: number;
+            dirtyPaths?: string[];
+            ignoredPaths?: string[];
+            changedSourcePaths?: string[];
         }>;
         /** What gc would keep, with the reason it is kept. */
-        kept: Array<{
+        retained: Array<{
+            branch: string;
+            path: string;
+            reason: string;
+            taskId?: string;
+            taskStatus?: string;
+            commitsAhead?: number;
+            dirtyPaths?: string[];
+            ignoredPaths?: string[];
+            changedSourcePaths?: string[];
+        }>;
+        /** Registered worktrees outside RepoOS's managed directory (never touched). */
+        external: Array<{
             branch: string;
             path: string;
             reason: string;
         }>;
+        /** Why a sweep could not proceed, e.g. unreadable lifecycle state. */
+        errors: string[];
+        /** Counts mirror `gc --dry-run`, so the two views agree by construction. */
+        counts: {
+            candidates: number;
+            retained: number;
+            external: number;
+        };
     };
     tunnel: {
         configured: boolean;