toolroll 0.5.0

package/dist/principal.d.ts

@@ -0,0 +1,42 @@
+import type { Store } from "./store.js";
+declare const verifiedApproverBrand: unique symbol;
+export type VerifiedApprover = {
+    readonly [verifiedApproverBrand]: true;
+    readonly name: string;
+    /** The approver row's credential generation at mint; re-proved on every use. */
+    readonly generation: number;
+    /** The admitted repos, in the surface's own order — `r1..rN` maps by index. */
+    readonly repos: readonly string[];
+    readonly ceilingDigest: string;
+};
+/** The mate's ceiling digest: the admitted repos IN ORDER, hashed — `rN`
+ * is an index, so two surfaces naming the same repos in a different order
+ * hold different ceilings (slice-2 review, finding 3). */
+export declare function ceilingDigestOf(repos: readonly string[]): string;
+/** True only for an object this module minted — never for a structural copy. */
+export declare function isVerifiedApprover(value: unknown): value is VerifiedApprover;
+export type PrincipalRefusal = {
+    ok: false;
+    reason: "no-approvers" | "unknown" | "revoked" | "locked" | "not-an-approver" | "generation" | "forged";
+};
+/** The password road: the CLI, and any ceremony that retypes it. */
+export declare function verifyApproverByPassword(store: Store, name: string, token: string, repos: readonly string[]): {
+    ok: true;
+    who: VerifiedApprover;
+} | PrincipalRefusal;
+/**
+ * The session road: the edge has already proved the cookie, csrf, and the
+ * origin, and holds the generation the session was opened under. This
+ * re-proves the ROW — present, an approver, not revoked, SAME generation —
+ * so a name alone mints nothing, and a credential rotation since the
+ * session opened ends the principal.
+ */
+export declare function verifyApproverStanding(store: Store, name: string, generation: number, repos: readonly string[]): {
+    ok: true;
+    who: VerifiedApprover;
+} | PrincipalRefusal;
+/** Re-prove a principal minted earlier: minted here, intact, same row, same generation, still an approver. */
+export declare function reproveApprover(store: Store, who: VerifiedApprover): {
+    ok: true;
+} | PrincipalRefusal;
+export {};

package/dist/principal.js

