tuiboard 0.8.3 → 0.8.5

package/.tuiboard/config.example.yaml

@@ -62,6 +62,15 @@ archive_column: Archive
 #   - "{cwd}"
 #   - "{sessionId}"
 
+# Optional: the command copied to your clipboard by `c` in the Agents zone — one
+# paste that cd's into the session's directory and resumes it, for when you want
+# to open the session yourself in a new tab/pane anywhere (no WezTerm needed).
+# The tokens {cwd} and {sessionId} are substituted. It's a plain string, so use
+# whatever chaining your shell wants. Default (works in bash/zsh/pwsh/cmd):
+#   copy_resume_command: 'cd "{cwd}" && claude --resume {sessionId}'
+# Nushell users typically want `;` instead of `&&`:
+# copy_resume_command: 'cd "{cwd}"; claude --resume {sessionId}'
+
 # 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

@@ -5,6 +5,61 @@ All notable changes to **tuiboard** are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.8.5] - 2026-08-31
+
+### Added
+- **`tuiboard summary` — JSON snapshot for status bars and scripts.** Totals, a
+  per-board breakdown, and `planner`: the same Today / Tomorrow / Overdue
+  aggregation the planner zone renders, built from `buildPlannerItems()` so a
+  bar widget and the dashboard can never disagree about what is due. `--pretty`
+  to read it, `--next N` to size (or drop) the per-board upcoming list.
+- **`tuiboard task` — headless mutations.** `done`, `undone`, `defer` and `add`
+  against a board file, matched **by title rather than index** so a task that
+  moved is a miss instead of the wrong task. `--dry-run` reports without
+  writing; an ambiguous title is refused rather than guessed at; exit 3 means
+  the board changed on disk since it was read.
+- **`undone` reopens a completed task**, dropping its `✅` date with the tick —
+  the exact inverse of `done`, and the same semantics as the TUI's Enter.
+- **`defer` moves the date the planner actually reads** (`scheduled`, else
+  `due`, else adds a `scheduled`), so the row really moves. Defaults to
+  tomorrow; `--days N` or `--to YYYY-MM-DD` for anything else, `--days 0` to
+  pull a task back to today.
+- **Planner entries in `summary` now report `done` and `doneDate`.** Today and
+  Tomorrow keep completed tasks — a day's plan is a record of the day — so
+  without this a consumer had no way to tell a ticked task from an open one.
+
+### Fixed
+- **Node's warnings no longer scribble on the dashboard.** OpenTUI registers one
+  `selection` listener per `<scrollbox>`, and a full dashboard keeps more than
+  ten alive (one per board column, plus planner, timeline and agents), tripping
+  Node's default `MaxListeners` cap of 10 — usually when `Tab` mounted a new
+  board's columns. The warning went to stderr, which is the alternate screen the
+  renderer believes it owns: two lines scrolled the buffer and every repaint
+  after that landed rows off, so the layout appeared to break on a keypress. The
+  cap is now sized for the real number of zones, and any remaining warning is
+  filed in `~/.cache/tuiboard/warnings.log` instead of on the screen.
+
+## [0.8.4] - 2026-07-31
+
+### Added
+- **Copy a session's resume command (`c` in the Agents zone).** Select a Claude
+  Code session and press `c` to copy a one-paste command that `cd`s into its
+  directory and resumes it — `cd "<cwd>" && claude --resume <id>` by default — so
+  you can drop it into any tab or pane, on any machine layout, without depending
+  on WezTerm (which `Enter` requires). The format is configurable via
+  `copy_resume_command` (tokens `{cwd}` / `{sessionId}`); Nushell users can swap
+  `&&` for `;`. The session detail view (`o`) now shows this exact command.
+
+### Fixed
+- **Modals now appear in zoom mode.** Opening a modal (new task, schedule, time
+  block, assign, edit, delete, search, new event…) while a zone was zoomed (`z`)
+  set the modal state but rendered nothing — the zoomed layout had no Agenda slot
+  to host it, so the dialog was invisible and you typed blind. The modal now
+  floats as a centered overlay on top of the zoomed view; closing it returns you
+  to the zoomed view exactly as you left it.
+
 ## [0.8.3] - 2026-06-04
 
 ### Added
