mixdog 0.9.85 → 0.9.87

package/README.md

@@ -138,7 +138,7 @@ Common slash commands:
 /setting           open the runtime settings hub
 /mcp               manage MCP servers and tools
 /skills            choose a skill for the next request
-/channels          manage Discord/Telegram, schedules, webhooks, voice
+/channels          manage Discord, Telegram, and voice
 /compact           compact older conversation context
 /clear             reset the conversation and screen
 /OutputStyle       show or switch Lead output style
@@ -149,6 +149,12 @@ route. The model picker warms the provider catalog in the background and keeps
 Claude families such as Opus, Sonnet, Haiku, and Fable separate when filtering
 current Anthropic models.
 
+Workflows and agents are Markdown definition packs (`WORKFLOW.md`,
+`AGENT.md`). Built-ins ship with mixdog; custom packs live under the data
+directory (`workflows/<id>/`, `agents/<id>/`) and are edited on the desktop
+app's Workflows page. Schedules and webhooks are also managed in the desktop
+app.
+
 ## Scripts
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.85",
+  "version": "0.9.87",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -55,7 +55,7 @@
     "test:tool-contracts": "node scripts/tool-smoke.mjs",
     "smoke:patch": "node scripts/apply-patch-edit-smoke.mjs",
     "smoke:output": "node scripts/output-style-smoke.mjs",
-    "smoke:tui": "node scripts/tui-render-smoke.mjs && npm run test:tui-input-render && npm run test:tui-streaming-window && npm run test:tui-queue",
+    "smoke:tui": "node scripts/build-tui.mjs && node scripts/tui-render-smoke.mjs && npm run test:tui-input-render && npm run test:tui-streaming-window && npm run test:tui-queue",
     "smoke:freevars": "node scripts/freevar-smoke.mjs",
     "smoke:logguard": "node scripts/log-writer-guard-smoke.mjs",
     "smoke:live-worker": "node scripts/live-worker-smoke.mjs",
@@ -73,6 +73,7 @@
     "test:anthropic-oauth-race": "node --test scripts/anthropic-oauth-refresh-race-test.mjs",
     "test:grok-oauth-race": "node --test scripts/grok-oauth-refresh-race-test.mjs",
     "test:atomiclock": "node --test scripts/atomic-lock-tryonce-test.mjs",
+    "test:keychain": "node --test scripts/keychain-prewarm-test.mjs",
     "test:memory-routing": "node --test scripts/memory-cycle-routing-test.mjs scripts/maintenance-default-routes-test.mjs scripts/embedding-worker-exit-test.mjs scripts/embedding-runtime-prune-test.mjs",
     "test:embedding-runtime": "node --test scripts/embedding-runtime-prune-test.mjs scripts/memory-pg-recovery-test.mjs && node scripts/verify-embedding-runtime.mjs",
     "test:embedding-runtime:core": "node --test scripts/embedding-runtime-prune-test.mjs scripts/memory-pg-recovery-test.mjs && node scripts/verify-embedding-runtime.mjs --core",
@@ -87,7 +88,7 @@
     "test:release-focused": "npm run test:release-assets && npm run test:tool-contracts && npm run test:placeholder && npm run smoke:patch && npm run test:patch-binary-cache && npm run test:providers && npm run test:deferred-tools && npm run smoke:compact && node --test scripts/code-graph-root-federation-test.mjs scripts/code-graph-aggregate-cwd-test.mjs && npm run test:code-graph-dispatch && node --test scripts/code-graph-disk-hit-test.mjs && npm run test:shellhardening && node --test scripts/windows-hide-spawn-options-test.mjs && npm run test:session && npm run test:workflow-editor && npm run test:embedding-runtime && node --test scripts/tui-transcript-perf-test.mjs",
     "test:native-edit-wire": "node --test scripts/native-edit-wire-test.mjs",
     "test:patch-binary-cache": "node --test scripts/patch-binary-cache-test.mjs",
-    "test:session": "node --test scripts/session-orphan-sweep-test.mjs scripts/interrupted-turn-history-test.mjs scripts/session-heartbeat-lifecycle-test.mjs scripts/remote-transition-order-test.mjs",
+    "test:session": "node --test scripts/session-orphan-sweep-test.mjs scripts/interrupted-turn-history-test.mjs scripts/turn-checkpoint-crash-test.mjs scripts/session-heartbeat-lifecycle-test.mjs scripts/remote-transition-order-test.mjs",
     "test:rebindtail": "node --test scripts/forwarder-rebind-tail-test.mjs",
     "test:workflow-editor": "node --test scripts/workflow-id-test.mjs scripts/workflow-pack-editor-test.mjs",
     "test:route-scope": "node --test scripts/route-scope-isolation-test.mjs",

