@towles/tool 0.0.128 → 0.0.130

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.128",
+  "version": "0.0.130",
   "description": "One off quality of life scripts that I use on a daily basis.",
   "homepage": "https://github.com/ChrisTowles/towles-tool#readme",
   "bugs": {

package/packages/agentboard/apps/tui/src/components/SessionCard.tsx

@@ -232,6 +232,15 @@ function AgentRow(props: AgentRowProps) {
 
   const statusText = () => STATUS_TEXT[props.agent.status];
 
+  const isCacheExpired = () => {
+    const details = props.agent.details;
+    if (!details) return false;
+    const now = props.now();
+    if (details.cacheExpiresAt != null) return now > details.cacheExpiresAt;
+    if (details.lastActivityAt != null) return now - details.lastActivityAt > 60 * 60 * 1000;
+    return false;
+  };
+
   let flashTimer: ReturnType<typeof setTimeout> | null = null;
   const triggerFlash = () => {
     setIsFlash(true);
@@ -324,6 +333,12 @@ function AgentRow(props: AgentRowProps) {
           );
         }}
       </Show>
+
+      <Show when={isCacheExpired()}>
+        <text truncate>
+          <span style={{ fg: P().overlay0, attributes: DIM }}>cache expired</span>
+        </text>
+      </Show>
     </box>
   );
 }

package/packages/agentboard/packages/runtime/src/agents/tracker.test.ts

@@ -152,6 +152,109 @@ describe("AgentTracker", () => {
     });
   });
 
