Letter-strike soft-TODO with ✓ flourish on clear

Replace the continuous leaky-bucket drain with a discrete model tied
to the 4 letters of the word TODO: each printable keypress strikes one
letter, 4 strikes clear the pill, and one letter un-strikes per
`recoverySecondsPerLetter` (default 1s) of idle. When the 4th strike
lands, the pill briefly morphs to a ✓ in the success color before
unmounting so completion is never silent.

Also fix a latent timer leak: attend() and dismissAlarm() now clear
the pending recovery timer before resetting todo to full.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nedtwigg

docs/specs/alarm.md

@@ -49,11 +49,11 @@ Each Session owns:
 - `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.
+  - `[0, 1]` (soft TODO): auto-created when a ringing alarm is phantom-dismissed (any attention path). Dashed-outline pill rendered as the word `TODO`. The value is quantized to five strike levels (`1.0` = no strikes, `0.75 / 0.5 / 0.25` = 1 / 2 / 3 letters struck, `0` = about to clear). Each printable keypress strikes exactly one letter (4 keypresses clears the TODO). After `recoverySecondsPerLetter` seconds of idle, one struck letter un-strikes; this repeats until the pill is fully un-struck. Synthetic terminal reports (focus events, cursor-position responses) do not count as keypresses.
   - `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`.
+  - Strike-timing tuning parameter is in `cfg.todoBucket.recoverySecondsPerLetter`.
 
 Each Session also owns:
 
@@ -206,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 not already `TODO_HARD`. If a partially-drained soft TODO already exists, the bucket resets to full — a fresh alarm ring deserves a full drain cycle. 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.
+All attention-based dismissals (the first three above) create a soft TODO if `todo` is not already `TODO_HARD`. If a partially-struck soft TODO already exists, the pill resets to fully un-struck — a fresh alarm ring deserves a full strike cycle. This prevents phantom dismissals where the alarm vanishes without a trace. Printable keypresses strike one letter of the `TODO` pill at a time (4 strikes clears it), so users who engage with the output don't accumulate breadcrumbs. After `cfg.todoBucket.recoverySecondsPerLetter` (default 1 s) of idle, one struck letter un-strikes; this repeats until the pill is fully un-struck. Synthetic terminal reports (focus events, cursor-position responses) do not count as keypresses.
 
 The Session leaves `ALARM_RINGING` and returns to `ALARM_DISABLED` when:
 
@@ -235,7 +235,8 @@ TODO pill:
 
 - 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
+- soft (`isSoftTodo(todo)`): dashed-outline pill — auto-created on alarm dismiss; each printable keypress strikes one letter of the word `TODO` (4 keypresses clears it), and one letter un-strikes per `recoverySecondsPerLetter` of idle
+- when the 4th strike lands and the soft TODO clears, the pill briefly morphs to a `✓` glyph in the success color (~500 ms) before unmounting — this marks the moment of completion so the pill never vanishes silently
 - `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
@@ -369,7 +370,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 → printable keypresses drain the soft TODO's leaky bucket; if enough keypresses occur without long pauses, the soft TODO clears (they engaged).
+- User types a command → each printable keypress strikes one letter of the `TODO` pill; after 4 keypresses the pill morphs to a `✓` and 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/cfg.ts

@@ -28,9 +28,9 @@ export const cfg = {
     userAttention: 15_000,
   },
   todoBucket: {
-    /** Seconds for a fully-drained soft-TODO bucket to refill to full when idle. */
-    timeToFullSeconds: 3,
-    /** Number of printable keypresses to drain a full bucket to zero. */
-    keypressesToEmpty: 5,
+    /** Seconds of idle time needed to un-strike one letter of the soft-TODO pill.
+     *  The word TODO has 4 letters; each printable keypress strikes one letter,
+     *  and each `recoverySecondsPerLetter` of idle time un-strikes one. */
+    recoverySecondsPerLetter: 1,
   },
 };

lib/src/components/Door.tsx

@@ -1,5 +1,6 @@
 import { BellIcon } from '@phosphor-icons/react';
