clauderipple 0.8.9 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.9.0 — 2026-10-13
+
+### Added
+
+- **The ripple mod.** A band above the Code tab's prompt shows reasoning effort, context, the
+  cache timer, and which model answered each request with its cache hit. Log opens the request
+  log, ⚙ opens quick settings, and the dashboard has a mod page with every setting.
+- **Effort picked per prompt.** A small judge model (Haiku 5.5 or Jev) reads the prompt and the
+  recent turns, then sets low through max. Pick an effort yourself whenever you want; Auto comes
+  back when you switch it on.
+- **Workers picked per task.** The main chat hands work to `ripple:auto`, and the judge decides
+  how hard each task is and sends it to the matching rung: light work to DeepSeek or GLM, hard work
+  to GPT or Opus. Rungs, candidate models and named modes (prefer or avoid a model, eager
+  delegation, switch off at a quota reset) are set on the dashboard. Every pick is kept in
+  `logs/worker-picks.jsonl`.
+- **Warnings that save tokens.** Cards appear when the prompt cache has gone cold on a big chat,
+  when the context gets heavy, and when a plan window passes 80%. Each card offers compact or a
+  handoff.
+- **Handoff to a fresh session.** A handoff writes a summary and opens a new session in the same
+  folder with it in the prompt box. The current chat is left as it is.
+- **리플이**, the mascot, on the band and every card, acting out what the band is doing. Mod text
+  in six languages, following the Mac's system language.
+- **Artificial Analysis scores** for every routable model, refreshed daily, used to rank worker
+  candidates by measured cost.
+- A provider that answers 402 or says its quota is exhausted is skipped for a while.
+
+### Changed
+
+- Dashboard settings are rebuilt in the style of macOS System Settings.
+- The mod's settings live in the router, so every session follows a change at once.
+
+### Fixed
+
+- Judge-only models such as Jev no longer appear in pickers, worker lists or Codex.
+- The install script works under macOS `/bin/sh` again.
+
+## 0.8.10 — 2026-10-10
+
+### Added
+
+- **Choose which Claude account is used first.** With several Claude accounts, the current Claude
+  login was always tried first. Each account card now has a "Use first" button (Providers →
+  Claude → Accounts). New conversations start on that account, move to the next one when it hits
+  its limit, and return to it once the limit resets. A conversation already running stays on its
+  account to keep its cache.
+
+### Fixed
+
+- **DeepSeek subagents no longer fail with 400 on the Artifact tool.** DeepSeek's Anthropic
+  endpoint rejected Claude Desktop's Artifact tool over a regular expression it cannot compile
+  (`"^[^\0]*$" is not a "regex"`). That pattern is now removed on the way out, as it already was for
+  OpenAI-format providers (#51).
+- **The tray starts again after a Windows restart.** Installed with the install script, the tray
+  was set to open at logon without its own script, so Windows opened a bare Electron instead
+  (#50). Restarting the tray once after updating fixes the entry. `clauderipple tray` now also
+  reports a tray that quits right after starting, with its output in `logs/tray.log`. Running it
+  while a tray is already up no longer adds a second icon.
+- **New ChatGPT models show up without the Codex CLI installed.** OpenAI's model list hides
+  models from older Codex versions, and without a Codex CLI the router asked as 0.155.0, so GPT-6.1
+  Sol never appeared (#50). It now asks as the newest published Codex. New models appear unticked in
+  the ChatGPT provider form.
+
 ## 0.8.9 — 2026-10-08
 
 ### Fixed

package/README.es.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <b>Español</b> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/README.ja.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <b>日本語</b> · <a href="README.es.md">Español</a> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/README.ko.md

@@ -1,5 +1,9 @@
 <p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="brand/mark.svg">
+    <img src="brand/mark.svg" width="120" height="120" alt="ClaudeRipple 마스코트 리플이: 속이 빈 파문 고리에 물마루가 말려 오른 모습">
+  </picture>
 </p>
 
 <h1 align="center">ClaudeRipple</h1>

package/README.md

@@ -1,5 +1,9 @@
 <p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="brand/mark.svg">
+    <img src="brand/mark.svg" width="120" height="120" alt="The ClaudeRipple mascot: a hollow ripple ring with a curling wave crest">
+  </picture>
 </p>
 
 <h1 align="center">ClaudeRipple</h1>

package/README.pt-BR.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> · <b>Português (BR)</b></p>

package/README.zh-CN.md

@@ -1,7 +1,3 @@
-<p align="center">
-  <img src="docs/media/icon.png" width="128" alt="ClaudeRipple">
-</p>
-
 <h1 align="center">ClaudeRipple</h1>
 
 <p align="center"><a href="README.md">English</a> · <a href="README.ko.md">한국어</a> · <b>简体中文</b> · <a href="README.ja.md">日本語</a> · <a href="README.es.md">Español</a> · <a href="README.pt-BR.md">Português (BR)</a></p>

package/dist/app/dist/main.js

@@ -512,9 +512,19 @@ function writeAppState(patch) {
         /* a read-only home only costs us the remembered default */
     }
 }
+/**
+ * How Windows starts this tray at login. A packaged app is its own binary. Installed from npm, the
+ * binary is a bare Electron that needs our script after it: registered without one, every logon
+ * opened Electron's default app and no tray (issue #50). macOS ignores `path`/`args`.
+ */
+function loginItemLaunch() {
+    if (electron_1.app.isPackaged || process.platform !== "win32" || !process.argv[1])
+        return undefined;
+    return { path: process.execPath, args: [node_path_1.default.resolve(process.argv[1])] };
+}
 function loginItemOn() {
     try {
-        return electron_1.app.getLoginItemSettings().openAtLogin;
+        return electron_1.app.getLoginItemSettings(loginItemLaunch()).openAtLogin;
     }
     catch {
         return false;
@@ -522,7 +532,7 @@ function loginItemOn() {
 }
 function setLoginItem(on) {
     try {
-        electron_1.app.setLoginItemSettings({ openAtLogin: on });
+        electron_1.app.setLoginItemSettings({ openAtLogin: on, ...loginItemLaunch() });
     }
     catch {
         /* macOS may refuse in an unsigned development build */
@@ -798,7 +808,9 @@ async function offerUpdate(check) {
     availableUpdate = null;
     if (electron_1.Notification.isSupported())
         new electron_1.Notification({ title: "ClaudeRipple", body: L.updateDone(version) }).show();
-    // A new tray from the new files, then this one goes.
+    // A new tray from the new files, then this one goes. The lock is let go first, or the new tray
+    // would see this one and leave.
+    electron_1.app.releaseSingleInstanceLock();
     await runCliResult(["tray"]);
     electron_1.app.quit();
 }
@@ -914,6 +926,10 @@ function render() {
     tray.setContextMenu(electron_1.Menu.buildFromTemplate(template));
     tray.setToolTip(s ? L.tooltip(state) : L.tooltipDown);
 }
+// One tray. `clauderipple tray` run while one is up started a second icon (Windows VM,
+// 2026-10-10); the newcomer now leaves at once with code 0, which the CLI reads as "already running".
+if (!electron_1.app.requestSingleInstanceLock())
+    electron_1.app.exit(0);
 electron_1.app.whenReady().then(() => {
     L = STRINGS[uiLang()];
     // Without this, Windows attributes our notifications to "Electron" instead of ClaudeRipple.
@@ -927,6 +943,10 @@ electron_1.app.whenReady().then(() => {
     // Default to starting at login on first run; after that the user's choice stands.
     if (!appState().loginItemInitialized)
         setLoginItem(true);
+    // An entry an older version wrote names bare Electron (the query without args finds it); the
+    // user had start-at-login on, so it is rewritten with the script rather than left broken.
+    else if (loginItemLaunch() && electron_1.app.getLoginItemSettings().openAtLogin && !loginItemOn())
+        setLoginItem(true);
     tray = new electron_1.Tray(icon("down"));
     tray.on("click", () => tray?.popUpContextMenu());
     render();

package/dist/app/package.json

@@ -1,5 +1,5 @@
 {
   "private": true,
-  "version": "0.8.9",
+  "version": "0.9.0",
   "type": "commonjs"
 }

package/dist/cli/src/codex.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isJudgeOnlyModel } from "../../router/src/model-policy.js";
 const START = "# >>> ClaudeRipple Codex provider >>>";
 const END = "# <<< ClaudeRipple Codex provider <<<";
 const PROFILE_START = "# >>> ClaudeRipple Codex profile >>>";
@@ -76,7 +77,8 @@ export function writeCodexCatalog(models, home = codexHome()) {
     catch {
         return undefined;
     }
-    const entries = (cached.models ?? []).filter((m) => typeof m.slug === "string");
+    models = models.filter(m => !isJudgeOnlyModel(m.id));
+    const entries = (cached.models ?? []).filter((m) => typeof m.slug === "string" && !isJudgeOnlyModel(m.slug));
     const template = entries.find((m) => m.slug === "gpt-5.5" && m.model_messages) ?? entries.find((m) => m.model_messages);
     if (!template)
         return undefined;

package/dist/cli/src/index.js

@@ -647,7 +647,7 @@ try {
             await update();
             break;
         case "tray": {
-            const result = args.includes("--install") ? installTrayRuntime() : startTray();
+            const result = args.includes("--install") ? installTrayRuntime() : await startTray();
             console.log(result.message);
             if (!result.ok)
                 process.exit(1);

package/dist/cli/src/settings.js

@@ -216,11 +216,14 @@ export function agentTitleHookEnabled() {
 }
 // ---- Status mod (packages/mod) ------------------------------------------------------------
 /** The `name` in packages/mod/.claude-plugin/plugin.json: how our entry is told from anyone else's. */
-export const STATUS_MOD_NAME = "clauderipple-status";
+export const STATUS_MOD_NAME = "ripple";
+/** Its name until 0.8.10: an entry an older install added is still ours to replace or remove. */
+const OLD_STATUS_MOD_NAMES = ["clauderipple-status"];
 const PLUGIN_DIRS = "CLAUDE_CODE_PLUGIN_DIRS";
 function isStatusMod(dir) {
     try {
-        return JSON.parse(fs.readFileSync(path.join(dir, ".claude-plugin", "plugin.json"), "utf8")).name === STATUS_MOD_NAME;
+        const name = JSON.parse(fs.readFileSync(path.join(dir, ".claude-plugin", "plugin.json"), "utf8")).name;
+        return name === STATUS_MOD_NAME || OLD_STATUS_MOD_NAMES.includes(name);
     }
     catch {
         return false;

package/dist/cli/src/tray.js

@@ -52,10 +52,11 @@ export function trayEnv(env = process.env) {
     return out;
 }
 /**
- * Starts the tray and returns immediately. `detached` outlives this process, which is what a
- * command typed in a terminal wants; the supervisor uses the foreground form instead.
+ * Starts the tray and returns once it has stayed up for a moment. `detached` outlives this
+ * process, which is what a command typed in a terminal wants; the supervisor uses the foreground
+ * form instead.
  */
-export function startTray(options = {}) {
+export async function startTray(options = {}) {
     const current = runtime();
     if (current.packaged) {
         // The packaged app IS the tray: relaunching its own binary with no script is what opens it.
@@ -75,15 +76,50 @@ export function startTray(options = {}) {
     if (!fs.existsSync(main)) {
         return { ok: false, message: `the tray is not built: ${main} is missing (run: npm run build)` };
     }
+    // Electron's own output goes to a file. With it discarded, a tray that died at launch still
+    // printed "✓ tray started" and left nothing to go on (issue #50).
+    const log = trayLogPath();
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    const out = fs.openSync(log, "a");
     const child = spawn(electron, [main], {
         detached: options.detached ?? true,
-        stdio: "ignore",
+        stdio: ["ignore", out, out],
         // Electron would otherwise re-enter as a plain Node process, since that is how the CLI runs.
         env: trayEnv(),
     });
+    fs.closeSync(out);
     if (options.detached ?? true)
         child.unref();
-    return { ok: true, message: "✓ tray started" };
+    return earlyExit(child, log);
+}
+export function trayLogPath() {
+    return path.join(homeDir(), "logs", "tray.log");
+}
+/** A tray that is still running after a moment has started; one that exits before then has not. */
+export function earlyExit(child, log, waitMs = 2_000) {
+    return new Promise((resolve) => {
+        // Not unref'd: the command has to stay up long enough to see the exit it is waiting for.
+        const timer = setTimeout(() => resolve({ ok: true, message: "✓ tray started" }), waitMs);
+        const failed = (detail) => {
+            clearTimeout(timer);
+            let tail = "";
+            try {
+                tail = fs.readFileSync(log, "utf8").trim().split(/\r?\n/).slice(-8).join("\n");
+            }
+            catch { /* nothing logged */ }
+            resolve({ ok: false, message: `the tray exited at once (${detail}). Its output is in ${log}${tail ? `:\n${tail}` : ""}` });
+        };
+        child.once("error", (error) => failed(error.message));
+        child.once("exit", (code, signal) => {
+            // A clean exit at once is a tray that found another one running (main.ts's single-instance lock).
+            if (code === 0 && !signal) {
+                clearTimeout(timer);
+                resolve({ ok: true, message: "✓ tray is already running" });
+            }
+            else
+                failed(signal ? `signal ${signal}` : `exit code ${code}`);
+        });
+    });
 }
 /** The npm that came with the Node running us, as a script we can hand to that same Node. */
 function npmCli() {

package/dist/mod/.claude-plugin/plugin.json

@@ -1 +1,9 @@
-{ "name": "clauderipple-status", "version": "0.1.0", "description": "Shows where ClaudeRipple sent each request and its request log, and keeps ClaudeRipple workers on their own model and effort.", "types": "./types/index.d.ts" }
+{
+  "name": "ripple",
+  "displayName": "ClaudeRipple",
+  "version": "0.7.0",
+  "description": "Picks the reasoning effort for every prompt and the worker for every delegated task, can keep the prompt cache warm, and shows where ClaudeRipple sent each request.",
+  "author": { "name": "ClaudeRipple" },
+  "license": "GPL-3.0-only",
+  "types": "./types/index.d.ts"
+}

package/dist/mod/hooks/cache.ts

@@ -0,0 +1,60 @@
+import type { ModelForkResult } from 'claude-code'
+import type { CacheMemo, Settings, Usage, WarmState } from '../types'
+import { weighted } from './stats'
+import { t } from './i18n.ts'
+import type { Lang } from './i18n.ts'
+
+const HOUR = 3600000
+const FIVE_MINUTES = 300000
+
+export function ttlFromUsage(usage: Usage): number {
+  if ((usage.cache_creation?.ephemeral_1h_input_tokens ?? 0) > 0) return HOUR
+  if ((usage.cache_creation?.ephemeral_5m_input_tokens ?? 0) > 0) return FIVE_MINUTES
+  return HOUR
+}
+
+/** A five-minute tail must not shorten a mostly-read hour-long prefix. */
+export function nextMemo(prev: CacheMemo | null, usage: Usage, now: number): CacheMemo {
+  const total = (usage.input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0)
+  const mostlyRead = (usage.cache_read_input_tokens ?? 0) > total / 2
+  const explicit = (usage.cache_creation?.ephemeral_1h_input_tokens ?? 0) > 0 || (usage.cache_creation?.ephemeral_5m_input_tokens ?? 0) > 0
+  let ttlMs = explicit ? ttlFromUsage(usage) : prev?.ttlMs ?? HOUR
+  if (prev?.ttlMs === HOUR && mostlyRead) ttlMs = HOUR
+  if (!explicit && prev && now - prev.lastReplyAt > FIVE_MINUTES && mostlyRead) ttlMs = HOUR
+  return { ttlMs, lastReplyAt: now, expiresAt: now + ttlMs }
+}
+
+export function secondsLeft(memo: CacheMemo | null, now: number): number | null {
+  return memo ? Math.max(0, Math.ceil((memo.expiresAt - now) / 1000)) : null
+}
+
+/** Never pay to revive an expired cache or extend the last-real-reply bound with our own pings. */
+export function shouldPing(input: {
+  settings: Settings; memo: CacheMemo | null; warm: WarmState; now: number; idle: boolean
+  contextTokens: number; lastRealReplyAt: number | null
+}): { ping: true } | { ping: false; reason?: string } {
+  const { settings, memo, warm, now } = input
+  if (!settings.keepWarm) return { ping: false, reason: 'keep warm is off' }
+  if (warm.stopped) return { ping: false, reason: warm.stopped }
+  if (!input.idle) return { ping: false, reason: 'chat is busy' }
+  if (!memo || memo.expiresAt <= now) return { ping: false, reason: 'cache is not warm' }
+  if (input.lastRealReplyAt === null || now >= input.lastRealReplyAt + settings.keepWarmHours * HOUR) return { ping: false, reason: 'keep warm time bound reached' }
+  if (input.contextTokens < settings.keepWarmMinTokens) return { ping: false, reason: 'chat is too small' }
+  const lead = memo.ttlMs === FIVE_MINUTES ? 60000 : 240000
+  return memo.expiresAt - now <= lead ? { ping: true } : { ping: false }
+}
+
+/** Failed forks stop once; answered cache misses still count the real tokens they spent. */
+export function afterPing(warm: WarmState, forkResult: ModelForkResult | null, now: number, lang: Lang = 'en'): WarmState {
+  if (!forkResult?.isAnswered) return { ...warm, stopped: t(lang, 'toasts.warmNoReply') }
+  const next: WarmState = { pings: warm.pings + 1, cost: warm.cost + weighted(forkResult.usage), lastPingAt: now }
+  if (forkResult.usage.cache_read_input_tokens <= 0) next.stopped = t(lang, 'toasts.warmNoCache')
+  return next
+}
+
+export function restoreFromResume(secondsSinceLastResponse: number | undefined, likelyExpired: boolean | undefined, ttlMs: number, now: number): CacheMemo | null {
+  if (secondsSinceLastResponse === undefined || !Number.isFinite(secondsSinceLastResponse) || secondsSinceLastResponse < 0) return null
+  const lastReplyAt = now - secondsSinceLastResponse * 1000
+  const expiresAt = lastReplyAt + ttlMs
+  return { ttlMs, lastReplyAt, expiresAt: likelyExpired || expiresAt <= now ? now - 1 : expiresAt }
+}

package/dist/mod/hooks/compact.ts

@@ -0,0 +1,40 @@
+import type { SessionCompacted, SessionMessage } from 'claude-code'
+
+export const COMPACT_SYSTEM = `Create a faithful continuation record of this coding conversation. Keep the user's intent and changes of mind, decisions and constraints, relevant concepts, files and code touched, errors and their fixes, and user feedback. List user requests in order, distinguish solved from pending work, and state exactly what is happening now. Include a next step only when the conversation justifies it. Preserve useful exact paths and commands, but omit secrets, redundant logs, and obsolete detail. Do not invent verification or claim unfinished work is complete. Write in the user's language.`
+
+function clipped(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit)}\n[truncated]` : text
+}
+
+function render(messages: readonly SessionMessage[], tight: boolean): string {
+  return messages.map((message, index) => {
+    const tail = index >= messages.length - 6
+    const inputLimit = tail ? (tight ? 4000 : 20000) : 400
+    const resultLimit = tail ? (tight ? 4000 : 20000) : (tight ? 300 : 2000)
+    const parts = [`${message.role}:\n${message.text}`]
+    for (const use of message.toolUses) {
+      parts.push(`tool ${use.tool} (${use.tool_use_id}):\n${clipped(JSON.stringify(use.input), inputLimit)}`)
+      const result = use.text ?? (use.result !== undefined ? JSON.stringify(use.result) : undefined)
+      if (result !== undefined) parts.push(`result${use.isError ? ' ERROR' : ''}:\n${clipped(result, resultLimit)}`)
+    }
+    if (!message.toolUses.length) {
+      for (const result of message.toolResults ?? []) parts.push(`result ${result.tool_use_id}${result.isError ? ' ERROR' : ''}:\n${clipped(result.text, resultLimit)}`)
+    }
+    return parts.join('\n\n')
+  }).join('\n\n---\n\n')
+}
+
+/** Shrink only tool bulk; losing user intent to hit a budget is worse than engine fallback. */
+export function serializeTranscript(messages: readonly SessionMessage[], budget = 2400000): string | null {
+  if (!messages.length) return null
+  const full = render(messages, false)
+  if (full.length <= budget) return full
+  const tight = render(messages, true)
+  return tight.length <= budget ? tight : null
+}
+
+/** No handle: the engine builds this replacement from role, text and tool blocks. */
+export function compactResult(summary: string): SessionCompacted {
+  return { messages: [{ role: 'user', toolUses: [], text:
+    `Continuation record from the previous conversation:\n\n${summary.trim()}\n\nResume the pending work from this record. Do not repeat completed work or ask for information already recorded.` }] }
+}

package/dist/mod/hooks/handoff.ts

@@ -0,0 +1,43 @@
+import type { SessionMessage } from 'claude-code'
+import type { HandoffKind, Settings } from '../types'
+
+export const QUICK_PROMPT = `Prepare a concise resume note for a fresh coding chat, in the user's language, about forty lines of bullets. Use only this conversation; do not run tools. Record project, folder and branch if known, the goal, verified completed work, unfinished work and blockers, git state as last checked, decisions and failed approaches, permissions or resume details, and the highest-priority runnable next action. Mark actions requiring the user. Keep only current relevant state and point to files or specs instead of copying them. Exclude secrets, environment values and raw logs. Output only the note, without an introduction or farewell.`
+
+export const FULL_PROMPT = `Write a durable handoff for the next coding chat. First verify the working directory, git status, recent commits and whether changes are pushed; check open pull requests if gh is available. Rebuild project-root HANDOFF.md from the current facts, fewer than eighty lines, in the user's language. Include the goal, verified done and undone work, blockers, changed files, decisions and failed approaches, permissions, exact current state and a prioritized next action. Distinguish facts from unverified claims. Never expose secrets, environment values or raw logs. Finish with the saved file path and a concise status for the next chat.`
+
+export function wrapForNewChat(text: string, after: Settings['handoffAfter'], kind: HandoffKind, hasSkill: boolean): string {
+  const source = kind === 'full' && hasSkill ?
+    'First read the saved handoff files named below; if no file is named, read HANDOFF.md. The last answer alone may not contain the handoff.\n\n' : ''
+  const action = after === 'confirm' ?
+    'State the current status and proposed next action in two lines, then wait for my confirmation without starting work.' :
+    'Continue with the justified next action. If it needs my permission or input, explain what is needed and wait.'
+  return `${source}Resume context from the previous chat:\n\n${text.trim()}\n\n${action}`
+}
+
+export const ADVICE_SYSTEM = `Decide whether starting a fresh chat clearly helps this coding work. Recommend it only when completed work is followed by a different task, unrelated history is dead weight, the topic changed, or repeated failed approaches are going in circles. A long chat, high context usage, or an ordinary next step is not enough. When uncertain, do not recommend it. Output only JSON {"handoff":null} or {"handoff":"reason"}, using the user's language and at most eight words.`
+
+/** Cadence counts real eligible prompts, not tool steps, pings or judge requests. */
+export function adviceDue(count: number, percent: number): boolean {
+  return percent >= 30 && Number.isInteger(count) && count > 0 && count % 2 === 0
+}
+
+export function adviceInput(input: { messages: readonly SessionMessage[]; next: string; contextPercent: number; warm: boolean }): string {
+  const users = input.messages.filter(message => message.role === 'user' && message.text.trim())
+  const assistant = input.messages.findLast(message => message.role === 'assistant' && message.text.trim())
+  const trail = users.slice(-8, -1).map(message => message.text.replace(/\s+/g, ' ').slice(0, 160)).join('\n')
+  return [`Context: ${Math.round(input.contextPercent)}%; user messages: ${users.length}; cache: ${input.warm ? 'warm' : 'cold'}`,
+    `Initial request: ${users[0]?.text.slice(0, 500) ?? ''}`, `Earlier requests:\n${trail}`,
+    `Assistant tail: ${assistant?.text.slice(-700) ?? ''}`, `Next request: ${input.next.slice(0, 600)}`].join('\n\n')
+}
+
+export function parseAdvice(text: string): string | null {
+  const span = /\{[\s\S]*\}/.exec(text)?.[0]
+  if (!span) return null
+  try {
+    const value: unknown = JSON.parse(span)
+    if (!value || typeof value !== 'object' || !('handoff' in value)) return null
+    return typeof value.handoff === 'string' && value.handoff.trim() ? value.handoff.trim().slice(0, 70) : null
+  } catch {
+    return null
+  }
+}