clementine-agent 1.18.177 → 1.18.179

package/dist/agent/complex-task-detector.d.ts

@@ -1,9 +1,26 @@
+/**
+ * Explicit background-intent detector.
+ *
+ * Returns a recommendation ONLY when the user explicitly asks for background
+ * / autonomous / overnight execution. We deliberately do not classify "this
+ * looks complex" anymore — chat now stays in the live SDK loop, with
+ * automatic compaction and inline subagent delegation (Agent → planner /
+ * researcher / etc.) for context isolation, just like Claude Code itself.
+ * Big work that genuinely blows past the SDK's auto-compact is caught by the
+ * gateway's overflow → retry → promote-to-background fallback, which is the
+ * *real* escape hatch instead of a regex pre-classifier.
+ *
+ * The narrow detection here is what lets a user say "go research this
+ * overnight" and have it actually queue as a durable background task.
+ */
 export interface ComplexTaskRecommendation {
-    score: number;
     reasons: string[];
     suggestedMaxMinutes: number;
     plan: string[];
-    queueImmediately: boolean;
+    /** Always true when this function returns a recommendation — the only
+     *  trigger is the user explicitly asking for background execution. Kept
+     *  on the type for back-compat with the post-overflow rescue path. */
+    queueImmediately: true;
 }
 export declare function detectComplexTaskForBackground(text: string): ComplexTaskRecommendation | null;
 //# sourceMappingURL=complex-task-detector.d.ts.map

package/dist/agent/complex-task-detector.js

@@ -1,32 +1,18 @@
+// Skill authoring is an interactive build-with-the-user flow; never auto-queue.
 const SKILL_AUTHORING_RE = /\b(create|make|build|draft|write|teach|save|update)\b.{0,40}\b(skill|SKILL\.md)\b|\bskill[- ]creator\b/i;
