@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/exocom/ledger.ts

@@ -8,7 +8,8 @@ import { dirname } from "node:path";
 
 import { attributePeer } from "../core/fence.ts";
 import { findWriteSetOverlaps, writeSetPathError } from "../core/ownership.ts";
-import { isSemanticFrame, truncateForInject, type ExocomAsk, type ExocomClaim, type ExocomSemanticFrame } from "./envelope.ts";
+import { frameSigningPayload, isSemanticFrame, truncateForInject, type ExocomAsk, type ExocomClaim, type ExocomSemanticFrame } from "./envelope.ts";
+import { applyCollaborationEvent, collaborationStatus, emptyCollaboration, parseCollaboration, pruneCollaboration, releaseCollaboration, retainedCollaborationEvent, type CollaborationState } from "./collaboration.ts";
 
 export type LedgerEvent = ExocomSemanticFrame;
 
@@ -33,6 +34,8 @@ export interface LedgerState {
 	/** Accepted ask ids, including completed asks, so ids cannot be recycled in this retained ledger window. */
 	askIds: string[];
 	seen: string[];
+	/** Optional only for older in-memory callers; current snapshots retain the bounded peer-work state. */
+	collaboration?: CollaborationState;
 }
 
 export type ApplyResult =
@@ -56,7 +59,7 @@ export const LEDGER_LIMITS = {
 } as const;
 
 export function emptyLedger(): LedgerState {
-	return { claims: [], asks: [], answers: [], askIds: [], seen: [] };
+	return { claims: [], asks: [], answers: [], askIds: [], seen: [], collaboration: emptyCollaboration() };
 }
 
 function remember(state: LedgerState, msgId: string): LedgerState {
@@ -99,8 +102,31 @@ export function applyLedgerEvent(state: LedgerState, event: LedgerEvent): ApplyR
 		}
 		return { ok: false, error: "malformed ledger event" };
 	}
