fix(cli): agent run refuses an --adapter that differs from the token file (#2099)

* fix(cli): agent run refuses an --adapter that differs from the token file

`--adapter` chose the CLI only at first-run bootstrap; once a token file
existed, the record's adapter ran and a different flag was dropped without
a word, so switching an agent from Claude to Codex kept running Claude
(#2098). The run now exits 1 with the binding, the token path and the
remedy for each path: `detach --force` and a re-bootstrap for a foreground
run, `agent config --adapter` for a daemon-managed seat. The option help
no longer says the flag is ignored.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013geJsV4RJMujdvpf3JV2Cv

* chore(cli): 0.1.87 for the --adapter mismatch refusal

cli/src changed, so the published version must rise ("Source changed ⇒
version bumped").

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013geJsV4RJMujdvpf3JV2Cv

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: lilyshen0722

cli/__tests__/run-adapter-mismatch.test.mjs

@@ -0,0 +1,117 @@
+/**
+ * run-adapter-mismatch.test.mjs — #2098
+ *
+ * `commonly agent run <name> --adapter X` only ever chose the CLI at first-run
+ * bootstrap. Once ~/.commonly/tokens/<name>.json exists, the record's adapter
+ * runs, and a different `--adapter` was dropped silently: switching an agent
+ * from Claude to Codex kept running Claude. The run now refuses the mismatch
+ * and names the remedy.
+ *
+ * Covers the pure check and the command wiring: the real `agent run` action,
+ * built by registerAgent, against a token file in a throwaway home directory.
+ */
+
+import { jest } from '@jest/globals';
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+import { Command } from 'commander';
+
+const homeTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-run-adapter-test-'));
+
+await jest.unstable_mockModule('os', () => {
+  const actual = os;
+  return {
+    ...actual,
+    default: { ...actual, homedir: () => homeTmpDir },
+    homedir: () => homeTmpDir,
+  };
+});
+
+const { checkRunAdapterRequest, saveAgentToken, registerAgent } = await import('../src/commands/agent.js');
+
+afterAll(() => fs.rmSync(homeTmpDir, { recursive: true, force: true }));
+
+const record = (adapter) => ({
+  agentName: 'byo-test',
+  podId: 'pod-1',
+  instanceUrl: 'https://api.commonly.me',
+  runtimeToken: 'cm_agent_test',
+  adapter,
+});
+const tokenPath = path.join(homeTmpDir, '.commonly', 'tokens', 'byo-test.json');
+
+describe('checkRunAdapterRequest', () => {
+  test('no --adapter runs the bound adapter', () => {
+    expect(checkRunAdapterRequest({ record: record('claude'), requestedAdapter: undefined, tokenPath })).toEqual({ ok: true });
+    expect(checkRunAdapterRequest({ record: record('claude'), requestedAdapter: null, tokenPath })).toEqual({ ok: true });
+  });
+
+  test('a matching --adapter runs, whatever its case', () => {
+    expect(checkRunAdapterRequest({ record: record('codex'), requestedAdapter: 'codex', tokenPath })).toEqual({ ok: true });
+    expect(checkRunAdapterRequest({ record: record('codex'), requestedAdapter: ' Codex ', tokenPath })).toEqual({ ok: true });
+  });
+
+  test('a mismatched --adapter refuses and names the binding and both remedies', () => {
+    const result = checkRunAdapterRequest({ record: record('claude'), requestedAdapter: 'codex', tokenPath });
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("'byo-test' is bound to the claude adapter");
+    expect(result.message).toContain(tokenPath);
+    expect(result.message).toContain('--adapter codex was not applied');
+    expect(result.message).toContain('commonly agent detach byo-test --force');
+    expect(result.message).toContain('commonly agent config byo-test --adapter codex');
+    // Plain detach also uninstalls the agent from its pod; the remedy must not suggest it.
+    expect(result.message).not.toMatch(/detach byo-test(?! --force)/);
+  });
+
+  test('a record with no adapter is left to the existing unknown-adapter error', () => {
+    expect(checkRunAdapterRequest({ record: record(undefined), requestedAdapter: 'codex', tokenPath })).toEqual({ ok: true });
+  });
+});
+
+describe('agent run --adapter against an existing token file', () => {
+  const exitSentinel = new Error('process.exit called');
+  let exitSpy;
+  let errorSpy;
+
+  beforeEach(() => {
+    saveAgentToken('byo-test', record('claude'));
+    exitSpy = jest.spyOn(process, 'exit').mockImplementation((code) => {
+      exitSentinel.code = code;
+      throw exitSentinel;
+    });
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  const run = async (...args) => {
+    const program = new Command();
+    program.exitOverride();
+    registerAgent(program);
+    return program.parseAsync(['agent', 'run', 'byo-test', ...args], { from: 'user' });
+  };
+
+  test('a mismatched --adapter exits 1 with the remedy before anything runs', async () => {
+    await expect(run('--adapter', 'codex')).rejects.toBe(exitSentinel);
+    expect(exitSentinel.code).toBe(1);
+    const stderr = errorSpy.mock.calls.map((call) => call.join(' ')).join('\n');
+    expect(stderr).toContain("[byo-test] 'byo-test' is bound to the claude adapter");
+    expect(stderr).toContain(`(${tokenPath})`);
+    expect(stderr).toContain('commonly agent detach byo-test --force');
+    // The token file is untouched: refusing must not edit the record.
+    expect(JSON.parse(fs.readFileSync(tokenPath, 'utf8')).adapter).toBe('claude');
+  });
+
+  test('the option help tells the truth about an existing token file', () => {
+    const program = new Command();
+    registerAgent(program);
+    const runCommand = program.commands.find((c) => c.name() === 'agent').commands.find((c) => c.name() === 'run');
+    const option = runCommand.options.find((o) => o.long === '--adapter');
+    expect(option.description).toContain('bound to a different adapter stops the run');
+    expect(option.description).not.toContain('ignored');
+  });
+});

cli/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.86",
+  "version": "0.1.87",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

cli/package.json

@@ -127,6 +127,30 @@ export const deleteAgentToken = (name) => {
 // falls back to the attach hint).
 export const BOOTSTRAP_ADAPTER_DETECT_ORDER = ['claude', 'codex', 'pi'];
 
+// ── `agent run --adapter` against an existing token file (#2098) ────────────
+// The flag picks the CLI once, at first-run bootstrap; after that the token
+// file's adapter is what runs. A different `--adapter` used to be dropped
+// without a word, so "switch this agent to Codex" kept running Claude and read
+// as Codex misbehaving. Refuse instead, and name the way out for each path:
+// a foreground run re-bootstraps from the Connect page's env exports after the
+// local record is removed; a daemon-managed seat is switched through the
+// registry, which the daemon applies on its next pass.
+export const checkRunAdapterRequest = ({ record, requestedAdapter, tokenPath }) => {
+  const requested = String(requestedAdapter || '').trim().toLowerCase();
+  if (!requested) return { ok: true };
+  const bound = String(record?.adapter || '').trim().toLowerCase();
+  if (!bound || bound === requested) return { ok: true };
+  const name = record.agentName;
+  return {
+    ok: false,
+    message: [
+      `'${name}' is bound to the ${bound} adapter by its token file (${tokenPath}); --adapter ${requested} was not applied.`,
+      `To run it with ${requested} here: commonly agent detach ${name} --force, then re-run with the Connect-page env exports and --adapter ${requested}.`,
+      `A daemon-managed seat switches with: commonly agent config ${name} --adapter ${requested}`,
+    ].join('\n'),
+  };
+};
+
 export const bootstrapAgentRecordFromEnv = async ({
   name,
   env = process.env,
@@ -2690,7 +2714,7 @@ Docs:
     .command('run <name>')
     .description('Run the local-CLI wrapper loop for an attached agent')
     .option('--interval <ms>', 'Poll interval in ms', '5000')
-    .option('--adapter <name>', 'CLI to wrap on first-run bootstrap (claude|codex); ignored when a token file already exists')
+    .option('--adapter <name>', 'CLI to wrap on first-run bootstrap (claude|codex); an existing token file bound to a different adapter stops the run')
     .option('--cascade-cap <n>', `Consecutive agent-triggered turns allowed per pod (env ${CASCADE_ENV_VARS.cap}, default ${CASCADE_DEFAULTS.cap})`)
     .option('--cascade-grace <n>', `Extra turns allowed when this seat was directly addressed; 0 disables the grace (env ${CASCADE_ENV_VARS.addressedGrace}, default ${CASCADE_DEFAULTS.addressedGrace})`)
     .option('--cascade-reset <ms>', `Silence window that clears the streak (env ${CASCADE_ENV_VARS.resetMs}, default ${CASCADE_DEFAULTS.resetMs})`)
@@ -2722,6 +2746,14 @@ Docs:
         }
       }
 
+      const adapterRequest = checkRunAdapterRequest({
+        record, requestedAdapter: opts.adapter, tokenPath: tokenFile(name),
+      });
+      if (!adapterRequest.ok) {
+        console.error(`${stamp()} [${name}] ${adapterRequest.message}`);
+        process.exit(1);
+      }
+
       const adapter = getAdapter(record.adapter);
       if (!adapter) {
         console.error(`Unknown adapter '${record.adapter}' in token file. Known: ${listAdapterNames().join(', ')}`);