@obversa/runtime 0.1.0 → 0.2.1

package/dist/api.js

@@ -1,25 +1,27 @@
 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, nodeJobContext, outcomeFromAgentText, requireNonEmptyFiles, requireNoFiles, panelReviewers, delegateNodeJob, branchCommits, RECORDED_ENGINE_USAGE, compareGitWorkspaceSnapshots } from './chunk-DV5P4QLI.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-DV5P4QLI.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';
 export { resolveGraphPlan, validateGraphDescription } from './chunk-3L6YNPN6.js';
 import { cloneFrozenJson, JsonValueError, digestJson, canonicalJson, GraphValidationError } from './chunk-5GLEABOU.js';
 export { GraphValidationError, JsonValueError } from './chunk-5GLEABOU.js';
-import { randomUUID, createHash, randomBytes } from 'crypto';
+import { newRunId, startSupervisor, formatEvent, runningTotal } from './chunk-XDMDT67Q.js';
+export { formatEvent, renderRecord, summarizeRecord } from './chunk-XDMDT67Q.js';
+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';
 import '@obversa/core/command';
-import { homedir } from 'os';
 import { createServer } from 'http';
 import { isDeepStrictEqual } from 'util';
+import { homedir } from 'os';
 import { hasExactFields, isObject, bindingFromSubject } from '@obversa/api/approval-support';
 import { acceptedResultSupport } from '@obversa/api/accepted-result-support';
 import { fileURLToPath } from 'url';
@@ -119,6 +121,139 @@ Write a concise MERGE SYNTHESIS for the commit body: what this line of work acco
   return requireFinalResultText(out).trim();
 }
 
+// src/core/judge.ts
+function stopQuestions(what = "the draft") {
+  return {
+    holds: {
+      type: "noul",
+      instructions: `For this use case, does ${what} hold as it stands?`,
+      criteria: {
+        true: "The latest findings are nits, taste or nothing, and a reader of this kind of work would not notice what remains.",
+        false: "The latest findings include a block, or shoulds a reader of this kind of work would notice."
+      }
+    },
+    worth_doing: {
+      type: "noul",
+      instructions: "Read the latest findings themselves. For this use case, are they worth acting on?",
+      criteria: {
+        true: "They name things a reader of this kind of work would stumble on, misread or distrust.",
+        false: "They are taste, edge cases, or polish past the bar the use case sets; acting on them would not change what a reader gets."
+      }
+    },
+    worth_another_round: {
+      type: "noul",
+      instructions: "Given the whole history and whether the latest findings are worth doing, is another round worth it?",
+      criteria: {
+        true: "The findings are worth doing, and the rounds so far have fixed what was found, so one more pass would land them.",
+        false: "The findings are not worth doing for this use case; or the same class of finding keeps returning; or the change between rounds is small; or the work is being polished past the bar."
+      }
+    },
+    stop_reason: {
+      type: "choice",
+      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.",
+        product_decision: "A person must settle a product decision before this review can continue."
+      }
+    }
+  };
+}
+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(), ...opts.interaction ? { interaction: opts.interaction } : {} };
+}
+function isJudge(value) {
+  return typeof value === "object" && value !== null && value.kind === "judge";
+}
+function hasBlockFinding(findings) {
+  return (findings ?? []).some((finding) => normalizeFeedbackSeverity(finding.severity) === "block");
+}
+var SEVERITIES = ["block", "should-fix", "nice-to-have", "approve"];
+function countBySeverity(findings) {
+  const counts = Object.fromEntries(SEVERITIES.map((severity) => [severity, 0]));
+  for (const finding of findings) counts[normalizeFeedbackSeverity(finding.severity)] += 1;
+  return counts;
+}
+function judgeDecision(answers) {
+  const worth = answers.worth_another_round?.noul ?? answers.worth_another_round?.probability;
+  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, stop: "fail", reason: `the judge chose ${reason}` };
+  }
+  if (typeof holds === "number" && holds >= 0.5) {
+    return { again: false, stop: "ship", reason: `the judge says it holds (${holds.toFixed(2)})` };
+  }
+  if (typeof doing === "number" && doing < 0.5) {
+    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, stop: "fail", reason: `the judge says another round is not worth it (${worth.toFixed(2)})` };
+  }
+  return {
+    again: true,
+    reason: `the judge says another round is worth it${typeof worth === "number" ? ` (${worth.toFixed(2)})` : ""}`
+  };
+}
+async function askJudge(cfg, state, ctx, path) {
+  const judgeJob = agentJob({
+    label: "refine:judge",
+    engine: cfg.seat.engine,
+    model: cfg.seat.identity.model,
+    workspaceMode: "none",
+    tools: [],
+    leaf: true,
+    prompt: JSON.stringify({ state, questions: cfg.questions })
+  });
+  const outcome = await judgeJob({ ...ctx, depth: ctx.depth + 1, path: [...path, "refine-judge"] });
+  let answers = {};
+  if (outcome.status === "pass") {
+    try {
+      const parsed = JSON.parse(String(outcome.data ?? ""));
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        answers = parsed;
+      }
+    } catch {
+    }
+  }
+  const decision = judgeDecision(answers);
+  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) {
   return s.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-+|-+$)/g, "") || "node";
