@d3ara1n/pi-subagent 3.2.2 → 3.2.3

package/README.md

@@ -64,16 +64,16 @@ Observations on how main models behave with this plugin, one family per subsecti
 
 | Command | Description |
 |---------|-------------|
-| `/subagent:view` | Open the live view: a tabbed overlay with a per-run activity feed and a brief detail page (inputs, files, stats), plus modal steer input for the focused run |
+| `/subagent:view` | Open the live view: a tabbed overlay with a per-run activity feed and a brief detail page (inputs, files, stats), plus modal steer input for the focused run — doubles as the session's run archive |
 | `/subagent:doctor` | Diagnose pi invocation, model-role resolution, configuration, and role references |
 | `/subagent:status` | List background runs and their current state |
 | `/subagent:cancel <id\|all> [reason]` | Cancel a live background run (or every live run); the optional reason is recorded with the run |
 
 ### Live view (`/subagent:view`)
 
-A centered overlay covering most of the screen. A tab row across the top lists every run (icon · id · role); `Tab` cycles the focused run, and the rest of the viewport belongs to it alone — showing one of two pages, toggled with `d`.
+A centered overlay covering most of the screen. A tab row across the top lists every run (icon · id · role); `Tab` cycles the focused run forward and `Shift+Tab` backward, and the rest of the viewport belongs to it alone — showing one of two pages, toggled with `d`. Runs are ordered newest-first, and the row is windowed around the focused cell — the archive can outgrow the terminal width, but focus never scrolls off-screen.
 
-The **activity page** (default) is the run's live feed: a continuous, append-only list where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent. A run leaves the view once its result is in the conversation — when the last one goes, the overlay shows a centered empty notice (with `Esc close` hinted) rather than shrinking away.
+The **activity page** (default) is the run's live feed: a continuous, append-only list where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent. Background runs stay listed for the whole session — the view doubles as the session's run archive, so a run's activity and brief remain browsable even after the model has collected the result. The centered empty notice (with `Esc close` hinted) appears only when nothing has been delegated yet.
 
 The **brief page** shows the run's inputs and vitals at full width: the task and context verbatim (wrapped; head+tail elided beyond 20k chars), inherited-conversation size and truncation status when enabled (never its text), the reference file list annotated with `✓`/`·` for whether the child's tool calls actually touched each file, usage and time stats, the fallback trace, and a stderr tail on failures.
 
@@ -264,11 +264,11 @@ Typical flow:
 
 Semantics worth knowing:
 
