@dadado/agent-kit-cli 5.17.0 → 6.0.0

package/dist/{chunk-TFZ2JUXH.js → chunk-PAB35H27.js}

@@ -8,18 +8,19 @@ import {
   extractHandoffNamedPlans,
   namedPlanCandidatePaths,
   parsePlanFrontmatter
-} from "./chunk-KD2MYBB6.js";
+} from "./chunk-WUWRGOUV.js";
 import {
   LineSplitter,
   RedactingStreamBuffer,
   claudeRedactions,
+  formatHitlGateLine,
   formatHitlSummary,
   operatorQuitStop,
   parseStreamLine,
   redactSecrets,
   renderStreamEvent,
   whichBinary
-} from "./chunk-OUQZC744.js";
+} from "./chunk-B5CH47OS.js";
 import {
   TtySpinner,
   shouldUseVisualMotion,
@@ -30,19 +31,22 @@ import {
   logger
 } from "./chunk-ZB43YMHW.js";
 import {
-  HANDOFF_REL
-} from "./chunk-5VCOWTTP.js";
+  HANDOFF_REL,
+  STATE_ROOT_ENV,
+  ensureLoopLogsDir,
+  runnerStatePaths
+} from "./chunk-C26I6HTO.js";
 import {
   fileExists,
   readJson
-} from "./chunk-77V75A7O.js";
+} from "./chunk-5B4DVO6C.js";
 
 // src/mission-control/live-run.ts
 import { readFile as readFile2 } from "fs/promises";
 import path2 from "path";
 
 // src/plan-loop/plan-state.ts