@@ -0,0 +1,82 @@
+/**
+ * The branded approver principal (mate arc, ruling 3).
+ *
+ * Every act the mate proposes and every confirmation an operator taps
+ * runs under a principal that PROVES it was authenticated — a password
+ * ceremony, or a cookie session the edge already proved (csrf, role,
+ * generation) and this module re-proves against the approver row. The
+ * maker is module-private and the brand is RUNTIME (slice-1 review,
+ * finding 3): a principal is frozen at mint and remembered in a private
+ * set, so a structural look-alike, a mutated copy, or a repos list edited
+ * after the fact is refused by `isVerifiedApprover` and `reproveApprover`.
+ * The ceiling rides on it — the admitted repos and their digest — so a
+ * principal minted on one surface can never read or confirm on another's
+ * wider or narrower view.
+ */
+import { createHash } from "node:crypto";
+import { authenticateAccount } from "./scope.js";
+/** The mate's ceiling digest: the admitted repos IN ORDER, hashed — `rN`
+ * is an index, so two surfaces naming the same repos in a different order
+ * hold different ceilings (slice-2 review, finding 3). */
+export function ceilingDigestOf(repos) {
+    return createHash("sha256").update(repos.join("\n")).digest("hex");
+}
+/** Every principal this process minted. Membership IS the brand at runtime. */
+const minted = new WeakSet();
+function verified(row) {
+    const who = Object.freeze({
+        name: row.name,
+        generation: row.generation,
+        repos: Object.freeze([...row.repos]),
+        ceilingDigest: ceilingDigestOf(row.repos),
+    });
+    minted.add(who);
+    return who;
+}
+/** True only for an object this module minted — never for a structural copy. */
+export function isVerifiedApprover(value) {
+    return typeof value === "object" && value !== null && minted.has(value);
+}
+/** The password road: the CLI, and any ceremony that retypes it. */
+export function verifyApproverByPassword(store, name, token, repos) {
+    const account = authenticateAccount(store, name, token);
+    if (!account.ok)
+        return { ok: false, reason: account.reason };
+    if (account.role !== "approver")
+        return { ok: false, reason: "not-an-approver" };
+    return { ok: true, who: verified({ name, generation: account.generation, repos }) };
+}
+/**
+ * The session road: the edge has already proved the cookie, csrf, and the
+ * origin, and holds the generation the session was opened under. This
+ * re-proves the ROW — present, an approver, not revoked, SAME generation —
+ * so a name alone mints nothing, and a credential rotation since the
+ * session opened ends the principal.
+ */
+export function verifyApproverStanding(store, name, generation, repos) {
+    const account = store.accountOf(name);
+    if (account === null)
+        return { ok: false, reason: "unknown" };
+    if (account.revokedAt !== null)
+        return { ok: false, reason: "revoked" };
+    if (account.role !== "approver")
+        return { ok: false, reason: "not-an-approver" };
+    if (account.generation !== generation)
+        return { ok: false, reason: "generation" };
+    return { ok: true, who: verified({ name, generation: account.generation, repos }) };
+}
+/** Re-prove a principal minted earlier: minted here, intact, same row, same generation, still an approver. */
+export function reproveApprover(store, who) {
+    if (!isVerifiedApprover(who) || ceilingDigestOf(who.repos) !== who.ceilingDigest)
+        return { ok: false, reason: "forged" };
+    const account = store.accountOf(who.name);
+    if (account === null)
+        return { ok: false, reason: "unknown" };
+    if (account.revokedAt !== null)
+        return { ok: false, reason: "revoked" };
+    if (account.role !== "approver")
+        return { ok: false, reason: "not-an-approver" };
+    if (account.generation !== who.generation)
+        return { ok: false, reason: "generation" };
+    return { ok: true };
+}

package/dist/probe.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Asking an environment whether it has what the work needs.
+ *
+ * A probe is an operator-authored command line whose exit 0 means "present
+ * and alive": `gh auth status`, `test -n "$SUPABASE_KEY"`. It runs through
+ * a real shell, deliberately — the design's own examples need expansion and
+ * `test` — and that is safe only because of who wrote it: probes are stored
+ * by the operator, at `cap add`, with the author recorded. Nothing an agent
+ * or a scanned repository writes is ever executed as a probe; the scanner
+ * synthesizes probes from a fixed template over validated identifiers or
+ * stores none at all.
+ *
+ * The answer is a claim about one machine at one moment. `verified` carries
+ * when and by whom; anything else carries the probe's own words — "exit 1",
+ * "timed out", "sh not found" — because collapsing those to a bit discards
+ * exactly what tells an operator whether to paste a key or fix a PATH.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+import { type Capability, type Store } from "./store.js";
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/** Probes are cheap questions; one that hangs is already an answer. */
+export declare const PROBE_TIMEOUT_MS = 10000;
+export type ProbeOutcome = {
+    kind: Capability["kind"];
+    name: string;
+    status: "verified" | "failed" | "unprobed";
+    /** The probe's words when it did not say yes. */
+    detail?: string;
+};
+/**
+ * Whether a capability is verified *right now*: a stale yes is not a yes.
+ * Presence is not enough, and neither is a verification whose expiry passed.
+ */
+export declare function isVerified(capability: Capability, now: Date): boolean;
+/** Run one capability's probe and record what it said. */
+export declare function probeOne(store: Store, capability: Capability, by: string, now: Date, runner?: Runner, env?: Record<string, string>): Promise<ProbeOutcome>;
+/**
+ * Probe a repo's capabilities — all of them, or the named subset. Statuses
+ * land in the store as each probe answers; the returned outcomes are for
+ * reporting, not the source of truth.
+ */
+export declare function probeRepo(store: Store, repo: string, by: string, now: Date, options?: {
+    runner?: Runner;
+    only?: ReadonlySet<string>;
+    env?: Record<string, string>;
+}): Promise<ProbeOutcome[]>;

