Claude Code review R1: fix stale TodoState comparisons, wire promoteTodo, update spec

Author: nedtwigg

docs/specs/alarm.md

@@ -46,11 +46,14 @@ Each Session owns:
   - Transitional states: `MIGHT_BE_BUSY`, `MIGHT_NEED_ATTENTION`.
   - When the user enables the alarm, status transitions from `ALARM_DISABLED` to `NOTHING_TO_SHOW` and activity tracking begins fresh from that moment.
   - When the user disables the alarm, activity tracking stops and status returns to `ALARM_DISABLED`.
-- `todo: false | 'soft' | 'hard'`
-  - Reminder state for the Session. Default `false`.
-  - `'soft'`: auto-created when a ringing alarm is phantom-dismissed (any attention path). Dashed-outline pill. Auto-clears when the user types printable text into the terminal (synthetic terminal reports like focus events and cursor-position responses are excluded).
-  - `'hard'`: explicitly set by the user via `t` key or context menu. Solid-outline pill. Only clears via explicit toggle.
-  - Dismissing a ringing alarm when `todo` is already `'soft'` or `'hard'` does not downgrade it.
+- `todo: TodoState` (numeric)
+  - Reminder state for the Session. Default `TODO_OFF` (`-1`).
+  - `TODO_OFF` (`-1`): no TODO.
+  - `[0, 1]` (soft TODO): auto-created when a ringing alarm is phantom-dismissed (any attention path). Value is the leaky-bucket fill level (`1` = full, `0` = about to clear). Dashed-outline pill. Uses a leaky-bucket mechanism: each printable keypress drains the bucket by `1/keypressesToEmpty` (default 5 keypresses to fully drain). When typing stops, the bucket refills to full over `timeToFullSeconds` (default 3 seconds). If the bucket empties completely, the soft TODO clears. Synthetic terminal reports (focus events, cursor-position responses) do not drain the bucket.
+  - `TODO_HARD` (`2`): explicitly set by the user via `t` key or context menu. Solid-outline pill. Only clears via explicit toggle.
+  - Dismissing a ringing alarm when `todo` is already soft or hard does not downgrade it.
+  - Helper functions: `isSoftTodo(todo)`, `isHardTodo(todo)`, `hasTodo(todo)`.
+  - Leaky-bucket tuning parameters are in `cfg.todoBucket`.
 
 Each Session also owns:
 
@@ -203,7 +206,7 @@ The Session leaves `ALARM_RINGING` and returns to `NOTHING_TO_SHOW` when any of
 - the user marks the Session as hard TODO (`t` key or context menu)
 - new output arrives while the Session has attention (starts a new `MIGHT_BE_BUSY` cycle; without attention the alarm stays ringing — see latch in transition rules)
 
-All attention-based dismissals (the first three above) create a soft TODO if `todo` is currently `false`. This prevents phantom dismissals where the alarm vanishes without a trace. Typing printable text into the terminal auto-clears soft TODOs, so users who engage with the output don't accumulate breadcrumbs. Synthetic terminal reports (focus events, cursor-position responses) do not count as typing.
+All attention-based dismissals (the first three above) create a soft TODO if `todo` is currently `TODO_OFF`. This prevents phantom dismissals where the alarm vanishes without a trace. Printable keypresses drain the soft TODO's leaky bucket, and if the bucket empties completely the soft TODO clears — so users who engage with the output don't accumulate breadcrumbs. If the user stops typing, the bucket refills over `cfg.todoBucket.timeToFullSeconds` (default 3 s). Synthetic terminal reports (focus events, cursor-position responses) do not drain the bucket.
 
 The Session leaves `ALARM_RINGING` and returns to `ALARM_DISABLED` when:
 
@@ -215,7 +218,7 @@ The Session's alarm state is cleared entirely when:
 
 If more output arrives later and the Session makes a fresh transition back into `ALARM_RINGING`, the alarm rings again.
 
-Marking a Session as hard TODO resets the alarm to `NOTHING_TO_SHOW` and sets `todo = 'hard'`, but it does **not** disable future alarms. `todo` and the alarm toggle are separate concerns.
+Marking a Session as hard TODO resets the alarm to `NOTHING_TO_SHOW` and sets `todo = TODO_HARD`, but it does **not** disable future alarms. `todo` and the alarm toggle are separate concerns.
 
 Disabling alarms disposes the activity monitor and returns `status` to `ALARM_DISABLED`.
 
