tuiboard 0.12.0 → 0.13.1

package/.tuiboard/config.example.yaml

@@ -59,6 +59,10 @@ archive_column: Archive
 # PowerShell (pwsh, else powershell); elsewhere your $SHELL. Force one with:
 # resume_shell: auto      # bash | zsh | fish | nu | pwsh | powershell | cmd
 #
+# Agent status symbols, the same as herdr's: × waiting for you, ◐ working,
+# ✓ done, ○ idle, · closed (△ = turn stopped updating). Or colored dots:
+# status_indicators: symbols   # symbols (default) | dots
+#
 # Enter not doing what you expect? From the directory you run tuiboard in (in a
 # checkout of the repo): `bun run agents:open <session-id-prefix> --dry-run`
 # prints the detected terminal, shell and exact command; the `o` detail of a

package/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-09-17
+
+### Fixed
+- **Agents list stays in order when sessions move** (#52). A new session
+  appearing on top could show twice, leave blank rows, or draw rows in the
+  wrong order past the panel border; the lists now keep one stable row per
+  position. The cursor also stays on the session you selected while the list
+  reorders, instead of silently landing on another one (so Enter, `H` and `c`
+  act on the session you picked).
+- **`--view=agents` / `--view=timeline` / `--view=board` start on their own
+  zone** (#54), so the cursor and keys work right away instead of acting on
+  the hidden planner.
+
+## [0.13.0] - 2026-09-17
+
+tuiboard and [herdr](https://herdr.dev) now work as one: the Agents zone shows
+herdr's live state for every session open there, speaks herdr's status
+symbols, and `H` jumps to a session in herdr or resumes it in the right
+workspace. Plus fixes found using it all day on Windows.
+
+### Added
+- **Live agent state from herdr** (#37). When herdr is running, tuiboard polls
+  `herdr api snapshot` and links every pane running Claude Code, Codex,
+  OpenCode or Pi to its session — by the session id/file herdr reports (with
+  herdr's agent integrations installed), else by agent and directory. Those
+  sessions take herdr's state, including two new ones: **waiting for you** and
+  **done**; idle Codex/OpenCode/Pi sessions become visible, and long Claude
+  turns no longer show as stale (#22). Zoomed cards and the `o` detail show the
+  herdr workspace and tab.
+- **herdr's status symbols** — `×` waiting, `◐` working, `✓` done, `○` idle,
+  `·` closed (tuiboard's own `△` for stale) — are the default for everyone, so
+  both tools read the same; `status_indicators: dots` keeps colored dots.
+- **`H` opens sessions in herdr** (#38): focuses the pane a session is open
+  in, or resumes it in herdr — a new tab named after the session, in the
+  workspace that already holds that directory (else one named like the
+  folder, else the focused one). **Enter** on a session already open in herdr
+  focuses it instead of starting a second copy.
+- **Omarchy bar widget in the repo** (#27): `omarchy-plugin/` — an
+  overdue/today badge and a Today/Tomorrow panel (done, undone, defer, open
+  tuiboard) built on `tuiboard summary` / `tuiboard task`, installed with
+  `omarchy-plugin/install.sh`. Repo only, not part of the npm package.
+
+### Changed
+- **Agent sessions are sorted by most recent activity** (#43), newest first,
+  instead of by status first — a session used 40 seconds ago no longer sits
+  below ones idle in herdr for hours. Status only breaks ties; archived
+  sessions stay at the bottom.
+- Launch steps for Enter and `H` run asynchronously: a slow start (cold
+  PowerShell, an agent booting in herdr) no longer freezes the UI.
+
+### Fixed
+- **Quitting gives the terminal back** (#47). `q`, Ctrl+C and termination
+  signals exited without tearing down the renderer, leaving mouse tracking
+  and the alternate screen on — moving the mouse at the shell then printed
+  `51;7;45M…`. tuiboard now restores the terminal before exiting, and the
+  `tuiboard` launcher resets mouse/paste/focus reporting and the cursor after
+  the app ends, whatever way it ended.
+- **`H` on Windows with Codex, OpenCode and Pi** (#41). npm-installed CLIs on
+  Windows are an extensionless sh shim next to `.cmd`/`.ps1`, which herdr
+  can't launch directly ("not a valid Win32 application"); on Windows the
+  resume command is typed into the new pane's shell instead.
+- **Responsive layout follows the renderer's terminal size** (#45), the size
+  the frame is drawn at, instead of `process.stdout.columns`.
+
+### Known issues
+- On Windows, herdr may not detect Pi sessions as agents (#49): they open
+  fine, but without herdr's live state.
+
 ## [0.12.0] - 2026-09-17
 
 The Agents zone stops being Claude-Code-only: it now lists **Codex, OpenCode
@@ -419,6 +487,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.13.1]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.1
+[0.13.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.0
 [0.12.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.12.0
 [0.11.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.11.0
 [0.10.0]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.10.0

package/README.md

@@ -85,6 +85,20 @@ record of running processes, so their sessions show as busy while a turn is in
 progress (stale if a turn stops updating for 30 minutes), never as
 idle-but-open.
 
+Each session's state uses the same symbols as [herdr](https://herdr.dev):
+`×` waiting for you, `◐` working, `✓` done, `○` idle, `·` closed, plus
+tuiboard's own `△` for a turn that stopped updating (`status_indicators: dots`
+switches to colored dots). **With herdr running**, tuiboard reads its live
+state for every session open in a herdr pane — so "waiting for you", "done"
+and "idle" show up for every agent, and a long Claude turn no longer turns
+stale — and the zoomed cards say where each one lives (`herdr blits · tab 3`).
+herdr reports the exact session when its agent integration is installed
+(`herdr integration install claude|codex|opencode|pi`); otherwise tuiboard
+matches by agent and directory. `H` jumps to a session in herdr — or resumes
+it there, in a new tab of the workspace that holds its project — and Enter on
+a session that's already open in herdr takes you to it instead of starting a
+second copy.
+
 Every session carries a colored two-letter harness badge — `cc` Claude Code,
 `cx` Codex, `oc` OpenCode, `pi` Pi — plus the model it ran on. The dashboard strip keeps
 one line per session (on a narrow row the model gives way first, then the
@@ -448,9 +462,10 @@ session (until the next terminal resize).
 | Key | Action |
 |---|---|
 | `j` / `k` | Move the cursor down / up the session list |
-| `Enter` | Open (resume) the selected session in a new tab/window of your terminal — tmux, herdr, WezTerm, Windows Terminal, Ghostty, or the OS default; falls back to copying the command (`resume_terminal` to force one) |
+| `Enter` | Go to the session if it's open in herdr; otherwise open (resume) it in a new tab/window of your terminal — tmux, herdr, WezTerm, Windows Terminal, Ghostty, or the OS default; falls back to copying the command (`resume_terminal` to force one) |
 | `c` | Copy a one-paste `cd … && <resume>` command (e.g. `claude --resume <id>`) 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 (harness, model, cwd, branch, last prompts, resume command, result of the last `Enter`) |
+| `H` | herdr: go to the session's pane, or resume it in a new tab of its project's workspace (herdr must be running) |
 | `f` | Filter by harness: all → `cc` Claude Code → `cx` Codex → `oc` OpenCode → `pi` Pi (shown in the panel title; outside the Agents zone `f` is the board filter) |
 
 ### Task actions (work in board, planner, AND timeline zones)
@@ -554,10 +569,48 @@ An ambiguous match is refused rather than guessed at.
 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.
 
+## Omarchy bar widget
+
+On [Omarchy](https://omarchy.org), `omarchy-plugin/` ships a bar widget built
+on `tuiboard summary` and `tuiboard task`: an overdue/today badge in the bar,
+and a panel with the Today/Tomorrow planner where a task can be marked
+done/undone or deferred to tomorrow without leaving the bar. Right-click the
+badge to force a refresh, middle-click to open tuiboard itself.
+
+**Requires** `tuiboard` on `PATH` (see [Install](#install) above) and Omarchy
+with its shell plugin support.
+
+**Install** (from a checkout of this repo):
+
+```bash
+git clone https://github.com/NazzarenoGiannelli/tuiboard.git
+cd tuiboard
+./omarchy-plugin/install.sh
+```
+
+This symlinks `omarchy-plugin/` into `~/.config/omarchy/plugins/nazz.tuiboard`
+and enables it in the bar's right section. `omarchy plugin add <git-url>`
+isn't used here — it clones a git repo and expects `manifest.json` at its
+root, which doesn't fit a widget living inside this monorepo, and there's no
+separate Omarchy plugin marketplace to publish to at the time of writing. The
+symlink means `omarchy plugin update` doesn't apply; update by pulling this
+repo instead (`git pull`, then `omarchy-shell shell rescanPlugins` if the bar
+doesn't pick it up on its own).
+
+Refresh interval, the `tuiboard summary`/`tuiboard task` commands, the open
+command, and the completion sound are all configurable from Omarchy's own
+plugin settings (`manifest.json`'s schema) — no config file to hand-edit.
+
+Uninstall: `omarchy plugin remove nazz.tuiboard`.
+
 ## Status
 
 See [CHANGELOG.md](CHANGELOG.md) for the full release history.
 
+- **v0.13** — tuiboard + herdr: live agent state from herdr (waiting for you,
+  working, done, idle) with herdr's status symbols, `H` to jump to a session
+  in herdr or resume it in its project's workspace, sessions sorted by most
+  recent activity, and the terminal properly restored on quit.
 - **v0.12** — the Agents zone goes multi-agent: Codex, OpenCode and Pi sessions
   next to Claude Code, with a colored harness badge, the model, a harness
   filter (`f`) and two-line cards when zoomed. Enter reopens a session in the

package/bin/tuiboard.ts

@@ -85,8 +85,17 @@ const child = spawn(
     env: { ...process.env, TUIBOARD_SPLASH_DONE: "1", TUIBOARD_READY_FLAG: readyFlag },
   },
 );
+// Safety net: whatever way the app ended (crash, kill), give the shell a sane
+// terminal back — mouse reporting off (else moving the mouse prints
+// `51;7;45M…`), focus/paste reporting off, cursor visible. Harmless when the
+// app already restored everything.
+const RESET_TERMINAL =
+  "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1015l" + // mouse
+  "\x1b[?1004l\x1b[?2004l" + // focus events, bracketed paste
+  "\x1b[?25h"; // cursor
 child.on("exit", (code, signal) => {
   stopSplash();
+  try { process.stdout.write(RESET_TERMINAL); } catch { /* ignore */ }
   process.exit(code ?? (signal ? 1 : 0));
 });
 child.on("error", (err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "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/app-exit.ts

@@ -0,0 +1,37 @@
+/**
+ * The one way out of the TUI. Destroying the OpenTUI renderer is what gives
+ * the terminal back — mouse tracking off, main screen, cooked input, cursor —
+ * and a bare `process.exit` skips it (OpenTUI only cleans up on `beforeExit`
+ * and its own signal/Ctrl+C handling), which left shells printing mouse
+ * reports like `51;7;45M` after quitting.
+ */
+
+import type { CliRenderer } from "@opentui/core";
+
+let renderer: CliRenderer | undefined;
+let quitting = false;
+
+export function registerRenderer(r: CliRenderer): void {
+  renderer = r;
+}
+
+/** Restore the terminal, run `cleanup`, exit. Safe to call more than once. */
+export async function quitApp(cleanup: () => Promise<void>, code = 0): Promise<never> {
+  if (!quitting) {
+    quitting = true;
+    try {
+      renderer?.destroy();
+      // A destroy requested mid-frame completes when that frame ends.
+      await new Promise((r) => setTimeout(r, 50));
+    } catch {
+      // Never let a teardown error keep the process alive.
+    }
+    try {
+      await cleanup();
+    } catch {
+      // Same.
+    }
+    process.exit(code);
+  }
+  return new Promise<never>(() => {});
+}

package/src/app.tsx

@@ -21,8 +21,11 @@ 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";
+import { createEffect, createMemo } from "solid-js";
+import { createCliRenderer } from "@opentui/core";
+import { render, useKeyboard, useTerminalDimensions } from "@opentui/solid";
+
+import { quitApp, registerRenderer } from "~/app-exit";
 
 import { parseArgs, type ViewKind } from "~/cli/args";
 import { loadConfig } from "~/config/loader";
@@ -84,12 +87,8 @@ if (needsOnboarding) {
   store.openBoardNew(true);
 }
 
-process.on("SIGINT", () => {
-  store.dispose().finally(() => process.exit(0));
-});
-process.on("SIGTERM", () => {
-  store.dispose().finally(() => process.exit(0));
-});
+process.on("SIGINT", () => void quitApp(() => store.dispose()));
+process.on("SIGTERM", () => void quitApp(() => store.dispose()));
 
 // ─── Responsive layout ──────────────────────────────────────────────────────
 // Auto-hide optional zones when the terminal isn't wide enough to host them
@@ -102,8 +101,7 @@ process.on("SIGTERM", () => {
 // This only reports what FITS. The store combines it with each zone's enabled
 // flag and the user's desired visibility, so F1/F2/F3 toggles persist across
 // resizes and a disabled/hidden zone is never force-shown.
-function applyResponsiveLayout(): void {
-  const width = process.stdout.columns ?? 200;
+function applyResponsiveLayout(width: number): void {
   // Report which zones FIT at this width. The store ANDs this with each zone's
   // enabled flag and the user's desired visibility, so a disabled or
   // intentionally-hidden zone is never force-shown just because there's room.
@@ -122,8 +120,11 @@ function applyResponsiveLayout(): void {
     { narrow: width < 100 },
   );
 }
-applyResponsiveLayout();
-process.stdout.on("resize", applyResponsiveLayout);
+// Initial guess before the renderer exists; from then on the layout follows
+// OpenTUI's own dimensions (see App). `process.stdout.columns` can lag behind
+// the real size — e.g. a Windows Terminal tab that starts at a provisional
+// size — which left zones overlapping until a manual resize.
+applyResponsiveLayout(process.stdout.columns ?? 200);
 
 // Land on the Today/Tomorrow panel by default — for a daily-planning tool the
 // first question is "what's on my plate today", and that panel answers it.
@@ -147,6 +148,11 @@ if (view === "planner") {
   store.setActiveZone("planner");
   store.setZoomed(true);
 }
+// The single-zone views show one zone; keys must act on it. Without this the
+// planner (the default landing zone above) stayed active behind them.
+if (view === "agents" || view === "timeline" || view === "board") {
+  store.setActiveZone(view);
+}
 
 // ─── App shell ──────────────────────────────────────────────────────────────
 
@@ -170,6 +176,13 @@ function App() {
 
   useKeyboard((key) => handleKey(store, key, plannerItems().length));
 
+  // Same width the frame is drawn at, updated on the renderer's resize events.
+  const dims = useTerminalDimensions();
+  createEffect(() => {
+    const { width } = dims();
+    if (width > 0) applyResponsiveLayout(width);
+  });
+
   return (
     <box
       style={{
@@ -226,4 +239,6 @@ if (process.env.TUIBOARD_READY_FLAG) {
   }
 }
 
-await render(() => <App />, { useMouse: true });
+const renderer = await createCliRenderer({ useMouse: true });
+registerRenderer(renderer);
+await render(() => <App />, renderer);

package/src/config/loader.ts

@@ -59,6 +59,11 @@ export interface Config {
    * Windows, `$SHELL` elsewhere). Ignored when `resumeCommand` is set.
    */
   resumeShell: "auto" | Shell;
+  /**
+   * Agent status glyphs (config `status_indicators`): `symbols` (default —
+   * the same × ◐ ✓ ○ · herdr uses) or `dots` (● ○ ·).
+   */
+  statusIndicators: "dots" | "symbols";
   /**
    * 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.
@@ -141,6 +146,7 @@ export const DEFAULT_CONFIG: Omit<Config, "root" | "loaded" | "boards"> = {
   archiveColumn: "Archive",
   resumeTerminal: "auto",
   resumeShell: "auto",
+  statusIndicators: "symbols",
   copyResumeCommand: DEFAULT_COPY_RESUME_COMMAND,
   zones: { planner: "on", agenda: "on", agents: "on" },
 };
@@ -216,6 +222,7 @@ interface RawConfig {
   resume_command: string[];
   resume_terminal: string;
   resume_shell: string;
+  status_indicators: string;
   copy_resume_command: string;
   calendars: {
     google?: {
@@ -367,6 +374,7 @@ 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",
+    statusIndicators: raw.status_indicators === "dots" ? "dots" : "symbols",
     copyResumeCommand:
       typeof raw.copy_resume_command === "string" &&
       raw.copy_resume_command.trim().length > 0

package/src/input/handleKey.ts

@@ -13,6 +13,7 @@
  * shares the same input contract.
  */
 
+import { quitApp } from "~/app-exit";
 import { isHiddenColumn } from "~/config/loader";
 import {
   LAUNCHER_NAME,
@@ -22,7 +23,9 @@ import {
   runLaunchPlan,
   systemLaunchEnv,
 } from "~/input/open-session";
+import { planHerdrFocus, planHerdrResume } from "~/input/herdr-open";
 import { HARNESS, type AgentSession } from "~/store/agents";
+import { herdrBin, herdrPlace } from "~/store/herdr";
 import { googleTokenCanWrite } from "~/store/calendar";
 import { isTask } from "~/parser/markdown";
 import {
@@ -135,7 +138,7 @@ export function handleKey(
 
   // Quit
   if (key.name === "q" || (key.ctrl && key.name === "c")) {
-    store.dispose().finally(() => process.exit(0));
+    void quitApp(() => store.dispose());
     return;
   }
 
@@ -498,10 +501,16 @@ function handleAgentsZone(store: TuiStore, key: KeyEvent): void {
     store.setCursor(0, Math.min(sessions.length - 1, ui.row + 1));
   } else if (key.name === "k" || key.name === "up") {
     store.setCursor(0, Math.max(0, ui.row - 1));
+  } else if (key.name === "H" || (key.name === "h" && key.shift)) {
+    // Jump to the session in herdr, or resume it there.
+    const target = sessions[ui.row];
+    if (target) void openInHerdr(store, target);
   } else if (key.name === "enter" || key.name === "return") {
-    // Open (resume) the selected session in a new terminal tab/window.
+    // Open (resume) the selected session in a new terminal tab/window —
+    // or, when it's already open in herdr, go there instead of a second copy.
     const target = sessions[ui.row];
-    if (target) void openSession(store, target);
+    if (target?.herdr) void openInHerdr(store, target);
+    else if (target) void openSession(store, target);
   } 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
@@ -959,6 +968,46 @@ async function openSession(store: TuiStore, session: AgentSession): Promise<void
   }
 }
 
+/**
+ * `H` in the Agents zone: focus the herdr pane the session is open in, or
+ * resume it in herdr — a new tab in the workspace that holds its project,
+ * started with `herdr agent start` (see herdr-open.ts).
+ */
+async function openInHerdr(store: TuiStore, session: AgentSession): Promise<void> {
+  const bin = herdrBin();
+  const snap = store.agents.herdr();
+  const { sessionId } = session;
+  if (!bin || !snap) {
+    const text = bin ? "herdr isn't running" : "herdr isn't installed (https://herdr.dev)";
+    store.setLastLaunch(sessionId, false, text);
+    store.flashBanner("warn", text);
+    return;
+  }
+  let steps;
+  let done: string;
+  if (session.herdr) {
+    steps = planHerdrFocus(bin, session);
+    done = `↗ ${herdrPlace(session.herdr)}`;
+  } else {
+    const plan = planHerdrResume(bin, session, snap);
+    steps = plan.steps;
+    done =
+      plan.where.kind === "new"
+        ? `↗ Resumed in a new herdr workspace "${plan.where.label}"`
+        : `↗ Resumed in herdr ${plan.where.label}`;
+    store.flashBanner("info", `Starting ${HARNESS[session.provider].name} in herdr…`);
+  }
+  try {
+    await runLaunchPlan(steps);
+    store.setLastLaunch(sessionId, true, `${done}\n${describePlan(steps)}`);
+    store.flashBanner("info", `${done} (${sessionId.slice(0, 8)})`);
+  } catch (e) {
+    const text = `herdr: ${e instanceof Error ? e.message : String(e)}`;
+    store.setLastLaunch(sessionId, false, text);
+    store.flashBanner("error", text);
+  }
+}
+
 /**
  * Cross-platform clipboard copy. Picks the host's native cli tool:
  *   Windows  → clip

package/src/input/herdr-open.ts

@@ -0,0 +1,132 @@
+/**
+ * Open agent sessions inside herdr (the `H` key, and Enter for sessions
+ * already open there): focus the pane a session lives in, or resume it in a
+ * new tab of the workspace that holds its project, started through
+ * `herdr agent start` so herdr tracks it as an agent from the first second.
+ *
+ * Planning is pure; the steps run through `runLaunchPlan`.
+ */
+
+import { basename } from "node:path";
+
+import type { LaunchStep } from "~/input/open-session";
+import type { AgentSession } from "~/store/agents";
+import { HERDR_AGENT, samePath, type HerdrSnapshot } from "~/store/herdr";
+
+/** Focus the herdr pane a session is open in. */
+export function planHerdrFocus(bin: string, session: AgentSession): LaunchStep[] {
+  if (!session.herdr) throw new Error("session isn't open in herdr");
+  return [{ cmd: bin, args: ["agent", "focus", session.herdr.paneId] }];
+}
+
+export type WorkspaceChoice =
+  | { kind: "existing"; workspaceId: string; label: string; why: "cwd" | "name" | "focused" }
+  | { kind: "new"; label: string };
+
+/**
+ * Where a session should open: the workspace already holding a pane in its
+ * directory, else one named like the directory, else the focused one — or a
+ * new workspace named after the directory when herdr has none.
+ */
+export function chooseWorkspace(snap: HerdrSnapshot, cwd: string): WorkspaceChoice {
+  const label = (id: string) => snap.workspaces.get(id)?.label ?? id;
+  const byCwd = snap.panes.find((p) => p.workspaceId && samePath(p.cwd, cwd));
+  if (byCwd) return { kind: "existing", workspaceId: byCwd.workspaceId, label: label(byCwd.workspaceId), why: "cwd" };
+  const folder = basename(cwd.replaceAll("\\", "/")).toLowerCase();
+  for (const [id, w] of snap.workspaces) {
+    if (folder && w.label.toLowerCase() === folder) return { kind: "existing", workspaceId: id, label: w.label, why: "name" };
+  }
+  const focused = snap.focusedWorkspaceId ?? [...snap.workspaces.keys()][0];
+  if (focused) return { kind: "existing", workspaceId: focused, label: label(focused), why: "focused" };
+  return { kind: "new", label: basename(cwd.replaceAll("\\", "/")) || "agents" };
+}
+
+/** Pane id from a `tab create` / `workspace create` response. */
+function rootPaneId(out: string): string | undefined {
+  try {
+    const r = JSON.parse(out)?.result;
+    return r?.root_pane?.pane_id ?? r?.pane?.pane_id ?? r?.tab?.root_pane?.pane_id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Tab titles: short, single line. */
+function tabLabel(name: string): string {
+  const line = name.split("\n")[0]!.trim();
+  return line.length > 32 ? `${line.slice(0, 31).trimEnd()}…` : line || "agent";
+}
+
+/**
+ * herdr agent names: lowercase letter first, then `[a-z0-9_-]`, ≤ 32 chars.
+ * Title slug + short session id, so two sessions with the same title differ.
+ */
+export function herdrAgentName(title: string, sessionId: string, fallback: string): string {
+  const id = sessionId.toLowerCase().replace(/[^a-z0-9]/g, "").slice(-6);
+  const slug = title
+    .split("\n")[0]!
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^[^a-z]+/, "")
+    .replace(/-+$/, "")
+    .slice(0, 32 - id.length - 1)
+    .replace(/-+$/, "");
+  return `${slug || fallback}-${id}`.slice(0, 32);
+}
+
+/**
+ * Resume a session in herdr: new tab (or workspace) in the session's
+ * directory, then start the agent there.
+ *
+ * POSIX: `herdr agent start --kind <agent> -- <resume args>`, so herdr tracks
+ * it from the first second. Windows: herdr launches the agent's executable
+ * directly, which fails for npm-installed CLIs (codex, opencode, pi are an
+ * extensionless sh shim next to `.cmd`/`.ps1` — "not a valid Win32
+ * application"), so the resume command is typed into the pane's shell
+ * instead (`herdr pane run`), which resolves it through PATHEXT; herdr still
+ * detects the agent from the running process.
+ */
+export function planHerdrResume(
+  bin: string,
+  session: AgentSession,
+  snap: HerdrSnapshot,
+  platform: NodeJS.Platform = process.platform,
+): { steps: LaunchStep[]; where: WorkspaceChoice } {
+  const where = chooseWorkspace(snap, session.cwd);
+  const label = tabLabel(session.displayName);
+  const create: LaunchStep =
+    where.kind === "existing"
+      ? {
+          cmd: bin,
+          args: ["tab", "create", "--workspace", where.workspaceId, "--cwd", session.cwd, "--label", label, "--focus"],
+          captureId: rootPaneId,
+          undo: { cmd: bin, args: ["pane", "close", "{id}"] },
+        }
+      : {
+          cmd: bin,
+          args: ["workspace", "create", "--cwd", session.cwd, "--label", where.label, "--focus"],
+          captureId: rootPaneId,
+          undo: { cmd: bin, args: ["pane", "close", "{id}"] },
+        };
+  if (platform === "win32") {
+    return {
+      steps: [create, { cmd: bin, args: ["pane", "run", "{id}", session.resumeCommand] }],
+      where,
+    };
+  }
+  const [, ...agentArgs] = session.resumeArgv;
+  const start: LaunchStep = {
+    cmd: bin,
+    args: [
+      "agent", "start", herdrAgentName(session.displayName, session.sessionId, HERDR_AGENT[session.provider]),
+      "--kind", HERDR_AGENT[session.provider],
+      "--pane", "{id}",
+      "--timeout", "30000",
+      "--", ...agentArgs,
+    ],
+    // herdr waits for the agent to be ready (up to the --timeout above).
+    timeoutMs: 40_000,
+  };
+  return { steps: [create, start], where };
+}