ai-foreman 1.7.8 → 1.7.9

package/README.md

@@ -115,9 +115,7 @@ 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 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-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-detected tracker files:
 
@@ -609,14 +607,6 @@ 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-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 === "context-usage")
+        reporter.pulse(event.percentage === undefined ? undefined : `context ${event.percentage.toFixed(0)}%`);
     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, ContextManagementPolicy, ContextUsage, InterruptResult, PermissionDecision, PreparedContextManagement, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, NativeCompaction, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, ProviderSessionUsage, TurnResult } from "./types.js";
 import type { ProviderSessionRefV1, SessionAvailabilityV1 } from "rafi-spec";
 /**
  * Pure function: build the `options` object passed to `query()`.
@@ -43,14 +43,11 @@ export declare function claudeApiRetryEvent(message: {
 export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly opts;
     readonly agent: "claude";
-    private inbox;
+    private readonly inbox;
     private readonly eventQueue;
-    private query;
-    private abort;
-    private pumpDone;
-    private readonly queryFactory;
-    private transportGeneration;
-    private transportObservedSessionId?;
+    private readonly query;
+    private readonly abort;
+    private readonly pumpDone;
     private _sessionId?;
     private _sessionRef?;
     private readonly stderrChunks;
@@ -58,19 +55,11 @@ 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 autoCompactionPrepared;
+    private preparedAutoCompactThreshold?;
+    private manualCompactionInFlight;
+    private nativeCompactions;
+    private nativeCompactionSequence;
     private cumulativeUsage;
     private pending?;
     private terminalResult?;
@@ -78,7 +67,6 @@ 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;
@@ -90,19 +78,15 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     adoptSessionRef(ref: ProviderSessionRefV1): void;
     validateSession(): Promise<SessionAvailabilityV1>;
     compact(): Promise<CompactResult>;
+    prepareAutoCompaction(thresholdPercent?: number | undefined): Promise<void>;
+    drainNativeCompactions(): NativeCompaction[];
+    restoreNativeCompactions(compactions: NativeCompaction[]): void;
     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,10 +145,6 @@ export class ClaudeAdapter {
     query;
     abort = new AbortController();
     pumpDone;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    queryFactory;
-    transportGeneration = 0;
-    transportObservedSessionId;
     _sessionId;
     _sessionRef;
     stderrChunks = [];
@@ -156,19 +152,11 @@ 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;
+    autoCompactionPrepared = false;
+    preparedAutoCompactThreshold;
+    manualCompactionInFlight = false;
+    nativeCompactions = [];
+    nativeCompactionSequence = 0;
     cumulativeUsage = { observedAt: new Date(0).toISOString(), source: "provider" };
     pending;
     terminalResult;
@@ -212,30 +200,18 @@ export class ClaudeAdapter {
         }
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    constructor(opts, queryFactory) {
+    constructor(opts, query) {
         this.opts = opts;
         this._sessionId = opts.resumeSessionRef?.sessionId ?? opts.resumeSessionId;
         this._sessionRef = opts.resumeSessionRef;
-        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({
+        this.query = query({
             prompt: this.inbox,
             options: {
-                ...buildClaudeQueryOptions(scopedOpts),
-                ...(nativeAutoCompactWindow === undefined ? {} : {
-                    settings: { autoCompactEnabled: true, autoCompactWindow: nativeAutoCompactWindow },
-                }),
+                ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
                 stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input, requestOptions = {}) => {
-                    const decision = await this.opts.permission({
+                    const decision = await opts.permission({
                         toolName,
                         input,
                         signal: requestOptions.signal,
@@ -250,22 +226,16 @@ export class ClaudeAdapter {
                 },
             },
         });
+        this.pumpDone = this.pump();
     }
     /** Background loop: consume the SDK message stream until it ends. */
-    async pump(query, generation) {
+    async pump() {
         try {
-            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);
+            for await (const msg of this.query) {
+                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 &&
@@ -280,8 +250,6 @@ 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));
@@ -294,9 +262,8 @@ export class ClaudeAdapter {
             this.eventQueue.close();
         }
     }
-    async handle(msg) {
+    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);
         }
