@repo-os/repoos 0.5.56 → 0.5.58

package/README.md

@@ -96,7 +96,7 @@ install, `repoos upgrade` prints the matching package-manager command instead.
 Then in any repo:
 
 ```bash
-repoos init        # scaffold work/, docs/, repoos.toml, AGENTS.md (idempotent)
+repoos init        # scaffold repoos/work/, repoos/docs/, repoos.toml, AGENTS.md (idempotent)
 ```
 
 Zero config required. `repoos init` walks up to find your repo root, creates the
@@ -219,6 +219,14 @@ your other Tailscale devices and from localhost-only tools on the same machine
 (e.g. a Cloudflare Tunnel's local origin). Pass `--host 127.0.0.1` explicitly
 to restrict it to localhost only.
 
+In that mode `repoos serve` also runs `tailscale serve` for you and prints an
+`https://<machine>.<tailnet>.ts.net` URL. Use it: a plain-`http://` Tailscale IP
+isn't a browser secure context, so some UI features can't work there. It is
+tailnet-only (not Funnel), never overwrites another `tailscale serve` mapping
+(it falls back to port 8443, then 10000), and needs MagicDNS + HTTPS
+Certificates enabled in the Tailscale admin console (`serve` prints a hint if
+not). Pass `--no-tailscale-https` to skip it.
+
 ### Endpoints
 
 ```

package/dist/.build-info.json

@@ -1,4 +1,5 @@
 {
-  "hash": "f30fcce6f5c1d53000699830d693eabb1921532ae40f9462a44af88519527c92",
-  "version": "0.5.56"
+  "hash": "6231b4db3b8903881a94953190689ef5b00ce6583415cf10eb1b86fe1211e1f1",
+  "version": "0.5.58",
+  "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-26T09:59:53.699Z"
+  "generatedAt": "2026-09-29T22:20:00.607Z"
 }

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { cmdList, cmdShow, cmdMv, cmdUpdate, cmdNew, cmdIndex, cmdNote, } from "
 import { cmdNewDoc } from "../commands/docs.js";
 import { cmdGc } from "../commands/gc.js";
 import { cmdCheck } from "../commands/check.js";
+import { cmdShot } from "../commands/shot.js";
 import { cmdServe, serveProcessTitle, setServeProcessTitle } from "../commands/serve.js";
 import { cmdStop } from "../commands/stop.js";
 import { cmdTunnel } from "../commands/tunnel.js";
@@ -20,7 +21,7 @@ import { cmdSupport } from "../commands/support.js";
 import { cmdService } from "../commands/service.js";
 import { checkBuild } from "../core/build.js";
 import { loadConfig } from "../core/config.js";
-import { reexecUnderBunIfRequested } from "../core/runtime.js";
+import { reexecAfterStaleBuild, reexecUnderBunIfRequested } from "../core/runtime.js";
 import { c } from "./colors.js";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -89,6 +90,7 @@ function help() {
         cmdRow("check --profile full", "Run every declared step, including ones held back from a routine run"),
         cmdRow("check --changed main", "Fast pre-review pass over steps affected by changed paths"),
         cmdRow("check --print-plan", "Print the resolved plan as [[check.steps]] TOML to commit"),
+        cmdRow("shot [<route|url>]", `Capture preview screenshots into the task's shots folder   ${c.dim("flags: --target --selector --task --base --wait --full-page")}`),
         cmdRow("init [name]", "Scaffold work/, repoos.toml, AGENTS.md; outside a git repo runs a guided flow that can launch the web console"),
         cmdRow("list [status]", `Show the board (or one column: ${c.dim("inbox|ready|active|review|done")})`),
         cmdRow("status [--json]", "One-screen health snapshot: server, build freshness, board, worktrees, tunnel, git"),
@@ -103,7 +105,7 @@ function help() {
         cmdRow('new-doc "<desc>"', "Create a document from a description via PM agent"),
         cmdRow("index [--json]", "Rebuild the derived index cache"),
         cmdRow("gc [--yes|--dry-run]", "Collect leaked task worktrees/branches (done/absent tasks, integrate candidates)"),
-        cmdRow("serve [--port N]", `Start the local server (live API + SSE stream)   ${c.dim("flags: --host, --preview-overrides, --no-preview-overrides")}`),
+        cmdRow("serve [--port N]", `Start the local server (live API + SSE stream)   ${c.dim("flags: --host, --no-tailscale-https, --preview-overrides, --no-preview-overrides")}`),
         cmdRow("stop [--port N]", "Stop this repo's serve process (by its own lockfile)"),
         cmdRow("service [sub]", `Manage background services ${c.dim("list|status|install|start|stop|restart|enable|disable|remove")}`),
         cmdRow("tunnel <sub>", `Publish local apps via Cloudflare Tunnel + Zero Trust ${c.dim("(setup|create|allow|deny|rename|destroy|start|install|stop|list|status)")}`),
@@ -113,13 +115,16 @@ function help() {
     const exampleLines = [
         exRow("repoos init"),
         exRow("repoos init myproject", "guided new-project flow outside a git repo"),
-        exRow('repoos new "Add company dashboard" --ai --type feature --area web --priority p1'),
+        exRow('repoos new "Add company dashboard" --ai --type feature --area web,server --priority p1'),
         exRow('repoos new-doc "API design doc for the payment system"'),
         exRow("repoos mv 0012 active"),
         exRow('repoos mv 0012 active --note "Fix the regression in checkout; see review"'),
         exRow('repoos note 0012 "Handle the reviewer\'s suggestions before the next review"'),
-        exRow('repoos update 0012 --title "New title" --area web'),
+        exRow('repoos update 0012 --title "New title" --area web,core'),
         exRow("repoos list ready"),
+        exRow("repoos shot", "screenshot the task preview for the current worktree"),
+        exRow("repoos shot /repo/commits/abc123", "capture one route"),
+        exRow("repoos shot --target 'Docs site' --selector '.sidebar'"),
         exRow("repoos status", "one-screen health snapshot"),
         exRow("repoos status --json", "machine-readable, for agents/tools"),
         exRow("repoos index --json", "machine-readable, for agents/tools"),
@@ -147,6 +152,9 @@ function main() {
     if (reexecUnderBunIfRequested()) {
         return;
     }
+    if (reexecAfterStaleBuild()) {
+        return;
+    }
     // Name the managed project in `ps`/Activity Monitor for the long-lived serve
     // process (#0347). Done here — before the staleness check — so the one-time
     // Bun re-exec inside setServeProcessTitle can't re-print that warning, and
@@ -261,6 +269,17 @@ function main() {
         case "check":
             void cmdCheck(rest);
             break;
+        case "shot":
+            void cmdShot(rest)
+                .then((code) => {
+                if (code !== 0)
+                    process.exitCode = code;
+            })
+                .catch((err) => {
+                console.error(c.red(`  ✗ shot failed: ${err.message}`));
+                process.exitCode = 1;
+            });
+            break;
         case "tunnel":
             void cmdTunnel(rest);
             break;

package/dist/commands/check.d.ts

@@ -124,13 +124,12 @@ export declare function themeContrastOffenders(css: string, config: ThemeContras
  * actually be affected). Unset for a standalone `repoos check` — that path
  * is the full definition-of-done gate and must never narrow coverage.
  *
- * Only the two per-branch pre-merge checks set this: the engineer's own
- * self-check before requesting handoff, and the server's handoff-finalize
- * re-verification (both re-checking the SAME isolated branch, just diffed
- * against its own base). The close-out gate that validates the actual merge
- * onto main (integration-orchestrator.ts's validateCandidate) deliberately
- * never sets it — that check is about interaction with whatever else has
- * landed on main since, which a per-branch diff can't see.
+ * Set after a remote validation pass (close-out, pre-review handoff, or
+ * `repoos check` when `remoteValidation.enabled`) so the local gate skips only
+ * the Tests step. Per-branch pre-merge checks also set `REPOOS_CHECK_CHANGED`
+ * (engineer self-check and handoff re-verification). Close-out's merge-gate
+ * check deliberately never sets `REPOOS_CHECK_CHANGED` — that gate validates
+ * interaction with whatever else has landed on main since.
  */
 export declare function changedTestRef(env: NodeJS.ProcessEnv): string | undefined;
 /**
@@ -177,6 +176,8 @@ export interface CheckOptions {
     changed?: string;
     /** Print the resolved plan as `[[check.steps]]` TOML and exit 0. */
     printPlan?: boolean;
+    /** Skip the remote runner even when `remoteValidation.enabled` (#0520). */
+    localTestsOnly?: boolean;
 }
 /** Parse `repoos check` flags. Unknown flags are ignored, never fatal. */
 export declare function parseCheckArgs(argv?: string[]): CheckOptions;

package/dist/commands/check.js

@@ -31,6 +31,12 @@ import { preferBunForDevTasks } from "../core/runtime.js";
 import { blockingFailures, DEFAULT_PROFILE, describeStep, formatPlanToml, resolveCheckPlan, selectSteps, } from "../core/check-plan.js";
 import { detectRepoMarkers, missingBinaries, prereqDetail, runCommand, stepCwd, } from "../core/check-runner.js";
 import { writeCheckRun } from "../core/check-results-store.js";
+import { extractFailedTests } from "../core/check-failure-summary.js";
+import { envToRunContext, getCheckStore, localMachineName } from "../core/check-store.js";
+import { mainCheckoutRoot } from "../core/git.js";
+import { Logger } from "../core/logger.js";
+import { createRemoteValidator } from "../server/remote-validation.js";
+import { runRemotePreReviewGate, standaloneCliCanUseRemote, remoteValidationAlreadyAttempted, uncommittedFilesBlockingRemoteGate, shouldRunCliRemotePreReviewGate, } 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).
@@ -499,22 +505,12 @@ function resolveVar(value, map, depth = 0) {
     const next = map[`--${m[1]}`];
     return next !== undefined ? resolveVar(next, map, depth + 1) : value;
 }
-// KNOWN LIMITATION (fix tracked in #0504, found while registering the gruvbox
-// theme in #0503): the rgb()/rgba() branches below tolerate no whitespace between
-// components, but oxfmt writes `rgba(110, 157, 106, 0.22)` with spaces, so every
-// spaced literal fails to parse and returns null. A pair whose fg or bg yields no
-// candidates is SKIPPED rather than failed, so a `[check] contrastPairs` bg token
-// written as a spaced `rgba()` is silently never checked — as are the spaced
-// `rgba()` stops inside a gradient, which drop out of `colorCandidates`. Measured
-// on this repo's own stylesheet: 425 spaced literals, leaving 4-6 of the 9
-// configured pairs unchecked in every theme. A whitespace-tolerant regex (`\s*`
-// after each separator) was measured to produce ZERO new offenders across all five
-// themes, so the fix is a one-liner that only strengthens the gate. It is its own
-// task rather than folded into a theme change because it alters the guard's
-// behaviour repo-wide and for every project that configures
-// `[check] contrastPairs`. Until it lands, do not rely on this guard to catch a
-// contrast problem in a token written as `rgba(r, g, b, a)`; gruvbox deliberately
-// uses 8-digit hex for its checked alpha tokens to stay verifiable.
+// Both rgb()/rgba() forms are whitespace-tolerant (`\s*` after each separator),
+// so a formatter's `rgba(110, 157, 106, 0.22)` parses (#0504). Before that fix
+// these branches tolerated no whitespace, which silently skipped any
+// contrastPairs whose colour could not be read; if you ever loosen them again,
+// a pair that fails to parse is SKIPPED rather than failed, so re-run the real
+// guard against the real stylesheet rather than reasoning about it.
 function parseColor(v) {
     const s = v.trim().toLowerCase();
     if (!s || s === "none")
@@ -688,13 +684,12 @@ export function themeContrastOffenders(css, config) {
  * actually be affected). Unset for a standalone `repoos check` — that path
  * is the full definition-of-done gate and must never narrow coverage.
  *
- * Only the two per-branch pre-merge checks set this: the engineer's own
- * self-check before requesting handoff, and the server's handoff-finalize
- * re-verification (both re-checking the SAME isolated branch, just diffed
- * against its own base). The close-out gate that validates the actual merge
- * onto main (integration-orchestrator.ts's validateCandidate) deliberately
- * never sets it — that check is about interaction with whatever else has
- * landed on main since, which a per-branch diff can't see.
+ * Set after a remote validation pass (close-out, pre-review handoff, or
+ * `repoos check` when `remoteValidation.enabled`) so the local gate skips only
+ * the Tests step. Per-branch pre-merge checks also set `REPOOS_CHECK_CHANGED`
+ * (engineer self-check and handoff re-verification). Close-out's merge-gate
+ * check deliberately never sets `REPOOS_CHECK_CHANGED` — that gate validates
+ * interaction with whatever else has landed on main since.
  */
 export function changedTestRef(env) {
     const ref = env.REPOOS_CHECK_CHANGED;
@@ -763,6 +758,8 @@ export function parseCheckArgs(argv = []) {
             opts.changed = argv[++i];
         else if (a === "--print-plan")
             opts.printPlan = true;
+        else if (a === "--local-tests")
+            opts.localTestsOnly = true;
     }
     return opts;
 }
@@ -1338,6 +1335,16 @@ export async function runCheckPlan(plan, opts) {
 export async function cmdCheck(argv = []) {
     const opts = parseCheckArgs(argv);
     const repoRoot = findRepoRoot();
+    // Where this run's history row(s) go (#0564 review): the MAIN checkout's
+    // `.repoos/checks.db`, the one store the running server reads. A standalone
+    // `repoos check` inside a task worktree used to write to the worktree's own
+    // file, so an agent's self-check never appeared in Checks → Runs. An
+    // explicit REPOOS_CHECK_STORE_ROOT (server-spawned paths) already points at
+    // the main root and wins. Deliberately a local value, NOT a process.env
+    // write: an exported env var reaches every child this command spawns —
+    // including the test suite, whose own check-store fixtures would then
+    // record into this repo's live store instead of their own tmp ones.
+    const checkStoreRoot = resolveCheckStoreRoot(repoRoot);
     const cfg = loadConfig(repoRoot);
     const markers = detectRepoMarkers(repoRoot);
     const plan = resolveCheckPlan({
@@ -1390,35 +1397,186 @@ export async function cmdCheck(argv = []) {
         console.log(c.dim(`  · Changed-path mode: ${changedPaths?.length ?? 0} path(s) differ from ${changedRef} ` +
             "(fast pre-review pass — close-out still runs the full plan)"));
     }
-    const runStartedAt = new Date();
-    const results = await runCheckPlan(plan, {
-        repoRoot,
-        cfg,
-        profile,
-        // Narrowed above after the null check; `?? undefined` keeps the types
-        // honest without a cast.
-        changedPaths: changedPaths ?? undefined,
-        changedRef,
-        onStart: (step) => {
-            heading(step.name);
-            console.log(c.dim(`  · ${describeStep(step)}`));
-        },
-        onResult: (r) => {
-            const secs = r.durationMs >= 1000 ? ` (${(r.durationMs / 1000).toFixed(1)}s)` : "";
-            if (r.status === "passed") {
-                console.log(c.green(`  ✔ ${r.name}${secs}${r.detail ? ` — ${r.detail}` : ""}`));
-            }
-            else if (r.status === "skipped") {
-                console.log(c.dim(`  ⏭ ${r.name} — ${statusDetail(r)}`));
+    if (cfg.remoteValidation?.enabled &&
+        !standaloneCliCanUseRemote(cfg) &&
+        !changedRef &&
+        !opts.localTestsOnly &&
+        !remoteValidationAlreadyAttempted(process.env)) {
+        console.log(c.dim("  · remote validation: the Hetzner runner is owned by the server, so a standalone " +
+            "`repoos check` runs the full local gate (handoff and close-out still use the runner)"));
+    }
+    let runRemoteGate = shouldRunCliRemotePreReviewGate(cfg, { ...opts, changedRef }, process.env);
+    if (runRemoteGate) {
+        // The runner tests a bundle of HEAD. Uncommitted work would be skipped by it
+        // and then unverified locally (tests are skipped after a remote pass), so
+        // test the working tree locally instead and say why.
+        const uncommitted = await uncommittedFilesBlockingRemoteGate(repoRoot, cfg);
+        if (uncommitted.length > 0) {
+            runRemoteGate = false;
+            const shown = uncommitted.slice(0, 5).join(", ");
+            console.log(c.yellow(`  ⚠ uncommitted changes (${shown}${uncommitted.length > 5 ? ", …" : ""}) — the remote ` +
+                "gate tests committed HEAD only, so running the full local gate on the working tree instead\n"));
+        }
+    }
+    // The plan never runs when the remote gate fails, so the normal end-of-run
+    // record is never written: persist the failure for the Checks surface too,
+    // like a local failure and like the handoff path (fail-soft).
+    const persistRemoteFailure = (detail, output, startedAt) => {
+        const finishedAt = new Date();
+        const durationMs = finishedAt.getTime() - startedAt.getTime();
+        writeCheckRun(repoRoot, {
+            profile,
+            source: plan.source,
+            changedRef,
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs,
+            passed: false,
+            results: [
+                {
+                    name: "remote-validation",
+                    status: "failed",
+                    durationMs,
+                    output: output || undefined,
+                    detail,
+                    required: true,
+                },
+            ],
+        }, cfg.cacheDir);
+    };
+    if (runRemoteGate) {
+        heading("Remote validation");
+        const logger = new Logger({ root: repoRoot });
+        let remoteValidator;
+        try {
+            remoteValidator = createRemoteValidator(cfg, logger);
+        }
+        catch (e) {
+            const msg = `remote validation init failed: ${e.message}`;
+            if (!cfg.remoteValidation?.fallbackToLocal) {
+                console.log(c.red(`\n  ✗ ${msg}\n`));
+                persistRemoteFailure(msg, "", new Date());
+                // The runner never dispatched, so nothing else will record this
+                // failed remote attempt in the history (#0564). Record it here —
+                // machine unknown (no host was ever chosen), remote half only.
+                recordRunHistoryRow({
+                    root: checkStoreRoot,
+                    cacheDir: cfg.cacheDir,
+                    scope: "full",
+                    startedAt: new Date().toISOString(),
+                    durationMs: 0,
+                    outcome: "fail",
+                    failedStep: "remote-validation",
+                    skippedSteps: [],
+                    detail: msg,
+                });
+                process.exit(1);
             }
-            else if (!r.required) {
-                console.log(c.yellow(`  ⚠ ${r.name} failed (optional) — ${statusDetail(r)}`));
+            console.log(c.yellow(`  ⚠ ${msg} — running the full local gate\n`));
+        }
+        if (remoteValidator) {
+            // Route the runner's own history rows (recordRemoteRunHistory reads
+            // this env) to the resolved store root for THIS dispatch only, then
+            // restore — a process-wide export here would leak into the check
+            // plan's child processes (the test suite's own check-store fixtures
+            // record via the same env and would land in the live store).
+            const prevStoreRoot = process.env.REPOOS_CHECK_STORE_ROOT;
+            process.env.REPOOS_CHECK_STORE_ROOT = checkStoreRoot;
+            try {
+                const taskId = process.env.REPOOS_TASK_ID?.trim() || "pre-review";
+                const remoteStartedAt = new Date();
+                let remoteOutput = "";
+                // Which gate is calling (#0564): a caller-supplied task id means this is
+                // a pre-review pass for that task; otherwise a bare CLI run.
+                const { phase: runPhase } = envToRunContext(process.env);
+                const gate = await runRemotePreReviewGate({
+                    config: cfg,
+                    remoteValidator,
+                    worktreePath: repoRoot,
+                    taskId,
+                    phase: runPhase,
+                    onChunk: (chunk) => {
+                        remoteOutput += chunk;
+                        process.stdout.write(chunk);
+                    },
+                });
+                // Await the teardown: the failure path below exits the process, and an
+                // un-awaited async runner delete would be cut off mid-request, leaking a
+                // warm VM that no idle timer survives the exit to reap.
+                await remoteValidator.dispose().catch(() => { });
+                if (gate.kind === "fail") {
+                    console.log(c.red(`\n  ✗ ${gate.detail}\n`));
+                    persistRemoteFailure(gate.detail, remoteOutput, remoteStartedAt);
+                    process.exit(1);
+                }
+                if (gate.kind === "local-only" && gate.skipTests) {
+                    process.env.REPOOS_SKIP_TESTS = "1";
+                    console.log(c.green("  ✔ remote gate passed — running local guards only\n"));
+                }
+                else if (gate.kind === "local-only") {
+                    console.log(c.yellow("  ⚠ remote unavailable — running the full local gate\n"));
+                }
             }
-            else {
-                console.log(c.red(`  ✗ ${r.name}${secs}`));
+            finally {
+                if (prevStoreRoot === undefined)
+                    delete process.env.REPOOS_CHECK_STORE_ROOT;
+                else
+                    process.env.REPOOS_CHECK_STORE_ROOT = prevStoreRoot;
             }
-        },
-    });
+        }
+    }
+    const runStartedAt = new Date();
+    let results;
+    try {
+        results = await runCheckPlan(plan, {
+            repoRoot,
+            cfg,
+            profile,
+            // Narrowed above after the null check; `?? undefined` keeps the types
+            // honest without a cast.
+            changedPaths: changedPaths ?? undefined,
+            changedRef,
+            onStart: (step) => {
+                heading(step.name);
+                console.log(c.dim(`  · ${describeStep(step)}`));
+            },
+            onResult: (r) => {
+                const secs = r.durationMs >= 1000 ? ` (${(r.durationMs / 1000).toFixed(1)}s)` : "";
+                if (r.status === "passed") {
+                    console.log(c.green(`  ✔ ${r.name}${secs}${r.detail ? ` — ${r.detail}` : ""}`));
+                }
+                else if (r.status === "skipped") {
+                    console.log(c.dim(`  ⏭ ${r.name} — ${statusDetail(r)}`));
+                }
+                else if (!r.required) {
+                    console.log(c.yellow(`  ⚠ ${r.name} failed (optional) — ${statusDetail(r)}`));
+                }
+                else {
+                    console.log(c.red(`  ✗ ${r.name}${secs}`));
+                }
+            },
+        });
+    }
+    catch (e) {
+        // The plan runner is not expected to throw, but if it does the normal
+        // end-of-run record below never runs — and the server-side check manager
+        // records only `code === null`, so a child that dies on an unhandled
+        // error would leave NO row at all (#0564 review). Record the crash, then
+        // re-throw for the usual CLI error path.
+        const finishedAt = new Date();
+        recordRunHistoryRow({
+            root: checkStoreRoot,
+            cacheDir: cfg.cacheDir,
+            scope: changedRef ? `changed:${changedRef}` : "full",
+            startedAt: runStartedAt.toISOString(),
+            durationMs: finishedAt.getTime() - runStartedAt.getTime(),
+            outcome: "fail",
+            failedStep: "check",
+            skippedSteps: [],
+            detail: `check crashed before completing: ${e.message}`,
+        });
+        throw e;
+    }
     // ── Summary ─────────────────────────────────────────────────────────
     const gatingFailures = results.filter((r) => r.required && r.status !== "passed" && r.status !== "skipped");
     const optionalFailures = results.filter((r) => !r.required && r.status !== "passed" && r.status !== "skipped");
@@ -1468,8 +1626,63 @@ export async function cmdCheck(argv = []) {
             required: r.required,
         })),
     }, cfg.cacheDir);
+    // Record the run in the durable history (#0564). The caller (handoff,
+    // close-out, release) identifies itself via env; a bare `repoos check`
+    // records as phase "cli" with a null task id. The store lives in the MAIN
+    // checkout (resolved at the top of this command, #0564 review) so worktree
+    // runs land in the history the server reads.
+    recordRunHistoryRow({
+        root: checkStoreRoot,
+        cacheDir: cfg.cacheDir,
+        scope: changedRef ? `changed:${changedRef}` : "full",
+        startedAt: runStartedAt.toISOString(),
+        durationMs: finishedAt.getTime() - runStartedAt.getTime(),
+        outcome: gatingFailures.length === 0 ? "pass" : "fail",
+        failedStep: gatingFailures[0]?.name ?? null,
+        skippedSteps: results.filter((r) => r.status === "skipped").map((r) => r.name),
+        detail: gatingFailures[0]?.detail ?? null,
+        // 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.
+        failedTests: gatingFailures.flatMap((r) => extractFailedTests(r.output ?? "")),
+    });
     process.exit(gatingFailures.length > 0 ? 1 : 0);
 }
+/**
+ * Where a standalone run's check-run history rows belong (#0564 review): an
+ * explicit `REPOOS_CHECK_STORE_ROOT` (server-spawned paths) wins; otherwise
+ * the MAIN checkout, resolved through any linked worktree. Fail-soft.
+ */
+function resolveCheckStoreRoot(repoRoot) {
+    const envRoot = process.env.REPOOS_CHECK_STORE_ROOT?.trim();
+    return envRoot || mainCheckoutRoot(repoRoot);
+}
+/**
+ * Write one local check-run row into the durable history (#0564), attributing
+ * the caller/phase from the environment. Fail-soft: history is observability,
+ * never a gate input.
+ */
+function recordRunHistoryRow(row) {
+    try {
+        const { taskId, phase } = envToRunContext(process.env);
+        getCheckStore(row.root, row.cacheDir).record({
+            taskId,
+            phase,
+            machine: localMachineName(),
+            remote: false,
+            scope: row.scope,
+            startedAt: row.startedAt,
+            durationMs: row.durationMs,
+            outcome: row.outcome,
+            failedStep: row.failedStep,
+            skippedSteps: row.skippedSteps,
+            detail: row.detail,
+            failedTests: row.failedTests,
+        });
+    }
+    catch {
+        /* never fail the gate on a history write */
+    }
+}
 /**
  * Names of steps that already failed and therefore block their dependents.
  * A timeout or a missing prerequisite counts; an OPTIONAL step never does —

package/dist/commands/init.d.ts

@@ -1,3 +1,5 @@
+/** Blockquote every line, so a multi-line (pasted markdown) description stays one quote. */
+export declare function quoteBlock(text: string): string;
 /** Marker makes the optional existing-repo addition safe to offer repeatedly. */
 export declare const REPOOS_AGENTS_SECTION_MARKER = "<!-- repoos:managed-instructions -->";
 /**
@@ -19,7 +21,11 @@ export declare function repoOSAgentsSectionAddition(existing: string, workDir?:
 type ScaffoldLayout = string;
 /** Which starter task to seed beyond 0001 — a blank project or an existing repo. */
 type ScaffoldKind = "new" | "existing";
-export declare function scaffoldInto(root: string, description: string, layout?: ScaffoldLayout, kind?: ScaffoldKind): {
+export declare function scaffoldInto(root: string, description: string, layout?: ScaffoldLayout, kind?: ScaffoldKind, 
+/** Areas collected at init time (#0583) — real `[[areas]]` rows when given. */
+areas?: string[], 
+/** When true, scaffold commented `[[preview.targets]]` stubs for those areas. */
+previewStub?: boolean): {
     created: string[];
     skipped: string[];
 };