toolroll 0.5.0

package/dist/process-recovery-eligibility.js

@@ -0,0 +1,170 @@
+/** Read-only eligibility, NEVER process-exit evidence or permission to clear a
+ * witness. This narrow classifier relies on the installed native builder path:
+ * its prepared-candidate handoff is machine-authored, and its actual v1 gate
+ * receipt is sealed only after awaited witnessedRunner returned and finished
+ * every direct beforeSpawn reservation. The caller must separately authenticate
+ * that execution provenance, the current host/boot, and a complete OS census.
+ * In particular, an eligible null PID can still hide an escaped descendant. */
+import { createHash } from "node:crypto";
+import { normalizeBootId } from "./boot-identity.js";
+import { scopeApprovedForDispatch } from "./dispatch.js";
+import { readVerifiedArtifact } from "./evidence.js";
+import { ownedProcessCount, runOwnerTag } from "./exec.js";
+import { scopeAuthorityOf } from "./scope.js";
+import { isVerificationReceipt, VERIFICATION_RECEIPT_CAPTURE, verificationEvidence } from "./verification-evidence.js";
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const instant = (value) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const commit = (value) => typeof value === "string" && /^[a-f0-9]{40}$/.test(value);
+const positive = (value) => Number.isSafeInteger(value) && Number(value) > 0;
+const artifactBinding = (a) => ({ id: a.id, run: a.run, kind: a.kind, key: a.key, sha256: a.sha256,
+    bytesOriginal: a.bytesOriginal, bytesStored: a.bytesStored, truncated: a.truncated, redacted: a.redacted,
+    capture: a.capture, captureStatus: a.captureStatus, createdAt: a.createdAt });
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+// A successful digest is only a saved-state prerequisite. Settlement must separately
+// prove provenance and absence, then recheck this same binding inside its transaction.
+export function preparedCandidateObserverGapEligibility(store, input) {
+    const refuse = (reason) => ({ ok: false, reason });
+    try {
+        // SAVEPOINT supplies a consistent read snapshot, including when a caller
+        // already has a transaction. No Store mutator or process probe runs here.
+        return store.savepoint(() => {
+            const { runId, evidenceRoot, now, host, bootId } = input;
+            if (!positive(runId) || !Number.isFinite(now.getTime()) || !host || /[\x00-\x1f\x7f]/.test(host) ||
+                bootId === null || normalizeBootId(bootId) !== bootId)
+                return refuse("current-host-boot-unavailable");
+            const run = store.getRun(runId);
+            if (!run || run.role !== "builder" || (run.outcome !== "built" && run.outcome !== "no-change") ||
+                !instant(run.startedAt) || !instant(run.finishedAt) || Date.parse(run.finishedAt) < Date.parse(run.startedAt) ||
+                Date.parse(run.finishedAt) > now.getTime())
+                return refuse("not-terminal-prepared-builder");
+            if (run.providerStartedAt !== null || run.sessionId !== null || run.attendedAuthorization != null || run.contestant !== null ||
+                !commit(run.baseRevision) || !commit(run.headRevision) || !run.branch || !run.worktree)
+                return refuse("provider-or-run-identity-unproven");
+            const ref = store.refById(run.taskRef);
+            if (!ref?.repo || store.getTask(ref.externalId)?.state !== "done")
+                return refuse("task-not-terminal");
+            const scope = store.getScope(ref.externalId);
+            if (!scope || !commit(scope.candidate) || scope.digest !== run.scopeDigest || scope.approvedDigest !== scope.digest ||
+                !instant(scope.approvedAt) || Date.parse(scope.approvedAt) > Date.parse(run.startedAt) ||
+                !scope.approvedBy || !scopeAuthorityOf(scope).ok || !store.sealedRouteOf(ref.externalId).ok ||
+                !scopeApprovedForDispatch(store, ref.id, now))
+                return refuse("prepared-scope-not-current");
+            const signerValid = (name) => {
+                const signer = store.accountOf(name);
+                return signer?.role === "approver" && signer.revokedAt === null && store.accountCanAccess(name, ref.repo);
+            };
+            if (!signerValid(scope.approvedBy))
+                return refuse("scope-signer-not-current");
+            const command = store.liveVerifyCommand(ref.repo);
+            if (!command || !positive(command.id) || !positive(command.timeoutMs) || !command.command ||
+                !instant(command.approvedAt) || Date.parse(command.approvedAt) > Date.parse(run.startedAt) ||
+                command.revokedAt !== null || !signerValid(command.approvedBy))
+                return refuse("verification-grant-not-current");
+            if (store.handle.prepare("SELECT 1 FROM claim WHERE task_ref = ? AND released_at IS NULL AND expires_at >= ? LIMIT 1").get(ref.id, now.toISOString()) ||
+                store.activeHolds(ref.id, now).length || store.handle.prepare("SELECT 1 FROM run WHERE task_ref = ? AND (outcome IS NULL OR finished_at IS NULL) LIMIT 1").get(ref.id))
+                return refuse("task-still-active-or-held");
+            const owned = store.ownedRunsOf(runId);
+            const ownedRuns = [];
+            for (const id of owned) {
+                const one = store.getRun(id);
+                if (!one || one.outcome === null || !instant(one.startedAt) || !instant(one.finishedAt) ||
+                    Date.parse(one.finishedAt) < Date.parse(one.startedAt) || Date.parse(one.finishedAt) > Date.parse(run.finishedAt) ||
+                    one.providerStartedAt !== null || one.sessionId !== null ||
+                    store.applicableStopFor(id) !== null || ownedProcessCount(runOwnerTag(store, id)) > 0 ||
+                    store.heldSessionOf(id)?.endedAt === null)
+                    return refuse("owned-run-not-settled");
+                ownedRuns.push({ id, taskRef: one.taskRef, leaseId: one.leaseId, parentRun: one.parentRun, role: one.role,
+                    outcome: one.outcome, startedAt: one.startedAt, finishedAt: one.finishedAt, providerStartedAt: one.providerStartedAt, sessionId: one.sessionId });
+            }
+            const machine = store.proofVerdictFor(runId);
+            if (!machine || (machine.machineVerdict ?? machine.verdict) !== "verified" || !instant(machine.decidedAt) ||
+                Date.parse(machine.decidedAt) > now.getTime())
+                return refuse("machine-verification-unproven");
+            const artifacts = store.artifactsFor(runId);
+            const receipts = artifacts.filter(isVerificationReceipt);
+            const logs = artifacts.filter(a => a.kind === "check-log");
+            if (receipts.length !== 1 || receipts[0].capture !== VERIFICATION_RECEIPT_CAPTURE || logs.length !== 1 ||
+                receipts[0].captureStatus !== "ok" || logs[0].captureStatus !== "ok")
+                return refuse("actual-v1-gate-required");
+            const gateArtifact = receipts[0], log = logs[0];
+            const gate = verificationEvidence(store, evidenceRoot, runId);
+            if (!gate.ok || gate.bytes === null)
+                return refuse("verification-evidence-unavailable");
+            const receipt = JSON.parse(gate.bytes);
+            if (receipt.version !== 1 || receipt.source !== undefined || receipt.reusedFrom !== undefined || receipt.executedHere !== undefined ||
+                receipt.result?.configured !== true || receipt.result.ran !== true || receipt.result.exitCode !== 0 ||
+                Object.keys(receipt.result).some(key => !["configured", "ran", "exitCode", "setupReplayed"].includes(key)) ||
+                (receipt.result.setupReplayed !== undefined && receipt.result.setupReplayed !== true) ||
+                !instant(gateArtifact.createdAt) || Date.parse(gateArtifact.createdAt) < Date.parse(run.startedAt) ||
+                Date.parse(gateArtifact.createdAt) > Date.parse(machine.decidedAt) ||
+                Date.parse(gateArtifact.createdAt) > Date.parse(run.finishedAt))
+                return refuse("actual-passing-gate-unproven");
+            const handoffs = artifacts.filter(a => a.kind === "handoff");
+            if (handoffs.length !== 1)
+                return refuse("machine-prepared-handoff-unavailable");
+            const artifact = handoffs[0];
+            if (artifact.capture !== "machine-authored handoff (exit 0)" || artifact.truncated || artifact.redacted || artifact.captureStatus === "failed")
+                return refuse("machine-prepared-handoff-unavailable");
+            const saved = readVerifiedArtifact(evidenceRoot, artifact);
+            if (!saved.ok)
+                return refuse("machine-prepared-handoff-unavailable");
+            const handoff = JSON.parse(saved.content.toString("utf8"));
+            const conclusion = `Prepared candidate ${scope.candidate} was checked out by the machine; no agent ran. ${run.outcome === "no-change" ? "The branch already matched it." : "The sealed diff spans this task's base to that candidate."}`;
+            if (handoff.schema !== 1 || handoff.runId !== runId || handoff.taskId !== ref.externalId || handoff.sessionId !== null ||
+                handoff.provider !== run.provider || handoff.branch !== run.branch || handoff.worktree !== run.worktree ||
+                handoff.base !== run.baseRevision || handoff.head !== run.headRevision || handoff.outcome !== run.outcome ||
+                handoff.committed !== run.committed || handoff.freshness?.currentAsOf !== run.headRevision ||
+                handoff.conclusion !== conclusion || run.handoff !== conclusion ||
+                !instant(artifact.createdAt) || Date.parse(artifact.createdAt) < Date.parse(run.startedAt) ||
+                Date.parse(artifact.createdAt) > Date.parse(gateArtifact.createdAt))
+                return refuse("machine-prepared-handoff-mismatch");
+            const witnesses = [];
+            for (const id of owned) {
+                for (const row of store.handle.prepare("SELECT id, run, pid, host, process_group, observed_at, exited_at, boot_id, containment, container, container_identity, container_empty_at FROM run_process WHERE run = ? ORDER BY id").all(id)) {
+                    if (!positive(row.id) || row.run !== id || (row.pid !== null && !positive(row.pid)) || typeof row.host !== "string" ||
+                        (row.process_group !== 0 && row.process_group !== 1) || !instant(row.observed_at) ||
+                        Date.parse(row.observed_at) < Date.parse(run.startedAt) || Date.parse(row.observed_at) > Date.parse(run.finishedAt) ||
+                        (row.exited_at !== null && (!instant(row.exited_at) || Date.parse(row.exited_at) < Date.parse(row.observed_at) || Date.parse(row.exited_at) > now.getTime())) ||
+                        (row.boot_id !== null && (typeof row.boot_id !== "string" || normalizeBootId(row.boot_id) !== row.boot_id)))
+                        return refuse("malformed-process-witness");
+                    // This classifier is deliberately ordinary-process-only. Even a
+                    // apparently empty native object needs its separate containment road.
+                    if (row.containment !== null || row.container !== null || row.container_identity !== null || row.container_empty_at !== null)
+                        return refuse("native-containment-outside-scope");
+                    if (row.pid !== null && row.exited_at === null)
+                        return refuse("known-process-exit-unproven");
+                    if (row.pid === null && row.exited_at === null && (id !== runId || row.host !== host || row.boot_id !== bootId ||
+                        Date.parse(row.observed_at) > Date.parse(gateArtifact.createdAt)))
+                        return refuse("unknown-witness-not-bound-to-gate");
+                    witnesses.push(row);
+                }
+            }
+            const unknownWitnessIds = witnesses.filter(row => row.pid === null && row.exited_at === null).map(row => row.id);
+            if (!unknownWitnessIds.length)
+                return refuse("no-unresolved-null-pid-witness");
+            if (!witnesses.some(row => row.run === runId && row.pid !== null && row.exited_at !== null))
+                return refuse("known-gate-process-witness-missing");
+            const binding = { version: 1, kind: "prepared-candidate-observer-gap-eligibility",
+                host, bootId, run: { id: runId, taskRef: ref.id, taskId: ref.externalId, repo: ref.repo, leaseId: run.leaseId,
+                    role: run.role, outcome: run.outcome, committed: run.committed, startedAt: run.startedAt, finishedAt: run.finishedAt,
+                    branch: run.branch, worktree: run.worktree, base: run.baseRevision, head: run.headRevision },
+                scope: { candidate: scope.candidate, digest: scope.digest, approvedAt: scope.approvedAt, approvedBy: scope.approvedBy,
+                    approvalBasis: scope.approvalBasis ?? "password", modeDigest: scope.modeDigest ?? null },
+                command, machine, gateDigest: gate.digest, gate: artifactBinding(gateArtifact), log: artifactBinding(log),
+                handoff: artifactBinding(artifact), ownedRuns, unknownWitnessIds, witnesses };
+            return freeze({ ok: true, digest: hash(binding), binding,
+                requires: "separate-authenticated-spawn-provenance-and-complete-os-census" });
+        });
+    }
+    catch {
+        // No private paths, artifact bodies, command output or raw database errors.
+        return refuse("saved-eligibility-evidence-unreadable");
+    }
+}

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