@@ -325,43 +292,16 @@ export class ClaudeAdapter {
                 this.turnSignals.push(...msg.output.map((line) => `auth: ${line}`));
         }
         else if (msg.type === "system" && msg.subtype === "status") {
-            if (msg.status === "compacting") {
-                this.compactionTerminalObserved = false;
+            if (msg.status === "compacting")
                 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);
+                if (!this.manualCompactionInFlight)
+                    this.nativeCompactions.push({ id: `claude:${this._sessionId ?? "unknown"}:${++this.nativeCompactionSequence}`, occurredAt: new Date().toISOString(), provider: "claude" });
             }
             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") {
@@ -423,9 +363,7 @@ 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;
@@ -440,11 +378,7 @@ export class ClaudeAdapter {
         }
     }
     sendTurn(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);
-        });
+        return withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
     }
     sendTurnInternal(text) {
         if (this.closed)
@@ -496,25 +430,62 @@ export class ClaudeAdapter {
     }
     async compact() {
         this.compactResult = undefined;
-        this.manualCompactionPending = true;
+        this.manualCompactionInFlight = true;
+        let result;
         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") };
+            result = await this.sendTurn("/compact");
         }
         finally {
-            this.manualCompactionPending = false;
+            this.manualCompactionInFlight = false;
+        }
+        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") };
     }
+    async prepareAutoCompaction(thresholdPercent = this.opts.autoCompactThresholdPercent) {
+        if (thresholdPercent === undefined)
+            return;
+        const threshold = validThreshold(thresholdPercent);
+        if (this.autoCompactionPrepared && this.preparedAutoCompactThreshold === threshold)
+            return;
+        this.opts.autoCompactThresholdPercent = threshold;
+        await this.query.initializationResult();
+        await this.query.applyFlagSettings({ autoCompactEnabled: true });
+        const baseline = await this.query.getContextUsage();
+        if (!Number.isFinite(baseline.maxTokens) || baseline.maxTokens <= 0
+            || !Number.isFinite(baseline.autoCompactThreshold) || baseline.autoCompactThreshold === undefined
+            || !baseline.isAutoCompactEnabled) {
+            throw new Error("Claude did not expose an enabled native automatic-compaction threshold");
+        }
+        // Claude's setting is the total window. Preserve the provider's own
+        // response/compaction reserve, so the resulting used-token trigger is at
+        // or before Rafi's configured percentage.
+        const reserve = baseline.maxTokens - baseline.autoCompactThreshold;
+        if (reserve < 0)
+            throw new Error("Claude reported an invalid automatic-compaction reserve");
+        const requestedWindow = tokenLimit(baseline.maxTokens, threshold) + reserve;
+        await this.query.applyFlagSettings({ autoCompactEnabled: true, autoCompactWindow: requestedWindow });
+        const installed = await this.query.getContextUsage();
+        if (!installed.isAutoCompactEnabled || installed.autoCompactThreshold === undefined
+            || installed.autoCompactThreshold > tokenLimit(baseline.maxTokens, threshold)) {
+            throw new Error("Claude did not accept the requested native automatic-compaction ceiling");
+        }
+        this.autoCompactionPrepared = true;
+        this.preparedAutoCompactThreshold = threshold;
+    }
+    drainNativeCompactions() {
+        const pending = this.nativeCompactions;
+        this.nativeCompactions = [];
+        return pending;
+    }
+    restoreNativeCompactions(compactions) { this.nativeCompactions.unshift(...compactions); }
     async contextUsage() {
         try {
             const usage = await this.query.getContextUsage();
-            const result = this.makeContextUsage(usage);
-            this.lastContextUsage = result;
+            const result = { used: usage.totalTokens, maximum: usage.maxTokens, percentage: usage.percentage, observedAt: new Date().toISOString(), source: "provider-query" };
             this.eventQueue.push({ kind: "context-usage", ...result });
             return result;
         }
@@ -522,32 +493,6 @@ 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 };
     }
@@ -556,14 +501,11 @@ 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 };
-        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) };
-        }
+        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 };
     }
     events() {
         return this.eventQueue;
@@ -592,200 +534,6 @@ 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)
@@ -813,20 +561,14 @@ 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 validThreshold(value) {
+    if (!Number.isInteger(value) || value < 1 || value > 99)
+        throw new Error("automatic compaction threshold must be an integer from 1 to 99");
+    return value;
 }
-function tokenCeiling(maximum, percentage) {
+function tokenLimit(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);
 }