aicodeman 1.43.0 → 1.44.0

package/dist/mux-interface.d.ts

@@ -39,9 +39,15 @@ export interface MuxSession {
     ralphEnabled?: boolean;
     /** Whether the current launch carries the statusLine exporter; set on every create and respawn. */
     statusLine?: StatusLineExporter;
+    /**
+     * Whether the current launch carries `idleCompaction: false` in its `--settings` JSON (keep-warm
+     * on at launch, the exporter injected, Claude Code new enough); set on every create and respawn.
+     */
+    idleCompactionOff?: boolean;
     /**
      * This record was rebuilt from the tmux socket rather than from Codeman's own
-     * bookkeeping, so everything on it but the name and the pid is a guess. Its
+     * bookkeeping, so everything on it but the name, the pid and, when tmux
+     * reported a usable one, the directory is a guess. Its
      * synthetic `restored-<fragment>` id cannot find the session's `state.json`
      * entry either, which means a remote or docker session rediscovered this way
      * arrives with no `remote`/`docker` metadata and looks local. Anything that
@@ -99,6 +105,10 @@ export interface CreateSessionOptions {
     effort?: EffortLevel;
     /** Claude advisor model, merged into the same `--settings` JSON (overridable via /advisor in-session) */
     advisorModel?: string;
+    /** The session's own prompt-cache keep-warm choice (undefined = app default); decides the `idleCompaction` opt-out. */
+    keepWarm?: boolean;
+    /** Spawned by another session: it does not inherit the keep-warm app default (`keepWarmOn`). */
+    spawnedByAgent?: boolean;
     /** tmux history-limit (scrollback lines) allocated when this session is created. */
     historyLimit?: number;
     /** Remote execution metadata for local tmux sessions wrapping SSH */
@@ -151,6 +161,10 @@ export interface RespawnPaneOptions {
     effort?: EffortLevel;
     /** Claude advisor model (preserved across respawns, merged into the same `--settings` JSON) */
     advisorModel?: string;
+    /** The session's own prompt-cache keep-warm choice, re-read at every relaunch (see CreateSessionOptions). */
+    keepWarm?: boolean;
+    /** Spawned by another session (see CreateSessionOptions). */
+    spawnedByAgent?: boolean;
     /** Original tmux history-limit retained for config parity; respawn cannot resize the existing pane. */
     historyLimit?: number;
     /** Remote execution metadata for local tmux sessions wrapping SSH */
@@ -344,12 +358,15 @@ export interface TerminalMultiplexer extends EventEmitter {
      */
     captureActivePaneBuffer?(muxName: string, opts?: PaneCaptureOptions): string | null;
     /**
-     * Plain text of the visible frame: no styles, no cursor query, no repaint
-     * reconstruction. Deliberately cheaper than `capturePaneBuffer` because idle
+     * Plain text of the visible frame: no cursor query, no repaint
+     * reconstruction, and no styles unless `styles` asks for them (SGR only, lines
+     * still `\n`-separated). Deliberately cheaper than `capturePaneBuffer` because idle
      * detection calls it on a timer: it only needs to read what the CLI is
      * currently rendering, never to replay it into an xterm. Returns null when the
      * pane cannot be read.
      */
-    capturePaneText?(muxName: string, paneTarget?: string): string | null;
+    capturePaneText?(muxName: string, paneTarget?: string, opts?: {
+        styles?: boolean;
+    }): string | null;
 }
 //# sourceMappingURL=mux-interface.d.ts.map

package/dist/mux-interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mux-interface.d.ts","sourceRoot":"","sources":["../src/mux-interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,YAAY,EACZ,sBAAsB,EACtB,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,UAAU,EACV,aAAa,EACb,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,QAAQ,EACR,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mGAAmG;IACnG,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,mCAAmC;IACnC,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sIAAsI;IACtI,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,4GAA4G;IAC5G,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yGAAyG;IACzG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,WAAW,CAAC;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+FAA+F;IAC/F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uGAAuG;IACvG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mHAAmH;IACnH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAI3B;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAElE;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjD,uDAAuD;IACvD,OAAO,IAAI,IAAI,CAAC;IAIhB,+BAA+B;IAC/B,WAAW,IAAI,UAAU,EAAE,CAAC;IAE5B,0CAA0C;IAC1C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAEtD,wDAAwD;IACxD,oBAAoB,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAEvD,6CAA6C;IAC7C,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAIjE;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAI9D,2CAA2C;IAC3C,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5D,wCAAwC;IACxC,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAExD,0DAA0D;IAC1D,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAE3C,oDAAoD;IACpD,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,SAAS,GAAG,IAAI,CAAC;IAEzF,mDAAmD;IACnD,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5C,+CAA+C;IAC/C,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE9D,2FAA2F;IAC3F,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI9C;;;OAGG;IACH,iBAAiB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAIxF,8CAA8C;IAC9C,oBAAoB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD,6CAA6C;IAC7C,mBAAmB,IAAI,IAAI,CAAC;IAI5B;;OAEG;IACH,gBAAgB,IAAI,MAAM,CAAC;IAE3B;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEzC,iFAAiF;IACjF,mBAAmB,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/C,8EAA8E;IAC9E,YAAY,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAIpE,iEAAiE;IACjE,WAAW,IAAI,OAAO,CAAC;IAEvB,6FAA6F;IAC7F,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3C,gGAAgG;IAChG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAErC;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEpD;;;;;OAKG;IACH,oBAAoB,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAE/C,kFAAkF;IAClF,aAAa,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC,kEAAkE;IAClE,oBAAoB,CAAC,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjD,kCAAkC;IAClC,mBAAmB,CAAC,IAAI,IAAI,CAAC;IAE7B,wFAAwF;IACxF,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEjE;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAAC;IAEnG;;;OAGG;IACH,uBAAuB,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,GAAG,IAAI,CAAC;IAEpF;;;;;;OAMG;IACH,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACvE"}
+{"version":3,"file":"mux-interface.d.ts","sourceRoot":"","sources":["../src/mux-interface.ts"],"names":[],"mappings":"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"}

package/dist/prompt-cache-keepwarm.d.ts

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Prompt-cache keep-warm: a one-line keep-alive turn shortly before an idle
+ * claude session's prompt cache would expire, so the next real prompt reads the conversation
+ * from cache instead of re-processing it at the cache-write rate.
+ *
+ * Why it exists: Claude Code gives a subscription's main conversation a one-hour cache and
+ * lets it expire after an hour idle. Measured on real sessions, nearly every gap over an
+ * hour went cold and the first turn back re-wrote the whole context at 2x; a keep-alive turn
+ * costs a cache read plus a one-word reply, a small fraction of the miss it prevents, and the
+ * payoff is concentrated in gaps of one to four hours, which is why there is a cap after the
+ * last real prompt rather than an indefinite loop.
+ *
+ * Codeman owns the idle policy for these sessions (Discussion #554): a launch with keep-warm
+ * on also carries `idleCompaction: false` in its one `--settings` JSON, so Claude Code's own
+ * idle compaction (which fires at 90% of the TTL, a minute before the nudge) cannot replace
+ * the conversation with a summary first. That is decided once per launch in
+ * `TmuxManager._resolveIdleCompactionOptOut()` and recorded on the mux record; a session
+ * switched on after launch is kept warm best-effort and says so.
+ *
+ * Where the facts come from: `Session.promptCache` (the statusline's `prompt_cache` object,
+ * see usage-telemetry.ts) carries `expires_at`, the TTL and the tokens at stake, so nothing
+ * here infers the lifetime from idle detection or the plan tier.
+ *
+ * Shape: `decideKeepWarm()` is the pure rulebook (every guard in one place, tested as a
+ * table); `PromptCacheKeepWarmService` owns the per-session timer and the ports it needs
+ * from the server. It never touches the session except through `beginKeepAliveTurn()` and
+ * `writeViaMux()`: the window `beginKeepAliveTurn()` opens is what keeps the nudge off the
+ * real-prompt clock and opens its stop hook and idle prompt pre-acknowledged
+ * (hook-event-routes.ts). The nudge is still a submit, so it moves `lastSubmitAt`.
+ *
+ * @module prompt-cache-keepwarm
+ */
+import type { KeepWarmStatus, PromptCacheStatus, StatusLineExporter } from './types/index.js';
+/** The nudge. Under 100 chars on purpose: a longer burst reads as a paste to Claude Code. */
+export declare const KEEP_WARM_NUDGE = "Codeman cache keep-alive: no action needed, reply with just \"ok\".";
+/** Nudge this long before `expires_at`. The nudge's own request is what refreshes the timer. */
+export declare const KEEP_WARM_LEAD_MS: number;
+/** Re-check cadence while a transient guard (working, dialog, draft in the composer) defers. */
+export declare const KEEP_WARM_RETRY_MS = 60000;
+/** Give up this close to expiry: a turn takes seconds to land and the Enter may be re-pressed. */
+export declare const KEEP_WARM_LAST_CHANCE_MS = 60000;
+/** Below this many tokens at stake a cold rewrite is cheap and a turn is not worth it. */
+export declare const KEEP_WARM_MIN_TOKENS = 20000;
+/** A person typed this recently: they may be about to submit, which refreshes the cache for free. */
+export declare const KEEP_WARM_RECENT_INPUT_MS: number;
+/**
+ * Ceiling on the keep-alive window. The window normally closes on the turn's own idle prompt
+ * (Claude Code sends it about a minute after the turn ends, so a slow turn must not outlast a
+ * short fixed window) or earlier, at any other submit; the ceiling covers a turn whose idle
+ * prompt never arrives, such as a workspace without Codeman's hooks.
+ */
+export declare const KEEP_WARM_TURN_WINDOW_MS: number;
+/** Default cap: hours after the last real prompt during which nudges are sent. */
+export declare const DEFAULT_KEEP_WARM_MAX_HOURS = 2;
+/**
+ * Whether keep-warm is on for a session: its own choice, else the app-wide default. A session
+ * an agent spawned (`parentSessionId`) does not inherit the default: a worker that finished
+ * its task is idle exactly like one that will be prompted again, and most never are, so only
+ * its own switch keeps it warm. One function because the launch (the `idleCompaction`
+ * opt-out) and the service must agree.
+ */
+export declare function keepWarmOn(choice: boolean | undefined, appDefault: boolean, spawnedByAgent: boolean): boolean;
+export interface KeepWarmFacts {
+    now: number;
+    /** The session's own choice; undefined = the app-wide default applies. */
+    choice: boolean | undefined;
+    appDefault: boolean;
+    /** Spawned by another session (`parentSessionId`); see `keepWarmOn`. */
+    spawnedByAgent: boolean;
+    /** Whether this launch carries the statusLine exporter; undefined when unknown. */
+    statusLine?: StatusLineExporter;
+    cache: PromptCacheStatus | null | undefined;
+    /** Idle by Codeman's own probe and not mid-turn. */
+    idle: boolean;
+    /** A pid and no recorded agent exit (`paneExit`: an exited agent's pane keeps its pid). */
+    paneAlive: boolean;
+    /** Auto-resume's pause, or a usage-limit message on screen whose reset is still ahead. */
+    limitPaused: boolean;
+    /** Respawn running, a Ralph loop active, a task assigned, or an agent long-polling the session. */
+    automationActive: boolean;
+    /** A permission, question or elicitation dialog is open (never the idle item). */
+    pendingApproval: boolean;
+    /** The composer line holds no text; null when the pane could not be read. */
+    composerEmpty: boolean | null;
+    /** Last keystroke a person sent, epoch ms; 0 when none seen. */
+    lastHumanInputAt: number;
+    /** Start of the keep-warm window: the last real (non-keep-alive) prompt, else the session start. */
+    budgetAnchorAt: number;
+    maxKeepWarmMs: number;
+}
+export type KeepWarmDecision = {
+    action: 'nudge';
+} | {
+    action: 'wait';
+    until: number;
+    reason: string;
+} | {
+    action: 'stop';
+    reason: string;
+};
+/**
+ * The rulebook. Hard stops first (nothing to do until the next cache report or a flag
+ * change), then the schedule, then the transient guards that defer by `KEEP_WARM_RETRY_MS`
+ * and never past the last-chance line. Pure: `now` is passed in.
+ */
+export declare function decideKeepWarm(f: KeepWarmFacts): KeepWarmDecision;
+/** What the service needs from a session; `Session` satisfies it structurally. */
+export interface KeepWarmSessionView {
+    readonly id: string;
+    readonly createdAt: number;
+    readonly pid: number | null;
+    /** Set when the agent exited in a pane that stays open (`remain-on-exit`); the pid stays. */
+    readonly paneExit?: unknown;
+    readonly parentSessionId?: string;
+    readonly promptCache: PromptCacheStatus | null;
+    readonly statusLineExporter?: StatusLineExporter;
+    /** Whether this launch carries `idleCompaction: false` (`MuxSession.idleCompactionOff`). */
+    readonly idleCompactionOptOut: boolean;
+    readonly keepWarmEnabled: boolean | undefined;
+    readonly isWorking: boolean;
+    readonly isLimitPaused: boolean;
+    readonly lastHumanInputAt: number;
+    /** Last submit that was not the keep-alive's own (persisted): the cap's clock. */
+    readonly lastRealPromptAt: number;
+    isIdle(): boolean;
+    beginKeepAliveTurn(windowMs: number): void;
+    /** Close the window `beginKeepAliveTurn()` opened, when the nudge never went out. */
+    endKeepAliveTurn(): void;
+    writeViaMux(data: string): Promise<boolean>;
+}
+export interface KeepWarmSettings {
+    /** App-wide default for sessions that have not chosen (`promptCacheKeepWarm`). */
+    keepWarmDefault: boolean;
+    /** Cap in hours after the last real prompt (`promptCacheKeepWarmMaxHours`). */
+    maxHours: number;
+}
+export interface KeepWarmPorts {
+    getSession(id: string): KeepWarmSessionView | undefined;
+    sessionIds(): Iterable<string>;
+    readSettings(): Promise<KeepWarmSettings>;
+    isAutomationActive(id: string): boolean;
+    hasPendingApproval(id: string): boolean;
+    /**
+     * Read the pane once a nudge is otherwise due: whether the composer is empty (null when it
+     * cannot be read), and whether a usage-limit message with a reset still ahead is on screen
+     * (auto-resume's own pause tracking only runs while auto-resume is on).
+     */
+    readPane(session: KeepWarmSessionView): {
+        composerEmpty: boolean | null;
+        limitShown: boolean;
+    };
+    /** Store and broadcast the status (the server dedupes against the session's last one). */
+    publish(id: string, status: KeepWarmStatus): void;
+    log?(message: string): void;
+}
+/** The scheduler the routes see: one method per trigger, nothing else. */
+export interface KeepWarmScheduler {
+    /** Re-evaluate a session: after a cache report, a flag change, or a settings change. Resolves once the status is published. */
+    schedule(sessionId: string): Promise<void>;
+    /** Re-read the app-wide default and cap, then re-evaluate every session (either one changed). */
+    rescheduleAll(): void;
+    /** The session is gone. */
+    remove(sessionId: string): void;
+}
+export declare class PromptCacheKeepWarmService implements KeepWarmScheduler {
+    private readonly ports;
+    private readonly timers;
+    private readonly tallies;
+    /** One evaluation per session; `remove()` and `stop()` cancel it at its next await. */
+    private readonly inFlight;
+    /** The evaluation running per session, and the one follow-up queued behind it. */
+    private readonly running;
+    private readonly followUps;
+    /**
+     * The default and cap, read once and kept: every statusline report schedules an evaluation,
+     * and reading settings.json on each would cost every install, the feature off included.
+     * `rescheduleAll()` drops it, and the settings PUT calls that whenever either key changes.
+     */
+    private settings;
+    /** The last settings read failure logged, so one that persists is logged once; cleared by a good read. */
+    private settingsFailure;
+    private stopped;
+    constructor(ports: KeepWarmPorts);
+    schedule(sessionId: string): Promise<void>;
+    rescheduleAll(): void;
+    remove(sessionId: string): void;
+    stop(): void;
+    private readSettings;
+    private clearTimer;
+    private arm;
+    private evaluate;
+}
+//# sourceMappingURL=prompt-cache-keepwarm.d.ts.map

package/dist/prompt-cache-keepwarm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-cache-keepwarm.d.ts","sourceRoot":"","sources":["../src/prompt-cache-keepwarm.ts"],"names":[],"mappings":"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"}

package/dist/prompt-cache-keepwarm.js

@@ -0,0 +1,359 @@
+/**
+ * @fileoverview Prompt-cache keep-warm: a one-line keep-alive turn shortly before an idle
+ * claude session's prompt cache would expire, so the next real prompt reads the conversation
+ * from cache instead of re-processing it at the cache-write rate.
+ *
+ * Why it exists: Claude Code gives a subscription's main conversation a one-hour cache and
+ * lets it expire after an hour idle. Measured on real sessions, nearly every gap over an
+ * hour went cold and the first turn back re-wrote the whole context at 2x; a keep-alive turn
+ * costs a cache read plus a one-word reply, a small fraction of the miss it prevents, and the
+ * payoff is concentrated in gaps of one to four hours, which is why there is a cap after the
+ * last real prompt rather than an indefinite loop.
+ *
+ * Codeman owns the idle policy for these sessions (Discussion #554): a launch with keep-warm
+ * on also carries `idleCompaction: false` in its one `--settings` JSON, so Claude Code's own
+ * idle compaction (which fires at 90% of the TTL, a minute before the nudge) cannot replace
+ * the conversation with a summary first. That is decided once per launch in
+ * `TmuxManager._resolveIdleCompactionOptOut()` and recorded on the mux record; a session
+ * switched on after launch is kept warm best-effort and says so.
+ *
+ * Where the facts come from: `Session.promptCache` (the statusline's `prompt_cache` object,
+ * see usage-telemetry.ts) carries `expires_at`, the TTL and the tokens at stake, so nothing
+ * here infers the lifetime from idle detection or the plan tier.
+ *
+ * Shape: `decideKeepWarm()` is the pure rulebook (every guard in one place, tested as a
+ * table); `PromptCacheKeepWarmService` owns the per-session timer and the ports it needs
+ * from the server. It never touches the session except through `beginKeepAliveTurn()` and
+ * `writeViaMux()`: the window `beginKeepAliveTurn()` opens is what keeps the nudge off the
+ * real-prompt clock and opens its stop hook and idle prompt pre-acknowledged
+ * (hook-event-routes.ts). The nudge is still a submit, so it moves `lastSubmitAt`.
+ *
+ * @module prompt-cache-keepwarm
+ */
+/** The nudge. Under 100 chars on purpose: a longer burst reads as a paste to Claude Code. */
+export const KEEP_WARM_NUDGE = 'Codeman cache keep-alive: no action needed, reply with just "ok".';
+/** Nudge this long before `expires_at`. The nudge's own request is what refreshes the timer. */
+export const KEEP_WARM_LEAD_MS = 5 * 60_000;
+/** Re-check cadence while a transient guard (working, dialog, draft in the composer) defers. */
+export const KEEP_WARM_RETRY_MS = 60_000;
+/** Give up this close to expiry: a turn takes seconds to land and the Enter may be re-pressed. */
+export const KEEP_WARM_LAST_CHANCE_MS = 60_000;
+/** Below this many tokens at stake a cold rewrite is cheap and a turn is not worth it. */
+export const KEEP_WARM_MIN_TOKENS = 20_000;
+/** A person typed this recently: they may be about to submit, which refreshes the cache for free. */
+export const KEEP_WARM_RECENT_INPUT_MS = 3 * 60_000;
+/**
+ * Ceiling on the keep-alive window. The window normally closes on the turn's own idle prompt
+ * (Claude Code sends it about a minute after the turn ends, so a slow turn must not outlast a
+ * short fixed window) or earlier, at any other submit; the ceiling covers a turn whose idle
+ * prompt never arrives, such as a workspace without Codeman's hooks.
+ */
+export const KEEP_WARM_TURN_WINDOW_MS = 10 * 60_000;
+/** Default cap: hours after the last real prompt during which nudges are sent. */
+export const DEFAULT_KEEP_WARM_MAX_HOURS = 2;
+/** Longest delay `setTimeout` honours; Node fires anything longer after 1 ms. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Whether keep-warm is on for a session: its own choice, else the app-wide default. A session
+ * an agent spawned (`parentSessionId`) does not inherit the default: a worker that finished
+ * its task is idle exactly like one that will be prompted again, and most never are, so only
+ * its own switch keeps it warm. One function because the launch (the `idleCompaction`
+ * opt-out) and the service must agree.
+ */
+export function keepWarmOn(choice, appDefault, spawnedByAgent) {
+    return choice ?? (appDefault && !spawnedByAgent);
+}
+const stop = (reason) => ({ action: 'stop', reason });
+const wait = (until, reason) => ({ action: 'wait', until, reason });
+/**
+ * The rulebook. Hard stops first (nothing to do until the next cache report or a flag
+ * change), then the schedule, then the transient guards that defer by `KEEP_WARM_RETRY_MS`
+ * and never past the last-chance line. Pure: `now` is passed in.
+ */
+export function decideKeepWarm(f) {
+    if (!keepWarmOn(f.choice, f.appDefault, f.spawnedByAgent)) {
+        return stop(f.choice === undefined && f.appDefault
+            ? 'an agent-spawned session follows the app-wide default only when switched on for itself'
+            : 'off');
+    }
+    // Only a launch that carries the exporter ever reports `prompt_cache`; the readout names the
+    // cause from `statusLineExporter`. This is also what stops a CLI without cache telemetry.
+    if (f.statusLine !== 'injected')
+        return stop(`no cache reports on this launch (${f.statusLine ?? 'unknown'})`);
+    const c = f.cache;
+    if (!c)
+        return stop('no cache report yet');
+    if (!c.warm || !c.expiresAt)
+        return stop('cache is cold; the next prompt rebuilds it');
+    // Compacted this gap (`/compact`, or Claude Code's own idle compaction on a launch without
+    // the opt-out): the full context is already gone, so keeping the summary warm buys little.
+    // The stamp is dropped at the next request, which re-opens the next gap.
+    if (c.compactedAt != null)
+        return stop('the context was compacted; resumes after the next prompt');
+    if (c.ttl === '5m') {
+        return stop('5-minute cache lifetime; a nudge every four minutes costs more than the miss it prevents');
+    }
+    if ((c.recacheTokensIfCold ?? 0) < KEEP_WARM_MIN_TOKENS)
+        return stop('context too small to be worth a turn');
+    if (!f.paneAlive)
+        return stop('no live pane');
+    if (f.limitPaused)
+        return stop('usage-limit pause');
+    if (f.now >= f.budgetAnchorAt + f.maxKeepWarmMs)
+        return stop('keep-warm window after the last prompt has passed');
+    const dueAt = c.expiresAt - KEEP_WARM_LEAD_MS;
+    if (f.now < dueAt)
+        return wait(dueAt, 'not due yet');
+    const lastChance = c.expiresAt - KEEP_WARM_LAST_CHANCE_MS;
+    if (f.now >= lastChance)
+        return stop('too close to expiry to land a turn');
+    const retryAt = Math.min(f.now + KEEP_WARM_RETRY_MS, lastChance);
+    if (!f.idle)
+        return wait(retryAt, 'session is working');
+    if (f.pendingApproval)
+        return wait(retryAt, 'a dialog is open');
+    // Transient, and nothing else re-triggers an idle session: an agent's long-poll waiter ends
+    // without a turn, and so does a capture that failed once.
+    if (f.automationActive)
+        return wait(retryAt, 'respawn, Ralph or an agent is driving the session');
+    if (f.composerEmpty === null)
+        return wait(retryAt, 'cannot read the composer');
+    if (!f.composerEmpty)
+        return wait(retryAt, 'the composer holds text');
+    if (f.lastHumanInputAt && f.now - f.lastHumanInputAt < KEEP_WARM_RECENT_INPUT_MS) {
+        return wait(retryAt, 'someone typed a moment ago');
+    }
+    return { action: 'nudge' };
+}
+/**
+ * Whether a session could be nudged once the settings are known: its own switch is not off, its
+ * launch reports the cache, and the last report is warm. Only such a session has anything to
+ * lose while the settings cannot be read, so only it retries on its own.
+ */
+function couldNudge(s) {
+    return (s.keepWarmEnabled !== false &&
+        s.statusLineExporter === 'injected' &&
+        !!s.promptCache?.warm &&
+        !!s.promptCache.expiresAt);
+}
+export class PromptCacheKeepWarmService {
+    ports;
+    timers = new Map();
+    tallies = new Map();
+    /** One evaluation per session; `remove()` and `stop()` cancel it at its next await. */
+    inFlight = new Map();
+    /** The evaluation running per session, and the one follow-up queued behind it. */
+    running = new Map();
+    followUps = new Map();
+    /**
+     * The default and cap, read once and kept: every statusline report schedules an evaluation,
+     * and reading settings.json on each would cost every install, the feature off included.
+     * `rescheduleAll()` drops it, and the settings PUT calls that whenever either key changes.
+     */
+    settings;
+    /** The last settings read failure logged, so one that persists is logged once; cleared by a good read. */
+    settingsFailure;
+    stopped = false;
+    constructor(ports) {
+        this.ports = ports;
+    }
+    schedule(sessionId) {
+        if (this.stopped)
+            return Promise.resolve();
+        const running = this.running.get(sessionId);
+        if (running) {
+            // A trigger landing mid-evaluation (a toggle while the nudge is written, a settings change)
+            // carries what that evaluation read too early, so one follow-up runs after it, shared by
+            // every trigger that arrives meanwhile.
+            let next = this.followUps.get(sessionId);
+            if (!next) {
+                next = running.then(() => {
+                    // `remove()` drops the queued follow-up: a deleted session gets no evaluation.
+                    if (this.followUps.get(sessionId) !== next)
+                        return;
+                    this.followUps.delete(sessionId);
+                    return this.schedule(sessionId);
+                });
+                this.followUps.set(sessionId, next);
+            }
+            return next;
+        }
+        const run = this.evaluate(sessionId)
+            .catch((err) => {
+            this.ports.log?.(`[KeepWarm] ${sessionId.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`);
+            // A failed write or pane read is transient, and an idle session gets no other trigger
+            // until its next turn. (A failed settings read is handled in evaluate().)
+            // Not after `remove()`, which drops this run: the session is being deleted.
+            if (!this.stopped && this.running.get(sessionId) === run)
+                this.arm(sessionId, Date.now() + KEEP_WARM_RETRY_MS);
+        })
+            .finally(() => {
+            if (this.running.get(sessionId) === run)
+                this.running.delete(sessionId);
+        });
+        this.running.set(sessionId, run);
+        return run;
+    }
+    rescheduleAll() {
+        this.settings = undefined;
+        for (const id of this.ports.sessionIds())
+            void this.schedule(id);
+    }
+    remove(sessionId) {
+        this.clearTimer(sessionId);
+        this.tallies.delete(sessionId);
+        this.inFlight.delete(sessionId);
+        this.running.delete(sessionId);
+        this.followUps.delete(sessionId);
+    }
+    stop() {
+        this.stopped = true;
+        for (const id of [...this.timers.keys()])
+            this.clearTimer(id);
+    }
+    readSettings() {
+        if (!this.settings) {
+            const read = this.ports.readSettings();
+            this.settings = read;
+            // A failed read is not kept: the next evaluation tries again.
+            read.catch(() => {
+                if (this.settings === read)
+                    this.settings = undefined;
+            });
+        }
+        return this.settings;
+    }
+    clearTimer(id) {
+        const t = this.timers.get(id);
+        if (t)
+            clearTimeout(t);
+        this.timers.delete(id);
+    }
+    arm(id, at) {
+        this.clearTimer(id);
+        const t = setTimeout(() => void this.schedule(id), Math.min(Math.max(0, at - Date.now()), MAX_TIMER_MS));
+        t.unref?.();
+        this.timers.set(id, t);
+    }
+    async evaluate(id) {
+        if (this.stopped || this.inFlight.has(id))
+            return;
+        const token = Symbol(id);
+        this.inFlight.set(id, token);
+        // A session removed (or the service stopped) during an await gets nothing after it: no
+        // nudge, no tally, no timer, no status.
+        const cancelled = () => this.stopped || this.inFlight.get(id) !== token;
+        try {
+            this.clearTimer(id);
+            const session = this.ports.getSession(id);
+            if (!session)
+                return;
+            let settings;
+            try {
+                settings = await this.readSettings();
+            }
+            catch (err) {
+                // A read that lands mid-write is retried. A settings.json that stays broken (a hand edit
+                // with a trailing comma) fails every read until it is fixed, so it is logged once rather
+                // than once a minute per session, and only a session that could nudge retries.
+                const message = err instanceof Error ? err.message : String(err);
+                if (message !== this.settingsFailure) {
+                    this.settingsFailure = message;
+                    this.ports.log?.(`[KeepWarm] ${id.slice(0, 8)}: cannot read the settings: ${message}`);
+                }
+                if (!cancelled() && couldNudge(session))
+                    this.arm(id, Date.now() + KEEP_WARM_RETRY_MS);
+                return;
+            }
+            this.settingsFailure = undefined;
+            if (cancelled())
+                return;
+            const tally = this.tallies.get(id) ?? { nudges: 0 };
+            const facts = {
+                now: Date.now(),
+                choice: session.keepWarmEnabled,
+                appDefault: settings.keepWarmDefault,
+                spawnedByAgent: !!session.parentSessionId,
+                statusLine: session.statusLineExporter,
+                cache: session.promptCache,
+                idle: session.isIdle() && !session.isWorking,
+                paneAlive: session.pid !== null && !session.paneExit,
+                limitPaused: session.isLimitPaused,
+                automationActive: this.ports.isAutomationActive(id),
+                pendingApproval: this.ports.hasPendingApproval(id),
+                // Optimistic until everything else says "due": the pane read is the one costly fact.
+                composerEmpty: true,
+                lastHumanInputAt: session.lastHumanInputAt,
+                budgetAnchorAt: session.lastRealPromptAt || session.createdAt,
+                maxKeepWarmMs: settings.maxHours * 3_600_000,
+            };
+            let decision = decideKeepWarm(facts);
+            if (decision.action === 'nudge') {
+                const pane = this.ports.readPane(session);
+                decision = decideKeepWarm({
+                    ...facts,
+                    composerEmpty: pane.composerEmpty,
+                    limitPaused: facts.limitPaused || pane.limitShown,
+                });
+            }
+            const enabled = keepWarmOn(facts.choice, facts.appDefault, facts.spawnedByAgent);
+            const base = {
+                enabled,
+                idleCompactionOff: session.idleCompactionOptOut,
+                nudges: tally.nudges,
+                lastNudgeAt: tally.lastNudgeAt,
+                // Off, the window means nothing, and it moves with every real prompt: carrying it would
+                // broadcast a change on every turn of every session.
+                ...(enabled && { budgetEndsAt: facts.budgetAnchorAt + facts.maxKeepWarmMs }),
+            };
+            if (decision.action === 'nudge') {
+                session.beginKeepAliveTurn(KEEP_WARM_TURN_WINDOW_MS);
+                const ok = await session.writeViaMux(`${KEEP_WARM_NUDGE}\r`);
+                if (cancelled())
+                    return;
+                if (ok) {
+                    tally.nudges += 1;
+                    tally.lastNudgeAt = Date.now();
+                    this.tallies.set(id, tally);
+                }
+                this.ports.log?.(`[KeepWarm] ${ok ? 'nudged' : 'failed to nudge'} ${id.slice(0, 8)} with ${facts.cache?.recacheTokensIfCold ?? '?'} tokens at stake (nudge ${tally.nudges})`);
+                // Sent: the nudge's own cache report re-schedules, and this timer is the fallback if none
+                // arrives. Not sent: no turn is running, so the window closes now rather than at its
+                // ceiling, and the retry lands inside the last minutes before the expiry, where a nudge
+                // can still go out (a lead time later would be past it).
+                let nextCheckAt = Date.now() + KEEP_WARM_LEAD_MS;
+                if (!ok) {
+                    session.endKeepAliveTurn();
+                    const expiresAt = facts.cache?.expiresAt ?? 0;
+                    nextCheckAt = Math.min(Date.now() + KEEP_WARM_RETRY_MS, expiresAt - KEEP_WARM_LAST_CHANCE_MS);
+                }
+                this.arm(id, nextCheckAt);
+                this.ports.publish(id, {
+                    ...base,
+                    nudges: tally.nudges,
+                    lastNudgeAt: tally.lastNudgeAt,
+                    state: ok ? 'nudged' : 'waiting',
+                    nextCheckAt,
+                    reason: ok ? undefined : 'the keep-alive could not be written',
+                });
+            }
+            else if (decision.action === 'wait') {
+                this.arm(id, decision.until);
+                this.ports.publish(id, {
+                    ...base,
+                    state: decision.reason === 'not due yet' ? 'armed' : 'waiting',
+                    nextCheckAt: decision.until,
+                    reason: decision.reason === 'not due yet' ? undefined : decision.reason,
+                });
+            }
+            else {
+                this.ports.publish(id, { ...base, state: enabled ? 'stopped' : 'off', reason: decision.reason });
+            }
+        }
+        finally {
+            if (this.inFlight.get(id) === token)
+                this.inFlight.delete(id);
+        }
+    }
+}
+//# sourceMappingURL=prompt-cache-keepwarm.js.map