@staix/agent-research 0.1.0 → 0.2.1

package/src/study-export.ts

@@ -0,0 +1,254 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, isAbsolute, sep } from "node:path";
+import { readAttemptRecords, type Attempt, type AttemptStatus } from "./exp/attempts.ts";
+import { ablateResultPath, readClosedAblate } from "./exp/ablate.ts";
+import { finalResultPath, readClosedFinal } from "./exp/final.ts";
+import { readClosedInvestigation } from "./exp/investigate.ts";
+import { readSelection } from "./exp/selection.ts";
+import { designBinding, protocolHash, readProtocol } from "./exp/protocol.ts";
+import { FORMAT_VERSIONS } from "./manifest.ts";
+import { PAPER_EVIDENCE_BYTES, paperBuildPaths } from "./paper/build.ts";
+import { assertWritable, openStudy, plain, readLedger, readTextBounded, sha256, withLock, writeAtomic, type LedgerEvent } from "./study.ts";
+
+/** Reader bound for every bundle file; writeAtomic refuses anything larger. */
+export const BUNDLE_FILE_BYTES = 64 * 1024 * 1024;
+export const BUNDLE_FILES = ["manifest.json", "ledger.jsonl", "attempts.jsonl", "results.json", "reviews.jsonl", "evidence.json"] as const;
+const STATUSES: AttemptStatus[] = ["running", "succeeded", "failed", "cancelled", "unknown"];
+const SHA256 = /^[a-f0-9]{64}$/;
+const HEX = /^[a-f0-9]{16,64}$/;
+const TOKEN = /^[a-z][a-z0-9_.:-]{0,47}$/;
+const GIT_ID = /^[a-f0-9]{40}$/, ATTEMPT_ID = /^[a-f0-9]{16}$/;
+const ACTOR_KINDS = new Set(["person", "agent", "auto"]), EVIDENCE_FAMILIES = new Set(["attempt", "posthoc", "investigate", "ablate", "final"]);
+/** Exact-shape field or null: hand-edited free text in an identity field is never copied. */
+const shaped = (value: unknown, pattern: RegExp): string | null => typeof value === "string" && pattern.test(value) ? value : null;
+const finite = (value: unknown): number | null => typeof value === "number" && Number.isFinite(value) ? value : null;
+const METRIC_KEYS = new Set(["name", "unit", "metric"]);
+/** Closed data keys per ledger event type; unlisted types keep the envelope with empty data. Never host, containerId or hubProject. */
+const LEDGER_KEYS: Record<string, readonly string[]> = {
+  "scope.set": ["sha256"], "autonomy.set": ["from", "to", "phase"], "gate.approve": ["gate", "binding"], "gate.reject": ["gate", "binding"],
+  "lit.search": ["sources", "added", "merged", "total"], "lit.screen": ["decision"], "lit.card": ["id", "sha256"], "lit.bib": ["entries", "sha256"], "lit.verify": ["verified", "failed"],
+  "archive.exported": ["fingerprint"], "skill.proposed": ["skillProposal", "sha256"], "skill.decided": ["skillProposal", "decision"], "watch.set": ["sha256"],
+  "plan.set": ["revision", "state", "sha256"], "plan.gates": ["revision"], "plan.paused": ["revision"], "plan.control": ["revision"], "node.observed": ["revision", "status"], "node.intent": ["revision"],
+  "executor.set": ["kind"], "protocol.set": ["sha256", "protocolHash", "treeHash"], "selection.set": ["sha256", "metric"], "final.seeds.set": ["sha256"],
+  "investigate.closed": ["run", "sha256", "ruleSha256", "winner"], "ablate.closed": ["sha256", "investigateSha256"], "final.closed": ["sha256", "status", "investigateSha256"],
+  "idea.decided": ["decision"], "paper.built": ["manuscriptSha256", "evidenceSha256", "sourceManuscriptSha256"], "review.added": [], "review.resolved": ["buildSha256"],
+  "attempt.started": ["id", "run", "seed", "commit", "treeId"],
+};
+for (const t of ["attempt.run", "attempt.snapshot", "attempt.stage.changed", "attempt.stage.evidence", "attempt.stage.recovered", "attempt.stage.started", "attempt.succeeded", "attempt.failed", "attempt.cancelled", "attempt.unknown"]) LEDGER_KEYS[t] = ["id", "run", "stage", "status"];
+
+export interface BundleManifest {
+  bundle: 1; formats: typeof FORMAT_VERSIONS; studyIdSha256: string; mode: string; protocolHash: string | null; sealBinding: string | null;
+  window: { from: string | null; to: string | null }; counts: { attempts: number; byStatus: Record<AttemptStatus, number>; byRun: Record<string, Record<AttemptStatus, number>>; ledgerEvents: number; reviews: number };
+  files: Record<string, string>;
+}
+export interface BundleListing { bundle: string; files: string[]; wouldWrite: true }
+
+/** A closed scalar: numbers, booleans, hashes and enum-like tokens survive; free text, paths and URLs do not. */
+function closed(value: unknown): value is number | boolean | string | null {
+  if (value === null || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  return typeof value === "string" && (HEX.test(value) || TOKEN.test(value));
+}
+function reduceData(data: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of keys) { const value = Object.hasOwn(data, key) ? data[key] : undefined; if (closed(value) || (METRIC_KEYS.has(key) && typeof value === "string")) out[key] = value; else if (Array.isArray(value) && value.every(closed)) out[key] = value; }
+  return out;
+}
+/** Result keys that hold free text even when a value happens to be one token. */
+const FREE_TEXT_KEYS = new Set(["removes", "description", "note", "notes", "label", "text", "message", "cause", "retryWhen", "method", "question"]);
+/** Keep numbers, booleans, null, hashes and closed tokens recursively; drop free-text keys and every other string. */
+function project(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(project).filter(v => v !== undefined);
+  if (plain(value)) { const out: Record<string, unknown> = {}; for (const [k, v] of Object.entries(value)) { if (FREE_TEXT_KEYS.has(k)) continue; const p = METRIC_KEYS.has(k) && typeof v === "string" ? v : project(v); if (p !== undefined) out[k] = p; } return out; }
+  return closed(value) ? value : undefined;
+}
+/** A parseable ISO timestamp or null. */
+const isoAt = (value: unknown): string | null => typeof value === "string" && value.length <= 64 && /^\d{4}-\d{2}-\d{2}T[\d:.]+(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value)) ? value : null;
+function reduceEvent(event: LedgerEvent) {
+  const actor = { kind: ACTOR_KINDS.has(event.actor?.kind as string) ? event.actor.kind : "other", ...(event.actor.id !== undefined ? { idSha256: sha256(event.actor.id) } : {}) };
+  const at = isoAt(event.at);
+  return { v: event.v, at, actor, type: TOKEN.test(event.type) ? event.type : "other", data: reduceData(plain(event.data) ? event.data : {}, (Object.hasOwn(LEDGER_KEYS, event.type) ? LEDGER_KEYS[event.type]! : [])) };
+}
+// Closed codes emitted by attempts.ts, metrics.ts and artifacts.ts; never derive a class from user prose.
+const ATTEMPT_REASON_CODES = new Set([
+  "executor-start", "executor-start-uncertain", "preparation", "lost", "wall-clock", "candidate-exit", "evaluator-exit",
+  "evidence-read", "invalid-metrics", "malformed-metrics", "undeclared-metric", "missing-metric", "invalid-metric-value",
+  "nonfinite-metric", "metrics-limit", "duplicate-metric", "missing-metrics", "missing-receipt", "changed-output",
+  "artifact-limit", "artifact-read", "invalid-artifact", "invalid-log-state", "missing-logs",
+]);
+function reasonClass(reason: string | undefined, status: AttemptStatus): string | undefined {
+  if (reason === undefined) return undefined;
+  if (status === "cancelled") return "cancel-reason";
+  return ATTEMPT_REASON_CODES.has(reason) ? reason : "other";
+}
+function duration(start: unknown, end: unknown): number | null {
+  if (typeof start !== "string" || typeof end !== "string") return null;
+  const ms = Date.parse(end) - Date.parse(start);
+  return Number.isFinite(ms) ? ms : null;
+}
+function digest(image: unknown): string | null {
+  const match = typeof image === "string" ? /@(sha256:[a-f0-9]{64})$/.exec(image) : null;
+  return match?.[1] ?? null;
+}
+function attemptRow(a: Attempt) {
+  const stages: Record<string, unknown> = {};
+  for (const name of ["candidate", "evaluator"] as const) {
+    const stage = plain(a.stages) && Object.hasOwn(a.stages, name) ? a.stages[name] : undefined;
+    if (!plain(stage)) continue;
+    stages[name] = { exitCode: Number.isSafeInteger(stage.exitCode) ? stage.exitCode : null, durationMs: duration(stage.startedAt, stage.endedAt), network: stage.network === "none" ? "none" : "other", limits: plain(stage.limits) ? reduceData(stage.limits, ["cpus", "memoryMb", "pidsLimit", "wallSeconds", "gpus"]) : null, imageDigest: digest(stage.image) };
+  }
+  const reason = reasonClass(a.reason, a.status);
+  return {
+    id: a.id, run: a.run, studyIdSha256: sha256(String(a.studyId)), protocolHash: shaped(a.protocolHash, SHA256), sealBinding: shaped(a.sealBinding, SHA256), commit: shaped(a.commit, GIT_ID), treeId: shaped(a.treeId, GIT_ID),
+    snapshotSha256: shaped(a.snapshotSha256, SHA256), seed: Number.isSafeInteger(a.seed) ? a.seed : null, labelSha256: sha256(String(a.label ?? "")), retryOf: shaped(a.retryOf, ATTEMPT_ID), status: a.status, stage: a.stage, ...(reason ? { reasonClass: reason } : {}),
+    durationMs: duration(a.startedAt, a.endedAt), stages,
+    metrics: (Array.isArray(a.metrics) ? a.metrics : []).map(m => ({ name: m.name, unit: m.unit, value: finite(m.value), provenance: m.provenance === "ares-observed" ? "ares-observed" : "other" })),
+    outputs: (Array.isArray(a.outputs) ? a.outputs : []).map(o => ({ sha256: shaped(o.sha256, SHA256), bytes: finite(o.bytes) })),
+    sealing: plain(a.sealing) ? { separateContainers: a.sealing.separateContainers === true, evaluatorReadOnly: a.sealing.evaluatorReadOnly === true, candidateHasNoEvaluator: a.sealing.candidateHasNoEvaluator === true } : null,
+  };
+}
+function closedResult<T>(name: string, read: () => { result: T }): unknown {
+  try { return project(read().result); }
+  catch (error) { throw new Error(`study export: ${name} result is not a verified closed result (${(error as Error).message}); fix it as that message says, then export again`); }
+}
+function reviews(events: LedgerEvent[]) {
+  const resolved = new Map<string, number>();
+  for (const e of events) if (e.type === "review.resolved" && typeof e.data.reviewId === "string") resolved.set(e.data.reviewId, (resolved.get(e.data.reviewId) ?? 0) + 1);
+  return events.filter(e => e.type === "review.added" && plain(e.data.review)).map(e => {
+    const review = e.data.review as Record<string, unknown>, findings = Array.isArray(review.findings) ? review.findings as Record<string, unknown>[] : [];
+    const reviewer = plain(review.reviewer) ? review.reviewer : {}, kinds: Record<string, number> = {};
+    for (const f of findings) { const kind = typeof f.kind === "string" && TOKEN.test(f.kind) ? f.kind : "other"; kinds[kind] = (kinds[kind] ?? 0) + 1; }
+    const id = typeof e.data.id === "string" ? e.data.id : "";
+    const family = typeof reviewer.modelFamily === "string" ? reviewer.modelFamily.trim().toLowerCase() : "";
+    return { idSha256: sha256(id), at: isoAt(e.at), modelFamily: /^[a-z0-9][a-z0-9 ._-]{0,47}$/.test(family) ? family : "other", buildSha256: typeof review.buildSha256 === "string" && HEX.test(review.buildSha256) ? review.buildSha256 : null, findings: findings.length, blocking: findings.filter(f => f.blocking === true).length, kinds, resolved: resolved.get(id) ?? 0 };
+  });
+}
+function evidence(dir: string) {
+  const path = paperBuildPaths(dir).evidence;
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try { raw = JSON.parse(readTextBounded(path, PAPER_EVIDENCE_BYTES)); } catch { throw new Error("study export: paper/build/evidence.json is unreadable, invalid JSON or oversized; rebuild the paper before exporting"); }
+  if (!plain(raw) || raw.v !== 1 || !Array.isArray(raw.placeholders)) throw new Error("study export: paper/build/evidence.json has an unsupported shape; rebuild the paper before exporting");
+  return {
+    v: 1, manuscriptSha256: typeof raw.manuscriptSha256 === "string" && SHA256.test(raw.manuscriptSha256) ? raw.manuscriptSha256 : null,
+    placeholders: (raw.placeholders as Record<string, unknown>[]).filter(p => p.kind === "number").map(p => {
+      const ref = typeof p.ref === "string" ? p.ref : "", attempt = /^(?:attempt|posthoc):([a-f0-9]{16})\./.exec(ref)?.[1];
+      const source = plain(p.source) ? p.source : {};
+      return { refSha256: sha256(ref), family: ((f: string | undefined) => f && EVIDENCE_FAMILIES.has(f) ? f : "other")(/^[a-z]+/.exec(ref)?.[0]), ...(attempt ? { attempt } : {}), sourceSha256: typeof source.sha256 === "string" && SHA256.test(source.sha256) ? source.sha256 : null };
+    }),
+  };
+}
+
+/** Path rules run on decoded keys and string values, so a boundary is a real character (a raw newline or tab included). */
+const PATH_SCANS: RegExp[] = [
+  // POSIX: `/` or `~/` not preceded by a letter, digit or underscore; units such as tokens/s keep a word character there.
+  /(?<![\p{L}\p{N}_])(?:\/|~\/)/u,
+  /\b[A-Za-z]:\\/,
+  // Windows root-relative (\Users\x), bare \ and UNC (\\server): any backslash not preceded by a word character or backslash.
+  /(?<![\p{L}\p{N}_\\])\\/u,
+];
+/** URL, key-like and env rules, also run on decoded strings. */
+const SCANS: [string, RegExp][] = [
+  ["url", /\b[a-z][a-z0-9+.-]*:\/\/|\b(?:mailto|urn|file|data):/i],
+  ["key-like token", /\b(?:sk|pk|rk)[-_][A-Za-z0-9_-]{12,}|\b(?:ghp|gho|ghs|ghu|github_pat)_[A-Za-z0-9_]{12,}|\bxox[abprs]-[A-Za-z0-9-]{8,}|\bAKIA[0-9A-Z]{12,}|\beyJ[A-Za-z0-9_-]{16,}/],
+  ["key-like token", /(?<![A-Za-z0-9_-])(?=[A-Za-z0-9_-]*[A-Z])(?=[A-Za-z0-9_-]*[a-z])(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{32,}(?![A-Za-z0-9_-])/],
+  ["env value", /(?<![A-Za-z0-9_])[A-Za-z_][A-Za-z0-9_]*=[^\s"]/],
+];
+/** Every key and string value of a JSON document, or of each JSONL line; text that is not JSON is scanned as one string. */
+function* decodedStrings(text: string): Generator<string> {
+  const walk = function* (value: unknown): Generator<string> {
+    if (typeof value === "string") yield value;
+    else if (Array.isArray(value)) for (const item of value) yield* walk(item);
+    else if (value && typeof value === "object") for (const [key, item] of Object.entries(value)) { yield key; yield* walk(item); }
+  };
+  let whole: unknown, parsed = false;
+  try { whole = JSON.parse(text); parsed = true; } catch { /* JSONL or plain text */ }
+  if (parsed) { yield* walk(whole); return; }
+  for (const line of text.split("\n")) {
+    if (!line) continue;
+    try { yield* walk(JSON.parse(line)); } catch { yield line; }
+  }
+}
+/** Refuse the whole bundle if any file carries a path, URL, env assignment or key-like token. */
+export function scanBundle(files: Record<string, string>): void {
+  const refuse = (name: string, kind: string): never => { throw new Error(`study export: refused; ${name} would contain a ${kind}. Remove it from the study record (for example an attempt label or ledger field) and retry; nothing was written`); };
+  for (const [name, text] of Object.entries(files)) {
+    for (const value of decodedStrings(text)) {
+      if (PATH_SCANS.some(pattern => pattern.test(value))) refuse(name, "absolute path");
+      for (const [kind, pattern] of SCANS) if (pattern.test(value)) refuse(name, kind);
+    }
+  }
+}
+
+function emptyDir(path: string): void {
+  if (existsSync(path)) { if (!lstatSync(path).isDirectory()) throw new Error("study export: --bundle exists and is not a directory; choose a new or empty directory"); if (readdirSync(path).length) throw new Error("study export: --bundle directory is not empty; choose a new or empty directory"); }
+  else mkdirSync(path, { recursive: true });
+}
+
+/** Real path of the nearest existing ancestor with the missing tail re-appended, so symlinks cannot hide containment. */
+function realTarget(path: string): string {
+  const tail: string[] = [];
+  let current = path;
+  while (!existsSync(current)) { const parent = dirname(current); if (parent === current) break; tail.unshift(basename(current)); current = parent; }
+  return join(realpathSync(current), ...tail);
+}
+/** Caller holds the study lock across every bounded source read. */
+function readBundle(dirArg: string, maxFileBytes: number) {
+  const { dir, study } = openStudy(dirArg);
+  const events = readLedger(dir);
+  const zero = () => Object.fromEntries(STATUSES.map(s => [s, 0])) as Record<AttemptStatus, number>;
+  const byStatus = zero(), runCounts = new Map<string, Record<AttemptStatus, number>>(), attemptLines: string[] = [];
+  let attemptBytes = 0;
+  // One pass; only the projected row and counts outlive each raw record.
+  for (const a of study.mode === "experiment" ? readAttemptRecords(dir) : []) {
+    const line = JSON.stringify(attemptRow(a)) + "\n";
+    attemptBytes += Buffer.byteLength(line);
+    if (attemptBytes > maxFileBytes) throw new Error(`study export: attempts.jsonl would exceed ${maxFileBytes} bytes; nothing was written`);
+    attemptLines.push(line);
+    byStatus[a.status]++;
+    let row = runCounts.get(a.run); if (!row) runCounts.set(a.run, row = zero()); row[a.status]++;
+  }
+  const byRun: Record<string, Record<AttemptStatus, number>> = Object.create(null);
+  for (const [run, row] of [...runCounts].sort(([x], [y]) => x < y ? -1 : 1)) byRun[run] = row;
+  const experiment = study.mode === "experiment", current = experiment ? readProtocol(dir) : undefined, rule = current ? readSelection(dir, current) : undefined;
+  const investigate: Record<string, unknown> = {};
+  if (rule && existsSync(join(dir, "runs", rule.run, "investigate.json"))) investigate[rule.run] = closedResult("investigate", () => readClosedInvestigation(dir));
+  const reviewRows = reviews(events), protocol = study.mode === "experiment" ? readProtocol(dir) : undefined;
+  const lines = (rows: unknown[]) => rows.map(r => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : "");
+  const files: Record<string, string> = {
+    "ledger.jsonl": lines(events.map(reduceEvent)),
+    "attempts.jsonl": attemptLines.join(""),
+    "results.json": JSON.stringify({
+      investigate,
+      ablate: experiment && existsSync(ablateResultPath(dir)) ? closedResult("ablate", () => readClosedAblate(dir)) : null,
+      final: experiment && existsSync(finalResultPath(dir)) ? closedResult("final", () => readClosedFinal(dir)) : null,
+    }, null, 2) + "\n",
+    "reviews.jsonl": lines(reviewRows),
+    "evidence.json": JSON.stringify(evidence(dir), null, 2) + "\n",
+  };
+  const manifest: BundleManifest = {
+    bundle: 1, formats: { ...FORMAT_VERSIONS }, studyIdSha256: sha256(study.id), mode: study.mode,
+    protocolHash: protocol ? protocolHash(protocol) : null, sealBinding: study.mode === "experiment" ? designBinding(dir) ?? null : null,
+    window: (() => { const ats = events.map(e => isoAt(e.at)).filter((v): v is string => v !== null); return { from: ats[0] ?? null, to: ats.at(-1) ?? null }; })(),
+    counts: { attempts: attemptLines.length, byStatus, byRun, ledgerEvents: events.length, reviews: reviewRows.length },
+    files: Object.fromEntries(Object.entries(files).map(([name, text]) => [name, sha256(text)])),
+  };
+  files["manifest.json"] = JSON.stringify(manifest, null, 2) + "\n";
+  return { files, manifest };
+}
+
+/** Read one locked study snapshot, then validate and publish without holding the study lock. */
+export async function exportBundle(dirArg: string, options: { bundle: string; list?: boolean }, maxFileBytes = BUNDLE_FILE_BYTES): Promise<BundleManifest | BundleListing> {
+  const dir = resolve(dirArg), target = resolve(options.bundle), inside = relative(realpathSync(dir), realTarget(target));
+  if (inside === "" || (!(inside === ".." || inside.startsWith(".." + sep)) && !isAbsolute(inside))) throw new Error("study export: --bundle is inside the study directory; choose a directory outside the study");
+  if (options.list) {
+    await withLock(dir, () => openStudy(dir));
+    return { bundle: options.bundle, files: [...BUNDLE_FILES], wouldWrite: true };
+  }
+  const { files, manifest } = await withLock(dir, () => readBundle(dir, maxFileBytes));
+  scanBundle(files);
+  for (const name of BUNDLE_FILES) assertWritable(files[name]!, maxFileBytes, `study export: ${name}; nothing was written`);
+  emptyDir(target);
+  for (const name of BUNDLE_FILES) writeAtomic(join(target, name), files[name]!, maxFileBytes);
+  return manifest;
+}

package/src/study.ts

@@ -1,3 +1,5 @@
+import { validateAutonomy, validateAutonomyMode, resolveAutonomy, ACCEPT_ARTIFACTS, type Autonomy, type Phase, type AcceptArtifact } from "./autonomy.ts";
+export type { Autonomy } from "./autonomy.ts";
 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";
@@ -5,10 +7,9 @@ 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 type GateName = "scope" | "screen" | "design" | "final" | "review" | `plan:${string}` | `accept:${AcceptArtifact}`;
 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 Study { v: 1 | 2; 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");
@@ -105,19 +106,22 @@ export function openStudy(dir: string): { dir: string; study: Study } {
 }
 
 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;
+  if (plain(raw) && raw.v !== 1 && raw.v !== 2) 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 && raw.v !== 2) || typeof raw.id !== "string" || typeof raw.question !== "string" || typeof raw.createdAt !== "string" ||
+    !["survey", "experiment"].includes(raw.mode as string)) throw new Error("study.json: malformed");
+  let autonomy: Autonomy;
+  try { autonomy = validateAutonomy(raw.autonomy); }
+  catch { throw new Error("study.json: unsupported or malformed autonomy policy; restore the last valid study.json or use a compatible ares version before retrying"); }
+  if (raw.v === 1 && (typeof autonomy !== "string" || autonomy === "copilot" || autonomy === "step")) throw new Error("study.json: this autonomy policy requires study v2; restore the valid v1 study and use ares autonomy set with a compatible ares version");
+  return { ...raw, autonomy } 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";
+  const mode = options.mode ?? "survey", autonomy = validateAutonomyMode(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() };
+  const study: Study = { v: autonomy === "auto" || autonomy === "gates" ? 1 : 2, 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`);
@@ -133,10 +137,15 @@ export function initStudy(dir: string, options: { question: string; mode?: strin
 
 /**
  * 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.
+ * ponytail: mtime-based staleness, no owner liveness check. The inode check before unlink is best-effort:
+ * a replacement between lstat and unlink can still be removed, after stale takeover of a live owner has
+ * already broken exclusion. Upgrade path: an owner liveness probe, including shared-host ownership.
  */
+const ownedStudyLocks = new Set<() => void>();
+/** MCP termination only: call immediately before process exit, never while continuing async work. */
+export function releaseStudyLocksForExit(): void { for (const release of [...ownedStudyLocks]) release(); }
 export class StudyLockBusyError extends Error {}
-export async function withLock<T>(dir: string, fn: () => Promise<T> | T): Promise<T> {
+export async function withLock<T>(dir: string, fn: () => Promise<T> | T, inspectOwner: (fd: number) => ReturnType<typeof fstatSync> = fstatSync): Promise<T> {
   const path = join(dir, ".ares.lock");
   let fd: number;
   try { fd = openSync(path, "wx", 0o600); }
@@ -148,8 +157,25 @@ export async function withLock<T>(dir: string, fn: () => Promise<T> | T): Promis
     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 */ } }
+  let owner: ReturnType<typeof fstatSync>;
+  try { owner = inspectOwner(fd); }
+  catch (error) {
+    try { unlinkSync(path); } catch { /* the just-created lock may already be absent */ }
+    finally { try { closeSync(fd); } catch { /* preserve the original probe failure */ } }
+    throw error;
+  }
+  let released = false;
+  const release = () => {
+    if (released) return; released = true;
+    try { const current = lstatSync(path); if (current.dev === owner.dev && current.ino === owner.ino) unlinkSync(path); }
+    catch { /* absent or replaced; never remove a different owner's lock */ }
+    finally { try { closeSync(fd); } catch { /* process exit also closes owned descriptors */ } ownedStudyLocks.delete(release); }
+  };
+  ownedStudyLocks.add(release);
+  try { writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`); }
+  catch (error) { release(); throw error; }
+  // Keep the descriptor open until release so an unlinked inode cannot be reused by a replacement lock.
+  try { return await fn(); } finally { release(); }
 }
 
 export interface PendingEvent { actor: Actor; type: string; data: Record<string, unknown> }
