chord-cli 0.2.0 → 0.2.2

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 }));

package/dist/tools.js

@@ -1,40 +1,47 @@
-import { execFileSync, execSync } from 'node:child_process';
+import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import * as db from "./db.js";
-import { readConfig } from "./launch.js";
+/** path.relative, except that on macOS directory names differing only in case match, as path.relative already has them
+ *  on Windows: both file systems ignore case, so /P/Repo is /P/repo, and a write must not slip past a check that way. */
+function relativePath(from, to) {
+    if (process.platform !== 'darwin')
+        return path.relative(from, to);
+    const a = path.resolve(from).split('/').filter(Boolean), b = path.resolve(to).split('/').filter(Boolean);
+    let i = 0;
+    while (i < a.length && i < b.length && a[i].toLowerCase() === b[i].toLowerCase())
+        i++;
+    return [...a.slice(i).map(() => '..'), ...b.slice(i)].join('/');
+}
 /** Is `file` inside `dir`? False for paths on another drive or above it. */
 export function insideDir(dir, file) {
-    const rel = path.relative(dir, path.resolve(dir, file));
+    const rel = relativePath(dir, path.resolve(dir, file));
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 }
 /**
- * The claim key for a path an agent names: workspace-relative with forward slashes. Absolute paths and
- * paths starting with the repository directory are taken as given; a path from the project folder
- * (chord/agents/<name>/<repo>/...) is resolved there; any other relative path is read as
- * repository-relative (what agents working inside the repo naturally write). Paths outside the
+ * The claim key for a path an agent names: workspace-relative with forward slashes. Absolute paths are taken as
+ * given; a path from the project folder (chord/agents/<name>/<repo>/...) is resolved there; any other relative
+ * path is repository-relative (what agents working on the repository naturally write). Paths outside the
  * workspace are refused: chord cannot coordinate them.
  */
 export function claimPath(ctx, file) {
-    const repoDir = path.relative(ctx.cwd, ctx.worktree).split(path.sep).join('/');
     const asGiven = normFile(ctx, file);
     let abs;
     const fromProject = 'chord/agents/'; // the spelling from the tool's cwd, the project folder; another agent's folder then fails the check below
-    if (path.isAbsolute(file) || !repoDir || repoDir === '.' || /^\.\.(\/|$)/.test(asGiven))
+    if (path.isAbsolute(file) || /^\.\.(\/|$)/.test(asGiven))
         abs = path.resolve(ctx.cwd, file);
     else if (ctx.project && asGiven.startsWith(fromProject))
         abs = path.resolve(ctx.project, file);
-    else if (asGiven === repoDir || asGiven.startsWith(repoDir + '/')) {
-        // "rich/console.py" is the workspace path of the repository's console.py, or the repository path of a package
-        // named like the repository (rich/rich/console.py); whichever exists is meant, and both existing is ambiguous
-        const asWorkspace = path.resolve(ctx.cwd, file), asRepo = path.resolve(ctx.worktree, file);
-        const w = fs.existsSync(asWorkspace), r = fs.existsSync(asRepo);
-        if (w && r && asWorkspace !== asRepo)
-            throw new Error(`${file} is ambiguous: it could be ${normFile(ctx, asWorkspace)} or ${normFile(ctx, asRepo)}; give the path from your workspace root`);
-        abs = r && !w ? asRepo : asWorkspace;
-    }
-    else
+    else {
         abs = path.resolve(ctx.worktree, file);
+        // From the project folder "<repo>/x" is the main checkout's x. An agent naming its own copy that way, where the
+        // repository has no such path but x exists at its root, is told the spellings that reach it rather than given a
+        // claim on a file that is not there.
+        const repoName = path.basename(ctx.worktree), inner = asGiven.slice(repoName.length + 1);
+        if (asGiven.startsWith(`${repoName}/`) && !fs.existsSync(abs) && fs.existsSync(path.resolve(ctx.worktree, inner))) {
+            throw new Error(`there is no ${asGiven} in the repository, but it has ${inner}: name files relative to the repository root ("${inner}") or from the project folder ("chord/agents/<you>/${repoName}/${inner}")`);
+        }
+    }
     if (!insideDir(ctx.cwd, abs))
         throw new Error(`${file} is outside your workspace; chord only coordinates files under ${ctx.cwd}`);
     return normFile(ctx, abs);
@@ -42,7 +49,7 @@ export function claimPath(ctx, file) {
 /** How long a latecomer waits for replies before it may write anyway. */
 export const REPLY_TIMEOUT_MS = 10 * 60 * 1000;
 /** How long before its claim a latecomer's message to an occupant still counts as asking about that file. */
-export const ASK_WINDOW_MS = 2 * 60 * 1000;
+const ASK_WINDOW_MS = 2 * 60 * 1000;
 const str = (desc) => ({ type: 'string', description: desc });
 function req(args, key) {
     const v = args[key];
@@ -50,9 +57,9 @@ function req(args, key) {
         throw new Error(`${key} is required`);
     return v;
 }
-/** Worktree-relative path with forward slashes, so the same file matches across worktrees. */
+/** Workspace-relative path with forward slashes (repo/src/x.ts), so the same file matches across agents' worktrees. */
 export function normFile(ctx, file) {
-    return path.relative(ctx.cwd, path.resolve(ctx.cwd, file)).split(path.sep).join('/');
+    return relativePath(ctx.cwd, path.resolve(ctx.cwd, file)).split(path.sep).join('/');
 }
 export function peers(ctx) {
     return db.listAgents(ctx.db).filter(a => a.name !== ctx.agent).map(a => ({
@@ -61,10 +68,11 @@ export function peers(ctx) {
 }
 // words that describe code rather than name it: "the parse function" and "parse tests" share only "parse"
 const NOT_SYMBOLS = new Set(['a', 'an', 'and', 'or', 'the', 'of', 'in', 'to', 'for', 'with', 'new', 'its', 'all', 'function', 'functions', 'method', 'methods', 'class', 'classes', 'test', 'tests', 'block', 'blocks', 'section', 'line', 'lines', 'file', 'helper', 'helpers', 'code', 'logic', 'docs', 'docstring']);
-const symbolSet = (s) => new Set((s ?? '').toLowerCase().match(/[a-z_$][\w$.]*/g)?.filter(w => !NOT_SYMBOLS.has(w)) ?? []);
+// "Parser.parse" names Parser and parse too: whoever holds either holds part of it
+const symbolSet = (s) => new Set((s ?? '').toLowerCase().match(/[a-z_$][\w$.]*/g)?.flatMap(w => [w, ...w.split('.')]).filter(w => w && !NOT_SYMBOLS.has(w)) ?? []);
 /** Two modify claims on one file that each name the functions or blocks they touch, with none in common, do not
  *  need to talk first. Anything less certain (no symbols on either side, or an add, delete or rename) does. */
-export function disjointEdits(a, b) {
+function disjointEdits(a, b) {
     if (a.kind !== 'modify' || b.kind !== 'modify')
         return false;
     const x = symbolSet(a.symbols), y = symbolSet(b.symbols);
@@ -73,7 +81,9 @@ export function disjointEdits(a, b) {
 /** Online agents who claimed `file` before `mine` did, split into those `mine` overlaps and must talk to and those
  *  editing other parts of it. */
 function earlierOccupants(ctx, mine) {
-    const before = (c) => c.created_at < mine.created_at || (c.created_at === mine.created_at && c.rid < mine.rid);
+    // by rowid, which the insert gets under the write lock, not by the timestamp read before waiting for it: two
+    // agents claiming at once would otherwise each see the other as later and neither would talk first
+    const before = (c) => c.rid < mine.rid;
     const all = db.claimsFor(ctx.db, mine.file).filter(c => c.agent !== ctx.agent && before(c) && db.getAgent(ctx.db, c.agent)?.status !== 'offline');
     return { overlap: all.filter(c => !disjointEdits(c, mine)), elsewhere: all.filter(c => disjointEdits(c, mine)) };
 }
@@ -103,7 +113,7 @@ export function canWrite(ctx, file, now = Date.now()) {
         const askedAt = db.firstMessageAt(ctx.db, ctx.agent, o.agent, Math.max(since, mine.created_at - ASK_WINDOW_MS));
         if (askedAt === null)
             notAsked.push(o.agent);
-        else if (!db.repliedSince(ctx.db, o.agent, ctx.agent, since) && now - askedAt < REPLY_TIMEOUT_MS)
+        else if (db.firstMessageAt(ctx.db, o.agent, ctx.agent, since) === null && now - askedAt < REPLY_TIMEOUT_MS)
             waiting.push({ agent: o.agent, left: REPLY_TIMEOUT_MS - (now - askedAt) });
     }
     if (notAsked.length) {
@@ -115,9 +125,7 @@ export function canWrite(ctx, file, now = Date.now()) {
     }
     return { ok: true };
 }
-// 64 MB of output: a project's post-merge hook may print a great deal, and the default 1 MB would turn a merge that
-// already happened into an exception
-const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 }).trim();
+const { git } = db;
 const gitOk = (cwd, ...args) => { try {
     git(cwd, ...args);
     return true;
@@ -126,7 +134,7 @@ catch {
     return false;
 } };
 const stderrOf = (e) => (e.stderr ?? e.message).trim();
-const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const { sleepSync } = db;
 /** Tracked files with real changes, staged or not, ignoring line-ending differences and whatever happens inside
  *  submodules; '' when clean. */
 export function dirtyTracked(cwd) {
@@ -148,8 +156,10 @@ function gitRetry(cwd, ...args) {
         }
     }
 }
-/** Run fn holding an exclusive lock file. Waits up to `waitMs`; a lock older than `staleMs` is taken over. */
-export function withLock(file, fn, waitMs = 240_000, staleMs = 180_000) {
+/** Run fn holding an exclusive lock file that names its holder's pid. Waits up to `waitMs`. A lock whose holder is
+ *  gone is taken over at once; one older than `staleMs` as well, which must exceed the longest run of the project's
+ *  test command (ten minutes) so a live holder is never robbed of its lock. */
+export function withLock(file, fn, waitMs = 240_000, staleMs = 15 * 60_000) {
     const t0 = Date.now();
     for (;;) {
         try {
@@ -160,7 +170,8 @@ export function withLock(file, fn, waitMs = 240_000, staleMs = 180_000) {
             if (e.code !== 'EEXIST')
                 throw e;
             try {
-                if (Date.now() - fs.statSync(file).mtimeMs > staleMs) {
+                const holder = Number(fs.readFileSync(file, 'utf8'));
+                if ((holder > 0 && !db.pidAlive(holder)) || Date.now() - fs.statSync(file).mtimeMs > staleMs) {
                     fs.unlinkSync(file);
                     continue;
                 }
@@ -173,16 +184,50 @@ export function withLock(file, fn, waitMs = 240_000, staleMs = 180_000) {
             sleepSync(150 + Math.random() * 200);
         }
     }
+    // only our own lock is removed: one taken over meanwhile belongs to whoever holds it now
     try {
         return fn();
     }
     finally {
         try {
-            fs.unlinkSync(file);
+            if (fs.readFileSync(file, 'utf8') === String(process.pid))
+                fs.unlinkSync(file);
         }
         catch { /* already gone */ }
     }
 }
+/** <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. Lives here, not in launch.ts,
+ *  so the hooks (which load this module for finish's sake) do not load the launch code on every tool call. */
+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;
+}
 /** Rebase the agent's branch onto main and fast-forward main to it. Atomic from the agent's point of view.
  *  Finishes are serialised with a lock file: git cannot run two merges in one checkout concurrently. */
 export function finish(ctx) {
@@ -193,9 +238,9 @@ function finishLocked(ctx) {
     const wt = ctx.worktree;
     // A rebase in progress is only ours to clean up when finish itself started it (a finish killed mid-rebase leaves
     // the marker behind). Anyone else's rebase, perhaps with conflicts already resolved, is left alone.
-    const marker = path.resolve(wt, git(wt, 'rev-parse', '--git-path', 'chord-finish'));
-    for (const dir of ['rebase-merge', 'rebase-apply']) {
-        if (!fs.existsSync(path.resolve(wt, git(wt, 'rev-parse', '--git-path', dir))))
+    const [marker, rebaseMerge, rebaseApply, indexLock] = git(wt, 'rev-parse', '--git-path', 'chord-finish', '--git-path', 'rebase-merge', '--git-path', 'rebase-apply', '--git-path', 'index.lock').split('\n').map(p => path.resolve(wt, p));
+    for (const dir of [rebaseMerge, rebaseApply]) {
+        if (!fs.existsSync(dir))
             continue;
         if (!fs.existsSync(marker))
             throw new Error('a rebase is in progress in your worktree that finish did not start; run `git rebase --continue` (after resolving conflicts) or `git rebase --abort` first');
@@ -204,7 +249,6 @@ function finishLocked(ctx) {
     }
     fs.rmSync(marker, { force: true });
     // a finish killed mid-operation can leave the worktree's own index.lock behind; one older than a minute is debris
-    const indexLock = path.resolve(wt, git(wt, 'rev-parse', '--git-path', 'index.lock'));
     try {
         if (Date.now() - fs.statSync(indexLock).mtimeMs > 60_000) {
             fs.unlinkSync(indexLock);
@@ -217,6 +261,12 @@ function finishLocked(ctx) {
     // such file as modified the moment it is checked out, and no agent can commit that away.
     if (dirtyTracked(wt))
         throw new Error('your worktree has uncommitted changes to tracked files; commit them first');
+    // Except the files this agent claimed: one it wrote and never added (git commit -a skips new files) would leave
+    // main with half the change, and the claim that protected it would be released below.
+    const claimed = db.claimsBy(ctx.db, ctx.agent).map(c => relativePath(wt, path.resolve(ctx.cwd, c.file)).split(path.sep).join('/')).filter(f => f && !f.startsWith('..'));
+    const lost = claimed.length ? git(wt, 'ls-files', '--others', '--exclude-standard', '--', ...claimed) : '';
+    if (lost)
+        throw new Error(`you claimed ${lost.split('\n').join(', ')} but never committed it: git add and commit it (or release the claim) and call finish again. Nothing was merged.`);
     // What status still reports now differs only in line endings. git will not rebase over it, and nothing done in a
     // worktree can clear it: the repository needs a renormalised commit, which is the user's call.
     const phantom = git(wt, 'status', '--porcelain', '--untracked-files=no', '--ignore-submodules=dirty').split('\n').filter(Boolean).map(l => l.replace(/^[ MADRCU?!]{1,2}\s+/, ''));
@@ -269,7 +319,7 @@ function finishLocked(ctx) {
     const subjects = git(root, 'log', '--format=%s', `${main}..${branch}`).split('\n').filter(Boolean);
     // A submodule commit the branch points at must exist in the main checkout's copy of the submodule, or the
     // fast-forward leaves main pointing at a commit that is nowhere but inside this agent's worktree.
-    for (const line of git(root, 'diff', '--raw', main, branch).split('\n')) {
+    for (const line of git(root, '-c', 'core.quotePath=false', 'diff', '--raw', main, branch).split('\n')) { // a non-ASCII path arrives as itself, not quoted and escaped
         const m = /^:\d{6} 160000 [0-9a-f]+ ([0-9a-f]+) [AM]\t(.+)$/.exec(line);
         if (!m)
             continue;
@@ -355,7 +405,6 @@ export function tools(ctx) {
                 db.addClaim(ctx.db, { agent: ctx.agent, file, intent: req(a, 'intent'), kind, symbols: typeof a.symbols === 'string' ? a.symbols : null });
                 const mine = db.claimsFor(ctx.db, file).find(c => c.agent === ctx.agent);
                 const { overlap: others, elsewhere } = earlierOccupants(ctx, mine);
-                db.log(`claim ${file} by ${ctx.agent} (cwd ${ctx.cwd}): rows=${JSON.stringify(db.claimsFor(ctx.db, file).map(c => [c.agent, c.created_at]))} agents=${JSON.stringify(db.listAgents(ctx.db).map(a => [a.name, a.status, a.pid]))} others=${others.map(o => o.agent)} elsewhere=${elsewhere.map(o => o.agent)}`);
                 const brief = (o) => ({ agent: o.agent, intent: o.intent, kind: o.kind, symbols: o.symbols });
                 return {
                     claimed: file,