@arki/dot 0.1.3 → 0.2.0

package/src/cli/index.ts

@@ -33,6 +33,7 @@ import { runNew } from './new.js';
 import { probeObservability } from './observability-probe.js';
 import { renderDoctor } from './render-doctor.js';
 import { renderExplain } from './render-explain.js';
+import { renderGraph } from './render-graph.js';
 
 const debugCli = createDebugLogger('arki:dot:cli');
 
@@ -57,6 +58,10 @@ Common options:
   --app <path>           Path to the app entry file (default: discovers
                          ./dot.config.ts, ./src/app.ts, or ./app.ts)
   --cwd <dir>            Working directory (default: current)
+  --graph                Emit the pip graph as Mermaid flowchart source
+                         instead of the standard output. explain shows
+                         declaration (= boot) order; doctor shows the
+                         wiring observed during boot. Composes with --json.
 
 \`doctor\` options:
   --observability        Also probe whether an OpenTelemetry SDK is
@@ -89,6 +94,8 @@ export type CliArgs = {
   force?: boolean;
   /** `--observability` (only honored by `doctor`). */
   observability?: boolean;
+  /** `--graph` (honored by `explain` and `doctor`). */
+  graph?: boolean;
 };
 
 /**
@@ -152,6 +159,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
         'dry-run': { type: 'boolean', default: false },
         force: { type: 'boolean', default: false },
         observability: { type: 'boolean', default: false },
+        graph: { type: 'boolean', default: false },
       },
     });
   } catch (err) {
@@ -174,6 +182,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     'dry-run'?: boolean;
     force?: boolean;
     observability?: boolean;
+    graph?: boolean;
   };
 
   if (values.help) command = 'help';
@@ -205,6 +214,7 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     dryRun: values['dry-run'] ?? false,
     force: values.force ?? false,
     observability: values.observability ?? false,
+    graph: values.graph ?? false,
   };
 }
 
@@ -220,7 +230,7 @@ async function loadApp(args: CliArgs): Promise<DiscoveredApp> {
  */
 export async function runExplain(
   discovered: DiscoveredApp,
-  opts: { json: boolean; out?: (line: string) => void; now?: () => Date },
+  opts: { json: boolean; graph?: boolean; out?: (line: string) => void; now?: () => Date },
 ): Promise<DotCliEnvelope<unknown>> {
   let configured: DotApp<Record<string, unknown>> | DotAppConfigured<Record<string, unknown>>;
   try {
@@ -236,6 +246,12 @@ export async function runExplain(
     throw wrapLifecycleError(err, 'configure');
   }
 
+  if (opts.graph === true) {
+    return renderGraph(
+      { manifest: configured.manifest, command: 'explain' },
+      { json: opts.json, out: opts.out, now: opts.now },
+    );
+  }
   return renderExplain({ manifest: configured.manifest }, { json: opts.json, out: opts.out, now: opts.now });
 }
 
@@ -249,6 +265,8 @@ type DoctorRunOptions = {
    * present. Default `false`.
    */
   observability?: boolean;
+  /** When `true`, emit the pip graph (Mermaid) instead of diagnostics. */
+  graph?: boolean;
 };
 
 /**
@@ -268,6 +286,12 @@ export async function runDoctor(
   // Already-booted app: just read diagnostics, don't touch lifecycle.
   if (!guards.isDotAppBuilder(discovered) && !guards.isDotAppConfigured(discovered)) {
     const app = discovered as DotApp<Record<string, unknown>>;
+    if (opts.graph === true) {
+      return renderGraph(
+        { manifest: app.manifest, command: 'doctor' },
+        { json: opts.json, out: opts.out, now: opts.now },
+      );
+    }
     const diagnostics = applyObservabilityProbe(app.diagnostics, opts.observability ?? false);
     return renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
   }
@@ -297,6 +321,16 @@ export async function runDoctor(
   }
 
   try {
+    if (opts.graph === true) {
+      // Post-boot manifest carries the observed wiring edges; after a boot
+      // failure it carries the edges recorded up to the failing pip.
+      const manifest = bootedApp ? bootedApp.manifest : configured.manifest;
+      const graphEnvelope = renderGraph(
+        { manifest, command: 'doctor' },
+        { json: opts.json, out: opts.out, now: opts.now },
+      );
+      return bootThrew ? { ...graphEnvelope, status: 'failure' } : graphEnvelope;
+    }
     const rawDiagnostics = bootedApp ? bootedApp.diagnostics : configured.diagnostics;
     const diagnostics = applyObservabilityProbe(rawDiagnostics, opts.observability ?? false);
     const envelope = renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
@@ -450,7 +484,7 @@ export async function main(options: MainOptions): Promise<number> {
 
   try {
     const discovered = await loadApp(args);
-    const opts = { json: args.json, out: stdout, now: nowFactory };
+    const opts = { json: args.json, graph: args.graph, out: stdout, now: nowFactory };
     let envelope: DotCliEnvelope<unknown>;
 
     if (args.command === 'explain') {

package/src/cli/render-graph.ts

@@ -0,0 +1,88 @@
+/**
+ * Renderer for `dot explain --graph` / `dot doctor --graph`.
+ *
+ * Emits the app's pip graph as [Mermaid](https://mermaid.js.org) `flowchart`
+ * source — paste-able into GitHub markdown, docs, and mermaid.live.
+ *
+ * The nodes are the pips in declaration order (which IS boot order in v2 —
+ * the numbering makes that visible); the edges are the manifest's
+ * **observed** dependency edges, recorded by the kernel when a pip's need
+ * was satisfied during boot. `explain` never boots, so its graph shows
+ * declaration order with whatever edges configure-time metadata declared;
+ * `doctor` boots, so its graph shows the real wiring.
+ */
+
+import type { DotAppManifest } from '../manifest.js';
+import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
+
+/** Envelope payload for graph output. */
+export type GraphData = {
+  format: 'mermaid';
+  /** Mermaid `flowchart` source. */
+  source: string;
+};
+
+/** Escape a pip name for use inside a quoted Mermaid node label. */
+function escapeLabel(name: string): string {
+  return name.replaceAll('"', '#quot;');
+}
+
+/**
+ * Build Mermaid `flowchart` source from a manifest. Deterministic: node
+ * ids follow declaration order, edges follow manifest order.
+ */
+export function buildMermaidGraph(manifest: DotAppManifest): string {
+  const lines: string[] = ['flowchart TD'];
+  const idByPip = new Map<string, string>();
+
+  for (const [index, pip] of manifest.pips.entries()) {
+    const id = `p${index.toString()}`;
+    idByPip.set(pip.name, id);
+    const order = (index + 1).toString();
+    const version = pip.version === undefined ? '' : `@${pip.version}`;
+    lines.push(`  ${id}["${order} · ${escapeLabel(pip.name)}${escapeLabel(version)}"]`);
+  }
+
+  for (const edge of manifest.dependencies) {
+    const from = idByPip.get(edge.from);
+    const to = idByPip.get(edge.to);
+    // Edges referencing unknown pips would be a kernel bug — skip rather
+    // than emit invalid Mermaid.
+    if (from === undefined || to === undefined) continue;
+    lines.push(`  ${from} -->|${edge.kind}| ${to}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Render the graph output. Plain mode prints raw Mermaid source (pipe it
+ * straight into a markdown code fence); `--json` wraps it in the standard
+ * CLI envelope under `data.source`.
+ */
+export function renderGraph(
+  source: { manifest: DotAppManifest; command: 'explain' | 'doctor' },
+  opts: RenderOptions,
+): DotCliEnvelope<GraphData> {
+  const mermaid = buildMermaidGraph(source.manifest);
+  const nowFactory = opts.now ?? (() => new Date());
+  const envelope: DotCliEnvelope<GraphData> = {
+    status: 'success',
+    command: source.command,
+    generatedAt: nowFactory().toISOString(),
+    data: { format: 'mermaid', source: mermaid },
+    errors: [],
+  };
+
+  const out =
+    opts.out ??
+    ((line: string) => {
+      process.stdout.write(line);
+    });
+  if (opts.json) {
+    out(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    out(mermaid);
+  }
+  return envelope;
+}

package/src/define-app.ts

@@ -176,6 +176,7 @@ type BuilderState = {
   pips: AnyPip[];
   config?: Readonly<Record<string, unknown>>;
   observers?: readonly DotLifecycleObserver[];
+  hookTimeoutMs?: number;
 };
 
 /**
@@ -204,6 +205,16 @@ export function defineApp(
      * `configured.subscribe(...)` or `app.subscribe(...)`.
      */
     observers?: readonly DotLifecycleObserver[];
+    /**
+     * Watchdog budget (ms) for each async hook invocation (`boot`, `start`,
+     * `stop`, `dispose` — `configure` is sync). A hook exceeding the budget
+     * fails with `DOT_LIFECYCLE_E015` naming the pip and hook, and the
+     * kernel applies its normal failure rules (boot rollback, teardown
+     * aggregation). The hook's promise itself cannot be cancelled — the
+     * watchdog makes the hang *visible*, it does not kill it. Default:
+     * no watchdog.
+     */
+    hookTimeoutMs?: number;
   } = {},
 ): DotAppBuilder<EmptyShape> {
   const state: BuilderState = {
@@ -212,6 +223,7 @@ export function defineApp(
     pips: [],
     config: options.config,
     observers: options.observers,
+    hookTimeoutMs: options.hookTimeoutMs,
   };
   return makeBuilder<EmptyShape>(state);
 }
@@ -223,6 +235,7 @@ function buildImpl(state: BuilderState): DotAppImpl {
     pips: state.pips,
     config: state.config,
     observers: state.observers,
+    hookTimeoutMs: state.hookTimeoutMs,
   });
 }
 

package/src/index.ts

@@ -80,8 +80,11 @@ export type {
 export { renderTimeline } from './timeline.js';
 export type { RenderTimelineOptions } from './timeline.js';
 
-export { testApp, bootTestApp } from './test-harness.js';
-export type { TestAppOptions } from './test-harness.js';
+export { testApp, bootTestApp, testPip } from './test-harness.js';
+export type { TestAppOptions, TestPipBuilder } from './test-harness.js';
+
+export { hookSignals } from './signals.js';
+export type { HookSignalsOptions, SignalTarget } from './signals.js';
 
 // Task 9b: CLI envelope type is exported so adapter packages can produce the
 // same shape from related tooling (release-tooling, pip scaffolds, etc.).

package/src/kernel/app-instance.ts

@@ -104,6 +104,8 @@ export type DotAppInternalConfig = {
    * happen before there's a public seam to call `subscribe()` on.
    */
   observers?: readonly DotLifecycleObserver[];
+  /** Per-hook watchdog budget in ms — see `defineApp`'s option of the same name. */
+  hookTimeoutMs?: number;
 };
 
 /**
@@ -122,6 +124,9 @@ export class DotAppImpl {
   /** Macro-state of the app. */
   #state: DotLifecycleState = 'defined';
 
+  /** Per-hook watchdog budget (ms); `undefined` = no watchdog. */
+  readonly #hookTimeoutMs: number | undefined;
+
   /** Manifest finalised after `configure`. */
   #manifest: DotAppManifest;
 
@@ -180,6 +185,7 @@ export class DotAppImpl {
   constructor(config: DotAppInternalConfig) {
     this.#appName = config.appName;
     this.#appVersion = config.appVersion;
+    this.#hookTimeoutMs = config.hookTimeoutMs;
     this.#config = Object.freeze({ ...config.config });
     this.#logger = new Logger('arki:dot:lifecycle', { 'dot.app.name': config.appName });
     this.#observers = new Set(config.observers);
@@ -675,6 +681,44 @@ export class DotAppImpl {
     return ctx;
   }
 
+  /**
+   * Race one hook invocation against the app's `hookTimeoutMs` watchdog.
+   * No budget configured → plain pass-through. On timeout the returned
+   * promise rejects with `DOT_LIFECYCLE_E015` naming the pip and hook,
+   * and the call site's existing catch path applies the phase's normal
+   * failure rules (boot rollback, start cascade, teardown aggregation).
+   * The hook's own promise cannot be cancelled — the watchdog makes a
+   * hang visible and bounded; it does not kill the hung work.
+   */
+  async #withHookBudget<T>(pipName: string, hook: DotLifecycleHook, run: () => Promise<T> | T): Promise<T> {
+    const budget = this.#hookTimeoutMs;
+    if (budget === undefined) return run();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const watchdog = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new DotLifecycleError({
+            code: DotLifecycleErrorCode.HookTimeout,
+            phase: hook,
+            pip: pipName,
+            message:
+              `${hook} hook of pip "${pipName}" exceeded the ${budget.toString()}ms hookTimeoutMs watchdog. ` +
+              `The kernel treats the hook as failed and applies its normal rollback/aggregation rules, but ` +
+              `cannot cancel the hook's promise — find the hang (a missing await? a connection that never ` +
+              `settles?) or raise the budget in defineApp(name, { hookTimeoutMs }).`,
+          }),
+        );
+      }, budget);
+      // A pending watchdog must never keep an otherwise-finished process alive.
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([Promise.resolve(run()), watchdog]);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
   /**
    * Inner boot loop. Separated from `#runBoot` so the phase span wrapper
    * stays thin and the loop body — which orchestrates rollback on
@@ -770,26 +814,33 @@ export class DotAppImpl {
       this.#emitHook('boot', pip.name, record.order, 'starting');
       let result: ServiceRecord | void;
       try {
-        result = await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: pip.name,
-            pipVersion: pip.version,
-            hook: 'boot',
-            order: record.order,
-            logger: pipLogger,
-          },
-          // Erasure boundary: hooks are stored as `(ctx: never) => ...`;
-          // the kernel is the one caller allowed to cross it.
-          () => pip.hooks.boot!(ctx as never),
+        result = await this.#withHookBudget(pip.name, 'boot', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: pip.name,
+              pipVersion: pip.version,
+              hook: 'boot',
+              order: record.order,
+              logger: pipLogger,
+            },
+            // Erasure boundary: hooks are stored as `(ctx: never) => ...`;
+            // the kernel is the one caller allowed to cross it.
+            () => pip.hooks.boot!(ctx as never),
+          ),
         );
       } catch (error) {
+        const timedOut = error instanceof DotLifecycleError && error.code === DotLifecycleErrorCode.HookTimeout;
         return fail({
           record,
-          code: DotLifecycleErrorCode.BootFailed,
-          message: `boot hook threw for pip "${pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the boot() hook of "${pip.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes pips whose boot completed.`,
-          docsAnchor: 'boot-failed',
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.BootFailed,
+          message: timedOut
+            ? error.message
+            : `boot hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+          remediation: timedOut
+            ? `Find the hang in the boot() hook of "${pip.name}" — a missing await or a connection that never settles — or raise defineApp's hookTimeoutMs.`
+            : `Fix the error in the boot() hook of "${pip.name}". If boot opens partial resources before throwing, clean them up locally — DOT only disposes pips whose boot completed.`,
+          docsAnchor: timedOut ? 'hook-timeout' : 'boot-failed',
           durationMs: performance.now() - started,
           cause: error,
           rollback: bootedRecords,
@@ -917,25 +968,32 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('start', pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: pip.name,
-            pipVersion: pip.version,
-            hook: 'start',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => pip.hooks.start!(ctx as never),
+        await this.#withHookBudget(pip.name, 'start', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: pip.name,
+              pipVersion: pip.version,
+              hook: 'start',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => pip.hooks.start!(ctx as never),
+          ),
         );
       } catch (error) {
         const durationMs = performance.now() - startedAt;
+        const timedOut = error instanceof DotLifecycleError && error.code === DotLifecycleErrorCode.HookTimeout;
         const issue = makeIssue({
-          code: DotLifecycleErrorCode.StartFailed,
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
           pip: pip.name,
-          message: `start hook threw for pip "${pip.name}": ${stringifyError(error)}`,
-          remediation: `Fix the error in the start() hook of "${pip.name}". DOT will stop all already-started pips and dispose all booted pips in reverse order.`,
-          docsAnchor: 'start-failed',
+          message: timedOut
+            ? error.message
+            : `start hook threw for pip "${pip.name}": ${stringifyError(error)}`,
+          remediation: timedOut
+            ? `Find the hang in the start() hook of "${pip.name}" — or raise defineApp's hookTimeoutMs. DOT rolls back as for any start failure.`
+            : `Fix the error in the start() hook of "${pip.name}". DOT will stop all already-started pips and dispose all booted pips in reverse order.`,
+          docsAnchor: timedOut ? 'hook-timeout' : 'start-failed',
         });
         record.issues.push(issue);
         record.lifecycleDiagnostics.push({
@@ -958,7 +1016,7 @@ export class DotAppImpl {
         this.#manifest = this.#buildManifest();
         const failures = [...stopFailures, ...disposeFailures];
         throw new DotLifecycleError({
-          code: DotLifecycleErrorCode.StartFailed,
+          code: timedOut ? DotLifecycleErrorCode.HookTimeout : DotLifecycleErrorCode.StartFailed,
           phase: 'start',
           pip: pip.name,
           message: issue.message,
@@ -1053,16 +1111,18 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('stop', record.pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: record.pip.name,
-            pipVersion: record.pip.version,
-            hook: 'stop',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => record.pip.hooks.stop!(ctx as never),
+        await this.#withHookBudget(record.pip.name, 'stop', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: record.pip.name,
+              pipVersion: record.pip.version,
+              hook: 'stop',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => record.pip.hooks.stop!(ctx as never),
+          ),
         );
         record.started = false;
         const durationMs = performance.now() - startedAt;
@@ -1265,16 +1325,18 @@ export class DotAppImpl {
       const startedAt = performance.now();
       this.#emitHook('dispose', record.pip.name, record.order, 'starting');
       try {
-        await withPipHookSpan(
-          {
-            appName: this.#appName,
-            pipName: record.pip.name,
-            pipVersion: record.pip.version,
-            hook: 'dispose',
-            order: record.order,
-            logger: pipLogger,
-          },
-          () => record.pip.hooks.dispose!(ctx as never),
+        await this.#withHookBudget(record.pip.name, 'dispose', () =>
+          withPipHookSpan(
+            {
+              appName: this.#appName,
+              pipName: record.pip.name,
+              pipVersion: record.pip.version,
+              hook: 'dispose',
+              order: record.order,
+              logger: pipLogger,
+            },
+            () => record.pip.hooks.dispose!(ctx as never),
+          ),
         );
         record.booted = false;
         const durationMs = performance.now() - startedAt;

package/src/lifecycle.ts

@@ -76,6 +76,8 @@ export const DotLifecycleErrorCode = {
   ServiceCollision: 'DOT_LIFECYCLE_E013',
   /** A needs alias, publish key, or rename target uses the reserved `$` prefix. */
   ReservedServiceKey: 'DOT_LIFECYCLE_E014',
