@inetafrica/open-claudia 3.5.19 → 3.5.23

package/core/tool-guard.js

@@ -659,6 +659,340 @@ function hookFailure(toolName, reason) {
   };
 }
 
+// ── Browser app: the bot pauses while a person drives (bot apps v1, C7) ────
+// While someone drives the bot's browser from Kazee Chat, the driver lock file
+// (core/browser-lock.js) is live, and the bot's own agent-browser commands
+// would fight their clicks. So an agent-browser call at a command position is
+// refused, except the read-only ones: get, snapshot, screenshot, session list.
+// A command position is the start of a command: the start of the line, or
+// after ; & | && || ( $( a backtick or a newline, behind env assignments
+// (FOO=1), shell words (if, then, do, !, {) and wrappers (npx, sudo, env,
+// timeout, nice, xargs...). What a shell runs from a string is read the same
+// way: bash/sh -c '...', eval, a heredoc or here-string fed to a shell, and
+// $(...) or backticks, inside double quotes too. Any other string is data, so
+// `echo "agent-browser click"`, `grep agent-browser`, a commit message or a
+// heredoc written to a file never match. An expired lock never blocks, and any
+// error here allows: this is a pause for a person's sake, not a security gate.
+const AGENT_BROWSER_READ_ONLY = new Set(["get", "snapshot", "screenshot"]);
+const AGENT_BROWSER_VALUE_FLAGS = new Set([
+  "--session", "--restore-save", "--restore-check-url", "--restore-check-text", "--restore-check-fn",
+  "--namespace", "--session-name", "--profile", "--state", "--headers", "--executable-path", "--extension",
+  "--init-script", "--enable", "--args", "--user-agent", "--proxy", "--proxy-bypass", "--ca-cert",
+  "--hide-scrollbars", "-p", "--provider", "--device", "--threshold", "--screenshot-dir", "--screenshot-quality",
+  "--screenshot-format", "--cdp", "--color-scheme", "--download-path", "--max-output", "--allowed-domains",
+  "--action-policy", "--confirm-actions", "--engine", "--input-mode", "--idle-timeout", "--model", "--config",
+  "--port", "--allowed-origins",
+]);
+// agent-browser, agent-browser.js, agent-browser@latest, agent-browser-linux-x64...
+const AGENT_BROWSER_BIN = /^agent-browser(?:$|[.@-])/;
+const SHELL_WORDS = new Set(["!", "{", "if", "then", "else", "elif", "do", "while", "until"]);
+const SHELLS = new Set(["sh", "bash", "zsh", "dash", "ksh", "ash", "mksh", "fish"]);
+// Wrappers that run the command after them, with their options that take a value.
+const COMMAND_WRAPPERS = new Map([
+  ["sudo", ["-u", "-g", "-C", "-h", "-p", "-r", "-t", "-U", "-D", "-R", "-T", "--user", "--group", "--host", "--prompt", "--role", "--type", "--other-user", "--chdir", "--chroot", "--command-timeout", "--close-from"]],
+  ["doas", ["-u", "-C"]],
+  ["env", ["-u", "-C", "-S", "--unset", "--chdir", "--split-string"]],
+  ["command", []], ["builtin", []], ["exec", ["-a"]], ["nohup", []], ["setsid", []],
+  ["time", ["-f", "-o", "--format", "--output"]],
+  ["nice", ["-n", "--adjustment"]],
+  ["timeout", ["-s", "-k", "--signal", "--kill-after"]],
+  ["stdbuf", ["-i", "-o", "-e", "--input", "--output", "--error"]],
+  ["xargs", ["-I", "-n", "-L", "-P", "-d", "-E", "-s", "-a", "--max-args", "--max-lines", "--max-procs", "--delimiter", "--eof", "--max-chars", "--arg-file"]],
+  ["npx", ["-p", "--package", "-c", "--call"]],
+  ["pnpx", ["-p", "--package"]],
+  ["bunx", ["-p", "--package"]],
+]);
+// Wrapper options whose value is itself a command line: npx -c, env -S.
+const WRAPPER_SCRIPT_OPTIONS = new Set(["-c", "--call", "-S", "--split-string"]);
+const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+const baseName = (word) => String(word).split("/").pop();
+
+// Where $( ... ) that opens at `start` (just after "$(") closes: the index of
+// its ")", or the end of the text. Nested parentheses and quotes are skipped.
+function substitutionEnd(s, start) {
+  let depth = 1;
+  let i = start;
+  while (i < s.length) {
+    const c = s[i];
+    if (c === "\\") { i += 2; continue; }
+    if (c === "'") { const end = s.indexOf("'", i + 1); i = end < 0 ? s.length : end + 1; continue; }
+    if (c === '"') {
+      let j = i + 1;
+      while (j < s.length && s[j] !== '"') j += s[j] === "\\" ? 2 : 1;
+      i = j + 1;
+      continue;
+    }
+    if (c === "(") depth += 1;
+    else if (c === ")") { depth -= 1; if (depth === 0) return i; }
+    i += 1;
+  }
+  return s.length;
+}
+
+// The commands of a shell command line, the way a shell splits them: each is
+// { words, input } with quotes removed, redirection targets and comments left
+// out, and `input` the heredoc bodies and here-strings it reads. `nested` holds
+// the text of every $(...) and backtick, which the shell also runs.
+function shellCommands(command) {
+  const s = String(command || "");
+  const commands = [];
+  const nested = [];
+  let words = [];
+  let input = [];
+  let word = null;
+  let target = false; // the next word is a redirection's file or descriptor
+  let hereString = false; // the next word is a here-string (<<<)
+  let heredocs = []; // heredocs whose bodies start after the next newline
+  const endWord = () => {
+    if (word === null) return;
+    if (target) target = false;
+    else if (hereString) { hereString = false; input.push(word); }
+    else words.push(word);
+    word = null;
+  };
+  const endCommand = () => {
+    endWord();
+    if (words.length) commands.push({ words, input });
+    words = [];
+    input = [];
+    target = false;
+    hereString = false;
+  };
+  const backtick = (i) => {
+    let j = i + 1;
+    while (j < s.length && s[j] !== "`") j += s[j] === "\\" ? 2 : 1;
+    nested.push(s.slice(i + 1, Math.min(j, s.length)));
+    return j + 1;
+  };
+  let i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (c === "\\") {
+      if (s[i + 1] === "\n") { i += 2; continue; } // a line continuation
+      if (i + 1 < s.length) word = (word || "") + s[i + 1];
+      i += 2;
+      continue;
+    }
+    if (c === "#" && word === null) { // a comment, to the end of the line
+      while (i < s.length && s[i] !== "\n") i += 1;
+      continue;
+    }
+    if (c === "'") {
+      const end = s.indexOf("'", i + 1) < 0 ? s.length : s.indexOf("'", i + 1);
+      word = (word || "") + s.slice(i + 1, end);
+      i = end + 1;
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      let text = "";
+      while (j < s.length && s[j] !== '"') {
+        if (s[j] === "\\" && j + 1 < s.length) {
+          if (s[j + 1] !== "\n") text += /[$`"\\]/.test(s[j + 1]) ? s[j + 1] : s[j] + s[j + 1];
+          j += 2;
+          continue;
+        }
+        if (s[j] === "$" && s[j + 1] === "(") {
+          const end = substitutionEnd(s, j + 2);
+          nested.push(s.slice(j + 2, end));
+          text += s.slice(j, end + 1);
+          j = end + 1;
+          continue;
+        }
+        if (s[j] === "`") {
+          const after = backtick(j);
+          text += s.slice(j, after);
+          j = after;
+          continue;
+        }
+        text += s[j];
+        j += 1;
+      }
+      word = (word || "") + text;
+      i = j + 1;
+      continue;
+    }
+    if (c === "`") {
+      const after = backtick(i);
+      word = (word || "") + s.slice(i, after);
+      i = after;
+      continue;
+    }
+    if (c === "$" && s[i + 1] === "(") {
+      const end = substitutionEnd(s, i + 2);
+      nested.push(s.slice(i + 2, end));
+      word = (word || "") + s.slice(i, end + 1);
+      i = end + 1;
+      continue;
+    }
+    if (c === "<" && s.startsWith("<<<", i)) { endWord(); hereString = true; i += 3; continue; }
+    if (c === "<" && s[i + 1] === "<") { // a heredoc: its body follows the next newline
+      endWord();
+      i += 2;
+      const strip = s[i] === "-";
+      if (strip) i += 1;
+      while (s[i] === " " || s[i] === "\t") i += 1;
+      let delim = "";
+      while (i < s.length && !/[\s;&|<>()]/.test(s[i])) {
+        if (s[i] === "'" || s[i] === '"') {
+          const q = s[i];
+          const end = s.indexOf(q, i + 1) < 0 ? s.length : s.indexOf(q, i + 1);
+          delim += s.slice(i + 1, end);
+          i = end + 1;
+        } else {
+          if (s[i] !== "\\") delim += s[i];
+          i += 1;
+        }
+      }
+      if (delim) heredocs.push({ delim, strip, input });
+      continue;
+    }
+    if (c === "<" || c === ">") { // a redirection: the word after it is a file, not an argument
+      if (word !== null && /^\d+$/.test(word)) word = null; // the descriptor of 2>, 1>&...
+      endWord();
+      i += /[>&|]/.test(s[i + 1] || "") ? 2 : 1;
+      target = true;
+      continue;
+    }
+    if (c === "\n" || c === "\r") {
+      endCommand();
+      i += 1;
+      if (c === "\n" && heredocs.length) {
+        for (const doc of heredocs) {
+          const body = [];
+          while (i < s.length) {
+            const eol = s.indexOf("\n", i) < 0 ? s.length : s.indexOf("\n", i);
+            let line = s.slice(i, eol);
+            if (doc.strip) line = line.replace(/^\t+/, "");
+            i = eol + 1;
+            if (line === doc.delim) break;
+            body.push(line);
+          }
+          doc.input.push(body.join("\n"));
+        }
+        heredocs = [];
+      }
+      continue;
+    }
+    if (/[;&|()]/.test(c)) { endCommand(); i += 1; continue; }
+    if (/\s/.test(c)) { endWord(); i += 1; continue; }
+    word = (word || "") + c;
+    i += 1;
+  }
+  endCommand();
+  return { commands, nested };
+}
+
+// The index of the command's own name, behind env assignments, shell words and
+// wrappers with their options (-1 when there is none). A wrapper option whose
+// value is a command line (npx -c, env -S) is added to `scripts`.
+function commandWordIndex(words, scripts) {
+  let k = 0;
+  for (let guard = 0; guard < 16 && k < words.length; guard += 1) {
+    const w = words[k];
+    if (ENV_ASSIGNMENT.test(w) || SHELL_WORDS.has(w)) { k += 1; continue; }
+    const name = baseName(w);
+    const valueOptions = COMMAND_WRAPPERS.get(name);
+    if (!valueOptions) return k;
+    k += 1;
+    let positional = name === "timeout" ? 1 : 0; // timeout DURATION command
+    while (k < words.length) {
+      const arg = words[k];
+      if (arg === "--") { k += 1; break; }
+      if (name === "env" && ENV_ASSIGNMENT.test(arg)) { k += 1; continue; }
+      if (arg.length > 1 && arg.startsWith("-")) {
+        if (valueOptions.includes(arg)) {
+          if (WRAPPER_SCRIPT_OPTIONS.has(arg) && words[k + 1] !== undefined) scripts.push(words[k + 1]);
+          k += 2;
+        } else {
+          k += 1;
+        }
+        continue;
+      }
+      if (positional > 0) { positional -= 1; k += 1; continue; }
+      break;
+    }
+  }
+  return k < words.length ? k : -1;
+}
+
+// agent-browser's subcommand and the word after it (sub is null when there is
+// none, e.g. --help or --version).
+function agentBrowserCall(words, at) {
+  let j = at + 1;
+  while (j < words.length) {
+    const arg = words[j];
+    if (arg === "--") { j += 1; continue; }
+    if (arg.startsWith("-")) {
+      if (!arg.includes("=") && AGENT_BROWSER_VALUE_FLAGS.has(arg)) j += 2;
+      else j += /^(true|false)$/.test(words[j + 1] || "") ? 2 : 1; // boolean flags take an optional true/false
+      continue;
+    }
+    return { sub: arg, sub2: words[j + 1] === undefined ? null : words[j + 1] };
+  }
+  return { sub: null, sub2: null };
+}
+
+// Every agent-browser invocation in a command: [{ sub, sub2 }].
+function agentBrowserInvocations(command, depth = 0) {
+  const calls = [];
+  if (depth > 4) return calls;
+  const { commands, nested } = shellCommands(command);
+  const scripts = [...nested];
+  for (const { words, input } of commands) {
+    const at = commandWordIndex(words, scripts);
+    if (at < 0) continue;
+    const name = baseName(words[at]);
+    if (AGENT_BROWSER_BIN.test(name)) {
+      calls.push(agentBrowserCall(words, at));
+    } else if (name === "eval") {
+      scripts.push(words.slice(at + 1).join(" "));
+    } else if (SHELLS.has(name)) {
+      // sh -c '<script>' [name args], else the script a shell reads from its heredoc/here-string.
+      let script = null;
+      for (let j = at + 1; j < words.length; j += 1) {
+        const w = words[j];
+        if (/^-[A-Za-z]*c[A-Za-z]*$/.test(w)) {
+          script = words.slice(j + 1).find((x) => !x.startsWith("-"));
+          break;
+        }
+        if (w === "-o" || w === "+o" || w === "-O" || w === "+O") { j += 1; continue; }
+        if (!w.startsWith("-") && !w.startsWith("+")) break; // a script file
+      }
+      if (script != null) scripts.push(script);
+      else scripts.push(...input);
+    }
+  }
+  for (const script of scripts) calls.push(...agentBrowserInvocations(script, depth + 1));
+  return calls;
+}
+
+function readOnlyBrowserCall(call) {
+  if (!call.sub) return true; // no subcommand: usage or version
+  if (AGENT_BROWSER_READ_ONLY.has(call.sub)) return true;
+  return call.sub === "session" && call.sub2 === "list";
+}
+
+// null, or { subcommand, message } when a live driver lock refuses this command.
+function browserDriverDenial(command, now = Date.now()) {
+  try {
+    const cmd = String(command || "");
+    if (!cmd.includes("agent-browser")) return null;
+    const lock = require("./browser-lock").liveLock(now);
+    if (!lock) return null;
+    const blocked = agentBrowserInvocations(cmd).find((call) => !readOnlyBrowserCall(call));
+    if (!blocked) return null;
+    const name = String(lock.name || "").replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 60) || "Someone";
+    return {
+      subcommand: String(blocked.sub || "").slice(0, 40),
+      message: `${name} is driving the browser right now. Wait for them to hand it back; you will be woken in their chat when they do.`,
+    };
+  } catch (e) {
+    return null;
+  }
+}
+
 // Claude sends the shell command as a string; accept an argv array too.
 function shellCommandOf(input) {
   if (!input || typeof input !== "object") return null;
@@ -727,6 +1061,14 @@ function runHook(payload) {
       logGuardEvent({ kind: "deny", rule: "external-secret-read", pattern: secretDenial.rule, command: String(command).slice(0, 300) });
       return { exit: 2, stderr: secretDenial.message };
     }
+    // A person is driving the browser (Browser app): ahead of the tooling-mode
+    // switch, so relaxed mode cannot drive over them either. Only the
+    // subcommand is logged: the bot's own fill/type commands can carry text.
+    const driving = browserDriverDenial(command);
+    if (driving) {
+      logGuardEvent({ kind: "deny", rule: "browser-driver", subcommand: driving.subcommand });
+      return { exit: 2, stderr: driving.message };
+    }
     // Relaxed tooling mode: the gate observes but never blocks. The event is
     // still logged (as relaxed-pass, not deny) so the dream KPI can report
     // what WOULD have been denied — visibility survives the mode switch.
@@ -761,4 +1103,5 @@ module.exports = {
   externalFileMutationDenial, externalControlPlaneDenial, guardedSpeakerFromEnv,
   protectedReadRoots, isProtectedReadPath, isProtectedSearchRoot, secretReadRule,
   matchRawOp, noteRawOp, readGuardEvents,
+  agentBrowserInvocations, browserDriverDenial,
 };

package/core/turn-journal.js

@@ -25,6 +25,9 @@
 //     (6) on SIGTERM, whose sender kills soon after; whatever is still
 //     running stays journaled.
 //   - /stop offers each dropped queued message back with a "Run it" button.
+//   - /stop marks the conversation "stopped" (kept across a restart): its next
+//     turn is told the stopped request is cancelled, not cut off (see
+//     markStopped).
 // Scheduled runs (wake-ups, crons, watches) are not journaled: jobs.json keeps
 // their own retry, so they are never resumed twice.
 
@@ -78,7 +81,7 @@ function remove(file) { try { fs.unlinkSync(file); } catch (_) {} }
 
 // Persist the record, or drop the file when nothing is left in it.
 function store(file, record) {
-  if (!record.turn && !(record.queued || []).length) return remove(file);
+  if (!record.turn && !(record.queued || []).length && !record.stopped) return remove(file);
   write(file, record);
 }
 
@@ -164,6 +167,8 @@ function begin(runContext, opts = {}) {
     },
     queued: (existing.queued || []).filter((q) => q.runId !== runContext.runId),
   };
