@bjorntech/key-ferry 0.1.12 → 0.1.14

package/README.md

@@ -36,6 +36,11 @@ Direct provider/API transport protection is not included.
 - Varlock CLI 1.23.0 installed separately as `varlock`
 - An installed Varlock CLI and a configured Varlock environment/schema with the
   secrets and proxy rules your MCP servers need
+- A private, writable runtime directory for ownership records. By default this
+  is `tmpdir()/key-ferry-<uid>`; `adapter.ownershipDirectory` may be used to
+  inject another private, writable directory. If it cannot be secured, startup
+  fails closed with the `ownership_unavailable` diagnostic (also shown by
+  `key-ferry.doctor`).
 - Configure secret sources and authentication following the
   [Varlock documentation](https://varlock.dev/)
 
@@ -194,6 +199,21 @@ filters requested keys. Mark each remote upstream host with `@proxy(domain="..."
 Key Ferry does not install Varlock, create its schema, or configure provider
 authentication. Never commit a real secret.
 
+Broker processes remain available for `idleTimeoutMs` milliseconds after the
+last lease is released (default: `600000`, or ten minutes). This reuses the
+authenticated Varlock proxy when returning to a project. Set
+`idleTimeoutMs: 0` for immediate teardown; idle brokers are always stopped on
+host shutdown or when their schema/configuration identity changes. This is a
+security/performance trade-off: resolved secrets remain in the proxy process's
+memory for up to the idle timeout after leaving a project. On startup Key Ferry
+also reaps orphaned, identity-checked proxy records left by an earlier process.
+If stopping a proxy fails during shutdown, Key Ferry keeps its ownership record and
+defers cleanup to the next startup, whose reaper retries the same session UUID.
+On SIGINT or SIGTERM it performs bounded cleanup (up to three seconds), removes
+its signal listener, and re-raises the signal when it is the only listener so
+the host's normal termination semantics are preserved; host-owned signal
+listeners remain in control.
+
 ## TUI commands
 
 | Palette command | Slash command | RPC |

package/dist/broker-registry.d.ts

@@ -10,20 +10,52 @@ export interface BrokerLease extends ProjectKeyFerryManagerService {
 }
 export interface BrokerRegistryOptions {
     readonly canonicalize?: (directory: string) => Effect.Effect<string, unknown>;
+    /** Supplies the schema fingerprint; the default retains the real filesystem implementation. */
+    readonly schemaHash?: (directory: string) => Effect.Effect<string, unknown>;
     readonly maxEntries?: number;
+    readonly now?: () => number;
+    readonly idleTimeoutMs?: number;
+    readonly logger?: (event: BrokerLogEvent) => void;
+    readonly hostShutdownHooks?: boolean;
+}
+export interface BrokerLogEvent {
+    readonly event: "start" | "ready" | "release" | "idle-scheduled" | "reused" | "disposed" | "stop-failed" | "dispose-failed" | "stale-reaped" | "stale-skipped";
+    readonly scope: "global" | "project";
+    readonly directory: string;
+    readonly keyHash: string;
+    readonly pid?: number;
+    readonly proxySessionId?: string;
 }
 type BrokerResult = {
     readonly status: SafeStatus;
     readonly environment: ResolvedEnvironment;
 };
+export declare const RETRY_BASE_DELAY_MS = 5000;
+export declare const RETRY_MAX_DELAY_MS = 300000;
+export declare const retryDelayMs: (failureCount: number) => number;
 /** A module-local broker; it deliberately does not communicate across processes. */
 export declare function makeBrokerRegistry(configuration?: BrokerRegistryOptions): {
     acquire: <R>(factory: ProjectKeyFerryManagerFactory<R>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerLease, any, never>;
     retry: (factory: ProjectKeyFerryManagerFactory<any>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerResult, any, never>;
+    retryIfDue: (factory: ProjectKeyFerryManagerFactory<any>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerResult | undefined, any, never>;
+    shutdown: Effect.Effect<void, never, never>;
 };
+export interface HostSignalProcess {
+    readonly pid: number;
+    readonly on: (event: any, listener: (...args: any[]) => void) => unknown;
+    readonly removeListener: (event: any, listener: (...args: any[]) => void) => unknown;
+    readonly listeners: (event: any) => Function[];
+    readonly kill: (pid: number, signal: "SIGINT" | "SIGTERM") => unknown;
+}
+export declare function removeHostShutdownHooks(): void;
+export declare function installHostShutdownHooks(shutdown: Effect.Effect<void>, signalProcess?: HostSignalProcess, options?: {
+    readonly cleanupTimeoutMs?: number;
+}): (() => void) | undefined;
 export declare const brokerRegistry: {
     acquire: <R>(factory: ProjectKeyFerryManagerFactory<R>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerLease, any, never>;
     retry: (factory: ProjectKeyFerryManagerFactory<any>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerResult, any, never>;
+    retryIfDue: (factory: ProjectKeyFerryManagerFactory<any>, options: ProjectKeyFerryManagerOptions) => Effect.Effect<BrokerResult | undefined, any, never>;
+    shutdown: Effect.Effect<void, never, never>;
 };
 export type BrokerRegistry = ReturnType<typeof makeBrokerRegistry>;
 export {};

package/dist/broker-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broker-registry.d.ts","sourceRoot":"","sources":["../src/broker-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,MAAM,EAON,MAAM,EACP,MAAM,QAAQ,CAAC;AAChB,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAY,SAAQ,6BAA6B;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,KAAK,YAAY,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC;AA0H/F,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,qBAA0B;cAwPzD,CAAC,WACP,6BAA6B,CAAC,CAAC,CAAC,WAChC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC;qBA2B9B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC;EAiD3C;AAED,eAAO,MAAM,cAAc;cAnFR,CAAC,WACP,6BAA6B,CAAC,CAAC,CAAC,WAChC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC;qBA2B9B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC;CAmDM,CAAC;AACnD,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"broker-registry.d.ts","sourceRoot":"","sources":["../src/broker-registry.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,MAAM,EAON,MAAM,EACP,MAAM,QAAQ,CAAC;AAChB,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,UAAU,EAEhB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,WAAY,SAAQ,6BAA6B;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9E,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAClD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EACV,OAAO,GACP,OAAO,GACP,SAAS,GACT,gBAAgB,GAChB,QAAQ,GACR,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,KAAK,YAAY,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE/F,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AACzC,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C,eAAO,MAAM,YAAY,GAAI,cAAc,MAAM,WACuC,CAAC;AA8LzF,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,qBAA0B;cA4bzD,CAAC,WACP,6BAA6B,CAAC,CAAC,CAAC,WAChC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC;qBAsD9B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC;0BA8D/B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,GAAG,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC;;EAwCvD;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IACzE,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,KAAK,OAAO,CAAC;IACrF,QAAQ,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,EAAE,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,KAAK,OAAO,CAAC;CACvE;AAoCD,wBAAgB,uBAAuB,IAAI,IAAI,CAI9C;AACD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAC7B,aAAa,GAAE,iBAA2B,EAC1C,OAAO,GAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAiD1B;AAED,eAAO,MAAM,cAAc;cA7QR,CAAC,WACP,6BAA6B,CAAC,CAAC,CAAC,WAChC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,EAAE,KAAK,CAAC;qBAsD9B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,EAAE,KAAK,CAAC;0BA8D/B,6BAA6B,CAAC,GAAG,CAAC,WAClC,6BAA6B,KACrC,MAAM,CAAC,MAAM,CAAC,YAAY,GAAG,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC;;CAqJtD,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/broker-registry.js

@@ -1,6 +1,15 @@
-import { realpath } from "node:fs/promises";
-import { Context, Deferred, Effect, Exit, Fiber, Layer, PubSub, Scope, Semaphore, Stream, } from "effect";
+import { createHash } from "node:crypto";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { Context, Deferred, Duration, Effect, Exit, Fiber, Layer, PubSub, Scope, Semaphore, Stream, } from "effect";
 import { ProjectKeyFerryManager, VarlockError, } from "./contracts.js";
+import { setOwnershipLifecycleLogger } from "./varlock/ownership.js";
+export const RETRY_BASE_DELAY_MS = 5_000;
+export const RETRY_MAX_DELAY_MS = 300_000;
+export const retryDelayMs = (failureCount) => Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** Math.max(0, failureCount - 1));
+function retryPending(entry) {
+    return entry.attempt && entry.attemptPending ? { pending: entry.attempt } : undefined;
+}
 const adapterKeys = new Set([
     "command",
     "environmentKeys",
@@ -9,6 +18,7 @@ const adapterKeys = new Set([
     "reloadTimeoutMs",
     "pollIntervalMs",
     "requireStrictEgress",
+    "idleTimeoutMs",
 ]);
 function safeError(error, code) {
     if (error instanceof VarlockError)
@@ -51,19 +61,70 @@ function validateOptions(options) {
     validateAdapterShape(adapter);
     return adapter;
 }
-function keyFor(directory, options) {
-    const adapter = validateOptions(options);
-    return stable({
-        projectDirectory: directory,
-        owner: options.owner,
-        sessionID: options.sessionID,
-        command: adapter.command,
-        environmentKeys: [...new Set(adapter.environmentKeys)].sort(),
-        startupTimeoutMs: adapter.startupTimeoutMs,
-        commandTimeoutMs: adapter.commandTimeoutMs,
-        reloadTimeoutMs: adapter.reloadTimeoutMs,
-        pollIntervalMs: adapter.pollIntervalMs,
-        requireStrictEgress: adapter.requireStrictEgress,
+const schemaHashCache = new Map();
+async function contentHash(directory) {
+    const hash = createHash("sha256");
+    try {
+        const names = (await readdir(directory))
+            .filter((name) => name === ".env.schema" || name.startsWith(".env.schema."))
+            .sort();
+        const metadata = await Promise.all(names.map(async (name) => {
+            const info = await stat(join(directory, name));
+            return `${name}:${info.mtimeMs}:${info.size}`;
+        }));
+        const signature = metadata.join("\0");
+        const cached = schemaHashCache.get(directory);
+        if (cached?.signature === signature)
+            return cached.hash;
+        for (const name of names) {
+            hash.update(name);
+            hash.update(await readFile(join(directory, name)));
+        }
+        const result = hash.digest("hex");
+        schemaHashCache.set(directory, { signature, hash: result });
+        return result;
+    }
+    catch {
+        // The manager performs the authoritative directory validation. Keep the
+        // registry usable with injected/test canonicalizers and distinguish an
+        // unreadable schema from a real schema without exposing its contents.
+        hash.update("schema-unavailable");
+    }
+    return hash.digest("hex");
+}
+function keyFor(directory, options, schemaHash) {
+    return Effect.gen(function* () {
+        const adapter = validateOptions(options);
+        const keys = [
+            ...new Set([
+                ...adapter.environmentKeys,
+                ...Object.keys(globalThis.process.env).filter((key) => /^OP_/.test(key)),
+            ]),
+        ].sort();
+        const valuesHash = createHash("sha256");
+        for (const key of keys)
+            valuesHash.update(`${key}\0${globalThis.process.env[key] ?? ""}\0`);
+        const context = {
+            projectDirectory: directory,
+            owner: options.owner,
+            sessionID: options.sessionID,
+            command: adapter.command,
+            environmentKeys: [...new Set(adapter.environmentKeys)].sort(),
+            startupTimeoutMs: adapter.startupTimeoutMs,
+            commandTimeoutMs: adapter.commandTimeoutMs,
+            reloadTimeoutMs: adapter.reloadTimeoutMs,
+            pollIntervalMs: adapter.pollIntervalMs,
+            requireStrictEgress: adapter.requireStrictEgress,
+            idleTimeoutMs: adapter.idleTimeoutMs,
+        };
+        return {
+            contextKey: stable(context),
+            key: stable({
+                ...context,
+                environmentValuesHash: valuesHash.digest("hex"),
+                schemaHash: yield* schemaHash(directory),
+            }),
+        };
     });
 }
 function readinessChanged(entry, revision, ready) {
@@ -96,31 +157,107 @@ function awaitCurrentReady(entry) {
 export function makeBrokerRegistry(configuration = {}) {
     const entries = new Set();
     const factories = new WeakMap();
+    const factoryMaps = new Set();
     const lock = Effect.runSync(Semaphore.make(1));
     const canonicalize = configuration.canonicalize ??
         ((directory) => Effect.tryPromise(() => realpath(directory)));
+    const schemaHash = configuration.schemaHash ??
+        ((directory) => Effect.tryPromise(() => contentHash(directory)));
     const maxEntries = configuration.maxEntries ?? 128;
+    const now = configuration.now ?? (() => Date.now());
+    // Direct registry consumers historically received immediate teardown. The
+    // validated plugin adapter always supplies the public ten-minute default;
+    // retaining this fallback keeps injected/test registries backwards compatible.
+    const idleTimeoutMs = configuration.idleTimeoutMs ?? 0;
+    const log = (entry, event) => {
+        configuration.logger?.({
+            event,
+            scope: entry.options.owner === "key-ferry" ? "project" : "global",
+            directory: entry.options.projectDirectory,
+            keyHash: createHash("sha256").update(entry.key).digest("hex").slice(0, 12),
+            ...(entry.status?.pid === undefined ? {} : { pid: entry.status.pid }),
+            ...(entry.status
+                ?.proxySessionId === undefined
+                ? {}
+                : {
+                    proxySessionId: entry.status
+                        .proxySessionId,
+                }),
+        });
+    };
     const publish = (entry, status) => {
         entry.status = status;
         return PubSub.publish(entry.events, status);
     };
+    const recordFailure = (entry, failure) => {
+        entry.failure = failure;
+        entry.failureCount += 1;
+        entry.lastFailureAt = new Date(now()).toISOString();
+        entry.nextRetryAt = new Date(now() + retryDelayMs(entry.failureCount)).toISOString();
+        return {
+            lastFailureAt: entry.lastFailureAt,
+            nextRetryAt: entry.nextRetryAt,
+        };
+    };
+    const clearFailure = (entry) => {
+        entry.failure = undefined;
+        entry.failureCount = 0;
+        entry.lastFailureAt = undefined;
+        entry.nextRetryAt = undefined;
+        entry.retryBatch = undefined;
+    };
+    const capacityFailure = () => Effect.die(new Error("broker registry capacity reached"));
+    const disposeStaleEntries = (factoryMap, contextKey) => Effect.gen(function* () {
+        for (const [oldKey, oldEntry] of factoryMap) {
+            if (oldEntry.contextKey !== contextKey || oldEntry.leases.size > 0)
+                continue;
+            yield* disposeEntry(oldEntry);
+            entries.delete(oldEntry);
+            factoryMap.delete(oldKey);
+        }
+    });
+    const disposeEntry = (entry) => Effect.gen(function* () {
+        log(entry, "disposed");
+        if (entry.idleFiber) {
+            yield* Fiber.interrupt(entry.idleFiber);
+            entry.idleFiber = undefined;
+        }
+        if (entry.startup)
+            yield* Fiber.interrupt(entry.startup);
+        if (entry.manager) {
+            yield* entry.manager.dispose.pipe(Effect.catch(() => Effect.sync(() => {
+                // The manager may have left the ownership record in place. Drop
+                // the in-process entry, but make the startup reaper handoff
+                // explicit so cleanup is still observable without error text.
+                log(entry, "dispose-failed");
+            })));
+        }
+        yield* Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
+        entry.manager = undefined;
+        entry.disposed = true;
+        entry.idleUntil = undefined;
+    }).pipe(Effect.catch(() => Effect.void));
     const start = (entry) => {
         const operation = Effect.gen(function* () {
             const context = yield* Layer.build(entry.factory.layer(entry.options)).pipe(Effect.provideService(Scope.Scope, entry.scope));
             const manager = Context.get(context, ProjectKeyFerryManager);
             entry.manager = manager;
+            entry.status = yield* manager.status;
+            log(entry, "start");
             const result = yield* manager.ensureReady;
+            log(entry, "ready");
             yield* publish(entry, result.status);
             return result;
         });
         return operation.pipe(Effect.catch((error) => {
             const failure = safeError(error, "start_failed");
-            entry.failure = failure;
+            const metadata = recordFailure(entry, failure);
             return publish(entry, {
                 phase: "failed",
                 projectDirectory: entry.options.projectDirectory,
                 generation: entry.status?.generation ?? 0,
                 error: failure,
+                ...metadata,
             }).pipe(Effect.flatMap(() => Effect.fail(failure)));
         }));
     };
@@ -133,7 +270,9 @@ export function makeBrokerRegistry(configuration = {}) {
         }
         return yield* awaitCurrentReady(entry);
     });
-    const completeStartup = (entry, target) => Fiber.join(entry.startup).pipe(Effect.flatMap((result) => Deferred.succeed(target, result)), Effect.catch((error) => Deferred.fail(target, safeError(error, "start_failed"))), Effect.tap(() => Effect.sync(() => {
+    const completeStartup = (entry, target) => Fiber.join(entry.startup).pipe(Effect.flatMap((result) => Effect.sync(() => clearFailure(entry)).pipe(Effect.andThen(Deferred.succeed(target, result)))), Effect.catch((error) => Effect.sync(() => {
+        entry.attemptPending = false;
+    }).pipe(Effect.andThen(Deferred.fail(target, safeError(error, "start_failed"))))), Effect.tap(() => Effect.sync(() => {
         entry.attemptPending = false;
     })), Effect.forkDetach);
     const refreshShared = (entry) => Effect.gen(function* () {
@@ -159,13 +298,14 @@ export function makeBrokerRegistry(configuration = {}) {
                 entry.refresh = undefined;
             }).pipe(Effect.catch((error) => {
                 const failure = safeError(error, "refresh_failed");
-                entry.failure = failure;
+                const metadata = recordFailure(entry, failure);
                 entry.refresh = undefined;
                 return publish(entry, {
                     phase: "failed",
                     projectDirectory: entry.options.projectDirectory,
                     generation: entry.status?.generation ?? 0,
                     error: failure,
+                    ...metadata,
                 }).pipe(Effect.flatMap(() => Deferred.fail(next, failure)));
             }), Effect.forkIn(entry.scope));
             return next;
@@ -173,14 +313,16 @@ export function makeBrokerRegistry(configuration = {}) {
         return yield* Deferred.await(deferred);
     });
     const getOrCreateEntry = (factory, options, directory) => Effect.gen(function* () {
-        const key = keyFor(directory, options);
+        const identity = yield* keyFor(directory, options, schemaHash).pipe(Effect.orDie);
+        const key = identity.key;
         const factoryMap = factories.get(factory) ?? new Map();
         factories.set(factory, factoryMap);
+        factoryMaps.add(factoryMap);
         const existing = factoryMap.get(key);
         if (existing)
             return existing;
         if (entries.size >= maxEntries)
-            return yield* Effect.die(new Error("broker registry capacity reached"));
+            return yield* capacityFailure();
         const entry = {
             key,
             options: {
@@ -194,7 +336,10 @@ export function makeBrokerRegistry(configuration = {}) {
             leases: new Set(),
             readinessRevision: 0,
             disposed: false,
+            failureCount: 0,
+            contextKey: identity.contextKey,
         };
+        yield* disposeStaleEntries(factoryMap, identity.contextKey);
         factoryMap.set(key, entry);
         entries.add(entry);
         return entry;
@@ -202,9 +347,7 @@ export function makeBrokerRegistry(configuration = {}) {
     const disposeLeaseEntry = (entry, factoryMap, close) => Effect.gen(function* () {
         if (entry.startup)
             yield* Fiber.interrupt(entry.startup);
-        if (entry.manager)
-            yield* entry.manager.dispose;
-        yield* Scope.close(entry.scope, Exit.void);
+        yield* disposeEntry(entry);
     }).pipe(Effect.catch(() => Effect.void), Effect.flatMap(() => lock.withPermit(Effect.gen(function* () {
         if (entry.closing !== close)
             return;
@@ -217,13 +360,71 @@ export function makeBrokerRegistry(configuration = {}) {
         entry.closing = undefined;
         yield* Deferred.succeed(close, undefined);
     }))));
+    const scheduleIdle = (entry, factoryMap, directory, timeout) => Effect.gen(function* () {
+        entry.idleUntil = new Date(now() + timeout).toISOString();
+        log(entry, "idle-scheduled");
+        yield* publish(entry, {
+            ...(entry.status ?? { phase: "idle", projectDirectory: directory, generation: 0 }),
+            phase: "idle",
+            idleUntil: entry.idleUntil,
+        });
+        entry.idleFiber = yield* Effect.sleep(Duration.millis(timeout)).pipe(Effect.andThen(Effect.gen(function* () {
+            if (entry.leases.size === 0 && !entry.disposed) {
+                entry.disposed = true;
+                const deferred = yield* Deferred.make();
+                entry.closing = deferred;
+                yield* disposeLeaseEntry(entry, factoryMap, deferred).pipe(Effect.forkDetach);
+            }
+        })), Effect.forkIn(entry.scope));
+    });
+    const closeImmediately = (entry, factoryMap, required) => Effect.gen(function* () {
+        if (!required)
+            return undefined;
+        entry.disposed = true;
+        const deferred = yield* Deferred.make();
+        entry.closing = deferred;
+        yield* disposeLeaseEntry(entry, factoryMap, deferred).pipe(Effect.forkDetach);
+        return deferred;
+    });
+    const releaseLease = (entry, factoryMap, leaseID, directory, isReleased, markReleased) => lock.withPermit(Effect.gen(function* () {
+        if (isReleased())
+            return undefined;
+        markReleased();
+        log(entry, "release");
+        entry.leases.delete(leaseID);
+        return yield* releaseAfterDelete(entry, factoryMap, directory);
+    }));
+    const releaseAfterDelete = (entry, factoryMap, directory) => entry.leases.size !== 0 || entry.disposed
+        ? Effect.succeed(undefined)
+        : releaseLastLease(entry, factoryMap, directory);
+    const releaseLastLease = (entry, factoryMap, directory) => Effect.gen(function* () {
+        const timeout = Number(entry.options.adapter.idleTimeoutMs ?? idleTimeoutMs);
+        const immediate = yield* closeImmediately(entry, factoryMap, entry.failure !== undefined || timeout <= 0);
+        if (immediate)
+            return immediate;
+        yield* scheduleIdle(entry, factoryMap, directory, timeout);
+        return undefined;
+    });
+    const reuseIdle = (entry) => Effect.gen(function* () {
+        if (!entry.idleFiber)
+            return;
+        yield* Fiber.interrupt(entry.idleFiber);
+        entry.idleFiber = undefined;
+        entry.idleUntil = undefined;
+        entry.disposed = false;
+        if (entry.status?.phase === "idle")
+            yield* publish(entry, { ...entry.status, phase: "ready", idleUntil: undefined });
+        log(entry, "reused");
+    });
     const acquireAttempt = (factory, options) => lock.withPermit(Effect.gen(function* () {
         const directory = yield* canonicalize(options.projectDirectory).pipe(Effect.mapError(() => new TypeError("project directory does not exist")));
         const factoryMap = factories.get(factory) ?? new Map();
         factories.set(factory, factoryMap);
+        factoryMaps.add(factoryMap);
         const entry = yield* getOrCreateEntry(factory, options, directory);
         if (entry.closing)
             return { waiting: entry.closing };
+        yield* reuseIdle(entry);
         const leaseID = Symbol();
         entry.leases.add(leaseID);
         if (!entry.startup && !entry.failure) {
@@ -239,19 +440,7 @@ export function makeBrokerRegistry(configuration = {}) {
             return yield* operation(entry.manager);
         });
         const release = Effect.gen(function* () {
-            const close = yield* lock.withPermit(Effect.gen(function* () {
-                if (released)
-                    return undefined;
-                released = true;
-                entry.leases.delete(leaseID);
-                if (entry.leases.size !== 0 || entry.disposed)
-                    return undefined;
-                entry.disposed = true;
-                const deferred = yield* Deferred.make();
-                entry.closing = deferred;
-                yield* disposeLeaseEntry(entry, factoryMap, deferred).pipe(Effect.forkDetach);
-                return deferred;
-            }));
+            const close = yield* releaseLease(entry, factoryMap, leaseID, directory, () => released, () => (released = true));
             if (close)
                 yield* Deferred.await(close);
         });
@@ -296,10 +485,30 @@ export function makeBrokerRegistry(configuration = {}) {
     const retryAttempt = (factory, options) => Effect.gen(function* () {
         const directory = yield* canonicalize(options.projectDirectory);
         const target = yield* lock.withPermit(Effect.gen(function* () {
-            const entry = factories.get(factory)?.get(keyFor(directory, options));
+            const entry = factories
+                .get(factory)
+                ?.get((yield* keyFor(directory, options, schemaHash)).key);
+            if (entry?.retryBatch)
+                return entry.retryBatch;
+            if (entry) {
+                const initial = yield* retryEntry(entry);
+                if ("waiting" in initial || "pending" in initial)
+                    return initial;
+                const batch = yield* Deferred.make();
+                entry.retryBatch = batch;
+                yield* Deferred.await(initial).pipe(Effect.matchEffect({
+                    onSuccess: (result) => Deferred.succeed(batch, result),
+                    onFailure: (error) => Deferred.fail(batch, error),
+                }), 
+                // Keep the completed batch as the result of this explicit
+                // retry. A background retry clears it when its deadline is due
+                // and atomically establishes the next batch.
+                Effect.andThen(Effect.void), Effect.forkDetach);
+                return batch;
+            }
             return yield* retryEntry(entry);
         }));
-        if ("waiting" in target)
+        if ("waiting" in target || "pending" in target)
             return target;
         return yield* Deferred.await(target);
     });
@@ -309,6 +518,12 @@ export function makeBrokerRegistry(configuration = {}) {
             yield* Deferred.await(result.waiting);
             return yield* retry(factory, options);
         }
+        if ("pending" in result) {
+            // This caller observed an attempt already in flight. Its result is the
+            // result of this retry operation; do not turn a shared failure into a
+            // fresh attempt when the pending attempt completes.
+            return yield* Deferred.await(result.pending);
+        }
         return result;
     });
     const retryEntry = (entry) => {
@@ -320,8 +535,9 @@ export function makeBrokerRegistry(configuration = {}) {
             }));
         if (entry.closing)
             return Effect.succeed({ waiting: entry.closing });
-        if (entry.attempt && entry.attemptPending)
-            return Effect.succeed(entry.attempt);
+        const pending = retryPending(entry);
+        if (pending)
+            return Effect.succeed(pending);
         if (!entry.failure)
             return Effect.fail(new VarlockError({
                 code: "not_ready",
@@ -329,6 +545,10 @@ export function makeBrokerRegistry(configuration = {}) {
                 retryable: false,
             }));
         return Effect.gen(function* () {
+            // The previous attempt is complete (attemptPending was checked above),
+            // so closing its scope cannot race a startup. This runs manager and
+            // certificate-directory finalizers before allocating the replacement.
+            yield* Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
             entry.failure = undefined;
             entry.disposed = false;
             entry.scope = yield* Scope.make();
@@ -341,7 +561,121 @@ export function makeBrokerRegistry(configuration = {}) {
             return entry.ready;
         });
     };
-    return { acquire, retry };
+    const retryIfDue = (factory, options) => Effect.gen(function* () {
+        const directory = yield* canonicalize(options.projectDirectory);
+        const entry = factories
+            .get(factory)
+            ?.get((yield* keyFor(directory, options, schemaHash)).key);
+        if (!entry?.failure || (entry.nextRetryAt && now() < Date.parse(entry.nextRetryAt)))
+            return undefined;
+        entry.retryBatch = undefined;
+        return yield* retry(factory, options).pipe(Effect.catch((error) => error instanceof VarlockError && error.code === "not_ready"
+            ? Effect.succeed(undefined)
+            : Effect.fail(error)));
+    });
+    let unregisterOwnershipLogger = () => undefined;
+    const shutdown = Effect.uninterruptible(Effect.gen(function* () {
+        removeHooksWhenConfigured(configuration.hostShutdownHooks);
+        const current = [...entries];
+        yield* Effect.forEach(current, (entry) => disposeEntry(entry), { concurrency: "unbounded" });
+        for (const map of factoryMaps)
+            map.clear();
+        entries.clear();
+        unregisterOwnershipLogger();
+    }));
+    installHooksWhenConfigured(configuration.hostShutdownHooks, shutdown);
+    unregisterOwnershipLogger = setOwnershipLifecycleLogger((event) => configuration.logger?.({
+        ...event,
+        scope: "project",
+        directory: "",
+        keyHash: event.keyHash,
+    }));
+    return { acquire, retry, retryIfDue, shutdown };
+}
+let hostHooks;
+let hostShutdown;
+function removeHooksWhenConfigured(enabled) {
+    if (enabled)
+        removeHostShutdownHooks();
+}
+function installHooksWhenConfigured(enabled, shutdown) {
+    if (enabled)
+        installHostShutdownHooks(shutdown);
+}
+function signalListener(name, onSigInt, onSigTerm) {
+    return name === "SIGINT" ? onSigInt : onSigTerm;
+}
+function reraiseSignal(signalProcess, name, listener) {
+    signalProcess.removeListener(name, listener);
+    signalProcess.kill(signalProcess.pid, name);
+}
+function finishSignalCleanup(signalProcess, name, listener, active) {
+    if (!active && signalProcess.listeners(name).length > 0)
+        return;
+    const others = signalProcess.listeners(name).filter((item) => item !== listener);
+    signalProcess.removeListener(name, listener);
+    if (others.length === 0)
+        signalProcess.kill(signalProcess.pid, name);
+}
+export function removeHostShutdownHooks() {
+    hostHooks?.();
+    hostHooks = undefined;
+    hostShutdown = undefined;
+}
+export function installHostShutdownHooks(shutdown, signalProcess = process, options = {}) {
+    if (hostHooks)
+        return;
+    hostShutdown = shutdown;
+    let active = true;
+    const beforeExit = () => {
+        if (active)
+            void Effect.runPromise(hostShutdown).catch(() => undefined);
+    };
+    let cleaning = false;
+    // Node and Bun suppress their default signal termination while a signal
+    // listener is installed. Cleanup is bounded; `exit` cannot await work and
+    // is covered by the startup ownership reaper instead.
+    const boundedTimer = (resolve) => {
+        const timer = setTimeout(resolve, options.cleanupTimeoutMs ?? 3_000);
+        timer.unref?.();
+        return timer;
+    };
+    const signal = (name) => {
+        if (!active)
+            return;
+        const listener = signalListener(name, onSigInt, onSigTerm);
+        if (cleaning) {
+            reraiseSignal(signalProcess, name, listener);
+            return;
+        }
+        cleaning = true;
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = boundedTimer(resolve);
+        });
+        void Promise.race([Effect.runPromise(hostShutdown).catch(() => undefined), timeout]).finally(() => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // shutdown() removes the hooks at its start, so do not let that normal
+            // cleanup path suppress the signal re-raise requested by this handler.
+            finishSignalCleanup(signalProcess, name, listener, active);
+        });
+    };
+    const onSigInt = () => signal("SIGINT");
+    const onSigTerm = () => signal("SIGTERM");
+    signalProcess.on("beforeExit", beforeExit);
+    signalProcess.on("SIGINT", onSigInt);
+    signalProcess.on("SIGTERM", onSigTerm);
+    hostHooks = () => {
+        active = false;
+        signalProcess.removeListener("beforeExit", beforeExit);
+        signalProcess.removeListener("SIGINT", onSigInt);
+        signalProcess.removeListener("SIGTERM", onSigTerm);
+    };
+    return hostHooks;
 }
-export const brokerRegistry = makeBrokerRegistry();
+export const brokerRegistry = makeBrokerRegistry({
+    idleTimeoutMs: 600_000,
+    hostShutdownHooks: true,
+});
 //# sourceMappingURL=broker-registry.js.map