@cleocode/adapters 2026.9.20 → 2026.9.22

package/src/providers/kimi/spawn.ts

@@ -27,12 +27,9 @@
  * @task T648
  */
 
-import { exec } from 'node:child_process';
-import { promisify } from 'node:util';
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
 import { getErrorMessage } from '@cleocode/contracts';
-
-const execAsync = promisify(exec);
+import { findOnPath } from '@cleocode/paths';
 
 /** Moonshot AI API base URL. */
 const MOONSHOT_API_BASE = 'https://api.moonshot.cn/v1';
@@ -80,15 +77,10 @@ function resolveMoonshotApiKey(): string | null {
  *
  * This is a forward-compatibility hook for any future official Kimi CLI.
  *
- * @returns `true` if `kimi` is found via `which`
+ * @returns `true` if `kimi` is found on PATH (PATHEXT-aware on Windows)
  */
 async function kimiCliBinaryAvailable(): Promise<boolean> {
-  try {
-    await execAsync('which kimi');
-    return true;
-  } catch {
-    return false;
-  }
+  return findOnPath('kimi') !== null;
 }
 
 /**

package/src/providers/opencode/__tests__/spawn-prompt-delivery.test.ts

@@ -0,0 +1,123 @@
+/**
+ * T12619 — the opencode prompt is delivered on stdin, never argv.
+ *
+ * The prompt used to be the last positional argument of `opencode run`. On
+ * Windows opencode is a `.cmd` shim launched through cmd.exe, which cannot
+ * carry a line break (E_UNSAFE_BATCH_ARG) and caps the line at 8191 chars,
+ * so every real multi-line prompt failed there. `--file` would only attach
+ * it behind a pointer message; `opencode run` uses piped stdin AS the message
+ * when no positional is given, so the prompt is piped on every platform.
+ */
+
+import type { ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@cleocode/paths', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@cleocode/paths')>();
+  return {
+    ...actual,
+    resolveSpawnInvocation: (
+      command: string,
+      args: readonly string[],
+      opts: import('@cleocode/paths').ExecPathOptions = {},
+    ) =>
+      actual.resolveSpawnInvocation(command, args, {
+        ...opts,
+        isExecutable: (p) => p === 'C:\\npm\\opencode.cmd',
+      }),
+  };
+});
+vi.mock('node:child_process', { spy: true });
+
+import { spawn } from 'node:child_process';
+import { OpenCodeSpawnProvider } from '../spawn.js';
+
+const PROMPT = 'Implement T1.\n\nSteps:\n  1. read "spec" & run tests\n  2. 100% done ^_^';
+const realPlatform = process.platform;
+let cwd: string;
+let child: EventEmitter;
+let stdinText: () => string;
+
+function setPlatform(value: NodeJS.Platform): void {
+  Object.defineProperty(process, 'platform', { value, configurable: true });
+}
+
+/** Temp dirs the old `--file` delivery created. */
+function promptDirs(): string[] {
+  return readdirSync(tmpdir()).filter((d) => d.startsWith('cleo-opencode-spawn-'));
+}
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'opencode-spawn-'));
+  child = new EventEmitter();
+  const stdin = new PassThrough();
+  const chunks: Buffer[] = [];
+  stdin.on('data', (c: Buffer) => chunks.push(c));
+  stdinText = () => Buffer.concat(chunks).toString('utf-8');
+  Object.assign(child, { pid: 4242, unref: () => undefined, stdin });
+  vi.mocked(spawn).mockReturnValue(child as ChildProcess);
+});
+afterEach(() => {
+  setPlatform(realPlatform);
+  vi.unstubAllEnvs();
+  vi.mocked(spawn).mockReset();
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+describe('opencode prompt delivery (T12619)', () => {
+  it('POSIX: prompt is piped on stdin byte-exact; argv has no prompt; no temp file', async () => {
+    setPlatform('linux');
+    const before = promptDirs();
+    const result = await new OpenCodeSpawnProvider().spawn({
+      taskId: 'T1',
+      prompt: PROMPT,
+      workingDirectory: cwd,
+    });
+    expect(result.status).toBe('running');
+    const [, args, opts] = vi.mocked(spawn).mock.calls[0] ?? [];
+    const argv = (args ?? []) as readonly string[];
+    expect(opts).toMatchObject({ stdio: ['pipe', 'ignore', 'ignore'] });
+    await vi.waitFor(() => expect(stdinText()).toBe(PROMPT));
+    expect(argv.some((a) => a.includes('Implement') || a.includes('\n'))).toBe(false);
+    expect(argv).not.toContain('--file');
+    // No positional message: argv ends at the title, so stdin IS the message.
+    expect(argv.at(-1)).toBe('CLEO T1');
+    expect(promptDirs()).toEqual(before);
+  });
+
+  it('win32: a multi-line prompt spawns through cmd.exe and is piped on stdin', async () => {
+    setPlatform('win32');
+    vi.stubEnv('PATH', 'C:\\npm');
+    vi.stubEnv('PATHEXT', '.COM;.EXE;.BAT;.CMD');
+    vi.stubEnv('ComSpec', 'C:\\Windows\\system32\\cmd.exe');
+    const before = promptDirs();
+    const result = await new OpenCodeSpawnProvider().spawn({
+      taskId: 'T1',
+      prompt: PROMPT,
+      workingDirectory: cwd,
+    });
+    expect(result.status).toBe('running');
+    const [file, args, opts] = vi.mocked(spawn).mock.calls[0] ?? [];
+    expect(file).toBe('C:\\Windows\\system32\\cmd.exe');
+    expect(opts).toMatchObject({ windowsVerbatimArguments: true });
+    const line = ((args ?? []) as readonly string[])[3] ?? '';
+    expect(line).toContain('C:\\npm\\opencode.cmd');
+    expect(line).not.toContain('Implement');
+    expect(line).not.toContain('--file');
+    await vi.waitFor(() => expect(stdinText()).toBe(PROMPT));
+    expect(promptDirs()).toEqual(before);
+  });
+
+  it('a spawn error (no exit) does not leave the instance tracked', async () => {
+    setPlatform('linux');
+    const provider = new OpenCodeSpawnProvider();
+    await provider.spawn({ taskId: 'T1', prompt: PROMPT, workingDirectory: cwd });
+    child.emit('error', Object.assign(new Error('spawn opencode ENOENT'), { code: 'ENOENT' }));
+    expect(await provider.listRunning()).toEqual([]);
+  });
+});

package/src/providers/opencode/adapter.ts

@@ -7,21 +7,18 @@
  * @task T5240
  */
 
-import { exec } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 import type {
   AdapterCapabilities,
   AdapterHealthStatus,
   CLEOProviderAdapter,
 } from '@cleocode/contracts';
+import { findOnPath } from '@cleocode/paths';
 import { OpenCodeHookProvider } from './hooks.js';
 import { OpenCodeInstallProvider } from './install.js';
 import { OpenCodeSpawnProvider } from './spawn.js';
 
-const execAsync = promisify(exec);
-
 /**
  * CLEO provider adapter for OpenCode AI coding assistant.
  *
@@ -141,13 +138,11 @@ export class OpenCodeAdapter implements CLEOProviderAdapter {
 
     // Check OpenCode CLI availability
     let cliAvailable = false;
-    try {
-      const { stdout } = await execAsync('which opencode');
-      cliAvailable = stdout.trim().length > 0;
-      details.cliPath = stdout.trim();
-    } catch {
-      details.cliAvailable = false;
-    }
+    // In-process PATH/PATHEXT lookup: there is no `which` on Windows (T12604).
+    const resolvedCli = findOnPath('opencode');
+    cliAvailable = resolvedCli !== null;
+    if (resolvedCli) details.cliPath = resolvedCli;
+    else details.cliAvailable = false;
 
     // Check for OpenCode config directory in the project
     if (this.projectDir) {

package/src/providers/opencode/spawn.ts

@@ -11,15 +11,13 @@
  * @task T5240
  */
 
-import { exec, spawn as nodeSpawn } from 'node:child_process';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { findOnPath } from '@cleocode/paths';
+import { spawnCli } from '../shared/cli-spawn.js';
 import { getCleoTemplatesTildePath } from '../shared/paths.js';
 
-const execAsync = promisify(exec);
-
 /** Name used for the CLEO subagent definition in OpenCode's agent directory. */
 const OPENCODE_SUBAGENT_NAME = 'cleo-subagent';
 
@@ -122,7 +120,8 @@ async function ensureSubagentDefinition(
  *
  * Spawns detached OpenCode CLI processes for subagent execution.
  * Each spawn ensures a CLEO subagent definition exists, then runs
- * `opencode run --format json --agent <name> --title <title> <prompt>`
+ * `opencode run --format json --agent <name> --title <title>` with the
+ * prompt piped on stdin (never in argv, T12619)
  * as a detached, unref'd child process.
  *
  * @remarks
@@ -139,15 +138,10 @@ export class OpenCodeSpawnProvider implements AdapterSpawnProvider {
   /**
    * Check if the OpenCode CLI is available in PATH.
    *
-   * @returns true if `opencode` is found via `which`
+   * @returns true if `opencode` is found on PATH (PATHEXT-aware on Windows)
    */
   async canSpawn(): Promise<boolean> {
-    try {
-      await execAsync('which opencode');
-      return true;
-    } catch {
-      return false;
-    }
+    return findOnPath('opencode') !== null;
   }
 
   /**
@@ -164,7 +158,6 @@ export class OpenCodeSpawnProvider implements AdapterSpawnProvider {
     const instanceId = `opencode-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
     const startTime = new Date().toISOString();
     const workingDirectory = context.workingDirectory ?? process.cwd();
-
     try {
       // Enrich prompt with CANT bundle, memory bridge, and mental model (T555).
       // Best-effort: if CANT context is unavailable, the raw prompt is used.
@@ -187,25 +180,26 @@ export class OpenCodeSpawnProvider implements AdapterSpawnProvider {
         agentName = OPENCODE_FALLBACK_AGENT;
       }
 
-      const child = nodeSpawn(
+      // The prompt is piped on stdin, never argv (T12619). With no positional
+      // message `opencode run` uses piped stdin AS the message (not an
+      // attachment). argv would fail on Windows — opencode is a `.cmd` shim
+      // run through cmd.exe, which cannot carry a line break and caps the line
+      // at 8191 chars — and argv is visible to every local user everywhere.
+      const child = spawnCli(
         'opencode',
-        [
-          'run',
-          '--format',
-          'json',
-          '--agent',
-          agentName,
-          '--title',
-          `CLEO ${context.taskId}`,
-          context.prompt,
-        ],
+        ['run', '--format', 'json', '--agent', agentName, '--title', `CLEO ${context.taskId}`],
         {
           cwd: workingDirectory,
           detached: true,
-          stdio: 'ignore',
+          stdio: ['pipe', 'ignore', 'ignore'],
         },
       );
 
+      // A child that dies before reading raises EPIPE on stdin; that is an
+      // exit, not an unhandled error.
+      child.stdin?.on('error', () => undefined);
+      child.stdin?.end(context.prompt, 'utf-8');
+
       child.unref();
 
       if (child.pid) {
@@ -219,6 +213,10 @@ export class OpenCodeSpawnProvider implements AdapterSpawnProvider {
       child.on('exit', () => {
         this.processMap.delete(instanceId);
       });
+      // A failed async spawn (e.g. ENOENT) emits `error` and never `exit`.
+      child.on('error', () => {
+        this.processMap.delete(instanceId);
+      });
 
       return {
         instanceId,

package/src/providers/pi/adapter.ts

@@ -16,22 +16,19 @@
  * @task T553
  */
 
-import { exec } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { promisify } from 'node:util';
 import type {
   AdapterCapabilities,
   AdapterHealthStatus,
   CLEOProviderAdapter,
 } from '@cleocode/contracts';
+import { findOnPath } from '@cleocode/paths';
 import { PiHookProvider } from './hooks.js';
 import { PiInstallProvider } from './install.js';
 import { PiSpawnProvider } from './spawn.js';
 
-const execAsync = promisify(exec);
-
 /**
  * Resolve the Pi global state root directory.
  *
@@ -163,7 +160,7 @@ export class PiAdapter implements CLEOProviderAdapter {
    *
    * Checks:
    * 1. Adapter has been initialized
-   * 2. Pi CLI is available (via PI_CLI_PATH or `which pi`)
+   * 2. Pi CLI is available (via PI_CLI_PATH or a PATH search for `pi`)
    * 3. Pi global state root (~/.pi/agent/ or PI_CODING_AGENT_DIR) exists
    *
    * @returns Health status with details about each check
@@ -182,19 +179,12 @@ export class PiAdapter implements CLEOProviderAdapter {
     // Check Pi CLI availability
     let cliAvailable = false;
     const cliPath = process.env['PI_CLI_PATH'] ?? 'pi';
-    try {
-      if (cliPath !== 'pi') {
-        const { stdout } = await execAsync(`test -x "${cliPath}" && echo ok`);
-        cliAvailable = stdout.trim() === 'ok';
-        details.cliPath = cliPath;
-      } else {
-        const { stdout } = await execAsync('which pi');
-        cliAvailable = stdout.trim().length > 0;
-        details.cliPath = stdout.trim();
-      }
-    } catch {
-      details.cliAvailable = false;
-    }
+    // PI_CLI_PATH (a path) is checked directly, a bare name searched on
+    // PATH/PATHEXT; no `test -x`/`which` shell-out (T12604).
+    const resolvedCli = findOnPath(cliPath);
+    cliAvailable = resolvedCli !== null;
+    if (resolvedCli) details.cliPath = cliPath === 'pi' ? resolvedCli : cliPath;
+    else details.cliAvailable = false;
 
     // Check for Pi global state root
     const agentDir = getPiAgentDir();

package/src/providers/pi/spawn.ts

@@ -7,18 +7,17 @@
  * subagent processes with prompts written to temporary files. Processes
  * run detached and are tracked by PID for listing and termination.
  *
- * Pi detection: `PI_CLI_PATH` env var or `which pi`.
+ * Pi detection: `PI_CLI_PATH` env var or a PATH search for `pi`.
  *
  * @task T553
  */
 
-import { exec, spawn as nodeSpawn } from 'node:child_process';
-import { unlink, writeFile } from 'node:fs/promises';
-import { promisify } from 'node:util';
+import type { SpawnOptions } from 'node:child_process';
 import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
 import { getErrorMessage } from '@cleocode/contracts';
-
-const execAsync = promisify(exec);
+import { findOnPath } from '@cleocode/paths';
+import { spawnCli } from '../shared/cli-spawn.js';
+import { removeSpawnPromptFile, writeSpawnPromptFile } from '../shared/prompt-file.js';
 
 /** Internal tracking entry for a spawned process. */
 interface TrackedProcess {
@@ -45,7 +44,7 @@ function getPiCliPath(): string {
  * prompt file as the primary argument as a detached, unref'd child process.
  *
  * @remarks
- * Prompts are written to temporary files under `/tmp/` and cleaned up
+ * Prompts are written to temporary files under a private temp directory (`os.tmpdir()`) and cleaned up
  * after the child process exits. Processes are tracked by instance ID in
  * an in-memory map and verified via `kill(pid, 0)` liveness checks.
  * All failures are best-effort and non-blocking.
@@ -57,23 +56,15 @@ export class PiSpawnProvider implements AdapterSpawnProvider {
   /**
    * Check if the Pi CLI is available.
    *
-   * Checks `PI_CLI_PATH` env var first, then tries `which pi`.
+   * Checks `PI_CLI_PATH` env var first, then searches PATH for `pi`.
    *
    * @returns true if the Pi CLI is accessible
    */
   async canSpawn(): Promise<boolean> {
     const cliPath = getPiCliPath();
-    try {
-      if (cliPath !== 'pi') {
-        // Custom path — check if it exists
-        const { stdout } = await execAsync(`test -x "${cliPath}" && echo ok`);
-        return stdout.trim() === 'ok';
-      }
-      await execAsync('which pi');
-      return true;
-    } catch {
-      return false;
-    }
+    // A custom path is checked directly, a bare name searched on PATH/PATHEXT
+    // — no `test -x`/`which` shell-out, neither exists on Windows (T12604).
+    return findOnPath(cliPath) !== null;
   }
 
   /**
@@ -91,12 +82,11 @@ export class PiSpawnProvider implements AdapterSpawnProvider {
     let tmpFile: string | undefined;
 
     try {
-      tmpFile = `/tmp/pi-spawn-${instanceId}.txt`;
-      await writeFile(tmpFile, context.prompt, 'utf-8');
+      tmpFile = await writeSpawnPromptFile('pi-spawn', context.prompt);
 
       const cliPath = getPiCliPath();
       const args = [tmpFile];
-      const spawnOpts: Parameters<typeof nodeSpawn>[2] = {
+      const spawnOpts: SpawnOptions = {
         detached: true,
         stdio: 'ignore',
       };
@@ -105,7 +95,7 @@ export class PiSpawnProvider implements AdapterSpawnProvider {
         spawnOpts.cwd = context.workingDirectory;
       }
 
-      const child = nodeSpawn(cliPath, args, spawnOpts);
+      const child = spawnCli(cliPath, args, spawnOpts);
       child.unref();
 
       if (child.pid) {
@@ -119,11 +109,7 @@ export class PiSpawnProvider implements AdapterSpawnProvider {
       const capturedTmpFile = tmpFile;
       child.on('exit', async () => {
         this.processMap.delete(instanceId);
-        try {
-          await unlink(capturedTmpFile);
-        } catch {
-          // Ignore cleanup errors
-        }
+        await removeSpawnPromptFile(capturedTmpFile);
       });
 
       return {
@@ -137,11 +123,7 @@ export class PiSpawnProvider implements AdapterSpawnProvider {
       console.error(`[PiSpawnProvider] Failed to spawn: ${getErrorMessage(error)}`);
 
       if (tmpFile) {
-        try {
-          await unlink(tmpFile);
-        } catch {
-          // Ignore cleanup errors
-        }
+        await removeSpawnPromptFile(tmpFile);
       }
 
       return {

package/src/providers/shared/__tests__/credentials-cleo-home.test.ts

@@ -0,0 +1,42 @@
+/**
+ * The legacy flat-key tier reads `<getCleoHome()>/anthropic-key` (T12602).
+ *
+ * Core's `storeAnthropicApiKey()` writes that file under `getCleoHome()`
+ * (`~/Library/Application Support/cleo` on macOS). This reader used
+ * `$XDG_DATA_HOME ?? ~/.local/share` + `cleo`, so on macOS and Windows it
+ * never saw the key core had stored.
+ *
+ * @task T12602
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveCredentials } from '../credentials.js';
+
+describe('resolveCredentials — legacy flat-key tier (T12602)', () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'cleo-adapters-cred-'));
+    const cleoHome = join(root, 'cleo-home');
+    mkdirSync(cleoHome, { recursive: true });
+    writeFileSync(join(cleoHome, 'anthropic-key'), 'sk-ant-flat-key\n');
+    vi.stubEnv('ANTHROPIC_API_KEY', undefined);
+    vi.stubEnv('CLEO_HOME', cleoHome);
+    // The old resolver read here; it is empty.
+    vi.stubEnv('XDG_DATA_HOME', join(root, 'empty-xdg'));
+    // Keep tier 3 (~/.claude/.credentials.json) off the real home dir.
+    vi.stubEnv('HOME', join(root, 'home'));
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('reads the key core stored under getCleoHome()', () => {
+    expect(resolveCredentials('anthropic')).toEqual({ apiKey: 'sk-ant-flat-key' });
+  });
+});

package/src/providers/shared/agent-spawn-wrapper.ts

@@ -35,6 +35,7 @@
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import type { AgentContainmentMode, AgentSuiteOwnership } from '@cleocode/contracts';
+import { resolveSpawnInvocation } from '@cleocode/paths';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -119,6 +120,11 @@ export interface AgentSpawnArgs {
   command: string;
   /** Full argument list. */
   args: string[];
+  /**
+   * Set (`true`) only when win32 launches a `.cmd`/`.bat` CLI through
+   * cmd.exe; pass it to `spawn` so the pre-quoted line is not re-quoted.
+   */
+  windowsVerbatimArguments?: boolean;
   /**
    * Ownership handle to persist in the session tracking record.
    *
@@ -154,7 +160,8 @@ export function buildAgentSpawnArgs(
   scopeId?: string,
 ): AgentSpawnArgs {
   if (!hasSystemdRun()) {
-    if (!_demotionLogged) {
+    // T12621: pgid is the expected mode off Linux, so only a Linux debug run hears about it.
+    if (!_demotionLogged && process.platform === 'linux' && process.env['CLEO_DEBUG']) {
       _demotionLogged = true;
       process.stderr.write(
         '[cleo:agent-spawn-wrapper] systemd-run unavailable — ' +
@@ -162,9 +169,22 @@ export function buildAgentSpawnArgs(
       );
     }
 
-    // pgid fallback: wrap with ulimit -c 0 for core suppression.
+    // pgid fallback: wrap with ulimit -c 0 for core suppression on POSIX.
+    // Windows has no `sh`/`ulimit` and writes no core files, so the command
+    // is spawned directly there (T12604).
     // The caller MUST pass { detached: true } to spawn() so that Node creates
     // a new session+pgid for this child.
+    // On win32 the CLI is resolved to its absolute path and a `.cmd` shim is
+    // routed through cmd.exe with injection-safe quoting (T12618).
+    if (process.platform === 'win32') {
+      const inv = resolveSpawnInvocation(command, args);
+      return {
+        command: inv.file,
+        args: inv.args,
+        ...(inv.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
+        ownership: { mode: 'pgid' as AgentContainmentMode },
+      };
+    }
     return {
       command: 'sh',
       args: ['-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args],

package/src/providers/shared/cli-spawn.ts

@@ -0,0 +1,41 @@
+/**
+ * Spawn a provider CLI the same way on every platform.
+ *
+ * On Windows an npm-installed CLI (`codex`, `gemini`, `opencode`, `pi`) is a
+ * `.cmd` shim. Node's bare-name lookup only tries `.exe`/`.com`, and Node
+ * refuses to spawn a `.cmd` without a shell (CVE-2024-27980), so a bare
+ * `spawn('codex', …)` failed there. {@link resolveSpawnInvocation} spawns the
+ * absolute path, routing batch files through cmd.exe with injection-safe
+ * quoting. POSIX is unchanged.
+ *
+ * @task T12618
+ */
+
+import { type ChildProcess, type SpawnOptions, spawn } from 'node:child_process';
+import { resolveSpawnInvocation } from '@cleocode/paths';
+
+/**
+ * Spawn `command args` without a user-visible shell on any platform.
+ *
+ * @param command - CLI name or path, e.g. `codex` or `PI_CLI_PATH`.
+ * @param args - Literal arguments; never interpreted by a shell.
+ * @param options - Spawn options (cwd, stdio, detached, env).
+ * @returns The child process.
+ * @throws When a win32 batch-file argument contains a line break.
+ * @example
+ * ```ts
+ * const child = spawnCli('codex', ['--full-auto', promptFile], { detached: true, stdio: 'ignore' });
+ * ```
+ */
+export function spawnCli(
+  command: string,
+  args: readonly string[],
+  options: SpawnOptions,
+): ChildProcess {
+  const inv = resolveSpawnInvocation(command, args);
+  return spawn(
+    inv.file,
+    inv.args,
+    inv.windowsVerbatimArguments ? { ...options, windowsVerbatimArguments: true } : options,
+  );
+}

package/src/providers/shared/credentials.ts

@@ -8,7 +8,7 @@
  *
  * ## Resolution tiers (first non-empty match wins)
  * 1. `ANTHROPIC_API_KEY` environment variable
- * 2. `~/.local/share/cleo/anthropic-key` (XDG-aware legacy flat-key file)
+ * 2. `<getCleoHome()>/anthropic-key` (legacy flat-key file)
  * 3. `~/.claude/.credentials.json` OAuth bearer token
  *
  * Call-sites use the same `resolveCredentials('anthropic').apiKey` pattern
@@ -24,6 +24,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { parseClaudeCodeCredentials } from '@cleocode/contracts';
+import { getCleoHome } from '@cleocode/paths';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -53,7 +54,7 @@ export interface ResolvedCredential {
  *
  * Resolution order (first non-empty match wins):
  * 1. `ANTHROPIC_API_KEY` environment variable
- * 2. `~/.local/share/cleo/anthropic-key` (XDG-aware stored key)
+ * 2. `<getCleoHome()>/anthropic-key` (stored key)
  * 3. `~/.claude/.credentials.json` Claude Code OAuth token
  *
  * Never throws — all filesystem errors are caught and treated as "not found".
@@ -74,10 +75,10 @@ export function resolveCredentials(_provider: 'anthropic'): ResolvedCredential {
   const envKey = process.env['ANTHROPIC_API_KEY'];
   if (envKey?.trim()) return { apiKey: envKey.trim() };
 
-  // Tier 2 — XDG-aware legacy flat-key file (~/.local/share/cleo/anthropic-key)
+  // Tier 2 — legacy flat-key file (<getCleoHome()>/anthropic-key), the same
+  // file core's storeAnthropicApiKey() writes.
   try {
-    const xdg = process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share');
-    const keyFile = join(xdg, 'cleo', 'anthropic-key');
+    const keyFile = join(getCleoHome(), 'anthropic-key');
     if (existsSync(keyFile)) {
       const stored = readFileSync(keyFile, 'utf-8').trim();
       if (stored) return { apiKey: stored };