-import { TODO_OFF, isSoftTodo, hasTodo, type SessionStatus, type TodoState } from '../lib/terminal-registry';
+import { TODO_OFF, isSoftTodo, type SessionStatus, type TodoState } from '../lib/terminal-registry';
+import { useTodoPillContent } from './TodoPillBody';
 
 export interface DoorProps {
   doorId?: string;
@@ -28,6 +29,7 @@ export function Door({
 
   const alarmEnabled = status !== 'ALARM_DISABLED';
   const alarmRinging = status === 'ALARM_RINGING';
+  const todoPill = useTodoPillContent(todo);
 
   return (
     <button
@@ -51,21 +53,16 @@ export function Door({
       <span className={['min-w-0 flex-1 truncate', (isActive && windowFocused) ? 'text-foreground' : 'text-muted'].join(' ')}>
         {title}
       </span>
-      {(hasTodo(todo) || alarmEnabled) && (
+      {(todoPill.visible || alarmEnabled) && (
         <span className="flex shrink-0 items-center gap-1.5">
-          {hasTodo(todo) && (
+          {todoPill.visible && (
             <span
               className={[
                 'rounded bg-surface-raised px-1 py-px text-[8px] font-semibold tracking-[0.08em] text-foreground',
-                isSoftTodo(todo) ? 'border border-dashed border-border' : 'border border-border',
+                isSoftTodo(todo) || todoPill.flourishing ? 'border border-dashed border-border' : 'border border-border',
               ].join(' ')}
-              style={isSoftTodo(todo) ? {
-                opacity: 0.3 + 0.7 * todo,
-                transform: `scale(${0.7 + 0.3 * todo})`,
-                transition: 'opacity 0.15s ease, transform 0.15s ease',
-              } : undefined}
             >
-              TODO
+              {todoPill.body}
             </span>
           )}
           {alarmEnabled && (

lib/src/components/Pond.tsx

@@ -36,7 +36,6 @@ import {
   type SessionStatus,
   isSoftTodo,
   isHardTodo,
-  hasTodo,
   TODO_OFF,
 } from '../lib/terminal-registry';
 import { resolvePanelElement, findPanelInDirection, findRestoreNeighbor, type DetachDirection } from '../lib/spatial-nav';
@@ -45,6 +44,7 @@ import { getPlatform } from '../lib/platform';
 import { saveSession } from '../lib/session-save';
 import type { PersistedDetachedItem } from '../lib/session-types';
 import { cfg } from '../cfg';
+import { useTodoPillContent } from './TodoPillBody';
 
 // --- Theme ---
 
@@ -538,7 +538,8 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
   const suppressAlarmClickRef = useRef(false);
   const [tier, setTier] = useState<HeaderTier>('full');
   const [dialogPosition, setDialogPosition] = useState<{ x: number; y: number } | null>(null);
-  const showTodoPill = hasTodo(sessionState.todo) && tier !== 'minimal';
+  const todoPill = useTodoPillContent(sessionState.todo);
+  const showTodoPill = todoPill.visible && tier !== 'minimal';
   const alarmButtonAriaLabel = sessionState.status === 'ALARM_RINGING'
     ? 'Alarm ringing'
     : sessionState.status === 'ALARM_DISABLED'
@@ -653,28 +654,32 @@ export function TerminalPaneHeader({ api }: IDockviewPanelHeaderProps) {
           </span>
         </HeaderActionButton>
         {showTodoPill && (
-          <button
-            type="button"
-            data-session-todo-for={api.id}
-            className={[
-              'shrink-0 rounded px-1.5 py-px text-[9px] font-semibold tracking-[0.08em] text-muted transition-colors hover:bg-foreground/10',
-              isSoftTodo(sessionState.todo) ? 'border border-dashed border-muted' : 'border border-muted',
-            ].join(' ')}
-            style={isSoftTodo(sessionState.todo) ? {
-              opacity: 0.3 + 0.7 * sessionState.todo,
-              transform: `scale(${0.7 + 0.3 * sessionState.todo})`,
-              transition: 'opacity 0.15s ease, transform 0.15s ease',
-            } : undefined}
-            aria-label="TODO settings"
-            onMouseDown={(e) => e.stopPropagation()}
-            onClick={(e) => {
-              e.stopPropagation();
-              const rect = e.currentTarget.getBoundingClientRect();
-              setDialogPosition({ x: rect.left + rect.width / 2 - 140, y: rect.bottom + 6 });
-            }}
-          >
-            TODO
-          </button>
+          todoPill.flourishing ? (
+            <span
+              className="shrink-0 rounded border border-dashed border-muted px-1.5 py-px text-[9px] font-semibold tracking-[0.08em] text-muted"
+              aria-hidden
+            >
+              {todoPill.body}
+            </span>
+          ) : (
+            <button
+              type="button"
+              data-session-todo-for={api.id}
+              className={[
+                'shrink-0 rounded px-1.5 py-px text-[9px] font-semibold tracking-[0.08em] text-muted transition-colors hover:bg-foreground/10',
+                isSoftTodo(sessionState.todo) ? 'border border-dashed border-muted' : 'border border-muted',
+              ].join(' ')}
+              aria-label="TODO settings"
+              onMouseDown={(e) => e.stopPropagation()}
+              onClick={(e) => {
+                e.stopPropagation();
+                const rect = e.currentTarget.getBoundingClientRect();
+                setDialogPosition({ x: rect.left + rect.width / 2 - 140, y: rect.bottom + 6 });
+              }}
+            >
+              {todoPill.body}
+            </button>
+          )
         )}
       </div>
       {!isRenaming && (

lib/src/components/TodoPillBody.tsx

@@ -0,0 +1,92 @@
+import { type ReactNode, useEffect, useRef, useState } from 'react';
+import {
+  hasTodo,
+  isHardTodo,
+  isSoftTodo,
+  TODO_OFF,
+  type TodoState,
+} from '../lib/terminal-registry';
+
+interface StrikeLetterProps {
+  char: string;
+  strike: boolean;
+}
+
+function StrikeLetter({ char, strike }: StrikeLetterProps) {
+  return (
+    <span className="strike-letter" data-strike={strike ? 'true' : 'false'}>
+      {char}
+    </span>
+  );
+}
+
+const TODO_LETTERS = ['T', 'O', 'D', 'O'] as const;
+const FLOURISH_MS = 500;
+
+/**
+ * Shared render body + flourish state for the soft/hard TODO pill.
+ *
+ * Returns `visible: false` when the pill should not render at all.
+ * Returns `flourishing: true` briefly after a soft TODO clears, so the
+ * caller can render a non-interactive wrapper (no click target).
+ */
+export function useTodoPillContent(todo: TodoState): {
+  visible: boolean;
+  flourishing: boolean;
+  body: ReactNode;
+} {
+  const [flourishing, setFlourishing] = useState(false);
+  const prevRef = useRef<TodoState>(todo);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    const prev = prevRef.current;
+    prevRef.current = todo;
+    if (isSoftTodo(prev) && todo === TODO_OFF) {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      setFlourishing(true);
+      timerRef.current = setTimeout(() => {
+        setFlourishing(false);
+        timerRef.current = null;
+      }, FLOURISH_MS);
+    }
+  }, [todo]);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const visible = hasTodo(todo) || flourishing;
+
+  let body: ReactNode = null;
+  if (flourishing) {
+    body = (
+      <span className="todo-pill-flourish">
+        <span className="todo-pill-flourish__letters">
+          {TODO_LETTERS.map((ch, i) => (
+            <StrikeLetter key={i} char={ch} strike />
+          ))}
+        </span>
+        <span className="todo-pill-flourish__check" aria-hidden>
+          ✓
+        </span>
+      </span>
+    );
+  } else if (isSoftTodo(todo)) {
+    const strikes = Math.round((1 - todo) * 4);
+    body = (
+      <span className="inline-flex">
+        {TODO_LETTERS.map((ch, i) => (
+          <StrikeLetter key={i} char={ch} strike={strikes > i} />
+        ))}
+      </span>
+    );
+  } else if (isHardTodo(todo)) {
+    body = <>TODO</>;
+  }
+
+  return { visible, flourishing, body };
+}