toolroll 0.9.77 → 0.9.78

package/dist/release.js

@@ -48,6 +48,10 @@ export const REQUIRED_PR_CHECKS = [
     // The git lanes (ci.yml job "git"): the declared floor (git-floor.ts) and Debian trixie's 2.47.
     "git 2.41 · debian trixie",
     "git 2.47 · debian trixie",
+    // The unit suite on macOS (ci.yml jobs "macos-shard" and "macos"; pipeline-speed.md, item 3a): tested on the candidate
+    // before it merges, no longer only on the tag after.
+    "node 22 · macos-latest",
+    "node 24 · macos-latest",
 ];
 /** The workflow file every REQUIRED_PR_CHECKS job belongs to: a job of that name from any other workflow (a lookalike
  * added beside it) never stands for it (Codex review round 1, inherited CI limitation). */
@@ -57,11 +61,14 @@ export const REQUIRED_PR_CHECKS_WORKFLOW = ".github/workflows/ci.yml";
  * git lanes join main's protection once they have run there, so a protection without them is reported, never refused.
  * A later release empties this list; from then on main's protection must name every REQUIRED_PR_CHECKS check.
  */
-export const PROTECTION_REPORT_ONLY_CHECKS = ["git 2.41 · debian trixie", "git 2.47 · debian trixie"];
+export const PROTECTION_REPORT_ONLY_CHECKS = ["git 2.41 · debian trixie", "git 2.47 · debian trixie", "node 22 · macos-latest", "node 24 · macos-latest"];
 /** The checks main's protection must require at minimum: every required check that isn't report-only. */
 export const PROTECTION_MINIMUM_CHECKS = REQUIRED_PR_CHECKS.filter(name => !PROTECTION_REPORT_ONLY_CHECKS.includes(name));
-/** The checks a release tag runs (.github/workflows/publish.yml), awaited before Homebrew moves. */
-export const RELEASE_TAG_CHECKS = ["node 22 · macos-latest", "node 24 · macos-latest", "publish"];
+/** The checks a release's publication waits for on its tag (.github/workflows/publish.yml, pipeline-speed.md item 3):
+ * the publish job and the macOS legs it needs, each named. Nothing else reported on the merge commit (main's own CI push
+ * run) holds publication. */
+export const RELEASE_TAG_CHECKS = ["publish", "tag macOS · node 22", "tag macOS · node 24"];
+export const RELEASE_TAG_WORKFLOW = ".github/workflows/publish.yml";
 export const RELEASE_STEPS = ["gate", "approval", "check", "complete", "quiet", "deploy", "link", "ci", "merge", "tree", "tag", "publish", "homebrew", "done"];
 /** How long each waiting step may take, in minutes, before the release stops there (rerunning continues from it). */
 export const RELEASE_LIMITS = { gate: 60, approval: 24 * 60, check: 120, quiet: 60, deploy: 30, ci: 60, publish: 45, homebrew: 45 };
@@ -85,6 +92,9 @@ class Stop extends Error {
         this.build = build;
     }
 }
