@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/agent/group/run-group-turn.js

@@ -0,0 +1,218 @@
+// Run one full group turn: persist the owner's line, walk the mention cascade
+// (turn-resolver.js), and for each speaker call the SAME turn engine the 1:1
+// chat uses (run-turn.js) — so agents run their real tools instead of narrating
+// them — streaming tokens back tagged by speaker. Everything persists to the
+// message ledger via the group helpers (stores/messages.js); there is no
+// separate group store.
+import { wasAbortedBySignal } from "#core/agent/abort.js";
+import { resolveAgentModel } from "#core/agent/agent-model.js";
+import { buildAgentSystem } from "#core/agent/build-agent-system.js";
+import { groupToolIters } from "#core/agent/constants.js";
+import { runAgentTurn } from "#core/agent/run-turn.js";
+import { readAgents } from "#core/apc/parser.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import {
+  appendGroupAgentMessage,
+  appendGroupOwnerMessage,
+  lastGroupOwnerMessage,
+  readProjectGroupThread,
+} from "#core/stores/messages.js";
+import { resolveGroupTurn } from "./turn-resolver.js";
+
+const displayName = (a) => a.fields?.Name || a.slug;
+
+// System addendum that turns a normal agent into a group participant. No "you
+// have no tools" line — in a group the agent keeps its real toolset; this only
+// frames the room and the @-mention protocol.
+function groupSystemBlock({ me, ownerName, others }) {
+  const roster = others.length ? others.join(", ") : "(nadie más por ahora)";
+  return [
+    "## Group chat",
+    `You are in a group chat with **${ownerName}** (the owner) and these other agents: ${roster}.`,
+    "The conversation transcript is shown to you with each line prefixed by who said it.",
+    `Reply ONLY as yourself (**${me}**), in your own voice, concisely. Never write anyone else's lines, and never speak for the owner.`,
+    "**How to bring someone in:** the ONLY way another participant hears you and gets a turn is if you write their handle with an @ and their exact slug — e.g. `" + others.map((x) => x.match(/@[a-z0-9_-]+/)?.[0]).filter(Boolean).join("`, `") + "`. Writing just their NAME (without the @slug) does NOT reach them.",
+    "@-mention another agent with their exact @slug only if they actually need to reply. If you can close the turn yourself, don't cite anyone. A short acknowledgement is fine — don't pad.",
+  ].join("\n");
+}
+
+function reasonLine({ reason, byOwner, ownerName, nameFor, me }) {
+  if (byOwner) return `${ownerName} addressed the group and it's your turn, ${me}. Reply now.`;
+  return `${nameFor(reason)} tagged you (@${me}) into the conversation. Reply now.`;
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.p          resolved project (db entry: path, storagePath, config, logMessage)
+ * @param {string} args.gid        group id
+ * @param {string} args.text       the owner's message body
+ * @param {string} args.ownerName  display name for the owner in the transcript
+ * @param {object} args.config     global config (fallback for the project's)
+ * @param {object} args.projects   projects registry (for runAgentTurn tool handlers)
+ * @param {object} [args.plugins]
+ * @param {object} [args.registries]
+ * @param {string} [args.from]     regenerate: slug of the speaker to resume from
+ * @param {string|null} [args.reason] regenerate: who pulled that speaker in (null = owner)
+ * @param {AbortSignal} [args.signal] the owner pressed Stop: aborts the speaker
+ *        mid-run and stops the cascade behind it (see the catch in runAgent)
+ * @param {(ev:object)=>void} [args.onEvent] stream sink: owner_message/speaker_start/speaker_delta/speaker_final/speaker_aborted/done
+ * @returns {Promise<{messages: object[]}>}
+ */
+export async function runGroupTurn({ p, gid, text, attachments = [], media = null, rerun = false, from = null, reason = null, ownerName = "Owner", config, projects, plugins, registries, signal = null, onEvent = () => { } }) {
+  const thread = readProjectGroupThread(p.storagePath, gid);
+  if (!thread) throw new Error(`group ${gid} not found`);
+
+  // Regenerate: reuse the LAST owner turn already in the thread (the caller
+  // truncated from the target bubble onward), without appending a new owner
+  // line. If `from` is set, resume the cascade at that speaker and leave
+  // earlier replies this turn untouched.
+  let resume = null;
+  if (rerun) {
+    const seed = lastGroupOwnerMessage(p.storagePath, gid);
+    if (seed == null) throw new Error("nothing to regenerate: the group has no owner message yet");
+    text = seed;
+    if (from) {
+      resume = {
+        from,
+        reason: reason || "owner",
+        byOwner: !reason,
+      };
+    }
+  }
+
+  // Resolve each participant against its home project when the room was built
+  // cross-project (inbox / mobile). Same-project rooms keep the host roster.
+  const homes = thread.homes && typeof thread.homes === "object" ? thread.homes : null;
+  const resolveHome = (slug) => {
+    const homeId = homes?.[slug];
+    if (homeId == null || homeId === "" || String(homeId) === String(p.id)) return p;
+    try {
+      const home = projects?.get?.(homeId);
+      return home?.path ? home : p;
+    } catch {
+      return p;
+    }
+  };
+  const bySlug = new Map(); // slug -> { agent, project }
+  for (const slug of thread.participants || []) {
+    const home = resolveHome(slug);
+    const agent = readAgents(home.path).find((a) => a.slug === slug);
+    if (agent) bySlug.set(slug, { agent, project: home });
+  }
+  const agents = [...bySlug.values()].map((x) => x.agent);
+  if (!agents.length) throw new Error("group has no resolvable agents");
+  if (from && !bySlug.has(from))
+    throw new Error(`agent ${from} is not in this group`);
+
+  const nameFor = (author) =>
+    author === "owner" ? ownerName : (bySlug.get(author) ? displayName(bySlug.get(author).agent) : author);
+
+  const participants = [
+    { slug: "owner", name: ownerName, kind: "owner" },
+    ...[...bySlug.entries()].map(([slug, { agent }]) => ({ slug, name: displayName(agent), kind: "agent" })),
+  ];
+
+  // The owner's line first, so it's part of the transcript everyone reads.
+  // (A regenerate reuses the owner line already there — don't duplicate it.)
+  if (!rerun) {
+    appendGroupOwnerMessage(p.logMessage, gid, text, media);
+    onEvent({ type: "owner_message" });
+  }
+
+  const cfg = p.config || config;
+  const said = [];
+
+  const runAgent = async (slug, ctx) => {
+    const hit = bySlug.get(slug);
+    if (!hit) throw new Error(`agent ${slug} is not in this group`);
+    const { agent, project: agentProject } = hit;
+    const modelId = await resolveAgentModel({ agent, config: cfg });
+    if (!modelId) throw new Error(`no model for agent ${slug}`);
+
+    const me = displayName(agent);
+    const others = participants
+      .filter((x) => x.kind === "agent" && x.slug !== slug)
+      .map((x) => `${x.name} (@${x.slug})`);
+    const system = buildAgentSystem(agentProject, agent, {
+      invocation: "engine",
+      caller: ctx.byOwner ? "user" : ctx.reason,
+      globalConfig: cfg,
+      extraParts: [groupSystemBlock({ me, ownerName, others })],
+    });
+
+    // Fresh read each time: earlier speakers this turn are already persisted, so
+    // a later cascade speaker sees what was just said. Tool rows stay out of the
+    // transcript text — they are execution noise; the answer bubble is enough.
+    const current = readProjectGroupThread(p.storagePath, gid);
+    const transcript = current.messages
+      .filter((m) => m.role === "user" || (m.role === "assistant" && m.content))
+      .map((m) => `${m.role === "user" ? ownerName : (nameFor(m.agent) || "agent")}: ${m.content}`)
+      .join("\n");
+    const directive = reasonLine({ reason: ctx.reason, byOwner: ctx.byOwner, ownerName, nameFor, me });
+
+    onEvent({ type: "speaker_start", slug, reason: ctx.byOwner ? null : ctx.reason });
+    // What this speaker has produced so far, kept alongside the stream so an
+    // interrupted reply can still be written to the room. runAgentTurn throws on
+    // abort and takes its text and trace with it.
+    const partialTrace = [];
+    let partialText = "";
+    let result;
+    try {
+      result = await runAgentTurn({
+        p: agentProject, agent, modelId, system,
+        prompt: `${transcript}\n\n---\n${directive}`,
+        previousMessages: [],
+        // The owner's image rides on this turn for every speaker answering it, so
+        // a vision model actually sees what was sent (not just the "[image
+        // attached]" marker already folded into the transcript text).
+        attachments,
+        channel: CHANNELS.WEB,
+        // NOT the web channel's budget, even though the channel above says web:
+        // that string picks the channel PROMPT, and a room fans one owner message
+        // out into up to MAX_TURNS_PER_MESSAGE of these runs. See GROUP_TOOL_ITERS.
+        maxIters: groupToolIters(cfg),
+        tools: true,
+        projects, plugins, registries, config: cfg,
+        signal,
+        onEvent: (ev) => {
+          if (ev?.type === "tool_result" && ev.trace) partialTrace.push(ev.trace);
+          onEvent(ev);
+        },
+        onToken: (chunk) => { partialText += chunk; onEvent({ type: "speaker_delta", slug, delta: chunk }); },
+      });
+    } catch (e) {
+      if (!wasAbortedBySignal(e, signal)) throw e;
+      // The owner stopped the room mid-reply. Whatever streamed is real work they
+      // watched happen, so it stays in the transcript with the tool rows that
+      // really ran — the next owner message reads this as history, exactly as the
+      // 1:1 chat does with an interrupted turn. Returning "" parses no mentions,
+      // and the resolver's own signal check stops the queue behind us.
+      const partial = partialText.trim();
+      if (partial || partialTrace.length) {
+        appendGroupAgentMessage(p.logMessage, gid, {
+          slug, body: partial,
+          reason: ctx.byOwner ? null : ctx.reason,
+          model: modelId, trace: partialTrace,
+        });
+      }
+      onEvent({ type: "speaker_aborted", slug, text: partial });
+      return "";
+    }
+
+    const reply = (result.text || "").trim() || "…";
+    appendGroupAgentMessage(p.logMessage, gid, {
+      slug, body: reply,
+      reason: ctx.byOwner ? null : ctx.reason,
+      model: result.model, usage: result.usage,
+      trace: result.trace,
+      media: result.media,
+    });
+    said.push({ slug, text: reply });
+    onEvent({ type: "speaker_final", slug, model: result.model || modelId, usage: result.usage });
+    return reply;
+  };
+
+  await resolveGroupTurn({ text, participants, runAgent, resume, signal });
+  onEvent({ type: "done" });
+  return { messages: said };
+}

package/src/core/agent/group/turn-resolver.js

@@ -0,0 +1,165 @@
+// Group chat turn-taking (option C + cross-mentions).
+//
+// A group conversation is the owner plus N agents in one room. Who speaks on a
+// given human message is decided by @mentions, and mentions CASCADE: if the
+// owner writes "@naty …", Naty speaks; if Naty's reply names "@candela",
+// Candela speaks next — even though the owner never addressed her. With no
+// mention at all, the FIRST agent in the room takes the turn.
+//
+// This module is pure orchestration: it parses mentions and walks the cascade,
+// delegating the actual model call to a `runAgent(slug, ctx)` callback the
+// caller injects. That keeps the turn logic unit-testable without engines.
+
+// Agents keep talking as long as they @-mention someone. The only loop guard
+// is a ceiling: one human message can produce at most this many agent replies
+// (A↔B ping-pong included). After that the cascade stops even if they still cite.
+//
+// Exported because it is half of the group tool budget: each of these replies is
+// a full tool-loop run, so this number multiplies GROUP_TOOL_ITERS into what one
+// owner message may actually cost (see agent/constants.js).
+export const MAX_TURNS_PER_MESSAGE = 10;
+
+// Strip diacritics + lowercase so "@Natalia", "@natalia" and "@natália" all
+// resolve to the same participant.
+function norm(s) {
+  return String(s || "")
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .trim();
+}
+
+/**
+ * Build the set of tokens that address a participant: its slug and every word
+ * of its display name (so "@naty" matches slug `naty` and "@Natalia" matches
+ * the agent whose Name is "Natalia"). Multi-word names also match on the full
+ * name joined without spaces ("@analytics-bot", "@AnaLucia").
+ */
+function aliasesFor(participant) {
+  const out = new Set();
+  const add = (v) => { const n = norm(v); if (n) out.add(n); };
+  add(participant.slug);
+  if (participant.name) {
+    add(participant.name);
+    add(participant.name.replace(/\s+/g, ""));
+    for (const w of String(participant.name).split(/\s+/)) add(w);
+  }
+  return out;
+}
+
+/**
+ * Parse @mentions out of a message body and resolve them to participant slugs.
+ * Only AGENT participants can be addressed (mentioning the owner is a no-op —
+ * the owner speaks by typing, not by being summoned). The author never mentions
+ * themselves into another turn.
+ *
+ * @param {string} text
+ * @param {Array<{slug,name,kind}>} participants
+ * @param {string} [authorSlug]  slug of who wrote `text`, excluded from the result
+ * @returns {string[]} ordered, de-duplicated slugs of mentioned agents
+ */
+export function parseMentions(text, participants, authorSlug) {
+  const agents = participants.filter((p) => p.kind !== "owner");
+  // Longest alias first so "@ana-lucia" wins over a bare "@ana".
+  const table = agents
+    .map((p) => ({ slug: p.slug, aliases: [...aliasesFor(p)] }))
+    .flatMap((p) => p.aliases.map((a) => ({ slug: p.slug, alias: a })))
+    .sort((a, b) => b.alias.length - a.alias.length);
+
+  const found = [];
+  const seen = new Set();
+  // @token where token is a run of letters/digits/_/-  (mentions never span
+  // spaces). We scan raw matches and resolve each against the alias table.
+  const re = /@([\p{L}\p{N}_-]+)/gu;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const token = norm(m[1]);
+    const hit = table.find((t) => t.alias === token);
+    if (!hit) continue;
+    if (hit.slug === authorSlug) continue;
+    if (seen.has(hit.slug)) continue;
+    seen.add(hit.slug);
+    found.push(hit.slug);
+  }
+  return found;
+}
+
+/**
+ * Decide who speaks first for a human message: the agents it mentions, in
+ * order; or, if it mentions nobody, the first agent in the room.
+ *
+ * @returns {string[]} slugs to seed the cascade with
+ */
+export function seedSpeakers(text, participants) {
+  const mentioned = parseMentions(text, participants, "owner");
+  if (mentioned.length) return mentioned;
+  const firstAgent = participants.find((p) => p.kind !== "owner");
+  return firstAgent ? [firstAgent.slug] : [];
+}
+
+/**
+ * Walk a full group turn. Starting from the human message, run each seeded
+ * speaker; scan every reply for @mentions and queue those agents — even if
+ * they already spoke this turn, so a back-and-forth keeps going until nobody
+ * cites anyone (or the ceiling is hit).
+ *
+ * @param {object} args
+ * @param {string} args.text          the human message body
+ * @param {Array}  args.participants  [{slug,name,kind}], agents in room order
+ * @param {(slug:string, ctx:{reason:string, byOwner:boolean}) => Promise<string>} args.runAgent
+ *        Runs one agent's turn against the current transcript and returns its
+ *        reply text. The resolver appends it before scanning for mentions.
+ * @param {(slug:string) => void} [args.onSpeakerStart]  fires before each run
+ * @param {number} [args.maxTurns]
+ * @param {AbortSignal} [args.signal]
+ *        The owner stopped the room. Checked between speakers so an interrupted
+ *        cascade does not start the NEXT agent's turn: the speaker that was
+ *        mid-run is aborted through its own run's signal, and this stops the
+ *        queue behind it. Without it "stop" only ever ended one reply of ten.
+ * @param {{from:string, reason?:string, byOwner?:boolean}} [args.resume]
+ *        Regenerating one bubble: start from `from` instead of re-seeding the
+ *        whole room from the owner line. Earlier replies this turn stay put;
+ *        a new @mention can still pull those speakers in again.
+ * @returns {Promise<Array<{slug,text}>>} the replies in the order they were said
+ */
+export async function resolveGroupTurn({
+  text,
+  participants,
+  runAgent,
+  onSpeakerStart,
+  maxTurns = MAX_TURNS_PER_MESSAGE,
+  resume = null,
+  signal = null,
+}) {
+  const replies = [];
+  // Each queue entry remembers WHY the agent is speaking: addressed by the
+  // owner, or pulled in by another agent's mention. The reason is handed to
+  // runAgent so the prompt can frame it ("owner asked you" vs "naty tagged you").
+  // A regenerate of one bubble resumes from that speaker; a fresh turn seeds
+  // from the owner's @mentions (or the first agent in the room).
+  const queue = resume?.from
+    ? [{ slug: resume.from, reason: resume.reason || "owner", byOwner: resume.byOwner !== false }]
+    : seedSpeakers(text, participants).map((slug) => ({ slug, reason: "owner", byOwner: true }));
+
+  while (queue.length && replies.length < maxTurns) {
+    if (signal?.aborted) break;
+    const { slug, reason, byOwner } = queue.shift();
+    const participant = participants.find((p) => p.slug === slug && p.kind !== "owner");
+    if (!participant) continue;
+
+    onSpeakerStart?.(slug);
+    const reply = await runAgent(slug, { reason, byOwner });
+    const replyText = typeof reply === "string" ? reply : "";
+    replies.push({ slug, text: replyText });
+
+    // A reply can pull anyone in, including someone who already spoke — that's
+    // how the ping-pong continues. Skip only if they're already waiting.
+    for (const mentioned of parseMentions(replyText, participants, slug)) {
+      if (queue.some((q) => q.slug === mentioned)) continue;
+      queue.push({ slug: mentioned, reason: slug, byOwner: false });
+    }
+  }
+  return replies;
+}
+
+export const __test__ = { norm, aliasesFor, MAX_TURNS_PER_MESSAGE };

package/src/core/agent/judge.js

@@ -1,17 +1,39 @@
 // Goal-completion judge loop (OpenHands Critic / iterative-refinement
-// pattern). After a completion-contract run declares done, an LLM judge scores
-// how likely the ORIGINAL goal is actually met (0..1). Below the threshold,
-// the agent gets a follow-up verification note and continues — bounded by
-// max_iterations so a harsh judge can't spin forever. Opt-in and scoped to
-// completion-contract surfaces (coding turns), where "done" is checkable.
+// pattern). An LLM judge scores how likely the ORIGINAL goal is actually met
+// (0..1); below the threshold the agent gets a follow-up verification note and
+// continues — bounded by max_iterations so a harsh judge can't spin forever.
+//
+// Two bounds, and only one of them is a count of rounds. `max_iterations` caps
+// how many times we RE-ASK; the turn's tool budget caps how much the asking may
+// cost, and the rounds share that budget with the run that came before them
+// (applyJudgeLoop's `maxIters`). They used to be independent, which quietly made
+// the real ceiling max_iterations × the budget — see constants.js.
+//
+// It serves two different failures, through the same loop:
+//
+//   - Completion-contract turns (coding surfaces) declare "done" themselves,
+//     and the judge checks that claim. Opt-in: `judge.enabled`.
+//   - Conversational turns (Telegram, web chat) end whenever the model stops
+//     calling tools — which it also does when it merely ANNOUNCES the next step
+//     ("ahora genero el SRT en inglés") and writes no call. Nothing declared
+//     anything; the task just stopped halfway and waited to be poked. Here the
+//     judge IS the poke, and it is on by default (`judge.continue_unfinished`).
 import { callEngine } from "../engines/index.js";
+import { TURN_ENDING_TOOLS } from "./tools/names.js";
+import { MIN_JUDGE_ROUND_ITERS } from "./constants.js";
 
 export function judgeConfig(globalConfig) {
   const raw = globalConfig?.super_agent?.judge || {};
   const threshold = Number(raw.success_threshold);
   const iters = parseInt(raw.max_iterations, 10);
   return {
+    // Verify a contract turn's own "done". Opt-in — the coding surfaces pay a
+    // judge call per finish, and not every deployment wants that.
     enabled: raw.enabled === true,
+    // Continue a conversational turn that stopped mid-task. On unless switched
+    // off: a turn that quits after announcing its next step reads as a bug, and
+    // the alternative is the user typing "seguí" to restart it by hand.
+    continue_unfinished: raw.continue_unfinished !== false,
     success_threshold:
       Number.isFinite(threshold) && threshold > 0 && threshold <= 1 ? threshold : 0.6,
     max_iterations: Number.isFinite(iters) && iters > 0 ? Math.min(iters, 5) : 2,
@@ -91,10 +113,17 @@ export function parseVerdict(text) {
  * Score a finished run against its goal. Returns {score, reasoning, missing}
  * or null when the judge is unusable (engine down, unparseable reply) — the
  * caller treats null as "accept the result", never as a failure.
+ *
+ * `fallbackModel` is the last resort for the model that does the scoring, and
+ * exists for project agents: they run on installs that never configured a
+ * super-agent, and resolving to "" there would switch the judge off silently —
+ * shipped, on by default, and doing nothing. The caller passes the model that
+ * ran the turn. The explicit knobs still win, in order: `judge.model`, then
+ * `super_agent.model`.
  */
-export async function judgeCompletion({ goal, result, globalConfig, callEngineFn = callEngine }) {
+export async function judgeCompletion({ goal, result, globalConfig, fallbackModel = "", callEngineFn = callEngine }) {
   const cfg = judgeConfig(globalConfig);
-  const modelId = cfg.model || globalConfig?.super_agent?.model || "";
+  const modelId = cfg.model || globalConfig?.super_agent?.model || fallbackModel || "";
   if (!modelId) return null;
   try {
     const r = await callEngineFn({
@@ -136,15 +165,89 @@ export function buildJudgeFollowup(verdict, iteration) {
     .join("\n");
 }
 
+/**
+ * Is this conversational turn one worth checking — and continuing if unfinished?
+ *
+ * Two exclusions, both about not spending a call to learn nothing:
+ *   - a turn that ran no tools is chat, and chat has no half-done work; judging
+ *     it would be one model call per "hola".
+ *   - a turn that ended by ASKING the user is not unfinished, it is waiting. A
+ *     verdict of "not complete" there would push the agent to answer its own
+ *     question instead of letting the person answer it. That covers both ways a
+ *     turn can ask: the ask_questions tool, and run-agent's reserved wrap-up
+ *     step (`endedAwaitingUser`), whose whole job is to recap and ask "want me
+ *     to keep going?" when the tool budget runs out.
+ *
+ * The wrap-up case is the one that bit us (2026-08-30, web chat): the budget
+ * ran out at 9 actions, the wrap-up asked whether to continue, the judge read
+ * "worked and then stopped" and re-ran the turn — which spent another 9 actions
+ * and hit the same wall, so the user got the same recap and the same question
+ * three times in a row, never once getting to answer it. Extending a budget the
+ * system itself set is what maxIters is for; the judge's job is to poke a turn
+ * that quit on its own.
+ *
+ * @param {{trace?: {tool?: string}[], endedAwaitingUser?: boolean}} result a runAgent result
+ */
+export function continuableTurn(result) {
+  const trace = Array.isArray(result?.trace) ? result.trace : [];
+  if (trace.length === 0) return false;
+  return !awaitingUser(result);
+}
+
+/**
+ * Did this turn close by putting a question to the user? Two ways it can:
+ * the ask_questions tool, or run-agent's reserved wrap-up step, which recaps
+ * and asks "want me to keep going?" when the tool budget runs out
+ * (`endedAwaitingUser`). Either way the next move belongs to a person.
+ *
+ * @param {{trace?: {tool?: string}[], endedAwaitingUser?: boolean}} result a runAgent result
+ */
+export function awaitingUser(result) {
+  if (result?.endedAwaitingUser) return true;
+  const trace = Array.isArray(result?.trace) ? result.trace : [];
+  return trace.some((t) => TURN_ENDING_TOOLS.has(String(t?.tool || "")));
+}
+
+/**
+ * Iterations of the tool budget a run consumed. runAgent reports it directly;
+ * an injected runner (tests, a surface with its own loop) may not, and for
+ * those we fall back to a LOWER BOUND — a tool result cannot exist without an
+ * iteration that produced it, and a round that ran at all cost at least one.
+ * Under-counting means one extra round in a synthetic case; not counting at all
+ * would mean no ceiling, which is the bug this whole file's budget arithmetic
+ * exists to close.
+ *
+ * @param {{iterations?: number, trace?: unknown[]}} result a runAgent result
+ */
+export function itersSpent(result) {
+  const n = Number(result?.iterations);
+  if (Number.isFinite(n) && n >= 0) return n;
+  const trace = Array.isArray(result?.trace) ? result.trace : [];
+  return Math.max(1, trace.length);
+}
+
 /**
  * Refinement driver, dependency-injected so surfaces and tests supply their
  * own judge/runner. `judgeFn(result)` → verdict|null; `runFollowup(followupPrompt,
- * result)` → next run result. Merges usage and traces across rounds and
- * attaches the verdict trail as `result.judge`.
+ * result, {maxIters})` → next run result. Merges usage, traces and iteration
+ * spend across rounds and attaches the verdict trail as `result.judge`.
+ *
+ * `maxIters` is the budget for the WHOLE TURN — the run that produced
+ * `initialResult` plus every round this loop adds — not a per-round allowance.
+ * Each round is handed what the rounds before it left, and once too little is
+ * left to be worth a round (MIN_JUDGE_ROUND_ITERS) the loop stops. See the
+ * "one turn, one budget" note in constants.js for why the total is shared
+ * rather than the rounds getting a budget of their own.
+ *
+ * Omit it (or pass 0) and there is no arithmetic to do: rounds run on whatever
+ * budget the runner picks, bounded only by cfg.max_iterations. That is the
+ * shape an injected runner without a tool loop wants.
  */
-export async function applyJudgeLoop({ initialResult, cfg, judgeFn, runFollowup, onEvent = null }) {
+export async function applyJudgeLoop({ initialResult, cfg, judgeFn, runFollowup, onEvent = null, maxIters = 0 }) {
   let result = initialResult;
   const trail = [];
+  const budget = Number.isFinite(Number(maxIters)) && Number(maxIters) > 0 ? Number(maxIters) : 0;
+  let spent = itersSpent(initialResult);
   for (let i = 1; i <= cfg.max_iterations; i++) {
     const verdict = await judgeFn(result);
     if (verdict) {
@@ -160,7 +263,23 @@ export async function applyJudgeLoop({ initialResult, cfg, judgeFn, runFollowup,
       }
     }
     if (!verdict || verdict.score >= cfg.success_threshold) break;
-    const next = await runFollowup(buildJudgeFollowup(verdict, i), result);
+    // The verdict is worth recording even when we cannot act on it — it says
+    // the turn ended unverified, and why. Acting on it is what the budget
+    // decides. We judge first and check the budget here, rather than the other
+    // way round, because a completion-contract turn is judged FOR the verdict.
+    const remaining = budget ? budget - spent : 0;
+    if (budget && remaining < MIN_JUDGE_ROUND_ITERS) {
+      if (typeof onEvent === "function") {
+        await onEvent({ type: "judge_budget_exhausted", iteration: i, spent, budget });
+      }
+      break;
+    }
+    const next = await runFollowup(
+      buildJudgeFollowup(verdict, i),
+      result,
+      budget ? { maxIters: remaining } : {},
+    );
+    spent += itersSpent(next);
     result = {
       ...next,
       usage: {
@@ -168,7 +287,15 @@ export async function applyJudgeLoop({ initialResult, cfg, judgeFn, runFollowup,
         output_tokens: (result.usage?.output_tokens || 0) + (next.usage?.output_tokens || 0),
       },
       trace: [...(result.trace || []), ...(next.trace || [])],
+      // The turn's total, not this round's — same rule as usage and trace. A
+      // caller that logs "spent N of maxIters" must see one number for the turn.
+      iterations: spent,
     };
+    // The round we just ran closed by asking the user something — it exhausted
+    // its budget and wrapped up, or it called ask_questions. Same rule as the
+    // gate that let us in here: another round would answer over their head and
+    // re-ask the identical question.
+    if (awaitingUser(result)) break;
   }
   return trail.length ? { ...result, judge: trail } : result;
 }