@aragon-agent/cli 0.6.13 → 0.6.15

package/dist/agent/controller.d.ts

@@ -1,5 +1,6 @@
 import { type ModelSettingsSnapshot } from './model-profile-settings.js';
 import type { ModelSettingsDraft, ModelSettingsPatch, ModelSettingsSaveResult } from '../config/model-profile-store.js';
+import { type CompactionIdentity } from '../compaction/memory-identity.js';
 /**
  * AgentController — builds the core `Agent`, wires the built-in toolset, and
  * exposes a small run/abort/steer surface plus the pre-flight validation that
@@ -123,6 +124,10 @@ export declare class AgentController {
     private readonly agent;
     private readonly providerRegistry;
     private readonly modelRegistry;
+    private modelMetadataEnabled;
+    private modelMetadataGeneration;
+    private modelMetadataAbort;
+    private disposed;
     private readonly tools;
     private readonly skills;
     private readonly skillsEnabled;
@@ -184,6 +189,10 @@ export declare class AgentController {
     private readonly fast;
     private readonly compaction;
     private settingsRevision;
+    private requestVersion;
+    private idleCompaction;
+    private restoredCompactionIdentity;
+    private readonly compactionBusyListeners;
     private modelSettingsBlocked;
     private preparedSystemPrompt;
     private readonly contextMeter;
@@ -287,6 +296,7 @@ export declare class AgentController {
     private waitForEngineIdle;
     /** Prepare before clearing the plan, then enter the engine without yielding. */
     private startPrompt;
+    private prepareUserTurn;
     /** Cancel pending startup as well as any engine run already in progress. */
     abort(): void;
     private stopEngine;
