@staix/agent-research 0.1.0 → 0.2.1

package/src/commands.ts

@@ -1,6 +1,8 @@
+import { validateAutonomyMode, validatePhase, PHASES, ACCEPT_ARTIFACTS, resolveAutonomy, type AcceptArtifact, type Autonomy } from "./autonomy.ts";
+import { copilotBinding, requireCopilotAccept } from "./copilot.ts";
 import { homedir } from "node:os";
 import { addStudy, removeStudy, readRegistry } from "./console/registry.ts";
-import { readWatchSnapshot, setWatch, runWatch, showWatch, type WatchSnapshot } from "./lit/watch.ts";
+import { readWatchSnapshot, setWatch, runWatch, showWatch, recordWatchFailure, watchFailureClass, type WatchSnapshot } from "./lit/watch.ts";
 import { runSetup, type SetupMode } from "./setup.ts";
 import { proposeSkill, decideSkill, listSkills } from "./memory/skills.ts";
 import { rankLessons, type LessonRankOptions } from "./memory/lessons.ts";
@@ -21,11 +23,12 @@ import { spawnRunner } from "./exp/executor.ts";
 import { foldPlan, readPlanState, planGateBinding, prepareControl, type ControlRequest, type ControlResult } from "./plan/state.ts";
 import { setPlan } from "./plan/definition.ts";
 export { manifest } from "./manifest.ts";
