@aeondave/pi-persona 1.17.3 → 1.17.5

package/src/core/leg-thinking.ts

@@ -0,0 +1,57 @@
+/** Per-leg effort selection. Pi alone owns model-capability clamping. Pure, no host imports. */
+import { isThinkingLevel, THINKING_LEVELS, type ThinkingLevel } from "./types.ts";
+
+/** An explicit invalid selection is a configuration error, never an instruction to inherit. */
+export function parseLegThinking(value: unknown, label = "thinking"): ThinkingLevel | undefined {
+	if (value === undefined) return undefined;
+	if (!isThinkingLevel(value)) throw new Error(`${label} must be one of: ${THINKING_LEVELS.join(", ")}`);
+	return value;
+}
+
+/** One shared display formatter for effort on delegate launch cards: the FULL level name,
+ * with `off` rendering nothing so absence is unambiguous. Unknown input renders nothing too
+ * (render paths must never throw); the compact siglas live in the tree/overlay view, not here. */
+const EFFORT_FULL_NAMES: Record<ThinkingLevel, string> = {
+	off: "",
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "max",
+};
+
+export function effortFullName(level: ThinkingLevel): string {
+	return EFFORT_FULL_NAMES[level] ?? "";
+}
+
+/** The COMPACT siglas for the agent-tree/overlay rows (frozen convention): minimal→mn, low→l,
+ * medium→m, high→h, xhigh→xh, max→mx — with `off` rendering nothing so absence is unambiguous.
+ * Unknown input renders nothing too (render paths must never throw). The delegate CARDS keep the
+ * full names via {@link effortFullName}; the F9 drill-in uses those full names through the same
+ * formatter — only the tree/overlay ROWS are compact. */
+const EFFORT_SIGLAS: Record<ThinkingLevel, string> = {
+	off: "",
+	minimal: "mn",
+	low: "l",
+	medium: "m",
+	high: "h",
+	xhigh: "xh",
+	max: "mx",
+};
+
+export function effortSigla(level: ThinkingLevel): string {
+	return EFFORT_SIGLAS[level] ?? "";
+}
+
+/** Explicit spec (including a roster member) > agent default > configured/inherited child effort.
+ * Validate explicit fields even when another field wins; never normalize a typo into inheritance. */
+export function resolveLegThinking(
+	spec: { thinking?: ThinkingLevel },
+	agent: { thinking?: ThinkingLevel },
+	childThinking: unknown,
+): ThinkingLevel | undefined {
+	const explicit = parseLegThinking(spec.thinking);
+	const configured = parseLegThinking(agent.thinking, "agent.thinking");
+	return explicit ?? configured ?? (isThinkingLevel(childThinking) ? childThinking : undefined);
+}

package/src/core/ownership.ts

