@cloudcli-ai/cloudcli 1.37.3 → 1.37.4

package/server/modules/websocket/tests/chat-stop-task.test.ts

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+import { handleChatConnection } from '@/modules/websocket/services/chat-websocket.service.js';
+import { chatRunRegistry } from '@/modules/websocket/services/chat-run-registry.service.js';
+import { connectedClients } from '@/modules/websocket/services/websocket-state.service.js';
+
+const SESSION_ID = 'held-session';
+
+function createFakeSocket() {
+  const socket = new EventEmitter() as EventEmitter & {
+    readyState: number;
+    frames: Array<Record<string, unknown>>;
+    send: (data: string) => void;
+  };
+  socket.readyState = 1;
+  socket.frames = [];
+  socket.send = (data: string) => socket.frames.push(JSON.parse(data) as Record<string, unknown>);
+  return socket;
+}
+
+type StopCall = { provider: string; sessionId: string; taskId: string };
+
+/**
+ * A gateway whose runtime knows exactly one background task. There is no chat
+ * run in progress: the turn that launched the task has ended, which is the
+ * state a stop request arrives in.
+ */
+async function withGateway(
+  knownTaskId: string,
+  runTest: (context: {
+    socket: ReturnType<typeof createFakeSocket>;
+    stops: StopCall[];
+  }) => Promise<void>,
+): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'chat-stop-task-'));
+
+  closeConnection();
+  process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
+  await initializeDatabase();
+
+  const stops: StopCall[] = [];
+  const socket = createFakeSocket();
+
+  try {
+    sessionsDb.createAppSession(SESSION_ID, 'claude', tempDirectory);
+
+    handleChatConnection(
+      socket as never,
+      { user: { id: 1 } } as never,
+      {
+        runtime: {
+          stopBackgroundTask: async (provider: string, sessionId: string, taskId: string) => {
+            stops.push({ provider, sessionId, taskId });
+            return taskId === knownTaskId;
+          },
+        } as never,
+      },
+    );
+
+    await runTest({ socket, stops });
+  } finally {
+    connectedClients.clear();
+    chatRunRegistry.clearAll();
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+/** The handler is async and the socket listener does not await it. */
+const settle = () => new Promise((resolve) => { setTimeout(resolve, 30); });
+
+test('chat.stop-task stops the task through the session\'s provider runtime', async () => {
+  await withGateway('task-1', async ({ socket, stops }) => {
+    socket.emit('message', JSON.stringify({ type: 'chat.stop-task', sessionId: SESSION_ID, taskId: 'task-1' }));
+    await settle();
+
+    // The provider comes from the session row, never from the frame.
+    assert.deepEqual(stops, [{ provider: 'claude', sessionId: SESSION_ID, taskId: 'task-1' }]);
+    // The runtime reports the stop on the session's stream; nothing is echoed here.
+    assert.deepEqual(socket.frames, []);
+  });
+});
+
+test('a task the runtime is not tracking is refused with NO_SUCH_TASK', async () => {
+  await withGateway('task-1', async ({ socket, stops }) => {
+    socket.emit('message', JSON.stringify({ type: 'chat.stop-task', sessionId: SESSION_ID, taskId: 'already-settled' }));
+    await settle();
+
+    assert.equal(stops.length, 1);
+    assert.equal(socket.frames.length, 1);
+    assert.equal(socket.frames[0].kind, 'protocol_error');
+    assert.equal(socket.frames[0].code, 'NO_SUCH_TASK');
+    assert.equal(socket.frames[0].sessionId, SESSION_ID);
+  });
+});
+
+test('a stop without a task id never reaches the runtime', async () => {
+  await withGateway('task-1', async ({ socket, stops }) => {
+    socket.emit('message', JSON.stringify({ type: 'chat.stop-task', sessionId: SESSION_ID }));
+    await settle();
+
+    assert.equal(stops.length, 0);
+    assert.equal(socket.frames.at(-1)?.code, 'TASK_ID_REQUIRED');
+  });
+});
+
+test('a stop for a session that does not exist is refused', async () => {
+  await withGateway('task-1', async ({ socket, stops }) => {
+    socket.emit('message', JSON.stringify({ type: 'chat.stop-task', sessionId: 'no-such-session', taskId: 'task-1' }));
+    await settle();
+
+    assert.equal(stops.length, 0);
+    assert.equal(socket.frames.at(-1)?.code, 'SESSION_NOT_FOUND');
+  });
+});

package/server/modules/websocket/tests/shell-websocket.service.test.ts

@@ -1,5 +1,7 @@
 import assert from 'node:assert/strict';
+import { execFileSync, spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
@@ -225,3 +227,522 @@ test('a missing project directory is reported as an error frame and starts no pt
     [{ type: 'error', message: 'Invalid project path' }]
   );
 });
