pi-herdr-agents 3.0.2 → 3.1.0

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/index.ts

@@ -12,7 +12,8 @@ export type {
 	RuntimeCandidate,
 } from "./run-session.ts";
 export { defaultRetainSurface } from "./surface-retention.ts";
-export { initializeTaskModels } from "./task-model-init.ts";
+export { startTaskModelInit } from "./task-model-init.ts";
+export type { TaskModelInitOutcome } from "./task-model-init.ts";
 export {
 	createDefaultRunSession,
 	observePiActivity,

package/maestro/runtime/task-model-init.ts

@@ -1,22 +1,119 @@
 import {
 	buildTaskModelBrief,
 	buildTaskModelInitPrompt,
+	collectApprovalOffers,
+	DIRECT_WRITER_DESTINATION,
+	type NonEmpty,
+	type OfferCallback,
+	openApprovalOffer,
+	selectApprovalRoute,
+	type TaskModelBrief,
+	type TaskModelFacts,
+	type TaskModelInitDestination,
 	type TaskModelRegistryProjector,
 	type TaskModelRegistrySnapshot,
 } from "../core/config/task-model-init.ts";
-import type { ModelConfig } from "../core/config/model-config.ts";
+import type { ModelConfigSnapshot } from "../core/config/model-config.ts";
 import { projectTaskModelRegistry } from "../adapters/pi/task-model-init.ts";
 
-/** Compose the active Pi projection with current saved choices and the complete init prompt. */
-export function initializeTaskModels(input: {
+/** What one init request did. Only `started` submitted a prompt. */
+export type TaskModelInitOutcome =
+	| { kind: "started"; destination: string }
+	| { kind: "not-started"; reason: string };
+
+export interface TaskModelInitInput {
+	preferences: string;
+	/** Saved settings and the revision of the same bytes; throws when invalid. */
+	readConfig(): ModelConfigSnapshot;
 	/** The host supplies its actual active registry to this projector exactly once. */
 	projectActiveRegistry(
 		project: TaskModelRegistryProjector,
 	): TaskModelRegistrySnapshot;
-	current: ModelConfig;
-	preferences: string;
-}): string {
-	const snapshot = input.projectActiveRegistry(projectTaskModelRegistry);
-	const brief = buildTaskModelBrief(snapshot, input.current, input.preferences);
-	return buildTaskModelInitPrompt(brief);
+	/** Emits the approval request for this brief and returns when listeners did. */
+	emitApprovalRequest(brief: TaskModelBrief, offer: OfferCallback): void;
+	isToolActive(name: string): boolean;
+	/** Hands the prompt to Pi; a throw means Pi did not take it. */
+	submit(prompt: string): void;
+}
+
+/** Listeners share the brief; freezing it keeps the prompt equal to what they saw. */
+function deepFreeze<T>(value: T): T {
+	if (value == null || Object(value) !== value) return value;
+	// SAFETY: Object(value) === value holds only for objects and functions.
+	for (const item of Object.values(value as object)) deepFreeze(item);
+	return Object.freeze(value);
+}
+
+function isNonEmpty<T>(values: T[]): values is NonEmpty<T> {
+	return values.length > 0;
+}
+
+/**
+ * Capture one brief, pick where its proposal goes, and submit the prompt. It
+ * runs synchronously, so nothing can change between selection and submission.
+ * An opened offer that is not submitted is cancelled before this returns.
+ */
+export function startTaskModelInit(
+	input: TaskModelInitInput,
+): TaskModelInitOutcome {
+	const notStarted = (reason: string): TaskModelInitOutcome => ({
+		kind: "not-started",
+		reason,
+	});
+	let snapshot: ModelConfigSnapshot;
+	try {
+		snapshot = input.readConfig();
+	} catch (error) {
+		return notStarted(error instanceof Error ? error.message : String(error));
+	}
+	const { models } = input.projectActiveRegistry(projectTaskModelRegistry);
+	if (!isNonEmpty<TaskModelFacts>(models))
+		return notStarted(
+			"the active registry has no authenticated models, so there is nothing to rank. Configure a provider, then run /subagents-init again",
+		);
+	const brief = deepFreeze(
+		buildTaskModelBrief({
+			models,
+			current: snapshot.config,
+			configRevision: snapshot.revision,
+			preferences: input.preferences,
+		}),
+	);
+	const route = selectApprovalRoute(
+		collectApprovalOffers((offer) => input.emitApprovalRequest(brief, offer)),
+	);
+	let destination: TaskModelInitDestination;
+	let cancel: () => string | undefined = () => undefined;
+	switch (route.kind) {
+		case "direct":
+			destination = DIRECT_WRITER_DESTINATION;
+			break;
+		case "refused":
+			return notStarted(route.reason);
+		case "offer": {
+			const opened = openApprovalOffer(route.offer);
+			if (opened.kind === "blocked") return notStarted(opened.reason);
+			destination = opened.destination;
+			cancel = opened.cancel;
+			break;
+		}
+		default: {
+			const _exhaustive: never = route;
+			return _exhaustive;
+		}
+	}
+	const cancelled = (reason: string): TaskModelInitOutcome => {
+		const problem = cancel();
+		return notStarted(problem ? `${reason}; ${problem}` : reason);
+	};
+	if (!input.isToolActive(destination.toolName))
+		return cancelled(`${destination.toolName} is not an active tool`);
+	try {
+		input.submit(buildTaskModelInitPrompt(brief, destination));
+	} catch (error) {
+		return cancelled(
+			`Pi did not accept the init prompt (${error instanceof Error ? error.message : String(error)})`,
+		);
+	}
+	return { kind: "started", destination: destination.toolName };
 }

package/maestro/runtime/worktree-operations.ts

@@ -612,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(