tuiboard 0.13.3 → 0.14.0

package/.tuiboard/config.example.yaml

@@ -95,6 +95,12 @@ archive_column: Archive
 # Nushell users typically want `;` instead of `&&`:
 # copy_resume_command: 'cd "{cwd}"; {resume}'
 
+# Optional: a markdown file to read from inside tuiboard with `i` — a morning
+# digest, a handover note, whatever you (or an agent) write there. Shown as it
+# is: never parsed, never written to. Relative paths resolve against this file,
+# `~` works. tuiboard picks up changes while the dialog is open.
+# status_file: ~/vault/Home.md
+
 # Optional: overlay read-only calendar events on the Agenda (the 24h timeline).
 # Connect a provider with `tuiboard calendar-setup google` / `... microsoft`,
 # which opens the auth flow and prints the exact block to paste here. Bring your

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-09-21
+
+### Added
+- **Status file viewer** (#67): point `status_file:` at a markdown file — a
+  morning digest, a handover note, whatever you or an agent write there — and
+  `i` shows it in a dialog, read-only. The markdown is rendered rather than
+  shown as source: headings and bold as weight, links and wikilinks by their
+  label, list and checkbox glyphs, frontmatter hidden. `j`/`k`, arrows and
+  PgUp/PgDn scroll it. It re-reads itself while open when the file changes,
+  and `tuiboard summary` reports its path and mtime (never its body) when
+  configured.
+- **Overdue tasks show how late they are** (#67): a task overdue for days is
+  painted in a louder red than one that slipped yesterday. No day count
+  anywhere — just two bands.
+- **Agent interface documentation** (#69): `docs/agent-interface.md` spells
+  out `tuiboard summary` and `tuiboard task` as a stable contract for agents
+  and scripts — the JSON shape, title matching, exit codes and the rules that
+  keep an agent from corrupting a board.
+
+### Changed
+- **Time blocking in arm mode takes fewer round trips** (#73). A task placed
+  on the agenda stays armed, so `+`/`-` and `j`/`k` size and move it straight
+  away. `Enter` keeps it and returns to where `c` was pressed (usually
+  Today/Tomorrow — in single-pane, without passing through the agents panel);
+  `Esc` puts the task back as it was and returns the same way.
+
+### Fixed
+- **Keypad `+` grows an armed time block** (#71) instead of opening the "new
+  board" dialog.
+- Arming a second task no longer rewrites the first task's reference in place
+  (#73), a latent bug surfaced by the new arm-mode tests.
+
 ## [0.13.3] - 2026-09-19
 
 ### Fixed
@@ -512,6 +544,7 @@ First public release on npm. This entry captures the full feature set at launch.
 
 Built with [OpenTUI](https://opentui.com) + SolidJS on Bun.
 
+[0.14.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.14.0
 [0.13.3]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.3
 [0.13.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.2
 [0.13.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.1

package/README.md

@@ -204,6 +204,12 @@ archive_column: Archive
 # yourself in any tab/pane (no WezTerm needed). {cwd}/{sessionId}/{resume}
 # substituted. Default: 'cd "{cwd}" && {resume}'. Nushell users:
 # copy_resume_command: 'cd "{cwd}"; {resume}'
+
+# Optional: a markdown file to read from inside tuiboard with `i` — a morning
+# digest, a handover note, whatever you (or an agent) write there. Shown as it
+# is: never parsed, never written to. `~` works, relative paths resolve against
+# the config file. Unconfigured, `i` just explains how to set it.
+# status_file: ~/vault/Home.md
 ```
 
 ## Zones
@@ -456,6 +462,10 @@ session (until the next terminal resize).
 | `c` | Arm mode: click a task, then click a slot to schedule (works from any zone) |
 | `j` / `k` | While armed: nudge the block ±15 min |
 | `+` / `-` | While armed: resize the block's end ±15 min |
+| `Enter` | While armed: keep the placement and go back to where `c` was pressed |
+| `Esc` | While armed: undo the placement and go back to where `c` was pressed |
+
+A placed task stays armed, so it can be sized and moved straight away.
 
 ### Agents (agents zone)
 
@@ -501,11 +511,17 @@ session (until the next terminal resize).
 | `n` | New task in current column (quick-add syntax) |
 | `Shift-T` | Reset ALL overdue tasks (any board) to today |
 | `Ctrl-Z` | Undo last mutation |
+| `i` | Status file — the markdown file set as `status_file`, shown read-only |
 | `?` | Help modal with the full reference |
 | `q` · `Ctrl-C` | Quit |
 
 ## Headless commands
 
+> Driving tuiboard from Claude Code, Codex or any other agent?
+> [docs/agent-interface.md](docs/agent-interface.md) documents these two
+> commands as an API: the JSON shape, the matching rules, the exit codes, and
+> the handful of rules that keep an agent from corrupting a board.
+
 Two subcommands run without the TUI, for status bars, widgets and scripts.
 Both reuse the same config loader and parser as the dashboard, so they can
 never disagree with it about what is on your board.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.13.3",
+  "version": "0.14.0",
   "description": "Terminal kanban for markdown task boards, with optional Today/Tomorrow planner, 24h agenda + calendar overlay, and a live view of your coding-agent sessions (Claude Code, Codex, OpenCode, Pi). Use only the panels you want.",
   "type": "module",
   "license": "MIT",

package/src/cli/summary.ts

@@ -12,7 +12,7 @@
  * dashboard shows — the parser stays the single source of truth.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 
 import { isHiddenColumn, loadConfig } from "~/config/loader";
 import { isTask, parseBoard } from "~/parser/markdown";
@@ -92,6 +92,22 @@ export interface Summary {
    * widget and the dashboard can never disagree about what is due.
    */
   planner: Record<PlannerSection, PlannerEntry[]>;
+  /**
+   * The configured status file, when there is one: mtime only, never the
+   * body. A bar widget wants to know *that* it changed — laying out a page of
+   * prose is the TUI's job. Absent when unconfigured, so every existing
+   * consumer sees the shape it already knows.
+   */
+  statusFile?: { path: string; updatedAt: string | null };
+}
+
+/** A file's mtime as ISO, or null when it isn't there. */
+function statMtimeIso(path: string): string | null {
+  try {
+    return new Date(statSync(path).mtimeMs).toISOString();
+  } catch {
+    return null;
+  }
 }
 
 /** Local calendar date as YYYY-MM-DD — never UTC, or "today" flips at the wrong hour. */
@@ -253,7 +269,22 @@ export function buildSummary(options: { next?: number; today?: string } = {}): S
     });
   }
 
-  return { generatedAt: new Date().toISOString(), totals, boards, planner };
+  const statusFile = config.statusFilePath
+    ? {
+        path: config.statusFilePath,
+        // null, not absent: configured but not written yet is a state a widget
+        // may want to show, and it differs from "no status file at all".
+        updatedAt: statMtimeIso(config.statusFilePath),
+      }
+    : undefined;
+
+  return {
+    generatedAt: new Date().toISOString(),
+    totals,
+    boards,
+    planner,
+    ...(statusFile ? { statusFile } : {}),
+  };
 }
 
 export async function runSummary(argv: readonly string[]): Promise<number> {

package/src/config/loader.ts

@@ -59,6 +59,13 @@ export interface Config {
    * Windows, `$SHELL` elsewhere). Ignored when `resumeCommand` is set.
    */
   resumeShell: "auto" | Shell;
+  /**
+   * A markdown file to read from inside tuiboard with `i` (config
+   * `status_file`) — a morning digest, a handover note, whatever is written
+   * there. Read-only and never parsed: tuiboard shows it, nothing else.
+   * Unset means the key does nothing.
+   */
+  statusFilePath?: string;
   /**
    * Agent status glyphs (config `status_indicators`): `symbols` (default —
    * the same × ◐ ✓ ○ · herdr uses) or `dots` (● ○ ·).
@@ -223,6 +230,7 @@ interface RawConfig {
   resume_terminal: string;
   resume_shell: string;
   status_indicators: string;
+  status_file: string;
   copy_resume_command: string;
   calendars: {
     google?: {
@@ -374,6 +382,10 @@ function normalize(raw: Partial<RawConfig>, root: string, loaded: boolean): Conf
     resumeShell: (SHELLS as readonly string[]).includes(raw.resume_shell ?? "")
       ? (raw.resume_shell as Shell)
       : "auto",
+    statusFilePath:
+      typeof raw.status_file === "string" && raw.status_file.trim()
+        ? expandPath(raw.status_file.trim(), root)
+        : undefined,
     statusIndicators: raw.status_indicators === "dots" ? "dots" : "symbols",
     copyResumeCommand:
       typeof raw.copy_resume_command === "string" &&

package/src/input/handleKey.ts

@@ -24,6 +24,7 @@ import {
   systemLaunchEnv,
 } from "~/input/open-session";
 import { planHerdrFocus, planHerdrResume } from "~/input/herdr-open";
+import { isMinusKey, isPlusKey } from "~/input/keys";
 import { HARNESS, type AgentSession } from "~/store/agents";
 import { herdrBin, herdrPlace } from "~/store/herdr";
 import { googleTokenCanWrite } from "~/store/calendar";
@@ -31,6 +32,7 @@ import { isTask } from "~/parser/markdown";
 import {
   isoToday,
   isoTomorrow,
+  type ArmOrigin,
   type ModalKind,
   type TaskRef,
   type TuiStore,
@@ -116,6 +118,17 @@ export function handleKey(
       store.closeModal();
       return;
     }
+    // The status file closes on its own key too, like `o` closes the detail.
+    if (ui.modal.kind === "status-file") {
+      if (key.name === "i") { store.closeModal(); return; }
+      const step =
+        key.name === "j" || key.name === "down" ? 1 :
+        key.name === "k" || key.name === "up" ? -1 :
+        key.name === "pagedown" || key.name === "space" ? 10 :
+        key.name === "pageup" ? -10 : 0;
+      if (step) store.setStatusScroll(ui.statusScroll + step);
+      return;
+    }
     // Help modal: j/k (or arrows) scroll its keyboard reference.
     if (ui.modal.kind === "help") {
       if (key.name === "j" || key.name === "down") { store.setHelpScroll(ui.helpScroll + 1); return; }
@@ -146,10 +159,11 @@ export function handleKey(
   // disruptive first.
   if (key.name === "escape") {
     if (ui.armMode || ui.armedTimelineRef) {
-      const wasMode = ui.armMode;
-      store.setArmMode(false);
-      store.armTimeline(undefined);
-      store.flashBanner("info", wasMode ? "Arm mode off" : "Disarmed");
+      // Cancel: the armed task goes back to how it was, the cursor to where
+      // `c` was pressed (#73).
+      const hadTask = !!ui.armedTimelineRef;
+      restoreArmOrigin(store, store.leaveArmMode(false), plannerCount);
+      store.flashBanner("info", hadTask ? "Cancelled" : "Arm mode off");
       return;
     }
     if (ui.selectedCalEvent) {
@@ -212,9 +226,10 @@ export function handleKey(
     return;
   }
 
-  // New board — the `+` chip in the top bar, and its key. Free at this level:
-  // `+` is otherwise only used inside the timeline's duration sub-mode.
-  if (key.name === "+" || key.sequence === "+" || (key.name === "=" && key.shift)) {
+  // New board — the `+` chip in the top bar, and its key. Except on the
+  // agenda with a block armed: there `+` grows the block (handleTimelineZone),
+  // and this shortcut running first used to swallow it (#71).
+  if (isPlusKey(key) && !(ui.armedTimelineRef && ui.activeZone === "timeline")) {
     store.openBoardNew();
     return;
   }
@@ -270,6 +285,14 @@ export function handleKey(
     return;
   }
 
+  // The status file: a markdown file read once in a while (a morning digest,
+  // a handover note), shown in a dialog. `i` for "info"; `u` and `w` were the
+  // other free letters, both easier to misread as undo / write.
+  if (key.name === "i") {
+    store.openModal({ kind: "status-file" });
+    return;
+  }
+
   // Zoom toggle: focus the active panel (board column or planner panel)
   // at full width.
   if (key.name === "z") {
@@ -320,7 +343,7 @@ export function handleKey(
   }
 
   if (ui.activeZone === "timeline") {
-    handleTimelineZone(store, key, openLater);
+    handleTimelineZone(store, key, plannerCount, openLater);
     return;
   }
 
@@ -373,9 +396,22 @@ function handlePlannerZone(
   }
 }
 
+/** Put the cursor back where `c` started arm mode. */
+function restoreArmOrigin(store: TuiStore, origin: ArmOrigin | undefined, plannerCount = Infinity): boolean {
+  if (!origin) return false;
+  if (origin.boardIndex !== store.state.ui.activeBoardIndex) store.setActiveBoard(origin.boardIndex);
+  store.setActiveZone(origin.zone);
+  // Placing a task can reorder the planner (it joins the time-blocked
+  // bucket); the row stays, clamped to what's there.
+  const row = origin.zone === "planner" ? Math.min(origin.row, Math.max(0, plannerCount - 1)) : origin.row;
+  store.setCursor(origin.col, row);
+  return true;
+}
+
 function handleTimelineZone(
   store: TuiStore,
   key: KeyEvent,
+  plannerCount: number,
   openLater: (m: ModalKind) => void,
 ): void {
   const ui = store.state.ui;
@@ -427,6 +463,16 @@ function handleTimelineZone(
       )
     : undefined;
 
+  // Enter confirms whatever is armed — placed or not — and goes back to where
+  // `c` started; a task armed straight from its band still jumps to its card.
+  if (armedRef && (key.name === "enter" || key.name === "return")) {
+    const origin = store.leaveArmMode(true);
+    if (!restoreArmOrigin(store, origin, plannerCount)) jumpToKanban(store, armedRef);
+    const t = store.getTask(armedRef);
+    store.flashBanner("info", t?.timeBlock ? `✓ ${fmtHm(t.timeBlock.startMin)}-${fmtHm(t.timeBlock.endMin)}` : "Arm mode off");
+    return;
+  }
+
   if (armed) {
     const NUDGE = 15; // minutes
     if (key.name === "j" || key.name === "down") {
@@ -443,24 +489,18 @@ function handleTimelineZone(
       store.flashBanner("info", `✋ ${fmtHm(newStart)}-${fmtHm(newEnd)}`);
       return;
     }
-    if (key.name === "+" || key.name === "=" || key.sequence === "+") {
+    if (isPlusKey(key) || key.name === "=") {
       const newEnd = Math.min(24 * 60 - 1, armed.endMin + NUDGE);
       store.setTimeBlock(armed.ref, { startMin: armed.startMin, endMin: newEnd });
       store.flashBanner("info", `↕ ${fmtHm(armed.startMin)}-${fmtHm(newEnd)}`);
       return;
     }
-    if (key.name === "-" || key.name === "_" || key.sequence === "-") {
+    if (isMinusKey(key) || key.name === "_") {
       const newEnd = Math.max(armed.startMin + 15, armed.endMin - NUDGE);
       store.setTimeBlock(armed.ref, { startMin: armed.startMin, endMin: newEnd });
       store.flashBanner("info", `↕ ${fmtHm(armed.startMin)}-${fmtHm(newEnd)}`);
       return;
     }
-    if (key.name === "enter" || key.name === "return") {
-      // Commit + jump to kanban + disarm.
-      store.armTimeline(undefined);
-      jumpToKanban(store, armed.ref);
-      return;
-    }
     // Fall through for other keys (Esc handled globally, task actions below).
   }
 
@@ -784,13 +824,12 @@ function dispatchTaskAction(
   // slot, repeat. `c` again or `Esc` exits. Works from any zone.
   if (key.name === "c" && !key.shift) {
     if (store.state.ui.armMode) {
-      store.setArmMode(false);
-      store.armTimeline(undefined);
+      // `c` again keeps what was placed, like Enter.
+      restoreArmOrigin(store, store.leaveArmMode(true));
       store.flashBanner("info", "Arm mode off");
       return true;
     }
-    store.setArmMode(true);
-    store.armTimeline(ref);
+    store.startArmMode(ref);
     store.setZoneVisible("timeline", true);
     store.setActiveZone("timeline");
     const t = store.getTask(ref);

package/src/input/keys.ts

@@ -0,0 +1,22 @@
+/**
+ * Keys that more than one handler cares about, recognised in one place so the
+ * handlers can't disagree about what "+" is.
+ *
+ * A `+` arrives in several shapes: the main-row key (name "+", or "=" with
+ * shift on US layouts), the keypad key (name "kpplus" under the kitty
+ * keyboard protocol, a plain "+" sequence elsewhere).
+ */
+
+export interface KeyLike {
+  name?: string;
+  sequence?: string;
+  shift?: boolean;
+}
+
+export function isPlusKey(key: KeyLike): boolean {
+  return key.name === "+" || key.name === "kpplus" || key.sequence === "+" || (key.name === "=" && !!key.shift);
+}
+
+export function isMinusKey(key: KeyLike): boolean {
+  return key.name === "-" || key.name === "kpminus" || key.sequence === "-";
+}

package/src/store/index.ts

@@ -18,7 +18,7 @@
  *   4. Schedule a debounced write to disk (writer + watcher self-mark).
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createMemo } from "solid-js";
@@ -76,6 +76,14 @@ export interface TaskRef {
   taskIndex: number;
 }
 
+function sameRef(a: TaskRef, b: TaskRef): boolean {
+  return a.boardPath === b.boardPath && a.columnIndex === b.columnIndex && a.taskIndex === b.taskIndex;
+}
+
+function sameBlock(a: TimeBlock | undefined, b: TimeBlock | undefined): boolean {
+  return a?.startMin === b?.startMin && a?.endMin === b?.endMin;
+}
+
 export interface LoadedBoard {
   board: Board;
   /** mtime in ms at the moment of the last successful read or write. */
@@ -98,6 +106,7 @@ export type ModalKind =
   | { kind: "confirm-delete-event" }
   | { kind: "search" }
   | { kind: "board-new" }
+  | { kind: "status-file" }
   | { kind: "help" };
 
 /**
@@ -133,6 +142,24 @@ export interface BoardNew {
 }
 
 /** What the detail view needs to show a task's note, or to explain its absence. */
+/** The configured status file, as the modal shows it. */
+export interface StatusFileView {
+  /** Path as configured, for the dialog subtitle. */
+  path: string;
+  body?: string;
+  /** Last write, ISO — undefined when the file isn't there. */
+  updatedAt?: string;
+  /** The configured path doesn't exist. */
+  missing?: string;
+  /** It exists but couldn't be read. */
+  error?: string;
+  /** Shown truncated: bigger than STATUS_FILE_MAX_BYTES. */
+  truncated?: boolean;
+}
+
+/** A status file is prose, not a database: past this it's shown cut. */
+export const STATUS_FILE_MAX_BYTES = 64 * 1024;
+
 export interface TaskNoteView {
   path?: string;
   body?: string;
@@ -177,6 +204,14 @@ export interface SelectedCalEvent {
 export type ActiveZone = "planner" | "board" | "timeline" | "agents";
 
 /** Fixed cycling order for Shift+Tab navigation. */
+/** Where `c` was pressed, so leaving arm mode can put the cursor back. */
+export interface ArmOrigin {
+  zone: ActiveZone;
+  boardIndex: number;
+  col: number;
+  row: number;
+}
+
 const ZONE_ORDER: readonly ActiveZone[] = ["planner", "board", "timeline", "agents"];
 
 export interface UIState {
@@ -246,6 +281,8 @@ export interface UIState {
    * `armedTimelineRef`, which is the single task currently armed.
    */
   armMode: boolean;
+  /** Set when `c` starts arm mode; `Enter`/`Esc` return here (#73). */
+  armOrigin?: ArmOrigin;
   /**
    * Which day the Agenda (timeline) zone is showing, as a signed offset from
    * today (0 = today, +1 = tomorrow, -1 = yesterday). Drives both the task
@@ -258,6 +295,10 @@ export interface UIState {
    * the upper bound (it knows the block count) and scrolls that block into view.
    */
   helpScroll: number;
+  /** Bumped when the status file changes on disk, so an open modal re-reads. */
+  statusFileRev: number;
+  /** Status-file modal scroll, in rows. The modal clamps the upper bound. */
+  statusScroll: number;
   view: ViewMode;
   /**
    * Tasks marked for bulk ops (`Space`). Key format:
@@ -359,6 +400,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
       armMode: false,
       agendaOffset: 0,
       helpScroll: 0,
+      statusFileRev: 0,
+      statusScroll: 0,
       view: "kanban",
       marked: {},
       filter: "all",
@@ -372,9 +415,12 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   // Last content tuiboard itself wrote per board path — used by the watcher's
   // self-write guard to ignore our own writes echoed back by the OS / sync.
   const lastWrittenContent = new Map<string, string>();
-  const watcher: BoardWatcher = createBoardWatcher(
-    initialBoards.map((b) => b.board.filepath),
-  );
+  const watcher: BoardWatcher = createBoardWatcher([
+    ...initialBoards.map((b) => b.board.filepath),
+    // Watched from the start, even when it doesn't exist yet: chokidar picks
+    // up a file created later as long as its directory exists (verified).
+    ...(config.statusFilePath ? [config.statusFilePath] : []),
+  ]);
 
   // Agents store has its own lifecycle (chokidar watcher on each agent CLI's
   // session dirs). Shared dispose() boundary below so SIGINT cleans both. When
@@ -389,6 +435,12 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     ? createCalendarStore(config.calendars, isoToday)
     : noopCalendarStore();
   watcher.onChange((filepath) => {
+    // The status file is not a board: nothing to parse, just tell an open
+    // modal to read it again.
+    if (config.statusFilePath && filepath === config.statusFilePath) {
+      setState("ui", "statusFileRev", (n: number) => n + 1);
+      return;
+    }
     // External edit. Re-read this board from disk.
     try {
       const content = readFileSync(filepath, "utf-8");
@@ -1308,14 +1360,58 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     setState("ui", "grabbing", false);
   }
 
+  /**
+   * The armed task as it was when it was armed, so `Esc` can put it back.
+   * Not UI state: nothing renders it, and it only means something while the
+   * same ref is still armed.
+   */
+  let armSnapshot: { ref: TaskRef; scheduled?: string; timeBlock?: TimeBlock } | undefined;
+
   function armTimeline(ref: TaskRef | undefined): void {
-    setState("ui", "armedTimelineRef", ref);
+    // A copy: handed an object, setState merges it into the one already
+    // stored, so arming a second task used to rewrite the first task's ref
+    // object in place — wherever a caller still held it.
+    const own = ref && { ...ref };
+    setState("ui", "armedTimelineRef", own);
+    const t = own && getTask(own);
+    armSnapshot =
+      own && t
+        ? { ref: own, scheduled: t.scheduled, timeBlock: t.timeBlock && { ...t.timeBlock } }
+        : undefined;
   }
 
   function setArmMode(on: boolean): void {
     setState("ui", "armMode", on);
   }
 
+  /** Start arm mode from the cursor, remembering where it started. */
+  function startArmMode(ref: TaskRef): void {
+    const ui = state.ui;
+    setState("ui", "armOrigin", { zone: ui.activeZone, boardIndex: ui.activeBoardIndex, col: ui.col, row: ui.row });
+    setArmMode(true);
+    armTimeline(ref);
+  }
+
+  /**
+   * Leave arm mode. `confirm` keeps whatever was placed; otherwise the armed
+   * task goes back to how it was when armed. Returns the origin to restore,
+   * if arm mode was started with `c`.
+   */
+  function leaveArmMode(confirm: boolean): ArmOrigin | undefined {
+    const ref = state.ui.armedTimelineRef;
+    const snap = armSnapshot;
+    if (!confirm && ref && snap && sameRef(ref, snap.ref)) {
+      const t = getTask(ref);
+      if (t && !sameBlock(t.timeBlock, snap.timeBlock)) setTimeBlock(ref, snap.timeBlock);
+      if (t && t.scheduled !== snap.scheduled) setScheduled(ref, snap.scheduled);
+    }
+    const origin = state.ui.armOrigin;
+    armTimeline(undefined);
+    setArmMode(false);
+    setState("ui", "armOrigin", undefined);
+    return origin;
+  }
+
   /** ISO date the Agenda is currently showing (today + offset). Reactive. */
   function agendaDate(): string {
     return isoAddDays(isoToday(), state.ui.agendaOffset);
@@ -1370,6 +1466,37 @@ export function createTuiStore({ config }: CreateStoreOptions) {
    * from, or why it could not be read. `undefined` means the task has no note —
    * which is most tasks, and must produce no message at all.
    */
+  /**
+   * The configured status file, read fresh. No parsing and no caching: it is
+   * read when the modal opens and again whenever the watcher says it changed,
+   * which is rare enough that a cache would only be a way to show stale text.
+   */
+  function statusFile(): StatusFileView | undefined {
+    const path = config.statusFilePath;
+    if (!path) return undefined;
+    let size: number;
+    let mtimeMs: number;
+    try {
+      const st = statSync(path);
+      size = st.size;
+      mtimeMs = st.mtimeMs;
+    } catch {
+      return { path, missing: path };
+    }
+    try {
+      const body = readNoteBody(path);
+      const truncated = size > STATUS_FILE_MAX_BYTES;
+      return {
+        path,
+        updatedAt: new Date(mtimeMs).toISOString(),
+        body: truncated ? body.slice(0, STATUS_FILE_MAX_BYTES) : body,
+        ...(truncated ? { truncated: true } : {}),
+      };
+    } catch (e) {
+      return { path, updatedAt: new Date(mtimeMs).toISOString(), error: (e as Error).message };
+    }
+  }
+
   function taskNote(ref: TaskRef): TaskNoteView | undefined {
     const task = getTask(ref);
     if (!task?.note) return undefined;
@@ -1541,6 +1668,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   function openModal(m: ModalKind): void {
     // Help always opens scrolled to the top.
     if (m.kind === "help") setState("ui", "helpScroll", 0);
+    if (m.kind === "status-file") setState("ui", "statusScroll", 0);
     setState("ui", "modal", m);
   }
 
@@ -1603,6 +1731,11 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   function setHelpScroll(n: number): void {
     setState("ui", "helpScroll", Math.max(0, n));
   }
+  /** Scroll the status file (rows, lower-clamped at 0; StatusFileModal writes
+   *  back the upper bound once it knows how tall the file renders). */
+  function setStatusScroll(n: number): void {
+    setState("ui", "statusScroll", Math.max(0, n));
+  }
 
   /** Move the step-2 calendar selection (wraps). */
   function setEventSel(n: number): void {
@@ -1753,6 +1886,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     moveTaskWithinBoard,
     // notes
     taskNote,
+    statusFile,
     // boards
     addBoard,
     openBoardNew,
@@ -1779,6 +1913,8 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     exitGrab,
     armTimeline,
     setArmMode,
+    startArmMode,
+    leaveArmMode,
     agendaDate,
     shiftAgendaDay,
     resetAgendaDay,
@@ -1798,6 +1934,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     openEventModal,
     advanceEventToStep2,
     setHelpScroll,
+    setStatusScroll,
     setEventSel,
     confirmEventPicker,
     selectCalEvent,

package/src/ui/Modal.tsx

@@ -22,9 +22,10 @@ import {
 import { ATTR, T, cellWidth } from "~/ui/glyphs";
 import { AGENDA_WIDTH } from "~/ui/layout";
 import { formatHm } from "~/store/timeline";
-import { HARNESS } from "~/store/agents";
+import { HARNESS, formatAge } from "~/store/agents";
 import { HARNESS_COLOR } from "~/ui/AgentRow";
 import { herdrPlace } from "~/store/herdr";
+import { markdownLines, type MdLine, type MdStyle } from "~/ui/markdown-lines";
 import type { TuiStore } from "~/store/index";
 import type { PriorityLevel, TimeBlock } from "~/types";
 
@@ -68,6 +69,7 @@ function ModalRouter(props: { store: TuiStore; modal: NonNullable<TuiStore["stat
     case "confirm-delete-event": return <ConfirmDeleteEventModal store={props.store} />;
     case "search":   return <SearchModal store={props.store} />;
     case "board-new": return <BoardNewModal store={props.store} />;
+    case "status-file": return <StatusFileModal store={props.store} />;
     case "help":     return <HelpModal store={props.store} />;
   }
 }
@@ -258,7 +260,7 @@ function DialogShell(props: DialogShellProps) {
     >
       {props.children}
       <Show when={props.hint}>
-        <text>
+        <text style={{ flexShrink: 0 }}>
           <span style={{ fg: T.textDim }}>{props.hint}</span>
         </text>
       </Show>
@@ -837,6 +839,145 @@ function DetailModal(props: { store: TuiStore; modal: Extract<NonNullable<TuiSto
   );
 }
 
+/**
+ * The configured status file (`status_file`), shown and nothing else: no
+ * writing, and no parsing beyond the light markdown rendering of
+ * markdown-lines.ts — markers become colour and weight, link targets go away.
+ * Same shape as a task's note — a dialog with a scrollable body — because
+ * from tuiboard's side it is the same object.
+ */
+/** "updated now" / "updated 5m ago" — same vocabulary the agents rows use. */
+function updatedLabel(iso: string): string {
+  const age = formatAge(Date.parse(iso), Date.now());
+  return age === "now" ? "updated just now" : `updated ${age} ago`;
+}
+
+const MD_SPAN: Record<MdStyle, { fg: string | undefined; attributes?: number }> = {
+  text:     { fg: T.text },
+  bold:     { fg: T.text, attributes: ATTR.bold },
+  italic:   { fg: T.text, attributes: ATTR.italic },
+  code:     { fg: T.tag },
+  link:     { fg: T.accent },
+  wikilink: { fg: T.accent },
+  dim:      { fg: T.textDim },
+};
+
+/** One markdown line as a word-wrapped row; blank lines keep their height. */
+function MarkdownLine(props: { line: MdLine }) {
+  const l = () => props.line;
+  const heading = () => l().kind === "heading";
+  const spanStyle = (style: MdStyle) =>
+    heading()
+      ? { fg: l().level! <= 2 ? T.accent : T.warm, attributes: ATTR.bold }
+      : l().kind === "quote" && style === "text"
+        ? MD_SPAN.dim
+        : MD_SPAN[style];
+  return (
+    <Show when={l().kind !== "blank"} fallback={<box style={{ height: 1 }} />}>
+      <Show
+        when={l().kind !== "rule"}
+        fallback={
+          <text wrapMode="none">
+            <span style={{ fg: T.textDim }}>{"─".repeat(40)}</span>
+          </text>
+        }
+      >
+        <text wrapMode="word">
+          <Show when={l().prefix}>
+            <span style={{ fg: T.textDim }}>{l().prefix}</span>
+          </Show>
+          <For each={l().spans}>
+            {(s) => <span style={spanStyle(s.style)}>{s.text}</span>}
+          </For>
+        </text>
+      </Show>
+    </Show>
+  );
+}
+
+/** The bits of OpenTUI's <scrollbox> the status file needs. */
+interface ScrollTopLike {
+  scrollTop: number;
+}
+
+function StatusFileModal(props: { store: TuiStore }) {
+  let scroller: ScrollTopLike | undefined;
+  // j/k drive `ui.statusScroll`; the scrollbox clamps it to what it can
+  // show, and the clamped value is written back so `k` answers at once after
+  // overshooting the end.
+  createEffect(() => {
+    const want = props.store.state.ui.statusScroll;
+    if (!scroller) return;
+    scroller.scrollTop = want;
+    if (scroller.scrollTop !== want) props.store.setStatusScroll(scroller.scrollTop);
+  });
+  const view = createMemo(() => {
+    props.store.state.ui.statusFileRev; // re-read when the file changes on disk
+    return props.store.statusFile();
+  });
+  return (
+    <Show
+      when={view()}
+      fallback={
+        <DialogShell title="Status file" hint="Esc to close" width={70}>
+          <text wrapMode="word">
+            <span style={{ fg: T.textDim }}>
+              No status file configured. Set `status_file:` in your config to the markdown
+              file you want to read here.
+            </span>
+          </text>
+        </DialogShell>
+      }
+    >
+      {(v: () => NonNullable<ReturnType<typeof view>>) => (
+        <DialogShell title="Status file" hint="j/k scroll · Esc/i to close" width={90}>
+          <text wrapMode="word">
+            <span style={{ fg: T.tag }}>{v().path}</span>
+            <Show when={v().updatedAt}>
+              <span style={{ fg: T.textDim }}>{"  " + updatedLabel(v().updatedAt!)}</span>
+            </Show>
+          </text>
+          <Show when={v().missing}>
+            <box style={{ height: 1 }} />
+            <text wrapMode="word">
+              <span style={{ fg: T.overdue }}>{"File not found: " + v().missing}</span>
+            </text>
+          </Show>
+          <Show when={v().error}>
+            <box style={{ height: 1 }} />
+            <text wrapMode="word">
+              <span style={{ fg: T.overdue }}>{"File unreadable: " + v().error}</span>
+            </text>
+          </Show>
+          <Show when={v().body !== undefined}>
+            <box style={{ height: 1 }} />
+            <scrollbox
+              ref={(r: ScrollTopLike) => (scroller = r)}
+              style={{ flexGrow: 1, flexShrink: 1, flexBasis: 0, minHeight: 0 }}
+            >
+              <Show
+                when={v().body !== ""}
+                fallback={
+                  <text wrapMode="word">
+                    <span style={{ fg: T.textDim }}>(the status file is empty)</span>
+                  </text>
+                }
+              >
+                <For each={markdownLines(v().body!)}>{(line) => <MarkdownLine line={line} />}</For>
+              </Show>
+            </scrollbox>
+            <Show when={v().truncated}>
+              <text wrapMode="word">
+                <span style={{ fg: T.textDim }}>… shown truncated (the file is large)</span>
+              </text>
+            </Show>
+          </Show>
+        </DialogShell>
+      )}
+    </Show>
+  );
+}
+
 // ─── Search ──────────────────────────────────────────────────────────────────
 
 function SearchModal(props: { store: TuiStore }) {
@@ -1125,13 +1266,13 @@ const HELP_SECTIONS: HelpSection[] = [
       ["n / click slot", "New Google Calendar event (needs: calendar-setup google --write) append date+time: Lunch tomorrow 12-13 · Review 2026-06-10 15-16 · Holiday 25-12 allday"],
       ["click an event", "Select an editable Google event — then e edit · d delete · Esc"],
       ["c (any zone)", "Toggle ARM MODE — then click a task, click a slot, repeat"],
-      ["click empty row", "Place the armed task here (30-min block, or move if it has one)"],
+      ["click empty row", "Place the armed task here (30-min block, or move if it has one) — it stays armed"],
       ["click band", "Arm an existing block (or place the armed task at its start)"],
       ["shift+click row", "While armed (existing block): resize end to that row"],
       ["j / k", "While armed: nudge block ±15 min"],
       ["+ / -", "While armed: resize block end ±15 min"],
-      ["Enter", "While armed: commit + jump to source task"],
-      ["Esc", "Disarm / exit arm mode"],
+      ["Enter", "While armed: keep it, exit arm mode, back to where c was pressed"],
+      ["Esc", "While armed: undo the placement, exit arm mode, back to where c was pressed"],
     ],
   },
   {
@@ -1173,6 +1314,7 @@ const HELP_SECTIONS: HelpSection[] = [
     title: "Global",
     rows: [
       ["Ctrl-Z", "Undo last mutation"],
+      ["i", "Status file (the markdown file set as `status_file`)"],
       ["?", "This help"],
       ["q · Ctrl-C", "Quit"],
     ],

package/src/ui/TaskRow.tsx

@@ -14,6 +14,12 @@ import { Show, createMemo } from "solid-js";
 
 import { PRIORITY_COLOR, PRIORITY_GLYPH, T, cellWidth, fmtMin } from "~/ui/glyphs";
 import { isoToday, isoTomorrow } from "~/store/index";
+import {
+  statusOf,
+  suffixColorFor,
+  titleColorFor,
+  type TaskStatus,
+} from "~/ui/task-status";
 import type { Task } from "~/types";
 
 interface TaskRowProps {
@@ -149,40 +155,6 @@ export function TaskRow(props: TaskRowProps) {
   );
 }
 
-type TaskStatus =
-  | "done"
-  | "overdue"
-  | "today"
-  | "tomorrow"
-  | "future"
-  | "unscheduled";
-
-function statusOf(t: Task): TaskStatus {
-  if (t.done) return "done";
-  const d = t.scheduled ?? t.due;
-  if (!d) return "unscheduled";
-  if (d < isoToday()) return "overdue";
-  if (d === isoToday()) return "today";
-  if (d === isoTomorrow()) return "tomorrow";
-  return "future";
-}
-
-function titleColorFor(task: Task, status: TaskStatus): string | undefined {
-  // Precedence: done (green) > overdue (red) > priority (orange) > today
-  // (pale yellow) > tomorrow (grey) > default. The orange now *means*
-  // "priority flag" — only tasks with a priority get it; everything scheduled
-  // today is the calm pale yellow instead.
-  if (status === "done") return T.done;
-  if (status === "overdue") return T.overdue;
-  // Tomorrow is uniformly grey — even priority tasks — so everything set for
-  // tomorrow reads consistently as "later, de-emphasized".
-  if (status === "tomorrow") return T.textDim;
-  if (task.priority !== "none") return T.today;
-  if (status === "today") return T.todayPale;
-  // future / unscheduled: terminal default fg (looks right on any theme).
-  return T.text;
-}
-
 /**
  * Build the compact right-side suffix shown on a task row.
  *
@@ -211,16 +183,6 @@ function buildSuffix(task: Task, hideDate?: boolean): string | undefined {
   return parts.join(" ");
 }
 
-function suffixColorFor(task: Task, status: TaskStatus): string | undefined {
-  if (status === "done") return T.textDone;
-  if (status === "overdue") return T.overdue;
-  if (status === "today") return T.todayPale;
-  if (status === "tomorrow") return T.textDim;
-  if (status === "future") return T.scheduled;
-  return T.textDim;
-  void task;
-}
-
 /**
  * Truncate to `max` chars, preserving as much of the head as possible.
  * When the string fits, return it untouched. Otherwise show the first

package/src/ui/TimelineView.tsx

@@ -20,7 +20,8 @@
  *   Enter                → bounce kanban cursor to the underlying task
  *   j/k while armed      → nudge armed block ±15 min (move)
  *   +/- while armed      → resize armed block end ±15 min
- *   Esc                  → disarm
+ *   Enter while armed    → keep, leave arm mode, back to where `c` started
+ *   Esc while armed      → undo the placement, then the same way back
  *
  * Each timeline row is exactly 1 terminal line tall, so row index maps
  * 1:1 to MINS_PER_ROW (15) minute offsets from DAY_START_HOUR.
@@ -258,7 +259,7 @@ export function TimelineView(props: TimelineViewProps) {
       props.store.armTimeline(entry.ref);
       props.store.flashBanner(
         "info",
-        `Armed ⌚${formatHm(entry.startMin)}-${formatHm(entry.endMin)} · click empty row to move, shift+click to resize, Esc to cancel`,
+        `Armed ⌚${formatHm(entry.startMin)}-${formatHm(entry.endMin)} · click a row to move, shift+click to resize · Enter done · Esc cancel`,
       );
     }
   };
@@ -298,11 +299,10 @@ export function TimelineView(props: TimelineViewProps) {
       props.store.setTimeBlock(ref, { startMin, endMin });
       props.store.flashBanner(
         "info",
-        `⌚ Scheduled → ${formatHm(startMin)}-${formatHm(endMin)}`,
+        `⌚ ${formatHm(startMin)}-${formatHm(endMin)} · +/- length · j/k move · Enter done · Esc cancel`,
       );
-      // Auto-disarm: the task now has a block and will appear as a band;
-      // the user can re-click on that band to keep adjusting.
-      props.store.armTimeline(undefined);
+      // Stays armed (#73): the default length is rarely the right one, so
+      // +/- and j/k apply straight away, without re-clicking the band.
       return;
     }
 
@@ -361,7 +361,7 @@ export function TimelineView(props: TimelineViewProps) {
             {"◉ ARM MODE "}
           </span>
           <span style={{ fg: T.textDim }}>
-            {"click a task → click a slot · Esc to exit"}
+            {"click a task → click a slot · Enter done · Esc cancel"}
           </span>
         </text>
       </Show>
@@ -376,7 +376,7 @@ export function TimelineView(props: TimelineViewProps) {
           <span style={{ fg: T.textDim }}>
             {armedIsUnscheduled()
               ? "  click row to place · Esc to cancel"
-              : "  click row to move · shift+click to resize · Esc"}
+              : "  +/- length · j/k move · Enter done · Esc cancel"}
           </span>
         </text>
       </Show>

package/src/ui/glyphs.ts

@@ -74,6 +74,9 @@ export const T = {
 
   // Status-based row colors — kept clearly distinct in hue + brightness
   overdue: "#e26a6a",        // hue 0°, sat 65%, light 65% — clearly red
+  // Same hue, turned up: a task that has been late for days reads louder than
+  // one that slipped yesterday, without introducing a second meaning.
+  overdueHeavy: "#ff5555",   // hue 0°, sat 100%, light 67%
   today: "#e8a05c",          // warm orange — now the PRIORITY accent (flagged tasks)
   // Today/Tomorrow identity + today-scheduled task titles: a soft pale yellow.
   todayPale: "#eaf6ad",      // bright, calm — the Today/Tomorrow zone accent

package/src/ui/markdown-lines.ts

@@ -0,0 +1,110 @@
+/**
+ * Just enough markdown for reading a note in a dialog: the file is shown, not
+ * edited, so the markers that only matter to an editor go away (`**`, `#`,
+ * link targets, `[[ ]]`) and what they meant becomes colour and weight.
+ *
+ * Deliberately line-based and forgiving — anything it doesn't recognise is
+ * printed as written, never dropped. Pure so the rules can be tested without
+ * a renderer.
+ */
+
+export type MdStyle = "text" | "bold" | "italic" | "code" | "link" | "wikilink" | "dim";
+
+export interface MdSpan {
+  text: string;
+  style: MdStyle;
+}
+
+export type MdLineKind = "heading" | "text" | "quote" | "code" | "rule" | "blank";
+
+export interface MdLine {
+  kind: MdLineKind;
+  /** Heading depth (1–6); only set on headings. */
+  level?: number;
+  /** Leading glyph + indent for list items and quotes, e.g. "  • ". */
+  prefix?: string;
+  spans: MdSpan[];
+}
+
+// Order matters: code first (its content is literal), then links, then emphasis.
+const INLINE =
+  /(`[^`]+`)|(\[\[[^\]]+\]\])|(\[[^\]]+\]\([^)\s]+\))|(\*\*[^*]+\*\*|__[^_]+__)|(\*[^*\s][^*]*\*|(?<![\w])_[^_\s][^_]*_(?![\w]))/g;
+
+export function parseInline(src: string): MdSpan[] {
+  const out: MdSpan[] = [];
+  let last = 0;
+  const push = (text: string, style: MdStyle) => {
+    if (!text) return;
+    const prev = out[out.length - 1];
+    if (prev && prev.style === style) prev.text += text;
+    else out.push({ text, style });
+  };
+  for (const m of src.matchAll(INLINE)) {
+    push(src.slice(last, m.index), "text");
+    const [tok, code, wiki, link, bold] = m;
+    if (code) push(tok.slice(1, -1), "code");
+    else if (wiki) {
+      const inner = tok.slice(2, -2);
+      const bar = inner.indexOf("|");
+      push(bar >= 0 ? inner.slice(bar + 1) : inner.replace(/#.*$/, ""), "wikilink");
+    } else if (link) push(tok.slice(1, tok.indexOf("](")), "link");
+    else if (bold) {
+      // Links inside bold keep their own colour; the rest is bold.
+      for (const s of parseInline(tok.slice(2, -2))) push(s.text, s.style === "text" ? "bold" : s.style);
+    } else push(tok.slice(1, -1), "italic");
+    last = m.index! + tok.length;
+  }
+  push(src.slice(last), "text");
+  return out;
+}
+
+export function markdownLines(body: string): MdLine[] {
+  const lines: MdLine[] = [];
+  let fence: string | undefined;
+  let inFrontmatter = false;
+  const src = body.replace(/\r\n?/g, "\n").split("\n");
+
+  src.forEach((raw, i) => {
+    // YAML frontmatter is metadata for the editor, not something to read.
+    if (i === 0 && raw.trim() === "---") return void (inFrontmatter = true);
+    if (inFrontmatter) {
+      if (raw.trim() === "---") inFrontmatter = false;
+      return;
+    }
+
+    const fenceMatch = raw.match(/^\s*(```|~~~)/);
+    if (fenceMatch) {
+      fence = fence ? undefined : fenceMatch[1];
+      return;
+    }
+    if (fence) return void lines.push({ kind: "code", spans: [{ text: raw, style: "code" }] });
+
+    if (raw.trim() === "") return void lines.push({ kind: "blank", spans: [] });
+
+    const heading = raw.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (heading) {
+      return void lines.push({ kind: "heading", level: heading[1]!.length, spans: parseInline(heading[2]!) });
+    }
+
+    if (/^\s*([-*_])(\s*\1){2,}\s*$/.test(raw)) return void lines.push({ kind: "rule", spans: [] });
+
+    const quote = raw.match(/^\s*>\s?(.*)$/);
+    if (quote) return void lines.push({ kind: "quote", prefix: "│ ", spans: parseInline(quote[1]!) });
+
+    const item = raw.match(/^(\s*)([-*+]|\d+[.)])\s+(?:\[( |x|X)\]\s+)?(.*)$/);
+    if (item) {
+      const indent = " ".repeat(Math.floor(item[1]!.replace(/\t/g, "  ").length / 2) * 2);
+      const box = item[3];
+      const glyph = box === undefined ? (/\d/.test(item[2]!) ? item[2]! : "•") : box === " " ? "○" : "✓";
+      return void lines.push({ kind: "text", prefix: `${indent}${glyph} `, spans: parseInline(item[4]!) });
+    }
+
+    lines.push({ kind: "text", spans: parseInline(raw.trim()) });
+  });
+
+  // Collapse runs of blank lines, and trim them at both ends.
+  const out = lines.filter((l, i, all) => l.kind !== "blank" || all[i - 1]?.kind !== "blank");
+  while (out[0]?.kind === "blank") out.shift();
+  while (out[out.length - 1]?.kind === "blank") out.pop();
+  return out;
+}

package/src/ui/task-status.ts

@@ -0,0 +1,100 @@
+/**
+ * What a task *is* right now (done, overdue, today…) and what color says so.
+ *
+ * Pulled out of TaskRow.tsx so the rules can be tested directly: they encode
+ * every precedence decision the board and planner rows rely on, and a
+ * component is an awkward place to assert them from.
+ */
+
+import { isoToday, isoTomorrow } from "~/store/index";
+import { T } from "~/ui/glyphs";
+import type { Task } from "~/types";
+
+export type TaskStatus =
+  | "done"
+  | "overdue"
+  | "today"
+  | "tomorrow"
+  | "future"
+  | "unscheduled";
+
+/**
+ * Calendar days from `from` to `to` (both `YYYY-MM-DD`). UTC arithmetic, so
+ * a DST change can't turn a day into 23 or 25 hours and round the wrong way.
+ */
+export function daysBetweenIso(from: string, to: string): number {
+  const ms = (iso: string) => {
+    const [y, m, d] = iso.split("-").map(Number);
+    return Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1);
+  };
+  return Math.round((ms(to) - ms(from)) / 86_400_000);
+}
+
+/**
+ * How late is late. Nazz resets most tasks to Today each morning, so being a
+ * day or two past is ordinary drift — a Friday task looked at again on Monday
+ * is already 3 days old without anyone ignoring it. Five days means the task
+ * has survived a weekend *and* working days of deliberate skipping, which is
+ * the thing worth seeing from across the board.
+ *
+ * Measured against the real boards when this landed (117 open tasks, 13
+ * overdue): 3 days would have painted 8 of the 13 — the whole weekend —
+ * while the spec's placeholder of 7 would have painted none.
+ */
+export const OVERDUE_HEAVY_AFTER_DAYS = 5;
+
+/** Two bands, not a gradient: "a little" vs "a lot". */
+export function overdueBand(scheduled: string, today: string): "light" | "heavy" {
+  return daysBetweenIso(scheduled, today) >= OVERDUE_HEAVY_AFTER_DAYS ? "heavy" : "light";
+}
+
+export function statusOf(t: Task, today = isoToday(), tomorrow = isoTomorrow()): TaskStatus {
+  if (t.done) return "done";
+  const d = t.scheduled ?? t.due;
+  if (!d) return "unscheduled";
+  if (d < today) return "overdue";
+  if (d === today) return "today";
+  if (d === tomorrow) return "tomorrow";
+  return "future";
+}
+
+/** The overdue color for this task: louder once it's been late a while. */
+function overdueColor(task: Task, today: string): string {
+  const d = task.scheduled ?? task.due;
+  return d && overdueBand(d, today) === "heavy" ? T.overdueHeavy : T.overdue;
+}
+
+export function titleColorFor(
+  task: Task,
+  status: TaskStatus,
+  today = isoToday(),
+): string | undefined {
+  // Precedence: done (green) > overdue (red) > priority (orange) > today
+  // (pale yellow) > tomorrow (grey) > default. The orange now *means*
+  // "priority flag" — only tasks with a priority get it; everything scheduled
+  // today is the calm pale yellow instead.
+  if (status === "done") return T.done;
+  if (status === "overdue") return overdueColor(task, today);
+  // Tomorrow is uniformly grey — even priority tasks — so everything set for
+  // tomorrow reads consistently as "later, de-emphasized".
+  if (status === "tomorrow") return T.textDim;
+  if (task.priority !== "none") return T.today;
+  if (status === "today") return T.todayPale;
+  // future / unscheduled: terminal default fg (looks right on any theme).
+  return T.text;
+}
+
+export function suffixColorFor(
+  task: Task,
+  status: TaskStatus,
+  today = isoToday(),
+): string | undefined {
+  if (status === "done") return T.textDone;
+  // The date suffix carries the same band as the title, so a row doesn't read
+  // as two different degrees of late at once.
+  if (status === "overdue") return overdueColor(task, today);
+  if (status === "today") return T.todayPale;
+  if (status === "tomorrow") return T.textDim;
+  if (status === "future") return T.scheduled;
+  return T.textDim;
+}