pi-herdr-agents 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -7,11 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v2.0.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.2...v2.0.3)
+## [v2.0.5](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.4...v2.0.5)
+
+### Merged
+
+- test(worktrees): fix path assertions and clarify cleanup scope [`#65`](https://github.com/giuseppecrj/pi-herdr-agents/pull/65)
+- fix(worktrees): support launches from linked checkouts [`#64`](https://github.com/giuseppecrj/pi-herdr-agents/pull/64)
+- fix(subagents): accept null worktree for strict tool clients [`#57`](https://github.com/giuseppecrj/pi-herdr-agents/pull/57)
+- fix(subagents): interactive mode time [`#62`](https://github.com/giuseppecrj/pi-herdr-agents/pull/62)
+
+### Commits
+
+- test(worktrees): make quoting expectations independent [`a526824`](https://github.com/giuseppecrj/pi-herdr-agents/commit/a526824dcffd97fa09b158fba5cae05ff75fc100)
+- Merge commit '5fc2ea04b52a03df35b246cef6cb524516d34350' into maint/pr57-null-render-type [`e6fe747`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e6fe747d5df44789df1e8fd42b585d4dbc36a144)
+- perf(startup): skip worktree inventory during session init [`8de2447`](https://github.com/giuseppecrj/pi-herdr-agents/commit/8de24470cb53fd345979cfe501a10645202403e0)
+- fix(worktrees): keep in-scope inventory rows visible [`41639a7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/41639a7673e7a48c28e34e3f3f079c02f6454264)
+- refactor(cleanup): remove unused inventory notice [`330cc96`](https://github.com/giuseppecrj/pi-herdr-agents/commit/330cc9669eff14358e9eea8999f024e0ebfe4187)
+- docs: make worktree inventory on-demand [`e946dba`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e946dba9ca246c15e581f35c098ccf88f003c4f9)
+- fix nullable worktree render args [`afc50bc`](https://github.com/giuseppecrj/pi-herdr-agents/commit/afc50bc6e96005f3a36c3e29a17be36f99d81845)
+
+## [v2.0.4](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.3...v2.0.4) - 2026-09-22
+
+### Merged
+
+- perf: batch persistent delivery ledger reads [`#58`](https://github.com/giuseppecrj/pi-herdr-agents/pull/58)
+
+### Commits
+
+- chore: release v2.0.4 [`4cacc1a`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4cacc1a65c3cb8627f05264b61684a8089cb7512)
+
+## [v2.0.3](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.2...v2.0.3) - 2026-09-21
 
 ### Commits
 
 - fix: skip startup worktree inventory outside Herdr [`34800d7`](https://github.com/giuseppecrj/pi-herdr-agents/commit/34800d79464575063a61ad6f240cd49cc8acd730)
+- chore: release v2.0.3 [`60888f2`](https://github.com/giuseppecrj/pi-herdr-agents/commit/60888f2dea48317257909abbcd0dd374ed861d77)
 
 ## [v2.0.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.1...v2.0.2) - 2026-09-19
 

package/README.md

@@ -23,7 +23,7 @@ Delegate investigation, implementation, and review without blocking the parent s
 - [Herdr](https://herdr.dev) and its CLI
 - `HERDR_ENV=1` — start Pi from inside Herdr
 
-Other terminal multiplexers are not supported. Outside Herdr, the extension skips automatic startup worktree inventory. Explicit inventory tools still report unavailable inspection as unknown. Worktrees isolate Git checkouts, not processes or permissions; child agents and installed Pi packages run with your user account's access.
+Other terminal multiplexers are not supported. Session startup skips worktree inventory to avoid blocking Pi initialization; use `/worktree list` or `worktree_list` to inspect managed worktrees. Outside Herdr, explicit inventory tools still report unavailable inspection as unknown. Worktrees isolate Git checkouts, not processes or permissions; child agents and installed Pi packages run with your user account's access.
 
 ## Install
 
@@ -576,7 +576,7 @@ subagent({
 | `skills`               | string  | —              | Comma-separated skill names                                                                       |
 | `tools`                | string  | —              | Comma-separated tool names                                                                        |
 | `cwd`                  | string  | —              | Working directory, or source repository when `worktree` is set (see [Role Folders](#role-folders)) |
-| `worktree`             | object  | —              | Isolated Herdr-managed Git worktree; requires `branch`, with optional `base` (committed `HEAD` by default) |
+| `worktree`             | object \| null | —          | Isolated Herdr-managed Git worktree; requires `branch`, with optional `base` (committed `HEAD` by default). Omit or pass `null` to use an ordinary pane in `cwd` when a client requires the property. |
 
 ### Naming coordinated children
 
@@ -589,7 +589,7 @@ prompts, handoffs, and results.
 
 ### Isolated worktree runs
 
-Use one worktree per parallel independent writing task; a single or sequential writer can work in the parent checkout, and read-only agents use ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
+Use one worktree per parallel independent writing task; a single or sequential writer can work in the parent checkout, and read-only agents use ordinary panes. Omit `worktree` for an ordinary pane; clients whose generated tool schema requires every property may send `worktree: null` with the same effect. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `cwd` is a linked checkout, Herdr provisioning uses the principal checkout while the requested checkout supplies the base SHA and manifest provenance. A successful launch from that linked checkout does not itself authorize cleanup there: cleanup checks the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. If cleanup is needed, start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use the normal explicit cleanup flow; changing directories inside an existing Pi session does not change its session cwd. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
 
 A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a coordinator that uses an ordinary pane for its child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings. A `read,bash` allowlist is not an enforced read-only boundary because shell commands can mutate files; report-only roles must restrict Bash to safe inspection and avoid artifact-generating verification in the reviewed checkout.
 
@@ -746,9 +746,9 @@ BTW shares the current working directory. It treats inherited work as reference
 
 Parent sessions can call `worktree_remove({ target: "<path|branch|workspace-id>", preserve: true })` or `/worktree remove <target> [--preserve]`. Preservation is optional and never implied: dirty work is blocked unless explicitly committed first or preserved as a WIP commit. The result reports its SHA even if removal later fails or is refused. A failed preservation commit restores the pre-preservation index and never proceeds to removal. Inventory and removal reports disclose exact ignored-file counts: enumeration is streamed rather than buffered as one listing. Ignored files do not block cleanup and are not captured by preservation; failed counting still blocks removal.
 
-Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
+Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
 
-Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session start only reports retained-worktree counts. Child sessions retain `/worktree list` and `/worktree <name>`, but receive neither cleanup tools nor the remove subcommand. Their repository-local listing labels detached entries `(detached HEAD)`; a detached sibling does not prevent inspection of named branches. See [cleanup and recovery](docs/worktree-subagents.md#cleanup) for details.
+Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. Child sessions retain `/worktree list` and `/worktree <name>`, but receive neither cleanup tools nor the remove subcommand. Their repository-local listing labels detached entries `(detached HEAD)`; a detached sibling does not prevent inspection of named branches. See [cleanup and recovery](docs/worktree-subagents.md#cleanup) for details.
 
 ## Custom Agents
 

package/docs/adr/0011-explicit-worktree-cleanup.md

@@ -47,7 +47,7 @@ only the cleanup tools and removal subcommand are parent-only.
 
 Open workspaces are removed through Herdr. Git-only orphans use Git removal,
 verify checkout absence, and then prune stale registrations. Branches and their
-commits are retained. Session start only reports inventory counts.
+commits are retained. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory.
 
 ## Rejected alternatives
 

package/docs/worktree-subagents.md

@@ -36,17 +36,19 @@ subagent({
 });
 ```
 
+Omit `worktree` for an ordinary pane. If a generated tool client requires every declared property, pass `worktree: null`; the extension treats it exactly like omission and starts the child in `cwd` without calling `herdr worktree create`.
+
 Worktrees isolate checkouts, indexes, and `HEAD`. They are **not security sandboxes**: worktrees still share the repository's object database and most refs, and the child process has the same host permissions as Pi.
 
 ## Launch contract
 
 For a worktree launch:
 
-- `cwd` selects the source Git repository. A relative tool argument is resolved from the parent Pi process's current directory.
+- `cwd` selects the source Git repository. A relative tool argument is resolved from the parent Pi process's current directory. When `cwd` is a linked checkout, Herdr provisioning uses its principal checkout while the requested checkout supplies the base SHA and manifest provenance.
 - `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 retained root pane and newly owned `Agents` tab. Finishing Pi returns to the interactive checkout shell; it does not close the 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. A successful launch from a linked checkout does not itself authorize cleanup there: cleanup checks the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd.
 - 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.
 
@@ -217,7 +219,7 @@ Parent sessions have an inspect-only inventory and an explicit removal surface:
 
 The equivalent tools are `worktree_list({})` and `worktree_remove({ target, preserve?: true })`. Use the exact path when a branch name is ambiguous. Children are not offered these tools or `/worktree remove`. Their existing `/worktree list` (repository-local Herdr listing) and `/worktree <name>` handoff remain available. Detached entries are labeled `(detached HEAD)` in the child listing and do not prevent cleanup inspection of named-branch siblings; the detached checkout itself remains blocked.
 
-Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
+Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. For linked checkouts, this means the canonical principal/source repository under the invoking parent session's cwd; a successful launch does not itself authorize cleanup, and authorization does not use `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
 
 Removal rechecks containment, Git registration, no detected process holder, known live child, or persistent-specialist lease, and no uncommitted, untracked, or conflicted files. Liveness checks observable same-user processes from any session with a cwd inside the checkout, regardless of runtime name (including thread-suffixed Node names). Only Herdr-confirmed idle retained shell PIDs are exempt; an active runtime at the same PID is not. Detached HEAD, locked checkouts, initialized submodules, and conflicting identity evidence block removal. For initialized submodules, deinitialize them deliberately or use operator removal. No force option is provided.
 
@@ -231,7 +233,7 @@ Ignored files do not block cleanup. Inventory shows their exact file count, and
 
 Open workspaces are removed through Herdr. Git-only orphans use `git worktree remove`, verify checkout absence, and then prune stale Git registrations. Failed removal is reported, never forced. A reachable owned manifest is merge-updated to `removed` with `workspaceRemovedAt` only after success; absent cross-session manifests are reported and are not rewritten. A manifest update failure after removal is a removed-with-warning result, not a failed removal. Removed manifests provide already-removed no-op evidence only; a new checkout at the same path is classified independently. Missing and dangling manifest paths are non-matches. Permission errors, symlink loops, and other undecidable manifest identities remain blockers, as do genuine identity disagreements. Cleanup Git and Herdr calls have 30-second timeouts; a timed-out operation fails closed rather than proceeding with removal.
 
-Branches and their commits are always retained: cleanup never deletes, force-updates, or rewrites a branch. It never runs on completion, shutdown, or a timer. Inside Herdr with its CLI available, parent session start emits only one compact inventory count when contained worktrees remain. Outside Herdr, startup skips the automatic inventory; explicit inventory tools remain available and report unavailable inspection as unknown. Unsupported platforms or failed global process enumeration block removal; individual visibility gaps are disclosed warnings, never proof that an orphan is idle.
+Branches and their commits are always retained: cleanup never deletes, force-updates, or rewrites a branch. It never runs on completion, shutdown, or a timer. Session startup skips worktree inventory to avoid blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. Outside Herdr, explicit inventory tools remain available and report unavailable inspection as unknown. Unsupported platforms or failed global process enumeration block removal; individual visibility gaps are disclosed warnings, never proof that an orphan is idle.
 
 ## Current limits
 

package/package.json

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

package/pi-extension/subagents/index.ts

@@ -129,7 +129,6 @@ import {
 	listContainedWorktrees,
 	removeContainedWorktree,
 	formatWorktreeInventory,
-	worktreeInventoryNotice,
 	type WorktreeCleanupOperations,
 } from "./worktree-cleanup.ts";
 import {
@@ -282,19 +281,28 @@ const SubagentParams = Type.Object({
 		}),
 	),
 	worktree: Type.Optional(
-		Type.Object({
-			branch: Type.String({
-				minLength: 1,
-				description:
-					"New branch name for an isolated Herdr-managed Git worktree",
-			}),
-			base: Type.Optional(
-				Type.String({
-					description:
-						"Git revision to branch from. Defaults to the source checkout's committed HEAD.",
+		Type.Union(
+			[
+				Type.Object({
+					branch: Type.String({
+						minLength: 1,
+						description:
+							"New branch name for an isolated Herdr-managed Git worktree",
+					}),
+					base: Type.Optional(
+						Type.String({
+							description:
+								"Git revision to branch from. Defaults to the source checkout's committed HEAD.",
+						}),
+					),
 				}),
-			),
-		}),
+				Type.Null(),
+			],
+			{
+				description:
+					"Optional isolated Herdr-managed Git worktree. Omit or pass null to use an ordinary pane in cwd.",
+			},
+		),
 	),
 	fork: Type.Optional(
 		Type.Boolean({
@@ -1218,7 +1226,7 @@ interface PartialSubagentArgs {
 	task?: unknown;
 	agent?: unknown;
 	cwd?: unknown;
-	worktree?: PartialWorktreeArgs;
+	worktree?: PartialWorktreeArgs | null;
 }
 
 function sendSubagentResult(
@@ -2422,6 +2430,7 @@ export const __test__ = {
 	resolveUnexpectedErrorPresentation,
 	shouldAdvanceToFallback,
 	deliverPersistentTaskEvent,
+	drainPersistentTaskEvents,
 	notifyPersistentCrash,
 	sendSubagentResult,
 	shouldRetainSubagentSurface,
@@ -2657,11 +2666,13 @@ function deliverPersistentTaskEvent(
 	running: RunningSubagent,
 	event: ReturnType<typeof readPersistentTaskEvents>[number],
 	api: Pick<ExtensionAPI, "sendMessage">,
+	ledgerSnapshot?: ReturnType<typeof readPersistentDeliveryLedger>,
 ): void {
 	if (!running.persistent || event.generation !== running.generationId) return;
 	const deliveryKey = `${running.id}:${event.type}:${event.task}`;
 	if (inFlightPersistentTaskDeliveries.has(deliveryKey)) return;
-	const ledger = readPersistentDeliveryLedger(running.sessionFile);
+	const ledger =
+		ledgerSnapshot ?? readPersistentDeliveryLedger(running.sessionFile);
 	if (event.type === "help-request") {
 		if (
 			ledger.some(
@@ -2685,13 +2696,15 @@ function deliverPersistentTaskEvent(
 				},
 				{ triggerTurn: true, deliverAs: "steer" },
 			);
-			appendPersistentDeliveryLedger(running.sessionFile, {
-				task: event.task,
-				outcome: "help-requested",
-				generation: running.generationId!,
-				logicalId: running.logicalId!,
-				policyHash: running.policyHash!,
-			});
+			ledger.push(
+				appendPersistentDeliveryLedger(running.sessionFile, {
+					task: event.task,
+					outcome: "help-requested",
+					generation: running.generationId!,
+					logicalId: running.logicalId!,
+					policyHash: running.policyHash!,
+				}),
+			);
 			if (running.taskId === event.task) running.taskId = undefined;
 		} finally {
 			inFlightPersistentTaskDeliveries.delete(deliveryKey);
@@ -2724,13 +2737,15 @@ function deliverPersistentTaskEvent(
 				policyHash: running.policyHash!,
 			},
 		);
-		appendPersistentDeliveryLedger(running.sessionFile, {
-			task: event.task,
-			outcome: "delivered",
-			generation: running.generationId!,
-			logicalId: running.logicalId!,
-			policyHash: running.policyHash!,
-		});
+		ledger.push(
+			appendPersistentDeliveryLedger(running.sessionFile, {
+				task: event.task,
+				outcome: "delivered",
+				generation: running.generationId!,
+				logicalId: running.logicalId!,
+				policyHash: running.policyHash!,
+			}),
+		);
 		running.tasksCompleted = completed;
 		if (running.taskId === event.task) running.taskId = undefined;
 		if (running.stopState === "pending")
@@ -2743,13 +2758,25 @@ function deliverPersistentTaskEvent(
 function drainPersistentTaskEvents(
 	running: RunningSubagent,
 	api: Pick<ExtensionAPI, "sendMessage">,
+	readLedger = readPersistentDeliveryLedger,
 ): void {
 	const events = readPersistentTaskEvents(running.sessionFile);
+	let ledger: ReturnType<typeof readPersistentDeliveryLedger> | undefined;
 	for (const event of events.slice(running.observedTaskEvents ?? 0)) {
+		if (!running.persistent || event.generation !== running.generationId)
+			continue;
+		if (
+			inFlightPersistentTaskDeliveries.has(
+				`${running.id}:${event.type}:${event.task}`,
+			)
+		)
+			continue;
+		ledger ??= readLedger(running.sessionFile);
 		deliverPersistentTaskEvent(
 			running,
 			event,
 			selectCompletionApi(api, runtime.pi),
+			ledger,
 		);
 	}
 	running.observedTaskEvents = events.length;
@@ -3131,19 +3158,6 @@ export default function subagentsExtension(
 			startStatusRefresh(pi);
 			updateWidget();
 		}
-		if (parentSession && ctx.cwd && ctx.hasUI && isTerminalAvailable()) {
-			try {
-				const notice = worktreeInventoryNotice(
-					await listContainedWorktrees(cleanupInput(ctx)),
-				);
-				if (notice) ctx.ui.notify(notice, "info");
-			} catch (error) {
-				ctx.ui.notify(
-					`Worktree inventory unavailable: ${error instanceof Error ? error.message : String(error)}`,
-					"warning",
-				);
-			}
-		}
 	});
 
 	// Clean up on session shutdown

package/pi-extension/subagents/launch.ts

@@ -84,7 +84,7 @@ export interface FreshPiLaunchRequest {
 	task: string;
 	agent?: string;
 	cwd?: string;
-	worktree?: { branch: string; base?: string };
+	worktree?: { branch: string; base?: string } | null;
 	fork?: boolean;
 	handoff?: { leafId: string };
 	surface?: string;
@@ -391,6 +391,7 @@ function prepareLaunchSurface(
 
 	const baseRef = request.worktree.base ?? "HEAD";
 	const baseSha = resolveGitCommit(resolved.sourceCwd, baseRef);
+	const provisionCwd = resolveWorktreeProvisionCwd(resolved.sourceCwd);
 	const manifestFile = join(
 		resolved.artifactDir,
 		"worktree-runs",
@@ -414,7 +415,7 @@ function prepareLaunchSurface(
 	try {
 		created = operations.createWorktree(
 			request.name,
-			resolved.sourceCwd,
+			provisionCwd,
 			request.worktree.branch,
 			baseSha,
 		);
@@ -918,6 +919,50 @@ function resolveGitCommit(cwd: string, ref: string): string {
 	}).trim();
 }
 
+function resolveWorktreeProvisionCwd(sourceCwd: string): string {
+	let gitDir: string;
+	let commonDir: string;
+	try {
+		gitDir = resolveGitPath(sourceCwd, "--git-dir");
+		commonDir = resolveGitPath(sourceCwd, "--git-common-dir");
+	} catch (error) {
+		throw new Error(
+			`Unable to identify the Git checkout for worktree provisioning from ${sourceCwd}: ${errorMessage(error)}`,
+		);
+	}
+	if (gitDir === commonDir) return sourceCwd;
+
+	try {
+		const output = execFileSync(
+			"git",
+			["worktree", "list", "--porcelain", "-z"],
+			{ cwd: sourceCwd },
+		).toString("utf8");
+		const principal = output
+			.split("\0")
+			.find((record) => record.startsWith("worktree "))
+			?.slice("worktree ".length);
+		if (!principal) throw new Error("Git returned no principal worktree");
+		return principal;
+	} catch (error) {
+		throw new Error(
+			`Unable to determine the principal Git checkout for linked worktree ${sourceCwd}: ${errorMessage(error)}`,
+		);
+	}
+}
+
+function resolveGitPath(
+	cwd: string,
+	flag: "--git-dir" | "--git-common-dir",
+): string {
+	const output = execFileSync(
+		"git",
+		["rev-parse", "--path-format=absolute", flag],
+		{ cwd, encoding: "utf8" },
+	);
+	return output.endsWith("\n") ? output.slice(0, -1) : output;
+}
+
 export function readWorktreeManifest(path: string): JsonObject | undefined {
 	try {
 		const value: unknown = JSON.parse(readFileSync(path, "utf8"));

package/pi-extension/subagents/worktree-cleanup.ts

@@ -214,7 +214,12 @@ export function formatWorktreeInventory(
 	rows: WorktreeInventoryEntry[],
 ): string {
 	return (
-		rows
+		[...rows]
+			.sort(
+				(a, b) =>
+					Number(a.contained) - Number(b.contained) ||
+					a.path.localeCompare(b.path),
+			)
 			.map(
 				(row) =>
 					`${row.branch ?? "unknown branch"} — ${row.path}\nSource: ${row.sourceRepo ?? "unknown"} · workspace: ${row.workspaceId ?? "none"} · manifest: ${row.manifest.length ? row.manifest.map(({ value }) => value.state ?? "unknown").join(", ") : "absent"}\n${row.classification} · Git: ${row.git ? `${row.git.dirtyFiles} dirty, ${row.git.untrackedFiles} untracked, ${row.git.ignoredFiles} ignored, ${row.git.conflicts} conflicts` : "unknown"}${row.blockers.length ? ` · ${row.blockers.join("; ")}` : " · clean"}${row.warnings.length ? `\nWarning: ${row.warnings.join("; ")}` : ""}`,
@@ -223,17 +228,6 @@ export function formatWorktreeInventory(
 	);
 }
 
-export function worktreeInventoryNotice(
-	rows: WorktreeInventoryEntry[],
-): string | undefined {
-	const present = rows.filter((row) => row.contained);
-	if (!present.length) return undefined;
-	const eligible = present.filter(
-		(row) => row.classification === "eligible",
-	).length;
-	return `Worktrees: ${present.length} present · ${eligible} eligible · ${present.length - eligible} blocked. /worktree list`;
-}
-
 export async function removeContainedWorktree(
 	input: CleanupInput & { target: string; preserve?: boolean },
 ): Promise<WorktreeRemovalResult> {
@@ -552,6 +546,8 @@ function processHolders(
 	const blockers: string[] = [];
 	const unreadable = new Set<string>();
 	const shellNames = new Set(["bash", "zsh", "fish", "sh", "dash"]);
+	const checkout =
+		platform === "linux" || platform === "darwin" ? realpathSync(path) : path;
 	if (!process.getuid) throw new Error("Process user identity unavailable");
 	const uid = process.getuid();
 	if (platform === "linux") {
@@ -571,7 +567,7 @@ function processHolders(
 				// A shell can exec a runtime without changing PID/process group.
 				if (idleShellPids.has(Number(pid)) && shellNames.has(command)) continue;
 				const cwd = realpathSync(`${procRoot}/${pid}/cwd`);
-				if (contained(path, cwd))
+				if (contained(checkout, cwd))
 					blockers.push(`Live process ${pid} holds the checkout`);
 			} catch (error) {
 				// SAFETY: filesystem probes throw Node errors with an optional errno code.
@@ -644,7 +640,7 @@ function processHolders(
 			try {
 				if (!cwd || !isAbsolute(cwd))
 					throw new Error("Process cwd unavailable");
-				if (contained(path, realpathSync(cwd)))
+				if (contained(checkout, realpathSync(cwd)))
 					blockers.push(`Live process ${pid} holds the checkout`);
 			} catch {
 				unreadable.add(pid);