pi-squire 0.14.0 → 0.16.0

package/src/tool-ceiling.ts

@@ -0,0 +1,125 @@
+// A nested launch is bounded by operations its direct parent can reach, not
+// by the schemas currently displayed. CLI registration filtering also covers
+// deferred tools and tools registered later by launch-time extensions.
+import { type Args, type ExtensionAPI, parseArgs, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+/** Match Pi's tool-list glob: only * has special meaning. */
+export function toolMatches(pattern: string, name: string): boolean {
+	const source = pattern
+		.split("*")
+		.map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+		.join(".*");
+	return new RegExp(`^${source}$`).test(name);
+}
+
+/** Includes active model-only operations, though ctx.executeTool cannot call those. */
+export function availableTools(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">): string[] {
+	const active = new Set(pi.getActiveTools());
+	return pi
+		.getAllTools()
+		.filter(
+			(tool) =>
+				tool.exposure !== "hidden" &&
+				(active.has(tool.name) || tool.exposure === "codemode" || tool.exposure === "deferred"),
+		)
+		.map((tool) => tool.name);
+}
+
+type CeilingInput = {
+	args: string[];
+	available: readonly string[];
+	registered?: readonly string[];
+	cwd: string;
+	agentDir: string;
+	trusted: boolean;
+	notices: string[];
+};
+
+function requestedTools(parsed: Args, input: CeilingInput): string[] {
+	const requested = parsed.tools ?? [];
+	if (!requested.some((name) => name.startsWith("+") || name.startsWith("-"))) return requested;
+	// Pi modifiers replace the earlier --tools selection and modify the
+	// child's defaults. Use Pi's trusted settings reader, not the parent's defaults.
+	const defaults =
+		parsed.noTools || parsed.noBuiltinTools
+			? []
+			: (SettingsManager.create(input.cwd, input.agentDir, { projectTrusted: input.trusted }).getDefaultTools() ?? [
+					"read",
+					"bash",
+					"edit",
+					"write",
+				]);
+	const selected = new Set(defaults);
+	for (const entry of requested) {
+		if (entry.startsWith("+")) selected.add(entry.slice(1));
+		else selected.delete(entry.slice(1));
+	}
+	return [...selected];
+}
+
+function ceilingNotice(input: CeilingInput, requested: string[], exclusions: string[]): void {
+	const { available } = input;
+	const removed = [
+		...new Set([
+			...requested.filter((pattern) => pattern !== "mcp__" && !pattern.includes("*") && !available.includes(pattern)),
+			...(input.registered ?? []).filter(
+				(name) => !available.includes(name) && requested.some((pattern) => toolMatches(pattern, name)),
+			),
+		]),
+	].filter((name) => !exclusions.some((pattern) => toolMatches(pattern, name)));
+	// Child-only and future registrations cannot be enumerated in the parent.
+	const bounded = [...new Set(requested.filter((pattern) => pattern.includes("*")))];
+	if (!removed.length && !bounded.length) return;
+	const parts = ["Nested tool ceiling:"];
+	if (removed.length) parts.push(`removed unavailable tools ${removed.join(", ")}.`);
+	if (bounded.length)
+		parts.push(`Restricted patterns ${bounded.join(", ")} to exact tools available to the direct parent.`);
+	input.notices.push(parts.join(" "));
+}
+
+/** Find an option terminator, not a -- token consumed as another flag’s value. */
+function optionBoundary(args: string[]): number {
+	let marker = "--squire-ceiling-boundary";
+	while (args.includes(marker)) marker += "-";
+	for (const [index, arg] of args.entries()) {
+		if (arg === "--" && !parseArgs([...args.slice(0, index + 1), marker]).unknownFlags.has(marker.slice(2)))
+			return index;
+	}
+	return args.length;
+}
+
+function exactName(name: string): boolean {
+	return !!name && name.trim() === name && !name.includes("*") && !name.includes(",") && !/^[+-]/.test(name);
+}
+
+/**
+ * Resolve the final customized CLI selection, then pin an exact registration
+ * allowlist. Run after all synchronous session:launch listeners, before spawn.
+ * args excludes the executable/launcher prefix. Unrelated args stay unchanged.
+ */
+export function enforceToolCeiling(input: CeilingInput): void {
+	const { args, available } = input;
+	const parsed = parseArgs(args);
+	const errors = parsed.diagnostics.filter((item) => item.type === "error");
+	if (errors.length)
+		throw new Error(`invalid nested launch arguments: ${errors.map((item) => item.message).join("; ")}`);
+	const requested = requestedTools(parsed, input);
+	const exclusions = parsed.excludeTools ?? [];
+	const allowed = available.filter(
+		(name) =>
+			requested.some((pattern) => toolMatches(pattern, name)) &&
+			!exclusions.some((pattern) => toolMatches(pattern, name)),
+	);
+	// Never turn a wildcard in a registered name into a grant pattern.
+	if (!allowed.every(exactName))
+		throw new Error("cannot encode the parent's tool names as an exact nested tool ceiling");
+	ceilingNotice(input, requested, exclusions);
+	const entries = allowed.some((name) => name.startsWith("mcp__")) ? allowed : [...allowed, "mcp__"];
+	// --no-tools alone would leave a previous --tools value authoritative.
+	const final = allowed.length ? ["--tools", entries.join(",")] : ["--tools", "", "--no-tools"];
+	args.splice(optionBoundary(args), 0, ...final);
+	const effective = parseArgs(args).tools;
+	const expected = allowed.length ? entries : [];
+	if (!effective || effective.length !== expected.length || effective.some((name, index) => name !== expected[index]))
+		throw new Error("could not apply the nested tool ceiling to customized launch arguments");
+}

package/src/tracking.ts

@@ -2,11 +2,11 @@
 // and the `delegation_status` and `delegation_close` tools. A delegation's
 // state comes from `results.ts` (`deriveState`); this module only asks tmux
 // about the window and words what it is told.
-import { statSync } from "node:fs";
 
+import { statSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
-
+import { Type } from "typebox";
+import { readIdentity } from "./identity.ts";
 import { type Mark, readMarks } from "./limits.ts";
 import { createPoll } from "./poll.ts";
 import { attemptLines, cwdLine, modelLabel, snapshotLines, workspaceLine } from "./render.ts";
@@ -26,11 +26,14 @@ import { inspectWorkspace, type WorkspaceSnapshot, WorkspaceSnapshotSchema } fro
 import type { TmuxClient, TmuxWindow } from "./tmux.ts";
 import { AttemptSchema } from "./tracking-attempt.ts";
 import { ago, autoExitLine, stateLine } from "./tracking-text.ts";
+import { type CloseResult, CloseSchema, closeTree } from "./tree-close.ts";
+import { accountingFor } from "./tree-view.ts";
 import type { ReadingError } from "./usage.ts";
 import { listWindows, ownWindow, windowState } from "./windows.ts";
 import { WorkspaceSchema } from "./workspace.ts";
 
-export { listWindows, ownWindow, windowState };
+export type { CloseResult };
+export { CloseSchema, listWindows, ownWindow, windowState };
 
 /** What `src/index.ts` needs from tracking. */
 export type Tracking = {
@@ -38,17 +41,16 @@ export type Tracking = {
 	registerTools(): void;
 	/** Start the poll when a delegation is running. */
 	startPolling(): void;
-	/** Close one delegation as `delegation_close` does; throws as the tool does. */
-	close(id: string): Promise<CloseResult>;
+	/** Close a recorded descendant subtree, with honest complete/partial details. */
+	close(id: string, ctx: ExtensionContext): Promise<CloseResult>;
+	/** Root-only explicit whole-tree action. */
+	closeAll(ctx: ExtensionContext): Promise<CloseResult>;
 	/** On `session_start`: rebuild the records and restart the poll. */
 	restore(ctx: ExtensionContext): void;
 	/** On `session_shutdown`: stop the poll, and declare nothing more. */
 	stop(): void;
 };
 
-/** What closing one delegation did. */
-export type CloseResult = { text: string; details: Static<typeof CloseSchema> };
-
 /** The one result every tool returns. `details` doubles as `structuredContent`, so it must match the tool's `outputSchema`; Pi does not check it. */
 export function toolResult(
 	payload: string,
@@ -64,6 +66,14 @@ const STARTED_STATES = ["closed", "done", "gone", "running", "window-closed", "u
 
 /** One started delegation in `delegation_status`'s structured result; `viewDetails` builds it. */
 const StartedSchema = Type.Object({
+	sessionId: Type.String(),
+	parent: Type.Optional(Type.String()),
+	root: Type.Optional(Type.String()),
+	depth: Type.Optional(Type.Number()),
+	accounting: Type.Optional(Type.String()),
+	canResume: Type.Boolean({
+		description: "Direct-parent authority only; current admission and exited-session checks still apply.",
+	}),
 	kind: Type.Literal("started"),
 	id: Type.String(),
 	name: Type.String(),
@@ -118,15 +128,6 @@ export const StatusSchema = Type.Object({
 	readingErrors: Type.Array(Type.Object({ provider: Type.String(), reason: Type.String(), at: Type.String() })),
 });
 
-export const CloseSchema = Type.Object({
-	id: Type.String(),
-	windowId: Type.String(),
-	windowName: Type.String(),
-	closed: Type.Literal(true),
-	alreadyClosed: Type.Boolean({ description: "An earlier delegation_close had recorded it; nothing was done." }),
-	killed: Type.Boolean({ description: "This call killed the delegate's window." }),
-});
-
 /** A tool as registered; `execute` takes the tool's own parameters, which the registration call does not check. */
 export type ToolDef = {
 	name: string;
@@ -152,6 +153,7 @@ type View = {
 	resumedAs: string | undefined;
 	/** The session its window is in now, looked up; undefined when the window is gone or unknown. */
 	windowSession: string | undefined;
+	canResume: boolean;
 };
 
 /** The view of a delegation: its state and the fields the text and details share. */
@@ -173,7 +175,17 @@ function view(
 	}
 	const snapshot = inspectWorkspace(record.workspace?.cwd, record.workspace?.git);
 	const windowSession = windows === undefined ? undefined : ownWindow(windows, record)?.session;
-	return { record, state, name: recordedName(record), sessionPath, lastActive, snapshot, resumedAs, windowSession };
+	return {
+		record,
+		state,
+		name: recordedName(record),
+		sessionPath,
+		lastActive,
+		snapshot,
+		resumedAs,
+		windowSession,
+		canResume: (record.identity?.parent ?? ctx.sessionManager.getSessionId()) === ctx.sessionManager.getSessionId(),
+	};
 }
 
 /** The text block for one delegation. */
@@ -183,6 +195,8 @@ function viewText({ record, state, name, sessionPath, lastActive, snapshot, resu
 	const lines = [
 		`${record.id} ${record.agent} (${modelLabel(record.model, record.result?.finishedModel)}, thinking ${record.thinking})`,
 		`  name: ${name}`,
+		`  identity: session ${sessionIdOf(record)} · parent ${record.identity?.parent ?? "this session"} · root ${record.identity?.root ?? "this session"} · depth ${record.identity?.depth ?? 1}`,
+		...(accountingFor(record) ? [`  shared accounting: ${accountingFor(record)} (not result processing)`] : []),
 		...(record.resumedFrom === undefined ? [] : [`  resumed from ${record.resumedFrom}`]),
 		...(resumedAs === undefined ? [] : [`  resumed as ${resumedAs}`]),
 		`  state: ${stateLine(state, record)}${seen}`,
@@ -207,9 +221,16 @@ function viewDetails({
 	lastActive,
 	snapshot,
 	windowSession,
+	canResume,
 }: View): Record<string, unknown> {
 	return {
 		kind: "started",
+		sessionId: sessionIdOf(record),
+		parent: record.identity?.parent,
+		root: record.identity?.root,
+		depth: record.identity?.depth,
+		accounting: accountingFor(record),
+		canResume,
 		id: record.id,
 		name,
 		agent: record.agent,
@@ -276,7 +297,7 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 		name: "delegation_status",
 		label: "Delegation status",
 		description:
-			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, working directory, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
+			"This session’s descendant delegations, scoped to its own subtree. Parent/root/depth and stable session ids identify ownership; only a direct parent may resume a child. Shared accounting does not acknowledge result processing. Each delegation is reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Call it to check on a delegation that seems stuck or to find its files; a result arrives as a message on its own, so there is no need to call it to wait for one. Names the delegation id, agent, session name, model, thinking, window, working directory, delegate session path and result envelope path. A running delegation also shows when its session file was last written; a long gap may mean it is stuck but does not prove it. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
 		parameters: Type.Object({
 			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
 		}),
@@ -327,68 +348,49 @@ function statusTool(results: Results, tmux: TmuxClient, readingErrors: () => Rea
 	};
 }
 
-/** Close one delegation: kill its window when it is open and record the close; throws when it cannot. */
-export async function closeDelegation(results: Results, tmux: TmuxClient, id: string): Promise<CloseResult> {
-	const [record] = selectRecords(results, id);
-	if (!isStarted(record)) {
+/** Shared explicit-close entry point, also used by the navigator. */
+export async function closeDelegation(
+	results: Results,
+	tmux: TmuxClient,
+	id: string | undefined,
+	ctx: ExtensionContext,
+	assertActive: () => void,
+): Promise<CloseResult> {
+	const local = id ? results.find(id) : undefined;
+	if (local && !isStarted(local))
 		throw new Error(
-			`delegation ${record.id} is a workspace attempt (${record.attempt.phase}): no verified window id was recorded; a window may still exist, so close is unavailable`,
+			`delegation ${local.id} is a workspace attempt (${local.attempt.phase}); close requires a verified create outcome`,
 		);
-	}
-	const closed = (alreadyClosed: boolean, killed: boolean): CloseResult["details"] => ({
-		id: record.id,
-		windowId: record.windowId,
-		windowName: record.windowName,
-		closed: true as const,
-		alreadyClosed,
-		killed,
-	});
-	if (record.closed === true)
-		return { text: `Delegation ${record.id} is already closed.`, details: closed(true, false) };
-	let windows: TmuxWindow[];
-	try {
-		windows = await tmux.listWindows();
-	} catch (err) {
-		throw new Error(`could not ask tmux about window ${record.windowName}: ${(err as Error).message}`);
-	}
-	// Only a window with the recorded id and name is ours, exited program or not.
-	const alive = ownWindow(windows, record) !== undefined;
-	if (alive) {
-		try {
-			await tmux.kill(record.windowId);
-		} catch (err) {
-			throw new Error(`could not kill window ${record.windowName} (${record.windowId}): ${(err as Error).message}`);
-		}
-	}
-	results.recordClose(record.id);
-	const how = alive
-		? `killed window ${record.windowName} (${record.windowId})`
-		: `its window ${record.windowName} was already gone`;
-	return { text: `Closed delegation ${record.id}: ${how}.`, details: closed(false, alive) };
+	const actor = ctx.sessionManager.getSessionId();
+	const root = readIdentity(actor)?.root ?? actor;
+	const result = await closeTree({ root, actor, id, tmux, assertActive });
+	assertActive();
+	results.syncCloses();
+	return result;
 }
 
 /** The `delegation_close` tool. */
-function closeTool(results: Results, tmux: TmuxClient): ToolDef {
+function closeTool(results: Results, tmux: TmuxClient, assertActive: () => void): ToolDef {
 	return {
 		name: "delegation_close",
 		label: "Close delegation",
 		description:
-			"Close one delegation: kill its tmux window through tmux and record the close, so delegation_status reports it closed. The delegate's session file and result envelope stay on disk. An unknown or already closed id returns a message with nothing killed.",
+			"Explicitly close a descendant and its recorded subtree. Fences new child launches, kills only verified current tmux windows and retains worktrees, branches and session/result files. Any ancestor may close; only the direct parent may resume. Partial errors or unknown in-flight creates stay fenced and are reported for an explicit retry, never as successful closure.",
 		parameters: Type.Object({
 			id: Type.String({ description: "The delegation id to close." }),
 		}),
 		outputSchema: CloseSchema,
-		// Kills a window; a second close finds it recorded and does nothing.
+		// Kills only verified windows; repeats retry unresolved members and preserve confirmed facts.
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...CLOSED_WORLD },
 		async execute(
 			_toolCallId: string,
 			params: { id: string },
 			_signal: unknown,
 			_onUpdate: unknown,
-			_ctx: ExtensionContext,
+			ctx: ExtensionContext,
 		): Promise<ReturnType<typeof toolResult>> {
-			const { text, details } = await closeDelegation(results, tmux, params.id);
-			return toolResult(text, details);
+			const { text, details } = await closeDelegation(results, tmux, params.id, ctx, assertActive);
+			return { ...toolResult(text, details), ...(!details.complete ? { isError: true } : {}) };
 		},
 	};
 }
@@ -399,15 +401,20 @@ export function createTracking(
 	results: Results,
 	tmux: TmuxClient,
 	readingErrors: () => ReadingError[] = () => [],
+	views: Results = results,
+	assertActive: () => void = () => {},
 ): Tracking {
 	const poll = createPoll(pi, results, tmux);
 	return {
 		registerTools(): void {
-			pi.registerTool(statusTool(results, tmux, readingErrors) as never);
-			pi.registerTool(closeTool(results, tmux) as never);
+			pi.registerTool(statusTool(views, tmux, readingErrors) as never);
+			pi.registerTool(closeTool(results, tmux, assertActive) as never);
 		},
 		startPolling: poll.start,
-		close: (id: string): Promise<CloseResult> => closeDelegation(results, tmux, id),
+		close: (id: string, ctx: ExtensionContext): Promise<CloseResult> =>
+			closeDelegation(results, tmux, id, ctx, assertActive),
+		closeAll: (ctx: ExtensionContext): Promise<CloseResult> =>
+			closeDelegation(results, tmux, undefined, ctx, assertActive),
 		restore(ctx: ExtensionContext): void {
 			poll.arm();
 			results.restore(ctx);

package/src/tree-close.ts

@@ -0,0 +1,236 @@
+// Explicit close only. Shared structural facts fence admission; each owner
+// separately imports confirmed closes into its own semantic processing inbox.
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import type { TmuxClient, TmuxWindow } from "./tmux.ts";
+import { below } from "./tree-fence.ts";
+import { descendants, readTree, treeTransaction } from "./tree-registry.ts";
+import type { TreeClose, TreeEntry, TreeState } from "./tree-types.ts";
+
+const MemberSchema = Type.Object({
+	id: Type.String(),
+	sessionId: Type.String(),
+	windowId: Type.Optional(Type.String()),
+	windowName: Type.Optional(Type.String()),
+	outcome: Type.Union(
+		["killed", "absent", "already-closed", "not-started", "pending", "error"].map((s) => Type.Literal(s)),
+	),
+	closed: Type.Boolean(),
+	killed: Type.Boolean(),
+	error: Type.Optional(Type.String()),
+});
+export const CloseSchema = Type.Object({
+	id: Type.String(),
+	windowId: Type.Optional(Type.String()),
+	windowName: Type.Optional(Type.String()),
+	closed: Type.Boolean({ description: "True only when every member is confirmed closed or never dispatched." }),
+	complete: Type.Boolean(),
+	alreadyClosed: Type.Boolean(),
+	killed: Type.Boolean(),
+	members: Type.Array(MemberSchema),
+	error: Type.Optional(Type.String()),
+});
+export type CloseMember = {
+	id: string;
+	sessionId: string;
+	windowId?: string;
+	windowName?: string;
+	outcome: "killed" | "absent" | "already-closed" | "not-started" | "pending" | "error";
+	closed: boolean;
+	killed: boolean;
+	error?: string;
+};
+export type CloseDetails = {
+	id: string;
+	windowId?: string;
+	windowName?: string;
+	closed: boolean;
+	complete: boolean;
+	alreadyClosed: boolean;
+	killed: boolean;
+	members: CloseMember[];
+	error?: string;
+};
+export type CloseResult = { text: string; details: CloseDetails };
+
+/** Atomic capture/fence; rootAll has no entry, so also fence root admission. */
+export function beginTreeClose(root: string, actor: string, id?: string): TreeClose {
+	return treeTransaction(root, (state) => {
+		const target: string = closeTarget(state, actor, id);
+		const existing: TreeClose | undefined = state.closes?.find((close) => close.target === target);
+		if (existing) return existing;
+		const ids: Set<string> = new Set(descendants(state, target).map((entry) => entry.id));
+		const entries: TreeEntry[] = state.entries.filter((entry) => entry.sessionId === target || ids.has(entry.id));
+		for (const entry of entries) {
+			entry.closing = true;
+			if (entry.phase === "reserved") entry.phase = "not-started";
+		}
+		const close: TreeClose = { id: randomUUID(), target, entries: entries.map((entry) => entry.id) };
+		state.closes = [...(state.closes ?? []), close];
+		return close;
+	});
+}
+function closeTarget(state: TreeState, actor: string, id: string | undefined): string {
+	if (id === undefined) {
+		if (actor !== state.root) throw new Error("only the root may close all delegations");
+		return state.root;
+	}
+	const entry: TreeEntry | undefined = state.entries.find((item) => item.id === id);
+	if (!entry || entry.sessionId === actor || !below(state, entry.identity.parent, actor))
+		throw new Error(`no delegation ${JSON.stringify(id)} in this session's descendant tree; close refused`);
+	const successor: TreeEntry | undefined = state.entries.find(
+		(item) => item.resumedFrom === id && item.phase !== "not-started",
+	);
+	if (successor)
+		throw new Error(`delegation ${id} was resumed as ${successor.id}; close the newest delegation instead`);
+	return entry.sessionId;
+}
+function member(entry: TreeEntry, outcome: CloseMember["outcome"], error?: string): CloseMember {
+	return {
+		id: entry.id,
+		sessionId: entry.sessionId,
+		...(entry.windowId ? { windowId: entry.windowId } : {}),
+		...(entry.windowName ? { windowName: entry.windowName } : {}),
+		outcome,
+		closed: !["pending", "error"].includes(outcome),
+		killed: outcome === "killed",
+		...(error ? { error } : {}),
+	};
+}
+function sameLocator(a: TreeEntry, b: TreeEntry): boolean {
+	return a.windowId === b.windowId && a.windowName === b.windowName && !b.createPending;
+}
+/** Publish only positive window/no-start facts; never invent a task result. */
+function confirm(root: string, close: TreeClose, previous: TreeEntry): boolean {
+	return treeTransaction(root, (state) => {
+		const entry: TreeEntry | undefined = state.entries.find((item) => item.id === previous.id);
+		if (!entry || !sameLocator(previous, entry)) return false;
+		if (!entry.closed && !state.closes?.some((item) => item.id === close.id)) return false;
+		entry.closed = true;
+		return true;
+	});
+}
+function finishClose(root: string, token: string): boolean {
+	return treeTransaction(root, (state) => {
+		state.closes = (state.closes ?? []).filter((close) =>
+			close.entries.some((id) => {
+				const entry: TreeEntry | undefined = state.entries.find((item) => item.id === id);
+				return !entry || (!entry.closed && entry.phase !== "not-started");
+			}),
+		);
+		return !state.closes.some((close) => close.id === token);
+	});
+}
+async function closeMember(
+	root: string,
+	close: TreeClose,
+	entry: TreeEntry,
+	tmux: TmuxClient,
+	assertActive: () => void,
+): Promise<CloseMember> {
+	if (entry.phase === "not-started") return member(entry, "not-started");
+	if (entry.closed) return member(entry, "already-closed");
+	if (entry.createPending || entry.phase === "dispatched" || !entry.windowId || !entry.windowName)
+		return member(
+			entry,
+			"pending",
+			"create outcome/current window locator is unknown; reservation remains charged and fenced",
+		);
+	const windows: TmuxWindow[] = await tmux.listWindows();
+	assertActive();
+	const current: TreeEntry | undefined = readTree(root).entries.find((item) => item.id === entry.id);
+	if (!current || !sameLocator(entry, current))
+		return member(entry, "pending", "current window locator changed; retry close");
+	if (current.closed) return member(current, "already-closed");
+	const window: TmuxWindow | undefined = windows.find(
+		(item) => item.id === entry.windowId && item.name === entry.windowName,
+	);
+	if (window) await tmux.kill(window.id);
+	assertActive();
+	try {
+		if (!confirm(root, close, entry))
+			return { ...member(entry, "pending", "window changed before close publication; retry close"), killed: !!window };
+	} catch (error) {
+		return {
+			...member(
+				entry,
+				"error",
+				`window was ${window ? "killed" : "already absent"}, but close publication failed: ${String(error)}`,
+			),
+			killed: !!window,
+		};
+	}
+	return member(entry, window ? "killed" : "absent");
+}
+
+export type CloseOptions = {
+	root: string;
+	actor: string;
+	id?: string;
+	tmux: TmuxClient;
+	assertActive(): void;
+};
+/** Narrow shared control entry point; no UI/mail/foreign semantic writes. */
+export async function closeTree(options: CloseOptions): Promise<CloseResult> {
+	const { root, actor, id, tmux, assertActive } = options;
+	assertActive();
+	const close: TreeClose = beginTreeClose(root, actor, id);
+	const outcomes: Map<string, CloseMember> = new Map();
+	for (let pass = 0; pass < 3; pass++) {
+		const entries: TreeEntry[] = readTree(root)
+			.entries.filter((entry) => close.entries.includes(entry.id))
+			.sort((a, b) => b.identity.depth - a.identity.depth);
+		for (const entry of entries) {
+			if (outcomes.get(entry.id)?.closed) continue;
+			assertActive();
+			try {
+				outcomes.set(entry.id, await closeMember(root, close, entry, tmux, assertActive));
+			} catch (error) {
+				outcomes.set(entry.id, member(entry, "error", `could not close window/publication: ${String(error)}`));
+			}
+		}
+		if (![...outcomes.values()].some((item) => item.outcome === "pending")) break;
+		if (pass < 2) await new Promise<void>((resolve) => setTimeout(resolve, 25));
+		assertActive();
+	}
+	return closeResult(id ?? root, [...outcomes.values()], finishOperation(root, close.id, assertActive));
+}
+function finishOperation(root: string, token: string, assertActive: () => void): string | undefined {
+	try {
+		assertActive();
+		if (!finishClose(root, token)) return "shared close still has unresolved members; scope remains fenced";
+	} catch (error) {
+		return String(error);
+	}
+	return undefined;
+}
+function closeResult(id: string, members: CloseMember[], error: string | undefined): CloseResult {
+	const complete: boolean = !error && members.every((item) => item.closed);
+	const target: CloseMember | undefined = members.find((item) => item.id === id);
+	const details: CloseDetails = {
+		id,
+		...(target?.windowId ? { windowId: target.windowId } : {}),
+		...(target?.windowName ? { windowName: target.windowName } : {}),
+		closed: complete,
+		complete,
+		alreadyClosed: members.length > 0 && members.every((item) => item.outcome === "already-closed"),
+		killed: members.some((item) => item.killed),
+		members,
+		...(error ? { error } : {}),
+	};
+	const lines: string[] = members.map(
+		(item) =>
+			`- ${item.id}: ${item.outcome}${item.windowId ? ` ${item.windowName} (${item.windowId})` : ""}${item.error ? ` — ${item.error}` : ""}`,
+	);
+	return {
+		text: [
+			`${complete ? "Closed" : "Partial close of"} delegation subtree ${id} (${members.length} members).`,
+			...lines,
+			...(error ? [`Close operation: ${error}`] : []),
+			...(complete
+				? []
+				: ["Unresolved members remain fenced; retry this explicit close after positive window/create evidence."]),
+		].join("\n"),
+		details,
+	};
+}

package/src/tree-fence.ts

@@ -0,0 +1,51 @@
+// Admission and explicit close share session ancestry, never tmux session names.
+import type { TreeEntry, TreeIntent, TreeState } from "./tree-types.ts";
+
+export function below(state: TreeState, session: string, ancestor: string): boolean {
+	const seen: Set<string> = new Set();
+	let current: string = session;
+	while (!seen.has(current)) {
+		if (current === ancestor) return true;
+		seen.add(current);
+		const entry: TreeEntry | undefined = state.entries.find((item) => item.sessionId === current);
+		if (!entry) return false;
+		current = entry.identity.parent;
+	}
+	throw new Error("invalid delegation ancestry; operation refused");
+}
+
+export function activeFence(state: TreeState, session: string): boolean {
+	return (state.closes ?? []).some((close) => below(state, session, close.target));
+}
+
+export function fenced(state: TreeState, parent: string): boolean {
+	if (activeFence(state, parent)) return true;
+	return state.entries.some(
+		(entry) =>
+			entry.closing &&
+			entry.phase !== "not-started" &&
+			!state.entries.some((next) => next.resumedFrom === entry.id && next.phase !== "not-started") &&
+			below(state, parent, entry.sessionId),
+	);
+}
+
+/** The caller already passed 06 authority/owner checks; enforce the shared chain atomically too. */
+export function checkResumeFence(state: TreeState, intent: TreeIntent): void {
+	if (activeFence(state, intent.sessionId)) throw new Error("delegation subtree is closing; resume refused");
+	if (!intent.resumedFrom) return;
+	const previous: TreeEntry | undefined = state.entries.find((entry) => entry.id === intent.resumedFrom);
+	// 06 has already authenticated a parent-local record. With no shared session
+	//history there is no historical fence/chain to supersede; do not invent one.
+	if (!previous && !state.entries.some((entry) => entry.sessionId === intent.sessionId)) return;
+	const successor: TreeEntry | undefined = state.entries.find(
+		(entry) => entry.resumedFrom === intent.resumedFrom && entry.phase !== "not-started",
+	);
+	if (successor?.phase === "reserved") throw new Error(`delegation ${intent.resumedFrom} is already being resumed`);
+	if (
+		!previous ||
+		previous.sessionId !== intent.sessionId ||
+		previous.identity.parent !== intent.identity.parent ||
+		successor
+	)
+		throw new Error("obsolete or inconsistent shared resume chain; resume refused");
+}