chord-cli 0.1.3 → 0.2.0

package/README.md

@@ -6,6 +6,7 @@
   <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue"></a>
   <img alt="Node 24 or later" src="https://img.shields.io/badge/node-%E2%89%A5%2024-339933?logo=nodedotjs&logoColor=white">
   <img alt="Windows and Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-blue">
+  <a href="README.zh-CN.md"><img alt="中文说明" src="https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-2F7CF6"></a>
 </p>
 
 One repository, as many agents as you care to start. Each agent works in its own worktree; a shared board records who holds which file; an agent that wants a file another agent holds asks first and waits for the answer; when the work is committed, one call rebases the branch and fast-forwards main. Idle agents are woken the moment a message arrives, so the agents negotiate among themselves while you keep handing out work in plain language.
@@ -27,6 +28,19 @@ One repository, as many agents as you care to start. Each agent works in its own
 - 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
 
+## 📊 Benchmark
+
+On [CooperBench](https://github.com/cooperbench/CooperBench) two agents each take one feature in the same repository, and a pair passes when the merged result passes the tests of both features. The gpt-6-luna figures cover the pairs where both sides finished.
+
+| chord vs | gpt-6.1-sol | gpt-6-luna |
+|---|---|---|
+| solo (one agent, both features) | 76% vs 74% | 63% vs 51% |
+| coop + git (messages and a shared git remote) | 76% vs 73% | 63% vs 47% |
+| team (a lead hands out the work) | 76% vs 69% | **63% vs 34%** |
+| coop (messages only) | 76% vs 11% | 63% vs 11% |
+
+On the stronger model chord keeps pace with the best baselines. On the weaker one it is the only two-agent setup that does not fall below a single agent, and it beats the team setting by 20 points. chord's agents got only the feature text, while the coop + git and team prompts spell out how to split and merge the work.
+
 ## 🤖 Supported agents
 
 | agent | status |
@@ -100,13 +114,16 @@ chord stop api           # let it finish its turn, then quit
 chord clean              # remove the workspaces and branches of agents that have left
 ```
 
-`--name` fixes an agent's name, workspace and branch, so launching the same name later returns to the same worktree (add `--resume` or `-c` to pick up the conversation too). Run chord in a repository root and it offers to move the repository into a child directory first.
+`--name` fixes an agent's name, workspace and branch, so launching the same name later returns to the same worktree. `chord resume <agent>` does that and also reopens the agent's own conversation, for Claude and Codex alike. Run chord in a repository root and it offers to move the repository into a child directory first.
+
+Agents start in the project folder, the same directory you run plain `claude` or `codex` in, so that stays their project too: one `/resume` list, one CLAUDE.md, one trust answer. Each agent edits only its own worktree under `chord/agents/<name>/`; chord refuses edits (editor tools, apply_patch) to the main checkout and to other agents' worktrees, and tells the agent off after a shell command that ran there.
 
 ## 🧰 Commands
 
 | command | what it does |
 |---|---|
 | `chord <agent> [--name x] [tool args...]` | start an agent: `claude` or `codex` |
+| `chord resume <agent> [tool args...]` | start an agent that has left again, in its own worktree, reopening its own conversation |
 | `chord ls [--all]` | agents and claims of this project, or of every project |
 | `chord messages [agent] [-n N]` | message history |
 | `chord events [agent] [-n N]` | claim, release, merge and conflict history |
@@ -130,7 +147,7 @@ A repository's own Claude configuration (`.claude/settings*.json`, `.mcp.json`)
 ## 🔌 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**: 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.
+- **Trust**: agents run in the project folder, so Claude asks about it once, as it does for plain `claude`; chord writes nothing to `~/.claude.json`. Codex asks you to review chord's hooks once, and again whenever their definition changes; answer "trust all". chord says so at launch if a hook has been switched off.
 - **Branches and worktrees.** Each agent adds a `chord/<name>` branch and a worktree; `chord clean` removes them when the agent has left and keeps anything not yet on main.
 - **Permissions.** chord's own tools are pre-approved for Claude, so an agent working on its own is never parked at a prompt for them; your usual shell and edit approvals apply as before. Codex runs with full access. On Windows chord refuses a sandboxed launch, because that sandbox cannot run the hooks; on Linux the hooks run inside the sandbox, but Codex then asks you to approve each chord tool call.
 - **The terminal title** reads `chord <agent> · <task>`, so each window says which agent it is.

package/README.zh-CN.md

@@ -0,0 +1,169 @@
+# chord
+
+**把编码 agent 当成一个集群来跑。**
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-blue"></a>
+  <img alt="Node 24 or later" src="https://img.shields.io/badge/node-%E2%89%A5%2024-339933?logo=nodedotjs&logoColor=white">
+  <img alt="Windows and Linux" src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux-blue">
+  <a href="README.md"><img alt="English README" src="https://img.shields.io/badge/README-English-2F7CF6"></a>
+</p>
+
+一个仓库，想开几个 agent 就开几个。每个 agent 在自己的 worktree 里干活；一块共享的看板记着谁占着哪个文件；想改别人占着的文件，先问，等对方回话；活干完提交了，一个调用把分支 rebase 到 main 并快进。空闲的 agent 一有消息就被叫醒，所以 agent 之间自己协商，你只管用大白话继续派活。
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/demo-dark.svg">
+    <img alt="两个 agent 各在自己的终端里占用文件，通过消息商量一个共用文件，然后 finish 合进 main；chord ls 显示它们的状态" src="docs/demo-light.svg" width="100%">
+  </picture>
+</p>
+
+## ✨ 特点
+
+- 一个仓库、N 个 agent、每人一个 worktree：并行干活，互不踩脚
+- 文件级的占用看板：改之前先登记，先占的人先说话，没登记过的写入被 hook 挡回去
+- agent 之间的异步消息：空闲的被叫醒，忙着的在下一次工具调用时听到
+- `finish` 一步到位：rebase、快进 main、释放占用、通知其他人；遇到冲突什么都不动，让 agent 自己 rebase、解决、再 finish，解决不了才来问你
+- 规则由 chord 自己教给 agent，启动时讲一遍，每条 prompt 再提醒一次；你只派任务，不用解释 chord
+- 设计上不绑定某一家 agent：接一个新工具只是加一条启动配方，不用新写协调器
+- `chord ls` 看全局，`messages` 和 `events` 回放发生过什么，`stop` 和 `clean` 收尾
+
+## 📊 基准测试
+
+在 [CooperBench](https://github.com/cooperbench/CooperBench) 上，两个 agent 在同一个仓库里各做一个功能，合并后的结果通过两个功能的测试才算这一对通过。gpt-6-luna 的数字只算两边都做完的那些对。
+
+| chord 对比 | gpt-6.1-sol | gpt-6-luna |
+|---|---|---|
+| solo（一个 agent 做两个功能） | 76% vs 74% | 63% vs 51% |
+| coop + git（消息加一个共享的 git 远端） | 76% vs 73% | 63% vs 47% |
+| team（一个主管派活） | 76% vs 69% | **63% vs 34%** |
+| coop（只有消息） | 76% vs 11% | 63% vs 11% |
+
+在强模型上 chord 和最好的基线持平。在弱模型上它是唯一不掉到单 agent 以下的双 agent 方案，比 team 高 20 个点。chord 的 agent 只拿到功能描述，而 coop + git 和 team 的 prompt 里把怎么分工、怎么合并都写明了。
+
+## 🤖 支持的 agent
+
+| agent | 状态 |
+|---|---|
+| Claude Code | 支持 |
+| Codex CLI | 支持 |
+| OpenCode | 计划中 |
+| Gemini CLI | 计划中 |
+| Cursor CLI | 计划中 |
+| GitHub Copilot CLI | 计划中 |
+| Qwen Code | 计划中 |
+| DeepSeek Harness | 计划中 |
+
+接一个新 agent 需要它的工具提供三样东西：启动时注入 hook 和 MCP server 的办法、hook 事件的名字和载荷、一个空闲/忙碌信号。
+
+## 🧩 工作原理
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/architecture-dark.svg">
+    <img alt="你把任务交给一群 agent，每人一个 worktree；agent 共享一块占用和消息的看板，做完 finish 进 main" src="docs/architecture-light.svg" width="100%">
+  </picture>
+</p>
+
+1. **隔离。** 每个 agent 在自己的分支、自己的 worktree 里干活。主 checkout 只通过 `finish` 变化。
+2. **协调。** 一块共享看板存着占用、消息和事件。agent 用 chord 给的工具登记、占用、对话；hook 在每次写入前查占用，并在它干活时把新消息递过去。
+3. **合并。** `finish` 把分支 rebase 到 main 再快进。rebase 干净就合进去；其他任何情况都停在原地等你。
+
+## 📦 安装
+
+机器上有 Node 24 和 git：
+
+```
+npm install -g chord-cli
+```
+
+Linux 上加 `--allow-scripts=node-pty`，并装好 python3、make 和 g++：node-pty 不带 Linux 的二进制，安装时现场编译。
+
+或者从源码：
+
+```
+git clone https://github.com/Cedr1cSun/chord-cli && cd chord-cli
+npm install && npm link
+```
+
+## 🚀 快速开始
+
+一个项目是一个文件夹，仓库放在它的子目录里：
+
+```
+my-project/
+  my-repo/        主 checkout
+  chord/          chord 自己的文件，在仓库之外
+```
+
+在项目文件夹里，一个终端开一个 agent：
+
+```
+chord claude                                     # 开一个 agent
+chord codex --name api                           # 再开一个，起个名字
+chord claude "fix the flaky test in tests/auth"  # 工具名后面的参数原样交给工具
+```
+
+在这些终端里像平时一样派任务。另开一个终端：
+
+```
+chord ls                 # agent、各自在做什么、未读消息、分支状态、文件占用
+chord messages api       # 某个 agent 说过什么、收到过什么
+chord events             # 占用、释放、合并、冲突
+chord stop api           # 让它做完这一轮再退出
+chord clean              # 删掉已经离开的 agent 的工作区和分支
+```
+
+`--name` 固定 agent 的名字、工作区和分支，以后用同一个名字启动就回到同一个 worktree。`chord resume <agent>` 也是这样，还会接着打开这个 agent 自己的对话，Claude 和 Codex 都一样。在仓库根目录里跑 chord，它会先提议把仓库移进一个子目录。
+
+agent 在项目文件夹里启动，也就是你平时直接敲 `claude` 或 `codex` 的那个目录，所以那仍然是它们的项目：同一份 `/resume` 列表，同一个 CLAUDE.md，同一次信任确认。每个 agent 只改 `chord/agents/<名字>/` 下自己的 worktree；chord 拒绝对主 checkout 和其他 agent 的 worktree 的编辑（编辑器工具、apply_patch），shell 命令在那里跑过之后也会说一声。
+
+## 🧰 命令
+
+| 命令 | 作用 |
+|---|---|
+| `chord <agent> [--name x] [tool args...]` | 开一个 agent：`claude` 或 `codex` |
+| `chord resume <agent> [tool args...]` | 把离开的 agent 再开起来，回到它的 worktree，接着它自己的对话 |
+| `chord ls [--all]` | 本项目的 agent 和占用，或所有项目的 |
+| `chord messages [agent] [-n N]` | 消息记录 |
+| `chord events [agent] [-n N]` | 占用、释放、合并、冲突的记录 |
+| `chord stop <agent>` | 等 agent 这一轮结束、输入框为空时退出它 |
+| `chord clean [--force] [agent...]` | 删掉离线 agent 的工作区、worktree 和分支；还没到 main 上的工作留着，除非 `--force` |
+
+## ⚙️ 配置
+
+`<项目>/chord/config.json`：
+
+```json
+{ "setup": "npm ci", "test": "npm test" }
+```
+
+`setup` 在每个新建的 worktree 里、agent 启动前跑一次，环境里带着 `CHORD_*` 变量，这样新 worktree 一来就装好了依赖。setup 失败则放弃这次启动并删掉 worktree。
+
+`test` 设置了的话，每次 `finish` 把分支 rebase 到 main 之后、main 移动之前，在 agent 的 worktree 里跑一遍。失败就什么都不合，agent 拿到输出的末尾：rebase 干净也可能弄坏别人刚合进去的东西。它跑的时候其他 agent 的 `finish` 等着。
+
+仓库自带的 Claude 配置（`.claude/settings*.json`、`.mcp.json`）在你自己在 Claude Code 里信任过这个仓库之后才会到达 agent；你在那里批准过的 MCP server 才会启动。
+
+## 🔌 chord 怎么和你的工具相处
+
+- **叫醒 agent** 就是往它的终端里敲一句短话。chord 只在输入框为空、键盘安静了几秒、终端回显了这句话之后才这么做；对话框永远收不到那个回车。
+- **信任**：agent 在项目文件夹里跑，所以 Claude 像平时敲 `claude` 一样只问一次；chord 不往 `~/.claude.json` 里写任何东西。Codex 会让你审核一次 chord 的 hook，hook 定义变了会再问一次；选 "trust all"。有 hook 被关掉时 chord 会在启动时告诉你。
+- **分支和 worktree。** 每个 agent 添一个 `chord/<名字>` 分支和一个 worktree；`chord clean` 在 agent 离开后删掉它们，还没到 main 上的东西留着。
+- **权限。** chord 自己的工具对 Claude 预先放行，所以独自干活的 agent 不会卡在它们的确认框上；你平时的 shell 和编辑审批照旧。Codex 以完全访问运行。Windows 上 chord 拒绝带沙箱启动，因为那个沙箱起不来 hook；Linux 上 hook 在沙箱里运行，但 Codex 会让你逐个批准 chord 的工具调用。
+- **终端标题**是 `chord <agent> · <任务>`，每个窗口都说得出自己是谁。
+- **hook 把关的是编辑器工具。** 从 shell 改的文件在每条命令之后按名字报出来，并附上该做的占用。
+
+## 🗺️ 范围
+
+- 在 Windows 11 和 Linux 上运行。
+- 每个项目一个仓库。
+- 项目路径最长约 190 个字符。
+- 仓库里有 CRLF 文件和一条从未重新规范化过的 `* text` 属性时，每个 worktree 都会出现假改动；chord 会报出文件名和把仓库修好的命令。
+
+## 🧪 测试
+
+`npm test` 在临时文件夹里的真实 git 仓库上跑单元测试。协调本身用真实工具做过端到端验证，从两个 agent 商量一个文件到二十个 agent 合进同一个 main，还有 Python、Rust 和 JavaScript 的开源仓库。
+
+## 📄 许可
+
+[MIT](LICENSE)

package/dist/clean.js

@@ -9,12 +9,15 @@ const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8',
  *  main, or whose worktree has uncommitted work, is kept unless `force`; an online agent is always kept. Directories
  *  under chord/agents/ with no database row (a launch that died before the tool started) are treated the same way. */
 export function clean(project, d, names = [], force = false) {
-    db.sweep(d);
+    db.sweep(d, undefined, undefined, 2500); // as in ls: a dead wrapper with a reused pid must not count as online
     const main = git(project.repo, 'rev-parse', '--abbrev-ref', 'HEAD');
     const agents = db.listAgents(d).filter(a => (names.length ? names.includes(a.name) : a.status === 'offline'));
     const result = { removed: [], kept: [] };
     const kept = (name, why) => result.kept.push({ name, why });
+    const agentsDir = path.join(project.dir, 'chord', 'agents');
     const remove = (a, hasRow) => {
+        // by name, never by the stored paths: a row pointing elsewhere must not take that folder or worktree with it
+        const dir = path.join(agentsDir, a.name), wt = path.join(dir, project.repoName);
         try {
             if (a.status !== 'offline') {
                 kept(a.name, 'still online');
@@ -31,37 +34,37 @@ export function clean(project, d, names = [], force = false) {
                     merged = false;
                 }
                 if (!merged) {
-                    kept(a.name, `${branch} has commits that are not on ${main}; use --force to discard them`);
+                    kept(a.name, `unmerged commits on ${branch}`);
                     return;
                 }
             }
             // work that was never committed (an agent stopped half-way) is just as much work as an unmerged commit
-            if (!force && fs.existsSync(path.join(a.worktree, '.git'))) {
+            if (!force && fs.existsSync(path.join(wt, '.git'))) {
                 let dirty = '';
                 try {
-                    dirty = git(a.worktree, 'status', '--porcelain');
+                    dirty = git(wt, 'status', '--porcelain');
                 }
                 catch { /* a broken worktree holds nothing to keep */ }
                 if (dirty) {
-                    kept(a.name, `${a.worktree} has uncommitted changes; use --force to discard them`);
+                    kept(a.name, `uncommitted changes in ${path.relative(project.dir, wt).split(path.sep).join('/')}`);
                     return;
                 }
             }
             // The directory goes first. On Windows a directory some process is using (a shell left open in it) cannot be
             // removed; then the branch and the database row stay too, so the next clean sees the agent whole.
-            if (fs.existsSync(a.worktree)) {
+            if (fs.existsSync(wt)) {
                 try {
-                    git(project.repo, 'worktree', 'remove', '--force', a.worktree);
+                    git(project.repo, 'worktree', 'remove', '--force', wt);
                 }
                 catch { /* fall through to rm */ }
             }
             try {
-                fs.rmSync(a.cwd, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+                fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
             }
             catch { /* checked below */ }
             git(project.repo, 'worktree', 'prune');
-            if (fs.existsSync(a.cwd)) {
-                kept(a.name, `${a.cwd} could not be removed, probably because a process is using it; close it and run clean again`);
+            if (fs.existsSync(dir)) {
+                kept(a.name, `${dir} could not be removed, probably because a process is using it; close it and run clean again`);
                 return;
             }
             if (hasBranch)
@@ -80,7 +83,6 @@ export function clean(project, d, names = [], force = false) {
     for (const a of agents)
         remove(a, true);
     // directories with no row: a launch that died before the tool registered, or a database that was deleted
-    const agentsDir = path.join(project.dir, 'chord', 'agents');
     const known = new Set(db.listAgents(d).map(a => a.name.toLowerCase()));
     let orphans = [];
     try {
@@ -88,6 +90,6 @@ export function clean(project, d, names = [], force = false) {
     }
     catch { /* no agents directory yet */ }
     for (const n of orphans)
-        remove({ name: n, status: 'offline', cwd: path.join(agentsDir, n), worktree: path.join(agentsDir, n, project.repoName) }, false);
+        remove({ name: n, status: 'offline' }, false);
     return result;
 }

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 { 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';
+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,19 +402,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 +412,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

@@ -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,9 +63,9 @@ 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.',
@@ -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)) {

package/dist/launch.js

@@ -16,7 +16,6 @@ const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8',
 const here = (f) => fs.realpathSync.native(fileURLToPath(new URL(f + path.extname(fileURLToPath(import.meta.url)), import.meta.url))).split(path.sep).join('/');
 export const HOOKS_TS = here('./hooks');
 export const SERVE_TS = here('./serve');
-const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 /** `staleWaitMs`: how long to watch a stale heartbeat before calling its agent dead (tests shorten it). */
 export function pickName(d, tool, project, override, staleWaitMs = 2500) {
     if (override) {
@@ -36,7 +35,7 @@ export function pickName(d, tool, project, override, staleWaitMs = 2500) {
             // (a live one writes every second), and this launch itself proves the machine is awake.
             const stale = clash.heartbeat_at !== null && Date.now() - clash.heartbeat_at > db.HEARTBEAT_STALE_MS;
             if (stale)
-                sleepSync(staleWaitMs);
+                db.sleepSync(staleWaitMs);
             const again = stale ? db.getAgent(d, clash.name) : clash;
             if (!stale || again?.heartbeat_at !== clash.heartbeat_at)
                 throw new Error(`agent "${override}" is already online`);
@@ -211,8 +210,9 @@ export function claudeArgs(env, projectConfig = false) {
     // chord's own tools are pre-approved: in the default permission mode every claim, send and finish would otherwise
     // stop at a prompt, and an unattended agent would never get past the first one
     const ours = { hooks, permissions: { allow: ['mcp__chord'] } };
-    // The agent's cwd is its workspace, not the repository, so Claude Code would not pick up the repository's
-    // own CLAUDE.md, .claude/settings*.json or .mcp.json. --add-dir covers CLAUDE.md; the others are passed along.
+    // The agent's cwd is the project folder, not the repository, so Claude Code would not pick up the repository's
+    // skills, commands and agents under .claude/, nor its settings*.json or .mcp.json. --add-dir covers the first group
+    // (the briefing carries CLAUDE.md itself); the others are passed along.
     const wt = env.CHORD_WORKTREE;
     const addDir = wt ? ['--add-dir', wt] : [];
     const source = projectConfig === true ? { repo: wt ?? '' } : projectConfig || null;

package/dist/pty.js

@@ -142,6 +142,15 @@ export function typedEchoed(output, text) {
     const squash = (s) => stripAnsi(s).replace(/\s+/g, '');
     return squash(output).includes(squash(text).slice(0, 25));
 }
+/** The Esc key as the tool reads it: in win32-input-mode (ConPTY turns a bare ESC byte into nothing, waiting for a
+ *  sequence) a key-down and key-up record; elsewhere the CSI u form the tools ask for (`ESC [ > 5 u`), which a legacy
+ *  reader ignores harmlessly. Linux form not yet verified against the real tools. */
+export const ESC_INPUT = process.platform === 'win32' ? '\x1b[27;1;27;1;0;1_\x1b[27;1;27;0;0;1_' : '\x1b[27u';
+/** Did the tool answer the exit command with its "background work is running, exit and stop it or stay?" dialogue?
+ *  Claude Code asks this while a shell the agent started (a monitor it is waiting on, say) still runs. */
+export function exitDeclined(output) {
+    return /Backgroundworkisrunning|willstopwhenyouexit/i.test(stripAnsi(output).replace(/\s+/g, ''));
+}
 /** The terminal title is chord's: "chord <agent> · <task>", so a window or tab can be matched to a `chord ls` row.
  *  The tools set their own titles (Claude Code its session summary, Codex the folder name), so their title
  *  sequences (OSC 0, 1, 2) are removed from the forwarded output; everything else, including Codex's OSC 7501
@@ -169,9 +178,14 @@ export const titleSequence = (title) => `\x1b]0;${title.replace(/[\x00-\x1f\x7f]
  *  stop`), press Enter once more, or nothing. Messages stay in the inbox until a hook takes them, so a lost
  *  keystroke is retried, never dropped. `typed`/`typedAt` say what was last typed and when; `echoed` whether the TUI
  *  showed it; `enters` how many times Enter was pressed for it and `enteredAt` when last. Enter is pressed at most
- *  twice per typed text, never when the text was not echoed, and nothing new is typed while the last text is fresh. */
+ *  twice per nudge, never when the text was not echoed, and nothing new is typed while the last text is fresh.
+ *  `quietFor`: milliseconds since the tool last wrote to the terminal. A Stop hook does not mean the turn is over: a
+ *  goal (/goal) or another plugin's Stop hook keeps the tool working after it, with the spinner still redrawing, so
+ *  nothing is typed until the screen has been still for a few seconds.
+ *  The exit command gets no second Enter: the first one quits the tool, and anything that then appears is a dialogue
+ *  (Claude Code asks about background tasks it would stop), where Enter would pick the default for the user. */
 export function nextAction(s, now) {
-    if (s.status !== 'idle' || !s.gateClear)
+    if (s.status !== 'idle' || !s.gateClear || s.quietFor < 3000)
         return null;
     const want = s.stop ? 'stop' : s.unread ? 'nudge' : null;
     if (!want)
@@ -180,7 +194,7 @@ export function nextAction(s, now) {
         return want; // first try, or the typed text was lost or swallowed
     if (s.typed !== want)
         return null; // something else is still in the input box; wait for it to go through or expire
-    if (!s.echoed || s.enters !== 1)
+    if (s.typed === 'stop' || !s.echoed || s.enters !== 1)
         return null; // swallowed: hands off; never pressed: the user got there first; pressed twice: enough
     if (now - s.enteredAt > 5_000)
         return 'enter'; // typed and echoed but not submitted: press Enter once more
@@ -212,15 +226,16 @@ export function run(tool, launch, extraArgs) {
         if (/^CLAUDECODE/.test(k))
             delete env[k]; // allow launching from inside a Claude session
     const term = pty.spawn(file, [...args, ...launch.args, ...extraArgs], {
-        name: 'xterm-256color', cols: process.stdout.columns || 120, rows: process.stdout.rows || 40, cwd: launch.cwd, env,
+        name: 'xterm-256color', cols: process.stdout.columns || 120, rows: process.stdout.rows || 40, cwd: launch.project.dir, env, // the project folder: the tool then treats it as the project (same /resume list, CLAUDE.md, trust)
     });
     const d = db.openDb(launch.dbFile);
     db.addAgent(d, { name: launch.name, tool, pid: term.pid, cwd: launch.cwd, worktree: launch.worktree, heartbeat: true });
-    let outTail = '', echoBuf = '', awaitingEcho = false;
+    let outTail = '', echoBuf = '', awaitingEcho = false, lastOutputAt = Date.now();
     const titles = new TitleFilter();
     let title = titleFor(launch.name, null);
     process.stdout.write(titleSequence(title));
     term.onData(x => {
+        lastOutputAt = Date.now();
         process.stdout.write(titles.push(x));
         if (awaitingEcho)
             echoBuf = (echoBuf + x).slice(-16000);
@@ -258,11 +273,11 @@ export function run(tool, launch, extraArgs) {
             typedAt = enteredAt = enters = 0;
             echoed = false;
         }
-        const s = { status, unread: db.hasUnread(d, launch.name), stop: !!me?.stop_requested_at, gateClear: gate.clear() && gate.settled(), typed, typedAt, echoed, enters, enteredAt };
+        const s = { status, unread: db.hasUnread(d, launch.name), stop: !!me?.stop_requested_at, gateClear: gate.clear() && gate.settled(), quietFor: Date.now() - lastOutputAt, typed, typedAt, echoed, enters, enteredAt };
         const action = nextAction(s, Date.now());
-        const state = `${status}/${s.unread}/${s.stop}/${s.gateClear}/${action}`;
+        const state = `${status}/${s.unread}/${s.stop}/${s.gateClear}/${s.quietFor >= 3000}/${action}`;
         if (state !== lastState) {
-            db.log(`wake loop: status=${status} unread=${s.unread} stop=${s.stop} gateClear=${s.gateClear} action=${action}`);
+            db.log(`wake loop: status=${status} unread=${s.unread} stop=${s.stop} gateClear=${s.gateClear} quiet=${s.quietFor >= 3000} action=${action}`);
             lastState = state;
         }
         if (!action)
@@ -297,6 +312,19 @@ export function run(tool, launch, extraArgs) {
             term.write('\r');
             enteredAt = Date.now();
             enters = 1;
+            if (action !== 'stop')
+                return;
+            // Quitting over the agent's background work would kill it, so chord stays (Esc) and tries again once the exit
+            // command has expired, by which time the work may be done.
+            echoBuf = '';
+            awaitingEcho = true;
+            setTimeout(() => {
+                awaitingEcho = false;
+                if (!exitDeclined(echoBuf))
+                    return;
+                db.log('wake loop: the tool asked before quitting because the agent has background work running; staying, will try again later');
+                term.write(ESC_INPUT);
+            }, 2000);
         }, 1500);
     }), 1000);
     return new Promise(resolve => {

package/dist/serve.js

@@ -1,4 +1,5 @@
-// Entry point for the per-agent MCP server. Spawned by the coding agent over stdio, in the agent's workspace.
+// Entry point for the per-agent MCP server. Spawned by the coding agent over stdio, in the project folder; the
+// agent's workspace comes from the CHORD_* environment, not from cwd.
 import { openDb } from "./db.js";
 import { serve } from "./mcp.js";
 import { tools } from "./tools.js";

package/dist/tools.js

@@ -10,16 +10,20 @@ export function insideDir(dir, file) {
 }
 /**
  * The claim key for a path an agent names: workspace-relative with forward slashes. Absolute paths and
- * paths starting with the repository directory are taken as given; any other relative path is read as
- * repository-relative (what the schema used to say, and what agents working inside the repo naturally
- * write). Paths outside the workspace are refused: chord cannot coordinate them.
+ * paths starting with the repository directory are taken as given; a path from the project folder
+ * (chord/agents/<name>/<repo>/...) is resolved there; any other relative path is read as
+ * repository-relative (what agents working inside the repo naturally write). Paths outside the
+ * workspace are refused: chord cannot coordinate them.
  */
 export function claimPath(ctx, file) {
     const repoDir = path.relative(ctx.cwd, ctx.worktree).split(path.sep).join('/');
     const asGiven = normFile(ctx, file);
     let abs;
+    const fromProject = 'chord/agents/'; // the spelling from the tool's cwd, the project folder; another agent's folder then fails the check below
     if (path.isAbsolute(file) || !repoDir || repoDir === '.' || /^\.\.(\/|$)/.test(asGiven))
         abs = path.resolve(ctx.cwd, file);
+    else if (ctx.project && asGiven.startsWith(fromProject))
+        abs = path.resolve(ctx.project, file);
     else if (asGiven === repoDir || asGiven.startsWith(repoDir + '/')) {
         // "rich/console.py" is the workspace path of the repository's console.py, or the repository path of a package
         // named like the repository (rich/rich/console.py); whichever exists is meant, and both existing is ambiguous
@@ -306,7 +310,7 @@ function finishLocked(ctx) {
     db.releaseAll(ctx.db, ctx.agent, 'finish');
     const online = db.listAgents(ctx.db).filter(a => a.name !== ctx.agent && a.status !== 'offline').map(a => a.name);
     if (online.length)
-        db.send(ctx.db, ctx.agent, online, `${ctx.agent} merged into ${main}:\n${subjects.map(s => `- ${s}`).join('\n')}\nNo action is needed: finish() rebases your branch for you when you call it. This is a notification; do not reply.`, 'notice');
+        db.send(ctx.db, ctx.agent, online, `${ctx.agent} merged into ${main}:\n${subjects.map(s => `- ${s}`).join('\n')}\n${db.NOTICE_TAIL}`, 'notice');
     return { merged: subjects, into: main, notified: online };
 }
 export function tools(ctx) {
@@ -336,7 +340,7 @@ export function tools(ctx) {
             inputSchema: {
                 type: 'object',
                 properties: {
-                    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)'),
+                    file: str('The file, as a path from your working directory (chord/agents/<you>/<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: 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.'),

package/dist/trust.js

@@ -1,6 +1,5 @@
-// Claude Code asks "do you trust this folder?" once per working directory and records the answer in
-// ~/.claude.json. Every agent workspace is a new directory, so without this each launch asks again.
-// The workspace only holds a worktree of a repository the user already chose to run chord in.
+// What the user has told Claude Code and Codex to trust, read from their own config files. Agents run in the
+// project folder, which the user trusts (or not) in Claude Code themselves; chord writes no trust of its own.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -18,37 +17,6 @@ export function claudeTrusts(dir, file = claudeConfigPath()) {
         return false;
     }
 }
-/** Mark `workspace` as trusted for Claude Code. Returns false when Claude Code has no config yet (nothing to do)
- *  or the entry was already there. Writes atomically; other fields of the file are left untouched. */
-export function pretrustClaude(workspace, file = claudeConfigPath()) {
-    let raw;
-    try {
-        raw = fs.readFileSync(file, 'utf8');
-    }
-    catch {
-        return false;
-    }
-    let cfg;
-    try {
-        cfg = JSON.parse(raw);
-    }
-    catch {
-        return false;
-    } // not ours to repair
-    if (typeof cfg !== 'object' || cfg === null)
-        return false;
-    const projects = (cfg.projects ??= {});
-    const key = Object.keys(projects).find(k => norm(k) === norm(workspace)) ?? workspace.replace(/\\/g, '/');
-    if (projects[key]?.hasTrustDialogAccepted === true)
-        return false;
-    projects[key] = projects[key]
-        ? { ...projects[key], hasTrustDialogAccepted: true } // existing entry: flip the flag, keep everything else
-        : { allowedTools: [], mcpContextUris: [], mcpServers: {}, enabledMcpjsonServers: [], disabledMcpjsonServers: [], hasTrustDialogAccepted: true, hasClaudeMdExternalIncludesApproved: false, hasClaudeMdExternalIncludesWarningShown: false };
-    const tmp = `${file}.chord-${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2));
-    fs.renameSync(tmp, file);
-    return true;
-}
 /** Which of a repository's .mcp.json servers the user has approved or rejected in Claude Code, and whether they
  *  approved them all at once. Claude asks per server when it runs in the repository; chord has no prompt, so it only
  *  starts what the user has already approved there. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chord-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Run several coding agents in one git project, each in its own worktree, with shared file claims and messaging",
   "license": "MIT",
   "keywords": [
@@ -31,7 +31,10 @@
   "engines": {
     "node": ">=24"
   },
-  "os": ["win32", "linux"],
+  "os": [
+    "win32",
+    "linux"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "prepare": "tsc -p tsconfig.build.json",