toolroll 0.5.0

package/dist/process-recovery-services.js

@@ -0,0 +1,191 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { release } from "node:os";
+import { normalizeBootId } from "./boot-identity.js";
+import { changedDarwinProcessIdentities, collectDarwinCoalitionSnapshot } from "./process-recovery-native.js";
+const label = "com.apple.speech.SpeechSynthesisServerXPC";
+const bundle = "/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/SpeechSynthesis.framework/Versions/A/XPCServices/SpeechSynthesisServerXPC.xpc";
+export const APP_SERVICE_EXECUTABLE = `${bundle}/Contents/MacOS/SpeechSynthesisServerXPC`;
+const executable = APP_SERVICE_EXECUTABLE;
+const chrome = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+const clonePathSha256 = "0e92ba8224883b668b6becb0f2768fdca1912630e176ded161b6786822ec2a73";
+const cloneSha256 = "fe21b4086d7f035b17ce4c8ff9d1ceef88eb9510252a5b311d7a5aa48c352b32";
+const cloneCdHash = "fab09b6e6ce70ffb18f6f672564b1215c8a7c75f";
+export const APP_SERVICE_PLATFORM = Object.freeze({ osRelease: "25.5.0", osBuild: "25F84", serviceType: "Application", label,
+    codesignSha256: "214d455584d19abc0d74d02b9cbc7d3da6bdcb0596c235e6156dd9ed2f4e1ba7", clonePathSha256, cloneSha256, cloneCdHash,
+    launchctlSha256: "b1f2b90f349938cc4c3c9234f11cefd05545f7b4bfe9b1751ac01f1cb27d3714",
+    plistSha256: "c26cec3d7afe55cb33c360018c04d0c848df45dbe1ea3c3c50c9dd3b9d483aee",
+    executableSha256: "0be2afc6ec7bce4c06e14cdfe7e5155b394f98a689189f069a6ca8611fd7911d" });
+const env = { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C", TZ: "UTC" };
+const command = (file, args) => execFileSync(file, args, { encoding: "utf8", env, timeout: 10_000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024 });
+const digest = (data) => createHash("sha256").update(data).digest("hex");
+const hash = (path) => digest(readFileSync(path));
+const isChrome = (path) => path !== null && (path === chrome || digest(path) === clonePathSha256);
+function platformMatches() {
+    return process.platform === "darwin" && release() === APP_SERVICE_PLATFORM.osRelease && command("/usr/bin/sw_vers", ["-buildVersion"]).trim() === APP_SERVICE_PLATFORM.osBuild &&
+        hash("/usr/bin/codesign") === APP_SERVICE_PLATFORM.codesignSha256 && hash("/bin/launchctl") === APP_SERVICE_PLATFORM.launchctlSha256 && hash(`${bundle}/Contents/Info.plist`) === APP_SERVICE_PLATFORM.plistSha256 && hash(executable) === APP_SERVICE_PLATFORM.executableSha256;
+}
+const id = (s) => typeof s === "string" && /^[1-9][0-9]{0,19}$/.test(s) && BigInt(s) <= 0xffffffffffffffffn;
+function requireFact(ok) { if (!ok)
+    throw Error("unrecognized-app-service-fact"); }
+/** launchctl explicitly promises no stable print API. This parser is restricted
+ * to the inspected tool/OS hashes, entire balanced records and singleton fields.
+ * Environment continuations cannot create identity fields or hide duplicates. */
+function record(text, header) {
+    requireFact(!/[^\x09\x0a\x20-\x7e]/.test(text));
+    const lines = text.trimEnd().split("\n");
+    requireFact(lines.shift() === `${header} = {` && lines.pop() === "}");
+    const fields = new Map(), sections = new Map();
+    const stack = [], seen = new Set();
+    const allowed = new Set(["security context", "environment", "inherited environment", "default environment", "services", "service stubs", "unmanaged processes", "endpoints", "task-special ports", "resource coalition", "jetsam coalition"]);
+    for (const line of lines) {
+        if (line === "")
+            continue;
+        const m = /^(\t*)([^\t].*)$/.exec(line);
+        requireFact(m);
+        const depth = m[1].length, value = m[2];
+        if (value === "}") {
+            requireFact(stack.length && depth === stack.length);
+            stack.pop();
+            continue;
+        }
+        if (stack.length === 1 && stack[0] === "task-special ports") {
+            requireFact(depth === 3 && /^ *0x[0-9a-f]+ +[0-9]+ +[a-z-]+ +\([^{}=\t]*\)$/.test(value));
+            continue;
+        }
+        requireFact(depth === stack.length + 1);
+        const open = /^([^{}]+) = \{$/.exec(value);
+        if (open) {
+            const key = open[1], path = [...stack, key].join("/");
+            requireFact(!seen.has(path) && !fields.has(key) && (stack.length === 0 ? allowed.has(key) : stack.length === 1 && stack[0] === "endpoints" && /^"?[A-Za-z0-9._-]+"?$/.test(key)));
+            seen.add(path);
+            stack.push(key);
+            if (stack.length === 1)
+                sections.set(key, []);
+            continue;
+        }
+        requireFact(!/[{}]/.test(value));
+        if (stack.length) {
+            if (stack[0].endsWith("environment"))
+                requireFact(stack.length === 1 && /^[A-Za-z_][A-Za-z0-9_]* => [^\t]*$/.test(value));
+            else
+                requireFact(!/^(?:pid|uniqueid|handle|creator|domain|program|path|bundle id) = /.test(value));
+            sections.get(stack[0]).push(line);
+            continue;
+        }
+        const field = /^([^=]+) = ([^\t]*)$/.exec(value);
+        requireFact(field);
+        requireFact(!fields.has(field[1]) && !seen.has(field[1]));
+        fields.set(field[1], field[2]);
+    }
+    requireFact(!stack.length);
+    return { fields, sections };
+}
+function sealed(s, anchorPids, bound) {
+    const a = s.anchors.find(p => p.pid === bound.pid), counters = s.counterBefore;
+    return s.schema === 1 && s.complete && s.stable && s.kernelTableRead && s.countersStable && s.unreadableMembershipCount === 0 &&
+        !s.errors.length && !s.identityChanges.length && !s.anchorIdentityChanges.length && !!normalizeBootId(s.bootId ?? "") &&
+        s.osRelease === APP_SERVICE_PLATFORM.osRelease && s.anchorPids.length === anchorPids.length && anchorPids.every(pid => s.anchorPids.includes(pid)) &&
+        a?.uniqueId === bound.uniqueId && a.traced === false && s.collector?.exited === true &&
+        s.processes.some(p => p.pid === s.collector.pid && p.uniqueId === s.collector.uniqueId) &&
+        !!counters && id(counters.tasksStarted) && /^(0|[1-9][0-9]*)$/.test(counters.tasksExited) &&
+        counters.tasksStarted === s.counterAfter?.tasksStarted && counters.tasksExited === s.counterAfter?.tasksExited &&
+        BigInt(counters.tasksStarted) - BigInt(counters.tasksExited) === BigInt(s.processes.length) &&
+        new Set(s.processes.map(p => p.pid)).size === s.processes.length && new Set(s.processes.map(p => p.uniqueId)).size === s.processes.length &&
+        s.processes.every(p => Number.isSafeInteger(p.pid) && p.pid > 1 && p.pid <= 0x7fffffff && id(p.uniqueId) && p.resourceCoalitionId === s.resourceCoalitionId);
+}
+function signing(pid, path, phase) {
+    if (path === chrome)
+        return null;
+    phase("owner-signature-bytes");
+    requireFact(digest(path) === clonePathSha256 && hash(path) === cloneSha256);
+    // Dynamic PID verification checks the running code. A display alone is not
+    // validation; the inspected clone's static resource-metadata check refused.
+    const run = (args) => {
+        const r = spawnSync("/usr/bin/codesign", args, { encoding: "utf8", env, timeout: 10_000, killSignal: "SIGKILL", maxBuffer: 65536, stdio: "pipe" });
+        requireFact(!r.error && r.status === 0 && r.signal === null && r.stdout === "");
+        return r.stderr;
+    };
+    phase("owner-signature-verify");
+    run(["--verify", "--strict", `+${pid}`]);
+    phase("owner-signature-display");
+    const display = run(["--display", "--verbose=4", `+${pid}`]);
+    // codesign localizes its non-authoritative timestamp with a narrow no-break
+    // space even under LC_ALL=C. Identity lines remain exact ASCII singletons.
+    requireFact(display.split("\n").every(line => !/[^\x20-\x7e]/.test(line) || /^Timestamp=[\x20-\x7e]*\u202f(?:AM|PM)$/.test(line)));
+    const value = (key) => { const all = display.split("\n").filter(l => l.startsWith(`${key}=`)); requireFact(all.length === 1); return all[0].slice(key.length + 1); };
+    requireFact(value("Executable") === path && value("Identifier") === "com.google.Chrome" && value("TeamIdentifier") === "EQHXZ8M8AV" && value("CDHash") === cloneCdHash);
+    return { identifier: "com.google.Chrome", teamId: "EQHXZ8M8AV", cdHash: cloneCdHash, dynamicallyVerified: true };
+}
+function bindings(s, ownerPids, bound, phase) {
+    const result = [];
+    for (const ownerPid of ownerPids) {
+        phase("owner-identity");
+        const owner = s.processes.find(p => p.pid === ownerPid);
+        requireFact(owner && id(owner.uniqueId) && BigInt(owner.uniqueId) <= BigInt(bound.uniqueId) && owner.traced === false && isChrome(owner.executable) && owner.uid !== null && Number.isInteger(owner.pidVersion) && owner.pidVersion > 0);
+        phase("owner-domain");
+        const domain = `pid/${ownerPid}`, d = record(command("/bin/launchctl", ["print", domain]), domain);
+        requireFact(d.fields.get("type") === "pid" && d.fields.get("handle") === String(ownerPid) && d.fields.get("uniqueid") === owner.uniqueId &&
+            d.fields.get("creator") === `Google Chrome[${ownerPid}]` && d.fields.get("creator euid") === String(owner.uid) && d.fields.get("originator") === "/Applications/Google Chrome.app");
+        const rows = d.sections.get("services");
+        requireFact(rows);
+        const entries = rows.map(line => { const m = /^\t\t\s*(0|[1-9][0-9]*|-)\s+([-A-Za-z0-9?()]+)\s+([A-Za-z0-9._-]+)$/.exec(line); requireFact(m); return { pid: m[1], label: m[3] }; });
+        requireFact(new Set(entries.map(e => e.label)).size === entries.length);
+        // A pending job supplies no live identity or exit evidence. Any unmatched
+        // process in the final native census still needs its own exclusion proof.
+        const entry = entries.find(e => e.label === label);
+        if (!entry || entry.pid === "-" || entry.pid === "0")
+            continue;
+        phase("service-job");
+        const pid = Number(entry.pid), process = s.processes.find(p => p.pid === pid);
+        requireFact(process && id(process.uniqueId) && process.traced === false && process.uid === owner.uid && process.executable === executable && process.resourceCoalitionId === owner.resourceCoalitionId);
+        const job = record(command("/bin/launchctl", ["print", `${domain}/${label}`]), `${domain}/${label}`).fields;
+        requireFact(job.get("type") === "XPCService" && job.get("state") === "running" && job.get("domain") === `${domain} [Google Chrome]` &&
+            job.get("pid") === String(pid) && job.get("path") === bundle && job.get("program") === executable && job.get("bundle id") === label && job.get("forks") === "0" && job.get("execs") === "1");
+        requireFact(!result.some(p => p.pid === pid));
+        const ownerSigning = signing(ownerPid, owner.executable, phase);
+        result.push({ pid, uniqueId: process.uniqueId, ownerPid, ownerUniqueId: owner.uniqueId, ownerExecutable: owner.executable, ownerPidVersion: owner.pidVersion, ownerSigning, uid: owner.uid, resourceCoalitionId: owner.resourceCoalitionId, executable, domain, platform: APP_SERVICE_PLATFORM });
+    }
+    return result;
+}
+/** Read-only observations, not exit/custody authority. Caller must authenticate
+ * upperBound historically and consume these facts inside its existing proof. */
+export async function collectPreexistingAppServices(args) {
+    let phase = "platform";
+    const at = (value) => { phase = value; };
+    try {
+        if (!platformMatches())
+            return { ok: false, reason: "app-service-platform-unrecognized" };
+        const native = { ...args.native };
+        const initial = structuredClone(args.snapshot), bound = { ...args.upperBound }, anchorPids = [...args.anchorPids];
+        at("initial-census");
+        requireFact(id(bound.uniqueId) && anchorPids.includes(bound.pid) && new Set(anchorPids).size === anchorPids.length && sealed(initial, anchorPids, bound));
+        requireFact(initial.nativeSourceSha256 === native.sourceSha256 && initial.nativeExecutableSha256 === native.executableSha256);
+        const owners = initial.processes.filter(p => isChrome(p.executable) && p.traced === false && id(p.uniqueId) && BigInt(p.uniqueId) <= BigInt(bound.uniqueId)).map(p => p.pid).sort((a, b) => a - b);
+        const first = bindings(initial, owners, bound, at);
+        const collect = () => collectDarwinCoalitionSnapshot({ native, resourceCoalitionId: initial.resourceCoalitionId, anchorPids, maxAttempts: 1 });
+        const validate = (next) => {
+            requireFact(sealed(next, anchorPids, bound) && normalizeBootId(next.bootId ?? "") === normalizeBootId(initial.bootId ?? "") && next.host === initial.host && next.resourceCoalitionId === initial.resourceCoalitionId && next.nativeSourceSha256 === initial.nativeSourceSha256 && next.nativeExecutableSha256 === initial.nativeExecutableSha256);
+            const pids = new Set([...owners, ...first.map(p => p.pid)]);
+            requireFact(!changedDarwinProcessIdentities(initial.processes.filter(p => pids.has(p.pid)), next.processes.filter(p => pids.has(p.pid))).length &&
+                !changedDarwinProcessIdentities(initial.anchors, next.anchors).length);
+        };
+        at("middle-census");
+        const middle = await collect();
+        validate(middle);
+        const repeated = bindings(middle, owners, bound, at);
+        at("repeated-binding");
+        requireFact(JSON.stringify(first) === JSON.stringify(repeated));
+        at("platform");
+        if (!platformMatches())
+            return { ok: false, reason: "app-service-platform-unrecognized" };
+        at("final-census");
+        const final = await collect();
+        validate(final);
+        return { ok: true, snapshot: final, services: first };
+    }
+    catch {
+        return { ok: false, reason: "app-service-observation-refused", diagnostic: { phase } };
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { Store } from "./store.js";
+/** A one-shot legacy repair, never a force-clear API. It recollects its own
+ * pinned historical and current OS facts. Serialized successful reports are
+ * deliberately not inputs. Inspection is the default and never writes custody.
+ * The caller opens the compatible Store; this function never migrates it. */
+export declare function recoverPreparedObserverGap(store: Store, input: {
+    profilePath: string;
+    compilationDirectory: string;
+    evidenceRoot: string;
+    mode: "inspect" | "record";
+}): Promise<{
+    ok: false;
+    reason: string;
+} | {
+    runId: number;
+    witnessIds: number[];
+    certificateDigest: string;
+    observedAt: string;
+    assumptions: string[];
+    ok: true;
+    recorded: false;
+} | {
+    runId: number;
+    witnessIds: number[];
+    certificateDigest: string;
+    observedAt: string;
+    assumptions: string[];
+    ok: true;
+    recorded: true;
+    actionId: number;
+    certificatePath: string;
+}>;

package/dist/process-recovery-settlement.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { currentBootId } from "./boot-identity.js";
+import { assessDarwinCoalitionRecovery } from "./process-recovery-coalition.js";
+import { preparedCandidateObserverGapEligibility } from "./process-recovery-eligibility.js";
+import { collectLegacySourceProvenance, collectedLegacyProvenanceOf } from "./process-recovery-provenance.js";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** A one-shot legacy repair, never a force-clear API. It recollects its own
+ * pinned historical and current OS facts. Serialized successful reports are
+ * deliberately not inputs. Inspection is the default and never writes custody.
+ * The caller opens the compatible Store; this function never migrates it. */
+export async function recoverPreparedObserverGap(store, input) {
+    const refuse = (reason) => ({ ok: false, reason });
+    if (input.mode !== "inspect" && input.mode !== "record")
+        return refuse("invalid-recovery-mode");
+    const collected = await collectLegacySourceProvenance(store.handle, input);
+    // The collector exposes only fixed diagnostic codes. Preserve the failed
+    // phase so an operator can distinguish an unreadable anchor from a later
+    // source or service observation without exposing subprocess output.
+    if (!collected.ok)
+        return collected;
+    const live = collectedLegacyProvenanceOf(collected.proof);
+    if (!live)
+        return refuse("uncollected-process-evidence");
+    const { receipt, snapshot, anchor } = live;
+    const now = new Date();
+    const context = { runId: receipt.targetRun, evidenceRoot: input.evidenceRoot, now,
+        host: hostname(), bootId: currentBootId() };
+    let matchingRoot = false;
+    try {
+        matchingRoot = realpathSync(input.evidenceRoot) === join(dirname(anchor.databasePath), "evidence");
+    }
+    catch { /* Refuse an unreadable evidence root. */ }
+    if (context.host !== receipt.host || context.bootId !== receipt.bootId || !matchingRoot ||
+        ![snapshot.startedAt, snapshot.finishedAt].every(value => Number.isFinite(Date.parse(value))) || Date.parse(snapshot.finishedAt) > now.getTime() ||
+        Date.parse(snapshot.startedAt) > Date.parse(snapshot.finishedAt))
+        return refuse("recovery-context-changed");
+    const eligible = preparedCandidateObserverGapEligibility(store, context);
+    if (!eligible.ok)
+        return refuse(eligible.reason);
+    if (eligible.binding.run.head !== receipt.head || eligible.binding.scope.digest !== receipt.scopeDigest ||
+        Date.parse(snapshot.startedAt) <= Date.parse(eligible.binding.run.finishedAt) ||
+        snapshot.nativeSourceSha256 !== anchor.nativeSourceSha256 || snapshot.nativeExecutableSha256 !== anchor.nativeExecutableSha256 ||
+        sha256(JSON.stringify(snapshot)) !== receipt.snapshotDigest)
+        return refuse("recovery-source-mismatch");
+    const assessed = assessDarwinCoalitionRecovery({ host: context.host, bootId: receipt.bootId,
+        resourceCoalitionId: receipt.resourceCoalitionId, sourceRoot: receipt.sourceRoot,
+        preRunUpperBound: receipt.preRunUpperBound, snapshot, preexistingAppServices: receipt.preexistingAppServices });
+    if (!assessed.ok)
+        return refuse("surviving-processes-not-excluded");
+    const certificate = { schema: 1, kind: "prepared-observer-gap-absence", collectedAt: now.toISOString(),
+        eligibility: eligible, provenance: receipt, anchor, inventory: snapshot, assessment: assessed,
+        statement: "Positive current absence of direct and ordinary-fork descendants under the recorded audited first-party path and trusted execution assumptions. This observation alone is not a database settlement; a matching committed action-ledger entry records application." };
+    const bytes = Buffer.from(JSON.stringify(certificate) + "\n"), digest = sha256(bytes);
+    const result = { runId: receipt.targetRun, witnessIds: [...eligible.binding.unknownWitnessIds],
+        certificateDigest: digest, observedAt: snapshot.finishedAt, assumptions: receipt.assumptions };
+    if (input.mode === "inspect")
+        return { ok: true, recorded: false, ...result };
+    // Preserve the entire pre-mutation row inventory and OS observations first.
+    // Exclusive, owned files remain as observations if a later transaction fails.
+    const directory = join(dirname(anchor.databasePath), "process-recovery");
+    let certificatePath;
+    try {
+        mkdirSync(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            return refuse("recovery-audit-unavailable");
+    }
+    try {
+        const stat = lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || realpathSync(directory) !== directory)
+            return refuse("recovery-audit-unavailable");
+        certificatePath = join(directory, digest + ".json");
+        const fd = openSync(certificatePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        try {
+            writeFileSync(fd, bytes);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        const parent = openSync(directory, constants.O_RDONLY);
+        try {
+            fsyncSync(parent);
+        }
+        finally {
+            closeSync(parent);
+        }
+    }
+    catch {
+        return refuse("recovery-audit-unavailable");
+    }
+    try {
+        return store.transact(() => store.savepoint(() => {
+            if (hostname() !== context.host || currentBootId() !== context.bootId)
+                throw Error("recovery-context-changed");
+            const current = preparedCandidateObserverGapEligibility(store, { ...context, now: new Date() });
+            if (!current.ok || current.digest !== eligible.digest)
+                throw Error("recovery-custody-changed");
+            const fd = openSync(certificatePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                const stat = fstatSync(fd);
+                if (!stat.isFile() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o600 || sha256(readFileSync(fd)) !== digest)
+                    throw Error("recovery-audit-changed");
+            }
+            finally {
+                closeSync(fd);
+            }
+            for (const row of current.binding.witnesses.filter(row => current.binding.unknownWitnessIds.includes(row.id))) {
+                const update = store.handle.prepare(`UPDATE run_process SET exited_at = ?
+          WHERE id = ? AND run = ? AND pid IS ? AND host = ? AND process_group = ?
+            AND observed_at = ? AND exited_at IS NULL AND boot_id IS ? AND containment IS ?
+            AND container IS ? AND container_identity IS ? AND container_empty_at IS ?`)
+                    .run(snapshot.finishedAt, row.id, row.run, row.pid, row.host, row.process_group, row.observed_at, row.boot_id, row.containment, row.container, row.container_identity, row.container_empty_at);
+                if (Number(update.changes) !== 1)
+                    throw Error("recovery-custody-changed");
+            }
+            if (store.stopQuiescenceProblem(receipt.targetRun) !== null)
+                throw Error("run-still-not-quiescent");
+            const actionId = store.recordAction({ at: new Date().toISOString(), actor: "system", repo: current.binding.run.repo,
+                taskId: current.binding.run.taskId, runId: receipt.targetRun, action: "process absence recovered",
+                outcome: digest, source: "work" });
+            return { ok: true, recorded: true, ...result, actionId, certificatePath };
+        }));
+    }
+    catch {
+        return refuse("recovery-not-recorded");
+    }
+}

package/dist/process-recovery.d.ts

@@ -0,0 +1,41 @@
+import type { DarwinProcessRecoverySnapshot } from "./process-recovery-native.js";
+export type ProcessRecoveryAssessment = {
+    ok: true;
+    observedAt: string;
+    external: {
+        pid: number;
+        basis: "predates-run" | "managed-service" | "pre-existing-app-service" | "ancestry" | "owned-probe";
+        anchor: number;
+    }[];
+} | {
+    ok: false;
+    problems: string[];
+    unresolved: number[];
+};
+export type ProcessRecoveryAnchor = {
+    pid: number;
+    uniqueId: string;
+};
+/** Read-only assessment of a COMPLETE, stable OS census. The caller must
+ * separately prove that the missing record is an observation gap, every
+ * actual spawn is accounted for, every recorded owned process has positive
+ * exit evidence, and the terminal run cannot launch more work, including
+ * outstanding delegated launches.
+ * preRunIdentities must come from authenticated observations on this host/boot
+ * before the earliest possible task spawn, not from current wall-clock birth
+ * times. Trusted managed identities require independent proof that the job
+ * is external to the task, including jobs the task could delegate to launchd.
+ * A launchd service listing alone establishes no such independence. This
+ * pure function checks identity binding, not the provenance of these inputs.
+ * A missing spawn cannot be recovered by following its old worker's ancestry.
+ * Numeric PIDs, process names and 32-bit original-parent versions authorize
+ * nothing. In particular, reparenting to launchd is never exit evidence. */
+export declare function assessDarwinObserverRecovery(args: {
+    host: string;
+    bootId: string;
+    boundary: string;
+    runFinishedAt: string;
+    preRunIdentities: readonly ProcessRecoveryAnchor[];
+    trustedExternalManagedServiceIdentities: readonly ProcessRecoveryAnchor[];
+    snapshot: DarwinProcessRecoverySnapshot;
+}): ProcessRecoveryAssessment;

package/dist/process-recovery.js

@@ -0,0 +1,91 @@
+import { normalizeBootId } from "./boot-identity.js";
+const iso = (value) => {
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value ? time : null;
+};
+const identity = (value) => typeof value === "string" && /^[1-9][0-9]{0,19}$/.test(value) && BigInt(value) <= 0xffffffffffffffffn;
+/** Read-only assessment of a COMPLETE, stable OS census. The caller must
+ * separately prove that the missing record is an observation gap, every
+ * actual spawn is accounted for, every recorded owned process has positive
+ * exit evidence, and the terminal run cannot launch more work, including
+ * outstanding delegated launches.
+ * preRunIdentities must come from authenticated observations on this host/boot
+ * before the earliest possible task spawn, not from current wall-clock birth
+ * times. Trusted managed identities require independent proof that the job
+ * is external to the task, including jobs the task could delegate to launchd.
+ * A launchd service listing alone establishes no such independence. This
+ * pure function checks identity binding, not the provenance of these inputs.
+ * A missing spawn cannot be recovered by following its old worker's ancestry.
+ * Numeric PIDs, process names and 32-bit original-parent versions authorize
+ * nothing. In particular, reparenting to launchd is never exit evidence. */
+export function assessDarwinObserverRecovery(args) {
+    const { snapshot } = args;
+    const refuse = (...problems) => ({ ok: false, problems, unresolved: [] });
+    const boundary = iso(args.boundary), ended = iso(args.runFinishedAt);
+    const began = iso(snapshot.startedAt), finished = iso(snapshot.finishedAt);
+    const boot = normalizeBootId(args.bootId);
+    if (boot === null || snapshot.bootId === null || normalizeBootId(snapshot.bootId) !== boot || snapshot.host !== args.host)
+        return refuse("The process census belongs to a different or unreadable host/boot.");
+    if (boundary === null || ended === null || began === null || finished === null || boundary > ended || ended > began || began > finished)
+        return refuse("The run and process census timestamps do not establish a recovery interval.");
+    if (snapshot.schema !== 1 || !snapshot.complete || !snapshot.stable || snapshot.errors.length || snapshot.identityChanges.length)
+        return refuse("The complete process census could not be read and revalidated without changes.");
+    const rows = new Map(snapshot.processes.map(row => [row.pid, row]));
+    if (rows.size === 0 || rows.size !== snapshot.processes.length || !rows.has(1) ||
+        snapshot.processes.some(row => !Number.isSafeInteger(row.pid) || row.pid <= 0 || !identity(row.uniqueId)) ||
+        new Set(snapshot.processes.map(row => row.uniqueId)).size !== rows.size)
+        return refuse("The process census has missing or ambiguous kernel identities.");
+    const anchorsValid = (anchors) => Array.isArray(anchors) &&
+        anchors.every(anchor => Number.isSafeInteger(anchor.pid) && anchor.pid > 0 && identity(anchor.uniqueId)) &&
+        new Set(anchors.map(anchor => anchor.pid)).size === anchors.length &&
+        new Set(anchors.map(anchor => anchor.uniqueId)).size === anchors.length;
+    if (!anchorsValid(args.preRunIdentities) || !anchorsValid(args.trustedExternalManagedServiceIdentities))
+        return refuse("The authenticated external process identities are malformed or ambiguous.");
+    const preRun = new Map(args.preRunIdentities.map(anchor => [anchor.pid, anchor.uniqueId]));
+    const trustedManaged = new Map(args.trustedExternalManagedServiceIdentities.map(anchor => [anchor.pid, anchor.uniqueId]));
+    const probes = new Set(snapshot.collectorPids);
+    if ([...probes].some(pid => !Number.isSafeInteger(pid) || pid <= 1))
+        return refuse("The owned diagnostic process inventory is malformed.");
+    const managed = new Set(snapshot.managedServices.filter(service => {
+        const row = rows.get(service.pid);
+        return service.identityBound && identity(service.uniqueId) && row?.uniqueId === service.uniqueId &&
+            trustedManaged.get(service.pid) === service.uniqueId &&
+            service.beforeUniqueId === service.uniqueId && service.afterUniqueId === service.uniqueId &&
+            /^(system|gui\/[0-9]+|user\/[0-9]+|pid\/[0-9]+)$/.test(service.domain) && service.label.length > 0;
+    }).map(service => service.pid));
+    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 = pid) => { external.set(pid, { pid, basis, anchor }); return true; };
+        if (probes.has(pid))
+            return accept("owned-probe");
+        if (preRun.get(pid) === row.uniqueId)
+            return accept("predates-run");
+        if (managed.has(pid))
+            return accept("managed-service");
+        // An orphan may exec and acquire launchd's parentUniqueId. Even a launchd
+        // service record needs independent caller provenance; there is no PID1
+        // ancestry shortcut. Wall birth times cannot establish age after a
+        // clock adjustment. Kernel fork identities must increase along each edge,
+        // also refusing reparenting to a later process after historical tracing.
+        if (row.ppid === null || 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 gone = visit(parent.pid);
+        visiting.delete(pid);
+        return gone ? accept("ancestry", external.get(parent.pid).anchor) : false;
+    };
+    const unresolved = snapshot.processes.filter(row => !visit(row.pid)).map(row => row.pid).sort((a, b) => a - b);
+    return unresolved.length ? { ok: false, problems: ["Some current processes cannot be distinguished from unobserved descendants."], unresolved }
+        : { ok: true, observedAt: snapshot.finishedAt, external: [...external.values()].sort((a, b) => a.pid - b.pid) };
+}

package/dist/process-tree.d.ts

@@ -0,0 +1,41 @@
+import { type ChildProcess } from "node:child_process";
+export type ObservedProcess = {
+    pid: number;
+    group: boolean;
+};
+export type ProcessObservationFailure = {
+    phase: "sample" | "periodic" | "final-exit" | "stop" | "supervisor";
+    operation: "snapshot" | "descendant-write" | "exit-write" | "signal" | "diagnostic-read";
+    code: string;
+    rootPid: number | null;
+    at: string;
+    identityUnknown: boolean;
+};
+export type ProcessTreeObserver = {
+    onDescendant?: (pid: number, group: boolean) => void;
+    /** A dedicated durable fallback for the exact identities already observed.
+     * Return true only after preserving every row. Never replay arbitrary callbacks. */
+    onDescendantWriteFailure?: (rows: readonly ObservedProcess[]) => boolean;
+    /** An observed PID (and its group, when recorded) is now proven absent.
+     * This never follows merely from reparenting or the root's exit. */
+    onDescendantExit?: (pid: number, group: boolean) => void;
+    /** Diagnostics never establish exit or erase a custody witness. */
+    onObservationFailure?: (failure: ProcessObservationFailure) => void;
+    onUnknown?: () => void;
+};
+/** Private supervisor pipe input. Keep only validated identifier diagnostics. */
+export declare function readProcessObservationFailure(value: unknown): ProcessObservationFailure | null;
+/** Capture current descendants before asking an owned process to exit.
+ * A cooperative root may exit before the next periodic observation; even
+ * a killed tool can retain its PID briefly after its process group is gone. */
+export declare function sampleProcessTree(child: ChildProcess): void;
+/** Observe escaped process groups while their ancestry is still provable.
+ * Durable witnesses prevent recovery from mistaking a dead harness for a dead
+ * shell. They never grant permission to send a signal after worker recovery. */
+export declare function observeProcessTree(child: ChildProcess, observer: ProcessTreeObserver): void;
+/** Freeze the owned handle, then its live descendants before killing them.
+ * Claude's tool shells create new process groups, so killing only -rootPid
+ * leaves writers behind. Re-scan after freezing parents to catch a child born
+ * during the previous scan. Every target comes from current ancestry of the
+ * still-owned handle, never from a saved PID. Unknown ancestry stays blocked. */
+export declare function stopProcessTree(child: ChildProcess): boolean;