ai-foreman 1.7.29 → 2.0.1

package/dist/cli/start.js

@@ -1,3 +1,4 @@
+import { nativePolicy, operationInstruction, operationPayload, structuredTurnErrorMessage } from "../structuredOperation.js";
 import { finalQaRoleInstructions, resolveEffectiveQaConfiguration } from "../qaEffectiveConfig.js";
 import { activateQaRecoveryBuilder } from "../qaBuilderActivation.js";
 import { graphContext, sendGraphTurn } from "../graph/turn.js";
@@ -10,8 +11,8 @@ 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 { requiresBuildApproval, buildScopeRevision, createBuildApprovalGate, validatePlanApprovalBinding } from "../buildApproval.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";
 import { resolve, join, relative } from "node:path";
@@ -34,7 +35,7 @@ import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../
 import { hasRollbackOrMitigationPlan, loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
 import { ticketDefinitionDigest } from "../tickets/riskWaivers.js";
-import { applySharedDeliveryBranch, applySizeBranchPolicy, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
+import { applySharedDeliveryBranch, applySizeBranchPolicy, buildBranchAuditInstruction, buildBranchPlan } from "../branch/planner.js";
 import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
 import { captureDirtyBaseline } from "../branch/dirtyBaseline.js";
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
@@ -42,7 +43,7 @@ import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
 import { branchPlanLogMetadata, presentBranchPlan } from "../branch/presentation.js";
 import { branchTicketScopeProgress, buildRunSessionBinding, checkpointBuildRun, completeBuildRun, createBuildRun, currentBranchRecoveryTicket, currentBranchTicketProgress, recoveryExecutionTickets, finishBranchTicketScope, finishRecoveredTicketScope, heartbeatBuildRun, persistBuildSession, persistCurrentBuildSession, projectBuildRecovery, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
-import { parseProviderContract, qaRemediationProposalV1Schema } from "rafi-spec";
+import { branchAuditOutput, plannerRemediationOutput } from "rafi-spec";
 import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
@@ -539,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)")
@@ -564,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);
         }
