fix(daemon)(#19): keep --detach child alive past process.disconnect()

[vrogojin]

Summary

Fixes #19 — sphere daemon start --detach exited successfully with a PID, but the forked child died between fork() and any useful work, leaving a stale PID file and an empty daemon.log.

Root cause

Two compounding bugs in src/legacy/daemon.ts:

1. stdio: 'ignore' strips the IPC channel. child_process.fork() normally establishes an IPC channel, but overriding stdio removes it. The child's process.connected was therefore false from the start.

2. process.disconnect() was guarded only on its existence, not on process.connected. The function exists regardless of channel state, but calling it without a live channel throws "IPC channel is not open". The throw bubbled up to legacy-cli's catch, which called console.error (already redirected to an unflushed WriteStream) and process.exit(1). The child died silently — pending WriteStream writes never flushed because fs.open hadn't completed.

The diagnostic trail that pinpointed this:

[1779532169143] forked-enter pid=474909 connected=false   ← no IPC channel
[1779532169143] pre-disconnect pid=474909 connected=false  ← about to throw
[1779532169143] exit pid=474909 code=1                     ← exited via legacy-cli catch

Fix

src/legacy/daemon.ts:

• Parent side — detachDaemon opens the log file in the parent and inherits the fd to the child's stdout AND stderr (stdio: ['ignore', logFd, logFd, 'ipc']). Any future startup failure — crash, uncaught exception, raw stderr emission — now lands in the log file at the OS level, before any Node-level streaming machinery is needed. 'ipc' is kept because fork() rejects without it; the channel exists solely to satisfy fork's contract (no messages flow).

• Child side — runDaemon's disconnect is now guarded on process.connected, so it correctly no-ops if the channel was already torn down and only disconnects when there's a live channel to release.

• log() double-write — pre-existing bug: in forked mode log() wrote both via logStream.write AND console.log (which was redirected to the same stream), producing duplicate lines. Exposed only because the daemon now actually runs. Fixed via if/else.

Test plan

• Build (npm run build) — clean.
• Typecheck (npm run typecheck) — clean.
• Lint (npm run lint) — no new warnings from these changes (the 5 warnings on daemon.ts are pre-existing on lines unchanged here).
• Unit tests (npm test) — 106/106 passing.
• Issue's exact reproduction (mkdir … && wallet create … && init … && daemon start --detach … && sleep 3 && daemon status) now reports:

  Daemon is running (PID 498927).
  Log file size: 736 bytes
  

  Was: Daemon is not running (stale PID file, process X).
• New integration test (test/integration/cli-daemon.integration.test.ts) — 4 tests, all passing:
  • 3 offline help-shape pins (daemon / daemon start / daemon status)
  • 1 network detach lifecycle pin (start → status running → log non-empty → stop → status not-running → PID file gone)
  • afterEach defensively stops daemon to avoid leaking forked processes that hold open Nostr WebSocket connections.

Acceptance criteria (from the issue)

• sphere daemon start --detach followed by sleep 3 && sphere daemon status reports the daemon as running, with a non-empty daemon.log.
• manual-test-full-recovery.sh §C.3/§C.4 unblocked — once this lands and SDK builds against it, peer2's daemons will receive events as expected. (Confirmed locally; CI run pending.)
• New integration test under test/integration/ mirroring cli-wallet-lifecycle.integration.test.ts.

Related

• sphere-sdk #226 / #227 (merged 2026-05-23) — invoice delivery via UXF DM, the work that motivated this fix.
• sphere-sdk PR #222 / commit 108e9ac — original documentation of --detach as a known limitation.