@staix/agent-research 0.0.0-stage → 0.2.1

package/src/plan/controller.ts

@@ -0,0 +1,222 @@
+import { CopilotAcceptError } from "../copilot.ts";
+import { boundHubTask, type HubClient, type HubObservation } from "./hub.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" }>;
+export interface Observation { status: "dispatched" | "done" | "failed" | "cancelled" | "uncertain"; output?: unknown; reason?: string; progress?: string; taskId?: number; hubProject?: string }
+export interface ControllerRuntime {
+  actor: Actor;
+  hub?: HubClient;
+  signal?: AbortSignal;
+  sleep?: (ms: number) => Promise<void>;
+  clock?: () => number;
+  prepare: (node: StepNode, state: NodeState) => Promise<{ attemptId?: string }>;
+  execute: (node: StepNode, state: NodeState) => Promise<Observation>;
+  reconcile: (node: StepNode, state: NodeState) => Promise<Observation>;
+}
+export interface ControllerOptions { parallel?: number }
+const delay = (ms: number, signal?: AbortSignal): Promise<void> => new Promise(resolve => {
+  if (signal?.aborted) { resolve(); return; }
+  const finish = () => { clearTimeout(timer); signal?.removeEventListener("abort", finish); resolve(); };
+  const timer = setTimeout(finish, ms); signal?.addEventListener("abort", finish, { once: true });
+});
+async function tryTransaction<T>(dir: string, fn: () => T): Promise<{ value: T } | undefined> {
+  try { return { value: await withLock(dir, fn) }; }
+  catch (error) { if (error instanceof StudyLockBusyError) return undefined; throw error; }
+}
+async function transaction<T>(dir: string, fn: () => T): Promise<T> {
+  let wait = 50;
+  for (;;) {
+    const result = await tryTransaction(dir, fn);
+    if (result) return result.value;
+    await delay(wait); wait = Math.min(wait * 2, 1000);
+  }
+}
+/** 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 } = 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));
+    const clock = runtime.clock ?? (() => performance.now());
+    const sleep = (ms: number) => runtime.sleep ? runtime.sleep(ms) : delay(ms, runtime.signal);
+    const polls = new Map<string, { at: number; wait: number; signature: string }>();
+    const schedule = (node: NodeState, observation: Observation) => {
+      if (!node.dispatchId) return;
+      if (observation.status !== "dispatched") { polls.delete(node.dispatchId); return; }
+      const previous = polls.get(node.dispatchId), signature = canonical(observation);
+      const wait = previous?.signature === signature ? Math.min(previous.wait * 2, 30_000) : 1000;
+      polls.set(node.dispatchId, { at: clock() + wait, wait, signature });
+    };
+    const locked = <T>(fn: () => T) => transaction(dir, () => { assertPlanOwner(dir, owner); return fn(); });
+    const observe = async (node: NodeState, observation: Observation) => {
+      const target = state().nodes.find(n => n.id === node.id);
+      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 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;
+      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> => {
+      const definition = state().definition.nodes.find(n => n.id === node.id);
+      if (!definition || (definition.kind === "hub" && !runtime.hub)) return;
+      let observation: Observation;
+      if (definition.kind === "hub") {
+        try { observation = await runtime.hub!.observe(definition.campaign, definition.unit, node.taskId ?? boundHubTask(readLedger(dir), state().revision, node.id)); }
+        catch { observation = { status: "dispatched", reason: "hub read unavailable; check ahub study show and restore hub access" }; }
+      } else if (definition.kind !== "step" || definition.command !== "attempt.run") observation = { status: "uncertain", reason: "step result unavailable after interruption; explicitly retry or skip this node" };
+      else {
+        try { observation = await runtime.reconcile(definition, node); }
+        catch (error) { if (error instanceof StudyLockBusyError) { schedule(node, { status: "dispatched", reason: node.reason }); return; } observation = { status: "dispatched", reason: "attempt observation unavailable; check the executor and run ares attempt reconcile" }; }
+      }
+      await observe(node, observation); schedule(node, observation);
+    };
+    await locked(() => {
+      const current = state();
+      if (current.state === "running") commit(dir, [], [{ actor: runtime.actor, type: "plan.paused", data: { revision: current.revision, reason: "controller startup restores paused" } }]);
+    });
+    for (const node of state().nodes.filter(n => n.status === "dispatched")) await reconcile(node);
+    const active = new Map<string, Promise<void>>();
+    const launch = (definition: StepNode, node: NodeState) => {
+      const work = (async () => {
+        let observation: Observation;
+        let wait = 1000;
+        for (;;) {
+          const current = state().nodes.find(n => n.id === node.id);
+          if (runtime.signal?.aborted || !current || current.dispatchId !== node.dispatchId || current.status !== "dispatched") return;
+          assertPlanOwner(dir, owner);
+          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;
+          }
+        }
+        await observe(node, observation); schedule(node, observation);
+      })();
+      active.set(node.id, work);
+      // The main loop awaits every task; failures are consumed immediately to prevent unhandled rejection.
+      void work.catch(() => {});
+    };
+    let failure: unknown, wait = 500, fingerprint = canonical(state());
+    try {
+      while (!runtime.signal?.aborted) {
+        let current = state();
+        if (current.state === "done" || current.state === "failed") break;
+        if (current.state === "running") {
+          // Pending auto gates are approved only inside a successful controller transaction.
+          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")) {
+              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 } }]);
+          });
+          current = state();
+          for (const node of current.nodes) {
+            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;
+              try { result = await runtime.hub.observe(definition.campaign, definition.unit, binding); }
+              catch { result = { status: "dispatched", reason: "hub read unavailable; check ahub study show and restore hub access" }; }
+              const intent = await admit(dir, owner, runtime.actor, current, node, definition, { ...(result.taskId !== undefined ? { taskId: result.taskId } : {}), ...(result.hubProject !== undefined ? { hubProject: result.hubProject } : {}) }, parallel);
+              if (intent) { await observe(intent, result); schedule(intent, result); }
+              current = state(); continue;
+            }
+            if (definition.kind !== "step") continue;
+            const slots = stepSlots(current);
+            if (slots >= parallel) continue;
+            // A2 permits one active experiment attempt per study.
+            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 (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: 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);
+            if (intent) launch(definition, intent);
+            current = state();
+          }
+        }
+        // Detached attempts are observed while paused too, without admitting new work.
+        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 (["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));
+        for (const id of polls.keys()) if (!live.has(id)) polls.delete(id);
+        const due = [...polls.values()].map(p => Math.max(1, p.at - clock()));
+        const interval = Math.min(wait, ...(due.length ? due : [30_000]));
+        if (active.size) {
+          const settled = await Promise.race([...active].map(async ([id, work]) => { await work; return id; }).concat([sleep(interval).then(() => "")]));
+          if (settled) { await active.get(settled); active.delete(settled); }
+        } else await sleep(interval);
+      }
+    } catch (error) { failure = error; }
+    // Pause stops admission, drains this process's command calls, and leaves detached attempts alive.
+    await Promise.allSettled(active.values());
+    await locked(() => { const current = state(); if (current.state === "running") commit(dir, [], [{ actor: runtime.actor, type: "plan.paused", data: { revision: current.revision, reason: "controller stopped" } }]); });
+    if (failure) throw failure;
+    return state();
+  });
+}
+async function admit(dir: string, owner: PlanOwner, actor: Actor, snapshot: PlanState, node: NodeState, definition: StepNode | HubNode, prepared: { attemptId?: string; taskId?: number; hubProject?: string }, parallel: number): Promise<NodeState | undefined> {
+  const result = await tryTransaction(dir, () => {
+    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)!;
+  });
+  return result?.value;
+}
+
+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

@@ -0,0 +1,168 @@
+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";
+
+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[]; phase?: Phase };
+export type PlanNode = BaseNode & (
+  { kind: "step"; command: StepCommand; args: StepArgs } |
+  { kind: "hub"; campaign: string; unit: string } |
+  { kind: "gate"; binds: string[] }
+);
+export interface PlanDefinition { v: 1; revision: number; nodes: PlanNode[]; edges: [string, string][] }
+const retry = "correct the definition and run ares plan set again";
+const compatible = "use an ares version that supports this plan, keeping plan.json unchanged";
+function nodeId(raw: unknown, what = "plan node id"): string {
+  const id = boundedText(raw, what, PLAN_ID_BYTES);
+  if (Buffer.byteLength(id) > PLAN_ID_BYTES) throw new Error(`${what}: at most ${PLAN_ID_BYTES} bytes`);
+  return id;
+}
+function references(raw: unknown, name: string): string[] {
+  if (!Array.isArray(raw) || raw.length > 128) throw new Error(`${name}: at most 128 node ids required`);
+  return raw.map((id, i) => nodeId(id, `${name}[${i}]`));
+}
+function stepArgs(raw: unknown, command: StepCommand, id: string): StepArgs {
+  const where = `plan step ${id} (${command})`;
+  if (!plain(raw)) throw new Error(`${where}.args: object required`);
+  const spec = COMMANDS.find(c => c.name === command.replace(".", " "))!;
+  const args: StepArgs = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const field = `${where}.args.${key}`;
+    if (key === "json" || (command === "attempt.run" && key === "detach")) throw new Error(`${field}: controller-owned option; remove ${key} and run ares plan set again`);
+    if (command === "lit.search" && key === "query") {
+      const query = boundedText(value, field, 1000);
+      if (Buffer.byteLength(query) > 1000) throw new Error(`${field}: at most 1000 bytes`);
+      args[key] = query; continue;
+    }
+    if (command === "cite.check" && key === "draft") {
+      args[key] = boundedText(value, field, 4096); continue;
+    }
+    if (command === "lit.verify" && key === "ids") {
+      if (!Array.isArray(value) || value.length > 500) throw new Error(`${field}: array of at most 500 candidate ids required`);
+      args[key] = value.map((item, i) => boundedText(item, `${field}[${i}]`, 300)); continue;
+    }
+    const option = Object.hasOwn(spec.options, `--${key}`) ? spec.options[`--${key}`] : undefined;
+    if (!option) throw new Error(`${field}: unknown option ${key}`);
+    if (option === "flag" ? typeof value !== "boolean" : !["string", "number"].includes(typeof value)) throw new Error(`${field}: ${option === "flag" ? "boolean flag" : "string or number value"} required`);
+    if (typeof value === "number" && !Number.isFinite(value)) throw new Error(`${field}: finite value required`);
+    if (typeof value === "string") boundedText(value, field, 4096);
+    args[key] = value as string | number | boolean;
+  }
+  const required = command === "attempt.run" ? ["repo", "commit"] : command === "lit.search" ? ["query"] : command === "cite.check" ? ["draft"] : [];
+  for (const key of required) if (!Object.hasOwn(args, key)) throw new Error(`${where}: required option ${key}; add args.${key} and run ares plan set again`);
+  return args;
+}
+export function validatePlan(raw: unknown): PlanDefinition {
+  try { return validateDefinition(raw); }
+  catch (error) {
+    const message = error instanceof Error ? error.message : "plan: invalid definition";
+    throw new Error(message.includes(compatible) || message.includes("run ares plan set again") ? message : `${message}; ${retry}`);
+  }
+}
+function validateDefinition(raw: unknown): PlanDefinition {
+  if (!plain(raw)) throw new Error("plan: object required");
+  if (raw.v !== 1) throw new Error(`plan: unsupported v ${String(raw.v)} (expected 1); ${compatible}`);
+  onlyKeys(raw, ["v", "revision", "nodes", "edges"], "plan");
+  const revision = raw.revision ?? 1;
+  if (!Number.isSafeInteger(revision) || (revision as number) < 1) throw new Error("plan: revision must be a positive safe integer");
+  if (!Array.isArray(raw.nodes) || raw.nodes.length > 128) throw new Error("plan: at most 128 nodes required");
+  if (!Array.isArray(raw.edges) || raw.edges.length > 512) throw new Error("plan: at most 512 edges required");
+  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, ...(n.phase === undefined ? {} : { phase: validatePhase(n.phase) }) };
+    switch (n.kind) {
+      case "step": {
+        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", "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", "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}`);
+    }
+  });
+  const ids = new Set(nodes.map(n => n.id));
+  const seen = new Set<string>();
+  for (const n of nodes) {
+    if (seen.has(n.id)) throw new Error(`plan: duplicate node id ${n.id}; rename the duplicate node and update its references`);
+    seen.add(n.id);
+  }
+  const edges: [string, string][] = raw.edges.map((e: unknown, index: number) => {
+    if (!Array.isArray(e) || e.length !== 2) throw new Error(`plan edge[${index}]: pair required`);
+    return [nodeId(e[0], `plan edge[${index}].from`), nodeId(e[1], `plan edge[${index}].to`)];
+  });
+  const parents = new Map(nodes.map(n => [n.id, new Set(n.needs)]));
+  for (const [from, to] of edges) {
+    if (!ids.has(from) || !ids.has(to)) throw new Error(`plan edge [${from}, ${to}]: missing endpoint, no node ${!ids.has(from) ? from : to}; add that node or remove this edge`);
+    parents.get(to)!.add(from);
+  }
+  for (const n of nodes) for (const p of n.needs) if (!ids.has(p)) throw new Error(`plan node ${n.id}.needs: missing endpoint, no node ${p}; add that node or remove this dependency`);
+  const visiting = new Set<string>(), visited = new Set<string>();
+  const stack: string[] = [];
+  function visit(id: string): void {
+    if (visiting.has(id)) throw new Error(`plan: cycle through ${[...stack.slice(stack.indexOf(id)), id].reverse().join(" -> ")}; remove one dependency and run ares plan set again`);
+    if (visited.has(id)) return;
+    visiting.add(id); stack.push(id);
+    for (const parent of parents.get(id)!) visit(parent);
+    stack.pop(); visiting.delete(id); visited.add(id);
+  }
+  for (const n of nodes) visit(n.id);
+  const ancestorCache = new Map<string, Set<string>>();
+  function ancestors(id: string): Set<string> {
+    const cached = ancestorCache.get(id);
+    if (cached) return cached;
+    const result = new Set<string>();
+    for (const parent of parents.get(id)!) {
+      result.add(parent);
+      for (const ancestor of ancestors(parent)) result.add(ancestor);
+    }
+    ancestorCache.set(id, result);
+    return result;
+  }
+  for (const n of nodes) if (n.kind === "gate") for (const bound of n.binds) {
+    if (!ids.has(bound) || !ancestors(n.id).has(bound)) throw new Error(`plan gate ${n.id} binds ${bound}, which is not upstream; add an upstream dependency or remove this binding`);
+  }
+  const result: PlanDefinition = { v: 1, revision: revision as number, nodes, edges };
+  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;
+  const raw: unknown = readJsonFile(file, PLAN_BYTES);
+  const definition = validatePlan(raw);
+  if (!plain(raw) || raw.revision === undefined) throw new Error(`plan.json: stored revision required; restore a revisioned definition before running ares plan set again`);
+  return definition;
+}
+/** Caller holds the study lock; definition and initial state share one transaction. */
+export function setPlan(dir: string, raw: unknown, actor: Actor) {
+  const definition = validatePlan(raw), previous = readPlan(dir);
+  definition.revision = (previous?.revision ?? 0) + 1;
+  if (!Number.isSafeInteger(definition.revision)) throw new Error("plan.revision: exhausted; create a new study before setting another plan");
+  const text = JSON.stringify(definition, null, 2) + "\n";
+  commit(dir, [[join(dir, "plan.json"), text, PLAN_BYTES]], [{ actor, type: "plan.set", data: { revision: definition.revision, definition, state: "paused", sha256: sha256(text) } }]);
+  return { definition, state: "paused" as const };
+}