-const EXPLICIT_BACKGROUND_RE = /\b(background|deep mode|keep working|don't stop|dont stop|autonomous|long[- ]running|run overnight|take your time)\b/i;
-const COMPLEX_WORK_RE = /\b(audit|research|analy[sz]e|review|scrape|crawl|extract|enrich|compile|compare|verify|cross[- ]check|triage|reconcile|draft|generate|update|sync|report back|write back)\b/i;
-const BATCH_RE = /\b(all|every|each|bulk|batch|list of|contacts?|leads?|accounts?|tasks?|tickets?|records?|rows?|pages?|repos?|projects?)\b/i;
-const SIDE_EFFECT_RE = /\b(update|write|create|draft|send|post|comment|reply|upload|append|sync|mark|close|move)\b/i;
-const MULTI_STEP_RE = /\b(and then|then|after that|finally|from .* to |against .* and |across|compile .* into|check .* then)\b/i;
+// The ONLY trigger. Matches "in the background", "overnight", "keep working",
+// "don't stop", "autonomous", "long-running", "take your time", "deep mode".
+const EXPLICIT_BACKGROUND_RE = /\b(background|deep mode|keep working|don't stop|dont stop|autonomous|long[- ]running|run overnight|overnight|take your time)\b/i;
+// Light scope hints used only for the duration estimate + plan text. None of
+// these alter whether the function fires — they shape the recommendation
+// once the explicit-intent gate has already opened.
+const BATCH_RE = /\b(all|every|each|bulk|batch|list of|contacts?|leads?|accounts?|tasks?|tickets?|records?|rows?|pages?|repos?|projects?|firms?|metros?|prospects?)\b/i;
+const SIDE_EFFECT_RE = /\b(update|write|create|draft|send|post|comment|reply|upload|append|sync|mark|close|move|deploy|host|publish)\b/i;
 const SYSTEM_KEYWORDS = [
-    'asana',
-    'salesforce',
-    'google sheet',
-    'google sheets',
-    'sheet',
-    'sheets',
-    'dataforseo',
-    'hubspot',
-    'notion',
-    'github',
-    'gmail',
-    'outlook',
-    'slack',
-    'discord',
-    'website',
-    'websites',
-    'crm',
-    'spreadsheet',
-    'csv',
-    'airtable',
-    'linear',
-    'jira',
+    'asana', 'salesforce', 'google sheet', 'google sheets', 'sheet', 'sheets',
+    'dataforseo', 'hubspot', 'notion', 'github', 'gmail', 'outlook', 'slack',
+    'discord', 'website', 'websites', 'crm', 'spreadsheet', 'csv', 'netlify',
+    'vercel', 'airtable', 'linear', 'jira',
 ];
 function countSystemMentions(text) {
     const lower = text.toLowerCase();
@@ -37,10 +23,10 @@ function countSystemMentions(text) {
     }
     return count;
 }
-function estimatedMinutes(score, systemCount) {
-    if (score >= 8 || systemCount >= 4)
+function estimatedMinutes(systemCount, textLength) {
+    if (systemCount >= 4 || textLength > 800)
         return 90;
-    if (score >= 6 || systemCount >= 3)
+    if (systemCount >= 2 || textLength > 400)
         return 60;
     return 30;
 }
@@ -72,47 +58,17 @@ export function detectComplexTaskForBackground(text) {
         return null;
     if (SKILL_AUTHORING_RE.test(trimmed))
         return null;
-    const systemCount = countSystemMentions(trimmed);
-    const reasons = [];
-    let score = 0;
-    if (EXPLICIT_BACKGROUND_RE.test(trimmed)) {
-        score += 4;
-        reasons.push('explicit background/deep-work wording');
-    }
-    if (COMPLEX_WORK_RE.test(trimmed)) {
-        score += 2;
-        reasons.push('multi-step work verb');
-    }
-    if (BATCH_RE.test(trimmed)) {
-        score += 2;
-        reasons.push('batch or many-record scope');
-    }
-    if (SIDE_EFFECT_RE.test(trimmed)) {
-        score += 1;
-        reasons.push('write/draft/update side effects');
-    }
-    if (MULTI_STEP_RE.test(trimmed)) {
-        score += 1;
-        reasons.push('multi-step sequencing');
-    }
-    if (systemCount >= 2) {
-        score += Math.min(4, systemCount);
-        reasons.push(`${systemCount} named systems or data surfaces`);
-    }
-    if (trimmed.length > 450) {
-        score += 1;
-        reasons.push('long detailed request');
-    }
-    const queueImmediately = EXPLICIT_BACKGROUND_RE.test(trimmed) && score >= 5;
-    const shouldOffer = queueImmediately || score >= 5 || (systemCount >= 2 && (BATCH_RE.test(trimmed) || SIDE_EFFECT_RE.test(trimmed)));
-    if (!shouldOffer)
+    if (!EXPLICIT_BACKGROUND_RE.test(trimmed))
         return null;
+    const systemCount = countSystemMentions(trimmed);
+    const reasons = ['explicit background/deep-work wording'];
+    if (systemCount >= 2)
+        reasons.push(`${systemCount} named systems`);
     return {
-        score,
         reasons,
-        suggestedMaxMinutes: estimatedMinutes(score, systemCount),
+        suggestedMaxMinutes: estimatedMinutes(systemCount, trimmed.length),
         plan: buildPlan(trimmed, systemCount),
-        queueImmediately,
+        queueImmediately: true,
     };
 }
 //# sourceMappingURL=complex-task-detector.js.map

package/dist/agent/run-agent-cron.js

@@ -26,6 +26,31 @@ const CRON_PROGRESS_PENDING_MAX_ITEMS = 20;
 const CRON_PROGRESS_NOTES_MAX_CHARS = 2000;
 const logger = pino({ name: 'clementine.run-agent-cron' });
 const CRON_CONTEXT_ITEM_MAX = 80;
+const CLEMENTINE_TOOLS_SERVER = `${(process.env.ASSISTANT_NAME ?? 'Clementine').toLowerCase()}-tools`;
+const BACKGROUND_TASK_WORKER_NAME = 'background-task-worker';
+const DEFAULT_BACKGROUND_WORKER_TOOLS = [
+    'Agent',
+    'Read',
+    'Write',
+    'Edit',
+    'Glob',
+    'Grep',
+    'Bash',
+    'WebSearch',
+    'WebFetch',
+    'TodoWrite',
+];
+const BACKGROUND_TASK_WORKER_PROMPT = [
+    'You are Clementine\'s background task worker for long-running user requests.',
+    '',
+    'Run the assigned task to completion using the available tools. Keep raw API responses, scraped pages, and large file contents out of the final answer; extract the fields you need and continue.',
+    '',
+    'Use TodoWrite for multi-step state. Process batch work in bounded chunks, checkpoint meaningful progress in durable artifacts when useful, and avoid repeating the same expensive read or tool call.',
+    '',
+    'If credentials, missing scope, human approval, or an irreversible action blocks completion, stop with one concise blocker/question and the exact next action needed. Do not keep retrying blindly.',
+    '',
+    'Return only the final user-facing result: links or changed locations, counts, skipped/error records, and the next recommended action.',
+].join('\n');
 /** Total number of skill blocks injected into a cron prompt — pinned + auto. */
 const MAX_INJECTED_SKILLS = 4;
 /**
@@ -172,6 +197,27 @@ function capContextBlock(s, max) {
         return '';
     return s.length <= max ? s : s.slice(0, max - 3) + '...';
 }
+function backgroundWorkerTools(effectiveAllowedTools, mcpServersApplied) {
+    if (effectiveAllowedTools)
+        return [...new Set(['Agent', ...effectiveAllowedTools])];
+    const mcpWildcards = [CLEMENTINE_TOOLS_SERVER, ...mcpServersApplied]
+        .filter(Boolean)
+        .map((server) => `mcp__${server}__*`);
+    return [...new Set([...DEFAULT_BACKGROUND_WORKER_TOOLS, ...mcpWildcards])];
+}
+function buildBackgroundTaskWorker(tools, model, maxTurns) {
+    return {
+        description: [
+            'Use for background tasks queued from chat, especially multi-step work, batch data collection, project builds, deployments, and external-system writebacks.',
+            'This agent owns the heavy tool loop so the parent task context stays small.',
+        ].join(' '),
+        prompt: BACKGROUND_TASK_WORKER_PROMPT,
+        tools,
+        ...(model ? { model } : { model: 'sonnet' }),
+        effort: 'medium',
+        maxTurns: typeof maxTurns === 'number' && maxTurns > 0 ? maxTurns : 40,
+    };
+}
 /**
  * Build the previous-progress block from the cron progress JSON file.
  * Lets the agent continue where the prior run left off without re-doing
@@ -749,10 +795,18 @@ export async function runAgentCron(opts) {
         skillsMissing: plan.skillsMissing.length,
         trickAllowedTools: effectiveAllowedTools?.length,
         trickAllowedMcp: opts.allowedMcpServers?.length,
+        forcedBackgroundWorker: opts.jobName.startsWith('bg:'),
         widenedFromSkills: plan.widenedFromSkills,
         ...(promptOversized ? { warning: 'prompt > 50KB; risk of "Prompt is too long" failure' } : {}),
     }, 'runAgentCron: dispatching to runAgent');
     const startedAt = Date.now();
+    const forceBackgroundWorker = opts.jobName.startsWith('bg:');
+    const workerTools = forceBackgroundWorker
+        ? backgroundWorkerTools(effectiveAllowedTools, mcpServersApplied)
+        : [];
+    const workerDef = forceBackgroundWorker
+        ? buildBackgroundTaskWorker(workerTools, opts.model, opts.maxTurns)
+        : null;
     const result = await runAgent(builtPrompt, {
         sessionKey: `cron:${opts.jobName}`,
         source: 'cron',
@@ -762,9 +816,16 @@ export async function runAgentCron(opts) {
         model: opts.model,
         effort,
         ...(maxBudget !== undefined ? { maxBudgetUsd: maxBudget } : {}),
-        maxTurns: opts.maxTurns,
+        maxTurns: forceBackgroundWorker ? 5 : opts.maxTurns,
         abortSignal: opts.abortSignal,
-        ...(effectiveAllowedTools ? { allowedTools: effectiveAllowedTools } : {}),
+        ...(forceBackgroundWorker
+            ? {
+                allowedTools: ['Agent'],
+                permissionTools: workerTools,
+                forceSubagent: BACKGROUND_TASK_WORKER_NAME,
+                agents: { [BACKGROUND_TASK_WORKER_NAME]: workerDef },
+            }
+            : (effectiveAllowedTools ? { allowedTools: effectiveAllowedTools } : {})),
         extraMcpServers: mcpServerMap,
         // 1.18.121 — pipe the merged addDirs+pinned-skill folders to the SDK
         // so a skill's bundled scripts/templates are reachable via Bash/Read

package/dist/agent/run-agent.d.ts

@@ -16,6 +16,7 @@
  *    long-task preflight, NO mode=unleashed wrapper.
  */
 import { type AgentDefinition } from '@anthropic-ai/claude-agent-sdk';
+import type { TerminalReason } from '../types.js';
 /** Read the latest MCP status snapshot. Safe to call from any module. */
 export declare function getLatestMcpStatusSnapshot(): {
     servers: Array<{
@@ -26,6 +27,10 @@ export declare function getLatestMcpStatusSnapshot(): {
 };
 /** Write a fresh snapshot. Called from system/init handlers. */
 export declare function recordMcpStatusFromSystemInit(rawMcpServers: unknown): void;
+/** True when the SDK emits an internal context-pressure diagnostic as an
+ * assistant text block. These are operational warnings, not useful user
+ * output, and they can appear while the run is still recovering/continuing. */
+export declare function isSdkContextDiagnosticText(text: string): boolean;
 /** Drop one server from the cache so the next query repopulates it. */
 export declare function invalidateMcpStatusEntry(name: string): {
     cleared: boolean;
@@ -133,6 +138,8 @@ export interface RunAgentResult {
     sessionId: string;
     /** Final stop reason from the SDK (success, error_max_turns, error_max_budget_usd, etc). */
     subtype: string;
+    /** Precise SDK loop terminal reason, when available. */
+    terminalReason?: TerminalReason;
     /** Token usage breakdown (input, output, cache). */
     usage?: {
         input_tokens?: number;

package/dist/agent/run-agent.js

@@ -75,6 +75,16 @@ function truncateForLog(value, maxBytes) {
         return { _unstringifiable: true };
     }
 }
+/** True when the SDK emits an internal context-pressure diagnostic as an
+ * assistant text block. These are operational warnings, not useful user
+ * output, and they can appear while the run is still recovering/continuing. */
+export function isSdkContextDiagnosticText(text) {
+    const t = text.trim();
+    if (!t)
+        return false;
+    return /^Autocompact is thrashing:\s*the context refilled to the limit/i.test(t)
+        || /^rapid_refill_breaker\b/i.test(t);
+}
 /** Drop one server from the cache so the next query repopulates it. */
 export function invalidateMcpStatusEntry(name) {
     const before = _lastMcpStatusSnapshot.servers.length;
@@ -483,6 +493,7 @@ export async function runAgent(prompt, opts) {
     let totalCostUsd = 0;
     let numTurns = 0;
     let subtype = 'unknown';
+    let terminalReason;
     let usage;
     const stream = query({ prompt: effectivePrompt, options: sdkOptions });
     try {
@@ -538,6 +549,15 @@ export async function runAgent(prompt, opts) {
                 const blocks = (am.message?.content ?? []);
                 for (const block of blocks) {
                     if (block.type === 'text' && typeof block.text === 'string') {
+                        if (isSdkContextDiagnosticText(block.text)) {
+                            logger.warn({
+                                sessionKey: opts.sessionKey,
+                                source,
+                                subtype,
+                                preview: block.text.slice(0, 240),
+                            }, 'runAgent: suppressed SDK context diagnostic text');
+                            continue;
+                        }
                         finalText += block.text;
                         // PRD Phase 4a / 1.18.85: llm_text Event. Truncate at 8KB to keep
                         // the JSONL light — full text is reachable via the SDK transcript.
@@ -611,6 +631,7 @@ export async function runAgent(prompt, opts) {
                 const result = message;
                 sessionId = sessionId || (result.session_id ?? '');
                 subtype = result.subtype ?? 'unknown';
+                terminalReason = result.terminal_reason;
                 numTurns = result.num_turns ?? numTurns;
                 totalCostUsd = result.total_cost_usd ?? 0;
                 const u = result.usage;
@@ -629,7 +650,7 @@ export async function runAgent(prompt, opts) {
                     ts: new Date().toISOString(),
                     sessionId,
                     costUsd: totalCostUsd,
-                    stopReason: subtype,
+                    stopReason: terminalReason && terminalReason !== 'completed' ? `${subtype}:${terminalReason}` : subtype,
                 });
                 // PRD Phase 4d / 1.18.101: unregister from the hook-session registry.
                 // Late-arriving hook events for this sessionId silently drop after this.
@@ -758,6 +779,7 @@ export async function runAgent(prompt, opts) {
         numTurns,
         sessionId,
         subtype,
+        ...(terminalReason ? { terminalReason } : {}),
         ...(usage ? { usage } : {}),
         runId,
         permissionMode: toolPolicy.permissionMode,

package/dist/cli/dashboard.js

@@ -19,7 +19,7 @@ import { TunnelManager } from './tunnel.js';
 import { AgentManager } from '../agent/agent-manager.js';
 import { discoverMcpServers, getClaudeIntegrations, KNOWN_MCP_DESCRIPTIONS } from '../agent/mcp-bridge.js';
 import { buildBuilderEnrichedMessage, builderSessionKey } from '../dashboard/builder/prompt.js';
-import { AGENTS_DIR, MEMORY_FILE, SESSIONS_FILE, TIMEZONE, applyOneMillionContextRecovery, currentTimeZone, looksLikeClaudeOneMillionContextError, normalizeClaudeSdkOptionsForOneMillionContext, } from '../config.js';
+import { AGENTS_DIR, MEMORY_FILE, SESSIONS_FILE, TIMEZONE, applyOneMillionContextRecovery, currentTimeZone, looksLikeClaudeOneMillionContextError, normalizeClaudeSdkOptionsForOneMillionContext, setEnvOverride, } from '../config.js';
 import { parseTasks } from '../tools/shared.js';
 // 1.18.160 — also pull parseCronJobs + parseAgentCronJobs so getCronJobs()
 // returns the same merged set the runtime fires (CRON.md + agent CRON +
@@ -8724,6 +8724,11 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             content = content.trimEnd() + `\n${key}=${value}\n`;
         }
         writeFileSync(ENV_PATH, content, { mode: 0o600 });
+        // Always mirror the disk write into the live env cache. Without this,
+        // BUDGET.* and any other getEnv-backed config stays at the value it
+        // was first read with — that's how "Saved $0 in the dashboard" can
+        // coexist with "Hit the $1.00 cron budget cap" in the same minute.
+        setEnvOverride(key, value);
     }
     function deleteEnvValue(key) {
         if (!existsSync(ENV_PATH))
@@ -8731,6 +8736,9 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
         const re = new RegExp(`^${key}=.*\n?`, 'm');
         const content = readFileSync(ENV_PATH, 'utf-8').replace(re, '');
         writeFileSync(ENV_PATH, content, { mode: 0o600 });
+        // Mirror the delete so live readers don't keep seeing the cached value.
+        setEnvOverride(key, '');
+        delete process.env[key];
     }
     const DASHBOARD_BUDGET_ROWS = [
         { key: 'BUDGET_CHAT_USD', value: '5', label: 'Chat', hint: 'Per interactive chat turn' },
@@ -8786,8 +8794,9 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             return { ok: false, error: 'Budget cap is too high for the dashboard. Use the CLI if you really need a cap above $1000.' };
         }
         const normalized = n === 0 ? '0' : String(Math.round(n * 100) / 100);
+        // `writeEnvValue` mirrors into the live env cache, so BUDGET.* (now
+        // backed by getters) sees the new value on the very next tool call.
         writeEnvValue(key, normalized);
-        process.env[key] = normalized;
         return { ok: true, value: normalized };
     }
     function readRecentDashboardChatFailures(limit = 5) {
@@ -9046,7 +9055,7 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             }
             res.json({
                 ok: true,
-                message: `${key} set to ${formatDashboardBudgetValue(result.value)}. Restart Clementine to apply to running workers.`,
+                message: `${key} set to ${formatDashboardBudgetValue(result.value)}. Applied to running workers immediately.`,
             });
         }
         catch (err) {
@@ -9060,11 +9069,11 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             let message;
             if (preset === 'defaults' || preset === 'standard') {
                 writes = DASHBOARD_BUDGET_ROWS.map(row => ({ key: row.key, value: row.value }));
-                message = 'Restored the standard spend caps. Restart Clementine to apply to running workers.';
+                message = 'Restored the standard spend caps. Applied to running workers immediately.';
             }
             else if (preset === 'uncapped' || preset === 'off' || preset === 'none') {
                 writes = DASHBOARD_BUDGET_ROWS.map(row => ({ key: row.key, value: '0' }));
-                message = 'Removed spend caps by setting all budget values to 0. Restart Clementine for the change to take effect on running workers. (1M context mode is separate — use Force 200K or Safe Recovery for 1M errors.)';
+                message = 'Removed spend caps by setting all budget values to 0. Applied to running workers immediately. (1M context mode is separate — use Force 200K or Safe Recovery for 1M errors.)';
             }
             else {
                 res.status(400).json({ error: 'preset must be defaults or uncapped' });

package/dist/config.d.ts

@@ -40,6 +40,17 @@ export declare function usesOneMillionContext(model: string | null | undefined,
 export declare function getEnv(key: string, fallback?: string): string;
 /** Merged view of process.env overlaid with .env. Use for classifyIntegrations / summarizeIntegrationStatus. */
 export declare function envSnapshot(): Record<string, string | undefined>;
+/**
+ * Hot-update a config value at runtime. Call this from any code path that
+ * persists a config change (e.g. dashboard `/api/budgets/set`) so the
+ * in-module `env` cache stays in sync with what's on disk + in process.env.
+ *
+ * Without this, `getEnv` keeps returning the value that was read from .env
+ * at module init and frozen objects like BUDGET stay stale until the
+ * daemon restarts — that's how a "Budgets at zero in the dashboard" UI can
+ * coexist with a `Hit the $1.00 cron budget cap` error on the same minute.
+ */
+export declare function setEnvOverride(key: string, value: string): void;
 /** Test-only: clear the keychain ref cache so re-resolution can be tested. */
 export declare function _resetKeychainRefCache(): void;
 /**
@@ -83,14 +94,14 @@ export declare const ASSISTANT_EXPERIENCE: {
 export declare const shellEscape: typeof _shellEscape;
 export declare const MODELS: Models;
 export declare const BUDGET: {
-    heartbeat: number;
-    cronT1: number;
-    cronT2: number;
-    chat: number;
-    unleashedPhase: undefined;
-    memoryExtraction: undefined;
-    summarization: undefined;
-    reflection: undefined;
+    readonly heartbeat: number;
+    readonly cronT1: number;
+    readonly cronT2: number;
+    readonly chat: number;
+    readonly unleashedPhase: number | undefined;
+    readonly memoryExtraction: number | undefined;
+    readonly summarization: number | undefined;
+    readonly reflection: number | undefined;
 };
 export declare const MEMORY_JANITOR: {
     consolidatedExpireDays: number;

package/dist/config.js

@@ -285,6 +285,20 @@ export function getEnv(key, fallback = '') {
 export function envSnapshot() {
     return { ...process.env, ...env };
 }
+/**
+ * Hot-update a config value at runtime. Call this from any code path that
+ * persists a config change (e.g. dashboard `/api/budgets/set`) so the
+ * in-module `env` cache stays in sync with what's on disk + in process.env.
+ *
+ * Without this, `getEnv` keeps returning the value that was read from .env
+ * at module init and frozen objects like BUDGET stay stale until the
+ * daemon restarts — that's how a "Budgets at zero in the dashboard" UI can
+ * coexist with a `Hit the $1.00 cron budget cap` error on the same minute.
+ */
+export function setEnvOverride(key, value) {
+    env[key] = value;
+    process.env[key] = value;
+}
 /** Test-only: clear the keychain ref cache so re-resolution can be tested. */
 export function _resetKeychainRefCache() {
     resolvedKeychainRefs.clear();
@@ -379,11 +393,14 @@ export const MODELS = {
 // User-tunable via `clementine config set BUDGET_<NAME>_USD <value>`
 // (writes to ~/.clementine/.env, survives npm update -g) or via
 // `budgets.*` keys in clementine.json.
+// Live getters — each property re-reads .env + process.env on access so a
+// dashboard write (via setEnvOverride) takes effect on the *next* tool call
+// without needing a daemon restart. Defaults match the previous fixed values.
 export const BUDGET = {
-    heartbeat: getEnvOrJsonNumber('BUDGET_HEARTBEAT_USD', json.budgets?.heartbeat, 0.25), // per heartbeat (Haiku)
-    cronT1: getEnvOrJsonNumber('BUDGET_CRON_T1_USD', json.budgets?.cronT1, 0.75), // per tier-1 cron job
-    cronT2: getEnvOrJsonNumber('BUDGET_CRON_T2_USD', json.budgets?.cronT2, 1.50), // per tier-2 cron job
-    chat: getEnvOrJsonNumber('BUDGET_CHAT_USD', json.budgets?.chat, 5.00), // per interactive chat
+    get heartbeat() { return getEnvOrJsonNumber('BUDGET_HEARTBEAT_USD', json.budgets?.heartbeat, 0.25); },
+    get cronT1() { return getEnvOrJsonNumber('BUDGET_CRON_T1_USD', json.budgets?.cronT1, 0.75); },
+    get cronT2() { return getEnvOrJsonNumber('BUDGET_CRON_T2_USD', json.budgets?.cronT2, 1.50); },
+    get chat() { return getEnvOrJsonNumber('BUDGET_CHAT_USD', json.budgets?.chat, 5.00); },
     unleashedPhase: undefined,
     memoryExtraction: undefined,
     summarization: undefined,

package/dist/gateway/router.d.ts

@@ -18,6 +18,11 @@ export declare function buildContextOverflowRetryPrompt(opts: {
     turnContextPrefix?: string;
     project?: ProjectMeta | null;
 }): string;
+export declare function runAgentResultIndicatesContextOverflow(result: {
+    subtype?: string;
+    terminalReason?: string;
+    text?: string;
+}): boolean;
 export type ChatErrorKind = 'rate_limit' | 'one_million_context' | 'context_overflow' | 'auth' | 'billing' | 'transient' | 'unknown';
 export declare function classifyChatError(err: unknown): ChatErrorKind;
 /** Detect auth-like errors in response text that the SDK returned as "successful" results. */
@@ -64,13 +69,14 @@ export declare class Gateway {
     private extractBackgroundTaskId;
     private makeBackgroundOfferId;
     private backgroundAgentForSession;
+    private buildBackgroundTaskPrompt;
     private pruneExpiredBackgroundOffers;
     private latestBackgroundOfferForSession;
     private getBackgroundOfferForSession;
     private createBackgroundOffer;
     private queueBackgroundOffer;
     private formatBackgroundQueuedResponse;
-    private formatBackgroundOfferResponse;
+    private queueBackgroundTaskAfterContextOverflow;
     acceptBackgroundOffer(sessionKey: string, id: string): {
         ok: boolean;
         response: string;

package/dist/gateway/router.js

@@ -96,6 +96,17 @@ export function buildContextOverflowRetryPrompt(opts) {
     parts.push(opts.chatPrompt);
     return parts.filter(Boolean).join('\n\n');
 }
+export function runAgentResultIndicatesContextOverflow(result) {
+    const terminalReason = (result.terminalReason ?? '').trim();
+    if (terminalReason && classifyChatError(terminalReason) === 'context_overflow')
+        return true;
+    const subtype = (result.subtype ?? '').trim();
+    if (subtype && subtype !== 'success' && classifyChatError(subtype) === 'context_overflow')
+        return true;
+    const text = (result.text ?? '').trim();
+    return /^Autocompact is thrashing:\s*the context refilled to the limit/i.test(text)
+        || /^rapid_refill_breaker\b/i.test(text);
+}
 export function classifyChatError(err) {
     const msg = String(err);
     if (isCreditBalanceError(msg))
@@ -299,6 +310,18 @@ export class Gateway {
     backgroundAgentForSession(sessionKey) {
         return this._agentSlugFromSessionKey(sessionKey) ?? this.getSessionProfile(sessionKey) ?? 'clementine';
     }
+    buildBackgroundTaskPrompt(sessionKey, prompt) {
+        const sess = this.sessions.get(sessionKey);
+        const parts = [
+            '[Background task from chat: run this in a fresh task execution. Do not rely on the live chat transcript being resumed; use the self-contained request below.]',
+        ];
+        if (sess?.project?.path) {
+            const description = sess.project.description ? ` (${sess.project.description})` : '';
+            parts.push(`[Active project: ${sess.project.path}${description}]`);
+        }
+        parts.push(prompt.trim());
+        return parts.filter(Boolean).join('\n\n');
+    }
     pruneExpiredBackgroundOffers() {
         const now = Date.now();
         for (const [id, offer] of this.pendingBackgroundOffers) {
@@ -327,6 +350,7 @@ export class Gateway {
             sessionKey,
             fromAgent: this.backgroundAgentForSession(sessionKey),
             prompt,
+            taskPrompt: this.buildBackgroundTaskPrompt(sessionKey, prompt),
             recommendation,
             createdAt: Date.now(),
             expiresAt: Date.now() + 30 * 60_000,
@@ -337,7 +361,7 @@ export class Gateway {
     queueBackgroundOffer(offer) {
         const task = createBackgroundTask({
             fromAgent: offer.fromAgent,
-            prompt: offer.prompt,
+            prompt: offer.taskPrompt,
             maxMinutes: offer.recommendation.suggestedMaxMinutes,
             sessionKey: offer.sessionKey,
         });
@@ -355,25 +379,37 @@ export class Gateway {
         return [
             `Queued background task **${task.id}**.`,
             '',
-            `It will run as **${task.fromAgent}** with a ${task.maxMinutes} minute cap.`,
+            `It will run as **${task.fromAgent}** in a fresh task session with a ${task.maxMinutes} minute cap.`,
             `Use \`status ${task.id}\` or check the dashboard Background Tasks panel for progress.`,
         ].join('\n');
     }
-    formatBackgroundOfferResponse(offer) {
-        const lines = [
-            'This looks like long-running, multi-tool work. I recommend running it in the background so chat does not go stale.',
-            '',
-            '**Plan**',
-            ...offer.recommendation.plan.map((step, idx) => `${idx + 1}. ${step}`),
-            '',
-            `**Why background:** ${offer.recommendation.reasons.join('; ')}.`,
-            `**Estimated cap:** ${offer.recommendation.suggestedMaxMinutes} minutes.`,
-            `**Background offer:** ${offer.id}`,
-            '',
-            `Reply \`run background ${offer.id}\` to queue it, \`run inline ${offer.id}\` to run it in this chat, or \`save skill ${offer.id}\` to make it reusable first.`,
-        ];
-        return lines.join('\n');
+    queueBackgroundTaskAfterContextOverflow(sessionKey, prompt) {
+        const recommendation = detectComplexTaskForBackground(prompt);
+        const task = createBackgroundTask({
+            fromAgent: this.backgroundAgentForSession(sessionKey),
+            prompt,
+            maxMinutes: recommendation?.suggestedMaxMinutes ?? 60,
+            sessionKey,
+        });
+        logger.warn({
+            taskId: task.id,
+            sessionKey,
+            fromAgent: task.fromAgent,
+            maxMinutes: task.maxMinutes,
+        }, 'Queued background task after repeated chat context overflow');
+        return {
+            task,
+            response: [
+                `The live chat context hit the limit, so I moved this into background task **${task.id}** and kept your request attached.`,
+                '',
+                `It will run as **${task.fromAgent}** in a fresh task session with a ${task.maxMinutes} minute cap.`,
+                `Use \`status ${task.id}\` or check the dashboard Background Tasks panel for progress.`,
+            ].join('\n'),
+        };
     }
+    // Offer-message formatter was removed in the Saturday-feel restoration —
+    // the chat path no longer asks "want me to run this in the background?".
+    // Auto-queue on explicit user intent is silent; everything else just runs.
     acceptBackgroundOffer(sessionKey, id) {
         const offer = this.getBackgroundOfferForSession(sessionKey, id);
         if (!offer) {
@@ -1918,45 +1954,38 @@ export class Gateway {
                     || text.startsWith('[Approval:')
                     || text.startsWith('[Reaction:')
                     || text.startsWith('[System:');
+                // ── Explicit background-intent shortcut ────────────────────────
+                // Chat normally runs in-place — the SDK auto-compacts and the model
+                // can spawn `planner` / `researcher` subagents for context-heavy
+                // sub-steps, just like Claude Code. We only auto-queue a durable
+                // background task when the user *explicitly* says "in the
+                // background", "overnight", "keep working", "don't stop", etc. The
+                // post-overflow rescue path below still catches the rare case
+                // where chat actually drowns despite all that.
                 if (!skipBackgroundOffer && !isBuilderSession && !isInternalMsg && this.isTrustedPersonalSession(sessionKey)) {
                     const recommendation = detectComplexTaskForBackground(text);
                     if (recommendation) {
                         const offer = this.createBackgroundOffer(sessionKey, text, recommendation);
-                        if (recommendation.queueImmediately) {
-                            const task = this.queueBackgroundOffer(offer);
-                            const queued = this.formatBackgroundQueuedResponse(task);
-                            if (ledgerRunMetadata) {
-                                ledgerRunMetadata.executionMode = 'background_queued';
-                                ledgerRunMetadata.backgroundTaskId = task.id;
-                            }
-                            if (onText) {
-                                try {
-                                    await onText(queued);
-                                }
-                                catch { /* channel streaming is best-effort */ }
-                            }
-                            this.mirrorChatExchange(sessionKey, originalText, queued, { model: 'chat-control' });
-                            return queued;
-                        }
-                        const offerText = this.formatBackgroundOfferResponse(offer);
+                        const task = this.queueBackgroundOffer(offer);
+                        const queued = this.formatBackgroundQueuedResponse(task);
                         if (ledgerRunMetadata) {
-                            ledgerRunMetadata.executionMode = 'background_offer';
+                            ledgerRunMetadata.executionMode = 'background_queued';
+                            ledgerRunMetadata.backgroundTaskId = task.id;
                         }
                         logger.info({
                             sessionKey,
-                            offerId: offer.id,
-                            score: recommendation.score,
+                            taskId: task.id,
                             reasons: recommendation.reasons,
                             maxMinutes: recommendation.suggestedMaxMinutes,
-                        }, 'Offering background execution for complex chat request');
+                        }, 'Auto-queued background task on explicit user intent');
                         if (onText) {
                             try {
-                                await onText(offerText);
+                                await onText(queued);
                             }
                             catch { /* channel streaming is best-effort */ }
                         }
-                        this.mirrorChatExchange(sessionKey, originalText, offerText, { model: 'chat-control' });
-                        return offerText;
+                        this.mirrorChatExchange(sessionKey, originalText, queued, { model: 'chat-control' });
+                        return queued;
                     }
                 }
                 if (!isInternalMsg && !sess?.profile && !text.startsWith('!') && !isStructuredWorkflowMsg && onProgress) {
@@ -2080,6 +2109,7 @@ export class Gateway {
                     // Interrupt flag was set but no useful partial text — just clear it.
                     delete sessState.pendingInterrupt;
                 }
+                let contextOverflowRecoveryPrompt = '';
                 try {
                     // ── Canonical SDK chat path (Phase 5) ────────────────────────
                     // runAgent() owns chat. No legacy fallback — errors propagate
@@ -2201,22 +2231,18 @@ export class Gateway {
                         },
                         abortSignal: chatAc.signal,
                     });
-                    let runAgentResult;
-                    try {
-                        runAgentResult = await runAgent(finalPrompt, buildRunAgentChatOptions({
-                            ...(priorSdkSessionId ? { resumeSessionId: priorSdkSessionId } : {}),
-                            ...(chatSystemAppend ? { systemPromptAppend: chatSystemAppend } : {}),
-                        }));
-                    }
-                    catch (err) {
-                        if (chatAc.signal.aborted || classifyChatError(err) !== 'context_overflow') {
-                            throw err;
-                        }
+                    let didContextOverflowRetry = false;
+                    const contextOverflowAfterRetryError = () => new Error('rapid_refill_breaker after context overflow retry');
+                    const retryAfterContextOverflow = async () => {
+                        if (didContextOverflowRetry)
+                            throw contextOverflowAfterRetryError();
+                        didContextOverflowRetry = true;
                         const retryPrompt = buildContextOverflowRetryPrompt({
                             chatPrompt,
                             turnContextPrefix,
                             project: sess?.project ?? null,
                         });
+                        contextOverflowRecoveryPrompt = retryPrompt;
                         logger.info({
                             sessionKey: effectiveSessionKey,
                             hadResume: !!priorSdkSessionId,
@@ -2229,9 +2255,49 @@ export class Gateway {
                             await onProgress('refreshing conversation context...').catch(() => { });
                         }
                         this.assistant.clearSession(effectiveSessionKey);
-                        runAgentResult = await runAgent(retryPrompt, buildRunAgentChatOptions({
+                        return runAgent(retryPrompt, buildRunAgentChatOptions({
                             ...(retrySystemAppend ? { systemPromptAppend: retrySystemAppend } : {}),
                         }));
+                    };
+                    let runAgentResult;
+                    try {
+                        runAgentResult = await runAgent(finalPrompt, buildRunAgentChatOptions({
+                            ...(priorSdkSessionId ? { resumeSessionId: priorSdkSessionId } : {}),
+                            ...(chatSystemAppend ? { systemPromptAppend: chatSystemAppend } : {}),
+                        }));
+                    }
+                    catch (err) {
+                        if (chatAc.signal.aborted || classifyChatError(err) !== 'context_overflow') {
+                            throw err;
+                        }
+                        runAgentResult = await retryAfterContextOverflow();
+                    }
+                    if (!chatAc.signal.aborted && runAgentResultIndicatesContextOverflow(runAgentResult)) {
+                        if (didContextOverflowRetry) {
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                subtype: runAgentResult.subtype,
+                                terminalReason: runAgentResult.terminalReason,
+                                textPreview: runAgentResult.text?.slice(0, 240),
+                            }, 'Context overflow result after retry — queueing background task');
+                            throw contextOverflowAfterRetryError();
+                        }
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            subtype: runAgentResult.subtype,
+                            terminalReason: runAgentResult.terminalReason,
+                            textPreview: runAgentResult.text?.slice(0, 240),
+                        }, 'Context overflow result — retrying current message in fresh SDK session');
+                        runAgentResult = await retryAfterContextOverflow();
+                        if (runAgentResultIndicatesContextOverflow(runAgentResult)) {
+                            logger.info({
+                                sessionKey: effectiveSessionKey,
+                                subtype: runAgentResult.subtype,
+                                terminalReason: runAgentResult.terminalReason,
+                                textPreview: runAgentResult.text?.slice(0, 240),
+                            }, 'Context overflow result after retry — queueing background task');
+                            throw contextOverflowAfterRetryError();
+                        }
                     }
                     if (ledgerRunMetadata) {
                         ledgerRunMetadata.runId = runAgentResult.runId;
@@ -2309,9 +2375,18 @@ export class Gateway {
                             this.clearSession(effectiveSessionKey);
                             return oneMillionContextRecoveryMessage();
                         case 'context_overflow':
-                            logger.info({ sessionKey }, 'Context overflow — rotating session');
+                            logger.info({ sessionKey }, 'Context overflow after retry — queueing background task');
                             this.assistant.clearSession(effectiveSessionKey);
-                            return "That conversation got too long — I've started a fresh session. Please resend your message.";
+                            {
+                                const promptForBackground = contextOverflowRecoveryPrompt || chatPrompt;
+                                const { response, task } = this.queueBackgroundTaskAfterContextOverflow(sessionKey, promptForBackground);
+                                if (ledgerRunMetadata) {
+                                    ledgerRunMetadata.executionMode = 'background_queued';
+                                    ledgerRunMetadata.backgroundTaskId = task.id;
+                                }
+                                this.mirrorChatExchange(sessionKey, originalText, response, { model: 'chat-control' });
+                                return response;
+                            }
                         case 'auth':
                             this.recordAuthFailure();
                             return "I'm temporarily offline due to an authentication issue. The owner needs to re-authenticate — I'll recover automatically once it's resolved.";

package/dist/integrations/composio/client.d.ts

@@ -32,6 +32,12 @@ export declare function isComposioEnabled(): boolean;
  * the dashboard PUT /api/settings/COMPOSIO_API_KEY handler.
  */
 export declare function resetComposioClient(): void;
+/**
+ * Drop the per-process connection-list cache so the next call to
+ * `listConnectedToolkits()` hits Composio fresh. Used after authorize /
+ * disconnect / rename so the dashboard and agent see the change immediately.
+ */
+export declare function clearConnectedToolkitsCache(): void;
 export declare function getPreferredUserId(): Promise<string>;
 export declare function clementineUserId(): string;
 export declare function displayNameFor(slug: string): string;

package/dist/integrations/composio/client.js

@@ -83,6 +83,30 @@ export function resetComposioClient() {
     identityCache.clear();
     catalogCache = null;
     detectedPreferredUserId = null;
+    connectionsCache = null;
+    void busComposioMcpCache();
+}
+/**
+ * Drop the per-process connection-list cache so the next call to
+ * `listConnectedToolkits()` hits Composio fresh. Used after authorize /
+ * disconnect / rename so the dashboard and agent see the change immediately.
+ */
+export function clearConnectedToolkitsCache() {
+    connectionsCache = null;
+}
+/**
+ * Fire-and-forget MCP-server cache bust. Imported lazily to avoid the
+ * client → mcp-bridge → client cycle that an `import { ... }` at the top
+ * would create.
+ */
+async function busComposioMcpCache() {
+    try {
+        const mod = await import('./mcp-bridge.js');
+        mod.clearComposioMcpCache?.();
+    }
+    catch {
+        /* mcp-bridge optional at boot; safe to ignore */
+    }
 }
 // Public: same logic as the internal detector, exposed for the MCP bridge so
 // agent sessions land on the right user_id.
@@ -310,10 +334,22 @@ async function getIdentityFor(composio, id, slug, seed) {
     identityCache.set(id, { at: Date.now(), identity });
     return identity;
 }
+// Short-lived per-process cache + stale-while-revalidate. Composio API hiccups
+// between turns used to make tools "vanish" from the chat; with this, a single
+// failed list call falls back to the prior good snapshot. TTL is short enough
+// (60s) that legit reconnects / disconnects show up quickly, and the dashboard
+// auth/disconnect handlers explicitly bust the cache via
+// `clearConnectedToolkitsCache()` for instant reflection.
+let connectionsCache = null;
+const CONNECTIONS_TTL_MS = 60_000;
 export async function listConnectedToolkits() {
     const composio = getComposio();
     if (!composio)
         return [];
+    const now = Date.now();
+    if (connectionsCache && now - connectionsCache.at < CONNECTIONS_TTL_MS) {
+        return connectionsCache.data;
+    }
     try {
         // No userIds filter: a Composio API key is account-scoped, and a personal
         // agent should see every connection on the account regardless of which
@@ -337,10 +373,15 @@ export async function listConnectedToolkits() {
                 createdAt: it.createdAt,
             };
         }));
+        connectionsCache = { at: now, data: enriched };
         return enriched;
     }
     catch (err) {
-        logger.error({ err }, 'listConnectedToolkits failed');
+        if (connectionsCache) {
+            logger.warn({ err, staleAgeMs: now - connectionsCache.at, items: connectionsCache.data.length }, 'listConnectedToolkits failed — returning stale cache');
+            return connectionsCache.data;
+        }
+        logger.error({ err }, 'listConnectedToolkits failed (no cache to fall back to)');
         return [];
     }
 }
@@ -481,6 +522,8 @@ _opts) {
         // others created in parallel via Composio's web UI) get picked up
         // immediately, even within the 60s TTL window.
         detectedPreferredUserId = null;
+        connectionsCache = null;
+        void busComposioMcpCache();
         return { redirectUrl: conn.redirectUrl ?? null, connectionId: conn.id };
     }
     catch (err) {
@@ -509,6 +552,8 @@ export async function disconnectToolkit(connectionId) {
         throw new Error('COMPOSIO_API_KEY not set');
     await composio.connectedAccounts.delete(connectionId);
     identityCache.delete(connectionId);
+    connectionsCache = null;
+    void busComposioMcpCache();
 }
 export async function renameConnection(connectionId, alias) {
     const composio = getComposio();
@@ -520,5 +565,6 @@ export async function renameConnection(connectionId, alias) {
     // hatch and the alternative (bypassing the wrapper entirely) loses retry
     // and auth handling.
     await composio.client.connectedAccounts.patch(connectionId, { alias });
+    connectionsCache = null;
 }
 //# sourceMappingURL=client.js.map

package/dist/integrations/composio/mcp-bridge.d.ts

@@ -16,6 +16,7 @@
  * always works — Composio is purely additive.
  */
 import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+export declare function clearComposioMcpCache(slug?: string): void;
 /**
  * Build SDK MCP server configs for the given toolkit slugs (or all active
  * connected toolkits when omitted). Each toolkit becomes one MCP server.

package/dist/integrations/composio/mcp-bridge.js

@@ -19,6 +19,15 @@ import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';
 import pino from 'pino';
 import { getComposio, getPreferredUserId, listConnectedToolkits, } from './client.js';
 const logger = pino({ name: 'clementine.composio.mcp' });
+const serverCache = new Map();
+const SERVER_CACHE_TTL_MS = 5 * 60_000;
+export function clearComposioMcpCache(slug) {
+    if (slug) {
+        serverCache.delete(slug);
+        return;
+    }
+    serverCache.clear();
+}
 /**
  * Build SDK MCP server configs for the given toolkit slugs (or all active
  * connected toolkits when omitted). Each toolkit becomes one MCP server.
@@ -70,6 +79,11 @@ export async function listComposioToolkitTools(slugs) {
     return out;
 }
 async function buildOne(composio, slug, _connected) {
+    const now = Date.now();
+    const cached = serverCache.get(slug);
+    if (cached && now - cached.at < SERVER_CACHE_TTL_MS) {
+        return cached.server;
+    }
     // composio.tools.get() returns the FLAT toolkit tools (OUTLOOK_LIST_MESSAGES,
     // GMAIL_SEND_EMAIL, …) — exactly the namespacing the agent expects as
     // mcp__outlook__OUTLOOK_LIST_MESSAGES. The alternative, composio.create()
@@ -83,11 +97,13 @@ async function buildOne(composio, slug, _connected) {
     // alphabetically come after OUTLOOK_LIST_CALENDAR_GROUP_*. GitHub has
     // 800+. Set 1000 — comfortable headroom for any single toolkit.
     const tools = await fetchToolkitTools(composio, slug);
-    return createSdkMcpServer({
+    const server = createSdkMcpServer({
         name: slug,
         version: '0.1.0',
         tools: tools,
     });
+    serverCache.set(slug, { at: now, server });
+    return server;
 }
 async function fetchToolkitTools(composio, slug) {
     const userId = await getPreferredUserId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.177",
+  "version": "1.18.179",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",