@stigmer/cli 3.12.9 → 3.14.0-dev.20260910084630

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

@@ -8,7 +8,11 @@ const baseInputs: DaemonEnvInputs = {
   temporalAddress: "127.0.0.1:7233",
   serverOnly: false,
   noWeb: false,
-  serverBin: "/usr/local/bin/stigmer-server",
+  server: {
+    nodeBin: "/usr/bin/node",
+    entryPath: "/repo/server/dist/main.js",
+    appDir: "/repo/server",
+  },
   runner: { nodeBin: "/usr/bin/node", entryPath: "/repo/runner/dist/main.js", appDir: "/repo/runner" },
 };
 
@@ -23,7 +27,11 @@ describe("buildDaemonEnv + readDaemonConfig", () => {
       temporalAddress: "127.0.0.1:7233",
       serverOnly: false,
       noWeb: false,
-      serverBin: "/usr/local/bin/stigmer-server",
+      server: {
+        nodeBin: "/usr/bin/node",
+        entryPath: "/repo/server/dist/main.js",
+        appDir: "/repo/server",
+      },
       runner: { nodeBin: "/usr/bin/node", entryPath: "/repo/runner/dist/main.js", appDir: "/repo/runner" },
       cursorApiKey: undefined,
       anthropicApiKey: undefined,
@@ -90,8 +98,11 @@ describe("buildDaemonEnv + readDaemonConfig", () => {
     expect(readDaemonConfig(env)).not.toHaveProperty("openaiApiKey");
   });
 
-  it("requires the data dir and server binary", () => {
+  it("requires the data dir and the full server launch triple", () => {
     expect(() => readDaemonConfig({})).toThrow(/STIGMER_DATA_DIR/);
-    expect(() => readDaemonConfig({ STIGMER_DATA_DIR: "/x" })).toThrow(/STIGMER_SERVER_BIN/);
+    expect(() => readDaemonConfig({ STIGMER_DATA_DIR: "/x" })).toThrow(/STIGMER_SERVER_NODE_BIN/);
+    expect(() => readDaemonConfig({ STIGMER_DATA_DIR: "/x", STIGMER_SERVER_NODE_BIN: "/usr/bin/node" })).toThrow(
+      /STIGMER_SERVER_ENTRY/,
+    );
   });
 });

package/src/local/daemon/env.ts

@@ -12,7 +12,9 @@ export const DaemonEnvVar = {
   TemporalAddress: "TEMPORAL_SERVICE_ADDRESS",
   ServerOnly: "STIGMER_SERVER_ONLY",
   NoWeb: "STIGMER_NO_WEB",
-  ServerBin: "STIGMER_SERVER_BIN",
+  ServerNodeBin: "STIGMER_SERVER_NODE_BIN",
+  ServerEntry: "STIGMER_SERVER_ENTRY",
+  ServerAppDir: "STIGMER_SERVER_APP_DIR",
   RunnerNodeBin: "STIGMER_RUNNER_NODE_BIN",
   RunnerEntry: "STIGMER_RUNNER_ENTRY",
   RunnerAppDir: "STIGMER_RUNNER_APP_DIR",
@@ -30,6 +32,18 @@ export interface RunnerLaunch {
   appDir: string;
 }
 
+/**
+ * Resolved server launch coordinates: a node binary + bundled entry — the
+ * same launch shape as the runner. (Until #25 go-server-retirement this was
+ * a discriminated union whose "binary" variant carried the Go rollback
+ * executable.)
+ */
+export interface ServerLaunch {
+  nodeBin: string;
+  entryPath: string;
+  appDir: string;
+}
+
 /** The daemon's resolved configuration, parsed from the environment. */
 export interface DaemonConfig {
   dataDir: string;
@@ -38,7 +52,7 @@ export interface DaemonConfig {
   temporalAddress: string;
   serverOnly: boolean;
   noWeb: boolean;
-  serverBin: string;
+  server: ServerLaunch;
   runner?: RunnerLaunch;
   cursorApiKey?: string;
   anthropicApiKey?: string;
@@ -55,7 +69,7 @@ export interface DaemonEnvInputs {
   temporalAddress: string;
   serverOnly: boolean;
   noWeb: boolean;
-  serverBin: string;
+  server: ServerLaunch;
   runner?: RunnerLaunch;
   // Anthropic API key resolved by the launcher (env > config file). Must be
   // written into the daemon env explicitly: unlike a shell-exported key, a key
@@ -83,7 +97,9 @@ export function buildDaemonEnv(inputs: DaemonEnvInputs, base: NodeJS.ProcessEnv
   env[DaemonEnvVar.LogDir] = inputs.logDir;
   env[DaemonEnvVar.TemporalManaged] = String(inputs.temporalManaged);
   env[DaemonEnvVar.TemporalAddress] = inputs.temporalAddress;
-  env[DaemonEnvVar.ServerBin] = inputs.serverBin;
+  env[DaemonEnvVar.ServerNodeBin] = inputs.server.nodeBin;
+  env[DaemonEnvVar.ServerEntry] = inputs.server.entryPath;
+  env[DaemonEnvVar.ServerAppDir] = inputs.server.appDir;
   if (inputs.serverOnly) env[DaemonEnvVar.ServerOnly] = "true";
   if (inputs.noWeb) env[DaemonEnvVar.NoWeb] = "1";
   if (inputs.runner !== undefined && !inputs.serverOnly) {
@@ -112,7 +128,7 @@ export function readDaemonConfig(env: NodeJS.ProcessEnv = process.env): DaemonCo
     temporalAddress: env[DaemonEnvVar.TemporalAddress] ?? "127.0.0.1:7233",
     serverOnly,
     noWeb: env[DaemonEnvVar.NoWeb] === "1",
-    serverBin: required(env, DaemonEnvVar.ServerBin),
+    server: readServer(env),
     runner: serverOnly ? undefined : runner,
     cursorApiKey: nonEmpty(env[DaemonEnvVar.CursorApiKey]),
     anthropicApiKey: nonEmpty(env[DaemonEnvVar.AnthropicApiKey]),
@@ -122,6 +138,18 @@ export function readDaemonConfig(env: NodeJS.ProcessEnv = process.env): DaemonCo
   };
 }
 
+function readServer(env: NodeJS.ProcessEnv): ServerLaunch {
+  const nodeBin = env[DaemonEnvVar.ServerNodeBin];
+  const entryPath = env[DaemonEnvVar.ServerEntry];
+  const appDir = env[DaemonEnvVar.ServerAppDir];
+  if (!nodeBin || !entryPath || !appDir) {
+    throw new Error(
+      `the ${DaemonEnvVar.ServerNodeBin}/${DaemonEnvVar.ServerEntry}/${DaemonEnvVar.ServerAppDir} triple is required for the daemon process`,
+    );
+  }
+  return { nodeBin, entryPath, appDir };
+}
+
 function readRunner(env: NodeJS.ProcessEnv): RunnerLaunch | undefined {
   const nodeBin = env[DaemonEnvVar.RunnerNodeBin];
   const entryPath = env[DaemonEnvVar.RunnerEntry];

package/src/local/daemon/launch.ts

@@ -2,7 +2,7 @@
 // `down` (signal + wait + safety-net cleanup), and a liveness check.
 //
 // `up` resolves every heavy dependency in the foreground (Temporal binary,
-// server binary, runner entry) so failures surface with a clear message before
+// 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.
 
@@ -24,7 +24,7 @@ import { rotateLogs } from "../state/log-rotation.js";
 import { resolveApiKey, resolveProvider } from "../llm-config.js";
 import { resolveOperatorIdentity } from "../operator-config.js";
 import { ensureRunner } from "../runtime/runner.js";
-import { ensureServerBinary } from "../runtime/server.js";
+import { ensureServer } from "../runtime/server.js";
 import { TemporalManager } from "../temporal/manager.js";
 import { buildDaemonEnv, type DaemonEnvInputs } from "./env.js";
 
@@ -64,7 +64,8 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
     await temporal.ensureInstalled();
   }
 
-  const serverBin = await ensureServerBinary({ home });
+  // Resolves the server (repo tree or the acquired @stigmer/server-slim).
+  const server = ensureServer({ home });
   const runner = options.serverOnly === true ? undefined : ensureRunner({ home });
 
   const env = buildDaemonEnv(
@@ -75,7 +76,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
       temporalAddress: temporal.address,
       serverOnly: options.serverOnly === true,
       noWeb: options.noWeb === true,
-      serverBin,
+      server,
       runner,
       ...resolveLlmKeyInputs(config),
       ...resolveOperatorIdentityInputs(config),

package/src/local/daemon/process.ts

@@ -103,15 +103,18 @@ export async function runInternalDaemon(deps: InternalDaemonDeps): Promise<numbe
   await clock.sleep(SETTLE_DELAY_MS);
   supervisor.settleCheck();
 
-  // Web console: detect-and-skip until T06 wires real serving.
+  // Web console: the SERVER serves it from its unified port (DD-012); the
+  // daemon probes and records what a browser would actually find. pid 0 is
+  // truthful — there is no separate console process to supervise.
+  const consoleAvailable = config.noWeb ? false : await isWebConsoleAvailable();
   healthState.components["web-console"] = {
     pid: 0,
-    state: config.noWeb || !isWebConsoleAvailable() ? "stopped" : "running",
+    state: consoleAvailable ? "running" : "stopped",
     started_at: "",
     restart_count: 0,
   };
-  if (config.noWeb) log.info("web console disabled via --no-web");
-  else if (!isWebConsoleAvailable()) log.debug("web console not bundled in this build, skipping");
+  if (config.noWeb) log.info("web console suppressed via --no-web");
+  else if (!consoleAvailable) log.debug("server did not answer the console probe (no export bundled), skipping");
   persist();
 
   // --- Health monitor: sync Temporal + drive one supervisor tick per interval. ---

package/src/local/runtime/index.ts

@@ -1,6 +1,6 @@
 // Public surface of the runtime-acquisition seams (DD-002/003/007).
 
-export { resolveNode } from "./node.js";
+export { resolveNode, resolveServerNode } from "./node.js";
 export {
   type EnsureRunnerOptions,
   type RunnerResolution,
@@ -8,11 +8,12 @@ export {
   ensureRunner,
   resolveRunner,
 } from "./runner.js";
+// The TS server — the served implementation since the DD-006 cutover (D4 #24;
+// the Go binary ladder that backed rollback retired with #25).
 export {
   type EnsureServerOptions,
-  type ServerDownloadTarget,
-  downloadServerBinary,
-  ensureServerBinary,
-  resolveServerBinary,
+  acquireServer,
+  ensureServer,
+  resolveServerTs,
 } from "./server.js";
 export { which } from "./which.js";

package/src/local/runtime/node.ts

@@ -1,4 +1,5 @@
-// Resolution of the Node.js runtime used to launch the runner subprocess.
+// Resolution of the Node.js runtime used to launch the runner and TS-server
+// subprocesses.
 //
 // We reuse the very Node that is running the CLI (process.execPath). The CLI is
 // itself an npm package with `engines: node >= 22.13`, so a suitable Node is
@@ -8,16 +9,26 @@
 // (`spawn(process.execPath, ...)`). An explicit STIGMER_NODE_BIN override is
 // honored and capability-checked for advanced/multi-runtime setups.
 //
-// The gate is a CAPABILITY probe, not a version check. The runner's durable
-// local checkpointer imports Node's built-in `node:sqlite`, available unflagged
-// from 22.13 in the 22.x line and only from 23.4 in the 23.x line — a gap
-// (23.0–23.3) that a previous version-table gate here missed, letting those
-// Nodes through to crash at runner boot with a raw ERR_UNKNOWN_BUILTIN_MODULE.
-// Probing "can this binary provide node:sqlite?" directly cannot drift; the
-// version floors survive only in the error message, where staleness is
-// harmless. The runner performs the same probe on its own boot (see
-// backend/services/runner/src/preflight.ts) — this one exists to fail at
-// resolve time with CLI-appropriate guidance instead of a subprocess crash.
+// The gates are CAPABILITY probes, not version checks. Two probes, because the
+// two children need different sqlite capabilities:
+//
+// - The RUNNER's durable local checkpointer imports Node's built-in
+//   `node:sqlite`, available unflagged from 22.13 in the 22.x line and only
+//   from 23.4 in the 23.x line — a gap (23.0–23.3) that a previous
+//   version-table gate here missed, letting those Nodes through to crash at
+//   runner boot with a raw ERR_UNKNOWN_BUILTIN_MODULE.
+// - The SERVER additionally needs `node:sqlite` compiled WITH FTS5 (its
+//   search index; migration v3 creates an fts5 virtual table at boot). Node
+//   23.4 PROVIDES node:sqlite but its sqlite build LACKS FTS5 — found by
+//   D4 #14 and the reason the module-presence probe alone is insufficient
+//   for the server. Probing "can this binary create an fts5 table?" directly
+//   cannot drift; the version floors survive only in the error messages,
+//   where staleness is harmless.
+//
+// The runner performs the module-presence probe on its own boot (see
+// backend/services/runner/src/preflight.ts); the server fails at migration
+// time. Both probes here exist to fail at resolve time with CLI-appropriate
+// guidance instead of a subprocess crash.
 
 import { execFileSync } from "node:child_process";
 import { CliExitError } from "../../errors/cli-exit-error.js";
@@ -39,6 +50,16 @@ import { ExitCode } from "../../errors/exit-codes.js";
 const NODE_SQLITE_PROBE =
   "process.exit(process.getBuiltinModule?.('node:sqlite') === undefined ? 1 : 0)";
 
+// Exits 0 when the binary's `node:sqlite` can create an FTS5 virtual table,
+// 1 otherwise. Strictly stronger than NODE_SQLITE_PROBE: it exercises the
+// exact operation the server's migration v3 performs, in memory. The
+// try/catch covers both failure shapes — module absent (TypeError on the
+// undefined module) and FTS5 absent (the exec throws "no such module: fts5").
+const NODE_SQLITE_FTS5_PROBE =
+  "try{const{DatabaseSync}=process.getBuiltinModule('node:sqlite');" +
+  "new DatabaseSync(':memory:').exec('CREATE VIRTUAL TABLE t USING fts5(x)');" +
+  "process.exit(0)}catch{process.exit(1)}";
+
 /**
  * Resolve the Node binary to launch the runner with. Honors STIGMER_NODE_BIN;
  * otherwise returns the current runtime. Either way the binary is probed for
@@ -47,12 +68,50 @@ const NODE_SQLITE_PROBE =
  * runner-launch paths only (ensureRunner), never on ordinary CLI commands.
  */
 export function resolveNode(): string {
-  const override = process.env.STIGMER_NODE_BIN;
-  const bin = override !== undefined && override !== "" ? override : process.execPath;
-  assertProvidesNodeSqlite(bin);
+  const bin = nodeCandidate();
+  assertCapability(bin, NODE_SQLITE_PROBE, {
+    subject: "the runner",
+    capability: "the built-in node:sqlite module",
+    floor: "Node >= 22.13 (>= 23.4 in the 23.x line)",
+    detail: [
+      "The runner's durable checkpointer requires node:sqlite, which is available",
+      "unflagged from Node 22.13 (22.x line) and 23.4 (23.x and later) — note that",
+      "23.0-23.3 lack it.",
+    ],
+  });
+  return bin;
+}
+
+/**
+ * Resolve the Node binary to launch the TS server with. Same
+ * STIGMER_NODE_BIN/execPath resolution as {@link resolveNode}, but probes for
+ * `node:sqlite` WITH FTS5 — the server's search index needs it and some Node
+ * builds (e.g. 23.4) ship node:sqlite without it. Runs on server-launch paths
+ * only (ensureServer).
+ */
+export function resolveServerNode(): string {
+  const bin = nodeCandidate();
+  assertCapability(bin, NODE_SQLITE_FTS5_PROBE, {
+    subject: "the stigmer server",
+    capability: "the built-in node:sqlite module with FTS5",
+    floor: "Node 22.13+ in the 22.x line (23.x builds lack FTS5)",
+    detail: [
+      "The server's search index requires node:sqlite compiled with FTS5.",
+      "The 22.x line from 22.13 is known-good; 23.x builds ship node:sqlite",
+      "WITHOUT FTS5 and cannot run the server. Newer majors work if their",
+      "sqlite build includes FTS5 — this probe is the authority.",
+    ],
+  });
   return bin;
 }
 
+function nodeCandidate(): string {
+  const override = process.env.STIGMER_NODE_BIN;
+  return override !== undefined && override !== ""
+    ? override
+    : process.execPath;
+}
+
 /** Best-effort `--version` for error messages only; null when the spawn fails. */
 function probeNodeVersion(bin: string): string | null {
   try {
@@ -66,10 +125,27 @@ function probeNodeVersion(bin: string): string | null {
   }
 }
 
-function assertProvidesNodeSqlite(bin: string): void {
+interface CapabilityErrorCopy {
+  /** What is being launched, e.g. "the runner". */
+  subject: string;
+  /** The missing capability, in user terms. */
+  capability: string;
+  /** The known-good version floor, per probe — the two probes differ (the
+   * runner accepts 23.4+; the server does not). Error copy only; the probe
+   * is the authority. */
+  floor: string;
+  /** Guidance lines explaining the requirement. */
+  detail: string[];
+}
+
+function assertCapability(
+  bin: string,
+  probe: string,
+  copy: CapabilityErrorCopy,
+): void {
   let exitStatus: number | null;
   try {
-    execFileSync(bin, ["-e", NODE_SQLITE_PROBE], { stdio: "ignore" });
+    execFileSync(bin, ["-e", probe], { stdio: "ignore" });
     return;
   } catch (err) {
     // execFileSync reports a nonzero exit via `status`; a spawn failure
@@ -78,19 +154,19 @@ function assertProvidesNodeSqlite(bin: string): void {
   }
 
   if (exitStatus === null) {
-    throw new CliExitError(`could not run ${bin} to verify the runner's Node requirements`, ExitCode.General, [
-      `Ensure ${bin} is a working Node >= 22.13 runtime (>= 23.4 in the 23.x line).`,
-    ]);
+    throw new CliExitError(
+      `could not run ${bin} to verify ${copy.subject}'s Node requirements`,
+      ExitCode.General,
+      [`Ensure ${bin} is a working ${copy.floor} runtime.`],
+    );
   }
 
   const version = probeNodeVersion(bin) ?? "unknown version";
   throw new CliExitError(
-    `Node at ${bin} (${version}) cannot run the runner: it does not provide the built-in node:sqlite module`,
+    `Node at ${bin} (${version}) cannot run ${copy.subject}: it does not provide ${copy.capability}`,
     ExitCode.General,
     [
-      "The runner's durable checkpointer requires node:sqlite, which is available",
-      "unflagged from Node 22.13 (22.x line) and 23.4 (23.x and later) — note that",
-      "23.0-23.3 lack it.",
+      ...copy.detail,
       "Upgrade Node, or point STIGMER_NODE_BIN at a suitable runtime.",
     ],
   );

package/src/local/runtime/runner.ts

@@ -17,8 +17,7 @@
 // launch contract (`node main.js`) is identical to the repo-tree runner, so the
 // daemon spawns either the same way.
 
-import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -28,6 +27,7 @@ import { log } from "../../logger.js";
 import { VERSION } from "../../version.js";
 import { runtimesDir } from "../paths.js";
 import { resolveNode } from "./node.js";
+import { ensureRuntimesRoot, isAcquirableRelease, npmInstallIntoRuntimes, type NpmInstall } from "./runtimes-install.js";
 
 const SLIM_PACKAGE = "@stigmer/runner-slim";
 
@@ -48,7 +48,7 @@ export interface EnsureRunnerOptions {
   /** Node resolver (injectable for tests). */
   node?: () => string;
   /** npm install implementation (injectable for tests). */
-  install?: (installDir: string, spec: string) => void;
+  install?: NpmInstall;
 }
 
 /**
@@ -111,14 +111,8 @@ export function acquireRunner(opts: EnsureRunnerOptions = {}): RunnerResolution
 
   if (!existsSync(entryPath)) {
     log.info(`acquiring ${SLIM_PACKAGE}`, { version, dir: installDir });
-    mkdirSync(installDir, { recursive: true });
-    // A stable package.json root makes the install deterministic and records the
-    // pinned dependency rather than letting npm synthesize an ad-hoc root.
-    writeFileSync(
-      join(installDir, "package.json"),
-      `${JSON.stringify({ name: "stigmer-runtime", private: true, version: "0.0.0" }, null, 2)}\n`,
-    );
-    const install = opts.install ?? installRunnerSlim;
+    ensureRuntimesRoot(installDir);
+    const install = opts.install ?? npmInstallIntoRuntimes;
     install(installDir, `${SLIM_PACKAGE}@${version}`);
   }
 
@@ -132,24 +126,6 @@ export function acquireRunner(opts: EnsureRunnerOptions = {}): RunnerResolution
   return { nodeBin: node(), entryPath, appDir: dirname(entryPath) };
 }
 
-// Install the slim package (plus its platform-native optional dependency) into an
-// isolated prefix. `--omit=dev` drops devDependencies while keeping the optional
-// native package npm selects by os/cpu; output is inherited so the user sees the
-// one-time download progress.
-function installRunnerSlim(installDir: string, spec: string): void {
-  try {
-    execFileSync("npm", ["install", spec, "--prefix", installDir, "--omit=dev", "--no-audit", "--no-fund"], {
-      stdio: "inherit",
-    });
-  } catch (err) {
-    throw new CliExitError(`failed to install ${spec}`, ExitCode.General, [
-      `Command: npm install ${spec} --prefix ${installDir}`,
-      "Ensure npm is on PATH and the network is reachable.",
-      String(err),
-    ]);
-  }
-}
-
 function resolveBuiltRunner(appDir: string, node: () => string): RunnerResolution {
   const entryPath = join(appDir, "dist", "main.js");
   if (!existsSync(entryPath)) {
@@ -162,13 +138,6 @@ function resolveBuiltRunner(appDir: string, node: () => string): RunnerResolutio
   return { nodeBin: node(), entryPath, appDir };
 }
 
-// A source build reports "0.0.0-dev" and the dev npm channel stamps "<v>-dev.<stamp>"
-// versions; neither publishes a matching @stigmer/runner-slim, so they are not
-// acquirable. Release and rc/next versions are.
-function isAcquirableRelease(version: string): boolean {
-  return !version.includes("-dev");
-}
-
 function hasPackageJson(dir: string): boolean {
   return existsSync(join(dir, "package.json"));
 }

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

@@ -3,9 +3,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { CliExitError } from "../../errors/cli-exit-error.js";
-import { resolveNode } from "./node.js";
+import { resolveNode, resolveServerNode } from "./node.js";
 import { acquireRunner, resolveRunner } from "./runner.js";
-import { resolveServerBinary } from "./server.js";
 import { which } from "./which.js";
 
 function tempDir(prefix: string): string {
@@ -13,7 +12,7 @@ function tempDir(prefix: string): string {
 }
 
 // Snapshot and restore the env vars these resolvers read, so tests don't leak.
-const TOUCHED = ["PATH", "STIGMER_SERVER_BIN", "STIGMER_RUNNER_DIR", "STIGMER_NODE_BIN"] as const;
+const TOUCHED = ["PATH", "STIGMER_RUNNER_DIR", "STIGMER_NODE_BIN"] as const;
 let saved: Record<string, string | undefined>;
 
 beforeEach(() => {
@@ -52,12 +51,19 @@ describe("which", () => {
 
 // A fake "node" whose --version and capability-probe behavior the test
 // controls, making these tests deterministic regardless of which Node runs
-// the suite itself.
-function fakeNodeBinary(opts: { version: string; hasSqlite: boolean }): string {
+// the suite itself. The fake INSPECTS the probe script it receives ("fts5"
+// in the source distinguishes the server's FTS5 probe from the runner's
+// module-presence probe), so a mutation that wires resolveServerNode to the
+// weaker probe — or neuters the FTS5 probe's failure exit — fails here.
+function fakeNodeBinary(opts: { version: string; hasSqlite: boolean; hasFts5?: boolean }): string {
   const bin = join(tempDir("stigmer-node-"), "node");
+  const fts5Exit = (opts.hasFts5 ?? opts.hasSqlite) ? 0 : 1;
   writeFileSync(
     bin,
-    `#!/bin/sh\nif [ "$1" = "--version" ]; then echo "${opts.version}"; exit 0; fi\nexit ${opts.hasSqlite ? 0 : 1}\n`,
+    `#!/bin/sh\n` +
+      `if [ "$1" = "--version" ]; then echo "${opts.version}"; exit 0; fi\n` +
+      `case "$2" in *fts5*) exit ${fts5Exit};; esac\n` +
+      `exit ${opts.hasSqlite ? 0 : 1}\n`,
   );
   chmodSync(bin, 0o755);
   return bin;
@@ -97,15 +103,53 @@ describe("resolveNode", () => {
   });
 });
 
-describe("resolveServerBinary", () => {
-  it("honors the STIGMER_SERVER_BIN override", () => {
-    const dir = tempDir("stigmer-server-");
-    const bin = join(dir, "stigmer-server");
-    writeFileSync(bin, "#!/bin/sh\n");
-    chmodSync(bin, 0o755);
-    process.env.STIGMER_SERVER_BIN = bin;
-    expect(resolveServerBinary()).toBe(bin);
+describe("resolveServerNode", () => {
+  it("honors an override that passes the FTS5 capability probe", () => {
+    const bin = fakeNodeBinary({ version: "v22.13.0", hasSqlite: true });
+    process.env.STIGMER_NODE_BIN = bin;
+    expect(resolveServerNode()).toBe(bin);
+  });
+
+  it("rejects a Node whose sqlite lacks FTS5, naming the capability (the 23.4 trap)", () => {
+    // The shape of a REAL 23.4 binary: node:sqlite present (the module probe
+    // would pass), FTS5 absent (the fts5 probe fails) — pinning that the
+    // server resolution dispatches the STRONGER probe (D4 #14).
+    process.env.STIGMER_NODE_BIN = fakeNodeBinary({ version: "v23.4.0", hasSqlite: true, hasFts5: false });
+
+    expect(() => resolveServerNode()).toThrow(/FTS5/);
+    expect(() => resolveServerNode()).toThrow(/v23\.4\.0/);
+  });
+
+  it("the runner resolution still accepts the 23.4 shape (module present, FTS5 absent)", () => {
+    // The two probes deliberately differ: the runner needs only node:sqlite.
+    const bin = fakeNodeBinary({ version: "v23.4.0", hasSqlite: true, hasFts5: false });
+    process.env.STIGMER_NODE_BIN = bin;
+    expect(resolveNode()).toBe(bin);
   });
+
+  it("runs the real FTS5 probe against the current runtime", () => {
+    // The one place the REAL probe script executes end-to-end (the fake-node
+    // tests above only exercise the dispatch and error copy). Conditional on
+    // the runtime's own capability — the resolveNode own-runtime pattern —
+    // so a no-FTS5 Node (e.g. 23.4) asserts the throw instead of the pass.
+    delete process.env.STIGMER_NODE_BIN;
+    if (currentRuntimeHasFts5()) {
+      expect(resolveServerNode()).toBe(process.execPath);
+    } else {
+      expect(() => resolveServerNode()).toThrow(/FTS5/);
+    }
+  });
+
+  function currentRuntimeHasFts5(): boolean {
+    const sqlite = process.getBuiltinModule?.("node:sqlite");
+    if (sqlite === undefined) return false;
+    try {
+      new sqlite.DatabaseSync(":memory:").exec("CREATE VIRTUAL TABLE t USING fts5(x)");
+      return true;
+    } catch {
+      return false;
+    }
+  }
 });
 
 describe("resolveRunner", () => {

package/src/local/runtime/runtimes-install.test.ts

@@ -0,0 +1,56 @@
+// Pins the shared runtimes-install contract both acquirers depend on: the
+// no-clobber root manifest (the runner and the server install into ONE
+// per-version root), the dev-version gate, and the actionable install
+// failure.
+
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ensureRuntimesRoot, isAcquirableRelease, npmInstallIntoRuntimes } from "./runtimes-install.js";
+
+function tempDir(): string {
+  return mkdtempSync(join(tmpdir(), "stigmer-runtimes-"));
+}
+
+describe("ensureRuntimesRoot", () => {
+  it("creates the root with the stable manifest when absent", () => {
+    const dir = join(tempDir(), "0.5.0");
+    ensureRuntimesRoot(dir);
+    const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    expect(manifest).toEqual({ name: "stigmer-runtime", private: true, version: "0.0.0" });
+  });
+
+  it("never clobbers an existing root manifest — the shared-root contract", () => {
+    const dir = tempDir();
+    writeFileSync(join(dir, "package.json"), '{"name":"stigmer-runtime","marker":"first-installer"}\n');
+    ensureRuntimesRoot(dir);
+    expect(readFileSync(join(dir, "package.json"), "utf8")).toContain("first-installer");
+  });
+});
+
+describe("isAcquirableRelease", () => {
+  it("admits releases and rc/next versions, refuses dev builds", () => {
+    expect(isAcquirableRelease("0.5.0")).toBe(true);
+    expect(isAcquirableRelease("0.5.0-rc.1")).toBe(true);
+    expect(isAcquirableRelease("0.0.0-dev")).toBe(false);
+    expect(isAcquirableRelease("0.5.0-dev.20260825")).toBe(false);
+  });
+});
+
+describe("npmInstallIntoRuntimes", () => {
+  it("wraps an install failure in an actionable CliExitError with remediation hints", () => {
+    // /dev/null/x is unwritable on every POSIX system, so the real npm spawn
+    // fails deterministically without network access.
+    const attempt = (): void => npmInstallIntoRuntimes("/dev/null/x", "@stigmer/nonexistent@0.0.0");
+    expect(attempt).toThrow(CliExitError);
+    try {
+      attempt();
+    } catch (err) {
+      const hints = (err as CliExitError).hints?.join("\n") ?? "";
+      expect(hints).toMatch(/npm install/);
+      expect(hints).toMatch(/remove/i);
+    }
+  });
+});