@soleri/core 9.4.0 → 9.6.0

package/src/runtime/runtime.ts

@@ -60,6 +60,10 @@ import { loadPersona } from '../persona/loader.js';
 import { generatePersonaInstructions } from '../persona/prompt-generator.js';
 import { OperatorProfileStore } from '../operator/operator-profile.js';
 import { ContextHealthMonitor } from './context-health.js';
+import { ShutdownRegistry } from './shutdown-registry.js';
+import { RuntimeAdapterRegistry } from '../adapters/registry.js';
+import { ClaudeCodeRuntimeAdapter } from '../adapters/claude-code-adapter.js';
+import { SubagentDispatcher } from '../subagent/dispatcher.js';
 
 /**
  * Create a fully initialized agent runtime.
@@ -221,6 +225,127 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
   learningRadar.setOperatorProfile(operatorProfile);
   brainIntelligence.setOperatorProfile(operatorProfile);
 
+  // ─── Shutdown Registry ────────────────────────────────────────────
+  const shutdownRegistry = new ShutdownRegistry();
+
+  // Build pipeline runner before the runtime object so we can reference it
+  const pipelineRunner = (() => {
+    const jq = new JobQueue(vault.getProvider());
+    const pr = new PipelineRunner(jq);
+    // Register default job handlers for curator pipeline
+    pr.registerHandler('tag-normalize', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const result = curator.normalizeTag(entry.tags[0] ?? '');
+      return result;
+    });
+    pr.registerHandler('dedup-check', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('auto-link', async (job) => {
+      if (linkManager) {
+        const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
+        for (const s of suggestions) {
+          linkManager.addLink(
+            job.entryId ?? '',
+            s.entryId,
+            s.suggestedType,
+            `pipeline: ${s.reason}`,
+          );
+        }
+        return { linked: suggestions.length };
+      }
+      return { skipped: true, reason: 'link manager not available' };
+    });
+    pr.registerHandler('quality-gate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return evaluateQuality(entry, llmClient);
+    });
+    pr.registerHandler('classify', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return classifyEntry(entry, llmClient);
+    });
+
+    // ─── 9 additional handlers for full Salvador parity (#216) ────
+    pr.registerHandler('enrich-frontmatter', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.enrichMetadata(entry.id);
+    });
+    pr.registerHandler('detect-staleness', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      // Check if entry is older than 90 days (using validFrom or fallback to 0)
+      const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
+      const ageMs = Date.now() - entryTimestamp;
+      const staleDays = 90;
+      const isStale = ageMs > staleDays * 86400000;
+      return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
+    });
+    pr.registerHandler('detect-duplicate', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      return curator.detectDuplicates(entry.id);
+    });
+    pr.registerHandler('detect-contradiction', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const contradictions = curator.detectContradictions(0.4);
+      const relevant = contradictions.filter(
+        (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
+      );
+      return { found: relevant.length, contradictions: relevant };
+    });
+    pr.registerHandler('consolidate-duplicates', async (_job) => {
+      return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+    });
+    pr.registerHandler('archive-stale', async (_job) => {
+      // Run consolidation with stale detection
+      const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
+      return { archived: result.staleEntries.length, result };
+    });
+    pr.registerHandler('verify-searchable', async (job) => {
+      const entry = vault.get(job.entryId ?? '');
+      if (!entry) return { skipped: true, reason: 'entry not found' };
+      const searchResults = vault.search(entry.title, { limit: 1 });
+      const found = searchResults.some((r) => r.entry.id === entry.id);
+      return { searchable: found, entryId: entry.id };
+    });
+    return pr;
+  })();
+
+  // ─── Register cleanup callbacks (LIFO: first registered = last closed) ──
+  // Vault manager closes last (other modules may flush to vault during close)
+  shutdownRegistry.register('vaultManager', () => vaultManager.close());
+  // Pipeline runner — clear its polling interval
+  shutdownRegistry.register('pipelineRunner', () => pipelineRunner.stop());
+  // Agency manager — close FSWatchers and debounce timers
+  shutdownRegistry.register('agencyManager', () => agencyManager.disable());
+
+  shutdownRegistry.register('subagentDispatcher', () => subagentDispatcher.cleanup());
+  // Loop manager — clear accumulated state
+  shutdownRegistry.register('loopManager', () => {
+    if (loop.isActive()) {
+      try {
+        loop.cancelLoop();
+      } catch {
+        // Loop may already be inactive
+      }
+    }
+  });
+
+  // Runtime Adapter Registry — dispatch work to different AI CLIs
+  const adapterRegistry = new RuntimeAdapterRegistry();
+  adapterRegistry.register('claude-code', new ClaudeCodeRuntimeAdapter());
+  adapterRegistry.setDefault('claude-code');
+
+  // Subagent Dispatcher — spawn and manage child agent processes
+  const subagentDispatcher = new SubagentDispatcher({ adapterRegistry });
+
   return {
     config,
     logger,
@@ -256,94 +381,7 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
     knowledgeSynthesizer: new KnowledgeSynthesizer(brain, llmClient),
     chainRunner: new ChainRunner(vault.getProvider()),
     jobQueue: new JobQueue(vault.getProvider()),
-    pipelineRunner: (() => {
-      const jq = new JobQueue(vault.getProvider());
-      const pr = new PipelineRunner(jq);
-      // Register default job handlers for curator pipeline
-      pr.registerHandler('tag-normalize', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const result = curator.normalizeTag(entry.tags[0] ?? '');
-        return result;
-      });
-      pr.registerHandler('dedup-check', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('auto-link', async (job) => {
-        if (linkManager) {
-          const suggestions = linkManager.suggestLinks(job.entryId ?? '', 3);
-          for (const s of suggestions) {
-            linkManager.addLink(
-              job.entryId ?? '',
-              s.entryId,
-              s.suggestedType,
-              `pipeline: ${s.reason}`,
-            );
-          }
-          return { linked: suggestions.length };
-        }
-        return { skipped: true, reason: 'link manager not available' };
-      });
-      pr.registerHandler('quality-gate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return evaluateQuality(entry, llmClient);
-      });
-      pr.registerHandler('classify', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return classifyEntry(entry, llmClient);
-      });
-
-      // ─── 9 additional handlers for full Salvador parity (#216) ────
-      pr.registerHandler('enrich-frontmatter', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.enrichMetadata(entry.id);
-      });
-      pr.registerHandler('detect-staleness', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        // Check if entry is older than 90 days (using validFrom or fallback to 0)
-        const entryTimestamp = (entry.validFrom ?? 0) * 1000 || Date.now();
-        const ageMs = Date.now() - entryTimestamp;
-        const staleDays = 90;
-        const isStale = ageMs > staleDays * 86400000;
-        return { stale: isStale, ageDays: Math.floor(ageMs / 86400000), entryId: entry.id };
-      });
-      pr.registerHandler('detect-duplicate', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        return curator.detectDuplicates(entry.id);
-      });
-      pr.registerHandler('detect-contradiction', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const contradictions = curator.detectContradictions(0.4);
-        const relevant = contradictions.filter(
-          (c) => c.patternId === job.entryId || c.antipatternId === job.entryId,
-        );
-        return { found: relevant.length, contradictions: relevant };
-      });
-      pr.registerHandler('consolidate-duplicates', async (_job) => {
-        return curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-      });
-      pr.registerHandler('archive-stale', async (_job) => {
-        // Run consolidation with stale detection
-        const result = curator.consolidate({ dryRun: false, staleDaysThreshold: 90 });
-        return { archived: result.staleEntries.length, result };
-      });
-      pr.registerHandler('verify-searchable', async (job) => {
-        const entry = vault.get(job.entryId ?? '');
-        if (!entry) return { skipped: true, reason: 'entry not found' };
-        const searchResults = vault.search(entry.title, { limit: 1 });
-        const found = searchResults.some((r) => r.entry.id === entry.id);
-        return { searchable: found, entryId: entry.id };
-      });
-      return pr;
-    })(),
+    pipelineRunner,
     operatorProfile,
     persona: (() => {
       const p = loadPersona(agentId, config.persona ?? undefined);
@@ -354,10 +392,15 @@ export function createAgentRuntime(config: AgentRuntimeConfig): AgentRuntime {
       const p = loadPersona(agentId, config.persona ?? undefined);
       return generatePersonaInstructions(p);
     })(),
+    adapterRegistry,
+    subagentDispatcher,
     contextHealth: new ContextHealthMonitor(),
+    shutdownRegistry,
     createdAt: Date.now(),
     close: () => {
-      vaultManager.close();
+      // Synchronous close — runs all registered callbacks in LIFO order,
+      // then closes the vault (registered first, so runs last).
+      shutdownRegistry.closeAllSync();
     },
   };
 }

package/src/runtime/session-briefing.test.ts

@@ -17,6 +17,14 @@ function makeRuntime(overrides?: {
     toolsUsed: string[];
     filesModified: string[];
   }>;
+  memories?: Array<{
+    id?: string;
+    createdAt: number;
+    projectPath?: string;
+    summary?: string;
+    context?: string;
+    type?: string;
+  }>;
   plans?: Array<{
     id: string;
     status: string;
@@ -45,6 +53,7 @@ function makeRuntime(overrides?: {
     vault: {
       stats: () => o.vaultStats ?? { totalEntries: 50, byType: { playbook: 5 } },
       getRecent: (_n: number) => o.recentEntries ?? [],
+      listMemories: () => o.memories ?? [],
     },
     curator: {
       healthAudit: () => ({
@@ -95,11 +104,34 @@ describe('session-briefing', () => {
       expect(data.sections.find((s) => s.label === 'Welcome')).toBeUndefined();
     });
 
-    it('includes Last session section', async () => {
+    it('includes Last session from cross-project memories when fresh', async () => {
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-1',
+            createdAt: Date.now() - 600_000, // 10 min ago (ms)
+            projectPath: '/Users/me/projects/other-app',
+            summary: 'Fixed KPI card layout in the dashboard',
+            type: 'session',
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+      const res = await executeOp(ops, 'session_briefing', {});
+
+      const data = res.data as { sections: Array<{ label: string; content: string }> };
+      const session = data.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeDefined();
+      expect(session!.content).toContain('other-app');
+      expect(session!.content).toContain('Fixed KPI card layout');
+    });
+
+    it('falls back to brain sessions when no fresh memories exist', async () => {
       const runtime = makeRuntime({
+        memories: [], // no memories
         sessions: [
           {
-            endedAt: new Date(Date.now() - 3600000).toISOString(),
+            endedAt: new Date(Date.now() - 3600_000).toISOString(), // 1h ago
             domain: 'frontend',
             context: 'Refactored button component',
             toolsUsed: ['vault_search', 'brain_recommend'],
@@ -117,6 +149,63 @@ describe('session-briefing', () => {
       expect(session!.content).toContain('Refactored button component');
     });
 
+    it('skips Last session when all sessions are stale', async () => {
+      const staleTs = Date.now() - 72 * 3600_000; // 72h ago — beyond default 48h
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-old',
+            createdAt: staleTs,
+            projectPath: '/old-project',
+            summary: 'Ancient session',
+            type: 'session',
+          },
+        ],
+        sessions: [
+          {
+            endedAt: new Date(staleTs).toISOString(),
+            domain: 'old',
+            context: 'Ancient brain session',
+            toolsUsed: [],
+            filesModified: [],
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+      const res = await executeOp(ops, 'session_briefing', {});
+
+      const data = res.data as { sections: Array<{ label: string; content: string }> };
+      const session = data.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeUndefined();
+    });
+
+    it('respects custom recencyHours parameter', async () => {
+      const runtime = makeRuntime({
+        memories: [
+          {
+            id: 'mem-3h',
+            createdAt: Date.now() - 3 * 3600_000, // 3h ago
+            projectPath: '/recent-project',
+            summary: 'Recent work',
+            type: 'session',
+          },
+        ],
+      });
+      const ops = captureOps(createSessionBriefingOps(runtime));
+
+      // With 1h window — should skip
+      const narrow = await executeOp(ops, 'session_briefing', { recencyHours: 1 });
+      const narrowData = narrow.data as { sections: Array<{ label: string }> };
+      expect(narrowData.sections.find((s) => s.label === 'Last session')).toBeUndefined();
+
+      // With 4h window — should include
+      const wide = await executeOp(ops, 'session_briefing', { recencyHours: 4 });
+      const wideData = wide.data as { sections: Array<{ label: string; content: string }> };
+      const session = wideData.sections.find((s) => s.label === 'Last session');
+      expect(session).toBeDefined();
+      expect(session!.content).toContain('Recent work');
+    });
+
     it('includes Active plans section', async () => {
       const runtime = makeRuntime({
         plans: [
@@ -234,6 +323,9 @@ describe('session-briefing', () => {
           getRecent: () => {
             throw new Error('no vault');
           },
+          listMemories: () => {
+            throw new Error('no vault');
+          },
         },
         curator: {
           healthAudit: () => {

package/src/runtime/session-briefing.ts

@@ -57,22 +57,58 @@ export function createSessionBriefingOps(runtime: AgentRuntime): OpDefinition[]
           // Vault stats unavailable — skip
         }
 
-        // 1. Last session
+        // 1. Last session — cross-project, with staleness threshold
         try {
-          const sessions = brainIntelligence.listSessions({ limit: 1, active: false });
-          dataPoints += sessions.length;
-          if (sessions.length > 0) {
-            const last = sessions[0];
-            const ago = formatTimeAgo(last.endedAt ? new Date(last.endedAt).getTime() : Date.now());
-            const domain = last.domain ? ` [${last.domain}]` : '';
-            const context = last.context ? `: ${last.context.slice(0, 80)}` : '';
-            const tools = last.toolsUsed.length > 0 ? `, used ${last.toolsUsed.length} tools` : '';
-            const files =
-              last.filesModified.length > 0 ? `, modified ${last.filesModified.length} files` : '';
+          const recencyMs = (params.recencyHours as number) * 3600_000;
+          const cutoff = Date.now() - recencyMs;
+
+          // Try cross-project memories first (most recent work, any project)
+          const recentMemories = vault.listMemories({ type: 'session', limit: 3 });
+          const freshMemory = recentMemories.find((m) => {
+            const ts = m.createdAt > 1e12 ? m.createdAt : m.createdAt * 1000;
+            return ts > cutoff;
+          });
+
+          if (freshMemory) {
+            const ts =
+              freshMemory.createdAt > 1e12 ? freshMemory.createdAt : freshMemory.createdAt * 1000;
+            const ago = formatTimeAgo(ts);
+            const project = freshMemory.projectPath
+              ? ` [${freshMemory.projectPath.split('/').pop()}]`
+              : '';
+            const summary = freshMemory.summary
+              ? `: ${freshMemory.summary.slice(0, 100)}`
+              : freshMemory.context
+                ? `: ${freshMemory.context.slice(0, 100)}`
+                : '';
+            dataPoints += recentMemories.length;
             sections.push({
               label: 'Last session',
-              content: `(${ago})${domain}${context}${tools}${files}`,
+              content: `(${ago})${project}${summary}`,
             });
+          } else {
+            // Fall back to brain sessions (same-project only) if no fresh memory
+            const sessions = brainIntelligence.listSessions({ limit: 1, active: false });
+            dataPoints += sessions.length;
+            if (sessions.length > 0) {
+              const last = sessions[0];
+              const endTs = last.endedAt ? new Date(last.endedAt).getTime() : 0;
+              if (endTs > cutoff) {
+                const ago = formatTimeAgo(endTs);
+                const domain = last.domain ? ` [${last.domain}]` : '';
+                const context = last.context ? `: ${last.context.slice(0, 80)}` : '';
+                const tools =
+                  last.toolsUsed.length > 0 ? `, used ${last.toolsUsed.length} tools` : '';
+                const files =
+                  last.filesModified.length > 0
+                    ? `, modified ${last.filesModified.length} files`
+                    : '';
+                sections.push({
+                  label: 'Last session',
+                  content: `(${ago})${domain}${context}${tools}${files}`,
+                });
+              }
+            }
           }
         } catch {
           // Session data unavailable — skip

package/src/runtime/shutdown-registry.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Unit tests for ShutdownRegistry — centralized cleanup for agent runtime.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { ShutdownRegistry } from './shutdown-registry.js';
+
+describe('ShutdownRegistry', () => {
+  it('starts with zero entries and not closed', () => {
+    const registry = new ShutdownRegistry();
+    expect(registry.size).toBe(0);
+    expect(registry.isClosed).toBe(false);
+  });
+
+  it('tracks registered entries', () => {
+    const registry = new ShutdownRegistry();
+    registry.register('a', vi.fn());
+    registry.register('b', vi.fn());
+    expect(registry.size).toBe(2);
+  });
+
+  it('calls callbacks in LIFO order on closeAll', async () => {
+    const order: string[] = [];
+    const registry = new ShutdownRegistry();
+    registry.register('first', () => {
+      order.push('first');
+    });
+    registry.register('second', () => {
+      order.push('second');
+    });
+    registry.register('third', () => {
+      order.push('third');
+    });
+
+    await registry.closeAll();
+    expect(order).toEqual(['third', 'second', 'first']);
+  });
+
+  it('calls callbacks in LIFO order on closeAllSync', () => {
+    const order: string[] = [];
+    const registry = new ShutdownRegistry();
+    registry.register('first', () => {
+      order.push('first');
+    });
+    registry.register('second', () => {
+      order.push('second');
+    });
+    registry.register('third', () => {
+      order.push('third');
+    });
+
+    registry.closeAllSync();
+    expect(order).toEqual(['third', 'second', 'first']);
+  });
+
+  it('is idempotent — second closeAll is a no-op', async () => {
+    const callback = vi.fn();
+    const registry = new ShutdownRegistry();
+    registry.register('test', callback);
+
+    await registry.closeAll();
+    await registry.closeAll();
+
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(registry.isClosed).toBe(true);
+  });
+
+  it('is idempotent — second closeAllSync is a no-op', () => {
+    const callback = vi.fn();
+    const registry = new ShutdownRegistry();
+    registry.register('test', callback);
+
+    registry.closeAllSync();
+    registry.closeAllSync();
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('handles async callbacks in closeAll', async () => {
+    const order: string[] = [];
+    const registry = new ShutdownRegistry();
+    registry.register('sync', () => {
+      order.push('sync');
+    });
+    registry.register('async', async () => {
+      await new Promise((r) => setTimeout(r, 5));
+      order.push('async');
+    });
+
+    await registry.closeAll();
+    expect(order).toEqual(['async', 'sync']);
+  });
+
+  it('continues on error — remaining callbacks still execute', async () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    const order: string[] = [];
+    const registry = new ShutdownRegistry();
+    registry.register('first', () => {
+      order.push('first');
+    });
+    registry.register('failing', () => {
+      throw new Error('boom');
+    });
+    registry.register('third', () => {
+      order.push('third');
+    });
+
+    await registry.closeAll();
+
+    // third runs first (LIFO), failing throws but first still runs
+    expect(order).toEqual(['third', 'first']);
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('boom'));
+    stderrSpy.mockRestore();
+  });
+
+  it('closeAllSync swallows errors silently', () => {
+    const order: string[] = [];
+    const registry = new ShutdownRegistry();
+    registry.register('first', () => {
+      order.push('first');
+    });
+    registry.register('failing', () => {
+      throw new Error('boom');
+    });
+    registry.register('third', () => {
+      order.push('third');
+    });
+
+    // Should not throw
+    registry.closeAllSync();
+    expect(order).toEqual(['third', 'first']);
+  });
+
+  it('ignores registrations after close', async () => {
+    const registry = new ShutdownRegistry();
+    await registry.closeAll();
+
+    const callback = vi.fn();
+    registry.register('late', callback);
+    expect(registry.size).toBe(0);
+  });
+
+  it('clears entries after closeAll', async () => {
+    const registry = new ShutdownRegistry();
+    registry.register('test', vi.fn());
+    expect(registry.size).toBe(1);
+
+    await registry.closeAll();
+    expect(registry.size).toBe(0);
+  });
+});

package/src/runtime/shutdown-registry.ts

@@ -0,0 +1,85 @@
+/**
+ * Shutdown Registry — centralized cleanup for agent runtime resources.
+ *
+ * Modules register their cleanup callbacks (clear timers, close watchers,
+ * kill child processes). On shutdown, callbacks run in LIFO order so
+ * dependents close before their dependencies.
+ *
+ * Idempotent: calling `closeAll()` multiple times is safe.
+ */
+
+export type ShutdownCallback = () => void | Promise<void>;
+
+interface ShutdownEntry {
+  name: string;
+  callback: ShutdownCallback;
+}
+
+export class ShutdownRegistry {
+  private entries: ShutdownEntry[] = [];
+  private closed = false;
+
+  /**
+   * Register a named cleanup callback.
+   * Callbacks are invoked in LIFO order (last registered = first closed).
+   */
+  register(name: string, callback: ShutdownCallback): void {
+    if (this.closed) return;
+    this.entries.push({ name, callback });
+  }
+
+  /**
+   * Run all registered cleanup callbacks in LIFO order.
+   * Idempotent — subsequent calls are no-ops.
+   * Errors in individual callbacks are caught and logged to stderr
+   * so that remaining callbacks still execute.
+   */
+  async closeAll(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+
+    // LIFO order
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const entry = this.entries[i];
+      try {
+        await entry.callback();
+      } catch (err) {
+        // Log but don't throw — remaining cleanups must still run
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[shutdown] ${entry.name}: ${msg}\n`);
+      }
+    }
+
+    this.entries = [];
+  }
+
+  /**
+   * Synchronous close — best-effort for non-async callbacks.
+   * Use when you can't await (e.g. process.on('exit')).
+   */
+  closeAllSync(): void {
+    if (this.closed) return;
+    this.closed = true;
+
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const entry = this.entries[i];
+      try {
+        entry.callback();
+      } catch {
+        // Best-effort — swallow errors in sync path
+      }
+    }
+
+    this.entries = [];
+  }
+
+  /** Number of registered callbacks. */
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** Whether closeAll() has been called. */
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}