ai-foreman 2.0.0 → 2.0.1

package/dist/adapters/claude.js

@@ -63,14 +63,15 @@ export function buildClaudeQueryOptions(opts, scratchDirectory = join(dirname(op
                 failIfUnavailable: true,
                 autoAllowBashIfSandboxed: true,
                 allowUnsandboxedCommands: false,
-                network: { allowedDomains: [], deniedDomains: ["*"] },
+                // QA stays offline unless the operator granted --qa-network for this build.
+                network: opts.networkAccess === true ? { allowedDomains: ["*"] } : { allowedDomains: [], deniedDomains: ["*"] },
                 filesystem: { allowWrite: [scratchDirectory], denyWrite: [opts.cwd, ...(opts.configRoot ? [opts.configRoot] : [])] },
             } } : {}),
     };
     const exactSkills = opts.preloadedSkillContent?.length
         ? ["# Preloaded Skills", "Use the following skills for this run.", ...opts.preloadedSkillContent.map((skill) => skill.content)].join("\n\n")
         : undefined;
-    const systemAppend = [handoffSystemInstructions(opts.sessionRole, opts.systemPromptAppend), opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${opts.networkAccess === true ? "explicitly approved for this build" : "disabled"}; sandbox fallback disabled. If acquisition requires unavailable access, request input first or use a provenance-verified local bundle. A ticket answer does not grant runtime permissions.` : undefined, exactSkills].filter((part) => Boolean(part)).join("\n\n");
+    const systemAppend = [handoffSystemInstructions(opts.sessionRole, opts.systemPromptAppend), opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${opts.networkAccess === true ? "explicitly approved for this build" : "disabled"}; sandbox fallback disabled. If acquisition requires unavailable access, request input first or use a provenance-verified local bundle. A ticket answer does not grant runtime permissions.` : undefined, opts.sessionRole === "qa" && opts.networkAccess === true ? "QA runtime contract: shell network explicitly approved for this review (--qa-network); you may run live checks against operator-provided local or remote services. Workspace stays read-only." : undefined, exactSkills].filter((part) => Boolean(part)).join("\n\n");
     if (systemAppend) {
         base.systemPrompt = { type: "preset", preset: "claude_code", append: systemAppend };
     }
