@stigmer/cli 3.0.8

package/src/local/artifact.test.ts

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { mapReleaseArch, mapReleaseOs, sha256Hex } from "./artifact.js";
+
+describe("mapReleaseOs", () => {
+  it("maps Node platforms to release OS tokens", () => {
+    expect(mapReleaseOs("darwin")).toBe("darwin");
+    expect(mapReleaseOs("win32")).toBe("windows");
+    expect(mapReleaseOs("linux")).toBe("linux");
+    expect(mapReleaseOs("freebsd")).toBe("linux"); // default bucket
+  });
+});
+
+describe("mapReleaseArch", () => {
+  it("maps Node arch names to release arch tokens", () => {
+    expect(mapReleaseArch("arm64")).toBe("arm64");
+    expect(mapReleaseArch("x64")).toBe("amd64");
+    expect(mapReleaseArch("ppc64")).toBe("ppc64"); // passthrough
+  });
+});
+
+describe("sha256Hex", () => {
+  it("computes a lowercase hex digest matching node:crypto", () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 5]);
+    const expected = createHash("sha256").update(bytes).digest("hex");
+    expect(sha256Hex(bytes)).toBe(expected);
+  });
+});

package/src/local/artifact.ts

@@ -0,0 +1,166 @@
+// Shared primitives for acquiring a single executable from a GitHub-release
+// `.tar.gz`: release platform/arch mapping, a fetch + gunzip + minimal tar
+// reader, optional sha256 verification, and an executable write.
+//
+// Both on-demand downloaders — the Temporal CLI (`temporal/download.ts`) and the
+// `stigmer-server` control plane (`runtime/server.ts`) — build on this, so the
+// fetch/extract contract lives in exactly one place. The tar reader is a tiny
+// POSIX/ustar implementation: no native `tar` dependency, which keeps the base
+// install lean (DD-002).
+
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { gunzipSync } from "fflate";
+import { CliExitError } from "../errors/cli-exit-error.js";
+import { ExitCode } from "../errors/exit-codes.js";
+
+/** Release OS token, matching the `<os>` segment of our release asset names. */
+export function mapReleaseOs(platform: NodeJS.Platform): string {
+  switch (platform) {
+    case "darwin":
+      return "darwin";
+    case "win32":
+      return "windows";
+    default:
+      return "linux";
+  }
+}
+
+/** Release arch token, matching the `<arch>` segment of our release asset names. */
+export function mapReleaseArch(arch: string): string {
+  switch (arch) {
+    case "arm64":
+      return "arm64";
+    case "x64":
+      return "amd64";
+    default:
+      return arch;
+  }
+}
+
+export interface TarballBinarySource {
+  /** URL of the `.tar.gz` archive. */
+  url: string;
+  /**
+   * URL of a `shasum -a 256`-format checksum file for {@link url}. When set, the
+   * downloaded archive's sha256 is verified against it before extraction and any
+   * mismatch aborts the install.
+   */
+  checksumUrl?: string;
+  /** Basename of the entry to extract from the archive. */
+  entryName: string;
+  /** Absolute path to write the extracted, executable binary to. */
+  binPath: string;
+  /** Human label used in error messages (e.g. "Temporal CLI", "stigmer-server"). */
+  label: string;
+  /** Override the fetch implementation (tests). */
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * Download a `.tar.gz`, optionally verify its sha256, extract the named entry,
+ * and write it to `binPath` with executable permissions. Throws a
+ * {@link CliExitError} with the URL on any network, checksum, or extraction
+ * failure.
+ */
+export async function fetchTarballBinary(src: TarballBinarySource): Promise<void> {
+  const doFetch = src.fetchImpl ?? fetch;
+  const archive = await fetchBytes(doFetch, src.url, src.label);
+
+  if (src.checksumUrl !== undefined) {
+    const expected = parseShasum(await fetchText(doFetch, src.checksumUrl, `${src.label} checksum`));
+    const actual = sha256Hex(archive);
+    if (expected === "" || expected !== actual) {
+      throw new CliExitError(`${src.label} checksum mismatch — refusing to use the download`, ExitCode.General, [
+        `expected: ${expected || "(unparseable)"}`,
+        `actual:   ${actual}`,
+        `archive:  ${src.url}`,
+      ]);
+    }
+  }
+
+  const tarBytes = gunzipSync(archive);
+  const binary = extractTarEntry(tarBytes, src.entryName);
+  if (binary === null) {
+    throw new CliExitError(`${src.entryName} not found in the downloaded ${src.label} archive`, ExitCode.General, [
+      `archive: ${src.url}`,
+    ]);
+  }
+
+  mkdirSync(dirname(src.binPath), { recursive: true });
+  writeFileSync(src.binPath, binary, { mode: 0o755 });
+  chmodSync(src.binPath, 0o755);
+}
+
+/** Lowercase hex sha256 of `bytes`. */
+export function sha256Hex(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+async function fetchBytes(doFetch: typeof fetch, url: string, label: string): Promise<Uint8Array> {
+  const res = await doFetchOrThrow(doFetch, url, label);
+  return new Uint8Array(await res.arrayBuffer());
+}
+
+async function fetchText(doFetch: typeof fetch, url: string, label: string): Promise<string> {
+  const res = await doFetchOrThrow(doFetch, url, label);
+  return res.text();
+}
+
+async function doFetchOrThrow(doFetch: typeof fetch, url: string, label: string): Promise<Response> {
+  let res: Response;
+  try {
+    res = await doFetch(url);
+  } catch (err) {
+    throw new CliExitError(`failed to download ${label} from ${url}`, ExitCode.General, [String(err)]);
+  }
+  if (!res.ok) {
+    throw new CliExitError(`failed to download ${label}: HTTP ${res.status} from ${url}`, ExitCode.General);
+  }
+  return res;
+}
+
+// `shasum`/`sha256sum` output is "<hex>  <filename>"; take the first token.
+function parseShasum(content: string): string {
+  return (content.trim().split(/\s+/)[0] ?? "").toLowerCase();
+}
+
+/**
+ * Extract a single regular-file entry whose basename matches `name` from an
+ * (uncompressed) tar buffer. Minimal POSIX/ustar reader: 512-byte header blocks,
+ * octal size at offset 124, type flag at 156, data padded to 512 bytes.
+ */
+export function extractTarEntry(buf: Uint8Array, name: string): Uint8Array | null {
+  let offset = 0;
+  while (offset + 512 <= buf.length) {
+    const header = buf.subarray(offset, offset + 512);
+    const entryName = readCString(header, 0, 100);
+    if (entryName === "") break; // zero block marks end of archive
+
+    const size = Number.parseInt(readCString(header, 124, 12).trim() || "0", 8) || 0;
+    const typeFlag = String.fromCharCode(header[156] ?? 0);
+    const dataStart = offset + 512;
+
+    const isRegularFile = typeFlag === "0" || typeFlag === "\0";
+    if (isRegularFile && basename(entryName) === name) {
+      return buf.subarray(dataStart, dataStart + size);
+    }
+
+    // Advance past this entry's data, rounded up to the 512-byte block size.
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+  return null;
+}
+
+function readCString(block: Uint8Array, start: number, length: number): string {
+  let end = start;
+  const limit = start + length;
+  while (end < limit && block[end] !== 0) end += 1;
+  return Buffer.from(block.subarray(start, end)).toString("utf8");
+}
+
+function basename(path: string): string {
+  const parts = path.split("/");
+  return parts[parts.length - 1] ?? path;
+}

package/src/local/constants.ts

@@ -0,0 +1,52 @@
+// Cross-cutting constants for the local-stack orchestration subsystem.
+//
+// These are the values that must stay identical across the foreground launcher,
+// the supervised daemon, the Temporal manager, and the status/logs commands.
+// Keeping them in one module is what lets a coding agent change a port or a
+// queue name in exactly one place and trust that server-dispatch and
+// runner-poll can never drift (see the T05 plan's "Critical correctness
+// finding").
+
+/** Port `stigmer-server` listens on (gRPC). Matches the Go CLI's `DaemonPort`. */
+export const SERVER_PORT = 7234;
+
+/** Port the embedded web console is served on (7xxx=API, 8xxx=UI convention). */
+export const WEB_CONSOLE_PORT = 8234;
+
+/** Temporal frontend gRPC port (dev server default). */
+export const TEMPORAL_PORT = 7233;
+
+/** Temporal Web UI port. */
+export const TEMPORAL_UI_PORT = 8233;
+
+/** Temporal namespace the local stack uses end-to-end. */
+export const TEMPORAL_NAMESPACE = "default";
+
+/**
+ * The Temporal task queue the unified runner polls and the server dispatches
+ * to. This is the single source of truth, pinned identically on both the
+ * launched server and the runner so they can never diverge.
+ *
+ * Note: the Go CLI daemon still sets the runner to the stale
+ * `agent_execution_runner` queue while the server dispatches to
+ * `stigmer_runner` (the unified TS runner queue) — a latent hang. The TS CLI
+ * uses the correct value; a Go follow-up tracks fixing the daemon env.
+ */
+export const RUNNER_TASK_QUEUE = "stigmer_runner";
+
+/**
+ * The marker the unified runner prints on stdout once its Temporal worker is
+ * actually polling. Two existing harnesses (`test/conformance`, `test/e2e`)
+ * already depend on it; the daemon uses it to report truthful runner readiness
+ * rather than mere process liveness.
+ */
+export const RUNNER_READY_MARKER = "Worker ready, polling for tasks";
+
+/** PID file names (live under the data dir; see `paths.ts`). */
+export const DAEMON_PID_FILE = "daemon.pid";
+export const SERVER_PID_FILE = "stigmer-server.pid";
+export const RUNNER_PID_FILE = "runner.pid";
+
+/** State file names (live under the data dir). */
+export const HEALTH_STATE_FILE = "health-state.json";
+export const STARTUP_CONFIG_FILE = "startup-config.json";

package/src/local/daemon/components.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { RUNNER_READY_MARKER, RUNNER_TASK_QUEUE } from "../constants.js";
+import type { DaemonConfig } from "./env.js";
+import { buildComponents, buildRunnerEnv, buildServerEnv } from "./components.js";
+
+const config: DaemonConfig = {
+  dataDir: "/home/u/.stigmer/data",
+  logDir: "/home/u/.stigmer/data/logs",
+  temporalManaged: true,
+  temporalAddress: "127.0.0.1:7233",
+  serverOnly: false,
+  noWeb: false,
+  serverBin: "/bin/stigmer-server",
+  runner: { nodeBin: "/bin/node", entryPath: "/repo/runner/dist/main.js", appDir: "/repo/runner" },
+};
+
+describe("buildServerEnv", () => {
+  it("pins ports, queues, and db/storage paths under ~/.stigmer", () => {
+    const env = buildServerEnv(config, {});
+    expect(env.GRPC_PORT).toBe("7234");
+    expect(env.TEMPORAL_HOST_PORT).toBe("127.0.0.1:7233");
+    expect(env.TEMPORAL_NAMESPACE).toBe("default");
+    expect(env.TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE).toBe(RUNNER_TASK_QUEUE);
+    expect(env.TEMPORAL_WORKFLOW_EXECUTION_RUNNER_TASK_QUEUE).toBe(RUNNER_TASK_QUEUE);
+    expect(env.DB_PATH).toBe("/home/u/.stigmer/stigmer.db");
+    expect(env.STORAGE_PATH).toBe("/home/u/.stigmer/storage");
+  });
+});
+
+describe("buildRunnerEnv", () => {
+  it("configures static mode with the workspace and pinned queue", () => {
+    const env = buildRunnerEnv(config, {});
+    expect(env.MODE).toBe("local");
+    expect(env.STIGMER_RUNNER_MODE).toBeUndefined(); // static mode
+    expect(env.STIGMER_BACKEND_ENDPOINT).toBe("http://localhost:7234");
+    expect(env.TEMPORAL_SERVICE_ADDRESS).toBe("127.0.0.1:7233");
+    expect(env.TEMPORAL_NAMESPACE).toBe("default");
+    expect(env.WORKSPACE_ROOT_DIR).toBe("/home/u/.stigmer/data/workspace");
+    expect(env.STIGMER_TASK_QUEUE).toBe(RUNNER_TASK_QUEUE);
+    expect(env.LOG_LEVEL).toBe("info");
+  });
+
+  it("forwards CURSOR_API_KEY and activity routing only when set", () => {
+    expect(buildRunnerEnv(config, {}).CURSOR_API_KEY).toBeUndefined();
+    const withKey = buildRunnerEnv({ ...config, cursorApiKey: "ck", activityRouting: "session" }, {});
+    expect(withKey.CURSOR_API_KEY).toBe("ck");
+    expect(withKey.STIGMER_ACTIVITY_ROUTING).toBe("session");
+  });
+
+  // The regression guard for the queue bug: the server dispatches to, and the
+  // runner polls, the exact same queue.
+  it("pins the runner's poll queue to the server's dispatch queue", () => {
+    const serverEnv = buildServerEnv(config, {});
+    const runnerEnv = buildRunnerEnv(config, {});
+    expect(runnerEnv.STIGMER_TASK_QUEUE).toBe(serverEnv.TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE);
+    expect(runnerEnv.STIGMER_TASK_QUEUE).toBe(serverEnv.TEMPORAL_WORKFLOW_EXECUTION_RUNNER_TASK_QUEUE);
+  });
+});
+
+describe("buildComponents", () => {
+  it("orders server (critical, gated) before runner (marker, not critical)", () => {
+    const components = buildComponents(config, {});
+    expect(components.map((c) => c.name)).toEqual(["stigmer-server", "runner"]);
+
+    const [server, runner] = components;
+    expect(server.critical).toBe(true);
+    expect(server.gate).toBeDefined();
+    expect(server.resolve().readinessMarker).toBeUndefined();
+
+    expect(runner.critical).toBe(false);
+    expect(runner.gate).toBeUndefined();
+    expect(runner.resolve().readinessMarker).toBe(RUNNER_READY_MARKER);
+    expect(runner.resolve().args).toEqual(["/repo/runner/dist/main.js"]);
+  });
+
+  it("omits the runner in server-only mode", () => {
+    const components = buildComponents({ ...config, serverOnly: true }, {});
+    expect(components.map((c) => c.name)).toEqual(["stigmer-server"]);
+  });
+});

package/src/local/daemon/components.ts

@@ -0,0 +1,113 @@
+// Builds the ordered list of managed components and their child environments.
+//
+// This module is where the queue pin lives end-to-end: the server is told to
+// dispatch to RUNNER_TASK_QUEUE and the runner is told to poll RUNNER_TASK_QUEUE,
+// both from the same constant, so the two can never drift. Setting the server's
+// load-bearing env explicitly (ports, queues, db/storage paths) rather than
+// relying on its compiled defaults makes the launch deterministic and the pin
+// enforceable — mirroring test/e2e/fixtures/server-manager.ts.
+
+import { dirname, join } from "node:path";
+import { RUNNER_TASK_QUEUE, RUNNER_READY_MARKER, SERVER_PID_FILE, RUNNER_PID_FILE, SERVER_PORT, TEMPORAL_NAMESPACE } from "../constants.js";
+import { waitForTcp } from "../net/tcp.js";
+import type { DaemonConfig } from "./env.js";
+import type { ComponentSpec, ReadinessGate } from "./types.js";
+
+/** How long the server has to open its gRPC port before startup aborts. */
+const SERVER_GATE_TIMEOUT_MS = 30_000;
+
+/**
+ * Environment for the `stigmer-server` child. Pins ports, Temporal coordinates,
+ * both runner task queues, and the db/storage paths to the ~/.stigmer layout.
+ */
+export function buildServerEnv(config: DaemonConfig, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const configDir = dirname(config.dataDir); // ~/.stigmer
+  return {
+    ...base,
+    GRPC_PORT: String(SERVER_PORT),
+    TEMPORAL_HOST_PORT: config.temporalAddress,
+    TEMPORAL_NAMESPACE,
+    TEMPORAL_AGENT_EXECUTION_RUNNER_TASK_QUEUE: RUNNER_TASK_QUEUE,
+    TEMPORAL_WORKFLOW_EXECUTION_RUNNER_TASK_QUEUE: RUNNER_TASK_QUEUE,
+    DB_PATH: join(configDir, "stigmer.db"),
+    STORAGE_PATH: join(configDir, "storage"),
+  };
+}
+
+/**
+ * Environment for the unified runner child in static mode (STIGMER_RUNNER_MODE
+ * left unset). The runner polls RUNNER_TASK_QUEUE — the corrected queue that the
+ * server actually dispatches to.
+ */
+export function buildRunnerEnv(config: DaemonConfig, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...base,
+    MODE: "local",
+    STIGMER_BACKEND_ENDPOINT: `http://localhost:${SERVER_PORT}`,
+    TEMPORAL_SERVICE_ADDRESS: config.temporalAddress,
+    TEMPORAL_NAMESPACE,
+    WORKSPACE_ROOT_DIR: join(config.dataDir, "workspace"),
+    STIGMER_TASK_QUEUE: RUNNER_TASK_QUEUE,
+    LOG_LEVEL: base.LOG_LEVEL ?? "info",
+  };
+  if (config.cursorApiKey !== undefined) env.CURSOR_API_KEY = config.cursorApiKey;
+  if (config.activityRouting !== undefined) env.STIGMER_ACTIVITY_ROUTING = config.activityRouting;
+  return env;
+}
+
+/**
+ * Build the ordered components: `stigmer-server` (critical, gated on its gRPC
+ * port) always first; the runner second unless server-only. Order matters — the
+ * runner talks to the server.
+ */
+export function buildComponents(config: DaemonConfig, base: NodeJS.ProcessEnv = process.env): ComponentSpec[] {
+  const components: ComponentSpec[] = [
+    {
+      name: "stigmer-server",
+      pidFile: join(config.dataDir, SERVER_PID_FILE),
+      critical: true,
+      resolve: () => ({
+        command: config.serverBin,
+        args: [],
+        env: buildServerEnv(config, base),
+        logFile: join(config.logDir, "stigmer-server.log"),
+      }),
+      gate: serverGate(),
+    },
+  ];
+
+  if (config.serverOnly || config.runner === undefined) {
+    return components;
+  }
+
+  const runner = config.runner;
+  components.push({
+    name: "runner",
+    pidFile: join(config.dataDir, RUNNER_PID_FILE),
+    critical: false,
+    resolve: () => ({
+      command: runner.nodeBin,
+      args: [runner.entryPath],
+      cwd: join(config.dataDir, "workspace"),
+      env: buildRunnerEnv(config, base),
+      logFile: join(config.logDir, "runner.log"),
+      readinessMarker: RUNNER_READY_MARKER,
+    }),
+  });
+  return components;
+}
+
+// The server is ready once its gRPC port accepts a connection; fail fast if it
+// exits first.
+function serverGate(): ReadinessGate {
+  return {
+    description: `stigmer-server gRPC on port ${SERVER_PORT}`,
+    wait: (handle) =>
+      waitForTcp({
+        port: SERVER_PORT,
+        timeoutMs: SERVER_GATE_TIMEOUT_MS,
+        label: "stigmer-server gRPC",
+        getExit: () => (handle.hasExited() ? { code: null, signal: null } : null),
+      }),
+  };
+}

package/src/local/daemon/daemon.integration.test.ts

@@ -0,0 +1,183 @@
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Logger } from "../../logger.js";
+import { RUNNER_READY_MARKER, SERVER_PORT } from "../constants.js";
+import { isProcessAlive } from "../state/proc.js";
+import { loadHealthState, type HealthState } from "../state/health-state.js";
+import { readPidFile } from "../state/pidfile.js";
+import type { DaemonConfig } from "./env.js";
+import { NodeProcessHost } from "./host.js";
+import { runInternalDaemon, type TemporalControl } from "./process.js";
+import type { ChildHandle, Clock, ExitInfo, ProcessHost, SpawnRequest } from "./types.js";
+
+const silent: Logger = { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "stigmer-int-"));
+}
+
+// ---- Integration 1: the real ProcessHost spawns, tees logs, detects the
+// readiness marker, and stops a real child. ----
+describe("NodeProcessHost (real spawn)", () => {
+  it("pipes logs, detects the readiness marker, and stops the child", async () => {
+    const dir = tempDir();
+    const script = join(dir, "fake-child.cjs");
+    writeFileSync(
+      script,
+      `process.stdout.write(${JSON.stringify(`${RUNNER_READY_MARKER}\n`)});\n` +
+        `process.on("SIGTERM", () => process.exit(0));\n` +
+        `setInterval(() => {}, 1000);\n`,
+    );
+    const logFile = join(dir, "child.log");
+
+    const host = new NodeProcessHost();
+    const request: SpawnRequest = {
+      command: process.execPath,
+      args: [script],
+      env: process.env,
+      logFile,
+      readinessMarker: RUNNER_READY_MARKER,
+    };
+    const handle = host.spawn(request);
+
+    const ready = new Promise<void>((resolve) => handle.onReady(resolve));
+    const exited = new Promise<void>((resolve) => handle.onExit(() => resolve()));
+
+    await ready;
+    expect(isProcessAlive(handle.pid)).toBe(true);
+    // The readiness marker is detected on the stdout stream, but the tee to the
+    // log file is a buffered write that may not have flushed to disk yet — poll
+    // the file rather than reading it once to avoid a race.
+    await expect.poll(() => readFileSync(logFile, "utf8")).toContain(RUNNER_READY_MARKER);
+
+    handle.kill("SIGTERM");
+    await exited;
+    expect(handle.hasExited()).toBe(true);
+  });
+});
+
+// ---- Integration 2: the full daemon body, with a fake process host + fake
+// Temporal, but a real TCP listener satisfying the server's gRPC gate. ----
+
+// Minimal fake host whose children exit on SIGTERM.
+class FakeHost implements ProcessHost {
+  private nextPid = 2000;
+  readonly killed: NodeJS.Signals[] = [];
+  spawn(_request: SpawnRequest): ChildHandle {
+    let exited = false;
+    let exitCb: ((info: ExitInfo) => void) | null = null;
+    const pid = this.nextPid++;
+    return {
+      pid,
+      hasExited: () => exited,
+      onExit: (cb) => {
+        exitCb = cb;
+      },
+      onReady: () => {},
+      kill: (signal) => {
+        this.killed.push(signal);
+        if (!exited) {
+          exited = true;
+          exitCb?.({ code: null, signal });
+        }
+      },
+    };
+  }
+}
+
+const fastClock: Clock = { now: () => Date.now(), sleep: () => Promise.resolve() };
+
+function fakeTemporal(): TemporalControl {
+  return {
+    address: "127.0.0.1:7233",
+    start: vi.fn(async () => {}),
+    stop: vi.fn(async () => {}),
+    isRunning: vi.fn(async () => true),
+    getPid: () => 4242,
+    startSupervisor: vi.fn(),
+    stopSupervisor: vi.fn(),
+  };
+}
+
+function listenOn(port: number): Promise<Server> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolve(server));
+  });
+}
+
+let gateServer: Server | null = null;
+afterEach(async () => {
+  if (gateServer !== null) {
+    await new Promise<void>((resolve) => gateServer?.close(() => resolve()));
+    gateServer = null;
+  }
+});
+
+describe("runInternalDaemon (full body with fakes)", () => {
+  it("brings the stack up, writes a health snapshot, and tears down on shutdown", async () => {
+    const data = join(tempDir(), ".stigmer", "data");
+    const config: DaemonConfig = {
+      dataDir: data,
+      logDir: join(data, "logs"),
+      temporalManaged: true,
+      temporalAddress: "127.0.0.1:7233",
+      serverOnly: false,
+      noWeb: true,
+      serverBin: "server-cmd",
+      runner: { nodeBin: "node-cmd", entryPath: join(data, "entry.js"), appDir: data },
+    };
+
+    // Satisfy the server's gRPC readiness gate with a real listener.
+    try {
+      gateServer = await listenOn(SERVER_PORT);
+    } catch {
+      // Port busy (a real daemon?) — the gate will still connect to whatever is
+      // listening, which is all this test needs.
+    }
+
+    const host = new FakeHost();
+    const temporal = fakeTemporal();
+    const healthPath = join(data, "health-state.json");
+
+    let snapshot: HealthState | null = null;
+    let resolveShutdown!: () => void;
+    const shutdown = new Promise<void>((resolve) => {
+      resolveShutdown = resolve;
+    });
+
+    const code = await runInternalDaemon({
+      config,
+      host,
+      clock: fastClock,
+      temporal,
+      log: silent,
+      waitForShutdown: () => shutdown,
+      onStarted: () => {
+        snapshot = loadHealthState(healthPath);
+        resolveShutdown();
+      },
+    });
+
+    expect(code).toBe(0);
+    expect(temporal.start).toHaveBeenCalledOnce();
+    expect(temporal.stop).toHaveBeenCalledOnce();
+
+    // The snapshot captured while up shows the whole stack.
+    expect(snapshot).not.toBeNull();
+    const components = snapshot as unknown as HealthState;
+    expect(components.daemon_pid).toBe(process.pid);
+    expect(Object.keys(components.components).sort()).toEqual(["runner", "stigmer-server", "temporal", "web-console"]);
+    expect(components.components["stigmer-server"].state).toBe("running");
+    expect(components.components.runner.state).toBe("running");
+
+    // Children were signaled, and the daemon cleaned up after shutdown.
+    expect(host.killed).toContain("SIGTERM");
+    expect(readPidFile(join(data, "daemon.pid"))).toBeNull();
+    expect(loadHealthState(healthPath)).toBeNull();
+  });
+});