@@ -217,8 +243,9 @@ export function gateState(gate: GateName, events: LedgerEvent[], binder: Binder)
 }
 
 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`);
+  if (!GATES.includes(gate) && !ACCEPT_ARTIFACTS.some(artifact => gate === `accept:${artifact}`) && !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" && gate.startsWith("accept:")) throw new Error(`gate ${gate}: no current copilot draft; inspect ares autonomy show, create the phase artifact, then use ares gate list and ares gate approve <dir> ${gate}`);
   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 } : {}) });
@@ -230,11 +257,12 @@ export function decideGate(dir: string, gate: GateName, decision: "approve" | "r
  * `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[] {
+export function requireGate(dir: string, study: Study, gate: GateName, binder: Binder, guardedPhase?: Phase): 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 === "pending" && !gate.startsWith("accept:") && resolveAutonomy(study.autonomy, gate, guardedPhase) === "auto") return [{ actor: { kind: "auto" }, type: "gate.approve", data: { gate, binding: state.current! } }];
+  if (state.state === "none" && gate.startsWith("accept:")) throw new Error(`gate ${gate}: no current copilot draft; create the phase artifact, then run ares gate list and ares gate approve <dir> ${gate}`);
   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");

package/src/ui/panel.js

@@ -10,6 +10,8 @@ export default (host) => {
   const number = (value) => typeof value === "number" && Number.isFinite(value) ? String(value) : "Unavailable";
   const rows = (value) => Array.isArray(value) ? value : [];
   const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const autonomyLabel = (value) => typeof value === "string" ? text(value)
+    : `${text(record(value).default)}${Object.keys(record(record(value).phases)).length ? " (phase overrides)" : ""}`;
   const line = (value, max = 180) => {
     const valueText = text(value, "").replace(/\s+/g, " ").trim();
     return valueText.length > max ? `${valueText.slice(0, max - 3)}...` : valueText;
@@ -84,7 +86,7 @@ export default (host) => {
         const attempts = study.attempts?.available === false ? `Attempts unavailable: ${line(study.attempts.reason) || "Attempt records could not be read."}` : `${number(study.attempts?.total)} attempts`;
         const pending = rows(study.gates).filter((gate) => gate.state === "pending").length;
         return ui.row({ title: line(study.question) || text(study.id, "Unavailable study"),
-          sub: available ? [text(study.mode), text(study.autonomy), attempts, `${pending} pending gates`, finalState ? `Final ${finalState}` : "Final unavailable", reviewState, watchState].join(" | ") : text(study.reason, "Study cannot be read; its registration is retained."),
+          sub: available ? [text(study.mode), autonomyLabel(study.autonomy), attempts, `${pending} pending gates`, finalState ? `Final ${finalState}` : "Final unavailable", reviewState, watchState].join(" | ") : text(study.reason, "Study cannot be read; its registration is retained."),
           chip: { text: available ? text(study.mode, "study") : "unavailable", tone: available ? "neutral" : "err" },
           ...(typeof study.dir === "string" ? { onOpen: () => go("study", { study: study.dir }) } : {}) });
       }) ?? ui.empty("No registered studies", "Register one with ares console add <dir>. Ares does not scan the disk for studies.")];
