@stigmer/cli 3.15.0 → 3.15.2-dev.20260913223433

package/src/local/state/state.test.ts

@@ -6,7 +6,7 @@ import { type HealthState, loadHealthState, writeHealthState } from "./health-st
 import { acquireLock } from "./lock.js";
 import { cleanupOldLogs, rotateLogs } from "./log-rotation.js";
 import { readPidFile, removePidFile, writePidFile } from "./pidfile.js";
-import { isProcessAlive } from "./proc.js";
+import { isOtherLiveProcess, isProcessAlive } from "./proc.js";
 import { loadStartupConfig, removeStartupConfig, saveStartupConfig, type StartupConfig } from "./startup-config.js";
 
 function tempDir(prefix: string): string {
@@ -46,6 +46,17 @@ describe("isProcessAlive", () => {
   it("is true for the current process and false for a dead PID", () => {
     expect(isProcessAlive(process.pid)).toBe(true);
     expect(isProcessAlive(DEAD_PID)).toBe(false);
+  });
+});
+
+describe("isOtherLiveProcess", () => {
+  // A recorded PID equal to our own is a leftover from a previous life of this
+  // PID (a restarted container's fresh PID namespace, a laptop after reboot),
+  // never a live peer — the distinction every stale-state reader needs.
+  it("is false for the current process, true for its parent, false for a dead PID", () => {
+    expect(isOtherLiveProcess(process.pid)).toBe(false);
+    expect(isOtherLiveProcess(process.ppid)).toBe(true);
+    expect(isOtherLiveProcess(DEAD_PID)).toBe(false);
     expect(isProcessAlive(0)).toBe(false);
     expect(isProcessAlive(-1)).toBe(false);
   });
@@ -176,6 +187,19 @@ describe("lock", () => {
     expect(readFileSync(path, "utf8").trim()).toBe(String(process.pid));
   });
 
+  // The container case: after an unclean stop the lock file on the volume names
+  // the PID the daemon had last time — and a fresh PID namespace hands the
+  // restarted daemon that same PID. We are not holding a lock we are trying to
+  // acquire, so an owner equal to ourselves is stale by construction.
+  it("reclaims a lock whose recorded owner is this very process (a previous life of the PID)", () => {
+    const path = join(tempDir("stigmer-lock-"), "temporal.lock");
+    writeFileSync(path, `${process.pid}\n`);
+    const lock = acquireLock(path);
+    expect(lock).not.toBeNull();
+    lock?.release();
+    expect(acquireLock(path)).not.toBeNull();
+  });
+
   it("release is idempotent and only removes our own lock", () => {
     const path = join(tempDir("stigmer-lock-"), "temporal.lock");
     const lock = acquireLock(path);

package/src/local/temporal/download.test.ts

@@ -1,9 +1,16 @@
-import { mkdtempSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { gzipSync } from "fflate";
 import { describe, expect, it } from "vitest";
-import { downloadTemporalCli, extractTarEntry } from "./download.js";
+import {
+  TEMPORAL_CHECKSUMS_FILE,
+  downloadTemporalCli,
+  extractTarEntry,
+  temporalArchiveName,
+  temporalReleaseAssetUrl,
+} from "./download.js";
 
 // Build a minimal ustar archive containing a single regular-file entry. Only
 // the fields the reader uses (name, octal size, type flag) are populated.
@@ -40,24 +47,85 @@ describe("extractTarEntry", () => {
   });
 });
 
-describe("downloadTemporalCli", () => {
-  it("downloads, gunzips, untars, and writes an executable binary", async () => {
-    const payload = Buffer.from("the-temporal-binary");
-    const gz = gzipSync(new Uint8Array(makeTar("temporal", payload)));
-    const fetchImpl = (async () => ({
+// A release as GitHub serves it: the archive for the requested platform plus a
+// release-wide checksums.txt listing every asset. `fetchImpl` routes by URL so
+// the checksum arm is exercised against a realistic multi-line file.
+function release(version: string, archives: Record<string, Buffer>, checksums: string): typeof fetch {
+  return (async (input: string | URL | Request) => {
+    const url = String(input);
+    const name = url.slice(url.lastIndexOf("/") + 1);
+    if (name === TEMPORAL_CHECKSUMS_FILE) {
+      return { ok: true, status: 200, text: async () => checksums } as unknown as Response;
+    }
+    const gz = archives[name];
+    if (gz === undefined) return { ok: false, status: 404, arrayBuffer: async () => new ArrayBuffer(0) } as unknown as Response;
+    return {
       ok: true,
       status: 200,
       arrayBuffer: async () => gz.buffer.slice(gz.byteOffset, gz.byteOffset + gz.byteLength),
-    })) as unknown as typeof fetch;
+    } as unknown as Response;
+  }) as unknown as typeof fetch;
+}
+
+function archiveFor(payload: Buffer): Buffer {
+  return Buffer.from(gzipSync(new Uint8Array(makeTar("temporal", payload))));
+}
+
+function sha256(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+describe("downloadTemporalCli", () => {
+  const linuxArm = temporalArchiveName("1.5.1", "linux", "arm64");
+  const linuxAmd = temporalArchiveName("1.5.1", "linux", "x64");
+
+  it("names the release assets the way Temporal publishes them", () => {
+    expect(linuxArm).toBe("temporal_cli_1.5.1_linux_arm64.tar.gz");
+    expect(linuxAmd).toBe("temporal_cli_1.5.1_linux_amd64.tar.gz");
+    expect(temporalArchiveName("1.5.1", "darwin", "arm64")).toBe("temporal_cli_1.5.1_darwin_arm64.tar.gz");
+    expect(temporalReleaseAssetUrl("1.5.1", TEMPORAL_CHECKSUMS_FILE)).toBe(
+      "https://github.com/temporalio/cli/releases/download/v1.5.1/checksums.txt",
+    );
+  });
+
+  it("downloads, verifies against the matching checksums.txt line, gunzips, untars, and writes the binary", async () => {
+    const arm = archiveFor(Buffer.from("the-arm64-binary"));
+    const amd = archiveFor(Buffer.from("the-amd64-binary"));
+    // amd64 listed FIRST: a first-token parser would verify arm64 against it.
+    const checksums = `${sha256(amd)}  ${linuxAmd}\n${sha256(arm)}  ${linuxArm}\n`;
+    const fetchImpl = release("1.5.1", { [linuxArm]: arm, [linuxAmd]: amd }, checksums);
 
     const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "bin", "temporal");
-    await downloadTemporalCli({ version: "1.5.1", binPath, fetchImpl });
+    await downloadTemporalCli({ version: "1.5.1", binPath, platform: "linux", arch: "arm64", fetchImpl });
+
+    expect(readFileSync(binPath, "utf8")).toBe("the-arm64-binary");
+  });
 
-    expect(readFileSync(binPath, "utf8")).toBe("the-temporal-binary");
+  it("refuses an archive whose digest does not match its checksums.txt line", async () => {
+    const arm = archiveFor(Buffer.from("tampered"));
+    const checksums = `${"0".repeat(64)}  ${linuxArm}\n`;
+    const fetchImpl = release("1.5.1", { [linuxArm]: arm }, checksums);
+
+    const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "temporal");
+    await expect(
+      downloadTemporalCli({ version: "1.5.1", binPath, platform: "linux", arch: "arm64", fetchImpl }),
+    ).rejects.toThrow(/checksum mismatch/);
+    expect(existsSync(binPath)).toBe(false);
+  });
+
+  it("refuses an archive the checksums.txt has no entry for", async () => {
+    const arm = archiveFor(Buffer.from("unlisted"));
+    const checksums = `${sha256(arm)}  some_other_asset.tar.gz\n`;
+    const fetchImpl = release("1.5.1", { [linuxArm]: arm }, checksums);
+
+    const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "temporal");
+    await expect(
+      downloadTemporalCli({ version: "1.5.1", binPath, platform: "linux", arch: "arm64", fetchImpl }),
+    ).rejects.toThrow(/checksum mismatch/);
   });
 
   it("fails clearly on a non-OK response", async () => {
-    const fetchImpl = (async () => ({ ok: false, status: 404, arrayBuffer: async () => new ArrayBuffer(0) })) as unknown as typeof fetch;
+    const fetchImpl = release("9.9.9", {}, "");
     const binPath = join(mkdtempSync(join(tmpdir(), "stigmer-temporal-")), "temporal");
     await expect(downloadTemporalCli({ version: "9.9.9", binPath, fetchImpl })).rejects.toThrow(/HTTP 404/);
   });

package/src/local/temporal/download.ts

@@ -2,12 +2,14 @@
 //
 // `up` needs a `temporal` binary and the upstream release is a small, public,
 // stable artifact. The fetch/gunzip/untar/write mechanics are shared with the
-// stigmer-server downloader in `../artifact.ts`; this module only owns Temporal's
-// asset-naming and the default version.
+// other release downloaders in `../artifact.ts`; this module only owns
+// Temporal's asset-naming and the default version.
 //
-// Parity note: like the Go CLI, this does not verify a checksum (the stigmer
-// -server downloader does, per DD-003). A checksum-hardening follow-up is filed;
-// until then the integrity guarantee is HTTPS + GitHub's release immutability.
+// Every download is verified against the release's `checksums.txt` (the
+// `sha256sum` file Temporal publishes beside its archives) before the binary is
+// written: the integrity guarantee is the published digest, not merely HTTPS
+// plus GitHub's release immutability. The same code path stages the binary the
+// all-in-one image bakes, so one pin and one verification serve every channel.
 
 import { existsSync } from "node:fs";
 import { fetchTarballBinary, mapReleaseArch, mapReleaseOs } from "../artifact.js";
@@ -19,6 +21,9 @@ export { extractTarEntry } from "../artifact.js";
 /** Default Temporal CLI version (matches the Go CLI's `DefaultTemporalVersion`). */
 export const DEFAULT_TEMPORAL_VERSION = "1.5.1";
 
+/** The release's `sha256sum`-format digest file, one line per published asset. */
+export const TEMPORAL_CHECKSUMS_FILE = "checksums.txt";
+
 export interface TemporalDownloadTarget {
   /** Temporal CLI version, e.g. "1.5.1". */
   version: string;
@@ -32,15 +37,23 @@ export interface TemporalDownloadTarget {
   fetchImpl?: typeof fetch;
 }
 
-/** Download and install the Temporal CLI binary to `binPath`. */
+/** The release asset name for a version on a platform, as Temporal publishes it. */
+export function temporalArchiveName(version: string, platform: NodeJS.Platform, arch: string): string {
+  return `temporal_cli_${version}_${mapReleaseOs(platform)}_${mapReleaseArch(arch)}.tar.gz`;
+}
+
+/** The GitHub release download URL for one asset of a version. */
+export function temporalReleaseAssetUrl(version: string, asset: string): string {
+  return `https://github.com/temporalio/cli/releases/download/v${version}/${asset}`;
+}
+
+/** Download, verify and install the Temporal CLI binary to `binPath`. */
 export async function downloadTemporalCli(target: TemporalDownloadTarget): Promise<void> {
-  const goos = mapReleaseOs(target.platform ?? process.platform);
-  const goarch = mapReleaseArch(target.arch ?? process.arch);
-  const archive = `temporal_cli_${target.version}_${goos}_${goarch}.tar.gz`;
-  const url = `https://github.com/temporalio/cli/releases/download/v${target.version}/${archive}`;
+  const archive = temporalArchiveName(target.version, target.platform ?? process.platform, target.arch ?? process.arch);
 
   await fetchTarballBinary({
-    url,
+    url: temporalReleaseAssetUrl(target.version, archive),
+    checksumUrl: temporalReleaseAssetUrl(target.version, TEMPORAL_CHECKSUMS_FILE),
     entryName: "temporal",
     binPath: target.binPath,
     label: "Temporal CLI",

package/src/local/temporal/index.ts

@@ -1,6 +1,14 @@
 // Public surface of the Temporal subsystem.
 
-export { DEFAULT_TEMPORAL_VERSION, downloadTemporalCli, extractTarEntry, isTemporalInstalled } from "./download.js";
-export { isLikelyTemporal, processCommandLine } from "./inspect.js";
-export { TemporalManager, type TemporalManagerOptions } from "./manager.js";
+export {
+  DEFAULT_TEMPORAL_VERSION,
+  TEMPORAL_CHECKSUMS_FILE,
+  downloadTemporalCli,
+  extractTarEntry,
+  isTemporalInstalled,
+  temporalArchiveName,
+  temporalReleaseAssetUrl,
+} from "./download.js";
+export { isLikelyTemporal, processCommandLine, type ProcessInspectOptions } from "./inspect.js";
+export { TEMPORAL_BIN_ENV, TemporalManager, type TemporalManagerOptions } from "./manager.js";
 export { type SupervisedTarget, type SupervisorOptions, TemporalSupervisor } from "./supervisor.js";

package/src/local/temporal/inspect.test.ts

@@ -0,0 +1,83 @@
+// Pins the process-identity reader: the kernel's /proc answer comes first, `ps`
+// is the fallback, and neither's absence is mistaken for "not Temporal" when the
+// other can answer. The /proc arm is what keeps a minimal container (no `ps`)
+// from restarting a healthy Temporal every supervisor tick.
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { isLikelyTemporal, processCommandLine } from "./inspect.js";
+
+function procFixture(entries: Record<number, string[] | "">): string {
+  const root = mkdtempSync(join(tmpdir(), "stigmer-proc-"));
+  for (const [pid, argv] of Object.entries(entries)) {
+    mkdirSync(join(root, pid));
+    // /proc/<pid>/cmdline: argv joined by NUL, NUL-terminated; empty for a zombie.
+    writeFileSync(join(root, pid, "cmdline"), argv === "" ? "" : `${argv.join("\0")}\0`);
+  }
+  return root;
+}
+
+// Hide `ps` so the fallback cannot answer; tests that need it restore PATH.
+let savedPath: string | undefined;
+beforeEach(() => {
+  savedPath = process.env.PATH;
+});
+afterEach(() => {
+  if (savedPath === undefined) delete process.env.PATH;
+  else process.env.PATH = savedPath;
+});
+
+describe("processCommandLine", () => {
+  it("reads argv from <procRoot>/<pid>/cmdline, joining the NUL-separated arguments", () => {
+    const root = procFixture({ 42: ["/opt/stigmer/bin/temporal", "server", "start-dev", "--port", "7233"] });
+    process.env.PATH = "";
+    expect(processCommandLine(42, { procRoot: root })).toBe("/opt/stigmer/bin/temporal server start-dev --port 7233");
+  });
+
+  it("falls back to ps when the pid has no cmdline entry", () => {
+    const root = procFixture({});
+    // Our own process is the one PID whose command line `ps` can always report.
+    const line = processCommandLine(process.pid, { procRoot: root });
+    expect(line).not.toBeNull();
+    expect(line).toMatch(/node|vitest/);
+  });
+
+  it("treats an empty cmdline (a zombie) as unreadable and falls back to ps", () => {
+    const root = procFixture({ [process.pid]: "" });
+    expect(processCommandLine(process.pid, { procRoot: root })).toMatch(/node|vitest/);
+  });
+
+  it("returns null when neither /proc nor ps can answer", () => {
+    process.env.PATH = "";
+    expect(processCommandLine(process.pid, { procRoot: null })).toBeNull();
+  });
+});
+
+describe("isLikelyTemporal", () => {
+  it("recognises the managed dev server by its binary path", () => {
+    const root = procFixture({ 7: ["/home/u/.stigmer/bin/temporal", "server", "start-dev"] });
+    process.env.PATH = "";
+    expect(isLikelyTemporal(7, "/home/u/.stigmer/bin/temporal", { procRoot: root })).toBe(true);
+  });
+
+  it("recognises a temporal server started from another path by its subcommand", () => {
+    const root = procFixture({ 8: ["/usr/local/bin/temporal", "server", "start-dev"] });
+    process.env.PATH = "";
+    expect(isLikelyTemporal(8, "/elsewhere/temporal", { procRoot: root })).toBe(true);
+  });
+
+  it("rejects an unrelated process that reused the pid", () => {
+    const root = procFixture({ 9: ["/usr/bin/node", "/app/main.js"] });
+    process.env.PATH = "";
+    expect(isLikelyTemporal(9, "/home/u/.stigmer/bin/temporal", { procRoot: root })).toBe(false);
+  });
+
+  // The defect the /proc arm fixes: with `ps` gone and no /proc reader, a live
+  // Temporal read as "not Temporal" and the supervisor restarted it forever.
+  it("is false, not an exception, when no reader can answer", () => {
+    process.env.PATH = "";
+    expect(isLikelyTemporal(process.pid, "/x/temporal", { procRoot: null })).toBe(false);
+  });
+});

package/src/local/temporal/inspect.ts

@@ -3,30 +3,78 @@
 // A PID file can outlive the process it named; the OS may then assign that PID
 // to something unrelated. Before trusting a PID as "our Temporal", we confirm
 // the live process's command line actually looks like the Temporal dev server.
-// POSIX-only (uses `ps`); returns false on any uncertainty.
+//
+// Two readers, in order. On Linux the kernel publishes every process's command
+// line at /proc/<pid>/cmdline (NUL-separated argv), which needs no external
+// program — the reader that works inside a minimal container. Everywhere else
+// (and on a Linux where /proc is unreadable) we shell out to `ps`, the
+// POSIX-portable answer. Returns null on any uncertainty; callers treat null
+// as "not Temporal", which is the safe direction for a PID-reuse guard.
+//
+// Why the /proc reader exists: `node:22-slim` and its kin ship no `ps`. With
+// `ps` as the only reader, every liveness probe answered "not Temporal", the
+// supervisor restarted a healthy dev server every tick, and each restart spawned
+// a second process that failed to bind while the first kept the port. A
+// dependency on a userland tool is the wrong shape for a liveness check that
+// the kernel can answer directly.
 
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 
-/** Full command line of a process via `ps`, or null if it cannot be read. */
-export function processCommandLine(pid: number): string | null {
-  try {
-    return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-  } catch {
-    return null;
+/** Where the kernel publishes process metadata on Linux; null where it does not. */
+const DEFAULT_PROC_ROOT: string | null = process.platform === "linux" ? "/proc" : null;
+
+export interface ProcessInspectOptions {
+  /**
+   * Root of a procfs tree to read `<pid>/cmdline` from. Defaults to `/proc` on
+   * Linux and to none elsewhere; tests point it at a fixture directory.
+   */
+  procRoot?: string | null;
+}
+
+/** Full command line of a process, or null if it cannot be read. */
+export function processCommandLine(pid: number, options: ProcessInspectOptions = {}): string | null {
+  const procRoot = options.procRoot === undefined ? DEFAULT_PROC_ROOT : options.procRoot;
+  if (procRoot !== null) {
+    const fromProc = readProcCmdline(procRoot, pid);
+    if (fromProc !== null) return fromProc;
   }
+  return psCommandLine(pid);
 }
 
 /**
  * Heuristically confirm that `pid` is the Temporal server we manage: its command
  * line mentions "temporal" and either our binary path or a "server" subcommand.
  */
-export function isLikelyTemporal(pid: number, binPath: string): boolean {
-  const cmd = processCommandLine(pid);
+export function isLikelyTemporal(pid: number, binPath: string, options: ProcessInspectOptions = {}): boolean {
+  const cmd = processCommandLine(pid, options);
   if (cmd === null) return false;
   const lower = cmd.toLowerCase();
   if (!lower.includes("temporal")) return false;
   return cmd.includes(binPath) || lower.includes("server");
 }
+
+// /proc/<pid>/cmdline is argv joined by NUL bytes (with a trailing NUL). An
+// empty file means a zombie or a kernel thread — nothing we can name, so null
+// lets the caller fall through to `ps`.
+function readProcCmdline(procRoot: string, pid: number): string | null {
+  try {
+    const raw = readFileSync(join(procRoot, String(pid), "cmdline"), "utf8");
+    const argv = raw.split("\0").filter((arg) => arg !== "");
+    return argv.length === 0 ? null : argv.join(" ");
+  } catch {
+    return null;
+  }
+}
+
+function psCommandLine(pid: number): string | null {
+  try {
+    return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}

package/src/local/temporal/manager.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
@@ -28,4 +28,37 @@ describe("TemporalManager", () => {
     const manager = TemporalManager.forHome(tempHome());
     expect(await manager.isRunning()).toBe(false);
   });
+
+  // A stale PID file naming THIS process (the restarted container's fresh PID
+  // namespace reused it) can never be a running Temporal.
+  it("reports not-running when the PID file names the current process", async () => {
+    const home = tempHome();
+    writePidFile(temporalPidFile(home), process.pid);
+    expect(await TemporalManager.forHome(home).isRunning()).toBe(false);
+  });
+
+  describe("STIGMER_TEMPORAL_BIN", () => {
+    it("relocates only the binary; data, log, PID and lock stay under the home", async () => {
+      const home = tempHome();
+      const binPath = join(tempHome(), "opt", "temporal");
+      mkdirSync(join(binPath, ".."), { recursive: true });
+      writeFileSync(binPath, "#!/bin/sh\n");
+
+      const manager = TemporalManager.forHome(home, { STIGMER_TEMPORAL_BIN: binPath });
+      expect(manager.binPath).toBe(binPath);
+
+      // Nothing to download: the pre-installed binary is what ensureInstalled checks for.
+      await manager.ensureInstalled();
+      expect(existsSync(join(home, ".stigmer", "bin", "temporal"))).toBe(false);
+      // State still lives in the home layout.
+      writePidFile(temporalPidFile(home), 5151);
+      expect(manager.getPid()).toBe(5151);
+    });
+
+    it("is ignored when empty, keeping the ~/.stigmer/bin default", () => {
+      const home = tempHome();
+      const manager = TemporalManager.forHome(home, { STIGMER_TEMPORAL_BIN: "" });
+      expect(manager.binPath).toBe(join(home, ".stigmer", "bin", "temporal"));
+    });
+  });
 });

package/src/local/temporal/manager.ts

@@ -19,7 +19,7 @@ import { binDir, logDir, temporalDataDir, temporalLockFile, temporalPidFile } fr
 import { TEMPORAL_PORT, TEMPORAL_UI_PORT } from "../constants.js";
 import { type FileLock, acquireLock } from "../state/lock.js";
 import { readPidFile, removePidFile, writePidFile } from "../state/pidfile.js";
-import { findProcessByPort, isProcessAlive, killProcessGroup } from "../state/proc.js";
+import { findProcessByPort, isOtherLiveProcess, killProcessGroup } from "../state/proc.js";
 import { DEFAULT_TEMPORAL_VERSION, downloadTemporalCli, isTemporalInstalled } from "./download.js";
 import { isLikelyTemporal } from "./inspect.js";
 
@@ -27,8 +27,16 @@ const READY_TIMEOUT_MS = 10_000;
 const STOP_POLL_MS = 500;
 const STOP_TIMEOUT_MS = 10_000;
 
+/**
+ * Env var naming a pre-installed `temporal` binary to use instead of the one
+ * the CLI downloads into ~/.stigmer/bin — the STIGMER_NODE_BIN precedent. The
+ * all-in-one image bakes the binary read-only off its data volume and points
+ * here; `ensureInstalled` then has nothing to download.
+ */
+export const TEMPORAL_BIN_ENV = "STIGMER_TEMPORAL_BIN";
+
 export interface TemporalManagerOptions {
-  /** Path to the temporal binary (~/.stigmer/bin/temporal). */
+  /** Path to the temporal binary (~/.stigmer/bin/temporal, or STIGMER_TEMPORAL_BIN). */
   binPath: string;
   /** Temporal dev-server data directory (~/.stigmer/temporal-data). */
   dataDir: string;
@@ -44,7 +52,8 @@ export interface TemporalManagerOptions {
 }
 
 export class TemporalManager {
-  private readonly binPath: string;
+  /** The `temporal` binary this manager runs (downloaded, or pre-installed via STIGMER_TEMPORAL_BIN). */
+  readonly binPath: string;
   private readonly dataDir: string;
   private readonly logFile: string;
   private readonly pidFile: string;
@@ -65,10 +74,15 @@ export class TemporalManager {
     this.uiPort = options.uiPort ?? TEMPORAL_UI_PORT;
   }
 
-  /** Build a manager from the standard ~/.stigmer layout. */
-  static forHome(home: string = homedir()): TemporalManager {
+  /**
+   * Build a manager from the standard ~/.stigmer layout. The binary alone may
+   * be relocated through STIGMER_TEMPORAL_BIN; the dev server's data, log,
+   * PID and lock stay under the home, because they are state, not software.
+   */
+  static forHome(home: string = homedir(), env: NodeJS.ProcessEnv = process.env): TemporalManager {
+    const binOverride = env[TEMPORAL_BIN_ENV];
     return new TemporalManager({
-      binPath: join(binDir(home), "temporal"),
+      binPath: binOverride !== undefined && binOverride !== "" ? binOverride : join(binDir(home), "temporal"),
       dataDir: temporalDataDir(home),
       logFile: join(logDir(home), "temporal.log"),
       pidFile: temporalPidFile(home),
@@ -183,7 +197,7 @@ export class TemporalManager {
   async isRunning(): Promise<boolean> {
     const pid = this.getPid();
     if (pid === null) return false;
-    if (!isProcessAlive(pid)) return false;
+    if (!isOtherLiveProcess(pid)) return false;
     if (!isLikelyTemporal(pid, this.binPath)) return false;
     return this.isPortInUse();
   }
@@ -229,7 +243,7 @@ export class TemporalManager {
   private cleanupStaleProcesses(): void {
     const pid = this.getPid();
     if (pid !== null) {
-      if (!isProcessAlive(pid) || !isLikelyTemporal(pid, this.binPath)) {
+      if (!isOtherLiveProcess(pid) || !isLikelyTemporal(pid, this.binPath)) {
         removePidFile(this.pidFile);
       }
       return;