@hydraharness/harness-hooks-registry 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @hydraharness/harness-hooks-registry
+
+`HookRecordRegistry` (`ctx.hookRecords`) owns the declared hook records in its settings provider's `hooks` namespace. User and workspace providers choose the persistence file; changes from a configuration surface or a hand-edited document reconcile without a restart. Each enabled record mounts its dialect's bridge — `@hydraharness/harness-hooks-claude-code` or `@hydraharness/harness-hooks-codex` — which owns payloads, matchers, and extension-point mapping.
+
+## Service API
+
+`list()` projects every stored record with its live status, the events its definitions cover, and how many command hooks they declare. `define(request)` stores one complete definition and converges the mounted set: `mode: 'create'` requires an unused name, and `mode: 'replace'` requires an existing record. These conditions are checked inside the serialized mutation chain, so concurrent creates cannot overwrite one another and an edit cannot recreate a removed record. `setEnabled({ name, enabled })` changes only the desired state. `remove(name)` deletes the record, unmounts it, and deletes any document this registry materialized for it. Every mutation and every reconciliation runs on one serialized chain.
+
+On replacement, omitted `enabled` and `defaultTimeoutMs` retain their stored values. Other omitted optional fields clear the stored values; callers must supply the complete document source, since inline definitions are not returned by `list()`.
+
+`define`, `setEnabled`, and `remove` accept an optional `SettingsProvider` selecting a write layer. They derive records and revisions from that layer's base and stored override, including overrides suppressed by trust; shared writes preserve shared definitions without copying local overrides. Their result remains the effective runtime projection. Removing a shared record retains its materialized document while a local record still runs. `list(settings)` projects desired records, reporting live state only when the running definition matches; `list()` reads effective records. `settle()` awaits queued reconciliation after a settings-layer or trust change.
+
+## Stored records
+
+Registry writes carry the revision read before constructing the next record list. A concurrent settings change rejects the write with `SettingsConflictError` and refreshes the stored projection; retry against that projection. This prevents stale lists from restoring deleted records or discarding another writer's changes.
+
+`hooks.records` is an ordered list of at most 50 records. A record carries `name` (`[A-Za-z0-9_-]{1,64}`, unique across records), `dialect` (`claude-code` or `codex`), exactly one document source, `defaultTimeoutMs`, and `enabled` (default `false`, so a new record is inert until switched on). `claude-code` records may also carry `pluginRoot` and `projectDir`, which the bridge substitutes into command strings.
+
+The document source is either `configPath` — an absolute path, or a path relative to registry `Config.cwd` when supplied — or `config`, inline definitions as a bare event map or a `{ hooks: … }` wrapper. Inline definitions are capped at 256 KiB and materialized to `<hydraHome>/hooks/<name>.json` on every mount, because both bridges read one file path at load; editing the inline section is enough to change what runs.
+
+`define` parses the definitions with the record's own dialect parser before it persists, so a stored record can never be silently inert. At mount time the same parse decides the record's projection: a record whose document is missing, is not valid JSON, or declares nothing its dialect can run is reported with status `invalid` and the reason instead of failing the process — a hand-edited document must not stop every other record from mounting.
+
+`hooks-registry/reconciled` is emitted after each reconciliation settles, carrying the projection. The package invariant checks the registry's one contract on that event: an accepted enabled record is live and a disabled one is not.
+
+Mounts and settings writes use the registry's owning context and registration scope, including calls through an API context. Hooks receive descendant agents' events, including subagent lifecycle events; sibling workspace hooks remain separate. Mounts survive disposal of the API caller. Each workspace registry requires a separate Host-private `hydraHome` for its materialized documents. Definition validation requires at least one supported synchronous command hook, and the inline-document limit measures UTF-8 bytes.
+
+Registry `Config.cwd` is an optional absolute workspace directory. Relative file and substitution paths resolve from it, and the bridge runs commands there. Without it, file paths must be absolute and commands use the agent's session cwd. Unmounting aborts and drains every active hook before reconciliation settles, including blocking prompt/tool hooks; materialized inline files remain under the Host-private home.
+
+## Model Experience
+
+Indirectly, through the bridge a record mounts. `@hydraharness/harness-hooks-claude-code` and `@hydraharness/harness-hooks-codex` own everything a hook injects into a request — `SessionStart` and `UserPromptSubmit` context, `PostToolUse` feedback, `Stop` continuation messages — and this package decides only which of their configurations are live. It assembles no model input of its own.
+
+#### KV Cache effect
+
+Independent of this package's own operations, and consequential through them: mounting a record makes its hooks able to inject context into later requests, which the bridges document. Mounting or unmounting between requests does not itself rewrite an existing prefix; a hook that injects a message appends to the conversation like any other message.
+
+## Known Limitations and Deferred Work
+
+- **One document per bridge mount** — file records are read when the bridge mounts; editing an external hook document requires redefining or toggling the record to reload it.
+- **No dialect conversion** — a record is mounted by the dialect it declares; the registry never translates a Claude Code document into Codex spelling or the reverse, and each dialect silently drops events the other supports.

