@cortexkit/opencode-magic-context 0.17.2 → 0.18.0

package/src/shared/model-suggestion-retry.ts

@@ -1,6 +1,8 @@
 import type { createOpencodeClient } from "@opencode-ai/sdk";
 
+import { detectOverflow } from "../features/magic-context/overflow-detection";
 import { log } from "./logger";
+import { parseProviderModel } from "./resolve-fallbacks";
 
 type Client = ReturnType<typeof createOpencodeClient>;
 
@@ -20,6 +22,29 @@ export interface PromptRetryOptions {
     timeoutMs?: number;
     /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
     signal?: AbortSignal;
+    /**
+     * Ordered list of "provider/modelID" alternates to try if the primary call
+     * (and its single-suggestion retry) fails. Empty / undefined = no fallback
+     * iteration (legacy behavior).
+     *
+     * Fallback policy:
+     *   - Each fallback gets the FULL `timeoutMs` budget (per-attempt, not total).
+     *   - Suggestion-retry runs inside each attempt (so "did you mean X?" errors
+     *     still self-heal at the primary AND at each fallback).
+     *   - Iteration stops immediately on abort/timeout/context-overflow errors —
+     *     fallbacks won't help and the caller's emergency-recovery path needs
+     *     to handle these.
+     *   - On all-failed, the LAST error is thrown (matches legacy behavior when
+     *     `fallbackModels` is empty).
+     */
+    fallbackModels?: readonly string[];
+    /**
+     * Identifier for structured logging (e.g. "dreamer:consolidate",
+     * "historian", "compressor", "sidekick"). Helps correlate fallback
+     * attempts to a specific call site in `magic-context.log`. Defaults to
+     * "subagent" if not provided.
+     */
+    callContext?: string;
 }
 
 export interface ModelSuggestionInfo {
@@ -95,6 +120,15 @@ async function promptWithTimeout(
     timeoutMs: number,
     signal?: AbortSignal,
 ): Promise<void> {
+    // Bail immediately if the caller's signal is already aborted (e.g.
+    // lease loss before this attempt was scheduled). Per spec
+    // `addEventListener('abort', ...)` on an already-aborted signal fires
+    // synchronously in modern Node/Bun, but an explicit guard is clearer
+    // and avoids one wasted upstream `client.session.prompt` round-trip
+    // before `isNonRetryable` catches the cancellation at the chain loop.
+    if (signal?.aborted) {
+        throw new Error("prompt aborted by external signal");
+    }
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
@@ -121,22 +155,76 @@ async function promptWithTimeout(
     }
 }
 
-export async function promptSyncWithModelSuggestionRetry(
+/**
+ * Returns true if the error indicates a NON-RETRYABLE condition where iterating
+ * to a fallback model would be pointless or harmful:
+ *
+ *   - External abort (user cancellation, lease loss, etc.) — caller wants to
+ *     stop, not retry.
+ *   - Context overflow — same prompt will overflow on any reasonably-sized
+ *     model. Caller has its own emergency-recovery path for this.
+ *   - Timeout — same wall-clock budget on the same prompt is unlikely to
+ *     succeed on another model. Caller decides whether to retry at a higher
+ *     level (e.g. historian's MAX_HISTORIAN_RETRIES loop).
+ *
+ * Everything else (auth errors, ProviderModelNotFoundError without suggestion,
+ * rate limits, transient network failures, etc.) is considered retryable on a
+ * different model.
+ */
+function isNonRetryable(error: unknown, externalSignal?: AbortSignal): boolean {
+    if (externalSignal?.aborted) return true;
+
+    if (error instanceof Error) {
+        if (error.name === "AbortError") return true;
+        // promptWithTimeout wraps both abort cases in plain `Error` with a
+        // recognizable message.
+        if (error.message === "prompt aborted by external signal") return true;
+        if (/^prompt timed out after \d+ms$/.test(error.message)) return true;
+    }
+
+    if (detectOverflow(error).isOverflow) return true;
+
+    return false;
+}
+
+function shortErr(error: unknown): string {
+    if (error instanceof Error) {
+        return error.name && error.name !== "Error"
+            ? `${error.name}: ${error.message}`
+            : error.message;
+    }
+    return extractMessage(error);
+}
+
+/**
+ * Try a single prompt attempt against the supplied body, with the existing
+ * single-suggestion retry layered inside (so "did you mean X?" still self-heals
+ * per attempt). Throws on failure; returns on success.
+ */
+async function attemptOnce(
     client: Client,
     args: PromptArgs,
-    options: PromptRetryOptions = {},
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+    callContext: string,
+    label: string,
 ): Promise<void> {
-    const timeoutMs = options.timeoutMs ?? 300_000;
-
     try {
-        await promptWithTimeout(client, args, timeoutMs, options.signal);
+        await promptWithTimeout(client, args, timeoutMs, signal);
+        return;
     } catch (error) {
+        // If non-retryable (abort, overflow, timeout), bubble up immediately.
+        // Don't even try suggestion retry — caller needs the original error.
+        if (isNonRetryable(error, signal)) throw error;
+
         const suggestion = parseModelSuggestion(error);
         if (!suggestion || !args.body.model) {
+            // No suggestion available — caller's fallback loop will decide
+            // whether to try the next chain entry.
             throw error;
         }
 
-        log("[model-suggestion-retry] Model not found, retrying with suggestion", {
+        log(`[${callContext}] ${label}: model not found, retrying with suggestion`, {
             original: `${suggestion.providerID}/${suggestion.modelID}`,
             suggested: suggestion.suggestion,
         });
@@ -154,7 +242,107 @@ export async function promptSyncWithModelSuggestionRetry(
                 },
             },
             timeoutMs,
+            signal,
+        );
+    }
+}
+
+/**
+ * Run an OpenCode subagent prompt with model fallback support.
+ *
+ * Attempts the configured primary model first (whatever `args.body.model` or
+ * the registered agent default resolves to), then iterates through
+ * `options.fallbackModels` if provided. Each attempt internally retries once on
+ * the SDK's "model not found, did you mean X?" suggestion. Aborts, timeouts,
+ * and context-overflow errors short-circuit the fallback loop because retrying
+ * the same prompt against another model won't help.
+ *
+ * Behavior with `fallbackModels` empty/undefined is identical to the pre-v0.18
+ * single-suggestion retry — fully backward-compatible for callers that haven't
+ * been updated to thread a chain.
+ */
+export async function promptSyncWithModelSuggestionRetry(
+    client: Client,
+    args: PromptArgs,
+    options: PromptRetryOptions = {},
+): Promise<void> {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const callContext = options.callContext ?? "subagent";
+    const fallbacks = options.fallbackModels ?? [];
+
+    // Attempt 0 = whatever the agent or explicit body.model resolves to.
+    // Subsequent attempts override body.model with each fallback in order.
+    const explicitPrimaryLabel =
+        args.body.model?.providerID && args.body.model.modelID
+            ? `${args.body.model.providerID}/${args.body.model.modelID}`
+            : "primary";
+
+    let lastError: unknown = null;
+
+    try {
+        await attemptOnce(
+            client,
+            args,
+            timeoutMs,
             options.signal,
+            callContext,
+            explicitPrimaryLabel,
+        );
+        return;
+    } catch (error) {
+        lastError = error;
+        if (isNonRetryable(error, options.signal)) throw error;
+
+        if (fallbacks.length === 0) {
+            // No fallbacks configured — behave exactly like legacy: propagate
+            // the original error (which may already have had its suggestion
+            // retry attempted inside `attemptOnce`).
+            throw error;
+        }
+
+        log(
+            `[${callContext}] primary (${explicitPrimaryLabel}) failed: ${shortErr(error)}; trying ${fallbacks.length} fallback(s)`,
         );
     }
+
+    // Iterate fallbacks.
+    for (let i = 0; i < fallbacks.length; i += 1) {
+        const parsed = parseProviderModel(fallbacks[i]);
+        if (!parsed) {
+            log(`[${callContext}] skipping invalid fallback spec: ${fallbacks[i]}`);
+            continue;
+        }
+
+        const label = `${parsed.providerID}/${parsed.modelID}`;
+        const attemptArgs: PromptArgs = {
+            ...args,
+            body: { ...args.body, model: parsed },
+        };
+
+        try {
+            await attemptOnce(client, attemptArgs, timeoutMs, options.signal, callContext, label);
+            log(
+                `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
+            );
+            return;
+        } catch (error) {
+            lastError = error;
+            if (isNonRetryable(error, options.signal)) throw error;
+
+            const remaining = fallbacks.length - i - 1;
+            if (remaining > 0) {
+                log(
+                    `[${callContext}] ${label} failed: ${shortErr(error)}; ${remaining} fallback(s) left`,
+                );
+            }
+        }
+    }
+
+    // All exhausted. Log the full chain and throw the last error so the
+    // caller's report (e.g. /ctx-dream tasks_json) still surfaces a real
+    // diagnostic.
+    log(
+        `[${callContext}] all models exhausted; tried: ${[explicitPrimaryLabel, ...fallbacks].join(", ")}; last error: ${shortErr(lastError)}`,
+    );
+    throw lastError ?? new Error("All fallback models failed");
 }

package/src/shared/models-dev-cache.ts

@@ -24,6 +24,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import { getCacheDir } from "./data-path";
+import { parseJsonc } from "./jsonc-parser";
 import { sessionLog } from "./logger";
 
 interface OpencodeClientLike {
@@ -195,19 +196,18 @@ function loadModelsDevMetadataFromFile(): Map<string, CachedModelMetadata> {
     try {
         const configPath = getOpencodeConfigPath();
         if (configPath && existsSync(configPath)) {
-            let raw = readFileSync(configPath, "utf-8");
-            // Strip JSONC single-line comments while preserving // inside strings.
-            raw = raw.replace(/"(?:[^"\\]|\\.)*"|\/\/.*$/gm, (match) =>
-                match.startsWith('"') ? match : "",
-            );
-            const config = JSON.parse(raw) as {
+            // Use the shared JSONC parser — handles `//` comments AND trailing commas.
+            // The previous custom regex stripped comments only; OpenCode's `opencode.jsonc`
+            // frequently contains trailing commas (valid JSONC, invalid JSON), which broke
+            // custom provider model-limit resolution silently. See issue #14 follow-up.
+            const config = parseJsonc<{
                 provider?: Record<
                     string,
                     {
                         models?: Record<string, { limit?: { context?: number; input?: number } }>;
                     }
                 >;
-            };
+            }>(readFileSync(configPath, "utf-8"));
 
             if (config.provider && typeof config.provider === "object") {
                 for (const [providerId, provider] of Object.entries(config.provider)) {

package/src/shared/resolve-fallbacks.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+
+import { DREAMER_AGENT } from "../agents/dreamer";
+import { HISTORIAN_AGENT } from "../agents/historian";
+import { SIDEKICK_AGENT } from "../agents/sidekick";
+import { parseProviderModel, resolveFallbackChain } from "./resolve-fallbacks";
+
+describe("resolveFallbackChain", () => {
+    test("returns builtin chain when user provides nothing", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, undefined);
+        // Builtin DREAMER_FALLBACK_CHAIN expands to multiple provider/model entries.
+        expect(chain.length).toBeGreaterThan(2);
+        // Every entry must be in "provider/model" form.
+        for (const entry of chain) {
+            expect(entry.indexOf("/")).toBeGreaterThan(0);
+        }
+    });
+
+    test("returns builtin chain for empty string", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, "");
+        expect(chain.length).toBeGreaterThan(0);
+    });
+
+    test("returns builtin chain for empty array", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, []);
+        expect(chain.length).toBeGreaterThan(0);
+    });
+
+    test("user-only when user provides valid fallback_models string", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, "anthropic/claude-sonnet-4-6");
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6"]);
+    });
+
+    test("user-only when user provides valid fallback_models array", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, [
+            "anthropic/claude-sonnet-4-6",
+            "google/gemini-3-flash",
+        ]);
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6", "google/gemini-3-flash"]);
+    });
+
+    test("dedupes user-provided list", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, [
+            "anthropic/claude-sonnet-4-6",
+            "anthropic/claude-sonnet-4-6",
+            "google/gemini-3-flash",
+        ]);
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6", "google/gemini-3-flash"]);
+    });
+
+    test("strips invalid 'provider/model' entries", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, [
+            "anthropic/claude-sonnet-4-6",
+            "no-slash-here",
+            "/leading-slash",
+            "trailing-slash/",
+            "",
+            "  ",
+        ]);
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6"]);
+    });
+
+    test("trims whitespace in user entries", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, [
+            "  anthropic/claude-sonnet-4-6  ",
+            "\tgoogle/gemini-3-flash\n",
+        ]);
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6", "google/gemini-3-flash"]);
+    });
+
+    test("returns empty array for unknown agent with no user fallbacks", () => {
+        const chain = resolveFallbackChain("unknown-agent", undefined);
+        expect(chain).toEqual([]);
+    });
+
+    test("returns user fallbacks for unknown agent when provided", () => {
+        const chain = resolveFallbackChain("unknown-agent", ["foo/bar"]);
+        expect(chain).toEqual(["foo/bar"]);
+    });
+
+    test("HISTORIAN_AGENT has builtin chain", () => {
+        const chain = resolveFallbackChain(HISTORIAN_AGENT, undefined);
+        expect(chain.length).toBeGreaterThan(0);
+    });
+
+    test("SIDEKICK_AGENT has builtin chain", () => {
+        const chain = resolveFallbackChain(SIDEKICK_AGENT, undefined);
+        expect(chain.length).toBeGreaterThan(0);
+    });
+
+    test("user-only policy: builtin not appended even if user set short list", () => {
+        const chain = resolveFallbackChain(DREAMER_AGENT, ["anthropic/claude-sonnet-4-6"]);
+        expect(chain).toEqual(["anthropic/claude-sonnet-4-6"]);
+        // Confirm length is exactly 1, not user+builtin
+        expect(chain.length).toBe(1);
+    });
+});
+
+describe("parseProviderModel", () => {
+    test("parses standard provider/model", () => {
+        expect(parseProviderModel("anthropic/claude-sonnet-4-6")).toEqual({
+            providerID: "anthropic",
+            modelID: "claude-sonnet-4-6",
+        });
+    });
+
+    test("handles model id with slashes (only splits on first slash)", () => {
+        expect(parseProviderModel("lemonade/GLM-4.7-Flash-GGUF/main")).toEqual({
+            providerID: "lemonade",
+            modelID: "GLM-4.7-Flash-GGUF/main",
+        });
+    });
+
+    test("trims whitespace", () => {
+        expect(parseProviderModel("  anthropic/claude-sonnet-4-6  ")).toEqual({
+            providerID: "anthropic",
+            modelID: "claude-sonnet-4-6",
+        });
+    });
+
+    test("returns null for no slash", () => {
+        expect(parseProviderModel("anthropic")).toBeNull();
+    });
+
+    test("returns null for leading slash", () => {
+        expect(parseProviderModel("/claude-sonnet-4-6")).toBeNull();
+    });
+
+    test("returns null for trailing slash", () => {
+        expect(parseProviderModel("anthropic/")).toBeNull();
+    });
+
+    test("returns null for empty string", () => {
+        expect(parseProviderModel("")).toBeNull();
+    });
+});

package/src/shared/resolve-fallbacks.ts

@@ -0,0 +1,76 @@
+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`).
+ *
+ * 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 (must contain a "/" with non-empty parts) are
+ * also dropped — 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));
+}
+
+function normalizeUserFallbacks(userFallbacks: readonly string[] | string | undefined): string[] {
+    if (!userFallbacks) return [];
+    if (typeof userFallbacks === "string") {
+        const trimmed = userFallbacks.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    return userFallbacks.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function isValidModelSpec(spec: string): boolean {
+    const slash = spec.indexOf("/");
+    return slash > 0 && slash < spec.length - 1;
+}
+
+function dedupe(list: string[]): string[] {
+    const seen = new Set<string>();
+    const out: string[] = [];
+    for (const item of list) {
+        if (seen.has(item)) continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+}
+
+/**
+ * Parse a "provider/modelID" string into the OpenCode `model` object shape.
+ * Returns null on invalid input.
+ *
+ * Note: only splits on the FIRST "/" — modelID can legitimately contain slashes
+ * (e.g. `lemonade/GLM-4.7-Flash-GGUF/main`).
+ */
+export function parseProviderModel(spec: string): { providerID: string; modelID: string } | null {
+    const slash = spec.indexOf("/");
+    if (slash < 1 || slash >= spec.length - 1) return null;
+    return {
+        providerID: spec.slice(0, slash).trim(),
+        modelID: spec.slice(slash + 1).trim(),
+    };
+}

package/src/shared/tag-transcript.ts

@@ -159,9 +159,10 @@ export function tagTranscript(
         const messageId = message.info.id;
 
         let textOrdinal = 0;
+        const parts = message.parts;
 
-        for (let partIndex = 0; partIndex < message.parts.length; partIndex += 1) {
-            const part = message.parts[partIndex];
+        for (let partIndex = 0; partIndex < parts.length; partIndex += 1) {
+            const part = parts[partIndex];
             if (part === undefined) continue;
 
             if (part.kind === "text") {

package/src/tui/index.tsx

@@ -453,6 +453,111 @@ function showStatusDialog(api: TuiPluginApi) {
     })
 }
 
+/**
+ * Register Magic Context command palette entries, preferring the v1.14.42+
+ * `keymap.registerLayer` API and falling back to the legacy
+ * `api.command.register` for older hosts.
+ *
+ * The `keymap.registerLayer` shape uses `name`/`title`/`run`/`namespace`
+ * (see `@opencode-ai/plugin/tui` types) and is what the host's own legacy
+ * command-shim translates into. Calling it directly skips the deprecation
+ * warning and works without depending on the (now-deprecated) `api.command`
+ * namespace existing at all.
+ *
+ * Version coverage:
+ *   1.14.0–1.14.41 — `api.command.register` only
+ *   1.14.42–1.14.43 — both surfaces broken (api.command removed, keymap landed
+ *                     but with bugs); plugins crash on init either way
+ *   1.14.44+        — `api.keymap.registerLayer` canonical, `api.command` shim
+ */
+function registerCommandPaletteEntries(api: TuiPluginApi): void {
+    type ApiAny = {
+        keymap?: {
+            registerLayer?: (layer: {
+                commands: Array<Record<string, unknown>>
+                bindings: Array<Record<string, unknown>>
+            }) => unknown
+        }
+        command?: {
+            register?: (cb: () => Array<Record<string, unknown>>) => unknown
+        }
+    }
+    const apiAny = api as unknown as ApiAny
+
+    if (typeof apiAny.keymap?.registerLayer === "function") {
+        // Audit Finding #2 hardening: even when registerLayer exists as a
+        // function, the underlying keymap implementation in OpenCode TUI
+        // 1.14.42-1.14.43 can throw at call time. Without the try-catch the
+        // `return` below would propagate the throw and the legacy
+        // `command.register` fallback path (~20 lines down) would be
+        // unreachable. The cost is one debug log on the rare broken-TUI
+        // build; the benefit is that older command.register-only TUIs
+        // running alongside a partially-broken keymap surface still get
+        // their command palette entries.
+        try {
+            apiAny.keymap.registerLayer({
+                commands: [
+                    {
+                        namespace: "palette",
+                        name: "magic-context.status",
+                        title: "Magic Context: Status",
+                        category: "Magic Context",
+                        run() {
+                            showStatusDialog(api)
+                        },
+                    },
+                    {
+                        namespace: "palette",
+                        name: "magic-context.recomp",
+                        title: "Magic Context: Recomp",
+                        category: "Magic Context",
+                        run() {
+                            showRecompDialog(api)
+                        },
+                    },
+                ],
+                bindings: [],
+            })
+            return
+        } catch (err) {
+            console.debug(
+                "[magic-context-tui] keymap.registerLayer threw; falling back to command.register",
+                err,
+            )
+            // Fall through to legacy registration.
+        }
+    }
+
+    if (typeof apiAny.command?.register === "function") {
+        apiAny.command.register(() => [
+            {
+                title: "Magic Context: Status",
+                value: "magic-context.status",
+                category: "Magic Context",
+                onSelect() {
+                    showStatusDialog(api)
+                },
+            },
+            {
+                title: "Magic Context: Recomp",
+                value: "magic-context.recomp",
+                category: "Magic Context",
+                onSelect() {
+                    showRecompDialog(api)
+                },
+            },
+        ])
+        return
+    }
+
+    // Neither API surface is present. The TUI host can still load — we only
+    // lose the command palette entry points. The sidebar (registered above
+    // via api.slots.register) remains visible. Status/Recomp are still
+    // reachable through the server-side `/ctx-status` and `/ctx-recomp`
+    // slash commands, which the server handler bridges to the TUI dialogs
+    // via RPC.
+}
+
 const tui: TuiPlugin = async (api, _options, meta) => {
     // Initialize RPC client for server communication
     const directory = api.state.path.directory ?? ""
@@ -465,24 +570,15 @@ const tui: TuiPlugin = async (api, _options, meta) => {
     // are registered server-side so there's only one /ctx-* registration).
     // The server detects TUI mode and sends dialog requests via RPC instead
     // of sendIgnoredMessage.
-    api.command.register(() => [
-        {
-            title: "Magic Context: Status",
-            value: "magic-context.status",
-            category: "Magic Context",
-            onSelect() {
-                showStatusDialog(api)
-            },
-        },
-        {
-            title: "Magic Context: Recomp",
-            value: "magic-context.recomp",
-            category: "Magic Context",
-            onSelect() {
-                showRecompDialog(api)
-            },
-        },
-    ])
+    //
+    // OpenCode 1.14.42 removed `api.command.register` entirely
+    // (anomalyco/opencode#26053). A later patch (1.14.44+) reinstated it as
+    // a deprecated shim that translates to `api.keymap.registerLayer`. To
+    // work across all hosts (1.14.0–1.14.41 with command-only, the broken
+    // 1.14.42–1.14.43, and 1.14.44+ where both exist), we prefer
+    // `api.keymap.registerLayer` and fall back to `api.command.register`
+    // only when keymap is missing.
+    registerCommandPaletteEntries(api)
 
     // Poll for server→TUI messages: toasts and dialog requests.
     // Single poller because consumeTuiMessages() is destructive (deletes consumed rows).