@@ -230,10 +233,10 @@ The Pane header exposes two independent concepts:
 
 TODO pill:
 
-- toggled in command mode with `t` (cycles: `false` → `'hard'`, `'soft'` → `'hard'`, `'hard'` → `false`)
-- shown when `todo` is `'soft'` or `'hard'`
-- `'soft'`: dashed-outline pill — auto-created on alarm dismiss, auto-clears on user input
-- `'hard'`: solid-outline pill — explicitly set, only clears manually
+- toggled in command mode with `t` (cycles: `TODO_OFF` → `TODO_HARD`, soft → `TODO_HARD`, `TODO_HARD` → `TODO_OFF`)
+- shown when `hasTodo(todo)` is true (i.e. `todo !== TODO_OFF`)
+- soft (`isSoftTodo(todo)`): dashed-outline pill — auto-created on alarm dismiss, drains via leaky bucket on typing
+- `TODO_HARD` (`isHardTodo(todo)`): solid-outline pill — explicitly set, only clears manually
 - clicking a soft pill shows a prompt: "Clear" / "Keep" (keep promotes to hard)
 - clicking a hard pill clears it
 - no empty placeholder when off
@@ -276,7 +279,7 @@ A Door is display-only for alarm state in v1. It must not replace the existing D
 Door indicators:
 
 - show bell indicator only when `status !== 'ALARM_DISABLED'`
-- show TODO pill when `todo !== false` (`'soft'` or `'hard'`)
+- show TODO pill when `hasTodo(todo)` (soft or hard)
 - if `status === 'ALARM_RINGING'`, the Door itself gets the ringing treatment, not just a tiny icon
 - the Door bell icon shows the same dot badge as the Pane header for `MIGHT_BE_BUSY`, `BUSY`, and `MIGHT_NEED_ATTENTION` states, but smaller (4px vs 6px) to match the smaller bell icon
 
@@ -366,7 +369,7 @@ Consequences:
 - A Session rings.
 - User clicks into the pane to read the output.
 - The alarm clears, a soft TODO appears (dashed pill).
-- User types a command → soft TODO auto-clears (they engaged).
+- User types a command → printable keypresses drain the soft TODO's leaky bucket; if enough keypresses occur without long pauses, the soft TODO clears (they engaged).
 - The Session later emits new output, progresses through `BUSY`, and eventually reaches `ALARM_RINGING` again.
 
 ### User dismisses but doesn't engage

lib/src/components/Pond.tsx

@@ -36,6 +36,7 @@ import {
   isSoftTodo,
   isHardTodo,
   hasTodo,
+  TODO_OFF,
 } from '../lib/terminal-registry';
 import { resolvePanelElement, findPanelInDirection, findRestoreNeighbor, type DetachDirection } from '../lib/spatial-nav';
 import { cloneLayout, getLayoutStructureSignature } from '../lib/layout-snapshot';