@@ -666,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" }] });
@@ -687,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"
@@ -699,9 +740,11 @@ export function buildStartCommand(options = {}) {
             // recovery remains fail-closed on an exact current-plan approval.
             if (recoveryRecord && autoApprovePlanUpdates && recoveryTickets.length > 0) {
                 const decision = recoveryRecord.recoveryDecision;
-                if (!decision?.planApproval)
+                if (!decision?.planApproval && !decision?.frozenWorkApproval)
                     fail("saved --yes approval has no exact plan binding; rerun rafi build:resume --yes to approve the current plan");
-                const approvalCheck = validatePlanApprovalBinding(cwd, recoveryTickets, decision.planApproval);
+                const approvalCheck = decision.frozenWorkApproval
+                    ? validateFrozenWorkApprovalBinding(cwd, recoveryRecord.runId, recoveryTickets, decision.frozenWorkApproval)
+                    : validatePlanApprovalBinding(cwd, recoveryTickets, decision.planApproval);
                 if (!approvalCheck.valid)
                     fail(`saved --yes approval is stale (${approvalCheck.reason}); rerun rafi build:resume --yes before provider work`);
             }
@@ -1098,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) => {
@@ -1182,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,
@@ -1305,7 +1352,6 @@ export function buildStartCommand(options = {}) {
                     try {
                         const revision = countDb.continuityHead(runId, "builder")?.authoritativeStateRevision ?? settings.settings_revision;
                         countDb.appendContinuityEvent({ runId, role: "builder", kind: "builder_requested_handoff_delta", payload: request.delta, authoritativeStateRevision: revision });
-                        countDb.publishContinuityCheckpoint({ runId, role: "builder", delta: request.delta, authoritativeStateRevision: revision });
                         compactionCount = countDb.successfulCompactionCount(runId, "builder", predecessor.sessionRef?.() ?? sessionId);
                     }
                     finally {
@@ -1318,6 +1364,7 @@ export function buildStartCommand(options = {}) {
                         predecessorSessionId: sessionId,
                         predecessorSessionRef: predecessor.sessionRef?.(),
                         requestedByBuilder: true,
+                        predecessorDispatchId: request.predecessorDispatchId,
                         roleState: {
                             ...request.roleState,
                             frozenActionDigest: createHash("sha256").update(frozenAction).digest("hex"),
@@ -1334,7 +1381,8 @@ export function buildStartCommand(options = {}) {
                         resources: [{ label: "frozen-action", content: frozenAction, authoritative: true }],
                     }, (_handoff, runtime) => createBuilderForSettings(builderCwd, settingsForRequestedRuntime(effectiveSettings, runtime)), handoffRecoveryOptions("builder"));
                     log.write("handoff-transfer", {
-                        requestedByBuilder: true, reason: request.reason, generation: transfer.manifest.generation,
+                        requestedByBuilder: true,
+                        predecessorDispatchId: request.predecessorDispatchId, reason: request.reason, generation: transfer.manifest.generation,
                         predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
                         acceptanceCheckpointDigest: transfer.acceptanceCheckpointDigest,
                     });
@@ -1452,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,
@@ -2027,10 +2076,13 @@ export function buildStartCommand(options = {}) {
                     try {
                         auditBuilder = await createBuilder(cwd);
                         auditViewer = printEvents(auditBuilder.events());
-                        const audit = await sendGraphTurn(auditBuilder, buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket)), graphContext(cwd, auditBuilder.sessionRef?.()?.cwd ?? cwd, "branch-dependency-audit", plan.nodes.map(node => node.ticket.id).join(" ")), { purpose: "planning" });
+                        const audit = await sendGraphTurn(auditBuilder, `${buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket))}\n${operationInstruction(branchAuditOutput)}`, graphContext(cwd, auditBuilder.sessionRef?.()?.cwd ?? cwd, "branch-dependency-audit", plan.nodes.map(node => node.ticket.id).join(" ")), nativePolicy(branchAuditOutput, { purpose: "planning", journalRunId: auditRunId }));
                         if (audit.isError)
-                            throw new Error(audit.text);
-                        const auditDependencies = parseAuditDependencies(audit.text);
+                            throw new Error(structuredTurnErrorMessage(audit, "Branch dependency audit"));
+                        const auditDependencies = operationPayload(audit, branchAuditOutput).dependencies;
+                        const selectedIds = new Set(plan.nodes.map(node => node.ticket.id));
+                        if (auditDependencies.some(dep => dep.ticket === dep.dependsOn || !selectedIds.has(dep.ticket) || !selectedIds.has(dep.dependsOn)))
+                            throw new Error("Branch audit returned a foreign or self dependency");
                         plan = buildBranchPlan(tickets, states, {
                             steps,
                             baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch ?? currentGitRef(cwd),
@@ -2148,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" },
@@ -2182,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)) {
@@ -2506,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); };
@@ -2981,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) {
@@ -3146,8 +3203,7 @@ export function createQaNonconvergenceHandler(projectDir, noninteractive, planne
                 `User discussion: ${String(discussion)}`,
                 `Complete QA history:\n${JSON.stringify(context.history, null, 2)}`,
                 `${diffTruncated ? "Builder diff (TRUNCATED at 128 KiB; inspect the actual worktree before relying on it)" : "Full Builder diff"}:\n${diff || "(no tracked diff)"}`,
-                "Return RAFI_QA_REMEDIATION_START, then one JSON object {\"summary\":\"...\",\"fix_instructions\":[\"...\"]}, then RAFI_QA_REMEDIATION_END.",
-                "End with STEP_STATUS: plan_complete | summary=\"QA remediation proposed\"",
+                "Submit the native planner-remediation payload with summary and fix_instructions.",
             ].join("\n\n");
             let resumeSessionId;
             let revision = 0;
@@ -3155,24 +3211,14 @@ export function createQaNonconvergenceHandler(projectDir, noninteractive, planne
                 revision++;
                 const proposalDigest = createHash("sha256").update(JSON.stringify([scope, round, revision, instruction, planner, captureFrozenQaSource(context.builderWorktree).digest])).digest("hex");
                 const run = await durableReadOnlyProposal({ projectDir, runId, ticketId: context.ticket.id, digest: proposalDigest, operation: () => runRoleInstruction({
-                        projectDir, role: "planner", instruction, label: "QA Planner remediation", agent: planner?.make,
+                        projectDir, role: "planner", instruction, output: plannerRemediationOutput, label: "QA Planner remediation", agent: planner?.make,
                         model: explicitDefaultValue(planner?.model), effort: explicitEffort(planner?.reasoning), fast: planner?.fast,
                         resumeSessionId, permissionConfig: readOnlyPermissionConfig(), sandboxMode: "read-only",
                         logPath: makeRoleLogPath(projectDir, "qa-remediation"), logEvent: "rafi-plan",
                     }) });
-                if (run.turn.result.isError || run.turn.status.kind !== "plan_complete")
+                if (run.turn.result.isError || run.turn.status.kind !== "done")
                     throw new Error(`Planner remediation failed: ${run.turn.status.error ?? run.turn.result.text.slice(0, 500)}`);
-                const match = /RAFI_QA_REMEDIATION_START\s*([\s\S]*?)\s*RAFI_QA_REMEDIATION_END/.exec(run.turn.result.text);
-                if (!match)
-                    throw new Error("Planner remediation did not return the required structured proposal");
-                let parsed;
-                try {
-                    parsed = JSON.parse(match[1].replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, ""));
-                }
-                catch (error) {
-                    throw new Error(`Planner remediation proposal is invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
-                }
-                const proposal = parseProviderContract(qaRemediationProposalV1Schema, parsed, "RAFI_QA_REMEDIATION");
+                const proposal = operationPayload(run.turn.result, plannerRemediationOutput);
                 console.log(`\nPlanner remediation: ${proposal.summary}\n${proposal.fix_instructions.map((item) => `- ${item}`).join("\n")}`);
                 const decision = await ask(`QA remediation approval ${revision}: ${JSON.stringify(proposal)}`, [{ id: "approve", label: "Approve" }, { id: "revise", label: "Revise" }, { id: "cancel", label: "Return to choices" }], () => select({ message: "Use this remediation for a new Builder fix session?", options: [
                         { value: "approve", label: "Approve (Recommended)" }, { value: "revise", label: "Discuss/revise" }, { value: "cancel", label: "Cancel and return to choices" },
@@ -3185,7 +3231,7 @@ export function createQaNonconvergenceHandler(projectDir, noninteractive, planne
                 if (isCancel(feedback))
                     break;
                 resumeSessionId = run.sessionId;
-                instruction = `Revise the complete QA remediation proposal using this feedback: ${String(feedback)}. Keep the exact structured envelope and final plan_complete marker.`;
+                instruction = `Revise the complete QA remediation proposal using this feedback: ${String(feedback)}. Use the native planner-remediation contract.`;
             }
         }
     };

package/dist/cli/tickets.d.ts

@@ -1,17 +1,10 @@
 import { Command } from "commander";
 import type { StructuredPlanV1 } from "rafi-spec";
 import { Log } from "../log.js";
-import { type StepStatus } from "../foreman.js";
 import type { EffortLevel } from "../adapters/types.js";
 import { type RoleBuilderOptions } from "../agentRun.js";
 import type { TicketsConfig } from "../tickets/config.js";
 import { type TicketPopulateRuntimeMode, type TicketSourceConfig, type TicketsSetupConfig } from "../tickets/setupConfig.js";
-/**
- * Ticket Maker may append an explanatory note after its machine envelope.
- * Preserve a schema-valid proposal before Foreman's strict generic marker
- * repair path replaces the response with a status-only correction.
- */
-export declare function acceptTicketPopulationCompletion(text: string): StepStatus | undefined;
 /** Commander preserves comma-delimited values as one argument; accept both documented forms. */
 export declare function normalizeRiskWaiverTicketIds(values: readonly string[] | undefined): string[];
 /** Record an explicit, definition-bound exception for existing risk tickets. */
@@ -23,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

@@ -1,13 +1,15 @@
+import { streamTicketPopulation } from "../ticketPopulationPaging.js";
+import { operationPayload } from "../structuredOperation.js";
 import { Command } from "commander";
 import { accent, error, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { 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";
-import { Foreman, parseStepStatus } from "../foreman.js";
+import { Foreman } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdStackQueue, cmdArchive, cmdReview, } from "../tickets/commands.js";
 import { loadDeliveryConfig } from "../tickets/delivery.js";
@@ -20,7 +22,7 @@ import { DEFAULT_TICKET_SETUP, configuredPlanningSources, configuredAppName, def
 import { deactivateSource, discardStagedSourceCaptures, loadSourceRegistry, refreshSourceRegistry, registerSourceRequests, removeSource, saveSourceRegistry, } from "../sources/sourceRegistry.js";
 import { fetchAndSnapshotUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, readInterviewRecords, resumeInterviewRecord, } from "../interviews.js";
-import { applyTicketPopulation, assertRiskPlanOnlyCorrection, authorizeTicketRetirements, extractTicketPopulationProposal, materializeTicketPopulation, recoverTicketPublications, TicketPopulationValidationError, TICKET_POPULATION_PROPOSAL_END, TICKET_POPULATION_PROPOSAL_START } from "../ticketPopulation.js";
+import { applyTicketPopulation, assertRiskPlanOnlyCorrection, authorizeTicketRetirements, materializeTicketPopulation, recoverTicketPublications, TicketPopulationValidationError } from "../ticketPopulation.js";
 import { loadTickets, saveTickets, validateTicketDefs } from "../tickets/ticketLoader.js";
 import { resolveTicketPaths } from "../tickets/config.js";
 import { formatAllTicketDetails, formatTicketDetails, getAllTicketDetails, getTicketDetails } from "../tickets/details.js";
@@ -31,25 +33,11 @@ import { listTicketGroups, previewTicketGroupRepair, repairTicketGroups } from "
 import { StateDb } from "../tickets/stateDb.js";
 import { ticketDefinitionDigest } from "../tickets/riskWaivers.js";
 import { hasRollbackOrMitigationPlan } from "../tickets/ticketLoader.js";
+import { migrateTrackerRules } from "../tickets/renderMarkdown.js";
 let nestedTicketCommandDepth = 0;
 class TicketInterviewCancelled extends Error {
 }
 function cancelTicketInterview() { throw new TicketInterviewCancelled("ticket interview cancelled"); }
-/**
- * Ticket Maker may append an explanatory note after its machine envelope.
- * Preserve a schema-valid proposal before Foreman's strict generic marker
- * repair path replaces the response with a status-only correction.
- */
-export function acceptTicketPopulationCompletion(text) {
-    try {
-        extractTicketPopulationProposal(text);
-    }
-    catch {
-        return undefined;
-    }
-    const status = parseStepStatus(text, { requireFinalLine: false });
-    return status.kind === "done" || status.kind === "plan_complete" ? status : undefined;
-}
 function fail(msg) {
     if (nestedTicketCommandDepth > 0)
         throw new Error(msg);
@@ -128,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));
@@ -210,23 +178,13 @@ Return ticket content using Foreman's schema:
 - title, area, priority, size, risk, depends_on, summary, acceptance, required_tests, likely_files, rollback, notes.
 - Keep dependencies, acceptance criteria, testing expectations, file hints, risk notes, and implementation notes from the source material. For each ticket, use only the mapped approved slice's acceptance and required tests; do not copy plan-level acceptance criteria or add requirements about sibling slices or unfinished tickets. A ticket's acceptance must remain implementable and verifiable when its own slice is delivered.
 - Preserve additive-slice independence without inventing an absence test: each ticket's own behavior and tests should work against the shared approved baseline and must not depend on sibling implementation. Do not add wording such as "with the sibling absent/present," "without [sibling] present," or "with this slice alone" unless the approved plan explicitly requires sibling absence testing or an isolated branch. Otherwise use positive own-ticket checks, the shared project tests, and the combined-result check.
-- Preserve the approved slice's documentation policy exactly. Documentation is off by default; do not invent a documentation requirement because a docs directory exists. When documentation is required, retain its exact targets and criteria so the Builder and independent QA can enforce it.
+- Rafi copies documentation policy and QA preparation decisions directly from the approved slice. Do not include these host-owned fields in your proposal or invent additional requirements. Preserve the approved acceptance and tests.
 - File names and likely_files are implementation hints, not an exhaustive allowlist. Do not invent acceptance criteria or tests that require an exact changed-file list; allow other relevant files needed to complete the approved work. Preserve explicit user-established security, privacy, access, and other safety restrictions. Rafi manages ticket lifecycle state; do not require the Builder to mark tickets done in a document.
 - For every Medium or High risk ticket, \`rollback\` is required. It must state a concrete rollback or mitigation action: what is disabled, reverted, or contained, and how recovery or impact is verified. \`notes\` may add context but never satisfies this requirement. Low-risk tickets may use \`rollback: null\`.
 - Do not store mutable status/progress fields in .tickets/tickets.yaml.
 - Dependencies must reference slice_ref values. Include the exact IDs of existing populated tickets whose removed slices should become obsolete.
 
-If source content does not cleanly map to the new schema, ask for guidance instead of guessing. Use:
-STEP_STATUS: needs_input | question="..." choices="..."
-
-Output one JSON object between ${TICKET_POPULATION_PROPOSAL_START} and ${TICKET_POPULATION_PROPOSAL_END} with shape:
-{"version":1,"plan_id":"approved plan ID","revision":1,"tickets":[{"slice_ref":"slc_low","title":"...","area":"...","priority":"P1","size":"S","risk":"Low","summary":"...","acceptance":["..."],"required_tests":["..."],"likely_files":["..."],"documentation":{"required":false,"targets":[],"criteria":[]},"depends_on":[],"rollback":null,"notes":null},{"slice_ref":"slc_medium","title":"...","area":"...","priority":"P1","size":"S","risk":"Medium","summary":"...","acceptance":["..."],"required_tests":["..."],"likely_files":["..."],"documentation":{"required":false,"targets":[],"criteria":[]},"depends_on":["slc_low"],"rollback":"Disable the feature flag, restore the previous handler, and verify the affected error rate returns to baseline.","notes":null}],"retirements":["exact existing ticket ID"]}
-Triple-check that every approved slice appears exactly once.
-
-End with exactly one marker line as the final non-empty line; do not append notes or commentary after it:
-STEP_STATUS: done | summary="populated Foreman tickets from existing project ticket sources"
-or
-STEP_STATUS: blocked | reason="why ticket population cannot proceed"`;
+If source content does not cleanly map to the approved plan, return a needs-input or blocked result instead of guessing. Return the full proposal in result.payload of the native ticket-population response. The proposal contains version, plan_id, revision, tickets, and retirements. Do not allocate final ticket IDs.`;
 }
 /** A bounded correction loop ended without a publishable proposal. */
 export class TicketPopulationRiskCorrectionExhaustedError extends Error {
@@ -546,6 +504,18 @@ async function cmdSetupUpdateCli(opts) {
             saveSourceRegistry(dir, patch.sourceRegistry);
         registrySaved = true;
         syncTicketLimits(dir, next.limits);
+        if (isTicketsInitialized(dir)) {
+            const ticketsConfig = loadTicketsConfig(dir);
+            const trackerRulesPath = join(dir, ticketsConfig.paths.trackerRules);
+            if (existsSync(trackerRulesPath)) {
+                const before = readFileSync(trackerRulesPath, "utf8");
+                const migrated = migrateTrackerRules(before, ticketsConfig.paths.progressDoc);
+                if (migrated.disposition !== "unchanged") {
+                    writeFileSync(trackerRulesPath, migrated.content, "utf8");
+                    console.log(`foreman tickets setup: ${migrated.disposition === "replaced-legacy" ? "upgraded" : "refreshed"} Rafi-managed tracker rules`);
+                }
+            }
+        }
         console.log(`foreman tickets setup: updated ticket setup in ${join(dir, "rafi-config.yaml")}`);
         if (isTicketsInitialized(dir)) {
             const rows = cmdQueue(dir, 1);
@@ -1480,8 +1450,23 @@ export async function cmdPopulateCli(opts) {
         if (contextSources.length) {
             console.log(`foreman tickets: context sources ${contextSources.join(" ")}`);
         }
-        let turn = await foreman.runInstruction(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc), { completion: acceptTicketPopulationCompletion });
-        planningRecord = checkpointInterview(dir, planningRecord, { runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() }, decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text } });
+        const population = (instruction, correction) => streamTicketPopulation({
+            projectDir: dir, interviewId: planningRecord.id, correction, instruction,
+            checkpoint: scope => { planningRecord = checkpointInterview(dir, planningRecord, { decisions: { ...planningRecord.decisions, populationArtifact: scope } }); },
+            dispatch: (instruction, policy) => foreman.runInstruction(instruction, policy),
+        });
+        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", {
             statusKind: turn.status.kind,
             summary: turn.status.summary,
@@ -1499,7 +1484,9 @@ export async function cmdPopulateCli(opts) {
             throw new Error(`needs human — ${turn.status.error ?? "builder did not emit done"}`);
         }
         const existing = loadTickets(resolveTicketPaths(ticketsConfig, dir).tickets);
-        let proposal = extractTicketPopulationProposal(turn.result.text);
+        if (!turn.result.selectedDispatch)
+            throw new Error("Ticket population response has no sealed dispatch tuple");
+        let proposal = initialPopulation.proposal;
         let proposalArtifact = savePopulationProposalArtifact(dir, planningRecord.id, approvedPlan, proposal);
         let materialized;
         let populationWaiver;
@@ -1525,18 +1512,22 @@ export async function cmdPopulateCli(opts) {
                     continue;
                 }
                 console.log(`foreman tickets: ${ids} need risk plans; asking Ticket Maker for a targeted correction (${correction + 1}/2)`);
-                const correctionTurn = await foreman.runInstruction(`Correct the existing ticket population proposal only. Do not change plan_id, revision, slice_ref mappings, ticket IDs, dependencies, scope, ownership, acceptance criteria, tests, retirements, or any field except \`rollback\` for these tickets: ${ids}. Each listed ticket is Medium or High risk and requires a concrete rollback or mitigation plan in \`rollback\`; \`notes\` cannot satisfy this requirement. Return the complete replacement JSON proposal between ${TICKET_POPULATION_PROPOSAL_START} and ${TICKET_POPULATION_PROPOSAL_END}, followed by STEP_STATUS: done.`);
+                const correctedPopulation = await population(`Correct the existing ticket population proposal only. Do not change plan_id, revision, slice_ref mappings, ticket IDs, dependencies, scope, ownership, acceptance criteria, tests, retirements, or any field except \`rollback\` for these tickets: ${ids}. Each listed ticket is Medium or High risk and requires a concrete rollback or mitigation plan in \`rollback\`; \`notes\` cannot satisfy this requirement. Return the complete replacement proposal through native ticket-population pages.`, correction + 1);
+                const correctionTurn = correctedPopulation.turn;
                 if (correctionTurn.result.isError || (correctionTurn.status.kind !== "done" && correctionTurn.status.kind !== "plan_complete")) {
                     throw new Error(`Ticket Maker could not correct missing risk plans for ${ids}: ${correctionTurn.status.reason ?? correctionTurn.status.error ?? correctionTurn.result.text.slice(0, 200)}`);
                 }
                 turn = correctionTurn;
                 planningRecord = checkpointInterview(dir, planningRecord, {
                     runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() },
-                    decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text, riskPlanCorrections: correction + 1 },
+                    decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text, structuredResponse: turn.result.structured, riskPlanCorrections: correction + 1 },
                 });
-                const corrected = extractTicketPopulationProposal(turn.result.text);
+                const corrected = correctedPopulation.proposal;
                 assertRiskPlanOnlyCorrection(proposal, corrected, err.repairableRiskSliceRefs);
                 proposal = corrected;
+                if (!turn.result.selectedDispatch)
+                    throw new Error("Ticket population correction has no sealed dispatch tuple");
+                // A correction is immutable lineage, never a rewrite of the terminal proposal.
                 proposalArtifact = savePopulationProposalArtifact(dir, planningRecord.id, approvedPlan, proposal);
             }
         }
