ai-foreman 1.7.29 → 2.0.1

package/dist/continuity.d.ts

@@ -1,6 +1,6 @@
 import type { ContinuityDelta, ResolvedAgentSettings } from "rafi-spec";
 import type { BuilderAdapter, CompactResult, ContextUsage, NativeAutoCompactionPolicy, NativeCompaction, ProviderSessionUsage, ProviderSettingSwitch, RuntimeFailure, TurnResult } from "./adapters/types.js";
-export declare const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
+import type { BuilderHandoffRequest } from "./handoffs.js";
 export declare class ContinuityValidationError extends Error {
     readonly problems: string[];
     constructor(problems: string[]);
@@ -22,15 +22,10 @@ export declare class SessionUnavailableContinuityError extends Error {
     readonly guidedRecovery: boolean;
     constructor(runId: string, role: "builder" | "qa", failure: RuntimeFailure);
 }
+export declare const CONTINUITY_REQUIRED_INSTRUCTION = "Include the required bounded continuity object in the operation response; continuity cannot be null for this session.";
 export declare function validateContinuityDelta(value: unknown): ContinuityDelta;
-export declare function parseContinuityDelta(text: string): {
-    delta?: ContinuityDelta;
-    cleanText: string;
-    error?: ContinuityValidationError;
-};
 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;
@@ -53,7 +48,7 @@ export interface ContinuityAdapterOptions {
     /** Explicit compatibility recovery may replace a dead predecessor lease only after its first valid checkpoint. */
     replaceRecoveryLeaseAfterCheckpoint?: boolean;
     /** Host-owned validated Builder handoff request processing at a safe turn boundary. */
-    handleHandoffRequest?: (text: string, predecessor: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter | undefined>;
+    handleHandoffRequest?: (text: string | BuilderHandoffRequest, predecessor: BuilderAdapter, frozenAction: string) => Promise<BuilderAdapter | undefined>;
     /** QA journals each provider turn separately; wrappers must not repair or redispatch inside one host turn. */
     durableSingleTurn?: boolean;
 }
@@ -79,15 +74,16 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     /** Establish an explicitly requested fresh owner before context probes or work. */
     validateFreshRecovery(): Promise<void>;
     get agent(): "claude" | "codex";
-    sendTurn(instruction: string, policy?: {
-        handback?: boolean;
-        responseOnly?: boolean;
-        logicalActionId?: string;
-        purpose?: import("./providerPhase.js").ProviderTurnPurpose;
-    }): Promise<TurnResult>;
+    /** Every confirmed dispatch publishes a checkpoint, so continuity is mandatory. */
+    structuredDispatchRequirement(): import("./adapters/types.js").StructuredDispatchRequirement;
+    sendTurn(instruction: string, policy?: import("./adapters/types.js").TurnRequest): Promise<TurnResult>;
     private sendTurnOwned;
+    postConfirmedDispatch(reference: import("./adapters/types.js").ConfirmedDispatchReference): Promise<TurnResult>;
     observeEvents(listener: (event: import("./adapters/types.js").BuilderEvent) => void): () => void;
     acceptHandbackTurn(turn: TurnResult): void;
+    /** Explicit restart recovery of the already accepted action; never repeats acceptance. */
+    resumePlannedContinuation(): Promise<TurnResult | undefined>;
+    recoverConfirmedPublications(): Promise<void>;
     sessionId(): string | undefined;
     sessionRef(): import("rafi-spec").ProviderSessionRefV1 | undefined;
     prepareSession(): Promise<import("rafi-spec").ProviderSessionRefV1>;
@@ -109,9 +105,7 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     /** Keep the observable wrapper and event stream stable while moving to an accepted successor. */
     adoptValidatedSuccessor(successor: BuilderAdapter): Promise<void>;
     private publish;
-    private moveRecoveryLeaseAfterCheckpoint;
     private recordSessionUnavailable;
-    private reconstructionHandoff;
     private revision;
     private pumpEvents;
 }

package/dist/continuity.js

@@ -1,11 +1,15 @@
+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";
-import { continuityDeltaV1Schema, zodIssues } from "rafi-spec";
+import { continuityDeltaV1Schema, initializationOutput, zodIssues } from "rafi-spec";
 import { BuilderEventQueue } from "./activity.js";
 import { providerSessionKey } from "./sessionIdentity.js";
+import { nativePolicy, operationInstruction, journalStructuredDispatch, continuationPolicy } from "./structuredOperation.js";
 import { WorkflowDb } from "./workflowDb.js";
-export const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
+import { assertSealedDispatch, withFreshRecoveryValidation } from "./structuredDispatchAuthority.js";
+import { verifyPersistedDispatch } from "./structuredDispatchRecord.js";
 export class ContinuityValidationError extends Error {
     problems;
     constructor(problems) {
@@ -44,6 +48,7 @@ export class SessionUnavailableContinuityError extends Error {
         this.guidedRecovery = guidedRecovery;
     }
 }
+export const CONTINUITY_REQUIRED_INSTRUCTION = "Include the required bounded continuity object in the operation response; continuity cannot be null for this session.";
 export function validateContinuityDelta(value) {
     const problems = [];
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -74,20 +79,6 @@ export function validateContinuityDelta(value) {
         throw new ContinuityValidationError(problems);
     return output;
 }
-export function parseContinuityDelta(text) {
-    const lines = text.split(/\r?\n/);
-    const markerIndexes = lines.flatMap((line, index) => line.trimStart().startsWith(CONTINUITY_MARKER) ? [index] : []);
-    const cleanText = lines.filter((_line, index) => !markerIndexes.includes(index)).join("\n").trimEnd();
-    if (markerIndexes.length !== 1)
-        return { cleanText, error: new ContinuityValidationError([markerIndexes.length ? "multiple continuity markers" : "missing continuity marker"]) };
-    const raw = lines[markerIndexes[0]].trimStart().slice(CONTINUITY_MARKER.length).trim();
-    try {
-        return { delta: validateContinuityDelta(JSON.parse(raw)), cleanText };
-    }
-    catch (error) {
-        return { cleanText, error: error instanceof ContinuityValidationError ? error : new ContinuityValidationError([`marker is not valid JSON: ${String(error)}`]) };
-    }
-}
 export function mergeContinuityDeltas(deltas) {
     const result = baselineContinuityDelta();
     for (const delta of deltas) {
@@ -102,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;
@@ -136,7 +118,7 @@ export class ContinuityAdapter {
             db.ensureRun(options.runId);
             if (!db.continuityHead(options.runId, options.role)) {
                 db.appendContinuityEvent({ runId: options.runId, role: "host", kind: "role_baseline", payload: { role: options.role, provider: options.settings.make, model: options.settings.model }, authoritativeStateRevision: this.revision() });
-                db.publishContinuityCheckpoint({ runId: options.runId, role: options.role, delta: baselineContinuityDelta(), authoritativeStateRevision: this.revision() });
+                db.publishContinuityCheckpoint({ runId: options.runId, role: options.role, delta: baselineContinuityDelta(), hostEventKind: "role-baseline", inputCheckpointDigests: [], authoritativeStateRevision: this.revision() });
             }
             const initialSession = options.adapter.sessionRef?.() ?? options.adapter.sessionId();
             if (initialSession)
@@ -166,7 +148,7 @@ export class ContinuityAdapter {
         }
         this.validatingFreshRecovery = true;
         try {
-            const result = await this.sendTurn("Fresh recovery validation only. Do not use tools, change files, implement work, or request a handoff. Acknowledge this new session and emit the required continuity record using only the supplied instructions.", { responseOnly: true });
+            const result = await withFreshRecoveryValidation(this.options.projectDir, this.options.runId, this.options.role, authorization => this.sendTurn("Fresh recovery validation only. Do not use tools, change files, implement work, or request a handoff. Acknowledge this new session and include the required continuity object. " + operationInstruction(initializationOutput), nativePolicy(initializationOutput, { responseOnly: true, journalRunId: this.options.runId, dispatchId: `fresh-recovery:${authorization.decisionDigest}` })));
             if (result.isError || result.failure || this.recoveryLeasePending)
                 throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh recovery did not establish a valid continuity checkpoint");
         }
@@ -179,47 +161,84 @@ export class ContinuityAdapter {
         }
     }
     get agent() { return this.adapter.agent; }
+    /** Every confirmed dispatch publishes a checkpoint, so continuity is mandatory. */
+    structuredDispatchRequirement() {
+        return { instruction: CONTINUITY_REQUIRED_INSTRUCTION, validate: response => { validateContinuityDelta(response.continuity); } };
+    }
     async sendTurn(instruction, policy) {
-        return withGraphSessionAccess(this.options.projectDir, this.adapter, () => this.sendTurnOwned(instruction, policy));
+        if (!policy?.output)
+            throw new Error("Continuity dispatch requires a native operation contract");
+        if (policy.dispatchCapability) {
+            assertSealedDispatch(this.options.projectDir, policy.dispatchCapability, policy.selectedDispatch, instruction);
+            return this.sendTurnOwned(instruction, policy);
+        }
+        // The continuity requirement is applied by journalStructuredDispatch through
+        // structuredDispatchRequirement(), before sealing, on every dispatch path.
+        const hostInstruction = instruction;
+        return withGraphSessionAccess(this.options.projectDir, this.adapter, () => policy?.output
+            ? journalStructuredDispatch(this.options.projectDir, this, instruction, { ...policy, journalRunId: policy.journalRunId ?? this.options.runId }, (text, selected) => this.sendTurnOwned(text, selected))
+            : this.sendTurnOwned(instruction, policy)).then(result => {
+            if (result.failure?.category === "session-unavailable") {
+                this.recordSessionUnavailable(result.failure, hostInstruction);
+                throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, result.failure);
+            }
+            return { ...result, hostInstruction };
+        });
     }
     async sendTurnOwned(instruction, policy) {
-        const providerInstruction = `${instruction}\n\n${continuityInstruction(this.options.role)}`;
+        const providerInstruction = instruction;
         const journal = new WorkflowDb(this.options.projectDir);
-        const dispatchId = `dispatch:${this.options.runId}:${this.options.role}:${randomUUID()}`;
+        const dispatchId = policy?.dispatchId ?? `dispatch:${this.options.runId}:${this.options.role}:${randomUUID()}`;
+        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).length)
-                    throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "a previous dispatched turn has no durable completion; reconcile it before sending more work");
-                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) } });
-                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));
             }
             catch (error) {
-                journal.updateOperation(dispatchId, "uncertain", { error: String(error) });
+                if (!policy?.selectedDispatch)
+                    journal.updateOperation(dispatchId, "uncertain", { error: String(error) });
                 throw error;
             }
