pi-squire 0.15.0 → 0.16.0

package/src/resume-checks.ts

@@ -3,17 +3,18 @@
 // prerequisites once, then per record the window, session file, agent, thinking
 // level and model. None of them changes anything; killing an exited window and
 // deciding trust stay with the resume itself.
+
 import { statSync } from "node:fs";
 import { isAbsolute } from "node:path";
-
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
 import { type Agent, disabledProblem, isThinking, withoutLocked } from "./agents.ts";
 import { sessionHeaderCwd, sessionIdOf, sessionThinking } from "./result-sessions.ts";
 import { deriveState, finishedModel, locateSession, type StartedRecorded } from "./results.ts";
 import type { ResumeDeps, ResumeRequest } from "./resume.ts";
+import { ownerDetails, sessionIsOwned } from "./session-owner.ts";
 import { requireTmuxVersion, type TmuxWindow } from "./tmux.ts";
 import { ownWindow, windowState } from "./tracking.ts";
+import { assertResumeAuthority } from "./tree-view.ts";
 import type { WindowPlacement } from "./window-placement.ts";
 
 /**
@@ -110,12 +111,23 @@ function lastThinking(record: StartedRecorded, sessionPath: string): string {
 	return level !== undefined && isThinking(level) ? level : record.thinking;
 }
 
+export function assertNoOwner(record: StartedRecorded): void {
+	if (sessionIsOwned(sessionIdOf(record)))
+		throw new Error(
+			`delegation ${record.id} is already open in another process: ${ownerDetails(sessionIdOf(record))}; send it a message instead of resuming it`,
+		);
+}
+
 /** Steps 5 and 6: the session file and the agent, and no resume of the delegation already under way. */
 export function recordCheck(
 	deps: ResumeDeps,
 	record: StartedRecorded,
 	ctx: ExtensionContext,
 ): { session: SessionFile; agent: Agent } {
+	assertResumeAuthority(record, ctx);
+	assertNoOwner(record);
+	deps.authorize?.(record.id, ctx);
+	deps.admit?.(record.agent, ctx);
 	const session = sessionFor(record, ctx);
 	const roster = deps.roster(ctx);
 	const disabled = disabledProblem(roster, record.agent);

package/src/resume-picker.ts

@@ -19,7 +19,7 @@ export type ResumePickerDeps = {
 const optionFor = (record: StartedRecorded): string =>
 	`${recordedName(record)} · ${record.agent} · ${record.id.slice(0, 8)}`;
 
-export async function pickResume(ctx: ExtensionContext, deps: ResumePickerDeps): Promise<void> {
+export async function pickResume(ctx: ExtensionContext, deps: ResumePickerDeps, id?: string): Promise<void> {
 	const unavailable = deps.unavailable();
 	if (unavailable !== undefined) {
 		ctx.ui.notify(`delegate: ${unavailable}`, "error");
@@ -37,7 +37,14 @@ export async function pickResume(ctx: ExtensionContext, deps: ResumePickerDeps):
 		return;
 	}
 	const options = records.map(optionFor);
-	const picked = await ctx.ui.select("Resume which delegation?", options);
+	const picked =
+		id === undefined
+			? await ctx.ui.select("Resume which delegation?", options)
+			: options[records.findIndex((record) => record.id === id)];
+	if (id !== undefined && picked === undefined) {
+		ctx.ui.notify("delegate: selected delegation cannot be resumed now", "warning");
+		return;
+	}
 	const record = records[options.indexOf(picked ?? "")];
 	if (record === undefined) return;
 	const task = await ctx.ui.editor(`Follow-up for ${recordedName(record)}`);

package/src/resume.ts

@@ -10,9 +10,11 @@ import type { ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-
 import { type TObject, Type } from "typebox";
 
 import { type Agent, type Roster, THINKING_LEVELS } from "./agents.ts";
+import { type Identity, readIdentity } from "./identity.ts";
 import { sessionIdOf } from "./result-sessions.ts";
 import { isStarted, type Results, recordedName, type StartedRecorded } from "./results.ts";
 import {
+	assertNoOwner,
 	inFlight,
 	passes,
 	preflight,
@@ -23,6 +25,8 @@ import {
 } from "./resume-checks.ts";
 import type { OpenedWindow, TmuxClient } from "./tmux.ts";
 import { listWindows, type ToolDef, toolResult } from "./tracking.ts";
+import { bindTree, failedTree, type Reservation } from "./tree-registry.ts";
+import { recordedIdentity } from "./tree-view.ts";
 import type { WindowPlacement } from "./window-placement.ts";
 import type { Workspace } from "./workspace.ts";
 
@@ -52,6 +56,10 @@ export type ResumeDeps = {
 	/** The window placement for this call; throws on an invalid setting. */
 	placement(): WindowPlacement;
 	roster(ctx: ExtensionContext): Roster;
+	/** Depth/current-parent grant check, before even an exited window is killed. */
+	admit?(agent: string, ctx: ExtensionContext): void;
+	authorize?(id: string, ctx: ExtensionContext): void;
+	reserve(record: StartedRecorded, id: string, ctx: ExtensionContext): Promise<Reservation>;
 	/** The parent's current model and thinking level, which a field the agent locks but does not set keeps. */
 	parentDefaults(ctx: ExtensionContext): { model?: string; thinking: string };
 	chooseModel(
@@ -66,6 +74,7 @@ export type ResumeDeps = {
 		cwd: string,
 		ctx: ExtensionContext,
 		signal: AbortSignal | undefined,
+		agent: string,
 	): Promise<{ workspace: Workspace; trusted: boolean }>;
 	/** Mail the task to a session id; returns the request id. */
 	sendTask(to: string, task: string): string;
@@ -78,10 +87,12 @@ export type ResumeDeps = {
 		trusted: boolean;
 		cwd: string;
 		sessionDir: string;
-		start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean };
+		start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean; notices: string[] };
 		toolCallId: string | undefined;
 		ctx: ExtensionContext;
 		placement: WindowPlacement;
+		identity: Identity;
+		sessionId: string;
 	}): Promise<OpenedWindow>;
 };
 
@@ -166,7 +177,7 @@ function resultSchema(delegateSchema: TObject): TObject {
 
 /** The model, thinking and auto-exit a resume runs with, and the directory and workspace it opens in. */
 type Plan = {
-	start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean };
+	start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean; notices: string[] };
 	chosen: Awaited<ReturnType<ResumeDeps["chooseModel"]>>;
 	workspace: Workspace;
 	trusted: boolean;
@@ -182,11 +193,11 @@ async function planResume(
 	const { record, agent, session, request } = input;
 	const { thinking, chosen } = await settleModel(deps, input, ctx);
 	const autoExit = request.autoExit ?? record.autoExit === true;
-	const prepared = await deps.prepareDirectory(session.cwd, ctx, signal);
+	const prepared = await deps.prepareDirectory(session.cwd, ctx, signal, agent.name);
 	// A managed worktree keeps its launch facts while the session still runs in it.
 	const workspace = record.workspace?.cwd === prepared.workspace.cwd ? record.workspace : prepared.workspace;
 	return {
-		start: { agent, model: chosen.model, rest: chosen.rest, thinking, autoExit },
+		start: { agent, model: chosen.model, rest: chosen.rest, thinking, autoExit, notices: chosen.notices },
 		chosen,
 		workspace,
 		trusted: prepared.trusted,
@@ -210,26 +221,40 @@ async function mailTask(deps: ResumeDeps, windowId: string, sessionId: string, t
 	}
 }
 
+function publishResumeRequest(token: Reservation, requestId: string, windowId: string, ctx: ExtensionContext): void {
+	try {
+		bindTree(token, { requestId });
+	} catch (error) {
+		ctx.ui.notify(
+			`delegate: window ${windowId} opened and task mail was sent, but shared request publication failed: ${String(error)}. Local tracking continues; accounting reconciles before the next admission.`,
+			"warning",
+		);
+	}
+}
+
 async function startResume(
 	deps: ResumeDeps,
 	input: {
-		record: StartedRecorded;
+		record: StartedRecorded & { identity: Identity };
 		session: SessionFile;
 		plan: Plan;
 		task: string;
 		toolCallId: string | undefined;
 		placement: WindowPlacement;
+		reservation: Reservation;
 	},
 	ctx: ExtensionContext,
 ): Promise<Resumed> {
 	const { record, session, plan, task, toolCallId, placement } = input;
 	const { start, chosen, workspace } = plan;
-	const id = randomUUID();
+	const id = input.reservation.id;
 	const sessionId = sessionIdOf(record);
 	const name = recordedName(record);
 	const { id: windowId, session: windowSession } = await deps.open({
 		id,
 		name,
+		identity: record.identity,
+		sessionId,
 		sessionPath: session.path,
 		workspace,
 		trusted: plan.trusted,
@@ -241,9 +266,11 @@ async function startResume(
 		placement,
 	});
 	const requestId = await mailTask(deps, windowId, sessionId, task);
+	publishResumeRequest(input.reservation, requestId, windowId, ctx);
 	deps.results.recordStart(
 		{
 			id,
+			identity: readIdentity(sessionId) ?? record.identity,
 			agent: start.agent.name,
 			...(start.agent.displayName === undefined ? {} : { displayName: start.agent.displayName }),
 			model: start.model,
@@ -284,6 +311,13 @@ async function startResume(
 	};
 }
 
+/** Resolve once before any exited-window kill; never reconstruct a lost root from cwd. */
+function requiredIdentity(record: StartedRecorded): Identity {
+	const own = recordedIdentity(record);
+	if (!own) throw new Error(`delegation ${record.id} has no original root placement identity; resume refused`);
+	return own;
+}
+
 /** Resume `request.id`: every eligibility check in order, then the launch. */
 async function resume(
 	deps: ResumeDeps,
@@ -293,19 +327,34 @@ async function resume(
 ): Promise<Resumed> {
 	const placement = await preflight(deps); // read once, before the exited window is killed or anything is mailed
 	if (request.task.trim() === "") throw new Error("a task is required");
-	const record = newestStarted(deps.results, request.id);
-	await ensureExited(record, deps.tmux);
-	const { session, agent } = recordCheck(deps, record, ctx);
-	inFlight.add(record.id);
+	deps.authorize?.(request.id, ctx);
+	const found = newestStarted(deps.results, request.id);
+	const record = { ...found, identity: requiredIdentity(found) };
+	deps.admit?.(record.agent, ctx);
+	assertNoOwner(record);
+	deps.results.checkStorage(true);
+	const reservation = await deps.reserve(record, randomUUID(), ctx);
+	let acquired = false;
 	try {
+		await ensureExited(record, deps.tmux);
+		const { session, agent } = recordCheck(deps, record, ctx);
+		inFlight.add(record.id);
+		acquired = true;
 		const plan = await planResume(deps, { record, agent, session, request }, ctx, signal);
 		return await startResume(
 			deps,
-			{ record, session, plan, task: request.task, toolCallId: request.toolCallId, placement },
+			{ record, session, plan, task: request.task, toolCallId: request.toolCallId, placement, reservation },
 			ctx,
 		);
+	} catch (error) {
+		try {
+			failedTree(reservation);
+		} catch (accounting) {
+			ctx.ui.notify(`delegate: reservation remains charged: ${String(accounting)}`, "error");
+		}
+		throw error;
 	} finally {
-		inFlight.delete(record.id);
+		if (acquired) inFlight.delete(record.id);
 	}
 }
 
@@ -342,7 +391,7 @@ function resumeTool(deps: ResumeDeps): ToolDef {
 		name: "delegation_resume",
 		label: "Resume delegation",
 		description:
-			"Continue an exited delegate with a follow-up task: reopen its own session, so it keeps the context it built, in a new window. The follow-up is recorded as a new delegation, and its result arrives as a message on its own, like a delegate's. Use it when the next task needs what the delegate already read or decided; for unrelated work, use delegate. It refuses a delegation that is still running (send it a message instead), one whose window is still open, an older delegation of a chain that was already resumed (it names the newest), and one whose working directory is gone, a removed worktree included. A delegate whose window was killed mid-turn can be resumed.",
+			"Only this session’s direct children may be resumed; viewing a descendant does not grant authority, and fork/clone copies must return to the original parent. Current depth, grants, caps, tools and trust are checked again. Continue an exited delegate with a follow-up task: reopen its own session, so it keeps the context it built, in a new window. The follow-up is recorded as a new delegation, and its result arrives as a message on its own, like a delegate's. Use it when the next task needs what the delegate already read or decided; for unrelated work, use delegate. It refuses a delegation that is still running (send it a message instead), one whose window is still open, an older delegation of a chain that was already resumed (it names the newest), and one whose working directory is gone, a removed worktree included. A delegate whose window was killed mid-turn can be resumed.",
 		parameters: Type.Object({
 			id: Type.String({ description: "The delegation to resume, from a delegate result or delegation_status." }),
 			task: Type.String({

package/src/session-owner.ts

@@ -0,0 +1,279 @@
+// One Squire actor per exact Pi session. Already-claimed Squire mail is staged
+// before dispatch so a duplicate provider cannot steal it from the live owner.
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { basename, join } from "node:path";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { readChildRecords } from "./child-tasks.ts";
+import { readIdentity } from "./identity.ts";
+import { readState, writeState } from "./local-state.ts";
+import { type Inbound, isStarted, sessionIdOf } from "./results.ts";
+import { processAlive, withTreeLock } from "./tree-lock.ts";
+import { readTree } from "./tree-registry.ts";
+
+type OwnerRecord = { pid: number; token: string };
+type Callback = (...args: unknown[]) => unknown;
+const base = (session: string): string => join(getAgentDir(), "squire", "owners", encodeURIComponent(session));
+const lock = <T>(session: string, work: () => T): T => withTreeLock(`${base(session)}.lock`, work);
+function ownerRecord(session: string): OwnerRecord | undefined {
+	const saved: OwnerRecord | undefined = readState<OwnerRecord>(`${base(session)}.json`);
+	if (saved && (!Number.isSafeInteger(saved.pid) || saved.pid < 1 || typeof saved.token !== "string"))
+		throw new Error(`invalid Squire process owner ${base(session)}.json; repair that owner record before reopening`);
+	return saved;
+}
+export function ownerDetails(session: string): string {
+	const path: string = `${base(session)}.json`;
+	try {
+		const saved: OwnerRecord | undefined = ownerRecord(session);
+		return `${path} (PID ${saved?.pid ?? "not recorded"})`;
+	} catch (error) {
+		return `${path} (unreadable: ${String(error)})`;
+	}
+}
+/** Observation only: matches the elected incarnation, never grants action authority. */
+export function matchesSessionOwner(session: string, pid: number, token: string): boolean {
+	const saved: OwnerRecord | undefined = ownerRecord(session);
+	return saved?.pid === pid && saved.token === token;
+}
+export function sessionIsOwned(session: string): boolean {
+	const saved: OwnerRecord | undefined = ownerRecord(session);
+	return saved !== undefined && processAlive(saved.pid);
+}
+function recognizes(session: string, input: Inbound): boolean {
+	const envelope = input.envelope as Inbound["envelope"] & { kind?: string };
+	if (envelope.kind === "request") return readIdentity(session)?.parent === envelope.from;
+	if (!Array.isArray(envelope.in_reply_to) || !envelope.in_reply_to.length) return false;
+	const matches = (record: import("./results.ts").Recorded): boolean =>
+		isStarted(record) && sessionIdOf(record) === envelope.from && envelope.in_reply_to.includes(record.requestId);
+	return readChildRecords(session).some(matches) || registryStarts(session).some(matches);
+}
+function registryStarts(session: string): import("./results.ts").Delegation[] {
+	try {
+		return readTree(readIdentity(session)?.root ?? session, 0)
+			.entries.filter((entry) => entry.identity.parent === session && entry.launch !== undefined)
+			.flatMap((entry) => (entry.launch ? [entry.launch] : []));
+	} catch {
+		return [];
+	}
+}
+export class SessionOwner {
+	readonly token: string = randomUUID();
+	session: string | undefined;
+	owned = false;
+	ctx: ExtensionContext | undefined;
+	private timer: ReturnType<typeof setInterval> | undefined;
+	private readonly inbound: Callback[] = [];
+	private draining = false;
+	private ready = false;
+	private failed = false;
+	private readonly warned: Set<string> = new Set();
+
+	private warn(message: string): void {
+		if (this.warned.has(message)) return;
+		this.warned.add(message);
+		if (this.ctx) this.ctx.ui.notify(message, "error");
+		else console.error(message);
+	}
+
+	active(): boolean {
+		if (!this.owned || this.failed || !this.session) return false;
+		try {
+			return ownerRecord(this.session)?.token === this.token;
+		} catch (error) {
+			this.warn(
+				`delegate: could not read Squire owner ${ownerDetails(this.session)}: ${String(error)}; processing is blocked until storage is repaired and this session reopened.`,
+			);
+			return false;
+		}
+	}
+	assert(): void {
+		if (this.failed)
+			throw new Error(
+				"Squire input processing failed; staged input is retained. Repair storage and reopen this session.",
+			);
+		if (!this.owned || !this.session || ownerRecord(this.session)?.token !== this.token)
+			throw new Error(
+				`Squire is inactive: this session is already open in another process, or has shut down. ${this.session ? ownerDetails(this.session) : "No owner session"}. Reopen the owning session only once.`,
+			);
+	}
+	start(ctx: ExtensionContext): void {
+		this.ctx = ctx;
+		this.session = ctx.sessionManager.getSessionId();
+		this.ready = false;
+		this.failed = false;
+		this.warned.clear();
+		this.owned = false;
+		this.owned = lock(this.session, () => {
+			const saved: OwnerRecord | undefined = ownerRecord(this.session as string);
+			if (saved && saved.token !== this.token && processAlive(saved.pid)) return false;
+			writeState(`${base(this.session as string)}.json`, { pid: process.pid, token: this.token });
+			return true;
+		});
+		if (!this.owned) {
+			ctx.ui.notify(
+				`delegate: this Pi session is already open in another process: ${ownerDetails(this.session)}. Squire actions are disabled here; return to the existing owner. Inspect the PID/record if stale; never evict a live owner.`,
+				"error",
+			);
+			ctx.shutdown();
+		}
+	}
+	listen(callback: Callback): () => void {
+		this.inbound.push(callback);
+		return (): void => {
+			const i: number = this.inbound.indexOf(callback);
+			if (i >= 0) this.inbound.splice(i, 1);
+		};
+	}
+	receive(payload: Inbound): void {
+		if (payload?.handled || !payload?.envelope) return;
+		const session: string | undefined = payload.envelope.to || this.session;
+		if (!session) return;
+		if (!recognizes(session, payload)) {
+			if (this.active() && this.ready) for (const callback of this.inbound) callback(payload);
+			return;
+		}
+		try {
+			const dir: string = join(base(session), "inbound");
+			mkdirSync(dir, { recursive: true, mode: 0o700 });
+			writeState(join(dir, arrivalName(payload)), { ...payload, handled: false });
+		} catch (error) {
+			this.unstaged(payload, error);
+			return;
+		}
+		payload.handled = true;
+		this.drain();
+	}
+	drain(): void {
+		if (!this.active() || !this.ready || !this.session || this.draining) return;
+		this.draining = true;
+		try {
+			this.deliver();
+		} catch (error) {
+			this.failed = true;
+			this.ctx?.ui.notify(
+				`delegate: staged task input retained: ${String(error)}; repair storage and reopen this session.`,
+				"error",
+			);
+		} finally {
+			this.draining = false;
+		}
+	}
+	private unstaged(payload: Inbound, error: unknown): void {
+		this.warn(`delegate: could not stage claimed Squire input ${payload.path}: ${String(error)}.`);
+		try {
+			if (this.active() && this.ready) for (const callback of this.inbound) callback(payload);
+			if (payload.handled) return;
+		} catch (failure) {
+			this.failed = true;
+			this.warn(`delegate: direct Squire input processing failed: ${String(failure)}.`);
+		}
+		payload.handled = true;
+		this.warn(
+			`delegate: claimed Squire input ${payload.envelope.id} at ${payload.path} could not be retained or delivered to its owner. Delivery is NOT lossless with unwritable staging here: repair storage and ask the sender to resend; no plain-mail fallback was used.`,
+		);
+	}
+	private deliver(): void {
+		if (!this.session || ownerRecord(this.session)?.token !== this.token) throw new Error("Squire ownership changed");
+		const dir: string = join(base(this.session), "inbound");
+		let names: string[];
+		try {
+			names = readdirSync(dir)
+				.filter((name) => name.endsWith(".json"))
+				.sort();
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		for (const name of names) {
+			const path: string = join(dir, name);
+			const payload: Inbound | undefined = readState<Inbound>(path);
+			if (!payload) continue;
+			this.assert();
+			for (const callback of this.inbound) callback(payload);
+			if (!payload.handled) throw new Error("staged Squire input did not match restored task state");
+			this.assert();
+			unlinkSync(path);
+		}
+	}
+	arm(): void {
+		if (!this.owned) return;
+		this.ready = true;
+		this.drain();
+		if (this.timer) clearInterval(this.timer);
+		this.timer = setInterval(() => this.drain(), 250).unref();
+	}
+	stop(): void {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = undefined;
+		this.ready = false;
+		try {
+			if (this.session && this.owned)
+				lock(this.session, () => {
+					if (ownerRecord(this.session as string)?.token === this.token)
+						unlinkSync(`${base(this.session as string)}.json`);
+				});
+		} finally {
+			this.owned = false;
+			this.ctx = undefined;
+		}
+	}
+}
+
+function arrivalName(payload: Inbound): string {
+	const parsed: number = Date.parse(payload.envelope.ts);
+	const time: string = String(Number.isFinite(parsed) ? parsed : 0).padStart(16, "0");
+	return `${time}-${encodeURIComponent(basename(payload.path || ""))}-${encodeURIComponent(payload.envelope.id)}.json`;
+}
+
+/** Wrap only Squire registrations; mail and other extensions keep their own API. */
+export function ownedAPI(pi: ExtensionAPI, owner: SessionOwner): ExtensionAPI {
+	const events: ExtensionAPI["events"] = {
+		...pi.events,
+		on: (name: string, handler: Parameters<ExtensionAPI["events"]["on"]>[1]) =>
+			name === "message:inbound" ? owner.listen(handler as Callback) : pi.events.on(name, handler),
+		emit: (name: string, payload: unknown) => {
+			if (name === "message:scan" && !owner.active()) return;
+			owner.assert();
+			pi.events.emit(name, payload);
+		},
+	};
+	return new Proxy(pi, {
+		get(target: ExtensionAPI, key: string | symbol, receiver: unknown): unknown {
+			if (key === "events") return events;
+			const value: unknown = Reflect.get(target, key, receiver);
+			if (typeof value !== "function") return value;
+			return (...args: unknown[]): unknown => dispatchAPI(target, key, value as Callback, args, owner);
+		},
+	});
+}
+function dispatchAPI(
+	target: ExtensionAPI,
+	key: string | symbol,
+	call: Callback,
+	args: unknown[],
+	owner: SessionOwner,
+): unknown {
+	if (key === "on") {
+		const [name, handler] = args as [string, Callback];
+		return Reflect.apply(call, target, [
+			name,
+			(...params: unknown[]) => (name === "session_shutdown" || owner.active() ? handler(...params) : undefined),
+		]);
+	}
+	if (key === "registerTool" || key === "registerCommand" || key === "registerShortcut") {
+		const index: number = key === "registerTool" ? 0 : 1;
+		const definition: Record<string, unknown> = args[index] as Record<string, unknown>;
+		const method: string = key === "registerTool" ? "execute" : "handler";
+		const callback: Callback = definition[method] as Callback;
+		args[index] = {
+			...definition,
+			[method]: (...params: unknown[]): unknown => {
+				owner.assert();
+				return callback(...params);
+			},
+		};
+	}
+	if (["appendEntry", "sendMessage", "sendUserMessage", "setModel", "setActiveTools"].includes(String(key)))
+		owner.assert();
+	return Reflect.apply(call, target, args);
+}