@staix/agent-research 0.1.0 → 0.2.1

package/src/paper/check.ts

@@ -1,3 +1,4 @@
+import { CopilotAcceptError } from "../copilot.ts";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { openStudy, readTextBounded, sha256 } from "../study.ts";
@@ -10,7 +11,7 @@ import { finalResultPath } from "../exp/final.ts";
 import { MANUSCRIPT_BYTES, parsePlaceholders, resolvePlaceholders } from "./placeholders.ts";
 
 export const MAX_CODE_NUMBERS = 500;
-export interface PaperFinding { code: "bare-number" | "unresolved-ref" | "bad-format" | "unknown-citation" | "unverified-citation" | "missing-negative-result"; start: number; end: number; line: number; column: number; message: string }
+export interface PaperFinding { code: "bare-number" | "unresolved-ref" | "unaccepted-draft" | "bad-format" | "unknown-citation" | "unverified-citation" | "missing-negative-result"; start: number; end: number; line: number; column: number; message: string }
 function blank(text: string, mask: Uint8Array): string { return text.split("").map((char, index) => mask[index] && char !== "\n" && char !== "\r" ? " " : char).join(""); }
 function mark(mask: Uint8Array, start: number, end: number) { mask.fill(1, start, end); }
 function escaped(text: string, index: number): boolean { let slashes = 0; while (index > 0 && text[--index] === "\\") slashes++; return slashes % 2 === 1; }
@@ -169,9 +170,9 @@ export function checkPaper(dirArg: string) {
       const protocol = readProtocol(dir), rule = protocol ? readSelection(dir, protocol) : undefined;
       if (rule && existsSync(investigateResultPath(dir, rule.run))) {
         try { if (readClosedInvestigation(dir).result.winner === null) requireRef("investigate.reason"); }
-        catch { findings.push(finding("unresolved-ref", 0, 0, "investigate result is not current and closed; run ares investigate close before checking the paper")); }
+        catch (error) { findings.push(error instanceof CopilotAcceptError ? finding("unaccepted-draft", 0, 0, error.message) : finding("unresolved-ref", 0, 0, "investigate result is not current and closed; run ares investigate close before checking the paper")); }
       }
-    } catch { findings.push(finding("unresolved-ref", 0, 0, "experiment design or selection is invalid; restore the current validated inputs before paper check")); }
+    } catch (error) { findings.push(error instanceof CopilotAcceptError ? finding("unaccepted-draft", 0, 0, error.message) : finding("unresolved-ref", 0, 0, "experiment design or selection is invalid; restore the current validated inputs before paper check")); }
   }
   let rendered = "", cursor = 0;
   for (const entry of resolution.placeholders) { rendered += manuscript.slice(cursor, entry.placeholder.start) + entry.rendered; cursor = entry.placeholder.end; }

package/src/paper/placeholders.ts

@@ -1,3 +1,4 @@
+import { CopilotAcceptError } from "../copilot.ts";
 import { join, relative } from "node:path";
 import { openStudy, plain, readLedger, readTextBounded, sha256 } from "../study.ts";
 import { ATTEMPT_BYTES, listAttempts, type Attempt, type AttemptStatus } from "../exp/attempts.ts";