@@ -174,6 +229,8 @@ First public release on npm. This entry captures the full feature set at launch.
 
 Built with [OpenTUI](https://opentui.com) + SolidJS on Bun.
 
+[0.8.5]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.5
+[0.8.4]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.4
 [0.8.3]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.3
 [0.8.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.2
 [0.8.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.8.1

package/README.md

@@ -147,6 +147,12 @@ archive_column: Archive
 # path, NOT a shell builtin or Windows App Execution Alias). Defaults to
 # opening a WezTerm tab with `claude --resume <id>`. For a custom layout:
 # resume_command: ["nu", "C:/Users/you/.config/tuiboard/code-resume.nu", "{cwd}", "{sessionId}"]
+
+# Optional: the command `c` copies to the clipboard in the Agents zone — one
+# paste that cd's into the session dir and resumes it, so you can open it
+# yourself in any tab/pane (no WezTerm needed). {cwd}/{sessionId} substituted.
+# Default: 'cd "{cwd}" && claude --resume {sessionId}'. Nushell users:
+# copy_resume_command: 'cd "{cwd}"; claude --resume {sessionId}'
 ```
 
 ## Zones
@@ -397,6 +403,15 @@ session (until the next terminal resize).
 | `j` / `k` | While armed: nudge the block ±15 min |
 | `+` / `-` | While armed: resize the block's end ±15 min |
 
+### Agents (agents zone)
+
+| Key | Action |
+|---|---|
+| `j` / `k` | Move the cursor down / up the session list |
+| `Enter` | Open (resume) the selected session in a new WezTerm tab |
+| `c` | Copy a one-paste `cd … && claude --resume <id>` command for the selected session — drop it into any tab/pane to land in the right dir and resume (no WezTerm needed; format is `copy_resume_command`) |
+| `o` | Session detail (cwd, branch, last prompts, resume command) |
+
 ### Task actions (work in board, planner, AND timeline zones)
 
 | Key | Action |
@@ -433,6 +448,56 @@ session (until the next terminal resize).
 | `?` | Help modal with the full reference |
 | `q` · `Ctrl-C` | Quit |
 
+## Headless commands
+
+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.
+
+### `tuiboard summary` — JSON snapshot
+
+```bash
+tuiboard summary                # compact JSON on stdout
+tuiboard summary --pretty       # indented, for reading
+tuiboard summary --next 8       # upcoming tasks per board (default 5, 0 = none)
+```
+
+Returns totals, a per-board breakdown, and `planner` — the same Today /
+Tomorrow / Overdue aggregation the planner zone renders, each entry carrying
+its title, board, column, bucket, priority, dates, time block, assignee, and
+whether it is already `done` (with `doneDate`). Today and Tomorrow keep
+completed tasks, as the panel does: a day's plan is a record of the day, not
+only of what is left.
+
+### `tuiboard task` — mutations
+
+```bash
+tuiboard task done   --board Personal --column Home --match "Bollette"
+tuiboard task undone --board Personal --column Home --match "Bollette"
+tuiboard task defer  --board Personal --column Home --match "Bollette" [--days N | --to YYYY-MM-DD]
+tuiboard task add    --board Personal --column Home --text "Nuova task 🔺 ⏳ 2026-09-01"
+```
+
+`--dry-run` reports what would change and writes nothing. `defer` defaults to
+one day and moves the date the planner actually reads (`scheduled`, else
+`due`, else adds a `scheduled`), so the row really moves; `--days 0` pulls a
+task back to today.
+
+Tasks are matched **by title, not by index**: a position is only valid inside
+one render pass, and a widget polling every couple of minutes holds a stale
+snapshot — matching on text makes a moved task a miss rather than a mistake.
+An ambiguous match is refused rather than guessed at.
+
+| Exit | Meaning |
+|---|---|
+| `0` | Done (including "already done" / "already open" — both are no-ops) |
+| `1` | No match, ambiguous match, or unknown board/column |
+| `2` | Bad arguments |
+| `3` | The board changed on disk since it was read — refresh and retry |
+
+Exit 3 is the mtime watermark: a write is refused rather than allowed to
+clobber an edit made in the TUI or another editor in the meantime.
+
 ## Status
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
@@ -451,6 +516,15 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history.
   responsive layout. Tested on Windows with WezTerm; Linux/macOS should
   work via the same OpenTUI binaries (untested).
 
+## Contributing
+
+Contributions are welcome — bugs, docs, fixes, features, or just trying it on a
+platform I haven't tested. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the
+project layout, and the checks to run, and the [good first issues][gfi] for a
+place to start.
+
+[gfi]: https://github.com/NazzarenoGiannelli/tuiboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/bin/tuiboard.ts

@@ -29,6 +29,14 @@ if (process.argv[2] === "calendar-setup") {
   const { runCalendarSetup } = await import("../src/calendar/setup.ts");
   process.exit(await runCalendarSetup(process.argv.slice(3)));
 }
+if (process.argv[2] === "summary") {
+  const { runSummary } = await import("../src/cli/summary.ts");
+  process.exit(await runSummary(process.argv.slice(3)));
+}
+if (process.argv[2] === "task") {
+  const { runTask } = await import("../src/cli/task.ts");
+  process.exit(await runTask(process.argv.slice(3)));
+}
 const preload = fileURLToPath(import.meta.resolve("@opentui/solid/preload"));
 
 // Paint the splash from the (already-running) launcher and animate its booting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Terminal kanban for markdown task boards, with optional Today/Tomorrow planner, 24h agenda + calendar overlay, and a live Claude Code agent view. Use only the panels you want.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "tb": "./bin/tuiboard.ts"
   },
   "files": [
+    "tsconfig.json",
     "src/",
     "bin/",
     ".tuiboard/config.example.yaml",
@@ -47,6 +48,7 @@
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "agents:check": "bun run src/scripts/agents-check.ts",
+    "summary": "bun run src/cli/summary.ts",
     "prepublishOnly": "bun run typecheck && bun test"
   },
   "dependencies": {

package/src/app.tsx

@@ -16,6 +16,11 @@
 // (OpenTUI) and the ~600ms store build below run. See ui/splash-boot.ts.
 import "~/ui/splash-boot";
 
+import { EventEmitter } from "node:events";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import { createMemo } from "solid-js";
 import { render, useKeyboard } from "@opentui/solid";
 
@@ -35,6 +40,35 @@ import { Dashboard } from "~/views/Dashboard";
 import { TimelineOnly } from "~/views/TimelineOnly";
 import { AgentsOnly } from "~/views/AgentsOnly";
 
+// ─── Keep Node's own output off the screen ──────────────────────────────────
+//
+// OpenTUI registers one "selection" listener on the renderer per <scrollbox>,
+// and a dashboard keeps more than ten alive at once: one per board column,
+// plus planner, timeline and agents. That is a legitimate count, not a leak,
+// but it trips Node's default MaxListeners cap of 10 — and switching board
+// with Tab crosses the threshold as the new columns mount.
+EventEmitter.defaultMaxListeners = 64;
+
+// Whatever still warns must never reach the terminal. Node writes warnings to
+// stderr, which here means straight onto the alternate screen the renderer
+// believes it owns: the two extra lines scroll the buffer, and from then on
+// every absolutely-positioned repaint lands a couple of rows off — the layout
+// appears to "break" on the next keypress. Removing the default handler stops
+// Node printing them; ours files them where they can still be read.
+process.removeAllListeners("warning");
+process.on("warning", (w: Error) => {
+  try {
+    const dir = join(homedir(), ".cache", "tuiboard");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      join(dir, "warnings.log"),
+      `${new Date().toISOString()} ${w.name}: ${w.message}\n${w.stack ?? ""}\n`,
+    );
+  } catch {
+    // A log we cannot write is not worth losing the screen over.
+  }
+});
+
 // ─── Bootstrap ──────────────────────────────────────────────────────────────
 
 const config = loadConfig();

package/src/cli/headless.test.ts

@@ -0,0 +1,202 @@
+/**
+ * The headless CLI — `tuiboard task` and `tuiboard summary`.
+ *
+ * These are the only commands that write to the user's real board files from
+ * outside the TUI (a bar widget, a cron job), so they are tested against a
+ * real board on disk rather than a parsed fixture: the round trip through
+ * parse → mutate → serialize → write is exactly what can lose data.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { ConflictError, statMtime, writeBoardFile } from "~/io/writer";
+import { buildSummary } from "./summary";
+import { runTask } from "./task";
+
+const BOARD = `---
+
+kanban-plugin: board
+
+---
+
+## Home
+- [ ] Bollette ⏳ 2026-08-31
+- [x] Spesa ⏳ 2026-08-31 ✅ 2026-08-31
+- [ ] Chiamare idraulico 📅 2026-08-31
+- [ ] Cambiare gomme
+- [ ] Ambiguo uno
+- [ ] Ambiguo due
+`;
+
+let dir: string;
+let boardPath: string;
+let configPath: string;
+let previousConfig: string | undefined;
+
+/** Days from today as YYYY-MM-DD, in local time — matches the CLI's own clock. */
+function iso(offsetDays: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() + offsetDays);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function board(): string {
+  return readFileSync(boardPath, "utf-8");
+}
+
+function line(title: string): string {
+  const hit = board()
+    .split("\n")
+    .find((l) => l.includes(title));
+  if (!hit) throw new Error(`no line matching "${title}" in board`);
+  return hit;
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "tuiboard-cli-"));
+  boardPath = join(dir, "Board.md");
+  configPath = join(dir, "config.yaml");
+  writeFileSync(boardPath, BOARD, "utf-8");
+  writeFileSync(configPath, `boards:\n  - path: ${boardPath}\n    name: Test\n`, "utf-8");
+  previousConfig = process.env.TUIBOARD_CONFIG;
+  process.env.TUIBOARD_CONFIG = configPath;
+});
+
+afterEach(() => {
+  if (previousConfig === undefined) delete process.env.TUIBOARD_CONFIG;
+  else process.env.TUIBOARD_CONFIG = previousConfig;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+const args = (...rest: string[]) => ["--board", "Test", "--column", "Home", ...rest];
+
+describe("tuiboard task done", () => {
+  it("ticks the task and stamps today's completion date", async () => {
+    expect(await runTask(["done", ...args("--match", "Bollette")])).toBe(0);
+    expect(line("Bollette")).toBe(`- [x] Bollette ⏳ 2026-08-31 ✅ ${iso(0)}`);
+  });
+
+  it("leaves an already-done task untouched", async () => {
+    const before = line("Spesa");
+    expect(await runTask(["done", ...args("--match", "Spesa")])).toBe(0);
+    expect(line("Spesa")).toBe(before);
+  });
+});
+
+describe("tuiboard task undone", () => {
+  it("reopens a completed task and drops the completion date with it", async () => {
+    expect(await runTask(["undone", ...args("--match", "Spesa")])).toBe(0);
+    expect(line("Spesa")).toBe("- [ ] Spesa ⏳ 2026-08-31");
+  });
+
+  it("is the exact inverse of done — round trip restores the line", async () => {
+    const before = line("Bollette");
+    expect(await runTask(["done", ...args("--match", "Bollette")])).toBe(0);
+    expect(await runTask(["undone", ...args("--match", "Bollette")])).toBe(0);
+    expect(line("Bollette")).toBe(before);
+  });
+
+  it("leaves an already-open task untouched", async () => {
+    const before = line("Bollette");
+    expect(await runTask(["undone", ...args("--match", "Bollette")])).toBe(0);
+    expect(line("Bollette")).toBe(before);
+  });
+});
+
+describe("tuiboard task defer", () => {
+  it("moves `scheduled` when the task has one", async () => {
+    expect(await runTask(["defer", ...args("--match", "Bollette")])).toBe(0);
+    expect(line("Bollette")).toBe(`- [ ] Bollette ⏳ ${iso(1)}`);
+  });
+
+  it("moves `due` when that is the only date — the field the planner reads", async () => {
+    expect(await runTask(["defer", ...args("--match", "idraulico")])).toBe(0);
+    expect(line("idraulico")).toBe(`- [ ] Chiamare idraulico 📅 ${iso(1)}`);
+  });
+
+  it("schedules an undated task, which is what puts it on the agenda", async () => {
+    expect(await runTask(["defer", ...args("--match", "gomme")])).toBe(0);
+    expect(line("gomme")).toBe(`- [ ] Cambiare gomme ⏳ ${iso(1)}`);
+  });
+
+  it("--days 0 pulls a task back to today", async () => {
+    expect(await runTask(["defer", ...args("--match", "Bollette", "--days", "0")])).toBe(0);
+    expect(line("Bollette")).toBe(`- [ ] Bollette ⏳ ${iso(0)}`);
+  });
+
+  it("--to takes an explicit date", async () => {
+    expect(await runTask(["defer", ...args("--match", "Bollette", "--to", "2027-01-15")])).toBe(0);
+    expect(line("Bollette")).toBe("- [ ] Bollette ⏳ 2027-01-15");
+  });
+
+  it("rejects a malformed --to without touching the board", async () => {
+    const before = board();
+    expect(await runTask(["defer", ...args("--match", "Bollette", "--to", "15/01/2027")])).toBe(2);
+    expect(board()).toBe(before);
+  });
+});
+
+describe("tuiboard task — refusing to guess", () => {
+  it("writes nothing when the match is ambiguous", async () => {
+    const before = board();
+    expect(await runTask(["done", ...args("--match", "Ambiguo")])).toBe(1);
+    expect(board()).toBe(before);
+  });
+
+  it("writes nothing when nothing matches", async () => {
+    const before = board();
+    expect(await runTask(["done", ...args("--match", "inesistente")])).toBe(1);
+    expect(board()).toBe(before);
+  });
+
+  it("--dry-run reports success and leaves the file alone", async () => {
+    const before = board();
+    expect(await runTask(["done", ...args("--match", "Bollette", "--dry-run")])).toBe(0);
+    expect(board()).toBe(before);
+  });
+
+  it("refuses the write when the board moved on since it was read", () => {
+    // What `runTask` maps to exit 3. Driven through the writer directly: the
+    // race it guards against — the file changing between the read and the
+    // write — cannot be staged from outside the function that spans it.
+    const stale = statMtime(boardPath);
+    const past = new Date(Date.now() - 60_000);
+    utimesSync(boardPath, past, past);
+    const before = board();
+    expect(() => writeBoardFile(boardPath, "clobbered", { expectedMtimeMs: stale }))
+      .toThrow(ConflictError);
+    expect(board()).toBe(before);
+  });
+});
+
+describe("tuiboard summary — planner entries", () => {
+  it("reports whether a Today entry is already ticked", async () => {
+    // The board's dates are fixed, so the summary is asked for that same day.
+    const s = buildSummary({ next: 0, today: "2026-08-31" });
+    const today = s.planner.today;
+    const bollette = today.find((e) => e.title === "Bollette");
+    const spesa = today.find((e) => e.title === "Spesa");
+
+    expect(bollette?.done).toBe(false);
+    expect(bollette?.doneDate).toBeUndefined();
+    expect(spesa?.done).toBe(true);
+    expect(spesa?.doneDate).toBe("2026-08-31");
+  });
+
+  it("follows a task through done and back", async () => {
+    await runTask(["done", ...args("--match", "Bollette")]);
+    const done = buildSummary({ next: 0, today: "2026-08-31" })
+      .planner.today.find((e) => e.title === "Bollette");
+    expect(done?.done).toBe(true);
+
+    await runTask(["undone", ...args("--match", "Bollette")]);
+    const reopened = buildSummary({ next: 0, today: "2026-08-31" })
+      .planner.today.find((e) => e.title === "Bollette");
+    expect(reopened?.done).toBe(false);
+    expect(reopened?.doneDate).toBeUndefined();
+  });
+});

package/src/cli/summary.ts

@@ -0,0 +1,284 @@
+/**
+ * Headless JSON snapshot of the configured boards.
+ *
+ * Usage:
+ *   tuiboard summary              # compact JSON on stdout
+ *   tuiboard summary --pretty     # indented, for humans
+ *   tuiboard summary --next 8     # how many upcoming tasks per board (default 5)
+ *
+ * Written for status bars, widgets and scripts: no TUI, no OpenTUI preload.
+ * It deliberately reuses `loadConfig` and `parseBoard` rather than re-reading
+ * the markdown itself, so these numbers can never drift from what the
+ * dashboard shows — the parser stays the single source of truth.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { isHiddenColumn, loadConfig } from "~/config/loader";
+import { isTask, parseBoard } from "~/parser/markdown";
+import { buildPlannerItems, type PlannerSection } from "~/store/planner-panel";
+import type { Board, PriorityLevel, Task } from "~/types";
+
+/** Lower sorts first, so "highest" leads an ascending sort. */
+const PRIORITY_RANK: Record<PriorityLevel, number> = {
+  highest: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+  lowest: 4,
+  none: 5,
+};
+
+export interface SummaryTask {
+  title: string;
+  board: string;
+  column: string;
+  priority: PriorityLevel;
+  due?: string;
+  scheduled?: string;
+  assignee?: string;
+  tags: string[];
+  /** Negative when overdue, 0 today, positive in the future, null when undated. */
+  daysUntil: number | null;
+}
+
+export interface SummaryColumn {
+  name: string;
+  open: number;
+}
+
+export interface SummaryBoard {
+  name: string;
+  path: string;
+  open: number;
+  done: number;
+  overdue: number;
+  today: number;
+  columns: SummaryColumn[];
+  next: SummaryTask[];
+  /** Parser complaints, so a malformed board is visible instead of silently empty. */
+  diagnostics: number;
+}
+
+/** One row of the Today/Tomorrow planner, flattened for consumers. */
+export interface PlannerEntry {
+  title: string;
+  board: string;
+  column: string;
+  /** "agenda" = time-blocked, "priority" = unscheduled priority, "rest" = everything else. */
+  bucket: string;
+  priority: PriorityLevel;
+  due?: string;
+  scheduled?: string;
+  timeBlock?: string;
+  assignee?: string;
+  /**
+   * Whether the task is already ticked. Today/Tomorrow keep completed tasks —
+   * the day's plan is a record of the day, not just of what is left — so a
+   * consumer that omits this renders a done task identically to an open one.
+   */
+  done: boolean;
+  /** Completion date, when the task carries one (✅ YYYY-MM-DD). */
+  doneDate?: string;
+}
+
+export interface Summary {
+  generatedAt: string;
+  totals: { open: number; done: number; overdue: number; today: number };
+  boards: SummaryBoard[];
+  /**
+   * The same Today/Tomorrow aggregation the TUI renders in its left column.
+   * Built with buildPlannerItems() rather than re-derived here, so a bar
+   * widget and the dashboard can never disagree about what is due.
+   */
+  planner: Record<PlannerSection, PlannerEntry[]>;
+}
+
+/** Local calendar date as YYYY-MM-DD — never UTC, or "today" flips at the wrong hour. */
+function localToday(now = new Date()): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/** Whole days between two YYYY-MM-DD dates, midday-anchored to dodge DST. */
+function daysBetween(from: string, to: string): number {
+  const at = (iso: string) => {
+    const [y, m, d] = iso.split("-").map(Number);
+    return new Date(y!, (m ?? 1) - 1, d ?? 1, 12, 0, 0).getTime();
+  };
+  return Math.round((at(to) - at(from)) / 86_400_000);
+}
+
+/** "09:30-11:00" from minutes-since-midnight, or undefined when unblocked. */
+function formatTimeBlock(tb: Task["timeBlock"]): string | undefined {
+  if (!tb) return undefined;
+  const hhmm = (m: number) =>
+    String(Math.floor(m / 60)).padStart(2, "0") + ":" + String(m % 60).padStart(2, "0");
+  return hhmm(tb.startMin) + "-" + hhmm(tb.endMin);
+}
+
+/** The date a task is judged by: an explicit due date wins over a scheduled one. */
+function effectiveDate(task: Task): string | undefined {
+  return task.due ?? task.scheduled;
+}
+
+export function buildSummary(options: { next?: number; today?: string } = {}): Summary {
+  const nextCount = options.next ?? 5;
+  const today = options.today ?? localToday();
+  const config = loadConfig();
+
+  const boards: SummaryBoard[] = [];
+  const parsed: Board[] = [];
+  const totals = { open: 0, done: 0, overdue: 0, today: 0 };
+
+  for (const ref of config.boards) {
+    let content: string;
+    try {
+      content = readFileSync(ref.path, "utf-8");
+    } catch {
+      // A board listed in config but missing on disk is worth surfacing, not
+      // crashing over: a widget polling every 30s shouldn't die on a moved file.
+      boards.push({
+        name: ref.name ?? ref.path,
+        path: ref.path,
+        open: 0,
+        done: 0,
+        overdue: 0,
+        today: 0,
+        columns: [],
+        next: [],
+        diagnostics: -1,
+      });
+      continue;
+    }
+
+    const { board, diagnostics } = parseBoard(content, { filepath: ref.path });
+    const boardName = ref.name ?? board.name;
+    parsed.push(board);
+
+    const columns: SummaryColumn[] = [];
+    const openTasks: SummaryTask[] = [];
+    let open = 0;
+    let done = 0;
+    let overdue = 0;
+    let dueToday = 0;
+
+    for (const column of board.columns) {
+      const hidden = isHiddenColumn(config, column.name);
+      let columnOpen = 0;
+
+      for (const child of column.children) {
+        if (!isTask(child)) continue;
+        const task = child;
+
+        // Anything parked in Done/Archive counts as done wherever its checkbox
+        // sits — the column is the workflow truth, not the `- [x]` marker.
+        if (hidden || task.done) {
+          done++;
+          continue;
+        }
+
+        open++;
+        columnOpen++;
+
+        const date = effectiveDate(task);
+        const daysUntil = date ? daysBetween(today, date) : null;
+        if (daysUntil !== null && daysUntil < 0) overdue++;
+        if (daysUntil === 0) dueToday++;
+
+        openTasks.push({
+          title: task.displayTitle,
+          board: boardName,
+          column: column.name,
+          priority: task.priority,
+          due: task.due,
+          scheduled: task.scheduled,
+          assignee: task.assignee,
+          tags: task.tags,
+          daysUntil,
+        });
+      }
+
+      if (!hidden) columns.push({ name: column.name, open: columnOpen });
+    }
+
+    // Soonest first; undated tasks last; ties broken by priority then title so
+    // the order is stable between polls and the widget doesn't flicker.
+    openTasks.sort((a, b) => {
+      const ad = a.daysUntil ?? Number.POSITIVE_INFINITY;
+      const bd = b.daysUntil ?? Number.POSITIVE_INFINITY;
+      if (ad !== bd) return ad - bd;
+      const ap = PRIORITY_RANK[a.priority];
+      const bp = PRIORITY_RANK[b.priority];
+      if (ap !== bp) return ap - bp;
+      return a.title.localeCompare(b.title);
+    });
+
+    totals.open += open;
+    totals.done += done;
+    totals.overdue += overdue;
+    totals.today += dueToday;
+
+    boards.push({
+      name: boardName,
+      path: ref.path,
+      open,
+      done,
+      overdue,
+      today: dueToday,
+      columns,
+      next: openTasks.slice(0, nextCount),
+      diagnostics: diagnostics.length,
+    });
+  }
+
+  const planner: Record<PlannerSection, PlannerEntry[]> = {
+    overdue: [],
+    today: [],
+    tomorrow: [],
+  };
+  for (const item of buildPlannerItems(parsed)) {
+    planner[item.section].push({
+      title: item.task.displayTitle,
+      board: item.boardName,
+      column: item.columnName,
+      bucket: item.bucket,
+      priority: item.task.priority,
+      due: item.task.due,
+      scheduled: item.task.scheduled,
+      timeBlock: formatTimeBlock(item.task.timeBlock),
+      assignee: item.task.assignee,
+      done: item.task.done,
+      doneDate: item.task.doneDate,
+    });
+  }
+
+  return { generatedAt: new Date().toISOString(), totals, boards, planner };
+}
+
+export async function runSummary(argv: readonly string[]): Promise<number> {
+  let pretty = false;
+  let next: number | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--pretty") pretty = true;
+    else if (arg === "--next") next = Number(argv[++i]);
+    else if (arg.startsWith("--next=")) next = Number(arg.slice("--next=".length));
+    else {
+      console.error(`tuiboard summary: unknown argument "${arg}"`);
+      return 2;
+    }
+  }
+
+  if (next !== undefined && (!Number.isFinite(next) || next < 0)) {
+    console.error("tuiboard summary: --next needs a non-negative number");
+    return 2;
+  }
+
+  const summary = buildSummary({ next });
+  process.stdout.write(
+    (pretty ? JSON.stringify(summary, null, 2) : JSON.stringify(summary)) + "\n",
+  );
+  return 0;
+}

package/src/cli/task.ts

@@ -0,0 +1,235 @@
+/**
+ * Headless mutations on a board, for scripts and widgets.
+ *
+ *   tuiboard task done   --board <name> --column <col> --match <text>
+ *   tuiboard task undone --board <name> --column <col> --match <text>
+ *   tuiboard task add    --board <name> --column <col> --text <text>
+ *   tuiboard task defer --board <name> --column <col> --match <text> [--days N|--to DATE]
+ *   ... --dry-run     report what would change, write nothing
+ *
+ * Why match by text and not by index: a task's id is `${column}:${position}`,
+ * which is only valid inside one render pass. Anything outside the TUI — a
+ * widget polling every two minutes, a cron job — holds a stale snapshot, and
+ * acting on a stale index silently hits the wrong task. Matching on the
+ * rendered title instead makes a moved task a miss rather than a mistake.
+ *
+ * Concurrency is handled by writeBoardFile()'s mtime watermark: if the file
+ * changed since we read it, it throws ConflictError and we refuse the write.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { loadConfig } from "~/config/loader";
+import { ConflictError, statMtime, writeBoardFile } from "~/io/writer";
+import { isTask, parseBoard } from "~/parser/markdown";
+import { serializeBoard } from "~/parser/serialize";
+import type { Board, Column, Task } from "~/types";
+
+interface Args {
+  board?: string;
+  column?: string;
+  match?: string;
+  text?: string;
+  days?: number;
+  to?: string;
+  dryRun: boolean;
+}
+
+function parse(argv: readonly string[]): Args {
+  const a: Args = { dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    const take = () => argv[++i];
+    if (arg === "--board") a.board = take();
+    else if (arg === "--column") a.column = take();
+    else if (arg === "--match") a.match = take();
+    else if (arg === "--text") a.text = take();
+    else if (arg === "--days") a.days = Number(take());
+    else if (arg === "--to") a.to = take();
+    else if (arg === "--dry-run") a.dryRun = true;
+    else if (arg.startsWith("--board=")) a.board = arg.slice(8);
+    else if (arg.startsWith("--column=")) a.column = arg.slice(9);
+    else if (arg.startsWith("--match=")) a.match = arg.slice(8);
+    else if (arg.startsWith("--text=")) a.text = arg.slice(7);
+    else if (arg.startsWith("--days=")) a.days = Number(arg.slice(7));
+    else if (arg.startsWith("--to=")) a.to = arg.slice(5);
+    else throw new Error(`unknown argument "${arg}"`);
+  }
+  return a;
+}
+
+function isoToday(): string {
+  const d = new Date();
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function isoShift(days: number): string {
+  const d = new Date();
+  d.setDate(d.getDate() + days);
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** Resolve a board by configured name, then by path suffix. */
+function resolveBoard(needle: string) {
+  const cfg = loadConfig();
+  const lower = needle.toLowerCase();
+  const hit =
+    cfg.boards.find((b) => (b.name ?? "").toLowerCase() === lower) ??
+    cfg.boards.find((b) => b.path.toLowerCase().endsWith(lower));
+  if (!hit) {
+    const names = cfg.boards.map((b) => b.name ?? b.path).join(", ");
+    throw new Error(`board "${needle}" not found. Configured: ${names || "(none)"}`);
+  }
+  return hit;
+}
+
+function findColumn(board: Board, name: string): Column {
+  const lower = name.toLowerCase();
+  const col = board.columns.find((c) => c.name.toLowerCase() === lower);
+  if (!col) {
+    throw new Error(
+      `column "${name}" not found. Available: ${board.columns.map((c) => c.name).join(", ")}`,
+    );
+  }
+  return col;
+}
+
+/** Exactly one match or nothing: an ambiguous title must not be guessed at. */
+function findTask(col: Column, needle: string): Task {
+  const lower = needle.toLowerCase();
+  const tasks = col.children.filter(isTask);
+  let hits = tasks.filter((t) => t.displayTitle.toLowerCase() === lower);
+  if (hits.length === 0) {
+    hits = tasks.filter((t) => t.displayTitle.toLowerCase().includes(lower));
+  }
+  if (hits.length === 0) throw new Error(`no task in "${col.name}" matching "${needle}"`);
+  if (hits.length > 1) {
+    throw new Error(
+      `"${needle}" matches ${hits.length} tasks in "${col.name}"; be more specific`,
+    );
+  }
+  return hits[0]!;
+}
+
+export async function runTask(argv: readonly string[]): Promise<number> {
+  const sub = argv[0];
+  if (sub !== "done" && sub !== "undone" && sub !== "add" && sub !== "defer") {
+    console.error(
+      "usage: tuiboard task <done|undone|add|defer> --board <b> --column <c> [--match|--text] <s>",
+    );
+    return 2;
+  }
+
+  let a: Args;
+  try {
+    a = parse(argv.slice(1));
+  } catch (e) {
+    console.error(`tuiboard task: ${(e as Error).message}`);
+    return 2;
+  }
+
+  if (!a.board || !a.column) {
+    console.error("tuiboard task: --board and --column are required");
+    return 2;
+  }
+  if ((sub === "done" || sub === "undone" || sub === "defer") && !a.match) {
+    console.error(`tuiboard task ${sub}: --match is required`);
+    return 2;
+  }
+  if (sub === "defer" && a.days !== undefined && !Number.isFinite(a.days)) {
+    console.error("tuiboard task defer: --days must be a number");
+    return 2;
+  }
+  if (sub === "defer" && a.to !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(a.to)) {
+    console.error("tuiboard task defer: --to must be YYYY-MM-DD");
+    return 2;
+  }
+  if (sub === "add" && !a.text) {
+    console.error("tuiboard task add: --text is required");
+    return 2;
+  }
+
+  try {
+    const ref = resolveBoard(a.board);
+    const mtime = statMtime(ref.path);
+    const { board } = parseBoard(readFileSync(ref.path, "utf-8"), { filepath: ref.path });
+    const col = findColumn(board, a.column);
+
+    let summary: string;
+
+    if (sub === "done") {
+      const task = findTask(col, a.match!);
+      if (task.done) {
+        console.log(`already done: ${task.displayTitle}`);
+        return 0;
+      }
+      // Same semantics as the TUI's toggleDone: keep an existing completion
+      // date if one was already recorded, otherwise stamp today.
+      task.done = true;
+      task.dirty = true;
+      task.doneDate = task.doneDate ?? isoToday();
+      summary = `done: ${task.displayTitle}`;
+    } else if (sub === "undone") {
+      // The counterpart of `done`: ticking a task by mistake, or reopening one
+      // that turned out not to be finished, must not require the TUI.
+      // The completion date goes with it — a task that is open has not been
+      // completed on any date, and a stale ✅ would outlive the tick.
+      const task = findTask(col, a.match!);
+      if (!task.done) {
+        console.log(`already open: ${task.displayTitle}`);
+        return 0;
+      }
+      task.done = false;
+      task.doneDate = undefined;
+      task.dirty = true;
+      summary = `reopened: ${task.displayTitle}`;
+    } else if (sub === "defer") {
+      const task = findTask(col, a.match!);
+      const target = a.to ?? isoShift(a.days ?? 1);
+
+      // Move the field the planner actually reads. buildPlannerItems() buckets
+      // on `scheduled ?? due`, so shifting `due` on a task that also carries a
+      // `scheduled` date would write a change that never moves the row.
+      // A task with neither date gets a scheduled one, which is what puts it
+      // on the agenda in the first place.
+      if (task.scheduled !== undefined) task.scheduled = target;
+      else if (task.due !== undefined) task.due = target;
+      else task.scheduled = target;
+
+      task.dirty = true;
+      summary = `deferred to ${target}: ${task.displayTitle}`;
+    } else {
+      const task: Task = {
+        id: `${board.columns.indexOf(col)}:${col.children.filter(isTask).length}`,
+        done: false,
+        rawBody: a.text!,
+        rawLine: `- [ ] ${a.text!}`,
+        dirty: true,
+        displayTitle: a.text!,
+        tags: [],
+        wikilinks: [],
+        priority: "none",
+      };
+      col.children.push(task);
+      summary = `added to ${col.name}: ${a.text}`;
+    }
+
+    if (a.dryRun) {
+      console.log(`[dry-run] ${summary}`);
+      return 0;
+    }
+
+    writeBoardFile(ref.path, serializeBoard(board), { expectedMtimeMs: mtime });
+    console.log(summary);
+    return 0;
+  } catch (e) {
+    if (e instanceof ConflictError) {
+      console.error(`tuiboard task: the board changed on disk — refresh and retry.`);
+      return 3;
+    }
+    console.error(`tuiboard task: ${(e as Error).message}`);
+    return 1;
+  }
+}

package/src/config/loader.ts

@@ -43,6 +43,15 @@ export interface Config {
    * When unset, tuiboard falls back to opening a tab + `claude --resume <id>`.
    */
   resumeCommand?: string[];
+  /**
+   * Template for the shell command copied to the clipboard by `c` in the agents
+   * zone — one paste that `cd`s into the session's directory and resumes it.
+   * The tokens `{cwd}` and `{sessionId}` are substituted. Default:
+   *   cd "{cwd}" && claude --resume {sessionId}
+   * `&&` works in bash/zsh/pwsh/cmd; Nushell users may prefer
+   *   cd "{cwd}"; claude --resume {sessionId}
+   */
+  copyResumeCommand: string;
   /**
    * Optional read-only calendar feeds merged into the Agenda (timeline) zone.
    * Paths support `~` and are resolved against the config dir if relative.
@@ -102,10 +111,18 @@ export interface CalendarsConfig {
   microsoft?: MicrosoftCalendarConfig;
 }
 
+/**
+ * Default clipboard template for `c` in the agents zone: `cd` + resume in one
+ * paste. `&&` chains in bash/zsh/pwsh/cmd (Nushell users override with `;`).
+ */
+export const DEFAULT_COPY_RESUME_COMMAND =
+  'cd "{cwd}" && claude --resume {sessionId}';
+
 export const DEFAULT_CONFIG: Omit<Config, "root" | "loaded" | "boards"> = {
   assignees: [],
   doneColumn: "Done",
   archiveColumn: "Archive",
+  copyResumeCommand: DEFAULT_COPY_RESUME_COMMAND,
   zones: { planner: "on", agenda: "on", agents: "on" },
 };
 
@@ -149,6 +166,7 @@ interface RawConfig {
   done_column: string;
   archive_column: string;
   resume_command: string[];
+  copy_resume_command: string;
   calendars: {
     google?: {
       enabled?: boolean;
@@ -293,6 +311,11 @@ function normalize(raw: Partial<RawConfig>, root: string, loaded: boolean): Conf
       Array.isArray(raw.resume_command) && raw.resume_command.length > 0
         ? raw.resume_command.map(String)
         : undefined,
+    copyResumeCommand:
+      typeof raw.copy_resume_command === "string" &&
+      raw.copy_resume_command.trim().length > 0
+        ? raw.copy_resume_command
+        : DEFAULT_COPY_RESUME_COMMAND,
     calendars: normalizeCalendars(raw.calendars, root),
     zones: normalizeZones(raw.zones),
   };

package/src/input/handleKey.ts

@@ -432,6 +432,20 @@ function handleAgentsZone(store: TuiStore, key: KeyEvent): void {
     // Open (resume) the selected session in a new WezTerm tab.
     const target = sessions[ui.row];
     if (target) void openSessionInWezterm(store, target.cwd, target.sessionId);
+  } else if (key.name === "c") {
+    // Copy a one-paste "cd + resume" command for the selected session, so you
+    // can drop it into any tab/pane anywhere and land in the right directory
+    // resuming the right session (no WezTerm dependency, unlike Enter).
+    const target = sessions[ui.row];
+    if (target) {
+      const cmd = store.config.copyResumeCommand
+        .replaceAll("{cwd}", target.cwd)
+        .replaceAll("{sessionId}", target.sessionId);
+      copyToClipboard(cmd).then(
+        () => store.flashBanner("info", `📋 Copied resume command (${target.sessionId.slice(0, 8)})`),
+        (err) => store.flashBanner("error", `Copy failed: ${err}`),
+      );
+    }
   } else if (key.name === "o") {
     // Inspect the session in the detail modal.
     const target = sessions[ui.row];

package/src/store/index.test.ts

@@ -18,6 +18,7 @@ function emptyConfig(overrides: Partial<Config> = {}): Config {
     assignees: [],
     doneColumn: "Done",
     archiveColumn: "Archive",
+    copyResumeCommand: 'cd "{cwd}" && claude --resume {sessionId}',
     zones: { planner: "on", agenda: "on", agents: "on" },
     ...overrides,
   };

package/src/ui/Modal.tsx

@@ -772,12 +772,14 @@ function AgentDetailModal(props: { store: TuiStore; modal: Extract<NonNullable<T
             <box style={{ height: 1 }} />
             <text>
               <span style={{ fg: T.textDim }}>
-                resume — press Enter in the agents list to open this in WezTerm:
+                resume — Enter opens this in WezTerm; c copies this command to paste anywhere:
               </span>
             </text>
             <text wrapMode="word">
               <span style={{ fg: T.scheduled }}>
-                claude --resume {s().sessionId}
+                {props.store.config.copyResumeCommand
+                  .replaceAll("{cwd}", s().cwd)
+                  .replaceAll("{sessionId}", s().sessionId)}
               </span>
             </text>
           </box>
@@ -845,6 +847,7 @@ function HelpModal(props: { store: TuiStore }) {
         <span style={{ fg: T.text }}>{"  /                 Search task titles — jumps cursor to first match\n"}</span>
         <span style={{ fg: T.textDim }}>{"\nAgents zone\n"}</span>
         <span style={{ fg: T.text }}>{"  Enter             Open (resume) the selected session in a new WezTerm tab\n"}</span>
+        <span style={{ fg: T.text }}>{"  c                 Copy a 'cd + claude --resume' command for the session\n"}</span>
         <span style={{ fg: T.text }}>{"  o                 Session detail (cwd, branch, last prompts, resume cmd)\n"}</span>
         <span style={{ fg: T.textDim }}>{"\nMulti-select\n"}</span>
         <span style={{ fg: T.text }}>{"  Space             Mark / unmark task (cursor stays — mark in any order)\n"}</span>

package/src/views/Dashboard.tsx

@@ -54,18 +54,46 @@ export function Dashboard(props: { store: TuiStore }) {
  * Board + planner share BoardOnly because both live in the top-left
  * zone of the normal layout and BoardOnly already respects ui.zoomed
  * to render only the active panel between them.
+ *
+ * Modals: the normal layout drops them into the Agenda's slot, which doesn't
+ * exist while zoomed — so here the modal floats as a centered absolute overlay
+ * on top of the zoomed view. The user stays zoomed; close the modal and the
+ * zoomed view is exactly as they left it (no exit-zoom / re-zoom flip).
  */
 function ZoomedLayout(props: { store: TuiStore }) {
-  const zone = () => props.store.state.ui.activeZone;
+  const ui = () => props.store.state.ui;
+  const zone = () => ui().activeZone;
 
   return (
-    <Show when={zone() === "timeline"} fallback={
-      <Show when={zone() === "agents"} fallback={<BoardOnly store={props.store} />}>
-        <AgentsOnly store={props.store} />
+    <>
+      <Show when={zone() === "timeline"} fallback={
+        <Show when={zone() === "agents"} fallback={<BoardOnly store={props.store} />}>
+          <AgentsOnly store={props.store} />
+        </Show>
+      }>
+        <TimelineOnly store={props.store} />
       </Show>
-    }>
-      <TimelineOnly store={props.store} />
-    </Show>
+      {/* Modal overlay — only while zoomed AND a modal is open. Absolute + high
+          zIndex so it paints over the zoomed view; centered; transparent
+          backdrop so the board stays visible behind the (opaque) modal panel. */}
+      <Show when={ui().modal}>
+        <box
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            zIndex: 100,
+            flexDirection: "column",
+            alignItems: "center",
+            justifyContent: "center",
+          }}
+        >
+          <ModalLayer store={props.store} />
+        </box>
+      </Show>
+    </>
   );
 }
 

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["bun-types"],
+
+    "jsx": "preserve",
+    "jsxImportSource": "@opentui/solid",
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*"]
+}