pi-wakeup 0.1.0 → 0.2.1

package/README.md

@@ -9,6 +9,22 @@ A pi extension giving a running session two tools to pace itself — the pi anal
 
 Use it to re-check something without a human poking the session — a build that takes a few minutes, a remote queue, a rate-limit window — rather than busy-waiting.
 
+## Countdown
+
+While a wakeup is pending, the session shows a live countdown to the soonest one: `17:34 · 12m · <reason>` (local fire time, whole minutes left, a truncated reason). Under a minute reads `<1m`; a missing reason drops that segment; more than one pending appends ` · +N [6m, 11m]`, the minutes left on the next two others (`…` when there are more). It re-renders every 30 s (an unref'd interval) and immediately on schedule / fire / cancel / delivery failure, and clears when nothing is pending or on shutdown.
+
+Where it shows is decided once at session start:
+
+- **tmux bar** — if this pane is inside tmux (`$TMUX` + `$TMUX_PANE`) *and* the server's global `status-left` / `status-right` already renders `@wakeup`, the countdown is written to the pane-session user option `@wakeup` (muster's `@muster_inbox` pattern) and nothing is drawn in the pi pane. Add this to your tmux `status-right` to render it:
+
+  ```tmux
+  set -g status-right '#{?@wakeup,⏰ #{@wakeup}  ,}'
+  ```
+
+- **above the editor** — otherwise (no tmux, or a config that doesn't render `@wakeup`), one line via `ctx.ui.setWidget("wakeup", …)` above the pi editor.
+
+Every tmux / UI call is best-effort: a failure in a timer callback is caught and logged, never thrown.
+
 ## Design
 
 - **Session-local.** A wakeup is an in-process `setTimeout`, not a cron job. It lives and dies with the session. This is deliberate: subagents and pacing in pi are in-process (the muster-teammate shape is shelved), and cross-session scheduling is a different product (`cron` + `pi -p`), not this tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-wakeup",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "schedule_wakeup / cancel_wakeup for the pi coding agent: session-local self-pacing, the pi analog of Claude Code's ScheduleWakeup dynamic mode.",
   "type": "module",
   "license": "MIT",

package/src/index.test.ts

@@ -4,8 +4,25 @@ import { createWakeup } from "./index.ts";
 import type { Deps } from "./index.ts";
 
 type Timer = { fn: () => void; ms: number; cancelled: boolean };
+type Interval = { fn: () => void; ms: number; cancelled: boolean };
+type TmuxCall = { socket: string; args: string[] };
+type WidgetCall = { key: string; lines: string[] | undefined };
 
-function harness(opts: { idle?: boolean; sendThrows?: boolean; idleThrows?: boolean } = {}) {
+function harness(
+  opts: {
+    idle?: boolean;
+    sendThrows?: boolean;
+    idleThrows?: boolean;
+    // Countdown display knobs. By default no tmux env -> widget mode.
+    env?: NodeJS.ProcessEnv;
+    // The tmux status-left / status-right the mode decision reads.
+    statusLeft?: string;
+    statusRight?: string;
+    // Make a tmux call or setWidget throw, to prove containment.
+    tmuxThrows?: boolean;
+    widgetThrows?: boolean;
+  } = {},
+) {
   const idle = opts.idle ?? true;
   const tools = new Map<string, any>();
   const handlers = new Map<string, (event?: unknown, ctx?: unknown) => void>();
@@ -13,13 +30,23 @@ function harness(opts: { idle?: boolean; sendThrows?: boolean; idleThrows?: bool
   const entries: Array<{ type: string; data: any }> = [];
   const notifies: Array<{ text: string; level: string }> = [];
   const timers: Timer[] = [];
+  const intervals: Interval[] = [];
+  const tmuxCalls: TmuxCall[] = [];
+  const widgetCalls: WidgetCall[] = [];
 
   const ctx = {
     isIdle: () => {
       if (opts.idleThrows) throw new Error("stale ctx");
       return idle;
     },
-    ui: { notify: (text: string, level: string) => notifies.push({ text, level }) },
+    ui: {
+      theme: { fg: (color: string, text: string) => `<${color}>${text}` },
+      notify: (text: string, level: string) => notifies.push({ text, level }),
+      setWidget: (key: string, lines: string[] | undefined) => {
+        if (opts.widgetThrows) throw new Error("stale widget ctx");
+        widgetCalls.push({ key, lines });
+      },
+    },
   };
 
   const pi = {
@@ -48,6 +75,25 @@ function harness(opts: { idle?: boolean; sendThrows?: boolean; idleThrows?: bool
       (handle as Timer).cancelled = true;
     },
     now: () => 1000,
+    setInterval: (fn: () => void, ms: number) => {
+      const i: Interval = { fn, ms, cancelled: false };
+      intervals.push(i);
+      return i;
+    },
+    clearInterval: (handle: unknown) => {
+      (handle as Interval).cancelled = true;
+    },
+    runTmux: (socket: string, args: string[]) => {
+      tmuxCalls.push({ socket, args });
+      // Serve the status strings the mode decision reads (these never throw, so
+      // the decision can still land on tmux mode even when writes blow up).
+      if (args[0] === "show" && args.includes("status-left")) return opts.statusLeft ?? "";
+      if (args[0] === "show" && args.includes("status-right")) return opts.statusRight ?? "";
+      // A write (set-option) is where a flaky tmux surfaces.
+      if (opts.tmuxThrows) throw new Error("tmux boom");
+      return "";
+    },
+    env: opts.env ?? {},
   };
 
   createWakeup(pi, deps);
@@ -60,9 +106,28 @@ function harness(opts: { idle?: boolean; sendThrows?: boolean; idleThrows?: bool
   const fire = (t: Timer) => {
     if (!t.cancelled) t.fn();
   };
-  return { tools, handlers, sent, entries, notifies, timers, schedule, cancel, fire };
+  const tmuxSets = () =>
+    tmuxCalls.filter((c) => c.args[0] === "set-option");
+  return {
+    tools,
+    handlers,
+    sent,
+    entries,
+    notifies,
+    timers,
+    intervals,
+    tmuxCalls,
+    tmuxSets,
+    widgetCalls,
+    schedule,
+    cancel,
+    fire,
+  };
 }
 
+// A tmux env whose status line renders @wakeup -> the extension uses the bar.
+const TMUX_ENV = { TMUX: "/tmp/sock,42,0", TMUX_PANE: "%7" };
+
 test("registers both tools", () => {
   const h = harness();
   assert.ok(h.tools.has("schedule_wakeup"));
@@ -177,3 +242,94 @@ test("session_shutdown clears every timer and no wakeup can still deliver", asyn
   h.timers.forEach((t) => t.fn());
   assert.equal(h.sent.length, 0);
 });
+
+// --- Countdown display -----------------------------------------------------
+
+test("widget mode: scheduling shows a line above the editor and arms a refresh", async () => {
+  const h = harness(); // no tmux env -> widget
+  await h.schedule({ delay_seconds: 120, prompt: "x", reason: "CI" });
+  const last = h.widgetCalls.at(-1)!;
+  assert.equal(last.key, "wakeup");
+  assert.equal(last.lines!.length, 1);
+  assert.match(last.lines![0], /2m/); // 120s from now()=1000 -> 2m remaining
+  assert.match(last.lines![0], /CI/);
+  assert.match(last.lines![0], /^<warning>⏰ /); // styled like the tmux bar
+  assert.equal(h.intervals.length, 1);
+  assert.equal(h.intervals[0].cancelled, false);
+  // The tmux runner is never touched in widget mode.
+  assert.equal(h.tmuxSets().length, 0);
+});
+
+test("widget mode: a refresh tick re-renders while pending", async () => {
+  const h = harness();
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  const before = h.widgetCalls.length;
+  h.intervals[0].fn(); // simulate a 30s tick
+  assert.ok(h.widgetCalls.length > before);
+});
+
+test("widget mode: cancelling the last wakeup clears the widget and stops the refresh", async () => {
+  const h = harness();
+  const res = await h.schedule({ delay_seconds: 120, prompt: "x" });
+  await h.cancel({ id: res.details.id });
+  const last = h.widgetCalls.at(-1)!;
+  assert.equal(last.lines, undefined); // cleared
+  assert.equal(h.intervals[0].cancelled, true);
+});
+
+test("widget mode: firing clears the display when nothing else is pending", async () => {
+  const h = harness({ idle: true });
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  h.fire(h.timers[0]);
+  assert.equal(h.widgetCalls.at(-1)!.lines, undefined);
+  assert.equal(h.intervals[0].cancelled, true);
+});
+
+test("tmux mode: sets @wakeup on the pane session and never draws a widget", async () => {
+  const h = harness({ env: TMUX_ENV, statusRight: "#{?@wakeup,x,}" });
+  await h.schedule({ delay_seconds: 120, prompt: "x", reason: "CI" });
+  const set = h.tmuxSets().at(-1)!;
+  assert.deepEqual(set.args.slice(0, 4), ["set-option", "-t", "%7", "@wakeup"]);
+  assert.match(set.args[4], /2m/);
+  assert.equal(set.socket, "sock"); // basename of /tmp/sock
+  assert.equal(h.widgetCalls.length, 0); // nothing in the pi pane
+});
+
+test("tmux mode: cancelling the last wakeup unsets @wakeup", async () => {
+  const h = harness({ env: TMUX_ENV, statusRight: "#{?@wakeup,x,}" });
+  await h.cancel({}); // nothing pending -> no-op, but prove the unset path on real cancel
+  const res = await h.schedule({ delay_seconds: 120, prompt: "x" });
+  await h.cancel({ id: res.details.id });
+  const set = h.tmuxSets().at(-1)!;
+  assert.deepEqual(set.args, ["set-option", "-u", "-t", "%7", "@wakeup"]);
+  assert.equal(h.widgetCalls.length, 0);
+});
+
+test("tmux mode is NOT used when the status line doesn't render @wakeup", async () => {
+  const h = harness({ env: TMUX_ENV, statusRight: "plain bar", statusLeft: "also plain" });
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  // Falls back to the widget; no @wakeup option set.
+  assert.ok(h.widgetCalls.length > 0);
+  assert.equal(h.tmuxSets().length, 0);
+});
+
+test("tmux mode: a throwing set-option is contained and does not fail the schedule", async () => {
+  // Decision lands on tmux (show calls succeed); the set-option write throws.
+  const h = harness({ env: TMUX_ENV, statusRight: "#{?@wakeup,x,}", tmuxThrows: true });
+  await assert.doesNotReject(() => h.schedule({ delay_seconds: 120, prompt: "x" }));
+  assert.ok(h.tmuxSets().length >= 1); // it tried the write
+  assert.equal(h.widgetCalls.length, 0); // still never drew a widget
+});
+
+test("a throwing setWidget is contained and does not fail the schedule", async () => {
+  const h = harness({ widgetThrows: true });
+  await assert.doesNotReject(() => h.schedule({ delay_seconds: 120, prompt: "x" }));
+});
+
+test("session_shutdown clears the display and stops the refresh interval", async () => {
+  const h = harness();
+  await h.schedule({ delay_seconds: 120, prompt: "x" });
+  h.handlers.get("session_shutdown")!();
+  assert.equal(h.widgetCalls.at(-1)!.lines, undefined); // cleared
+  assert.equal(h.intervals[0].cancelled, true);
+});

package/src/index.ts

@@ -20,13 +20,22 @@
 // (the extension API exposes no entry read-back). Within a live session,
 // wakeups fire.
 
+import { execFileSync } from "node:child_process";
 import {
   clampDelaySeconds,
+  decideDisplayMode,
   deliveryMode,
+  formatCountdown,
   wakeupMessage,
 } from "./schedule.ts";
 
-type Pending = { prompt: string; reason: string };
+// fireAtMs is tracked per pending wakeup so the countdown display can derive
+// how long is left; it's the same value persisted in the wakeup_scheduled entry.
+type Pending = { prompt: string; reason: string; fireAtMs: number };
+
+// How often the countdown re-renders while anything is pending. The interval is
+// unref'd so it never holds the process open on its own.
+const REFRESH_MS = 30_000;
 
 export type Deps = {
   // Injectable so the wiring is testable without real time passing. Default to
@@ -34,6 +43,14 @@ export type Deps = {
   setTimer?: (fn: () => void, ms: number) => unknown;
   clearTimer?: (handle: unknown) => void;
   now?: () => number;
+  // The countdown's periodic refresh, also injectable so tests can drive it.
+  setInterval?: (fn: () => void, ms: number) => unknown;
+  clearInterval?: (handle: unknown) => void;
+  // The tmux runner, mirroring pi-tmux-bridge's `tmux()`: best-effort, returns
+  // the trimmed stdout or undefined. Injected so the tmux-bar path is testable.
+  runTmux?: (socket: string, args: string[]) => string | undefined;
+  // The environment the tmux mode decision reads ($TMUX / $TMUX_PANE).
+  env?: NodeJS.ProcessEnv;
 };
 
 const SCHEDULE_PARAMS = {
@@ -80,6 +97,34 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
   const clearTimer =
     deps.clearTimer ?? ((handle: unknown) => clearTimeout(handle as ReturnType<typeof setTimeout>));
   const now = deps.now ?? (() => Date.now());
+  const setIntervalFn =
+    deps.setInterval ??
+    ((fn: () => void, ms: number) => {
+      const handle = setInterval(fn, ms);
+      // Unref'd like the per-wakeup timer: the refresh loop is cosmetic and must
+      // never be the reason the process stays alive.
+      const unrefable = handle as { unref?: () => void };
+      if (typeof unrefable.unref === "function") unrefable.unref();
+      return handle;
+    });
+  const clearIntervalFn =
+    deps.clearInterval ??
+    ((handle: unknown) => clearInterval(handle as ReturnType<typeof setInterval>));
+  const runTmux =
+    deps.runTmux ??
+    ((socket: string, args: string[]) => {
+      // Best-effort, mirroring pi-tmux-bridge's tmux(): a display call must never
+      // fail a tool call, a timer callback, or a shutdown.
+      try {
+        return execFileSync("tmux", ["-L", socket, ...args], {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+      } catch {
+        return undefined;
+      }
+    });
+  const env = deps.env ?? process.env;
 
   const pending = new Map<string, Pending>();
   const timers = new Map<string, unknown>();
@@ -88,6 +133,14 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
   let ctx: any;
   let counter = 0;
 
+  // Countdown display state, decided ONCE at session_start. In tmux mode we set
+  // a pane-session option the status line renders; otherwise we draw a widget
+  // above the pi editor. intervalHandle re-renders the minutes ticking down.
+  let displayTarget: "tmux" | "widget" = "widget";
+  let tmuxSocket: string | undefined;
+  let tmuxPane: string | undefined;
+  let intervalHandle: unknown;
+
   function log(message: string): void {
     try {
       process.stderr.write(`[wakeup] ${message}\n`);
@@ -96,6 +149,117 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
     }
   }
 
+  // Local HH:MM in the machine's timezone — the fire time a human reads off
+  // the bar. Kept here (not in schedule.ts) so the pure formatter stays TZ-free.
+  function formatClock(ms: number): string {
+    const d = new Date(ms);
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    return `${hh}:${mm}`;
+  }
+
+  // $TMUX is "<socket-path>,<pid>,<session>"; the socket NAME is the basename of
+  // the first field, exactly as pi-tmux-bridge resolves it. undefined unless
+  // both $TMUX and $TMUX_PANE are set.
+  function resolveTmuxCtx(): { socket: string; pane: string } | undefined {
+    const tmuxEnv = env.TMUX;
+    const pane = env.TMUX_PANE;
+    if (!tmuxEnv || !pane) return undefined;
+    const socketPath = tmuxEnv.split(",")[0];
+    if (!socketPath) return undefined;
+    const socket = socketPath.slice(socketPath.lastIndexOf("/") + 1);
+    if (!socket) return undefined;
+    return { socket, pane };
+  }
+
+  // Decide where the countdown shows, ONCE, from the env and the tmux server's
+  // global status strings. Best-effort: any failure falls back to the widget.
+  function decideDisplay(): void {
+    try {
+      const t = resolveTmuxCtx();
+      if (!t) {
+        displayTarget = "widget";
+        return;
+      }
+      const left = runTmux(t.socket, ["show", "-gv", "status-left"]);
+      const right = runTmux(t.socket, ["show", "-gv", "status-right"]);
+      displayTarget = decideDisplayMode(env, left, right);
+      if (displayTarget === "tmux") {
+        tmuxSocket = t.socket;
+        tmuxPane = t.pane;
+      }
+    } catch (error) {
+      displayTarget = "widget";
+      log(`display mode decision failed: ${String(error)}`);
+    }
+  }
+
+  // The widget line matches the tmux bar: a clock and the theme's warning
+  // (yellow) colour, so it stands out above the editor. The theme read is
+  // guarded like every other ctx.ui access; without one the line is plain.
+  function widgetLine(text: string): string {
+    const line = `⏰ ${text}`;
+    try {
+      const theme = ctx?.ui?.theme;
+      return theme && typeof theme.fg === "function" ? theme.fg("warning", line) : line;
+    } catch {
+      return line;
+    }
+  }
+
+  // Render the current pending list to the chosen target, or clear it when
+  // nothing is pending. Runs inside timer/interval callbacks, so every tmux and
+  // ctx.ui call is guarded — a throw here must never escape (best-effort).
+  function refresh(): void {
+    const view = [...pending.values()].map((p) => ({ fireAtMs: p.fireAtMs, reason: p.reason }));
+    const text = formatCountdown(view, now(), formatClock);
+    try {
+      if (displayTarget === "tmux" && tmuxSocket && tmuxPane) {
+        // Follows muster's @muster_inbox pattern: set the user option on THIS
+        // pane's session; `-u` unsets it so the status segment collapses.
+        if (text === undefined) {
+          runTmux(tmuxSocket, ["set-option", "-u", "-t", tmuxPane, "@wakeup"]);
+        } else {
+          runTmux(tmuxSocket, ["set-option", "-t", tmuxPane, "@wakeup", text]);
+        }
+        return;
+      }
+      // Widget mode. Guard ctx.ui: a ctx captured at session_start goes stale
+      // after /reload or a session switch, and setWidget would then throw.
+      if (ctx?.ui?.setWidget) {
+        ctx.ui.setWidget("wakeup", text === undefined ? undefined : [widgetLine(text)]);
+      }
+    } catch (error) {
+      log(`display refresh failed: ${String(error)}`);
+    }
+  }
+
+  // Re-render now and keep the refresh interval in step with the pending set:
+  // start it when something is pending, stop it (and clear the display implied
+  // by an empty set) when nothing is.
+  function syncDisplay(): void {
+    refresh();
+    if (pending.size === 0) {
+      stopInterval();
+    } else if (intervalHandle === undefined) {
+      intervalHandle = setIntervalFn(() => {
+        try {
+          refresh();
+        } catch {
+          // refresh is already guarded; this is belt-and-braces for the callback.
+        }
+        if (pending.size === 0) stopInterval();
+      }, REFRESH_MS);
+    }
+  }
+
+  function stopInterval(): void {
+    if (intervalHandle !== undefined) {
+      clearIntervalFn(intervalHandle);
+      intervalHandle = undefined;
+    }
+  }
+
   function forget(id: string): void {
     const handle = timers.get(id);
     if (handle !== undefined) clearTimer(handle);
@@ -107,8 +271,9 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
     const w = pending.get(id);
     if (!w) return;
     // Remove BEFORE delivering: one-shot, and a throw in sendMessage must not
-    // leave a half-fired wakeup armed.
+    // leave a half-fired wakeup armed. Refresh the countdown off the firing.
     forget(id);
+    syncDisplay();
     // Reading ctx.isIdle() can THROW: a ctx captured at session_start goes
     // stale after /reload, fork, or a session switch (assertActive() throws),
     // and this runs up to an hour later inside a setTimeout callback where an
@@ -153,11 +318,19 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
 
   pi.on("session_start", (_event: unknown, sessionCtx: any) => {
     ctx = sessionCtx;
+    // Decide the display target once, now, from the env + tmux status strings.
+    decideDisplay();
+    // Nothing is pending at a fresh start, so this just clears any stale display.
+    refresh();
   });
   pi.on("session_shutdown", () => {
     for (const handle of timers.values()) clearTimer(handle);
     timers.clear();
     pending.clear();
+    stopInterval();
+    // Clear the display: with pending now empty, refresh() unsets the option /
+    // removes the widget.
+    refresh();
   });
 
   pi.registerTool({
@@ -181,7 +354,7 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
       counter += 1;
       const id = `wake-${counter}`;
       const fireAtMs = now() + delay * 1000;
-      pending.set(id, { prompt, reason });
+      pending.set(id, { prompt, reason, fireAtMs });
       const handle = setTimer(() => deliver(id), delay * 1000);
       timers.set(id, handle);
       try {
@@ -189,6 +362,8 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
       } catch {
         // best-effort persistence
       }
+      // Show the new wakeup and arm the refresh loop.
+      syncDisplay();
       const reasonText = reason ? ` (${reason})` : "";
       return {
         content: [{ type: "text", text: `Scheduled ${id}: waking in ${delay}s${reasonText}.` }],
@@ -214,6 +389,8 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
           } catch {
             // best-effort persistence
           }
+          // Update (or clear) the countdown now that one is gone.
+          syncDisplay();
         }
         return {
           content: [
@@ -229,6 +406,8 @@ export function createWakeup(pi: any, deps: Deps = {}): void {
         } catch {
           // best-effort persistence
         }
+        // Everything's gone: clear the display and stop the refresh loop.
+        syncDisplay();
       }
       return { content: [{ type: "text", text: `Cancelled ${count} pending wakeup${count === 1 ? "" : "s"}.` }] };
     },

package/src/schedule.test.ts

@@ -2,8 +2,13 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import {
   clampDelaySeconds,
+  decideDisplayMode,
   deliveryMode,
+  formatCountdown,
+  formatRemaining,
+  truncateReason,
   wakeupMessage,
+  MAX_REASON_LENGTH,
   MIN_DELAY_SECONDS,
   MAX_DELAY_SECONDS,
 } from "./schedule.ts";
@@ -52,3 +57,77 @@ test("wakeupMessage: an empty or whitespace reason leaves the prompt bare", () =
   assert.equal(wakeupMessage("check the build", ""), "check the build");
   assert.equal(wakeupMessage("check the build", "   "), "check the build");
 });
+
+// A fixed HH:MM formatter so these assertions never depend on the machine's TZ.
+const clock = (ms: number) => (ms === 0 ? "17:34" : `t+${ms}`);
+
+test("formatRemaining: whole minutes, and under a minute collapses to <1m", () => {
+  assert.equal(formatRemaining(12 * 60_000), "12m");
+  assert.equal(formatRemaining(12 * 60_000 + 59_000), "12m"); // floored
+  assert.equal(formatRemaining(59_000), "<1m");
+  assert.equal(formatRemaining(0), "<1m");
+  assert.equal(formatRemaining(-5000), "<1m"); // a refresh racing the fire
+});
+
+test("truncateReason: long reasons are cut with an ellipsis, short ones pass through", () => {
+  assert.equal(truncateReason("waiting on CI"), "waiting on CI");
+  assert.equal(truncateReason("   waiting on CI   "), "waiting on CI"); // trimmed
+  const long = "a".repeat(40);
+  const out = truncateReason(long);
+  assert.equal(out.length, MAX_REASON_LENGTH);
+  assert.ok(out.endsWith("\u2026"));
+});
+
+test("formatCountdown: nothing pending clears the display", () => {
+  assert.equal(formatCountdown([], 0, clock), undefined);
+});
+
+test("formatCountdown: soonest wakeup as time \u00b7 minutes \u00b7 reason", () => {
+  const text = formatCountdown([{ fireAtMs: 0, reason: "waiting on CI" }], -12 * 60_000, clock);
+  assert.equal(text, "17:34 \u00b7 12m \u00b7 waiting on CI");
+});
+
+test("formatCountdown: no reason omits that segment", () => {
+  const text = formatCountdown([{ fireAtMs: 0, reason: "" }], -12 * 60_000, clock);
+  assert.equal(text, "17:34 \u00b7 12m");
+});
+
+test("formatCountdown: more pending appends +N with the others' times, soonest first", () => {
+  const pending = [
+    { fireAtMs: 300_000, reason: "later" },
+    { fireAtMs: 0, reason: "soon" },
+    { fireAtMs: 600_000, reason: "latest" },
+  ];
+  const text = formatCountdown(pending, -60_000, clock);
+  // Soonest (fireAtMs 0) drives the line; the two others become +2 with their times.
+  assert.equal(text, "17:34 \u00b7 1m \u00b7 soon \u00b7 +2 [6m, 11m]");
+});
+
+test("formatCountdown: the others' times are capped, the rest shown as \u2026", () => {
+  const pending = [0, 300_000, 600_000, 900_000, 1_200_000].map((fireAtMs) => ({ fireAtMs, reason: "" }));
+  const text = formatCountdown(pending, -60_000, clock);
+  assert.equal(text, "17:34 \u00b7 1m \u00b7 +4 [6m, 11m, \u2026]");
+});
+
+test("formatCountdown: a long reason is truncated in the line", () => {
+  const text = formatCountdown(
+    [{ fireAtMs: 0, reason: "x".repeat(40) }],
+    -5 * 60_000,
+    clock,
+  );
+  assert.ok(text!.includes("\u2026"));
+});
+
+test("decideDisplayMode: tmux only when in a pane AND the status renders @wakeup", () => {
+  const inPane = { TMUX: "/tmp/sock,1,0", TMUX_PANE: "%3" };
+  assert.equal(decideDisplayMode(inPane, "", "#{?@wakeup,x,}"), "tmux"); // status-right
+  assert.equal(decideDisplayMode(inPane, "@wakeup", ""), "tmux"); // status-left
+  assert.equal(decideDisplayMode(inPane, "", ""), "widget"); // config doesn't render it
+  assert.equal(decideDisplayMode(inPane, undefined, undefined), "widget");
+});
+
+test("decideDisplayMode: no tmux env is always the widget", () => {
+  assert.equal(decideDisplayMode({}, "@wakeup", "@wakeup"), "widget");
+  assert.equal(decideDisplayMode({ TMUX: "/tmp/sock,1,0" }, "@wakeup", "@wakeup"), "widget");
+  assert.equal(decideDisplayMode({ TMUX_PANE: "%3" }, "@wakeup", "@wakeup"), "widget");
+});

package/src/schedule.ts

@@ -39,3 +39,84 @@ export function wakeupMessage(prompt: string, reason: string): string {
   const suffix = trimmedReason ? `\n\n(scheduled wakeup — ${trimmedReason})` : "";
   return `${prompt}${suffix}`;
 }
+
+// --- Countdown display -----------------------------------------------------
+// The session's pending wakeups, shown with a live countdown so a human can
+// see what the session is waiting on and when it restarts. Pure here (text +
+// mode decision); the I/O — reading tmux, writing a widget or a tmux option —
+// lives in index.ts.
+
+// A pending wakeup, reduced to just what the countdown needs: when it fires and
+// why. index.ts carries the full record (prompt, timer handle); this is the
+// view the formatter sees.
+export type PendingView = { fireAtMs: number; reason: string };
+
+// Reasons are shown inline in a status bar, so a long one is truncated to keep
+// the line short; the ellipsis marks the cut.
+export const MAX_REASON_LENGTH = 25;
+
+export function truncateReason(reason: string, max = MAX_REASON_LENGTH): string {
+  const trimmed = typeof reason === "string" ? reason.trim() : "";
+  if (trimmed.length <= max) return trimmed;
+  // Reserve one char for the ellipsis so the result is exactly `max` wide.
+  return `${trimmed.slice(0, max - 1)}…`;
+}
+
+// Whole minutes remaining until a fire time. Anything under a minute (including
+// a fire time already past, if a refresh races the timer) collapses to `<1m`
+// rather than showing `0m`.
+export function formatRemaining(remainingMs: number): string {
+  if (remainingMs < 60_000) return "<1m";
+  return `${Math.floor(remainingMs / 60_000)}m`;
+}
+
+// The countdown line for the soonest pending wakeup:
+//   `17:34 · 12m · <reason>`  (fire time, minutes remaining, truncated reason)
+// A missing reason drops that segment; more than one pending appends
+// ` · +N [6m, 11m]`, the others' minutes left, capped at MAX_OTHER_TIMES with
+// `…` for the rest.
+// Returns undefined when nothing is pending, so the caller clears the display.
+// The HH:MM formatter is injected so tests need not depend on the machine's TZ.
+export function formatCountdown(
+  pending: PendingView[],
+  nowMs: number,
+  formatHHMM: (ms: number) => string,
+): string | undefined {
+  if (pending.length === 0) return undefined;
+  // Soonest fire time first — that's the one we count down to.
+  const sorted = [...pending].sort((a, b) => a.fireAtMs - b.fireAtMs);
+  const soonest = sorted[0];
+  const parts = [formatHHMM(soonest.fireAtMs), formatRemaining(soonest.fireAtMs - nowMs)];
+  const reason = truncateReason(soonest.reason ?? "");
+  if (reason) parts.push(reason);
+  let text = parts.join(" · ");
+  const others = sorted.slice(1);
+  if (others.length > 0) {
+    const times = others.slice(0, MAX_OTHER_TIMES).map((w) => formatRemaining(w.fireAtMs - nowMs));
+    if (others.length > MAX_OTHER_TIMES) times.push("…");
+    text += ` · +${others.length} [${times.join(", ")}]`;
+  }
+  return text;
+}
+
+// How many of the other pending wakeups list their time after `+N`; two keeps
+// the status bar to one short line.
+export const MAX_OTHER_TIMES = 2;
+
+// Where the countdown shows, decided ONCE at session_start. The tmux bar is
+// used only when this pane is inside tmux AND the server's global status line
+// actually renders `@wakeup` (otherwise the option we set would go nowhere);
+// everything else falls back to a widget above the pi editor.
+export type DisplayMode = "tmux" | "widget";
+
+export function decideDisplayMode(
+  env: { TMUX?: string; TMUX_PANE?: string },
+  statusLeft: string | undefined,
+  statusRight: string | undefined,
+): DisplayMode {
+  if (!env.TMUX || !env.TMUX_PANE) return "widget";
+  const left = statusLeft ?? "";
+  const right = statusRight ?? "";
+  if (left.includes("@wakeup") || right.includes("@wakeup")) return "tmux";
+  return "widget";
+}