@adecore/agents 0.29.0 → 0.29.2

package/dist/chat/chat-core.js

@@ -1,4 +1,3 @@
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { ChatAttachmentUploadsSchema, generatedImageAttachment, HOST_TASK_ORIGIN } from '@adecore/agent-contracts';
 import { ClientSinks } from '../client-sinks.js';
@@ -15,6 +14,7 @@ import { ChatError } from './errors.js';
 import { readableAssistantText } from './readable-text.js';
 import { SubagentReader } from './subagent-reader.js';
 import { ChatUiQueries } from './ui-queries.js';
+import { homeFolder } from '../home-folder.js';
 function withoutHidden(info) {
     const { hidden: _hidden, ...rest } = info;
     return rest;
@@ -251,7 +251,7 @@ export class ChatCore {
         const provider = this.providers.get(kind);
         const catalog = provider.catalog;
         const selection = catalog.normalize(stored?.info.selection ?? this.hooks.openingSelection?.(payload.chatId, kind) ?? payload.selection);
-        const cwd = stored?.info.cwd ?? payload.cwd ?? this.env.HOME ?? homedir();
+        const cwd = stored?.info.cwd ?? payload.cwd ?? homeFolder(this.env);
         await this.hooks.admit?.(payload.chatId, cwd);
         // A thread on disk keeps its account too. One it lost still opens, and says why on its next turn.
         // A new one without an account takes the person's pick for this CLI, which is refused rather than replaced when it went.

package/dist/chat/chat-process.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { Readable } from 'node:stream';
+import { spawnTarget } from '../windows-command.js';
 // How long an exit waits for the rest of stdout; a process the CLI started may hold the pipe open.
 const STDOUT_DRAIN_MS = 250;
 export function spawnChatProcess(options) {
@@ -7,10 +8,12 @@ export function spawnChatProcess(options) {
     if (command === undefined) {
         throw new Error('No command to start');
     }
-    const child = spawn(command, args, {
+    const target = spawnTarget(command, args, { env: options.env });
+    const child = spawn(target.file, target.args, {
         cwd: options.cwd,
         env: options.env,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsVerbatimArguments: target.windowsVerbatimArguments ?? false,
         // A group of its own, so ending the chat also ends what its agent started (a dev server, a watcher).
         // On Windows that would open a console window of its own instead; `taskkill` reaches the tree there.
         detached: process.platform !== 'win32',

package/dist/chat/subagent-reader.js

@@ -1,4 +1,4 @@
-import { dirname } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { workflowAgentIdOf } from '@adecore/agent-contracts';
 import { SYSTEM_WATCH } from '../watch-seam.js';
 import { findSubagentsDir, findWorkflowAgent, readSubagentMetas, TranscriptProjection } from './claude-transcript.js';
@@ -340,7 +340,7 @@ export class SubagentReader {
         for (const key of this.dirWatches.get(dir)?.keys ?? []) {
             const path = this.claudeFiles.get(key)?.path;
             // A platform that names no file could mean any of them.
-            if (filename === null || (path !== undefined && path.endsWith(`/${filename}`))) {
+            if (filename === null || (path !== undefined && basename(path) === filename)) {
                 this.markChanged(key);
             }
         }

package/dist/fs.d.ts

@@ -6,4 +6,7 @@ export declare function writeAtomic(target: string, content: string | Uint8Array
 export declare function replaceSync(temp: string, target: string): void;
 export declare function writeAtomicSync(target: string, content: string | Uint8Array, mode?: number): void;
 export declare function isNotFound(e: unknown): boolean;
+export declare function removeFile(path: string, remove?: (path: string, options: {
+    force: true;
+}) => Promise<void>): Promise<void>;
 export declare function fileExists(path: string): Promise<boolean>;

package/dist/fs.js

@@ -1,5 +1,5 @@
 import { renameSync, writeFileSync } from 'node:fs';
-import { open, rename, stat, writeFile } from 'node:fs/promises';
+import { open, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 // Windows can refuse a rename while a watcher or an indexer holds the target; a few short retries cover it.
 const RENAME_RETRIES = 5;
@@ -96,6 +96,17 @@ export function writeAtomicSync(target, content, mode = 0o600) {
 export function isNotFound(e) {
     return typeof e === 'object' && e !== null && 'code' in e && e.code === 'ENOENT';
 }
+// Bun on Windows fails a forced rm with EFAULT while another delete of the same file is pending; it goes either way.
+export async function removeFile(path, remove = rm) {
+    try {
+        await remove(path, { force: true });
+    }
+    catch (e) {
+        if (!(typeof e === 'object' && e !== null && 'code' in e && e.code === 'EFAULT')) {
+            throw e;
+        }
+    }
+}
 export async function fileExists(path) {
     try {
         await stat(path);

package/dist/home-folder.d.ts

@@ -0,0 +1 @@
+export declare function homeFolder(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string;

package/dist/home-folder.js

@@ -0,0 +1,8 @@
+import { homedir } from 'node:os';
+/*
+ * The home folder the CLIs read their config from. On Windows they take it from USERPROFILE, as Node
+ * does; a HOME there is often Git Bash's `/c/Users/...`, which no native program can open.
+ */
+export function homeFolder(env, platform = process.platform) {
+    return (platform === 'win32' ? env.USERPROFILE : env.HOME) || homedir();
+}

package/dist/providers/accounts/accounts.js

@@ -1,7 +1,7 @@
-import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { AgentKindSchema, ProviderAccountSchema } from '@adecore/agent-contracts';
 import { DEFAULT_ACCOUNTS_HOST, variablesProblem } from './variables.js';
+import { homeFolder } from '../../home-folder.js';
 const KNOWN_KINDS = AgentKindSchema.options;
 export function isKnownKind(kind) {
     return KNOWN_KINDS.includes(kind);
@@ -11,11 +11,11 @@ export function isDefaultAccount(id, account) {
     return id === account.kind;
 }
 export function expandHome(path, env) {
-    const home = env.HOME ?? homedir();
+    const home = homeFolder(env);
     if (path === '~') {
         return home;
     }
-    if (path.startsWith('~/')) {
+    if (path.startsWith('~/') || (process.platform === 'win32' && path.startsWith('~\\'))) {
         return join(home, path.slice(2));
     }
     return resolve(path);
@@ -85,7 +85,7 @@ export function defaultFolder(provider, env) {
     if (provider.home === undefined) {
         return '';
     }
-    return env[provider.home.env] ?? join(env.HOME ?? homedir(), provider.home.fallback);
+    return env[provider.home.env] ?? join(homeFolder(env), provider.home.fallback);
 }
 /* The folder a CLI of this account is started with: for a Codex account with a shadow home, that one. */
 export function accountFolder(id, account, provider, env) {

package/dist/providers/codex-rules.js

@@ -1,8 +1,8 @@
 import { mkdir, readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { errorText } from '../error-text.js';
 import { isNotFound, writeAtomic } from '../fs.js';
+import { homeFolder } from '../home-folder.js';
 export function codexRulesText(rules) {
     return ([
         `# Written by ${rules.app}; it is rewritten when it changes.`,
@@ -14,7 +14,7 @@ export function codexRulesPathIn(folder, rules) {
     return join(folder, 'rules', `${rules.app.toLowerCase().replace(/[^a-z0-9]+/g, '-')}.rules`);
 }
 export function defaultCodexHome(env = process.env) {
-    return env.CODEX_HOME ?? join(env.HOME ?? homedir(), '.codex');
+    return env.CODEX_HOME ?? join(homeFolder(env), '.codex');
 }
 /* Idempotent: a file that already says the same is left alone. */
 export async function installCodexRules(path, rules) {

package/dist/record-directory.js

@@ -1,6 +1,6 @@
-import { mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isNotFound, writeAtomic } from './fs.js';
+import { isNotFound, removeFile, writeAtomic } from './fs.js';
 import { KeyedSerializer } from './serializer.js';
 // The id is a node id or a chat id a client chose, so it is encoded before it becomes a file name.
 export function recordFileName(id) {
@@ -59,7 +59,7 @@ export class RecordDirectory {
             }
             const record = this.keep === null ? parsed.data : this.keep(parsed.data);
             if (record === null) {
-                await rm(join(this.dir, name), { force: true });
+                await removeFile(join(this.dir, name));
                 continue;
             }
             this.records.set(this.idOf(record), record);
@@ -89,7 +89,7 @@ export class RecordDirectory {
             await mkdir(this.dir, { recursive: true, mode: 0o700 });
             await this.writeFile(this.pathOf(id), JSON.stringify(record));
             if (!this.records.has(id)) {
-                await rm(this.pathOf(id), { force: true });
+                await removeFile(this.pathOf(id));
                 return false;
             }
             return true;
@@ -98,7 +98,7 @@ export class RecordDirectory {
     /* Forgets a record here and now; its file follows. */
     remove(id) {
         this.records.delete(id);
-        return rm(this.pathOf(id), { force: true });
+        return removeFile(this.pathOf(id));
     }
     async prune(drop) {
         for (const listed of this.all()) {

package/dist/run-process.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { killProcessTree } from './chat/chat-process.js';
+import { spawnTarget } from './windows-command.js';
 // What a command and everything it started get between the SIGTERM and the SIGKILL.
 const KILL_GRACE_MS = 2000;
 // Stdout and stderr together; a short command that prints more is ended and fails instead of filling memory.
@@ -12,10 +13,12 @@ export function runProcess(command, options = {}) {
             reject(new Error('No command to run'));
             return;
         }
-        const child = spawn(executable, args, {
+        const target = spawnTarget(executable, args, options.env === undefined ? {} : { env: options.env });
+        const child = spawn(target.file, target.args, {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
             ...(options.env === undefined ? {} : { env: options.env }),
             stdio: [options.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            windowsVerbatimArguments: target.windowsVerbatimArguments ?? false,
             // A group of its own, so ending the command also ends what it started; Windows ends the tree through `taskkill`.
             detached: process.platform !== 'win32',
             windowsHide: true

package/dist/usage/roots.js

@@ -1,10 +1,10 @@
-import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { homeFolder } from '../home-folder.js';
 /* Where in its config folder each CLI leaves its transcripts. */
 const TRANSCRIPTS = { claude: 'projects', codex: 'sessions' };
 /* The transcripts of the default accounts, found through the variables the CLIs themselves read. */
 export function usageRoots(env = process.env) {
-    const home = env.HOME ?? homedir();
+    const home = homeFolder(env);
     return [
         { provider: 'claude', path: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), TRANSCRIPTS.claude) },
         { provider: 'codex', path: join(env.CODEX_HOME ?? join(home, '.codex'), TRANSCRIPTS.codex) }

package/dist/windows-command.d.ts

@@ -0,0 +1,11 @@
+export interface SpawnTarget {
+    file: string;
+    args: string[];
+    windowsVerbatimArguments?: boolean;
+}
+export interface SpawnTargetOptions {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    isFile?(path: string): boolean;
+}
+export declare function spawnTarget(command: string, args: readonly string[], options?: SpawnTargetOptions): SpawnTarget;

package/dist/windows-command.js

@@ -0,0 +1,71 @@
+import { statSync } from 'node:fs';
+import { win32 } from 'node:path';
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+// What cmd.exe reads as syntax outside quotes, and so escapes with a caret.
+const CMD_SPECIAL = /([()\][%!^"`<>&|;, *?])/g;
+/*
+ * The file and arguments a spawn starts a command with. On Windows a bare name is looked up on the
+ * PATH with PATHEXT, which CreateProcess does not do, and a `.cmd` or `.bat` (npm installs every CLI
+ * as one) runs through cmd.exe, as CreateProcess cannot start a batch file itself. Elsewhere nothing changes.
+ */
+export function spawnTarget(command, args, options = {}) {
+    const { env = process.env, platform = process.platform, isFile = existingFile } = options;
+    if (platform !== 'win32') {
+        return { file: command, args: [...args] };
+    }
+    const resolved = findOnPath(command, env, isFile) ?? command;
+    if (!/\.(cmd|bat)$/i.test(resolved)) {
+        return { file: resolved, args: [...args] };
+    }
+    const line = [escapeForCmd(resolved), ...args.map((arg) => escapeForCmd(escapeForCmd(quoteArgument(arg))))].join(' ');
+    return { file: variable(env, 'ComSpec') ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], windowsVerbatimArguments: true };
+}
+function findOnPath(command, env, isFile) {
+    const extensions = (variable(env, 'PATHEXT') ?? DEFAULT_PATHEXT)
+        .split(';')
+        .map((extension) => extension.trim().toLowerCase())
+        .filter((extension) => extension !== '');
+    const hasExtension = extensions.includes(win32.extname(command).toLowerCase());
+    const folders = /[\\/]/.test(command)
+        ? ['']
+        : (variable(env, 'PATH') ?? '')
+            .split(';')
+            .map((folder) => folder.trim().replace(/^"(.*)"$/, '$1'))
+            .filter((folder) => folder !== '');
+    for (const folder of folders) {
+        const base = folder === '' ? command : win32.join(folder, command);
+        const candidates = hasExtension ? [base] : extensions.map((extension) => `${base}${extension}`);
+        const found = candidates.find((candidate) => isFile(candidate));
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return null;
+}
+// Windows treats variable names case-insensitively, and an environment often carries `Path`.
+function variable(env, name) {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase());
+    return key === undefined ? undefined : env[key];
+}
+/* One argument as the C runtime splits a command line: quotes around it, a quote and the backslashes before it escaped. */
+function quoteArgument(arg) {
+    if (/[\r\n]/.test(arg)) {
+        throw new Error('An argument to a batch file cannot hold a line break');
+    }
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}
+/*
+ * Carets keep cmd.exe from reading the argument as syntax. An argument gets them twice: cmd.exe takes
+ * one set as it runs the line, and the batch file reads them again where it hands `%*` on.
+ */
+function escapeForCmd(text) {
+    return text.replace(CMD_SPECIAL, '^$1');
+}
+function existingFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agents",
-  "version": "0.29.0",
+  "version": "0.29.2",
   "description": "Node-compatible agent chat hosts, providers, accounts, usage and durable task coordination.",
   "type": "module",
   "exports": {
@@ -81,8 +81,8 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/agent-contracts": "0.29.0",
-    "@adecore/intelligent-ui": "0.29.0",
+    "@adecore/agent-contracts": "0.29.2",
+    "@adecore/intelligent-ui": "0.29.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat/chat-core.ts

@@ -1,4 +1,3 @@
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import {
     ChatAttachmentUploadsSchema,
@@ -64,6 +63,7 @@ import { readableAssistantText } from './readable-text.ts';
 import { SubagentReader, type SubagentReaderOptions } from './subagent-reader.ts';
 import { ChatUiQueries, type ChatUiHost } from './ui-queries.ts';
 import type { VisualInput, VisualStore } from './visual-store.ts';
+import { homeFolder } from '../home-folder.ts';
 
 /* A turn that was running when the host went down, and the attempt that would take it up again. */
 export interface InterruptedRun {
@@ -442,7 +442,7 @@ export class ChatCore {
         const provider = this.providers.get(kind);
         const catalog = provider.catalog;
         const selection = catalog.normalize(stored?.info.selection ?? this.hooks.openingSelection?.(payload.chatId, kind) ?? payload.selection);
-        const cwd = stored?.info.cwd ?? payload.cwd ?? this.env.HOME ?? homedir();
+        const cwd = stored?.info.cwd ?? payload.cwd ?? homeFolder(this.env);
         await this.hooks.admit?.(payload.chatId, cwd);
         // A thread on disk keeps its account too. One it lost still opens, and says why on its next turn.
         // A new one without an account takes the person's pick for this CLI, which is refused rather than replaced when it went.

package/src/chat/chat-process.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { Readable } from 'node:stream';
+import { spawnTarget } from '../windows-command.ts';
 
 /*
  * The part of a child process a chat backend talks to: lines in over stdin, lines out over stdout,
@@ -37,10 +38,12 @@ export function spawnChatProcess(options: ChatSpawnOptions): ChatProcess {
     if (command === undefined) {
         throw new Error('No command to start');
     }
-    const child = spawn(command, args, {
+    const target = spawnTarget(command, args, { env: options.env });
+    const child = spawn(target.file, target.args, {
         cwd: options.cwd,
         env: options.env,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsVerbatimArguments: target.windowsVerbatimArguments ?? false,
         // A group of its own, so ending the chat also ends what its agent started (a dev server, a watcher).
         // On Windows that would open a console window of its own instead; `taskkill` reaches the tree there.
         detached: process.platform !== 'win32',

package/src/chat/subagent-reader.ts

@@ -1,4 +1,4 @@
-import { dirname } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { workflowAgentIdOf, type ChatInfo, type ChatItem, type ChatSubagentChangedEvent, type ChatSubagentResult } from '@adecore/agent-contracts';
 import { SYSTEM_WATCH, type DirectoryWatcher, type WatchSeams } from '../watch-seam.ts';
 import { findSubagentsDir, findWorkflowAgent, readSubagentMetas, TranscriptProjection, type SubagentMeta } from './claude-transcript.ts';
@@ -411,7 +411,7 @@ export class SubagentReader {
         for (const key of this.dirWatches.get(dir)?.keys ?? []) {
             const path = this.claudeFiles.get(key)?.path;
             // A platform that names no file could mean any of them.
-            if (filename === null || (path !== undefined && path.endsWith(`/${filename}`))) {
+            if (filename === null || (path !== undefined && basename(path) === filename)) {
                 this.markChanged(key);
             }
         }

package/src/fs.ts

@@ -1,5 +1,5 @@
 import { renameSync, writeFileSync } from 'node:fs';
-import { open, rename, stat, writeFile } from 'node:fs/promises';
+import { open, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
 // Windows can refuse a rename while a watcher or an indexer holds the target; a few short retries cover it.
@@ -108,6 +108,17 @@ export function isNotFound(e: unknown): boolean {
     return typeof e === 'object' && e !== null && 'code' in e && e.code === 'ENOENT';
 }
 
+// Bun on Windows fails a forced rm with EFAULT while another delete of the same file is pending; it goes either way.
+export async function removeFile(path: string, remove: (path: string, options: { force: true }) => Promise<void> = rm): Promise<void> {
+    try {
+        await remove(path, { force: true });
+    } catch (e) {
+        if (!(typeof e === 'object' && e !== null && 'code' in e && e.code === 'EFAULT')) {
+            throw e;
+        }
+    }
+}
+
 export async function fileExists(path: string): Promise<boolean> {
     try {
         await stat(path);

package/src/home-folder.ts

@@ -0,0 +1,9 @@
+import { homedir } from 'node:os';
+
+/*
+ * The home folder the CLIs read their config from. On Windows they take it from USERPROFILE, as Node
+ * does; a HOME there is often Git Bash's `/c/Users/...`, which no native program can open.
+ */
+export function homeFolder(env: Record<string, string | undefined>, platform: NodeJS.Platform = process.platform): string {
+    return (platform === 'win32' ? env.USERPROFILE : env.HOME) || homedir();
+}

package/src/providers/accounts/accounts.ts

@@ -1,8 +1,8 @@
-import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { AgentKindSchema, ProviderAccountSchema, type AgentKind, type ProviderAccount, type ProviderAccountMap } from '@adecore/agent-contracts';
 import type { ChatProvider } from '../provider.ts';
 import { DEFAULT_ACCOUNTS_HOST, variablesProblem, type AccountsHost, type ReservedVariables } from './variables.ts';
+import { homeFolder } from '../../home-folder.ts';
 
 export type Env = Record<string, string | undefined>;
 
@@ -18,11 +18,11 @@ export function isDefaultAccount(id: string, account: Pick<ProviderAccount, 'kin
 }
 
 export function expandHome(path: string, env: Env): string {
-    const home = env.HOME ?? homedir();
+    const home = homeFolder(env);
     if (path === '~') {
         return home;
     }
-    if (path.startsWith('~/')) {
+    if (path.startsWith('~/') || (process.platform === 'win32' && path.startsWith('~\\'))) {
         return join(home, path.slice(2));
     }
     return resolve(path);
@@ -103,7 +103,7 @@ export function defaultFolder(provider: ChatProvider, env: Env): string {
     if (provider.home === undefined) {
         return '';
     }
-    return env[provider.home.env] ?? join(env.HOME ?? homedir(), provider.home.fallback);
+    return env[provider.home.env] ?? join(homeFolder(env), provider.home.fallback);
 }
 
 /* The folder a CLI of this account is started with: for a Codex account with a shadow home, that one. */

package/src/providers/codex-rules.ts

@@ -1,8 +1,8 @@
 import { mkdir, readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { errorText } from '../error-text.ts';
 import { isNotFound, writeAtomic } from '../fs.ts';
+import { homeFolder } from '../home-folder.ts';
 
 /*
  * The commands a host lets Codex run outside its sandbox without asking: the seatbelt of
@@ -33,7 +33,7 @@ export function codexRulesPathIn(folder: string, rules: CodexRules): string {
 }
 
 export function defaultCodexHome(env: Record<string, string | undefined> = process.env): string {
-    return env.CODEX_HOME ?? join(env.HOME ?? homedir(), '.codex');
+    return env.CODEX_HOME ?? join(homeFolder(env), '.codex');
 }
 
 /* Idempotent: a file that already says the same is left alone. */

package/src/record-directory.ts

@@ -1,7 +1,7 @@
-import { mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { mkdir, readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { z } from 'zod';
-import { isNotFound, writeAtomic } from './fs.ts';
+import { isNotFound, removeFile, writeAtomic } from './fs.ts';
 import { KeyedSerializer } from './serializer.ts';
 
 // The id is a node id or a chat id a client chose, so it is encoded before it becomes a file name.
@@ -74,7 +74,7 @@ export class RecordDirectory<T> {
             }
             const record = this.keep === null ? parsed.data : this.keep(parsed.data);
             if (record === null) {
-                await rm(join(this.dir, name), { force: true });
+                await removeFile(join(this.dir, name));
                 continue;
             }
             this.records.set(this.idOf(record), record);
@@ -108,7 +108,7 @@ export class RecordDirectory<T> {
             await mkdir(this.dir, { recursive: true, mode: 0o700 });
             await this.writeFile(this.pathOf(id), JSON.stringify(record));
             if (!this.records.has(id)) {
-                await rm(this.pathOf(id), { force: true });
+                await removeFile(this.pathOf(id));
                 return false;
             }
             return true;
@@ -118,7 +118,7 @@ export class RecordDirectory<T> {
     /* Forgets a record here and now; its file follows. */
     remove(id: string): Promise<void> {
         this.records.delete(id);
-        return rm(this.pathOf(id), { force: true });
+        return removeFile(this.pathOf(id));
     }
 
     async prune(drop: (record: T) => boolean): Promise<void> {

package/src/run-process.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { killProcessTree } from './chat/chat-process.ts';
+import { spawnTarget } from './windows-command.ts';
 
 export interface ProcessResult {
     // Null when the process ended on a signal.
@@ -31,10 +32,12 @@ export function runProcess(command: readonly string[], options: RunProcessOption
             reject(new Error('No command to run'));
             return;
         }
-        const child = spawn(executable, args, {
+        const target = spawnTarget(executable, args, options.env === undefined ? {} : { env: options.env });
+        const child = spawn(target.file, target.args, {
             ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
             ...(options.env === undefined ? {} : { env: options.env }),
             stdio: [options.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            windowsVerbatimArguments: target.windowsVerbatimArguments ?? false,
             // A group of its own, so ending the command also ends what it started; Windows ends the tree through `taskkill`.
             detached: process.platform !== 'win32',
             windowsHide: true

package/src/usage/roots.ts

@@ -1,6 +1,6 @@
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { UsageProvider } from '@adecore/agent-contracts';
+import { homeFolder } from '../home-folder.ts';
 
 export interface UsageRootPath {
     provider: UsageProvider;
@@ -14,7 +14,7 @@ const TRANSCRIPTS: Record<UsageProvider, string> = { claude: 'projects', codex:
 
 /* The transcripts of the default accounts, found through the variables the CLIs themselves read. */
 export function usageRoots(env: Record<string, string | undefined> = process.env): UsageRootPath[] {
-    const home = env.HOME ?? homedir();
+    const home = homeFolder(env);
     return [
         { provider: 'claude', path: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), TRANSCRIPTS.claude) },
         { provider: 'codex', path: join(env.CODEX_HOME ?? join(home, '.codex'), TRANSCRIPTS.codex) }

package/src/windows-command.ts

@@ -0,0 +1,90 @@
+import { statSync } from 'node:fs';
+import { win32 } from 'node:path';
+
+export interface SpawnTarget {
+    file: string;
+    args: string[];
+    // Set for a batch file: the command line is quoted here, so the spawn must pass it on unchanged.
+    windowsVerbatimArguments?: boolean;
+}
+
+export interface SpawnTargetOptions {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    isFile?(path: string): boolean;
+}
+
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+// What cmd.exe reads as syntax outside quotes, and so escapes with a caret.
+const CMD_SPECIAL = /([()\][%!^"`<>&|;, *?])/g;
+
+/*
+ * The file and arguments a spawn starts a command with. On Windows a bare name is looked up on the
+ * PATH with PATHEXT, which CreateProcess does not do, and a `.cmd` or `.bat` (npm installs every CLI
+ * as one) runs through cmd.exe, as CreateProcess cannot start a batch file itself. Elsewhere nothing changes.
+ */
+export function spawnTarget(command: string, args: readonly string[], options: SpawnTargetOptions = {}): SpawnTarget {
+    const { env = process.env, platform = process.platform, isFile = existingFile } = options;
+    if (platform !== 'win32') {
+        return { file: command, args: [...args] };
+    }
+    const resolved = findOnPath(command, env, isFile) ?? command;
+    if (!/\.(cmd|bat)$/i.test(resolved)) {
+        return { file: resolved, args: [...args] };
+    }
+    const line = [escapeForCmd(resolved), ...args.map((arg) => escapeForCmd(escapeForCmd(quoteArgument(arg))))].join(' ');
+    return { file: variable(env, 'ComSpec') ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], windowsVerbatimArguments: true };
+}
+
+function findOnPath(command: string, env: Record<string, string | undefined>, isFile: (path: string) => boolean): string | null {
+    const extensions = (variable(env, 'PATHEXT') ?? DEFAULT_PATHEXT)
+        .split(';')
+        .map((extension) => extension.trim().toLowerCase())
+        .filter((extension) => extension !== '');
+    const hasExtension = extensions.includes(win32.extname(command).toLowerCase());
+    const folders = /[\\/]/.test(command)
+        ? ['']
+        : (variable(env, 'PATH') ?? '')
+              .split(';')
+              .map((folder) => folder.trim().replace(/^"(.*)"$/, '$1'))
+              .filter((folder) => folder !== '');
+    for (const folder of folders) {
+        const base = folder === '' ? command : win32.join(folder, command);
+        const candidates = hasExtension ? [base] : extensions.map((extension) => `${base}${extension}`);
+        const found = candidates.find((candidate) => isFile(candidate));
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return null;
+}
+
+// Windows treats variable names case-insensitively, and an environment often carries `Path`.
+function variable(env: Record<string, string | undefined>, name: string): string | undefined {
+    const key = Object.keys(env).find((candidate) => candidate.toUpperCase() === name.toUpperCase());
+    return key === undefined ? undefined : env[key];
+}
+
+/* One argument as the C runtime splits a command line: quotes around it, a quote and the backslashes before it escaped. */
+function quoteArgument(arg: string): string {
+    if (/[\r\n]/.test(arg)) {
+        throw new Error('An argument to a batch file cannot hold a line break');
+    }
+    return `"${arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}
+
+/*
+ * Carets keep cmd.exe from reading the argument as syntax. An argument gets them twice: cmd.exe takes
+ * one set as it runs the line, and the batch file reads them again where it hands `%*` on.
+ */
+function escapeForCmd(text: string): string {
+    return text.replace(CMD_SPECIAL, '^$1');
+}
+
+function existingFile(path: string): boolean {
+    try {
+        return statSync(path).isFile();
+    } catch {
+        return false;
+    }
+}