pi-agent-zh 17.1.8

package/src/registry/agent-lifecycle.ts

@@ -0,0 +1,455 @@
+/**
+ * AgentLifecycleManager - Owns the idle → parked → revived lifecycle of
+ * adopted subagents.
+ *
+ * The task executor hands a finished agent over via {@link AgentLifecycleManager.adopt};
+ * from then on the manager arms a TTL timer whenever the agent goes `idle`,
+ * parks it on expiry (disposes the live session, keeps the AgentRef +
+ * sessionFile), and revives it on demand through
+ * {@link AgentLifecycleManager.ensureLive}. Only this manager flips
+ * `parked` ↔ `idle`.
+ *
+ * Park/dispose is gated against concurrent ensureLive/hub-send:
+ * - A disposing session is never handed out.
+ * - 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,
+	type AgentRefExpectation,
+	AgentRegistry,
+	MAIN_AGENT_ID,
+	type RegistryEvent,
+} from "./agent-registry";
+
+export type AgentReviver = (expected: AgentRef) => Promise<AgentSession>;
+
+/**
+ * Builds a reviver for a `parked` ref restored from disk (Agent Hub scan,
+ * collab mirror, resumed process) that carries a sessionFile but no in-memory
+ * adoption. Returns undefined when the ref cannot be faithfully rebuilt (no
+ * persisted session contract, or its workspace is gone). Injected from the
+ * top-level session so this manager stays free of sdk/SessionManager imports.
+ */
+export type PersistedSubagentReviverFactory = (ref: AgentRef) => Promise<AgentReviver | undefined>;
+
+export interface AdoptOptions {
+	/** TTL before an idle agent is parked. <= 0 disables parking. */
+	idleTtlMs: number;
+	/** Recreates a live AgentSession from the ref's sessionFile. Absent => not resumable after park (e.g. isolated runs). */
+	revive?: AgentReviver;
+}
+
+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. */
+	cancel: () => boolean;
+	/** True once cancel() succeeded (ensureLive kept the live session). */
+	cancelled: boolean;
+	/** True once the live session has been detached and status is parked. */
+	detached: boolean;
+}
+
+interface RevivingAgent {
+	ref: AgentRef;
+	promise: Promise<AgentSession>;
+}
+
+export class AgentLifecycleManager {
+	static #global: AgentLifecycleManager | undefined;
+
+	static global(): AgentLifecycleManager {
+		if (!AgentLifecycleManager.#global) {
+			AgentLifecycleManager.#global = new AgentLifecycleManager();
+		}
+		return AgentLifecycleManager.#global;
+	}
+
+	/** Reset the global manager. Test-only. */
+	static resetGlobalForTests(): void {
+		const current = AgentLifecycleManager.#global;
+		if (current) {
+			current.#unsubscribe?.();
+			current.#unsubscribe = undefined;
+			for (const adopted of current.#adopted.values()) {
+				clearTimeout(adopted.timer);
+			}
+			current.#adopted.clear();
+			current.#revivals.clear();
+			current.#parks.clear();
+			current.#persistedReviverFactory = undefined;
+		}
+		AgentLifecycleManager.#global = undefined;
+	}
+
+	readonly #registry: AgentRegistry;
+	readonly #adopted = new Map<string, AdoptedAgent>();
+	/**
+	 * 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, 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. */
+	#persistedReviveTtlMs = 0;
+
+	constructor(registry: AgentRegistry = AgentRegistry.global()) {
+		this.#registry = registry;
+		this.#unsubscribe = registry.onChange(event => this.#onRegistryEvent(event));
+	}
+
+	/**
+	 * Install the factory used to cold-revive `parked` refs restored from disk
+	 * (Agent Hub scan, collab mirror, resumed process) — they carry a sessionFile
+	 * but no adoption. Set by the top-level session, which owns the ambient deps
+	 * (auth, models, MCP, artifacts) the factory needs at revive time.
+	 */
+	setPersistedSubagentReviverFactory(factory: PersistedSubagentReviverFactory, idleTtlMs: number): void {
+		this.#persistedReviverFactory = factory;
+		this.#persistedReviveTtlMs = idleTtlMs;
+	}
+
+	/**
+	 * 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, expected?: AgentRefExpectation): void {
+		if (id === MAIN_AGENT_ID) return;
+		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 = { 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) — 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),
+		);
+	}
+
+	/**
+	 * True when this manager owns `registry` — i.e. its adopt/park/revive state
+	 * describes that registry's refs. Lets a caller holding a specific registry
+	 * (e.g. a custom-registry {@link IrcBus} that fell back to the global
+	 * manager) skip lifecycle gating that would consult unrelated park state.
+	 */
+	manages(registry: AgentRegistry): boolean {
+		return this.#registry === registry;
+	}
+
+	/**
+	 * 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. When `expected` is
+	 * given, only a park bound to that ref (or its session) counts.
+	 */
+	isParking(id: string, expected?: AgentRefExpectation): boolean {
+		const park = this.#parks.get(id);
+		return Boolean(
+			park && !park.cancelled && (expected === undefined || park.ref === expected || park.ref.session === expected),
+		);
+	}
+
+	/**
+	 * Dispose the live session, detach it from the registry, and mark the
+	 * agent `parked`. No-op unless the id is adopted and live.
+	 *
+	 * The session is detached (and status flipped to `parked`) *before*
+	 * `session.dispose()` so concurrent {@link ensureLive}/hub-send never
+	 * observe or inject into a disposing session. A concurrent ensureLive that
+	 * arrives before detach cancels the park and keeps the live session.
+	 */
+	async park(id: string): Promise<void> {
+		const existing = this.#parks.get(id);
+		if (existing) return existing.promise;
+
+		const adopted = this.#adopted.get(id);
+		if (!adopted) return;
+		const ref = this.#registry.get(id);
+		if (!ref || adopted.ref !== ref) return;
+		const session = ref.session;
+		if (!session) return;
+
+		if (adopted.timer) {
+			clearTimeout(adopted.timer);
+			adopted.timer = undefined;
+		}
+
+		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
+				// leaving the registry and must finish disposing.
+				if (park.detached || cancelled) return cancelled;
+				cancelled = true;
+				park.cancelled = true;
+				return true;
+			},
+			cancelled: false,
+			detached: false,
+		};
+
+		park.promise = (async () => {
+			try {
+				// Yield so a same-tick ensureLive/hub-send can cancel before we
+				// commit to dispose. Deterministic with Promise microtasks; no timers.
+				await Promise.resolve();
+				if (cancelled) return;
+
+				// Re-check liveness: release/unregister/replace may have raced us.
+				const live = this.#registry.get(id);
+				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, ref);
+				this.#registry.setStatus(id, "parked", ref);
+
+				try {
+					await session.dispose();
+				} catch (error) {
+					logger.warn("AgentLifecycleManager.park: session dispose failed", { id, error: String(error) });
+				}
+			} finally {
+				// Only clear if we are still the in-flight entry (a later park would
+				// have replaced us only after we resolved).
+				if (this.#parks.get(id) === park) this.#parks.delete(id);
+			}
+		})();
+
+		this.#parks.set(id, park);
+		return park.promise;
+	}
+
+	/**
+	 * Return the live session, reviving from the sessionFile if parked.
+	 * Throws a plain Error if the id is unknown or parked without a reviver.
+	 * Concurrent calls share one in-flight revive.
+	 *
+	 * Never returns a session that is mid-dispose: an in-flight park is either
+	 * cancelled (session still live) or awaited to completion before revive.
+	 */
+	async ensureLive(id: string): Promise<AgentSession> {
+		const park = this.#parks.get(id);
+		if (park) {
+			const parked = this.#registry.get(id);
+			// Cancel if the live session is still attached — keep it instead of
+			// thrashing dispose + revive.
+			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 && adopted.ref === parked && parked.status === "idle") this.#armTimer(id, adopted);
+					return kept;
+				}
+			} else {
+				// Already committed to detach (or no live session): wait for park,
+				// then fall through to the revive path.
+				await park.promise;
+			}
+		}
+
+		const ref = this.#registry.get(id);
+		if (!ref) {
+			throw new Error(
+				`Unknown agent "${id}" — it was never registered or has been released. If a transcript exists, read history://${id}.`,
+			);
+		}
+		if (ref.session) return ref.session;
+		const inflight = this.#revivals.get(id);
+		if (inflight?.ref === ref) return inflight.promise;
+		const revival = this.#resolveAndRevive(id, ref);
+		const pending: RevivingAgent = { ref, promise: revival };
+		this.#revivals.set(id, pending);
+		try {
+			return await revival;
+		} finally {
+			if (this.#revivals.get(id) === pending) this.#revivals.delete(id);
+		}
+	}
+
+	/**
+	 * Resolve a reviver and bring the agent back to a live session. A ref
+	 * restored from disk is `parked` with a sessionFile but no in-memory
+	 * adoption; build a reviver via the injected persisted-subagent factory and
+	 * adopt it so the agent rejoins the normal idle↔parked lifecycle. Throws
+	 * when the agent is not revivable or no reviver can be produced.
+	 */
+	async #resolveAndRevive(id: string, ref: AgentRef): Promise<AgentSession> {
+		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) {
+				adoption = { ref, idleTtlMs: this.#persistedReviveTtlMs, revive };
+				this.#adopted.set(id, adoption);
+				coldAdopted = true;
+			}
+		}
+		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, 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.get(id) === adoption) this.#adopted.delete(id);
+			throw error;
+		}
+	}
+
+	/**
+	 * 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);
+		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 && park.ref === ref) {
+			// Prefer cancel when the session is still live so release owns dispose.
+			if (!park.detached) park.cancel();
+			await park.promise;
+		}
+
+		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, ref);
+		return true;
+	}
+
+	/** Teardown everything (process exit / main session dispose). */
+	async dispose(): Promise<void> {
+		this.#unsubscribe?.();
+		this.#unsubscribe = undefined;
+		const ids = [...new Set([...this.#adopted.keys(), ...this.#parks.keys()])];
+		await Promise.all(ids.map(id => this.release(id)));
+		this.#revivals.clear();
+		this.#parks.clear();
+		this.#persistedReviverFactory = undefined;
+	}
+
+	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.
+		if (!this.#registry.setStatus(id, "idle", liveRef)) {
+			await session.dispose();
+			throw new Error(`Agent "${id}" changed before its persisted session became idle.`);
+		}
+		return session;
+	}
+
+	#armTimer(id: string, adopted: AdoptedAgent): void {
+		if (adopted.idleTtlMs <= 0) return;
+		clearTimeout(adopted.timer);
+		const timer = setTimeout(() => {
+			adopted.timer = undefined;
+			void this.park(id);
+		}, adopted.idleTtlMs);
+		timer.unref?.();
+		adopted.timer = timer;
+	}
+
+	#onRegistryEvent(event: RegistryEvent): void {
+		const adopted = this.#adopted.get(event.ref.id);
+		if (!adopted || adopted.ref !== event.ref) return;
+		if (event.type === "removed") {
+			clearTimeout(adopted.timer);
+			this.#adopted.delete(event.ref.id);
+			return;
+		}
+		if (event.type !== "status_changed") return;
+		if (event.ref.status === "running") {
+			if (adopted.timer) {
+				clearTimeout(adopted.timer);
+				adopted.timer = undefined;
+			}
+		} else if (event.ref.status === "idle") {
+			// Don't re-arm while a park is in flight — the park owns the transition.
+			if (this.#parks.has(event.ref.id)) return;
+			this.#armTimer(event.ref.id, adopted);
+		}
+	}
+}

