toolroll 0.5.0

package/dist/process-recovery-anchor.js

@@ -0,0 +1,188 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeBootId } from "./boot-identity.js";
+import { changedDarwinProcessIdentities, collectDarwinCoalitionSnapshot, DARWIN_PROCESS_CENSUS_SOURCE } from "./process-recovery-native.js";
+/** This version's causal argument was audited against these installed bytes:
+ * up registers a fresh token BEFORE listening; every watch creates a fresh UUID;
+ * heartbeat authenticates that closure's token and exact owner transactionally.
+ * A new runtime needs its own audit, not a caller assertion of equivalent code. */
+export const SERVICE_ANCHOR_RUNTIME_V1_SHA256 = "9641efcb3b46717a7f122aa025e3945a08fa55ca046605276825a9d69eefd01d";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const positive = (value) => Number.isSafeInteger(value) && Number(value) > 0;
+const text = (value) => typeof value === "string" && value.length > 0 && !/[\x00-\x1f\x7f]/.test(value);
+const instant = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const uuid = (value) => typeof value === "string" && normalizeBootId(value) === value;
+const uint64 = (value) => /^[1-9][0-9]{0,19}$/.test(value) && BigInt(value) <= 0xffffffffffffffffn;
+const environment = { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C", TZ: "UTC" };
+function runtimeFingerprint(root) {
+    const files = [];
+    const walk = (directory, prefix = "") => {
+        for (const name of readdirSync(directory).sort()) {
+            const path = join(directory, name), relative = prefix + name, stat = lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw Error("runtime-unreadable");
+            if (stat.isDirectory())
+                walk(path, relative + "/");
+            else if (stat.isFile())
+                files.push([relative, hash(readFileSync(path))]);
+            else
+                throw Error("runtime-unreadable");
+        }
+    };
+    walk(root);
+    if (!files.length)
+        throw Error("runtime-unreadable");
+    return hash(JSON.stringify(files));
+}
+const readCommand = (file, argv) => execFileSync(file, argv, {
+    encoding: "utf8", env: environment, timeout: 5000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
+});
+function observeService(input) {
+    if (runtimeFingerprint(input.runtime) !== input.runtimeSha256)
+        throw Error("runtime-changed");
+    const job = readCommand("/bin/launchctl", ["print", input.service]);
+    // Only direct job fields count. Nested environment and diagnostic sections
+    // can contain arbitrary similarly named strings and are never returned.
+    if (job.match(/^\tpid = (\d+)$/m)?.[1] !== String(input.supervisorPid) || !/^\tstate = running$/m.test(job))
+        throw Error("managed-service-changed");
+    for (const [pid, expected] of [[input.supervisorPid, input.supervisorArgv], [input.workerPid, input.workerArgv]]) {
+        if (readCommand("/bin/ps", ["-ww", "-p", String(pid), "-o", "args="]).trim() !== expected.join(" "))
+            throw Error("service-command-changed");
+    }
+    const listener = readCommand("/usr/sbin/lsof", ["-nP", "-iTCP:" + input.port, "-sTCP:LISTEN", "-Fpn"]);
+    const pids = [...listener.matchAll(/^p(\d+)$/gm)].map(one => Number(one[1]));
+    const names = [...listener.matchAll(/^n(.+)$/gm)].map(one => one[1]);
+    if (!pids.length || pids.some(pid => pid !== input.workerPid) || !names.length || names.some(name => name !== `127.0.0.1:${input.port}`))
+        throw Error("listener-owner-changed");
+}
+// One SELECT is a consistent read snapshot. No credential leaves this module;
+// its hash is used only to reject a registration/authority change while waiting.
+const stateSql = `SELECT t.id target_id, t.started_at target_started, t.finished_at target_finished, t.outcome target_outcome,
+ a.id anchor_id, a.role anchor_role, a.runner anchor_runner, a.watch_incarnation anchor_owner,
+ a.started_at anchor_started, a.finished_at anchor_finished, a.outcome anchor_outcome,
+ ar.repo anchor_repo, a.parent_run source_run, p.verdict source_verdict,
+ (SELECT count(*) FROM criterion_review c WHERE c.reviewer_run=a.id AND c.source_run=a.parent_run) review_count,
+ (SELECT count(*) FROM criterion_review c WHERE c.reviewer_run=a.id AND (c.source_run<>a.parent_run OR c.judgement<>'upholds')) bad_reviews,
+ w.owner, w.generation, w.heartbeat_at heartbeat, w.expires_at expires,
+ e.id episode, e.started_at episode_started, e.ended_at episode_ended,
+ n.registered_at registered, n.credential_hash credential, n.retired_at retired, n.host runner_host, n.repos runner_repos
+ FROM run t JOIN run a ON a.id=? JOIN task_ref ar ON ar.id=a.task_ref
+ JOIN watch_lease w ON w.runner=a.runner AND w.repo=ar.repo
+ JOIN watch_episode e ON e.incarnation=w.owner AND e.runner=w.runner AND e.repo=w.repo
+ JOIN runner n ON n.name=w.runner LEFT JOIN proof_verdict p ON p.run=a.parent_run WHERE t.id=?`;
+// Saved history alone is not a live anchor: collection also requires an unchanged
+// credential epoch/incarnation across an authenticated heartbeat and native identities.
+function readState(db, input, now) {
+    const row = db.prepare(stateSql).get(input.anchorReviewerRun, input.targetRun);
+    if (!row || row["target_id"] !== input.targetRun || row["anchor_id"] !== input.anchorReviewerRun ||
+        input.anchorReviewerRun >= input.targetRun || row["anchor_role"] !== "reviewer" || row["anchor_outcome"] !== "no-change" ||
+        row["anchor_runner"] !== input.runner || row["anchor_repo"] !== input.repo || row["runner_host"] !== input.host ||
+        !uuid(row["owner"]) || row["anchor_owner"] !== row["owner"] || !positive(row["generation"]) || !positive(row["episode"]) ||
+        row["episode_ended"] !== null || row["retired"] !== null || row["source_verdict"] !== "verified" ||
+        !positive(row["review_count"]) || row["bad_reviews"] !== 0 || !text(row["credential"]) ||
+        !["registered", "episode_started", "anchor_started", "anchor_finished", "target_started", "target_finished", "heartbeat", "expires"].every(key => instant(row[key])) ||
+        !["built", "no-change"].includes(String(row["target_outcome"])))
+        throw Error("watch-history-unproven");
+    const r = row;
+    const times = [r.registered, r["episode_started"], r["anchor_started"], r["anchor_finished"], r["target_started"], r["target_finished"], r.heartbeat].map(value => Date.parse(String(value)));
+    if (times.some((time, i) => i > 0 && time < times[i - 1]) || Date.parse(r.heartbeat) > now || Date.parse(r.expires) <= now || Date.parse(r.expires) <= Date.parse(r.heartbeat))
+        throw Error("watch-history-unproven");
+    const repos = JSON.parse(String(r["runner_repos"]));
+    if (!Array.isArray(repos) || !repos.includes(input.repo))
+        throw Error("watch-history-unproven");
+    return r;
+}
+const staticState = ({ heartbeat: _heartbeat, expires: _expires, ...row }) => JSON.stringify(row);
+function anchored(snapshot, input) {
+    if (!snapshot.complete || !snapshot.stable || snapshot.errors.length || snapshot.anchorIdentityChanges.length ||
+        snapshot.host !== input.host || normalizeBootId(snapshot.bootId ?? "") !== input.bootId || snapshot.resourceCoalitionId !== input.resourceCoalitionId ||
+        snapshot.nativeSourceSha256 !== input.native.sourceSha256 || snapshot.nativeExecutableSha256 !== input.native.executableSha256 ||
+        snapshot.anchorPids.length !== 2 || !snapshot.anchorPids.includes(input.workerPid) || !snapshot.anchorPids.includes(input.supervisorPid))
+        throw Error("native-anchor-unproven");
+    const worker = snapshot.anchors.find(row => row.pid === input.workerPid), supervisor = snapshot.anchors.find(row => row.pid === input.supervisorPid);
+    if (!worker?.uniqueId || !supervisor?.uniqueId || worker.traced !== false || supervisor.traced !== false ||
+        worker.ppid !== supervisor.pid || worker.parentUniqueId !== supervisor.uniqueId || BigInt(supervisor.uniqueId) >= BigInt(worker.uniqueId) || worker.uid !== supervisor.uid ||
+        worker.executable !== input.workerArgv[0] || supervisor.executable !== input.supervisorArgv[0])
+        throw Error("native-anchor-unproven");
+    return [worker, supervisor];
+}
+/** Trusted read-only collection, not exit evidence. Reads an existing connection
+ * (including a schema69 Store.handle), never opens/migrates or writes a database.
+ * Under the trusted installed-code/credential model, renewing a saved pre-run
+ * UUID while registration stays fixed establishes a pre-run live service bound.
+ * It does NOT establish coalition inheritance, survivor exclusion, or authority
+ * to clear process custody. Every incomplete observation returns a refusal. */
+export async function collectDarwinServiceAnchor(db, input) {
+    let phase = "invalid-anchor-input";
+    try {
+        const wait = input.maxWaitMs ?? 60_000;
+        if (process.platform !== "darwin" || input.runtimeSha256 !== SERVICE_ANCHOR_RUNTIME_V1_SHA256 || input.native.sourceSha256 !== hash(DARWIN_PROCESS_CENSUS_SOURCE) ||
+            ![input.targetRun, input.anchorReviewerRun, input.supervisorPid, input.workerPid, input.port].every(positive) ||
+            input.workerPid === input.supervisorPid || input.port > 65535 || !uuid(input.bootId) || !uint64(input.resourceCoalitionId) ||
+            ![input.databasePath, input.runtime, input.runner, input.repo, input.host].every(text) ||
+            !/^(system|gui\/[0-9]+)\/[A-Za-z0-9._-]+$/.test(input.service) || !Number.isSafeInteger(wait) || wait < 0 || wait > 60_000 ||
+            [input.runtime, input.databasePath, input.repo].some(path => realpathSync(path) !== path) ||
+            ![input.workerArgv, input.supervisorArgv].every(args => Array.isArray(args) && args.length > 2 && args.every(arg => text(arg) && !/\s/.test(arg))))
+            return { ok: false, reason: phase };
+        const args = input.workerArgv;
+        const flag = (name, value) => args.filter(arg => arg === name).length === 1 && args[args.indexOf(name) + 1] === value;
+        if (args[1] !== join(input.runtime, "cli.js") || args[2] !== "up" ||
+            !flag("--db", input.databasePath) || !flag("--repo", input.repo) || !flag("--runner", input.runner) ||
+            !flag("--port", String(input.port)) || !flag("--host", "127.0.0.1") ||
+            input.supervisorArgv[1] !== join(input.runtime, "controller-service.js") ||
+            JSON.stringify(input.supervisorArgv.slice(2)) !== JSON.stringify(args))
+            return { ok: false, reason: phase };
+        phase = "database-binding-unproven";
+        const main = db.prepare("PRAGMA database_list").all().filter(row => row["name"] === "main");
+        if (main.length !== 1 || main[0]?.["file"] !== input.databasePath)
+            throw Error(phase);
+        const witnesses = db.prepare("SELECT DISTINCT host, boot_id FROM run_process WHERE run=?").all(input.targetRun);
+        if (!witnesses.length || witnesses.some(row => row["host"] !== input.host || typeof row["boot_id"] !== "string" || normalizeBootId(row["boot_id"]) !== input.bootId))
+            throw Error(phase);
+        phase = "watch-history-unproven";
+        const initial = readState(db, input, Date.now()), fixed = staticState(initial);
+        phase = "native-anchor-unproven";
+        const capture = () => collectDarwinCoalitionSnapshot({ native: input.native, resourceCoalitionId: input.resourceCoalitionId, anchorPids: [input.workerPid, input.supervisorPid], maxAttempts: 3 });
+        const before = anchored(await capture(), input);
+        phase = "service-observation-unproven";
+        observeService(input);
+        phase = "watch-renewal-unproven";
+        const deadline = performance.now() + wait;
+        let advanced;
+        for (;;) {
+            advanced = readState(db, input, Date.now());
+            if (staticState(advanced) !== fixed || Date.parse(advanced.heartbeat) < Date.parse(initial.heartbeat))
+                throw Error("watch-incarnation-changed");
+            if (Date.parse(advanced.heartbeat) > Date.parse(initial.heartbeat))
+                break;
+            const left = deadline - performance.now();
+            if (left <= 0)
+                throw Error("watch-renewal-not-observed");
+            await new Promise(resolve => setTimeout(resolve, Math.min(1000, left)));
+        }
+        phase = "service-observation-unproven";
+        observeService(input);
+        phase = "native-anchor-unproven";
+        const after = anchored(await capture(), input);
+        if (changedDarwinProcessIdentities(before, after).length || before.some((row, i) => row.resourceCoalitionId !== after[i]?.resourceCoalitionId))
+            throw Error("service-identity-changed");
+        phase = "watch-renewal-unproven";
+        const final = readState(db, input, Date.now());
+        if (staticState(final) !== fixed || Date.parse(final.heartbeat) < Date.parse(advanced.heartbeat))
+            throw Error("watch-incarnation-changed");
+        return { ok: true, receipt: { schema: 1, kind: "authenticated-watch-continuity", targetRun: input.targetRun,
+                anchorReviewerRun: input.anchorReviewerRun, host: input.host, bootId: input.bootId, observedAt: new Date().toISOString(),
+                runtimeSha256: input.runtimeSha256, databasePath: input.databasePath, runner: input.runner, repo: input.repo,
+                owner: initial.owner, generation: initial.generation, episode: initial.episode, registeredAt: initial.registered,
+                heartbeatBefore: initial.heartbeat, heartbeatAfter: final.heartbeat, service: input.service, listener: `127.0.0.1:${input.port}`,
+                worker: after[0], supervisor: after[1], nativeSourceSha256: input.native.sourceSha256, nativeExecutableSha256: input.native.executableSha256 } };
+    }
+    catch (error) {
+        // Never forward subprocess/SQLite error objects: they may retain argv,
+        // launchd environment text, paths or credential-bearing row values.
+        const known = new Set(["runtime-changed", "managed-service-changed", "service-command-changed", "listener-owner-changed", "watch-history-unproven", "native-anchor-unproven", "watch-incarnation-changed", "watch-renewal-not-observed", "service-identity-changed"]);
+        return { ok: false, reason: error instanceof Error && known.has(error.message) ? error.message : phase };
+    }
+}

package/dist/process-recovery-coalition.d.ts

@@ -0,0 +1,25 @@
+import type { DarwinCoalitionRecoverySnapshot } from "./process-recovery-native.js";
+import { type PreexistingAppService } from "./process-recovery-services.js";
+import type { ProcessRecoveryAnchor, ProcessRecoveryAssessment } from "./process-recovery.js";
+/** A current coalition inventory supplies membership, not historical authority.
+ * Before calling, independently authenticate that the terminal run inherited
+ * sourceRoot's resource coalition, could not select another coalition or delegate
+ * a launch, and has no remaining producer. All known owned processes must have
+ * positive exit evidence. A lost direct spawn is not an observer gap.
+ *
+ * Independently authenticate that preRunUpperBound's exact STILL-LIVE identity
+ * existed before the run could spawn. This can be a causally bound live service;
+ * calendar birth times, numeric PIDs, names and absent restart logs do not count.
+ * XNU assigns increasing 64-bit process IDs at fork and preserves them at exec.
+ * IDs no greater than that authenticated bound therefore predate the run.
+ * The native collector must revalidate this anchor alongside its counter seal.
+ * This pure assessment never records an exit or authorizes a database mutation. */
+export declare function assessDarwinCoalitionRecovery(args: {
+    host: string;
+    bootId: string;
+    resourceCoalitionId: string;
+    sourceRoot: ProcessRecoveryAnchor;
+    preRunUpperBound: ProcessRecoveryAnchor;
+    snapshot: DarwinCoalitionRecoverySnapshot;
+    preexistingAppServices?: readonly PreexistingAppService[];
+}): ProcessRecoveryAssessment;

package/dist/process-recovery-coalition.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { normalizeBootId } from "./boot-identity.js";
+import { APP_SERVICE_EXECUTABLE, APP_SERVICE_PLATFORM } from "./process-recovery-services.js";
+const uint64 = (value) => typeof value === "string" && /^(0|[1-9][0-9]{0,19})$/.test(value) && BigInt(value) <= 0xffffffffffffffffn;
+const identity = (value) => uint64(value) && value !== "0";
+const anchorValid = (value) => Number.isSafeInteger(value.pid) && value.pid > 1 && identity(value.uniqueId);
+/** A current coalition inventory supplies membership, not historical authority.
+ * Before calling, independently authenticate that the terminal run inherited
+ * sourceRoot's resource coalition, could not select another coalition or delegate
+ * a launch, and has no remaining producer. All known owned processes must have
+ * positive exit evidence. A lost direct spawn is not an observer gap.
+ *
+ * Independently authenticate that preRunUpperBound's exact STILL-LIVE identity
+ * existed before the run could spawn. This can be a causally bound live service;
+ * calendar birth times, numeric PIDs, names and absent restart logs do not count.
+ * XNU assigns increasing 64-bit process IDs at fork and preserves them at exec.
+ * IDs no greater than that authenticated bound therefore predate the run.
+ * The native collector must revalidate this anchor alongside its counter seal.
+ * This pure assessment never records an exit or authorizes a database mutation. */
+export function assessDarwinCoalitionRecovery(args) {
+    const s = args.snapshot;
+    const refuse = (problem, unresolved = []) => ({ ok: false, problems: [problem], unresolved });
+    const boot = normalizeBootId(args.bootId);
+    if (!boot || !s.bootId || normalizeBootId(s.bootId) !== boot || s.host !== args.host || !args.host ||
+        !identity(args.resourceCoalitionId) || s.resourceCoalitionId !== args.resourceCoalitionId)
+        return refuse("The process inventory does not match the authenticated host, boot and resource coalition.");
+    if (!anchorValid(args.sourceRoot) || !anchorValid(args.preRunUpperBound))
+        return refuse("The historical process identities are missing or malformed.");
+    if (s.schema !== 1 || !s.complete || !s.stable || !s.kernelTableRead || !s.countersStable || s.unreadableMembershipCount !== 0 || s.errors.length || s.identityChanges.length || s.anchorIdentityChanges.length)
+        return refuse("The target process inventory or its external anchor changed during observation.");
+    const before = s.counterBefore, after = s.counterAfter;
+    if (!before || !after || !uint64(before.tasksStarted) || !uint64(before.tasksExited) ||
+        before.tasksStarted !== after.tasksStarted || before.tasksExited !== after.tasksExited ||
+        BigInt(before.tasksStarted) < BigInt(before.tasksExited) ||
+        BigInt(before.tasksStarted) - BigInt(before.tasksExited) !== BigInt(s.processes.length))
+        return refuse("Kernel task counters do not establish a complete target inventory.");
+    const rows = new Map(s.processes.map(row => [row.pid, row]));
+    if (!rows.size || rows.size !== s.processes.length || new Set(s.processes.map(row => row.uniqueId)).size !== rows.size ||
+        s.processes.some(row => !Number.isSafeInteger(row.pid) || row.pid < 1 || !identity(row.uniqueId) || row.resourceCoalitionId !== s.resourceCoalitionId))
+        return refuse("The target inventory contains missing or ambiguous process identities.");
+    const source = rows.get(args.sourceRoot.pid);
+    if (source?.uniqueId !== args.sourceRoot.uniqueId || source.traced !== false)
+        return refuse("The original execution service is no longer the authenticated kernel identity.");
+    const anchorRows = s.anchors.filter(row => row.pid === args.preRunUpperBound.pid);
+    if (s.anchorPids.filter(pid => pid === args.preRunUpperBound.pid).length !== 1 || anchorRows.length !== 1 ||
+        anchorRows[0].uniqueId !== args.preRunUpperBound.uniqueId || anchorRows[0].traced !== false)
+        return refuse("The pre-run service identity was not independently revalidated by the native collector.");
+    const collector = s.collector;
+    if (!collector || collector.exited !== true || rows.get(collector.pid)?.uniqueId !== collector.uniqueId)
+        return refuse("The owned diagnostic process has no bound positive exit evidence.");
+    const bound = BigInt(args.preRunUpperBound.uniqueId);
+    const services = new Map();
+    for (const binding of args.preexistingAppServices ?? []) {
+        const service = rows.get(binding.pid), owner = rows.get(binding.ownerPid);
+        const signing = binding.ownerSigning;
+        const recognizedOwner = typeof binding.ownerExecutable === "string" &&
+            (binding.ownerExecutable === "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ? signing === null :
+                createHash("sha256").update(binding.ownerExecutable).digest("hex") === APP_SERVICE_PLATFORM.clonePathSha256 &&
+                    signing?.identifier === "com.google.Chrome" && signing.teamId === "EQHXZ8M8AV" &&
+                    signing.cdHash === APP_SERVICE_PLATFORM.cloneCdHash && signing.dynamicallyVerified === true);
+        if (services.has(binding.pid) || !identity(binding.uniqueId) || !identity(binding.ownerUniqueId) ||
+            service?.uniqueId !== binding.uniqueId || owner?.uniqueId !== binding.ownerUniqueId || service.pid === owner.pid ||
+            service.traced !== false || owner.traced !== false || BigInt(owner.uniqueId) > bound || BigInt(owner.uniqueId) >= BigInt(service.uniqueId) ||
+            !recognizedOwner || owner.executable !== binding.ownerExecutable || !Number.isInteger(binding.ownerPidVersion) ||
+            binding.ownerPidVersion <= 0 || owner.pidVersion !== binding.ownerPidVersion ||
+            service.uid !== binding.uid || owner.uid !== binding.uid || binding.uid === null ||
+            service.resourceCoalitionId !== binding.resourceCoalitionId || owner.resourceCoalitionId !== binding.resourceCoalitionId ||
+            service.executable !== binding.executable || binding.executable !== APP_SERVICE_EXECUTABLE || binding.domain !== `pid/${owner.pid}` ||
+            s.osRelease !== APP_SERVICE_PLATFORM.osRelease || JSON.stringify(binding.platform) !== JSON.stringify(APP_SERVICE_PLATFORM)) {
+            return refuse("A collected app service does not match its pre-existing owner and final kernel identities.");
+        }
+        services.set(binding.pid, binding);
+    }
+    const external = new Map();
+    const visiting = new Set();
+    const visit = (pid) => {
+        if (external.has(pid))
+            return true;
+        if (visiting.has(pid))
+            return false;
+        const row = rows.get(pid);
+        if (!row || row.traced !== false)
+            return false;
+        const accept = (basis, anchor) => { external.set(pid, { pid, basis, anchor }); return true; };
+        if (pid === collector.pid && row.uniqueId === collector.uniqueId)
+            return accept("owned-probe", pid);
+        if (BigInt(row.uniqueId) <= bound)
+            return accept("predates-run", args.preRunUpperBound.pid);
+        const service = services.get(pid);
+        if (service)
+            return accept("pre-existing-app-service", service.ownerPid);
+        if (!row.ppid || row.ppid <= 1 || row.ppid === pid || !identity(row.parentUniqueId))
+            return false;
+        const parent = rows.get(row.ppid);
+        if (!parent || parent.uniqueId !== row.parentUniqueId || BigInt(parent.uniqueId) >= BigInt(row.uniqueId))
+            return false;
+        visiting.add(pid);
+        const found = visit(parent.pid);
+        visiting.delete(pid);
+        return found ? accept("ancestry", external.get(parent.pid).anchor) : false;
+    };
+    const unresolved = s.processes.filter(row => !visit(row.pid)).map(row => row.pid).sort((a, b) => a - b);
+    return unresolved.length ? refuse("Some processes could still be unobserved descendants of the completed run.", unresolved)
+        : { ok: true, observedAt: s.finishedAt, external: [...external.values()].sort((a, b) => a.pid - b.pid) };
+}

package/dist/process-recovery-eligibility.d.ts

@@ -0,0 +1,178 @@
+import type { Store } from "./store.js";
+export type RecoveryWitnessSnapshot = Readonly<{
+    id: number;
+    run: number;
+    pid: number | null;
+    host: string;
+    process_group: number;
+    observed_at: string;
+    exited_at: string | null;
+    boot_id: string | null;
+    containment: string | null;
+    container: string | null;
+    container_identity: string | null;
+    container_empty_at: string | null;
+}>;
+export declare function preparedCandidateObserverGapEligibility(store: Store, input: {
+    runId: number;
+    evidenceRoot: string;
+    now: Date;
+    /** Authenticated current kernel context supplied by the caller, not a row's
+     * own host/boot copied back to it. Unknown identity refuses. */
+    host: string;
+    bootId: string | null;
+}): {
+    readonly ok: true;
+    readonly digest: string;
+    readonly binding: {
+        readonly version: 1;
+        readonly kind: "prepared-candidate-observer-gap-eligibility";
+        readonly host: string;
+        readonly bootId: string;
+        readonly run: {
+            id: number;
+            taskRef: number;
+            taskId: string;
+            repo: string;
+            leaseId: string;
+            role: "builder";
+            outcome: "built" | "no-change";
+            committed: boolean | null;
+            startedAt: string;
+            finishedAt: string;
+            branch: string;
+            worktree: string;
+            base: string;
+            head: string;
+        };
+        readonly scope: {
+            candidate: string;
+            digest: string;
+            approvedAt: string;
+            approvedBy: string;
+            approvalBasis: "mode" | "password";
+            modeDigest: string | null;
+        };
+        readonly command: {
+            readonly id: number;
+            readonly repo: string;
+            readonly command: string;
+            readonly timeoutMs: number;
+            readonly digest: string;
+            readonly recoverySetupDigest: string | null;
+            readonly approvedBy: string;
+            readonly approvedAt: string;
+            readonly revokedAt: string | null;
+            readonly revokedBy: string | null;
+        };
+        readonly machine: {
+            readonly run: number;
+            readonly verdict: "verified" | "attested" | "short" | "refuted";
+            readonly reasons: readonly string[];
+            readonly decidedAt: string;
+            readonly matrix: readonly {
+                readonly assessment?: {
+                    readonly evidenceState: import("./proof.js").CriterionMatrixState;
+                    readonly detail: readonly string[];
+                };
+                readonly id: string;
+                readonly statement: string;
+                readonly requiredEvidence: readonly import("./scope.js").EvidenceKind[];
+                readonly state: import("./proof.js").CriterionMatrixState;
+                readonly detail: readonly string[];
+                readonly answered: readonly {
+                    readonly kind: import("./scope.js").EvidenceKind;
+                    readonly ref: string;
+                }[];
+                readonly review: {
+                    readonly judgement: import("./proof.js").CriterionJudgementWord;
+                    readonly note: string;
+                    readonly author: string;
+                } | null;
+                readonly coverage?: {
+                    readonly state: "patch" | "context" | "gap";
+                    readonly inherited: boolean;
+                    readonly items: readonly string[];
+                    readonly gaps: readonly string[];
+                    readonly priorSupport: "eligible" | "invalid" | "none";
+                };
+            }[];
+            readonly machineVerdict: import("./store.js").ProofVerdictRow["verdict"] | null;
+        };
+        readonly gateDigest: string;
+        readonly gate: {
+            readonly id: number;
+            readonly run: number;
+            readonly kind: "base-tree" | "check-log" | "diff" | "diff-stat" | "handoff" | "park-payload" | "plan" | "plan-contract" | "proof" | "report" | "review-context" | "revision-brief" | "screenshot" | "status" | "structured-output" | "terminal-diff";
+            readonly key: string;
+            readonly sha256: string;
+            readonly bytesOriginal: number;
+            readonly bytesStored: number;
+            readonly truncated: boolean;
+            readonly redacted: boolean;
+            readonly capture: string;
+            readonly captureStatus: "failed" | "ok" | null;
+            readonly createdAt: string;
+        };
+        readonly log: {
+            readonly id: number;
+            readonly run: number;
+            readonly kind: "base-tree" | "check-log" | "diff" | "diff-stat" | "handoff" | "park-payload" | "plan" | "plan-contract" | "proof" | "report" | "review-context" | "revision-brief" | "screenshot" | "status" | "structured-output" | "terminal-diff";
+            readonly key: string;
+            readonly sha256: string;
+            readonly bytesOriginal: number;
+            readonly bytesStored: number;
+            readonly truncated: boolean;
+            readonly redacted: boolean;
+            readonly capture: string;
+            readonly captureStatus: "failed" | "ok" | null;
+            readonly createdAt: string;
+        };
+        readonly handoff: {
+            readonly id: number;
+            readonly run: number;
+            readonly kind: "base-tree" | "check-log" | "diff" | "diff-stat" | "handoff" | "park-payload" | "plan" | "plan-contract" | "proof" | "report" | "review-context" | "revision-brief" | "screenshot" | "status" | "structured-output" | "terminal-diff";
+            readonly key: string;
+            readonly sha256: string;
+            readonly bytesOriginal: number;
+            readonly bytesStored: number;
+            readonly truncated: boolean;
+            readonly redacted: boolean;
+            readonly capture: string;
+            readonly captureStatus: "failed" | "ok" | null;
+            readonly createdAt: string;
+        };
+        readonly ownedRuns: readonly {
+            readonly id: number;
+            readonly taskRef: number;
+            readonly leaseId: string;
+            readonly parentRun: number | null;
+            readonly role: "builder" | "planner" | "repair" | "reviewer" | "scout";
+            readonly outcome: "built" | "failed" | "interrupted" | "no-change" | "parked" | "refused";
+            readonly startedAt: string;
+            readonly finishedAt: string;
+            readonly providerStartedAt: null;
+            readonly sessionId: null;
+        }[];
+        readonly unknownWitnessIds: readonly number[];
+        readonly witnesses: readonly {
+            readonly id: number;
+            readonly run: number;
+            readonly pid: number | null;
+            readonly host: string;
+            readonly process_group: number;
+            readonly observed_at: string;
+            readonly exited_at: string | null;
+            readonly boot_id: string | null;
+            readonly containment: string | null;
+            readonly container: string | null;
+            readonly container_identity: string | null;
+            readonly container_empty_at: string | null;
+        }[];
+    };
+    readonly requires: "separate-authenticated-spawn-provenance-and-complete-os-census";
+} | {
+    ok: false;
+    reason: string;
+};
+export type PreparedCandidateObserverGapEligibility = ReturnType<typeof preparedCandidateObserverGapEligibility>;