pi-herdr-agents 3.0.1 → 3.0.3

package/maestro/core/opened-primary-workspace.ts

@@ -0,0 +1,108 @@
+import { isNonEmptyString } from "./config/type-guards.ts";
+
+/**
+ * A primary workspace this process saw Herdr open while creating a worktree.
+ * The record lives only in this process. Another session is another process,
+ * and a restart starts empty, so neither reports a claim. Nothing is persisted.
+ */
+export interface PrimaryWorkspaceClaim {
+	workspaceId: string;
+	repoKey: string;
+	terminalId: string;
+	checkoutPath: string;
+}
+
+export interface ReleasedPrimaryWorkspaceClaim {
+	workspaceId: string;
+	repoKey: string;
+	terminalId: string;
+}
+
+/**
+ * A report never closes a workspace. `note` is absent when nothing is safe to
+ * suggest, and never states the attribution as fact.
+ */
+export interface OpenedPrimaryWorkspaceReport {
+	note?: string;
+	repoKey: string;
+	releasedClaims: ReleasedPrimaryWorkspaceClaim[];
+}
+
+const openedPrimaryWorkspacesKey = Symbol.for(
+	"pi-herdr-agents:opened-primary-workspaces",
+);
+
+interface OpenedPrimaryWorkspaceStore {
+	claims: PrimaryWorkspaceClaim[];
+}
+
+function store(): OpenedPrimaryWorkspaceStore {
+	// SAFETY: this extension alone writes this process-local symbol.
+	const globalStore = globalThis as typeof globalThis & {
+		[openedPrimaryWorkspacesKey]?: OpenedPrimaryWorkspaceStore;
+	};
+	return (globalStore[openedPrimaryWorkspacesKey] ??= { claims: [] });
+}
+
+export function isCompletePrimaryWorkspaceClaim(
+	value: PrimaryWorkspaceClaim,
+): boolean {
+	return (
+		isNonEmptyString(value.workspaceId) &&
+		isNonEmptyString(value.repoKey) &&
+		isNonEmptyString(value.terminalId) &&
+		isNonEmptyString(value.checkoutPath)
+	);
+}
+
+function sameClaim(
+	left: PrimaryWorkspaceClaim,
+	right: PrimaryWorkspaceClaim,
+): boolean {
+	return (
+		left.workspaceId === right.workspaceId &&
+		left.repoKey === right.repoKey &&
+		left.terminalId === right.terminalId &&
+		left.checkoutPath === right.checkoutPath
+	);
+}
+
+export function rememberOpenedPrimaryWorkspace(
+	claim: PrimaryWorkspaceClaim,
+): void {
+	if (!isCompletePrimaryWorkspaceClaim(claim)) return;
+	const claims = store().claims;
+	if (claims.some((existing) => sameClaim(existing, claim))) return;
+	claims.push({
+		workspaceId: claim.workspaceId,
+		repoKey: claim.repoKey,
+		terminalId: claim.terminalId,
+		checkoutPath: claim.checkoutPath,
+	});
+}
+
+export function openedPrimaryWorkspaceClaims(): PrimaryWorkspaceClaim[] {
+	return store()
+		.claims.filter(isCompletePrimaryWorkspaceClaim)
+		.map((claim) => ({ ...claim }));
+}
+
+export function forgetOpenedPrimaryWorkspaceClaims(
+	released: readonly ReleasedPrimaryWorkspaceClaim[],
+): void {
+	if (!released.length) return;
+	const claims = store().claims;
+	store().claims = claims.filter(
+		(claim) =>
+			!released.some(
+				(entry) =>
+					entry.workspaceId === claim.workspaceId &&
+					entry.repoKey === claim.repoKey &&
+					entry.terminalId === claim.terminalId,
+			),
+	);
+}
+
+export function clearOpenedPrimaryWorkspaceClaims(): void {
+	store().claims = [];
+}

package/maestro/core/supervision.ts

