@hcflabs/pi-subagent 28.1.0 → 28.2.2

package/README.md

@@ -43,7 +43,7 @@ Commands, prompts, and UI are for you. Tools and the packaged skill are for Main
 | `subagent_abort` | tool | Terminate an isolated request without discarding retained work. Retained candidates and integration work require release or proof of absence. |
 | `git_read` | tool | Let Role-declared children inspect bounded local Git evidence without Bash, tests, network access, or writes. Not available to Main. |
 | `pi-subagent` | skill | Guide Main through authorization, delegation, checks, integration, and recovery. |
-| Direct status widget (`D`) | ui | Show direct references, names, Role badges, status, routes, elapsed time, measured task tokens, cost, and tool activity in the TUI. |
+| Direct status widget (`D`) | ui | Show direct workflows as a tree under `Main` with references, names, Role badges, status, routes, elapsed time, measured task tokens, cost, and tool activity. In fullscreen mode, a click on a working row focuses that worker's verified Herdr pane. |
 | Isolated status widget (`I`) | ui | Show recorded task state, Role/model-class badges, and retained workspaces in the TUI. Readiness does not mean promotion. |
 
 `delegate_task`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort` are model-only. Main must make these decisions visibly; `codemode` scripts can call only `subagent_status`.
@@ -108,6 +108,8 @@ When Pi runs in a parent directory that holds many repositories, set `repo` to s
 
 The worker opens in the current Herdr workspace with the Repository target as its working directory. Change reports and stale-read checks use that checkout, and each result names its `repo`. A write request reserves the checkout of each target at one time, so writers in different repositories can run together. When Pi runs in a parent directory that is not a Git repository, each Main call that can write covers the whole parent. Such a call waits while a direct writer owns the checkout of any Repository target in it. Main can still read files and use `subagent_repos`.
 
+A `herdr_command` job with write access blocks direct writers in its checkout until `stop` proves that the job ended.
+
 An isolated request accepts one `repo` for the whole graph. Tasks cannot select another repository. The request then uses the Repository target as its checkout. State, worker worktrees, validation, and promotion belong to that repository. The Pi working directory does not change.
 
 Your Herdr workspace can belong to another checkout or to none. Herdr opens the primary workspace of the target when it opens the first worker worktree, and it does not close that workspace later. Pass the same `repo` to `subagent_status`, `subagent_resume`, `subagent_stage`, `subagent_integrate`, and `subagent_abort`.
@@ -277,7 +279,7 @@ The built-in reviewer answers exactly `PASS` when it finds no actionable correct
 
 The built-in reviewer and scout include `git_read`; existing user reviewers and scouts must add it to `tools`. No additional extension or Bash access is necessary. See [Reviewer Git inspection](./docs/orchestration.md#reviewer-git-inspection) for operations, parameters, limits, and Git requirements.
 
-Children load only declared resources and required adapters. Roles must list their model provider extension. `codemode` requires both `builtin:codemode` in `extensions` and `codemode` in `tools`. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work. Main-only delegation, integration, and recovery tools, `herdr_handoff`, and `ask_question` stay unavailable to children.
+Children load only declared resources and required adapters. Roles must list their model provider extension. `codemode` requires both `builtin:codemode` in `extensions` and `codemode` in `tools`. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work. Main-only delegation, integration, and recovery tools, `herdr_handoff`, `herdr_command`, and `ask_question` stay unavailable to children.
 
 Read [Role and resource policy](./docs/orchestration.md#role-and-resource-policy) for extension exposure, MCP validation, OAuth constraints, and child budgets. Project MCP overrides cannot change a Role's global allowlist or exposure.
 

package/dist/direct-herdr.d.ts

@@ -20,6 +20,8 @@ export interface DirectHandle {
     partialText(maxChars: number): Promise<string | undefined>;
     /** Display-only activity from the last usage() sample. */
     readonly activity?: DirectToolActivity;
+    /** Focus the worker pane after Herdr confirms the exact launched agent still owns it. */
+    focus(): Promise<void>;
     cancel(): Promise<void>;
 }
 export declare function exactDirectTerminalTurn(jsonl: string, prompt: string): boolean;

package/dist/direct-herdr.js

@@ -86,6 +86,9 @@ export function exactDirectTerminalTurn(jsonl, prompt) {
     return reason === "stop" || reason === "error" || reason === "aborted";
 }
 const turnSuffix = (turn) => `\n\nTurn identity: ${turn}`;
+/** How long to wait for Pi to retry a turn that ended with a provider error, and how many times. */
+const PROVIDER_RETRY_GRACE_MS = 65_000;
+const PROVIDER_RETRY_WAITS = 5;
 /** Refuse continuation unless the saved session's exact recorded turn is terminal and no later user turn exists. */
 export async function assertSettledDirectSession(sessionFile, turn) {
     const info = await stat(sessionFile).catch((error) => {
@@ -481,36 +484,70 @@ export function createDirectHerdr(pi, cwd, idleMs) {
                                 deadline = Date.now() + idleMs;
                             }
                         };
-                        while (current === "working" || current === "idle") {
-                            // A turn may finish before observation begins (or between waits).
-                            if (current === "idle") {
-                                const answer = await maybeAnswer();
-                                if (answer !== undefined)
-                                    return answer;
-                            }
-                            await observeProgress();
-                            const remaining = deadline - Date.now();
-                            if (remaining <= 0)
-                                throw new Error(`Herdr agent in tab ${tabId} made no progress for ${idleMs}ms; inspect ${sessionFile} before retrying.`);
-                            const args = ["agent", "wait", name,
-                                ...(current === "idle" ? ["--until", "working"] : ["--until", "idle"]),
-                                "--until", "done", "--until", "blocked", "--until", "unknown",
-                                "--timeout", String(Math.max(1, Math.min(current === "idle" ? 1000 : OPERATION_MS - 1000, remaining)))];
+                        let retryWaits = 0;
+                        // A provider error, such as HTTP 429, ends a turn with stopReason "error", and Pi can then retry it.
+                        // Wait a bounded time for the retry before the error counts as the final answer.
+                        const retryPending = async () => {
+                            if (retryWaits >= PROVIDER_RETRY_WAITS)
+                                return false;
+                            const info = await stat(sessionFile).catch(() => undefined);
+                            if (!info || info.size > SESSION_LIMIT)
+                                return false;
+                            if (exactFinalTurn(await readFile(sessionFile, "utf8"), prompt)?.stopReason !== "error")
+                                return false;
+                            retryWaits += 1;
+                            const args = ["agent", "wait", name, "--until", "working", "--timeout", String(PROVIDER_RETRY_GRACE_MS)];
                             const waited = await herdr.exec(args, options(signal));
                             if (waited.code !== 0 || waited.killed) {
-                                if (!waited.killed && hasHerdrErrorCode(waited, "timeout")) {
-                                    continue;
-                                }
+                                if (!waited.killed && hasHerdrErrorCode(waited, "timeout"))
+                                    return false;
                                 throw new Error(herdrCommandFailure(args, waited));
                             }
-                            const next = inspect(JSON.parse(waited.stdout), "agent_info", name, paneId, tabId);
-                            if (next !== current)
-                                deadline = Date.now() + idleMs;
-                            current = next;
+                            current = inspect(JSON.parse(waited.stdout), "agent_info", name, paneId, tabId);
+                            deadline = Date.now() + idleMs;
+                            return current === "working";
+                        };
+                        for (;;) {
+                            while (current === "working" || current === "idle") {
+                                // A turn may finish before observation begins (or between waits).
+                                if (current === "idle") {
+                                    const answer = await maybeAnswer();
+                                    if (answer !== undefined)
+                                        return answer;
+                                }
+                                await observeProgress();
+                                const remaining = deadline - Date.now();
+                                if (remaining <= 0)
+                                    throw new Error(`Herdr agent in tab ${tabId} made no progress for ${idleMs}ms; inspect ${sessionFile} before retrying.`);
+                                const args = ["agent", "wait", name,
+                                    ...(current === "idle" ? ["--until", "working"] : ["--until", "idle"]),
+                                    "--until", "done", "--until", "blocked", "--until", "unknown",
+                                    "--timeout", String(Math.max(1, Math.min(current === "idle" ? 1000 : OPERATION_MS - 1000, remaining)))];
+                                const waited = await herdr.exec(args, options(signal));
+                                if (waited.code !== 0 || waited.killed) {
+                                    if (!waited.killed && hasHerdrErrorCode(waited, "timeout")) {
+                                        continue;
+                                    }
+                                    throw new Error(herdrCommandFailure(args, waited));
+                                }
+                                const next = inspect(JSON.parse(waited.stdout), "agent_info", name, paneId, tabId);
+                                if (next !== current)
+                                    deadline = Date.now() + idleMs;
+                                current = next;
+                            }
+                            if (current !== "done")
+                                throw new Error(`Herdr agent in tab ${tabId} became ${current}; inspect it before retrying.`);
+                            const answer = await maybeAnswer();
+                            if (answer !== undefined)
+                                return answer;
+                            if (!await retryPending())
+                                return readAnswer();
                         }
-                        if (current !== "done")
-                            throw new Error(`Herdr agent in tab ${tabId} became ${current}; inspect it before retrying.`);
-                        return readAnswer();
+                    },
+                    async focus() {
+                        // A reused pane ID must not receive focus: the agent identity must match the launch first.
+                        inspect(await herdr.json(["agent", "get", paneId], options()), "agent_info", name, paneId, tabId);
+                        await herdr.json(["agent", "focus", paneId], options());
                     },
                     async cancel() {
                         await herdr.json(["agent", "send-keys", name, "ctrl+c"], options());

package/dist/index.d.ts

@@ -19,7 +19,7 @@ export declare function roleToolPolicyFromArgv(args: readonly string[]): string[
  * `codemode` or `deferred` exposure. Loading `builtin:codemode` alone registers the tool inactive.
  */
 export declare function roleActivatesCodemode(tools: readonly string[]): boolean;
-export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "subagent_status", "subagent_resume", "subagent_stage", "subagent_integrate", "subagent_abort", "herdr_handoff"];
+export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "subagent_status", "subagent_resume", "subagent_stage", "subagent_integrate", "subagent_abort", "herdr_handoff", "herdr_command"];
 export declare const DELEGATE_TASK: {
     readonly id: "pi-subagent/delegateTask";
     readonly label: "Subagent delegation";

package/dist/index.js

@@ -68,6 +68,7 @@ export const CHILD_EXCLUDED_TOOL_NAMES = [
     "subagent_integrate",
     "subagent_abort",
     "herdr_handoff",
+    "herdr_command",
 ];
 const SYSTEM_PROMPT_FLAG = "--append-system-prompt";
 const CHILD_IDENTITY_POLICY = "You are a delegated Pi Subagent, not Main. Execute the assigned Role and task directly. Main-only delegation rules do not apply. Recursive delegation is unavailable; do not seek or invoke delegation tools.";

package/dist/process-lease.d.ts

@@ -1,5 +1,2 @@
-import type { HerdrExecResult } from "@hcflabs/pi-herdr";
+export { assertPrivateLease, scanProcessLease } from "@hcflabs/pi-process";
 export declare const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
-export declare function assertPrivateLease(path: string, allowMissing: boolean): Promise<boolean>;
-/** Shared exact process-lease evidence for direct and isolated workers. */
-export declare function scanProcessLease(path: string, execute: (args: string[]) => Promise<HerdrExecResult>, pid?: number, allowMissing?: boolean): Promise<number[]>;

package/dist/process-lease.js

@@ -1,43 +1,2 @@
-import { lstat } from "node:fs/promises";
+export { assertPrivateLease, scanProcessLease } from "@hcflabs/pi-process";
 export const PI_SUBAGENT_PROCESS_LEASE = "PI_SUBAGENT_PROCESS_LEASE";
-export async function assertPrivateLease(path, allowMissing) {
-    let info;
-    try {
-        info = await lstat(path);
-    }
-    catch (error) {
-        if (allowMissing && error.code === "ENOENT")
-            return false;
-        throw new Error(`Exact process lease cannot be inspected: ${path}`, { cause: error });
-    }
-    const uid = process.getuid?.();
-    if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o777) !== 0o600 || (uid !== undefined && info.uid !== uid)) {
-        throw new Error("Exact process lease must be a current-user regular non-symlink mode-0600 file.");
-    }
-    return true;
-}
-/** Shared exact process-lease evidence for direct and isolated workers. */
-export async function scanProcessLease(path, execute, pid, allowMissing = false) {
-    if (!await assertPrivateLease(path, allowMissing))
-        return [];
-    // -w: host-wide warnings (for example an unreachable network mount) are not lease evidence; real errors still reach stderr.
-    const args = ["-w", "-nP", "-a", ...(pid === undefined ? [] : ["-p", String(pid)]), "-F", "p", "--", path];
-    const result = await execute(args);
-    if (result.killed || ![0, 1].includes(result.code) || (result.code === 1 && (result.stdout.trim() || result.stderr.trim()))) {
-        throw new Error("Exact process lease lsof scan failed or was ambiguous.");
-    }
-    if (result.code === 1)
-        return [];
-    if (result.stderr.trim())
-        throw new Error("Exact process lease lsof scan returned unexpected diagnostics.");
-    // lsof always selects the file descriptor field, so `-F p` also emits `f<fd>` lines.
-    const lines = result.stdout.trim().split(/\r?\n/).filter((line) => line && !/^f\w+$/.test(line));
-    if (!lines.length || lines.some((line) => !/^p[1-9]\d*$/.test(line))) {
-        throw new Error("Exact process lease lsof scan returned malformed PID fields.");
-    }
-    const holders = [...new Set(lines.map((line) => Number(line.slice(1))))];
-    if (holders.some((holder) => !Number.isSafeInteger(holder) || holder <= 0) || (pid !== undefined && holders.some((holder) => holder !== pid))) {
-        throw new Error("Exact process lease lsof scan returned an unexpected PID.");
-    }
-    return holders;
-}

package/docs/orchestration.md

@@ -95,6 +95,8 @@ Direct writes change Main's checkout immediately. They require no clean checkout
 
 A task with `repo` runs in that Repository target instead of Main's checkout. Admission resolves the target before the launch and reserves the checkout of each target at one time. Two checkouts conflict when one contains the other. Thus a Main call from a non-Git parent directory covers the checkout of every Repository target in it, and writers in two different Repository targets can run together. An invalid `repo` blocks the call before any reservation. Admission does not parse Bash text for a directory.
 
+A trusted tool can report long-running Main activity with two Pi events. `pi:checkout-activity:start` carries `{ jobId, cwd }`, and `pi:checkout-activity:end` carries `{ jobId }`. Admission treats an open activity as a Main call in progress in `cwd`, so a direct writer in a checkout that contains `cwd` cannot start. The activity ends only with its end event. `herdr_command` sends the end event after it proves that a write job stopped. The events coordinate one Pi session; they are not a sandbox.
+
 A write request runs its tasks in sequence. It holds checkout admission after the initial handle returns. Competing direct writers and Main writes fail until the extension proves that all owned workers stopped. To keep Main free to write, use `mode: isolated`. This mode gives worktree checks and explicit integration, not immediate changes to the shared checkout. Parallel read requests still run concurrently.
 
 A failure in a write request stops further dispatch, but a worker with an uncertain state can still run. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. Task outcome and worker termination are separate.
@@ -141,6 +143,8 @@ If the extension cannot prove termination of the stopped worker, the workflow ke
 
 The extension retrieves each final answer from its exact Pi session file, not its possibly truncated screen. Idle, blocked, unknown, or malformed answers fail with recoverable tab and session identities. No whole-run deadline applies.
 
+A provider error, such as HTTP 429, can end a worker turn before Pi retries it automatically. When the final turn has `stopReason: "error"`, the extension waits up to 65 seconds for the worker to work again, at most 5 times for one task. The task fails only when Pi does not retry in that time.
+
 The tasks in a request share a 40 KiB inline answer budget. Each worker prompt states its share. A longer exact answer is still a success. The result shows a UTF-8-safe prefix and a truncation marker. The marker gives the path of a private `answer-<turn>.md` file beside the session file, which holds the full answer. For a write task, the budget applies to the `answer` field of the completion object. A chain step receives the full answer of the previous step in `{previous}`; the budget applies only to the result for Main. The result details keep `answerFile` for each full-answer file. Recovery text includes these paths outside the output limit, even when checkout notes remove the inline link.
 
 Herdr accepts prompt text as one command argument. To stay below the operating system's argument limit, a task packet above 64 KiB uses a private, exclusively created `task-<turn>.md` file beside the session file. This packet includes the full chain context. The worker prompt requires the Role's `read` tool to read all parts with line offsets before work starts. Pi's native `read` can return a line of exactly 50 KiB (51,200 bytes), but not a longer line. If any packet line is longer, or `read` is absent, the worker uses the Role's `bash` tool. If a line is too long and `bash` is absent, the task fails before tab creation with the read limit and a request for `bash` or shorter lines. A Role with neither tool also fails before tab creation; the extension adds no tool. The task file stays available for recovery.
@@ -180,7 +184,19 @@ Each direct row starts with a saved direct reference such as `D7.1`. `D7` is the
 
 A session switch can move a workflow into a session that already uses its number. In that case, the workflow gets a new number there. An existing Herdr tab keeps its original launch label.
 
-The direct widget shows the launched model, thinking level, elapsed time, measured task tokens (`— tok` until usage is available), and cost next to the tokens (such as `$0.12`; not shown when unknown or zero). Failed rows show before working and completed rows. When rows overflow, `… N more` includes counts by status.
+The direct widget shows the launched model, thinking level, elapsed time, measured task tokens (`— tok` until usage is available), and cost next to the tokens (such as `$0.12`; not shown when unknown or zero). Failed workflows show before working and completed workflows. When rows overflow, the final `└─ … N more` row includes counts by status.
+
+The direct widget is a tree under a `Main` header. The header counts the workers by status. A workflow with one worker is one row. A workflow with more than one worker gets a group row, and its launched workers are child rows:
+
+```text
+Main · 2 working · 1 complete
+├─ ⠋ D7 · 2 workers
+│  ├─ ⠋ D7.1 [S] Map entry points · …
+│  └─ ⠋ D7.2 [S] Map tests · …
+└─ ✓ D8.1 [R] complete · Review patch · …
+```
+
+In Pi fullscreen mode, click a working worker row to focus its Herdr pane. Before the extension moves focus, Herdr must confirm that the pane still runs the exact launched agent. If the check fails, Pi shows a warning and focus does not change. The header, group rows, finished rows, the overflow row, and rows with a truncated reference do nothing when you click them. Regular mode leaves the mouse to the terminal. Use the Herdr tab label or `/subagent` to find a worker from the keyboard. A click moves focus only. It gives no ownership or control authority.
 
 The isolated widget shows the recorded task state and any retained workspace. It does not show reliable live model, thinking, or token readings from Herdr. Attention shows before ordinary work, and overflow uses `+N more · /subagent`. An aborted request with visible tasks has its own `request aborted` row. This row does not change the recorded statuses of the tasks.
 
@@ -467,7 +483,7 @@ Every child launch:
 2. loads only declared resources plus required internal adapters;
 3. resolves Skill and model names from Pi's effective registries;
 4. installs an exact tool policy;
-5. excludes Main-only delegation, integration, and recovery tools, `herdr_handoff`, and `ask_question`; and
+5. excludes Main-only delegation, integration, and recovery tools, `herdr_handoff`, `herdr_command`, and `ask_question`; and
 6. prepends the delegated-subagent identity contract.
 
 An empty `tools` list adds no base tools. Selected extension tools can still activate.
@@ -496,7 +512,7 @@ Before launch, the extension checks each selected entry against Pi's documented
 
 The extension never modifies the file. Fix the entry or choose another server. The extension passes valid `auth`, `oauth`, and `description` fields through, so Pi's native provider auth and OAuth apply. `oauth.clientRegistration` must be `dcr` or `cimd`. A `cimd` entry cannot use `clientId` or `clientName`. Any `callbackUrl` must use localhost or 127.0.0.1 with path `/callback`.
 
-The extension still ignores project MCP overrides. A project cannot change the global server allowlist or exposure of the Role. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. The extension excludes Main-only delegation, integration, and recovery tools, `herdr_handoff`, and `ask_question` from children.
+The extension still ignores project MCP overrides. A project cannot change the global server allowlist or exposure of the Role. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work starts. The extension excludes Main-only delegation, integration, and recovery tools, `herdr_handoff`, `herdr_command`, and `ask_question` from children.
 
 Isolated Herdr Role launches receive the same turn, token, and child-runtime budget metadata as ephemeral launches. Retained workers therefore keep one non-refilling session budget across follow-ups rather than receiving a new request budget.
 

package/extensions/admission.ts

@@ -1,4 +1,5 @@
 import { realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isWithin, resolveRepoTarget } from "@hcflabs/pi-repo";
 
@@ -24,6 +25,18 @@ async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<str
 	return await realpath(root);
 }
 
+/** A trusted tool reports a long-running Main command that can write in `cwd`. Payload: `{ jobId, cwd }`. */
+export const CHECKOUT_ACTIVITY_START = "pi:checkout-activity:start";
+/** The tool reports that the job's processes are proved stopped. Payload: `{ jobId }`. */
+export const CHECKOUT_ACTIVITY_END = "pi:checkout-activity:end";
+
+/** `herdr_command` writes only when it starts a job with write access. Read, stop, and read-access jobs do not write. */
+function writingMainCall(toolName: string, input: unknown): boolean {
+	if (toolName !== "herdr_command") return !MAIN_NON_WRITING_TOOLS.has(toolName);
+	const { action, access } = (input ?? {}) as { action?: unknown; access?: unknown };
+	return action === "start" && access !== "read";
+}
+
 /** Two scopes conflict when one contains the other. A non-Git parent directory covers its whole subtree. */
 const overlaps = (left: string, right: string) => isWithin(left, right) || isWithin(right, left);
 
@@ -64,7 +77,7 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, classifyDirect: (inp
 	};
 	pi.on("tool_call", async (event, ctx) => {
 		const direct = event.toolName === "delegate_task";
-		const classified = direct ? classifyDirect(event.input) : !MAIN_NON_WRITING_TOOLS.has(event.toolName);
+		const classified = direct ? classifyDirect(event.input) : writingMainCall(event.toolName, event.input);
 		if (classified === false) return;
 		const repos: ReadonlyArray<string | undefined> = classified === true ? [undefined] : classified;
 		const call: { direct: boolean; keys?: readonly string[] } = { direct };
@@ -95,6 +108,22 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, classifyDirect: (inp
 		}
 		call.keys = keys;
 	});
+	// A long-running Main activity is a Main call that stays in flight after its tool result.
+	// Its key is the command's directory, so it conflicts with a writer in the checkout that contains it.
+	pi.events.on(CHECKOUT_ACTIVITY_START, (data) => {
+		const { jobId, cwd } = (data ?? {}) as { jobId?: unknown; cwd?: unknown };
+		if (typeof jobId !== "string" || !jobId || typeof cwd !== "string" || !isAbsolute(cwd)) return;
+		const id = `activity:${jobId}`;
+		heldCalls.add(id);
+		calls.set(id, { direct: false, keys: [cwd] });
+	});
+	pi.events.on(CHECKOUT_ACTIVITY_END, (data) => {
+		const { jobId } = (data ?? {}) as { jobId?: unknown };
+		if (typeof jobId !== "string") return;
+		const id = `activity:${jobId}`;
+		heldCalls.delete(id);
+		release(id);
+	});
 	pi.on("tool_result", (event) => release(event.toolCallId));
 	pi.on("tool_execution_end", (event) => release(event.toolCallId));
 	pi.on("session_start", () => checkouts.clear());

package/extensions/isolated.ts

@@ -1,3 +1,4 @@
+import { lstat } from "node:fs/promises";
 import { basename, relative, sep } from "node:path";
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -914,10 +915,20 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		const invalidIds: string[] = [];
 		const selectorOf = (root: string) => found.repos.find((item) => item.root === root)?.repo
 			?? (isWithin(found.base, root) ? relative(found.base, root).split(sep).join("/") : root);
+		const warnings = discoveryWarnings(found);
 		for (const { repo, root } of found.repos) {
 			if (!current()) throw new Error("Session or branch changed; reopen /subagent.");
-			const listed = await getComponents().runner.listRequests(root);
-			const leaseLive = await getComponents().runner.hasProductiveRunLease(root);
+			let listed: Awaited<ReturnType<IsolatedRunner["listRequests"]>>;
+			let leaseLive: boolean;
+			try {
+				listed = await getComponents().runner.listRequests(root);
+				leaseLive = await getComponents().runner.hasProductiveRunLease(root);
+			} catch (error) {
+				// A repository removed after discovery has no requests to list. Other failures stay visible.
+				if ((error as NodeJS.ErrnoException).code === "ENOENT" && await lstat(root).then(() => false, () => true)) continue;
+				warnings.push(`Isolated inventory could not read repo ${repo}: ${boundedPublicText(error instanceof Error ? error.message : String(error))}`);
+				continue;
+			}
 			for (const request of listed.requests) requests.push({ ...request, root: request.root ?? root, repo, leaseLive, checkout: root });
 			invalidIds.push(...listed.invalidIds.map((id) => `${repo}/${id}`));
 		}
@@ -929,7 +940,7 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 		}
 		invalidIds.push(...orphans.invalidIds);
 		return { root: found.base, leaseLive: requests.some((request) => request.leaseLive), requests,
-			invalidIds: [...new Set(invalidIds)], warnings: discoveryWarnings(found) };
+			invalidIds: [...new Set(invalidIds)], warnings };
 	};
 	return {
 		async inventory(cwd, current) {
@@ -967,7 +978,10 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 				const found = await discoverRepos(cwd);
 				const lines: string[] = [];
 				for (const { repo, root: child } of found.repos) {
-					const listed = await getComponents().runner.listRequests(child);
+					const listed = await getComponents().runner.listRequests(child).catch(async (error: unknown) => {
+						if ((error as NodeJS.ErrnoException).code === "ENOENT" && await lstat(child).then(() => false, () => true)) return { requests: [], invalidIds: [] };
+						throw error;
+					});
 					if (!listed.requests.length && !listed.invalidIds.length) continue;
 					lines.push(`repo ${repo}:`, ...await recoveryLines(child));
 				}

package/extensions/subagent.ts

@@ -24,6 +24,10 @@ const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧",
 type WidgetStatus = "working" | "success" | "failure";
 type WidgetItem = {
 	ref: string;
+	/** Display numbers only; they group rows and never identify a pane. */
+	workflow: number;
+	worker: number;
+	workers: number;
 	role: string;
 	model: string;
 	thinkingLevel: string;
@@ -76,45 +80,88 @@ function activityLabel(activity: DirectToolActivity | undefined): string | undef
 	return parts.length ? parts.join(" · ") : undefined;
 }
 
+function renderWorkerRow(item: WidgetItem, width: number, now: number, spinnerIndex: number, theme: Theme): string {
+	const prefix = `${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", `${item.ref} ${item.role}`)} ${item.status === "working" ? "" : `${statusLabel(item.status)} · `}`;
+	const metrics = [
+		`${item.model}/${item.thinkingLevel}`,
+		tokenLabel(item.tokens, item.cost),
+		formatDuration((item.finishedAt ?? now) - item.startedAt),
+	];
+	const activity = activityLabel(item.activity);
+	if (activity) metrics.push(activity); // Activity is the first metric removed on narrow rows.
+	while (metrics.length && width - visibleWidth(prefix) - visibleWidth(` · ${metrics.join(" · ")}`) < 8) {
+		if (metrics.length === 2) metrics.shift(); // Preserve measured tokens ahead of route details.
+		else metrics.pop();
+	}
+	const suffix = metrics.length ? ` · ${theme.fg("muted", metrics.join(" · "))}` : "";
+	const name = truncateToWidth(theme.fg("text", item.name), Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)));
+	return truncateToWidth(`${prefix}${name}${suffix}`, width);
+}
+
+const STATUS_RANK: Record<WidgetStatus, number> = { failure: 0, working: 1, success: 2 };
+const STATUS_COUNT_ORDER = ["working", "failure", "success"] as const;
+
+function statusCounts(items: readonly WidgetItem[]): string {
+	const counts: Record<WidgetStatus, number> = { working: 0, success: 0, failure: 0 };
+	for (const { status } of items) counts[status] += 1;
+	return STATUS_COUNT_ORDER.flatMap((status) => counts[status] ? [`${counts[status]} ${statusLabel(status)}`] : []).join(" · ");
+}
+
+/** One rendered widget line. `focus` names a live worker item that a click may focus. */
+type WidgetRow = { text: string; focus?: string };
+type TreeLine = { top: number; child?: { last: boolean }; item?: [string, WidgetItem]; group?: WidgetItem[] };
+
+/**
+ * Render the direct widget as a tree under a Main header.
+ * A workflow with one launched worker is a leaf row. A workflow with more workers gets a group row.
+ * `focusable` tells which item IDs have a live handle. Only fully visible references become click targets.
+ */
 function renderWidgetRows(
-	items: WidgetItem[],
+	items: ReadonlyArray<[string, WidgetItem]>,
 	width: number,
 	now: number,
 	spinnerIndex: number,
 	theme: Theme,
-): string[] {
-	const ordered = [...items].sort((a, b) =>
-		(a.status === "failure" ? 0 : a.status === "working" ? 1 : 2)
-		- (b.status === "failure" ? 0 : b.status === "working" ? 1 : 2));
-	const visible = ordered.slice(0, ordered.length > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES);
-	const lines = visible.map((item) => {
-		const prefix = `${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", `${item.ref} ${item.role}`)} ${item.status === "working" ? "" : `${statusLabel(item.status)} · `}`;
-		const metrics = [
-			`${item.model}/${item.thinkingLevel}`,
-			tokenLabel(item.tokens, item.cost),
-			formatDuration((item.finishedAt ?? now) - item.startedAt),
-		];
-		const activity = activityLabel(item.activity);
-		if (activity) metrics.push(activity); // Activity is the first metric removed on narrow rows.
-		while (metrics.length && width - visibleWidth(prefix) - visibleWidth(` · ${metrics.join(" · ")}`) < 8) {
-			if (metrics.length === 2) metrics.shift(); // Preserve measured tokens ahead of route details.
-			else metrics.pop();
-		}
-		const suffix = metrics.length ? ` · ${theme.fg("muted", metrics.join(" · "))}` : "";
-		const name = truncateToWidth(theme.fg("text", item.name), Math.max(0, width - visibleWidth(prefix) - visibleWidth(suffix)));
-		return truncateToWidth(`${prefix}${name}${suffix}`, width);
+	focusable: (id: string) => boolean = () => false,
+): WidgetRow[] {
+	if (!items.length) return [];
+	const groups = new Map<number, Array<[string, WidgetItem]>>();
+	for (const entry of items) groups.set(entry[1].workflow, [...groups.get(entry[1].workflow) ?? [], entry]);
+	const rank = (list: ReadonlyArray<[string, WidgetItem]>) => Math.min(...list.map(([, item]) => STATUS_RANK[item.status]));
+	const ordered = [...groups].sort(([a, left], [b, right]) => rank(left) - rank(right) || a - b)
+		.map(([, list]) => list.sort(([, a], [, b]) => a.worker - b.worker));
+	const lines: TreeLine[] = [];
+	ordered.forEach((list, top) => {
+		if (list.length === 1 && list[0]![1].workers === 1) return void lines.push({ top, item: list[0]! });
+		lines.push({ top, group: list.map(([, item]) => item) });
+		list.forEach((entry, index) => lines.push({ top, child: { last: index === list.length - 1 }, item: entry }));
 	});
-	const hidden = ordered.slice(visible.length);
-	if (hidden.length) {
-		const counts: Record<WidgetStatus, number> = { working: 0, success: 0, failure: 0 };
-		for (const { status } of hidden) counts[status] += 1;
-		lines.push(truncateToWidth(theme.fg("muted", [
-			`… ${hidden.length} more`,
-			...(["working", "success", "failure"] as const).flatMap((status) =>
-				counts[status] ? [`${counts[status]} ${statusLabel(status)}`] : []),
-		].join(" · ")), width));
+	const visible = lines.length > MAX_WIDGET_LINES ? lines.slice(0, MAX_WIDGET_LINES - 1) : lines;
+	const hidden = lines.slice(visible.length).flatMap(({ item }) => item ? [item[1]] : []);
+	const lastTop = hidden.length ? -1 : visible.at(-1)!.top;
+	const rows: WidgetRow[] = [{ text: truncateToWidth(`${theme.fg("accent", "Main")}${theme.fg("muted", ` · ${statusCounts(items.map(([, item]) => item))}`)}`, width) }];
+	for (const line of visible) {
+		const topLast = line.top === lastTop;
+		const connector = line.child
+			? `${topLast ? "   " : "│  "}${line.child.last ? "└─ " : "├─ "}`
+			: topLast ? "└─ " : "├─ ";
+		const branch = theme.fg("dim", connector);
+		const room = Math.max(0, width - visibleWidth(connector));
+		if (line.group) {
+			const status = line.group.reduce<WidgetStatus>((best, { status }) => STATUS_RANK[status] < STATUS_RANK[best] ? status : best, "success");
+			const first = line.group[0]!;
+			const label = `${statusGlyph(status, spinnerIndex, theme)} ${theme.fg("accent", `D${first.workflow}`)}${theme.fg("muted", ` · ${first.workers} workers`)}`;
+			rows.push({ text: truncateToWidth(`${branch}${truncateToWidth(label, room)}`, width) });
+			continue;
+		}
+		const [id, item] = line.item!;
+		const text = truncateToWidth(`${branch}${renderWorkerRow(item, room, now, spinnerIndex, theme)}`, width);
+		// The glyph, a space, and the full reference must be visible before a click can name this worker.
+		const referenceVisible = visibleWidth(connector) + 2 + visibleWidth(item.ref) <= width;
+		rows.push({ text, ...(item.status === "working" && referenceVisible && focusable(id) ? { focus: id } : {}) });
 	}
-	return lines;
+	if (hidden.length) rows.push({ text: truncateToWidth(`${theme.fg("dim", "└─ ")}${theme.fg("muted", `… ${hidden.length} more · ${statusCounts(hidden)}`)}`, width) });
+	return rows;
 }
 
 function replaceRouteModel(ctx: ExtensionContext, reference: string, route: ResolvedTaskRoute): ResolvedTaskRoute {
@@ -460,14 +507,45 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		widgetTimer.unref();
 	};
 
+	let focusInFlight = false;
+	// A click is a request only. The handle checks the exact Herdr agent identity before it moves focus.
+	const focusWorker = (id: string) => {
+		const handle = tokenHandles.get(id);
+		const item = widgetItems.get(id);
+		if (!handle || item?.status !== "working" || focusInFlight) return;
+		const epoch = sessionEpoch;
+		const ctx = latestCtx;
+		focusInFlight = true;
+		void handle.focus().catch((error: unknown) => {
+			if (epoch === sessionEpoch && ctx?.hasUI) {
+				ctx.ui.notify(`Cannot focus ${item.ref}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+			}
+		}).finally(() => { focusInFlight = false; });
+	};
+
 	const ensureWidget = (ctx: ExtensionContext) => {
 		if (!ctx.hasUI || widgetInstalled) return;
 		widgetInstalled = true;
 		ctx.ui.setWidget(WIDGET_KEY, (tui, theme): Component => {
 			activeTui = tui;
+			let renderedWidth = -1;
+			let hits: Array<{ row: number; to: number; id: string }> = [];
 			return {
 				invalidate() {},
-				render: (width) => renderWidgetRows([...widgetItems.values()], width, Date.now(), spinnerIndex, theme),
+				render(width) {
+					const rows = renderWidgetRows([...widgetItems], width, Date.now(), spinnerIndex, theme, (id) => tokenHandles.has(id));
+					renderedWidth = width;
+					hits = rows.flatMap(({ text, focus }, row) => focus ? [{ row, to: visibleWidth(text), id: focus }] : []);
+					return rows.map(({ text }) => text);
+				},
+				// Pi routes mouse events only in fullscreen mode. Regular mode keeps terminal selection.
+				handleMouse(event) {
+					if (event.type !== "click" || event.button !== "left" || event.width !== renderedWidth) return undefined;
+					const hit = hits.find(({ row, to }) => row === event.y && event.x >= 0 && event.x < to);
+					if (!hit) return undefined;
+					focusWorker(hit.id);
+					return { handled: true, render: false };
+				},
 			};
 		});
 	};
@@ -491,6 +569,9 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		widgetItems.set(id, {
 			ref: directRef(display),
+			workflow: display.workflow,
+			worker: display.worker,
+			workers: display.workers,
 			role: roleBadge(display.role),
 			model,
 			thinkingLevel: thinkingLevel ?? "default",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "28.1.0",
+  "version": "28.2.2",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -71,9 +71,9 @@
   },
   "dependencies": {
     "@hcflabs/pi-config-store": "^4.0.0",
-    "@hcflabs/pi-herdr": "^0.5.0",
+    "@hcflabs/pi-herdr": "^0.6.0",
     "@hcflabs/pi-multi-codex": "^3.0.0",
-    "@hcflabs/pi-process": "^0.2.0",
+    "@hcflabs/pi-process": "^0.3.0",
     "@hcflabs/pi-repo": "^0.1.0",
     "@hcflabs/pi-task-models": "^9.0.0",
     "proper-lockfile": "^4.1.2"