chord-cli 0.2.0 → 0.2.2

package/README.md

@@ -5,8 +5,8 @@
 <p align="center">
   <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue"></a>
   <img alt="Node 24 or later" src="https://img.shields.io/badge/node-%E2%89%A5%2024-339933?logo=nodedotjs&logoColor=white">
-  <img alt="Windows and Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-blue">
-  <a href="README.zh-CN.md"><img alt="中文说明" src="https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-2F7CF6"></a>
+  <img alt="Windows, macOS and Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue">
+  <a href="README-zh-CN.md"><img alt="中文说明" src="https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-2F7CF6"></a>
 </p>
 
 One repository, as many agents as you care to start. Each agent works in its own worktree; a shared board records who holds which file; an agent that wants a file another agent holds asks first and waits for the answer; when the work is committed, one call rebases the branch and fast-forwards main. Idle agents are woken the moment a message arrives, so the agents negotiate among themselves while you keep handing out work in plain language.
@@ -30,7 +30,7 @@ One repository, as many agents as you care to start. Each agent works in its own
 
 ## 📊 Benchmark
 
-On [CooperBench](https://github.com/cooperbench/CooperBench) two agents each take one feature in the same repository, and a pair passes when the merged result passes the tests of both features. The gpt-6-luna figures cover the pairs where both sides finished.
+On [CooperBench](https://github.com/cooperbench/CooperBench) two agents each take one feature in the same repository, and a pair passes when the merged result passes the tests of both features.
 
 | chord vs | gpt-6.1-sol | gpt-6-luna |
 |---|---|---|
@@ -67,7 +67,7 @@ A new agent needs three things from its tool: a way to inject hooks and an MCP s
 
 1. **Isolation.** Every agent works on its own branch in its own worktree. The main checkout changes through `finish` alone.
 2. **Coordination.** A shared board holds claims, messages and events. Agents register, claim and talk through tools chord gives them; hooks check claims before each write and hand new messages to the agent as it works.
-3. **Merging.** `finish` rebases the branch onto main and fast-forwards. A clean rebase merges; anything else stops where it is and waits for you.
+3. **Merging.** `finish` rebases the branch onto main and fast-forwards. A clean rebase that passes the project's test command merges; on a conflict nothing moves, and the agent resolves it and finishes again.
 
 ## 📦 Install
 
@@ -77,7 +77,7 @@ With Node 24 and git on the machine:
 npm install -g chord-cli
 ```
 
-On Linux add `--allow-scripts=node-pty`, with python3, make and g++ present: node-pty ships no Linux binary and builds one on install.
+On Linux add `--allow-scripts=node-pty`, with python3, make and g++ present: node-pty ships no Linux binary and builds one on install. macOS needs nothing more: node-pty ships a binary for it.
 
 Or from source:
 
@@ -129,6 +129,7 @@ Agents start in the project folder, the same directory you run plain `claude` or
 | `chord events [agent] [-n N]` | claim, release, merge and conflict history |
 | `chord stop <agent>` | quit an agent once its turn ends and its input box is empty |
 | `chord clean [--force] [agent...]` | remove offline agents' workspaces, worktrees and branches; work not yet on main stays unless `--force` |
+| `chord --version` | the installed version |
 
 ## ⚙️ Configuration
 
@@ -142,20 +143,20 @@ Agents start in the project folder, the same directory you run plain `claude` or
 
 `test`, when set, runs in the agent's worktree each time `finish` has rebased the branch onto main, before main moves. If it fails nothing is merged and the agent gets the end of the output: a clean rebase can still break what another agent merged. Other agents' `finish` waits while it runs.
 
-A repository's own Claude configuration (`.claude/settings*.json`, `.mcp.json`) reaches an agent once you have trusted that repository in Claude Code yourself; the MCP servers you approved there are the ones that start.
+A repository's own Claude configuration (`.claude/settings*.json`, `.mcp.json`) reaches an agent once you have trusted that repository, or the project folder, in Claude Code yourself; the MCP servers you approved there are the ones that start.
 
 ## 🔌 How chord works with your tools
 
 - **Waking an agent** means typing a short note into its terminal. chord does this only when the input box is empty, the keyboard has been quiet for a few seconds, and the terminal has echoed the note; a dialogue never receives the Enter.
 - **Trust**: agents run in the project folder, so Claude asks about it once, as it does for plain `claude`; chord writes nothing to `~/.claude.json`. Codex asks you to review chord's hooks once, and again whenever their definition changes; answer "trust all". chord says so at launch if a hook has been switched off.
 - **Branches and worktrees.** Each agent adds a `chord/<name>` branch and a worktree; `chord clean` removes them when the agent has left and keeps anything not yet on main.
-- **Permissions.** chord's own tools are pre-approved for Claude, so an agent working on its own is never parked at a prompt for them; your usual shell and edit approvals apply as before. Codex runs with full access. On Windows chord refuses a sandboxed launch, because that sandbox cannot run the hooks; on Linux the hooks run inside the sandbox, but Codex then asks you to approve each chord tool call.
+- **Permissions.** chord's own tools are pre-approved for Claude, so an agent working on its own is never parked at a prompt for them; your usual shell and edit approvals apply as before. Codex keeps the sandbox and approval mode from your own configuration. On Windows chord refuses a sandbox given on the command line, because that sandbox cannot run the hooks; on Linux and macOS the hooks run inside the sandbox, but Codex then asks you to approve each chord tool call.
 - **The terminal title** reads `chord <agent> · <task>`, so each window says which agent it is.
 - **Hooks gate the editor tools.** Files changed from the shell are reported by name after each command, with the claim to make.
 
 ## 🗺️ Scope
 
-- Runs on Windows 11 and Linux.
+- Runs on Windows 11, macOS and Linux.
 - One repository per project.
 - Project paths up to about 190 characters.
 - A repository with CRLF files and a `* text` attribute that was never renormalised shows phantom changes in every worktree; chord names the files and the command that puts the repository right.

package/dist/clean.js

@@ -1,10 +1,9 @@
 // chord clean: remove the workspaces, worktrees and branches of agents that are gone.
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import * as db from "./db.js";
 import { setupMarker } from "./launch.js";
-const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+const { git } = db;
 /** Remove offline agents (all of them, or the named ones). An agent whose branch has commits that are not on
  *  main, or whose worktree has uncommitted work, is kept unless `force`; an online agent is always kept. Directories
  *  under chord/agents/ with no database row (a launch that died before the tool started) are treated the same way. */
@@ -40,13 +39,18 @@ export function clean(project, d, names = [], force = false) {
             }
             // work that was never committed (an agent stopped half-way) is just as much work as an unmerged commit
             if (!force && fs.existsSync(path.join(wt, '.git'))) {
+                const rel = path.relative(project.dir, wt).split(path.sep).join('/');
                 let dirty = '';
+                // a worktree git cannot read (its link broken by a move) may still hold work: not knowing is not clean
                 try {
                     dirty = git(wt, 'status', '--porcelain');
                 }
-                catch { /* a broken worktree holds nothing to keep */ }
+                catch {
+                    kept(a.name, `uncommitted changes unknown: git status failed in ${rel}`);
+                    return;
+                }
                 if (dirty) {
-                    kept(a.name, `uncommitted changes in ${path.relative(project.dir, wt).split(path.sep).join('/')}`);
+                    kept(a.name, `uncommitted changes in ${rel}`);
                     return;
                 }
             }

package/dist/cli.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 // The chord command line; see USAGE.
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -9,7 +8,7 @@ import { clean } from "./clean.js";
 import * as db from "./db.js";
 import { mergeUserSettings, prepare } from "./launch.js";
 import { NeedsRestructure, knownProjects, resolveProject, restructure, restructureBlocker, validateRepoName } from "./project.js";
-import { resolveCommand, run } from "./pty.js";
+import { ensureSpawnHelper, resolveCommand, run } from "./pty.js";
 import { codexFirstStart, disabledCodexHooks } from "./trust.js";
 const USAGE = [
     'usage: chord <command> [arguments]',
@@ -27,14 +26,12 @@ const USAGE = [
     '  ... stands for arguments passed on to the tool.',
     '',
 ].join('\n');
-const gitOut = (cwd, ...args) => {
-    try {
-        return execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    }
-    catch {
-        return undefined;
-    }
-};
+const gitOut = (cwd, ...args) => { try {
+    return db.git(cwd, ...args);
+}
+catch {
+    return undefined;
+} };
 /** "12s", "3m", "2h", "5d": how long ago. */
 export function ago(ms) {
     const s = Math.max(0, Math.round(ms / 1000));
@@ -188,7 +185,6 @@ export function listArgs(rest) {
     }
     return { agent, limit };
 }
-/** `--name <x>` or `--name=<x>` anywhere before the tool's own arguments. */
 /** The user's own `--settings <json|file>` for Claude, removed from the tool arguments: passed through as is it would
  *  replace chord's --settings wholesale and switch the hooks off, so chord folds it under its own instead. */
 export function takeSettings(rest) {
@@ -256,6 +252,7 @@ export function cleanArgs(rest) {
     }
     return { names, force };
 }
+/** `--name <x>` or `--name=<x>` anywhere before the tool's own arguments. */
 export function takeName(rest) {
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
@@ -392,6 +389,8 @@ async function main(argv) {
     const userSettings = cmd === 'claude' ? takeSettings(rest) : undefined;
     refuseHookKillers(cmd, rest);
     resolveCommand(cmd); // fail before creating a workspace when the tool is not installed
+    if (process.platform === 'darwin')
+        ensureSpawnHelper(); // or when node-pty could not start it
     let launch;
     try {
         launch = prepare(cmd, process.cwd(), name);

package/dist/db.js

@@ -10,7 +10,11 @@ export function gitEnv() {
             env[k] = v;
     return env;
 }
-const commonDir = (cwd) => path.resolve(cwd, execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8', env: gitEnv() }).trim());
+/** git run in `cwd`, trimmed stdout; throws with git's stderr on a non-zero exit. 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. */
+export const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024 }).trim();
+const commonDir = (cwd) => path.resolve(cwd, git(cwd, 'rev-parse', '--git-common-dir'));
 /** Root of the main checkout, even when run from inside a linked worktree. */
 export const mainRoot = (cwd) => path.dirname(commonDir(cwd));
 /** chord.db lives in the project's state directory under ~/.chord; CHORD_DB carries its path to hooks and servers. */
@@ -33,7 +37,7 @@ export function openDb(file) {
         catch (e) {
             if (attempt >= 50 || !/database is locked/.test(e.message))
                 throw e;
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+            sleepSync(100);
         }
     }
     return db;
@@ -41,6 +45,7 @@ export function openDb(file) {
 function setup(db) {
     db.exec(`
     pragma journal_mode = wal;
+    pragma synchronous = normal;
     pragma busy_timeout = 5000;
     pragma foreign_keys = on;
     create table if not exists agents (
@@ -48,7 +53,6 @@ function setup(db) {
       tool       text not null,
       pid        integer not null,
       cwd        text not null,
-      worktree   text not null,
       task       text,
       scope      text,
       status     text not null default 'busy',
@@ -65,7 +69,6 @@ function setup(db) {
       kind     text not null,
       symbols    text,
       created_at integer not null,
-      asked_at   integer,
       primary key (agent, file)
     );
     create table if not exists messages (
@@ -90,7 +93,7 @@ function setup(db) {
 }
 /** Bump when the schema changes and add a step below; `pragma user_version` records what a database has. A database
  *  from before versioning reads as 0 and gets every step, each of which checks what is actually there. */
-const SCHEMA_VERSION = 3;
+const SCHEMA_VERSION = 4;
 function migrate(db) {
     // under a write lock: several processes opening an old database together must not each add the same column
     db.exec('begin immediate');
@@ -104,6 +107,12 @@ function migrate(db) {
                 db.exec('alter table agents add column stop_requested_at integer'); // 2026-10-17; the events table is created above
             if (v < 3 && !agentCols().includes('session_id'))
                 db.exec('alter table agents add column session_id text'); // 2026-10-25
+            if (v < 4) { // 2026-10-28: two columns written and never read
+                if (agentCols().includes('worktree'))
+                    db.exec('alter table agents drop column worktree');
+                if (db.prepare('pragma table_info(claims)').all().some(c => c.name === 'asked_at'))
+                    db.exec('alter table claims drop column asked_at');
+            }
             db.exec(`pragma user_version = ${SCHEMA_VERSION}`);
         }
         db.exec('commit');
@@ -116,20 +125,25 @@ function migrate(db) {
 // agents
 export function addAgent(db, a) {
     const now = Date.now();
-    db.prepare(`insert into agents (name, tool, pid, cwd, worktree, status, started_at, updated_at, heartbeat_at)
-     values (?, ?, ?, ?, ?, 'busy', ?, ?, ?)
-     on conflict(name) do update set tool = excluded.tool, pid = excluded.pid, cwd = excluded.cwd, worktree = excluded.worktree,
+    db.prepare(`insert into agents (name, tool, pid, cwd, status, started_at, updated_at, heartbeat_at)
+     values (?, ?, ?, ?, 'busy', ?, ?, ?)
+     on conflict(name) do update set tool = excluded.tool, pid = excluded.pid, cwd = excluded.cwd,
        status = 'busy', task = null, scope = null, started_at = excluded.started_at, updated_at = excluded.updated_at, heartbeat_at = excluded.heartbeat_at,
-       stop_requested_at = null, session_id = case when tool = excluded.tool then session_id end`).run(a.name, a.tool, a.pid, a.cwd, a.worktree ?? a.cwd, now, now, a.heartbeat ? now : null);
+       stop_requested_at = null, session_id = case when tool = excluded.tool then session_id end`).run(a.name, a.tool, a.pid, a.cwd, now, now, a.heartbeat ? now : null);
     // a relaunch under the same name must not inherit messages meant for the previous session
     db.prepare('delete from messages where recipient = ? and read_at is null').run(a.name);
 }
-/** Forget an agent entirely: its claims and every message it sent or received. */
+/** Forget an agent: its claims, the messages to it and those it sent that have been read. What it said and nobody
+ *  has read yet stays: "f.ts is yours now" must still reach its recipient after the sender has been cleaned away. */
 export function removeAgent(db, name) {
     db.prepare('delete from claims where agent = ?').run(name);
-    db.prepare('delete from messages where sender = ? or recipient = ?').run(name, name);
+    db.prepare('delete from messages where recipient = ? or (sender = ? and read_at is not null)').run(name, name);
     db.prepare('delete from agents where name = ?').run(name);
 }
+/** The wrapper's take-over of the row prepare reserved: the tool's own pid replaces chord's. */
+export function setPid(db, name, pid) {
+    db.prepare('update agents set pid = ? where name = ?').run(pid, name);
+}
 /** The tool's conversation id, from the hook payloads; a relaunch keeps the old one until the new session reports its own. */
 export function setSession(db, name, id) {
     db.prepare('update agents set session_id = ? where name = ?').run(id, name);
@@ -138,9 +152,9 @@ export function setTask(db, name, task, scope) {
     db.prepare('update agents set task = ?, scope = ?, updated_at = ? where name = ?').run(task, scope, Date.now(), name);
 }
 /** Offline is sticky here: a hook that outlives its killed agent must not revive it. Only the wrapper does, through
- *  addAgent (relaunch) or heartbeat. */
+ *  addAgent (relaunch) or heartbeat. Returns whether a row changed. */
 export function setStatus(db, name, status) {
-    db.prepare(`update agents set status = ?, updated_at = ? where name = ? and status != 'offline'`).run(status, Date.now(), name);
+    return db.prepare(`update agents set status = ?, updated_at = ? where name = ? and status != 'offline'`).run(status, Date.now(), name).changes > 0;
 }
 export function getAgent(db, name) {
     return db.prepare('select * from agents where name = ?').get(name);
@@ -148,7 +162,7 @@ export function getAgent(db, name) {
 export function listAgents(db) {
     return db.prepare('select * from agents order by started_at').all();
 }
-function pidAlive(pid) {
+export function pidAlive(pid) {
     try {
         process.kill(pid, 0);
         return true;
@@ -161,12 +175,21 @@ function pidAlive(pid) {
         return code === 'EPERM';
     }
 }
+/** The log is moved aside to .log.1 once it passes this size, so twenty agents logging every hook for days do not
+ *  fill the disk; one old copy stays for looking into what just happened. */
+export const LOG_MAX_BYTES = 16 * 1024 * 1024;
 /** Append a line to chord.db.log next to the database, when CHORD_DB is known. Silent otherwise. */
 export function log(line) {
     if (!process.env.CHORD_DB)
         return;
+    const file = process.env.CHORD_DB + '.log';
     try {
-        fs.appendFileSync(process.env.CHORD_DB + '.log', `${new Date().toISOString()} [${process.env.CHORD_AGENT_ID ?? '-'}/${process.pid}] ${line}
+        try {
+            if (fs.statSync(file).size > LOG_MAX_BYTES)
+                fs.renameSync(file, file + '.1');
+        }
+        catch { /* no log yet, or another process just rotated it */ }
+        fs.appendFileSync(file, `${new Date().toISOString()} [${process.env.CHORD_AGENT_ID ?? '-'}/${process.pid}] ${line}
 `);
     }
     catch { /* best effort */ }
@@ -181,6 +204,12 @@ export function heartbeat(db, name) {
     // working all along; the next Stop, idle report or idle_prompt makes it idle again
     db.prepare(`update agents set heartbeat_at = ?, status = case when status = 'offline' then 'busy' else status end where name = ?`).run(Date.now(), name);
 }
+/** Every online wrapper's heartbeat refreshed at once. For the first wrapper to wake after the machine slept: its own
+ *  heartbeat alone would make the others look dead to a sweep in the second before they wake too. Agents without a
+ *  wrapper yet are left to their pid. */
+export function heartbeatAll(db) {
+    db.prepare(`update agents set heartbeat_at = ? where status != 'offline' and heartbeat_at is not null`).run(Date.now());
+}
 /** How long after launch an agent may go without a heartbeat before the watch in sweep calls it dead. */
 const STARTUP_GRACE_MS = 10 * 60_000;
 export const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -209,8 +238,10 @@ export function sweep(db, alive = pidAlive, now = Date.now(), watchMs = 0, sleep
         dead = online.filter(a => !alive(a.pid) || (!slept && stale(a))).map(a => a.name);
     }
     for (const name of dead) {
+        // several hooks sweep at once; the one whose update took the agent offline releases the claims, so each file gets one release event
+        if (!setStatus(db, name, 'offline'))
+            continue;
         log(`sweep: ${name} marked offline, claims released`);
-        setStatus(db, name, 'offline');
         releaseAll(db, name, 'swept');
     }
     return dead;
@@ -221,9 +252,6 @@ export function addClaim(db, c) {
      on conflict(agent, file) do update set intent = excluded.intent, kind = excluded.kind, symbols = excluded.symbols`).run(c.agent, c.file, c.intent, c.kind, c.symbols ?? null, Date.now());
     addEvent(db, c.agent, 'claim', c.file, `${c.kind}: ${c.intent}`);
 }
-export function setAskedAt(db, agent, file, at) {
-    db.prepare('update claims set asked_at = ? where agent = ? and file = ?').run(at, agent, file);
-}
 export function removeClaim(db, agent, file) {
     const gone = db.prepare('delete from claims where agent = ? and file = ?').run(agent, file).changes;
     if (gone)
@@ -278,7 +306,7 @@ export function send(db, sender, recipients, body, kind = 'message') {
         ins.run(sender, r, kind, body, now);
 }
 /** Roughly what a hook may attach without the tool truncating it (Codex caps additionalContext near 2500 tokens). */
-export const DELIVERY_BUDGET_CHARS = 6000;
+const DELIVERY_BUDGET_CHARS = 6000;
 /** Unread messages for `recipient`, oldest first, marked read as they are returned. Stops after `budget`
  *  characters (always at least one message) so a flood is delivered in several rounds instead of truncated. */
 export function takeUnread(db, recipient, budget = DELIVERY_BUDGET_CHARS) {
@@ -309,10 +337,6 @@ export function takeUnread(db, recipient, budget = DELIVERY_BUDGET_CHARS) {
 export function hasUnread(db, recipient) {
     return !!db.prepare(`select 1 from messages where recipient = ? and read_at is null and kind = 'message' limit 1`).get(recipient);
 }
-/** Has `sender` sent `recipient` a real message (not a notice) at or after `since`? */
-export function repliedSince(db, sender, recipient, since) {
-    return firstMessageAt(db, sender, recipient, since) !== null;
-}
 /** When `sender` first messaged `recipient` at or after `since`; null if never. Notices do not count. */
 export function firstMessageAt(db, sender, recipient, since) {
     const row = db.prepare("select min(created_at) t from messages where sender = ? and recipient = ? and kind = 'message' and created_at >= ?").get(sender, recipient, since);

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