-import { readFile, readdir } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import path from "path";
 function countPendingTodos(raw) {
   return parsePlanFrontmatter(raw).todos.filter(
@@ -486,18 +490,21 @@ async function withLiveTui(opts, run) {
 
 // src/plan-loop/detect.ts
 var DETECT_ORDER = ["cursor-agent", "claude"];
+var EXPLICIT_ONLY_BACKENDS = ["codex", "cursor-acp"];
 var INSTALL_HINTS = {
   "cursor-agent": "Install the Cursor Agent CLI and ensure `cursor-agent` is on PATH (https://cursor.com/docs/cli).",
-  claude: "Install Claude Code and ensure `claude` is on PATH (https://code.claude.com/docs/en/quickstart)."
+  claude: "Install Claude Code and ensure `claude` is on PATH (https://code.claude.com/docs/en/quickstart).",
+  "cursor-acp": "Install the Cursor Agent CLI and ensure `cursor-agent` is on PATH (https://cursor.com/docs/cli/acp); sign in with `cursor-agent login`.",
+  codex: "Install the Codex CLI and ensure `codex` is on PATH (https://developers.openai.com/codex/cli)."
 };
 function isBackendId(id) {
-  return id === "cursor-agent" || id === "claude";
+  return id === "cursor-agent" || id === "claude" || id === "codex" || id === "cursor-acp";
 }
 function isRequestedBackend(id) {
   return id === "auto" || isBackendId(id);
 }
 function listDetectBackendIds() {
-  return ["auto", ...DETECT_ORDER];
+  return ["auto", ...DETECT_ORDER, ...EXPLICIT_ONLY_BACKENDS];
 }
 async function detectAgentBackend(requested, whichFn = whichBinary) {
   const id = requested.trim().toLowerCase();
@@ -534,8 +541,220 @@ async function detectAgentBackend(requested, whichFn = whichBinary) {
   return { ok: true, id, bin };
 }
 
+// src/plan-loop/driver-events.ts
+import { createInterface } from "readline";
+import { StringDecoder as StringDecoder2 } from "string_decoder";
+var DRIVER_PROTOCOL_MAJOR = 1;
+var DRIVER_PROTOCOL_VERSION = "1.1.0";
+var DRIVER_EVENTS_FORMATS = ["ndjson"];
+var INBOUND_MAX_CHARS = 64 * 1024;
+var AGENT_PENDING_MAX_CHARS = 4 * 1024 * 1024;
+function formatDriverEvent(event, now = () => /* @__PURE__ */ new Date()) {
+  return `${JSON.stringify({ v: DRIVER_PROTOCOL_MAJOR, ts: now().toISOString(), ...event })}
+`;
+}
+function createDriverEmitter(write = (text) => {
+  process.stdout.write(text);
+}, now) {
+  return {
+    emit(event) {
+      try {
+        write(formatDriverEvent(event, now));
+      } catch {
+      }
+    }
+  };
+}
+function parseDriverInbound(line) {
+  const text = line.trim();
+  if (text.length > INBOUND_MAX_CHARS) return { ok: false, error: "line too long" };
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return { ok: false, error: "not JSON" };
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: "not a JSON object" };
+  }
+  const msg = value;
+  if (msg.v !== void 0 && msg.v !== DRIVER_PROTOCOL_MAJOR) {
+    return { ok: false, error: `unsupported protocol v${String(msg.v)}` };
+  }
+  if (msg.type === "stop") {
+    return {
+      ok: true,
+      message: { type: "stop", ...typeof msg.reason === "string" ? { reason: msg.reason } : {} }
+    };
+  }
+  if (msg.type !== "hitl_reply")
+    return { ok: false, error: `unknown type ${JSON.stringify(msg.type)}` };
+  if (typeof msg.askId !== "string" || !/^[a-z0-9-]+$/.test(msg.askId)) {
+    return { ok: false, error: "hitl_reply.askId must be a kebab-case string" };
+  }
+  if (typeof msg.reply === "number") {
+    if (!Number.isInteger(msg.reply) || msg.reply < 1) {
+      return { ok: false, error: "hitl_reply.reply number must be a positive integer" };
+    }
+    return { ok: true, message: { type: "hitl_reply", askId: msg.askId, reply: msg.reply } };
+  }
+  if (typeof msg.reply === "string" && msg.reply.trim() && !/[\r\n]/.test(msg.reply)) {
+    return { ok: true, message: { type: "hitl_reply", askId: msg.askId, reply: msg.reply.trim() } };
+  }
+  return { ok: false, error: "hitl_reply.reply must be a number or a one-line non-empty string" };
+}
+function inboundToRawAnswer(gate, parsed) {
+  if (!parsed.ok) return { kind: "stop", cause: "protocol error", detail: parsed.error };
+  const message = parsed.message;
+  if (message.type === "stop") return { kind: "stop", cause: "driver stop" };
+  if (message.askId !== gate.askId) {
+    return {
+      kind: "stop",
+      cause: "protocol error",
+      detail: `reply for ${message.askId} while gate ${gate.askId} is open`
+    };
+  }
+  return { kind: "line", text: String(message.reply) };
+}
+function createDriverAnswerReader(opts) {
+  const input = opts.input ?? process.stdin;
+  const queue = [];
+  let ended = false;
+  let waiter = null;
+  let rl = null;
+  const ensure = () => {
+    if (rl) return;
+    rl = createInterface({ input, terminal: false, crlfDelay: Number.POSITIVE_INFINITY });
+    rl.on("line", (line) => {
+      if (!line.trim()) return;
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w(line);
+      } else queue.push(line);
+    });
+    rl.on("close", () => {
+      ended = true;
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w(null);
+      }
+    });
+  };
+  const nextLine = (signal) => new Promise((resolve) => {
+    const queued = queue.shift();
+    if (queued !== void 0) {
+      resolve(queued);
+      return;
+    }
+    if (ended) {
+      resolve(null);
+      return;
+    }
+    const onAbort = () => {
+      if (waiter === settle) waiter = null;
+      resolve(null);
+    };
+    const settle = (line) => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(line);
+    };
+    if (signal?.aborted) {
+      resolve(null);
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    waiter = settle;
+  });
+  return {
+    read: async (gate, readOpts) => {
+      ensure();
+      opts.emitter.emit({
+        type: "hitl_gate",
+        tick: opts.tick(),
+        askId: gate.askId,
+        labels: [...gate.labels],
+        detection: gate.detection,
+        line: formatHitlGateLine(gate)
+      });
+      const line = await nextLine(readOpts.signal);
+      if (line === null) return { kind: "eof" };
+      return inboundToRawAnswer(gate, parseDriverInbound(line));
+    },
+    close: () => {
+      const r = rl;
+      rl = null;
+      r?.close();
+      if (typeof input.pause === "function") {
+        input.pause();
+      }
+    }
+  };
+}
+var DriverAgentSink = class {
+  constructor(emitter, tick) {
+    this.emitter = emitter;
+    this.tick = tick;
+  }
+  emitter;
+  tick;
+  pending = "";
+  dropped = false;
+  decoder = new StringDecoder2("utf8");
+  feed(chunk) {
+    try {
+      const text = typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+      if (!text) return;
+      const lines = (this.pending + text).split("\n");
+      this.pending = lines.pop() ?? "";
+      for (const line of lines) {
+        if (this.dropped) {
+          this.dropped = false;
+          continue;
+        }
+        this.take(line);
+      }
+      if (this.pending.length > AGENT_PENDING_MAX_CHARS) {
+        this.pending = "";
+        this.dropped = true;
+      }
+    } catch {
+    }
+  }
+  end() {
+    try {
+      const rest = this.pending + this.decoder.end();
+      this.pending = "";
+      if (rest && !this.dropped) this.take(rest);
+      this.dropped = false;
+    } catch {
+    }
+  }
+  take(raw) {
+    const line = raw.replace(/\r$/, "");
+    if (!line.trim()) return;
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{")) {
+      try {
+        const event = JSON.parse(trimmed);
+        if (typeof event === "object" && event !== null && !Array.isArray(event)) {
+          this.emitter.emit({
+            type: "agent_event",
+            tick: this.tick,
+            event
+          });
+          return;
+        }
+      } catch {
+      }
+    }
+    this.emitter.emit({ type: "agent_text", tick: this.tick, text: line });
+  }
+};
+
 // src/plan-loop/run-loop.ts
