@iowarp/clio-coder 0.4.1 → 0.4.2

package/src/domains/extensions/types.ts

@@ -27,6 +27,19 @@ export interface ExtensionDiagnostic {
 	path?: string;
 }
 
+export interface ExtensionProvenance {
+	id: string;
+	scope: ExtensionScope;
+	/** Path recorded in install state, 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 on this load. */
+	contentDigest: string;
+}
+
 export interface InstalledExtension {
 	id: string;
 	name: string;
@@ -36,14 +49,28 @@ export interface InstalledExtension {
 	rootPath: string;
 	manifestPath: string;
 	enabled: boolean;
+	/** Whether the complete manifest and declared resource tree are valid. */
+	valid: boolean;
 	/** Whether this package admits the running Clio version. */
 	compatible: boolean;
 	effective: boolean;
+	/** The single admission decision for extension-owned resources and hooks. */
+	loadable: boolean;
+	/** Present exactly when the installed tree and manifest bytes were reverified. */
+	provenance?: ExtensionProvenance;
+	/** Digest observed while checking installed content on this load. */
+	observedContentDigest?: string;
 	resources: ExtensionManifestResources;
 	overriddenBy?: ExtensionScope;
 	diagnostics: ExtensionDiagnostic[];
 }
 
+export type LoadableExtension = InstalledExtension & { loadable: true; provenance: ExtensionProvenance };
+
+export function isLoadableExtension(entry: InstalledExtension): entry is LoadableExtension {
+	return entry.loadable && entry.provenance !== undefined;
+}
+
 export interface ExtensionCandidate {
 	path: string;
 	manifestPath?: string;
@@ -58,8 +85,88 @@ export interface ExtensionResourceRoot {
 	path: string;
 	rootPath: string;
 	source: string;
+	provenance: ExtensionProvenance;
+	/** Zero denotes an ephemeral, uncommitted projection. */
+	generation: number;
+}
+
+export interface ExtensionHookSource {
+	provenance: ExtensionProvenance;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+	/** Parsed captured YAML, or an empty list when parsing failed. */
+	declarations: unknown;
+	parseError?: string;
 }
 
+export interface ExtensionSnapshotDiagnostics {
+	entries: ReadonlyArray<ExtensionDiagnostic & { extensionId?: string }>;
+	truncated: number;
+}
+
+export interface ExtensionSnapshot {
+	version: 1;
+	generation: number;
+	cwd: string;
+	builtAt: string;
+	/** Content identity; generation, timestamp, and diagnostic text are excluded. */
+	digest: string;
+	packages: ReadonlyArray<InstalledExtension>;
+	resourceRoots: Readonly<Record<ExtensionResourceKind, ReadonlyArray<ExtensionResourceRoot>>>;
+	hookSources: ReadonlyArray<ExtensionHookSource>;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+export type ExtensionReloadRejectionReason = "build-failed" | "reentrant" | "stale" | "workspace-changed";
+
+export interface ExtensionReloadRejection {
+	status: "rejected";
+	reason: ExtensionReloadRejectionReason;
+	/** Generation that remains committed. */
+	generation: number;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+/**
+ * A fully built and validated generation that has not been published. The
+ * bundle holds at most one candidate at a time. `publish` is one reference
+ * assignment that never validates, refuses, throws, or calls out; the caller
+ * checks `current()` on the same stack immediately before it. `discard`
+ * releases the candidate without any visible change.
+ */
+export interface ExtensionReloadCandidate {
+	generation: number;
+	previousGeneration: number;
+	snapshot: ExtensionSnapshot;
+	/** False when the candidate digest equals the committed digest. */
+	changed: boolean;
+	added: ReadonlyArray<string>;
+	removed: ReadonlyArray<string>;
+	modified: ReadonlyArray<string>;
+	/** True while this is the in-flight candidate and the committed snapshot it was diffed against is still live. */
+	current(): boolean;
+	publish(): void;
+	discard(): void;
+}
+
+export type ExtensionReloadPrepareResult =
+	| { status: "prepared"; candidate: ExtensionReloadCandidate }
+	| ExtensionReloadRejection;
+
+export interface ExtensionReloadCommitted {
+	status: "committed";
+	generation: number;
+	previousGeneration: number;
+	changed: boolean;
+	digest: string;
+	added: ReadonlyArray<string>;
+	removed: ReadonlyArray<string>;
+	modified: ReadonlyArray<string>;
+	diagnostics: ExtensionSnapshotDiagnostics;
+}
+
+export type ExtensionReloadResult = ExtensionReloadCommitted | ExtensionReloadRejection;
+
 export interface ExtensionListOptions {
 	scope?: ExtensionScope;
 	cwd?: string;
@@ -72,17 +179,27 @@ export interface ExtensionInstallOptions extends ExtensionListOptions {
 
 export interface ExtensionInstallResult {
 	extension?: InstalledExtension;
+	recovery?: { stateBackup?: string; packageBackup?: string };
 	diagnostics: ExtensionDiagnostic[];
 }
 
 export interface ExtensionMutationResult {
 	extension?: InstalledExtension;
 	removed?: { id: string; scope: ExtensionScope; path: string };
+	recovery?: { stateBackup?: string; packageBackup?: string };
 	diagnostics: ExtensionDiagnostic[];
 }
 
+export interface ExtensionStateUpgradeReport {
+	scope: ExtensionScope;
+	statePath: string;
+	backupPath?: string;
+	upgraded: string[];
+	refused: Array<{ id: string; reason: string }>;
+}
+
 export interface ExtensionState {
 	version: 1;
 	disabled: string[];
-	installed: Record<string, { installedAt: string; source?: string }>;
+	installed: Record<string, { installedAt: string; source?: string; contentDigest?: string }>;
 }

package/src/domains/lifecycle/migrations/2026-09-01-extension-install-digests.ts

@@ -0,0 +1,27 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { safeResourceWrite } from "../../../core/safe-resource-write.js";
+import { upgradeLegacyExtensionInstallState } from "../../extensions/state.js";
+import type { Migration } from "./index.js";
+
+export const EXTENSION_INSTALL_DIGESTS_MIGRATION_ID = "2026-09-01-extension-install-digests";
+
+function migrateExtensionInstallDigests(stateDir: string, cwd = process.cwd()): void {
+	const scopes = upgradeLegacyExtensionInstallState(cwd);
+	const reportDir = join(stateDir, "migration-reports");
+	mkdirSync(reportDir, { recursive: true });
+	safeResourceWrite(
+		join(reportDir, `${EXTENSION_INSTALL_DIGESTS_MIGRATION_ID}.json`),
+		`${JSON.stringify({ migration: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID, scopes }, null, 2)}\n`,
+		{ encoding: "utf8", mode: 0o644 },
+	);
+}
+
+const migration: Migration = {
+	id: EXTENSION_INSTALL_DIGESTS_MIGRATION_ID,
+	async up(stateDir: string): Promise<void> {
+		migrateExtensionInstallDigests(stateDir);
+	},
+};
+
+export default migration;

package/src/domains/lifecycle/migrations/index.ts

@@ -34,6 +34,7 @@ import { join } from "node:path";
 
 import lmStudioRuntimeId from "./2026-08-18-lmstudio-runtime-id.js";
 import clioCoderNaming from "./2026-09-01-clio-coder-naming.js";
+import extensionInstallDigests from "./2026-09-01-extension-install-digests.js";
 import retirePanesKnobs from "./2026-09-01-retire-panes-knobs.js";
 import settingsV2 from "./2026-09-01-settings-v2.js";
 
@@ -61,6 +62,7 @@ export interface MigrationRunResult {
 // migration independently and for manifest continuity; it is a no-op on v2.
 const REGISTRY: ReadonlyArray<Migration> = Object.freeze([
 	settingsV2,
+	extensionInstallDigests,
 	clioCoderNaming,
 	retirePanesKnobs,
 	lmStudioRuntimeId,

package/src/domains/lifecycle/naming-resources.ts

@@ -9,12 +9,14 @@ import {
 	statSync,
 	writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
 
 import { parse as parseYaml } from "yaml";
 import { resolvePackageRoot } from "../../core/package-root.js";
 import { fsyncDirectory } from "../../core/safe-resource-write.js";
 import { resolveClioDirs } from "../../core/xdg.js";
+import { INTEROP_AGENT_KINDS } from "../interop/registry.js";
 import { normalizedSkillHash, stripProvenanceFrontmatter } from "../resources/skills/content-hash.js";
 
 const LEGACY_SKILL_NAMES = [
@@ -35,6 +37,8 @@ export interface NamingResourceReport {
 export interface NamingResourceOptions {
 	cwd?: string;
 	configDir?: string;
+	/** Home directory whose interop skill roots are inspected; defaults to the OS home. */
+	home?: string;
 	packageRoot?: string;
 	fix?: boolean;
 }
@@ -206,14 +210,25 @@ function collectSkillFiles(root: string, current = root): string[] {
 	return out;
 }
 
-/** Read-only inventory of released skill metadata keys in selected Clio Coder roots. */
+/**
+ * Read-only inventory of released skill metadata keys in every root the skill
+ * loader reads: the Clio user and project roots plus each interop agent's
+ * user and project compatibility roots (`.claude/skills`, `.agents/skills`,
+ * ...). The loader warns for a legacy key in any of them, so the doctor has to
+ * look where the loader looks or it reports "canonical" while boot warns.
+ */
 export function inspectSkillMetadataNaming(
-	options: Pick<NamingResourceOptions, "cwd" | "configDir"> = {},
+	options: Pick<NamingResourceOptions, "cwd" | "configDir" | "home"> = {},
 ): SkillMetadataNamingInspection[] {
 	const cwd = options.cwd ?? process.cwd();
 	const configDir = options.configDir ?? resolveClioDirs().config;
-	const roots = [path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")];
-	return roots.flatMap((root) =>
+	const home = options.home ?? homedir();
+	const roots = new Set<string>([path.join(configDir, "skills"), path.join(cwd, ".clio-coder", "skills")]);
+	for (const kind of INTEROP_AGENT_KINDS) {
+		if (kind.userSkillRoot !== undefined) roots.add(path.join(home, kind.userSkillRoot));
+		if (kind.projectSkillRoot !== undefined) roots.add(path.join(cwd, kind.projectSkillRoot));
+	}
+	return [...roots].flatMap((root) =>
 		collectSkillFiles(root).map((file) => ({
 			path: file,
 			legacyMetadataKey: /^clio:\s*(?:#.*)?$/mu.test(readFileSync(file, "utf8")),

package/src/domains/lifecycle/naming-yazi.ts

@@ -54,10 +54,14 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 	const cacheDir = options.cacheDir ?? resolveClioDirs().cache;
 	const before = inspectYaziNaming(cacheDir);
 	if (!before.present) {
-		return { ...before, status: "absent", detail: "managed Yazi profile is absent; next open writes canonical names" };
+		return {
+			...before,
+			status: "absent",
+			detail: "managed files pane profile is absent; next open writes canonical names",
+		};
 	}
 	if (before.legacyEvents === 0 && before.legacyEnvironmentNames === 0) {
-		return { ...before, status: "canonical", detail: "managed Yazi profile already uses canonical names" };
+		return { ...before, status: "canonical", detail: "managed files pane profile already uses canonical names" };
 	}
 	const yaziPath = options.yaziPath === undefined ? resolveToolBinary("yazi").binaryPath : options.yaziPath;
 	const yaPath = options.yaPath === undefined ? resolveToolBinary("ya").binaryPath : options.yaPath;
@@ -66,7 +70,8 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 		return {
 			...before,
 			status: "removed-unresolved",
-			detail: "legacy managed profile removed; Yazi/ya is unresolved, so the next managed open will regenerate it",
+			detail:
+				"legacy managed profile removed; the files pane engine is unresolved, so the next managed open will regenerate it",
 		};
 	}
 	const profile = ensureYaziProfile({ yaziPath, yaPath, profileDir: before.profileDir });
@@ -74,8 +79,8 @@ export function regenerateYaziNamingProfile(options: YaziNamingOptions = {}): Ya
 		return {
 			...before,
 			status: "regeneration-failed",
-			detail: "legacy managed profile removed, but current Yazi rejected the regenerated profile",
+			detail: "legacy managed profile removed, but the files pane engine rejected the regenerated profile",
 		};
 	}
-	return { ...before, status: "regenerated", detail: "managed Yazi profile regenerated with canonical names" };
+	return { ...before, status: "regenerated", detail: "managed files pane profile regenerated with canonical names" };
 }

package/src/domains/middleware/contract.ts

@@ -1,3 +1,8 @@
+import type {
+	MiddlewareRegistrationOwner,
+	PrepareRegistrationReplacementResult,
+	ReplaceRegistrationsReport,
+} from "./registrations.js";
 import type { MiddlewareDiagnosticSink, MiddlewareHookRegistration } from "./runtime.js";
 import type {
 	MiddlewareEffect,
@@ -32,4 +37,25 @@ export interface MiddlewareContract {
 	 * stderr writer default.
 	 */
 	setDiagnosticSink(sink: MiddlewareDiagnosticSink): void;
+	/**
+	 * Validate an owner's replacement registration set against the current
+	 * builtin and host ids and build its evaluation list without publishing.
+	 * Rejected when `generation` is not strictly greater than the owner's
+	 * active generation. The returned replacement publishes with one reference
+	 * assignment that cannot refuse or call out, so a composition root can publish it
+	 * back-to-back with another domain's generation on the same stack.
+	 */
+	prepareRegistrationReplacement(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): PrepareRegistrationReplacementResult;
+	/** Prepare, check currentness, publish, then emit any conflict diagnostics. */
+	replaceRegistrations(
+		owner: MiddlewareRegistrationOwner,
+		generation: number,
+		registrations: ReadonlyArray<MiddlewareHookRegistration>,
+	): ReplaceRegistrationsReport;
+	/** Active generation for an owner; 0 when nothing was ever applied. */
+	ownedGeneration(owner: MiddlewareRegistrationOwner): number;
 }

package/src/domains/middleware/extension.ts

@@ -6,6 +6,7 @@ import {
 	resolveHookBudgetTunablesFromEnv,
 } from "./budget.js";
 import type { MiddlewareContract } from "./contract.js";
+import { createMiddlewareRegistrationTable } from "./registrations.js";
 import { cloneMiddlewareRule, listMiddlewareRuleDefinitions } from "./rules.js";
 import {
 	type MiddlewareDiagnosticSink,
@@ -14,6 +15,7 @@ import {
 	registrationFromRuleDefinition,
 	runMiddlewareAsyncRegistrations,
 	runMiddlewareRegistrations,
+	writeMiddlewareDiagnosticToStderr,
 } from "./runtime.js";
 import { createMiddlewareSnapshot } from "./snapshot.js";
 
@@ -54,18 +56,28 @@ export interface MiddlewareBundleOptions {
 
 export function createMiddlewareBundle(options: MiddlewareBundleOptions = {}): DomainBundle<MiddlewareContract> {
 	const ruleDefinitions = combineRuleDefinitions(listMiddlewareRuleDefinitions(), options.ruleDefinitions ?? []);
-	const registrations = combineRegistrations(ruleDefinitions, options.registrations ?? []);
-	const registeredIds = new Set(registrations.map((registration) => registration.id));
 	let diagnosticSink = options.onDiagnostic;
+	// Declarative rules are the fixed tier; construction-time coded
+	// registrations are the first host entries, deduplicated first-wins across
+	// the shared id namespace exactly as before.
+	const table = createMiddlewareRegistrationTable({
+		fixed: ruleDefinitions.map(registrationFromRuleDefinition),
+		diagnosticSink: () => diagnosticSink ?? writeMiddlewareDiagnosticToStderr,
+	});
+	for (const registration of options.registrations ?? []) table.registerHook(registration);
 	const budgetTracker = options.budgetTracker ?? createEnvHookBudgetTracker();
 	const contract: MiddlewareContract = {
 		runHook(input) {
+			// Capture the list once; a replacement published mid-evaluation
+			// takes effect for the next evaluation, never this one.
+			const registrations = table.list();
 			return runMiddlewareRegistrations(input, registrations, {
 				budgetTracker,
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
 			});
 		},
 		runAsyncHook(input, priorEffects = []) {
+			const registrations = table.list();
 			return runMiddlewareAsyncRegistrations(input, registrations, priorEffects, {
 				...(diagnosticSink !== undefined ? { onDiagnostic: diagnosticSink } : {}),
 			});
@@ -77,13 +89,20 @@ export function createMiddlewareBundle(options: MiddlewareBundleOptions = {}): D
 			return createMiddlewareSnapshot(ruleDefinitions.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);
+		},
 	};
 	return {
 		extension: {
@@ -108,22 +127,3 @@ function combineRuleDefinitions(
 	}
 	return combined;
 }
-
-/**
- * One ordered evaluation list: declarative rules first (builtin, then
- * composition-root), then coded registrations, deduplicated across the shared
- * id namespace with the earlier entry winning.
- */
-function combineRegistrations(
-	ruleDefinitions: ReadonlyArray<MiddlewareRuleDefinition>,
-	coded: ReadonlyArray<MiddlewareHookRegistration>,
-): MiddlewareHookRegistration[] {
-	const seen = new Set<string>(ruleDefinitions.map((definition) => definition.rule.id));
-	const combined: MiddlewareHookRegistration[] = ruleDefinitions.map(registrationFromRuleDefinition);
-	for (const registration of coded) {
-		if (seen.has(registration.id)) continue;
-		seen.add(registration.id);
-		combined.push(registration);
-	}
-	return combined;
-}

package/src/domains/middleware/hook-receipts.ts

@@ -1,11 +1,14 @@
 /**
  * Durable receipt log for user-defined middleware hooks. Every hook execution
- * emits a {@link HookReceipt}; this log keeps a bounded in-memory ring (the live
- * surface `clio-coder config inspect` reads) and persists it atomically through
- * safeResourceWrite. Writes are throttled so a per-tool-call cadence never turns
- * into per-call disk I/O; `flush()` forces a final write at shutdown.
+ * emits a {@link HookReceipt}; this log keeps a bounded in-memory ring and
+ * persists it atomically through safeResourceWrite. Writes are throttled so a
+ * per-tool-call cadence never turns into per-call disk I/O; `flush()` forces a
+ * final write at shutdown. `clio-coder config inspect` reads the persisted
+ * snapshot back with {@link readPersistedHookReceipts}, since it runs as its
+ * own process and has no access to a running session's in-memory ring.
  */
 
+import { readFileSync } from "node:fs";
 import { safeResourceWrite } from "../../core/safe-resource-write.js";
 import type { HookReceipt } from "./hooks.js";
 
@@ -68,3 +71,23 @@ export function createHookReceiptLog(options: HookReceiptLogOptions = {}): HookR
 		},
 	};
 }
+
+/**
+ * Read a log's persisted snapshot back, for a process that never held the
+ * live log (`config inspect` runs as its own invocation). A log that has
+ * never persisted yet reads as empty, not an error.
+ */
+export function readPersistedHookReceipts(persistPath: string): HookReceipt[] {
+	let raw: string;
+	try {
+		raw = readFileSync(persistPath, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const parsed = JSON.parse(raw) as Partial<PersistedReceipts>;
+	if (parsed.version !== 1 || !Array.isArray(parsed.receipts)) {
+		throw new Error(`${persistPath}: unrecognized hook receipt log shape`);
+	}
+	return parsed.receipts;
+}

package/src/domains/middleware/hooks-io.ts

@@ -1,12 +1,19 @@
 /**
- * Filesystem loading for user-defined middleware hooks and the production
- * command runner. Hooks live in dedicated, secrets-free files so they stay out
- * of the strict settings schema:
+ * Loading for user-defined middleware hooks and the production command
+ * runner. Hooks live in dedicated, secrets-free files so they stay out of the
+ * strict settings schema:
  *
  *   - `.clio-coder/hooks.yaml`        committed project hooks (origin "project"),
  *   - `.clio-coder/hooks.local.yaml`  gitignored local hooks (origin "project.local"),
  *   - `<extensionRoot>/hooks.yaml`  hooks shipped by an installed extension.
  *
+ * Project files are read from disk here. Extension declarations are never
+ * read here: they arrive already parsed as a captured source set that the
+ * composition root adapts from the extension snapshot, which captured the
+ * bytes during install-digest verification, so a hooks.yaml rewritten after
+ * verification cannot be admitted until the next generation re-verifies the
+ * tree. Middleware never sees extension-domain types.
+ *
  * Reads are best-effort: a missing file is skipped silently, and a malformed
  * file is reported as an issue without aborting anything.
  */
@@ -26,6 +33,7 @@ import {
 	type UserHookCommandRunner,
 	type UserHookDeclarationBatch,
 	type UserHookLoadResult,
+	type UserHookPackageProvenance,
 	type UserHookSource,
 	userHookToRegistration,
 } from "./hooks.js";
@@ -43,15 +51,27 @@ export interface ReadHookSourcesResult {
 	fileIssues: HookFileIssue[];
 }
 
-export interface ExtensionHookRoot {
-	id: string;
-	rootPath: string;
+/** One package's hook declarations, captured by the supplier from verified bytes. */
+export interface CapturedHookDeclarations {
+	provenance: UserHookPackageProvenance;
+	/** SHA-256 of the captured hooks.yaml bytes. */
+	declarationsDigest: string;
+	/** Parsed declarations, or an empty list when parsing failed. */
+	declarations: unknown;
+	parseError?: string;
+}
+
+/** The captured declarations of one supplier generation. */
+export interface CapturedHookSourceSet {
+	/** 0 for an ephemeral (uncommitted) build. */
+	generation: number;
+	sources: ReadonlyArray<CapturedHookDeclarations>;
 }
 
 export interface ReadHookSourcesOptions {
 	cwd: string;
-	/** Installed extension roots, in dependency order. */
-	extensions?: ReadonlyArray<ExtensionHookRoot>;
+	/** Captured extension declarations; absent means no extension hooks. */
+	capturedSources?: CapturedHookSourceSet;
 }
 
 function readBatch(
@@ -86,14 +106,23 @@ export function readHookSources(options: ReadHookSourcesOptions): ReadHookSource
 	const fileIssues: HookFileIssue[] = [];
 	const batches: UserHookDeclarationBatch[] = [];
 
-	for (const extension of options.extensions ?? []) {
+	const captured = options.capturedSources;
+	for (const entry of captured?.sources ?? []) {
 		const source: UserHookSource = {
 			origin: "extension",
-			sourcePath: `${extension.id}:hooks.yaml`,
-			sourceId: extension.id,
+			sourcePath: `${entry.provenance.id}:hooks.yaml`,
+			sourceId: entry.provenance.id,
+			extension: {
+				provenance: entry.provenance,
+				generation: captured?.generation ?? 0,
+				declarationsDigest: entry.declarationsDigest,
+			},
 		};
-		const batch = readBatch(source, join(extension.rootPath, "hooks.yaml"), fileIssues);
-		if (batch) batches.push(batch);
+		if (entry.parseError !== undefined) {
+			fileIssues.push({ source, message: `failed to parse ${source.sourcePath}: ${entry.parseError}` });
+			continue;
+		}
+		batches.push({ source, declarations: entry.declarations });
 	}
 
 	const projectBatch = readBatch(
@@ -113,44 +142,48 @@ export function readHookSources(options: ReadHookSourcesOptions): ReadHookSource
 	return { batches, fileIssues };
 }
 
-export interface InstallUserHooksOptions {
+export interface BuildUserHookRegistrationsOptions {
 	cwd: string;
 	/** Absolute workspace root a command `cwd` must resolve under; defaults to `cwd`. */
 	workspaceRoot?: string;
-	extensions?: ReadonlyArray<ExtensionHookRoot>;
-	registerHook: (registration: MiddlewareHookRegistration) => void;
+	capturedSources?: CapturedHookSourceSet;
 	recordReceipt: HookReceiptSink;
 	/** Injected for tests; defaults to the spawnSync runner. */
 	runCommand?: UserHookCommandRunner;
 	now?: () => number;
 }
 
-export interface InstallUserHooksResult extends UserHookLoadResult {
+export interface BuildUserHookRegistrationsResult extends UserHookLoadResult {
 	fileIssues: HookFileIssue[];
+	/** One registration per admitted hook, in merged precedence order. Nothing is registered here. */
+	registrations: MiddlewareHookRegistration[];
 }
 
 /**
- * Read, normalize, and register every user hook on the middleware contract. The
- * returned hooks and issues feed `clio-coder config inspect`. Best-effort throughout:
- * a malformed file or hook is reported, never thrown.
+ * Read project files, merge them with the captured extension declarations,
+ * normalize, and build one registration per admitted hook. Pure with respect
+ * to the middleware contract: the caller decides when the set is published,
+ * which is what lets extension and hook state publish on one stack. The
+ * returned hooks and issues feed `clio-coder config inspect`. Best-effort
+ * throughout: a malformed file or hook is reported, never thrown.
  */
-export function installUserHooks(options: InstallUserHooksOptions): InstallUserHooksResult {
+export function buildUserHookRegistrations(
+	options: BuildUserHookRegistrationsOptions,
+): BuildUserHookRegistrationsResult {
 	const workspaceRoot = options.workspaceRoot ?? options.cwd;
 	const readOptions: ReadHookSourcesOptions = { cwd: options.cwd };
-	if (options.extensions !== undefined) readOptions.extensions = options.extensions;
+	if (options.capturedSources !== undefined) readOptions.capturedSources = options.capturedSources;
 	const { batches, fileIssues } = readHookSources(readOptions);
 	const loaded = loadUserHooks(batches, { workspaceRoot });
 	const runCommand = options.runCommand ?? spawnSyncCommandRunner();
-	for (const hook of loaded.hooks) {
-		options.registerHook(
-			userHookToRegistration(hook, {
-				recordReceipt: options.recordReceipt,
-				runCommand,
-				...(options.now !== undefined ? { now: options.now } : {}),
-			}),
-		);
-	}
-	return { ...loaded, fileIssues };
+	const registrations = loaded.hooks.map((hook) =>
+		userHookToRegistration(hook, {
+			recordReceipt: options.recordReceipt,
+			runCommand,
+			...(options.now !== undefined ? { now: options.now } : {}),
+		}),
+	);
+	return { ...loaded, fileIssues, registrations };
 }
 
 /**