+	const retained = retainedCollaborationEvent(state.collaboration ?? emptyCollaboration(), event.msg_id);
+	if (retained) return frameSigningPayload(retained) === frameSigningPayload(event)
+		? { ok: true, state, duplicate: true } : { ok: false, error: "msg_id conflicts with a retained collaboration fact" };
 	if (state.seen.includes(event.msg_id)) return { ok: true, state, duplicate: true };
 	switch (event.kind) {
+		case "task_create":
+		case "task_take":
+		case "task_finish":
+		case "offer":
+		case "publish": {
+			const collaboration = state.collaboration ?? emptyCollaboration();
+			const applied = applyCollaborationEvent(collaboration, event);
+			if (!applied.ok) return applied;
+			let claims = state.claims;
+			const task = collaboration.tasks.find((candidate) => candidate.created.work_key === event.work_key);
+			if (event.kind === "task_take" && task?.created.write_set.length) {
+				if (claims.some((claim) => claim.work_key === event.work_key && claim.from_session === event.from_session)) return { ok: false, error: "task pickup conflicts with an existing owned claim on this work_key" };
+				const claimed = applyLedgerEvent(state, { kind: "claim", work_key: event.work_key, from_session: event.from_session, from_name: event.from_name,
+					write_set: [...task.created.write_set], slice: task.created.description.slice(0, 256), msg_id: event.msg_id, ts: event.ts });
+				if (!claimed.ok) return claimed;
+				claims = claimed.state.claims;
+			}
+			if (event.kind === "task_finish" && task?.taken) claims = claims.filter((claim) => claim.msg_id !== task.taken!.msg_id);
+			return { ok: true, state: remember({ ...state, claims, collaboration: applied.state }, event.msg_id) };
+		}
 		case "claim": {
 			if (state.claims.length >= LEDGER_LIMITS.maxClaims) return { ok: false, error: "ledger claim limit reached" };
 			for (const path of event.write_set) {
@@ -138,12 +164,18 @@ export function applyLedgerEvent(state: LedgerState, event: LedgerEvent): ApplyR
 		case "release": {
 			const owned = state.claims.filter((claim) => claim.work_key === event.work_key && claim.from_session === event.from_session);
 			const outbound = state.asks.filter((ask) => ask.work_key === event.work_key && ask.from_session === event.from_session);
-			if (owned.length === 0 && outbound.length === 0) return { ok: false, error: "release: no owned claim or outbound ask on that work_key" };
+			const collaboration = state.collaboration ?? emptyCollaboration();
+			const ownsTask = collaboration.tasks.some((task) => task.created.work_key === event.work_key && !task.finished && !task.stale
+				&& (task.taken?.from_session ?? task.created.from_session) === event.from_session);
+			if (owned.length === 0 && outbound.length === 0 && !ownsTask) return { ok: false, error: "release: no owned claim or outbound ask on that work_key" };
 			const claims = state.claims.filter((claim) => !(claim.work_key === event.work_key && claim.from_session === event.from_session));
 			const asks = state.asks.filter((ask) => !(ask.work_key === event.work_key && ask.from_session === event.from_session));
-			return { ok: true, state: remember({ ...state, claims, asks }, event.msg_id) };
+			return { ok: true, state: remember({ ...state, claims, asks, collaboration: releaseCollaboration(collaboration, event.from_session, event.work_key, Date.parse(event.ts)) }, event.msg_id) };
+		}
+		case "progress": {
+			const applied = applyCollaborationEvent(state.collaboration ?? emptyCollaboration(), event);
+			return applied.ok ? { ok: true, state: remember({ ...state, collaboration: applied.state }, event.msg_id) } : applied;
 		}
-		case "progress": return { ok: true, state: remember(state, event.msg_id) };
 	}
 }
 
@@ -154,6 +186,7 @@ interface LedgerSnapshot {
 	answers: LedgerAnswer[];
 	ask_ids: string[];
 	seen: string[];
+	collaboration?: CollaborationState;
 }
 
 function token(value: unknown): value is string {
@@ -216,7 +249,15 @@ function parseSnapshot(raw: unknown): LedgerState | undefined {
 	}
 	const requiredAskIds = new Set(state.askIds);
 	if (![...requiredAskIds].every((askId) => snapshot.ask_ids!.includes(askId))) return undefined;
-	return { ...state, askIds: [...snapshot.ask_ids], seen: [...snapshot.seen] };
+	const collaboration = snapshot.collaboration === undefined ? emptyCollaboration() : parseCollaboration(snapshot.collaboration);
+	if (!collaboration) return undefined;
+	for (const task of collaboration.tasks) {
+		if (collaborationStatus(task) !== "taken" || !task.created.write_set.length) continue;
+		const claim = state.claims.find((candidate) => candidate.msg_id === task.taken?.msg_id);
+		if (!claim || claim.from_session !== task.taken?.from_session || claim.work_key !== task.created.work_key
+			|| JSON.stringify(claim.write_set) !== JSON.stringify(task.created.write_set)) return undefined;
+	}
+	return { ...state, collaboration, askIds: [...snapshot.ask_ids], seen: [...snapshot.seen] };
 }
 
 function snapshotOf(state: LedgerState): LedgerSnapshot {
@@ -227,6 +268,7 @@ function snapshotOf(state: LedgerState): LedgerSnapshot {
 		answers: state.answers,
 		ask_ids: state.askIds,
 		seen: state.seen,
+		collaboration: state.collaboration ?? emptyCollaboration(),
 	};
 }
 
@@ -246,6 +288,8 @@ export function parseLedger(text: string): LedgerState {
 			state = restored;
 			continue;
 		}
+		if (raw && typeof raw === "object" && typeof (raw as { kind?: unknown }).kind === "string"
+			&& (raw as { kind: string }).kind.startsWith("ledger_snapshot_")) throw new Error("unsupported ledger snapshot version");
 		if (!isSemanticFrame(raw)) continue;
 		const result = applyLedgerEvent(state, raw);
 		if (result.ok) state = result.state;
@@ -276,7 +320,7 @@ export function pruneLedger(state: LedgerState, options: LedgerPruneOptions): Le
 	const asks = state.asks.filter((ask) => options.liveSessions.has(ask.from_session) && options.liveSessions.has(ask.to_session));
 	const answers = state.answers.filter((answer) => isFresh(answer.ts, now, ttlMs)).slice(-LEDGER_LIMITS.maxResults);
 	const askIds = [...new Set([...asks.map((ask) => ask.ask_id), ...answers.map((answer) => answer.ask_id)])];
-	return { ...state, claims, asks, answers, askIds };
+	return { ...state, claims, asks, answers, askIds, collaboration: pruneCollaboration(state.collaboration ?? emptyCollaboration(), now, ttlMs, (session) => options.liveSessions.has(session)) };
 }
 
 /** The pending asks a prune dropped (a party left the pool) — the ids a waiter must be woken for. */
