@aeondave/pi-persona 1.17.3 → 1.17.5

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/companion.ts

@@ -0,0 +1,38 @@
+/** Framework adapter for loaded companion presence and current-owner activity contributions. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ACTIVITY_EVENT, COMPANION_EVENT, companionPresence, parseCompanionActivity, type CompanionRole } from "../core/companion.ts";
+import { ActivityRows } from "../ui/activity-rows.ts";
+import type { AgentTree } from "../ui/agent-tree.ts";
+
+/** Registered before worker/disable guards; the host revokes subscriptions when the extension unloads. */
+export function installCompanionPresence(pi: Pick<ExtensionAPI, "events">, role: CompanionRole): void {
+	pi.events.on(COMPANION_EVENT, (request: unknown) => {
+		if (!request || typeof request !== "object" || Array.isArray(request)) return;
+		const query = request as Record<string, unknown>;
+		if (query.version !== 1 || typeof query.respond !== "function" || Reflect.ownKeys(query).some((key) => key !== "version" && key !== "respond")) return;
+		try { query.respond(companionPresence(role)); } catch { /* a companion's callback cannot disrupt Persona */ }
+	});
+}
+
+export interface ActivityIngress { start(ctx: ExtensionContext): void; stop(removeRows?: boolean): void }
+export function installActivityIngress(pi: Pick<ExtensionAPI, "events">, tree: AgentTree, now: () => number = Date.now): ActivityIngress {
+	const rows = new ActivityRows();
+	let owner: { manager: ExtensionContext["sessionManager"]; sessionId: string; file: string | undefined } | undefined;
+	const stop = (removeRows = true): void => {
+		owner = undefined;
+		const ids = rows.clear();
+		if (removeRows) for (const id of ids) tree.remove(id);
+	};
+	pi.events.on(ACTIVITY_EVENT, (value: unknown) => {
+		const event = parseCompanionActivity(value);
+		if (!event || !owner || event.sessionId !== owner.sessionId) return;
+		try {
+			if (owner.manager.getSessionId() !== owner.sessionId || owner.manager.getSessionFile() !== owner.file) return;
+			const change = rows.accept(event, now());
+			if (!change) return;
+			for (const id of change.removed) tree.remove(id);
+			tree.add(change.node);
+		} catch { /* malformed/local UI contributions never affect memory or orchestration */ }
+	});
+	return { start(ctx) { stop(); owner = { manager: ctx.sessionManager, sessionId: ctx.sessionManager.getSessionId(), file: ctx.sessionManager.getSessionFile() }; }, stop };
+}

package/src/extension/engine.ts

@@ -21,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;
@@ -45,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
@@ -61,6 +66,10 @@ export type BuildEngine = (
 		 *  `false`: there the SDK's own main-model recovery is the ONE reroute, so an arbitrary
 		 *  provider must not be substituted underneath a member the user pinned. */
 		providerFallback?: boolean;
+		/** Trusted companion worker definition, scoped to this engine build; never installed/discovered. */
+		agentOverride?: AgentConfig;
+		/** Internal tool-less maintenance may revoke communication even for a coaching persona. */
+		canUseBus?: false;
 	},
 ) => StrategyEngine;
 
@@ -69,9 +78,9 @@ 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);
+			const resolveAgent = (n: string): AgentConfig | undefined => engOpts?.agentOverride?.name === n ? engOpts.agentOverride : agents.find((a) => a.name === n);
 			// A named contract file (contracts/<name>.contract.json) wins; "default" is the built-in.
 			const contracts = (n: string): ContractDef | undefined => contractDefs[n] ?? (n === "default" ? DEFAULT_CONTRACT : undefined);
 			const contractNames = (): string[] => installedContractNames(contractDefs);
@@ -111,7 +120,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;
@@ -120,7 +129,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			// A child-process engine pinned to a specific cwd — the seam worktree isolation runs
 			// through (a worktree needs its own working dir, i.e. a separate process).
 			const childEngineAt = (cwd: string): StrategyEngine => {
-				const deps: EngineAdapterDeps = { resolveAgent, contracts, modelFor, childThinking, cwd };
+				const deps: EngineAdapterDeps = { resolveAgent, contracts, modelFor, childThinking, cwd, memoryPersona: persona ?? null };
 				deps.listAgents = () => agents.map((a) => a.name);
 				deps.listContracts = contractNames;
 				if (legSpine) deps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
@@ -137,10 +146,14 @@ 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;
-				if (caps) deps.canUseBus = caps.canUseBus;
+				if (engOpts?.canUseBus === false) deps.canUseBus = false;
+				else if (caps) deps.canUseBus = caps.canUseBus;
 				if (engOpts?.async) deps.allowBlocking = true;
 				return engineFactories.makeEngine(deps);
 			};
