ai-foreman 1.7.19 → 1.7.20

package/README.md

@@ -166,17 +166,19 @@ Build stall recovery uses current context occupancy, not lifetime token usage. T
 
 Unchanged, source-bound plan and ticket approvals are reused. Material ticket, plan, delivery, or workflow changes require a new decision, including with `--yes`. Legacy approval evidence that cannot prove unchanged scope requires review. `--steps` counts completed tickets or steps; it is neither a wall-clock limit nor a model-turn budget.
 
-Questions are persisted before prompting. Redirected or detached runs return a recoverable needs-input outcome (exit 2). Use `rafi build:attach . --run <id>` to see decisions, `rafi build:decide . --run <id> --decision <id> --choice <id>` to answer, and `rafi build:resume . --run <id>` to continue. Custom answers additionally use `--choice custom --answer "text"`. Independent eligible tickets continue around a ticket blocker; dependent and unsafe shared-delivery work stays deferred. Answered ticket questions are reconsidered at safe boundaries.
+Questions are persisted before prompting. Redirected or detached runs return a recoverable needs-input outcome (exit 2). Use `rafi build:attach . --run <id>` to see decisions, `rafi build:decide . --run <id> --decision <id> --choice <id>` to answer, and `rafi resume` to select a build and continue. Custom answers additionally use `--choice custom --answer "text"`. Independent eligible tickets continue around a ticket blocker; dependent and unsafe shared-delivery work stays deferred. Answered ticket questions are reconsidered at safe boundaries.
 
 CLI starts run under a durable parent supervisor by default. `--detach` writes output under `.rafi/logs/supervisor-<run>.log`; `--no-supervisor` retains direct execution. A preparation-only worker crash may restart within frozen budgets after proving the worker and registered readiness children are stopped. A worker crash with unresolved provider work pauses for reconciliation: it does not silently repeat a possibly completed action. `build:stop` signals only a verified supervisor process incarnation.
 
-Runtime deadlines can be overridden in `autonomy.runtime_deadlines` using positive integer milliseconds: `preparation_ms` (120000), `rpc_ms` (60000), `compaction_ms` (120000), `shutdown_ms` (10000), and `turn_ms` (3600000). They are frozen with the run policy. Transport-idle and hard active-turn deadlines have distinct meanings; neither grants permission to repeat uncertain side effects. Attached-process elapsed time includes waiting and is not provider compute time. Activity warns after five minutes without a completed tool or agent turn; intentional human waits are excluded, and the warning alone does not cancel work. Final paused output lists the durable question and exact run-scoped recovery commands.
+Runtime deadlines can be overridden in `autonomy.runtime_deadlines` using positive integer milliseconds: `preparation_ms` (120000), `rpc_ms` (60000), `compaction_ms` (120000), `shutdown_ms` (10000), and `turn_ms` (3600000). They are frozen with the run policy. Transport-idle and hard active-turn deadlines have distinct meanings; neither grants permission to repeat uncertain side effects. Attached-process elapsed time includes waiting and is not provider compute time. Activity warns after five minutes without a completed tool or agent turn; intentional human waits are excluded, and the warning alone does not cancel work. Final paused output lists the durable question, its answer command, and the short `rafi resume` recovery command.
 
 The current terminal status includes the role/provider, activity, truthful context state, successful compaction count, and handoff generation. At the Builder threshold, Foreman settles the in-flight action, verifies native compaction plus a fresh provider usage sample, and resumes the frozen action. The configured maximum defaults to ten successful compactions per location-scoped provider session; the next crossing uses a validated fresh handoff instead of exceeding it. Disposable QA snapshots never reuse a prior QA conversation in a new `/tmp/rafi-qa-*` worktree; they transfer cumulative state through an accepted handoff.
 
 Failed QA reviews use the versioned `RAFI_QA_FAILURE_REPORT_START` / `RAFI_QA_FAILURE_REPORT_END` JSON contract. Foreman validates the report before Builder remediation, namespaces finding IDs by run, ticket, and review, and durably indexes the exact report, remediation response, and bounded fix summary by digest. A malformed failing report receives two correction-only turns in its original session, then a validated fresh successor performs one complete source-bound review followed by up to two correction-only turns. Any later operator-requested fresh successor performs one complete source-bound review followed by five usable correction-only turns.
 
-Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review to a full frozen source digest: commit, porcelain status, staged and unstaged bytes, and untracked content. Every fresh attempt captures and compares that complete state. Drift appends the new state and forces a complete review; correction-only reconstruction is never applied to changed source. Packet revisions and the authoritative WorkflowDb recovery head advance together. A successor must have a location-scoped identity, accept a handoff containing the complete resource inventory (purpose, byte count, digest, and recovery requirement), and acknowledge the copied packet before reporting. Paused recovery resumes with `rafi build:resume <project> --run <run-id> --ticket <ticket-id> --fresh-with-handoff`.
+A completed QA turn with missing/invalid continuity metadata or a malformed response can trigger one automatic complete fresh review per ticket. That allowance is durable across restarts and shared across protocol failures. The old session and snapshot close before the new review starts. Exhausted same-session report correction and malformed resumed report/acknowledgement responses use this route, rather than requiring an immediate manual resume. Earlier invalid responses cannot authorize Builder work or a QA pass. Provider execution failures, uncertain dispatch, invalid acceptance receipts, and modified recovery evidence still pause. Repeated failures exhaust the allowance and preserve recoverable state; independent eligible tickets can continue.
+
+Owner-only recovery packets under `.foreman/qa-report-recovery/` bind the review to a full frozen source digest: commit, porcelain status, staged and unstaged bytes, and untracked content. Every fresh attempt captures and compares that complete state. Drift appends the new state and forces a complete review; correction-only reconstruction is never applied to changed source. Packet revisions and the authoritative WorkflowDb recovery head advance together. A successor must have a location-scoped identity, accept a handoff containing the complete resource inventory (purpose, byte count, digest, and recovery requirement), and acknowledge the copied packet before reporting. Paused recovery is available through `rafi resume` or `rafi build:resume` in the project directory. The picker resolves the ticket, current QA revision, and validated QA handoff internally; explicit recovery flags still reject stale revisions.
 
 ### `ai-foreman manager`
 
@@ -681,3 +683,15 @@ Package output:
 - **`special-agents`** — library (rules + skills + agents + composition)
 - **`ai-foreman`** — this runtime
 - **`@rafi-ai/cli`** — CLI for `rafi create` and `rafi compile`
+
+### Recovery ownership upgrades
+
+Stop existing workers before upgrading. The recovery database now records preparation admission, single-use launches, retry lineage, owned readiness processes and monotonic lease generations. Older binaries must not write an upgraded database; preserve these records when troubleshooting rather than deleting locks. Unknown process identity, incomplete child-launch evidence or an unresolved provider dispatch requires reconciliation. A stale heartbeat alone does not authorize another worker. Read-only resume inspection supports older storage without migrating it.
+
+Ownership schema version 2 adds bounded child registration/acknowledgement, explicit child-workflow ownership, and separate readiness/cleanup outcomes. Build readiness requires the original admission and owning project even when the command executes in an external worktree. Both the current build and competing starts wait for verified probe cleanup. Runtime snapshot, dispatch, continuity and session writes retain original authority; releasing a lease does not make those records writable by an arbitrary caller. Completed, cancelled and superseded builds cannot be reactivated by saving a snapshot.
+
+Ownership schema version 3 gates provider readiness behind registered helper authorization and records cleanup separately. Cleanup is reachable through both short resume commands even when its owning build is terminal or has no valid build snapshot. Restricted cleanup connections can update only their selected readiness records. Migration waits for local legacy execution to become safely quiescent; persistent compatibility guards then reject already-open older writers as well as new older opens. Uncertain remote provider records survive the upgrade unchanged so their owning recovery flow remains reachable. Ordinary starts remain blocked until those operations are reconciled. A lost acknowledgement cannot revoke an already-authorized helper.
+
+Standalone readiness also rejects unverified cleanup. The current process retains its cleanup evidence and checks it before another probe starts; restoring process visibility permits a retry. Standalone commands do not create a build recovery database, so this evidence does not survive process exit.
+
+On macOS/Linux, readiness cleanup checks the dedicated process group and inherited probe tags, including tagged descendants that escape the group. This is not a sandbox for descendants that deliberately remove their tag and detach. Unavailable inventory and ambiguous legacy evidence remain unresolved. The Windows readiness implementation targets Windows 10 / Server 2016 APIs, but those minimum versions have not been verified. Native Windows verification remains a release gate. Readiness providers start inside a non-breakaway Job Object with kill-on-close behavior, using built-in Windows PowerShell and `Add-Type`. Standard npm `.cmd`/`.bat` provider shims resolve to direct Node arguments; arbitrary shell shims are rejected. The Windows Job Object applies to readiness probes; it does not add containment for arbitrary Builder commands. Native regression tests are in `.github/workflows/build-recovery.yml`; the implementation plan records actual platform verification.

package/dist/branch/runner.js

@@ -1,3 +1,4 @@
+import { formatRecoveryCommand } from "../recoveryGuidance.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { buildScopeRevision } from "../buildApproval.js";
 import { beginQaFinalization, completeQaFinalization, verifyPendingQaFinalizationSource, compactWithRetry, runIsolatedQa } from "../qaReview.js";
