​

SPEC-072 — Per-Session Daemon Lifecycle — Spawn, Termination, Cleanup

​

1. Motivation

1. The daemon runs when no Prism is in use. A user who logs in but doesn’t open any editor for the day still has a daemon process consuming a WS connection, heartbeating the backend, and occupying registration rows. The system pays for an “always-on listener” whose only consumer (the editor surface) isn’t running.
2. OS-launcher integration is heavy and platform-specific. Each OS requires a different installer path. The install lane carries the cross-OS complexity. Every new OS adds another launcher template.

​

2. Goals

• Daemon’s lifetime is bounded by the Prism session: it spawns on prism_start and terminates on prism_wrap (or when the shim process dies abruptly without a wrap).
• Never running when there’s no active Prism session.
• No OS-launcher integration. Cross-platform contract is identical.
• 1:1 relationship — one bootstrapped session, one daemon. No shared-resource machinery (no lockfile, no connection counting, no linger window).
• Backend orphan-row cleanup is automatic via the existing routing-registry liveness probe (PR #56).
• Shim-side handle tracking ensures bootstraps are idempotent — repeated prism_start calls without intervening prism_wrap do not duplicate daemons.

​

3. Non-goals

• No multi-session sharing. If a future workflow puts the same persona on two editor surfaces simultaneously (each with its own bootstrapped session), two daemons spawn. Signals fan out via the existing publish path; the recipient sees the doorbell twice. Duplicate but not broken.
• No always-on listener. “Lola idle 4h, teammate sends mail” → bootstrap drain on next session.
• No OS service / LaunchAgent / systemd integration. SPEC-070 §B4 templates are retired.
• No daemon-spawned-by-installer. prism install does not start the daemon.

​

4. The unit of life: one bootstrapped session, one daemon

​

5. Spawn — on prism_start

// module-level singleton
let daemon_process: ChildProcess | null = null;

async function spawnDaemonForSession(): Promise<void> {
  if (daemon_process) {
    // Idempotent — re-bootstrap inside the same shim without an intervening
    // wrap is a no-op. Existing daemon continues serving the (re-)registered
    // session.
    return;
  }
  daemon_process = spawn(process.execPath, [daemonBinPath()], {
    stdio: ["pipe", "ignore", "ignore"],   // shim writes to daemon's stdin; stdout/stderr ignored
    detached: false,                       // implementation detail; not load-bearing for correctness
    env: {
      ...process.env,
      PRISM_DAEMON_SHIM_PID: String(process.pid),
      PRISM_DAEMON_SHIM_DOORBELL_PATH: shimDoorbellSocketPath(),
    },
  });
  daemon_process.unref();   // shim's event loop can exit independently of daemon's
  daemon_process.on("exit", () => { daemon_process = null; });
}

​

6. Termination — on prism_wrap, and on shim death

​

6.1 Clean termination via prism_wrap

async function shutdownDaemonForSession(): Promise<void> {
  if (!daemon_process) return;   // no daemon to shut down
  const proc = daemon_process;
  daemon_process = null;          // clear singleton up front so a concurrent prism_start can spawn fresh
  try {
    proc.stdin?.end();             // close the pipe → daemon's EOF handler fires
  } catch {
    /* daemon already exited; nothing to do */
  }
  // We don't await the daemon's exit; its graceful shutdown runs async.
  // Backend's liveness probe handles the registration row regardless.
}

​

6.2 Daemon-side EOF handler

process.stdin.on("end", () => initiateGracefulShutdown("stdin_eof"));
process.stdin.on("error", () => initiateGracefulShutdown("stdin_error"));
process.stdin.resume();   // start reading; we don't expect data, just EOF

1. Mark FSM SHUTTING_DOWN (new terminal state added to ADR-41 FSM)
2. Stop accepting new UDS clients
3. Close all WS connections to backend (sends WS close frame so backend’s _forward_pubsub task observes disconnect cleanly)
4. Call prism_wrap(kind=daemon) to deregister the daemon row (best-effort; backend liveness probe handles it if this fails)
5. Flush any in-flight metrics
6. process.exit(0)

​

6.3 Shim-death backstop

​

7. Edge cases

​

8. Backend cleanup of fragments

1. Graceful deregister — daemon’s initiateGracefulShutdown calls prism_wrap(kind=daemon). Backend marks the row released_at = NOW().
2. Liveness probe (PR #56) — if heartbeat falls behind the 60s threshold, send-time resolution treats the daemon as not_available_stale and the routing-registry sweep marks the row stale.
3. gRPC heartbeat continuity — bidirectional gRPC stream (via prism-server-backend-grpc container) provides faster signal than HTTP polling; broken stream is immediate evidence of daemon death. Aspirational optimization, not a v1 gate (Texi calibration). v1 ships with HTTP heartbeat.

​

9. Cross-platform considerations

• All platforms: resolved relative to the running shim binary’s location: path.join(path.dirname(import.meta.url), "daemon", "server.js") (after URL→path normalization)
• Spawn: spawn(process.execPath, [daemonBinPath()], ...) invokes the same Node binary the shim is running under — no cross-platform shell wrapper

​

10. What changes vs SPEC-070 v0.2

​

11. Implementation plan

​

Phase A — Shim spawn integration (Donna)

• A1. Module-level daemon_process: ChildProcess | null singleton in mcp-node/src/verbs/lifecycle.ts
• A2. spawnDaemonForSession() helper called after session registration in prism_start. Idempotent against re-spawn.
• A3. Daemon path resolution helper (daemonBinPath()) using path.dirname(import.meta.url) + relative resolve to daemon/server.js
• A4. Spawn-failure handling — log to stderr, emit prism_daemon_spawn_failed{reason} metric, non-fatal

​

Phase B — Shim-side wrap shutdown + daemon stdin-EOF handler (Donna)

• B1. shutdownDaemonForSession() in prism_wrap path — clears singleton, closes daemon stdin
• B2. Daemon entry point opens process.stdin reader on start
• B3. EOF / error handlers call initiateGracefulShutdown(reason)
• B4. FSM gains SHUTTING_DOWN terminal state; reconnect logic gates on it
• B5. Graceful shutdown sequence (UDS close → WS close → deregister → metrics flush → exit)

​

Phase C — Retire SPEC-070 §B4 (Lafonda + Donna)

• C1. Lafonda: close the feat/spec-070-b4-install-lane-2026-05-02 worktree without merging the launcher templates
• C2. Lafonda + Donna: move daemon entry to mcp-node/dist/daemon/server.js packaging; ensure prism install ships the file
• C3. Donna: remove or repurpose prism_persona_destroy’s daemon-talking path
• C4. Update SPEC-070 (v0.3 or annotation) to point at SPEC-072 for launch lifecycle

​

Phase D — Smoke (Donna + Porsche)

• D1. End-to-end smoke: shim bootstrap → prism_start → daemon spawn → WS connection visible in prism_status daemon view → prism_wrap → daemon exits within 1s → backend row marked released. Then prism_start again in same shim → fresh daemon. Then kill shim → daemon exits via stdin EOF backstop.
• D2. Porsche: dashboard shows daemon spawn / death events as observable mesh state (folds into SPEC-071 §11 card)

​

12. Resolved during review

• Daemon binary packaging: ships at mcp-node/dist/daemon/server.js (sibling of mcp-node/dist/server.js). Same shipped artifact as the shim, same versioning unit. Adopted in §10.
• Spawn-failure policy: non-fatal, log to stderr, emit metric. No system signal escalation. Adopted in §5.
• gRPC heartbeat upgrade: aspirational, not a v1 gate. v1 ships with HTTP heartbeat. Adopted in §8 item 3.

​

13. References

• SPEC-070 v0.2 — daemon binary architecture (foundation; this SPEC narrows §B4 only)
• ADR-41 — daemon FSM; gains SHUTTING_DOWN terminal state via this SPEC
• ADR-42 — project attach lifecycle (unchanged)
• ADR-43 — daemon-via-shim (filed by Texi during SPEC-070 ratification; this SPEC provides the concrete launch contract)
• PR #52 — agent_sessions.kind=daemon discriminator (unchanged)
• PR #56 — routing-registry liveness probe (provides 60s stale threshold for fragment cleanup)
• PR #57 — daemon binary skeleton
• PR #67 — backend wake-up: daemon WS receipt is notification, not delivery
• PR #81 — mcp-launcher staleness check (relevant: the launcher is what keeps the shim long-lived across editor restarts; the unit-of-life is therefore the bootstrapped session, not the shim process)
• project_open_todo_kill_fallback — retired by this SPEC
• feedback_frank_spidy_sense_pattern — encapsulation > resource economy; drives the 1:1 choice
• feedback_optimize_later — get architecture uniform first; multi-surface-per-persona is unobserved
• project_lane_split_install_vs_deploy — Lafonda owns install lane scope reduction in §11 Phase C
• SPEC-071 — Signal Bus QoS (independent SPEC; daemon participates as a kind=daemon recipient via the same delivery semantics)

​

14. Revision log

• v0.1 (2026-05-03 02:35Z) — initial draft circulated for review
• v0.2 (2026-05-03 02:42Z) — Texi review revisions:
  • Finding 1: corrected the unit-of-life. Daemon is scoped to the bootstrapped session, NOT the shim process. Spawn on prism_start (idempotent against re-bootstrap), terminate on prism_wrap (shim closes daemon’s stdin, fires the same EOF mechanism). Stdin-EOF on shim death remains the unclean-exit backstop. §4-§7 rewritten.
  • Finding 2: removed the “process-group cleanup belt-and-suspenders” claim from the correctness story. Stdin EOF is the only normative parent-death mechanism. detached: false is now flagged as implementation hygiene only.
  • Finding 3: added the module-level singleton handle daemon_process in the shim. Re-bootstrap without wrap is a no-op (existing daemon continues); wrap clears the handle so the next prism_start spawns fresh. §5-§7 carry the rule.
  • Plus calibration: daemon packaging at mcp-node/dist/daemon/server.js, spawn-failure metric, gRPC aspirational not v1 gate.