feat(opencode): native opencode integration — /mcpctl switcher, live project switching, footer indicator

Adds `mcpctl config opencode`, two opencode plugins and an `opencode` skills
sync target, so an mcpctl project can be switched from inside opencode's TUI
and the active one is visible at a glance.

Unlike `config claude` / `config prime-agent`, this writes NO MCP entry into
the host's config. opencode exposes an HTTP API for its own MCP registry
(`POST /mcp`), so the project is mounted through the running app:

  - the token stays in ~/.mcpctl/opencode-state.json (0600) instead of a
    mode-0644 opencode.json users paste into bug reports;
  - switching projects takes effect on the next turn, with no restart.

Inside opencode:
  /mcpctl         filterable project picker; switches live
  /mcpctl-status  active project, mount state, gateway URL
  /mcpctl-skills  re-sync this project's skills
  plus a `mcpctl:<project>` indicator in the prompt footer, next to the model
  name and one line above the token counter.

Design notes:
  - the MCP server is registered under a constant name, so tools keep a stable
    `mcpctl_*` prefix and opencode's per-request tool resolution shows the new
    project's tools by itself — no "your old tool names are dead" message to
    the model, unlike the pi extension;
  - an unchanged mount is never re-registered: mcp.add rebuilds the connection
    and mcplocal binds a gated project's unlocked state to that connection's
    mcp-session-id, so re-adding would re-lock a project begin_session had just
    opened;
  - the server plugin does not mount during setup — setup runs before the
    server accepts connections and mcp.add calls back into it, which hangs
    opencode on a blank screen before the TUI draws;
  - the switcher shells out to this CLI (--skip-plugin --skip-marker) so token
    minting, state and skills stay in one place;
  - no usable credential aborts non-zero with the state file untouched, so a
    failed switch leaves the previous project working rather than swapping it
    for a mount that 401s.

`skills sync --agent opencode` installs into ~/.config/opencode/skill (XDG
aware) with the same shared-tree semantics as pi and prime-agent. The
credential plumbing shared with `config prime-agent` is lifted to one place and
parameterised by agent rather than copied.

The plugin sources are embedded in the CLI (generated, freshness-tested) so an
installed binary with no source tree can provision them, and are typechecked
against the real @opencode-ai/plugin types.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BVwuCjuMoA13gmzYEfcrNP