@@ -9,7 +10,7 @@ import { FINAL_RESULT_BYTES, finalResultPath, readClosedFinal, requirePosthocClo
 export const MANUSCRIPT_BYTES = 2 * 1024 * 1024, MAX_PLACEHOLDERS = 5000;
 interface Position { start: number; end: number; line: number; column: number; raw: string }
 export type Placeholder = Position & ({ kind: "number"; ref: string; format?: number } | { kind: "literal"; text: string });
-export interface PlaceholderFinding extends Position { code: "bad-format" | "unresolved-ref"; message: string }
+export interface PlaceholderFinding extends Position { code: "bad-format" | "unresolved-ref" | "unaccepted-draft"; message: string }
 export interface ResolvedPlaceholder { placeholder: Placeholder; value: number | string; rendered: string; source?: { file: string; sha256: string } }
 /** Offsets are UTF-16 string indices; line and column are 1-based, as used by the Markdown checker. */
 export function parsePlaceholders(text: string): { placeholders: Placeholder[]; findings: PlaceholderFinding[] } {
@@ -59,7 +60,7 @@ export function resolvePlaceholders(dirArg: string, text: string) {
   const { dir, study } = openStudy(dirArg), parsed = parsePlaceholders(text), findings = [...parsed.findings], resolved: ResolvedPlaceholder[] = [], literals: Placeholder[] = [];
   const cache = new Map<string, Source<unknown> | Error>();
   const cached = <T>(key: string, read: () => Source<T>): Source<T> => {
-    if (!cache.has(key)) { try { cache.set(key, read()); } catch { cache.set(key, new Error("absent, unclosed, stale or invalid source")); } }
+    if (!cache.has(key)) { try { cache.set(key, read()); } catch (error) { cache.set(key, error instanceof CopilotAcceptError ? error : new Error("absent, unclosed, stale or invalid source")); } }
     const value = cache.get(key)!; if (value instanceof Error) throw value; return value as Source<T>;
   };
   const investigate = () => cached("investigate", () => { const closed = readClosedInvestigation(dir); return source(dir, investigateResultPath(dir, closed.result.run), INVESTIGATE_BYTES, closed.result, closed.sha256); });
@@ -104,7 +105,8 @@ export function resolvePlaceholders(dirArg: string, text: string) {
       }
       const rendered = (typeof value === "number" && placeholder.format !== undefined ? value.toFixed(placeholder.format) : String(value)) + (exploratory ? " (exploratory)" : "");
       resolved.push({ placeholder, value, rendered, source: provenance.source });
-    } catch {
+    } catch (error) {
+      if (error instanceof CopilotAcceptError) { findings.push({ ...placeholder, code: "unaccepted-draft", message: error.message }); continue; }
       findings.push({ ...placeholder, code: "unresolved-ref", message: `placeholder ${ref}: unknown ref or absent, unclosed, stale or invalid source; inspect the attempt and close the current phase results before retrying` });
     }
   }

package/src/paper/review.ts

@@ -1,3 +1,4 @@
+import { requireCopilotAccept, CopilotAcceptError } from "../copilot.ts";
 import { boundedText, commit, onlyKeys, openStudy, plain, readLedger, sha256, type Actor, type LedgerEvent } from "../study.ts";
 import { readCurrentBuild } from "./build.ts";
 import { checkPaper } from "./check.ts";
@@ -63,7 +64,9 @@ export function foldReviews(events: LedgerEvent[]): ReviewRecord[] {
 }
 /** Caller holds the study lock; report ids are generated, findings never disappear by vote. */
 export function addReview(dirArg: string, raw: unknown, actor: Actor) {
-  const { dir } = openStudy(dirArg), report = validateReview(raw), current = readCurrentBuild(dir), events = readLedger(dir), rows = foldReviews(events);
+  const { dir } = openStudy(dirArg);
+  requireCopilotAccept(dir, "paper");
+  const report = validateReview(raw), current = readCurrentBuild(dir), events = readLedger(dir), rows = foldReviews(events);
   if (report.buildSha256 !== current.evidenceSha256) bad("stale buildSha256; use the evidenceSha256 from the current ares paper build output");
   if (rows.filter(row => row.report.buildSha256 === report.buildSha256).length >= 100) bad("100 reviews already recorded for this build; resolve existing findings or build a revised manuscript");
   const id = sha256(JSON.stringify([report, events.length])).slice(0, 16);
@@ -73,7 +76,9 @@ export function addReview(dirArg: string, raw: unknown, actor: Actor) {
   commit(dir, [], [{ actor, type: "review.added", data: { id, review: report } }]); return { id, ...report };
 }
 export function resolveReview(dirArg: string, target: string, reason: string, actor: Actor) {
-  const { dir } = openStudy(dirArg), parts = target.split("/");
+  const { dir } = openStudy(dirArg);
+  requireCopilotAccept(dir, "paper");
+  const parts = target.split("/");
   if (parts.length !== 2) bad("resolution target must be <review-id>/<finding-id>; use ids from ares review show");
   const reviewId = identifier(parts[0], "review id"), findingId = identifier(parts[1], "finding id"), why = text(reason, "resolution reason"), row = foldReviews(readLedger(dir)).find(row => row.id === reviewId);
   if (!row) bad(`unknown review ${reviewId}`);
@@ -98,9 +103,14 @@ export function reviewBinding(dirArg: string): string | undefined {
 }
 export function reviewReadiness(dirArg: string) {
   const { dir } = openStudy(dirArg), events = readLedger(dir), unmet: { code: string; message: string }[] = [];
+  for (const artifact of ["paper", "reviews"] as const) {
+    try { requireCopilotAccept(dir, artifact); }
+    catch (error) { unmet.push({ code: `accept:${artifact}`, message: error instanceof Error ? error.message : `copilot ${artifact} acceptance unavailable; inspect ares gate list` }); }
+  }
   let current: ReturnType<typeof readCurrentBuild> | undefined, check: ReturnType<typeof checkPaper> | undefined;
   try { current = readCurrentBuild(dir); check = current.check; } catch (error) { unmet.push({ code: "build", message: error instanceof Error ? error.message : "current build unavailable; run ares paper build" }); }
   if (!check) { try { check = checkPaper(dir); } catch (error) { unmet.push({ code: "paper-check", message: error instanceof Error ? error.message : "paper check unavailable; restore paper/manuscript.md" }); } }
+  for (const finding of check?.findings ?? []) if (finding.code === "unaccepted-draft" && !unmet.some(item => item.code === "accept-source" && item.message === finding.message)) unmet.unshift({ code: "accept-source", message: finding.message });
   if (check && !check.ok) unmet.push({ code: "paper-check", message: `paper check has ${check.findings.length} finding(s); run ares paper check --json and fix every finding` });
   let rows: ReviewRecord[] = [];
   try { rows = foldReviews(events); } catch (error) { unmet.push({ code: "review-journal", message: error instanceof Error ? error.message : "review journal invalid; restore its valid events" }); }
@@ -111,5 +121,7 @@ export function reviewReadiness(dirArg: string) {
   return { ready: unmet.length === 0, buildSha256: buildSha256 ?? null, ...(current ? { manuscriptSha256: current.manuscriptSha256 } : {}), check: check ?? null, reviews, families, openBlocking, checklists: reviews.map(row => ({ reviewId: row.id, ...row.report.checklist })), claims: "unavailable (STAIxBWLB/agent-hub#931)", unmet };
 }
 export function requireReviewReady(dir: string): void {
-  const report = reviewReadiness(dir); if (!report.ready) throw new Error(`gate review: ${report.unmet.map(item => `${item.code}: ${item.message}`).join("; ")}; inspect ares review show before approval`);
+  const report = reviewReadiness(dir), accept = report.unmet.find(item => item.code.startsWith("accept:") || item.code === "accept-source");
+  if (accept) throw new CopilotAcceptError(accept.message);
+  if (!report.ready) throw new Error(`gate review: ${report.unmet.map(item => `${item.code}: ${item.message}`).join("; ")}; inspect ares review show before approval`);
 }

package/src/plan/controller.ts

@@ -1,7 +1,9 @@
+import { CopilotAcceptError } from "../copilot.ts";
 import { boundHubTask, type HubClient, type HubObservation } from "./hub.ts";
-import { assertPlanOwner, commit, openStudy, readLedger, requireGate, withLock, withPlanLock, StudyLockBusyError, type Actor, type PendingEvent, type PlanOwner } from "../study.ts";
-import { canonical, nextDispatchId, planGateBinding, readPlanState, type NodeState, type PlanState } from "./state.ts";
-import type { PlanNode } from "./definition.ts";
+import { assertPlanOwner, commit, openStudy, readLedger, prepareCommit, requireGate, withLock, withPlanLock, StudyLockBusyError, type Actor, type PendingEvent, type PlanOwner } from "../study.ts";
+import { canonical, foldPlan, hasRemainingWork, TERMINAL_NODE_STATUSES, nextDispatchId, planGateBinding, readPlanState, type NodeState, type PlanState } from "./state.ts";
+import { guardedPlanPhase, type PlanNode } from "./definition.ts";
+import { resolveAutonomy, resolvePhaseAutonomy, type Autonomy } from "../autonomy.ts";
 
 export type StepNode = Extract<PlanNode, { kind: "step" }>;
 export type HubNode = Extract<PlanNode, { kind: "hub" }>;
@@ -36,7 +38,7 @@ async function transaction<T>(dir: string, fn: () => T): Promise<T> {
 }
 /** One controller, short transactional study locks, and no replay of unobserved actions. */
 export async function runPlan(dirArg: string, options: ControllerOptions, runtime: ControllerRuntime): Promise<PlanState> {
-  const { dir, study } = openStudy(dirArg), parallel = options.parallel ?? 1;
+  const { dir } = openStudy(dirArg), parallel = options.parallel ?? 1;
   if (!Number.isSafeInteger(parallel) || parallel < 1 || parallel > 8) throw new Error("run --parallel: integer in 1..8 required; run ares run <dir> --parallel 1..8");
   return withPlanLock(dir, async owner => {
     const state = () => readPlanState(dir, readLedger(dir));
@@ -56,10 +58,20 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
       if (!target || target.dispatchId !== node.dispatchId || !["dispatched", "uncertain"].includes(target.status)) return;
       if (observation.status === "dispatched" && target.lastObserved?.dispatchId === node.dispatchId && target.reason === observation.reason && (observation.taskId === undefined || target.taskId === observation.taskId) && (observation.hubProject === undefined || target.hubProject === observation.hubProject)) return;
       return locked(() => {
-      const current = state(), target = current.nodes.find(n => n.id === node.id);
+      const ledger = readLedger(dir), current = readPlanState(dir, ledger), target = current.nodes.find(n => n.id === node.id);
       if (!target || target.dispatchId !== node.dispatchId || !["dispatched", "uncertain"].includes(target.status)) return;
       if (observation.status === "dispatched" && target.status === "dispatched" && target.lastObserved && target.lastObserved.dispatchId === node.dispatchId && target.lastObserved.status === "dispatched" && target.reason === observation.reason && (observation.taskId === undefined || target.taskId === observation.taskId) && (observation.hubProject === undefined || target.hubProject === observation.hubProject)) return;
-      commit(dir, [], [{ actor: runtime.actor, type: "node.observed", data: { revision: current.revision, node: node.id, dispatchId: node.dispatchId, status: observation.status, ...(observation.output !== undefined ? { output: observation.output } : {}), ...(observation.reason !== undefined ? { reason: observation.reason } : {}), ...(observation.taskId !== undefined ? { taskId: observation.taskId } : {}), ...(observation.hubProject !== undefined ? { hubProject: observation.hubProject } : {}) } }]);
+      const events: PendingEvent[] = [{ actor: runtime.actor, type: "node.observed", data: { revision: current.revision, node: node.id, dispatchId: node.dispatchId, status: observation.status, ...(observation.output !== undefined ? { output: observation.output } : {}), ...(observation.reason !== undefined ? { reason: observation.reason } : {}), ...(observation.taskId !== undefined ? { taskId: observation.taskId } : {}), ...(observation.hubProject !== undefined ? { hubProject: observation.hubProject } : {}) } }];
+      const definition = current.definition.nodes.find(value => value.id === node.id)!;
+      if (definition.kind !== "gate" && nodeMode(openStudy(dir).study.autonomy, definition) === "step") {
+        const next = foldPlan([...ledger, ...prepareCommit(dir, [], events).events])!;
+        // A hub binding conflict can turn a dispatched observation into a terminal failure in the fold.
+        if (TERMINAL_NODE_STATUSES.includes(next.nodes.find(value => value.id === node.id)!.status)) {
+          events[0]!.data.step = true; // Preserve the completion-time policy when replaying terminal failure.
+          if (hasRemainingWork(next)) events.push({ actor: runtime.actor, type: "plan.paused", data: { revision: current.revision, reason: "step", node: node.id, dispatchId: node.dispatchId } });
+        }
+      }
+      commit(dir, [], events);
       });
     };
     const reconcile = async (node: NodeState): Promise<void> => {
@@ -93,6 +105,7 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
           try { observation = await runtime.execute(definition, node); break; }
           catch (error) {
             if (error instanceof StudyLockBusyError) { await sleep(wait); wait = Math.min(wait * 2, 30_000); continue; }
+            if (error instanceof CopilotAcceptError) { observation = { status: "failed", reason: error.message }; break; }
             if (definition.command === "attempt.run") { await reconcile(node); return; }
             observation = { status: "uncertain", reason: "step execution interrupted or failed without an observable result; inspect inputs, then retry or skip this node" }; break;
           }
@@ -107,15 +120,20 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
     try {
       while (!runtime.signal?.aborted) {
         let current = state();
-        if (current.state === "done") break;
+        if (current.state === "done" || current.state === "failed") break;
         if (current.state === "running") {
           // Pending auto gates are approved only inside a successful controller transaction.
-          if (study.autonomy === "auto" && current.nodes.some(n => n.kind === "gate" && n.status === "pending" && n.gate?.state === "pending")) await tryTransaction(dir, () => {
+          const pendingGates = current.nodes.filter(n => n.kind === "gate" && n.status === "pending" && n.gate?.state === "pending");
+          // Advisory read avoids contending with manual approvals; the transaction still rechecks fresh policy.
+          const policy = pendingGates.length ? openStudy(dir).study.autonomy : undefined;
+          if (policy !== undefined && pendingGates.some(gate => resolveAutonomy(policy, `plan:${gate.id}`, guardedPlanPhase(current.definition, `plan:${gate.id}`)) === "auto")) await tryTransaction(dir, () => {
             assertPlanOwner(dir, owner);
             const events = readLedger(dir), value = readPlanState(dir, events), approvals: PendingEvent[] = [];
+            const { study } = openStudy(dir);
             if (value.state !== "running") return;
             for (const gate of value.nodes.filter(n => n.kind === "gate" && n.status === "pending" && n.gate?.state === "pending")) {
-              if (study.autonomy === "auto") approvals.push(...requireGate(dir, study, `plan:${gate.id}`, name => planGateBinding(value, name)));
+              const name = `plan:${gate.id}` as const, phase = guardedPlanPhase(value.definition, name);
+              if (resolveAutonomy(study.autonomy, name, phase) === "auto") approvals.push(...requireGate(dir, study, name, gateName => planGateBinding(value, gateName), phase));
             }
             if (approvals.length) commit(dir, [], [...approvals, { actor: runtime.actor, type: "plan.gates", data: { revision: value.revision } }]);
           });
@@ -124,6 +142,7 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
             if (runtime.signal?.aborted || current.state !== "running") break;
             const definition = current.definition.nodes.find(n => n.id === node.id)!;
             if (node.status !== "ready" || active.has(node.id)) continue;
+            if (!modeAllowsAdmission(current, openStudy(dir).study.autonomy, definition)) continue;
             if (definition.kind === "hub" && runtime.hub) {
               const binding = boundHubTask(readLedger(dir), current.revision, node.id);
               let result: HubObservation;
@@ -140,10 +159,10 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
             if (definition.command === "attempt.run" && current.nodes.some(n => n.status === "dispatched" && current.definition.nodes.find(d => d.id === n.id)?.kind === "step" && (current.definition.nodes.find(d => d.id === n.id) as StepNode).command === "attempt.run")) continue;
             let prepared: { attemptId?: string };
             try { prepared = await runtime.prepare(definition, node); }
-            catch { // Preparation is read-only; still record a correlated failed dispatch for visibility.
+            catch (error) { // Preparation is read-only; still record a correlated failed dispatch for visibility.
               prepared = {};
               const intent = await admit(dir, owner, runtime.actor, current, node, definition, prepared, parallel);
-              if (intent) await observe(intent, { status: "failed", reason: "step preparation failed; check command inputs and retry this node" });
+              if (intent) await observe(intent, { status: "failed", reason: error instanceof CopilotAcceptError ? error.message : "step preparation failed; check command inputs and retry this node" });
               current = state(); continue;
             }
             const intent = await admit(dir, owner, runtime.actor, current, node, definition, prepared, parallel);
@@ -155,7 +174,7 @@ export async function runPlan(dirArg: string, options: ControllerOptions, runtim
         for (const node of state().nodes.filter(n => n.status === "dispatched" && !active.has(n.id))) {
           if (clock() >= (polls.get(node.dispatchId!)?.at ?? 0)) await reconcile(node);
         }
-        if (state().state === "done") break;
+        if (["done", "failed"].includes(state().state)) break;
         const next = canonical(state());
         wait = next === fingerprint ? Math.min(wait * 2, 30_000) : 1000; fingerprint = next;
         const live = new Set(state().nodes.filter(n => n.status === "dispatched").map(n => n.dispatchId));
@@ -180,6 +199,7 @@ async function admit(dir: string, owner: PlanOwner, actor: Actor, snapshot: Plan
     assertPlanOwner(dir, owner);
     const current = readPlanState(dir, readLedger(dir)), target = current.nodes.find(n => n.id === node.id);
     if (current.state !== "running" || current.revision !== snapshot.revision || target?.status !== "ready" || canonical(current.definition.nodes.find(n => n.id === node.id)) !== canonical(definition) || (definition.kind === "step" && stepSlots(current) >= parallel)) return undefined;
+    if (!modeAllowsAdmission(current, openStudy(dir).study.autonomy, definition)) return undefined;
     const dispatchId = nextDispatchId(current, node.id);
     commit(dir, [], [{ actor, type: "node.intent", data: { revision: current.revision, node: node.id, dispatchId, ...prepared } }]);
     return readPlanState(dir, readLedger(dir)).nodes.find(n => n.id === node.id)!;
@@ -190,3 +210,13 @@ async function admit(dir: string, owner: PlanOwner, actor: Actor, snapshot: Plan
 function stepSlots(state: PlanState): number {
   return state.nodes.filter(n => n.kind === "step" && n.status === "dispatched").length;
 }
+
+function nodeMode(policy: Autonomy, node: PlanNode) {
+  return resolvePhaseAutonomy(policy, node.kind === "hub" ? undefined : node.phase);
+}
+/** Step effects are exclusive even when ordinary steps may run in parallel. */
+function modeAllowsAdmission(state: PlanState, policy: Autonomy, next: PlanNode): boolean {
+  const active = state.nodes.filter(node => node.status === "dispatched" && node.kind !== "gate");
+  if (active.some(node => nodeMode(policy, state.definition.nodes.find(value => value.id === node.id)!) === "step")) return false;
+  return nodeMode(policy, next) !== "step" || active.length === 0;
+}

package/src/plan/definition.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { validatePhase, type Phase } from "../autonomy.ts";
 import { COMMANDS } from "../commands-table.ts";
 import { boundedText, commit, onlyKeys, plain, readJsonFile, sha256, type Actor } from "../study.ts";
 
@@ -7,7 +8,7 @@ export const PLAN_BYTES = 65_536, PLAN_ID_BYTES = 128;
 export const STEP_COMMANDS = ["lit.search", "lit.verify", "lit.bib", "cite.check", "attempt.run", "investigate.close", "ablate.close", "final.close", "paper.build", "watch.run"] as const;
 export type StepCommand = typeof STEP_COMMANDS[number];
 export type StepArgs = Record<string, string | number | boolean | string[]>;
-type BaseNode = { id: string; needs: string[] };
+type BaseNode = { id: string; needs: string[]; phase?: Phase };
 export type PlanNode = BaseNode & (
   { kind: "step"; command: StepCommand; args: StepArgs } |
   { kind: "hub"; campaign: string; unit: string } |
@@ -74,20 +75,20 @@ function validateDefinition(raw: unknown): PlanDefinition {
   const nodes: PlanNode[] = raw.nodes.map((n: unknown, index: number) => {
     if (!plain(n)) throw new Error(`plan node[${index}]: object required`);
     const id = nodeId(n.id, `plan node[${index}].id`), needs = n.needs === undefined ? [] : references(n.needs, `plan node ${String(n.id)}.needs`);
-    const base = { id, needs };
+    const base = { id, needs, ...(n.phase === undefined ? {} : { phase: validatePhase(n.phase) }) };
     switch (n.kind) {
       case "step": {
-        onlyKeys(n, ["id", "kind", "needs", "command", "args"], `plan step ${id}`);
+        onlyKeys(n, ["id", "kind", "needs", "phase", "command", "args"], `plan step ${id}`);
         if (!STEP_COMMANDS.includes(n.command as StepCommand)) throw new Error(`plan step ${id}: unknown command ${String(n.command)} (allowed: ${STEP_COMMANDS.join(", ")})`);
         const command = n.command as StepCommand;
         return { ...base, kind: "step", command, args: stepArgs(n.args ?? {}, command, id) };
       }
       case "hub": {
-        onlyKeys(n, ["id", "kind", "needs", "campaign", "unit"], `plan hub ${id}`);
+        onlyKeys(n, ["id", "kind", "needs", "phase", "campaign", "unit"], `plan hub ${id}`);
         return { ...base, kind: "hub", campaign: nodeId(n.campaign, `plan hub ${id}.campaign`), unit: nodeId(n.unit, `plan hub ${id}.unit`) };
       }
       case "gate":
-        onlyKeys(n, ["id", "kind", "needs", "binds"], `plan gate ${id}`);
+        onlyKeys(n, ["id", "kind", "needs", "phase", "binds"], `plan gate ${id}`);
         return { ...base, kind: "gate", binds: references(n.binds, `plan gate ${id}.binds`) };
       default: throw new Error(`plan node ${id}: unknown node kind ${String(n.kind)}; ${compatible}`);
     }
@@ -137,6 +138,17 @@ function validateDefinition(raw: unknown): PlanDefinition {
   if (Buffer.byteLength(JSON.stringify(result, null, 2) + "\n") > PLAN_BYTES) throw new Error(`plan: exceeds ${PLAN_BYTES} bytes`);
   return result;
 }
+/** A plan gate inherits only one explicitly declared phase shared by all immediate targets. */
+export function guardedPlanPhase(definition: PlanDefinition, gate: string): Phase | undefined {
+  if (!gate.startsWith("plan:")) return undefined;
+  const id = gate.slice(5);
+  if (!definition.nodes.some(node => node.id === id && node.kind === "gate")) return undefined;
+  const targets = definition.nodes.filter(node => node.needs.includes(id) || definition.edges.some(([from, to]) => from === id && to === node.id));
+  if (!targets.length || targets.some(node => node.kind === "hub" || node.phase === undefined)) return undefined;
+  const phases = new Set(targets.map(node => node.phase));
+  return phases.size === 1 ? targets[0]!.phase : undefined;
+}
+
 export function readPlan(dir: string): PlanDefinition | undefined {
   const file = join(dir, "plan.json");
   if (!existsSync(file)) return undefined;

package/src/plan/state.ts

@@ -1,13 +1,27 @@
+import { resolvePhaseAutonomy, type Autonomy } from "../autonomy.ts";
 import { gateState, plain, sha256, boundedText, onlyKeys, type Actor, type GateName, type GateState, type LedgerEvent, type PendingEvent } from "../study.ts";
 import { PLAN_ID_BYTES, readPlan, validatePlan, type PlanDefinition, type PlanNode } from "./definition.ts";
 
 export const PLAN_GATE_BYTES = "plan:".length + PLAN_ID_BYTES;
 
 export type NodeStatus = "pending" | "ready" | "dispatched" | "done" | "failed" | "cancelled" | "uncertain" | "stale" | "skipped";
-export interface NodeState { id: string; kind: PlanNode["kind"]; status: NodeStatus; dispatchId?: string; dispatchCount?: number; retryOf?: string; output?: unknown; attemptId?: string; taskId?: number; hubProject?: string; reason?: string; gate?: GateState; lastObserved?: { revision: number; dispatchId: string; status: NodeStatus; at: string; output?: unknown; reason?: string } }
+export interface NodeState { stepCancellation?: { revision: number; dispatchId: string; commandId: string }; id: string; kind: PlanNode["kind"]; status: NodeStatus; dispatchId?: string; dispatchCount?: number; retryOf?: string; output?: unknown; attemptId?: string; taskId?: number; hubProject?: string; reason?: string; gate?: GateState; lastObserved?: { revision: number; dispatchId: string; status: NodeStatus; at: string; output?: unknown; reason?: string; step?: true } }
 export interface ControlRequest { action: "pause" | "resume" | "retry" | "cancel" | "skip"; node?: string; commandId: string; expectedRevision: number }
-export interface ControlResult { commandId: string; revision: number; action: ControlRequest["action"]; node?: string; state: "paused" | "running" | "done"; status?: NodeStatus }
-export interface PlanState { definition: PlanDefinition; revision: number; state: "paused" | "running" | "done"; nodes: NodeState[]; uncertain: string[] }
+export interface ControlResult { commandId: string; revision: number; action: ControlRequest["action"]; node?: string; state: "paused" | "running" | "done" | "failed"; status?: NodeStatus }
+export interface PlanState { pauseReason?: "step"; definition: PlanDefinition; revision: number; state: "paused" | "running" | "done" | "failed"; nodes: NodeState[]; uncertain: string[] }
+export const TERMINAL_NODE_STATUSES: readonly NodeStatus[] = ["done", "failed", "cancelled", "uncertain", "skipped"];
+export function hasRemainingWork(state: PlanState): boolean { return state.nodes.some(node => !TERMINAL_NODE_STATUSES.includes(node.status)); }
+function hasStepOutcome(node: NodeState): boolean {
+  if (node.status === "cancelled" && node.dispatchId === undefined && node.stepCancellation) return true;
+  return node.lastObserved?.step === true && node.lastObserved.dispatchId === node.dispatchId && node.lastObserved.status === node.status && TERMINAL_NODE_STATUSES.includes(node.status);
+}
+function matchesStepPause(state: PlanState, node: NodeState, data: Record<string, unknown>): boolean {
+  if (typeof data.dispatchId !== "string" || !hasStepOutcome(node)) return false;
+  const cancelled = node.stepCancellation;
+  if (cancelled && node.status === "cancelled" && node.dispatchId === undefined) return data.revision === state.revision && cancelled.revision === data.revision && cancelled.dispatchId === data.dispatchId && cancelled.commandId === data.commandId;
+  const observed = node.lastObserved;
+  return !!observed && node.dispatchId === data.dispatchId && observed.dispatchId === data.dispatchId && observed.revision === data.revision;
+}
 const statuses: readonly NodeStatus[] = ["pending", "ready", "dispatched", "done", "failed", "cancelled", "uncertain", "stale", "skipped"];
 const recovery = "; run ares plan show and retry with its revision and a new --command-id";
 function bad(message: string): never { throw new Error(`plan: ${message}${recovery}`); }
@@ -35,7 +49,7 @@ function descendants(definition: PlanDefinition, roots: Set<string>): Set<string
 }
 function reset(node: NodeState, status: NodeStatus): void {
   node.status = status; delete node.output; delete node.reason; delete node.gate;
-  delete node.dispatchId;
+  delete node.dispatchId; delete node.stepCancellation;
   // A retry must create a child attempt, while hub task references stay read-only.
   if (status === "pending" && node.attemptId) { node.retryOf = node.attemptId; delete node.attemptId; }
 }
@@ -90,15 +104,17 @@ function refresh(state: PlanState, decisions: Map<string, LedgerEvent>): void {
   }
   for (const node of state.definition.nodes) visit(node.id);
   state.uncertain = state.nodes.filter(n => n.status === "uncertain").map(n => n.id);
-  if (state.nodes.length && state.nodes.every(n => n.status === "done" || n.status === "skipped")) state.state = "done";
-  else if (state.state === "done") state.state = "paused";
+  if (state.nodes.length && state.nodes.every(n => n.status === "done" || n.status === "skipped")) { state.state = "done"; delete state.pauseReason; }
+  // Only completed step-policy effects introduce terminal failure; legacy plans keep their prior recovery flow.
+  else if (state.nodes.length && !hasRemainingWork(state) && state.nodes.some(hasStepOutcome)) { state.state = "failed"; delete state.pauseReason; }
+  else if (state.state === "done" || state.state === "failed") state.state = "paused";
 }
 /** Sole state authority: replay ledger events; no cache or snapshot is written. */
 /** Optional observer sees each effective, refreshed event; it must not mutate the folded state. */
 export function foldPlan(events: LedgerEvent[], onEvent?: (state: PlanState, event: LedgerEvent) => void): PlanState | undefined {
   let state: PlanState | undefined;
   const decisions = new Map<string, LedgerEvent>();
-  const dispatches = new Set<string>();
+  const dispatches = new Set<string>(), stepPauses = new Set<string>();
   for (const event of events) {
     const d = event.data;
     if (event.type === "gate.approve" || event.type === "gate.reject") {
@@ -127,19 +143,34 @@ export function foldPlan(events: LedgerEvent[], onEvent?: (state: PlanState, eve
     }
     if (!state) continue;
     if (!["plan.control", "plan.paused", "node.intent", "node.observed", "node.stale"].includes(event.type)) continue;
-    if (event.type !== "node.observed" && d.revision !== state.revision) continue;
-    if (event.type === "plan.paused") state.state = "paused";
+    const stepPause = event.type === "plan.paused" && d.reason === "step";
+    if (event.type !== "node.observed" && !stepPause && d.revision !== state.revision) continue;
+    if (event.type === "plan.paused") {
+      if (stepPause) {
+        const target = state.nodes.find(node => node.id === d.node), key = canonical([d.node, d.dispatchId]);
+        if (!target || !matchesStepPause(state, target, d) || stepPauses.has(key)) continue;
+        stepPauses.add(key); state.pauseReason = "step";
+      } else delete state.pauseReason;
+      state.state = "paused";
+    }
     else if (event.type === "plan.control") {
       const request = validateControl(d.request);
       if (request.expectedRevision !== state.revision) bad("plan.control revision mismatch; restore the last valid ledger");
-      if (request.action === "pause") state.state = "paused";
-      else if (request.action === "resume") state.state = "running";
+      if (request.action === "pause") { state.state = "paused"; delete state.pauseReason; }
+      else if (request.action === "resume") { state.state = "running"; delete state.pauseReason; }
       else {
         const target = state.nodes.find(n => n.id === request.node);
         if (!target) bad(`control references missing node ${request.node}`);
         const affected = descendants(state.definition, new Set([target.id]));
         for (const node of state.nodes) if (affected.has(node.id) && node.id !== target.id && consumed(node)) reset(node, "stale");
+        let cancelled = request.action === "cancel" && hasStepOutcome(target)
+          ? { revision: state.revision, dispatchId: target.stepCancellation?.dispatchId ?? target.lastObserved!.dispatchId, commandId: request.commandId } : undefined;
+        if (d.stepCancel !== undefined) {
+          if (request.action !== "cancel" || target.kind === "gate" || target.status !== "dispatched" || typeof d.stepCancel !== "string" || target.dispatchId !== d.stepCancel) bad("step cancellation binding does not match the dispatched effect; restore the valid ledger or inspect ares plan show before retrying with a new command-id");
+          cancelled = { revision: state.revision, dispatchId: d.stepCancel, commandId: request.commandId };
+        }
         reset(target, request.action === "retry" ? "pending" : request.action === "skip" ? "skipped" : "cancelled");
+        if (cancelled) target.stepCancellation = cancelled;
       }
     } else {
       const node = state.nodes.find(n => n.id === d.node);
@@ -168,7 +199,7 @@ export function foldPlan(events: LedgerEvent[], onEvent?: (state: PlanState, eve
           if (node.kind !== "hub" || !Number.isSafeInteger(d.taskId) || (d.taskId as number) < 1 || (node.taskId !== undefined && node.taskId !== d.taskId)) {
             node.status = "failed"; delete node.output;
             node.reason = "hub child task binding changed or invalid; inspect ahub study show and retry explicitly";
-            node.lastObserved = { revision: d.revision as number, dispatchId, status: "failed", at: event.at, reason: node.reason };
+            node.lastObserved = { revision: d.revision as number, dispatchId, status: "failed", at: event.at, reason: node.reason, ...(d.step === true ? { step: true as const } : {}) };
             refresh(state, decisions); onEvent?.(state, event); continue;
           }
           node.taskId = d.taskId as number;
@@ -178,7 +209,7 @@ export function foldPlan(events: LedgerEvent[], onEvent?: (state: PlanState, eve
         if (node.status === "done" && d.output !== undefined) node.output = d.output;
         delete node.reason;
         if (typeof d.reason === "string") node.reason = boundedText(d.reason, `node ${node.id} reason`, 500);
-        node.lastObserved = { revision: d.revision as number, dispatchId, status: node.status, at: event.at, ...(d.output !== undefined ? { output: d.output } : {}), ...(node.reason !== undefined ? { reason: node.reason } : {}) };
+        node.lastObserved = { revision: d.revision as number, dispatchId, status: node.status, at: event.at, ...(d.output !== undefined ? { output: d.output } : {}), ...(node.reason !== undefined ? { reason: node.reason } : {}), ...(d.step === true && TERMINAL_NODE_STATUSES.includes(node.status) ? { step: true as const } : {}) };
       }
     }
     refresh(state, decisions); onEvent?.(state, event);
@@ -211,7 +242,7 @@ function controlRequest(raw: unknown): ControlRequest {
   if ((action === "pause" || action === "resume") ? node !== undefined : node === undefined) bad(`control ${action} ${node === undefined ? "requires a node" : "takes no node"}`);
   return { action, commandId, expectedRevision: raw.expectedRevision as number, ...(node !== undefined ? { node } : {}) };
 }
-export function prepareControl(state: PlanState, events: LedgerEvent[], raw: unknown, actor: Actor): { result: ControlResult; event?: PendingEvent } {
+export function prepareControl(state: PlanState, events: LedgerEvent[], raw: unknown, actor: Actor, policy?: Autonomy): { result: ControlResult; event?: PendingEvent; pause?: PendingEvent } {
   const request = validateControl(raw);
   for (const e of events) if (e.type === "plan.control" && plain(e.data.request) && e.data.request.commandId === request.commandId) {
     if (canonical(e.data.request) !== canonical(request)) bad(`command-id ${request.commandId} already has a different payload`);
@@ -226,9 +257,14 @@ export function prepareControl(state: PlanState, events: LedgerEvent[], raw: unk
     if (request.action === "skip" && (node.kind === "gate" || node.status === "dispatched" || node.status === "done")) bad(`cannot skip ${node.kind} node ${node.id} in ${node.status}; approve its gate or cancel running work first`);
     if (request.action === "retry" && (node.status === "dispatched" || node.status === "ready" || node.status === "pending")) bad(`cannot retry node ${node.id} in ${node.status}; wait for an outcome first`);
   }
-  const pending: PendingEvent = { actor, type: "plan.control", data: { revision: state.revision, request } };
-  const next = foldPlan([...events, { v: 1, at: new Date().toISOString(), ...pending }])!;
+  const target = state.nodes.find(node => node.id === request.node), definition = state.definition.nodes.find(node => node.id === request.node);
+  const stepCancel = policy !== undefined && request.action === "cancel" && target?.status === "dispatched" && definition && definition.kind !== "gate" && resolvePhaseAutonomy(policy, definition.kind === "hub" ? undefined : definition.phase) === "step";
+  if (stepCancel && !target?.dispatchId) bad("dispatched step has no cancellation binding; restore its intent before retrying plan control");
+  const pending: PendingEvent = { actor, type: "plan.control", data: { revision: state.revision, request, ...(stepCancel ? { stepCancel: target!.dispatchId } : {}) } };
+  const at = new Date().toISOString(), projected = foldPlan([...events, { v: 1, at, ...pending }])!;
+  const pause: PendingEvent | undefined = stepCancel && hasRemainingWork(projected) ? { actor, type: "plan.paused", data: { revision: state.revision, node: target!.id, dispatchId: target!.dispatchId, commandId: request.commandId, reason: "step" } } : undefined;
+  const next = pause ? foldPlan([...events, { v: 1, at, ...pending }, { v: 1, at, ...pause }])! : projected;
   const result: ControlResult = { commandId: request.commandId, revision: state.revision, action: request.action, ...(request.node ? { node: request.node, status: next.nodes.find(n => n.id === request.node)!.status } : {}), state: next.state };
   pending.data.result = result;
-  return { result, event: pending };
+  return { result, event: pending, ...(pause ? { pause } : {}) };
 }

package/src/playbook.ts

@@ -1,7 +1,7 @@
 /** Standalone workflow for one agent session. Printed by `ares playbook` and the `ares_playbook` tool. */
-export const PLAYBOOK = `ares research playbook (A1 literature, A2 experiments, A3 plan DAG, investigate/final phases, A4 paper/review, A5 memory/evolution, A6 setup/console/watch)
+export const PLAYBOOK = `ares research playbook (A1 literature, A2 experiments, A3 plan DAG, investigate/final phases, A4 paper/review, A5 memory/evolution, A6 setup/console/watch, autonomy policy, study export)
 
-Before starting a phase, create its study once: ares init <dir> --question "..." [--mode experiment] [--autonomy gates]. Use --mode experiment for experiment phases; reuse the initialized study thereafter. Install amem 0.20.3 or a compatible CLI for phase lessons and archive; these keep the study cwd and agent attribution.
+Before starting a phase, create its study once: ares init <dir> --question "..." [--mode experiment] [--autonomy auto|gates|copilot|step]. Use --mode experiment for experiment phases; reuse the initialized study thereafter. Phase lessons and archive call the amem CLI on PATH (its output parser was written against amem 0.20.3; no amem version is tested live here); these keep the study cwd and agent attribution.
 
 Literature workflow
 
@@ -118,6 +118,18 @@ ares lessons <dir> --for "derive reusable skills from study evidence"
 3. List every state: ares skill list <dir>. Decide with ares skill decide <dir> <name> accept|reject|withdraw --reason TEXT [--pr URL]. Accept requires a reviewed HTTP(S) PR URL without credentials. Ares stores the actor's reference, never opens, checks or merges it. Every terminal state is final; withdraw is allowed only while proposed.
 4. Survey and experiment studies support lessons, archive and the skill queue. Survey archives can derive resolved review contradictions; experiment pivots/selection/results remain experiment-only. Open contradictions are never exported. Durable vault promotion stays in amem vault-candidates; ares never writes the vault.
 
+Autonomy policy
+
+1. Read ares autonomy show <dir> for the stored policy and each phase's effective mode; change it with ares autonomy set <dir> <auto|gates|copilot|step> [--phase PHASE]. Phases: scope, literature, hypotheses, design, investigate, ablate, final, posthoc, write, review, archive. Only auto approves pending gates automatically; gates, copilot and step need a recorded approval. Policy changes keep earlier gate decisions and record actor, from, to and phase.
+2. step: the CLI controller runs one effect node at a time and pauses (pauseReason step) after each terminal outcome while work remains; resume with ares plan control <dir> resume --command-id <new-id> --expected-revision <revision>. MCP resume changes the same plan state but starts no controller.
+3. copilot: a producing phase in copilot mode makes its drafts usable only after ares gate approve <dir> accept:hypotheses|accept:paper|accept:reviews binds their current content hash. Source edits or new relevant journal entries make the accept pending again. Drafting and own-draft checks stay usable before acceptance; acceptance is a checkpoint, not scientific verification.
+4. Plain auto|gates studies keep study v1; object policies, copilot and step write study v2, which 0.1.0 refuses without changing the file. A plan node may declare phase; 0.1.0 refuses such plans the same way.
+
+Study export
+
+1. ares study export <dir> --bundle <new-or-empty-dir-outside-the-study> [--list] writes manifest.json, ledger.jsonl, attempts.jsonl, results.json, reviews.jsonl and evidence.json from committed study files only, never the executor workdir. --list names the files and writes nothing.
+2. Identities are hashes; values are metrics, seeds, statuses, exit codes, durations, counts and closed enums. Paths, mounts, container ids, argv, env, image names (digests kept) and free text are dropped. A planted path, URL, NAME=value assignment or key-like token in any decoded key or string refuses the whole export and writes nothing; remove it from the study record and retry.
+
 Archive workflow
 
 ares lessons <dir> --for "archive the completed study"