@vellumai/assistant 0.10.6 → 0.10.7-dev.202607072325.09ad030

package/src/hooks/__tests__/hook-live-reload.test.ts

@@ -1,11 +1,10 @@
 /**
  * Pins the eviction primitives hook live-reload is built on, driven through
- * the production import machinery (`preImportHooksDir` →
- * `collectUserHookEntries`), one layer below the sentinel-driven reconcile
- * that orchestrates them in production (see `../../plugins/mtime-cache.ts`
- * and its end-to-end suite).
+ * the production resolution path (`resolveHook` behind `collectUserHookEntries`),
+ * one layer below the sentinel-driven reconcile that orchestrates them in
+ * production (see `../../plugins/mtime-cache.ts` and its end-to-end suite).
  *
- * Two invariants live here:
+ * Three invariants live here:
  *
  * 1. **The Bun primitive.** Deleting a file's `require.cache` entry makes
  *    the next dynamic `import()` re-evaluate it from disk. This is
@@ -14,10 +13,15 @@
  *    Bun upgrade that breaks it must fail here rather than silently degrade
  *    hook edits back to restart-required.
  *
- * 2. **Whole-owner eviction.** Evicting only a hook's own module re-binds
+ * 2. **Whole-plugin module sweep.** Evicting only a hook's own module re-binds
  *    the re-imported hook to its stale cached helpers. The reconcile sweeps
  *    every path in the plugin for exactly this reason, and this suite pins
  *    the failure mode that rule prevents.
+ *
+ * 3. **Negative caching.** A hook an owner doesn't define resolves to a cached
+ *    absence, so it is stat'd once rather than re-stat'd every dispatch; the
+ *    absence only lifts when the owner is evicted (as the reconcile does on a
+ *    source change).
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -30,7 +34,6 @@ import type { HookEntry } from "../../plugins/types.js";
 import {
   collectUserHookEntries,
   evictHooksForOwner,
-  preImportHooksDir,
   resetHookCacheForTests,
 } from "../hook-loader.js";
 
@@ -58,18 +61,15 @@ function makePlugin(): { dir: string; hooksDir: string; name: string } {
 }
 
 /**
- * Redeploy an owner's hooks the way the reconcile does: drop its cache
- * entries, sweep the given module paths, and re-import from disk.
+ * Redeploy an owner's hooks the way the reconcile does: drop its cached
+ * resolutions and sweep the given module paths. The next read re-resolves
+ * from disk.
  */
