@tetsuo-ai/agenc 0.10.0 → 0.13.0

package/lib/runtime-release-contract.d.mts

@@ -13,7 +13,14 @@ export interface RuntimeReleaseArtifact {
   readonly attestationUrl?: string;
   readonly attestationSha256?: string;
   readonly attestationBytes?: number;
-  readonly bins?: { readonly agenc?: string };
+  readonly buildProvenanceUrl?: string;
+  readonly buildProvenanceSha256?: string;
+  readonly buildProvenanceBytes?: number;
+  readonly bins?: {
+    readonly agenc?: string;
+    readonly node?: string;
+    readonly nodeLibrary?: string;
+  };
   readonly [key: string]: unknown;
 }
 
@@ -32,6 +39,10 @@ export const MAX_RUNTIME_ARTIFACT_BYTES: number;
 export const MAX_RUNTIME_ATTESTATION_BYTES: number;
 export const OFFICIAL_RELEASE_REPOSITORY: string;
 export const OFFICIAL_SOURCE_REPOSITORY: string;
+export const FROZEN_LEGACY_RUNTIME_VERSION: "0.7.2";
+export const MINIMUM_PRIVATE_NODE_RUNTIME_VERSION: "0.11.2";
+export const MINIMUM_DUAL_PROVENANCE_RUNTIME_VERSION: "0.13.0";
+export const PRIVATE_NODE_BOOTSTRAP_RELEASE_TAG: "agenc-v0.11.2";
 export const OFFICIAL_RELEASE_WORKFLOW: string;
 export const RUNTIME_ATTESTATION_POLICY: Readonly<{
   repository: string;
@@ -40,6 +51,14 @@ export const RUNTIME_ATTESTATION_POLICY: Readonly<{
   oidcIssuer: string;
   predicateType: string;
 }>;
+export const RUNTIME_BUILD_PROVENANCE_POLICY: Readonly<{
+  repository: string;
+  signerWorkflow: string;
+  hostname: string;
+  oidcIssuer: string;
+  predicateType: string;
+  sourceRef: "refs/heads/main";
+}>;
 export const PINNED_GITHUB_CLI_VERSION: string;
 export const PINNED_GITHUB_CLI_ARTIFACTS: Readonly<Record<string, Readonly<{
   file: string;
@@ -47,6 +66,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS: Readonly<Record<string, Readonly<{
   sha256: string;
   bytes: number;
   executable: string;
+  executableSha256: string;
+  executableBytes: number;
 }>>>;
 export const RUNTIME_MANIFEST_TRUST_MODES: readonly RuntimeManifestTrustMode[];
 
@@ -57,6 +78,13 @@ export function canonicalRuntimeAttestationVerificationArgs(options: {
   readonly sourceRef: string;
 }): readonly string[];
 
+export function canonicalRuntimeBuildProvenanceVerificationArgs(options: {
+  readonly subjectPath: string;
+  readonly bundlePath: string;
+  readonly sourceCommit: string;
+  readonly sourceRef?: "refs/heads/main";
+}): readonly string[];
+
 export type LocalFileUrlPlatform =
   | "win"
   | "win32"
@@ -79,6 +107,32 @@ export function canonicalRuntimeArtifactName(
   >,
 ): string;
 
+export function canonicalRuntimeNodeBin(platform: string): string;
+
+export function canonicalRuntimeNodeLibrary(platform: string): string | undefined;
+
+export function requireSupportedRuntimeVersion(version: string): string;
+
+export function runtimeVersionRequiresDualProvenance(version: string): boolean;
+
+export interface RuntimeReleaseCandidateIdentity {
+  readonly workflow: "release-runtime.yml";
+  readonly runId: number;
+  readonly runAttempt: number;
+  readonly runUrl: string;
+  readonly phase: "candidate";
+  readonly sourceRef: "refs/heads/main";
+  readonly evidenceSha256: string;
+}
+
+export function validateRuntimeReleaseCandidateIdentity<
+  T extends RuntimeReleaseCandidateIdentity,
+>(
+  value: T | undefined,
+  sourceCommit: unknown,
+  options?: { readonly required?: boolean },
+): T | undefined;
+
 export function canonicalLocalFileUrlToPath(
   value: string,
   platform?: LocalFileUrlPlatform,

package/lib/runtime-release-contract.mjs

@@ -10,6 +10,11 @@ export const MAX_RUNTIME_ARTIFACT_BYTES = 256 * 1024 * 1024;
 export const MAX_RUNTIME_ATTESTATION_BYTES = 4 * 1024 * 1024;
 export const OFFICIAL_RELEASE_REPOSITORY = "tetsuo-ai/agenc-releases";
 export const OFFICIAL_SOURCE_REPOSITORY = "tetsuo-ai/agenc-core";
+export const FROZEN_LEGACY_RUNTIME_VERSION = "0.7.2";
+export const MINIMUM_PRIVATE_NODE_RUNTIME_VERSION = "0.11.2";
+export const MINIMUM_DUAL_PROVENANCE_RUNTIME_VERSION = "0.13.0";
+export const PRIVATE_NODE_BOOTSTRAP_RELEASE_TAG =
+  `agenc-v${MINIMUM_PRIVATE_NODE_RUNTIME_VERSION}`;
 export const OFFICIAL_RELEASE_WORKFLOW =
   "tetsuo-ai/agenc-core/.github/workflows/release-runtime.yml";
 export const RUNTIME_ATTESTATION_POLICY = Object.freeze({
@@ -19,6 +24,10 @@ export const RUNTIME_ATTESTATION_POLICY = Object.freeze({
   oidcIssuer: "https://token.actions.githubusercontent.com",
   predicateType: "https://slsa.dev/provenance/v1",
 });
+export const RUNTIME_BUILD_PROVENANCE_POLICY = Object.freeze({
+  ...RUNTIME_ATTESTATION_POLICY,
+  sourceRef: "refs/heads/main",
+});
 export const PINNED_GITHUB_CLI_VERSION = "2.96.0";
 export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
   "linux-x64": Object.freeze({
@@ -27,6 +36,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
     sha256: "83d5c2ccad5498f58bf6368acb1ab32588cf43ab3a4b1c301bf36328b1c8bd60",
     bytes: 14652560,
     executable: "gh_2.96.0_linux_amd64/bin/gh",
+    executableSha256: "56b8bbbb27b066ecb33dbef9a256dc9d1314adaeff0908a752feba6c34053b40",
+    executableBytes: 40722594,
   }),
   "linux-arm64": Object.freeze({
     file: "gh_2.96.0_linux_arm64.tar.gz",
@@ -34,6 +45,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
     sha256: "06f86ec7103d41993b76cd78072f43595c34aaa56506d971d9860e67140bf909",
     bytes: 13321232,
     executable: "gh_2.96.0_linux_arm64/bin/gh",
+    executableSha256: "f903d2fa04ae78ee8f8df0186364d0b92f078d2720053941a47e0a3beaef54f0",
+    executableBytes: 37879970,
   }),
   "darwin-x64": Object.freeze({
     file: "gh_2.96.0_macOS_amd64.zip",
@@ -41,6 +54,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
     sha256: "4bd449df9ad639391bc62b8032546f0fe9edcd8526e06682a4f88abd8c5d163c",
     bytes: 15298430,
     executable: "gh_2.96.0_macOS_amd64/bin/gh",
+    executableSha256: "49380b19e758c14ce5509afe0ced58777fe45cfbcd5989941f7314d5f7e468c8",
+    executableBytes: 41773632,
   }),
   "darwin-arm64": Object.freeze({
     file: "gh_2.96.0_macOS_arm64.zip",
@@ -48,6 +63,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
     sha256: "f23a0c37d963aacc3bed703ccbd59b41c5ca22101fab7f00eb2b7cad23aba463",
     bytes: 13950131,
     executable: "gh_2.96.0_macOS_arm64/bin/gh",
+    executableSha256: "b1d6c442fde99ca27c04e1e74d624895abe37785f4a3e9e9b684bf7586ce4bc8",
+    executableBytes: 38817216,
   }),
   "win-x64": Object.freeze({
     file: "gh_2.96.0_windows_amd64.zip",
@@ -55,6 +72,8 @@ export const PINNED_GITHUB_CLI_ARTIFACTS = Object.freeze({
     sha256: "c2d6acc935cd2f00e2144d7e036d5cd82e6b6bd5594e8c75aa75ef2a4ed6aac3",
     bytes: 14821821,
     executable: "gh_2.96.0_windows_amd64/bin/gh.exe",
+    executableSha256: "cd79f16203f1fbe56937c4c96e2b6eadd10549418dcb241d91576ac77af0ac8b",
+    executableBytes: 41504056,
   }),
 });
 export const RUNTIME_MANIFEST_TRUST_MODES = Object.freeze([
@@ -65,17 +84,19 @@ export const RUNTIME_MANIFEST_TRUST_MODES = Object.freeze([
 
 const TRUST_MODES = new Set(RUNTIME_MANIFEST_TRUST_MODES);
 
-export function canonicalRuntimeAttestationVerificationArgs({
+function canonicalRuntimeProvenanceVerificationArgs({
   subjectPath,
   bundlePath,
   sourceCommit,
   sourceRef,
+  sourceRefPattern,
+  sourceRefError,
 }) {
   if (!/^[0-9a-f]{40,64}$/.test(sourceCommit ?? "")) {
     throw new Error("runtime attestation policy requires an exact source commit");
   }
-  if (typeof sourceRef !== "string" || !sourceRef.startsWith("refs/tags/agenc-v")) {
-    throw new Error("runtime attestation policy requires the canonical release source ref");
+  if (typeof sourceRef !== "string" || !sourceRefPattern.test(sourceRef)) {
+    throw new Error(sourceRefError);
   }
   return [
     "attestation",
@@ -103,6 +124,40 @@ export function canonicalRuntimeAttestationVerificationArgs({
   ];
 }
 
+export function canonicalRuntimeAttestationVerificationArgs({
+  subjectPath,
+  bundlePath,
+  sourceCommit,
+  sourceRef,
+}) {
+  return canonicalRuntimeProvenanceVerificationArgs({
+    subjectPath,
+    bundlePath,
+    sourceCommit,
+    sourceRef,
+    sourceRefPattern: /^refs\/tags\/agenc-v[0-9]+\.[0-9]+\.[0-9]+$/,
+    sourceRefError:
+      "runtime attestation policy requires the canonical release source ref",
+  });
+}
+
+export function canonicalRuntimeBuildProvenanceVerificationArgs({
+  subjectPath,
+  bundlePath,
+  sourceCommit,
+  sourceRef = RUNTIME_BUILD_PROVENANCE_POLICY.sourceRef,
+}) {
+  return canonicalRuntimeProvenanceVerificationArgs({
+    subjectPath,
+    bundlePath,
+    sourceCommit,
+    sourceRef,
+    sourceRefPattern: /^refs\/heads\/main$/,
+    sourceRefError:
+      "runtime build provenance policy requires the canonical main source ref",
+  });
+}
+
 export function requireRuntimeManifestTrustMode(trustMode) {
   if (!TRUST_MODES.has(trustMode)) {
     throw new Error(`agenc: unsupported runtime manifest trust mode ${String(trustMode)}`);
@@ -115,6 +170,100 @@ export function canonicalRuntimeArtifactName(manifest, artifact) {
     `-node${artifact.nodeMajor}-abi${artifact.nodeModuleAbi}.tar.gz`;
 }
 
+export function canonicalRuntimeNodeBin(platform) {
+  if (platform === "win" || platform === "win32") {
+    return "node_modules/.agenc-node/node.exe";
+  }
+  if (platform === "linux" || platform === "darwin") {
+    return "node_modules/.agenc-node/bin/node";
+  }
+  throw new Error(`agenc: unsupported runtime Node platform ${String(platform)}`);
+}
+
+export function canonicalRuntimeNodeLibrary(platform) {
+  if (platform === "linux") {
+    return "node_modules/.agenc-node/lib";
+  }
+  if (platform === "darwin" || platform === "win" || platform === "win32") {
+    return undefined;
+  }
+  throw new Error(`agenc: unsupported runtime Node platform ${String(platform)}`);
+}
+
+export function requireSupportedRuntimeVersion(version) {
+  if (version === FROZEN_LEGACY_RUNTIME_VERSION) {
+    return version;
+  }
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(version ?? "");
+  if (match === null) {
+    throw new Error("agenc: runtime version is not a canonical semantic version");
+  }
+  const actual = match.slice(1, 4).map(Number);
+  const minimum = MINIMUM_PRIVATE_NODE_RUNTIME_VERSION.split(".").map(Number);
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (actual[index] > minimum[index]) return version;
+    if (actual[index] < minimum[index]) {
+      throw new Error(
+        `agenc: runtime ${version} has no supported standalone activation contract; ` +
+          `use the frozen ${FROZEN_LEGACY_RUNTIME_VERSION} bridge with host Node 25.9, ` +
+          `or ${MINIMUM_PRIVATE_NODE_RUNTIME_VERSION} and newer with private Node`,
+      );
+    }
+  }
+  return version;
+}
+
+export function runtimeVersionRequiresDualProvenance(version) {
+  requireSupportedRuntimeVersion(version);
+  if (version === FROZEN_LEGACY_RUNTIME_VERSION) return false;
+  const actual = version.split("-", 1)[0].split(".").map(Number);
+  const minimum = MINIMUM_DUAL_PROVENANCE_RUNTIME_VERSION.split(".").map(Number);
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (actual[index] > minimum[index]) return true;
+    if (actual[index] < minimum[index]) return false;
+  }
+  return true;
+}
+
+const RUNTIME_RELEASE_CANDIDATE_KEYS = Object.freeze([
+  "workflow",
+  "runId",
+  "runAttempt",
+  "runUrl",
+  "phase",
+  "sourceRef",
+  "evidenceSha256",
+]);
+
+export function validateRuntimeReleaseCandidateIdentity(
+  value,
+  sourceCommit,
+  { required = false } = {},
+) {
+  if (value === undefined && !required) return undefined;
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).sort().join("\0") !==
+      [...RUNTIME_RELEASE_CANDIDATE_KEYS].sort().join("\0") ||
+    value.workflow !== "release-runtime.yml" ||
+    !Number.isSafeInteger(value.runId) ||
+    value.runId <= 0 ||
+    !Number.isSafeInteger(value.runAttempt) ||
+    value.runAttempt <= 0 ||
+    value.runUrl !==
+      `https://github.com/tetsuo-ai/agenc-core/actions/runs/${value.runId}` ||
+    value.phase !== "candidate" ||
+    value.sourceRef !== RUNTIME_BUILD_PROVENANCE_POLICY.sourceRef ||
+    !/^[0-9a-f]{64}$/.test(value.evidenceSha256 ?? "") ||
+    !/^[0-9a-f]{40}$/.test(sourceCommit ?? "")
+  ) {
+    throw new Error("agenc: runtime release candidate identity is invalid");
+  }
+  return value;
+}
+
 function localFileUrlUsesWindowsPaths(platform) {
   if (platform === "win" || platform === "win32") return true;
   if (
@@ -234,7 +383,10 @@ function validateArtifactUrl(manifest, artifact, trustMode) {
     if (
       artifact.attestationUrl !== undefined ||
       artifact.attestationSha256 !== undefined ||
-      artifact.attestationBytes !== undefined
+      artifact.attestationBytes !== undefined ||
+      artifact.buildProvenanceUrl !== undefined ||
+      artifact.buildProvenanceSha256 !== undefined ||
+      artifact.buildProvenanceBytes !== undefined
     ) {
       throw new Error("agenc: explicit local runtime artifacts must not declare remote attestations");
     }
@@ -268,6 +420,31 @@ function validateArtifactUrl(manifest, artifact, trustMode) {
       throw new Error("agenc: runtime artifact attestation size is invalid");
     }
   }
+  const hasBuildProvenance =
+    artifact.buildProvenanceUrl !== undefined ||
+    artifact.buildProvenanceSha256 !== undefined ||
+    artifact.buildProvenanceBytes !== undefined;
+  if (
+    (
+      trustMode === "official" &&
+      runtimeVersionRequiresDualProvenance(manifest.runtimeVersion)
+    ) ||
+    hasBuildProvenance
+  ) {
+    if (artifact.buildProvenanceUrl !== `${artifact.url}.build.sigstore.json`) {
+      throw new Error("agenc: runtime artifact build provenance URL is not canonical");
+    }
+    if (!/^[0-9a-f]{64}$/.test(artifact.buildProvenanceSha256 ?? "")) {
+      throw new Error("agenc: runtime artifact build provenance digest is invalid");
+    }
+    if (
+      !Number.isSafeInteger(artifact.buildProvenanceBytes) ||
+      artifact.buildProvenanceBytes <= 0 ||
+      artifact.buildProvenanceBytes > MAX_RUNTIME_ATTESTATION_BYTES
+    ) {
+      throw new Error("agenc: runtime artifact build provenance size is invalid");
+    }
+  }
 }
 
 export function validateRuntimeReleaseManifest(
@@ -289,6 +466,7 @@ export function validateRuntimeReleaseManifest(
   if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(manifest.runtimeVersion ?? "")) {
     throw new Error("agenc: runtime manifest has an invalid runtimeVersion");
   }
+  requireSupportedRuntimeVersion(manifest.runtimeVersion);
   if (manifest.releaseTag !== `agenc-v${manifest.runtimeVersion}`) {
     throw new Error("agenc: runtime manifest releaseTag does not match runtimeVersion");
   }
@@ -345,7 +523,14 @@ export function validateRuntimeReleaseManifest(
       !Number.isSafeInteger(artifact.bytes) ||
       artifact.bytes <= 0 ||
       artifact.bytes > MAX_RUNTIME_ARTIFACT_BYTES ||
-      artifact.bins?.agenc !== "node_modules/@tetsuo-ai/runtime/bin/agenc"
+      artifact.bins?.agenc !== "node_modules/@tetsuo-ai/runtime/bin/agenc" ||
+      (
+        manifest.runtimeVersion !== FROZEN_LEGACY_RUNTIME_VERSION &&
+        (
+          artifact.bins?.node !== canonicalRuntimeNodeBin(artifact.platform) ||
+          artifact.bins?.nodeLibrary !== canonicalRuntimeNodeLibrary(artifact.platform)
+        )
+      )
     ) {
       throw new Error(`agenc: runtime manifest artifact identity is invalid (${identity})`);
     }
@@ -372,6 +557,15 @@ export function validateRuntimeReleaseManifest(
     ) {
       throw new Error("agenc: runtime manifest build provenance is invalid");
     }
+    validateRuntimeReleaseCandidateIdentity(
+      build.releaseCandidate,
+      build.sourceCommit,
+      {
+        required:
+          trustMode === "official" &&
+          runtimeVersionRequiresDualProvenance(manifest.runtimeVersion),
+      },
+    );
     for (const artifact of manifest.artifacts) {
       if (
         artifact.nodeMajor !== build.nodeMajor ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tetsuo-ai/agenc",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "description": "Public AgenC CLI launcher package",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
     "lib/activation-lock-identity.mjs",
     "lib/generated-wrapper.d.mts",
     "lib/generated-wrapper.mjs",
+    "lib/runtime-archive.d.mts",
     "lib/runtime-archive.mjs",
     "lib/runtime-compatibility.mjs",
     "lib/runtime-manager.mjs",
@@ -47,6 +48,6 @@
     "@tetsuo-ai/runtime": "file:../../runtime"
   },
   "engines": {
-    "node": ">=25.9.0 <26.0.0"
+    "node": ">=26.5.0 <27.0.0"
   }
 }

package/src/launcher.mjs

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const DEFAULT_READY_TIMEOUT_MS = 2000;
@@ -74,11 +75,17 @@ export function isDaemonCommand(argv) {
 export function resolveRuntimeBin(requireFn = requireFromLauncher) {
   try {
     const runtimeEntry = requireFn.resolve("@tetsuo-ai/runtime");
+    const runtimeRoot = realpathSync(resolve(dirname(runtimeEntry), ".."));
+    const repositoryRuntimeRoot = realpathSync(
+      resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "runtime"),
+    );
+    if (runtimeRoot !== repositoryRuntimeRoot) return null;
     return resolve(dirname(runtimeEntry), "../bin/agenc");
   } catch (error) {
     if (
       error?.code === "MODULE_NOT_FOUND" ||
-      error?.code === "ERR_MODULE_NOT_FOUND"
+      error?.code === "ERR_MODULE_NOT_FOUND" ||
+      error?.code === "ENOENT"
     ) {
       return null;
     }
@@ -86,8 +93,41 @@ export function resolveRuntimeBin(requireFn = requireFromLauncher) {
   }
 }
 
-// Resolve the runtime entry for either mode: prefer the dev file:-link, else
-// ensure (download + verify + extract) the published per-platform runtime.
+function hostRuntimeLaunch(runtimeBin) {
+  return { runtimeBin, nodeBin: process.execPath };
+}
+
+function requireRuntimeLaunch(value) {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    typeof value.runtimeBin !== "string" ||
+    typeof value.nodeBin !== "string" ||
+    (
+      value.nodeLibraryPath !== undefined &&
+      typeof value.nodeLibraryPath !== "string"
+    )
+  ) {
+    throw new Error("agenc: runtime manager returned an invalid launch contract");
+  }
+  return value;
+}
+
+// Resolve every path needed to execute the runtime. Development file: links
+// intentionally use the current Node process; published artifacts always
+// return their embedded Node (and the Linux compatibility-library directory).
+export async function resolveRuntimeLaunchAsync({
+  requireFn = requireFromLauncher,
+  ensureFn,
+} = {}) {
+  const dev = resolveRuntimeBin(requireFn);
+  if (dev !== null) return hostRuntimeLaunch(dev);
+  const ensureRuntimeLaunch =
+    ensureFn ?? (await import("../lib/runtime-manager.mjs")).ensureRuntimeLaunch;
+  return requireRuntimeLaunch(await ensureRuntimeLaunch());
+}
+
+// Retained for callers that only need the script path.
 export async function resolveRuntimeBinAsync({
   requireFn = requireFromLauncher,
   ensureFn,
@@ -96,7 +136,10 @@ export async function resolveRuntimeBinAsync({
   if (dev !== null) return dev;
   const ensureRuntime =
     ensureFn ?? (await import("../lib/runtime-manager.mjs")).ensureRuntime;
-  return ensureRuntime();
+  const ensured = await ensureRuntime();
+  return typeof ensured === "string"
+    ? ensured
+    : requireRuntimeLaunch(ensured).runtimeBin;
 }
 
 export async function spawnNodeScript(
@@ -107,12 +150,27 @@ export async function spawnNodeScript(
     cwd = process.cwd(),
     stdio = "inherit",
     spawnFn = spawn,
+    nodeBin = process.execPath,
+    nodeLibraryPath,
   } = {},
 ) {
+  const childEnv = { ...env };
+  const pathKey =
+    Object.keys(childEnv).find((key) => key.toLowerCase() === "path") ?? "PATH";
+  const nodeDir = dirname(nodeBin);
+  childEnv[pathKey] = childEnv[pathKey]
+    ? `${nodeDir}${delimiter}${childEnv[pathKey]}`
+    : nodeDir;
+  if (nodeLibraryPath !== undefined) {
+    // The embedded Linux Node requires the artifact's pinned libatomic. Do not
+    // search an operator-controlled ambient library path before that exact
+    // directory.
+    childEnv.LD_LIBRARY_PATH = nodeLibraryPath;
+  }
   return new Promise((resolveExit, reject) => {
-    const child = spawnFn(process.execPath, [scriptPath, ...args], {
+    const child = spawnFn(nodeBin, [scriptPath, ...args], {
       cwd,
-      env,
+      env: childEnv,
       stdio,
     });
     child.once("error", reject);
@@ -174,6 +232,8 @@ export async function ensureDaemonForLaunch({
   env = process.env,
   cwd = process.cwd(),
   runtimeBin = resolveRuntimeBin(),
+  runtimeNodeBin = process.execPath,
+  runtimeNodeLibraryPath,
   userHome = homedir(),
   readText = readFile,
   signalPid = process.kill,
@@ -197,7 +257,12 @@ export async function ensureDaemonForLaunch({
     return { status: "already-running" };
   }
 
-  await spawnDaemonFn(runtimeBin, { env, cwd });
+  await spawnDaemonFn(runtimeBin, {
+    env,
+    cwd,
+    nodeBin: runtimeNodeBin,
+    nodeLibraryPath: runtimeNodeLibraryPath,
+  });
   const ready = await waitForReadyFn({ env, userHome, readText, signalPid });
   if (!ready) {
     throw new Error("AgenC daemon did not become ready before timeout");
@@ -210,16 +275,29 @@ export async function main(
   {
     env = process.env,
     cwd = process.cwd(),
+    runtimeLaunch,
     runtimeBin,
+    runtimeNodeBin = process.execPath,
+    runtimeNodeLibraryPath,
     userHome = homedir(),
   } = {},
 ) {
   // Resolve (and, in a published install, download + verify) the runtime before
   // anything tries to spawn it. Sync default is avoided: it returns null when
   // runtime isn't an npm dep, which is the normal published case.
-  let resolvedBin = runtimeBin;
+  let resolvedLaunch = runtimeLaunch ??
+    (runtimeBin === undefined
+      ? undefined
+      : {
+          runtimeBin,
+          nodeBin: runtimeNodeBin,
+          ...(runtimeNodeLibraryPath === undefined
+            ? {}
+            : { nodeLibraryPath: runtimeNodeLibraryPath }),
+        });
   try {
-    resolvedBin ??= await resolveRuntimeBinAsync();
+    resolvedLaunch ??= await resolveRuntimeLaunchAsync();
+    resolvedLaunch = requireRuntimeLaunch(resolvedLaunch);
   } catch (error) {
     process.stderr.write(
       `agenc: could not obtain runtime: ${
@@ -229,7 +307,15 @@ export async function main(
     return 1;
   }
   try {
-    await ensureDaemonForLaunch({ argv, env, cwd, runtimeBin: resolvedBin, userHome });
+    await ensureDaemonForLaunch({
+      argv,
+      env,
+      cwd,
+      runtimeBin: resolvedLaunch.runtimeBin,
+      runtimeNodeBin: resolvedLaunch.nodeBin,
+      runtimeNodeLibraryPath: resolvedLaunch.nodeLibraryPath,
+      userHome,
+    });
   } catch (error) {
     // The launcher is transport, not policy: a daemon that cannot start must
     // not block daemon-independent commands. `agenc update` is the canonical
@@ -245,7 +331,13 @@ export async function main(
         "agenc: continuing without the daemon; commands that require it will report the failure\n",
     );
   }
-  return spawnNodeScript(resolvedBin, argv, { env, cwd, stdio: "inherit" });
+  return spawnNodeScript(resolvedLaunch.runtimeBin, argv, {
+    env,
+    cwd,
+    stdio: "inherit",
+    nodeBin: resolvedLaunch.nodeBin,
+    nodeLibraryPath: resolvedLaunch.nodeLibraryPath,
+  });
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {