pi-subagents 0.53.0 → 0.55.0

package/src/inspectors/herdr/focus.ts

@@ -0,0 +1,55 @@
+import type { HerdrClient, HerdrErrorCode } from "./client.ts";
+
+export type HerdrFocusErrorCode = HerdrErrorCode | "PANE_FOCUS_UNSUPPORTED" | "INVALID_PANE_RESPONSE";
+
+export type HerdrPaneFocusResult =
+	| { ok: true; data: { paneId: string; tabId?: string; workspaceId?: string } }
+	| { ok: false; error: { code: HerdrFocusErrorCode; message: string; details?: unknown } };
+
+export function herdrPaneRecord(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	return record.pane && typeof record.pane === "object" && !Array.isArray(record.pane)
+		? record.pane as Record<string, unknown>
+		: record;
+}
+
+function text(record: Record<string, unknown>, ...keys: string[]): string | undefined {
+	for (const key of keys) if (typeof record[key] === "string" && record[key]) return record[key] as string;
+	return undefined;
+}
+
+export function herdrPaneFocusTarget(value: unknown): { paneId?: string; tabId?: string; workspaceId?: string } {
+	const pane = herdrPaneRecord(value);
+	if (!pane) return {};
+	return {
+		paneId: text(pane, "pane_id", "paneId", "id"),
+		tabId: text(pane, "tab_id", "tabId"),
+		workspaceId: text(pane, "workspace_id", "workspaceId"),
+	};
+}
+
+export async function focusHerdrPane(client: HerdrClient, paneId: string, signal?: AbortSignal): Promise<HerdrPaneFocusResult> {
+	const live = await client.run(["pane", "get", paneId], { timeoutMs: 5_000, signal });
+	if (live.ok === false) return live;
+	const target = herdrPaneFocusTarget(live.data);
+	if (!target.paneId) {
+		return { ok: false, error: { code: "INVALID_PANE_RESPONSE", message: `Herdr pane get returned no pane id for '${paneId}'.`, details: live.data } };
+	}
+	if (target.tabId) {
+		const focused = await client.run(["tab", "focus", target.tabId], { timeoutMs: 5_000, signal });
+		return focused.ok ? { ok: true, data: { paneId: target.paneId, tabId: target.tabId, ...(target.workspaceId ? { workspaceId: target.workspaceId } : {}) } } : focused;
+	}
+	if (target.workspaceId) {
+		const focused = await client.run(["workspace", "focus", target.workspaceId], { timeoutMs: 5_000, signal });
+		return focused.ok ? { ok: true, data: { paneId: target.paneId, workspaceId: target.workspaceId } } : focused;
+	}
+	return {
+		ok: false,
+		error: {
+			code: "PANE_FOCUS_UNSUPPORTED",
+			message: `Herdr pane '${paneId}' has no tab_id or workspace_id. Select it in Herdr manually, or upgrade Herdr focus support.`,
+			details: live.data,
+		},
+	};
+}

package/src/inspectors/herdr/project-panes.ts

@@ -4,8 +4,9 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { getPiSpawnCommand } from "../../runs/shared/pi-spawn.ts";
 import { getProjectSubagentsDir } from "../../shared/artifacts.ts";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import type { Details } from "../../shared/types.ts";
+import type { Details, HerdrProjectPaneSnapshot, SubagentState } from "../../shared/types.ts";
 import { createHerdrClient, detectHerdr, type HerdrClient, type HerdrErrorCode } from "./client.ts";
+import { focusHerdrPane, herdrPaneFocusTarget, herdrPaneRecord } from "./focus.ts";
 import { formatShellCommand } from "./shell-command.ts";
 
 export const HERDR_PROJECT_PANE_ACTIONS = ["project.open", "project.status", "project.close"] as const;
@@ -34,6 +35,9 @@ export interface ProjectPaneRuntime {
 	cwd?: string;
 	foregroundCwd?: string;
 	focused?: boolean;
+	tabId?: string;
+	workspaceId?: string;
+	summary?: string;
 	terminalTitle?: string;
 }
 
@@ -44,6 +48,7 @@ export type ProjectPaneErrorCode = HerdrErrorCode
 	| "BINDING_READ_FAILED"
 	| "BINDING_WRITE_FAILED"
 	| "BINDING_REMOVE_FAILED"