@@ -106,8 +108,9 @@ export default (host) => {
     if (!study) return [toolbar("Study", true), ui.notice(text(snapshot.error, "Choose a registered study from the studies panel."), "warn")];
     const sections = [toolbar(text(study.question, "Study"), true), decisionNotice()];
     if (study.available === false) return [...sections, ui.notice(text(study.reason, "Study unavailable; its registration is retained."), "err"), h("p", { class: "ares-sub", text: text(study.dir, "") })];
-    sections.push(h("div", { class: "ares-bar" }, ui.chip(text(study.mode), "neutral"), ui.chip(text(study.autonomy), "neutral")),
+    sections.push(h("div", { class: "ares-bar" }, ui.chip(text(study.mode), "neutral"), ui.chip(autonomyLabel(study.autonomy), "neutral")),
       h("p", { class: "ares-sub", text: text(study.dir, "") }), gateRows(study.gates, study.dir), attemptRows(study.attempts));
+    if (study.autonomy && typeof study.autonomy === "object") sections.push(block("Autonomy policy", study.autonomy));
     const final = record(study.final);
     sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Final status" }),
       typeof final.status === "string" ? ui.chip(final.status, tone(final.status)) : ui.empty("No current closed final"),
@@ -119,11 +122,13 @@ export default (host) => {
       rows(review.openBlocking).length ? ui.notice(`${review.openBlocking.length} blocking findings remain open.`, "warn") : null));
     if (typeof study.manuscript?.id === "string") sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Built manuscript" }),
       ui.link({ asset: study.manuscript.id }, "Open manuscript text")));