package/src/defaults/agents.json

@@ -48,6 +48,18 @@
       "permission": "read",
       "stallCap": { "idleSeconds": 300, "toolRunningSeconds": 300 }
     },
+    {
+      "agent": "title-agent",
+      "slot": "title",
+      "systemFile": "rules/agent/43-title-agent.md",
+      "description": "One-shot session title generator invoked by the desktop host",
+      "invokedBy": "desktop-title",
+      "maintKey": "memory",
+      "toolSchemaProfile": "none",
+      "kind": "maintenance",
+      "permission": "read",
+      "stallCap": { "idleSeconds": 90, "toolRunningSeconds": 90 }
+    },
     {
       "agent": "scheduler-task",
       "slot": "scheduler",

package/src/defaults/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Use this skill to configure a mixdog installation — request-driven recipes for models, MCP, channels, output style, memory/recap, skills, secrets, and workflow packs. Triggers on "setup", "configure", "change model", "add MCP", "output style", "Discord token", "workflow".
+description: Use this skill to configure a mixdog installation — request-driven recipes for models, MCP, channels, remote, output style, memory, skills, secrets, and workflow/agent packs. Triggers on "setup", "configure", "change model", "add MCP", "output style", "Discord token", "workflow", "remote".
 ---
 
 # Setup Skill
@@ -34,16 +34,21 @@ apply it, and verify the result.
 |---|---|
 | Main model | `/model` |
 | Agent model | `/agents` |
-| Workflow pack | `/workflow` |
+| Workflow switch | `/workflow` |
+| Workflow/agent definition | desktop Workflows page or pack files |
 | Search model | `/search` |
 | Reasoning effort | `/effort [level]` |
 | Fast mode | `/fast [on|off]` |
 | Output style | `/style` |
-| Memory / recap | `/memory`, `/recap`, config |
+| Memory / core memories | `/memory`, config |
 | MCP server | `/mcp`, config |
 | Provider secret | provider login flow or secret store |
-| Discord / channel | config and channel runtime status |
+| Discord / Telegram / voice | `/channels`, config |
+| Remote (channel control) | `/remote` (manual claim) |
+| Theme | `/theme` |
+| Profile (title/language) | `/profile` |
 | Skill add/update | project or global `skills/<name>/SKILL.md` |
+| Schedules / webhooks | desktop app only |
 
 ## Recipes
 
@@ -59,12 +64,26 @@ apply it, and verify the result.
 2. Change the target agent route through the agent picker.
 3. Verify the target agent reports the new route on the next run.
 
-### Workflow pack
+### Workflow switch
 
 1. Check `/workflow` or `/setting` for the active workflow.
 2. Change with `/workflow`; this updates `config.workflow.active`.
 3. Verify the notice and active marker.
 
+### Workflow / agent definitions
+
+1. Workflows and agents are Markdown packs. Built-ins ship with mixdog
+   (workflows `default`, `solo`; agents worker, heavy-worker, reviewer,
+   debugger, maintainer); custom packs live at
+   `<mixdogData>/workflows/<id>/WORKFLOW.md` and
+   `<mixdogData>/agents/<id>/AGENT.md`.
+2. Saving a built-in id writes a user override; deleting the override
+   reverts to the built-in.
+3. The desktop app (Workflows page) is the full editor. The TUI only
+   switches the active workflow (`/workflow`) and per-agent model routes
+   (`/agents`).
+4. Verify with `/workflow` / `/agents` listings after the change.
+
 ### Search model
 
 1. Check `searchRoute` in config and the status line.
@@ -89,11 +108,13 @@ apply it, and verify the result.
 2. Change with `/style` and the picker.
 3. Verify the active style and run a short response if needed.
 
-### Memory and recap
+### Memory
 
-1. Inspect memory/recap status via commands or config.
-2. Update the requested setting only.
-3. Verify status output and, when relevant, run a small recall/recap check.
+1. `/memory` is the one-stop surface: memory on/off toggle plus core-memory
+   list, add, edit, and delete.
+2. Compact type is fixed to Fast-track; only auto-compact toggles in
+   `/setting`.
+3. Verify status output and, when relevant, run a small recall check.
 
 ### MCP server
 
@@ -108,13 +129,24 @@ apply it, and verify the result.
 2. Use the provider login flow, secret store, or environment variable path.
 3. Verify presence only; never print the secret value.
 
-### Discord or channel configuration
+### Discord / Telegram / voice channels
 
-1. Check config and runtime channel status.
-2. Update the requested channel setting.
+1. Check `/channels` (or `/setting` → Channel) and runtime channel status.
+2. Update the requested backend, credential, or main channel/chat setting.
 3. Restart/reconnect only when the channel implementation requires it.
 4. Verify channel presence and a non-secret status signal.
 
+Schedules and webhooks are managed in the desktop app, not the TUI.
+
+### Remote
+
+1. Remote is manual-only: `/remote` claims remote for the current session
+   and takes over from any other session. There is no auto-start, and
+   session handoffs never transfer ownership implicitly.
+2. Turning remote OFF (or exiting the owning session) stops messaging;
+   schedules and webhooks keep running.
+3. Verify via the status line or `/setting` → Remote Runtime.
+
 ### Skills
 
 1. Check existing skills with `/skills` or `skillsStatus()`.

package/src/help.mjs

@@ -5,22 +5,53 @@ export const HELP_LINES = [
   'mixdog — standalone mixdog CLI/TUI coding agent.',
   '',
   'Usage:',
-  '  mixdog [--provider <name>] [--model <name>] [--readonly]',
-  '  mixdog [--onboarding]      re-run the first-run setup wizard',
+  '  mixdog [options]           start the TUI in the current project',
   '  mixdog --provider <name> --model <name> [--effort <level>] [--fast] <role> <message...>',
   '  mixdog --help',
   '',
+  'Options:',
+  '  --provider <name>   provider route for this session',
+  '  --model <name>      model route for this session',
+  '  --effort <level>    reasoning effort for the selected model',
+  '  --fast              enable Fast mode for the selected model',
+  '  --workflow <name>   start with the given workflow active',
+  '  --readonly          read-only tool surface',
+  '  --remote            enable remote/channel mode for this session',
+  '  --onboarding        re-run the first-run setup wizard',
+  '',
   'Headless role commands require an explicit provider/model pair and run with',
   'ephemeral config/data; host behavioral config and personal state are not loaded.',
+  'Roles: explore, worker, heavy-worker, reviewer, debugger, maintainer, web-researcher.',
   '',
   'Slash commands (inside mixdog):',
-  '  /clear             reset the conversation and clear the screen',
-  '  /compact           compact older conversation context',
-  '  /model <name>      switch model/preset for subsequent turns',
-  '  /OutputStyle [name] show or switch Lead output style',
-  '  /providers         manage provider auth and local endpoints',
-  '  /agents            show available workflow agents',
-  '  /quit              quit (aliases: /exit, /q)',
+  '  /clear                        start a fresh chat (alias: /new)',
+  '  /project [path]               switch working directory (project)',
+  '  /compact                      compact older conversation context',
+  '  /autoclear [on|off|duration]  reduce cache-miss cost after long idle gaps',
+  '  /resume [id]                  resume a saved chat',
+  '  /context                      show current context surface',
+  '  /usage [refresh]              show total provider quota / balance',
+  '  /model [name|refresh]         switch model for subsequent turns',
+  '  /search                       set the web search provider/model',
+  '  /workflow [name]              switch the active workflow',
+  '  /OutputStyle [name]           switch Lead output style (alias: /style)',
+  '  /theme [id]                   change the TUI color theme',
+  '  /agents [refresh]             show available workflow agents',
+  '  /effort [level]               set reasoning effort for the current model',
+  '  /fast [on|off]                toggle Fast mode for the current model',
+  '  /mcp                          manage MCP servers and tools',
+  '  /skills                       choose a skill for the next request',
+  '  /memory [status|core ...]     list and edit core memories',
+  '  /plugins                      manage local plugin integrations',
+  '  /hooks                        manage before-tool hook rules and events',
+  '  /providers                    manage auth, API keys, OAuth, and local endpoints',
+  '  /channels                     manage Discord, Telegram, and voice',
+  '  /remote                       claim remote for this session',
+  '  /setting                      open runtime settings (aliases: /settings, /config)',
+  '  /profile                      set your title and response language',
+  '  /update                       check version and update mixdog',
+  '  /doctor                       diagnose installation health',
+  '  /quit                         quit the TUI (aliases: /exit, /q)',
   '',
   'History: use ↑ / ↓ to recall previous inputs.',
 ];

package/src/lib/keychain-cjs.cjs

@@ -24,6 +24,11 @@ const KEYCHAIN_CACHE_TTL_MS = (() => {
 const _secretCache = new Map();
 const _cacheGenerations = new Map();
 let _cacheEpoch = 0;
+// A desktop process can create several session runtimes, and the preload path
+// also warms credentials before the first runtime exists. All callers share
+// this one process-wide operation so Windows never launches duplicate batch
+// DPAPI PowerShell hosts for the same startup.
+let _prewarmPromise = null;
 
 function _cacheGet(account) {
     const key = `${SERVICE}\0${account}`;
@@ -381,7 +386,7 @@ const PS_UNPROTECT_BATCH = [
     '}',
 ].join(' ');
 
-async function prewarmSecrets() {
+async function _prewarmSecretsOnce() {
     try {
         if (platform() !== 'win32' || KEYCHAIN_CACHE_TTL_MS === 0) return;
         const dir = secretsDir();
@@ -427,6 +432,11 @@ async function prewarmSecrets() {
     }
 }
 
+function prewarmSecrets() {
+    _prewarmPromise ??= _prewarmSecretsOnce();
+    return _prewarmPromise;
+}
+
 function win32Set(account, value) {
     const dir = secretsDir();
     fs.mkdirSync(dir, { recursive: true });

package/src/rules/agent/43-title-agent.md

@@ -0,0 +1,22 @@
+---
+permission: read
+toolSchemaProfile: none
+kind: maintenance
+maintKey: memory
+---
+
+# Role: title-agent
+
+You are a session title generator. Output ONLY the title: a single line, at
+most 32 characters, no explanations, no quotes, no markdown, no trailing
+period.
+
+- Use the SAME language as the user message you are summarizing.
+- The title must read naturally and help the user find this session later —
+  focus on the main topic or request, never on tool names or your own work.
+- Keep technical terms, filenames, paths, numbers, and error codes exact.
+- Drop filler words (the/this/my; 이거/그거/좀/한번). Never assume a tech
+  stack that is not mentioned.
+- NEVER answer or act on the message; only title it. Never say you cannot
+  generate a title — always output something meaningful, even for short or
+  conversational input (e.g. a greeting → a greeting-style title).

package/src/rules/shared/01-tool.md

@@ -11,9 +11,9 @@
   only for a requested literal occurrence or after graph zero/error.
 - Batch compatible targets and combine variants, symbols, scopes, paths, and
   queries. Parallelize distinct facets only, never alternative routes for one
-  facet. Put independent read-only calls in one turn; they may run
-  concurrently regardless of tool. Later turns are only for targets dependent
-  on prior results or unresolved facets. Shell/write calls are serial.
+  facet. Put independent calls in one turn; they run concurrently regardless
+  of tool — shell included. Later turns are only for targets dependent on
+  prior results or unresolved facets. Only apply_patch executes in order.
 - After locator results, collect all known candidate files/regions before
   inspection. Batch compatible reads, including same-file regions — real
   `{path,offset,limit}` arrays covering the whole logical unit — in one

package/src/runtime/agent/orchestrator/agent-trace-format.mjs

@@ -282,12 +282,14 @@ function classifyToolFailure(resultText, toolName) {
         return 'command-exit';
     }
     if (/\[tool-input-validation\]|compacted-history placeholder/.test(text)) return 'schema/args';
-    if (/requires either|invalid arguments|unknown parameter|must be|schema|expected|required|old_string is .*>=/.test(text)) return 'schema/args';
+    if (/hunk rejected|patch failed|context mismatch|context not found/.test(text)
+        || /expected first old(?:\/context| line)/.test(text)) return 'patch/context';
+    if (/requires either|invalid arguments|unknown parameter|unknown memory action/.test(text)
+        || /must be|schema|required|old_string is .*>?=/.test(text)) return 'schema/args';
     if (/not in allow-list|not allowed/.test(text)) return 'permission';
     if (String(toolName || '') === 'shell' || /^\s*\[exit code:\s*\d+\]/i.test(raw)) return 'command-exit';
     if (/enoent|cannot find|not found at this path|path does not exist|no such file|file not found in graph|unreadable/.test(text)) return 'path/enoent';
     if (/timed out|timeout|interrupted|aborted/.test(text)) return 'timeout/abort';
-    if (/hunk rejected|patch failed|context mismatch|expected first old\/context|context not found/.test(text)) return 'patch/context';
     if (/permission|denied|forbidden/.test(text)) return 'permission';
     if (/unknown tool|tool.*not.*available|missing.*tool/.test(text)) return 'tool-surface';
     return 'runtime/failure';

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -24,6 +24,18 @@ const DEFAULT_MCP_STARTUP_TIMEOUT_MS = 10000;
 // --- State ---
 const servers = new Map();
 let mcpSdkPromise = null;
+// Agent-shard proxy mode (P2, docs/agent-shard-design.md): a shard child has
+// no MCP connections of its own — the lead process owns the singleton server
+// registry. When a proxy is installed, tool DEFINITIONS come from the
+// lead-supplied snapshot and every call is forwarded over IPC; the local
+// `servers` map stays empty and untouched.
+let _mcpToolProxy = null;
+export function setMcpToolProxy(proxy) {
+    _mcpToolProxy = proxy && typeof proxy.call === 'function'
+        ? { tools: Array.isArray(proxy.tools) ? proxy.tools : [], call: proxy.call }
+        : null;
+    _invalidateMcpToolFieldMemo();
+}
 // Memo for mcpToolHasField(name, field) — keyed by `${toolName}|${field}`.
 // The lookup (regex parse + servers Map get + tools.find + schema property
 // inspection) runs on every MCP tool invocation but its result only changes
@@ -139,6 +151,7 @@ export async function connectMcpServers(config) {
  * Tool names are prefixed: `mcp__{serverName}__{toolName}`
  */
 export function getMcpTools() {
+    if (_mcpToolProxy) return _mcpToolProxy.tools;
     const tools = [];
     for (const server of servers.values()) {
         tools.push(...server.tools);
@@ -182,6 +195,9 @@ export async function executeMcpTool(name, args) {
     const match = name.match(/^mcp__(.+?)__(.+)$/);
     if (!match)
         throw new Error(`Not an MCP tool name: ${name}`);
+    // Proxy mode: the lead executes (including its own reconnect/timeout/cap
+    // handling) and returns the final model-visible result/envelope.
+    if (_mcpToolProxy) return _mcpToolProxy.call(name, args);
     const [, serverName, toolName] = match;
     const server = servers.get(serverName);
     if (!server)
@@ -355,6 +371,7 @@ export function isMcpTool(name) {
 /** True when the prefixed name exists on a connected MCP server. */
 export function isRegisteredMcpTool(name) {
     if (!isMcpTool(name)) return false;
+    if (_mcpToolProxy) return _mcpToolProxy.tools.some((t) => t?.name === name);
     const match = name.match(/^mcp__(.+?)__(.+)$/);
     if (!match) return false;
     const [, serverName] = match;
@@ -372,6 +389,13 @@ export function mcpToolHasField(name, field) {
     const memoKey = `${name}|${field}`;
     const memoized = _mcpToolFieldMemo.get(memoKey);
     if (memoized !== undefined) return memoized;
+    if (_mcpToolProxy) {
+        const proxyTool = _mcpToolProxy.tools.find((t) => t?.name === name);
+        const proxyProps = proxyTool?.inputSchema?.properties;
+        const proxyResult = Boolean(proxyProps && Object.prototype.hasOwnProperty.call(proxyProps, field));
+        _mcpToolFieldMemo.set(memoKey, proxyResult);
+        return proxyResult;
+    }
     const match = name.match(/^mcp__(.+?)__(.+)$/);
     if (!match) { _mcpToolFieldMemo.set(memoKey, false); return false; }
     const [, serverName] = match;

package/src/runtime/agent/orchestrator/providers/admission-scheduler.mjs

@@ -1,7 +1,11 @@
 import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-export const PROVIDER_ACCOUNT_CONCURRENCY = 64;
+// Unbounded by design: provider requests must never serialize behind a local
+// concurrency cap. Rate-limit cooldowns below (server-mandated retry-after)
+// remain the only thing that parks/rejects requests; with an infinite limit
+// the adaptive halving/recovery below is inert.
+export const PROVIDER_ACCOUNT_CONCURRENCY = Infinity;
 export const PROVIDER_ACCOUNT_MAX_QUEUE = 1024;
 // A cooldown longer than this is a quota-window block (subscription limit),
 // not a transient burst: parking requests silently for it would look like a
@@ -119,9 +123,59 @@ export class ProviderAdmissionScheduler {
         this.reportedRateLimits = new WeakSet();
         this.closedReason = null;
         this.context = currentAdmission;
+        // Cross-process cooldown fan-out (agent shard pool): listeners observe
+        // locally-recorded 429 cooldowns and credential-driven resets so one
+        // account's quota window parks every shard process.
+        this.cooldownListeners = new Set();
     }
 
-    run(key, task, { signal = null } = {}) {
+    /** Observe cooldown/reset events. Returns an unsubscribe function. */
+    onCooldownEvent(listener) {
+        if (typeof listener !== 'function') return () => {};
+        this.cooldownListeners.add(listener);
+        return () => this.cooldownListeners.delete(listener);
+    }
+
+    _emitCooldownEvent(event) {
+        for (const listener of [...this.cooldownListeners]) {
+            try { listener(event); } catch { /* observer must not break admission */ }
+        }
+    }
+
+    /**
+     * Apply a cooldown recorded by ANOTHER process (shard broadcast). Extends
+     * the local lane's park window without re-emitting (no feedback loops) and
+     * without touching the adaptive limit — only the reporting process saw the
+     * actual 429. Returns true when the lane's window moved forward.
+     */
+    applyExternalCooldown(key, cooldownUntil) {
+        const laneKey = String(key || '');
+        const until = Number(cooldownUntil) || 0;
+        const now = this.now();
+        if (!laneKey || until <= now || this.closedReason) return false;
+        const lane = this.lanes.get(laneKey) || {
+            active: 0,
+            queue: [],
+            adaptive: isAnthropicLane(laneKey),
+            limit: this.concurrency,
+            cooldownUntil: 0,
+            recoverySuccesses: 0,
+            cooldownTimer: null,
+        };
+        if (!lane.adaptive || until <= lane.cooldownUntil) return false;
+        this.lanes.set(laneKey, lane);
+        lane.cooldownUntil = until;
+        lane.recoverySuccesses = 0;
+        this._scheduleCooldown(laneKey, lane);
+        // Same queue semantics as a locally-recorded quota window: parked
+        // requests must not hang silently for hours.
+        if (until - now > PROVIDER_COOLDOWN_FAIL_FAST_MS) {
+            this._rejectQueueForCooldown(laneKey, lane);
+        }
+        return true;
+    }
+
+    run(key, task, { signal = null, onCooldownWait = null } = {}) {
         const laneKey = String(key || 'provider:default');
         // Provider-local recovery may recursively call this.send(). It already
         // owns a slot, so reacquiring the same lane could deadlock a full wave.
@@ -168,6 +222,17 @@ export class ProviderAdmissionScheduler {
             }
             lane.queue.push(item);
             this._drain(laneKey, lane);
+            // Short-cooldown visibility: this request just parked behind an
+            // active burst cooldown (long quota windows fail fast above). Tell
+            // the caller how long the silent wait will be so the UI can show
+            // "rate-limited" instead of looking stalled.
+            if (!item.started && !item.canceled && lane.adaptive
+                && typeof onCooldownWait === 'function') {
+                const waitMs = lane.cooldownUntil - this.now();
+                if (waitMs > 250) {
+                    try { onCooldownWait(waitMs); } catch { /* display-only */ }
+                }
+            }
         });
     }
 
@@ -249,6 +314,7 @@ export class ProviderAdmissionScheduler {
         if (lane.cooldownUntil - now > PROVIDER_COOLDOWN_FAIL_FAST_MS) {
             this._rejectQueueForCooldown(key, lane);
         }
+        this._emitCooldownEvent({ type: 'cooldown', key, cooldownUntil: lane.cooldownUntil });
         return true;
     }
 
@@ -289,6 +355,11 @@ export class ProviderAdmissionScheduler {
             resetCount += 1;
             this._drain(key, lane);
         }
+        // resetCount gating terminates cross-process echo: a broadcast-driven
+        // second reset finds nothing to clear and emits nothing.
+        if (resetCount > 0) {
+            this._emitCooldownEvent({ type: 'reset', provider: providerName ? String(providerName) : null });
+        }
         return resetCount;
     }
 
@@ -432,7 +503,17 @@ export function wrapProviderAdmission(provider, providerName, scheduler = provid
                 ...opts,
                 signal: admissionSignal,
             });
-        }, { signal });
+        }, {
+            signal,
+            onCooldownWait: (waitMs) => {
+                // Display-only: the TUI/desktop 'reconnecting' stage already
+                // renders a custom verb, so no new stage vocabulary is needed.
+                const secs = Math.max(1, Math.ceil(waitMs / 1000));
+                try {
+                    opts.onStageChange?.('reconnecting', { message: `Rate-limited — waiting ~${secs}s for the provider window` });
+                } catch { /* display-only */ }
+            },
+        });
     };
     return provider;
 }