ai-foreman 1.7.7 → 1.7.8

package/README.md

@@ -115,7 +115,9 @@ What each part does:
 | `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
 | `--show-session-cost` / `--hide-session-cost` | flags | saved role preferences | Show authoritative provider cost or trustworthy cumulative tokens for Builder and QA; does not change context occupancy display. |
-| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `50` | Initial run threshold override. A newer persistent settings revision wins at the next safe boundary. |
+| `--auto-compact-threshold <percent>` | integer `1`–`99` | saved Builder value, then `50` | Initial Builder threshold override. A later explicit Builder-threshold revision wins for the active run. |
+
+Builder and QA context ceilings are configured independently (default `50%`, maximum `10` successful compactions per scoped provider session). Claude and Codex install the ceiling as a native in-turn auto-compaction limit before real work begins; Rafi verifies the post-compaction occupancy and counts provider-native and host-requested compactions together. An ineffective or failed compact receives one bounded retry, followed by a validated cumulative handoff. Status output reports the configured and installed ceilings, lifecycle state, scoped count/maximum, and settings revision without substituting cumulative session tokens for active context occupancy.
 
 Auto-detected tracker files:
 
@@ -607,6 +609,14 @@ pnpm build
 pnpm dev -- start ../../examples/dummy-project --steps 2
 ```
 
+Changes to provider adapters or context lifecycle enforcement also require the opt-in authenticated gate:
+
+```bash
+pnpm test:live-providers
+```
+
+It exercises Claude and Codex as both Builder and QA with a low native ceiling, verifies in-turn compaction and same-session continuation, then verifies a maximum-one boundary interruption and validated fresh handoff. Set `RAFI_LIVE_CONTEXT_THRESHOLD_PERCENT` to an integer from `1` through `10` to override its default `10%` ceiling. Very low Claude ceilings can intentionally fail the capability check when they fall below the SDK's minimum native window. The gate uses locally authenticated provider CLIs and is intentionally skipped by the ordinary test suite.
+
 Package output:
 
 - The package publishes an `ai-foreman` binary from `dist/index.js`.

package/dist/activity.js