package/src/local/daemon/env.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { buildDaemonEnv, type DaemonEnvInputs, readDaemonConfig } from "./env.js";
+
+const baseInputs: DaemonEnvInputs = {
+  dataDir: "/home/u/.stigmer/data",
+  logDir: "/home/u/.stigmer/data/logs",
+  temporalManaged: true,
+  temporalAddress: "127.0.0.1:7233",
+  serverOnly: false,
+  noWeb: false,
+  serverBin: "/usr/local/bin/stigmer-server",
+  runner: { nodeBin: "/usr/bin/node", entryPath: "/repo/runner/dist/main.js", appDir: "/repo/runner" },
+};
+
+describe("buildDaemonEnv + readDaemonConfig", () => {
+  it("round-trips the full launcher -> daemon contract", () => {
+    const env = buildDaemonEnv(baseInputs, {});
+    const config = readDaemonConfig(env);
+    expect(config).toEqual({
+      dataDir: "/home/u/.stigmer/data",
+      logDir: "/home/u/.stigmer/data/logs",
+      temporalManaged: true,
+      temporalAddress: "127.0.0.1:7233",
+      serverOnly: false,
+      noWeb: false,
+      serverBin: "/usr/local/bin/stigmer-server",
+      runner: { nodeBin: "/usr/bin/node", entryPath: "/repo/runner/dist/main.js", appDir: "/repo/runner" },
+      cursorApiKey: undefined,
+      activityRouting: undefined,
+    });
+  });
+
+  it("omits runner coordinates in server-only mode", () => {
+    const env = buildDaemonEnv({ ...baseInputs, serverOnly: true }, {});
+    const config = readDaemonConfig(env);
+    expect(config.serverOnly).toBe(true);
+    expect(config.runner).toBeUndefined();
+  });
+
+  it("passes CURSOR_API_KEY and activity routing through from the base env", () => {
+    const env = buildDaemonEnv(baseInputs, { CURSOR_API_KEY: "ck", STIGMER_ACTIVITY_ROUTING: "session" });
+    const config = readDaemonConfig(env);
+    expect(config.cursorApiKey).toBe("ck");
+    expect(config.activityRouting).toBe("session");
+  });
+
+  it("requires the data dir and server binary", () => {
+    expect(() => readDaemonConfig({})).toThrow(/STIGMER_DATA_DIR/);
+    expect(() => readDaemonConfig({ STIGMER_DATA_DIR: "/x" })).toThrow(/STIGMER_SERVER_BIN/);
+  });
+});