chord-cli 0.1.2 → 0.2.0

package/dist/cli.js

@@ -1,10 +1,5 @@
 #!/usr/bin/env node
-// chord <claude|codex> [--name <agent>] [tool args...]   launch an agent in its own workspace
-// chord ls [--all]                                        agents and file claims, this project or all
-// chord messages [agent] [-n N]                           message history
-// chord events [agent] [-n N]                             claim, release, merge and conflict history
-// chord stop <agent>                                      quit an agent once it is idle
-// chord clean [--force] [agent...]                        remove offline agents' workspaces, worktrees and branches
+// The chord command line; see USAGE.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -15,8 +10,23 @@ 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";
-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';
+import { codexFirstStart, disabledCodexHooks } from "./trust.js";
+const USAGE = [
+    'usage: chord <command> [arguments]',
+    '',
+    '  chord claude [--name <agent>] ...   start a Claude Code agent here',
+    '  chord codex [--name <agent>] ...    start a Codex agent here',
+    "  chord resume <agent> ...            reopen an agent's conversation",
+    '  chord ls [--all]                    agents and claims (--all: every project)',
+    '  chord messages [agent] [-n N]       message history, latest N',
+    '  chord events [agent] [-n N]         claims, releases, merges, conflicts',
+    '  chord stop <agent>                  quit an agent once it is idle',
+    "  chord clean [--force] [agent...]    remove offline agents' worktrees",
+    '  chord --version',
+    '',
+    '  ... 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();
@@ -30,29 +40,65 @@ export function ago(ms) {
     const s = Math.max(0, Math.round(ms / 1000));
     return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86400)}d`;
 }
-/** Local time of day, with the date in front when it is not today. */
+/** Local time of day; another day reads "Oct 17 23:39" (a numeric date differs between the UK and the US), another
+ *  year adds the year. */
 export function when(t, now = Date.now()) {
-    const d = new Date(t), pad = (n) => String(n).padStart(2, '0');
+    const d = new Date(t), n = new Date(now), pad = (x) => String(x).padStart(2, '0');
     const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
-    return d.toDateString() === new Date(now).toDateString() ? time : `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}`;
+    if (d.toDateString() === n.toDateString())
+        return time;
+    return `${d.toDateString().slice(4, 10)}${d.getFullYear() === n.getFullYear() ? '' : ` ${d.getFullYear()}`} ${time.slice(0, 5)}`;
 }
-/** Agents (with unread messages, time since the last sign of life, commits on their branch not yet on main) and
- *  claims. `repo` is the main checkout; without it the branch column shows "?". */
-export function ls(d, repo, now = Date.now()) {
-    db.sweep(d);
+// East Asian wide and fullwidth ranges, plus emoji: two terminal cells each
+const WIDE = /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6\u{1F300}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u;
+/** Terminal cells `s` takes. */
+export function width(s) {
+    let n = 0;
+    for (const ch of s)
+        n += WIDE.test(ch) ? 2 : 1;
+    return n;
+}
+/** `s` cut to `max` cells with an ASCII "..." (the ellipsis character is ambiguous-width). */
+export function fit(s, max) {
+    if (width(s) <= max)
+        return s;
+    let out = '', n = 0;
+    for (const ch of s) {
+        const w = WIDE.test(ch) ? 2 : 1;
+        if (n + w > max - 3)
+            break;
+        out += ch;
+        n += w;
+    }
+    return out + '...';
+}
+/** Agents (status, unread messages, commits on their branch not yet on main, task), each followed by its claims. `repo`
+ *  is the main checkout; without it the branch column shows "?". `cols` is the terminal width: lines are cut to fit. */
+export function ls(d, repo, now = Date.now(), cols = Infinity) {
+    db.sweep(d, undefined, undefined, 2500); // a short watch, so a killed wrapper whose pid was reused is not shown online for ever
     const agents = db.listAgents(d);
-    const claims = db.allClaims(d);
     const main = repo ? gitOut(repo, 'rev-parse', '--abbrev-ref', 'HEAD') : undefined;
     const ahead = (name) => { if (!repo || !main)
         return '?'; const n = gitOut(repo, 'rev-list', '--count', `${main}..chord/${name}`); return n === undefined ? '-' : `+${n}`; };
-    const unread = (name) => d.prepare('select count(*) c from messages where recipient = ? and read_at is null').get(name).c;
-    const row = (a) => [a.name.padEnd(28), a.tool.padEnd(7), a.status.padEnd(8), String(unread(a.name)).padEnd(6), ago(now - (a.heartbeat_at ?? a.updated_at)).padEnd(7), ahead(a.name).padEnd(6), `${a.task ?? '-'}${a.scope ? ` [${a.scope}]` : ''}`].join(' ');
-    const header = ['agent'.padEnd(28), 'tool'.padEnd(7), 'status'.padEnd(8), 'unread', 'active'.padEnd(7), 'branch', 'task'].join(' ');
-    const out = agents.length ? [header, ...agents.map(row)] : ['no agents'];
-    out.push('', ...(claims.length ? claims.map(c => `${c.file.padEnd(40)} ${c.agent.padEnd(28)} ${c.kind.padEnd(7)} ${c.intent}`) : ['no claims']));
-    return out.join('\n') + '\n';
+    // messages only: a merge notice never wakes an agent, so it is not waiting on anyone
+    const unread = (name) => d.prepare("select count(*) c from messages where recipient = ? and read_at is null and kind = 'message'").get(name).c;
+    const label = (a) => (a.name.startsWith(`${a.tool}-`) ? a.name : `${a.name} (${a.tool})`);
+    const nameW = Math.max(5, ...agents.map(a => label(a).length));
+    // a live agent's heartbeat is always seconds old, so the age only means something once it is offline
+    const state = (a) => (a.status === 'offline' ? `off ${ago(now - (a.heartbeat_at ?? a.updated_at))}` : a.status);
+    const row = (a) => {
+        const head = [label(a).padEnd(nameW), state(a).padEnd(8), String(unread(a.name)).padEnd(6), ahead(a.name).padEnd(6), ''].join(' ');
+        return head + fit(`${a.task ?? '-'}${a.scope ? ` [${a.scope}]` : ''}`, cols - head.length);
+    };
+    const header = ['agent'.padEnd(nameW), 'status'.padEnd(8), 'unread', 'branch', 'task'].join(' ');
+    // each agent's claims under its row; a file held by several agents says so on each of their lines
+    const also = (c) => { const o = db.claimsFor(d, c.file).filter(x => x.agent !== c.agent).map(x => x.agent); return o.length ? ` (also ${o.join(', ')})` : ''; };
+    const claimLines = (a) => db.claimsBy(d, a.name).map(c => fit(`    ${c.kind.padEnd(6)} ${c.file}  ${c.intent}${also(c)}`, cols));
+    if (!agents.length)
+        return 'no agents\n';
+    return [header, ...agents.flatMap(a => [row(a), ...claimLines(a)])].join('\n') + '\n';
 }
-export function lsAll() {
+export function lsAll(cols = Infinity) {
     const projects = knownProjects();
     if (!projects.length)
         return 'no chord projects on this machine yet\n';
@@ -64,34 +110,66 @@ export function lsAll() {
     } };
     return projects.map(p => {
         try {
-            return `== ${p.dir ?? p.stateDir}\n${ls(db.openDb(p.dbFile), repoOf(p.dir ?? undefined))}`;
+            return `== ${p.dir ?? p.stateDir}\n${ls(db.openDb(p.dbFile), repoOf(p.dir ?? undefined), Date.now(), cols)}`;
         }
         catch (e) {
             return `== ${p.dir ?? p.stateDir}\n(unreadable: ${e.message})\n`;
         }
     }).join('\n');
 }
-/** chord messages [agent] [-n N]: the latest messages, oldest first, one line each. */
+/** chord messages [agent] [-n N]: the latest sends, oldest first, one line each. */
 export function messages(d, agent, limit = 50, now = Date.now()) {
     const ms = db.listMessages(d, agent, limit);
     if (!ms.length)
         return agent ? `no messages to or from ${agent}\n` : 'no messages\n';
     const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
-    return ms.map(m => `${when(m.created_at, now)} ${m.sender} -> ${m.recipient}${m.kind !== 'message' ? ` [${m.kind}]` : ''}${m.read_at ? '' : ' (unread)'}: ${oneLine(m.body)}`).join('\n') + '\n';
+    const body = (m) => (m.kind === 'notice' && m.body.endsWith('\n' + db.NOTICE_TAIL) ? m.body.slice(0, -db.NOTICE_TAIL.length - 1) : m.body);
+    const to = (m) => (m.n > 3 ? `${m.n} agents` : m.recipient);
+    const flag = (m) => (m.unread === 0 ? '' : m.unread === m.n ? ' (unread)' : ` (${m.unread}/${m.n} unread)`);
+    return ms.map(m => `${when(m.created_at, now)} ${m.sender} -> ${to(m)}${m.kind !== 'message' ? ` [${m.kind}]` : ''}${flag(m)}: ${oneLine(body(m))}`).join('\n') + '\n';
 }
 /** chord events [agent] [-n N]: claims, releases, merges and conflicts, oldest first. */
 export function events(d, agent, limit = 50, now = Date.now()) {
     const es = db.listEvents(d, agent, limit);
     if (!es.length)
         return agent ? `no events for ${agent}\n` : 'no events\n';
-    return es.map(e => `${when(e.at, now)} ${e.agent.padEnd(28)} ${e.kind.padEnd(8)} ${[e.file, e.detail].filter(Boolean).join(' ')}`).join('\n') + '\n';
+    const w = Math.max(...es.map(e => e.agent.length));
+    return es.map(e => `${when(e.at, now)} ${e.agent.padEnd(w)} ${e.kind.padEnd(8)} ${[e.file, e.detail].filter(Boolean).join(' ')}`).join('\n') + '\n';
+}
+/** What chord says when the tool has exited: how to carry on, or why resume cannot yet. */
+export function quitHint(d, name) {
+    const a = db.getAgent(d, name);
+    return a?.session_id
+        ? `chord: ${name} quit; \`chord resume ${name}\` continues it\n`
+        : `chord: ${name} quit before its conversation was recorded; start it again with chord ${a?.tool ?? 'claude'} --name ${name}\n`;
+}
+/** chord clean's report: what went, what stayed and why, and the exact --force that would discard the held work. */
+export function cleanReport(r) {
+    const lines = [...r.removed.map(n => `removed ${n}`), ...r.kept.map(k => `kept ${k.name}: ${k.why}`)];
+    // named, so the hint never reads as a bare "chord clean --force", which would discard every offline agent's work
+    const held = r.kept.filter(k => /^(unmerged|uncommitted)/.test(k.why)).map(k => k.name);
+    if (held.length)
+        lines.push(`to discard their work: chord clean --force ${held.join(' ')}`);
+    return (lines.length ? lines : ['nothing to clean']).join('\n') + '\n';
 }
