@repo-os/repoos 0.5.45

package/dist/server/system.js

@@ -0,0 +1,480 @@
+/**
+ * System resource sampler. Uses `node:os` for machine-wide facts and `ps` for
+ * per-process CPU/memory stats. One `ps` invocation per interval covers all
+ * tracked PIDs — never one call per process. Zero runtime dependencies.
+ *
+ * Orphan detection: a live process not in the AgentRunner registry, or whose
+ * ppid is no longer the server's pid, is marked orphaned.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { cpus, totalmem, freemem, loadavg, platform } from "node:os";
+import { availableMemBytes } from "../core/sysmem.js";
+const OWNERSHIP_FILE = "repoos-ownership.json";
+const KB = 1024;
+function safeExecFileSync(cmd, args) {
+    try {
+        return execFileSync(cmd, args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function parsePsLine(line) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 6)
+        return null;
+    const pid = Number(parts[0]);
+    const ppid = Number(parts[1]);
+    const cpuPercent = Number(parts[2]);
+    const memPercent = Number(parts[3]);
+    const rssKB = Number(parts[4]);
+    const elapsed = parts.slice(5).join(" ");
+    if (isNaN(pid) || isNaN(ppid) || isNaN(cpuPercent) || isNaN(memPercent) || isNaN(rssKB)) {
+        return null;
+    }
+    return { pid, ppid, cpuPercent, memPercent, rssKB, elapsed };
+}
+/**
+ * Parse `ps -o pid=,ppid=,%cpu=,%mem=,rss=,etime=` output into records.
+ * One `ps` call covers all PIDs at once. Export for testing.
+ */
+export function parsePsOutput(output) {
+    return output
+        .split("\n")
+        .map(parsePsLine)
+        .filter((r) => r !== null);
+}
+function machineInfo() {
+    return {
+        cpuCount: cpus().length,
+        totalMem: totalmem(),
+        freeMem: freemem(),
+        availableMem: availableMemBytes(),
+        loadavg: loadavg(),
+        platform: platform(),
+    };
+}
+let repoStatsCache = null;
+const REPO_STATS_TTL_MS = 30_000;
+/**
+ * git-derived codebase size: worktree count, tracked-file count, and total
+ * lines across tracked text files. Three `git` spawns, so memoised for 30s —
+ * the SSE loop calls this every 5s and these numbers change on the order of
+ * commits, not seconds. Returns the last good value (or null) on git failure.
+ */
+export function sampleRepoStats(root, worktreeWarnThreshold = 20) {
+    const now = Date.now();
+    if (repoStatsCache &&
+        repoStatsCache.root === root &&
+        now - repoStatsCache.at < REPO_STATS_TTL_MS) {
+        return { ...repoStatsCache.stats, worktreeWarnThreshold };
+    }
+    const worktreeOut = safeExecFileSync("git", ["-C", root, "worktree", "list", "--porcelain"]);
+    const filesOut = safeExecFileSync("git", ["-C", root, "ls-files"]);
+    if (worktreeOut === null || filesOut === null) {
+        // Git unavailable or not a repo: keep serving a stale value for THIS root,
+        // never another root's.
+        return repoStatsCache?.root === root
+            ? { ...repoStatsCache.stats, worktreeWarnThreshold }
+            : null;
+    }
+    // Empty pattern matches every line; -I skips binary files. One spawn yields
+    // `path:<linecount>` per text file.
+    const locOut = safeExecFileSync("git", ["-C", root, "grep", "-I", "--count", "-e", ""]);
+    let linesOfCode = 0;
+    if (locOut !== null) {
+        for (const line of locOut.split("\n")) {
+            const m = line.match(/:(\d+)$/);
+            if (m)
+                linesOfCode += Number(m[1]);
+        }
+    }
+    const stats = {
+        worktrees: (worktreeOut.match(/^worktree /gm) ?? []).length,
+        trackedFiles: filesOut.split("\n").filter(Boolean).length,
+        linesOfCode,
+        worktreeWarnThreshold,
+    };
+    repoStatsCache = { at: now, root, stats };
+    return stats;
+}
+function sampleProcesses(pids) {
+    if (pids.length === 0)
+        return [];
+    const pidArgs = pids.map(String);
+    const output = safeExecFileSync("ps", [
+        "-o",
+        "pid=,ppid=,%cpu=,%mem=,rss=,etime=",
+        "-p",
+        ...pidArgs,
+    ]);
+    if (!output)
+        return [];
+    return parsePsOutput(output);
+}
+/**
+ * Persist RepoOS process ownership so orphan detection survives a server restart.
+ */
+function readOwnership(cacheDir) {
+    const file = join(cacheDir, OWNERSHIP_FILE);
+    if (!existsSync(file))
+        return [];
+    try {
+        const raw = readFileSync(file, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+}
+function writeOwnership(cacheDir, records) {
+    try {
+        mkdirSync(cacheDir, { recursive: true });
+        writeFileSync(join(cacheDir, OWNERSHIP_FILE), JSON.stringify(records, null, 2), "utf8");
+    }
+    catch {
+        /* best-effort: sampling should never fail on a writable-directory problem */
+    }
+}
+/**
+ * Update the persisted ownership records: add entries for newly-spawned agents
+ * (registry entries not yet persisted) and remove entries whose PIDs are dead.
+ */
+function syncOwnership(cacheDir, running, livePids) {
+    const existing = readOwnership(cacheDir);
+    const byPid = new Map();
+    for (const r of existing)
+        byPid.set(r.pid, r);
+    for (const info of running) {
+        if (info.pid <= 0)
+            continue;
+        if (!byPid.has(info.pid)) {
+            byPid.set(info.pid, {
+                pid: info.pid,
+                taskId: info.id,
+                startedAt: info.startedAt,
+                executable: "",
+                workdir: info.workdir ?? "",
+            });
+        }
+    }
+    const out = [];
+    for (const [pid, rec] of byPid) {
+        if (livePids.has(pid) || running.some((r) => r.pid === pid)) {
+            out.push(rec);
+        }
+    }
+    writeOwnership(cacheDir, out);
+    return out;
+}
+/**
+ * A stray count at or above this is a real problem, not untidiness: it is the
+ * regime where #0211 failed its close-out gate twice on unrelated flaky tests.
+ */
+const SERVE_WARN_THRESHOLD = 4;
+/** Matches both a compiled (`dist/cli/index.js`) and a dev (`src/cli/index.ts`) serve. */
+const SERVE_CMD_RE = /[/\\](?:dist[/\\]cli[/\\]index\.js|src[/\\]cli[/\\]index\.ts)\s+serve\b/;
+/** Extract the repo root a serve process is running from, or null. */
+export function parseServeRoot(command) {
+    const m = command.match(/(\S+?)[/\\](?:dist[/\\]cli[/\\]index\.js|src[/\\]cli[/\\]index\.ts)\s+serve\b/);
+    return m ? m[1] : null;
+}
+/** True when two repo-root paths point at the same directory (symlink-safe). */
+function sameRoot(a, b) {
+    if (!a || !b)
+        return false;
+    if (a === b)
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract `--port N` from a serve command line, or null. */
+export function parseServePort(command) {
+    const m = command.match(/--port[= ](\d+)/);
+    return m ? Number(m[1]) : null;
+}
+/**
+ * Parse `ps ax -o pid=,ppid=,command=` output into serve-process records.
+ *
+ * Classification order matters. The control plane is checked first because the
+ * reload handoff deliberately detaches it, so it also runs with `ppid` 1 and
+ * would otherwise look abandoned. Everything else that RepoOS did not start is
+ * abandoned only if its parent is gone — a fixture server with a live vitest
+ * worker above it is the gate doing its job, not a leak.
+ *
+ * Exported for testing so classification can be exercised without spawning servers.
+ */
+export function parseServeScan(output, serverPid, knownPids, rootExists, ownRoot) {
+    const rows = [];
+    const livePids = new Set();
+    for (const line of output.split("\n")) {
+        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        livePids.add(pid);
+        rows.push({ pid, ppid: Number(m[2]), command: m[3] });
+    }
+    const processes = [];
+    for (const { pid, ppid, command } of rows) {
+        if (!SERVE_CMD_RE.test(command))
+            continue;
+        const root = parseServeRoot(command);
+        const rootIsLive = rootExists(root);
+        // A parent of 1 means the process was reparented after its spawner died.
+        const supervised = ppid !== 1 && livePids.has(ppid);
+        const kind = pid === serverPid
+            ? "control-plane"
+            : knownPids.has(pid)
+                ? "known-preview"
+                : supervised
+                    ? "in-flight"
+                    : // A detached serve for another repo whose root still exists is that
+                        // repo's control plane (also ppid 1) — not ours to touch. Only an
+                        // orphan of OUR root, or one whose root is gone, is a real stray.
+                        ownRoot && root && rootIsLive && !sameRoot(root, ownRoot)
+                            ? "foreign"
+                            : "stray";
+        processes.push({
+            pid,
+            ppid,
+            port: parseServePort(command),
+            root,
+            rootExists: rootIsLive,
+            kind,
+        });
+    }
+    const strays = processes.filter((p) => p.kind === "stray");
+    const deadRoot = strays.filter((p) => !p.rootExists).length;
+    const level = strays.length === 0 ? "ok" : strays.length >= SERVE_WARN_THRESHOLD ? "warn" : "notice";
+    return {
+        total: processes.length,
+        strays: strays.length,
+        inFlight: processes.filter((p) => p.kind === "in-flight").length,
+        deadRoot,
+        level,
+        processes,
+    };
+}
+let serveScanCache = null;
+/** The census walks every process on the machine, so it runs far less often than the 5s sample. */
+const SERVE_SCAN_TTL_MS = 20_000;
+/**
+ * Census live `repoos serve` processes. Cached — `ps ax` lists every process on
+ * the machine, which is much heavier than the targeted per-PID sample.
+ */
+export function scanServeProcesses(serverPid, knownPids, ownRoot) {
+    const now = Date.now();
+    if (serveScanCache && now - serveScanCache.at < SERVE_SCAN_TTL_MS)
+        return serveScanCache.scan;
+    const output = safeExecFileSync("ps", ["ax", "-o", "pid=,ppid=,command="]);
+    if (output === null)
+        return serveScanCache?.scan ?? null;
+    const scan = parseServeScan(output, serverPid, knownPids, (root) => root !== null && existsSync(root), ownRoot);
+    serveScanCache = { at: now, scan };
+    return scan;
+}
+/** Drop the cached census. Exported for tests. */
+export function resetServeScanCache() {
+    serveScanCache = null;
+}
+/**
+ * Reap every `stray` process the census finds — a process whose spawning
+ * parent is confirmed dead (reparented to PID 1). This is safe by
+ * construction: `in-flight` processes (a live parent still supervising them,
+ * e.g. the close-out gate's own test suite mid-run) are never included, and
+ * neither is the control plane or a known preview. Killing a stray destroys
+ * no live work — nothing will ever come back to claim it.
+ *
+ * Root cause this offsets (#0216): a failed reload-replacement handoff kills
+ * only the direct child process (`ReloadManager.killChild`, plain SIGTERM,
+ * not a process-group kill), so anything that child spawned before failing
+ * its readiness check survives as an orphan. Under repeated failed reload
+ * attempts this accumulates fast enough to strain the whole machine, not just
+ * starve the close-out gate. This periodic sweep is the general safety net;
+ * the process-group fix in reload.ts is the more targeted root-cause fix,
+ * tracked separately.
+ */
+export function reapStrayServeProcesses(serverPid, knownPids, kill = process.kill.bind(process), scan, ownRoot) {
+    const doScan = scan ??
+        ((p, k) => {
+            resetServeScanCache();
+            return scanServeProcesses(p, k, ownRoot);
+        });
+    const result = doScan(serverPid, knownPids);
+    if (!result)
+        return 0;
+    let reaped = 0;
+    for (const p of result.processes) {
+        if (p.kind !== "stray")
+            continue;
+        try {
+            kill(p.pid, "SIGTERM");
+            reaped++;
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    return reaped;
+}
+/**
+ * Kill a single process by PID: SIGTERM first, escalating to SIGKILL after a
+ * grace period if it hasn't exited. Same sequence AgentRunner.stop() and the
+ * stray-serve reaper already use elsewhere. Backs the manual "Kill" action in
+ * the System Resources panel — callers must verify the PID is one RepoOS
+ * itself is tracking (a fresh sampleSystem()/scanServeProcesses() result)
+ * before calling this; it does not re-check.
+ */
+export function killTrackedProcess(pid, kill = process.kill.bind(process)) {
+    try {
+        kill(pid, "SIGTERM");
+    }
+    catch {
+        return false; // already gone, or no such process
+    }
+    const t = setTimeout(() => {
+        try {
+            kill(pid, "SIGKILL");
+        }
+        catch {
+            /* already gone */
+        }
+    }, 3000);
+    t.unref?.();
+    return true;
+}
+/**
+ * Sample the system: machine facts, RepoOS process totals, and a per-process
+ * breakdown with orphan detection. One `ps` call covers all tracked + agent PIDs.
+ */
+export function sampleSystem(opts) {
+    const machine = machineInfo();
+    const serverPid = opts.serverPid;
+    const agentPids = new Set(opts.runningAgents.map((a) => a.pid).filter((p) => p > 0));
+    const idByPid = new Map();
+    for (const a of opts.runningAgents) {
+        if (a.pid > 0)
+            idByPid.set(a.pid, a.id);
+    }
+    const allPids = [serverPid, ...agentPids];
+    const ownership = syncOwnership(opts.cacheDir, opts.runningAgents, new Set(allPids));
+    const ownershipByPid = new Map();
+    for (const o of ownership)
+        ownershipByPid.set(o.pid, o);
+    const records = sampleProcesses(allPids);
+    const psByPid = new Map();
+    for (const r of records)
+        psByPid.set(r.pid, r);
+    let totalCpu = 0;
+    let totalMem = 0;
+    let totalMemPercent = 0;
+    const processes = [];
+    for (const pid of allPids) {
+        const ps = psByPid.get(pid);
+        if (!ps)
+            continue;
+        const memBytes = ps.rssKB * KB;
+        totalCpu += ps.cpuPercent;
+        totalMem += memBytes;
+        totalMemPercent += ps.memPercent;
+        const owned = ownershipByPid.get(pid);
+        const taskId = idByPid.get(pid) ?? owned?.taskId ?? null;
+        const orphaned = ps.ppid !== serverPid && pid !== serverPid;
+        processes.push({
+            pid,
+            taskId,
+            cpuPercent: ps.cpuPercent,
+            memBytes,
+            elapsed: ps.elapsed,
+            orphaned,
+            unverified: !idByPid.has(pid) && !owned,
+        });
+    }
+    // Discover orphaned RepoOS processes: PIDs that are NOT in the current
+    // running registry but WERE persisted as RepoOS-owned. Also include
+    // REGISTERED agents whose ppid is no longer the server.
+    const seenPids = new Set(allPids);
+    for (const [pid, owned] of ownershipByPid) {
+        if (seenPids.has(pid))
+            continue;
+        if (!isProcessAlive(pid))
+            continue;
+        const ps = sampleSingleProcess(pid);
+        if (!ps)
+            continue;
+        const memBytes = ps.rssKB * KB;
+        totalCpu += ps.cpuPercent;
+        totalMem += memBytes;
+        totalMemPercent += ps.memPercent;
+        processes.push({
+            pid,
+            taskId: owned.taskId,
+            cpuPercent: ps.cpuPercent,
+            memBytes,
+            elapsed: ps.elapsed,
+            orphaned: true,
+            unverified: false,
+        });
+    }
+    // Sort: orphans first, then by CPU descending
+    processes.sort((a, b) => {
+        if (a.orphaned !== b.orphaned)
+            return a.orphaned ? -1 : 1;
+        return b.cpuPercent - a.cpuPercent;
+    });
+    return {
+        machine,
+        totals: {
+            cpuPercent: Math.round(totalCpu * 10) / 10,
+            memBytes: totalMem,
+            memPercent: Math.round(totalMemPercent * 10) / 10,
+        },
+        processes,
+        serve: scanServeProcesses(serverPid, new Set(opts.knownServePids ?? []), opts.root),
+        repo: opts.root ? sampleRepoStats(opts.root, opts.worktreeWarnThreshold) : null,
+        serverPid,
+        at: new Date().toISOString(),
+    };
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sampleSingleProcess(pid) {
+    const output = safeExecFileSync("ps", [
+        "-o",
+        "pid=,ppid=,%cpu=,%mem=,rss=,etime=",
+        "-p",
+        String(pid),
+    ]);
+    if (!output)
+        return null;
+    const records = parsePsOutput(output);
+    return records[0] ?? null;
+}
+/**
+ * True when the current platform can run the `ps` command with the expected
+ * flags (pid=,ppid=,%cpu=,%mem=,rss=,etime=). Windows `ps` (PowerShell alias)
+ * does not support these flags, so per-process stats are unavailable there.
+ */
+export function psAvailable() {
+    if (platform() === "win32")
+        return false;
+    return safeExecFileSync("ps", ["-o", "pid=", "-p", String(process.pid)]) !== null;
+}

package/dist/server/task-check.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tracks the `repoos check` invocations RepoOS's own server spawns directly
+ * for a task — the handoff-finalize check (handoff.ts's runCheck()) and the
+ * MTD merge-gate check (integration-orchestrator.ts's validateCandidate) —
+ * so the Debug tab (0310) can show when each ran, how long it took, whether
+ * it passed, and stream a currently-running one's output live.
+ *
+ * Deliberately in-memory only, same tradeoff as TestRunManager: this is
+ * observability for the current server session, not a durable audit log. A
+ * server restart mid-check simply loses the in-flight run; the check itself
+ * gets re-attempted by whatever triggered it.
+ */
+export type TaskCheckKind = "handoff-finalize" | "merge-gate";
+export interface TaskCheckRun {
+    id: string;
+    taskId: string;
+    kind: TaskCheckKind;
+    startedAt: string;
+    finishedAt: string | null;
+    durationMs: number | null;
+    running: boolean;
+    /** null while running; true/false once done() is called. */
+    passed: boolean | null;
+    code: number | null;
+    output: string;
+}
+export type TaskCheckEventKind = "started" | "output" | "done";
+export type TaskCheckListener = (run: TaskCheckRun, event: TaskCheckEventKind, chunk?: string) => void;
+export interface TaskCheckHandle {
+    readonly id: string;
+    chunk(text: string): void;
+    done(code: number | null): void;
+}
+export declare class TaskCheckManager {
+    private runsByTask;
+    private seq;
+    /**
+     * Begins tracking one check run for `taskId`. Returns a handle the caller
+     * feeds output chunks into as the underlying subprocess streams them, and
+     * calls `done()` on once the process exits.
+     */
+    start(taskId: string, kind: TaskCheckKind, onEvent: TaskCheckListener): TaskCheckHandle;
+    /** Past + in-progress runs for a task, oldest first. */
+    getRuns(taskId: string): TaskCheckRun[];
+}

package/dist/server/task-check.js

@@ -0,0 +1,71 @@
+/**
+ * Tracks the `repoos check` invocations RepoOS's own server spawns directly
+ * for a task — the handoff-finalize check (handoff.ts's runCheck()) and the
+ * MTD merge-gate check (integration-orchestrator.ts's validateCandidate) —
+ * so the Debug tab (0310) can show when each ran, how long it took, whether
+ * it passed, and stream a currently-running one's output live.
+ *
+ * Deliberately in-memory only, same tradeoff as TestRunManager: this is
+ * observability for the current server session, not a durable audit log. A
+ * server restart mid-check simply loses the in-flight run; the check itself
+ * gets re-attempted by whatever triggered it.
+ */
+/** Cap on retained output per run so a very noisy check can't grow this
+ *  without bound in memory — old text is dropped from the front. */
+const MAX_BUFFERED_CHARS = 500_000;
+/** How many past runs to retain per task — enough to inspect recent
+ *  history without letting a task that gets checked repeatedly (retries)
+ *  grow this without bound. */
+const MAX_RUNS_PER_TASK = 10;
+export class TaskCheckManager {
+    runsByTask = new Map();
+    seq = 0;
+    /**
+     * Begins tracking one check run for `taskId`. Returns a handle the caller
+     * feeds output chunks into as the underlying subprocess streams them, and
+     * calls `done()` on once the process exits.
+     */
+    start(taskId, kind, onEvent) {
+        const id = `${taskId}-${kind}-${++this.seq}`;
+        const run = {
+            id,
+            taskId,
+            kind,
+            startedAt: new Date().toISOString(),
+            finishedAt: null,
+            durationMs: null,
+            running: true,
+            passed: null,
+            code: null,
+            output: "",
+        };
+        const list = this.runsByTask.get(taskId) ?? [];
+        list.push(run);
+        while (list.length > MAX_RUNS_PER_TASK)
+            list.shift();
+        this.runsByTask.set(taskId, list);
+        onEvent(run, "started");
+        return {
+            id,
+            chunk: (text) => {
+                run.output += text;
+                if (run.output.length > MAX_BUFFERED_CHARS) {
+                    run.output = run.output.slice(run.output.length - MAX_BUFFERED_CHARS);
+                }
+                onEvent(run, "output", text);
+            },
+            done: (code) => {
+                run.running = false;
+                run.finishedAt = new Date().toISOString();
+                run.durationMs = Math.max(0, Date.parse(run.finishedAt) - Date.parse(run.startedAt));
+                run.code = code;
+                run.passed = code === 0;
+                onEvent(run, "done");
+            },
+        };
+    }
+    /** Past + in-progress runs for a task, oldest first. */
+    getRuns(taskId) {
+        return this.runsByTask.get(taskId) ?? [];
+    }
+}

package/dist/server/task-transitions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The canonical status-transition table (lifecycle audit, #0295-adjacent).
+ *
+ * Before this, `patchTaskFile` accepted any `(from, to)` status pair with no
+ * rule about which ones make sense — reachable from the task-panel dropdown,
+ * board drag-drop, and a direct PATCH, none of which know an agent might be
+ * running or a review mid-flight. This module is the single reference for
+ * which edges are legitimate and, of those, which are safe to perform as a
+ * bare metadata write versus which require a dedicated action endpoint
+ * (start/pause/done/abandon/reopen) because they carry real side effects
+ * (spawning or stopping an agent, running the close-out pipeline).
+ *
+ * Twelve edges total. Six are cheap enough (no side effect beyond the write
+ * itself, or a side effect — `guardReviewTransition` — that already runs
+ * safely inline within a PATCH request) to allow through the generic patch
+ * path; those are `GENERIC_PATCH_EDGES` below. The other six — spawning an
+ * agent, running the close-out pipeline, stopping a live agent/review, or
+ * re-provisioning a deleted worktree — each already have (or, for the two
+ * new ones, now have) their own `/api/tasks/:id/<action>` endpoint that
+ * performs the effect and writes the status as part of the same request.
+ * `GENERIC_PATCH_EDGES` is the enforcement point for the *other* six: they
+ * are rejected outright, from every generic-write caller (PATCH, the task
+ * drawer's dropdown, board drag-drop), no matter how the request arrives.
+ *
+ * `reopen` (done -> active in the original design sketch) lands on `ready`
+ * instead: the close-out pipeline deletes the task's branch and worktree, so
+ * re-provisioning them is exactly what `/start` (ready -> active) already
+ * does. Landing reopen on `ready` reuses that machinery instead of
+ * duplicating it.
+ */
+import type { Status } from "../core/types.js";
+export interface TransitionEdge {
+    /** Human-readable one-liner: what happens when this edge fires. */
+    effect: string;
+    /** Where this edge is actually performed. */
+    via: "generic-patch" | "action:start" | "action:done" | "action:pause" | "action:abandon" | "action:reopen" | "automated";
+}
+/** The full 12-edge allow-list. Absence of a `(from, to)` pair here means the
+ *  transition is rejected, from every caller, with no exceptions. */
+export declare const TRANSITIONS: Partial<Record<Status, Partial<Record<Status, TransitionEdge>>>>;
+/**
+ * Whether a bare status write (no accompanying action) from `from` to `to`
+ * is allowed. `from === to` is always fine (no-op). Returns a reason and a
+ * pointer to the right endpoint when rejected.
+ */
+export declare function checkGenericStatusPatch(from: Status, to: Status): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};