+    const investigationArtifact = record(study.investigationArtifact);
+    if (investigationArtifact.state === "missing") sections.push(ui.notice(text(investigationArtifact.message, "Investigation artifact missing; displayed result is recalculated. Restore the artifact or run ares investigate close."), "warn"));
     sections.push(block("Investigation", study.investigation), block("Posthoc exploration", study.posthoc));
     const watch = record(study.watch), watchConfig = record(watch.config);
     sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Watch" }),
       typeof watchConfig.rubric === "string" ? h("div", {}, h("strong", { text: "Display-only rubric" }), h("p", { class: "ares-prose", text: watchConfig.rubric })) : null,
-      ui.rows(rows(watch.runs), (run) => ui.row({ title: run.ok ? "Source answered" : "All sources failed", sub: `${at(run.at)} | ${number(run.added)} added | ${number(run.addedIdsTotal)} recorded ids`, chip: { text: run.ok ? "answered" : "failed", tone: run.ok ? "ok" : "err" } })) ?? ui.empty("No watch runs")));
+      ui.rows(rows(watch.runs), (run) => ui.row({ title: run.ok ? "Source answered" : run.cause === undefined ? "All sources failed" : ["terminated", "filesystem", "internal", "network", "rate", "server", "client", "format"].includes(run.cause) ? `Watch run failed (${run.cause})` : "Watch run failed (unknown cause)", sub: `${at(run.at)} | ${number(run.added)} added | ${number(run.addedIdsTotal)} recorded ids`, chip: { text: run.ok ? "answered" : "failed", tone: run.ok ? "ok" : "err" } })) ?? ui.empty("No watch runs")));
     const candidates = rows(record(watch.newCandidates).candidates).filter((candidate) => candidate.status === "new" && typeof candidate.id === "string");
     sections.push(h("section", { class: "ares-card" }, h("h3", { text: "New candidates" }),
       ui.rows(candidates, (candidate) => ui.row({ title: line(candidate.title) || candidate.id, sub: `${candidate.id}${typeof candidate.year === "number" ? ` | ${candidate.year}` : ""}`, verbs: typeof study.dir === "string" ? [

package/src/ui/plugin.ts

@@ -12,6 +12,7 @@ import { previewArchive, ARCHIVE_NOTES, ArchivePartialError } from "../memory/ar
 import { spawnRunner, type ProcessRunner } from "../exp/executor.ts";
 import { readProtocol } from "../exp/protocol.ts";
 import { readSelection, selectionPath } from "../exp/selection.ts";
+import { investigateResultPath } from "../exp/investigate.ts";
 import { readClosedFinal, finalResultPath } from "../exp/final.ts";
 import { readCurrentBuild, paperBuildPaths } from "../paper/build.ts";
 import { loadCandidates } from "../lit/candidates.ts";
@@ -39,12 +40,13 @@ const stamp = (value: unknown, fallback = EPOCH) => typeof value === "string" &&
 function readCall<T>(name: string, fn: () => T, errors: Record<string, string>): T | null {
   try { return fn(); } catch (cause) { errors[name] = error(cause); return null; }
 }
-interface GateInputs { selectionRun?: string; review?: { manuscriptSha256: string; evidenceSha256: string; ids: ReadonlySet<string> } }
+export interface GateInputs { selectionRun?: string; review?: { manuscriptSha256: string; evidenceSha256: string; ids: ReadonlySet<string> } }
 /** Every gate advances only when an input consumed by its binder changes, never merely on an event kind. */
-function gateWaitingTimes(events: LedgerEvent[], inputs: GateInputs): Map<string, string> {
+export function gateWaitingTimes(events: LedgerEvent[], inputs: GateInputs, observeSignature?: (gate: string, signature: string | undefined) => void): Map<string, string> {
   const waiting = new Map<string, string>(), previous = new Map<string, string | undefined>();
   const observe = (gate: string, input: unknown, at: string) => {
     const signature = input === undefined ? undefined : canonical(input);
+    observeSignature?.(gate, signature);
     if (previous.get(gate) === signature) return;
     previous.set(gate, signature);
     if (signature === undefined) waiting.delete(gate); else waiting.set(gate, at);
@@ -85,8 +87,8 @@ function gateWaitingTimes(events: LedgerEvent[], inputs: GateInputs): Map<string
         experiment(event.at); break;
       case "selection.set": if (typeof data.sha256 === "string") selection = data.sha256; experiment(event.at); break;
       case "final.seeds.set": if (typeof data.sha256 === "string") reserved = data.sha256; experiment(event.at); break;
-      case "investigate.closed": if (data.run === inputs.selectionRun && typeof data.sha256 === "string") investigate = data.sha256; experiment(event.at); break;
-      case "ablate.added": hasAblations = true; experiment(event.at); break;
+      case "investigate.closed": if (data.run === inputs.selectionRun && typeof data.sha256 === "string") investigate = typeof data.winner === "string" && /^[a-f0-9]{40}$/.test(data.winner) ? data.sha256 : undefined; experiment(event.at); break;
+      case "ablation.added": hasAblations = true; experiment(event.at); break;
       case "ablate.closed": if (typeof data.sha256 === "string") ablate = data.sha256; experiment(event.at); break;
       case "paper.built":
         if (typeof data.manuscriptSha256 === "string" && typeof data.evidenceSha256 === "string") paper = [data.manuscriptSha256, data.evidenceSha256];
@@ -124,9 +126,16 @@ function loadStudy(dir: string, features: readonly string[], input: { panel: str
   };
   const status = ops.status(dir), gates = ops.gateList(dir);
   const attempt = study.mode === "experiment" ? readCall("attempts", () => attempts(dir, inbox), errors) : null;
+  let investigationArtifact: { state: "missing"; recalculated: true; message: string } | undefined;
   const investigation = detailed && study.mode === "experiment" ? readCall("investigation", () => {
     const configured = recordPresent(selectionPath(dir)) || events.some(event => event.type === "selection.set" || event.type === "investigate.closed");
-    return configured ? ops.investigateShow(dir) : null;
+    if (!configured) return null;
+    const result = ops.investigateShow(dir);
+    if (events.some(event => event.type === "investigate.closed" && event.data.run === result.run) && !recordPresent(investigateResultPath(dir, result.run))) {
+      investigationArtifact = { state: "missing", recalculated: true,
+        message: `Missing receipted artifact runs/${result.run}/investigate.json; this investigation result is recalculated from current inputs. Restore the artifact or run ares investigate close before using a closed result.` };
+    }
+    return result;
   }, errors) : null;
   const final = study.mode === "experiment" ? readCall("final", () => {
     const recorded = recordPresent(finalResultPath(dir)) || events.some(event => event.type === "final.closed");
@@ -169,7 +178,12 @@ function loadStudy(dir: string, features: readonly string[], input: { panel: str
     const event = attemptEvents.get(`${row.id}:${row.status}`);
     add("attempt", row.id, "alert", `${row.status} attempt ${row.id}`, event?.at ?? at, row.reason ?? "Inspect ares attempt show before retrying");
   }
-  for (const [index, event] of events.entries()) if (event.type === "watch.ran" && event.data.ok === false) add("watch", event.at + index, "alert", "Every watch source failed", event.at, "Inspect ares watch show and retry after restoring source access");
+  for (const [index, event] of events.entries()) if (event.type === "watch.ran" && event.data.ok === false) {
+    const cause = event.data.cause, known = typeof cause === "string" && ["terminated", "filesystem", "internal", "network", "rate", "server", "client", "format"].includes(cause);
+    const title = cause === undefined ? "Every watch source failed" : known ? `Watch run failed (${cause})` : "Watch run failed (unknown cause)";
+    const detail = cause === undefined ? "Inspect ares watch show and retry after restoring source access" : "Inspect ares watch show and lit list; restore study storage or source access as needed, then rerun ares watch run";
+    add("watch", event.at + index, "alert", title, event.at, detail);
+  }
   }
   const archive = detailed ? readCall("archive", () => { const preview = previewArchive(dir); return { pendingCount: preview.notes.length, fingerprint: preview.fingerprint }; }, errors) : null;
   const manuscript = detailed && readCall("manuscript", () => {
@@ -186,7 +200,7 @@ function loadStudy(dir: string, features: readonly string[], input: { panel: str
     attempts: attempt ? { total: attempt.total, byStatus: attempt.byStatus } : study.mode === "experiment" ? { available: false, reason: errors.attempts ?? "Attempt records could not be read; inspect ares attempt list and restore readable records, then refresh" } : { total: 0, byStatus: {} },
     final: final ? { status: final.status, ...(final.reason ? { reason: final.reason } : {}) } : null,
     review: review ? { ready: review.ready, unmet: review.unmet } : null, lastWatch };
-  return { summary, targets, detail: detailed ? { ...summary, investigation, final, posthoc, review, skills, watch, archive, manuscript, errors } : null, items, at };
+  return { summary, targets, detail: detailed ? { ...summary, investigation, investigationArtifact: investigationArtifact ?? null, final, posthoc, review, skills, watch, archive, manuscript, errors } : null, items, at };
 }
 interface Selection { wireAction: string; action: "gate" | "screen" | "skill.decide" | "archive.confirm"; study: string; gate?: string; ids?: string[]; name?: string; decision?: string; reason?: string; pr?: string }
 const ACTIONS: Record<string, { action: Selection["action"]; decision?: string; fields: readonly string[] }> = {