@@ -565,6 +609,8 @@ export function appendLedgerEvent(path: string, event: LedgerEvent): void {
 export interface LedgerCommitOptions {
 	/** Applied under the same transaction lock before validating the new event. */
 	prune?: LedgerPruneOptions;
+	/** Authoritative write admission, evaluated against the locked task definition (not a preflight read). */
+	canClaim?: boolean;
 	/** Test/operations override; defaults to half the maximum journal size. */
 	compactAtBytes?: number;
 	/** Fault-injection seam for short-write and Windows replacement regression tests. */
@@ -578,7 +624,8 @@ export interface LedgerFileIO {
 
 function pruningChanged(before: LedgerState, after: LedgerState): boolean {
 	return before.claims.length !== after.claims.length || before.asks.length !== after.asks.length
-		|| before.answers.length !== after.answers.length || before.askIds.length !== after.askIds.length;
+		|| before.answers.length !== after.answers.length || before.askIds.length !== after.askIds.length
+		|| JSON.stringify(before.collaboration) !== JSON.stringify(after.collaboration);
 }
 
 export function commitLedgerEvent(path: string, event: LedgerEvent, options: LedgerCommitOptions = {}): ApplyResult {
@@ -588,6 +635,9 @@ export function commitLedgerEvent(path: string, event: LedgerEvent, options: Led
 		const sizeBeforeRecovery = recoverIncompleteTrailingRecordLocked(path);
 		const loaded = loadLedger(path);
 		const pruned = options.prune ? pruneLedger(loaded, options.prune) : loaded;
+		const writes = event.kind === "claim" || event.kind === "task_create" ? event.write_set.length > 0
+			: event.kind === "task_take" && (pruned.collaboration?.tasks.find((task) => task.created.work_key === event.work_key)?.created.write_set.length ?? 0) > 0;
+		if (options.canClaim === false && writes) return { ok: false, error: "this session cannot claim write paths in the selected scope" };
 		const result = applyLedgerEvent(pruned, event);
 		const compactAt = Number.isFinite(options.compactAtBytes) && options.compactAtBytes !== undefined
 			? Math.max(1, Math.floor(options.compactAtBytes)) : Math.floor(LEDGER_LIMITS.maxBytes / 2);

package/src/exocom/plane.ts

@@ -33,6 +33,7 @@ import { createFrameReader, encodeFrame } from "../bus/broker/framing.ts";
 import { frameSigningPayload, isExocomFrame, isSemanticFrame, nextHops, parseExocomArtifactDescriptor, truncateForInject, type AgentCard, type ExocomAck, type ExocomArtifactDescriptor, type ExocomBye, type ExocomFrame, type ExocomMessage, type ExocomNack, type ExocomSemanticFrame } from "./envelope.ts";
 import { EXOCOM } from "./limits.ts";
 import { exocomRoot } from "./paths.ts";
+import { normalizeExocomProfile, type ExocomProfile } from "./profile.ts";
 import { isAlive, normalizePeerName, prune, readAll, removeEntryIfMatches, writeEntry, type RegistryEntry, type RegistryOwnership } from "./registry.ts";
 
 export interface ExocomIdentity {
@@ -398,6 +399,9 @@ export class ExocomPlane {
 	private server: net.Server | undefined;
 	private readonly unlinkEndpoint: () => void;
 	private endpointOwned = false;
+	private profile: ExocomProfile | undefined;
+	/** Last successfully published metadata, so editing a profile cannot restore startup labels. */
+	private presence: RegistryEntry | undefined;
 	/** Ownership of the registry entry successfully written by this plane.  A plane
 	 * may share a session_id with a replacement, so session_id alone is not enough
 	 * to clean up safely. */
@@ -443,6 +447,17 @@ export class ExocomPlane {
 		return normalizePeerName(this.deps.identity.name);
 	}
 
+	/** The plane owns this transient, optional self-report for its live session. */
+	getProfile(): ExocomProfile | undefined {
+		return this.profile ? { ...this.profile, capabilities: [...this.profile.capabilities] } : undefined;
+	}
+
+	/** Update the live registry immediately; `undefined` withdraws the entire self-report. */
+	setProfile(profile: ExocomProfile | undefined): void {
+		this.profile = profile === undefined ? undefined : normalizeExocomProfile(profile);
+		if (this.registeredOwnership) this.heartbeat({ ...(this.presence ?? this.buildEntry()), heartbeat_at: new Date(this.now()).toISOString() });
+	}
+
 	/** Messages this instance has successfully `send()`'d TO the given peer (ack settled), keyed by
 	 *  the peer's session_id — 0 for a peer never sent to. The plane is the SINGLE source of these
 	 *  counters — the widget reads them, it never keeps its own. */
@@ -480,6 +495,7 @@ export class ExocomPlane {
 			prune(agentDir, hash, { now: this.now(), staleMs: EXOCOM.STALE_AFTER_MS });
 			const entry = this.buildEntry();
 			writeEntry(agentDir, hash, entry);
+			this.presence = entry;
 			this.registeredOwnership = {
 				session_id: entry.session_id,
 				endpoint: entry.endpoint,
@@ -524,6 +540,7 @@ export class ExocomPlane {
 				workspace_code: identity.workspace.code,
 				workspace_label: identity.workspace.label,
 			} : {}),
+			...(this.profile ? { profile: this.getProfile()! } : {}),
 		};
 	}
 
@@ -535,8 +552,15 @@ export class ExocomPlane {
 	 *  key exists only in this process. `session_id` is ours by construction, never the caller's. */
 	heartbeat(entry: Omit<RegistryEntry, "public_key">): void {
 		const { agentDir, hash, identity } = this.deps;
-		const owned = { ...entry, session_id: identity.session_id, public_key: this.publicKey };
+		const { profile: _callerProfile, ...entryWithoutProfile } = entry;
+		const owned = {
+			...entryWithoutProfile,
+			session_id: identity.session_id,
+			public_key: this.publicKey,
+			...(this.profile ? { profile: this.getProfile()! } : {}),
+		};
 		writeEntry(agentDir, hash, owned);
+		this.presence = owned;
 		this.registeredOwnership = { session_id: owned.session_id, endpoint: owned.endpoint, public_key: owned.public_key };
 	}
 
@@ -864,6 +888,11 @@ export class ExocomPlane {
 					return;
 				}
 				case "claim":
+				case "task_create":
+				case "task_take":
+				case "task_finish":
+				case "offer":
+				case "publish":
 				case "ask":
 				case "answer":
 				case "progress":
@@ -1112,5 +1141,7 @@ export class ExocomPlane {
 		// spill. In a scope where Exocom is never enabled again, that is never: sweeping on the
 		// way out bounds the retention without touching anything still inside its TTL.
 		this.cleanupArtifacts();
+		this.profile = undefined;
+		this.presence = undefined;
 	}
 }

package/src/exocom/profile.ts

@@ -0,0 +1,40 @@
+/** Self-reported presence only; these fields carry no identity or authorization. */
+export interface ExocomProfile {
+	capabilities: readonly string[];
+	availability?: "available" | "busy" | "away";
+}
+
+const UNSAFE_PROFILE_TEXT = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200b-\u200f\u202a-\u202e\u2060-\u206f<>]/g;
+const AVAILABILITIES = new Set(["available", "busy", "away"]);
+
+function normalizeCapability(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const clean = Array.from(value.normalize("NFKC").replace(UNSAFE_PROFILE_TEXT, " ").replace(/\s+/g, " ").trim())
+		.slice(0, 48).join("");
+	return clean || undefined;
+}
+
+/** Normalize untrusted registry or tool data into the bounded, display-safe profile contract. */
+export function normalizeExocomProfile(value: unknown): ExocomProfile | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	const capabilities: string[] = [];
+	const seen = new Set<string>();
+	if (Array.isArray(input.capabilities)) {
+		for (const value of input.capabilities) {
+			const capability = normalizeCapability(value);
+			if (!capability || seen.has(capability.toLowerCase())) continue;
+			seen.add(capability.toLowerCase());
+			capabilities.push(capability);
+			if (capabilities.length === 8) break;
+		}
+	}
+	const availability = typeof input.availability === "string" && AVAILABILITIES.has(input.availability)
+		? input.availability as ExocomProfile["availability"]
+		: undefined;
+	if (capabilities.length === 0 && availability === undefined) return undefined;
+	return {
+		capabilities,
+		...(availability ? { availability } : {}),
+	};
+}

package/src/exocom/registry.ts

@@ -2,6 +2,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { agentsDir, registryPath } from "./paths.ts";
+import { normalizeExocomProfile, type ExocomProfile } from "./profile.ts";
 
 export interface RegistryEntry {
 	/** `name` is display-only — NOT unique, NOT a lookup key. The registry FILE is keyed by
@@ -16,6 +17,8 @@ export interface RegistryEntry {
 	workspace_id?: string;
 	workspace_code?: string;
 	workspace_label?: string;
+	/** Optional self-reported presence; it is descriptive and never grants capability. */
+	profile?: ExocomProfile;
 }
 
 /** The fields that prove which process owns a registry slot.  `session_id` is the
@@ -57,6 +60,7 @@ export function normalizeRegistryEntry(value: unknown): RegistryEntry | undefine
 	const contextPct = typeof e.context_pct === "number" && Number.isFinite(e.context_pct) ? Math.max(0, Math.min(100, e.context_pct)) : 0;
 	const inbox = typeof e.inbox === "number" && Number.isFinite(e.inbox) ? Math.max(0, Math.min(1_000_000, Math.floor(e.inbox))) : 0;
 	const publicKey = opaqueString(e.public_key, 256);
+	const profile = normalizeExocomProfile(e.profile);
 	const hasWorkspaceMetadata = e.workspace_id !== undefined || e.workspace_code !== undefined || e.workspace_label !== undefined;
 	let workspace: Pick<RegistryEntry, "workspace_id" | "workspace_code" | "workspace_label"> = {};
 	if (hasWorkspaceMetadata) {
@@ -83,6 +87,7 @@ export function normalizeRegistryEntry(value: unknown): RegistryEntry | undefine
 		inbox,
 		heartbeat_at: new Date(Date.parse(heartbeatAt)).toISOString(),
 		...(publicKey && /^[A-Za-z0-9+/]+={0,2}$/.test(publicKey) ? { public_key: publicKey } : {}),
+		...(profile ? { profile } : {}),
 		...workspace,
 	};
 }

package/src/exocom/status.ts

@@ -20,6 +20,7 @@ import type { LedgerAsk, LedgerClaim, LedgerState } from "./ledger.ts";
 import { formatDuration } from "../core/time.ts";
 import { fencePeer } from "../core/fence.ts";
 import { renderWriteSet, untrusted, UNTRUSTED_MAX } from "./untrusted.ts";
+import { collaborationOfferStatus, collaborationStatus } from "./collaboration.ts";
 
 /** No section may hand the model an unbounded ledger — a long-lived scope with many claims stays
  *  one bounded read, same discipline as the pending-ask block and the peer roster. */
@@ -72,8 +73,12 @@ export function formatLedgerStatus(
 	const peerClaims = state.claims.filter((claim) => claim.from_session !== self).sort(byTsAscending);
 	const asksForYou = state.asks.filter((ask) => ask.to_session === self).sort(byTsAscending);
 	const yourAsks = state.asks.filter((ask) => ask.from_session === self).sort(byTsAscending);
+	const collaboration = state.collaboration;
+	const tasks = collaboration?.tasks ?? [];
+	const offers = collaboration?.offers ?? [];
+	const evidence = collaboration?.evidence ?? [];
 
-	if (ownClaims.length === 0 && peerClaims.length === 0 && asksForYou.length === 0 && yourAsks.length === 0) {
+	if (ownClaims.length === 0 && peerClaims.length === 0 && asksForYou.length === 0 && yourAsks.length === 0 && tasks.length === 0 && offers.length === 0 && evidence.length === 0) {
 		return "nothing claimed or pending";
 	}
 
@@ -82,5 +87,10 @@ export function formatLedgerStatus(
 		section("peer claims", peerClaims.map((claim) => claimRow(claim, self, labelFor, now)), { fence: true }),
 		section("asks waiting for you", asksForYou.map((ask) => askRow(ask, ask.from_session, labelFor, now)), { fence: true }),
 		section("your open asks", yourAsks.map((ask) => askRow(ask, ask.to_session, labelFor, now))),
+		...(tasks.length ? [section("shared tasks (exocom_task list for detail)", tasks.map((task) =>
+			`${task.created.work_key} · ${collaborationStatus(task)} · ${resolveLabel(task.taken?.from_session ?? task.created.from_session, labelFor)}`), { fence: true })] : []),
+		...(offers.length ? [section("optional invitations", offers.map((offer) =>
+			`${offer.offer_id} · task ${offer.work_key} · ${collaborationOfferStatus(offer, tasks, now)} · ${offer.to_session ? resolveLabel(offer.to_session, labelFor) : "open invitation"}`), { fence: true })] : []),
+		...(evidence.length ? [`${evidence.length} retained evidence excerpt(s); discover with exocom_publish { action: "read", work_key: "<task>" }.`] : []),
 	].join("\n\n");
 }

package/src/exocom/write-guard.ts

@@ -64,6 +64,13 @@ export function writeWarningReason(path: string, claim: LedgerClaim, label: stri
 	return `exocom: ${path} is inside ${who}'s open claim — coordinate with exocom_ask or claim it; call the tool again to proceed (this warning shows once per path)\n${fencePeer(`${slice}: ${writeSet}`)}`;
 }
 
+/** The operator-TOAST variant of the same warning: its single authoritative line, sanitized and
+ *  bounded. The fenced peer-authored detail below the newline stays model-facing (the tool
+ *  result); a toast is one line and never carries the claim block. */
+export function writeWarningToastReason(path: string, claim: LedgerClaim, label: string): string {
+	return untrusted(writeWarningReason(path, claim, label).split("\n")[0] ?? "", 300);
+}
+
 /** Warn-once memory for the write guard. A bare unbounded set would grow for the life of the
  *  install on a long session with many distinct claim+path pairs; caps at `maxEntries` (like the
  *  sibling `SeenMessages` in guards.ts) and drops the oldest insertion first once exceeded. */

package/src/extension/broker-host.ts

@@ -2,7 +2,8 @@
  * Supervisor-side broker lifecycle (spec B1-B7): the ONE cross-process host every child-engine
  * leg connects to. Started lazily on the first child-engine build; a failed bind is reported to
  * the user ONCE, children built while it is failed spawn without a bus endpoint (so they never
- * burn the connect backoff against a dead socket), and the next build retries.
+ * burn the connect backoff against a dead socket), and the next build retries. Result readers
+ * use the separate strict awaited preflight on this SAME host, never bus-less degradation.
  */
 
 import { mkdirSync } from "node:fs";
@@ -11,6 +12,7 @@ import { dirname } from "node:path";
 import type { EngineAdapterBroker } from "../engine/adapter.ts";
 import { type BrokerHost, startBrokerHost } from "../bus/broker/host.ts";
 import type { InProcessBus } from "../bus/inproc.ts";
+import { RESULT_READ_TIMEOUT_MS, type PreparedResultReader, type ScopedReader } from "../bus/result-reader.ts";
 
 export interface SupervisorBrokerDeps {
 	bus: InProcessBus;
@@ -49,6 +51,8 @@ export class SupervisorBroker {
 	private readonly expected = new Set<string>();
 	private readonly preHostSteers = new Map<string, string[]>();
 	private readonly deps: SupervisorBrokerDeps;
+	private generation = 0;
+	private readonly preparingReaders = new Set<() => void>();
 
 	constructor(deps: SupervisorBrokerDeps) {
 		this.deps = deps;
@@ -82,6 +86,7 @@ export class SupervisorBroker {
 			}
 		}
 		const start = this.deps.startHost ?? startBrokerHost;
+		const generation = this.generation;
 		this.promise = start({
 			bus: this.deps.bus,
 			supervisorHandle: this.deps.supervisorHandle,
@@ -90,6 +95,7 @@ export class SupervisorBroker {
 		});
 		this.promise.then(
 			(h) => {
+				if (generation !== this.generation) return; // close() owns the late host's teardown
 				this.hostRef = h;
 				this.lastError = undefined;
 				this.warned = false;
@@ -98,6 +104,7 @@ export class SupervisorBroker {
 				this.preHostSteers.clear();
 			},
 			(err) => {
+				if (generation !== this.generation) return;
 				this.promise = undefined; // a later build retries
 				this.lastError = err instanceof Error ? err.message : String(err);
 				const dropped = [...this.preHostSteers.values()].reduce((n, texts) => n + texts.length, 0);
@@ -112,6 +119,46 @@ export class SupervisorBroker {
 		);
 	}
 
+	/** Strict reader preflight, unlike ordinary bus-less degradation. Call ensure(endpoint)
+	 * first, then await this BEFORE adapter registration/spawn. The owner must revoke on
+	 * settlement/spawn failure and close this broker when the owning session changes. */
+	async prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader> {
+		const generation = this.generation;
+		let revoked = false;
+		const revoke = (): void => {
+			if (revoked) return;
+			revoked = true;
+			try { reader.revoke(); } catch { /* fixed diagnostic, even if cleanup throws */ }
+		};
+		const fail = (): Error => new Error("Result reader preparation failed.");
+		const hostPromise = this.promise;
+		if (!hostPromise || signal?.aborted) { revoke(); throw fail(); }
+		return new Promise<PreparedResultReader>((resolve, reject) => {
+			let settled = false;
+			const cleanup = (): void => {
+				settled = true;
+				clearTimeout(timer);
+				this.preparingReaders.delete(cancel);
+				signal?.removeEventListener("abort", cancel);
+			};
+			const cancel = (): void => {
+				if (settled) return;
+				revoke(); cleanup(); reject(fail());
+			};
+			const timer = setTimeout(cancel, RESULT_READ_TIMEOUT_MS);
+			timer.unref?.();
+			this.preparingReaders.add(cancel);
+			signal?.addEventListener("abort", cancel, { once: true });
+			void hostPromise.then(async (host) => {
+				if (settled) return;
+				const grant = await host.prepareResultReader(handle, { read: (request, s) => reader.read(request, s), revoke }, signal);
+				if (settled || generation !== this.generation || signal?.aborted) { grant.revoke(); cancel(); return; }
+				cleanup();
+				resolve(grant);
+			}).catch(cancel);
+		});
+	}
+
 	/** The adapter-facing deps, or undefined while the last start failed (children spawn bus-less). */
 	adapterDeps(endpoint: string): EngineAdapterBroker | undefined {
 		const failedBefore = this.state() === "failed";
@@ -141,6 +188,7 @@ export class SupervisorBroker {
 				return true;
 			},
 			hasPendingAskFrom: (handle) => this.deps.bus.hasPendingAskFrom(handle),
+			prepareResultReader: (handle, reader, signal) => this.prepareResultReader(handle, reader, signal),
 		};
 	}
 
@@ -164,18 +212,22 @@ export class SupervisorBroker {
 	}
 
 	async close(): Promise<void> {
-		if (this.promise) {
-			try {
-				const h = await this.promise;
-				await h.close();
-			} catch {
-				/* best-effort — never block shutdown on a broker teardown error */
-			}
-		}
+		this.generation++;
+		for (const cancel of this.preparingReaders) cancel();
+		const host = this.hostRef;
+		const pending = this.promise;
 		this.hostRef = undefined;
 		this.promise = undefined;
+		this.lastError = undefined;
 		this.peers.clear();
 		this.expected.clear();
 		this.preHostSteers.clear();
+		try {
+			// Invoke immediately: bound readers revoke before the first await.
+			if (host) await host.close();
+			else if (pending) await (await pending).close();
+		} catch {
+			/* best-effort — never block shutdown on a broker teardown error */
+		}
 	}
 }

package/src/extension/engine.ts

@@ -8,6 +8,7 @@ import { type ContractDef, DEFAULT_CONTRACT, installedContractNames } from "../c
 import type { RunLimits } from "../core/capabilities.ts";
 import type { PiPersonaConfig } from "../core/config.ts";
 import { isThinkingLevel } from "../core/types.ts";
+import type { ModelCostMetadata } from "../core/model-tier.ts";
 import { personaModels, type PersonaConfigStore } from "../persona/config-store.ts";
 import { participantKey } from "../persona/model-participants.ts";
 import type { PersonaController, PersonaHost } from "../persona/controller.ts";
@@ -20,6 +21,7 @@ import { emptyUsage, type ProgressSnapshot } from "../engine/stream.ts";
 import type { AgentRunSpec, StrategyEngine } from "../orchestration/sdk.ts";
 import type { AgentResult } from "../orchestration/types.ts";
 import type { InProcessBus } from "../bus/inproc.ts";
+import type { ResultArchiveView } from "../results/retrieval.ts";
 
 export interface EngineFactories {
 	makeEngine: typeof makeEngine;
@@ -44,6 +46,10 @@ export interface BuildEngineDeps {
 	runLimits: RunLimits;
 	bus: InProcessBus;
 	supervisorHandle: string;
+	/** The live terminal-result archive (a GETTER: the owning session can change across runs).
+	 *  Feeds both engines' reference-handoff preflight + scoped `read_result` readers.
+	 *  Absent ⇒ reference-handoff legs fail closed on both engines (no archive to page). */
+	resultArchive?: () => ResultArchiveView | undefined;
 	/** Breadcrumb for a provider reroute (toast + log); absent ⇒ silent, as before. */
 	onFallback?: (info: { from: string; to: string; agent: string }) => void;
 	/** Injected git runner for the non-worktree files-changed report (tests only); defaults to
@@ -68,7 +74,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 		const {
 			agents, contractDefs, controller, host, config, personaConfigs, lastCtx, workerSpineText,
 			engineFactories, makeBrokerDeps, userAgentDir, childPiSettingsEnv, runLimits: RUN_LIMITS,
-			bus, supervisorHandle: SUPERVISOR, onFallback,
+			bus, supervisorHandle: SUPERVISOR, onFallback, resultArchive,
 		} = d();
 			const resolveAgent = (n: string): AgentConfig | undefined => agents.find((a) => a.name === n);
 			// A named contract file (contracts/<name>.contract.json) wins; "default" is the built-in.
@@ -110,7 +116,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			const getBrokerDeps = (): EngineAdapterBroker | undefined => {
 				if (!brokerDepsBuilt) {
 					brokerDepsBuilt = true;
-					const sessionId = (lastCtx as { sessionManager?: { getSessionId?: () => string } } | undefined)?.sessionManager?.getSessionId?.();
+					const sessionId = lastCtx?.sessionManager.getSessionId();
 					if (config.broker && lastCtx && sessionId) brokerDepsMemo = makeBrokerDeps(lastCtx);
 				}
 				return brokerDepsMemo;
@@ -136,6 +142,9 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				if (onProgress) deps.childOptions.onProgress = onProgress;
 				const brokerDeps = getBrokerDeps();
 				if (brokerDeps) deps.broker = brokerDeps;
+				// Reference-handoff legs page the owning session's terminal archive (strict preflight
+				// + scoped reader); the getter is read at LEG time so a mid-run session switch is seen.
+				if (resultArchive !== undefined) deps.resultArchive = resultArchive;
 				// Peer messaging obeys the persona's bus capability, and blocking asks are honoured
 				// only for async runs — same guards as the inproc engine below (spec B7 / §4.9).
 				const caps = controller.capabilities;
@@ -163,6 +172,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				// can't answer, so blocking there would deadlock; the tool downgrades to one-way).
 				ideps.bus = bus;
 				ideps.supervisorHandle = SUPERVISOR;
+				if (resultArchive !== undefined) ideps.resultArchive = resultArchive;
 				if (controller.activePersona?.coaching) ideps.coaching = true;
 				// Peer messaging obeys the persona's bus capability (canUseBus; Task: sibling peer comm).
 				const caps = controller.capabilities;
@@ -186,6 +196,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				if (onProgress) deps.childOptions.onProgress = onProgress;
 				const brokerDeps = getBrokerDeps();
 				if (brokerDeps) deps.broker = brokerDeps;
+				if (resultArchive !== undefined) deps.resultArchive = resultArchive;
 				// Peer messaging obeys the persona's bus capability, and blocking asks are honoured
 				// only for async runs — same guards as the inproc engine above (spec B7 / §4.9).
 				const caps = controller.capabilities;
@@ -247,9 +258,9 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 						const preflight = await worktreePreflight(root, defaultGitExec);
 						if (!preflight.ok) return isolatedWorktreeFailure(spec, preflight.error);
 						try {
-							return await withWorktree(root, defaultGitExec, async (dir) => {
+							return await withWorktree(root, defaultGitExec, async (dir, baseCommit) => {
 								const result = await childEngineAt(dir).run({ ...spec, isolation: "none" }, perProgress, perSignal, perSteer);
-								const artifact = await captureWorktreeArtifact(dir, defaultGitExec);
+								const artifact = await captureWorktreeArtifact(dir, baseCommit, defaultGitExec);
 								const hasOutputArtifact = hasUnifiedDiff(result.output);
 								if (!result.ok) {
 									return artifact.ok && artifact.diff.trim().length > 0
@@ -310,33 +321,48 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 	}
 }
 
-// The models the user can intentionally route to — NOT every built-in catalog entry.
-// `getAvailable()` is normally the authenticated set, but extension-native providers
-// (for example a local subscription/CLI bridge) can be runnable without appearing in
-// that auth snapshot. Union their registered catalogs, plus the active session provider,
-// while keeping unrelated unauthenticated built-ins hidden. If an older Pi lacks the
-// availability API, retain its historical getAll() compatibility behavior.
-export function configuredModels(ctx: ExtensionContext): Array<{ provider: string; id: string }> {
+// The host's model-level availability snapshot, plus the exact active model. A provider's
+// credentials do not grant every model in its catalog. Extension-native bridges can be
+// absent from an auth snapshot: restore only their explicit registered model lists in that
+// case, never every inherited model under their provider id.
+export function configuredModels(ctx: ExtensionContext): ModelCostMetadata[] {
 	const reg = ctx.modelRegistry;
 	const all = reg.getAll();
-	let available: typeof all;
-	try {
-		available = reg.getAvailable();
-	} catch {
-		return all.map((m) => ({ provider: m.provider, id: m.id }));
-	}
-	const trustedProviders = new Set<string>();
-	if (ctx.model?.provider) trustedProviders.add(ctx.model.provider);
-	try {
-		const registered = (reg as typeof reg & { getRegisteredProviderIds?: () => string[] }).getRegisteredProviderIds?.() ?? [];
-		for (const provider of registered) trustedProviders.add(provider);
-	} catch {
-		/* a third-party/older registry facade may not expose extension provider ids */
-	}
+	const available = reg.getAvailable();
 	const byRef = new Map(available.map((m) => [`${m.provider}\0${m.id}`, m]));
+	if (ctx.model) byRef.set(`${ctx.model.provider}\0${ctx.model.id}`, ctx.model);
+	const availableProviders = new Set(available.map((m) => m.provider));
+	const declaredRefs = new Set<string>();
+	const registered = reg.getRegisteredProviderIds();
+	for (const provider of registered) {
+		// A populated snapshot can intentionally exclude individual models for this credential.
+		if (availableProviders.has(provider)) continue;
+		let native: ReturnType<typeof reg.getRegisteredNativeProvider>;
+		try {
+			native = reg.getRegisteredNativeProvider(provider);
+			// An empty credential-filtered list is authoritative too; it need not be a stale snapshot.
+			if (reg.getProvider(provider)?.filterModels || native?.filterModels) continue;
+		} catch { continue; }
+		try {
+			const models = reg.getRegisteredProviderConfig(provider)?.models;
+			if (Array.isArray(models)) {
+				for (const model of models) {
+					if ((model.type === undefined || model.type === "chat") && typeof model.id === "string") declaredRefs.add(`${provider}\0${model.id}`);
+				}
+			}
+		} catch { /* one broken extension's metadata must not hide other providers */ }
+		try {
+			const models = native?.getModels();
+			if (Array.isArray(models)) {
+				for (const model of models) {
+					if (model.provider === provider && typeof model.id === "string") declaredRefs.add(`${provider}\0${model.id}`);
+				}
+			}
+		} catch { /* a native catalog may be temporarily unavailable */ }
+	}
 	for (const model of all) {
-		if (trustedProviders.has(model.provider)) byRef.set(`${model.provider}\0${model.id}`, model);
+		const ref = `${model.provider}\0${model.id}`;
+		if (declaredRefs.has(ref)) byRef.set(ref, model);
 	}
-	const list = [...byRef.values()];
-	return list.map((m) => ({ provider: m.provider, id: m.id }));
+	return [...byRef.values()];
 }