@loops-adk/core 0.1.0 → 0.2.0

package/dist/{chunk-3BPU34DE.js → chunk-WM5QVHM2.js}

@@ -1,11 +1,12 @@
 import { redactSecrets } from './chunk-JFTXJ7I2.js';
-import { isEngine } from './chunk-XC46B4FD.js';
+import { isEngine } from './chunk-MA6NDQMO.js';
 import { isLimitError, waitMsFor } from './chunk-Y2SD7GBL.js';
 import { LoopError } from './chunk-I3STY7U6.js';
-import { readFileSync, mkdtempSync, existsSync, writeFileSync, appendFileSync, mkdirSync, rmSync } from 'fs';
+import { readFileSync, mkdtempSync, existsSync, writeFileSync, appendFileSync, readdirSync, mkdirSync, rmSync } from 'fs';
 import { execa } from 'execa';
-import { tmpdir } from 'os';
+import { tmpdir, homedir } from 'os';
 import { join, dirname } from 'path';
+import { randomBytes } from 'crypto';
 
 // src/core/describe.ts
 var META = /* @__PURE__ */ new WeakMap();
@@ -34,6 +35,19 @@ function describeConditions(input) {
   return [condLabel(input)];
 }
 var count = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+function renderContract(value) {
+  const c = value;
+  if (!c || typeof c !== "object") return void 0;
+  const bits = [];
+  if (c.tier) bits.push(`tier ${c.tier}`);
+  if (c.outputs?.length) bits.push(`outputs ${c.outputs.join(", ")}`);
+  if (c.capabilities?.length) bits.push(`capabilities ${c.capabilities.join(", ")}`);
+  if (c.requiresSkills?.length) bits.push(`requires ${c.requiresSkills.join(", ")}`);
+  if (c.usesSkills?.length) bits.push(`uses ${c.usesSkills.join(", ")}`);
+  if (c.humanGates?.length) bits.push(`gates ${c.humanGates.join(", ")}`);
+  if (c.failureModes?.length) bits.push(`failure modes ${c.failureModes.join(", ")}`);
+  return bits.join("; ");
+}
 function renderPlan(meta, indent = "") {
   if (!meta) return [`${indent}(a runnable job, shape not introspectable)`];
   const nm = meta.name ? ` "${meta.name}"` : "";
@@ -68,6 +82,10 @@ function renderPlan(meta, indent = "") {
     }
     case "agent":
       out.push(`${indent}agent${nm}${meta.ground ? " (grounded)" : ""}`);
+      {
+        const contract = renderContract(meta.contract);
+        if (contract) out.push(`${indent}  contract: ${contract}`);
+      }
       break;
     case "fn":
       out.push(`${indent}fn${nm}`);
@@ -128,12 +146,59 @@ function defineSkill(skill) {
   if (!skill.instructions?.trim()) throw new Error(`defineSkill "${skill.name}": empty instructions`);
   return skill;
 }
+function skillRefName(ref) {
+  return typeof ref === "string" ? ref : ref.name;
+}
+function validateName(value, label) {
+  if (!value?.trim()) throw new Error(`${label}: \`name\` is required`);
+}
+function validateSkillRef(ref, label) {
+  if (typeof ref === "string") {
+    if (!ref.trim()) throw new Error(`${label}: empty skill name`);
+    return;
+  }
+  defineSkill(ref);
+}
 function defineAgent(def) {
   if (!def.name) throw new Error("defineAgent: `name` is required");
   if (!def.system?.trim()) throw new Error(`defineAgent "${def.name}": empty system prompt`);
   def.skills?.forEach((s) => defineSkill(s));
+  def.requiresSkills?.forEach(
+    (s) => validateSkillRef(s, `defineAgent "${def.name}" requiresSkills`)
+  );
+  def.usesSkills?.forEach(
+    (s) => validateSkillRef(s, `defineAgent "${def.name}" usesSkills`)
+  );
+  def.outputs?.forEach(
+    (o) => validateName(o.name, `defineAgent "${def.name}" outputs`)
+  );
+  def.humanGates?.forEach(
+    (g) => validateName(g.name, `defineAgent "${def.name}" humanGates`)
+  );
+  def.failureModes?.forEach((f) => {
+    if (!f.mode?.trim())
+      throw new Error(`defineAgent "${def.name}" failureModes: \`mode\` is required`);
+    if (!f.recovery?.trim())
+      throw new Error(`defineAgent "${def.name}" failureModes "${f.mode}": \`recovery\` is required`);
+  });
   return def;
 }
+function agentContract(agent) {
+  if (!agent) return void 0;
+  const summary = {};
+  if (agent.tier) summary.tier = agent.tier;
+  if (agent.capabilities?.length) summary.capabilities = [...agent.capabilities];
+  if (agent.outputs?.length) summary.outputs = agent.outputs.map((o) => o.name);
+  if (agent.requiresSkills?.length)
+    summary.requiresSkills = agent.requiresSkills.map(skillRefName);
+  if (agent.usesSkills?.length)
+    summary.usesSkills = agent.usesSkills.map(skillRefName);
+  if (agent.humanGates?.length)
+    summary.humanGates = agent.humanGates.map((g) => g.name);
+  if (agent.failureModes?.length)
+    summary.failureModes = agent.failureModes.map((f) => f.mode);
+  return Object.keys(summary).length ? summary : void 0;
+}
 function resolveSystem(agent) {
   if (!agent.skills?.length) return agent.system;
   const methods = agent.skills.map((s) => `### ${s.name}
@@ -927,6 +992,15 @@ function resetLedger(workspace) {
   reset(ledgerPath(workspace));
 }
 
+// src/core/text.ts
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+function truncate(s, max) {
+  return s.length > max ? `${s.slice(0, max).trimEnd()}
+\u2026` : s;
+}
+
 // src/core/consolidate.ts
 var CONSOLIDATE_SYSTEM = "You maintain a project's CONSOLIDATED LEDGER from its commit history \u2014 the bounded coarse memory a fresh context reads to continue safely. Capture the current state and the open threads, and PRESERVE every binding decision, convention and constraint with its exact values verbatim (downstream work must honour them, so dropping or generalising even one is a failure). Tight markdown; MERGE new commits into the prior ledger, deduplicate, omit only narrative \u2014 never omit a decision.";
 function digest(body, n = 280) {
@@ -965,11 +1039,6 @@ Output the updated consolidated ledger.`,
   return result.text.trim();
 }
 var COMPACT_SYSTEM = "You write the HANDOFF a future agent reads if it lost ALL memory of this work. Include EVERYTHING it needs to continue safely, as structured markdown: ## Why (the problem and the root cause), ## What (exactly what changed, and where \u2014 names, paths, signatures), ## Alternatives (what was ruled out and why), ## Constraints (the invariants and limits that shaped it), ## Next (what is left or to watch). Preserve every decision and specific value verbatim. Completeness matters more than brevity \u2014 drop only literal repetition and play-by-play narration, never a decision or a detail. Omit a section only if it truly has nothing. No preamble.";
-function truncate(s, n) {
-  const t = s.trim();
-  return t.length > n ? `${t.slice(0, n).trimEnd()}
-\u2026` : t;
-}
 async function compactLedger(ctx, text, opts = {}) {
   const trimmed = text.trim();
   if (!trimmed) return "";
@@ -1038,10 +1107,6 @@ function consolidateJob(config = {}) {
 }
 
 // src/core/ground.ts
-function truncate2(s, n) {
-  return s.length > n ? `${s.slice(0, n).trimEnd()}
-\u2026` : s;
-}
 async function groundingText(workspace, opts = {}) {
   const records = await log({
     cwd: workspace.dir,
@@ -1058,7 +1123,7 @@ What prior iterations already did and why \u2014 read it before working so you d
     const head = `### ${r.sha.slice(0, 7)}  ${r.subject}`;
     return r.body ? `${head}
 
-${truncate2(r.body, bodyChars)}` : head;
+${truncate(r.body, bodyChars)}` : head;
   });
   return `${header}
 
@@ -1114,12 +1179,305 @@ Commits a search judged relevant \u2014 read them before working.`;
     const head = `### ${r.sha.slice(0, 7)}  ${r.subject}`;
     return r.body ? `${head}
 
-${truncate2(r.body, bodyChars)}` : head;
+${truncate(r.body, bodyChars)}` : head;
   });
   return `${header}
 
 ${entries.join("\n\n")}`;
 }
+function normalizeFeedbackSeverity(severity) {
+  switch (severity) {
+    case "advisory":
+      return "nice-to-have";
+    case "blocking":
+    case void 0:
+      return "block";
+    default:
+      return severity;
+  }
+}
+function isRequiredFeedbackSeverity(severity) {
+  const normalized = normalizeFeedbackSeverity(severity);
+  return normalized === "block" || normalized === "should-fix";
+}
+function findingLine(finding) {
+  const reviewer = finding.reviewer ? `${finding.reviewer} ` : "";
+  const severity = normalizeFeedbackSeverity(finding.severity);
+  const decision = finding.decision ? ` Decision: ${finding.decision}.` : "";
+  const recommendation = finding.recommendation ? ` Recommendation: ${oneLine(finding.recommendation)}` : "";
+  return `- ${reviewer}[${severity}]: ${oneLine(finding.evidence)}${decision}${recommendation}`;
+}
+function defaultReason(findings) {
+  if (!findings?.length) return "Revision requested";
+  if (findings.length === 1) return oneLine(findings[0].evidence);
+  return `${findings.length} findings require another pass`;
+}
+function normalizeRevision(input) {
+  const reason = input.reason?.trim() || defaultReason(input.findings);
+  return {
+    reason,
+    target: input.target,
+    findings: input.findings,
+    rerun: input.rerun ?? (input.target ? "target-and-dependents" : void 0),
+    source: input.source,
+    decision: input.decision
+  };
+}
+function revisionRequest(input, over = {}) {
+  const revision = normalizeRevision(input);
+  return {
+    status: over.status ?? "fail",
+    confidence: over.confidence,
+    summary: over.summary ?? revision.reason,
+    data: over.data,
+    error: over.error,
+    revision
+  };
+}
+function kickback(to, reason, over = {}) {
+  return revisionRequest({ target: to, reason }, over);
+}
+function revisionFromOutcome(outcome) {
+  return outcome.revision;
+}
+function feedbackBlock(outcome) {
+  const revision = revisionFromOutcome(outcome);
+  const parts = [
+    "## Feedback to address",
+    "A review or downstream stage requested another pass. Address this before unrelated work."
+  ];
+  if (revision?.target) parts.push(`Target: ${revision.target}`);
+  if (revision?.source) parts.push(`Source: ${revision.source}`);
+  if (revision?.decision) parts.push(`Caller decision: ${revision.decision}`);
+  const reason = revision?.reason ?? outcome.summary;
+  if (reason) parts.push(`Reason: ${reason}`);
+  const findings = revision?.findings ?? [];
+  if (findings.length) {
+    parts.push("Findings:");
+    parts.push(findings.map(findingLine).join("\n"));
+  }
+  return parts.join("\n\n");
+}
+function graphPositionBlock(graph) {
+  return [
+    "## Graph position",
+    `DAG: ${graph.dag}`,
+    `Current node: ${graph.node}`,
+    `Path: ${graph.path.join(" > ")}`,
+    `Depends on: ${graph.needs.length ? graph.needs.join(", ") : "none"}`,
+    `Direct dependents: ${graph.dependents.length ? graph.dependents.join(", ") : "none"}`
+  ].join("\n");
+}
+async function runReviewer(reviewer, index, ctx) {
+  const name = reviewer.name ?? `reviewer-${index + 1}`;
+  try {
+    if ("job" in reviewer) {
+      const outcome = await reviewer.job(ctx);
+      return {
+        name,
+        met: outcome.status === "pass",
+        confidence: outcome.confidence,
+        reason: outcome.summary ?? outcome.status
+      };
+    }
+    const result = await toCondition(reviewer.review)(
+      ctx,
+      ctx.lastOutcome
+    );
+    return {
+      name,
+      met: result.met,
+      confidence: result.confidence,
+      reason: result.reason
+    };
+  } catch (e) {
+    if (ctx.signal.aborted) throw e;
+    return {
+      name,
+      met: false,
+      reason: `reviewer errored: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+function reviewFinding(result) {
+  return {
+    reviewer: result.name,
+    severity: "block",
+    evidence: result.reason
+  };
+}
+function findingSeverityCounts(findings) {
+  const counts = {};
+  for (const finding of findings) {
+    const severity = normalizeFeedbackSeverity(finding.severity);
+    counts[severity] = (counts[severity] ?? 0) + 1;
+  }
+  return counts;
+}
+function reviewPanel(config) {
+  const label = config.label ?? "review-panel";
+  if (!config.reviewers.length)
+    throw new LoopError({
+      code: "CONFIG",
+      message: `reviewPanel "${label}": at least one reviewer is required`
+    });
+  const job = async (ctx) => {
+    ctx.emit({ kind: "job:start", ts: Date.now(), path: [...ctx.path], label });
+    const results = await Promise.all(
+      config.reviewers.map((reviewer, i) => runReviewer(reviewer, i, ctx))
+    );
+    const passedCount = results.filter((r) => r.met).length;
+    const required = config.pass === void 0 || config.pass === "all" ? results.length : config.pass;
+    const findings = results.filter((r) => !r.met).map(reviewFinding);
+    const passed = passedCount >= required;
+    const summaryHead = `Review panel: ${passedCount}/${results.length} reviewer(s) cleared`;
+    const summary = findings.length ? `${summaryHead}.
+${findings.map(findingLine).join("\n")}` : `${summaryHead}.`;
+    const scored = results.map((r) => r.confidence).filter((c) => c != null);
+    const confidence = scored.length ? scored.reduce((sum, c) => sum + c, 0) / scored.length : void 0;
+    const data = {
+      findings,
+      results,
+      passed: passedCount,
+      required,
+      severityCounts: findingSeverityCounts(findings)
+    };
+    const outcome = passed ? { status: "pass", summary, confidence, data } : revisionRequest(
+      {
+        target: config.target,
+        // A clean one-line reason. The findings ride the `findings` array, so
+        // feedbackBlock renders them once (not embedded in the reason too) and
+        // the records/tail `reason` stays a single tidy line. The full
+        // multi-line `summary` is kept on the outcome below for logs/TUI.
+        reason: `${summaryHead}.`,
+        findings,
+        rerun: config.rerun
+      },
+      { summary, confidence, data }
+    );
+    ctx.emit({ kind: "job:end", ts: Date.now(), path: [...ctx.path], label, outcome });
+    return outcome;
+  };
+  return setMeta(job, { kind: "reviewPanel", name: label });
+}
+async function gitOutput(cwd, args, signal) {
+  const out = await execa("git", args, {
+    cwd,
+    reject: false,
+    stripFinalNewline: false,
+    cancelSignal: signal
+  });
+  return out.stdout.trim();
+}
+async function resolveFiles(ctx, patterns) {
+  const fromGit = await gitOutput(
+    ctx.workspace.dir,
+    ["ls-files", "--", ...patterns],
+    ctx.signal
+  ).catch(() => "");
+  const files = fromGit ? fromGit.split("\n").filter(Boolean) : [];
+  if (files.length) return files;
+  return patterns.filter((p) => existsSync(join(ctx.workspace.dir, p)));
+}
+function reviewContext(config) {
+  return async (ctx, last) => {
+    const max = config.maxChars ?? 6e3;
+    const buildTests = async () => {
+      if (!config.tests) return [];
+      if (config.tests === true) {
+        const lines = [];
+        if (last?.status) lines.push(`Last outcome status: ${last.status}`);
+        if (last?.summary) lines.push(`Last outcome summary: ${last.summary}`);
+        if (last?.data !== void 0) {
+          let rendered;
+          try {
+            rendered = JSON.stringify(last.data, null, 2);
+          } catch {
+            rendered = String(last.data);
+          }
+          lines.push(`Last outcome data: ${rendered}`);
+        }
+        return lines.length ? [`## Test and outcome context
+
+${lines.join("\n")}`] : [];
+      }
+      const cwd = config.tests.cwd ?? ctx.workspace.dir;
+      const result = await execa(
+        config.tests.command,
+        config.tests.args ?? [],
+        { cwd, reject: false, stripFinalNewline: false, cancelSignal: ctx.signal }
+      ).catch((e) => {
+        if (ctx.signal.aborted) throw e;
+        return {
+          exitCode: void 0,
+          stdout: "",
+          stderr: e instanceof Error ? e.message : String(e)
+        };
+      });
+      const exit = result.exitCode ?? "(command did not run)";
+      return [
+        `## Test command
+
+${config.tests.command} ${(config.tests.args ?? []).join(" ")}
+
+exit: ${exit}
+
+stdout:
+${truncate(result.stdout ?? "", max)}
+
+stderr:
+${truncate(result.stderr ?? "", max)}`
+      ];
+    };
+    const buildDiff = async () => {
+      if (!config.diff) return [];
+      const diff2 = await gitOutput(
+        ctx.workspace.dir,
+        ["diff", "HEAD", "--"],
+        ctx.signal
+      ).catch(() => "");
+      return diff2 ? [`## Git diff
+
+${truncate(diff2, max)}`] : [];
+    };
+    const buildFiles = async () => {
+      if (!config.files?.length) return [];
+      const files2 = await resolveFiles(ctx, config.files);
+      const out = [];
+      for (const file of files2) {
+        const path = join(ctx.workspace.dir, file);
+        if (!existsSync(path)) continue;
+        out.push(`## File: ${file}
+
+${truncate(readFileSync(path, "utf8"), max)}`);
+      }
+      return out;
+    };
+    const buildLedger = async () => {
+      if (!config.ledger) return [];
+      const out = [];
+      const live = [readPrompt(ctx.workspace), readLedger(ctx.workspace)].filter(Boolean).join("\n\n");
+      if (live) out.push(`## Live ledger
+
+${truncate(live, max)}`);
+      const committed = await groundingText(ctx.workspace, {
+        max: 5,
+        bodyChars: 1200,
+        signal: ctx.signal
+      }).catch(() => "");
+      if (committed) out.push(truncate(committed, max));
+      return out;
+    };
+    const [tests, diff, files, ledger] = await Promise.all([
+      buildTests(),
+      buildDiff(),
+      buildFiles(),
+      buildLedger()
+    ]);
+    const sections = [...tests, ...diff, ...files, ...ledger];
+    return sections.join("\n\n---\n\n") || "(no review context)";
+  };
+}
 
 // src/core/job.ts
 var HANDOFF_MARK = "===HANDOFF===";
@@ -1197,6 +1555,16 @@ var TERMINAL = (text) => ({
   summary: text.trim().slice(0, 280),
   data: text
 });
+function withOperationalContext(ctx, userPrompt, config) {
+  const parts = [userPrompt];
+  if (config.consumeFeedback && ctx.lastReview) {
+    parts.push(feedbackBlock(ctx.lastReview));
+  }
+  if (config.graphContext && ctx.graph) {
+    parts.push(graphPositionBlock(ctx.graph));
+  }
+  return parts.join("\n\n---\n\n");
+}
 function agentJob(config) {
   const job = async (ctx) => {
     const path = [...ctx.path];
@@ -1204,7 +1572,8 @@ function agentJob(config) {
     ctx.emit({ kind: "job:start", ts: Date.now(), path, label });
     const engine = ctx.resolveEngine(config.engine);
     const userPrompt = typeof config.prompt === "function" ? await config.prompt(ctx) : config.prompt;
-    const prompt = config.ground ? await withGrounding(ctx, userPrompt, config.ground) : userPrompt;
+    const contextualPrompt = withOperationalContext(ctx, userPrompt, config);
+    const prompt = config.ground ? await withGrounding(ctx, contextualPrompt, config.ground) : contextualPrompt;
     const system = config.system !== void 0 ? typeof config.system === "function" ? config.system(ctx) : config.system : config.agent ? resolveSystem(config.agent) : void 0;
     let result;
     const toolUses = /* @__PURE__ */ new Map();
@@ -1305,7 +1674,8 @@ function agentJob(config) {
   return setMeta(job, {
     kind: "agent",
     name: config.label ?? config.agent?.name ?? "agent",
-    ground: !!config.ground
+    ground: !!config.ground,
+    contract: agentContract(config.agent)
   });
 }
 function composeWay(ctx, last) {
@@ -1381,14 +1751,6 @@ function commitJob(config) {
     }
   };
 }
-function kickback(to, reason, over) {
-  return {
-    status: "fail",
-    summary: reason,
-    ...over,
-    kickback: { to, reason }
-  };
-}
 function fnJob(label, fn) {
   const job = async (ctx) => {
     const path = [...ctx.path];
@@ -1438,6 +1800,7 @@ function childContext(parent, over) {
     log: parent.log,
     depth: over.depth,
     path: over.path,
+    graph: over.graph ?? parent.graph,
     // Inherit the enclosing iteration by default. A `loop` always passes one
     // explicitly; a `dag`/`sequence` does not, so without this a node nested in a
     // loop would reset to 0 — the "Attempt 0" confound where a retry body could not
@@ -1745,13 +2108,18 @@ function loop(config) {
               iteration
             });
           }
+          const reviewPassed = reviewOutcome.status === "pass";
+          const restartsExhausted = config.maxReviewRestarts != null && consecutiveReviewFails + 1 >= config.maxReviewRestarts;
+          const iterationsRemain = config.max == null || iteration < config.max;
+          const willReenter = !reviewPassed && !restartsExhausted && iterationsRemain;
           parent.emit({
             kind: "loop:review",
             ts: ts(),
             path,
-            outcome: reviewOutcome
+            outcome: reviewOutcome,
+            accepted: willReenter
           });
-          if (reviewOutcome.status === "pass") {
+          if (reviewPassed) {
             await recordMilestone(ctxAt(iteration, last));
             return finish(
               {
@@ -1769,7 +2137,7 @@ function loop(config) {
             `review did not pass (${reviewOutcome.summary ?? reviewOutcome.status}); re-entering ${config.name}`,
             "warn"
           );
-          if (config.maxReviewRestarts != null && consecutiveReviewFails >= config.maxReviewRestarts) {
+          if (restartsExhausted) {
             return finish(
               {
                 status: "exhausted",
@@ -1865,14 +2233,14 @@ var EngineRegistry = class {
     this.register(
       "agent-sdk",
       (o) => lazy(
-        () => import('./agent-sdk-RF5VJZAT.js').then((m) => new m.AgentSdkEngine(o)),
+        () => import('./agent-sdk-4QJDWM7N.js').then((m) => new m.AgentSdkEngine(o)),
         "agent-sdk"
       )
     );
     this.register(
       "claude-cli",
       (o) => lazy(
-        () => import('./claude-cli-U7WEVAOL.js').then((m) => new m.ClaudeCliEngine(o)),
+        () => import('./claude-cli-75AOQUKG.js').then((m) => new m.ClaudeCliEngine(o)),
         "claude-cli"
       )
     );
@@ -1885,7 +2253,7 @@ var EngineRegistry = class {
     );
     this.register(
       "codex",
-      (o) => lazy(() => import('./codex-6I5UZ2HM.js').then((m) => new m.CodexEngine(o)), "codex")
+      (o) => lazy(() => import('./codex-LYZF52WL.js').then((m) => new m.CodexEngine(o)), "codex")
     );
   }
 };
@@ -1971,25 +2339,383 @@ var Stats = class {
     return m;
   }
 };
+function ensureDir2(path) {
+  const dir = dirname(path);
+  if (dir && dir !== ".") mkdirSync(dir, { recursive: true });
+}
+function outcomeSummary(outcome) {
+  return {
+    status: outcome.status,
+    summary: outcome.summary,
+    confidence: outcome.confidence
+  };
+}
+function strongestFinding(findings) {
+  if (!findings?.length) return void 0;
+  const severities = findings.map((f) => normalizeFeedbackSeverity(f.severity));
+  if (severities.includes("block")) return "block";
+  if (severities.includes("should-fix")) return "should-fix";
+  if (severities.includes("nice-to-have")) return "nice-to-have";
+  if (severities.includes("approve")) return "approve";
+  return void 0;
+}
+function emittedRevisionRecord(event, outcome) {
+  const revision = revisionFromOutcome(outcome);
+  return revision ? [
+    {
+      kind: "revision-emitted",
+      ts: event.ts,
+      path: event.path,
+      sourceEvent: "job:end",
+      revision
+    }
+  ] : [];
+}
+function semanticRecordsFromEvent(event) {
+  switch (event.kind) {
+    case "job:start":
+      return [
+        {
+          kind: "dispatch",
+          ts: event.ts,
+          path: event.path,
+          unit: "job",
+          label: event.label
+        }
+      ];
+    case "dag:node":
+      if (event.phase === "start")
+        return [
+          {
+            kind: "dispatch",
+            ts: event.ts,
+            path: [...event.path, event.node],
+            unit: "dag-node",
+            node: event.node,
+            attempt: event.attempt
+          }
+        ];
+      return event.outcome ? [
+        {
+          kind: "completion",
+          ts: event.ts,
+          path: [...event.path, event.node],
+          unit: "dag-node",
+          label: event.node,
+          outcome: outcomeSummary(event.outcome),
+          attempt: event.attempt
+        }
+      ] : [];
+    case "job:end":
+      return [
+        {
+          kind: "completion",
+          ts: event.ts,
+          path: event.path,
+          unit: "job",
+          label: event.label,
+          outcome: outcomeSummary(event.outcome)
+        },
+        ...emittedRevisionRecord(event, event.outcome)
+      ];
+    case "loop:review": {
+      if (event.outcome.status === "pass") return [];
+      const revision = revisionFromOutcome(event.outcome);
+      const decision = event.accepted === false ? "rejected" : "accepted";
+      const records = [
+        {
+          kind: "surfacing",
+          ts: event.ts,
+          path: event.path,
+          source: "loop-review",
+          decision,
+          severity: strongestFinding(revision?.findings),
+          reason: revision?.reason ?? event.outcome.summary ?? event.outcome.status
+        }
+      ];
+      if (revision) {
+        records.push({
+          kind: "revision-routed",
+          ts: event.ts,
+          path: event.path,
+          sourceEvent: "loop:review",
+          decision,
+          revision
+        });
+      }
+      return records;
+    }
+    case "loop:end":
+      return [
+        {
+          kind: "completion",
+          ts: event.ts,
+          path: event.path,
+          unit: "loop",
+          outcome: outcomeSummary(event.outcome),
+          iterations: event.iterations
+        }
+      ];
+    case "dag:kickback": {
+      const at = [...event.path, event.to];
+      const decision = event.accepted ? "accepted" : "rejected";
+      return [
+        {
+          kind: "surfacing",
+          ts: event.ts,
+          path: at,
+          source: "dag-kickback",
+          decision,
+          severity: "block",
+          from: event.from,
+          to: event.to,
+          reason: event.reason,
+          note: event.note
+        },
+        {
+          kind: "revision-routed",
+          ts: event.ts,
+          path: at,
+          sourceEvent: "dag:kickback",
+          decision,
+          revision: {
+            target: event.to,
+            reason: event.reason,
+            source: event.from,
+            rerun: event.accepted ? "target-and-dependents" : void 0
+          }
+        }
+      ];
+    }
+    case "dag:end":
+      return [
+        {
+          kind: "completion",
+          ts: event.ts,
+          path: event.path,
+          unit: "dag",
+          outcome: outcomeSummary(event.outcome)
+        }
+      ];
+    default:
+      return [];
+  }
+}
+function makeSemanticRecorder(path) {
+  try {
+    ensureDir2(path);
+    writeFileSync(path, "");
+  } catch {
+    return () => {
+    };
+  }
+  return (event) => {
+    const records = semanticRecordsFromEvent(event);
+    if (!records.length) return;
+    try {
+      for (const record of records) {
+        appendFileSync(path, `${JSON.stringify(record)}
+`);
+      }
+    } catch {
+    }
+  };
+}
 var NOISE = /* @__PURE__ */ new Set([
   "engine:text",
   "engine:thinking"
 ]);
+function runsHome() {
+  const base = process.env.LOOPS_HOME ?? join(homedir(), ".loops");
+  return join(base, "runs");
+}
+function slug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "run";
+}
+function newRunId(title) {
+  return `${slug(title)}-${randomBytes(3).toString("hex")}`;
+}
+function startSupervisor(input) {
+  const dir = join(runsHome(), input.runId);
+  mkdirSync(dir, { recursive: true });
+  const eventsPath = join(dir, "events.jsonl");
+  const semanticPath = join(dir, "semantic.jsonl");
+  const statusPath = join(dir, "status.json");
+  try {
+    writeFileSync(eventsPath, "");
+  } catch {
+  }
+  const semanticSink = makeSemanticRecorder(semanticPath);
+  const status = {
+    runId: input.runId,
+    pid: process.pid,
+    cwd: input.cwd,
+    title: input.title,
+    startedAt: Date.now(),
+    updatedAt: Date.now(),
+    status: "running",
+    shape: input.shape,
+    live: {
+      path: [],
+      iteration: 0,
+      usage: { inputTokens: 0, outputTokens: 0, calls: 0 }
+    }
+  };
+  const writeStatus = () => {
+    status.updatedAt = Date.now();
+    try {
+      writeFileSync(statusPath, JSON.stringify(status, null, 2));
+    } catch {
+    }
+  };
+  writeStatus();
+  const sink = (event) => {
+    if (!NOISE.has(event.kind)) {
+      try {
+        appendFileSync(eventsPath, `${JSON.stringify(event)}
+`);
+      } catch {
+      }
+      semanticSink(event);
+    }
+    switch (event.kind) {
+      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 "dag:node":
+        status.live.path = [...event.path, event.node];
+        break;
+      case "loop:end":
+      case "dag:end":
+      case "job:end":
+        status.live.lastOutcome = {
+          status: event.outcome.status,
+          summary: event.outcome.summary
+        };
+        status.live.path = event.path;
+        break;
+      case "engine:usage":
+        status.live.usage.inputTokens += event.usage.inputTokens;
+        status.live.usage.outputTokens += event.usage.outputTokens;
+        status.live.usage.calls += 1;
+        break;
+    }
+    if (!NOISE.has(event.kind)) writeStatus();
+  };
+  const finish = (outcome) => {
+    status.status = outcome.status;
+    status.endedAt = Date.now();
+    status.live.lastOutcome = {
+      status: outcome.status,
+      summary: outcome.summary
+    };
+    writeStatus();
+  };
+  return { runId: input.runId, dir, sink, finish };
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+function readRunStatus(runId) {
+  try {
+    const raw = readFileSync(join(runsHome(), runId, "status.json"), "utf8");
+    const s = JSON.parse(raw);
+    s.alive = s.status === "running" ? isAlive(s.pid) : false;
+    return s;
+  } catch {
+    return void 0;
+  }
+}
+function listRuns() {
+  const base = runsHome();
+  if (!existsSync(base)) return [];
+  const out = [];
+  for (const id of readdirSync(base)) {
+    const s = readRunStatus(id);
+    if (s) out.push(s);
+  }
+  return out.sort((a, b) => b.startedAt - a.startedAt);
+}
+function runEventsPath(runId) {
+  return join(runsHome(), runId, "events.jsonl");
+}
+function runSemanticRecordsPath(runId) {
+  return join(runsHome(), runId, "semantic.jsonl");
+}
+function formatEvent(event) {
+  const at = event.path.length ? `${event.path.join(" \u203A ")} ` : "";
+  switch (event.kind) {
+    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 "loop:review":
+      return `${at}\xB7 review: ${event.outcome.status}`;
+    case "loop:end":
+      return `${at}\u25C2 ${event.outcome.status} (${event.iterations} iter)`;
+    case "dag:node":
+      return `${at}\xB7 node ${event.node}: ${event.phase}${event.outcome ? ` (${event.outcome.status})` : ""}`;
+    case "dag:kickback":
+      return `${at}\u21A9 kickback ${event.accepted ? "accepted" : "rejected"} ${event.from} -> ${event.to}: ${event.reason}${event.note ? ` (${event.note})` : ""}`;
+    case "dag:end":
+      return `${at}\u25C2 dag ${event.outcome.status}`;
+    case "job:start":
+      return `${at}\u2022 ${event.label}`;
+    case "job:end":
+      return `${at}\u2022 ${event.label}: ${event.outcome.status}`;
+    case "engine:tool":
+      return `${at}  tool ${event.name} ${event.phase}`;
+    case "engine:usage":
+      return `${at}  ${event.model}: ${event.usage.inputTokens}/${event.usage.outputTokens} tok`;
+    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}`;
+  }
+}
+var NOISE2 = /* @__PURE__ */ new Set([
+  "engine:text",
+  "engine:thinking"
+]);
 var CHECKPOINT_AT = /* @__PURE__ */ new Set([
   "loop:iteration",
   "loop:end",
   "dag:end",
   "job:end"
 ]);
-function ensureDir2(path) {
+function ensureDir3(path) {
   const dir = dirname(path);
   if (dir && dir !== ".") mkdirSync(dir, { recursive: true });
 }
 function makeRecorder(path) {
-  ensureDir2(path);
+  ensureDir3(path);
   writeFileSync(path, "");
   return (event) => {
-    if (NOISE.has(event.kind)) return;
+    if (NOISE2.has(event.kind)) return;
     try {
       appendFileSync(path, `${JSON.stringify(event)}
 `);
@@ -1998,14 +2724,14 @@ function makeRecorder(path) {
   };
 }
 function makeCheckpointer(path, state) {
-  ensureDir2(path);
+  ensureDir3(path);
   return (event) => {
     if (!CHECKPOINT_AT.has(event.kind)) return;
     flushCheckpoint(path, state);
   };
 }
 function flushCheckpoint(path, state) {
-  ensureDir2(path);
+  ensureDir3(path);
   try {
     writeFileSync(path, JSON.stringify({ ts: Date.now(), state }, null, 2));
   } catch {
@@ -2051,10 +2777,23 @@ async function run(job, options = {}) {
       });
     }
   }
+  const dir = options.cwd ?? process.cwd();
   const sinks = [];
   if (options.recordTo) sinks.push(makeRecorder(options.recordTo));
   if (options.checkpoint)
     sinks.push(makeCheckpointer(options.checkpoint, initialState));
+  let supervisor;
+  if (options.supervise) {
+    const shape = jobMeta(job);
+    const title = shape?.name ?? "run";
+    supervisor = startSupervisor({
+      runId: newRunId(title),
+      cwd: dir,
+      title,
+      shape
+    });
+    sinks.push(supervisor.sink);
+  }
   const emit = (event) => {
     stats.record(event);
     if (budget && event.kind === "engine:usage")
@@ -2063,7 +2802,6 @@ async function run(job, options = {}) {
     for (const sink of sinks) sink(event);
   };
   const resolveEngine = (ref) => registry.create(ref, defaultEngine);
-  const dir = options.cwd ?? process.cwd();
   const workspace = {
     dir,
     branch: await currentBranch({ cwd: dir, signal: controller.signal })
@@ -2081,18 +2819,21 @@ async function run(job, options = {}) {
         message: `environment "${options.environment.name}" failed to start: ${error.message}`,
         code: error.code
       });
+      const failOutcome = {
+        status: "fail",
+        summary: `environment failed to start: ${error.message}`,
+        error
+      };
+      supervisor?.finish(failOutcome);
       return {
-        outcome: {
-          status: "fail",
-          summary: `environment failed to start: ${error.message}`,
-          error
-        },
+        outcome: failOutcome,
         stats: stats.snapshot(),
         budget: budget ? {
           limit: budget.limit,
           spent: budget.spent(),
           remaining: budget.remaining()
-        } : void 0
+        } : void 0,
+        runId: supervisor?.runId
       };
     }
   }
@@ -2133,6 +2874,7 @@ async function run(job, options = {}) {
   }
   if (outcome.status === "paused" && options.checkpoint)
     flushCheckpoint(options.checkpoint, initialState);
+  supervisor?.finish(outcome);
   return {
     outcome,
     stats: stats.snapshot(),
@@ -2140,7 +2882,8 @@ async function run(job, options = {}) {
       limit: budget.limit,
       spent: budget.spent(),
       remaining: budget.remaining()
-    } : void 0
+    } : void 0,
+    runId: supervisor?.runId
   };
 }
 function exitCodeFor(outcome) {
@@ -2158,6 +2901,6 @@ function exitCodeFor(outcome) {
   }
 }
 
-export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, childContext, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, fnJob, forgeChecks, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, setMeta, stageAll, toCondition };
-//# sourceMappingURL=chunk-3BPU34DE.js.map
-//# sourceMappingURL=chunk-3BPU34DE.js.map
+export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, Stats, addWorktree, agentCheck, agentContract, agentJob, all, always, any, appendLedger, appendPrompt, bodyPassed, buildChecksArgs, buildCreateArgs, buildEditArgs, buildMergeArgs, buildViewArgs, childContext, commandSucceeds, commit, commitJob, compactLedger, composeCommitBody, conflictedFiles, consolidate, consolidateJob, currentBranch, defineAgent, defineSkill, deleteBranch, describeConditions, ensureIgnored, exitCodeFor, feedbackBlock, fnJob, forgeChecks, formatEvent, fromFile, gateJob, graphPositionBlock, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, isRequiredFeedbackSeverity, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, normalizeFeedbackSeverity, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, setMeta, stageAll, toCondition };
+//# sourceMappingURL=chunk-WM5QVHM2.js.map
+//# sourceMappingURL=chunk-WM5QVHM2.js.map