@@ -818,7 +819,7 @@ function invalidateUnpublishedMergeDrift(projectDir, runId, ticketId, operationI
         // and source edits, but retire its dispatch slot before scheduling new QA.
         db.updateOperation(operationId, "failed", { error: error.message });
         const paused = db.invalidateQaFinalization(runId, ticketId, head.revision, error.message, intent.branch);
-        return new Error(`${error.message}. A complete QA recheck is required. Resume with: rafi build:resume ${projectDir} --run ${runId} --ticket ${ticketId} --qa-revision ${paused.revision} --fresh-with-handoff`);
+        return new Error(`${error.message}. A complete QA recheck is required. Resume with: ${formatRecoveryCommand(projectDir)}`);
     }
     catch {
         return error;

package/dist/buildAdmission.d.ts

@@ -0,0 +1,61 @@
+import type { ProjectLease } from "./workflowDb.js";
+import Database from "better-sqlite3";
+export declare class BuildOwnershipError extends Error {
+    readonly code: "stale-owner" | "unknown-owner" | "active-owner" | "invalid-launch";
+    constructor(code: "stale-owner" | "unknown-owner" | "active-owner" | "invalid-launch", message: string);
+}
+export interface BuildAdmission {
+    token: string;
+    runId: string;
+    project: string;
+    pid: number;
+    host: string;
+    processStart: string;
+    phase: "coordinator" | "worker";
+    heartbeatAt: string;
+}
+export interface BuildLaunch {
+    token: string;
+    runId: string;
+    project: string;
+    launcher: string;
+    role: BuildAdmission["phase"];
+    digest: string;
+    state: "reserved" | "dispatching" | "claimed" | "failed";
+    claimant?: BuildAdmission;
+    createdAt: string;
+    protocol?: "registered-v2";
+    child?: {
+        pid: number;
+        processStart: string;
+        host: string;
+    };
+    acknowledged?: boolean;
+}
+export declare function canonicalProject(project: string): string;
+export declare function originalBuildLease(project: string): ProjectLease | undefined;
+export declare function rememberOriginalLease(project: string, lease: ProjectLease): void;
+export declare function forgetOriginalLease(project: string, lease: ProjectLease): void;
+export declare function withBuildInvocation<T>(work: () => T): T;
+export declare function localBuildAuthority(project: string): BuildAdmission | undefined;
+export declare function rememberBuildAuthority(authority: BuildAdmission): void;
+export declare function forgetBuildAuthority(authority: BuildAdmission): void;
+export declare function launchDigest(args: readonly string[]): string;
+export declare function checkBuildOwnershipSchema(db: Database.Database): void;
+export declare function maintainBuildAdmission(authority: BuildAdmission): void;
+export declare function stopBuildAdmissionHeartbeat(authority: BuildAdmission): void;
+/** Additive, transactional storage. Readers never invoke this migration. */
+export declare function migrateBuildAdmission(db: Database.Database): void;
+export declare function readAdmission(db: Database.Database): BuildAdmission | undefined;
+export declare function assertAdmission(db: Database.Database, authority: BuildAdmission): void;
+export declare function acquireAdmission(db: Database.Database, project: string, runId: string, phase: BuildAdmission["phase"]): BuildAdmission;
+export declare function releaseAdmission(db: Database.Database, authority: BuildAdmission): void;
+export declare function reserveLaunch(db: Database.Database, authority: BuildAdmission, role: BuildAdmission["phase"], digest: string, protocol?: BuildLaunch["protocol"]): BuildLaunch;
+export declare function readLaunch(db: Database.Database, token: string): BuildLaunch | undefined;
+export declare function setLaunchState(db: Database.Database, authority: BuildAdmission, token: string, state: "dispatching" | "failed"): void;
+export declare function claimLaunch(db: Database.Database, project: string, runId: string, token: string, role: BuildAdmission["phase"], digest: string): BuildAdmission;
+/** Child registration grants no mutation/provider authority. Competes atomically with retirement. */
+export declare function registerLaunchChild(db: Database.Database, token: string, project: string): void;
+export declare function acknowledgeLaunchChild(db: Database.Database, authority: BuildAdmission, token: string, pid: number): void;
+/** Restricted retirement only; does not grant execution authority or replay work. */
+export declare function reconcileLaunch(db: Database.Database, token: string, original?: BuildAdmission): "retired" | "claimed" | "unknown";

package/dist/buildAdmission.js

@@ -0,0 +1,284 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import Database from "better-sqlite3";
+import { classifyProcess, processStartIdentity } from "./processIdentity.js";
+export class BuildOwnershipError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "BuildOwnershipError";
+    }
+}
+export function canonicalProject(project) { return realpathSync(resolve(project)); }
+const localAuthorities = new Map();
+const invocation = new AsyncLocalStorage();
+const localLeases = new Map();
+export function originalBuildLease(project) { return (invocation.getStore()?.leases ?? (invocation.getStore() ? new Map() : localLeases)).get(canonicalProject(project)); }
+export function rememberOriginalLease(project, lease) { const scope = invocation.getStore(); const leases = scope ? (scope.leases ??= new Map()) : localLeases; leases.set(canonicalProject(project), lease); }
+export function forgetOriginalLease(project, lease) { const leases = invocation.getStore()?.leases ?? localLeases; if (leases.get(canonicalProject(project))?.owner === lease.owner)
+    leases.delete(canonicalProject(project)); }
+export function withBuildInvocation(work) { return invocation.run({}, work); }
+export function localBuildAuthority(project) { const scope = invocation.getStore(); const authority = scope ? scope.authority : localAuthorities.get(canonicalProject(project)); return authority?.project === canonicalProject(project) ? authority : undefined; }
+export function rememberBuildAuthority(authority) { const scope = invocation.getStore(); if (scope)
+    scope.authority = authority;
+else
+    localAuthorities.set(authority.project, authority); }
+export function forgetBuildAuthority(authority) { const scope = invocation.getStore(); if (scope?.authority?.token === authority.token)
+    delete scope.authority; if (!scope && localAuthorities.get(authority.project)?.token === authority.token)
+    localAuthorities.delete(authority.project); }
+export function launchDigest(args) {
+    const options = [];
+    for (let i = 2; i < args.length; i++) {
+        const option = [args[i]];
+        if (args[i + 1] !== undefined && !args[i + 1].startsWith("--"))
+            option.push(args[++i]);
+        options.push(option);
+    }
+    options.sort((a, b) => a[0].localeCompare(b[0]));
+    return createHash("sha256").update(JSON.stringify([args[0], args[1], options])).digest("hex");
+}
+export function checkBuildOwnershipSchema(db) {
+    const exists = db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='build_ownership_schema'").get();
+    if (!exists)
+        return;
+    const row = db.prepare("SELECT version FROM build_ownership_schema WHERE singleton=1").get();
+    if (!row || ![1, 2, 3].includes(row.version))
+        throw new Error(`Unsupported build ownership schema ${row?.version ?? "missing"}; upgrade Rafi before accessing it`);
+}
+const ownershipHeartbeats = new Map();
+export function maintainBuildAdmission(authority) {
+    const timer = setInterval(() => {
+        let db;
+        try {
+            db = new Database(join(authority.project, ".rafi/recovery.sqlite3"), { fileMustExist: true });
+            db.function("rafi_protocol_v3", () => 1);
+            const changed = db.prepare("UPDATE build_admission SET record_json=json_set(record_json,'$.heartbeatAt',?) WHERE singleton=1 AND json_extract(record_json,'$.token')=?").run(new Date().toISOString(), authority.token);
+            if (changed.changes !== 1)
+                stopBuildAdmissionHeartbeat(authority);
+        }
+        catch {
+            stopBuildAdmissionHeartbeat(authority);
+        }
+        finally {
+            db?.close();
+        }
+    }, 5000);
+    timer.unref();
+    ownershipHeartbeats.set(authority.token, timer);
+}
+export function stopBuildAdmissionHeartbeat(authority) {
+    const timer = ownershipHeartbeats.get(authority.token);
+    if (timer)
+        clearInterval(timer);
+    ownershipHeartbeats.delete(authority.token);
+}
+/** Additive, transactional storage. Readers never invoke this migration. */
+export function migrateBuildAdmission(db) {
+    db.transaction(() => {
+        db.exec(`CREATE TABLE IF NOT EXISTS build_ownership_schema(singleton INTEGER PRIMARY KEY CHECK(singleton=1),version INTEGER NOT NULL);
+      INSERT OR IGNORE INTO build_ownership_schema VALUES(1,1);`);
+        const version = db.prepare("SELECT version FROM build_ownership_schema WHERE singleton=1").get().version;
+        if (![1, 2, 3].includes(version))
+            throw new Error(`Unsupported build ownership schema ${version}; upgrade Rafi before writing`);
+        if (version >= 2) {
+            migrateReadinessProtocol(db);
+            return;
+        }
+        db.exec(`CREATE TABLE IF NOT EXISTS workflow_lease_sequence(singleton INTEGER PRIMARY KEY CHECK(singleton=1),generation INTEGER NOT NULL);
+      INSERT OR IGNORE INTO workflow_lease_sequence VALUES(1,0);
+      CREATE TABLE IF NOT EXISTS build_runtime_runs(run_id TEXT PRIMARY KEY);
+      CREATE TABLE IF NOT EXISTS build_child_runs(child TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),parent TEXT NOT NULL REFERENCES workflow_runs(run_id),CHECK(child<>parent));
+      CREATE TABLE IF NOT EXISTS build_admission(singleton INTEGER PRIMARY KEY CHECK(singleton=1),record_json TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS build_retry_lineage(predecessor TEXT PRIMARY KEY REFERENCES workflow_runs(run_id),successor TEXT NOT NULL UNIQUE REFERENCES workflow_runs(run_id),project TEXT NOT NULL,created_at TEXT NOT NULL,CHECK(predecessor<>successor));
+      CREATE TABLE IF NOT EXISTS build_owned_processes(id TEXT PRIMARY KEY,run_id TEXT NOT NULL,owner TEXT NOT NULL,pid INTEGER,process_start TEXT,host TEXT NOT NULL,state TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS build_launches(token TEXT PRIMARY KEY,run_id TEXT NOT NULL REFERENCES workflow_runs(run_id),state TEXT NOT NULL,record_json TEXT NOT NULL);
+      CREATE UNIQUE INDEX IF NOT EXISTS build_launch_exclusive ON build_launches(run_id) WHERE state IN ('reserved','dispatching');`);
+        if (!db.prepare("PRAGMA table_info(build_owned_processes)").all().some(column => column.name === "outcome_json"))
+            db.exec("ALTER TABLE build_owned_processes ADD COLUMN outcome_json TEXT");
+        db.exec(`CREATE TRIGGER IF NOT EXISTS build_lineage_project BEFORE INSERT ON build_retry_lineage
+      WHEN NEW.project<>COALESCE((SELECT json_extract(record_json,'$.project') FROM build_admission WHERE singleton=1),'')
+      BEGIN SELECT RAISE(ABORT,'Retry lineage project does not match admission'); END;
+      CREATE TRIGGER IF NOT EXISTS build_lineage_cycle BEFORE INSERT ON build_retry_lineage
+      WHEN EXISTS(WITH RECURSIVE chain(id) AS (SELECT NEW.successor UNION SELECT successor FROM build_retry_lineage JOIN chain ON predecessor=chain.id) SELECT 1 FROM chain WHERE id=NEW.predecessor)
+      BEGIN SELECT RAISE(ABORT,'Retry lineage cycle is invalid'); END;
+      CREATE TRIGGER IF NOT EXISTS build_lineage_immutable BEFORE UPDATE ON build_retry_lineage
+      BEGIN SELECT RAISE(ABORT,'Retry lineage is immutable'); END;`);
+        db.prepare("UPDATE build_ownership_schema SET version=2 WHERE singleton=1").run();
+        db.exec("INSERT OR IGNORE INTO build_runtime_runs SELECT run_id FROM workflow_runs WHERE kind='build' AND json_extract(state_json,'$.version') IS NOT NULL");
+        const qaTables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all()
+            .map(row => row.name).filter(name => /^qa_[a-z_]+$/.test(name) && db.prepare(`PRAGMA table_info(${name})`).all().some(column => column.name === "run_id"));
+        for (const table of [...new Set(["operation_journal", "provider_sessions", "role_mutation_leases", "continuity_heads", "continuity_checkpoints", "continuity_events", "handoffs", "compaction_attempts", "recovery_decisions", "recovery_attempts", "role_settings", "publication_transactions", "branch_resume_sessions", ...qaTables])]) {
+            for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                const target = action === "DELETE" ? "OLD" : "NEW";
+                db.exec(`DROP TRIGGER IF EXISTS build_fence_${table}_${action.toLowerCase()};
+          CREATE TRIGGER build_fence_${table}_${action.toLowerCase()} BEFORE ${action} ON ${table}
+          WHEN (EXISTS(SELECT 1 FROM build_admission) OR rafi_build_writer_run()<>'' OR EXISTS(SELECT 1 FROM build_runtime_runs WHERE run_id=${target}.run_id))
+          AND NOT EXISTS(SELECT 1 FROM build_admission WHERE json_extract(record_json,'$.token')=rafi_build_writer_token() AND (json_extract(record_json,'$.runId')=${target}.run_id OR EXISTS(SELECT 1 FROM build_child_runs c WHERE c.child=${target}.run_id AND c.parent=json_extract(record_json,'$.runId')) OR EXISTS(SELECT 1 FROM workflow_runs r WHERE r.run_id=${target}.run_id AND r.status='superseded' AND json_extract(r.state_json,'$.supersededBy')=json_extract(record_json,'$.runId'))))
+          AND NOT (NOT EXISTS(SELECT 1 FROM build_admission) AND EXISTS(SELECT 1 FROM project_lease WHERE owner=rafi_build_lease_owner() AND generation=rafi_build_lease_generation() AND (run_id=${target}.run_id OR EXISTS(SELECT 1 FROM workflow_runs r WHERE r.run_id=project_lease.run_id AND r.kind='recovery' AND json_extract(r.state_json,'$.operation')='build-start-over'))))
+          BEGIN SELECT RAISE(ABORT,'Build mutation rejected: original admission authority is stale or missing'); END;`);
+            }
+        }
+        migrateReadinessProtocol(db);
+    }).immediate();
+}
+export function readAdmission(db) {
+    const row = db.prepare("SELECT record_json FROM build_admission WHERE singleton=1").get();
+    return row ? JSON.parse(row.record_json) : undefined;
+}
+export function assertAdmission(db, authority) {
+    const held = readAdmission(db);
+    if (!held || held.token !== authority.token || held.runId !== authority.runId || held.project !== authority.project)
+        throw new BuildOwnershipError("stale-owner", "Build admission ownership changed; stale caller cannot mutate or dispatch");
+}
+export function acquireAdmission(db, project, runId, phase) {
+    return db.transaction(() => {
+        const held = readAdmission(db);
+        if (held) {
+            const owner = classifyProcess(held.pid, held.processStart, held.host);
+            if (owner.state !== "dead")
+                throw new BuildOwnershipError(owner.state === "live" ? "active-owner" : "unknown-owner", `Build ${held.runId} admission is ${owner.state}: ${owner.reason}`);
+            // A reserved launch cannot spawn until its owner conditionally marks it
+            // dispatching. Fence that transition before replacing a proven-dead owner.
+            for (const row of db.prepare("SELECT record_json FROM build_launches WHERE run_id=? AND state='reserved'").all(held.runId)) {
+                const launch = JSON.parse(row.record_json);
+                db.prepare("UPDATE build_launches SET state='failed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "failed" }), launch.token);
+            }
+            const pending = db.prepare("SELECT 1 FROM build_launches WHERE run_id=? AND state='dispatching'").get(held.runId);
+            if (pending)
+                throw new Error(`Build ${held.runId} has an unresolved launch; reconcile its child before retrying`);
+        }
+        db.prepare("INSERT OR IGNORE INTO build_runtime_runs VALUES(?)").run(runId);
+        const authority = { token: randomUUID(), project: canonicalProject(project), runId, pid: process.pid, host: hostname(), processStart: processStartIdentity(), phase, heartbeatAt: new Date().toISOString() };
+        db.prepare("INSERT OR REPLACE INTO build_admission VALUES(1,?)").run(JSON.stringify(authority));
+        return authority;
+    }).immediate();
+}
+export function releaseAdmission(db, authority) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        if (db.prepare("SELECT 1 FROM build_launches WHERE run_id=? AND state IN ('reserved','dispatching')").get(authority.runId))
+            throw new Error("Cannot release admission with an unresolved launch");
+        db.prepare("DELETE FROM build_admission WHERE singleton=1").run();
+    }).immediate();
+}
+export function reserveLaunch(db, authority, role, digest, protocol) {
+    return db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = { token: randomUUID(), runId: authority.runId, project: authority.project, launcher: authority.token, role, digest, protocol, state: "reserved", createdAt: new Date().toISOString() };
+        db.prepare("INSERT INTO build_launches VALUES(?,?,?,?)").run(launch.token, launch.runId, launch.state, JSON.stringify(launch));
+        return launch;
+    }).immediate();
+}
+export function readLaunch(db, token) {
+    const row = db.prepare("SELECT record_json FROM build_launches WHERE token=?").get(token);
+    return row ? JSON.parse(row.record_json) : undefined;
+}
+export function setLaunchState(db, authority, token, state) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = readLaunch(db, token);
+        if (state === "failed" && launch?.state === "failed" && launch.launcher === authority.token)
+            return;
+        if (!launch || launch.launcher !== authority.token || !(state === "dispatching" ? launch.state === "reserved" : ["reserved", "dispatching"].includes(launch.state)))
+            throw new Error("Invalid launch transition");
+        db.prepare("UPDATE build_launches SET state=?,record_json=? WHERE token=?").run(state, JSON.stringify({ ...launch, state }), token);
+    }).immediate();
+}
+export function claimLaunch(db, project, runId, token, role, digest) {
+    return db.transaction(() => {
+        const launch = readLaunch(db, token);
+        const owner = readAdmission(db);
+        if (!launch || launch.state !== "dispatching" || launch.project !== canonicalProject(project) || launch.runId !== runId || launch.role !== role || launch.digest !== digest || owner?.token !== launch.launcher || owner.host !== hostname())
+            throw new BuildOwnershipError("invalid-launch", "Invalid, stale, or already claimed build launch authorization");
+        if (launch.protocol === "registered-v2" && (!launch.acknowledged || launch.child?.pid !== process.pid || launch.child.processStart !== processStartIdentity() || launch.child.host !== hostname()))
+            throw new BuildOwnershipError("invalid-launch", "Build child registration was not acknowledged");
+        const authority = { ...owner, token: randomUUID(), phase: role, pid: process.pid, host: hostname(), processStart: processStartIdentity(), heartbeatAt: new Date().toISOString() };
+        db.prepare("UPDATE build_admission SET record_json=? WHERE singleton=1").run(JSON.stringify(authority));
+        db.prepare("UPDATE build_launches SET state='claimed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "claimed", claimant: authority }), token);
+        return authority;
+    }).immediate();
+}
+/** Child registration grants no mutation/provider authority. Competes atomically with retirement. */
+export function registerLaunchChild(db, token, project) {
+    db.transaction(() => {
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state !== "dispatching" || launch.protocol !== "registered-v2" || launch.project !== canonicalProject(project) || launch.child)
+            throw new BuildOwnershipError("invalid-launch", "Launch is retired, already registered, or invalid");
+        const child = { pid: process.pid, processStart: processStartIdentity(), host: hostname() };
+        if (child.processStart === "unavailable")
+            throw new BuildOwnershipError("unknown-owner", "Cannot register child process identity");
+        db.prepare("UPDATE build_launches SET record_json=? WHERE token=?").run(JSON.stringify({ ...launch, child }), token);
+    }).immediate();
+}
+export function acknowledgeLaunchChild(db, authority, token, pid) {
+    db.transaction(() => {
+        assertAdmission(db, authority);
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state !== "dispatching" || launch.launcher !== authority.token || launch.child?.pid !== pid || classifyProcess(pid, launch.child.processStart, launch.child.host).state !== "live")
+            throw new BuildOwnershipError("invalid-launch", "Registered child cannot be acknowledged");
+        db.prepare("UPDATE build_launches SET record_json=? WHERE token=?").run(JSON.stringify({ ...launch, acknowledged: true }), token);
+    }).immediate();
+}
+/** Restricted retirement only; does not grant execution authority or replay work. */
+export function reconcileLaunch(db, token, original) {
+    return db.transaction(() => {
+        const launch = readLaunch(db, token);
+        if (!launch || launch.state === "failed")
+            return "retired";
+        if (launch.state === "claimed")
+            return "claimed";
+        const owner = readAdmission(db);
+        if (!owner || owner.token !== launch.launcher)
+            return "unknown";
+        const callerOwns = original?.token === owner.token;
+        if (!callerOwns && classifyProcess(owner.pid, owner.processStart, owner.host).state !== "dead")
+            return "unknown";
+        // New gated children cannot enter the CLI until durable acknowledgement.
+        // Fence the token even if a delayed bootstrap is still registering.
+        const safe = launch.state === "reserved" || (launch.protocol === "registered-v2" && (!launch.acknowledged || (launch.child && classifyProcess(launch.child.pid, launch.child.processStart, launch.child.host).state === "dead")));
+        if (!safe)
+            return "unknown";
+        db.prepare("UPDATE build_launches SET state='failed',record_json=? WHERE token=?").run(JSON.stringify({ ...launch, state: "failed" }), token);
+        return "retired";
+    }).immediate();
+}
+/** Old open connections lack this function, even if they passed a prior schema check. */
+function migrateReadinessProtocol(db) {
+    const version = db.prepare("SELECT version FROM build_ownership_schema").get().version;
+    if (version === 3)
+        return;
+    const owner = readAdmission(db);
+    // Leave legacy inspection/restricted cleanup available. New execution requires v3.
+    if (owner && classifyProcess(owner.pid, owner.processStart, owner.host).state !== "dead")
+        return;
+    const lease = db.prepare("SELECT pid,process_start,host FROM project_lease").get();
+    if (lease && classifyProcess(lease.pid, lease.process_start, lease.host).state !== "dead")
+        return;
+    for (const row of db.prepare("SELECT state_json FROM supervisor_leases WHERE status IN ('running','stopping')").all()) {
+        const state = JSON.parse(row.state_json);
+        if (!state.pid || classifyProcess(state.pid, state.processStart).state !== "dead")
+            return;
+    }
+    for (const row of db.prepare("SELECT record_json FROM build_launches WHERE state IN ('reserved','dispatching')").all()) {
+        const launch = JSON.parse(row.record_json);
+        if (reconcileLaunch(db, launch.token) === "unknown")
+            return;
+    }
+    // Local executable ownership must be reconciled before semantic migration.
+    if (db.prepare("SELECT 1 FROM build_owned_processes WHERE state<>'quiescent' LIMIT 1").get())
+        return;
+    // Remote uncertainty survives migration unchanged. Recovery needs the new
+    // writer fences to reconcile it; ordinary admission still rejects dispatch uncertainty.
+    const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all();
+    for (const { name } of tables) {
+        if (!/^[a-z_]+$/.test(name))
+            throw new Error("Unexpected ownership table");
+        for (const action of ["INSERT", "UPDATE", "DELETE"])
+            db.exec(`CREATE TRIGGER IF NOT EXISTS protocol_v3_${name}_${action} BEFORE ${action} ON ${name} BEGIN SELECT CASE WHEN rafi_protocol_v3()<>1 THEN RAISE(ABORT,'Incompatible writer protocol') END; END`);
+    }
+    db.prepare("UPDATE build_ownership_schema SET version=3").run();
+}

package/dist/buildApproval.d.ts

@@ -7,3 +7,5 @@ export declare function approvedBuildScope(projectDir: string, ticketIds?: reado
 export declare function requiresBuildApproval(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences?: Record<string, unknown>): boolean;
 /** Bind decisions to current files so an old answer cannot approve a changed scope. */
 export declare function buildScopeRevision(projectDir: string, consequences?: Record<string, unknown>): string;
+/** Reuse a decision only while its source and consequences remain unchanged. */
+export declare function createBuildApprovalGate(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences: Record<string, unknown> | undefined, requestApproval: () => Promise<void>): () => Promise<void>;

package/dist/buildApproval.js

@@ -124,3 +124,20 @@ export function buildScopeRevision(projectDir, consequences) {
     });
     return createHash("sha256").update(JSON.stringify([contents, consequences])).digest("hex");
 }
+/** Reuse a decision only while its source and consequences remain unchanged. */
+export function createBuildApprovalGate(projectDir, ticketIds, explicitYes, consequences, requestApproval) {
+    let approvedRevision;
+    return async () => {
+        while (true) {
+            const revision = buildScopeRevision(projectDir, consequences);
+            if (revision === approvedRevision)
+                return;
+            if (requiresBuildApproval(projectDir, ticketIds, explicitYes, consequences))
+                await requestApproval();
+            if (revision !== buildScopeRevision(projectDir, consequences))
+                continue;
+            approvedRevision = revision;
+            return;
+        }
+    };
+}