package/src/registry/agent-registry.ts

@@ -0,0 +1,217 @@
+/**
+ * AgentRegistry - Process-global registry of agents (the main session plus
+ * every subagent), keyed by stable id.
+ *
+ * Tracks each agent's status and (when live) its AgentSession so peers can be
+ * addressed by id (`hub`, `task resume`, `history://`). Sessions are
+ * registered explicitly at creation; finished agents stay registered as
+ * `idle` (live) or `parked` (session disposed, ref + sessionFile retained for
+ * revival) and are only removed on explicit release/teardown.
+ */
+
+import type { AgentSession } from "../session/agent-session";
+import { oneLineLabel } from "../task/types";
+
+export const MAIN_AGENT_ID = "Main";
+
+/**
+ * - `running`: a turn is in flight.
+ * - `idle`: live AgentSession in memory, awaiting work. Finished agents are
+ *   `idle`, not removed.
+ * - `parked`: session disposed; AgentRef + sessionFile retained, revivable.
+ * - `aborted`: hard-killed, terminal.
+ */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
+/**
+ * - `main`/`sub`: the user-facing agent tree (driving agent + task subagents).
+ * - `advisor`: a passive review transcript persisted like a subagent for usage
+ *   attribution and Agent Hub observability, but never a peer — hidden from
+ *   agent-facing rosters (`hub`, `history://`) and not messageable/revivable.
+ */
+export type AgentKind = "main" | "sub" | "advisor";
+
+export interface AgentRef {
+	id: string;
+	displayName: string;
+	kind: AgentKind;
+	parentId?: string;
+	status: AgentStatus;
+	/** Null exactly when parked/aborted. */
+	session: AgentSession | null;
+	sessionFile: string | null;
+	createdAt: number;
+	lastActivity: number;
+	/** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
+	activity?: string;
+}
+
+export type AgentRefExpectation = AgentRef | AgentSession;
+
+export type RegistryEvent =
+	| { type: "registered"; ref: AgentRef }
+	| { type: "status_changed"; ref: AgentRef }
+	| { type: "removed"; ref: AgentRef };
+
+type RegistryListener = (event: RegistryEvent) => void;
+
+export interface RegisterInput {
+	id: string;
+	displayName: string;
+	kind: AgentKind;
+	parentId?: string;
+	session: AgentSession | null;
+	sessionFile?: string | null;
+	status?: AgentStatus;
+}
+
+export class AgentRegistry {
+	static #global: AgentRegistry | undefined;
+
+	static global(): AgentRegistry {
+		if (!AgentRegistry.#global) {
+			AgentRegistry.#global = new AgentRegistry();
+		}
+		return AgentRegistry.#global;
+	}
+
+	/** Reset the global registry. Test-only. */
+	static resetGlobalForTests(): void {
+		AgentRegistry.#global = new AgentRegistry();
+	}
+
+	readonly #refs = new Map<string, AgentRef>();
+	readonly #listeners = new Set<RegistryListener>();
+
+	#matchesExpected(ref: AgentRef, expected?: AgentRefExpectation): boolean {
+		return expected === undefined || ref === expected || ref.session === expected;
+	}
+
+	register(input: RegisterInput): AgentRef {
+		const now = Date.now();
+		const ref: AgentRef = {
+			id: input.id,
+			displayName: input.displayName,
+			kind: input.kind,
+			parentId: input.parentId,
+			status: input.status ?? "running",
+			session: input.session,
+			sessionFile: input.sessionFile ?? null,
+			createdAt: now,
+			lastActivity: now,
+		};
+		this.#refs.set(ref.id, ref);
+		this.#emit({ type: "registered", ref });
+		return ref;
+	}
+
+	/**
+	 * Register a new id only when it is absent, or reuse the exact ref a parked
+	 * revival was authorized to revive. A missing expected ref is a failed CAS:
+	 * callers must never claim an id after its prior generation disappeared.
+	 */
+	registerIfAvailable(input: RegisterInput, expected: AgentRef | null): AgentRef | undefined {
+		const current = this.#refs.get(input.id);
+		if (expected === null) return current ? undefined : this.register(input);
+		return current === expected ? current : undefined;
+	}
+
+	setStatus(id: string, status: AgentStatus, expected?: AgentRefExpectation): boolean {
+		const ref = this.#refs.get(id);
+		if (!ref || !this.#matchesExpected(ref, expected)) return false;
+		if (ref.status === status) return true;
+		ref.status = status;
+		// Activity describes current work; it is meaningless once the agent
+		// leaves `running`, so drop it to avoid showing stale work in rosters.
+		if (status !== "running") ref.activity = undefined;
+		ref.lastActivity = Date.now();
+		this.#emit({ type: "status_changed", ref });
+		return true;
+	}
+
+	/**
+	 * Record a short activity gist for the work-aware roster. Display-only and
+	 * read on demand (`irc list`, peer roster), so it emits no event — keeping
+	 * the per-tool-call update rate off the registry listener path (same as
+	 * `attachSession`, which also bumps `lastActivity` without emitting). Only a
+	 * `running` agent has current work: a heartbeat for any other status is
+	 * dropped, so a late progress flush can't resurrect activity on a ref that
+	 * `setStatus` just cleared. Every running heartbeat refreshes `lastActivity`
+	 * — even when the gist text is unchanged — so the roster's "active … ago" and
+	 * recency sort track real work, not just the last status change.
+	 * The gist is normalized to one bounded line (`oneLineLabel`) so model-derived
+	 * intent text can neither break the roster nor smuggle terminal escapes —
+	 * every caller is safe without sanitizing at its own call site.
+	 */
+	setActivity(id: string, activity: string): void {
+		const ref = this.#refs.get(id);
+		if (!ref) return;
+		if (ref.status !== "running") return;
+		const gist = oneLineLabel(activity);
+		ref.lastActivity = Date.now();
+		if (ref.activity === gist) return;
+		ref.activity = gist;
+	}
+
+	attachSession(
+		id: string,
+		session: AgentSession,
+		sessionFile?: string | null,
+		expected?: AgentRefExpectation,
+	): boolean {
+		const ref = this.#refs.get(id);
+		if (!ref || !this.#matchesExpected(ref, expected)) return false;
+		ref.session = session;
+		if (sessionFile !== undefined) ref.sessionFile = sessionFile;
+		ref.lastActivity = Date.now();
+		return true;
+	}
+
+	detachSession(id: string, expected?: AgentRefExpectation): boolean {
+		const ref = this.#refs.get(id);
+		if (!ref || !this.#matchesExpected(ref, expected)) return false;
+		ref.session = null;
+		return true;
+	}
+
+	unregister(id: string, expected?: AgentRefExpectation): boolean {
+		const ref = this.#refs.get(id);
+		if (!ref || !this.#matchesExpected(ref, expected)) return false;
+		this.#refs.delete(id);
+		this.#emit({ type: "removed", ref });
+		return true;
+	}
+
+	get(id: string): AgentRef | undefined {
+		return this.#refs.get(id);
+	}
+
+	list(): AgentRef[] {
+		return [...this.#refs.values()];
+	}
+
+	/**
+	 * Returns every alive agent (running | idle) except the caller. Advisor refs
+	 * are observability-only transcripts, never peers, so they are excluded.
+	 * Flat namespace: every other agent is visible.
+	 */
+	listVisibleTo(id: string): AgentRef[] {
+		return this.list().filter(
+			ref => ref.id !== id && ref.kind !== "advisor" && (ref.status === "running" || ref.status === "idle"),
+		);
+	}
+
+	onChange(listener: RegistryListener): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	#emit(event: RegistryEvent): void {
+		for (const listener of this.#listeners) {
+			try {
+				listener(event);
+			} catch {
+				// listeners must not break the dispatch loop
+			}
+		}
+	}
+}