@aeondave/pi-persona 1.15.2

package/src/extension/broker-host.ts

@@ -0,0 +1,181 @@
+/**
+ * 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.
+ */
+
+import { mkdirSync } from "node:fs";
+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";
+
+export interface SupervisorBrokerDeps {
+	bus: InProcessBus;
+	supervisorHandle: string;
+	/** Injected in tests. */
+	startHost?: typeof startBrokerHost;
+	/** User-facing warning (ctx.ui.notify "warning" when a TUI is present, stderr otherwise). */
+	warn: (message: string) => void;
+}
+
+/** Cross-process `contact_peer` roster (spec B7): scopes `brokerPeers` — the process-wide,
+ *  pre-spawn registry keyed by handle (populated in `SupervisorBroker.adapterDeps`'s `register`,
+ *  below) — to the SAME per-engine group as the caller `self`, mirroring `engine/inproc.ts`'s
+ *  per-engine-instance `peerLabels` map. `self`'s OWN recorded group is the source of truth
+ *  here, NOT the wire's `group` argument the host would otherwise pass: the child's env
+ *  carries no group (spec B6, the wire `register` frame stays minimal), so every wire group
+ *  is "" and scoping by it would either always come back empty (this scope) or leak every
+ *  concurrent run's peers into one flat list (the host's own default `group=""` scoping).
+ *  `self` not found (not registered with `peers: true`) ⇒ empty roster, never a leak.
+ *  Exported for direct unit/integration testing — `extension.ts`'s activation closure itself
+ *  isn't a testable unit. */
+export function listPeersForGroup(brokerPeers: ReadonlyMap<string, { label: string; group: string }>, self: string): Array<{ handle: string; label: string }> {
+	const g = brokerPeers.get(self)?.group;
+	if (g === undefined) return [];
+	return [...brokerPeers.entries()]
+		.filter(([handle, p]) => p.group === g && handle !== self)
+		.map(([handle, p]) => ({ handle, label: p.label }));
+}
+
+export class SupervisorBroker {
+	readonly peers = new Map<string, { label: string; group: string }>();
+	private hostRef: BrokerHost | undefined;
+	private promise: Promise<BrokerHost> | undefined;
+	private lastError: string | undefined;
+	private warned = false;
+	private readonly expected = new Set<string>();
+	private readonly preHostSteers = new Map<string, string[]>();
+	private readonly deps: SupervisorBrokerDeps;
+
+	constructor(deps: SupervisorBrokerDeps) {
+		this.deps = deps;
+	}
+
+	get host(): BrokerHost | undefined {
+		return this.hostRef;
+	}
+
+	get error(): string | undefined {
+		return this.lastError;
+	}
+
+	/** The lifecycle state `adapterDeps`, `steerFrame`, and `doctorLine` each branch on, named
+	 *  once so they can never read it as three different ad hoc conditions. */
+	private state(): "idle" | "starting" | "up" | "failed" {
+		if (this.hostRef) return "up";
+		if (this.lastError !== undefined) return "failed";
+		if (this.promise) return "starting";
+		return "idle";
+	}
+
+	/** Start the host once per endpoint attempt; retried on the next call after a failure. */
+	ensure(endpoint: string): void {
+		if (this.promise) return;
+		if (process.platform !== "win32") {
+			try {
+				mkdirSync(dirname(endpoint), { recursive: true }); // POSIX sockets are filesystem paths
+			} catch {
+				/* a failed mkdir surfaces as a listen error below */
+			}
+		}
+		const start = this.deps.startHost ?? startBrokerHost;
+		this.promise = start({
+			bus: this.deps.bus,
+			supervisorHandle: this.deps.supervisorHandle,
+			endpoint,
+			listPeersFor: (_group, self) => listPeersForGroup(this.peers, self),
+		});
+		this.promise.then(
+			(h) => {
+				this.hostRef = h;
+				this.lastError = undefined;
+				this.warned = false;
+				for (const handle of this.expected) h.expect(handle);
+				for (const [handle, texts] of this.preHostSteers) for (const text of texts) h.steer(handle, text);
+				this.preHostSteers.clear();
+			},
+			(err) => {
+				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);
+				this.preHostSteers.clear();
+				if (!this.warned) {
+					this.warned = true;
+					this.deps.warn(
+						`pi-persona: child-agent bus unavailable — ${this.lastError}; child legs run without live steer/contact until it starts${dropped > 0 ? `; ${dropped} queued steer${dropped === 1 ? "" : "s"} ${dropped === 1 ? "was" : "were"} dropped` : ""}`,
+					);
+				}
+			},
+		);
+	}
+
+	/** 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";
+		this.ensure(endpoint);
+		if (failedBefore) return undefined;
+		return {
+			endpoint,
+			register: (info) => {
+				this.deps.bus.register(info.handle);
+				this.expected.add(info.handle);
+				if (info.peers) this.peers.set(info.handle, { label: info.label ?? info.handle, group: info.group ?? "" });
+				this.hostRef?.expect(info.handle);
+			},
+			unregister: (handle) => {
+				this.expected.delete(handle);
+				this.preHostSteers.delete(handle);
+				this.peers.delete(handle);
+				this.deps.bus.unregister(handle);
+				this.hostRef?.forget(handle);
+			},
+			steerFrame: (handle, text) => {
+				if (this.hostRef) return this.hostRef.steer(handle, text);
+				if (this.state() === "failed" || !this.expected.has(handle) || !text.trim()) return false;
+				const queued = this.preHostSteers.get(handle) ?? [];
+				queued.push(text);
+				this.preHostSteers.set(handle, queued);
+				return true;
+			},
+			hasPendingAskFrom: (handle) => this.deps.bus.hasPendingAskFrom(handle),
+		};
+	}
+
+	doctorLine(): string {
+		// Failed is reported on its own (spec §4.7: `broker: failed — <reason>`) rather than folded
+		// into the "on — …" family: there is no host and no connected-children count to report while
+		// down, so "broker: on — failed — …" was a confusing double dash for a state that isn't "on".
+		if (this.state() === "failed") return `broker: failed — ${this.lastError}`;
+		let status: string;
+		switch (this.state()) {
+			case "up":
+				status = `endpoint ${this.hostRef?.endpoint}`;
+				break;
+			case "starting":
+				status = "(starting…)";
+				break;
+			default:
+				status = "(not started — no child-engine build yet)";
+		}
+		return `broker: on — ${status}, connected children: ${this.hostRef?.connectedHandles().length ?? 0}`;
+	}
+
+	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.hostRef = undefined;
+		this.promise = undefined;
+		this.peers.clear();
+		this.expected.clear();
+		this.preHostSteers.clear();
+	}
+}

package/src/extension/clock.ts

@@ -0,0 +1,14 @@
+/** Resolve host-local facts outside the pure clock formatter. */
+import { buildClockSnapshot } from "../core/time.ts";
+
+export function readClockSnapshot(now: number): string | undefined {
+	const date = new Date(now);
+	if (!Number.isFinite(date.getTime())) return undefined;
+	let timeZone = "local timezone";
+	try {
+		timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone || timeZone;
+	} catch {
+		// The numeric offset still identifies local time when an IANA name is unavailable.
+	}
+	return buildClockSnapshot(now, { timeZone, offsetMinutes: -date.getTimezoneOffset() });
+}