package/dist/probe.js

@@ -0,0 +1,79 @@
+/**
+ * Asking an environment whether it has what the work needs.
+ *
+ * A probe is an operator-authored command line whose exit 0 means "present
+ * and alive": `gh auth status`, `test -n "$SUPABASE_KEY"`. It runs through
+ * a real shell, deliberately — the design's own examples need expansion and
+ * `test` — and that is safe only because of who wrote it: probes are stored
+ * by the operator, at `cap add`, with the author recorded. Nothing an agent
+ * or a scanned repository writes is ever executed as a probe; the scanner
+ * synthesizes probes from a fixed template over validated identifiers or
+ * stores none at all.
+ *
+ * The answer is a claim about one machine at one moment. `verified` carries
+ * when and by whom; anything else carries the probe's own words — "exit 1",
+ * "timed out", "sh not found" — because collapsing those to a bit discards
+ * exactly what tells an operator whether to paste a key or fix a PATH.
+ */
+import { run, NOT_FOUND_CODE, OVERFLOW_CODE, TIMEOUT_CODE, } from "./exec.js";
+import {} from "./store.js";
+/** Probes are cheap questions; one that hangs is already an answer. */
+export const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Whether a capability is verified *right now*: a stale yes is not a yes.
+ * Presence is not enough, and neither is a verification whose expiry passed.
+ */
+export function isVerified(capability, now) {
+    if (capability.status !== "verified")
+        return false;
+    if (capability.expiresAt === null)
+        return true;
+    return capability.expiresAt > now.toISOString();
+}
+/** Run one capability's probe and record what it said. */
+export async function probeOne(store, capability, by, now, runner = run, env) {
+    const { kind, name } = capability;
+    if (capability.probe === null) {
+        // Nothing can vouch for it, and nobody may vouch by hand (§3: presence
+        // is not enough — an assertion is even less). It stays a visible gap.
+        return { kind, name, status: "unprobed", detail: "no probe — only a probe can verify" };
+    }
+    const asked = await runner("sh", ["-lc", capability.probe], {
+        cwd: capability.repo,
+        timeoutMs: PROBE_TIMEOUT_MS,
+        ...(env === undefined ? {} : { env }),
+    });
+    if (asked.code === 0) {
+        store.markCapability(capability.repo, kind, name, { status: "verified", by }, now);
+        return { kind, name, status: "verified" };
+    }
+    const detail = describe(asked);
+    store.markCapability(capability.repo, kind, name, { status: "failed", by, detail }, now);
+    return { kind, name, status: "failed", detail };
+}
+/**
+ * Probe a repo's capabilities — all of them, or the named subset. Statuses
+ * land in the store as each probe answers; the returned outcomes are for
+ * reporting, not the source of truth.
+ */
+export async function probeRepo(store, repo, by, now, options = {}) {
+    const outcomes = [];
+    for (const capability of store.listCapabilities(repo)) {
+        if (options.only !== undefined && !options.only.has(`${capability.kind}:${capability.name}`)) {
+            continue;
+        }
+        outcomes.push(await probeOne(store, capability, by, now, options.runner ?? run, options.env));
+    }
+    return outcomes;
+}
+function describe(result) {
+    if (result.timedOut || result.code === TIMEOUT_CODE) {
+        return `timed out after ${PROBE_TIMEOUT_MS / 1000}s`;
+    }
+    if (result.notFound || result.code === NOT_FOUND_CODE)
+        return "sh not found";
+    if (result.code === OVERFLOW_CODE)
+        return "output too large";
+    const stderr = result.stderr.split("\n")[0]?.trim() ?? "";
+    return stderr === "" ? `exit ${result.code}` : `exit ${result.code} — ${stderr}`;
+}

