tuiboard 0.12.0 → 0.13.0

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,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +474,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.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.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/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.
@@ -170,6 +171,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 +234,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 };
+}

package/src/input/open-session.ts

@@ -179,6 +179,8 @@ export interface LaunchStep {
    * replaced with it.
    */
   captureId?: (stdout: string) => string | undefined;
+  /** Best-effort rollback (with `{id}`) if a later step fails, e.g. close the tab this step opened. */
+  undo?: LaunchStep;
 }
 
 export interface LaunchTarget {
@@ -365,39 +367,86 @@ export function describePlan(steps: LaunchStep[]): string {
 
 /**
  * Run a plan. Throws with a readable message on the first failing step.
- * Short IPC steps run synchronously (their output feeds the next step);
- * GUI launches are detached so tuiboard doesn't wait on the new window.
+ * Short IPC steps are awaited (their output feeds the next step) without
+ * blocking the UI; GUI launches are detached so tuiboard doesn't wait on the
+ * new window.
  */
 export async function runLaunchPlan(steps: LaunchStep[]): Promise<void> {
-  const { spawn, spawnSync } = await import("node:child_process");
+  const undos: LaunchStep[] = [];
   let id: string | undefined;
-  for (const step of steps) {
-    const args = step.args.map((a) => (id !== undefined ? a.replaceAll("{id}", id) : a));
-    const exe = Bun.which(step.cmd) ?? step.cmd;
-    if (step.detached) {
-      await new Promise<void>((resolve, reject) => {
-        const child = spawn(exe, args, { detached: true, stdio: "ignore", windowsHide: true });
-        child.once("error", (e) => reject(new Error(`${step.cmd}: ${e.message}`)));
-        child.once("spawn", () => {
-          child.unref();
-          resolve();
-        });
-      });
-      continue;
-    }
-    const res = spawnSync(exe, args, {
-      input: step.input,
-      encoding: "utf8",
-      windowsHide: true,
-      timeout: step.timeoutMs ?? 10_000,
-    });
-    if (res.error) throw new Error(`${step.cmd}: ${res.error.message}`);
-    if (res.status !== 0) {
-      throw new Error(`${step.cmd}: ${(res.stderr || "").trim() || `exit ${res.status}`}`);
+  try {
+    for (const step of steps) {
+      id = await runStep(step, id);
+      if (step.undo) undos.unshift(step.undo);
     }
-    if (step.captureId) {
-      id = step.captureId(res.stdout ?? "");
-      if (!id) throw new Error(`${step.cmd}: unexpected output`);
+  } catch (e) {
+    for (const undo of undos) {
+      await runStep(undo, id).catch(() => undefined);
     }
+    throw e;
+  }
+}
+
+/** CLI error text, unwrapping JSON errors like herdr's `{"error":{"message":…}}`. */
+function errorText(out: string): string {
+  const text = out.trim();
+  try {
+    const msg = JSON.parse(text)?.error?.message;
+    if (typeof msg === "string") return msg;
+  } catch {
+    // not JSON
+  }
+  return text;
+}
+
+async function runStep(step: LaunchStep, id: string | undefined): Promise<string | undefined> {
+  const { spawn } = await import("node:child_process");
+  const args = step.args.map((a) => (id !== undefined ? a.replaceAll("{id}", id) : a));
+  const exe = Bun.which(step.cmd) ?? step.cmd;
+  if (step.detached) {
+    await new Promise<void>((resolve, reject) => {
+      const child = spawn(exe, args, { detached: true, stdio: "ignore", windowsHide: true });
+      child.once("error", (e) => reject(new Error(`${step.cmd}: ${e.message}`)));
+      child.once("spawn", () => {
+        child.unref();
+        resolve();
+      });
+    });
+    return id;
+  }
+  const { status, stdout, stderr } = await new Promise<{
+    status: number | null;
+    stdout: string;
+    stderr: string;
+  }>((resolve, reject) => {
+    const child = spawn(exe, args, { windowsHide: true });
+    let out = "";
+    let err = "";
+    child.stdout?.on("data", (d) => (out += d));
+    child.stderr?.on("data", (d) => (err += d));
+    const timeoutMs = step.timeoutMs ?? 10_000;
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`${step.cmd}: timed out after ${Math.round(timeoutMs / 1000)}s`));
+    }, timeoutMs);
+    child.once("error", (e) => {
+      clearTimeout(timer);
+      reject(new Error(`${step.cmd}: ${e.message}`));
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve({ status: code, stdout: out, stderr: err });
+    });
+    if (step.input !== undefined) child.stdin?.end(step.input);
+    else child.stdin?.end();
+  });
+  if (status !== 0) {
+    throw new Error(`${step.cmd}: ${errorText(stderr) || errorText(stdout) || `exit ${status}`}`);
+  }
+  if (step.captureId) {
+    const captured = step.captureId(stdout);
+    if (!captured) throw new Error(`${step.cmd}: unexpected output`);
+    return captured;
   }
+  return id;
 }

package/src/store/agent-adapters/claude-code.ts

@@ -333,6 +333,7 @@ function buildSession(
     gitBranch: parsed.gitBranch,
     model: parsed.model,
     resumeCommand: `claude --resume ${jsonl.sessionId}`,
+    resumeArgv: ["claude", "--resume", jsonl.sessionId],
   };
 }
 

