@inetafrica/open-claudia 3.5.17 → 3.5.18

package/.env.example

@@ -70,6 +70,16 @@ USAGE_ALERT_RATE_MULTIPLIER=1.75
 USAGE_ALERT_BASELINE_TURNS=20
 USAGE_ALERT_MIN_BASELINE_TURNS=6
 USAGE_ALERT_COOLDOWN_MS=1800000
+# Plan limits (Claude Pro/Max, the ChatGPT plan behind Codex). Warn in the chat
+# when a window's use passes these percentages, once per window (off = never).
+LIMIT_WARN_PERCENTS=80,95
+# A message a usage limit stopped is picked up when the limit resets, unless
+# the person writes again first: on (default) | off.
+LIMIT_PICKUP=on
+# Seconds after the reset before it runs (default 120); a reset further out
+# than LIMIT_PICKUP_MAX_WAIT_H hours (default 192) is not waited for.
+LIMIT_PICKUP_DELAY_S=120
+LIMIT_PICKUP_MAX_WAIT_H=192
 MEMORY_RECALL_MAX_CHARS=9000
 # Default recall engine when a chat hasn't picked one with /engine: classic | discoverer
 RECALL_ENGINE=classic

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 3.5.18
+
+Usage limits (Sumeet, 7 Oct 15:00 EAT: "track usage and notify the user that they are going to hit their limit, if the limit is hit can the bot auto schedule to continue when the limit replenishes"; 15:14 EAT: "if the user sends it a message it cancels and if the session limit message comes up again it will just rearm").
+
+- **A message a usage limit stopped is picked up when the limit resets.** When Claude's 5-hour or weekly limit (or Codex's plan limit) stops a chat turn, the bot says which limit and when it resets ("⏳ Claude's weekly limit is used up, so I stopped here. I'll pick your message back up on Fri 9 Oct at 08:02, when it resets. If you write to me before then, I'll answer that instead and drop this.") and runs the message again 2 minutes after the reset (`LIMIT_PICKUP_DELAY_S`), in the same conversation, as the person who sent it, with "check what you already did; never repeat a send, push, deploy or write". One pick-up per person per conversation, kept in `limit-pickups.json` so it survives a restart. The person writing again in that conversation drops it (also when the guard holds that message), as do `/stop`, `/new` and `/end`; another person in a group does not. A run that hits a limit again arms it again with the same message, at most 5 times. Resets further out than `LIMIT_PICKUP_MAX_WAIT_H` (192 h) are not waited for. `LIMIT_PICKUP=off` only says when the limit resets. An unasked group reply that hits a limit posts nothing.
+- **The limit notice is never the reply.** Claude Code words a plan limit "You've hit your limit / session limit / weekly limit · resets …", which the old checks missed: the bot posted "Claude Code run failed: You've hit your session limit · resets 11:30am (Africa/Nairobi)", or the bare notice as if it were the answer (the tickets bot to a staff member, 7 Oct). The limit is now read from Claude Code's `rate_limit_event` (status `rejected`, the reset time) and its synthetic `rate_limit` message, which never streams as answer text; Codex's "You've hit your usage limit … try again at …" was already caught. The reset time comes from the event, else Codex's rollout, else the notice's own words.
+- **Warnings at 80% and 95%.** Claude Code reports each window's use on every run (`rate_limit_event.unifiedWindows`, a 0-1 fraction per 5-hour and weekly window); Codex in its rollout (its windows are named by length: on a Pro account the main one is weekly). After the reply that takes a window past 80% or 95%, the chat gets "⚠️ Claude: 82% of the 5-hour limit is used. It resets at 17:20." Once per window per percentage (`LIMIT_WARN_PERCENTS`, `off` for none); never to an outside contact, on a call or for an unasked group reply. Claude Code's own `allowed_warning` status is a pace warning (25% early in the week) and is not used.
+- **/usage shows the plan limits** ("Claude plan limits: 5-hour 57% (resets 17:20) · weekly 26% (resets Wed 14 Oct, 08:00)") and the waiting pick-up in this conversation.
+- **Tests:** `test-usage-limits.js`, `test-limit-pickup.js` (new); `test-provider-events.js`; the fake agent CLI gains a `usage-limit` scenario and `FAKE_AGENT_RATE_LIMIT_INFO`.
+
+Token diet for every bot (Sumeet, 8 Oct 08:19 EAT: "Let's roll it out to the fleet if we already seeing savings?"). On the owner's bot the 3.5.17 canary cut a typical reply from $8.72 to $4.03, and the cost per reply with compactions included by 48%, over 82 replies.
+
+- **The token diet is on by default.** Every conversation compacts at 200k, and before a cold resume over 120k, as listed conversations did in 3.5.17. `TOKEN_DIET_CONVERSATIONS=off` turns it off; a list of conversation keys still limits it to those.
+- **The compaction summary no longer dies on a tool call.** Claude runs it with `--max-turns 1`, and its prompt never said not to use tools: a model that checked a fact first used up the one turn and left no brief (4 of 24 compactions on 7-8 Oct, $35 for nothing). The prompt now says so, and a threshold compaction that does not complete logs why.
+- **A scheduled job's own conversation gets the same cap.** A watch, cron or wakeup resumes the conversation it was made in; once its thread had moved on, nothing compacted that conversation (the Kazee Bugs monitor's grew to 894k, $55 a wake). It is now compacted like its thread, before a cold run and after a run past the threshold, without touching the thread's live session. The usage ledger marks these compactions `scope: "job"`.
+- **Jobs follow their compactions.** The completed-compactions index keeps only the last 20, which the token diet fills in under a day, so jobs lost their way and resumed old, huge conversations (the PBX thread's wakeup and watch: 790k, $86 for two runs). The scheduler now also reads the lineage in the session history, and a recurring job remembers the session it last ran on.
+- **Tests:** `test-token-diet.js` (the default; job conversations end to end through the scheduler), `test-provider-compaction.js` (branch commit, the no-tools summary), `test-provider-scheduler.js` (history lineage, a job keeps its session); `test-usage-accounting.js` pins the classic thresholds with the diet off.
+
 ## 3.5.17
 
 One combined release (Sumeet, 7 Oct 09:21 EAT): Release 1 below, the 7 Oct security fixes, and the dashboard and provider fixes found on 6 Oct. What people will notice: Codex bots start answering in groups when a message concerns them (their checks failed before), a file over 200 MB sent to a bot is refused, and a /dashboard link opens a Continue page first.

package/README.md

@@ -453,6 +453,9 @@ All stored in `~/.open-claudia/`:
 | `USAGE_ALERT_CONTEXT_TOKENS` | No | With alerts on: alert when one completed turn's context tokens exceed this ceiling (default `120000`, `off` disables) |
 | `USAGE_ALERT_RATE_MULTIPLIER` | No | With alerts on: alert when the latest context-token rate exceeds the recent baseline by this multiple (default `1.75`, `off` disables) |
 | `USAGE_ALERT_BASELINE_TURNS` / `USAGE_ALERT_MIN_BASELINE_TURNS` / `USAGE_ALERT_COOLDOWN_MS` | No | Tune token-rate baseline size, minimum sample size, and alert cooldown |
+| `LIMIT_WARN_PERCENTS` | No | Plan-limit warnings in the chat: comma-separated percentages of a 5-hour or weekly window (default `80,95`, `off` disables). Each is said once per window, after the reply that crossed it; never to an outside contact |
+| `LIMIT_PICKUP` | No | `on` (default) or `off`. A message a Claude or Codex usage limit stopped is picked up when the limit resets; the person writing again in that conversation, `/stop`, `/new` or `/end` drops it, and a new limit hit arms it again |
+| `LIMIT_PICKUP_DELAY_S` / `LIMIT_PICKUP_MAX_WAIT_H` | No | Seconds after the reset before the pick-up runs (default `120`); resets further out than this many hours (default `192`) are not waited for |
 | `MEMORY_RECALL_MAX_CHARS` | No | Hard cap for auto-injected pack/entity memory per turn (default `9000`, `off` disables auto recall injection) |
 | `RECALL_ENGINE` | No | Default recall engine when a chat hasn't set one via `/engine` (`classic` or `discoverer`, default `discoverer`) |
 | `RECALL_GRAPH_DB` / `RECALL_METRICS` | No | Override the discoverer graph DB path; `off` on metrics disables per-turn recall logging |

package/bot.js

@@ -381,6 +381,13 @@ async function safeModeBoot() {
     }
   } catch (e) { console.error("interrupted-turn resume failed:", e.message); }
 
