ai-foreman 1.7.25 → 1.7.26

package/dist/qaBuilderActivation.js

@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { assertBuildAssignmentReconciled, captureBuildSource } from "./buildAssignment.js";
+import { HandoffService, HandoffRecoveryPausedError } from "./handoffs.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { providerSessionKey } from "./sessionIdentity.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { WorkflowDb } from "./workflowDb.js";
+/** QA-only startup must not replace Builder ownership. Activate a Builder only
+ * at an authorized work boundary, through the ordinary validated handoff. */
+export async function activateQaRecoveryBuilder(input) {
+    const inspect = () => {
+        const db = new WorkflowDb(input.projectDir);
+        try {
+            const lease = db.currentLease();
+            if (lease?.runId !== input.runId || lease.pid !== process.pid)
+                throw new Error("Builder activation requires the current build execution lease");
+            const run = db.getRun(input.runId)?.state;
+            if (!run?.tickets.includes(input.ticketId) || run.progress.completedTickets.includes(input.ticketId))
+                throw new Error("QA recovery cannot activate Builder work outside unfinished approved scope");
+            const admission = db.assertAdmittedWork(input.runId, input.ticketId);
+            const definition = loadTickets(resolveTicketPaths(loadTicketsConfig(input.projectDir), input.projectDir).tickets).find(ticket => ticket.id === input.ticketId);
+            if (!definition || qaDigest("admitted-requirements", definition) !== admission.requirementsDigest)
+                throw new Error("Builder recovery requirements changed; renew scope approval before implementation");
+            if (!run.builder || qaDigest("builder-settings", run.builder.settings) !== qaDigest("builder-settings", input.settings))
+                throw new Error("QA recovery cannot replace the saved Builder settings");
+            if (input.expectedCapabilities && qaDigest("builder-capabilities", run.builderCapabilities) !== qaDigest("builder-capabilities", input.expectedCapabilities))
+                throw new Error("Builder capability approval changed before recovery activation");
+            if (db.unresolvedRoleDispatches(input.runId, "builder").length)
+                throw new Error("Reconcile unknown Builder dispatch before activating another session");
+            assertBuildAssignmentReconciled(input.projectDir, input.runId, input.worktree);
+            const owner = db.roleMutationLease(input.runId, "builder");
+            const ref = owner?.sessionRef;
+            if (!owner || !Number.isSafeInteger(owner.generation) || owner.generation < 0 || !ref || ref.version !== 1 || ref.role !== "builder" || ref.stream !== "builder"
+                || !Number.isSafeInteger(ref.generation) || ref.generation < 0 || ref.sessionId !== owner.providerSessionId
+                || ref.source !== "observed" || !ref.validatedAt || Number.isNaN(Date.parse(ref.validatedAt)) || providerSessionKey(ref) !== owner.sessionKey
+                || realpathSync(ref.cwd) !== realpathSync(input.worktree) || realpathSync(ref.configRoot) !== realpathSync(input.projectDir))
+                throw new Error("QA recovery has no validated Builder owner for this worktree");
+            const branchSession = db.branchResumeSessions(false).find(session => session.ticket === input.ticketId && realpathSync(session.worktreePath) === realpathSync(input.worktree));
+            const branch = branchSession?.branch ?? (realpathSync(run.repository.worktree) === realpathSync(input.worktree) ? run.repository.branch : undefined);
+            if (!branch || execFileSync("git", ["branch", "--show-current"], { cwd: input.worktree, encoding: "utf8" }).trim() !== branch)
+                throw new Error("Return to the approved Builder worktree branch before recovery activation");
+            const head = db.continuityHead(input.runId, "builder");
+            if (!head || head.state !== "current" || !db.latestContinuityCheckpoint(input.runId, "builder"))
+                throw new Error("Builder continuity needs reconstruction before QA can request implementation");
+            return { owner, ref, head, source: captureBuildSource(input.worktree), requirementsDigest: admission.requirementsDigest,
+                capabilitiesDigest: qaDigest("builder-capabilities", run.builderCapabilities), compactionCount: db.successfulCompactionCount(input.runId, "builder", ref) };
+        }
+        finally {
+            db.close();
+        }
+    };
+    const before = inspect();
+    const currentRef = input.adapter.sessionRef?.();
+    if (currentRef && providerSessionKey(currentRef) === before.owner.sessionKey && currentRef.generation === before.ref.generation
+        && currentRef.role === "builder" && currentRef.stream === "builder" && realpathSync(currentRef.configRoot) === realpathSync(input.projectDir)
+        && currentRef.source === "observed" && currentRef.validatedAt)
+        return input.adapter;
+    const assertPreparedState = (current) => {
+        if (current.owner.generation !== before.owner.generation || current.owner.sessionKey !== before.owner.sessionKey
+            || current.head.digest !== before.head.digest || current.source.digest !== before.source.digest || current.capabilitiesDigest !== before.capabilitiesDigest)
+            throw new Error("Builder recovery state changed while preparing its handoff; inspect and retry");
+    };
+    const transfer = await new HandoffService(input.projectDir).transfer({
+        runId: input.runId, role: "builder", reason: "Authorized Builder work after QA-only recovery requires a validated Builder owner",
+        predecessorSessionId: before.ref.sessionId, predecessorSessionRef: before.ref,
+        compactionCount: before.compactionCount, compactMaximum: input.settings.compact_maximum ?? 10,
+        roleState: { ticketId: input.ticketId, requirementsDigest: before.requirementsDigest, sourceDigest: before.source.digest,
+            capabilitiesDigest: before.capabilitiesDigest, recovery: "qa-builder-activation", providerReplayAuthorized: false },
+        resources: [{ label: "frozen-action", content: input.frozenAction, authoritative: true, purpose: "Approved QA remediation or guidance action; no replay of historical work" }],
+    }, async (handoff, runtime) => {
+        assertPreparedState(inspect());
+        const successor = await input.createSuccessor(handoff, runtime);
+        try {
+            assertPreparedState(inspect());
+        }
+        catch (error) {
+            await successor.close().catch(() => { });
+            throw error;
+        }
+        return successor;
+    }, input.recovery);
+    let owned;
+    try {
+        owned = await input.wrap(transfer.successor);
+    }
+    catch (error) {
+        let drainError;
+        try {
+            await transfer.successor.close();
+        }
+        catch (failure) {
+            drainError = failure;
+        }
+        throw new HandoffRecoveryPausedError(input.runId, transfer.manifest.generation, `Builder handoff was accepted but could not install its execution wrapper: ${String(error)}.${drainError ? ` The accepted session also needs cleanup: ${String(drainError)}.` : " The accepted session was closed without implementation."} The recorded accepted owner is preserved; inspect this build with rafi resume before continuing.`);
+    }
+    try {
+        await input.adapter.close();
+    }
+    catch (error) {
+        let drainError;
+        try {
+            await owned.close();
+        }
+        catch (failure) {
+            drainError = failure;
+        }
+        throw new HandoffRecoveryPausedError(input.runId, transfer.manifest.generation, `Builder handoff was accepted, but the unused startup session could not close: ${String(error)}.${drainError ? ` The accepted session also needs cleanup: ${String(drainError)}.` : " The accepted session was closed without implementation."} Ownership remains with the recorded accepted session; reconcile cleanup with rafi resume before continuing.`);
+    }
+    return owned;
+}