-import { mkdir, readFile as readFile4, rm, unlink } from "fs/promises";
+import { readFile as readFile4, rm, unlink } from "fs/promises";
 import path5 from "path";
 
 // src/plan-loop/external-review.ts
@@ -595,7 +814,8 @@ async function armExternalPlanReview(root, options = {}) {
     const emitOut = (s) => {
       if (!s) return;
       output += s;
-      process.stdout.write(s);
+      if (options.writeOut) options.writeOut(s);
+      else process.stdout.write(s);
     };
     const emitErr = (s) => {
       if (!s) return;
@@ -728,7 +948,7 @@ function createPersonaBannerPrinter(persona) {
 
 // src/plan-loop/sentinel.ts
 import { readFile as readFile3 } from "fs/promises";
-var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—\-].*)?)/i;
+var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—-].*)?)/i;
 function takeFromText(text) {
   if (!text) return null;
   const m = SENTINEL_RE.exec(text);
@@ -839,8 +1059,87 @@ async function resolveTickSentinel(lastResult, logPath, fromFile = parseSentinel
   return fromTurn ?? fromFile(logPath);
 }
 
+// src/plan-loop/usage-limit.ts
+var LIMIT_TEXT_RE = /\b(?:usage|rate)[ _-]?limit|\blimit (?:reached|exceeded)|\bquota (?:exceeded|reached)|\btoo many requests\b|\bout of (?:extra )?usage\b/i;
+var NON_LIMIT_STATUSES = /* @__PURE__ */ new Set(["allowed", "allowed_warning"]);
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function oneLine(text, max = 200) {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > max ? `${line.slice(0, max - 1)}\u2026` : line;
+}
+function fromRateLimitEvent(event) {
+  const info = isRecord(event.rate_limit_info) ? event.rate_limit_info : event;
+  const status = typeof info.status === "string" ? info.status : null;
+  if (!status || NON_LIMIT_STATUSES.has(status)) return null;
+  const parts = [status];
+  if (typeof info.rateLimitType === "string") parts.unshift(info.rateLimitType);
+  if (typeof info.resetsAt === "number" && Number.isFinite(info.resetsAt)) {
+    const ms = info.resetsAt < 1e12 ? info.resetsAt * 1e3 : info.resetsAt;
+    parts.push(`resets ${new Date(ms).toISOString()}`);
+  }
+  return { source: "rate_limit_event", detail: parts.join(" ") };
+}
+function fromErrorResult(event) {
+  if (event.is_error !== true) return null;
+  const texts = [];
+  if (typeof event.result === "string") texts.push(event.result);
+  if (typeof event.subtype === "string") texts.push(event.subtype);
+  if (Array.isArray(event.errors)) {
+    for (const e of event.errors) if (typeof e === "string") texts.push(e);
+  }
+  if (isRecord(event.error) && typeof event.error.message === "string") {
+    texts.push(event.error.message);
+  }
+  const hit = texts.find((t) => LIMIT_TEXT_RE.test(t));
+  return hit ? { source: "result", detail: oneLine(hit) } : null;
+}
+function fromCodexError(event) {
+  const message = isRecord(event.error) && typeof event.error.message === "string" ? event.error.message : typeof event.message === "string" ? event.message : "";
+  return LIMIT_TEXT_RE.test(message) ? { source: "result", detail: oneLine(message) } : null;
+}
+var PRIORITY = {
+  rate_limit_event: 3,
+  result: 2,
+  stderr: 1
+};
+function detectUsageLimit(logText) {
+  let last = null;
+  const take = (hit) => {
+    if (!last || PRIORITY[hit.source] >= PRIORITY[last.source]) last = hit;
+  };
+  for (const raw of logText.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (!line.startsWith("{")) {
+      if (LIMIT_TEXT_RE.test(line)) take({ source: "stderr", detail: oneLine(line) });
+      continue;
+    }
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(event)) continue;
+    const hit = event.type === "rate_limit_event" ? fromRateLimitEvent(event) : event.type === "result" ? fromErrorResult(event) : event.type === "turn.failed" || event.type === "error" || event.jsonrpc === "2.0" && isRecord(event.error) ? fromCodexError(event) : null;
+    if (hit) take(hit);
+  }
+  return last;
+}
+
 // src/plan-loop/run-loop.ts
 var TICK_PROMPT = '/run-plan - single tick from the headless runner (agent-kit run-plan). Read .cursor/HANDOFF.md and the active plan in .cursor/plans/. Mark the next to-do as in_progress in the frontmatter, execute ONLY that to-do, mark completed and update HANDOFF. If there is a commitable diff: run /git-staging without asking for confirmation. NEVER /git-prod. Do NOT re-arm an internal Loop skill - the external runner starts the next agent. End the response with exactly one line: "LOOP_TICK_RESULT: continue" if implementable to-dos remain, or "LOOP_TICK_RESULT: stop - <reason>" (plan exhausted, external blocker, or human decision needed).';