+  // Messages a usage limit stopped are picked up when the limit resets
+  // (core/limit-pickup.js): a timer for each one still waiting.
+  try {
+    const waiting = require("./core/limit-pickup").start(adapters);
+    if (waiting.length) console.log(`Limit pick-ups waiting: ${waiting.length}`);
+  } catch (e) { console.error("limit pick-up start failed:", e.message); }
+
   // Kazee Cards: snoozed owner decisions are asked again when due.
   try { require("./core/cards").startDecisionPump(registry); } catch (e) { console.error("Decision pump start failed:", e.message); }
 

package/core/config.js

@@ -126,15 +126,18 @@ const CLAUDE_PATH = configuredProviderPath("claude");
 const CODEX_PATH = config.CODEX_PATH || null;
 const AUTO_COMPACT_TOKENS = parseInt(config.AUTO_COMPACT_TOKENS || process.env.AUTO_COMPACT_TOKENS || "380000", 10);
 const MIN_COMPACT_INTERVAL_MS = parseInt(config.MIN_COMPACT_INTERVAL_MS || process.env.MIN_COMPACT_INTERVAL_MS || "1800000", 10);
-// Token diet canary (off unless conversations are listed). TOKEN_DIET_CONVERSATIONS
-// is a comma-separated list of conversation keys as the usage ledger's `project`
-// field writes them (e.g. kazee:<room>#thread:<root>), or "*" for all. A listed
-// conversation compacts at TOKEN_DIET_COMPACT_TOKENS instead of
+// Token diet, on for every conversation by default since 3.5.18 (the 3.5.17
+// canary halved the cost of a reply on the owner's bot). TOKEN_DIET_CONVERSATIONS
+// is "*" (all), a comma-separated list of conversation keys as the usage
+// ledger's `project` field writes them (e.g. kazee:<room>#thread:<root>), or
+// "off". A listed conversation compacts at TOKEN_DIET_COMPACT_TOKENS instead of
 // AUTO_COMPACT_TOKENS, and is compacted before a turn that resumes it after
 // TOKEN_DIET_COLD_MINUTES idle (the prompt cache has expired, so the whole
 // context would be re-written) when its context exceeds TOKEN_DIET_COLD_MIN_TOKENS.