@@ -8,6 +8,10 @@ import {
 export const RECONCILE_INTERVAL_MS = 4_800;
 export const POLLING_INTERVAL_MS = 1_000;
 const BATCH_UNHEALTHY_MS = 5_000;
+const ABORT_MESSAGE = "Aborted while waiting for subagent to finish";
+const UNREGISTERED_MESSAGE = "Supervision registration was unregistered";
+const CONCURRENT_WAIT_MESSAGE =
+	"Supervision registration already has a parked wait";
 
 export interface PaneListEntry {
 	paneId: string;
@@ -30,12 +34,18 @@ interface Entry {
 	generation: number;
 	wakeRegistration?: WakeRegistration;
 	pending?: WakeReason;
-	resolve?: (reason: WakeReason) => void;
+	parked?: ParkedWait;
+	unregistered?: boolean;
 	inspection?: PaneInspection;
 	fallback: boolean;
 	fileFallback: boolean;
 }
 
+interface ParkedWait {
+	resolve(reason: WakeReason): void;
+	reject(error: Error): void;
+}
+
 export interface SupervisionDiagnostics {
 	mode: "wake+batch" | "polling(forced)" | "polling(fallback)";
 	watcherCount: number;
@@ -138,12 +148,15 @@ export class SupervisionCoordinator {
 	}
 
 	private unregister(entry: Entry): void {
+		entry.unregistered = true;
 		entry.wakeRegistration?.unregister();
 		this.entries.delete(entry);
 		if (this.entries.size === 0 && this.timer) {
 			clearInterval(this.timer);
 			this.timer = undefined;
 		}
+		// Nothing can wake a parked wait now; settle it so its retain is released.
+		entry.parked?.reject(new Error(UNREGISTERED_MESSAGE));
 	}
 
 	private enterFallback(entry: Entry): void {
@@ -155,10 +168,12 @@ export class SupervisionCoordinator {
 	}
 
 	private wait(entry: Entry, signal: AbortSignal): Promise<WakeReason> {
-		if (signal.aborted)
-			return Promise.reject(
-				new Error("Aborted while waiting for subagent to finish"),
-			);
+		if (signal.aborted) return Promise.reject(new Error(ABORT_MESSAGE));
+		if (entry.unregistered)
+			return Promise.reject(new Error(UNREGISTERED_MESSAGE));
+		// One completion loop consumes a registration: `pending` queues a single
+		// reason for a single waiter, so a second concurrent wait is a caller bug.
+		if (entry.parked) return Promise.reject(new Error(CONCURRENT_WAIT_MESSAGE));
 		if (entry.pending) {
 			const reason = entry.pending;
 			entry.pending = undefined;
@@ -166,14 +181,24 @@ export class SupervisionCoordinator {
 		}
 		if (entry.fallback) return this.poll(signal);
 		return new Promise((resolve, reject) => {
+			// Polling keeps its own timer referenced. A wake wait has only this
+			// promise, so retain the unref'd directory watch until it settles.
+			const release = this.wakeRegistry.retain();
+			let settled = false;
+			const finish = (settle: () => void) => {
+				if (settled) return;
+				settled = true;
+				signal.removeEventListener("abort", onAbort);
+				entry.parked = undefined;
+				release();
+				settle();
+			};
 			const onAbort = () => {
-				entry.resolve = undefined;
-				reject(new Error("Aborted while waiting for subagent to finish"));
+				finish(() => reject(new Error(ABORT_MESSAGE)));
 			};
-			entry.resolve = (reason) => {
-				signal.removeEventListener("abort", onAbort);
-				entry.resolve = undefined;
-				resolve(reason);
+			entry.parked = {
+				resolve: (reason) => finish(() => resolve(reason)),
+				reject: (error) => finish(() => reject(error)),
 			};
 			signal.addEventListener("abort", onAbort, { once: true });
 		});
@@ -187,7 +212,7 @@ export class SupervisionCoordinator {
 			}, POLLING_INTERVAL_MS);
 			const onAbort = () => {
 				clearTimeout(timer);
-				reject(new Error("Aborted while waiting for subagent to finish"));
+				reject(new Error(ABORT_MESSAGE));
 			};
 			signal.addEventListener("abort", onAbort, { once: true });
 		});
@@ -196,7 +221,7 @@ export class SupervisionCoordinator {
 	private signal(entry: Entry, reason: WakeReason): void {
 		if (this.closed) return;
 		if (reason === "wake") entry.inspection = undefined;
-		if (entry.resolve) entry.resolve(reason);
+		if (entry.parked) entry.parked.resolve(reason);
 		// A wake must never downgrade a queued reconciliation: the reconcile
 		// reason carries the epoch's pane inspection, and skipping it would
 		// defer pane-disappearance detection past the documented 5s bound.

package/maestro/core/surface-provider.ts

@@ -6,6 +6,10 @@
  * Methods may be sync or async; providers choose. The CLI is the only place
  * that wires a provider to an adapter (via core's SurfaceHandle).
  */
+import type {
+	OpenedPrimaryWorkspaceReport,
+	PrimaryWorkspaceClaim,
+} from "./opened-primary-workspace.ts";
 import type { PaneInspection, SurfaceHandle } from "./types.ts";
 
 // pi-herdr-agents extension
@@ -48,6 +52,13 @@ export interface WorktreeSurface {
 	/** Provider-native workspace/container id for later removal. */
 	workspaceId: string;
 	surfaceId: string;
+	/** Non-fatal provisioning problems the parent should see, such as a failed snapshot. */
+	diagnostics?: string[];
+}
+
+export interface ReportOpenedPrimaryWorkspaceInput {
+	sourceRepo: string;
+	claims: readonly PrimaryWorkspaceClaim[];
 }
 
 export type RecoveredWorktreeProvisioning = Pick<
@@ -135,6 +146,17 @@ export interface SurfaceProvider {
 		opts?: { timeoutMs?: number },
 	): void | Promise<void>;
 
+	/**
+	 * Suggest closing a claimed primary workspace that still looks untouched.
+	 * Never closes it. Unsupported providers return undefined.
+	 */
+	reportOpenedPrimaryWorkspace(
+		input: ReportOpenedPrimaryWorkspaceInput,
+	):
+		| OpenedPrimaryWorkspaceReport
+		| undefined
+		| Promise<OpenedPrimaryWorkspaceReport | undefined>;
+
 	/** Human-readable hint when isAvailable() is false; today's terminalSetupHint(). */
 	// pi-herdr-agents extension
 	setupHint(): string;

package/maestro/core/wake.ts

@@ -27,6 +27,7 @@ export class FileWakeRegistry {
 	private readonly directories = new Map<string, DirectoryWatcher>();
 	private readonly watchDirectory: typeof watch;
 	private closed = false;
+	private retained = 0;
 
 	constructor(watchDirectory: typeof watch = watch) {
 		this.watchDirectory = watchDirectory;
@@ -57,7 +58,10 @@ export class FileWakeRegistry {
 					}
 				});
 				current = { watcher, entries: new Set() };
+				// Idle watches must not keep the process running. A parked waiter
+				// retains them so this callback can still run.
 				watcher.unref();
+				if (this.retained > 0) watcher.ref();
 				watcher.on("error", () => this.failDirectory(directory));
 				this.directories.set(directory, current);
 			} catch {
@@ -85,12 +89,45 @@ export class FileWakeRegistry {
 		return this.directories.size;
 	}
 
+	/** Outstanding retains; every directory watch is referenced while nonzero. */
+	get retainedWaits(): number {
+		return this.retained;
+	}
+
+	/**
+	 * Pin every active directory watch until the returned function runs.
+	 * A bare wake promise does not keep the event loop alive, and idle watches
+	 * are unref'd, so without this the callback never runs when that promise is
+	 * the only pending work.
+	 */
+	retain(): () => void {
+		if (this.closed) return () => {};
+		this.retained++;
+		if (this.retained === 1) this.applyWatcherRef(true);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			if (this.closed || this.retained === 0) return;
+			this.retained--;
+			if (this.retained === 0) this.applyWatcherRef(false);
+		};
+	}
+
 	close(): void {
 		this.closed = true;
+		this.retained = 0;
 		for (const { watcher } of this.directories.values()) watcher.close();
 		this.directories.clear();
 	}
 
+	private applyWatcherRef(active: boolean): void {
+		for (const { watcher } of this.directories.values()) {
+			if (active) watcher.ref();
+			else watcher.unref();
+		}
+	}
+
 	private failDirectory(directory: string): void {
 		if (this.closed) return;
 		const current = this.directories.get(directory);

package/maestro/core/worktree-cleanup.ts

@@ -1,5 +1,11 @@
 import { isAbsolute, relative, sep } from "node:path";
 import { isString, type JsonObject } from "./config/type-guards.ts";
+import {
+	forgetOpenedPrimaryWorkspaceClaims,
+	openedPrimaryWorkspaceClaims,
+	type OpenedPrimaryWorkspaceReport,
+	type PrimaryWorkspaceClaim,
+} from "./opened-primary-workspace.ts";
 import type { WorktreeSurfaceInfo } from "./surface-provider.ts";
 
 export interface CleanupGitState {
@@ -53,6 +59,17 @@ export interface WorktreeCleanupOperations {
 	exists(path: string): boolean;
 	preserve(entry: WorktreeInventoryEntry): string;
 	removeWorkspace(id: string): void | Promise<void>;
+	/**
+	 * Suggest, never close, a primary workspace this process's worktree
+	 * creation appears to have opened. Undefined means the surface cannot report.
+	 */
+	reportOpenedPrimaryWorkspace(
+		sourceRepo: string,
+		claims: readonly PrimaryWorkspaceClaim[],
+	):
+		| OpenedPrimaryWorkspaceReport
+		| undefined
+		| Promise<OpenedPrimaryWorkspaceReport | undefined>;
 	removeCheckout(sourceRepo: string, path: string): void | Promise<void>;
 	prune(sourceRepo: string): void;
 	writeManifest(file: string, value: JsonObject): void;
@@ -80,6 +97,21 @@ function contained(root: string, path: string): boolean {
 	);
 }
 
+function claimsForSource(
+	claims: readonly PrimaryWorkspaceClaim[],
+	sourceRepo: string,
+	ops: WorktreeCleanupOperations,
+): PrimaryWorkspaceClaim[] {
+	return claims.filter((claim) => {
+		if (claim.checkoutPath === sourceRepo) return true;
+		try {
+			return ops.realpath(claim.checkoutPath) === sourceRepo;
+		} catch {
+			return false;
+		}
+	});
+}
+
 export function cleanupBlockers(entry: WorktreeInventoryEntry): string[] {
 	const git = entry.git;
 	const blockers: string[] = [];
@@ -345,6 +377,25 @@ export async function removeContainedWorktree(
 		checkoutRemoved = true;
 		if (!entry.workspaceId) ops.prune(entry.sourceRepo);
 		const warnings: string[] = [];
+		let primaryNote = "";
+		const claims = claimsForSource(
+			openedPrimaryWorkspaceClaims(),
+			entry.sourceRepo,
+			ops,
+		);
+		if (claims.length) {
+			try {
+				const report = await ops.reportOpenedPrimaryWorkspace(
+					entry.sourceRepo,
+					claims,
+				);
+				if (report?.note) primaryNote = ` ${report.note}`;
+				if (report?.releasedClaims.length)
+					forgetOpenedPrimaryWorkspaceClaims(report.releasedClaims);
+			} catch (error) {
+				warnings.push(`Primary workspace report failed: ${message(error)}`);
+			}
+		}
 		for (const manifest of entry.manifest) {
 			try {
 				ops.writeManifest(manifest.file, {
@@ -361,7 +412,7 @@ export async function removeContainedWorktree(
 			status: "removed",
 			entry,
 			preservationSha,
-			message: `Removed ${entry.path}. Branch ${entry.branch} and its commits retained.${preservationSha ? ` Preservation commit: ${preservationSha}.` : ""}${ignoredNotice()}${warnings.length ? ` Warning: ${warnings.join("; ")}` : entry.manifest.length ? " Manifest marked removed." : " No reachable manifest (orphan)."}`,
+			message: `Removed ${entry.path}. Branch ${entry.branch} and its commits retained.${preservationSha ? ` Preservation commit: ${preservationSha}.` : ""}${ignoredNotice()}${primaryNote}${warnings.length ? ` Warning: ${warnings.join("; ")}` : entry.manifest.length ? " Manifest marked removed." : " No reachable manifest (orphan)."}`,
 		});
 	} catch (error) {
 		return finish({

package/maestro/core/worktree.ts

@@ -11,6 +11,8 @@ export interface WorktreeLaunch {
 	sessionFile?: string;
 	sourceSessionFile?: string;
 	handoffMessage?: string;
+	/** Non-fatal provisioning problems reported with the launch. */
+	diagnostics?: string[];
 }
 
 export interface FailedWorktreeManifest extends JsonObject {

package/maestro/runtime/worktree-operations.ts

@@ -11,7 +11,7 @@ import {
 	unlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isRecord, type JsonObject } from "../core/config/type-guards.ts";
 import type { SurfaceProvider } from "../core/surface-provider.ts";
 import type {
@@ -245,7 +245,19 @@ function resolveSource(path: string): string {
 			"--git-common-dir",
 		]).trim(),
 	);
-	const root = realpathSync(dirname(common));
+	// A submodule's common directory lives under the superproject's
+	// .git/modules; only core.worktree, including included config, names its checkout.
+	const configured = git(common, [
+		`--git-dir=${common}`,
+		"config",
+		"--default",
+		"",
+		"--get",
+		"core.worktree",
+	]).trim();
+	const root = realpathSync(
+		configured ? resolve(common, configured) : dirname(common),
+	);
 	if (realpathSync(git(root, ["rev-parse", "--show-toplevel"]).trim()) !== root)
 		throw new Error("Cannot prove source repository root");
 	if (
@@ -600,6 +612,8 @@ export function createWorktreeCleanupOperations(
 		},
 		removeWorkspace: (id) =>
 			provider.removeWorktreeSurface(id, { timeoutMs: CLEANUP_TIMEOUT_MS }),
+		reportOpenedPrimaryWorkspace: (sourceRepo, claims) =>
+			provider.reportOpenedPrimaryWorkspace({ sourceRepo, claims }),
 		removeCheckout: (source, path) => {
 			git(source, ["worktree", "remove", "--", path]);
 		},

package/maestro/surfaces/fake/fake-surface-provider.ts

@@ -1,7 +1,9 @@
 import path from "node:path";
+import type { OpenedPrimaryWorkspaceReport } from "../../core/opened-primary-workspace.ts";
 import type {
 	CreateSurfaceOptions,
 	CreateWorktreeSurfaceOptions,
+	ReportOpenedPrimaryWorkspaceInput,
 	SurfaceInfo,
 	SurfaceProcessInfo,
 	SurfaceProvider,
@@ -147,6 +149,12 @@ export class FakeSurfaceProvider implements SurfaceProvider {
 		this.removeSurface(worktree.surfaceId);
 	}
 
+	reportOpenedPrimaryWorkspace(
+		_input: ReportOpenedPrimaryWorkspaceInput,
+	): OpenedPrimaryWorkspaceReport | undefined {
+		return undefined;
+	}
+
 	setupHint(): string {
 		return "Fake surface provider is always available in memory.";
 	}

package/maestro/surfaces/herdr/herdr-surface-provider.ts

@@ -1,12 +1,14 @@
 import type {
 	CreateSurfaceOptions,
 	CreateWorktreeSurfaceOptions,
+	ReportOpenedPrimaryWorkspaceInput,
 	SurfaceInfo,
 	SurfaceProcessInfo,
 	SurfaceProvider,
 	WorktreeSurface,
 	WorktreeSurfaceInfo,
 } from "../../core/surface-provider.ts";
+import type { OpenedPrimaryWorkspaceReport } from "../../core/opened-primary-workspace.ts";
 import type { PaneInspection, SurfaceHandle } from "../../core/types.ts";
 import type { PaneConfig } from "../../core/config/pane-config.ts";
 import {
@@ -16,6 +18,7 @@ import {
 	createHerdrSurfaceSplit,
 	createHerdrWorktree,
 	focusHerdrWorkspace,
+	reportOpenedPrimaryWorkspace as reportHerdrOpenedPrimaryWorkspace,
 	getHerdrPaneProcessInfo,
 	getHerdrPaneProcessInfoAsync,
 	inspectHerdrPane,
@@ -111,12 +114,20 @@ export class HerdrSurfaceProvider implements SurfaceProvider {
 			opts.branch,
 			opts.base,
 		);
-		return {
+		const surface: WorktreeSurface = {
 			path: worktree.path,
 			branch: worktree.branch,
 			workspaceId: worktree.workspaceId,
 			surfaceId: worktree.paneId,
 		};
+		if (worktree.diagnostics) surface.diagnostics = worktree.diagnostics;
+		return surface;
+	}
+
+	reportOpenedPrimaryWorkspace(
+		input: ReportOpenedPrimaryWorkspaceInput,
+	): Promise<OpenedPrimaryWorkspaceReport | undefined> {
+		return reportHerdrOpenedPrimaryWorkspace(input.sourceRepo, input.claims);
 	}
 
 	removeWorktreeSurface(