chord-cli 0.2.0 → 0.2.1

package/dist/hooks.js

@@ -6,7 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as db from "./db.js";
 import { patchFiles } from "./patch.js";
-import { canWrite, insideDir, normFile } from "./tools.js";
+import { canWrite, dirtyTracked, insideDir, normFile } from "./tools.js";
 const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 export function filesTouched(tool, payload) {
     const name = String(payload.tool_name ?? '');
@@ -26,10 +26,10 @@ export function filesTouched(tool, payload) {
     return [];
 }
 /** Tools that write files and must therefore name them: a call that names none is refused rather than let through. */
-export const isEditTool = (tool, name) => (tool === 'claude' ? EDIT_TOOLS.has(String(name)) : name === 'apply_patch');
+const isEditTool = (tool, name) => (tool === 'claude' ? EDIT_TOOLS.has(String(name)) : name === 'apply_patch');
 const isShell = (name) => /^(bash|powershell|shell|exec|exec_command|local_shell)$/i.test(String(name ?? ''));
 const hhmm = (t) => new Date(t).toTimeString().slice(0, 5); // local time
-export function formatMessages(ms) {
+function formatMessages(ms) {
     return ms.map(m => `[chord] message from ${m.sender} at ${hhmm(m.created_at)}:\n${m.body}`).join('\n\n');
 }
 const MAX_CLAIM_LINES = 60;
@@ -45,6 +45,17 @@ function ownCopy(ctx, abs, tool) {
     const tail = parts[0] === repoName ? parts.slice(1) : parts[0] === 'chord' && parts[1] === 'agents' && parts[3] === repoName ? parts.slice(4) : [];
     return tool === 'claude' ? path.join(ctx.worktree, ...tail) : `${repoDirOf(ctx)}/${tail.join('/')}`; // Claude's editor wants absolute paths
 }
+/** The path with links resolved, so a write through a junction or symlink is judged by where it lands. The file may
+ *  not exist yet: the nearest existing ancestor is resolved and the rest appended. */
+function realPath(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        const parent = path.dirname(p);
+        return parent === p ? p : path.join(realPath(parent), path.basename(p));
+    }
+}
 /** The repository's own agent instructions. The agent's cwd is the project folder, which is not a git repository, so
  *  Codex does not load the worktree's AGENTS.md and Claude only reads a nested CLAUDE.md once it opens a file there. */
 function projectInstructions(ctx, repoDir) {
@@ -126,7 +137,7 @@ export function handleHook(ctx, tool, event, payload) {
             const base = ctx.project ?? ctx.cwd;
             const workdir = tool === 'codex' && typeof payload.tool_input?.workdir === 'string' ? path.resolve(base, payload.tool_input.workdir) : base;
             for (const f of files) {
-                const abs = path.resolve(workdir, f);
+                const abs = realPath(path.resolve(workdir, f));
                 if (!insideDir(ctx.worktree, abs)) {
                     // the main checkout and the other agents' workspaces are off limits; anything else is not ours to police
                     if (ctx.project && insideDir(ctx.project, abs) && !insideDir(ctx.cwd, abs)) {
@@ -149,18 +160,21 @@ export function handleHook(ctx, tool, event, payload) {
             db.setStatus(ctx.db, ctx.agent, 'busy');
             const parts = [];
             if (isShell(payload.tool_name))
-                parts.push(...shellWarnings(ctx, payload));
-            const ms = db.takeUnread(ctx.db, ctx.agent);
+                parts.push(...shellWarnings(ctx, payload), ...commandWarnings(ctx, payload));
+            // a Claude Code subagent's tool calls fire this hook too (with its agent_id); context given to it never reaches
+            // the main conversation, so the messages wait for a call of the agent's own
+            const ms = payload.agent_id ? [] : db.takeUnread(ctx.db, ctx.agent);
             if (ms.length)
                 parts.push(`${formatMessages(ms)}\n\n[chord] ${ms.length} message(s) above arrived from other agents while you were working. Deal with them when convenient (reply with the chord send tool where a reply is asked for), then carry on with your task.`);
             return parts.length ? { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: parts.join('\n\n') } } : undefined;
         }
         case 'stop': {
-            const ms = db.takeUnread(ctx.db, ctx.agent);
-            if (ms.length)
-                return { decision: 'block', reason: formatMessages(ms) + '\n\nHandle these messages before stopping.' };
-            db.setStatus(ctx.db, ctx.agent, 'idle');
-            return undefined;
+            // only a message is worth another turn; a notice (a merge broadcast) waits for the next hook, as it does for the wake-up
+            if (!db.hasUnread(ctx.db, ctx.agent)) {
+                db.setStatus(ctx.db, ctx.agent, 'idle');
+                return undefined;
+            }
+            return { decision: 'block', reason: formatMessages(db.takeUnread(ctx.db, ctx.agent)) + '\n\nHandle these messages before stopping.' };
         }
         case 'notification':
             // Claude Code: "idle_prompt" fires about a minute after Claude stopped and nobody typed. It is the only
@@ -176,30 +190,9 @@ export function handleHook(ctx, tool, event, payload) {
             return undefined;
     }
 }
-/** Paths changed according to `git status --porcelain=v1 -z -uall`: entries are NUL-separated, a rename
- *  or copy is followed by the original path, and nothing is quoted or folded into directories. */
-export function changedPaths(statusZ) {
-    const parts = statusZ.split('\0');
-    const out = [];
-    for (let i = 0; i < parts.length; i++) {
-        const entry = parts[i];
-        if (!entry)
-            continue;
-        out.push(entry.slice(3));
-        const xy = entry.slice(0, 2);
-        if (/R/.test(xy)) {
-            i++;
-            if (parts[i])
-                out.push(parts[i]);
-        } // a rename changes its "from" path too
-        else if (/C/.test(xy))
-            i++; // a copy leaves its source alone
-    }
-    return out;
-}
 /** The old names of renames in NUL-separated status output: a rename changes that path too, and diff --name-only
  *  lists only the new one. */
-export function renameSources(statusZ) {
+function renameSources(statusZ) {
     const parts = statusZ.split('\0');
     const out = [];
     for (let i = 0; i < parts.length; i++) {
@@ -225,30 +218,47 @@ const gitOut = (cwd, ...args) => {
         return '';
     }
 };
-/** What a shell command may have done behind chord's back: edits or commits to unclaimed files, git stash, and
- *  changes to the main checkout. */
-export function shellWarnings(ctx, payload) {
+/** What a shell command may have done behind chord's back, according to git: edits or commits to unclaimed files,
+ *  and changes to the main checkout. */
+function shellWarnings(ctx, payload) {
     const out = [];
     const mine = new Set(db.claimsBy(ctx.db, ctx.agent).map(c => c.file.toLowerCase()));
-    // uncommitted changes (-unormal folds an untracked directory into one entry) plus whatever the branch has
-    // committed since it left main: a commit made from the shell is no more a claim than an edit is
-    // tracked files: real changes only, so a repository whose files differ in line endings from the moment they are
-    // checked out does not make every shell command cry wolf; untracked files from status, directories folded
+    // Everything the worktree differs in from where its branch left main, committed or not: a commit made from the
+    // shell is no more a claim than an edit is. Tracked files by one diff against the merge base with the main
+    // checkout's HEAD (real changes only, so a repository whose files differ in line endings from the moment they are
+    // checked out does not make every shell command cry wolf); untracked files from status, directories folded.
     const status = gitOut(ctx.worktree, 'status', '--porcelain=v1', '-z', '-unormal');
     const untracked = status.split('\0').filter(e => e.startsWith('?? ')).map(e => e.slice(3));
-    const modified = ['', '--cached'].flatMap(c => gitOut(ctx.worktree, 'diff', ...(c ? [c] : []), '--name-only', '-z', '--ignore-cr-at-eol').split('\0'));
-    const root = db.mainRoot(ctx.worktree);
-    const main = root ? gitOut(root, 'rev-parse', '--abbrev-ref', 'HEAD').trim() : '';
-    const base = main && main !== 'HEAD' ? gitOut(ctx.worktree, 'merge-base', 'HEAD', main).trim() : '';
-    const committed = base ? gitOut(ctx.worktree, 'diff', '--name-only', '-z', base, 'HEAD').split('\0').filter(Boolean) : [];
-    const touched = [...new Set([...modified.filter(Boolean), ...untracked, ...renameSources(status), ...committed])];
-    const unclaimed = touched.map(f => normFile(ctx, path.join(ctx.worktree, f))).filter(f => !mine.has(f.toLowerCase()));
+    const modified = gitOut(ctx.worktree, 'diff', '--name-only', '-z', '--ignore-cr-at-eol', '--merge-base', 'main-worktree/HEAD').split('\0');
+    // the main checkout is <project>/<repoName>; asking git costs a subprocess on every shell command
+    const root = ctx.project ? path.join(ctx.project, path.basename(ctx.worktree)) : db.mainRoot(ctx.worktree);
+    const touched = [...new Set([...modified.filter(Boolean), ...untracked, ...renameSources(status)])];
+    // a folded untracked directory counts as claimed when a claim names a file inside it
+    const claimed = (f) => mine.has(f) || [...mine].some(m => m.startsWith(f + '/'));
+    const unclaimed = touched.map(f => normFile(ctx, path.join(ctx.worktree, f))).filter(f => !claimed(f.toLowerCase()));
     const shown = unclaimed.slice(0, MAX_WARNED_FILES);
     if (unclaimed.length)
         out.push(`[chord] The shell command changed files you have not claimed: ${shown.join(', ')}${unclaimed.length > shown.length ? ` and ${unclaimed.length - shown.length} more` : ''}. Claim them now with claim(), or revert the change.`);
+    if (path.resolve(root) !== path.resolve(ctx.worktree)) {
+        // the same rule finish applies, so what finish will not mind (line endings, submodule insides) is not reported
+        const dirty = (() => { try {
+            return dirtyTracked(root).split('\n').filter(Boolean);
+        }
+        catch {
+            return [];
+        } })();
+        if (dirty.length)
+            out.push(`[chord] The main checkout (${root}) has uncommitted changes, which blocks everyone's finish(): ${dirty.slice(0, 10).join(', ')}. If your command did this, undo it there; the main branch is only ever changed through finish().`);
+    }
+    return out;
+}
+/** What the command's text alone gives away: it ran in or named the main checkout, or used git stash. Heuristics,
+ *  so warnings, not gates; no git involved, unlike shellWarnings. */
+export function commandWarnings(ctx, payload) {
+    const out = [];
     const cmd = typeof payload.tool_input?.command === 'string' ? payload.tool_input.command : '';
     // From the project folder, "<repo>/" is the main checkout: a command that ran there (Codex's workdir), cd'd there or
-    // named a path there did not touch the agent's own copy. A heuristic on the command text, so a warning, not a gate.
+    // named a path there did not touch the agent's own copy.
     if (ctx.project) {
         const repoName = path.basename(ctx.worktree);
         const workdir = typeof payload.tool_input?.workdir === 'string' ? path.resolve(ctx.project, payload.tool_input.workdir) : null;
@@ -266,11 +276,6 @@ export function shellWarnings(ctx, payload) {
     }
     if (/\bgit\b[^|;&\n]*\bstash\b/.test(cmd))
         out.push("[chord] git stash is shared by every worktree of this repository: a stash pop can hand you another agent's changes, and yours to them. Make a work-in-progress commit instead.");
-    if (root && path.resolve(root) !== path.resolve(ctx.worktree)) {
-        const dirty = gitOut(root, 'status', '--porcelain', '--untracked-files=no').split('\n').filter(Boolean).map(l => l.slice(3));
-        if (dirty.length)
-            out.push(`[chord] The main checkout (${root}) has uncommitted changes, which blocks everyone's finish(): ${dirty.slice(0, 10).join(', ')}. If your command did this, undo it there; the main branch is only ever changed through finish().`);
-    }
     return out;
 }
 /** handleHook, but never lets an exception reach the tool: a broken hook must not fail open on a write. */
@@ -293,8 +298,11 @@ async function main() {
     const agent = process.env.CHORD_AGENT_ID;
     const file = process.env.CHORD_DB;
     const tool = process.env.CHORD_TOOL;
-    if (!agent || !file || !tool) {
-        process.stderr.write('chord hook: CHORD_AGENT_ID, CHORD_DB and CHORD_TOOL must be set\n');
+    // the workspace is fixed per agent and comes from the launch; the tool's own cwd is the project folder, which would
+    // make every claim path wrong, so it is never used as a stand-in
+    const { CHORD_WORKSPACE: cwd, CHORD_WORKTREE: worktree } = process.env;
+    if (!agent || !file || !tool || !cwd || !worktree) {
+        process.stderr.write('chord hook: CHORD_AGENT_ID, CHORD_DB, CHORD_TOOL, CHORD_WORKSPACE and CHORD_WORKTREE must be set\n');
         process.exit(0);
     }
     const chunks = [];
@@ -306,11 +314,9 @@ async function main() {
         payload = JSON.parse(raw);
     }
     catch { /* no payload */ }
-    // the workspace is fixed per agent; the tool's own cwd moves when the agent runs `cd`, so it is not used as the base
-    const cwd = process.env.CHORD_WORKSPACE ?? (typeof payload.cwd === 'string' ? payload.cwd : process.cwd());
     let ctx;
     try {
-        ctx = { db: db.openDb(file), agent, cwd, worktree: process.env.CHORD_WORKTREE ?? cwd, project: process.env.CHORD_PROJECT };
+        ctx = { db: db.openDb(file), agent, cwd, worktree, project: process.env.CHORD_PROJECT };
     }
     catch (e) {
         // the database would not open: a write must still not go through unchecked
@@ -324,9 +330,9 @@ async function main() {
     if (process.env.CHORD_DEBUG_HOOKS)
         db.log(`hook payload ${event}: keys=${Object.keys(payload).join(',')} agent_id=${payload.agent_id ?? '-'} agent_type=${payload.agent_type ?? '-'} source=${payload.source ?? '-'} reason=${payload.reason ?? '-'}`);
     const out = safeHandle(ctx, tool, event, payload);
-    db.log(`hook ${event} (${tool}, tool_name=${payload.tool_name ?? '-'}): ${out === undefined ? 'no output' : `${typeof out === 'string' ? 'text' : 'json'} ${JSON.stringify(out).length} chars`} in ${Date.now() - started}ms`);
+    db.log(`hook ${event} (${tool}, tool_name=${payload.tool_name ?? '-'}): ${out === undefined ? 'no output' : `json ${JSON.stringify(out).length} chars`} in ${Date.now() - started}ms`);
     if (out !== undefined)
-        process.stdout.write(typeof out === 'string' ? out : JSON.stringify(out));
+        process.stdout.write(JSON.stringify(out));
 }
 const isMain = (() => { try {
     return fs.realpathSync.native(process.argv[1] ?? '') === fs.realpathSync.native(fileURLToPath(new URL(import.meta.url)));

package/dist/launch.js

@@ -2,20 +2,21 @@
 // workspace with its repository worktree, and the per-launch hook/MCP configuration for each
 // tool. Hook command strings must stay identical across launches (Codex persists trust by
 // hashing them), so per-session values go in env.
-import { execFileSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as db from "./db.js";
 import { ensureStateDir, resolveProject } from "./project.js";
+import { readConfig } from "./tools.js";
 import { claudeMcpChoices, claudeTrusts } from "./trust.js";
-const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const { git } = db;
 // realpath gives one canonical spelling (drive letter and directory case): Codex persists hook trust by hashing the command string
 // sibling modules by absolute path: .ts when run from src, .js from the built dist
 const here = (f) => fs.realpathSync.native(fileURLToPath(new URL(f + path.extname(fileURLToPath(import.meta.url)), import.meta.url))).split(path.sep).join('/');
-export const HOOKS_TS = here('./hooks');
-export const SERVE_TS = here('./serve');
+const HOOKS_TS = here('./hooks');
+const SERVE_TS = here('./serve');
 /** `staleWaitMs`: how long to watch a stale heartbeat before calling its agent dead (tests shorten it). */
 export function pickName(d, tool, project, override, staleWaitMs = 2500) {
     if (override) {
@@ -162,8 +163,8 @@ export function withNodeOnPath(env) {
     return { ...env, [key]: current ? `${dir}${path.delimiter}${current}` : dir };
 }
 /** `$CLAUDE_PROJECT_DIR` in a repository's hook commands and MCP definitions means the repository, which for an agent
- *  is its worktree; Claude would point it at the workspace. */
-export function substituteProjectDir(value, worktree) {
+ *  is its worktree; Claude would point it at the project folder. */
+function substituteProjectDir(value, worktree) {
     const dir = worktree.split(path.sep).join('/');
     const walk = (v) => {
         if (typeof v === 'string')
@@ -178,7 +179,7 @@ export function substituteProjectDir(value, worktree) {
 }
 /** The repository's .mcp.json as an --mcp-config value, reduced to the servers the user approved in Claude Code, or
  *  null when there is nothing to pass. */
-export function projectMcpConfig(worktree, source) {
+function projectMcpConfig(worktree, source) {
     const file = path.join(worktree, '.mcp.json');
     if (!fs.existsSync(file))
         return null;
@@ -198,6 +199,10 @@ export function projectMcpConfig(worktree, source) {
         process.stderr.write(`chord: not starting the repository's MCP server(s) ${skipped.join(', ')}: run claude in ${source.repo} once and approve them there first\n`);
     return Object.keys(keep).length ? JSON.stringify({ mcpServers: substituteProjectDir(keep, worktree) }) : null;
 }
+/** CLI arguments that inject chord's hooks and MCP server into Claude Code. `projectConfig`: also load the repository's
+ *  own .claude settings and .mcp.json, only when the user has trusted the repository (or the project folder) in Claude
+ *  Code, because Claude's trust dialogue is what normally stands between a cloned repository's hooks and MCP servers
+ *  and running them. */
 export function claudeArgs(env, projectConfig = false) {
     const hooks = {};
     for (const e of EVENTS) {
@@ -215,10 +220,9 @@ export function claudeArgs(env, projectConfig = false) {
     // (the briefing carries CLAUDE.md itself); the others are passed along.
     const wt = env.CHORD_WORKTREE;
     const addDir = wt ? ['--add-dir', wt] : [];
-    const source = projectConfig === true ? { repo: wt ?? '' } : projectConfig || null;
-    const projectMcp = source && wt ? projectMcpConfig(wt, source) : null;
+    const projectMcp = projectConfig && wt ? projectMcpConfig(wt, projectConfig) : null;
     const mcpFiles = projectMcp ? [projectMcp] : [];
-    const settings = source ? mergeProjectSettings(ours, wt) : ours;
+    const settings = projectConfig && wt ? mergeProjectSettings(ours, wt) : ours;
     // --add-dir and --mcp-config take any number of values, so they must not come last: the user's own arguments
     // follow these, and a prompt such as `chord claude "fix the tests"` would be read as another directory.
     // --settings takes exactly one value and closes the list.
@@ -234,9 +238,7 @@ export function mergeUserSettings(args, user) {
     return out;
 }
 const PROJECT_CONFIG_FILES = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json'];
-export const hasProjectConfig = (worktree) => PROJECT_CONFIG_FILES.some(f => fs.existsSync(path.join(worktree, f)));
-/** chord's settings plus the repository's .claude/settings.json and settings.local.json (later files win,
- *  hook lists are concatenated so both chord's and the project's hooks run). */
+const hasProjectConfig = (worktree) => PROJECT_CONFIG_FILES.some(f => fs.existsSync(path.join(worktree, f)));
 /** Hook lists of `b` appended to those of `a`, so both sets run. */
 function concatHooks(a, b) {
     const hooks = { ...(a.hooks ?? {}) };
@@ -246,7 +248,7 @@ function concatHooks(a, b) {
 }
 /** Somebody else's settings underneath chord's: their keys fill in, chord's keys win, hook lists are concatenated,
  *  and disableAllHooks is dropped because it would switch chord itself off. */
-export function mergeSettings(ours, theirs) {
+function mergeSettings(ours, theirs) {
     const out = { ...theirs, ...ours, hooks: concatHooks(ours, theirs) };
     if (ours.permissions || theirs.permissions) {
         // permission lists add up, as across Claude's own settings levels; other permission keys follow the usual precedence
@@ -259,9 +261,9 @@ export function mergeSettings(ours, theirs) {
     delete out.disableAllHooks;
     return out;
 }
+/** chord's settings plus the repository's .claude/settings.json and settings.local.json (later files win, hook lists
+ *  are concatenated so both chord's and the project's hooks run). */
 export function mergeProjectSettings(ours, worktree) {
-    if (!worktree)
-        return ours;
     let theirs = {};
     for (const name of ['settings.json', 'settings.local.json']) { // settings.local.json wins, as in Claude Code itself
         let one;
@@ -280,10 +282,10 @@ export function mergeProjectSettings(ours, worktree) {
 }
 /** A JSON string literal is also a valid TOML basic string, quotes, backslashes and non-ASCII included. */
 const toml = (s) => JSON.stringify(s);
-/** CLI arguments that inject chord's hooks and MCP server into Codex. Values are TOML. */
-/** `writableRoots`: directories Codex's workspace-write sandbox must also be allowed to write. A linked worktree keeps
- *  its index and refs under the main checkout's .git, outside the agent's workspace, so without this every git commit
- *  fails inside the sandbox. */
+/** CLI arguments that inject chord's hooks and MCP server into Codex. Values are TOML. `writableRoots`: directories
+ *  Codex's workspace-write sandbox must also be allowed to write: a linked worktree keeps its index and refs under the
+ *  main checkout's .git. shortcut: the tool now runs in the project folder, which holds that .git, so this may be
+ *  redundant; drop it once a sandboxed Codex has committed from a worktree without it on Linux or macOS. */
 export function codexArgs(env, writableRoots = []) {
     const args = [];
     if (writableRoots.length)
@@ -317,8 +319,9 @@ export function prepare(tool, cwd, override) {
     const name = pickName(d, tool, project.dir, override);
     const ws = workspacePath(project, name);
     // Take the name now, before the worktree and setup take their time: a second launch under the same name a moment
-    // later must find it online. The wrapper re-registers with the tool's own pid when it starts.
-    db.addAgent(d, { name, tool, pid: process.pid, cwd: ws, worktree: path.join(ws, project.repoName), heartbeat: true });
+    // later must find it online. No heartbeat yet: nobody writes one until the wrapper runs, and setup or Codex's first
+    // start can take minutes, so a sweep meanwhile must judge this agent by its (live) pid alone.
+    db.addAgent(d, { name, tool, pid: process.pid, cwd: ws });
     try {
         const config = readConfig(project);
         const worktree = ensureWorktree(project.repo, path.join(ws, project.repoName), name);
@@ -335,7 +338,7 @@ export function prepare(tool, cwd, override) {
         if (tool === 'claude' && hasProjectConfig(worktree)) {
             projectConfig = claudeTrusts(project.repo) || claudeTrusts(project.dir) ? { repo: project.repo } : false;
             if (!projectConfig)
-                process.stderr.write(`chord: ${project.repo} has its own .claude settings or .mcp.json, but you have not trusted it in Claude Code, so they are not loaded for this agent. Run claude in ${project.repo} once and accept the trust prompt to change that.\n`);
+                process.stderr.write(`chord: ${project.repo} has its own .claude settings or .mcp.json, but you have not trusted it or the project folder in Claude Code, so they are not loaded for this agent. Run claude in ${project.repo} once and accept the trust prompt to change that.\n`);
         }
         return { name, project, cwd: ws, worktree, dbFile, env, args: tool === 'claude' ? claudeArgs(env, projectConfig) : codexArgs(env, [path.join(project.repo, '.git')]) };
     }
@@ -344,37 +347,6 @@ export function prepare(tool, cwd, override) {
         throw e;
     }
 }
-/** <project>/chord/config.json. `setup` is a shell command run in every new worktree before the agent starts,
- *  for example "npm install". `test` is a shell command finish runs in the worktree after rebasing onto main and
- *  before fast-forwarding it, for example "npm test"; when it fails nothing is merged. */
-export function readConfig(project) {
-    const file = path.join(project.dir, 'chord', 'config.json');
-    let raw;
-    try {
-        raw = fs.readFileSync(file, 'utf8');
-    }
-    catch {
-        return {};
-    }
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
-    }
-    catch (e) {
-        throw new Error(`${file} is not valid JSON: ${e.message}`);
-    }
-    if (typeof cfg !== 'object' || cfg === null)
-        throw new Error(`${file} must hold a JSON object`);
-    const out = {};
-    for (const key of ['setup', 'test']) {
-        const v = cfg[key];
-        if (v !== undefined && typeof v !== 'string')
-            throw new Error(`${file}: "${key}" must be a string (a shell command)`);
-        if (v)
-            out[key] = v;
-    }
-    return out;
-}
 /** Where `chord clean` and a relaunch look to see whether the setup command has run for this agent. */
 export const setupMarker = (project, name) => path.join(project.stateDir, 'setup-done', name);
 /** A failed setup aborts the launch, and the half-prepared worktree and branch go with it so the next launch starts clean. */

package/dist/mcp.js

@@ -1,6 +1,8 @@
 // Minimal MCP server over stdio: newline-delimited JSON-RPC 2.0, tools only.
+import fs from 'node:fs';
 import { createInterface } from 'node:readline';
 const PROTOCOL = '2025-06-18';
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version; // src/ and dist/ both sit under the package root
 /** Handle one JSON-RPC message. Returns the response, or undefined for notifications. */
 export function handle(tools, req) {
     const { id, method, params = {} } = req;
@@ -10,7 +12,7 @@ export function handle(tools, req) {
     const err = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
     switch (method) {
         case 'initialize':
-            return ok({ protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'chord', version: '0.0.0' } });
+            return ok({ protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'chord', version: VERSION } });
         case 'ping':
             return ok({});
         case 'tools/list':

package/dist/project.js

@@ -1,11 +1,10 @@
 // A chord project is the folder `chord` is run in. It contains the git repository as a child
 // directory and a `chord/` directory for agent workspaces; chord's own state lives under ~/.chord.
 import { createHash } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { gitEnv } from "./db.js";
+import { git } from "./db.js";
 /** Thrown when the folder is a repository root: chord offers to move it into a child directory. */
 export class NeedsRestructure extends Error {
     dir;
@@ -16,8 +15,9 @@ export class NeedsRestructure extends Error {
         this.suggestedName = suggestedName;
     }
 }
-const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+// Windows and macOS file systems ignore case: two spellings are one folder
+const CASE_INSENSITIVE = process.platform !== 'linux';
+const same = (a, b) => (CASE_INSENSITIVE ? a.toLowerCase() === b.toLowerCase() : a === b);
 function repoRootOf(dir) {
     try {
         return fs.realpathSync.native(git(dir, 'rev-parse', '--show-toplevel'));
@@ -36,10 +36,10 @@ catch {
 /** Readable like Claude Code's projects directory (separators and colons become dashes), plus a short hash so
  *  that D:\a-b and D:\a\b do not share one state directory. */
 export function encodeProjectPath(dir) {
-    const key = process.platform === 'win32' ? dir.toLowerCase() : dir;
+    const key = CASE_INSENSITIVE ? dir.toLowerCase() : dir;
     return `${dir.replace(/[\\/:]/g, '-')}-${createHash('sha1').update(key).digest('hex').slice(0, 6)}`;
 }
-export const stateDirFor = (dir) => path.join(process.env.CHORD_HOME ?? path.join(os.homedir(), '.chord'), 'projects', encodeProjectPath(dir));
+const stateDirFor = (dir) => path.join(process.env.CHORD_HOME ?? path.join(os.homedir(), '.chord'), 'projects', encodeProjectPath(dir));
 /** A repository directory name chord can work with: a single path segment that is not chord's own directory. */
 export function validateRepoName(name) {
     if (!name.trim())
@@ -63,7 +63,6 @@ export function suggestedRepoName(repo) {
     const own = path.basename(repo);
     return validateRepoName(own) ? 'repo' : own;
 }
-/** The nearest ancestor that already is a chord project, if any. */
 /** Child directories of `dir` that are repository roots. Looked up with stat, so a junction or symlink to a repository
  *  counts (a Dirent reports those as links, not directories). */
 const repoChildren = (dir) => fs.readdirSync(dir).filter(n => { const p = path.join(dir, n); try {

package/dist/pty.js

@@ -1,6 +1,7 @@
 // Run the agent under a pseudo-terminal: pass the user's keyboard through, and when the
 // agent is idle with unread messages, type a nudge in as if the user had.
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 import pty from 'node-pty';
@@ -32,6 +33,27 @@ export function resolveCommand(tool, readFile = (f) => fs.readFileSync(f, 'utf8'
         throw new Error(`cannot read the script path from ${hit}`);
     return { file: process.execPath, args: [path.join(path.dirname(hit), m[1])] };
 }
+/** On macOS node-pty starts the tool through its `spawn-helper` binary, which the prebuilt package ships without the
+ *  execute bit (and npm no longer runs install scripts that might set it), so every launch would fail with
+ *  "posix_spawnp failed". The bit is set here, or the error says how when the install directory is not writable. */
+export function ensureSpawnHelper(root = path.dirname(createRequire(import.meta.url).resolve('node-pty/package.json'))) {
+    for (const dir of ['build/Release', 'build/Debug', `prebuilds/${process.platform}-${process.arch}`]) { // where node-pty looks
+        const helper = path.join(root, dir, 'spawn-helper');
+        if (!fs.existsSync(helper))
+            continue;
+        try {
+            fs.accessSync(helper, fs.constants.X_OK);
+            continue;
+        }
+        catch { /* not executable */ }
+        try {
+            fs.chmodSync(helper, 0o755);
+        }
+        catch (e) {
+            throw new Error(`${helper} is not executable, so no agent can start (${e.message}); run: chmod +x "${helper}"`);
+        }
+    }
+}
 const ESC_KEY = ''; // a decoded Esc key, kept apart from escape sequences while they are stripped
 const SOFT_NL = ''; // Shift+Enter: a newline inside the draft, not a submit
 /**
@@ -144,8 +166,8 @@ export function typedEchoed(output, text) {
 }
 /** The Esc key as the tool reads it: in win32-input-mode (ConPTY turns a bare ESC byte into nothing, waiting for a
  *  sequence) a key-down and key-up record; elsewhere the CSI u form the tools ask for (`ESC [ > 5 u`), which a legacy
- *  reader ignores harmlessly. Linux form not yet verified against the real tools. */
-export const ESC_INPUT = process.platform === 'win32' ? '\x1b[27;1;27;1;0;1_\x1b[27;1;27;0;0;1_' : '\x1b[27u';
+ *  reader ignores harmlessly. Verified against Claude Code on macOS; on Linux not yet. */
+const ESC_INPUT = process.platform === 'win32' ? '\x1b[27;1;27;1;0;1_\x1b[27;1;27;0;0;1_' : '\x1b[27u';
 /** Did the tool answer the exit command with its "background work is running, exit and stop it or stay?" dialogue?
  *  Claude Code asks this while a shell the agent started (a monitor it is waiting on, say) still runs. */
 export function exitDeclined(output) {
@@ -200,14 +222,18 @@ export function nextAction(s, now) {
         return 'enter'; // typed and echoed but not submitted: press Enter once more
     return null;
 }
-/** Codex reports its state to the terminal as OSC 7501 ("state=idle" / "state=working"); Claude Code does not. */
+/** Codex reports its state to the terminal as OSC 7501 ("state=idle" / "state=working", and "state=done" when a turn
+ *  ends, as of 0.164); Claude Code does not. */
 export function oscState(chunk) {
-    const m = /\x1b\]7501;state=(\w+)/g;
+    const m = /\x1b\]7501;state=(\w+)[^\x07\x1b]*(?:\x07|\x1b\\)/g; // complete reports only: "state=id" cut off by a chunk is not "busy"
     let last = null;
     for (const x of chunk.matchAll(m))
-        last = x[1] === 'idle' ? 'idle' : 'busy';
+        last = x[1] === 'idle' || x[1] === 'done' ? 'idle' : 'busy';
     return last;
 }
+/** An OSC sequence a chunk ends in the middle of, to prepend to the next chunk; '' when the chunk ends cleanly, so a
+ *  complete report is never read twice. */
+export const oscTail = (chunk) => /\x1b\][^\x07\x1b]*$/.exec(chunk)?.[0] ?? '';
 /** A database call from the wrapper's own callbacks. One that fails (a lock held past busy_timeout while the disk
  *  stalls) is logged and dropped: thrown from a timer or a PTY callback it would end the wrapper and the agent in
  *  it, and the next tick or terminal report puts the state right anyway. */
@@ -229,7 +255,10 @@ export function run(tool, launch, extraArgs) {
         name: 'xterm-256color', cols: process.stdout.columns || 120, rows: process.stdout.rows || 40, cwd: launch.project.dir, env, // the project folder: the tool then treats it as the project (same /resume list, CLAUDE.md, trust)
     });
     const d = db.openDb(launch.dbFile);
-    db.addAgent(d, { name: launch.name, tool, pid: term.pid, cwd: launch.cwd, worktree: launch.worktree, heartbeat: true });
+    // prepare registered the agent; the wrapper only takes it over (a fresh registration would drop messages that
+    // arrived during setup and a stop requested meanwhile)
+    db.setPid(d, launch.name, term.pid);
+    db.heartbeat(d, launch.name);
     let outTail = '', echoBuf = '', awaitingEcho = false, lastOutputAt = Date.now();
     const titles = new TitleFilter();
     let title = titleFor(launch.name, null);
@@ -243,7 +272,7 @@ export function run(tool, launch, extraArgs) {
             const state = oscState(outTail + x);
             if (state)
                 tolerant('terminal state report', () => db.setStatus(d, launch.name, state));
-            outTail = x.slice(-64);
+            outTail = oscTail(x);
         }
     });
     const gate = new InputGate();
@@ -258,8 +287,13 @@ export function run(tool, launch, extraArgs) {
     const onResize = () => term.resize(process.stdout.columns || 120, process.stdout.rows || 40);
     process.stdout.on('resize', onResize);
     Object.assign(process.env, launch.env); // so the wrapper writes to the same chord.db.log as the hooks
-    let typed = null, typedAt = 0, enteredAt = 0, enters = 0, echoed = false, lastState = '';
+    let typed = null, typedAt = 0, enteredAt = 0, enters = 0, echoed = false, lastState = '', lastTick = Date.now();
     const timer = setInterval(() => tolerant('wake loop', () => {
+        // a tick long overdue means the machine slept: vouch for every wrapper before a hook sweeps the ones not yet awake
+        const now = Date.now();
+        if (now - lastTick > db.HEARTBEAT_STALE_MS)
+            db.heartbeatAll(d);
+        lastTick = now;
         db.heartbeat(d, launch.name);
         const me = db.getAgent(d, launch.name);
         const wanted = titleFor(launch.name, me?.task);

package/dist/serve.js

@@ -1,13 +1,11 @@
 // Entry point for the per-agent MCP server. Spawned by the coding agent over stdio, in the project folder; the
-// agent's workspace comes from the CHORD_* environment, not from cwd.
+// agent's workspace comes from the CHORD_* environment, never from cwd, which would make every claim path wrong.
 import { openDb } from "./db.js";
 import { serve } from "./mcp.js";
 import { tools } from "./tools.js";
-const agent = process.env.CHORD_AGENT_ID;
-const file = process.env.CHORD_DB;
-if (!agent || !file) {
-    process.stderr.write('chord: CHORD_AGENT_ID and CHORD_DB must be set\n');
+const { CHORD_AGENT_ID: agent, CHORD_DB: file, CHORD_WORKSPACE: cwd, CHORD_WORKTREE: worktree } = process.env;
+if (!agent || !file || !cwd || !worktree) {
+    process.stderr.write('chord: CHORD_AGENT_ID, CHORD_DB, CHORD_WORKSPACE and CHORD_WORKTREE must be set\n');
     process.exit(2);
 }
-const cwd = process.env.CHORD_WORKSPACE ?? process.cwd();
-serve(tools({ db: openDb(file), agent, cwd, worktree: process.env.CHORD_WORKTREE ?? cwd, project: process.env.CHORD_PROJECT }));
+serve(tools({ db: openDb(file), agent, cwd, worktree, project: process.env.CHORD_PROJECT }));