-const TOKEN_DIET_CONVERSATIONS = String(config.TOKEN_DIET_CONVERSATIONS || process.env.TOKEN_DIET_CONVERSATIONS || "")
-  .split(",").map((s) => s.trim()).filter(Boolean);
+const TOKEN_DIET_SETTING = String(config.TOKEN_DIET_CONVERSATIONS || process.env.TOKEN_DIET_CONVERSATIONS || "*").trim();
+const TOKEN_DIET_CONVERSATIONS = /^(off|none)$/i.test(TOKEN_DIET_SETTING)
+  ? []
+  : TOKEN_DIET_SETTING.split(",").map((s) => s.trim()).filter(Boolean);
 const TOKEN_DIET_COMPACT_TOKENS = parseInt(config.TOKEN_DIET_COMPACT_TOKENS || process.env.TOKEN_DIET_COMPACT_TOKENS || "200000", 10);
 const TOKEN_DIET_COLD_MINUTES = parseInt(config.TOKEN_DIET_COLD_MINUTES || process.env.TOKEN_DIET_COLD_MINUTES || "60", 10);
 const TOKEN_DIET_COLD_MIN_TOKENS = parseInt(config.TOKEN_DIET_COLD_MIN_TOKENS || process.env.TOKEN_DIET_COLD_MIN_TOKENS || "120000", 10);

package/core/handlers.js

@@ -87,6 +87,18 @@ function cancelledQueueResult(item, reason) {
   };
 }
 
+// A pick-up waiting for a usage limit to reset (core/limit-pickup.js) in
+// the current conversation, dropped by /stop, /new and /end.
+function dropLimitPickup(reason, state = currentState(), laneKey = currentLaneKey(state)) {
+  try { return require("./limit-pickup").cancel(state.userId, laneKey, reason); } catch (_) { return null; }
+}
+
+function pickupDroppedNote(count) {
+  return count === 1
+    ? "I won't pick up your earlier message when the usage limit resets."
+    : `I won't pick up your ${count} earlier messages when the usage limits reset.`;
+}
+
 // Drops every message queued in one lane: each one's caller gets a cancelled
 // result (no hanging promise), and an idle lane loses its typing heartbeat (the
 // chip would stay on, and the lane could never be pruned). Returns the items.
@@ -1539,6 +1551,7 @@ register({
     if (!requireSession()) return;
     const result = startNewConversation();
     if (!result.ok) return send(`Could not start a new conversation: ${result.error.message}`);
+    dropLimitPickup("/new");
     return send(`Session: ${result.project}\nNew ${result.provider} conversation\n\nSend text, voice, or images.`);
   },
 });
@@ -1792,10 +1805,16 @@ register({
       const dropped = lanes.flatMap((lane) => dropLaneQueue(lane, STOP_DROP_REASON));
       const stopped = lanes.filter((lane) => stopLane(state, lane)).length;
       const sideStopped = await sideCancellation;
-      if (!stopped && !dropped.length) return send(sideStopped ? "Cancelled side response." : "Nothing running.");
+      let pickups = [];
+      try { pickups = require("./limit-pickup").cancelAllFor(state.userId, "/stop all"); } catch (_) {}
+      if (!stopped && !dropped.length) {
+        if (sideStopped) return send("Cancelled side response.");
+        return send(pickups.length ? pickupDroppedNote(pickups.length) : "Nothing running.");
+      }
       const parts = [];
       if (stopped) parts.push(`Cancelled ${stopped} running conversation${stopped === 1 ? "" : "s"}.`);
       if (dropped.length) parts.push(droppedNote(dropped, stopped ? "queued" : "waiting"));
+      if (pickups.length) parts.push(pickupDroppedNote(pickups.length));
       return send(parts.join(" "), dropOffer(dropped));
     }
     // /stop cancels the CURRENT conversation's turn only (other threads keep
@@ -1805,16 +1824,19 @@ register({
     const lane = laneFor(state);
     const sideCancellation = sideChatCoordinator.cancel(state.userId, lane.key);
     const dropped = dropLaneQueue(lane, STOP_DROP_REASON);
+    // A pick-up waiting for a usage limit to reset is dropped too.
+    const pickup = dropLimitPickup("/stop", state, lane.key);
+    const pickupNote = pickup ? ` ${pickupDroppedNote(1)}` : "";
     if (stopLane(state, lane)) {
       await sideCancellation;
-      await send(dropped.length ? `Cancelled. ${droppedNote(dropped, "queued")}` : "Cancelled.", dropOffer(dropped));
+      await send(`${dropped.length ? `Cancelled. ${droppedNote(dropped, "queued")}` : "Cancelled."}${pickupNote}`, dropOffer(dropped));
     } else if (dropped.length) {
       // Nothing to cancel: the dropped messages were waiting for a slot (or
       // queued behind a turn that is only finishing its tail).
       await sideCancellation;
-      await send(droppedNote(dropped, laneBusy(lane) ? "queued" : "waiting"), dropOffer(dropped));
-    } else if (await sideCancellation) await send("Cancelled side response.");
-    else await send("Nothing running.");
+      await send(`${droppedNote(dropped, laneBusy(lane) ? "queued" : "waiting")}${pickupNote}`, dropOffer(dropped));
+    } else if (await sideCancellation) await send(`Cancelled side response.${pickupNote}`);
+    else await send(pickup ? pickupDroppedNote(1) : "Nothing running.");
   },
 });
 