@@ -1341,7 +1342,7 @@ export class ClaudeAdapter {
         pending.idleTimer.unref();
     }
     providerIdleTimeoutMs() {
-        const configured = this.opts.providerIdleTimeoutMs;
+        const configured = this.opts.providerIdleTimeoutMs ?? Number(process.env.RAFI_PROVIDER_IDLE_TIMEOUT_MS);
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
     }
     streamFailureResult(message, sessionUnavailable) {

package/dist/adapters/codex.d.ts

@@ -132,6 +132,8 @@ export declare class CodexAdapter implements BuilderAdapter {
     private traceLifecycle;
     private touchWaiters;
     private providerIdleTimeoutMs;
+    /** Read-only QA may reach the network only with the operator's --qa-network grant. */
+    private qaNetworkAccess;
     private effectiveNetworkAccess;
     private effectiveApprovalPolicy;
     /** Fail closed; approval is for this operation only, never a session cache or policy amendment. */

package/dist/adapters/codex.js

@@ -151,6 +151,7 @@ export class CodexAdapter {
     buildInstruction(instruction) {
         return [this.opts.systemPromptAppend,
             this.opts.sessionRole === "builder" ? `Builder runtime contract: shell network ${this.effectiveNetworkAccess() ? "explicitly approved for this build" : "disabled"}; sandbox escalation ${this.effectiveApprovalPolicy() === "on-request" ? "requires separate approval for each exact operation" : "disabled"}. Web tools do not establish shell network access. If acquisition needs unavailable capabilities, request input before running acquisition, or use a local source/dependency bundle with verified provenance. A ticket answer does not change runtime permissions.` : undefined,
+            this.qaNetworkAccess() ? "QA runtime contract: shell network explicitly approved for this review (--qa-network); you may run live checks against operator-provided local or remote services. Workspace stays read-only." : undefined,
             this.buildSkillsAppendix(), instruction]
             .filter((part) => Boolean(part)).join("\n\n");
     }
@@ -293,7 +294,7 @@ export class CodexAdapter {
                 ...(this.opts.fast ? { serviceTier: this.fastTier ?? "default" } : {}),
                 approvalPolicy: policy?.responseOnly || policy?.purpose && policy.purpose !== "implementation" ? "never" : this.effectiveApprovalPolicy(),
                 sandboxPolicy: readOnlyTurn
-                    ? { type: "readOnly", networkAccess: false }
+                    ? { type: "readOnly", networkAccess: this.qaNetworkAccess() }
                     : { type: "workspaceWrite", writableRoots: [this.opts.cwd], networkAccess: this.effectiveNetworkAccess() },
             };
             let started;
@@ -1090,9 +1091,13 @@ export class CodexAdapter {
                 waiter.touch?.();
     }
     providerIdleTimeoutMs() {
-        const configured = this.opts.providerIdleTimeoutMs;
+        const configured = this.opts.providerIdleTimeoutMs ?? Number(process.env.RAFI_PROVIDER_IDLE_TIMEOUT_MS);
         return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_PROVIDER_IDLE_TIMEOUT_MS;
     }
+    /** Read-only QA may reach the network only with the operator's --qa-network grant. */
+    qaNetworkAccess() {
+        return this.opts.sessionRole === "qa" && this.opts.networkAccess === true;
+    }
     effectiveNetworkAccess() {
         return this.opts.sandboxMode !== "read-only" && this.opts.sessionRole !== "qa" && this.opts.networkAccess === true;
     }

package/dist/branch/git.js

@@ -1,6 +1,7 @@
+import { ensureLocalGitExcludes } from "../gitExclude.js";
 import { invalidateGraphWorkspace } from "../graph/lifecycle.js";
 import { execFileSync } from "node:child_process";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { mkdirSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 export function runGit(cwd, args) {
     const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
@@ -41,13 +42,7 @@ export function ensureCleanBaseWorktree(cwd, opts = {}) {
     }
 }
 export function ensureForemanExcluded(cwd) {
-    const excludePath = join(cwd, ".git", "info", "exclude");
-    if (!existsSync(excludePath))
-        return;
-    const line = ".foreman/";
-    if (readFileSync(excludePath, "utf8").split(/\r?\n/).includes(line))
-        return;
-    appendFileSync(excludePath, `\n${line}\n`, "utf8");
+    ensureLocalGitExcludes(cwd, [".foreman/"], { leadingBlankLine: true });
 }
 export function createTicketWorktree(projectDir, runId, branch, base) {
     const worktreePath = join(projectDir, ".foreman", "worktrees", runId, branch.replace(/\//g, "__"));

package/dist/buildApproval.js

@@ -97,15 +97,9 @@ export function requiresBuildApproval(projectDir, ticketIds, explicitYes, conseq
     }
     if (scope.approved && !changedConsequences)
         return false;
-    if (!explicitYes)
-        return true;
-    const db = new WorkflowDb(projectDir);
-    try {
-        return db.completedPlanApprovals().length > 0;
-    }
-    finally {
-        db.close();
-    }
+    // --yes is the operator's standing approval for this invocation: it never
+    // stops to ask, even when the scope differs from the recorded plan approval.
+    return !explicitYes;
 }
 /** Bind decisions to current files so an old answer cannot approve a changed scope. */
 export function buildScopeRevision(projectDir, consequences) {

package/dist/buildRuns.d.ts

@@ -12,6 +12,7 @@ export interface CreateBuildRunInput {
     tickets: string[];
     authorizedBatch?: BuildRunRecordV2["authorizedBatch"];
     builderCapabilities?: BuildRunRecordV2["builderCapabilities"];
+    qaCapabilities?: BuildRunRecordV2["qaCapabilities"];
     deliveryUnit?: string;
     branchMode?: BuildRunRecordV2["branchMode"];
     repositoryRoot: string;

package/dist/buildRuns.js

@@ -6,7 +6,7 @@ import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import Database from "better-sqlite3";
-import { WorkflowDb, heartbeatCurrentWorkflowLease, readCurrentWorkflowLease } from "./workflowDb.js";
+import { WorkflowDb, heartbeatCurrentWorkflowLease, isNonBuildRunId, readCurrentWorkflowLease } from "./workflowDb.js";
 import { WorkflowReader } from "./workflowReader.js";
 import { canonicalSessionPath, captureWorkspaceIdentity, createProviderSessionRef, latestSessionBinding, upsertSessionBinding } from "./sessionIdentity.js";
 import { resolveProviderSessionAvailability } from "./sessionAvailability.js";
@@ -53,6 +53,7 @@ export function createBuildRun(input) {
         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,
+        qaCapabilities: input.qaCapabilities,
         deliveryUnit: input.deliveryUnit,
         branchMode: input.branchMode ?? "current",
         checkpoint: "created",
@@ -435,6 +436,10 @@ export function readBuildRuns(projectDir) {
             catch { /* authoritative DB state can repair an absent or partial projection */ }
         }
     for (const stored of workflow.buildRuns()) {
+        // Journal runs for agent calls outside a build were once stored with the
+        // build kind; they are never builds.
+        if (isNonBuildRunId(stored.runId))
+            continue;
         const value = stored.state;
         if (value?.runId)
             candidates.set(value.runId, value);

package/dist/cli/doctor.js

@@ -13,6 +13,7 @@ import { WorkflowReader } from "../workflowReader.js";
 import { WorkflowDb } from "../workflowDb.js";
 import { error, success, warning } from "../terminalStyle.js";
 import { readInterviewRecords } from "../interviews.js";
+import { checkRuntimeEnvironment } from "../runtimePreflight.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -50,7 +51,8 @@ export function buildDoctorCommand() {
         const warn = (label, detail) => {
             console.log(`${warning("--")} ${label}${detail ? ` — ${detail}` : ""}`);
         };
-        report(Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10) >= 20, "node >=20", process.version);
+        for (const check of checkRuntimeEnvironment())
+            report(check.ok, check.label, check.fix ? `${check.detail}; fix: ${check.fix}` : check.detail);
         report(Boolean(PACKAGE_VERSION), "foreman package version", PACKAGE_VERSION);
         report(existsSync(cwd), "project directory exists", cwd);
         if (!existsSync(cwd))

package/dist/cli/start.js

@@ -11,7 +11,7 @@ import { durableReadOnlyProposal } from "../readOnlyProposal.js";
 import { captureFrozenQaSource } from "../qaSnapshot.js";
 import { finishStartAdmission, superviseStart, supervisedRunId } from "../supervisedStart.js";
 import { assertBuildAssignmentReconciled, isInterruptedBuilderRecovery, assertInterruptedSourceSnapshot } from "../buildAssignment.js";
-import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, servicePendingHumanDecisions } from "../humanDecision.js";
+import { durableHumanDecision, HumanDecisionRequired, HumanDecisionCancelled, reusableCapabilityDecision, servicePendingHumanDecisions } from "../humanDecision.js";
 import { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate, validatePlanApprovalBinding, validateFrozenWorkApprovalBinding } from "../buildApproval.js";
 import { Command, Option } from "commander";
 import { accent, error, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
@@ -540,7 +540,7 @@ export function buildStartCommand(options = {}) {
         .option("--accept-handoff-role <role>", "role owning the pre-staged handoff (builder | qa)", "builder")
         .option("--continue", "resume the most recent logged session for this project")
         .option("-t, --tickets <path>", "path to ticket file (.md, .txt, .yaml, …) — passed to the builder as context")
-        .option("-y, --yes", "skip pre-flight confirmation prompt")
+        .option("-y, --yes", "never stop to ask: approve the pre-flight plan, plan updates, and capabilities requested by flag (--builder-network, --qa-network)")
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--fast", "use native fast mode when available; keep the model and reasoning settings")
         .option("--no-qa", "disable per-ticket QA review (enabled by default)")
@@ -565,13 +565,15 @@ export function buildStartCommand(options = {}) {
         .option("--auto-compact-threshold <percent>", "initial Builder context compaction threshold (1-99)")
         .option("--max-branch-depth <n>", "maximum selected branch stack depth", "5")
         .option("--pr-ready", "create ready-for-review PRs instead of draft PRs")
-        .option("--builder-network", "request build-scoped builder internet access with separate explicit approval; rechecked on resume")
+        .option("--builder-network", "request build-scoped builder internet access; asks for approval unless --yes; rechecked on resume")
+        .option("--qa-network", "allow independent QA network access for this build (e.g. live local services); asks for approval unless --yes; rechecked on resume")
         .option("--builder-approvals", "allow the builder to request explicit per-operation sandbox approvals; QA stays restricted")
         .option("--keep-worktrees", "keep successful ticket worktrees for inspection")
         .option("--dirty-work <mode>", "preserve | include: continue in isolated branches without merging into the dirty checkout")
         .option("--ticket <id>", "select one new ticket, or identify recovery tickets with --resume/--continue/--recover-run", collectTicket, [])
         .option("--skip-delivery-unit <id>", "skip one unfinished delivery unit for this run", collectTicket, [])
         .action(async (project, opts, command) => withBuildInvocation(async () => {
+        let waitingForDecision = false;
         try {
             validateStartOptions(opts, false);
         }
@@ -667,18 +669,26 @@ export function buildStartCommand(options = {}) {
                     return;
             }
             const requestedNetwork = Boolean(opts.builderNetwork || recoveryRecord?.builderCapabilities?.requestedNetwork);
+            // --yes never stops to ask: it approves capabilities the operator
+            // requested by flag. A resumed run counts only an explicit --yes.
+            const explicitYes = recoveryRecord ? recoveryRecord.recoveryDecision?.planUpdateApprovalSource === "explicit-yes" : Boolean(opts.yes);
             let grantedNetwork = false;
-            if (requestedNetwork) {
+            let networkDecisionId;
+            if (requestedNetwork && explicitYes) {
+                grantedNetwork = true;
+                console.error("foreman: builder internet for this build approved by --yes (requested with --builder-network)");
+            }
+            else if (requestedNetwork) {
                 const permissionDb = new WorkflowDb(cwd);
                 let networkKey;
                 try {
-                    networkKey = permissionDb.pendingHumanDecisions(supervisedInvocationId).find(decision => decision.interruptionId.startsWith("builder-network:"))?.interruptionId ?? `builder-network:${process.pid}:${randomUUID()}`;
+                    networkKey = reusableCapabilityDecision(permissionDb, supervisedInvocationId, "builder-network:", recoveryRecord?.builderCapabilities?.decisionId) ?? `builder-network:${process.pid}:${randomUUID()}`;
                 }
                 finally {
                     permissionDb.close();
                 }
-                const networkDecision = await durableHumanDecision({ projectDir: cwd, runId: supervisedInvocationId, key: networkKey,
-                    prompt: "Allow the builder shell to access the internet for this build? This permits network use by any builder command, not only downloads. Workspace write confinement remains enforced. QA stays offline. Recovery requires approval again; --yes does not approve this permission.",
+                const networkDecision = await durableHumanDecision({ projectDir: cwd, runId: supervisedInvocationId, key: networkKey, onAnswered: decision => { networkDecisionId = decision.decisionId; },
+                    prompt: "Allow the builder shell to access the internet for this build? This permits network use by any builder command, not only downloads. Workspace write confinement remains enforced. QA stays offline unless --qa-network is separately approved. Recovery requires approval again unless resumed with --yes.",
                     choices: [{ id: "allow-network", label: "Allow builder internet for this build" }, { id: "stay-offline", label: "Stay offline and use a verified local bundle" }],
                     operation: async () => {
                         const action = await select({ message: "Allow builder internet for this build?", options: [{ value: "stay-offline", label: "Stay offline" }, { value: "allow-network", label: "Allow builder internet for this build" }] });
@@ -688,7 +698,37 @@ export function buildStartCommand(options = {}) {
                     return;
                 grantedNetwork = networkDecision === "allow-network";
             }
-            const builderCapabilities = { requestedNetwork, grantedNetwork, ...(grantedNetwork ? { approvedAt: new Date().toISOString(), grantWorkerPid: process.pid } : {}) };
+            const builderCapabilities = { requestedNetwork, grantedNetwork, ...(grantedNetwork ? { approvedAt: new Date().toISOString(), grantWorkerPid: process.pid } : {}), ...(networkDecisionId ? { decisionId: networkDecisionId } : {}) };
+            // Independent QA is offline unless the operator grants --qa-network, e.g.
+            // so QA can verify a live local service the ticket requires.
+            const requestedQaNetwork = Boolean(opts.qaNetwork || recoveryRecord?.qaCapabilities?.requestedNetwork);
+            let grantedQaNetwork = false;
+            let qaNetworkDecisionId;
+            if (requestedQaNetwork && explicitYes) {
+                grantedQaNetwork = true;
+                console.error("foreman: QA network for this build approved by --yes (requested with --qa-network)");
+            }
+            else if (requestedQaNetwork) {
+                const permissionDb = new WorkflowDb(cwd);
+                let qaNetworkKey;
+                try {
+                    qaNetworkKey = reusableCapabilityDecision(permissionDb, supervisedInvocationId, "qa-network:", recoveryRecord?.qaCapabilities?.decisionId) ?? `qa-network:${process.pid}:${randomUUID()}`;
+                }
+                finally {
+                    permissionDb.close();
+                }
+                const qaNetworkDecision = await durableHumanDecision({ projectDir: cwd, runId: supervisedInvocationId, key: qaNetworkKey, onAnswered: decision => { qaNetworkDecisionId = decision.decisionId; },
+                    prompt: "Allow independent QA shell commands to access the network for this build? This lets QA run live checks (for example against a local service). QA keeps a read-only workspace. Recovery requires approval again unless resumed with --yes.",
+                    choices: [{ id: "allow-qa-network", label: "Allow QA network for this build" }, { id: "qa-offline", label: "Keep QA offline" }],
+                    operation: async () => {
+                        const action = await select({ message: "Allow QA network for this build?", options: [{ value: "qa-offline", label: "Keep QA offline" }, { value: "allow-qa-network", label: "Allow QA network for this build" }] });
+                        return isCancel(action) ? undefined : action;
+                    } });
+                if (qaNetworkDecision === undefined || isCancel(qaNetworkDecision))
+                    return;
+                grantedQaNetwork = qaNetworkDecision === "allow-qa-network";
+            }
+            const qaCapabilities = { requestedNetwork: requestedQaNetwork, grantedNetwork: grantedQaNetwork, ...(grantedQaNetwork ? { approvedAt: new Date().toISOString() } : {}), ...(qaNetworkDecisionId ? { decisionId: qaNetworkDecisionId } : {}) };
             const readinessOwner = { project: cwd, runId: supervisedInvocationId, authority: localBuildAuthority(cwd) };
             const autoApprovePlanUpdates = recoveryRecord
                 ? recoveryRecord.recoveryDecision?.planUpdateApproval === "auto"
@@ -1101,6 +1141,9 @@ export function buildStartCommand(options = {}) {
                 : base;
             const handoffRecoveryOptions = (role) => ({
                 allowProviderSwitch: true,
+                // --yes never stops to ask: retry with a fresh successor. The handoff
+                // still pauses after three rejected successors.
+                ...(explicitYes ? { choose: async () => "retry" } : {}),
                 desktopNotifications: config.notifications.enabled,
                 terminalBell: config.notifications.terminal_bell,
                 onAccepted: (accepted) => {
@@ -1185,6 +1228,7 @@ export function buildStartCommand(options = {}) {
                     configRoot: cwd,
                     sessionRole: "qa",
                     sessionStream: "qa",
+                    networkAccess: grantedQaNetwork,
                     runtimeExecutable: ready.executable,
                     runtimePhase: "qa",
                     preparationTimeoutMs: frozenPolicy.runtimeDeadlines?.preparation_ms,
@@ -1456,6 +1500,7 @@ export function buildStartCommand(options = {}) {
                     configRoot: cwd,
                     sessionRole: "qa",
                     sessionStream: "qa",
+                    networkAccess: grantedQaNetwork,
                     runtimeExecutable: ready.executable,
                     runtimePhase: "qa",
                     preparationTimeoutMs: frozenPolicy.runtimeDeadlines?.preparation_ms,
@@ -2155,7 +2200,7 @@ export function buildStartCommand(options = {}) {
                     && (opts.qaRevision !== undefined || pendingQaRecoveryPacket(cwd, recoveryRecord.runId, requestedTicketIds[0])));
                 let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { ...(branchQaOnlyRecovery ? {} : { builder: capturedBranchBuilder, builderSessionId: firstResumeRef?.sessionId ?? null, builderSessionRef: firstResumeRef ?? null }), qa: capturedBranchQa, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
                     runId: invocationRunId,
-                    builderCapabilities, tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
+                    builderCapabilities, qaCapabilities, tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
                     repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, baseRef: plan.baseRef, builder: capturedBranchBuilder, qa: capturedBranchQa,
                     frozenPolicy, autonomyProfile, qaEnabled,
                     runDecisions: { dirtyWork, workMode: "branch-per-ticket", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBranchBuilder.auto_compact_threshold_percent ?? 65, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
@@ -2189,7 +2234,7 @@ export function buildStartCommand(options = {}) {
                 }
                 for (const node of plan.nodes)
                     admitApprovedTicket(cwd, masterRun.runId, node.ticket.id, buildScopeRevision(cwd), `build invocation ${invocationRunId}: approved branch plan`);
-                masterRun = checkpointBuildRun(cwd, masterRun, "capabilities-resolved", { builderCapabilities });
+                masterRun = checkpointBuildRun(cwd, masterRun, "capabilities-resolved", { builderCapabilities, qaCapabilities });
                 const qaResumedRecovery = recoveryRecord && !isInterruptedBuilderRecovery(recoveryRecord) ? pendingQaRecoveryPacket(cwd, masterRun.runId, requestedTicketIds[0]) : undefined;
                 let qaProtocolResumeTicket;
                 if (recoveryRecord && !qaResumedRecovery && !isInterruptedBuilderRecovery(recoveryRecord)) {
@@ -2513,11 +2558,11 @@ export function buildStartCommand(options = {}) {
                 && (opts.qaRevision !== undefined || pendingQaRecoveryPacket(cwd, recoveryRecord.runId, requestedTicketIds[0])));
             let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { ...(qaOnlyRecovery ? {} : { builder: capturedBuilder, builderSessionId: resumeSessionId ?? null, builderSessionRef: resumeSessionRef ?? null }), qa: capturedQa, expectedRecoveryDecisionDigest: opts.recoveryDecisionDigest }) : createBuildRun({
                 runId: invocationRunId,
-                tickets: [...(executionTickets ?? [])], builderCapabilities, authorizedBatch: { tickets: [...(executionTickets ?? [])], requestedSteps: steps, scopeRevision: buildScopeRevision(cwd, approvalConsequences), startedTickets: [] }, repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
+                tickets: [...(executionTickets ?? [])], builderCapabilities, qaCapabilities, authorizedBatch: { tickets: [...(executionTickets ?? [])], requestedSteps: steps, scopeRevision: buildScopeRevision(cwd, approvalConsequences), startedTickets: [] }, repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
                 frozenPolicy, autonomyProfile, qaEnabled,
                 runDecisions: { workMode: "current", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBuilder.auto_compact_threshold_percent ?? 65, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
             });
-            buildRun = checkpointBuildRun(cwd, buildRun, "capabilities-resolved", { builderCapabilities });
+            buildRun = checkpointBuildRun(cwd, buildRun, "capabilities-resolved", { builderCapabilities, qaCapabilities });
             activeObserver?.store.attachExecutionLease(activeObserver.executionId, readCurrentWorkflowLease(cwd)?.generation);
             activeContinuityRunId = buildRun.runId;
             publishActivatedBuilderSession = ref => { buildRun = persistCurrentBuildSession(cwd, buildRun, "builder", ref); };
@@ -2988,11 +3033,16 @@ export function buildStartCommand(options = {}) {
             if (!(error instanceof HumanDecisionRequired))
                 throw error;
             console.error(error.message);
-            process.exitCode = 2;
+            waitingForDecision = true;
         }
         finally {
             finishStartAdmission(cwd, supervisedInvocationId);
         }
+        // Exit explicitly: supervisor IPC, heartbeats and runtime handles keep a
+        // supervised worker alive, so it would otherwise wait forever while its
+        // supervisor waits for it, and `rafi resume` refuses the "live" owner.
+        if (waitingForDecision)
+            process.exit(2);
     }));
 }
 function ticketSizeBucket(projectDir, ticketIds) {

package/dist/cli/tickets.d.ts

@@ -16,7 +16,6 @@ export interface RiskNoteRepairProposal {
         rollback: string;
     }>;
 }
-export declare function extractRiskNoteRepairProposal(output: string): RiskNoteRepairProposal;
 /** Validate a deliberately narrow repair: only exactly the missing rollback fields may change. */
 export declare function applyRiskNoteRepairProposal(tickets: import("../tickets/ticketSchema.js").TicketDef[], proposal: RiskNoteRepairProposal): import("../tickets/ticketSchema.js").TicketDef[];
 export declare function buildPopulateInstruction(approvedPlanPath: string, contextSources?: string[], progressDoc?: string): string;

package/dist/cli/tickets.js

@@ -5,7 +5,7 @@ import { accent, error, sanitizeTerminalText, success, warning } from "../termin
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { riskNoteRepairOutput, riskNoteRepairProposalV1Schema, zodIssues } from "rafi-spec";
+import { riskNoteRepairOutput } from "rafi-spec";
 import { select, text, confirm, isCancel, multiselect } from "@clack/prompts";
 import { loadConfig } from "../config.js";
 import { Log } from "../log.js";
@@ -116,26 +116,6 @@ function optionWasProvided(command, name) {
 }
 const TICKET_POPULATE_ROLE = "ticket-maker";
 const RAFI_CONFIG_FILES = ["rafi-config.yaml", "project.yaml"];
-const RISK_NOTE_REPAIR_START = "RAFI_RISK_NOTE_REPAIR_START";
-const RISK_NOTE_REPAIR_END = "RAFI_RISK_NOTE_REPAIR_END";
-export function extractRiskNoteRepairProposal(output) {
-    const start = output.lastIndexOf(RISK_NOTE_REPAIR_START);
-    const end = output.lastIndexOf(RISK_NOTE_REPAIR_END);
-    if (start < 0 || end <= start)
-        throw new Error(`Ticket Maker repair output is missing ${RISK_NOTE_REPAIR_START}/${RISK_NOTE_REPAIR_END}`);
-    const raw = output.slice(start + RISK_NOTE_REPAIR_START.length, end).trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`Ticket Maker risk-note repair is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    const validated = riskNoteRepairProposalV1Schema.safeParse(parsed);
-    if (!validated.success)
-        throw new Error(`Ticket Maker risk-note repair contract validation failed:\n${zodIssues(validated.error).map((issue) => `- ${issue}`).join("\n")}`);
-    return validated.data;
-}
 /** Validate a deliberately narrow repair: only exactly the missing rollback fields may change. */
 export function applyRiskNoteRepairProposal(tickets, proposal) {
     const targets = tickets.filter(ticket => ticket.risk !== "Low" && !hasRollbackOrMitigationPlan(ticket.rollback));
@@ -1475,7 +1455,16 @@ export async function cmdPopulateCli(opts) {
             checkpoint: scope => { planningRecord = checkpointInterview(dir, planningRecord, { decisions: { ...planningRecord.decisions, populationArtifact: scope } }); },
             dispatch: (instruction, policy) => foreman.runInstruction(instruction, policy),
         });
-        const initialPopulation = await population(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc), 0);
+        const populateInstruction = buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc);
+        let initialPopulation;
+        try {
+            initialPopulation = await population(populateInstruction, 0);
+        }
+        catch (error) {
+            // One automatic restart of a failed population before stopping for a human.
+            console.log(`foreman tickets: ticket population failed (${String(error).slice(0, 200)}); restarting it once from the first page.`);
+            initialPopulation = await population(populateInstruction, 0);
+        }
         let turn = initialPopulation.turn;
         planningRecord = checkpointInterview(dir, planningRecord, { runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() }, decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text, structuredResponse: turn.result.structured } });
         log.write("ticket-populate", {

package/dist/continuity.d.ts

@@ -1,7 +1,6 @@
 import type { ContinuityDelta, ResolvedAgentSettings } from "rafi-spec";
 import type { BuilderAdapter, CompactResult, ContextUsage, NativeAutoCompactionPolicy, NativeCompaction, ProviderSessionUsage, ProviderSettingSwitch, RuntimeFailure, TurnResult } from "./adapters/types.js";
 import type { BuilderHandoffRequest } from "./handoffs.js";
-export declare const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
 export declare class ContinuityValidationError extends Error {
     readonly problems: string[];
     constructor(problems: string[]);
@@ -27,7 +26,6 @@ export declare const CONTINUITY_REQUIRED_INSTRUCTION = "Include the required bou
 export declare function validateContinuityDelta(value: unknown): ContinuityDelta;
 export declare function mergeContinuityDeltas(deltas: readonly ContinuityDelta[]): ContinuityDelta;
 export declare function baselineContinuityDelta(nextAction?: string): ContinuityDelta;
-export declare function continuityInstruction(role?: "builder" | "qa"): string;
 export interface ContinuityAdapterOptions {
     adapter: BuilderAdapter;
     projectDir: string;

package/dist/continuity.js

@@ -1,4 +1,5 @@
 import { persistedProviderWireContract } from "rafi-spec";
+import { markDispatchNotSent } from "./dispatchNotSent.js";
 import { dispatchWithGraphAccess, withGraphSessionAccess } from "./graph/session.js";
 import { localBuildAuthority } from "./buildAdmission.js";
 import { randomUUID, createHash } from "node:crypto";
@@ -9,7 +10,6 @@ import { nativePolicy, operationInstruction, journalStructuredDispatch, continua
 import { WorkflowDb } from "./workflowDb.js";
 import { assertSealedDispatch, withFreshRecoveryValidation } from "./structuredDispatchAuthority.js";
 import { verifyPersistedDispatch } from "./structuredDispatchRecord.js";
-export const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
 export class ContinuityValidationError extends Error {
     problems;
     constructor(problems) {
@@ -93,15 +93,6 @@ export function mergeContinuityDeltas(deltas) {
 export function baselineContinuityDelta(nextAction = "Await the first role action.") {
     return { version: 1, decisions: [], constraints: [], discoveries: [], completedActions: [], evidence: [], failures: [], blockers: [], openWork: [], nextAction };
 }
-export function continuityInstruction(role) {
-    return [
-        "Before your final STEP_STATUS line (or as the final line when STEP_STATUS is not requested), emit exactly one single-line continuity record:",
-        `${CONTINUITY_MARKER} {"version":1,"decisions":[],"constraints":[],"discoveries":[],"completedActions":[],"evidence":[],"failures":[],"blockers":[],"openWork":[],"nextAction":"specific next action"}`,
-        "The continuity record is JSON. A requested STEP_STATUS line is separate plain text: never add JSON braces, a trailing comma, or a code fence to that status line.",
-        ...(role === "qa" ? ["QA protocol: this continuity record is required even when the review requests only a report or status. Put it before RAFI_QA_FAILURE_REPORT_START when returning a failure envelope, outside the report JSON. Rafi strips the record before validating the report, so keep the report envelope immediately followed by STEP_STATUS."] : []),
-        "Keep it concise and cumulative for facts learned this turn. Do not include credentials, hidden reasoning, or raw transcripts.",
-    ].join("\n");
-}
 /** Enforces a durable role checkpoint after every completed provider turn. */
 export class ContinuityAdapter {
     options;
@@ -201,30 +192,35 @@ export class ContinuityAdapter {
         const beforeSession = this.adapter.sessionRef?.();
         let original;
         try {
-            journal.atomic(() => {
-                if (this.buildAuthority)
-                    journal.assertBuildAdmission(this.buildAuthority);
-                else if (journal.buildAdmission())
-                    throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "dispatch requires original build admission authority");
-                if (process.send && process.env.RAFI_BUILD_WORKER_RUN === this.options.runId) {
-                    const supervisor = journal.supervisorState(this.options.runId);
-                    if (!process.connected || supervisor?.status !== "running" || supervisor.workerGeneration !== Number(process.env.RAFI_BUILD_WORKER_GENERATION))
-                        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "supervised worker no longer owns dispatch authority");
-                }
-                const owner = journal.roleMutationLease(this.options.runId, this.options.role);
-                const ref = this.adapter.sessionRef?.();
-                const session = ref?.sessionId ?? this.adapter.sessionId();
-                if (!(this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly) && owner && session && (owner.providerSessionId !== session || (owner.sessionKey && ref && owner.sessionKey !== providerSessionKey(ref)))) {
-                    throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "provider session no longer owns role dispatch authority");
-                }
-                if (journal.unresolvedRoleDispatches(this.options.runId, this.options.role).filter(item => item.idempotencyKey !== dispatchId).length)
-                    throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "a previous dispatched turn has no durable completion; reconcile it before sending more work");
-                if (!policy?.selectedDispatch)
-                    journal.planOperation({ runId: this.options.runId, idempotencyKey: dispatchId, kind: "provider-dispatch", intent: { role: this.options.role, sessionRef: this.adapter.sessionRef?.(), instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) } });
-                if (!policy?.selectedDispatch)
-                    journal.updateOperation(dispatchId, "in_progress");
-                journal.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, dispatchId, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
-            });
+            try {
+                journal.atomic(() => {
+                    if (this.buildAuthority)
+                        journal.assertBuildAdmission(this.buildAuthority);
+                    else if (journal.buildAdmission())
+                        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "dispatch requires original build admission authority");
+                    if (process.send && process.env.RAFI_BUILD_WORKER_RUN === this.options.runId) {
+                        const supervisor = journal.supervisorState(this.options.runId);
+                        if (!process.connected || supervisor?.status !== "running" || supervisor.workerGeneration !== Number(process.env.RAFI_BUILD_WORKER_GENERATION))
+                            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "supervised worker no longer owns dispatch authority");
+                    }
+                    const owner = journal.roleMutationLease(this.options.runId, this.options.role);
+                    const ref = this.adapter.sessionRef?.();
+                    const session = ref?.sessionId ?? this.adapter.sessionId();
+                    if (!(this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly) && owner && session && (owner.providerSessionId !== session || (owner.sessionKey && ref && owner.sessionKey !== providerSessionKey(ref)))) {
+                        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "provider session no longer owns role dispatch authority");
+                    }
+                    if (journal.unresolvedRoleDispatches(this.options.runId, this.options.role).filter(item => item.idempotencyKey !== dispatchId).length)
+                        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "a previous dispatched turn has no durable completion; reconcile it before sending more work");
+                    if (!policy?.selectedDispatch)
+                        journal.planOperation({ runId: this.options.runId, idempotencyKey: dispatchId, kind: "provider-dispatch", intent: { role: this.options.role, sessionRef: this.adapter.sessionRef?.(), instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) } });
+                    if (!policy?.selectedDispatch)
+                        journal.updateOperation(dispatchId, "in_progress");
+                    journal.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "turn_started", payload: { role: this.options.role, dispatchId, instructionDigest: sha(instruction), instructionBytes: Buffer.byteLength(instruction) }, authoritativeStateRevision: this.revision() });
+                });
+            }
+            catch (error) {
+                throw markDispatchNotSent(error);
+            }
             try {
                 original = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, providerInstruction, policy, (text, p) => this.adapter.sendTurn(text, p));
             }

package/dist/dispatchNotSent.d.ts

@@ -0,0 +1,4 @@
+/** Tag an error raised before any provider transport began, so the journal
+ * records a known unsent turn instead of an unknown outcome. */
+export declare function markDispatchNotSent(error: unknown): unknown;
+export declare function dispatchWasNotSent(error: unknown): boolean;

package/dist/dispatchNotSent.js

@@ -0,0 +1,10 @@
+/** Tag an error raised before any provider transport began, so the journal
+ * records a known unsent turn instead of an unknown outcome. */
+export function markDispatchNotSent(error) {
+    if (error && typeof error === "object")
+        error.dispatchNotSent = true;
+    return error;
+}
+export function dispatchWasNotSent(error) {
+    return Boolean(error && typeof error === "object" && error.dispatchNotSent);
+}

package/dist/foreman.d.ts

@@ -7,7 +7,7 @@ import { type QaNonconvergenceContext, type QaNonconvergenceDecision, type QaRep
 import type { SessionStrategy } from "rafi-spec";
 import type { RunObserver } from "./observability.js";
 import type { QaRecoveryPacket } from "./qaRecovery.js";
-/** Parsed STEP_STATUS marker from a builder's turn. */
+/** A role turn's outcome, derived from its native structured result. */
 export interface StepStatus {
     kind: "done" | "blocked" | "plan_complete" | "needs_input" | "qa_pass" | "qa_fail" | "unknown";
     summary?: string;
@@ -21,17 +21,10 @@ export interface StepStatus {
     error?: string;
 }
 /**
- * Workflow-specific completion is opt-in. Callers may preserve a valid
- * structured response before the generic strict STEP_STATUS repair path runs.
+ * Workflow-specific completion is opt-in. Callers may interpret a valid
+ * structured response before the generic native result handling runs.
  */
 export type InstructionCompletion = (text: string) => StepStatus | undefined;
-/**
- * Pull the STEP_STATUS marker out of a turn's final text.
- * Format: `STEP_STATUS: <kind> | key="value" key="value"`.
- */
-export declare function parseStepStatus(text: string, options?: {
-    requireFinalLine?: boolean;
-}): StepStatus;
 /** Heuristic: did a marker-less turn end by asking the human something? */
 export declare function looksLikeQuestion(text: string): boolean;
 export { MARKER_SPEC } from "./markers.js";
@@ -39,13 +32,13 @@ export { QA_MARKER_SPEC } from "./markers.js";
 /** Instruction sent on the first turn of a batch. */
 export declare function buildPrimer(n: number, trackerPath?: string, ticketsEnabled?: boolean, preferredTicketId?: string): string;
 /** Instruction sent on turns 2–N. */
-export declare function buildNextStepInstruction(i: number, n: number): string;
+export declare function buildNextStepInstruction(i: number, n: number, ticketsEnabled?: boolean): string;
 /** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
 export declare function buildQaInstruction(): string;
 /** Follow-up turn after qa_fail: have the builder implement the listed fixes. */
 export declare function buildQaFixInstruction(issues: string): string;
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export declare function buildPlanningTurn(n: number, ticketsContent?: string, preferredTicketId?: string): string;
+export declare function buildPlanningTurn(n: number, ticketsContent?: string, preferredTicketId?: string, ticketsEnabled?: boolean): string;
 /** Builds the permission callback: classify, log, allow or escalate. */
 export declare function createPermissionHandler(policy: PermissionPolicy, log: Log, opts?: {
     interactive?: boolean;