@stigmer/cli 3.14.1 → 3.15.1

package/src/local/artifact.test.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { describe, expect, it } from "vitest";
-import { mapReleaseArch, mapReleaseOs, sha256Hex } from "./artifact.js";
+import { mapReleaseArch, mapReleaseOs, parseShasum, sha256Hex } from "./artifact.js";
 
 describe("mapReleaseOs", () => {
   it("maps Node platforms to release OS tokens", () => {
@@ -26,3 +26,29 @@ describe("sha256Hex", () => {
     expect(sha256Hex(bytes)).toBe(expected);
   });
 });
+
+// A release-wide `sha256sum` file is matched by filename, never by position,
+// and the binary-mode "*" prefix is not part of a name.
+describe("parseShasum", () => {
+  const A = "a".repeat(64);
+  const B = "b".repeat(64);
+
+  it("returns the digest on the line naming the file, wherever the line is", () => {
+    const file = `${A}  first.tar.gz\n${B}  second.tar.gz\n`;
+    expect(parseShasum(file, "second.tar.gz")).toBe(B);
+    expect(parseShasum(file, "first.tar.gz")).toBe(A);
+  });
+
+  it("returns an empty string when no line names the file", () => {
+    expect(parseShasum(`${A}  first.tar.gz\n`, "missing.tar.gz")).toBe("");
+    expect(parseShasum("", "missing.tar.gz")).toBe("");
+  });
+
+  it("accepts sha256sum's binary-mode marker and normalises the hex to lowercase", () => {
+    expect(parseShasum(`${A.toUpperCase()} *first.tar.gz\n`, "first.tar.gz")).toBe(A);
+  });
+
+  it("ignores blank and malformed lines", () => {
+    expect(parseShasum(`\n\nnot-a-digest\n${B}  x.tar.gz\n`, "x.tar.gz")).toBe(B);
+  });
+});

package/src/local/artifact.ts

@@ -2,11 +2,12 @@
 // `.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).
+// The Temporal CLI downloader (`temporal/download.ts`) builds on this, and any
+// future release-binary downloader should too, so the fetch/verify/extract
+// contract lives in exactly one place. (The `stigmer-server` Go binary was its
+// second consumer until the server became an npm artifact.) 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";
@@ -43,9 +44,11 @@ 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.
+   * URL of a `shasum -a 256`-format checksum file covering {@link url}. The
+   * file may list many assets (a release's `checksums.txt`); the line whose
+   * filename is the archive's basename is the one that counts. When set, the
+   * downloaded archive's sha256 is verified against it before extraction and
+   * any mismatch — or a file with no entry for the archive — aborts the install.
    */
   checksumUrl?: string;
   /** Basename of the entry to extract from the archive. */
@@ -69,11 +72,12 @@ export async function fetchTarballBinary(src: TarballBinarySource): Promise<void
   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 archiveName = archiveBasename(src.url);
+    const expected = parseShasum(await fetchText(doFetch, src.checksumUrl, `${src.label} checksum`), archiveName);
     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)"}`,
+        `expected: ${expected || `(no entry for ${archiveName} in ${src.checksumUrl})`}`,
         `actual:   ${actual}`,
         `archive:  ${src.url}`,
       ]);
@@ -121,9 +125,27 @@ async function doFetchOrThrow(doFetch: typeof fetch, url: string, label: string)
   return res;
 }
 