+	| "PANE_FOCUS_UNSUPPORTED"
 	| "PANE_NOT_IDLE"
 	| "PANE_OWNERSHIP_UNVERIFIED";
 
@@ -87,6 +92,13 @@ export interface CloseProjectPaneData extends ProjectPaneCommonData {
 	runtime?: ProjectPaneRuntime;
 }
 
+export interface FocusProjectPaneData extends ProjectPaneCommonData {
+	binding: HerdrProjectPaneBinding;
+	runtime: ProjectPaneRuntime;
+	ownership: "verified" | "unknown" | "mismatch";
+	focused: { paneId: string; tabId?: string; workspaceId?: string };
+}
+
 export interface OpenProjectPaneOptions {
 	cwd: string;
 	message?: string;
@@ -106,12 +118,7 @@ export interface CloseProjectPaneOptions {
 	signal?: AbortSignal;
 }
 
-export interface ProjectPaneCommandClient {
-	run<T = unknown>(
-		args: string[],
-		options?: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean },
-	): Promise<{ ok: true; data: T } | { ok: false; error: { code: HerdrErrorCode; message: string; details?: unknown } }>;
-}
+export type ProjectPaneCommandClient = Pick<HerdrClient, "run">;
 
 export interface ProjectPaneManagerOptions {
 	client?: ProjectPaneCommandClient;
@@ -121,6 +128,7 @@ export interface ProjectPaneManagerOptions {
 export interface ProjectPaneManager {
 	open(options: OpenProjectPaneOptions): Promise<ProjectPaneResult<OpenProjectPaneData>>;
 	status(options: GetProjectPaneStatusOptions): Promise<ProjectPaneResult<ProjectPaneStatusData>>;
+	focus(options: GetProjectPaneStatusOptions): Promise<ProjectPaneResult<FocusProjectPaneData>>;
 	close(options: CloseProjectPaneOptions): Promise<ProjectPaneResult<CloseProjectPaneData>>;
 }
 
@@ -129,6 +137,12 @@ interface InternalProjectPaneManagerOptions extends ProjectPaneManagerOptions {
 	legacyToolCompatibility?: boolean;
 }
 
+interface HerdrProjectPaneRootIndex {
+	schemaVersion: 1;
+	kind: "herdr-project-pane-roots";
+	projectRoots: string[];
+}
+
 interface ProjectPaneParams {
 	cwd?: string;
 	message?: string;
@@ -137,6 +151,7 @@ interface ProjectPaneParams {
 
 interface ProjectPaneDeps {
 	cwd: string;
+	state?: SubagentState;
 	client?: HerdrClient;
 	signal?: AbortSignal;
 	now?: () => Date;
@@ -162,6 +177,51 @@ export function projectPaneBindingPath(projectRoot: string): string {
 	return path.join(projectPaneDir(projectRoot), "herdr.json");
 }
 
+function projectPaneRootIndexPath(ownerRoot: string): string {
+	return path.join(projectPaneDir(ownerRoot), "herdr-roots.json");
+}
+
+function parseRootIndex(value: unknown): string[] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Herdr project pane root index.");
+	const input = value as Partial<HerdrProjectPaneRootIndex>;
+	if (input.schemaVersion !== 1 || input.kind !== "herdr-project-pane-roots" || !Array.isArray(input.projectRoots)) throw new Error("Invalid Herdr project pane root index.");
+	if (!input.projectRoots.every((root) => typeof root === "string" && root.length > 0)) throw new Error("Invalid Herdr project pane root index.");
+	return input.projectRoots;
+}
+
+export function listHerdrProjectPaneRoots(ownerRoot: string): string[] {
+	try {
+		return parseRootIndex(JSON.parse(fs.readFileSync(projectPaneRootIndexPath(ownerRoot), "utf-8")));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ENOTDIR") return [];
+		throw error;
+	}
+}
+
+function writeHerdrProjectPaneRoot(ownerRoot: string, projectRoot: string): void {
+	const projectRoots = [...new Set([...listHerdrProjectPaneRoots(ownerRoot), projectRoot])].sort();
+	writeAtomicJson(projectPaneRootIndexPath(ownerRoot), {
+		schemaVersion: 1,
+		kind: "herdr-project-pane-roots",
+		projectRoots,
+	} satisfies HerdrProjectPaneRootIndex);
+}
+
+function removeHerdrProjectPaneRoot(ownerRoot: string, projectRoot: string): void {
+	const projectRoots = listHerdrProjectPaneRoots(ownerRoot).filter((root) => root !== projectRoot);
+	const file = projectPaneRootIndexPath(ownerRoot);
+	if (projectRoots.length === 0) {
+		fs.rmSync(file, { force: true });
+		return;
+	}
+	writeAtomicJson(file, {
+		schemaVersion: 1,
+		kind: "herdr-project-pane-roots",
+		projectRoots,
+	} satisfies HerdrProjectPaneRootIndex);
+}
+
 function parseBinding(value: unknown, strict = false): HerdrProjectPaneBinding | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 	const input = value as Partial<HerdrProjectPaneBinding>;
@@ -224,27 +284,60 @@ export function readProjectPaneBinding(projectRoot: string): ProjectPaneResult<H
 	return { ok: true, data: read.binding };
 }
 
-function paneRecord(value: unknown): Record<string, unknown> | undefined {
+function herdrProjectPaneSnapshotFromBinding(binding: HerdrProjectPaneBinding, now = Date.now()): HerdrProjectPaneSnapshot {
+	return {
+		projectRoot: binding.projectRoot,
+		bindingPath: projectPaneBindingPath(binding.projectRoot),
+		paneId: binding.paneId,
+		openedAt: binding.openedAt,
+		...(binding.lastFocusedAt ? { lastFocusedAt: binding.lastFocusedAt } : {}),
+		state: "open",
+		agentStatus: "unknown",
+		ownership: "unknown",
+		safeToClose: false,
+		refreshedAt: now,
+	};
+}
+
+export function restoreHerdrProjectPaneSnapshots(state: SubagentState, projectRoots: Iterable<string>, now = Date.now()): void {
+	const restored = new Map(state.herdrProjectPanes ?? []);
+	for (const projectRoot of projectRoots) {
+		const binding = readHerdrProjectPaneBinding(projectRoot);
+		if (binding) restored.set(binding.projectRoot, herdrProjectPaneSnapshotFromBinding(binding, now));
+	}
+	state.herdrProjectPanes = restored;
+}
+
+function sanitizedSummary(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+	return cleaned ? cleaned.slice(0, 120) : undefined;
+}
+
+function nestedRecord(value: unknown, key: string): Record<string, unknown> | undefined {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const record = value as Record<string, unknown>;
-	return record.pane && typeof record.pane === "object" && !Array.isArray(record.pane)
-		? record.pane as Record<string, unknown>
-		: record;
+	const child = (value as Record<string, unknown>)[key];
+	return child && typeof child === "object" && !Array.isArray(child) ? child as Record<string, unknown> : undefined;
 }
 
-function extractPaneId(value: unknown): string | undefined {
-	const pane = paneRecord(value);
-	if (!pane) return undefined;
-	for (const key of ["pane_id", "paneId", "id"]) if (typeof pane[key] === "string") return pane[key];
-	return undefined;
+function paneSummary(pane: Record<string, unknown>): string | undefined {
+	return sanitizedSummary(pane.summary)
+		?? sanitizedSummary(pane.state_text)
+		?? sanitizedSummary(pane.stateText)
+		?? sanitizedSummary(pane.token_summary)
+		?? sanitizedSummary(nestedRecord(pane, "tokens")?.summary)
+		?? sanitizedSummary(nestedRecord(pane, "metadata")?.summary)
+		?? sanitizedSummary(nestedRecord(nestedRecord(pane, "metadata"), "tokens")?.summary);
 }
 
 function projectPaneRuntime(value: unknown): ProjectPaneRuntime | undefined {
-	const pane = paneRecord(value);
-	const paneId = extractPaneId(value);
+	const pane = herdrPaneRecord(value);
+	const focusTarget = herdrPaneFocusTarget(value);
+	const paneId = focusTarget.paneId;
 	if (!pane || !paneId) return undefined;
 	const text = (key: string): string | undefined => typeof pane[key] === "string" ? pane[key] as string : undefined;
 	const agentStatus = text("agent_status") ?? text("agentStatus") ?? "unknown";
+	const summary = paneSummary(pane);
 	return {
 		paneId,
 		...(text("agent") ? { agent: text("agent") } : {}),
@@ -252,12 +345,48 @@ function projectPaneRuntime(value: unknown): ProjectPaneRuntime | undefined {
 		...(text("cwd") ? { cwd: text("cwd") } : {}),
 		...(text("foreground_cwd") || text("foregroundCwd") ? { foregroundCwd: text("foreground_cwd") ?? text("foregroundCwd") } : {}),
 		...(typeof pane.focused === "boolean" ? { focused: pane.focused } : {}),
+		...(focusTarget.tabId ? { tabId: focusTarget.tabId } : {}),
+		...(focusTarget.workspaceId ? { workspaceId: focusTarget.workspaceId } : {}),
+		...(summary ? { summary } : {}),
 		...(text("terminal_title_stripped") || text("terminal_title") || text("terminalTitle")
 			? { terminalTitle: text("terminal_title_stripped") ?? text("terminal_title") ?? text("terminalTitle") }
 			: {}),
 	};
 }
 
+function herdrProjectPaneSnapshotFromStatus(data: ProjectPaneStatusData, now: number): HerdrProjectPaneSnapshot | undefined {
+	if (data.state === "absent" || !data.binding) return undefined;
+	return {
+		projectRoot: data.projectRoot,
+		bindingPath: data.bindingPath,
+		paneId: data.binding.paneId,
+		openedAt: data.binding.openedAt,
+		...(data.binding.lastFocusedAt ? { lastFocusedAt: data.binding.lastFocusedAt } : {}),
+		state: data.state,
+		agentStatus: data.runtime?.agentStatus ?? "unknown",
+		ownership: data.ownership,
+		safeToClose: data.safeToClose,
+		refreshedAt: now,
+		...(data.runtime?.summary ? { summary: data.runtime.summary } : {}),
+		...(data.runtime?.tabId ? { tabId: data.runtime.tabId } : {}),
+		...(data.runtime?.workspaceId ? { workspaceId: data.runtime.workspaceId } : {}),
+		...(data.runtime?.terminalTitle ? { terminalTitle: data.runtime.terminalTitle } : {}),
+		...(data.staleReason ? { staleReason: data.staleReason.message } : {}),
+	};
+}
+
+function rememberProjectPane(state: SubagentState | undefined, data: ProjectPaneStatusData, now: number): void {
+	if (!state) return;
+	state.herdrProjectPanes ??= new Map();
+	const snapshot = herdrProjectPaneSnapshotFromStatus(data, now);
+	if (snapshot) state.herdrProjectPanes.set(data.projectRoot, snapshot);
+	else state.herdrProjectPanes.delete(data.projectRoot);
+}
+
+function forgetProjectPane(state: SubagentState | undefined, projectRoot: string): void {
+	state?.herdrProjectPanes?.delete(projectRoot);
+}
+
 function resolveProjectRoot(requested: string): ProjectPaneResult<string> {
 	const resolved = path.resolve(requested);
 	try {
@@ -379,6 +508,41 @@ function createProjectPaneManagerInternal(options: InternalProjectPaneManagerOpt
 			} };
 		},
 
+		async focus(input) {
+			const status = await this.status(input);
+			if (!status.ok) return projectPaneError(status.error.code, status.error.message, status.error);
+			if (status.data.state !== "open" || !status.data.binding || !status.data.runtime) {
+				return projectPaneError("PANE_GONE", `No open Herdr project pane binding exists for '${status.data.projectRoot}'.`, {
+					projectRoot: status.data.projectRoot, bindingPath: status.data.bindingPath,
+				});
+			}
+			if (status.data.ownership !== "verified") {
+				return projectPaneError("PANE_OWNERSHIP_UNVERIFIED", `Project pane '${status.data.binding.paneId}' ownership is '${status.data.ownership}' for '${status.data.projectRoot}'.`, {
+					projectRoot: status.data.projectRoot, bindingPath: status.data.bindingPath, details: status.data.runtime,
+				});
+			}
+			const focused = await focusHerdrPane(client, status.data.binding.paneId, input.signal);
+			if (!focused.ok) return projectPaneError(focused.error.code, focused.error.message, {
+				projectRoot: status.data.projectRoot, bindingPath: status.data.bindingPath, details: focused.error.details,
+			});
+			const now = (options.now?.() ?? new Date()).toISOString();
+			const binding = { ...status.data.binding, lastFocusedAt: now };
+			try {
+				writeAtomicJson(status.data.bindingPath, binding);
+			} catch (cause) {
+				return projectPaneError("BINDING_WRITE_FAILED", `Failed to update project pane binding '${status.data.bindingPath}': ${cause instanceof Error ? cause.message : String(cause)}`, {
+					projectRoot: status.data.projectRoot, bindingPath: status.data.bindingPath, details: fileSystemErrorDetails(cause),
+				});
+			}
+			return { ok: true, data: {
+				...common(status.data.projectRoot),
+				binding,
+				runtime: status.data.runtime,
+				ownership: status.data.ownership,
+				focused: focused.data,
+			} };
+		},
+
 		async open(input) {
 			const root = resolveProjectRoot(input.cwd);
 			if (!root.ok) return root;
@@ -414,7 +578,7 @@ function createProjectPaneManagerInternal(options: InternalProjectPaneManagerOpt
 			splitArgs.push(input.focus === true ? "--focus" : "--no-focus");
 			const split = await client.run(splitArgs, { timeoutMs: 15_000, signal: input.signal });
 			if (!split.ok) return projectPaneError(split.error.code, split.error.message, { projectRoot, details: split.error.details });
-			const paneId = extractPaneId(split.data);
+			const paneId = herdrPaneFocusTarget(split.data).paneId;
 			if (!paneId) return projectPaneError(options.legacyToolCompatibility ? "PANE_GONE" : "INVALID_PANE_RESPONSE", "Herdr pane split returned no pane id.", { projectRoot, details: split.data });
 			const startupMessage = input.message?.trim();
 			const command = projectPaneCommand(startupMessage);
@@ -466,29 +630,26 @@ function createProjectPaneManagerInternal(options: InternalProjectPaneManagerOpt
 			if (!bindingResult.ok) return bindingResult;
 			const existing = bindingResult.data;
 			if (!existing) return { ok: true, data: { ...common(projectRoot), disposition: "absent" } };
-			let runtime: ProjectPaneRuntime | undefined;
-			if (input.requireIdle) {
-				const live = await inspectPane(client, existing.paneId, input.signal);
-				if (!live.ok) {
-					if (live.error.code === "NOT_FOUND" || live.error.code === "PANE_GONE") {
-						const removed = removeProjectPaneBinding(projectRoot);
-						if (!removed.ok) return removed;
-						return { ok: true, data: { ...common(projectRoot), disposition: "stale-binding-removed", binding: existing } };
-					}
-					return { ok: false, error: { ...live.error, projectRoot, bindingPath: projectPaneBindingPath(projectRoot) } };
-				}
-				runtime = live.data;
-				const ownership = projectPaneOwnership(runtime, existing, projectRoot);
-				if (ownership !== "verified") {
-					return projectPaneError("PANE_OWNERSHIP_UNVERIFIED", `Project pane '${existing.paneId}' ownership is '${ownership}' for '${projectRoot}'.`, {
-						projectRoot, bindingPath: projectPaneBindingPath(projectRoot), details: runtime,
-					});
-				}
-				if (runtime.agentStatus !== "idle") {
-					return projectPaneError("PANE_NOT_IDLE", `Project pane '${existing.paneId}' is '${runtime.agentStatus}', not explicitly idle.`, {
-						projectRoot, bindingPath: projectPaneBindingPath(projectRoot), details: runtime,
-					});
+			const live = await inspectPane(client, existing.paneId, input.signal);
+			if (!live.ok) {
+				if (live.error.code === "NOT_FOUND" || live.error.code === "PANE_GONE") {
+					const removed = removeProjectPaneBinding(projectRoot);
+					if (!removed.ok) return removed;
+					return { ok: true, data: { ...common(projectRoot), disposition: "stale-binding-removed", binding: existing } };
 				}
+				return { ok: false, error: { ...live.error, projectRoot, bindingPath: projectPaneBindingPath(projectRoot) } };
+			}
+			const runtime = live.data;
+			const ownership = projectPaneOwnership(runtime, existing, projectRoot);
+			if (ownership !== "verified") {
+				return projectPaneError("PANE_OWNERSHIP_UNVERIFIED", `Project pane '${existing.paneId}' ownership is '${ownership}' for '${projectRoot}'.`, {
+					projectRoot, bindingPath: projectPaneBindingPath(projectRoot), details: runtime,
+				});
+			}
+			if (runtime.agentStatus !== "idle") {
+				return projectPaneError("PANE_NOT_IDLE", `Project pane '${existing.paneId}' is '${runtime.agentStatus}', not explicitly idle.`, {
+					projectRoot, bindingPath: projectPaneBindingPath(projectRoot), details: runtime,
+				});
 			}
 			const closed = await client.run(["pane", "close", existing.paneId], { timeoutMs: 10_000, signal: input.signal });
 			if (!closed.ok && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE") {
@@ -518,12 +679,19 @@ export async function closeProjectPane(options: CloseProjectPaneOptions): Promis
 	return createProjectPaneManager().close(options);
 }
 
+export async function focusProjectPane(options: GetProjectPaneStatusOptions): Promise<ProjectPaneResult<FocusProjectPaneData>> {
+	return createProjectPaneManager().focus(options);
+}
+
 export async function handleHerdrProjectPaneAction(action: HerdrProjectPaneAction, params: ProjectPaneParams, deps: ProjectPaneDeps): Promise<AgentToolResult<Details>> {
 	const requested = params.cwd?.trim() || deps.cwd;
+	const ownerRoot = path.resolve(deps.cwd);
 	const manager = createProjectPaneManagerInternal({ client: deps.client, now: deps.now, legacyToolCompatibility: true });
+	const remember = (data: ProjectPaneStatusData) => rememberProjectPane(deps.state, data, deps.now?.().getTime() ?? Date.now());
 	if (action === "project.status") {
 		const status = await manager.status({ cwd: requested, signal: deps.signal });
 		if (!status.ok) return toolResult(formatProjectPaneError(status.error), true);
+		remember(status.data);
 		if (status.data.state === "absent") return toolResult(`No Herdr project pane binding exists for ${status.data.projectRoot}.`);
 		if (status.data.state === "stale") {
 			const reason = status.data.staleReason!;
@@ -532,15 +700,31 @@ export async function handleHerdrProjectPaneAction(action: HerdrProjectPaneActio
 		return toolResult(`Herdr project pane ${status.data.binding!.paneId} is open for ${status.data.projectRoot}.\nBinding: ${status.data.bindingPath}`);
 	}
 	if (action === "project.close") {
-		const closed = await manager.close({ cwd: requested, signal: deps.signal });
+		const closed = await manager.close({ cwd: requested, requireIdle: true, signal: deps.signal });
 		if (!closed.ok) return toolResult(formatProjectPaneError(closed.error), true);
+		forgetProjectPane(deps.state, closed.data.projectRoot);
+		try { removeHerdrProjectPaneRoot(ownerRoot, closed.data.projectRoot); } catch (error) {
+			return toolResult(`Herdr project pane error (BINDING_REMOVE_FAILED): Failed to remove project pane root index '${projectPaneRootIndexPath(ownerRoot)}': ${error instanceof Error ? error.message : String(error)}`, true);
+		}
 		if (closed.data.disposition === "absent") return toolResult(`No Herdr project pane binding exists for ${closed.data.projectRoot}.`);
 		return toolResult(`Closed Herdr project pane ${closed.data.binding!.paneId} for ${closed.data.projectRoot}.`);
 	}
 	const opened = await manager.open({ cwd: requested, message: params.message, focus: params.focus, signal: deps.signal });
 	if (!opened.ok) return toolResult(formatProjectPaneError(opened.error), true);
+	try { writeHerdrProjectPaneRoot(ownerRoot, opened.data.projectRoot); } catch (error) {
+		return toolResult(`Herdr project pane error (BINDING_WRITE_FAILED): Failed to persist project pane root index '${projectPaneRootIndexPath(ownerRoot)}': ${error instanceof Error ? error.message : String(error)}`, true);
+	}
+	const status = await manager.status({ cwd: opened.data.projectRoot, signal: deps.signal });
+	if (status.ok) remember(status.data);
 	if (opened.data.disposition === "already-open") {
-		return toolResult(`Herdr project pane ${opened.data.binding.paneId} is already open for ${opened.data.projectRoot}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
+		if (params.focus) {
+			const focused = await manager.focus({ cwd: opened.data.projectRoot, signal: deps.signal });
+			if (!focused.ok) return toolResult(`Herdr project pane ${opened.data.binding.paneId} is already open for ${opened.data.projectRoot}. ${formatProjectPaneError(focused.error)}`, true);
+			const focusedStatus = await manager.status({ cwd: opened.data.projectRoot, signal: deps.signal });
+			if (focusedStatus.ok) remember(focusedStatus.data);
+			return toolResult(`Herdr project pane ${opened.data.binding.paneId} is already open for ${opened.data.projectRoot}. Focused ${focused.data.focused.tabId ? `tab ${focused.data.focused.tabId}` : `workspace ${focused.data.focused.workspaceId}`}.`);
+		}
+		return toolResult(`Herdr project pane ${opened.data.binding.paneId} is already open for ${opened.data.projectRoot}.`);
 	}
 	return toolResult(`Opened Herdr project pane ${opened.data.binding.paneId} for ${opened.data.projectRoot}. The pane runs its own Pi session; subagents launched there belong to that project.`);
 }

package/src/integrations/herdr-status.ts

@@ -33,6 +33,8 @@ export interface HerdrStatusBridgeOptions {
 	env?: Record<string, string | undefined>;
 	/** Current authoritative active-run projection, used before TTL refresh. */
 	getRuns?: () => Iterable<HerdrStatusRun>;
+	/** Current project panes opened by this Pi session. Views are excluded. */
+	getProjectPaneCount?: () => number;
 	runHerdr: (args: readonly string[]) => void | Promise<void>;
 	ttlMs?: number;
 	refreshMs?: number;
@@ -109,12 +111,27 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 	let drainPromise = Promise.resolve();
 	let refreshTimer: ReturnType<typeof setInterval> | undefined;
 
-	const label = (): string => {
-		const agents = [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
+	const activeAgentNames = (): string[] => [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
+	const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) => total + Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0)), 0);
+
+	const label = (includeAttention = false): string => {
+		const agents = activeAgentNames();
+		const activeCount = activeSubagentCount();
 		const who = agents.length > 0
 			? ` (${agents.slice(0, 3).join(", ")}${agents.length > 3 ? ", …" : ""})`
 			: "";
-		return `⏳ ${runs.size} subagent${runs.size === 1 ? "" : "s"}${who}`;
+		const panes = Math.max(0, options.getProjectPaneCount?.() ?? 0);
+		const paneText = panes > 0 ? ` · ${panes} pane${panes === 1 ? "" : "s"}` : "";
+		const attention = includeAttention && attentionLabels.size > 0 ? " ⚠" : "";
+		return `⏳ ${activeCount} subagent${activeCount === 1 ? "" : "s"}${who}${paneText}${attention}`;
+	};
+
+	const titleSuffix = (): string | undefined => {
+		if (runs.size === 0) return undefined;
+		const agentNames = activeAgentNames();
+		const activeCount = activeSubagentCount();
+		const target = activeCount === 1 && agentNames.length === 1 ? agentNames[0]! : String(activeCount);
+		return `⏳${target}${attentionLabels.size > 0 ? "⚠" : ""}`;
 	};
 
 	const enqueue = (args: readonly string[]): void => {
@@ -150,11 +167,13 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 				"--applies-to-source", "herdr:pi",
 				"--clear-state-labels",
 				"--clear-token", "summary",
+				"--clear-token", "title-suffix",
 				"--seq", seq,
 			]);
 			return;
 		}
-		const text = label();
+		const text = label(true);
+		const suffix = titleSuffix();
 		published = true;
 		enqueue([
 			"pane", "report-metadata", paneId,
@@ -165,6 +184,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 			"--state-label", `done=${text}`,
 			"--state-label", `working=${text}`,
 			"--token", `summary=${text}`,
+			...(suffix ? ["--token", `title-suffix=${suffix}`] : []),
 			"--ttl-ms", String(ttlMs),
 			"--seq", seq,
 		]);
@@ -221,6 +241,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 	const clearAttention = (): void => {
 		attentionLabels.clear();
 		syncBlocked();
+		publish();
 	};
 
 	const raiseAttention = (runId: string, labelText: string): void => {
@@ -228,6 +249,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
 		acknowledgedAttention.delete(runId);
 		attentionLabels.set(runId, labelText);
 		syncBlocked();
+		publish();
 	};
 
 	const replaceRuns = (nextRuns: Iterable<HerdrStatusRun>): void => {