@obversa/runtime 0.2.0 → 0.2.1

package/dist/api.js

@@ -1,7 +1,7 @@
 import { compileGraph } from './chunk-DEW5R23M.js';
 export { compileGraph } from './chunk-DEW5R23M.js';
-import { LoopError, needDecisionsOf, DEFAULT_FANOUT_CONCURRENCY, setMeta, jobMeta, describeConditions, Budget, currentBranch, assertDistinctSeats, seatIdentity, copyJobMeta, predicate, setLabel, resolveEnv, scrubCapture, withConditionPreparation, toCondition, prepareCondition, validateCallbackRequest, reportedUsage, validateIncompleteResultEvidence, engineSelection, validateAgentResult, requireFinalResultText, isRepo, addWorktree, childContext, stageAll, commit, mergeBranch, removeWorktree, deleteBranch, headSha, hasStagedChanges, reviewPanel, createCallbackGate, defineAgent, isInfrastructureError, validateCallbackResponse, gitRoot, captureGitWorkspaceSnapshot, workspaceFingerprint, revisionFromOutcome, agentJob, commandJob, approval, mergeNoCommit, mergeAbort, normalizeFeedbackSeverity, nodeJobContext, outcomeFromAgentText, requireNonEmptyFiles, requireNoFiles, panelReviewers, delegateNodeJob, branchCommits, RECORDED_ENGINE_USAGE, compareGitWorkspaceSnapshots } from './chunk-ZXVFWRW5.js';
-export { LoopError, RECORDED_ENGINE_USAGE, agentCheck, agentJob, all, always, any, approval, bodyPassed, callbackRequestDigest, commandJob, commandSucceeds, copyJobMeta, createCallbackGate, defineAgent, defineSkill, describeConditions, failed, finalResultPart, finalResultText, fnJob, fromFile, gateJob, jobMeta, kickback, minConfidence, never, not, passed, predicate, prove, quorum, renderPlan, reviewContext, reviewPanel, revisionRequest, toCondition, validateAgentResult, validateCallbackRequest, validateCallbackResponse, withEnv } from './chunk-ZXVFWRW5.js';
+import { LoopError, needDecisionsOf, interactionIdentity, DEFAULT_FANOUT_CONCURRENCY, interactionDeclaration, setMeta, jobMeta, describeConditions, Budget, currentBranch, assertDistinctSeats, seatIdentity, copyJobMeta, predicate, setLabel, resolveEnv, scrubCapture, withConditionPreparation, toCondition, prepareCondition, validateCallbackRequest, reportedUsage, validateIncompleteResultEvidence, engineSelection, validateAgentResult, requireFinalResultText, isRepo, addWorktree, childContext, stageAll, commit, mergeBranch, removeWorktree, deleteBranch, headSha, hasStagedChanges, reviewPanel, createCallbackGate, defineAgent, isInfrastructureError, validateCallbackResponse, gitRoot, captureGitWorkspaceSnapshot, workspaceFingerprint, savedInteraction, revisionFromOutcome, checkpointInteraction, jsonSnapshot, outcomeSnapshot, agentJob, humanReview, commandJob, approval, requestInteraction, mergeNoCommit, mergeAbort, normalizeFeedbackSeverity, DEFAULT_INTERACTION, nodeJobContext, outcomeFromAgentText, requireNonEmptyFiles, requireNoFiles, panelReviewers, hasSavedInteraction, fnJob, kickback, delegateNodeJob, branchCommits, RECORDED_ENGINE_USAGE, compareGitWorkspaceSnapshots } from './chunk-G2OIKOUI.js';
+export { LoopError, RECORDED_ENGINE_USAGE, agentCheck, agentJob, all, always, any, approval, bodyPassed, callbackRequestDigest, commandJob, commandSucceeds, copyJobMeta, createCallbackGate, defineAgent, defineSkill, describeConditions, failed, finalResultPart, finalResultText, fnJob, fromFile, gateJob, humanReview, jobMeta, kickback, minConfidence, never, not, passed, predicate, prove, quorum, renderPlan, reviewContext, reviewPanel, revisionRequest, toCondition, validateAgentResult, validateCallbackRequest, validateCallbackResponse, withEnv } from './chunk-G2OIKOUI.js';
 import { runRuntimeProcess, processText } from './chunk-NIBHM5I5.js';
 import { loadRunDefinition, StorageError, validateDomainEventBatch, validateNewDomainEvent, validateDomainEventEnvelope, validateDomainEventId, validateArtifactReference, validateStorageId } from './chunk-RZLMX3IA.js';
 export { StorageError, loadRunDefinition, persistRunDefinition, validateArtifactReference, validateArtifactScope, validateDomainEventBatch, validateDomainEventEnvelope, validateDomainEventId, validateEventStreamRef, validateNewArtifact, validateNewDomainEvent, validateRunDefinition, validateRunStartRecord, validateRunStoragePolicy, validateRunStorageRecord } from './chunk-RZLMX3IA.js';
