agentcoor 0.0.0-stage → 0.3.7

package/src/connect.js

@@ -0,0 +1,351 @@
+import { open, lstat, unlink, rmdir, readlink, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { spawnSync, spawn } from "node:child_process";
+import { join, dirname } from "node:path";
+import { homedir, userInfo } from "node:os";
+import { installPaths } from "./config.js";
+import { download, MAX_API_BYTES, MAX_BINARY_BYTES } from "./http.js";
+import { RELEASE_PUBLIC_KEY } from "./signature.js";
+import { verifyManifest, artifactFor, verifyArtifact, readAcceptedEpoch, recordAcceptedEpoch, withInstallLock, MIN_RELEASE_EPOCH } from "./release.js";
+import { ensurePrivateDir, ensureUserDir, atomicWrite, assertSafePath } from "./fsx.js";
+import { updateFile, parseJsonObject } from "./harness.js";
+import { replaceTomlTables, tomlString } from "./toml.js";
+
+const AGENT_NAMES = /^agentcoor-agent-(darwin|linux)-(amd64|arm64)$/;
+export const HOST_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;   // gateway issues UUIDs
+export const HOST_TOKEN = /^[A-Za-z0-9_-]{16,255}$/;           // gateway issues base64url tokens
+
+/** Map Node's platform/arch to the gateway's download name. Windows users should run inside WSL. */
+export function agentBinaryName(platform = process.platform, arch = process.arch) {
+  const os = { darwin: "darwin", linux: "linux" }[platform];
+  if (!os) throw new Error(platform === "win32" ? "Windows is supported through WSL: run this inside your WSL shell" : `unsupported OS: ${platform}`);
+  const cpu = { x64: "amd64", arm64: "arm64" }[arch];
+  if (!cpu) throw new Error(`unsupported CPU: ${arch}`);
+  const name = `agentcoor-agent-${os}-${cpu}`;
+  if (!AGENT_NAMES.test(name)) throw new Error(`unsupported platform: ${name}`);
+  return name;
+}
+
+/** XML text escaping for plist <string> values. Paths are checked for control characters first. */
+export const xml = (s) => assertSafePath(String(s)).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+/** systemd ExecStart quoting: double quotes, backslash escapes, and %/$ specifiers doubled. */
+export const systemdQuote = (s) => `"${assertSafePath(String(s)).replace(/(["\\])/g, "\\$1").replace(/%/g, "%%").replace(/\$/g, "$$$$")}"`;
+
+/** Service identity. AGENT_SERVICE is the terminal agent; share.js passes SHARE_SERVICE. */
+export const AGENT_SERVICE = Object.freeze({ label: "com.agentcoor.agent", unit: "agentcoor-agent", description: "AgentCoor agent", log: "agent", flag: "-config", extra: [] });
+
+export function launchdPlist({ bin, config, logs, service = AGENT_SERVICE }) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${xml(service.label)}</string>
+<key>ProgramArguments</key><array><string>${xml(bin)}</string>${service.extra.map((a) => `<string>${xml(a)}</string>`).join("")}<string>${xml(service.flag)}</string><string>${xml(config)}</string></array>
+<key>RunAtLoad</key><true/><key>KeepAlive</key><true/>
+<key>StandardOutPath</key><string>${xml(join(logs, `${service.log}.log`))}</string><key>StandardErrorPath</key><string>${xml(join(logs, `${service.log}.err`))}</string>
+</dict></plist>
+`;
+}
+
+/**
+ * Capabilities the root marketplace worker keeps (docs/marketplace/AGENT-JOBS.md
+ * "Worker service"). Root is used only to build sandboxes: SYS_ADMIN for
+ * cgroup v2 subtrees, mount/pivot_root and namespaces; NET_ADMIN/NET_RAW for
+ * the private egress network namespace; SYS_CHROOT, SETUID/SETGID, SETPCAP,
+ * DAC_*, CHOWN, FOWNER, FSETID, MKNOD for runsc's gofer/sandbox setup and the
+ * uid-65534 job user; SYS_PTRACE for the systrap/ptrace platforms; KILL to tear
+ * sandboxes down; SYS_RESOURCE for RLIMIT_NPROC; SETFCAP because runsc maps
+ * uid 0 into the gofer's user namespace, which Linux 5.12+ refuses without it
+ * (measured on infra-server: "gofer: fork/exec /proc/self/exe: operation not
+ * permitted" under this unit until SETFCAP was added). Everything else (modules,
+ * raw I/O, clock, boot, BPF, MAC, audit control, ...) is dropped.
+ */
+export const WORKER_CAPABILITIES = Object.freeze(["CAP_SYS_ADMIN", "CAP_NET_ADMIN", "CAP_NET_RAW", "CAP_SYS_CHROOT", "CAP_SETUID", "CAP_SETGID", "CAP_SETPCAP",
+  "CAP_DAC_OVERRIDE", "CAP_DAC_READ_SEARCH", "CAP_CHOWN", "CAP_FOWNER", "CAP_FSETID", "CAP_MKNOD", "CAP_SYS_PTRACE", "CAP_KILL", "CAP_SYS_RESOURCE", "CAP_SETFCAP"]);
+export const SYSTEM_UNIT_DIR = "/etc/systemd/system";
+
+/** System-level unit (root, survives reboot without a login) with the capability bound above. */
+export function systemdSystemUnit({ bin, config, service = AGENT_SERVICE }) {
+  return `[Unit]\nDescription=${service.description}\nWants=network-online.target\nAfter=network-online.target\n[Service]\nType=simple\nExecStart=${[bin, ...service.extra, service.flag].map(systemdQuote).join(" ")} ${systemdQuote(config)}\nRestart=always\nRestartSec=3\nUMask=0077\nNoNewPrivileges=yes\nCapabilityBoundingSet=${WORKER_CAPABILITIES.join(" ")}\nProtectSystem=full\nProtectKernelModules=yes\nProtectClock=yes\nRestrictRealtime=yes\nLockPersonality=yes\n[Install]\nWantedBy=multi-user.target\n`;
+}
+
+export function systemdUnit({ bin, config, service = AGENT_SERVICE }) {
+  return `[Unit]\nDescription=${service.description}\nAfter=network-online.target\n[Service]\nExecStart=${[bin, ...service.extra, service.flag].map(systemdQuote).join(" ")} ${systemdQuote(config)}\nRestart=always\nRestartSec=3\n[Install]\nWantedBy=default.target\n`;
+}
+
+/** Secrets that must never reach a child process (launchctl, systemctl, claude, the agent itself). */
+export const SECRET_ENV = ["AGENTCOOR_HOST_TOKEN", "AGENTCOOR_API_KEY"];
+export function childEnv(env = process.env) {
+  const e = { ...env };
+  for (const k of SECRET_ENV) delete e[k];
+  return e;
+}
+const has = (cmd) => spawnSync("sh", ["-c", 'command -v "$1"', "sh", cmd], { stdio: "ignore", env: childEnv() }).status === 0;
+const run = (cmd, args, opts = {}) => spawnSync(cmd, args, { stdio: "ignore", env: childEnv(), ...opts });
+/** Run a command and capture stdout: { status, stdout }. */
+export const capture = (cmd, args) => {
+  const r = spawnSync(cmd, args, { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8", env: childEnv() });
+  return { status: r.status, stdout: r.stdout || "" };
+};
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Download and verify the signed manifest (signature, expiry, epoch >= embedded
+ * minimum and >= the highest epoch accepted on this machine), then the binary
+ * (size and SHA-256 from the manifest). Throws on any failure.
+ */
+export async function fetchVerifiedAgent(origin, name, { publicKey = RELEASE_PUBLIC_KEY, fetcher = download, minEpoch = MIN_RELEASE_EPOCH, acceptedEpoch = 0, now = Date.now() } = {}) {
+  const [manifestBuf, sig] = await Promise.all([
+    fetcher(`${origin}/download/release.json`, { maxBytes: MAX_API_BYTES }),
+    fetcher(`${origin}/download/release.json.sig`, { maxBytes: MAX_API_BYTES }).catch((e) => { throw new Error(`release.json.sig could not be downloaded (${e.message}): refusing to install an unsigned release`); }),
+  ]);
+  const manifest = verifyManifest(manifestBuf, sig, { publicKey, minEpoch, acceptedEpoch, now });
+  const entry = artifactFor(manifest, name);
+  const binary = await fetcher(`${origin}/download/${name}`, { maxBytes: Math.min(MAX_BINARY_BYTES, entry.size) });
+  const digest = verifyArtifact(binary, entry);
+  return { binary, digest, manifest };
+}
+
+export async function connect({ origin, hostId, hostToken, log = console.log, env = process.env }) {
+  if (!hostId || !hostToken) throw new Error("a host ID and host token are required: in the dashboard open Hosts -> Connect a machine, then run\n  npx agentcoor connect --host-id <id>\n(the token is read from a hidden prompt, --token-file, stdin, or AGENTCOOR_HOST_TOKEN)");
+  if (!HOST_ID.test(hostId)) throw new Error("the host ID contains unexpected characters; copy it again from the dashboard");
+  if (!HOST_TOKEN.test(hostToken)) throw new Error("the host token contains unexpected characters; copy it again from the dashboard");
+  for (const k of SECRET_ENV) { delete env[k]; delete process.env[k]; }
+  const name = agentBinaryName();
+  const p = installPaths(env);
+  for (const d of [p.base, dirname(p.bin), p.state, p.logs]) await ensurePrivateDir(d);
+
+  // One installer at a time per install dir: state read, manifest verification,
+  // epoch update, binary replacement and service restart all happen under the lock,
+  // so a concurrent older install can neither lower the epoch nor win the rename.
+  await withInstallLock(p.base, async () => {
+    log(`==> Downloading ${name}`);
+    const acceptedEpoch = await readAcceptedEpoch(p.base);
+    const { binary, digest, manifest } = await fetchVerifiedAgent(origin, name, { acceptedEpoch });
+    log(`==> Verified signed release ${manifest.version} (epoch ${manifest.epoch}) and SHA-256 ${digest}`);
+    await recordAcceptedEpoch(p.base, manifest.epoch);
+
+    await stopLegacy({ p, env, log });
+    await atomicWrite(p.bin, binary, { mode: 0o755, sha256: digest });
+    await atomicWrite(p.config, JSON.stringify({ gateway_url: origin, host_id: hostId, token: hostToken, state_path: join(p.state, "sessions.json") }) + "\n", { mode: 0o600 });
+    log(`==> Configuration written to ${p.config}`);
+
+    await startService({ bin: p.bin, config: p.config, logs: p.logs, state: p.state, log, env });
+  });
+  await connectHarnesses({ bin: p.bin, config: p.config, log, env });
+  log("==> Done. This machine will appear under Hosts in the AgentCoor dashboard within a few seconds.");
+  return { bin: p.bin, config: p.config };
+}
+
+export const pidFile = (state) => join(state, "agent.pid");
+
+/** Is `pid` a running process executing one of `bins`? Linux: /proc/<pid>/exe; elsewhere: ps. */
+async function runsOurBinary(pid, bins) {
+  if (process.platform === "linux") {
+    const exe = await readlink(`/proc/${pid}/exe`).catch(() => null);
+    return !!exe && bins.some((b) => exe === b || exe === `${b} (deleted)`);
+  }
+  const r = spawnSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", env: childEnv() });
+  const cmd = (r.stdout || "").trim();
+  return r.status === 0 && bins.some((b) => cmd === b || cmd.startsWith(`${b} `));
+}
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+
+/**
+ * Does `pid` run exactly the binary now at `bin`? Linux: /proc/<pid>/exe must equal
+ * `bin` (a process still mapping a replaced binary shows "<bin> (deleted)" and fails).
+ * Elsewhere: the ps command line starts with `bin`.
+ */
+export async function runsCurrentBinary(pid, bin, platform = process.platform) {
+  if (!Number.isSafeInteger(pid) || pid < 2) return false;
+  if (platform === "linux") {
+    const exe = await readlink(`/proc/${pid}/exe`).catch(() => null);
+    return !!exe && (exe === bin || exe === await realpath(bin).catch(() => null));
+  }
+  const cmd = capture("ps", ["-o", "command=", "-p", String(pid)]).stdout.trim();
+  return cmd === bin || cmd.startsWith(`${bin} `);
+}
+
+/** Stop a detached agent recorded in a pidfile, only after verifying the process runs our binary. */
+export async function stopPidfileAgent(pidPath, bins, log = () => {}) {
+  let fh;
+  try { fh = await open(pidPath, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0)); } catch { return false; }
+  let pid;
+  try {
+    const st = await fh.stat();
+    if (!st.isFile() || st.size > 32 || (typeof process.getuid === "function" && st.uid !== process.getuid())) return false;
+    const text = (await fh.readFile("utf8")).trim();
+    if (!/^[1-9][0-9]{0,9}$/.test(text)) return false;
+    pid = Number(text);
+  } finally { await fh.close(); }
+  let stopped = false;
+  if (pid !== process.pid && await runsOurBinary(pid, bins)) {
+    try { process.kill(pid, "SIGTERM"); stopped = true; } catch {}
+    // Wait for it to exit so the new agent never runs alongside the old one.
+    for (let i = 0; stopped && i < 50 && alive(pid); i++) await sleepMs(100);
+    if (stopped && alive(pid) && await runsOurBinary(pid, bins)) { try { process.kill(pid, "SIGKILL"); } catch {} }
+    if (stopped) log(`==> Stopped the earlier background agent (pid ${pid})`);
+  }
+  await unlink(pidPath).catch(() => {});
+  return stopped;
+}
+
+/**
+ * Earlier CLI builds installed the agent under ~/.agentcoor. Session state is NOT
+ * migrated (a planted state file could make the agent run commands on restore):
+ * the old detached agent is stopped (pidfile, verified to be our binary), the old
+ * binary and its config (which holds a host token) are removed, and the user is
+ * told to reconnect. Only the default ~/.agentcoor is considered, never $AGENTCOOR_HOME.
+ */
+export async function stopLegacy({ p, env, log = () => {} }) {
+  await stopPidfileAgent(pidFile(p.state), [p.bin], log);
+  const old = join(env.HOME || homedir(), ".agentcoor");
+  if (old === p.base) return false;
+  const st = await lstat(old).catch(() => null);
+  if (!st || !st.isDirectory() || (typeof process.getuid === "function" && st.uid !== process.getuid())) return false;
+  const oldBin = join(old, "bin", "agentcoor-agent");
+  if (!(await lstat(oldBin).catch(() => null))) return false;
+  await stopPidfileAgent(join(old, "state", "agent.pid"), [oldBin], log);
+  for (const f of [oldBin, join(old, "agent.json")]) await unlink(f).catch(() => {});
+  await rmdir(join(old, "bin")).catch(() => {});
+  log(`==> Removed the earlier agent install in ${old}. Its session state was not carried over: reconnect any sessions you need from the dashboard.`);
+  return true;
+}
+
+/**
+ * Install and (re)start the agent service, then prove the new binary is what runs.
+ * An upgrade must replace a running old agent: systemd `enable --now` is a no-op for
+ * an active unit, so this uses `restart`; launchd jobs are booted out, bootstrapped
+ * and kickstarted (-k kills any instance). Afterwards the service's main PID must be
+ * executing the freshly installed `bin`, or the install fails.
+ * `ops` (platform, run, capture, runsBinary, sleep) exists for tests.
+ */
+export async function startService({ bin, config, logs, state, log = () => {}, env = process.env, service = AGENT_SERVICE, system = false }, ops = {}) {
+  const o = { platform: process.platform, run, capture, runsBinary: runsCurrentBinary, sleep: sleepMs, has, tries: 20, systemUnitDir: SYSTEM_UNIT_DIR, ...ops };
+  const ok = (cmd, args) => o.run(cmd, args).status === 0;
+  const home = env.HOME || homedir();
+  const waitFor = async (check, what) => {
+    for (let i = 0; i < o.tries; i++) { if (await check()) return; await o.sleep(250); }
+    throw new Error(`${what}: the new agent binary is not the one running; check the agent logs in ${logs}`);
+  };
+  if (o.platform === "darwin") {
+    const label = service.label;
+    const plist = join(home, "Library", "LaunchAgents", `${label}.plist`);
+    await ensureUserDir(dirname(plist));
+    await atomicWrite(plist, launchdPlist({ bin, config, logs, service }), { mode: 0o644 });
+    const target = `gui/${process.getuid()}/${label}`;
+    const launchdPid = () => { const r = o.capture("launchctl", ["print", target]); const m = r.status === 0 && /^\s*pid = (\d+)\s*$/m.exec(r.stdout); return m ? Number(m[1]) : 0; };
+    const oldPid = launchdPid();
+    o.run("launchctl", ["bootout", target]);
+    await waitFor(() => o.capture("launchctl", ["print", target]).status !== 0, "launchctl bootout did not finish");
+    let booted = false;
+    for (let i = 0; i < 5 && !booted; i++) { booted = ok("launchctl", ["bootstrap", `gui/${process.getuid()}`, plist]); if (!booted) await o.sleep(500); }
+    if (!booted) throw new Error("launchctl bootstrap failed");
+    ok("launchctl", ["kickstart", "-k", target]);
+    await waitFor(async () => { const pid = launchdPid(); return pid > 0 && pid !== oldPid && await o.runsBinary(pid, bin, "darwin"); }, "launchd restart");
+    log(`==> Agent restarted (launchd: ${label}, pid ${launchdPid()})`);
+    return;
+  }
+  // Root (sudo) on Linux: a system unit, so the worker survives reboot with no
+  // user session. systemd must be running (show-environment answers).
+  if (system && o.has("systemctl") && ok("systemctl", ["show-environment"])) {
+    const svc = `${service.unit}.service`;
+    const unit = join(o.systemUnitDir, svc);
+    await atomicWrite(unit, systemdSystemUnit({ bin, config, service }), { mode: 0o644 });
+    if (!ok("systemctl", ["daemon-reload"])) throw new Error("systemctl daemon-reload failed");
+    if (!ok("systemctl", ["enable", svc])) throw new Error(`systemctl enable ${svc} failed`);
+    if (!ok("systemctl", ["restart", svc])) throw new Error(`systemctl restart ${svc} failed; see journalctl -u ${svc}`);
+    let pid = 0;
+    await waitFor(async () => {
+      if (!ok("systemctl", ["is-active", "--quiet", svc])) return false;
+      pid = Number(o.capture("systemctl", ["show", "-p", "MainPID", "--value", svc]).stdout.trim()) || 0;
+      return pid > 1 && await o.runsBinary(pid, bin, "linux");
+    }, `systemctl restart ${svc}`);
+    log(`==> Worker restarted (systemd system unit ${unit}, pid ${pid}); it starts at boot`);
+    return;
+  }
+  if (system) log(`warning: running as root but systemd is not available; the worker runs detached and will NOT survive a reboot. Start it from your init system: ${[bin, ...service.extra, service.flag, config].join(" ")}`);
+  if (!system && o.has("systemctl") && ok("systemctl", ["--user", "show-environment"])) {
+    const svc = `${service.unit}.service`;
+    const unit = join(env.XDG_CONFIG_HOME || join(home, ".config"), "systemd", "user", svc);
+    await ensureUserDir(dirname(unit));
+    await atomicWrite(unit, systemdUnit({ bin, config, service }), { mode: 0o644 });
+    if (!ok("systemctl", ["--user", "daemon-reload"])) throw new Error("systemctl --user daemon-reload failed");
+    if (!ok("systemctl", ["--user", "enable", svc])) throw new Error("systemctl --user enable failed");
+    if (!ok("systemctl", ["--user", "restart", svc])) throw new Error("systemctl --user restart failed");
+    let pid = 0;
+    await waitFor(async () => {
+      if (!ok("systemctl", ["--user", "is-active", "--quiet", svc])) return false;
+      pid = Number(o.capture("systemctl", ["--user", "show", "-p", "MainPID", "--value", svc]).stdout.trim()) || 0;
+      return pid > 1 && await o.runsBinary(pid, bin, "linux");
+    }, "systemctl --user restart");
+    log(`==> Agent restarted (systemd --user: ${service.unit}, pid ${pid})`);
+    if (o.has("loginctl")) o.run("loginctl", ["enable-linger", userInfo().username]);
+    return;
+  }
+  // No service manager: stop the earlier detached process of this service (pidfile,
+  // verified to run our binary, waited for) so two copies never share one credential
+  // (`list-agent` then `list-tools` reuse the worker); then start the new one and
+  // check it is running the new binary.
+  const pidPath = service === AGENT_SERVICE ? pidFile(state) : join(state, `${service.log}.pid`);
+  await (o.stopPidfile || stopPidfileAgent)(pidPath, [bin], log);
+  const out = await open(join(logs, `${service.log}.log`), constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW || 0), 0o600);
+  const child = (o.spawn || spawn)(bin, [...service.extra, service.flag, config], { detached: true, stdio: ["ignore", out.fd, out.fd], env: childEnv(env) });
+  child.unref();
+  await out.close();
+  await atomicWrite(pidPath, `${child.pid}\n`, { mode: 0o600 });
+  await o.sleep(500);
+  if (!(await o.runsBinary(child.pid, bin, o.platform))) throw new Error(`the agent exited right after starting; see ${join(logs, `${service.log}.log`)}`);
+  log(`==> Agent started in the background (pid ${child.pid}; no service manager found, re-run after reboot)`);
+}
+
+export const HOOK_EVENTS = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Notification", "Stop", "SessionEnd", "PermissionRequest", "SubagentStart", "SubagentStop"];
+
+const isOurHook = (h) => typeof h?.command === "string" && /(^|\/)agentcoor-agent$/.test(h.command) && Array.isArray(h.args) && h.args.includes("-report-claude-hook");
+
+/** Replace every AgentCoor lifecycle hook (from any install location) with exactly one per event. */
+export function mergeClaudeHooks(text, { bin, config }) {
+  const data = parseJsonObject(text, "~/.claude/settings.json");
+  if (data.hooks !== undefined && (typeof data.hooks !== "object" || Array.isArray(data.hooks) || data.hooks === null)) throw new Error("~/.claude/settings.json has an unexpected \"hooks\" value; nothing was changed");
+  const hooks = (data.hooks ||= {});
+  for (const ev of HOOK_EVENTS) {
+    if (hooks[ev] !== undefined && !Array.isArray(hooks[ev])) throw new Error(`~/.claude/settings.json has a non-array "hooks.${ev}" value; nothing was changed`);
+    const entries = hooks[ev] || [];
+    const cleaned = [];
+    for (const e of entries) {
+      if (!Array.isArray(e?.hooks)) { cleaned.push(e); continue; }
+      const rest = e.hooks.filter((h) => !isOurHook(h));
+      if (rest.length) cleaned.push(rest.length === e.hooks.length ? e : { ...e, hooks: rest });
+    }
+    cleaned.push({ hooks: [{ type: "command", command: bin, args: ["-config", config, "-report-claude-hook"], timeout: 5 }] });
+    hooks[ev] = cleaned;
+  }
+  return JSON.stringify(data, null, 2) + "\n";
+}
+
+export const codexMcpToml = ({ bin, config }) => `
+# Added by agentcoor connect
+[mcp_servers.agentcoor]
+command = ${tomlString(bin)}
+args = ["-config", ${tomlString(config)}, "-mcp"]
+`;
+
+/** Optional: connect installed harnesses, mirroring install.sh. Failures never abort the install and never clobber a file. */
+async function connectHarnesses({ bin, config, log, env }) {
+  const home = env.HOME || homedir();
+  if (has("claude")) {
+    run("claude", ["mcp", "remove", "--scope", "user", "agentcoor"]);
+    if (run("claude", ["mcp", "add", "--scope", "user", "agentcoor", "--", bin, "-config", config, "-mcp"]).status === 0) log("==> Claude Code: AgentCoor tools added");
+    try {
+      await updateFile(join(home, ".claude", "settings.json"), (t) => mergeClaudeHooks(t, { bin, config }));
+      log("==> Claude Code: lifecycle hooks installed");
+    } catch (e) { log(`==> Claude Code: hooks not installed (${e.message})`); }
+  }
+  if (has("codex")) {
+    try {
+      const r = await updateFile(join(home, ".codex", "config.toml"), (t) => replaceTomlTables(t, ["mcp_servers.agentcoor"], codexMcpToml({ bin, config })));
+      log(r ? "==> Codex: AgentCoor tools added" : "==> Codex: already configured");
+    } catch (e) { log(`==> Codex: not configured (${e.message})`); }
+  }
+}
+

package/src/fsx.js

@@ -0,0 +1,125 @@
+// Filesystem helpers that refuse to follow attacker-controlled links and never
+// leave a predictable temporary file behind.
+import { open, mkdir, lstat, stat, chmod, rename, unlink, readFile, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomBytes, createHash } from "node:crypto";
+import { dirname, basename, join } from "node:path";
+
+const uid = () => (typeof process.getuid === "function" ? process.getuid() : null);
+const CTRL = /[\u0000-\u001f\u007f]/;
+
+/** Reject paths with control characters (newlines would inject into service files). */
+export function assertSafePath(p, what = "path") {
+  if (typeof p !== "string" || !p || CTRL.test(p)) throw new Error(`refusing to use a ${what} containing control characters: ${JSON.stringify(p)}`);
+  return p;
+}
+
+function checkOwnedDir(st, p) {
+  if (st.isSymbolicLink()) throw new Error(`refusing to use ${p}: it is a symbolic link`);
+  if (!st.isDirectory()) throw new Error(`refusing to use ${p}: not a directory`);
+  if (uid() !== null && st.uid !== uid()) throw new Error(`refusing to use ${p}: owned by uid ${st.uid}, not ${uid()}`);
+}
+
+/**
+ * Create (or adopt) a private directory: it must be a real directory owned by
+ * the current user, not a symlink, and ends up mode 0700 even if it existed.
+ */
+export async function ensurePrivateDir(p) {
+  assertSafePath(p, "directory");
+  await mkdir(p, { recursive: true, mode: 0o700 });
+  checkOwnedDir(await lstat(p), p);
+  await chmod(p, 0o700);
+  return p;
+}
+
+/** Ensure a directory we write into but do not own the policy of (e.g. ~/.claude): owned by us, not group/world writable. */
+export async function ensureUserDir(p) {
+  assertSafePath(p, "directory");
+  await mkdir(p, { recursive: true, mode: 0o700 });
+  const st = await stat(p); // a symlinked dotfile directory is acceptable if it resolves to our own directory
+  if (!st.isDirectory()) throw new Error(`refusing to use ${p}: not a directory`);
+  if (uid() !== null && st.uid !== uid()) throw new Error(`refusing to use ${p}: owned by uid ${st.uid}, not ${uid()}`);
+  if (st.mode & 0o022) throw new Error(`refusing to write into ${p}: it is group- or world-writable`);
+  return p;
+}
+
+/** Read a file; only a missing file is treated as absent (returns null). Every other error propagates. */
+export async function readIfExists(p) {
+  try { return await readFile(p, "utf8"); } catch (e) { if (e.code === "ENOENT") return null; throw e; }
+}
+
+/**
+ * Inode, mtime, size and content of a regular file, read through one
+ * O_NOFOLLOW descriptor; null when missing. Used to detect concurrent edits.
+ */
+export async function snapshot(p) {
+  let fh;
+  try { fh = await open(p, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0)); }
+  catch (e) { if (e.code === "ENOENT") return null; throw e; }
+  try {
+    const st = await fh.stat();
+    if (!st.isFile()) throw new Error(`refusing to edit ${p}: not a regular file`);
+    if (st.size > 16 * 1024 * 1024) throw new Error(`refusing to edit ${p}: too large`);
+    const text = await fh.readFile("utf8");
+    return { dev: st.dev, ino: st.ino, mtimeMs: st.mtimeMs, size: st.size, text };
+  } finally { await fh.close(); }
+}
+
+export function sameSnapshot(a, b) {
+  if (!a || !b) return a === b;
+  return a.dev === b.dev && a.ino === b.ino && a.mtimeMs === b.mtimeMs && a.size === b.size && a.text === b.text;
+}
+
+/** Open a brand-new file exclusively without following links. */
+export async function openExclusive(p, mode) {
+  return open(p, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), mode);
+}
+
+const randName = (target) => join(dirname(target), `.${basename(target)}.${randomBytes(12).toString("hex")}.tmp`);
+
+/**
+ * Atomically replace `target` with `data`: random O_EXCL|O_NOFOLLOW temporary in
+ * the same directory, write, re-read through the same descriptor and hash the
+ * exact bytes on disk (compared against `sha256` when given), fsync, rename,
+ * fsync the directory. Returns the hex SHA-256 of what was written.
+ */
+export async function atomicWrite(target, data, { mode = 0o600, sha256 } = {}) {
+  assertSafePath(target, "file path");
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data));
+  const tmp = randName(target);
+  const fh = await openExclusive(tmp, mode);
+  let ok = false;
+  try {
+    await fh.writeFile(buf);
+    await fh.chmod(mode);
+    const back = Buffer.alloc(buf.length);
+    const { bytesRead } = await fh.read(back, 0, buf.length, 0);
+    const got = createHash("sha256").update(back.subarray(0, bytesRead)).digest("hex");
+    const want = sha256 || createHash("sha256").update(buf).digest("hex");
+    if (bytesRead !== buf.length || got !== want) throw new Error(`integrity check failed while writing ${target}`);
+    await fh.sync();
+    await fh.close();
+    const cur = await lstat(target).catch((e) => { if (e.code === "ENOENT") return null; throw e; });
+    if (cur && cur.isDirectory()) throw new Error(`refusing to replace directory ${target}`);
+    await rename(tmp, target);
+    ok = true;
+    const dh = await open(dirname(target), "r").catch(() => null);
+    if (dh) { await dh.sync().catch(() => {}); await dh.close(); }
+    return got;
+  } finally {
+    if (!ok) { await fh.close().catch(() => {}); await unlink(tmp).catch(() => {}); }
+  }
+}
+
+/** Write a 0600 backup copy of `content` next to `target` under an exclusive random name. */
+export async function writeBackup(target, content, now = new Date()) {
+  const p = `${target}.agentcoor-backup-${now.toISOString().replace(/[:.]/g, "-")}-${randomBytes(6).toString("hex")}`;
+  const fh = await openExclusive(p, 0o600);
+  try { await fh.writeFile(content); await fh.sync(); } finally { await fh.close(); }
+  return p;
+}
+
+/** Resolve an existing harness config file through dotfile symlinks; a missing file stays as given. */
+export async function resolveTarget(p) {
+  try { return await realpath(p); } catch (e) { if (e.code === "ENOENT") return p; throw e; }
+}

package/src/harness.js

@@ -0,0 +1,138 @@
+import { access } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { baseUrls, homeDir } from "./config.js";
+import { writeBackup, atomicWrite, ensurePrivateDir, ensureUserDir, resolveTarget, snapshot, sameSnapshot } from "./fsx.js";
+import { replaceTomlTables, tomlString } from "./toml.js";
+
+export const HARNESSES = ["claude", "codex", "openclaude", "cursor", "env"];
+export const TIERS = ["agentcoor-auto", "agentcoor-fast", "agentcoor-compute"];
+
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+const home = (env) => env.HOME || homedir();
+
+export function envExports(origin, key) {
+  const u = baseUrls(origin);
+  return [
+    `export ANTHROPIC_BASE_URL=${shq(u.anthropic)}`,
+    `export ANTHROPIC_API_KEY=${shq(key)}`,
+    `export OPENAI_BASE_URL=${shq(u.openai)}`,
+    `export OPENAI_API_KEY=${shq(key)}`,
+    `export AGENTCOOR_API_KEY=${shq(key)}`,
+  ].join("\n") + "\n";
+}
+
+export const CODEX_MODEL_TABLES = ["model_providers.agentcoor", "profiles.agentcoor"];
+
+export function codexToml(origin) {
+  const u = baseUrls(origin);
+  return `
+# Added by agentcoor setup codex. Use with: codex --profile agentcoor
+[model_providers.agentcoor]
+name = "AgentCoor"
+base_url = ${tomlString(u.openai)}
+env_key = "AGENTCOOR_API_KEY"
+wire_api = "chat"
+
+[profiles.agentcoor]
+model_provider = "agentcoor"
+model = "agentcoor-auto"
+`;
+}
+
+/**
+ * Build the plan for a harness: text to print, and optionally a file to write.
+ * `displayKey` is what appears in printed text (masked unless --show-key); `key` is what is written to files.
+ */
+export function plan(harness, { origin, key, displayKey, env = process.env }) {
+  const u = baseUrls(origin);
+  switch (harness) {
+    case "claude":
+      return {
+        print: `# Claude Code\nexport ANTHROPIC_BASE_URL=${u.anthropic}\nexport ANTHROPIC_API_KEY=${displayKey}\n\n` +
+          `Claude model names map automatically: opus -> agentcoor-fast, haiku -> agentcoor-compute, others -> agentcoor-auto.\n` +
+          `With --write, these are stored in the "env" block of ~/.claude/settings.json.\n`,
+        file: join(home(env), ".claude", "settings.json"),
+        merge: (text) => {
+          const data = parseJsonObject(text, "~/.claude/settings.json");
+          if (data.env !== undefined && (data.env === null || typeof data.env !== "object" || Array.isArray(data.env))) throw new Error('~/.claude/settings.json has a non-object "env" value; nothing was changed');
+          data.env = { ...(data.env || {}), ANTHROPIC_BASE_URL: u.anthropic, ANTHROPIC_API_KEY: key };
+          return JSON.stringify(data, null, 2) + "\n";
+        },
+      };
+    case "openclaude":
+      return {
+        print: `# OpenClaude\nexport ANTHROPIC_BASE_URL=${u.anthropic}\nexport ANTHROPIC_API_KEY=${displayKey}\n\n` +
+          `With --write, exports are saved to ~/.agentcoor/env.sh; add "source ~/.agentcoor/env.sh" to your shell profile.\n`,
+        file: join(homeDir(env), "env.sh"), private: true,
+        merge: () => envExports(origin, key),
+      };
+    case "env":
+      return {
+        print: envExports(origin, displayKey).replaceAll(`'${displayKey}'`, displayKey) +
+          `\nWith --write, these are saved to ~/.agentcoor/env.sh; add "source ~/.agentcoor/env.sh" to your shell profile.\n`,
+        file: join(homeDir(env), "env.sh"), private: true,
+        merge: () => envExports(origin, key),
+      };
+    case "codex":
+      return {
+        print: `# Codex (~/.codex/config.toml)${codexToml(origin)}\nThen: export AGENTCOOR_API_KEY=${displayKey}\n      codex --profile agentcoor\n`,
+        file: join(home(env), ".codex", "config.toml"),
+        merge: (text) => replaceTomlTables(text, CODEX_MODEL_TABLES, codexToml(origin)),
+      };
+    case "cursor":
+      return {
+        print: `# Cursor\nSettings -> Models -> API Keys:\n  OpenAI API Key:           ${displayKey}\n  Override OpenAI Base URL: ${u.openai}\n` +
+          `Then add a custom model named one of: ${TIERS.join(", ")}.\n(Cursor stores this in its own settings; --write is not supported.)\n`,
+      };
+    default:
+      throw new Error(`unknown harness "${harness}" (choose: ${HARNESSES.join(", ")})`);
+  }
+}
+
+/** Parse a JSON object; an empty/missing file is {}, anything malformed aborts (never silently overwritten). */
+export function parseJsonObject(text, label) {
+  if (text === null || text === undefined || text.trim() === "") return {};
+  let data;
+  try { data = JSON.parse(text); } catch (e) { throw new Error(`${label} is not valid JSON (${e.message}); fix or move it, then retry. Nothing was changed.`); }
+  if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error(`${label} is not a JSON object; nothing was changed`);
+  return data;
+}
+
+/**
+ * Read-modify-write a config file safely: only ENOENT counts as empty, `merge`
+ * may throw to abort (malformed input), the previous content is backed up to an
+ * exclusive random 0600 file, and the new content replaces it atomically.
+ * Immediately before replacing, the file's inode, mtime and content are compared
+ * with what was read; if another process changed it in between, the merge is
+ * redone on the fresh content (up to `retries` times) and then aborted. This
+ * narrows, but does not close, the window: an edit landing after the final
+ * comparison and before the rename can still be overwritten (see docs/SECURITY.md,
+ * known limitations); the backup file keeps the previous content.
+ * Returns {path, backup} or null when nothing changed.
+ */
+export async function updateFile(file, merge, { privateDir = false, now = new Date(), retries = 3, beforeReplace } = {}) {
+  if (privateDir) await ensurePrivateDir(dirname(file)); else await ensureUserDir(dirname(file));
+  const target = await resolveTarget(file);
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const before = await snapshot(target);
+    const existing = before ? before.text : null;
+    const next = merge(existing ?? "");
+    if (next === null || next === existing) return null;
+    if (beforeReplace) await beforeReplace(attempt);
+    if (!sameSnapshot(before, await snapshot(target))) continue;
+    const backup = existing ? await writeBackup(target, existing, now) : null;
+    if (!sameSnapshot(before, await snapshot(target))) continue;
+    await atomicWrite(target, next, { mode: 0o600 });
+    return { path: target, backup };
+  }
+  throw new Error(`${target} kept changing while it was being updated; nothing was changed. Retry when other tools are idle.`);
+}
+
+/** Write a plan's file, backing up any existing file first. Returns {path, backup} or null if nothing changed. */
+export async function applyPlan(p, now = new Date()) {
+  if (!p.file) throw new Error("this harness has no config file to write; follow the printed steps");
+  return updateFile(p.file, p.merge, { privateDir: !!p.private, now });
+}
+
+export async function exists(p) { try { await access(p); return true; } catch { return false; } }