-            const responseDigest = journal.putEvidence("handoff", original.rawResponse ?? original.text);
+            // Preserve the native transport result before interpreting it or publishing
+            // a checkpoint. The outer journal remains the sole completion owner.
+            // journalStructuredDispatch owns the one retained raw receipt for native
+            // turns. Continuity records retain only its durable reference/fact.
+            const responseDigest = policy?.selectedDispatch ? undefined : journal.putEvidence("handoff", Buffer.from(JSON.stringify(original)));
             journal.atomic(() => {
-                journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : original.failure?.dispatchState === "not-sent" ? "failed" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
+                journal.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind: "provider_response_received",
+                    payload: { dispatchId, ...(responseDigest ? { responseDigest } : { journalOwnedEvidence: true }) }, authoritativeStateRevision: this.revision() });
+                if (!policy?.selectedDispatch)
+                    journal.updateOperation(dispatchId, original.failure?.dispatchState === "unknown" ? "uncertain" : original.failure?.dispatchState === "not-sent" ? "failed" : "confirmed", { result: { responseDigest, isError: original.isError, failure: original.failure, turnId: original.turnId, sessionRef: this.adapter.sessionRef?.() } });
                 if (original.failure?.dispatchState === "not-sent")
                     journal.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind: "turn_not_sent", payload: { dispatchId, role: this.options.role }, authoritativeStateRevision: this.revision() });
             });
