ai-foreman 1.7.19 → 1.7.21

package/dist/buildRuns.js

@@ -1,5 +1,7 @@
+import { loadQaPreparationPolicy } from "./qaEffectiveConfig.js";
+export { withBuildInvocation as withBuildRecoveryInvocation, launchDigest as launchArgumentDigest } from "./buildAdmission.js";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -12,11 +14,27 @@ import { captureCurrentWorkflowSessionIdentity, currentWorkflowIdentityKey } fro
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
 import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
-import { isLiveProcessIdentity, processStartIdentity } from "./processIdentity.js";
+import { classifyProcess, processStartIdentity } from "./processIdentity.js";
+import { assertBuildAssignmentReconciled } from "./buildAssignment.js";
 export const BUILD_RUN_VERSION = 3;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
 export const BUILD_LEASE_STALE_MS = 45_000;
+const buildAuthority = Symbol("buildAuthority");
+export function bindBuildAuthority(run, lease) {
+    return { ...run, [buildAuthority]: lease };
+}
+function assertBuildAuthority(workflow, run) {
+    const token = run[buildAuthority];
+    if (!token)
+        throw new Error("build mutation requires the caller's original workflow authority");
+    const held = workflow.currentLease();
+    const authorizedSupersession = run.status === "superseded" && run.supersededBy === held?.runId;
+    if (token && (!held || held.owner !== token.owner || held.generation !== token.generation || held.runId !== token.runId))
+        throw new Error("workflow lease ownership changed");
+    if (held && (!token || (held.runId !== run.runId && !authorizedSupersession)))
+        throw new Error("build mutation requires the caller's original workflow authority");
+}
 export function createBuildRun(input) {
     const now = input.now ?? new Date();
     // Complete the one-time legacy import before the new mutable build snapshot
@@ -32,6 +50,8 @@ export function createBuildRun(input) {
         runId: input.runId ?? randomUUID(),
         status: "running",
         tickets: [...input.tickets],
+        authorizedBatch: input.authorizedBatch ?? (input.tickets.length && (input.branchMode ?? "current") === "current" ? { tickets: [...input.tickets], requestedSteps: input.tickets.length, scopeRevision: "explicit-create-selection", startedTickets: [] } : undefined),
+        builderCapabilities: input.builderCapabilities,
         deliveryUnit: input.deliveryUnit,
         branchMode: input.branchMode ?? "current",
         checkpoint: "created",
@@ -61,45 +81,37 @@ export function createBuildRun(input) {
         createdAt: stamp,
         updatedAt: stamp,
     };
-    const saved = saveBuildRun(input.repositoryRoot, run, now);
     const workflow = new WorkflowDb(input.repositoryRoot);
     try {
-        workflow.acquireLease(saved.runId, undefined, now, BUILD_LEASE_STALE_MS);
+        workflow.ensureRun(run.runId, "build", now);
+        const authority = workflow.acquireLease(run.runId, undefined, now, BUILD_LEASE_STALE_MS);
+        workflow.qaPreparationStore().freezePolicy(run.runId, loadQaPreparationPolicy(input.repositoryRoot));
+        return saveBuildRun(input.repositoryRoot, bindBuildAuthority(run, authority), now);
     }
     finally {
         workflow.close();
     }
-    return saved;
 }
 export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
     let existing = readBuildRuns(projectDir).find((run) => run.runId === runId);
     if (!existing)
         throw new Error(`recoverable build run not found: ${runId}`);
-    if (existing.status === "completed" || existing.status === "superseded")
+    if (["completed", "cancelled", "superseded"].includes(existing.status))
         throw new Error(`build run ${runId} is ${existing.status} and cannot resume`);
     const workflow = new WorkflowDb(projectDir);
+    let authority;
     try {
-        const held = workflow.currentLease();
-        if (held && held.runId === runId && held.pid === process.pid && held.host === hostname() && held.processStart === processStartIdentity(process.pid)) {
-            workflow.heartbeatLease(held, now);
-        }
-        else {
-            workflow.acquireLease(runId, undefined, now, BUILD_LEASE_STALE_MS);
-        }
+        authority = workflow.acquireLease(runId, undefined, now, BUILD_LEASE_STALE_MS);
         if (patch.expectedRecoveryDecisionDigest) {
             const decision = workflow.getRun(runId)?.state.recoveryDecision;
             if (createHash("sha256").update(JSON.stringify(decision ?? null)).digest("hex") !== patch.expectedRecoveryDecisionDigest) {
-                const lease = workflow.currentLease();
-                if (lease?.runId === runId && lease.pid === process.pid)
-                    workflow.releaseLease(lease, now);
+                workflow.releaseLease(authority, now);
                 throw new Error("Recovery decision changed before the child supervisor acquired its lease; inspect and retry");
             }
         }
         existing = readBuildRuns(projectDir).find((run) => run.runId === runId);
-        if (!existing || existing.status === "completed" || existing.status === "superseded") {
-            const lease = workflow.currentLease();
-            if (lease?.runId === runId && lease.pid === process.pid)
-                workflow.releaseLease(lease, now);
+        if (!existing || ["completed", "cancelled", "superseded"].includes(existing.status)) {
+            workflow.releaseLease(authority, now);
             throw new Error("Recovery run completed or disappeared before lease acquisition");
         }
     }
@@ -111,7 +123,7 @@ export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
         ? undefined
         : patch.builderSessionRef?.sessionId ?? patch.builderSessionId ?? existing.builder?.sessionId;
     return saveBuildRun(projectDir, {
-        ...existing, status: "running", checkpoint: "recovery-resumed", completedAt: undefined,
+        ...bindBuildAuthority(existing, authority), status: "running", checkpoint: "recovery-resumed", completedAt: undefined,
         builder: patch.builder ? { settings: normalizeCapturedSettings(patch.builder), ...(builderSessionId ? { sessionId: builderSessionId } : {}) } : existing.builder,
         qa: patch.qa ? { settings: normalizeCapturedSettings(patch.qa), sessionId: existing.qa?.sessionId } : existing.qa,
         sessionBindings: patch.builderSessionRef ? upsertSessionBinding(existing.sessionBindings, patch.builderSessionRef) : existing.sessionBindings,
@@ -123,15 +135,28 @@ function normalizeCapturedSettings(settings) {
         ...settings,
         session_strategy: settings.session_strategy ?? (["builder", "qa", "ticket-maker"].includes(settings.role) ? "compact" : "fresh"),
         display_session_cost: settings.display_session_cost ?? false,
-        auto_compact_threshold_percent: settings.auto_compact_threshold_percent ?? 50,
+        auto_compact_threshold_percent: settings.auto_compact_threshold_percent ?? 65,
         compact_maximum: settings.compact_maximum ?? 10,
         settings_revision: settings.settings_revision ?? 0,
     };
 }
 export function saveBuildRun(projectDir, run, now = new Date()) {
+    if (!run[buildAuthority])
+        throw new Error("build mutation requires the caller's original workflow authority");
+    if (canonicalSessionPath(projectDir) !== canonicalSessionPath(run.repository.root))
+        throw new Error("Build authority belongs to another project");
+    const original = run[buildAuthority];
+    const current = readCurrentWorkflowLease(projectDir);
+    if (!current || current.owner !== original.owner || current.generation !== original.generation || current.runId !== original.runId)
+        throw new Error("workflow lease ownership changed");
     validateBuildRun(run);
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
-    mkdirSync(directory, { recursive: true });
+    const progress = ["recoverable", "interrupted", "blocked", "failed"].includes(run.status) ? currentBranchTicketProgress(projectDir, run) : undefined;
+    if (progress)
+        run = { ...run,
+            currentTicket: progress.pendingQa.find(ticket => run.tickets.includes(ticket)) ?? (run.currentTicket && progress.remaining.includes(run.currentTicket) ? run.currentTicket : progress.remaining[0]),
+            progress: { ...run.progress, completedTickets: progress.completed, remainingTickets: progress.remaining },
+        };
     const upgraded = upgradeBuildRun(run, projectDir, now);
     const completedOperations = Object.keys(upgraded.receipts).sort();
     let next = {
@@ -142,13 +167,17 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
     const workflow = new WorkflowDb(projectDir);
     const target = join(directory, `${run.runId}.json`);
     let publicationId;
+    let temporary;
     try {
         workflow.atomic(() => {
+            assertBuildAuthority(workflow, run);
             const frozenPolicy = workflow.freezeAutonomyPolicy(next.runId, next.frozenPolicy, now);
             next = { ...next, frozenPolicy, recoveryAttempts: workflow.recoveryAttempts(next.runId), pendingDecisions: workflow.pendingHumanDecisions(next.runId), supervisor: workflow.supervisorState(next.runId) ?? next.supervisor };
             const existing = workflow.getRun(next.runId);
-            if (existing?.status === "superseded" && next.status !== "superseded")
-                throw new Error("cannot rewrite a superseded build run as active");
+            const priorProgress = existing?.state.progress;
+            next = { ...next, progress: { ...next.progress, completedTickets: [...new Set([...next.progress.completedTickets, ...(priorProgress?.completedTickets ?? [])])] } };
+            if (existing && ["completed", "cancelled", "superseded"].includes(existing.status) && workflowStatus(next.status) !== existing.status)
+                throw new Error(`cannot rewrite a ${existing.status} build run`);
             if (!existing)
                 workflow.createRun({
                     runId: next.runId, kind: "build", checkpoint: next.checkpoint,
@@ -167,9 +196,17 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
             publicationId = workflow.beginPublication(next.runId, { operation: "build-run-projection", target,
                 revision: createHash("sha256").update(JSON.stringify(next)).digest("hex"), updatedAt: next.updatedAt }, {}, now).transactionId;
         });
+        mkdirSync(directory, { recursive: true });
         const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+        temporary = temp;
         writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-        renameSync(temp, target);
+        workflow.atomic(() => {
+            assertBuildAuthority(workflow, run);
+            if (JSON.stringify(workflow.getRun(run.runId)?.state) !== JSON.stringify(next))
+                throw new Error("Build projection changed before publication");
+            renameSync(temp, target);
+            temporary = undefined;
+        });
         workflow.atomic(() => {
             workflow.updatePublication(publicationId, "committed", now);
             // Publishing the latest authoritative revision also reconciles any older
@@ -182,6 +219,8 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
         });
     }
     finally {
+        if (temporary)
+            rmSync(temporary, { force: true });
         workflow.close();
     }
     return next;
@@ -243,7 +282,7 @@ export function recordBuildReceipt(projectDir, run, operationId, detail) {
     return next;
 }
 export function heartbeatBuildRun(projectDir, run, now = new Date()) {
-    const lease = readCurrentWorkflowLease(projectDir);
+    const lease = run[buildAuthority];
     if (!lease || lease.runId !== run.runId)
         throw new Error("workflow lease ownership changed");
     const next = heartbeatCurrentWorkflowLease(projectDir, lease, now);
@@ -251,21 +290,45 @@ export function heartbeatBuildRun(projectDir, run, now = new Date()) {
 }
 export function releaseBuildLease(projectDir, run, status = "interrupted") {
     const saved = saveBuildRun(projectDir, { ...run, status, lease: undefined });
-    releaseWorkflowLease(projectDir, run.runId);
+    releaseWorkflowLease(projectDir, run);
     return saved;
 }
 export function completeBuildRun(projectDir, run, now = new Date()) {
+    assertBuildAssignmentReconciled(projectDir, run.runId);
+    if (run.status === "completed") {
+        const committed = readBuildRuns(projectDir).find(item => item.runId === run.runId);
+        if (committed?.status === "completed" && JSON.stringify(committed) === JSON.stringify(run))
+            return committed;
+    }
     const workflow = new WorkflowDb(projectDir);
     try {
         workflow.assertQaRunFinalizable(run.runId);
+        if (workflow.pendingHumanDecisions(run.runId).length)
+            throw new Error("build run has unanswered decisions");
+        if (["builder", "qa"].some(role => workflow.unresolvedRoleDispatches(run.runId, role).length))
+            throw new Error("build run has unresolved provider dispatches");
     }
     finally {
         workflow.close();
     }
     const saved = saveBuildRun(projectDir, { ...run, status: "completed", checkpoint: "complete", lease: undefined, completedAt: now.toISOString(), progress: { ...run.progress, completedTickets: [...run.tickets], remainingTickets: [], nextAction: "None; build complete" } }, now);
-    releaseWorkflowLease(projectDir, run.runId, now);
+    releaseWorkflowLease(projectDir, run, now);
     return saved;
 }
+/** A recovered ticket boundary is complete only when the saved run scope is done. */
+export function finishRecoveredTicketScope(projectDir, run, checkpoint) {
+    if (run.branchMode !== "current" || !run.tickets.length || !isTicketsInitialized(projectDir))
+        throw new Error("Ticket recovery completion requires an initialized current-branch run scope");
+    const { completed, remaining } = currentBranchTicketProgress(projectDir, run);
+    if (!remaining.length && !run.authorizedBatch)
+        return releaseBuildLease(projectDir, checkpointBuildRun(projectDir, run, "legacy-scope-reconciliation-required", { progress: { ...run.progress, completedTickets: completed, remainingTickets: [], nextAction: "Confirm the original authorized batch scope before declaring the build complete" } }), "recoverable");
+    if (!remaining.length)
+        return completeBuildRun(projectDir, run);
+    return releaseBuildLease(projectDir, checkpointBuildRun(projectDir, run, checkpoint, {
+        currentTicket: remaining[0],
+        progress: { ...run.progress, completedTickets: completed, remainingTickets: remaining, nextAction: `Resume ${remaining[0]}` },
+    }), "recoverable");
+}
 export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     const workflow = new WorkflowReader(projectDir);
@@ -282,6 +345,17 @@ export function readBuildRuns(projectDir) {
         const value = stored.state;
         if (value?.runId)
             candidates.set(value.runId, value);
+        else if (!["completed", "superseded", "cancelled"].includes(stored.status) && !candidates.has(stored.runId)) {
+            // Supervision/readiness can stop before the first full build snapshot.
+            // Keep that attempt visible without inventing a provider session or baseline.
+            candidates.set(stored.runId, {
+                version: 1, runId: stored.runId, status: stored.status === "running" ? "running" : "recoverable",
+                tickets: [], branchMode: "current", checkpoint: stored.checkpoint,
+                repository: { root: resolve(projectDir), worktree: resolve(projectDir) }, receipts: {},
+                createdAt: stored.createdAt, updatedAt: stored.updatedAt,
+                failure: { category: "preparation-incomplete", summary: "Build preparation stopped before a complete build checkpoint", at: stored.updatedAt },
+            });
+        }
     }
     const runs = [...candidates.values()].flatMap((projection) => {
         try {
@@ -289,8 +363,9 @@ export function readBuildRuns(projectDir) {
             const authoritative = workflow?.getRun(projection.runId)?.state;
             const run = authoritative?.runId ? authoritative : projection;
             let upgraded = upgradeBuildRun(run, projectDir);
-            if (workflow?.getRun(run.runId)?.status === "superseded")
-                upgraded = { ...upgraded, status: "superseded" };
+            const dbStatus = workflow.getRun(run.runId)?.status;
+            if (dbStatus === "superseded" || dbStatus === "completed" || dbStatus === "cancelled")
+                upgraded = { ...upgraded, status: dbStatus };
             if (!["completed", "superseded", "cancelled"].includes(workflow?.getRun(run.runId)?.status ?? "")) {
                 for (const role of ["builder", "qa"]) {
                     const lease = workflow?.roleMutationLease(run.runId, role);
@@ -304,36 +379,53 @@ export function readBuildRuns(projectDir) {
         catch {
             return [];
         }
-    }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.runId.localeCompare(b.runId));
     workflow?.close();
     return runs;
 }
 export function recoverableBuildRuns(projectDir, now = new Date()) {
-    const databaseLease = readCurrentWorkflowLease(projectDir);
-    return readBuildRuns(projectDir)
-        .filter((run) => run.status !== "completed")
-        .map((run) => ({ ...inferLegacyRunTickets(projectDir, run), active: databaseLease?.runId === run.runId ? workflowLeaseLooksLive(databaseLease, now) : isLeaseActive(run, now) }));
-}
-function workflowLeaseLooksLive(lease, now) {
-    if (now.getTime() - new Date(lease.heartbeatAt).getTime() > BUILD_LEASE_STALE_MS)
-        return false;
-    if (lease.host !== hostname())
-        return true;
-    return isLiveProcessIdentity(lease.pid, lease.processStart);
+    const reader = new WorkflowReader(projectDir);
+    const databaseLease = reader.currentLease();
+    const admission = reader.buildAdmission();
+    const unfinished = readBuildRuns(projectDir).filter(run => !["completed", "cancelled", "superseded"].includes(run.status));
+    const cleanupRuns = [...new Set(reader.readinessProcesses().map(row => row.run_id))].filter(id => !unfinished.some(run => run.runId === id)).map(runId => {
+        const run = reader.getRun(runId);
+        const at = run?.updatedAt ?? new Date(0).toISOString();
+        return { ...upgradeBuildRun({ version: 1, runId, status: "recoverable", tickets: [], branchMode: "current", checkpoint: "readiness-cleanup", repository: { root: resolve(projectDir), worktree: resolve(projectDir) }, receipts: {}, createdAt: run?.createdAt ?? at, updatedAt: at }, projectDir), cleanupOnly: true };
+    });
+    try {
+        return [...unfinished, ...cleanupRuns]
+            .map(run => {
+            const owners = [];
+            if (admission?.runId === run.runId)
+                owners.push(classifyProcess(admission.pid, admission.processStart, admission.host));
+            if (databaseLease?.runId === run.runId)
+                owners.push(classifyProcess(databaseLease.pid, databaseLease.processStart, databaseLease.host));
+            if (run.supervisor?.pid && ["running", "stopping"].includes(run.supervisor.status))
+                owners.push(classifyProcess(run.supervisor.pid, run.supervisor.processStart));
+            if (!owners.length && run.lease)
+                owners.push(classifyProcess(run.lease.pid, run.lease.processStart, run.lease.hostname));
+            let owner = owners.find(item => item.state === "live") ?? owners.find(item => item.state === "unknown") ?? { state: "dead", reason: "No live owner recorded" };
+            if (owner.state !== "live" && reader.pendingBuildLaunches(run.runId).some(launch => launch.state === "dispatching"))
+                owner = { state: "unknown", reason: "launch dispatch began but no child claim was confirmed; reconcile the launcher and child process evidence before retrying" };
+            return { ...run, active: owner.state === "live", ownership: owner.state, ownershipReason: owner.reason };
+        });
+    }
+    finally {
+        reader.close();
+    }
 }
 /**
- * Current-branch runs created before ticket checkpointing did not retain their
- * selected ticket. Recover it from Foreman's tracker events so --ticket can
- * still address those durable runs without rewriting the legacy record.
+ * Timestamp correlations are diagnostic hints, never executable membership.
  */
-function inferLegacyRunTickets(projectDir, run) {
-    if (run.tickets.length > 0 || !isTicketsInitialized(projectDir))
-        return run;
+export function legacyTrackerWorkHints(projectDir, run) {
+    if (!isTicketsInitialized(projectDir))
+        return [];
     let db;
     try {
         const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
         if (!existsSync(paths.stateDb))
-            return run;
+            return [];
         db = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
         const rows = db.prepare(`
       SELECT ticket_id
@@ -345,26 +437,18 @@ function inferLegacyRunTickets(projectDir, run) {
       ORDER BY timestamp, id
     `).all(run.createdAt, run.updatedAt);
         const tickets = [...new Set(rows.map((row) => row.ticket_id).filter(Boolean))];
-        if (tickets.length === 0)
-            return run;
-        return { ...run, tickets, currentTicket: tickets.at(-1) };
+        return tickets;
     }
     catch {
-        return run;
+        return [];
     }
     finally {
         db?.close();
     }
 }
 export function isLeaseActive(run, now = new Date()) {
-    if (!run.lease)
-        return false;
-    const age = now.getTime() - new Date(run.lease.heartbeatAt).getTime();
-    if (age > BUILD_LEASE_STALE_MS)
-        return false;
-    if (run.lease.hostname !== hostname())
-        return true;
-    return isLiveProcessIdentity(run.lease.pid, run.lease.processStart);
+    void now;
+    return Boolean(run.lease && classifyProcess(run.lease.pid, run.lease.processStart, run.lease.hostname).state !== "dead");
 }
 export function buildRecoveryPreview(run) {
     const completed = Object.keys(run.receipts).sort();
@@ -381,6 +465,59 @@ export function buildRecoveryPreview(run) {
         `QA session ${buildRunSessionBinding(run, "qa") ? "QA session candidate requires validation" : "fresh QA session required"}`,
     ];
 }
+/** Saved context may be broader than the work authorized for this invocation. */
+export function recoveryExecutionTickets(run, requested, frozen) {
+    const scope = frozen && run.recoveryDecision?.executionTickets !== undefined
+        ? run.recoveryDecision.executionTickets
+        : requested.length ? requested : run.tickets;
+    if (scope.some(ticket => !run.tickets.includes(ticket)) || requested.some(ticket => !scope.includes(ticket)) || (run.tickets.length && !scope.length)) {
+        throw new Error("Recovery execution scope conflicts with the saved run or requested ticket");
+    }
+    return [...new Set(scope)];
+}
+/** Read-only reconciliation also handles crashes before the last progress checkpoint. */
+export function currentBranchTicketProgress(projectDir, run) {
+    if (run.branchMode !== "current" || !run.tickets.length || !isTicketsInitialized(projectDir))
+        return undefined;
+    if (run.status === "completed")
+        return { completed: [...run.tickets], remaining: [], pendingQa: [] };
+    const workflow = new WorkflowReader(projectDir);
+    let pendingQa;
+    let questions;
+    try {
+        pendingQa = workflow.pendingQaTicketIds(run.runId);
+        questions = workflow.pendingHumanDecisions(run.runId).filter(item => item.interruptionId.startsWith("ticket:")).map(item => item.interruptionId.slice(7));
+    }
+    finally {
+        workflow.close();
+    }
+    let state;
+    let completed = [];
+    try {
+        const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+        state = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
+        const read = state.prepare("SELECT status FROM ticket_state WHERE ticket_id=?");
+        completed = run.tickets.filter(ticket => read.get(ticket)?.status === "done" && !pendingQa.includes(ticket) && !questions.includes(ticket));
+    }
+    catch {
+        // Legacy, missing or unreadable tracker evidence cannot authorize completion.
+        // Keep recovery inspectable; actual dispatch still requires a usable tracker.
+        completed = [];
+    }
+    finally {
+        state?.close();
+    }
+    return { completed, remaining: run.tickets.filter(ticket => !completed.includes(ticket)), pendingQa };
+}
+/** Match the frozen preview at both the resume wrapper and direct start boundary. */
+export function currentBranchRecoveryTicket(projectDir, run) {
+    if (run.currentTicket && !run.tickets.includes(run.currentTicket))
+        throw new Error(`Recovery ticket ${run.currentTicket} is outside the saved run scope`);
+    const ticket = projectBuildRecovery(projectDir, run).ticketId;
+    if (ticket && !run.tickets.includes(ticket))
+        throw new Error(`Recovery ticket ${ticket} is outside the saved run scope`);
+    return ticket;
+}
 export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOverride, sessionAvailability) {
     let operationNames = [];
     let issues = [];
@@ -397,7 +534,13 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         }
     }
     const stateTicket = typeof workflowState.currentTicket === "string" ? workflowState.currentTicket : undefined;
-    const ticketId = ticketOverride ?? stateTicket ?? run.currentTicket ?? run.progress.remainingTickets[0] ?? run.tickets[0];
+    const progress = currentBranchTicketProgress(projectDir, run);
+    if (progress && stateTicket && !run.tickets.includes(stateTicket))
+        throw new Error(`Recovery ticket ${stateTicket} is outside the saved run scope`);
+    const savedTicket = stateTicket ?? run.currentTicket;
+    const ticketId = ticketOverride ?? (progress
+        ? progress.pendingQa.find(ticket => run.tickets.includes(ticket)) ?? (savedTicket && progress.remaining.includes(savedTicket) ? savedTicket : progress.remaining[0])
+        : savedTicket ?? run.progress.remainingTickets[0] ?? run.tickets[0]);
     let ticketTitle;
     if (ticketId && isTicketsInitialized(projectDir)) {
         try {
@@ -420,15 +563,15 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         unexpectedChanges.push({ path: recoveryWorktree, risk: "preserved worktree identity changed" });
     if (branchChanged)
         unexpectedChanges.push({ path: recoveryWorktree, risk: `branch changed from ${expectedBranch} to ${branchNow}` });
-    const completed = [...new Set([...run.progress.completedTickets, ...run.progress.completedOperations, ...operationNames])];
-    const remaining = run.progress.remainingTickets.length ? run.progress.remainingTickets : remainingTickets(run);
+    const completed = [...new Set([...(progress?.completed ?? run.progress.completedTickets), ...run.progress.completedOperations, ...operationNames])];
+    const remaining = progress?.remaining ?? (run.progress.remainingTickets.length ? run.progress.remainingTickets : remainingTickets(run));
     const interruption = run.interruption?.lastError ?? run.interruption?.summary ?? run.failure?.summary ?? issues.at(-1) ?? run.status;
     const validation = run.progress.validation
         ? `${run.progress.validation.status}${run.progress.validation.qa ? `; QA ${run.progress.validation.qa}` : ""}`
         : run.qa?.sessionId ? "QA session checkpointed" : "no completed QA/validation checkpoint recorded";
     const nextAction = ticketOverride
         ? `Resume ${ticketOverride} from ${run.checkpoint}`
-        : run.progress.nextAction ?? (ticketId ? `Resume ${ticketId} from ${run.checkpoint}` : `Resume from ${run.checkpoint}`);
+        : (progress ? undefined : run.progress.nextAction) ?? (ticketId ? `Resume ${ticketId} from ${run.checkpoint}` : `Resume from ${run.checkpoint}`);
     const primary = ticketId ? `${ticketId}${ticketTitle ? `: ${ticketTitle}` : ""}` : "legacy run (ticket unavailable)";
     const stateSessionId = typeof workflowState.sessionId === "string" ? workflowState.sessionId : undefined;
     const sessionCandidateRef = buildRunSessionBinding(run, "builder", stateSessionId ?? run.builder?.sessionId);
@@ -510,6 +653,8 @@ function validateBuildRun(run) {
     }
 }
 function workflowStatus(status) {
+    if (status === "cancelled")
+        return "cancelled";
     if (status === "completed")
         return "completed";
     if (status === "failed")
@@ -524,7 +669,7 @@ function workflowStatus(status) {
 }
 function remainingTickets(run) {
     const current = run.currentTicket ? run.tickets.indexOf(run.currentTicket) : 0;
-    return run.status === "completed" ? [] : run.tickets.slice(Math.max(0, current));
+    return run.status === "completed" ? [] : (run.branchMode === "current" ? run.tickets : run.tickets.slice(Math.max(0, current))).filter(ticket => run.branchMode !== "current" || !run.progress.completedTickets.includes(ticket));
 }
 function captureGitSnapshot(worktree, input) {
     const git = (args) => {
@@ -619,11 +764,12 @@ function upgradeBuildRun(run, projectDir = run.repository.root, now = new Date()
         deferredTickets: [],
     };
 }
-function releaseWorkflowLease(projectDir, runId, now = new Date()) {
+function releaseWorkflowLease(projectDir, run, now = new Date()) {
     const workflow = new WorkflowDb(projectDir);
     try {
-        const lease = workflow.currentLease();
-        if (lease?.runId === runId)
+        assertBuildAuthority(workflow, run);
+        const lease = run[buildAuthority];
+        if (lease)
             workflow.releaseLease(lease, now);
     }
     finally {

package/dist/buildSyntheticWork.d.ts

@@ -0,0 +1,2 @@
+/** Explicit unticketed CLI mode freezes each work definition before its first dispatch. */
+export declare function initializeSyntheticWork(projectDir: string, runId: string, steps: number, authorization: string, approvedPlan?: string): string[];

package/dist/buildSyntheticWork.js

@@ -0,0 +1,30 @@
+import { randomUUID } from "node:crypto";
+import { WorkflowDb } from "./workflowDb.js";
+import { buildScopeRevision } from "./buildApproval.js";
+/** Explicit unticketed CLI mode freezes each work definition before its first dispatch. */
+export function initializeSyntheticWork(projectDir, runId, steps, authorization, approvedPlan = "Explicit unticketed work authorized by the host") {
+    if (!Number.isSafeInteger(steps) || steps < 1 || steps > 10000)
+        throw new Error("Invalid synthetic work step limit");
+    if (!approvedPlan.trim() || Buffer.byteLength(approvedPlan) > 262144)
+        throw new Error("Synthetic work requires a bounded, frozen approved preflight plan");
+    const db = new WorkflowDb(projectDir);
+    try {
+        return db.atomic(() => {
+            db.ensureRun(runId);
+            const existing = db.workDefinitions(runId).filter(work => work.kind === "synthetic");
+            if (existing.length)
+                return existing.map(work => work.workId);
+            const ids = [];
+            for (let step = 1; step <= steps; step++) {
+                const id = `synthetic:${randomUUID()}`;
+                const definition = { id, order: step, title: `Authorized unticketed step ${step}`, area: "project", priority: "P2", size: "M", risk: "Low", depends_on: [], summary: `Implement step ${step} of the explicitly authorized project work`, acceptance: ["Satisfy the approved project requirements and the host preflight plan"], required_tests: ["Run the relevant project validation"], likely_files: [], notes: `Frozen approved preflight plan:\n${approvedPlan}` };
+                db.admitWork({ runId, kind: "synthetic", workId: id, definition, approvalId: `unticketed:${runId}`, scopeRevision: buildScopeRevision(projectDir), provenance: { userTurn: authorization, reason: "Explicit unticketed CLI invocation after approval" } });
+                ids.push(id);
+            }
+            return ids;
+        });
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/buildWorkAdmission.d.ts

@@ -0,0 +1,17 @@
+import type Database from "better-sqlite3";
+import { type BuildWorkAdmissionV1 } from "rafi-spec";
+export type { BuildWorkAdmissionV1 } from "rafi-spec";
+export interface AdmitWorkInput {
+    runId: string;
+    workId?: string;
+    kind: "ticket" | "synthetic";
+    ticketId?: string;
+    definition: unknown;
+    approvalId: string;
+    scopeRevision: string;
+    provenance: BuildWorkAdmissionV1["provenance"];
+}
+export declare function admittedWork(db: Database.Database, runId: string, workId: string): BuildWorkAdmissionV1 | undefined;
+export declare function assertAdmittedWork(db: Database.Database, runId: string, workId: string): BuildWorkAdmissionV1;
+/** Only host approval/reconciliation callers hold this service; reads never call it. */
+export declare function admitWork(db: Database.Database, input: AdmitWorkInput, metadataRepair?: boolean): BuildWorkAdmissionV1;

package/dist/buildWorkAdmission.js

@@ -0,0 +1,57 @@
+import { createHash, randomUUID } from "node:crypto";
+import { qaDigest } from "./qaProtocolV2.js";
+import { validateBuildWorkAdmissionV1 } from "rafi-spec";
+export function admittedWork(db, runId, workId) {
+    const row = db.prepare("SELECT a.record_json FROM build_work_admissions a JOIN build_work_scope s USING(run_id,work_id) WHERE a.run_id=? AND a.work_id=? AND s.state='admitted' ORDER BY a.sequence DESC LIMIT 1").get(runId, workId);
+    return row ? JSON.parse(row.record_json) : undefined;
+}
+export function assertAdmittedWork(db, runId, workId) {
+    const admission = admittedWork(db, runId, workId);
+    if (!admission)
+        throw new Error(`Work ${runId}/${workId} is not admitted; ownership reconciliation is required before dispatch`);
+    return admission;
+}
+/** Only host approval/reconciliation callers hold this service; reads never call it. */
+export function admitWork(db, input, metadataRepair = false) {
+    if (!input.approvalId || !input.scopeRevision || !input.provenance.reason || !(input.provenance.userTurn || input.provenance.decisionId || input.provenance.approvedPlanDigest))
+        throw new Error("Work admission requires explicit authorization provenance and requirements revision");
+    if (input.kind === "ticket" && (!input.ticketId || input.workId && input.workId !== input.ticketId || input.ticketId.startsWith("synthetic:")))
+        throw new Error("Ticket work identity is invalid");
+    const workId = input.kind === "ticket" ? input.ticketId : input.workId ?? `synthetic:${randomUUID()}`;
+    if (input.kind === "synthetic" && !/^synthetic:[a-f0-9-]{36}$/.test(workId))
+        throw new Error("Synthetic work requires a persisted opaque identity");
+    const requirementsDigest = qaDigest("admitted-requirements", input.definition);
+    return db.transaction(() => {
+        const prior = admittedWork(db, input.runId, workId);
+        if (prior?.requirementsDigest === requirementsDigest && prior.scopeRevision === input.scopeRevision)
+            return prior;
+        const run = db.prepare("SELECT status FROM workflow_runs WHERE run_id=?").get(input.runId);
+        if (!run || !metadataRepair && ["completed", "cancelled", "superseded"].includes(run.status))
+            throw new Error("Admission requires a nonterminal build");
+        const quarantined = db.prepare("SELECT state FROM build_work_scope WHERE run_id=? AND work_id=?").get(input.runId, workId);
+        if (quarantined?.state === "quarantined")
+            throw new Error("Historical work requires audited ownership reconciliation before admission");
+        db.prepare("INSERT OR IGNORE INTO build_work_scope VALUES(?,?,?,?, 'admitted',?)").run(input.runId, workId, input.kind, input.ticketId ?? null, JSON.stringify(input.definition));
+        const definitionBytes = Buffer.from(JSON.stringify(input.definition));
+        const definitionDigest = createHash("sha256").update(definitionBytes).digest("hex");
+        db.prepare("INSERT OR IGNORE INTO content_refs VALUES(?,'qa',?,?)").run(definitionDigest, definitionBytes, new Date().toISOString());
+        db.prepare("UPDATE build_work_scope SET definition_json=? WHERE run_id=? AND work_id=?").run(JSON.stringify(input.definition), input.runId, workId);
+        const projectId = db.prepare("SELECT project_id FROM build_project_identity").get().project_id;
+        const record = { version: 1, projectId, runId: input.runId, workId, kind: input.kind, ...(input.ticketId ? { ticketId: input.ticketId } : {}), assignmentId: randomUUID(), approvalId: input.approvalId, scopeRevision: input.scopeRevision, requirementsDigest, definitionDigest, admittedAt: new Date().toISOString(), admittedSequence: 0, provenance: input.provenance };
+        // Reserve sequence explicitly so immutable JSON and its ordinal agree.
+        record.admittedSequence = db.prepare("SELECT COALESCE(MAX(sequence),0)+1 AS n FROM build_work_admissions").get().n;
+        const validation = validateBuildWorkAdmissionV1(record);
+        if (!validation.valid)
+            throw new Error(`Invalid work admission: ${validation.errors.join("; ")}`);
+        db.prepare("INSERT INTO build_work_admissions VALUES(?,?,?,?,?,?,?,?,?,?)").run(record.admittedSequence, randomUUID(), record.runId, workId, record.assignmentId, record.approvalId, record.scopeRevision, requirementsDigest, JSON.stringify(record), record.admittedAt);
+        const snapshot = db.prepare("SELECT state_json FROM workflow_runs WHERE run_id=?").get(input.runId);
+        const state = JSON.parse(snapshot.state_json);
+        if (metadataRepair && !Array.isArray(state.tickets))
+            state.tickets = [];
+        if ((metadataRepair || state.version !== undefined) && Array.isArray(state.tickets) && !state.tickets.includes(workId)) {
+            state.tickets.push(workId);
+            db.prepare("UPDATE workflow_runs SET state_json=? WHERE run_id=?").run(JSON.stringify(state), input.runId);
+        }
+        return record;
+    }).immediate();
+}

package/dist/buildWorkAuthorization.d.ts

@@ -0,0 +1,2 @@
+/** Called by the CLI only after its source-bound approval gate succeeds. */
+export declare function admitApprovedTicket(projectDir: string, runId: string, ticketId: string, approvedRevision: string, authorization: string): void;