package/dist/qaFailureDelivery.js

@@ -372,7 +372,7 @@ export class QaFailureDeliveryService {
                     Object.assign(record, { providerInstructionDigest: db.putEvidence("handoff", Buffer.from(turn.providerInstruction)), providerInstructionBytes: Buffer.byteLength(turn.providerInstruction), providerInstructionAvailability: "captured" });
             }
             record.eventEvidenceDigest = db.putEvidence("qa", Buffer.from(canonicalEvidence(events)));
-            record.toolCount = events.filter(e => e.kind === "tool" || e.kind === "provider-item" && !["agentMessage", "reasoning", "userMessage", "contextCompaction"].includes(e.itemType)).length;
+            record.toolCount = events.filter(e => e.kind === "tool" || e.kind === "provider-item" && !["text", "agentMessage", "reasoning", "userMessage", "contextCompaction"].includes(e.itemType)).length;
             record.terminalCount = events.filter(e => e.kind === "turn-complete").length;
             db.recordQaDeliveryTurn(record);
             this.faults.afterResponseStored?.();

package/dist/qaRecovery.js

@@ -426,9 +426,10 @@ export function materializeQaRecoveryContext(packet, qaWorktree) {
         } };
 }
 export function renderQaRecoveryAcknowledgementInstruction(packet, relativePath) {
-    const required = packet.manifest.resources.filter((resource) => resource.requiredForRecovery).map((resource) => `- path=${resource.path} purpose=${JSON.stringify(resource.purpose)} media_type=${resource.mediaType} bytes=${resource.bytes} digest=${resource.digest}`).join("\n");
+    const required = packet.manifest.resources.filter((resource) => resource.requiredForRecovery).map((resource) => `- read_path=${join(relativePath, resource.path)} packet_path=${resource.path} purpose=${JSON.stringify(resource.purpose)} media_type=${resource.mediaType} bytes=${resource.bytes} digest=${resource.digest}`).join("\n");
     return [
         "Read and verify every required recovery resource in this exact sealed packet revision before replying.",
+        "Use each exact read_path below within the current QA working directory. The normal read-only QA permissions apply; preserve the sealed packet and source.",
         `Recovery context directory: ${relativePath}`,
         `Packet ID: ${packet.manifest.packetId}`,
         `Packet revision: ${packet.manifest.revision}`,

package/dist/qaReview.d.ts

@@ -208,6 +208,10 @@ export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<Isolated
 export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[], changeSummary?: unknown, history?: QaReportHistoryEntry[]): string;
 export declare function compactWithRetry(adapter: BuilderAdapter): Promise<CompactResult>;
 export declare const QA_REPORT_RECOVERY_MENU: readonly ["Try a complete fresh QA review.", "Manually fix saved JSON for human inspection.", "Give QA specific instructions for a fresh review.", "Pause."];
+/** Shared invariant for host staging and the actual QA boundary receipt. */
+export declare function assertQaRecoveryHandoffInventory(resources: ReadonlyArray<{
+    label: string;
+}>): void;
 export declare function beginQaFinalization(projectDir: string, sourceWorktree: string, runId: string, ticketId: string, certificateId: string, expectedSourceStateDigest: string, consumer: string, allowedProjectionPaths?: string[]): Promise<void>;
 export declare function verifyPendingQaFinalizationSource(projectDir: string, sourceWorktree: string, runId: string, ticketId: string, allowProjection?: boolean, projectionOperationId?: string): Promise<void>;
 export declare function completeQaFinalization(projectDir: string, runId: string, ticketId: string): void;

package/dist/qaReview.js

@@ -200,8 +200,10 @@ async function runIsolatedQaOwned(opts) {
         if (protocolHead.state === "source-frozen" || protocolHead.state === "review-ready") {
             protocolHead = scopeDb.transitionQa(opts.recovery.runId, opts.ticket.id, protocolHead.revision, { type: "operator-menu" });
         }
-        if (opts.resumedRecovery && protocolHead.state === "recheck-required" && opts.resumedRecovery.manifest.pendingAction !== "qa-full-review") {
+        if (opts.resumedRecovery && protocolHead.state === "recheck-required") {
             opts.resumedRecovery = updateQaRecoveryPosition(opts.resumedRecovery, "qa-full-review", opts.resumedRecovery.manifest.correctionTurns, "qa-full-review");
+            if (scopeDb.hasConfirmedQaRemediationForRecheck(opts.recovery.runId, opts.ticket.id))
+                opts.resumedRecovery = undefined;
         }
         durableReviews = scopeDb.qaReviewAttempts(opts.recovery.runId, opts.ticket.id);
         for (const interrupted of durableReviews.filter((item) => item.status === "started"))
@@ -324,6 +326,8 @@ async function runIsolatedQaOwned(opts) {
         opts.qaRemediationAuthorization = undefined;
         if (!fix.ok)
             return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA remediation failed during restart recovery", fix.outcome === "needs-input" ? "needs-human" : "blocked");
+        if (!consumeRecoveryAfterOwnedFix(opts))
+            return pauseQaProtocol(opts, "builder-remediation-unconfirmed", "Builder remediation needs durable reconciliation before a fresh review", "needs-human");
         const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? "Builder reported remediation complete");
         opts.state.builderResponseHistory.push({ ticketId: opts.ticket.id, cycle: durableReport.reviewNumber, kind: "remediation", response: fix.response, summary: fixSummary });
         opts.builderSummary = fix.response;
@@ -387,6 +391,8 @@ async function runIsolatedQaOwned(opts) {
             opts.qaRemediationAuthorization = undefined;
             if (!fix.ok)
                 return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA fix failed", fix.outcome === "needs-input" ? "needs-human" : "blocked");
+            if (!consumeRecoveryAfterOwnedFix(opts))
+                return pauseQaProtocol(opts, "builder-remediation-unconfirmed", "Builder remediation needs durable reconciliation before a fresh review", "needs-human");
             const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? fix.detail ?? "Builder reported remediation complete");
             opts.state.builderResponseHistory.push({
                 ticketId: opts.ticket.id,
@@ -1367,6 +1373,22 @@ function markQaRecoveryResolved(opts) {
         db.close();
     }
 }
+function consumeRecoveryAfterOwnedFix(opts) {
+    if (!opts.resumedRecovery)
+        return true;
+    const db = new WorkflowDb(opts.recovery.projectDir);
+    try {
+        if (!db.hasConfirmedQaRemediationForRecheck(opts.recovery.runId, opts.ticket.id))
+            return false;
+        // The validated report led to confirmed source-changing implementation.
+        // Its recovery packet remains durable history, not the next review basis.
+        opts.resumedRecovery = undefined;
+        return true;
+    }
+    finally {
+        db.close();
+    }
+}
 function markQaRecoveryPendingBuilder(opts) {
     markQaRecoveryAction(opts, "builder-remediation-pending");
 }
@@ -1542,10 +1564,7 @@ function validateBoundaryReceipt(receipt, packet, successorHandle) {
         || resource.authoritative !== true || typeof resource.requiredForRecovery !== "boolean")) {
         throw new Error("QA recovery acceptance receipt contains invalid resource metadata");
     }
-    for (const required of ["continuity-checkpoint", "authoritative-run-state", "frozen-qa-action"]) {
-        if (!receipt.resources.some((resource) => resource.label === required))
-            throw new Error(`QA recovery acceptance receipt is missing ${required}`);
-    }
+    assertQaRecoveryHandoffInventory(receipt.resources);
     if (receipt.inventoryDigest !== qaDigest("handoff-inventory", receipt.resources))
         throw new Error("QA recovery acceptance receipt inventory digest mismatch");
     const receiptDb = new WorkflowDb(packet.projectDir);
@@ -1566,6 +1585,13 @@ function validateBoundaryReceipt(receipt, packet, successorHandle) {
         }
     }
 }
+/** Shared invariant for host staging and the actual QA boundary receipt. */
+export function assertQaRecoveryHandoffInventory(resources) {
+    for (const required of ["continuity-checkpoint", "authoritative-run-state", "frozen-qa-action"]) {
+        if (!resources.some(resource => resource.label === required))
+            throw new Error(`QA recovery acceptance receipt is missing ${required}`);
+    }
+}
 function effectiveTurnText(turn) { return turn.cleanedResponse ?? turn.text; }
 const qaTurnBindings = new WeakMap();
 function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle, attempt) {
@@ -1769,8 +1795,12 @@ async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
     }
     let result;
     const providerStartedAt = Date.now();
