@staix/agent-research 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@staix/agent-research",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Research engine for the agent family: literature with verified references, study ledger and gates (ares)",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STAIxBWLB/agent-research.git"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "devDependencies": {
+    "@staix/agent-console": "git+https://github.com/STAIxBWLB/agent-console.git#27e4f89babc7a25df8038918d1181d0af35384e0",
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.8.0"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "ares": "bin/ares.js"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "bun x tsc --noEmit && bun scripts/check-boundary.ts && bun test && bun pm pack --dry-run",
+    "release:stage": "bun scripts/release.ts stage",
+    "release:smoke": "bun scripts/release-smoke.ts"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,295 @@
+import { version } from "../package.json";
+import { findCommand, help, type CommandSpec } from "./commands-table.ts";
+import * as ops from "./commands.ts";
+import { createHttp, type Http } from "./http.ts";
+import { PLAYBOOK } from "./playbook.ts";
+import { detectActor, readTextBounded } from "./study.ts";
+
+const INPUT_BYTES = 65_536;
+export interface Io extends ops.ExperimentRuntime { readStdin?: () => Promise<string>; http?: Http; signal?: AbortSignal }
+
+function parse(spec: CommandSpec, args: string[]): { flags: Record<string, string | true>; positional: string[] } {
+  const flags: Record<string, string | true> = {}, positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const word = args[i]!;
+    if (word === "-" || !word.startsWith("-")) { positional.push(word); continue; }
+    const kind = spec.options[word];
+    if (!kind || word in flags) throw new Error(`${spec.name}: unknown or repeated option ${word}; use ares --help and pass each supported option once`);
+    if (kind === "value") {
+      const value = args[++i];
+      if (value === undefined || (value.startsWith("--") && value !== "-")) throw new Error(`${spec.name}: ${word} needs a value; use ares --help for its accepted values`);
+      flags[word] = value;
+    } else flags[word] = true;
+  }
+  return { flags, positional };
+}
+function count(spec: CommandSpec, positional: string[], min: number, max = min): void {
+  if (positional.length < min || positional.length > max) throw new Error(`usage: ares ${spec.usage}`);
+}
+function integer(value: string | true | undefined, what: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !/^\d{1,7}$/.test(value)) throw new Error(`${what}: integer required; pass a nonnegative decimal integer`);
+  return Number(value);
+}
+function seed(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!/^-?\d{1,10}$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < -2_147_483_648 || Number(value) > 2_147_483_647) throw new Error("--seed: invalid integer; use a declared protocol seed in -2147483648..2147483647");
+  return Number(value);
+}
+async function readInput(path: string, io: Io): Promise<unknown> {
+  let text: string;
+  if (path === "-") {
+    if (!io.readStdin) throw new Error("--file -: no standard input");
+    text = await io.readStdin();
+  } else text = readTextBounded(path, INPUT_BYTES);
+  if (Buffer.byteLength(text) > INPUT_BYTES) throw new Error(`input larger than ${INPUT_BYTES} bytes`);
+  try { return JSON.parse(text); } catch { throw new Error(`${path === "-" ? "standard input" : path}: not valid JSON`); }
+}
+
+export async function run(args: string[], env: NodeJS.ProcessEnv = process.env, io: Io = {}): Promise<{ text: string; code: number }> {
+  if (!args.length || (args.length === 1 && ["--help", "-h", "help"].includes(args[0]!))) return { text: help(), code: 0 };
+  if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
+  const found = findCommand(args);
+  if (!found) throw new Error(`unknown command: ${args.slice(0, 2).join(" ")}; use --help`);
+  const { spec, rest } = found, { flags, positional } = parse(spec, rest);
+  const ctx: ops.Ctx = { actor: detectActor(env), http: io.http ?? createHttp(env), ...(io.signal ? { signal: io.signal } : {}), ...(io.sleep ? { sleep: io.sleep } : {}), ...(io.runner ? { runner: io.runner } : {}), ...(io.now ? { now: io.now } : {}), ...(io.collectEvaluation ? { collectEvaluation: io.collectEvaluation } : {}), ...(io.collectStageEvidence ? { collectStageEvidence: io.collectStageEvidence } : {}) };
+  const str = (flag: string) => (typeof flags[flag] === "string" ? flags[flag] as string : undefined);
+  let result: unknown, code = 0;
+  switch (spec.name) {
+    case "console add": count(spec, positional, 1); result = ops.consoleAdd(positional[0]!, env); break;
+    case "console remove": count(spec, positional, 1); result = ops.consoleRemove(positional[0]!, env); break;
+    case "console list": count(spec, positional, 0); result = ops.consoleList(env); break;
+    case "watch set": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("watch set: input missing; pass --file PATH or --file - for watch JSON");
+      result = await ops.watchSet(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "watch run": {
+      count(spec, positional, 1); const output = await ops.watchRun(positional[0]!, ctx);
+      result = output; if (!output.ok) code = 1; break;
+    }
+    case "watch show": count(spec, positional, 1); result = ops.watchShow(positional[0]!); break;
+    case "setup": {
+      count(spec, positional, 1);
+      if (flags["--apply"] && flags["--undo"]) throw new Error("setup: --apply and --undo conflict; choose one or omit both for preview");
+      const root = str("--root"); result = ops.setup(positional[0]!, flags["--apply"] ? "apply" : flags["--undo"] ? "undo" : "dry-run", env, { ...(root === undefined ? {} : { root }) });
+      if ((result as ReturnType<typeof ops.setup>).actions.some(action => action.change === "refused")) code = 1;
+      break;
+    }
+    case "skill propose": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("skill propose: input missing; pass --file PATH or --file - for proposal JSON");
+      result = await ops.skillPropose(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "skill decide": {
+      count(spec, positional, 3); const reason = str("--reason");
+      if (reason === undefined) throw new Error("skill decide: reason missing; pass --reason TEXT and --pr URL for accept");
+      result = await ops.skillDecide(positional[0]!, positional[1]!, positional[2]!, reason, str("--pr"), ctx); break;
+    }
+    case "skill list": count(spec, positional, 1); result = ops.skillList(positional[0]!); break;
+    case "lessons": {
+      count(spec, positional, 1); const intent = str("--for"), halfLife = str("--half-life"), limit = integer(flags["--limit"], "--limit");
+      result = await ops.lessons(positional[0]!, { ...(intent === undefined ? {} : { for: intent }), ...(halfLife === undefined ? {} : { halfLife: Number(halfLife) }), ...(limit === undefined ? {} : { limit }) }, ctx, env); break;
+    }
+    case "archive": {
+      count(spec, positional, 1); const confirm = str("--confirm");
+      result = await ops.archive(positional[0]!, { ...(confirm !== undefined ? { confirm } : {}) }, ctx, env); break;
+    }
+    case "run": {
+      count(spec, positional, 1); const parallel = integer(flags["--parallel"], "--parallel");
+      result = await ops.planRun(positional[0]!, { ...(parallel !== undefined ? { parallel } : {}) }, ctx); break;
+    }
+    case "manifest": count(spec, positional, 0); result = ops.manifest(); break;
+    case "playbook": count(spec, positional, 0); return { text: PLAYBOOK.trimEnd(), code: 0 };
+    case "mcp": throw new Error("mcp: run `ares mcp` with no other arguments");
+    case "init": {
+      count(spec, positional, 1);
+      const question = str("--question");
+      if (question === undefined) throw new Error("init: --question is required");
+      result = ops.init(positional[0]!, { question, ...(str("--mode") ? { mode: str("--mode")! } : {}), ...(str("--autonomy") ? { autonomy: str("--autonomy")! } : {}) }, ctx);
+      break;
+    }
+    case "plan set": {
+      count(spec, positional, 1);
+      const file = str("--file");
+      if (file === undefined) throw new Error("plan set: --file is required");
+      result = await ops.planSet(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "plan control": {
+      count(spec, positional, 2, 3);
+      const commandId = str("--command-id"), expectedRevision = integer(flags["--expected-revision"], "--expected-revision");
+      if (!commandId || expectedRevision === undefined) throw new Error("plan control: command id and revision required; pass --command-id ID --expected-revision N from ares plan show");
+      result = await ops.planControl(positional[0]!, { action: positional[1]! as Parameters<typeof ops.planControl>[1]["action"], ...(positional[2] !== undefined ? { node: positional[2] } : {}), commandId, expectedRevision }, ctx); break;
+    }
+    case "plan show": count(spec, positional, 1); result = ops.planShow(positional[0]!); break;
+    case "status": count(spec, positional, 1); result = ops.status(positional[0]!); break;
+    case "scope": {
+      count(spec, positional, 1);
+      const file = str("--file");
+      if (file === undefined) throw new Error("scope: --file is required");
+      result = await ops.scope(positional[0]!, await readInput(file, io), ctx);
+      break;
+    }
+    case "idea add": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("idea add: input missing; pass --file PATH or --file - for JSON");
+      result = await ops.ideaAdd(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "idea decide": {
+      count(spec, positional, 3); const reason = str("--reason"), attempts = str("--attempts");
+      if (reason === undefined) throw new Error("idea decide: reason missing; pass --reason TEXT and --commit SHA for refine, plus --attempts for an idea with commits");
+      result = await ops.ideaDecide(positional[0]!, positional[1]!, { decision: positional[2], reason, ...(str("--cause") !== undefined ? { cause: str("--cause") } : {}), ...(str("--retry-when") !== undefined ? { retryWhen: str("--retry-when") } : {}), ...(attempts !== undefined ? { attempts: attempts.split(",") } : {}), ...(str("--commit") !== undefined ? { commit: str("--commit") } : {}) }, ctx); break;
+    }
+    case "investigate show": count(spec, positional, 1); result = ops.investigateShow(positional[0]!); break;
+    case "investigate close": count(spec, positional, 1); result = await ops.investigateClose(positional[0]!, ctx); break;
+    case "ablate add": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("ablate add: input missing; pass --file PATH or --file - for JSON");
+      result = await ops.ablateAdd(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "ablate show": count(spec, positional, 1); result = ops.ablateShow(positional[0]!); break;
+    case "ablate close": count(spec, positional, 1); result = await ops.ablateClose(positional[0]!, ctx); break;
+    case "posthoc show": count(spec, positional, 1); result = ops.posthocShow(positional[0]!); break;
+    case "final close": count(spec, positional, 1); result = await ops.finalClose(positional[0]!, ctx); break;
+    case "final seeds": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("final seeds: input missing; pass --file PATH or --file - for JSON");
+      result = await ops.finalSeeds(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "selection": {
+      count(spec, positional, 1);
+      const file = str("--file");
+      if (file === undefined) throw new Error("selection: input missing; pass --file PATH or --file - for a JSON rule");
+      result = await ops.selection(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "protocol": {
+      count(spec, positional, 1);
+      const file = str("--file");
+      if (file === undefined) throw new Error("protocol: input file missing; use --file PATH or --file - for JSON standard input");
+      result = await ops.protocol(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "executor set": {
+      count(spec, positional, 1);
+      const kind = str("--kind"), workdir = str("--workdir");
+      if (!kind || !workdir) throw new Error("executor set: kind/workdir missing; use --kind local|ssh --workdir PATH and --host ALIAS for ssh");
+      result = await ops.executorSet(positional[0]!, { v: 1, kind, workdir, ...(str("--host") !== undefined ? { host: str("--host") } : {}) }, ctx); break;
+    }
+    case "executor check": count(spec, positional, 1); result = await ops.executorCheck(positional[0]!, ctx); break;
+    case "attempt run": {
+      count(spec, positional, 1);
+      const repo = str("--repo"), commit = str("--commit"), chosenSeed = seed(str("--seed"));
+      if (!repo || !commit) throw new Error("attempt run: repo/commit missing; use --repo PATH --commit FULL_40_HEX_SHA");
+      const attempt = await ops.attemptRun(positional[0]!, { repo, commit, ...(chosenSeed !== undefined ? { seed: chosenSeed } : {}), ...(str("--run") !== undefined ? { run: str("--run") } : {}), ...(str("--label") !== undefined ? { label: str("--label") } : {}), ...(str("--retry") !== undefined ? { retry: str("--retry") } : {}), detach: !!flags["--detach"] }, ctx);
+      if (attempt.status !== "running" && attempt.status !== "succeeded") code = 1;
+      result = attempt; break;
+    }
+    case "attempt list": {
+      count(spec, positional, 1); const limit = integer(flags["--limit"], "--limit"), offset = integer(flags["--offset"], "--offset");
+      result = ops.attemptList(positional[0]!, { ...(str("--run") !== undefined ? { run: str("--run") } : {}), ...(str("--status") !== undefined ? { status: str("--status") } : {}), ...(limit !== undefined ? { limit } : {}), ...(offset !== undefined ? { offset } : {}) }); break;
+    }
+    case "attempt show": count(spec, positional, 2); result = ops.attemptShow(positional[0]!, positional[1]!); break;
+    case "attempt cancel": count(spec, positional, 2); result = await ops.attemptCancel(positional[0]!, positional[1]!, str("--reason"), ctx); break;
+    case "attempt reconcile": count(spec, positional, 1); result = await ops.attemptReconcile(positional[0]!, ctx); break;
+    case "attempt logs": {
+      count(spec, positional, 2); const tailBytes = integer(flags["--tail"], "--tail");
+      const logs = await ops.attemptLogs(positional[0]!, positional[1]!, { ...(str("--stage") !== undefined ? { stage: str("--stage") } : {}), ...(str("--stream") !== undefined ? { stream: str("--stream") } : {}), ...(tailBytes !== undefined ? { tailBytes } : {}) }, ctx);
+      if (!flags["--json"]) return { text: logs.logs.map(log => `[${log.stage} ${log.stream}${log.truncated ? ", truncated copy" : ""}]\n${log.text}`).join("\n"), code: 0 };
+      result = logs; break;
+    }
+    case "gate list": count(spec, positional, 1); result = ops.gateList(positional[0]!); break;
+    case "gate approve": case "gate reject":
+      count(spec, positional, 2);
+      result = await ops.gateDecide(positional[0]!, positional[1]!, spec.name === "gate approve" ? "approve" : "reject", str("--reason"), ctx);
+      break;
+    case "lit search": {
+      count(spec, positional, 2);
+      const limit = integer(flags["--limit"], "--limit"), yearFrom = integer(flags["--year-from"], "--year-from");
+      const out = await ops.search(positional[0]!, positional[1]!, { ...(str("--source") ? { source: str("--source")! } : {}), ...(limit !== undefined ? { limit } : {}), ...(yearFrom !== undefined ? { yearFrom } : {}) }, ctx);
+      if (!out.sources.some(s => s.ok)) code = 1;
+      result = out;
+      break;
+    }
+    case "lit list": {
+      count(spec, positional, 1);
+      const limit = integer(flags["--limit"], "--limit");
+      result = ops.list(positional[0]!, { ...(str("--status") ? { status: str("--status")! } : {}), ...(limit !== undefined ? { limit } : {}) });
+      break;
+    }
+    case "lit screen": {
+      if (positional.length < 2) throw new Error(`usage: ares ${spec.usage}`);
+      if (!!flags["--include"] === !!flags["--exclude"]) throw new Error("lit screen: exactly one of --include or --exclude");
+      result = await ops.screen(positional[0]!, positional.slice(1), flags["--include"] ? "include" : "exclude", str("--reason"), ctx);
+      break;
+    }
+    case "lit card": {
+      count(spec, positional, 2);
+      const file = str("--file");
+      if (file === undefined) throw new Error("lit card: --file is required");
+      result = await ops.card(positional[0]!, positional[1]!, await readInput(file, io), ctx);
+      break;
+    }
+    case "lit verify": if (!positional.length) throw new Error(`usage: ares ${spec.usage}`); result = await ops.verify(positional[0]!, positional.slice(1), ctx); break;
+    case "lit bib": count(spec, positional, 1); result = await ops.bib(positional[0]!, ctx); break;
+    case "review add": {
+      count(spec, positional, 1); const file = str("--file");
+      if (file === undefined) throw new Error("review add: --file is required; pass --file PATH|- with a current-build report");
+      result = await ops.reviewAdd(positional[0]!, await readInput(file, io), ctx); break;
+    }
+    case "review resolve": {
+      count(spec, positional, 2); const reason = str("--reason");
+      if (reason === undefined) throw new Error("review resolve: --reason is required; explain how the finding was resolved");
+      result = await ops.reviewResolve(positional[0]!, positional[1]!, reason, ctx); break;
+    }
+    case "review show": count(spec, positional, 1); result = ops.reviewShow(positional[0]!); break;
+    case "paper build": count(spec, positional, 1); result = await ops.paperBuild(positional[0]!, ctx); break;
+    case "paper check": {
+      count(spec, positional, 1); const report = ops.paperCheck(positional[0]!);
+      if (!report.ok) code = 1;
+      result = report; break;
+    }
+    case "cite check": {
+      count(spec, positional, 2);
+      const report = ops.cite(positional[0]!, positional[1]!);
+      if (!report.ok) code = 1;
+      result = report;
+      break;
+    }
+    default: throw new Error(`unknown command: ${spec.name}`);
+  }
+  return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code };
+}
+
+/** `ares mcp`: stdout carries protocol frames only. */
+export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  const [{ serveMcp }, { createAresMcp }] = await Promise.all([import("./mcp.ts"), import("./mcp-tools.ts")]);
+  const server = createAresMcp(env);
+  try { await serveMcp({ tools: server.tools, handlers: server.handlers, name: "ares", version }); }
+  finally { await server.waitForIdle(); }
+}
+
+/** Standard input stops at the input bound instead of buffering everything first. */
+async function readStdinBounded(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for await (const chunk of Bun.stdin.stream()) {
+    size += chunk.byteLength;
+    if (size > INPUT_BYTES) throw new Error(`standard input larger than ${INPUT_BYTES} bytes`);
+    chunks.push(chunk);
+  }
+  return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+}
+
+export async function main(args: string[]): Promise<number> {
+  const stop = new AbortController(), interrupt = () => stop.abort();
+  if (args[0] === "run") { process.on("SIGINT", interrupt); process.on("SIGTERM", interrupt); }
+  try {
+    const output = await run(args, process.env, { readStdin: readStdinBounded, signal: stop.signal });
+    console.log(output.text);
+    return output.code;
+  } catch (error) {
+    console.error(`ares: ${error instanceof Error ? error.message : "operation failed"}`);
+    return 1;
+  } finally {
+    if (args[0] === "run") { process.off("SIGINT", interrupt); process.off("SIGTERM", interrupt); }
+  }
+}

package/src/commands-table.ts

@@ -0,0 +1,72 @@
+/** The single source of the CLI surface: help text is rendered from it and the parser reads its options. */
+export interface CommandSpec { name: string; usage: string; mutates: boolean | "network"; options: Record<string, "flag" | "value"> }
+const json = { "--json": "flag" } as const;
+export const COMMANDS: readonly CommandSpec[] = [
+  { name: "skill propose", usage: "skill propose <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "skill decide", usage: "skill decide <dir> <name> <accept|reject|withdraw> --reason TEXT [--pr URL] [--json]", mutates: true, options: { "--reason": "value", "--pr": "value", ...json } },
+  { name: "skill list", usage: "skill list <dir> [--json]", mutates: false, options: json },
+  { name: "lessons", usage: "lessons <dir> [--for TEXT] [--half-life DAYS] [--limit N] [--json]", mutates: false, options: { "--for": "value", "--half-life": "value", "--limit": "value", ...json } },
+  { name: "archive", usage: "archive <dir> [--confirm FINGERPRINT] [--json]", mutates: "network", options: { "--confirm": "value", ...json } },
+  { name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all|console> [--apply|--undo] [--root ABS] [--json]", mutates: true, options: { "--apply": "flag", "--undo": "flag", "--root": "value", ...json } },
+  { name: "watch set", usage: "watch set <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "watch run", usage: "watch run <dir> [--json]", mutates: "network", options: json },
+  { name: "watch show", usage: "watch show <dir> [--json]", mutates: false, options: json },
+  { name: "console add", usage: "console add <dir> [--json]", mutates: true, options: json },
+  { name: "console remove", usage: "console remove <dir> [--json]", mutates: true, options: json },
+  { name: "console list", usage: "console list [--json]", mutates: false, options: json },
+  { name: "manifest", usage: "manifest [--json]", mutates: false, options: json },
+  { name: "init", usage: "init <dir> --question TEXT [--mode survey|experiment] [--autonomy auto|gates] [--json]", mutates: true, options: { "--question": "value", "--mode": "value", "--autonomy": "value", ...json } },
+  { name: "run", usage: "run <dir> [--parallel 1..8] [--json]", mutates: "network", options: { "--parallel": "value", ...json } },
+  { name: "plan set", usage: "plan set <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "plan control", usage: "plan control <dir> <pause|resume|retry|cancel|skip> [node] --command-id ID --expected-revision N [--json]", mutates: "network", options: { "--command-id": "value", "--expected-revision": "value", ...json } },
+  { name: "plan show", usage: "plan show <dir> [--json]", mutates: false, options: json },
+  { name: "status", usage: "status <dir> [--json]", mutates: false, options: json },
+  { name: "scope", usage: "scope <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "idea add", usage: "idea add <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "idea decide", usage: "idea decide <dir> <id> <refine|pivot> --reason TEXT [--attempts ID[,ID...]] [--commit SHA] [--cause TEXT] [--retry-when TEXT] [--json]", mutates: true, options: { "--cause": "value", "--retry-when": "value", "--reason": "value", "--attempts": "value", "--commit": "value", ...json } },
+  { name: "investigate show", usage: "investigate show <dir> [--json]", mutates: false, options: json },
+  { name: "investigate close", usage: "investigate close <dir> [--json]", mutates: true, options: json },
+  { name: "ablate add", usage: "ablate add <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "ablate show", usage: "ablate show <dir> [--json]", mutates: false, options: json },
+  { name: "ablate close", usage: "ablate close <dir> [--json]", mutates: true, options: json },
+  { name: "posthoc show", usage: "posthoc show <dir> [--json]", mutates: false, options: json },
+  { name: "final close", usage: "final close <dir> [--json]", mutates: true, options: json },
+  { name: "final seeds", usage: "final seeds <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "selection", usage: "selection <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "protocol", usage: "protocol <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "executor set", usage: "executor set <dir> --kind local|ssh [--host ALIAS] --workdir PATH [--json]", mutates: true, options: { "--kind": "value", "--host": "value", "--workdir": "value", ...json } },
+  { name: "executor check", usage: "executor check <dir> [--json]", mutates: "network", options: json },
+  { name: "gate list", usage: "gate list <dir> [--json]", mutates: false, options: json },
+  { name: "gate approve", usage: "gate approve <dir> <scope|screen|design|final|review|plan:node-id> [--reason TEXT] [--json]", mutates: true, options: { "--reason": "value", ...json } },
+  { name: "gate reject", usage: "gate reject <dir> <scope|screen|design|final|review|plan:node-id> --reason TEXT [--json]", mutates: true, options: { "--reason": "value", ...json } },
+  { name: "attempt run", usage: "attempt run <dir> --repo PATH --commit SHA [--seed N] [--run NAME] [--label TEXT] [--retry ID] [--detach] [--json]", mutates: "network", options: { "--repo": "value", "--commit": "value", "--seed": "value", "--run": "value", "--label": "value", "--retry": "value", "--detach": "flag", ...json } },
+  { name: "attempt list", usage: "attempt list <dir> [--run NAME] [--status running|succeeded|failed|cancelled|unknown] [--limit N] [--offset N] [--json]", mutates: false, options: { "--run": "value", "--status": "value", "--limit": "value", "--offset": "value", ...json } },
+  { name: "attempt show", usage: "attempt show <dir> <id> [--json]", mutates: false, options: json },
+  { name: "attempt cancel", usage: "attempt cancel <dir> <id> [--reason TEXT] [--json]", mutates: "network", options: { "--reason": "value", ...json } },
+  { name: "attempt reconcile", usage: "attempt reconcile <dir> [--json]", mutates: "network", options: json },
+  { name: "attempt logs", usage: "attempt logs <dir> <id> [--stage candidate|evaluator] [--stream stdout|stderr] [--tail BYTES] [--json]", mutates: false, options: { "--stage": "value", "--stream": "value", "--tail": "value", ...json } },
+  { name: "lit search", usage: "lit search <dir> <query> [--source openalex|s2|arxiv|all] [--limit 1..50] [--year-from YYYY] [--json]", mutates: "network", options: { "--source": "value", "--limit": "value", "--year-from": "value", ...json } },
+  { name: "lit list", usage: "lit list <dir> [--status new|included|excluded] [--limit 1..500] [--json]", mutates: false, options: { "--status": "value", "--limit": "value", ...json } },
+  { name: "lit screen", usage: "lit screen <dir> <id>... --include|--exclude [--reason TEXT] [--json]", mutates: true, options: { "--include": "flag", "--exclude": "flag", "--reason": "value", ...json } },
+  { name: "lit card", usage: "lit card <dir> <id> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "lit verify", usage: "lit verify <dir> [<id>...] [--json]", mutates: "network", options: json },
+  { name: "lit bib", usage: "lit bib <dir> [--json]", mutates: true, options: json },
+  { name: "review add", usage: "review add <dir> --file PATH|- [--json]", mutates: true, options: { "--file": "value", ...json } },
+  { name: "review resolve", usage: "review resolve <dir> <review-id>/<finding-id> --reason TEXT [--json]", mutates: true, options: { "--reason": "value", ...json } },
+  { name: "review show", usage: "review show <dir> [--json]", mutates: false, options: json },
+  { name: "paper build", usage: "paper build <dir> [--json]", mutates: true, options: json },
+  { name: "paper check", usage: "paper check <dir> [--json]", mutates: false, options: json },
+  { name: "cite check", usage: "cite check <dir> <draft> [--json]", mutates: false, options: json },
+  { name: "playbook", usage: "playbook", mutates: false, options: {} },
+  { name: "mcp", usage: "mcp", mutates: false, options: {} },
+];
+export function findCommand(args: string[]): { spec: CommandSpec; rest: string[] } | undefined {
+  for (const words of [2, 1]) {
+    const name = args.slice(0, words).join(" "), spec = COMMANDS.find(c => c.name === name);
+    if (spec) return { spec, rest: args.slice(words) };
+  }
+  return undefined;
+}
+export function help(): string {
+  return "ares - research engine: study ledger, literature search, verified references\n\n" + COMMANDS.map(c => `  ares ${c.usage}`).join("\n") + "\n\n  ares --help | --version\n";
+}