@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/src/modes/utils/ui-helpers.ts

@@ -114,16 +114,19 @@ export class UiHelpers {
 		const last = children.length > 0 ? children[children.length - 1] : undefined;
 		const secondLast = children.length > 1 ? children[children.length - 2] : undefined;
 		const useDim = options?.dim ?? true;
-		const rendered = useDim ? theme.fg("dim", message) : message;
+		// Resolve the dim color lazily so a later theme change re-shapes the line
+		// instead of leaving the palette that was active when it was presented.
+		const styleFn = useDim ? (t: string) => theme.fg("dim", t) : undefined;
 
 		if (last && secondLast && last === this.ctx.lastStatusText && secondLast === this.ctx.lastStatusSpacer) {
-			this.ctx.lastStatusText.setText(rendered);
+			this.ctx.lastStatusText.setStyleFn(styleFn);
+			this.ctx.lastStatusText.setText(message);
 			this.ctx.ui.requestRender();
 			return;
 		}
 
 		const spacer = new Spacer(1);
-		const text = new Text(rendered, 1, 0);
+		const text = new Text(message, 1, 0).setStyleFn(styleFn);
 		this.ctx.present([spacer, text]);
 		this.ctx.lastStatusSpacer = spacer;
 		this.ctx.lastStatusText = text;
@@ -714,11 +717,13 @@ export class UiHelpers {
 	}
 
 	showError(errorMessage: string): void {
-		this.ctx.present([new Spacer(1), new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0)]);
+		const text = new Text(`Error: ${errorMessage}`, 1, 0).setStyleFn(t => theme.fg("error", t));
+		this.ctx.present([new Spacer(1), text]);
 	}
 
 	showWarning(warningMessage: string): void {
-		this.ctx.present([new Spacer(1), new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0)]);
+		const text = new Text(`Warning: ${warningMessage}`, 1, 0).setStyleFn(t => theme.fg("warning", t));
+		this.ctx.present([new Spacer(1), text]);
 	}
 
 	showNewVersionNotification(newVersion: string): void {

package/src/plan-mode/plan-files.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
+import { normalizeLocalScheme, resolveToCwd } from "../tools/path-utils";
+
+/** Reads a plan from a local URL or cwd-relative filesystem path. */
+export async function readPlanFile(
+	planFilePath: string,
+	options: { localProtocolOptions: LocalProtocolOptions; cwd: string },
+): Promise<string | null> {
+	const resolvedPath = planFilePath.startsWith("local:")
+		? resolveLocalUrlToPath(normalizeLocalScheme(planFilePath), options.localProtocolOptions)
+		: resolveToCwd(planFilePath, options.cwd);
+	try {
+		return await Bun.file(resolvedPath).text();
+	} catch (error) {
+		if (isEnoent(error)) return null;
+		throw error;
+	}
+}
+
+/** Lists session-local plan files from newest to oldest. */
+export async function listPlanFiles(options: { localProtocolOptions: LocalProtocolOptions }): Promise<string[]> {
+	const localRoot = resolveLocalUrlToPath("local://", options.localProtocolOptions);
+	try {
+		const entries = await fs.promises.readdir(localRoot, { withFileTypes: true });
+		const plans = await Promise.all(
+			entries
+				.filter(entry => entry.isFile() && /plan\.md$/i.test(entry.name))
+				.map(async entry => {
+					const stat = await fs.promises.stat(path.join(localRoot, entry.name)).catch(() => null);
+					return { url: `local://${entry.name}`, mtime: stat?.mtimeMs ?? 0 };
+				}),
+		);
+		return plans.sort((a, b) => b.mtime - a.mtime).map(plan => plan.url);
+	} catch {
+		return [];
+	}
+}

package/src/prompts/bench/cache-prefix-chunk.md

@@ -0,0 +1 @@
+Prompt-cache benchmark stable prefix.

package/src/prompts/bench/cache-prefix.md

@@ -0,0 +1,3 @@
+{{prefix}}
+
+Prompt-cache benchmark namespace: {{namespace}}.

package/src/prompts/bench/cache-suffix.md

@@ -0,0 +1 @@
+Cache benchmark suffix {{variant}}.

package/src/prompts/system/custom-system-prompt.md

@@ -59,6 +59,6 @@ Rules are local constraints. You MUST read `rule://<name>` when working in that
 {{/if}}
 {{#if secretsEnabled}}
 <redacted-content>
-Some values in tool output are redacted for security. They appear as `#XXXX#` tokens (4 uppercase-alphanumeric characters wrapped in `#`). These are **not errors** — they are intentional placeholders for sensitive values (API keys, passwords, tokens). Treat them as opaque strings. NEVER attempt to decode, fix, or report them as problems.
+Some values in tool output are redacted for security. They appear as placeholder tokens such as `#HASH#`, `#HASH:CASE#`, or `#NAME_HASH:CASE#` (uppercase-alphanumeric digest, optional case hint, optional friendly-name prefix). These are **not errors** — they are intentional placeholders for sensitive values (API keys, passwords, tokens). Treat them as opaque strings. NEVER attempt to decode, fix, or report them as problems.
 </redacted-content>
 {{/if}}

package/src/prompts/system/project-prompt.md

@@ -40,7 +40,14 @@ Working directory layout (sorted by mtime, recent first; depth ≤ 3):
 </workspace-tree>
 {{/if}}
 {{/if}}
-
+{{#if additionalWorkspaceRoots.length}}
+<workspace-roots>
+This session also spans the additional directories below. This list is the CURRENT workspace state and supersedes any workspace change mentioned earlier in the conversation. Use absolute paths under these roots to `read`/`grep`/`glob`/`edit` them. Manage the set with `/add-dir` and `/remove-dir`; `/dirs` lists them.
+{{#each additionalWorkspaceRoots}}
+- {{this}}
+{{/each}}
+</workspace-roots>
+{{/if}}
 Today is {{date}}, and the current working directory is '{{cwd}}'.
 
 <critical>

package/src/prompts/system/subagent-async-pending.md

@@ -0,0 +1,6 @@
+Your yield was recorded, but {{count}} background job{{#if multiple}}s{{/if}} you own {{#if multiple}}are{{else}}is{{/if}} still running: {{jobs}}.
+
+This run completes only after these jobs settle AND you submit a fresh `yield` that accounts for their results. Job results arrive as follow-up messages; a result that arrives after your yield supersedes it — your current yield will NOT be accepted as the final report. Decide now:
+- Need the results? Wait for them (`hub` op:"wait"), then submit a fresh `yield` that incorporates them.
+- Job no longer needed? Cancel it (`hub` op:"cancel", ids:[…]) and re-yield.
+- Otherwise stand by; when each result arrives, submit a fresh `yield` (repeat your report unchanged if the result does not affect it).

package/src/prompts/system/system-prompt.md

@@ -101,7 +101,7 @@ Use tools whenever they improve correctness, completeness, or grounding.
 # Tool I/O
 - Prefer relative paths for `path`-like fields.
 {{#if intentTracing}}- Most tools take `{{intentField}}`: a concise intent, present participle, 2–6 words, no period, capitalized.{{/if}}
-{{#if secretsEnabled}}- Redacted `#XXXX#` tokens in output are opaque strings.{{/if}}
+{{#if secretsEnabled}}- Redacted `#HASH#`, `#HASH:CASE#`, or `#NAME_HASH:CASE#` tokens in output are opaque strings.{{/if}}
 {{#has tools "inspect_image"}}- Image tasks: prefer `{{toolRefs.inspect_image}}` over `{{toolRefs.read}}` to spare session context.{{/has}}
 
 # Specialized Tools

package/src/prompts/system/workflow-notice.md

@@ -28,56 +28,64 @@ For independent per-item chains (review → verify, fetch → extract → score)
 
 **Python (`eval`, Python backend):**
 
-    DIMENSIONS = [{"key": "bugs", "prompt": "…"}, {"key": "perf", "prompt": "…"}]
-    def review_and_verify(d):
-        found = agent(d["prompt"], label=f"review:{d['key']}", schema=FINDINGS_SCHEMA)
-        return parallel([lambda f=f: {**f, "verdict": agent(
-            f"Refute if you can (default refuted when unsure): {f['title']}",
-            label=f"verify:{f['file']}", schema=VERDICT_SCHEMA)} for f in found["findings"]])
-    phase("Review")
-    results = parallel([lambda d=d: review_and_verify(d) for d in DIMENSIONS])
-    confirmed = [f for group in results for f in group if f["verdict"]["is_real"]]
+```python
+DIMENSIONS = [{"key": "bugs", "prompt": "…"}, {"key": "perf", "prompt": "…"}]
+def review_and_verify(d):
+    found = agent(d["prompt"], label=f"review:{d['key']}", schema=FINDINGS_SCHEMA)
+    return parallel([lambda f=f: {**f, "verdict": agent(
+        f"Refute if you can (default refuted when unsure): {f['title']}",
+        label=f"verify:{f['file']}", schema=VERDICT_SCHEMA)} for f in found["findings"]])
+phase("Review")
+results = parallel([lambda d=d: review_and_verify(d) for d in DIMENSIONS])
+confirmed = [f for group in results for f in group if f["verdict"]["is_real"]]
+```
 
 **JavaScript (`eval`, JavaScript backend):**
 
-    const DIMENSIONS = [{ key: "bugs", prompt: "…" }, { key: "perf", prompt: "…" }];
-    async function reviewAndVerify(d) {
-        const found = await agent(d.prompt, {
-            label: `review:${d.key}`,
-            schema: FINDINGS_SCHEMA,
-        });
-        return await parallel(found.findings.map((f) => async () => ({
-            …f,
-            verdict: await agent(
-                `Refute if you can (default refuted when unsure): ${f.title}`,
-                { label: `verify:${f.file}`, schema: VERDICT_SCHEMA },
-            ),
-        })));
-    }
-    phase("Review");
-    const results = await parallel(DIMENSIONS.map((d) => async () => reviewAndVerify(d)));
-    const confirmed = results.flat().filter((f) => f.verdict.is_real);
+```js
+const DIMENSIONS = [{ key: "bugs", prompt: "…" }, { key: "perf", prompt: "…" }];
+async function reviewAndVerify(d) {
+    const found = await agent(d.prompt, {
+        label: `review:${d.key}`,
+        schema: FINDINGS_SCHEMA,
+    });
+    return await parallel(found.findings.map((f) => async () => ({
+        ...f,
+        verdict: await agent(
+            `Refute if you can (default refuted when unsure): ${f.title}`,
+            { label: `verify:${f.file}`, schema: VERDICT_SCHEMA },
+        ),
+    })));
+}
+phase("Review");
+const results = await parallel(DIMENSIONS.map((d) => async () => reviewAndVerify(d)));
+const confirmed = results.flat().filter((f) => f.verdict.is_real);
+```
 Reach for `pipeline()` only when a stage genuinely needs ALL of the previous stage first — dedup/merge across the whole set, early-exit on zero, or "compare against the other findings" — because its inter-stage barrier makes every item wait for the slowest peer:
 
 **Python (`eval`, Python backend):**
 
-    phase("Find")
-    found = parallel([lambda d=d: agent(d["prompt"], schema=FINDINGS_SCHEMA) for d in DIMENSIONS])
-    findings = dedupe([f for r in found for f in r["findings"]])   # needs everything at once
-    phase("Verify")
-    verdicts = parallel([lambda f=f: agent(verify_prompt(f), schema=VERDICT_SCHEMA) for f in findings])
+```python
+phase("Find")
+found = parallel([lambda d=d: agent(d["prompt"], schema=FINDINGS_SCHEMA) for d in DIMENSIONS])
+findings = dedupe([f for r in found for f in r["findings"]])   # needs everything at once
+phase("Verify")
+verdicts = parallel([lambda f=f: agent(verify_prompt(f), schema=VERDICT_SCHEMA) for f in findings])
+```
 
 **JavaScript (`eval`, JavaScript backend):**
 
-    phase("Find");
-    const found = await parallel(DIMENSIONS.map((d) => async () =>
-        await agent(d.prompt, { schema: FINDINGS_SCHEMA }),
-    ));
-    const findings = dedupe(found.flatMap((r) => r.findings)); // needs everything at once
-    phase("Verify");
-    const verdicts = await parallel(findings.map((f) => async () =>
-        await agent(verifyPrompt(f), { schema: VERDICT_SCHEMA }),
-    ));
+```js
+phase("Find");
+const found = await parallel(DIMENSIONS.map((d) => async () =>
+    await agent(d.prompt, { schema: FINDINGS_SCHEMA }),
+));
+const findings = dedupe(found.flatMap((r) => r.findings)); // needs everything at once
+phase("Verify");
+const verdicts = await parallel(findings.map((f) => async () =>
+    await agent(verifyPrompt(f), { schema: VERDICT_SCHEMA }),
+));
+```
 Use ordinary code between calls to flatten/map/filter; don't add a barrier just for that. Nested `parallel()` pools each cap independently, so keep total fan-out sane.
 </structure>
 

package/src/prompts/system/xdev-mount-notice.md

@@ -13,4 +13,8 @@ No longer mounted (writes to these devices will fail):
 - xd://{{this.name}}
 {{/each}}
 {{/if}}
+{{#if docs}}
+Configured inline device docs:
+{{docs}}
+{{/if}}
 </system-notice>

package/src/prompts/tools/todo.md

@@ -12,6 +12,8 @@ Completing tasks out of phase order can move this pointer **back** to an earlier
 |`start`|`task`|Mark in progress|
 |`done`|`task` or `phase`|Mark completed|
 |`drop`|`task` or `phase`|Mark abandoned|
+|`block`|`task` or `phase`, optional `reason`|Mark **blocked** — open but waiting on external input; excluded from the stop-time incomplete-todo reminder|
+|`unblock`|`task` or `phase`|Return a blocked task to `pending`|
 |`rm`|`task` or `phase` (optional)|Remove task or phase; omit both to clear|
 |`append`|`phase`, `items: string[]`|Append tasks to `phase`; lazily creates phase|
 |`view`|—|Read-only: echo list|
@@ -23,7 +25,7 @@ Completing tasks out of phase order can move this pointer **back** to an earlier
 ## Rules
 - Mark tasks done immediately after finishing. Complete phases in order.
 - NEVER make a todo call your turn's only tool call — batch it with the real work: `init` with the first reads/edits, each `done`/`start` with the next action. Solo todo turns waste a round trip.
-- Blocked? `append` a task to the active phase, or `drop`.
+- Waiting on something you can't act on (a user decision, another agent, an external service)? `block` the task (optional `reason`) — it stays in the tracker but won't trip the stop reminder; `unblock` when it's actionable again. If the blocker is itself agent-actionable, `append` an unblocking task instead.
 - Keep `task`/`phase` strings stable once introduced.
 - Lost the exact task text? `view` echoes the list — NEVER guess from memory.
 

package/src/registry/agent-lifecycle.ts

@@ -14,13 +14,23 @@
  * - ensureLive during an in-flight park either cancels the park (session still
  *   live) or waits for detach+park and then revives.
  * - Concurrent ensureLive/park operations coalesce per id.
+ *
+ * Every adoption, park, and revival is bound to the exact {@link AgentRef} it
+ * started from, so stale async work (a late finalizer, a cancelled initializer,
+ * a superseded revive) can never clobber a newer same-id ref.
  */
 
 import { logger } from "@oh-my-pi/pi-utils";
 import type { AgentSession } from "../session/agent-session";
-import { type AgentRef, AgentRegistry, MAIN_AGENT_ID, type RegistryEvent } from "./agent-registry";
+import {
+	type AgentRef,
+	type AgentRefExpectation,
+	AgentRegistry,
+	MAIN_AGENT_ID,
+	type RegistryEvent,
+} from "./agent-registry";
 
-export type AgentReviver = () => Promise<AgentSession>;
+export type AgentReviver = (expected: AgentRef) => Promise<AgentSession>;
 
 /**
  * Builds a reviver for a `parked` ref restored from disk (Agent Hub scan,
@@ -39,12 +49,15 @@ export interface AdoptOptions {
 }
 
 interface AdoptedAgent {
+	ref: AgentRef;
 	idleTtlMs: number;
 	revive?: AgentReviver;
 	timer?: NodeJS.Timeout;
 }
 
 interface ParkInFlight {
+	/** The exact ref this park was started for. */
+	ref: AgentRef;
 	/** Resolves when the park attempt finishes (success, cancel, or dispose error). */
 	promise: Promise<void>;
 	/** Cancel before the session is detached. Returns true if cancel took effect. */
@@ -55,6 +68,11 @@ interface ParkInFlight {
 	detached: boolean;
 }
 
+interface RevivingAgent {
+	ref: AgentRef;
+	promise: Promise<AgentSession>;
+}
+
 export class AgentLifecycleManager {
 	static #global: AgentLifecycleManager | undefined;
 
@@ -85,12 +103,13 @@ export class AgentLifecycleManager {
 	readonly #registry: AgentRegistry;
 	readonly #adopted = new Map<string, AdoptedAgent>();
 	/**
-	 * In-flight park attempts. A park is cancelable until the live session is
-	 * detached; after detach, ensureLive waits for the park and revives.
+	 * In-flight park attempts, each bound to the ref it started from. A park is
+	 * cancelable until the live session is detached; after detach, ensureLive
+	 * waits for the park and revives.
 	 */
 	readonly #parks = new Map<string, ParkInFlight>();
-	/** In-flight revives, so concurrent {@link ensureLive} calls coalesce. */
-	readonly #revivals = new Map<string, Promise<AgentSession>>();
+	/** In-flight revives, bound to the parked ref that initiated them, so concurrent {@link ensureLive} calls coalesce. */
+	readonly #revivals = new Map<string, RevivingAgent>();
 	#unsubscribe: (() => void) | undefined;
 	#persistedReviverFactory: PersistedSubagentReviverFactory | undefined;
 	/** TTL applied when a cold-revived ref is adopted on demand. */
@@ -115,23 +134,29 @@ export class AgentLifecycleManager {
 	/**
 	 * Take ownership of a finished subagent. Caller has already set registry
 	 * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+	 * When `expected` is given, the adoption is refused if the id no longer
+	 * resolves to that ref (or that ref's session).
 	 */
-	adopt(id: string, opts: AdoptOptions): void {
+	adopt(id: string, opts: AdoptOptions, expected?: AgentRefExpectation): void {
 		if (id === MAIN_AGENT_ID) return;
-		if (!this.#registry.get(id)) {
-			logger.warn("AgentLifecycleManager.adopt: unknown agent id", { id });
+		const ref = this.#registry.get(id);
+		if (!ref || (expected !== undefined && ref !== expected && ref.session !== expected)) {
+			logger.warn("AgentLifecycleManager.adopt: unknown or replaced agent id", { id });
 			return;
 		}
 		const existing = this.#adopted.get(id);
 		clearTimeout(existing?.timer);
-		const adopted: AdoptedAgent = { idleTtlMs: opts.idleTtlMs, revive: opts.revive };
+		const adopted: AdoptedAgent = { ref, idleTtlMs: opts.idleTtlMs, revive: opts.revive };
 		this.#adopted.set(id, adopted);
 		this.#armTimer(id, adopted);
 	}
 
-	/** True if the id is adopted (parked or live). */
-	has(id: string): boolean {
-		return this.#adopted.has(id);
+	/** True if the id is adopted (parked or live) — and, when `expected` is given, still bound to that ref. */
+	has(id: string, expected?: AgentRefExpectation): boolean {
+		const adopted = this.#adopted.get(id);
+		return Boolean(
+			adopted && (expected === undefined || adopted.ref === expected || adopted.ref.session === expected),
+		);
 	}
 
 	/**
@@ -147,11 +172,14 @@ export class AgentLifecycleManager {
 	/**
 	 * True while {@link park} is disposing this agent's session (lets dispose
 	 * hooks distinguish park from teardown). False once the park is cancelled
-	 * by ensureLive or after detach+dispose completes.
+	 * by ensureLive or after detach+dispose completes. When `expected` is
+	 * given, only a park bound to that ref (or its session) counts.
 	 */
-	isParking(id: string): boolean {
+	isParking(id: string, expected?: AgentRefExpectation): boolean {
 		const park = this.#parks.get(id);
-		return Boolean(park && !park.cancelled);
+		return Boolean(
+			park && !park.cancelled && (expected === undefined || park.ref === expected || park.ref.session === expected),
+		);
 	}
 
 	/**
@@ -170,7 +198,8 @@ export class AgentLifecycleManager {
 		const adopted = this.#adopted.get(id);
 		if (!adopted) return;
 		const ref = this.#registry.get(id);
-		const session = ref?.session;
+		if (!ref || adopted.ref !== ref) return;
+		const session = ref.session;
 		if (!session) return;
 
 		if (adopted.timer) {
@@ -180,6 +209,7 @@ export class AgentLifecycleManager {
 
 		let cancelled = false;
 		const park: ParkInFlight = {
+			ref,
 			promise: undefined as unknown as Promise<void>,
 			cancel: () => {
 				// Cancel only before detach — once detached the old session is already
@@ -200,16 +230,16 @@ export class AgentLifecycleManager {
 				await Promise.resolve();
 				if (cancelled) return;
 
-				// Re-check liveness: release/unregister may have raced us.
+				// Re-check liveness: release/unregister/replace may have raced us.
 				const live = this.#registry.get(id);
-				if (!live?.session || live.session !== session) return;
-				if (!this.#adopted.has(id)) return;
+				if (live !== ref || !live.session || live.session !== session) return;
+				if (this.#adopted.get(id)?.ref !== ref) return;
 
 				// Commit: detach + parked *before* dispose so callers never see a
 				// dying session via ref.session / idle status.
 				park.detached = true;
-				this.#registry.detachSession(id);
-				this.#registry.setStatus(id, "parked");
+				this.#registry.detachSession(id, ref);
+				this.#registry.setStatus(id, "parked", ref);
 
 				try {
 					await session.dispose();
@@ -238,16 +268,16 @@ export class AgentLifecycleManager {
 	async ensureLive(id: string): Promise<AgentSession> {
 		const park = this.#parks.get(id);
 		if (park) {
-			const ref = this.#registry.get(id);
+			const parked = this.#registry.get(id);
 			// Cancel if the live session is still attached — keep it instead of
 			// thrashing dispose + revive.
-			if (ref?.session && !park.detached && park.cancel()) {
+			if (parked?.session && !park.detached && park.cancel()) {
 				await park.promise;
 				const kept = this.#registry.get(id)?.session;
 				if (kept) {
 					// Park cleared the idle timer; re-arm so TTL park still works.
 					const adopted = this.#adopted.get(id);
-					if (adopted && ref.status === "idle") this.#armTimer(id, adopted);
+					if (adopted && adopted.ref === parked && parked.status === "idle") this.#armTimer(id, adopted);
 					return kept;
 				}
 			} else {
@@ -265,13 +295,14 @@ export class AgentLifecycleManager {
 		}
 		if (ref.session) return ref.session;
 		const inflight = this.#revivals.get(id);
-		if (inflight) return inflight;
+		if (inflight?.ref === ref) return inflight.promise;
 		const revival = this.#resolveAndRevive(id, ref);
-		this.#revivals.set(id, revival);
+		const pending: RevivingAgent = { ref, promise: revival };
+		this.#revivals.set(id, pending);
 		try {
 			return await revival;
 		} finally {
-			this.#revivals.delete(id);
+			if (this.#revivals.get(id) === pending) this.#revivals.delete(id);
 		}
 	}
 
@@ -283,53 +314,72 @@ export class AgentLifecycleManager {
 	 * when the agent is not revivable or no reviver can be produced.
 	 */
 	async #resolveAndRevive(id: string, ref: AgentRef): Promise<AgentSession> {
-		let revive = this.#adopted.get(id)?.revive;
+		let adoption = this.#adopted.get(id);
+		let revive = adoption?.ref === ref ? adoption.revive : undefined;
 		let coldAdopted = false;
 		if (!revive && ref.status === "parked" && ref.sessionFile && this.#persistedReviverFactory) {
 			revive = await this.#persistedReviverFactory(ref);
 			if (revive) {
-				this.#adopted.set(id, { idleTtlMs: this.#persistedReviveTtlMs, revive });
+				adoption = { ref, idleTtlMs: this.#persistedReviveTtlMs, revive };
+				this.#adopted.set(id, adoption);
 				coldAdopted = true;
 			}
 		}
-		if (ref.status !== "parked" || !revive) {
+		if (this.#registry.get(id) !== ref) {
+			throw new Error(`Agent "${id}" changed while its persisted session was being prepared.`);
+		}
+		if (ref.status !== "parked" || !revive || !adoption) {
 			throw new Error(
 				`Agent "${id}" is ${ref.status} and cannot be revived${revive ? "" : " (no reviver registered)"}. Its transcript remains readable at history://${id}.`,
 			);
 		}
 		try {
-			return await this.#revive(id, revive, ref.sessionFile);
+			return await this.#revive(id, revive, ref, adoption);
 		} catch (error) {
 			// A failed cold revive (stale ctx, missing cwd, bad MCP) must not leave a
 			// poisoned reviver stuck in #adopted — drop it so a later ensureLive
 			// rebuilds via the factory (which may have fresher context by then).
-			if (coldAdopted) this.#adopted.delete(id);
+			if (coldAdopted && this.#adopted.get(id) === adoption) this.#adopted.delete(id);
 			throw error;
 		}
 	}
 
-	/** Hard removal: dispose if live, unregister from registry, drop timers. */
-	async release(id: string): Promise<void> {
+	/**
+	 * Hard removal: dispose if live, unregister from registry, drop timers.
+	 * When `expected` is given, only a ref matching it is released; a stale
+	 * release can never take down a newer same-id ref. Returns true when a
+	 * matching ref was released.
+	 */
+	async release(id: string, expected?: AgentRefExpectation): Promise<boolean> {
 		const adopted = this.#adopted.get(id);
-		clearTimeout(adopted?.timer);
-		this.#adopted.delete(id);
+		const current = this.#registry.get(id);
+		const currentMatches =
+			current && (expected === undefined || current === expected || current.session === expected);
+		const adoptedMatches =
+			adopted && (expected === undefined || adopted.ref === expected || adopted.ref.session === expected);
+		const ref = currentMatches ? current : adoptedMatches ? adopted.ref : undefined;
+		if (!ref) return false;
+		if (adopted?.ref === ref) {
+			clearTimeout(adopted.timer);
+			this.#adopted.delete(id);
+		}
 
 		const park = this.#parks.get(id);
-		if (park) {
+		if (park && park.ref === ref) {
 			// Prefer cancel when the session is still live so release owns dispose.
 			if (!park.detached) park.cancel();
 			await park.promise;
 		}
 
-		const ref = this.#registry.get(id);
-		if (ref?.session) {
+		if (this.#registry.get(id) === ref && ref.session) {
 			try {
 				await ref.session.dispose();
 			} catch (error) {
 				logger.warn("AgentLifecycleManager.release: session dispose failed", { id, error: String(error) });
 			}
 		}
-		this.#registry.unregister(id);
+		this.#registry.unregister(id, ref);
+		return true;
 	}
 
 	/** Teardown everything (process exit / main session dispose). */
@@ -343,11 +393,31 @@ export class AgentLifecycleManager {
 		this.#persistedReviverFactory = undefined;
 	}
 
-	async #revive(id: string, revive: AgentReviver, sessionFile: string | null): Promise<AgentSession> {
-		const session = await revive();
-		this.#registry.attachSession(id, session, sessionFile);
+	async #revive(id: string, revive: AgentReviver, ref: AgentRef, adopted: AdoptedAgent): Promise<AgentSession> {
+		const session = await revive(ref);
+		let liveRef = this.#registry.get(id);
+		if (liveRef === ref) {
+			if (!this.#registry.attachSession(id, session, ref.sessionFile, ref)) {
+				await session.dispose();
+				throw new Error(`Agent "${id}" changed before its persisted session could attach.`);
+			}
+			liveRef = ref;
+		} else if (
+			!liveRef ||
+			liveRef.session !== session ||
+			liveRef.kind !== ref.kind ||
+			liveRef.parentId !== ref.parentId ||
+			liveRef.sessionFile !== ref.sessionFile
+		) {
+			await session.dispose();
+			throw new Error(`Agent "${id}" was replaced while its persisted session was reviving.`);
+		}
+		adopted.ref = liveRef;
 		// Emits status_changed → "idle", which re-arms the TTL timer below.
-		this.#registry.setStatus(id, "idle");
+		if (!this.#registry.setStatus(id, "idle", liveRef)) {
+			await session.dispose();
+			throw new Error(`Agent "${id}" changed before its persisted session became idle.`);
+		}
 		return session;
 	}
 
@@ -364,7 +434,7 @@ export class AgentLifecycleManager {
 
 	#onRegistryEvent(event: RegistryEvent): void {
 		const adopted = this.#adopted.get(event.ref.id);
-		if (!adopted) return;
+		if (!adopted || adopted.ref !== event.ref) return;
 		if (event.type === "removed") {
 			clearTimeout(adopted.timer);
 			this.#adopted.delete(event.ref.id);