@staix/agent-research 0.0.0-stage → 0.1.0

package/src/setup.ts

@@ -0,0 +1,296 @@
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, realpathSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { assertWritable, plain, readBytesBounded, readTextBounded, sha256, writeAtomic } from "./study.ts";
+
+export const SETUP_TARGETS = ["claude", "codex", "kimi", "pi", "qwen", "jcode", "agy"] as const;
+type AgentSetupTarget = typeof SETUP_TARGETS[number];
+export type SetupTarget = AgentSetupTarget | "console";
+export type SetupMode = "dry-run" | "apply" | "undo";
+export interface McpEntry { command: string; args: string[] }
+export interface ConsoleManifest { api: 1; tool: "ares"; module: string; sha256: string }
+type SetupEntry = McpEntry | ConsoleManifest;
+interface Host { target: SetupTarget; file: string; key: string; format: "json" | "toml" | "manifest" }
+export interface SetupAction { target: SetupTarget; file: string; entry: string; receipt: string; lock: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "none" | "refused"; receiptChange: "add" | "replace" | "remove" | "none"; reason?: string }
+export interface SetupReport { mode: SetupMode; applied: boolean; root: string; entry: McpEntry; actions: SetupAction[]; notes: string[]; console?: ConsoleManifest }
+interface Receipt { v: 1; target: SetupTarget; file: string; existed: boolean; keyExisted: boolean; priorPresent: boolean; prior?: unknown; priorToml?: string; installed: SetupEntry }
+interface Plan { host: Host; action: SetupAction; before: string | null; after: string | null; receiptBefore: string | null; receiptAfter: string | null }
+export const SETUP_CONFIG_BYTES = 4 * 1024 * 1024, SETUP_RECEIPT_BYTES = 8 * 1024 * 1024;
+const OWN_ROOT = fileURLToPath(new URL("..", import.meta.url));
+class SetupError extends Error {}
+function fail(message: string, nextStep = "correct the config or restore its setup receipt, then rerun ares setup"): never { throw new SetupError(`setup: ${message}; ${nextStep}`); }
+function failureReason(error: unknown): string {
+  return error instanceof SetupError ? error.message : `setup: ${error instanceof Error ? error.message : "file operation failed"}; check file permissions and the setup receipt, then rerun ares setup`;
+}
+function setupLockRefusal(file: string): never {
+  fail(`target is locked by another setup: ${file}`, `if no ares setup is running, remove ${file} and rerun ares setup`);
+}
+function absolute(value: string, label: string): string {
+  if (!isAbsolute(value) || value.includes("\0")) fail(`${label} must be an absolute path`, label === "--root" ? "pass --root ABS for an existing agent-research release" : `set ${label} to an absolute path and rerun ares setup`);
+  return resolve(value);
+}
+/** Links are always refused. Ownership checks protect mutable config/receipts; release reads may be administrator-owned. */
+function guard(file: string, owned = true): void {
+  const parts: string[] = []; for (let current = resolve(file); ; current = dirname(current)) { parts.unshift(current); if (current === dirname(current)) break; }
+  for (const part of parts) {
+    let info;
+    try { info = lstatSync(part); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw error; }
+    if (info.isSymbolicLink()) fail("links are refused in config and receipt paths");
+    if (part === resolve(file)) {
+      if (!info.isFile()) fail("config or receipt is not a regular file");
+      if (owned && info.uid !== process.getuid!()) fail("config or receipt is owned by another user");
+    } else {
+      if (!info.isDirectory()) fail("config or receipt parent is not a directory");
+      if (owned && info.uid !== 0 && info.uid !== process.getuid!()) fail("config or receipt parent is owned by another user");
+    }
+  }
+}
+function read(file: string, max: number, owned = true): string | null {
+  guard(file, owned);
+  try { return readTextBounded(file, max, { noFollow: true, ...(owned ? { uid: process.getuid!() } : {}) }); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+}
+function write(file: string, value: string | null, max: number, privateFile = false): void {
+  guard(file);
+  if (value === null) { unlinkSync(file); return; }
+  assertWritable(value, max, "setup output");
+  let mode = 0o600;
+  try { if (!privateFile) mode = lstatSync(file).mode & 0o777; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  if (privateFile) privateDirectory(dirname(file), true);
+  guard(file); writeAtomic(file, value, max, mode);
+}
+function record(value: unknown): Record<string, unknown> { if (!plain(value)) fail("config must contain an object"); return value; }
+function document(host: Host, source: string | null): Record<string, unknown> {
+  if (source === null) return {};
+  try { return record(host.format === "toml" ? Bun.TOML.parse(source) : JSON.parse(source)); }
+  catch { fail(`invalid ${host.format.toUpperCase()}; fix ${host.file} before applying setup`); }
+}
+function entry(host: Host, source: string | null): unknown { if (host.format === "manifest") return source === null ? undefined : document(host, source); const doc = document(host, source); return doc[host.key] === undefined ? undefined : record(doc[host.key]).ares; }
+function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<AgentSetupTarget, Host> {
+  const home = absolute(env.HOME?.trim() || homedir(), "HOME");
+  const dir = (key: string, fallback: string) => absolute(env[key]?.trim() || join(home, fallback), key);
+  const json = (target: AgentSetupTarget, file: string, key = "mcpServers"): Host => ({ target, file, format: "json", key });
+  return {
+    claude: json("claude", env.CLAUDE_CONFIG_DIR?.trim() ? join(dir("CLAUDE_CONFIG_DIR", ".claude"), ".claude.json") : join(home, ".claude.json")),
+    codex: { target: "codex", file: join(dir("CODEX_HOME", ".codex"), "config.toml"), format: "toml", key: "mcp_servers" },
+    kimi: json("kimi", join(dir("KIMI_CODE_HOME", ".kimi-code"), "mcp.json")),
+    pi: json("pi", join(dir("PI_CODING_AGENT_DIR", ".pi/agent"), "mcp.json")),
+    qwen: json("qwen", join(dir("QWEN_HOME", ".qwen"), "settings.json")),
+    jcode: json("jcode", join(dir("JCODE_HOME", ".jcode"), "mcp.json"), "servers"),
+    agy: json("agy", join(absolute(cwd, "cwd"), ".agents", "mcp_config.json")),
+  };
+}
+/** Header/key handling follows vmem setup; Bun decodes quoted keys instead of a second TOML decoder. */
+function tomlKey(raw: string): string[] | undefined {
+  const pattern = /\s*([A-Za-z0-9_-]+|"(?:[^"\\]|\\.)*"|'[^']*')\s*(?:\.|$)/y, parts: string[] = [];
+  while (pattern.lastIndex < raw.length) {
+    const match = pattern.exec(raw); if (!match) return undefined;
+    const token = match[1]!;
+    try { parts.push(token.startsWith('"') || token.startsWith("'") ? record(Bun.TOML.parse(`key = ${token}`)).key as string : token); } catch { return undefined; }
+  }
+  return parts;
+}
+function header(line: string): string | undefined {
+  line = line.replace(/\r?\n$/, "");
+  const match = /^\s*(\[\[?)/.exec(line); if (!match) return undefined;
+  let quote = "", index = match[0].length;
+  for (; index < line.length; index++) {
+    const char = line[index]!;
+    if (quote) { if (char === "\\" && quote === '"') index++; else if (char === quote) quote = ""; }
+    else if (char === '"' || char === "'") quote = char;
+    else if (char === "]") break;
+  }
+  const close = match[1] === "[[" ? "]]" : "]";
+  return !quote && line.startsWith(close, index) && /^\s*(?:#.*)?$/.test(line.slice(index + close.length)) ? line.slice(match[0].length, index).trim() : undefined;
+}
+/** Multiline strings may contain apparent table headers; never treat those lines as config entries. */
+function spans(lines: string[]): [number, number][] {
+  const result: [number, number][] = [], comments: boolean[] = []; let start = -1, quote = "";
+  for (let i = 0; i <= lines.length; i++) {
+    const line = lines[i], name = line !== undefined && !quote ? header(line) : undefined;
+    comments[i] = !quote && line?.trim().startsWith("#") === true;
+    if (i === lines.length || name !== undefined) {
+      if (start >= 0) { let stop = i; while (stop > start && (!lines[stop - 1]!.trim() || comments[stop - 1])) stop--; result.push([start, stop]); start = -1; }
+      const key = name === undefined ? undefined : tomlKey(name); if (key?.[0] === "mcp_servers" && key[1] === "ares") start = i;
+    }
+    for (let pos = 0; line !== undefined && pos < line.length; pos++) {
+      const char = line[pos]!;
+      if (!quote && char === "#") break;
+      if (quote && char === "\\" && quote[0] === '"') { pos++; continue; }
+      if (quote.length === 3 && line.startsWith(quote, pos)) { const end = quote[0]!; while (line[pos + 1] === end) pos++; quote = ""; }
+      else if (quote.length === 1 && char === quote) quote = "";
+      else if (!quote && (char === '"' || char === "'")) { quote = line.startsWith(char.repeat(3), pos) ? char.repeat(3) : char; pos += quote.length - 1; }
+    }
+  }
+  return result;
+}
+const linesOf = (source: string): string[] => source.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+function priorToml(source: string | null): string | undefined {
+  const lines = linesOf(source ?? ""), owned = spans(lines);
+  return owned.length ? owned.map(([start, stop]) => lines.slice(start, stop).join("")).join("") : undefined;
+}
+function put(host: Host, source: string | null, value: unknown, rawToml?: string, keepKey = false): string {
+  if (host.format === "manifest") return JSON.stringify(value ?? {}, null, 2) + "\n";
+  if (host.format === "json") {
+    const doc = document(host, source), servers = { ...record(doc[host.key] ?? {}) };
+    if (value === undefined) delete servers.ares; else servers.ares = value;
+    if (Object.keys(servers).length || keepKey) doc[host.key] = servers; else delete doc[host.key];
+    return JSON.stringify(doc, null, source && /\n(\t| +)"/.exec(source)?.[1] || "  ") + "\n";
+  }
+  const newline = source?.includes("\r\n") ? "\r\n" : "\n", lines = linesOf(source ?? ""), owned = spans(lines);
+  let block = rawToml ?? "";
+  if (value !== undefined && rawToml === undefined) {
+    const target = record(value);
+    block = `[mcp_servers.ares]${newline}command = ${JSON.stringify(target.command)}${newline}args = ${JSON.stringify(target.args)}${newline}`;
+  }
+  if (owned.length) {
+    for (const [start, stop] of [...owned].reverse()) lines.splice(start, stop - start);
+    lines.splice(owned[0]![0], 0, block);
+  } else if (block) {
+    const prefix = (source ?? "").endsWith("\n") || !source ? "" : newline;
+    lines.push(prefix + (source ? newline : "") + block);
+  }
+  const output = lines.join("");
+  try { const parsed = document(host, output); if (!isDeepStrictEqual(parsed.mcp_servers === undefined ? undefined : record(parsed.mcp_servers).ares, rawToml === undefined ? value : entry(host, rawToml))) throw new Error(); }
+  catch { fail("TOML entry cannot be edited safely; convert inline/dotted ares settings to [mcp_servers.ares] tables first"); }
+  return output;
+}
+function install(root: string): string {
+  const requested = absolute(root, "--root");
+  let location: string;
+  try { location = realpathSync(requested); } catch { fail("install root is unreadable or missing", "pass --root ABS for an existing agent-research release"); }
+  const source = read(join(location, "package.json"), 65_536, false);
+  let pkg: unknown; try { pkg = source === null ? null : JSON.parse(source); } catch { fail("install root package.json is not valid JSON", "select or reinstall an intact agent-research release root"); }
+  if (!plain(pkg) || pkg.name !== "@staix/agent-research" || typeof pkg.version !== "string") fail("--root is not an agent-research installation", "select a release root containing package.json and bin/ares.js");
+  const bootstrap = join(location, "bin", "ares.js"); guard(bootstrap, false);
+  try { if (!lstatSync(bootstrap).isFile()) throw new Error(); } catch { fail("install root has no regular bin/ares.js", "select or reinstall an intact agent-research release root"); }
+  return location;
+}
+function validInstalled(host: Host, value: unknown): boolean {
+  if (!plain(value)) return false;
+  return host.format === "manifest"
+    ? value.api === 1 && value.tool === "ares" && typeof value.module === "string" && isAbsolute(value.module) && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256)
+    : typeof value.command === "string" && Array.isArray(value.args) && value.args.every(arg => typeof arg === "string");
+}
+function receipt(source: string | null, host: Host): Receipt | undefined {
+  if (source === null) return undefined;
+  let raw: unknown; try { raw = JSON.parse(source); } catch { fail("receipt must be valid JSON"); }
+  if (!plain(raw) || raw.v !== 1 || raw.target !== host.target || raw.file !== host.file || typeof raw.existed !== "boolean" || typeof raw.keyExisted !== "boolean" || typeof raw.priorPresent !== "boolean"
+    || !validInstalled(host, raw.installed)
+    || (raw.priorPresent && !Object.hasOwn(raw, "prior")) || (raw.priorToml !== undefined && typeof raw.priorToml !== "string")) fail("unsupported, malformed or foreign setup receipt");
+  return raw as unknown as Receipt;
+}
+function plan(host: Host, receiptPath: string, mode: SetupMode, desired: SetupEntry, ownsLock = false): Plan {
+  const action: SetupAction = { target: host.target, file: host.file, entry: host.format === "manifest" ? "console plugin manifest" : `${host.key}.ares`, receipt: receiptPath, lock: `${host.file}.ares-setup.lock`, change: "none", receiptChange: "none" };
+  if (host.format === "manifest") privateDirectory(dirname(host.file));
+  guard(action.lock);
+  if (!ownsLock && existsSync(action.lock)) setupLockRefusal(action.lock);
+  const before = read(host.file, SETUP_CONFIG_BYTES), receiptBefore = read(receiptPath, SETUP_RECEIPT_BYTES), prior = receipt(receiptBefore, host), current = entry(host, before);
+  const result: Plan = { host, action, before, after: before, receiptBefore, receiptAfter: receiptBefore };
+  if (mode === "undo") {
+    if (!prior) return result;
+    if (!isDeepStrictEqual(current, prior.installed)) fail("ares entry changed since apply; keep the user edit and reconcile the receipt manually before undo");
+    result.after = put(host, before, prior.priorPresent ? prior.prior : undefined, prior.priorToml, prior.keyExisted);
+    if (!prior.existed && isDeepStrictEqual(document(host, result.after), {})) result.after = null;
+    result.receiptAfter = null; action.change = prior.priorPresent ? "restore" : "remove"; action.receiptChange = "remove"; return result;
+  }
+  if (isDeepStrictEqual(current, desired) && (host.format !== "manifest" || !privateModesNeeded(host.file))) { action.change = "unchanged"; return result; }
+  const original = prior?.priorToml === undefined ? prior?.priorPresent ? prior.prior : undefined : entry(host, prior.priorToml);
+  if (prior && !isDeepStrictEqual(current, prior.installed) && !isDeepStrictEqual(current, original)) fail("ares entry changed since apply; reconcile it before replacing the installed root");
+  result.after = put(host, before, desired);
+  const saved: Receipt = prior ?? { v: 1, target: host.target, file: host.file, existed: before !== null, keyExisted: Object.hasOwn(document(host, before), host.key), priorPresent: current !== undefined,
+    ...(current === undefined ? {} : { prior: current }), ...(host.format === "toml" && current !== undefined ? { priorToml: priorToml(before) } : {}), installed: desired };
+  result.receiptAfter = JSON.stringify({ ...saved, installed: desired }, null, 2) + "\n";
+  assertWritable(result.receiptAfter, SETUP_RECEIPT_BYTES, "setup receipt");
+  assertWritable(result.after, SETUP_CONFIG_BYTES, "client config");
+  action.change = current === undefined ? "add" : "replace"; action.receiptChange = receiptBefore === null ? "add" : "replace"; return result;
+}
+/** Per-config, not per-family, so two family homes cannot race on the same client file. */
+function acquireSetupLock(file: string): () => void {
+  guard(file); mkdirSync(dirname(file), { recursive: true, mode: 0o700 }); guard(file);
+  let fd: number;
+  try { fd = openSync(file, "wx", 0o600); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") setupLockRefusal(file); throw error; }
+  return () => { try { closeSync(fd); } finally { unlinkSync(file); } };
+}
+/** Agent setup only. Console dispatch is deliberately separate for the plugin integration. */
+export function runSetup(target: string, mode: SetupMode, options: { env: NodeJS.ProcessEnv; cwd?: string; root?: string }): SetupReport {
+  if (target === "console") return consoleManifest(mode, options.env, options.root ?? OWN_ROOT, options.root !== undefined);
+  if (target !== "all" && !(SETUP_TARGETS as readonly string[]).includes(target)) fail("unknown target", `use ${SETUP_TARGETS.join("|")}|all|console`);
+  if (!["dry-run", "apply", "undo"].includes(mode)) fail("unsupported setup mode", "choose dry-run, apply or undo and rerun ares setup");
+  const env = options.env, root = install(options.root ?? OWN_ROOT), desired: McpEntry = { command: "bun", args: ["--smol", join(root, "bin", "ares.js"), "mcp"] };
+  const table = hosts(env, options.cwd ?? process.cwd()), family = absolute(env.AGENTHUB_HOME?.trim() || join(absolute(env.HOME?.trim() || homedir(), "HOME"), ".agenthub"), "AGENTHUB_HOME");
+  const targets = target === "all" ? SETUP_TARGETS.filter(name => name !== "agy") : [target as AgentSetupTarget], plans: Plan[] = [];
+  const report: SetupReport = { mode, applied: false, root, entry: desired, actions: [], notes: target === "all" ? ["all covers user-level clients; run ares setup agy from its workspace separately"] : [] };
+  for (const name of targets) {
+    const host = table[name], receiptPath = join(family, "research", "setup", `${name}-${sha256(host.file).slice(0, 16)}.json`);
+    try { const item = plan(host, receiptPath, mode, desired); plans.push(item); report.actions.push(item.action); }
+    catch (error) { report.actions.push({ target: name, file: host.file, entry: host.format === "manifest" ? "console plugin manifest" : `${host.key}.ares`, receipt: receiptPath, lock: `${host.file}.ares-setup.lock`, change: "refused", receiptChange: "none", reason: failureReason(error) }); }
+  }
+  return executePlans(plans, mode, desired, report);
+}
+function executePlans(plans: Plan[], mode: SetupMode, desired: SetupEntry, report: SetupReport): SetupReport {
+  if (mode === "dry-run" || report.actions.some(action => action.change === "refused")) return report;
+  for (let item of plans) {
+    if (["none", "unchanged"].includes(item.action.change)) continue;
+    let release: (() => void) | undefined;
+    try {
+      release = acquireSetupLock(item.action.lock);
+      const fresh = plan(item.host, item.action.receipt, mode, desired, true);
+      Object.assign(item.action, fresh.action); item = { ...fresh, action: item.action };
+      if (["none", "unchanged"].includes(item.action.change)) continue;
+      if (read(item.host.file, SETUP_CONFIG_BYTES) !== item.before || read(item.action.receipt, SETUP_RECEIPT_BYTES) !== item.receiptBefore) fail("config or receipt changed during setup; rerun preview before applying");
+      // Receipt is durable before apply changes client config. Undo keeps the receipt until restoration succeeds.
+      if (mode === "apply") write(item.action.receipt, item.receiptAfter, SETUP_RECEIPT_BYTES);
+      try {
+        if (read(item.host.file, SETUP_CONFIG_BYTES) !== item.before) fail("client config changed after receipt creation; rerun preview before applying");
+        write(item.host.file, item.after, SETUP_CONFIG_BYTES, item.host.format === "manifest");
+      }
+      catch (error) { if (mode === "apply" && read(item.action.receipt, SETUP_RECEIPT_BYTES) === item.receiptAfter) write(item.action.receipt, item.receiptBefore, SETUP_RECEIPT_BYTES); throw error; }
+      if (mode === "undo") write(item.action.receipt, null, SETUP_RECEIPT_BYTES);
+      report.applied = true;
+    } catch (error) { item.action.change = "refused"; item.action.reason = failureReason(error); break; }
+    finally { release?.(); }
+  }
+  return report;
+}
+
+/** The manifest directory must satisfy agent-console's private user-owned registration boundary. */
+function privateDirectory(dir: string, apply = false): void {
+  let info;
+  try { info = lstatSync(dir); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+  if (!info.isDirectory() || info.isSymbolicLink()) fail("console plugin directory must be a real directory");
+  if (info.uid !== process.getuid!()) fail("console plugin directory is owned by another user");
+  if (apply) chmodSync(dir, 0o700);
+}
+function privateModesNeeded(file: string): boolean {
+  try { if ((lstatSync(dirname(file)).mode & 0o777) !== 0o700) return true; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+  try { return (lstatSync(file).mode & 0o777) !== 0o600; } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return false; }
+}
+/** Console registration is separate from agent-client `all`; no instruction blocks or other manifests are touched. */
+export function consoleManifest(mode: SetupMode, env: NodeJS.ProcessEnv, requestedRoot = OWN_ROOT, versioned = false): SetupReport {
+  if (!["dry-run", "apply", "undo"].includes(mode)) fail("unsupported setup mode", "choose dry-run, apply or undo and rerun ares setup");
+  const root = install(requestedRoot), module = join(root, "src", "ui", "plugin.ts");
+  const mcp: McpEntry = { command: "bun", args: ["--smol", join(root, "bin", "ares.js"), "mcp"] };
+  let desired: SetupEntry = mcp;
+  if (mode !== "undo") {
+    guard(module, false);
+    let bytes: Buffer;
+    try { bytes = readBytesBounded(module, SETUP_CONFIG_BYTES, { noFollow: true }); }
+    catch { fail("console plugin module is missing, unreadable or over 4 MiB", "select an intact release containing src/ui/plugin.ts and rerun ares setup console"); }
+    desired = { api: 1, tool: "ares", module, sha256: sha256(bytes) };
+  }
+  const pkg = record(JSON.parse(read(join(root, "package.json"), 65_536, false)!)), version = pkg.version;
+  if (versioned && (typeof version !== "string" || version.length > 64 || !/^\d{1,9}\.\d{1,9}\.\d{1,9}(?:[-+][0-9A-Za-z.+-]{1,40})?$/.test(version))) fail("release version cannot name a console registration", "use an agent-research root with a semantic package version: three 1..9-digit parts, optional -/+ suffix of 1..40 characters from 0-9A-Za-z.+-, and at most 64 characters total");
+  const family = absolute(env.AGENTHUB_HOME?.trim() || join(absolute(env.HOME?.trim() || homedir(), "HOME"), ".agenthub"), "AGENTHUB_HOME");
+  const file = join(family, "console", "plugins", versioned ? `ares@${version}.json` : "ares.json");
+  const host: Host = { target: "console", file, key: "", format: "manifest" }, receiptPath = join(family, "research", "setup", `console-${sha256(file).slice(0, 16)}.json`);
+  const report: SetupReport = { mode, applied: false, root, entry: mcp, ...(mode === "undo" ? {} : { console: desired as ConsoleManifest }), actions: [], notes: ["Registers only the ares console plugin; restart the console to load changed code."] };
+  let item: Plan;
+  try { item = plan(host, receiptPath, mode, desired); }
+  catch (error) { report.actions.push({ target: "console", file, entry: "console plugin manifest", receipt: receiptPath, lock: `${file}.ares-setup.lock`, change: "refused", receiptChange: "none", reason: failureReason(error) }); return report; }
+  report.actions.push(item.action); return executePlans([item], mode, desired, report);
+}

package/src/study.ts

@@ -0,0 +1,296 @@
+import { hostname } from "node:os";
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync, writeSync, appendFileSync, lstatSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+
+export type Mode = "survey" | "experiment";
+export type Autonomy = "auto" | "gates";
+export type GateName = "scope" | "screen" | "design" | "final" | "review" | `plan:${string}`;
+export const GATES: readonly GateName[] = ["scope", "screen", "design", "final", "review"];
+export interface Study { v: 1; id: string; question: string; mode: Mode; autonomy: Autonomy; createdAt: string }
+export interface Actor { kind: "person" | "agent" | "auto"; id?: string }
+export function requireExperiment(study: Study): void {
+  if (study.mode !== "experiment") throw new Error("experiment command: study mode must be experiment; create a study with ares init <dir> --question TEXT --mode experiment");
+}
+export interface LedgerEvent { v: 1; at: string; actor: Actor; type: string; data: Record<string, unknown> }
+
+const EVENT_BYTES = 65_536, LEDGER_BYTES = 64 * 1024 * 1024;
+const LOCK_STALE_MS = 10 * 60_000;
+const QUESTION_MAX = 2000;
+export const STUDY_BYTES = 65_536;
+
+/** Agent environment markers the family uses; the first match names the actor. */
+const AGENT_MARKERS: readonly [string, string | undefined][] = [
+  ["AGENTHUB_PEER_ID", undefined], ["CLAUDECODE", "claude"], ["CLAUDE_CODE_SESSION_ID", "claude"], ["CODEX_THREAD_ID", "codex"], ["PI_SESSION_ID", "pi"],
+];
+export function detectActor(env: NodeJS.ProcessEnv): Actor {
+  for (const [marker, name] of AGENT_MARKERS) {
+    const value = env[marker]?.trim();
+    if (value) return { kind: "agent", id: (name ?? value).slice(0, 64) };
+  }
+  return { kind: "person" };
+}
+
+export const sha256 = (data: string | Uint8Array) => createHash("sha256").update(data).digest("hex");
+
+/**
+ * Write a file by temp + fsync + rename so readers never see a partial file. `maxBytes` must be the bound the
+ * file's reader uses, so nothing is written that the tool cannot read back.
+ */
+export function writeAtomic(path: string, text: string, maxBytes: number, mode = 0o644): void {
+  assertWritable(text, maxBytes, path);
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, "wx", mode);
+  try { writeSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  try { renameSync(tmp, path); } catch (error) { try { unlinkSync(tmp); } catch { /* already gone */ } throw error; }
+}
+
+/** Read a regular file, stopping one byte past `maxBytes`: special files and oversize files are refused without buffering them. */
+export interface ReadOptions { noFollow?: boolean; uid?: number }
+export function readBytesBounded(path: string, maxBytes: number, options: ReadOptions = {}): Buffer {
+  // Non-blocking open: a FIFO without a writer would otherwise block before the type check.
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | (options.noFollow ? constants.O_NOFOLLOW : 0));
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw new Error(`${path}: not a regular file`);
+    if (options.uid !== undefined && info.uid !== options.uid) throw new Error(`${path}: owned by another user`);
+    const buffer = Buffer.alloc(Math.min(maxBytes + 1, 1 << 20)), parts: Buffer[] = [];
+    let total = 0;
+    for (;;) {
+      const n = readSync(fd, buffer, 0, buffer.length, null);
+      if (n === 0) break;
+      total += n;
+      if (total > maxBytes) throw new Error(`${path}: larger than ${maxBytes} bytes`);
+      parts.push(Buffer.from(buffer.subarray(0, n)));
+    }
+    return Buffer.concat(parts);
+  } finally { closeSync(fd); }
+}
+export function readTextBounded(path: string, maxBytes: number, options: ReadOptions = {}): string {
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(readBytesBounded(path, maxBytes, options)); }
+  catch (error) { if (error instanceof TypeError) throw new Error(`${path}: not valid UTF-8`); throw error; }
+}
+export function readJsonFile(path: string, maxBytes: number): unknown {
+  const text = readTextBounded(path, maxBytes);
+  try { return JSON.parse(text); } catch { throw new Error(`${path}: not valid JSON`); }
+}
+/** Refuse a write that the matching bounded read could not load back. */
+export function assertWritable(text: string, maxBytes: number, what: string): void {
+  if (Buffer.byteLength(text) > maxBytes) throw new Error(`${what} would exceed ${maxBytes} bytes`);
+}
+
+export const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+
+/** Refuse keys outside `allowed`, so a typo never silently drops a field. */
+export function onlyKeys(value: Record<string, unknown>, allowed: readonly string[], what: string): void {
+  const extra = Object.keys(value).filter(key => !allowed.includes(key));
+  if (extra.length) throw new Error(`${what}: unknown field ${extra[0]}`);
+}
+
+export function boundedText(value: unknown, what: string, max: number, min = 1): string {
+  if (typeof value !== "string" || value.includes("\0")) throw new Error(`${what}: text required`);
+  const text = value.trim();
+  if (text.length < min || text.length > max) throw new Error(`${what}: ${min}..${max} characters`);
+  return text;
+}
+
+export function studyFile(dir: string, ...parts: string[]): string { return join(dir, ...parts); }
+
+/** Resolve a study directory: it must hold a valid study.json. */
+export function openStudy(dir: string): { dir: string; study: Study } {
+  const root = resolve(dir), file = join(root, "study.json");
+  if (!existsSync(file)) throw new Error(`${root}: no study.json (run ares init first)`);
+  return { dir: root, study: validStudy(readJsonFile(file, STUDY_BYTES)) };
+}
+
+function validStudy(raw: unknown): Study {
+  if (plain(raw) && raw.v !== 1) throw new Error("study.json: unsupported schema version; use an ares version that supports this study, keeping the original file unchanged");
+  if (!plain(raw) || raw.v !== 1 || typeof raw.id !== "string" || typeof raw.question !== "string" || typeof raw.createdAt !== "string" ||
+    !["survey", "experiment"].includes(raw.mode as string) || !["auto", "gates"].includes(raw.autonomy as string)) throw new Error("study.json: malformed");
+  return raw as unknown as Study;
+}
+
+export function initStudy(dir: string, options: { question: string; mode?: string; autonomy?: string }, actor: Actor): Study {
+  const root = resolve(dir);
+  if (existsSync(join(root, "study.json"))) throw new Error(`${root}: a study already exists here`);
+  const mode = options.mode ?? "survey", autonomy = options.autonomy ?? "gates";
+  if (mode !== "survey" && mode !== "experiment") throw new Error("--mode: survey or experiment");
+  if (autonomy !== "auto" && autonomy !== "gates") throw new Error("--autonomy: auto or gates");
+  const study: Study = { v: 1, id: randomUUID(), question: boundedText(options.question, "--question", QUESTION_MAX), mode, autonomy, createdAt: new Date().toISOString() };
+  for (const sub of ["", "literature", "literature/cards", "refs"]) mkdirSync(join(root, sub), { recursive: true });
+  // link() refuses an existing target, so two concurrent inits cannot both create the study.
+  const text = JSON.stringify(study, null, 2) + "\n", tmp = join(root, `study.json.${randomUUID()}.tmp`);
+  assertWritable(text, STUDY_BYTES, "study.json");
+  const fd = openSync(tmp, "wx", 0o644);
+  try { writeSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  try { linkSync(tmp, join(root, "study.json")); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`${root}: a study already exists here`); throw error; }
+  finally { unlinkSync(tmp); }
+  appendEvent(root, actor, "study.init", { id: study.id, mode, autonomy });
+  return study;
+}
+
+/**
+ * Exclusive write lock for one study. A lock older than 10 minutes is treated as abandoned and replaced.
+ * ponytail: mtime-based staleness, no owner liveness check; add a pid probe if two hosts share a study.
+ */
+export class StudyLockBusyError extends Error {}
+export async function withLock<T>(dir: string, fn: () => Promise<T> | T): Promise<T> {
+  const path = join(dir, ".ares.lock");
+  let fd: number;
+  try { fd = openSync(path, "wx", 0o600); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    let age = 0;
+    try { age = Date.now() - statSync(path).mtimeMs; } catch { /* removed meanwhile */ }
+    if (age < LOCK_STALE_MS) throw new StudyLockBusyError(`study is locked by another ares command (${path}); retry when it finishes`);
+    try { unlinkSync(path); } catch { /* raced with another cleaner */ }
+    fd = openSync(path, "wx", 0o600);
+  }
+  try { writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`); } finally { closeSync(fd); }
+  try { return await fn(); } finally { try { unlinkSync(path); } catch { /* already removed */ } }
+}
+
+export interface PendingEvent { actor: Actor; type: string; data: Record<string, unknown> }
+export type FileWrite = [path: string, text: string, maxBytes: number];
+
+/** Validate command capacity without writing; callers can reserve receipt space before outward effects. */
+export function prepareCommit(dir: string, files: FileWrite[], pending: PendingEvent[]): { events: LedgerEvent[]; lines: string[] } {
+  const at = new Date().toISOString(), events: LedgerEvent[] = pending.map(e => ({ v: 1, at, ...e }));
+  const lines = events.map(e => JSON.stringify(e) + "\n");
+  lines.forEach((line, i) => { if (Buffer.byteLength(line) > EVENT_BYTES) throw new Error(`ledger event ${events[i]!.type} exceeds ${EVENT_BYTES} bytes`); });
+  const ledger = join(dir, "ledger.jsonl"), size = existsSync(ledger) ? statSync(ledger).size : 0;
+  if (size + Buffer.byteLength(lines.join("")) > LEDGER_BYTES) throw new Error(`ledger.jsonl would exceed ${LEDGER_BYTES} bytes; start a new study`);
+  for (const [path, text, max] of files) assertWritable(text, max, path);
+  return { events, lines };
+}
+/**
+ * Apply one command's changes: every file and ledger bound is checked first (file sizes, event sizes, the ledger's
+ * total against its read limit), then the files are written and all events appended in one write. A failed check
+ * changes nothing.
+ * ponytail: no write-ahead log; a crash between the file writes and the append leaves files without their event.
+ */
+export function commit(dir: string, files: FileWrite[], pending: PendingEvent[]): LedgerEvent[] {
+  const { events, lines } = prepareCommit(dir, files, pending), ledger = join(dir, "ledger.jsonl");
+  for (const [path, text, max] of files) { mkdirSync(dirname(path), { recursive: true }); writeAtomic(path, text, max); }
+  if (lines.length) appendFileSync(ledger, lines.join(""), { mode: 0o644 });
+  return events;
+}
+
+export function appendEvent(dir: string, actor: Actor, type: string, data: Record<string, unknown>): LedgerEvent {
+  return commit(dir, [], [{ actor, type, data }])[0]!;
+}
+
+/** Read the whole ledger; a malformed line fails closed with its line number. */
+export function readLedger(dir: string): LedgerEvent[] {
+  const path = join(dir, "ledger.jsonl");
+  if (!existsSync(path)) return [];
+  const lines = readTextBounded(path, LEDGER_BYTES).split("\n");
+  const events: LedgerEvent[] = [];
+  lines.forEach((line, index) => {
+    if (!line.trim()) return;
+    let event: unknown;
+    try { event = JSON.parse(line); } catch { throw new Error(`ledger.jsonl line ${index + 1}: not JSON`); }
+    if (plain(event) && event.v !== 1) throw new Error(`ledger.jsonl line ${index + 1}: unsupported schema version; use an ares version that supports this ledger, keeping all original lines unchanged`);
+    if (!plain(event) || event.v !== 1 || typeof event.type !== "string" || !plain(event.data) || !plain(event.actor)) throw new Error(`ledger.jsonl line ${index + 1}: malformed event`);
+    events.push(event as unknown as LedgerEvent);
+  });
+  return events;
+}
+
+export interface GateState { gate: GateName; state: "none" | "pending" | "approved" | "rejected"; current?: string; decided?: { decision: "approve" | "reject"; binding: string; actor: Actor; at: string; reason?: string } }
+
+/** The content a gate approval binds to. `undefined` means there is nothing to decide yet. */
+export type Binder = (gate: GateName) => string | undefined;
+
+export function gateState(gate: GateName, events: LedgerEvent[], binder: Binder): GateState {
+  const current = binder(gate);
+  let decided: GateState["decided"];
+  for (const event of events) {
+    if ((event.type === "gate.approve" || event.type === "gate.reject") && event.data.gate === gate && typeof event.data.binding === "string")
+      decided = { decision: event.type === "gate.approve" ? "approve" : "reject", binding: event.data.binding, actor: event.actor, at: event.at, ...(typeof event.data.reason === "string" ? { reason: event.data.reason } : {}) };
+  }
+  if (current === undefined) return { gate, state: "none", ...(decided ? { decided } : {}) };
+  if (!decided || decided.binding !== current) return { gate, state: "pending", current, ...(decided ? { decided } : {}) };
+  return { gate, state: decided.decision === "approve" ? "approved" : "rejected", current, decided };
+}
+
+export function decideGate(dir: string, gate: GateName, decision: "approve" | "reject", actor: Actor, binder: Binder, reason?: string): GateState {
+  if (!GATES.includes(gate) && !gate.startsWith("plan:")) throw new Error(`unknown gate: ${gate}; run ares gate list to select a gate`);
+  const before = gateState(gate, readLedger(dir), binder);
+  if (before.state === "none") throw new Error(`gate ${gate}: nothing to decide yet${gate.startsWith("plan:") ? "; finish every upstream node with output references, then run ares gate list" : ""}`);
+  if (decision === "reject" && !reason) throw new Error(`gate ${gate}: a rejection needs --reason`);
+  appendEvent(dir, actor, decision === "approve" ? "gate.approve" : "gate.reject", { gate, binding: before.current!, ...(reason ? { reason } : {}) });
+  return gateState(gate, readLedger(dir), binder);
+}
+
+/**
+ * Pass when the gate is approved for the current content. In auto mode a pending gate passes too, and the returned
+ * `auto` approval goes into the command's own commit only when the command succeeds, so a failed command never
+ * changes a gate.
+ */
+export function requireGate(dir: string, study: Study, gate: GateName, binder: Binder): PendingEvent[] {
+  if (gate === "design" || gate === "final") requireExperiment(study);
+  const state = gateState(gate, readLedger(dir), binder);
+  if (state.state === "approved") return [];
+  if (state.state === "pending" && study.autonomy === "auto") return [{ actor: { kind: "auto" }, type: "gate.approve", data: { gate, binding: state.current! } }];
+  if (state.state === "none" && gate === "final") throw new Error("gate final: complete reserved seeds and close investigate/required ablate inputs before final approval");
+  if (state.state === "none" && gate.startsWith("plan:")) throw new Error(`gate ${gate}: upstream outputs are not complete; finish every upstream node and run ares gate list again`);
+  if (state.state === "none") throw new Error(gate === "scope" ? "gate scope: no scope yet (run ares scope)" : gate === "design" ? "gate design: no protocol yet (run ares protocol)" : "gate screen: no included candidates yet");
+  if (state.state === "rejected") throw new Error(`gate ${gate} is rejected${state.decided?.reason ? `: ${state.decided.reason}` : ""}; change the content and ask again`);
+  throw new Error(`gate ${gate} is pending: run ares gate approve <dir> ${gate}`);
+}
+
+
+export interface PlanOwner { pid: number; host: string; startedAt: string; token: string }
+/** Kernel process start identity, rather than lock age, detects a reused PID. */
+export function processStart(pid: number): string | undefined {
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 2000, maxBuffer: 4096, env: { PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C" } });
+  if (result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+  return undefined;
+}
+export function readPlanOwner(dir: string): PlanOwner | undefined {
+  const file = join(dir, ".ares.plan.lock");
+  let stat;
+  try { stat = lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("plan controller lock: regular file required; restore the study lock file without links before running ares run");
+  const raw = readJsonFile(file, 4096);
+  if (!plain(raw) || !Number.isSafeInteger(raw.pid) || (raw.pid as number) < 1 || typeof raw.host !== "string" || !raw.host || typeof raw.startedAt !== "string" || !raw.startedAt || typeof raw.token !== "string" || !raw.token) throw new Error("plan controller lock: malformed owner; inspect the owner process and restore a valid lock before ares run");
+  return raw as unknown as PlanOwner;
+}
+export function assertPlanOwner(dir: string, owner: PlanOwner): void {
+  const current = readPlanOwner(dir);
+  if (!current || current.token !== owner.token || current.pid !== owner.pid || current.host !== owner.host || current.startedAt !== owner.startedAt) throw new Error("plan controller: ownership changed; stop this controller and inspect ares plan show before restarting");
+}
+export async function withPlanLock<T>(dir: string, fn: (owner: PlanOwner) => Promise<T>): Promise<T> {
+  const startedAt = processStart(process.pid);
+  if (!startedAt) throw new Error("plan controller: process start identity unavailable; check local ps access before running ares run");
+  const owner: PlanOwner = { pid: process.pid, host: hostname(), startedAt, token: randomUUID() };
+  await withLock(dir, () => {
+    const previous = readPlanOwner(dir);
+    if (previous) {
+      const busy = () => new Error(`plan controller: owned by pid ${previous.pid} on ${previous.host} (started ${previous.startedAt}); stop that controller or run on its host after it exits`);
+      if (previous.host !== owner.host) throw busy();
+      let alive = true;
+      try { process.kill(previous.pid, 0); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") alive = false; else throw busy(); }
+      if (alive) {
+        const observed = processStart(previous.pid);
+        if (!observed || observed === previous.startedAt) throw busy();
+      }
+      // Short study lock serializes contenders. Never recover by age.
+      unlinkSync(join(dir, ".ares.plan.lock"));
+    }
+    const fd = openSync(join(dir, ".ares.plan.lock"), "wx", 0o600);
+    try { writeSync(fd, JSON.stringify(owner) + "\n"); fsyncSync(fd); } finally { closeSync(fd); }
+  });
+  try { return await fn(owner); }
+  finally {
+    // A live matching owner cannot be replaced by any valid contender.
+    try {
+      const current = readPlanOwner(dir);
+      if (current?.token === owner.token) unlinkSync(join(dir, ".ares.plan.lock"));
+    } catch { /* Preserve the original failure; never remove a malformed or unverified owner. */ }
+  }
+}

package/src/ui/panel.css

@@ -0,0 +1,11 @@
+.ares { display: flex; flex-direction: column; gap: var(--acon-space-3); min-width: 0; }
+.ares-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.ares-bar h2 { flex: 1; margin: 0; min-width: 0; font-size: var(--acon-text-lg); overflow-wrap: anywhere; }
+.ares-card { display: flex; flex-direction: column; gap: var(--acon-space-2); min-width: 0; }
+.ares-card h3 { margin: 0; font-size: var(--acon-text-base, 1rem); }
+.ares-card > p, .ares-prose { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.ares-sub { margin: 0; color: var(--acon-text-2); overflow-wrap: anywhere; }
+.ares-pre { margin: 0; max-height: 40vh; overflow: auto; padding: var(--acon-space-3); white-space: pre-wrap; overflow-wrap: anywhere; background: var(--acon-surface-2); border: 1px solid var(--acon-line); border-radius: var(--acon-radius-2); font: var(--acon-text-sm)/1.5 var(--acon-font-mono); }
+.ares-list { margin: 0; padding-left: 1.5em; overflow-wrap: anywhere; }
+.ares-list li + li { margin-top: var(--acon-space-1); }
+@media (max-width: 600px) { .ares-bar { align-items: flex-start; } .ares-bar h2 { flex-basis: 100%; } }