package/lib/index.js

@@ -0,0 +1,428 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { Service } from "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { writeFileAtomic } from "@hydraharness/harness-atomic-write";
+import { resolveHydraHome } from "@hydraharness/harness-home-paths";
+import { settingsNamespace } from "@hydraharness/harness-settings";
+import { apply, inject as inject$1 } from "@hydraharness/harness-hooks-claude-code";
+import { apply as apply$1, inject as inject$2 } from "@hydraharness/harness-hooks-codex";
+import { parseClaudeCodeConfig } from "@hydraharness/harness-hooks-claude-code/config";
+import { parseCodexConfig } from "@hydraharness/harness-hooks-codex/config";
+//#region lib/types/index.js
+/**
+* User-declared hook records: one settings-backed registry that mounts every
+* enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+* `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+* redefined, or removed. The stored document (`hooks.records` in the harness
+* settings file) is the only source of truth, so a hook added from a
+* configuration surface survives a restart and one added by hand-editing that
+* document mounts without one.
+*
+* A record either points at an existing hook document (`configPath`) or carries
+* its definitions inline. Inline definitions are materialized under the harness
+* home, because both bridges read one file path at load.
+* @module @hydraharness/harness-hooks-registry
+*/
+/** Settings namespace holding every user-declared hook record. */
+const HOOKS_SETTINGS_NAMESPACE = settingsNamespace("hooks");
+/** Accepted record name. */
+const RECORD_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/u;
+const MAX_RECORDS = 50;
+const MAX_INLINE_BYTES = 256 * 1024;
+const DEFAULT_HOOK_TIMEOUT_MS = 6e5;
+const StoredRecordSchema = z.object({
+	name: z.string().required(),
+	dialect: z.union([z.const("claude-code"), z.const("codex")]).default("claude-code"),
+	configPath: z.string().default(""),
+	config: z.dict(z.any()).default({}),
+	pluginRoot: z.string().default(""),
+	projectDir: z.string().default(""),
+	defaultTimeoutMs: z.number().step(1).min(1).default(DEFAULT_HOOK_TIMEOUT_MS),
+	enabled: z.boolean().default(false)
+});
+const HooksSettingsSchema = z.object({ records: z.array(StoredRecordSchema).max(MAX_RECORDS).default([]) });
+/** Which document source a stored record declares. */
+function sourceKind(record) {
+	return record.configPath === "" ? "inline" : "file";
+}
+/**
+* Reject a definition this registry could not mount. Every check answers a
+* constraint the schema cannot express: the name grammar, that exactly one
+* document source is declared, that a path is absolute, and that inline
+* definitions stay inside the document budget.
+* @param record - one stored record to judge.
+* @param label - operation name used in the diagnostic.
+*/
+function assertMountable(record, label, cwd) {
+	if (!RECORD_NAME_PATTERN.test(record.name)) throw new Error(`${label}: record name must match ${String(RECORD_NAME_PATTERN)}`);
+	const inline = Object.keys(record.config).length > 0;
+	if (record.configPath === "" && !inline) throw new Error(`${label}: record ${record.name} needs either a configPath or inline hook definitions`);
+	if (record.configPath !== "" && inline) throw new Error(`${label}: record ${record.name} declares both a configPath and inline hook definitions`);
+	if (record.configPath !== "" && !isAbsolute(record.configPath) && cwd === void 0) throw new Error(`${label}: record ${record.name} configPath must be absolute`);
+	if (inline && Buffer.byteLength(JSON.stringify(record.config), "utf8") > MAX_INLINE_BYTES) throw new Error(`${label}: record ${record.name} inline hooks exceed ${String(MAX_INLINE_BYTES)} bytes`);
+	if (record.dialect === "codex" && (record.pluginRoot !== "" || record.projectDir !== "")) throw new Error(`${label}: record ${record.name} substitution roots apply to claude-code records only`);
+}
+/** Reject a stored section whose records collide, so no mount silently wins. */
+function assertUniqueNames(settings) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const record of settings.records) {
+		if (seen.has(record.name)) throw new Error(`hookRecords: record name ${JSON.stringify(record.name)} is declared more than once`);
+		seen.add(record.name);
+	}
+}
+/**
+* Parse one document with its dialect's parser, so what the registry reports is
+* exactly what the bridge will run.
+* @param dialect - the record's config dialect.
+* @param raw - parsed JSON document.
+* @returns the event names covered and the total command-hook count.
+*/
+function summarize(dialect, raw) {
+	const parsed = dialect === "claude-code" ? parseClaudeCodeConfig(raw) : parseCodexConfig(raw);
+	const events = Object.keys(parsed.config).sort();
+	let hookCount = 0;
+	for (const groups of Object.values(parsed.config)) for (const group of groups) hookCount += group.hooks.length;
+	if (hookCount === 0) throw new Error(`hookRecords: ${dialect} document contains no supported synchronous command hooks`);
+	return {
+		events,
+		hookCount
+	};
+}
+/**
+* Fold one write request onto the record it replaces. Every field is restated
+* by the caller: unlike a credential, nothing here is withheld from a read, so
+* an omission is a deliberate clear.
+* @param request - complete definition supplied by the caller.
+* @param previous - the record being replaced, when one exists.
+* @returns the next stored record.
+*/
+function foldDefinition(request, previous) {
+	return {
+		name: request.name.trim(),
+		dialect: request.dialect,
+		configPath: (request.configPath ?? "").trim(),
+		config: { ...request.config },
+		pluginRoot: (request.pluginRoot ?? "").trim(),
+		projectDir: (request.projectDir ?? "").trim(),
+		defaultTimeoutMs: request.defaultTimeoutMs ?? previous?.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+		enabled: request.enabled ?? previous?.enabled ?? false
+	};
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+const inject = ["settings", "shell"];
+/**
+* Settings-backed hook records with their live bridge mounts. Reconciliation is
+* idempotent and runs on one serialized chain, so a document commit from any
+* source — this service's own write, another process, or a hand edit —
+* converges the mounted set on the stored one.
+* Mutations reject with `SettingsConflictError` if another writer changes the
+* stored section after the read; retry uses the refreshed projection.
+*/
+var HookRecordRegistry = class extends Service {
+	static inject = inject;
+	/** Bridge mounts belong to this Host service, not to a traced API caller. */
+	owner;
+	static Config = z.object({
+		hydraHome: z.string(),
+		cwd: z.string()
+	});
+	settings;
+	live = /* @__PURE__ */ new Map();
+	/** Stored records this registry refuses to mount, with the refusal reason. */
+	invalid = /* @__PURE__ */ new Map();
+	/** Directory holding the documents materialized from inline definitions. */
+	inlineRoot;
+	cwd;
+	tail = Promise.resolve();
+	stopped = false;
+	constructor(ctx, config = {}) {
+		super(ctx, "hookRecords");
+		if (config.cwd !== void 0 && !isAbsolute(config.cwd)) throw new Error("hookRecords: cwd must be absolute");
+		this.owner = ctx;
+		this.cwd = config.cwd;
+		this.inlineRoot = join(resolveHydraHome(config.hydraHome), "hooks");
+		this.settings = ctx.settings.register(HOOKS_SETTINGS_NAMESPACE, HooksSettingsSchema, { validate: assertUniqueNames });
+	}
+	async [Service.init]() {
+		this.ctx.inject(["optionalPlugins"], (pctx) => {
+			pctx.effect(() => pctx.optionalPlugins.subscribe((enabled) => {
+				this.enqueue(async () => {
+					if (!enabled) await pctx.optionalPlugins.drain();
+					if (pctx.optionalPlugins.enabled === enabled) await this.reconcile();
+				}).catch((error) => {
+					this.ctx.logger.error(error);
+				});
+			}), "hooks-registry: optional policy");
+		});
+		this.ctx.effect(() => () => this.shutdown(), "hookRecords.dispose");
+		this.ctx.effect(() => this.settings.watch(() => this.enqueue(() => this.reconcile())), "hookRecords.settingsWatch");
+		await this.enqueue(() => this.reconcile());
+	}
+	/**
+	* Project every stored record with its live state.
+	* @param settings - optional layer whose desired records to project.
+	* @returns the current record projection, in stored order.
+	*/
+	list(settings) {
+		return { records: (settings === void 0 ? this.settings.get().records : this.writeSource(settings).records).map((record) => this.view(record)) };
+	}
+	/**
+	* Reconcile the current effective settings after a layer or trust change.
+	* @returns completion after earlier queued work and the current mounts settle.
+	*/
+	settle() {
+		return this.enqueue(() => this.reconcile());
+	}
+	/**
+	* Create or replace one complete definition as requested, then
+	* converge the mounted set. A definition this registry could not mount is
+	* refused before anything persists.
+	* @param request - complete record definition.
+	* @param settings - selected write layer; omitted uses this registry's provider.
+	* @returns the refreshed projection.
+	* @throws If create names an existing record or replace names a missing record.
+	*/
+	define(request, settings = this.owner.settings) {
+		return this.enqueue(async () => {
+			const { revision, records } = this.writeSource(settings);
+			const index = records.findIndex((candidate) => candidate.name === request.name.trim());
+			if (request.mode === "create" && index !== -1) throw new Error(`hookRecords.define: record ${request.name} already exists`);
+			if (request.mode === "replace" && index === -1) throw new Error(`hookRecords.define: record ${request.name} is not configured`);
+			const record = foldDefinition(request, index === -1 ? void 0 : records[index]);
+			assertMountable(record, "hookRecords.define", this.cwd);
+			summarize(record.dialect, await this.readDefinitions(record));
+			const next = index === -1 ? [...records, record] : records.map((candidate, position) => position === index ? record : candidate);
+			if (next.length > MAX_RECORDS) throw new Error(`hookRecords.define: at most ${String(MAX_RECORDS)} records are supported`);
+			await settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+			await this.reconcile();
+			return this.list();
+		});
+	}
+	/**
+	* Change one stored record's desired state.
+	* @param request - target record and desired state.
+	* @param settings - selected write layer; omitted uses this registry's provider.
+	* @returns the refreshed projection.
+	*/
+	setEnabled(request, settings = this.owner.settings) {
+		return this.enqueue(async () => {
+			const { revision, records } = this.writeSource(settings);
+			const index = records.findIndex((candidate) => candidate.name === request.name);
+			if (index === -1) throw new Error(`hookRecords.setEnabled: record ${request.name} is not configured`);
+			const next = records.map((candidate, position) => position === index ? {
+				...candidate,
+				enabled: request.enabled
+			} : candidate);
+			await settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+			await this.reconcile();
+			return this.list();
+		});
+	}
+	/**
+	* Remove one stored record, unmount it, and delete any document this registry
+	* materialized for it.
+	* @param name - stored record name.
+	* @param settings - selected write layer; omitted uses this registry's provider.
+	* @returns the refreshed projection.
+	*/
+	remove(name, settings = this.owner.settings) {
+		return this.enqueue(async () => {
+			const { revision, records } = this.writeSource(settings);
+			if (!records.some((candidate) => candidate.name === name)) throw new Error(`hookRecords.remove: record ${name} is not configured`);
+			await settings.replace(HOOKS_SETTINGS_NAMESPACE, { records: records.filter((candidate) => candidate.name !== name) }, revision);
+			await this.reconcile();
+			if (!this.settings.get().records.some((record) => record.name === name)) await rm(this.inlinePath(name), { force: true });
+			return this.list();
+		});
+	}
+	/** Read the selected layer's desired records, including overrides suppressed by trust. */
+	writeSource(settings) {
+		const descriptor = settings.describe().find((section) => section.ns === HOOKS_SETTINGS_NAMESPACE);
+		if (descriptor === void 0) throw new Error("hookRecords: selected settings provider has no hooks namespace");
+		return {
+			...HooksSettingsSchema({ records: descriptor.user?.records ?? descriptor.base?.records ?? [] }),
+			revision: descriptor.revision
+		};
+	}
+	/** Serialize every mutation and reconciliation on one chain. */
+	enqueue(task) {
+		const run = this.tail.then(task, task);
+		this.tail = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	/**
+	* Converge the mounted set on the stored one: unmount every record that is
+	* gone, disabled, or redefined, then mount every enabled record that is not
+	* already live from the same definition. A record whose document is missing,
+	* unparseable, or refused by its dialect is recorded as `invalid` with the
+	* diagnostic and does not stop the others.
+	*/
+	async reconcile() {
+		if (this.stopped) return;
+		const records = new Map(this.settings.get().records.map((record) => [record.name, record]));
+		this.invalid.clear();
+		for (const [name, mount] of [...this.live]) {
+			const record = records.get(name);
+			if (this.ctx.get("optionalPlugins")?.enabled !== false && record?.enabled === true && recordDigest(record) === mount.digest) continue;
+			this.live.delete(name);
+			await disposeQuietly(mount.fiber);
+		}
+		for (const record of records.values()) {
+			if (this.ctx.get("optionalPlugins")?.enabled === false || !record.enabled || this.live.has(record.name)) continue;
+			await this.mount(record);
+		}
+		this.ctx.emit("hooks-registry/reconciled", this.list());
+	}
+	/**
+	* Materialize the record's document when it is inline, then start its
+	* dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+	* hand-edited document must not stop every other record from mounting.
+	*/
+	async mount(record) {
+		let configPath;
+		let summary;
+		try {
+			assertMountable(record, "hookRecords", this.cwd);
+			configPath = await this.materialize(record);
+			summary = summarize(record.dialect, await this.readDefinitions(record));
+		} catch (error) {
+			/* v8 ignore next -- validation, JSON parsing, and local filesystem operations throw Error instances. */
+			this.invalid.set(record.name, error instanceof Error ? error.message : String(error));
+			return;
+		}
+		const fiber = record.dialect === "claude-code" ? this.owner.plugin({
+			name: `hook-record:${record.name}`,
+			inject: inject$1,
+			apply
+		}, {
+			configPath,
+			defaultTimeoutMs: record.defaultTimeoutMs,
+			...this.cwd === void 0 ? {} : { cwd: this.cwd },
+			...record.pluginRoot === "" ? {} : { pluginRoot: this.documentPath(record.pluginRoot) },
+			...record.projectDir === "" ? {} : { projectDir: this.documentPath(record.projectDir) }
+		}) : this.owner.plugin({
+			name: `hook-record:${record.name}`,
+			inject: inject$2,
+			apply: apply$1
+		}, {
+			configPath,
+			defaultTimeoutMs: record.defaultTimeoutMs,
+			...this.cwd === void 0 ? {} : { cwd: this.cwd }
+		});
+		const mount = {
+			fiber,
+			digest: recordDigest(record),
+			events: summary.events,
+			hookCount: summary.hookCount,
+			status: "started"
+		};
+		this.live.set(record.name, mount);
+		try {
+			await fiber;
+		} catch (error) {
+			mount.status = "failed";
+			/* v8 ignore next -- Cordis normalizes plugin failures to Error before fiber.await rejects. */
+			mount.detail = error instanceof Error ? error.message : String(error);
+		}
+	}
+	/**
+	* Resolve the document path the bridge reads: a `file` record's own path, or
+	* the harness-home document this registry writes from inline definitions.
+	* Materialization is idempotent and re-runs per mount, so an edited inline
+	* section always reaches the bridge.
+	*/
+	async materialize(record) {
+		if (sourceKind(record) === "file") return this.documentPath(record.configPath);
+		const path = this.inlinePath(record.name);
+		await mkdir(this.inlineRoot, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFileAtomic(path, `${JSON.stringify(record.config, void 0, 2)}\n`, {
+			mode: 384,
+			dirMode: 448
+		});
+		return path;
+	}
+	/** Read one record's raw definitions, from its file or its inline section. */
+	async readDefinitions(record) {
+		if (sourceKind(record) === "inline") return record.config;
+		let text;
+		try {
+			text = await readFile(this.documentPath(record.configPath), "utf8");
+		} catch (cause) {
+			throw new Error(`hookRecords: record ${record.name} cannot read ${record.configPath}`, { cause });
+		}
+		try {
+			return JSON.parse(text);
+		} catch (cause) {
+			throw new Error(`hookRecords: record ${record.name} document is not valid JSON`, { cause });
+		}
+	}
+	/** Path of the document this registry materializes for one inline record. */
+	inlinePath(name) {
+		return join(this.inlineRoot, `${name}.json`);
+	}
+	/** Resolve a read-only document or substitution path inside the owning cwd. */
+	documentPath(path) {
+		return this.cwd === void 0 ? path : resolve(this.cwd, path);
+	}
+	/** Project one stored record with its live state. */
+	view(record) {
+		const candidate = this.live.get(record.name);
+		const digest = recordDigest(record);
+		const mount = candidate?.digest === digest ? candidate : void 0;
+		const effective = this.settings.get().records.find((hook) => hook.name === record.name);
+		const invalid = effective !== void 0 && recordDigest(effective) === digest ? this.invalid.get(record.name) : void 0;
+		const status = invalid !== void 0 ? "invalid" : !record.enabled ? "stopped" : mount?.status ?? "stopped";
+		const detail = invalid ?? mount?.detail;
+		return {
+			name: record.name,
+			dialect: record.dialect,
+			source: sourceKind(record),
+			enabled: record.enabled,
+			status,
+			...detail === void 0 || status === "stopped" ? {} : { detail },
+			...sourceKind(record) === "file" ? { configPath: record.configPath } : {},
+			events: mount?.events ?? [],
+			hookCount: mount?.hookCount ?? 0,
+			...record.pluginRoot === "" ? {} : { pluginRoot: record.pluginRoot },
+			...record.projectDir === "" ? {} : { projectDir: record.projectDir }
+		};
+	}
+	/** Refuse new work, then unmount every live record. */
+	async shutdown() {
+		this.stopped = true;
+		/* v8 ignore next -- enqueue stores a fulfilled tail after either task outcome. */
+		await this.tail.catch(() => void 0);
+		this.invalid.clear();
+		for (const [name, mount] of [...this.live]) {
+			this.live.delete(name);
+			await disposeQuietly(mount.fiber);
+		}
+	}
+};
+/**
+* Digest of everything a mount is started from, so reconciliation can tell a
+* redefined record from an untouched one without restarting a live bridge on
+* every unrelated document commit. The desired state is excluded: enablement is
+* handled by mount and unmount, not by a restart.
+*/
+function recordDigest(record) {
+	const { enabled: _desired, ...definition } = record;
+	return JSON.stringify(definition);
+}
+/**
+* Unmount one bridge and swallow its teardown failure. The record it served is
+* already out of the live map, so a disposal error cannot restore it, and
+* letting it escape would strand every later record in the same reconcile.
+* @param fiber - the mount to tear down.
+*/
+async function disposeQuietly(fiber) {
+	try {
+		await fiber.dispose();
+	} catch (_hookMountTeardownFailure) {}
+}
+//#endregion
+export { HOOKS_SETTINGS_NAMESPACE, HookRecordRegistry, HookRecordRegistry as default, inject };

package/lib/invariant.js

@@ -0,0 +1,32 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+* @module @hydraharness/harness-hooks-registry/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-hooks-registry";
+/** Cordis companion plugin name. */
+const name = "hooks-registry-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* The registry's contract is that the mounted bridge set follows the stored
+* records once reconciliation settles: an enabled record it accepted is live,
+* and a disabled one is not. Both sides ride the reconciliation event, so the
+* check observes the authoritative projection rather than re-deriving it.
+*/
+const install = (ctx, fail) => {
+	ctx.on("hooks-registry/reconciled", (snapshot) => {
+		for (const record of snapshot.records) {
+			if (record.enabled && record.status === "stopped") fail(`enabled hook record ${JSON.stringify(record.name)} has no live bridge after reconciliation`);
+			if (!record.enabled && record.status !== "stopped") fail(`disabled hook record ${JSON.stringify(record.name)} still reports ${record.status}`);
+		}
+	});
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,134 @@
+/**
+ * User-declared hook records: one settings-backed registry that mounts every
+ * enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+ * `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+ * redefined, or removed. The stored document (`hooks.records` in the harness
+ * settings file) is the only source of truth, so a hook added from a
+ * configuration surface survives a restart and one added by hand-editing that
+ * document mounts without one.
+ *
+ * A record either points at an existing hook document (`configPath`) or carries
+ * its definitions inline. Inline definitions are materialized under the harness
+ * home, because both bridges read one file path at load.
+ * @module @hydraharness/harness-hooks-registry
+ */
+import { Service, type Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { type SettingsProvider } from '@hydraharness/harness-settings';
+import type { HookRecordDefinitionRequest, HookRecordEnablementRequest, HookRecordSnapshot } from './types.ts';
+export type * from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        /** User-declared hook records and their live bridge mounts. */
+        hookRecords: HookRecordRegistry;
+    }
+}
+/** Settings namespace holding every user-declared hook record. */
+export declare const HOOKS_SETTINGS_NAMESPACE: import("@hydraharness/harness-settings").SettingsNamespace;
+/** Registry configuration. */
+export interface Config {
+    /** Override the resolved harness home that holds materialized inline documents. */
+    hydraHome?: string;
+    /** Absolute workspace directory for relative document paths and hook commands. */
+    cwd?: string;
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+export declare const inject: string[];
+/**
+ * Settings-backed hook records with their live bridge mounts. Reconciliation is
+ * idempotent and runs on one serialized chain, so a document commit from any
+ * source — this service's own write, another process, or a hand edit —
+ * converges the mounted set on the stored one.
+ * Mutations reject with `SettingsConflictError` if another writer changes the
+ * stored section after the read; retry uses the refreshed projection.
+ */
+export declare class HookRecordRegistry extends Service {
+    static inject: string[];
+    /** Bridge mounts belong to this Host service, not to a traced API caller. */
+    private readonly owner;
+    static Config: z<Config>;
+    private readonly settings;
+    private readonly live;
+    /** Stored records this registry refuses to mount, with the refusal reason. */
+    private readonly invalid;
+    /** Directory holding the documents materialized from inline definitions. */
+    private readonly inlineRoot;
+    private readonly cwd;
+    private tail;
+    private stopped;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Project every stored record with its live state.
+     * @param settings - optional layer whose desired records to project.
+     * @returns the current record projection, in stored order.
+     */
+    list(settings?: SettingsProvider): HookRecordSnapshot;
+    /**
+     * Reconcile the current effective settings after a layer or trust change.
+     * @returns completion after earlier queued work and the current mounts settle.
+     */
+    settle(): Promise<void>;
+    /**
+     * Create or replace one complete definition as requested, then
+     * converge the mounted set. A definition this registry could not mount is
+     * refused before anything persists.
+     * @param request - complete record definition.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     * @throws If create names an existing record or replace names a missing record.
+     */
+    define(request: HookRecordDefinitionRequest, settings?: SettingsProvider): Promise<HookRecordSnapshot>;
+    /**
+     * Change one stored record's desired state.
+     * @param request - target record and desired state.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     */
+    setEnabled(request: HookRecordEnablementRequest, settings?: SettingsProvider): Promise<HookRecordSnapshot>;
+    /**
+     * Remove one stored record, unmount it, and delete any document this registry
+     * materialized for it.
+     * @param name - stored record name.
+     * @param settings - selected write layer; omitted uses this registry's provider.
+     * @returns the refreshed projection.
+     */
+    remove(name: string, settings?: SettingsProvider): Promise<HookRecordSnapshot>;
+    /** Read the selected layer's desired records, including overrides suppressed by trust. */
+    private writeSource;
+    /** Serialize every mutation and reconciliation on one chain. */
+    private enqueue;
+    /**
+     * Converge the mounted set on the stored one: unmount every record that is
+     * gone, disabled, or redefined, then mount every enabled record that is not
+     * already live from the same definition. A record whose document is missing,
+     * unparseable, or refused by its dialect is recorded as `invalid` with the
+     * diagnostic and does not stop the others.
+     */
+    private reconcile;
+    /**
+     * Materialize the record's document when it is inline, then start its
+     * dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+     * hand-edited document must not stop every other record from mounting.
+     */
+    private mount;
+    /**
+     * Resolve the document path the bridge reads: a `file` record's own path, or
+     * the harness-home document this registry writes from inline definitions.
+     * Materialization is idempotent and re-runs per mount, so an edited inline
+     * section always reaches the bridge.
+     */
+    private materialize;
+    /** Read one record's raw definitions, from its file or its inline section. */
+    private readDefinitions;
+    /** Path of the document this registry materializes for one inline record. */
+    private inlinePath;
+    /** Resolve a read-only document or substitution path inside the owning cwd. */
+    private documentPath;
+    /** Project one stored record with its live state. */
+    private view;
+    /** Refuse new work, then unmount every live record. */
+    private shutdown;
+}
+export default HookRecordRegistry;
+//# sourceMappingURL=index.d.ts.map