From d3760cebb498e44687f42ebc3639680d104f3740 Mon Sep 17 00:00:00 2001 From: Chip Morningstar Date: Wed, 8 Jul 2026 16:07:52 -0700 Subject: [PATCH 1/2] fix(kernel-cli): log fatal exits from daemon-entry before terminating MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- packages/kernel-cli/CHANGELOG.md | 1 + .../kernel-cli/src/commands/daemon-entry.ts | 94 ++++++++++++++++++- 2 files changed, 92 insertions(+), 3 deletions(-) diff --git a/packages/kernel-cli/CHANGELOG.md b/packages/kernel-cli/CHANGELOG.md index 2e32a111d..1726892cf 100644 --- a/packages/kernel-cli/CHANGELOG.md +++ b/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] diff --git a/packages/kernel-cli/src/commands/daemon-entry.ts b/packages/kernel-cli/src/commands/daemon-entry.ts index 0a43d64a0..237f7f73d 100644 --- a/packages/kernel-cli/src/commands/daemon-entry.ts +++ b/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 { * @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 */ +} From 9b9d82ba244ffbbd85136bf5adc1fbe14baa882d Mon Sep 17 00:00:00 2001 From: Chip Morningstar Date: Wed, 8 Jul 2026 16:19:45 -0700 Subject: [PATCH 2/2] docs(kernel-cli): link changelog entry to #966 --- packages/kernel-cli/CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/kernel-cli/CHANGELOG.md b/packages/kernel-cli/CHANGELOG.md index 1726892cf..01ef62cb9 100644 --- a/packages/kernel-cli/CHANGELOG.md +++ b/packages/kernel-cli/CHANGELOG.md @@ -20,7 +20,8 @@ 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. +- 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 ([#966](https://github.com/MetaMask/ocap-kernel/pull/966)) + - 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]