@@ -149,7 +162,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			let base: StrategyEngine;
 			if (config.engine === "inproc" && lastCtx) {
 				if (process.env.PI_PERSONA_DEBUG) process.stderr.write("[pi-persona] engine=inproc\n");
-				const ideps: InProcessDeps = { resolveAgent, contracts, modelFor, childThinking, modelRegistry: lastCtx.modelRegistry, cwd: lastCtx.cwd, agentDir: userAgentDir() };
+				const ideps: InProcessDeps = { resolveAgent, contracts, modelFor, childThinking, modelRegistry: lastCtx.modelRegistry, cwd: lastCtx.cwd, agentDir: userAgentDir(), memoryPersona: persona ?? null };
 				ideps.listAgents = () => agents.map((a) => a.name);
 				ideps.listContracts = contractNames;
 				if (legSpine) ideps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
@@ -164,15 +177,17 @@ 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;
-				if (caps) ideps.canUseBus = caps.canUseBus;
+				if (engOpts?.canUseBus === false) ideps.canUseBus = false;
+				else if (caps) ideps.canUseBus = caps.canUseBus;
 				if (engOpts?.async) ideps.allowBlocking = true;
 				base = engineFactories.makeInProcessEngine(ideps);
 			} else {
 				if (process.env.PI_PERSONA_DEBUG) process.stderr.write("[pi-persona] engine=child\n");
-				const deps: EngineAdapterDeps = { resolveAgent, contracts, modelFor, childThinking };
+				const deps: EngineAdapterDeps = { resolveAgent, contracts, modelFor, childThinking, memoryPersona: persona ?? null };
 				deps.listAgents = () => agents.map((a) => a.name);
 				deps.listContracts = contractNames;
 				if (legSpine) deps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
@@ -187,10 +202,12 @@ 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;
-				if (caps) deps.canUseBus = caps.canUseBus;
+				if (engOpts?.canUseBus === false) deps.canUseBus = false;
+				else if (caps) deps.canUseBus = caps.canUseBus;
 				if (engOpts?.async) deps.allowBlocking = true;
 				base = engineFactories.makeEngine(deps);
 			}
@@ -248,9 +265,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
@@ -258,7 +275,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 										: result;
 								}
 								if (!artifact.ok) {
-									if (hasOutputArtifact) return result;
+									if (hasOutputArtifact) return prependWorktreeCaptureWarning(result);
 									return isolatedWorktreeFailure(spec, `${artifact.error}; the isolated leg returned success without an exportable diff/artifact`);
 								}
 								if (artifact.diff.trim().length > 0) return appendWorktreeArtifact(result, artifact.diff);
@@ -301,6 +318,11 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 		return appendBlock(result, block);
 	}
 
+	function prependWorktreeCaptureWarning(result: AgentResult): AgentResult {
+		const warning = "⚠ Worktree artifact capture failed; the following patch is worker-provided and was not verified against the worktree state.";
+		return { ...result, output: result.output.trim() ? `${warning}\n\n${result.output}` : warning };
+	}
+
 	/** Append a block to a leg's output, never leading with blank lines when there was nothing to
 	 *  trim — the shape `withChangeReport` and `appendWorktreeArtifact` both need: a leg that
 	 *  produced no text of its own (an early abort/timeout before any streamed output) still gets a
@@ -314,38 +336,27 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 // 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. Older facades without an
-// availability API retain their historical getAll() fallback.
+// 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;
-	}
+	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>();
-	let registered: readonly string[] = [];
-	try {
-		registered = reg.getRegisteredProviderIds?.() ?? [];
-	} catch {
-		/* a third-party/older registry facade may not expose extension provider ids */
-	}
+	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);
+			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;
+			if (reg.getProvider(provider)?.filterModels || native?.filterModels) continue;
 		} catch { continue; }
 		try {
-			const models = reg.getRegisteredProviderConfig?.(provider)?.models;
+			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}`);