@lucascouts/claude-agent-acp-plus 0.12.0 → 0.14.0

package/dist/acp-agent.js

@@ -14,6 +14,7 @@ import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createEli
 import { agentName } from "./agent-name.js";
 import { filterDeprecatedModels } from "./model-deprecation.js";
 import { SettingsManager } from "./settings.js";
+import { ContextCompactionLifecycle, contextCompactionMetadataFromBoundary, } from "./context-compaction.js";
 import { createThinkingConfigOption, effectiveThinkingConfig, resolveThinkingSelection, THINKING_CONFIG_ID, } from "./thinking-option.js";
 import { effortOptionValue, isUltracodeAvailable, isUltracodeValue, ULTRACODE_OPTION_NAME, ULTRACODE_OPTION_VALUE, ultracodeFlagSettings, } from "./ultracode.js";
 import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
@@ -30,6 +31,8 @@ import { acceptedPlanToolResult, ExitPlanCoordinator, executionDiagnostic, exitP
 import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { AccountUsageTracker } from "./account-usage.js";
+import { ACCOUNT_CONFIG_ID, accountForValue, accountInForce, createAccountConfigOption, envForAccount, readDeclaredAccounts, } from "./accounts.js";
+import { isUsageCommandText, structuredUsageMarkdown } from "./usage-markdown.js";
 export { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
 import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
@@ -112,6 +115,37 @@ function parseSteerRequest(params) {
         _meta: _meta,
     };
 }
+/** How often the account quota windows are refreshed while a session sits idle,
+ *  in milliseconds; `0` disables polling entirely.
+ *
+ *  Without this the windows move at only three moments: session establishment,
+ *  the end of every turn, and a pushed `rate_limit_event`. None of them is time
+ *  — so a five-hour window that resets while nobody is prompting keeps showing
+ *  the old utilization, and the bar is wrong in the one direction that matters
+ *  (it under-reports how much is available) until the next turn ends.
+ *
+ *  The floor is not timidity: each tick costs one control request, and neither
+ *  the five-hour nor the seven-day window can move fast enough for a tighter
+ *  loop to show anything a 15-second one would miss. */
+const QUOTA_POLL_DEFAULT_MS = 60_000;
+const QUOTA_POLL_FLOOR_MS = 15_000;
+/** Resolve the poll interval from the environment, clamped. An unparseable or
+ *  negative value falls back to the default rather than disabling the refresh:
+ *  a typo should not silently return the bars to the stale behaviour this
+ *  exists to fix. Exactly `0` disables, because that is the only way to ask. */
+export function quotaPollIntervalMs(raw = process.env.CLAUDE_ACP_QUOTA_POLL_MS) {
+    if (raw === undefined || raw.trim() === "") {
+        return QUOTA_POLL_DEFAULT_MS;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return QUOTA_POLL_DEFAULT_MS;
+    }
+    if (parsed === 0) {
+        return 0;
+    }
+    return Math.max(parsed, QUOTA_POLL_FLOOR_MS);
+}
 /** Result-message origin kinds that mark an AUTONOMOUS cycle — work the
  *  model did on its own (a task-notification followup, a peer/coordinator/
  *  observer message it handled) rather than the user's prompt. Absent,
@@ -481,6 +515,14 @@ export class ClaudeAcpAgent {
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
     forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
+    /** The account selector's last choice, as a selector value (see
+     *  `accounts.ts`). Held on the AGENT, not on a session, because that is what
+     *  it governs: the account applies to sessions created after it is set, and
+     *  the thread that was on screen when the user chose keeps the account it
+     *  started under (D7 — a session id belongs to one account's local history,
+     *  so a live thread cannot be carried across a switch). `undefined` until a
+     *  selection is made, in which case the first declared account stands. */
+    selectedAccount;
     constructor(client, logger) {
         this.sessions = {};
         this.client = client;
@@ -1007,6 +1049,12 @@ export class ClaudeAcpAgent {
             session.fileChangeReportRequestIds.add(fileChangeReportRequestId);
             fileChangeAudit = createFileChangeAuditTurnState(fileChangeReportRequestId);
         }
+        // R2.3: exactly `/usage`, and nothing else in the prompt. A second block
+        // (an attached file, a second text part) is a model turn that happens to
+        // mention the command, not the local command itself.
+        const isUsageCommand = params.prompt.length === 1 &&
+            params.prompt[0]?.type === "text" &&
+            isUsageCommandText(params.prompt[0].text);
         session.titles.onPrompt(params.prompt);
         // Each prompt is a Turn whose deferred the persistent consumer settles once
         // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
@@ -1015,6 +1063,9 @@ export class ClaudeAcpAgent {
         const turn = {
             promptUuid,
             isLocalOnlyCommand,
+            ...(isUsageCommand
+                ? { isUsageCommand: true, usageMarkdownAbort: new AbortController() }
+                : {}),
             ...(fileChangeAudit ? { fileChangeAudit } : {}),
             settled: false,
             resolve: () => { },
@@ -1105,7 +1156,14 @@ export class ClaudeAcpAgent {
             // answers to, and it is written out here rather than hidden behind a
             // helper so a rename lands as one named failure in the log below, not as
             // a quiet degradation to no report at all.
-            const report = await session.query.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET();
+            // `skipBehaviors` drops the local-transcript scan that fills the report's
+            // `behaviors` section. Nothing here reads it — `windowsFrom` touches only
+            // `rate_limits_available` and `rate_limits` — so on every call, not just
+            // the polled ones, that scan was pure cost. `/usage` still asks for the
+            // full report, because it renders those contributions.
+            const report = await session.query.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({
+                skipBehaviors: true,
+            });
             // The session can be torn down or recreated while the request is in
             // flight (provider switch, a changed cwd on session/load). A successor
             // must not inherit its predecessor's windows.
@@ -1142,6 +1200,50 @@ export class ClaudeAcpAgent {
             this.logger.error(`Session ${sessionId}: structured usage report unavailable: ${error}`);
         }
     }
+    /** Start the idle refresh of the account quota windows for this session.
+     *
+     *  Idempotent, and deliberately called at the end of every turn rather than
+     *  once: the first call arms, the rest return immediately, so no caller has to
+     *  know whether this is turn one.
+     *
+     *  The tick does nothing while a turn is in flight. That turn's own end
+     *  already refreshes the windows, and a second control request would buy the
+     *  same answer twice — the same reasoning that excludes autonomous cycles at
+     *  the end-of-turn call site. */
+    armAccountUsagePolling(sessionId, session) {
+        if (session.accountUsageTimer) {
+            return;
+        }
+        const intervalMs = quotaPollIntervalMs();
+        if (intervalMs === 0) {
+            return;
+        }
+        // Closure-local rather than a Session field: it guards this timer alone, and
+        // a slow report must not let ticks pile up into a queue of duplicate control
+        // requests against a session that is already struggling to answer one.
+        let inFlight = false;
+        const timer = setInterval(() => {
+            // Re-resolve through the map. A provider update replaces the Session
+            // object under the same id and the replacement arms its own timer, so an
+            // orphaned closure must retire rather than keep polling a husk.
+            if (this.sessions[sessionId] !== session || session.queryClosed) {
+                clearInterval(timer);
+                return;
+            }
+            if (session.turnQueue?.length || session.activeTurn || inFlight) {
+                return;
+            }
+            inFlight = true;
+            // `publishAccountUsage` never rejects — it logs and returns — so this
+            // cannot become an unhandled rejection, and `finally` always re-opens.
+            void this.publishAccountUsage(sessionId, session).finally(() => {
+                inFlight = false;
+            });
+        }, intervalMs);
+        // A quota refresh is never a reason to keep the process alive.
+        timer.unref?.();
+        session.accountUsageTimer = timer;
+    }
     async publishGoalFromPrompt(sessionId, prompt, commandUuid) {
         const goalUpdate = goalUpdateFromPrompt(prompt);
         if (goalUpdate !== undefined) {
@@ -1310,11 +1412,6 @@ export class ClaudeAcpAgent {
         // stop_reason "refusal" and structured stop_details. We capture the
         // human-readable explanation so the terminal `result` can surface it.
         let lastRefusalExplanation = null;
-        // Tracks whether we're inside a compaction. The SDK emits the terminal
-        // `status` (compact_result success/failed) twice for a single failed
-        // compaction, and the two messages are indistinguishable — so we report the
-        // outcome only while a compaction is in progress, then clear this.
-        let compactionInProgress = false;
         // Anthropic API message id of the assistant message currently being
         // streamed, captured from `message_start` so the streamed chunks that follow
         // (whose delta events don't carry it) can all be tagged with the same,
@@ -1349,6 +1446,12 @@ export class ClaudeAcpAgent {
          *  recognizable by the `parentToolUseId` meta that toAcpNotifications
          *  stamps from `parent_tool_use_id`, and never reach the top-level feed
          *  as the turn's answer. */
+        /** Compaction as one ACP tool lifecycle, replacing the in-progress boolean
+         *  this consumer used to infer it from (story 010, R2.1/R2.2). Declared
+         *  ahead of `sendUpdate` because that chokepoint consults it; the closure
+         *  below only dereferences `sendUpdate` when an update is actually sent,
+         *  which is always after both bindings exist. */
+        const compaction = new ContextCompactionLifecycle((notification) => sendUpdate(notification));
         const sendUpdate = async (notification) => {
             const { update } = notification;
             if (isFileChangeAuditReportPhase(session.activeTurn?.fileChangeAudit) &&
@@ -1361,6 +1464,14 @@ export class ClaudeAcpAgent {
             }
             if (update.sessionUpdate === "agent_message_chunk") {
                 const claudeMeta = update._meta?.claudeCode;
+                // A failed manual compaction's error also arrives as assistant text;
+                // the tool lifecycle already carried it, so drop that one copy rather
+                // than report the same failure twice (R2.2).
+                if (!claudeMeta?.parentToolUseId &&
+                    update.content.type === "text" &&
+                    compaction.consumeDuplicateErrorOutput(update.content.text)) {
+                    return;
+                }
                 if (!claudeMeta?.parentToolUseId) {
                     session.emittedAssistantText = true;
                     session.titles.onAssistantText(update.content);
@@ -1413,7 +1524,6 @@ export class ClaudeAcpAgent {
             lastAssistantWasUsageLimit = false;
             lastAssistantFailureTitle = undefined;
             lastRefusalExplanation = null;
-            compactionInProgress = false;
             // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
             // activation can fire mid-message (the replayed user echo with
             // --replay-user-messages lands between a message's blocks); clearing the
@@ -1432,6 +1542,22 @@ export class ClaudeAcpAgent {
             if (session.activeTurn)
                 session.activeTurn.carriedUsage = undefined;
         };
+        /** Start this turn's structured `/usage` render, once, and hand back the
+         *  in-flight promise; undefined when the turn owns no render.
+         *
+         *  Started at ACTIVATION rather than when the output arrives, so the
+         *  bounded wait overlaps the command instead of following it: by the time
+         *  the CLI has printed its answer the report has usually already lost or
+         *  won its race, and the user waits for neither. */
+        const ensureUsageMarkdown = (turn) => {
+            if (!turn.isUsageCommand || !turn.usageMarkdownAbort) {
+                return undefined;
+            }
+            // `session.query` is read here rather than captured: a provider switch
+            // can replace it, and the render must ask the query that is live now.
+            turn.usageMarkdown ??= structuredUsageMarkdown(session.query, turn.usageMarkdownAbort.signal, this.logger);
+            return turn.usageMarkdown;
+        };
         /** Promote a queued turn to active: it becomes the one output is attributed
          *  to, and its scratch starts fresh. Clears the cancelled flag so a turn
          *  enqueued after a prior cancel isn't treated as cancelled. Also clears any
@@ -1443,6 +1569,7 @@ export class ClaudeAcpAgent {
         const activateTurn = (turn) => {
             session.activeTurn = turn;
             session.cancelled = false;
+            ensureUsageMarkdown(turn);
             session.pendingOrphanResults = 0;
             session.orphanCommands?.clear();
             // Two-phase sweep of registry entries the level signal ended (see
@@ -1481,12 +1608,20 @@ export class ClaudeAcpAgent {
          *
          *  But an echo-less result can also be an ORPHAN: cancel() settles+removes a
          *  queued turn whose user message was already pushed, so the SDK still runs
-         *  it and emits a result with no uuid to match. Promoting the head for an
+         *  it and emits a result with no echo to match. Promoting the head for an
          *  orphan would misattribute its stop reason/usage to an unrelated later
          *  prompt. `session.pendingOrphanResults` counts exactly how many such
          *  orphans are still expected (FIFO, they arrive before any live turn's
-         *  result), so we skip those and only promote once the count is drained. */
-        const ensureActiveTurn = () => {
+         *  result), so we skip those and only promote once the count is drained.
+         *
+         *  `resultUserMessageUuid` is the result's own join key (SDK 0.3.246+
+         *  echoes the triggering send's client uuid on results; absent on older
+         *  CLIs, synthetic/meta turns, and session-scoped failures). When present
+         *  it upgrades the map lane from positional heuristics to an exact match:
+         *  a stamp naming an orphaned command consumes the result outright, and a
+         *  stamp naming anything else positively refutes "this is a dead turn's
+         *  result", so the dup-over-loss one-skip must not eat it. */
+        const ensureActiveTurn = (resultUserMessageUuid) => {
             if (session.activeTurn) {
                 if (!isHeldOpen(session.activeTurn)) {
                     return;
@@ -1538,8 +1673,19 @@ export class ClaudeAcpAgent {
             // double-consume it. The unexpected-transition logging in the frame
             // handler is the tripwire for that class of drift.
             if (session.orphanCommands?.size) {
+                // Resolved BEFORE the drain below, which deletes every started/zombie
+                // entry: a stamp naming a "started" orphan would no longer be found
+                // afterwards, and the result would promote the head — misattributing
+                // a dead turn's outcome to a live prompt, the exact failure the map
+                // exists to prevent. The lookup order is load-bearing.
+                const stampedOrphanUuid = resultUserMessageUuid !== undefined && session.orphanCommands.has(resultUserMessageUuid)
+                    ? resultUserMessageUuid
+                    : undefined;
                 let consumedOrphanResult = false;
                 let oldestPending;
+                // The started/zombie drain applies regardless of the stamp: commands
+                // folded into the turn that emitted this result share it, and zombies'
+                // late results have already passed (or never existed).
                 for (const [uuid, state] of session.orphanCommands) {
                     if (state === "started" || state === "zombie") {
                         consumedOrphanResult = true;
@@ -1549,17 +1695,33 @@ export class ClaudeAcpAgent {
                         oldestPending ??= uuid;
                     }
                 }
-                if (consumedOrphanResult) {
+                if (stampedOrphanUuid !== undefined) {
+                    // Exact join: the result names an orphaned command. Delete the
+                    // matched entry even when it is still "pending" (its dispatch frame
+                    // was lost) and consume the result — no promotion.
+                    session.orphanCommands.delete(stampedOrphanUuid);
                     return;
                 }
-                if (oldestPending !== undefined) {
-                    // No dispatch was seen before this result, so it is very likely a
-                    // live turn's — but a lost "started" frame would mean it IS the
-                    // orphan's (dup-over-loss: prefer one wrong skip over
-                    // misattributing a dead turn's outcome to a live prompt). Grant
-                    // each pending entry exactly one skip, like the count lane did.
-                    session.orphanCommands.delete(oldestPending);
-                    return;
+                if (resultUserMessageUuid !== undefined) {
+                    // The stamp names a send that is NOT in the orphan map, so this is
+                    // a live turn's result: skip both the consumed-return (its folded
+                    // orphans were drained above, but the result itself still needs a
+                    // turn) and the dup-over-loss one-skip the stamp refutes, and fall
+                    // through to promote the head.
+                }
+                else {
+                    if (consumedOrphanResult) {
+                        return;
+                    }
+                    if (oldestPending !== undefined) {
+                        // No dispatch was seen before this result, so it is very likely a
+                        // live turn's — but a lost "started" frame would mean it IS the
+                        // orphan's (dup-over-loss: prefer one wrong skip over
+                        // misattributing a dead turn's outcome to a live prompt). Grant
+                        // each pending entry exactly one skip, like the count lane did.
+                        session.orphanCommands.delete(oldestPending);
+                        return;
+                    }
                 }
             }
             const head = firstUnsettledQueuedTurn();
@@ -1600,6 +1762,49 @@ export class ClaudeAcpAgent {
          *  spelling of "a prompt is pending" shared by the head promotion and
          *  the autonomous stretch-close guard. */
         const firstUnsettledQueuedTurn = () => (session.turnQueue ?? []).find((t) => !t.settled);
+        /** Claim the structured render for whichever turn is producing this local
+         *  command output. Three answers, and the caller must distinguish all
+         *  three:
+         *
+         *    undefined — not a `/usage` turn, or one of R2.4's three ways out
+         *                fired: publish `originalOutput` unchanged
+         *    string    — the render: publish it INSTEAD of `originalOutput`
+         *    null      — publish nothing (a duplicate of an already-replaced
+         *                frame, or a turn cancelled during the wait)
+         *
+         *  No content signature and no text parsing: which turn owns a render was
+         *  decided from the prompt, so a command whose output happens to look like
+         *  `/usage`'s can never be rewritten. */
+        const takeUsageMarkdown = async (originalOutput) => {
+            const turn = session.activeTurn ?? firstUnsettledQueuedTurn();
+            if (!turn) {
+                return undefined;
+            }
+            const pending = ensureUsageMarkdown(turn);
+            if (!pending) {
+                return undefined;
+            }
+            const markdown = await pending;
+            // That await can span the whole bounded wait, and a cancel landing inside
+            // it ends the turn. A cancelled turn publishes nothing — not the render,
+            // and not the original text either.
+            if (session.cancelled) {
+                return null;
+            }
+            if (markdown === null) {
+                return undefined;
+            }
+            if (turn.usageMarkdownDelivered) {
+                // One local command can reach the client through more than one SDK
+                // message shape. Suppress an exact mirror of the frame already
+                // replaced, but let a later, genuinely different frame (an
+                // interruption diagnostic, say) take the normal path.
+                return turn.usageOriginalOutput === originalOutput ? null : undefined;
+            }
+            turn.usageMarkdownDelivered = true;
+            turn.usageOriginalOutput = originalOutput;
+            return markdown;
+        };
         /** Whether any background subagent this turn spawned is still live —
          *  while true, the turn's settlement stays deferred so the subagent's
          *  output and permission requests land inside it (see
@@ -1668,6 +1873,9 @@ export class ClaudeAcpAgent {
             // Captured before the settled flip below (isHeldOpen tests !settled).
             const wasHeld = isHeldOpen(turn);
             turn.settled = true;
+            // The turn is over: abandon any structured `/usage` render still in
+            // flight rather than leaving it to run out its own clock (D5).
+            turn.usageMarkdownAbort?.abort();
             disarmForceCancel(session);
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
@@ -1700,6 +1908,7 @@ export class ClaudeAcpAgent {
             }
             this.finishFileChangeAudit(session, turn, "providerError");
             turn.settled = true;
+            turn.usageMarkdownAbort?.abort();
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
             streamedToolInputs.clear();
@@ -1748,6 +1957,7 @@ export class ClaudeAcpAgent {
                     this.finishFileChangeAudit(session, turn, "providerError");
                     const wasHeld = isHeldOpen(turn);
                     turn.settled = true;
+                    turn.usageMarkdownAbort?.abort();
                     if (wasHeld) {
                         // A held turn's answer already streamed and its outcome is
                         // recorded — a stream death during the post-answer hold is a
@@ -2073,50 +2283,43 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             case "status": {
-                                // These banners count as delivered text (via sendUpdate), so
-                                // an echo-less turn that only ever emits them (e.g. `/compact`,
-                                // promoted at its own result) doesn't have its result text
-                                // re-emitted by the issue-#453 fallback.
+                                // Compaction is reported as ONE tool lifecycle rather than the
+                                // assistant-text banners this branch used to emit (R2.1). The
+                                // banners needed a boolean in-progress guard because the SDK
+                                // repeats the terminal `status` and the two copies are
+                                // indistinguishable here; the lifecycle owns that de-duplication
+                                // by phase instead, so the guard is gone rather than inert (R2.2).
+                                //
+                                // The SDK signals manual `/compact` completion with a status
+                                // message carrying `compact_result`, not the `compact_boundary`
+                                // message (which only fires when there's content to compact) —
+                                // so both frames must be able to close a lifecycle.
                                 if (message.status === "compacting") {
-                                    compactionInProgress = true;
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: "Compacting..." },
-                                        },
-                                    });
+                                    await compaction.start(message.session_id, message.uuid);
                                 }
-                                else if (message.compact_result === "success" && compactionInProgress) {
-                                    // The SDK signals manual `/compact` completion with a status
-                                    // message carrying `compact_result`, not the `compact_boundary`
-                                    // message (which only fires when there's content to compact).
-                                    compactionInProgress = false;
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: "\n\nCompacting completed." },
-                                        },
-                                    });
+                                else if (message.compact_result === "success") {
+                                    await compaction.finish(message.session_id, message.uuid, "completed");
                                 }
-                                else if (message.compact_result === "failed" && compactionInProgress) {
-                                    compactionInProgress = false;
-                                    const reason = message.compact_error ? `: ${message.compact_error}` : ".";
-                                    await sendUpdate({
-                                        sessionId: message.session_id,
-                                        update: {
-                                            sessionUpdate: "agent_message_chunk",
-                                            content: { type: "text", text: `\n\nCompacting failed${reason}` },
-                                        },
+                                else if (message.compact_result === "failed") {
+                                    await compaction.finish(message.session_id, message.uuid, "failed", {
+                                        ...(message.compact_error ? { error: message.compact_error } : {}),
                                     });
                                 }
                                 break;
                             }
                             case "compact_boundary": {
+                                // This is the only frame carrying the token counts, and it
+                                // arrives AFTER the terminal `status` — so it enriches the
+                                // lifecycle rather than reporting an outcome again
+                                // (`enrichTerminal`): the update omits `status`, leaving exactly
+                                // one terminal transition the client can see (R2.2). It also
+                                // stands alone when no `status` preceded it (an automatic
+                                // compaction, or a replay that dropped the opening frame).
+                                const compactMetadata = message.compact_metadata;
+                                await compaction.finish(message.session_id, message.uuid, "completed", compactMetadata ? contextCompactionMetadataFromBoundary(compactMetadata) : {}, true);
                                 // Refresh the displayed usage immediately so the client doesn't
                                 // keep showing the stale pre-compaction size (e.g. "944k/1m")
-                                // right after the user sees "Compacting completed", which is
+                                // right after the compaction tool call completes, which is
                                 // confusing and wrong.
                                 //
                                 // Prefer the SDK's authoritative post-compaction `used` via
@@ -2131,10 +2334,6 @@ export class ClaudeAcpAgent {
                                 // `size` keeps coming from session.contextWindowSize —
                                 // compaction frees occupancy, it doesn't change the model's
                                 // window.
-                                //
-                                // The "Compacting completed." text is emitted from the `status`
-                                // handler (keyed on `compact_result`), not here, so the failure
-                                // path gets a message too.
                                 const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
                                 lastAssistantTotalUsage = usedTokens ?? 0;
@@ -2150,11 +2349,24 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "local_command_output": {
+                                // A failed `/compact` also prints its error here; the tool
+                                // lifecycle already carried it, so consume that one duplicate
+                                // (matched by text, once) without hiding other command output.
+                                if (compaction.consumeDuplicateErrorOutput(message.content)) {
+                                    break;
+                                }
+                                // R2.3/R2.4: a `/usage` turn publishes its structured render
+                                // here instead; anything else, and any way out, publishes the
+                                // CLI's own text byte-for-byte.
+                                const usageMarkdown = await takeUsageMarkdown(message.content);
+                                if (usageMarkdown === null) {
+                                    break;
+                                }
                                 await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
-                                        content: { type: "text", text: message.content },
+                                        content: { type: "text", text: usageMarkdown ?? message.content },
                                     },
                                 });
                                 break;
@@ -2192,6 +2404,10 @@ export class ClaudeAcpAgent {
                                     // the interrupted turn's tokens entirely (issue #844). Zero
                                     // when the cancel pre-empted the result (wedge/force-cancel).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
+                                        // An interrupt can pre-empt the result entirely, so the
+                                        // lifecycle's own reset there never ran; close it here or a
+                                        // half-open compaction would leak into the next turn.
+                                        compaction.reset();
                                         settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
                                         // An interrupt can pre-empt the turn's result entirely
                                         // (nothing ran the result-case `finally`), so close the
@@ -2254,6 +2470,9 @@ export class ClaudeAcpAgent {
                                     else if (!session.cancelled &&
                                         session.activeTurn &&
                                         !session.activeTurn.settled) {
+                                        // Same reason as the cancelled branch: this turn will never
+                                        // reach the result that would have reset the lifecycle.
+                                        compaction.reset();
                                         // Deliberately only the ACTIVE turn: a queued turn that
                                         // was never echoed is NOT failed here, because an idle
                                         // can legitimately precede the SDK picking up freshly
@@ -2669,7 +2888,7 @@ export class ClaudeAcpAgent {
                             // the map in that case).
                             if (!isAutonomousResult) {
                                 recordResultForOrphanCommands();
-                                ensureActiveTurn();
+                                ensureActiveTurn(message.user_message_uuid);
                                 // Once the submitted goal command has produced its own result,
                                 // no older runtime update can still precede it in the ordered
                                 // SDK stream. Stop suppressing updates even when this runtime
@@ -2700,6 +2919,12 @@ export class ClaudeAcpAgent {
                             // through the early break below, which the gated `finally`
                             // leaves alone).
                             const deliveredAssistantText = session.emittedAssistantText;
+                            // The deleted "Compacting…" banners counted as delivered text
+                            // simply by going through sendUpdate; tool calls don't, so a turn
+                            // that ONLY compacted (e.g. `/compact`, promoted at its own
+                            // result) needs this to keep its result text from being re-emitted
+                            // by the issue-#453 fallback below.
+                            const deliveredCompactionOutput = compaction.hasDeliveredOutput;
                             // Every user-turn result terminates a turn (settle, reject, or
                             // orphan skip) and the SDK follows it with a trailing
                             // `session_state_changed: idle` — record the debt so the idle
@@ -2946,9 +3171,19 @@ export class ClaudeAcpAgent {
                                     // the fallback there. (Autonomous results never get here —
                                     // they exit at the early break above — so no background
                                     // prose can be injected into the feed.)
-                                    if (session.activeTurn?.isLocalOnlyCommand ||
-                                        (!deliveredAssistantText && (message.usage.output_tokens ?? 0) === 0)) {
-                                        for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
+                                    const shouldForwardResult = session.activeTurn?.isLocalOnlyCommand ||
+                                        (!deliveredAssistantText &&
+                                            !deliveredCompactionOutput &&
+                                            (message.usage.output_tokens ?? 0) === 0);
+                                    if (shouldForwardResult) {
+                                        // A `/usage` turn whose output arrives only on the result.
+                                        // Claiming it here also stops the raw text following a
+                                        // render already published from another message shape.
+                                        const usageMarkdown = await takeUsageMarkdown(message.result);
+                                        if (usageMarkdown === null) {
+                                            break;
+                                        }
+                                        for (const notification of toAcpNotifications(usageMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
                                             await sendUpdate(notification);
                                         }
                                     }
@@ -3023,6 +3258,11 @@ export class ClaudeAcpAgent {
                         finally {
                             if (!isAutonomousResult) {
                                 session.emittedAssistantText = false;
+                                // A result closes this turn's compaction lifecycle. Reset here
+                                // rather than at idle: an owed idle from this turn can arrive
+                                // after the next turn has already started, and would erase that
+                                // turn's compaction state instead of its own.
+                                compaction.reset();
                                 // R1.2: a user turn's terminal result is the moment consumption
                                 // actually changed, so refresh the account quota windows here —
                                 // in the `finally`, which is the one point EVERY exit from this
@@ -3038,11 +3278,26 @@ export class ClaudeAcpAgent {
                                 // the trailing idle is, and a stalled control request there is
                                 // the same exposure `fetchContextUsedTokens` already accepts.
                                 await this.publishAccountUsage(params.sessionId, session);
+                                // A settled turn is the proof that control requests are being
+                                // serviced (before the first one they are not — #886/#880), so
+                                // this is the earliest honest moment to start the idle refresh.
+                                this.armAccountUsagePolling(params.sessionId, session);
                             }
                         }
                         break;
                     }
                     case "stream_event": {
+                        // Compaction streams as its own block type. The deltas carry the
+                        // generated summary, which stays internal to the agent — all the
+                        // client gets is one keep-alive on the open tool call, so a long
+                        // compaction doesn't look stalled.
+                        const isCompactionProgress = (message.event.type === "content_block_start" &&
+                            message.event.content_block.type === "compaction") ||
+                            (message.event.type === "content_block_delta" &&
+                                message.event.delta.type === "compaction_delta");
+                        if (isCompactionProgress) {
+                            await compaction.heartbeat(message.session_id, message.uuid);
+                        }
                         // `message_start` carries the Anthropic API message id; capture it
                         // so the streamed chunks that follow (whose delta events don't carry
                         // it) can all be tagged with the same, replay-stable id.
@@ -3265,6 +3520,18 @@ export class ClaudeAcpAgent {
                         if (session.cancelled) {
                             break;
                         }
+                        // Synthetic assistant frames carry the CLI's local-command output.
+                        // On resume the SDK can replay a stale frame from an earlier compact
+                        // attempt after a later compaction completed. Scope the suppression
+                        // to the compaction lifecycle and the synthetic frame itself rather
+                        // than to the owning turn: one model turn may compact more than
+                        // once, and its real assistant response must still be delivered.
+                        if (message.type === "assistant" &&
+                            message.parent_tool_use_id === null &&
+                            message.message.model === "<synthetic>" &&
+                            compaction.hasDeliveredOutput) {
+                            break;
+                        }
                         // Snapshot the latest top-level assistant usage and model so the
                         // next `result` can emit a usage_update tied to the right context
                         // window. Subagent messages are excluded to keep the snapshot
@@ -3303,7 +3570,13 @@ export class ClaudeAcpAgent {
                             message.message.content.includes("<local-command-stdout>")) {
                             const stripped = stripLocalCommandMetadata(message.message.content);
                             if (typeof stripped === "string") {
-                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
+                                // The usual shape for a real `/usage`: the comment above names
+                                // it as one of the commands the CLI wraps in these markers.
+                                const usageMarkdown = await takeUsageMarkdown(stripped);
+                                if (usageMarkdown === null) {
+                                    break;
+                                }
+                                for (const notification of toAcpNotifications(usageMarkdown ?? stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
@@ -3644,6 +3917,11 @@ export class ClaudeAcpAgent {
             await session.queryRecreateInFlight;
         }
         session.cancelled = true;
+        // Every turn's structured `/usage` render is abandoned here — the queue
+        // still holds the active turn at this point, so one sweep covers both.
+        for (const turn of session.turnQueue ?? []) {
+            turn.usageMarkdownAbort?.abort();
+        }
         session.pendingExitPlanModeInterruption = undefined;
         session.pendingExitPlanContextReset = undefined;
         // The stream already ended (see closeQueryStream): every in-flight turn was
@@ -3686,8 +3964,10 @@ export class ClaudeAcpAgent {
             }
             // Each removed queued turn's user message was already pushed to the SDK,
             // which processes input FIFO and will still emit a result for it with no
-            // uuid to match. Track those so the consumer skips them (see
-            // ensureActiveTurn) rather than misattributing them to the head.
+            // user echo to match (0.3.246+ CLIs do stamp results with the
+            // triggering send's user_message_uuid, which ensureActiveTurn uses as
+            // an exact join when present). Track those so the consumer skips them
+            // (see ensureActiveTurn) rather than misattributing them to the head.
             // msg_lifecycle_v1 CLIs get per-uuid tracking drained by the command's
             // own terminal lifecycle frame — exact under command coalescing, where
             // N queued commands fold into ONE turn emitting one result and a plain
@@ -3874,6 +4154,15 @@ export class ClaudeAcpAgent {
         }
         session.queryClosed = true;
         session.consumer = undefined;
+        // Every teardown path reaches this method, which is why the quota timer is
+        // cleared here and nowhere else: a `clearInterval` repeated at each of the
+        // four call sites is one merge away from missing the fifth. A session whose
+        // stream is closed cannot answer the usage control request anyway, so a
+        // surviving timer would only log a failure a minute, forever.
+        if (session.accountUsageTimer) {
+            clearInterval(session.accountUsageTimer);
+            session.accountUsageTimer = undefined;
+        }
         session.settingsManager.dispose();
         session.input.end();
         session.query.close();
@@ -4619,6 +4908,14 @@ export class ClaudeAcpAgent {
                 // same way it does for any unsupported level.
                 available: isUltracodeAvailable(newModelInfo?.supportsEffort ? (newModelInfo.supportedEffortLevels ?? []) : [], { disableWorkflows: session.workflowsDisabled }),
                 enabled: session.ultracode,
+            }, {
+                disableWorkflows: session.workflowsDisabled,
+                // Threaded for the same reason Thinking is (R1.7): an option not
+                // passed through this rebuild silently drops from the picker on
+                // every model switch. The account is model-independent, so the row
+                // and its selection survive unchanged.
+                accounts: session.declaredAccounts,
+                currentAccount: session.currentAccount,
             });
             // Sync effort with the SDK if it changed after the model switch
             const newEffortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
@@ -4649,6 +4946,26 @@ export class ClaudeAcpAgent {
             session.currentAgent = value;
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
+        else if (configId === ACCOUNT_CONFIG_ID) {
+            // Resolve BEFORE recording anything: an account nobody declared must
+            // leave the session exactly as it was. `setSessionConfigOption`'s shared
+            // validation already refuses a value that is not among the option's
+            // entries; this second check covers the one path that bypasses it (a
+            // client round-tripping `currentValue`) and keeps the refusal here
+            // rather than in a caller (R6.3).
+            const account = accountForValue(session.declaredAccounts ?? [], value);
+            if (!account) {
+                throw new Error(`Invalid value for config option ${configId}: ${value}`);
+            }
+            // No SDK call, and no query recreate: the account is applied through the
+            // per-session `env` at query CREATION (D2/D9 — the SDK already accepts
+            // one, so no Zed patch is involved), and this session's query keeps the
+            // account it was created under (D7).
+            this.selectedAccount = value;
+            session.currentAccount = value;
+            session.accountEnv = envForAccount(account);
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        }
         else {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
             if (configId === EFFORT_CONFIG_ID) {
@@ -5247,9 +5564,28 @@ export class ClaudeAcpAgent {
                 env: { ...baseSettings?.env, ...providerEnv },
             };
         }
+        // The account this session runs under (R6.3): the selector's last choice
+        // when it names a declared account, else the first declared one. Read from
+        // the resolved settings, because accounts are DECLARED, never discovered
+        // (D4) — nothing here scans a home directory for credential stores. With
+        // none declared there is no overlay and the process's own configuration
+        // home stands, which is exactly the behavior that predates this option.
+        const declaredAccounts = readDeclaredAccounts(settingsManager.getSettings(), this.logger);
+        const accountEntry = accountInForce(declaredAccounts, this.selectedAccount);
+        // The SESSION's account home, never the ADAPTER's (D3): this overlay is
+        // handed to the SDK per session and to nothing else. `process.env` is not
+        // mutated — `CLAUDE_CONFIG_DIR` is read once into a module-level constant
+        // that `settings.ts` uses to find the adapter's OWN settings.json, so a
+        // mutation would be seen by some readers and not others.
+        const accountEnv = accountEntry ? envForAccount(accountEntry.account) : undefined;
         const env = {
             ...process.env,
             ...userProvidedOptions?.env,
+            // After the client-supplied env: the selector is a live user choice,
+            // and an agent entry that pinned CLAUDE_CONFIG_DIR is precisely the
+            // "account as a second agent" shape this option replaces (D1). Before
+            // the provider routing, which sets ANTHROPIC_* and never this key.
+            ...accountEnv,
             // Client-managed LLM routing: `providers/set` config wins, else the
             // legacy gateway auth request. Routing is baked into the query at
             // creation; provider updates recreate loaded queries between turns.
@@ -5533,6 +5869,13 @@ export class ClaudeAcpAgent {
             // `xhigh` on its own is a legitimate selection that is not Ultracode.
             available: isUltracodeAvailable(currentModelInfo?.supportsEffort ? (currentModelInfo.supportedEffortLevels ?? []) : [], { disableWorkflows: workflowsDisabled }),
             enabled: settingsManager.getSettings().ultracode === true,
+        }, {
+            disableWorkflows: workflowsDisabled,
+            // Both halves of the selector, resolved above alongside the env they
+            // produced — so the row the client renders and the configuration
+            // directory the query was actually started with cannot disagree.
+            accounts: declaredAccounts,
+            currentAccount: accountEntry?.value,
         });
         // Apply the initial effort level to the SDK so it matches the UI default
         const initialEffort = configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
@@ -5611,6 +5954,9 @@ export class ClaudeAcpAgent {
             currentAgent,
             ultracode: initialUltracode,
             workflowsDisabled,
+            declaredAccounts,
+            currentAccount: accountEntry?.value,
+            accountEnv,
             fastModeEnabled,
             fastModeDisabledReason,
             abortController,
@@ -5980,8 +6326,12 @@ thinkingEnabled,
  *  direct callers/tests, in which case availability is derived from
  *  `settings` and the entry renders unselected. */
 ultracode, 
-/** Resolved session settings, read only for `disableWorkflows` — the half of
- *  the Ultracode gate that is not a model capability. */
+/** Resolved session settings, read for `disableWorkflows` — the half of the
+ *  Ultracode gate that is not a model capability — and, alongside them, the
+ *  declared accounts plus the one in force, which decide whether an account
+ *  selector is advertised at all (R6.1/R6.2). `accounts` is not a field of
+ *  the SDK's `Settings`, so it is carried beside them rather than picked
+ *  from them. */
 settings) {
     const options = [
         SessionModeManager.configOption(modes),
@@ -6087,6 +6437,15 @@ settings) {
             ],
         });
     }
+    // The account selector, last because it is the least often touched of the
+    // rows and the only one that governs the NEXT thread rather than this one.
+    // `createAccountConfigOption` returns undefined below two declared accounts,
+    // so the row is genuinely absent there rather than present and empty (D8,
+    // R6.2).
+    const accountOption = createAccountConfigOption(settings?.accounts ?? [], settings?.currentAccount);
+    if (accountOption) {
+        options.push(accountOption);
+    }
     return options;
 }
 // Claude Code CLI persists display strings like "opus[1m]" in settings,