package/src/store/agent-adapters/codex.ts

@@ -389,6 +389,7 @@ export function createCodexAdapter(codexHome = defaultCodexHome()): AgentAdapter
         gitBranch: parsed.gitBranch ?? row?.git_branch ?? undefined,
         model: parsed.model ?? row?.model ?? undefined,
         resumeCommand: `codex resume ${f.threadId}`,
+        resumeArgv: ["codex", "resume", f.threadId],
       });
     }
     // Drop cache entries for files that disappeared (archived / deleted).

package/src/store/agent-adapters/opencode.ts

@@ -178,6 +178,7 @@ export function readOpenCodeSessions(dbPath: string, now: number): AgentSession[
         // Assistant messages carry `modelID`; user messages `model.modelID`.
         model: lastData?.modelID ?? lastData?.model?.modelID,
         resumeCommand: `opencode --session ${s.id}`,
+        resumeArgv: ["opencode", "--session", s.id],
       } satisfies AgentSession;
     });
   } finally {

package/src/store/agent-adapters/pi.ts

@@ -238,6 +238,7 @@ export function createPiAdapter(sessionsDir = defaultPiSessionsDir()): AgentAdap
         lastAssistant: p.lastAssistant,
         model: p.model,
         resumeCommand: `pi --session ${sessionId}`,
+        resumeArgv: ["pi", "--session", sessionId],
       };
     });
     const live = new Set(files.map((f) => f.path));

package/src/store/agents.ts

@@ -13,6 +13,13 @@ import { resolve, sep } from "node:path";
 import chokidar from "chokidar";
 import { createSignal } from "solid-js";
 
+import {
+  linkHerdrSessions,
+  type HerdrLink,
+  type HerdrSnapshot,
+  type HerdrSource,
+} from "~/store/herdr";
+
 /** Threshold: session untouched longer than this is "archived" (won't show in compact list). */
 export const DORMANT_AFTER_MS = 7 * 86_400 * 1000;
 