@@ -1867,16 +1889,42 @@ register({
     const state = currentState();
     const result = endCurrentSession({ state });
     if (!result.ok) return send(`Could not end conversation: ${result.error.message}`);
+    dropLimitPickup("/end", state);
     send("Ended. Send anything to start a fresh conversation.");
   },
 });
 
+// Plan limits as last reported (core/usage-limits.js), and this person's
+// pick-up in this conversation if a usage limit stopped a message.
+function planLimitLines(state = currentState()) {
+  const lines = [];
+  try {
+    const limits = require("./usage-limits");
+    const byProvider = new Map();
+    for (const w of limits.knownWindows()) {
+      if (!byProvider.has(w.provider)) byProvider.set(w.provider, []);
+      byProvider.get(w.provider).push(w);
+    }
+    const order = { five_hour: 0, seven_day: 1 };
+    for (const [provider, windows] of byProvider) {
+      const parts = windows
+        .sort((a, b) => (order[a.id] ?? 9) - (order[b.id] ?? 9))
+        .map((w) => `${limits.windowLabel(w.id).replace(/ limit$/, "")} ${Math.round(w.usedPercent)}%${w.resetsAt ? ` (resets ${limits.formatResetTime(w.resetsAt)})` : ""}`);
+      lines.push(`${limits.providerLabel(provider)} plan limits: ${parts.join(" · ")}`);
+    }
+    const pickup = require("./limit-pickup").get(state.userId, currentLaneKey(state));
+    if (pickup) lines.push(`Picking up your stopped message ${limits.whenPhrase(pickup.runAt)} (/stop drops it).`);
+  } catch (_) {}
+  return lines;
+}
+
 register({
   name: "usage", description: "Show token usage & cost for this session",
   handler: async (env) => {
     if (!authorized(env)) return;
     const u = currentState().sessionUsage;
-    if (u.turns === 0) return send("No usage yet in this session.");
+    const limitLines = planLimitLines();
+    if (u.turns === 0) return send(["No usage yet in this session.", ...limitLines].join("\n"));
     const fmt = (n) => n >= 1000 ? (n / 1000).toFixed(1) + "k" : String(n);
     const lines = [
       `*Session usage* (${u.turns} turn${u.turns === 1 ? "" : "s"})`,
@@ -1892,7 +1940,8 @@ register({
     if (u.subagentThreads > 0) {
       lines.push(`Provider sub-agents: ${u.subagentThreads} thread${u.subagentThreads === 1 ? "" : "s"} · ${fmt(u.subagentInputTokens || 0)} in / ${fmt(u.subagentOutputTokens || 0)} out (spawned by the model; not in the totals above)`);
     }
-    if (Number.isFinite(u.quotaUsedPercent)) {
+    if (limitLines.length) lines.push(...limitLines);
+    else if (Number.isFinite(u.quotaUsedPercent)) {
       lines.push(`Plan quota used: ${u.quotaUsedPercent}%${u.quotaResetsAt ? ` (resets ${String(u.quotaResetsAt).slice(0, 16).replace("T", " ")}Z)` : ""}`);
     }
     if (u.lastInputTokens > 200000) {

package/core/limit-pickup.js

@@ -0,0 +1,313 @@
+// Limit pick-up: a chat turn stopped by a plan usage limit runs again when
+// the limit resets (Sumeet, 7 Oct 2026: "have it pick up when the session
+// replenishes … if the user sends it a message it cancels and if the session
+// limit message comes up again it will just rearm").
+//
+//   - arm(): a foreground chat turn failed on PROVIDER_USAGE_LIMIT with a
+//     known reset time. <config>/limit-pickups.json keeps ONE pick-up per
+//     person per conversation (a newer one replaces it; in a group each
+//     sender has their own lane and session) with what is needed to run the
+//     message again as the person who sent it (the turn journal's shape).
+//   - cancel(): that person writing again in that conversation drops it
+//     (router.onMessage, and runner.runAgent for turns started another way),
+//     as do /stop, /new and /end: the conversation moved on.
+//   - start(adapters) at boot sets a timer per pick-up; a reset that passed
+//     while the bot was down fires shortly after boot. When it fires the
+//     record is removed and the message runs with a "the limit has reset,
+//     pick it up" prompt. If that run hits a limit again it re-arms, keeping
+//     the original message and counting attempts (MAX_ATTEMPTS at most).
+// LIMIT_PICKUP=off turns it off (the notice then only says when it resets).
+
+const path = require("path");
+const crypto = require("crypto");
+const CONFIG_DIR = require("../config-dir");
+const { atomicWriteFileSync, readJsonWithFallback, withFileLock } = require("./fsutil");
+const limits = require("./usage-limits");
+
+const FILE = () => process.env.OC_LIMIT_PICKUPS_FILE || path.join(CONFIG_DIR, "limit-pickups.json");
+const MAX_ATTEMPTS = 5;
+// setTimeout's ceiling is ~24.8 days; a plan window is a week at most.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const BOOT_GRACE_MS = 60000;
+
+function setting(name) {
+  if (process.env[name] !== undefined) return process.env[name];
+  try { return require("./config").config[name]; } catch (_) { return undefined; }
+}
+function enabled() {
+  return !/^(off|false|0|no)$/i.test(String(setting("LIMIT_PICKUP") ?? "on").trim());
+}
+// Wait this long after the reset, so the provider's window has turned over.
+function delayMs() {
+  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 maxWaitMs() {
+  const n = Number(setting("LIMIT_PICKUP_MAX_WAIT_H"));
+  return (Number.isFinite(n) && n > 0 ? n : 192) * 3600000;
+}
+
+// A test run that did not point the store somewhere else never touches the
+// live bot's pick-ups.
+function storeOn() {
+  return !(process.env.OPEN_CLAUDIA_TEST === "1" && !process.env.OPEN_CLAUDIA_CONFIG_DIR && !process.env.OC_LIMIT_PICKUPS_FILE);
+}
+
+function readAll() {
+  const data = readJsonWithFallback(FILE(), null);
+  return data && typeof data === "object" && data.pickups && typeof data.pickups === "object" ? data : { v: 1, pickups: {} };
+}
+function update(fn) {
+  return withFileLock(FILE(), () => {
+    const data = readAll();
+    const out = fn(data.pickups);
+    atomicWriteFileSync(FILE(), JSON.stringify(data, null, 2) + "\n");
+    return out;
+  });
+}
+
+// One pick-up per person per conversation.
+function keyFor(canonicalUserId, laneKey) {
+  return `${canonicalUserId || "-"}::${laneKey}`;
+}
+
+// Keys with a pick-up on disk, so the check on every inbound message reads
+// no file. Only this process writes the store.
+let indexCache = null;
+function index() {
+  if (!indexCache) indexCache = new Set(storeOn() ? Object.keys(readAll().pickups) : []);
+  return indexCache;
+}
+
+function list() {
+  return storeOn() ? Object.values(readAll().pickups) : [];
+}
+function get(canonicalUserId, laneKey) {
+  if (!storeOn() || !index().has(keyFor(canonicalUserId, laneKey))) return null;
+  return readAll().pickups[keyFor(canonicalUserId, laneKey)] || null;
+}
+
+// ── wording ─────────────────────────────────────────────────────────────
+
+function at(ms, now = Date.now()) {
+  return limits.whenPhrase(ms, { now });
+}
+function limitName(provider, limitType) {
+  return `${limits.providerLabel(provider)}'s ${limits.windowLabel(limitType)}`;
+}
+
+const PICKUP_PROMPT = (hitAt, provider, original) => `Your ${limits.providerLabel(provider)} usage limit stopped this turn at ${hitAt}. The limit has reset, so pick it up now. The message was: ${original}\n\nCheck what you already did (your history, git, files, tool state, the chat) before acting; never repeat a send, push, deploy or write that already happened; then finish.`;
+
+/**
+ * What a turn stopped by a limit should do: arm a pick-up (armable) or only
+ * say when the limit lifts. Pure: deliverForegroundResult posts `notice` and
+ * then calls arm() with the plan when armable.
+ */
+function planFor(result, runContext, { now = Date.now(), windows = [], guarded = false } = {}) {
+  const hit = limits.limitHitDetails({
+    provider: runContext?.provider, error: result?.error, rateLimit: result?.rateLimit, windows, now,
+  });
+  if (!hit) return null;
+  // An outside contact is not told which model or plan the bot runs on.
+  const name = guarded ? "My usage limit" : limitName(hit.provider, hit.limitType);
+  const known = Number.isFinite(hit.resetsAt) && hit.resetsAt > now - 6 * 3600000;
+  const runAt = known ? Math.max(hit.resetsAt, now) + delayMs() : null;
+  const pickup = runContext?.limitPickup || null;
+  const attempts = (pickup?.attempts || 0) + 1;
+  const armable = enabled()
+    && known
+    && runAt - now <= maxWaitMs()
+    && attempts <= MAX_ATTEMPTS
+    && runContext?.purpose === "foreground"
+    && !runContext?.passive
+    && !runContext?.liveCall
+    && !!runContext?.origin?.adapterId
+    && !!runContext?.channelId;
+  let notice;
+  if (known && runContext?.purpose && runContext.purpose !== "foreground") {
+    notice = `⏳ ${name} is used up, so this ${runContext.purpose === "scheduled" ? "scheduled run" : "run"} stopped. It resets ${at(hit.resetsAt, now)}.`;
+  } else if (armable) {
+    const again = pickup && pickup.limitType && pickup.limitType === hit.limitType ? "is still used up" : "is used up too";
+    notice = pickup
+      ? `⏳ ${name} ${again}. I'll try your message again ${at(runAt, now)}. If you write to me before then, I'll answer that instead and drop this.`
+      : `⏳ ${name} is used up, so I stopped here. I'll pick your message back up ${at(runAt, now)}, when it resets. If you write to me before then, I'll answer that instead and drop this.`;
+  } else if (known) {
+    notice = attempts > MAX_ATTEMPTS
+      ? `⏳ ${name} is used up again, after ${MAX_ATTEMPTS} tries. It resets ${at(hit.resetsAt, now)}: send your message again then.`
+      : `⏳ ${name} is used up. It resets ${at(hit.resetsAt, now)}: send your message again then.`;
+  } else if (guarded) {
+    notice = "⏳ My usage limit is reached and I can't tell when it resets, so send your message again later.";
+  } else {
+    notice = `⏳ ${limits.providerLabel(hit.provider)} says its usage limit is reached ("${String(hit.text || "").slice(0, 160)}"). I can't tell when it resets, so send your message again later.`;
+  }
+  return { hit, armable, runAt, attempts, notice };
+}
+
+// ── arm / cancel ────────────────────────────────────────────────────────
+
+const timers = new Map(); // keyFor(person, conversation) -> timeout
+let runtime = null; // { adapters, deps } once start() ran
+
+function conversationOf(runContext) {
+  return require("./turn-journal").conversationOf(runContext);
+}
+
+function arm(runContext, plan, { now = Date.now() } = {}) {
+  if (!storeOn() || !plan?.armable) return null;
+  const pickup = runContext.limitPickup || null;
+  const record = {
+    v: 1,
+    id: crypto.randomBytes(6).toString("hex"),
+    conversation: conversationOf(runContext),
+    turn: {
+      // A pick-up that hits a limit again keeps the person's original message.
+      prompt: pickup?.originalPrompt || String(runContext.userPrompt || ""),
+      imagePaths: runContext.imagePaths || [],
+      attachments: runContext.attachments || [],
+      replyToMsgId: runContext.replyToMsgId || null,
+      project: runContext.project ? { name: runContext.project.name || null, dir: runContext.project.dir || null } : null,
+    },
+    provider: plan.hit.provider,
+    limitType: plan.hit.limitType || null,
+    resetsAt: plan.hit.resetsAt,
+    runAt: plan.runAt,
+    armedAt: now,
+    firstHitAt: pickup?.firstHitAt || now,
+    attempts: plan.attempts,
+  };
+  const key = keyFor(record.conversation.canonicalUserId, record.conversation.laneKey);
+  update((pickups) => { pickups[key] = record; });
+  index().add(key);
+  schedule(key, record, now);
+  console.log(`[limit-pickup] armed ${key}: ${record.provider} ${record.limitType || "limit"} resets ${new Date(record.resetsAt).toISOString()}, runs ${new Date(record.runAt).toISOString()} (attempt ${record.attempts})`);
+  return record;
+}
+
+function drop(keys, reason) {
+  const wanted = keys.filter((key) => index().has(key) || timers.has(key));
+  if (!wanted.length) return [];
+  for (const key of wanted) {
+    const timer = timers.get(key);
+    if (timer) { clearTimeout(timer); timers.delete(key); }
+    index().delete(key);
+  }
+  const removed = update((pickups) => wanted.filter((key) => pickups[key]).map((key) => {
+    const record = pickups[key];
+    delete pickups[key];
+    return record;
+  }));
+  for (const record of removed) console.log(`[limit-pickup] cancelled ${keyFor(record.conversation.canonicalUserId, record.conversation.laneKey)} (${reason})`);
+  return removed;
+}
+
+/** Drop this person's pick-up in this conversation (they wrote, /stop, /new, /end). */
+function cancel(canonicalUserId, laneKey, reason = "a new message") {
+  if (!laneKey || !storeOn()) return null;
+  return drop([keyFor(canonicalUserId, laneKey)], reason)[0] || null;
+}
+
+/** Drop every pick-up of this person (/stop all). */
+function cancelAllFor(canonicalUserId, reason = "/stop all") {
+  if (!storeOn()) return [];
+  const prefix = `${canonicalUserId || "-"}::`;
+  return drop([...index()].filter((key) => key.startsWith(prefix)), reason);
+}
+
+// ── timers and the pick-up run ──────────────────────────────────────────
+
+function schedule(key, record, now = Date.now()) {
+  if (!runtime) return; // start() at boot sets the timers
+  const old = timers.get(key);
+  if (old) clearTimeout(old);
+  const wait = Math.min(Math.max(record.runAt - now, 0), MAX_TIMER_MS);
+  const timer = setTimeout(() => {
+    timers.delete(key);
+    // The ceiling cut the wait short: set the rest.
+    if (record.runAt - Date.now() > 1000) return schedule(key, record);
+    fire(key, record.id).catch((error) => console.warn(`[limit-pickup] ${key}: ${error?.message || error}`));
+  }, wait);
+  timer.unref?.();
+  timers.set(key, timer);
+}
+
+function defaultDeps() {
+  const journal = require("./turn-journal");
+  return {
+    ...journal.defaultDeps(),
+    chatScope: journal.chatScope,
+    findAdapter: journal.findAdapter,
+    isGuarded: () => { try { return require("./relationship").isCurrentSpeakerGuarded(); } catch (_) { return false; } },
+  };
+}
+
+async function fire(key, id) {
+  if (!runtime) return null;
+  const { adapters, deps } = runtime;
+  // Take it out first: it runs once; a new limit hit arms a new one.
+  const record = update((pickups) => {
+    const current = pickups[key];
+    if (!current || (id && current.id !== id)) return null;
+    delete pickups[key];
+    return current;
+  });
+  if (!record) return null;
+  index().delete(key);
+  if (!enabled()) return null;
+  if (deps.isSafeMode()) {
+    // Safe mode runs no turns: keep it for the next boot.
+    update((pickups) => { pickups[key] = pickups[key] || record; });
+    index().add(key);
+    return null;
+  }
+  const adapter = deps.findAdapter(adapters || [], record.conversation);
+  if (!adapter) {
+    console.warn(`[limit-pickup] ${key}: its channel is not loaded; dropped`);
+    return null;
+  }
+  const scope = deps.chatScope(record.conversation, adapter, deps);
+  const hitAt = limits.formatResetTime(record.firstHitAt, { now: deps.now() });
+  return deps.runInChat(scope, async () => {
+    // An outside contact is not told which model or plan the bot runs on.
+    const which = deps.isGuarded() ? "my usage limit" : limitName(record.provider, record.limitType);
+    await Promise.resolve(deps.send(`Picking up your message from ${hitAt} now that ${which} has reset.`, { replyTo: record.turn.replyToMsgId || undefined })).catch(() => {});
+    return deps.runAgent(PICKUP_PROMPT(hitAt, record.provider, record.turn.prompt), record.turn.project?.dir || null, record.turn.replyToMsgId, {
+      purpose: "foreground",
+      imagePaths: record.turn.imagePaths || [],
+      attachments: record.turn.attachments || [],
+      limitPickup: { originalPrompt: record.turn.prompt, firstHitAt: record.firstHitAt, attempts: record.attempts, limitType: record.limitType },
+    });
+  });
+}
+
+/** Boot (after the adapters connect): a timer per waiting pick-up. */
+function start(adapters, overrides = {}) {
+  const deps = { ...defaultDeps(), ...overrides };
+  runtime = { adapters, deps };
+  const now = deps.now();
+  const out = [];
+  indexCache = null;
+  for (const record of list()) {
+    if (!record.conversation?.laneKey) continue;
+    const key = keyFor(record.conversation.canonicalUserId, record.conversation.laneKey);
+    // A reset that passed while the bot was down: run shortly after boot,
+    // once the resumed and restored turns have started.
+    schedule(key, record.runAt < now + BOOT_GRACE_MS ? { ...record, runAt: now + BOOT_GRACE_MS } : record, now);
+    out.push(key);
+  }
+  return out;
+}
+
+function _resetForTests() {
+  for (const timer of timers.values()) clearTimeout(timer);
+  timers.clear();
+  runtime = null;
+  indexCache = null;
+}
+
+module.exports = {
+  PICKUP_PROMPT, MAX_ATTEMPTS,
+  enabled, delayMs, maxWaitMs,
+  keyFor, planFor, arm, cancel, cancelAllFor, list, get, start, fire,
+  _resetForTests,
+};

package/core/providers/claude-events.js

@@ -16,9 +16,56 @@ function createClaudeParserState() {
     seenUsage: new Set(),
     totalCostUsd: 0,
     refusal: null,
+    // Set once the plan limit rejected this run: { resetsAt, limitType, text }.
+    limitHit: null,
   };
 }
 
+const epochMs = (seconds) => {
+  const n = Number(seconds);
+  return Number.isFinite(n) && n > 0 ? Math.round(n * 1000) : null;
+};
+
+// Claude Code's rate_limit_event (emitted when the plan status changes, so at
+// least once per fresh run). rate_limit_info.unifiedWindows carries the use of
+// each window as a 0-1 fraction; status "allowed_warning" is Claude Code's own
+// pace warning (it fires at 25% early in the week), so callers should read the
+// windows, not the status, for "close to the limit".
+function claudeRateLimitEvent(info) {
+  if (!info || typeof info !== "object") return null;
+  const windows = [];
+  const unified = info.unifiedWindows && typeof info.unifiedWindows === "object" ? info.unifiedWindows : {};
+  for (const [id, window] of Object.entries(unified)) {
+    const utilization = Number(window?.utilization);
+    if (!Number.isFinite(utilization)) continue;
+    windows.push({ id, usedPercent: Math.round(utilization * 1000) / 10, resetsAt: epochMs(window.resetsAt) });
+  }
+  return {
+    type: "rate_limit",
+    provider: "claude",
+    status: typeof info.status === "string" ? info.status : null,
+    limitType: typeof info.rateLimitType === "string" ? info.rateLimitType : null,
+    resetsAt: epochMs(info.resetsAt),
+    windows,
+  };
+}
+
+function noteLimitHit(state, patch) {
+  state.limitHit = { resetsAt: null, limitType: null, text: null, ...(state.limitHit || {}) };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== null && value !== undefined && value !== "") state.limitHit[key] = value;
+  }
+}
+
+// The limit notice arrives as a synthetic assistant message (model
+// "<synthetic>", error "rate_limit"). It is not answer text.
+function isLimitNotice(rawEvent) {
+  if (rawEvent.error === "rate_limit") return true;
+  if (rawEvent.message?.model !== "<synthetic>") return false;
+  const text = (rawEvent.message?.content || []).map((block) => (block?.type === "text" ? block.text : "")).join(" ");
+  return providerErrorFlags(text).usageLimit;
+}
+
 function sessionEvent(sessionId, state) {
   if (!sessionId || state.sessionId === sessionId) return null;
   state.sessionId = sessionId;
@@ -43,6 +90,11 @@ function captureRefusal(state, stopReason, stopDetails) {
 function claudeFailureEvent(message, state) {
   const flags = providerErrorFlags(message);
   const event = { type: "error", message, ...flags };
+  if (state.limitHit) {
+    event.usageLimit = true;
+    event.limitResetsAt = state.limitHit.resetsAt;
+    event.limitType = state.limitHit.limitType;
+  }
   if (flags.refusal || state.refusal) {
     const parsed = refusalDetailsFromMessage(message);
     event.refusal = true;
@@ -72,6 +124,13 @@ function normalizeClaudeEvent(rawEvent, state = createClaudeParserState()) {
     return event ? [event] : [];
   }
 
+  if (rawEvent.type === "rate_limit_event") {
+    const event = claudeRateLimitEvent(rawEvent.rate_limit_info);
+    if (!event) return [];
+    if (event.status === "rejected") noteLimitHit(state, { resetsAt: event.resetsAt, limitType: event.limitType });
+    return [event];
+  }
+
   if (rawEvent.type === "stream_event") {
     if (rawEvent.event?.type === "message_delta") {
       captureRefusal(state, rawEvent.event.delta?.stop_reason, rawEvent.event.delta?.stop_details ?? rawEvent.event.stop_details);
@@ -85,6 +144,11 @@ function normalizeClaudeEvent(rawEvent, state = createClaudeParserState()) {
   }
 
   if (rawEvent.type === "assistant") {
+    if (isLimitNotice(rawEvent)) {
+      const text = (rawEvent.message?.content || []).map((block) => (block?.type === "text" ? block.text : "")).join(" ").trim();
+      noteLimitHit(state, { text });
+      return [];
+    }
     const events = [];
     captureRefusal(state, rawEvent.message?.stop_reason, rawEvent.message?.stop_details);
     for (const block of rawEvent.message?.content || []) {
@@ -133,6 +197,12 @@ function normalizeClaudeEvent(rawEvent, state = createClaudeParserState()) {
     if (rawEvent.is_error || /^error/.test(String(rawEvent.subtype || ""))) {
       return [claudeFailureEvent(claudeErrorMessage(rawEvent), state)];
     }
+    if (state.limitHit && !state.sawText) {
+      // A plan limit is a failed turn even when the CLI closes it as a
+      // "success": the limit notice must never go out as the reply. (With
+      // answer text, Claude Code fell back to another model and finished.)
+      return [claudeFailureEvent(state.limitHit.text || claudeErrorMessage(rawEvent), state)];
+    }
     const events = [];
     const session = sessionEvent(rawEvent.session_id, state);
     if (session) events.push(session);