@inetafrica/open-claudia 3.5.17 → 3.5.19

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);

package/core/providers/events.js

@@ -11,6 +11,7 @@ const NORMALIZED_EVENT_TYPES = Object.freeze([
   "result",
   "error",
   "warning",
+  "rate_limit",
 ]);
 
 // 16MB: tool results carrying base64 images legitimately exceed 1MB — the old
@@ -130,7 +131,9 @@ function providerErrorFlags(message) {
   const text = String(message || "").toLowerCase();
   return {
     authError: /unauthori[sz]ed|not (?:logged in|authenticated)|unauthenticated|login required|authentication failed|auth failed|invalid api key|no credentials|401/.test(text),
-    usageLimit: /usage limit|spend limit|monthly cycle|quota|rate limit/.test(text),
+    // "You've hit your limit / session limit / weekly limit / Opus limit · resets …"
+    // is how Claude Code words a plan limit; the older patterns never matched it.
+    usageLimit: /usage limit|spend limit|monthly cycle|quota|rate limit|hit your (?:[a-z0-9'’-]+ ){0,3}limit/.test(text),
     refusal: /refusals-and-fallback|usage policy|safety classifier|stop_reason['":\s]*refusal/.test(text),
   };
 }

package/core/recall-filter.js

@@ -7,9 +7,15 @@
 const FILTER_TIMEOUT_MS = Number(process.env.RECALL_FILTER_TIMEOUT_MS || 20000);
 const MESSAGE_CLIP_CHARS = 1500;
 const CONTEXT_CLIP_CHARS = 3500;
+// The root must be an object: Claude Code turns the schema into a tool whose
+// input_schema the API requires to be an object, so the bare array this used
+// to be got a 400 on every Claude call and the filter failed open.
 const FILTER_OUTPUT_SCHEMA = Object.freeze({
-  type: "array",
-  items: { type: "string" },
+  type: "object",
+  required: ["relevant"],
+  properties: {
+    relevant: { type: "array", items: { type: "string" } },
+  },
 });
 
 function enabled() {
@@ -18,15 +24,28 @@ function enabled() {
 
 const FILTER_SYSTEM_PROMPT = [
   "You are a relevance judge for an assistant's memory recall.",
-  "Reply with ONLY a JSON array of candidate ids — no prose, no markdown fences.",
+  'Reply with ONLY a JSON object {"relevant": [candidate ids]} — no prose, no markdown fences.',
 ].join("\n");
 
+// The reply is {"relevant": [...]}; a bare array is still read.
+function idList(value) {
+  if (Array.isArray(value)) return value;
+  return value && typeof value === "object" && Array.isArray(value.relevant) ? value.relevant : null;
+}
+
 function parseIds(result) {
-  if (Array.isArray(result?.json)) return result.json;
-  const match = String(result?.text || "").match(/\[[\s\S]*?\]/);
-  if (!match) return null;
-  const parsed = JSON.parse(match[0]);
-  return Array.isArray(parsed) ? parsed : null;
+  const fromJson = idList(result?.json);
+  if (fromJson) return fromJson;
+  const text = String(result?.text || "");
+  for (const pattern of [/\{[\s\S]*\}/, /\[[\s\S]*?\]/]) {
+    const match = text.match(pattern);
+    if (!match) continue;
+    try {
+      const ids = idList(JSON.parse(match[0]));
+      if (ids) return ids;
+    } catch (_) { /* try the other shape */ }
+  }
+  return null;
 }
 
 function createRecallFilter(dependencies = {}) {
@@ -62,7 +81,7 @@ function createRecallFilter(dependencies = {}) {
       "Candidates:",
       ...lines,
       "",
-      `Reply with ONLY a JSON array of the relevant ids, e.g. ["${candidates[0].id}"]. Use [] if none are relevant.`,
+      `Reply with ONLY a JSON object of the relevant ids, e.g. {"relevant": ["${candidates[0].id}"]}. Use {"relevant": []} if none are relevant.`,
     ].join("\n");
     try {
       const result = await runUtility(prompt, {

package/core/router.js

@@ -167,6 +167,16 @@ async function onMessage(envelope) {
       // and the meet-greet lane all have a person to attach to.
       try { require("./relationship").ensureContact(envelope); } catch (e) {}
 
+      // The person writing again drops their pick-up of a message a usage
+      // limit stopped (core/limit-pickup.js): the conversation moved on. Also
+      // when the guard then holds this message. Another bot's message does not.
+      if (!envelope.botHandoff) {
+        try {
+          const state = currentState();
+          require("./limit-pickup").cancel(state.userId, require("./state").currentLaneKey(state), "a new message");
+        } catch (e) {}
+      }
+
       if (envelope.type === "voice") return handleVoice(envelope);
       if (envelope.type === "audio") return handleAudio(envelope);
       if (envelope.type === "photo") return handlePhoto(envelope);

package/core/run-context.js

@@ -213,6 +213,9 @@ function captureRunContext({
     occurrenceId: opts.occurrenceId || null,
     scheduledJobId: opts.scheduledJobId || null,
     originRunId: opts.originRunId || null,
+    // Set on a turn that core/limit-pickup.js re-runs after a usage limit
+    // reset: { originalPrompt, firstHitAt, attempts }.
+    limitPickup: opts.limitPickup ? cloneSerializable(opts.limitPickup, "limit pickup") : null,
   };
 
   return deepFreeze(context);

package/core/runner.js

@@ -16,12 +16,14 @@ const {
   currentState, saveState, recordSession,
   resetSessionUsage, admitLane, cancelTargets, getActiveProvider, getProjectKey,
   laneFor, laneForRun, peekLane, laneBusy, runLaneKey, waitingLanes, slotBlocker, pruneIdleLanes,
-  getProviderSession, setProviderSession, clearProviderSession, quarantineProviderSession, getUsageForSession, commitProviderCompaction,
+  getProviderSession, setProviderSession, clearProviderSession, quarantineProviderSession, getUsageForSession, commitProviderCompaction, commitBranchCompaction,
   resolveProviderSettings, getProjectSessions,
 } = require("./state");
 const { chatContext, currentChannelId, currentAdapter, currentThreadId } = require("./context");
 const { buildTurnPrompt } = require("./system-prompt");
 const turnJournal = require("./turn-journal");
+const usageLimits = require("./usage-limits");
+const limitPickup = require("./limit-pickup");
 const { getProvider, resolveProviderForRun } = require("./providers");
 const { validateInvocation } = require("./providers/contract");
 const { selectTerminalText } = require("./providers/events");
@@ -318,6 +320,8 @@ async function executeProviderInvocation(options = {}) {
   const cleanupOutcome = { ok: true, skipped: false };
   const rawErrors = [];
   const usageEvents = [];
+  // The provider's last plan-limit reading this run (Claude's rate_limit_event).
+  let rateLimit = null;
   const tools = [];
   const textDeltas = [];
   const textFinals = [];
@@ -403,6 +407,7 @@ async function executeProviderInvocation(options = {}) {
       tools.push(event);
     }
     else if (event.type === "usage") usageEvents.push(event);
+    else if (event.type === "rate_limit") rateLimit = event;
     else if (event.type === "result") {
       terminalSeen = true;
       if (event.sessionId) sessionId = event.sessionId;
@@ -598,6 +603,7 @@ async function executeProviderInvocation(options = {}) {
     usage: finalUsage?.usage || null,
     usageScope: finalUsage?.scope || null,
     usageEvents,
+    rateLimit,
     costUsd: Number.isFinite(invocation.parserState.totalCostUsd) ? invocation.parserState.totalCostUsd : 0,
     tools,
     exitCode: closeInfo.code,
@@ -1084,7 +1090,12 @@ function coldResumeDecision(state, runContext, opts = {}) {
   if (runContext.fresh || runContext.continueSession || runContext.liveCall) return no("fresh-or-continue");
   const provider = runContext.provider;
   const sessionId = runContext.sessionId || null;
-  if (!sessionId || getProviderSession(state, provider, key) !== sessionId) return no("no-session");
+  if (!sessionId) return no("no-session");
+  // A scheduled job on its own conversation (a branch: its thread has moved
+  // on) gets the same cap, on that branch. Any other run only on the session
+  // its conversation points at.
+  const branch = getProviderSession(state, provider, key) !== sessionId;
+  if (branch && !isJobBranchRun(runContext)) return no("no-session");
   if (peekLane(state, opts.laneKey || runLaneKey(runContext))?.isCompacting) return no("compacting");
   if (effectiveCompactThreshold(state, { conversationKey: key, tokenDiet: opts.tokenDiet }) === 0) return no("compaction-off");
   const settings = tokenDietSettings(opts.tokenDiet);
@@ -1099,7 +1110,44 @@ function coldResumeDecision(state, runContext, opts = {}) {
   const checkpointTime = Date.parse(usage?.compactionCheckpoint?.at || "");
   const lastCompactedAt = Number(usage?.lastCompactedAt) || (Number.isFinite(checkpointTime) ? checkpointTime : 0);
   if (lastCompactedAt && now - lastCompactedAt < minInterval) return no("recently-compacted", { idleMinutes, contextTokens });
-  return { compact: true, reason: "cold-resume", key, idleMinutes, contextTokens };
+  return { compact: true, reason: "cold-resume", key, idleMinutes, contextTokens, ...(branch ? { sessionId } : {}) };
+}
+
+// A scheduled run that resumes the job's own conversation without becoming
+// its thread's live session (scheduler: attachSession false).
+function isJobBranchRun(runContext) {
+  return !!runContext?.scheduledJobId && runContext.attachSession === false;
+}
+
+// The threshold rule for a scheduled job's own conversation, checked after
+// its run: the thread's rule (shouldAutoCompact) reads only the thread's live
+// session, so a job's branch grew without limit (Kazee Bugs monitor, 5-7 Oct:
+// 201k to 894k, $54.90 a wake). Same threshold and the same spacing.
+function jobBranchThresholdDecision(state, runContext, result, opts = {}) {
+  const key = runContext?.project?.name || null;
+  const no = (reason, extra = {}) => ({ compact: false, reason, key, ...extra });
+  if (!isJobBranchRun(runContext) || !runContext.sessionId) return no("not-a-job-branch");
+  const provider = runContext.provider;
+  const sessionId = result?.sessionId || runContext.sessionId;
+  if (!key || getProviderSession(state, provider, key) === sessionId) return no("live");
+  if (peekLane(state, opts.laneKey || runLaneKey(runContext))?.isCompacting) return no("compacting");
+  const usage = getUsageForSession(state, key, provider, sessionId);
+  const threshold = effectiveCompactThreshold(state, {
+    conversationKey: key,
+    tokenDiet: opts.tokenDiet,
+    contextWindowTokens: usage?.contextWindowTokens,
+  });
+  if (threshold === 0) return no("compaction-off");
+  const contextTokens = usage?.liveContextTokens || usage?.lastInputTokens || 0;
+  if (contextTokens < threshold) return no("under", { contextTokens });
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const minInterval = Number.isFinite(MIN_COMPACT_INTERVAL_MS) ? MIN_COMPACT_INTERVAL_MS : 1800000;
+  const checkpointTime = Date.parse(usage?.compactionCheckpoint?.at || "");
+  const lastCompactedAt = Number(usage?.lastCompactedAt) || (Number.isFinite(checkpointTime) ? checkpointTime : 0);
+  if (contextTokens < threshold * 2 && lastCompactedAt && now - lastCompactedAt < minInterval) {
+    return no("recently-compacted", { contextTokens });
+  }
+  return { compact: true, reason: "threshold", key, sessionId, contextTokens };
 }
 
 // Runs the cold-resume compaction for a turn that holds its lane, and returns
@@ -1121,12 +1169,14 @@ async function compactColdResume(runContext, state, lane, deps = {}) {
     }
     return runContext;
   }
-  console.log(`[token-diet] cold-resume compact ${decision.key} ctx=${decision.contextTokens} idle=${decision.idleMinutes}m`);
+  const branch = decision.sessionId || null;
+  console.log(`[token-diet] cold-resume compact ${decision.key} ctx=${decision.contextTokens} idle=${decision.idleMinutes}m${branch ? ` job-session=${String(branch).slice(0, 8)}` : ""}`);
   let result;
   try {
     result = await compact(runContext.project.dir, {
       notify: false, laneKey: lane.key, admissionHeld: true,
       compactReason: "cold-resume", contextTokensBefore: decision.contextTokens,
+      ...(branch ? { sessionId: branch, provider: runContext.provider } : {}),
     });
   } catch (error) {
     console.warn(`[token-diet] cold-resume compaction failed: ${redactSensitive(error.message)}`);
@@ -1136,6 +1186,18 @@ async function compactColdResume(runContext, state, lane, deps = {}) {
     console.warn(`[token-diet] cold-resume compaction did not complete: ${result?.reason || "unknown"}`);
     return runContext;
   }
+  if (branch) {
+    // The job runs on its compacted conversation; the thread's live pointer
+    // (previousSessionId) and the run's detachment from it stay as they were.
+    return deepFreeze({
+      ...runContext,
+      sessionId: result.newSessionId,
+      admittedSessionId: result.newSessionId,
+      resumeSessionId: result.newSessionId,
+      continueSession: false,
+      fresh: false,
+    });
+  }
   return deepFreeze({
     ...runContext,
     sessionId: result.newSessionId,
@@ -1173,6 +1235,8 @@ function recordCompactionUsage(entry, deps = {}) {
     version: PKG_VERSION,
     kind: "compaction",
     compactReason: entry.compactReason || "manual",
+    // A scheduled job's own conversation, not its thread's live session.
+    ...(entry.branch ? { scope: "job" } : {}),
     backend: entry.provider,
     provider: entry.provider,
     model: entry.model || null,
@@ -1190,6 +1254,7 @@ function compactSummaryPrompt() {
   return [
     "Summarize this conversation for a fresh compacted continuation.",
     "Write a brief that lets your future self resume work without re-asking the user.",
+    "Write it now, in this one reply, from what is already in this conversation. Do NOT use any tools or run any commands (no searches, file reads or status checks): this step allows one reply only, so a tool call ends it with no brief and the compaction fails. The live repo state is attached to the seed for you; if you are unsure of a fact, say so in the brief.",
     "",
     "Include:",
     "- Current user goal and any active side threads or sub-goals.",
@@ -1466,6 +1531,7 @@ function createCompactionService(dependencies = {}) {
   const captureContext = dependencies.captureRunContext || admitRunContext;
   const runCapture = dependencies.runCapture || runAgentCapture;
   const commitCompaction = dependencies.commitCompaction || commitProviderCompaction;
+  const commitBranch = dependencies.commitBranchCompaction || commitBranchCompaction;
   const archiveBrief = dependencies.archiveBrief || archiveCompactionBrief;
   const appendDaySeed = dependencies.appendDaySeed || ((entry) => require("./day-seeds").appendDaySeed(entry));
   const collectRepoFacts = dependencies.collectRepoFacts || collectRepoStateFacts;
@@ -1484,9 +1550,14 @@ function createCompactionService(dependencies = {}) {
     if (lane.runningProcess || ((lane.preparingRun || lane.settling) && !opts.admissionHeld)) {
       return { compacted: false, reason: "Finish or stop the active run before compacting." };
     }
-    const provider = getActiveProvider(state);
+    const provider = opts.provider || getActiveProvider(state);
     const project = getProjectKey(state);
-    const oldSessionId = getProviderSession(state, provider, project);
+    const liveSessionId = getProviderSession(state, provider, project);
+    // opts.sessionId names a scheduled job's own conversation (a branch beside
+    // the thread's live session): that is what gets compacted, and only the
+    // job follows it; the thread's pointer stays where it is.
+    const branch = !!opts.sessionId && opts.sessionId !== liveSessionId;
+    const oldSessionId = branch ? opts.sessionId : liveSessionId;
     if (!project || !oldSessionId) return { compacted: false, reason: "No conversation." };
     const summaryPrompt = compactSummaryPrompt();
     const admitted = captureContext(summaryPrompt, cwd, null, {
@@ -1511,7 +1582,7 @@ function createCompactionService(dependencies = {}) {
     // The recent turns come from THIS conversation's transcript: the captured
     // project, not the state's legacy "Workspace" session (which read another file).
     const recentTurns = collectRecent(capturedStateView(state, summaryContext));
-    const usageBefore = state.sessionUsage;
+    const usageBefore = branch ? getUsageForSession(state, project, provider, oldSessionId) : state.sessionUsage;
     const contextTokensBefore = Number.isFinite(opts.contextTokensBefore)
       ? opts.contextTokensBefore
       : (usageBefore?.liveContextTokens || usageBefore?.lastInputTokens || 0);
@@ -1566,14 +1637,14 @@ function createCompactionService(dependencies = {}) {
       }
       let commit;
       try {
-        commit = await commitCompaction(state, {
+        commit = await (branch ? commitBranch : commitCompaction)(state, {
           operationId,
           canonicalUserId: summaryContext.canonicalUserId,
           project: summaryContext.project.name,
           provider: summaryContext.provider,
           previousSessionId: oldSessionId,
           newSessionId: seedRun.sessionId,
-          title: `Compacted ${new Date().toLocaleDateString()}`,
+          title: branch ? null : `Compacted ${new Date().toLocaleDateString()}`,
           seedUsage: seedRun.usage || null,
         });
       } catch (error) {
@@ -1600,6 +1671,7 @@ function createCompactionService(dependencies = {}) {
         summary,
         commit,
         compactReason: opts.compactReason || "manual",
+        ...(branch ? { branch: true } : {}),
       };
     } finally {
       lane.isCompacting = false;
@@ -1607,6 +1679,7 @@ function createCompactionService(dependencies = {}) {
         try {
           recordCompaction({
             compactReason: opts.compactReason || "manual",
+            branch,
             provider: summaryContext.provider,
             model: summaryContext.providerSettings?.model || null,
             userId: summaryContext.canonicalUserId,
@@ -1662,6 +1735,58 @@ function capturedTranscriptMetadata(runContext, extra = {}) {
   };
 }
 
+// Plan limits (core/usage-limits.js, core/limit-pickup.js). Worked out once
+// per run and kept on the result (not enumerable: never part of its shape).
+function keepOnResult(result, key, value) {
+  try { Object.defineProperty(result, key, { value, enumerable: false, configurable: true, writable: true }); } catch (_) {}
+  return value;
+}
+
+// Each plan window's use after this run: Claude reports it in the stream;
+// Codex in its rollout (read for the ledger on success, here on a failure).
+function planLimitWindows(result, runContext) {
+  if (result.planWindows !== undefined) return result.planWindows;
+  let windows = [];
+  try {
+    if (runContext.provider === "claude") windows = result.rateLimit?.windows || [];
+    else if (runContext.provider === "codex") {
+      const rateLimits = result.codexRateLimits !== undefined
+        ? result.codexRateLimits
+        : (result.sessionId ? readCodexRollout({ threadId: result.sessionId, includeSubagents: false })?.rateLimits || null : null);
+      windows = usageLimits.codexWindows(rateLimits);
+    }
+  } catch (_) { windows = []; }
+  return keepOnResult(result, "planWindows", windows);
+}
+
+// What a turn a usage limit stopped does: the notice it posts and, when the
+// reset time is known, the pick-up deliverForegroundResult arms.
+function limitPlanFor(result, runContext) {
+  if (result.limitPlan !== undefined) return result.limitPlan;
+  let plan = null;
+  if (!result.ok && result.error?.code === "PROVIDER_USAGE_LIMIT") {
+    let guarded = false;
+    try { guarded = require("./relationship").isCurrentSpeakerGuarded(); } catch (_) {}
+    try { plan = limitPickup.planFor(result, runContext, { windows: planLimitWindows(result, runContext), guarded }); }
+    catch (error) { console.warn(`[limit-pickup] plan failed: ${redactSensitive(String(error.message || error))}`); }
+  }
+  return keepOnResult(result, "limitPlan", plan);
+}
+
+// Remember each window's use; the warnings now due (80% / 95%, once per
+// window). A run that cannot show them only updates the use, so the warning
+// is still due on the next turn that can.
+function recordPlanLimits(result, runContext, { warn = true } = {}) {
+  try {
+    const windows = planLimitWindows(result, runContext);
+    if (!windows.length) return [];
+    return usageLimits.recordWindows({ provider: runContext.provider, windows, ...(warn ? {} : { percents: [] }) });
+  } catch (error) {
+    console.warn(`[usage-limits] ${redactSensitive(String(error.message || error))}`);
+    return [];
+  }
+}
+
 function providerRunDiagnostic(result, runContext) {
   if (result.ok) return null;
   let provider;
@@ -1674,6 +1799,8 @@ function providerRunDiagnostic(result, runContext) {
     return `${label} authentication failed.${help ? `\n\n${help}` : ""}`;
   }
   if (code === "PROVIDER_USAGE_LIMIT") {
+    const plan = limitPlanFor(result, runContext);
+    if (plan?.notice) return plan.notice;
     return `${label} reported a usage or rate limit. Check that provider's account status or select another configured provider.`;
   }
   if (code === "PROVIDER_REFUSAL") {
@@ -1777,6 +1904,7 @@ async function persistForegroundUsage(result, runContext, state = currentState()
       liveContextTokens = rollout && rollout.lastContextTokens > 0
         ? rollout.lastContextTokens
         : usageParts(rawUsage, "codex").context;
+      keepOnResult(result, "codexRateLimits", rollout ? rollout.rateLimits || null : null);
     }
     const rolloutOpts = rollout ? {
       contextSource: "rollout_last_request",
@@ -1902,6 +2030,20 @@ async function finalizeStreamPreview(lane, result, runContext = null) {
 // words. That is never an answer, so it is never posted.
 const PLACEHOLDER_REPLY = /^no response requested\.?$/i;
 
+// "⚠️ Claude: 82% of the 5-hour limit is used. It resets at 17:20." goes out
+// after the answer that crossed it. Never to an outside contact (plan
+// internals), never on a live call, never after an unasked group reply.
+function limitWarningsVisible(result, runContext) {
+  if (!result.ok || runContext.passive === true || runContext.liveCall || statusChatterMuted()) return false;
+  try { return !require("./relationship").isCurrentSpeakerGuarded(); } catch (_) { return false; }
+}
+
+async function sendLimitWarnings(due) {
+  for (const item of due) {
+    await send(usageLimits.formatWarning(item)).catch(() => {});
+  }
+}
+
 async function deliverForegroundResult(result, runContext, state = currentState()) {
   const lane = laneForRun(state, runContext);
   if (runContext.lastInputWasVoice) lane.lastInputWasVoice = false;
@@ -1915,6 +2057,17 @@ async function deliverForegroundResult(result, runContext, state = currentState(
     if (stoppedHere) lane.cancelRequested = false;
     return { ok: true, suppressed: "cancelled" };
   }
+  // Plan limits: each window's use is remembered (a warning is due once per
+  // window at 80% and 95%), and a turn a usage limit stopped is picked up
+  // when the limit resets, unless the person writes again first.
+  const limitWarnings = recordPlanLimits(result, runContext, { warn: limitWarningsVisible(result, runContext) });
+  const limitPlan = limitPlanFor(result, runContext);
+  if (limitPlan?.armable) {
+    try { limitPickup.arm(runContext, limitPlan); }
+    catch (error) { console.warn(`[limit-pickup] could not arm: ${redactSensitive(String(error.message || error))}`); }
+  }
+  // Nobody asked for a passive reply: a limit that stopped one is not news.
+  if (limitPlan && runContext.passive === true) return { ok: true, held: true, suppressed: "passive" };
   const diagnostic = providerRunDiagnostic(result, runContext);
   if (diagnostic) result.diagnostic = diagnostic;
   const cleanAnswer = String(result.finalAnswerText || "").trim();
@@ -1966,6 +2119,7 @@ async function deliverForegroundResult(result, runContext, state = currentState(
     if (!sent.ok) sent = await send(chunks[index], telegramHtmlOpts({ botTags: true }));
     if (!sent.ok) throw new Error(`failed to deliver response chunk ${index + 1}`);
   }
+  if (limitWarnings.length) await sendLimitWarnings(limitWarnings);
 
   const shouldSpeak = shouldReplyWithVoice(VOICE_REPLY_MODE, runContext.lastInputWasVoice);
   if (result.ok && shouldSpeak) {
@@ -2712,10 +2866,23 @@ async function runAdmitted(runContext, state, store, capture, ownsAdmissionLock,
   // kill keeps it journaled; see turn-journal.end.)
   if (tracksMainRun) turnJournal.end(runContext);
   // Auto-compaction is part of the lane's turn: only when nothing waits in
-  // this conversation, and it compacts this conversation only.
-  if (!capture && !runContext.skipAutoCompact && result.ok && lane.messageQueue.length === 0 && sameCapturedProject(state, runContext) && shouldAutoCompact(state, { laneKey: lane.key })) {
-    try { await compactActiveSession(runContext.project.dir, { notify: false, laneKey: lane.key, admissionHeld: ownsAdmissionLock, compactReason: "threshold" }); }
-    catch (error) { console.warn(`[proactive-compact] failed: ${redactSensitive(error.message)}`); }
+  // this conversation, and it compacts this conversation only. A scheduled
+  // job on its own conversation (a branch) is held to the same threshold.
+  if (!capture && !runContext.skipAutoCompact && result.ok && lane.messageQueue.length === 0 && sameCapturedProject(state, runContext)) {
+    let jobBranch = { compact: false };
+    try { jobBranch = jobBranchThresholdDecision(state, runContext, result, { laneKey: lane.key }); }
+    catch (error) { console.warn(`[proactive-compact] job conversation check failed: ${redactSensitive(error.message)}`); }
+    if (jobBranch.compact) console.log(`[proactive-compact] job conversation ${jobBranch.key} job-session=${String(jobBranch.sessionId).slice(0, 8)} ctx=${jobBranch.contextTokens}`);
+    if (jobBranch.compact || shouldAutoCompact(state, { laneKey: lane.key })) {
+      try {
+        const outcome = await compactActiveSession(runContext.project.dir, {
+          notify: false, laneKey: lane.key, admissionHeld: ownsAdmissionLock, compactReason: "threshold",
+          ...(jobBranch.compact ? { sessionId: jobBranch.sessionId, provider: runContext.provider, contextTokensBefore: jobBranch.contextTokens } : {}),
+        });
+        // A compaction that runs but does not commit returns its reason instead of throwing.
+        if (outcome && outcome.compacted === false) console.warn(`[proactive-compact] did not complete: ${redactSensitive(String(outcome.reason || "unknown"))}`);
+      } catch (error) { console.warn(`[proactive-compact] failed: ${redactSensitive(error.message)}`); }
+    }
   }
   return result;
 }
@@ -2798,6 +2965,11 @@ function runAgent(prompt, cwd, replyToMsgId, opts = {}) {
   });
 
   if (obsoleteCallTurn(store)) return Promise.resolve(cancelledCallRunResult(runContext));
+  // A turn the person starts here (a button, a restored message) drops their
+  // pick-up waiting for a usage limit to reset; the pick-up's own run does not.
+  if (runContext.purpose === "foreground" && !runContext.limitPickup && !runContext.liveCall) {
+    try { limitPickup.cancel(runContext.canonicalUserId, runLaneKey(runContext), "a new turn"); } catch (_) {}
+  }
   // A planned restart is draining: no new turn starts now. The message is
   // journaled as queued and runs right after the restart.
   if (turnJournal.isDraining() && turnJournal.journalable(runContext)) {
@@ -2975,6 +3147,7 @@ module.exports = {
   defaultCompactTokens,
   coldResumeDecision,
   compactColdResume,
+  jobBranchThresholdDecision,
   recordCompactionUsage,
   effectiveCompactThreshold,
   usageParts,