cachetoast 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,8 @@
 # Cachetoast
 
-When you come back to a **large, idle** coding-agent session whose prompt cache has likely expired, Cachetoast holds your first prompt before the agent re-reads the whole context at full price, and gives you a handoff to continue in a fresh session instead. Works with Claude Code, Codex, and Pi.
+Cachetoast tries to compact **large, idle** Claude Code and Pi sessions before their prompt cache expires. If compaction cannot run, it holds your next prompt once and offers a handoff to a fresh session. Codex uses that handoff fallback.
 
-Zero dependencies. No LLM calls, API keys, telemetry, or network access. Node.js 22+, macOS/Linux.
+Zero dependencies. No separate API keys or telemetry. Timers and handoffs run locally; native compaction uses your agent's model and normal billing. Node.js 22+, macOS/Linux.
 
 Built by [R. Hunter Harris](https://huntersoftwareconsulting.com) at [Hunter Software Consulting](https://huntersoftwareconsulting.com), fractional product and technology leadership for B2B SaaS.
 
@@ -20,12 +20,23 @@ It installs for the agents you have (`--provider codex` to choose, `--dry-run` t
 
 Then restart your agent.
 
+- **Claude Code:** start from the repo root and trust the project. The repo-local `cachetoast-idle` plugin provides the timer; mods require terminal v2.1.287+ or desktop v2.1.286+. Check `/plugin` for loading errors. Older clients retain the handoff fallback.
 - **Codex:** trust the project, run `codex` in the repo, and approve the hooks in `/hooks`. The Codex app skips unapproved hooks and can't approve them ([openai/codex#47283](https://github.com/openai/codex/issues/47283)).
 - **Pi:** trust the project.
 
 ## How it works
 
-If a session is at least 100k tokens (`--min-context-tokens`) and has been idle past its cache deadline, your next prompt is held once:
+For sessions of at least 100k tokens (`--min-context-tokens`), Claude Code and Pi schedule one native compaction attempt per idle period:
+
+| Cache TTL | Compact after idle | Time before expiry |
+| --- | --- | --- |
+| 5 minutes | 4 minutes | 1 minute |
+| 30 minutes | 25 minutes | 5 minutes |
+| 1 hour | 55 minutes | 5 minutes |
+
+New activity cancels the timer. Successful compaction avoids the handoff for that idle period and does not start another timer. If the agent closes or the computer sleeps past expiry, Cachetoast skips the cold compaction. Resuming while still warm can restore the remaining timer.
+
+If compaction failed, was skipped, or is unavailable, your next prompt after the deadline is held once:
 
 ```text
 Cachetoast held this prompt!
@@ -65,7 +76,7 @@ node .cachetoast/runtime/bin/cachetoast.mjs uninstall           # restore origin
 
 ## What to commit
 
-Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings, hooks, and handoff command or skill. `local.json`, `state/`, `handoffs/`, and `manifest.json` are gitignored; handoffs contain conversation excerpts.
+Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings, hooks, handoff command or skill, and `.claude/skills/cachetoast-idle` plugin. These use repo-relative paths and need no launchd, cron, or global service. `local.json`, `state/`, `handoffs/`, and `manifest.json` are gitignored; handoffs contain conversation excerpts.
 
 `init` and `update` are idempotent and leave unrelated settings alone. `uninstall` restores the original files and removes local state. Each stops if you've edited the managed files by hand.
 
@@ -74,8 +85,10 @@ Commit `.cachetoast/runtime`, `.cachetoast/config.json`, and the agent settings,
 - Savings come mostly from Claude Code quota: its large contexts are rewritten to cache at 2× the input price after a miss. Codex and Pi misses cost less.
 - Mobile and remote clients may not show the notice clearly, and can't start a fresh local session to run the handoff. Send the prompt again to continue, or run the handoff later from the CLI or desktop app.
 - Expiry is estimated from a local clock; Cachetoast can't see the provider's cache.
+- Timers require the agent to remain running and awake. Starting a compaction before expiry does not guarantee completion or a cache hit. A failed attempt keeps the handoff available.
+- Codex exposes compaction to an owning app-server connection, but its repo hooks cannot portably reach an arbitrary open session. Codex gets the native context ceiling and handoff guard, without a proactive timer.
 - No hold if hooks are disabled, untrusted, or time out.
-- Verified with Claude Code 2.1.285, Codex CLI 0.159.2, and Pi 0.85.1; provider formats can change. Research: [docs/research.md](docs/research.md).
+- Claude plugin statically validated with Claude Code 2.1.292; adapter behavior tested with synthetic sessions. No paid live-compaction experiment was run. Other integration baselines: Codex CLI 0.159.2 and Pi 0.85.1. Research: [docs/research.md](docs/research.md).
 
 ## Develop
 

package/bin/cachetoast.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
-import { handleHook, configAt, ttlChoice, statePath, userConfigPath, KEY_RE, PROVIDERS } from '../lib/runtime.mjs';
+import { handleHook, idleState, recordIdle, configAt, ttlChoice, statePath, userConfigPath, KEY_RE, PROVIDERS } from '../lib/runtime.mjs';
 import { readJson, readText, safePath } from '../lib/storage.mjs';
 
-const HELP = `Cachetoast 0.1.0 — local handoffs, inspired in part by Antiburn
+const HELP = `Cachetoast 0.1.1 — local handoffs, inspired in part by Antiburn
 Usage: cachetoast <command> [--repo PATH] [options]
   init       Install in the current repo (or --repo) for the agents you have installed.
              [--provider claude,codex,pi] [--dry-run]
@@ -19,8 +19,10 @@ Usage: cachetoast <command> [--repo PATH] [options]
 Cache TTLs are read from Claude Code sessions, 30m for Codex (GPT-5.6+), and guessed from Pi's model.
 To override (5m, 30m, 1h, 24h), pass --<agent>-cache-ttl: saved per user in ~/.config/cachetoast/config.json,
 or per repo in the gitignored .cachetoast/local.json. A TTL a Claude session reports always wins.
-Only sessions of 100k+ tokens are held: the first prompt after the cache goes cold, once per idle period.
-Hooks and all commands run without LLMs, credentials, or network access.
+Claude Code and Pi attempt idle native compaction at 4m / 25m / 55m for 5m / 30m / 1h TTLs.
+Codex uses the handoff fallback; its hooks cannot portably compact an already-open session.
+Only sessions of 100k+ tokens are held, once per idle period, when compaction did not succeed.
+Hooks and handoffs run locally. Native compaction uses the agent's model and normal billing.
 `;
 function options(args) {
   const result = {};
@@ -65,6 +67,13 @@ async function main() {
   if (argv[0] === '--help' || argv[0] === '-h') { process.stdout.write(HELP); return; }
   const [command = 'help', ...args] = argv, o = options(args);
   if (command === 'help' || o.help) { process.stdout.write(HELP); return; }
+  if (command === 'idle') {
+    const input = JSON.parse(await stdin()), root = findRoot(o.repo ?? process.cwd());
+    const out = input.status ? recordIdle(root, o.provider, input.session_id, input)
+      : idleState(root, o.provider, input.session_id);
+    process.stdout.write(JSON.stringify(out) + '\n');
+    return;
+  }
   if (command === 'hook') {
     // A cost advisory must never stop work because of its own failure: fail open with a visible warning.
     let result;
@@ -104,8 +113,9 @@ async function main() {
     if (result.userConfig) console.log(`${result.dryRun ? 'Would save' : 'Saved'} cache TTLs to ${result.userConfig}.`);
     if (result.dryRun || !result.changed.length) return;
     const next = ['Restart your agent.'];
+    if (result.providers.includes('claude')) next.push('Claude: launch from the repo root, trust the project, and check /plugin for cachetoast-idle (requires mods support).');
     if (result.providers.includes('codex') || result.providers.includes('pi')) next.push('Trust the repo.');
-    if (result.providers.includes('codex')) next.push('Codex: review /hooks.');
+    if (result.providers.includes('codex')) next.push('Codex: review /hooks. Proactive idle compaction is unavailable, so the handoff is the fallback.');
     console.log(next.join(' '));
     return;
   }
@@ -127,7 +137,7 @@ async function main() {
     const sessions = keys.map(key => {
       try {
         const s = readJson(safePath(root, statePath(key)));
-        return { key, provider: s.provider, ...ttlChoice(config, s.provider, s), heldAt: s.heldAt ?? null, contextTokens: s.contextTokens ?? null, lastActivity: s.lastActivity, warnings: s.warnings ?? [] };
+        return { key, provider: s.provider, ...ttlChoice(config, s.provider, s), heldAt: s.heldAt ?? null, contextTokens: s.contextTokens ?? null, lastActivity: s.lastActivity, compaction: s.compaction ?? null, warnings: s.warnings ?? [] };
       } catch (error) { return { key, error: `Unreadable state (${error.message}); delete it to reset` }; }
     });
     console.log(JSON.stringify({ config, userConfig: userConfigPath(), sessions, note: 'Cache availability is inferred, never guaranteed. Sessions with unknown context size are never held.' }, null, 2));

package/docs/research.md

@@ -2,6 +2,8 @@
 
 Checked October 1, 2026 against primary provider documentation. Installed clients: Codex CLI 0.159.2 and Claude Code 2.1.285. No paid inference or quota experiment was performed. The private discussion was used to identify questions; its claims were not treated as documentation.
 
+Updated October 17, 2026: Claude's current mods API supports host timers and in-process compaction. The generated plugin passed strict static validation with Claude Code 2.1.292. Timing, cancellation, native API calls, and fallback state are tested with synthetic sessions; no paid live-compaction experiment was performed.
+
 ## What survives cache expiry
 
 Cache expiry removes reusable inference state, not the transcript or its context window. Continuing sends the current context again. Earlier compacted-away history is not magically restored. Native compaction changes the prompt prefix and can require a new cache write. A handoff prepared locally avoids submitting long history solely to summarize it.
@@ -34,11 +36,17 @@ A universal “shorter sessions always perform better” or “250K is optimal
 
 ## Available hooks
 
-Both current clients expose command hooks, including `UserPromptSubmit`, `Stop`, and compaction events. `UserPromptSubmit` supports blocking before the model processes the prompt. A `systemMessage` only appears after the prompt is sent, when the cost is already paid, so Cachetoast holds the first cold prompt once per idle period (`decision: "block"`) and lets it through when sent again. Codex's CLI adds a submitted prompt to message history before hooks run, so Up-arrow recalls a held prompt. Neither client offers a repo-installable surface visible before typing, so the hold is the only point where the cost can still be avoided. Neither documented lifecycle provides a portable command that requests in-process `/compact` while an arbitrary CLI session is idle. Cachetoast therefore performs deterministic local extraction at the next prompt, leaving live transcripts intact. Because extraction needs no model call, preparing it earlier with a timer would cost the same and only add moving parts.
+Both clients expose command hooks including `UserPromptSubmit`, `Stop`, and compaction events. `UserPromptSubmit` supports blocking before the model processes the prompt. Cachetoast holds the first continuation after the idle deadline once (`decision: "block"`) when native compaction has not succeeded; sending it again proceeds. Codex's CLI adds a submitted prompt to message history before hooks run, so Up-arrow recalls a held prompt. Handoff extraction is deterministic and does not modify provider transcripts.
+
+Claude's newer [mods API](https://code.claude.com/docs/en/plugins/mods/reference) exposes `$.clock.after()` and `$.session.compact()`. The latter uses native semantic compaction between turns, rejects while a turn runs, and returns a skip reason when vetoed. Cachetoast installs a bundled module under `.claude/skills/cachetoast-idle`; [project plugins](https://code.claude.com/docs/en/plugins/loading#plugins-shared-through-a-repository) load after trust, from the primary working directory (desktop worktrees may load the main checkout's plugin). Launch from the repo root. Mods require terminal v2.1.287+ or desktop v2.1.286+ per the [mod creation docs](https://code.claude.com/docs/en/plugins/mods/create). The module uses the host process API to read/write Cachetoast state through its copied Node runtime, without invoking another agent or editing the transcript itself.
+
+Claude and Pi now attempt compaction at TTL minus up to five minutes: 5m → 4m, 30m → 25m, 1h → 55m. New activity cancels the timer. Each idle cycle has at most one attempt; success suppresses the fallback for that cycle. Suspended timers waking at or beyond expiry skip compaction. Native compaction has model cost and cache hits remain uncertain.
+
+Codex's [app-server compaction API](https://learn.chatgpt.com/docs/app-server) exposes `thread/compact/start` to an owning connection. This does not establish a portable repo-hook connection to an arbitrary running CLI or desktop session. Cachetoast keeps Codex's threshold and handoff fallback, and installs no private-socket, UI, or second-process transcript workaround.
 
 Codex loads trusted repo hooks from `.codex/hooks.json`; new or changed hook definitions require review in `/hooks`. Hooks run with the session cwd, which may be a subdirectory. See [Codex hooks](https://learn.chatgpt.com/docs/hooks).
 
-Claude’s `UserPromptSubmit` hooks fail open on timeout or non-zero exit (other than exit 2), and `Stop` does not fire on user interrupt. Cachetoast therefore fails open on its own errors too, and reads response timestamps from the transcript to cover interrupted turns. It uses only `UserPromptSubmit` and `Stop`; native compaction summaries are read from the transcript. See [Claude hooks](https://code.claude.com/docs/en/hooks).
+Claude’s `UserPromptSubmit` hooks fail open on timeout or non-zero exit (other than exit 2), and `Stop` does not fire on user interrupt. Cachetoast fails open on its own errors too, and reads response timestamps from the transcript to cover interrupted turns. Command hooks use `UserPromptSubmit` and `Stop`; the native mod also handles startup, turn start, compaction, and shutdown. See [Claude hooks](https://code.claude.com/docs/en/hooks).
 
 ## Pi
 

package/lib/claude-mod.mjs

@@ -0,0 +1,65 @@
+import { createIdleCompactor } from './idle.mjs';
+
+// The installer bundles this module into a repo-local Claude Code plugin.
+// No Node globals: all host access goes through Claude's portable mod API.
+let controller, root, sessionId;
+function warn($, error) { void Promise.resolve($.ui.log(`Cachetoast idle compaction skipped: ${error.message}. The handoff remains available.`)).catch(() => {}); }
+async function command($, input, target = { root, sessionId }) {
+  const result = await $.process.run(['node', `${target.root}/.cachetoast/runtime/bin/cachetoast.mjs`, 'idle', '--provider', 'claude', '--repo', target.root], {
+    cwd: target.root, stdin: JSON.stringify({ session_id: target.sessionId, ...input }), timeoutMs: 10_000
+  });
+  if (result.exitCode !== 0) throw new Error(result.stderr || 'Cannot read compaction state');
+  return JSON.parse(result.stdout);
+}
+async function connect($) {
+  const id = await $.session.id();
+  let dir = await $.session.cwd();
+  while (!await $.fs.exists(`${dir}/.cachetoast/config.json`)) {
+    const parent = dir.slice(0, dir.lastIndexOf('/')) || '/';
+    if (parent === dir) return false;
+    dir = parent;
+  }
+  if (controller && (sessionId !== id || root !== dir)) { controller.cancel(); controller = undefined; }
+  root = dir; sessionId = id;
+  const target = { root, sessionId };
+  controller ??= createIdleCompactor({
+    read: () => command($, {}, target),
+    record: (s, status, result) => command($, { activityId: s.activityId, lastActivity: s.lastActivity, status, skip: result?.skip, tokensAfter: result?.tokensAfter }, target),
+    compact: () => $.session.compact(),
+    now: () => $.clock.now(), after: (ms, fn) => $.clock.after(ms, fn), onError: error => warn($, error)
+  });
+  return true;
+}
+export function register(on) {
+  on('classic.Stop', async ($, e, next) => {
+    const result = await next(e);
+    if (!e.agent_id && !controller?.isRunning()) {
+      try { if (await connect($)) await controller.arm(); } catch (error) { warn($, error); }
+    }
+    return result;
+  });
+  on('classic.SessionStart', async ($, e, next) => {
+    controller?.cancel();
+    const result = await next(e);
+    try { if (await connect($)) await controller.arm(); } catch (error) { warn($, error); }
+    return result;
+  });
+  on('classic.UserPromptSubmit', ($, e, next) => { controller?.cancel(); return next(e); });
+  on('turn.start', ($, e, next) => { controller?.cancel(); return next(e); });
+  on('session.end', ($, e, next) => { controller?.cancel(); return next(e); });
+  // Manual/threshold compaction also satisfies this idle cycle; precompute does not install a summary.
+  on('session.compact', async ($, e, next) => {
+    if (e.agentId || e.trigger === 'precompute') return next(e);
+    if (controller?.isRunning()) return next(e);
+    controller?.cancel();
+    let state;
+    try { if (await connect($)) state = await command($, {}); } catch (error) { warn($, error); }
+    const target = { root, sessionId };
+    const result = await next(e);
+    if (state && !result.skip) {
+      try { await command($, { activityId: state.activityId, lastActivity: state.lastActivity, status: 'succeeded', tokensAfter: result.tokensAfter }, target); }
+      catch (error) { warn($, error); }
+    }
+    return result;
+  });
+}

package/lib/idle.mjs

@@ -0,0 +1,35 @@
+// Host-neutral, single-shot timer. Hosts supply their own clock and native compaction API.
+// Bundled into Claude's sandboxed module as well as imported by Pi.
+export function createIdleCompactor({ read, record, compact, now, after, onError }) {
+  let timer, revision = 0, running = false;
+  const cancel = () => { revision++; timer?.cancel(); timer = undefined; };
+  const eligible = s => s && s.lastActivity != null && Number.isFinite(s.contextTokens)
+    && s.contextTokens >= s.p.minContextTokens && s.compaction?.activityId !== s.activityId;
+  const arm = async () => {
+    cancel();
+    const ticket = revision;
+    try {
+      const s = await read(), time = await now();
+      if (ticket !== revision || running || !eligible(s) || time >= s.lastActivity + s.p.ttlMs) return;
+      timer = after(Math.max(0, s.lastActivity + s.p.idleMs - time), async () => {
+        timer = undefined;
+        try {
+          const current = await read(), firedAt = await now();
+          if (ticket !== revision || running || !eligible(current) || current.activityId !== s.activityId
+            || current.lastActivity !== s.lastActivity || firedAt < current.lastActivity + current.p.idleMs
+            || firedAt >= current.lastActivity + current.p.ttlMs) return;
+          if (!await record(s, 'attempting') || ticket !== revision) return;
+          running = true;
+          try {
+            const result = await compact();
+            await record(s, result?.skip ? 'skipped' : 'succeeded', result);
+          } catch (error) {
+            await record(s, 'failed', { skip: error.message });
+            throw error;
+          } finally { running = false; }
+        } catch (error) { onError(error); }
+      });
+    } catch (error) { onError(error); }
+  };
+  return { arm, cancel, isRunning: () => running };
+}

package/lib/install.mjs

@@ -101,6 +101,13 @@ export function install(root, options = {}) {
     settings.autoCompactEnabled = true;
     for (const flag of ['DISABLE_AUTO_COMPACT', 'DISABLE_COMPACT']) if (settings.env[flag] === '1') settings.env[flag] = '0';
     set('.claude/settings.json', JSON.stringify(mergeHooks(settings, 'claude'), null, 2) + '\n');
+    // Claude discovers trusted project plugins here. Relative paths survive moves and clones.
+    const plugin = '.claude/skills/cachetoast-idle';
+    set(`${plugin}/.claude-plugin/plugin.json`, JSON.stringify({ name: 'cachetoast-idle', version: '0.1.1', author: { name: 'R. Hunter Harris' }, description: 'Compact large idle sessions before estimated cache expiry' }, null, 2) + '\n');
+    set(`${plugin}/hooks/hooks.json`, JSON.stringify({ modules: ['./register.mjs'] }, null, 2) + '\n');
+    const idle = readText(path.join(PACKAGE_ROOT, 'lib/idle.mjs')).replace(/^export /gm, '');
+    const adapter = readText(path.join(PACKAGE_ROOT, 'lib/claude-mod.mjs')).replace(/^import .*\n/, '');
+    set(`${plugin}/hooks/register.mjs`, `// Managed by Cachetoast; bundled for Claude's mod sandbox.\n${idle}\n${adapter}`);
     // Arguments are prompt data, never interpolated into an injected shell command.
     set('.claude/commands/cachetoast-handoff.md', `---\ndescription: Continue a Cachetoast-held session by its key (latest if omitted)\nargument-hint: "[session-key]"\nallowed-tools: Bash(node ${SCRIPT} handoff:*)\n---\n<!-- Managed by Cachetoast; edits are overwritten by init. -->\n${handoffInstructions('claude', 'Requested session key: $ARGUMENTS')}`);
   }
@@ -115,7 +122,7 @@ export function install(root, options = {}) {
     set('.pi/extensions/cachetoast.ts', '// Managed by Cachetoast; edits are overwritten by init.\nexport { default } from "../../.cachetoast/runtime/lib/pi-extension.mjs";\n');
   }
   set('.cachetoast/config.json', JSON.stringify(config, null, 2) + '\n');
-  set('.cachetoast/README.md', '# Cachetoast\n\nThe runtime, config.json, and provider hook settings can be committed. local.json (optional per-repo cache TTL overrides), state, handoffs, and the manifest stay local: handoffs contain conversation excerpts.\n\nWhen a large session (default 100k+ tokens) has been idle past your cache deadline, the first prompt is held once with a fresh-session handoff (in a new session, copy `/cachetoast-handoff KEY` in Claude Code or `$cachetoast-handoff KEY` in Codex from the notice; in Pi, `/handoff` opens one); sending it again continues. The key selects the held session even when others have been held since. Omitting it loads the latest handoff for that provider. Handoffs are local extracts, not model summaries. Cache TTLs are read from Claude Code sessions, 30m for Codex, and guessed from the Pi model; override one with `node .cachetoast/runtime/bin/cachetoast.mjs init --pi-cache-ttl 1h` (saved in ~/.config/cachetoast/config.json). Inspect with `status` and `handoff --key KEY`.\n\nInspired in part by [Antiburn](https://antiburn.com/) and its [open source work](https://github.com/antiburn/antiburn).\n');
+  set('.cachetoast/README.md', '# Cachetoast\n\nThe runtime, config.json, and provider hook settings can be committed. local.json (optional per-repo cache TTL overrides), state, handoffs, and the manifest stay local: handoffs contain conversation excerpts.\n\nLarge idle Claude Code and Pi sessions get one native compaction attempt before estimated expiry: 4m for a 5m TTL, 25m for 30m, 55m for 1h. Claude uses the trusted repo plugin in .claude/skills/cachetoast-idle (launch from the repo root; requires mods support); Pi uses its extension. Keep the agent running and awake. Native compaction uses the agent’s model and normal billing. Codex has no portable repo-hook compaction trigger. If compaction cannot run or fails, the first prompt after the idle deadline is held once with a fresh-session handoff (in a new session, copy `/cachetoast-handoff KEY` in Claude Code or `$cachetoast-handoff KEY` in Codex from the notice; in Pi, `/handoff` opens one); sending it again continues. The key selects the held session even when others have been held since. Omitting it loads the latest handoff for that provider. Handoffs are local extracts, not model summaries. Cache TTLs are read from Claude Code sessions, 30m for Codex, and guessed from the Pi model; override one with `node .cachetoast/runtime/bin/cachetoast.mjs init --pi-cache-ttl 1h` (saved in ~/.config/cachetoast/config.json). Inspect with `status` and `handoff --key KEY`.\n\nInspired in part by [Antiburn](https://antiburn.com/) and its [open source work](https://github.com/antiburn/antiburn).\n');
   const ignore = readText(safePath(root, '.gitignore'));
   const ignores = ['state/', 'handoffs/', 'manifest.json', 'local.json'].map(p => `.cachetoast/${p}`);
   const missing = ignores.filter(p => !ignore.split('\n').includes(p));

package/lib/pi-extension.mjs

@@ -2,7 +2,8 @@
 // Runs in-process: same policy, state, and handoffs as the Claude/Codex hooks.
 import fs from 'node:fs';
 import path from 'node:path';
-import { handleHook, handoffFor, handoffName, configAt, policyFor, statePath } from './runtime.mjs';
+import { handleHook, handoffFor, handoffName, configAt, policyFor, statePath, idleState, recordIdle } from './runtime.mjs';
+import { createIdleCompactor } from './idle.mjs';
 import { statusText } from './policy.mjs';
 import { readJson, safePath, keyFor } from './storage.mjs';
 
@@ -24,7 +25,7 @@ const ttlGuess = ({ model } = {}) => model?.provider !== 'anthropic' && !/claude
   : model.provider === 'anthropic' && process.env.PI_CACHE_RETENTION === 'long' ? '1h' : '5m';
 
 export default function cachetoast(pi) {
-  let lastAssistant = '', compacting = false, timer = null;
+  let lastAssistant = '', compacting = false, compacted = false, timer = null, idle = null;
   // Fail open: any error becomes a warning and Pi continues.
   const guarded = (ctx, action) => {
     try {
@@ -37,6 +38,40 @@ export default function cachetoast(pi) {
     session_name: ctx.sessionManager.getSessionName?.(),
     context_tokens: ctx.getContextUsage()?.tokens ?? undefined, cache_ttl_guess: ttlGuess(ctx), ...extra
   });
+  const compact = ctx => new Promise((resolve, reject) => {
+    if (!ctx.isIdle() || ctx.hasPendingMessages?.() || compacting) return resolve({ skip: 'Session is busy' });
+    compacting = true;
+    try {
+      ctx.compact({
+        onComplete: () => {
+          compacting = false; compacted = true;
+          // Usage can be unavailable immediately after native compaction; success still stands.
+          let tokensAfter;
+          try { tokensAfter = ctx.getContextUsage()?.tokens; } catch {}
+          resolve({ tokensAfter });
+        },
+        onError: error => { compacting = false; reject(error); }
+      });
+    } catch (error) { compacting = false; reject(error); }
+  });
+  const arm = ctx => {
+    idle?.cancel();
+    guarded(ctx, root => {
+      const sessionId = ctx.sessionManager.getSessionId();
+      idle = createIdleCompactor({
+        read: () => {
+          const state = idleState(root, 'pi', sessionId);
+          if (!state || !ctx.isIdle() || ctx.hasPendingMessages?.()) return null;
+          return { ...state, contextTokens: ctx.getContextUsage()?.tokens, p: policyFor(configAt(root), 'pi', { ...state, guessedTtl: ttlGuess(ctx) }) };
+        },
+        record: (s, status, result) => recordIdle(root, 'pi', sessionId, { activityId: s.activityId, lastActivity: s.lastActivity, status, ...result }),
+        compact: () => compact(ctx), now: Date.now,
+        after: (ms, fn) => { const timeout = setTimeout(fn, ms); timeout.unref?.(); return { cancel: () => clearTimeout(timeout) }; },
+        onError: error => ctx.ui.notify(`Cachetoast idle compaction skipped: ${error.message}. The handoff remains available.`, 'warning')
+      });
+      void idle.arm();
+    });
+  };
 
   // Footer status, visible before the next prompt; a timer flips it to cold while idle. Errors just clear it.
   const status = ctx => {
@@ -48,13 +83,17 @@ export default function cachetoast(pi) {
     } catch { try { ctx.ui.setStatus('cachetoast', undefined); } catch {} }
   };
   pi.on('session_start', (_event, ctx) => {
+    compacted = false;
     clearInterval(timer);
     timer = setInterval(() => status(ctx), 30_000);
     timer.unref?.();
     status(ctx);
+    arm(ctx);
   });
-  pi.on('session_shutdown', () => { clearInterval(timer); timer = null; });
+  pi.on('session_shutdown', () => { clearInterval(timer); timer = null; idle?.cancel(); });
+  pi.on('agent_start', () => { idle?.cancel(); compacted = false; });
   pi.on('input', (event, ctx) => {
+    idle?.cancel();
     // Only prompts that start a new run after idle; steering and queued follow-ups do not.
     if (event.source === 'extension' || event.streamingBehavior) return { action: 'continue' };
     const out = guarded(ctx, root => hook(root, ctx, 'UserPromptSubmit', { prompt: event.text }));
@@ -65,6 +104,7 @@ export default function cachetoast(pi) {
       return { action: 'handled' };
     }
     ctx.ui.setStatus('cachetoast', undefined);
+    compacted = false;
     return { action: 'continue' };
   });
   pi.on('agent_end', event => {
@@ -72,14 +112,16 @@ export default function cachetoast(pi) {
     if (last) lastAssistant = messageText(last);
   });
   pi.on('agent_settled', (_event, ctx) => guarded(ctx, root => {
+    if (compacting || compacted || idle?.isRunning()) return;
     hook(root, ctx, 'Stop', { last_assistant_message: lastAssistant });
     // Same context ceiling as Claude/Codex. Pi's compact() aborts a running turn, so only compact once idle.
     const tokens = ctx.getContextUsage()?.tokens;
     if (!compacting && ctx.isIdle() && Number.isFinite(tokens) && tokens >= configAt(root).targetTokens) {
-      compacting = true;
-      const done = () => { compacting = false; };
-      ctx.compact({ onComplete: done, onError: done });
-    }
+      idle?.cancel();
+      const state = idleState(root, 'pi', ctx.sessionManager.getSessionId());
+      void compact(ctx).then(result => recordIdle(root, 'pi', state.sessionId, { ...state, status: result.skip ? 'skipped' : 'succeeded', ...result }))
+        .catch(error => ctx.ui.notify(`Cachetoast compaction failed: ${error.message}`, 'warning'));
+    } else arm(ctx);
     status(ctx);
   }));
   pi.registerCommand('handoff', {

package/lib/policy.mjs

@@ -29,7 +29,8 @@ export function policy(options = {}) {
 export function evaluate(session, p = policy(), now = Date.now()) {
   const idleForMs = session.lastActivity == null ? null : Math.max(0, now - session.lastActivity);
   const large = Number.isFinite(session.contextTokens) && session.contextTokens >= p.minContextTokens;
-  const due = large && idleForMs !== null && idleForMs >= p.idleMs;
+  const compacted = session.compaction?.status === 'succeeded' && session.compaction.activityId === session.activityId;
+  const due = !compacted && large && idleForMs !== null && idleForMs >= p.idleMs;
   return {
     action: due ? 'handoff' : 'wait',
     idleForMs,
@@ -40,6 +41,7 @@ export function evaluate(session, p = policy(), now = Date.now()) {
 
 // Short status for the Pi footer, shown before the next prompt. Null when the session is small or unmeasured.
 export function statusText(session, p = policy(), now = Date.now()) {
+  if (session.compaction?.status === 'succeeded' && session.compaction.activityId === session.activityId) return 'idle context compacted';
   if (!Number.isFinite(session.contextTokens) || session.contextTokens < p.minContextTokens || session.lastActivity == null) return null;
   const size = `${Math.round(session.contextTokens / 1000)}k`, left = p.idleMs - (now - session.lastActivity);
   return left > 0 ? `cache warm ${Math.ceil(left / 60_000)}m · ${size}` : `cache cold · ${size}`;

package/lib/runtime.mjs

@@ -75,9 +75,14 @@ function refreshEvidence(state, input, provider) {
   state.warnings = evidence.warnings;
   // Only a fresh measurement counts: an unreadable or truncated tail must not warn on stale numbers.
   // In-process adapters (Pi) report context size directly.
-  state.contextTokens = Number.isFinite(input.context_tokens) ? input.context_tokens : evidence.contextTokens;
+  const compacted = state.compaction?.status === 'succeeded' && state.compaction.activityId === state.activityId
+    && (evidence.lastActivity == null || evidence.lastActivity <= state.compaction.at);
+  state.contextTokens = Number.isFinite(input.context_tokens) ? input.context_tokens : compacted ? state.contextTokens : evidence.contextTokens;
   // Transcript response times cover interrupted turns, where Stop does not fire.
-  if (evidence.lastActivity !== null) state.lastActivity = Math.max(state.lastActivity ?? 0, evidence.lastActivity);
+  if (!compacted && evidence.lastActivity !== null && (state.lastActivity == null || evidence.lastActivity > state.lastActivity)) {
+    state.lastActivity = evidence.lastActivity;
+    state.activityId = (state.activityId ?? 0) + 1;
+  }
   if (input.last_assistant_message) state.evidence.assistant = terse(input.last_assistant_message, 2400);
   if (evidence.cacheTtl) state.observedTtl = evidence.cacheTtl;
   // Pi sends a guess with every event (none means the default), so a model switch replaces it.
@@ -98,10 +103,10 @@ export function handleHook(root, provider, input, { now = Date.now() } = {}) {
   if (event === 'Stop') {
     // Stop fires right after a model response, which refreshes the provider cache.
     state.lastActivity = Math.max(state.lastActivity ?? 0, now);
+    state.activityId = (state.activityId ?? 0) + 1;
   } else {
     const result = evaluate(state, policyFor(c, provider, state), now);
-    // No agent shows anything before you type, so the first prompt after the cache goes cold is held once:
-    // that is the last moment the cost can be avoided. Sending it again goes through.
+    // If native compaction did not succeed, hold the first continuation after the idle deadline once.
     const held = state.heldAt != null && state.heldAt > (state.lastActivity ?? 0);
     if (result.action === 'handoff' && !held) {
       atomicWrite(root, `.cachetoast/handoffs/${key}.md`, handoffPrompt(root, state, input.prompt) + '\n');
@@ -120,7 +125,27 @@ export function handleHook(root, provider, input, { now = Date.now() } = {}) {
     state.objective ||= state.latestUser;
     // The prompt is sent to the model now, so the cache clock restarts.
     state.lastActivity = now;
+    state.activityId = (state.activityId ?? 0) + 1;
   }
   atomicWrite(root, statePath(key), state);
   return {};
 }
+
+// Shared with native in-process adapters; this never calls a model or edits its transcript.
+export function idleState(root, provider, sessionId) {
+  if (!PROVIDERS.includes(provider) || !sessionId || typeof sessionId !== 'string') throw new Error('Invalid idle session');
+  const state = readJson(safePath(root, statePath(keyFor(provider, sessionId))));
+  return state ? { ...state, activityId: state.activityId ?? 0, p: policyFor(configAt(root), provider, state) } : null;
+}
+export function recordIdle(root, provider, sessionId, input, { now = Date.now() } = {}) {
+  const state = idleState(root, provider, sessionId);
+  if (!state || input.activityId !== state.activityId || input.lastActivity !== state.lastActivity) return false;
+  if (!['attempting', 'succeeded', 'skipped', 'failed'].includes(input.status)) throw new Error('Invalid compaction status');
+  if (input.status === 'attempting' && state.compaction?.activityId === state.activityId) return false;
+  delete state.p;
+  state.compaction = { activityId: state.activityId, status: input.status, at: now };
+  if (input.skip) state.compaction.reason = terse(input.skip, 300);
+  if (input.status === 'succeeded') state.contextTokens = Number.isFinite(input.tokensAfter) ? input.tokensAfter : null;
+  atomicWrite(root, statePath(state.key), state);
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cachetoast",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local, provider-neutral handoffs and cache-aware session rotation for coding agents",
   "type": "module",
   "license": "MIT",