ai-foreman 1.7.7 → 1.7.8

package/dist/sessionLifecycle.js

@@ -3,6 +3,7 @@ import { SessionUnavailableError, sessionUnavailableErrorFromFailure } from "./a
 import { sanitizeDiagnostics } from "./runtimeReadiness.js";
 import { WorkflowDb } from "./workflowDb.js";
 import { providerSessionKey } from "./sessionIdentity.js";
+import { AsyncQueue } from "./util/asyncQueue.js";
 export class RoleSessionValidationError extends Error {
     role;
     availability;
@@ -59,6 +60,15 @@ export class RoleSessionController {
         this.adapter = result.adapter;
         return result;
     }
+    /** Return the stable role facade whose sendTurn() contains the lifecycle gate. */
+    manage(adapter) {
+        if (!this.thresholdController)
+            throw new Error("this role session controller does not own threshold lifecycle policy");
+        const managed = this.thresholdController.manage(adapter);
+        this.adapter = managed;
+        return managed;
+    }
+    contextSnapshot() { return this.thresholdController?.snapshot(); }
     async atWorkSessionBoundary(adapter, frozenAction, strategy) {
         if (!this.thresholdController)
             throw new Error("this role session controller does not own threshold lifecycle policy");
@@ -137,6 +147,13 @@ export class RoleSessionController {
             const result = this.boundary("missing", validated ? "exact session unavailable; transferred to a validated fresh successor" : "exact session unavailable; used the compatibility fresh fallback", issue);
             return result;
         }
+        if ((this.options.role === "builder" || this.options.role === "qa") && this.options.settings.session_strategy === "compact") {
+            const usage = await this.adapter.contextUsage?.().catch(() => undefined);
+            const percentage = usage?.percentage ?? (usage?.maximum ? usage.used / usage.maximum * 100 : undefined);
+            if (percentage !== undefined && percentage < (this.options.settings.auto_compact_threshold_percent ?? 50)) {
+                return this.boundary("continued", `context ${percentage.toFixed(1)}% remains below the configured ${this.options.settings.auto_compact_threshold_percent ?? 50}% ceiling`);
+            }
+        }
         let firstError = "";
         for (let attempt = 1; attempt <= 2; attempt++) {
             try {
@@ -295,331 +312,1101 @@ export class ContextCapabilityError extends Error {
         this.role = role;
     }
 }
-/** Threshold-triggered native compaction at host-owned safe boundaries. */
+/** Stable facade: every Builder/QA provider turn enters the coordinator here. */
+export class ManagedRoleAdapter {
+    coordinator;
+    adapter;
+    queue = new AsyncQueue();
+    eventPump;
+    processing = Promise.resolve();
+    closed = false;
+    activeSessionKeyValue;
+    constructor(coordinator, adapter) {
+        this.coordinator = coordinator;
+        this.adapter = adapter;
+        this.attachDispatcher(adapter);
+        this.pump(adapter);
+    }
+    get agent() { return this.adapter.agent; }
+    sendTurn(text) { return this.coordinator.dispatch(this, text); }
+    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.coordinator.compactExplicit(this); }
+    prepareContextManagement(policy) { if (!this.adapter.prepareContextManagement)
+        return Promise.reject(new Error("native context management unavailable")); return this.adapter.prepareContextManagement(policy); }
+    updateContextManagement(policy) { if (!this.adapter.updateContextManagement)
+        return Promise.reject(new Error("native context reconfiguration unavailable")); return this.adapter.updateContextManagement(policy); }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "compaction-boundary interruption unavailable", providerEventId }); }
+    contextUsage() { return Promise.resolve(this.coordinator.contextUsage(this)); }
+    sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
+    switchSettings(settings) { return this.adapter.switchSettings?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }
+    events() { return this.queue; }
+    underlying() { return this.adapter; }
+    noteActiveSession(key) {
+        const previous = this.activeSessionKeyValue;
+        this.activeSessionKeyValue = key;
+        return previous !== key ? previous : undefined;
+    }
+    activeSessionKey() { return this.activeSessionKeyValue; }
+    isClosed() { return this.closed; }
+    replace(adapter) {
+        if (adapter === this.adapter)
+            return;
+        this.adapter = adapter;
+        this.attachDispatcher(adapter);
+        this.pump(adapter);
+    }
+    async settleEvents() {
+        // A provider may resolve sendTurn() in the same microtask that enqueues its
+        // final usage/compaction event. Wait until both the event pump and its
+        // serialized coordinator work reach a stable point.
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const processing = this.processing;
+            await Promise.resolve();
+            await processing;
+            await Promise.resolve();
+            if (processing === this.processing)
+                return;
+        }
+        await this.processing;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.coordinator.unregister(this);
+        await this.adapter.close().catch(() => { });
+        await this.eventPump?.catch(() => { });
+        this.queue.close();
+    }
+    pump(source) {
+        this.eventPump = (async () => {
+            try {
+                for await (const event of source.events()) {
+                    if (source !== this.adapter && event.kind !== "turn-complete")
+                        continue;
+                    this.queue.push(event);
+                    this.processing = this.processing.then(() => this.coordinator.observe(this, source, event));
+                    await this.processing;
+                }
+            }
+            catch (error) {
+                if (!this.closed)
+                    this.queue.push({ kind: "error", message: error instanceof Error ? error.message : String(error) });
+            }
+        })();
+    }
+    attachDispatcher(adapter) {
+        adapter.installManagedTurnDispatcher?.((text, invoke) => this.coordinator.dispatchFollowup(this, text, invoke));
+    }
+}
+/** Per-scoped-session context state machine and the sole occupancy sample store. */
 export class ThresholdCompactionController {
     options;
     settings;
-    armed = true;
-    crossing = 0;
-    seenSessions = new Set();
-    runOnlyThreshold;
-    bootstrapScheduled = false;
-    bootstrapRecoveryDepth = 0;
     historicalCountUncertain;
+    managed = new WeakMap();
+    states = new Map();
+    nativeAttempts = new Map();
+    observedCompactionPhases = new Set();
+    settingsWatchers = new WeakMap();
+    active;
+    provisional = 0;
+    refreshingSettings;
+    dispatchDepth = 0;
     constructor(options) {
         this.options = options;
         this.settings = normalizeContextSettings(options.initialSettings);
         this.historicalCountUncertain = Boolean(options.historicalCountUncertain);
     }
+    manage(adapter) {
+        if (adapter instanceof ManagedRoleAdapter && adapter.coordinator === this)
+            return adapter;
+        const existing = this.managed.get(adapter);
+        if (existing)
+            return existing;
+        const wrapper = new ManagedRoleAdapter(this, adapter);
+        this.managed.set(adapter, wrapper);
+        return wrapper;
+    }
     async atSafeBoundary(adapter, frozenAction) {
-        adapter = await this.adoptSettings(adapter, frozenAction);
-        if (!adapter.sessionId() && !this.bootstrapScheduled) {
-            this.bootstrapScheduled = true;
-            const sample = {
-                version: 1, runId: this.options.runId, role: this.options.role, provider: adapter.agent,
-                model: this.settings.model, observedAt: this.now().toISOString(), source: "provider-query", freshness: "measuring",
-                settingsRevision: this.settings.settings_revision, compactionCount: 0, handoffGeneration: this.handoffGeneration(),
-            };
-            const db = new WorkflowDb(this.options.projectDir);
-            try {
-                db.recordContextSample(sample);
-            }
-            finally {
-                db.close();
+        const managed = this.manage(adapter);
+        this.active = managed;
+        await this.refreshSettings(managed, frozenAction, true);
+        let state = await this.ensureInitialized(managed, frozenAction);
+        state = await this.recoverMeasurementFailure(managed, state, frozenAction);
+        if (state.capabilityFailure)
+            throw this.capability(state.capabilityFailure);
+        state = await this.measureIntoState(managed, state, "provider-query").catch((error) => { throw this.capability(error); });
+        if ((state.latest.percentage ?? 100) >= this.threshold()) {
+            return this.enforceThreshold(managed, state, frozenAction, true);
+        }
+        this.transition(state, "armed");
+        return this.result(managed, state, "below-threshold");
+    }
+    async atWorkSessionBoundary(adapter, frozenAction, strategy = this.settings.session_strategy) {
+        const managed = this.manage(adapter);
+        this.active = managed;
+        await this.refreshSettings(managed, frozenAction, true);
+        let state = await this.ensureInitialized(managed, frozenAction);
+        state = await this.recoverMeasurementFailure(managed, state, frozenAction);
+        if (state.capabilityFailure)
+            throw this.capability(state.capabilityFailure);
+        state = await this.measureIntoState(managed, state, "provider-query");
+        if (strategy === "fresh") {
+            return this.performHandoff(managed, state, frozenAction, "ordinary session_strategy=fresh boundary requires a validated fresh successor", false);
+        }
+        // `compact` is a threshold policy, not an unconditional work-boundary compact.
+        if ((state.latest.percentage ?? 100) < this.threshold()) {
+            this.transition(state, "armed");
+            return this.result(managed, state, "below-threshold");
+        }
+        return this.enforceThreshold(managed, state, frozenAction, true);
+    }
+    effectiveSettings() { return this.settings; }
+    effectiveThreshold() { return this.threshold(); }
+    snapshot() {
+        if (!this.active)
+            return undefined;
+        const state = this.stateFor(this.active, false);
+        if (!state)
+            return undefined;
+        return {
+            role: this.options.role, provider: this.active.agent, model: this.settings.model,
+            lifecycleState: state.state, contextSample: state.latest,
+            configuredCeilingPercent: this.threshold(),
+            ...(state.installedNativeTokenLimit === undefined ? {} : { installedNativeTokenLimit: state.installedNativeTokenLimit }),
+            ...(state.installedNativePercent === undefined ? {} : { installedNativePercent: state.installedNativePercent }),
+            compactionCount: state.compactionCount, compactMaximum: this.maximum(), settingsRevision: this.settings.settings_revision,
+        };
+    }
+    contextUsage(adapter) {
+        const state = this.stateFor(adapter, false);
+        if (!state || state.latest.freshness !== "fresh" || state.latest.used === undefined)
+            return undefined;
+        return {
+            used: state.latest.used, maximum: state.latest.maximum, percentage: state.latest.percentage,
+            observedAt: state.latest.observedAt, source: state.latest.source, sequence: state.latest.sequence,
+            sessionId: state.latest.providerSessionId, model: state.latest.model,
+        };
+    }
+    async dispatch(managed, frozenAction, resumed = false) {
+        if (this.dispatchDepth > 0 && this.active === managed) {
+            // Nested role wrappers (for example continuity repair) remain inside the
+            // already-established gate and native policy.
+            return managed.underlying().sendTurn(frozenAction);
+        }
+        this.active = managed;
+        await this.refreshSettings(managed, frozenAction, true);
+        let state = await this.ensureInitialized(managed, frozenAction);
+        state = await this.recoverMeasurementFailure(managed, state, frozenAction);
+        if (state.capabilityFailure)
+            throw this.capability(state.capabilityFailure);
+        if (state.state === "handoff_required") {
+            const moved = await this.performHandoff(managed, state, frozenAction, state.handoffAfterTurn ?? "durable lifecycle recovery requires a validated successor", false);
+            state = this.stateFor(moved.adapter, true);
+        }
+        if ((state.latest.percentage ?? -1) >= this.threshold() || state.state === "threshold_pending" || state.state === "retrying" || state.state === "compacted_unverified") {
+            const enforced = await this.enforceThreshold(managed, state, frozenAction, true);
+            state = this.stateFor(enforced.adapter, true);
+        }
+        let result;
+        this.dispatchDepth += 1;
+        try {
+            result = await managed.underlying().sendTurn(frozenAction);
+        }
+        finally {
+            this.dispatchDepth -= 1;
+        }
+        await managed.settleEvents();
+        // A continuity-owned validated handoff may adopt its successor while the
+        // outer action is still running. Establish independent successor state
+        // before interpreting any post-turn lifecycle flags.
+        state = this.stateFor(managed, false) ?? await this.ensureInitialized(managed, frozenAction);
+        if (state.capabilityFailure) {
+            // The in-flight action settled. Preserve its result, then fence the next turn.
+            this.options.report?.({ kind: "capability-failure", detail: state.capabilityFailure, sample: state.latest });
+            return result;
+        }
+        if (state.boundaryHandoff) {
+            if (!result.interrupted) {
+                state.capabilityFailure = "the provider completed a turn after the compact maximum boundary instead of returning a distinct interrupted result";
+                this.persist(state);
+                return result;
             }
-            return { adapter, action: "continued", sample, effectiveThreshold: this.threshold(), compactionCount: 0 };
+            if (resumed)
+                throw this.capability("a fresh successor immediately repeated a maximum-triggered compaction boundary");
+            await this.performHandoff(managed, state, frozenAction, state.boundaryHandoff.reason, true);
+            return this.dispatch(managed, frozenAction, true);
+        }
+        try {
+            await this.refreshSettings(managed, frozenAction, true);
+        }
+        catch (error) {
+            state.capabilityFailure = sanitize(error);
+            this.persist(state);
+            return result;
+        }
+        try {
+            state = await this.measureIntoState(managed, this.stateFor(managed, true), "provider-query");
+        }
+        catch (error) {
+            state.capabilityFailure = `context measurement failed after provider action: ${sanitize(error)}`;
+            this.persist(state);
+            return result;
+        }
+        if ((state.latest.percentage ?? 100) >= this.threshold() || state.retryAfterTurn || state.handoffAfterTurn) {
+            await this.enforceThreshold(managed, state, frozenAction, true);
+        }
+        return result;
+    }
+    /** Same gate for continuity repair, recursive continuation, and runtime retry. */
+    async dispatchFollowup(managed, frozenAction, invoke) {
+        if (this.dispatchDepth === 0 || this.active !== managed) {
+            throw this.capability("a wrapper attempted a provider follow-up outside the managed role dispatcher");
         }
-        let sample = await this.measure(adapter, "provider-query");
-        const threshold = this.threshold();
-        let session = adapter.sessionRef?.() ?? adapter.sessionId();
-        let sessionKey = adapterSessionKey(adapter);
-        const firstObservedSession = Boolean(sessionKey && !this.seenSessions.has(sessionKey));
-        if (sessionKey)
-            this.seenSessions.add(sessionKey);
+        let state = this.stateFor(managed, false) ?? await this.ensureInitialized(managed, frozenAction);
+        if (state.capabilityFailure)
+            throw this.capability(state.capabilityFailure);
+        if (state.state === "handoff_required") {
+            await this.performHandoff(managed, state, frozenAction, state.handoffAfterTurn ?? "durable lifecycle recovery requires a validated successor", false);
+            state = this.stateFor(managed, true);
+        }
+        if ((state.latest.percentage ?? -1) >= this.threshold()
+            || state.state === "threshold_pending" || state.state === "retrying" || state.state === "compacted_unverified") {
+            await this.enforceThreshold(managed, state, frozenAction, true);
+        }
+        return invoke();
+    }
+    async compactExplicit(managed) {
+        try {
+            const state = await this.ensureInitialized(managed, "explicit native compaction");
+            const result = await this.compactAndVerify(managed, state, "explicit native compaction", true);
+            return { ok: result.action === "compacted" || result.action === "handed-off" };
+        }
+        catch (error) {
+            if (error instanceof SessionUnavailableError)
+                return { ok: false, error: error.message, failure: error.failure };
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    unregister(managed) {
+        this.settingsWatchers.get(managed)?.stop();
+        this.settingsWatchers.delete(managed);
+        const sessionKey = managed.activeSessionKey();
         const db = new WorkflowDb(this.options.projectDir);
-        let count = 0;
         try {
-            db.recordContextSample(sample);
-            count = db.successfulCompactionCount(this.options.runId, this.options.role, session);
+            if (sessionKey)
+                db.clearRoleAdapterActive(this.options.runId, this.options.role, sessionKey);
         }
         finally {
             db.close();
         }
-        if ((sample.percentage ?? -1) < threshold) {
-            this.armed = true;
-            return { adapter, action: "below-threshold", sample, effectiveThreshold: threshold, compactionCount: count };
-        }
-        if (!this.armed)
-            return { adapter, action: "continued", sample, effectiveThreshold: threshold, compactionCount: count };
-        this.armed = false;
-        this.crossing += 1;
-        let freshBootstrap = firstObservedSession;
-        // A settings command published while the action settled is newer intent.
-        const revisionBeforeSettle = this.settings.settings_revision;
-        const sessionBeforeSettle = adapterSessionKey(adapter);
-        adapter = await this.adoptSettings(adapter, frozenAction);
-        if (this.settings.settings_revision !== revisionBeforeSettle || adapterSessionKey(adapter) !== sessionBeforeSettle) {
-            sample = await this.measure(adapter, "provider-query");
-            session = adapter.sessionRef?.() ?? adapter.sessionId();
-            sessionKey = adapterSessionKey(adapter);
-            freshBootstrap = Boolean(sessionKey && !this.seenSessions.has(sessionKey));
-            if (sessionKey)
-                this.seenSessions.add(sessionKey);
-            const refreshed = new WorkflowDb(this.options.projectDir);
-            try {
-                refreshed.recordContextSample(sample);
-                count = refreshed.successfulCompactionCount(this.options.runId, this.options.role, adapter.sessionRef?.() ?? adapter.sessionId());
+        if (this.active === managed)
+            this.active = undefined;
+    }
+    async observe(managed, source, event) {
+        if (source !== managed.underlying())
+            return;
+        if (event.kind === "context-usage") {
+            const state = this.stateFor(managed, false);
+            if (!state)
+                return;
+            this.acceptUsage(managed, state, event, event.source ?? "provider-event");
+            return;
+        }
+        if (event.kind === "context-compaction")
+            await this.observeCompaction(managed, event);
+    }
+    async ensureInitialized(managed, frozenAction) {
+        let existing = this.stateFor(managed, false);
+        if (existing && existing.settingsRevision === this.settings.settings_revision && existing.model === this.settings.model) {
+            this.markActive(managed, existing);
+            this.ensureSettingsWatcher(managed, frozenAction);
+            return existing;
+        }
+        const raw = managed.underlying();
+        const prepared = await this.installNative(raw, this.settings, !existing);
+        const key = adapterStateKey(raw) ?? `pending:${this.options.role}:${++this.provisional}`;
+        if (this.options.requireNativeContextManagement && key.includes(":unscoped:")) {
+            throw this.capability("provider initialized context management without a location-scoped session reference");
+        }
+        existing = this.states.get(key);
+        if (!existing)
+            existing = this.recoverOrCreateState(managed, key, frozenAction);
+        existing.installedNativeTokenLimit = prepared.installedNativeTokenLimit;
+        existing.installedNativePercent = prepared.installedNativePercent;
+        existing.settingsRevision = this.settings.settings_revision;
+        existing.model = this.settings.model;
+        if (prepared.sample)
+            this.acceptUsage(managed, existing, prepared.sample, prepared.sample.source ?? "provider-query");
+        if (existing.latest.freshness !== "fresh")
+            existing = await this.measureIntoState(managed, existing, "provider-query");
+        if (existing.state === "native_compacting" || existing.state === "host_compacting") {
+            this.reconcileIncompleteCompaction(managed, existing);
+        }
+        else if (existing.state === "compacted_unverified") {
+            if ((existing.latest.percentage ?? 100) < this.threshold())
+                this.transition(existing, "armed");
+            else
+                existing.handoffAfterTurn = "recovered compaction remained unverified at or above the configured ceiling";
+        }
+        else if (existing.state !== "handoff_required") {
+            this.transition(existing, (existing.latest.percentage ?? 100) < this.threshold() ? "armed" : "threshold_pending");
+        }
+        this.markActive(managed, existing);
+        this.ensureSettingsWatcher(managed, frozenAction);
+        return existing;
+    }
+    async installNative(adapter, settings, initial) {
+        const strict = Boolean(this.options.requireNativeContextManagement);
+        if (strict && (!adapter.prepareContextManagement || !adapter.updateContextManagement || !adapter.interruptTurnAtCompactionBoundary)) {
+            throw this.capability(`${adapter.agent} does not expose prepare, live update, and compaction-boundary interruption capabilities`);
+        }
+        const known = this.persistedMaximum(adapter, settings.model);
+        const policy = {
+            role: this.options.role, configuredThresholdPercent: settings.auto_compact_threshold_percent,
+            compactMaximum: settings.compact_maximum, settingsRevision: settings.settings_revision, model: settings.model,
+            providerSequenceStart: this.providerSequence(adapter), ...(known ? { knownModelContextWindow: known } : {}),
+            nativeCompactionEnabled: true,
+        };
+        const method = initial ? adapter.prepareContextManagement : adapter.updateContextManagement;
+        if (method) {
+            const prepared = await method.call(adapter, policy);
+            if (prepared.installedNativePercent > settings.auto_compact_threshold_percent + 0.01) {
+                throw this.capability(`installed native ceiling ${prepared.installedNativePercent.toFixed(2)}% is later than configured ${settings.auto_compact_threshold_percent}%`);
             }
-            finally {
-                refreshed.close();
+            return prepared;
+        }
+        const usage = await adapter.contextUsage?.();
+        if (!usage?.maximum)
+            throw this.capability("provider context occupancy and model maximum are unavailable");
+        const configuredTokenLimit = Math.max(1, Math.floor(usage.maximum * settings.auto_compact_threshold_percent / 100));
+        return { modelContextWindow: usage.maximum, configuredTokenLimit, installedNativeTokenLimit: configuredTokenLimit, installedNativePercent: settings.auto_compact_threshold_percent, sample: usage };
+    }
+    recoverOrCreateState(managed, key, frozenAction) {
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            const prior = db.thresholdGenerations(this.options.runId, this.options.role, key).at(-1);
+            if (prior && prior.model === this.settings.model && prior.settingsRevision === this.settings.settings_revision) {
+                const state = {
+                    key, generationId: prior.generationId, generation: prior.generation, state: prior.state,
+                    settingsRevision: prior.settingsRevision, model: prior.model,
+                    latest: prior.latestSample ?? this.measuringSample(managed, key, prior.generation),
+                    latestProviderSequence: prior.latestSample?.sequence ?? 0,
+                    installedNativeTokenLimit: prior.installedNativeTokenLimit,
+                    installedNativePercent: prior.installedNativePercent,
+                    compactionCount: db.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId()),
+                };
+                this.states.set(key, state);
+                return state;
             }
+            const generation = (prior?.generation ?? 0) + 1;
+            const state = {
+                key, generation, generationId: this.generationId(key, generation), state: "initializing",
+                settingsRevision: this.settings.settings_revision, model: this.settings.model,
+                latest: this.measuringSample(managed, key, generation), latestProviderSequence: 0,
+                compactionCount: db.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId()),
+            };
+            this.states.set(key, state);
+            this.persist(state, frozenAction);
+            return state;
         }
-        const revisedThreshold = this.threshold();
-        if ((sample.percentage ?? -1) < revisedThreshold) {
-            this.armed = true;
-            return { adapter, action: "continued", sample, effectiveThreshold: revisedThreshold, compactionCount: count };
+        finally {
+            db.close();
         }
-        const crossingKey = `${sessionKey ?? "missing"}:${this.crossing}:${revisedThreshold}`;
-        return this.compactSession(adapter, sample, count, frozenAction, crossingKey, true, freshBootstrap);
     }
-    /** Apply the configured ordinary work-session boundary without bypassing handoff or compaction accounting. */
-    async atWorkSessionBoundary(adapter, frozenAction, strategy = this.settings.session_strategy) {
-        adapter = await this.adoptSettings(adapter, frozenAction);
-        const sample = await this.measure(adapter, "provider-query");
+    reconcileIncompleteCompaction(managed, state) {
         const db = new WorkflowDb(this.options.projectDir);
-        let count = 0;
         try {
-            db.recordContextSample(sample);
-            count = db.successfulCompactionCount(this.options.runId, this.options.role, adapter.sessionRef?.() ?? adapter.sessionId());
+            const incomplete = db.compactionAttempts(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId())
+                .filter((attempt) => attempt.status === "started" && attempt.thresholdGenerationId === state.generationId);
+            if (!incomplete.length) {
+                this.transition(state, (state.latest.percentage ?? 100) < this.threshold() ? "armed" : "retrying");
+                return;
+            }
+            if ((state.latest.percentage ?? 100) < this.threshold()) {
+                for (const attempt of incomplete)
+                    db.finishCompactionAttempt(attempt.idempotencyKey, { ok: true, afterSample: state.latest });
+                state.compactionCount = db.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId());
+                this.transition(state, "armed");
+            }
+            else {
+                for (const attempt of incomplete)
+                    db.finishCompactionAttempt(attempt.idempotencyKey, { ok: true, status: "unverified", error: "process restarted before provider completion could be reconciled" });
+                state.compactionCount = db.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId());
+                state.handoffAfterTurn = "an in-flight compaction could not be reconciled after recovery";
+                this.transition(state, "compacted_unverified");
+            }
         }
         finally {
             db.close();
         }
-        if (strategy === "fresh") {
-            return this.performHandoff(adapter, sample, count, frozenAction, "ordinary session_strategy=fresh boundary requires a validated fresh successor");
-        }
-        const crossingKey = `${adapterSessionKey(adapter) ?? "missing"}:ordinary:${count + 1}:${sha(frozenAction).slice(0, 20)}`;
-        return this.compactSession(adapter, sample, count, frozenAction, crossingKey, false, false);
     }
-    effectiveSettings() { return this.settings; }
-    effectiveThreshold() { return this.threshold(); }
-    async compactSession(adapter, sample, count, frozenAction, crossingKey, thresholdCrossing, freshBootstrap) {
-        const threshold = this.threshold();
-        const sessionId = adapter.sessionId();
-        const sessionRef = adapter.sessionRef?.();
-        const sessionKey = sessionRef ? providerSessionKey(sessionRef) : undefined;
-        if (this.historicalCountUncertain)
-            return this.performHandoff(adapter, sample, count, frozenAction, "historical compaction count is uncertain; handing off rather than risking the configured maximum");
-        if (!sessionId)
-            return this.performHandoff(adapter, sample, count, frozenAction, "the provider session identity is unavailable");
-        if (!sessionRef)
-            return this.performHandoff(adapter, sample, count, frozenAction, "the provider session has no validated location-scoped identity");
-        if (count >= (this.settings.compact_maximum ?? 10))
-            return this.performHandoff(adapter, sample, count, frozenAction, `compact maximum ${this.settings.compact_maximum ?? 10} reached`);
-        if (!adapter.compact)
-            return this.performHandoff(adapter, sample, count, frozenAction, "native compaction is unavailable for this provider session");
-        const idempotencyKey = `compact:${this.options.runId}:${this.options.role}:${sha(crossingKey).slice(0, 24)}`;
-        const attemptDb = new WorkflowDb(this.options.projectDir);
-        const prior = attemptDb.startCompactionAttempt({ idempotencyKey, runId: this.options.runId, role: this.options.role, providerSessionId: sessionId, sessionRef, sessionKey, crossingKey, beforeSample: sample });
-        attemptDb.close();
-        if (prior.status === "succeeded" && prior.afterSample) {
-            const replayDb = new WorkflowDb(this.options.projectDir);
+    stateFor(managed, required) {
+        const key = adapterStateKey(managed.underlying());
+        const state = key ? this.states.get(key) : undefined;
+        if (!state && required)
+            throw this.capability("managed role adapter has no initialized scoped-session state");
+        return state;
+    }
+    async measureIntoState(managed, state, source, requireNewerThan) {
+        const attempts = Math.max(1, this.options.contextRetries ?? 3);
+        let lastError = "truthful context occupancy is unavailable";
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            let usage;
             try {
-                count = replayDb.successfulCompactionCount(this.options.runId, this.options.role, sessionRef ?? sessionId);
+                usage = await managed.underlying().contextUsage?.();
             }
-            finally {
-                replayDb.close();
+            catch (error) {
+                lastError = sanitize(error);
             }
-            return { adapter, action: "compacted", sample: prior.afterSample, effectiveThreshold: threshold, compactionCount: count };
+            if (usage && Number.isFinite(usage.used) && (usage.percentage !== undefined || usage.maximum !== undefined)) {
+                const accepted = this.acceptUsage(managed, state, usage, source, requireNewerThan);
+                if (accepted)
+                    return state;
+                lastError = "provider returned only a stale or out-of-order context sample";
+            }
+            if (attempt + 1 < attempts)
+                await new Promise((resolve) => setTimeout(resolve, 100));
         }
-        this.options.report?.({ kind: "compacting", detail: thresholdCrossing
-                ? `context ${sample.percentage?.toFixed(1)}% reached ${threshold}%`
-                : `ordinary compact session boundary (${count}/${this.settings.compact_maximum ?? 10})`, sample });
-        let compacted;
+        throw this.capability(`${lastError} after ${attempts} bounded provider query attempt(s)`);
+    }
+    async recoverMeasurementFailure(managed, state, frozenAction) {
+        if (!state.capabilityFailure?.startsWith("context measurement failed after provider action:"))
+            return state;
         try {
-            compacted = await adapter.compact();
+            state = await this.measureIntoState(managed, state, "provider-query");
+            state.capabilityFailure = undefined;
+            this.transition(state, (state.latest.percentage ?? 100) < this.threshold() ? "armed" : "threshold_pending");
         }
         catch (error) {
-            compacted = error instanceof SessionUnavailableError
-                ? { ok: false, error: error.message, failure: error.failure }
-                : { ok: false, error: error instanceof Error ? error.message : String(error) };
+            state.capabilityFailure = `context measurement failed after provider action: ${sanitize(error)}`;
+            this.persist(state, frozenAction);
         }
-        if (compacted.failure?.category === "session-unavailable") {
-            const failedDb = new WorkflowDb(this.options.projectDir);
+        return state;
+    }
+    acceptUsage(managed, state, usage, source, requireNewerThan) {
+        if (!Number.isFinite(usage.used))
+            return false;
+        const percentage = usage.percentage ?? (usage.maximum ? usage.used / usage.maximum * 100 : undefined);
+        if (percentage === undefined || !Number.isFinite(percentage))
+            return false;
+        if (usage.sessionId && managed.sessionId() && usage.sessionId !== managed.sessionId())
+            return false;
+        if (usage.model && this.settings.model !== "default" && usage.model !== this.settings.model)
+            return false;
+        const sequence = usage.sequence;
+        if (sequence !== undefined && sequence === state.latestProviderSequence && requireNewerThan === undefined && state.latest.freshness === "fresh")
+            return true;
+        if (sequence !== undefined && sequence < state.latestProviderSequence)
+            return false;
+        if (requireNewerThan !== undefined && sequence !== undefined && sequence <= requireNewerThan)
+            return false;
+        if (requireNewerThan !== undefined && sequence === undefined
+            && state.latest.used === usage.used && state.latest.maximum === usage.maximum && state.latest.percentage === percentage)
+            return false;
+        if (sequence !== undefined)
+            state.latestProviderSequence = sequence;
+        if (state.capabilityFailure?.startsWith("context measurement failed after provider action:"))
+            state.capabilityFailure = undefined;
+        const ref = managed.sessionRef?.();
+        state.compactionCount = this.compactionCount(ref ?? managed.sessionId());
+        state.latest = {
+            version: 1, runId: this.options.runId, role: this.options.role, provider: managed.agent,
+            providerSessionId: managed.sessionId(), ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : { sessionKey: state.key }),
+            model: this.settings.model, observedAt: usage.observedAt ?? this.now().toISOString(), source, freshness: "fresh",
+            used: usage.used, maximum: usage.maximum, percentage, settingsRevision: this.settings.settings_revision,
+            compactionCount: state.compactionCount, handoffGeneration: this.handoffGeneration(),
+            ...(sequence === undefined ? {} : { sequence }), thresholdGeneration: state.generation,
+        };
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            db.recordContextSample(state.latest);
+        }
+        finally {
+            db.close();
+        }
+        this.persist(state);
+        this.options.report?.({
+            kind: "context-sample",
+            detail: `authoritative context ${percentage.toFixed(1)}% (${usage.used}${usage.maximum === undefined ? "" : `/${usage.maximum}`})`,
+            sample: state.latest,
+        });
+        if (percentage >= this.threshold() && state.state === "armed")
+            this.beginGeneration(state, "threshold_pending");
+        return true;
+    }
+    async enforceThreshold(managed, state, frozenAction, allowHandoff) {
+        if (state.handoffAfterTurn)
+            return this.performHandoff(managed, state, frozenAction, state.handoffAfterTurn, false);
+        if (this.historicalCountUncertain)
+            return this.performHandoff(managed, state, frozenAction, "historical compaction count is uncertain; handing off rather than risking the configured maximum", false);
+        if ((state.latest.percentage ?? 100) < this.threshold() && !state.retryAfterTurn) {
+            this.transition(state, "armed");
+            return this.result(managed, state, "below-threshold");
+        }
+        if (state.compactionCount >= this.maximum())
+            return this.performHandoff(managed, state, frozenAction, `compact maximum ${this.maximum()} reached`, false);
+        return this.compactAndVerify(managed, state, frozenAction, allowHandoff);
+    }
+    async compactAndVerify(managed, state, frozenAction, allowHandoff) {
+        const raw = managed.underlying();
+        if (!raw.compact) {
+            if (allowHandoff)
+                return this.performHandoff(managed, state, frozenAction, "native compaction is unavailable", false);
+            throw this.capability("fresh successor does not expose native compaction");
+        }
+        let failure = "native compaction failed";
+        for (let attempt = 1; attempt <= 2; attempt++) {
+            const terminalAttempts = this.generationTerminalAttempts(managed, state);
+            if (terminalAttempts >= 2) {
+                failure = "the threshold generation exhausted its one bounded compaction retry";
+                break;
+            }
+            state.compactionCount = this.compactionCount(managed.sessionRef?.() ?? managed.sessionId());
+            if (state.compactionCount >= this.maximum())
+                break;
+            if (attempt > 1)
+                this.transition(state, "retrying");
+            else if (state.state === "armed")
+                this.beginGeneration(state, "threshold_pending");
+            this.transition(state, "host_compacting");
+            const beforeSample = state.latest;
+            const beforeProviderSequence = state.latestProviderSequence;
+            this.invalidateSample(managed, state);
+            const crossingKey = `${state.key}:${state.generation}:${attempt}:${sha(frozenAction).slice(0, 20)}`;
+            const idempotencyKey = `compact:${this.options.runId}:${this.options.role}:${sha(crossingKey).slice(0, 24)}`;
+            const db = new WorkflowDb(this.options.projectDir);
+            const prior = db.startCompactionAttempt({
+                idempotencyKey, runId: this.options.runId, role: this.options.role,
+                providerSessionId: managed.sessionId(), sessionRef: managed.sessionRef?.(), sessionKey: state.key,
+                crossingKey, beforeSample, origin: "rafi-manual", thresholdGenerationId: state.generationId,
+            });
+            db.close();
+            if (prior.status !== "started") {
+                const recoveredSample = prior.afterSample ?? prior.beforeSample;
+                if (recoveredSample) {
+                    state.latest = recoveredSample;
+                    state.latestProviderSequence = Math.max(state.latestProviderSequence, recoveredSample.sequence ?? 0);
+                }
+                state.compactionCount = this.compactionCount(managed.sessionRef?.() ?? managed.sessionId());
+                if (prior.status === "succeeded" && prior.afterSample && (prior.afterSample.percentage ?? 100) < this.threshold()) {
+                    this.transition(state, "armed");
+                    return this.result(managed, state, "compacted");
+                }
+                if (prior.status === "unverified" || (prior.status === "succeeded" && !prior.afterSample)) {
+                    this.transition(state, "compacted_unverified");
+                    if (allowHandoff)
+                        return this.performHandoff(managed, state, frozenAction, "a recovered compaction has no authoritative post-compact sample", false);
+                    throw this.capability("fresh successor compaction could not be verified after recovery");
+                }
+                failure = prior.status === "failed"
+                    ? sanitize(prior.error ?? "the prior compaction attempt failed")
+                    : `the prior compaction remained at ${prior.afterSample?.percentage?.toFixed(1) ?? "an unknown"}%`;
+                // The durable terminal attempt already consumed this ordinal. Move to
+                // the one remaining retry rather than issuing the same compaction again.
+                continue;
+            }
+            state.manualAttemptKey = idempotencyKey;
+            this.options.report?.({ kind: attempt === 1 ? "compacting" : "retrying", detail: `context reached ${this.threshold()}%; compaction ${state.compactionCount + 1}/${this.maximum()}`, sample: state.latest });
+            let compacted;
             try {
-                failedDb.finishCompactionAttempt(idempotencyKey, { ok: false, error: compacted.error ?? compacted.failure.diagnostics });
-                failedDb.appendContinuityEvent({
-                    runId: this.options.runId,
-                    role: "host",
-                    kind: "session_unavailable",
-                    payload: {
-                        role: this.options.role,
-                        operation: "native-compaction",
-                        phase: compacted.failure.phase,
-                        dispatchState: compacted.failure.dispatchState ?? "unknown",
-                        reason: compacted.failure.availability?.reason,
-                        detail: compacted.failure.diagnostics,
-                    },
-                    authoritativeStateRevision: failedDb.continuityHead(this.options.runId, this.options.role)?.authoritativeStateRevision ?? this.settings.settings_revision,
-                    sessionRef,
-                });
-                if (compacted.failure.dispatchState === "unknown")
-                    failedDb.setContinuityHeadState(this.options.runId, this.options.role, "degraded");
+                compacted = await raw.compact();
+            }
+            catch (error) {
+                compacted = error instanceof SessionUnavailableError ? { ok: false, error: error.message, failure: error.failure } : { ok: false, error: sanitize(error) };
+            }
+            await managed.settleEvents();
+            state.manualAttemptKey = undefined;
+            if (compacted.failure?.category === "session-unavailable") {
+                const failed = new WorkflowDb(this.options.projectDir);
+                try {
+                    failed.finishCompactionAttempt(idempotencyKey, { ok: false, error: compacted.error ?? compacted.failure.diagnostics });
+                    this.recordCompactionSessionUnavailable(failed, managed, compacted.failure);
+                }
+                finally {
+                    failed.close();
+                }
+                throw sessionUnavailableErrorFromFailure(compacted.failure);
+            }
+            if (!compacted.ok) {
+                failure = sanitize(compacted.error ?? "provider did not explicitly complete compaction");
+                const failed = new WorkflowDb(this.options.projectDir);
+                try {
+                    failed.finishCompactionAttempt(idempotencyKey, { ok: false, error: failure });
+                }
+                finally {
+                    failed.close();
+                }
+                continue; // one bounded retry; failures do not consume compact slots
+            }
+            let after;
+            try {
+                state = await this.measureIntoState(managed, state, "post-compact", beforeProviderSequence);
+                after = state.latest;
+            }
+            catch (error) {
+                failure = sanitize(error);
+            }
+            const completed = new WorkflowDb(this.options.projectDir);
+            try {
+                completed.finishCompactionAttempt(idempotencyKey, after
+                    ? { ok: true, afterSample: after }
+                    : { ok: true, status: "unverified", error: failure });
+                state.compactionCount = completed.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId());
             }
             finally {
-                failedDb.close();
+                completed.close();
+            }
+            if (!after) {
+                this.transition(state, "compacted_unverified");
+                if (allowHandoff)
+                    return this.performHandoff(managed, state, frozenAction, "provider reported compaction but no newer authoritative post-compact sample was available", false);
+                throw this.capability("fresh successor compaction could not be verified");
             }
-            throw sessionUnavailableErrorFromFailure(compacted.failure);
+            this.options.report?.({ kind: "compacted", detail: `context reduced to ${after.percentage?.toFixed(1)}%`, sample: after });
+            if ((after.percentage ?? 100) < this.threshold()) {
+                state.retryAfterTurn = undefined;
+                this.transition(state, "armed");
+                return this.result(managed, state, "compacted");
+            }
+            failure = `compaction remained at ${after.percentage?.toFixed(1)}%, at or above the configured ${this.threshold()}% ceiling`;
+            if (this.generationTerminalAttempts(managed, state) >= 2 || state.compactionCount >= this.maximum())
+                break;
+        }
+        if (allowHandoff)
+            return this.performHandoff(managed, state, frozenAction, failure, false);
+        throw this.capability(`fresh successor could not get below the configured ceiling after bounded compaction: ${failure}`);
+    }
+    async performHandoff(managed, state, frozenAction, reason, resumeFrozenAction) {
+        if (!this.options.handoff)
+            throw this.capability(`${reason}; validated handoff is unavailable`);
+        this.transition(state, "handoff_required", frozenAction);
+        this.options.report?.({ kind: "handoff", detail: reason, sample: state.latest });
+        const predecessorKey = state.key;
+        const successor = await this.options.handoff({
+            reason, adapter: managed.underlying(), sample: state.latest, settings: this.settings,
+            compactionCount: state.compactionCount, frozenAction,
+        });
+        const successorRaw = successor instanceof ManagedRoleAdapter ? successor.underlying() : successor;
+        const successorKey = adapterStateKey(successorRaw);
+        if (!successorKey || successorKey === predecessorKey)
+            throw this.capability("validated handoff did not produce a genuinely fresh location-scoped successor");
+        managed.replace(successorRaw);
+        this.historicalCountUncertain = false;
+        let next = await this.ensureInitialized(managed, frozenAction);
+        this.transition(next, "resuming", frozenAction);
+        next = await this.measureIntoState(managed, next, "provider-query");
+        if ((next.latest.percentage ?? 100) >= this.threshold()) {
+            await this.compactAndVerify(managed, next, frozenAction, false);
+            next = this.stateFor(managed, true);
         }
-        if (!compacted.ok) {
-            const failedDb = new WorkflowDb(this.options.projectDir);
+        this.transition(next, "armed");
+        if (resumeFrozenAction)
+            next.boundaryHandoff = undefined;
+        return this.result(managed, next, "handed-off");
+    }
+    async observeCompaction(managed, event) {
+        const state = this.stateFor(managed, false);
+        if (!state)
+            return;
+        if (event.sessionId && managed.sessionId() && event.sessionId !== managed.sessionId())
+            return;
+        const eventKey = `${state.key}:${event.providerEventId}`;
+        const phaseKey = `${eventKey}:${event.phase}`;
+        if (this.observedCompactionPhases.has(phaseKey))
+            return;
+        this.observedCompactionPhases.add(phaseKey);
+        if (event.origin === "rafi-manual" && state.manualAttemptKey) {
+            const db = new WorkflowDb(this.options.projectDir);
             try {
-                failedDb.finishCompactionAttempt(idempotencyKey, { ok: false, error: compacted.error ?? "provider did not explicitly complete compaction" });
+                db.linkCompactionProviderEvent(state.manualAttemptKey, event.providerEventId);
             }
+            catch { /* a duplicate provider event is already durably linked */ }
             finally {
-                failedDb.close();
+                db.close();
             }
-            return this.performHandoff(adapter, sample, count, frozenAction, `native compaction failed: ${sanitize(compacted.error ?? "no explicit completion")}`);
+            this.nativeAttempts.set(eventKey, state.manualAttemptKey);
+            return; // the host compact path owns success verification and accounting
         }
-        let after;
-        try {
-            after = await this.measure(adapter, "post-compact");
+        if (event.origin === "rafi-manual" && this.nativeAttempts.has(eventKey))
+            return;
+        if (event.phase === "started") {
+            if (state.compactionCount >= this.maximum()) {
+                await this.interruptForHandoff(managed, state, event.providerEventId, `compact maximum ${this.maximum()} reached at native boundary ${event.providerEventId}`);
+                return;
+            }
+            if (state.state === "armed")
+                this.beginGeneration(state, "threshold_pending");
+            if (state.handoffAfterTurn || this.generationTerminalAttempts(managed, state) >= 2) {
+                await this.interruptForHandoff(managed, state, event.providerEventId, state.handoffAfterTurn
+                    ?? `bounded compaction retry exhausted at native boundary ${event.providerEventId}`);
+                return;
+            }
+            this.transition(state, "native_compacting", undefined, event.providerEventId);
+            const beforeSample = state.latest;
+            this.invalidateSample(managed, state);
+            const idempotencyKey = `native:${this.options.runId}:${this.options.role}:${sha(eventKey).slice(0, 24)}`;
+            const db = new WorkflowDb(this.options.projectDir);
+            const attempt = db.startCompactionAttempt({
+                idempotencyKey, runId: this.options.runId, role: this.options.role,
+                providerSessionId: managed.sessionId(), sessionRef: managed.sessionRef?.(), sessionKey: state.key,
+                crossingKey: eventKey, beforeSample, origin: event.origin,
+                providerEventId: event.providerEventId, thresholdGenerationId: state.generationId,
+            });
+            db.close();
+            this.nativeAttempts.set(eventKey, attempt.idempotencyKey);
+            return;
         }
-        catch (error) {
-            const failedDb = new WorkflowDb(this.options.projectDir);
+        const idempotencyKey = this.nativeAttempts.get(eventKey) ?? `native:${this.options.runId}:${this.options.role}:${sha(eventKey).slice(0, 24)}`;
+        const observedStart = this.nativeAttempts.has(eventKey);
+        const db = new WorkflowDb(this.options.projectDir);
+        let attempt = db.compactionAttempt(idempotencyKey);
+        if (!attempt)
+            attempt = db.startCompactionAttempt({
+                idempotencyKey, runId: this.options.runId, role: this.options.role,
+                providerSessionId: managed.sessionId(), sessionRef: managed.sessionRef?.(), sessionKey: state.key,
+                crossingKey: eventKey, beforeSample: state.latest, origin: event.origin,
+                providerEventId: event.providerEventId, thresholdGenerationId: state.generationId,
+            });
+        if (attempt.status !== "started") {
+            db.close();
+            return;
+        }
+        if (event.phase === "failed") {
+            db.finishCompactionAttempt(attempt.idempotencyKey, { ok: false, error: event.reason ?? "provider-native compaction failed" });
+            db.close();
+            state.retryAfterTurn = event.reason ?? "provider-native compaction failed";
+            this.transition(state, "retrying");
+            return;
+        }
+        db.close();
+        if (!observedStart && event.origin !== "rafi-manual") {
+            state.capabilityFailure = `provider completed native compaction ${event.providerEventId} without an observable start boundary; compact maximum ${this.maximum()} cannot be enforced`;
+            this.persist(state, undefined, event.providerEventId);
+        }
+        if (state.boundaryHandoff?.providerEventId === event.providerEventId) {
+            const exceeded = new WorkflowDb(this.options.projectDir);
             try {
-                failedDb.finishCompactionAttempt(idempotencyKey, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                exceeded.finishCompactionAttempt(attempt.idempotencyKey, { ok: true, status: "unverified", error: "provider completed a vetoed over-maximum compaction" });
             }
             finally {
-                failedDb.close();
+                exceeded.close();
             }
-            return this.performHandoff(adapter, sample, count, frozenAction, "provider reported compaction but no authoritative post-compact occupancy sample was available");
+            state.compactionCount = this.compactionCount(managed.sessionRef?.() ?? managed.sessionId());
+            state.capabilityFailure = `provider completed native compaction ${event.providerEventId} beyond compact maximum ${this.maximum()}`;
+            this.persist(state);
+            return;
         }
-        const completedDb = new WorkflowDb(this.options.projectDir);
+        if (event.postCompactSample)
+            this.acceptUsage(managed, state, event.postCompactSample, "post-compact");
+        let verified = state.latest.freshness === "fresh" && state.latest.sequence !== undefined && state.latest.sequence > (attempt.beforeSample?.sequence ?? -1);
+        if (!verified) {
+            try {
+                await this.measureIntoState(managed, state, "post-compact", attempt.beforeSample?.sequence);
+                verified = true;
+            }
+            catch {
+                verified = false;
+            }
+        }
+        const completed = new WorkflowDb(this.options.projectDir);
         try {
-            completedDb.recordContextSample(after);
-            completedDb.finishCompactionAttempt(idempotencyKey, { ok: true, afterSample: after });
-            count = completedDb.successfulCompactionCount(this.options.runId, this.options.role, sessionRef ?? sessionId);
+            completed.finishCompactionAttempt(attempt.idempotencyKey, verified
+                ? { ok: true, afterSample: state.latest }
+                : { ok: true, status: "unverified", error: "no newer authoritative post-compact sample" });
+            state.compactionCount = completed.successfulCompactionCount(this.options.runId, this.options.role, managed.sessionRef?.() ?? managed.sessionId());
         }
         finally {
-            completedDb.close();
+            completed.close();
         }
-        this.options.report?.({ kind: "compacted", detail: `context reduced to ${after.percentage?.toFixed(1)}%`, sample: after });
-        if (freshBootstrap && (after.percentage ?? -1) >= threshold) {
-            const adjusted = Math.min(99, Math.ceil((after.percentage ?? 0) + 10));
-            if (adjusted <= (after.percentage ?? 0))
-                throw new ContextCapabilityError(this.options.runId, this.options.role, `fresh bootstrap remained at ${after.percentage?.toFixed(1)}% after compaction and no safe run-only threshold exists`);
-            this.runOnlyThreshold = adjusted;
-            this.options.report?.({ kind: "threshold-adjusted", detail: `fresh bootstrap remained high; run-only threshold is now ${adjusted}%`, sample: after });
+        if (!verified) {
+            state.handoffAfterTurn = "provider-native compaction succeeded but post-compact occupancy could not be verified";
+            this.transition(state, "compacted_unverified");
+        }
+        else if ((state.latest.percentage ?? 100) < this.threshold()) {
+            this.transition(state, "armed");
+        }
+        else {
+            state.retryAfterTurn = `provider-native compaction remained at ${state.latest.percentage?.toFixed(1)}%`;
+            this.transition(state, "retrying");
         }
-        this.armed = thresholdCrossing ? (after.percentage ?? 100) < this.threshold() : true;
-        return { adapter, action: "compacted", sample: after, effectiveThreshold: this.threshold(), compactionCount: count };
     }
-    async performHandoff(adapter, sample, count, frozenAction, reason) {
-        if (!this.options.handoff)
-            throw new ContextCapabilityError(this.options.runId, this.options.role, `${reason}; validated handoff is unavailable`);
-        this.options.report?.({ kind: "handoff", detail: reason, sample });
-        const successor = await this.options.handoff({ reason, adapter, sample, settings: this.settings, compactionCount: count, frozenAction });
-        const post = await this.measure(successor, "provider-query");
-        this.historicalCountUncertain = false;
-        const successorSessionId = successor.sessionId();
-        const successorSessionKey = adapterSessionKey(successor);
-        if (successorSessionKey)
-            this.seenSessions.add(successorSessionKey);
+    async interruptForHandoff(managed, state, providerEventId, reason) {
+        state.boundaryHandoff = { providerEventId, reason };
+        this.transition(state, "handoff_required", undefined, providerEventId);
+        const interrupted = await managed.underlying().interruptTurnAtCompactionBoundary?.(providerEventId);
+        if (!interrupted?.ok) {
+            state.capabilityFailure = `provider could not stop native compaction ${providerEventId}: ${interrupted?.error ?? "interrupt unavailable"}`;
+            this.persist(state);
+        }
+    }
+    generationTerminalAttempts(managed, state) {
+        const session = managed.sessionRef?.() ?? managed.sessionId();
+        if (!session)
+            return 0;
         const db = new WorkflowDb(this.options.projectDir);
         try {
-            db.recordContextSample(post);
+            return db.compactionAttempts(this.options.runId, this.options.role, session)
+                .filter((attempt) => attempt.thresholdGenerationId === state.generationId && attempt.status !== "started")
+                .length;
         }
         finally {
             db.close();
         }
-        if ((post.percentage ?? 100) >= this.threshold()) {
-            if (this.bootstrapRecoveryDepth >= 1) {
-                throw new ContextCapabilityError(this.options.runId, this.options.role, `fresh successor bootstrap remained at ${post.percentage?.toFixed(1)}% after compaction-failure recovery`);
-            }
-            this.bootstrapRecoveryDepth += 1;
-            try {
-                const bootstrapped = await this.compactSession(successor, post, 0, frozenAction, `${successorSessionKey ?? successorSessionId ?? "missing"}:fresh-bootstrap:${sha(frozenAction).slice(0, 20)}`, true, true);
-                return { ...bootstrapped, action: "handed-off" };
-            }
-            finally {
-                this.bootstrapRecoveryDepth -= 1;
-            }
-        }
-        this.armed = true;
-        return { adapter: successor, action: "handed-off", sample: post, effectiveThreshold: this.threshold(), compactionCount: 0 };
     }
-    async adoptSettings(adapter, frozenAction) {
+    async refreshSettings(managed, frozenAction, allowTransition) {
+        // Timer-driven and post-turn refreshes can meet at the same provider
+        // boundary. Wait for the active installation, then re-read the revision so
+        // neither caller can proceed on partially applied settings or miss a newer
+        // revision that arrived during the first installation.
+        while (this.refreshingSettings)
+            await this.refreshingSettings;
+        if (managed.isClosed())
+            return;
         const candidate = this.options.readSettings?.();
         if (!candidate || candidate.settings_revision <= this.settings.settings_revision)
-            return adapter;
+            return;
+        const lifecycle = this.stateFor(managed, false)?.state;
+        if (lifecycle === "native_compacting" || lifecycle === "host_compacting")
+            return;
         const next = normalizeContextSettings(candidate);
-        const providerControlsChanged = next.make !== this.settings.make
-            || next.model !== this.settings.model
-            || next.reasoning !== this.settings.reasoning
-            || next.fast !== this.settings.fast;
-        let adoptedAdapter = adapter;
-        if (providerControlsChanged) {
-            if (this.options.settingsBoundary) {
-                adoptedAdapter = await this.options.settingsBoundary({ adapter, current: this.settings, next, frozenAction });
-            }
-            else if (next.make === this.settings.make && adapter.switchSettings) {
-                const switched = await adapter.switchSettings({ model: next.model === "default" ? undefined : next.model, effort: effort(next.reasoning), fast: next.fast });
-                if (switched.failure?.category === "session-unavailable")
-                    throw sessionUnavailableErrorFromFailure(switched.failure);
-                if (!switched.ok)
-                    throw new ContextCapabilityError(this.options.runId, this.options.role, `settings revision ${next.settings_revision} could not be applied safely: ${sanitize(switched.error ?? "provider rejected the settings switch")}`);
+        const providerControlsChanged = next.make !== this.settings.make || next.model !== this.settings.model || next.reasoning !== this.settings.reasoning || next.fast !== this.settings.fast;
+        if (providerControlsChanged && !allowTransition)
+            return;
+        let releaseRefresh;
+        const refresh = new Promise((resolve) => { releaseRefresh = resolve; });
+        this.refreshingSettings = refresh;
+        try {
+            if (providerControlsChanged) {
+                let adopted;
+                if (this.options.settingsBoundary) {
+                    adopted = await this.options.settingsBoundary({ adapter: managed.underlying(), current: this.settings, next, frozenAction });
+                }
+                else if (next.make === this.settings.make && managed.underlying().switchSettings) {
+                    const switched = await managed.underlying().switchSettings({ model: next.model === "default" ? undefined : next.model, effort: effort(next.reasoning), fast: next.fast });
+                    if (switched.failure?.category === "session-unavailable")
+                        throw sessionUnavailableErrorFromFailure(switched.failure);
+                    if (!switched.ok)
+                        throw this.capability(`settings revision ${next.settings_revision} could not be applied safely: ${sanitize(switched.error ?? "provider rejected settings")}`);
+                    adopted = managed.underlying();
+                }
+                else
+                    throw this.capability(`settings revision ${next.settings_revision} requires a validated provider/model handoff`);
+                const raw = adopted instanceof ManagedRoleAdapter ? adopted.underlying() : adopted;
+                if (raw.agent !== next.make)
+                    throw this.capability(`settings revision ${next.settings_revision} requested ${next.make}, but successor reports ${raw.agent}`);
+                managed.replace(raw);
+                this.settings = next;
+                await this.ensureInitialized(managed, frozenAction);
             }
             else {
-                throw new ContextCapabilityError(this.options.runId, this.options.role, `settings revision ${next.settings_revision} requires a validated provider/model handoff, but no settings boundary is available`);
+                // Threshold-only revisions are acknowledged only after native control is installed.
+                const priorState = this.stateFor(managed, false);
+                if (!priorState) {
+                    this.settings = next;
+                    await this.ensureInitialized(managed, frozenAction);
+                }
+                else {
+                    const prepared = await this.installNative(managed.underlying(), next, false);
+                    this.settings = next;
+                    const state = this.stateFor(managed, true);
+                    this.beginGeneration(state, (state.latest.percentage ?? 100) < this.threshold() ? "armed" : "threshold_pending");
+                    state.settingsRevision = next.settings_revision;
+                    state.model = next.model;
+                    state.installedNativeTokenLimit = prepared.installedNativeTokenLimit;
+                    state.installedNativePercent = prepared.installedNativePercent;
+                    if (prepared.sample)
+                        this.acceptUsage(managed, state, prepared.sample, prepared.sample.source ?? "provider-query");
+                    this.persist(state, frozenAction);
+                }
             }
-            if (adoptedAdapter.agent !== next.make) {
-                throw new ContextCapabilityError(this.options.runId, this.options.role, `settings revision ${next.settings_revision} requested ${next.make}, but the adopted session reports ${adoptedAdapter.agent}`);
+            const adoptedState = this.stateFor(managed, false);
+            if (adoptedState?.capabilityFailure) {
+                adoptedState.capabilityFailure = undefined;
+                this.persist(adoptedState, frozenAction);
             }
+            const db = new WorkflowDb(this.options.projectDir);
+            try {
+                const ref = managed.sessionRef?.();
+                db.acknowledgeSettings({ runId: this.options.runId, role: this.options.role, providerSessionId: managed.sessionId(), ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}), revision: next.settings_revision, acknowledgedAt: this.now().toISOString() });
+            }
+            finally {
+                db.close();
+            }
+            this.options.settingsAdopted?.(next, managed);
+            this.options.report?.({ kind: "settings-adopted", detail: `adopted settings revision ${next.settings_revision}` });
+        }
+        finally {
+            releaseRefresh();
+            if (this.refreshingSettings === refresh)
+                this.refreshingSettings = undefined;
+        }
+    }
+    ensureSettingsWatcher(managed, frozenAction) {
+        if (managed.isClosed())
+            return;
+        const existing = this.settingsWatchers.get(managed);
+        if (existing) {
+            existing.frozenAction = frozenAction;
+            return;
         }
-        this.settings = next;
-        this.runOnlyThreshold = undefined;
+        if (!this.options.readSettings)
+            return;
+        const watcher = { frozenAction, stop: () => { } };
+        const timer = setInterval(() => {
+            // Provider/model transitions may hand off only while no role turn is in
+            // flight. Threshold-only changes may be attempted during a turn; an
+            // adapter that cannot safely reconfigure then is retried while idle.
+            void this.refreshSettings(managed, watcher.frozenAction, this.dispatchDepth === 0).catch((error) => {
+                const state = this.stateFor(managed, false);
+                if (state && this.dispatchDepth > 0) {
+                    this.options.report?.({ kind: "settings-pending", detail: sanitize(error), sample: state.latest });
+                    this.transition(state, "threshold_pending", watcher.frozenAction);
+                    return;
+                }
+                if (state) {
+                    state.capabilityFailure = `live settings revision could not be installed: ${sanitize(error)}`;
+                    this.options.report?.({ kind: "capability-failure", detail: state.capabilityFailure, sample: state.latest });
+                    this.transition(state, "threshold_pending", watcher.frozenAction);
+                }
+                watcher.stop();
+                this.settingsWatchers.delete(managed);
+            });
+            const state = this.stateFor(managed, false);
+            if (state)
+                this.markActive(managed, state);
+        }, Math.max(50, this.options.settingsPollMs ?? 250));
+        timer.unref();
+        watcher.stop = () => clearInterval(timer);
+        this.settingsWatchers.set(managed, watcher);
+    }
+    beginGeneration(state, lifecycle) {
+        state.generation += 1;
+        state.generationId = this.generationId(state.key, state.generation);
+        state.state = lifecycle;
+        state.latest = { ...state.latest, thresholdGeneration: state.generation, settingsRevision: this.settings.settings_revision };
+        state.retryAfterTurn = undefined;
+        state.handoffAfterTurn = undefined;
+        this.persist(state);
+    }
+    transition(state, lifecycle, frozenAction, providerEventId) {
+        const changed = state.state !== lifecycle;
+        state.state = lifecycle;
+        this.persist(state, frozenAction, providerEventId);
+        if (changed)
+            this.options.report?.({ kind: "lifecycle", detail: lifecycle, sample: state.latest });
+    }
+    persist(state, frozenAction, providerEventId) {
         const db = new WorkflowDb(this.options.projectDir);
         try {
-            const ref = adoptedAdapter.sessionRef?.();
-            db.acknowledgeSettings({ runId: this.options.runId, role: this.options.role, providerSessionId: adoptedAdapter.sessionId(), ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}), revision: next.settings_revision, acknowledgedAt: this.now().toISOString() });
+            const ref = state.latest.sessionRef;
+            db.upsertThresholdGeneration({
+                generationId: state.generationId, runId: this.options.runId, role: this.options.role,
+                providerSessionId: state.latest.providerSessionId, ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : { sessionKey: state.key }),
+                generation: state.generation, state: state.state, configuredCeilingPercent: this.threshold(),
+                installedNativeTokenLimit: state.installedNativeTokenLimit, installedNativePercent: state.installedNativePercent,
+                settingsRevision: this.settings.settings_revision, model: this.settings.model, latestSample: state.latest,
+                ...(frozenAction ? { frozenActionDigest: sha(frozenAction) } : {}), ...(providerEventId ? { providerEventId } : {}),
+            });
         }
         finally {
             db.close();
         }
-        this.options.settingsAdopted?.(next, adoptedAdapter);
-        this.options.report?.({ kind: "settings-adopted", detail: `adopted settings revision ${next.settings_revision}` });
-        return adoptedAdapter;
     }
-    async measure(adapter, source) {
-        const attempts = Math.max(1, this.options.contextRetries ?? 3);
-        let usage;
-        for (let attempt = 0; attempt < attempts; attempt++) {
-            try {
-                usage = await adapter.contextUsage?.();
-            }
-            catch {
-                usage = undefined;
-            }
-            if (usage && Number.isFinite(usage.used) && (usage.percentage !== undefined || usage.maximum !== undefined))
-                break;
+    invalidateSample(managed, state) {
+        state.latest = {
+            ...this.measuringSample(managed, state.key, state.generation), source: "post-compact",
+            observedAt: this.now().toISOString(), freshness: "measuring", compactionCount: state.compactionCount,
+        };
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            db.recordContextSample(state.latest);
         }
-        if (!usage || !Number.isFinite(usage.used))
-            throw new ContextCapabilityError(this.options.runId, this.options.role, `truthful context occupancy was unavailable after ${attempts} provider attempt(s)`);
-        const percentage = usage.percentage ?? (usage.maximum ? usage.used / usage.maximum * 100 : undefined);
-        if (percentage === undefined || !Number.isFinite(percentage))
-            throw new ContextCapabilityError(this.options.runId, this.options.role, "provider context occupancy lacks a usable percentage and maximum");
-        const ref = adapter.sessionRef?.();
+        finally {
+            db.close();
+        }
+        this.persist(state);
+    }
+    measuringSample(managed, key, generation) {
+        const ref = managed.sessionRef?.();
         return {
-            version: 1, runId: this.options.runId, role: this.options.role, provider: adapter.agent,
-            providerSessionId: adapter.sessionId(), ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : {}), model: this.settings.model, observedAt: usage.observedAt ?? this.now().toISOString(),
-            source, freshness: "fresh", used: usage.used, maximum: usage.maximum, percentage,
-            settingsRevision: this.settings.settings_revision,
-            compactionCount: adapter.sessionId() ? this.compactionCount(ref ?? adapter.sessionId()) : 0,
-            handoffGeneration: this.handoffGeneration(),
+            version: 1, runId: this.options.runId, role: this.options.role, provider: managed.agent,
+            providerSessionId: managed.sessionId(), ...(ref ? { sessionRef: ref, sessionKey: providerSessionKey(ref) } : { sessionKey: key }),
+            model: this.settings.model, observedAt: this.now().toISOString(), source: "provider-query", freshness: "measuring",
+            settingsRevision: this.settings.settings_revision, compactionCount: 0, handoffGeneration: this.handoffGeneration(), thresholdGeneration: generation,
         };
     }
+    result(managed, state, action) {
+        return { adapter: managed, action, sample: state.latest, effectiveThreshold: this.threshold(), compactionCount: state.compactionCount };
+    }
+    markActive(managed, state) {
+        if (managed.isClosed())
+            return;
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            const previous = managed.noteActiveSession(state.key);
+            if (previous)
+                db.clearRoleAdapterActive(this.options.runId, this.options.role, previous);
+            db.markRoleAdapterActive({ runId: this.options.runId, role: this.options.role, providerSessionId: managed.sessionId(), sessionKey: state.key, settingsRevision: this.settings.settings_revision, observedAt: this.now().toISOString() });
+        }
+        finally {
+            db.close();
+        }
+    }
+    providerSequence(adapter, state) {
+        const key = adapterStateKey(adapter);
+        if (state)
+            return state.latestProviderSequence;
+        if (!key)
+            return 0;
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            return Math.max(0, ...db.thresholdGenerations(this.options.runId, this.options.role, key)
+                .map((generation) => generation.latestSample?.sequence ?? 0));
+        }
+        finally {
+            db.close();
+        }
+    }
+    recordCompactionSessionUnavailable(db, managed, failure) {
+        const sessionRef = managed.sessionRef?.();
+        db.appendContinuityEvent({
+            runId: this.options.runId,
+            role: "host",
+            kind: "session_unavailable",
+            payload: {
+                role: this.options.role,
+                operation: "native-compaction",
+                phase: failure.phase,
+                dispatchState: failure.dispatchState ?? "unknown",
+                reason: failure.availability?.reason,
+                detail: failure.diagnostics,
+            },
+            authoritativeStateRevision: db.continuityHead(this.options.runId, this.options.role)?.authoritativeStateRevision ?? this.settings.settings_revision,
+            sessionRef,
+        });
+        if (failure.dispatchState === "unknown")
+            db.setContinuityHeadState(this.options.runId, this.options.role, "degraded");
+    }
+    persistedMaximum(adapter, model) {
+        const key = adapterStateKey(adapter);
+        if (!key)
+            return undefined;
+        const db = new WorkflowDb(this.options.projectDir);
+        try {
+            return db.thresholdGenerations(this.options.runId, this.options.role, key).filter((item) => item.model === model).at(-1)?.latestSample?.maximum;
+        }
+        finally {
+            db.close();
+        }
+    }
     compactionCount(session) {
+        if (!session)
+            return 0;
         const db = new WorkflowDb(this.options.projectDir);
         try {
             return db.successfulCompactionCount(this.options.runId, this.options.role, session);
@@ -637,8 +1424,13 @@ export class ThresholdCompactionController {
             db.close();
         }
     }
-    threshold() { return this.runOnlyThreshold ?? this.settings.auto_compact_threshold_percent ?? 50; }
+    generationId(key, generation) {
+        return `threshold:${this.options.runId}:${this.options.role}:${sha(`${key}:${generation}`).slice(0, 24)}`;
+    }
+    threshold() { return this.settings.auto_compact_threshold_percent; }
+    maximum() { return this.settings.compact_maximum; }
     now() { return this.options.now?.() ?? new Date(); }
+    capability(error) { return error instanceof ContextCapabilityError ? error : new ContextCapabilityError(this.options.runId, this.options.role, sanitize(error)); }
 }
 function normalizeContextSettings(settings) {
     const threshold = settings.auto_compact_threshold_percent ?? 50;
@@ -660,3 +1452,6 @@ function adapterSessionKey(adapter) {
     const ref = adapter.sessionRef?.();
     return ref ? providerSessionKey(ref) : undefined;
 }
+function adapterStateKey(adapter) {
+    return adapterSessionKey(adapter) ?? (adapter.sessionId() ? `${adapter.agent}:unscoped:${adapter.sessionId()}` : undefined);
+}