-/** chord stop <agent>: the wrapper quits the tool once the agent is idle and nothing is typed. */
-export function stop(d, name) {
+/** chord stop <agent>: the wrapper quits the tool once the agent is idle and nothing is typed. `watchMs`: see db.sweep;
+ *  a wrapper that died with its pid reused must be found out here, or the quit is promised and never comes. */
+export function stop(d, name, watchMs = 2500) {
+    db.sweep(d, undefined, undefined, watchMs);
     if (db.requestStop(d, name))
         return `stop requested: ${name} will quit when its current turn ends and its input box is empty\n`;
     throw new Error(db.getAgent(d, name) ? `${name} is already offline` : `no such agent: ${name}`);
 }
+/** chord resume <agent>: the launch of that agent again under its own tool, reopening the conversation its hooks
+ *  recorded. Every agent runs in the project folder, so the tools' "latest conversation here" could be anyone's. */
+export function resumeArgv(d, name, more) {
+    const a = db.getAgent(d, name);
+    if (!a)
+        throw new Error(`no such agent: ${name}`);
+    if (!a.session_id)
+        throw new Error(`no recorded conversation for ${name}; start it again with chord ${a.tool} --name ${name}`);
+    return [a.tool, '--name', a.name, ...(a.tool === 'codex' ? ['resume', a.session_id] : ['--resume', a.session_id]), ...more];
+}
 /** [agent] and -n N for the history commands. */
 export function listArgs(rest) {
     let agent, limit = 50;
@@ -164,6 +242,20 @@ export function refuseHookKillers(tool, rest) {
         }
     }
 }
