pi-squire 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-squire",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
 	"keywords": [
 		"pi-package",
@@ -55,6 +55,7 @@
 		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@earendil-works/pi-tui": "1.3.0",
 		"@types/node": "26.6.5",
+		"pi-session-mail": "0.6.0",
 		"typebox": "1.4.3",
 		"typescript": "7.0.2"
 	}

package/src/agents.ts

@@ -11,19 +11,17 @@
 // holding a comma, makes the file invalid; absent `model` means the parent's),
 // `thinking` (absent or unknown means the parent's level), `tools` (the
 // delegate's complete tool list; absent means the parent's tools, empty means
-// none; a list entry holding a comma makes the file invalid), `extensions`
-// (extra extension paths for the delegate only; `~` expands, relative paths resolve against the agent file's folder, and a
-// missing path leaves the agent out), `auto-exit` (default true),
+// none; a list entry holding a comma makes the file invalid), `auto_exit` (default true),
 // `prompt_mode` (`append`, the default, or `replace`), `enabled` (false leaves
 // the agent out) and `locked` (true, or a list of `model` and `thinking`). Any
 // other key is ignored, left for whatever else reads the file. The body is the
 // delegate's instructions. A file that cannot be read as an agent is disabled:
 // left out, with a warning, and a call naming it is refused with the reason.
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { join } from "node:path";
 
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { toolMatches } from "./tool-ceiling.ts";
 
 /** The levels `pi --thinking` accepts. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
@@ -57,8 +55,12 @@ export type Agent = {
 	model?: string;
 	/** Undefined means the parent's level. */
 	thinking?: Thinking;
-	/** Whether the delegate closes itself after a normal completion; `auto-exit`, default true. */
+	/** Whether the delegate closes itself after a normal completion; `auto_exit`, default true. */
 	autoExit: boolean;
+	/** Current grant: true for the roster, or an explicit list of child identities. */
+	allowNested?: true | string[];
+	/** Presence of a permission map only; not a policy evaluation or privilege comparison. */
+	hasPermission?: boolean;
 	/**
 	 * The delegate's complete tool list, from a `tools` line of tool names:
 	 * undefined when the field is absent or holds only `-name` entries (the
@@ -67,8 +69,6 @@ export type Agent = {
 	tools?: string[];
 	/** The names or `*` patterns a `tools` line of only `-name` entries takes off the parent's tools; empty otherwise. */
 	toolsExcept: string[];
-	/** Absolute paths of extra extensions the delegate loads, from `extensions`; empty when absent. */
-	extensions: string[];
 	/** Models to try, in order, when `model` is usage-limited; from `fallback`, empty when absent. */
 	fallback: string[];
 	/** The fields a call cannot override, from `locked`. */
