@cortexkit/opencode-magic-context 0.25.0 → 0.27.0

package/src/shared/resolve-fallbacks.ts

@@ -1,37 +1,27 @@
-import { getAgentFallbackModels } from "./model-requirements";
-
 /**
- * Resolve the final fallback model list to attempt for an OpenCode subagent
- * call.
- *
- * Policy (decided 2026-05-10):
- *   - If user configured explicit `fallback_models` in their magic-context.jsonc
- *     for this agent: use ONLY those. Respects user intent, no surprise
- *     providers.
- *   - If user did NOT configure any: fall back to the plugin's builtin
- *     provider-agnostic chain (`AGENT_MODEL_REQUIREMENTS`).
+ * Resolve the fallback model list to attempt for a hidden-agent (historian /
+ * dreamer / sidekick) call when its configured primary fails.
  *
- * The returned list does NOT include the primary model — it's the ordered
- * list of *alternates* to try after the primary fails. Each entry is
- * "provider/modelID" form.
+ * Policy: ONLY the user's explicitly-configured `fallback_models` for this
+ * agent. There is NO builtin provider-agnostic chain — a hardcoded chain
+ * inevitably names providers the user doesn't have (e.g. a metapi-only user got
+ * a chain of google/github-copilot/opencode entries, every one a
+ * `Model not found` retry), which produced confusing errors and wasted
+ * attempts. If the user configured nothing, this returns an empty list and the
+ * runner's session-model last resort (the model the user is actually using) is
+ * the only fallback.
  *
- * Duplicates and empty strings are filtered. Entries that don't match the
- * "provider/modelID" shape (must contain a "/" with non-empty parts) are
- * also dropped — defensive guard against malformed user config.
+ * The returned list does NOT include the primary model — it's the ordered list
+ * of *alternates* to try after the primary fails. Each entry is
+ * "provider/modelID" form. Duplicates and empty strings are filtered; entries
+ * that don't match the "provider/modelID" shape (a "/" with non-empty parts) are
+ * dropped as a defensive guard against malformed user config.
  */
 export function resolveFallbackChain(
-    agentName: string,
     userFallbacks: readonly string[] | string | undefined,
 ): string[] {
     const userList = normalizeUserFallbacks(userFallbacks);
-
-    if (userList.length > 0) {
-        return dedupe(userList.filter(isValidModelSpec));
-    }
-
-    const builtin = getAgentFallbackModels(agentName);
-    if (!builtin || builtin.length === 0) return [];
-    return dedupe(builtin.filter(isValidModelSpec));
+    return dedupe(userList.filter(isValidModelSpec));
 }
 
 function normalizeUserFallbacks(userFallbacks: readonly string[] | string | undefined): string[] {
@@ -74,3 +64,17 @@ export function parseProviderModel(spec: string): { providerID: string; modelID:
         modelID: spec.slice(slash + 1).trim(),
     };
 }
+
+/**
+ * Build the `{ model: { providerID, modelID } }` fragment for an OpenCode prompt
+ * body from a `provider/model` spec string, or `{}` when the spec is absent or
+ * unparseable (the session falls back to its default model). Spread into a
+ * `client.session.prompt` body.
+ */
+export function modelBodyField(spec: string | undefined): {
+    model?: { providerID: string; modelID: string };
+} {
+    if (!spec) return {};
+    const parsed = parseProviderModel(spec);
+    return parsed ? { model: parsed } : {};
+}

package/src/shared/rpc-server.ts

@@ -1,9 +1,11 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import {
+    chmodSync,
     mkdirSync,
     readdirSync,
     readFileSync,
     renameSync,
+    rmSync,
     unlinkSync,
     writeFileSync,
 } from "node:fs";