package/dist/process-custody.d.ts

@@ -0,0 +1,17 @@
+import type { ObservedProcess, ProcessObservationFailure } from "./process-tree.js";
+import type { Store } from "./store.js";
+import type { ExecResult, RunOptions } from "./exec.js";
+/** Existing append-only ledger; a diagnostic is not exit evidence. */
+export declare function recordProcessObservationFailure(store: Store, runId: number, now: Date, failure: ProcessObservationFailure): void;
+/** Preserve observed IDs through the existing serialized write boundary. This
+ * writes process facts only; it does not declare exit or replay observers. */
+export declare function preserveObservedProcesses(store: Store, runId: number, now: Date, rows: readonly ObservedProcess[]): boolean;
+type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+/** Reserve each spawn before the OS call. A crash before its PID is recorded
+ * leaves an explicit unknown, even if earlier setup/check processes exited.
+ * Only the returning transport can certify that its reserved spawn made no child.
+ * Retained PIDs are read-only witnesses, never authority to signal a process.
+ * A native OS object (v53) rides the same witness: named at the spawn, and
+ * marked empty only when the OS proved it so — never on a transport exit. */
+export declare function witnessedRunner(store: Store, runId: number, clock: () => Date, runner: Runner): Runner;
+export {};

package/dist/process-custody.js

@@ -0,0 +1,91 @@
+/** Existing append-only ledger; a diagnostic is not exit evidence. */
+export function recordProcessObservationFailure(store, runId, now, failure) {
+    const run = store.getRun(runId);
+    const ref = run === null ? null : store.refById(run.taskRef);
+    store.recordAction({ at: now.toISOString(), actor: run?.runner ?? "system", repo: ref?.repo ?? null,
+        taskId: ref?.externalId ?? null, runId, action: "process observation failed", source: "work",
+        outcome: JSON.stringify(failure) });
+}
+/** Preserve observed IDs through the existing serialized write boundary. This
+ * writes process facts only; it does not declare exit or replay observers. */
+export function preserveObservedProcesses(store, runId, now, rows) {
+    const first = rows[0];
+    if (!first)
+        return false;
+    // Reserve BEFORE waiting for the batch transaction. A crash/rollback leaves
+    // this new guard intact; no old unknown witness is reused or cleared.
+    const witness = store.reserveRunProcess(runId, now, first.group);
+    store.transact(() => {
+        store.recordRunProcess(runId, first.pid, now, first.group, witness);
+        for (const row of rows.slice(1))
+            store.recordRunProcess(runId, row.pid, now, row.group);
+    });
+    return true;
+}
+/** Reserve each spawn before the OS call. A crash before its PID is recorded
+ * leaves an explicit unknown, even if earlier setup/check processes exited.
+ * Only the returning transport can certify that its reserved spawn made no child.
+ * Retained PIDs are read-only witnesses, never authority to signal a process.
+ * A native OS object (v53) rides the same witness: named at the spawn, and
+ * marked empty only when the OS proved it so — never on a transport exit. */
+export function witnessedRunner(store, runId, clock, runner) {
+    return async (file, args, options = {}) => {
+        const witnesses = [];
+        let unknown = false;
+        let native = false;
+        const result = await runner(file, args, {
+            ...options,
+            onDescendant: (pid, group) => {
+                store.recordRunProcess(runId, pid, clock(), group);
+                options.onDescendant?.(pid, group);
+            },
+            // External custody callbacks retain the conservative failure path;
+            // replaying them could repeat non-idempotent side effects.
+            onDescendantWriteFailure: rows => options.onDescendant === undefined
+                && preserveObservedProcesses(store, runId, clock(), rows),
+            onDescendantExit: (pid, group) => {
+                store.recordRunProcessExits(runId, clock(), { pid, group });
+                options.onDescendantExit?.(pid, group);
+            },
+            onObservationFailure: failure => {
+                recordProcessObservationFailure(store, runId, clock(), failure);
+                options.onObservationFailure?.(failure);
+            },
+            onUnknown: () => {
+                if (!native && !unknown) {
+                    store.reserveRunProcess(runId, clock(), true);
+                    unknown = true;
+                }
+                options.onUnknown?.();
+            },
+            beforeSpawn: () => {
+                if (options.beforeSpawn?.() === false)
+                    return false;
+                native = false;
+                witnesses.push(store.reserveRunProcess(runId, clock(), options.processGroup === true));
+                return true;
+            },
+            onSpawn: pid => {
+                store.recordRunProcess(runId, pid, clock(), options.processGroup === true, witnesses.at(-1));
+                options.onSpawn?.(pid);
+            },
+            onContainer: info => {
+                native = true;
+                const witness = witnesses.at(-1);
+                if (witness !== undefined)
+                    store.recordRunContainer(witness, info.backend, info.id, info.identity);
+                options.onContainer?.(info);
+            },
+            onContainerEmpty: () => {
+                const witness = witnesses.at(-1);
+                if (witness !== undefined)
+                    store.markRunContainerEmpty(witness, clock());
+                options.onContainerEmpty?.();
+            },
+        });
+        for (const witness of witnesses)
+            store.finishUnspawnedProcess(witness, clock());
+        store.recordRunProcessExits(runId, clock());
+        return result;
+    };
+}