package/dist/buildLaunchGate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/buildLaunchGate.js

@@ -0,0 +1,36 @@
+/** Minimal pre-CLI child. No providers or mutable workflow code before acknowledgement. */
+import { WorkflowDb } from "./workflowDb.js";
+import { pathToFileURL } from "node:url";
+const [entry, project, token, ...args] = process.argv.slice(2);
+if (!entry || !project || !token || !process.send || !process.connected)
+    throw new Error("Missing resume startup channel");
+const db = new WorkflowDb(project);
+try {
+    db.registerBuildLaunchChild(token);
+}
+finally {
+    db.close();
+}
+await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => finish(new Error("Resume startup acknowledgement timed out")), 10_000);
+    const disconnected = () => finish(new Error("Resume launcher exited before acknowledgement"));
+    const message = (value) => { if (value === "rafi-launch-ack")
+        finish(); };
+    function finish(error) {
+        clearTimeout(timeout);
+        process.off("disconnect", disconnected);
+        process.off("message", message);
+        if (error)
+            reject(error);
+        else
+            resolve();
+    }
+    process.once("disconnect", disconnected);
+    process.on("message", message);
+    process.send({ kind: "rafi-launch-registered", token });
+});
+// The durable claim still validates the token atomically after acknowledgement.
+if (!process.env.RAFI_BUILD_WORKER_RUN)
+    process.disconnect();
+process.argv = [process.execPath, entry, ...args];
+await import(pathToFileURL(entry).href);

