@aragon-agent/cli 0.6.14 → 0.6.16

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
@@ -14,6 +15,7 @@ import type { PromptOptions, PromptOutcome } from './prompt-options.js';
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import type { ModelRole } from '../config/model-profiles.js';
+import { ModelWindows } from '../config/model-windows.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
@@ -101,6 +103,13 @@ export interface ControllerDeps {
      * once at construction and lost at the first `rebuildSystemPrompt()`.
      */
     appendSystemPrompt?: string;
+    /**
+     * The per-model window table from ~/.aragon-agent/model-windows.json.
+     * Injectable so tests can hand the controller a table without writing into
+     * the shared vitest home root (app-paths.ts TEST-ISOLATION CONTRACT);
+     * production leaves it absent and the constructor builds the real one.
+     */
+    modelWindows?: ModelWindows;
 }
 /** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
 export interface AgentModeState {
@@ -123,6 +132,8 @@ export declare class AgentController {
     private readonly agent;
     private readonly providerRegistry;
     private readonly modelRegistry;
+    /** Per-model user-declared context windows; see `config/model-windows.ts`. */
+    private readonly modelWindows;
     private modelMetadataEnabled;
     private modelMetadataGeneration;
     private modelMetadataAbort;
@@ -188,6 +199,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;
@@ -291,6 +306,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;
@@ -379,6 +395,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;
     /**
@@ -538,6 +559,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. */
@@ -596,8 +618,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;
@@ -759,6 +788,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,10 +1,13 @@
 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';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
+import { ModelWindows } from '../config/model-windows.js';
 import { createBuiltinTools } from '../tools/index.js';
 import { createFileChangeStore } from '../tools/file-change-store.js';
 import { createToolOutputStore, } from '../tools/tool-output-store.js';
