pi-herdr-agents 1.6.0 → 1.7.0

package/AGENTS.md

@@ -4,7 +4,7 @@ These instructions apply to humans and coding agents changing `pi-herdr-agents`.
 
 ## What this package is
 
-`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous Pi child agents exclusively in Herdr. Ordinary runs use dedicated Herdr panes/tabs. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch. Legacy role definitions that request an external CLI fail before Herdr creates resources.
+`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous Pi child agents exclusively in Herdr. Ordinary runs group child panes in extension-owned `Agents` tabs by default. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch. Legacy role definitions that request an external CLI fail before Herdr creates resources.
 
 The extension is fire-and-forget: `subagent` returns an acknowledgement, and completion is delivered to the parent automatically. Never add polling guidance that tells callers to sleep, tail sessions, or repeatedly check status.
 
@@ -22,7 +22,7 @@ Bundled role prompts live in [`agents/`](agents/). The native `/skill:orchestrat
 ## Code map
 
 - `pi-extension/subagents/index.ts` — public tools/commands, agent discovery, launch/watch lifecycle, completion delivery, worktree manifests and handoffs
-- `pi-extension/subagents/herdr.ts` — Herdr CLI argument construction and response parsing
+- `pi-extension/subagents/herdr.ts` — Herdr CLI calls, response parsing, and ID-based Agents tab placement and capacity
 - `pi-extension/subagents/terminal.ts` — terminal adapter used by the lifecycle
 - `pi-extension/subagents/lifecycle.ts`, `status.ts`, `activity.ts` — process/turn state and widget projection
 - `pi-extension/subagents/wake.ts`, `supervision.ts`, `supervision-config.ts` — file wake-ups, shared pane reconciliation, polling fallback, and supervision configuration

package/CHANGELOG.md

@@ -7,7 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v1.6.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.1...v1.6.0)
+## [v1.7.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.6.0...v1.7.0)
+
+### Merged
+
+- feat(subagents): checkout-aware Agents tabs and safe cleanup (#33) [`#43`](https://github.com/giuseppecrj/pi-herdr-agents/pull/43)
+- feat: no-progress advisories for active subagents (#40) [`#41`](https://github.com/giuseppecrj/pi-herdr-agents/pull/41)
+- fix(subagents): measure recovered hang duration and track outstanding tool calls [`#40`](https://github.com/giuseppecrj/pi-herdr-agents/pull/40)
+
+### Commits
+
+- feat(subagents): group agents by checkout with safe pane cleanup (#33) [`59a1075`](https://github.com/giuseppecrj/pi-herdr-agents/commit/59a10756722e7cce3b2ded07db6e1adb04abb0ab)
+- fix(subagents): preserve delivery cleanup and live caller identity (#33) [`26987c5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/26987c58a2c882f31a0d935d7e97ce9dd8c4cce8)
+- feat(subagents): no-progress hang advisories for active children (#40) [`1ebf356`](https://github.com/giuseppecrj/pi-herdr-agents/commit/1ebf356521dd46dd6ee035fe3ebba0262992f399)
+- fix(subagents): keep no-progress recovery guidance evidence-based (#40) [`9cbf155`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9cbf155e291c063f70ef86800ef3bfe3c742c6c6)
+- test(integration): hang advisory coverage (#40) [`075f4fe`](https://github.com/giuseppecrj/pi-herdr-agents/commit/075f4feb17938df28a92fa00851d606e5a83b258)
+- fix(subagents): preserve boundary-aligned records in bounded session tails (#40) [`f096fdb`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f096fdb681921e9ab460610d53e456758802725f)
+
+## [v1.6.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.1...v1.6.0) - 2026-09-08
 
 ### Merged
 
@@ -34,11 +51,13 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - fix(subagents): scope pane snapshots to registered owners and confirm absence (#29) [`c73a132`](https://github.com/giuseppecrj/pi-herdr-agents/commit/c73a13211f743dc881c506226f457c6a5045e41b)
 - feat(subagents): persistent specialist docs, glossary, and integration coverage (#32) [`e0f052d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e0f052da7b717a9c4c21ae1d83172acb1a27452c)
 - fix(subagents): guard terminal evidence against racing semantic records (#29) [`f2e41f7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/f2e41f74f185c13a89b49301e226e04948d4c088)
+- chore: release v1.6.0 [`8a18189`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8a181890479f46d5955d4f1bac3be759a2d39010)
 - fix(subagents): type-safe validation for persistent sidecar, ledger, and config parsing [`fe81be5`](https://github.com/giuseppecrj/pi-herdr-agents/commit/fe81be5ca76eba504ff59fcf46ba3e9499753a70)
 - fix(orchestrate): parse review reports out of wrapped public delivery [`9f11918`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9f11918a407be39388999feeee16970e9d888105)
 - fix(subagents): close stopped persistent specialist panes (#32) [`8d0b6e7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8d0b6e7e9703fd7416e8ddc0ffb97dc26d48ab6b)
 - docs(context): define child wake-up signal and result delivery terms [`a3c159e`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a3c159e2056d13be5697494a13bcb84bdcf92bab)
 - docs(subagents): clarify persistent help requests (#32) [`16e9363`](https://github.com/giuseppecrj/pi-herdr-agents/commit/16e9363180cf49b5e03003f5ea1e57b38ac8adbd)
+- docs(release): require workflow-worker.js absence in the pack preview (#31) [`9d40cc0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/9d40cc0f3aa08ce203a720947bf097a4b66c9357)
 
 ## [v1.5.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v1.5.0...v1.5.1) - 2026-09-05
 

package/CONTEXT.md

@@ -18,6 +18,12 @@ The parent-facing handoff of a child run's observed outcome and available
 evidence. Receiving it does not establish that the work is correct or accepted.
 _Avoid_: Wake-up signal, acceptance
 
+**No-progress advisory**:
+An internal warning that an active child shows no durable progress in its session
+JSONL or activity snapshot. It is advisory only and never changes the child's
+outcome or triggers recovery.
+_Avoid_: Hang verdict, automatic recovery, stall replacement
+
 **Legacy external CLI role**:
 An old role definition that contains `cli`. Discovery reports a migration
 diagnostic, and launch fails before Herdr creates a pane or worktree. Remove
@@ -76,6 +82,19 @@ The append-only evidence record of persistent task dispatch and terminal
 outcomes for one session generation.
 _Avoid_: Work queue, mutable task list
 
+**Agents tab**:
+An extension-owned Herdr tab grouping delegated child panes in an existing
+checkout workspace. Ownership comes from returned IDs, not its display label.
+The pane cap includes every live pane; overflow creates another tab, not a
+workspace. Separate parent processes own separate groups.
+_Avoid_: Agent workspace, label-based ownership, automatic rearrangement
+
+**Retained checkout shell**:
+The interactive shell in a managed worktree's root pane, preserved after the
+child Pi process exits. Temporary review panes can close without deleting this
+surface or its checkout.
+_Avoid_: Completed agent process, disposable pane, automatic worktree cleanup
+
 **Worktree lease**:
 The lifetime-exclusive binding between a persistent specialist generation and
 one managed worktree, when that specialist writes in a worktree.

package/README.md

@@ -83,7 +83,7 @@ Use ordinary panes for read-only agents. A single or sequential writer can work
 
 ![Pi Herdr Agents lifecycle: spawn a child, run it in Herdr, supervise live state, and deliver one bounded result to the parent.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/async-subagent-lifecycle.png)
 
-A `subagent` call creates a dedicated Herdr pane or worktree, launches a child Pi session, and returns `started`. The parent watcher combines Herdr process state with child activity details and projects the result into a live widget:
+A `subagent` call selects the target checkout, reuses its Herdr workspace, and gives the child a pane in an extension-owned `Agents` tab. Four panes fit in each tab by default; overflow opens another tab in the same workspace. A worktree is created only when explicitly requested for checkout isolation. The call launches a child Pi session and returns `started`. The parent watcher combines Herdr process state with child activity details and projects the result into a live widget:
 
 ```text
 ╭─ Subagents ──────────────────── 1 active · 1 open ─╮
@@ -92,7 +92,7 @@ A `subagent` call creates a dedicated Herdr pane or worktree, launches a child P
 ╰────────────────────────────────────────────────────╯
 ```
 
-When the child completes, the parent receives one bounded `subagent_result` message and starts a new turn with that result in context. Callers never need to poll, tail session files, or wait in a shell loop.
+When the child completes, the parent receives one bounded `subagent_result` message and starts a new turn with that result in context. Disposable ordinary panes close after result delivery; Herdr removes a tab when its last pane closes. Persistent specialists keep their pane between tasks, and managed worktree roots return to retained interactive shells. Callers never need to poll, tail session files, or wait in a shell loop.
 
 ## Troubleshooting completion delivery
 
@@ -301,11 +301,13 @@ cp config.json.example config.json
     "maxAgents": 3
   },
   "supervision": {
-    "forcePolling": false
+    "forcePolling": false,
+    "hangWarningMinutes": 15
   },
   "panes": {
-    "mode": "tab",
-    "direction": "right"
+    "mode": "grouped",
+    "direction": "right",
+    "maxPerTab": 4
   }
 }
 ```
@@ -347,6 +349,34 @@ disable wake-ups and use that legacy cadence deliberately. The setting is read
 when the coordinator is created, so run `/reload` after changing it.
 `subagents_list` reports the active transport mode (`wake+batch`,
 `polling(forced)`, or `polling(fallback)`) and watcher count.
+
+`supervision.hangWarningMinutes` defaults to `15`; set it to `0` to disable
+no-progress advisories. For example, this keeps the default transport and sets
+a 30-minute advisory budget:
+
+```json
+{
+  "supervision": {
+    "forcePolling": false,
+    "hangWarningMinutes": 30
+  }
+}
+```
+
+While a child projects active or blocked, the parent compares durable session
+JSONL and activity-snapshot updates against this budget. An advisory is warning-only, fires once per no-progress episode, and
+never interrupts, kills, retries, or restarts a child. It identifies `blocked-tool` (an outstanding tool call may still complete),
+`truncated-turn` (an observed `toolUse` stop with no tool call; its cause is unknown), or
+`generic-no-progress` when neither condition is established, then
+includes the session path and manual recovery options. Ordinary children can be
+interrupted or, after manual termination, resumed or newly spawned. Persistent
+ordinary-pane specialists can be interrupted or stopped with `subagent_stop` and
+replaced; they cannot be resumed. Managed-worktree children, including persistent
+ones, retain their workspace and continue there only after the previous process
+has exited; do not use `subagent_resume` or start a concurrent writer. Interactive children stay
+quiet just as they do for stalled/recovered notices; their widget state still
+updates. A later durable update clears the episode and sends the corresponding
+recovered notice for non-interactive children.
 `polling(fallback)` means at least one tracked child is using per-child polling;
 other children can still use wake+batch.
 
@@ -359,7 +389,13 @@ was 4.82 s. The benchmark measures `/proc` CPU ticks for the supervisor and
 isolated Herdr tree, not parent-model latency; raw samples are written to
 `/tmp/issue29-bench/` by `test/bench/supervision-bench.mjs`.
 
-Set `panes.mode` to `"split"` to open ordinary public `subagent` and `subagent_resume` launches, including bare forks and `/iterate`, as splits of the stable parent pane. Set `panes.direction` to `"right"` or `"down"`; it defaults to `"right"` and is ignored when mode is `"tab"`. The default `"tab"` mode preserves existing behavior. Managed worktrees still use separate workspaces, while `/btw` keeps its existing tab behavior.
+`panes.mode` defaults to `"grouped"` when omitted. Ordinary public `subagent` and `subagent_resume` launches, including bare forks and `/iterate`, fill extension-owned `Agents`, `Agents 2`, etc. tabs in the target checkout's existing workspace. `panes.maxPerTab` is a positive safe integer, defaults to `4`, and counts all live panes in each owned tab, including user-added panes and retained shells. Overlapping launches in one parent respect this cap. It is independent of `persistent.maxAgents`.
+
+Checkout matching uses Herdr's canonical `worktree.checkout_path` and includes descendant directories. Shell working directories do not establish workspace ownership. If no checkout matches (including non-Git directories), placement uses the caller's workspace; overflow never creates a workspace. A reviewer with `cwd` set to a managed checkout joins that workspace without creating another worktree. Resume placement uses the saved session's cwd.
+
+Explicit `panes.mode: "tab"` preserves one new tab per ordinary child in the caller's workspace. Explicit `"split"` preserves splits of the stable parent pane. `panes.direction` is `"right"` (default) or `"down"` and applies to grouped and legacy splits. `maxPerTab` does not affect these legacy modes. Managed worktrees retain their separate workspaces, while `/btw` keeps its existing tab behavior.
+
+Ownership is tracked by returned pane/tab/workspace IDs, never labels. Separate parent processes own separate groups; `/reload` preserves a parent's in-memory ownership, but a full restart does not adopt old tabs. Placement never moves existing panes or renames user tabs. Background launches preserve focus; Herdr may resize sibling panes when splitting or closing. User-added panes are never closed by automatic tab cleanup. An owned tab remains reusable while user panes remain, even after all child panes close.
 
 Run `/reload` after changing role, model, or pane settings.
 
@@ -457,7 +493,7 @@ A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adver
 
 The child starts at the returned worktree root. Tell writing agents to test and commit when you want a commit-based handoff, and tell them not to push, merge, switch branches, or remove the worktree. The parent owns review and integration.
 
-Successful, failed, and help-requesting runs retain their workspace. Completion includes the worktree path, Herdr workspace, branch, base/head SHAs, commits ahead, changed and untracked files, and clean/dirty/conflicted state. Here, `clean` means no uncommitted files; the branch may still contain commits. If Git inspection fails, state is reported as unknown rather than guessed.
+Successful, failed, and help-requesting worktree runs retain their workspace and root shell. A reviewer's disposable pane can close without closing that root, tab, or checkout. Completion includes the worktree path, Herdr workspace, branch, base/head SHAs, commits ahead, changed and untracked files, and clean/dirty/conflicted state. Here, `clean` means no uncommitted files; the branch may still contain commits. If Git inspection fails, state is reported as unknown rather than guessed.
 
 An ownership manifest is written under the parent session's `artifacts/<session-id>/worktree-runs/` directory before Herdr creates resources. V1 does not automatically recover watchers after a full process restart, and `subagent_resume` does not reattach the managed worktree lifecycle.
 
@@ -568,7 +604,7 @@ Phase 5: Integrate        → Parent reviews and integrates worktree branches on
 Phase 6: Review           → Reviewer subagent checks the integrated changes
 ```
 
-The parent workspace and tab names stay unchanged. Subagents are created in newly named tabs or panes for each phase.
+The parent workspace and tab names stay unchanged. Subagents use the configured placement policy; grouped mode reuses available space in owned Agents tabs.
 
 ---
 

package/config.json.example

@@ -12,10 +12,12 @@
     "maxAgents": 3
   },
   "supervision": {
-    "forcePolling": false
+    "forcePolling": false,
+    "hangWarningMinutes": 15
   },
   "panes": {
-    "mode": "tab",
-    "direction": "right"
+    "mode": "grouped",
+    "direction": "right",
+    "maxPerTab": 4
   }
 }

package/docs/worktree-subagents.md

@@ -46,7 +46,7 @@ For a worktree launch:
 - `worktree.branch` is a new, unique branch name. Git/Herdr rejects a branch that cannot be created or is already checked out elsewhere.
 - `worktree.base` may be any revision that resolves to a commit in the source repository. It defaults to committed `HEAD`.
 - The extension resolves `base` to an exact SHA, writes an ownership manifest, then calls `herdr worktree create --no-focus`.
-- The child starts at the root of the returned worktree, in that workspace's root pane.
+- The child starts at the root of the returned worktree, in that workspace's retained root pane and newly owned `Agents` tab. Finishing Pi returns to the interactive checkout shell; it does not close the root pane.
 - Uncommitted and untracked files from the parent checkout are not copied. Commit anything the child must see before spawning it, or pass the needed context in the task.
 - Worktree creation does not steal terminal focus.
 
@@ -139,7 +139,7 @@ For parallel read-only review, prepare one stable existing checkout of the pull
 
 1. The parent records the canonical repository root, exact comparison base and head SHAs, and exact task/spec evidence. It makes sure no writer changes the checkout while review runs.
 2. Decide explicitly whether staged, unstaged, and untracked files are in scope. For included dirty state, record a bounded inventory and fingerprint; a commit SHA alone cannot pin it.
-3. Start each read-only child in an ordinary pane with `cwd` set to that checkout. Omit `worktree`.
+3. Start each read-only child in an ordinary pane with `cwd` set to that checkout. Omit `worktree`. With default grouped placement, the extension reuses that checkout's workspace and available space in this parent's owned Agents tabs, including a retained writer's root tab. It never moves the writer or creates another worktree. Separate parent processes do not adopt one another's tabs by label.
 4. Give every reviewer the same exact scope. Require it to report the repository root and `git rev-parse HEAD` before its review result.
 5. Before each dependent review wave and before reporting, recheck the head and dirty-state fingerprint. Drift makes prior evidence stale; review the new state again instead of mixing revisions.
 
@@ -205,7 +205,9 @@ This manual continuation is not watched by the original parent lifecycle. Do not
 
 ## Cleanup
 
-Cleanup is always explicit. First make sure commits, patches, or uncommitted files are no longer needed. Then remove the Herdr worktree workspace:
+Worktree and branch cleanup is always explicit. Ordinary temporary reviewer panes close after result delivery; Herdr removes their tab only if its last pane closes. The retained worktree root shell is excluded from automatic cleanup, and user-added panes are preserved. Persistent specialists retain their pane between tasks and follow the existing explicit stop semantics.
+
+First make sure commits, patches, or uncommitted files are no longer needed. Then remove the Herdr worktree workspace:
 
 ```bash
 herdr worktree remove --workspace <workspace-id>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/herdr.ts

@@ -1,5 +1,7 @@
 import { execFile, execSync, execFileSync } from "node:child_process";
 import { promisify } from "node:util";
+import { realpathSync } from "node:fs";
+import { resolve, relative, isAbsolute, sep } from "node:path";
 import { isFiniteNumber, isPlainObject, isString } from "./type-guards.ts";
 
 const execFileAsync = promisify(execFile);
@@ -132,33 +134,25 @@ interface HerdrCurrentPaneInfo {
 }
 
 function getHerdrCurrentPaneInfo(): HerdrCurrentPaneInfo {
-	const paneId = process.env.HERDR_PANE_ID;
-	const tabId = process.env.HERDR_TAB_ID;
-	const workspaceId = process.env.HERDR_WORKSPACE_ID;
-
-	// Fall back to `herdr pane current` if any identity env var is missing —
-	// older herdr versions may not set all three.
-	if (!paneId || !tabId || !workspaceId) {
-		const output = herdrExec(buildCurrentPaneArgs());
-		const parsed = parseHerdrJson(output);
-		const pane = parsed?.result?.pane;
-		if (
-			!isString(pane?.pane_id) ||
-			!isString(pane?.tab_id) ||
-			!isString(pane?.workspace_id)
-		) {
-			throw new Error(
-				`Unexpected herdr pane current output: ${output.trim() || "(empty)"}`,
-			);
-		}
-		return {
-			pane_id: pane.pane_id,
-			tab_id: pane.tab_id,
-			workspace_id: pane.workspace_id,
-		};
+	// Inherited IDs go stale after a pane moves. Herdr resolves the calling
+	// terminal's original identity to its live pane, tab, and workspace.
+	const output = herdrExec(buildCurrentPaneArgs());
+	const parsed = parseHerdrJson(output);
+	const pane = parsed?.result?.pane;
+	if (
+		!isString(pane?.pane_id) ||
+		!isString(pane?.tab_id) ||
+		!isString(pane?.workspace_id)
+	) {
+		throw new Error(
+			`Unexpected herdr pane current output: ${output.trim() || "(empty)"}`,
+		);
 	}
-
-	return { pane_id: paneId, tab_id: tabId, workspace_id: workspaceId };
+	return {
+		pane_id: pane.pane_id,
+		tab_id: pane.tab_id,
+		workspace_id: pane.workspace_id,
+	};
 }
 
 function buildTabCreateArgs(
@@ -217,14 +211,11 @@ function buildWorktreeCreateArgs(
 	];
 }
 
-export function createHerdrSurface(name: string): string {
-	// Create a new tab per subagent so parallel spawns each get a full tab
-	// instead of ever-narrower splits of the parent pane. Target the current
-	// workspace explicitly because Herdr's implicit default may be another space.
+export function createHerdrSurface(name: string, cwd = process.cwd()): string {
+	// Legacy tab mode and BTW target the caller workspace explicitly; Herdr's
+	// implicit default may be another workspace.
 	const { workspace_id: workspaceId } = getHerdrCurrentPaneInfo();
-	const output = herdrExec(
-		buildTabCreateArgs(name, process.cwd(), workspaceId),
-	);
+	const output = herdrExec(buildTabCreateArgs(name, cwd, workspaceId));
 	const paneId = extractHerdrRootPaneId(output, "tab create");
 	try {
 		herdrExec(["pane", "rename", paneId, name]);
@@ -234,6 +225,147 @@ export function createHerdrSurface(name: string): string {
 	return paneId;
 }
 
+interface OwnedAgentsTab {
+	workspaceId: string;
+	panes: Set<string>;
+	retainedPaneId?: string;
+}
+
+// In-memory ownership survives /reload, not process restart. Separate parent
+// processes never adopt tabs by label or share a capacity reservation.
+const agentsTabsKey = Symbol.for("pi-herdr-subagents:agents-tabs");
+// SAFETY: this extension alone writes this process-local symbol.
+const placementGlobal = globalThis as typeof globalThis & {
+	[agentsTabsKey]?: Map<string, OwnedAgentsTab>;
+};
+const agentsTabs = (placementGlobal[agentsTabsKey] ??= new Map<
+	string,
+	OwnedAgentsTab
+>());
+
+function canonicalPath(path: string): string {
+	try {
+		return realpathSync(path);
+	} catch {
+		return resolve(path);
+	}
+}
+
+function containsCwd(root: string, cwd: string): boolean {
+	const child = relative(root, cwd);
+	return (
+		child === "" ||
+		(child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child))
+	);
+}
+
+function placementPanes(): Array<{
+	pane_id: string;
+	tab_id: string;
+	workspace_id: string;
+}> {
+	const parsed = parseHerdrJson(herdrExec(["pane", "list"]));
+	const panes = parsed?.result?.panes;
+	if (
+		parsed?.result?.type !== "pane_list" ||
+		!Array.isArray(panes) ||
+		panes.some(
+			(pane) =>
+				!isString(pane?.pane_id) ||
+				!isString(pane?.tab_id) ||
+				!isString(pane?.workspace_id),
+		)
+	) {
+		throw new Error("Unexpected herdr pane list output for placement");
+	}
+	return panes;
+}
+
+export function createHerdrGroupedSurface(
+	name: string,
+	cwd: string,
+	maxPerTab: number,
+	direction: "right" | "down",
+): string {
+	const callerWorkspace = getHerdrCurrentPaneInfo().workspace_id;
+	const parsed = parseHerdrJson(herdrExec(["workspace", "list"]));
+	const workspaces = parsed?.result?.workspaces;
+	if (parsed?.result?.type !== "workspace_list" || !Array.isArray(workspaces)) {
+		throw new Error("Unexpected herdr workspace list output for placement");
+	}
+	const panes = placementPanes();
+	const target = canonicalPath(cwd);
+	let workspaceId = callerWorkspace;
+	let matchLength = -1;
+	for (const workspace of workspaces) {
+		if (!isString(workspace?.workspace_id))
+			throw new Error("Unexpected herdr workspace identity");
+		// Herdr exposes checkout ownership, but no stable non-Git workspace root.
+		// A shell's incidental cwd is not a workspace association.
+		const checkout = workspace.worktree?.checkout_path;
+		if (!isString(checkout)) continue;
+		const canonical = canonicalPath(checkout);
+		if (
+			containsCwd(canonical, target) &&
+			(canonical.length > matchLength ||
+				(canonical.length === matchLength &&
+					workspace.workspace_id === callerWorkspace))
+		) {
+			workspaceId = workspace.workspace_id;
+			matchLength = canonical.length;
+		}
+	}
+
+	// The entire inspect/create/record window is synchronous, before launch's
+	// first await. Overlapping launches in this parent cannot overbook a tab.
+	let paneId: string | undefined;
+	for (const [tabId, owned] of agentsTabs) {
+		if (owned.workspaceId !== workspaceId) continue;
+		const live = panes.filter(
+			(pane) => pane.tab_id === tabId && pane.workspace_id === workspaceId,
+		);
+		if (live.length === 0) {
+			agentsTabs.delete(tabId);
+			continue;
+		}
+		if (live.length >= maxPerTab) continue;
+		// The tab ID remains ours even when only user-added panes survive.
+		const anchor =
+			live.find((pane) => owned.panes.has(pane.pane_id)) ?? live[0];
+		paneId = extractHerdrPaneId(
+			herdrExec(buildPaneSplitArgs(anchor.pane_id, direction, cwd)),
+			"pane split",
+		);
+		owned.panes.add(paneId);
+		break;
+	}
+	if (!paneId) {
+		const count = [...agentsTabs.values()].filter(
+			(tab) => tab.workspaceId === workspaceId,
+		).length;
+		const label = count === 0 ? "Agents" : `Agents ${count + 1}`;
+		const output = herdrExec(buildTabCreateArgs(label, cwd, workspaceId));
+		paneId = extractHerdrRootPaneId(output, "tab create");
+		const tabId = parseHerdrJson(output)?.result?.tab?.tab_id;
+		if (!isString(tabId) || !tabId) {
+			// Only the explicitly returned pane is ours to roll back.
+			try {
+				herdrExec(["pane", "close", paneId]);
+			} catch {
+				/* preserve parse error */
+			}
+			throw new Error("Unexpected herdr tab create identity");
+		}
+		agentsTabs.set(tabId, { workspaceId, panes: new Set([paneId]) });
+	}
+	try {
+		herdrExec(["pane", "rename", paneId, name]);
+	} catch {
+		/* cosmetic */
+	}
+	return paneId;
+}
+
 /** Worktree records returned by `herdr worktree list`. */
 export interface HerdrWorktreeInfo {
 	branch: string;
@@ -298,7 +430,9 @@ function parseHerdrPaneList(output: string, workspaceId: string): string[] {
 	) {
 		throw new Error("Unexpected herdr pane list output");
 	}
-	return parsed.result.panes
+	const panes: Array<{ workspace_id?: unknown; pane_id?: unknown }> =
+		parsed.result.panes;
+	return panes
 		.filter((pane) => pane.workspace_id === workspaceId)
 		.map((pane) => pane.pane_id)
 		.filter(isString);
@@ -327,6 +461,34 @@ function recoverHerdrWorktree(
 	};
 }
 
+function retainWorktreeTab(
+	worktree: HerdrWorktreeSurface,
+	output: string,
+): HerdrWorktreeSurface {
+	const returnedTabId = parseHerdrJson(output)?.result?.tab?.tab_id;
+	const tabId =
+		isString(returnedTabId) && returnedTabId
+			? returnedTabId
+			: placementPanes().find(
+					(pane) =>
+						pane.pane_id === worktree.paneId &&
+						pane.workspace_id === worktree.workspaceId,
+				)?.tab_id;
+	if (tabId) {
+		agentsTabs.set(tabId, {
+			workspaceId: worktree.workspaceId,
+			panes: new Set([worktree.paneId]),
+			retainedPaneId: worktree.paneId,
+		});
+		try {
+			herdrExec(["tab", "rename", tabId, "Agents"]);
+		} catch {
+			/* cosmetic */
+		}
+	}
+	return worktree;
+}
+
 export function createHerdrWorktree(
 	name: string,
 	cwd: string,
@@ -335,7 +497,7 @@ export function createHerdrWorktree(
 ): HerdrWorktreeSurface {
 	const output = herdrExec(buildWorktreeCreateArgs(name, cwd, branch, base));
 	try {
-		return extractHerdrWorktree(output);
+		return retainWorktreeTab(extractHerdrWorktree(output), output);
 	} catch (parseError) {
 		let recovered: HerdrWorktreeSurface | HerdrWorktreeInfo | undefined;
 		try {
@@ -343,7 +505,8 @@ export function createHerdrWorktree(
 		} catch {
 			throw parseError;
 		}
-		if (recovered?.workspaceId && "paneId" in recovered) return recovered;
+		if (recovered?.workspaceId && "paneId" in recovered)
+			return retainWorktreeTab(recovered, output);
 		if (recovered) {
 			throw new HerdrWorktreeCreateError(
 				`Herdr created branch ${branch}, but its workspace response was incomplete`,
@@ -357,11 +520,10 @@ export function createHerdrWorktree(
 export function createHerdrSurfaceSplit(
 	name: string,
 	direction: "right" | "down",
+	cwd = process.cwd(),
 ): string {
 	const parentPaneId = getHerdrParentPaneId();
-	const output = herdrExec(
-		buildPaneSplitArgs(parentPaneId, direction, process.cwd()),
-	);
+	const output = herdrExec(buildPaneSplitArgs(parentPaneId, direction, cwd));
 	const paneId = extractHerdrPaneId(output, "pane split");
 	try {
 		herdrExec(["pane", "rename", paneId, name]);
@@ -759,7 +921,14 @@ export function sendHerdrEscape(surface: string): void {
 }
 
 export function closeHerdrSurface(surface: string): void {
+	for (const owned of agentsTabs.values()) {
+		if (owned.retainedPaneId === surface) return;
+	}
+	// Herdr removes a tab when its last pane closes. Never close a whole tab:
+	// a user may have added a pane since our last snapshot.
 	herdrExec(["pane", "close", surface]);
+	// Keep tab ownership until placement observes that the tab is actually gone.
+	for (const owned of agentsTabs.values()) owned.panes.delete(surface);
 }
 
 export function renameHerdrTab(title: string): void {