@@ -30,7 +37,11 @@ export const HARNESS: Record<AgentProvider, { code: string; name: string }> = {
 export type AgentsFilter = "all" | AgentProvider;
 
 export type AgentStatus =
+  /** Waiting for you (permission/question) — known only via herdr. */
+  | "live-blocked"
   | "live-busy"
+  /** Finished its turn, not looked at yet — known only via herdr. */
+  | "live-done"
   | "live-idle"
   /** Looks busy, but stopped updating — the process likely crashed. */
   | "stale"
@@ -58,6 +69,10 @@ export interface AgentSession {
   model?: string;
   /** Shell command that resumes this session when run from `cwd`. */
   resumeCommand: string;
+  /** Same, as argv (`[binary, ...args]`) — for launchers that start the agent directly. */
+  resumeArgv: string[];
+  /** Set when the session is open in a herdr pane. */
+  herdr?: HerdrLink;
 }
 
 /** One agent CLI's session source. */
@@ -109,18 +124,32 @@ export function formatAge(ts: number, now: number): string {
 }
 
 const STATUS_RANK: Record<AgentStatus, number> = {
-  "live-busy": 0,
-  "live-idle": 1,
-  "stale": 2,
-  "dormant": 3,
-  "archived": 4,
+  "live-blocked": 0,
+  "live-busy": 1,
+  "live-done": 2,
+  "live-idle": 3,
+  "stale": 4,
+  "dormant": 5,
+  "archived": 6,
 };
 
+/** Is the agent process running (as far as we can tell)? */
+export function isLive(status: AgentStatus): boolean {
+  return status.startsWith("live-");
+}
+
+/**
+ * Most recently active first; status only breaks ties. Archived sessions
+ * always go last — the dashboard strip hides them and relies on that to keep
+ * cursor indices aligned with the full list.
+ */
 export function sortSessions(arr: AgentSession[]): AgentSession[] {
   return arr.slice().sort((a, b) => {
-    const r = STATUS_RANK[a.status] - STATUS_RANK[b.status];
-    if (r !== 0) return r;
-    return b.lastActivityMs - a.lastActivityMs;
+    const archived = Number(a.status === "archived") - Number(b.status === "archived");
+    if (archived !== 0) return archived;
+    const recency = b.lastActivityMs - a.lastActivityMs;
+    if (recency !== 0) return recency;
+    return STATUS_RANK[a.status] - STATUS_RANK[b.status];
   });
 }
 
@@ -128,6 +157,8 @@ export function sortSessions(arr: AgentSession[]): AgentSession[] {
 
 export interface AgentsStore {
   sessions: () => AgentSession[];
+  /** Latest herdr snapshot (undefined without herdr). */
+  herdr: () => HerdrSnapshot | undefined;
   refresh: () => void;
   dispose: () => Promise<void>;
 }
@@ -148,7 +179,10 @@ const MISSING_PATH_POLL_MS = 5000;
  */
 export function createAgentsStore(
   adapters: AgentAdapter[],
-  { missingPathPollMs = MISSING_PATH_POLL_MS } = {},
+  {
+    missingPathPollMs = MISSING_PATH_POLL_MS,
+    herdr,
+  }: { missingPathPollMs?: number; herdr?: HerdrSource } = {},
 ): AgentsStore {
   const [sessions, setSessions] = createSignal<AgentSession[]>([]);
   const byAdapter = new Map<AgentAdapter, AgentSession[]>();
@@ -162,8 +196,10 @@ export function createAgentsStore(
   }
 
   function publish(): void {
-    setSessions(sortSessions([...byAdapter.values()].flat()));
+    const all = [...byAdapter.values()].flat();
+    setSessions(sortSessions(linkHerdrSessions(all, herdr?.snapshot())));
   }
+  herdr?.onChange(publish);
 
   function refresh(): void {
     const now = Date.now();
@@ -231,8 +267,9 @@ export function createAgentsStore(
   async function dispose() {
     if (debounceTimer) clearTimeout(debounceTimer);
     clearInterval(missingPoll);
+    herdr?.dispose();
     await watcher.close();
   }
 
-  return { sessions, refresh, dispose };
+  return { sessions, herdr: () => herdr?.snapshot(), refresh, dispose };
 }

package/src/store/herdr.ts

@@ -0,0 +1,272 @@
+/**
+ * herdr (terminal workspace manager for coding agents) link.
+ *
+ * `herdr api snapshot` lists every pane with the agent running in it, that
+ * agent's state and — when herdr's integration for that agent is installed —
+ * the agent session it's on (`{kind: "id"}` for Claude/OpenCode, `{kind:
+ * "path"}` for Pi). tuiboard polls it and links panes to its own sessions, so
+ * a session open in herdr shows herdr's live state (including "idle" and
+ * "waiting for you", which the on-disk formats can't tell) and where it lives.
+ *
+ * Optional by design: no `herdr` on PATH, no server, or an unexpected answer
+ * all just mean "no links".
+ */
+
+import type { AgentProvider, AgentSession, AgentStatus } from "~/store/agents";
+
+export type HerdrAgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+
+export interface HerdrPane {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+  agent?: string;
+  status: HerdrAgentStatus;
+  cwd: string;
+  session?: { kind: "id" | "path"; value: string };
+}
+
+export interface HerdrSnapshot {
+  panes: HerdrPane[];
+  focusedWorkspaceId?: string;
+  tabs: Map<string, { label: string; number: number }>;
+  workspaces: Map<string, { label: string; number: number }>;
+}
+
+/** The `herdr` binary to drive: the one herdr itself advertises, else PATH. */
+export function herdrBin(env: Record<string, string | undefined> = process.env): string | undefined {
+  return env.HERDR_BIN_PATH || Bun.which("herdr") || undefined;
+}
+
+/** Where a session is open in herdr. */
+export interface HerdrLink {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+  workspaceLabel: string;
+  tabLabel: string;
+  tabNumber: number;
+  status: HerdrAgentStatus;
+  /** How the pane was matched; `cwd` = no session identity from herdr. */
+  matchedBy: "id" | "path" | "cwd";
+  /** herdr's name for the agent (for `herdr integration install <name>`). */
+  agent: string;
+}
+
+/** `herdr blits · tab 3` */
+export function herdrPlace(l: HerdrLink): string {
+  return `herdr ${l.workspaceLabel || l.workspaceId} · tab ${l.tabNumber || l.tabId}`;
+}
+
+/** herdr agent name ↔ tuiboard provider. */
+export const HERDR_AGENT: Record<AgentProvider, string> = {
+  "claude-code": "claude",
+  codex: "codex",
+  opencode: "opencode",
+  pi: "pi",
+};
+const PROVIDER_OF: Record<string, AgentProvider> = Object.fromEntries(
+  Object.entries(HERDR_AGENT).map(([p, a]) => [a, p as AgentProvider]),
+);
+
+const STATUSES = new Set<HerdrAgentStatus>(["idle", "working", "blocked", "done", "unknown"]);
+
+/** Parse `herdr api snapshot` output. Returns undefined if it isn't one. */
+export function parseHerdrSnapshot(raw: string): HerdrSnapshot | undefined {
+  let data: any;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  const snap = data?.result?.snapshot ?? data?.snapshot;
+  if (!snap || !Array.isArray(snap.panes)) return undefined;
+  const panes: HerdrPane[] = [];
+  for (const p of snap.panes) {
+    if (typeof p?.pane_id !== "string") continue;
+    const s = p.agent_session;
+    panes.push({
+      paneId: p.pane_id,
+      tabId: String(p.tab_id ?? ""),
+      workspaceId: String(p.workspace_id ?? ""),
+      agent: typeof p.agent === "string" ? p.agent : undefined,
+      status: STATUSES.has(p.agent_status) ? p.agent_status : "unknown",
+      cwd: String(p.cwd ?? ""),
+      session:
+        s && (s.kind === "id" || s.kind === "path") && typeof s.value === "string"
+          ? { kind: s.kind, value: s.value }
+          : undefined,
+    });
+  }
+  const byId = (list: unknown, key: string) =>
+    new Map<string, { label: string; number: number }>(
+      (Array.isArray(list) ? list : [])
+        .filter((x: any) => typeof x?.[key] === "string")
+        .map((x: any) => [x[key], { label: String(x.label ?? ""), number: Number(x.number ?? 0) }]),
+    );
+  return {
+    panes,
+    focusedWorkspaceId: typeof snap.focused_workspace_id === "string" ? snap.focused_workspace_id : undefined,
+    tabs: byId(snap.tabs, "tab_id"),
+    workspaces: byId(snap.workspaces, "workspace_id"),
+  };
+}
+
+/** Compare paths across the formats agents store (`C:/x`, `C:\x`, lossy case). */
+export function samePath(a: string, b: string): boolean {
+  const norm = (p: string) => {
+    let s = p.replaceAll("\\", "/").replace(/\/+$/, "");
+    if (/^[A-Za-z]:/.test(s)) s = s.toLowerCase();
+    return s;
+  };
+  if (!a || !b) return false;
+  const x = norm(a);
+  const y = norm(b);
+  return x === y || x.toLowerCase() === y.toLowerCase();
+}
+
+const STATUS_FROM_HERDR: Partial<Record<HerdrAgentStatus, AgentStatus>> = {
+  working: "live-busy",
+  blocked: "live-blocked",
+  done: "live-done",
+  idle: "live-idle",
+};
+
+/**
+ * Attach herdr links to sessions and let herdr's state win where it knows
+ * it. Panes reporting a session id/path are matched first; panes without one
+ * fall back to "most recent session of that agent in that directory".
+ */
+export function linkHerdrSessions(
+  sessions: AgentSession[],
+  snap: HerdrSnapshot | undefined,
+): AgentSession[] {
+  if (!snap || snap.panes.length === 0) return sessions;
+  const links = new Map<AgentSession, HerdrLink>();
+  const link = (s: AgentSession, p: HerdrPane, matchedBy: HerdrLink["matchedBy"]) => {
+    const tab = snap.tabs.get(p.tabId);
+    links.set(s, {
+      paneId: p.paneId,
+      tabId: p.tabId,
+      workspaceId: p.workspaceId,
+      workspaceLabel: snap.workspaces.get(p.workspaceId)?.label ?? "",
+      tabLabel: tab?.label ?? "",
+      tabNumber: tab?.number ?? 0,
+      status: p.status,
+      matchedBy,
+      agent: p.agent ?? "",
+    });
+  };
+  const agentPanes = snap.panes.filter((p) => p.agent && PROVIDER_OF[p.agent]);
+
+  for (const p of agentPanes) {
+    if (!p.session) continue;
+    const provider = PROVIDER_OF[p.agent!];
+    const { kind, value } = p.session;
+    const s = sessions.find(
+      (x) =>
+        x.provider === provider &&
+        !links.has(x) &&
+        (kind === "id"
+          ? x.sessionId === value
+          : samePath(x.sourcePath, value) || value.includes(x.sessionId)),
+    );
+    if (s) link(s, p, kind);
+  }
+  for (const p of agentPanes) {
+    if (p.session) continue;
+    const provider = PROVIDER_OF[p.agent!];
+    const s = sessions
+      .filter((x) => x.provider === provider && !links.has(x) && samePath(x.cwd, p.cwd))
+      .sort((a, b) => b.lastActivityMs - a.lastActivityMs)[0];
+    if (s) link(s, p, "cwd");
+  }
+
+  if (links.size === 0) return sessions;
+  return sessions.map((s) => {
+    const l = links.get(s);
+    if (!l) return s;
+    return { ...s, herdr: l, status: STATUS_FROM_HERDR[l.status] ?? s.status };
+  });
+}
+
+/** Agent status glyph style — the same two herdr offers. */
+export type IndicatorStyle = "dots" | "symbols";
+
+/** One synchronous snapshot, for CLI/dev scripts. */
+export function readHerdrSnapshotOnce(bin = Bun.which("herdr") ?? undefined): HerdrSnapshot | undefined {
+  if (!bin) return undefined;
+  try {
+    const res = Bun.spawnSync([bin, "api", "snapshot"], { stdout: "pipe", stderr: "ignore", timeout: 5000 });
+    return res.exitCode === 0 ? parseHerdrSnapshot(res.stdout.toString()) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── Polling source ─────────────────────────────────────────────────────────
+
+export interface HerdrSource {
+  snapshot: () => HerdrSnapshot | undefined;
+  onChange: (cb: () => void) => void;
+  dispose: () => void;
+}
+
+export const HERDR_POLL_MS = 2000;
+
+/**
+ * Poll `herdr api snapshot` in the background. Inert when herdr isn't on
+ * PATH (or `bin: null`). A failing call clears the snapshot (server gone)
+ * without noise.
+ */
+export function createHerdrSource(
+  { pollMs = HERDR_POLL_MS, bin = Bun.which("herdr") }: { pollMs?: number; bin?: string | null } = {},
+): HerdrSource {
+  let current: HerdrSnapshot | undefined;
+  let lastRaw = "";
+  const listeners: (() => void)[] = [];
+  if (!bin) return { snapshot: () => undefined, onChange: () => {}, dispose: () => {} };
+
+  let inFlight = false;
+  let disposed = false;
+  const poll = async () => {
+    if (inFlight || disposed) return;
+    inFlight = true;
+    try {
+      const proc = Bun.spawn([bin, "api", "snapshot"], {
+        stdout: "pipe",
+        stderr: "ignore",
+        windowsHide: true,
+      });
+      const timer = setTimeout(() => proc.kill(), 5000);
+      const out = await new Response(proc.stdout).text();
+      clearTimeout(timer);
+      const code = await proc.exited;
+      const snap = code === 0 ? parseHerdrSnapshot(out) : undefined;
+      // Only the parts we use decide whether anything changed.
+      const key = snap
+        ? JSON.stringify([snap.panes, [...snap.tabs], [...snap.workspaces]])
+        : "";
+      if (key !== lastRaw && !disposed) {
+        lastRaw = key;
+        current = snap;
+        for (const cb of listeners) cb();
+      }
+    } catch {
+      // herdr vanished mid-call — try again next tick
+    } finally {
+      inFlight = false;
+    }
+  };
+  void poll();
+  const timer = setInterval(poll, pollMs);
+  timer.unref?.();
+  return {
+    snapshot: () => current,
+    onChange: (cb) => listeners.push(cb),
+    dispose: () => {
+      disposed = true;
+      clearInterval(timer);
+    },
+  };
+}

package/src/store/index.ts

@@ -38,6 +38,7 @@ import {
   type AgentsStore,
 } from "./agents";
 import { AGENT_ADAPTERS } from "./agent-adapters";
+import { createHerdrSource } from "./herdr";
 import {
   createCalendarStore,
   createGoogleEvent,
@@ -380,7 +381,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
   // the agents zone is disabled we skip the watcher entirely (no session reads
   // at all) and hand back an inert stub.
   const agentsStore: AgentsStore = enabledZones.agents
-    ? createAgentsStore(AGENT_ADAPTERS)
+    ? createAgentsStore(AGENT_ADAPTERS, { herdr: createHerdrSource() })
     : noopAgentsStore();
   // Calendar feeds (read-only) merged into the Agenda zone. Skipped entirely
   // (no network) when the agenda zone is disabled.
@@ -1732,6 +1733,7 @@ export function createTuiStore({ config }: CreateStoreOptions) {
     activeBoard,
     agents: agentsStore,
     agentSessions,
+    agentIndicators: config.statusIndicators,
     cycleAgentsFilter,
     setLastLaunch,
     calendar: calendarStore,
@@ -1819,7 +1821,7 @@ export type TuiStore = ReturnType<typeof createTuiStore>;
 /** Inert agents store for when the agents zone is disabled — no chokidar
  *  watcher, no `~/.claude` reads at all. */
 function noopAgentsStore(): AgentsStore {
-  return { sessions: () => [], refresh: () => {}, dispose: async () => {} };
+  return { sessions: () => [], herdr: () => undefined, refresh: () => {}, dispose: async () => {} };
 }
 
 /** Inert calendar store for when the agenda zone is disabled — no fetching. */

package/src/ui/AgentRow.tsx

@@ -16,6 +16,7 @@ import { homedir } from "node:os";
 
 import { layoutCardDetails, layoutCardName, layoutLine } from "~/ui/agent-line";
 import { T } from "~/ui/glyphs";
+import { herdrPlace, type IndicatorStyle } from "~/store/herdr";
 import {
   HARNESS,
   cwdShort,
@@ -27,21 +28,42 @@ import {
 } from "~/store/agents";
 
 const STATUS_COLOR: Record<AgentStatus, string> = {
-  "live-busy": T.today,     // bright accent for actively-running
-  "live-idle": T.scheduled, // warm but quieter
-  "stale":     T.bannerWarn,
-  "dormant":   T.textDim,
-  "archived":  T.textDone,
+  "live-blocked": T.overdue,  // needs you
+  "live-busy":    T.today,    // bright accent for actively-running
+  "live-done":    T.done,     // finished, not looked at yet
+  "live-idle":    T.scheduled, // warm but quieter
+  "stale":        T.bannerWarn,
+  "dormant":      T.textDim,
+  "archived":     T.textDone,
 };
 
-const STATUS_GLYPH: Record<AgentStatus, string> = {
-  "live-busy": "●",
-  "live-idle": "○",
-  "stale":     "△",
-  "dormant":   "·",
-  "archived":  "·",
+/**
+ * herdr's two `status_indicators` styles, copied as-is so the same state reads
+ * the same in both tools. `stale` is tuiboard's own (no herdr equivalent).
+ */
+const STATUS_GLYPH: Record<IndicatorStyle, Record<AgentStatus, string>> = {
+  dots: {
+    "live-blocked": "●",
+    "live-busy":    "●",
+    "live-done":    "●",
+    "live-idle":    "○",
+    "stale":        "△",
+    "dormant":      "·",
+    "archived":     "·",
+  },
+  symbols: {
+    "live-blocked": "×",
+    "live-busy":    "◐",
+    "live-done":    "✓",
+    "live-idle":    "○",
+    "stale":        "△",
+    "dormant":      "·",
+    "archived":     "·",
+  },
 };
 
+
+
 /** One hue per harness so the badge reads before the letters do. */
 export const HARNESS_COLOR: Record<AgentProvider, string> = {
   "claude-code": T.warm,    // orange
@@ -66,6 +88,8 @@ interface AgentRowProps {
   nameMaxChars?: number;
   /** `line` (default) for the dashboard strip, `card` for the fullscreen view. */
   variant?: "line" | "card";
+  /** Status glyph style (default symbols, as in herdr). */
+  indicators?: IndicatorStyle;
   onClick?: () => void;
 }
 
@@ -106,7 +130,15 @@ export function AgentRow(props: AgentRowProps) {
   );
   const cardName = createMemo(() => layoutCardName(displayName(), width()));
   const details = createMemo(() =>
-    layoutCardDetails([model(), props.session.gitBranch, cardCwd(props.session.cwd)], width()),
+    layoutCardDetails(
+      [
+        model(),
+        props.session.herdr && herdrPlace(props.session.herdr),
+        props.session.gitBranch,
+        cardCwd(props.session.cwd),
+      ],
+      width(),
+    ),
   );
 
   // cursor · status glyph · harness badge — shared by both variants.
@@ -115,7 +147,7 @@ export function AgentRow(props: AgentRowProps) {
       {props.cursor ? "▶ " : "  "}
     </span>,
     <span style={{ fg: STATUS_COLOR[props.session.status] }}>
-      {STATUS_GLYPH[props.session.status]}{" "}
+      {STATUS_GLYPH[props.indicators ?? "symbols"][props.session.status]}{" "}
     </span>,
     <span style={{ fg: HARNESS_COLOR[props.session.provider] }}>
       {HARNESS[props.session.provider].code}{" "}

package/src/ui/AgentsBar.tsx

@@ -100,6 +100,7 @@ export function AgentsBar(props: AgentsBarProps) {
             {(session, i) => (
               <box id={agentRowId(i())}>
                 <AgentRow
+                  indicators={props.store.agentIndicators}
                   session={session}
                   cursor={isActive() && i() === agentRow()}
                   nameMaxChars={48}

package/src/ui/Modal.tsx

@@ -24,6 +24,7 @@ import { AGENDA_WIDTH } from "~/ui/layout";
 import { formatHm } from "~/store/timeline";
 import { HARNESS } from "~/store/agents";
 import { HARNESS_COLOR } from "~/ui/AgentRow";
+import { herdrPlace } from "~/store/herdr";
 import type { TuiStore } from "~/store/index";
 import type { PriorityLevel, TimeBlock } from "~/types";
 
@@ -936,6 +937,27 @@ function AgentDetailModal(props: { store: TuiStore; modal: Extract<NonNullable<T
               <span style={{ fg: T.textDim }}>status    </span>
               <span style={{ fg: T.text }}>{s().status}</span>
             </text>
+            <Show when={s().herdr}>
+              {(h: () => NonNullable<ReturnType<typeof s>["herdr"]>) => (
+                <>
+                  <text>
+                    <span style={{ fg: T.textDim }}>herdr     </span>
+                    <span style={{ fg: T.accent }}>{herdrPlace(h())}</span>
+                    <span style={{ fg: T.textDim }}>
+                      {"  "}pane {h().paneId} · {h().status} · matched by {h().matchedBy}
+                    </span>
+                  </text>
+                  <Show when={h().matchedBy === "cwd"}>
+                    <text wrapMode="word">
+                      <span style={{ fg: T.textDim }}>
+                        {"          "}herdr doesn't report which {h().agent} session this pane is on — run
+                        `herdr integration install {h().agent}` for an exact match.
+                      </span>
+                    </text>
+                  </Show>
+                </>
+              )}
+            </Show>
             <text>
               <span style={{ fg: T.textDim }}>cwd       </span>
               <span style={{ fg: T.text }}>{s().cwd}</span>
@@ -1126,7 +1148,8 @@ const HELP_SECTIONS: HelpSection[] = [
     emoji: "🤖",
     title: "Agents zone",
     rows: [
-      ["Enter", "Open (resume) the selected session in a new terminal tab/window"],
+      ["Enter", "Open (resume) the selected session in a new terminal tab/window — or go to it if it's open in herdr"],
+      ["H", "herdr: go to the session, or resume it in a new tab of its project's workspace"],
       ["c", "Copy a 'cd + resume' command for the session"],
       ["o", "Session detail (harness, model, cwd, branch, last prompts, resume cmd)"],
       ["f", "Filter by harness: all → cc Claude Code → cx Codex → oc OpenCode → pi Pi"],

package/src/views/AgentsOnly.tsx

@@ -93,6 +93,7 @@ export function AgentsOnly(props: { store: TuiStore }) {
                     cursor={isActive() && i() === agentRow()}
                     nameMaxChars={120}
                     variant="card"
+                    indicators={props.store.agentIndicators}
                     onClick={() => {
                       props.store.setActiveZone("agents");
                       props.store.setCursor(0, i());