@@ -158,10 +293,11 @@ function validateKickbackBudget(budget, nodes) {
         message: `dag maxKickbacks names unknown target "${target}"`
       });
     }
+    if (isJudge(limit2)) continue;
     if (!Number.isInteger(limit2) || limit2 < 0) {
       throw new LoopError({
         code: "CONFIG",
-        message: `dag maxKickbacks for "${target}" must be a non-negative integer`
+        message: `dag maxKickbacks for "${target}" must be a non-negative integer or a judge`
       });
     }
   }
@@ -220,8 +356,18 @@ function dag(config) {
   const stopOnError = config.stopOnError ?? true;
   const maxKickbacks = config.maxKickbacks ?? 0;
   const perTargetBudget = typeof maxKickbacks !== "number";
-  const targetLimit = (target) => typeof maxKickbacks === "number" ? maxKickbacks : maxKickbacks[target] ?? 0;
+  const targetJudge = (target) => {
+    if (typeof maxKickbacks === "number") return void 0;
+    const budget = maxKickbacks[target];
+    return isJudge(budget) ? budget : void 0;
+  };
+  const targetLimit = (target) => {
+    if (typeof maxKickbacks === "number") return maxKickbacks;
+    const budget = maxKickbacks[target] ?? 0;
+    return isJudge(budget) ? budget.cap : budget;
+  };
   const routeKickbacks = config.maxKickbacks !== void 0 && (perTargetBudget || maxKickbacks > 0);
+  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) => {
@@ -253,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) => {
@@ -497,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(),
@@ -523,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;
@@ -533,6 +684,71 @@ function dag(config) {
           emitKickback(from, to, reason, false, count, limit3, note);
           continue;
         }
+        const requestFindings = request.findings ?? [];
+        const cfgJudge = targetJudge(to);
+        const withinBudget = perTargetBudget ? count <= limit3 : used < limit3;
+        let effectiveReason = reason;
+        if (cfgJudge !== void 0 && withinBudget && !hasBlockFinding(requestFindings)) {
+          const history = judgeHistory.get(to) ?? [];
+          const state = pending?.from === from ? pending.state : {
+            ...productFeedback.has(to) ? { productFeedback: productFeedback.get(to) } : {},
+            latestFindings: requestFindings,
+            rounds: history,
+            round: count,
+            cap: cfgJudge.cap
+          };
+          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) {
+            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})`;
+        }
         if (perTargetBudget ? count > limit3 : used >= limit3) {
           emitKickback(
             from,
@@ -550,7 +766,7 @@ function dag(config) {
           break;
         }
         used += 1;
-        emitKickback(from, to, reason, true, count, limit3);
+        emitKickback(from, to, effectiveReason, true, count, limit3);
         const dirty = dirtyFrom(to);
         for (const d of dirty) {
           memo.delete(d);
@@ -559,8 +775,8 @@ function dag(config) {
         }
         pendingKickback.set(to, {
           status: "fail",
-          summary: `Kicked back from "${from}": ${reason}`,
-          revision: { ...request, source: request.source ?? from }
+          summary: `Kicked back from "${from}": ${effectiveReason}`,
+          revision: { ...request, reason: effectiveReason, source: request.source ?? from }
         });
         stopped = false;
         await Promise.all(names.map(run2));
@@ -608,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 } : {},
@@ -629,7 +845,7 @@ function dag(config) {
         job: jobMeta(nodeJob)
       };
     })
-  });
+  }), config);
 }
 function sequence(name, ...jobs) {
   const nodes = {};
@@ -802,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,
@@ -815,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 {
@@ -861,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",
@@ -877,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",
@@ -926,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",
@@ -993,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(
@@ -1010,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",
@@ -1022,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;
@@ -1119,7 +1363,7 @@ function loop(config) {
             iteration
           );
         }
-        if (config.onIteration) {
+        if (config.onIteration && !resumingReview) {
           try {
             await config.onIteration(last, ctx);
           } catch (e) {
@@ -1131,7 +1375,7 @@ function loop(config) {
             });
           }
         }
-        if (stopOn) {
+        if (stopOn && !resumingReview) {
           const r = await gate(stopOn, "stopOn", ctx, last);
           parent.emit({
             kind: "loop:condition",
@@ -1179,7 +1423,7 @@ function loop(config) {
               });
             }
           }
-          const report = tracker.record({
+          const sample = {
             iteration,
             fingerprint,
             signal: signalValue,
@@ -1188,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(
@@ -1244,7 +1490,7 @@ function loop(config) {
       );
     }
   };
-  return setMeta(job, {
+  return interactionDeclaration(setMeta(job, {
     kind: "loop",
     name: config.name,
     max: config.max,
@@ -1256,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();
@@ -1475,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;
@@ -1489,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);
         }
@@ -1529,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);
@@ -1613,259 +1869,6 @@ function assertSafeDirectory(root, dir, label) {
     throw new Error(`unsafe ${label}: resolves outside the workspace`);
   }
 }
-var NOISE2 = /* @__PURE__ */ new Set([
-  "engine:text",
-  "engine:thinking"
-]);
-function runsHome() {
-  return join(process.env.OBVERSA_HOME ?? join(homedir(), ".obversa"), "runs");
-}
-function slug2(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "run";
-}
-function newRunId(title) {
-  return `${slug2(title)}-${randomBytes(3).toString("hex")}`;
-}
-function startSupervisor(input) {
-  const dir = join(runsHome(), input.runId);
-  const eventsPath = join(dir, "events.jsonl");
-  const proofsPath = join(dir, "proofs.jsonl");
-  const statusPath = join(dir, "status.json");
-  mkdirSync(dir, { recursive: true });
-  writeBestEffort(eventsPath, "");
-  writeBestEffort(proofsPath, "");
-  const startedAt = Date.now();
-  const status = {
-    runId: input.runId,
-    pid: process.pid,
-    cwd: input.cwd,
-    title: input.title,
-    startedAt,
-    updatedAt: startedAt,
-    status: "running",
-    shape: input.shape,
-    live: {
-      path: [],
-      iteration: 0,
-      usage: {
-        inputTokens: 0,
-        outputTokens: 0,
-        cacheReadInputTokens: 0,
-        cacheCreationInputTokens: 0,
-        calls: 0,
-        unmeasuredCalls: 0
-      }
-    }
-  };
-  const active = /* @__PURE__ */ new Map();
-  let proofCount = 0;
-  const writeStatus = () => {
-    status.updatedAt = Date.now();
-    writeBestEffort(statusPath, JSON.stringify(status, null, 2));
-  };
-  const refreshCurrent = () => {
-    status.live.active = active.size ? Object.fromEntries(active.entries()) : void 0;
-    status.live.current = [...active.values()].sort((a, b) => {
-      const deadline = (a.deadlineAt ?? Number.POSITIVE_INFINITY) - (b.deadlineAt ?? Number.POSITIVE_INFINITY);
-      return deadline || b.startedAt - a.startedAt;
-    })[0];
-  };
-  const activeKey = (kind, path) => `${kind}:${path.join("\0")}`;
-  writeStatus();
-  const sink = (event) => {
-    if (!NOISE2.has(event.kind)) appendBestEffort(eventsPath, event);
-    switch (event.kind) {
-      case "run:end":
-        status.live.lastOutcome = outcomeSummary(event.outcome);
-        break;
-      case "loop:iteration":
-        status.live.path = event.path;
-        status.live.iteration = event.iteration;
-        break;
-      case "loop:condition":
-        status.live.lastGate = {
-          which: event.which,
-          met: event.result.met,
-          confidence: event.result.confidence,
-          reason: event.result.reason
-        };
-        break;
-      case "condition:result":
-        status.live.lastGate = {
-          which: event.label,
-          met: event.result.met,
-          confidence: event.result.confidence,
-          reason: event.result.reason
-        };
-        break;
-      case "dag:node": {
-        const path = [...event.path, event.node];
-        status.live.path = path;
-        if (event.phase === "start") {
-          active.set(activeKey("dag-node", path), {
-            kind: "dag-node",
-            path,
-            node: event.node,
-            startedAt: event.ts,
-            timeoutMs: event.timeoutMs,
-            deadlineAt: event.timeoutMs ? event.ts + event.timeoutMs : void 0
-          });
-        } else {
-          active.delete(activeKey("dag-node", path));
-        }
-        refreshCurrent();
-        break;
-      }
-      case "job:start": {
-        const path = [...event.path, event.label];
-        active.set(activeKey("job", path), {
-          kind: "job",
-          path: event.path,
-          label: event.label,
-          startedAt: event.ts,
-          timeoutMs: event.timeoutMs,
-          deadlineAt: event.timeoutMs ? event.ts + event.timeoutMs : void 0
-        });
-        refreshCurrent();
-        break;
-      }
-      case "loop:end":
-      case "dag:end":
-      case "job:end":
-        status.live.path = event.path;
-        status.live.lastOutcome = outcomeSummary(event.outcome);
-        if (event.kind === "job:end") {
-          active.delete(activeKey("job", [...event.path, event.label]));
-          refreshCurrent();
-        }
-        break;
-      case "engine:usage":
-        status.live.usage.calls += 1;
-        if (event.usage.kind === "unknown") {
-          status.live.usage.unmeasuredCalls += 1;
-        } else {
-          status.live.usage.inputTokens += event.usage.inputTokens;
-          status.live.usage.outputTokens += event.usage.outputTokens;
-          status.live.usage.cacheReadInputTokens += event.usage.cacheReadInputTokens ?? 0;
-          status.live.usage.cacheCreationInputTokens += event.usage.cacheCreationInputTokens ?? 0;
-        }
-        break;
-      case "proof": {
-        const proof = {
-          name: event.name,
-          path: event.path,
-          artifact: event.artifact
-        };
-        proofCount += 1;
-        appendBestEffort(proofsPath, proof);
-        status.evidence = {
-          count: proofCount,
-          indexPath: proofsPath,
-          latest: proof
-        };
-        break;
-      }
-    }
-    if (!NOISE2.has(event.kind)) writeStatus();
-  };
-  const finish = (outcome) => {
-    status.status = outcome.status;
-    status.endedAt = Date.now();
-    status.live.current = void 0;
-    status.live.active = void 0;
-    status.live.lastOutcome = outcomeSummary(outcome);
-    writeStatus();
-  };
-  return { runId: input.runId, dir, sink, finish };
-}
-function outcomeSummary(outcome) {
-  return {
-    status: outcome.status,
-    summary: outcome.summary,
-    late: outcome.late
-  };
-}
-function writeBestEffort(path, text6) {
-  try {
-    writeFileSync(path, text6);
-  } catch {
-  }
-}
-function appendBestEffort(path, value) {
-  try {
-    appendFileSync(path, `${JSON.stringify(value)}
-`);
-  } catch {
-  }
-}
-function runningTotal(totals) {
-  const read = totals.cacheReadInputTokens ?? 0;
-  const unmeasured = totals.unmeasuredCalls ?? 0;
-  const missing = unmeasured > 0 ? `, usage unknown on ${unmeasured} call${unmeasured === 1 ? "" : "s"}` : "";
-  const base = `${totals.inputTokens}/${totals.outputTokens} tok`;
-  return `${base}${read > 0 ? `, ${read} tok from cache` : ""}${missing}`;
-}
-function toLine(value) {
-  return value.replace(/[\u0000-\u001f\u007f]+/g, " ");
-}
-function formatEvent(event, totals) {
-  return toLine(renderEvent(event, totals));
-}
-function renderEvent(event, totals) {
-  const at = event.path.length ? `${event.path.join(" \u203A ")} ` : "";
-  switch (event.kind) {
-    case "run:start":
-      return "\u25B8 run";
-    case "run:end":
-      return `\u25C2 run ${event.outcome.status}${event.outcome.late ? " late" : ""} (${runningTotal(event.usage)})`;
-    case "loop:start":
-      return `${at}\u25B8 loop${event.max ? ` (max ${event.max})` : ""}`;
-    case "dag:start":
-      return `${at}\u25B8 dag (${event.nodes.length} nodes)`;
-    case "loop:iteration":
-      return `${at}\xB7 iteration ${event.iteration}`;
-    case "loop:condition":
-      return `${at}\xB7 ${event.which} ${event.result.met ? "met" : "not met"}: ${event.result.reason}`;
-    case "condition:result":
-      return `${at}\xB7 ${event.label} ${event.result.met ? "met" : "not met"}: ${event.result.reason}`;
-    case "loop:review":
-      return `${at}\xB7 review: ${event.outcome.status}${event.outcome.late ? " late" : ""}`;
-    case "loop:end":
-      return `${at}\u25C2 ${event.outcome.status}${event.outcome.late ? " late" : ""} (${event.iterations} iter)`;
-    case "dag:node":
-      return `${at}\xB7 node ${event.node}: ${event.phase}${event.outcome ? ` (${event.outcome.status}${event.outcome.late ? " late" : ""})` : ""}`;
-    case "dag:kickback":
-      return `${at}\u21A9 kickback ${event.accepted ? "accepted" : "rejected"} ${event.from} -> ${event.to} [${event.count}/${event.limit}]: ${event.reason}${event.note ? ` (${event.note})` : ""}`;
-    case "dag:end":
-      return `${at}\u25C2 dag ${event.outcome.status}${event.outcome.late ? " late" : ""}`;
-    case "job:start":
-      return `${at}\u2022 ${event.label}`;
-    case "advisor:consult":
-      return `${at}\u25C7 advisor ${event.label} #${event.call}: ${event.question}`;
-    case "proof":
-      return `${at}\u25C8 proof ${event.name}: ${event.artifact.title ?? event.artifact.path ?? event.artifact.kind}`;
-    case "job:end":
-      return `${at}\u2022 ${event.label}: ${event.outcome.status}${event.outcome.late ? " late" : ""}`;
-    case "engine:tool":
-      return `${at}  tool ${event.name} ${event.phase}`;
-    case "engine:usage": {
-      const call = event.usage.kind === "unknown" ? "usage unknown" : `${event.usage.inputTokens}/${event.usage.outputTokens} tok`;
-      return `${at}  ${event.model}: ${call}${totals ? ` (run ${runningTotal(totals)})` : ""}`;
-    }
-    case "loop:stall":
-      return `${at}\u23F9 stalled after ${event.report.iterations.length} no-progress iterations: ${event.report.reason}`;
-    case "limit:wait":
-      return `${at}\u23F8 limit ${event.code}: waiting ${Math.round(event.waitMs / 1e3)}s`;
-    case "limit:pause":
-      return `${at}\u23F8 paused (${event.code}): ${event.reason}`;
-    case "log":
-      return `${at}${event.message}`;
-    case "error":
-      return `${at}\u2717 ${event.code}: ${event.message}`;
-    default:
-      return `${at}${event.kind}`;
-  }
-}
 function applyEvent(states, event) {
   switch (event.kind) {
     case "callback-requested": {
@@ -2162,14 +2165,11 @@ var MonitorFold = class {
         ...event.note !== void 0 ? { note: event.note } : {}
       });
     }
-    const line = { kind: event.kind, ts: event.ts, path: [...event.path] };
-    if ("node" in event && typeof event.node === "string") line.node = event.node;
-    if ("label" in event && typeof event.label === "string") line.label = event.label;
-    if ("outcome" in event && event.outcome && typeof event.outcome === "object" && "summary" in event.outcome && typeof event.outcome.summary === "string") {
-      line.summary = event.outcome.summary;
+    const line = formatEvent(event, this.usage);
+    if (line !== "") {
+      this.events.push({ ts: event.ts, line });
+      if (this.events.length > EVENT_TAIL) this.events.splice(0, this.events.length - EVENT_TAIL);
     }
-    this.events.push(line);
-    if (this.events.length > EVENT_TAIL) this.events.splice(0, this.events.length - EVENT_TAIL);
   }
   finish(outcome) {
     this.status = "done";
@@ -2359,6 +2359,15 @@ function page(name) {
 (() => {
   const el = (id) => document.getElementById(id);
   const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+  // What the question is about: the raw input, and a link when it names one,
+  // so a reviewer can open the thing being approved instead of taking the
+  // question's word for it.
+  function aboutHtml(input) {
+    if (input === null || input === undefined) return '';
+    const url = input && typeof input === 'object' && !Array.isArray(input) && typeof input.url === 'string' ? input.url : null;
+    const link = url ? '<p><a href="' + esc(url) + '" target="_blank" rel="noopener">' + esc(url) + '</a></p>' : '';
+    return '<pre>' + esc(JSON.stringify(input, null, 2)) + '</pre>' + link;
+  }
   async function answer(requestId, approved) {
     const box = document.querySelector('[data-note="' + CSS.escape(requestId) + '"]');
     const note = box && box.value ? box.value : '';
@@ -2384,8 +2393,8 @@ function page(name) {
       + '<span class="phase" data-phase="' + esc(v.phase) + '" data-status="' + esc(v.outcome ? v.outcome.status : '') + '">' + esc(v.phase === 'done' && v.outcome ? v.outcome.status : v.phase) + '</span></li>'; }).join('');
     el('kickbacks').innerHTML = s.kickbacks.map((k) => '<p class="kick">' + esc(k.from) + ' sent work back to ' + esc(k.to) + (k.accepted ? '' : ' (not accepted' + (k.note ? ': ' + esc(k.note) : '') + ')') + ': ' + esc(k.reason) + ' (' + k.count + ' of ' + k.limit + ')</p>').join('');
     el('pending-title').hidden = s.pending.length === 0;
-    el('pending').innerHTML = s.pending.map((p) => '<div><p>' + esc(p.decisionText) + '</p><form onsubmit="return false"><input data-note="' + esc(p.requestId) + '" placeholder="a note, if any"><button class="yes" data-answer="yes" data-request="' + esc(p.requestId) + '">Yes</button><button data-answer="no" data-request="' + esc(p.requestId) + '">No</button></form></div>').join('');
-    el('record').textContent = s.events.slice(-40).map((e) => new Date(e.ts).toISOString().slice(11, 19) + '  ' + e.kind.padEnd(14) + (e.node || e.label || '') + (e.summary ? '  ' + e.summary : '')).join('\\n');
+    el('pending').innerHTML = s.pending.map((p) => '<div><p>' + esc(p.decisionText) + '</p>' + aboutHtml(p.input) + '<form onsubmit="return false"><input data-note="' + esc(p.requestId) + '" placeholder="a note, if any"><button class="yes" data-answer="yes" data-request="' + esc(p.requestId) + '">Yes</button><button data-answer="no" data-request="' + esc(p.requestId) + '">No</button></form></div>').join('');
+    el('record').textContent = s.events.slice(-40).map((e) => new Date(e.ts).toISOString().slice(11, 19) + '  ' + e.line).join('\\n');
     if (s.status !== 'done') setTimeout(render, 1000);
   }
   render();
@@ -2475,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;
     }
@@ -2706,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 } };
@@ -2733,24 +2745,29 @@ function writesOf(config) {
   if (!writes.length || new Set(writes).size !== writes.length) throw new TypeError("writes must contain unique paths");
   return writes;
 }
-function retryCount(retry, label) {
-  if (retry === void 0) return 0;
-  if (!Number.isSafeInteger(retry) || retry < 0) throw new TypeError(`${label} must be a non-negative integer`);
-  return retry;
+function refineCount(refine, label) {
+  if (refine === void 0) return 0;
+  if (!Number.isSafeInteger(refine) || refine < 0) throw new TypeError(`${label} must be a non-negative integer`);
+  return refine;
+}
+function refineCap(refine) {
+  return isJudge(refine) ? refine.cap : refine;
 }
 function optionalFlag(optional) {
   if (optional === void 0) return void 0;
   if (typeof optional !== "boolean") throw new TypeError("optional must be a boolean");
   return optional;
 }
-function retryOf(config) {
-  return config.retry === void 0 ? 1 : retryCount(config.retry, "retry");
+function refineOf(config) {
+  if (config.refine === void 0) return 1;
+  if (isJudge(config.refine)) return config.refine;
+  return refineCount(config.refine, "refine");
 }
-function retryForStage(config, receivesKickback) {
-  if ("reviewedBy" in config && config.reviewedBy) return retryOf(config);
-  if (receivesKickback) return retryOf(config);
-  if (config.retry !== void 0) {
-    throw new TypeError("retry must be on a reviewed stage or a kickback target");
+function refineForStage(config, receivesKickback) {
+  if ("reviewedBy" in config && config.reviewedBy) return refineOf(config);
+  if (receivesKickback) return refineOf(config);
+  if (config.refine !== void 0) {
+    throw new TypeError("refine must be on a reviewed stage or a kickback target");
   }
   return 0;
 }
@@ -2882,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)
       );
@@ -2893,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",
@@ -2901,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",
@@ -3006,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) => {
@@ -3035,6 +3073,84 @@ function unchangedNoteGuard(label, job, writes) {
     return outcome;
   };
 }
+function lineDiffCount(before, after) {
+  if (before === void 0) return after.split("\n").length;
+  const a = new Set(before.split("\n"));
+  const b = new Set(after.split("\n"));
+  let changed = 0;
+  for (const line of a) if (!b.has(line)) changed += 1;
+  for (const line of b) if (!a.has(line)) changed += 1;
+  return changed;
+}
+function judgedReview(brief, config, cfgJudge, panel) {
+  const useCase = /^Use case:\s*([\s\S]*?)\n\s*\n/m.exec(brief.brief)?.[1]?.replace(/\s+/g, " ").trim();
+  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) {
+      try {
+        draft = await readFile(join(ctx.workspace.dir, file), "utf8");
+        changedLines = lineDiffCount(previousDraft, draft);
+      } catch {
+      }
+      previousDraft = draft;
+    }
+    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"]
+    });
+    if (panelOutcome.status === "pass") return panelOutcome;
+    const findings = revisionFromOutcome(panelOutcome)?.findings ?? [];
+    if (hasBlockFinding(findings)) return panelOutcome;
+    const round2 = history.length + 1;
+    const state = saved ? saved.state : {
+      ...productFeedback.length ? { productFeedback } : {},
+      ...useCase !== void 0 ? { useCase } : {},
+      ...file !== void 0 ? { file } : {},
+      ...draft !== void 0 ? { draft } : {},
+      latestFindings: findings,
+      rounds: history,
+      round: round2,
+      cap: cfgJudge.cap
+    };
+    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,
+      counts: countBySeverity(findings),
+      ...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})` };
+  };
+}
 function stageJob(brief, named, roles, files, declaredFiles, targetFiles, familyTargetStageNames, familyTargetFamilies) {
   const config = named.config;
   if ("agent" in config && config.agent !== void 0) {
@@ -3042,9 +3158,33 @@ 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 retry = retryOf(config);
+    const refine = refineOf(config);
+    const cap = refineCap(refine);
+    const review = isJudge(refine) ? judgedReview(brief, config, refine, panel) : async (ctx) => panel({
+      ...ctx,
+      depth: ctx.depth + 1,
+      path: [...ctx.path, "review-panel"]
+    });
     const reviewLoop = loop({
       name: `${named.name}-review`,
       body: job,
@@ -3060,15 +3200,9 @@ function stageJob(brief, named, roles, files, declaredFiles, targetFiles, family
         }
         return true;
       }, `${named.name} writes`),
-      // Review events use a child path. The jobs' role tags, not their
-      // paths, separate the recorded sides. The outcome passes through.
-      review: async (ctx) => panel({
-        ...ctx,
-        depth: ctx.depth + 1,
-        path: [...ctx.path, "review-panel"]
-      }),
-      max: retry + 1,
-      maxReviewRestarts: retry,
+      review,
+      max: cap + 1,
+      maxReviewRestarts: cap,
       noProgress: { window: 2, gate: true }
     });
     return copyJobMeta(
@@ -3102,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 };
+    };
+  }
+  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 or input`);
+  throw new TypeError(`stage ${named.name} must declare agent, run, panel, input or fn`);
 }
 function workflowRecord(outcome) {
   return {
@@ -3129,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,
@@ -3183,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) {
@@ -3206,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}`, {
@@ -3267,7 +3410,7 @@ function workflow(name, config) {
     if (reviewedBy !== void 0 && stageConfig.sendsBackTo !== void 0) {
       throw new TypeError(`stage ${stageName} cannot use both reviewedBy and sendsBackTo`);
     }
-    retryForStage(stageConfig, incomingTargets.has(stageName));
+    refineForStage(stageConfig, incomingTargets.has(stageName));
     optionalFlag(stageConfig.optional);
     if (stageConfig.retrySafe !== void 0 && typeof stageConfig.retrySafe !== "boolean") {
       throw new TypeError("retrySafe must be a boolean");
@@ -3277,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);
@@ -3307,10 +3452,9 @@ function workflow(name, config) {
   for (const named of config.stages) {
     if (named.config.sendsBackTo !== void 0) {
       const target = config.stages.find((candidate) => candidate.name === named.config.sendsBackTo);
-      maxKickbacks[named.config.sendsBackTo] = Math.max(
-        maxKickbacks[named.config.sendsBackTo] ?? 0,
-        retryOf(target.config)
-      );
+      const refine = refineOf(target.config);
+      const existing = maxKickbacks[named.config.sendsBackTo];
+      maxKickbacks[named.config.sendsBackTo] = isJudge(refine) ? refine : Math.max(isJudge(existing) ? 0 : existing ?? 0, refine);
     }
   }
   const stageJobIdentity = resumeIdentity(workflowName, config);
@@ -9160,7 +9304,7 @@ function pipeline(name, stages, opts) {
   });
   return dag({ name, nodes, ...opts });
 }
-function slug3(s) {
+function slug2(s) {
   return s.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-+|-+$)/g, "") || "x";
 }
 function tournament(config) {
@@ -9193,7 +9337,7 @@ function tournament(config) {
       Array.from(
         { length: config.n },
         (_, i) => limit2(async () => {
-          const branch = `lines/${slug3(config.name)}-cand-${i}`;
+          const branch = `lines/${slug2(config.name)}-cand-${i}`;
           const wt = await addWorktree(base.dir, {
             branch,
             base: "HEAD",
@@ -9271,7 +9415,7 @@ function tournament(config) {
 }
 
 // src/core/isolated.ts
-var slug4 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "job";
+var slug3 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "job";
 var forkSeq = 0;
 function isolated(job, opts = {}) {
   const label = opts.label ?? "isolated";
@@ -9292,7 +9436,7 @@ function isolated(job, opts = {}) {
       );
       return job(parent);
     }
-    const branch = `lines/${slug4(label)}-${forkSeq += 1}`;
+    const branch = `lines/${slug3(label)}-${forkSeq += 1}`;
     const wt = await addWorktree(base.dir, {
       branch,
       base: "HEAD",
@@ -9326,7 +9470,7 @@ function isolated(job, opts = {}) {
           ...outcome.summary === void 0 ? {} : { summary: outcome.summary }
         }) : void 0;
         const sha = await commit(
-          message ?? { subject: `chore(${slug4(label)}): worktree changes` },
+          message ?? { subject: `chore(${slug3(label)}): worktree changes` },
           { cwd: wt.dir, signal: parent.signal }
         );
         const merged = await mergeLock(
@@ -9770,6 +9914,6 @@ function defineJob(job) {
   return job;
 }
 
-export { EXIT_PAUSED, RESUME_STAGE_OUTCOMES, assertGraph, briefFromFile, confidenceCondition, confidenceFromText, convergence, costReport, createAcceptedResultRecord, createCallbackClient, createGitWorktreeProvider, createGraphExecutor, createProofCache, createStoredCallbackClient, dag, dag2 as dagGraphType, defineAgentFromMarkdown, defineJob, directRouter, exitCodeFor, fallbackEngine, formatCostReport, formatEvent, formatPreflight, interruptRunPreflight, isolated, lastDecisionLine, lastGateBrief, loop, parallel, person, pipeline, preflight, preflightEngine, projectTeamRooms, ratchet, readRunPreflight, replayCallbackClient, resolveAcceptedResult, resolveApproval, run, sampled, sequence, stage, team, teamGraphType, tournament, workflow, writeProofArtifact, writeScope };
+export { EXIT_PAUSED, RESUME_STAGE_OUTCOMES, assertGraph, briefFromFile, confidenceCondition, confidenceFromText, convergence, costReport, createAcceptedResultRecord, createCallbackClient, createGitWorktreeProvider, createGraphExecutor, createProofCache, createStoredCallbackClient, dag, dag2 as dagGraphType, defineAgentFromMarkdown, defineJob, directRouter, exitCodeFor, fallbackEngine, formatCostReport, formatPreflight, interruptRunPreflight, isJudge, isolated, judge, lastDecisionLine, lastGateBrief, loop, parallel, person, pipeline, preflight, preflightEngine, projectTeamRooms, ratchet, readRunPreflight, replayCallbackClient, resolveAcceptedResult, resolveApproval, run, sampled, sequence, stage, stopQuestions, team, teamGraphType, tournament, workflow, writeProofArtifact, writeScope };
 //# sourceMappingURL=api.js.map
 //# sourceMappingURL=api.js.map