chord-cli 0.1.0 → 0.1.1

package/dist/launch.js

@@ -0,0 +1,399 @@
+// Everything `chord <tool>` needs before spawning: the project, an agent name, the agent's
+// workspace with its repository worktree, and the per-launch hook/MCP configuration for each
+// tool. Hook command strings must stay identical across launches (Codex persists trust by
+// hashing them), so per-session values go in env.
+import { execFileSync, execSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as db from "./db.js";
+import { ensureStateDir, resolveProject } from "./project.js";
+import { claudeMcpChoices, claudeTrusts } from "./trust.js";
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: db.gitEnv(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+// realpath gives one canonical spelling (drive letter and directory case): Codex persists hook trust by hashing the command string
+// sibling modules by absolute path: .ts when run from src, .js from the built dist
+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) {
+        if (!/^[A-Za-z0-9._-]+$/.test(override))
+            throw new Error('agent names may only contain letters, digits, ".", "_" and "-"');
+        // the name becomes a directory and a branch: ".." would escape agents/, git refuses components starting with "."
+        // or ending in "." or ".lock", and Windows reserves CON, NUL, COM1 and friends
+        if (/^[.-]|\.$|\.\.|\.lock$/i.test(override) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i.test(override))
+            throw new Error(`"${override}" cannot be an agent name: no leading "." or "-", no trailing "." or ".lock", no "..", and no Windows reserved names (CON, NUL, COM1...)`);
+        // workspace paths are case-insensitive on Windows and macOS, so names differing only in case would share one
+        const clash = db.listAgents(d).find(a => a.name.toLowerCase() === override.toLowerCase());
+        if (clash && clash.name !== override)
+            throw new Error(`agent "${clash.name}" already exists; names must differ in more than case`);
+        if (clash && clash.status !== 'offline') {
+            // A lone agent killed outright, whose pid Windows has since handed to another process, is never swept: nobody
+            // else's heartbeat is fresh to compare with. A heartbeat that stays stale while we watch it is a dead wrapper
+            // (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);
+            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`);
+            db.log(`launch: ${override} has not had a heartbeat for ${Math.round((Date.now() - clash.heartbeat_at) / 1000)}s; taking it for dead`);
+            db.setStatus(d, clash.name, 'offline');
+            db.releaseAll(d, clash.name, 'swept');
+        }
+        return override;
+    }
+    // the project name makes the agent recognisable in `chord ls --all`; kept short so the worktree path stays short
+    const base = path.basename(project).toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 12).replace(/^-+|-+$/g, '') || 'project';
+    for (;;) {
+        const name = `${tool}-${base}-${randomBytes(2).toString('hex')}`;
+        if (!db.getAgent(d, name))
+            return name;
+    }
+}
+/** The agent's workspace: <project>/chord/agents/<name>. Its repository worktree sits inside at <repoName>. */
+export const workspacePath = (p, name) => path.join(p.dir, 'chord', 'agents', name);
+/** Create (or reuse) a worktree of `repo` at `wt` on branch chord/<name>, forked from the current main HEAD. */
+export function ensureWorktree(repo, wt, name) {
+    const branch = `chord/${name}`;
+    if (fs.existsSync(path.join(wt, '.git'))) {
+        try {
+            git(wt, 'rev-parse', '--git-dir');
+        }
+        catch { // the link is broken, e.g. the project was moved
+            git(repo, 'worktree', 'repair', wt);
+            git(wt, 'rev-parse', '--git-dir');
+        }
+        return onBranch(wt, branch);
+    }
+    if (fs.existsSync(wt) && fs.readdirSync(wt).length)
+        throw new Error(`${wt} exists but is not a git worktree; remove it or pick another --name`);
+    fs.mkdirSync(path.dirname(wt), { recursive: true });
+    // Every worktree directory is named after the repository, so git gives them ids repo, repo1, repo2... After the
+    // project moves, the registrations point at the old place: pruning first would drop them all and let this new
+    // worktree take the id "repo" that belonged to another agent, which a later repair of that agent would then share.
+    // Repair the siblings first; prune only removes what the user really deleted.
+    const siblings = siblingWorktrees(wt);
+    if (siblings.length) {
+        try {
+            git(repo, 'worktree', 'repair', ...siblings);
+        }
+        catch { /* a sibling beyond repair is pruned below */ }
+    }
+    git(repo, 'worktree', 'prune');
+    const exists = git(repo, 'branch', '--list', branch) !== '';
+    try {
+        // core.longpaths: a worktree path is some forty characters longer than the main checkout's, which on Windows is
+        // enough to push a deep repository past MAX_PATH
+        if (exists)
+            git(repo, '-c', 'core.longpaths=true', 'worktree', 'add', wt, branch);
+        else
+            git(repo, '-c', 'core.longpaths=true', 'worktree', 'add', '-b', branch, wt);
+    }
+    catch (e) {
+        // nothing half-made stays behind: a stale branch or an empty directory would trip the next launch
+        try {
+            git(repo, 'worktree', 'prune');
+        }
+        catch { /* best effort */ }
+        if (!exists) {
+            try {
+                git(repo, 'branch', '-D', branch);
+            }
+            catch { /* never created */ }
+        }
+        try {
+            fs.rmSync(wt, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        const msg = (e.stderr ?? e.message).trim();
+        if (/too long/i.test(msg))
+            throw new Error(`${msg}\n${wt} is too long a path for git here; run "git config --global core.longpaths true", or move the project to a shorter path`);
+        throw new Error(`could not create the worktree ${wt}: ${msg}`);
+    }
+    return onBranch(wt, branch);
+}
+/** The other agents' worktrees beside `wt` (chord/agents/<other>/<repoName>) that still exist on disk. */
+function siblingWorktrees(wt) {
+    const agents = path.dirname(path.dirname(wt));
+    try {
+        return fs.readdirSync(agents)
+            .map(n => path.join(agents, n, path.basename(wt)))
+            .filter(p => p !== wt && fs.existsSync(path.join(p, '.git')));
+    }
+    catch {
+        return [];
+    }
+}
+/** A worktree that is not on its own branch is sharing a registration with another agent: refuse rather than let two
+ *  agents work on one index. */
+function onBranch(wt, branch) {
+    const head = git(wt, 'rev-parse', '--abbrev-ref', 'HEAD');
+    if (head !== branch)
+        throw new Error(`${wt} is on ${head} instead of ${branch}; its git registration seems to be shared with another agent. Remove the directory and launch again`);
+    return wt;
+}
+// ctxLimit: Codex caps a hook's additionalContext (default about 2,500 tokens); the briefing and message batches need more
+const EVENTS = [
+    { event: 'session-start', claude: 'SessionStart', codex: 'SessionStart', ctxLimit: 16000 },
+    { event: 'notification', claude: 'Notification', matcher: { claude: 'idle_prompt' } }, // Claude only: Codex reports idle through OSC 7501
+    { event: 'user-prompt-submit', claude: 'UserPromptSubmit', codex: 'UserPromptSubmit', ctxLimit: 16000 },
+    { event: 'pre-tool-use', claude: 'PreToolUse', codex: 'PreToolUse', matcher: { claude: 'Edit|Write|MultiEdit|NotebookEdit' } }, // Codex: every tool, so apply_patch run from the shell is seen too
+    { event: 'post-tool-use', claude: 'PostToolUse', codex: 'PostToolUse', ctxLimit: 16000 }, // every tool: shell-edit warnings and mid-turn message delivery
+    { event: 'stop', claude: 'Stop', codex: 'Stop' },
+    { event: 'session-end', claude: 'SessionEnd', codex: 'SessionEnd', timeout: 10 },
+];
+/** The node that runs chord, by absolute path, for the MCP server (spawned from an argument list, so spaces in the
+ *  path are no problem). The hook commands say plain `node`: Codex cannot run a command whose executable is quoted
+ *  ("C:/Program Files/nodejs/node.exe" fails silently, a quoted argument is fine), so instead the wrapper puts this
+ *  node's directory at the front of the agent's PATH (see withNodeOnPath), which also keeps an older node on the
+ *  user's PATH (nvm, a project .nvmrc) from being the one that cannot run .ts files. */
+export const NODE = fs.realpathSync.native(process.execPath).split(path.sep).join('/');
+export const hookCommand = (event) => `node "${HOOKS_TS}" ${event}`;
+/** The environment with the directory of the node running chord first on PATH (whatever the variable's case). */
+export function withNodeOnPath(env) {
+    const key = Object.keys(env).find(k => k.toUpperCase() === 'PATH') ?? 'PATH';
+    const dir = path.dirname(fs.realpathSync.native(process.execPath));
+    const current = env[key] ?? '';
+    if (current.split(path.delimiter)[0] === dir)
+        return env;
+    return { ...env, [key]: current ? `${dir}${path.delimiter}${current}` : dir };
+}
+/** `$CLAUDE_PROJECT_DIR` in a repository's hook commands and MCP definitions means the repository, which for an agent
+ *  is its worktree; Claude would point it at the workspace. */
+export function substituteProjectDir(value, worktree) {
+    const dir = worktree.split(path.sep).join('/');
+    const walk = (v) => {
+        if (typeof v === 'string')
+            return v.replace(/\$\{CLAUDE_PROJECT_DIR\}|\$CLAUDE_PROJECT_DIR/g, dir);
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === 'object')
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(value);
+}
+/** The repository's .mcp.json as an --mcp-config value, reduced to the servers the user approved in Claude Code, or
+ *  null when there is nothing to pass. */
+export function projectMcpConfig(worktree, source) {
+    const file = path.join(worktree, '.mcp.json');
+    if (!fs.existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        process.stderr.write(`chord: ${file} is not valid JSON (${e.message}); its servers are not loaded\n`);
+        return null;
+    }
+    const servers = parsed?.mcpServers ?? {};
+    const choice = claudeMcpChoices(source.repo, source.claudeConfig);
+    const keep = Object.fromEntries(Object.entries(servers).filter(([name]) => !choice.disabled.includes(name) && (choice.all || choice.enabled.includes(name))));
+    const skipped = Object.keys(servers).filter(n => !(n in keep));
+    if (skipped.length)
+        process.stderr.write(`chord: not starting the repository's MCP server(s) ${skipped.join(', ')}: run claude in ${source.repo} once and approve them there first\n`);
+    return Object.keys(keep).length ? JSON.stringify({ mcpServers: substituteProjectDir(keep, worktree) }) : null;
+}
+export function claudeArgs(env, projectConfig = false) {
+    const hooks = {};
+    for (const e of EVENTS) {
+        hooks[e.claude] = [{
+                ...(e.matcher ? { matcher: e.matcher.claude } : {}),
+                hooks: [{ type: 'command', command: hookCommand(e.event), ...(e.timeout ? { timeout: e.timeout } : {}) }],
+            }];
+    }
+    const mcp = { mcpServers: { chord: { command: NODE, args: [SERVE_TS], env } } };
+    // 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.
+    const wt = env.CHORD_WORKTREE;
+    const addDir = wt ? ['--add-dir', wt] : [];
+    const source = projectConfig === true ? { repo: wt ?? '' } : projectConfig || null;
+    const projectMcp = source && wt ? projectMcpConfig(wt, source) : null;
+    const mcpFiles = projectMcp ? [projectMcp] : [];
+    const settings = source ? mergeProjectSettings(ours, wt) : ours;
+    // --add-dir and --mcp-config take any number of values, so they must not come last: the user's own arguments
+    // follow these, and a prompt such as `chord claude "fix the tests"` would be read as another directory.
+    // --settings takes exactly one value and closes the list.
+    return [...addDir, '--mcp-config', JSON.stringify(mcp), ...mcpFiles, '--settings', JSON.stringify(settings)];
+}
+/** The user's own --settings folded under chord's (chord's hooks stay, theirs are added), in place in `args`. */
+export function mergeUserSettings(args, user) {
+    const i = args.indexOf('--settings');
+    if (i < 0 || i + 1 >= args.length)
+        return args;
+    const out = [...args];
+    out[i + 1] = JSON.stringify(mergeSettings(JSON.parse(args[i + 1]), user));
+    return out;
+}
+const PROJECT_CONFIG_FILES = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json'];
+export const hasProjectConfig = (worktree) => PROJECT_CONFIG_FILES.some(f => fs.existsSync(path.join(worktree, f)));
+/** chord's settings plus the repository's .claude/settings.json and settings.local.json (later files win,
+ *  hook lists are concatenated so both chord's and the project's hooks run). */
+/** Hook lists of `b` appended to those of `a`, so both sets run. */
+function concatHooks(a, b) {
+    const hooks = { ...(a.hooks ?? {}) };
+    for (const [event, list] of Object.entries(b.hooks ?? {}))
+        hooks[event] = [...(hooks[event] ?? []), ...(Array.isArray(list) ? list : [])];
+    return hooks;
+}
+/** Somebody else's settings underneath chord's: their keys fill in, chord's keys win, hook lists are concatenated,
+ *  and disableAllHooks is dropped because it would switch chord itself off. */
+export function mergeSettings(ours, theirs) {
+    const out = { ...theirs, ...ours, hooks: concatHooks(ours, theirs) };
+    if (ours.permissions || theirs.permissions) {
+        // permission lists add up, as across Claude's own settings levels; other permission keys follow the usual precedence
+        const lists = (k) => [...new Set([...(ours.permissions?.[k] ?? []), ...(theirs.permissions?.[k] ?? [])])];
+        out.permissions = { ...theirs.permissions, ...ours.permissions };
+        for (const k of ['allow', 'deny', 'ask'])
+            if (lists(k).length)
+                out.permissions[k] = lists(k);
+    }
+    delete out.disableAllHooks;
+    return out;
+}
+export function mergeProjectSettings(ours, worktree) {
+    if (!worktree)
+        return ours;
+    let theirs = {};
+    for (const name of ['settings.json', 'settings.local.json']) { // settings.local.json wins, as in Claude Code itself
+        let one;
+        try {
+            one = JSON.parse(fs.readFileSync(path.join(worktree, '.claude', name), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (typeof one !== 'object' || one === null)
+            continue;
+        one = substituteProjectDir(one, worktree);
+        theirs = { ...theirs, ...one, hooks: concatHooks(theirs, one) };
+    }
+    return mergeSettings(ours, theirs);
+}
+/** A JSON string literal is also a valid TOML basic string, quotes, backslashes and non-ASCII included. */
+const toml = (s) => JSON.stringify(s);
+/** CLI arguments that inject chord's hooks and MCP server into Codex. Values are TOML. */
+/** `writableRoots`: directories Codex's workspace-write sandbox must also be allowed to write. A linked worktree keeps
+ *  its index and refs under the main checkout's .git, outside the agent's workspace, so without this every git commit
+ *  fails inside the sandbox. */
+export function codexArgs(env, writableRoots = []) {
+    const args = [];
+    if (writableRoots.length)
+        args.push('-c', `sandbox_workspace_write.writable_roots=[${writableRoots.map(toml).join(',')}]`);
+    for (const e of EVENTS) {
+        if (!e.codex)
+            continue;
+        const matcher = e.matcher?.codex ? `matcher=${toml(e.matcher.codex)},` : '';
+        const limit = e.ctxLimit ? `,additionalContextLimit=${e.ctxLimit}` : '';
+        args.push('-c', `hooks.${e.codex}=[{${matcher}hooks=[{type="command",command=${toml(hookCommand(e.event))}${limit}}]}]`);
+    }
+    const envToml = Object.entries(env).map(([k, v]) => `${k}=${toml(v)}`).join(',');
+    // finish may wait minutes for the merge lock; Codex's default tool timeout is 60s
+    args.push('-c', `mcp_servers.chord={command=${toml(NODE)},args=[${toml(SERVE_TS)}],env={${envToml}},tool_timeout_sec=600}`);
+    return args;
+}
+const fwd = (p) => p.split(path.sep).join('/');
+/** Resolve everything for `chord <tool> [--name x] [tool args...]` without spawning. Throws NeedsRestructure. */
+export function prepare(tool, cwd, override) {
+    const project = resolveProject(cwd);
+    try {
+        git(project.repo, 'rev-parse', '--verify', '-q', 'HEAD');
+    }
+    catch {
+        throw new Error(`${project.repo} has no commits yet; make an initial commit first`);
+    }
+    ensureStateDir(project);
+    const dbFile = db.dbPath(project.stateDir);
+    const d = db.openDb(dbFile);
+    db.sweep(d);
+    const name = pickName(d, tool, project.dir, override);
+    const ws = workspacePath(project, name);
+    // Take the name now, before the worktree and setup take their time: a second launch under the same name a moment
+    // later must find it online. The wrapper re-registers with the tool's own pid when it starts.
+    db.addAgent(d, { name, tool, pid: process.pid, cwd: ws, worktree: path.join(ws, project.repoName), heartbeat: true });
+    try {
+        const config = readConfig(project);
+        const worktree = ensureWorktree(project.repo, path.join(ws, project.repoName), name);
+        const env = { CHORD_AGENT_ID: name, CHORD_DB: fwd(dbFile), CHORD_TOOL: tool, CHORD_PROJECT: fwd(project.dir), CHORD_WORKSPACE: fwd(ws), CHORD_WORKTREE: fwd(worktree) };
+        // Setup is owed until it has finished once: a marker, not the worktree's existence, says so, because a setup
+        // interrupted half-way leaves the worktree behind and a relaunch must not take a half-prepared checkout for ready.
+        const marker = setupMarker(project, name);
+        if (config.setup && !fs.existsSync(marker)) {
+            runSetup(project, name, worktree, config.setup, env);
+            fs.mkdirSync(path.dirname(marker), { recursive: true });
+            fs.writeFileSync(marker, `${Date.now()}\n`);
+        }
+        let projectConfig = false;
+        if (tool === 'claude' && hasProjectConfig(worktree)) {
+            projectConfig = claudeTrusts(project.repo) || claudeTrusts(project.dir) ? { repo: project.repo } : false;
+            if (!projectConfig)
+                process.stderr.write(`chord: ${project.repo} has its own .claude settings or .mcp.json, but you have not trusted it in Claude Code, so they are not loaded for this agent. Run claude in ${project.repo} once and accept the trust prompt to change that.\n`);
+        }
+        return { name, project, cwd: ws, worktree, dbFile, env, args: tool === 'claude' ? claudeArgs(env, projectConfig) : codexArgs(env, [path.join(project.repo, '.git')]) };
+    }
+    catch (e) {
+        db.setStatus(d, name, 'offline'); // the launch failed: the name is free again
+        throw e;
+    }
+}
+/** <project>/chord/config.json. `setup` is a shell command run in every new worktree before the agent starts,
+ *  for example "npm install". */
+export function readConfig(project) {
+    const file = path.join(project.dir, 'chord', 'config.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return {};
+    }
+    let cfg;
+    try {
+        cfg = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${file} is not valid JSON: ${e.message}`);
+    }
+    if (typeof cfg !== 'object' || cfg === null)
+        throw new Error(`${file} must hold a JSON object`);
+    const setup = cfg.setup;
+    if (setup !== undefined && typeof setup !== 'string')
+        throw new Error(`${file}: "setup" must be a string (a shell command)`);
+    return setup ? { setup } : {};
+}
+/** Where `chord clean` and a relaunch look to see whether the setup command has run for this agent. */
+export const setupMarker = (project, name) => path.join(project.stateDir, 'setup-done', name);
+/** A failed setup aborts the launch, and the half-prepared worktree and branch go with it so the next launch starts clean. */
+function runSetup(project, name, worktree, setup, env) {
+    process.stderr.write(`chord: running setup in ${worktree}: ${setup}\n`);
+    // Ctrl+C goes to the setup command, which then fails and is cleaned up below; without a listener it would kill chord
+    // itself first and leave the worktree and branch behind
+    const ignoreSigint = () => { };
+    process.on('SIGINT', ignoreSigint);
+    try {
+        execSync(setup, { cwd: worktree, stdio: 'inherit', env: { ...process.env, ...env } });
+    }
+    catch (e) {
+        try {
+            git(project.repo, 'worktree', 'remove', '--force', worktree);
+        }
+        catch { /* best effort */ }
+        try {
+            git(project.repo, 'branch', '-D', `chord/${name}`);
+        }
+        catch { /* best effort */ }
+        const status = e.status;
+        throw new Error(`setup command failed${status != null ? ` with exit code ${status}` : ''}: ${setup}\nthe worktree was removed; fix the command in ${path.join(project.dir, 'chord', 'config.json')} or the repository and launch again`);
+    }
+    finally {
+        process.off('SIGINT', ignoreSigint);
+    }
+}

package/dist/mcp.js

@@ -0,0 +1,51 @@
+// Minimal MCP server over stdio: newline-delimited JSON-RPC 2.0, tools only.
+import { createInterface } from 'node:readline';
+const PROTOCOL = '2025-06-18';
+/** Handle one JSON-RPC message. Returns the response, or undefined for notifications. */
+export function handle(tools, req) {
+    const { id, method, params = {} } = req;
+    if (id === undefined)
+        return undefined; // notification, e.g. notifications/initialized
+    const ok = (result) => ({ jsonrpc: '2.0', id, result });
+    const err = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+    switch (method) {
+        case 'initialize':
+            return ok({ protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: { name: 'chord', version: '0.0.0' } });
+        case 'ping':
+            return ok({});
+        case 'tools/list':
+            return ok({ tools: tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+        case 'tools/call': {
+            const tool = tools.find(t => t.name === params.name);
+            if (!tool)
+                return err(-32602, `unknown tool: ${String(params.name)}`);
+            try {
+                const out = tool.handler(params.arguments ?? {});
+                const text = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
+                return ok({ content: [{ type: 'text', text }] });
+            }
+            catch (e) {
+                return ok({ content: [{ type: 'text', text: e.message }], isError: true });
+            }
+        }
+        default:
+            return err(-32601, `method not found: ${method}`);
+    }
+}
+export function serve(tools) {
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', line => {
+        if (!line.trim())
+            return;
+        let req;
+        try {
+            req = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const res = handle(tools, req);
+        if (res)
+            process.stdout.write(JSON.stringify(res) + '\n');
+    });
+}

package/dist/patch.js

@@ -0,0 +1,10 @@
+/** File paths touched by a Codex apply_patch payload, taken from its header lines. */
+export function patchFiles(patch) {
+    const out = new Set();
+    for (const line of patch.split('\n')) {
+        const m = /^\s*\*\*\* (?:Add File|Update File|Delete File|Move to): (.+?)\s*$/.exec(line); // a heredoc may indent the headers
+        if (m)
+            out.add(m[1]);
+    }
+    return [...out];
+}

package/dist/project.js

@@ -0,0 +1,188 @@
+// A chord project is the folder `chord` is run in. It contains the git repository as a child
+// directory and a `chord/` directory for agent workspaces; chord's own state lives under ~/.chord.
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { gitEnv } from "./db.js";
+/** Thrown when the folder is a repository root: chord offers to move it into a child directory. */
+export class NeedsRestructure extends Error {
+    dir;
+    suggestedName;
+    constructor(dir, suggestedName) {
+        super(`${dir} is itself a git repository; chord needs the repository in a child directory of the project`);
+        this.dir = dir;
+        this.suggestedName = suggestedName;
+    }
+}
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8', env: gitEnv(), stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+const same = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+function repoRootOf(dir) {
+    try {
+        return fs.realpathSync.native(git(dir, 'rev-parse', '--show-toplevel'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Only a .git *directory* marks a project repository; a .git file is a linked worktree or a submodule. */
+const isRepoDir = (dir) => { try {
+    return fs.statSync(path.join(dir, '.git')).isDirectory();
+}
+catch {
+    return false;
+} };
+/** Readable like Claude Code's projects directory (separators and colons become dashes), plus a short hash so
+ *  that D:\a-b and D:\a\b do not share one state directory. */
+export function encodeProjectPath(dir) {
+    const key = process.platform === 'win32' ? dir.toLowerCase() : dir;
+    return `${dir.replace(/[\\/:]/g, '-')}-${createHash('sha1').update(key).digest('hex').slice(0, 6)}`;
+}
+export const stateDirFor = (dir) => path.join(process.env.CHORD_HOME ?? path.join(os.homedir(), '.chord'), 'projects', encodeProjectPath(dir));
+/** A repository directory name chord can work with: a single path segment that is not chord's own directory. */
+export function validateRepoName(name) {
+    if (!name.trim())
+        return 'the name is empty';
+    if (/[\\/]/.test(name) || name === '.' || name === '..')
+        return 'the name must be a single directory name';
+    if (name.toLowerCase() === 'chord')
+        return '"chord" is reserved for chord\'s own directory';
+    return null;
+}
+/** Default name for the repository directory: the origin remote's name, else the folder's own name. */
+export function suggestedRepoName(repo) {
+    try {
+        const url = git(repo, 'remote', 'get-url', 'origin');
+        const last = url.split(/[\\/:]/).filter(Boolean).pop() ?? '';
+        const name = last.replace(/\.git$/i, '');
+        if (name && !validateRepoName(name))
+            return name;
+    }
+    catch { /* no origin */ }
+    const own = path.basename(repo);
+    return validateRepoName(own) ? 'repo' : own;
+}
+/** The nearest ancestor that already is a chord project, if any. */
+/** Child directories of `dir` that are repository roots. Looked up with stat, so a junction or symlink to a repository
+ *  counts (a Dirent reports those as links, not directories). */
+const repoChildren = (dir) => fs.readdirSync(dir).filter(n => { const p = path.join(dir, n); try {
+    return fs.statSync(p).isDirectory() && isRepoDir(p);
+}
+catch {
+    return false;
+} });
+/** The project `dir` belongs to, when it lies inside one: under the project's chord/ directory (a workspace or a
+ *  worktree) or inside its repository. A folder merely beside those, such as a new project created next to an old
+ *  one, is not claimed by the ancestor. */
+function enclosingProject(dir) {
+    for (let a = path.dirname(dir); a !== path.dirname(a); a = path.dirname(a)) {
+        if (!fs.existsSync(stateDirFor(a)) && !fs.existsSync(path.join(a, 'chord', 'agents')))
+            continue;
+        const inside = (sub) => { const rel = path.relative(path.join(a, sub), dir); return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)); };
+        if (inside('chord') || repoChildren(a).some(inside))
+            return a;
+    }
+    return null;
+}
+export function resolveProject(cwd) {
+    const dir = fs.realpathSync.native(cwd);
+    // inside an existing project (its main checkout, a workspace or a worktree): that project is meant
+    const parent = enclosingProject(dir);
+    if (parent)
+        return resolveProject(parent);
+    const enclosing = repoRootOf(dir);
+    if (enclosing) {
+        if (same(enclosing, dir))
+            throw new NeedsRestructure(dir, suggestedRepoName(dir));
+        throw new Error(`${dir} is inside the repository ${enclosing}; a chord project is the folder that contains the repository, not a folder inside it`);
+    }
+    const children = repoChildren(dir);
+    if (children.some(c => c.toLowerCase() === 'chord'))
+        throw new Error(`${dir}/chord is a git repository, but chord/ is reserved for chord's own directory; rename it`);
+    if (children.length === 0)
+        throw new Error(`${dir} contains no git repository; a chord project is a folder with the repository in a child directory`);
+    if (children.length > 1)
+        throw new Error(`${dir} contains several repositories (${children.join(', ')}); chord supports one per project for now`);
+    const repo = path.join(dir, children[0]);
+    return { dir, repo, repoName: children[0], stateDir: stateDirFor(dir) };
+}
+/** Why `dir` (a repository root) must not be moved into a child directory, or null when it is safe. */
+export function restructureBlocker(dir) {
+    if (same(fs.realpathSync.native(dir), fs.realpathSync.native(os.homedir())))
+        return 'refusing to move your home directory';
+    let worktrees = 1;
+    try {
+        worktrees = git(dir, 'worktree', 'list', '--porcelain').split('\n').filter(l => l.startsWith('worktree ')).length;
+    }
+    catch { /* not a repo */ }
+    if (worktrees > 1)
+        return `${dir} has linked worktrees (git worktree list); remove them first, moving the repository would break them`;
+    try {
+        if (git(dir, 'ls-files', '--', 'chord'))
+            return 'the repository tracks a top-level chord/ directory, which chord needs for itself; rename it first';
+    }
+    catch { /* ignore */ }
+    return null;
+}
+/** Move everything in `dir` (except chord/) into `dir/name`, so the repository becomes a child. Rolls back on failure. */
+export function restructure(dir, name, rename = fs.renameSync) {
+    const invalid = validateRepoName(name);
+    if (invalid)
+        throw new Error(invalid);
+    const blocker = restructureBlocker(dir);
+    if (blocker)
+        throw new Error(blocker);
+    const target = path.join(dir, name);
+    if (fs.existsSync(target))
+        throw new Error(`${target} already exists`);
+    const entries = fs.readdirSync(dir).filter(e => e !== 'chord');
+    fs.mkdirSync(target);
+    const moved = [];
+    try {
+        for (const e of entries) {
+            rename(path.join(dir, e), path.join(target, e));
+            moved.push(e);
+        }
+    }
+    catch (e) {
+        const stuck = [];
+        for (const m of moved) {
+            try {
+                rename(path.join(target, m), path.join(dir, m));
+            }
+            catch {
+                stuck.push(m);
+            }
+        }
+        if (!stuck.length) {
+            try {
+                fs.rmdirSync(target);
+            }
+            catch { /* leave it */ }
+        }
+        const note = stuck.length ? ` Rolling back failed too: ${stuck.join(', ')} are still under ${target}.` : ' Everything was moved back.';
+        throw new Error(`could not move ${dir} into ${target}: ${e.message}.${note} Close programs that have files open there and try again.`);
+    }
+    return target;
+}
+/** Every project that has state under ~/.chord/projects, for `chord ls --all`. */
+export function knownProjects() {
+    const root = path.dirname(stateDirFor('x'));
+    if (!fs.existsSync(root))
+        return [];
+    return fs.readdirSync(root).map(name => {
+        const stateDir = path.join(root, name);
+        let dir = null;
+        try {
+            dir = fs.readFileSync(path.join(stateDir, 'path'), 'utf8').trim();
+        }
+        catch { /* unknown */ }
+        return { stateDir, dbFile: path.join(stateDir, 'chord.db'), dir };
+    }).filter(p => fs.existsSync(p.dbFile));
+}
+/** Create the state directory and remember the project's real path (the encoding is not reversible). */
+export function ensureStateDir(p) {
+    fs.mkdirSync(p.stateDir, { recursive: true });
+    fs.writeFileSync(path.join(p.stateDir, 'path'), p.dir);
+}