@loops-adk/core 0.1.1 → 0.3.0

package/dist/{chunk-6BDWTFOS.js → chunk-3PMVII43.js}

@@ -1,12 +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, readdirSync, mkdirSync, rmSync } from 'fs';
 import { execa } from 'execa';
+import { createHash, randomBytes } from 'crypto';
 import { tmpdir, homedir } from 'os';
 import { join, dirname } from 'path';
-import { randomBytes } from 'crypto';
 
 // src/core/describe.ts
 var META = /* @__PURE__ */ new WeakMap();
@@ -35,13 +35,30 @@ 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}"` : "";
   const out = [];
   switch (meta.kind) {
     case "loop": {
-      const max = typeof meta.max === "number" ? ` (max ${meta.max})` : "";
+      const caps = [];
+      if (typeof meta.max === "number") caps.push(`max ${meta.max}`);
+      if (typeof meta.noProgress === "number")
+        caps.push(`stall after ${meta.noProgress} flat`);
+      const max = caps.length ? ` (${caps.join("; ")})` : "";
       out.push(`${indent}loop${nm}${max}`);
       const start = meta.start;
       const gate = meta.gate;
@@ -69,6 +86,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}`);
@@ -129,12 +150,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}
@@ -748,6 +816,32 @@ async function isDirty(opts) {
   const r = await git(["status", "--porcelain"], opts);
   return r.stdout.trim().length > 0;
 }
+async function workspaceFingerprint(opts) {
+  try {
+    if (!await isRepo(opts)) return void 0;
+    const hash = createHash("sha256");
+    const feed = (label, value) => {
+      hash.update(label);
+      hash.update("");
+      hash.update(value);
+      hash.update("");
+    };
+    feed("head", await headSha(opts) ?? "");
+    feed("status", (await git(["status", "--porcelain"], opts)).stdout);
+    feed("unstaged", (await git(["diff"], opts)).stdout);
+    feed("staged", (await git(["diff", "--cached"], opts)).stdout);
+    const untracked = (await git(["ls-files", "--others", "--exclude-standard"], opts)).stdout.split("\n").filter(Boolean);
+    for (let i = 0; i < untracked.length; i += 500) {
+      const chunk = untracked.slice(i, i + 500);
+      feed(`untracked-paths:${i}`, chunk.join("\n"));
+      const r = await git(["hash-object", "--", ...chunk], opts);
+      if (r.exitCode === 0) feed(`untracked-content:${i}`, r.stdout);
+    }
+    return hash.digest("hex");
+  } catch {
+    return void 0;
+  }
+}
 async function commit(input, opts) {
   if (!input.allowEmpty && !await hasStagedChanges(opts)) return void 0;
   const message = input.body ? `${input.subject}
@@ -928,6 +1022,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) {
@@ -966,11 +1069,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 "";
@@ -1039,10 +1137,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,
@@ -1059,7 +1153,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}
 
@@ -1115,12 +1209,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===";
@@ -1198,6 +1585,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];
@@ -1205,7 +1602,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();
@@ -1306,7 +1704,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) {
@@ -1382,14 +1781,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];
@@ -1419,6 +1810,102 @@ function fnJob(label, fn) {
   return setMeta(job, { kind: "fn", name: label });
 }
 