@@ -14,7 +14,7 @@ import { randomUUID, createHash } from 'crypto';
 import { SUBAGENT_TOOLS, snapshotApprovalSubject, assertApprovalPermissionsAdmitted, validateAcceptedResultRecord, EngineIncompleteResultError, EngineError, classifyEngineFailure, LANE_DEAD_FAILURES, validateCallbackEvent, ApprovalSubjectError, isEngine, cloneFrozenJson as cloneFrozenJson$1, validateApprovalRecord, digestJson as digestJson$1, GraphExecutionError, validateApprovalSubject, modelIdentity, validateActionDecision } from '@obversa/api';
 export { ApprovalSubjectError, EngineError, EngineIncompleteResultError, GraphExecutionError, LANE_DEAD_FAILURES, acceptedResultMatches, approvalSubjectDigest, classifyEngineFailure, createApprovalCallbackGate, validateAcceptedResultRecord, validateApprovalRecord, validateCallbackEvent } from '@obversa/api';
 import { readFileSync, mkdirSync, existsSync, writeFileSync, appendFileSync, lstatSync, realpathSync } from 'fs';
-import { mkdir, stat, open, rename, rm, realpath, readFile, lstat } from 'fs/promises';
+import { mkdir, readFile, stat, open, rename, rm, realpath, lstat } from 'fs/promises';
 import { join, resolve, basename, extname, dirname, isAbsolute, relative, sep } from 'path';
 import pLimit from 'p-limit';
 import toposort from 'toposort';
@@ -150,12 +150,13 @@ function stopQuestions(what = "the draft") {
     },
     stop_reason: {
       type: "choice",
-      instructions: "Are we at the point of diminishing returns? If so, which kind; if not, continue.",
+      instructions: "If a person must settle a product decision, choose product_decision. Otherwise, are we at the point of diminishing returns? If so, which kind; if not, continue.",
       criteria: {
         holds: `${what} holds for this use case.`,
         over_polishing: "The remaining findings are taste, nits or edge cases past the bar.",
         not_converging: "The same class of finding keeps returning, so another round will not fix it.",
-        continue: "Another round is worth it."
+        continue: "Another round is worth it.",
+        product_decision: "A person must settle a product decision before this review can continue."
       }
     }
   };