@@ -227,152 +246,162 @@ export class ContinuityAdapter {
         finally {
             journal.close();
         }
-        if (policy?.handback) {
-            const parsed = parseContinuityDelta(original.rawResponse ?? original.text);
-            // The delivery journal owns the sole repair allowance and validates execution
-            // before a checkpoint is published. Never transfer/replay inside this turn.
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction,
-                providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText,
-                continuityErrors: parsed.error?.problems ?? [] };
+        return original;
+    }
+    async postConfirmedDispatch(reference) {
+        const db = new WorkflowDb(this.options.projectDir);
+        let original;
+        let context;
+        let response;
+        try {
+            const operation = db.operation(reference.dispatchId);
+            if (operation?.runId !== this.options.runId || reference.runId !== this.options.runId || db.structuredOwnerDispatch(reference.dispatchId).tupleDigest !== reference.tupleDigest)
+                throw new Error("Continuity postprocessing belongs to a foreign dispatch");
+            original = db.retainedStructuredTurn(reference.dispatchId);
+            context = db.structuredProcessingContext(reference.dispatchId);
+            const tuple = original.selectedDispatch;
+            const contract = persistedProviderWireContract(tuple).canonical;
+            response = db.replayStructuredDispatch(reference.dispatchId, contract);
         }
-        const activeSession = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
-        if (activeSession) {
-            const leaseDb = new WorkflowDb(this.options.projectDir);
+        finally {
+            db.close();
+        }
+        const delta = validateContinuityDelta(response.continuity);
+        if (this.recoveryLeasePending && (response.result.kind !== "completed" || !response.result.payload.ready))
+            throw new Error("Fresh recovery requires a completed initialization checkpoint");
+        if (!context.policy.handback) {
+            this.publish(delta, "turn_completed", original);
+        }
+        if (response.result.kind === "handoff-request") {
+            if (context.policy.handback || this.options.durableSingleTurn || this.validatingFreshRecovery)
+                throw new Error("This operation cannot transfer its session");
+            // Publication is complete before the explicitly linked acceptance stage.
+            const completed = new WorkflowDb(this.options.projectDir);
             try {
-                leaseDb.claimInitialRoleLease(this.options.runId, this.options.role, activeSession);
+                completed.beginStructuredHandoff(reference.dispatchId);
+                completed.completeStructuredPostprocessing(reference.dispatchId);
             }
             finally {
-                leaseDb.close();
+                completed.close();
             }
-        }
-        if (original.failure?.category === "session-unavailable") {
-            this.recordSessionUnavailable(original.failure, instruction);
-            throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, original.failure);
-        }
-        if (original.isError || original.failure)
-            return original;
-        const parsed = parseContinuityDelta(original.text);
-        if (parsed.delta && !original.isError && !original.failure) {
-            this.publish(parsed.delta, "turn_completed", original);
-            this.moveRecoveryLeaseAfterCheckpoint();
-            if (this.options.durableSingleTurn || this.validatingFreshRecovery) {
-                return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                    rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            const successor = await this.options.handleHandoffRequest?.({ version: 1, reason: response.result.reason, roleState: response.result.roleState, delta, predecessorDispatchId: reference.dispatchId }, this.adapter, context.instruction);
+            if (!successor || successor === this.adapter)
+                throw new Error("Handoff request did not establish a validated successor");
+            const continuation = new WorkflowDb(this.options.projectDir);
+            let continuationId;
+            try {
+                const session = successor.sessionRef?.();
+                if (!session)
+                    throw new Error("Handoff successor has no scoped session");
+                continuationId = continuation.planStructuredContinuation(reference.dispatchId, session);
             }
-            const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
-            if (successor && successor !== this.adapter) {
-                await this.adoptValidatedSuccessor(successor);
-                return this.sendTurn([
-                    "Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.",
-                    instruction,
-                ].join("\n\n"), policy);
+            finally {
+                continuation.close();
             }
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            await this.adoptValidatedSuccessor(successor);
+            const tuple = original.selectedDispatch;
+            const output = persistedProviderWireContract(tuple).canonical;
+            return this.sendTurn("Continue the frozen action after the accepted handoff. Reconcile receipts; do not repeat completed side effects.\n" + context.instruction, nativePolicy(output, { ...continuationPolicy(context.policy, reference.dispatchId), dispatchId: continuationId }));
         }
-        if (this.options.durableSingleTurn || (this.validatingFreshRecovery && this.recoveryLeasePending && policy?.responseOnly)) {
-            const invalidDb = new WorkflowDb(this.options.projectDir);
+        return { ...original, hostInstruction: context.instruction, continuityErrors: [], continuity: delta };
+    }
+    observeEvents(listener) {
+        if (!this.adapter.observeEvents)
+            throw new Error("wrapped provider does not expose turn observation");
+        return this.adapter.observeEvents(listener);
+    }
+    acceptHandbackTurn(turn) {
+        if (turn.structured) {
+            if (turn.isError || turn.failure || turn.structured.state !== "candidate")
+                throw new Error("cannot publish an invalid handback checkpoint");
+            const db = new WorkflowDb(this.options.projectDir);
+            let retained;
+            try {
+                if (!turn.selectedDispatch || db.operation(turn.selectedDispatch.dispatchId)?.runId !== this.options.runId)
+                    throw new Error("Foreign handback dispatch");
+                retained = db.retainedStructuredTurn(turn.selectedDispatch.dispatchId);
+            }
+            finally {
+                db.close();
+            }
+            const tuple = retained.selectedDispatch;
+            const owner = new WorkflowDb(this.options.projectDir);
             try {
-                invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid", payload: { problems: parsed.error?.problems }, authoritativeStateRevision: this.revision() });
+                const response = verifyPersistedDispatch(persistedProviderWireContract(tuple).canonical, owner.structuredOwnerDispatch(tuple.dispatchId), retained.structured, tuple);
+                this.publish(validateContinuityDelta(response.continuity), "handback_turn_completed", retained);
             }
             finally {
-                invalidDb.close();
+                owner.close();
             }
-            return { ...original, isError: true, continuityErrors: parsed.error?.problems ?? ["unknown continuity error"], text: `QA continuity record was invalid: ${parsed.error?.problems.join("; ") ?? "unknown error"}`,
-                hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            return;
         }
-        const budget = new WorkflowDb(this.options.projectDir);
+        throw new Error("Handback acceptance requires a native receipt and validated continuity");
+    }
+    /** Explicit restart recovery of the already accepted action; never repeats acceptance. */
+    async resumePlannedContinuation() {
+        const db = new WorkflowDb(this.options.projectDir);
+        let continuation;
+        let context;
+        let output;
         try {
-            const maximum = budget.autonomyPolicy(this.options.runId)?.limits.protocolCorrections ?? 1;
-            if (!budget.reserveRecoveryAllowance(this.options.runId, policy?.logicalActionId ?? sha(instruction), "protocol-correction", maximum)) {
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "shared protocol correction budget exhausted");
+            continuation = db.structuredContinuation(this.options.runId, this.options.role);
+            if (!continuation)
+                return;
+            const operation = db.operation(continuation.continuationId);
+            if (operation?.status === "confirmed") {
+                if (db.pendingStructuredPostprocessing(this.options.runId).includes(continuation.continuationId)) {
+                    await this.postConfirmedDispatch({ dispatchId: continuation.continuationId, runId: this.options.runId,
+                        tupleDigest: db.structuredOwnerDispatch(continuation.continuationId).tupleDigest });
+                    db.completeStructuredPostprocessing(continuation.continuationId);
+                    db.finishStructuredContinuation(continuation.continuationId);
+                }
+                const turn = db.retainedStructuredTurn(continuation.continuationId);
+                const descriptor = persistedProviderWireContract(turn.selectedDispatch);
+                const response = db.replayStructuredDispatch(continuation.continuationId, descriptor.canonical);
+                return { ...turn, continuity: validateContinuityDelta(response.continuity) };
             }
+            if (continuation.state !== "continuation-planned" || operation && operation.status !== "planned")
+                throw new Error("Continuation may already have been submitted; explicit reconciliation is required");
+            const current = this.adapter.sessionRef?.();
+            if (!current || providerSessionKey(current) !== providerSessionKey(continuation.successor))
+                throw new Error("Reattach the durably accepted successor before continuation recovery");
+            context = db.structuredProcessingContext(continuation.predecessorId);
+            const predecessor = db.retainedStructuredTurn(continuation.predecessorId);
+            output = persistedProviderWireContract(predecessor.selectedDispatch).canonical;
         }
         finally {
-            budget.close();
-        }
-        const repair = await dispatchWithGraphAccess(this.options.projectDir, this.adapter, [
-            "Continuity protocol repair only. Do not run tools, repeat work, or change files.",
-            `Your prior turn's continuity record was invalid: ${parsed.error?.problems.join("; ")}.`,
-            continuityInstruction(),
-            "Return only the continuity record.",
-        ].join("\n"), { ...policy, purpose: "response-repair", responseOnly: true }, (text, p) => this.adapter.sendTurn(text, p));
-        const repaired = parseContinuityDelta(repair.text);
-        if (repaired.delta && !repair.isError && !repair.failure) {
-            this.publish(repaired.delta, "turn_completed_after_repair", original);
-            this.moveRecoveryLeaseAfterCheckpoint();
-            const successor = await this.options.handleHandoffRequest?.(original.text, this.adapter, instruction);
-            if (successor && successor !== this.adapter) {
-                await this.adoptValidatedSuccessor(successor);
-                return this.sendTurn(["Continue the frozen action after the accepted Rafi handoff. Do not repeat completed side effects.", instruction].join("\n\n"), policy);
-            }
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction: original.providerInstruction ?? providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
+            db.close();
         }
-        const invalidDb = new WorkflowDb(this.options.projectDir);
+        return this.sendTurn("Continue the frozen action after the accepted handoff. Reconcile receipts; do not repeat completed side effects.\n" + context.instruction, nativePolicy(output, { ...continuationPolicy(context.policy, continuation.predecessorId), dispatchId: continuation.continuationId }));
+    }
+    async recoverConfirmedPublications() {
+        const db = new WorkflowDb(this.options.projectDir);
+        let pending;
         try {
-            invalidDb.appendContinuityEvent({ runId: this.options.runId, role: "host", kind: "continuity_invalid_twice", payload: { original: parsed.error?.problems, repair: repaired.error?.problems }, authoritativeStateRevision: this.revision() });
-            invalidDb.setContinuityHeadState(this.options.runId, this.options.role, "invalid");
+            pending = db.pendingStructuredPostprocessing(this.options.runId);
         }
         finally {
-            invalidDb.close();
+            db.close();
         }
-        const handoff = this.reconstructionHandoff();
-        if (this.options.recoverWithHandoff) {
-            let successor;
+        for (const dispatchId of pending) {
+            const current = new WorkflowDb(this.options.projectDir);
+            let reference;
             try {
-                successor = await this.options.recoverWithHandoff({
-                    reason: "continuity delta and same-session repair were both invalid",
-                    reconstruction: handoff,
-                    predecessor: this.adapter,
-                });
+                reference = { dispatchId, runId: this.options.runId, tupleDigest: current.structuredOwnerDispatch(dispatchId).tupleDigest };
             }
-            catch (error) {
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, `fresh validated successor also failed after the same-session repair: ${error instanceof Error ? error.message : String(error)}`);
+            finally {
+                current.close();
             }
-            if (!successor.sessionId() || successor.sessionId() === this.adapter.sessionId()) {
-                await successor.close().catch(() => { });
-                throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "validated recovery callback did not return a genuinely fresh successor");
+            await this.postConfirmedDispatch(reference);
+            const completed = new WorkflowDb(this.options.projectDir);
+            try {
+                completed.completeStructuredPostprocessing(dispatchId);
+                completed.finishStructuredContinuation(dispatchId);
+            }
+            finally {
+                completed.close();
             }
-            await this.adoptValidatedSuccessor(successor);
-            return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
-                rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
-        }
-        if (!this.options.createSuccessor)
-            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "continuity repair failed in the original session and no validated successor is configured");
-        const successor = await this.options.createSuccessor(handoff);
-        const accepted = await dispatchWithGraphAccess(this.options.projectDir, successor, `${handoff}\n\nReply with HANDOFF_ACCEPTED on the first line, then ${continuityInstruction()}`, { purpose: "contract-acceptance", responseOnly: true }, (text, p) => successor.sendTurn(text, p));
-        const successorDelta = parseContinuityDelta(accepted.text);
-        const firstAcceptanceLine = accepted.text.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
-        if (firstAcceptanceLine !== "HANDOFF_ACCEPTED" || !successorDelta.delta || !successor.sessionId()) {
-            await successor.close().catch(() => { });
-            throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "fresh successor did not validate and accept the cumulative checkpoint");
-        }
-        await this.adoptValidatedSuccessor(successor);
-        this.publish(successorDelta.delta, "fresh_successor_accepted", accepted);
-        const leaseDb = new WorkflowDb(this.options.projectDir);
-        try {
-            leaseDb.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, successor.sessionRef?.() ?? successor.sessionId(), "double-invalid continuity recovery");
-        }
-        finally {
-            leaseDb.close();
         }
-        return { ...original, text: parsed.cleanText, hostInstruction: instruction, providerInstruction,
-            rawResponse: original.rawResponse ?? original.text, cleanedResponse: parsed.cleanText };
-    }
-    observeEvents(listener) {
-        if (!this.adapter.observeEvents)
-            throw new Error("wrapped provider does not expose turn observation");
-        return this.adapter.observeEvents(listener);
-    }
-    acceptHandbackTurn(turn) {
-        const parsed = parseContinuityDelta(turn.rawResponse ?? turn.text);
-        if (turn.isError || turn.failure || !parsed.delta)
-            throw new Error("cannot publish an invalid handback checkpoint");
-        this.publish(parsed.delta, "handback_turn_completed", turn);
-        this.moveRecoveryLeaseAfterCheckpoint();
     }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
@@ -422,30 +451,32 @@ export class ContinuityAdapter {
         const db = new WorkflowDb(this.options.projectDir);
         try {
             const sessionRef = this.adapter.sessionRef?.();
-            return db.atomic(() => {
-                db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
-                return db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef });
+            let moved = false;
+            const checkpoint = db.atomic(() => {
+                if (this.recoveryLeasePending && sessionRef)
+                    db.assertFreshRecoveryValidation(result.selectedDispatch.dispatchId, sessionRef);
+                const prior = db.providerCheckpoint(result.selectedDispatch.dispatchId, kind);
+                if (prior) {
+                    if (JSON.stringify(prior.delta) !== JSON.stringify(delta))
+                        throw new Error("Conflicting repeated continuity publication");
+                    return prior;
+                }
+                db.appendContinuityEvent({ runId: this.options.runId, role: this.options.role, kind, payload: { dispatchId: result.selectedDispatch.dispatchId, isError: result.isError, numTurns: result.numTurns, sessionId: this.adapter.sessionId(), sessionRef, delta }, authoritativeStateRevision: this.revision(), sessionRef });
+                const published = db.publishContinuityCheckpoint({ runId: this.options.runId, role: this.options.role, delta, authoritativeStateRevision: this.revision(), sessionRef, origin: { kind: "provider", dispatchId: result.selectedDispatch.dispatchId, publicationKind: kind } });
+                if (this.recoveryLeasePending && sessionRef) {
+                    db.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, sessionRef, "explicit fresh-recovery-only continuation");
+                    moved = true;
+                }
+                return published;
             });
+            if (moved)
+                this.recoveryLeasePending = false;
+            return checkpoint;
         }
         finally {
             db.close();
         }
     }
-    moveRecoveryLeaseAfterCheckpoint() {
-        if (!this.recoveryLeasePending)
-            return;
-        const session = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
-        if (!session)
-            return;
-        const db = new WorkflowDb(this.options.projectDir);
-        try {
-            db.moveRoleLeaseAfterValidatedRecovery(this.options.runId, this.options.role, session, "explicit fresh-recovery-only continuation");
-        }
-        finally {
-            db.close();
-        }
-        this.recoveryLeasePending = false;
-    }
     recordSessionUnavailable(failure, instruction) {
         const sessionRef = this.adapter.sessionRef?.();
         const db = new WorkflowDb(this.options.projectDir);
@@ -473,22 +504,6 @@ export class ContinuityAdapter {
             db.close();
         }
     }
-    reconstructionHandoff() {
-        const db = new WorkflowDb(this.options.projectDir);
-        try {
-            const checkpoints = db.continuityCheckpoints(this.options.runId, this.options.role);
-            const events = db.continuityEvents(this.options.runId, checkpoints.at(-1)?.sequence ?? 0);
-            return [
-                `Validated cumulative recovery for run ${this.options.runId}, role ${this.options.role}.`,
-                JSON.stringify(mergeContinuityDeltas(checkpoints.map((checkpoint) => checkpoint.delta))),
-                `Later host facts: ${JSON.stringify(events.map((event) => ({ kind: event.kind, payload: event.payload, digest: event.digest })))}`,
-                "The prior in-flight operation is unknown unless a host fact proves completion. Reconcile receipts before retrying side effects.",
-            ].join("\n\n");
-        }
-        finally {
-            db.close();
-        }
-    }
     revision() { return this.options.authoritativeStateRevision?.() ?? this.options.settings.settings_revision; }
     pumpEvents() {
         const source = this.adapter;