+
+type SpawnCall = { shell: string; args: string[]; command: string; env: Record<string, string | undefined> };
+
+function spawnRecorder(resumeSessionId: string | null = null) {
+  const calls: SpawnCall[] = [];
+  const dependencies = {
+    resolveProviderSessionId: () => resumeSessionId,
+    spawnPty: (shell: string, args: string | string[], options?: { env?: Record<string, string | undefined> }) => {
+      calls.push({
+        shell,
+        args: Array.isArray(args) ? args : [args],
+        command: Array.isArray(args) ? args[args.length - 1] : args,
+        env: options?.env ?? {},
+      });
+      return createFakePty() as never;
+    },
+  };
+  return { calls, dependencies };
+}
+
+let launchCount = 0;
+
+function launch(
+  dependencies: ReturnType<typeof spawnRecorder>['dependencies'],
+  init: Record<string, unknown>,
+  projectPath = process.cwd()
+) {
+  const socket = createFakeSocket();
+  handleShellConnection(socket as never, dependencies);
+  launchCount += 1;
+  socket.emit(
+    'message',
+    JSON.stringify({
+      type: 'init',
+      projectPath,
+      sessionId: `scheme-${launchCount}-${Date.now()}`,
+      hasSession: false,
+      ...init,
+    })
+  );
+  return socket;
+}
+
+type ClaudeConfigFixture = {
+  configHome: string;
+  home: string;
+  projectPath: string;
+  write: (filePath: string, contents: unknown) => void;
+};
+
+/**
+ * Runs `body` against a throwaway CLAUDE_CONFIG_DIR, HOME and project folder,
+ * so the user's real Claude config and app data folder never leak into (or
+ * out of) the tests. `homeName` names the HOME folder, to test awkward paths.
+ */
+function withClaudeConfig(body: (fixture: ClaudeConfigFixture) => void, homeName = 'home') {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shell-claude-theme-'));
+  const configHome = path.join(root, 'config');
+  const home = path.join(root, homeName);
+  const projectPath = path.join(root, 'project');
+  fs.mkdirSync(configHome, { recursive: true });
+  fs.mkdirSync(projectPath, { recursive: true });
+  const savedEnv = {
+    CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
+    HOME: process.env.HOME,
+    USERPROFILE: process.env.USERPROFILE,
+  };
+  process.env.CLAUDE_CONFIG_DIR = configHome;
+  // os.homedir() reads HOME on POSIX and USERPROFILE on Windows.
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+
+  const write = (filePath: string, contents: unknown) => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, typeof contents === 'string' ? contents : JSON.stringify(contents));
+  };
+
+  try {
+    body({ configHome, home, projectPath, write });
+  } finally {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// The server-owned settings file a light launch points `--settings` at. The
+// default fixture HOME has no quote in it, so bash quoting is a plain wrap.
+const themeSettingsPath = (theme: string) =>
+  path.join(os.homedir(), '.cloudcli', `claude-shell-theme-${theme}.json`);
+const themeFlag = (theme: string) => ` --settings '${themeSettingsPath(theme)}'`;
+
+// The flag outranks the user's own settings, so a dark Shell tab must not send
+// one: it would turn a daltonized or ANSI theme back into the plain dark one.
+test('a dark Shell tab launches claude exactly as before, whatever the user theme is', () => {
+  withClaudeConfig(({ configHome, home, projectPath, write }) => {
+    write(path.join(configHome, 'settings.json'), { theme: 'dark-daltonized' });
+    const { calls, dependencies } = spawnRecorder('resumed-session-id');
+
+    launch(dependencies, { provider: 'claude', colorScheme: 'dark' }, projectPath);
+    launch(dependencies, { provider: 'claude', colorScheme: 'dark', bypassPermissions: true }, projectPath);
+    launch(dependencies, { provider: 'claude', colorScheme: 'dark', hasSession: true }, projectPath);
+    launch(dependencies, { provider: 'claude' }, projectPath);
+    launch(dependencies, { provider: 'claude', colorScheme: 'sepia' }, projectPath);
+
+    if (os.platform() !== 'win32') {
+      assert.deepEqual(
+        calls.map((call) => call.command),
+        [
+          'claude',
+          'claude --dangerously-skip-permissions',
+          'claude --resume "resumed-session-id" || claude',
+          'claude',
+          'claude',
+        ]
+      );
+    }
+    assert.equal(calls[0].env.COLORFGBG, '15;0');
+    assert.equal(calls[3].env.COLORFGBG, process.env.COLORFGBG);
+    assert.equal(calls[4].env.COLORFGBG, process.env.COLORFGBG);
+    assert.equal(fs.existsSync(path.join(home, '.cloudcli')), false, 'a dark launch writes no file');
+  });
+});
+
+// Claude Code defaults to its dark theme whatever the terminal looks like, so a
+// light Shell tab showed dark prompt bands until the launch carried a light one.
+test('a light Shell tab swaps a dark Claude theme for its light variant', () => {
+  const cases: Array<[string | undefined, string]> = [
+    [undefined, 'light'],
+    ['dark', 'light'],
+    ['dark-daltonized', 'light-daltonized'],
+    ['dark-ansi', 'light-ansi'],
+  ];
+
+  for (const [userTheme, expectedTheme] of cases) {
+    withClaudeConfig(({ configHome, projectPath, write }) => {
+      if (userTheme) {
+        write(path.join(configHome, 'settings.json'), { theme: userTheme, verbose: true });
+      }
+      const { calls, dependencies } = spawnRecorder();
+
+      launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+      assert.equal(calls.length, 1);
+      if (os.platform() !== 'win32') {
+        assert.equal(calls[0].command, `claude${themeFlag(expectedTheme)}`, `user theme ${userTheme}`);
+      }
+      assert.deepEqual(JSON.parse(fs.readFileSync(themeSettingsPath(expectedTheme), 'utf8')), {
+        theme: expectedTheme,
+      });
+      assert.equal(calls[0].env.COLORFGBG, '0;15');
+    });
+  }
+});
+
+test('a light Shell tab keeps a light, auto or custom theme the user chose', () => {
+  for (const userTheme of ['light', 'light-daltonized', 'light-ansi', 'auto', 'custom:solarized']) {
+    withClaudeConfig(({ configHome, projectPath, write }) => {
+      write(path.join(configHome, 'settings.json'), { theme: userTheme });
+      const { calls, dependencies } = spawnRecorder();
+
+      launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+      assert.deepEqual(calls.map((call) => call.command), ['claude'], `user theme ${userTheme}`);
+      assert.equal(calls[0].env.COLORFGBG, '0;15');
+    });
+  }
+});
+
+// Mirrors resolveSetting("theme") of Claude Code 2.1.280: local, project and user
+// settings first, then the legacy `theme` key of the global config.
+test('the Claude theme is read in the CLI order, including the legacy global config', () => {
+  const lightLaunch = (projectPath: string) => {
+    const { calls, dependencies } = spawnRecorder();
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    return calls[0].command;
+  };
+  if (os.platform() === 'win32') {
+    return;
+  }
+
+  withClaudeConfig(({ configHome, projectPath, write }) => {
+    write(path.join(configHome, '.claude.json'), { theme: 'dark-daltonized' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-daltonized')}`);
+
+    write(path.join(configHome, 'settings.json'), { theme: 'sepia' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-daltonized')}`, 'invalid value is unset');
+
+    write(path.join(configHome, 'settings.json'), { theme: 'dark-ansi' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-ansi')}`, 'settings beat legacy config');
+
+    write(path.join(projectPath, '.claude', 'settings.json'), { theme: 'light' });
+    assert.equal(lightLaunch(projectPath), 'claude', 'project settings beat user settings');
+
+    write(path.join(projectPath, '.claude', 'settings.local.json'), { theme: 'dark-daltonized' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-daltonized')}`, 'local beats project');
+  });
+
+  withClaudeConfig(({ configHome, projectPath, write }) => {
+    write(path.join(configHome, '.claude.json'), { theme: 'dark-daltonized' });
+    write(path.join(configHome, '.config.json'), { theme: 'dark-ansi' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-ansi')}`, 'legacy .config.json wins');
+  });
+
+  // Without CLAUDE_CONFIG_DIR the CLI reads ~/.claude/settings.json and ~/.claude.json.
+  withClaudeConfig(({ projectPath, write }) => {
+    delete process.env.CLAUDE_CONFIG_DIR;
+    const home = process.env.HOME as string;
+    write(path.join(home, '.claude.json'), { theme: 'dark-ansi' });
+    assert.equal(lightLaunch(projectPath), `claude${themeFlag('light-ansi')}`);
+
+    write(path.join(home, '.claude', 'settings.json'), { theme: 'light-daltonized' });
+    assert.equal(lightLaunch(projectPath), 'claude');
+  });
+});
+
+test('an unreadable or unparsable Claude config counts as unset and never blocks the launch', () => {
+  withClaudeConfig(({ configHome, projectPath, write }) => {
+    // A directory where a file is expected fails to read with EISDIR.
+    fs.mkdirSync(path.join(configHome, 'settings.json'));
+    write(path.join(configHome, '.claude.json'), '{"theme": "dark-daltonized",');
+    write(path.join(projectPath, '.claude', 'settings.local.json'), 'not json');
+    write(path.join(projectPath, '.claude', 'settings.json'), '["dark-ansi"]');
+    const { calls, dependencies } = spawnRecorder();
+
+    const socket = launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+    assert.equal(calls.length, 1);
+    if (os.platform() !== 'win32') {
+      assert.equal(calls[0].command, `claude${themeFlag('light')}`);
+    }
+    const frames = socket.frames.map((frame) => JSON.parse(frame) as { type: string });
+    assert.deepEqual(frames.map((frame) => frame.type), ['output', 'claude_theme']);
+  });
+});
+
+// The project can be a cloned repository, and the repository decides what its
+// `.claude/settings.local.json` is. Reading a symlink to a FIFO blocked the
+// server until something wrote to it; one to /dev/zero exhausted its memory.
+test('a Claude config that is not a regular file is skipped without being opened', (t) => {
+  if (os.platform() === 'win32') {
+    t.skip('needs mkfifo and /dev/null');
+    return;
+  }
+  withClaudeConfig(({ configHome, projectPath }) => {
+    const fifoPath = path.join(projectPath, 'settings.fifo');
+    execFileSync('mkfifo', [fifoPath]);
+    fs.mkdirSync(path.join(projectPath, '.claude'));
+    fs.symlinkSync(fifoPath, path.join(projectPath, '.claude', 'settings.local.json'));
+    fs.symlinkSync('/dev/null', path.join(projectPath, '.claude', 'settings.json'));
+    fs.symlinkSync(os.tmpdir(), path.join(configHome, 'settings.json'));
+    // A reader that opened the FIFO would get a dark-daltonized theme from this
+    // writer (and so launch light-daltonized) instead of blocking forever. A
+    // launch that skips it falls through to the default dark theme.
+    const writer = spawn('sh', ['-c', `printf %s '{"theme":"dark-daltonized"}' > "$0"`, fifoPath], {
+      stdio: 'ignore',
+    });
+    try {
+      const { calls, dependencies } = spawnRecorder();
+      const startedAt = Date.now();
+
+      const socket = launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+      assert.ok(Date.now() - startedAt < 1000, 'the launch did not wait for the FIFO');
+      assert.deepEqual(calls.map((call) => call.command), [`claude${themeFlag('light')}`]);
+      const frames = socket.frames.map((frame) => JSON.parse(frame) as { type: string });
+      assert.deepEqual(frames.map((frame) => frame.type), ['output', 'claude_theme']);
+    } finally {
+      writer.kill();
+    }
+  });
+});
+
+test('an oversized Claude config is skipped without being read', (t) => {
+  withClaudeConfig(({ configHome, projectPath }) => {
+    const settingsPath = path.join(configHome, 'settings.json');
+    // The CLI refuses settings files over 2 MiB. A sparse tail takes the file
+    // past that cap without using the disk.
+    fs.writeFileSync(settingsPath, '{"theme":"dark-daltonized"}');
+    fs.truncateSync(settingsPath, 2 * 1024 * 1024 + 1);
+    const readFileSync = t.mock.method(fs, 'readFileSync');
+    const { calls, dependencies } = spawnRecorder();
+
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+    const readPaths = readFileSync.mock.calls.map((call) => String(call.arguments[0]));
+    assert.equal(readPaths.includes(settingsPath), false, 'the oversized file was read');
+    assert.equal(calls.length, 1);
+    if (os.platform() !== 'win32') {
+      assert.equal(calls[0].command, `claude${themeFlag('light')}`);
+    }
+  });
+});
+
+test('the legacy global config may be bigger than a settings file', () => {
+  withClaudeConfig(({ configHome, projectPath, write }) => {
+    // `~/.claude.json` keeps per-project history and can grow to several MB.
+    write(path.join(configHome, '.claude.json'), {
+      theme: 'dark-daltonized',
+      padding: 'x'.repeat(3 * 1024 * 1024),
+    });
+    const { calls, dependencies } = spawnRecorder();
+
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+    assert.equal(calls.length, 1);
+    if (os.platform() !== 'win32') {
+      assert.equal(calls[0].command, `claude${themeFlag('light-daltonized')}`);
+    }
+  });
+});
+
+test('the light theme rides along with bypass and resume launches', () => {
+  withClaudeConfig(({ projectPath }) => {
+    const { calls, dependencies } = spawnRecorder('resumed-session-id');
+
+    launch(
+      dependencies,
+      { hasSession: true, provider: 'claude', bypassPermissions: true, colorScheme: 'light' },
+      projectPath
+    );
+
+    assert.equal(calls.length, 1);
+    if (os.platform() !== 'win32') {
+      const flags = ` --dangerously-skip-permissions${themeFlag('light')}`;
+      assert.equal(calls[0].command, `claude --resume "resumed-session-id"${flags} || claude${flags}`);
+    }
+  });
+});
+
+// The file lives in the app's own data folder: the user's Claude config and
+// the project are only ever read.
+test('the light theme settings file is written once to the app data folder', () => {
+  withClaudeConfig(({ configHome, home, projectPath, write }) => {
+    write(path.join(configHome, 'settings.json'), { theme: 'dark-daltonized' });
+    const configBefore = fs.readdirSync(configHome).sort();
+    const settingsPath = path.join(home, '.cloudcli', 'claude-shell-theme-light-daltonized.json');
+    const { calls, dependencies } = spawnRecorder();
+
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    assert.equal(fs.readFileSync(settingsPath, 'utf8'), '{"theme":"light-daltonized"}\n');
+
+    // Unchanged contents are not rewritten.
+    const past = new Date('2020-01-01T00:00:00Z');
+    fs.utimesSync(settingsPath, past, past);
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    assert.equal(fs.statSync(settingsPath).mtimeMs, past.getTime());
+
+    // Stale contents are replaced.
+    fs.writeFileSync(settingsPath, '{"theme":"dark"}');
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    assert.equal(fs.readFileSync(settingsPath, 'utf8'), '{"theme":"light-daltonized"}\n');
+
+    assert.equal(calls.length, 3);
+    assert.deepEqual(fs.readdirSync(path.join(home, '.cloudcli')), ['claude-shell-theme-light-daltonized.json']);
+    assert.deepEqual(fs.readdirSync(configHome).sort(), configBefore);
+    assert.equal(fs.existsSync(path.join(projectPath, '.claude')), false);
+  });
+});
+
+// Windows runs the command through `powershell.exe -Command`, which is why the
+// theme travels as a file path: PowerShell strips the double quotes of inline
+// JSON when it hands an argument to a native program.
+test('the settings file path is quoted for bash and for PowerShell', (t) => {
+  if (os.platform() === 'win32') {
+    t.skip('asserts the bash launch and POSIX paths first');
+    return;
+  }
+  withClaudeConfig(({ home, projectPath }) => {
+    const settingsPath = path.join(home, '.cloudcli', 'claude-shell-theme-light.json');
+    const { calls, dependencies } = spawnRecorder('resumed-session-id');
+
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    launch(dependencies, { provider: 'claude', colorScheme: 'light', hasSession: true }, projectPath);
+    t.mock.method(os, 'platform', () => 'win32');
+    launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    launch(dependencies, { provider: 'claude', colorScheme: 'light', hasSession: true }, projectPath);
+
+    const bashFlag = ` --settings '${settingsPath.replace(/'/g, `'\\''`)}'`;
+    const powerShellFlag = ` --settings '${settingsPath.replace(/['\u2019]/g, '$&$&')}'`;
+    assert.ok(settingsPath.includes("it's a \u2019quoted\u2019 home"), settingsPath);
+    assert.deepEqual(calls.map((call) => [call.shell, ...call.args]), [
+      ['bash', '-c', `claude${bashFlag}`],
+      ['bash', '-c', `claude --resume "resumed-session-id"${bashFlag} || claude${bashFlag}`],
+      ['powershell.exe', '-Command', `claude${powerShellFlag}`],
+      [
+        'powershell.exe',
+        '-Command',
+        `claude --resume "resumed-session-id"${powerShellFlag}; if ($LASTEXITCODE -ne 0) { claude${powerShellFlag} }`,
+      ],
+    ]);
+    // Spelled out once, so the escaping above is not only checked against itself.
+    assert.ok(calls[0].command.endsWith(`/it'\\''s a \u2019quoted\u2019 home/.cloudcli/claude-shell-theme-light.json'`));
+    assert.ok(calls[2].command.endsWith(`/it''s a \u2019\u2019quoted\u2019\u2019 home/.cloudcli/claude-shell-theme-light.json'`));
+    assert.deepEqual(JSON.parse(fs.readFileSync(settingsPath, 'utf8')), { theme: 'light' });
+  }, "it's a \u2019quoted\u2019 home");
+});
+
+test('a settings file that cannot be written drops the flag, logs once and still launches', (t) => {
+  withClaudeConfig(({ home, projectPath, write }) => {
+    // A file where the app data folder should be makes every write fail.
+    write(path.join(home, '.cloudcli'), 'not a folder');
+    const warn = t.mock.method(console, 'warn', () => undefined);
+    const { calls, dependencies } = spawnRecorder();
+
+    const firstSocket = launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+    const secondSocket = launch(dependencies, { provider: 'claude', colorScheme: 'light' }, projectPath);
+
+    assert.deepEqual(calls.map((call) => call.command), ['claude', 'claude']);
+    assert.deepEqual(calls.map((call) => call.env.COLORFGBG), ['0;15', '0;15']);
+    // The CLI paints its dark default in either app theme, so no restart hint.
+    for (const socket of [firstSocket, secondSocket]) {
+      const frames = socket.frames.map((frame) => JSON.parse(frame) as { type: string });
+      assert.deepEqual(frames.map((frame) => frame.type), ['output']);
+    }
+    assert.equal(warn.mock.callCount(), 1);
+    assert.match(String(warn.mock.calls[0].arguments[0]), /Claude theme settings file/);
+  });
+});
+
+// A running CLI keeps its launch-time colours. The client is told the theme the
+// pty's claude was launched for, also when it reattaches later in another theme,
+// so the Shell can suggest a restart when they differ.
+test('claude launches report the app theme they started in, also on reattach', () => {
+  withClaudeConfig(({ projectPath }) => {
+    const { calls, dependencies } = spawnRecorder();
+    const themeFrames = (socket: ReturnType<typeof createFakeSocket>) =>
+      socket.frames
+        .map((frame) => JSON.parse(frame) as Record<string, unknown>)
+        .filter((frame) => frame.type === 'claude_theme');
+    const sessionId = `claude-theme-${Date.now()}`;
+    const attach = (colorScheme: string) => {
+      const socket = createFakeSocket();
+      handleShellConnection(socket as never, dependencies);
+      socket.emit(
+        'message',
+        JSON.stringify({ type: 'init', projectPath, sessionId, hasSession: false, provider: 'claude', colorScheme })
+      );
+      return socket;
+    };
+
+    const firstSocket = attach('light');
+    const reattachedSocket = attach('dark');
+
+    assert.equal(calls.length, 1, 'the second init reattached to the running pty');
+    assert.deepEqual(themeFrames(firstSocket), [{ type: 'claude_theme', colorScheme: 'light' }]);
+    assert.deepEqual(themeFrames(reattachedSocket), [{ type: 'claude_theme', colorScheme: 'light' }]);
+
+    const darkSocket = launch(dependencies, { provider: 'claude', colorScheme: 'dark' }, projectPath);
+    assert.deepEqual(themeFrames(darkSocket), [{ type: 'claude_theme', colorScheme: 'dark' }]);
+
+    const silentLaunches = [
+      launch(dependencies, { provider: 'claude' }, projectPath),
+      launch(dependencies, { provider: 'claude', initialCommand: 'claude /login', colorScheme: 'light' }, projectPath),
+      launch(dependencies, { provider: 'codex', colorScheme: 'light' }, projectPath),
+      launch(dependencies, { provider: 'plain-shell', isPlainShell: true, colorScheme: 'light' }, projectPath),
+    ];
+    assert.deepEqual(silentLaunches.map(themeFrames), [[], [], [], []]);
+  });
+});
+
+// A restart only helps when the CLI's colours follow the app theme. A light or
+// custom theme the user chose paints the same in either app theme.
+test('the restart hint is only offered when a restart would change the CLI colours', () => {
+  for (const [userTheme, expectsHint] of [
+    ['dark-daltonized', true],
+    ['auto', true],
+    ['light', false],
+    ['light-daltonized', false],
+    ['custom:mine', false],
+  ] as const) {
+    withClaudeConfig(({ configHome, projectPath, write }) => {
+      write(path.join(configHome, 'settings.json'), { theme: userTheme });
+      const { dependencies } = spawnRecorder();
+
+      for (const colorScheme of ['light', 'dark']) {
+        const socket = launch(dependencies, { provider: 'claude', colorScheme }, projectPath);
+        const themeFrames = socket.frames
+          .map((frame) => JSON.parse(frame) as Record<string, unknown>)
+          .filter((frame) => frame.type === 'claude_theme');
+        assert.deepEqual(
+          themeFrames,
+          expectsHint ? [{ type: 'claude_theme', colorScheme }] : [],
+          `${userTheme} in a ${colorScheme} tab`,
+        );
+      }
+    });
+  }
+});
+
+test('other shells and initial commands only get the COLORFGBG hint', () => {
+  withClaudeConfig(({ projectPath }) => {
+    const { calls, dependencies } = spawnRecorder();
+    const loginCommand = 'claude --dangerously-skip-permissions /login';
+
+    launch(
+      dependencies,
+      { provider: 'plain-shell', isPlainShell: true, initialCommand: 'npx task-master init', colorScheme: 'light' },
+      projectPath
+    );
+    launch(dependencies, { provider: 'claude', initialCommand: loginCommand, colorScheme: 'light' }, projectPath);
+    launch(dependencies, { provider: 'codex', colorScheme: 'light' }, projectPath);
+    launch(dependencies, { provider: 'codex', colorScheme: 'dark' }, projectPath);
+
+    assert.deepEqual(
+      calls.map((call) => call.command),
+      ['npx task-master init', loginCommand, 'codex', 'codex']
+    );
+    assert.deepEqual(
+      calls.map((call) => call.env.COLORFGBG),
+      ['0;15', '0;15', '0;15', '15;0']
+    );
+  });
+});