@@ -51,6 +54,8 @@ export class AgentController {
     agent;
     providerRegistry;
     modelRegistry;
+    /** Per-model user-declared context windows; see `config/model-windows.ts`. */
+    modelWindows;
     modelMetadataEnabled = false;
     modelMetadataGeneration = 0;
     modelMetadataAbort = new AbortController();
@@ -201,6 +206,10 @@ export class AgentController {
     // and a `Set`.
     // -----------------------------------------------------------------------
     settingsRevision = 0;
+    requestVersion = 0;
+    idleCompaction;
+    restoredCompactionIdentity;
+    compactionBusyListeners = new Set();
     modelSettingsBlocked = false;
     preparedSystemPrompt;
     contextMeter;
@@ -253,7 +262,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;
@@ -269,6 +278,7 @@ export class AgentController {
         // reuses this very registry instance.
         this.providerRegistry = initProviders({ retryPolicy: toRetryPolicy(config.retry) });
         this.modelRegistry = new ModelRegistry(this.providerRegistry);
+        this.modelWindows = deps.modelWindows ?? new ModelWindows();
         this.skillsEnabled = config.skills.enabled;
         this.onSkillsChanged = deps.onSkillsChanged;
         this.skills = new SkillService({
@@ -530,6 +540,7 @@ 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(),
@@ -768,7 +779,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() {
@@ -799,7 +813,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 };
     }
     /**
@@ -856,6 +870,8 @@ 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' };
@@ -873,6 +889,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) {
@@ -908,10 +926,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' };
         }
@@ -919,9 +934,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() {
@@ -1066,11 +1088,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);
         }
@@ -1084,6 +1106,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;
     }
@@ -1216,7 +1262,7 @@ export class AgentController {
      * honestly by checking `isTeamRegistered()` first.
      */
     setTeamEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.teamEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1230,7 +1276,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;
@@ -1256,6 +1302,7 @@ 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();
@@ -1295,7 +1342,7 @@ export class AgentController {
      * reports that honestly by checking `isTodoRegistered()` first.
      */
     setTodoEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.todoEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1318,7 +1365,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;
@@ -1374,7 +1421,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;
@@ -1384,11 +1431,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);
@@ -1414,10 +1466,13 @@ 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);
@@ -1429,7 +1484,12 @@ export class AgentController {
             }
             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 {
@@ -1451,9 +1511,11 @@ export class AgentController {
     setModel(provider, model, baseUrl) {
         if (this.isModelSettingsBusy())
             throw new Error('Model settings are busy.');
+        const connectionChanged = this.config.provider !== provider || this.config.model !== model
+            || this.config.baseUrl !== baseUrl;
         if (this.modelMetadataEnabled)
             this.resetModelMetadataRequest();
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.config = { ...this.config, provider, model, baseUrl };
         this.config.modelProfileState = resolveModelProfileState(this.config);
         this.agent.setModel({ providerId: provider, modelId: model, ...(baseUrl ? { baseUrl } : {}) });
@@ -1468,30 +1530,29 @@ 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 },
@@ -1512,7 +1573,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
@@ -1581,6 +1642,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
@@ -1608,7 +1671,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.
@@ -1621,12 +1686,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();
@@ -1662,9 +1741,18 @@ export class AgentController {
         const found = this.modelRegistry.getModel(ref.providerId, ref.modelId);
         const baseUrl = ref.baseUrl ?? (ref.providerId === this.config.provider && ref.modelId === this.config.model
             ? this.config.baseUrl : undefined);
+        const userWindow = this.modelWindows.lookup(ref.modelId);
         return {
             ...(found ?? this.modelRegistry.buildRuntimeModel(ref.providerId, ref.modelId)),
             ...this.modelRegistry.getContextWindow(ref.providerId, ref.modelId, baseUrl),
+            // A USER-DECLARED WINDOW OUTRANKS EVERY TABLE (model-windows.json): the
+            // user asserted the number for exactly this id, while api/catalog are
+            // what this process managed to look up about it. It still LOSES to
+            // config.json's `contextWindow`, which `ContextMeter.resolveWindow`
+            // consults before it ever reaches here.
+            ...(userWindow !== undefined
+                ? { contextWindow: userWindow, contextWindowSource: 'user' }
+                : {}),
         };
     }
     /** Best-effort metadata lookup; never block typing or a model request. */
@@ -1726,7 +1814,7 @@ export class AgentController {
      * `/fast` reports that honestly by checking `isFastRegistered()` first.
      */
     setFastEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.fast?.setEnabled(enabled);
     }
     getFastConfig() {
@@ -1742,7 +1830,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
@@ -1842,7 +1930,7 @@ export class AgentController {
      * on purpose (§3.2).
      */
     setCompactionEnabled(enabled) {
-        this.settingsRevision += 1;
+        this.advanceSettingsRevision();
         this.compaction?.setEnabled(enabled);
     }
     getCompactionConfig() {
@@ -1857,7 +1945,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;
@@ -1910,18 +1998,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.

package/dist/agent/plan-prompt.d.ts

@@ -8,7 +8,7 @@
  * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
  */
 /** Bump when the wording changes, so a transcript can be dated. */
-export declare const PLAN_MODE_BLOCK_VERSION = "v1-2026-07";
+export declare const PLAN_MODE_BLOCK_VERSION = "v2-2026-10-08";
 export interface PlanModeBlockOptions {
     /** False under `-p` / piped stdin: no overlay can be rendered, so no tools. */
     interactive: boolean;

package/dist/agent/plan-prompt.js

@@ -8,7 +8,7 @@
  * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
  */
 /** Bump when the wording changes, so a transcript can be dated. */
-export const PLAN_MODE_BLOCK_VERSION = 'v1-2026-07';
+export const PLAN_MODE_BLOCK_VERSION = 'v2-2026-10-08';
 /**
  * The closing paragraph of the interactive block.
  *
@@ -75,8 +75,9 @@ export function buildPlanModeBlock(options) {
         'design mode: you must not change anything on disk and must not run commands.',
         '',
         'Work in this order:',
-        '1. Ground yourself in the real code. Use read_file, list_dir, glob, grep and any',
-        '   relevant skill. Never plan against a directory structure you have not read.',
+        '1. Follow the project-guidance protocol: read applicable guidance and index navigation',
+        '   before any source search or read. Then inspect the real code with read_file,',
+        '   list_dir, glob, grep and relevant skills. Never plan against unread structure.',
         ...askStep,
         ...submitStep,
         '',

package/dist/agent/project-guidance-prompt.d.ts

@@ -0,0 +1,4 @@
+/** Shared workspace-orientation protocol; no local content is injected. */
+export declare const PROJECT_GUIDANCE_BLOCK_VERSION = "v5-2026-10-08";
+/** Return the versioned English protocol without performing discovery or IO. */
+export declare function buildProjectGuidanceBlock(): string;