+// src/core/progress.ts
+function resolveNoProgress(input) {
+  if (input == null) return void 0;
+  const cfg = typeof input === "number" ? { window: input } : input;
+  return {
+    ...cfg,
+    window: cfg.window ?? 3,
+    minConfidenceDelta: cfg.minConfidenceDelta ?? 0.02
+  };
+}
+var ProgressTracker = class {
+  window;
+  minConfidenceDelta;
+  /** Every state this run has reached, namespaced by channel. */
+  seen = /* @__PURE__ */ new Set();
+  /** Confidence high-water mark — the best score at the last progress point. */
+  best;
+  /** The current run of consecutive no-progress iterations. */
+  stalledRun = [];
+  lastEvidence = [];
+  lastReason = "gate not met";
+  indeterminate = 0;
+  sampled = 0;
+  constructor(cfg) {
+    this.window = cfg.window;
+    this.minConfidenceDelta = cfg.minConfidenceDelta;
+  }
+  /**
+   * Record one iteration. Returns a `StallReport` when this sample fills the
+   * window, else undefined.
+   */
+  record(sample) {
+    this.sampled += 1;
+    if (sample.reason) this.lastReason = sample.reason;
+    const flat = [];
+    let progressed = false;
+    let channels = 0;
+    if (sample.fingerprint !== void 0) {
+      channels += 1;
+      const key = `fp:${sample.fingerprint}`;
+      if (this.seen.has(key)) {
+        flat.push("workspace: no state this run has not already visited");
+      } else {
+        this.seen.add(key);
+        progressed = true;
+      }
+    }
+    if (sample.signal !== void 0) {
+      channels += 1;
+      const key = `sig:${sample.signal}`;
+      if (this.seen.has(key)) {
+        flat.push(`signal: "${sample.signal}" already seen this run`);
+      } else {
+        this.seen.add(key);
+        progressed = true;
+      }
+    }
+    if (sample.confidence !== void 0) {
+      channels += 1;
+      if (this.best === void 0 || sample.confidence >= this.best + this.minConfidenceDelta) {
+        this.best = Math.max(this.best ?? -Infinity, sample.confidence);
+        progressed = true;
+      } else {
+        flat.push(
+          `confidence ${sample.confidence.toFixed(2)} did not improve on ${this.best.toFixed(2)} (needs +${this.minConfidenceDelta})`
+        );
+      }
+    }
+    if (channels === 0) {
+      this.indeterminate += 1;
+      return void 0;
+    }
+    if (progressed) {
+      this.stalledRun = [];
+      return void 0;
+    }
+    this.stalledRun.push(sample.iteration);
+    this.lastEvidence = flat;
+    if (this.stalledRun.length < this.window) return void 0;
+    return {
+      window: this.window,
+      iterations: [...this.stalledRun],
+      reason: this.lastReason,
+      evidence: [...this.lastEvidence]
+    };
+  }
+  /**
+   * True when the detector has seen a full window of samples and none carried
+   * any evidence channel — detection is configured but cannot fire. The loop
+   * uses this to warn once instead of failing silently-inert.
+   */
+  isInert() {
+    return this.indeterminate >= this.window && this.indeterminate === this.sampled;
+  }
+};
+
 // src/core/context.ts
 function childContext(parent, over) {
   return {
@@ -1439,6 +1926,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
@@ -1480,6 +1968,7 @@ function loop(config) {
   const until = config.until ? toCondition(config.until) : void 0;
   const stopOn = config.stopOn ? toCondition(config.stopOn) : void 0;
   const onError = config.retry?.onError ?? "continue";
+  const noProgress = resolveNoProgress(config.noProgress);
   const job = async (parent) => {
     const path = [...parent.path, config.name];
     const depth = parent.depth + 1;
@@ -1566,6 +2055,8 @@ function loop(config) {
       let last;
       let consecutiveErrors = 0;
       let consecutiveReviewFails = 0;
+      const tracker = noProgress ? new ProgressTracker(noProgress) : void 0;
+      let warnedInert = false;
       while (true) {
         await yieldToLoop();
         if (parent.signal.aborted)
@@ -1586,6 +2077,7 @@ function loop(config) {
         }
         iteration += 1;
         const ctx = ctxAt(iteration, last);
+        let turnReview;
         parent.emit({ kind: "loop:iteration", ts: ts(), path, iteration });
         let bodyThrew = false;
         try {
@@ -1746,13 +2238,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(
               {
@@ -1766,11 +2263,12 @@ function loop(config) {
           }
           consecutiveReviewFails += 1;
           lastReview = reviewOutcome;
+          turnReview = reviewOutcome;
           parent.log(
             `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",
@@ -1781,6 +2279,62 @@ function loop(config) {
             );
           }
         }
+        if (tracker) {
+          let fingerprint;
+          if (noProgress.workspace !== false) {
+            fingerprint = await workspaceFingerprint({
+              cwd: ctx.workspace.dir,
+              signal: parent.signal
+            });
+          }
+          let signalValue;
+          if (noProgress.signal) {
+            try {
+              const v = await noProgress.signal(ctx, last);
+              signalValue = v == null ? void 0 : String(v);
+            } catch (e) {
+              throw LoopError.from(e, {
+                code: "VALIDATION",
+                phase: "body",
+                path,
+                iteration
+              });
+            }
+          }
+          const report = tracker.record({
+            iteration,
+            fingerprint,
+            signal: signalValue,
+            confidence: turnReview?.confidence ?? conv.confidence ?? last.confidence,
+            reason: turnReview ? turnReview.summary ?? "review rejected" : conv.reason
+          });
+          if (!warnedInert && tracker.isInert()) {
+            warnedInert = true;
+            parent.log(
+              `noProgress is set on ${config.name} but no evidence channel exists (no git workspace, no gate confidence, no custom signal); stall detection is inert`,
+              "warn"
+            );
+          }
+          if (report) {
+            parent.emit({
+              kind: "loop:stall",
+              ts: ts(),
+              path,
+              iteration,
+              report
+            });
+            return finish(
+              {
+                status: "exhausted",
+                summary: `stalled after ${report.iterations.length} iterations with no observable progress: ${report.reason}`,
+                confidence: last.confidence,
+                data: last.data,
+                stall: report
+              },
+              iteration
+            );
+          }
+        }
         if (config.delayMs) await delay(config.delayMs, parent.signal);
       }
     } catch (e) {
@@ -1802,6 +2356,7 @@ function loop(config) {
     kind: "loop",
     name: config.name,
     max: config.max,
+    noProgress: noProgress?.window,
     start: describeConditions(config.start),
     gate: describeConditions(config.until),
     stopOn: describeConditions(config.stopOn),
@@ -1866,14 +2421,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"
       )
     );
@@ -1886,7 +2441,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")
     );
   }
 };
@@ -1972,6 +2527,188 @@ 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"
@@ -1990,11 +2727,13 @@ 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,
@@ -2025,6 +2764,7 @@ function startSupervisor(input) {
 `);
       } catch {
       }
+      semanticSink(event);
     }
     switch (event.kind) {
       case "loop:iteration":
@@ -2101,6 +2841,9 @@ function listRuns() {
 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) {
@@ -2118,6 +2861,8 @@ function formatEvent(event) {
       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":
@@ -2128,6 +2873,8 @@ function formatEvent(event) {
       return `${at}  tool ${event.name} ${event.phase}`;
     case "engine:usage":
       return `${at}  ${event.model}: ${event.usage.inputTokens}/${event.usage.outputTokens} tok`;
+    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":
@@ -2150,12 +2897,12 @@ var CHECKPOINT_AT = /* @__PURE__ */ new Set([
   "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 (NOISE2.has(event.kind)) return;
@@ -2167,14 +2914,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 {
@@ -2344,6 +3091,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, formatEvent, fromFile, gateJob, groundingText, hasStagedChanges, headSha, isDirty, isForge, isRepo, jobMeta, kickback, ledgerPath, listRuns, log, loop, mergeAbort, mergeBranch, mergeNoCommit, minConfidence, never, not, predicate, promptPath, push, quorum, readLedger, readPrompt, readRunStatus, removeWorktree, renderPlan, resetLedger, resetPrompt, resolveSystem, retrieveLedger, run, runEventsPath, runsHome, setMeta, stageAll, toCondition };
-//# sourceMappingURL=chunk-6BDWTFOS.js.map
-//# sourceMappingURL=chunk-6BDWTFOS.js.map
+export { Budget, EXIT_PAUSED, EngineRegistry, GhForge, MockForge, ProgressTracker, 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, resolveNoProgress, resolveSystem, retrieveLedger, reviewContext, reviewPanel, revisionFromOutcome, revisionRequest, run, runEventsPath, runSemanticRecordsPath, runsHome, semanticRecordsFromEvent, setMeta, stageAll, toCondition, workspaceFingerprint };
+//# sourceMappingURL=chunk-3PMVII43.js.map
+//# sourceMappingURL=chunk-3PMVII43.js.map