+/** The tap change's checks failed: Homebrew's own state, never a stop of a published release. */
+class HomebrewFailed extends Error {
+}
 /** The branch moved before the deploy reservation: carry the approval to the new head, or file it for a person. */
 class Restart extends Error {
     head;
@@ -180,6 +190,18 @@ export function checksVerdict(runs, required) {
         return { state: "failed", failed };
     return waiting.length > 0 ? { state: "pending", waiting } : { state: "passed" };
 }
+/**
+ * Publication's verdict on the tag commit (pipeline-speed.md, item 3): only RELEASE_TAG_CHECKS, from GitHub Actions
+ * runs of publish.yml bound to the tag's push, each by its newest attempt. Every other check on the merge commit — main's
+ * own CI run — is not waited for: the candidate's checks already passed on its exact head before the merge, and the
+ * merged tree was proved equal to it.
+ */
+export function tagChecksVerdict(runs) {
+    const names = RELEASE_TAG_CHECKS;
+    // Only GitHub Actions runs of publish.yml bound to the tag's own push (release-adapters.ts readCheckRuns): a check of
+    // the same name from another workflow, an unbound run or another app is never counted (security scan).
+    return checksVerdict(runs.filter(run => names.includes(run.name) && run.app === "github-actions" && workflowIs(run.workflowPath, RELEASE_TAG_WORKFLOW)), RELEASE_TAG_CHECKS);
+}
 /** Run the release from wherever its journal stopped. */
 export async function runRelease(options, adapters) {
     const file = journalFile(options.stateDir, options.branch);
@@ -254,6 +276,8 @@ export async function runRelease(options, adapters) {
             say(`Released ${journal.tag} (${journal.candidate.sha.slice(0, 7)}) — nothing left to do.`);
             return { ok: true, journal, file };
         }
+        // Published, with Homebrew still to finish: this run finishes it, waiting for the tap's checks within its limit.
+        const finishingHomebrew = journal !== null && journal.step === "homebrew" && journal.published !== null && options.fresh !== true;
         if (!await adapters.github.authenticated())
             throw new Stop("github-auth", "GitHub CLI is not signed in: run `gh auth login`, then rerun.");
         if (journal === null) {
@@ -297,6 +321,89 @@ export async function runRelease(options, adapters) {
                 throw new Stop("drift", `Pull request #${j.pr} no longer has ${j.candidate.sha.slice(0, 7)} at its head.`);
             return pr;
         };
+        // ---- Homebrew, finished apart from publication (pipeline-speed.md, P1) ------------------------------------------
+        let homebrewLeft = null;
+        /**
+         * One look at the tap: propose the formula change when it's missing, judge its checks (once, or within the Homebrew
+         * limit when `wait`), and merge exactly the proposed head once every check passed. A tap that already names a newer
+         * version is never overwritten, checked again right before the merge. Checksums come from npm's own tarball
+         * (release-adapters.ts propose), unchanged.
+         */
+        const homebrewPass = async (wait) => {
+            const brew = adapters.homebrew;
+            let state = await brew.state(j.packageVersion);
+            if (state.kind === "newer")
+                return { state: "superseded", why: `the tap already names ${state.version}` };
+            if (state.kind === "current")
+                return { state: "current", why: null };
+            // A change this release already proposed is the only one it ever merges (security scan): another pull request for
+            // the same version, a moved head or a closed change is failed, never adopted or merged.
+            const journaled = j.homebrew?.pr != null && j.homebrew.head != null ? { pr: j.homebrew.pr, head: j.homebrew.head } : null;
+            if (journaled !== null && state.kind === "missing")
+                return { state: "failed", why: `${brew.repo} #${journaled.pr} was closed before it merged` };
+            if (journaled !== null && state.kind === "proposed" && (state.pr !== journaled.pr || state.head !== journaled.head)) {
+                return { state: "failed", why: `${brew.repo}'s change for ${j.packageVersion} is now #${state.pr} at ${state.head.slice(0, 7)}, not the #${journaled.pr} at ${journaled.head.slice(0, 7)} this release proposed` };
+            }
+            if (state.kind === "missing") {
+                intend("homebrew");
+                const proposed = await brew.propose(j.packageVersion);
+                state = { kind: "proposed", ...proposed };
+            }
+            const proposed = state;
+            j.homebrew = { pr: proposed.pr, head: proposed.head, merged: false, state: "pending", why: null };
+            save();
+            // Whatever checks do register are always judged; an empty set passes only for a tap whose workflows never run
+            // on a change, and only when it's still empty a poll later.
+            const checked = await brew.checked(proposed.head);
+            let emptyLooks = 0;
+            const probe = async () => {
+                // Check runs and commit statuses are judged apart, so neither stands in for the other or hides its failure.
+                // Two apps may name a check alike; each app's attempts stand for themselves.
+                const runs = (await adapters.github.checks(brew.repo, proposed.head)).map(run => ({ ...run, name: `${run.app ?? "unknown app"}: ${run.name}` }));
+                const statuses = await brew.statuses(proposed.head);
+                const verdicts = [runs, statuses].filter(one => one.length > 0).map(one => checksVerdict(one, [...new Set(one.map(run => run.name))]));
+                const failed = verdicts.flatMap(one => one.state === "failed" ? one.failed : []);
+                if (failed.length > 0)
+                    throw new HomebrewFailed(`the tap change's checks failed: ${failed.join(", ")}`);
+                if (verdicts.some(one => one.state === "pending"))
+                    return null;
+                // GitHub registers checks asynchronously; an empty set says nothing about success.
+                // A workflow is owed: only its own run counts, not another app's green check.
+                if (checked && !runs.some(run => run.app === "github-actions"))
+                    return null;
+                if (runs.length === 0 && statuses.length === 0)
+                    return ++emptyLooks >= 2 ? true : null;
+                return true;
+            };
+            try {
+                const passed = wait ? await waitFor("homebrew", `the Homebrew change's checks (${brew.repo} #${proposed.pr})`, probe) : await probe();
+                if (passed === null)
+                    return { state: "pending", why: `${brew.repo} #${proposed.pr}'s checks are still running` };
+            }
+            catch (error) {
+                if (error instanceof HomebrewFailed)
+                    return { state: "failed", why: `${brew.repo} #${proposed.pr}: ${error.message}` };
+                // Waiting ran out: still pending, never a stop of a published release.
+                if (error instanceof Stop && error.reason === "timeout")
+                    return { state: "pending", why: error.message };
+                throw error;
+            }
+            // Ordering, once more right before the merge: a newer formula landed meanwhile is never overwritten.
+            const now = await brew.state(j.packageVersion);
+            if (now.kind === "newer")
+                return { state: "superseded", why: `the tap already names ${now.version}` };
+            if (now.kind === "missing")
+                return { state: "failed", why: `${brew.repo} #${proposed.pr} was closed before it merged` };
+            if (now.kind === "proposed" && now.head !== proposed.head)
+                return { state: "failed", why: `${brew.repo} #${proposed.pr} moved to ${now.head.slice(0, 7)} after its checks were read` };
+            if (now.kind === "current")
+                return { state: "current", why: null };
+            const verified = await brew.verified(proposed.pr, proposed.head, j.packageVersion);
+            if (!verified.ok)
+                return { state: "failed", why: verified.why };
+            await brew.merge(proposed.pr, proposed.head);
+            return { state: "current", why: null };
+        };
         // ---- one approval per release (release-once.md) -------------------------------------------------------------
         const rel = adapters.release;
         let epoch = null;
@@ -601,7 +708,7 @@ export async function runRelease(options, adapters) {
             throw new Stop("ci-failed", `A pull request check failed after the deploy, so ${j.candidate.sha.slice(0, 7)} needs a person's approval again: run \`toolroll release ${j.branch} --repo ${j.checkout} --new\`.`);
         // A resumed release that already has an authority takes its lease and settles every open operation first.
         await hold();
-        while (j.step !== "done") {
+        while (j.step !== "done" && homebrewLeft === null) {
             step = j.step;
             say(`• ${j.step}`);
             try {
@@ -1055,7 +1162,7 @@ export async function runRelease(options, adapters) {
                         await waitFor("publish", `npm, the GitHub release and the tag's checks for ${j.tag}`, async () => {
                             if (await adapters.github.tag(j.github, j.tag) !== j.tagged.sha)
                                 throw new Stop("conflict", `${j.tag} no longer points at the verified merge commit. Homebrew was not updated.`);
-                            const verdict = checksVerdict(await adapters.github.checks(j.github, j.tagged.sha), RELEASE_TAG_CHECKS);
+                            const verdict = tagChecksVerdict(await adapters.github.checks(j.github, j.tagged.sha, { tag: j.tag }));
                             if (verdict.state === "failed")
                                 throw new Stop("publish-failed", `The release tag's checks failed: ${verdict.failed.join(", ")}. Homebrew was not updated.`);
                             if (verdict.state === "pending")
@@ -1068,43 +1175,16 @@ export async function runRelease(options, adapters) {
                     }
                     case "homebrew": {
                         await publishHold();
-                        const brew = adapters.homebrew;
-                        let state = await brew.state(j.packageVersion);
-                        if (state.kind === "missing") {
-                            intend("homebrew");
-                            const proposed = await brew.propose(j.packageVersion);
-                            state = { kind: "proposed", ...proposed };
-                        }
-                        if (state.kind === "proposed") {
-                            const proposed = state;
-                            j.homebrew = { pr: proposed.pr, head: proposed.head, merged: false };
-                            save();
-                            // Whatever checks do register are always judged; an empty set passes only for a tap whose workflows never run
-                            // on a change, and only when it's still empty a poll later.
-                            const checked = await brew.checked(proposed.head);
-                            let emptyLooks = 0;
-                            await waitFor("homebrew", `the Homebrew change's checks (${brew.repo} #${proposed.pr})`, async () => {
-                                // Check runs and commit statuses are judged apart, so neither stands in for the other or hides its failure.
-                                // Two apps may name a check alike; each app's attempts stand for themselves.
-                                const runs = (await adapters.github.checks(brew.repo, proposed.head)).map(run => ({ ...run, name: `${run.app ?? "unknown app"}: ${run.name}` }));
-                                const statuses = await brew.statuses(proposed.head);
-                                const verdicts = [runs, statuses].filter(one => one.length > 0).map(one => checksVerdict(one, [...new Set(one.map(run => run.name))]));
-                                const failed = verdicts.flatMap(one => one.state === "failed" ? one.failed : []);
-                                if (failed.length > 0)
-                                    throw new Stop("homebrew-failed", `The Homebrew change's checks failed: ${failed.join(", ")}.`);
-                                if (verdicts.some(one => one.state === "pending"))
-                                    return null;
-                                // GitHub registers checks asynchronously; an empty set says nothing about success.
-                                // A workflow is owed: only its own run counts, not another app's green check.
-                                if (checked && !runs.some(run => run.app === "github-actions"))
-                                    return null;
-                                if (runs.length === 0 && statuses.length === 0)
-                                    return ++emptyLooks >= 2 ? true : null;
-                                return true;
-                            });
-                            await brew.merge(proposed.pr, proposed.head);
+                        // Homebrew is finished apart from publication (pipeline-speed.md, P1): npm and the GitHub release are verified,
+                        // so the release is published. This run proposes the tap's change and reads its checks once; only a run that
+                        // resumes to finish Homebrew waits for them. Pending or failed, the state is kept and the run ends published.
+                        const progress = await homebrewPass(finishingHomebrew);
+                        j.homebrew = { pr: j.homebrew?.pr ?? null, head: j.homebrew?.head ?? null, merged: progress.state === "current" && j.homebrew?.head != null ? true : j.homebrew?.merged ?? false, state: progress.state, why: progress.why };
+                        save();
+                        if (progress.state === "pending" || progress.state === "failed") {
+                            homebrewLeft = { state: progress.state, why: progress.why };
+                            break;
                         }
-                        j.homebrew = { pr: j.homebrew?.pr ?? null, head: j.homebrew?.head ?? null, merged: true };
                         advance("done");
                         break;
                     }
@@ -1116,8 +1196,13 @@ export async function runRelease(options, adapters) {
                 await restart(error.head);
             }
         }
-        say(`Released ${j.tag}: deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, published and on Homebrew.`);
-        if (j.auto?.state === "approved") {
+        const left = homebrewLeft;
+        if (left === null)
+            say(`Released ${j.tag}: deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, published and ${j.homebrew?.state === "superseded" ? `left Homebrew as it is (${j.homebrew.why ?? "the tap names a newer version"})` : "on Homebrew"}.`);
+        else
+            say(`Published ${j.tag} (deployed, merged as ${j.merge.sha.slice(0, 7)}, tagged, on npm and GitHub); Homebrew ${left.state}${left.why === null ? "" : `: ${left.why}`}. Finish it with \`${resume}\`.`);
+        // The automatic road's note, once: when this run published (a run that only finishes Homebrew already said it).
+        if (j.auto?.state === "approved" && !finishingHomebrew) {
             try {
                 await rel?.auto?.released(j.task.id, j.tag);
             }

package/dist/runner-process.d.ts

@@ -0,0 +1,67 @@
+import type { Runner } from "./runner.js";
+export type RunnerProcessRole = "up" | "console" | "worker";
+export type RunnerProcess = {
+    pid: number;
+    role: RunnerProcessRole;
+    started: string;
+};
+export type RunnerProcessRecord = {
+    v: 1;
+    runner: string;
+    host: string;
+    registeredAt: string;
+    /** A digest of the plane's credential hash for this registration: it names the incarnation, it proves nothing. */
+    credential: string;
+    processes: RunnerProcess[];
+    /** Authenticated with the plane's stored credential hash; legacy/forged records prove nothing. */
+    signature?: string;
+};
+export declare const RUNNER_PROCESS_DIR = "runner-processes";
+/** The namespace is created before builds launch and denied by name, including in a shared state folder. */
+export declare function ensureRunnerProcessFolder(folder: string): void;
+export declare function sealRunnerProcessRecord(record: RunnerProcessRecord, credentialHash: string): RunnerProcessRecord;
+/** Where a runner's record lives: beside the database, under a name derived from the runner's (never the name itself). */
+export declare function runnerProcessFile(databaseFile: string, runner: string): string;
+/** The incarnation's name in a record: a digest of the stored credential hash, so the record never holds that hash. */
+export declare function credentialDigest(credentialHash: string): string;
+/** `ps -o lstart=` (LC_ALL=C, TZ=UTC) as an ISO second, or null when it isn't exactly that shape. */
+export declare function parseProcessStart(raw: string): string | null;
+/** When a process started (whole seconds), or null when there is no such process or it can't be read. */
+export declare function processStart(pid: number): string | null;
+/** The probes a proof uses; real by default, supplied by tests. */
+export type ProcessProbe = {
+    exists: (pid: number) => "absent" | "present" | "unknown";
+    start: (pid: number) => string | null;
+};
+export declare const realProcessProbe: ProcessProbe;
+/** Proved gone: no process has this id, or the one that has it started at another time (the id was reused). */
+export declare function processGone(entry: RunnerProcess, probe?: ProcessProbe): boolean;
+/** A record read strictly: a regular private file of bounded size, every field its exact type, or null. */
+export declare function readRunnerProcessRecord(file: string): RunnerProcessRecord | null;
+/** Replace the record atomically: a private temp file in a private folder, renamed into place. */
+export declare function writeRunnerProcessRecord(file: string, record: RunnerProcessRecord): void;
+/**
+ * Whether the plane's current holder of a runner name is proved gone: the record is for exactly that registration,
+ * on this host, and every process it names has exited (by identity). `detail` says which processes, for the ledger.
+ */
+export declare function holderProvedGone(record: RunnerProcessRecord | null, holder: {
+    runner: Runner;
+    credentialHash: string;
+}, host: string, probe?: ProcessProbe): {
+    gone: true;
+    detail: string;
+} | {
+    gone: false;
+    why: string;
+};
+/** Re-read after observing exit: an up may append a child between the first read and its own exit. */
+export declare function recordedHolderProvedGone(file: string, holder: {
+    runner: Runner;
+    credentialHash: string;
+}, host: string, probe?: ProcessProbe): {
+    gone: true;
+    detail: string;
+} | {
+    gone: false;
+    why: string;
+};

package/dist/runner-process.js

@@ -0,0 +1,219 @@
+/**
+ * Which processes hold a runner's credential, kept beside the plane's database so a later `up` can prove the previous
+ * holder is gone (docs: the 2026-10-29 deploy incident). `toolroll up` registers its runner, then records itself and
+ * every role child it hands the token to, each by process id AND start time, before the child receives the token.
+ *
+ * A fresh `up` whose runner name is still held (its heartbeat looks fresh, or its watch lease has not lapsed) asks
+ * this record whether that holder is gone: the record must be for exactly the registration the plane holds (name,
+ * host, registration time and credential), and every process in it must have exited, each proved by identity (no
+ * such process, or a process with that id started at a different time). Then the plane retires the stale holder in
+ * the same transaction that proved it (runner.ts registerRunnerIfIdle). Anything missing, unreadable or ambiguous
+ * proves nothing, and the door keeps refusing until the heartbeat ages out, exactly as before.
+ *
+ * The record is the plane's own state (the folder that holds the database). It grants nothing by itself: it can
+ * only let a name whose every recorded holder has exited be taken over early.
+ */
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, rmSync, writeFileSync, fsyncSync, constants } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export const RUNNER_PROCESS_DIR = "runner-processes";
+/** The namespace is created before builds launch and denied by name, including in a shared state folder. */
+export function ensureRunnerProcessFolder(folder) {
+    try {
+        mkdirSync(folder, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    const stat = lstatSync(folder);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0
+        || (process.getuid && stat.uid !== process.getuid()) || realpathSync(folder) !== resolve(folder))
+        throw Error("Untrusted runner process folder");
+}
+export function sealRunnerProcessRecord(record, credentialHash) {
+    const { signature: _signature, ...plain } = record;
+    return { ...plain, signature: createHmac("sha256", credentialHash).update(JSON.stringify(plain)).digest("hex") };
+}
+const MAX_RECORD = 64 * 1024;
+const MAX_PROCESSES = 64;
+const ROLES = new Set(["up", "console", "worker"]);
+/** Where a runner's record lives: beside the database, under a name derived from the runner's (never the name itself). */
+export function runnerProcessFile(databaseFile, runner) {
+    let database = databaseFile;
+    try {
+        database = realpathSync(databaseFile);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return join(realpathSync(dirname(database)), RUNNER_PROCESS_DIR, `${createHash("sha256").update(runner, "utf8").digest("hex").slice(0, 32)}.json`);
+}
+/** The incarnation's name in a record: a digest of the stored credential hash, so the record never holds that hash. */
+export function credentialDigest(credentialHash) {
+    return createHash("sha256").update(`runner-process:${credentialHash}`, "utf8").digest("hex").slice(0, 32);
+}
+const LSTART = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{1,2}) (\d{2}:\d{2}:\d{2}) (\d{4})$/;
+/** `ps -o lstart=` (LC_ALL=C, TZ=UTC) as an ISO second, or null when it isn't exactly that shape. */
+export function parseProcessStart(raw) {
+    const match = LSTART.exec(raw.trim().replace(/ +/g, " "));
+    if (match === null)
+        return null;
+    const utc = `${match[1]}, ${match[3].padStart(2, "0")} ${match[2]} ${match[5]} ${match[4]} GMT`;
+    const at = Date.parse(utc);
+    if (!Number.isFinite(at) || new Date(at).toUTCString() !== utc)
+        return null;
+    return new Date(at).toISOString();
+}
+/** When a process started (whole seconds), or null when there is no such process or it can't be read. */
+export function processStart(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 1 || process.platform === "win32")
+        return null;
+    try {
+        const raw = execFileSync("/bin/ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8", env: { PATH: "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" }, stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 1024, timeout: 2_000, killSignal: "SIGKILL",
+        });
+        return parseProcessStart(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export const realProcessProbe = {
+    exists: pid => {
+        try {
+            process.kill(pid, 0);
+            return "present";
+        }
+        catch (error) {
+            const code = error.code;
+            return code === "ESRCH" ? "absent" : code === "EPERM" ? "present" : "unknown";
+        }
+    },
+    start: processStart,
+};
+/** Proved gone: no process has this id, or the one that has it started at another time (the id was reused). */
+export function processGone(entry, probe = realProcessProbe) {
+    const exists = probe.exists(entry.pid);
+    if (exists === "absent")
+        return true;
+    if (exists === "unknown")
+        return false;
+    const started = probe.start(entry.pid);
+    if (started === null)
+        return probe.exists(entry.pid) === "absent";
+    return started !== entry.started;
+}
+/** A record read strictly: a regular private file of bounded size, every field its exact type, or null. */
+export function readRunnerProcessRecord(file) {
+    let fd = null;
+    try {
+        const folder = lstatSync(dirname(file));
+        if (!folder.isDirectory() || folder.isSymbolicLink() || (folder.mode & 0o077) !== 0
+            || (process.getuid && folder.uid !== process.getuid()) || realpathSync(dirname(file)) !== resolve(dirname(file)))
+            return null;
+        const link = lstatSync(file);
+        if (!link.isFile() || link.isSymbolicLink() || link.size > MAX_RECORD)
+            return null;
+        fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK | (constants.O_NOFOLLOW ?? 0));
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_RECORD || stat.ino !== link.ino || stat.dev !== link.dev || (stat.mode & 0o077) !== 0)
+            return null;
+        if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+            return null;
+        const buffer = Buffer.alloc(stat.size);
+        let read = 0;
+        while (read < stat.size) {
+            const n = readSync(fd, buffer, read, stat.size - read, read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        return parseRecord(JSON.parse(buffer.subarray(0, read).toString("utf8")));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function parseRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const v = value;
+    const text = (one, max = 512) => typeof one === "string" && one !== "" && one.length <= max && !one.includes("\0");
+    if (v["v"] !== 1 || !text(v["runner"]) || !text(v["host"]) || !text(v["registeredAt"]) || !ISO.test(v["registeredAt"]) || !text(v["credential"], 64))
+        return null;
+    const list = v["processes"];
+    if (!Array.isArray(list) || list.length === 0 || list.length > MAX_PROCESSES)
+        return null;
+    const processes = [];
+    for (const one of list) {
+        if (typeof one !== "object" || one === null)
+            return null;
+        const p = one;
+        if (!Number.isSafeInteger(p["pid"]) || p["pid"] <= 1 || !ROLES.has(p["role"]) || !text(p["started"], 32) || !ISO.test(p["started"]))
+            return null;
+        processes.push({ pid: p["pid"], role: p["role"], started: p["started"] });
+    }
+    return { v: 1, runner: v["runner"], host: v["host"], registeredAt: v["registeredAt"], credential: v["credential"], processes,
+        ...(typeof v["signature"] === "string" ? { signature: v["signature"] } : {}) };
+}
+/** Replace the record atomically: a private temp file in a private folder, renamed into place. */
+export function writeRunnerProcessRecord(file, record) {
+    ensureRunnerProcessFolder(dirname(file));
+    const temp = `${file}.${randomUUID()}.tmp`;
+    try {
+        const fd = openSync(temp, "wx", 0o600);
+        try {
+            writeFileSync(fd, JSON.stringify(record));
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, file);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+}
+/**
+ * Whether the plane's current holder of a runner name is proved gone: the record is for exactly that registration,
+ * on this host, and every process it names has exited (by identity). `detail` says which processes, for the ledger.
+ */
+export function holderProvedGone(record, holder, host, probe = realProcessProbe) {
+    if (record === null)
+        return { gone: false, why: "no readable record of its processes" };
+    const expected = sealRunnerProcessRecord(record, holder.credentialHash).signature;
+    if (typeof record.signature !== "string" || !/^[a-f0-9]{64}$/.test(record.signature)
+        || !timingSafeEqual(Buffer.from(record.signature, "hex"), Buffer.from(expected, "hex")))
+        return { gone: false, why: "its process record is not authenticated" };
+    if (record.runner !== holder.runner.name || record.host !== holder.runner.host || record.host !== host)
+        return { gone: false, why: "its record is for another worker or machine" };
+    if (record.registeredAt !== holder.runner.registeredAt || record.credential !== credentialDigest(holder.credentialHash))
+        return { gone: false, why: "its record is from an earlier start" };
+    if (!record.processes.some(one => one.role === "up"))
+        return { gone: false, why: "its record names no `up` process" };
+    const left = record.processes.filter(one => !processGone(one, probe));
+    if (left.length > 0)
+        return { gone: false, why: `process ${left.map(one => one.pid).join(", ")} is still running` };
+    return { gone: true, detail: `${record.runner}: process ${record.processes.map(one => `${one.pid} (${one.role})`).join(", ")} proved gone` };
+}
+/** Re-read after observing exit: an up may append a child between the first read and its own exit. */
+export function recordedHolderProvedGone(file, holder, host, probe = realProcessProbe) {
+    const record = readRunnerProcessRecord(file);
+    const proof = holderProvedGone(record, holder, host, probe);
+    if (!proof.gone)
+        return proof;
+    const after = readRunnerProcessRecord(file);
+    if (after === null || JSON.stringify(after) !== JSON.stringify(record))
+        return { gone: false, why: "its process record changed during the exit proof" };
+    return proof;
+}

package/dist/runner.d.ts

@@ -21,7 +21,7 @@
  */
 import { type AcpProviderId } from "./acp-agents.js";
 import type { AcpAttestation } from "./store.js";
-import type { Store, Mutation } from "./store.js";
+import { type Store, type Mutation } from "./store.js";
 import { type ProviderId } from "./provider.js";
 import type { ReadinessObservation } from "./phase-routing.js";
 /** A runner's repo binding, in the same canonical form task filing uses —
@@ -59,11 +59,18 @@ export declare const RUNNER_TOKEN_MS: number;
 /**
  * How long a runner may go quiet before it is presumed gone.
  *
- * Comfortably more than any sensible heartbeat interval: declaring a busy
- * machine dead because one check-in was slow costs more than waiting another
- * minute for a machine that really is.
+ * Four heartbeats (RUNNER_HEARTBEAT_MS): one slow check-in never declares a busy
+ * machine dead, and a machine that really is gone holds its name for a minute,
+ * not three (docs/plans/actors-lessons.md). A clean stop doesn't wait even that
+ * long: a draining or stopped holder never blocks the next start
+ * (registerRunnerIfIdle).
  */
-export declare const DEFAULT_LIVENESS_MS: number;
+export declare const DEFAULT_LIVENESS_MS = 60000;
+/** How often a live runner says so: `up`'s runner heartbeat and every watch lease renewal. */
+export declare const RUNNER_HEARTBEAT_MS = 15000;
+/** The longest a watch lease may be taken or renewed for (durable-actors' MAX_HOST_LEASE_DURATION_MS): a crashed
+ * holder's projects are free within a minute. The store clamps every ttl to it. */
+export { MAX_WATCH_LEASE_MS } from "./store.js";
 export type RegisterOptions = {
     name: string;
     host: string;
@@ -140,13 +147,35 @@ export declare function normalizeRunnerName(raw: string): string;
  * live claim owns), reclaims, and rotates. Two racers serialize: one wins,
  * the other gets the typed refusal.
  */
-export declare function registerRunnerIfIdle(store: Store, options: RegisterOptions): (Registration & {
+export declare function registerRunnerIfIdle(store: Store, options: RegisterOptions & {
+    /**
+     * Whether the name's current holder is proved gone (runner-process.ts): every process it handed its credential to
+     * has exited, verified by identity. Asked only while the holder still blocks the name, inside this transaction;
+     * a proof retires that holder and lapses its watch leases here, so a stale heartbeat never outlives its processes.
+     */
+    previousGone?: (holder: {
+        runner: Runner;
+        credentialHash: string;
+    }) => {
+        gone: true;
+        detail: string;
+    } | {
+        gone: false;
+        why: string;
+    };
+}): (Registration & {
     ok: true;
     recoveredRuns: number;
+    signedOff: string | null;
 }) | {
     ok: false;
     reason: "runner-alive" | "watch-live";
     detail: string;
+} | {
+    ok: false;
+    reason: "runner-draining";
+    detail: string;
+    until: string;
 };
 /**
  * The authenticated lease door (arc 2 findings 15/26): credential verified
@@ -280,3 +309,16 @@ export declare function reportProviderReadinessAuthed(store: Store, args: {
     token: string;
     observations: readonly Omit<ReadinessObservation, "runner" | "observedAt">[];
 }, now: Date): AuthResult;
+/** A worker's lifecycle row (service_lifecycle). */
+export declare const workerComponent: (name: string) => string;
+/**
+ * The stop begins (durable-actors' draining report), fenced by this holder's credential: from now this runner takes
+ * no new work (claim.ts acquire refuses). `until` is a schedule, never proof that the holder exited.
+ */
+export declare function drainRunnerIfCurrent(store: Store, name: string, token: string, now: Date, until: Date): boolean;
+/** A runner's drain as its own lifecycle row reports it (only the current registration's row counts): null when it
+ * isn't draining; ended once its bound passed or it reported stopped. */
+export declare function drainOf(store: Store, runner: Runner, now: Date): {
+    until: string;
+    ended: boolean;
+} | null;