+  // A stop this turn has not taken yet stays for the turn that does.
+  if (existing.stopped) record.stopped = existing.stopped;
   try { write(file, record); } catch (error) { console.warn(`[turn-journal] could not journal ${runContext.laneKey}: ${error.message}`); return false; }
   active.set(runContext.laneKey, file);
   ensureHeartbeat();
@@ -205,6 +210,52 @@ function dropQueued(laneKey, runIds) {
   store(file, record);
 }
 
+// ── /stop: a cancel, not a cut ─────────────────────────────────────────
+// /stop kills the provider mid-turn. On the next message Claude Code resumes
+// the session and writes the cut turn into the history the same way a
+// restart's cut reads ("[Request interrupted by user for tool use]", then
+// "Continue from where you left off." / "No response requested."), and the
+// system prompt says to finish work a restart cut off. So a stopped request
+// came back on the next message (home pi, 9 Oct: "/stop" on "ok play big
+// bang", then "Big Bang didn't start … just say if you still want it"). The
+// stop is kept in the conversation's file until its next turn takes it.
+function markStopped(laneKey, opts = {}) {
+  if (!journalOn() || !laneKey) return false;
+  const file = fileFor(laneKey);
+  const record = read(file) || { v: 1, conversation: null, turn: null, queued: [] };
+  if (!record.conversation && opts.runContext?.origin) record.conversation = conversationOf(opts.runContext);
+  record.stopped = {
+    at: Number.isFinite(opts.now) ? opts.now : Date.now(),
+    runId: opts.runContext?.runId || null,
+  };
+  try { write(file, record); } catch (_) { return false; }
+  return true;
+}
+
+// The conversation's stop, once: the turn that takes it carries the note.
+function takeStopped(laneKey) {
+  if (!journalOn() || !laneKey) return null;
+  const file = fileFor(laneKey);
+  const record = read(file);
+  if (!record?.stopped) return null;
+  const stopped = record.stopped;
+  delete record.stopped;
+  try { store(file, record); } catch (_) {}
+  return stopped;
+}
+
+// /new, /end or a project change: the stopped turn's history is gone.
+function clearStopped(laneKey) {
+  takeStopped(laneKey);
+}
+
+// What the turn after a /stop reads before the person's message.
+function stoppedNote(stopped) {
+  const at = Number(stopped?.at);
+  const when = Number.isFinite(at) && at > 0 ? `At ${hhmm(at)} the person` : "The person";
+  return `[${when} stopped your previous turn with /stop, so that request is cancelled. Your history may still show it unfinished, followed by "Continue from where you left off." from the agent CLI (not from them). Don't resume it, redo it or offer to do it again unless they ask; just answer the message below.]`;
+}
+
 function list() {
   if (!journalOn()) return [];
   let names = [];
@@ -337,7 +388,8 @@ async function resumeInterrupted(adapters, overrides = {}) {
     if (!turn) {
       const queued = record.queued || [];
       record.queued = [];
-      remove(file);
+      // A stop not yet taken stays (the restored messages' turn takes it).
+      store(file, record);
       runQueued({ ...record, queued }, adapter, deps);
       out.restored += queued.length;
       continue;
@@ -502,6 +554,7 @@ module.exports = {
   conversationOf, chatScope, findAdapter, defaultDeps,
   resumeInterrupted, handleResumeAction, RESUME_PROMPT,
   rememberDropped, droppedKeyboard, handleRunDropped,
+  markStopped, takeStopped, clearStopped, stoppedNote,
   drain, exitAfterDrain, isDraining, markShuttingDown,
   resumeEnabled, maxAgeMs, drainTimeoutMs, sigtermDrainTimeoutMs, MAX_ATTEMPTS, HEARTBEAT_MS,
   _resetForTests,

package/core/usage-limits.js

@@ -302,9 +302,119 @@ function limitHitDetails({ provider, error, rateLimit = null, windows = [], now
   };
 }
 
+// ---------------------------------------------------------------------------
+// Waiting for a reset: one rule and one record for every kind of work
+// (Sumeet, 9 Oct 2026: a used-up limit is handled the same way everywhere,
+// as a runtime concept, not a fix per feature).
+//
+//   - limitRetryAt() is when work a limit stopped runs again: a chat message
+//     (core/limit-pickup), a scheduled run (core/scheduler), the dream's AI
+//     step (core/dream). Never another provider: the other one may not be
+//     signed in or may be used up too.
+//   - noteLimitHit() records that a provider is used up until its reset,
+//     from any run a limit stopped; a run that works clears it
+//     (clearLimitBlock). Background calls read it (limitBlock) and do not
+//     start a used-up provider again and again. Chat turns never read it:
+//     they always try, so the provider stays the judge.
+
+function setting(name) {
+  if (process.env[name] !== undefined) return process.env[name];
+  return config[name];
+}
+
+// Wait this long after the reset, so the provider's window has turned over.
+function limitRetryDelayMs() {
+  const n = Number(setting("LIMIT_PICKUP_DELAY_S"));
+  return (Number.isFinite(n) && n >= 0 ? n : 120) * 1000;
+}
+
+// A reset further out than this (a monthly spend cap) is not waited for.
+function limitMaxWaitMs() {
+  const n = Number(setting("LIMIT_PICKUP_MAX_WAIT_H"));
+  return (Number.isFinite(n) && n > 0 ? n : 192) * 3600000;
+}
+
+/** When work a limit stopped should run again; null when the reset is not known. */
+function limitRetryAt(resetsAt, { now = Date.now() } = {}) {
+  if (!Number.isFinite(resetsAt) || resetsAt <= now - 6 * 3600000) return null;
+  return Math.max(resetsAt, now) + limitRetryDelayMs();
+}
+
+/** Whether a wait until `runAt` is short enough to wait for. */
+function canWaitFor(runAt, { now = Date.now() } = {}) {
+  return Number.isFinite(runAt) && runAt - now <= limitMaxWaitMs();
+}
+
+function liveFile(file) {
+  // A test run that did not point the config dir somewhere else never touches
+  // the live bot's file.
+  return !(file === DEFAULT_FILE && process.env.OPEN_CLAUDIA_TEST === "1" && !process.env.OPEN_CLAUDIA_CONFIG_DIR);
+}
+
+// A model-family limit (Claude's weekly Opus or Sonnet limit) stops only that
+// family; an unknown model counts as stopped.
+function blocksModel(limitType, model) {
+  const family = /opus|sonnet|fable|haiku/i.exec(String(limitType || ""));
+  if (!family || !model) return true;
+  return String(model).toLowerCase().includes(family[0].toLowerCase());
+}
+
+/** Record that `provider` is used up until `resetsAt` (a run hit its limit). */
+function noteLimitHit({ provider, limitType = null, resetsAt, file = DEFAULT_FILE, now = Date.now() } = {}) {
+  if (!provider || !Number.isFinite(resetsAt) || resetsAt <= now || !liveFile(file)) return null;
+  return withFileLock(file, () => {
+    const state = readState(file);
+    if (!state.blocks || typeof state.blocks !== "object") state.blocks = {};
+    const previous = state.blocks[provider];
+    const block = {
+      limitType: limitType || null,
+      resetsAt,
+      since: previous && previous.resetsAt > now ? previous.since : new Date(now).toISOString(),
+      updatedAt: new Date(now).toISOString(),
+    };
+    state.blocks[provider] = block;
+    atomicWriteFileSync(file, JSON.stringify(state, null, 2) + "\n");
+    return { provider, ...block };
+  });
+}
+
+/** The limit `provider` is used up on now, or null. `model` narrows a model-family limit. */
+function limitBlock(provider, { model = null, file = DEFAULT_FILE, now = Date.now() } = {}) {
+  if (!provider || !liveFile(file)) return null;
+  const block = readState(file).blocks?.[provider];
+  if (!block || !Number.isFinite(block.resetsAt) || block.resetsAt <= now) return null;
+  if (!blocksModel(block.limitType, model)) return null;
+  return { provider, ...block };
+}
+
+/**
+ * A run on `provider` worked: it is not used up (any more). A run on a model
+ * a model-family limit does not cover proves nothing about that limit.
+ */
+function clearLimitBlock(provider, { model = null, file = DEFAULT_FILE } = {}) {
+  if (!provider || !liveFile(file)) return false;
+  // Read first: almost every run finds nothing to clear and writes nothing.
+  const found = readState(file).blocks?.[provider];
+  if (!found || !blocksModel(found.limitType, model)) return false;
+  return withFileLock(file, () => {
+    const state = readState(file);
+    if (!state.blocks?.[provider]) return false;
+    delete state.blocks[provider];
+    atomicWriteFileSync(file, JSON.stringify(state, null, 2) + "\n");
+    return true;
+  });
+}
+
 module.exports = {
   DEFAULT_FILE,
   DEFAULT_WARN_PERCENTS,
+  limitRetryDelayMs,
+  limitMaxWaitMs,
+  limitRetryAt,
+  canWaitFor,
+  noteLimitHit,
+  limitBlock,
+  clearLimitBlock,
   warnPercents,
   providerLabel,
   windowLabel,