@bridge_gpt/mcp-server 0.2.62 → 0.2.65

package/build/executor/process-containment.js

@@ -0,0 +1,756 @@
+/**
+ * Job-owned process containment (BAPI-1301, D4a — plan Steps 7 and 8).
+ *
+ * WHAT THIS IS. A covered child attempt (`implement`, `resume`, `remediate`,
+ * `ci_fix`) may only report success when the executor has CONFIRMED that no
+ * process the job started is still running. This module produces that
+ * confirmation as a closed `CompletionCleanup` verdict. The verdict is
+ * SUCCESS-BLOCKING: anything other than `confirmed` with zero survivors refuses
+ * success (`successRefusalReason` in `completion-contract.ts`).
+ *
+ * WHAT THIS IS NOT. It is not the adapter's configuration lifecycle cleanup in
+ * `agent-launchers/executor-adapter.ts` (temporary config files, isolation
+ * directories). That cleanup stays separate and best-effort, and it can never
+ * stand in for this verdict.
+ *
+ * THE MECHANISM (measured in the BAPI-1292 probe addendum §4). Every covered
+ * worker environment carries a unique, unpredictable per-job tag in
+ * `BRIDGE_EXECUTOR_JOB_TAG`. Descendants that keep the inherited environment keep
+ * the tag, even after they double-fork, `setsid`, and reparent to PID 1. After
+ * every termination path, the executor:
+ *   1. enumerates same-user processes with their parent pids and environments
+ *      (`ps -E`),
+ *   2. freezes (SIGSTOP) each OWNED process, re-verifying PID + start time
+ *      immediately before the signal. Owned means: its tag EXACTLY matches the
+ *      job token, OR its (pid, start time) exactly matches a descendant the
+ *      executor tracked by parent pid while the worker ran, OR its parent is an
+ *      owned process in the same listing,
+ *   3. repeats until several consecutive rounds find nothing new (this is what
+ *      catches work spawned while the enumeration was running),
+ *   4. re-verifies identity again and SIGKILLs each frozen process,
+ *   5. re-enumerates to confirm nothing owned remains.
+ * Any owned process found at all means the job left work behind: the verdict is
+ * `failed` even when the sweep then removed it. Cleanup stops the work; it does
+ * not turn leftover work into a success.
+ *
+ * ACCEPTED RESIDUALS (macOS lane). Every verdict names both:
+ *  - `environment_scrubbing_daemon`: a daemon that detaches AND clears its own
+ *    environment carries no tag and is invisible to every user-space method the
+ *    probe tested on macOS. The controlled workload excludes such a daemon.
+ *  - `platform_binary_environment_hidden`: macOS hides the environment of a
+ *    platform (Apple-signed) binary such as `/bin/bash`, `/bin/zsh` or
+ *    `/bin/sleep` from `ps -E`, so it shows no tag. Descendant tracking covers
+ *    the common case; one that detaches from the tracked tree between samples
+ *    (reparented to launchd) is not attributable.
+ * Nothing here claims to detect either, and there is no heuristic that pretends to.
+ *
+ * NO KERNEL-BOUNDARY CLAIM. This module makes no Linux cgroup claim and no
+ * separate-OS-user-per-job claim. On any platform other than darwin the default
+ * inspector reports enumeration as failed, so cleanup is `unconfirmed` and a
+ * covered job can never succeed there. Support is never advertised off macOS.
+ *
+ * SIGNAL SEAM. The ONLY raw process signalling in this module is the default
+ * `signal` implementation of the macOS inspector (`defaultSignal`). Everything
+ * else signals through the injected `ProcessInspector.signal` seam, so tests fake
+ * it and no other executor module needs `process.kill`.
+ *
+ * NEVER RETAINED. The enumeration parser keeps only a pid, a start time, and the
+ * tag value. It never keeps command text, arguments, or any other environment
+ * value, and nothing here ever logs the token.
+ */
+import { createHash, randomBytes as nodeRandomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { CLEANUP_RESIDUAL_ENV_SCRUBBING_DAEMON, CLEANUP_RESIDUAL_PLATFORM_BINARY_ENV_HIDDEN, } from "./completion-contract.js";
+// ---------------------------------------------------------------------------
+// Ownership token
+// ---------------------------------------------------------------------------
+/** The environment variable carrying the per-job ownership tag. */
+export const OWNERSHIP_TAG_ENV = "BRIDGE_EXECUTOR_JOB_TAG";
+/** A token is exactly 32 random bytes, hex encoded. */
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+/**
+ * Create a fresh, unpredictable ownership token (32 random bytes → 64 hex).
+ * `randomBytes` is injectable for tests only; production uses node:crypto.
+ */
+export function createOwnershipToken(randomBytes = nodeRandomBytes) {
+    return randomBytes(32).toString("hex");
+}
+export function isOwnershipToken(value) {
+    return typeof value === "string" && TOKEN_RE.test(value);
+}
+/** SHA-256 hex of the token. The digest may leave the executor; the token never does. */
+export function ownershipTokenDigest(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+/** SHA-256 hex of the executor host identity (pass `os.hostname()`). */
+export function hostIdentityDigest(hostname) {
+    return createHash("sha256").update(hostname, "utf8").digest("hex");
+}
+/** A copy of `env` with any ambient ownership tag removed. */
+export function stripAmbientOwnershipTag(env) {
+    const next = { ...env };
+    delete next[OWNERSHIP_TAG_ENV];
+    return next;
+}
+/**
+ * A NEW environment carrying `token` as the ownership tag. Any ambient tag is
+ * stripped first, so neither the parent environment nor a job payload can ever
+ * choose the value. Call this AFTER the adapter/base environment is built.
+ */
+export function withOwnershipTag(env, token) {
+    if (!isOwnershipToken(token)) {
+        throw new Error("ownership token must be 64 lowercase hex characters");
+    }
+    const next = stripAmbientOwnershipTag(env);
+    next[OWNERSHIP_TAG_ENV] = token;
+    return next;
+}
+/** Per-`ps` call bound. The whole sweep is further bounded by its deadline. */
+const PS_TIMEOUT_MS = 10_000;
+/**
+ * Output bound. `runCommand` caps its own buffer (10 MiB, which fails the call
+ * and so fails enumeration closed); this second cap refuses to parse anything
+ * larger if a different runner is injected.
+ */
+const PS_MAX_OUTPUT_CHARS = 16 * 1024 * 1024;
+// `lstart` is fixed-shape: "Wed Sep 25 15:14:00 2026" (day may be space-padded).
+const PS_ROW_RE = /^\s*(\d+)\s+(\d+)\s+([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})(?:\s+([\s\S]*))?$/;
+const LSTART_RE = /^[A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4}$/;
+// The tag must stand as its own whitespace-delimited word and be a full token.
+const TAG_RE = new RegExp(`(?:^|\\s)${OWNERSHIP_TAG_ENV}=([0-9a-f]{64})(?=\\s|$)`, "g");
+function normalizeLstart(raw) {
+    return raw.trim().replace(/\s+/g, " ");
+}
+/**
+ * Extract only the tag value from the command+environment tail of a `ps -E`
+ * row. The environment follows the arguments, so the LAST well-formed
+ * occurrence is taken. Nothing else from the tail is returned.
+ */
+export function extractOwnershipTag(tail) {
+    let last = null;
+    TAG_RE.lastIndex = 0;
+    for (let m = TAG_RE.exec(tail); m !== null; m = TAG_RE.exec(tail))
+        last = m[1];
+    return last;
+}
+/** Parse `ps -E -ww -o pid=,ppid=,lstart=,command=` output into restricted rows. */
+export function parsePsEnvironmentListing(stdout, selfPid) {
+    const out = [];
+    for (const line of stdout.split("\n")) {
+        if (!line.trim())
+            continue;
+        const m = PS_ROW_RE.exec(line);
+        if (!m)
+            continue;
+        const pid = Number(m[1]);
+        const ppid = Number(m[2]);
+        if (!Number.isSafeInteger(pid) || pid <= 1 || pid === selfPid)
+            continue;
+        if (!Number.isSafeInteger(ppid) || ppid < 0)
+            continue;
+        out.push({ pid, ppid, startedAt: normalizeLstart(m[3]), envTag: extractOwnershipTag(m[4] ?? "") });
+    }
+    return out;
+}
+/**
+ * The default raw signal delivery (BAPI-1301). This is the single place the
+ * containment sweep touches `process.kill`; every caller goes through
+ * `ProcessInspector.signal`.
+ */
+export function defaultSignal(pid, sig) {
+    if (!Number.isSafeInteger(pid) || pid <= 1)
+        return "denied";
+    try {
+        process.kill(pid, sig);
+        return "sent";
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return "gone";
+        return "denied";
+    }
+}
+/**
+ * The measured macOS inspector. On any other platform (or without a resolvable
+ * uid) enumeration always fails, so cleanup can never be `confirmed` there.
+ */
+export function createMacProcessInspector(options) {
+    const platform = options.platform ?? process.platform;
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const signal = options.signal ?? defaultSignal;
+    if (platform !== "darwin" || uid === undefined || !Number.isSafeInteger(uid) || uid < 0) {
+        return createUnsupportedProcessInspector();
+    }
+    return {
+        async enumerateSameUser() {
+            try {
+                const res = await options.runCommand("ps", ["-E", "-ww", "-U", String(uid), "-o", "pid=,ppid=,lstart=,command="], { timeoutMs: PS_TIMEOUT_MS });
+                if (res.exitCode !== 0 || res.stdout.length > PS_MAX_OUTPUT_CHARS) {
+                    return { ok: false, reason: "enumeration_failed" };
+                }
+                const procs = parsePsEnvironmentListing(res.stdout, options.selfPid);
+                // `ps` itself is a same-user process, so an empty listing means the
+                // enumeration did not really run.
+                if (procs.length === 0)
+                    return { ok: false, reason: "enumeration_failed" };
+                return { ok: true, procs };
+            }
+            catch {
+                return { ok: false, reason: "enumeration_failed" };
+            }
+        },
+        async identity(pid) {
+            if (!Number.isSafeInteger(pid) || pid <= 1 || pid === options.selfPid)
+                return null;
+            try {
+                const res = await options.runCommand("ps", ["-o", "lstart=", "-p", String(pid)], {
+                    timeoutMs: PS_TIMEOUT_MS,
+                });
+                if (res.exitCode !== 0)
+                    return null;
+                const startedAt = normalizeLstart(res.stdout);
+                return LSTART_RE.test(startedAt) ? { startedAt } : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        signal(pid, sig) {
+            if (pid === options.selfPid)
+                return "denied";
+            return signal(pid, sig);
+        },
+    };
+}
+/** An inspector that never claims support: enumeration fails, nothing is signalled. */
+export function createUnsupportedProcessInspector() {
+    return {
+        enumerateSameUser: async () => ({ ok: false, reason: "enumeration_failed" }),
+        identity: async () => null,
+        signal: () => "denied",
+    };
+}
+// ---------------------------------------------------------------------------
+// Cleanup verdicts
+// ---------------------------------------------------------------------------
+/**
+ * The residuals named on EVERY verdict (BAPI-1301):
+ *  - `environment_scrubbing_daemon`: a daemon that detaches AND clears its
+ *    environment carries no tag and is invisible to the sweep.
+ *  - `platform_binary_environment_hidden`: macOS hides a platform (Apple-signed)
+ *    binary's environment from `ps -E`, so `/bin/bash`, `/bin/zsh` or
+ *    `/bin/sleep` shows no tag even when it inherited one. Tracked descendants
+ *    (see `createDescendantTracker`) cover the common case; a platform-binary
+ *    process that detaches from the tracked tree between samples (reparented to
+ *    launchd) is not attributable.
+ * The server only requires the first token to be present; both are always sent.
+ */
+export const CLEANUP_RESIDUALS_NOT_COVERED = [
+    CLEANUP_RESIDUAL_ENV_SCRUBBING_DAEMON,
+    CLEANUP_RESIDUAL_PLATFORM_BINARY_ENV_HIDDEN,
+];
+/** Build a closed cleanup verdict. Every verdict names both accepted residuals. */
+export function buildCleanupVerdict(verdict, survivors, reasons) {
+    return {
+        verdict,
+        method: "env_tag_sweep",
+        survivors: Math.max(0, Math.floor(survivors)),
+        reasons: [...new Set(reasons)],
+        residual_not_covered: [...CLEANUP_RESIDUALS_NOT_COVERED],
+    };
+}
+/** The verdict for a covered attempt whose sweep never ran (e.g. executor interruption). */
+export function unconfirmedCleanup(reason) {
+    return buildCleanupVerdict("unconfirmed", 0, [reason]);
+}
+/** Hard cap on distinct processes tracked by one sweep or one descendant tracker. */
+const MAX_TRACKED_PROCESSES = 1024;
+/** Confirmation enumerations after SIGKILL (a killed process can take a moment to leave). */
+const CONFIRM_ATTEMPTS = 3;
+const keyOf = (p) => `${p.pid}|${p.startedAt}`;
+/**
+ * Tracks the worker's process tree by parent pid (BAPI-1301). This is what
+ * attributes platform binaries whose environment `ps -E` hides: a child's ppid
+ * is a kernel fact, so a process whose parent is a verified member (same pid AND
+ * start time in the same listing) is ours. A process that has already
+ * reparented to launchd before a sample cannot be attributed this way — that is
+ * the `platform_binary_environment_hidden` residual. The integrator samples
+ * about every 2 s while the worker runs and once right before the sweep.
+ */
+export function createDescendantTracker(options) {
+    const { inspector, rootPid } = options;
+    let rootStartedAt = options.rootStartedAt ?? null;
+    let rootExited = false;
+    let overflow = false;
+    const members = new Map();
+    return {
+        async sample() {
+            try {
+                const listing = await inspector.enumerateSameUser();
+                if (!listing.ok)
+                    return;
+                const childrenOf = new Map();
+                const byPid = new Map();
+                for (const proc of listing.procs) {
+                    byPid.set(proc.pid, proc);
+                    const list = childrenOf.get(proc.ppid);
+                    if (list)
+                        list.push(proc);
+                    else
+                        childrenOf.set(proc.ppid, [proc]);
+                }
+                // Seeds: the root (when its identity matches) and every tracked member
+                // still live with the SAME start time. A reused pid is not a seed.
+                const frontier = [];
+                const rootNow = byPid.get(rootPid);
+                if (rootNow) {
+                    if (rootStartedAt === null)
+                        rootStartedAt = rootNow.startedAt;
+                    if (rootNow.startedAt === rootStartedAt)
+                        frontier.push(rootPid);
+                }
+                for (const member of members.values()) {
+                    const live = byPid.get(member.pid);
+                    if (live && live.startedAt === member.startedAt)
+                        frontier.push(member.pid);
+                }
+                const visited = new Set(frontier);
+                while (frontier.length > 0) {
+                    const parent = frontier.pop();
+                    for (const child of childrenOf.get(parent) ?? []) {
+                        if (visited.has(child.pid))
+                            continue;
+                        visited.add(child.pid);
+                        const key = keyOf(child);
+                        if (!members.has(key)) {
+                            if (members.size >= MAX_TRACKED_PROCESSES) {
+                                overflow = true;
+                                continue;
+                            }
+                            members.set(key, { pid: child.pid, startedAt: child.startedAt });
+                        }
+                        frontier.push(child.pid);
+                    }
+                }
+            }
+            catch {
+                /* sampling is best-effort; the sweep's own verdict stays authoritative */
+            }
+        },
+        owned() {
+            const out = [...members.values()].filter((m) => !(m.pid === rootPid && m.startedAt === rootStartedAt));
+            if (rootExited && rootStartedAt !== null)
+                out.push({ pid: rootPid, startedAt: rootStartedAt });
+            return out;
+        },
+        overflowed() {
+            return overflow;
+        },
+        markRootExited() {
+            rootExited = true;
+        },
+    };
+}
+/**
+ * Which processes in one listing are owned. A process is owned when:
+ *  (a) its environment tag exactly matches the token, OR
+ *  (b) its (pid, startedAt) exactly matches a tracked descendant, OR
+ *  (c) its parent (same listing) is an owned process — a frozen one or one
+ *      owned by (a)/(b) — which catches children spawned during the sweep.
+ * Nothing else is ever owned.
+ */
+function ownedInListing(procs, token, tracked, frozen) {
+    const owned = new Map();
+    const childrenOf = new Map();
+    for (const proc of procs) {
+        const list = childrenOf.get(proc.ppid);
+        if (list)
+            list.push(proc);
+        else
+            childrenOf.set(proc.ppid, [proc]);
+        const key = keyOf(proc);
+        if (proc.envTag === token || tracked.has(key) || frozen.has(key))
+            owned.set(proc.pid, proc);
+    }
+    const frontier = [...owned.keys()];
+    while (frontier.length > 0) {
+        const parent = frontier.pop();
+        for (const child of childrenOf.get(parent) ?? []) {
+            if (owned.has(child.pid))
+                continue;
+            owned.set(child.pid, child);
+            frontier.push(child.pid);
+        }
+    }
+    return [...owned.values()];
+}
+/**
+ * The bounded enumerate → freeze → kill → confirm sweep (BAPI-1301 Step 7).
+ * Identity (pid + start time) is re-verified right before every signal; a
+ * reused pid is never signalled. Never throws; any unexpected error yields
+ * `unconfirmed`.
+ */
+export async function runOwnedProcessSweep(options) {
+    const { token, inspector, deps, deadlineAtMs } = options;
+    const quietRounds = Math.max(1, options.quietRounds ?? 3);
+    const maxRounds = Math.max(quietRounds, options.maxRounds ?? 200);
+    const roundDelayMs = Math.max(0, options.roundDelayMs ?? 15);
+    if (!isOwnershipToken(token))
+        return unconfirmedCleanup("ownership_unverifiable");
+    const reasons = new Set();
+    if (options.trackerOverflowed)
+        reasons.add("ownership_unverifiable");
+    const tracked = new Set((options.trackedDescendants ?? []).slice(0, MAX_TRACKED_PROCESSES).map((p) => keyOf(p)));
+    const seen = new Map();
+    const frozen = new Map();
+    let enumerationFailed = false;
+    let deadlineHit = false;
+    try {
+        // Freeze until a fixed point: `quietRounds` consecutive rounds find nothing new.
+        let quiet = 0;
+        let rounds = 0;
+        while (quiet < quietRounds) {
+            if (rounds >= maxRounds || deps.now() >= deadlineAtMs) {
+                deadlineHit = true;
+                break;
+            }
+            rounds += 1;
+            const listing = await inspector.enumerateSameUser();
+            if (!listing.ok) {
+                enumerationFailed = true;
+                break;
+            }
+            let sawNew = false;
+            for (const proc of ownedInListing(listing.procs, token, tracked, frozen)) {
+                const key = keyOf(proc);
+                if (frozen.has(key))
+                    continue;
+                if (!seen.has(key)) {
+                    if (seen.size >= MAX_TRACKED_PROCESSES) {
+                        deadlineHit = true;
+                        continue;
+                    }
+                    seen.set(key, { pid: proc.pid, startedAt: proc.startedAt });
+                    sawNew = true;
+                }
+                // Re-verify identity immediately before the signal. A changed start
+                // time means the pid was reused: that process is not ours.
+                const live = await inspector.identity(proc.pid);
+                if (live === null)
+                    continue; // gone (or unreadable; the confirm pass decides)
+                if (live.startedAt !== proc.startedAt)
+                    continue;
+                const result = inspector.signal(proc.pid, "SIGSTOP");
+                if (result === "sent")
+                    frozen.set(key, { pid: proc.pid, startedAt: proc.startedAt });
+                else if (result === "denied")
+                    reasons.add("ownership_unverifiable");
+            }
+            quiet = sawNew ? 0 : quiet + 1;
+            if (quiet < quietRounds)
+                await deps.sleep(roundDelayMs);
+        }
+        // Kill every frozen process, re-verifying identity once more. This runs even
+        // after a deadline or enumeration failure so nothing is left merely frozen.
+        for (const proc of frozen.values()) {
+            const live = await inspector.identity(proc.pid);
+            if (live === null || live.startedAt !== proc.startedAt)
+                continue;
+            const result = inspector.signal(proc.pid, "SIGKILL");
+            if (result === "denied")
+                reasons.add("ownership_unverifiable");
+        }
+        // Confirm nothing owned remains.
+        if (!enumerationFailed) {
+            let remaining = -1;
+            for (let attempt = 0; attempt < CONFIRM_ATTEMPTS; attempt += 1) {
+                const listing = await inspector.enumerateSameUser();
+                if (!listing.ok) {
+                    enumerationFailed = true;
+                    break;
+                }
+                const still = ownedInListing(listing.procs, token, tracked, frozen);
+                for (const p of still) {
+                    const key = keyOf(p);
+                    if (!seen.has(key) && seen.size < MAX_TRACKED_PROCESSES) {
+                        seen.set(key, { pid: p.pid, startedAt: p.startedAt });
+                    }
+                }
+                remaining = still.length;
+                if (remaining === 0)
+                    break;
+                await deps.sleep(roundDelayMs);
+            }
+            // An owned process still present after the sweep is one we could not
+            // verify or control.
+            if (remaining > 0)
+                reasons.add("ownership_unverifiable");
+        }
+    }
+    catch {
+        enumerationFailed = true;
+    }
+    const found = seen.size;
+    if (found > 0)
+        reasons.add("survivors_detected");
+    if (enumerationFailed)
+        reasons.add("enumeration_failed");
+    if (deadlineHit)
+        reasons.add("sweep_deadline_exhausted");
+    if (found > 0)
+        return buildCleanupVerdict("failed", found, reasons);
+    if (enumerationFailed || deadlineHit || reasons.size > 0) {
+        return buildCleanupVerdict("unconfirmed", 0, reasons);
+    }
+    return buildCleanupVerdict("confirmed", 0, []);
+}
+/**
+ * Inspect for survivors of an interrupted covered job.
+ *
+ * With only a digest, each observed tag is hashed and compared; matching
+ * processes are REPORTED, never signalled — a digest alone is not enough
+ * authority to kill. When the matching token is available locally, ownership is
+ * verified exactly and the full sweep runs. Never throws.
+ */
+export async function inspectInterruptedOwnership(options) {
+    const { tokenDigest, inspector, deps, deadlineAtMs } = options;
+    if (!HEX64_RE.test(tokenDigest))
+        return { outcome: "unconfirmed", survivors: 0 };
+    if (isOwnershipToken(options.token) && ownershipTokenDigest(options.token) === tokenDigest) {
+        const verdict = await runOwnedProcessSweep({ token: options.token, inspector, deps, deadlineAtMs });
+        if (verdict.verdict === "confirmed")
+            return { outcome: "no_tagged_survivors", survivors: 0 };
+        if (verdict.survivors > 0)
+            return { outcome: "survivors", survivors: verdict.survivors };
+        if (verdict.reasons.includes("enumeration_failed"))
+            return { outcome: "enumeration_failed", survivors: 0 };
+        return { outcome: "unconfirmed", survivors: 0 };
+    }
+    try {
+        if (deps.now() >= deadlineAtMs)
+            return { outcome: "unconfirmed", survivors: 0 };
+        const listing = await inspector.enumerateSameUser();
+        if (!listing.ok)
+            return { outcome: "enumeration_failed", survivors: 0 };
+        let survivors = 0;
+        let unverified = false;
+        for (const proc of listing.procs) {
+            if (proc.envTag === null || ownershipTokenDigest(proc.envTag) !== tokenDigest)
+                continue;
+            if (deps.now() >= deadlineAtMs) {
+                unverified = true;
+                break;
+            }
+            const live = await inspector.identity(proc.pid);
+            if (live === null)
+                continue; // exited since enumeration
+            if (live.startedAt !== proc.startedAt) {
+                unverified = true; // pid reused mid-inspection; cannot attribute either way
+                continue;
+            }
+            survivors += 1;
+        }
+        if (survivors > 0)
+            return { outcome: "survivors", survivors };
+        if (unverified)
+            return { outcome: "unconfirmed", survivors: 0 };
+        return { outcome: "no_tagged_survivors", survivors: 0 };
+    }
+    catch {
+        return { outcome: "unconfirmed", survivors: 0 };
+    }
+}
+export function createDefaultOwnershipRecordFs() {
+    return {
+        mkdir: (dirPath, options) => mkdir(dirPath, options),
+        writeFile: (filePath, data, options) => writeFile(filePath, data, { encoding: "utf-8", mode: options.mode }),
+        readFile: (filePath) => readFile(filePath, "utf-8"),
+        readdir: (dirPath) => readdir(dirPath),
+        removeFile: (filePath) => rm(filePath, { force: true }),
+    };
+}
+const isSafePid = (v) => typeof v === "number" && Number.isSafeInteger(v) && v > 1;
+const OWNED_JOBS_DIR = "owned-jobs";
+const SAFE_JOB_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** Ownership records are tiny; a larger file is not ours and is not parsed. */
+const MAX_RECORD_CHARS = 4096;
+/** Bound on records inspected in one startup pass. */
+const MAX_RECORDS = 256;
+function safeJobId(jobId) {
+    const s = String(jobId);
+    return SAFE_JOB_ID_RE.test(s) ? s : null;
+}
+export function ownershipRecordDir(stateDir) {
+    return path.join(stateDir, OWNED_JOBS_DIR);
+}
+export async function writeOwnershipRecord(stateDir, record, fsDeps) {
+    const id = safeJobId(record.jobId);
+    if (id === null)
+        throw new Error("ownership record job id is not a safe identifier");
+    if (!isOwnershipToken(record.token))
+        throw new Error("ownership record token is malformed");
+    if (!HEX64_RE.test(record.hostDigest))
+        throw new Error("ownership record host digest is malformed");
+    if (record.executorPid !== undefined && !isSafePid(record.executorPid)) {
+        throw new Error("ownership record executor pid is malformed");
+    }
+    const dir = ownershipRecordDir(stateDir);
+    await fsDeps.mkdir(dir, { recursive: true, mode: 0o700 });
+    const body = {
+        jobId: record.jobId,
+        repoName: record.repoName,
+        token: record.token,
+        hostDigest: record.hostDigest,
+        createdAt: record.createdAt,
+        ...(record.executorPid !== undefined ? { executorPid: record.executorPid } : {}),
+    };
+    await fsDeps.writeFile(path.join(dir, `${id}.json`), JSON.stringify(body), { mode: 0o600 });
+}
+function parseOwnershipRecord(raw) {
+    if (raw.length > MAX_RECORD_CHARS)
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        if (!v || typeof v !== "object")
+            return null;
+        const jobId = v.jobId;
+        if (typeof jobId !== "number" && typeof jobId !== "string")
+            return null;
+        if (safeJobId(jobId) === null)
+            return null;
+        if (typeof v.repoName !== "string" || typeof v.createdAt !== "string")
+            return null;
+        if (!isOwnershipToken(v.token))
+            return null;
+        if (typeof v.hostDigest !== "string" || !HEX64_RE.test(v.hostDigest))
+            return null;
+        if (v.executorPid !== undefined && !isSafePid(v.executorPid))
+            return null;
+        return {
+            jobId,
+            repoName: v.repoName,
+            token: v.token,
+            hostDigest: v.hostDigest,
+            createdAt: v.createdAt,
+            ...(v.executorPid !== undefined ? { executorPid: v.executorPid } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** List ownership records. An absent directory is an empty list. Never throws. */
+export async function listOwnershipRecords(stateDir, fsDeps) {
+    const dir = ownershipRecordDir(stateDir);
+    let names;
+    try {
+        names = await fsDeps.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names.slice().sort()) {
+        if (out.length >= MAX_RECORDS)
+            break;
+        if (!name.endsWith(".json"))
+            continue;
+        const fileJobId = name.slice(0, -".json".length);
+        if (!SAFE_JOB_ID_RE.test(fileJobId))
+            continue;
+        let record = null;
+        try {
+            record = parseOwnershipRecord(await fsDeps.readFile(path.join(dir, name)));
+        }
+        catch {
+            record = null;
+        }
+        if (record !== null && String(record.jobId) !== fileJobId)
+            record = null;
+        out.push({ fileJobId, record });
+    }
+    return out;
+}
+/** Remove one ownership record, tolerating absence. Never throws. */
+export async function removeOwnershipRecord(stateDir, jobId, fsDeps) {
+    const id = safeJobId(jobId);
+    if (id === null)
+        return;
+    try {
+        await fsDeps.removeFile(path.join(ownershipRecordDir(stateDir), `${id}.json`));
+    }
+    catch {
+        /* absent or unremovable: tolerated */
+    }
+}
+/** True unless the owner pid is verifiably gone. An unreadable answer counts as alive (never sweep on doubt). */
+async function ownerMayBeAlive(inspector, pid) {
+    try {
+        return (await inspector.identity(pid)) !== null;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Executor startup recovery. Each leftover record means a covered job was
+ * interrupted before its own sweep finished. The record holds the exact token,
+ * so ownership is verified and the full sweep runs. Only the job id and the
+ * verdict are logged — never the token. A malformed record cannot prove
+ * ownership: it is reported `unconfirmed / ownership_unverifiable` and removed
+ * without signalling anything. Never throws.
+ */
+export async function recoverInterruptedOwnership(options) {
+    const { stateDir, inspector, deps, fsDeps, deadlineMs } = options;
+    const log = deps.log ?? (() => { });
+    const results = [];
+    const records = await listOwnershipRecords(stateDir, fsDeps);
+    for (const { fileJobId, record } of records) {
+        let verdict;
+        try {
+            if (record === null) {
+                verdict = unconfirmedCleanup("ownership_unverifiable");
+            }
+            else if (options.hostDigest !== undefined && record.hostDigest !== options.hostDigest) {
+                continue;
+            }
+            else if (record.executorPid !== undefined &&
+                record.executorPid !== options.selfPid &&
+                (await ownerMayBeAlive(inspector, record.executorPid))) {
+                // Another executor on this host still owns this job: its worker is
+                // live work, not an interrupted leftover. Leave the record alone.
+                try {
+                    log(`[executor] BAPI-1301 ownership recovery job=${fileJobId} skipped: owning executor is still running`);
+                }
+                catch {
+                    /* logging is best-effort */
+                }
+                continue;
+            }
+            else {
+                verdict = await runOwnedProcessSweep({
+                    token: record.token,
+                    inspector,
+                    deps,
+                    deadlineAtMs: deps.now() + Math.max(0, deadlineMs),
+                });
+            }
+        }
+        catch {
+            verdict = unconfirmedCleanup("enumeration_failed");
+        }
+        try {
+            log(`[executor] BAPI-1301 ownership recovery job=${fileJobId} cleanup=${verdict.verdict} ` +
+                `survivors=${verdict.survivors} reasons=${verdict.reasons.join(",") || "none"}`);
+        }
+        catch {
+            /* logging is best-effort */
+        }
+        await removeOwnershipRecord(stateDir, fileJobId, fsDeps);
+        results.push({ jobId: fileJobId, verdict });
+    }
+    return results;
+}