-- **Results are pull-only for the model.** A purple completion notice is shown to the user, but nothing delivers the result to the model or wakes it up. The notice is a pure notification in the same visual family as pi's `[compaction]` card — a `[subagent] id (role) outcome` header with the bare task preview beneath, each line truncated to the terminal width — and deliberately unlike the tool rows, so it never reads as model behavior; the result itself never appears in the notice, only in `subagent_check` (model) or `/subagent:status` (user). The model owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists runs not yet checked on the active branch on every request, but it never pushes results.
+- **Results are pull-only for the model.** A purple completion notice is shown to the user, but nothing delivers the result to the model or wakes it up. The notice is a pure notification in the same visual family as pi's `[compaction]` card — a `[subagent] id (role) outcome` header with the bare task preview beneath, each line truncated to the terminal width — and deliberately unlike the tool rows, so it never reads as model behavior; the result itself never appears in the notice, only in `subagent_check` (model) or `/subagent:status` (user). The model owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists runs not yet collected by a terminal check on the active branch on every request, but it never pushes results.
 - **Background runs survive turn cancellation** and are unaffected by a cancelled `subagent_wait` — cancelling the wait never cancels the runs; call `subagent_wait` or `subagent_check` again later.
 - **Idempotent check, session-tree delivery state:** `subagent_check` re-delivers the same terminal snapshot on every call — runs stay in the registry for the whole session, so no result can ever be stranded by branch navigation or compaction. Whether a run still needs collecting is not tracked in the registry: it derives from the session tree itself. The session is append-only, so branching back past a check entry drops it from the active path — the inbox reminder re-arms and the model simply checks again (the id still resolves; the run is still there). Branching forward to the original branch restores the check entry and silences the reminder again.
 - **Cancellation keeps the partial output.** `subagent_cancel(id, reason?)` kills the child (SIGTERM, escalating to SIGKILL) and settles the run as `cancelled` — its own stop reason in the same family as `timeout`/`budget_exceeded` (TUI warning styling ⏹, not the error-red ✗ of real failures) — with whatever it had produced. The `reason` becomes the error message verbatim, so whoever reads the partial output later via `subagent_check` — or the audit history — sees `cancelled — <reason>`; the source is distinguishable too (`user: ...` for `/subagent:cancel`, the model's own words for the tool, `session shutdown` for reaping). Cancelling does not remove the run: `subagent_check` still returns the partial output, and `subagent_wait` reports the run as `cancelled` with its usage stats.
-- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the runs not yet checked on the active branch (queued, running, and finished-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Runs missing from the list were already checked on this branch — so a finished run the model forgot to check keeps surfacing until it does. Branch navigation keeps this honest: the list derives from the session tree, not registry bookkeeping.
+- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the runs not yet collected by a terminal check on the active branch (queued, running, and finished/failed-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Only checks that returned a terminal snapshot count — a peek at a live frame never silences the inbox, so the steer flow's check → steer → check-later cycle cannot strand an outcome. Runs missing from the list were already checked on this branch — so a finished run the model forgot to check keeps surfacing until it does. Branch navigation keeps this honest: the list derives from the session tree, not registry bookkeeping.
 - **`timeout` (seconds) is optional — omitting it is the normal usage.** `subagent_wait` blocks until every run finishes, with each run bounded by its own role timeout; subagent runs typically take minutes. Set a timeout only when the waiter must resume soon (e.g. to report progress to the user).
 - Background runs share the global `maxConcurrency` gate — extra runs show up as `queued` in wait/check views.
 - **Top-level only:** nested subagents cannot delegate in the background (a subagent process exits when its task finishes, which would orphan the run).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/index.ts

@@ -43,7 +43,7 @@ import { startSubagentRun, type RunHandle } from "./run.ts";
 import { buildInboxReminder, injectReminder } from "./reminder.ts";
 import { serializeInheritedConversation } from "./inheritance.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
-import { createViewPanel, filterDeliveredRuns } from "./view.ts";
+import { createViewPanel } from "./view.ts";
 import {
   createSteerCallRender,
   renderBackgroundDelegateCall,
@@ -60,11 +60,6 @@ import {
 
 const BACKGROUND_COMPLETION_MESSAGE_TYPE = "subagent-completion";
 
-/** Refresh ceiling for the /subagent:view delivered-ids cache (ms). The panel
- * re-renders on every animation tick (~150ms); deriving delivery from the
- * session tree is throttled so the overlay stays cheap. */
-const VIEW_DELIVERED_CACHE_MS = 1000;
-
 // ── Extension entry ────────────────────────────────────────────────
 
 export default function subagentExtension(pi: ExtensionAPI) {
@@ -812,28 +807,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("subagent:view", {
-    description: "Open the live subagent activity view (watch progress, steer runs)",
+    description: "Open the subagent activity view (watch runs, steer, browse the session's archive)",
     handler: async (_args, ctx) => {
-      // Union of every known run: the background registry plus live
-      // in-flight runs (foreground delegate calls included). Dedupe by id —
-      // background runs appear in both. Terminal runs stay listed until
-      // their result is delivered (subagent_check on the active branch,
-      // derived from the session tree — same source of truth as the inbox
-      // reminder), then leave the view: it is for live watching and pending
-      // collection, not an archive. Delivery re-derivation is throttled
-      // because the panel re-renders on every animation tick.
-      const deliveredCache = { ids: new Set<string>(), at: 0 };
-      const deliveredIds = (): Set<string> => {
-        if (Date.now() - deliveredCache.at > VIEW_DELIVERED_CACHE_MS) {
-          try {
-            deliveredCache.ids = collectDeliveredIds(ctx.sessionManager.buildContextEntries());
-          } catch {
-            /* keep the previous set */
-          }
-          deliveredCache.at = Date.now();
-        }
-        return deliveredCache.ids;
-      };
+      // Union of every known run: the background registry — append-only for
+      // the whole session, the view doubles as the run archive and derives
+      // nothing from delivery state — plus live in-flight runs (foreground
+      // delegate calls included, visible only while in flight). Dedupe by
+      // id — background runs appear in both.
       const runsProvider = () => {
         const seen = new Set<string>();
         const out: RunHandle[] = [];
@@ -843,7 +823,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
             out.push(r);
           }
         }
-        return filterDeliveredRuns(out, deliveredIds());
+        return out;
       };
       if (runsProvider().length === 0) {
         ctx.ui.notify("No subagent runs yet.", "info");

package/src/reminder.ts

@@ -3,11 +3,12 @@
  *
  * Injected into the LLM context before every provider call via the `context`
  * event. The reminder lists every delegated run not yet delivered by a
- * subagent_check on the active branch — queued, running, and
- * finished/failed alike — so the model cannot forget about them. Delivery
- * state is derived from the session tree (see collectDeliveredIds), not
- * tracked in the registry: branching past a check re-arms the inbox,
- * branching back silences it, and compaction un-delivers naturally.
+ * subagent_check of a terminal snapshot on the active branch — queued,
+ * running, and finished/failed alike — so the model cannot forget about
+ * them. Delivery state is derived from the session tree (see
+ * collectDeliveredIds), not tracked in the registry: branching past a check
+ * re-arms the inbox, branching back silences it, and compaction un-delivers
+ * naturally.
  *
  * Cache discipline: the reminder is prepended to the FIRST user message, so
  * it sits at a stable position in the message prefix. Its content must stay
@@ -65,9 +66,9 @@ function inboxStatus(entry: InboxEntry): string {
  * Build the inbox reminder text, or undefined when every delegated run has
  * already been checked on the active branch (nothing to remind about —
  * inject nothing, keep the context untouched and the provider cache fully
- * stable). Queued/running runs are always listed regardless of delivery
- * state — their result is not final yet, so a past check (of a live frame)
- * never counts as delivered.
+ * stable). The state guard pins the inbox's own invariant locally — only
+ * terminal runs can ever count as delivered (collectDeliveredIds ignores
+ * live-frame checks), so a past peek at a running run never silences it.
  */
 export function buildInboxReminder(entries: Iterable<InboxEntry>, delivered: Set<string>): string | undefined {
   const rows: string[] = [];

package/src/spawn.ts

@@ -481,7 +481,12 @@ export async function spawnSubagent(
               usage.totalTokens || 0,
             );
           }
-          if (!result.model && msg.model) result.model = msg.model;
+          // The child's AssistantMessage carries the bare model id with the
+          // provider in a separate field — compose the full `provider/model-id`
+          // ref so usage displays match the delegate-facing modelRef format.
+          if (!result.model && msg.model) {
+            result.model = msg.provider ? `${msg.provider}/${msg.model}` : msg.model;
+          }
           // message_end is authoritative for the latest assistant attempt. A
           // successful native retry must clear the transient error left by the
           // failed attempt instead of triggering a redundant whole-run fallback.

package/src/types.ts

@@ -137,6 +137,7 @@ export interface SubagentMessage {
     cost?: { total?: number };
     totalTokens?: number;
   };
+  provider?: string;
   model?: string;
   stopReason?: string;
   errorMessage?: string;

package/src/utils.test.ts

@@ -910,9 +910,15 @@ describe("briefFilesUsed", () => {
 });
 
 describe("collectDeliveredIds", () => {
-  const checkEntry = (id: string) => ({
+  // A check tool result carrying a terminal snapshot (exitCode >= 0) —
+  // the shape the check tool persists into the session tree.
+  const checkEntry = (id: string, exitCode = 0) => ({
     type: "message",
-    message: { role: "toolResult", toolName: "subagent_check", details: { id, role: "worker" } },
+    message: {
+      role: "toolResult",
+      toolName: "subagent_check",
+      details: { id, role: "worker", result: { exitCode } },
+    },
   });
 
   test("collects ids from subagent_check tool results only", () => {
@@ -932,6 +938,11 @@ describe("collectDeliveredIds", () => {
     assert.deepEqual(collectDeliveredIds([checkEntry("sub-1"), checkEntry("sub-1")]), new Set(["sub-1"]));
   });
 
+  test("a check of a live frame never delivers (stale peek must not silence the inbox)", () => {
+    const entries = [checkEntry("sub-1", -1), checkEntry("sub-2")];
+    assert.deepEqual(collectDeliveredIds(entries), new Set(["sub-2"]));
+  });
+
   test("empty path means nothing delivered (branch rewound past the check)", () => {
     assert.equal(collectDeliveredIds([]).size, 0);
   });
@@ -941,6 +952,10 @@ describe("collectDeliveredIds", () => {
       { type: "message", message: { role: "toolResult", toolName: "subagent_check" } },
       { type: "message", message: { role: "toolResult", toolName: "subagent_check", details: {} } },
       { type: "message", message: { role: "toolResult", toolName: "subagent_check", details: { id: 42 } } },
+      {
+        type: "message",
+        message: { role: "toolResult", toolName: "subagent_check", details: { id: "sub-1", result: {} } },
+      },
     ];
     assert.equal(collectDeliveredIds(entries).size, 0);
   });

package/src/utils.ts

@@ -903,6 +903,11 @@ interface SessionEntryLike {
  * truth for delivery state: it is append-only and branch navigation rebuilds
  * the active path, so branching past a check entry un-delivers (the inbox
  * re-arms) while branching back re-delivers — no mirrored state to sync.
+ *
+ * Only checks that returned a TERMINAL snapshot count: a peek at a live
+ * frame (running/queued, exitCode -1) delivers nothing — the steer flow
+ * re-checks later — so an early check can never silence the inbox before
+ * the outcome exists.
  */
 export function collectDeliveredIds(entries: Iterable<SessionEntryLike>): Set<string> {
   const ids = new Set<string>();
@@ -910,8 +915,12 @@ export function collectDeliveredIds(entries: Iterable<SessionEntryLike>): Set<st
     if (entry.type !== "message") continue;
     const message = entry.message;
     if (!message || message.role !== "toolResult" || message.toolName !== "subagent_check") continue;
-    const id = (message.details as { id?: unknown } | undefined)?.id;
-    if (typeof id === "string" && id) ids.add(id);
+    const details = message.details as { id?: unknown; result?: { exitCode?: unknown } } | undefined;
+    if (typeof details?.id !== "string" || !details.id) continue;
+    // A malformed or live frame (exitCode -1) is not a delivery — leave the
+    // inbox armed.
+    if (typeof details.result?.exitCode !== "number" || details.result.exitCode === -1) continue;
+    ids.add(details.id);
   }
   return ids;
 }

package/src/view.test.ts

@@ -1,10 +1,6 @@
 import test from "node:test";
 import assert from "node:assert";
-import {
-  filterDeliveredRuns,
-  inheritedConversationFields,
-  sortViewRuns,
-} from "./view.ts";
+import { inheritedConversationFields, sortViewRuns, windowTabCells } from "./view.ts";
 import type { RunHandle } from "./run.ts";
 
 // ── Fakes ──────────────────────────────────────────────────────────
@@ -13,26 +9,6 @@ function fakeHandle(id: string, state: RunHandle["state"]): RunHandle {
   return { id, state } as unknown as RunHandle;
 }
 
-// ── filterDeliveredRuns ────────────────────────────────────────────
-
-test("filterDeliveredRuns drops delivered terminal runs, keeps live and undelivered", () => {
-  const running = fakeHandle("sub-1", "running");
-  const queued = fakeHandle("sub-2", "queued");
-  const finishedUndelivered = fakeHandle("sub-3", "finished");
-  const finishedDelivered = fakeHandle("sub-4", "finished");
-  const failedDelivered = fakeHandle("sub-5", "failed");
-
-  const out = filterDeliveredRuns(
-    [running, queued, finishedUndelivered, finishedDelivered, failedDelivered],
-    new Set(["sub-4", "sub-5"]),
-  );
-
-  assert.deepEqual(
-    out.map((r) => r.id),
-    ["sub-1", "sub-2", "sub-3"],
-  );
-});
-
 // ── inheritedConversationFields ────────────────────────────────────
 
 test("inheritedConversationFields returns aligned-view metadata without body text", () => {
@@ -50,15 +26,72 @@ test("inheritedConversationFields returns aligned-view metadata without body tex
 
 // ── sortViewRuns ───────────────────────────────────────────────────
 
-test("sortViewRuns ranks running before finished, each group by id", () => {
+test("sortViewRuns orders newest first by numeric id (creation order)", () => {
   const out = sortViewRuns([
-    fakeHandle("sub-3", "finished"),
     fakeHandle("sub-2", "running"),
-    fakeHandle("sub-4", "running"),
+    fakeHandle("sub-10", "finished"),
     fakeHandle("sub-1", "failed"),
+    fakeHandle("sub-9", "queued"),
   ]);
   assert.deepEqual(
     out.map((r) => r.id),
-    ["sub-2", "sub-4", "sub-1", "sub-3"],
+    ["sub-10", "sub-9", "sub-2", "sub-1"],
   );
 });
+
+test("sortViewRuns is state-agnostic — a run settling never reshuffles rows", () => {
+  const before = sortViewRuns([
+    fakeHandle("sub-1", "running"),
+    fakeHandle("sub-2", "running"),
+    fakeHandle("sub-3", "running"),
+  ]);
+  const after = sortViewRuns([
+    fakeHandle("sub-1", "running"),
+    fakeHandle("sub-2", "failed"),
+    fakeHandle("sub-3", "finished"),
+  ]);
+  assert.deepEqual(
+    after.map((r) => r.id),
+    before.map((r) => r.id),
+  );
+});
+
+// ── windowTabCells ─────────────────────────────────────────────────
+
+test("windowTabCells returns everything when the row fits", () => {
+  const cells = ["[a sub-1]", "[b sub-22]", "[c sub-333]"];
+  const win = windowTabCells(cells, 1, 100);
+  assert.deepEqual(win, { items: cells, leftClipped: false, rightClipped: false });
+});
+
+test("windowTabCells keeps the focused cell visible under a tight budget", () => {
+  const cells = ["[a sub-1 x]", "[b sub-2 y]", "[c sub-3 z]"];
+  // Cell widths with one separator space each: 13 + 12 = 25 fits the left
+  // neighbor too; the right one (13) does not fit.
+  const win = windowTabCells(cells, 1, 25);
+  assert.equal(win.leftClipped, false); // sub-1 fits on the left
+  assert.equal(win.rightClipped, true); // sub-3 does not fit
+  assert.deepEqual(win.items, [cells[0], cells[1]]);
+});
+
+test("windowTabCells clips both sides around a mid-list focus", () => {
+  const cells = ["[1]", "[22]", "[333]", "[4444]", "[55555]"];
+  // Focused cell (width 6) plus left neighbor (width 5) = 11.
+  const win = windowTabCells(cells, 2, 11);
+  assert.deepEqual(win.items, [cells[1], cells[2]]);
+  assert.equal(win.leftClipped, true);
+  assert.equal(win.rightClipped, true);
+});
+
+test("windowTabCells still returns the focused cell when it alone overflows", () => {
+  const cells = ["[tiny]", "[enormous-cell]"];
+  const win = windowTabCells(cells, 1, 3);
+  assert.deepEqual(win.items, [cells[1]]);
+  assert.equal(win.leftClipped, true);
+  assert.equal(win.rightClipped, false);
+});
+
+test("windowTabCells handles an empty list and clamps an out-of-range focus", () => {
+  assert.deepEqual(windowTabCells([], 0, 50), { items: [], leftClipped: false, rightClipped: false });
+  assert.deepEqual(windowTabCells(["[a]"], 99, 50).items, ["[a]"]);
+});

package/src/view.ts

@@ -23,8 +23,13 @@
  * Steer input is modal so keys never conflict with the editor: browse mode
  * owns navigation; `s` opens the editor (Enter sends and returns to browse,
  *    Esc cancels and clears). Esc in browse closes the overlay; Tab cycles
- *    the focused run and resets its view — page back to activity, scrolls
- *    re-pinned.
+ *    the focused run forward, Shift+Tab backward, and cycling resets its
+ *    view — page back to activity, scrolls re-pinned.
+ *
+ * The run list is the session's archive: every background run stays listed
+ * (newest first) after it settles — results remain browsable even after the
+ * model collects them, so nothing is ever derived from delivery state here.
+ * Foreground runs appear only while their delegate call is in flight.
  *
  * Layout: a centered screen overlay (overlay:true) occupying most of the
  * terminal, framed with a thin border. An embedded Editor accepts steering
@@ -110,25 +115,54 @@ function capBriefText(text: string): string {
 }
 
 /**
- * Build the display list of runs for the panel: running/queued first, then
- * finished, each group ordered by registry id.
+ * Build the display list of runs for the panel: newest first, by numeric
+ * id (creation order). Creation order never reshuffles — the archive is
+ * append-only, so rows stay put when runs settle and focus remains
+ * predictable.
  */
 export function sortViewRuns(runs: RunHandle[]): RunHandle[] {
-  const rank = (r: RunHandle) => (r.state === "running" || r.state === "queued" ? 0 : 1);
-  return [...runs].sort((a, b) => rank(a) - rank(b) || a.id.localeCompare(b.id));
+  const num = (r: RunHandle) => Number.parseInt(r.id.replace(/^sub-/, ""), 10) || 0;
+  return [...runs].sort((a, b) => num(b) - num(a));
 }
 
 /**
- * Drop terminal runs whose result is already in the conversation — delivered
- * by subagent_check on the active branch (the same session-tree source of
- * truth as the inbox reminder). Live runs and undelivered terminal runs
- * stay: the view is for live watching and pending collection, not an
- * archive.
+ * @internal — exported for testing; fits a window of tab cells around the
+ * focused one into `budget` visible columns. The archive can outgrow the
+ * row, but the focused cell never scrolls off-screen: neighbors expand
+ * outward (cheaper side first) while they fit, and clipped sides collapse
+ * to `…` markers.
  */
-export function filterDeliveredRuns(runs: RunHandle[], delivered: Set<string>): RunHandle[] {
-  return runs.filter(
-    (r) => (r.state !== "finished" && r.state !== "failed") || !delivered.has(r.id),
-  );
+export function windowTabCells(
+  cells: string[],
+  focusIdx: number,
+  budget: number,
+): { items: string[]; leftClipped: boolean; rightClipped: boolean } {
+  if (cells.length === 0) return { items: [], leftClipped: false, rightClipped: false };
+  const focus = Math.max(0, Math.min(focusIdx, cells.length - 1));
+  const widths = cells.map((c) => visibleWidth(c) + 1); // +1 separator space
+  let lo = focus;
+  let hi = focus;
+  let used = widths[focus];
+  const tryAdd = (i: number): boolean => {
+    if (i < 0 || i >= cells.length || used + widths[i] > budget) return false;
+    used += widths[i];
+    return true;
+  };
+  for (;;) {
+    const canLeft = lo > 0;
+    const canRight = hi < cells.length - 1;
+    if (!canLeft && !canRight) break;
+    const preferLeft = canLeft && (!canRight || widths[lo - 1] <= widths[hi + 1]);
+    if (preferLeft) {
+      if (tryAdd(lo - 1)) { lo--; continue; }
+      if (canRight && tryAdd(hi + 1)) { hi++; continue; }
+      break;
+    }
+    if (tryAdd(hi + 1)) { hi++; continue; }
+    if (canLeft && tryAdd(lo - 1)) { lo--; continue; }
+    break;
+  }
+  return { items: cells.slice(lo, hi + 1), leftClipped: lo > 0, rightClipped: hi < cells.length - 1 };
 }
 
 /**
@@ -205,9 +239,10 @@ export class SubagentViewPanel implements Component, Focusable {
     }, ANIMATION_INTERVAL_MS);
   }
 
-  /** Resolve the focused run by id; stable across sort-order reshuffles
-   *  (e.g. a run finishing re-ranks the list). The focused run's view state
-   *  (page + scrolls) resets only when the focused run actually changes. */
+  /** Resolve the focused run by id; stable across list changes (a
+   *  foreground run settling drops out of the registry). The focused run's
+   *  view state (page + scrolls) resets only when the focused run actually
+   *  changes. */
   private focusedRun(): RunHandle | undefined {
     const runs = sortViewRuns(this.runsProvider());
     if (runs.length === 0) {
@@ -231,15 +266,21 @@ export class SubagentViewPanel implements Component, Focusable {
     this.briefTop = 0;
   }
 
-  private cycleRun(): void {
+  private cycleRun(direction: 1 | -1): void {
     const runs = sortViewRuns(this.runsProvider());
     if (runs.length < 2) return;
     const idx = runs.findIndex((r) => r.id === this.focusId);
-    // Focus id gone from the list: fall back to the first run, same as
-    // focusedRun() — not to the second.
-    const next = idx < 0 ? runs[0] : runs[(idx + 1) % runs.length];
-    if (next.id === this.focusId) return;
-    this.focusId = next.id;
+    if (idx < 0) {
+      // Focus id gone from the list (a foreground run settled): fall back
+      // to the newest run, same as focusedRun().
+      const run = runs[0];
+      if (run.id === this.focusId) return;
+      this.focusId = run.id;
+    } else {
+      const next = runs[(idx + direction + runs.length) % runs.length];
+      if (next.id === this.focusId) return;
+      this.focusId = next.id;
+    }
     this.resetRunView();
     this.tui.requestRender();
   }
@@ -282,7 +323,11 @@ export class SubagentViewPanel implements Component, Focusable {
       return;
     }
     if (matchesKey(data, Key.tab)) {
-      this.cycleRun();
+      this.cycleRun(1);
+      return;
+    }
+    if (matchesKey(data, "shift+tab")) {
+      this.cycleRun(-1);
       return;
     }
     const ch = printableChar(data);
@@ -482,25 +527,30 @@ export class SubagentViewPanel implements Component, Focusable {
     const runningCount = runs.filter((r) => r.state === "running").length;
     const focused = this.focusedRun();
 
-    // ── Tab row: one cell per run; the focused one is highlighted. ──
+    // ── Tab row: one cell per run; the focused one is highlighted. The
+    // archive can outgrow the row — window the cells around the focused one
+    // so focus never scrolls off-screen; Tab/⇧Tab walk the full list.
     if (runs.length > 0) {
       // Brackets stay on every cell, focused included — the selectedBg +
       // accent highlight is the indicator, so Tab doesn't shift text.
       const cells = runs.map((r) => {
-        const isFocused = r === focused;
-        const label = `${runIcon(r.snapshot, fg)} ${r.id} ${r.role}`;
-        const styled = isFocused ? th.bg("selectedBg", fg("accent", label)) : fg("dim", label);
-        return `[${styled}]`;
+        const label = `[${runIcon(r.snapshot, fg)} ${r.id} ${r.role}]`;
+        return r === focused ? th.bg("selectedBg", fg("accent", label)) : fg("dim", label);
       });
-      lines.push(
-        row(
-          `${fg("accent", th.bold("subagents"))} ${th.fg("dim", `${runningCount} running · ${runs.length} total · Tab switch`)}  ` +
-            cells.join(th.fg("dim", " ")),
-        ),
-      );
+      const header =
+        `${fg("accent", th.bold("subagents"))} ` +
+        th.fg("dim", `${runningCount} running · ${runs.length} total · Tab/⇧Tab switch`) +
+        "  ";
+      const focusIdx = Math.max(0, runs.findIndex((r) => r === focused));
+      const win = windowTabCells(cells, focusIdx, innerW - visibleWidth(header));
+      const parts: string[] = [];
+      if (win.leftClipped) parts.push(fg("dim", "…"));
+      parts.push(...win.items);
+      if (win.rightClipped) parts.push(fg("dim", "…"));
+      lines.push(row(header + parts.join(th.fg("dim", " "))));
     } else {
-      // Empty registry — every run left the view (a run disappears once its
-      // result is in the conversation). Give the state real presence — a
+      // Empty registry — nothing was delegated this session and no
+      // foreground run is in flight. Give the state real presence — a
       // full-size panel with a centered message and the close hint — and
       // fold steer mode back to browse so Esc closes immediately.
       if (this.mode === "steer") {
@@ -510,12 +560,7 @@ export class SubagentViewPanel implements Component, Focusable {
       lines.push(row(""));
       lines.push(row(fg("muted", centerText("no subagent runs", innerW))));
       lines.push(
-        row(
-          fg(
-            "dim",
-            centerText("a run leaves the view once its result is in the conversation", innerW),
-          ),
-        ),
+        row(fg("dim", centerText("start one with subagent_delegate to see it here", innerW))),
       );
       lines.push(row(""));
       lines.push(row(""));
@@ -565,7 +610,7 @@ export class SubagentViewPanel implements Component, Focusable {
           lines.push(row(fg("dim", `steer → ${label} · press s`)));
         }
         const pageKey = this.page === "activity" ? "d brief" : "d activity";
-        lines.push(row(fg("dim", `↑↓ scroll · ${pageKey} · Tab run · s steer · Esc close`)));
+        lines.push(row(fg("dim", `↑↓ scroll · ${pageKey} · Tab/⇧Tab run · s steer · Esc close`)));
       }
     }