@stigmer/cli 3.14.1 → 3.15.1

package/src/local/daemon/process.ts

@@ -36,14 +36,35 @@ export interface TemporalControl {
 
 export interface InternalDaemonDeps {
   config?: DaemonConfig;
+  /**
+   * The environment the children inherit (defaults to this process's). The
+   * detached daemon IS the environment the launcher built for it; the
+   * foreground launcher passes that same built environment here so the
+   * children see exactly what they would have seen detached.
+   */
+  env?: NodeJS.ProcessEnv;
   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;
+  /**
+   * Invoked once the stack is up and the monitor is running, and awaited
+   * before the daemon settles into waiting for shutdown. The foreground
+   * launcher does its post-readiness work here (seedpack, the success card);
+   * tests use it to observe "started".
+   */
+  onStarted?: () => void | Promise<void>;
+}
+
+/** Resolve on the first SIGTERM or SIGINT — the daemon's shutdown trigger. */
+export function waitForShutdownSignal(): Promise<void> {
+  return new Promise((resolve) => {
+    const onSignal = (): void => resolve();
+    process.once("SIGTERM", onSignal);
+    process.once("SIGINT", onSignal);
+  });
 }
 
 /** Run the daemon to completion. Returns the process exit code. */
@@ -88,7 +109,13 @@ export async function runInternalDaemon(deps: InternalDaemonDeps): Promise<numbe
   }
 
   // --- Start the server (gated) and runner via the supervisor. ---