@@ -1599,13 +1590,12 @@ export async function cmdRepairRiskNotesCli(opts) {
             "You are Ticket Maker in read-only repair mode. Do not edit files.",
             "For every listed ticket, supply a concrete rollback or mitigation plan. Do not change any other field or add/remove tickets.",
             `Tickets requiring repair:\n${JSON.stringify(targets.map(ticket => ({ id: ticket.id, title: ticket.title, risk: ticket.risk, summary: ticket.summary, acceptance: ticket.acceptance, required_tests: ticket.required_tests })), null, 2)}`,
-            `Return exactly one JSON object between ${RISK_NOTE_REPAIR_START} and ${RISK_NOTE_REPAIR_END}: {"version":1,"tickets":[{"id":"T001","rollback":"Concrete reversal or mitigation steps."}]}.`,
-            "End with STEP_STATUS: done | summary=\"risk-note repair proposed\"",
+            `Submit the native risk-note-repair payload: {"version":1,"tickets":[{"id":"T001","rollback":"Concrete reversal or mitigation steps."}]}.`,
         ].join("\n\n");
-        const turn = await foreman.runInstruction(instruction);
+        const turn = await foreman.runInstruction(instruction, { output: riskNoteRepairOutput });
         if (turn.result.isError || (turn.status.kind !== "done" && turn.status.kind !== "plan_complete"))
             throw new Error(`Ticket Maker could not propose risk-plan repairs: ${turn.status.reason ?? turn.status.error ?? turn.result.text.slice(0, 300)}`);
-        const proposal = extractRiskNoteRepairProposal(turn.result.text);
+        const proposal = operationPayload(turn.result, riskNoteRepairOutput);
         const repaired = applyRiskNoteRepairProposal(current, proposal);
         for (const target of targets)
             console.log(`  ${target.id}: ${proposal.tickets.find(item => item.id === target.id).rollback.trim()}`);