@@ -0,0 +1,172 @@
+export type PreparedDarwinProcessCensus = {
+    sourcePath: string;
+    executablePath: string;
+    sourceSha256: string;
+    executableSha256: string;
+};
+export type DarwinProcessIdentity = {
+    pid: number;
+    ppid: number | null;
+    uid: number | null;
+    birthMs: number | null;
+    uniqueId: string | null;
+    parentUniqueId: string | null;
+    traced: boolean | null;
+    executable: string | null;
+    originalParentVersion: number | null;
+    pidVersion?: number;
+};
+export type DarwinManagedService = {
+    domain: string;
+    label: string;
+    pid: number;
+    uniqueId: string;
+    beforeUniqueId: string;
+    afterUniqueId: string;
+    identityBound: boolean;
+};
+export type DarwinPidDomain = {
+    pid: number;
+    domain: string;
+    readable: boolean;
+    identityBound: boolean;
+    uniqueId: string | null;
+    type: string | null;
+    handle: number | null;
+    originator: string | null;
+    creatorPid: number | null;
+};
+export type DarwinProcessRecoverySnapshot = {
+    schema: 1;
+    host: string;
+    bootId: string | null;
+    osRelease: string;
+    startedAt: string;
+    finishedAt: string;
+    elevation: "none" | "sudo-n";
+    complete: boolean;
+    stable: boolean;
+    processes: DarwinProcessIdentity[];
+    managedServices: DarwinManagedService[];
+    collectorPids: number[];
+    domainFailures: {
+        domain: string;
+        reason: string;
+    }[];
+    identityChanges: number[];
+    errors: string[];
+    nativeSourceSha256: string;
+    nativeExecutableSha256: string;
+    pidDomains: DarwinPidDomain[];
+};
+type NativeSnapshot = {
+    schema: 1;
+    bootId: string | null;
+    collectorPid: number;
+    complete: boolean;
+    processes: DarwinProcessIdentity[];
+    errors: string[];
+};
+/** Facts only. Public KERN_PROC_ALL supplies birth/UID/trace metadata without
+ * reading argv or environments. XNU's flavor 17 supplies 64-bit identities:
+ * https://github.com/apple-oss-distributions/xnu/blob/main/bsd/sys/proc_info_private.h
+ * p_puniqueid can change on orphan exec; original-parent version is diagnostic
+ * only (32-bit wrap is possible). No recovery authority lives in this helper. */
+export declare const DARWIN_PROCESS_CENSUS_SOURCE: string;
+/** Compilation is explicit, local, and separate from read-only collection. */
+export declare function prepareDarwinProcessCensus(directory: string): PreparedDarwinProcessCensus;
+/** Strict parser also strips every field not in the facts contract. */
+export declare function parseDarwinNativeSnapshot(text: string): NativeSnapshot;
+/** PID reuse, orphan exec, tracing, UID and birth changes all invalidate a seal. */
+export declare function changedDarwinProcessIdentities(before: DarwinProcessIdentity[], after: DarwinProcessIdentity[]): number[];
+/** Parse only the launchd domain's direct service table; never return raw print
+ * output, environment, arguments or nested service-like text. */
+export declare function parseDarwinLaunchdServices(output: string): {
+    pid: number;
+    label: string;
+}[];
+export declare function parseDarwinPidDomain(output: string): Pick<DarwinPidDomain, "type" | "handle" | "originator" | "creatorPid">;
+/** Does not write a recovery receipt, clear custody, signal task processes, or
+ * infer that an unreadable service/domain is safe. sudo-n is explicit and can
+ * only fail closed; this function never requests or reads a password. */
+export declare function collectDarwinProcessRecoverySnapshot(args: {
+    native: PreparedDarwinProcessCensus;
+    elevation?: "none" | "sudo-n";
+    boundary: string;
+    maxAttempts?: number;
+}): Promise<DarwinProcessRecoverySnapshot>;
+export type DarwinCoalitionCounters = {
+    tasksStarted: string;
+    tasksExited: string;
+};
+export type DarwinCoalitionProcessIdentity = DarwinProcessIdentity & {
+    resourceCoalitionId: string;
+};
+export type DarwinCoalitionNativeSnapshot = Omit<NativeSnapshot, "processes"> & {
+    resourceCoalitionId: string;
+    processes: DarwinCoalitionProcessIdentity[];
+    anchorPids: number[];
+    anchors: DarwinCoalitionProcessIdentity[];
+    counterBefore: DarwinCoalitionCounters | null;
+    counterAfter: DarwinCoalitionCounters | null;
+    kernelTableRead: boolean;
+    unreadableMembershipCount: number;
+};
+export type DarwinCoalitionRecoverySnapshot = {
+    schema: 1;
+    host: string;
+    bootId: string | null;
+    osRelease: string;
+    startedAt: string;
+    finishedAt: string;
+    resourceCoalitionId: string;
+    complete: boolean;
+    stable: boolean;
+    anchorPids: number[];
+    anchors: DarwinCoalitionProcessIdentity[];
+    anchorIdentityChanges: number[];
+    processes: DarwinCoalitionProcessIdentity[];
+    counterBefore: DarwinCoalitionCounters | null;
+    counterAfter: DarwinCoalitionCounters | null;
+    countersStable: boolean;
+    kernelTableRead: boolean;
+    unreadableMembershipCount: number;
+    identityChanges: number[];
+    errors: string[];
+    collector: {
+        pid: number;
+        uniqueId: string;
+        exited: true;
+    } | null;
+    nativeSourceSha256: string;
+    nativeExecutableSha256: string;
+};
+export declare const prepareDarwinCoalitionCensus: typeof prepareDarwinProcessCensus;
+/** Counts corroborate membership; they cannot classify unreadable processes.
+ * Every non-zombie table row must have a readable coalition or fresh ESRCH.
+ * Fork adopts a coalition before publishing the child PID, then makes it
+ * runnable. An in-construction child therefore also requires a live producer;
+ * separate historical provenance and absence of owned producers are mandatory.
+ * Exec shadows share a PID; changed task counters still invalidate the seal. */
+export declare function parseDarwinCoalitionNativeSnapshot(text: string): DarwinCoalitionNativeSnapshot;
+/** Validates the two seals without trusting a numeric PID intersection. Exported
+ * so the same malformed/racing native response receives deterministic checks. */
+export declare function compareDarwinCoalitionSnapshots(before: DarwinCoalitionNativeSnapshot, after: DarwinCoalitionNativeSnapshot): {
+    complete: boolean;
+    stable: boolean;
+    countersStable: boolean;
+    identityChanges: number[];
+    anchorIdentityChanges: number[];
+    errors: string[];
+};
+/** Facts-only same-coalition census; this does not establish that any historical
+ * run inherited this coalition or lacked privileged/delegated spawn authority.
+ * Unlike the full-host reader, no launchctl child is spawned between seals.
+ * Native task counters include fork AND exec, so transient exec copies refuse. */
+export declare function collectDarwinCoalitionSnapshot(args: {
+    native: PreparedDarwinProcessCensus;
+    resourceCoalitionId: string;
+    maxAttempts?: number;
+    anchorPids?: number[];
+}): Promise<DarwinCoalitionRecoverySnapshot>;
+export {};