@bill10/agent-007 0.6.2

package/server/auth.js

@@ -0,0 +1,162 @@
+// Identity & auth (multiplayer phase 1)
+//
+// Users live in ~/.agent-007/users.json (separate from config.json so the
+// `adduser` CLI never races the server's session writes and needs no restart).
+// Each user: { id, displayName, color, tokenHash, createdAt }. Tokens are
+// bearer secrets — only the SHA-256 hash is stored, never the plaintext.
+//
+// Auth is OFF until the first user exists: with zero users the server behaves
+// exactly as it did before (open localhost single-player). Creating a user with
+// `npm run adduser` flips the server into authenticated mode. This keeps the
+// zero-config clone-and-run experience intact while enabling multiplayer.
+//
+// NOTE: like the origin check, this is a trust/identity layer, not a sandbox —
+// every authenticated user can still spawn shells on this machine. Only issue
+// tokens to people you'd give an SSH login. See docs/designs/multiplayer.md.
+
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { sessions } from './state.js';
+
+export const USERS_PATH = process.env.AGENT007_USERS_PATH
+  || join(homedir(), '.agent-007', 'users.json');
+
+// Distinct-per-user accent palette (separate from the per-agent color cycle).
+export const USER_COLORS = [
+  '#d4a847', '#58a6ff', '#7fbc6a', '#e0853a', '#bc8cff', '#76d9e6', '#ff7b72', '#e3b341',
+];
+
+// WebSocket close code for "authentication required/failed". Shared so the
+// server and client agree (client mirrors this in public/modules/auth.js).
+export const WS_UNAUTHORIZED = 4401;
+
+export function hashToken(token) {
+  return createHash('sha256').update(String(token)).digest('hex');
+}
+
+// users.json may be a bare array or a { users: [...] } wrapper. One normalizer
+// so auth.js and bin/adduser.js can't drift.
+export function normalizeUsers(raw) {
+  return Array.isArray(raw) ? raw : (Array.isArray(raw?.users) ? raw.users : []);
+}
+
+export function generateToken() {
+  return randomBytes(32).toString('base64url');
+}
+
+export function newUserId() {
+  return 'u_' + randomBytes(4).toString('hex');
+}
+
+// Sentinel served when users.json exists but can't be read/parsed and we have no
+// last-known-good copy: length > 0 keeps auth ENABLED, but its unmatchable id and
+// empty tokenHash reject every token. This makes a corrupt file fail CLOSED
+// (deny) rather than open (silently disabling auth for the whole server).
+const DENY_ALL = Object.freeze([Object.freeze({ id: '__deny__', displayName: '', color: '', tokenHash: '' })]);
+
+// Cache keyed on mtime AND size so same-second / coarse-FS-resolution rewrites
+// aren't missed (mtime alone can collide on HFS+/NFS). Refreshes without a
+// restart when `adduser` changes the file.
+let _cache = { key: null, users: [] };
+export function loadUsers() {
+  if (!existsSync(USERS_PATH)) { _cache = { key: null, users: [] }; return []; }
+  try {
+    const st = statSync(USERS_PATH);
+    const key = `${st.mtimeMs}:${st.size}`;
+    if (key === _cache.key) return _cache.users;
+    const users = normalizeUsers(JSON.parse(readFileSync(USERS_PATH, 'utf8')));
+    _cache = { key, users };
+    return users;
+  } catch (err) {
+    // File exists but couldn't be read/parsed. NEVER disable auth on error:
+    // serve the last known-good users if we have them, otherwise deny everything.
+    console.warn('users.json unreadable — failing closed (auth stays on):', err.message);
+    return _cache.users.length ? _cache.users : DENY_ALL;
+  }
+}
+
+export function authEnabled() {
+  return loadUsers().length > 0;
+}
+
+// The shape safe to send to clients (never includes tokenHash).
+export function publicUser(u) {
+  return u && { id: u.id, displayName: u.displayName, color: u.color };
+}
+
+// Look up a user by id (for labeling session owners). Returns publicUser or null.
+export function userById(id) {
+  if (!id) return null;
+  return publicUser(loadUsers().find(u => u.id === id)) || null;
+}
+
+// Resolve a bearer token to a user, or null. Constant-time compare against each
+// stored hash so a wrong token can't be distinguished by timing.
+export function resolveToken(token) {
+  if (!token) return null;
+  const presented = Buffer.from(hashToken(token), 'utf8');
+  for (const u of loadUsers()) {
+    // Skip malformed records; the length guard also satisfies timingSafeEqual's
+    // equal-length requirement (hex strings of equal length → equal-size buffers).
+    if (!u.tokenHash || u.tokenHash.length !== presented.length) continue;
+    if (timingSafeEqual(Buffer.from(u.tokenHash, 'utf8'), presented)) return u;
+  }
+  return null;
+}
+
+// Just the Authorization header. Split out because agent tokens are accepted
+// ONLY in this form: a ?token= URL lands in reverse-proxy and access logs, and
+// nothing legitimately puts an agent token in a URL.
+export function tokenFromAuthHeader(req) {
+  const auth = req.headers?.authorization;
+  if (auth && auth.startsWith('Bearer ')) return auth.slice(7).trim();
+  return null;
+}
+
+// Pull a bearer token from an Express request: Authorization header first,
+// then a ?token= query param (needed for the WebSocket handshake, where the
+// browser can't set headers).
+export function tokenFromRequest(req) {
+  const header = tokenFromAuthHeader(req);
+  if (header) return header;
+  try {
+    const url = new URL(req.url, 'http://localhost');
+    const q = url.searchParams.get('token');
+    if (q) return q;
+  } catch {}
+  return null;
+}
+
+// --- Agent session tokens (job board: the MCP tool) ---
+//
+// Every agent terminal is spawned with a one-off bearer token so the board's
+// MCP server can tell which agent is calling. The token is minted per session,
+// lives in memory on the session object plus one mode-0600 config file that is
+// deleted when the PTY exits, and stops resolving the moment that session ends.
+// Nothing is written to the agent's environment: an env var is inherited by
+// every child process the agent runs, which is a much wider blast radius than
+// a file only the MCP client reads at startup.
+//
+// It is deliberately NOT a user credential. It identifies one live agent and
+// reaches exactly one surface (POST /mcp and POST /api/jobs); every other /api
+// route is user-only by construction (see requireUser in server/http.js).
+export function mintAgentToken() {
+  return 'a007a_' + randomBytes(32).toString('base64url');
+}
+
+// Resolve a token to the live session that owns it. Sessions are few, so a scan
+// beats a second index that has to be invalidated on every exit — and an exited
+// session's token stops resolving with no cleanup step at all.
+export function resolveAgentToken(token) {
+  if (!token) return null;
+  const presented = Buffer.from(String(token), 'utf8');
+  for (const session of sessions.values()) {
+    if (session.exited || !session.agentToken) continue;
+    const stored = Buffer.from(session.agentToken, 'utf8');
+    if (stored.length !== presented.length) continue;
+    if (timingSafeEqual(stored, presented)) return session;
+  }
+  return null;
+}

package/server/billion.js

@@ -0,0 +1,176 @@
+// Billion — the one agent you talk to (docs/BILLION.md).
+//
+// A repo-less agent whose working directory is its own git repo, holding its
+// charter and memory. The server starts it on boot (unless it is off, see
+// billionRuns), resuming the last conversation when there is one. Everything here is pure or touches only
+// Billion's own folder; spawning it is server.js's job, like every session.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync } from 'fs';
+import { join, dirname, resolve, relative, isAbsolute } from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+import { CONFIG_DIR, sessions } from './state.js';
+import { authEnabled } from './auth.js';
+
+import { quote } from '../lib/jobs.js';
+import { envSwitchOn } from '../lib/helpers.js';
+export { BILLION_NAME } from '../lib/jobs.js';
+
+const TEMPLATE_DIR = fileURLToPath(new URL('../templates/billion/', import.meta.url));
+// Two owners, two kinds of file. The charter is Agent 007's: rewritten on every
+// start, so a new version reaches a Billion that already exists. The rest is
+// the owner's and Billion's, copied once and never touched again. CLAUDE.md
+// (from owner.md) imports the charter and holds the owner's rules. Neither
+// template is named CLAUDE.md here, or an agent working on Agent 007 itself
+// would load Billion's instructions as its own.
+const CHARTER = { from: 'charter.md', to: 'CHARTER.md' };
+const FIRST_RUN_ONLY = { 'owner.md': 'CLAUDE.md', 'STATE.md': 'STATE.md', 'COMPANY.md': 'COMPANY.md' };
+const OS_FILES = ['.DS_Store', 'Thumbs.db', 'desktop.ini'];
+// Written at setup: what makes a folder Billion's. A file name alone is not
+// enough (macOS matches CHARTER.md to a project's charter.md).
+const MARKER = { name: '.billion', text: 'This folder is Billion\'s, set up by Agent 007.\n' };
+// Synchronous, on the server's own thread, so bounded: a global
+// commit.gpgsign waiting on a pinentry, or a hook, must not freeze every
+// terminal. These commits are Agent 007's own bookkeeping in Billion's folder,
+// so the user's signing and hooks are left out of them.
+const GIT_TIMEOUT_MS = 15_000;
+const git = (dir, args) => execFileSync('git', args, { cwd: dir, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+const COMMIT = ['-c', 'commit.gpgsign=false', 'commit', '-q', '--no-verify'];
+
+// The running Billion, if there is one.
+export function liveBillion() {
+  return [...sessions.values()].find(s => s.isBillion && !s.exited) || null;
+}
+
+// On unless turned off: BILLION=0 (or false/off/no) in the environment or .env.
+export function billionEnabled(env = process.env) {
+  return envSwitchOn(env.BILLION);
+}
+
+// Whether this server runs Billion. Not with user accounts: Billion belongs
+// to no one, so every signed-in user could drive an agent that never asks
+// before acting. That waits for a Billion per user.
+export function billionRuns(env = process.env) {
+  return billionEnabled(env) && !authEnabled();
+}
+
+export function billionDir(env = process.env) {
+  return env.BILLION_DIR ? resolve(env.BILLION_DIR) : join(CONFIG_DIR, 'billion');
+}
+
+// First run: a git repo with the templates, committed. An existing repo is left
+// exactly as it is — it is Billion's memory. A folder that exists but is not a
+// repo yet (someone made BILLION_DIR by hand) gets the templates it lacks.
+//
+// A repo without Billion's charter is someone else's (BILLION_DIR pointed at a
+// project, say): refused, rather than committing a charter into it and
+// starting an agent there that never asks before acting.
+export function ensureBillionRepo(dir) {
+  if (existsSync(join(dir, '.git'))) {
+    let marker = null;
+    try { marker = readFileSync(join(dir, MARKER.name), 'utf8'); } catch {}
+    // Line endings aside: restored with git on Windows it may come back CRLF.
+    if (marker?.replace(/\r\n/g, '\n') !== MARKER.text) {
+      throw new Error(`${dir} is a git repository without Billion's ${MARKER.name} marker. If it is Billion's folder, restore the file from its git history (git checkout -- ${MARKER.name}); otherwise point BILLION_DIR somewhere else`);
+    }
+    return { created: false };
+  }
+  // Nor a folder with anything in it (BILLION_DIR at a home or projects
+  // folder): setting up there would put all of it in Billion's repo, and run
+  // Billion in it. Only the template files may be there already.
+  // The files an OS leaves in any folder it has shown don't count either;
+  // they are ignored, so neither this commit nor any of Billion's takes them.
+  const ours = new Set([CHARTER.to, ...Object.values(FIRST_RUN_ONLY), '.gitignore', MARKER.name, ...OS_FILES]);
+  const theirs = existsSync(dir) ? readdirSync(dir).filter(name => !ours.has(name)) : [];
+  if (theirs.length) {
+    throw new Error(`${dir} already holds other files (${theirs.slice(0, 3).join(', ')}${theirs.length > 3 ? ', …' : ''}), so it can't be Billion's folder; point BILLION_DIR at a new or empty folder`);
+  }
+  mkdirSync(dir, { recursive: true });
+  for (const [from, to] of [[CHARTER.from, CHARTER.to], ...Object.entries(FIRST_RUN_ONLY)]) {
+    const target = join(dir, to);
+    if (!existsSync(target)) copyFileSync(join(TEMPLATE_DIR, from), target);
+  }
+  writeFileSync(join(dir, MARKER.name), MARKER.text);
+  const ignore = join(dir, '.gitignore');
+  if (!existsSync(ignore)) writeFileSync(ignore, `${OS_FILES.join('\n')}\n`);
+  git(dir, ['-c', 'init.defaultBranch=main', 'init', '-q']);
+  git(dir, ['add', '-A']);
+  // An identity of its own, so a machine with no git user.name still commits.
+  git(dir, ['-c', 'user.name=Billion', '-c', 'user.email=billion@agent-007.local', ...COMMIT, '-m', 'Billion: first run']);
+  return { created: true };
+}
+
+// Bring CHARTER.md up to this version of Agent 007, before Billion starts.
+// Committed on its own — the pathspec leaves anything else Billion had not
+// committed exactly as it was — so the upgrade shows in Billion's history as
+// what it is. Returns whether it changed.
+export function refreshCharter(dir) {
+  const target = join(dir, CHARTER.to);
+  const text = readFileSync(join(TEMPLATE_DIR, CHARTER.from), 'utf8');
+  if (existsSync(target) && readFileSync(target, 'utf8') === text) return false;
+  writeFileSync(target, text);
+  git(dir, ['add', '--', CHARTER.to]);
+  git(dir, ['-c', 'user.name=Agent 007', '-c', 'user.email=agent-007@agent-007.local',
+    ...COMMIT, '-m', 'Agent 007: update the charter', '--', CHARTER.to]);
+  return true;
+}
+
+// The folder holding most of the owner's repos, offered as the place for new
+// ones. The most common parent rather than a common prefix: one repo living
+// elsewhere must not widen the suggestion to the home directory. Repos inside
+// Agent 007's own folder (a worktree added as a repo) are not the owner's
+// projects folder and don't count.
+export function suggestProjectsDir(repoPaths, { ignoreUnder = CONFIG_DIR } = {}) {
+  const inside = (p) => { const r = relative(resolve(ignoreUnder), p); return r && !r.startsWith('..') && !isAbsolute(r); };
+  const counts = new Map();
+  for (const p of repoPaths) {
+    if (inside(resolve(p))) continue;
+    const parent = dirname(resolve(p));
+    counts.set(parent, (counts.get(parent) || 0) + 1);
+  }
+  let best = null;
+  for (const [dir, n] of counts) if (!best || n > counts.get(best)) best = dir;
+  return best;
+}
+
+
+// Everything Billion must do lives in its charter; the prompt only says which
+// part applies. A fresh repo gets the introduction. Any later start says both,
+// because a restart can land mid-introduction: the charter tells it to finish
+// the introduction while STATE.md still says "not started". --continue only
+// when a conversation exists, so a lost transcript still starts cleanly.
+export function billionCommand({ created, hasConversation, dir, projectsHint }) {
+  const where = `Your folder is ${dir}.`;
+  const hint = projectsHint
+    ? `Suggest ${projectsHint} as the projects folder: most of the owner's repos are there.`
+    : 'The owner has no repos yet, so ask for a projects folder without suggesting one.';
+  const prompt = created
+    ? `This is your first run. Introduce yourself as described in CHARTER.md under "First run". ${where} ${hint}`
+    : `You were restarted. If STATE.md still says "Status: not started", do or finish your introduction (CHARTER.md, "First run"). ${hint} Otherwise start your operating loop (CHARTER.md, "Operating loop"). ${where}`;
+  return `claude --dangerously-skip-permissions${!created && hasConversation ? ' --continue' : ''} ${quote(prompt)}`;
+}
+
+// Claude Code asks whether to trust a folder the first time it runs there, and
+// highlights "No, exit". Billion's folder is Agent 007's own, holding only
+// what the server put there, so the server answers for it. Board workers get
+// the same answer for a different reason: queueing a job on a repo already
+// trusts it (server/claude-trust.js has the trade-off and the opt-out). It acts on what the
+// screen shows rather than a fixed key sequence, so a version that highlights
+// "Yes" first still gets the right answer: Ctrl-N off "No", Enter on "Yes",
+// nothing on anything else. The text is everything drawn since the dialog
+// settled, which can hold an older drawing too, so the LAST cursor is the one
+// on screen now. Claude Code draws with cursor moves, so the stripped text may
+// have lost its spaces.
+export function trustDialogKey(screenText) {
+  // Both options, not just the phrase: a board worker's screen also shows its
+  // job text, which anyone who can post a card chooses.
+  if (!/Yes,\s*I\s*trust\s*this\s*folder/i.test(screenText) || !/No,\s*exit/.test(screenText)) return null;
+  const at = screenText.lastIndexOf('❯');
+  if (at === -1) return null;
+  const selected = screenText.slice(at + 1);
+  if (/^\s*Yes,\s*I\s*trust\s*this\s*folder/i.test(selected)) return '\r';
+  // Ctrl-N, not the down arrow: an arrow starts with ESC, and a lone ESC here
+  // is "Esc to cancel", which exits claude. Verified on 2.1.282.
+  if (/^\s*No,\s*exit/.test(selected)) return '\x0e';
+  return null;
+}

package/server/claude-trust.js

@@ -0,0 +1,66 @@
+// Claude Code stops at a workspace-trust dialog the first time it runs in a
+// folder, and every board worker gets a brand-new worktree, so every dispatch
+// used to wait for a click. Trust is recorded per absolute path in
+// ~/.claude.json (projects[<path>].hasTrustDialogAccepted); writing that entry
+// before the spawn skips the dialog. Verified against claude 2.1.282.
+//
+// Claude Code rewrites this file itself, constantly, so the write is kept as
+// small as it can be: read, add one entry, write a temp file beside it, rename.
+// A running claude that read the file before the rename and writes after it can
+// still drop the entry, and a write of Claude Code's that lands while we
+// build ours makes us give up rather than overwrite it, so the PTY answer
+// (server/pty.js, answerTrustDialog) stays on as a fallback. A missing or
+// unreadable file is left alone: it is Claude Code's, and a guess at its shape
+// would be worse than one dialog.
+import { readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { sessionAgentFromCommand } from '../lib/jobs.js';
+import { envSwitchOn } from '../lib/helpers.js';
+
+// Board-dispatched Claude Code workers only, and on unless
+// TRUST_BOARD_WORKTREES says otherwise (0/false/off/no). Hand-started agents
+// keep the dialog.
+export function autoTrusts({ spawnedBy, worktreePath, command }, env = process.env) {
+  return spawnedBy === 'board' && !!worktreePath && sessionAgentFromCommand(command) === 'claude'
+    && envSwitchOn(env.TRUST_BOARD_WORKTREES);
+}
+
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+// True when the entry is there afterwards. Never throws. Workers inherit the
+// server's environment, so CLAUDE_CONFIG_DIR moves their file and ours alike.
+export function trustClaudeFolder(folder, { home = homedir(), env = process.env } = {}) {
+  let file = join(env.CLAUDE_CONFIG_DIR || home, '.claude.json');
+  let tmp = null;
+  try {
+    file = realpathSync(file);   // a dotfiles symlink stays a symlink
+    tmp = `${file}.agent007-${process.pid}.tmp`;
+    const before = statSync(file);
+    // claude records the path as its cwd reports it, which is the real one
+    // (/tmp is /private/tmp on macOS).
+    const path = realpathSync(folder);
+    const data = JSON.parse(readFileSync(file, 'utf8'));
+    // Any part not shaped as expected means the file is not what we think it
+    // is: leave it to Claude Code rather than overwrite what we don't know.
+    const projects = data?.projects ?? {};
+    if (!isRecord(data) || !isRecord(projects) || !isRecord(projects[path] ?? {})) return false;
+    if (projects[path]?.hasTrustDialogAccepted === true) return true;
+    data.projects = { ...projects, [path]: { ...projects[path], hasTrustDialogAccepted: true } };
+    rmSync(tmp, { force: true });   // a leftover from a crash; 'wx' never follows one
+    writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: before.mode & 0o777, flag: 'wx' });
+    // Claude Code wrote the file while we built ours: renaming now would drop
+    // its change. Leave it to the PTY fallback instead.
+    const now = statSync(file);
+    if (now.mtimeMs !== before.mtimeMs || now.size !== before.size || now.ino !== before.ino) {
+      rmSync(tmp, { force: true });
+      return false;
+    }
+    renameSync(tmp, file);
+    return true;
+  } catch (err) {
+    if (tmp) rmSync(tmp, { force: true });
+    console.error(`Could not pre-trust ${folder} in ${file}: ${err.message}`);
+    return false;
+  }
+}

package/server/command-path.js

@@ -0,0 +1,102 @@
+// Windows executable resolution for PTY spawns.
+//
+// node-pty checks that the command exists before returning, but it launches
+// through CreateProcessW with the *unresolved* name. CreateProcessW only ever
+// appends `.exe` — it does not consult PATHEXT — so an npm-installed command
+// like `claude` (which ships as `claude.cmd` plus an extensionless bash shim)
+// passes node-pty's existence check and then fails inside the console host
+// with "Cannot create process, error code: 2" (ERROR_FILE_NOT_FOUND).
+//
+// Worse, that failure is raised on the conout worker thread *after* spawn()
+// has already returned, so it lands as an uncaught exception rather than
+// something the caller can try/catch. Resolving the command to a full path
+// with a launchable extension up front is what keeps it from happening.
+
+import { statSync } from 'fs';
+import { join, resolve } from 'path';
+
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+
+// A Windows PATH is always ';'-separated and its separators are always `\` or
+// `/`, whatever platform this process happens to be running on. Taking those
+// from `path.delimiter` / `path.sep` instead would make the `platform`
+// argument a lie on a POSIX host — and the CI runner is Linux.
+const WIN_PATH_DELIMITER = ';';
+const HAS_SEPARATOR_RE = /[\\/]/;
+const DRIVE_PREFIX_RE = /^[a-zA-Z]:/;
+// Whatever follows the last dot of the final path segment.
+const OWN_EXT_RE = /\.[^.\\/]*$/;
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * Resolve `file` to a path CreateProcessW can actually launch.
+ *
+ * Returns the resolved absolute path, or null when nothing matched — callers
+ * fall back to the original name so node-pty keeps whatever resolution it can
+ * do on its own. Non-Windows platforms are returned unchanged: execvp handles
+ * PATH lookup there and has no PATHEXT quirk.
+ *
+ * @param {string} file      command as typed, e.g. 'claude'
+ * @param {object} [env]     environment to read PATH/PATHEXT from
+ * @param {string} [platform]
+ * @param {string} [cwd]     base for relative paths
+ */
+export function resolveExecutable(file, env = process.env, platform = process.platform, cwd = process.cwd()) {
+  if (platform !== 'win32' || !file) return null;
+
+  // PATHEXT is conventionally uppercase but the files on disk are not, and the
+  // resolved path ends up in log lines and error messages, so match the
+  // lowercase convention. Windows itself does not care either way.
+  const exts = (env.PATHEXT || DEFAULT_PATHEXT)
+    .split(';')
+    .map(e => e.trim().toLowerCase())
+    .filter(Boolean);
+
+  // A command that already carries a launchable extension is used verbatim;
+  // anything else gets each PATHEXT entry appended, the same order cmd.exe
+  // would try them in.
+  const ownExt = (file.match(OWN_EXT_RE) || [''])[0];
+  const candidates = ownExt && exts.includes(ownExt.toLowerCase())
+    ? [file]
+    : exts.map(e => file + e);
+
+  // A command carrying a separator or a drive letter is a path, not a PATH
+  // lookup. Relative ones resolve against the working directory.
+  if (HAS_SEPARATOR_RE.test(file) || DRIVE_PREFIX_RE.test(file)) {
+    for (const candidate of candidates) {
+      const full = resolve(cwd, candidate);
+      if (isFile(full)) return full;
+    }
+    return null;
+  }
+
+  // PATH only — deliberately NOT the working directory, even though cmd.exe
+  // searches there first. The working directory is the agent's worktree, so
+  // searching it would let a `claude.cmd` committed to a repository replace the
+  // command the agent runs. child_process and PowerShell skip it too.
+  const dirs = (env.PATH || env.Path || '').split(WIN_PATH_DELIMITER).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of candidates) {
+      const full = join(dir.replace(/^"|"$/g, ''), candidate);
+      if (isFile(full)) return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * True when `dir` is usable as a PTY working directory.
+ *
+ * CreateProcessW rejects a missing lpCurrentDirectory with error code 267
+ * (ERROR_DIRECTORY) — and, like the command lookup above, it does so
+ * asynchronously. A re-spawn whose worktree has since been deleted is the
+ * common way to get there, so the caller checks first and reports a real
+ * error instead of taking the server down.
+ */
+export function isUsableCwd(dir) {
+  if (!dir) return false;
+  try { return statSync(dir).isDirectory(); } catch { return false; }
+}