fix(kernel-cli): log fatal exits from daemon-entry before terminating by FUDCo · Pull Request #966 · MetaMask/ocap-kernel

FUDCo · 2026-07-08T23:08:40Z

Summary

Add process-level handlers in daemon-entry.ts for uncaughtException, unhandledRejection, SIGHUP, and exit.
Each handler synchronously appends a line to daemon.log before the process exits.
Handlers install at module load, before main() runs, so early kernel-init failures also leave a fingerprint.

Why

daemon-entry runs with stdio: 'ignore' under the CLI spawner (see daemon-spawn.ts). Node's default behaviour on uncaughtException / unhandledRejection (print stack to stderr, exit 1) therefore writes to nowhere, and the operator sees only that the daemon vanished — no trace in ~/.ocap*/daemon.log.

I've hit two silent daemon deaths in the last few weeks (matcher daemon disappearing mid-rehearsal, services daemon disappearing between registration and the next call), and in both cases the log ended cleanly on the last successful message with no shutdown line, no error, no stack trace. Debugging cost real time each time.

With this change, every terminating path now leaves at least one line:

[timestamp] [error] Uncaught exception (about to exit): <stack>
[timestamp] [error] Process exiting (code=1).

or

[timestamp] [error] SIGHUP received; exiting.
[timestamp] [error] Process exiting (code=0).

Log-write itself is wrapped in try/catch so a broken log file doesn't mask the original exit cause.

Test plan

yarn workspace @metamask/kernel-cli test:dev:quiet --run — all package tests pass.
yarn workspace @metamask/kernel-cli lint — clean.
CI green.
Manual (in a downstream branch): induce an uncaught exception in a scratch daemon under a temp $OCAP_HOME, confirm the log line lands and the process exits 1.

🤖 Generated with Claude Code

Note

Low Risk
Observability-only changes to daemon exit paths; SIGHUP now logs and exits 0 explicitly instead of the default silent terminate, with no auth or data-handling impact.

Overview
Daemon fatal-path visibility when the CLI spawns daemon-entry with stdio: 'ignore': uncaught errors and signals no longer vanish with no record in daemon.log.

daemon-entry now builds the file logger at module load (before main()), registers installFatalHandlers() immediately, and logs then exits on uncaughtException, unhandledRejection, and SIGHUP, with an exit handler that always writes a final line. The log transport switches from dynamic require('node:fs') to appendFileSync so fatal handlers flush synchronously. CHANGELOG documents the fix under Unreleased.

^{Reviewed by Cursor Bugbot for commit 70b96eb. Bugbot is set up for automated code reviews on this repo. Configure here.}

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.

github-actions · 2026-07-08T23:18:28Z

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	71.31% ⬇️ -0.08%	8869 / 12437
🔵	Statements	71.13% ⬇️ -0.08%	9019 / 12678
🔵	Functions	72.46% ⬇️ -0.13%	2140 / 2953
🔵	Branches	64.81% ⬇️ -0.11%	3584 / 5530

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/kernel-cli/src/commands/daemon-entry.ts	0% 🟰 ±0%	0% 🟰 ±0%	0% 🟰 ±0%	0% 🟰 ±0%	14-203

Generated in workflow #4529 for commit 70b96eb by the Vitest Coverage Report Action

grypez

I think it would suffice to create the logger at file root scope instead of in the main header. File-scoped logger for entrypoints is already standard convention across the monorepo; seems we just missed this one because it is a command.

grypez · 2026-07-09T13:38:53Z

+/**
+ * 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.
+  }
+}


Suggested change

/**

* 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.

}

}

The logger dispatch routine is already synchronous; async methods follow 'spray and pray' semantics, i.e. best effort.

I think the process.on handlers are doing the work here, not this function.

Good call — done in 70b96eb. Logger dispatch is indeed synchronous (Logger.#dispatch iterates transports via .forEach) and our file transport is appendFileSync, so logger.error(...) from a fatal handler flushes to disk before exit. Dropped the parallel sync helper.

grypez · 2026-07-09T13:48:58Z

+  process.on('uncaughtException', (error: unknown) => {
+    const detail =
+      error instanceof Error ? (error.stack ?? error.message) : String(error);
+    logFatalSync(logPath, 'Uncaught exception (about to exit):', detail);


Suggested change

logFatalSync(logPath, 'Uncaught exception (about to exit):', detail);

logger.error('Uncaught exception', detail);

Done — the handler now calls logger.error(...) directly, and the file-scoped logger it references is hoisted to module top level in the same commit.

@grypez

Applying @grypez review feedback on PR #966: - Move the logger and its path from inside main() to file scope, matching the entrypoint convention already used by app.ts, background.ts, and vat-worker.ts. - Delete logFatalSync — the logger's dispatch routine is synchronous (Logger.#dispatch iterates transports via .forEach) and the file transport itself is appendFileSync, so logger.error(...) from inside a fatal handler flushes to disk before the process exits. - Fatal handlers now call logger.error directly instead of the parallel sync helper. Behaviour is unchanged: every terminating path still writes a line to daemon.log before the process goes away.

@grypez

Applying @grypez review feedback on PR #966: - Move the logger and its path from inside main() to file scope, matching the entrypoint convention already used by app.ts, background.ts, and vat-worker.ts. - Delete logFatalSync — the logger's dispatch routine is synchronous (Logger.#dispatch iterates transports via .forEach) and the file transport itself is appendFileSync, so logger.error(...) from inside a fatal handler flushes to disk before the process exits. - Fatal handlers now call logger.error directly instead of the parallel sync helper. Behaviour is unchanged: every terminating path still writes a line to daemon.log before the process goes away.

The demo branch's file-scope logger construction hit a temporal- dead-zone reference because `makeFileTransport(logPath, resolveMinLogLevel())` runs at module top and `resolveMinLogLevel` uses `LOG_LEVELS`, which was declared as a `const` further down the file. Function declarations hoist but `const` bindings stay in TDZ until execution reaches them, so the daemon child crashed at module init with: ReferenceError: Cannot access 'LOG_LEVELS' before initialization The crash happened before the fatal-handler install ran, and the child was spawned with stdio: 'ignore', so the failure surfaced only as a 30-second polling timeout ("Daemon did not start"). Move `LOG_LEVELS`, `LogLevelName`, and `resolveMinLogLevel()` above the module-scope logger construction. Fixes the demo branch; PR #966 (main-based) is unaffected because its transport factory doesn't reference `LOG_LEVELS`.

docs(kernel-cli): link changelog entry to #966

9b9d82b

FUDCo marked this pull request as ready for review July 9, 2026 00:43

FUDCo requested a review from a team as a code owner July 9, 2026 00:43

grypez requested changes Jul 9, 2026

View reviewed changes

FUDCo requested a review from grypez July 14, 2026 18:05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

fix(kernel-cli): log fatal exits from daemon-entry before terminating#966
FUDCo wants to merge 3 commits into
mainfrom
chip/daemon-entry-fatal-logging

FUDCo commented Jul 8, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

grypez left a comment

Uh oh!

grypez Jul 9, 2026

Uh oh!

FUDCo Jul 14, 2026

Uh oh!

grypez Jul 9, 2026

Uh oh!

FUDCo Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	logFatalSync(logPath, 'Uncaught exception (about to exit):', detail);
	logger.error('Uncaught exception', detail);

Uh oh!

Conversation

FUDCo commented Jul 8, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Test plan

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

grypez left a comment

Choose a reason for hiding this comment

Uh oh!

grypez Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

FUDCo Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

grypez Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

FUDCo Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

FUDCo commented Jul 8, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading