chord-cli 0.1.1 → 0.1.3

package/README.md

@@ -22,7 +22,7 @@ One repository, as many agents as you care to start. Each agent works in its own
 - One repository, N agents, one worktree each: parallel work without stepping on each other
 - A file-level claims board: register before editing, talk to the holder first, and a hook turns away any write that was never claimed
 - Asynchronous messaging between agents: idle ones are woken, busy ones hear at their next tool call
-- `finish` in one step: rebase, fast-forward main, release the claims, tell the others; a conflict stops for a human instead of guessing
+- `finish` in one step: rebase, fast-forward main, release the claims, tell the others; on a conflict nothing changes and the agent is told to rebase, resolve it and finish again, asking you only if it cannot
 - Agents learn the rules from chord itself, at start-up and on every prompt; you give tasks, not instructions about chord
 - Agent-agnostic by design: adding a tool means one launch recipe, not a new coordinator
 - `chord ls` for the whole picture, `messages` and `events` to replay what happened, `stop` and `clean` to wind down
@@ -118,17 +118,19 @@ chord clean              # remove the workspaces and branches of agents that hav
 `<project>/chord/config.json`:
 
 ```json
-{ "setup": "npm ci" }
+{ "setup": "npm ci", "test": "npm test" }
 ```
 
 `setup` runs once in every new worktree before the agent starts, with the `CHORD_*` variables in its environment, so a fresh worktree arrives with its dependencies in place. A failed setup abandons the launch and removes the worktree.
 
+`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.
 
 ## 🔌 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** for each agent workspace is recorded in `~/.claude.json`, so Claude asks about a folder once rather than for every agent. 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.
+- **Trust**: chord records the project's agents folder as trusted in `~/.claude.json` once, so Claude does not ask about each agent's workspace. 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.
 - **The terminal title** reads `chord <agent> · <task>`, so each window says which agent it is.
@@ -136,7 +138,7 @@ A repository's own Claude configuration (`.claude/settings*.json`, `.mcp.json`)
 
 ## 🗺️ Scope
 
-- Runs on Windows 11 and Linux. Windows has had the whole end-to-end suite; Linux the unit tests and part of it so far.
+- Runs on Windows 11 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/cli.js

@@ -15,7 +15,7 @@ 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 { disabledCodexHooks, pretrustClaude } from "./trust.js";
+import { codexFirstStart, disabledCodexHooks, pretrustClaude } from "./trust.js";
 const USAGE = 'usage: chord <claude|codex> [--name <agent>] [tool args...]\n       chord ls [--all]\n       chord messages [agent] [-n N]\n       chord events [agent] [-n N]\n       chord stop <agent>\n       chord clean [--force] [agent...]\n';
 const gitOut = (cwd, ...args) => {
     try {
@@ -301,11 +301,13 @@ async function main(argv) {
     if (userSettings)
         launch.args = mergeUserSettings(launch.args, userSettings);
     if (cmd === 'claude') { // otherwise every new workspace asks "do you trust this folder?"; a failure here only brings that dialogue back
+        // Claude inherits trust from a parent folder, so the project's agents folder is trusted once. One entry per
+        // workspace was lost whenever two agents started together: each launch, and every running Claude, rewrites the file.
         try {
-            pretrustClaude(launch.cwd);
+            pretrustClaude(path.dirname(launch.cwd));
         }
         catch (e) {
-            process.stderr.write(`chord: could not record the workspace as trusted in ~/.claude.json (${e.message}); Claude may ask you to trust the folder\n`);
+            process.stderr.write(`chord: could not record the agents folder as trusted in ~/.claude.json (${e.message}); Claude may ask you to trust the folder\n`);
         }
     }
     if (cmd === 'codex') {
@@ -313,7 +315,10 @@ async function main(argv) {
         if (off.length)
             process.stderr.write(`chord: Codex has chord's ${off.join(', ')} hook(s) switched off in ~/.codex/config.toml, so the matching chord features will not work. Remove the "enabled = false" line(s) under the [hooks.state.'...<session-flags>...'] tables to switch them back on.\n`);
     }
-    return run(cmd, launch, rest);
+    const spawned = cmd === 'codex' ? await codexFirstStart() : () => { };
+    const exit = run(cmd, launch, rest);
+    spawned();
+    return exit;
 }
 // run only as the entry point (argv[1] may be a symlink such as an npm bin link)
 const isMain = (() => { try {

package/dist/db.js

@@ -23,6 +23,22 @@ export function openDb(file) {
     // the busy timeout must be in force before the first statement: switching to WAL below does not wait otherwise,
     // and several agents starting at once on a new database all hit it together
     const db = new DatabaseSync(file, { timeout: 5000 });
+    // A brand-new database opened by several processes at once: SQLite answers the WAL switch and the schema with an
+    // immediate SQLITE_BUSY instead of waiting (seen on Linux, never on Windows), so the setup is retried briefly.
+    for (let attempt = 0;; attempt++) {
+        try {
+            setup(db);
+            break;
+        }
+        catch (e) {
+            if (attempt >= 50 || !/database is locked/.test(e.message))
+                throw e;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+        }
+    }
+    return db;
+}
+function setup(db) {
     db.exec(`
     pragma journal_mode = wal;
     pragma busy_timeout = 5000;
@@ -70,7 +86,6 @@ export function openDb(file) {
     );
   `);
     migrate(db);
-    return 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. */

package/dist/hooks.js

@@ -58,12 +58,12 @@ export function briefing(ctx) {
         '',
         'Rules:',
         '1. First thing: call register(task, scope) to say what you are doing.',
-        '2. Before creating or changing any file, call claim(file, intent, kind). Writes to unclaimed files are refused.',
+        '2. Before creating or changing any file, call claim(file, intent, kind), naming in symbols the functions or blocks you will touch. Writes to unclaimed files are refused.',
         '3. If claim() lists agents under must_talk_to, read their intent and send() each of them a message saying what you will change. You may write once each has replied, or after 10 minutes. Do other work meanwhile; never wait idle.',
         '4. Do not modify files through shell commands (sed, echo >, etc.). Use the editor tools so claims are checked.',
         '5. To talk to other agents use only chord send()/inbox(); do not use any other agent-messaging feature. Messages are asynchronous.',
         '6. To learn about the project, read the agent list and claims below and ask a specific agent with send(); do not ask the user.',
-        '7. When your change is complete and committed on your branch, call finish() to rebase onto main and fast-forward it. If finish() reports a conflict, stop and ask the user.',
+        '7. When your change is complete and committed on your branch, call finish() to rebase onto main and fast-forward it, unless the user has asked you to hold off merging. If finish() reports a conflict, rebase onto main yourself, resolve it so both changes survive (ask the agent whose work you meet with send() if its intent is unclear), run the tests, commit and call finish() again; ask the user only if you cannot resolve it.',
         '8. Never merge, rebase onto, push or otherwise update the main branch yourself, and never touch the main checkout: finish() is the only way changes reach main. This holds even if the project\'s own instructions say otherwise.',
         '9. Do not use git stash: every worktree of this repository shares one stash list, so a stash pop can hand you another agent\'s changes. Make a work-in-progress commit instead.',
         '',

package/dist/launch.js

@@ -345,7 +345,8 @@ export function prepare(tool, cwd, override) {
     }
 }
 /** <project>/chord/config.json. `setup` is a shell command run in every new worktree before the agent starts,
- *  for example "npm install". */
+ *  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;
@@ -364,10 +365,15 @@ export function readConfig(project) {
     }
     if (typeof cfg !== 'object' || cfg === null)
         throw new Error(`${file} must hold a JSON object`);
-    const setup = cfg.setup;
-    if (setup !== undefined && typeof setup !== 'string')
-        throw new Error(`${file}: "setup" must be a string (a shell command)`);
-    return setup ? { setup } : {};
+    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);

package/dist/pty.js

@@ -194,6 +194,17 @@ export function oscState(chunk) {
         last = x[1] === 'idle' ? 'idle' : 'busy';
     return last;
 }
+/** 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. */
+function tolerant(what, f) {
+    try {
+        f();
+    }
+    catch (e) {
+        db.log(`${what}: ${e.message}; skipped`);
+    }
+}
 export function run(tool, launch, extraArgs) {
     const { file, args } = resolveCommand(tool);
     const env = withNodeOnPath({ ...process.env, ...launch.env });
@@ -216,7 +227,7 @@ export function run(tool, launch, extraArgs) {
         if (tool === 'codex') { // the hooks set status too; the terminal report catches turns the hooks miss (Esc, untrusted hooks)
             const state = oscState(outTail + x);
             if (state)
-                db.setStatus(d, launch.name, state);
+                tolerant('terminal state report', () => db.setStatus(d, launch.name, state));
             outTail = x.slice(-64);
         }
     });
@@ -233,7 +244,7 @@ export function run(tool, launch, extraArgs) {
     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 = '';
-    const timer = setInterval(() => {
+    const timer = setInterval(() => tolerant('wake loop', () => {
         db.heartbeat(d, launch.name);
         const me = db.getAgent(d, launch.name);
         const wanted = titleFor(launch.name, me?.task);
@@ -287,7 +298,7 @@ export function run(tool, launch, extraArgs) {
             enteredAt = Date.now();
             enters = 1;
         }, 1500);
-    }, 1000);
+    }), 1000);
     return new Promise(resolve => {
         term.onExit(({ exitCode }) => {
             clearInterval(timer);
@@ -296,8 +307,8 @@ export function run(tool, launch, extraArgs) {
             if (process.stdin.isTTY)
                 process.stdin.setRawMode(false);
             process.stdin.pause();
-            db.setStatus(d, launch.name, 'offline');
-            db.releaseAll(d, launch.name, 'exit');
+            tolerant('exit', () => db.setStatus(d, launch.name, 'offline'));
+            tolerant('exit', () => db.releaseAll(d, launch.name, 'exit')); // missed here, the next sweep releases them
             resolve(exitCode);
         });
     });

package/dist/tools.js

@@ -1,7 +1,8 @@
-import { execFileSync } from 'node:child_process';
+import { execFileSync, 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";
 /** 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));
@@ -54,10 +55,23 @@ export function peers(ctx) {
         name: a.name, tool: a.tool, status: a.status, cwd: a.cwd, task: a.task, scope: a.scope,
     }));
 }
-/** Online agents who claimed `file` before `mine` did. */
+// 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)) ?? []);
+/** 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) {
+    if (a.kind !== 'modify' || b.kind !== 'modify')
+        return false;
+    const x = symbolSet(a.symbols), y = symbolSet(b.symbols);
+    return x.size > 0 && y.size > 0 && ![...x].some(w => y.has(w));
+}
+/** 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);
-    return db.claimsFor(ctx.db, mine.file).filter(c => c.agent !== ctx.agent && before(c) && db.getAgent(ctx.db, c.agent)?.status !== 'offline');
+    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)) };
 }
 /**
  * May `ctx.agent` write `file` now? It must hold a claim, and if others claimed the file first it must
@@ -70,7 +84,7 @@ export function canWrite(ctx, file, now = Date.now()) {
     const mine = db.claimsFor(ctx.db, rel).find(c => c.agent === ctx.agent);
     if (!mine)
         return { ok: false, reason: `${rel} is not claimed by you. Call claim(file, intent, kind) first.` };
-    const others = earlierOccupants(ctx, mine);
+    const others = earlierOccupants(ctx, mine).overlap;
     if (!others.length)
         return { ok: true };
     const myStart = db.getAgent(ctx.db, ctx.agent)?.started_at ?? mine.created_at;
@@ -230,7 +244,23 @@ function finishLocked(ctx) {
             throw new Error(`rebase onto ${main} failed (not a conflict); nothing was merged.\n${stderrOf(e)}`);
         db.log(`finish: rebase of ${branch} onto ${main} conflicted; aborted`);
         db.addEvent(ctx.db, ctx.agent, 'conflict', null, `rebase of ${branch} onto ${main} conflicted; aborted, nothing merged`);
-        throw new Error(`rebase onto ${main} failed; nothing was merged. Ask the user how to resolve it.\n${stderrOf(e)}`);
+        throw new Error(`rebase onto ${main} failed; nothing was merged. Run \`git rebase ${main}\` in your worktree, resolve the conflicts so both changes survive, run the tests, then call finish again; ask the user only if you cannot resolve them.\n${stderrOf(e)}`);
+    }
+    // The project's tests, on the branch as it now sits on top of main: a clean rebase can still break what another
+    // agent merged. ponytail: they run inside the finish lock, so other agents' finish waits for them (withLock gives
+    // up after 240 s); run them before taking the lock and re-check main if test suites get long.
+    const test = ctx.project ? readConfig({ dir: ctx.project }).test : undefined;
+    if (test) {
+        db.log(`finish: running the test command in ${wt}: ${test}`);
+        try {
+            execSync(test, { cwd: wt, stdio: 'pipe', timeout: 600_000, maxBuffer: 64 << 20 });
+        }
+        catch (e) {
+            const x = e;
+            const out = `${x.stdout ?? ''}${x.stderr ?? ''}`.trimEnd().split('\n').slice(-40).join('\n');
+            db.log(`finish: the test command failed${x.status != null ? ` with exit code ${x.status}` : ''}; nothing merged`);
+            throw new Error(`your branch is now rebased onto ${main}, but the project's test command failed there, so nothing was merged: ${test}\n${out}\nFix it (another agent's merged work may be what broke), commit, and call finish again.`);
+        }
     }
     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
@@ -309,7 +339,7 @@ export function tools(ctx) {
                     file: str('The file, as a path from your working directory (e.g. <repo>/src/x.ts) or relative to the repository root (src/x.ts)'),
                     intent: str('One sentence: what you will change and why'),
                     kind: { type: 'string', enum: ['add', 'modify', 'delete', 'rename'] },
-                    symbols: str('Optional: functions or blocks you will touch'),
+                    symbols: str('Optional: the functions or blocks you will touch, comma-separated. When you and an earlier holder of the file both name them and none are shared, you need not talk first.'),
                 },
                 required: ['file', 'intent', 'kind'],
             },
@@ -320,11 +350,13 @@ export function tools(ctx) {
                     throw new Error('kind must be add, modify, delete or rename');
                 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 others = 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)}`);
+                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,
-                    must_talk_to: others.map(o => ({ agent: o.agent, intent: o.intent, kind: o.kind, symbols: o.symbols })),
+                    must_talk_to: others.map(brief),
+                    ...(elsewhere.length ? { also_editing: elsewhere.map(brief) } : {}),
                     ...(others.length ? { next: 'Send each agent above a message describing your change. You may write once each has replied, or after 10 minutes.' } : {}),
                 };
             },
@@ -366,7 +398,7 @@ export function tools(ctx) {
         },
         {
             name: 'finish',
-            description: 'Your work is committed on your branch: rebase it onto main, fast-forward main, release all your claims and tell the other agents. On a rebase conflict nothing is changed; stop and ask the user.',
+            description: 'Your work is committed on your branch: rebase it onto main, fast-forward main, release all your claims and tell the other agents. On a rebase conflict nothing is changed; rebase onto main yourself, resolve it, then call finish again.',
             inputSchema: { type: 'object', properties: {} },
             handler: () => finish(ctx),
         },

package/dist/trust.js

@@ -88,3 +88,65 @@ export function disabledCodexHooks(file = codexConfigPath()) {
     }
     return off;
 }
+const hasCodexState = (home) => { try {
+    return fs.readdirSync(home).some(f => /^state_\d+\.sqlite$/.test(f));
+}
+catch {
+    return false;
+} };
+/** Codex creates and migrates its state database (~/.codex/state_N.sqlite) on its first start, and when two start at
+ *  once the second exits with "local database appears to be damaged". Until that database exists, launches take
+ *  turns: the first holds a lock while its Codex creates it, the others wait for the lock. Call the returned
+ *  function once Codex has been spawned; it lets go of the lock when the database is there, or after a minute. */
+export async function codexFirstStart(home = path.join(os.homedir(), '.codex')) {
+    if (hasCodexState(home))
+        return () => { };
+    const lock = path.join(home, '.chord-first-start');
+    const t0 = Date.now();
+    try {
+        fs.mkdirSync(home, { recursive: true });
+    }
+    catch {
+        return () => { };
+    }
+    for (;;) {
+        try {
+            fs.writeFileSync(lock, String(process.pid), { flag: 'wx' });
+            break;
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                return () => { };
+            try {
+                if (Date.now() - fs.statSync(lock).mtimeMs > 60_000) {
+                    fs.unlinkSync(lock);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - t0 > 90_000)
+                return () => { }; // a launch that never lets go must not hold this one up for good
+            await new Promise(r => setTimeout(r, 250));
+        }
+    }
+    const unlock = () => { try {
+        fs.unlinkSync(lock);
+    }
+    catch { /* gone */ } };
+    if (hasCodexState(home)) {
+        unlock();
+        return () => { };
+    } // the launch before this one created it
+    return () => {
+        const started = Date.now();
+        const poll = setInterval(() => {
+            if (!hasCodexState(home) && Date.now() - started < 60_000)
+                return;
+            clearInterval(poll);
+            setTimeout(unlock, 2000).unref(); // the file appears before its migrations have run
+        }, 250);
+        poll.unref();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chord-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Run several coding agents in one git project, each in its own worktree, with shared file claims and messaging",
   "license": "MIT",
   "keywords": [