chord-cli 0.1.3 → 0.2.1

package/dist/cli.js

@@ -1,11 +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
-import { execFileSync } from 'node:child_process';
+// The chord command line; see USAGE.
 import fs from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
@@ -14,45 +8,94 @@ 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 { 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 {
-        return execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    }
-    catch {
-        return undefined;
-    }
-};
+import { ensureSpawnHelper, resolveCommand, run } from "./pty.js";
+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 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));
     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)}`;
+}
+// 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;
 }
-/** 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);
+/** `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 +107,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 stop <agent>: the wrapper quits the tool once the agent is idle and nothing is typed. */
-export function stop(d, name) {
+/** 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. `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;
@@ -110,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) {
@@ -164,6 +238,21 @@ 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 };
+}
+/** `--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];
@@ -220,9 +309,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 +349,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 +361,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,24 +377,20 @@ 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);
     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);
@@ -297,19 +401,9 @@ 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)
@@ -317,8 +411,11 @@ async function main(argv) {
     }
     const spawned = cmd === 'codex' ? await codexFirstStart() : () => { };
     const exit = run(cmd, launch, rest);
-    spawned();
-    return exit;
+    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

@@ -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,14 +53,14 @@ 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',
       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),
@@ -64,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 (
@@ -89,42 +93,68 @@ 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 = 4;
 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
+            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');
+    }
+    catch (e) {
+        db.exec('rollback');
+        throw e;
+    }
 }
 // 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`).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);
+}
 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);
@@ -132,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;
@@ -145,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 */ }
@@ -165,21 +204,44 @@ 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);
 /** 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) {
+        // 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;
@@ -190,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)
@@ -216,11 +275,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. */
@@ -244,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) {
@@ -275,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);