@obversa/runtime 0.1.0 → 0.2.0

package/dist/api.js

@@ -1,14 +1,16 @@
 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, 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 { 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';
@@ -17,9 +19,9 @@ import { join, resolve, basename, extname, dirname, isAbsolute, relative, sep }
 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,111 @@ 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: "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."
+      }
+    }
+  };
+}
+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() };
+}
+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 !== "unknown" && reason !== "continue") {
+    return { again: false, reason: `the judge chose ${reason}` };
+  }
+  if (typeof holds === "number" && holds >= 0.5) {
+    return { again: false, 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)})` };
+  }
+  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: 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 };
+}
+
 // src/core/dag.ts
 function slug(s) {
   return s.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-+|-+$)/g, "") || "node";
@@ -158,10 +265,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 +328,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 judgeHistory = /* @__PURE__ */ new Map();
   const dependents = new Map(names.map((n) => [n, []]));
   for (const [dep, name] of edges) dependents.get(dep).push(name);
   const ancestorsOf = (name) => {
@@ -533,6 +651,30 @@ 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 = {
+            latestFindings: requestFindings,
+            rounds: history,
+            round: count,
+            cap: cfgJudge.cap
+          };
+          const { decision } = await askJudge(cfgJudge, state, parent, path);
+          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);
+            continue;
+          }
+          effectiveReason = `${reason} (${decision.reason})`;
+        }
         if (perTargetBudget ? count > limit3 : used >= limit3) {
           emitKickback(
             from,
@@ -550,7 +692,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 +701,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));
@@ -1613,259 +1755,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 +2051,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 +2245,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 +2279,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();
@@ -2733,24 +2628,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;
 }
@@ -3035,6 +2935,62 @@ 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;
+  return async (ctx) => {
+    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;
+    }
+    const panelOutcome = 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 = {
+      ...useCase !== void 0 ? { useCase } : {},
+      ...file !== void 0 ? { file } : {},
+      ...draft !== void 0 ? { draft } : {},
+      latestFindings: findings,
+      rounds: history,
+      round: round2,
+      cap: cfgJudge.cap
+    };
+    const { decision } = await askJudge(cfgJudge, state, ctx, ctx.path);
+    history.push({
+      round: round2,
+      findings,
+      counts: countBySeverity(findings),
+      ...changedLines !== void 0 ? { changedLines } : {}
+    });
+    if (!decision.again) {
+      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) {
@@ -3044,7 +3000,13 @@ function stageJob(brief, named, roles, files, declaredFiles, targetFiles, family
     if (config.reviewedBy === void 0) return job;
     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 +3022,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(
@@ -3267,7 +3223,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");
@@ -3307,10 +3263,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 +9115,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 +9148,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 +9226,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 +9247,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 +9281,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 +9725,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