package/dist/process-liveness.d.ts

@@ -0,0 +1,10 @@
+type HistoricalWitness = {
+    observedAt: unknown;
+    finishedAt: unknown;
+};
+/** Read-only checks of retained process witnesses. Saved PIDs authorize no
+ * signal. ESRCH or proven macOS PID reuse establishes absence; everything
+ * unknown stays occupied. This concerns the historical identity, not whether
+ * the numeric PID/PGID is currently populated by unrelated processes. */
+export declare function processMayBeAlive(pid: number, group: boolean, witness?: HistoricalWitness): boolean;
+export {};

package/dist/process-liveness.js

@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+/** Only the exact UTC millisecond format stored by the writer is evidence. */
+function timestamp(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value))
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) && new Date(ms).toISOString() === value ? ms : null;
+}
+function newerMacProcess(pid, witness) {
+    if (process.platform !== "darwin" || witness === undefined)
+        return false;
+    const observed = timestamp(witness.observedAt), finished = timestamp(witness.finishedAt);
+    if (observed === null || finished === null)
+        return false;
+    try {
+        // lstart has whole-second precision. Fix locale AND timezone; never let
+        // Date.parse guess either, or normalize an invalid calendar date.
+        const raw = execFileSync("/bin/ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+            stdio: ["ignore", "pipe", "ignore"], maxBuffer: 1024,
+            // Bound only this owned diagnostic child, never an agent or task.
+            // A stalled/oversized lookup throws and leaves the witness occupied.
+            timeout: 1_000, killSignal: "SIGKILL",
+        }).trim().replace(/ +/g, " ");
+        const match = /^(Sun|Mon|Tue|Wed|Thu|Fri|Sat) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{1,2}) (\d{2}:\d{2}:\d{2}) (\d{4})$/.exec(raw);
+        if (match === null)
+            return false;
+        const utc = `${match[1]}, ${match[3].padStart(2, "0")} ${match[2]} ${match[5]} ${match[4]} GMT`;
+        const start = Date.parse(utc);
+        if (!Number.isFinite(start) || new Date(start).toUTCString() !== utc || start > Date.now())
+            return false;
+        // The displayed second is a lower bound, not a rounded millisecond
+        // identity. Same-second observations are ambiguous. Reservations can
+        // precede spawn, so also require birth AFTER the owning run ended.
+        return start > Math.max(observed, finished);
+    }
+    catch {
+        return false;
+    }
+}
+/** Read-only checks of retained process witnesses. Saved PIDs authorize no
+ * signal. ESRCH or proven macOS PID reuse establishes absence; everything
+ * unknown stays occupied. This concerns the historical identity, not whether
+ * the numeric PID/PGID is currently populated by unrelated processes. */
+export function processMayBeAlive(pid, group, witness) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return true;
+    if (group && process.platform !== "win32") {
+        let absent = false;
+        try {
+            process.kill(-pid, 0);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ESRCH")
+                absent = true;
+            else if (code !== "EPERM")
+                return true;
+        }
+        // Darwin's forkproc excludes existing PIDs, PGIDs and session IDs under
+        // proc_list_lock. A proven newer PID EQUAL to the saved PGID therefore
+        // implies the old group ended before allocation, even if a new group now
+        // uses that number. A new member or an absent leader proves nothing.
+        // See docs/assessments/UPDATE_PID_REUSE_2026-09-15.md, recovery attempt 2.
+        if (!absent)
+            return !newerMacProcess(pid, witness);
+    }
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        if (code !== "EPERM")
+            return true;
+        // Signal permission and readable birth identity are independent. EPERM
+        // alone proves nothing; a failed/ambiguous ps read still stays occupied.
+    }
+    return !newerMacProcess(pid, witness);
+}

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

