ai-foreman 1.7.7 → 1.7.8

package/dist/cli/start.js

@@ -625,6 +625,13 @@ export function buildStartCommand() {
                 fast: builderFast,
                 systemPromptAppend: roleBundle.system || undefined,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+                contextManagementPolicy: {
+                    role: "builder",
+                    configuredThresholdPercent: thresholdOverride ?? roleDefaults.builder?.auto_compact_threshold_percent ?? 50,
+                    compactMaximum: roleDefaults.builder?.compact_maximum ?? 10,
+                    settingsRevision,
+                    model: model ?? "default",
+                },
             };
             const adapter = agent === "codex"
                 ? new CodexAdapter(adapterOpts)
@@ -641,6 +648,7 @@ export function buildStartCommand() {
         let activeContinuityRunId;
         let liveStatusReporter;
         let activeBuilderForStatus;
+        let activeBuilderContextSnapshot;
         const resolvedContinuitySettings = (role) => role === "builder" ? {
             role, source: roleDefaults.builder ? "project" : "provider", make: agent, model: model ?? "default",
             reasoning: builderEffort ?? "default", fast: Boolean(builderFast), session_strategy: roleDefaults.builder?.session_strategy ?? "compact",
@@ -651,27 +659,70 @@ export function buildStartCommand() {
             role, source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default",
             reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact",
             settings_revision: settingsRevision, display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false,
-            auto_compact_threshold_percent: 50, compact_maximum: 10,
+            auto_compact_threshold_percent: roleDefaults.qa?.auto_compact_threshold_percent ?? 50,
+            compact_maximum: roleDefaults.qa?.compact_maximum ?? 10,
+        };
+        const liveRoleFields = [
+            "make", "model", "reasoning", "fast", "session_strategy", "display_session_cost",
+            "auto_compact_threshold_percent", "compact_maximum",
+        ];
+        const observedRoleDefaults = {
+            builder: { ...(roleDefaults.builder ?? {}) },
+            qa: { ...(roleDefaults.qa ?? {}) },
+        };
+        const observedProjectRevision = { builder: settingsRevision, qa: settingsRevision };
+        const effectiveRoleRevision = { builder: settingsRevision, qa: settingsRevision };
+        const liveRoleOverrides = {
+            builder: new Map(),
+            qa: new Map(),
         };
         const liveRoleSettings = (role, base) => {
             const live = readAgentDefaults(cwd);
             const revision = live.revision ?? 0;
-            if (revision <= base.settings_revision)
-                return base;
             const defaults = role === "builder" ? live.builder : live.qa;
-            return {
+            if (revision > observedProjectRevision[role]) {
+                const prior = observedRoleDefaults[role];
+                let roleChanged = false;
+                for (const field of liveRoleFields) {
+                    const value = defaults?.[field];
+                    if (!Object.is(value, prior[field])) {
+                        liveRoleOverrides[role].set(field, value);
+                        roleChanged = true;
+                    }
+                }
+                const revisionDb = new WorkflowDb(cwd);
+                let targetedFields;
+                try {
+                    targetedFields = revisionDb.projectSettingsRevisionTargets(revision)[role] ?? [];
+                }
+                finally {
+                    revisionDb.close();
+                }
+                for (const field of targetedFields) {
+                    if (liveRoleFields.includes(field)) {
+                        const typedField = field;
+                        liveRoleOverrides[role].set(typedField, defaults?.[typedField]);
+                    }
+                }
+                observedRoleDefaults[role] = { ...(defaults ?? {}) };
+                observedProjectRevision[role] = revision;
+                if (roleChanged || targetedFields.length)
+                    effectiveRoleRevision[role] = revision;
+            }
+            if (effectiveRoleRevision[role] <= base.settings_revision)
+                return base;
+            const merged = {
                 ...base,
                 source: defaults ? "project" : base.source,
-                make: defaults?.make ?? base.make,
-                model: defaults?.model ?? base.model,
-                reasoning: defaults?.reasoning ?? base.reasoning,
-                fast: defaults?.fast ?? base.fast,
-                session_strategy: defaults?.session_strategy ?? base.session_strategy,
-                display_session_cost: defaults?.display_session_cost ?? base.display_session_cost,
-                auto_compact_threshold_percent: defaults?.auto_compact_threshold_percent ?? base.auto_compact_threshold_percent,
-                compact_maximum: defaults?.compact_maximum ?? base.compact_maximum,
-                settings_revision: revision,
+                settings_revision: effectiveRoleRevision[role],
             };
+            const mutable = merged;
+            for (const [field, value] of liveRoleOverrides[role]) {
+                if (value === undefined)
+                    continue;
+                mutable[field] = value;
+            }
+            return merged;
         };
         const createBuilderForSettings = async (builderCwd, settings) => {
             const ready = await ensureRuntimeReadyForCommand(builderCwd, settings.make, {
@@ -696,6 +747,10 @@ export function buildStartCommand() {
                 fast: settings.fast,
                 systemPromptAppend: roleBundle.system || undefined,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+                contextManagementPolicy: {
+                    role: "builder", configuredThresholdPercent: settings.auto_compact_threshold_percent,
+                    compactMaximum: settings.compact_maximum, settingsRevision: settings.settings_revision, model: settings.model,
+                },
             };
             const created = settings.make === "codex" ? new CodexAdapter(adapterOptions) : await ClaudeAdapter.create(adapterOptions);
             return !branchMode ? new CurrentWorkflowGuardAdapter(created, builderCwd) : created;
@@ -722,6 +777,10 @@ export function buildStartCommand() {
                 fast: settings.fast,
                 systemPromptAppend: `${roleBundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+                contextManagementPolicy: {
+                    role: "qa", configuredThresholdPercent: settings.auto_compact_threshold_percent,
+                    compactMaximum: settings.compact_maximum, settingsRevision: settings.settings_revision, model: settings.model,
+                },
             };
             return settings.make === "codex" ? new CodexAdapter(adapterOptions) : await ClaudeAdapter.create(adapterOptions);
         };
@@ -928,6 +987,13 @@ export function buildStartCommand() {
                 fast: qaFast,
                 systemPromptAppend: `${roleBundle.system}\n\nYou are an independent QA reviewer. Do not edit source, tickets, configuration, or project documentation. You may run tests and create only harmless ignored caches or coverage output.`,
                 skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
+                contextManagementPolicy: {
+                    role: "qa",
+                    configuredThresholdPercent: roleDefaults.qa?.auto_compact_threshold_percent ?? 50,
+                    compactMaximum: roleDefaults.qa?.compact_maximum ?? 10,
+                    settingsRevision,
+                    model: qaModel ?? "default",
+                },
             };
             return qaAgent === "codex"
                 ? new CodexAdapter(adapterOpts)
@@ -1048,6 +1114,7 @@ export function buildStartCommand() {
                         finally {
                             db.close();
                         } },
+                        contextSnapshot: activeBuilderContextSnapshot,
                     });
             });
         };
@@ -1151,6 +1218,7 @@ export function buildStartCommand() {
                 projectDir: cwd,
                 runId: activeContinuityRunId,
                 role: "qa",
+                requireNativeContextManagement: true,
                 initialSettings: qaSettings,
                 historicalCountUncertain: Boolean(recoveryRecord && (recoveryRecord.legacy || !recoveryRecord.runDecisions)),
                 readSettings: () => liveRoleSettings("qa", qaSettings),
@@ -1163,6 +1231,7 @@ export function buildStartCommand() {
                 report: (event) => {
                     currentActivity()?.update(event.kind, event.detail, { provider: qaSettings.make, model: qaSettings.model });
                     log.write("context-lifecycle", { role: "qa", ...event, sample: event.sample });
+                    void liveStatusReporter?.tick();
                 },
                 handoff: async ({ reason, adapter: predecessor, sample, settings, compactionCount }) => {
                     const nativeUsage = await predecessor.sessionUsage?.().catch(() => undefined);
@@ -1183,6 +1252,7 @@ export function buildStartCommand() {
                     return decorateQa(transfer.successor, qaCwd, undefined, settings);
                 },
             });
+            liveStatusReporter?.updateState({ contextSnapshot: () => controller.contextSnapshot() });
             return (await controller.atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter;
         };
         const qaNonconvergence = createQaNonconvergenceHandler(cwd, Boolean(opts.yes), roleDefaults.planner);
@@ -1286,12 +1356,68 @@ export function buildStartCommand() {
                 });
                 let auditBuilder;
                 let auditViewer;
+                let auditCompleted = false;
                 const auditRunId = `audit-${stamp}`;
                 activeContinuityRunId = auditRunId;
                 try {
+                    const auditSettings = resolvedContinuitySettings("builder");
+                    const auditInstruction = buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket));
+                    const auditDb = new WorkflowDb(cwd);
+                    try {
+                        auditDb.ensureRun(auditRunId);
+                        auditDb.appendContinuityEvent({
+                            runId: auditRunId, role: "host", kind: "branch_audit_initialized",
+                            payload: { frozenActionDigest: createHash("sha256").update(auditInstruction).digest("hex") },
+                            authoritativeStateRevision: auditSettings.settings_revision,
+                        });
+                        auditDb.publishContinuityCheckpoint({
+                            runId: auditRunId, role: "builder", authoritativeStateRevision: auditSettings.settings_revision,
+                            delta: {
+                                version: 1, decisions: [], constraints: [], discoveries: [], completedActions: [], evidence: [], failures: [], blockers: [],
+                                openWork: ["complete the selected-ticket dependency audit"], nextAction: "complete the selected-ticket dependency audit",
+                            },
+                        });
+                    }
+                    finally {
+                        auditDb.close();
+                    }
                     auditBuilder = await createBuilder(cwd);
+                    const auditController = RoleSessionController.managed({
+                        projectDir: cwd, runId: auditRunId, role: "builder", initialSettings: auditSettings,
+                        requireNativeContextManagement: true,
+                        readSettings: () => liveRoleSettings("builder", auditSettings),
+                        settingsBoundary: (input) => applyBuilderSettingsBoundary(auditRunId, cwd, input),
+                        report: (event) => log.write("context-lifecycle", { phase: "branch-audit", ...event, sample: event.sample }),
+                        handoff: async ({ reason, adapter, sample, settings, compactionCount, frozenAction }) => {
+                            const nativeUsage = await adapter.sessionUsage?.().catch(() => undefined);
+                            const transfer = await new HandoffService(cwd).transfer({
+                                runId: auditRunId, role: "builder", reason, predecessorSessionId: adapter.sessionId(), predecessorSessionRef: adapter.sessionRef?.(),
+                                roleState: { phase: "branch-audit", frozenActionDigest: createHash("sha256").update(frozenAction).digest("hex"), contextSample: sample },
+                                ...(nativeUsage ? { sessionUsage: {
+                                        version: 1, runId: auditRunId, role: "builder", provider: adapter.agent,
+                                        providerSessionId: adapter.sessionId(), observedAt: nativeUsage.observedAt, source: nativeUsage.source,
+                                        cumulativeInputTokens: nativeUsage.inputTokens, cumulativeOutputTokens: nativeUsage.outputTokens,
+                                        cumulativeTotalTokens: nativeUsage.totalTokens, authoritativeCostUsd: nativeUsage.authoritativeCostUsd,
+                                    } } : {}),
+                                compactionCount, compactMaximum: settings.compact_maximum,
+                                resources: [{ label: "frozen-branch-audit", content: frozenAction, authoritative: true }],
+                            }, () => createBuilderForSettings(cwd, settings));
+                            log.write("handoff-transfer", {
+                                phase: "branch-audit", reason, generation: transfer.manifest.generation,
+                                predecessorSessionId: transfer.manifest.predecessorSessionId, successorSessionId: transfer.successorSessionId,
+                                acceptanceCheckpointDigest: transfer.acceptanceCheckpointDigest,
+                            });
+                            if (adapter instanceof ContinuityAdapter) {
+                                await adapter.adoptValidatedSuccessor(transfer.successor);
+                                return adapter;
+                            }
+                            await adapter.close().catch(() => { });
+                            return continuousBuilder(transfer.successor, cwd, auditRunId, settings);
+                        },
+                    });
+                    auditBuilder = (await auditController.atSafeBoundary(auditBuilder, auditInstruction)).adapter;
                     auditViewer = printEvents(auditBuilder.events());
-                    const audit = await auditBuilder.sendTurn(buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket)));
+                    const audit = await auditBuilder.sendTurn(auditInstruction);
                     if (audit.isError)
                         throw new Error(audit.text);
                     const auditDependencies = parseAuditDependencies(audit.text);
@@ -1305,6 +1431,7 @@ export function buildStartCommand() {
                         ticketIds: selectedNewTicket ? [selectedNewTicket] : selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
                     });
                     auditDependencyCount = auditDependencies.length;
+                    auditCompleted = true;
                 }
                 finally {
                     await auditBuilder?.close().catch(() => { });
@@ -1312,7 +1439,9 @@ export function buildStartCommand() {
                     const auditDb = new WorkflowDb(cwd);
                     try {
                         if (auditDb.getRun(auditRunId))
-                            auditDb.transition(auditRunId, { status: "completed", checkpoint: "branch-audit-complete", remainingWork: {}, event: "audit_completed" });
+                            auditDb.transition(auditRunId, auditCompleted
+                                ? { status: "completed", checkpoint: "branch-audit-complete", remainingWork: {}, event: "audit_completed" }
+                                : { status: "paused", checkpoint: "branch-audit-interrupted", remainingWork: { action: "complete the selected-ticket dependency audit" }, event: "audit_interrupted" });
                     }
                     finally {
                         auditDb.close();
@@ -1416,7 +1545,8 @@ export function buildStartCommand() {
                 role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default",
                 reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", settings_revision: settingsRevision,
                 display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false,
-                auto_compact_threshold_percent: 50, compact_maximum: 10,
+                auto_compact_threshold_percent: roleDefaults.qa?.auto_compact_threshold_percent ?? 50,
+                compact_maximum: roleDefaults.qa?.compact_maximum ?? 10,
             };
             const firstResumeRef = plan.nodes[0] ? resumeSessionByTicket.get(plan.nodes[0].ticket.id)?.sessionRef : undefined;
             let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBranchBuilder, qa: capturedBranchQa, builderSessionId: firstResumeRef?.sessionId ?? null, builderSessionRef: firstResumeRef ?? null }) : createBuildRun({
@@ -1432,6 +1562,7 @@ export function buildStartCommand() {
                     return existing;
                 const controller = RoleSessionController.managed({
                     projectDir: cwd, runId: masterRun.runId, role: "builder", initialSettings: capturedBranchBuilder,
+                    requireNativeContextManagement: true,
                     historicalCountUncertain: Boolean(recoveryRecord && (recoveryRecord.legacy || !recoveryRecord.runDecisions)),
                     readSettings: () => liveRoleSettings("builder", capturedBranchBuilder),
                     settingsBoundary: (input) => applyBuilderSettingsBoundary(masterRun.runId, worktreePath, input),
@@ -1440,7 +1571,7 @@ export function buildStartCommand() {
                         adapter: active, settingsRevision: settings.settings_revision, displaySessionCost: settings.display_session_cost,
                         sessionTransition: "adopted live settings",
                     }),
-                    report: (event) => { currentActivity()?.update(event.kind, event.detail, { provider: capturedBranchBuilder.make, model: capturedBranchBuilder.model }); log.write("context-lifecycle", { worktreePath, ...event, sample: event.sample }); },
+                    report: (event) => { currentActivity()?.update(event.kind, event.detail, { provider: capturedBranchBuilder.make, model: capturedBranchBuilder.model }); log.write("context-lifecycle", { worktreePath, ...event, sample: event.sample }); void liveStatusReporter?.tick(); },
                     handoff: async ({ reason, adapter, sample, settings, compactionCount, frozenAction }) => {
                         const nativeUsage = await adapter.sessionUsage?.().catch(() => undefined);
                         const transfer = await new HandoffService(cwd).transfer({
@@ -1492,7 +1623,7 @@ export function buildStartCommand() {
                     archiveDoc: ticketsConfig.paths.archiveDoc,
                 },
                 resumeSessions: resumeSessionByTicket,
-                createBuilder: (builderCwd, sessionId, sessionRef) => createBuilder(builderCwd, sessionId, sessionRef),
+                createBuilder: async (builderCwd, sessionId, sessionRef) => branchContextController(builderCwd).manage(await createBuilder(builderCwd, sessionId, sessionRef)),
                 recordBuilderSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "builder", session); },
                 recordQaSession: (session, ticketId) => { masterRun = persistBuildSession(cwd, { ...masterRun, currentTicket: ticketId }, "qa", session); },
                 onSessionUnavailable: (error) => { branchSessionFailure = error; },
@@ -1502,6 +1633,9 @@ export function buildStartCommand() {
                 observeBuilder: async (builder) => {
                     liveStatusReporter?.stop();
                     activeBuilderForStatus = () => builder;
+                    activeBuilderContextSnapshot = () => [...branchContextControllers.values()]
+                        .map((controller) => controller.contextSnapshot())
+                        .find((snapshot) => snapshot?.contextSample.providerSessionId === builder.sessionId());
                     const reporter = liveStatusReporter = new AgentStatusReporter({
                         runId: masterRun.runId, role: "builder", provider: builder.agent, model: capturedBranchBuilder.model,
                         reasoning: capturedBranchBuilder.reasoning, fast: capturedBranchBuilder.fast, step: Math.min(plan.nodes.length, branchContextControllers.size + 1), total: plan.nodes.length,
@@ -1519,6 +1653,7 @@ export function buildStartCommand() {
                         finally {
                             db.close();
                         } },
+                        contextSnapshot: activeBuilderContextSnapshot,
                     }, (line, snapshot) => {
                         const activity = currentActivity();
                         if (activity && process.stdout.isTTY)
@@ -1529,7 +1664,6 @@ export function buildStartCommand() {
                         const db = new WorkflowDb(cwd);
                         try {
                             db.recordTelemetry(masterRun.runId, snapshot);
-                            db.recordContextSample(snapshot.contextSample);
                             if (snapshot.sessionUsage)
                                 db.recordSessionUsage(snapshot.sessionUsage);
                         }
@@ -1653,7 +1787,7 @@ export function buildStartCommand() {
             auto_compact_threshold_percent: thresholdOverride ?? roleDefaults.builder?.auto_compact_threshold_percent ?? 50,
             compact_maximum: roleDefaults.builder?.compact_maximum ?? 10,
         };
-        const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false, auto_compact_threshold_percent: 50, compact_maximum: 10, settings_revision: settingsRevision };
+        const capturedQa = { role: "qa", source: roleDefaults.qa ? "project" : "provider", make: qaAgent, model: qaModel ?? "default", reasoning: qaEffort ?? "default", fast: qaFast, session_strategy: roleDefaults.qa?.session_strategy ?? "compact", display_session_cost: sessionCostOverride ?? roleDefaults.qa?.display_session_cost ?? false, auto_compact_threshold_percent: roleDefaults.qa?.auto_compact_threshold_percent ?? 50, compact_maximum: roleDefaults.qa?.compact_maximum ?? 10, settings_revision: settingsRevision };
         let buildRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBuilder, qa: capturedQa, builderSessionId: resumeSessionId ?? null, builderSessionRef: resumeSessionRef ?? null }) : createBuildRun({
             tickets: [], repositoryRoot: cwd, branchMode: "current", baseRef: opts.base ?? loadTicketSetupConfig(cwd)?.build.base_branch, builder: capturedBuilder, qa: capturedQa,
             runDecisions: { workMode: "current", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBuilder.auto_compact_threshold_percent ?? 50, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
@@ -1691,6 +1825,7 @@ export function buildStartCommand() {
             projectDir: cwd,
             runId: buildRun.runId,
             role: "builder",
+            requireNativeContextManagement: true,
             initialSettings: capturedBuilder,
             historicalCountUncertain: Boolean(recoveryRecord && (recoveryRecord.legacy || !recoveryRecord.runDecisions)),
             readSettings: () => liveRoleSettings("builder", capturedBuilder),
@@ -1703,6 +1838,7 @@ export function buildStartCommand() {
             report: (event) => {
                 currentActivity()?.update(event.kind, event.detail, { provider: capturedBuilder.make, model: capturedBuilder.model });
                 log.write("context-lifecycle", { ...event, sample: event.sample });
+                void liveStatusReporter?.tick();
             },
             handoff: async ({ reason, adapter, sample, settings, compactionCount, frozenAction }) => {
                 const nativeUsage = await adapter.sessionUsage?.().catch(() => undefined);
@@ -1732,6 +1868,8 @@ export function buildStartCommand() {
                 return continuousBuilder(transfer.successor, cwd, buildRun.runId, settings);
             },
         });
+        builder = contextController.manage(builder);
+        activeBuilderContextSnapshot = () => contextController.contextSnapshot();
         const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd, undefined, qaEnabled ? createQa : undefined, capturedQa.session_strategy, createBuilder, capturedBuilder.session_strategy, qaNonconvergence, async (adapter, frozenAction) => (await contextController.atSafeBoundary(adapter, frozenAction)).adapter, async (adapter, frozenAction, strategy) => (await contextController.atWorkSessionBoundary(adapter, frozenAction, strategy)).adapter, qaSessionBoundary);
         activeBuilderForStatus = () => foreman.builderAdapter();
         const statusReporter = liveStatusReporter = new AgentStatusReporter({
@@ -1753,6 +1891,7 @@ export function buildStartCommand() {
             finally {
                 db.close();
             } },
+            contextSnapshot: () => contextController.contextSnapshot(),
         }, (line, snapshot) => {
             const activity = currentActivity();
             if (activity && process.stdout.isTTY)
@@ -1763,7 +1902,6 @@ export function buildStartCommand() {
             const db = new WorkflowDb(cwd);
             try {
                 db.recordTelemetry(buildRun.runId, snapshot);
-                db.recordContextSample(snapshot.contextSample);
                 if (snapshot.sessionUsage)
                     db.recordSessionUsage(snapshot.sessionUsage);
             }

package/dist/continuity.d.ts

@@ -1,5 +1,5 @@
 import type { ContinuityDelta, ResolvedAgentSettings } from "rafi-spec";
-import type { BuilderAdapter, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, RuntimeFailure, TurnResult } from "./adapters/types.js";
+import type { BuilderAdapter, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, ManagedTurnDispatcher, PreparedContextManagement, ProviderSessionUsage, ProviderSettingSwitch, RuntimeFailure, TurnResult } from "./adapters/types.js";
 export declare const CONTINUITY_MARKER = "RAFI_CONTINUITY_DELTA:";
 export declare class ContinuityValidationError extends Error {
     readonly problems: string[];
@@ -38,7 +38,7 @@ export interface ContinuityAdapterOptions {
     role: "builder" | "qa";
     settings: ResolvedAgentSettings;
     authoritativeStateRevision?: () => number;
-    /** Fresh successor creation after the same-session repair also fails. */
+    /** @deprecated Use recoverWithHandoff so successor acceptance is lifecycle-managed and durable. */
     createSuccessor?: (handoff: string) => Promise<BuilderAdapter>;
     /**
      * Production recovery path for a double-invalid delta. The callback must
@@ -62,6 +62,7 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     private readonly queue;
     private sourcePump?;
     private recoveryLeasePending;
+    private turnDispatcher?;
     constructor(options: ContinuityAdapterOptions);
     get agent(): "claude" | "codex";
     sendTurn(instruction: string): Promise<TurnResult>;
@@ -70,6 +71,10 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     adoptSessionRef(ref: import("rafi-spec").ProviderSessionRefV1): void;
     validateSession(): Promise<import("rafi-spec").SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
+    installManagedTurnDispatcher(dispatcher: ManagedTurnDispatcher): void;
     contextUsage(): Promise<ContextUsage | undefined>;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
@@ -77,6 +82,7 @@ export declare class ContinuityAdapter implements BuilderAdapter {
     close(): Promise<void>;
     /** Keep the observable wrapper and event stream stable while moving to an accepted successor. */
     adoptValidatedSuccessor(successor: BuilderAdapter): Promise<void>;
+    private providerTurn;
     private publish;
     private moveRecoveryLeaseAfterCheckpoint;
     private recordSessionUnavailable;

package/dist/continuity.js

@@ -109,6 +109,7 @@ export class ContinuityAdapter {
     queue = new BuilderEventQueue();
     sourcePump;
     recoveryLeasePending;
+    turnDispatcher;
     constructor(options) {
         this.options = options;
         this.adapter = options.adapter;
@@ -138,7 +139,7 @@ export class ContinuityAdapter {
         finally {
             db.close();
         }
-        const original = await this.adapter.sendTurn(`${instruction}\n\n${continuityInstruction()}`);
+        const original = await this.providerTurn(`${instruction}\n\n${continuityInstruction()}`);
         const activeSession = this.adapter.sessionRef?.() ?? this.adapter.sessionId();
         if (activeSession) {
             const leaseDb = new WorkflowDb(this.options.projectDir);
@@ -153,6 +154,30 @@ export class ContinuityAdapter {
             this.recordSessionUnavailable(original.failure, instruction);
             throw new SessionUnavailableContinuityError(this.options.runId, this.options.role, original.failure);
         }
+        if (original.interrupted?.reason === "compaction-boundary") {
+            // The coordinator owns the validated handoff and replay of this frozen
+            // action. A protocol-repair turn here would run in the interrupted
+            // predecessor (or race successor adoption) without a completed delta.
+            const interruptedDb = new WorkflowDb(this.options.projectDir);
+            try {
+                interruptedDb.appendContinuityEvent({
+                    runId: this.options.runId,
+                    role: "host",
+                    kind: "turn_interrupted_at_compaction_boundary",
+                    payload: {
+                        role: this.options.role,
+                        providerEventId: original.interrupted.providerEventId,
+                        instructionDigest: sha(instruction),
+                    },
+                    authoritativeStateRevision: this.revision(),
+                    sessionRef: this.adapter.sessionRef?.(),
+                });
+            }
+            finally {
+                interruptedDb.close();
+            }
+            return original;
+        }
         const parsed = parseContinuityDelta(original.text);
         if (parsed.delta) {
             this.publish(parsed.delta, "turn_completed", original);
@@ -167,12 +192,37 @@ export class ContinuityAdapter {
             }
             return { ...original, text: parsed.cleanText };
         }
-        const repair = await this.adapter.sendTurn([
+        const repair = await this.providerTurn([
             "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"));
+        if (repair.interrupted?.reason === "compaction-boundary") {
+            // Preserve the predecessor and let the outer managed dispatch perform
+            // the validated handoff/replay. Treating this as another invalid delta
+            // would race continuity recovery against the coordinator and could lose
+            // the original frozen action.
+            const interruptedDb = new WorkflowDb(this.options.projectDir);
+            try {
+                interruptedDb.appendContinuityEvent({
+                    runId: this.options.runId,
+                    role: "host",
+                    kind: "continuity_repair_interrupted_at_compaction_boundary",
+                    payload: {
+                        role: this.options.role,
+                        providerEventId: repair.interrupted.providerEventId,
+                        instructionDigest: sha(instruction),
+                    },
+                    authoritativeStateRevision: this.revision(),
+                    sessionRef: this.adapter.sessionRef?.(),
+                });
+            }
+            finally {
+                interruptedDb.close();
+            }
+            return repair;
+        }
         const repaired = parseContinuityDelta(repair.text);
         if (repaired.delta) {
             this.publish(repaired.delta, "turn_completed_after_repair", original);
@@ -207,31 +257,25 @@ export class ContinuityAdapter {
             await this.adoptValidatedSuccessor(successor);
             return { ...original, text: 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 successor.sendTurn(`${handoff}\n\nReply with HANDOFF_ACCEPTED on the first line, then ${continuityInstruction()}`);
-        const successorDelta = parseContinuityDelta(accepted.text);
-        if (!/^HANDOFF_ACCEPTED\b/m.test(accepted.text) || !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 };
+        // A raw create-and-send fallback cannot install native context control,
+        // account compactions, or validate the scoped successor atomically. Refuse
+        // it instead of allowing continuity recovery to escape the managed gate.
+        throw new ContinuityRecoveryRequiredError(this.options.runId, this.options.role, "continuity repair failed in the original session and no lifecycle-managed recoverWithHandoff callback is configured");
     }
     sessionId() { return this.adapter.sessionId(); }
     sessionRef() { return this.adapter.sessionRef?.(); }
     adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
     validateSession() { return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
     compact() { return this.adapter.compact ? this.adapter.compact() : Promise.resolve({ ok: false, error: "provider adapter does not expose native compaction" }); }
+    prepareContextManagement(policy) { if (!this.adapter.prepareContextManagement)
+        return Promise.reject(new Error("provider adapter does not expose native context management")); return this.adapter.prepareContextManagement(policy); }
+    updateContextManagement(policy) { if (!this.adapter.updateContextManagement)
+        return Promise.reject(new Error("provider adapter does not expose native context reconfiguration")); return this.adapter.updateContextManagement(policy); }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "provider adapter does not expose compaction-boundary interruption", providerEventId }); }
+    installManagedTurnDispatcher(dispatcher) {
+        this.turnDispatcher = dispatcher;
+        this.adapter.installManagedTurnDispatcher?.(dispatcher);
+    }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
     sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     switchSettings(settings) { return this.adapter.switchSettings ? this.adapter.switchSettings(settings) : Promise.resolve({ ok: false, error: "provider adapter does not support settings changes" }); }
@@ -243,9 +287,15 @@ export class ContinuityAdapter {
             return;
         const prior = this.adapter;
         this.adapter = successor;
+        if (this.turnDispatcher)
+            successor.installManagedTurnDispatcher?.(this.turnDispatcher);
         this.pumpEvents();
         await prior.close().catch(() => { });
     }
+    providerTurn(text) {
+        const invoke = () => this.adapter.sendTurn(text);
+        return this.turnDispatcher ? this.turnDispatcher(text, invoke) : invoke();
+    }
     publish(delta, kind, result) {
         const db = new WorkflowDb(this.options.projectDir);
         try {
@@ -322,7 +372,7 @@ export class ContinuityAdapter {
             try {
                 for await (const event of source.events()) {
                     this.queue.push(event);
-                    if (event.kind === "tool" || event.kind === "session-transition" || event.kind === "context-usage") {
+                    if (event.kind === "tool" || event.kind === "session-transition" || event.kind === "context-usage" || event.kind === "context-compaction") {
                         const db = new WorkflowDb(this.options.projectDir);
                         try {
                             const payload = event.kind === "tool"