+  /** A lifecycle hook exceeded the app's `hookTimeoutMs` watchdog. */
+  HookTimeout: 'DOT_LIFECYCLE_E015',
 } as const;
 
 export type DotLifecycleErrorCodeValue = (typeof DotLifecycleErrorCode)[keyof typeof DotLifecycleErrorCode];

package/src/signals.ts

@@ -0,0 +1,134 @@
+/**
+ * Signal wiring for graceful shutdown.
+ *
+ * `hookSignals(app)` connects OS termination signals to the app's
+ * lifecycle: on the first SIGTERM/SIGINT the app is disposed (which
+ * cascades `stop()` when started — transitions are serialized, so a
+ * signal racing a slow `start()` still ends in `disposed`), then the
+ * signal is re-raised with the default handler restored so the process
+ * terminates with conventional signal semantics.
+ *
+ * Design points:
+ *
+ *  - **First signal drains, second signal kills.** All handlers are
+ *    removed the moment the first signal fires, so an impatient second
+ *    Ctrl-C hits the runtime default (immediate termination) instead of
+ *    a stuck drain.
+ *  - **Bounded.** `timeoutMs` caps the drain. On timeout or dispose
+ *    failure the process still terminates — exit code reflects the
+ *    failure via the re-raised signal; the error is logged on
+ *    `arki:dot:signals`.
+ *  - **No `process.exit()`.** The signal is re-raised via
+ *    `proc.kill(proc.pid, signal)` so the exit status is the standard
+ *    128+n signal encoding — supervisors (systemd, Docker, Coolify)
+ *    read it correctly.
+ */
+
+import { Logger } from '@arki/log';
+
+/**
+ * The slice of `process` the signal hook touches. Injectable so tests can
+ * drive signals through a fake without terminating the test runner —
+ * defaults to the real `process`.
+ */
+export type SignalTarget = {
+  readonly pid: number;
+  once(event: string, listener: (...args: never[]) => void): unknown;
+  off(event: string, listener: (...args: never[]) => void): unknown;
+  kill(pid: number, signal?: string): unknown;
+};
+
+export type HookSignalsOptions = {
+  /** Signals to intercept. Default: `['SIGTERM', 'SIGINT']`. */
+  readonly signals?: readonly string[];
+  /**
+   * Maximum time the drain (`dispose()`) may take before the process is
+   * terminated anyway. Default: 10 000 ms.
+   */
+  readonly timeoutMs?: number;
+  /** Test seam — a process-like target. Default: the real `process`. */
+  readonly proc?: SignalTarget;
+};
+
+/** The app surface the hook needs — satisfied by any `DotApp`. */
+export type Disposable = {
+  readonly name: string;
+  dispose(): Promise<void>;
+};
+
+/**
+ * Wire termination signals to `app.dispose()`. Returns an unhook function
+ * that removes the handlers without disposing — call it if the app is
+ * torn down through another path first.
+ *
+ * ```ts
+ * const app = await defineApp('shop').use(...).start();
+ * hookSignals(app);                          // SIGTERM/SIGINT → drain → exit
+ * hookSignals(app, { timeoutMs: 30_000 });   // slower drain budget
+ * ```
+ */
+export function hookSignals(app: Disposable, options: HookSignalsOptions = {}): () => void {
+  const signals = options.signals ?? ['SIGTERM', 'SIGINT'];
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const proc: SignalTarget = options.proc ?? (process as unknown as SignalTarget);
+  const logger = new Logger('arki:dot:signals', { 'dot.app.name': app.name });
+
+  const handlers = new Map<string, () => void>();
+
+  const unhook = (): void => {
+    for (const [signal, handler] of handlers) proc.off(signal, handler);
+    handlers.clear();
+  };
+
+  for (const signal of signals) {
+    const handler = (): void => {
+      // First signal wins; the rest fall through to runtime defaults.
+      unhook();
+      logger.info('signal received — draining', { 'dot.signal': signal, 'dot.drain.timeout.ms': timeoutMs });
+      void drainAndReraise({ app, signal, timeoutMs, proc, logger });
+    };
+    handlers.set(signal, handler);
+    proc.once(signal, handler);
+  }
+
+  return unhook;
+}
+
+/** Dispose with a timeout cap, then re-raise the signal for default handling. */
+async function drainAndReraise(args: {
+  app: Disposable;
+  signal: string;
+  timeoutMs: number;
+  proc: SignalTarget;
+  logger: Logger;
+}): Promise<void> {
+  const { app, signal, timeoutMs, proc, logger } = args;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<'timeout'>(resolve => {
+    timer = setTimeout(() => {
+      resolve('timeout');
+    }, timeoutMs);
+    // A pending drain timer must never keep an otherwise-finished process alive.
+    if (typeof timer === 'object' && 'unref' in timer) timer.unref();
+  });
+
+  try {
+    const outcome = await Promise.race([app.dispose().then(() => 'disposed' as const), timedOut]);
+    if (outcome === 'timeout') {
+      logger.error('drain timed out — terminating without a clean dispose', {
+        'dot.signal': signal,
+        'dot.drain.timeout.ms': timeoutMs,
+      });
+    } else {
+      logger.info('drain complete', { 'dot.signal': signal });
+    }
+  } catch (error) {
+    logger.error('dispose failed during drain — terminating', {
+      'dot.signal': signal,
+      'dot.error.message': error instanceof Error ? error.message : String(error),
+    });
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    proc.kill(proc.pid, signal);
+  }
+}