Loop control
diff --git a/src/web/public/session-ui.js b/src/web/public/session-ui.js
index 3ec17fe06..82e001cfb 100644
--- a/src/web/public/session-ui.js
+++ b/src/web/public/session-ui.js
@@ -2534,6 +2534,7 @@ Object.assign(CodemanApp.prototype, {
// Populate auto-resume on usage limit (token pause control)
document.getElementById('modalAutoResumeEnabled').checked = session.autoResumeEnabled ?? false;
this.updateAutoResumeStatus(sessionId);
+ this.updatePromptCacheStatus(sessionId);
document.getElementById('modalImageWatcherEnabled').checked = session.imageWatcherEnabled ?? true;
document.getElementById('modalFlickerFilterEnabled').checked = session.flickerFilterEnabled ?? false;
@@ -2784,6 +2785,27 @@ Object.assign(CodemanApp.prototype, {
}
},
+ /**
+ * Session Options → Respawn → "Prompt cache": the main conversation's cache state as
+ * Claude Code reports it on the statusline (`session.promptCache`, v2.1.251+), worded by
+ * the pure `CodemanPromptCache.format` (constants.js). Refreshed on open and on the
+ * `session:promptCache` SSE event while the modal shows that session.
+ */
+ updatePromptCacheStatus(sessionId) {
+ const el = document.getElementById('promptCacheStatus');
+ if (!el || this.editingSessionId !== sessionId) return;
+ const session = this.sessions.get(sessionId);
+ el.textContent = window.CodemanPromptCache.format(session?.promptCache, Date.now(), session?.statusLineExporter);
+ },
+
+ _onSessionPromptCache(data) {
+ const { sessionId, ...promptCache } = data;
+ const session = this.sessions.get(sessionId);
+ if (!session) return;
+ session.promptCache = promptCache;
+ this.updatePromptCacheStatus(sessionId);
+ },
+
async toggleSessionImageWatcher() {
if (!this.editingSessionId) return;
const enabled = document.getElementById('modalImageWatcherEnabled').checked;
diff --git a/src/web/routes/status-telemetry-routes.ts b/src/web/routes/status-telemetry-routes.ts
index b7074c6c2..a568ac74e 100644
--- a/src/web/routes/status-telemetry-routes.ts
+++ b/src/web/routes/status-telemetry-routes.ts
@@ -20,13 +20,14 @@ import { FastifyInstance } from 'fastify';
import { StatusTelemetrySchema } from '../schemas.js';
import { parseBody } from '../route-helpers.js';
import {
+ parsePromptCache,
parseStatusTelemetry,
parseSessionStatus,
formatSessionStatusText,
telemetrySignature,
type RawStatuslinePayload,
} from '../../usage-telemetry.js';
-import { SessionStatusTelemetry } from '../sse-events.js';
+import { SessionPromptCache, SessionStatusTelemetry } from '../sse-events.js';
import { setLatestPlanUsage } from '../plan-usage-latest.js';
import type { SessionPort, EventPort } from '../ports/index.js';
import { getCli } from '../../config/cli-registry/index.js';
@@ -59,6 +60,21 @@ export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: Session
session.noteReportedModel('statusline', payload?.model?.display_name);
}
+ // Prompt-cache state of the main conversation (Claude Code v2.1.251+): kept on the
+ // session for the Session Options readout and `toState()`, broadcast only when the
+ // report changes (the statusline fires on every assistant message). The broadcast
+ // carries the STORED object, so a compaction stamp set in setPromptCache rides along.
+ // Reports are applied in arrival order. When the exporter wraps a user's own statusline
+ // it backgrounds this POST (hooks-config.ts), so two sub-second loopback reports can
+ // arrive out of order; a stale one then briefly overwrites newer state until the next
+ // render corrects it. Accepted for a display-only readout rather than ordered here.
+ const promptCache = parsePromptCache(payload);
+ if (promptCache && session?.setPromptCache(promptCache)) {
+ ctx.broadcast(SessionPromptCache, { sessionId, ...session.promptCache });
+ // Persisted on change, like a model change, so a crash restores the latest report.
+ ctx.persistSessionState(session);
+ }
+
// Plan-usage limits (account-wide) → broadcast to the header chip, when
// present and changed (the statusline fires on every assistant message).
const telemetry = parseStatusTelemetry(payload);
diff --git a/src/web/schemas.ts b/src/web/schemas.ts
index d242a6254..23e0f650a 100644
--- a/src/web/schemas.ts
+++ b/src/web/schemas.ts
@@ -653,6 +653,34 @@ export const StatusTelemetrySchema = z.object({
.nullish(),
cost: z.object({ total_cost_usd: z.number().nullish() }).nullish(),
model: z.object({ display_name: z.string().max(100).nullish() }).nullish(),
+ // Main-conversation prompt-cache statistics (Claude Code v2.1.251+). Every documented
+ // scalar field is listed nullish: `expires_at`/`hit_ratio`/`last_miss_at`/
+ // `recache_tokens_if_cold` are all documented as possibly null, and the object gains
+ // fields over CLI versions, so a stricter shape would 400 the whole post and blank the
+ // footer (the recurring .optional()/null trap). Causes stay `unknown` (the parser keeps
+ // the strings); `last_miss_cause`'s extra numeric keys and the `miss_causes` record are
+ // stripped by Zod unread, which keeps the stored object bounded — a hostile localhost
+ // payload cannot bloat state, since only the normalized subset below is ever stored.
+ prompt_cache: z
+ .object({
+ warm: z.boolean().nullish(),
+ caching_observed: z.boolean().nullish(),
+ // No length cap: a future TTL longer than today's `5m`/`1h` must not 400 the whole
+ // post and blank the footer. parsePromptCache discards any TTL it does not know, so
+ // the stored value stays bounded to those two regardless.
+ ttl: z.string().nullish(),
+ expires_at: z.number().nullish(),
+ requests: z.number().nullish(),
+ misses: z.number().nullish(),
+ expected_rebuilds: z.number().nullish(),
+ hit_ratio: z.number().nullish(),
+ cache_write_tokens: z.number().nullish(),
+ miss_recache_tokens: z.number().nullish(),
+ last_miss_at: z.number().nullish(),
+ recache_tokens_if_cold: z.number().nullish(),
+ last_miss_cause: z.object({ causes: z.array(z.unknown()).max(20).nullish() }).nullish(),
+ })
+ .nullish(),
})
.nullish(),
});
diff --git a/src/web/server.ts b/src/web/server.ts
index bb159e16f..f51884ef4 100644
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -3569,6 +3569,11 @@ export class WebServer extends EventEmitter {
// tile header keeps naming it until the next report; an idle claude
// session re-renders its statusline only on its next turn.
displayModel: savedState?.displayModel,
+ // The last prompt-cache report, restored for the same reason: an idle claude
+ // session re-renders its statusline only on its next turn, so without this the
+ // Session Options readout would read "not reported yet" after every restart. The
+ // readout is time-aware, so a value past its expiry shows as cold, not stale-warm.
+ promptCache: savedState?.promptCache,
// A record rebuilt from the socket has no provenance, so its
// apparent locality is a guess (see `MuxSession.discovered`).
discoveredMuxSession: muxSession.discovered,
diff --git a/src/web/sse-events.ts b/src/web/sse-events.ts
index f18fbf6d3..b7020b9d2 100644
--- a/src/web/sse-events.ts
+++ b/src/web/sse-events.ts
@@ -5,10 +5,10 @@
* and referenced by the frontend (`SSE_EVENTS` in `constants.js`).
* Both files MUST be kept in sync.
*
- * 161 event constants organized by category:
+ * 162 event constants organized by category:
* - **Core** (1): init
* - **Transport** (1): sse:heartbeat
- * - **Session lifecycle** (23): created, updated, deleted, terminal, idle, working, ...
+ * - **Session lifecycle** (24): created, updated, deleted, terminal, idle, working, ...
* - **Session: Ralph** (6): ralphLoopUpdate, todoUpdate, completionDetected, ...
* - **Session: Bash tools** (3): bashToolStart, bashToolEnd, bashToolsUpdate
* - **Session: Plan** (4): planTaskUpdate, planCheckpoint, planRollback, planTaskAdded
@@ -119,6 +119,8 @@ export const SessionInteractive = 'session:interactive' as const;
export const SessionRunning = 'session:running' as const;
/** Combined Claude and main Codex plan-usage telemetry for the shared header chip. */
export const SessionStatusTelemetry = 'session:statusTelemetry' as const;
+/** Prompt-cache state of one session's main conversation changed (`{ sessionId, ...PromptCacheStatus }`). */
+export const SessionPromptCache = 'session:promptCache' as const;
// ─── Session: Ralph ──────────────────────────────────────────────────────────
@@ -526,6 +528,7 @@ export const SseEvent = {
SessionInteractive,
SessionRunning,
SessionStatusTelemetry,
+ SessionPromptCache,
// Session: Ralph
SessionRalphLoopUpdate,
diff --git a/test/mocks/mock-session.ts b/test/mocks/mock-session.ts
index 17c838ae2..9b5d01fe6 100644
--- a/test/mocks/mock-session.ts
+++ b/test/mocks/mock-session.ts
@@ -4,7 +4,7 @@
*/
import { EventEmitter } from 'node:events';
import { vi } from 'vitest';
-import type { SessionAttachmentHistoryItem, SessionStatus, SessionRemote } from '../../src/types.js';
+import type { PromptCacheStatus, SessionAttachmentHistoryItem, SessionStatus, SessionRemote } from '../../src/types.js';
/**
* Enhanced mock session for testing RespawnController.
@@ -41,6 +41,13 @@ export class MockSession extends EventEmitter {
* need to be able to set it.
*/
watching: string | null = null;
+ /** Mirrors Session.promptCache / setPromptCache (fed by POST /api/status-telemetry). */
+ promptCache: PromptCacheStatus | null = null;
+ setPromptCache(status: PromptCacheStatus): boolean {
+ const changed = JSON.stringify(status) !== JSON.stringify(this.promptCache);
+ this.promptCache = status;
+ return changed;
+ }
private _activeChildProcesses: { pid: number; command: string }[] = [];
ralphTracker: null = null;
writeBuffer: string[] = [];
diff --git a/test/prompt-cache-status.test.ts b/test/prompt-cache-status.test.ts
new file mode 100644
index 000000000..6f3e90263
--- /dev/null
+++ b/test/prompt-cache-status.test.ts
@@ -0,0 +1,89 @@
+/**
+ * The Session Options "Prompt cache" readout (`CodemanPromptCache.format`, constants.js):
+ * the one sentence that tells the user whether the next turn reads the conversation
+ * from cache or re-processes it cold. Loaded the way the other constants.js policies are.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import vm from 'node:vm';
+
+type Cache = {
+ warm: boolean;
+ ttl?: string;
+ expiresAt?: number;
+ recacheTokensIfCold?: number;
+ hitRatio?: number;
+ lastMissCauses?: string[];
+ compactedAt?: number;
+};
+
+function loadFormat() {
+ const context = vm.createContext({ window: {}, globalThis: {} });
+ const source = readFileSync(resolve(import.meta.dirname, '../src/web/public/constants.js'), 'utf8');
+ vm.runInContext(source, context, { filename: 'constants.js' });
+ return (context.window as { CodemanPromptCache: { format: (c: Cache | null | undefined, now: number) => string } })
+ .CodemanPromptCache.format as (c: Cache | null | undefined, now: number, statusLine?: string) => string;
+}
+
+const clock = (ms: number) => new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
+const NOW = Date.UTC(2026, 9, 6, 22, 18, 0);
+
+describe('Prompt cache readout', () => {
+ it('says so when Claude has not reported the cache yet (older CLI or no response yet)', () => {
+ const format = loadFormat();
+ expect(format(null, NOW)).toMatch(/^Not reported yet/);
+ expect(format(undefined, NOW)).toMatch(/^Not reported yet/);
+ });
+
+ it('says why when the launch carries no statusLine exporter, whatever report is stored', () => {
+ const format = loadFormat();
+ expect(format(null, NOW, 'collection-off')).toMatch(/^Not collected: Plan Usage was off when this session started/);
+ expect(format({ warm: true, expiresAt: NOW + 60_000 }, NOW, 'collection-off')).toMatch(/^Not collected/);
+ expect(format(null, NOW, 'workspace-statusline')).toMatch(/settings\.local\.json sets its own statusLine/);
+ expect(format(null, NOW, 'remote')).toBe('Not collected for remote and Docker sessions.');
+ expect(format(null, NOW, 'injected')).toMatch(/^Not reported yet/);
+ });
+
+ it('warm: a clock time, the lifetime and the tokens at stake', () => {
+ const format = loadFormat();
+ const expiresAt = NOW + 42 * 60_000;
+ expect(format({ warm: true, ttl: '1h', expiresAt, recacheTokensIfCold: 109833 }, NOW)).toBe(
+ `Warm until ${clock(expiresAt)} (1h cache). About 110k tokens would be re-cached if it goes cold.`
+ );
+ expect(format({ warm: true, expiresAt }, NOW)).toBe(`Warm until ${clock(expiresAt)}.`);
+ });
+
+ it('cold once reported cold, past the expiry, or warm with no expiry to promise', () => {
+ const format = loadFormat();
+ expect(format({ warm: false, recacheTokensIfCold: 89882 }, NOW)).toBe(
+ 'Cold. The next turn re-caches about 90k tokens.'
+ );
+ expect(format({ warm: true, expiresAt: NOW - 1, recacheTokensIfCold: 500 }, NOW)).toBe(
+ 'Cold. The next turn re-caches about 500 tokens.'
+ );
+ expect(format({ warm: true }, NOW)).toBe('Cold.');
+ expect(format({ warm: false }, NOW)).toBe('Cold.');
+ });
+
+ it('appends the hit rate and the last miss cause when Claude reports them', () => {
+ const format = loadFormat();
+ const expiresAt = NOW + 42 * 60_000;
+ expect(format({ warm: true, ttl: '1h', expiresAt, recacheTokensIfCold: 50000, hitRatio: 0.91 }, NOW)).toBe(
+ `Warm until ${clock(expiresAt)} (1h cache). About 50k tokens would be re-cached if it goes cold. 91% cache hit rate.`
+ );
+ expect(
+ format({ warm: false, recacheTokensIfCold: 90000, hitRatio: 0.6, lastMissCauses: ['ttl_expired_1h'] }, NOW)
+ ).toBe('Cold. The next turn re-caches about 90k tokens. 60% cache hit rate. Last miss: ttl_expired_1h.');
+ });
+
+ it('names a compaction, with no re-cache stake while the prefix is still warm', () => {
+ const format = loadFormat();
+ const expiresAt = NOW + 42 * 60_000;
+ const compactedAt = NOW - 6 * 60_000;
+ // recacheTokensIfCold is null right after a compaction, so no "would be re-cached" clause.
+ expect(format({ warm: true, ttl: '1h', expiresAt, compactedAt, hitRatio: 0.88 }, NOW)).toBe(
+ `Warm until ${clock(expiresAt)} (1h cache). Context compacted at ${clock(compactedAt)}. 88% cache hit rate.`
+ );
+ });
+});
diff --git a/test/routes/status-telemetry-routes.test.ts b/test/routes/status-telemetry-routes.test.ts
index f85b8c693..0741b17f1 100644
--- a/test/routes/status-telemetry-routes.test.ts
+++ b/test/routes/status-telemetry-routes.test.ts
@@ -6,13 +6,14 @@
* skip, per-session change-detection (dedup), rebroadcast on a displayed change,
* NO rebroadcast on context-only drift, null-tolerance of Claude's undocumented
* fields (the .nullish() schema — the project's recurring .optional()/null trap),
+ * the prompt-cache group of the footer (warm and cold shapes of `prompt_cache`),
* and 400 on a malformed body. Also the session's model (`displayModel`) the route
* records off the same payload.
*/
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { createRouteTestHarness, type RouteTestHarness } from './_route-test-utils.js';
import { registerStatusTelemetryRoutes } from '../../src/web/routes/status-telemetry-routes.js';
-import { SessionStatusTelemetry } from '../../src/web/sse-events.js';
+import { SessionPromptCache, SessionStatusTelemetry } from '../../src/web/sse-events.js';
import { Session } from '../../src/session.js';
const SID = 'test-session-1'; // default id created by createMockRouteContext
@@ -97,6 +98,62 @@ describe('POST /api/status-telemetry', () => {
expect(payload.sevenDay).toBeUndefined();
});
+ it('prints the prompt-cache state in the footer: a clock time while warm, cold once Claude says so', async () => {
+ const expiresAtS = Math.floor(Date.now() / 1000) + 3600;
+ const warm = await post({
+ sessionId: SID,
+ data: {
+ ...REAL,
+ prompt_cache: { warm: true, ttl: '1h', expires_at: expiresAtS, recache_tokens_if_cold: 109833 },
+ },
+ });
+ expect(warm.statusCode).toBe(200);
+ expect(warm.body).toMatch(/^Opus 4\.8 \(1M context\) in:562,411 out:1,188 ctx:56% cache:until \d\d:\d\d$/);
+
+ // The cold flip Claude sends when expires_at passes: null expiry, and a last_miss_cause
+ // that carries numeric detail keys beside `causes` (must not 400, which would blank the footer).
+ const cold = await post({
+ sessionId: SID,
+ data: {
+ ...REAL,
+ prompt_cache: {
+ warm: false,
+ ttl: '1h',
+ expires_at: null,
+ misses: 1,
+ last_miss_cause: { causes: ['ttl_expired_1h'], system_char_delta: 0 },
+ },
+ },
+ });
+ expect(cold.statusCode).toBe(200);
+ expect(cold.body.endsWith(' cache:cold')).toBe(true);
+
+ // The report is kept on the session (toState / Session Options readout) and each CHANGE
+ // is broadcast on its own event; the plan chip did not change, so it broadcast once.
+ const session = h.ctx.sessions.get(SID) as unknown as { promptCache: { warm: boolean } | null };
+ expect(session.promptCache).toMatchObject({
+ warm: false,
+ ttl: '1h',
+ misses: 1,
+ lastMissCauses: ['ttl_expired_1h'],
+ });
+ const events = h.ctx.broadcast.mock.calls.map(([name]) => name);
+ expect(events.filter((e) => e === SessionStatusTelemetry)).toHaveLength(1);
+ expect(events.filter((e) => e === SessionPromptCache)).toHaveLength(2);
+ expect(h.ctx.broadcast).toHaveBeenCalledWith(
+ SessionPromptCache,
+ expect.objectContaining({ sessionId: SID, warm: true, ttl: '1h', recacheTokensIfCold: 109833 })
+ );
+ });
+
+ it('does not rebroadcast an unchanged prompt-cache report', async () => {
+ const pc = { warm: true, ttl: '1h', expires_at: Math.floor(Date.now() / 1000) + 3600 };
+ await post({ sessionId: SID, data: { ...REAL, prompt_cache: pc } });
+ await post({ sessionId: SID, data: { ...REAL, prompt_cache: pc } });
+ const events = h.ctx.broadcast.mock.calls.map(([name]) => name);
+ expect(events.filter((e) => e === SessionPromptCache)).toHaveLength(1);
+ });
+
it('rejects a malformed body (missing sessionId) with 400', async () => {
const res = await post({ data: REAL });
expect(res.statusCode).toBe(400);
@@ -154,4 +211,46 @@ describe('POST /api/status-telemetry: the session model (displayModel)', () => {
await post({ sessionId: 'codex-1', data: { model: { display_name: 'Opus 4.8' } } });
expect(session.toState().displayModel).toBeUndefined();
});
+
+ it('broadcasts the STORED prompt-cache object, so a compaction stamp reaches the live readout', async () => {
+ const session = realSession('claude', 'claude-compact');
+ const expiresAtS = Math.floor(Date.now() / 1000) + 3600;
+ // The order Claude Code really reports in: a warm report with 500k at stake, then
+ // `/compact` finishes (recache null, expected_rebuilds unchanged), and the session stamps
+ // compactedAt in setPromptCache on entering that window.
+ await post({
+ sessionId: 'claude-compact',
+ data: {
+ prompt_cache: {
+ warm: true,
+ ttl: '1h',
+ expires_at: expiresAtS,
+ expected_rebuilds: 0,
+ recache_tokens_if_cold: 500000,
+ },
+ },
+ });
+ await post({
+ sessionId: 'claude-compact',
+ data: { prompt_cache: { warm: true, ttl: '1h', expires_at: expiresAtS, expected_rebuilds: 0 } },
+ });
+ expect(typeof session.toState().promptCache?.compactedAt).toBe('number');
+ // The broadcast must carry the stored object, not just the freshly parsed one, or the
+ // frontend's live update would never see the stamp (only a modal reopen would).
+ const last = (h.ctx.broadcast.mock.calls as [string, Record][])
+ .filter(([name]) => name === SessionPromptCache)
+ .at(-1)?.[1];
+ expect(last).toMatchObject({ sessionId: 'claude-compact', warm: true });
+ expect(typeof last?.compactedAt).toBe('number');
+ });
+
+ it('persists a changed prompt-cache report, and only a changed one', async () => {
+ const session = realSession('claude', 'claude-persist');
+ const data = { prompt_cache: { warm: true, ttl: '1h', expires_at: Math.floor(Date.now() / 1000) + 3600 } };
+ await post({ sessionId: 'claude-persist', data });
+ expect(h.ctx.persistSessionState).toHaveBeenCalledWith(session);
+ h.ctx.persistSessionState.mockClear();
+ await post({ sessionId: 'claude-persist', data });
+ expect(h.ctx.persistSessionState).not.toHaveBeenCalled();
+ });
});
diff --git a/test/session-prompt-cache.test.ts b/test/session-prompt-cache.test.ts
new file mode 100644
index 000000000..9f9fa9425
--- /dev/null
+++ b/test/session-prompt-cache.test.ts
@@ -0,0 +1,130 @@
+/**
+ * Session.setPromptCache's compaction detection and the restore of the last report.
+ *
+ * The statusline never reports WHEN the context was compacted, so the session stamps it.
+ * Claude Code's tracker (2.1.294-2.1.296) opens a window at a compaction or a tool-result
+ * clearing in which `recacheTokensIfCold` reads null, and closes it on the next request,
+ * which is also the one that counts as an expected rebuild. So `expectedRebuilds` never rises
+ * inside the window, and the stamp fires on ENTERING it: a warm null report after one that
+ * carried a value. It is carried through idle re-reports, dropped at the next request, and a
+ * first report already inside the window never invents one. The fixtures follow that real
+ * order. The last report is restored through the constructor (keeping an old stamp, never
+ * re-stamping at restart time), and a conversation switch drops it.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Session } from '../src/session.js';
+import type { PromptCacheStatus } from '../src/types.js';
+
+function claudeSession(extra: Record = {}): Session {
+ return new Session({ workingDir: '/tmp', mode: 'claude', ...extra } as ConstructorParameters[0]);
+}
+
+describe('Session.setPromptCache compaction detection', () => {
+ afterEach(() => vi.useRealTimers());
+
+ it('stamps when /compact finishes, keeps the stamp through idle re-reports, drops it at the next request', () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date('2026-10-06T22:05:00Z'));
+ const s = claudeSession();
+ const expiresAt = Date.now() + 3600_000;
+
+ // 1. Warm, 500k at stake.
+ s.setPromptCache({ warm: true, ttl: '1h', expiresAt, expectedRebuilds: 0, recacheTokensIfCold: 500000 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+
+ // 2. `/compact` finishes: recache null (absent after parsing), expected_rebuilds unchanged.
+ vi.setSystemTime(new Date('2026-10-06T22:31:00Z'));
+ s.setPromptCache({ warm: true, ttl: '1h', expiresAt, expectedRebuilds: 0 });
+ expect(s.promptCache?.compactedAt).toBe(Date.parse('2026-10-06T22:31:00Z'));
+
+ // An idle re-report inside the same window: the stamp is carried, not re-stamped.
+ vi.setSystemTime(new Date('2026-10-06T22:45:00Z'));
+ s.setPromptCache({ warm: true, ttl: '1h', expiresAt, expectedRebuilds: 0 });
+ expect(s.promptCache?.compactedAt).toBe(Date.parse('2026-10-06T22:31:00Z'));
+
+ // 3. The next request closes the window: expected_rebuilds 1, recache 40k.
+ s.setPromptCache({ warm: true, ttl: '1h', expiresAt, expectedRebuilds: 1, recacheTokensIfCold: 40000 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+ });
+
+ it('never stamps a first report that is already inside the window', () => {
+ // The first report Codeman sees (a restart mid-window) has no prior value to leave.
+ const s = claudeSession();
+ s.setPromptCache({ warm: true, expiresAt: Date.now() + 3600_000, expectedRebuilds: 4 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+ // Nor does a later report in the same window: the stamp needs a known value before it.
+ s.setPromptCache({ warm: true, expiresAt: Date.now() + 3600_000, expectedRebuilds: 4 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+ });
+
+ it('never stamps a cold report or a report that still carries the stake', () => {
+ const s = claudeSession();
+ s.setPromptCache({ warm: true, expiresAt: Date.now() + 3600_000, recacheTokensIfCold: 60000 });
+ // Cold with no stake: an expired cache, not a compaction.
+ s.setPromptCache({ warm: false, expectedRebuilds: 0 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+ // A rebuild count that rose with the stake present is the request after a window, not one.
+ s.setPromptCache({ warm: true, expiresAt: Date.now() + 3600_000, expectedRebuilds: 2, recacheTokensIfCold: 60000 });
+ expect(s.promptCache?.compactedAt).toBeUndefined();
+ });
+
+ it('reports changed only when the stored object differs', () => {
+ const s = claudeSession();
+ const pc: PromptCacheStatus = { warm: true, ttl: '1h', expiresAt: 1, recacheTokensIfCold: 10 };
+ expect(s.setPromptCache({ ...pc })).toBe(true);
+ expect(s.setPromptCache({ ...pc })).toBe(false);
+ expect(s.setPromptCache({ ...pc, warm: false })).toBe(true);
+ });
+});
+
+describe('prompt-cache report survives a restart', () => {
+ it('restores the constructor value onto the session and toState, and a new report replaces it', () => {
+ const restored: PromptCacheStatus = { warm: true, ttl: '1h', expiresAt: 1, recacheTokensIfCold: 25000, misses: 1 };
+ const s = claudeSession({ promptCache: restored });
+ expect(s.promptCache).toEqual(restored);
+ expect(s.toState().promptCache).toEqual(restored);
+ s.setPromptCache({ warm: false });
+ expect(s.toState().promptCache).toEqual({ warm: false });
+ });
+
+ it('is absent, not null, when nothing was restored', () => {
+ const s = claudeSession();
+ expect(s.promptCache).toBeNull();
+ expect(s.toState().promptCache).toBeUndefined();
+ });
+
+ it('restores a post-compaction value WITHOUT re-stamping it at restart time', () => {
+ // A direct restore, not a setPromptCache call: a report from inside the window (recache
+ // absent, an OLD compactedAt) must keep its original timestamp through construction,
+ // never be re-stamped with "now" as a fresh compaction.
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date('2026-10-06T23:59:00Z'));
+ const oldStamp = Date.parse('2026-10-06T22:31:00Z');
+ const s = claudeSession({
+ promptCache: {
+ warm: true,
+ ttl: '1h',
+ expiresAt: Date.now() + 600_000,
+ expectedRebuilds: 3,
+ compactedAt: oldStamp,
+ },
+ });
+ expect(s.promptCache?.compactedAt).toBe(oldStamp);
+ vi.useRealTimers();
+ });
+});
+
+describe('a conversation switch drops the prompt-cache report', () => {
+ it('clears it when the Claude conversation id changes, keeps it on a same-id reattach', () => {
+ const s = claudeSession();
+ s.adoptClaudeSessionId('conv-a', { firstHand: true }); // establish the current conversation
+ s.setPromptCache({ warm: true, ttl: '1h', expiresAt: Date.now() + 600_000, expectedRebuilds: 0 });
+ // A hook reports the SAME conversation (a reattach): the report must survive.
+ s.adoptClaudeSessionId('conv-a', { firstHand: true });
+ expect(s.promptCache).not.toBeNull();
+ // A post-/clear switch to a NEW conversation: the old prefix's state is gone.
+ s.adoptClaudeSessionId('conv-b', { firstHand: true });
+ expect(s.promptCache).toBeNull();
+ expect(s.toState().promptCache).toBeUndefined();
+ });
+});
diff --git a/test/statusline-cli-flag.test.ts b/test/statusline-cli-flag.test.ts
index dd85368a2..929fa0f52 100644
--- a/test/statusline-cli-flag.test.ts
+++ b/test/statusline-cli-flag.test.ts
@@ -15,9 +15,13 @@
* sees.
*/
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { execFileSync } from 'node:child_process';
-import { buildSpawnCommand } from '../src/tmux-manager.js';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { buildSpawnCommand, TmuxManager } from '../src/tmux-manager.js';
+import { SETTINGS_PATH } from '../src/web/route-helpers.js';
const EXPORTER_CMD = 'curl -sfk -X POST "$CODEMAN_API_URL/api/status-telemetry" --data @- 2>/dev/null || true';
@@ -94,3 +98,52 @@ describe('buildSpawnCommand statusLineCommand (claude mode)', () => {
expect(cmd).not.toContain('--settings');
});
});
+
+// Why a launch does or does not carry the exporter. Recorded on the mux record and
+// published as `statusLineExporter`, so the Status row can say why no
+// cache report will come instead of "not reported yet" forever.
+describe('TmuxManager statusLine classification', () => {
+ type Resolve = (
+ mode: string,
+ workingDir: string,
+ remoteOrDocker: boolean
+ ) => Promise<{ command?: string; state?: string }>;
+ let workingDir: string;
+ let resolve: Resolve;
+
+ beforeEach(() => {
+ workingDir = mkdtempSync(join(tmpdir(), 'statusline-state-'));
+ const mux = new TmuxManager() as unknown as { _resolveStatusLine: Resolve };
+ resolve = mux._resolveStatusLine.bind(mux);
+ mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+ });
+ afterEach(() => {
+ rmSync(workingDir, { recursive: true, force: true });
+ rmSync(SETTINGS_PATH, { force: true });
+ });
+
+ it('injected when plan-usage collection is on (an absent key reads as on)', async () => {
+ const r = await resolve('claude', workingDir, false);
+ expect(r.state).toBe('injected');
+ expect(r.command).toBeTruthy();
+ });
+
+ it('collection-off when the setting is explicitly false', async () => {
+ writeFileSync(SETTINGS_PATH, JSON.stringify({ showPlanUsageLimits: false }));
+ expect(await resolve('claude', workingDir, false)).toEqual({ command: undefined, state: 'collection-off' });
+ });
+
+ it("workspace-statusline when the workspace's settings.local.json sets its own", async () => {
+ mkdirSync(join(workingDir, '.claude'));
+ writeFileSync(
+ join(workingDir, '.claude', 'settings.local.json'),
+ JSON.stringify({ statusLine: { type: 'command', command: 'echo mine' } })
+ );
+ expect(await resolve('claude', workingDir, false)).toEqual({ command: undefined, state: 'workspace-statusline' });
+ });
+
+ it('remote for remote and docker launches, nothing at all for a CLI without the capability', async () => {
+ expect(await resolve('claude', workingDir, true)).toEqual({ state: 'remote' });
+ expect(await resolve('codex', workingDir, false)).toEqual({});
+ });
+});
diff --git a/test/usage-telemetry.test.ts b/test/usage-telemetry.test.ts
index f5797dcb5..3d1ee7b87 100644
--- a/test/usage-telemetry.test.ts
+++ b/test/usage-telemetry.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
import {
parseStatusTelemetry,
parseSessionStatus,
+ parsePromptCache,
formatSessionStatusText,
telemetrySignature,
type RawStatuslinePayload,
@@ -88,7 +89,111 @@ describe('parseStatusTelemetry', () => {
});
});
+// Mirrors a captured `prompt_cache` object (CC 2.1.280, Claude Max, 1h TTL) from a
+// session whose first turn finished at 23:00:06Z; expires_at is epoch SECONDS.
+const EXPIRES_AT_S = Date.UTC(2026, 9, 6, 23, 0, 6) / 1000;
+const WARM_CACHE: RawStatuslinePayload = {
+ prompt_cache: {
+ warm: true,
+ ttl: '1h',
+ expires_at: EXPIRES_AT_S,
+ recache_tokens_if_cold: 109833,
+ misses: 0,
+ last_miss_cause: null,
+ },
+};
+
+/** The footer prints the server-local clock, so derive the expected text the same way. */
+function localHHMM(ms: number): string {
+ const d = new Date(ms);
+ return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+
+describe('parsePromptCache', () => {
+ it('normalizes the captured object, converting expires_at seconds to ms', () => {
+ expect(parsePromptCache(WARM_CACHE)).toEqual({
+ warm: true,
+ ttl: '1h',
+ expiresAt: EXPIRES_AT_S * 1000,
+ recacheTokensIfCold: 109833,
+ misses: 0,
+ });
+ });
+
+ it('keeps a cold report (warm:false, null expires_at) and the diagnosed miss causes', () => {
+ expect(
+ parsePromptCache({
+ prompt_cache: {
+ warm: false,
+ ttl: '1h',
+ expires_at: null,
+ misses: 1,
+ // Real shape: numeric detail keys ride next to `causes`
+ last_miss_cause: { causes: ['ttl_expired_1h', 7, ''] } as never,
+ },
+ })
+ ).toEqual({ warm: false, ttl: '1h', misses: 1, lastMissCauses: ['ttl_expired_1h'] });
+ });
+
+ it('returns null when the payload has no prompt_cache or warm is not a boolean (state unknown, not cold)', () => {
+ expect(parsePromptCache(undefined)).toBeNull();
+ expect(parsePromptCache({})).toBeNull();
+ expect(parsePromptCache({ prompt_cache: null })).toBeNull();
+ expect(parsePromptCache({ prompt_cache: { warm: null, ttl: '1h' } })).toBeNull();
+ });
+
+ it('drops a TTL it does not know and a non-positive or non-finite expiry', () => {
+ expect(parsePromptCache({ prompt_cache: { warm: true, ttl: '2h', expires_at: 0 } })).toEqual({ warm: true });
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: Number.NaN } })).toEqual({ warm: true });
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: -5 } })).toEqual({ warm: true });
+ });
+
+ it('drops an expiry that overflows or leaves the Date range after the seconds->ms multiply', () => {
+ // These pass `expires_at > 0 && isFinite` on the SECONDS but render "cache:until NaN:NaN"
+ // once converted, so the converted ms must be validated too (finite, within Date range).
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: Number.POSITIVE_INFINITY } })).toEqual({
+ warm: true,
+ });
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: 1e308 } })).toEqual({ warm: true }); // *1000 = Infinity
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: 1e14 } })).toEqual({ warm: true }); // 1e17 ms, out of range
+ // The documented boundary still parses (8.64e15 ms = 8.64e12 s).
+ expect(parsePromptCache({ prompt_cache: { warm: true, expires_at: 8.64e12 } })).toEqual({
+ warm: true,
+ expiresAt: 8.64e15,
+ });
+ });
+
+ it('keeps hit_ratio (clamped 0-1) and expected_rebuilds (rounded, non-negative)', () => {
+ expect(parsePromptCache({ prompt_cache: { warm: true, hit_ratio: 0.91, expected_rebuilds: 2 } })).toEqual({
+ warm: true,
+ hitRatio: 0.91,
+ expectedRebuilds: 2,
+ });
+ // Out-of-range or non-finite values are clamped or dropped, never stored as-is.
+ expect(parsePromptCache({ prompt_cache: { warm: true, hit_ratio: 1.5 } })).toEqual({ warm: true, hitRatio: 1 });
+ expect(parsePromptCache({ prompt_cache: { warm: true, hit_ratio: -0.2 } })).toEqual({ warm: true, hitRatio: 0 });
+ // expected_rebuilds is rounded and floored at 0 (it indexes the compaction rise).
+ expect(parsePromptCache({ prompt_cache: { warm: true, expected_rebuilds: 2.9 } })).toEqual({
+ warm: true,
+ expectedRebuilds: 3,
+ });
+ expect(parsePromptCache({ prompt_cache: { warm: true, expected_rebuilds: -4 } })).toEqual({
+ warm: true,
+ expectedRebuilds: 0,
+ });
+ expect(parsePromptCache({ prompt_cache: { warm: true, hit_ratio: null, expected_rebuilds: null } })).toEqual({
+ warm: true,
+ });
+ });
+});
+
describe('parseSessionStatus', () => {
+ it('carries the prompt-cache state into the footer status', () => {
+ expect(parseSessionStatus({ ...REAL, ...WARM_CACHE })?.cache).toEqual(parsePromptCache(WARM_CACHE));
+ // prompt_cache alone IS session status (a cold flip arrives with nothing else changed)
+ expect(parseSessionStatus(WARM_CACHE)).toEqual({ cache: parsePromptCache(WARM_CACHE) });
+ });
+
it('extracts model, token totals, and context % for the footer', () => {
const s = parseSessionStatus(REAL);
expect(s).toEqual({
@@ -123,6 +228,22 @@ describe('formatSessionStatusText', () => {
expect(formatSessionStatusText(null)).toBe('');
expect(formatSessionStatusText({} as never)).toBe('');
});
+
+ it('shows the warm cache as a server-local clock time, not a countdown that would sit stale', () => {
+ const expiresAt = EXPIRES_AT_S * 1000;
+ const now = expiresAt - 42 * 60_000;
+ expect(formatSessionStatusText(parseSessionStatus({ ...REAL, ...WARM_CACHE }), now)).toBe(
+ `Opus 4.8 (1M context) in:562,411 out:1,188 ctx:56% cache:until ${localHHMM(expiresAt)}`
+ );
+ });
+
+ it('shows cache:cold once Claude reports it cold or the render happened past expires_at', () => {
+ const expiresAt = EXPIRES_AT_S * 1000;
+ expect(formatSessionStatusText({ cache: { warm: false } })).toBe('cache:cold');
+ expect(formatSessionStatusText({ cache: { warm: true, expiresAt } }, expiresAt + 1)).toBe('cache:cold');
+ // warm without an expiry is unknowable, so it is not promised as warm
+ expect(formatSessionStatusText({ cache: { warm: true } })).toBe('cache:cold');
+ });
});
describe('telemetrySignature', () => {