+/** `[--force|-f] [agent...]` for chord clean. */
+export function cleanArgs(rest) {
+    const names = [];
+    let force = false;
+    for (const a of rest) {
+        if (a === '--force' || a === '-f')
+            force = true;
+        else if (a.startsWith('-'))
+            throw new Error(`unknown option ${a}`);
+        else
+            names.push(a);
+    }
+    return { names, force };
+}
 export function takeName(rest) {
     for (let i = 0; i < rest.length; i++) {
         const a = rest[i];
@@ -220,9 +312,30 @@ async function offerRestructure(e) {
 }
 async function main(argv) {
     const [cmd, ...rest] = argv;
+    if (cmd === undefined || cmd === 'help' || cmd === '-h' || cmd === '--help') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (cmd === '--version' || cmd === '-V') {
+        process.stdout.write(JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version + '\n');
+        return 0;
+    }
+    // argument shapes are checked before the project is looked up, so a typo gets one line, not a project error
+    if (cmd === 'stop' && rest.length !== 1) {
+        process.stderr.write('usage: chord stop <agent>\n');
+        return 2;
+    }
+    if (cmd === 'resume' && (!rest[0] || rest[0].startsWith('-'))) {
+        process.stderr.write('usage: chord resume <agent> [tool args...]\n');
+        return 2;
+    }
     if (cmd === 'ls') {
+        const bad = rest.find(a => a !== '--all');
+        if (bad)
+            throw new Error(`unknown argument ${bad}; usage: chord ls [--all]`);
+        const cols = process.stdout.isTTY ? process.stdout.columns ?? Infinity : Infinity; // piped output is never cut
         if (rest.includes('--all')) {
-            process.stdout.write(lsAll());
+            process.stdout.write(lsAll(cols));
             return 0;
         }
         let project;
@@ -239,10 +352,10 @@ async function main(argv) {
             process.stdout.write(`no agents have run in ${project.dir} yet\n`);
             return 0;
         }
-        process.stdout.write(ls(db.openDb(file), project.repo));
+        process.stdout.write(ls(db.openDb(file), project.repo, Date.now(), cols));
         return 0;
     }
-    if (cmd === 'messages' || cmd === 'events' || cmd === 'stop') {
+    if (cmd === 'messages' || cmd === 'events' || cmd === 'stop' || cmd === 'resume') {
         const project = resolveProject(process.cwd());
         const file = db.dbPath(project.stateDir);
         if (!fs.existsSync(file)) {
@@ -251,13 +364,11 @@ async function main(argv) {
         }
         const d = db.openDb(file);
         if (cmd === 'stop') {
-            if (rest.length !== 1) {
-                process.stderr.write(USAGE);
-                return 2;
-            }
             process.stdout.write(stop(d, rest[0]));
             return 0;
         }
+        if (cmd === 'resume')
+            return main(resumeArgv(d, rest[0], rest.slice(1)));
         const { agent, limit } = listArgs(rest);
         process.stdout.write(cmd === 'messages' ? messages(d, agent, limit) : events(d, agent, limit));
         return 0;
@@ -269,18 +380,12 @@ async function main(argv) {
             process.stdout.write(`no agents have run in ${project.dir} yet\n`);
             return 0;
         }
-        const force = rest.includes('--force');
-        const r = clean(project, db.openDb(file), rest.filter(a => a !== '--force'), force);
-        for (const n of r.removed)
-            process.stdout.write(`removed ${n}\n`);
-        for (const k of r.kept)
-            process.stdout.write(`kept ${k.name}: ${k.why}\n`);
-        if (!r.removed.length && !r.kept.length)
-            process.stdout.write('nothing to clean\n');
+        const { names, force } = cleanArgs(rest);
+        process.stdout.write(cleanReport(clean(project, db.openDb(file), names, force)));
         return 0;
     }
     if (cmd !== 'claude' && cmd !== 'codex') {
-        process.stderr.write(USAGE);
+        process.stderr.write(`chord: unknown command "${cmd}"\n${USAGE}`);
         return 2;
     }
     const name = takeName(rest);
@@ -297,25 +402,21 @@ async function main(argv) {
         await offerRestructure(e);
         launch = prepare(cmd, process.cwd(), name);
     }
-    process.stderr.write(`chord: agent ${launch.name} in ${launch.cwd}\n`);
+    process.stderr.write(`chord: agent ${launch.name}; worktree ${launch.worktree}\n`);
     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(path.dirname(launch.cwd));
-        }
-        catch (e) {
-            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') {
         const off = disabledCodexHooks();
         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(); // right after the spawn: it releases the Codex first-start lock
+    const code = await exit;
+    // the tool's own parting line (Codex prints "codex resume <id>") would start it outside chord
+    process.stderr.write(quitHint(db.openDb(launch.dbFile), launch.name));
+    return code;
 }
 // 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

@@ -55,7 +55,8 @@ function setup(db) {
       started_at integer not null,
       updated_at integer not null,
       heartbeat_at integer,
-      stop_requested_at integer
+      stop_requested_at integer,
+      session_id text
     );
     create table if not exists claims (
       agent    text not null references agents(name),
@@ -89,17 +90,28 @@ 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 = 2;
+const SCHEMA_VERSION = 3;
 function migrate(db) {
-    const v = db.prepare('pragma user_version').get().user_version;
-    if (v >= SCHEMA_VERSION)
-        return;
-    const agentCols = () => db.prepare('pragma table_info(agents)').all().map(c => c.name);
-    if (v < 1 && !agentCols().includes('heartbeat_at'))
-        db.exec('alter table agents add column heartbeat_at integer'); // 2026-10-17
-    if (v < 2 && !agentCols().includes('stop_requested_at'))
-        db.exec('alter table agents add column stop_requested_at integer'); // 2026-10-17; the events table is created above
-    db.exec(`pragma user_version = ${SCHEMA_VERSION}`);
+    // under a write lock: several processes opening an old database together must not each add the same column
+    db.exec('begin immediate');
+    try {
+        const v = db.prepare('pragma user_version').get().user_version;
+        if (v < SCHEMA_VERSION) {
+            const agentCols = () => db.prepare('pragma table_info(agents)').all().map(c => c.name);
+            if (v < 1 && !agentCols().includes('heartbeat_at'))
+                db.exec('alter table agents add column heartbeat_at integer'); // 2026-10-17
+            if (v < 2 && !agentCols().includes('stop_requested_at'))
+                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
+            db.exec(`pragma user_version = ${SCHEMA_VERSION}`);
+        }
+        db.exec('commit');
+    }
+    catch (e) {
+        db.exec('rollback');
+        throw e;
+    }
 }
 // agents
 export function addAgent(db, a) {
@@ -108,7 +120,7 @@ export function addAgent(db, a) {
      values (?, ?, ?, ?, ?, 'busy', ?, ?, ?)
      on conflict(name) do update set tool = excluded.tool, pid = excluded.pid, cwd = excluded.cwd, worktree = excluded.worktree,
        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`).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, a.worktree ?? 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);
 }
@@ -118,6 +130,10 @@ export function removeAgent(db, name) {
     db.prepare('delete from messages where sender = ? or recipient = ?').run(name, name);
     db.prepare('delete from agents where name = ?').run(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);
+}
 export function setTask(db, name, task, scope) {
     db.prepare('update agents set task = ?, scope = ?, updated_at = ? where name = ?').run(task, scope, Date.now(), name);
 }
@@ -165,18 +181,33 @@ 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);
 }
+/** 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);
 /** Mark agents whose process is gone as offline and drop their claims. Returns the names swept. A missing
- *  process or a stale heartbeat both count: Windows reuses pids quickly, so the pid alone can lie. */
-export function sweep(db, alive = pidAlive, now = Date.now()) {
+ *  process or a stale heartbeat both count: Windows reuses pids quickly, so the pid alone can lie.
+ *  `watchMs`: when every heartbeat is stale, wait that long and see whose heartbeat moves (a live wrapper writes every
+ *  second); the rest are dead. Zero, the default for hooks and tools, judges by pid alone in that case. */
+export function sweep(db, alive = pidAlive, now = Date.now(), watchMs = 0, sleep = sleepSync) {
     const online = listAgents(db).filter(a => a.status !== 'offline');
     // Every heartbeat stale at once means the machine was asleep, not that everyone died: judge by pid alone then.
-    // ponytail: a lone dead agent whose pid was reused is therefore missed until a second agent comes online.
+    // ponytail: a lone dead agent whose pid was reused is therefore missed by the hooks until a second agent comes online.
     const beating = online.filter(a => a.heartbeat_at !== null);
     const stale = (a) => a.heartbeat_at !== null && now - a.heartbeat_at > HEARTBEAT_STALE_MS;
     const slept = beating.length > 0 && beating.every(stale);
-    if (slept)
-        log('sweep: every heartbeat is stale, the machine was probably asleep; judging by pid only');
-    const dead = online.filter(a => !alive(a.pid) || (!slept && stale(a))).map(a => a.name);
+    let dead;
+    if (slept && watchMs > 0) {
+        sleep(watchMs);
+        const moved = new Set(listAgents(db).filter(a => beating.some(b => b.name === a.name && b.heartbeat_at !== a.heartbeat_at)).map(a => a.name));
+        // no heartbeat yet while the setup command or Codex's first-start wait runs: a live pid that started lately is starting
+        const starting = (a) => now - a.started_at < STARTUP_GRACE_MS;
+        dead = online.filter(a => !alive(a.pid) || (a.heartbeat_at !== null && !moved.has(a.name) && !starting(a))).map(a => a.name);
+    }
+    else {
+        if (slept)
+            log('sweep: every heartbeat is stale, the machine was probably asleep; judging by pid only');
+        dead = online.filter(a => !alive(a.pid) || (!slept && stale(a))).map(a => a.name);
+    }
     for (const name of dead) {
         log(`sweep: ${name} marked offline, claims released`);
         setStatus(db, name, 'offline');
@@ -216,11 +247,14 @@ export function listEvents(db, agent, limit = 50) {
         : db.prepare('select * from events order by id desc limit ?').all(limit);
     return rows.reverse();
 }
-/** The latest `limit` messages (oldest first), all or those sent or received by one agent. */
+/** The closing sentence of a merge notice: for the agents, not for `chord messages`. */
+export const NOTICE_TAIL = 'No action is needed: finish() rebases your branch for you when you call it. This is a notification; do not reply.';
+/** The latest `limit` sends (oldest first), all or those sent or received by one agent. A message to several agents
+ *  is one row per recipient in the table and one send here. */
 export function listMessages(db, agent, limit = 50) {
-    const rows = agent
-        ? db.prepare('select * from messages where sender = ? or recipient = ? order by id desc limit ?').all(agent, agent, limit)
-        : db.prepare('select * from messages order by id desc limit ?').all(limit);
+    const sql = (where) => `select min(id) id, sender, group_concat(recipient, ', ') recipient, kind, body, created_at, max(read_at) read_at,
+    count(*) n, count(*) - count(read_at) unread from messages ${where} group by sender, kind, body, created_at order by max(id) desc limit ?`;
+    const rows = agent ? db.prepare(sql('where sender = ? or recipient = ?')).all(agent, agent, limit) : db.prepare(sql('')).all(limit);
     return rows.reverse();
 }
 /** `chord stop`: ask the wrapper to quit the tool once the agent is idle. Returns false for an unknown or offline agent. */

package/dist/hooks.js

@@ -35,7 +35,18 @@ export function formatMessages(ms) {
 const MAX_CLAIM_LINES = 60;
 const MAX_WARNED_FILES = 20;
 const MAX_INSTRUCTION_CHARS = 8000;
-/** The repository's own agent instructions. The agent's cwd is the workspace, so the tools do not load them themselves. */
+/** The agent's worktree as a path from its cwd, the project folder: chord/agents/<name>/<repoName>. */
+const repoDirOf = (ctx) => path.relative(ctx.project ?? ctx.cwd, ctx.worktree).split(path.sep).join('/') || '.';
+/** The same file in the agent's own worktree, for a path that hit the main checkout or another agent's worktree:
+ *  both are named after the repository, so what follows that directory is the file. */
+function ownCopy(ctx, abs, tool) {
+    const parts = path.relative(ctx.project ?? ctx.cwd, abs).split(path.sep), repoName = path.basename(ctx.worktree);
+    // P/<repoName>/... is the main checkout; P/chord/agents/<other>/<repoName>/... another agent's worktree
+    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 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) {
     const out = [];
     for (const name of ['AGENTS.md', 'CLAUDE.md']) {
@@ -52,18 +63,18 @@ export function briefing(ctx) {
     const me = db.getAgent(ctx.db, ctx.agent);
     const peers = db.listAgents(ctx.db).filter(a => a.name !== ctx.agent && a.status !== 'offline');
     const claims = db.allClaims(ctx.db);
-    const repoDir = path.relative(ctx.cwd, ctx.worktree).split(path.sep).join('/') || '.';
+    const repoDir = repoDirOf(ctx), repoName = path.basename(ctx.worktree);
     const lines = [
-        `You are agent "${ctx.agent}" (${me?.tool ?? 'unknown'}), one of several coding agents working on the same project. Your working directory is your own workspace; the repository is the directory "${repoDir}" inside it, a git worktree on your own branch. Run git commands inside "${repoDir}". Name files as paths from your working directory, e.g. "${repoDir}/src/x.ts" (claim() also accepts repository-relative paths like "src/x.ts"). Other agents have their own worktrees of the same repository; never edit files outside your workspace. Coordination goes through the "chord" MCP tools.`,
+        `You are agent "${ctx.agent}" (${me?.tool ?? 'unknown'}), one of several coding agents working on the same project. Your working directory is the project folder. Your own copy of the repository is "${repoDir}", a git worktree on your own branch: edit, build and run git only there. "${repoName}/" in the project folder is the main checkout and other agents have their copies under chord/agents/; never touch those. Name files as "${repoDir}/src/x.ts" or repository-relative "src/x.ts" (claim() accepts both). Coordination goes through the "chord" MCP tools.`,
         '',
         '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, unless the user has asked you to hold off merging. 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.',
         '',
@@ -80,21 +91,27 @@ export function briefing(ctx) {
 /** Context for the model. Plain stdout also works for Claude Code and `codex exec`, but the Codex TUI
  *  only takes the JSON form, so both events use it. */
 const context = (hookEventName, additionalContext) => ({ hookSpecificOutput: { hookEventName, additionalContext } });
+/** Both tools put their conversation id in the payload as session_id; `chord resume` reopens that conversation. Taken on
+ *  every prompt too, because Codex /new and a /resume start a new conversation without a SessionStart hook. */
+const recordSession = (ctx, payload) => { if (typeof payload.session_id === 'string' && payload.session_id)
+    db.setSession(ctx.db, ctx.agent, payload.session_id); };
 export function handleHook(ctx, tool, event, payload) {
     db.sweep(ctx.db);
     switch (event) {
         case 'session-start':
+            recordSession(ctx, payload);
             // The agent now waits for its first prompt: idle, so messages that arrive before the user types still wake it.
             // Claude Code also fires this after compacting a long conversation, in the middle of a turn: not idle then.
             if (payload.source !== 'compact')
                 db.setStatus(ctx.db, ctx.agent, 'idle');
             return context('SessionStart', briefing(ctx));
         case 'user-prompt-submit': {
+            recordSession(ctx, payload);
             db.setStatus(ctx.db, ctx.agent, 'busy');
             const ms = db.takeUnread(ctx.db, ctx.agent);
             // One line of identity on every prompt: a conversation that started without the briefing (Codex /new fires no
             // session hooks; a resumed conversation may predate chord) still learns what it is and what the rules are.
-            const reminder = `[chord] You are agent "${ctx.agent}" in a chord project: claim a file with the chord claim tool before editing it, talk to the other agents with chord send, merge with chord finish.`;
+            const reminder = `[chord] You are agent "${ctx.agent}" in a chord project: claim a file with the chord claim tool before editing it, talk to the other agents with chord send, merge with chord finish. Your worktree is "${repoDirOf(ctx)}"; edit and run git only there.`;
             return context('UserPromptSubmit', ms.length
                 ? `${formatMessages(ms)}\n\n[chord] ${ms.length} message(s) above arrived from other agents. Act on them in this turn as well as on the user's request: reply with the chord send tool where a reply is asked for.\n${reminder}`
                 : reminder);
@@ -104,14 +121,16 @@ export function handleHook(ctx, tool, event, payload) {
             if (!files.length && isEditTool(tool, payload.tool_name)) {
                 return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: 'chord could not tell which file this call writes, so it is refused; use the editor tool with a plain file path' } };
             }
-            // Codex resolves a patch's relative paths against the call's workdir when it gives one; otherwise the workspace
-            const workdir = tool === 'codex' && typeof payload.tool_input?.workdir === 'string' ? path.resolve(ctx.cwd, payload.tool_input.workdir) : ctx.cwd;
+            // Codex resolves a patch's relative paths against the call's workdir when it gives one, else against its own cwd,
+            // the project folder (the workspace when no project is known, as in the tests)
+            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);
                 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)) {
-                        return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: `${f} is outside your workspace: edit files only inside your own worktree ${ctx.worktree}` } };
+                        return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: `${f} is outside your workspace (the main checkout or another agent's worktree); edit your own copy ${ownCopy(ctx, abs, tool)} instead` } };
                     }
                     continue;
                 }
@@ -228,6 +247,23 @@ export function shellWarnings(ctx, payload) {
     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.`);
     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.
+    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;
+        const inMain = workdir !== null && insideDir(ctx.project, workdir) && !insideDir(ctx.cwd, workdir);
+        const words = cmd.split(/\s+/);
+        const namesMain = words.some((w, i) => {
+            if (/chord[\\/]agents[\\/]/.test(w))
+                return false;
+            const stripped = w.replace(/^["'(]+/, '').replace(/^\.[\\/]/, '');
+            const head = stripped.split(/[\\/]/)[0].replace(/["';&|)]+$/, '');
+            return head === repoName && (/[\\/]/.test(stripped) || words[i - 1] === 'cd');
+        });
+        if (inMain || namesMain)
+            out.push(`[chord] That command ran in the main checkout (${repoName}/) or named a path there; your copy is ${repoDirOf(ctx)}. Build, test and run git only there.`);
+    }
     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)) {