package/src/extension/engine.ts

@@ -0,0 +1,321 @@
+/**
+ * Engine construction: in-process vs child, worktree isolation, MCP-child routing, provider fallback.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { AgentConfig } from "../agents/agent.ts";
+import { type ContractDef, DEFAULT_CONTRACT, installedContractNames } from "../core/contract.ts";
+import type { RunLimits } from "../core/capabilities.ts";
+import type { PiPersonaConfig } from "../core/config.ts";
+import { isThinkingLevel } from "../core/types.ts";
+import { personaModels, type PersonaConfigStore } from "../persona/config-store.ts";
+import type { PersonaController, PersonaHost } from "../persona/controller.ts";
+import { type EngineAdapterBroker, type EngineAdapterDeps, makeEngine } from "../engine/adapter.ts";
+import { captureStatus, diffStatus, findGitRoot, renderChangeReport } from "../engine/change-report.ts";
+import { withModelFallback } from "../engine/fallback.ts";
+import { captureWorktreeArtifact, defaultGitExec, type GitExec, withWorktree, worktreePreflight } from "../engine/worktree.ts";
+import { type InProcessDeps, makeInProcessEngine } from "../engine/inproc.ts";
+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";
+
+export interface EngineFactories {
+	makeEngine: typeof makeEngine;
+	makeInProcessEngine: typeof makeInProcessEngine;
+}
+
+export const DEFAULT_ENGINE_FACTORIES: EngineFactories = Object.freeze({ makeEngine, makeInProcessEngine });
+
+export interface BuildEngineDeps {
+	agents: AgentConfig[];
+	contractDefs: Record<string, ContractDef>;
+	controller: PersonaController;
+	host: PersonaHost;
+	config: PiPersonaConfig;
+	personaConfigs: PersonaConfigStore;
+	lastCtx: ExtensionContext | undefined;
+	workerSpineText: string;
+	engineFactories: EngineFactories;
+	makeBrokerDeps: (ctx: ExtensionContext) => EngineAdapterBroker | undefined;
+	userAgentDir: () => string;
+	childPiSettingsEnv: () => Record<string, string>;
+	runLimits: RunLimits;
+	bus: InProcessBus;
+	supervisorHandle: string;
+	/** 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
+	 *  `defaultGitExec`. */
+	gitExec?: GitExec;
+}
+
+export type BuildEngine = (signal?: AbortSignal, onProgress?: (s: ProgressSnapshot) => void, engOpts?: { async?: boolean }) => StrategyEngine;
+
+export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
+	return (signal, onProgress, engOpts) => {
+		const {
+			agents, contractDefs, controller, host, config, personaConfigs, lastCtx, workerSpineText,
+			engineFactories, makeBrokerDeps, userAgentDir, childPiSettingsEnv, runLimits: RUN_LIMITS,
+			bus, supervisorHandle: SUPERVISOR, onFallback,
+		} = 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.
+			const contracts = (n: string): ContractDef | undefined => contractDefs[n] ?? (n === "default" ? DEFAULT_CONTRACT : undefined);
+			const contractNames = (): string[] => installedContractNames(contractDefs);
+			const modelFor = (agent: string): string | undefined => {
+				const persona = controller.activePersona?.name;
+				return persona ? personaModels(personaConfigs, persona)[agent] : undefined;
+			};
+			// The main model thinks adaptively (it picks effort by difficulty); a spawned child
+			// can't inherit "adaptive" if its model doesn't support it, so give children an
+			// explicit level — the supervisor's (if concrete) or a sane default, overridable.
+			const supLevel = host.getThinkingLevel();
+			const childThinking = config.childThinking ?? (isThinkingLevel(supLevel) ? supLevel : "high");
+
+			// A persona that opted out of the layer (`spine: false`) opts its legs out too — otherwise
+			// a short verdict persona (judge/verify/audit) would still pay for the baseline on every
+			// sub-agent it spawns. The per-AGENT opt-out applies on top, inside each engine.
+			const legSpine = controller.activePersona?.spine === false ? "" : workerSpineText;
+
+			// Cross-process broker (spec B1-B7): lazily built on the FIRST actual child-engine
+			// construction below (worktree leg, MCP leg, or `PI_PERSONA_ENGINE=child`) — NOT on every
+			// `buildEngine` call, most of which build the (default) in-process engine and never
+			// touch a child at all; starting a host for those would be neither lazy nor needed.
+			// Memoized so both call sites below share ONE broker object (and its `peerGroup`
+			// registration) per `buildEngine` invocation. `config.broker` off or no live
+			// `ctx` yet ⇒ stays undefined forever, so `deps.broker` is never set.
+			let brokerDepsMemo: EngineAdapterBroker | undefined;
+			let brokerDepsBuilt = false;
+			const getBrokerDeps = (): EngineAdapterBroker | undefined => {
+				if (!brokerDepsBuilt) {
+					brokerDepsBuilt = true;
+					const sessionId = (lastCtx as { sessionManager?: { getSessionId?: () => string } } | undefined)?.sessionManager?.getSessionId?.();
+					if (config.broker && lastCtx && sessionId) brokerDepsMemo = makeBrokerDeps(lastCtx);
+				}
+				return brokerDepsMemo;
+			};
+
+			// 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 };
+				deps.listAgents = () => agents.map((a) => a.name);
+				deps.listContracts = contractNames;
+				if (legSpine) deps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
+				if (signal) deps.signal = signal;
+				deps.childOptions = {
+					timeoutMs: RUN_LIMITS.timeoutMs,
+					hardTimeoutMs: config.agentHardTimeoutMs,
+					startupTimeoutMs: config.agentStartupTimeoutMs,
+					env: childPiSettingsEnv(),
+				};
+				// Feed progress here too (mirrors the plain-child branch): without it a worktree/mcp async leg
+				// never advances its tracker snapshot, so lastAdvanceAt freezes at launch and the leg is falsely
+				// flagged stalled while a genuine later wedge goes undetected.
+				if (onProgress) deps.childOptions.onProgress = onProgress;
+				const brokerDeps = getBrokerDeps();
+				if (brokerDeps) deps.broker = brokerDeps;
+				// 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?.async) deps.allowBlocking = true;
+				return engineFactories.makeEngine(deps);
+			};
+
+			// v0.4: run sub-agents in-process (createAgentSession) instead of spawning `pi -p`.
+			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() };
+				ideps.listAgents = () => agents.map((a) => a.name);
+				ideps.listContracts = contractNames;
+				if (legSpine) ideps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
+				ideps.timeoutMs = RUN_LIMITS.timeoutMs; // idle watchdog — a hung session must settle, like the child engine's idle kill
+				ideps.hardTimeoutMs = config.agentHardTimeoutMs; // hard lifetime ceiling — catches a busy loop the idle watchdog never would
+				ideps.startupTimeoutMs = config.agentStartupTimeoutMs; // first-progress deadline — fast-fail a child that never started
+				if (signal) ideps.signal = signal;
+				if (onProgress) ideps.onProgress = onProgress;
+				if (lastCtx.model) ideps.defaultModel = `${lastCtx.model.provider}/${lastCtx.model.id}`;
+				// Comm plane: a `coaching: on` persona gives its children `contact_supervisor`.
+				// Blocking asks are honoured only for async runs (a sync run holds the turn → it
+				// can't answer, so blocking there would deadlock; the tool downgrades to one-way).
+				ideps.bus = bus;
+				ideps.supervisorHandle = SUPERVISOR;
+				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?.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 };
+				deps.listAgents = () => agents.map((a) => a.name);
+				deps.listContracts = contractNames;
+				if (legSpine) deps.spine = legSpine; // legs get the worker variant (docs/SPINE.md)
+				if (signal) deps.signal = signal;
+				if (lastCtx?.cwd) deps.cwd = lastCtx.cwd;
+				deps.childOptions = {
+					timeoutMs: RUN_LIMITS.timeoutMs,
+					hardTimeoutMs: config.agentHardTimeoutMs,
+					startupTimeoutMs: config.agentStartupTimeoutMs,
+					env: childPiSettingsEnv(),
+				}; // idle watchdog + hard cap + startup deadline on every child; same Pi settings dir as inproc
+				if (onProgress) deps.childOptions.onProgress = onProgress;
+				const brokerDeps = getBrokerDeps();
+				if (brokerDeps) deps.broker = brokerDeps;
+				// 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?.async) deps.allowBlocking = true;
+				base = engineFactories.makeEngine(deps);
+			}
+
+			// Worktree isolation: an agent/leg marked `isolation: worktree` runs in a throwaway git
+			// worktree via the child engine (its edits never touch the main tree), regardless of the
+			// default backend. This branch is deliberately fail-closed: a missing/dirty repository or
+			// failed worktree creation is a contract failure, never permission to run in the real cwd.
+			// Provider fallback (outermost): a run whose model PROVIDER fails at call time (auth,
+			// outage, 5xx, model-not-supported) is retried on the same model id under another
+			// authenticated provider — "priority to the supervisor's provider, but try others and
+			// switch on error". No ctx (no registry) ⇒ pass through. Each attempt still runs through
+			// worktree isolation + steering below.
+			const wrapFallback = (eng: StrategyEngine): StrategyEngine => {
+				if (!lastCtx) return eng;
+				const prefer = lastCtx.model?.provider;
+				return withModelFallback(eng, {
+					models: configuredModels(lastCtx),
+					...(prefer ? { preferProvider: prefer } : {}),
+					...(onFallback ? { onFallback } : {}),
+				});
+			};
+			const root = lastCtx?.cwd;
+			const gitExec = d().gitExec ?? defaultGitExec;
+			// Files-changed report for a leg that does NOT run in its own worktree: it shares the
+			// real checkout, so the only honest signal is "what did `git status` see change while
+			// this leg ran" — a before/after snapshot, not a private diff (see change-report.ts).
+			// Skipped for the worktree path below, which already returns a real diff artifact, and
+			// for the whole feature when `PI_PERSONA_LEG_CHANGE_REPORT` is off.
+			//
+			// The repository root is resolved ONCE here (a pure filesystem walk, no process spawn)
+			// and threaded into BOTH captures as their `knownGitRoot` — each then skips its own
+			// walk AND its `rev-parse` liveness gate, so a leg pays for exactly two `git status`
+			// spawns (one at launch, one at settle) instead of four.
+			const withChangeReport = async (run: () => Promise<AgentResult>, spec: AgentRunSpec): Promise<AgentResult> => {
+				if (!root || config.changeReport === false) return run();
+				const gitRoot = findGitRoot(root);
+				if (!gitRoot) return run();
+				const before = await captureStatus(gitRoot, gitExec, gitRoot);
+				const result = await run();
+				if (!before) return result;
+				const after = await captureStatus(gitRoot, gitExec, gitRoot);
+				if (!after) return result;
+				const block = renderChangeReport(diffStatus(before, after), spec.writeSet);
+				return block ? appendBlock(result, block) : result;
+			};
+			return wrapFallback({
+				async run(spec, perProgress, perSignal, perSteer) {
+					const iso = spec.isolation ?? resolveAgent(spec.agent)?.isolation;
+					if (iso === "worktree") {
+						if (!root) {
+							return isolatedWorktreeFailure(spec, "worktree isolation requires a real Git cwd; remove isolation: \"worktree\" or run inside a Git checkout");
+						}
+						const preflight = await worktreePreflight(root, defaultGitExec);
+						if (!preflight.ok) return isolatedWorktreeFailure(spec, preflight.error);
+						try {
+							return await withWorktree(root, defaultGitExec, async (dir) => {
+								const result = await childEngineAt(dir).run({ ...spec, isolation: "none" }, perProgress, perSignal, perSteer);
+								const artifact = await captureWorktreeArtifact(dir, defaultGitExec);
+								const hasOutputArtifact = hasUnifiedDiff(result.output);
+								if (!result.ok) {
+									return artifact.ok && artifact.diff.trim().length > 0
+										? appendWorktreeArtifact(result, artifact.diff)
+										: result;
+								}
+								if (!artifact.ok) {
+									if (hasOutputArtifact) return 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);
+								if (hasOutputArtifact) return result;
+								return isolatedWorktreeFailure(
+									spec,
+									"isolated leg returned success but produced no unified diff or artifact; its worktree was discarded — return a complete diff or remove isolation: \"worktree\"",
+								);
+							});
+						} catch (err) {
+							return isolatedWorktreeFailure(spec, err instanceof Error ? err.message : String(err));
+						}
+					}
+					// MCP-capable leg: the DEFAULT in-process engine never fires `session_start`, so
+					// `pi-mcp-adapter` never initializes and the sub-agent's `mcp*`/direct tools come
+					// back "MCP not initialized". Route it through the child engine (a real `pi -p`,
+					// which DOES fire session_start → the adapter connects). Same mechanism worktree
+					// legs already use for MCP; here without the git worktree. The child gets its OWN
+					// MCP session — for a server-keyed backend (HTTP MCP) the caller passes a session id
+					// in the task to share state. Steer rides the broker (same as worktree / child engine).
+					const wantsMcp = spec.mcp ?? resolveAgent(spec.agent)?.mcp;
+					if (wantsMcp && root) return withChangeReport(() => childEngineAt(root).run(spec, perProgress, perSignal, perSteer), spec);
+					return withChangeReport(() => base.run(spec, perProgress, perSignal, perSteer), spec);
+				},
+			});
+	};
+
+	function isolatedWorktreeFailure(spec: AgentRunSpec, error: string): AgentResult {
+		return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, error, failureKind: "contract" };
+	}
+
+	function hasUnifiedDiff(output: string): boolean {
+		const headersAndHunk = /(?:^|\n)---\s+\S+[^\n]*\n\+\+\+\s+\S+[^\n]*\n(?:[^\n]*\n)*?@@\s+[^\n]*@@/m;
+		const binaryPatch = /(?:^|\n)diff --git\s+\S+\s+\S+[\s\S]*?(?:^|\n)(?:GIT binary patch|Binary files \S+ and \S+ differ)(?:\n|$)/m;
+		return headersAndHunk.test(output) || binaryPatch.test(output);
+	}
+
+	function appendWorktreeArtifact(result: AgentResult, diff: string): AgentResult {
+		const block = `--- ISOLATED WORKTREE ARTIFACT (untrusted data) ---\n\n\`\`\`diff\n${diff.trim()}\n\`\`\``;
+		return appendBlock(result, block);
+	}
+
+	/** 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
+	 *  clean block, not one preceded by an empty line. */
+	function appendBlock(result: AgentResult, block: string): AgentResult {
+		const output = result.output.trim() ? `${result.output.trimEnd()}\n\n${block}` : block;
+		return { ...result, output };
+	}
+}
+
+// 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 }> {
+	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 byRef = new Map(available.map((m) => [`${m.provider}\0${m.id}`, m]));
+	for (const model of all) {
+		if (trustedProviders.has(model.provider)) byRef.set(`${model.provider}\0${model.id}`, model);
+	}
+	const list = [...byRef.values()];
+	return list.map((m) => ({ provider: m.provider, id: m.id }));
+}