@repo-os/repoos 0.5.56 → 0.5.57

package/dist/.build-info.json

@@ -1,4 +1,5 @@
 {
-  "hash": "f30fcce6f5c1d53000699830d693eabb1921532ae40f9462a44af88519527c92",
-  "version": "0.5.56"
+  "hash": "69cefc15aead79d33e1a4fcf9b4d8d1358152d8f214530f3af45226fbe121036",
+  "version": "0.5.57",
+  "devUi": false
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-26T09:59:53.699Z"
+  "generatedAt": "2026-09-29T11:51:40.533Z"
 }

package/dist/cli/index.js

@@ -20,7 +20,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";
@@ -147,6 +147,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

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,11 @@ 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 { 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 +504,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 +683,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 +757,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 +1334,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 +1396,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 +1625,59 @@ 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,
+    });
     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,
+        });
+    }
+    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.js

@@ -158,42 +158,47 @@ repo itself is the source of truth. This file tells AI agents how to operate.
 
 ## Operating loop
 
-1. Read this file and any relevant docs under \`${docsDir}/\`.
-2. Pick a task from \`${workDir}/\` whose \`status: ready\`.
-3. Set its \`status: active\` (edit the frontmatter; do not move the file).
-4. Create a worktree on the branch named in the task's \`branch:\` field, or set one.
-5. Run \`repoos check\` and confirm it passes, then implement → test → if the repo
-   has a git remote, open an MR/PR against main.
-6. When ready for human sign-off, run \`repoos mv <id> review\` and stop. **That
-   records a handoff request; it does not set the status.** RepoOS re-runs the
-   check, commits the branch and moves the task to \`review\`. The task stays
-   \`active\` until then, and stays \`active\` with the failure shown if the check
-   fails. **Leave the worktree open; do NOT merge its branch.**
+For a RepoOS-managed task runner:
+
+1. Read this file, your assigned task under \`${workDir}/\`, and relevant
+   project docs under \`${docsDir}/\`.
+2. Work in the task branch and dedicated worktree RepoOS assigned. The server
+   owns activation and worktree setup; do not claim another task or edit its
+   frontmatter directly.
+3. Implement the task, update directly affected docs, and run
+   \`repoos check --changed main\`. It must pass before handoff.
+4. Request handoff with \`repoos mv <id> review\` or finish your reply with
+   \`::repoos-handoff-ready::\`, then end your turn. In your own runner session,
+   both record a request without changing status. RepoOS commits the branch,
+   runs checks, verifies the tested tree stayed unchanged, and then moves the
+   task to \`review\`. Failure leaves it \`active\` with the reason shown.
+5. Leave the worktree open and stop. Do not merge the branch or mark it done.
+   Requested fixes continue on the same worktree with another checked handoff.
+
+Interactive agents helping on a task use its same branch/worktree and the
+same review/close-out workflow. Coordinate with any live engineer/reviewer
+before editing. Outside a managed runner, \`repoos mv <id> review\` writes
+metadata that the server intercepts asynchronously; wait for finalization,
+not just the CLI command's return. Runner-only signals do not apply there.
 
 ## Review and sign-off
 
-A \`review\` task stays in its open worktree until a human (or another AI) signs
-off; the implementer never merges to \`main\` at \`review\` time.
+RepoOS owns review and close-out whether or not this repo has a Git remote.
+Do not open a PR, push a task branch, or substitute GitHub approval/merge
+unless the human explicitly requests that separate workflow.
 
-Every route into \`review\` — the Review button, a board drag, a
-\`PATCH status: review\`, \`repoos mv\`, or an agent's handoff signal — runs the
-same finalization: scoped \`repoos check\`, then the commit guard, then
-\`review\`. Nothing reaches \`review\` on the commit guard alone.
+The reviewer agent, when enabled, writes an advisory report in the task drawer.
+It does not edit code or replace human approval. After the human approves,
+use **Move to done** in RepoOS or \`POST /api/tasks/:id/done\`. The server
+merges the task into a separate candidate worktree, validates the combined
+result, rechecks the primary branch under a publication lock, publishes,
+cleans up, and records completion. \`repoos mv <id> done\` only changes metadata;
+it does not run close-out or merge code.
 
-- No git remote: on approval, the reviewer says **"move task <id> to done"**. The
-  implementer then sets \`status: done\` (commit \`docs(<id>): set status done\`),
-  fast-forward merges the branch to \`main\`, removes the worktree, and deletes
-  the branch.
-- With a git remote: an MR/PR is opened against \`main\` at \`review\` time. On
-  approval it is merged by the reviewer (or by the implementer only on "move task
-  <id> to done"), then remote + local branches are deleted and \`status\` is set
-  to \`done\`.
-- Requested changes are fixed on the same worktree, tests re-run, and the task
-  handed off again.
-- If the \`reviewer\` agent is enabled on the Agents page, RepoOS reviews the
-  task automatically when it lands in \`review\` and shows a short report (bugs,
-  edge cases, suggestions) in the task drawer. It is advisory: the human still
-  reviews and is the only one who moves a task to \`done\`.
+A direct commit on the primary branch is an exception requiring explicit
+human authorization. If that already-landed work has a branchless task record,
+the \`/done\` endpoint can check the primary checkout and record release without
+a candidate merge. Do not erase a task's branch metadata to force this path.
 
 ## Rules
 
@@ -246,8 +251,9 @@ export const REPOOS_AGENTS_SECTION = (workDir) => `${REPOOS_AGENTS_SECTION_MARKE
 RepoOS keeps tasks as Markdown under \`${workDir}/\` and runs task work in dedicated
 Git worktrees. Use the RepoOS UI or \`repoos\` commands to create and update
 tasks; do not hand-edit task files. Read the relevant project docs before
-starting work, run \`repoos check\` before handoff, and let the reviewer decide
-what merges.
+starting work, run \`repoos check\` before handoff, and await human approval
+through RepoOS's **Move to done**. The reviewer is advisory. A Git remote does
+not require a PR; close-out validates and merges through RepoOS.
 `;
 /**
  * Return the exact addition that `repoos init` may offer for an existing

package/dist/core/auth-store.d.ts

@@ -42,11 +42,57 @@ export interface AuditLogEntry {
     details: string | null;
     createdAt: string;
 }
+export interface TelegramUserLink {
+    instanceIdentity?: string;
+    telegramUserId: number;
+    email: string;
+    telegramUsername: string | null;
+    boundAt: string;
+    boundBy: string | null;
+    lastSeenAt: string | null;
+    revokedAt: string | null;
+}
+export interface TelegramChatLink {
+    instanceIdentity?: string;
+    telegramChatId: number;
+    chatType: string;
+    title: string | null;
+    boundAt: string;
+    boundBy: string;
+    revokedAt: string | null;
+    /** When false, this chat is bound but opted out of push notifications (#0537). */
+    notificationsEnabled: boolean;
+}
+export interface TelegramChatBindInvite {
+    nonceHash: string;
+    repoIdentity: string;
+    instanceIdentity: string;
+    mac: string;
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string;
+    redeemedAt: string | null;
+    redeemedChatId: number | null;
+}
+export interface TelegramLinkInvite {
+    nonceHash: string;
+    email: string;
+    repoIdentity: string;
+    instanceIdentity: string;
+    mac: string;
+    createdBy: string;
+    createdAt: string;
+    expiresAt: string;
+    redeemedAt: string | null;
+}
 export declare class AuthStore {
     private db;
     private available;
+    private instanceIdentityValue;
+    get instanceIdentity(): string;
     constructor(repoRoot: string);
     isAvailable(): boolean;
+    private migrateTelegramBindingTables;
     getUser(email: string): AuthUser | null;
     listUsers(): AuthUser[];
     upsertUser(email: string, role: AuthRole, addedBy: string | null, displayName?: string): void;
@@ -71,6 +117,8 @@ export declare class AuthStore {
     countFailedVerifyAttempts(email: string, windowSeconds: number): number;
     cleanupExpiredOtps(): number;
     logAudit(action: string, targetEmail: string | null, actorEmail: string | null, details?: string): void;
+    /** Like logAudit, but required for lifecycle events that must not report success without a row. */
+    logAuditRequired(action: string, targetEmail: string | null, actorEmail: string | null, details?: string): void;
     getAuditLog(limit?: number): AuditLogEntry[];
     createHubCapability(input: Omit<HubCapability, "tokenHash" | "revokedAt" | "lastUsedAt"> & {
         tokenHash: string;
@@ -80,11 +128,52 @@ export declare class AuthStore {
     getHubCapability(id: string): HubCapability | null;
     revokeHubCapability(id: string): boolean;
     markHubCapabilityUsed(id: string): void;
+    getTelegramLink(telegramUserId: number): TelegramUserLink | null;
+    listTelegramLinks(): TelegramUserLink[];
+    upsertTelegramLink(link: TelegramUserLink): boolean;
+    touchTelegramLinkSeen(telegramUserId: number, seenAt: string): void;
+    revokeTelegramLink(telegramUserId: number, revokedAt: string): boolean;
+    /**
+     * Revoke active user links for this instance only.
+     */
+    revokeAllActiveTelegramUserLinks(revokedAt: string): number;
+    insertTelegramInvite(invite: TelegramLinkInvite): boolean;
+    getTelegramInviteByNonceHash(nonceHash: string): TelegramLinkInvite | null;
+    /**
+     * Mark an unused invite redeemed. Returns false if the row is missing,
+     * already redeemed, or the write fails — callers treat all as replay.
+     */
+    markTelegramInviteRedeemed(nonceHash: string, redeemedAt: string): boolean;
+    cleanupExpiredTelegramInvites(): number;
+    getTelegramChatLink(telegramChatId: number): TelegramChatLink | null;
+    listTelegramChatLinks(): TelegramChatLink[];
+    upsertTelegramChatLink(link: TelegramChatLink): boolean;
+    setTelegramChatNotificationsEnabled(telegramChatId: number, enabled: boolean): boolean;
+    revokeTelegramChatLink(telegramChatId: number, revokedAt: string): boolean;
+    /** Revoke active chat links for this instance only. */
+    revokeAllActiveTelegramChatLinks(revokedAt: string): number;
+    deleteTelegramUserInvitesForInstance(instanceIdentity: string): number;
+    deleteTelegramChatBindInvitesForInstance(instanceIdentity: string): number;
+    insertTelegramChatBindInvite(invite: TelegramChatBindInvite): boolean;
+    getTelegramChatBindInviteByNonceHash(nonceHash: string): TelegramChatBindInvite | null;
+    markTelegramChatBindInviteRedeemed(nonceHash: string, redeemedAt: string, redeemedChatId: number): boolean;
+    cleanupExpiredTelegramChatBindInvites(): number;
+    /**
+     * Run `fn` inside BEGIN IMMEDIATE so invite redeem cannot race a second
+     * /start into a double bind. Nested calls are not supported — later
+     * Telegram intake (#0532/#0534) must not wrap redeemTelegramInvite in
+     * another transaction.
+     */
+    withImmediateTransaction<T>(fn: () => T): T;
     private toHubCapability;
     private toUser;
     private toSession;
     private toOtp;
     private toAuditEntry;
+    private toTelegramLink;
+    private toTelegramInvite;
+    private toTelegramChatLink;
+    private toTelegramChatBindInvite;
     close(): void;
 }
 export declare function getAuthStore(repoRoot: string): AuthStore | null;