-  const supervisor = new ProcessSupervisor(buildComponents(config), { host, clock, healthState, persist, log });
+  const supervisor = new ProcessSupervisor(buildComponents(config, deps.env ?? process.env), {
+    host,
+    clock,
+    healthState,
+    persist,
+    log,
+  });
   const result = await supervisor.startAll();
   if (!result.ok) {
     log.error("critical component failed to start", { component: result.failedCritical });
@@ -127,7 +154,7 @@ export async function runInternalDaemon(deps: InternalDaemonDeps): Promise<numbe
   monitor.unref?.();
 
   log.info("daemon started", { pid: process.pid });
-  deps.onStarted?.();
+  await deps.onStarted?.();
 
   // --- Wait for shutdown, then tear down in reverse order. ---
   await deps.waitForShutdown();

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

@@ -109,7 +109,7 @@ function spec(name: string, opts: { critical?: boolean; marker?: string; gate?:
     name,
     pidFile: join(dir, `${name}.pid`),
     critical: opts.critical ?? false,
-    resolve: () => ({ command: name, args: [], env: {}, logFile: join(dir, `${name}.log`), readinessMarker: opts.marker }),
+    resolve: () => ({ name, command: name, args: [], env: {}, logFile: join(dir, `${name}.log`), readinessMarker: opts.marker }),
     gate: opts.gate,
   };
 }

package/src/local/daemon/types.ts

@@ -14,6 +14,8 @@ export interface ExitInfo {
 
 /** A request to launch one child process. */
 export interface SpawnRequest {
+  /** The component's name (the ComponentSpec's), used to label mirrored output. */
+  name: string;
   command: string;
   args: string[];
   cwd?: string;

package/src/local/paths.ts

@@ -47,11 +47,24 @@ export function binDir(home: string = homedir()): string {
 }
 
 /**
- * Root for on-demand-acquired npm runtimes (~/.stigmer/runtimes). Each release
- * version installs into its own `<version>/` subtree so multiple CLI versions can
- * coexist and a partial install never poisons another version's runner.
+ * Env var that relocates the acquired-runtimes root. The acquirers (server,
+ * runner, seedpack) keep their `<root>/<version>/node_modules/@stigmer/<pkg>`
+ * layout under it, so a root that already holds the packages is used as-is
+ * and nothing is downloaded. The all-in-one image bakes exactly that layout
+ * read-only off its data volume — a `stigmer up` whose first-run acquisitions
+ * already happened — and points here.
  */
-export function runtimesDir(home: string = homedir()): string {
+export const RUNTIMES_DIR_ENV = "STIGMER_RUNTIMES_DIR";
+
+/**
+ * Root for on-demand-acquired npm runtimes (~/.stigmer/runtimes, or
+ * STIGMER_RUNTIMES_DIR). Each release version installs into its own
+ * `<version>/` subtree so multiple CLI versions can coexist and a partial
+ * install never poisons another version's runner.
+ */
+export function runtimesDir(home: string = homedir(), env: NodeJS.ProcessEnv = process.env): string {
+  const override = env[RUNTIMES_DIR_ENV];
+  if (override !== undefined && override !== "") return override;
   return join(configDir(home), "runtimes");
 }
 

package/src/local/runtime/runner.ts

@@ -94,22 +94,26 @@ export function resolveRunner(node: () => string = resolveNode): RunnerResolutio
  * ~/.stigmer/runtimes/<version>/ (idempotent: reuses a prior install) and resolve
  * its `main.js` entry. The version is pinned to the CLI's own version so the
  * runner's protos/SDK stay in lockstep with the control plane.
+ *
+ * Presence beats acquirability (the server acquirer's rule, stated there): an
+ * installed runtime is used whatever its version string; only an install we
+ * would have to perform is refused for a non-release build.
  */
 export function acquireRunner(opts: EnsureRunnerOptions = {}): RunnerResolution {
   const home = opts.home ?? homedir();
   const version = opts.version ?? VERSION;
-  if (!isAcquirableRelease(version)) {
-    throw new CliExitError(`cannot acquire ${SLIM_PACKAGE} for a non-release build (${version})`, ExitCode.General, [
-      "Run from the repo with a built runner, or set STIGMER_RUNNER_DIR.",
-      "On-demand acquisition is only available for published releases.",
-    ]);
-  }
 
   const node = opts.node ?? resolveNode;
   const installDir = join(runtimesDir(home), version);
   const entryPath = join(installDir, "node_modules", "@stigmer", "runner-slim", "main.js");
 
   if (!existsSync(entryPath)) {
+    if (!isAcquirableRelease(version)) {
+      throw new CliExitError(`cannot acquire ${SLIM_PACKAGE} for a non-release build (${version})`, ExitCode.General, [
+        "Run from the repo with a built runner, or set STIGMER_RUNNER_DIR.",
+        "On-demand acquisition is only available for published releases.",
+      ]);
+    }
     log.info(`acquiring ${SLIM_PACKAGE}`, { version, dir: installDir });
     ensureRuntimesRoot(installDir);
     const install = opts.install ?? npmInstallIntoRuntimes;

package/src/local/runtime/runtime.test.ts

@@ -222,4 +222,19 @@ describe("acquireRunner", () => {
       /non-release build/,
     );
   });
+
+  // Presence beats acquirability (the server acquirer's rule; the all-in-one
+  // image bakes a dev-stamped runtime npm never published).
+  it("uses an already-installed runtime even for a non-release (dev) build", () => {
+    const home = tempDir("stigmer-home-");
+    const pkgDir = join(home, ".stigmer", "runtimes", "0.0.0-dev.abc123", "node_modules", "@stigmer", "runner-slim");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "main.js"), "// slim bundle");
+
+    const install = vi.fn();
+    const resolution = acquireRunner({ home, version: "0.0.0-dev.abc123", node: fakeNode, install });
+
+    expect(resolution.entryPath).toBe(join(pkgDir, "main.js"));
+    expect(install).not.toHaveBeenCalled();
+  });
 });

package/src/local/runtime/server.test.ts

@@ -22,6 +22,7 @@ const fakeNode = (): string => "/usr/bin/node";
 const TOUCHED = [
   "STIGMER_SERVER_DIR",
   "STIGMER_NODE_BIN",
+  "STIGMER_RUNTIMES_DIR",
 ] as const;
 let saved: Record<string, string | undefined>;
 
@@ -190,6 +191,42 @@ describe("acquireServer", () => {
     expect(hints).toMatch(/Remove .* and retry/);
   });
 
+  // Presence beats acquirability: the all-in-one image bakes a dev-stamped
+  // runtime npm never published; an installed runtime is usable whatever its
+  // version string, and only an install we would have to perform is refused.
+  it("uses an already-installed runtime even for a non-release (dev) build", () => {
+    const home = tempDir("stigmer-home-");
+    const pkgDir = join(home, ".stigmer", "runtimes", "0.0.0-dev.abc123", "node_modules", "@stigmer", "server-slim");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "main.js"), "// slim bundle");
+
+    const install = vi.fn();
+    const launch = acquireServer({ home, version: "0.0.0-dev.abc123", node: fakeNode, install });
+
+    expect(launch.entryPath).toBe(join(pkgDir, "main.js"));
+    expect(install).not.toHaveBeenCalled();
+  });
+
+  // STIGMER_RUNTIMES_DIR relocates the whole acquired-runtimes root; the
+  // per-version layout under it is unchanged, so a pre-filled root is found
+  // exactly where an on-demand install would have put things.
+  it("reads the runtimes root from STIGMER_RUNTIMES_DIR, keeping the per-version layout", () => {
+    const home = tempDir("stigmer-home-");
+    const root = tempDir("stigmer-runtimes-");
+    process.env.STIGMER_RUNTIMES_DIR = root;
+    const pkgDir = join(root, "0.5.0", "node_modules", "@stigmer", "server-slim");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "main.js"), "// slim bundle");
+
+    const install = vi.fn();
+    const launch = acquireServer({ home, version: "0.5.0", node: fakeNode, install });
+
+    expect(launch.entryPath).toBe(join(pkgDir, "main.js"));
+    expect(launch.appDir).toBe(pkgDir);
+    expect(install).not.toHaveBeenCalled();
+    expect(readFileSync(join(pkgDir, "main.js"), "utf8")).toBe("// slim bundle");
+  });
+
   it("refuses to acquire for a non-release (dev) build, naming the fallback", () => {
     const home = tempDir("stigmer-home-");
     const attempt = (): unknown =>

package/src/local/runtime/server.ts

@@ -97,23 +97,17 @@ export function resolveServerTs(
  * the install root with the runner's package) and resolve its `main.js`
  * entry. The version is pinned to the CLI's own version so the server's
  * protos and behavior stay in lockstep with the CLI and the runner.
+ *
+ * Presence beats acquirability: a runtime that is already installed is used
+ * whatever its version string looks like; only an install we would have to
+ * perform is refused for a non-release build. (The all-in-one image relies on
+ * this: it bakes a dev-stamped runtime that npm never published.)
  */
 export function acquireServer(opts: EnsureServerOptions = {}): ServerLaunch {
   const home = opts.home ?? homedir();
   const version = opts.version ?? VERSION;
-  if (!isAcquirableRelease(version)) {
-    throw new CliExitError(
-      `cannot acquire ${SLIM_PACKAGE} for a non-release build (${version})`,
-      ExitCode.General,
-      [
-        "Run from the repo with a built server (make build-server), or set",
-        "STIGMER_SERVER_DIR to a built server package.",
-        "On-demand acquisition is only available for published releases.",
-      ],
-    );
-  }
 
-  // Probe the Node capability BEFORE the download: a user on an FTS5-less
+  // Probe the Node capability BEFORE any download: a user on an FTS5-less
   // Node must not fetch the full slim artifact only to be rejected after.
   const node = opts.node ?? resolveServerNode;
   const nodeBin = node();
@@ -127,6 +121,17 @@ export function acquireServer(opts: EnsureServerOptions = {}): ServerLaunch {
   );
 
   if (!existsSync(entryPath)) {
+    if (!isAcquirableRelease(version)) {
+      throw new CliExitError(
+        `cannot acquire ${SLIM_PACKAGE} for a non-release build (${version})`,
+        ExitCode.General,
+        [
+          "Run from the repo with a built server (make build-server), or set",
+          "STIGMER_SERVER_DIR to a built server package.",
+          "On-demand acquisition is only available for published releases.",
+        ],
+      );
+    }
     log.info(`acquiring ${SLIM_PACKAGE}`, { version, dir: installDir });
     ensureRuntimesRoot(installDir);
     const install = opts.install ?? npmInstallIntoRuntimes;

package/src/local/seedpack/content.test.ts

@@ -126,6 +126,27 @@ describe("acquireSeedpack", () => {
     expect(classify(err)?.exitCode).toBe(ExitCode.General);
   });
 
+  // Presence beats acquirability (the server acquirer's rule; the all-in-one
+  // image bakes dev-stamped content npm never published).
+  it("uses already-installed content even for a non-release (dev) build", () => {
+    const home = mkdtempSync(join(tmpdir(), "seedpack-home-"));
+    const pkgDir = join(home, ".stigmer", "runtimes", "0.0.0-dev.abc123", "node_modules", "@stigmer", "seedpack");
+    mkdirSync(pkgDir, { recursive: true });
+    writeFileSync(join(pkgDir, "stigmer.yaml"), "kind: Organization\n");
+
+    let installs = 0;
+    const dir = acquireSeedpack({
+      home,
+      version: "0.0.0-dev.abc123",
+      install: () => {
+        installs += 1;
+      },
+    });
+
+    expect(dir).toBe(pkgDir);
+    expect(installs).toBe(0);
+  });
+
   it("installs on demand and is idempotent on the second call", () => {
     const home = mkdtempSync(join(tmpdir(), "seedpack-home-"));
     let installs = 0;

package/src/local/seedpack/content.ts

@@ -36,6 +36,7 @@ import { ExitCode } from "../../errors/exit-codes.js";
 import { log } from "../../logger.js";
 import { VERSION } from "../../version.js";
 import { runtimesDir } from "../paths.js";
+import { isAcquirableRelease } from "../runtime/runtimes-install.js";
 
 const SEEDPACK_PACKAGE = "@stigmer/seedpack";
 
@@ -91,26 +92,30 @@ export function resolveSeedpackContent(
  * ~/.stigmer/runtimes/<version>/ (idempotent) and return its package directory.
  * The version is pinned to the CLI's own version so system content stays in
  * lockstep with the control plane it bootstraps.
+ *
+ * Presence beats acquirability (the server acquirer's rule, stated in
+ * runtime/server.ts): installed content is used whatever its version string;
+ * only an install we would have to perform is refused for a non-release build.
  */
 export function acquireSeedpack(opts: ResolveSeedpackOptions = {}): string {
   const home = opts.home ?? homedir();
   const version = opts.version ?? VERSION;
-  if (!isAcquirableRelease(version)) {
-    throw new CliExitError(
-      `cannot acquire ${SEEDPACK_PACKAGE} for a non-release build (${version})`,
-      ExitCode.General,
-      [
-        "Run from the repo (the seedpack/ tree is used directly in dev).",
-        "On-demand acquisition is only available for published releases.",
-      ],
-    );
-  }
 
   const installDir = join(runtimesDir(home), version);
   const pkgDir = join(installDir, "node_modules", "@stigmer", "seedpack");
   const marker = join(pkgDir, "stigmer.yaml");
 
   if (!existsSync(marker)) {
+    if (!isAcquirableRelease(version)) {
+      throw new CliExitError(
+        `cannot acquire ${SEEDPACK_PACKAGE} for a non-release build (${version})`,
+        ExitCode.General,
+        [
+          "Run from the repo (the seedpack/ tree is used directly in dev).",
+          "On-demand acquisition is only available for published releases.",
+        ],
+      );
+    }
     log.info(`acquiring ${SEEDPACK_PACKAGE}`, { version, dir: installDir });
     mkdirSync(installDir, { recursive: true });
     // A stable package.json root keeps the install deterministic. npm install is
@@ -234,12 +239,6 @@ function toPosix(p: string): string {
   return sep === posix.sep ? p : p.split(sep).join(posix.sep);
 }
 
-// A source build reports "0.0.0-dev" and the dev channel stamps "<v>-dev.<stamp>";
-// neither publishes a matching @stigmer/seedpack, so they are not acquirable.
-function isAcquirableRelease(version: string): boolean {
-  return !version.includes("-dev");
-}
-
 // Walk up from this module to a repo root containing seedpack/stigmer.yaml.
 function repoSeedpackDir(): string | null {
   let dir = dirname(fileURLToPath(import.meta.url));

package/src/local/state/lock.ts

@@ -4,13 +4,16 @@
 // lock and whose contents are the owning PID. Creation uses the "wx" flag
 // (O_CREAT | O_EXCL), which is atomic on POSIX and Windows, so two racing
 // acquirers cannot both win. If the file already exists we read the owner PID:
-// a dead owner means a stale lock we may reclaim; a live owner means the lock
-// is genuinely held. This guards the Temporal dev server against double-start
-// the way the Go CLI's flock does, without a native dependency.
+// a live peer means the lock is genuinely held; a dead owner means a stale
+// lock we may reclaim; an owner PID that is OUR OWN is held only if this
+// process is actually holding it (tracked in-process), otherwise it is a
+// leftover from a previous life of the PID (see isOtherLiveProcess) and stale.
+// This guards the Temporal dev server against double-start the way the Go
+// CLI's flock does, without a native dependency.
 
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { isProcessAlive } from "./proc.js";
+import { isOtherLiveProcess } from "./proc.js";
 
 /** A held lock. Call release() exactly once when done. */
 export interface FileLock {
@@ -18,20 +21,30 @@ export interface FileLock {
   release(): void;
 }
 
+// Lock paths this process currently holds. A lock file naming OUR pid is
+// genuinely held only if it is in here; otherwise it is a leftover from a
+// previous life of the pid (a restarted container, a rebooted laptop) and is
+// reclaimed like any other stale lock.
+const heldInProcess = new Set<string>();
+
 /**
  * Try to acquire the lock at `path`. Returns a FileLock on success, or null if
- * the lock is held by a live process. A lock left behind by a dead process is
- * reclaimed automatically.
+ * the lock is held by a live process (this one included — a second acquire
+ * while we hold it fails). A lock left behind by a dead process, or by a past
+ * process that had our pid, is reclaimed automatically.
  */
 export function acquireLock(path: string): FileLock | null {
   mkdirSync(dirname(path), { recursive: true });
 
+  if (heldInProcess.has(path)) return null; // held right here, by us
+
   if (tryCreate(path)) return makeLock(path);
 
-  // The lock file exists. Reclaim it only if its owner is gone.
+  // The lock file exists. Reclaim it only if its owner is gone, or is our own
+  // pid from a previous life (we just established we are not holding it).
   const owner = readOwner(path);
-  if (owner !== null && isProcessAlive(owner)) {
-    return null; // genuinely held by a live process
+  if (owner !== null && isOtherLiveProcess(owner)) {
+    return null; // genuinely held by a live peer
   }
 
   // Stale (or unreadable) lock: remove and retry exactly once. A failure on the
@@ -63,12 +76,14 @@ function readOwner(path: string): number | null {
 }
 
 function makeLock(path: string): FileLock {
+  heldInProcess.add(path);
   let released = false;
   return {
     path,
     release(): void {
       if (released) return;
       released = true;
+      heldInProcess.delete(path);
       // Only remove the file if we still own it, so we never delete a lock a
       // different process acquired after ours was (somehow) gone.
       if (readOwner(path) === process.pid) rmSync(path, { force: true });

package/src/local/state/proc.ts

@@ -19,6 +19,22 @@ export function isProcessAlive(pid: number): boolean {
   }
 }
 
+/**
+ * Report whether `pid` names a live process OTHER than this one — the question
+ * every stale-state reader (a PID file, a lock file's owner) actually asks.
+ *
+ * A recorded PID equal to our own can never be a live peer: we did not write it
+ * in this life, so it is a leftover from a previous process that happened to
+ * get the same number. That happens deterministically in a container (every
+ * start is a fresh PID namespace, so the daemon lands on the same low PID it
+ * had before the unclean stop) and occasionally on a laptop after a reboot.
+ * Treating such a PID as "alive" makes a launcher SIGTERM itself or refuse a
+ * lock it could never have been holding.
+ */
+export function isOtherLiveProcess(pid: number): boolean {
+  return pid !== process.pid && isProcessAlive(pid);
+}
+
 /** Send a signal to a single process. Returns false if the process is gone. */
 export function killProcess(pid: number, signal: NodeJS.Signals = "SIGTERM"): boolean {
   try {

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/);
   });