+function driverSentinel(sentinel) {
+  if (!sentinel) return null;
+  const line = formatSentinelLine(sentinel);
+  return {
+    kind: sentinel.kind,
+    ...sentinel.kind === "stop" ? { reason: sentinel.reason } : {},
+    line: line || null
+  };
+}
 async function runTickWithSpinner(label, backend, opts, plain) {
   if (shouldUseLiveTui({ plain })) {
     return withLiveTui(
@@ -884,60 +1183,119 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const stopFile = path5.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path5.join(opts.root, ".cursor", "loop-logs");
+  const statePaths = runnerStatePaths(opts.root);
+  const stopFile = statePaths.stopFile;
+  const logDir = statePaths.loopLogsDir;
+  let tick = 0;
+  let ticksRun = 0;
+  const driver = opts.events ? (() => {
+    const emitter = createDriverEmitter(opts.events.write, opts.events.now);
+    return {
+      emitter,
+      reader: createDriverAnswerReader({
+        input: opts.events.input,
+        emitter,
+        tick: () => tick
+      }),
+      writeErr: opts.events.writeErr ?? ((text) => {
+        process.stderr.write(text);
+      })
+    };
+  })() : null;
+  const say = (message, level = "info") => {
+    if (driver) driver.emitter.emit({ type: "log", level, message });
+    else if (level === "error") logger.error(message);
+    else console.log(message);
+  };
+  const emit = (event) => driver?.emitter.emit(event);
+  const finishRun = (exitCode, reason, pending2, planExhausted = false) => {
+    emit({ type: "run_end", exitCode, ticks: ticksRun, pending: pending2, reason, planExhausted });
+    driver?.reader.close();
+    return exitCode;
+  };
   const planPath = await resolveActivePlanPath(opts.root);
   if (!planPath) {
-    logger.error("No active plan in .cursor/plans/");
-    return 1;
+    say("No active plan in .cursor/plans/", "error");
+    return finishRun(1, "no active plan", null);
   }
   const pending = async () => countPendingTodos(await readPlan(planPath));
-  await mkdir(logDir, { recursive: true });
+  if (statePaths.invalid !== void 0) {
+    say(
+      `${STATE_ROOT_ENV}=${statePaths.invalid} is not supported (use .cursor or .agent-kit); using .cursor.`,
+      "warn"
+    );
+  }
+  await ensureLoopLogsDir(statePaths);
   try {
     await unlink(stopFile);
   } catch {
   }
   const onSigInt = () => {
-    console.log("");
-    console.log("Loop interrupted (Ctrl+C). State saved in HANDOFF by the last tick.");
+    if (driver) {
+      emit({
+        type: "run_end",
+        exitCode: 130,
+        ticks: ticksRun,
+        pending: null,
+        reason: "interrupted (SIGINT)",
+        planExhausted: false
+      });
+    } else {
+      console.log("");
+      console.log("Loop interrupted (Ctrl+C). State saved in HANDOFF by the last tick.");
+    }
     process.exit(130);
   };
   process.on("SIGINT", onSigInt);
   try {
-    const persona = await loadCliRunPlanPersona(opts.root);
+    const persona = driver ? null : await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path5.basename(planPath)}`);
-    console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
-    console.log(`Backend: ${opts.backend.id}`);
+    const pendingAtStart = await pending();
+    emit({
+      type: "run_start",
+      protocol: DRIVER_PROTOCOL_VERSION,
+      backend: opts.backend.id,
+      plan: path5.basename(planPath),
+      pending: pendingAtStart,
+      maxTicks: opts.maxTicks,
+      hitl: opts.noHitl ? "off" : "driver"
+    });
+    say(`Active plan: ${path5.basename(planPath)}`);
+    say(`Pending to-dos: ${pendingAtStart} | max ticks: ${opts.maxTicks}`);
+    say(`Backend: ${opts.backend.id}`);
     if (persona) {
-      console.log(`CLI persona: ${persona.displayName ?? persona.id}`);
+      say(`CLI persona: ${persona.displayName ?? persona.id}`);
     }
     if (opts.dryRun) {
-      console.log("--dry-run: no agent will be started. Tick prompt:");
-      console.log(TICK_PROMPT);
-      return 0;
+      say("--dry-run: no agent will be started. Tick prompt:");
+      say(TICK_PROMPT);
+      return finishRun(0, "dry-run", pendingAtStart);
     }
     const binary = await opts.backend.resolve();
     if (!binary) {
-      logger.error(`${opts.backend.id} not found on PATH`);
-      return 1;
+      say(`${opts.backend.id} not found on PATH`, "error");
+      return finishRun(1, `${opts.backend.id} not found on PATH`, pendingAtStart);
     }
-    let tick = 0;
     let stopReason;
     let planExhausted = false;
     let exitCode = 0;
+    let endReason = "";
+    let backend = opts.backend;
+    let limitSwitched = false;
     while (true) {
       tick += 1;
       if (tick > opts.maxTicks) {
         const msg = `Budget of ${opts.maxTicks} ticks reached - stopping. Run again to continue.`;
         if (banners) banners.stop(msg);
-        else console.log(msg);
+        else say(msg);
+        endReason = `budget of ${opts.maxTicks} ticks reached`;
         break;
       }
       if (await fileExists(stopFile)) {
         const msg = `Stop file found (${stopFile}) - stopping.`;
         if (banners) banners.stop(msg);
-        else console.log(msg);
+        else say(msg);
+        endReason = "stop file found";
         try {
           await rm(stopFile, { force: true });
         } catch {
@@ -946,81 +1304,159 @@ async function runPlanLoop(opts) {
       }
       const before = await pending();
       if (before === 0) {
-        console.log("Plan exhausted (0 pending to-dos) - nothing to do.");
+        say("Plan exhausted (0 pending to-dos) - nothing to do.");
         planExhausted = true;
+        endReason = "plan exhausted";
         break;
       }
       const logPath = path5.join(logDir, `tick-${stamp()}.log`);
       const relLog = path5.relative(opts.root, logPath);
-      console.log("");
+      if (!driver) console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
-      else console.log(tickLine);
+      else say(tickLine);
+      ticksRun = tick;
+      emit({
+        type: "tick_start",
+        tick,
+        maxTicks: opts.maxTicks,
+        pending: before,
+        log: relLog,
+        prompt: TICK_PROMPT,
+        backend: backend.id
+      });
       let agentExit = 0;
       let hitlStop;
       let lastResult;
+      let replies = [];
+      let limit = null;
+      const endTick = (pendingAfter, sentinel2) => emit({
+        type: "tick_end",
+        tick,
+        backend: backend.id,
+        limit,
+        exitCode: agentExit,
+        pendingBefore: before,
+        pendingAfter,
+        result: driverSentinel(sentinel2),
+        replies: replies.map(({ askId, reply, label, line, at }) => ({
+          askId,
+          reply,
+          label,
+          line,
+          at
+        })),
+        stop: hitlStop ? {
+          askId: hitlStop.askId,
+          cause: hitlStop.cause,
+          message: hitlStop.message,
+          exitCode: hitlStop.exitCode
+        } : null
+      });
       try {
-        const result = await runTickWithSpinner(
-          `tick ${tick}`,
-          opts.backend,
-          {
-            workspace: opts.root,
-            prompt: TICK_PROMPT,
-            model: opts.model,
-            logPath,
-            hitl: { policy: opts.noHitl ? "off" : "prompt" }
-          },
-          opts.plain === true
-        );
+        const runOpts = {
+          workspace: opts.root,
+          prompt: TICK_PROMPT,
+          model: opts.model,
+          logPath,
+          hitl: { policy: opts.noHitl ? "off" : "prompt" }
+        };
+        const result = driver ? await backend.run({
+          ...runOpts,
+          log: (line) => say(line),
+          render: new DriverAgentSink(driver.emitter, tick),
+          hitl: {
+            policy: opts.noHitl ? "off" : "driver",
+            readAnswer: driver.reader.read,
+            write: driver.writeErr
+          }
+        }) : await runTickWithSpinner(`tick ${tick}`, backend, runOpts, opts.plain === true);
         agentExit = result.exitCode;
-        for (const line of formatHitlSummary(result.hitl)) console.log(line);
+        for (const line of formatHitlSummary(result.hitl)) say(line);
         hitlStop = result.hitl?.stop;
+        replies = result.hitl?.replies ?? [];
         lastResult = result.lastResult;
       } catch (err) {
-        logger.error(String(err));
-        return 1;
+        say(String(err), "error");
+        agentExit = 1;
+        endTick(null, null);
+        return finishRun(1, `tick ${tick} failed to start: ${String(err)}`, await pending());
       }
       if (hitlStop) {
-        const msg = `${opts.backend.id} tick ended at a HITL gate without a reply - stopping. See log: ${relLog}`;
+        const msg = `${backend.id} tick ended at a HITL gate without a reply - stopping. See log: ${relLog}`;
         if (banners) {
           banners.tickEnd("hitl stop");
           banners.stop(msg);
         } else {
-          console.log(msg);
+          say(msg);
         }
+        endTick(await pending(), null);
         exitCode = hitlStop.exitCode;
+        endReason = hitlStop.message;
         break;
       }
+      let logText = "";
       try {
-        const logText = await readFile4(logPath, "utf8");
-        if (logText.includes("Too many MCP tools")) {
-          const msg = "Too many MCP tools for the headless model - disable servers (cursor-agent mcp disable <id>) and run again.";
-          if (banners) banners.stop(msg);
-          else console.log(msg);
-          break;
-        }
+        logText = await readFile4(logPath, "utf8");
       } catch {
       }
+      limit = detectUsageLimit(logText);
+      if (limit) {
+        const hit = limit;
+        const fallback = opts.onLimit && !limitSwitched && opts.onLimit.id !== backend.id ? opts.onLimit : null;
+        const fallbackBin = fallback ? await fallback.resolve() : null;
+        endTick(await pending(), null);
+        if (fallback && fallbackBin) {
+          const msg2 = `${backend.id} stopped on a usage limit (${hit.detail}); next tick continues the plan on ${fallback.id} (--on-limit). See log: ${relLog}`;
+          if (banners) banners.tickEnd("usage limit");
+          say(msg2, "warn");
+          backend = fallback;
+          limitSwitched = true;
+          continue;
+        }
+        const why = fallback ? ` (--on-limit ${fallback.id} not found on PATH)` : "";
+        const msg = `${backend.id} stopped on a usage limit (${hit.detail})${why} - stopping. The plan is unchanged: run again after the reset, or with --backend <other>. See log: ${relLog}`;
+        if (banners) {
+          banners.tickEnd("usage limit");
+          banners.stop(msg);
+        } else {
+          say(msg);
+        }
+        endReason = `usage-limit: ${backend.id}`;
+        break;
+      }
+      if (logText.includes("Too many MCP tools")) {
+        const msg = "Too many MCP tools for the headless model - disable servers (cursor-agent mcp disable <id>) and run again.";
+        if (banners) banners.stop(msg);
+        else say(msg);
+        endTick(await pending(), null);
+        endReason = "too many MCP tools";
+        break;
+      }
       const status = await resolveTickResultStatus(lastResult, logPath);
       if (status?.isError) {
         const detail = status.errors[0] ? `: ${status.errors[0].split("\n")[0]}` : "";
-        const msg = `${opts.backend.id} tick failed (${status.subtype ?? "is_error"}${detail}) - stopping. See log: ${relLog}`;
+        const msg = `${backend.id} tick failed (${status.subtype ?? "is_error"}${detail}) - stopping. See log: ${relLog}`;
         if (banners) {
           banners.tickEnd(status.subtype ?? "is_error");
           banners.stop(msg);
         } else {
-          console.log(msg);
+          say(msg);
         }
+        endTick(await pending(), null);
+        endReason = `tick failed (${status.subtype ?? "is_error"})`;
         break;
       }
       if (agentExit !== 0) {
-        const msg = `${opts.backend.id} exited with code ${agentExit} - stopping. See log: ${relLog}`;
+        const msg = `${backend.id} exited with code ${agentExit} - stopping. See log: ${relLog}`;
         if (banners) {
           banners.tickEnd(`exit ${agentExit}`);
           banners.stop(msg);
         } else {
-          console.log(msg);
+          say(msg);
         }
+        endTick(await pending(), null);
+        endReason = `${backend.id} exited with code ${agentExit}`;
         break;
       }
       const sentinel = await resolveTickSentinel(lastResult, logPath);
@@ -1028,45 +1464,58 @@ async function runPlanLoop(opts) {
       if (banners) {
         banners.tickEnd(`pending: ${after}`);
       }
+      endTick(after, sentinel);
       if (sentinel.kind === "continue") {
       } else if (sentinel.kind === "stop") {
-        console.log(`Agent requested stop: ${formatSentinelLine(sentinel)}`);
+        say(`Agent requested stop: ${formatSentinelLine(sentinel)}`);
         stopReason = sentinel.reason;
+        endReason = `agent requested stop: ${sentinel.reason}`;
         if (after === 0 || isPlanExhaustedReason(sentinel.reason)) {
           planExhausted = true;
         }
         break;
       } else if (after < before) {
-        console.log(
-          `warn: tick without sentinel, but progress (${before} -> ${after}) - continuing.`
+        say(
+          `warn: tick without sentinel, but progress (${before} -> ${after}) - continuing.`,
+          "warn"
         );
       } else {
         const msg = `Tick without sentinel and no progress (${before} -> ${after}) - stopping for safety.`;
         if (banners) banners.stop(msg);
-        else console.log(msg);
+        else say(msg);
+        endReason = "tick without sentinel and no progress";
         break;
       }
       if (after === 0) {
-        console.log("All to-dos completed. Suggesting /git-prod stays with the human (HITL).");
+        say("All to-dos completed. Suggesting /git-prod stays with the human (HITL).");
         planExhausted = true;
+        endReason = "plan exhausted";
         break;
       }
       if (opts.sleepSeconds > 0) {
         if (banners) banners.sleep(opts.sleepSeconds);
-        await withCliProgress(`sleep ${opts.sleepSeconds}s`, () => sleep(opts.sleepSeconds * 1e3));
+        if (driver) await sleep(opts.sleepSeconds * 1e3);
+        else
+          await withCliProgress(
+            `sleep ${opts.sleepSeconds}s`,
+            () => sleep(opts.sleepSeconds * 1e3)
+          );
       }
     }
     const pendingNow = await pending();
-    console.log("");
+    if (!driver) console.log("");
     const finishDetail = `after ${tick} tick(s); pending: ${pendingNow}`;
     if (banners) banners.phaseComplete(finishDetail);
-    console.log(
+    say(
       `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path5.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
-      await armExternalPlanReview(opts.root);
+      await armExternalPlanReview(
+        opts.root,
+        driver ? { log: (line) => say(line), writeOut: driver.writeErr } : {}
+      );
     }
-    return exitCode;
+    return finishRun(exitCode, endReason || "stopped", pendingNow, planExhausted);
   } finally {
     process.off("SIGINT", onSigInt);
   }
@@ -1077,5 +1526,6 @@ export {
   withLiveTui,
   listDetectBackendIds,
   detectAgentBackend,
+  DRIVER_EVENTS_FORMATS,
   runPlanLoop
 };