fix(kernel-cli): log fatal exits from daemon-entry before terminating

daemon-entry runs with `stdio: 'ignore'` under the CLI spawner, so
Node's default behaviour on uncaughtException / unhandledRejection
(print stack to stderr, exit 1) writes to nowhere and the operator
sees only that the daemon vanished. Two recent debugging sessions
were consumed by silent daemon deaths that left no trace.

Install process-level handlers that append a synchronous log line
before the process exits:

  - uncaughtException — captures stack, exits(1)
  - unhandledRejection — captures reason, exits(1)
  - SIGHUP — logs, exits(0) (default was silent terminate)
  - exit — last-ditch record; fires on every exit path

Handlers are installed at module load, before main() runs, so
early kernel-init failures also leave a fingerprint. Each handler
uses only synchronous fs and the fs write is wrapped in try/catch
so a log-write failure never masks the original exit cause.

Author: FUDCo

packages/kernel-cli/CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - `kernel daemon start` refuses to start when another daemon is already listening on the same Unix socket, instead of unlinking the socket and orphaning the running process ([#952](https://github.com/MetaMask/ocap-kernel/pull/952))
+- Daemon fatal-path visibility: `daemon-entry` now installs handlers for `uncaughtException`, `unhandledRejection`, `SIGHUP`, and `exit` that append a synchronous fingerprint line to `daemon.log` before terminating. Without these, silent daemon deaths under `stdio: 'ignore'` (the CLI's default spawn mode) left no trace in the log; the operator saw only that the daemon was gone. Every terminating path now leaves at least one line.
 
 ## [0.1.0]
 

packages/kernel-cli/src/commands/daemon-entry.ts

@@ -4,12 +4,24 @@ import { startDaemon } from '@metamask/kernel-node-runtime/daemon';
 import type { DaemonHandle } from '@metamask/kernel-node-runtime/daemon';
 import type { LogEntry } from '@metamask/logger';
 import { Logger } from '@metamask/logger';
+import { appendFileSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { getOcapHome } from '../ocap-home.ts';
 import { isProcessAlive } from '../utils.ts';
 
+// Install exit-cause handlers at module load, before main() runs, so
+// failures during kernel init also leave a fingerprint. daemon-entry
+// runs with `stdio: 'ignore'` under the CLI spawner (see
+// `daemon-spawn.ts`); without these, an uncaught exception, an
+// unhandled rejection, or a SIGHUP terminates the process silently
+// with no record in `daemon.log`. Silent deaths cost real debugging
+// time — see the run-notes for two past cases where a daemon
+// disappeared with no trace. Every terminating path now writes at
+// least one line before the process goes away.
+installFatalHandlers(join(getOcapHome(), 'daemon.log'));
+
 main().catch((error) => {
   process.stderr.write(`Daemon fatal: ${String(error)}\n`);
   process.exitCode = 1;
@@ -133,11 +145,87 @@ async function readDaemonPid(pidPath: string): Promise<number | undefined> {
  * @returns A log transport function.
  */
 function makeFileTransport(logPath: string) {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports, n/global-require -- need sync fs for log transport
-  const fs = require('node:fs') as typeof import('node:fs');
   return (entry: LogEntry): void => {
     const line = `[${new Date().toISOString()}] [${entry.level}] ${entry.message ?? ''} ${(entry.data ?? []).map(String).join(' ')}\n`;
     // eslint-disable-next-line n/no-sync -- synchronous write needed for log transport reliability
-    fs.appendFileSync(logPath, line);
+    appendFileSync(logPath, line);
   };
 }
+
+/**
+ * Append a fatal-path entry to `daemon.log` synchronously. Used from
+ * `process.on('uncaughtException' | 'unhandledRejection' | 'SIGHUP')`
+ * handlers where the async logger pipeline can't be trusted to
+ * flush before the process exits. Best-effort: if the log file is
+ * unwritable we swallow the error rather than throw from a fatal
+ * handler.
+ *
+ * @param logPath - The daemon-log file path.
+ * @param message - Short label for the entry.
+ * @param detail - Optional extra data (stack, error, etc.) — coerced
+ *   to string.
+ */
+function logFatalSync(
+  logPath: string,
+  message: string,
+  detail?: string | number,
+): void {
+  try {
+    const tail = detail === undefined ? '' : ` ${detail}`;
+    const line = `[${new Date().toISOString()}] [error] ${message}${tail}\n`;
+    // eslint-disable-next-line n/no-sync -- fatal handler must flush before exit
+    appendFileSync(logPath, line);
+  } catch {
+    // Best-effort — the daemon is dying either way.
+  }
+}
+
+/**
+ * Install process-level handlers that guarantee a log line is
+ * written for every terminating event before the daemon exits.
+ *
+ * Handlers registered:
+ *
+ * - `uncaughtException` — the classic silent-death path. Node's
+ *   default is to print the stack to stderr and exit with code 1;
+ *   under `stdio: 'ignore'` (how the daemon is spawned) that
+ *   default writes nowhere.
+ * - `unhandledRejection` — currently defaults to a warning in
+ *   Node, but future Node versions treat it as uncaughtException;
+ *   either way we want a fingerprint.
+ * - `SIGHUP` — sent when the controlling terminal disappears
+ *   (ssh session closed, laptop lid closed while the daemon was
+ *   under an interactive shell). Default action terminates the
+ *   process; installing a handler lets us log the fact before
+ *   exiting.
+ * - `exit` — last-ditch record. Fires during every exit, including
+ *   the ones already logged by the handlers above. Sync-safe: only
+ *   sync APIs are usable here.
+ *
+ * @param logPath - The daemon-log file path.
+ */
+function installFatalHandlers(logPath: string): void {
+  /* eslint-disable n/no-sync, n/no-process-exit -- fatal handlers must flush synchronously and terminate deterministically */
+  process.on('uncaughtException', (error: unknown) => {
+    const detail =
+      error instanceof Error ? (error.stack ?? error.message) : String(error);
+    logFatalSync(logPath, 'Uncaught exception (about to exit):', detail);
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason: unknown) => {
+    const detail =
+      reason instanceof Error
+        ? (reason.stack ?? reason.message)
+        : String(reason);
+    logFatalSync(logPath, 'Unhandled rejection (about to exit):', detail);
+    process.exit(1);
+  });
+  process.on('SIGHUP', () => {
+    logFatalSync(logPath, 'SIGHUP received; exiting.');
+    process.exit(0);
+  });
+  process.on('exit', (code) => {
+    logFatalSync(logPath, `Process exiting (code=${code}).`);
+  });
+  /* eslint-enable n/no-sync, n/no-process-exit */
+}