+import { exportBundle } from "./study-export.ts";
 import { existsSync, readdirSync, utimesSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { Http } from "./http.ts";
 import { readScope, scopeHash, setScope } from "./scope.ts";
-import { boundedText, commit, decideGate, gateState, GATES, initStudy, openStudy, readBytesBounded, readLedger, readTextBounded, requireGate, sha256, withLock, readPlanOwner, type Actor, type Binder, type GateName, type Study } from "./study.ts";
+import { boundedText, commit, decideGate, gateState, GATES, initStudy, openStudy, readBytesBounded, readLedger, readTextBounded, requireGate, sha256, withLock, readPlanOwner, type Actor, type Binder, type GateName, type Study, STUDY_BYTES } from "./study.ts";
 import { candidatesFile, includedHash, isVerified, loadCandidates, mergeCandidates, sameWork, verifySubject, type Candidate } from "./lit/candidates.ts";
 import { searchSource, SOURCES, type SourceName } from "./lit/sources.ts";
 import { verifyCandidates } from "./lit/verify.ts";
@@ -43,10 +46,10 @@ export interface Ctx extends ExperimentRuntime { actor: Actor; http: Http; signa
 const MAX_IDS = 200, DRAFT_BYTES = 2 * 1024 * 1024, BIB_BYTES = 16 * 1024 * 1024, CARD_BYTES = 65_536;
 
 export function binder(dir: string): Binder {
-  return gate => gate === "review" ? reviewBinding(dir) : gate === "final" ? finalGateBinding(dir) : gate.startsWith("plan:") ? planGateBinding(readPlanState(dir, readLedger(dir)), gate) : gate === "scope" ? scopeHash(dir) : gate === "design" ? designBinding(dir) : includedHash(loadCandidates(dir));
+  return gate => gate.startsWith("accept:") ? copilotBinding(dir, gate.slice(7) as AcceptArtifact) : gate === "review" ? reviewBinding(dir) : gate === "final" ? finalGateBinding(dir) : gate.startsWith("plan:") ? planGateBinding(readPlanState(dir, readLedger(dir)), gate) : gate === "scope" ? scopeHash(dir) : gate === "design" ? designBinding(dir) : includedHash(loadCandidates(dir));
 }
 function gateName(value: string): GateName {
-  if (!GATES.includes(value as GateName) && !value.startsWith("plan:")) throw new Error(`unknown gate: ${value} (${GATES.join(", ")})`);
+  if (!GATES.includes(value as GateName) && !ACCEPT_ARTIFACTS.some(artifact => value === `accept:${artifact}`) && !value.startsWith("plan:")) throw new Error("unknown gate: unsupported name; run ares gate list <dir> and choose a listed gate before approval or rejection");
   return value as GateName;
 }
 function ids(values: string[]): string[] {
@@ -65,6 +68,24 @@ export function init(dir: string, options: { question: string; mode?: string; au
   return { created: resolve(dir), study };
 }
 
+export function autonomyShow(dirArg: string) {
+  const { study } = openStudy(dirArg), policy = study.autonomy;
+  const effective = Object.fromEntries(PHASES.map(phase => [phase, typeof policy === "string" ? policy : policy.phases[phase] ?? policy.default]));
+  return { autonomy: policy, effective };
+}
+export async function autonomySet(dirArg: string, rawMode: string, rawPhase: string | undefined, ctx: Pick<Ctx, "actor">) {
+  const mode = validateAutonomyMode(rawMode), phase = rawPhase === undefined ? undefined : validatePhase(rawPhase);
+  const { dir } = openStudy(dirArg);
+  return withLock(dir, () => {
+    const { study } = openStudy(dir), from = study.autonomy;
+    const to: Autonomy = phase !== undefined ? { default: typeof from === "string" ? from : from.default, phases: { ...(typeof from === "string" ? {} : from.phases), [phase]: mode } }
+      : typeof from === "string" ? mode : { default: mode, phases: { ...from.phases } };
+    const v = study.v === 2 || typeof to !== "string" || to === "copilot" || to === "step" ? 2 : 1;
+    commit(dir, [[join(dir, "study.json"), JSON.stringify({ ...study, v, autonomy: to }, null, 2) + "\n", STUDY_BYTES]], [{ actor: ctx.actor, type: "autonomy.set", data: { from, to, phase: phase ?? null } }]);
+    return autonomyShow(dir);
+  });
+}
+
 export async function protocol(dirArg: string, raw: unknown, ctx: Ctx) {
   const { dir } = openStudy(dirArg);
   return withLock(dir, () => {
@@ -103,6 +124,8 @@ export function status(dirArg: string) {
   };
 }
 
+export const studyExport = (dir: string, options: { bundle: string; list?: boolean }) => exportBundle(dir, options);
+
 export async function scope(dirArg: string, raw: unknown, ctx: Ctx) {
   const { dir } = openStudy(dirArg);
   return withLock(dir, () => {
@@ -114,7 +137,8 @@ export async function scope(dirArg: string, raw: unknown, ctx: Ctx) {
 export function gateList(dirArg: string) {
   const { dir, study } = openStudy(dirArg), events = readLedger(dir), bind = binder(dir);
   const plan = foldPlan(events);
-  const gates: GateName[] = [...GATES.filter(g => (g !== "design" && g !== "final") || study.mode === "experiment"), ...(plan?.nodes.filter(n => n.kind === "gate").map(n => `plan:${n.id}` as GateName) ?? [])];
+  const accepts = ACCEPT_ARTIFACTS.filter(artifact => resolveAutonomy(study.autonomy, `accept:${artifact}`) === "copilot").map(artifact => `accept:${artifact}` as GateName);
+  const gates: GateName[] = [...accepts, ...GATES.filter(g => (g !== "design" && g !== "final") || study.mode === "experiment"), ...(plan?.nodes.filter(n => n.kind === "gate").map(n => `plan:${n.id}` as GateName) ?? [])];
   return gates.map(g => gateState(g, events, bind));
 }
 
@@ -262,23 +286,26 @@ export async function planControl(dirArg: string, request: ControlRequest, ctx:
   const { dir } = openStudy(dirArg);
   const prepared = await withLock(dir, () => {
     const events = readLedger(dir), state = readPlanState(dir, events);
-    const prepared = prepareControl(state, events, request, ctx.actor);
+    const prepared = prepareControl(state, events, request, ctx.actor, openStudy(dir).study.autonomy);
     if (!prepared.event) return { result: prepared.result };
     const node = state.nodes.find(n => n.id === request.node);
     const attempt = node?.attemptId ? listAttempts(dir).attempts.find(a => a.id === node.attemptId) : undefined;
-    if (request.action === "cancel" && attempt) return { attemptId: attempt.id };
+    if (request.action === "cancel" && attempt) return { attemptId: attempt.id, dispatchId: node?.dispatchId };
     // A missing record after a crash is uncertain, and explicit retry/cancel may release it.
     if ((request.action === "retry" || request.action === "skip") && attempt?.status === "running") throw new Error(`plan node ${node!.id}: attempt is still running; cancel it or run ares attempt reconcile before retry`);
-    commit(dir, [], [prepared.event]);
+    commit(dir, [], [prepared.event, ...(prepared.pause ? [prepared.pause] : [])]);
     return { result: prepared.result };
   });
   if (prepared.result) return prepared.result;
   let result: ControlResult | undefined;
   await cancelAttempt(dir, prepared.attemptId!, "plan cancellation", ctx, () => {
     const events = readLedger(dir), state = readPlanState(dir, events);
-    const prepared = prepareControl(state, events, request, ctx.actor);
-    result = prepared.result;
-    return prepared.event ? [prepared.event] : [];
+    // An identical cancel may have committed while this request waited for the attempt control lock.
+    const current = prepareControl(state, events, request, ctx.actor, openStudy(dir).study.autonomy);
+    if (!current.event) { result = current.result; return []; }
+    if (state.nodes.find(node => node.id === request.node)?.dispatchId !== prepared.dispatchId) throw new Error("plan cancel: dispatch changed while cancelling the attempt; inspect ares plan show and retry with a new command-id");
+    result = current.result;
+    return current.event ? [current.event, ...(current.pause ? [current.pause] : [])] : [];
   });
   return result!;
 }
@@ -317,6 +344,7 @@ export async function planRun(dirArg: string, options: { parallel?: number }, ct
     actor: ctx.actor, ...(ctx.signal ? { signal: ctx.signal } : {}), ...(ctx.sleep ? { sleep: ctx.sleep } : {}),
     prepare: async (node, state) => {
       if (node.command !== "attempt.run") return {};
+      requireCopilotAccept(dir, "hypotheses");
       const design = readDesign(dir);
       if (!design) throw new Error("plan attempt: protocol missing; run ares protocol before resume");
       const options = attemptOptions(node, state.retryOf), snapshot = await resolveSnapshot(options.repo, options.commit, ctx.runner ?? spawnRunner);
@@ -495,19 +523,32 @@ export async function watchRun(dirArg: string, ctx: Ctx) {
 }
 export interface WatchStarted { started: true; configSha256: string }
 /** Acknowledge only validated admission; the finite pass keeps the same lock until its receipt is written. */
-export function watchRunDetached(dirArg: string, ctx: Ctx, track?: (completion: Promise<void>) => void): Promise<WatchStarted> {
+export function watchRunDetached(dirArg: string, ctx: Ctx, track?: (completion: Promise<void>, terminate: () => void) => void): Promise<WatchStarted> {
   const { dir, study } = openStudy(dirArg);
   let accept!: (value: WatchStarted) => void, reject!: (cause: unknown) => void, started = false;
+  let terminate = () => {};
   const admission = new Promise<WatchStarted>((resolve, refuse) => { accept = resolve; reject = refuse; });
   const completion = withLock(dir, async () => {
     const snapshot = watchPreflight(dir, study);
+    let settled = false;
+    terminate = () => {
+      if (settled) return; settled = true;
+      recordWatchFailure(dir, snapshot, ctx.actor, "terminated");
+      console.error("ares watch: terminated; inspect ares watch show and lit list before retrying");
+    };
     started = true; accept({ started: true, configSha256: snapshot.sha256 });
-    await watchRunLocked(dir, snapshot, ctx);
+    try { await watchRunLocked(dir, snapshot, ctx); settled = true; }
+    catch (cause) {
+      if (settled) return; settled = true;
+      const kind = watchFailureClass(cause);
+      recordWatchFailure(dir, snapshot, ctx.actor, kind);
+      console.error(`ares watch: background pass failed (${kind}); inspect ares watch show and lit list before retrying`);
+    }
   }).then(() => {}, cause => {
     if (!started) reject(cause);
-    else console.error("ares watch: background pass failed; inspect ares watch show and lit list before retrying");
+    else console.error(`ares watch: failure receipt could not be written (${watchFailureClass(cause)}); restore study storage, inspect ares watch show and lit list, then retry`);
   });
-  track?.(completion);
+  track?.(completion, () => terminate());
   return admission;
 }
 export const watchShow = (dir: string) => ({ ...showWatch(dir), newCandidates: list(dir, { status: "new", limit: 500 }) });

package/src/copilot.ts

@@ -0,0 +1,91 @@
+import { lstatSync, opendirSync } from "node:fs";
+import { join } from "node:path";
+import { ACCEPT_ARTIFACTS, resolveAutonomy, type AcceptArtifact } from "./autonomy.ts";
+import { canonical } from "./plan/state.ts";
+import { gateState, openStudy, readBytesBounded, readLedger, readTextBounded, sha256 } from "./study.ts";
+
+export const COPILOT_HYPOTHESES_BYTES = 2 * 1024 * 1024;
+export const COPILOT_PAPER_BYTES = 64 * 1024 * 1024;
+export const COPILOT_PAPER_FILES = 500, COPILOT_PAPER_DIRECTORIES = 1000, COPILOT_PAPER_DEPTH = 64;
+export class CopilotAcceptError extends Error {}
+class DraftReadError extends CopilotAcceptError {}
+function refuse(artifact: AcceptArtifact, reason: string): never {
+  throw new DraftReadError(`copilot draft ${artifact}: ${reason}; restore the last valid bounded regular draft files and ledger, then run ares gate list and ares gate approve <dir> accept:${artifact} before retrying`);
+}
+function draftLedger(dir: string, artifact: AcceptArtifact) {
+  try { return readLedger(dir); }
+  catch (error) {
+    if (error instanceof Error && /^ledger\.jsonl line [0-9]+: unsupported schema version/.test(error.message)) throw new DraftReadError(`copilot draft ${artifact}: unsupported ledger version; keep its bytes unchanged and use a compatible ares version before ares gate approve <dir> accept:${artifact}`);
+    refuse(artifact, "acceptance ledger is unreadable, malformed or over-bound");
+  }
+}
+function metadata(file: string) {
+  try { return lstatSync(file); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+}
+function paperTree(dir: string): [string, string][] {
+  const root = join(dir, "paper"), entries: [string, string][] = [];
+  const rootStat = metadata(root);
+  if (rootStat === undefined) return entries;
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) refuse("paper", "paper source root must be a directory without symbolic links");
+  const derived = metadata(join(root, "build"));
+  let bytes = 0, directories = 0;
+  function walk(relative: string, depth: number): void {
+    // paper/build is derived output; manuscript sources include all other notes and assets.
+    if (relative === "build") return;
+    const file = relative ? join(root, relative) : root, stat = lstatSync(file);
+    // Respect the filesystem's case aliases without excluding a distinct source directory on case-sensitive hosts.
+    if (depth === 1 && relative.toLowerCase() === "build" && derived && derived.dev === stat.dev && derived.ino === stat.ino) return;
+    if (stat.isSymbolicLink()) refuse("paper", "symbolic links refused");
+    if (stat.isDirectory()) {
+      if (depth > COPILOT_PAPER_DEPTH || ++directories > COPILOT_PAPER_DIRECTORIES) refuse("paper", `source tree exceeds ${COPILOT_PAPER_DIRECTORIES} directories or ${COPILOT_PAPER_DEPTH} levels`);
+      const directory = opendirSync(file);
+      try { for (let entry = directory.readSync(); entry; entry = directory.readSync()) walk(relative ? `${relative}/${entry.name}` : entry.name, depth + 1); }
+      finally { directory.closeSync(); }
+    } else {
+      if (!relative || !stat.isFile()) refuse("paper", "regular files within the paper directory required");
+      if (entries.length >= COPILOT_PAPER_FILES) refuse("paper", `file count exceeds ${COPILOT_PAPER_FILES}`);
+      if (stat.size > COPILOT_PAPER_BYTES - bytes) refuse("paper", `aggregate bytes exceed ${COPILOT_PAPER_BYTES}`);
+      const content = readBytesBounded(file, COPILOT_PAPER_BYTES - bytes, { noFollow: true });
+      bytes += content.byteLength; entries.push([relative, sha256(content)]);
+    }
+  }
+  walk("", 0);
+  return entries.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+}
+
+/** Only active, present drafts have accept bindings. Irrelevant and acceptance events are excluded. */
+export function copilotBinding(dirArg: string, artifact: AcceptArtifact): string | undefined {
+  if (!ACCEPT_ARTIFACTS.includes(artifact)) throw new Error("copilot draft: unknown artifact; select hypotheses, paper or reviews and retry ares gate list");
+  const { dir, study } = openStudy(dirArg);
+  if (resolveAutonomy(study.autonomy, `accept:${artifact}`) !== "copilot") return undefined;
+  try {
+    if (artifact === "paper") {
+      const files = paperTree(dir);
+      return files.length ? sha256(canonical(files)) : undefined;
+    }
+    const events = draftLedger(dir, artifact).filter(event => artifact === "hypotheses" ? event.type === "idea.added" || event.type === "idea.decided" : event.type === "review.added" || event.type === "review.resolved");
+    if (artifact === "reviews") return events.length ? sha256(canonical(events)) : undefined;
+    const file = join(dir, "hypotheses.md"), stat = metadata(file);
+    let hypotheses: string | undefined;
+    if (stat !== undefined) {
+      if (stat.isSymbolicLink() || !stat.isFile()) refuse(artifact, "regular hypotheses file required; symbolic links refused");
+      if (stat.size > COPILOT_HYPOTHESES_BYTES) refuse(artifact, `hypotheses source exceeds ${COPILOT_HYPOTHESES_BYTES} bytes`);
+      hypotheses = readTextBounded(file, COPILOT_HYPOTHESES_BYTES, { noFollow: true });
+    }
+    return hypotheses !== undefined || events.length ? sha256(canonical([hypotheses === undefined ? null : sha256(hypotheses), events])) : undefined;
+  } catch (error) {
+    if (error instanceof DraftReadError) throw error;
+    refuse(artifact, "artifact or ledger is unreadable, non-regular, invalid UTF-8 or over-bound");
+  }
+}
+
+/** Acceptance records the existing gate actor; neither agents nor people receive an implicit approval. */
+export function requireCopilotAccept(dir: string, artifact: AcceptArtifact): void {
+  const binding = copilotBinding(dir, artifact);
+  if (binding === undefined) return;
+  const events = draftLedger(dir, artifact);
+  const gate = `accept:${artifact}` as const, state = gateState(gate, events, () => binding);
+  if (state.state === "approved") return;
+  throw new CopilotAcceptError(`copilot draft ${artifact}: ${state.state} acceptance; run ares gate approve <dir> ${gate} for the current draft before retrying`);
+}

package/src/exp/attempts.ts

@@ -1,3 +1,5 @@
+import { requireCopilotAccept } from "../copilot.ts";
+import { resolveAutonomy } from "../autonomy.ts";
 import { readFinalSeeds, authorizeFinalAttempt, finalGateBinding, requirePosthocClosed } from "./final.ts";
 import { closeSync, existsSync, lstatSync, openSync, opendirSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
@@ -28,6 +30,8 @@ export interface AttemptContext { actor: Actor; runner?: ProcessRunner; now?: ()
 export const ATTEMPT_BYTES = 1024 * 1024;
 // Startup includes bounded image pulls and two 5-minute transfers; claims never survive indefinitely after a crash.
 export const CONTROL_STALE_MS = 30 * 60_000;
+// Filesystem mtime has sub-ms precision; Date.now is integral. Tolerate small future skew on live locks.
+export const CONTROL_FUTURE_SKEW_MS = 60_000;
 const controlScope = new AsyncLocalStorage<{ dir: string; token: string }>();
 const STATUSES: AttemptStatus[] = ["running", "succeeded", "failed", "cancelled", "unknown"];
 const inspectFields = (prefix: string, fields: string[]) => fields.map(field => `${JSON.stringify(field)}:{{json ${prefix}.${field}}}`).join(",");
@@ -159,7 +163,7 @@ async function withControl<T>(dir: string, fn: () => Promise<T>): Promise<T> {
       if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
       let age = 0; try { age = Date.now() - statSync(path).mtimeMs; } catch { /* owner removed it */ }
       if (performance.now() - waitingSince >= 2000) throw new Error("attempt control: another operation is active; retry reconcile or cancel when it finishes (abandoned claims expire after 30 minutes)");
-      if (age < 0 || age >= CONTROL_STALE_MS) {
+      if (age < -CONTROL_FUTURE_SKEW_MS || age >= CONTROL_STALE_MS) {
         try { unlinkSync(path); }
         catch (failure) { if ((failure as NodeJS.ErrnoException).code !== "ENOENT") throw new Error("attempt control: abandoned lock could not be removed; restore study-directory ownership and permissions, then retry"); }
         continue;
@@ -240,10 +244,12 @@ async function recordVerifiedStage(dir: string, attempt: Attempt, state: Observe
     if (current.stage === "candidate") {
       current.sealing.candidateHasNoEvaluator = true;
       if (approveDesign && current.pendingAutoApproval === current.sealBinding && designBinding(dir) === current.sealBinding) {
-        approvals.push(...requireGate(dir, { ...openStudy(dir).study, autonomy: "auto" }, "design", () => current.sealBinding));
+        const study = openStudy(dir).study;
+        if (resolveAutonomy(study.autonomy, "design") === "auto") approvals.push(...requireGate(dir, study, "design", () => current.sealBinding));
       }
       if (approveDesign && current.pendingFinalApproval === current.finalBinding && current.finalBinding && finalGateBinding(dir) === current.finalBinding) {
-        approvals.push(...requireGate(dir, { ...openStudy(dir).study, autonomy: "auto" }, "final", () => current.finalBinding));
+        const study = openStudy(dir).study;
+        if (resolveAutonomy(study.autonomy, "final") === "auto") approvals.push(...requireGate(dir, study, "final", () => current.finalBinding));
       }
       delete current.pendingAutoApproval; delete current.pendingFinalApproval;
     } else {
@@ -319,6 +325,7 @@ async function captureStage(dir: string, attempt: Attempt, ctx: AttemptContext,
 export async function runAttempt(dirArg: string, options: AttemptOptions, ctx: AttemptContext): Promise<Attempt> {
   const dir = studyDir(dirArg), { study } = openStudy(dir);
   const frozen = await withLock(dir, () => {
+    requireCopilotAccept(dir, "hypotheses");
     const design = readDesign(dir), executor = readExecutor(dir);
     if (!design) throw new Error("protocol: missing; run ares protocol <dir> --file PATH before attempt run");
     if (!executor) throw new Error("executor: missing; run ares executor set <dir> --kind local|ssh --workdir PATH before attempt run");
@@ -338,13 +345,14 @@ export async function runAttempt(dirArg: string, options: AttemptOptions, ctx: A
   if (options.expectedId !== undefined && wanted !== options.expectedId) throw new Error("attempt identity: changed since plan intent; reconcile the plan node before retrying");
   let created = false;
   let attempt = await withLock(dir, () => {
+    requireCopilotAccept(dir, "hypotheses");
     if (run === "posthoc") requirePosthocClosed(dir);
     if (finalAuthorization && authorizeFinalAttempt(dir, options.commit, seed).binding !== finalAuthorization.binding) throw new Error("final inputs changed during snapshot resolution; approve the current final gate before retrying");
     const attempts = load(dir), existing = attempts.find(a => a.id === wanted); if (existing) return existing;
     if (designBinding(dir) !== initialBinding) throw new Error("design: changed while resolving the snapshot; approve the current design and retry attempt run");
     if (options.retry && !attempts.some(a => a.id === options.retry)) throw new Error("retry: attempt not found; choose an existing id from ares attempt list");
     if (attempts.some(a => a.status === "running")) throw new Error("attempt: another attempt is running; reconcile or cancel it before starting a new one");
-    const binding = designBinding(dir), approval = requireGate(dir, study, "design", () => binding);
+    const binding = designBinding(dir), approval = requireGate(dir, openStudy(dir).study, "design", () => binding);
     enforceBudget(protocol, attempts, now(ctx));
     const root = posix.join(executor.workdir, study.id, wanted);
     const record: Attempt = { v: 1, id: wanted, studyId: study.id, run, protocolHash: hash, sealBinding: binding!, ...snapshot, seed, label, ...(options.retry ? { retryOf: options.retry } : {}), executor, protocol, paths: { snapshot: posix.join(root, "snapshot"), output: posix.join(root, "output"), evaluator: posix.join(root, "task", "evaluator"), result: posix.join(root, "result") }, status: "running", stage: "candidate", startedAt: at(ctx), stages: {}, metrics: [], outputs: [], sealing: { separateContainers: false, evaluatorReadOnly: false, candidateHasNoEvaluator: false, verifiedBy: "ares-observed" }, launching: owner(ctx) };

package/src/exp/investigate.ts

@@ -1,3 +1,4 @@
+import { requireCopilotAccept } from "../copilot.ts";
 import { readFinalSeeds, finalSeedsHash } from "./final.ts";
 import { foldIdeas } from "./ideas.ts";
 import { existsSync } from "node:fs";
@@ -162,7 +163,9 @@ export function showInvestigation(dirArg: string): InvestigateResult {
 }
 /** Caller holds the study lock; every refusal precedes the single file/event commit. */
 export function closeInvestigation(dirArg: string, actor: Actor): InvestigateResult {
-  const input = inputs(dirArg), file = investigateResultPath(input.dir, input.rule.run), previous = previousResult(file);
+  const input = inputs(dirArg);
+  requireCopilotAccept(input.dir, "hypotheses");
+  const file = investigateResultPath(input.dir, input.rule.run), previous = previousResult(file);
   if (input.attempts.some(a => a.status === "running")) throw new Error("investigate close: an attempt in the selected run is running; run ares attempt reconcile before closing");
   const result = calculate(input), text = JSON.stringify(result, null, 2) + "\n";
   if (previous !== text) commit(input.dir, [[file, text, INVESTIGATE_BYTES]], [{ actor, type: "investigate.closed", data: { run: input.rule.run, sha256: sha256(text), ruleSha256: input.ruleSha, winner: result.winner?.commit ?? null } }]);
@@ -172,7 +175,9 @@ export function closeInvestigation(dirArg: string, actor: Actor): InvestigateRes
 
 /** Read only a current, committed investigation result, never a hand-edited or stale winner. */
 export function readClosedInvestigation(dirArg: string): { result: InvestigateResult; sha256: string } {
-  const input = inputs(dirArg), text = previousResult(investigateResultPath(input.dir, input.rule.run));
+  const input = inputs(dirArg);
+  requireCopilotAccept(input.dir, "hypotheses");
+  const text = previousResult(investigateResultPath(input.dir, input.rule.run));
   if (text === undefined) throw new Error("investigate result: not closed; run ares investigate close before the next phase");
   const hash = sha256(text), receipt = input.events.findLast(e => e.type === "investigate.closed" && e.data.run === input.rule.run);
   if (!receipt || receipt.data.sha256 !== hash) throw new Error("investigate result: bytes do not match the latest close receipt; run ares investigate close to restore the committed result");

package/src/exp/protocol.ts

@@ -1,3 +1,4 @@
+import { requireCopilotAccept } from "../copilot.ts";
 import { finalSeedsHash } from "./final.ts";
 import { selectionHash } from "./selection.ts";
 import { existsSync, lstatSync, opendirSync } from "node:fs";
@@ -136,7 +137,9 @@ export function readDesign(dir: string): { protocol: Protocol; treeHash: string;
 /** Caller holds the study lock, as with setScope. Validate everything before any write. */
 export function setProtocol(dir: string, raw: unknown, actor: Actor): Protocol {
   requireExperiment(openStudy(dir).study);
-  const protocol = validateProtocol(raw), treeHash = taskTreeHash(dir), text = JSON.stringify(protocol, null, 2) + "\n";
+  const protocol = validateProtocol(raw);
+  requireCopilotAccept(dir, "hypotheses");
+  const treeHash = taskTreeHash(dir), text = JSON.stringify(protocol, null, 2) + "\n";
   // Never commit a protocol that makes its existing selection unreadable.
   selectionHash(dir, protocol);
   finalSeedsHash(dir, protocol);

package/src/http.ts

@@ -15,6 +15,47 @@ export interface Http {
 const TIMEOUT_MS = 20_000, MAX_BYTES = 5 * 1024 * 1024;
 const EMAIL = /^[^\s@<>()]{1,64}@[^\s@<>()]{1,190}$/;
 
+export const S2_START_INTERVAL_MS = 1_100;
+export interface HttpPacingClock {
+  now(): number;
+  sleep(ms: number): Promise<void>;
+}
+export interface HttpPacing {
+  start<T>(request: () => Promise<T>): Promise<T>;
+}
+
+/** Serialize admissions only: an in-flight response never holds the next start. */
+export function createHttpPacing(clock: HttpPacingClock = {
+  now: () => performance.now(),
+  sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+}): HttpPacing {
+  let tail = Promise.resolve(), lastStart: number | undefined;
+  return {
+    start<T>(request: () => Promise<T>): Promise<T> {
+      const admitted = tail.then(async () => {
+        if (lastStart !== undefined) {
+          let remaining = S2_START_INTERVAL_MS - (clock.now() - lastStart);
+          while (remaining > 0) {
+            await clock.sleep(remaining);
+            remaining = S2_START_INTERVAL_MS - (clock.now() - lastStart);
+          }
+        }
+        // Measure after invocation, conservatively spacing actual fetch starts.
+        let response: Promise<T>;
+        try { response = request(); } finally { lastStart = clock.now(); }
+        // Box the promise so admission releases without waiting for the response.
+        // A later admission must not delay handling a rejected response.
+        void response.catch(() => {});
+        return { response };
+      });
+      tail = admitted.then(() => {}, () => {});
+      return admitted.then(({ response }) => response);
+    },
+  };
+}
+
+const processS2Pacing = createHttpPacing();
+
 /** Read the body while counting bytes; past the limit the stream is cancelled, never buffered whole. */
 async function readBounded(response: Response, host: string): Promise<string> {
   if (!response.body) return "";
@@ -38,11 +79,14 @@ export function userAgent(env: NodeJS.ProcessEnv): string {
 }
 
 /** 200 returns the body, 404 returns `body: undefined`; 429, 5xx, other statuses and network failures throw HttpError. */
-export function createHttp(env: NodeJS.ProcessEnv = process.env, fetchImpl: FetchLike = fetch as FetchLike): Http {
+export function createHttp(env: NodeJS.ProcessEnv = process.env, fetchImpl: FetchLike = fetch as FetchLike, pacing: HttpPacing = processS2Pacing): Http {
   async function get(url: string, headers: Record<string, string> = {}): Promise<HttpResult<string>> {
     const host = new URL(url).host;
     let response: Response;
-    try { response = await fetchImpl(url, { headers: { "user-agent": userAgent(env), ...headers }, signal: AbortSignal.timeout(TIMEOUT_MS) }); }
+    try {
+      const request = () => fetchImpl(url, { headers: { "user-agent": userAgent(env), ...headers }, signal: AbortSignal.timeout(TIMEOUT_MS) });
+      response = await (new URL(url).hostname === "api.semanticscholar.org" ? pacing.start(request) : request());
+    }
     catch { throw new HttpError("network", host); }
     if (response.status === 404) return { status: 404, body: undefined };
     if (response.status === 429) throw new HttpError("rate", host, 429);

package/src/lit/watch.ts

@@ -1,3 +1,4 @@
+import { HttpError } from "../http.ts";
 import { join } from "node:path";
 import { assertWritable, boundedText, commit, onlyKeys, openStudy, plain, readLedger, readBytesBounded, sha256, type Actor } from "../study.ts";
 import { loadCandidates } from "./candidates.ts";
@@ -10,7 +11,8 @@ export interface WatchSnapshot { config: WatchConfig; sha256: string }
 export interface SearchResult { added: number; merged: number; dropped: number; linked: number; sources: { source: SourceName; ok: boolean; returned: number; error?: string }[] }
 export interface WatchError { host: string; status: number | null }
 export interface WatchQueryResult { id: string; added: number; merged: number; dropped: number; linked: number; sources: { source: SourceName; ok: boolean; returned: number }[]; errors: WatchError[] }
-export interface WatchRun { configSha256: string; queries: WatchQueryResult[]; added: number; addedIds: string[]; addedIdsTotal: number; ok: boolean }
+export type WatchFailureClass = "terminated" | "filesystem" | "network" | "rate" | "server" | "client" | "format" | "internal";
+export interface WatchRun { cause?: WatchFailureClass; configSha256: string; queries: WatchQueryResult[]; added: number; addedIds: string[]; addedIdsTotal: number; ok: boolean }
 const HOSTS: Record<SourceName, string> = { openalex: "api.openalex.org", s2: "api.semanticscholar.org", arxiv: "export.arxiv.org" };
 class WatchInputError extends Error {}
 class WatchVersionError extends WatchInputError {}
@@ -80,6 +82,17 @@ function sourceErrors(sources: SearchResult["sources"]): WatchError[] {
     return { host, status: match?.[1] === undefined ? null : Number(match[1]) };
   });
 }
+/** A closed vocabulary only: thrown messages can contain request URLs, keys or response bodies. */
+export function watchFailureClass(error: unknown): WatchFailureClass {
+  if (error instanceof HttpError) return error.kind;
+  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  return ["ENOENT", "EACCES", "EPERM", "ENOSPC", "EIO", "EROFS", "ENOTDIR", "EISDIR"].includes(String(code)) ? "filesystem" : "internal";
+}
+/** Caller still holds the study lock; no partial query details or diagnostic text are copied. */
+export function recordWatchFailure(dir: string, snapshot: WatchSnapshot, actor: Actor, cause: WatchFailureClass): void {
+  const run: WatchRun = { configSha256: snapshot.sha256, queries: [], added: 0, addedIds: [], addedIdsTotal: 0, ok: false, cause };
+  commit(dir, [], [{ actor, type: "watch.ran", data: { ...run } }]);
+}
 /** One finite pass, using the caller's existing locked lit-search operation. No timer or screening. */
 export async function runWatch(dir: string, snapshot: WatchSnapshot, actor: Actor, search: (query: WatchQuery) => Promise<SearchResult>): Promise<WatchRun> {
   const { config } = snapshot;

package/src/manifest.ts

@@ -5,7 +5,7 @@ import { ARES_TOOLS } from "./mcp-tools.ts";
 /** Implemented family-readable records only; private inputs and future integrations are not contracts. */
 export const FORMAT_VERSIONS = {
   manifest: 1,
-  study: 1,
+  study: 2,
   paperEvidence: 1,
   skillProposal: 1,
   studyRegistry: 1,
@@ -20,10 +20,11 @@ export const FORMAT_VERSIONS = {
   investigateResult: 1,
   executor: 1,
   experimentAttempt: 1,
+  studyBundle: 1,
 } as const;
 export const MEMORY_LEDGER_EVENTS = ["archive.exported", "skill.proposed", "skill.decided"] as const;
 export const WATCH_LEDGER_EVENTS = ["watch.set", "watch.ran"] as const;
-export const LEDGER_EVENTS = [...MEMORY_LEDGER_EVENTS, ...WATCH_LEDGER_EVENTS] as const;
+export const LEDGER_EVENTS = [...MEMORY_LEDGER_EVENTS, ...WATCH_LEDGER_EVENTS, "autonomy.set"] as const;
 export interface Manifest {
   v: 1;
   name: "ares";

package/src/mcp-tools.ts

@@ -1,3 +1,4 @@
+import { PHASES, AUTONOMY_MODES } from "./autonomy.ts";
 import { SETUP_TARGETS, type SetupMode } from "./setup.ts";
 import { isAbsolute } from "node:path";
 import * as ops from "./commands.ts";
@@ -30,8 +31,8 @@ const SKILL = obj({ name: text(64), summary: text(16384), steps: { ...texts(1638
 const SCOPE = obj({ question: text(2000), subquestions: texts(30, 1000), include: texts(50, 500), exclude: texts(50, 500), yearFrom: year, yearTo: year, maxCandidates: { type: "integer", minimum: 1, maximum: 5000 } }, ["question"]);
 const CARD = obj({ summary: text(4000), claims: texts(50, 1000), methods: text(4000), findings: text(4000), limitations: text(4000), relevance: text(4000) }, ["summary"]);
 const integer = (minimum: number, maximum: number) => ({ type: "integer", minimum, maximum });
-const WATCH = obj({ v: { type: "integer", enum: [1] }, queries: { type: "array", minItems: 1, maxItems: 20,
-  items: obj({ id: text(64), query: text(4096), source: { type: "string", enum: ["openalex", "s2", "arxiv", "all"] }, yearFrom: year, limit: integer(1, 50) }, ["id", "query"]) }, rubric: text(8000) }, ["v", "queries"]);
+const WATCH = obj({ v: {}, queries: { type: "array", minItems: 1, maxItems: 20,
+  items: obj({ id: text(64), query: text(4096), source: { type: "string", enum: ["openalex", "s2", "arxiv", "all"] }, yearFrom: year, limit: integer(1, 50) }, ["id", "query"]) }, rubric: text(8000) }, ["queries"]);
 const argv = { type: "array", minItems: 1, maxItems: 128, items: { type: "string", maxLength: 4096 } };
 const image = { ...text(512), description: "Digest-pinned image: name@sha256:<64 lowercase hex digits>" };
 const stage = { type: "string", enum: ["candidate", "evaluator"] };
@@ -53,7 +54,7 @@ const planId = text(PLAN_ID_BYTES);
 const PLAN = obj({
   v: { type: "integer", enum: [1] }, revision: integer(1, Number.MAX_SAFE_INTEGER),
   nodes: { type: "array", maxItems: 128, items: obj({
-    id: planId, kind: { type: "string", enum: ["step", "hub", "gate"] },
+    id: planId, kind: { type: "string", enum: ["step", "hub", "gate"] }, phase: { type: "string", enum: [...PHASES] },
     needs: { type: "array", maxItems: 128, items: planId },
     command: { type: "string", enum: [...STEP_COMMANDS] },
     args: { type: "object", maxProperties: 32, properties: {}, additionalProperties: { type: ["string", "number", "boolean", "array"], maxLength: 4096, maxItems: 500, items: text(300) } },
@@ -72,6 +73,8 @@ const SELECTION = obj({
 const IDEA = obj({ id: text(64), title: text(500), hypothesis: text(4000), parent: text(64), commit: { type: "string", minLength: 40, maxLength: 40 } }, ["id", "title", "hypothesis"]);
 
 export const ARES_TOOLS: readonly McpTool[] = [
+  { name: "ares_autonomy_show", description: "Read the study autonomy policy and effective mode for each phase; no writes.", inputSchema: obj({ study }, ["study"]), annotations: read },
+  { name: "ares_autonomy_set", description: `Set the default or one phase autonomy mode (${AUTONOMY_MODES.join("|")}) and record from/to/phase. Only auto approves pending gates; existing gate decisions remain unchanged. Copilot draft acceptance and step pausing are separate features.`, inputSchema: obj({ study, mode: text(16), phase: text(32) }, ["study", "mode"]), annotations: write },
   { name: "ares_watch_set", description: "Set bounded v1 literature queries and an optional display-only rubric. At most 20 queries; identical config is a no-op. Does not search, screen or start a timer. Survey and experiment studies.", inputSchema: obj({ study, watch: WATCH }, ["study", "watch"]), annotations: { ...write, idempotentHint: true } },
   { name: "ares_watch_run", description: "Start one finite watch pass and return {started:true,configSha256} after config, scope gate and year preflight. Always detached: this ack is not completion. Inspect ares_watch_show for the watch.ran outcome. The background pass holds the study lock for up to about 20 minutes; duplicate starts refuse. Adds only new candidates, never screens. No timer or daemon is started.", inputSchema: obj({ study }, ["study"]), annotations: net },
   { name: "ares_watch_show", description: "Read watch config, recent event-timed run receipts and new candidates. No lock, network or write.", inputSchema: obj({ study }, ["study"]), annotations: read },
@@ -89,8 +92,9 @@ export const ARES_TOOLS: readonly McpTool[] = [
   { name: "ares_plan_control", description: "Pause/resume admission or retry/cancel/skip a node. Requires a durable command id and expected definition revision: identical replay returns its original receipt; changed payloads/stale new requests refuse. Does not start a controller; run ares run separately. Cancelling an attempt may contact its executor; hub cancellation stays local.", inputSchema: obj({ study, action: { type: "string", enum: ["pause", "resume", "retry", "cancel", "skip"] }, node: text(128), commandId: text(128), expectedRevision: integer(1, Number.MAX_SAFE_INTEGER) }, ["study", "action", "commandId", "expectedRevision"]), annotations: net },
   { name: "ares_plan_show", description: "Read the definition revision, ledger-derived node states and last observations, gate decisions, uncertain nodes, controller owner and resolved hubProject without taking a lock or contacting an executor/hub.", inputSchema: obj({ study }, ["study"]), annotations: read },
   { name: "ares_status", description: "Study summary: gates, candidate counts, verification counts, bibliography.", inputSchema: obj({ study }, ["study"]), annotations: read },
+  { name: "ares_study_export", description: "Write a content-free study bundle (manifest, reduced ledger, attempt rows, closed results, review counts, evidence hashes) from committed study files into a new or empty directory. Refuses the whole export if a path, URL, env value or key-like token would be written. list=true only names the files. No executor or network.", inputSchema: obj({ study, bundle: text(4096), list: { type: "boolean" } }, ["study", "bundle"]), annotations: write },
   { name: "ares_scope_set", description: "Set scope.json (question, subquestions, include, exclude, yearFrom, yearTo, maxCandidates). A change returns the scope gate to pending.", inputSchema: obj({ study, scope: SCOPE }, ["study", "scope"]), annotations: write },
-  { name: "ares_gate", description: "List gates, or approve/reject scope, screen, design, final, review or plan:node-id. Plan approvals bind all upstream output references and need complete upstream outputs; skip never bypasses them. The ledger records the actor; approval authority is workspace policy.", inputSchema: obj({ study, action: { type: "string", enum: ["list", "approve", "reject"] }, gate: text(PLAN_GATE_BYTES), reason }, ["study", "action"]), annotations: write },
+  { name: "ares_gate", description: "List gates, or approve/reject scope, screen, design, final, review, plan:node-id or accept:hypotheses|paper|reviews. Copilot accepts bind current draft hashes and are never automatic. Plan approvals bind all upstream output references and need complete upstream outputs; skip never bypasses them. The ledger records the actor; approval authority is workspace policy.", inputSchema: obj({ study, action: { type: "string", enum: ["list", "approve", "reject"] }, gate: text(PLAN_GATE_BYTES), reason }, ["study", "action"]), annotations: write },
   { name: "ares_idea_add", description: "Add an experiment idea to the ledger, with optional existing parent and frozen commit. Unique run-name ids and commit ownership; at most 1000 ideas. Starts no work.", inputSchema: obj({ study, idea: IDEA }, ["study", "idea"]), annotations: write },
   { name: "ares_idea_decide", description: "Record refine/pivot with a reason of at most 2000 bytes. Ideas with commits require terminal own-commit attempts (at most 200). Untested ideas omit attempts to attach a first commit or pivot. Refine requires --commit with unique idea ownership; Pivot accepts optional cause/retryWhen (2000 bytes each); refine refuses them. Pivot rejects commit and closes further decisions. Starts no work.", inputSchema: obj({ study, id: text(64), decision: { type: "string", enum: ["refine", "pivot"] }, reason: text(2000), cause: text(2000), retryWhen: text(2000), attempts: { type: "array", maxItems: 200, items: attemptId }, commit: { type: "string", minLength: 40, maxLength: 40 } }, ["study", "id", "decision", "reason"]), annotations: write },
   { name: "ares_investigate_show", description: "Read investigation candidate/baseline paired-seed scores, winner or no-winner reason and all run attempt totals/exclusions. No executor or network calls.", inputSchema: obj({ study }, ["study"]), annotations: read },
@@ -132,13 +136,15 @@ function absolute(value: unknown, what: string): string {
 }
 
 /** MCP calls always come from an agent; the actor id is the detected agent or `mcp`. */
-export function createAresMcp(env: NodeJS.ProcessEnv, http: Http = createHttp(env), runtime: ops.ExperimentRuntime = {}): { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; waitForIdle(): Promise<void> } {
+export function createAresMcp(env: NodeJS.ProcessEnv, http: Http = createHttp(env), runtime: ops.ExperimentRuntime = {}): { tools: readonly McpTool[]; handlers: Record<string, McpHandler>; waitForIdle(): Promise<void>; terminate(): void } {
   const detected = detectActor(env), actor: Actor = { kind: "agent", id: detected.kind === "agent" ? detected.id! : "mcp" };
   const ctx = { ...runtime, actor, http }, memoryEnv = { ...env, AGENTHUB_PEER_ID: actor.id };
   const dir = (a: Record<string, unknown>) => absolute(a.study, "study");
-  const background = new Set<Promise<void>>();
-  const track = (completion: Promise<void>) => { background.add(completion); void completion.then(() => { background.delete(completion); }); };
+  const background = new Map<Promise<void>, () => void>();
+  const track = (completion: Promise<void>, terminate: () => void) => { background.set(completion, terminate); void completion.then(() => { background.delete(completion); }); };
   const handlers: Record<string, McpHandler> = {
+    ares_autonomy_show: a => ops.autonomyShow(dir(a)),
+    ares_autonomy_set: a => ops.autonomySet(dir(a), a.mode as string, a.phase as string | undefined, ctx),
     ares_watch_set: a => ops.watchSet(dir(a), a.watch, ctx),
     ares_watch_run: a => ops.watchRunDetached(dir(a), ctx, track),
     ares_watch_show: a => ops.watchShow(dir(a)),
@@ -156,6 +162,7 @@ export function createAresMcp(env: NodeJS.ProcessEnv, http: Http = createHttp(en
     ares_plan_control: a => ops.planControl(dir(a), { action: a.action as Parameters<typeof ops.planControl>[1]["action"], commandId: a.commandId as string, expectedRevision: a.expectedRevision as number, ...(a.node !== undefined ? { node: a.node as string } : {}) }, ctx),
     ares_plan_show: a => ops.planShow(dir(a)),
     ares_status: a => ops.status(dir(a)),
+    ares_study_export: a => ops.studyExport(dir(a), { bundle: absolute(a.bundle, "bundle"), ...(a.list === true ? { list: true } : {}) }),
     ares_scope_set: a => ops.scope(dir(a), a.scope, ctx),
     ares_idea_add: a => ops.ideaAdd(dir(a), a.idea, ctx),
     ares_idea_decide: a => ops.ideaDecide(dir(a), a.id as string, { decision: a.decision, reason: a.reason, ...(a.cause !== undefined ? { cause: a.cause } : {}), ...(a.retryWhen !== undefined ? { retryWhen: a.retryWhen } : {}), ...(a.attempts !== undefined ? { attempts: a.attempts } : {}), ...(a.commit !== undefined ? { commit: a.commit } : {}) }, ctx),
@@ -196,5 +203,8 @@ export function createAresMcp(env: NodeJS.ProcessEnv, http: Http = createHttp(en
     ares_cite_check: a => ops.cite(dir(a), absolute(a.draft, "draft")),
     ares_playbook: () => ({ playbook: PLAYBOOK }),
   };
-  return { tools: ARES_TOOLS, handlers, waitForIdle: async () => { await Promise.all([...background]); } };
+  return { tools: ARES_TOOLS, handlers,
+    // Only for the entrypoint immediately before process exit; pending async work must not resume.
+    terminate: () => { for (const stop of background.values()) { try { stop(); } catch { console.error("ares watch: termination receipt failed (storage); restore study storage and inspect ares watch show before retrying"); } } },
+    waitForIdle: async () => { await Promise.all([...background.keys()]); } };
 }

package/src/mcp.ts

@@ -12,6 +12,8 @@ const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v ===
 
 /** Runtime validation for the small schema vocabulary the tools use. Unknown keywords never widen acceptance. */
 export function validArguments(value: unknown, raw: unknown): boolean {
+  // An empty JSON schema delegates a frame-bounded field (watch version) to the shared validator.
+  if (plain(raw) && Object.keys(raw).length === 0) return true;
   const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
   const types: unknown[] = Array.isArray(s.type) ? s.type : [s.type];
   if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;

package/src/memory/archive.ts

@@ -1,3 +1,5 @@
+import { ACCEPT_ARTIFACTS } from "../autonomy.ts";
+import { requireCopilotAccept } from "../copilot.ts";
 import { commit, prepareCommit, openStudy, plain, sha256, type Actor, type LedgerEvent } from "../study.ts";
 import { canonical } from "../plan/state.ts";
 import { createAmemClient, type AmemNote } from "./amem.ts";
@@ -35,6 +37,7 @@ function exported(events: LedgerEvent[]): Set<string> {
 }
 /** No lock, subprocess or write: confirmation binds the full list, receipts only narrow pending writes. */
 export function previewArchive(dir: string): ArchivePreview {
+  for (const artifact of ACCEPT_ARTIFACTS) requireCopilotAccept(dir, artifact);
   const sources = readLessonSources(dir), notes = deriveLessons(sources), known = exported(sources.events);
   const unique = new Map(notes.map(note => [sha256(canonical(note)), note]));
   const pending = [...unique].filter(([hash]) => !known.has(hash)).map(([sha256, note]) => ({ sha256, note }));

package/src/paper/build.ts

@@ -1,3 +1,4 @@
+import { requireCopilotAccept } from "../copilot.ts";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { assertWritable, commit, openStudy, plain, readLedger, readTextBounded, sha256, type Actor } from "../study.ts";
@@ -50,7 +51,9 @@ function calculatePaper(dir: string) {
 }
 /** Caller holds the study lock. Refusals precede the single output-and-receipt commit. */
 export function buildPaper(dirArg: string, actor: Actor) {
-  const { dir } = openStudy(dirArg), paths = paperBuildPaths(dir), oldEvidence = evidenceBytes(dir);
+  const { dir } = openStudy(dirArg);
+  requireCopilotAccept(dir, "hypotheses");
+  const paths = paperBuildPaths(dir), oldEvidence = evidenceBytes(dir);
   const { report, text, manuscriptSha256, evidenceSha256 } = calculatePaper(dir), oldManuscript = previous(paths.manuscript, MANUSCRIPT_BYTES);
   const receipt = readLedger(dir).findLast(event => event.type === "paper.built");
   const changed = oldManuscript !== report.rendered || oldEvidence !== text || receipt?.data.manuscriptSha256 !== manuscriptSha256 || receipt.data.evidenceSha256 !== evidenceSha256;