-// `shasum`/`sha256sum` output is "<hex>  <filename>"; take the first token.
-function parseShasum(content: string): string {
-  return (content.trim().split(/\s+/)[0] ?? "").toLowerCase();
+/**
+ * The sha256 a `shasum`/`sha256sum`-format file records for `filename`, lowercase
+ * hex, or "" when the file has no entry for it. Each line is "<hex>  <filename>";
+ * `sha256sum -b` writes the filename with a leading "*" (binary mode), which is
+ * not part of the name. A release-wide file lists every asset, so the match is
+ * by filename, never by position.
+ */
+export function parseShasum(content: string, filename: string): string {
+  for (const line of content.split("\n")) {
+    const [hex, name] = line.trim().split(/\s+/, 2);
+    if (hex === undefined || name === undefined) continue;
+    if (name.replace(/^\*/, "") === filename) return hex.toLowerCase();
+  }
+  return "";
+}
+
+// The archive's basename as the checksum file names it: the last path segment
+// of the URL, with any query string already excluded by URL parsing.
+function archiveBasename(url: string): string {
+  const segments = new URL(url).pathname.split("/");
+  return segments[segments.length - 1] ?? "";
 }
 
 /**

package/src/local/daemon/components.ts

@@ -94,6 +94,7 @@ export function buildComponents(config: DaemonConfig, base: NodeJS.ProcessEnv =
       // The server is `node <entry>` — the runner's launch shape, one child
       // contract for both components.
       resolve: () => ({
+        name: "stigmer-server",
         command: config.server.nodeBin,
         args: [config.server.entryPath],
         env: buildServerEnv(config, base),
@@ -113,6 +114,7 @@ export function buildComponents(config: DaemonConfig, base: NodeJS.ProcessEnv =
     pidFile: join(config.dataDir, RUNNER_PID_FILE),
     critical: false,
     resolve: () => ({
+      name: "runner",
       command: runner.nodeBin,
       args: [runner.entryPath],
       cwd: join(config.dataDir, "workspace"),

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

@@ -35,6 +35,7 @@ describe("NodeProcessHost (real spawn)", () => {
 
     const host = new NodeProcessHost();
     const request: SpawnRequest = {
+      name: "runner",
       command: process.execPath,
       args: [script],
       env: process.env,
@@ -57,6 +58,38 @@ describe("NodeProcessHost (real spawn)", () => {
     await exited;
     expect(handle.hasExited()).toBe(true);
   });
+
+  // The foreground launcher's window into the children: every complete line,
+  // tagged with the component, in order within a stream; a partial trailing
+  // line is delivered at exit; the log file still receives the same bytes.
+  it("mirrors complete lines tagged with the component, flushing the tail at exit", async () => {
+    const dir = tempDir();
+    const script = join(dir, "chatty-child.cjs");
+    writeFileSync(
+      script,
+      // Two writes that split a line across chunks, one stderr line, and a
+      // final line with no newline.
+      `process.stdout.write("first li");\n` +
+        `process.stdout.write("ne\\nsecond line\\n");\n` +
+        `process.stderr.write("a warning\\n");\n` +
+        `process.stdout.write("tail without newline");\n` +
+        `setTimeout(() => process.exit(0), 50);\n`,
+    );
+    const logFile = join(dir, "child.log");
+    const mirrored: string[] = [];
+    const host = new NodeProcessHost({ mirror: (component, line) => mirrored.push(`${component}|${line}`) });
+
+    const handle = host.spawn({ name: "stigmer-server", command: process.execPath, args: [script], env: process.env, logFile });
+    await new Promise<void>((resolve) => handle.onExit(() => resolve()));
+
+    expect(mirrored.filter((l) => l !== "stigmer-server|a warning")).toEqual([
+      "stigmer-server|first line",
+      "stigmer-server|second line",
+      "stigmer-server|tail without newline",
+    ]);
+    expect(mirrored).toContain("stigmer-server|a warning");
+    await expect.poll(() => readFileSync(logFile, "utf8")).toContain("first line\nsecond line\n");
+  });
 });
 
 // ---- Integration 2: the full daemon body, with a fake process host + fake

package/src/local/daemon/host.ts

@@ -7,13 +7,32 @@
 // 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`.
+//
+// An optional mirror receives every complete line a child writes, tagged with
+// the component's name. The foreground launcher (`stigmer up --foreground`)
+// uses it to show the stack's output in the terminal — or in `docker logs` —
+// while the log files keep receiving the same bytes. The detached daemon
+// installs no mirror: its own stdout is already redirected to daemon.log.
 
 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";
 
+/** Receives one complete output line from a child, with the component that wrote it. */
+export type OutputMirror = (component: string, line: string) => void;
+
+export interface NodeProcessHostOptions {
+  mirror?: OutputMirror;
+}
+
 export class NodeProcessHost implements ProcessHost {
+  private readonly mirror: OutputMirror | undefined;
+
+  constructor(options: NodeProcessHostOptions = {}) {
+    this.mirror = options.mirror;
+  }
+
   spawn(request: SpawnRequest): ChildHandle {
     const out = createWriteStream(request.logFile, { flags: "a" });
     const child = spawn(request.command, request.args, {
@@ -31,8 +50,14 @@ export class NodeProcessHost implements ProcessHost {
     // Keep a small rolling tail so a marker split across chunks is still found.
     let tail = "";
     const marker = request.readinessMarker;
+    // One line assembler per stream: a chunk can end mid-line, and the two
+    // streams interleave, so each keeps its own partial line.
+    const mirrorStdout = this.lineMirror(request.name);
+    const mirrorStderr = this.lineMirror(request.name);
+
     child.stdout?.on("data", (chunk: Buffer) => {
       out.write(chunk);
+      mirrorStdout(chunk);
       if (marker !== undefined && !ready) {
         tail = (tail + chunk.toString("utf8")).slice(-Math.max(marker.length * 2, 256));
         if (tail.includes(marker)) {
@@ -41,10 +66,15 @@ export class NodeProcessHost implements ProcessHost {
         }
       }
     });
-    child.stderr?.on("data", (chunk: Buffer) => out.write(chunk));
+    child.stderr?.on("data", (chunk: Buffer) => {
+      out.write(chunk);
+      mirrorStderr(chunk);
+    });
 
     child.on("exit", (code, signal) => {
       exited = true;
+      mirrorStdout(null);
+      mirrorStderr(null);
       out.end();
       exitCb?.({ code, signal });
     });
@@ -70,6 +100,25 @@ export class NodeProcessHost implements ProcessHost {
       },
     };
   }
+
+  // Assemble complete lines from a byte stream and hand each to the mirror. A
+  // `null` chunk flushes the trailing partial line at exit. Without a mirror
+  // this is a no-op closure, so the hot path pays nothing in the detached daemon.
+  private lineMirror(component: string): (chunk: Buffer | null) => void {
+    const mirror = this.mirror;
+    if (mirror === undefined) return () => {};
+    let partial = "";
+    return (chunk) => {
+      if (chunk === null) {
+        if (partial !== "") mirror(component, partial);
+        partial = "";
+        return;
+      }
+      const lines = (partial + chunk.toString("utf8")).split("\n");
+      partial = lines.pop() ?? "";
+      for (const line of lines) mirror(component, line);
+    };
+  }
 }
 
 /** Real wall-clock implementation of Clock. */

package/src/local/daemon/index.ts

@@ -2,9 +2,9 @@
 
 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 { NodeProcessHost, type NodeProcessHostOptions, type OutputMirror, systemClock } from "./host.js";
+export { down, isRunning, type UpForegroundDeps, type UpOptions, up, upForeground } from "./launch.js";
+export { type InternalDaemonDeps, type TemporalControl, runInternalDaemon, waitForShutdownSignal } from "./process.js";
 export {
   HEALTH_CHECK_INTERVAL_MS,
   MAX_RESTARTS,

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

@@ -0,0 +1,136 @@
+// Pins the foreground launcher's contract with the daemon body: the config it
+// hands over is the detached shape's, encoded through the same env contract;
+// the children inherit that built environment; the post-readiness work (the
+// bootstrap, the startup record, the caller's onReady) runs from onStarted;
+// the daemon's exit code is the launcher's. Resolution is driven through the
+// same overrides a container sets (STIGMER_SERVER_DIR, STIGMER_RUNNER_DIR,
+// STIGMER_TEMPORAL_BIN), so nothing is downloaded or installed.
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SERVER_PORT } from "../constants.js";
+import { tcpConnects } from "../net/tcp.js";
+import { loadStartupConfig } from "../state/startup-config.js";
+import { DaemonEnvVar } from "./env.js";
+import { upForeground } from "./launch.js";
+import type { InternalDaemonDeps } from "./process.js";
+
+// The launcher refuses to start beside a stack already serving on the server
+// port — including a developer's own `stigmer up`. Report SKIPPED rather than
+// a false failure in that case.
+const serverPortBusy = await tcpConnects(SERVER_PORT, "127.0.0.1", 300);
+
+function tempDir(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+// A built package in the shape the resolvers accept: package.json + dist/main.js.
+function builtPackage(prefix: string): string {
+  const dir = tempDir(prefix);
+  writeFileSync(join(dir, "package.json"), "{}");
+  mkdirSync(join(dir, "dist"));
+  writeFileSync(join(dir, "dist", "main.js"), "//");
+  return dir;
+}
+
+const TOUCHED = ["STIGMER_SERVER_DIR", "STIGMER_RUNNER_DIR", "STIGMER_TEMPORAL_BIN", "STIGMER_NODE_BIN", "ANTHROPIC_API_KEY"] as const;
+let saved: Record<string, string | undefined>;
+
+beforeEach(() => {
+  saved = {};
+  for (const key of TOUCHED) {
+    saved[key] = process.env[key];
+    delete process.env[key];
+  }
+  process.env.STIGMER_SERVER_DIR = builtPackage("stigmer-fg-server-");
+  process.env.STIGMER_RUNNER_DIR = builtPackage("stigmer-fg-runner-");
+  const temporalBin = join(tempDir("stigmer-fg-temporal-"), "temporal");
+  writeFileSync(temporalBin, "#!/bin/sh\n");
+  process.env.STIGMER_TEMPORAL_BIN = temporalBin;
+});
+
+afterEach(() => {
+  for (const key of TOUCHED) {
+    if (saved[key] === undefined) delete process.env[key];
+    else process.env[key] = saved[key];
+  }
+});
+
+describe.skipIf(serverPortBusy)("upForeground", () => {
+  it("runs the daemon body in-process with the detached shape's config and env, bootstrapping from onStarted", async () => {
+    const home = tempDir("stigmer-fg-home-");
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    const order: string[] = [];
+    let captured: InternalDaemonDeps | null = null;
+
+    const code = await upForeground({ noWeb: true }, home, {
+      runDaemon: async (deps) => {
+        captured = deps;
+        order.push("daemon:started");
+        await deps.onStarted?.();
+        order.push("daemon:waiting");
+        return 0;
+      },
+      bootstrap: async () => {
+        order.push("bootstrap");
+      },
+      onReady: () => {
+        order.push("onReady");
+      },
+      waitForShutdown: () => Promise.resolve(),
+    });
+
+    expect(code).toBe(0);
+    expect(order).toEqual(["daemon:started", "bootstrap", "onReady", "daemon:waiting"]);
+
+    const deps = captured as unknown as InternalDaemonDeps;
+    // The config is the env contract read back — the detached daemon's view.
+    expect(deps.config?.dataDir).toBe(join(home, ".stigmer", "data"));
+    expect(deps.config?.temporalManaged).toBe(true);
+    expect(deps.config?.noWeb).toBe(true);
+    expect(deps.config?.server.entryPath).toBe(join(process.env.STIGMER_SERVER_DIR!, "dist", "main.js"));
+    expect(deps.config?.runner?.entryPath).toBe(join(process.env.STIGMER_RUNNER_DIR!, "dist", "main.js"));
+    expect(deps.config?.anthropicApiKey).toBe("sk-test");
+    // The children inherit the built environment, contract variables included.
+    expect(deps.env?.[DaemonEnvVar.DataDir]).toBe(join(home, ".stigmer", "data"));
+    expect(deps.env?.[DaemonEnvVar.ServerEntry]).toBe(deps.config?.server.entryPath);
+    // The startup record names this process as the daemon.
+    expect(loadStartupConfig(join(home, ".stigmer", "data"))?.stigmer_server_pid).toBe(process.pid);
+  });
+
+  it("propagates the daemon's failure exit code without bootstrapping", async () => {
+    const home = tempDir("stigmer-fg-home-");
+    const bootstrap = vi.fn(async () => {});
+
+    const code = await upForeground({}, home, {
+      // A critical component failed to start: the body returns 1 before onStarted.
+      runDaemon: async () => 1,
+      bootstrap,
+      waitForShutdown: () => Promise.resolve(),
+    });
+
+    expect(code).toBe(1);
+    expect(bootstrap).not.toHaveBeenCalled();
+    expect(loadStartupConfig(join(home, ".stigmer", "data"))).toBeNull();
+  });
+
+  it("omits the runner from the contract in server-only mode", async () => {
+    const home = tempDir("stigmer-fg-home-");
+    let captured: InternalDaemonDeps | null = null;
+
+    await upForeground({ serverOnly: true }, home, {
+      runDaemon: async (deps) => {
+        captured = deps;
+        return 0;
+      },
+      bootstrap: async () => {},
+      waitForShutdown: () => Promise.resolve(),
+    });
+
+    const deps = captured as unknown as InternalDaemonDeps;
+    expect(deps.config?.serverOnly).toBe(true);
+    expect(deps.config?.runner).toBeUndefined();
+  });
+});

package/src/local/daemon/launch.ts

@@ -1,10 +1,14 @@
 // Foreground control of the daemon: `up` (spawn + verify + wait-ready),
-// `down` (signal + wait + safety-net cleanup), and a liveness check.
+// `upForeground` (run the daemon body right here until a signal), `down`
+// (signal + wait + safety-net cleanup), and a liveness check.
 //
-// `up` resolves every heavy dependency in the foreground (Temporal binary,
+// Both `up` shapes resolve every heavy dependency first (Temporal binary,
 // server launch, 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.
+// anything long-lived starts. The detached shape then re-execs this same CLI
+// as the hidden `internal-daemon` and waits until the server's gRPC port
+// answers; the foreground shape calls the same daemon body in-process, which
+// is what a container entrypoint, a systemd unit or a tmux pane wants: one
+// process to watch, signals delivered to it, the stack's output on its stdio.
 
 import { spawn } from "node:child_process";
 import { mkdirSync, openSync } from "node:fs";
@@ -18,7 +22,7 @@ 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 { findProcessByPort, isOtherLiveProcess, isProcessAlive, killProcess } from "../state/proc.js";
 import { type StartupConfig, removeStartupConfig, saveStartupConfig } from "../state/startup-config.js";
 import { rotateLogs } from "../state/log-rotation.js";
 import { resolveApiKey, resolveProvider } from "../llm-config.js";
@@ -26,7 +30,9 @@ import { resolveOperatorIdentity } from "../operator-config.js";
 import { ensureRunner } from "../runtime/runner.js";
 import { ensureServer } from "../runtime/server.js";
 import { TemporalManager } from "../temporal/manager.js";
-import { buildDaemonEnv, type DaemonEnvInputs } from "./env.js";
+import { buildDaemonEnv, type DaemonEnvInputs, readDaemonConfig } from "./env.js";
+import { NodeProcessHost, type OutputMirror } from "./host.js";
+import { type InternalDaemonDeps, runInternalDaemon, waitForShutdownSignal } from "./process.js";
 
 /** How long `up` waits for the server's gRPC port after spawning the daemon. */
 const READY_TIMEOUT_MS = 60_000;
@@ -41,8 +47,94 @@ export interface UpOptions {
   noWeb?: boolean;
 }
 
+/** Everything both `up` shapes need once the heavy resolution is done. */
+interface PreparedLaunch {
+  data: string;
+  logs: string;
+  temporalAddress: string;
+  env: NodeJS.ProcessEnv;
+}
+
 /** 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, logs, temporalAddress, env } = await prepareLaunch(options, home);
+
+  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, temporalAddress, daemonPid, options));
+}
+
+/** Seams of the foreground launcher, injectable for tests. */
+export interface UpForegroundDeps {
+  /** The daemon body (default: the real one). */
+  runDaemon?: (deps: InternalDaemonDeps) => Promise<number>;
+  /** Resolves when the stack should shut down (default: the first SIGTERM/SIGINT). */
+  waitForShutdown?: () => Promise<void>;
+  /** Post-readiness bootstrap (default: the best-effort seedpack apply). */
+  bootstrap?: (home: string) => Promise<void>;
+  /** Receives each line the server and runner write (default: a `[component]`-prefixed stdout mirror). */
+  mirror?: OutputMirror;
+  /** Invoked once the stack is serving and seeded — the moment a detached `up` would have returned. */
+  onReady?: () => void | Promise<void>;
+}
+
+/**
+ * Start the local stack in THIS process and run it until shutdown is requested.
+ * Resolves to the daemon's exit code: 0 after a clean shutdown, 1 when a
+ * critical component failed to start (the daemon has already logged why).
+ *
+ * The same resolution, the same daemon body and the same on-disk state as
+ * `up`, so `stigmer status` and `stigmer down` from another shell see an
+ * ordinary daemon whose PID happens to be ours. The children receive the very
+ * environment a detached daemon would have inherited, and what a detached `up`
+ * does once the server answers — the seedpack, the startup record — happens in
+ * `onStarted`, at the same point in the stack's life.
+ */
+export async function upForeground(
+  options: UpOptions = {},
+  home: string = homedir(),
+  deps: UpForegroundDeps = {},
+): Promise<number> {
+  const { data, logs, temporalAddress, env } = await prepareLaunch(options, home);
+  const runDaemon = deps.runDaemon ?? runInternalDaemon;
+  const bootstrap = deps.bootstrap ?? applySeedpackBestEffort;
+
+  return runDaemon({
+    config: readDaemonConfig(env),
+    env,
+    host: new NodeProcessHost({ mirror: deps.mirror ?? mirrorToStdout }),
+    waitForShutdown: deps.waitForShutdown ?? waitForShutdownSignal,
+    onStarted: async () => {
+      await bootstrap(home);
+      saveStartupConfig(data, buildStartupConfig(data, logs, temporalAddress, process.pid, options));
+      await deps.onReady?.();
+    },
+  });
+}
+
+// The default foreground mirror: one line per child line, tagged with the
+// component, on stdout — a terminal in a tmux pane, `docker logs` in a
+// container. The log files keep receiving the same bytes untagged.
+const mirrorToStdout: OutputMirror = (component, line) => {
+  process.stdout.write(`[${component}] ${line}\n`);
+};
+
+// The part of `up` that is the same whether the daemon then runs detached or
+// right here: refuse a second stack, prepare the state dirs, resolve every
+// heavy dependency, and encode the launcher→daemon contract.
+async function prepareLaunch(options: UpOptions, home: string): Promise<PreparedLaunch> {
   const data = dataDir(home);
   const logs = logDir(home);
 
@@ -84,21 +176,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
     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, daemonPid, options));
+  return { data, logs, temporalAddress: temporal.address, env };
 }
 
 /**
@@ -143,7 +221,7 @@ export async function down(home: string = homedir()): Promise<boolean> {
   let pid = readPidFile(join(data, DAEMON_PID_FILE));
   if (pid === null) pid = findProcessByPort(SERVER_PORT);
 
-  if (pid === null || !isProcessAlive(pid)) {
+  if (pid === null || !isOtherLiveProcess(pid)) {
     removePidFile(join(data, DAEMON_PID_FILE));
     await stopManagedTemporal(home);
     cleanupOrphans(data);
@@ -173,13 +251,13 @@ export async function down(home: string = homedir()): Promise<boolean> {
   return true;
 }
 
-/** Whether the daemon is running: live PID, else a server-port fallback. */
+/** Whether the daemon is running: a live peer's 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
+    if (isOtherLiveProcess(pid)) return true;
+    removePidFile(join(data, DAEMON_PID_FILE)); // stale (dead, or a previous life of our own PID)
   }
   return tcpConnects(SERVER_PORT, "127.0.0.1", 1000);
 }
@@ -204,13 +282,16 @@ function spawnDaemon(env: NodeJS.ProcessEnv, daemonLog: string): number {
   return child.pid;
 }
 
-// Kill any daemon/server/runner left alive by a previous, improperly-stopped run.
+// Kill any daemon/server/runner left alive by a previous, improperly-stopped
+// run. A recorded PID that is our own is a leftover, never a peer (the fresh
+// PID namespace of a restarted container hands the launcher the PID its last
+// life had) — signalling it would be signalling ourselves.
 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)) {
+    if (isOtherLiveProcess(pid)) {
       log.warn("killing orphaned process from a previous run", { file: name, pid });
       killProcess(pid, "SIGTERM");
     }