pi-squire 0.14.0 → 0.16.0

package/src/tree-lock.ts

@@ -0,0 +1,77 @@
+// Lamport bakery mutex over atomic local-filesystem files. Each contender owns
+// a unique path: dead-owner cleanup never unlinks a successor's lock. There is
+// no time lease; a paused/live owner cannot be evicted. Transactions are sync.
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { readState, writeState } from "./local-state.ts";
+
+type Ticket = { pid: number; choosing: boolean; number: number };
+const pause: Int32Array = new Int32Array(new SharedArrayBuffer(4));
+
+/** PID reuse conservatively looks live; only ESRCH proves absence. */
+export function processAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function remove(path: string): void {
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+function tickets(dir: string): [string, Ticket][] {
+	const found: [string, Ticket][] = [];
+	for (const name of readdirSync(dir).filter((name) => name.endsWith(".json"))) {
+		const path: string = join(dir, name);
+		const ticket: Ticket | undefined = readState<Ticket>(path);
+		if (ticket === undefined) continue;
+		if (
+			!Number.isSafeInteger(ticket.pid) ||
+			ticket.pid < 1 ||
+			!Number.isSafeInteger(ticket.number) ||
+			ticket.number < 0 ||
+			typeof ticket.choosing !== "boolean"
+		)
+			throw new Error(`invalid tree lock ticket ${path}; admission blocked`);
+		if (!processAlive(ticket.pid)) remove(path);
+		else found.push([name, ticket]);
+	}
+	return found;
+}
+
+/** No async work inside: other calls in this process cannot deadlock on us. */
+export function withTreeLock<T>(dir: string, work: () => T, timeoutMs = 5000): T {
+	mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const name: string = `${process.pid}-${randomUUID()}.json`;
+	const path: string = join(dir, name);
+	const ticket: Ticket = { pid: process.pid, choosing: true, number: 0 };
+	writeState(path, ticket);
+	try {
+		ticket.number = 1 + Math.max(0, ...tickets(dir).map(([, item]) => item.number));
+		if (!Number.isSafeInteger(ticket.number)) throw new Error("tree lock ticket overflow");
+		ticket.choosing = false;
+		writeState(path, ticket);
+		const deadline: number = Date.now() + timeoutMs;
+		while (
+			tickets(dir).some(
+				([other, item]) =>
+					other !== name &&
+					(item.choosing || item.number < ticket.number || (item.number === ticket.number && other < name)),
+			)
+		) {
+			if (Date.now() >= deadline) throw new Error("tree registry is busy; retry the operation (no launch was queued)");
+			Atomics.wait(pause, 0, 0, 5);
+		}
+		return work();
+	} finally {
+		remove(path);
+	}
+}

package/src/tree-notice.ts

@@ -0,0 +1,124 @@
+// Bounded discovery is a notice only. Exact-session restore never uses this budget.
+import { statSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { findSession } from "./result-sessions.ts";
+import { ownerDetails, sessionIsOwned } from "./session-owner.ts";
+import type { TmuxClient, TmuxWindow } from "./tmux.ts";
+import { listTreeRoots, readTree, type TreeEntry, treePath } from "./tree-registry.ts";
+import { listWindows } from "./windows.ts";
+
+export const NOTICE_TREES = 64;
+export const NOTICE_OWNERS = 10;
+export const NOTICE_MS = 200;
+export async function treeNotice(
+	ctx: ExtensionContext,
+	tmux: TmuxClient,
+	active: () => boolean = () => true,
+): Promise<void> {
+	const deadline: number = performance.now() + NOTICE_MS;
+	const session: string = ctx.sessionManager.getSessionId();
+	const dir: string = ctx.sessionManager.getSessionDir();
+	const roots: string[] = listTreeRoots().filter((root) => root !== session);
+	const newest: string[] = roots.sort((a, b) => modified(b) - modified(a)).slice(0, NOTICE_TREES);
+	if (!newest.length) return;
+	const windows: TmuxWindow[] | undefined = await noticeWindows(tmux, deadline);
+	if (!active()) return;
+	if (!windows) {
+		ctx.ui.notify(
+			"delegate: owner discovery unavailable: tmux could not be asked within the total notice budget; no absence or ownership was inferred.",
+			"warning",
+		);
+		return;
+	}
+	const owners: Map<string, TreeEntry> = new Map();
+	let unavailable = 0,
+		scanned = 0,
+		ownerErrors = 0;
+	for (const root of newest) {
+		if (!active() || remaining(deadline) <= 0 || owners.size >= NOTICE_OWNERS) break;
+		try {
+			collectOwners(root, session, dir, windows, owners, deadline);
+		} catch {
+			unavailable++;
+		}
+		scanned++;
+		await new Promise<void>((resolve) => setImmediate(resolve));
+	}
+	if (!active()) return;
+	ownerErrors = reportOwners(ctx, dir, owners, deadline);
+	if (roots.length > NOTICE_TREES || scanned < newest.length || unavailable || ownerErrors)
+		ctx.ui.notify(
+			`delegate: discovery is limited to newest ${NOTICE_TREES} trees and ${NOTICE_OWNERS} owners in this agent/session directory, with a ${NOTICE_MS} ms total budget and 1 MiB per tree; ${unavailable} registries unavailable and ${ownerErrors} owner records unreadable. Reopen an exact owner to restore its full tree.`,
+			"warning",
+		);
+}
+function reportOwners(ctx: ExtensionContext, dir: string, owners: Map<string, TreeEntry>, deadline: number): number {
+	let ownerErrors = 0;
+	for (const [parent, entry] of [...owners].slice(0, NOTICE_OWNERS)) {
+		const path: string | undefined = remaining(deadline) > 0 ? findSession(dir, parent) : undefined;
+		let action: string;
+		try {
+			action = sessionIsOwned(parent)
+				? "Its Squire owner is already open; return to that process."
+				: `Reopen the owning Pi session with pi --session ${shellArg(path ?? parent)} --session-dir ${shellArg(dir)}.`;
+		} catch {
+			ownerErrors++;
+			action = `Owner status is unavailable: ${ownerDetails(parent)}. Inspect it before reopening.`;
+		}
+		ctx.ui.notify(
+			`delegate: earlier session ${parent} has running delegates (tree ${entry.identity.root}). ${action} This session does not adopt them.`,
+			"info",
+		);
+	}
+	return ownerErrors;
+}
+async function noticeWindows(tmux: TmuxClient, deadline: number): Promise<TmuxWindow[] | undefined> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		return await Promise.race([
+			listWindows(tmux),
+			new Promise<undefined>((resolve) => {
+				timer = setTimeout(() => resolve(undefined), remaining(deadline));
+			}),
+		]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+function remaining(deadline: number): number {
+	return Math.max(0, deadline - performance.now());
+}
+function collectOwners(
+	root: string,
+	session: string,
+	dir: string,
+	windows: TmuxWindow[],
+	owners: Map<string, TreeEntry>,
+	deadline: number,
+): void {
+	if (statSync(treePath(root)).size > 1024 * 1024) throw new Error("tree exceeds notice byte budget");
+	for (const entry of readTree(root, Math.min(20, remaining(deadline))).entries) {
+		if (owners.size >= NOTICE_OWNERS || remaining(deadline) <= 0) return;
+		if (entry.identity.parent !== session && entry.sessionDir === dir && live(entry, windows))
+			owners.set(entry.identity.parent, entry);
+	}
+}
+function shellArg(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function modified(root: string): number {
+	try {
+		return statSync(treePath(root)).mtimeMs;
+	} catch {
+		return 0;
+	}
+}
+function live(entry: TreeEntry, windows: TmuxWindow[]): boolean {
+	return (
+		entry.phase === "started" &&
+		!entry.finished &&
+		!entry.closed &&
+		windows.some((window) => window.id === entry.windowId && window.name === entry.windowName && !window.exited)
+	);
+}

package/src/tree-registry.ts

@@ -0,0 +1,365 @@
+// One registry per root owns structural/admission accounting. Parent-local
+// child facts and frozen worker replies remain semantic authorities. No bodies,
+// mailboxes, processing inboxes, or ancestor-liveness policy live here.
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readChildRecords } from "./child-tasks.ts";
+import type { Identity } from "./identity.ts";
+import { readState, writeState } from "./local-state.ts";
+import { sessionIdOf } from "./result-sessions.ts";
+import { isStarted, type Recorded } from "./result-types.ts";
+import { sessionIsOwned } from "./session-owner.ts";
+import { readTaskState, taskStatePath } from "./task-store.ts";
+import type { TmuxClient, TmuxWindow } from "./tmux.ts";
+import { checkResumeFence, fenced } from "./tree-fence.ts";
+import { processAlive, withTreeLock } from "./tree-lock.ts";
+import { treeCaps } from "./tree-settings.ts";
+import type { Reservation, TreeCounts, TreeEntry, TreeIntent, TreeState } from "./tree-types.ts";
+import { assertRootPlacement } from "./window-placement.ts";
+import { listWindows } from "./windows.ts";
+
+export type { Reservation, TreeCounts, TreeEntry, TreeIntent, TreeState } from "./tree-types.ts";
+
+export function treePath(root: string): string {
+	return join(getAgentDir(), "squire", "trees", `${encodeURIComponent(root)}.json`);
+}
+/** Discovery only; callers choose notice/view scope, never adopt another root. */
+export function listTreeRoots(): string[] {
+	try {
+		return readdirSync(join(getAgentDir(), "squire", "trees"))
+			.filter((name) => name.endsWith(".json"))
+			.map((name) => decodeURIComponent(name.slice(0, -5)));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+}
+function load(root: string): TreeState {
+	const saved: TreeState | undefined = readState<TreeState>(treePath(root));
+	const state: TreeState = saved === undefined ? { version: 1, root, entries: [] } : saved;
+	if (state?.version !== 1 || state.root !== root || !Array.isArray(state.entries))
+		throw new Error(`invalid tree registry for ${root}; admission blocked`);
+	const ids: Set<string> = new Set();
+	for (const entry of state.entries) {
+		if (
+			!entry ||
+			typeof entry.id !== "string" ||
+			ids.has(entry.id) ||
+			typeof entry.sessionId !== "string" ||
+			entry.identity?.root !== root ||
+			typeof entry.identity.parent !== "string" ||
+			!Number.isSafeInteger(entry.ownerPid) ||
+			entry.ownerPid < 1 ||
+			!["reserved", "dispatched", "started", "not-started"].includes(entry.phase)
+		)
+			throw new Error(`invalid entry in tree registry for ${root}; admission blocked`);
+		validateFields(entry);
+		ids.add(entry.id);
+	}
+	validateCloses(state, ids);
+	return state;
+}
+
+function validateCloses(state: TreeState, ids: Set<string>): void {
+	if (state.closes === undefined) return;
+	if (!Array.isArray(state.closes)) throw new Error("invalid close fences; admission blocked");
+	const tokens: Set<string> = new Set();
+	for (const close of state.closes) {
+		if (
+			!close ||
+			typeof close.id !== "string" ||
+			!close.id ||
+			tokens.has(close.id) ||
+			typeof close.target !== "string" ||
+			(close.target !== state.root && !state.entries.some((entry) => entry.sessionId === close.target)) ||
+			!Array.isArray(close.entries) ||
+			!close.entries.every((id) => typeof id === "string" && ids.has(id)) ||
+			new Set(close.entries).size !== close.entries.length
+		)
+			throw new Error(`invalid close fence for ${state.root}; admission blocked`);
+		tokens.add(close.id);
+	}
+}
+
+function validateFields(entry: TreeEntry): void {
+	const own = entry.identity;
+	assertRootPlacement(own.rootPlacement);
+	if (
+		!Number.isSafeInteger(own.depth) ||
+		own.depth < 1 ||
+		typeof own.agent !== "string" ||
+		!Array.isArray(own.chain) ||
+		!own.chain.every((name) => typeof name === "string") ||
+		typeof own.autoExit !== "boolean"
+	)
+		throw new Error(`invalid identity in tree entry ${entry.id}`);
+	for (const key of ["finished", "gone", "closed", "closing", "createPending"] as const)
+		if (entry[key] !== undefined && typeof entry[key] !== "boolean")
+			throw new Error(`invalid ${key} in tree entry ${entry.id}`);
+	for (const key of ["requestId", "windowId", "windowName", "cwd", "sessionDir", "resumedFrom"] as const)
+		if (entry[key] !== undefined && typeof entry[key] !== "string")
+			throw new Error(`invalid ${key} in tree entry ${entry.id}`);
+}
+/** Shared close/launch boundary. Callback is synchronous; never await tmux/UI. */
+export function treeTransaction<T>(root: string, work: (state: TreeState) => T): T {
+	return withTreeLock(`${treePath(root)}.lock`, () => {
+		const state: TreeState = load(root);
+		const result: T = work(state);
+		writeState(treePath(root), state);
+		return result;
+	});
+}
+export function readTree(root: string, timeoutMs = 5000): TreeState {
+	return withTreeLock(`${treePath(root)}.lock`, () => load(root), timeoutMs);
+}
+export function treeCounts(state: TreeState): TreeCounts {
+	const charged: TreeEntry[] = state.entries.filter((entry) => entry.phase !== "not-started");
+	return {
+		lifetime: charged.length,
+		concurrent: charged.filter(
+			(entry) =>
+				!entry.finished &&
+				!entry.closed &&
+				(!entry.gone ||
+					(!state.entries.some((next) => next.resumedFrom === entry.id && next.phase !== "not-started") &&
+						sessionIsOwned(entry.sessionId))),
+		).length,
+	};
+}
+
+/** Session-based ancestry survives a coordinator's absent process and resumes. */
+export function descendants(state: TreeState, ancestor: string): TreeEntry[] {
+	const sessions: Set<string> = new Set([ancestor]);
+	let changed = true;
+	while (changed) {
+		changed = false;
+		for (const entry of state.entries)
+			if (sessions.has(entry.identity.parent) && !sessions.has(entry.sessionId)) {
+				sessions.add(entry.sessionId);
+				changed = true;
+			}
+	}
+	return state.entries.filter((entry) => sessions.has(entry.identity.parent));
+}
+function entryFor(state: TreeState, token: Reservation): TreeEntry {
+	const entry: TreeEntry | undefined = state.entries.find((entry) => entry.id === token.id);
+	if (!entry) throw new Error(`missing tree reservation ${token.id}`);
+	return entry;
+}
+
+/** Read-only preflight also reused under the admission lock against races. */
+export function assertParentPlacement(state: TreeState, identity: Identity): void {
+	if (
+		state.entries.some(
+			(entry) => entry.sessionId === identity.parent && entry.identity.rootPlacement !== identity.rootPlacement,
+		)
+	)
+		throw new Error("conflicting rootPlacement with recorded direct parent; launch refused");
+}
+
+export function reserveTree(intent: TreeIntent): Reservation {
+	assertRootPlacement(intent.identity.rootPlacement);
+	const root: string = intent.identity.root;
+	return treeTransaction(root, (state) => {
+		reconcileFacts(state);
+		assertParentPlacement(state, intent.identity);
+		const caps = treeCaps();
+		const counts: TreeCounts = treeCounts(state);
+		if (fenced(state, intent.identity.parent)) throw new Error("delegation subtree is closing; launch refused");
+		checkResumeFence(state, intent);
+		if (state.entries.some((entry) => entry.id === intent.id)) throw new Error(`duplicate reservation ${intent.id}`);
+		if (state.entries.some((entry) => entry.sessionId === intent.sessionId && entry.phase === "dispatched"))
+			throw new Error(
+				`session ${intent.sessionId} has an earlier launch whose outcome is unknown; another resume is refused while its reservation remains charged. Its start in a window or a terminal result can resolve the uncertainty.`,
+			);
+		for (const [key, count] of [
+			["maxConcurrentDelegates", counts.concurrent],
+			["maxDelegatesPerRoot", counts.lifetime],
+		] as const)
+			if (caps[key] > 0 && count >= caps[key])
+				throw new Error(`${key}: current count ${count}, limit ${caps[key]}; launch refused (no queue)`);
+		state.entries.push({ ...intent, ownerPid: process.pid, phase: "reserved" });
+		return { root, id: intent.id };
+	});
+}
+
+export function bindTree(
+	token: Reservation,
+	facts: Partial<Pick<TreeEntry, "requestId" | "windowName" | "cwd" | "workspace">>,
+): void {
+	treeTransaction(token.root, (state) => Object.assign(entryFor(state, token), facts));
+}
+export function dispatchTree(token: Reservation): void {
+	treeTransaction(token.root, (state) => {
+		const entry: TreeEntry = entryFor(state, token);
+		if (entry.phase !== "reserved" || entry.closing || fenced(state, entry.identity.parent))
+			throw new Error("tree reservation is no longer dispatchable");
+		entry.phase = "dispatched";
+		entry.createPending = true;
+	});
+}
+export function openedTree(token: Reservation, windowId: string): void {
+	treeTransaction(token.root, (state) => {
+		const entry: TreeEntry = entryFor(state, token);
+		entry.phase = "started";
+		entry.windowId = windowId;
+		entry.createPending = false;
+	});
+}
+/** A child can locate its own window even if its opener lost tmux's response. */
+export function claimTree(root: string, session: string, window: { id: string; name: string } | undefined): void {
+	treeTransaction(root, (state) => {
+		const candidates: TreeEntry[] = state.entries.filter(
+			(entry) =>
+				entry.sessionId === session &&
+				(entry.phase === "dispatched" || entry.phase === "started") &&
+				!entry.finished &&
+				!entry.closed &&
+				!state.entries.some((next) => next.resumedFrom === entry.id && next.phase !== "not-started"),
+		);
+		if (candidates.length !== 1) return;
+		const entry: TreeEntry | undefined = candidates[0];
+		if (!entry) return;
+		entry.phase = "started";
+		if (window) {
+			entry.windowId = window.id;
+			entry.windowName = window.name;
+			entry.createPending = false;
+		}
+	});
+}
+/** Only a confirmed pre-start failure may refund lifetime. Unknown stays charged. */
+export function failedTree(token: Reservation, notOpened = false): void {
+	treeTransaction(token.root, (state) => {
+		const entry: TreeEntry = entryFor(state, token);
+		if (entry.phase === "reserved" || (entry.phase === "dispatched" && notOpened && !entry.finished)) {
+			entry.phase = "not-started";
+			entry.createPending = false;
+		}
+	});
+}
+
+function applyRecord(entry: TreeEntry, record: Recorded): void {
+	if (!isStarted(record)) return;
+	entry.launch = { ...record };
+	// Do not store semantic results or child processing facts in this index.
+	delete (entry.launch as Partial<typeof record>).result;
+	delete (entry.launch as Partial<typeof record>).gone;
+	delete (entry.launch as Partial<typeof record>).closed;
+	entry.phase = "started";
+	entry.createPending = false;
+	// A same-id manual reopen can positively locate a newer window. Historical
+	// parent facts must not overwrite that current locator at the next admission.
+	if (!entry.windowId || (!entry.closed && (!entry.gone || !sessionIsOwned(entry.sessionId)))) {
+		entry.windowId = record.windowId;
+		entry.windowName = record.windowName;
+	}
+	entry.requestId = record.requestId;
+	entry.cwd = record.cwd;
+	entry.workspace = record.workspace;
+	entry.sessionDir = record.sessionDir;
+	if (record.result) entry.finished = true;
+	if (record.gone) entry.gone = true;
+	if (record.closed) entry.closed = true;
+}
+
+/** Publish only already-durable local facts. It never acknowledges outcomes. */
+export function publishTreeRecords(root: string, parent: string, records: Recorded[]): void {
+	if (!records.some(isStarted)) return;
+	treeTransaction(root, (state) => {
+		for (const record of records) {
+			if (!isStarted(record)) continue;
+			let entry: TreeEntry | undefined = state.entries.find((item) => item.id === record.id);
+			if (!entry && record.identity?.root === root) {
+				entry = {
+					id: record.id,
+					sessionId: sessionIdOf(record),
+					identity: record.identity,
+					ownerPid: process.pid,
+					phase: "started",
+					resumedFrom: record.resumedFrom,
+				};
+				state.entries.push(entry);
+			}
+			if (entry?.identity.parent === parent) applyRecord(entry, record);
+		}
+	});
+}
+
+/** The worker invokes this after freezing its reply, before transport/dequeue. */
+export function finishTree(root: string, session: string, requests: readonly string[]): void {
+	treeTransaction(root, (state) => {
+		bindOrphanRequest(state, session, requests);
+		for (const entry of state.entries)
+			if (entry.sessionId === session && entry.requestId && requests.includes(entry.requestId)) {
+				entry.finished = true;
+				entry.phase = "started";
+			}
+	});
+}
+
+// Resume mails after open. Recover the send/bind crash gap only when both
+// the unresolved launch and the as-yet-unbound request are unambiguous.
+function bindOrphanRequest(state: TreeState, session: string, requests: readonly string[]): void {
+	const candidates: TreeEntry[] = state.entries.filter(
+		(entry) => entry.sessionId === session && !entry.requestId && entry.phase === "started",
+	);
+	const unknown: string[] = requests.filter((id) => !state.entries.some((entry) => entry.requestId === id));
+	if (candidates.length === 1 && unknown.length === 1) {
+		const candidate: TreeEntry | undefined = candidates[0];
+		if (candidate) candidate.requestId = unknown[0];
+	}
+}
+function markFinished(entry: TreeEntry): void {
+	entry.finished = true;
+	entry.phase = "started";
+}
+function reconcileTask(state: TreeState, entry: TreeEntry): void {
+	const task = readTaskState(taskStatePath(entry.sessionId));
+	if (task && (!Array.isArray(task.outbox) || !Array.isArray(task.requests)))
+		throw new Error(`invalid task outbox for ${entry.sessionId}`);
+	if (task?.parent === entry.identity.parent)
+		bindOrphanRequest(
+			state,
+			entry.sessionId,
+			task.requests.map((request) => request.id),
+		);
+	if (entry.requestId && task?.outbox.some((reply) => reply.ids.includes(entry.requestId as string)))
+		markFinished(entry);
+}
+function reconcileFacts(state: TreeState): void {
+	const parents: Map<string, Recorded[]> = new Map();
+	for (const entry of state.entries) {
+		const parent: string = entry.identity.parent;
+		if (!parents.has(parent)) parents.set(parent, readChildRecords(parent));
+		const record: Recorded | undefined = parents.get(parent)?.find((record) => record.id === entry.id);
+		if (record) applyRecord(entry, record);
+		reconcileTask(state, entry);
+		if (entry.phase === "reserved" && !processAlive(entry.ownerPid)) entry.phase = "not-started";
+	}
+}
+function reconcileWindows(state: TreeState, snapshot: TreeState, windows: TmuxWindow[]): void {
+	for (const previous of snapshot.entries) {
+		if (previous.phase !== "started" || !previous.windowId) continue;
+		const entry: TreeEntry | undefined = state.entries.find((item) => item.id === previous.id);
+		if (!entry || entry.windowId !== previous.windowId || entry.windowName !== previous.windowName) continue;
+		const window: TmuxWindow | undefined = windows.find(
+			(window) => window.id === entry.windowId && window.name === entry.windowName,
+		);
+		if (!window || window.exited) entry.gone = true;
+	}
+}
+/** Snapshot before tmux: a newly started child cannot be judged by an old list. */
+export async function reconcileTree(root: string, tmux: TmuxClient): Promise<void> {
+	const snapshot: TreeState = readTree(root);
+	const windows: TmuxWindow[] | undefined = snapshot.entries.some(
+		(entry) => entry.phase === "started" && !entry.finished && !entry.gone && !entry.closed,
+	)
+		? await listWindows(tmux)
+		: undefined;
+	treeTransaction(root, (state) => {
+		reconcileFacts(state);
+		if (windows) reconcileWindows(state, snapshot, windows);
+	});
+}

package/src/tree-settings.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { maxDepth } from "./identity.ts";
+
+export type TreeCaps = { maxConcurrentDelegates: number; maxDelegatesPerRoot: number };
+
+/** Call-time settings; malformed cap state must never silently become unlimited. */
+export function treeCaps(): TreeCaps {
+	const file: string = join(getAgentDir(), "squire", "settings.json");
+	let settings: Record<string, unknown>;
+	try {
+		settings = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT")
+			throw new Error(`could not read tree caps in ${file}: ${String(error)}`);
+		settings = {};
+	}
+	if (!settings || typeof settings !== "object" || Array.isArray(settings))
+		throw new Error(`invalid tree caps in ${file}: expected an object`);
+	const nested: boolean = maxDepth() > 1;
+	const caps: TreeCaps = { maxConcurrentDelegates: nested ? 16 : 0, maxDelegatesPerRoot: nested ? 64 : 0 };
+	for (const key of ["maxConcurrentDelegates", "maxDelegatesPerRoot"] as const) {
+		const value: unknown = settings[key];
+		if (value === undefined) continue;
+		if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+			throw new Error(`invalid ${key} in ${file}: expected a nonnegative integer (0 means unlimited)`);
+		caps[key] = value;
+	}
+	return caps;
+}

package/src/tree-types.ts

@@ -0,0 +1,32 @@
+import type { Identity } from "./identity.ts";
+import type { Delegation } from "./results.ts";
+import type { Workspace } from "./workspace.ts";
+
+/** Shared structural/admission facts, never parent outcome-processing state. */
+export type TreeEntry = {
+	id: string;
+	sessionId: string;
+	identity: Identity;
+	ownerPid: number;
+	phase: "reserved" | "dispatched" | "started" | "not-started";
+	requestId?: string;
+	windowId?: string;
+	windowName?: string;
+	cwd?: string;
+	sessionDir?: string;
+	workspace?: Workspace;
+	resumedFrom?: string;
+	launch?: Delegation;
+	finished?: boolean;
+	gone?: boolean;
+	closed?: boolean;
+	/** Explicit close fences this incarnation until an authorized successor supersedes it. */
+	closing?: boolean;
+	/** Dispatch may still create a window; completion accounting alone cannot clear this. */
+	createPending?: boolean;
+};
+export type TreeClose = { id: string; target: string; entries: string[] };
+export type TreeState = { version: 1; root: string; entries: TreeEntry[]; closes?: TreeClose[] };
+export type Reservation = { root: string; id: string };
+export type TreeIntent = Pick<TreeEntry, "id" | "sessionId" | "identity" | "resumedFrom" | "sessionDir">;
+export type TreeCounts = { concurrent: number; lifetime: number };