@@ -0,0 +1,75 @@
+import type { SQLInputValue } from "node:sqlite";
+import type { DarwinCoalitionProcessIdentity, PreparedDarwinProcessCensus } 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 declare const SERVICE_ANCHOR_RUNTIME_V1_SHA256 = "9641efcb3b46717a7f122aa025e3945a08fa55ca046605276825a9d69eefd01d";
+export type DarwinServiceAnchorInput = {
+    databasePath: string;
+    targetRun: number;
+    anchorReviewerRun: number;
+    runtime: string;
+    runtimeSha256: string;
+    runner: string;
+    repo: string;
+    host: string;
+    bootId: string;
+    resourceCoalitionId: string;
+    service: string;
+    supervisorPid: number;
+    workerPid: number;
+    port: number;
+    /** Full expected arrays; compared privately, never included in a receipt. */
+    supervisorArgv: string[];
+    workerArgv: string[];
+    /** Recovery must prepare this helper itself from the known embedded source;
+     * never accept an executable or this result receipt from a client request. */
+    native: PreparedDarwinProcessCensus;
+    maxWaitMs?: number;
+};
+export type DarwinServiceAnchorReceipt = {
+    schema: 1;
+    kind: "authenticated-watch-continuity";
+    targetRun: number;
+    anchorReviewerRun: number;
+    host: string;
+    bootId: string;
+    observedAt: string;
+    runtimeSha256: string;
+    databasePath: string;
+    runner: string;
+    repo: string;
+    owner: string;
+    generation: number;
+    episode: number;
+    registeredAt: string;
+    heartbeatBefore: string;
+    heartbeatAfter: string;
+    service: string;
+    listener: string;
+    worker: DarwinCoalitionProcessIdentity;
+    supervisor: DarwinCoalitionProcessIdentity;
+    nativeSourceSha256: string;
+    nativeExecutableSha256: string;
+};
+export type DarwinServiceAnchorResult = {
+    ok: true;
+    receipt: DarwinServiceAnchorReceipt;
+} | {
+    ok: false;
+    reason: string;
+};
+export type RecoveryReadDatabase = {
+    prepare(sql: string): {
+        get(...parameters: SQLInputValue[]): Record<string, unknown> | undefined;
+        all(...parameters: SQLInputValue[]): Record<string, unknown>[];
+    };
+};
+/** 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 declare function collectDarwinServiceAnchor(db: RecoveryReadDatabase, input: DarwinServiceAnchorInput): Promise<DarwinServiceAnchorResult>;