@stigmer/cli 3.0.8

package/src/local/daemon/env.ts

@@ -0,0 +1,118 @@
+// The foreground launcher hands the supervised daemon everything it needs to
+// run through the environment — the same mechanism the Go CLI uses. Centralizing
+// the variable names and the (de)serialization here keeps that contract in one
+// place: the launcher writes it with buildDaemonEnv, the daemon reads it with
+// readDaemonConfig, and nothing in between guesses at string keys.
+
+/** Environment variable names that make up the launcher -> daemon contract. */
+export const DaemonEnvVar = {
+  DataDir: "STIGMER_DATA_DIR",
+  LogDir: "STIGMER_LOG_DIR",
+  TemporalManaged: "STIGMER_TEMPORAL_MANAGED",
+  TemporalAddress: "TEMPORAL_SERVICE_ADDRESS",
+  ServerOnly: "STIGMER_SERVER_ONLY",
+  NoWeb: "STIGMER_NO_WEB",
+  ServerBin: "STIGMER_SERVER_BIN",
+  RunnerNodeBin: "STIGMER_RUNNER_NODE_BIN",
+  RunnerEntry: "STIGMER_RUNNER_ENTRY",
+  RunnerAppDir: "STIGMER_RUNNER_APP_DIR",
+  CursorApiKey: "CURSOR_API_KEY",
+  ActivityRouting: "STIGMER_ACTIVITY_ROUTING",
+} as const;
+
+/** Resolved runner launch coordinates. */
+export interface RunnerLaunch {
+  nodeBin: string;
+  entryPath: string;
+  appDir: string;
+}
+
+/** The daemon's resolved configuration, parsed from the environment. */
+export interface DaemonConfig {
+  dataDir: string;
+  logDir: string;
+  temporalManaged: boolean;
+  temporalAddress: string;
+  serverOnly: boolean;
+  noWeb: boolean;
+  serverBin: string;
+  runner?: RunnerLaunch;
+  cursorApiKey?: string;
+  activityRouting?: string;
+}
+
+/** Inputs the launcher already resolved, to encode into the daemon env. */
+export interface DaemonEnvInputs {
+  dataDir: string;
+  logDir: string;
+  temporalManaged: boolean;
+  temporalAddress: string;
+  serverOnly: boolean;
+  noWeb: boolean;
+  serverBin: string;
+  runner?: RunnerLaunch;
+}
+
+/**
+ * Build the environment for the internal-daemon child: the caller's environment
+ * plus the resolved contract values. Runner coordinates are omitted in
+ * server-only mode.
+ */
+export function buildDaemonEnv(inputs: DaemonEnvInputs, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...base };
+  env[DaemonEnvVar.DataDir] = inputs.dataDir;
+  env[DaemonEnvVar.LogDir] = inputs.logDir;
+  env[DaemonEnvVar.TemporalManaged] = String(inputs.temporalManaged);
+  env[DaemonEnvVar.TemporalAddress] = inputs.temporalAddress;
+  env[DaemonEnvVar.ServerBin] = inputs.serverBin;
+  if (inputs.serverOnly) env[DaemonEnvVar.ServerOnly] = "true";
+  if (inputs.noWeb) env[DaemonEnvVar.NoWeb] = "1";
+  if (inputs.runner !== undefined && !inputs.serverOnly) {
+    env[DaemonEnvVar.RunnerNodeBin] = inputs.runner.nodeBin;
+    env[DaemonEnvVar.RunnerEntry] = inputs.runner.entryPath;
+    env[DaemonEnvVar.RunnerAppDir] = inputs.runner.appDir;
+  }
+  return env;
+}
+
+/** Parse the daemon configuration from an environment. Throws if a required
+ * value is missing. */
+export function readDaemonConfig(env: NodeJS.ProcessEnv = process.env): DaemonConfig {
+  const dataDir = required(env, DaemonEnvVar.DataDir);
+  const logDir = env[DaemonEnvVar.LogDir] ?? `${dataDir}/logs`;
+  const serverOnly = env[DaemonEnvVar.ServerOnly] === "true";
+
+  const runner = readRunner(env);
+  return {
+    dataDir,
+    logDir,
+    temporalManaged: env[DaemonEnvVar.TemporalManaged] === "true",
+    temporalAddress: env[DaemonEnvVar.TemporalAddress] ?? "127.0.0.1:7233",
+    serverOnly,
+    noWeb: env[DaemonEnvVar.NoWeb] === "1",
+    serverBin: required(env, DaemonEnvVar.ServerBin),
+    runner: serverOnly ? undefined : runner,
+    cursorApiKey: nonEmpty(env[DaemonEnvVar.CursorApiKey]),
+    activityRouting: nonEmpty(env[DaemonEnvVar.ActivityRouting]),
+  };
+}
+
+function readRunner(env: NodeJS.ProcessEnv): RunnerLaunch | undefined {
+  const nodeBin = env[DaemonEnvVar.RunnerNodeBin];
+  const entryPath = env[DaemonEnvVar.RunnerEntry];
+  const appDir = env[DaemonEnvVar.RunnerAppDir];
+  if (!nodeBin || !entryPath || !appDir) return undefined;
+  return { nodeBin, entryPath, appDir };
+}
+
+function required(env: NodeJS.ProcessEnv, key: string): string {
+  const value = env[key];
+  if (value === undefined || value === "") {
+    throw new Error(`${key} is required for the daemon process`);
+  }
+  return value;
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value !== undefined && value !== "" ? value : undefined;
+}