@@ -77,8 +77,7 @@ export function writeSetPathError(path: string): string | undefined {
 }
 
 /** Return an actionable error for a parallel write-set collision; undefined means safe to spawn.
- *  Lives here (not in `tools/delegate.ts`) so a strategy can call it without importing a tool
- *  module — `delegate.ts` re-exports it unchanged for its own call sites. */
+ *  Lives here so strategies and tools can depend on ownership without importing each other. */
 export function validateParallelWriteSets(tasks: readonly WriteSetOwner[]): string | undefined {
 	for (const [index, task] of tasks.entries()) {
 		for (const path of task.writeSet ?? []) {

package/src/core/pi-compat.ts

@@ -1,12 +1,11 @@
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Oldest supported Pi host. The release is qualified against Pi 1.0's SDK and tool lifecycle;
- *  pre-1.0 hosts are unsupported. Keep in sync with README.md;
- *  npm host peers use "*" because Pi supplies them through its extension loader. */
-export const MIN_PI_VERSION = "1.0.0";
+/** API baseline of the current stable Pi target. Update with the four pinned development
+ * packages and qualify the installed artifact; historical host releases are not maintained.
+ * Keep README.md aligned. Host peers remain "*" because Pi supplies them through its loader. */
+export const MIN_PI_VERSION = "1.4.0";
 
 function parse(v: string): [number, number, number] | undefined {
 	const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());
@@ -21,15 +20,9 @@ export function satisfiesFloor(version: string, floor: string): boolean {
 }
 
 function resolveHostEntry(): string | undefined {
-	// The host package is ESM-only (no CJS `main`), so `createRequire(...).resolve` throws
-	// ERR_PACKAGE_PATH_NOT_EXPORTED for it — `import.meta.resolve` is tried first because it
-	// follows an `exports` map with no `main`/`require` condition. `createRequire` stays as a
-	// fallback for any host build that does publish one.
+	// The current host exposes its entry through the ESM import condition.
 	try {
 		return fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
-	} catch { /* fall through */ }
-	try {
-		return createRequire(import.meta.url).resolve("@earendil-works/pi-coding-agent");
 	} catch { /* unresolved host */ }
 	return undefined;
 }

package/src/core/session-runs.ts

@@ -83,5 +83,5 @@ export function restoreNotice(lost: LostWork): string | undefined {
 	if (lost.monitors > 0) parts.push(plural(lost.monitors, "monitor"));
 	if (parts.length === 0) return undefined;
 	return `Session restored. Background work from before the restore did not survive (it lives only in memory): ${parts.join("; ")}. `
-		+ "Earlier run results can no longer be fetched. Do not wait for them; relaunch or re-arm only what you still need.";
+		+ "Runtime workers and live run handles are not restored. Retained terminal reports may still be available via intercom { action:'results' } and result { ref:'result:<UUID>' }; read saved data without restarting work. Do not wait for vanished workers; relaunch unfinished work or re-arm wake sources only when still needed.";
 }

package/src/core/types.ts

@@ -14,7 +14,7 @@ export type { Permission };
  *  new level here too — `pi.getThinkingLevel()` returns the upstream union, so a missing member here
  *  is a hard compile error where the host reads it (see `PersonaHost.getThinkingLevel`). */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
 export function isThinkingLevel(x: unknown): x is ThinkingLevel {
 	return typeof x === "string" && (THINKING_LEVELS as readonly string[]).includes(x);

package/src/engine/adapter.ts

@@ -10,7 +10,10 @@ import { randomUUID } from "node:crypto";
 import type { AgentConfig } from "../agents/agent.ts";
 import { type ContractDef, contractInstructions, parseAndValidate, pinContract, type PinnedContract } from "../core/contract.ts";
 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";
@@ -18,8 +21,13 @@ import { type ChildEngineOptions, type ChildRunSpec, runChildAgent } from "./chi
 import { looksLikeProviderError } from "./errors.ts";
 import { piHostModuleHint } from "./host-module.ts";
 import { nextChildHandle } from "./handles.ts";
+import { admitResultReadTool, referenceHandoffFailure } from "./result-grant.ts";
+import { makeScopedResultReader, type ResultArchiveView } from "../results/retrieval.ts";
+import type { PreparedResultReader, ScopedReader } from "../bus/result-reader.ts";
 import { combineSignals } from "./signals.ts";
+import { emptyUsage } from "./stream.ts";
 import { toolModifierFailure, unknownAgentFailure, unknownContractFailure } from "./spec-preflight.ts";
+import { mergeSessionToolAllowlist } from "./session-tools.ts";
 
 /** The engine-side face of the cross-process broker (spec B3/B4/B7) — a child-engine
  *  spawn's connection to the supervisor-hosted relay. The concrete implementation
@@ -40,9 +48,15 @@ export interface EngineAdapterBroker {
 	 *  parent-side idle/startup watchdogs consult this before killing a silent leg (R9): a leg
 	 *  blocked on the supervisor is re-armed, not killed. */
 	hasPendingAskFrom(handle: string): boolean;
+	/** Strict, AWAITED result-reader preflight for a reference-handoff leg (the broker host binds
+	 *  a single-use token to this handle). Must complete BEFORE `register` and the spawn — a
+	 *  missing broker/binding fails the leg closed with zero usage instead of degrading bus-less. */
+	prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader>;
 }
 
 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;
@@ -55,8 +69,7 @@ export interface EngineAdapterDeps {
 	 *  the on-the-fly role this run carries, when it has one, so a member's own assignment key
 	 *  (`agent#hash`) resolves ahead of the bare agent's. */
 	modelFor?: (agent: string, role?: string) => string | undefined;
-	/** Explicit thinking level appended to the child model (`model:level`) so it can't
-	 *  fall into a model's default "adaptive" mode, which some models reject. */
+	/** Configured/inherited child effort, below explicit leg and agent selections. */
 	childThinking?: string;
 	/** The shared behavioral layer (docs/SPINE.md), prepended to every leg's prompt. This is the
 	 *  WORKER variant (`prompts/spine.worker.md`), not the supervisor text — a leg runs headless
@@ -80,9 +93,15 @@ export interface EngineAdapterDeps {
 	 *  blocking would deadlock: default false, mirroring `inproc.ts`'s `allowBlocking`
 	 *  default. Forwarded to the child as `PI_PERSONA_ALLOW_BLOCKING` (bridge.ts). */
 	allowBlocking?: boolean;
+	/** The owning session's terminal archive (a GETTER — the owner can change across sessions).
+	 *  Required by any leg carrying `resultRefs` (flow reference handoff): the scoped reader
+	 *  handed to the broker pages THIS archive, after a zero-usage preflight verified every
+	 *  granted ref is durably stored. Absent ⇒ such legs fail closed before any spawn. */
+	resultArchive?: () => ResultArchiveView | undefined;
 }
 
 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.
@@ -113,10 +132,38 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 		): Promise<AgentResult> {
 			const cfg = deps.resolveAgent(spec.agent);
 			if (!cfg) return unknownAgentFailure(spec.agent, deps.listAgents?.() ?? []);
+			let thinkingRequested: ThinkingLevel | undefined;
+			try {
+				thinkingRequested = resolveLegThinking(spec, cfg, deps.childThinking);
+			} catch (error) {
+				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, failureKind: "contract", error: `[${spec.agent}] ${error instanceof Error ? error.message : String(error)}` };
+			}
 			const tools = spec.tools ?? cfg.tools;
 			const invalidTools = toolModifierFailure(spec.agent, tools);
 			if (invalidTools) return invalidTools;
 
+			// ── reference handoff preflight (contract 3/4) — BEFORE any broker work or spawn ──
+			// Admission uses the SAME shared rule as the in-process engine; storage is verified
+			// durable (session-entry); the broker binding is AWAITED before registration/spawn.
+			// Any miss is a zero-usage contract failure and the child is never invoked.
+			let admittedTools = tools;
+			let resultReader: ScopedReader | undefined;
+			if (spec.resultRefs !== undefined && spec.resultRefs.length > 0) {
+				const grant = admitResultReadTool({
+					specTools: spec.tools, cfgTools: cfg.tools, excludeTools: cfg.excludeTools,
+					canUseBus: deps.canUseBus ?? true,
+				});
+				if (!grant.ok) return referenceHandoffFailure(spec.agent, grant.error);
+				const archive = deps.resultArchive?.();
+				if (archive === undefined) return referenceHandoffFailure(spec.agent, "terminal result archive unavailable for reference handoff");
+				const scoped = makeScopedResultReader(archive, spec.resultRefs);
+				const { missing } = scoped.preflight();
+				if (missing.length > 0) return referenceHandoffFailure(spec.agent, `archived results unavailable: ${missing.join(", ")}`);
+				if (deps.broker === undefined) return referenceHandoffFailure(spec.agent, "cross-process broker reader unavailable for reference handoff");
+				resultReader = scoped;
+				admittedTools = grant.tools;
+			}
+
 			// Resolved (and pinned) up front: the SAME def both instructs the member and
 			// validates its output — an instruction/validation drift is impossible. A named
 			// contract that cannot be resolved is a hard configuration error: running the leg
@@ -130,12 +177,10 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 					: spec.task;
 			const task = contractDef ? `${withSkills}\n\n${contractInstructions(contractDef)}` : withSkills;
 			const childSpec: ChildRunSpec = { task };
-			let model = spec.model ?? deps.modelFor?.(spec.agent, spec.role) ?? cfg.model;
-			// Append an explicit thinking level (model:level) unless one is already present —
-			// a child without it defaults to "adaptive", which some models reject.
-			if (model && deps.childThinking && !model.includes(":")) model = `${model}:${deps.childThinking}`;
+			const model = spec.model ?? deps.modelFor?.(spec.agent, spec.role) ?? cfg.model;
 			if (model) childSpec.model = model;
-			if (tools !== undefined) childSpec.tools = tools;
+			if (thinkingRequested !== undefined) childSpec.thinking = thinkingRequested;
+			if (admittedTools !== undefined) childSpec.tools = admittedTools;
 			if (cfg.excludeTools && cfg.excludeTools.length > 0) childSpec.excludeTools = cfg.excludeTools;
 			// The shared behavioral layer (docs/SPINE.md) + the agent's own persona + any
 			// on-the-fly `role` specialisation from the spec. All three go out as
@@ -147,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.
@@ -160,27 +211,46 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 
 			// Cross-process comm plane (spec B1-B7): absent broker ⇒ none of this runs, so
 			// the spawn env + behaviour stay byte-identical to pre-broker pi-persona.
-			// Present ⇒ mint a handle, register it with the host BEFORE
-			// spawn, wire the child's env, and give the caller a steer function.
+			// Present ⇒ mint a handle, (for a reference-handoff leg) AWAIT the strict reader
+			// binding BEFORE registration, register the handle with the host BEFORE spawn, wire
+			// the child's env, and give the caller a steer function.
 			let handle: string | undefined;
+			let preparedReader: PreparedResultReader | undefined;
 			if (deps.broker) {
-				handle = nextChildHandle(spec.agent);
+				const broker = deps.broker;
+			handle = nextChildHandle(spec.agent);
 				const wantsPeers = spec.peers === true && (deps.canUseBus ?? true);
-				const label = spec.name?.trim()
+				const busTools = (deps.canUseBus ?? true) ? ["contact_supervisor", ...(wantsPeers ? ["contact_peer"] : [])] : [];
+				const mergedTools = mergeSessionToolAllowlist(admittedTools, busTools);
+				if (mergedTools !== undefined) childSpec.tools = mergedTools;
+			const label = spec.name?.trim()
 					? sanitizeDisplayLabel(spec.name, handle)
 					: spec.role ? `${handle} (${roleHint(spec.role)})` : handle;
-				deps.broker.register({ handle, label, group: peerGroup, ...(wantsPeers ? { peers: true } : {}) });
+				if (resultReader !== undefined) {
+					try {
+						preparedReader = await broker.prepareResultReader(handle, resultReader, signal);
+					} catch (error) {
+						return referenceHandoffFailure(spec.agent, `broker result reader preparation failed: ${error instanceof Error ? error.message : String(error)}`);
+					}
+					childOptions.env = {
+						...childOptions.env,
+						// Private spawn credential for the child's bridge (bridge.ts installs read_result
+						// only when this is set); scrubbed from the inherited env inside child.ts.
+						PI_PERSONA_RESULT_READER_TOKEN: preparedReader.token,
+					};
+				}
+				broker.register({ handle, label, group: peerGroup, ...(wantsPeers ? { peers: true } : {}) });
 				childOptions.env = {
 					...childOptions.env,
-					PI_PERSONA_BUS: deps.broker.endpoint,
+					PI_PERSONA_BUS: broker.endpoint,
 					PI_PERSONA_HANDLE: handle,
+					PI_PERSONA_BUS_TOOLS: (deps.canUseBus ?? true) ? "on" : "off",
 					...(wantsPeers ? { PI_PERSONA_PEERS: "1" } : {}),
 					...(deps.allowBlocking ? { PI_PERSONA_ALLOW_BLOCKING: "1" } : {}),
 				};
 				// The parent-side watchdogs must not kill a leg that is genuinely waiting on the
 				// supervisor's answer (R9, inproc parity) — ask the bus, don't guess from a static flag.
-				childOptions.isBlocked = () => deps.broker!.hasPendingAskFrom(handle!);
-				const broker = deps.broker;
+				childOptions.isBlocked = () => broker.hasPendingAskFrom(handle!);
 				const h = handle;
 				const steer: SteerFn = Object.assign((text: string) => broker.steerFrame(h, text), {
 					isWaitingForSupervisor: () => broker.hasPendingAskFrom(h),
@@ -192,17 +262,27 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			try {
 				child = await runChildAgent(childSpec, signal, childOptions);
 			} finally {
-				// Unregister on EVERY settle path (success, failure, or an unexpected throw) —
-				// a leaked handle would otherwise linger in the host's registries forever.
+				// Revoke the reader grant and unregister on EVERY settle path (success, failure, or
+				// an unexpected throw) — a leaked grant would outlive its leg; a leaked handle would
+				// otherwise linger in the host's registries forever.
+				preparedReader?.revoke();
 				if (deps.broker && handle) deps.broker.unregister(handle);
 			}
 
 			const result: AgentResult = { agent: spec.agent, output: child.output, usage: child.usage, ok: child.ok };
-			// The provider/id the child ran on (drop any `:thinking` suffix) — for the UI and
+			if (thinkingRequested !== undefined) result.thinkingRequested = thinkingRequested;
+			if (child.thinkingEffective !== undefined) result.thinkingEffective = child.thinkingEffective;
+			// 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)?.split(":")[0];
+			// 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

@@ -11,13 +11,13 @@
 
 import type { ProgressSnapshot, ToolEvent } from "./stream.ts";
 import type { AgentResult } from "../orchestration/types.ts";
+import { resultReceiptHint, type ResultReceipt } from "../results/retrieval.ts";
 import { DEFAULT_ASYNC_RETAIN } from "../core/config.ts";
 import { MAX_DISPLAY_LABEL_CHARS, sanitizeDisplayLabel, sanitizeStatusLabel } from "../core/display-label.ts";
 import { compactTokens } from "../core/format.ts";
+import { isThinkingLevel } from "../core/types.ts";
 import { formatDuration } from "../core/time.ts";
 
-export { MAX_DISPLAY_LABEL_CHARS } from "../core/display-label.ts";
-
 /** "possibly stuck" — the soft stall signal shared by the operator card, the peek digest and the UI
  *  badge. It is deliberately patient: a long scan, a big generation, or a blocking command shows no
  *  visible progress yet is perfectly healthy, so every surface flags a leg only after a genuinely long quiet
@@ -33,6 +33,7 @@ export interface AsyncRun {
 	status: "running" | "done" | "failed" | "stopped";
 	progress: ProgressSnapshot;
 	result?: AgentResult;
+	resultReceipt?: ResultReceipt;
 	error?: string;
 	/** The codename the launcher gave this run (e.g. "atlas-static") — the SAME name shown on the
 	 *  agent-tree node for this run. When set, it's the canonical display name (over the bare
@@ -70,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;
@@ -115,6 +118,7 @@ export class AsyncRunTracker {
 	/** Ids whose payload was evicted while STILL UNCOLLECTED, oldest first (insertion-ordered Set). */
 	private readonly droppedIds = new Set<string>();
 	private readonly completeListeners: Array<(run: AsyncRun) => void> = [];
+	private readonly createListeners: Array<(run: AsyncRun) => void> = [];
 	private seq = 0;
 	private readonly maxRetained: number;
 	private readonly now: () => number;
@@ -138,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
@@ -153,12 +157,16 @@ 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.
 		if (meta.label !== undefined) entry.label = sanitizeDisplayLabel(meta.label);
 		if (meta.model !== undefined) entry.model = sanitizeDisplayLabel(meta.model, "model");
 		this.runs.set(id, entry);
+		for (const cb of [...this.createListeners]) {
+			try { cb(entry); } catch { /* archival observation cannot prevent launch */ }
+		}
 
 		const settle = (): void => this.settleOnce(entry);
 		// `Promise.resolve(run(...))` routes BOTH a returned rejection AND a SYNCHRONOUS throw from
@@ -176,7 +184,9 @@ export class AsyncRunTracker {
 				.then((result) => {
 					if (entry.settled) return; // force-settled by the supervisor — drop the late natural result
 					entry.status = result.ok ? "done" : result.failureKind === "abort" ? "stopped" : "failed";
-					entry.result = result;
+					// Retain scalar metadata by value: an engine reusing/mutating its result object
+					// after settlement must not rewrite this run's requested/observed effort.
+					entry.result = { ...result, usage: { ...result.usage }, ...(result.resultReceipt ? { resultReceipt: { ...result.resultReceipt } } : {}) };
 					if (!result.ok && result.error) entry.error = result.error;
 				})
 				.catch((err: unknown) => {
@@ -347,6 +357,14 @@ export class AsyncRunTracker {
 		return batch === undefined || !this.running().some((r) => r.batch === batch);
 	}
 
+	onCreate(cb: (run: AsyncRun) => void): () => void {
+		this.createListeners.push(cb);
+		return () => {
+			const i = this.createListeners.indexOf(cb);
+			if (i >= 0) this.createListeners.splice(i, 1);
+		};
+	}
+
 	onComplete(cb: (run: AsyncRun) => void): () => void {
 		this.completeListeners.push(cb);
 		return () => {
@@ -363,10 +381,18 @@ export function dedupeRunsById(runs: AsyncRun[]): AsyncRun[] {
 	return [...byId.values()];
 }
 
+/** A terminal engine observation supersedes the launch choice; running/launch rows retain their snapshot. */
+export function observedRunModel(run: Partial<Pick<AsyncRun, "status" | "result">>): string | undefined {
+	const model = run.status !== undefined && run.status !== "running" ? run.result?.modelUsed : undefined;
+	return model?.trim() ? model.split("/").map((part) => sanitizeDisplayLabel(part, "model", 256)).join("/").slice(0, 256) : undefined;
+}
+
 /** One identity everywhere a tracked run is rendered: the launcher's codename when present,
- *  otherwise the agent type, with the already-shortened model appended once. */
-export function runDisplayName(run: Pick<AsyncRun, "agent" | "label" | "model">): string {
-	const model = run.model === undefined ? undefined : sanitizeDisplayLabel(run.model, "model", 24);
+ *  otherwise the agent type, with the observed terminal model or launch model appended once. */
+export function runDisplayName(run: Pick<AsyncRun, "agent" | "label" | "model"> & Partial<Pick<AsyncRun, "status" | "result">>): string {
+	const observed = observedRunModel(run);
+	const selected = observed ? (observed.split("/").pop() ?? observed).replace(/^claude-/, "") : run.model;
+	const model = selected === undefined ? undefined : sanitizeDisplayLabel(selected, "model", 24);
 	if (model === undefined) return sanitizeDisplayLabel(run.label ?? run.agent);
 	const suffix = ` · ${model}`;
 	const nameLimit = Math.max(1, MAX_DISPLAY_LABEL_CHARS - suffix.length);
@@ -618,6 +644,25 @@ export function buildCompletionReport(runs: AsyncRun[], fence: (text: string) =>
 	const stoppedCount = stopped.length > 0 ? `, ${stopped.length} stopped` : "";
 	const head = `[pi-persona] ${runs.length} async run${runs.length === 1 ? "" : "s"} settled — ${done.length} done, ${failed.length} failed${stoppedCount}`;
 	const blocks: string[] = [head];
+	const models = runs.flatMap((run) => {
+		const model = observedRunModel(run);
+		return model ? [`${run.id}: Observed model: ${model}`] : [];
+	});
+	if (models.length > 0) blocks.push(`\n${models.join("\n")}`);
+	const receipts = runs.slice(0, MAX_ASYNC_STATUS_ROWS).flatMap((run) => {
+		const hint = resultReceiptHint(run.resultReceipt);
+		return hint ? [`${run.id}: ${hint}`] : [];
+	});
+	if (receipts.length > 0) blocks.push(`\nTerminal reports (intercom results lists all retained references):\n${receipts.join("\n")}`);
+	// Common result metadata, outside untrusted worker prose, on inline and background paths.
+	// A host effort observation is a Pi request setting, not a measure of provider cognition.
+	const efforts = runs.flatMap((r) => {
+		const requested = r.result?.thinkingRequested;
+		const observed = r.result?.thinkingEffective;
+		if (!isThinkingLevel(requested) && !isThinkingLevel(observed)) return [];
+		return [`${r.id}: requested ${isThinkingLevel(requested) ? requested : "unknown"}; observed Pi effort ${isThinkingLevel(observed) ? observed : "unknown"}`];
+	});
+	if (efforts.length > 0) blocks.push(`\nThinking (not provider cognition):\n${efforts.join("\n")}`);
 	for (const r of done) {
 		// Only fence REAL output — an empty/whitespace result gets a plain "(no output)", never an
 		// empty <fence></fence> shell (there's nothing untrusted to guard, and the empty block reads
@@ -660,7 +705,7 @@ export function buildCompletionReport(runs: AsyncRun[], fence: (text: string) =>
 	// The cap cuts whole legs from the middle of a wide fan-out. Name every run in the tail, which the
 	// cut keeps, so a cut leg is still fetchable by id instead of silently missing.
 	const named = report.length > MAX_COMPLETION_REPORT_CHARS
-		? `${report}\n\nRun ids in this report: ${runs.slice(0, MAX_ASYNC_STATUS_ROWS).map((r) => r.id).join(", ")}`
+		? `${report}\n\nRun ids in this report: ${runs.slice(0, MAX_ASYNC_STATUS_ROWS).map((r) => r.id).join(", ")}. Saved reports: intercom { action:"results" }; use result { ref, offset, limit } even if live handles were dropped.`
 		: report;
 	return boundCompletionSurface(named);
 }
@@ -697,9 +742,6 @@ export const MAX_EMPTY_RENDER_RETRIES = 3;
 export interface IdleNotifierDeps<T> {
 	/** Whether the supervisor is idle (not streaming a turn). */
 	isIdle: () => boolean;
-	/** Legacy host-queue probe. Retained for source compatibility, but deliberately ignored: when
-	 *  the supervisor is idle, starting a turn is what drains any orphaned host follow-ups. */
-	hasPending?: () => boolean;
 	/** Deliver the coalesced message. Async rejection is treated exactly like a synchronous throw:
 	 *  the batch is restored at the front of the queue and retried. */
 	deliver: (message: string) => void | Promise<void>;

package/src/engine/child.ts

@@ -10,11 +10,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import type { ThinkingLevel } from "../core/types.ts";
 import { applyEvent, type ChildUsage, createStreamState, feedLines, type ProgressSnapshot, snapshot } from "./stream.ts";
 
 export interface ChildRunSpec {
 	task: string;
 	model?: string;
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	excludeTools?: string[];
 	systemPrompt?: string;
@@ -32,6 +34,7 @@ export interface ChildRunResult {
 	/** True when the idle watchdog OR the hard wall-clock cap fired. Disjoint from `aborted`. */
 	timedOut: boolean;
 	model?: string;
+	thinkingEffective?: ThinkingLevel;
 	stopReason?: string;
 	errorMessage?: string;
 }
@@ -166,6 +169,7 @@ export async function runChildAgent(
 
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (spec.model) args.push("--model", spec.model);
+	if (spec.thinking !== undefined) args.push("--thinking", spec.thinking);
 	if (spec.tools !== undefined) {
 		if (spec.tools.length > 0) args.push("--tools", spec.tools.join(","));
 		else args.push("--no-tools");
@@ -201,13 +205,17 @@ export async function runChildAgent(
 			const inv = resolveInvocation(args);
 			// A stale broker wiring in the SUPERVISOR's own environment must not leak into a
 			// plain child: PI_PERSONA_BUS would boot the child's bridge against a dead (or
-			// foreign) endpoint. The adapter re-adds these deliberately via opts.env when a
-			// broker is actually live for THIS run.
+			// foreign) endpoint, and a stale reader token would arm a read_result tool nobody
+			// granted. The adapter re-adds these deliberately via opts.env when a broker (and a
+			// result-reader grant) is actually live for THIS run.
 			const inherited = { ...process.env };
 			delete inherited.PI_PERSONA_BUS;
 			delete inherited.PI_PERSONA_HANDLE;
 			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(),
 				shell: false,
@@ -496,6 +504,7 @@ export async function runChildAgent(
 			timedOut: timedOut || hardTimedOut || startupTimedOut,
 		};
 		if (state.model !== undefined) result.model = state.model;
+		if (state.thinkingEffective !== undefined) result.thinkingEffective = state.thinkingEffective;
 		if (state.stopReason !== undefined) result.stopReason = state.stopReason;
 		// errorMessage precedence: a timeout/abort is the *cause of death*, so label
 		// it explicitly and fold in any stream-level error rather than letting the