@@ -338,12 +339,12 @@ function TodoAlarmDialog({
         <span className="text-[10px] font-mono text-muted">[t]</span>
         <span className="text-[11px] text-foreground font-medium w-10">TODO</span>
         <div className="flex gap-1 ml-auto">
-          <button type="button" className={toggleBtn(sessionState.todo === 'hard')}
-            onClick={() => { if (sessionState.todo !== 'hard') markSessionTodo(sessionId); }}>
+          <button type="button" className={toggleBtn(isHardTodo(sessionState.todo))}
+            onClick={() => { if (!isHardTodo(sessionState.todo)) markSessionTodo(sessionId); }}>
             hard
           </button>
-          <button type="button" className={toggleBtn(sessionState.todo === false)}
-            onClick={() => { if (sessionState.todo !== false) clearSessionTodo(sessionId); }}>
+          <button type="button" className={toggleBtn(sessionState.todo === TODO_OFF)}
+            onClick={() => { if (sessionState.todo !== TODO_OFF) clearSessionTodo(sessionId); }}>
             off
           </button>
         </div>
@@ -369,7 +370,7 @@ function TodoAlarmDialog({
       <div className="border-t border-border pt-2 text-[9px] leading-relaxed text-muted">
         When an alarming tab is selected,<br />
         the alarm is cleared and the tab gets a soft TODO.<br />
-        Typing characters into the tab will automatically clear a soft TODO.
+        Typing drains the soft TODO; stop typing and it refills.
       </div>
     </div>,
     document.body,

lib/src/lib/alarm-manager.ts

@@ -21,6 +21,14 @@ export function isSoftTodo(todo: TodoState): boolean { return todo >= 0 && todo
 export function isHardTodo(todo: TodoState): boolean { return todo === TODO_HARD; }
 export function hasTodo(todo: TodoState): boolean { return todo !== TODO_OFF; }
 
+/** Migrate legacy persisted TodoState values (false/'soft'/'hard') to numeric. */
+export function migrateTodoState(todo: unknown): TodoState {
+  if (typeof todo === 'number') return todo;
+  if (todo === 'hard') return TODO_HARD;
+  if (todo === 'soft') return TODO_SOFT_FULL;
+  return TODO_OFF; // false, null, undefined, or any other unexpected value
+}
+
 export type AlarmButtonActionResult = 'enabled' | 'disabled' | 'dismissed' | 'noop';
 
 export interface AlarmState {
@@ -355,7 +363,7 @@ export class AlarmManager {
    */
   restore(id: string, state: { status: string; todo: TodoState }): void {
     const entry = this.getOrCreateEntry(id);
-    entry.todo = state.todo;
+    entry.todo = migrateTodoState(state.todo);
     // If the alarm was enabled (anything other than ALARM_DISABLED), create a monitor
     if (state.status !== 'ALARM_DISABLED') {
       if (!entry.monitor) {

lib/src/lib/platform/fake-adapter.ts

@@ -143,6 +143,7 @@ export class FakePtyAdapter implements PlatformAdapter {
   alarmClearAttention(id?: string): void { this.alarmManager.clearAttention(id); }
   alarmToggleTodo(id: string): void { this.alarmManager.toggleTodo(id); }
   alarmMarkTodo(id: string): void { this.alarmManager.markTodo(id); }
+  alarmPromoteTodo(id: string): void { this.alarmManager.promoteTodo(id); }
   alarmClearTodo(id: string): void { this.alarmManager.clearTodo(id); }
   alarmDrainTodoBucket(id: string): void { this.alarmManager.drainTodoBucket(id); }
   onAlarmState(handler: (detail: AlarmStateDetail) => void): void { this.alarmStateHandlers.add(handler); }

lib/src/lib/platform/types.ts

@@ -52,6 +52,7 @@ export interface PlatformAdapter {
   alarmClearAttention(id?: string): void;
   alarmToggleTodo(id: string): void;
   alarmMarkTodo(id: string): void;
+  alarmPromoteTodo(id: string): void;
   alarmClearTodo(id: string): void;
   alarmDrainTodoBucket(id: string): void;
   onAlarmState(handler: (detail: AlarmStateDetail) => void): void;

lib/src/lib/platform/vscode-adapter.ts

@@ -194,6 +194,10 @@ export class VSCodeAdapter implements PlatformAdapter {
     this.vscode.postMessage({ type: 'alarm:markTodo', id });
   }
 
+  alarmPromoteTodo(id: string): void {
+    this.vscode.postMessage({ type: 'alarm:promoteTodo', id });
+  }
+
   alarmClearTodo(id: string): void {
     this.vscode.postMessage({ type: 'alarm:clearTodo', id });
   }

lib/src/lib/session-save.test.ts

@@ -49,6 +49,7 @@ function createPlatform(savedState: PersistedSession | null): PlatformAdapter {
     alarmClearAttention: () => {},
     alarmToggleTodo: () => {},
     alarmMarkTodo: () => {},
+    alarmPromoteTodo: () => {},
     alarmClearTodo: () => {},
     alarmDrainTodoBucket: () => {},
     onAlarmState: () => {},

standalone/src/tauri-adapter.ts

@@ -199,6 +199,10 @@ export class TauriAdapter implements PlatformAdapter {
     this.alarmManager.markTodo(id);
   }
 
+  alarmPromoteTodo(id: string): void {
+    this.alarmManager.promoteTodo(id);
+  }
+
   alarmClearTodo(id: string): void {
     this.alarmManager.clearTodo(id);
   }

vscode-ext/src/message-router.ts

@@ -291,6 +291,9 @@ export function attachRouter(
       case 'alarm:markTodo':
         alarmManager.markTodo(msg.id);
         break;
+      case 'alarm:promoteTodo':
+        alarmManager.promoteTodo(msg.id);
+        break;
       case 'alarm:clearTodo':
         alarmManager.clearTodo(msg.id);
         break;