@aeondave/pi-persona 1.17.4 → 1.17.5

package/src/bus/peers.ts

@@ -24,7 +24,7 @@ import { Text } from "@earendil-works/pi-tui";
 
 import { compactInlineText } from "../ui/presentation.ts";
 import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
-import type { InProcessBus } from "./inproc.ts";
+import type { ContactTransport } from "./contact-transport.ts";
 
 /** Anti ping-pong budget: after this many sends the tool tells the member to finalize. */
 export const MAX_PEER_SENDS = 20;
@@ -59,7 +59,7 @@ function result(t: string, details: PeerDetails): { content: [{ type: "text"; te
 
 /** Build the child's `contact_peer` tool. Same `defineTool` variance shim as
  *  `makeContactSupervisorTool`, so it slots into `customTools: ToolDefinition[]`. */
-export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps: ContactPeerDeps) {
+export function makeContactPeerTool(bus: Pick<ContactTransport, "send">, selfHandle: string, deps: ContactPeerDeps) {
 	const maxSends = deps.maxSends ?? MAX_PEER_SENDS;
 	let sent = 0;
 	return defineTool({
@@ -74,7 +74,7 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 		].join(" "),
 		promptSnippet: "contact_peer — list your run's sibling agents or send one a one-way note",
 		parameters: PeerParams,
-		async execute(_toolCallId, params: Static<typeof PeerParams>, _signal, _onUpdate, _ctx) {
+		async execute(_toolCallId, params: Static<typeof PeerParams>, signal, _onUpdate, _ctx) {
 			if (params.action === "list") {
 				const peers = await deps.listPeers();
 				return result(
@@ -87,6 +87,7 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 			if (!params.to || params.message === undefined) {
 				return result("contact_peer send needs { to, message } — use `list` for peer handles.", { action: "send", delivered: false });
 			}
+			if (signal?.aborted) return result("Peer message cancelled before delivery.", { action: "send", delivered: false });
 			if (params.message.length > MAX_PEER_MESSAGE_CHARS) {
 				return result(
 					`contact_peer message exceeds the ${MAX_PEER_MESSAGE_CHARS}-character limit; send a smaller note.`,
@@ -102,14 +103,15 @@ export function makeContactPeerTool(bus: InProcessBus, selfHandle: string, deps:
 			sent += 1;
 			// Enforce the run-isolation boundary (previously only convention): a handle that is
 			// not one of THIS run's peers (e.g. "supervisor", or another run's child) never gets
-			// bus.send called at all — same "gone" wording as an actually-finished peer, so the
+			// bus.send called at all — same unavailable wording as an actually-finished peer, so the
 			// tool result gives no signal either way about what exists outside this run's scope.
 			const inScope = (await deps.listPeers()).some((p) => p.handle === params.to);
-			const delivered = inScope && bus.send(selfHandle, params.to, params.message, "progress");
+			const accepted = inScope && !signal?.aborted && await bus.send(selfHandle, params.to, params.message, "progress", signal);
+			const delivered = accepted && !signal?.aborted;
 			return result(
 				delivered
 					? `Sent to ${params.to}.`
-					: `Peer "${params.to}" is gone — it may have already finalized. Proceed with your own judgement.`,
+					: `Delivery to peer "${params.to}" could not be confirmed — it may be unavailable or its inbox full. Proceed with your own judgement.`,
 				{ action: "send", delivered },
 			);
 		},

package/src/core/companion.ts

@@ -0,0 +1,64 @@
+/** Public local companion contracts. These describe loaded capabilities and UI activity, not authority. */
+export const COMPANION_EVENT = "pi-persona:companion:v1";
+export const ACTIVITY_EVENT = "pi-persona:activity:v1";
+export const MEMORY_OWNER_EVENT = "pi-persona:memory-owner:v1";
+export const MEMORY_OWNER_CHANGED_EVENT = "pi-persona:memory-owner-changed:v1";
+export const MEMORY_PERSONA_ENV = "PI_PERSONA_MEMORY_PERSONA";
+
+export interface CompanionMemoryOwner {
+	version: 1;
+	provider: "pi-persona";
+	sessionId: string;
+	ready: boolean;
+	persona: string | null;
+}
+
+/** Spawn-local inheritance only. Absent/invalid is unavailable, never a global-settings fallback. */
+export function inheritedMemoryPersona(raw: string | undefined): { persona: string | null } | undefined {
+	if (raw === undefined || raw.length > 8_192) return undefined;
+	try {
+		const value = JSON.parse(raw) as Record<string, unknown> | null;
+		if (!value || typeof value !== "object" || Array.isArray(value) || value.version !== 1 || Object.keys(value).some((key) => key !== "version" && key !== "persona")) return undefined;
+		if (value.persona !== null && (typeof value.persona !== "string" || !value.persona.trim() || value.persona.length > 1_024 || /[\u0000-\u001f\u007f]/u.test(value.persona))) return undefined;
+		return { persona: value.persona as string | null };
+	} catch { return undefined; }
+}
+
+export type CompanionRole = "supervisor" | "leg" | "disabled";
+export interface CompanionPresence {
+	version: 1;
+	provider: "pi-persona";
+	role: CompanionRole;
+	capabilities: { memory: 1 | false; activity: 1 | false };
+}
+export interface CompanionActivity {
+	version: 1;
+	producerId: "pi-persona-mind";
+	activityId: string;
+	sessionId: string;
+	phase: "inspect" | "stage" | "apply";
+	state: "running" | "staged" | "done" | "failed";
+	target: "project" | "project-long" | "persona" | "shared";
+}
+
+export function companionPresence(role: CompanionRole): CompanionPresence {
+	return { version: 1, provider: "pi-persona", role, capabilities: { memory: role === "disabled" ? false : 1, activity: role === "supervisor" ? 1 : false } };
+}
+
+/** Closed records cannot accidentally export raw memory, model claims, or prompts into the tree. */
+export function parseCompanionActivity(value: unknown): CompanionActivity | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== null && prototype !== Object.prototype) return undefined;
+	const allowed = new Set(["version", "producerId", "activityId", "sessionId", "phase", "state", "target"]);
+	if (Reflect.ownKeys(value).some((key) => typeof key !== "string" || !allowed.has(key))) return undefined;
+	const activity = value as Record<string, unknown>;
+	if (activity.version !== 1 || activity.producerId !== "pi-persona-mind") return undefined;
+	if (typeof activity.activityId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/.test(activity.activityId)) return undefined;
+	if (typeof activity.sessionId !== "string" || activity.sessionId.length < 1 || activity.sessionId.length > 256 || /[\s\u0000-\u001f\u007f]/u.test(activity.sessionId)) return undefined;
+	if (activity.phase !== "inspect" && activity.phase !== "stage" && activity.phase !== "apply") return undefined;
+	if (activity.state !== "running" && activity.state !== "staged" && activity.state !== "done" && activity.state !== "failed") return undefined;
+	if (activity.state === "staged" && activity.phase !== "stage") return undefined;
+	if (activity.target !== "project" && activity.target !== "project-long" && activity.target !== "persona" && activity.target !== "shared") return undefined;
+	return { version: 1, producerId: "pi-persona-mind", activityId: activity.activityId, sessionId: activity.sessionId, phase: activity.phase, state: activity.state, target: activity.target };
+}

package/src/engine/adapter.ts

@@ -13,6 +13,7 @@ import { sanitizeDisplayLabel } from "../core/display-label.ts";
 import { resolveLegThinking } from "../core/leg-thinking.ts";
 import type { ThinkingLevel } from "../core/types.ts";
 import { assignedIdentityPrompt } from "../core/naming.ts";
+import { MEMORY_PERSONA_ENV } from "../core/companion.ts";
 import { roleHint } from "../orchestration/roster.ts";
 import { type AgentProgress, type AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
 import type { AgentResult } from "../orchestration/types.ts";
@@ -54,6 +55,8 @@ export interface EngineAdapterBroker {
 }
 
 export interface EngineAdapterDeps {
+	/** Immutable owning supervisor persona; null explicitly means no persona. */
+	memoryPersona?: string | null;
 	resolveAgent: (name: string) => AgentConfig | undefined;
 	contracts?: (name: string) => ContractDef | undefined;
 	signal?: AbortSignal;
@@ -98,6 +101,7 @@ export interface EngineAdapterDeps {
 }
 
 export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
+	const memoryPersona = deps.memoryPersona;
 	// Per-run contract pinning (I3): an engine instance is created per run, so the first
 	// time a contract is used we pin `name@hash` and reuse that frozen snapshot for the
 	// rest of the run — hot-reloading a contract file can't change an in-flight run.
@@ -188,6 +192,12 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			if (deps.cwd) childSpec.cwd = deps.cwd;
 
 			const childOptions: ChildEngineOptions = { ...deps.childOptions };
+			if (memoryPersona !== undefined || childOptions.env?.[MEMORY_PERSONA_ENV] !== undefined) {
+				const env = { ...childOptions.env };
+				delete env[MEMORY_PERSONA_ENV];
+				if (memoryPersona !== undefined) env[MEMORY_PERSONA_ENV] = JSON.stringify({ version: 1, persona: memoryPersona });
+				childOptions.env = env;
+			}
 			// NP2: a per-leg timeoutMs override raises (or shortens) just THIS leg's idle-timeout
 			// ceiling without touching the shared default other legs of the same run still see.
 			// Junk (non-finite/≤0) is ignored — the engine's existing childOptions.timeoutMs stands.
@@ -265,8 +275,14 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			// The opaque provider/id the child ran on — for the UI and
 			// as the seed of the provider-fallback chain on a provider failure. The child's
 			// STREAM-REPORTED model wins over the requested spec: a resolved alias or a
-			// provider-side redirect must seed the fallback chain with what actually ran.
-			const modelUsed = child.model ?? childSpec.model ?? spec.model ?? cfg.model;
+			// provider-side redirect must seed the fallback chain with what actually ran. Pi's native
+			// assistant message reports a bare model id: retain the pinned provider ONLY when that
+			// id exactly matches, never attach it to a different observed model or qualified route.
+			const requestedModel = childSpec.model ?? spec.model ?? cfg.model;
+			const observedModel = child.model?.trim() || undefined;
+			const modelUsed = observedModel && !observedModel.includes("/") && requestedModel?.includes("/")
+				&& requestedModel.slice(requestedModel.indexOf("/") + 1) === observedModel
+				? requestedModel : observedModel ?? requestedModel;
 			if (modelUsed) result.modelUsed = modelUsed;
 			// Diagnostic tag: agent · model ref · dynamic overrides. Same shape as inproc engine,
 			// so failed follow-ups always say WHICH agent+model died and WHY.

package/src/engine/async.ts

@@ -71,6 +71,8 @@ export interface AsyncRun {
 	/** The id of the one `tasks` call this leg was launched by. Its members are delivered together, once the
 	 *  last of them settles (see {@link AsyncRunTracker.batchSettled}); a single-leg launch has none. */
 	batch?: string;
+	/** Companion-owned maintenance settles to its owner without waking the supervisor model. */
+	delivery?: "companion";
 	/** What a running run is blocked on, when it is the OPERATOR (a flow checkpoint modal): shown in the
 	 *  digest instead of a stall verdict, because silence while a human decides is not a wedge. */
 	awaiting?: string;
@@ -140,7 +142,7 @@ export class AsyncRunTracker {
 		if (Number.isSafeInteger(issued) && issued > this.seq) this.seq = issued;
 	}
 
-	launch(meta: { agent: string; task: string; label?: string; model?: string; mutates?: boolean; queued?: boolean; batch?: AsyncRun["batch"] }, run: RunThunk): string {
+	launch(meta: { agent: string; task: string; label?: string; model?: string; mutates?: boolean; queued?: boolean; batch?: AsyncRun["batch"]; delivery?: AsyncRun["delivery"] }, run: RunThunk): string {
 		this.seq += 1;
 		const id = `run-${this.seq.toString(36)}`;
 		const startedAt = this.now(); // one clock read, so the launch and stall stamps cannot disagree
@@ -155,6 +157,7 @@ export class AsyncRunTracker {
 		};
 		if (meta.mutates) entry.mutates = true;
 		if (meta.batch) entry.batch = meta.batch;
+		if (meta.delivery) entry.delivery = meta.delivery;
 		// Labels/models are rendered as trusted status metadata on several compact surfaces. Normalize
 		// once at the tracker boundary so a caller cannot smuggle multiline instructions into any of
 		// those views; renderers still sanitize defensively when they compose a label.

package/src/engine/child.ts

@@ -214,6 +214,7 @@ export async function runChildAgent(
 			delete inherited.PI_PERSONA_PEERS;
 			delete inherited.PI_PERSONA_ALLOW_BLOCKING;
 			delete inherited.PI_PERSONA_BUS_TOOLS;
+			delete inherited.PI_PERSONA_MEMORY_PERSONA;
 			delete inherited.PI_PERSONA_RESULT_READER_TOKEN;
 			const proc = spawn(inv.command, inv.args, {
 				cwd: spec.cwd ?? process.cwd(),

package/src/engine/inproc.ts

@@ -28,6 +28,7 @@ import { type ContractDef, contractInstructions, parseAndValidate, pinContract,
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
 import { resolveLegThinking } from "../core/leg-thinking.ts";
 import { assignedIdentityPrompt } from "../core/naming.ts";
+import { installFrozenMemoryOwner } from "../extension/memory-owner.ts";
 import { attributeInbound } from "../core/fence.ts";
 import { isThinkingLevel, type ThinkingLevel } from "../core/types.ts";
 import { roleHint } from "../orchestration/roster.ts";
@@ -55,6 +56,8 @@ export interface InProcSession {
 }
 
 export interface CreateSessionOptions {
+	/** Immutable owning supervisor persona; null explicitly means no persona. */
+	memoryPersona?: string | null;
 	model: unknown;
 	/** Cooperative cancellation for resource/session initialization. Pi's loader does not
 	 * currently accept a signal itself, but injected factories can stop promptly and the
@@ -91,6 +94,8 @@ function sharedModelRuntime(registry: ModelRegistry): unknown {
 }
 
 export interface InProcessDeps {
+	/** Frozen at buildEngine construction, independent of later persona changes or saved settings. */
+	memoryPersona?: string | null;
 	resolveAgent: (name: string) => AgentConfig | undefined;
 	contracts?: (name: string) => ContractDef | undefined;
 	/** The host session's registry — shared so the sub-agent reuses the loader's auth. */
@@ -187,9 +192,12 @@ export function withOrchestrationToolsExcluded(extra: readonly string[] | undefi
  *  the orchestration tools excluded as a second line of defense. */
 const createPiSession: CreateInProcSession = async (opts) => {
 	if (opts.signal?.aborted) throw new DOMException("Session initialization aborted", "AbortError");
+	const manager = SessionManager.inMemory(opts.cwd);
+	const memoryPersona = opts.memoryPersona;
 	const loader = new DefaultResourceLoader({
 		cwd: opts.cwd,
 		agentDir: opts.agentDir,
+		...(memoryPersona !== undefined ? { extensionFactories: [(pi) => installFrozenMemoryOwner(pi, manager, memoryPersona)] } : {}),
 		...(opts.systemPrompt ? { appendSystemPrompt: [opts.systemPrompt] } : {}),
 	});
 	await loader.reload();
@@ -202,7 +210,7 @@ const createPiSession: CreateInProcSession = async (opts) => {
 	// and credentials that exist only in the supervisor's memory.
 	const sessionOptions: NonNullable<Parameters<typeof createAgentSession>[0]> = {
 		model: opts.model as NonNullable<NonNullable<Parameters<typeof createAgentSession>[0]>["model"]>,
-		sessionManager: SessionManager.inMemory(opts.cwd),
+		sessionManager: manager,
 		resourceLoader: loader,
 		cwd: opts.cwd,
 		agentDir: opts.agentDir,
@@ -285,6 +293,7 @@ function popDisableGuard(): void {
 }
 
 export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
+	const memoryPersona = deps.memoryPersona;
 	const createSession = deps.createSession ?? createPiSession;
 	const supervisorHandle = deps.supervisorHandle ?? "supervisor";
 	// Per-run contract pinning (I3), mirroring the child adapter.
@@ -402,6 +411,7 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 				agentDir: deps.agentDir ?? deps.cwd,
 			};
 			if (admittedTools !== undefined) sessionOpts.tools = admittedTools;
+			if (memoryPersona !== undefined) sessionOpts.memoryPersona = memoryPersona;
 			if (excludeTools && excludeTools.length > 0) sessionOpts.excludeTools = excludeTools;
 			if (thinkingRequested !== undefined) sessionOpts.thinkingLevel = thinkingRequested;
 			// The shared behavioral layer (docs/SPINE.md) + the agent's own persona + any

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

@@ -66,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;
 
@@ -76,7 +80,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			engineFactories, makeBrokerDeps, userAgentDir, childPiSettingsEnv, runLimits: RUN_LIMITS,
 			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);
@@ -125,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)
@@ -148,7 +152,8 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				// 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);
 			};
@@ -157,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)
@@ -176,12 +181,13 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				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)
@@ -200,7 +206,8 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 				// 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);
 			}
@@ -268,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);
@@ -311,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

package/src/extension/hooks.ts

@@ -36,7 +36,9 @@ import type { OrchestrationGrammar, Persona } from "../persona/persona.ts";
 import type { PersonaConfigStore } from "../persona/config-store.ts";
 import { TELEMETRY_EVENT_NAME } from "../telemetry/contract.ts";
 import { TelemetryProducer, type TelemetryAgentInput } from "../telemetry/producer.ts";
-import { isWakeSource, type AgentTree, type AgentNode } from "../ui/agent-tree.ts";
+import { isNonAgentNode, type AgentTree, type AgentNode } from "../ui/agent-tree.ts";
+import type { ActivityIngress } from "./companion.ts";
+import type { MemoryOwnerControl } from "./memory-owner.ts";
 import { compactInlineText } from "../ui/presentation.ts";
 import type { FailureKind } from "../orchestration/types.ts";
 import type { ExocomInstall } from "../exocom/install.ts";
@@ -46,7 +48,9 @@ import { resultReceiptHint, type ResultReceipt } from "../results/retrieval.ts";
 
 type MandatoryOutcome = { label: string; output: string; ok: boolean; error?: string; failureKind?: FailureKind; resultReceipt?: ResultReceipt };
 
-export interface HookHost {
+export interface HookHost {
+	readonly companionActivities: ActivityIngress;
+	readonly memoryOwner: MemoryOwnerControl;
 	readonly identity: SessionIdentity;
 	readonly results: SessionResults;
 	config: PiPersonaConfig;
@@ -180,7 +184,9 @@ export function installHooks(pi: ExtensionAPI, h: HookHost, exocom: ExocomInstal
 	}
 
 	// ── lifecycle ─────────────────────────────────────────────────────────────
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
+		const memoryOwnerReady = h.memoryOwner.start(ctx.sessionManager);
+		h.companionActivities.start(ctx);
 		clearInFlight();
 		h.lastCtx = ctx;
 		h.results.activate(ctx);
@@ -273,16 +279,19 @@ export function installHooks(pi: ExtensionAPI, h: HookHost, exocom: ExocomInstal
 				// published — a session start that follows no teardown carries no stale projection.
 				h.lastAgentProjection.clear();
 				for (const node of h.agentTree.snapshot()) {
-					if (isWakeSource(node)) continue; // timer/monitor rows are not agents: no replay, no projection
+					if (isNonAgentNode(node)) continue; // local activity/wake rows are not agent telemetry
 					h.lastAgentProjection.set(node.id, JSON.stringify(h.telemetryAgent(node)));
 					h.telemetry.publishAgentAdded(h.telemetryAgent(node));
 				}
-				exocom.publishTelemetryPeers();
-			}
-		}
-	});
+				exocom.publishTelemetryPeers();
+			}
+		}
+		memoryOwnerReady();
+	});
 
-	pi.on("session_shutdown", async (event, ctx) => {
+	pi.on("session_shutdown", async (event, ctx) => {
+		h.memoryOwner.stop();
+		h.companionActivities.stop(false); // revoke now; the single tree.clear below owns the final repaint
 		clearInFlight();
 		h.lastCtx = ctx;
 		recordLostWork(ctx); // before the notifiers/timers/runs below are torn down

package/src/extension/memory-owner.ts

@@ -0,0 +1,54 @@
+/** Live supervisor selection and immutable per-leg inheritance over the current local host bus. */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { MEMORY_OWNER_EVENT, MEMORY_OWNER_CHANGED_EVENT, type CompanionMemoryOwner } from "../core/companion.ts";
+
+type Manager = ExtensionContext["sessionManager"];
+export interface MemoryOwnerControl {
+	/** Returns a readiness callback bound to this exact activation, revoked by start/stop. */
+	start(manager: Manager): () => void;
+	changed(): void;
+	stop(): void;
+}
+
+export function installMemoryOwner(pi: Pick<ExtensionAPI, "events">, persona: () => string | null): MemoryOwnerControl {
+	let binding: { manager: Manager; sessionId: string; file: string | undefined; ready: boolean } | undefined;
+	const read = (sessionId: string): CompanionMemoryOwner => {
+		const unavailable: CompanionMemoryOwner = { version: 1, provider: "pi-persona", sessionId, ready: false, persona: null };
+		try {
+			if (!binding?.ready || sessionId !== binding.sessionId || binding.manager.getSessionId() !== sessionId || binding.manager.getSessionFile() !== binding.file) return unavailable;
+			return { ...unavailable, ready: true, persona: persona() };
+		} catch { return unavailable; }
+	};
+	const notify = (): void => {
+		if (!binding) return;
+		try { pi.events.emit(MEMORY_OWNER_CHANGED_EVENT, read(binding.sessionId)); } catch { /* observer-only */ }
+	};
+	pi.events.on(MEMORY_OWNER_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.sessionId !== "string" || !query.sessionId || query.sessionId.length > 256 || /[\s\u0000-\u001f\u007f]/u.test(query.sessionId) || typeof query.respond !== "function" || Reflect.ownKeys(query).some((key) => key !== "version" && key !== "sessionId" && key !== "respond")) return;
+		try { query.respond(read(query.sessionId)); } catch { /* a caller cannot break Persona */ }
+	});
+	const api: MemoryOwnerControl = {
+		start(manager) {
+			api.stop();
+			const captured = { manager, sessionId: manager.getSessionId(), file: manager.getSessionFile(), ready: false };
+			binding = captured;
+			return () => { if (binding === captured) { captured.ready = true; notify(); } };
+		},
+		changed() { if (binding?.ready) notify(); },
+		stop() {
+			const previous = binding;
+			binding = undefined;
+			if (previous) try { pi.events.emit(MEMORY_OWNER_CHANGED_EVENT, { version: 1, provider: "pi-persona", sessionId: previous.sessionId, ready: false, persona: null } satisfies CompanionMemoryOwner); } catch { /* observer-only */ }
+		},
+	};
+	return api;
+}
+
+/** A factory closed over this child's actual manager: no mutable process-global persona state. */
+export function installFrozenMemoryOwner(pi: Pick<ExtensionAPI, "events" | "on">, manager: Manager, persona: string | null): void {
+	const owner = installMemoryOwner(pi, () => persona);
+	owner.start(manager)();
+	pi.on("session_shutdown", () => owner.stop());
+}