+  describe("pruneStale", () => {
+    const TWELVE_HOURS = 12 * 60 * 60 * 1000;
+
+    it("prunes waiting agents older than threshold", () => {
+      tracker.applyEvent(makeEvent({ status: "waiting", ts: Date.now() - TWELVE_HOURS - 1000 }));
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).toBeNull();
+    });
+
+    it("prunes running agents older than threshold", () => {
+      tracker.applyEvent(makeEvent({ status: "running", ts: Date.now() - TWELVE_HOURS - 1000 }));
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).toBeNull();
+    });
+
+    it("leaves fresh agents alone", () => {
+      tracker.applyEvent(makeEvent({ status: "waiting", ts: Date.now() - 1000 }));
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).not.toBeNull();
+    });
+
+    it("respects pinned instances", () => {
+      tracker.applyEvent(makeEvent({ status: "waiting", ts: Date.now() - TWELVE_HOURS - 1000 }));
+      tracker.setPinnedInstances("main", ["claude-code"]);
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).not.toBeNull();
+    });
+
+    it("uses details.lastActivityAt when present", () => {
+      tracker.applyEvent(
+        makeEvent({
+          status: "waiting",
+          ts: Date.now() - TWELVE_HOURS - 1000,
+          details: { lastActivityAt: Date.now() - 1000 },
+        }),
+      );
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).not.toBeNull();
+    });
+
+    it("falls back to event.ts when lastActivityAt missing", () => {
+      tracker.applyEvent(makeEvent({ status: "waiting", ts: Date.now() - TWELVE_HOURS - 1000 }));
+      tracker.pruneStale(TWELVE_HOURS);
+      expect(tracker.getState("main")).toBeNull();
+    });
+  });
+
+  describe("pruneSupersededByPane", () => {
+    it("drops older instance when same agent reappears with new threadId in same pane", () => {
+      tracker.applyEvent(makeEvent({ threadId: "t1", status: "waiting", paneId: "%5", ts: 1000 }));
+      tracker.applyEvent(makeEvent({ threadId: "t2", status: "running", paneId: "%5", ts: 2000 }));
+      tracker.setPinnedInstances("main", ["claude-code:t2"]);
+      tracker.pruneSupersededByPane();
+      const agents = tracker.getAgents("main");
+      expect(agents).toHaveLength(1);
+      expect(agents[0]!.threadId).toBe("t2");
+    });
+
+    it("keeps both when instances are in different panes", () => {
+      tracker.applyEvent(makeEvent({ threadId: "t1", status: "waiting", paneId: "%5", ts: 1000 }));
+      tracker.applyEvent(makeEvent({ threadId: "t2", status: "running", paneId: "%7", ts: 2000 }));
+      tracker.pruneSupersededByPane();
+      expect(tracker.getAgents("main")).toHaveLength(2);
+    });
+
+    it("keeps both when they're different agent types in the same pane", () => {
+      tracker.applyEvent(makeEvent({ agent: "claude-code", paneId: "%5", ts: 1000 }));
+      tracker.applyEvent(makeEvent({ agent: "amp", paneId: "%5", ts: 2000 }));
+      tracker.pruneSupersededByPane();
+      expect(tracker.getAgents("main")).toHaveLength(2);
+    });
+
+    it("ignores instances without a paneId", () => {
+      tracker.applyEvent(makeEvent({ threadId: "t1", paneId: undefined, ts: 1000 }));
+      tracker.applyEvent(makeEvent({ threadId: "t2", paneId: undefined, ts: 2000 }));
+      tracker.pruneSupersededByPane();
+      expect(tracker.getAgents("main")).toHaveLength(2);
+    });
+
+    it("uses details.lastActivityAt for recency comparison", () => {
+      tracker.applyEvent(
+        makeEvent({
+          threadId: "t1",
+          paneId: "%5",
+          ts: 5000,
+          details: { lastActivityAt: 9000 },
+        }),
+      );
+      tracker.applyEvent(
+        makeEvent({
+          threadId: "t2",
+          paneId: "%5",
+          ts: 6000,
+          details: { lastActivityAt: 7000 },
+        }),
+      );
+      tracker.pruneSupersededByPane();
+      const agents = tracker.getAgents("main");
+      expect(agents).toHaveLength(1);
+      expect(agents[0]!.threadId).toBe("t1");
+    });
+  });
+
   describe("multi-thread support", () => {
     it("tracks multiple threads for the same agent", () => {
       tracker.applyEvent(makeEvent({ threadId: "t1", status: "running" }));

package/packages/agentboard/packages/runtime/src/agents/tracker.ts

@@ -148,6 +148,56 @@ export class AgentTracker {
     }
   }
 
+  /**
+   * When multiple instances of the same agent share a paneId, keep only the most recent.
+   * The currently-live instance is pinned by the pane scanner, so this only removes superseded
+   * predecessors (e.g. a Claude Code session that was /exited and replaced in the same pane).
+   */
+  pruneSupersededByPane(): void {
+    for (const [session, sessionInstances] of this.instances) {
+      const groups = new Map<string, { key: string; ts: number }[]>();
+      for (const [key, event] of sessionInstances) {
+        if (!event.paneId) continue;
+        const groupKey = `${event.paneId}\0${event.agent}`;
+        const ts = event.details?.lastActivityAt ?? event.ts;
+        const list = groups.get(groupKey) ?? [];
+        list.push({ key, ts });
+        groups.set(groupKey, list);
+      }
+      for (const list of groups.values()) {
+        if (list.length < 2) continue;
+        list.sort((a, b) => b.ts - a.ts);
+        for (let i = 1; i < list.length; i++) {
+          const k = list[i]!.key;
+          if (this.isPinned(session, k)) continue;
+          sessionInstances.delete(k);
+          this.unseenInstances.delete(this.unseenKey(session, k));
+        }
+      }
+      if (sessionInstances.size === 0) {
+        this.instances.delete(session);
+      }
+    }
+  }
+
+  /** Auto-prune any instance whose last activity is older than timeoutMs, regardless of status. Skips pinned. */
+  pruneStale(timeoutMs: number): void {
+    const now = Date.now();
+    for (const [session, sessionInstances] of this.instances) {
+      for (const [key, event] of sessionInstances) {
+        if (this.isPinned(session, key)) continue;
+        const lastSeen = event.details?.lastActivityAt ?? event.ts;
+        if (now - lastSeen > timeoutMs) {
+          sessionInstances.delete(key);
+          this.unseenInstances.delete(this.unseenKey(session, key));
+        }
+      }
+      if (sessionInstances.size === 0) {
+        this.instances.delete(session);
+      }
+    }
+  }
+
   /** Auto-prune terminal instances older than timeout, but only if instance is not unseen or pinned */
   pruneTerminal(): void {
     const now = Date.now();

package/packages/agentboard/packages/runtime/src/server/index.ts

@@ -23,6 +23,7 @@ import {
   PID_FILE,
   SERVER_IDLE_TIMEOUT_MS,
   STUCK_RUNNING_TIMEOUT_MS,
+  STALE_AGENT_TIMEOUT_MS,
 } from "../shared";
 import type { ServerState, SessionData, ClientCommand, FocusUpdate, MetadataTone } from "../shared";
 
@@ -391,6 +392,8 @@ export function startServer(
     invalidateCurrentSessionCache();
     tracker.pruneStuck(STUCK_RUNNING_TIMEOUT_MS);
     tracker.pruneTerminal();
+    tracker.pruneStale(STALE_AGENT_TIMEOUT_MS);
+    tracker.pruneSupersededByPane();
     lastState = computeState();
     syncGitWatchers(lastState.sessions, broadcastState);
     const msg = JSON.stringify(lastState);

package/packages/agentboard/packages/runtime/src/shared.ts

@@ -11,6 +11,7 @@ export const SERVER_HOST: string = process.env.TT_AGENTBOARD_HOST || DEFAULT_SER
 export const PID_FILE = "/tmp/agentboard.pid";
 export const SERVER_IDLE_TIMEOUT_MS = 30_000;
 export const STUCK_RUNNING_TIMEOUT_MS = 3 * 60 * 1000;
+export const STALE_AGENT_TIMEOUT_MS = 12 * 60 * 60 * 1000;
 export const JOURNAL_IDLE_TIMEOUT_MS = 120_000;
 
 export interface SessionData {

package/packages/core/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tt",
-  "description": "Core dev workflow commands: interview-me, write-prd, prd-to-issues, tdd, improve-architecture, refine-text, task.",
-  "version": "0.0.109",
+  "description": "Core dev workflow commands and skills: interview-me, write-prd, prd-to-issues, tdd, improve-architecture, refine-text, task, parallel-slots, towles-tool.",
+  "version": "0.0.130",
   "author": {
     "name": "Chris Towles"
   }

package/packages/core/README.md

@@ -10,6 +10,13 @@ Core workflow automation commands for Claude Code.
 | `/tt:improve` | Explore codebase and suggest improvements     |
 | `/tt:refine`  | Fix grammar/spelling in files                 |
 
+## Skills
+
+| Skill               | Description                                                                       |
+| ------------------- | --------------------------------------------------------------------------------- |
+| `tt:towles-tool`    | `tt` CLI reference: git/gh helpers, journaling, dependency checks.                |
+| `tt:parallel-slots` | Fan out parallel Claude Code agents across slot clones of any repo, via `gh` CLI. |
+
 ## Installation
 
 ```bash

package/packages/core/skills/parallel-slots/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: parallel-slots
+description: Use when the user wants to dispatch parallel Claude Code agents across slot clones of a repo, asks to "fan out", "run N in parallel", "use the slots", or wants to coordinate multiple isolated working copies of the same repo. Explains the slot directory layout, when to fan out vs. stay in primary, and the `gh`-driven workflow that ties slots together.
+user_invocable: true
+---
+
+# Parallel slots
+
+The slot pattern lets you run independent Claude Code sessions on the same repo without stepping on each other. Mirrors Boris Cherny's "5 terminal tabs, each a separate git checkout" workflow.
+
+## Layout
+
+```
+~/code/<scope>/<repo>-repos/
+  <repo>-primary/   # interactive work
+  <repo>-slot-1/    # parallel agent slot
+  <repo>-slot-2/
+  <repo>-slot-3/
+  <repo>-slot-4/
+  <repo>-slot-5/
+```
+
+Each slot is a full clone of the same GitHub remote, not a worktree. They check out branches independently. Use the `gh` CLI for all GitHub-side operations (issue → branch, PR create, PR merge, status). If the repo ships a tmux sidebar (e.g. AgentBoard in towles-tool), it watches every slot and surfaces completion via the stop-hook sweep.
+
+## When to fan out
+
+Fan out (use slots) when:
+
+- Three or more independent tasks would benefit from running simultaneously (e.g. one PR, one bug, one refactor).
+- A task is risky and you want a clean, throwaway slot that won't pollute primary's working tree.
+- You're iterating on the agent harness itself and want to leave primary stable.
+
+Stay in primary when:
+
+- The work is sequential or all the changes need to land in the same commit.
+- You're reading/exploring; spinning a slot just adds overhead.
+
+## Dispatch flow
+
+1. Pick a free slot (any slot whose sidebar pane is idle).
+2. `cd` into it and confirm the working tree is clean.
+3. Branch off from a GitHub issue: `gh issue develop <issue-number> --checkout` — creates a remote branch tied to the issue and switches the slot to it. If there's no issue, name the branch and use `gh pr checkout <pr>` later if you need to hop onto a colleague's PR.
+4. Hand the task to Claude in that slot — either via the repo's sidebar TUI or by running `tt auto-claude` with a prompt.
+5. Watch the sidebar pane for completion. The stop-hook prints results back to it.
+
+## Coordination rules
+
+- Never run two agents on the _same_ branch in two slots — push/pull races destroy work.
+- Branch names should be unique per slot for the duration of the run.
+- If a slot's working tree is dirty when you arrive, treat it as in-progress work — investigate before resetting.
+- Pre-commit hooks (format + lint + typecheck) run in every slot, so `--no-verify` is forbidden.
+
+## Verifying a slot's output
+
+Before merging from a slot, run that repo's verify command (`/verify` in towles-tool) inside it. Don't trust the slot's own self-report; the agent that wrote the change is not the right reviewer.
+
+## Shipping from a slot
+
+Open the PR with `gh pr create` (use `--fill` to seed title/body from commits, or pass `--title`/`--body` explicitly). Merge with `gh pr merge --rebase --admin` — the standard merge style.
+
+## Cleanup
+
+After a slot's branch is merged: confirm with `gh pr status` that the slot's PR is merged, then prune the local branch. Use `compound-engineering:ce-clean-gone-branches` to bulk-prune across multiple slots in one pass.
+
+## Anti-patterns
+
+- Spinning all 5 slots on the same task "for redundancy". You'll spend the time merging conflicts.
+- Treating slots as long-lived workspaces. They are scratch checkouts — keep them transient.
+- Editing files in primary while a slot has them open. Stay in one or the other for any given file.

package/src/commands/graph/analyzer.test.ts

@@ -18,7 +18,13 @@ function textBlock(text: string): ContentBlock {
 }
 
 function toolUseBlock(name: string, input: Record<string, unknown>): ContentBlock {
-  return { type: "tool_use" as const, id: "tool-stub", name, input, caller: { type: "direct" } };
+  return {
+    type: "tool_use" as const,
+    id: "tool-stub",
+    name,
+    input,
+    caller: { type: "direct" },
+  } as unknown as ContentBlock;
 }
 
 function makeUsage(overrides: Partial<Usage> = {}): Usage {
@@ -32,7 +38,7 @@ function makeUsage(overrides: Partial<Usage> = {}): Usage {
     server_tool_use: null,
     service_tier: null,
     ...overrides,
-  };
+  } as unknown as Usage;
 }
 
 function makeEntry(overrides: Partial<JournalEntry> = {}): JournalEntry {

package/src/commands/graph.test.ts

@@ -16,7 +16,7 @@ function makeUsage(overrides: Partial<Usage> = {}): Usage {
     server_tool_use: null,
     service_tier: null,
     ...overrides,
-  };
+  } as unknown as Usage;
 }
 
 describe("graph --days filtering", () => {