-async function redeploy(
-  plugin: { hooksDir: string; name: string },
-  modulePaths: string[],
-): Promise<void> {
-  evictHooksForOwner(plugin.name);
+function redeploy(plugin: { name: string }, modulePaths: string[]): void {
+  evictHooksForOwner("plugin", plugin.name);
   for (const path of modulePaths) {
     evictModule(path);
   }
-  await preImportHooksDir(plugin.hooksDir, plugin.name);
 }
 
 /** Collect and run the single expected hook, returning its result. */
@@ -89,7 +89,6 @@ describe("hook reload primitives", () => {
     const plugin = makePlugin();
     const hookPath = join(plugin.hooksDir, `${HOOK_NAME}.ts`);
     writeFileSync(hookPath, `export default () => "v1";\n`);
-    await preImportHooksDir(plugin.hooksDir, plugin.name);
     expect(await dispatchOne(plugin)).toBe("v1");
 
     // Two edit → redeploy cycles: the first proves the primitive, the
@@ -99,7 +98,7 @@ describe("hook reload primitives", () => {
         hookPath,
         `export default () => ${JSON.stringify(marker)};\n`,
       );
-      await redeploy(plugin, [hookPath]);
+      redeploy(plugin, [hookPath]);
       expect(await dispatchOne(plugin)).toBe(marker);
     }
   });
@@ -110,7 +109,6 @@ describe("hook reload primitives", () => {
       join(plugin.hooksDir, `${HOOK_NAME}.ts`),
       `export default () => "stable";\n`,
     );
-    await preImportHooksDir(plugin.hooksDir, plugin.name);
 
     const first = await collectUserHookEntries(HOOK_NAME, [
       [plugin.dir, plugin.name],
@@ -119,7 +117,8 @@ describe("hook reload primitives", () => {
       [plugin.dir, plugin.name],
     ]);
 
-    // Same function instance: dispatch is a map lookup, not an import.
+    // Same function instance: the second dispatch is a map lookup, not an
+    // import.
     expect(second[0]!.fn).toBe(first[0]!.fn);
   });
 
@@ -132,7 +131,6 @@ describe("hook reload primitives", () => {
       hookPath,
       `import { value } from "../lib/helper.ts";\nexport default () => value;\n`,
     );
-    await preImportHooksDir(plugin.hooksDir, plugin.name);
     expect(await dispatchOne(plugin)).toBe("h1");
 
     writeFileSync(helperPath, `export const value = "h2";\n`);
@@ -140,24 +138,66 @@ describe("hook reload primitives", () => {
     // Partial eviction — the hook file only. The re-evaluated hook binds to
     // the helper module still cached at h1: the version-skew failure mode
     // whole-plugin sweeping exists to prevent.
-    await redeploy(plugin, [hookPath]);
+    redeploy(plugin, [hookPath]);
     expect(await dispatchOne(plugin)).toBe("h1");
 
     // The full sweep (hook + helper, as the reconcile's eviction list would
     // carry) brings the edit through.
-    await redeploy(plugin, [hookPath, helperPath]);
+    redeploy(plugin, [hookPath, helperPath]);
     expect(await dispatchOne(plugin)).toBe("h2");
   });
 
-  test("re-import after owner eviction drops hooks whose files are gone", async () => {
+  test("concurrent first reads of a hook share one import", async () => {
+    const plugin = makePlugin();
+    writeFileSync(
+      join(plugin.hooksDir, `${HOOK_NAME}.ts`),
+      `export default () => "shared";\n`,
+    );
+
+    // Two reads race before the hook is resolved. The resolution memo must make
+    // both await one import and get the same function instance — not import
+    // twice, and not have one read a not-yet-populated entry.
+    const [first, second] = await Promise.all([
+      collectUserHookEntries(HOOK_NAME, [[plugin.dir, plugin.name]]),
+      collectUserHookEntries(HOOK_NAME, [[plugin.dir, plugin.name]]),
+    ]);
+
+    expect(first).toHaveLength(1);
+    expect(second).toHaveLength(1);
+    expect(second[0]!.fn).toBe(first[0]!.fn);
+  });
+
+  test("an absent hook is cached negative until the owner is evicted", async () => {
+    const plugin = makePlugin();
+    const hookPath = join(plugin.hooksDir, `${HOOK_NAME}.ts`);
+
+    // Owner defines no such hook yet — resolves absent, and the absence is
+    // cached.
+    expect(
+      await collectUserHookEntries(HOOK_NAME, [[plugin.dir, plugin.name]]),
+    ).toHaveLength(0);
+
+    // Adding the file without an eviction does not lift the cached absence:
+    // the negative entry is a hit, so the new file is not re-stat'd.
+    writeFileSync(hookPath, `export default () => "added";\n`);
+    expect(
+      await collectUserHookEntries(HOOK_NAME, [[plugin.dir, plugin.name]]),
+    ).toHaveLength(0);
+
+    // Evicting the owner (as the reconcile does on a source change) clears the
+    // negative entry, so the next read picks the hook up.
+    evictHooksForOwner("plugin", plugin.name);
+    expect(await dispatchOne(plugin)).toBe("added");
+  });
+
+  test("re-resolve after owner eviction drops hooks whose files are gone", async () => {
     const plugin = makePlugin();
     const hookPath = join(plugin.hooksDir, `${HOOK_NAME}.ts`);
     writeFileSync(hookPath, `export default () => "here";\n`);
-    await preImportHooksDir(plugin.hooksDir, plugin.name);
     expect(await dispatchOne(plugin)).toBe("here");
 
     rmSync(hookPath);
-    await redeploy(plugin, [hookPath]);
+    redeploy(plugin, [hookPath]);
 
     const entries = await collectUserHookEntries(HOOK_NAME, [
       [plugin.dir, plugin.name],

package/src/hooks/hook-loader.ts

@@ -11,20 +11,39 @@
  * - **Workspace hooks** — `<workspace>/hooks/<event>.{ts,js}`, standalone
  *   files not tied to any plugin (no `package.json`, no tools — just hooks).
  *
- * Hook dispatch is a hot path, so collecting hooks costs no filesystem
- * operations: every hook function enters the in-memory cache when its owner
- * is (re)activated ({@link preImportHooksDir}), and dispatch is pure map
- * lookups. Source changes reach the cache through the source-versions
- * reconcile in `../plugins/mtime-cache.ts`, which tears the owner down,
- * evicts its cache entries and modules, and reactivates it — dispatch never
- * stats, lists, or imports.
+ * The filesystem is the source of truth for which hooks exist. The single
+ * cache here ({@link hookCache}) only saves repeat filesystem/import work — it
+ * is an index over what's on disk, never the source of truth.
  *
- * This module owns the hook cache and every hook operation (collect, init,
- * shutdown, eviction). Plugin *discovery* (which plugin directories exist, in
- * what order) lives in `../plugins/mtime-cache.ts`; the orchestrator there
- * passes the discovered directories into {@link collectUserHooks} and drives
- * pre-import / init / shutdown. Keeping discovery out of this module lets it
- * sit below the plugin cache with no import cycle.
+ * Each hook is resolved **individually, on demand**, the first time something
+ * reads that exact `(owner, hookName)` pair — never a whole directory up front.
+ * A resolution memoizes its promise in {@link hookCache}, so the entry doubles
+ * as both the cache and the in-flight de-dup (concurrent first-readers of the
+ * same hook await one import). The promise resolves to the hook function, or to
+ * `null` when the owner doesn't define that hook — a **negative cache** so a
+ * hook an owner lacks is stat'd once, not re-stat'd every dispatch. Every hook,
+ * dispatch (`user-prompt-submit`, `post-tool-use`, …) *and* lifecycle (`init`,
+ * `shutdown`), goes through the one {@link resolveHook} path:
+ *
+ * - **Dispatch hooks** run on the hot per-turn path via
+ *   {@link collectUserHookEntries}, which resolves that one hook name across the
+ *   discovered owners; repeat reads are pure map lookups.
+ * - **Lifecycle hooks** run once per activation / teardown. {@link runInitHook}
+ *   resolves `init` (to run) and `shutdown` (to cache) while the owner's
+ *   directory is present; {@link runShutdownHook} then reads that cached
+ *   `shutdown`. Because the reconcile always tears an owner down *before*
+ *   evicting it, the cached `shutdown` is still resident at teardown even when
+ *   an uninstall has already removed the directory.
+ *
+ * Source changes reach the cache through the source-versions reconcile in
+ * `../plugins/mtime-cache.ts`: it evicts the owner ({@link evictHooksForOwner}
+ * drops every `(owner, *)` entry, positive and negative) and sweeps the module
+ * registry, so the next read re-resolves fresh.
+ *
+ * Plugin *discovery* (which plugin directories exist, in what order) lives in
+ * `../plugins/mtime-cache.ts`; the orchestrator there passes the discovered
+ * directories into {@link collectUserHookEntries}. Keeping discovery out of
+ * this module lets it sit below the plugin cache with no import cycle.
  */
 
 import {
@@ -37,6 +56,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
+import type { HookEventOwner } from "../api/events/hook-event.js";
 import { getConfig } from "../config/loader.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import type {
@@ -64,136 +84,189 @@ const log = getLogger("hook-loader");
  */
 export const WORKSPACE_HOOKS_OWNER = "__workspace__";
 
-/** A cached, imported hook function. */
-interface CachedHook {
-  readonly hook: HookFunction;
+/**
+ * Whether a hook's owner is a user plugin or the standalone workspace surface —
+ * the `kind` of a {@link HookEventOwner}, reused so this stays a single source
+ * of truth. Threaded into the cache key so the two owner namespaces can't
+ * collide even if a plugin's manifest name happens to equal
+ * {@link WORKSPACE_HOOKS_OWNER}.
+ */
+export type HookOwnerKind = HookEventOwner["kind"];
+
+/**
+ * Per-hook resolution memo keyed by `${kind}:${ownerName}/${hookName}`. The key
+ * includes the owner kind and name (plugin name, or {@link WORKSPACE_HOOKS_OWNER})
+ * so hooks from different owners — even a plugin and the workspace that share a
+ * name — never collide. Each value is the promise that resolved (or is
+ * resolving) that one hook: it settles to the imported function, or to `null`
+ * when the owner doesn't define it (a negative cache entry). Storing the
+ * promise, not the settled value, means concurrent first-readers of the same
+ * hook share one import. An index over the filesystem, never the source of
+ * truth.
+ */
+const hookCache = new Map<string, Promise<HookFunction | null>>();
+
+/** Cache key for a hook: `${kind}:${ownerName}/${hookName}`. */
+function hookKey(
+  kind: HookOwnerKind,
+  ownerName: string,
+  hookName: string,
+): string {
+  return `${kind}:${ownerName}/${hookName}`;
+}
+
+/** Key prefix for every hook owned by `(kind, ownerName)`. */
+function ownerKeyPrefix(kind: HookOwnerKind, ownerName: string): string {
+  return `${kind}:${ownerName}/`;
 }
 
 /**
- * Cached hooks keyed by `${ownerName}/${hookName}`. The key includes the
- * owner (plugin name, or {@link WORKSPACE_HOOKS_OWNER}) so hooks from
- * different owners don't collide. Entries are created when an owner is
- * (re)activated and removed only by owner-level eviction — the cache is the
- * complete record of an owner's dispatchable hooks.
+ * The hooks directory for an owner: `<pluginDir>/hooks` for a plugin, or the
+ * standalone workspace hooks directory for {@link WORKSPACE_HOOKS_OWNER}
+ * (whose `pluginDir` is `null`).
  */
-const hookCache = new Map<string, CachedHook>();
+function ownerHooksDir(pluginDir: string | null): string {
+  return pluginDir === null ? getWorkspaceHooksDir() : join(pluginDir, "hooks");
+}
 
-/** Cache key for a hook: `${ownerName}/${hookName}`. */
-function hookKey(ownerName: string, hookName: string): string {
-  return `${ownerName}/${hookName}`;
+/**
+ * Resolve a single `(owner, hookName)` to its function, memoized in
+ * {@link hookCache}. The first caller starts the import; concurrent callers
+ * await the same promise; later callers get a pure map lookup until the owner
+ * is evicted. Resolves to `null` when the owner doesn't define the hook — a
+ * negative cache entry so an absent hook is looked up once, not every dispatch.
+ * This is the single point where hook code enters the process, shared by
+ * dispatch reads ({@link collectUserHookEntries}) and lifecycle runs
+ * ({@link runInitHook} / {@link runShutdownHook}).
+ */
+function resolveHook(
+  kind: HookOwnerKind,
+  hooksDir: string,
+  ownerName: string,
+  hookName: string,
+): Promise<HookFunction | null> {
+  const key = hookKey(kind, ownerName, hookName);
+  let entry = hookCache.get(key);
+  if (entry === undefined) {
+    entry = importHook(hooksDir, ownerName, hookName);
+    hookCache.set(key, entry);
+  }
+  return entry;
+}
+
+/**
+ * Import the file backing `(owner, hookName)` from `hooksDir`, or `null` when
+ * the owner doesn't define it (no matching file, a failed import, or a
+ * non-function default export). Evicts the module first so an edited file
+ * re-evaluates. Never rejects — a failure is logged and cached as `null` like a
+ * genuinely absent hook, so one bad file doesn't wedge the resolution promise.
+ */
+async function importHook(
+  hooksDir: string,
+  ownerName: string,
+  hookName: string,
+): Promise<HookFunction | null> {
+  const file = listSurfaceDir(hooksDir).find((f) => f.name === hookName);
+  if (file === undefined) {
+    return null;
+  }
+
+  // The same path may hold different content than when it was last imported
+  // (edit, reinstall at the same path); evict so the import re-evaluates from
+  // disk instead of serving Bun's cached module. No-op for a first-ever load.
+  evictModule(file.path);
+
+  try {
+    const hook = await importWithTimeout<HookFunction>(file.path);
+    if (hook === undefined || typeof hook !== "function") {
+      log.error(
+        { plugin: ownerName, hook: hookName, path: file.path },
+        `hook ${hookName} default export must be a function (got ${typeof hook}) — skipping`,
+      );
+      return null;
+    }
+    return hook;
+  } catch (err) {
+    log.error(
+      { err, plugin: ownerName, hook: hookName, path: file.path },
+      `Failed to import hook ${hookName} from ${file.path}`,
+    );
+    return null;
+  }
 }
 
 /**
- * Collect every cached hook for a given event name across all surfaces.
- * Pure in-memory lookups — no filesystem operations on the dispatch path.
+ * Collect the hooks for one event name across all surfaces, resolving that one
+ * `(owner, hookName)` per owner via {@link resolveHook}. The first read of a
+ * given hook does one import; every read after that — until the owner is
+ * evicted — is a pure map lookup. Owners without the hook contribute nothing
+ * (their negative cache entry keeps them from being re-stat'd).
  *
  * `pluginDirs` is the orchestrator's discovered `[dir, ownerName]` set (in
  * install-date order). Each plugin's hook runs first, then the standalone
  * workspace hook runs last — so a plugin can shape the threaded context
- * before a workspace-wide hook observes or finalizes it.
+ * before a workspace-wide hook observes or finalizes it. Resolutions are kicked
+ * off together and awaited in that order, so a cold first read imports the
+ * owners' files concurrently without disturbing chain order.
  *
- * The cache holds exactly what each owner's last (re)activation imported;
- * added, removed, and edited hook files (including helper modules they
- * import) land when the source-versions reconcile redeploys the owner.
+ * Added, removed, and edited hook files (including helper modules they import)
+ * land when the source-versions reconcile evicts the owner and the next read
+ * re-resolves.
  *
  * `effectiveEnabledPlugins` carries the per-chat plugin scope: when non-null, a
  * plugin whose name is not in the set is skipped (its hooks do not run for this
- * conversation). The standalone workspace hook is not owned by a plugin, so it
- * always runs. `null`/omitted means no per-chat restriction.
+ * conversation, and its hook is not imported). The standalone workspace hook is
+ * not owned by a plugin, so it always runs. `null`/omitted means no per-chat
+ * restriction.
  */
 export async function collectUserHookEntries<TCtx = unknown>(
   hookName: string,
   pluginDirs: Iterable<readonly [string, string]>,
   effectiveEnabledPlugins?: Set<string> | null,
 ): Promise<HookEntry<TCtx>[]> {
-  const out: HookEntry<TCtx>[] = [];
+  const pending: Array<{
+    owner: HookEntry<TCtx>["owner"];
+    hook: Promise<HookFunction | null>;
+  }> = [];
 
-  for (const [, pluginName] of pluginDirs) {
+  for (const [pluginDir, pluginName] of pluginDirs) {
     if (
       effectiveEnabledPlugins != null &&
       !effectiveEnabledPlugins.has(pluginName)
     ) {
       continue;
     }
-    const cached = hookCache.get(hookKey(pluginName, hookName));
-    if (cached !== undefined) {
-      out.push({
-        fn: cached.hook as HookFunction<TCtx>,
-        owner: { kind: "plugin", id: pluginName },
-      });
-    }
+    pending.push({
+      owner: { kind: "plugin", id: pluginName },
+      hook: resolveHook(
+        "plugin",
+        ownerHooksDir(pluginDir),
+        pluginName,
+        hookName,
+      ),
+    });
   }
 
   // Standalone workspace hooks: files directly under `<workspace>/hooks/`
   // that are not part of any plugin (no package.json, no tools — just hooks).
-  const wsCached = hookCache.get(hookKey(WORKSPACE_HOOKS_OWNER, hookName));
-  if (wsCached !== undefined) {
-    out.push({
-      fn: wsCached.hook as HookFunction<TCtx>,
-      owner: { kind: "workspace", id: WORKSPACE_HOOKS_OWNER },
-    });
-  }
-
-  return out;
-}
+  pending.push({
+    owner: { kind: "workspace", id: WORKSPACE_HOOKS_OWNER },
+    hook: resolveHook(
+      "workspace",
+      ownerHooksDir(null),
+      WORKSPACE_HOOKS_OWNER,
+      hookName,
+    ),
+  });
 
-/**
- * {@link collectUserHookEntries} without owner attribution — returns just the
- * hook functions in the same order. For callers that only dispatch the chain
- * and don't attribute per-hook side effects.
- */
-export async function collectUserHooks<TCtx = unknown>(
-  hookName: string,
-  pluginDirs: Iterable<readonly [string, string]>,
-  effectiveEnabledPlugins?: Set<string> | null,
-): Promise<HookFunction<TCtx>[]> {
-  const entries = await collectUserHookEntries<TCtx>(
-    hookName,
-    pluginDirs,
-    effectiveEnabledPlugins,
-  );
-  return entries.map((e) => e.fn);
-}
-
-/**
- * Import every hook file under `hooksDir` into the cache, keyed by
- * `${ownerName}/${hookName}`. This is the single point where hook code
- * enters the process: it runs at owner (re)activation, and what it caches
- * is exactly what dispatch serves until the owner is next redeployed.
- * Best-effort per file: a failing or non-function import is logged and
- * skipped (the owner's other hooks still load). A missing directory yields
- * no files (handled by {@link listSurfaceDir}).
- */
-export async function preImportHooksDir(
-  hooksDir: string,
-  ownerName: string,
-): Promise<void> {
-  for (const file of listSurfaceDir(hooksDir)) {
-    const key = hookKey(ownerName, file.name);
-
-    // The same path may hold different content than when it was last
-    // imported (edit, reinstall at the same path); evict so the import
-    // below re-evaluates from disk instead of serving Bun's cached module.
-    // No-op for a first-ever load.
-    evictModule(file.path);
-
-    try {
-      const hook = await importWithTimeout<HookFunction>(file.path);
-      if (hook === undefined || typeof hook !== "function") {
-        log.error(
-          { plugin: ownerName, hook: file.name, path: file.path },
-          `hook ${file.name} default export must be a function (got ${typeof hook}) — skipping`,
-        );
-        continue;
-      }
-      hookCache.set(key, { hook });
-    } catch (err) {
-      log.error(
-        { err, plugin: ownerName, hook: file.name, path: file.path },
-        `Failed to pre-import hook ${file.name}`,
-      );
+  const out: HookEntry<TCtx>[] = [];
+  for (const { owner, hook } of pending) {
+    const fn = await hook;
+    if (fn !== null) {
+      out.push({ fn: fn as HookFunction<TCtx>, owner });
     }
   }
+  return out;
 }
 
 /**
@@ -206,19 +279,15 @@ export function hasWorkspaceHooks(): boolean {
 }
 
 /**
- * Pre-import the standalone workspace hooks under {@link WORKSPACE_HOOKS_OWNER}.
- * Convenience wrapper over {@link preImportHooksDir} that keeps the workspace
- * hooks directory path inside this module.
- */
-export async function preImportWorkspaceHooks(): Promise<void> {
-  await preImportHooksDir(getWorkspaceHooksDir(), WORKSPACE_HOOKS_OWNER);
-}
-
-/**
- * Run the `init` hook for `ownerName` if one was pre-imported into the cache.
- * Shared by user plugins and standalone workspace hooks so both get the same
- * init-context shape and per-owner isolation (a thrown `init` is logged and
- * swallowed, never blocking boot).
+ * Run the `init` hook for `ownerName` if the owner defines one. Resolves the
+ * owner's `shutdown` first — while the directory is still present — so it's
+ * cached for teardown even after an uninstall removes the directory, then
+ * resolves and runs `init`. `init` can't ride the whole-chain `runHook` the way
+ * dispatch hooks do because its context is per-plugin (config, logger, storage
+ * dir), so it's dispatched per-owner here. Shared by user plugins and
+ * standalone workspace hooks so both get the same init-context shape and
+ * per-owner isolation (a thrown `init` is logged and swallowed, never blocking
+ * boot).
  *
  * For user plugins, `pluginDir` is the absolute path to the installed plugin
  * directory (`<workspace>/plugins/<name>/`). Config and data now live inside
@@ -239,8 +308,17 @@ export async function runInitHook(
   ownerName: string,
   pluginDir: string | null = null,
 ): Promise<void> {
-  const initHookEntry = hookCache.get(hookKey(ownerName, HOOKS.INIT));
-  if (initHookEntry === undefined) {
+  // A plugin always has a directory; only the workspace owner passes `null`.
+  const kind: HookOwnerKind = pluginDir === null ? "workspace" : "plugin";
+  const hooksDir = ownerHooksDir(pluginDir);
+
+  // Resolve `shutdown` now, while the directory is present, so it's cached for
+  // teardown even after an uninstall removes the directory (runShutdownHook
+  // reads the cache, never disk). The result is discarded here — this is a warm.
+  await resolveHook(kind, hooksDir, ownerName, HOOKS.SHUTDOWN);
+
+  const initHook = await resolveHook(kind, hooksDir, ownerName, HOOKS.INIT);
+  if (initHook === null) {
     return;
   }
 
@@ -251,7 +329,7 @@ export async function runInitHook(
       pluginStorageDir: resolvePluginStorageDir(ownerName, pluginDir),
       assistantVersion: APP_VERSION,
     };
-    await initHookEntry.hook(initContext);
+    await initHook(initContext);
     log.info({ plugin: ownerName }, "user hooks initialized");
   } catch (err) {
     log.error(
@@ -262,22 +340,33 @@ export async function runInitHook(
 }
 
 /**
- * Run the `shutdown` hook for `ownerName` if one is cached. Best-effort: a
- * thrown shutdown is logged and swallowed. `reason` is threaded into the log
- * for attribution only.
+ * Run one owner's `shutdown` hook from the cache — the targeted single-owner
+ * teardown for a runtime uninstall / disable / reload (the whole-chain
+ * `runHook(HOOKS.SHUTDOWN)` at process exit runs *every* owner's shutdown; this
+ * runs exactly one). The reconcile tears an owner down before evicting it, so
+ * the `shutdown` cached at activation is still resident here even when the
+ * directory is already gone. Best-effort: a thrown shutdown is logged and
+ * swallowed. `reason` is threaded into the log for attribution only.
  */
 export async function runShutdownHook(
+  kind: HookOwnerKind,
   ownerName: string,
   context: ShutdownContext,
   reason: string,
 ): Promise<void> {
-  const shutdownHookEntry = hookCache.get(hookKey(ownerName, HOOKS.SHUTDOWN));
-  if (shutdownHookEntry === undefined) {
+  // Read from the cache (resolved at activation, while the directory existed) —
+  // never re-resolve here, since an uninstall may have already removed it.
+  const entry = hookCache.get(hookKey(kind, ownerName, HOOKS.SHUTDOWN));
+  if (entry === undefined) {
+    return;
+  }
+  const shutdown = await entry;
+  if (shutdown === null) {
     return;
   }
 
   try {
-    await shutdownHookEntry.hook(context);
+    await shutdown(context);
   } catch (err) {
     log.warn(
       { err, plugin: ownerName, reason },
@@ -287,11 +376,16 @@ export async function runShutdownHook(
 }
 
 /**
- * Evict every cached hook owned by `ownerName` (e.g. when a plugin directory
- * is removed). No-op when the owner has no cached hooks.
+ * Evict every cached resolution owned by `(kind, ownerName)` — positive and
+ * negative — so the next read re-resolves fresh. Called by the reconcile after
+ * the owner's `shutdown` has already run. No-op when the owner has no cached
+ * state.
  */
-export function evictHooksForOwner(ownerName: string): void {
-  const prefix = `${ownerName}/`;
+export function evictHooksForOwner(
+  kind: HookOwnerKind,
+  ownerName: string,
+): void {
+  const prefix = ownerKeyPrefix(kind, ownerName);
   for (const key of hookCache.keys()) {
     if (key.startsWith(prefix)) {
       hookCache.delete(key);
@@ -300,13 +394,13 @@ export function evictHooksForOwner(ownerName: string): void {
 }
 
 /**
- * Evict all plugin-owned hooks while preserving standalone workspace hooks.
- * Called when the plugins directory is gone entirely: workspace hooks live
- * outside it, so the absence of any plugin must not evict them.
+ * Evict all plugin-owned resolutions while preserving standalone workspace
+ * hooks. Called when the plugins directory is gone entirely: workspace hooks
+ * live outside it, so the absence of any plugin must not evict them.
  */
 export function clearPluginHooks(): void {
   for (const key of hookCache.keys()) {
-    if (!key.startsWith(`${WORKSPACE_HOOKS_OWNER}/`)) {
+    if (key.startsWith("plugin:")) {
       hookCache.delete(key);
     }
   }
@@ -434,7 +528,7 @@ function ensureLegacyStorageDir(ownerName: string): string {
 
 // ─── Test hooks ──────────────────────────────────────────────────────────────
 
-/** Clear the hook cache. Test-only. */
+/** Clear the hook resolution cache. Test-only. */
 export function resetHookCacheForTests(): void {
   const isTest =
     process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";