@@ -164,7 +165,7 @@ function judge(seat, opts) {
   if (!Number.isSafeInteger(opts.cap) || opts.cap < 1) {
     throw new TypeError("judge cap must be a positive integer");
   }
-  return { kind: "judge", seat, cap: opts.cap, questions: opts.questions ?? stopQuestions() };
+  return { kind: "judge", seat, cap: opts.cap, questions: opts.questions ?? stopQuestions(), ...opts.interaction ? { interaction: opts.interaction } : {} };
 }
 function isJudge(value) {
   return typeof value === "object" && value !== null && value.kind === "judge";
@@ -183,17 +184,21 @@ function judgeDecision(answers) {
   const doing = answers.worth_doing?.noul ?? answers.worth_doing?.probability;
   const holds = answers.holds?.noul ?? answers.holds?.probability;
   const reason = answers.stop_reason?.choice ?? "unknown";
+  if (reason === "product_decision") return { again: false, stop: "product_decision", reason: "the judge requested a product decision" };
+  if (reason === "holds" || reason === "over_polishing") {
+    return { again: false, stop: "ship", reason: `the judge chose ${reason}` };
+  }
   if (reason !== "unknown" && reason !== "continue") {
-    return { again: false, reason: `the judge chose ${reason}` };
+    return { again: false, stop: "fail", reason: `the judge chose ${reason}` };
   }
   if (typeof holds === "number" && holds >= 0.5) {
-    return { again: false, reason: `the judge says it holds (${holds.toFixed(2)})` };
+    return { again: false, stop: "ship", reason: `the judge says it holds (${holds.toFixed(2)})` };
   }
   if (typeof doing === "number" && doing < 0.5) {
-    return { again: false, reason: `the judge says the findings are not worth doing (${doing.toFixed(2)})` };
+    return { again: false, stop: "ship", reason: `the judge says the findings are not worth doing (${doing.toFixed(2)})` };
   }
   if (typeof worth === "number" && worth < 0.5) {
-    return { again: false, reason: `the judge says another round is not worth it (${worth.toFixed(2)})` };
+    return { again: false, stop: "fail", reason: `the judge says another round is not worth it (${worth.toFixed(2)})` };
   }
   return {
     again: true,
@@ -225,6 +230,29 @@ async function askJudge(cfg, state, ctx, path) {
   ctx.emit({ kind: "refine:judge", ts: Date.now(), path: [...path], answers, reason: decision.reason });
   return { answers, decision };
 }
+async function consultJudge(cfg, initialState, ctx, path, options) {
+  let state = initialState;
+  let pending = options.pending;
+  for (; ; ) {
+    if (pending) {
+      options.save(state);
+      const answer2 = await requestInteraction(
+        cfg.interaction ?? DEFAULT_INTERACTION,
+        "What product decision should guide this review?",
+        jsonSnapshot({
+          requester: { path, identity: options.identity, engine: cfg.seat.identity, round: state.round },
+          material: state
+        }),
+        ctx
+      );
+      if ("paused" in answer2) return { state, paused: answer2.paused };
+      state = { ...state, productFeedback: [...state.productFeedback ?? [], answer2.response] };
+    }
+    const { decision } = await askJudge(cfg, state, ctx, path);
+    if (decision.stop !== "product_decision") return { state, decision };
+    pending = true;
+  }
+}
 
 // src/core/dag.ts
 function slug(s) {
@@ -339,7 +367,7 @@ function dag(config) {
     return isJudge(budget) ? budget.cap : budget;
   };
   const routeKickbacks = config.maxKickbacks !== void 0 && (perTargetBudget || maxKickbacks > 0);
-  const judgeHistory = /* @__PURE__ */ new Map();
+  const identity = interactionIdentity(config);
   const dependents = new Map(names.map((n) => [n, []]));
   for (const [dep, name] of edges) dependents.get(dep).push(name);
   const ancestorsOf = (name) => {
@@ -371,12 +399,17 @@ function dag(config) {
     const path = [...parent.path, config.name];
     const depth = parent.depth + 1;
     const ts = () => Date.now();
-    const targetCounts = /* @__PURE__ */ new Map();
+    const checkpointPath = [...path, "@judge-kickback"];
+    const saved = savedInteraction(parent, checkpointPath, identity);
+    let pending = saved?.pending;
+    const targetCounts = new Map(Object.entries(saved?.targetCounts ?? {}));
+    const judgeHistory = new Map(Object.entries(saved?.history ?? {}));
+    const productFeedback = new Map(Object.entries(saved?.productFeedback ?? {}));
     parent.emit({ kind: "dag:start", ts: ts(), path, depth, nodes: names });
     const limit2 = pLimit(limitN);
-    const results = /* @__PURE__ */ new Map();
-    const memo = /* @__PURE__ */ new Map();
-    const attempts = /* @__PURE__ */ new Map();
+    const results = new Map(Object.entries(saved?.results ?? {}));
+    const memo = new Map([...results].map(([name, outcome2]) => [name, Promise.resolve(outcome2)]));
+    const attempts = new Map(Object.entries(saved?.attempts ?? {}));
     let stopped = false;
     const pendingKickback = /* @__PURE__ */ new Map();
     const nodeContext = (name) => {
@@ -615,8 +648,8 @@ function dag(config) {
     };
     await Promise.all(names.map(run2));
     if (routeKickbacks) {
-      let used = 0;
-      const rejected = /* @__PURE__ */ new Set();
+      let used = Number(saved?.used ?? 0);
+      const rejected = new Set(saved?.rejected ?? []);
       const emitKickback = (from, to, reason, accepted, count, limit3, note) => parent.emit({
         kind: "dag:kickback",
         ts: ts(),
@@ -641,7 +674,7 @@ function dag(config) {
         const request = revisionFromOutcome(results.get(from));
         const to = request.target;
         const { reason } = request;
-        const count = (targetCounts.get(to) ?? 0) + 1;
+        const count = pending?.from === from ? pending.count : (targetCounts.get(to) ?? 0) + 1;
         targetCounts.set(to, count);
         const limit3 = targetLimit(to);
         const allow = nodes.get(from).acceptsKickbackTo;
@@ -657,20 +690,61 @@ function dag(config) {
         let effectiveReason = reason;
         if (cfgJudge !== void 0 && withinBudget && !hasBlockFinding(requestFindings)) {
           const history = judgeHistory.get(to) ?? [];
-          const state = {
+          const state = pending?.from === from ? pending.state : {
+            ...productFeedback.has(to) ? { productFeedback: productFeedback.get(to) } : {},
             latestFindings: requestFindings,
             rounds: history,
             round: count,
             cap: cfgJudge.cap
           };
-          const { decision } = await askJudge(cfgJudge, state, parent, path);
+          const result = await consultJudge(cfgJudge, state, parent, path, {
+            identity: interactionIdentity({ identity, from, to }),
+            pending: pending?.from === from,
+            save: (questionState) => checkpointInteraction(parent, checkpointPath, identity, jsonSnapshot({
+              pending: { from, count, state: questionState },
+              results: Object.fromEntries([...results].map(([name, outcome2]) => [name, outcomeSnapshot(outcome2)])),
+              attempts: Object.fromEntries(attempts),
+              targetCounts: Object.fromEntries(targetCounts),
+              history: Object.fromEntries(judgeHistory),
+              productFeedback: Object.fromEntries(productFeedback),
+              used,
+              rejected: [...rejected]
+            }))
+          });
+          if ("paused" in result) {
+            record4(from, result.paused, "done");
+            break;
+          }
+          checkpointInteraction(parent, checkpointPath, identity, null);
+          pending = void 0;
+          productFeedback.set(to, result.state.productFeedback ?? []);
+          const { decision } = result;
           judgeHistory.set(to, [
             ...history,
             { round: count, findings: requestFindings, counts: countBySeverity(requestFindings) }
           ]);
           if (!decision.again) {
-            rejected.add(from);
             emitKickback(from, to, `${reason} (${decision.reason})`, false, count, limit3, decision.reason);
+            if (decision.stop === "ship") {
+              const shipped = record4(from, {
+                status: "pass",
+                confidence: results.get(from).confidence,
+                summary: decision.reason,
+                data: results.get(from).data
+              }, "done");
+              memo.set(from, Promise.resolve(shipped));
+              const unblocked = dirtyFrom(from);
+              unblocked.delete(from);
+              for (const d of unblocked) {
+                memo.delete(d);
+                results.delete(d);
+                rejected.delete(d);
+              }
+              stopped = false;
+              await Promise.all(names.map(run2));
+              continue;
+            }
+            rejected.add(from);
             continue;
           }
           effectiveReason = `${reason} (${decision.reason})`;
@@ -750,7 +824,7 @@ function dag(config) {
     parent.emit({ kind: "dag:end", ts: ts(), path, outcome });
     return outcome;
   };
-  return setMeta(job, {
+  return interactionDeclaration(setMeta(job, {
     kind: "dag",
     name: config.name,
     ...config.maxKickbacks !== void 0 ? { maxKickbacks: config.maxKickbacks } : {},
@@ -771,7 +845,7 @@ function dag(config) {
         job: jobMeta(nodeJob)
       };
     })
-  });
+  }), config);
 }
 function sequence(name, ...jobs) {
   const nodes = {};
@@ -944,9 +1018,15 @@ function loop(config) {
     const path = [...parent.path, config.name];
     const depth = parent.depth + 1;
     const ts = () => Date.now();
-    let lastReview;
-    let lastGate;
-    let iteration = 0;
+    const checkpointPath = [...path, "@interaction-loop"];
+    const identity = interactionIdentity({ config, params: parent.params });
+    const saved = savedInteraction(parent, checkpointPath, identity);
+    let checkpointed = saved !== void 0;
+    let resumePhase = saved?.phase;
+    let lastReview = saved?.lastReview ?? parent.lastReview;
+    let lastGate = saved?.lastGate;
+    let iteration = typeof saved?.iteration === "number" ? saved.iteration : 0;
+    if (resumePhase === "body") iteration -= 1;
     const ctxAt = (iter, lastOutcome) => childContext(parent, {
       depth,
       path,
@@ -957,6 +1037,7 @@ function loop(config) {
     });
     parent.emit({ kind: "loop:start", ts: ts(), path, depth, max: config.max });
     const finish = async (outcome, iterations) => {
+      if (checkpointed && outcome.status !== "paused" && outcome.status !== "aborted") checkpointInteraction(parent, checkpointPath, identity, null);
       parent.emit({ kind: "loop:end", ts: ts(), path, outcome, iterations });
       if (config.onComplete) {
         try {
@@ -1003,7 +1084,7 @@ function loop(config) {
         config.until ? prepareCondition(config.until, entryContext) : void 0,
         config.stopOn ? prepareCondition(config.stopOn, entryContext) : void 0
       ]);
-      if (start) {
+      if (start && !saved) {
         const r = await gate(start, "start", ctxAt(0), void 0);
         parent.emit({
           kind: "loop:condition",
@@ -1019,11 +1100,30 @@ function loop(config) {
             0
           );
       }
-      let last;
-      let consecutiveErrors = 0;
-      let consecutiveReviewFails = 0;
+      let last = saved?.last;
+      let consecutiveErrors = Number(saved?.consecutiveErrors ?? 0);
+      let consecutiveReviewFails = Number(saved?.consecutiveReviewFails ?? 0);
       const tracker = noProgress ? new ProgressTracker(noProgress) : void 0;
+      const samples = [...saved?.samples ?? []];
+      for (const sample of samples) tracker?.record(sample);
       let warnedInert = false;
+      const checkpointContext = (ctx, phase) => ({
+        ...ctx,
+        interactionCheckpoint() {
+          checkpointed = true;
+          parent.interactionCheckpoint?.();
+          checkpointInteraction(parent, checkpointPath, identity, jsonSnapshot({
+            phase,
+            iteration,
+            consecutiveErrors,
+            consecutiveReviewFails,
+            samples,
+            ...last ? { last: outcomeSnapshot(last) } : {},
+            ...lastReview ? { lastReview: outcomeSnapshot(lastReview) } : {},
+            ...lastGate ? { lastGate: Object.fromEntries(Object.entries(lastGate).filter(([, value]) => value !== void 0)) } : {}
+          }));
+        }
+      });
       const evaluateConvergence = async (at, gateContext, bodyOutcome) => {
         const conv = until ? await gate(until, "until", gateContext, bodyOutcome) : {
           met: bodyOutcome.status === "pass",
@@ -1068,7 +1168,7 @@ function loop(config) {
         }
         let reviewOutcome;
         try {
-          reviewOutcome = await config.review(ctxAt(at, bodyOutcome));
+          reviewOutcome = await config.review(checkpointContext(ctxAt(at, bodyOutcome), "review"));
         } catch (e) {
           throw LoopError.from(e, {
             code: "VALIDATION",
@@ -1135,7 +1235,7 @@ function loop(config) {
         }
         return { conv, turnReview: reviewOutcome };
       };
-      if (config.checkFirst) {
+      if (config.checkFirst && !saved) {
         await yieldToLoop();
         if (parent.signal.aborted)
           return finish(
@@ -1152,7 +1252,7 @@ function loop(config) {
             { status: "aborted", summary: "aborted by signal" },
             iteration
           );
-        if (config.max != null && iteration >= config.max) {
+        if (resumePhase !== "review" && config.max != null && iteration >= config.max) {
           return finish(
             {
               status: "exhausted",
@@ -1164,13 +1264,15 @@ function loop(config) {
             iteration
           );
         }
-        iteration += 1;
+        const resumingReview = resumePhase === "review";
+        resumePhase = void 0;
+        if (!resumingReview) iteration += 1;
         const ctx = ctxAt(iteration, last);
         let turnReview;
-        parent.emit({ kind: "loop:iteration", ts: ts(), path, iteration });
+        if (!resumingReview) parent.emit({ kind: "loop:iteration", ts: ts(), path, iteration });
         let bodyThrew = false;
         try {
-          last = await config.body(ctx);
+          if (!resumingReview) last = await config.body(checkpointContext(ctx, "body"));
           consecutiveErrors = 0;
         } catch (e) {
           bodyThrew = true;
@@ -1261,7 +1363,7 @@ function loop(config) {
             iteration
           );
         }
-        if (config.onIteration) {
+        if (config.onIteration && !resumingReview) {
           try {
             await config.onIteration(last, ctx);
           } catch (e) {
@@ -1273,7 +1375,7 @@ function loop(config) {
             });
           }
         }
-        if (stopOn) {
+        if (stopOn && !resumingReview) {
           const r = await gate(stopOn, "stopOn", ctx, last);
           parent.emit({
             kind: "loop:condition",
@@ -1321,7 +1423,7 @@ function loop(config) {
               });
             }
           }
-          const report = tracker.record({
+          const sample = {
             iteration,
             fingerprint,
             signal: signalValue,
@@ -1330,7 +1432,9 @@ function loop(config) {
             gate: noProgress.gate && until && !conv.met ? conv.output : void 0,
             confidence: turnReview?.confidence ?? conv.confidence ?? last.confidence,
             reason: turnReview ? turnReview.summary ?? "review rejected" : conv.reason
-          });
+          };
+          samples.push(Object.fromEntries(Object.entries(sample).filter(([, value]) => value !== void 0)));
+          const report = tracker.record(sample);
           if (!warnedInert && tracker.isInert()) {
             warnedInert = true;
             parent.log(
@@ -1386,7 +1490,7 @@ function loop(config) {
       );
     }
   };
-  return setMeta(job, {
+  return interactionDeclaration(setMeta(job, {
     kind: "loop",
     name: config.name,
     max: config.max,
@@ -1398,7 +1502,7 @@ function loop(config) {
     review: !!config.review,
     maxReviewRestarts: config.maxReviewRestarts,
     body: jobMeta(config.body)
-  });
+  }), config);
 }
 function delay(ms, signal) {
   if (signal.aborted) return Promise.resolve();
@@ -1617,11 +1721,13 @@ var NOISE = /* @__PURE__ */ new Set([
   "engine:thinking"
 ]);
 function readResumeRecord(path) {
+  const receipts = [];
+  const interactions = /* @__PURE__ */ new Map();
   const anchors = /* @__PURE__ */ new Map();
   const stages = /* @__PURE__ */ new Map();
   const usage2 = /* @__PURE__ */ new Map();
   const started = /* @__PURE__ */ new Set();
-  if (!existsSync(path)) return { outcomes: { anchors, stages }, usage: usage2 };
+  if (!existsSync(path)) return { outcomes: { anchors, stages, interactions }, usage: usage2, receipts };
   const lines = readFileSync(path, "utf8").split(/\r?\n/);
   for (const [lineNumber, line] of lines.entries()) {
     if (!line) continue;
@@ -1631,11 +1737,19 @@ function readResumeRecord(path) {
     } catch {
       continue;
     }
-    if (event.kind === "workflow:start") {
+    if (event.kind === "engine:usage") receipts.push(event.usage);
+    if (event.kind === "interaction:checkpoint") {
+      const key = event.path.join("/");
+      if (event.data === null) interactions.delete(key);
+      else interactions.set(key, { identity: event.identity, workspace: event.workspace, data: cloneFrozenJson(event.data) });
+    } else if (event.kind === "workflow:start") {
       const key = event.path.join("/");
       const prior = anchors.get(key);
       if (prior?.identity !== event.identity || prior.workspace !== event.workspace) {
         const prefix = key ? `${key}/` : "";
+        for (const stage2 of interactions.keys()) {
+          if (stage2.startsWith(prefix)) interactions.delete(stage2);
+        }
         for (const stage2 of stages.keys()) {
           if (stage2.startsWith(prefix)) stages.delete(stage2);
         }
@@ -1671,7 +1785,7 @@ function readResumeRecord(path) {
       }
     }
   }
-  return { outcomes: { anchors, stages }, usage: usage2 };
+  return { outcomes: { anchors, stages, interactions }, usage: usage2, receipts };
 }
 function ensureDir(path) {
   const dir = dirname(path);
@@ -2370,7 +2484,10 @@ async function run(job, options = {}) {
       thin: options.recordTo === "auto",
       ...resumed === void 0 ? {} : { resume: true }
     }));
-    if (resumed !== void 0 && resumed.outcomes.anchors.size > 0) {
+    if (resumed !== void 0) {
+      if (resumed.outcomes.interactions.size > 0) {
+        for (const receipt of resumed.receipts) budget?.addUsage(receipt);
+      }
       initialState[RESUME_STAGE_OUTCOMES] = resumed.outcomes;
       initialState[RESUME_RECORDED_USAGE] = resumed.usage;
     }
@@ -2601,8 +2718,8 @@ function parseFrontMatter(source) {
 function briefFromFile(path) {
   return parseFrontMatter(readFileSync(path, "utf8"));
 }
-function person(question) {
-  return { kind: "person", question: text(question, "person question") };
+function person(question, options = {}) {
+  return { kind: "person", question: text(question, "person question"), ...options };
 }
 function stage(name, config) {
   return { name: text(name, "stage name"), config: { ...config } };
@@ -2782,6 +2899,7 @@ function recordedFamilyGate(panel, reviewers, writerStageNames, writerFamilies,
     try {
       const all2 = recordedUsage(ctx);
       const beforeLength = all2.length;
+      const resumingInteraction = hasSavedInteraction(ctx, ctx.path);
       const writerSide = (records) => records.filter(
         (record4) => record4.role === "writer" && record4.stage !== void 0 && writerStageNames.includes(record4.stage)
       );
@@ -2793,7 +2911,7 @@ function recordedFamilyGate(panel, reviewers, writerStageNames, writerFamilies,
       const current = recordedUsage(ctx);
       const after = current.slice(beforeLength);
       const afterWriters = writerSide(after);
-      if (writerRunsInsidePanel && afterWriters.length === 0) {
+      if (writerRunsInsidePanel && afterWriters.length === 0 && !resumingInteraction) {
         throw new LoopError({
           code: "BODY",
           phase: "review",
@@ -2801,7 +2919,7 @@ function recordedFamilyGate(panel, reviewers, writerStageNames, writerFamilies,
         });
       }
       assertRecordedFamilies(afterWriters, reviewerDeclarations);
-      const reviewerSide = after.filter((record4) => record4.role === "reviewer");
+      const reviewerSide = (resumingInteraction ? current : after).filter((record4) => record4.role === "reviewer" && record4.stage === panelStage);
       if (reviewerSide.length === 0) {
         throw new LoopError({
           code: "BODY",
@@ -2906,6 +3024,26 @@ function guardedAgent(brief, named, seat, files, declaredFiles) {
     return requireNoFiles(named.name, required, ctx.workspace.dir, forbidden, "body")(ctx);
   };
 }
+function guardedFn(fn, named, declaredFiles) {
+  const writes = writesOf(named.config);
+  const target = named.config.sendsBackTo;
+  const body = fnJob(named.name, async (ctx) => {
+    const outcome = await fn(ctx);
+    if (outcome.status === "fail" && target !== void 0 && revisionFromOutcome(outcome)?.target === void 0) {
+      return kickback(target, outcome.summary ?? `${named.name} failed`, {
+        confidence: outcome.confidence,
+        data: outcome.data,
+        error: outcome.error
+      });
+    }
+    return outcome;
+  });
+  const forbidden = declaredFiles.filter((file) => !writes.includes(file));
+  return async (ctx) => {
+    const required = writes.length ? requireNonEmptyFiles(named.name, body, ctx.workspace.dir, writes) : body;
+    return requireNoFiles(named.name, required, ctx.workspace.dir, forbidden, "body")(ctx);
+  };
+}
 function unchangedNoteGuard(label, job, writes) {
   const previousHashKey = `declarativePreviousHash:${label}`;
   return async (ctx) => {
@@ -2949,7 +3087,11 @@ function judgedReview(brief, config, cfgJudge, panel) {
   const file = writesOf(config)[0];
   const history = [];
   let previousDraft;
+  let productFeedback = [];
+  const identity = interactionIdentity({ brief, config, cfgJudge });
   return async (ctx) => {
+    const checkpointPath = [...ctx.path, "@judge-review"];
+    let saved = savedInteraction(ctx, checkpointPath, identity);
     let draft;
     let changedLines;
     if (file !== void 0) {
@@ -2960,7 +3102,13 @@ function judgedReview(brief, config, cfgJudge, panel) {
       }
       previousDraft = draft;
     }
-    const panelOutcome = await panel({
+    if (saved && saved.state.draft !== draft) saved = void 0;
+    if (saved) {
+      history.splice(0, history.length, ...saved.state.rounds);
+      productFeedback = saved.state.productFeedback ?? [];
+      previousDraft = draft;
+    }
+    const panelOutcome = saved ? saved.panel : await panel({
       ...ctx,
       depth: ctx.depth + 1,
       path: [...ctx.path, "review-panel"]
@@ -2969,7 +3117,8 @@ function judgedReview(brief, config, cfgJudge, panel) {
     const findings = revisionFromOutcome(panelOutcome)?.findings ?? [];
     if (hasBlockFinding(findings)) return panelOutcome;
     const round2 = history.length + 1;
-    const state = {
+    const state = saved ? saved.state : {
+      ...productFeedback.length ? { productFeedback } : {},
       ...useCase !== void 0 ? { useCase } : {},
       ...file !== void 0 ? { file } : {},
       ...draft !== void 0 ? { draft } : {},
@@ -2978,7 +3127,15 @@ function judgedReview(brief, config, cfgJudge, panel) {
       round: round2,
       cap: cfgJudge.cap
     };
-    const { decision } = await askJudge(cfgJudge, state, ctx, ctx.path);
+    const result = await consultJudge(cfgJudge, state, ctx, ctx.path, {
+      identity,
+      pending: saved !== void 0,
+      save: (questionState) => checkpointInteraction(ctx, checkpointPath, identity, jsonSnapshot({ state: questionState, panel: outcomeSnapshot(panelOutcome) }))
+    });
+    if ("paused" in result) return result.paused;
+    checkpointInteraction(ctx, checkpointPath, identity, null);
+    productFeedback = result.state.productFeedback ?? [];
+    const { decision } = result;
     history.push({
       round: round2,
       findings,
@@ -2986,6 +3143,9 @@ function judgedReview(brief, config, cfgJudge, panel) {
       ...changedLines !== void 0 ? { changedLines } : {}
     });
     if (!decision.again) {
+      if (decision.stop === "fail") {
+        throw new LoopError({ code: "VALIDATION", phase: "review", path: ctx.path, message: decision.reason });
+      }
       return { status: "pass", confidence: panelOutcome.confidence, summary: decision.reason, data: panelOutcome.data };
     }
     return { ...panelOutcome, summary: `${panelOutcome.summary} (${decision.reason})` };
@@ -2998,6 +3158,24 @@ function stageJob(brief, named, roles, files, declaredFiles, targetFiles, family
     const guarded = guardedAgent(brief, named, seatRole(roles, config.agent), files, declaredFiles);
     const job = config.reviewedBy === void 0 ? guarded : unchangedNoteGuard(named.name, guarded, writes);
     if (config.reviewedBy === void 0) return job;
+    const reviewRole = role(roles, config.reviewedBy);
+    if (!Array.isArray(reviewRole) && "kind" in reviewRole && reviewRole.kind === "person") {
+      if (!reviewRole.interaction) throw new TypeError("a human reviewer needs an interaction binding");
+      const humanLoop = loop({
+        name: `${named.name}-review`,
+        body: job,
+        max: refineCap(refineOf(config)) + 1,
+        review: humanReview(named.name, {
+          question: reviewRole.question,
+          interaction: reviewRole.interaction,
+          input: async (ctx) => Object.fromEntries(await Promise.all(writes.map(async (file) => [file, await readFile(join(ctx.workspace.dir, file), "utf8")])))
+        })
+      });
+      return interactionDeclaration(copyJobMeta(async (ctx) => {
+        const outcome = await humanLoop(ctx);
+        return outcome.status === "exhausted" ? { ...outcome, status: "fail" } : outcome;
+      }, humanLoop), { humanLoop });
+    }
     const reviewers = panelRole(roles, config.reviewedBy);
     const panel = reviewerPanel(brief, named, reviewers, files, declaredFiles, void 0);
     const refine = refineOf(config);
@@ -3058,9 +3236,27 @@ function stageJob(brief, named, roles, files, declaredFiles, targetFiles, family
   }
   if ("input" in config && config.input !== void 0) {
     const personRole = inputRole(roles, config.input);
-    return approval(named.name, { question: personRole.question, target: config.sendsBackTo });
+    if (!personRole.interaction) return approval(named.name, { question: personRole.question, target: config.sendsBackTo });
+    return async (ctx) => {
+      const identity = interactionIdentity({ brief, named, personRole });
+      const checkpointPath = [...ctx.path, "@person-interaction"];
+      const input = jsonSnapshot({ requester: { path: ctx.path, identity }, material: brief });
+      const result = await requestInteraction(personRole.interaction, personRole.question, input, {
+        ...ctx,
+        interactionCheckpoint() {
+          ctx.interactionCheckpoint?.();
+          checkpointInteraction(ctx, checkpointPath, identity, input);
+        }
+      });
+      if ("paused" in result) return result.paused;
+      checkpointInteraction(ctx, checkpointPath, identity, null);
+      return { status: "pass", summary: result.response.prompt, data: result.response };
+    };
   }
-  throw new TypeError(`stage ${named.name} must declare agent, run, panel or input`);
+  if ("fn" in config && config.fn !== void 0) {
+    return guardedFn(config.fn, named, declaredFiles);
+  }
+  throw new TypeError(`stage ${named.name} must declare agent, run, panel, input or fn`);
 }
 function workflowRecord(outcome) {
   return {
@@ -3085,26 +3281,13 @@ function panelReviewFiles(stages, index) {
   const targetWrites = target === void 0 ? [] : writesOf(target.config);
   return targetWrites.length ? targetWrites : preceding === void 0 ? [] : writesOf(preceding.config);
 }
-function canonicalForDigest(value) {
-  if (typeof value === "function") return `fn:${value.toString()}`;
-  if (Array.isArray(value)) return value.map(canonicalForDigest);
-  if (value !== null && typeof value === "object") {
-    return Object.fromEntries(
-      Object.keys(value).sort().map((key) => [
-        key,
-        canonicalForDigest(value[key])
-      ])
-    );
-  }
-  return value;
-}
 function resumeIdentity(name, config) {
   const declared = {
     name,
     brief: config.brief,
     stages: config.stages.map((named) => ({
       name: named.name,
-      config: canonicalForDigest(named.config)
+      config: interactionIdentity(named.config)
     })),
     roles: Object.fromEntries(Object.entries(config.roles).map(([key, value]) => [
       key,
@@ -3139,6 +3322,10 @@ function resumeGuard(job, identity, label, retrySafe) {
     const parentPath = ctx.path.slice(0, -1).join("/");
     const anchor = resumed?.anchors.get(parentPath);
     const recorded = anchor?.identity === identity && anchor.workspace === ctx.workspace.dir ? resumed?.stages.get(ctx.path.join("/")) : void 0;
+    if (anchor?.identity === identity && anchor.workspace === ctx.workspace.dir && hasSavedInteraction(ctx, ctx.path)) {
+      restoreRecordedUsage(ctx);
+      return delegateNodeJob(ctx, guarded, job, ctx);
+    }
     if (ctx.graph?.attempt === 1 && recorded !== void 0) {
       if (recorded.kind === "interrupted") {
         if (!retrySafe) {
@@ -3162,7 +3349,7 @@ function resumeGuard(job, identity, label, retrySafe) {
     }
     return delegateNodeJob(ctx, guarded, job, ctx);
   };
-  return guarded;
+  return interactionDeclaration(guarded, { identity, label, job });
 }
 async function reconcileInterrupted(ctx, owner, job, label, identity, recordId, startLine) {
   const question = approval(`reconcile ${label}`, {
@@ -3233,10 +3420,12 @@ function workflow(name, config) {
   for (const [index, named] of config.stages.entries()) {
     const stageConfig = named.config;
     if ("agent" in stageConfig && stageConfig.agent !== void 0 && stageConfig.reviewedBy !== void 0) {
-      assertDistinctSeats([
+      const reviewer = role(config.roles, stageConfig.reviewedBy);
+      if (Array.isArray(reviewer)) assertDistinctSeats([
         seatRole(config.roles, stageConfig.agent),
         ...panelRole(config.roles, stageConfig.reviewedBy)
       ]);
+      else if (!("kind" in reviewer) || reviewer.kind !== "person") throw new TypeError("reviewedBy must name a reviewer panel or person");
     }
     if ("panel" in stageConfig && stageConfig.panel !== void 0) {
       const preceding = precedingAgent(config.stages, index);