src/cli/tests/commands/config-opencode.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createConfigCommand } from '../../src/commands/config.js';
+import type { ApiClient } from '../../src/api-client.js';
+
+interface ClientCalls { posts: Array<{ path: string; body?: unknown }> }
+
+/**
+ * @param tokens what `GET /api/v1/mcptokens` reports as existing for a project
+ */
+function mockClient(calls: ClientCalls, tokens: unknown[] = []): ApiClient {
+  return {
+    get: vi.fn(async (path: string) => {
+      if (path.startsWith('/api/v1/mcptokens')) return tokens;
+      if (path.endsWith('/skills/visible')) return [];
+      return {};
+    }),
+    post: vi.fn(async (path: string, body?: unknown) => {
+      calls.posts.push({ path, body });
+      if (path === '/api/v1/mcptokens') return { token: 'mcpctl_pat_MINTED0000000000' };
+      return {};
+    }),
+    put: vi.fn(async () => ({})),
+    delete: vi.fn(async () => {}),
+  } as unknown as ApiClient;
+}
+
+describe('config opencode', () => {
+  let output: string[];
+  let tmpDir: string;
+  let ocDir: string;
+  let calls: ClientCalls;
+  const log = (...args: string[]): void => { output.push(args.join(' ')); };
+  const statePath = (): string => join(ocDir, 'mcpctl-state.json');
+
+  /** Pre-existing state, as a machine that has already run this command has. */
+  function seedState(value: unknown): void {
+    mkdirSync(ocDir, { recursive: true });
+    writeFileSync(statePath(), JSON.stringify(value));
+  }
+
+  function command(client: ApiClient) {
+    return createConfigCommand(
+      { configDeps: { configDir: tmpDir }, log },
+      { client, credentialsDeps: { configDir: tmpDir }, log },
+    );
+  }
+
+  beforeEach(() => {
+    output = [];
+    calls = { posts: [] };
+    tmpDir = mkdtempSync(join(tmpdir(), 'mcpctl-config-oc-'));
+    ocDir = join(tmpDir, 'opencode');
+  });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
+
+  it('requires a project', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--opencode-dir', ocDir, '--skip-skills'], { from: 'user' });
+    expect(output.join('\n')).toContain('--project is required');
+    expect(existsSync(statePath())).toBe(false);
+  });
+
+  it('installs both plugins, registers the TUI one and writes the state file', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'docmost', '--opencode-dir', ocDir,
+        '--gateway-url', 'https://gw.example', '--token', 'mcpctl_pat_SUPPLIED000000',
+        '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+
+    expect(existsSync(join(ocDir, 'plugin', 'mcpctl.ts'))).toBe(true);
+    expect(existsSync(join(ocDir, 'mcpctl', 'mcpctl-tui.tsx'))).toBe(true);
+
+    const tui = JSON.parse(readFileSync(join(ocDir, 'tui.json'), 'utf-8'));
+    expect(tui.plugin).toEqual([join(ocDir, 'mcpctl', 'mcpctl-tui.tsx')]);
+
+    const state = JSON.parse(readFileSync(statePath(), 'utf-8'));
+    expect(state).toEqual({
+      project: 'docmost',
+      gatewayUrl: 'https://gw.example',
+      tokens: { docmost: 'mcpctl_pat_SUPPLIED000000' },
+    });
+  });
+
+  it('strips a trailing slash from the gateway URL so the mount URL stays canonical', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--gateway-url', 'https://gw.example/',
+        '--token', 't', '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(JSON.parse(readFileSync(statePath(), 'utf-8')).gatewayUrl).toBe('https://gw.example');
+  });
+
+  it('--token never mints', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--token', 't',
+        '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(calls.posts.filter((c) => c.path === '/api/v1/mcptokens')).toHaveLength(0);
+  });
+
+  it('mints a uniquely-named opencode token when none is stored', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    const mint = calls.posts.find((c) => c.path === '/api/v1/mcptokens');
+    expect(mint).toBeDefined();
+    // A fixed name could only ever be minted once per project: McpToken is
+    // unique on (name, projectId) and revoke is a soft delete.
+    expect((mint?.body as { name: string }).name).toMatch(/^opencode-/);
+    expect(JSON.parse(readFileSync(statePath(), 'utf-8')).tokens.p).toBe('mcpctl_pat_MINTED0000000000');
+  });
+
+  it('reuses a stored token that the server still reports as active', async () => {
+    // 16-char prefix is what the server exposes; the secret is never re-sent.
+    const stored = 'mcpctl_pat_STORED000000000';
+    seedState({ project: 'p', gatewayUrl: 'https://gw', tokens: { p: stored } });
+    const client = mockClient(calls, [{ id: '1', name: 'opencode-x', status: 'active', tokenPrefix: stored.slice(0, 16) }]);
+    await command(client).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(calls.posts.filter((c) => c.path === '/api/v1/mcptokens')).toHaveLength(0);
+    expect(output.join('\n')).toContain('already present');
+  });
+
+  it('re-mints when the stored token has been revoked server-side', async () => {
+    const stored = 'mcpctl_pat_REVOKED00000000';
+    seedState({ project: 'p', gatewayUrl: 'https://gw', tokens: { p: stored } });
+    const client = mockClient(calls, [{ id: '1', name: 'opencode-x', status: 'revoked', tokenPrefix: stored.slice(0, 16) }]);
+    await command(client).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(calls.posts.filter((c) => c.path === '/api/v1/mcptokens')).toHaveLength(1);
+    expect(JSON.parse(readFileSync(statePath(), 'utf-8')).tokens.p).toBe('mcpctl_pat_MINTED0000000000');
+  });
+
+  it('leaves the previous project mounted when no credential can be provisioned', async () => {
+    // A switch with no usable credential is a FAILURE: exiting 0 here would
+    // have the /mcpctl switcher report success over a project with no tools.
+    seedState({ project: 'old', gatewayUrl: 'https://gw', tokens: { old: 'tok-old' } });
+    const client = {
+      get: vi.fn(async () => []),
+      post: vi.fn(async () => ({})), // mint returns no token
+      put: vi.fn(async () => ({})),
+      delete: vi.fn(async () => {}),
+    } as unknown as ApiClient;
+    const prevExit = process.exitCode;
+    await command(client).parseAsync(
+      ['opencode', '--project', 'new', '--opencode-dir', ocDir, '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(process.exitCode).toBe(1);
+    process.exitCode = prevExit;
+    expect(JSON.parse(readFileSync(statePath(), 'utf-8')).project).toBe('old');
+    expect(output.join('\n')).toContain('Aborted');
+  });
+
+  it('--skip-plugin updates state without touching the loaded plugin files', async () => {
+    // This is the path the /mcpctl switcher takes: rewriting the very file
+    // opencode has already loaded buys nothing.
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--token', 't',
+        '--skip-plugin', '--skip-skills', '--skip-marker'],
+      { from: 'user' });
+    expect(existsSync(join(ocDir, 'plugin', 'mcpctl.ts'))).toBe(false);
+    expect(existsSync(join(ocDir, 'tui.json'))).toBe(false);
+    expect(JSON.parse(readFileSync(statePath(), 'utf-8')).project).toBe('p');
+  });
+
+  it('--dry-run reports the plan and writes nothing', async () => {
+    await command(mockClient(calls)).parseAsync(
+      ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--dry-run'], { from: 'user' });
+    const plan = JSON.parse(output.join('\n'));
+    expect(plan.opencode.mcpUrl).toContain('/projects/p/mcp');
+    expect(plan.opencode.statePath).toBe(statePath());
+    expect(existsSync(ocDir)).toBe(false);
+    expect(calls.posts).toHaveLength(0);
+  });
+
+  it('--skip-marker leaves the working directory unscoped', async () => {
+    const cwd = process.cwd();
+    const workDir = join(tmpDir, 'work');
+    mkdirSync(workDir, { recursive: true });
+    process.chdir(workDir);
+    try {
+      await command(mockClient(calls)).parseAsync(
+        ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--token', 't',
+          '--skip-skills', '--skip-marker'],
+        { from: 'user' });
+      expect(existsSync(join(workDir, '.mcpctl-project'))).toBe(false);
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+
+  it('writes a .mcpctl-project marker by default', async () => {
+    const cwd = process.cwd();
+    const workDir = join(tmpDir, 'work2');
+    mkdirSync(workDir, { recursive: true });
+    process.chdir(workDir);
+    try {
+      await command(mockClient(calls)).parseAsync(
+        ['opencode', '--project', 'p', '--opencode-dir', ocDir, '--token', 't', '--skip-skills'],
+        { from: 'user' });
+      expect(readFileSync(join(workDir, '.mcpctl-project'), 'utf-8')).toContain('p');
+    } finally {
+      process.chdir(cwd);
+    }
+  });
+});

src/cli/tests/config/opencode-extension-embed.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  OPENCODE_SERVER_PLUGIN_SOURCE,
+  OPENCODE_TUI_PLUGIN_SOURCE,
+  OPENCODE_SERVER_PLUGIN_FILENAME,
+  OPENCODE_TUI_PLUGIN_FILENAME,
+} from '../../src/config/opencode-extension.js';
+
+/**
+ * `mcpctl config opencode` installs the *embedded* copy of the plugins, not the
+ * files in src/opencode-ext/. Editing the sources without re-running the
+ * generator therefore ships stale code to users while the repo looks correct —
+ * and the embedded copy is the one thing no typecheck covers. Same guarantee
+ * the completions check gives.
+ */
+const repoRoot = join(import.meta.dirname, '..', '..', '..', '..');
+const extDir = join(repoRoot, 'src', 'opencode-ext');
+
+describe('embedded opencode plugins', () => {
+  it('match the sources in src/opencode-ext (re-run scripts/generate-opencode-extension.ts)', () => {
+    expect(OPENCODE_SERVER_PLUGIN_SOURCE, 'server plugin is stale — regenerate the embed')
+      .toBe(readFileSync(join(extDir, 'mcpctl-opencode.ts'), 'utf-8'));
+    expect(OPENCODE_TUI_PLUGIN_SOURCE, 'TUI plugin is stale — regenerate the embed')
+      .toBe(readFileSync(join(extDir, 'mcpctl-opencode-tui.tsx'), 'utf-8'));
+  });
+
+  it('install under names opencode can actually load', () => {
+    // The server plugin is auto-discovered from plugin/*.ts; the TUI plugin is
+    // referenced by path from tui.json and must stay .tsx for its JSX to be
+    // transpiled.
+    expect(OPENCODE_SERVER_PLUGIN_FILENAME).toBe('mcpctl.ts');
+    expect(OPENCODE_TUI_PLUGIN_FILENAME).toBe('mcpctl-tui.tsx');
+  });
+
+  it('are self-contained — the installed files have no mcpctl imports to resolve', () => {
+    for (const src of [OPENCODE_SERVER_PLUGIN_SOURCE, OPENCODE_TUI_PLUGIN_SOURCE]) {
+      expect(src).not.toMatch(/from '@mcpctl\//);
+      expect(src).not.toMatch(/from '\.\.\//);
+    }
+  });
+
+  it('keep the JSX pragma the TUI plugin needs to render its indicator', () => {
+    expect(OPENCODE_TUI_PLUGIN_SOURCE.startsWith('/** @jsxImportSource @opentui/solid */')).toBe(true);
+  });
+
+  it('agree on the MCP server name, so a switch re-points one mount instead of stacking two', () => {
+    for (const src of [OPENCODE_SERVER_PLUGIN_SOURCE, OPENCODE_TUI_PLUGIN_SOURCE]) {
+      expect(src).toContain("const SERVER_NAME = 'mcpctl'");
+    }
+  });
+
+  it('agree on the state file both read', () => {
+    for (const src of [OPENCODE_SERVER_PLUGIN_SOURCE, OPENCODE_TUI_PLUGIN_SOURCE]) {
+      expect(src).toContain("join(homedir(), '.mcpctl', 'opencode-state.json')");
+    }
+  });
+
+  it('spawn the CLI without a shell, so a project name is never interpolated into a command string', () => {
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).toContain("execFile('mcpctl', args");
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).not.toMatch(/\bexecSync\s*\(/);
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).not.toMatch(/\bexec\(`/);
+  });
+
+  it('sync skills into opencode’s own tree, never Claude’s', () => {
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).toContain("'--agent', 'opencode'");
+  });
+
+  it('switch without rewriting the plugin file opencode has already loaded', () => {
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).toContain("'--skip-plugin'");
+    expect(OPENCODE_TUI_PLUGIN_SOURCE).toContain("'--skip-marker'");
+  });
+});

src/cli/tests/config/opencode-project-order.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { orderProjects, indicatorLabel } from '../../../opencode-ext/mcpctl-opencode-tui.js';
+
+/**
+ * opencode's select dialog filters as you type, so the picker only has to get
+ * the *order* right — the active project first, because "the one I am on" is
+ * the most likely pick and real installs run to hundreds of projects (smoke-test
+ * leftovers included).
+ */
+const PROJECTS = [
+  { name: 'smoke-proj-none-mohimh46' },
+  { name: 'homeautomation', description: 'house' },
+  { name: 'docmost' },
+  { name: 'copy-homeautomation' },
+  { name: 'labctl' },
+  { name: 'sre' },
+];
+
+describe('orderProjects', () => {
+  it('puts the active project first, then sorts alphabetically', () => {
+    expect(orderProjects(PROJECTS, 'labctl').map((p) => p.name)).toEqual([
+      'labctl',
+      'copy-homeautomation',
+      'docmost',
+      'homeautomation',
+      'smoke-proj-none-mohimh46',
+      'sre',
+    ]);
+  });
+
+  it('sorts alphabetically when nothing is active', () => {
+    expect(orderProjects(PROJECTS, null).map((p) => p.name)).toEqual([
+      'copy-homeautomation',
+      'docmost',
+      'homeautomation',
+      'labctl',
+      'smoke-proj-none-mohimh46',
+      'sre',
+    ]);
+  });
+
+  it('never drops or duplicates a project', () => {
+    expect(orderProjects(PROJECTS, 'sre')).toHaveLength(PROJECTS.length);
+    expect(orderProjects(PROJECTS, 'not-a-project')).toHaveLength(PROJECTS.length);
+  });
+
+  it('does not mutate the caller’s list', () => {
+    const input = [...PROJECTS];
+    orderProjects(input, 'sre');
+    expect(input.map((p) => p.name)).toEqual(PROJECTS.map((p) => p.name));
+  });
+
+  it('keeps descriptions, which the dialog shows under each row', () => {
+    expect(orderProjects(PROJECTS, null).find((p) => p.name === 'homeautomation')?.description).toBe('house');
+  });
+});
+
+describe('indicatorLabel', () => {
+  it('names the active project', () => {
+    expect(indicatorLabel('docmost')).toBe('mcpctl:docmost');
+  });
+
+  it('says so when there is none, rather than rendering a bare prefix', () => {
+    expect(indicatorLabel(null)).toBe('mcpctl:none');
+    expect(indicatorLabel('')).toBe('mcpctl:none');
+  });
+});

src/cli/tests/utils/opencode-settings.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  opencodeConfigDir,
+  opencodeSkillsDir,
+  withOpencodeDir,
+  installOpencodePlugins,
+  registerOpencodeTuiPlugin,
+  readOpencodeState,
+  writeOpencodeState,
+  storedToken,
+} from '../../src/utils/opencode-settings.js';
+import {
+  OPENCODE_SERVER_PLUGIN_FILENAME,
+  OPENCODE_TUI_PLUGIN_FILENAME,
+} from '../../src/config/opencode-extension.js';
+
+describe('opencodeConfigDir', () => {
+  it('defaults to ~/.config/opencode', () => {
+    expect(opencodeConfigDir({}, '/home/u')).toBe('/home/u/.config/opencode');
+  });
+
+  it('honours XDG_CONFIG_HOME — provisioning ~/.config would be invisible to opencode', () => {
+    expect(opencodeConfigDir({ XDG_CONFIG_HOME: '/xdg' }, '/home/u')).toBe('/xdg/opencode');
+  });
+
+  it('ignores an empty XDG_CONFIG_HOME rather than resolving against ""', () => {
+    expect(opencodeConfigDir({ XDG_CONFIG_HOME: '' }, '/home/u')).toBe('/home/u/.config/opencode');
+  });
+
+  it('puts skills where opencode looks for them', () => {
+    expect(opencodeSkillsDir({}, '/home/u')).toBe('/home/u/.config/opencode/skill');
+  });
+});
+
+describe('installOpencodePlugins', () => {
+  let dir: string;
+  beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'mcpctl-oc-install-')); });
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  it('writes the server plugin where opencode auto-discovers it and the TUI plugin beside it', async () => {
+    const written = await installOpencodePlugins(dir);
+    const paths = withOpencodeDir(dir);
+    expect(written).toEqual([paths.serverPluginPath(), paths.tuiPluginPath()]);
+    expect(existsSync(join(dir, 'plugin', OPENCODE_SERVER_PLUGIN_FILENAME))).toBe(true);
+    expect(existsSync(join(dir, 'mcpctl', OPENCODE_TUI_PLUGIN_FILENAME))).toBe(true);
+  });
+
+  it('keeps the .tsx extension — opencode transpiles the TUI plugin by extension', async () => {
+    await installOpencodePlugins(dir);
+    expect(withOpencodeDir(dir).tuiPluginPath().endsWith('.tsx')).toBe(true);
+  });
+
+  it('is idempotent (re-running overwrites in place)', async () => {
+    await installOpencodePlugins(dir);
+    const first = readFileSync(withOpencodeDir(dir).serverPluginPath(), 'utf-8');
+    await installOpencodePlugins(dir);
+    expect(readFileSync(withOpencodeDir(dir).serverPluginPath(), 'utf-8')).toBe(first);
+  });
+});
+
+describe('registerOpencodeTuiPlugin', () => {
+  let dir: string;
+  let tuiJson: string;
+  const pluginPath = '/cfg/opencode/mcpctl/mcpctl-tui.tsx';
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mcpctl-oc-tui-'));
+    tuiJson = join(dir, 'tui.json');
+  });
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  it('creates tui.json with the plugin and a $schema', async () => {
+    expect(await registerOpencodeTuiPlugin(tuiJson, pluginPath)).toEqual({ added: true });
+    const parsed = JSON.parse(readFileSync(tuiJson, 'utf-8'));
+    expect(parsed.plugin).toEqual([pluginPath]);
+    expect(parsed.$schema).toBe('https://opencode.ai/tui.json');
+  });
+
+  it('is idempotent and leaves the file untouched on a no-op run', async () => {
+    await registerOpencodeTuiPlugin(tuiJson, pluginPath);
+    const before = readFileSync(tuiJson, 'utf-8');
+    expect(await registerOpencodeTuiPlugin(tuiJson, pluginPath)).toEqual({ added: false });
+    expect(readFileSync(tuiJson, 'utf-8')).toBe(before);
+  });
+
+  it('preserves other TUI plugins and unrelated keys', async () => {
+    writeFileSync(tuiJson, JSON.stringify({ plugin: ['opencode-tui-utils'], theme: 'nord' }));
+    await registerOpencodeTuiPlugin(tuiJson, pluginPath);
+    const parsed = JSON.parse(readFileSync(tuiJson, 'utf-8'));
+    expect(parsed.plugin).toEqual(['opencode-tui-utils', pluginPath]);
+    expect(parsed.theme).toBe('nord');
+  });
+
+  it('drops a stale entry for an older install location of our own plugin', async () => {
+    // Left behind, opencode fails to load a file that no longer exists on
+    // every start.
+    writeFileSync(tuiJson, JSON.stringify({ plugin: ['/old/place/mcpctl-tui.tsx', 'other-plugin'] }));
+    await registerOpencodeTuiPlugin(tuiJson, pluginPath);
+    expect(JSON.parse(readFileSync(tuiJson, 'utf-8')).plugin).toEqual(['other-plugin', pluginPath]);
+  });
+
+  it('refuses to overwrite a corrupt tui.json instead of dropping the user’s plugins', async () => {
+    writeFileSync(tuiJson, '{ this is not json');
+    await expect(registerOpencodeTuiPlugin(tuiJson, pluginPath)).rejects.toThrow(/not valid JSON/);
+    expect(readFileSync(tuiJson, 'utf-8')).toBe('{ this is not json');
+  });
+
+  it('treats an empty file as a fresh start', async () => {
+    writeFileSync(tuiJson, '   \n');
+    expect(await registerOpencodeTuiPlugin(tuiJson, pluginPath)).toEqual({ added: true });
+  });
+});
+
+describe('opencode state file', () => {
+  let dir: string;
+  let statePath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'mcpctl-oc-state-'));
+    statePath = join(dir, 'nested', 'opencode-state.json');
+  });
+  afterEach(() => { rmSync(dir, { recursive: true, force: true }); });
+
+  it('creates the directory and writes project + gateway + token', async () => {
+    await writeOpencodeState({ project: 'docmost', gatewayUrl: 'https://gw', token: 'mcpctl_pat_a' }, statePath);
+    expect(await readOpencodeState(statePath)).toEqual({
+      project: 'docmost',
+      gatewayUrl: 'https://gw',
+      tokens: { docmost: 'mcpctl_pat_a' },
+    });
+  });
+
+  it('is written 0600 — it holds bearer tokens', async () => {
+    await writeOpencodeState({ project: 'p', gatewayUrl: 'https://gw', token: 't' }, statePath);
+    expect(statSync(statePath).mode & 0o777).toBe(0o600);
+  });
+
+  it('keeps other projects’ tokens, so switching back needs no new mint', async () => {
+    await writeOpencodeState({ project: 'a', gatewayUrl: 'https://gw', token: 'tok-a' }, statePath);
+    await writeOpencodeState({ project: 'b', gatewayUrl: 'https://gw', token: 'tok-b' }, statePath);
+    const state = await readOpencodeState(statePath);
+    expect(state.project).toBe('b');
+    expect(state.tokens).toEqual({ a: 'tok-a', b: 'tok-b' });
+  });
+
+  it('switching without a new token leaves the stored one alone', async () => {
+    await writeOpencodeState({ project: 'a', gatewayUrl: 'https://gw', token: 'tok-a' }, statePath);
+    await writeOpencodeState({ project: 'a', gatewayUrl: 'https://gw2' }, statePath);
+    const state = await readOpencodeState(statePath);
+    expect(state.gatewayUrl).toBe('https://gw2');
+    expect(storedToken(state, 'a')).toBe('tok-a');
+  });
+
+  it('reads a missing or corrupt state as empty rather than throwing', async () => {
+    expect(await readOpencodeState(join(dir, 'nope.json'))).toEqual({});
+    mkdirSync(join(dir, 'x'), { recursive: true });
+    writeFileSync(join(dir, 'x', 's.json'), 'not json');
+    expect(await readOpencodeState(join(dir, 'x', 's.json'))).toEqual({});
+  });
+
+  it('storedToken ignores an empty or missing entry', () => {
+    expect(storedToken({ tokens: { a: '' } }, 'a')).toBeNull();
+    expect(storedToken({}, 'a')).toBeNull();
+    expect(storedToken({ tokens: { a: 'x' } }, 'a')).toBe('x');
+  });
+});