@@ -236,8 +236,8 @@ export function reportBuilderEvent(event) {
         reporter.update("processing agent response");
     else if (event.kind === "session-transition")
         reporter.update(`session ${event.transition}`, event.detail);
-    else if (event.kind === "context-usage")
-        reporter.pulse(event.percentage === undefined ? undefined : `context ${event.percentage.toFixed(0)}%`);
+    else if (event.kind === "context-compaction")
+        reporter.update(event.phase === "started" ? "compacting context" : event.phase === "succeeded" ? "context compacted" : "context compaction failed", `${event.origin} ${event.providerEventId}`, { provider: event.provider });
     else if (event.kind === "turn-complete")
         reporter.update(event.result.isError ? "agent turn failed" : "agent turn complete");
     else if (event.kind === "error")

package/dist/adapters/claude.d.ts

@@ -1,7 +1,7 @@
 import type { SDKSessionInfo, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, PermissionDecision, PreparedContextManagement, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 /**
  * Pure function: build the `options` object passed to `query()`.
@@ -43,11 +43,14 @@ export declare function claudeApiRetryEvent(message: {
 export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "claude";
-    private readonly inbox;
+    private inbox;
     private readonly eventQueue;
-    private readonly query;
-    private readonly abort;
-    private readonly pumpDone;
+    private query;
+    private abort;
+    private pumpDone;
+    private readonly queryFactory;
+    private transportGeneration;
+    private transportObservedSessionId?;
     private _sessionId?;
     private _sessionRef?;
     private readonly stderrChunks;
@@ -55,6 +58,19 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private structuredError?;
     private apiErrorStatus?;
     private compactResult?;
+    private contextPolicy?;
+    private contextSequence;
+    private compactionSequence;
+    private activeCompaction?;
+    private manualCompactionPending;
+    private boundaryInterrupt?;
+    private compactionTerminalObserved;
+    private lastContextUsage?;
+    /** Full provider context capacity, before Rafi narrows Claude's auto-compact window. */
+    private modelContextWindow?;
+    /** SDK-owned space between autoCompactWindow and the actual used-token trigger. */
+    private nativeAutoCompactReserve?;
+    private contextPrepared;
     private cumulativeUsage;
     private pending?;
     private terminalResult?;
@@ -62,6 +78,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private closed;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
     private constructor();
+    private openQuery;
     /** Background loop: consume the SDK message stream until it ends. */
     private pump;
     private handle;
@@ -74,11 +91,18 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
     contextUsage(): Promise<ContextUsage | undefined>;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;
     private observeSession;
+    private makeContextUsage;
+    private configureContextManagement;
+    private restartTransport;
+    private completeCompaction;
     private settlePending;
     private streamFailureResult;
 }

package/dist/adapters/claude.js

@@ -145,6 +145,10 @@ export class ClaudeAdapter {
     query;
     abort = new AbortController();
     pumpDone;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    queryFactory;
+    transportGeneration = 0;
+    transportObservedSessionId;
     _sessionId;
     _sessionRef;
     stderrChunks = [];
@@ -152,6 +156,19 @@ export class ClaudeAdapter {
     structuredError;
     apiErrorStatus;
     compactResult;
+    contextPolicy;
+    contextSequence = 0;
+    compactionSequence = 0;
+    activeCompaction;
+    manualCompactionPending = false;
+    boundaryInterrupt;
+    compactionTerminalObserved = false;
+    lastContextUsage;
+    /** Full provider context capacity, before Rafi narrows Claude's auto-compact window. */
+    modelContextWindow;
+    /** SDK-owned space between autoCompactWindow and the actual used-token trigger. */
+    nativeAutoCompactReserve;
+    contextPrepared = false;
     cumulativeUsage = { observedAt: new Date(0).toISOString(), source: "provider" };
     pending;
     terminalResult;
@@ -195,18 +212,30 @@ export class ClaudeAdapter {
         }
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    constructor(opts, query) {
+    constructor(opts, queryFactory) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
-        this.query = query({
+        this.queryFactory = queryFactory;
+        this.query = this.openQuery();
+        const generation = ++this.transportGeneration;
+        this.pumpDone = this.pump(this.query, generation);
+    }
+    openQuery(nativeAutoCompactWindow) {
+        const scopedOpts = this._sessionRef
+            ? { ...this.opts, resumeSessionId: this._sessionRef.sessionId, resumeSessionRef: this._sessionRef }
+            : this.opts;
+        return this.queryFactory({
             prompt: this.inbox,
             options: {
-                ...buildClaudeQueryOptions(opts),
+                ...buildClaudeQueryOptions(scopedOpts),
+                ...(nativeAutoCompactWindow === undefined ? {} : {
+                    settings: { autoCompactEnabled: true, autoCompactWindow: nativeAutoCompactWindow },
+                }),
                 abortController: this.abort,
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
-                    const decision = await opts.permission({
+                    const decision = await this.opts.permission({
                         toolName,
                         input,
                         signal: requestOptions.signal,
@@ -221,16 +250,22 @@ export class ClaudeAdapter {
                 },
             },
         });
-        this.pumpDone = this.pump();
     }
     /** Background loop: consume the SDK message stream until it ends. */
-    async pump() {
+    async pump(query, generation) {
         try {
-            for await (const msg of this.query) {
-                this.handle(msg);
+            for await (const msg of query) {
+                if (generation !== this.transportGeneration)
+                    return;
+                // Keep provider messages ordered through post-compaction measurement. In
+                // particular, a result message must not overtake the fresh context sample
+                // produced for the preceding compact_result/compact_boundary message.
+                await this.handle(msg);
             }
         }
         catch (err) {
+            if (generation !== this.transportGeneration)
+                return;
             // Suppress the AbortError that fires when close() aborts the stream.
             const isShutdownAbort = this.closed &&
                 (err instanceof Error &&
@@ -245,6 +280,8 @@ export class ClaudeAdapter {
             }
         }
         finally {
+            if (generation !== this.transportGeneration)
+                return;
             this.streamEnded = true;
             if (!this.closed && this.pending) {
                 const result = this.streamFailureResult("Claude stream ended without a result", Boolean(this.opts.resumeSessionRef ?? this.opts.resumeSessionId));
@@ -257,8 +294,9 @@ export class ClaudeAdapter {
             this.eventQueue.close();
         }
     }
-    handle(msg) {
+    async handle(msg) {
         if ("session_id" in msg && typeof msg.session_id === "string") {
+            this.transportObservedSessionId = msg.session_id;
             this._sessionId = msg.session_id;
             this.observeSession(msg.session_id);
         }
@@ -287,14 +325,43 @@ export class ClaudeAdapter {
                 this.turnSignals.push(...msg.output.map((line) => `auth: ${line}`));
         }
         else if (msg.type === "system" && msg.subtype === "status") {
-            if (msg.status === "compacting")
+            if (msg.status === "compacting") {
+                this.compactionTerminalObserved = false;
                 this.eventQueue.push({ kind: "session-transition", transition: "compacting" });
+                const providerSequence = ++this.compactionSequence;
+                const origin = this.manualCompactionPending ? "rafi-manual" : "provider-auto";
+                this.activeCompaction = { providerEventId: msg.uuid, providerSequence, origin };
+                this.eventQueue.push({
+                    kind: "context-compaction", phase: "started", origin, providerEventId: msg.uuid,
+                    providerSequence, provider: "claude", sessionId: this._sessionId, sessionRef: this._sessionRef,
+                    observedAt: new Date().toISOString(),
+                });
+            }
             if (msg.compact_result === "success") {
                 this.compactResult = { ok: true };
                 this.eventQueue.push({ kind: "session-transition", transition: "compacted" });
+                if (!this.compactionTerminalObserved)
+                    await this.completeCompaction(true);
             }
             else if (msg.compact_result === "failed") {
                 this.compactResult = { ok: false, error: sanitizeDiagnostics(msg.compact_error ?? "Claude native compaction failed") };
+                if (!this.compactionTerminalObserved)
+                    await this.completeCompaction(false, this.compactResult.error);
+            }
+        }
+        else if (msg.type === "system" && msg.subtype === "compact_boundary") {
+            if (!this.compactionTerminalObserved) {
+                // The boundary is itself a successful native compact signal. Query the
+                // SDK immediately and use its post_tokens only as a fallback if that
+                // authoritative query is unavailable.
+                if (!this.activeCompaction) {
+                    this.activeCompaction = {
+                        providerEventId: msg.uuid,
+                        providerSequence: ++this.compactionSequence,
+                        origin: msg.compact_metadata.trigger === "manual" ? "rafi-manual" : "provider-auto",
+                    };
+                }
+                await this.completeCompaction(true, undefined, msg.compact_metadata.post_tokens);
             }
         }
         else if (msg.type === "system" && msg.subtype === "api_retry") {
@@ -356,7 +423,9 @@ export class ClaudeAdapter {
                 costUsd: msg.total_cost_usd,
                 costAuthoritative: Number.isFinite(msg.total_cost_usd),
                 failure,
+                ...(this.boundaryInterrupt ? { interrupted: { reason: "compaction-boundary", ...(this.boundaryInterrupt.providerEventId ? { providerEventId: this.boundaryInterrupt.providerEventId } : {}) } } : {}),
             };
+            this.boundaryInterrupt = undefined;
             const rawResult = msg;
             const mergedUsage = mergeClaudeProviderSessionUsage(this.cumulativeUsage, rawResult);
             result.inputTokens = mergedUsage.inputTokens;
@@ -371,7 +440,11 @@ export class ClaudeAdapter {
         }
     }
     sendTurn(text) {
-        return withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
+        return withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, async () => {
+            if (this.opts.contextManagementPolicy && !this.contextPrepared)
+                await this.prepareContextManagement(this.opts.contextManagementPolicy);
+            return this.sendTurnInternal(text);
+        });
     }
     sendTurnInternal(text) {
         if (this.closed)
@@ -423,18 +496,25 @@ export class ClaudeAdapter {
     }
     async compact() {
         this.compactResult = undefined;
-        const result = await this.sendTurn("/compact");
-        if (result.failure?.category === "session-unavailable") {
-            return { ok: false, error: result.text || result.failure.diagnostics, failure: result.failure };
+        this.manualCompactionPending = true;
+        try {
+            const result = await this.sendTurn("/compact");
+            if (result.failure?.category === "session-unavailable") {
+                return { ok: false, error: result.text || result.failure.diagnostics, failure: result.failure };
+            }
+            if (this.compactResult)
+                return this.compactResult;
+            return { ok: false, error: sanitizeDiagnostics(result.text || "Claude did not emit an explicit compact status") };
+        }
+        finally {
+            this.manualCompactionPending = false;
         }
-        if (this.compactResult)
-            return this.compactResult;
-        return { ok: false, error: sanitizeDiagnostics(result.text || "Claude did not emit an explicit compact status") };
     }
     async contextUsage() {
         try {
             const usage = await this.query.getContextUsage();
-            const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage, observedAt: new Date().toISOString(), source: "provider-query" };
+            const result = this.makeContextUsage(usage);
+            this.lastContextUsage = result;
             this.eventQueue.push({ kind: "context-usage", ...result });
             return result;
         }
@@ -442,6 +522,32 @@ export class ClaudeAdapter {
             return undefined;
         }
     }
+    async prepareContextManagement(policy) {
+        validateContextPolicy(policy);
+        if (this.contextPrepared)
+            return this.configureContextManagement(policy, false);
+        await this.query.initializationResult();
+        const prepared = await this.configureContextManagement(policy, true);
+        this.contextPrepared = true;
+        return prepared;
+    }
+    async updateContextManagement(policy) {
+        validateContextPolicy(policy);
+        return this.configureContextManagement(policy, false);
+    }
+    async interruptTurnAtCompactionBoundary(providerEventId) {
+        if (!this.pending)
+            return { ok: false, error: "no active Claude turn exists at the compaction boundary", providerEventId };
+        try {
+            this.boundaryInterrupt = { providerEventId };
+            await this.query.interrupt();
+            return { ok: true, providerEventId };
+        }
+        catch (error) {
+            this.boundaryInterrupt = undefined;
+            return { ok: false, error: error instanceof Error ? error.message : String(error), providerEventId };
+        }
+    }
     async sessionUsage() {
         return this.cumulativeUsage.observedAt === new Date(0).toISOString() ? undefined : { ...this.cumulativeUsage };
     }
@@ -450,11 +556,14 @@ export class ClaudeAdapter {
             return { ok: false, error: "Claude SDK cannot change reasoning/fast controls on an existing transport" };
         if (settings.model === this.opts.model)
             return { ok: true };
-        const result = await this.sendTurn(`/model ${settings.model ?? "default"}`);
-        if (result.isError)
-            return { ok: false, error: result.text, ...(result.failure ? { failure: result.failure } : {}) };
-        this.opts.model = settings.model;
-        return { ok: true };
+        try {
+            await this.query.setModel(settings.model);
+            this.opts.model = settings.model;
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
     }
     events() {
         return this.eventQueue;
@@ -483,6 +592,200 @@ export class ClaudeAdapter {
             source: "observed",
         });
     }
+    makeContextUsage(usage) {
+        const maximum = this.modelContextWindow
+            ?? (Number.isFinite(usage.maxTokens) && usage.maxTokens > 0 ? usage.maxTokens : this.lastContextUsage?.maximum);
+        // Once Rafi installs a smaller autoCompactWindow, the SDK's percentage and
+        // maxTokens describe that artificial window. Enforcement and display stay
+        // relative to the full model capacity discovered before reconfiguration.
+        const percentage = maximum ? usage.totalTokens / maximum * 100
+            : Number.isFinite(usage.percentage) ? usage.percentage : undefined;
+        return {
+            used: usage.totalTokens,
+            ...(maximum ? { maximum } : {}),
+            ...(percentage !== undefined ? { percentage } : {}),
+            observedAt: new Date().toISOString(),
+            source: "provider-query",
+            sequence: ++this.contextSequence,
+            ...(this._sessionId ? { sessionId: this._sessionId } : {}),
+            ...(this.opts.model ?? usage.model ? { model: this.opts.model ?? usage.model } : {}),
+        };
+    }
+    async configureContextManagement(policy, initial) {
+        const modelChanged = this.contextPolicy !== undefined && this.contextPolicy.model !== policy.model;
+        if (modelChanged) {
+            this.modelContextWindow = undefined;
+            this.nativeAutoCompactReserve = undefined;
+            await this.restartTransport();
+        }
+        this.contextPolicy = { ...policy };
+        this.compactionSequence = Math.max(this.compactionSequence, policy.providerSequenceStart ?? 0);
+        this.contextSequence = Math.max(this.contextSequence, policy.providerSequenceStart ?? 0);
+        if (initial || modelChanged || !this.modelContextWindow || !this.nativeAutoCompactReserve) {
+            // Enable first so getContextUsage exposes the provider's real trigger.
+            await this.query.applyFlagSettings({ autoCompactEnabled: true });
+            const baseline = await this.query.getContextUsage();
+            const baselineWindow = positiveNumber(baseline.maxTokens);
+            const baselineTrigger = positiveNumber(baseline.autoCompactThreshold);
+            if (!baselineWindow || !baselineTrigger || baselineTrigger >= baselineWindow) {
+                throw new Error("Claude did not expose a usable maxTokens/autoCompactThreshold pair after enabling native auto-compaction");
+            }
+            this.modelContextWindow = policy.knownModelContextWindow ?? baselineWindow;
+            this.nativeAutoCompactReserve = baselineWindow - baselineTrigger;
+        }
+        const maximum = this.modelContextWindow;
+        const reserve = this.nativeAutoCompactReserve;
+        const configuredTokenLimit = tokenCeiling(maximum, policy.configuredThresholdPercent);
+        // Claude's setting is a total window, not the used-token trigger. Preserve
+        // the SDK-reported output/compaction reserve so its resulting trigger lands
+        // on (or earlier than) Rafi's configured absolute ceiling.
+        const requestedNativeWindow = configuredTokenLimit + reserve;
+        await this.query.applyFlagSettings({ autoCompactEnabled: true, autoCompactWindow: requestedNativeWindow });
+        let verified = await this.query.getContextUsage();
+        // The SDK applies flag-layer changes through an internal settings watcher;
+        // give that watcher a short bounded interval before declaring the native
+        // control unavailable.
+        for (let attempt = 0; attempt < 4
+            && positiveNumber(verified.autoCompactThreshold) !== undefined
+            && positiveNumber(verified.autoCompactThreshold) > configuredTokenLimit; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            verified = await this.query.getContextUsage();
+        }
+        if (initial && positiveNumber(verified.autoCompactThreshold) > configuredTokenLimit) {
+            // Some SDK builds commit flag-layer changes to the active query state at
+            // the next streaming-input boundary. Use the same approved, tool-free
+            // setup exchange that the handoff monitor already recognizes, then
+            // verify again before any real role work is dispatched.
+            const setup = await this.sendTurnInternal("Rafi context setup only. Do not call tools or change files. Reply with exactly CONTEXT_READY.");
+            if (setup.isError || setup.text.trim() !== "CONTEXT_READY") {
+                throw new Error(`Claude context setup did not complete safely: ${setup.text.slice(0, 240)}`);
+            }
+            verified = await this.query.getContextUsage();
+        }
+        if (positiveNumber(verified.autoCompactThreshold) > configuredTokenLimit) {
+            // Current SDK releases accept applyFlagSettings but some noninteractive
+            // transports do not project autoCompactWindow into their already-created
+            // query state. Restart only that transport with equivalent inline flag
+            // settings and resume the exact scoped conversation.
+            await this.restartTransport(requestedNativeWindow);
+            verified = await this.query.getContextUsage();
+        }
+        if (!verified.isAutoCompactEnabled)
+            throw new Error("Claude disabled native auto-compaction during context configuration");
+        const installed = positiveNumber(verified.autoCompactThreshold);
+        if (!installed)
+            throw new Error("Claude did not report the installed native auto-compaction trigger");
+        if (installed > configuredTokenLimit) {
+            throw new Error(`Claude installed native compaction at ${installed} tokens, later than the configured ${configuredTokenLimit}-token ceiling `
+                + `(requested SDK window ${requestedNativeWindow}; this ceiling may be below the provider's supported minimum)`);
+        }
+        const sample = this.makeContextUsage(verified);
+        this.lastContextUsage = sample;
+        this.eventQueue.push({ kind: "context-usage", ...sample });
+        return {
+            modelContextWindow: maximum,
+            configuredTokenLimit,
+            installedNativeTokenLimit: installed,
+            installedNativePercent: installed / maximum * 100,
+            sample,
+        };
+    }
+    async restartTransport(nativeAutoCompactWindow) {
+        if (this.pending)
+            throw new Error("Claude context transport cannot restart while a provider turn is active");
+        const expectedSessionId = this._sessionId;
+        const expectedSessionRef = this._sessionRef;
+        if (!expectedSessionId || !expectedSessionRef) {
+            throw new Error("Claude context transport restart requires an established location-scoped session");
+        }
+        const priorQuery = this.query;
+        const priorInbox = this.inbox;
+        const priorPump = this.pumpDone;
+        const generation = ++this.transportGeneration;
+        priorInbox.close();
+        priorQuery.close();
+        await priorPump.catch(() => { });
+        this.inbox = new AsyncQueue();
+        this.abort = new AbortController();
+        this.streamEnded = false;
+        this.terminalResult = undefined;
+        this.transportObservedSessionId = undefined;
+        this.query = this.openQuery(nativeAutoCompactWindow);
+        this.pumpDone = this.pump(this.query, generation);
+        await this.query.initializationResult();
+        for (let attempt = 0; attempt < 10 && !this.transportObservedSessionId; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        if (this.transportObservedSessionId && this.transportObservedSessionId !== expectedSessionId) {
+            this.query.close();
+            throw new Error(`Claude context transport did not resume the exact scoped session ${expectedSessionId} `
+                + `(observed ${this.transportObservedSessionId})`);
+        }
+        if (!this.transportObservedSessionId) {
+            // Claude does not always repeat the session-start frame until the next
+            // user message. Validate the exact persisted, location-scoped target;
+            // the immediately following context query then proves this transport is
+            // usable before any real role action is dispatched.
+            const availability = await probeClaudeSession(expectedSessionRef, {
+                cwd: this.opts.cwd,
+                configRoot: this.opts.configRoot,
+                workspaceIdentity: this.opts.workspaceIdentity,
+                role: this.opts.sessionRole,
+                stream: this.opts.sessionStream,
+                ticketId: this.opts.ticketId,
+                deliveryUnitId: this.opts.deliveryUnitId,
+            });
+            if (availability.status !== "available") {
+                this.query.close();
+                throw new Error(`Claude context transport could not validate scoped session ${expectedSessionId}: `
+                    + `${availability.reason ?? availability.status} (${availability.detail ?? "no provider detail"})`);
+            }
+        }
+    }
+    async completeCompaction(ok, reason, fallbackPostTokens) {
+        this.compactionTerminalObserved = true;
+        const active = this.activeCompaction;
+        const providerSequence = active?.providerSequence ?? ++this.compactionSequence;
+        const providerEventId = active?.providerEventId ?? `claude:${this._sessionId ?? "pending"}:${providerSequence}`;
+        const origin = active?.origin ?? (this.manualCompactionPending ? "rafi-manual" : "provider-auto");
+        this.activeCompaction = undefined;
+        if (!ok) {
+            this.eventQueue.push({
+                kind: "context-compaction", phase: "failed", origin, providerEventId, providerSequence,
+                provider: "claude", sessionId: this._sessionId, sessionRef: this._sessionRef,
+                observedAt: new Date().toISOString(), reason,
+            });
+            return;
+        }
+        let postCompactSample;
+        try {
+            const usage = await this.query.getContextUsage();
+            postCompactSample = { ...this.makeContextUsage(usage), source: "post-compact" };
+            this.lastContextUsage = postCompactSample;
+            this.eventQueue.push({ kind: "context-usage", ...postCompactSample });
+        }
+        catch {
+            if (fallbackPostTokens !== undefined && this.lastContextUsage?.maximum) {
+                postCompactSample = {
+                    ...this.makeContextUsage({
+                        totalTokens: fallbackPostTokens,
+                        maxTokens: this.lastContextUsage.maximum,
+                        model: this.opts.model,
+                    }),
+                    source: "post-compact",
+                };
+                this.lastContextUsage = postCompactSample;
+                this.eventQueue.push({ kind: "context-usage", ...postCompactSample });
+            }
+            // Otherwise the shared coordinator records this success as unverified
+            // and hands off after its own bounded query attempts.
+        }
+        this.eventQueue.push({
+            kind: "context-compaction", phase: "succeeded", origin, providerEventId, providerSequence,
+            provider: "claude", sessionId: this._sessionId, sessionRef: this._sessionRef,
+            observedAt: new Date().toISOString(), ...(postCompactSample ? { postCompactSample } : {}),
+        });
+    }
     settlePending(result, emit = true) {
         const pending = this.pending;
         if (!pending)
@@ -510,6 +813,20 @@ export class ClaudeAdapter {
     }
 }
 function finiteNumber(value) { const parsed = Number(value); return value !== null && value !== undefined && value !== "" && Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined; }
+function positiveNumber(value) {
+    const parsed = Number(value);
+    return value !== null && value !== undefined && value !== "" && Number.isFinite(parsed) && parsed > 0 ? parsed : 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 isMissingClaudeSession(message) {
     return /no conversation found with session id|session .* not found|conversation .* not found/i.test(message);
 }

package/dist/adapters/codex.d.ts

@@ -1,4 +1,4 @@
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextManagementPolicy, ContextUsage, InterruptResult, PreparedContextManagement, ProviderSessionUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 export interface CodexLineResult {
     events: BuilderEvent[];
@@ -24,9 +24,21 @@ export declare class CodexAdapter implements BuilderAdapter {
     private activeText;
     private usage?;
     private usageRevision;
+    private contextSequence;
     private providerSessionUsage?;
     private lastTurnTokens?;
     private stderr;
+    private contextPolicy?;
+    private nativeTokenLimit?;
+    private spawnedNativeTokenLimit?;
+    private contextPrepared;
+    private setupTurnActive;
+    private setupToolAttempted;
+    private activeTurnId?;
+    private boundaryInterrupt?;
+    private compactionSequence;
+    private activeCompaction?;
+    private manualCompactionPending;
     constructor(opts: BuilderAdapterOptions);
     buildInstruction(instruction: string): string;
     buildAppServerArgs(): string[];
@@ -34,6 +46,9 @@ export declare class CodexAdapter implements BuilderAdapter {
     buildArgs(instruction: string): string[];
     sendTurn(instruction: string): Promise<TurnResult>;
     private sendTurnInternal;
+    prepareContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    updateContextManagement(policy: ContextManagementPolicy): Promise<PreparedContextManagement>;
+    interruptTurnAtCompactionBoundary(providerEventId?: string): Promise<InterruptResult>;
     compact(): Promise<CompactResult>;
     contextUsage(): Promise<ContextUsage | undefined>;
     sessionUsage(): Promise<ProviderSessionUsage | undefined>;
@@ -52,5 +67,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     private handle;
     private waitFor;
     private disconnect;
+    /** Restart only app-server; the scoped thread remains the continuity boundary. */
+    private restartTransport;
     private buildSkillsAppendix;
 }