@adecore/agents 0.29.1 → 0.29.3

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/chat-session.d.ts

@@ -104,6 +104,7 @@ export declare class ChatSession {
     private staleResults;
     private spokenTurnId;
     private titleTimer;
+    private readonly checkpointWork;
     private naming;
     private frozen;
     private readonly subagentOwners;
@@ -232,6 +233,7 @@ export declare class ChatSession {
     private settleAgentTurn;
     private checkpoint;
     private settleCheckpoint;
+    private trackCheckpoint;
     private contextNote;
     private submit;
     private acceptPrompt;

package/dist/chat/chat-session.js

@@ -71,6 +71,8 @@ export class ChatSession {
     // The last turn the main agent spoke in; a turn opened only for a subagent's request gets no `result`.
     spokenTurnId = null;
     titleTimer = null;
+    /* Checkpoints still asking git, which `dispose` waits for: the host may remove the folder next. */
+    checkpointWork = new Set();
     // A name is asked for once per chat this host holds; the turn count keeps it once across restarts.
     naming = false;
     // Set while the host goes down: a CLI dying with it must not end the turn a restart takes up again.
@@ -1126,7 +1128,7 @@ export class ChatSession {
         this.frozen = true;
         this.backend?.stop();
     }
-    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL. */
+    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL and no checkpoint asks git any more. */
     dispose() {
         this.uiReplies.clear();
         this.clearStartWarning();
@@ -1138,7 +1140,7 @@ export class ChatSession {
         const ended = this.backend?.dispose() ?? Promise.resolve();
         this.backend = null;
         this.starting = null;
-        return ended;
+        return Promise.all([ended, ...this.checkpointWork]).then(() => undefined);
     }
     /* What a turn changed against its checkpoint: the stored answer, or one taken now while it runs. */
     async turnDiff(turnId) {
@@ -1412,15 +1414,13 @@ export class ChatSession {
             return Promise.resolve();
         }
         const cwd = this.thread.info.cwd;
-        return Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null])
-            .then(([tree, head]) => {
+        return this.trackCheckpoint(Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null]).then(([tree, head]) => {
             const turn = this.thread.get(turnId);
             if (tree === null || turn?.kind !== 'turn' || turn.state !== 'running' || this.info.activeTurnId !== turnId) {
                 return;
             }
             this.emit([this.thread.upsert({ ...turn, checkpoint: tree, ...(head === null ? {} : { checkpointHead: head }) })]);
-        })
-            .catch(() => undefined);
+        }));
     }
     /* The diff of a turn that just ended, so a reload shows it without asking git again, and the tree a fork after it starts from. */
     settleCheckpoint(turnId) {
@@ -1430,8 +1430,7 @@ export class ChatSession {
         }
         const { checkpoints } = this.options;
         const cwd = this.thread.info.cwd;
-        void Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null])
-            .then(([answer, head]) => {
+        void this.trackCheckpoint(Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null]).then(([answer, head]) => {
             const settled = this.thread.get(turnId);
             if (answer === null || settled?.kind !== 'turn') {
                 return;
@@ -1445,8 +1444,13 @@ export class ChatSession {
                 })
             ]);
             this.options.persist();
-        })
-            .catch(() => undefined);
+        }));
+    }
+    /* Keeps the work in `checkpointWork` until it settled; a failure leaves the turn without a checkpoint. */
+    trackCheckpoint(work) {
+        const tracked = work.catch(() => undefined).finally(() => this.checkpointWork.delete(tracked));
+        this.checkpointWork.add(tracked);
+        return tracked;
     }
     /*
      * What the agent has to hear before this prompt: what the chat kept for it and what the host says.

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/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/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.1",
+  "version": "0.29.3",
   "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.1",
-    "@adecore/intelligent-ui": "0.29.1",
+    "@adecore/agent-contracts": "0.29.3",
+    "@adecore/intelligent-ui": "0.29.3",
     "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/chat-session.ts

@@ -198,6 +198,8 @@ export class ChatSession {
     // The last turn the main agent spoke in; a turn opened only for a subagent's request gets no `result`.
     private spokenTurnId: string | null = null;
     private titleTimer: ReturnType<typeof setTimeout> | null = null;
+    /* Checkpoints still asking git, which `dispose` waits for: the host may remove the folder next. */
+    private readonly checkpointWork = new Set<Promise<void>>();
     // A name is asked for once per chat this host holds; the turn count keeps it once across restarts.
     private naming = false;
     // Set while the host goes down: a CLI dying with it must not end the turn a restart takes up again.
@@ -1341,7 +1343,7 @@ export class ChatSession {
         this.backend?.stop();
     }
 
-    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL. */
+    /* Ends the CLI and everything it started; settles once it exited or was sent the SIGKILL and no checkpoint asks git any more. */
     dispose(): Promise<void> {
         this.uiReplies.clear();
         this.clearStartWarning();
@@ -1353,7 +1355,7 @@ export class ChatSession {
         const ended = this.backend?.dispose() ?? Promise.resolve();
         this.backend = null;
         this.starting = null;
-        return ended;
+        return Promise.all([ended, ...this.checkpointWork]).then(() => undefined);
     }
 
     /* What a turn changed against its checkpoint: the stored answer, or one taken now while it runs. */
@@ -1645,15 +1647,15 @@ export class ChatSession {
             return Promise.resolve();
         }
         const cwd = this.thread.info.cwd;
-        return Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null])
-            .then(([tree, head]) => {
+        return this.trackCheckpoint(
+            Promise.all([checkpoints.take(cwd), checkpoints.head?.(cwd) ?? null]).then(([tree, head]) => {
                 const turn = this.thread.get(turnId);
                 if (tree === null || turn?.kind !== 'turn' || turn.state !== 'running' || this.info.activeTurnId !== turnId) {
                     return;
                 }
                 this.emit([this.thread.upsert({ ...turn, checkpoint: tree, ...(head === null ? {} : { checkpointHead: head }) })]);
             })
-            .catch(() => undefined);
+        );
     }
 
     /* The diff of a turn that just ended, so a reload shows it without asking git again, and the tree a fork after it starts from. */
@@ -1664,8 +1666,8 @@ export class ChatSession {
         }
         const { checkpoints } = this.options;
         const cwd = this.thread.info.cwd;
-        void Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null])
-            .then(([answer, head]) => {
+        void this.trackCheckpoint(
+            Promise.all([checkpoints.settle(cwd, turn.checkpoint), checkpoints.head?.(cwd) ?? null]).then(([answer, head]) => {
                 const settled = this.thread.get(turnId);
                 if (answer === null || settled?.kind !== 'turn') {
                     return;
@@ -1680,7 +1682,14 @@ export class ChatSession {
                 ]);
                 this.options.persist();
             })
-            .catch(() => undefined);
+        );
+    }
+
+    /* Keeps the work in `checkpointWork` until it settled; a failure leaves the turn without a checkpoint. */
+    private trackCheckpoint(work: Promise<void>): Promise<void> {
+        const tracked = work.catch(() => undefined).finally(() => this.checkpointWork.delete(tracked));
+        this.checkpointWork.add(tracked);
+        return tracked;
     }
 
     /*

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/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/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;
+    }
+}