package/src/plan/hub.ts

@@ -0,0 +1,56 @@
+import { isAbsolute, resolve } from "node:path";
+import { spawnRunner, type ProcessRunner } from "../exp/executor.ts";
+import { plain, sha256, type LedgerEvent } from "../study.ts";
+import type { Observation } from "./controller.ts";
+
+export interface HubObservation extends Observation { taskId?: number }
+export interface HubClient { observe(campaign: string, unit: string, taskId?: number): Promise<HubObservation> }
+export const HUB_READ_BYTES = 1_048_576;
+const states = ["backlog", "proposed", "in_progress", "in_review", "approved", "changes_requested", "cancelled", "unknown"];
+const id = (value: unknown): value is string => typeof value === "string" && !!value.trim() && !value.includes("\0") && Buffer.byteLength(value) <= 128;
+const task = (value: unknown): value is number => Number.isSafeInteger(value) && (value as number) > 0;
+function readError(kind: string): HubObservation { return { status: "dispatched", reason: `hub read ${kind}; check ahub study show for this campaign and restore hub access` }; }
+function failed(reason: string, taskId?: number): HubObservation { return { status: "failed", reason: `hub ${reason}; inspect ahub study show, correct the plan reference and retry explicitly`, ...(taskId !== undefined ? { taskId } : {}) }; }
+/** Only bounded status/study-show argv reads; no task creation, activation, approval or other hub write. */
+export function createHubClient(project: string, runner: ProcessRunner = spawnRunner): HubClient {
+  async function read(args: string[]): Promise<{ data?: unknown; error?: HubObservation }> {
+    let result;
+    try { result = await runner({ command: "ahub", args: ["--project", resolve(project), ...args], timeoutMs: 10_000, maxOutputBytes: HUB_READ_BYTES }); }
+    catch { return { error: readError("unavailable") }; }
+    if (result.timedOut) return { error: readError("timeout") };
+    if (result.truncated || Buffer.byteLength(result.stdout) > HUB_READ_BYTES) return { error: readError("oversize") };
+    if (result.exitCode !== 0) return { error: readError("exit") };
+    try { return { data: JSON.parse(result.stdout) }; } catch { return { error: readError("format") }; }
+  }
+  return { observe: async (campaign, unit, expected) => {
+    if (!id(campaign) || campaign.startsWith("-") || !id(unit) || (expected !== undefined && !task(expected))) return failed("reference invalid");
+    const status = await read(["status", "--json"]);
+    if (status.error) return { ...status.error, reason: "hub read project-unavailable: no reachable agent-hub project for this study; run ahub status --json from the study directory" };
+    if (!plain(status.data) || typeof status.data.cwd !== "string" || !isAbsolute(status.data.cwd) || status.data.cwd.includes("\0") || Buffer.byteLength(status.data.cwd) > 4096) return readError("project-format");
+    const hubProject = status.data.cwd;
+    const finish = (result: HubObservation): HubObservation => ({ ...result, hubProject });
+    const result = await read(["study", "show", campaign, "--json"]);
+    if (result.error) return finish(result.error);
+    const raw = result.data;
+    if (!plain(raw) || raw.id !== campaign || !task(raw.revision) || typeof raw.held !== "boolean" || !Array.isArray(raw.reasons) || !raw.reasons.every(r => typeof r === "string") || !Array.isArray(raw.units) || raw.units.length > 128) return finish(readError("format"));
+    // The shipped projection has no status field; it names non-current approval in reasons.
+    if (raw.reasons.includes("campaign approval is not current")) return finish({ status: "dispatched", reason: "hub campaign approval pending; a person approves it in ahub study" });
+    const units = raw.units.filter(u => plain(u) && u.unitId === unit);
+    if (!units.length) return finish(failed("unit missing from current campaign revision", expected));
+    if (units.length !== 1) return finish(readError("format"));
+    const found = units[0] as Record<string, unknown>;
+    if (found.taskId === null) return finish({ status: "dispatched", reason: "hub campaign activation pending: no child taskId; a person activates the campaign in ahub study" });
+    if (found.state === "unknown") return finish(failed("child task missing", expected));
+    if (!task(found.taskId) || typeof found.state !== "string" || !states.includes(found.state)) return finish(readError("unsupported"));
+    if (expected !== undefined && found.taskId !== expected) return finish(failed("child task binding changed", expected));
+    if (found.state === "cancelled") return finish(failed("child task cancelled", found.taskId));
+    const reference = { campaign, unit, campaignRevision: raw.revision, taskId: found.taskId, state: found.state };
+    return finish({ status: found.state === "approved" ? "done" : "dispatched", taskId: found.taskId,
+      ...(found.state === "approved" ? { output: { ...reference, sha256: sha256(JSON.stringify(reference)) } } : {}),
+      progress: JSON.stringify(reference) });
+  } };
+}
+/** The first known binding of this node/revision remains pinned through retries. */
+export function boundHubTask(events: LedgerEvent[], revision: number, node: string): number | undefined {
+  return events.find(e => (e.type === "node.intent" || e.type === "node.observed") && e.data.revision === revision && e.data.node === node && task(e.data.taskId))?.data.taskId as number | undefined;
+}