+    // Reading the sealed QA packet is ordinary confined read-only QA work.
+    // Only formatting repair and ownership acceptance are response-only; the
+    // first resource-inspection turn cannot truthfully read with tools disabled.
+    const responseRepair = slot?.includes("correction") || (slot?.includes("acknowledgement") && slot.includes("repair"));
     try {
-        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : slot?.includes("acknowledgement") || slot?.includes("correction") ? { purpose: "response-repair", responseOnly: true } : undefined);
+        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : responseRepair ? { purpose: "response-repair", responseOnly: true } : undefined);
     }
     catch (error) {
         const failedDb = new WorkflowDb(binding.projectDir);
@@ -1827,7 +1857,7 @@ async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
         throw new Error(detail);
     }
     const completedAt = new Date().toISOString();
-    const terminalEventObserved = Boolean(result.turnId
+    const terminalEventObserved = Boolean(result.turnId && result.failure?.dispatchState !== "unknown"
         && events.some((event) => event.kind === "turn-complete" && (event.turnId ?? event.result.turnId) === result.turnId));
     const receiptDb = new WorkflowDb(binding.projectDir);
     try {

package/dist/sessionLifecycle.js

@@ -768,7 +768,7 @@ export class ThresholdCompactionController {
     handoffGeneration() {
         const db = new WorkflowDb(this.options.projectDir);
         try {
-            return db.handoffs(this.options.runId).at(-1)?.generation ?? 0;
+            return db.roleMutationLease(this.options.runId, this.options.role)?.generation ?? 0;
         }
         finally {
             db.close();

package/dist/supervisedStart.js

@@ -3,8 +3,10 @@ import { fileURLToPath } from "node:url";
 import { execFileSync, spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
+import { hostname } from "node:os";
 import { DurableSupervisor } from "./supervisor.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { processStartIdentity } from "./processIdentity.js";
 import { cancelOwnedRuntimeProbes } from "./runtimeReadiness.js";
 /** Worker IPC is created by the parent; an environment flag alone cannot bypass supervision. */
 export function supervisedRunId() {
@@ -174,6 +176,12 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                     return;
                 try {
                     db.acknowledgeBuildLaunchChild(authority, launch.token, child.pid);
+                    // Record the incarnation before acknowledging the blocked launch gate.
+                    // Any persistence failure follows the existing owned-child cleanup.
+                    db.transitionSupervisor(runId, generation, {
+                        checkpoint: db.getRun(runId)?.checkpoint ?? "preparing", event: "worker_started",
+                        payload: { workerPid: child.pid, processStart: processStartIdentity(child.pid), host: hostname(), generation },
+                    });
                     child.send("rafi-launch-ack", () => { });
                     clearTimeout(startup);
                 }
@@ -228,12 +236,18 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             const result = new Promise(resolve => {
                 child.once("error", error => {
                     clearInterval(watchdog);
+                    exitCode = 1;
                     if (child.pid) {
                         stop();
                         return;
                     } // exit handler owns cleanup and settlement
-                    db.failBuildLaunch(authority, launch.token);
-                    resolve({ kind: "failed", detail: error.message });
+                    try {
+                        db.failBuildLaunch(authority, launch.token);
+                        resolve({ kind: "failed", detail: error.message });
+                    }
+                    catch (failure) {
+                        resolve({ kind: "failed", detail: `${error.message}; launch reconciliation failed: ${String(failure)}` });
+                    }
                 });
                 child.once("exit", async (code, signal) => {
                     clearInterval(watchdog);
@@ -309,7 +323,13 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     process.once("SIGINT", stopInt);
     process.once("SIGTERM", stopTerm);
     try {
-        await supervisor.run();
+        const outcome = await supervisor.run();
+        if (outcome.kind === "failed") {
+            exitCode ||= 1;
+            console.error(`rafi: ${outcome.detail}`);
+        }
+        else if (outcome.kind === "waiting_for_human")
+            exitCode ||= 2;
     }
     finally {
         process.off("SIGINT", stopInt);

package/dist/supervisor.js

@@ -80,6 +80,8 @@ export class DurableSupervisor {
                 if (pending.some(decision => !this.options.policy.continueIndependentTickets || !decision.interruptionId.startsWith("ticket:"))) {
                     state = { ...state, status: "waiting_for_human", workerPid: undefined, heartbeatAt: this.now().toISOString() };
                     saveState();
+                    if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: "paused", checkpoint: "waiting-for-human", event: "worker_waiting_for_human" });
                     return { kind: "waiting_for_human" };
                 }
                 const checkpoint = this.options.checkpoint();
@@ -94,6 +96,19 @@ export class DurableSupervisor {
                 this.active = undefined;
                 state = { ...state, workerPid: undefined, heartbeatAt: this.now().toISOString() };
                 if (outcome.kind !== "crashed") {
+                    if (outcome.kind === "failed" && db.getRun(this.options.runId)?.status === "running") {
+                        const eligibility = db.preparationEligibility(this.options.runId);
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: eligibility.eligible ? "failed" : "paused",
+                            checkpoint: eligibility.eligible ? "worker-failed" : "worker-reconciliation-required",
+                            event: "worker_exit_recorded", payload: { detail: outcome.detail, reasons: eligibility.reasons },
+                        });
+                    }
+                    else if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: "paused", checkpoint: outcome.kind === "waiting_for_human" && db.pendingHumanDecisions(this.options.runId).length ? "waiting-for-human" : "worker-exited-before-checkpoint",
+                            event: "worker_exit_recorded", payload: { outcome: outcome.kind },
+                        });
                     const status = outcome.kind === "completed" ? "stopped" : outcome.kind === "waiting_for_human" ? "waiting_for_human" : outcome.kind === "failed" ? "failed" : "stopped";
                     state = { ...state, status };
                     saveState();
@@ -111,6 +126,10 @@ export class DurableSupervisor {
                 if (state.checkpointRestarts >= checkpointLimit || state.runRestarts >= runLimit) {
                     state = { ...state, status: "failed" };
                     saveState();
+                    if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: "failed", checkpoint: "worker-restart-budget-exhausted", event: "worker_restart_budget_exhausted", payload: { checkpoint, detail: outcome.detail },
+                        });
                     return { kind: "failed", detail: `worker restart budget exhausted at ${checkpoint}: ${outcome.detail}` };
                 }
                 state = { ...state, checkpointRestarts: state.checkpointRestarts + 1, runRestarts: state.runRestarts + 1 };
@@ -118,9 +137,23 @@ export class DurableSupervisor {
                 await this.sleep(Math.min(10_000, 250 * (2 ** Math.min(5, state.checkpointRestarts - 1))));
             }
             state = { ...state, status: "stopped", stopRequestedAt: this.now().toISOString(), workerPid: undefined };
+            if (db.getRun(this.options.runId)?.status === "running")
+                db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: "paused", checkpoint: "worker-stopped", event: "supervisor_stop_recorded" });
             saveState();
             return { kind: "stopped" };
         }
+        catch (error) {
+            state = { ...state, status: "failed", workerPid: undefined, heartbeatAt: this.now().toISOString() };
+            saveState();
+            if (db.getRun(this.options.runId)?.status === "running") {
+                const eligibility = db.preparationEligibility(this.options.runId);
+                db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: eligibility.eligible ? "failed" : "paused",
+                    checkpoint: eligibility.eligible ? "worker-launch-failed" : "worker-reconciliation-required", event: "worker_launch_failed",
+                    payload: { detail: String(error), reasons: eligibility.reasons },
+                });
+            }
+            throw error;
+        }
         finally {
             clearInterval(heartbeat);
             try {

package/dist/tickets/groupReset.js

@@ -94,107 +94,111 @@ export function resolveTicketResetSelection(projectDir, requested, options = {},
 }
 export function applyResolvedTicketReset(projectDir, selection, actor = "user", now = new Date(), hooks = {}) {
     const opened = open(projectDir);
-    const { config, paths, definitions, db } = opened;
-    const workflow = new WorkflowDb(projectDir);
-    const resetId = hooks.resetId ?? randomUUID();
-    const current = new Map(definitions.map((definition) => [definition.id, definition]));
-    const groupCatalog = db.listTicketGroups();
-    const snapshots = new Map(groupCatalog.flatMap((group) => group.members.map((member) => [member.ticketId, member.snapshot])));
-    const states = db.getAllStates();
-    const selectedIds = new Set(selection.ticketIds);
-    const currentRelatedRuns = recoverableBuildRuns(projectDir, now)
-        .filter((run) => run.tickets.some((ticketId) => selectedIds.has(ticketId)))
-        .map((run) => ({ runId: run.runId, status: run.status, tickets: [...run.tickets] }));
-    const comparable = { ...selection, relatedRuns: currentRelatedRuns };
-    delete comparable.inputFingerprint;
-    const actualFingerprint = selectionFingerprint(comparable, current, states, snapshots, groupCatalog);
-    if (actualFingerprint !== selection.inputFingerprint) {
-        db.close();
-        workflow.close();
-        throw new Error("ticket/group/reset inputs changed after preview; no reset was applied—preview the exact selection again");
-    }
-    const restore = selection.definitionRestorations.filter((item) => item.restore);
-    const restored = restore.map((item) => item.ticketId);
-    const restoredSet = new Set(restored);
-    const restoredDefinitions = restore.map((item) => snapshots.get(item.ticketId)?.definition);
-    if (restoredDefinitions.some((item) => !item)) {
-        db.close();
-        workflow.close();
-        throw new Error("a selected definition snapshot became unavailable");
-    }
-    const nextDefinitions = [...definitions, ...restoredDefinitions.filter((definition) => !current.has(definition.id))].sort((a, b) => a.order - b.order);
-    const definitionIssues = validateTicketDefs(nextDefinitions);
-    if (definitionIssues.length) {
-        db.close();
-        workflow.close();
-        throw new Error(`restored ticket definitions are invalid: ${definitionIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
-    }
-    const resettable = selection.ticketIds.filter((ticketId) => current.has(ticketId) || restoredSet.has(ticketId));
-    const ignoredMissing = selection.ticketIds.filter((ticketId) => !current.has(ticketId) && !restoredSet.has(ticketId));
-    if (resettable.length === 0 && restored.length === 0) {
-        db.close();
-        workflow.close();
-        return { resetId, tickets: [], restored: [], ignoredMissing };
-    }
-    const stageDir = join(projectDir, ".rafi", "reset-stage", resetId);
-    const stagedDefinitions = join(stageDir, "tickets.yaml");
-    const stagedProgress = join(stageDir, "progress.md");
-    const definitionsBefore = existsSync(paths.tickets) ? readFileSync(paths.tickets) : undefined;
-    const progressBefore = existsSync(paths.progressDoc) ? readFileSync(paths.progressDoc) : undefined;
-    const oldStates = new Map([...new Set([...resettable, ...restored])].map((ticketId) => [ticketId, db.getState(ticketId)]));
-    const oldRecent = db.getRecentCompleted().filter((row) => resettable.includes(row.ticket_id));
-    const eventIds = [];
-    const run = workflow.createRun({ kind: "recovery", checkpoint: "group-reset-intent", originalWork: selection, remainingWork: { tickets: resettable }, state: { resetId } }, now);
-    const publication = workflow.beginPublication(run.runId, { operation: "group-ticket-reset", resetId, selection, stagedDefinitions, stagedProgress, definitionsTarget: paths.tickets, progressTarget: paths.progressDoc }, { definitions: digest(definitionsBefore), progress: digest(progressBefore) }, now);
+    const { config, paths, db } = opened;
+    let workflowHandle;
     try {
-        const stamp = now.toISOString();
-        db.transaction(() => {
-            for (const definition of restoredDefinitions)
-                if (!db.getState(definition.id))
-                    db.upsertState(definition.id, pristineTicketState(definition.id, stamp, actor), stamp);
-            for (const row of selection.previewRows) {
-                if (!resettable.includes(row.ticketId)) {
-                    eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset_skipped_missing", old_status: row.status, new_status: row.status, summary: `Skipped missing definition ${row.ticketId}`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, input_fingerprint: selection.inputFingerprint }) }));
-                    continue;
-                }
-                const old = db.getState(row.ticketId)?.status ?? row.status;
-                db.upsertState(row.ticketId, pristineTicketState(row.ticketId, stamp, actor), stamp);
-                db.deleteRecentCompleted(row.ticketId);
-                eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset", old_status: old, new_status: "planned", summary: `Reset ${row.ticketId} from approved immutable selection`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, groups: selection.groups.map((group) => group.id), restored_definition: restoredSet.has(row.ticketId), input_fingerprint: selection.inputFingerprint }) }));
+        const workflow = workflowHandle = new WorkflowDb(projectDir);
+        const resetId = hooks.resetId ?? randomUUID();
+        return workflow.withTrackerMutationAuthority(() => {
+            const definitions = loadTickets(paths.tickets);
+            const current = new Map(definitions.map((definition) => [definition.id, definition]));
+            const groupCatalog = db.listTicketGroups();
+            const snapshots = new Map(groupCatalog.flatMap((group) => group.members.map((member) => [member.ticketId, member.snapshot])));
+            const states = db.getAllStates();
+            const selectedIds = new Set(selection.ticketIds);
+            const currentRelatedRuns = recoverableBuildRuns(projectDir, now)
+                .filter((run) => run.tickets.some((ticketId) => selectedIds.has(ticketId)))
+                .map((run) => ({ runId: run.runId, status: run.status, tickets: [...run.tickets] }));
+            const comparable = { ...selection, relatedRuns: currentRelatedRuns };
+            delete comparable.inputFingerprint;
+            const actualFingerprint = selectionFingerprint(comparable, current, states, snapshots, groupCatalog);
+            if (actualFingerprint !== selection.inputFingerprint) {
+                throw new Error("ticket/group/reset inputs changed after preview; no reset was applied—preview the exact selection again");
+            }
+            const restore = selection.definitionRestorations.filter((item) => item.restore);
+            const restored = restore.map((item) => item.ticketId);
+            const restoredSet = new Set(restored);
+            const restoredDefinitions = restore.map((item) => snapshots.get(item.ticketId)?.definition);
+            if (restoredDefinitions.some((item) => !item)) {
+                throw new Error("a selected definition snapshot became unavailable");
+            }
+            const nextDefinitions = [...definitions, ...restoredDefinitions.filter((definition) => !current.has(definition.id))].sort((a, b) => a.order - b.order);
+            const definitionIssues = validateTicketDefs(nextDefinitions);
+            if (definitionIssues.length) {
+                throw new Error(`restored ticket definitions are invalid: ${definitionIssues.map((issue) => `${issue.path}: ${issue.message}`).join("; ")}`);
+            }
+            const resettable = selection.ticketIds.filter((ticketId) => current.has(ticketId) || restoredSet.has(ticketId));
+            const ignoredMissing = selection.ticketIds.filter((ticketId) => !current.has(ticketId) && !restoredSet.has(ticketId));
+            if (resettable.length === 0 && restored.length === 0) {
+                return { resetId, tickets: [], restored: [], ignoredMissing };
+            }
+            const stageDir = join(projectDir, ".rafi", "reset-stage", resetId);
+            const stagedDefinitions = join(stageDir, "tickets.yaml");
+            const stagedProgress = join(stageDir, "progress.md");
+            const definitionsBefore = existsSync(paths.tickets) ? readFileSync(paths.tickets) : undefined;
+            const progressBefore = existsSync(paths.progressDoc) ? readFileSync(paths.progressDoc) : undefined;
+            const oldStates = new Map([...new Set([...resettable, ...restored])].map((ticketId) => [ticketId, db.getState(ticketId)]));
+            const oldRecent = db.getRecentCompleted().filter((row) => resettable.includes(row.ticket_id));
+            const eventIds = [];
+            const run = workflow.createRun({ kind: "recovery", checkpoint: "group-reset-intent", originalWork: selection, remainingWork: { tickets: resettable }, state: { resetId } }, now);
+            let publication;
+            try {
+                publication = workflow.beginPublication(run.runId, { operation: "group-ticket-reset", resetId, selection, stagedDefinitions, stagedProgress, definitionsTarget: paths.tickets, progressTarget: paths.progressDoc }, { definitions: digest(definitionsBefore), progress: digest(progressBefore) }, now);
+                const stamp = now.toISOString();
+                db.transaction(() => {
+                    for (const definition of restoredDefinitions)
+                        if (!db.getState(definition.id))
+                            db.upsertState(definition.id, pristineTicketState(definition.id, stamp, actor), stamp);
+                    for (const row of selection.previewRows) {
+                        if (!resettable.includes(row.ticketId)) {
+                            eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset_skipped_missing", old_status: row.status, new_status: row.status, summary: `Skipped missing definition ${row.ticketId}`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, input_fingerprint: selection.inputFingerprint }) }));
+                            continue;
+                        }
+                        const old = db.getState(row.ticketId)?.status ?? row.status;
+                        db.upsertState(row.ticketId, pristineTicketState(row.ticketId, stamp, actor), stamp);
+                        db.deleteRecentCompleted(row.ticketId);
+                        eventIds.push(db.insertEvent({ timestamp: stamp, actor, ticket_id: row.ticketId, event_type: "ticket_reset", old_status: old, new_status: "planned", summary: `Reset ${row.ticketId} from approved immutable selection`, validation: null, evidence: null, payload_json: JSON.stringify({ reset_id: resetId, groups: selection.groups.map((group) => group.id), restored_definition: restoredSet.has(row.ticketId), input_fingerprint: selection.inputFingerprint }) }));
+                    }
+                });
+                mkdirSync(stageDir, { recursive: true });
+                writeFileSync(stagedDefinitions, stringify({ tickets: nextDefinitions }, { lineWidth: 120 }), "utf8");
+                writeFileSync(stagedProgress, renderProgressDoc({ config, projectDir, ticketDefs: nextDefinitions, states: db.getAllStates(), db, now: stamp }), "utf8");
+                workflow.updatePublication(publication.transactionId, "staged", now);
+                workflow.updatePublication(publication.transactionId, "tracker_committed", now);
+                hooks.beforePublish?.();
+                atomicCopy(stagedDefinitions, paths.tickets);
+                writeProgressDoc(paths.progressDoc, readFileSync(stagedProgress, "utf8"), true);
+                workflow.updatePublication(publication.transactionId, "published", now);
+                workflow.updatePublication(publication.transactionId, "committed", now);
+                workflow.transition(run.runId, { status: "completed", checkpoint: "group-reset-committed", remainingWork: {}, state: { resetId, tickets: resettable, restored, ignoredMissing } }, now);
+                rmSync(stageDir, { recursive: true, force: true });
+                return { resetId, tickets: resettable, restored, ignoredMissing };
+            }
+            catch (error) {
+                db.transaction(() => {
+                    db.deleteEvents(eventIds);
+                    for (const [ticketId, state] of oldStates)
+                        state ? db.upsertState(ticketId, state, state.updated_at) : db.deleteState(ticketId);
+                    for (const row of oldRecent)
+                        db.upsertRecentCompleted(row);
+                });
+                restoreFile(paths.tickets, definitionsBefore);
+                restoreFile(paths.progressDoc, progressBefore);
+                if (publication)
+                    workflow.updatePublication(publication.transactionId, "rolled_back", now);
+                workflow.transition(run.runId, { status: "failed", checkpoint: "group-reset-rolled-back", state: { resetId, error: error instanceof Error ? error.message : String(error) } }, now);
+                rmSync(stageDir, { recursive: true, force: true });
+                throw error;
             }
         });
-        mkdirSync(stageDir, { recursive: true });
-        writeFileSync(stagedDefinitions, stringify({ tickets: nextDefinitions }, { lineWidth: 120 }), "utf8");
-        writeFileSync(stagedProgress, renderProgressDoc({ config, projectDir, ticketDefs: nextDefinitions, states: db.getAllStates(), db, now: stamp }), "utf8");
-        workflow.updatePublication(publication.transactionId, "staged", now);
-        workflow.updatePublication(publication.transactionId, "tracker_committed", now);
-        hooks.beforePublish?.();
-        atomicCopy(stagedDefinitions, paths.tickets);
-        writeProgressDoc(paths.progressDoc, readFileSync(stagedProgress, "utf8"), true);
-        workflow.updatePublication(publication.transactionId, "published", now);
-        workflow.updatePublication(publication.transactionId, "committed", now);
-        workflow.transition(run.runId, { status: "completed", checkpoint: "group-reset-committed", remainingWork: {}, state: { resetId, tickets: resettable, restored, ignoredMissing } }, now);
-        rmSync(stageDir, { recursive: true, force: true });
-        return { resetId, tickets: resettable, restored, ignoredMissing };
-    }
-    catch (error) {
-        db.transaction(() => {
-            db.deleteEvents(eventIds);
-            for (const [ticketId, state] of oldStates)
-                state ? db.upsertState(ticketId, state, state.updated_at) : db.deleteState(ticketId);
-            for (const row of oldRecent)
-                db.upsertRecentCompleted(row);
-        });
-        restoreFile(paths.tickets, definitionsBefore);
-        restoreFile(paths.progressDoc, progressBefore);
-        workflow.updatePublication(publication.transactionId, "rolled_back", now);
-        workflow.transition(run.runId, { status: "failed", checkpoint: "group-reset-rolled-back", state: { resetId, error: error instanceof Error ? error.message : String(error) } }, now);
-        rmSync(stageDir, { recursive: true, force: true });
-        throw error;
     }
     finally {
-        db.close();
-        workflow.close();
+        try {
+            workflowHandle?.close();
+        }
+        finally {
+            db.close();
+        }
     }
 }
 function selectGroups(groups, requested) {