@@ -85,7 +87,22 @@ export class MagicContextRpcServer {
                     // file 0o600. renameSync preserves the tmp file's mode, so
                     // the 0o600 on the write covers the final file.
                     mkdirSync(dir, { recursive: true, mode: 0o700 });
+                    // mkdirSync's mode only applies on CREATION — a dir left by an
+                    // older build (or default 0o755 umask) keeps its loose perms, so
+                    // chmod it defensively so the bearer token isn't world-readable.
+                    try {
+                        chmodSync(dir, 0o700);
+                    } catch {
+                        // best-effort
+                    }
                     const tmpPath = `${this.portFilePath}.tmp`;
+                    // A stale tmp from a crashed write could exist with loose perms;
+                    // writeFileSync's mode only applies on create, so remove it first.
+                    try {
+                        rmSync(tmpPath, { force: true });
+                    } catch {
+                        // best-effort
+                    }
                     writeFileSync(
                         tmpPath,
                         JSON.stringify({
@@ -97,6 +114,13 @@ export class MagicContextRpcServer {
                         { encoding: "utf-8", mode: 0o600 },
                     );
                     renameSync(tmpPath, this.portFilePath);
+                    // renameSync preserves the tmp's mode, but chmod the final path
+                    // defensively in case the token file pre-existed with loose perms.
+                    try {
+                        chmodSync(this.portFilePath, 0o600);
+                    } catch {
+                        // best-effort
+                    }
                     log(`[rpc] server listening on 127.0.0.1:${this.port}`);
                 } catch (err) {
                     log(`[rpc] failed to write port file: ${err}`);

package/src/shared/rpc-types.ts

@@ -121,6 +121,8 @@ export interface StatusDetail extends SidebarSnapshot {
     historyBlockTokens: number;
     compressionBudget: number | null;
     compressionUsage: string | null;
+    /** Effective configured toast duration in ms after config resolution. */
+    toastDurationMs: number;
 }
 
 /** Embedding coverage for `/ctx-embed` status (mirrors getEmbeddingCoverageStatus). */

package/src/shared/subagent-runner.ts

@@ -155,9 +155,9 @@ export type SubagentProgressEvent =
  * Fields:
  * - `ok`: true iff the child produced a final assistant message.
  * - `assistantText`: concatenated text content from the final assistant
- *   message, with leading/trailing whitespace trimmed. Empty string if the
- *   child finished but produced no text (rare — usually means the model
- *   only emitted tool calls and we didn't follow up).
+ *   message, with leading/trailing whitespace trimmed. Empty assistant text is
+ *   reported as `ok: false, reason: "no_assistant"` so callers can try fallback
+ *   models instead of accepting an unusable success.
  * - `reason`: failure category, one of:
  *     - `"timeout"`: hit `timeoutMs` before the child finished
  *     - `"abort"`: caller's `signal` was triggered
@@ -180,6 +180,15 @@ export type SubagentRunResult =
           ok: true;
           assistantText: string;
           durationMs: number;
+          /**
+           * Number of tool invocations the agent made during the run. Pi reports
+           * this so callers that gate on "did the agent actually investigate vs
+           * just paraphrase" (refresh-primers' grounding gate) work on Pi, whose
+           * facade otherwise surfaces only the final assistant text. OpenCode
+           * leaves it undefined — its callers read tool-call parts straight off
+           * the real session messages.
+           */
+          toolCallCount?: number;
           meta?: Record<string, unknown>;
       }
     | {

package/src/shared/tui-config.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const roots: string[] = [];
+const prevConfigDir = process.env.OPENCODE_CONFIG_DIR;
+
+afterEach(() => {
+    if (prevConfigDir === undefined) delete process.env.OPENCODE_CONFIG_DIR;
+    else process.env.OPENCODE_CONFIG_DIR = prevConfigDir;
+    for (const root of roots.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+describe("ensureTuiPluginEntry", () => {
+    it("preserves tuple dev-path plugin entry and does not add @latest", async () => {
+        const root = mkdtempSync(join(tmpdir(), "mc-tui-"));
+        roots.push(root);
+        process.env.OPENCODE_CONFIG_DIR = root;
+        const devPath = "/Work/magic-context/packages/plugin";
+        const tuiPath = join(root, "tui.json");
+        writeFileSync(
+            tuiPath,
+            `${JSON.stringify({ plugin: [[devPath, { sidebar: true }], "other-plugin"] }, null, 2)}\n`,
+        );
+
+        const { ensureTuiPluginEntry } = await import("./tui-config");
+        const changed = ensureTuiPluginEntry();
+        expect(changed).toBe(false);
+        const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
+        expect(parsed.plugin).toHaveLength(2);
+        expect(Array.isArray(parsed.plugin[0])).toBe(true);
+        expect((parsed.plugin[0] as unknown[])[0]).toBe(devPath);
+        expect(parsed.plugin[1]).toBe("other-plugin");
+        expect(existsSync(`${tuiPath}.tmp`)).toBe(false);
+    });
+
+    it("upgrades bare npm name to @latest while preserving tuple options", async () => {
+        const root = mkdtempSync(join(tmpdir(), "mc-tui-npm-"));
+        roots.push(root);
+        process.env.OPENCODE_CONFIG_DIR = root;
+        const tuiPath = join(root, "tui.json");
+        writeFileSync(
+            tuiPath,
+            `${JSON.stringify(
+                {
+                    plugin: [["@cortexkit/opencode-magic-context", { enabled: true }]],
+                },
+                null,
+                2,
+            )}\n`,
+        );
+
+        const { ensureTuiPluginEntry } = await import("./tui-config");
+        expect(ensureTuiPluginEntry()).toBe(true);
+        const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
+        const entry = parsed.plugin[0] as unknown[];
+        expect(entry[0]).toBe("@cortexkit/opencode-magic-context@latest");
+        expect(entry[1]).toEqual({ enabled: true });
+    });
+});

package/src/shared/tui-config.ts

@@ -3,7 +3,15 @@
  * Called from the server plugin at startup so the TUI sidebar loads on next restart.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+    chmodSync,
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    renameSync,
+    statSync,
+    writeFileSync,
+} from "node:fs";
 import { dirname, join } from "node:path";
 import { parse, stringify } from "comment-json";
 import { log } from "./logger";
@@ -12,27 +20,41 @@ import { getOpenCodeConfigPaths } from "./opencode-config-dir";
 const PLUGIN_NAME = "@cortexkit/opencode-magic-context";
 const PLUGIN_ENTRY = `${PLUGIN_NAME}@latest`;
 
-/**
- * Detect whether a tui.json plugin entry already references magic-context, in
- * any form. Covers:
- *   - Bare npm name: "@cortexkit/opencode-magic-context"
- *   - Versioned npm: "@cortexkit/opencode-magic-context@latest" / "@0.15.7" / etc.
- *   - Local dev directory path (absolute or relative): ".../magic-context"
- *     or ".../magic-context/packages/plugin"
- *   - file:// URLs pointing at the same paths
- *   - Tarball paths ending in opencode-magic-context-*.tgz
- *
- * Without the path/URL detection, doctor/setup auto-injection adds the npm
- * @latest entry on top of an existing dev path, double-loading the plugin.
- */
-function isMagicContextEntry(entry: string): boolean {
-    if (!entry) return false;
-    if (entry === PLUGIN_NAME) return true;
-    if (entry.startsWith(`${PLUGIN_NAME}@`)) return true;
-    // Local directory paths: match anywhere in the string so the setup pattern
-    // (dir-only, dir + /packages/plugin, file:// + either) all qualify.
-    if (entry.includes("opencode-magic-context")) return true;
-    return false;
+function pluginEntryId(entry: unknown): string {
+    if (typeof entry === "string") return entry;
+    if (Array.isArray(entry) && typeof entry[0] === "string") return entry[0];
+    return "";
+}
+
+function isLocalMagicContextDevEntry(entry: unknown): boolean {
+    const id = pluginEntryId(entry);
+    if (!id) return false;
+    if (id === PLUGIN_NAME || id.startsWith(`${PLUGIN_NAME}@`)) return false;
+    const isPath =
+        id.startsWith("file://") || id.startsWith("/") || id.startsWith("./") || id.includes("\\");
+    if (!isPath) return false;
+    return id.includes("opencode-magic-context") || id.includes("magic-context");
+}
+
+function isMagicContextPluginEntry(entry: unknown): boolean {
+    const id = pluginEntryId(entry);
+    if (!id) return false;
+    if (id === PLUGIN_NAME || id.startsWith(`${PLUGIN_NAME}@`)) return true;
+    return isLocalMagicContextDevEntry(entry);
+}
+
+function writeTuiConfigAtomic(configPath: string, config: Record<string, unknown>): void {
+    const body = `${stringify(config, null, 2)}\n`;
+    const tmpPath = `${configPath}.tmp`;
+    writeFileSync(tmpPath, body);
+    try {
+        if (statSync(configPath, { throwIfNoEntry: false })?.isFile()) {
+            chmodSync(tmpPath, statSync(configPath).mode & 0o777);
+        }
+    } catch {
+        /* new file */
+    }
+    renameSync(tmpPath, configPath);
 }
 
 function resolveTuiConfigPath(): string {
@@ -59,35 +81,41 @@ export function ensureTuiPluginEntry(): boolean {
             config = (parse(raw) as Record<string, unknown>) ?? {};
         }
 
-        const plugins = Array.isArray(config.plugin)
-            ? config.plugin.filter((p): p is string => typeof p === "string")
-            : [];
+        const plugins: unknown[] = Array.isArray(config.plugin) ? [...config.plugin] : [];
 
-        const existingIdx = plugins.findIndex(isMagicContextEntry);
+        const existingIdx = plugins.findIndex(isMagicContextPluginEntry);
         if (existingIdx >= 0) {
             const existing = plugins[existingIdx];
-            if (existing === PLUGIN_ENTRY) {
-                return false; // Already @latest
+            if (isLocalMagicContextDevEntry(existing)) {
+                return false;
+            }
+            const id = pluginEntryId(existing);
+            if (id === PLUGIN_ENTRY) {
+                return false;
             }
-            // Only upgrade the bare versionless npm name to @latest.
-            // Pinned versions (e.g. @0.8.10), local dev paths
-            // (~/Work/OSS/magic-context/packages/plugin), and
-            // file:// URLs are all left as-is — the user chose them
-            // intentionally and overwriting their dev-loop entry would
-            // either double-load the plugin (npm + dev) or replace
-            // their working directory pointer.
-            if (existing === PLUGIN_NAME) {
-                plugins[existingIdx] = PLUGIN_ENTRY;
+            if (id === PLUGIN_NAME) {
+                if (Array.isArray(existing) && existing.length >= 1) {
+                    const replacement = [...existing];
+                    replacement[0] = PLUGIN_ENTRY;
+                    plugins[existingIdx] = replacement;
+                } else {
+                    plugins[existingIdx] = PLUGIN_ENTRY;
+                }
             } else {
                 return false;
             }
         } else {
-            plugins.push(PLUGIN_ENTRY);
+            const hasDev = plugins.some(isLocalMagicContextDevEntry);
+            if (!hasDev) {
+                plugins.push(PLUGIN_ENTRY);
+            } else {
+                return false;
+            }
         }
         config.plugin = plugins;
 
         mkdirSync(dirname(configPath), { recursive: true });
-        writeFileSync(configPath, `${stringify(config, null, 2)}\n`);
+        writeTuiConfigAtomic(configPath, config);
         log(`[magic-context] updated TUI plugin entry in ${configPath}`);
         return true;
     } catch (error) {

package/src/tui/data/context-db.ts

@@ -205,6 +205,7 @@ export async function loadStatusDetail(
         historyBlockTokens: 0,
         compressionBudget: null,
         compressionUsage: null,
+        toastDurationMs: 5000,
     };
 
     if (!rpcClient) return emptyDetail;
@@ -299,6 +300,17 @@ export async function dismissUpgradeReminder(sessionId: string): Promise<boolean
     }
 }
 
+/** Resolve global toast duration from server config via RPC. */
+export async function loadToastDurationMs(): Promise<number> {
+    if (!rpcClient) return 5000;
+    try {
+        const result = await rpcClient.call<{ toastDurationMs?: number }>("toast-duration", {});
+        return typeof result.toastDurationMs === "number" ? result.toastDurationMs : 5000;
+    } catch {
+        return 5000;
+    }
+}
+
 export interface TuiMessage {
     id: number;
     type: string;

package/src/tui/index.tsx

@@ -6,7 +6,7 @@ import { createMemo } from "solid-js"
 import type { TuiPlugin, TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui"
 import { createSidebarContentSlot, kickRecompProgressRefresh } from "./slots/sidebar-content"
 import packageJson from "../../package.json"
-import { closeRpc, consumeTuiMessages, dismissUpgradeReminder, getAnnouncement, getCompartmentCount, getRpcGeneration, initRpcClient, loadEmbedDetail, loadStatusDetail, markAnnounced, markTuiMessagesHandled, requestRecomp, requestUpgrade, type EmbedDetail, type TuiMessage, type StatusDetail } from "./data/context-db"
+import { closeRpc, consumeTuiMessages, dismissUpgradeReminder, getAnnouncement, getCompartmentCount, getRpcGeneration, initRpcClient, loadEmbedDetail, loadStatusDetail, loadToastDurationMs, markAnnounced, markTuiMessagesHandled, requestRecomp, requestUpgrade, type EmbedDetail, type TuiMessage, type StatusDetail } from "./data/context-db"
 import { formatThresholdPercent } from "../shared/format-threshold"
 import { detectConflicts } from "../shared/conflict-detector"
 import { fixConflicts } from "../shared/conflict-fixer"
@@ -14,6 +14,48 @@ import { readJsoncFile } from "../shared/jsonc-parser"
 import { getOpenCodeConfigPaths } from "../shared/opencode-config-dir"
 
 const PLUGIN_NAME = "@cortexkit/opencode-magic-context"
+const DEFAULT_TOAST_DURATION_MS = 5000
+let unifiedToastDurationMs = DEFAULT_TOAST_DURATION_MS
+
+async function refreshToastDurationMs(): Promise<void> {
+    try {
+        const resolved = await loadToastDurationMs()
+        if (typeof resolved === "number" && Number.isFinite(resolved)) {
+            unifiedToastDurationMs = resolved
+        }
+    } catch {
+        // Keep the current value; the next poll/startup can retry.
+    }
+}
+
+function getToastDurationMs(): number {
+    return unifiedToastDurationMs
+}
+
+function showToast(
+    api: TuiPluginApi,
+    input: {
+        message: string
+        variant: "info" | "warning" | "error" | "success"
+        durationOverrideMs?: number
+    },
+): void {
+    const duration =
+        typeof input.durationOverrideMs === "number" && Number.isFinite(input.durationOverrideMs)
+            ? input.durationOverrideMs
+            : getToastDurationMs()
+    // toast_duration_ms = 0 disables Magic Context toasts entirely. An explicit
+    // positive per-call override (e.g. restart-required) still shows; only a
+    // non-positive effective duration suppresses the toast.
+    if (!(duration > 0)) {
+        return
+    }
+    api.ui.toast({
+        message: input.message,
+        variant: input.variant,
+        duration,
+    })
+}
 
 function ensureParentDir(filePath: string) {
     mkdirSync(dirname(filePath), { recursive: true })
@@ -97,14 +139,18 @@ function showConflictDialog(api: TuiPluginApi, directory: string, reasons: strin
                             title="✅ Configuration Fixed"
                             message={`${actionSummary}\n\nPlease restart OpenCode for changes to take effect.`}
                             onConfirm={() => {
-                                api.ui.toast({ message: "Restart OpenCode to enable Magic Context", variant: "warning", duration: 10000 })
+                                showToast(api, {
+                                    message: "Restart OpenCode to enable Magic Context",
+                                    variant: "warning",
+                                    durationOverrideMs: 10_000,
+                                })
                             }}
                         />
                     ))
                 }, 50)
             }}
             onCancel={() => {
-                api.ui.toast({ message: "Magic Context remains disabled. Run: npx @cortexkit/opencode-magic-context@latest doctor", variant: "warning", duration: 5000 })
+                showToast(api, { message: "Magic Context remains disabled. Run: npx @cortexkit/opencode-magic-context@latest doctor", variant: "warning" })
             }}
         />
     ))
@@ -132,7 +178,7 @@ function showTuiSetupDialog(api: TuiPluginApi) {
                                 title="❌ Setup Failed"
                                 message={'Could not update tui.json automatically. Add the plugin manually:\n\n  { "plugin": ["@cortexkit/opencode-magic-context"] }'}
                                 onConfirm={() => {
-                                    api.ui.toast({ message: "Add plugin to tui.json manually", variant: "warning", duration: 5000 })
+                                    showToast(api, { message: "Add plugin to tui.json manually", variant: "warning" })
                                 }}
                             />
                         ))
@@ -146,14 +192,18 @@ function showTuiSetupDialog(api: TuiPluginApi) {
                             title="✅ Sidebar Enabled"
                             message="tui.json updated with Magic Context plugin.\n\nPlease restart OpenCode to see the sidebar."
                             onConfirm={() => {
-                                api.ui.toast({ message: "Restart OpenCode to see the sidebar", variant: "warning", duration: 10000 })
+                                showToast(api, {
+                                    message: "Restart OpenCode to see the sidebar",
+                                    variant: "warning",
+                                    durationOverrideMs: 10_000,
+                                })
                             }}
                         />
                     ))
                 }, 50)
             }}
             onCancel={() => {
-                api.ui.toast({ message: "You can add the sidebar later via: npx @cortexkit/opencode-magic-context@latest doctor", variant: "info", duration: 5000 })
+                showToast(api, { message: "You can add the sidebar later via: npx @cortexkit/opencode-magic-context@latest doctor", variant: "info" })
             }}
         />
     ))