package/dist/buildRuns.d.ts

@@ -1,9 +1,12 @@
+export { withBuildInvocation as withBuildRecoveryInvocation, launchDigest as launchArgumentDigest } from "./buildAdmission.js";
 import type { AutonomyProfile, BuildRunRecordV2, ProviderSessionRefV1, ResolvedAgentSettings, ResolvedAutonomyPolicy, SessionAvailabilityV1 } from "rafi-spec";
+import { type ProjectLease } from "./workflowDb.js";
 import { type ResolveSessionAvailabilityOptions } from "./sessionAvailability.js";
 export declare const BUILD_RUN_VERSION = 3;
 export declare const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export declare const BUILD_HEARTBEAT_MS = 10000;
 export declare const BUILD_LEASE_STALE_MS = 45000;
+export declare function bindBuildAuthority(run: BuildRunRecordV2, lease: ProjectLease): BuildRunRecordV2;
 export interface CreateBuildRunInput {
     runId?: string;
     tickets: string[];
@@ -44,9 +47,14 @@ export declare function recordBuildReceipt(projectDir: string, run: BuildRunReco
 export declare function heartbeatBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 export declare function releaseBuildLease(projectDir: string, run: BuildRunRecordV2, status?: BuildRunRecordV2["status"]): BuildRunRecordV2;
 export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
+/** A recovered ticket boundary is complete only when the saved run scope is done. */
+export declare function finishRecoveredTicketScope(projectDir: string, run: BuildRunRecordV2, checkpoint: string): BuildRunRecordV2;
 export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];
 export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV2 & {
     active: boolean;
+    ownership: "live" | "dead" | "unknown";
+    ownershipReason: string;
+    cleanupOnly?: boolean;
 }>;
 export declare function isLeaseActive(run: BuildRunRecordV2, now?: Date): boolean;
 export declare function buildRecoveryPreview(run: BuildRunRecordV2): string[];
@@ -74,7 +82,16 @@ export interface BuildRecoveryProjection {
     sessionCandidateRef?: ProviderSessionRefV1;
     sessionAvailability?: SessionAvailabilityV1;
 }
+/** Saved context may be broader than the work authorized for this invocation. */
+export declare function recoveryExecutionTickets(run: BuildRunRecordV2, requested: readonly string[], frozen: boolean): string[];
+/** Read-only reconciliation also handles crashes before the last progress checkpoint. */
+export declare function currentBranchTicketProgress(projectDir: string, run: BuildRunRecordV2): {
+    completed: string[];
+    remaining: string[];
+    pendingQa: string[];
+} | undefined;
+/** Match the frozen preview at both the resume wrapper and direct start boundary. */
+export declare function currentBranchRecoveryTicket(projectDir: string, run: BuildRunRecordV2): string | undefined;
 export declare function projectBuildRecovery(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, sessionAvailability?: SessionAvailabilityV1): BuildRecoveryProjection;
 export declare function resolveBuildRecoveryProjection(projectDir: string, run: BuildRunRecordV2, now?: Date, ticketOverride?: string, probe?: ResolveSessionAvailabilityOptions): Promise<BuildRecoveryProjection>;
 export declare function formatBuildRecoveryProjection(projection: BuildRecoveryProjection): string[];
-export {};