@staix/agent-research 0.0.0-stage → 0.1.0

package/src/exp/executor.ts

@@ -0,0 +1,207 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, posix } from "node:path";
+import { commit, openStudy, plain, readJsonFile, requireExperiment, type Actor } from "../study.ts";
+import { readProtocol, validateProtocol, type Protocol } from "./protocol.ts";
+
+export interface Executor { v: 1; kind: "local" | "ssh"; host?: string; workdir: string }
+export interface ProcessRequest {
+  command: string; args: string[]; stdin?: Uint8Array | AsyncIterable<Uint8Array>;
+  stdoutSink?: (chunk: Uint8Array) => void | Promise<void>; signal?: AbortSignal;
+  timeoutMs?: number; maxOutputBytes?: number; cwd?: string; env?: NodeJS.ProcessEnv;
+}
+export interface ProcessResult { exitCode: number; stdout: string; stderr: string; timedOut?: boolean; truncated?: boolean }
+export type ProcessRunner = (request: ProcessRequest) => Promise<ProcessResult>;
+export const EXECUTOR_BYTES = 8192, PROCESS_OUTPUT_BYTES = 65_536;
+
+/** Opt-in context for native CLI attribution and config discovery; no API credentials. */
+export const PROCESS_CONTEXT_ENV_KEYS = ["AGENTHUB_PEER_ID", "CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CODEX_THREAD_ID", "PI_SESSION_ID",
+  "AMEM_HOME", "AGENTHUB_HOME", "CLAUDE_CONFIG_DIR", "CODEX_HOME", "XDG_CONFIG_HOME", "KIMI_CODE_HOME", "PI_CODING_AGENT_DIR", "QWEN_HOME", "JCODE_HOME"] as const;
+const BASE_ENV_KEYS = ["PATH", "HOME", "USER", "LOGNAME", "TMPDIR", "SSH_AUTH_SOCK", "DOCKER_HOST", "DOCKER_CONTEXT"];
+/** Context is opt-in; executor children keep their existing minimal environment by default. */
+export function processEnvironment(env: NodeJS.ProcessEnv, extra: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv {
+  return Object.fromEntries([...BASE_ENV_KEYS, ...PROCESS_CONTEXT_ENV_KEYS].flatMap(key => {
+    const value = extra[key] ?? (BASE_ENV_KEYS.includes(key) ? env[key] : undefined);
+    return value === undefined ? [] : [[key, value]];
+  }));
+}
+
+/** Bounded tails and a deadline; callers must never persist raw process diagnostics. */
+export const spawnRunner: ProcessRunner = async request => {
+  const max = request.maxOutputBytes ?? PROCESS_OUTPUT_BYTES, timeout = request.timeoutMs ?? 30_000;
+  if (!Number.isSafeInteger(max) || max < 1 || max > 1024 * 1024 || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 604_800_000) {
+    throw new Error("process bounds: invalid; use 1..1048576 output bytes and 1..604800000 timeout milliseconds");
+  }
+  if (request.signal?.aborted) throw new Error("process cancelled; retry the operation when cancellation is cleared");
+  const child = spawn(request.command, request.args, { env: processEnvironment(process.env, request.env), cwd: request.cwd, detached: true, stdio: ["pipe", "pipe", "pipe"] });
+  let stdout: Buffer = Buffer.alloc(0), stderr: Buffer = Buffer.alloc(0), truncated = false, timedOut = false;
+  const append = (old: Buffer, chunk: Buffer): Buffer => {
+    if (old.length + chunk.length > max) truncated = true;
+    return chunk.length >= max ? Buffer.from(chunk.subarray(chunk.length - max)) : Buffer.concat([old.subarray(Math.max(0, old.length + chunk.length - max)), chunk]);
+  };
+  child.stderr.on("data", (chunk: Buffer) => { stderr = append(stderr, chunk); });
+  const stop = () => {
+    try { if (child.pid) process.kill(-child.pid, "SIGKILL"); }
+    catch { child.kill("SIGKILL"); }
+  };
+  const timer = setTimeout(() => { timedOut = true; stop(); }, timeout);
+  request.signal?.addEventListener("abort", stop, { once: true });
+  const closed = new Promise<number>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", code => resolve(code ?? -1));
+  });
+  // EPIPE is normal if a child exits before consuming its snapshot input.
+  child.stdin.on("error", () => {});
+  const input = async () => {
+    if (request.stdin && Symbol.asyncIterator in request.stdin) {
+      const iterator = request.stdin[Symbol.asyncIterator]();
+      try {
+        for (;;) {
+          const next = await Promise.race([iterator.next().then(value => ({ value })), closed.then(() => ({ value: undefined }))]);
+          if (!next.value || next.value.done || request.signal?.aborted || child.stdin.destroyed) break;
+          await new Promise<void>((resolve, reject) => child.stdin.write(next.value!.value, error => error ? reject(error) : resolve()));
+        }
+      } finally {
+        // A cancelled producer can have a pending next(); do not wait forever for its return().
+        void iterator.return?.().catch(() => {});
+      }
+      child.stdin.end();
+    } else child.stdin.end(request.stdin);
+  };
+  const output = async () => {
+    for await (const chunk of child.stdout) {
+      if (request.stdoutSink) await request.stdoutSink(chunk as Buffer);
+      else stdout = append(stdout, chunk as Buffer);
+    }
+  };
+  let ioError: unknown;
+  const pumps = [input(), output()].map(pump => pump.catch(error => { ioError ??= error; stop(); }));
+  try {
+    const code = await closed;
+    await Promise.all(pumps);
+    if (ioError) throw ioError;
+    return { exitCode: code, stdout: stdout.toString("utf8"), stderr: stderr.toString("utf8"), ...(timedOut ? { timedOut } : {}), ...(truncated ? { truncated } : {}) };
+  } finally {
+    clearTimeout(timer); request.signal?.removeEventListener("abort", stop);
+  }
+};
+
+function host(executor: Executor): string { return executor.kind === "ssh" ? executor.host! : "local"; }
+function failed(executor: Executor, step: string): Error {
+  return new Error(`executor ${host(executor)}: ${step} failed; check that step on the executor host and rerun ares executor check <dir>`);
+}
+function directory(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.length > 4096 || !value.startsWith("/") || /[\0\r\n,"]/.test(value)) throw new Error(`${field}: invalid directory; use an absolute path of at most 4096 characters without NUL, newlines, commas or double quotes`);
+  return posix.normalize(value);
+}
+export function validateExecutor(raw: unknown): Executor {
+  if (!plain(raw)) throw new Error("executor: object required; pass kind and workdir to ares executor set");
+  const extra = Object.keys(raw).find(key => !["v", "kind", "host", "workdir"].includes(key));
+  if (extra !== undefined) throw new Error(`executor: unknown field ${extra}; use only v, kind, host and workdir`);
+  if (raw.v !== 1 || (raw.kind !== "local" && raw.kind !== "ssh")) throw new Error("executor: invalid version or kind; set v to 1 and kind to local or ssh");
+  if (raw.kind === "ssh" && (typeof raw.host !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(raw.host))) throw new Error("executor.host: invalid SSH alias; configure an SSH alias and pass its name only (letters, digits, dot, underscore or hyphen)");
+  if (raw.kind === "local" && raw.host !== undefined) throw new Error("executor.host: local executor has no SSH host; remove host or set kind to ssh");
+  if (raw.workdir === undefined || raw.workdir === null) throw new Error("executor.workdir: required with no default; run ares executor set <dir> --kind local|ssh [--host ALIAS] --workdir PATH using a private directory on the executor host");
+  return { v: 1, kind: raw.kind, ...(raw.kind === "ssh" ? { host: raw.host as string } : {}), workdir: directory(raw.workdir, "executor.workdir") };
+}
+export function readExecutor(dir: string): Executor | undefined {
+  const file = join(dir, "executor.json");
+  return existsSync(file) ? validateExecutor(readJsonFile(file, EXECUTOR_BYTES)) : undefined;
+}
+/** Caller holds the study lock. Config contains no credentials and is outside the design seal. */
+export function setExecutor(dir: string, raw: unknown, actor: Actor): Executor {
+  requireExperiment(openStudy(dir).study);
+  const executor = validateExecutor(raw);
+  commit(dir, [[join(dir, "executor.json"), JSON.stringify(executor, null, 2) + "\n", EXECUTOR_BYTES]], [{ actor, type: "executor.set", data: { kind: executor.kind, ...(executor.host ? { host: executor.host } : {}) } }]);
+  return executor;
+}
+
+/** SSH concatenates its remote command argv into a shell command, so quote every unsafe byte. */
+export function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_./:@=+-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+export async function runOnExecutor(executorArg: Executor, command: string, args: string[], runner: ProcessRunner = spawnRunner, options: Omit<ProcessRequest, "command" | "args"> = {}): Promise<ProcessResult> {
+  const executor = validateExecutor(executorArg);
+  try { return await runner(executor.kind === "local" ? { ...options, command, args } : { ...options, command: "ssh", args: ["-o", "BatchMode=yes", executor.host!, shellQuote(command), ...args.map(shellQuote)] }); }
+  catch { throw failed(executor, "process start"); }
+}
+async function step(executor: Executor, name: string, command: string, args: string[], runner: ProcessRunner, options: Omit<ProcessRequest, "command" | "args"> = {}): Promise<ProcessResult> {
+  try {
+    const result = await runOnExecutor(executor, command, args, runner, options);
+    if (result.exitCode !== 0 || result.timedOut || result.truncated) throw failed(executor, name);
+    return result;
+  } catch { throw failed(executor, name); }
+}
+export interface ExecutorCheck { executor: Executor; serverVersion: string; user: string; images: { image: string; available: true }[]; pull: "missing" }
+export async function checkExecutor(dir: string, runner: ProcessRunner = spawnRunner): Promise<ExecutorCheck> {
+  requireExperiment(openStudy(dir).study);
+  const executor = readExecutor(dir), protocol = readProtocol(dir);
+  if (!executor) throw new Error("executor: not configured; run ares executor set <dir> --kind local|ssh [--host ALIAS] --workdir PATH");
+  if (!protocol) throw new Error("protocol: missing; run ares protocol <dir> --file PATH before executor check");
+  return checkExecutorInputs(executor, protocol, runner);
+}
+/** Check a frozen attempt's configuration rather than mutable study files. */
+export async function checkExecutorInputs(executor: Executor, protocol: Protocol, runner: ProcessRunner = spawnRunner): Promise<ExecutorCheck> {
+  const version = (await step(executor, "Docker server version", "docker", ["version", "--format", "{{.Server.Version}}"], runner)).stdout.trim();
+  if (!/^[0-9]+\.[0-9]+(?:\.[0-9]+)?[A-Za-z0-9.+_-]*$/.test(version) || version.length > 128) throw failed(executor, "Docker server version");
+  const uid = (await step(executor, "host uid", "id", ["-u"], runner)).stdout.trim();
+  const gid = (await step(executor, "host gid", "id", ["-g"], runner)).stdout.trim();
+  if (!/^[1-9][0-9]{0,9}$/.test(uid) || !/^[1-9][0-9]{0,9}$/.test(gid)) throw failed(executor, "non-root host uid:gid");
+  const images: ExecutorCheck["images"] = [];
+  for (const image of new Set([protocol.candidate.image, protocol.evaluator.image])) {
+    let present: ProcessResult;
+    try { present = await runOnExecutor(executor, "docker", ["image", "inspect", "--format", "{{.Id}}", image], runner); }
+    catch { throw failed(executor, "image availability"); }
+    if (present.timedOut || present.truncated) throw failed(executor, "image availability");
+    if (present.exitCode !== 0) await step(executor, "image pull", "docker", ["pull", image], runner, { timeoutMs: 300_000 });
+    images.push({ image, available: true });
+  }
+  return { executor, serverVersion: version, user: `${uid}:${gid}`, images, pull: "missing" };
+}
+
+export type Stage = "candidate" | "evaluator";
+export interface ContainerPaths { snapshot: string; output: string; evaluator: string; result: string }
+export interface ContainerOptions { protocol: Protocol; stage: Stage; studyId: string; attemptId: string; user: string; paths: ContainerPaths; seed?: number }
+export function containerName(attemptId: string, stage: Stage): string {
+  if (!/^[a-f0-9]{16}$/.test(attemptId) || !["candidate", "evaluator"].includes(stage)) throw new Error("container identity: invalid attempt or stage; use a 16-hex attempt id and candidate or evaluator stage");
+  return `ares-${attemptId}-${stage}`;
+}
+/** Mounts are fixed by stage, never supplied as free-form Docker options. */
+export function buildContainerArgs(options: ContainerOptions): string[] {
+  const p = validateProtocol(options.protocol), name = containerName(options.attemptId, options.stage);
+  const seed = options.seed === undefined ? p.seeds[0]! : options.seed;
+  if (!Number.isSafeInteger(seed) || !p.seeds.includes(seed)) throw new Error("container seed: undeclared or non-integer; choose a seed from protocol.seeds for ares attempt run --seed N");
+  if (!/^[A-Za-z0-9_-]{1,80}$/.test(options.studyId)) throw new Error("study id: invalid label; use the id from study.json");
+  if (!/^[1-9][0-9]{0,9}:[1-9][0-9]{0,9}$/.test(options.user)) throw new Error("container user: non-root uid:gid required; use the user reported by ares executor check");
+  const paths = Object.fromEntries(Object.entries(options.paths).map(([key, value]) => [key, directory(value, `container.paths.${key}`)])) as unknown as ContainerPaths;
+  // Prevent a broad snapshot/output mount from exposing evaluator data or result storage.
+  const sources = [paths.snapshot, paths.output, paths.evaluator, paths.result];
+  for (let a = 0; a < sources.length; a++) for (let b = a + 1; b < sources.length; b++) {
+    const x = sources[a]!, y = sources[b]!;
+    if (!x || !y || x === y || x.startsWith(y === "/" ? y : `${y}/`) || y.startsWith(x === "/" ? x : `${x}/`)) throw new Error("container mounts: overlapping sources; use separate snapshot, output, evaluator and result directories");
+  }
+  const argv = ["run", "--detach", "--pull", "missing", "--name", name, "--label", `ares.study=${options.studyId}`, "--label", `ares.attempt=${options.attemptId}`, "--label", `ares.stage=${options.stage}`,
+    "--network", "none", "--read-only", "--tmpfs", "/tmp", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--user", options.user,
+    "--cpus", String(p.limits.cpus), "--memory", `${p.limits.memoryMb}m`, "--pids-limit", String(p.limits.pidsLimit), "--env", `ARES_SEED=${seed}`];
+  if (p.limits.gpus > 0) argv.push("--gpus", String(p.limits.gpus));
+  const mount = (source: string, target: string, readonly: boolean) => argv.push("--mount", `type=bind,src=${source},dst=${target}${readonly ? ",readonly" : ""}`);
+  if (options.stage === "candidate") {
+    mount(paths.snapshot, "/workspace", true); mount(paths.output, "/out", false);
+    argv.push("--workdir", "/workspace");
+    for (const [key, value] of Object.entries(p.candidate.env ?? {})) argv.push("--env", `${key}=${value}`);
+  } else {
+    mount(paths.evaluator, "/eval", true); mount(paths.output, "/candidate", true); mount(paths.result, "/result", false);
+    argv.push("--workdir", "/eval");
+  }
+  argv.push(p[options.stage].image, ...p[options.stage].command);
+  return argv;
+}
+
+/** Launch on the executor host; stdio is detached so SSH returns immediately. T3 reconciles deadlines as a backstop. */
+export async function startWatchdog(executor: Executor, attemptId: string, stage: Stage, wallSeconds: number, runner: ProcessRunner = spawnRunner, containerId?: string): Promise<void> {
+  const name = containerName(attemptId, stage);
+  if (containerId !== undefined && !/^[a-f0-9]{64}$/.test(containerId)) throw new Error("watchdog container id: invalid; use the full id returned by the verified container start");
+  if (!Number.isSafeInteger(wallSeconds) || wallSeconds < 1 || wallSeconds > 604_800) throw new Error("watchdog deadline: invalid wallSeconds; use the validated protocol limit (1..604800 seconds)");
+  const script = `nohup sh -c ${shellQuote(`sleep ${wallSeconds}; docker kill ${containerId ?? name}`)} </dev/null >/dev/null 2>&1 &`;
+  await step(executor, "watchdog start", "sh", ["-c", script], runner);
+}

package/src/exp/final.ts

@@ -0,0 +1,197 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { commit, onlyKeys, openStudy, plain, readTextBounded, requireExperiment, sha256, assertWritable, gateState, readLedger, requireGate, type Actor, type LedgerEvent } from "../study.ts";
+import { readDesign, readProtocol, type Protocol } from "./protocol.ts";
+import { listAttempts, type Attempt, type AttemptStatus } from "./attempts.ts";
+import { ablateResultPath, ABLATE_BYTES, foldAblations, readClosedAblate } from "./ablate.ts";
+import { INVESTIGATE_BYTES, investigateResultPath, metricValue, pairSamples, readClosedInvestigation, type PairedSamples, type Sample } from "./investigate.ts";
+import { readSelection } from "./selection.ts";
+
+export interface FinalSeeds { v: 1; seeds: number[] }
+export const FINAL_SEEDS_BYTES = 65_536;
+const compatible = "use an ares version that supports this final-seeds file, keeping design/final.json unchanged";
+export function finalSeedsPath(dir: string): string { return join(dir, "design", "final.json"); }
+export function validateFinalSeeds(raw: unknown, protocol: Protocol): FinalSeeds {
+  try {
+    if (!plain(raw)) throw new Error("final seeds: JSON object required");
+    if (raw.v !== 1) throw new Error(`final seeds.v: unsupported version; ${compatible}`);
+    onlyKeys(raw, ["v", "seeds"], "final seeds");
+    const max = Math.floor(protocol.seeds.length / 2);
+    if (!max) throw new Error("final seeds: protocol needs at least two declared seeds to reserve at most half");
+    if (!Array.isArray(raw.seeds) || !raw.seeds.length || raw.seeds.length > max) throw new Error(`final seeds.seeds: nonempty list of at most ${max} seeds required (half the declared protocol seeds)`);
+    if (raw.seeds.some(s => !Number.isSafeInteger(s) || !protocol.seeds.includes(s as number))) throw new Error("final seeds.seeds: undeclared seed; use only declared integer protocol seeds");
+    if (new Set(raw.seeds).size !== raw.seeds.length) throw new Error("final seeds.seeds: duplicate seed; name each reserved seed once");
+    return { v: 1, seeds: [...raw.seeds] as number[] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "final seeds: invalid input";
+    throw new Error(message.includes(compatible) ? message : `${message}; correct the file or protocol and run ares final seeds <dir> --file PATH again`);
+  }
+}
+function record(dir: string, protocol: Protocol): { value: FinalSeeds; text: string } | undefined {
+  const file = finalSeedsPath(dir);
+  if (!existsSync(file)) return undefined;
+  let text: string;
+  try { text = readTextBounded(file, FINAL_SEEDS_BYTES); }
+  catch { throw new Error(`design/final.json: unreadable, non-regular, invalid UTF-8 or larger than ${FINAL_SEEDS_BYTES} bytes; restore a valid regular final-seeds file within this bound`); }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { throw new Error("design/final.json: invalid JSON; restore the last valid final-seeds file before continuing"); }
+  return { value: validateFinalSeeds(raw, protocol), text };
+}
+export function readFinalSeeds(dir: string, protocol: Protocol): FinalSeeds | undefined { return record(dir, protocol)?.value; }
+export function finalSeedsHash(dir: string, protocol: Protocol): string | undefined {
+  const value = record(dir, protocol); return value === undefined ? undefined : sha256(value.text);
+}
+/** Caller holds the study lock; identical bytes never move the reservation event boundary. */
+export function setFinalSeeds(dir: string, raw: unknown, protocol: Protocol, actor: Actor, readUsedSeeds: () => ReadonlySet<number>) {
+  requireExperiment(openStudy(dir).study);
+  const final = validateFinalSeeds(raw, protocol), previous = record(dir, protocol), text = JSON.stringify(final, null, 2) + "\n", hash = sha256(text), changed = previous?.text !== text;
+  if (changed) {
+    const used = readUsedSeeds();
+    const seen = final.seeds.find(seed => used.has(seed));
+    if (seen !== undefined) throw new Error(`final seeds: seed ${seen} was already used by an existing attempt; choose an unused declared seed`);
+    commit(dir, [[finalSeedsPath(dir), text, FINAL_SEEDS_BYTES]], [{ actor, type: "final.seeds.set", data: { sha256: hash, seeds: final.seeds } }]);
+  }
+  return { final, sha256: hash, changed };
+}
+
+
+export const FINAL_RESULT_BYTES = 1_048_576;
+function finalError(reason: string): never { throw new Error(`final: ${reason}; inspect ares gate list and close the current investigate/ablate inputs before retrying final`); }
+function resultBytes(file: string, bound: number, phase: string): string | undefined {
+  if (!existsSync(file)) return undefined;
+  let text: string;
+  try { text = readTextBounded(file, bound); } catch { finalError(`${phase} result is unreadable, invalid UTF-8 or oversized; restore its last valid bounded file`); }
+  let raw: unknown; try { raw = JSON.parse(text); } catch { finalError(`${phase} result JSON is malformed; restore its last valid file`); }
+  if (!plain(raw) || raw.v !== 1) throw new Error(`${phase} result: unsupported version; use an ares version that supports it, keeping the original file unchanged`);
+  return text;
+}
+/** Content changes reopen approval even before the changed result has been reclosed. */
+export function finalGateBinding(dir: string): string | undefined {
+  const { study } = openStudy(dir); if (study.mode !== "experiment") return undefined;
+  const protocol = readProtocol(dir); if (!protocol || !readFinalSeeds(dir, protocol)) return undefined;
+  const rule = readSelection(dir, protocol); if (!rule) return undefined;
+  const investigate = resultBytes(investigateResultPath(dir, rule.run), INVESTIGATE_BYTES, "investigate");
+  if (investigate === undefined) return undefined;
+  const raw = JSON.parse(investigate) as Record<string, unknown>;
+  if (!plain(raw.winner) || typeof raw.winner.commit !== "string" || !/^[a-f0-9]{40}$/.test(raw.winner.commit)) return undefined;
+  const ablate = resultBytes(ablateResultPath(dir), ABLATE_BYTES, "ablate");
+  if (foldAblations(readLedger(dir)).length && ablate === undefined) return undefined;
+  const design = readDesign(dir); if (!design) return undefined;
+  return sha256(JSON.stringify([sha256(investigate), ablate === undefined ? null : sha256(ablate), design.binding]));
+}
+export function requireFinalInputs(dirArg: string) {
+  const { dir, study } = openStudy(dirArg); requireExperiment(study);
+  const design = readDesign(dir); if (!design) finalError("protocol missing; set an experiment protocol first");
+  const final = readFinalSeeds(dir, design.protocol); if (!final) finalError("reserved seeds missing; run ares final seeds --file PATH first");
+  const rule = readSelection(dir, design.protocol); if (!rule) finalError("selection missing; run ares selection --file PATH first");
+  const investigate = readClosedInvestigation(dir); if (!investigate.result.winner) finalError("investigation has no winner");
+  const required = foldAblations(readLedger(dir)).length > 0;
+  const ablate = required || existsSync(ablateResultPath(dir)) ? readClosedAblate(dir) : undefined;
+  const binding = finalGateBinding(dir); if (!binding) finalError("closed upstream results are incomplete");
+  return { dir, study, design, final, rule, investigate, ablate, binding, winner: investigate.result.winner.commit, baseline: rule.baseline.commit };
+}
+function winnerChanged(attempts: Attempt[], events: LedgerEvent[], winner: string, baseline: string, seeds: number[]): boolean {
+  let latest: string | undefined;
+  const history = new Map<string, string | undefined>();
+  for (const event of events) {
+    if (event.type === "investigate.closed") latest = typeof event.data.winner === "string" ? event.data.winner : undefined;
+    if (event.type === "attempt.started" && typeof event.data.id === "string") history.set(event.data.id, latest);
+  }
+  return attempts.some(a => {
+    if (a.finalWinner !== undefined && (typeof a.finalWinner !== "string" || !/^[a-f0-9]{40}$/.test(a.finalWinner))) finalError(`attempt ${a.id} has malformed final winner metadata; restore its valid record`);
+    const original = a.finalWinner ?? history.get(a.id);
+    return (original !== undefined && original !== winner) || (seeds.includes(a.seed) && a.commit !== winner && a.commit !== baseline);
+  });
+}
+/** Called under the study lock before snapshot resolution and again before record creation. */
+export function authorizeFinalAttempt(dir: string, commit: string, seed: number): { binding: string; auto: boolean; winner: string } {
+  const input = requireFinalInputs(dir);
+  if (!input.final.seeds.includes(seed)) finalError(`seed ${seed} is not reserved; choose a seed from design/final.json`);
+  if (typeof commit !== "string" || !/^[a-fA-F0-9]{40}$/.test(commit)) finalError("commit must be a full 40-hex SHA; choose the winner or baseline frozen commit");
+  const normalized = commit.toLowerCase();
+  if (normalized !== input.winner && normalized !== input.baseline) finalError("commit is neither the investigate winner nor selection baseline; choose one of those frozen commits");
+  if (winnerChanged(listAttempts(input.dir, { run: "final" }).attempts, readLedger(input.dir), input.winner, input.baseline, input.final.seeds)) finalError("winner changed after a final attempt; approve the current final gate and run ares final close to record winner-changed, never start a second final");
+  const approvals = requireGate(dir, input.study, "final", () => input.binding);
+  return { binding: input.binding, auto: approvals.length > 0, winner: input.winner };
+}
+interface FinalAttempt { id: string; commit: string; seed: number; status: AttemptStatus; decisive: boolean; reason?: string; retryOf?: string }
+export interface FinalResult {
+  v: 1; status: "qualified" | "not_qualified"; reason?: string; winner: string; baseline: string; seeds: number[];
+  pairs: PairedSamples["pairs"]; mean: number | null; baselineMean: number | null; delta: number | null;
+  decisive: FinalAttempt[]; attempts: FinalAttempt[]; investigateSha256: string; ablateSha256?: string; sealBinding: string; inputsSha256: string;
+}
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (plain(value)) return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+export function finalResultPath(dir: string): string { return join(dir, "runs", "final", "final.json"); }
+/** Earliest start decides even on failure; newer retries never replace its outcome. */
+function calculateFinal(input: ReturnType<typeof requireFinalInputs>): FinalResult {
+  const attempts = listAttempts(input.dir, { run: "final" }).attempts;
+  if (attempts.some(a => a.status === "running")) throw new Error("final close: a final attempt is running; run ares attempt reconcile before closing");
+  const events = readLedger(input.dir);
+  if (gateState("final", events, () => input.binding).state !== "approved") finalError("gate is not currently approved; run ares gate approve <dir> final after closing changed inputs");
+  const changedWinner = winnerChanged(attempts, events, input.winner, input.baseline, input.final.seeds);
+  const starts = new Map<string, { index: number; data: Record<string, unknown> }>();
+  events.forEach((e, index) => { if (e.type === "attempt.started" && typeof e.data.id === "string") { if (starts.has(e.data.id)) finalError(`duplicate start receipt for ${e.data.id}; restore the valid ledger`); starts.set(e.data.id, { index, data: e.data }); } });
+  const ordered = [...attempts].sort((a, b) => (starts.get(a.id)?.index ?? -1) - (starts.get(b.id)?.index ?? -1) || a.id.localeCompare(b.id));
+  const chosen = new Map<string, Attempt>(), rows: FinalAttempt[] = [];
+  for (const a of ordered) {
+    if (a.studyId !== input.study.id || typeof a.commit !== "string" || !/^[a-f0-9]{40}$/.test(a.commit) || !Number.isSafeInteger(a.seed)) finalError(`attempt ${a.id} has invalid study/commit/seed metadata`);
+    const required = input.final.seeds.includes(a.seed), start = starts.get(a.id);
+    if (required && (!start || start.data.run !== "final" || start.data.commit !== a.commit || start.data.seed !== a.seed)) finalError(`attempt ${a.id} has no matching start receipt; restore its ledger evidence`);
+    const key = `${a.commit}:${a.seed}`, decisive = required && !chosen.has(key);
+    if (decisive) chosen.set(key, a);
+    rows.push({ id: a.id, commit: a.commit, seed: a.seed, status: a.status, decisive, ...(!required ? { reason: "outside-final-pairs" } : !decisive ? { reason: "later-attempt" } : {}), ...(a.retryOf ? { retryOf: a.retryOf } : {}) });
+  }
+  if (!changedWinner) for (const commit of [input.winner, input.baseline]) for (const seed of input.final.seeds) if (!chosen.has(`${commit}:${seed}`)) finalError(`missing decisive attempt for commit ${commit} seed ${seed}; finish every reserved winner/baseline pair`);
+  const decisive = rows.filter(a => a.decisive), firstFailure = decisive.find(a => a.status !== "succeeded");
+  let reason: string | undefined = changedWinner ? "winner-changed" : [...chosen.values()].some(a => a.protocolHash !== input.investigate.result.protocolHash) ? "protocol-changed" : firstFailure?.status;
+  const samples = (commit: string): Sample[] => input.final.seeds.flatMap(seed => {
+    const a = chosen.get(`${commit}:${seed}`);
+    if (!a || a.status !== "succeeded" || a.protocolHash !== input.investigate.result.protocolHash) return [];
+    return [{ seed, attempt: a.id, value: metricValue(a, input.investigate.result.metric) }];
+  });
+  const paired = pairSamples(samples(input.winner), samples(input.baseline), input.investigate.result.metric.direction, input.winner);
+  if (!reason) {
+    if (paired.delta === null || paired.delta <= 0 || paired.delta < input.rule.minDelta) reason = "below-margin";
+  }
+  const result: FinalResult = { v: 1, status: reason ? "not_qualified" : "qualified", ...(reason ? { reason } : {}), winner: input.winner, baseline: input.baseline, seeds: input.final.seeds, pairs: paired.pairs, mean: paired.mean, baselineMean: paired.referenceMean, delta: paired.delta, decisive, attempts: rows, investigateSha256: input.investigate.sha256, ...(input.ablate ? { ablateSha256: input.ablate.sha256 } : {}), sealBinding: input.design.binding,
+    inputsSha256: sha256(canonical({ binding: input.binding, attempts: ordered.map(a => ({ record: sha256(canonical(a)), start: starts.get(a.id)?.index ?? null })) })) };
+  const text = JSON.stringify(result, null, 2) + "\n"; assertWritable(text, FINAL_RESULT_BYTES, "final result; archive the study and start a new bounded run");
+  return result;
+}
+/** Caller holds the study lock; calculation and output bytes are shared with the read-only closed reader. */
+export function closeFinal(dirArg: string, actor: Actor): FinalResult {
+  const input = requireFinalInputs(dirArg), file = finalResultPath(input.dir), old = resultBytes(file, FINAL_RESULT_BYTES, "final");
+  const result = calculateFinal(input), text = JSON.stringify(result, null, 2) + "\n";
+  if (old !== text) commit(input.dir, [[file, text, FINAL_RESULT_BYTES]], [{ actor, type: "final.closed", data: { sha256: sha256(text), status: result.status, investigateSha256: result.investigateSha256 } }]);
+  return result;
+}
+/** Only the exact currently computable result, under current gate approval, is a closed source. */
+export function readClosedFinal(dirArg: string): { result: FinalResult; sha256: string } {
+  const input = requireFinalInputs(dirArg), text = resultBytes(finalResultPath(input.dir), FINAL_RESULT_BYTES, "final");
+  if (text === undefined) throw new Error("final result: not closed; run ares final close before using final results");
+  const hash = sha256(text), receipt = readLedger(input.dir).findLast(event => event.type === "final.closed");
+  if (!receipt || receipt.data.sha256 !== hash) throw new Error("final result: bytes disagree with the latest close receipt; run ares final close again");
+  const result = calculateFinal(input);
+  if (text !== JSON.stringify(result, null, 2) + "\n") throw new Error("final result: stale inputs; approve current final inputs and run ares final close again");
+  return { result, sha256: hash };
+}
+
+
+/** Historical closure is sufficient: exploratory work never refreshes or rewrites final inputs. */
+export function requirePosthocClosed(dir: string): void {
+  requireExperiment(openStudy(dir).study);
+  if (!readLedger(dir).some(event => event.type === "final.closed")) throw new Error("posthoc: final has not been closed; run ares final close <dir> before starting exploratory attempts");
+}
+export function showPosthoc(dirArg: string) {
+  const { dir, study } = openStudy(dirArg); requireExperiment(study);
+  const attempts = listAttempts(dir, { run: "posthoc" }).attempts.map(attempt => ({
+    id: attempt.id, commit: attempt.commit, seed: attempt.seed, status: attempt.status,
+    label: "exploratory" as const, metrics: attempt.metrics,
+    ...(attempt.reason ? { reason: attempt.reason } : {}), ...(attempt.retryOf ? { retryOf: attempt.retryOf } : {}),
+  }));
+  return { run: "posthoc" as const, label: "exploratory" as const, attempts };
+}

package/src/exp/ideas.ts

@@ -0,0 +1,117 @@
+import { boundedText, commit, onlyKeys, openStudy, plain, readLedger, requireExperiment, type Actor, type LedgerEvent } from "../study.ts";
+import { listAttempts } from "./attempts.ts";
+
+export const MAX_IDEAS = 1000, MAX_DECISION_ATTEMPTS = 200;
+export interface IdeaInput { id: string; title: string; hypothesis: string; parent?: string; commit?: string }
+export interface IdeaDecision { decision: "refine" | "pivot"; reason: string; attempts: string[]; commit?: string; cause?: string; retryWhen?: string }
+export interface Idea { id: string; title: string; hypothesis: string; parent?: string; commits: string[]; state: "open" | "pivoted"; decisions: IdeaDecision[] }
+const recovery = "; correct the idea input and retry ares idea add or ares idea decide";
+function bad(reason: string): never { throw new Error(`idea: ${reason}${recovery}`); }
+function name(raw: unknown, field: string): string {
+  if (typeof raw !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(raw)) bad(`${field}: use 1..64 letters, digits, underscores or hyphens, starting with a letter or digit`);
+  return raw;
+}
+function commitId(raw: unknown): string {
+  if (typeof raw !== "string" || !/^[a-fA-F0-9]{40}$/.test(raw)) bad("commit: full 40-hex SHA required");
+  return raw.toLowerCase();
+}
+function validateIdea(raw: unknown, strict: boolean): IdeaInput {
+  if (!plain(raw)) bad("JSON object required");
+  if (strict) onlyKeys(raw, ["id", "title", "hypothesis", "parent", "commit"], "idea");
+  return { id: name(raw.id, "id"), title: boundedText(raw.title, "idea.title", 500), hypothesis: boundedText(raw.hypothesis, "idea.hypothesis", 4000),
+    ...(raw.parent !== undefined ? { parent: name(raw.parent, "parent") } : {}), ...(raw.commit !== undefined ? { commit: commitId(raw.commit) } : {}) };
+}
+function pivotContext(raw: Record<string, unknown>, strict: boolean): Pick<IdeaDecision, "cause" | "retryWhen"> {
+  if (strict && raw.decision !== "pivot" && (raw.cause !== undefined || raw.retryWhen !== undefined)) bad("cause and retryWhen are pivot-only; omit --cause and --retry-when for refine");
+  const extra: { cause?: string; retryWhen?: string } = {};
+  for (const field of ["cause", "retryWhen"] as const) if (raw[field] !== undefined && raw.decision === "pivot") {
+    const value = boundedText(raw[field], `idea ${field}`, 2000);
+    if (Buffer.byteLength(value) > 2000) bad(`${field}: at most 2000 bytes required`);
+    extra[field] = value;
+  }
+  return extra;
+}
+function validateDecision(raw: unknown, strict: boolean): IdeaDecision {
+  if (!plain(raw)) bad("decision object required");
+  if (strict) onlyKeys(raw, ["decision", "reason", "attempts", "commit", "cause", "retryWhen"], "idea decision");
+  if (raw.decision !== "refine" && raw.decision !== "pivot") bad("decision: use refine or pivot");
+  // Reject new pivot commit options; keep older ledger entries readable on replay.
+  if (strict && raw.decision === "pivot" && raw.commit !== undefined) bad("pivot does not take --commit; omit --commit, or use refine to attach a commit");
+  const extra = pivotContext(raw, strict);
+  const reason = boundedText(raw.reason, "idea reason", 2000);
+  if (Buffer.byteLength(reason) > 2000) bad("reason: at most 2000 bytes required");
+  if (raw.attempts !== undefined && (!Array.isArray(raw.attempts) || raw.attempts.length > MAX_DECISION_ATTEMPTS || raw.attempts.some(a => typeof a !== "string" || !/^[a-f0-9]{16}$/.test(a)))) bad(`attempts: name at most ${MAX_DECISION_ATTEMPTS} 16-hex attempt ids from ares attempt list`);
+  if (raw.decision === "refine" && raw.commit === undefined) bad("refine requires --commit with a full frozen SHA");
+  return { decision: raw.decision, reason, ...extra, attempts: [...new Set((raw.attempts as string[] | undefined) ?? [])], ...(raw.commit !== undefined ? { commit: commitId(raw.commit) } : {}) };
+}
+function claim(ideas: Iterable<Idea>, id: string, frozen?: string): void {
+  if (!frozen) return;
+  for (const other of ideas) if (other.id !== id && other.commits.includes(frozen)) bad(`commit already belongs to idea ${other.id}; choose another commit or refine that idea`);
+}
+function evidenceRequired(target: Idea, input: IdeaDecision): void {
+  if (target.commits.length && !input.attempts.length) bad(`idea ${target.id} has commits; pass --attempts with terminal evidence from those commits`);
+  if (!target.commits.length && input.attempts.length) bad(`idea ${target.id} has no commit; omit --attempts when attaching its first commit or dropping it before testing`);
+}
+function safe<T>(fn: () => T): T {
+  try { return fn(); } catch (error) { const message = error instanceof Error ? error.message : "idea: invalid input"; throw new Error(message.includes(recovery) ? message : message + recovery); }
+}
+/** Replay the journal only; unknown event kinds and additive event fields are preserved in the ledger. */
+export function foldIdeas(events: LedgerEvent[]): Idea[] {
+  return safe(() => {
+    const ideas = new Map<string, Idea>();
+    for (const event of events) {
+      if (event.type === "idea.added") {
+        const input = validateIdea(event.data.idea, false);
+        if (ideas.has(input.id)) bad(`duplicate id ${input.id}; choose a new idea id`);
+        if (ideas.size >= MAX_IDEAS) bad(`limit ${MAX_IDEAS} reached; start a new study for more ideas`);
+        if (input.parent !== undefined && !ideas.has(input.parent)) bad(`parent ${input.parent} does not exist; add its parent idea first`);
+        claim(ideas.values(), input.id, input.commit);
+        ideas.set(input.id, { id: input.id, title: input.title, hypothesis: input.hypothesis, ...(input.parent !== undefined ? { parent: input.parent } : {}), commits: input.commit ? [input.commit] : [], state: "open", decisions: [] });
+      } else if (event.type === "idea.decided") {
+        const id = name(event.data.id, "id"), input = validateDecision(event.data, false), target = ideas.get(id);
+        if (!target) bad(`unknown id ${id}; add the idea before deciding`);
+        if (target.state === "pivoted") bad(`idea ${id} is pivoted; add a new child idea instead of deciding it again`);
+        evidenceRequired(target, input);
+        if (input.decision === "refine") claim(ideas.values(), id, input.commit);
+        if (input.decision === "refine" && !target.commits.includes(input.commit!)) target.commits.push(input.commit!);
+        if (input.decision === "pivot") target.state = "pivoted";
+        target.decisions.push(input);
+      }
+    }
+    return [...ideas.values()];
+  });
+}
+/** Caller holds the study lock; the journal is the only write. */
+export function addIdea(dir: string, raw: unknown, actor: Actor): Idea {
+  return safe(() => {
+    requireExperiment(openStudy(dir).study);
+    const input = validateIdea(raw, true), events = readLedger(dir), ideas = foldIdeas(events);
+    if (ideas.some(i => i.id === input.id)) bad(`duplicate id ${input.id}; choose a new idea id`);
+    if (ideas.length >= MAX_IDEAS) bad(`limit ${MAX_IDEAS} reached; start a new study for more ideas`);
+    if (input.parent !== undefined && !ideas.some(i => i.id === input.parent)) bad(`parent ${input.parent} does not exist; add its parent idea first`);
+    claim(ideas, input.id, input.commit);
+    const added = commit(dir, [], [{ actor, type: "idea.added", data: { idea: input } }]);
+    return foldIdeas([...events, ...added]).find(i => i.id === input.id)!;
+  });
+}
+/** Validate all evidence before committing the decision; a failed decision never changes the journal. */
+export function decideIdea(dir: string, idArg: string, raw: unknown, actor: Actor): Idea {
+  return safe(() => {
+    const { study } = openStudy(dir); requireExperiment(study);
+    const id = name(idArg, "id"), input = validateDecision(raw, true), events = readLedger(dir), ideas = foldIdeas(events), target = ideas.find(i => i.id === id);
+    if (!target) bad(`unknown id ${id}; add the idea before deciding`);
+    if (target.state === "pivoted") bad(`idea ${id} is pivoted; add a new child idea instead of deciding it again`);
+    evidenceRequired(target, input);
+    if (input.decision === "refine") claim(ideas, id, input.commit);
+    const attempts = new Map((input.attempts.length ? listAttempts(dir).attempts : []).map(a => [a.id, a]));
+    for (const wanted of input.attempts) {
+      const attempt = attempts.get(wanted);
+      if (!attempt) bad(`attempt ${wanted} does not exist; choose an id from ares attempt list`);
+      if (attempt.studyId !== study.id) bad(`attempt ${wanted} belongs to another study; choose this study's attempt`);
+      if (attempt.status === "running") bad(`attempt ${wanted} is running; run ares attempt reconcile before deciding`);
+      if (!target.commits.includes(attempt.commit)) bad(`attempt ${wanted} belongs to a foreign commit; cite only this idea's existing commits`);
+    }
+    const added = commit(dir, [], [{ actor, type: "idea.decided", data: { id, ...input } }]);
+    return foldIdeas([...events, ...added]).find(i => i.id === id)!;
+  });
+}