@@ -203,8 +253,16 @@ const StatusDialog = (props: { api: TuiPluginApi; s: StatusDetail }) => {
     const t = () => theme()
     const s = () => props.s
 
+    // Prefer the RPC-provided model context limit (what the sidebar shows) so the
+    // two surfaces never disagree. Fall back to deriving from usage% only when the
+    // RPC limit is absent (0) — and that derivation is itself undefined at 0%, so
+    // it stays "?" rather than showing a number inconsistent with the sidebar.
     const contextLimit = () =>
-        s().usagePercentage > 0 ? Math.round(s().inputTokens / (s().usagePercentage / 100)) : 0
+        s().contextLimit > 0
+            ? s().contextLimit
+            : s().usagePercentage > 0
+              ? Math.round(s().inputTokens / (s().usagePercentage / 100))
+              : 0
 
     const elapsed = () => (s().lastResponseTime > 0 ? Date.now() - s().lastResponseTime : 0)
 
@@ -450,7 +508,7 @@ function getModelKeyFromMessages(api: TuiPluginApi, sessionId: string): string |
 async function showRecompDialog(api: TuiPluginApi, targetSessionId = getSessionId(api)): Promise<boolean> {
     const sessionId = targetSessionId
     if (!sessionId) {
-        api.ui.toast({ message: "No active session", variant: "warning" })
+        showToast(api, { message: "No active session", variant: "warning" })
         return false
     }
 
@@ -475,10 +533,10 @@ async function showRecompDialog(api: TuiPluginApi, targetSessionId = getSessionI
             onConfirm={() => {
                 void requestRecomp(sessionId)
                 kickRecompProgressRefresh()
-                api.ui.toast({ message: "Recomp requested — historian will start shortly", variant: "info", duration: 5000 })
+                showToast(api, { message: "Recomp requested — historian will start shortly", variant: "info" })
             }}
             onCancel={() => {
-                api.ui.toast({ message: "Recomp cancelled", variant: "info", duration: 3000 })
+                showToast(api, { message: "Recomp cancelled", variant: "info", durationOverrideMs: 3000 })
             }}
         />
     ))
@@ -535,12 +593,11 @@ function showUpgradeDialog(
                     // call fires no message event, so without this the progress
                     // bar wouldn't appear until the upgrade finished.
                     kickRecompProgressRefresh()
-                    api.ui.toast({
+                    showToast(api, {
                         message: resume
                             ? "Resuming session upgrade — running in the background"
                             : "Session upgrade started — running in the background",
                         variant: "info",
-                        duration: 5000,
                     })
                     // Dismiss the durable reminder ONLY after the upgrade request
                     // actually started. If requestUpgrade() returns false (RPC /
@@ -558,10 +615,10 @@ function showUpgradeDialog(
                     // never-upgraded session (dogfood 2026-05-30) relies on THIS
                     // being the only place the TUI path stamps.
                     void dismissUpgradeReminder(sessionId)
-                    api.ui.toast({
+                    showToast(api, {
                         message: "Upgrade skipped — run /ctx-session-upgrade anytime",
                         variant: "info",
-                        duration: 4000,
+                        durationOverrideMs: 4000,
                     })
                 }}
             />
@@ -573,7 +630,7 @@ function showUpgradeDialog(
 async function showStatusDialog(api: TuiPluginApi, targetSessionId = getSessionId(api)): Promise<boolean> {
     const sessionId = targetSessionId
     if (!sessionId) {
-        api.ui.toast({ message: "No active session", variant: "warning" })
+        showToast(api, { message: "No active session", variant: "warning" })
         return false
     }
 
@@ -793,6 +850,7 @@ const tui: TuiPlugin = async (api, _options, meta) => {
     // Initialize RPC client for server communication
     const directory = api.state.path.directory ?? ""
     initRpcClient(directory)
+    await refreshToastDurationMs()
 
     // Register sidebar slot
     api.slots.register(createSidebarContentSlot(api))
@@ -830,6 +888,9 @@ const tui: TuiPlugin = async (api, _options, meta) => {
         pollInFlight = true
         const pollGeneration = getRpcGeneration()
         void consumeTuiMessages(requestedSessionId).then(async (messages) => {
+            if (unifiedToastDurationMs === DEFAULT_TOAST_DURATION_MS) {
+                void refreshToastDurationMs()
+            }
             // The dialog handlers read the current session when they run. If the
             // user switched routes while the RPC was in flight, drop this whole
             // batch without advancing the cursor; the next poll for the new
@@ -843,6 +904,12 @@ const tui: TuiPlugin = async (api, _options, meta) => {
             const orderedMessages = [...messages].sort((a, b) => a.id - b.id)
             const handledMessageIds = new Set<number>()
             for (const msg of orderedMessages) {
+                // A dialog helper earlier in this batch may have awaited; re-check
+                // the route before EACH message so a later action/toast in the same
+                // batch can't paint into a session the user switched to mid-batch
+                // (the pre-batch + pre-ack guards alone don't cover mid-batch awaits).
+                if (getRpcGeneration() !== pollGeneration) return
+                if (getSessionId(api) !== requestedSessionId) return
                 // Drop any action/dialog whose sessionId doesn't match this TUI's
                 // active session (session-less/global notifications still apply).
                 if (
@@ -854,10 +921,13 @@ const tui: TuiPlugin = async (api, _options, meta) => {
                 }
                 if (msg.type === "toast") {
                     const p = msg.payload
-                    api.ui.toast({
+                    showToast(api, {
                         message: String(p.message ?? ""),
                         variant: (p.variant as "info" | "warning" | "error" | "success") ?? "info",
-                        duration: typeof p.duration === "number" ? p.duration : 5000,
+                        durationOverrideMs:
+                            typeof p.duration === "number" && Number.isFinite(p.duration)
+                                ? p.duration
+                                : undefined,
                     })
                     handledMessageIds.add(msg.id)
                 } else if (msg.type === "action") {