@@ -121,10 +121,16 @@ function parseAgent(name: string, path: string, text: string): Parsed {
 	if (enabled === null)
 		return { invalid: `${path} has enabled ${JSON.stringify(fields.enabled)}, not true or false`, notes: [] };
 	if (enabled === false) return { notes: [] };
-	const autoExit = flag(fields["auto-exit"]);
+	const autoExit = flag(fields.auto_exit);
 	if (autoExit === null)
-		return { invalid: `${path} has auto-exit ${JSON.stringify(fields["auto-exit"])}, not true or false`, notes: [] };
-	const launch = launchFields(path, fields);
+		return { invalid: `${path} has auto_exit ${JSON.stringify(fields.auto_exit)}, not true or false`, notes: [] };
+	const nested = fields.allow_nested_delegation === false ? undefined : fields.allow_nested_delegation;
+	if (!validNested(nested))
+		return {
+			invalid: `${path} has allow_nested_delegation that is not true, false or a list of agent names`,
+			notes: [],
+		};
+	const launch = toolsField(path, fields);
 	if ("invalid" in launch) return { ...launch, notes: [] };
 	const model = field(fields, "model");
 	const fallback = toolList(fields.fallback);
@@ -135,6 +141,7 @@ function parseAgent(name: string, path: string, text: string): Parsed {
 	// A field that cannot be used is dropped with a note; it never costs the agent.
 	const notes: string[] = [];
 	const thinking = thinkingField(path, fields, notes);
+	warnDelegationTools(path, nested, launch.tools, notes);
 	if (fallback === null)
 		notes.push(`${path} has fallback ${JSON.stringify(fields.fallback)}, not a list of models; ignored`);
 	if (fields["exclude-tools"] !== undefined)
@@ -148,6 +155,9 @@ function parseAgent(name: string, path: string, text: string): Parsed {
 			...(model === undefined ? {} : { model }),
 			...(thinking === undefined ? {} : { thinking }),
 			autoExit: autoExit ?? true,
+			...(nested === undefined ? {} : { allowNested: nested === true ? true : [...new Set(nested as string[])] }),
+			hasPermission:
+				fields.permission !== null && typeof fields.permission === "object" && !Array.isArray(fields.permission),
 			...launch,
 			fallback: fallback ?? [],
 			locked: lockedFields(path, fields, { model, thinking }, notes),
@@ -158,6 +168,28 @@ function parseAgent(name: string, path: string, text: string): Parsed {
 	};
 }
 
+function warnDelegationTools(path: string, nested: unknown, tools: string[] | undefined, notes: string[]): void {
+	if (nested === true || (Array.isArray(nested) && nested.length > 0)) return;
+	if (
+		tools?.some((name) =>
+			["delegate", "delegation_status", "delegation_close", "delegation_resume"].some((tool) =>
+				toolMatches(name, tool),
+			),
+		)
+	)
+		notes.push(
+			`${path} lists delegation tools without allow_nested_delegation; listing tools alone does not grant nesting`,
+		);
+}
+
+function validNested(value: unknown): boolean {
+	return (
+		value === undefined ||
+		value === true ||
+		(Array.isArray(value) && value.every((entry) => typeof entry === "string" && NAME.test(entry)))
+	);
+}
+
 /**
  * Why a `model` or `fallback` entry makes the file invalid: a `*` pattern.
  * Each entry names one model (an exact `provider/id` or an alias Pi resolves
@@ -277,31 +309,6 @@ function toolsField(
 	return { toolsExcept: minus.map((name) => name.slice(1).trim()) };
 }
 
-/** The `tools` and `extensions` fields, or why the agent is invalid. */
-function launchFields(
-	path: string,
-	frontmatter: Record<string, unknown>,
-): { tools?: string[]; toolsExcept: string[]; extensions: string[] } | { invalid: string } {
-	const tools = toolsField(path, frontmatter);
-	if ("invalid" in tools) return tools;
-	const paths = toolList(frontmatter.extensions);
-	if (paths === null)
-		return {
-			invalid: `${path} has extensions ${JSON.stringify(frontmatter.extensions)}, not a comma-separated list of paths`,
-		};
-	const extensions = (paths ?? []).map((entry) => resolveExtension(entry, dirname(path)));
-	const absent = extensions.find((entry) => !existsSync(entry));
-	if (absent !== undefined) return { invalid: `${path} has extension ${absent}, which does not exist` };
-	return { ...tools, extensions };
-}
-
-/** An extension path as an absolute one: `~` is the home directory, a relative path is against the agent file's folder. */
-function resolveExtension(entry: string, dir: string): string {
-	if (entry === "~") return homedir();
-	if (entry.startsWith("~/")) return join(homedir(), entry.slice(2));
-	return isAbsolute(entry) ? entry : resolve(dir, entry);
-}
-
 /** A list of names (tools or models), comma-separated or a YAML list of names; undefined when absent, null when it is neither. */
 function toolList(value: unknown): string[] | undefined | null {
 	if (value === undefined || value === null) return undefined;
@@ -391,6 +398,20 @@ export function readRoster(agentDir: string, projectDir?: string): Roster {
 		if (agent !== undefined) agents.push(agent);
 		else if (invalid !== undefined) disable(name, path, invalid);
 	}
+	for (const agent of agents) {
+		const targets = agent.allowNested === true ? agents.map((item) => item.name) : (agent.allowNested ?? []);
+		for (const name of targets) {
+			const child = agents.find((item) => item.name === name);
+			if (!child)
+				warnings.push(
+					`${agent.path} allows unknown or unavailable nested agent ${JSON.stringify(name)}; it cannot launch until present in the current roster`,
+				);
+			else if (agent.hasPermission && !child.hasPermission)
+				warnings.push(
+					`${agent.path} grants nested agent ${JSON.stringify(name)} (${child.path}) without a permission block; this is a delegation grant, not proof of equal or lesser permission authority`,
+				);
+		}
+	}
 	return { agents, disabled, warnings };
 }
 

package/src/child-tasks.ts

@@ -0,0 +1,221 @@
+// The direct parent's durable task facts and processing inbox. Not a tree
+// index: the shared registry can publish these facts without owning answers.
+import { join } from "node:path";
+import {
+	type ContextEvent,
+	type ContextEventResult,
+	type ExtensionAPI,
+	type ExtensionContext,
+	getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import { readState, writeState } from "./local-state.ts";
+import type { Recorded } from "./result-types.ts";
+import type { MessageDetails } from "./results.ts";
+
+export type ChildOutcome = {
+	key: string;
+	content: string;
+	details: MessageDetails;
+	/** Root display was queued; processing still waits for a model request/settle. */
+	delivered?: boolean;
+};
+type State = { records: Recorded[]; outcomes: ChildOutcome[]; paused?: boolean };
+export function readChildRecords(session: string): Recorded[] {
+	const path = join(getAgentDir(), "squire", "child-tasks", `${encodeURIComponent(session)}.json`);
+	const state = readState<State>(path);
+	if (state !== undefined && (!state || !Array.isArray(state.records) || !Array.isArray(state.outcomes)))
+		throw new Error(`invalid child task record for ${session}`);
+	return state?.records ?? [];
+}
+export class ChildTasks {
+	path: string | undefined;
+	outcomes: ChildOutcome[] = [];
+	observed = new Set<string>();
+	failed = false;
+	unreadable = false;
+	restoreFailure: string | undefined;
+	paused = false;
+
+	blockRestore(error: unknown): void {
+		this.restoreFailure ??= String(error);
+		this.failed = true;
+	}
+
+	restore(session: string): Recorded[] {
+		this.path = join(getAgentDir(), "squire", "child-tasks", `${encodeURIComponent(session)}.json`);
+		this.outcomes = [];
+		this.paused = false;
+		this.observed.clear();
+		this.failed = false;
+		this.unreadable = false;
+		this.restoreFailure = undefined;
+		try {
+			const state = readState<State>(this.path);
+			if (state !== undefined && (!state || !Array.isArray(state.records) || !Array.isArray(state.outcomes)))
+				throw new Error("invalid child task record: expected records and outcomes arrays");
+			if (state?.paused !== undefined && typeof state.paused !== "boolean") throw new Error("invalid root stop state");
+			this.paused = state?.paused === true;
+			this.outcomes = state?.outcomes ?? [];
+			return state?.records ?? [];
+		} catch (error) {
+			this.failed = true;
+			this.unreadable = true;
+			throw error;
+		}
+	}
+
+	save(records: Recorded[]): void {
+		try {
+			if (this.restoreFailure)
+				throw new Error(`child task restoration failed: ${this.restoreFailure}; repair storage and reopen`);
+			if (this.unreadable) throw new Error("child tasks were unreadable; repair storage and reload before continuing");
+			if (!this.path) throw new Error("child task state has not been restored");
+			writeState(this.path, { records, outcomes: this.outcomes, paused: this.paused } satisfies State);
+			this.failed = false;
+		} catch (error) {
+			this.failed = true;
+			throw error;
+		}
+	}
+
+	storageProblem(): string | undefined {
+		if (this.unreadable) return "child tasks were unreadable; repair storage and reload before launching";
+		if (this.restoreFailure)
+			return `child task restoration failed: ${this.restoreFailure}; repair storage and reopen before launching`;
+		if (this.failed) return "child task storage failed; repair storage and reload before launching";
+		if (!this.path) return "child task storage has not been restored";
+		return undefined;
+	}
+
+	delivered(key: string): void {
+		for (const outcome of this.outcomes) if (outcome.key === key) outcome.delivered = true;
+	}
+
+	wakeAllowed(coordinator: boolean): boolean {
+		return coordinator || !this.paused;
+	}
+
+	replay(pi: ExtensionAPI, coordinator: boolean): void {
+		if (!this.wakeAllowed(coordinator)) return;
+		let wake = false;
+		for (const outcome of this.outcomes) {
+			if (!coordinator && outcome.delivered) {
+				wake = true;
+				continue;
+			}
+			pi.sendMessage(
+				{ customType: "delegate", content: outcome.content, details: outcome.details, display: true },
+				{ triggerTurn: true, deliverAs: "steer" },
+			);
+			this.delivered(outcome.key);
+		}
+		if (wake)
+			pi.sendMessage(
+				{
+					customType: "delegate-recovery",
+					display: false,
+					content: "[delegate] Saved delegate outcomes still need processing. Continue with them before settling.",
+				},
+				{ triggerTurn: true, deliverAs: "steer" },
+			);
+	}
+
+	observe(): void {
+		this.observed = new Set(this.outcomes.map(({ key }) => key));
+	}
+
+	settled(records: Recorded[], stopped: boolean): void {
+		if (this.restoreFailure || this.unreadable) throw new Error(this.storageProblem());
+		if (stopped) return;
+		this.outcomes = this.outcomes.filter(({ key }) => !this.observed.has(key));
+		this.observed.clear();
+		this.save(records);
+	}
+
+	needsProcessing(): boolean {
+		return this.outcomes.some(({ key }) => !this.observed.has(key));
+	}
+
+	/** Each exact model request receives all unprocessed direct-child outcomes. */
+	context(event: ContextEvent): ContextEventResult | undefined {
+		this.paused = false;
+		this.observe();
+		const missing = this.outcomes.filter(
+			({ details }) =>
+				!event.messages.some(
+					(message) =>
+						message.role === "custom" &&
+						message.customType === "delegate" &&
+						(message.details as MessageDetails | undefined)?.id === details.id &&
+						(message.details as MessageDetails | undefined)?.kind === details.kind,
+				),
+		);
+		if (!missing.length) return;
+		return {
+			messages: [
+				...event.messages,
+				...missing.map(({ content, details }) => ({
+					role: "custom" as const,
+					customType: "delegate",
+					content,
+					details,
+					display: true,
+					timestamp: Date.now(),
+				})),
+			],
+		};
+	}
+
+	register(
+		pi: ExtensionAPI,
+		records: () => Recorded[],
+		context: () => ExtensionContext | undefined,
+		coordinator: () => boolean = () => false,
+	): void {
+		let stopped = false;
+		pi.on("context", (event) => this.context(event));
+		pi.on("agent_end", (event, ctx) => {
+			const last = event.messages.findLast((message) => message.role === "assistant");
+			stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
+			if (stopped && !coordinator()) {
+				this.paused = true;
+				try {
+					this.save(records());
+				} catch (error) {
+					ctx.ui.notify(
+						`delegate: could not persist root user stop: ${String(error)}; completion is blocked.`,
+						"error",
+					);
+				}
+			}
+		});
+		pi.on("agent_before_settle", () => {
+			if (stopped || this.failed || !this.wakeAllowed(coordinator()) || !this.needsProcessing()) return;
+			// A bare continue can be rejected when the transcript ends with an
+			// assistant. Supply runnable context; context() supplies the outcomes.
+			return {
+				continue: true,
+				entries: [
+					{
+						type: "custom_message",
+						customType: "delegate",
+						content: coordinator()
+							? "[delegate] Child outcomes arrived after the last model request. Process them before your final task report."
+							: "[delegate] Delegate outcomes arrived after the last model request. Process them before finishing this response.",
+						display: true,
+					},
+				],
+			};
+		});
+		pi.on("agent_settled", () => {
+			try {
+				this.settled(records(), stopped);
+			} catch (error) {
+				context()?.ui.notify(
+					`delegate: could not persist child-result processing: ${String(error)}; completion is blocked.`,
+					"error",
+				);
+			}
+		});
+	}
+}

package/src/child.ts

@@ -16,8 +16,7 @@
 // it as a user prompt, so the task starts through the same path as a typed
 // prompt, labelled `[delegate]`. Pi 1.2.0 already prepares the system prompt
 // for custom-message runs (earendil-works/pi#5581); this takeover remains the
-// package's pinned startup delivery path. The provider still arms the
-// automatic answer for a request a listener took over.
+// package's pinned startup delivery path. task-replies.ts owns the answer.
 import type { Api, Model } from "@earendil-works/pi-ai";
 import {
 	type ExtensionAPI,
@@ -26,9 +25,9 @@ import {
 	type ModelRuntime,
 	resolveCliModel,
 } from "@earendil-works/pi-coding-agent";
-
+import { type Identity, writeIdentity } from "./identity.ts";
 import { activeMark, classify, type Response, recordLimit } from "./limits.ts";
-import { STATUS_KEY } from "./results.ts";
+import type { TaskReplies } from "./task-replies.ts";
 
 /** The launch variable that carries the parent's resolved setting. */
 export const AUTO_EXIT_ENV = "PI_DELEGATE_AUTO_EXIT";
@@ -43,8 +42,6 @@ const ON_NOTICE = "delegate: auto-exit is on; this delegate closes after its nex
 
 type Message = { role?: string; stopReason?: unknown; errorMessage?: unknown; provider?: unknown; model?: unknown };
 
-type Inbound = { envelope?: { from?: unknown; kind?: unknown; body?: unknown }; handled?: boolean };
-
 /** A run that ended on a usage-limit error leaves a mark for every Pi session. */
 function recordUsageLimit(last: Message, ctx: ExtensionContext, response?: Response): void {
 	const { provider, model, errorMessage } = last;
@@ -107,24 +104,6 @@ async function switchModel(
 	return undefined;
 }
 
-/** Take over the parent's task request and send it as a user prompt. */
-function registerTakeover(pi: ExtensionAPI, parent: string): void {
-	let current: ExtensionContext | undefined;
-	pi.on("session_start", async (_event, ctx) => {
-		current = ctx;
-	});
-	pi.events.on("message:inbound", (data) => {
-		const payload = data as Inbound;
-		const envelope = payload?.envelope;
-		if (payload.handled === true || envelope?.kind !== "request" || envelope.from !== parent) return;
-		payload.handled = true;
-		const text = `[delegate] Your task, from the session that started you (${parent}). Your final message this turn goes back to it automatically.\n\n${String(envelope.body ?? "")}`;
-		Promise.resolve(pi.sendUserMessage(text, { deliverAs: "steer" })).catch((err) =>
-			current?.ui.notify(`delegate: could not start the task: ${(err as Error).message}`, "error"),
-		);
-	});
-}
-
 /**
  * A usage limit or an unavailable endpoint moves the run to the next fallback
  * that is usable and not marked, and continues it in this session; each
@@ -173,34 +152,49 @@ function fallbackReason(last: Message | undefined): Failure | undefined {
 /** This delegate's footer icon, picked once per load. */
 const ICON = Math.random() < 0.5 ? "👦" : "👧";
 
-function showStatus(ctx: ExtensionContext, armed: boolean): void {
+function showStatus(ctx: ExtensionContext, armed: boolean, agent?: string): void {
 	const { theme } = ctx.ui;
-	const agent = process.env[AGENT_ENV];
 	const label = agent === undefined || agent === "" ? "delegate" : `${theme.fg("accent", agent)} delegate`;
 	ctx.ui.setStatus(
-		STATUS_KEY,
+		"delegate-self",
 		armed
 			? `${ICON} ${label} · auto-exit ${theme.fg("success", "on")}`
 			: `${ICON} ${label} · auto-exit ${theme.fg("dim", "off")}`,
 	);
 }
 
-export function registerChild(pi: ExtensionAPI, parent: string): void {
-	registerTakeover(pi, parent);
+function shutdownWhenActive(ctx: ExtensionContext, active: () => boolean): void {
+	setImmediate(() => {
+		if (active()) ctx.shutdown();
+	});
+}
+
+export function registerChild(
+	pi: ExtensionAPI,
+	replies: TaskReplies,
+	identity: () => Identity | undefined,
+	active: () => boolean = () => true,
+): void {
 	const setFailure = registerFallback(pi);
 
-	let armed = process.env[AUTO_EXIT_ENV] === "1";
+	let armed = false;
 	/** Whether the run that just ended finished without the user stopping it. */
 	let completed = false;
 
 	// Reload and session replacement clear extension statuses, then start again.
-	pi.on("session_start", async (_event, ctx) => showStatus(ctx, armed));
+	pi.on("session_start", async (_event, ctx) => {
+		const own = identity();
+		armed = own?.autoExit === true;
+		if (own) showStatus(ctx, armed, own.agent);
+	});
 
 	function disarm(ctx: ExtensionContext): void {
 		if (!armed) return;
 		armed = false;
+		const own = identity();
+		if (own) writeIdentity(ctx.sessionManager.getSessionId(), { ...own, autoExit: false });
 		ctx.ui.notify(OFF_NOTICE, "info");
-		showStatus(ctx, armed);
+		showStatus(ctx, armed, identity()?.agent);
 	}
 
 	// Typed text and RPC input are the user's; a prompt an extension sends is not.
@@ -221,11 +215,8 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 	// call Pi 0.99.1 ends with an `error` message, and only the signal tells a
 	// stop from a real error. Either way it is the user taking over.
 	pi.on("agent_end", async (event, ctx) => {
-		let last: Message | undefined;
-		for (let i = event.messages.length - 1; i >= 0 && last === undefined; i--) {
-			const message = event.messages[i] as Message;
-			if (message?.role === "assistant") last = message;
-		}
+		const last = event.messages.findLast((message) => message.role === "assistant") as Message | undefined;
+		if (!identity()) return;
 		const stopped = last?.stopReason === "aborted" || ctx.signal?.aborted === true;
 		if (stopped) disarm(ctx);
 		if (!stopped && last?.stopReason === "error") recordUsageLimit(last, ctx, response);
@@ -235,19 +226,22 @@ export function registerChild(pi: ExtensionAPI, parent: string): void {
 	});
 
 	pi.on("agent_settled", async (_event, ctx) => {
-		const exit = armed && completed;
+		const exit = armed && completed && replies.handled();
 		completed = false;
 		if (!exit) return;
-		// Later settle handlers (the `message:*` provider's reply among them) run first.
-		setImmediate(() => ctx.shutdown());
+		// Task settlement and its synchronous reply write have succeeded.
+		shutdownWhenActive(ctx, active);
 	});
 
 	pi.registerCommand("auto-exit", {
 		description: "Close this delegate after its next normal completion",
 		handler: async (_args, ctx) => {
+			if (!identity()) return ctx.ui.notify("auto-exit is available inside a delegate session", "error");
 			armed = true;
+			const own = identity();
+			if (own) writeIdentity(ctx.sessionManager.getSessionId(), { ...own, autoExit: true });
 			ctx.ui.notify(ON_NOTICE, "info");
-			showStatus(ctx, armed);
+			showStatus(ctx, armed, identity()?.agent);
 		},
 	});
 }

package/src/completion-holds.ts

@@ -0,0 +1,104 @@
+// Process-local completion composition. Providers own hold readiness; Squire
+// advertises only its active exact-session runtime and never owns provider rows.
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const KEY: symbol = Symbol.for("pi.completion-holds.v1");
+type Hold = { provider: string; ready: boolean };
+type Table = {
+	version: 1;
+	hosts: Map<string, Map<string, string>>;
+	holds: Map<string, Map<string, Hold>>;
+};
+const shared: Record<symbol, unknown> = globalThis as unknown as Record<symbol, unknown>;
+
+function table(create: boolean): Table | undefined {
+	const value: unknown = shared[KEY];
+	if (value === undefined) {
+		if (!create) return undefined;
+		const fresh: Table = { version: 1, hosts: new Map(), holds: new Map() };
+		shared[KEY] = fresh;
+		return fresh;
+	}
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		!("version" in value) ||
+		value.version !== 1 ||
+		!("hosts" in value) ||
+		!(value.hosts instanceof Map) ||
+		!("holds" in value) ||
+		!(value.holds instanceof Map)
+	)
+		throw new Error("invalid pi.completion-holds.v1 table; completion is blocked");
+	return value as Table;
+}
+
+function validHosts(hosts: unknown): hosts is Map<string, string> {
+	return (
+		hosts instanceof Map &&
+		[...hosts].every(
+			([name, runtime]) => typeof name === "string" && !!name && typeof runtime === "string" && !!runtime,
+		)
+	);
+}
+
+/** Missing table/no holds preserves normal completion; malformed data refuses. */
+export function externalHoldsReady(sessionId: string): boolean {
+	try {
+		const current: Table | undefined = table(false);
+		if (!current) return true;
+		const hosts: unknown = current.hosts.get(sessionId);
+		if (hosts !== undefined && !validHosts(hosts)) return false;
+		const holds: Map<string, Hold> | undefined = current.holds.get(sessionId);
+		if (holds === undefined) return true;
+		if (!(holds instanceof Map)) return false;
+		for (const [id, hold] of holds) {
+			if (
+				typeof id !== "string" ||
+				!id ||
+				typeof hold !== "object" ||
+				hold === null ||
+				typeof hold.provider !== "string" ||
+				!hold.provider ||
+				hold.ready !== true
+			)
+				return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function removeHost(sessionId: string, token: string): void {
+	// Clean our own token even if another field/version has become malformed.
+	const value: unknown = shared[KEY];
+	if (typeof value !== "object" || value === null || !("hosts" in value) || !(value.hosts instanceof Map)) return;
+	const hosts: unknown = value.hosts.get(sessionId);
+	if (!(hosts instanceof Map) || hosts.get("pi-squire") !== token) return;
+	hosts.delete("pi-squire");
+	if (hosts.size === 0) value.hosts.delete(sessionId);
+}
+
+/** Call with ownedAPI: a losing duplicate runtime must never advertise support. */
+export function registerCompletionHost(pi: ExtensionAPI): () => boolean {
+	const token: string = randomUUID();
+	let sessionId: string | undefined;
+	pi.on("session_start", (_event, ctx) => {
+		if (sessionId !== undefined) removeHost(sessionId, token);
+		sessionId = ctx.sessionManager.getSessionId();
+		const current: Table | undefined = table(true);
+		if (!current) throw new Error("completion hold table is unavailable");
+		const saved: Map<string, string> | undefined = current.hosts.get(sessionId);
+		if (saved !== undefined && !validHosts(saved)) throw new Error("invalid completion hold hosts");
+		const hosts: Map<string, string> = saved ?? new Map();
+		hosts.set("pi-squire", token);
+		current.hosts.set(sessionId, hosts);
+	});
+	pi.on("session_shutdown", () => {
+		if (sessionId !== undefined) removeHost(sessionId, token);
+		sessionId = undefined;
+	});
+	return (): boolean => sessionId !== undefined && externalHoldsReady(sessionId);
+}