@@ -375,6 +385,11 @@ export declare class AgentController {
     queueUserMessage(text: string): string;
     private enqueueSteering;
     followUp(text: string): void;
+    /** Resume queued input without appending a duplicate user message. */
+    continue(): Promise<PromptOutcome>;
+    /** Pending user receipts survive until Core accepts or the host clears them. */
+    hasPendingUserMessages(): boolean;
+    private compactionBusyOutcome;
     isRunning(): boolean;
     getAgentMode(): AgentMode;
     /**
@@ -534,6 +549,7 @@ export declare class AgentController {
     isModelSettingsBusy(): boolean;
     /** Monotonic revision protects an editor from all intervening settings changes. */
     getSettingsRevision(): number;
+    private advanceSettingsRevision;
     /** Read-only draft creation; no startup migration or credential copying. */
     createModelSettingsDraft(): ModelSettingsDraft;
     /** Save an explicit draft as a single disk/live transaction. */
@@ -592,8 +608,15 @@ export declare class AgentController {
     clearMessages(): void;
     /** Read-only view of the live system prompt (regression tests, /debug). */
     getSystemPrompt(): string;
-    replaceMessages(messages: Message[]): void;
+    replaceMessages(messages: Message[], identity?: CompactionIdentity): void;
     getMessages(): Message[];
+    /** Atomically capture adopted history and its host credential for serialization. */
+    getSessionSnapshot(): {
+        messages: Message[];
+        compactionIdentity?: CompactionIdentity;
+    };
+    /** Compatibility name for the documented compaction session boundary. */
+    getCompactionSessionState(): ReturnType<AgentController['getSessionSnapshot']>;
     clearAllQueues(): void;
     getConfig(): CliConfig;
     getProviderRegistry(): ProviderRegistry;
@@ -608,7 +631,11 @@ export declare class AgentController {
      * cost table for the model that actually billed" cannot drift from "the cost
      * table for the session's model" as two separate bodies.
      */
-    getModelInfoFor(ref: Pick<ModelRef, 'providerId' | 'modelId'>): ModelInfo;
+    getModelInfoFor(ref: Pick<ModelRef, 'providerId' | 'modelId' | 'baseUrl'>): ModelInfo;
+    /** Best-effort metadata lookup; never block typing or a model request. */
+    refreshModelMetadata(): Promise<void>;
+    /** Invalidate an old connection without restarting a lookup on every prompt. */
+    private resetModelMetadataRequest;
     /**
      * Whether the STATIC table knows this model's price (C-11 / RV-4).
      *
@@ -751,6 +778,13 @@ export declare class AgentController {
         ok: boolean;
         reason?: string;
     }>;
+    /** Local prepare/adopt ownership, available before any network-start event. */
+    isCompactionBusy(): boolean;
+    /** Cancel local compaction and await ownership release before a conversation switch. */
+    cancelCompaction(): Promise<void>;
+    /** Subscribe to synchronous ownership transitions; observers cannot break adoption. */
+    subscribeCompactionBusy(listener: (busy: boolean) => void): () => void;
+    private publishCompactionBusy;
     /**
      * Subscribe to the CLI-local compaction event stream.
      *

package/dist/agent/controller.js

@@ -1,5 +1,7 @@
 import { createModelSettingsDraft, saveModelSettings, reloadModelSettings, } from './model-profile-settings.js';
 import { randomUUID } from 'node:crypto';
+import { verifyCompactionIdentity } from '../compaction/memory-identity.js';
+import { COMPACTION_LIMITS } from '../compaction/limits.js';
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
 import { clampCompactionConfig, clampFastConfig, clampRetryConfig, clampTeamConfig, clampTodoConfig, isAdapterProvider, toRetryPolicy, } from '../config/schema.js';
 import { resolveModelProfileState } from '../config/model-profile-resolution.js';
@@ -51,6 +53,10 @@ export class AgentController {
     agent;
     providerRegistry;
     modelRegistry;
+    modelMetadataEnabled = false;
+    modelMetadataGeneration = 0;
+    modelMetadataAbort = new AbortController();
+    disposed = false;
     tools;
     skills;
     skillsEnabled;
@@ -197,6 +203,10 @@ export class AgentController {
     // and a `Set`.
     // -----------------------------------------------------------------------
     settingsRevision = 0;
+    requestVersion = 0;
+    idleCompaction;
+    restoredCompactionIdentity;
+    compactionBusyListeners = new Set();
     modelSettingsBlocked = false;
     preparedSystemPrompt;
     contextMeter;
@@ -249,7 +259,7 @@ export class AgentController {
      */
     abortRequested = false;
     /** Only exact acceptance receipts release user messages from reviewer protection. */
-    pendingUserSteering = new Set();
+    pendingUserSteering = new Map();
     /** Session changes must not make a delayed receipt match a new message. */
     steeringPrefix = randomUUID();
     steeringSequence = 0;
@@ -526,18 +536,12 @@ export class AgentController {
         // EVERY session, including one with compaction off, because that is the one
         // whose gauge was broken (P1-4 / P0-2).
         this.contextMeter = new ContextMeter({
+            getRequestVersion: () => this.requestVersion,
             getMessages: () => this.agent.state.messages,
             getSystemPrompt: () => this.agent.state.systemPrompt,
             getModelInfo: () => this.getModelInfo(),
-            // ONE PREDICATE FOR "IS THE DENOMINATOR REAL". `isPricedModel` is
-            // `modelRegistry.getModel(...) !== undefined`, and `getModelInfoFor` falls
-            // back to `buildRuntimeModel` - a 128k placeholder AND a zero cost table -
-            // for exactly the models it answers `false` for. The two are the same
-            // question about the same static table, not a coincidence.
-            isWindowKnown: () => this.isPricedModel({
-                providerId: this.config.provider,
-                modelId: this.config.model,
-            }),
+            // Context discovery does not imply that the model's price is known.
+            isWindowKnown: () => this.getModelInfo().contextWindowSource !== 'fallback',
             // LIVE, so a settings-screen edit moves the denominator without a relaunch.
             getWindowOverride: () => this.config.contextWindow,
         });
@@ -771,7 +775,10 @@ export class AgentController {
         });
     }
     rebuildSystemPrompt() {
-        this.agent.setSystemPrompt(this.preparedSystemPrompt ?? this.composeSystemPrompt());
+        const prompt = this.preparedSystemPrompt ?? this.composeSystemPrompt();
+        if (prompt !== this.agent.state.systemPrompt)
+            this.idleCompaction?.abort();
+        this.agent.setSystemPrompt(prompt);
     }
     /** Re-render the prompt from the current skill set and tell the UI. */
     refreshSkills() {
@@ -802,7 +809,7 @@ export class AgentController {
      * re-memoizes the palette (P1-1). Does not touch `@aragon-agent/core`.
      */
     setTheme(name) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, theme: name };
     }
     /**
@@ -859,10 +866,14 @@ export class AgentController {
      * never rejects, so callers must not treat resolution as success.
      */
     async prompt(text, options = {}) {
+        if (this.isCompactionBusy())
+            return this.compactionBusyOutcome();
         // Capture BEFORE stopping: synchronous abort listeners may cancel this request.
         if (this.modelSettingsBlocked) {
             return { status: 'not-started', reason: 'failed' };
         }
+        if (this.modelMetadataEnabled)
+            void this.refreshModelMetadata();
         const request = ++this.startupSequence;
         try {
             if (this.agent.state.isRunning) {
@@ -874,6 +885,8 @@ export class AgentController {
             }
             if (this.agent.state.isRunning)
                 throw new Error('The previous run is still stopping.');
+            if (this.isCompactionBusy())
+                return this.compactionBusyOutcome();
             return await this.startPrompt(text, options, request);
         }
         catch (err) {
@@ -909,10 +922,7 @@ export class AgentController {
     }
     /** Prepare before clearing the plan, then enter the engine without yielding. */
     async startPrompt(text, options, request) {
-        if (this.skillsEnabled)
-            this.skills.beginUserTurn();
-        this.askRounds = 0;
-        this.fast?.setGoal(text);
+        this.prepareUserTurn(text);
         if (request !== this.startupSequence) {
             return { status: 'not-started', reason: 'cancelled' };
         }
@@ -920,9 +930,16 @@ export class AgentController {
         await this.agent.prompt(text);
         return { status: 'finished' };
     }
+    prepareUserTurn(text) {
+        if (this.skillsEnabled)
+            this.skills.beginUserTurn();
+        this.askRounds = 0;
+        this.fast?.setGoal(text);
+    }
     /** Cancel pending startup as well as any engine run already in progress. */
     abort() {
         this.startupSequence += 1;
+        this.idleCompaction?.abort();
         this.stopEngine();
     }
     stopEngine() {
@@ -1067,11 +1084,11 @@ export class AgentController {
     }
     enqueueSteering(text, user) {
         // Both reviewer and user guidance can activate queued skill frames.
-        if (this.skillsEnabled)
+        if (this.skillsEnabled && this.isRunning())
             this.skills.absorbPendingFrames();
         const id = user ? `${this.steeringPrefix}:${++this.steeringSequence}` : undefined;
         if (id !== undefined)
-            this.pendingUserSteering.add(id);
+            this.pendingUserSteering.set(id, text);
         try {
             this.agent.steer(text, id);
         }
@@ -1085,6 +1102,30 @@ export class AgentController {
     followUp(text) {
         this.agent.followUp(text);
     }
+    /** Resume queued input without appending a duplicate user message. */
+    async continue() {
+        if (this.isCompactionBusy())
+            return this.compactionBusyOutcome();
+        if (this.modelSettingsBlocked || this.isRunning()) {
+            return { status: 'not-started', reason: 'failed' };
+        }
+        if (this.pendingUserSteering.size > 0) {
+            const request = ++this.startupSequence;
+            this.prepareUserTurn([...this.pendingUserSteering.values()].join('\n\n'));
+            if (request !== this.startupSequence) {
+                return { status: 'not-started', reason: 'cancelled' };
+            }
+            this.todos?.beginUserTurn('new-task');
+        }
+        await this.agent.continue();
+        return { status: 'finished' };
+    }
+    /** Pending user receipts survive until Core accepts or the host clears them. */
+    hasPendingUserMessages() { return this.pendingUserSteering.size > 0; }
+    compactionBusyOutcome() {
+        this.notifyHostFn?.('warn', 'Context compaction is busy; your input was not submitted.');
+        return { status: 'not-started', reason: 'failed' };
+    }
     isRunning() {
         return this.agent.state.isRunning;
     }
@@ -1217,7 +1258,7 @@ export class AgentController {
      * honestly by checking `isTeamRegistered()` first.
      */
     setTeamEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.teamEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1231,7 +1272,7 @@ export class AgentController {
      */
     setTeamConfig(patch) {
         const team = clampTeamConfig({ ...this.config.team, ...patch });
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, team };
         this.rebuildSystemPrompt();
         return team;
@@ -1257,6 +1298,10 @@ export class AgentController {
     }
     /** Abort every child and clear timers. Idempotent; safe to call twice. */
     dispose() {
+        this.idleCompaction?.abort();
+        this.disposed = true;
+        this.modelMetadataGeneration += 1;
+        this.modelMetadataAbort.abort();
         this.teamRuntime?.dispose();
         this.fast?.dispose();
         this.compaction?.dispose();
@@ -1293,7 +1338,7 @@ export class AgentController {
      * reports that honestly by checking `isTodoRegistered()` first.
      */
     setTodoEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.todoEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1316,7 +1361,7 @@ export class AgentController {
      */
     setTodoConfig(patch) {
         const todo = clampTodoConfig({ ...this.config.todo, ...patch });
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, todo };
         this.rebuildSystemPrompt();
         return todo;
@@ -1372,7 +1417,7 @@ export class AgentController {
      */
     setRetryConfig(patch) {
         const retry = clampRetryConfig({ ...this.config.retry, ...patch });
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, retry };
         this.providerRegistry.setRetryPolicy(toRetryPolicy(retry));
         return retry;
@@ -1382,11 +1427,16 @@ export class AgentController {
     // -----------------------------------------------------------------------
     /** True while any request can still use a model or credential snapshot. */
     isModelSettingsBusy() {
-        return this.isRunning() || this.isTeamBusy() || this.getCompactionSnapshot().inFlight
+        return this.isRunning() || this.isTeamBusy() || this.isCompactionBusy()
+            || this.getCompactionSnapshot().inFlight
             || this.getFastStatus().snapshot.inFlight;
     }
     /** Monotonic revision protects an editor from all intervening settings changes. */
     getSettingsRevision() { return this.settingsRevision; }
+    advanceSettingsRevision() {
+        this.settingsRevision += 1;
+        this.idleCompaction?.abort();
+    }
     /** Read-only draft creation; no startup migration or credential copying. */
     createModelSettingsDraft() {
         return createModelSettingsDraft(this.config, this.settingsRevision);
@@ -1412,21 +1462,37 @@ export class AgentController {
     }
     /** Apply prepared state synchronously, without rebuilding the controller or its history. */
     applyModelSettingsSnapshot(snapshot) {
+        const connectionChanged = this.config.provider !== snapshot.config.provider
+            || this.config.model !== snapshot.config.model || this.config.baseUrl !== snapshot.config.baseUrl;
+        this.idleCompaction?.abort();
         this.preparedSystemPrompt = snapshot.systemPrompt;
         try {
             this.config = snapshot.config;
-            this.settingsRevision += 1;
+            this.advanceSettingsRevision();
             this.agent.setModel(snapshot.model);
             this.agent.setThinkingLevel(snapshot.config.thinkingLevel);
             this.agent.setMaxTokens(snapshot.config.maxTokens);
+            // Credentials may change even when endpoint/model do not. Invalidate
+            // before publishing a window, including when the new profile has no key.
+            if (this.modelMetadataEnabled) {
+                this.resetModelMetadataRequest();
+                this.modelRegistry.clearCache();
+            }
             this.fast?.onConfigChanged(false, snapshot.config.fast.enabled);
             this.compaction?.onConfigChanged(snapshot.config.compaction.enabled);
-            this.contextMeter.onWindowChanged();
+            if (connectionChanged) {
+                this.requestVersion += 1;
+                this.contextMeter.onHistoryReplaced();
+            }
+            else
+                this.contextMeter.onWindowChanged();
             this.rebuildSystemPrompt();
         }
         finally {
             this.preparedSystemPrompt = undefined;
         }
+        if (this.modelMetadataEnabled)
+            void this.refreshModelMetadata();
     }
     /** Potentially failing ordinary-setting side effects are isolated from model application. */
     applyModelSettingsEffects() { getLogger().reconfigure(this.config.log); }
@@ -1434,13 +1500,18 @@ export class AgentController {
     blockModelSettingsRequests() {
         this.modelSettingsBlocked = true;
         this.config.modelSettingsRestartRequired = true;
+        this.resetModelMetadataRequest();
     }
     /** The UI uses this before accepting or draining queued prompts. */
     areModelSettingsBlocked() { return this.modelSettingsBlocked; }
     setModel(provider, model, baseUrl) {
         if (this.isModelSettingsBusy())
             throw new Error('Model settings are busy.');
-        this.settingsRevision += 1;
+        const connectionChanged = this.config.provider !== provider || this.config.model !== model
+            || this.config.baseUrl !== baseUrl;
+        if (this.modelMetadataEnabled)
+            this.resetModelMetadataRequest();
+        this.advanceSettingsRevision();
         this.config = { ...this.config, provider, model, baseUrl };
         this.config.modelProfileState = resolveModelProfileState(this.config);
         this.agent.setModel({ providerId: provider, modelId: model, ...(baseUrl ? { baseUrl } : {}) });
@@ -1455,32 +1526,39 @@ export class AgentController {
         // so the snapshot the chip and `/compact status` read has to be refreshed
         // for the same reason and at the same moments (the RV-3 lesson).
         this.compaction?.onConfigChanged();
-        // THE DENOMINATOR MOVED, NOT THE HISTORY (context-usage-gauge-accuracy §3.4).
-        // A re-measure, deliberately NOT a reset: the measured base is still a true
-        // statement about the messages, and throwing it away would swap a correct
-        // numerator for a whole-history estimate on a common operation. The
-        // numerator's calibration is one turn stale until the next `turn_end`
-        // (RV-13), which is the trade this call names.
-        this.contextMeter.onWindowChanged();
+        if (connectionChanged) {
+            this.requestVersion += 1;
+            this.contextMeter.onHistoryReplaced();
+        }
+        else
+            this.contextMeter.onWindowChanged();
+        if (this.modelMetadataEnabled)
+            void this.refreshModelMetadata();
     }
     setThinkingLevel(level) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, thinkingLevel: level };
         this.agent.setThinkingLevel(level);
     }
     setMaxTokens(value) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, maxTokens: value };
         this.agent.setMaxTokens(value);
     }
     setApiKey(provider, key) {
         // The Agent resolves keys via `resolveKey(this.config)` at call time, so
         // updating the config here is sufficient — no Agent rebuild needed.
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = {
             ...this.config,
             apiKeys: { ...this.config.apiKeys, [provider]: key },
         };
+        if (this.modelMetadataEnabled) {
+            this.resetModelMetadataRequest();
+            this.modelRegistry.clearCache(provider);
+            this.contextMeter.onWindowChanged();
+            void this.refreshModelMetadata();
+        }
         // Rule 5 of §3.2 reads `apiKeys`, so a key edit is a tier event: this is the
         // path that turns `no_key` back into a working tier without a relaunch.
         this.fast?.onConfigChanged();
@@ -1491,7 +1569,7 @@ export class AgentController {
     }
     setCwd(cwd) {
         this.cwd = cwd;
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, cwd };
         // The project scope moved with the cwd, so rescan BEFORE rebuilding — then
         // let the single prompt entry point emit a prompt that reflects both the new
@@ -1560,6 +1638,8 @@ export class AgentController {
         };
     }
     clearMessages() {
+        this.idleCompaction?.abort();
+        this.restoredCompactionIdentity = undefined;
         this.agent.clearMessages();
         this.startupSequence += 1;
         // INVALIDATION SITE 3 (context-auto-compaction-hardening §3.2.3). The history
@@ -1587,7 +1667,9 @@ export class AgentController {
     getSystemPrompt() {
         return this.agent.state.systemPrompt;
     }
-    replaceMessages(messages) {
+    replaceMessages(messages, identity) {
+        this.idleCompaction?.abort();
+        this.restoredCompactionIdentity = identity;
         this.agent.replaceMessages(messages);
         this.startupSequence += 1;
         // INVALIDATION SITE 4 (§3.2.3) - `/resume`, and any future host-side rewrite.
@@ -1600,12 +1682,26 @@ export class AgentController {
         // reading stood until the next completed turn. The DEEP reset also drops
         // `estimateOffset`, because `/resume` can change the model in the same
         // breath (I-8).
-        this.compaction?.onHistoryReplaced();
+        this.compaction?.onHistoryReplaced(identity);
         this.contextMeter.onHistoryReplaced();
     }
     getMessages() {
         return this.agent.state.messages;
     }
+    /** Atomically capture adopted history and its host credential for serialization. */
+    getSessionSnapshot() {
+        const messages = this.getMessages();
+        const identity = this.compaction ? this.compaction.getIdentity() : this.restoredCompactionIdentity;
+        if (identity && !verifyCompactionIdentity(messages, identity)) {
+            getLogger().debug('agent', 'invalid_compaction_session_identity');
+        }
+        // Retain invalid evidence so damaged host memory cannot become ordinary text.
+        return { messages, ...(identity ? { compactionIdentity: { ...identity } } : {}) };
+    }
+    /** Compatibility name for the documented compaction session boundary. */
+    getCompactionSessionState() {
+        return this.getSessionSnapshot();
+    }
     clearAllQueues() {
         this.agent.clearAllQueues();
         this.pendingUserSteering.clear();
@@ -1639,9 +1735,38 @@ export class AgentController {
      */
     getModelInfoFor(ref) {
         const found = this.modelRegistry.getModel(ref.providerId, ref.modelId);
-        if (found)
-            return found;
-        return this.modelRegistry.buildRuntimeModel(ref.providerId, ref.modelId);
+        const baseUrl = ref.baseUrl ?? (ref.providerId === this.config.provider && ref.modelId === this.config.model
+            ? this.config.baseUrl : undefined);
+        return {
+            ...(found ?? this.modelRegistry.buildRuntimeModel(ref.providerId, ref.modelId)),
+            ...this.modelRegistry.getContextWindow(ref.providerId, ref.modelId, baseUrl),
+        };
+    }
+    /** Best-effort metadata lookup; never block typing or a model request. */
+    async refreshModelMetadata() {
+        if (this.disposed || this.modelSettingsBlocked)
+            return;
+        this.modelMetadataEnabled = true;
+        const generation = ++this.modelMetadataGeneration;
+        const { provider, baseUrl } = this.config;
+        try {
+            const key = this.resolveKey(provider);
+            if (!key)
+                return;
+            await this.modelRegistry.discoverModels(provider, key, baseUrl, this.modelMetadataAbort.signal);
+            if (this.disposed || generation !== this.modelMetadataGeneration)
+                return;
+            this.contextMeter.onWindowChanged();
+        }
+        catch {
+            // Offline or unsupported discovery leaves catalog/unknown metadata intact.
+        }
+    }
+    /** Invalidate an old connection without restarting a lookup on every prompt. */
+    resetModelMetadataRequest() {
+        this.modelMetadataGeneration += 1;
+        this.modelMetadataAbort.abort();
+        this.modelMetadataAbort = new AbortController();
     }
     /**
      * Whether the STATIC table knows this model's price (C-11 / RV-4).
@@ -1676,7 +1801,7 @@ export class AgentController {
      * `/fast` reports that honestly by checking `isFastRegistered()` first.
      */
     setFastEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.fast?.setEnabled(enabled);
     }
     getFastConfig() {
@@ -1692,7 +1817,7 @@ export class AgentController {
      */
     setFastConfig(patch) {
         const fast = clampFastConfig({ ...this.config.fast, ...patch });
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, fast };
         // `onConfigChanged` rebuilds the prompt; when there is no wiring (the tier
         // was never registered) nothing has to be rebuilt, because no block is
@@ -1792,7 +1917,7 @@ export class AgentController {
      * on purpose (§3.2).
      */
     setCompactionEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.compaction?.setEnabled(enabled);
     }
     getCompactionConfig() {
@@ -1807,7 +1932,7 @@ export class AgentController {
      */
     setCompactionConfig(patch) {
         const compaction = clampCompactionConfig({ ...this.config.compaction, ...patch });
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, compaction };
         this.compaction?.onConfigChanged();
         return compaction;
@@ -1860,18 +1985,80 @@ export class AgentController {
             return { ok: false, reason: 'settings_restart_required' };
         if (!this.compaction)
             return { ok: false, reason: 'not_registered' };
+        if (this.isCompactionBusy() || this.isRunning())
+            return { ok: false, reason: 'busy' };
         const controller = new AbortController();
-        const outcome = await this.compaction.compactNow({
-            messages: this.agent.state.messages,
-            systemPrompt: this.agent.state.systemPrompt,
-            model: this.agent.state.model,
-            signal: controller.signal,
-            ...(instructions ? { instructions } : {}),
+        const epoch = this.startupSequence;
+        const settings = this.settingsRevision;
+        let adopted = false;
+        let timedOut = false;
+        const isCurrent = () => this.idleCompaction === controller && !controller.signal.aborted
+            && epoch === this.startupSequence && settings === this.settingsRevision
+            && !this.isRunning() && !this.disposed;
+        this.idleCompaction = controller;
+        this.publishCompactionBusy(true);
+        const deadline = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, COMPACTION_LIMITS.operationTimeoutMs);
+        deadline.unref?.();
+        try {
+            // The wiring races cancellation locally and settles before releasing ownership.
+            const outcome = await this.compaction.compactNow({
+                messages: this.agent.state.messages,
+                systemPrompt: this.agent.state.systemPrompt,
+                model: this.agent.state.model,
+                signal: controller.signal,
+                ...(instructions ? { instructions } : {}),
+                isCurrent,
+                adopt: (messages) => {
+                    if (!isCurrent())
+                        throw new Error('stale_history');
+                    this.agent.replaceMessages(messages);
+                    adopted = true;
+                },
+            });
+            return outcome.ok || adopted ? { ok: true }
+                : { ok: false, reason: timedOut ? 'timeout' : outcome.reason };
+        }
+        finally {
+            clearTimeout(deadline);
+            if (this.idleCompaction === controller) {
+                this.idleCompaction = undefined;
+                this.publishCompactionBusy(false);
+            }
+        }
+    }
+    /** Local prepare/adopt ownership, available before any network-start event. */
+    isCompactionBusy() { return this.idleCompaction !== undefined; }
+    /** Cancel local compaction and await ownership release before a conversation switch. */
+    cancelCompaction() {
+        if (!this.idleCompaction)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const unsubscribe = this.subscribeCompactionBusy((busy) => {
+                if (busy)
+                    return;
+                unsubscribe();
+                resolve();
+            });
+            this.abort();
         });
-        if (!outcome.ok)
-            return { ok: false, reason: outcome.reason };
-        this.agent.replaceMessages(outcome.messages);
-        return { ok: true };
+    }
+    /** Subscribe to synchronous ownership transitions; observers cannot break adoption. */
+    subscribeCompactionBusy(listener) {
+        this.compactionBusyListeners.add(listener);
+        return () => { this.compactionBusyListeners.delete(listener); };
+    }
+    publishCompactionBusy(busy) {
+        for (const listener of this.compactionBusyListeners) {
+            try {
+                listener(busy);
+            }
+            catch {
+                getLogger().debug('agent', 'compaction_busy_listener_threw');
+            }
+        }
     }
     /**
      * Subscribe to the CLI-local compaction event stream.