tuiboard 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.2] - 2026-09-17
+
+### Fixed
+- **A calmer Agents list while agents work** (#58).
+  - A failed herdr poll no longer drops every link at once (states briefly
+    reverting, rows jumping); herdr only counts as gone after a few misses.
+  - A Claude Code PID file read mid-write reuses its last good read instead of
+    making the session's state flicker.
+  - Live sessions are ordered by their activity at their last state change,
+    so a working agent moves once when it starts or finishes, not on every
+    write; closed sessions still sort by last activity.
+  - Ages tick on one shared clock and read `now` under a minute instead of
+    jumping through seconds.
+
+## [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
@@ -474,6 +501,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.2]: https://github.com/NazzarenoGiannelli/tuiboard/releases/tag/v0.13.2
+[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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tuiboard",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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.tsx

@@ -148,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 ──────────────────────────────────────────────────────────────
 

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

@@ -207,6 +207,13 @@ export function parseTranscript(content: string): TranscriptParseResult {
 
 // ─── Discovery ──────────────────────────────────────────────────────────────
 
+/**
+ * Last successfully parsed record per PID file. Claude Code rewrites these
+ * files in place, so a read can land mid-write; reusing the previous record
+ * keeps the session's live state from flickering for one scan.
+ */
+const lastGoodPid = new Map<string, { sessionId: string; record: LivePidRecord }>();
+
 function discoverLivePids(): Map<string, LivePidRecord> {
   const out = new Map<string, LivePidRecord>();
   if (!existsSync(SESSIONS_DIR)) return out;
@@ -216,25 +223,32 @@ function discoverLivePids(): Map<string, LivePidRecord> {
   } catch {
     return out;
   }
+  const seen = new Set<string>();
   for (const f of entries) {
     if (!f.endsWith(".json")) continue;
     const path = join(SESSIONS_DIR, f);
+    seen.add(path);
     try {
       const raw = JSON.parse(readFileSync(path, "utf-8"));
       const sid = raw.sessionId;
       if (!sid) continue;
       const stat = statSync(path);
-      out.set(sid, {
+      const record: LivePidRecord = {
         mtimeMs: stat.mtimeMs,
         status: raw.status?.toLowerCase(),
         pid: raw.pid,
         version: raw.version,
         cwd: raw.cwd,
-      });
+      };
+      lastGoodPid.set(path, { sessionId: sid, record });
+      out.set(sid, record);
     } catch {
-      // ignore — malformed PID files happen during writes
+      // Mid-write (or vanished): fall back to the last good read of this file.
+      const prev = lastGoodPid.get(path);
+      if (prev) out.set(prev.sessionId, prev.record);
     }
   }
+  for (const path of lastGoodPid.keys()) if (!seen.has(path)) lastGoodPid.delete(path);
   return out;
 }
 

package/src/store/agents.ts

@@ -73,6 +73,11 @@ export interface AgentSession {
   resumeArgv: string[];
   /** Set when the session is open in a herdr pane. */
   herdr?: HerdrLink;
+  /**
+   * Position in the list (newest first). Set by the store: last activity for
+   * closed sessions, last state change for live ones — see withSortKeys.
+   */
+  sortKeyMs?: number;
 }
 
 /** One agent CLI's session source. */
@@ -113,11 +118,11 @@ export function filterSessions(arr: AgentSession[], filter: AgentsFilter): Agent
   return filter === "all" ? arr : arr.filter((s) => s.provider === filter);
 }
 
-/** Compact human-readable age. Mirrors av.py `_fmt_age`. */
+/** Compact human-readable age; under a minute reads `now` (no ticking seconds). */
 export function formatAge(ts: number, now: number): string {
   if (!ts) return "—";
   const delta = (now - ts) / 1000;
-  if (delta < 60) return `${Math.floor(delta)}s`;
+  if (delta < 60) return "now";
   if (delta < 3600) return `${Math.floor(delta / 60)}m`;
   if (delta < 86_400) return `${Math.floor(delta / 3600)}h`;
   return `${Math.floor(delta / 86_400)}d`;
@@ -144,15 +149,48 @@ export function isLive(status: AgentStatus): boolean {
  * cursor indices aligned with the full list.
  */
 export function sortSessions(arr: AgentSession[]): AgentSession[] {
+  const key = (s: AgentSession) => s.sortKeyMs ?? s.lastActivityMs;
   return arr.slice().sort((a, b) => {
     const archived = Number(a.status === "archived") - Number(b.status === "archived");
     if (archived !== 0) return archived;
-    const recency = b.lastActivityMs - a.lastActivityMs;
+    const recency = key(b) - key(a);
     if (recency !== 0) return recency;
     return STATUS_RANK[a.status] - STATUS_RANK[b.status];
   });
 }
 
+export interface StateMemory {
+  status: AgentStatus;
+  since: number;
+}
+
+/**
+ * Sort keys that don't churn. A working agent writes its session file all
+ * the time; sorting by that made rows swap on every write. Live sessions are
+ * keyed by their last activity *as of their last state change* — they move
+ * once when they start or finish (both write), not on every write — and
+ * closed ones by their last activity. Using activity rather than the wall
+ * clock means a "change" that is only new information (herdr answering after
+ * the first scan) doesn't reshuffle the list.
+ * `memory` carries state across refreshes (keyed by provider + session id).
+ */
+export function withSortKeys(
+  sessions: AgentSession[],
+  memory: Map<string, StateMemory>,
+): AgentSession[] {
+  const seen = new Set<string>();
+  const out = sessions.map((s) => {
+    const id = `${s.provider}:${s.sessionId}`;
+    seen.add(id);
+    const prev = memory.get(id);
+    const since = prev && prev.status === s.status ? prev.since : s.lastActivityMs;
+    memory.set(id, { status: s.status, since });
+    return { ...s, sortKeyMs: isLive(s.status) ? since : s.lastActivityMs };
+  });
+  for (const id of memory.keys()) if (!seen.has(id)) memory.delete(id);
+  return out;
+}
+
 // ─── Reactive store ─────────────────────────────────────────────────────────
 
 export interface AgentsStore {
@@ -195,9 +233,11 @@ export function createAgentsStore(
     }
   }
 
+  const stateMemory = new Map<string, StateMemory>();
   function publish(): void {
     const all = [...byAdapter.values()].flat();
-    setSessions(sortSessions(linkHerdrSessions(all, herdr?.snapshot())));
+    const linked = linkHerdrSessions(all, herdr?.snapshot());
+    setSessions(sortSessions(withSortKeys(linked, stateMemory)));
   }
   herdr?.onChange(publish);
 

package/src/store/herdr.ts

@@ -213,6 +213,11 @@ export interface HerdrSource {
 }
 
 export const HERDR_POLL_MS = 2000;
+/**
+ * Consecutive failed polls before herdr counts as gone. A single slow or
+ * failed call used to drop every link at once, making states flicker.
+ */
+export const HERDR_MISSES_BEFORE_CLEAR = 3;
 
 /**
  * Poll `herdr api snapshot` in the background. Inert when herdr isn't on
@@ -220,7 +225,11 @@ export const HERDR_POLL_MS = 2000;
  * without noise.
  */
 export function createHerdrSource(
-  { pollMs = HERDR_POLL_MS, bin = Bun.which("herdr") }: { pollMs?: number; bin?: string | null } = {},
+  {
+    pollMs = HERDR_POLL_MS,
+    bin = Bun.which("herdr"),
+    missesBeforeClear = HERDR_MISSES_BEFORE_CLEAR,
+  }: { pollMs?: number; bin?: string | null; missesBeforeClear?: number } = {},
 ): HerdrSource {
   let current: HerdrSnapshot | undefined;
   let lastRaw = "";
@@ -229,6 +238,7 @@ export function createHerdrSource(
 
   let inFlight = false;
   let disposed = false;
+  let misses = 0;
   const poll = async () => {
     if (inFlight || disposed) return;
     inFlight = true;
@@ -242,7 +252,9 @@ export function createHerdrSource(
       const out = await new Response(proc.stdout).text();
       clearTimeout(timer);
       const code = await proc.exited;
-      const snap = code === 0 ? parseHerdrSnapshot(out) : undefined;
+      let snap = code === 0 ? parseHerdrSnapshot(out) : undefined;
+      if (snap) misses = 0;
+      else if (++misses < missesBeforeClear) snap = current; // ride out a blip
       // Only the parts we use decide whether anything changed.
       const key = snap
         ? JSON.stringify([snap.panes, [...snap.tabs], [...snap.workspaces]])
@@ -253,7 +265,8 @@ export function createHerdrSource(
         for (const cb of listeners) cb();
       }
     } catch {
-      // herdr vanished mid-call — try again next tick
+      // herdr vanished mid-call — counts as a miss, try again next tick
+      misses++;
     } finally {
       inFlight = false;
     }

package/src/ui/AgentRow.tsx

@@ -15,6 +15,7 @@ import { Show, createMemo, createSignal, onMount } from "solid-js";
 import { homedir } from "node:os";
 
 import { layoutCardDetails, layoutCardName, layoutLine } from "~/ui/agent-line";
+import { clockNow } from "~/ui/clock";
 import { T } from "~/ui/glyphs";
 import { herdrPlace, type IndicatorStyle } from "~/store/herdr";
 import {
@@ -95,7 +96,7 @@ interface AgentRowProps {
 
 export function AgentRow(props: AgentRowProps) {
   const ageStr = createMemo(() =>
-    formatAge(props.session.lastActivityMs, Date.now()),
+    formatAge(props.session.lastActivityMs, clockNow()),
   );
   const nameMax = () => props.nameMaxChars ?? 40;
   const displayName = createMemo(() => {

package/src/ui/AgentsBar.tsx

@@ -8,9 +8,10 @@
  * visible. Clicking a row sets activeZone + agent cursor.
  */
 
-import { For, Show, createEffect, createMemo } from "solid-js";
+import { Index, Show, createEffect, createMemo } from "solid-js";
 
 import { AgentRow } from "~/ui/AgentRow";
+import { useStickyAgentCursor } from "~/ui/agent-cursor";
 import { T } from "~/ui/glyphs";
 import { HARNESS } from "~/store/agents";
 import type { TuiStore } from "~/store/index";
@@ -42,6 +43,7 @@ export function AgentsBar(props: AgentsBarProps) {
   };
 
   let scrollBoxRef: ScrollBoxLike | undefined;
+  useStickyAgentCursor(props.store, allShown);
 
   // Keep the cursor row visible as j/k moves it (mouse wheel scrolls freely
   // via the scrollbox itself). setTimeout(0) waits for layout to commit.
@@ -96,22 +98,23 @@ export function AgentsBar(props: AgentsBarProps) {
             scrollbarOptions: { visible: false },
           }}
         >
-          <For each={allShown()}>
+          {/* <Index>: stable rows by position — see AgentsOnly (#52). */}
+          <Index each={allShown()}>
             {(session, i) => (
-              <box id={agentRowId(i())}>
+              <box id={agentRowId(i)}>
                 <AgentRow
                   indicators={props.store.agentIndicators}
-                  session={session}
-                  cursor={isActive() && i() === agentRow()}
+                  session={session()}
+                  cursor={isActive() && i === agentRow()}
                   nameMaxChars={48}
                   onClick={() => {
                     props.store.setActiveZone("agents");
-                    props.store.setCursor(0, i());
+                    props.store.setCursor(0, i);
                   }}
                 />
               </box>
             )}
-          </For>
+          </Index>
         </scrollbox>
       </Show>
     </box>

package/src/ui/agent-cursor.ts

@@ -0,0 +1,49 @@
+/**
+ * Keep the Agents cursor on the same session while the list reorders.
+ *
+ * The cursor is a row index (`ui.row`), and sessions move all the time —
+ * sorted by recency, a new one lands on top, a working one climbs. Without
+ * this, the highlighted row silently became a different session and Enter /
+ * H / c acted on it. Call once inside the component that renders the list.
+ */
+
+import { createEffect } from "solid-js";
+
+import type { AgentSession } from "~/store/agents";
+import type { TuiStore } from "~/store/index";
+
+/** Pure decision, for tests: where the cursor should be after a change. */
+export function followSelection(
+  prev: { list: readonly AgentSession[] | undefined; row: number; id: string | undefined },
+  list: readonly AgentSession[],
+  row: number,
+): number {
+  // Only a list change (not a keypress) may move the cursor.
+  if (list === prev.list || row !== prev.row || !prev.id) return row;
+  if (list[row]?.sessionId === prev.id) return row;
+  const idx = list.findIndex((s) => s.sessionId === prev.id);
+  return idx >= 0 ? idx : Math.min(row, Math.max(0, list.length - 1));
+}
+
+export function useStickyAgentCursor(store: TuiStore, list: () => readonly AgentSession[]): void {
+  const prev: { list: readonly AgentSession[] | undefined; row: number; id: string | undefined } = {
+    list: undefined,
+    row: -1,
+    id: undefined,
+  };
+  createEffect(() => {
+    const items = list();
+    const row = store.state.ui.row;
+    // `ui.row` belongs to whichever zone is active.
+    if (store.state.ui.activeZone !== "agents") {
+      prev.list = undefined;
+      prev.id = undefined;
+      return;
+    }
+    const next = followSelection(prev, items, row);
+    prev.list = items;
+    prev.row = next;
+    prev.id = items[next]?.sessionId;
+    if (next !== row) store.setCursor(0, next);
+  });
+}

package/src/ui/clock.ts

@@ -0,0 +1,21 @@
+/**
+ * A shared, coarse clock for relative times ("5m", "3h"). Rows used to compute
+ * their age only when their data changed, so ages jumped irregularly while
+ * agents worked; one timer for the whole UI keeps them ticking evenly.
+ */
+
+import { createSignal } from "solid-js";
+
+export const CLOCK_TICK_MS = 30_000;
+
+const [now, setNow] = createSignal(Date.now());
+let timer: ReturnType<typeof setInterval> | undefined;
+
+/** Current time, updated every CLOCK_TICK_MS. Starts on first use. */
+export function clockNow(): number {
+  if (!timer) {
+    timer = setInterval(() => setNow(Date.now()), CLOCK_TICK_MS);
+    timer.unref?.();
+  }
+  return now();
+}

package/src/views/AgentsOnly.tsx

@@ -5,9 +5,10 @@
  * scrollChildIntoView (same trick used in BoardView for active columns).
  */
 
-import { For, Show, createEffect, createMemo } from "solid-js";
+import { Index, Show, createEffect, createMemo } from "solid-js";
 
 import { AgentRow } from "~/ui/AgentRow";
+import { useStickyAgentCursor } from "~/ui/agent-cursor";
 import { T } from "~/ui/glyphs";
 import { HARNESS } from "~/store/agents";
 import type { TuiStore } from "~/store/index";
@@ -16,10 +17,9 @@ interface ScrollBoxLike {
   scrollChildIntoView(id: string): void;
 }
 
-function rowId(sessionId: string): string {
-  // Sanitize sessionId for use as an OpenTUI box id. UUIDs are already safe
-  // (alphanumeric + dashes), but defensive belt-and-braces doesn't hurt.
-  return `tuiboard-agent-${sessionId.replace(/[^a-zA-Z0-9]/g, "_")}`;
+/** Rows are keyed by position (see the <Index> below), and so are their ids. */
+function rowId(index: number): string {
+  return `tuiboard-agent-card-${index}`;
 }
 
 export function AgentsOnly(props: { store: TuiStore }) {
@@ -29,17 +29,17 @@ export function AgentsOnly(props: { store: TuiStore }) {
   const filter = () => props.store.state.ui.agentsFilter;
   const filterTag = () => (filter() === "all" ? "" : ` · ${HARNESS[filter() as keyof typeof HARNESS].code}`);
   let scrollBoxRef: ScrollBoxLike | undefined;
+  useStickyAgentCursor(props.store, sessions);
 
   // Auto-scroll the list so the active row is visible. setTimeout(0) waits
   // for OpenTUI to finish layout before requesting scroll.
   createEffect(() => {
     const row = agentRow();
     if (!isActive() || !scrollBoxRef) return;
-    const target = sessions()[row];
-    if (!target) return;
+    if (row >= sessions().length) return;
     setTimeout(() => {
       try {
-        scrollBoxRef?.scrollChildIntoView(rowId(target.sessionId));
+        scrollBoxRef?.scrollChildIntoView(rowId(row));
       } catch {
         // Child not mounted yet — harmless.
       }
@@ -85,23 +85,29 @@ export function AgentsOnly(props: { store: TuiStore }) {
               scrollbarOptions: { visible: false },
             }}
           >
-            <For each={sessions()}>
+            {/*
+              <Index>, not <For>: one stable row per position whose data
+              updates in place. Sessions are re-created on every refresh and
+              reorder by recency, and moving children inside OpenTUI's
+              scrollbox left stale/duplicate rows on screen (#52).
+            */}
+            <Index each={sessions()}>
               {(session, i) => (
-                <box id={rowId(session.sessionId)}>
+                <box id={rowId(i)}>
                   <AgentRow
-                    session={session}
-                    cursor={isActive() && i() === agentRow()}
+                    session={session()}
+                    cursor={isActive() && i === agentRow()}
                     nameMaxChars={120}
                     variant="card"
                     indicators={props.store.agentIndicators}
                     onClick={() => {
                       props.store.setActiveZone("agents");
-                      props.store.setCursor(0, i());
+                      props.store.setCursor(0, i);
                     }}
                   />
                 </box>
               )}
-            </For>
+            </Index>
           </scrollbox>
         </Show>
       </box>