package/src/local/daemon/host.ts

@@ -0,0 +1,79 @@
+// The production ProcessHost and Clock.
+//
+// Children are spawned detached (their own process group) so the whole tree can
+// be signaled, with stdout+stderr piped through the daemon. The daemon tees each
+// chunk to the component's log file and scans stdout for an optional readiness
+// marker — the same pipe-and-watch shape the conformance/e2e harnesses use,
+// which is what lets `status` report "runner actually polling" instead of mere
+// liveness. Logs survive normally because the daemon outlives its children; an
+// abnormal daemon death is handled by orphan cleanup on the next `up`.
+
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { killProcessGroup } from "../state/proc.js";
+import type { ChildHandle, Clock, ExitInfo, ProcessHost, SpawnRequest } from "./types.js";
+
+export class NodeProcessHost implements ProcessHost {
+  spawn(request: SpawnRequest): ChildHandle {
+    const out = createWriteStream(request.logFile, { flags: "a" });
+    const child = spawn(request.command, request.args, {
+      cwd: request.cwd,
+      env: request.env,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let exited = false;
+    let exitCb: ((info: ExitInfo) => void) | null = null;
+    let readyCb: (() => void) | null = null;
+    let ready = false;
+
+    // Keep a small rolling tail so a marker split across chunks is still found.
+    let tail = "";
+    const marker = request.readinessMarker;
+    child.stdout?.on("data", (chunk: Buffer) => {
+      out.write(chunk);
+      if (marker !== undefined && !ready) {
+        tail = (tail + chunk.toString("utf8")).slice(-Math.max(marker.length * 2, 256));
+        if (tail.includes(marker)) {
+          ready = true;
+          readyCb?.();
+        }
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer) => out.write(chunk));
+
+    child.on("exit", (code, signal) => {
+      exited = true;
+      out.end();
+      exitCb?.({ code, signal });
+    });
+    child.on("error", (err) => {
+      out.write(`failed to spawn ${request.command}: ${String(err)}\n`);
+      exited = true;
+      exitCb?.({ code: null, signal: null });
+    });
+
+    const pid = child.pid ?? -1;
+    return {
+      pid,
+      hasExited: () => exited,
+      onExit: (cb) => {
+        exitCb = cb;
+      },
+      onReady: (cb) => {
+        readyCb = cb;
+        if (ready) cb();
+      },
+      kill: (signal) => {
+        if (pid > 0) killProcessGroup(pid, signal);
+      },
+    };
+  }
+}
+
+/** Real wall-clock implementation of Clock. */
+export const systemClock: Clock = {
+  now: () => Date.now(),
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};

package/src/local/daemon/index.ts

@@ -0,0 +1,18 @@
+// Public surface of the daemon subsystem.
+
+export { buildComponents, buildRunnerEnv, buildServerEnv } from "./components.js";
+export { type DaemonConfig, type DaemonEnvInputs, DaemonEnvVar, buildDaemonEnv, readDaemonConfig } from "./env.js";
+export { NodeProcessHost, systemClock } from "./host.js";
+export { down, isRunning, type UpOptions, up } from "./launch.js";
+export { type InternalDaemonDeps, type TemporalControl, runInternalDaemon } from "./process.js";
+export {
+  HEALTH_CHECK_INTERVAL_MS,
+  MAX_RESTARTS,
+  MAX_UNHEALTHY_CHECKS,
+  ProcessSupervisor,
+  RAPID_CRASH_WINDOW_MS,
+  SETTLE_DELAY_MS,
+  type StartResult,
+  type SupervisorDeps,
+} from "./supervisor.js";
+export type { ChildHandle, Clock, ComponentSpec, ExitInfo, ProcessHost, ReadinessGate, SpawnRequest } from "./types.js";

package/src/local/daemon/launch.ts

@@ -0,0 +1,260 @@
+// Foreground control of the daemon: `up` (spawn + verify + wait-ready),
+// `down` (signal + wait + safety-net cleanup), and a liveness check.
+//
+// `up` resolves every heavy dependency in the foreground (Temporal binary,
+// server binary, runner entry) so failures surface with a clear message before
+// a detached daemon is spawned, then re-execs this same CLI as the hidden
+// `internal-daemon` and waits until the server's gRPC port answers.
+
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { type Config, load as loadConfig } from "../../config/config.js";
+import { log } from "../../logger.js";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ExitCode } from "../../errors/exit-codes.js";
+import { DAEMON_PID_FILE, SERVER_PORT } from "../constants.js";
+import { tcpConnects, waitForTcp } from "../net/tcp.js";
+import { dataDir, logDir } from "../paths.js";
+import { readPidFile, removePidFile } from "../state/pidfile.js";
+import { findProcessByPort, isProcessAlive, killProcess } from "../state/proc.js";
+import { type StartupConfig, removeStartupConfig, saveStartupConfig } from "../state/startup-config.js";
+import { rotateLogs } from "../state/log-rotation.js";
+import { ensureRunner } from "../runtime/runner.js";
+import { ensureServerBinary } from "../runtime/server.js";
+import { TemporalManager } from "../temporal/manager.js";
+import { buildDaemonEnv } from "./env.js";
+
+/** How long `up` waits for the server's gRPC port after spawning the daemon. */
+const READY_TIMEOUT_MS = 60_000;
+/** How long to wait for the daemon to come up before checking it is still alive. */
+const DAEMON_SETTLE_MS = 3_000;
+/** How long `down` waits for graceful daemon exit before force-killing. */
+const STOP_TIMEOUT_MS = 15_000;
+const STOP_POLL_MS = 500;
+
+export interface UpOptions {
+  serverOnly?: boolean;
+  noWeb?: boolean;
+}
+
+/** Start the local stack in the background. Throws on any startup failure. */
+export async function up(options: UpOptions = {}, home: string = homedir()): Promise<void> {
+  const data = dataDir(home);
+  const logs = logDir(home);
+
+  cleanupOrphans(data);
+  if (await isRunning(home)) {
+    throw new CliExitError("daemon is already running", ExitCode.General);
+  }
+
+  mkdirSync(data, { recursive: true });
+  mkdirSync(logs, { recursive: true });
+  rotateLogs(logs);
+
+  const config = loadConfig();
+  const temporalManaged = isTemporalManaged(config);
+  const temporal = TemporalManager.forHome(home);
+
+  if (temporalManaged) {
+    log.info("ensuring Temporal is installed");
+    await temporal.ensureInstalled();
+  }
+
+  const serverBin = await ensureServerBinary({ home });
+  const runner = options.serverOnly === true ? undefined : ensureRunner({ home });
+
+  const env = buildDaemonEnv(
+    {
+      dataDir: data,
+      logDir: logs,
+      temporalManaged,
+      temporalAddress: temporal.address,
+      serverOnly: options.serverOnly === true,
+      noWeb: options.noWeb === true,
+      serverBin,
+      runner,
+    },
+    process.env,
+  );
+
+  const daemonPid = spawnDaemon(env, join(logs, "daemon.log"));
+  log.info("daemon process started", { pid: daemonPid });
+
+  await sleep(DAEMON_SETTLE_MS);
+  if (!isProcessAlive(daemonPid)) {
+    throw new CliExitError("daemon process crashed during startup", ExitCode.General, [
+      `Check ${join(logs, "daemon.log")} for details.`,
+    ]);
+  }
+
+  await waitForTcp({ port: SERVER_PORT, timeoutMs: READY_TIMEOUT_MS, label: "stigmer-server" });
+
+  await applySeedpackBestEffort(home);
+
+  saveStartupConfig(data, buildStartupConfig(data, logs, temporal.address, config, daemonPid, options));
+}
+
+/**
+ * Bootstrap the system seedpack into the freshly-started local backend (the TS
+ * equivalent of the Go daemon's EnsureSeedpackBootstrapped). Idempotent via a
+ * content-hash marker, so repeated `up`s are cheap. Best-effort: the stack is
+ * already serving by this point, so a seedpack failure is surfaced as a warning
+ * with a retry hint rather than tearing the stack down.
+ */
+async function applySeedpackBestEffort(home: string): Promise<void> {
+  try {
+    const [{ createBackendClient }, { getDefault }, { applySeedpack }] = await Promise.all([
+      import("../../client/index.js"),
+      import("../../config/config.js"),
+      import("../seedpack/apply.js"),
+    ]);
+    // Always seed the local server `up` just started — never the active backend
+    // context. A user whose CLI is pointed at cloud must still get their local
+    // stack seeded, and must never have system resources applied to their cloud
+    // org. Pin to a fresh local config (localhost:SERVER_PORT) with no auth.
+    const client = createBackendClient({ config: getDefault(), getAccessToken: () => null });
+    const result = await applySeedpack(
+      {
+        controller: client.controller,
+        stigmer: client.stigmer,
+        info: (line) => process.stderr.write(`${line}\n`),
+        warn: (line) => process.stderr.write(`${line}\n`),
+      },
+      { markerDir: dataDir(home), home },
+    );
+    log.debug("seedpack bootstrap complete", { applied: result.applied, hash: result.hash, org: result.org });
+  } catch (err) {
+    log.warn("seedpack bootstrap failed", { error: String(err) });
+    process.stderr.write(
+      "Warning: failed to apply system resources (seedpack). Run 'stigmer seedpack apply' to retry.\n",
+    );
+  }
+}
+
+/** Stop the local stack. Returns false if nothing was running. */
+export async function down(home: string = homedir()): Promise<boolean> {
+  const data = dataDir(home);
+  let pid = readPidFile(join(data, DAEMON_PID_FILE));
+  if (pid === null) pid = findProcessByPort(SERVER_PORT);
+
+  if (pid === null || !isProcessAlive(pid)) {
+    removePidFile(join(data, DAEMON_PID_FILE));
+    await stopManagedTemporal(home);
+    cleanupOrphans(data);
+    return false;
+  }
+
+  // The daemon traps SIGTERM and tears down children + Temporal in order.
+  killProcess(pid, "SIGTERM");
+  log.info("sent SIGTERM to daemon", { pid });
+
+  const deadline = Date.now() + STOP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) {
+      removePidFile(join(data, DAEMON_PID_FILE));
+      removeStartupConfig(data);
+      return true;
+    }
+    await sleep(STOP_POLL_MS);
+  }
+
+  log.warn("daemon did not stop gracefully, force killing", { pid });
+  killProcess(pid, "SIGKILL");
+  removePidFile(join(data, DAEMON_PID_FILE));
+  removeStartupConfig(data);
+  await stopManagedTemporal(home);
+  cleanupOrphans(data);
+  return true;
+}
+
+/** Whether the daemon is running: live PID, else a server-port fallback. */
+export async function isRunning(home: string = homedir()): Promise<boolean> {
+  const data = dataDir(home);
+  const pid = readPidFile(join(data, DAEMON_PID_FILE));
+  if (pid !== null) {
+    if (isProcessAlive(pid)) return true;
+    removePidFile(join(data, DAEMON_PID_FILE)); // stale
+  }
+  return tcpConnects(SERVER_PORT, "127.0.0.1", 1000);
+}
+
+// Re-exec this CLI as the detached internal-daemon, returning its PID. Replaying
+// execArgv carries the tsx loader in dev and is a no-op for a plain-node build.
+function spawnDaemon(env: NodeJS.ProcessEnv, daemonLog: string): number {
+  const script = process.argv[1];
+  if (script === undefined) {
+    throw new CliExitError("cannot resolve the CLI entry point to launch the daemon", ExitCode.General);
+  }
+  const out = openSync(daemonLog, "a");
+  const child = spawn(process.execPath, [...process.execArgv, script, "internal-daemon"], {
+    detached: true,
+    env,
+    stdio: ["ignore", out, out],
+  });
+  child.unref();
+  if (child.pid === undefined) {
+    throw new CliExitError("failed to start the daemon process", ExitCode.General);
+  }
+  return child.pid;
+}
+
+// Kill any daemon/server/runner left alive by a previous, improperly-stopped run.
+function cleanupOrphans(data: string): void {
+  for (const name of [DAEMON_PID_FILE, "stigmer-server.pid", "runner.pid"]) {
+    const pidPath = join(data, name);
+    const pid = readPidFile(pidPath);
+    if (pid === null) continue;
+    if (isProcessAlive(pid)) {
+      log.warn("killing orphaned process from a previous run", { file: name, pid });
+      killProcess(pid, "SIGTERM");
+    }
+    removePidFile(pidPath);
+  }
+}
+
+async function stopManagedTemporal(home: string): Promise<void> {
+  try {
+    await TemporalManager.forHome(home).stop();
+  } catch (err) {
+    log.debug("managed Temporal stop skipped", { error: String(err) });
+  }
+}
+
+// Default to managed Temporal unless the opaque local config explicitly opts out
+// (Go parity: managed is the default). Wave 4's `setup` models this section.
+function isTemporalManaged(config: Config): boolean {
+  const local = config.backend.local as { temporal?: { managed?: boolean } } | undefined;
+  return local?.temporal?.managed !== false;
+}
+
+function buildStartupConfig(
+  data: string,
+  logs: string,
+  temporalAddr: string,
+  config: Config,
+  daemonPid: number,
+  options: UpOptions,
+): StartupConfig {
+  const local = config.backend.local as { llm?: { provider?: string; model?: string; base_url?: string } } | undefined;
+  return {
+    data_dir: data,
+    log_dir: logs,
+    temporal_addr: temporalAddr,
+    llm_provider: local?.llm?.provider ?? "",
+    llm_model: local?.llm?.model ?? "",
+    llm_base_url: local?.llm?.base_url ?? "",
+    execution_mode: "local",
+    sandbox_image: "",
+    sandbox_auto_pull: false,
+    sandbox_cleanup: false,
+    sandbox_ttl: 0,
+    stigmer_server_pid: daemonPid,
+    server_only: options.serverOnly === true,
+  };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/local/daemon/process.ts

@@ -0,0 +1,183 @@
+// The supervised daemon body — the `stigmer internal-daemon` entry point.
+//
+// It brings the local stack up in the canonical order (managed Temporal, then
+// the gated server, then the runner), records a health snapshot readers can
+// trust, runs the 10s health monitor, and on a shutdown signal tears everything
+// down in reverse. Temporal, the process host, the clock, and the shutdown
+// trigger are all injectable so the whole body can be driven in a test without
+// real signals or a real Temporal.
+
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { type Logger, log as defaultLog } from "../../logger.js";
+import { DAEMON_PID_FILE, HEALTH_STATE_FILE } from "../constants.js";
+import { type HealthState, writeHealthState } from "../state/health-state.js";
+import { removePidFile, writePidFile } from "../state/pidfile.js";
+import { TemporalManager } from "../temporal/manager.js";
+import { TemporalSupervisor } from "../temporal/supervisor.js";
+import { isWebConsoleAvailable } from "../webconsole/index.js";
+import { buildComponents } from "./components.js";
+import { type DaemonConfig, readDaemonConfig } from "./env.js";
+import { NodeProcessHost, systemClock } from "./host.js";
+import { HEALTH_CHECK_INTERVAL_MS, ProcessSupervisor, SETTLE_DELAY_MS } from "./supervisor.js";
+import type { Clock, ProcessHost } from "./types.js";
+
+/** The Temporal lifecycle surface the daemon drives. TemporalManager (+ its
+ * supervisor) satisfies it; tests provide a fake. */
+export interface TemporalControl {
+  readonly address: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isRunning(): Promise<boolean>;
+  getPid(): number | null;
+  startSupervisor(): void;
+  stopSupervisor(): void;
+}
+
+export interface InternalDaemonDeps {
+  config?: DaemonConfig;
+  host?: ProcessHost;
+  clock?: Clock;
+  temporal?: TemporalControl;
+  log?: Logger;
+  /** Resolves when shutdown is requested (real entry: SIGTERM/SIGINT). */
+  waitForShutdown: () => Promise<void>;
+  /** Invoked once the stack is up and the monitor is running (tests). */
+  onStarted?: () => void;
+}
+
+/** Run the daemon to completion. Returns the process exit code. */
+export async function runInternalDaemon(deps: InternalDaemonDeps): Promise<number> {
+  const config = deps.config ?? readDaemonConfig();
+  const host = deps.host ?? new NodeProcessHost();
+  const clock = deps.clock ?? systemClock;
+  const log = deps.log ?? defaultLog;
+
+  mkdirSync(config.logDir, { recursive: true });
+  mkdirSync(join(config.dataDir, "workspace"), { recursive: true });
+  writePidFile(join(config.dataDir, DAEMON_PID_FILE), process.pid);
+
+  const healthState: HealthState = {
+    daemon_pid: process.pid,
+    started_at: new Date(clock.now()).toISOString(),
+    components: {},
+  };
+  const healthPath = join(config.dataDir, HEALTH_STATE_FILE);
+  const persist = (): void => writeHealthState(healthPath, healthState);
+
+  const temporal = deps.temporal ?? (config.temporalManaged ? buildTemporal(config, log) : null);
+
+  // --- Start managed Temporal first (the server and runner depend on it). ---
+  if (temporal !== null) {
+    log.info("starting managed Temporal");
+    healthState.components.temporal = { pid: 0, state: "stopped", started_at: "", restart_count: 0 };
+    try {
+      await temporal.start();
+    } catch (err) {
+      healthState.components.temporal.state = "failed";
+      healthState.components.temporal.last_error = String(err);
+      persist();
+      log.error("failed to start managed Temporal", { error: String(err) });
+      return 1;
+    }
+    healthState.components.temporal.pid = temporal.getPid() ?? 0;
+    healthState.components.temporal.state = "running";
+    healthState.components.temporal.started_at = new Date(clock.now()).toISOString();
+    temporal.startSupervisor();
+    persist();
+  }
+
+  // --- Start the server (gated) and runner via the supervisor. ---
+  const supervisor = new ProcessSupervisor(buildComponents(config), { host, clock, healthState, persist, log });
+  const result = await supervisor.startAll();
+  if (!result.ok) {
+    log.error("critical component failed to start", { component: result.failedCritical });
+    if (temporal !== null) {
+      temporal.stopSupervisor();
+      await temporal.stop().catch(() => {});
+    }
+    return 1;
+  }
+
+  // Let processes settle, then catch anything that crashed immediately.
+  await clock.sleep(SETTLE_DELAY_MS);
+  supervisor.settleCheck();
+
+  // Web console: detect-and-skip until T06 wires real serving.
+  healthState.components["web-console"] = {
+    pid: 0,
+    state: config.noWeb || !isWebConsoleAvailable() ? "stopped" : "running",
+    started_at: "",
+    restart_count: 0,
+  };
+  if (config.noWeb) log.info("web console disabled via --no-web");
+  else if (!isWebConsoleAvailable()) log.debug("web console not bundled in this build, skipping");
+  persist();
+
+  // --- Health monitor: sync Temporal + drive one supervisor tick per interval. ---
+  const monitor = setInterval(() => {
+    void (async () => {
+      if (temporal !== null) await syncTemporal(temporal, healthState);
+      await supervisor.tick();
+    })();
+  }, HEALTH_CHECK_INTERVAL_MS);
+  monitor.unref?.();
+
+  log.info("daemon started", { pid: process.pid });
+  deps.onStarted?.();
+
+  // --- Wait for shutdown, then tear down in reverse order. ---
+  await deps.waitForShutdown();
+  log.info("received shutdown signal");
+  clearInterval(monitor);
+
+  await supervisor.shutdown();
+
+  if (temporal !== null) {
+    temporal.stopSupervisor();
+    log.info("stopping managed Temporal");
+    await temporal.stop().catch((err) => log.warn("failed to stop managed Temporal cleanly", { error: String(err) }));
+    if (healthState.components.temporal !== undefined) healthState.components.temporal.state = "stopped";
+  }
+
+  persist();
+  removePidFile(join(config.dataDir, DAEMON_PID_FILE));
+  removePidFile(healthPath);
+  log.info("daemon shutdown complete");
+  return 0;
+}
+
+// Sync the Temporal component's health from its self-supervising manager.
+async function syncTemporal(temporal: TemporalControl, healthState: HealthState): Promise<void> {
+  const state = healthState.components.temporal;
+  if (state === undefined) return;
+  if (await temporal.isRunning()) {
+    state.state = "running";
+    state.pid = temporal.getPid() ?? state.pid;
+    state.last_error = undefined;
+  } else {
+    state.state = "unhealthy";
+  }
+}
+
+// Build the real managed-Temporal control from the ~/.stigmer layout (home is
+// two levels up from the data dir: ~/.stigmer/data -> ~).
+function buildTemporal(config: DaemonConfig, log: Logger): TemporalControl {
+  const home = dirname(dirname(config.dataDir));
+  const manager = TemporalManager.forHome(home);
+  let supervisor: TemporalSupervisor | null = null;
+  return {
+    get address() {
+      return manager.address;
+    },
+    start: () => manager.start(),
+    stop: () => manager.stop(),
+    isRunning: () => manager.isRunning(),
+    getPid: () => manager.getPid(),
+    startSupervisor: () => {
+      supervisor = new TemporalSupervisor(manager, { log });
+      supervisor.start();
+    },
+    stopSupervisor: () => supervisor?.stop(),
+  };
+}