@cortexkit/opencode-magic-context 0.26.0 → 0.27.0

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

@@ -6,18 +6,36 @@ import { parseProviderModel } from "./resolve-fallbacks";
 
 type Client = ReturnType<typeof createOpencodeClient>;
 
-type PromptBody = {
+/** Max time to wait for the best-effort child-session abort HTTP call before
+ *  giving up on its response (the abort still proceeds server-side). Keeps a
+ *  wedged abort endpoint from masking the original timeout/abort error. */
+const ABORT_CALL_TIMEOUT_MS = 3000;
+
+export type PromptBody = {
     model?: { providerID: string; modelID: string };
     [key: string]: unknown;
 };
 
-type PromptArgs = {
+export type PromptArgs = {
     path: { id: string };
     body: PromptBody;
     signal?: AbortSignal;
     [key: string]: unknown;
 };
 
+export interface PromptAttemptInfo {
+    /** Human-readable model label used in logs ("primary" or "provider/model"). */
+    label: string;
+    /** Zero-based attempt index: 0 is primary, 1+ are fallback models. */
+    attemptIndex: number;
+    /** True for configured fallback models, false for the primary attempt. */
+    isFallback: boolean;
+    /** Total attempted models including the primary and all configured fallbacks. */
+    totalAttempts: number;
+    /** Explicit model override for this attempt, when one was supplied. */
+    model?: { providerID: string; modelID: string };
+}
+
 export interface PromptRetryOptions {
     timeoutMs?: number;
     /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
@@ -47,6 +65,29 @@ export interface PromptRetryOptions {
     callContext?: string;
 }
 
+export interface ValidatedPromptRetryOptions<TOutput, TValidated> extends PromptRetryOptions {
+    /**
+     * Fetch the output produced by the just-completed prompt attempt. This is
+     * intentionally caller-owned because OpenCode exposes results via session
+     * messages and each caller validates a different shape.
+     */
+    fetchOutput: (args: PromptArgs, attempt: PromptAttemptInfo) => Promise<TOutput>;
+    /**
+     * Validate and optionally transform the fetched output. Throw to reject this
+     * model's output and advance to the next configured fallback model.
+     */
+    validateOutput: (
+        output: TOutput,
+        attempt: PromptAttemptInfo,
+    ) => TValidated | Promise<TValidated>;
+}
+
+export interface ValidatedPromptRetryResult<TOutput, TValidated> {
+    output: TOutput;
+    validated: TValidated;
+    attempt: PromptAttemptInfo;
+}
+
 export interface ModelSuggestionInfo {
     providerID: string;
     modelID: string;
@@ -171,7 +212,15 @@ async function promptWithTimeout(
  */
 async function abortChildRun(client: Client, sessionId: string): Promise<void> {
     try {
-        await client.session.abort({ path: { id: sessionId } });
+        // Bound the abort call: it's best-effort cleanup, and if the abort
+        // endpoint itself stalls (the runner is wedged) an unbounded await here
+        // would hang the caller and MASK the original timeout/abort error that we
+        // still need to surface. Race against a short timer; the abort keeps
+        // running server-side regardless of whether we wait for its response.
+        await Promise.race([
+            client.session.abort({ path: { id: sessionId } }),
+            new Promise<void>((resolve) => setTimeout(resolve, ABORT_CALL_TIMEOUT_MS)),
+        ]);
     } catch (error) {
         log(`[model-retry] child session abort failed for ${sessionId}: ${String(error)}`);
     }
@@ -368,3 +417,132 @@ export async function promptSyncWithModelSuggestionRetry(
     );
     throw lastError ?? new Error("All fallback models failed");
 }
+
+async function attemptAndValidate<TOutput, TValidated>(
+    client: Client,
+    args: PromptArgs,
+    timeoutMs: number,
+    signal: AbortSignal | undefined,
+    callContext: string,
+    attempt: PromptAttemptInfo,
+    options: ValidatedPromptRetryOptions<TOutput, TValidated>,
+): Promise<ValidatedPromptRetryResult<TOutput, TValidated>> {
+    await attemptOnce(client, args, timeoutMs, signal, callContext, attempt.label);
+    const output = await options.fetchOutput(args, attempt);
+    const validated = await options.validateOutput(output, attempt);
+    return { output, validated, attempt };
+}
+
+/**
+ * Run a prompt with model fallback support, but accept an attempt only after the
+ * caller validates the model's actual output. This covers "empty success" cases
+ * where the provider/OpenCode prompt call completes successfully but the subagent
+ * produced no usable assistant text / JSON.
+ *
+ * The happy path is still one prompt + one caller-owned output fetch: callers
+ * should use the returned output instead of fetching messages a second time.
+ * Validation failures are retryable across configured fallback models. If every
+ * attempt produces invalid output (or otherwise fails retryably), the first
+ * failure is re-thrown so callers surface the original failure semantics.
+ */
+export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = TOutput>(
+    client: Client,
+    args: PromptArgs,
+    options: ValidatedPromptRetryOptions<TOutput, TValidated>,
+): Promise<ValidatedPromptRetryResult<TOutput, TValidated>> {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const callContext = options.callContext ?? "subagent";
+    const fallbacks = options.fallbackModels ?? [];
+
+    const explicitPrimaryLabel =
+        args.body.model?.providerID && args.body.model.modelID
+            ? `${args.body.model.providerID}/${args.body.model.modelID}`
+            : "primary";
+    const totalAttempts = fallbacks.length + 1;
+
+    let firstError: unknown = null;
+    let lastError: unknown = null;
+
+    try {
+        return await attemptAndValidate(
+            client,
+            args,
+            timeoutMs,
+            options.signal,
+            callContext,
+            {
+                label: explicitPrimaryLabel,
+                attemptIndex: 0,
+                isFallback: false,
+                totalAttempts,
+                model: args.body.model,
+            },
+            options,
+        );
+    } catch (error) {
+        firstError = error;
+        lastError = error;
+        if (isNonRetryable(error, options.signal)) throw error;
+
+        if (fallbacks.length === 0) {
+            throw error;
+        }
+
+        log(
+            `[${callContext}] primary (${explicitPrimaryLabel}) failed validation/prompt: ${shortErr(error)}; trying ${fallbacks.length} fallback(s)`,
+        );
+    }
+
+    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 },
+        };
+        const attempt: PromptAttemptInfo = {
+            label,
+            attemptIndex: i + 1,
+            isFallback: true,
+            totalAttempts,
+            model: parsed,
+        };
+
+        try {
+            const result = await attemptAndValidate(
+                client,
+                attemptArgs,
+                timeoutMs,
+                options.signal,
+                callContext,
+                attempt,
+                options,
+            );
+            log(
+                `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
+            );
+            return result;
+        } catch (error) {
+            if (firstError === null) firstError = error;
+            lastError = error;
+            if (isNonRetryable(error, options.signal)) throw error;
+
+            const remaining = fallbacks.length - i - 1;
+            if (remaining > 0) {
+                log(
+                    `[${callContext}] ${label} failed validation/prompt: ${shortErr(error)}; ${remaining} fallback(s) left`,
+                );
+            }
+        }
+    }
+
+    log(
+        `[${callContext}] all models exhausted; tried: ${[explicitPrimaryLabel, ...fallbacks].join(", ")}; original error: ${shortErr(firstError)}; last error: ${shortErr(lastError)}`,
+    );
+    throw firstError ?? lastError ?? new Error("All fallback models failed validation");
+}

package/src/shared/redaction.test.ts

@@ -0,0 +1,48 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, test } from "bun:test";
+
+import { hasShareabilitySensitiveText } from "./redaction";
+
+describe("hasShareabilitySensitiveText", () => {
+    test("safe project facts are shareable", () => {
+        expect(
+            hasShareabilitySensitiveText(
+                "The historian runs as a hidden subagent and never busts the prompt cache.",
+            ),
+        ).toBe(false);
+        expect(
+            hasShareabilitySensitiveText("Migration v45 adds the retrospective watermark column."),
+        ).toBe(false);
+    });
+
+    test("flags inline key:value / key=value secrets the keyed redactor misses in prose", () => {
+        expect(hasShareabilitySensitiveText("Set api_key: sk-live-abc123 in the env.")).toBe(true);
+        expect(hasShareabilitySensitiveText("password=hunter2 for the staging box")).toBe(true);
+        expect(hasShareabilitySensitiveText("client_secret = abcdef in the OAuth app")).toBe(true);
+    });
+
+    test("flags Windows forward-slash home (sanitizePathString only rewrites backslash form)", () => {
+        expect(hasShareabilitySensitiveText("logs are under C:/Users/ufuk/AppData/mc")).toBe(true);
+    });
+
+    test("flags ~/ rooted personal paths", () => {
+        expect(hasShareabilitySensitiveText("config lives at ~/.config/opencode/x.jsonc")).toBe(
+            true,
+        );
+    });
+
+    test("flags local / private endpoints", () => {
+        expect(hasShareabilitySensitiveText("embed endpoint is http://localhost:1234/v1")).toBe(
+            true,
+        );
+        expect(hasShareabilitySensitiveText("the box answers on 127.0.0.1:8080")).toBe(true);
+        expect(hasShareabilitySensitiveText("LAN host 192.168.1.42 runs the model")).toBe(true);
+        expect(hasShareabilitySensitiveText("internal 10.0.0.5 endpoint")).toBe(true);
+    });
+
+    test("a public IP / port alone is not flagged by the private-range rules", () => {
+        // 8.8.8.8 is public; no private-range or localhost pattern should match.
+        expect(hasShareabilitySensitiveText("DNS resolver at 8.8.8.8")).toBe(false);
+    });
+});

package/src/shared/redaction.ts

@@ -0,0 +1,240 @@
+import { homedir, userInfo } from "node:os";
+
+function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Whole-segment match: the key (or its components when split on common
+// separators) must BE one of these words, not merely contain them as a
+// substring. Bare substring matching wrongly redacts benign fields like
+// `pin_key_files`, `token_budget`, and `injection_budget_tokens`.
+const SECRET_WORDS = [
+    "key",
+    "token",
+    "secret",
+    "password",
+    "auth",
+    "authorization",
+    "bearer",
+    "credential",
+];
+const SECRET_SEGMENT_PATTERN = new RegExp(
+    `^(?:${SECRET_WORDS.map((w) => `${w}s?`).join("|")})$`,
+    "i",
+);
+const TRAILING_DESCRIPTORS = new Set(["id", "ids", "value", "values", "header", "headers"]);
+
+function redactionTypeForKey(key: string): string {
+    const normalized = key
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/g, "_");
+    const suffix = normalized.split(".").filter(Boolean).at(-1) ?? normalized;
+    return suffix || "secret";
+}
+
+const SECRET_QUALIFIERS = new Set([
+    "api",
+    "access",
+    "private",
+    "client",
+    "auth",
+    "authorization",
+    "secret",
+    "bearer",
+    "session",
+    "refresh",
+    "service",
+    "x",
+    "openai",
+    "anthropic",
+    "google",
+    "github",
+    "huggingface",
+    "aws",
+    "azure",
+]);
+
+export function isSecretKey(key: string): boolean {
+    const segments = key
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .split(/[._-]+/)
+        .filter(Boolean);
+    if (segments.length === 0) return false;
+
+    if (segments.length === 1) {
+        const first = segments[0];
+        return Boolean(first && SECRET_SEGMENT_PATTERN.test(first));
+    }
+
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (!seg || !SECRET_SEGMENT_PATTERN.test(seg)) continue;
+
+        let trailingOk = true;
+        for (let j = i + 1; j < segments.length; j++) {
+            const tail = segments[j];
+            if (!tail) continue;
+            if (TRAILING_DESCRIPTORS.has(tail)) continue;
+            if (SECRET_SEGMENT_PATTERN.test(tail)) continue;
+            trailingOk = false;
+            break;
+        }
+        if (!trailingOk) continue;
+
+        for (let k = i - 1; k >= 0; k--) {
+            const lead = segments[k];
+            if (lead && SECRET_QUALIFIERS.has(lead)) return true;
+        }
+    }
+    return false;
+}
+
+export function sanitizePathString(value: string): string {
+    const home = homedir();
+    const username = userInfo().username;
+    let sanitized = value;
+    if (home) {
+        sanitized = sanitized.replace(new RegExp(escapeRegex(home), "g"), "~");
+    }
+    sanitized = sanitized.replace(/\/Users\/[^/]+\//g, "/Users/<USER>/");
+    sanitized = sanitized.replace(/\/home\/[^/]+\//g, "/home/<USER>/");
+    sanitized = sanitized.replace(/C:\\Users\\[^\\]+\\/g, "C:\\Users\\<USER>\\");
+    if (username) {
+        sanitized = sanitized.replace(new RegExp(escapeRegex(username), "g"), "<USER>");
+    }
+    return sanitized;
+}
+
+const SECRET_TEXT_PATTERNS: Array<{
+    pattern: RegExp;
+    replacement: string | ((match: string, ...groups: string[]) => string);
+}> = [
+    {
+        pattern: /\bsk-ant-(?:api03-)?[A-Za-z0-9_-]{32,}/g,
+        replacement: "<ANTHROPIC_API_KEY_REDACTED>",
+    },
+    {
+        pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g,
+        replacement: "<OPENAI_API_KEY_REDACTED>",
+    },
+    {
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+        replacement: "<GITHUB_PAT_REDACTED>",
+    },
+    {
+        pattern: /\b(?:gh[opsu]|ghr)_[A-Za-z0-9]{30,}/g,
+        replacement: "<GITHUB_TOKEN_REDACTED>",
+    },
+    {
+        pattern: /\bhf_[A-Za-z0-9]{30,}/g,
+        replacement: "<HUGGINGFACE_TOKEN_REDACTED>",
+    },
+    {
+        pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+        replacement: "<AWS_ACCESS_KEY_ID_REDACTED>",
+    },
+    {
+        pattern: /\bxox[abprsuvc]-[A-Za-z0-9-]{10,}/g,
+        replacement: "<SLACK_TOKEN_REDACTED>",
+    },
+    {
+        pattern: /\bAIza[A-Za-z0-9_-]{35}\b/g,
+        replacement: "<GOOGLE_API_KEY_REDACTED>",
+    },
+    {
+        pattern: /\b(Authorization\s*:\s*Bearer\s+)([A-Za-z0-9._~+/=-]{8,})/gi,
+        replacement: (_full: string, prefix: string) => `${prefix}<REDACTED:bearer>`,
+    },
+    {
+        pattern: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
+        replacement: "<JWT_REDACTED>",
+    },
+    {
+        pattern:
+            /(["'])([^"']*(?:key|token|secret|password|auth|bearer|credential)[^"']*)\1(\s*:\s*)(["'])([^"']*)\4/gi,
+        replacement: (
+            _full: string,
+            quote: string,
+            key: string,
+            separator: string,
+            valueQuote: string,
+        ) =>
+            `${quote}${key}${quote}${separator}${valueQuote}<REDACTED:${redactionTypeForKey(key)}>${valueQuote}`,
+    },
+    {
+        pattern:
+            /\b([A-Za-z0-9_.-]*(?:key|token|secret|password|auth|bearer|credential)[A-Za-z0-9_.-]*)\s*=\s*([^\s'"`]+)/gi,
+        replacement: (_full: string, key: string) =>
+            `${key}=<REDACTED:${redactionTypeForKey(key)}>`,
+    },
+];
+
+export function redactSecretText(value: string): string {
+    let redacted = value;
+    for (const { pattern, replacement } of SECRET_TEXT_PATTERNS) {
+        if (typeof replacement === "string") {
+            redacted = redacted.replace(pattern, replacement);
+        } else {
+            redacted = redacted.replace(
+                pattern,
+                replacement as (match: string, ...groups: string[]) => string,
+            );
+        }
+    }
+    return redacted;
+}
+
+export function sanitizeDiagnosticText(value: string): string {
+    return redactSecretText(sanitizePathString(value));
+}
+
+// Extra shareability-only signals — patterns that mark text as unsafe to share
+// with teammates but that the diagnostic sanitizer (tuned for secret/path
+// REDACTION, not share-gating) does not rewrite. Kept here, NOT in
+// sanitizeDiagnosticText, so diagnostic redaction output is unchanged.
+const SHAREABILITY_SENSITIVE_PATTERNS: RegExp[] = [
+    // Windows user home, forward- OR back-slash (sanitizePathString only rewrites
+    // the backslash form).
+    /\bC:\/Users\/[^/\s]+/i,
+    // A `~`-rooted home path (personal/local).
+    /(?:^|\s)~\/[^\s]+/,
+    // Inline `key: value` / `key=value` secrets the keyed redactor misses in free
+    // text (it keys on config OBJECT keys, not prose).
+    /\b(?:api[_-]?key|secret|token|password|passwd|pwd|client[_-]?secret|access[_-]?key)\b\s*[:=]\s*\S+/i,
+    // Local / private endpoints — environment-specific, not a shared truth.
+    /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?\b/i,
+    /\b(?:10|127)\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/,
+    /\b192\.168\.\d{1,3}\.\d{1,3}\b/,
+    /\b172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}\b/,
+];
+
+export function hasShareabilitySensitiveText(text: string): boolean {
+    try {
+        if (sanitizeDiagnosticText(text) !== text) return true;
+        return SHAREABILITY_SENSITIVE_PATTERNS.some((pattern) => pattern.test(text));
+    } catch {
+        return true;
+    }
+}
+
+export function sanitizeConfigValue(value: unknown, keyPath: string[] = []): unknown {
+    const key = keyPath.at(-1) ?? "";
+    if (key && isSecretKey(key)) {
+        return `<REDACTED:${redactionTypeForKey(key)}>`;
+    }
+    if (typeof value === "string") return sanitizeDiagnosticText(value);
+    if (Array.isArray(value)) {
+        return value.map((entry, index) => sanitizeConfigValue(entry, [...keyPath, String(index)]));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(
+            Object.entries(value).map(([entryKey, entry]) => [
+                entryKey,
+                sanitizeConfigValue(entry, [...keyPath, entryKey]),
+            ]),
+        );
+    }
+    return value;
+}

package/src/shared/resolve-fallbacks.ts

@@ -64,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 });
+    });
+});