ai-foreman 1.7.7 → 1.7.8

package/dist/adapters/codex.js

@@ -23,6 +23,7 @@ export function parseCodexLine(raw) {
         return { events: [{ kind: "error", message: String(raw.error?.message ?? JSON.stringify(raw)) }] };
     return { events: [] };
 }
+const CODEX_COMPACTION_TIMEOUT_MS = 120_000;
 /** Persistent JSON-RPC controller for one live Codex thread. */
 export class CodexAdapter {
     opts;
@@ -40,9 +41,21 @@ export class CodexAdapter {
     activeText = [];
     usage;
     usageRevision = 0;
+    contextSequence = 0;
     providerSessionUsage;
     lastTurnTokens;
     stderr = "";
+    contextPolicy;
+    nativeTokenLimit;
+    spawnedNativeTokenLimit;
+    contextPrepared = false;
+    setupTurnActive = false;
+    setupToolAttempted = false;
+    activeTurnId;
+    boundaryInterrupt;
+    compactionSequence = 0;
+    activeCompaction;
+    manualCompactionPending = false;
     constructor(opts) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
@@ -52,7 +65,13 @@ export class CodexAdapter {
         return [this.opts.systemPromptAppend, this.buildSkillsAppendix(), instruction]
             .filter((part) => Boolean(part)).join("\n\n");
     }
-    buildAppServerArgs() { return ["app-server", "--listen", "stdio://"]; }
+    buildAppServerArgs() {
+        const args = ["app-server", "--listen", "stdio://"];
+        if (this.nativeTokenLimit !== undefined) {
+            args.push("-c", `model_auto_compact_token_limit=${this.nativeTokenLimit}`, "-c", 'model_auto_compact_token_limit_scope="total"');
+        }
+        return args;
+    }
     /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction) {
         const args = ["exec", "--json", "--skip-git-repo-check", "--sandbox", this.opts.sandboxMode ?? "workspace-write", "-C", this.opts.cwd];
@@ -68,9 +87,11 @@ export class CodexAdapter {
         return args;
     }
     async sendTurn(instruction) {
+        if (this.opts.contextManagementPolicy && !this.contextPrepared)
+            await this.prepareContextManagement(this.opts.contextManagementPolicy);
         return withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
     }
-    async sendTurnInternal(instruction) {
+    async sendTurnInternal(instruction, setup = false) {
         if (this.closed)
             throw new Error("builder is closed");
         this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
@@ -79,29 +100,49 @@ export class CodexAdapter {
             await this.ensureThread();
             this.activeText = [];
             this.lastTurnTokens = undefined;
+            this.setupTurnActive = setup;
+            this.setupToolAttempted = false;
             const completion = this.waitFor("turn/completed", (params) => params.threadId === this._sessionId);
             turnStartDispatched = true;
-            await this.request("turn/start", {
+            const started = await this.request("turn/start", {
                 threadId: this._sessionId,
-                input: [{ type: "text", text: this.buildInstruction(instruction), text_elements: [] }],
+                input: [{ type: "text", text: setup ? instruction : this.buildInstruction(instruction), text_elements: [] }],
                 cwd: this.opts.cwd,
                 model: this.opts.model ?? null,
                 effort: this.opts.effort ?? (this.opts.fast ? "low" : null),
             });
+            const startedTurn = started.turn;
+            this.activeTurnId = typeof startedTurn?.id === "string" ? startedTurn.id : undefined;
             const params = await completion;
             const turn = params.turn;
             const failed = turn?.status === "failed";
+            const interrupted = turn?.status === "interrupted" || Boolean(this.boundaryInterrupt);
             const error = turn?.error;
             const text = this.activeText.join("\n");
             const result = {
                 text: failed ? normalizeRuntimeErrorText("codex", String(error?.message ?? text), null, "app-server turn") : text,
                 isError: failed, numTurns: 1, costUsd: 0, costAuthoritative: false,
                 ...(this.lastTurnTokens ?? {}),
+                ...(interrupted ? { interrupted: { reason: "compaction-boundary", ...(this.boundaryInterrupt?.providerEventId ? { providerEventId: this.boundaryInterrupt.providerEventId } : {}) } } : {}),
             };
+            if (setup && this.setupToolAttempted)
+                throw new Error("Codex context setup attempted to invoke a tool; native context capability was not established");
             this.eventQueue.push({ kind: "turn-complete", result });
             return result;
         }
         catch (error) {
+            if (this.boundaryInterrupt) {
+                const result = {
+                    text: this.activeText.join("\n"), isError: false, numTurns: 1, costUsd: 0,
+                    costAuthoritative: false, ...(this.lastTurnTokens ?? {}),
+                    interrupted: {
+                        reason: "compaction-boundary",
+                        ...(this.boundaryInterrupt.providerEventId ? { providerEventId: this.boundaryInterrupt.providerEventId } : {}),
+                    },
+                };
+                this.eventQueue.push({ kind: "turn-complete", result });
+                return result;
+            }
             if (error instanceof SessionUnavailableError) {
                 const result = sessionUnavailableResult(error);
                 this.eventQueue.push({ kind: "error", message: result.text });
@@ -123,10 +164,87 @@ export class CodexAdapter {
             this.eventQueue.push({ kind: "turn-complete", result });
             return result;
         }
+        finally {
+            this.activeTurnId = undefined;
+            this.setupTurnActive = false;
+            this.boundaryInterrupt = undefined;
+        }
+    }
+    async prepareContextManagement(policy) {
+        validateContextPolicy(policy);
+        this.contextPolicy = { ...policy };
+        this.compactionSequence = Math.max(this.compactionSequence, policy.providerSequenceStart ?? 0);
+        this.contextSequence = Math.max(this.contextSequence, policy.providerSequenceStart ?? 0);
+        if (policy.knownModelContextWindow && policy.knownModelContextWindow > 0) {
+            this.nativeTokenLimit = tokenCeiling(policy.knownModelContextWindow, policy.configuredThresholdPercent);
+        }
+        await this.ensureThread();
+        if (!this.usage) {
+            const setup = await this.sendTurnInternal("Rafi context setup only. Do not call tools or change files. Reply with exactly CONTEXT_READY.", true);
+            if (setup.isError || setup.text.trim() !== "CONTEXT_READY") {
+                throw new Error(`Codex context setup did not complete safely: ${setup.text.slice(0, 240)}`);
+            }
+        }
+        const maximum = this.usage?.maximum ?? policy.knownModelContextWindow;
+        if (!maximum || !Number.isFinite(maximum) || maximum <= 0) {
+            throw new Error("Codex did not expose modelContextWindow during context setup");
+        }
+        const configuredTokenLimit = tokenCeiling(maximum, policy.configuredThresholdPercent);
+        this.nativeTokenLimit = configuredTokenLimit;
+        if (this.spawnedNativeTokenLimit !== configuredTokenLimit) {
+            await this.restartTransport();
+            await this.ensureThread();
+        }
+        this.contextPrepared = true;
+        return {
+            modelContextWindow: maximum,
+            configuredTokenLimit,
+            installedNativeTokenLimit: configuredTokenLimit,
+            installedNativePercent: configuredTokenLimit / maximum * 100,
+            ...(this.usage ? { sample: { ...this.usage } } : {}),
+        };
+    }
+    async updateContextManagement(policy) {
+        validateContextPolicy(policy);
+        if (this.activeTurnId)
+            throw new Error("Codex native context control can be reconfigured only after the active turn settles");
+        const maximum = this.usage?.maximum ?? policy.knownModelContextWindow;
+        if (!maximum || maximum <= 0)
+            return this.prepareContextManagement(policy);
+        this.contextPolicy = { ...policy };
+        this.compactionSequence = Math.max(this.compactionSequence, policy.providerSequenceStart ?? 0);
+        this.contextSequence = Math.max(this.contextSequence, policy.providerSequenceStart ?? 0);
+        const configuredTokenLimit = tokenCeiling(maximum, policy.configuredThresholdPercent);
+        this.nativeTokenLimit = configuredTokenLimit;
+        if (this.spawnedNativeTokenLimit !== configuredTokenLimit) {
+            await this.restartTransport();
+            await this.ensureThread();
+        }
+        return {
+            modelContextWindow: maximum,
+            configuredTokenLimit,
+            installedNativeTokenLimit: configuredTokenLimit,
+            installedNativePercent: configuredTokenLimit / maximum * 100,
+            ...(this.usage ? { sample: { ...this.usage } } : {}),
+        };
+    }
+    async interruptTurnAtCompactionBoundary(providerEventId) {
+        if (!this.activeTurnId || !this._sessionId)
+            return { ok: false, error: "no active Codex turn exists at the compaction boundary", providerEventId };
+        try {
+            this.boundaryInterrupt = { providerEventId };
+            await this.request("turn/interrupt", { threadId: this._sessionId, turnId: this.activeTurnId });
+            return { ok: true, providerEventId };
+        }
+        catch (error) {
+            this.boundaryInterrupt = undefined;
+            return { ok: false, error: error instanceof Error ? error.message : String(error), providerEventId };
+        }
     }
     async compact() {
         try {
             await this.ensureThread();
+            this.manualCompactionPending = true;
             this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
             const usageRevision = this.usageRevision;
             // A pre-compaction observation must never be mistaken for proof that the
@@ -137,12 +255,12 @@ export class CodexAdapter {
             const done = this.waitFor("item/completed", (params) => {
                 const item = params.item;
                 return params.threadId === this._sessionId && item?.type === "contextCompaction";
-            }, 30_000);
+            }, CODEX_COMPACTION_TIMEOUT_MS);
             const postCompactUsage = this.waitFor("thread/tokenUsage/updated", (params) => {
                 return (params.threadId === undefined || params.threadId === this._sessionId)
                     && this.usageRevision > usageRevision
                     && this.usage !== undefined;
-            }, 30_000);
+            }, CODEX_COMPACTION_TIMEOUT_MS);
             await Promise.all([
                 this.request("thread/compact/start", { threadId: this._sessionId }),
                 done,
@@ -156,6 +274,9 @@ export class CodexAdapter {
                 return { ok: false, error: error.message, failure: error.failure };
             return { ok: false, error: error instanceof Error ? error.message : String(error) };
         }
+        finally {
+            this.manualCompactionPending = false;
+        }
     }
     async contextUsage() { return this.usage; }
     async sessionUsage() { return this.providerSessionUsage ? { ...this.providerSessionUsage } : undefined; }
@@ -292,6 +413,7 @@ export class CodexAdapter {
         this.stderr = "";
         const executable = this.opts.runtimeExecutable ?? "codex";
         const child = spawn(executable, this.buildAppServerArgs(), { cwd: this.opts.cwd, stdio: ["pipe", "pipe", "pipe"] });
+        this.spawnedNativeTokenLimit = this.nativeTokenLimit;
         this.process = child;
         // A short-lived server may close stdin before its stderr/exit event. The
         // close handler owns rejection so diagnostics include the complete stderr.
@@ -303,8 +425,10 @@ export class CodexAdapter {
             }
             catch { /* ignore non-protocol stdout */ } });
         child.stderr.on("data", (chunk) => { this.stderr = `${this.stderr}${chunk.toString()}`.slice(-8192); });
-        child.on("error", (error) => this.disconnect(error));
-        child.on("close", (code) => this.disconnect(new Error(`Codex app-server exited with code ${code ?? "unknown"}`)));
+        child.on("error", (error) => { if (this.process === child)
+            this.disconnect(error); });
+        child.on("close", (code) => { if (this.process === child)
+            this.disconnect(new Error(`Codex app-server exited with code ${code ?? "unknown"}`)); });
         await this.request("initialize", { clientInfo: { name: "rafi", title: "Rafi", version: "1" }, capabilities: { experimentalApi: true, requestAttestation: false } });
         this.write({ method: "initialized", params: {} });
         this.initialized = true;
@@ -339,8 +463,29 @@ export class CodexAdapter {
         if (!message.method)
             return;
         const params = message.params ?? {};
-        if (message.method === "item/started") {
+        if (message.method === "turn/started") {
+            const turn = params.turn;
+            if (typeof turn?.id === "string")
+                this.activeTurnId = turn.id;
+        }
+        else if (message.method === "item/started") {
             const item = params.item;
+            if (this.setupTurnActive && item && isToolItem(item.type)) {
+                this.setupToolAttempted = true;
+                if (this.activeTurnId && this._sessionId)
+                    void this.request("turn/interrupt", { threadId: this._sessionId, turnId: this.activeTurnId }).catch(() => { });
+            }
+            if (item?.type === "contextCompaction") {
+                const providerSequence = ++this.compactionSequence;
+                const providerEventId = String(item.id ?? `codex-compaction-${providerSequence}`);
+                const origin = this.manualCompactionPending ? "rafi-manual" : "provider-auto";
+                this.activeCompaction = { providerEventId, providerSequence, origin, usageRevision: this.usageRevision };
+                this.eventQueue.push({
+                    kind: "context-compaction", phase: "started", origin, providerEventId, providerSequence,
+                    provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef,
+                    observedAt: new Date().toISOString(),
+                });
+            }
             const activity = codexItemActivity(item);
             if (activity)
                 this.eventQueue.push({ kind: "activity", provider: "codex", ...activity });
@@ -354,6 +499,21 @@ export class CodexAdapter {
             else if (item?.type === "commandExecution")
                 this.eventQueue.push({ kind: "tool", name: "command_execution", input: { command: item.command } });
             else {
+                if (item?.type === "contextCompaction") {
+                    const active = this.activeCompaction;
+                    const providerSequence = active?.providerSequence ?? ++this.compactionSequence;
+                    const providerEventId = String(item.id ?? active?.providerEventId ?? `codex-compaction-${providerSequence}`);
+                    const origin = active?.origin ?? (this.manualCompactionPending ? "rafi-manual" : "provider-auto");
+                    const failed = item.status === "failed" || item.status === "error" || item.error !== undefined;
+                    this.eventQueue.push({
+                        kind: "context-compaction", phase: failed ? "failed" : "succeeded", origin, providerEventId, providerSequence,
+                        provider: "codex", sessionId: this._sessionId, sessionRef: this._sessionRef,
+                        observedAt: new Date().toISOString(),
+                        ...(failed ? { reason: String(item.error?.message ?? item.error ?? "Codex context compaction failed") } : {}),
+                        ...(!failed && this.usage && (!active || this.usageRevision > active.usageRevision) ? { postCompactSample: { ...this.usage, source: "post-compact" } } : {}),
+                    });
+                    this.activeCompaction = undefined;
+                }
                 const activity = codexItemActivity(item, true);
                 if (activity)
                     this.eventQueue.push({ kind: "activity", provider: "codex", ...activity });
@@ -371,7 +531,8 @@ export class CodexAdapter {
             const tokenUsage = params.tokenUsage;
             const total = tokenUsage?.total;
             const last = tokenUsage?.last;
-            const used = Number(total?.totalTokens);
+            // `last` is active context occupancy. `total` is lifetime session usage.
+            const used = Number(last?.totalTokens);
             const maximum = Number(tokenUsage?.modelContextWindow);
             const observedAt = new Date().toISOString();
             const totalInput = optionalNonNegative(total?.inputTokens);
@@ -385,7 +546,11 @@ export class CodexAdapter {
                 outputTokens: optionalNonNegative(last?.outputTokens),
             };
             if (Number.isFinite(used) && used >= 0 && Number.isFinite(maximum) && maximum > 0) {
-                this.usage = { used, maximum, percentage: used / maximum * 100, observedAt, source: "provider-event" };
+                const sequence = ++this.contextSequence;
+                this.usage = {
+                    used, maximum, percentage: used / maximum * 100, observedAt, source: "provider-event", sequence,
+                    ...(this._sessionId ? { sessionId: this._sessionId } : {}), ...(this.opts.model ? { model: this.opts.model } : {}),
+                };
                 this.usageRevision += 1;
                 this.eventQueue.push({ kind: "context-usage", ...this.usage });
             }
@@ -441,6 +606,24 @@ export class CodexAdapter {
                 waiter.reject(error);
         this.notificationWaiters.clear();
     }
+    /** Restart only app-server; the scoped thread remains the continuity boundary. */
+    async restartTransport() {
+        if (this.activeTurnId)
+            throw new Error("cannot restart Codex app-server while a turn is active");
+        const child = this.process;
+        this.process = undefined;
+        this.initialized = false;
+        this.threadAttached = false;
+        if (child && child.exitCode === null)
+            child.kill("SIGTERM");
+        for (const pending of this.pending.values())
+            pending.reject(new Error("Codex app-server restarted for context policy"));
+        this.pending.clear();
+        for (const waiters of this.notificationWaiters.values())
+            for (const waiter of waiters)
+                waiter.reject(new Error("Codex app-server restarted for context policy"));
+        this.notificationWaiters.clear();
+    }
     buildSkillsAppendix() {
         if (!this.opts.skills?.length)
             return undefined;
@@ -452,6 +635,19 @@ function optionalNonNegative(value) {
     const number = Number(value);
     return Number.isFinite(number) && number >= 0 ? number : undefined;
 }
+function tokenCeiling(maximum, percentage) {
+    return Math.max(1, Math.floor(maximum * percentage / 100));
+}
+function validateContextPolicy(policy) {
+    if (!Number.isInteger(policy.configuredThresholdPercent) || policy.configuredThresholdPercent < 1 || policy.configuredThresholdPercent > 99) {
+        throw new Error("configured context threshold must be an integer from 1 to 99");
+    }
+    if (!Number.isSafeInteger(policy.compactMaximum) || policy.compactMaximum < 1)
+        throw new Error("compact maximum must be a positive safe integer");
+}
+function isToolItem(type) {
+    return type === "commandExecution" || type === "fileChange" || type === "mcpToolCall" || type === "dynamicToolCall" || type === "webSearch";
+}
 function activityPhase(phase) {
     if (phase === "planning")
         return "planning";

package/dist/adapters/recovering.d.ts

@@ -1,5 +1,5 @@
 import type { AgentRuntime } from "../runtimeAuth.js";
-import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, ManagedTurnDispatcher, PreparedContextManagement, ProviderSessionUsage, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export type TurnRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RecoveringAdapterOptions {
@@ -21,6 +21,7 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     private readonly eventQueue;
     private eventPump;
     private closed;
+    private turnDispatcher?;
     constructor(opts: RecoveringAdapterOptions);
     get agent(): "claude" | "codex";
     sendTurn(text: string): Promise<TurnResult>;
@@ -29,6 +30,10 @@ export declare class RecoveringAdapter implements BuilderAdapter {
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<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>;
     events(): AsyncIterable<BuilderEvent>;

package/dist/adapters/recovering.js

@@ -9,6 +9,7 @@ export class RecoveringAdapter {
     eventQueue = new AsyncQueue();
     eventPump;
     closed = false;
+    turnDispatcher;
     constructor(opts) {
         this.opts = opts;
         this.adapter = opts.initial;
@@ -20,7 +21,8 @@ export class RecoveringAdapter {
     }
     async sendTurn(text) {
         while (true) {
-            const result = await this.adapter.sendTurn(text);
+            const invoke = () => this.adapter.sendTurn(text);
+            const result = this.turnDispatcher ? await this.turnDispatcher(text, invoke) : await invoke();
             const sessionRef = this.adapter.sessionRef?.();
             if (sessionRef && this.opts.onSessionRef) {
                 try {
@@ -67,6 +69,12 @@ export class RecoveringAdapter {
         return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped", detail: "wrapped adapter does not expose scoped session validation" });
     }
     compact() { return this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" }); }
+    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 }); }
+    installManagedTurnDispatcher(dispatcher) { this.turnDispatcher = dispatcher; }
     contextUsage() { return this.adapter.contextUsage?.() ?? Promise.resolve(undefined); }
     sessionUsage() { return this.adapter.sessionUsage?.() ?? Promise.resolve(undefined); }
     events() {

package/dist/adapters/types.d.ts

@@ -59,7 +59,55 @@ export interface TurnResult {
     inputTokens?: number;
     outputTokens?: number;
     failure?: RuntimeFailure;
+    /** A provider turn stopped at a context-compaction boundary, not a failure. */
+    interrupted?: {
+        reason: "compaction-boundary";
+        providerEventId?: string;
+    };
 }
+export type ContextCompactionOrigin = "provider-auto" | "rafi-manual" | "recovery" | "boundary";
+export type ContextCompactionPhase = "started" | "succeeded" | "failed";
+/** Native context policy installed before a Builder/QA role may do real work. */
+export interface ContextManagementPolicy {
+    role: "builder" | "qa";
+    configuredThresholdPercent: number;
+    compactMaximum: number;
+    settingsRevision: number;
+    model: string;
+    /** Continue a provider-monotonic sequence after process recovery. */
+    providerSequenceStart?: number;
+    /** A persisted, model-matched maximum may avoid a discovery turn. */
+    knownModelContextWindow?: number;
+    /** Native compaction stays enabled until the host vetoes a boundary. */
+    nativeCompactionEnabled?: boolean;
+}
+export interface PreparedContextManagement {
+    modelContextWindow: number;
+    configuredTokenLimit: number;
+    installedNativeTokenLimit: number;
+    installedNativePercent: number;
+    sample?: ContextUsage;
+}
+export interface ContextCompactionEvent {
+    kind: "context-compaction";
+    phase: ContextCompactionPhase;
+    origin: ContextCompactionOrigin;
+    providerEventId: string;
+    providerSequence: number;
+    provider: "claude" | "codex";
+    sessionId?: string;
+    sessionRef?: ProviderSessionRefV1;
+    observedAt: string;
+    postCompactSample?: ContextUsage;
+    reason?: string;
+}
+export interface InterruptResult {
+    ok: boolean;
+    error?: string;
+    providerEventId?: string;
+}
+/** Host-owned gate used by wrappers that need additional provider turns. */
+export type ManagedTurnDispatcher = (text: string, invoke: () => Promise<TurnResult>) => Promise<TurnResult>;
 /** Observability events emitted while a builder works. */
 export type BuilderEvent = {
     kind: "text";
@@ -97,7 +145,10 @@ export type BuilderEvent = {
     percentage?: number;
     observedAt?: string;
     source?: "provider-event" | "provider-query" | "post-compact";
-} | {
+    sequence?: number;
+    sessionId?: string;
+    model?: string;
+} | ContextCompactionEvent | {
     kind: "error";
     message: string;
 };
@@ -107,6 +158,10 @@ export interface ContextUsage {
     percentage?: number;
     observedAt?: string;
     source?: "provider-event" | "provider-query" | "post-compact";
+    /** Monotonic within one scoped provider session. */
+    sequence?: number;
+    sessionId?: string;
+    model?: string;
 }
 export interface ProviderSessionUsage {
     inputTokens?: number;
@@ -163,6 +218,8 @@ export interface BuilderAdapterOptions {
     systemPromptAppend?: string;
     /** Skill names to preload for this session (Claude: lazy-loaded; Codex: flattened). */
     skills?: string[];
+    /** Builder/QA native policy used even for setup and handoff-acceptance turns. */
+    contextManagementPolicy?: ContextManagementPolicy;
 }
 export interface BuilderAdapter {
     readonly agent: "claude" | "codex";
@@ -178,6 +235,14 @@ export interface BuilderAdapter {
     validateSession?(): Promise<SessionAvailabilityV1>;
     /** Provider-native compaction on the exact live conversation. */
     compact?(): Promise<CompactResult>;
+    /** Initialize the session and install native in-turn context controls. */
+    prepareContextManagement?(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    /** Safely reconfigure native in-turn controls on the same session. */
+    updateContextManagement?(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    /** Stop only at a provider-observed compaction boundary. */
+    interruptTurnAtCompactionBoundary?(providerEventId?: string): Promise<InterruptResult>;
+    /** Route wrapper-owned repair/retry/follow-up turns through the role gate. */
+    installManagedTurnDispatcher?(dispatcher: ManagedTurnDispatcher): void;
     /** Truthful provider context occupancy, when exposed by the provider. */
     contextUsage?(): Promise<ContextUsage | undefined>;
     /** Provider/session cumulative totals; distinct from live context occupancy. */

package/dist/branch/currentGuard.d.ts

@@ -1,4 +1,4 @@
-import type { BuilderAdapter, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "../adapters/types.js";
+import type { BuilderAdapter, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, ManagedTurnDispatcher, PreparedContextManagement, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "../adapters/types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export interface CurrentWorkflowIdentity {
     worktree: string;
@@ -26,6 +26,10 @@ export declare class CurrentWorkflowGuardAdapter implements BuilderAdapter {
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<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>;

package/dist/branch/currentGuard.js

@@ -48,6 +48,12 @@ export class CurrentWorkflowGuardAdapter {
     adoptSessionRef(ref) { this.adapter.adoptSessionRef?.(ref); }
     validateSession() { assertCurrentWorkflowIdentity(this.cwd, this.expected); return this.adapter.validateSession?.() ?? Promise.resolve({ version: 1, status: "unknown", checkedAt: new Date().toISOString(), reason: "legacy-unscoped" }); }
     async compact() { assertCurrentWorkflowIdentity(this.cwd, this.expected); const result = await (this.adapter.compact?.() ?? Promise.resolve({ ok: false, error: "native compaction unavailable" })); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    async prepareContextManagement(policy) { assertCurrentWorkflowIdentity(this.cwd, this.expected); if (!this.adapter.prepareContextManagement)
+        throw new Error("native context management unavailable"); const result = await this.adapter.prepareContextManagement(policy); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    async updateContextManagement(policy) { assertCurrentWorkflowIdentity(this.cwd, this.expected); if (!this.adapter.updateContextManagement)
+        throw new Error("native context reconfiguration unavailable"); const result = await this.adapter.updateContextManagement(policy); assertCurrentWorkflowIdentity(this.cwd, this.expected); return result; }
+    interruptTurnAtCompactionBoundary(providerEventId) { return this.adapter.interruptTurnAtCompactionBoundary?.(providerEventId) ?? Promise.resolve({ ok: false, error: "compaction-boundary interruption unavailable", providerEventId }); }
+    installManagedTurnDispatcher(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?.(settings) ?? Promise.resolve({ ok: false, error: "settings switch unavailable" }); }