claude-memory-admin 1.10.0 → 1.10.2

package/src/parse.mjs

@@ -24,6 +24,36 @@ const WIKILINK = /\[\[([^\]|]+)(?:\|([^\]]*))?\]\]/g;
 /** Leading hook separator: em dash, en dash, hyphen or colon. */
 const HOOK_SEP = /^[ \t]*(?:—|–|-|:)[ \t]*/;
 
+/**
+ * A line with its carriage return taken off, for matching only.
+ *
+ * Every classifying regex here ends in `$`, and JavaScript's `.` does not match
+ * a carriage return, so on a CRLF file each of them fails on the last character
+ * and the file parses as if it held nothing: no index entries, no frontmatter,
+ * every memory an orphan. Splitting on /\r?\n/ instead would fix the matching
+ * and break the promise that matters more - that a file is rewritten byte for
+ * byte - because it would rewrite a CRLF file as LF. So the return stays on the
+ * stored line and comes off only for the match.
+ */
+export function forMatch(line) {
+  return typeof line === 'string' && line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+
+/**
+ * The carriage return a line added to this file should end with, so a new entry
+ * matches the file it joins rather than making it half one thing and half the
+ * other. Decided by what most of the file already does.
+ */
+export function fileEol(lines) {
+  let crlf = 0;
+  let lf = 0;
+  for (let i = 0; i < lines.length - 1; i++) {
+    if (lines[i].endsWith('\r')) crlf += 1;
+    else lf += 1;
+  }
+  return crlf > lf ? '\r' : '';
+}
+
 function unquote(value) {
   const trimmed = value.trim();
   if (trimmed.length >= 2) {
@@ -50,7 +80,7 @@ function readYaml(lines) {
     const withoutComment = raw.trimStart().startsWith('#') ? '' : raw;
     if (!withoutComment.trim()) continue;
 
-    const match = withoutComment.match(/^([ \t]*)([A-Za-z0-9_.\-]+):[ \t]*(.*)$/);
+    const match = forMatch(withoutComment).match(/^([ \t]*)([A-Za-z0-9_.\-]+):[ \t]*(.*)$/);
     if (!match) continue;
 
     const [, indent, key, rest] = match;
@@ -103,7 +133,7 @@ export function parseFrontmatter(text) {
   return {
     data: readYaml(block),
     raw: block.join('\n'),
-    body: lines.slice(end + 1).join('\n').replace(/^\n+/, ''),
+    body: lines.slice(end + 1).join('\n').replace(/^(?:\r?\n)+/, ''),
     hasFrontmatter: true,
   };
 }
@@ -140,12 +170,12 @@ export function parseIndex(text) {
   let section = null;
 
   lines.forEach((line, i) => {
-    const heading = line.match(/^(#{1,6})[ \t]+(.*)$/);
+    const heading = forMatch(line).match(/^(#{1,6})[ \t]+(.*)$/);
     if (heading) {
       section = heading[2].trim();
       parsedLines.push({ index: i, kind: 'heading', text: line, level: heading[1].length, section });
     } else {
-      const indexMatch = line.match(INDEX_LINE);
+      const indexMatch = forMatch(line).match(INDEX_LINE);
       // Only an unindented bullet is an index entry. An indented one is a
       // sub-bullet of surrounding prose and must not be treated as a pointer.
       if (indexMatch && indexMatch[1] === '') {
@@ -255,19 +285,23 @@ export function unwrapWikilink(text, target) {
 }
 
 function splitEntryLine(line) {
-  const match = line.match(INDEX_LINE);
+  const body = forMatch(line);
+  const match = body.match(INDEX_LINE);
   if (!match || match[1] !== '') return null;
   const file = match[3];
   const marker = `](${file})`;
-  const linkEnd = line.indexOf(marker) + marker.length;
-  const tail = line.slice(linkEnd);
+  const linkEnd = body.indexOf(marker) + marker.length;
+  const tail = body.slice(linkEnd);
   const separator = tail.match(HOOK_SEP);
   return {
-    head: line.slice(0, linkEnd),
+    head: body.slice(0, linkEnd),
     title: match[2].trim(),
     file,
     separator: separator ? separator[0] : null,
     hook: tail.replace(HOOK_SEP, ''),
+    // Carried so a rewritten line ends the way the line it replaces did. A file
+    // that comes back half CRLF and half LF is a file this tool corrupted.
+    eol: line.endsWith('\r') ? '\r' : '',
   };
 }
 
@@ -317,7 +351,7 @@ export function setIndexHook(text, index, expectedText, hook) {
 
   const separator = parts.separator || dominantSeparator(parseIndex(text));
   const before = lines[index];
-  lines[index] = trimmed ? `${parts.head}${separator}${trimmed}` : parts.head;
+  lines[index] = (trimmed ? `${parts.head}${separator}${trimmed}` : parts.head) + parts.eol;
   return { text: lines.join('\n'), before, after: lines[index] };
 }
 
@@ -396,7 +430,7 @@ export function sectionInsertIndex(parsed, section) {
 export function insertIndexEntry(text, at, line) {
   const lines = text.split('\n');
   const target = Math.max(0, Math.min(Number(at), lines.length));
-  lines.splice(target, 0, line);
+  lines.splice(target, 0, line + fileEol(lines));
   return { text: lines.join('\n'), index: target };
 }
 

package/src/pathcheck.mjs

@@ -22,7 +22,12 @@ function candidate(raw) {
   if (token.includes('://') || token.startsWith('@')) return null;
   if (GLOB_OR_SHELL.test(token)) return null;
 
+  // A memory written on Windows quotes its paths with backslashes. The project
+  // index below is keyed on forward slashes, so a token that is not normalised
+  // matches nothing and every Windows-written path is reported as missing.
+  token = token.replace(/\\/g, '/');
   token = token.replace(LINE_SUFFIX, '').replace(/[.,;:]+$/, '').replace(/\/+$/, '');
+  if (/^[A-Za-z]:\//.test(token)) return null;
   if (token.startsWith('./')) token = token.slice(2);
   if (!token || token.startsWith('/') || token.startsWith('~')) return null;
   if (token.split('/').includes('..')) return null;

package/src/projects.mjs

@@ -14,12 +14,12 @@
 // and the repository root preferred as the store's identity.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { configPath, configSource, fixedProjectDirName } from './config.mjs';
 import { rememberedPath } from './pathcache.mjs';
 import { autoMemoryState, expandHome, resolveMemoryDirectory } from './settings.mjs';
 
-export const DEFAULT_ROOT = path.join(os.homedir(), '.claude', 'projects');
+export const DEFAULT_ROOT = configPath('projects');
 
 /**
  * Which store to read, and what decided it. The source travels with the path so
@@ -44,7 +44,24 @@ export function resolveRoot() {
       invalid: `autoMemoryDirectory "${configured.raw}" is ${configured.invalid}`,
     };
   }
-  return { path: DEFAULT_ROOT, source: 'default', file: null, invalid: null };
+  // CLAUDE_CONFIG_DIR moved the whole config directory, so DEFAULT_ROOT is
+  // already inside it. Naming that as the source keeps the UI from claiming a
+  // default location the user never used.
+  const config = configSource();
+  if (config.source === 'env') {
+    return { path: DEFAULT_ROOT, source: 'config-dir', file: null, invalid: config.invalid };
+  }
+  return { path: DEFAULT_ROOT, source: 'default', file: null, invalid: config.invalid };
+}
+
+/**
+ * The one project directory every repository shares when
+ * CLAUDE_CODE_PROJECT_DIR_NAME is set, or null when each repository gets a slug
+ * of its own. Callers use it to explain why one row stands for several
+ * repositories rather than to change how the row is read.
+ */
+export function fixedProjectDir() {
+  return fixedProjectDirName();
 }
 
 export function projectsRoot() {
@@ -180,12 +197,29 @@ export function storeIdentity(cwds) {
  * Candidates are verified against the filesystem so a wrong guess is reported
  * as unresolved rather than presented as fact.
  */
-function decodeSlug(slug) {
+export function slugCandidates(slug, platform = process.platform) {
+  // A Windows cwd slugifies with its drive in front ("C--Users-me-repo"), so the
+  // POSIX candidates below decode it to a path with no drive and no meaning.
+  if (platform === 'win32') {
+    const drive = /^([A-Za-z])--(.*)$/.exec(slug);
+    if (drive) {
+      const [, letter, rest] = drive;
+      return [
+        `${letter}:\\` + rest.replace(/--/g, '\\.').replace(/-/g, '\\'),
+        `${letter}:\\` + rest.replace(/-/g, '\\'),
+      ];
+    }
+  }
+
   const body = slug.replace(/^-/, '');
-  const candidates = [
+  return [
     '/' + body.replace(/--/g, '/.').replace(/-/g, '/'),
     '/' + body.replace(/-/g, '/'),
   ];
+}
+
+function decodeSlug(slug) {
+  const candidates = slugCandidates(slug);
   for (const candidate of candidates) {
     try {
       if (fs.existsSync(candidate)) return { path: candidate, verified: true };
@@ -223,7 +257,10 @@ export function resolveProjectPath(dir, slug) {
 
 /** A short label for the sidebar: the last two path segments. */
 export function shortLabel(fullPath) {
-  const parts = fullPath.split('/').filter(Boolean);
+  // Split on both separators: a store recorded on Windows is still browsed on
+  // whatever machine is reading it, and a backslash path would otherwise come
+  // out as one unsplittable segment.
+  const parts = String(fullPath).split(/[\\/]+/).filter(Boolean);
   return parts.slice(-2).join('/') || fullPath;
 }
 

package/src/settings.mjs

@@ -11,10 +11,15 @@
 //               ->  .claude/settings.json  ->  ~/.claude/settings.json
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
-export const USER_SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
+import { configPath, configSource, expandHome, fixedProjectDirName, isAbsolutePath } from './config.mjs';
+
+export const USER_SETTINGS = configPath('settings.json');
+
+// Re-exported because this is where every caller has always imported it from,
+// and because settings values are the main thing that arrives `~/`-prefixed.
+export { expandHome };
 
 /** Default when nothing sets cleanupPeriodDays; transcripts older than this are swept. */
 export const DEFAULT_CLEANUP_PERIOD_DAYS = 30;
@@ -24,6 +29,7 @@ export const SETTINGS_SEVERITY = {
   unreadable: 'bad',
   'not-object': 'bad',
   'invalid-auto-memory-directory': 'bad',
+  'invalid-config-dir': 'bad',
 };
 
 export function summariseSettings(problems) {
@@ -149,11 +155,6 @@ export function lookupPath(layers, keyPath) {
   return null;
 }
 
-export function expandHome(value) {
-  if (value.startsWith('~/')) return path.join(os.homedir(), value.slice(2));
-  return value;
-}
-
 /**
  * Where the auto memory store lives, per settings.
  *
@@ -171,12 +172,55 @@ export function resolveMemoryDirectory(options = {}) {
 
   const raw = typeof found.value === 'string' ? found.value.trim() : '';
   if (!raw) return null;
-  if (!raw.startsWith('/') && !raw.startsWith('~/') && !/^[A-Za-z]:[\\/]/.test(raw)) {
+  // Accepted on every platform, not only the one this is running on: a settings
+  // file is routinely shared between machines, and a Windows path read on macOS
+  // is a path this tool cannot open but must still report as intentional.
+  const rooted = raw.startsWith('~/') || raw.startsWith('~\\')
+    || isAbsolutePath(raw, 'win32') || isAbsolutePath(raw, 'linux');
+  if (!rooted) {
     return { ...found, raw, path: null, invalid: 'not an absolute or ~/ path' };
   }
   return { ...found, raw, path: expandHome(raw), invalid: null };
 }
 
+export const DISABLE_AUTO_MEMORY = 'CLAUDE_CODE_DISABLE_AUTO_MEMORY';
+
+/** The env-var convention Claude Code uses: set, and not "0" or "false". */
+function truthyEnv(value) {
+  if (value === null || value === undefined) return false;
+  const text = String(value).trim();
+  return Boolean(text) && text !== '0' && text !== 'false';
+}
+
+/**
+ * CLAUDE_CODE_DISABLE_AUTO_MEMORY, from either place it can be set.
+ *
+ * The process environment is the obvious one, but settings files carry an `env`
+ * block whose entries a session exports before it starts, so the same switch is
+ * equally settable in any of the five layers. Reading only process.env reported
+ * auto memory as on for anyone who had turned it off in a file - the reverse of
+ * what this tool is for.
+ */
+export function disableAutoMemoryEnv({ layers = null, projectDir = null, env = process.env } = {}) {
+  const raw = env[DISABLE_AUTO_MEMORY];
+  if (truthyEnv(raw)) {
+    return { disabling: true, value: raw, scope: 'env', file: null };
+  }
+
+  const found = lookupPath(layers || settingsLayers({ projectDir }), ['env', DISABLE_AUTO_MEMORY]);
+  if (found && truthyEnv(found.value)) {
+    return { disabling: true, value: found.value, scope: found.scope, file: found.file };
+  }
+
+  const value = raw ?? (found ? found.value : null);
+  return {
+    disabling: false,
+    value: value === undefined ? null : value,
+    scope: raw !== undefined && raw !== null ? 'env' : found?.scope ?? null,
+    file: raw !== undefined && raw !== null ? null : found?.file ?? null,
+  };
+}
+
 /**
  * Whether auto memory is on for a project, and what decided it.
  *
@@ -186,12 +230,14 @@ export function resolveMemoryDirectory(options = {}) {
  * local layer to read, so the answer is unknown rather than assumed.
  */
 export function autoMemoryState({ projectDir = null } = {}) {
-  const env = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
-  if (env && env !== '0' && env !== 'false') {
-    return { enabled: false, setBy: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY', scope: 'env', known: true };
+  const layers = settingsLayers({ projectDir });
+
+  const disabled = disableAutoMemoryEnv({ layers });
+  if (disabled.disabling) {
+    return { enabled: false, setBy: disabled.file || DISABLE_AUTO_MEMORY, scope: disabled.scope, known: true };
   }
 
-  const found = lookup(settingsLayers({ projectDir }), 'autoMemoryEnabled');
+  const found = lookup(layers, 'autoMemoryEnabled');
   if (found && typeof found.value === 'boolean') {
     return { enabled: found.value, setBy: found.file, scope: found.scope, known: true };
   }
@@ -263,8 +309,8 @@ export function settingsReport(options = {}) {
   const cleanup = keys.find((entry) => entry.key === 'cleanupPeriodDays');
   cleanup.normalized = cleanupPeriodDays(options);
 
-  const raw = process.env.CLAUDE_CODE_DISABLE_AUTO_MEMORY;
-  const disabling = Boolean(raw && raw !== '0' && raw !== 'false');
+  const disable = disableAutoMemoryEnv({ layers: reads.filter((read) => read.status === 'ok') });
+  const config = configSource();
 
   const problems = layers
     .filter((layer) => layer.status !== 'ok' && layer.status !== 'absent')
@@ -276,6 +322,16 @@ export function settingsReport(options = {}) {
       detail: layer.error,
     }));
 
+  if (config.invalid) {
+    problems.push({
+      kind: 'invalid-config-dir',
+      severity: SETTINGS_SEVERITY['invalid-config-dir'],
+      scope: 'env',
+      file: null,
+      detail: config.invalid,
+    });
+  }
+
   const directory = resolveMemoryDirectory(options);
   if (directory && directory.invalid) {
     problems.push({
@@ -292,9 +348,19 @@ export function settingsReport(options = {}) {
     layers,
     keys,
     env: {
-      name: 'CLAUDE_CODE_DISABLE_AUTO_MEMORY',
-      value: raw ?? null,
-      overrides: disabling ? 'autoMemoryEnabled' : null,
+      name: DISABLE_AUTO_MEMORY,
+      value: disable.value,
+      scope: disable.scope,
+      file: disable.file,
+      overrides: disable.disabling ? 'autoMemoryEnabled' : null,
+    },
+    configDir: {
+      name: 'CLAUDE_CONFIG_DIR',
+      path: config.path,
+      source: config.source,
+      value: config.raw,
+      invalid: config.invalid,
+      fixedProjectDirName: fixedProjectDirName(),
     },
     problems,
   };

package/src/stores.mjs

@@ -15,11 +15,13 @@
 // somewhere else first.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { listAllAgents, MEMORY_SCOPES } from './agents.mjs';
+import { canonicalPath, configDir, configPath, DEFAULT_CONFIG_DIR_NAME } from './config.mjs';
 import { listProjects, memoryDir, projectsRoot, shortLabel } from './projects.mjs';
+import { autoMemoryState } from './settings.mjs';
 
-export const AGENT_USER_DIR = path.join(os.homedir(), '.claude', 'agent-memory');
+export const AGENT_USER_DIR = configPath('agent-memory');
 export const AGENT_PROJECT_DIR = path.join('.claude', 'agent-memory');
 export const AGENT_LOCAL_DIR = path.join('.claude', 'agent-memory-local');
 
@@ -96,10 +98,15 @@ export function listAgentStores({ userDir = AGENT_USER_DIR, projectPaths = [] }
 
   // A repository can be reached through more than one project entry (a worktree
   // and its root), so the same directory must not be listed twice.
+  // Keyed on the canonical form: Windows and a default macOS volume are
+  // case-insensitive, so two spellings of one repository are one repository and
+  // would otherwise contribute the same agent store twice.
   const seen = new Set();
   for (const projectPath of projectPaths) {
-    if (!projectPath || !path.isAbsolute(projectPath) || seen.has(projectPath)) continue;
-    seen.add(projectPath);
+    if (!projectPath || !path.isAbsolute(projectPath)) continue;
+    const key = canonicalPath(projectPath);
+    if (seen.has(key)) continue;
+    seen.add(key);
     for (const [kind, relative] of [['agent-project', AGENT_PROJECT_DIR], ['agent-local', AGENT_LOCAL_DIR]]) {
       const parent = path.join(projectPath, relative);
       for (const name of agentDirs(parent)) {
@@ -113,6 +120,60 @@ export function listAgentStores({ userDir = AGENT_USER_DIR, projectPaths = [] }
     || a.sublabel.localeCompare(b.sublabel));
 }
 
+/**
+ * Join each subagent store to the definition that asks for it.
+ *
+ * A store directory on its own says nothing about whether a session still loads
+ * it: the `memory:` field in an agent file is what creates one, and that field
+ * can be changed to another scope or removed entirely without the directory it
+ * created ever going away. So the store is annotated with what the definitions
+ * actually say, and the cleanup checks in src/checks.mjs read those annotations
+ * rather than re-deriving them.
+ *
+ * The one rule that outranks all of it: subagent memory is part of auto memory,
+ * so when auto memory is off the `memory:` field has no effect at all - the
+ * agent launches with no memory instructions and no file tools, and every store
+ * on the machine is frozen where it stands.
+ */
+export function linkAgentStores(stores, agents, { autoMemory = null } = {}) {
+  const byName = new Map();
+  for (const agent of agents || []) {
+    const key = agent.name.toLowerCase();
+    if (!byName.has(key)) byName.set(key, []);
+    byName.get(key).push(agent);
+  }
+
+  return stores.map((store) => {
+    if (!store.kind.startsWith('agent-')) return store;
+
+    const candidates = (byName.get(store.agentName.toLowerCase()) || []).filter((agent) => {
+      // A project-scope definition only speaks for stores in its own repository.
+      if (agent.scope !== 'project' || !store.projectPath) return true;
+      return canonicalPath(agent.projectPath) === canonicalPath(store.projectPath);
+    });
+
+    const declaring = candidates.find((agent) => MEMORY_SCOPES[agent.memory] === store.kind) || null;
+    const other = declaring ? null : candidates.find((agent) => agent.memory) || null;
+    const inert = autoMemory ? autoMemory.enabled === false : false;
+
+    return {
+      ...store,
+      // Marks that the join actually ran. A store that was never linked knows
+      // nothing about its definitions, and "nothing is declared" and "nobody
+      // asked" have to stay distinguishable or the checks below report an
+      // orphan every time a caller builds a store on its own.
+      linkage: true,
+      declaredBy: declaring ? declaring.file : other ? other.file : null,
+      declaredScope: declaring ? declaring.memory : other ? other.memory : null,
+      declaringScope: declaring ? declaring.scope : other ? other.scope : null,
+      defined: candidates.length > 0,
+      linked: Boolean(declaring),
+      inert,
+      inertBy: inert ? autoMemory.setBy : null,
+    };
+  });
+}
+
 /** An auto-memory project, in the shape the rest of the app expects of a store. */
 function autoStore(project, root) {
   return {
@@ -133,8 +194,7 @@ function autoStore(project, root) {
  * `hasMemoryDir` false is what keeps it out of full-text search, which skips
  * stores without one, and out of everything else that reads memory files.
  */
-function globalStore(home) {
-  const dir = path.join(home, '.claude');
+function globalStore(dir) {
   return {
     id: storeId('global', dir),
     kind: 'global',
@@ -154,19 +214,26 @@ function globalStore(home) {
  * found under the project paths auto memory already resolved, so a repository this
  * tool has never seen a session for contributes nothing.
  *
- * `home` is a parameter because the global entry is about the real home directory
- * rather than the memory root, which --root can point somewhere else entirely.
+ * The config directory is a parameter because the global entry is about where
+ * Claude Code keeps its own files rather than about the memory root, which
+ * --root can point somewhere else entirely. `home` is the older spelling of the
+ * same idea and still accepted, since a home directory names exactly one config
+ * directory when CLAUDE_CONFIG_DIR is not set.
  */
-export function listStores(root = projectsRoot(), { home = os.homedir() } = {}) {
+export function listStores(root = projectsRoot(), { home = null, dir = null, agents = null } = {}) {
+  const global = dir || (home ? path.join(home, DEFAULT_CONFIG_DIR_NAME) : configDir());
   const projects = listProjects(root);
   const projectPaths = projects
     .filter((project) => project.pathExists)
     .flatMap((project) => [project.path, ...(project.workingDirs || [])]);
 
+  const agentStores = listAgentStores({ projectPaths });
+  const definitions = agents || listAllAgents({ projectPaths });
+
   return [
-    globalStore(home),
+    globalStore(global),
     ...projects.map((project) => autoStore(project, root)),
-    ...listAgentStores({ projectPaths }),
+    ...linkAgentStores(agentStores, definitions, { autoMemory: autoMemoryState() }),
   ];
 }
 

package/src/toolrun.mjs

@@ -9,20 +9,25 @@ export const num = (value) => (typeof value === 'number' && Number.isFinite(valu
 export const text = (value) => (typeof value === 'string' ? value : '');
 export const pct = (part, whole) => (whole > 0 ? (part / whole) * 100 : 0);
 
-function candidateNames(binary, env) {
-  if (process.platform !== 'win32') return [binary];
-  return text(env.PATHEXT || '.EXE').split(';').filter(Boolean).map((ext) => binary + ext.toLowerCase());
+function candidateNames(binary, env, platform) {
+  if (platform !== 'win32') return [binary];
+  return text(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean).map((ext) => binary + ext.toLowerCase());
 }
 
-export function findBinary(binary, env = process.env) {
+export function findBinary(binary, env = process.env, platform = process.platform) {
+  // PATH is split on this process's delimiter, not the target platform's, since
+  // the PATH being searched is the one this process actually has.
   const dirs = text(env.PATH).split(path.delimiter).filter(Boolean);
-  const names = candidateNames(binary, env);
+  const names = candidateNames(binary, env, platform);
   for (const dir of dirs) {
     for (const name of names) {
       const candidate = path.join(dir, name);
       try {
         if (!fs.statSync(candidate).isFile()) continue;
-        fs.accessSync(candidate, fs.constants.X_OK);
+        // Windows has no execute bit, and Node answers X_OK there from the
+        // file's existence alone. Asking for it is meaningless rather than
+        // harmless: it is the check that would reject a perfectly good .cmd.
+        if (platform !== 'win32') fs.accessSync(candidate, fs.constants.X_OK);
         return { found: true, path: candidate };
       } catch {
         continue;
@@ -32,10 +37,45 @@ export function findBinary(binary, env = process.env) {
   return { found: false, path: null };
 }
 
-export function runBinary(binary, args, { cwd, timeout = TIMEOUT_MS } = {}) {
+/**
+ * How to actually start a program on Windows.
+ *
+ * npm installs `rtk` and `ccusage` as `rtk.cmd`, and a batch file is not a
+ * program: execFile refuses to run one outright, and would not find it by bare
+ * name in the first place, since only the shell applies PATHEXT. So the resolved
+ * file is handed to cmd.exe the way Node's own shell support does - `/d /s /c`
+ * with one pre-quoted command string and verbatim arguments - and the arguments
+ * are quoted here rather than trusted to survive a second round of parsing.
+ */
+export function windowsInvocation(binary, args, env = process.env) {
+  const found = findBinary(binary, env, 'win32');
+  const target = found.found ? found.path : binary;
+  if (!/\.(cmd|bat)$/i.test(target)) return { file: target, args, options: {} };
+
+  const quote = (value) => `"${String(value).replace(/"/g, '""')}"`;
+  const command = [target, ...args].map(quote).join(' ');
+  return {
+    file: env.COMSPEC || 'cmd.exe',
+    args: ['/d', '/s', '/c', command],
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+export function runBinary(binary, args, { cwd, timeout = TIMEOUT_MS, env = process.env } = {}) {
   return new Promise((resolve, reject) => {
-    const options = { cwd, timeout, maxBuffer: MAX_BUFFER, windowsHide: true, encoding: 'utf8' };
-    execFile(binary, args, options, (err, stdout, stderr) => {
+    const invocation = process.platform === 'win32'
+      ? windowsInvocation(binary, args, env)
+      : { file: binary, args, options: {} };
+
+    const options = {
+      cwd,
+      timeout,
+      maxBuffer: MAX_BUFFER,
+      windowsHide: true,
+      encoding: 'utf8',
+      ...invocation.options,
+    };
+    execFile(invocation.file, invocation.args, options, (err, stdout, stderr) => {
       if (!err) return resolve(stdout);
       if (err.code === 'ENOENT') return reject(new Error(`${binary} is not on this process PATH`));
       if (err.killed) return reject(new Error(`${binary} ${args[0]} was still running after ${timeout}ms and was stopped`));