@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/domains/middleware/hooks.ts

@@ -51,12 +51,47 @@ export const USER_HOOK_COMMAND_OUTPUT_MAX_CHARS = 4_000;
 /** Cap on a prompt hook's injected message, in characters. */
 export const USER_HOOK_PROMPT_MAX_CHARS = 2_000;
 
+/**
+ * Provenance of an installed package that supplied hook declarations, as the
+ * composition root attributes it. Middleware treats it as opaque identity
+ * data; it neither reads packages nor knows how the digests were produced.
+ */
+export interface UserHookPackageProvenance {
+	id: string;
+	/** Install scope label of the package (for example "user" or "project"). */
+	scope: string;
+	/** Path recorded at install, when known. */
+	sourcePath?: string;
+	/** Canonical filesystem identity of the installed package root. */
+	canonicalRoot: string;
+	/** SHA-256 of the manifest bytes covered by the installed-tree digest. */
+	manifestDigest: string;
+	/** Installed-tree digest recorded at install and reverified by the supplier. */
+	contentDigest: string;
+}
+
+/**
+ * Attribution for a hook declared by an installed package. The declaration
+ * bytes behind `declarationsDigest` are the ones the supplier hashed during
+ * content verification and captured; nothing here was re-read from a mutable
+ * path after verification.
+ */
+export interface UserHookExtensionSource {
+	provenance: UserHookPackageProvenance;
+	/** Generation the declarations were admitted under; 0 for an ephemeral build. */
+	generation: number;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+}
+
 export interface UserHookSource {
 	origin: UserHookOrigin;
 	/** File path or `extensionId:path` the declaration was read from. */
 	sourcePath: string;
 	/** Extension id when origin is "extension". */
 	sourceId?: string;
+	/** Present exactly when origin is "extension". */
+	extension?: UserHookExtensionSource;
 }
 
 export interface NormalizedCommandHook {
@@ -314,6 +349,17 @@ export function loadUserHooks(
 
 export type UserHookOutcome = "emitted" | "command-ok" | "command-failed" | "command-timeout" | "skipped";
 
+/** Bounded extension attribution carried on every receipt of an extension hook. */
+export interface HookReceiptExtension {
+	id: string;
+	scope: string;
+	canonicalRoot: string;
+	manifestDigest: string;
+	contentDigest: string;
+	declarationsDigest: string;
+	generation: number;
+}
+
 export interface HookReceipt {
 	at: number;
 	hookId: string;
@@ -327,6 +373,7 @@ export interface HookReceipt {
 	exitCode?: number;
 	outputChars?: number;
 	toolName?: string;
+	extension?: HookReceiptExtension;
 }
 
 export type HookReceiptSink = (receipt: HookReceipt) => void;
@@ -372,6 +419,10 @@ export function userHookToRegistration(
 	deps: UserHookRegistrationDeps,
 ): MiddlewareHookRegistration {
 	const now = deps.now ?? Date.now;
+	// Attribution is fixed when the registration is built, so a receipt written
+	// by a registration from an older generation names that generation even
+	// after a newer one is active.
+	const extension = hook.source.extension === undefined ? undefined : receiptExtension(hook.source.extension);
 	const baseReceipt = (input: { toolName?: string }): Omit<HookReceipt, "outcome"> => ({
 		at: now(),
 		hookId: hook.id,
@@ -380,6 +431,7 @@ export function userHookToRegistration(
 		hash: hook.hash,
 		hook: hook.on,
 		kind: hook.spec.kind,
+		...(extension !== undefined ? { extension: { ...extension } } : {}),
 		...(input.toolName !== undefined ? { toolName: input.toolName } : {}),
 	});
 	const registration: MiddlewareHookRegistration = {
@@ -401,6 +453,18 @@ export function userHookToRegistration(
 	return registration;
 }
 
+function receiptExtension(source: UserHookExtensionSource): HookReceiptExtension {
+	return {
+		id: source.provenance.id,
+		scope: source.provenance.scope,
+		canonicalRoot: source.provenance.canonicalRoot,
+		manifestDigest: source.provenance.manifestDigest,
+		contentDigest: source.provenance.contentDigest,
+		declarationsDigest: source.declarationsDigest,
+		generation: source.generation,
+	};
+}
+
 function evaluateHook(
 	hook: NormalizedUserHook,
 	deps: UserHookRegistrationDeps,

package/src/domains/middleware/index.ts

@@ -41,19 +41,27 @@ export {
 } from "./dispatch-nudge.js";
 export type { MiddlewareBundleOptions } from "./extension.js";
 export { createEnvHookBudgetTracker, createMiddlewareBundle } from "./extension.js";
-export { createHookReceiptLog, HOOK_RECEIPT_LOG_CAPACITY, type HookReceiptLog } from "./hook-receipts.js";
+export {
+	createHookReceiptLog,
+	HOOK_RECEIPT_LOG_CAPACITY,
+	type HookReceiptLog,
+	readPersistedHookReceipts,
+} from "./hook-receipts.js";
 export type {
 	HookReceipt,
+	HookReceiptExtension,
 	HookReceiptSink,
 	NormalizedUserHook,
 	UserHookCommandResult,
 	UserHookCommandRunner,
 	UserHookDeclarationBatch,
+	UserHookExtensionSource,
 	UserHookKind,
 	UserHookLoadIssue,
 	UserHookLoadResult,
 	UserHookOrigin,
 	UserHookOutcome,
+	UserHookPackageProvenance,
 	UserHookSource,
 } from "./hooks.js";
 export {
@@ -66,10 +74,12 @@ export {
 	userHookToRegistration,
 } from "./hooks.js";
 export {
-	type ExtensionHookRoot,
+	type BuildUserHookRegistrationsOptions,
+	type BuildUserHookRegistrationsResult,
+	buildUserHookRegistrations,
+	type CapturedHookDeclarations,
+	type CapturedHookSourceSet,
 	type HookFileIssue,
-	type InstallUserHooksResult,
-	installUserHooks,
 	readHookSources,
 	spawnSyncCommandRunner,
 } from "./hooks-io.js";
@@ -89,6 +99,19 @@ export {
 	type MemoryInterventionDeps,
 } from "./memory-intervention.js";
 export { announceMemoryStepEndpoint, type MemoryStepEndpointAnnouncerDeps } from "./memory-step-endpoint.js";
+export {
+	createMiddlewareRegistrationTable,
+	MIDDLEWARE_REGISTRATION_OWNERS,
+	type MiddlewareRegistrationConflict,
+	type MiddlewareRegistrationConflictTier,
+	type MiddlewareRegistrationOwner,
+	type MiddlewareRegistrationReplacement,
+	type MiddlewareRegistrationTable,
+	type MiddlewareRegistrationTableOptions,
+	type PrepareRegistrationReplacementResult,
+	type ReplaceRegistrationsRejection,
+	type ReplaceRegistrationsReport,
+} from "./registrations.js";
 export { BUILTIN_MIDDLEWARE_RULE_IDS, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
 export type {
 	MiddlewareDiagnostic,
@@ -99,6 +122,7 @@ export type {
 	RunMiddlewareRegistrationsOptions,
 } from "./runtime.js";
 export {
+	formatRegistrationConflict,
 	registrationFromRuleDefinition,
 	runMiddlewareHook,
 	runMiddlewareRegistrations,

package/src/domains/middleware/registrations.ts

@@ -0,0 +1,326 @@
+/**
+ * Ordered, copy-on-write registration table behind a middleware contract.
+ *
+ * Three tiers share one id namespace and one evaluation list:
+ *
+ *   - fixed: declarative rules (builtin plus composition-root definitions),
+ *     immutable for the life of the contract and always evaluated first;
+ *   - host: coded registrations appended by the composition root through
+ *     registerHook, append-only, first id wins;
+ *   - owned: registration sets replaced as one unit by an owner under a
+ *     strictly increasing generation. Today the only owner is "user-hooks".
+ *
+ * The whole table is one immutable state object held behind a single
+ * reference. Every writer computes a complete next state and publishes it
+ * with one assignment; readers capture the reference once per evaluation, so
+ * an evaluation that started before a publish finishes against the state it
+ * started with, including across an await. Preparation never runs user code:
+ * conflicts are returned as frozen data and a caller emits them through the
+ * diagnostic sink only after publication.
+ */
+
+import type { MiddlewareDiagnostic, MiddlewareDiagnosticSink, MiddlewareHookRegistration } from "./runtime.js";
+
+export const MIDDLEWARE_REGISTRATION_OWNERS = ["user-hooks"] as const;
+
+export type MiddlewareRegistrationOwner = (typeof MIDDLEWARE_REGISTRATION_OWNERS)[number];
+
+export type MiddlewareRegistrationConflictTier = "builtin" | "host" | "owned";
+
+export interface MiddlewareRegistrationConflict {
+	id: string;
+	conflictsWith: MiddlewareRegistrationConflictTier;
+}
+
+export type ReplaceRegistrationsRejection = "stale" | "unknown-owner";
+
+export type RegistrationConflictDiagnostic = Extract<MiddlewareDiagnostic, { kind: "registration_conflict" }>;
+
+export interface ReplaceRegistrationsReport {
+	applied: boolean;
+	owner: MiddlewareRegistrationOwner;
+	/** Generation active for the owner after the call. */
+	activeGeneration: number;
+	reason?: ReplaceRegistrationsRejection;
+	/** Offered registrations dropped for colliding with a builtin, host, or earlier owned id. */
+	dropped: ReadonlyArray<MiddlewareRegistrationConflict>;
+	/**
+	 * Remove this generation's registrations if the owner still holds it. A
+	 * disposer for a superseded generation is a no-op, so a late disposal can
+	 * never remove a newer generation's registrations.
+	 */
+	dispose(): void;
+}
+
+/**
+ * A validated replacement whose complete next table state is already built.
+ * `publish` is one reference assignment: it does not validate, refuse,
+ * throw, or call out. The caller checks `current()` on the same stack
+ * immediately before publishing, then emits `conflicts` afterwards.
+ */
+export interface MiddlewareRegistrationReplacement {
+	owner: MiddlewareRegistrationOwner;
+	generation: number;
+	dropped: ReadonlyArray<MiddlewareRegistrationConflict>;
+	/** Diagnostics for `dropped`, as data. Nothing was emitted during preparation. */
+	conflicts: ReadonlyArray<RegistrationConflictDiagnostic>;
+	/** Registrations that will be active for the owner after publish. */
+	size: number;
+	/** True while the table state this replacement was prepared against is still the live one. */
+	current(): boolean;
+	/** Assignment-only publication of the prepared state. */
+	publish(): void;
+	/** Send `conflicts` to the diagnostic sink. Call only after publication. */
+	emitConflicts(): void;
+	/** Remove this generation's registrations if the owner still holds it. */
+	dispose(): void;
+	discard(): void;
+}
+
+export type PrepareRegistrationReplacementResult =
+	| { status: "prepared"; replacement: MiddlewareRegistrationReplacement }
+	| {
+			status: "rejected";
+			owner: MiddlewareRegistrationOwner;
+			reason: ReplaceRegistrationsRejection;
+			activeGeneration: number;
+	  };
+
+export interface MiddlewareRegistrationTable {
+	/** The current frozen evaluation list. Capture once per evaluation. */
+	list(): ReadonlyArray<MiddlewareHookRegistration>;
+	registerHook(registration: MiddlewareHookRegistration): void;
+	prepareReplacement(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): PrepareRegistrationReplacementResult;
+	replaceRegistrations(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): ReplaceRegistrationsReport;
+	ownedGeneration(owner: MiddlewareRegistrationOwner): number;
+}
+
+interface OwnerSlot {
+	generation: number;
+	registrations: ReadonlyArray<MiddlewareHookRegistration>;
+	/** Host index the slot sits before; fixed at the owner's first replacement. */
+	anchor: number;
+}
+
+/** One immutable table state. Replaced wholesale, never mutated. */
+interface TableState {
+	host: ReadonlyArray<MiddlewareHookRegistration>;
+	hostIds: ReadonlySet<string>;
+	slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>;
+	list: ReadonlyArray<MiddlewareHookRegistration>;
+}
+
+export interface MiddlewareRegistrationTableOptions {
+	fixed: ReadonlyArray<MiddlewareHookRegistration>;
+	/** Resolved per emission so the composition root can swap the sink later. */
+	diagnosticSink: () => MiddlewareDiagnosticSink;
+}
+
+function isRegistrationOwner(value: string): value is MiddlewareRegistrationOwner {
+	return (MIDDLEWARE_REGISTRATION_OWNERS as ReadonlyArray<string>).includes(value);
+}
+
+export function createMiddlewareRegistrationTable(
+	options: MiddlewareRegistrationTableOptions,
+): MiddlewareRegistrationTable {
+	const fixed = Object.freeze([...options.fixed]);
+	const fixedIds = new Set(fixed.map((registration) => registration.id));
+
+	const buildList = (
+		host: ReadonlyArray<MiddlewareHookRegistration>,
+		slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>,
+	): ReadonlyArray<MiddlewareHookRegistration> => {
+		const list: MiddlewareHookRegistration[] = [...fixed];
+		const slotAt = (index: number): void => {
+			for (const owner of MIDDLEWARE_REGISTRATION_OWNERS) {
+				const slot = slots.get(owner);
+				if (slot !== undefined && slot.anchor === index) list.push(...slot.registrations);
+			}
+		};
+		for (let index = 0; index < host.length; index += 1) {
+			slotAt(index);
+			list.push(host[index] as MiddlewareHookRegistration);
+		}
+		slotAt(host.length);
+		return Object.freeze(list);
+	};
+
+	const makeState = (
+		host: ReadonlyArray<MiddlewareHookRegistration>,
+		slots: ReadonlyMap<MiddlewareRegistrationOwner, OwnerSlot>,
+	): TableState =>
+		Object.freeze({
+			host: Object.freeze([...host]),
+			hostIds: new Set(host.map((registration) => registration.id)),
+			slots: new Map(slots),
+			list: buildList(host, slots),
+		});
+
+	// The single live reference. Every publish below is `state = next`.
+	let state: TableState = makeState([], new Map());
+
+	const emit = (diagnostic: MiddlewareDiagnostic): void => {
+		try {
+			options.diagnosticSink()(diagnostic);
+		} catch {
+			// A diagnostics sink must never affect registration bookkeeping.
+		}
+	};
+
+	const slotFor = (base: TableState, owner: MiddlewareRegistrationOwner): OwnerSlot =>
+		base.slots.get(owner) ?? { generation: 0, registrations: [], anchor: base.host.length };
+
+	const disposeGeneration = (owner: MiddlewareRegistrationOwner, generation: number): void => {
+		const base = state;
+		const held = base.slots.get(owner);
+		if (held === undefined || held.generation !== generation || held.registrations.length === 0) return;
+		const slots = new Map(base.slots);
+		slots.set(owner, { ...held, registrations: Object.freeze([]) });
+		state = makeState(base.host, slots);
+	};
+
+	const table: MiddlewareRegistrationTable = {
+		list: () => state.list,
+		registerHook(registration) {
+			const base = state;
+			if (fixedIds.has(registration.id) || base.hostIds.has(registration.id)) return;
+			const evictions: RegistrationConflictDiagnostic[] = [];
+			const slots = new Map(base.slots);
+			for (const [owner, slot] of base.slots) {
+				if (!slot.registrations.some((entry) => entry.id === registration.id)) continue;
+				slots.set(owner, {
+					...slot,
+					registrations: Object.freeze(slot.registrations.filter((entry) => entry.id !== registration.id)),
+				});
+				evictions.push({
+					kind: "registration_conflict",
+					registrationId: registration.id,
+					owner,
+					generation: slot.generation,
+					conflictsWith: "host",
+					action: "evicted",
+				});
+			}
+			state = makeState([...base.host, registration], slots);
+			// Diagnostics only after the publish; a sink that registers another
+			// host hook re-enters against the already-published state.
+			for (const eviction of evictions) emit(eviction);
+		},
+		prepareReplacement(owner, generation, registrations) {
+			if (!isRegistrationOwner(owner)) {
+				return { status: "rejected", owner, reason: "unknown-owner", activeGeneration: 0 };
+			}
+			const base = state;
+			const slot = slotFor(base, owner);
+			if (!Number.isInteger(generation) || generation <= slot.generation) {
+				return { status: "rejected", owner, reason: "stale", activeGeneration: slot.generation };
+			}
+			const dropped: MiddlewareRegistrationConflict[] = [];
+			const conflicts: RegistrationConflictDiagnostic[] = [];
+			const accepted: MiddlewareHookRegistration[] = [];
+			const seen = new Set<string>();
+			for (const registration of registrations) {
+				const conflictsWith: MiddlewareRegistrationConflictTier | null = fixedIds.has(registration.id)
+					? "builtin"
+					: base.hostIds.has(registration.id)
+						? "host"
+						: seen.has(registration.id)
+							? "owned"
+							: null;
+				if (conflictsWith !== null) {
+					dropped.push({ id: registration.id, conflictsWith });
+					conflicts.push({
+						kind: "registration_conflict",
+						registrationId: registration.id,
+						owner,
+						generation,
+						conflictsWith,
+						action: "dropped",
+					});
+					continue;
+				}
+				seen.add(registration.id);
+				accepted.push(registration);
+			}
+			const slots = new Map(base.slots);
+			slots.set(owner, { generation, registrations: Object.freeze(accepted), anchor: slot.anchor });
+			const prepared = makeState(base.host, slots);
+			let settled = false;
+			const frozenDropped = Object.freeze(dropped);
+			const frozenConflicts = Object.freeze(conflicts);
+			const replacement: MiddlewareRegistrationReplacement = {
+				owner,
+				generation,
+				dropped: frozenDropped,
+				conflicts: frozenConflicts,
+				size: accepted.length,
+				// Reference identity on the base state covers every kind of
+				// intervening change: host appends, other replacements, disposals.
+				current: () => !settled && state === base,
+				publish() {
+					settled = true;
+					state = prepared;
+				},
+				emitConflicts() {
+					for (const conflict of frozenConflicts) emit(conflict);
+				},
+				dispose() {
+					disposeGeneration(owner, generation);
+				},
+				discard() {
+					settled = true;
+				},
+			};
+			return { status: "prepared", replacement };
+		},
+		replaceRegistrations(owner, generation, registrations) {
+			const prepared = table.prepareReplacement(owner, generation, registrations);
+			if (prepared.status === "rejected") {
+				return {
+					applied: false,
+					owner: prepared.owner,
+					activeGeneration: prepared.activeGeneration,
+					reason: prepared.reason,
+					dropped: [],
+					dispose: () => undefined,
+				};
+			}
+			const replacement = prepared.replacement;
+			// Nothing ran between prepare and here, so current() holds; the
+			// check is kept so the one-call form has the same shape as a caller
+			// that validates on its own stack.
+			if (!replacement.current()) {
+				replacement.discard();
+				return {
+					applied: false,
+					owner,
+					activeGeneration: table.ownedGeneration(owner),
+					reason: "stale",
+					dropped: replacement.dropped,
+					dispose: () => undefined,
+				};
+			}
+			replacement.publish();
+			replacement.emitConflicts();
+			return {
+				applied: true,
+				owner,
+				activeGeneration: generation,
+				dropped: replacement.dropped,
+				dispose: () => replacement.dispose(),
+			};
+		},
+		ownedGeneration(owner) {
+			return state.slots.get(owner)?.generation ?? 0;
+		},
+	};
+	return table;
+}

package/src/domains/middleware/runtime.ts

@@ -1,4 +1,5 @@
 import { createHookBudgetTracker, type HookBudgetStats, type HookBudgetTracker } from "./budget.js";
+import type { MiddlewareRegistrationConflictTier, MiddlewareRegistrationOwner } from "./registrations.js";
 import { listMiddlewareRuleDefinitions } from "./rules.js";
 import {
 	MIDDLEWARE_HOOK_TEXT_MAX_CHARS,
@@ -90,6 +91,20 @@ export type MiddlewareDiagnostic =
 			steadyStateWarn: boolean;
 			/** Rolling-window stats (p50/p95/over-count) for diagnosis. */
 			stats: HookBudgetStats;
+	  }
+	| {
+			/**
+			 * An owned registration set offered an id already held by a builtin
+			 * rule or a host registration (dropped), or a later host registration
+			 * took an id an owner held (evicted). Bookkeeping only; nothing was
+			 * evaluated.
+			 */
+			kind: "registration_conflict";
+			registrationId: string;
+			owner: MiddlewareRegistrationOwner;
+			generation: number;
+			conflictsWith: MiddlewareRegistrationConflictTier;
+			action: "dropped" | "evicted";
 	  };
 
 export type MiddlewareDiagnosticSink = (diagnostic: MiddlewareDiagnostic) => void;
@@ -106,6 +121,10 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 		);
 		return;
 	}
+	if (diagnostic.kind === "registration_conflict") {
+		process.stderr.write(`[clio-coder:middleware] ${formatRegistrationConflict(diagnostic)}\n`);
+		return;
+	}
 	// A single post-warmup spike is telemetry, not operator-facing noise: only
 	// consistent slowness prints, unless CLIO_CODER_HOOK_BUDGET_DEBUG=1 asks for all.
 	if (!diagnostic.steadyStateWarn && process.env.CLIO_CODER_HOOK_BUDGET_DEBUG !== "1") return;
@@ -120,6 +139,15 @@ export function writeMiddlewareDiagnosticToStderr(diagnostic: MiddlewareDiagnost
 	);
 }
 
+/** One operator line for a registration_conflict diagnostic. */
+export function formatRegistrationConflict(
+	diagnostic: Extract<MiddlewareDiagnostic, { kind: "registration_conflict" }>,
+): string {
+	return diagnostic.action === "dropped"
+		? `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) dropped: id is held by a ${diagnostic.conflictsWith} registration`
+		: `${diagnostic.owner} registration '${diagnostic.registrationId}' (generation ${diagnostic.generation}) evicted by a ${diagnostic.conflictsWith} registration with the same id`;
+}
+
 /**
  * Wrap a declarative rule definition as a degenerate coded registration so a
  * single ordered evaluation path serves both. The wrapped `evaluate` keeps the

package/src/domains/middleware/snapshot.ts

@@ -1,13 +1,14 @@
 import { createHookBudgetTracker, resolveHookBudgetsFromEnv, resolveHookBudgetTunablesFromEnv } from "./budget.js";
 import type { MiddlewareContract } from "./contract.js";
+import { createMiddlewareRegistrationTable } from "./registrations.js";
 import { cloneMiddlewareRule, listMiddlewareRuleDefinitions, listMiddlewareRules } from "./rules.js";
 import {
 	cloneMiddlewareEffect,
 	type MiddlewareDiagnosticSink,
-	type MiddlewareHookRegistration,
 	type MiddlewareRuleDefinition,
 	registrationFromRuleDefinition,
 	runMiddlewareRegistrations,
+	writeMiddlewareDiagnosticToStderr,
 } from "./runtime.js";
 import type { MiddlewareRule, MiddlewareSnapshot } from "./types.js";
 
@@ -39,15 +40,20 @@ export function createMiddlewareContractFromSnapshot(snapshot: MiddlewareSnapsho
 		if (builtin?.predicate !== undefined) definition.predicate = builtin.predicate;
 		return definition;
 	});
-	const registrations: MiddlewareHookRegistration[] = definitions.map(registrationFromRuleDefinition);
-	const registeredIds = new Set(registrations.map((registration) => registration.id));
+	let diagnosticSink: MiddlewareDiagnosticSink | undefined;
+	// Workers never receive owned registrations; the table exists so the
+	// worker contract satisfies the same interface with the same semantics.
+	const table = createMiddlewareRegistrationTable({
+		fixed: definitions.map(registrationFromRuleDefinition),
+		diagnosticSink: () => diagnosticSink ?? writeMiddlewareDiagnosticToStderr,
+	});
 	const budgetTracker = createHookBudgetTracker({
 		budgets: resolveHookBudgetsFromEnv(),
 		...resolveHookBudgetTunablesFromEnv(),
 	});
-	let diagnosticSink: MiddlewareDiagnosticSink | undefined;
 	return {
 		runHook(input) {
+			const registrations = table.list();
 			return runMiddlewareRegistrations(input, registrations, {
 				budgetTracker,
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
@@ -60,12 +66,19 @@ export function createMiddlewareContractFromSnapshot(snapshot: MiddlewareSnapsho
 			return createMiddlewareSnapshot(definitions.map((definition) => definition.rule));
 		},
 		registerHook(registration) {
-			if (registeredIds.has(registration.id)) return;
-			registeredIds.add(registration.id);
-			registrations.push(registration);
+			table.registerHook(registration);
 		},
 		setDiagnosticSink(sink) {
 			diagnosticSink = sink;
 		},
+		prepareRegistrationReplacement(owner, generation, registrations) {
+			return table.prepareReplacement(owner, generation, registrations);
+		},
+		replaceRegistrations(owner, generation, registrations) {
+			return table.replaceRegistrations(owner, generation, registrations);
+		},
+		ownedGeneration(owner) {
+			return table.ownedGeneration(owner);
+		},
 	};
 }

package/src/domains/mux/contract.ts

@@ -119,6 +119,20 @@ export interface MuxContract extends DomainContract {
 	focusPane(paneId: string): Promise<boolean>;
 	/** Zoom one Clio-created pane on, off, or toggled. Zooming steals focus; same rule as focusPane. */
 	zoomPane(paneId: string, mode: "on" | "off" | "toggle"): Promise<boolean>;
+	/**
+	 * Bring keyboard focus back to Clio's own hosting pane. This is the return
+	 * half of every explicit pane interaction: a pick in the files pane, a
+	 * toggle that closed a pane the operator was looking at. False outside
+	 * guest mode, without an anchor pane, or below the pane.focus floor.
+	 */
+	focusSelf(): Promise<boolean>;
+	/**
+	 * Leave zoom on the tab that hosts Clio, so a dock split from the anchor is
+	 * visible again. A zoomed tab hides every pane but one; opening or focusing
+	 * the files pane behind a zoom would report success for a pane the operator
+	 * cannot see. False when nothing was zoomed or the tier is absent.
+	 */
+	unzoomSelf(): Promise<boolean>;
 	/** Set a dock's share of its axis. False when the slot has no dock or the tier is absent. */
 	resizeDock(slot: DockSlot, share: number): Promise<boolean>;
 	/** Live dock geometry states, for `/panes` status. */
@@ -425,6 +439,30 @@ export function createMuxRuntime(options: MuxRuntimeOptions): MuxRuntime {
 			);
 		},
 
+		async focusSelf(): Promise<boolean> {
+			if (anchorPaneId === null || !muxSupportsMethod(detection.server, "pane.focus")) return false;
+			return await attempt(
+				"focusSelf",
+				async (live) => {
+					await live.paneFocus(anchorPaneId);
+					return true;
+				},
+				false,
+			);
+		},
+
+		async unzoomSelf(): Promise<boolean> {
+			if (anchorPaneId === null || !muxSupportsMethod(detection.server, "pane.zoom")) return false;
+			return await attempt(
+				"unzoomSelf",
+				async (live) => {
+					const result = await live.paneZoom(anchorPaneId, "off");
+					return result.changed;
+				},
+				false,
+			);
+		},
+
 		async resizeDock(slot: DockSlot, share: number): Promise<boolean> {
 			if (!docks) return false;
 			return await attempt("resizeDock", () => docks.resize(slot, share), false);