@nanobpm/nano-workforce 0.205.2 → 0.206.1

package/app/version.ts

@@ -5,8 +5,10 @@
 // inspecting the working tree at runtime. This module gathers that identity — the app's package
 // version, the resolved `@nanobpm/urban` version, the git commit (read from `.git`, handling both
 // an ordinary `.git` directory and the `gitdir:` file pointer used by worktrees/submodules, with
-// an env override for detached deploys), plus the Node runtime, pid and start time — so an operator
-// debugging a stuck instance can confirm the process is on the code they think it is.
+// an env override for detached deploys AND a `build-info.json` fallback baked into the release
+// package — an npm install has neither `.git` nor the env var, issue #925), plus the Node runtime,
+// pid and start time — so an operator debugging a stuck instance can confirm the process is on the
+// code they think it is.
 //
 // Every probe is best-effort: a missing file or unavailable `.git` yields `null` for that field
 // rather than throwing, so `/app/api/version` never fails just because one source is absent.
@@ -98,17 +100,68 @@ function urbanVersion(): string | null {
   return typeof pkg?.version === "string" ? pkg.version : null;
 }
 
+/**
+ * The build identity baked into the release package (`build-info.json` at the package root) by
+ * `scripts/write-build-info.ts` during semantic-release's `prepare` step (issue #925). An npm
+ * install ships this file but no `.git`, so it is the ONLY source of `gitSha` there. Its `gitSha`
+ * is the SOURCE HEAD the release was cut from (the tag commit does not exist yet at prepare time);
+ * its `gitTag` names the tag placed on the release commit, whose tree matches that source HEAD
+ * except for the version-bump metadata. Returns null on a dev checkout, which has no such file.
+ */
+export const SHA_RE = /^[0-9a-f]{40}$/;
+
+/** Validate a parsed build-info payload; returns a list of problems (empty = valid). The single
+ * validator shared by the writer (scripts/write-build-info.ts) and the reader below. */
+export function buildInfoProblems(info: unknown): string[] {
+  const problems: string[] = [];
+  if (typeof info !== "object" || info == null) return ["build-info.json is not a JSON object"];
+  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape (parsed JSON)
+  const bi = info as Record<string, unknown>;
+  if (typeof bi.version !== "string" || !bi.version.trim()) problems.push("version must be a non-blank string");
+  if (typeof bi.gitSha !== "string" || !SHA_RE.test(bi.gitSha)) problems.push("gitSha must be a 40-hex string");
+  if (typeof bi.gitTag !== "string" || !bi.gitTag.trim()) problems.push("gitTag must be a non-blank string");
+  if (typeof bi.builtAt !== "string" || Number.isNaN(Date.parse(bi.builtAt)))
+    problems.push("builtAt must be an ISO-8601 timestamp");
+  return problems;
+}
+
+
+function buildInfo(): { version: string; gitSha: string; gitTag: string; builtAt: string } | null {
+  const raw = readJson(join(REPO_ROOT, "build-info.json"));
+  if (raw == null) return null;
+  // Fail closed on ANY malformed field (bad SHA, unparseable builtAt, blank tag/version): a corrupt
+  // or tampered build-info.json is ignored wholesale rather than partially surfaced. Uses the SAME
+  // validator the writer's --check uses, so reader and writer can never drift.
+  if (buildInfoProblems(raw).length > 0) return null;
+  return {
+    version: String(raw.version),
+    gitSha: String(raw.gitSha),
+    gitTag: String(raw.gitTag),
+    builtAt: String(raw.builtAt),
+  };
+}
+
 /**
  * The git commit the working tree is on, read straight from `.git` so it reflects the ACTUAL
  * checked-out code — not a value baked at some earlier build. Resolves a symbolic `HEAD`
  * (`ref: refs/heads/…`) via the loose ref file (checking both the per-worktree and common dirs),
- * falling back to `packed-refs`. An explicit `NANO_WORKFORCE_GIT_SHA` env var wins (for deploys
- * that ship without a `.git` directory).
+ * falling back to `packed-refs`. Resolution order (issue #925): an explicit
+ * `NANO_WORKFORCE_GIT_SHA` env var wins (for deploys that ship without a `.git` directory), then
+ * the live `.git` checkout, then the release-baked `build-info.json` (the only source available to
+ * an npm-installed instance).
  */
 function gitSha(): string | null {
   const env = envVar("NANO_WORKFORCE_GIT_SHA");
   if (env) return env;
 
+  const fromCheckout = gitShaFromCheckout();
+  if (fromCheckout != null) return fromCheckout;
+
+  return buildInfo()?.gitSha ?? null;
+}
+
+/** The commit SHA read from the live `.git` checkout, or null when there is none (npm install). */
+function gitShaFromCheckout(): string | null {
   const dirs = resolveGitDirs();
   if (dirs == null) return null;
   const head = readText(join(dirs.gitDir, "HEAD"));
@@ -160,6 +213,10 @@ export interface VersionInfo {
   urbanVersion: string | null;
   gitSha: string | null;
   gitBranch: string | null;
+  /** The release tag (e.g. "v0.206.0") from the baked `build-info.json`; null on a dev checkout. */
+  gitTag: string | null;
+  /** ISO-8601 time the release package was built (from `build-info.json`); null on a dev checkout. */
+  builtAt: string | null;
   runtime: string;
   pid: number | null;
   startedAt: string;
@@ -172,12 +229,15 @@ export interface VersionInfo {
  */
 const STATIC: Omit<VersionInfo, "uptimeSeconds"> = (() => {
   const pkg = appPackage();
+  const build = buildInfo();
   return Object.freeze({
     name: appName(pkg),
     version: appVersion(pkg),
     urbanVersion: urbanVersion(),
     gitSha: gitSha(),
     gitBranch: gitBranch(),
+    gitTag: build?.gitTag || null,
+    builtAt: build?.builtAt || null,
     runtime: runtime(),
     pid: typeof process.pid === "number" ? process.pid : null,
     startedAt: STARTED_AT.toISOString(),

package/build-info.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.206.1",
+  "gitSha": "973c161d8b279db21915601647c5e8c43f3cac2f",
+  "gitTag": "v0.206.1",
+  "builtAt": "2026-11-08T20:26:54.809Z"
+}

package/docs/agent-guide.md

@@ -26,6 +26,11 @@ curl -sS __BASE__/version | jq   # tool: getVersion: app/urban version, git sha,
 curl -sS __BASE__/status  | jq   # tool: listActivePrs: every PR in flight
 ```
 
+`/status` also carries the running app's build identity as a top-level `version` object
+(`{ version, gitSha }`, the same source as `/version` — env override, then the live `.git`
+checkout, then the release-baked `build-info.json` an npm install ships), so the endpoint
+everyone polls answers "is the fix live?" in one call.
+
 Each `/status` entry carries `prKey` (`owner/repo#123`), `status`, `round`, `processKey`
 (the **engine process-instance key**, the bridge to §5), `openEscalation`,
 `activeWorker`/`leaseUntil` (an agent holds the round, or the job is just queued), and

package/openapi.yaml

@@ -195,6 +195,7 @@ components:
         - count
         - prs
         - deliveries
+        - version
       properties:
         count:
           type: integer
@@ -209,6 +210,26 @@ components:
             first (issue #889 §1 — the opt-in is shown for each PR AND each delivery).
           items:
             $ref: "#/components/schemas/ActiveDelivery"
+        version:
+          type: object
+          additionalProperties: false
+          required:
+            - version
+            - gitSha
+          description: >-
+            The running app's build identity (issue #925), derived from the same app/version.ts
+            getter as GET /version — so the endpoint everyone polls answers "is the fix live?" in
+            one call. gitSha resolves from NANO_WORKFORCE_GIT_SHA, then the .git checkout, then the
+            release-baked build-info.json (the only source an npm install has).
+          properties:
+            version:
+              type: string
+              nullable: true
+              description: The app's package version.
+            gitSha:
+              type: string
+              nullable: true
+              description: The commit the instance runs; null only when no source (env, .git, build-info.json) knows it.
     ActiveDelivery:
       type: object
       description: A delivery-graph run currently in flight, as reported by the status endpoint.
@@ -1561,6 +1582,8 @@ components:
         - urbanVersion
         - gitSha
         - gitBranch
+        - gitTag
+        - builtAt
         - runtime
         - pid
         - startedAt
@@ -1577,9 +1600,24 @@ components:
         gitSha:
           type: string
           nullable: true
+          description: >-
+            The commit the instance runs. Resolution order (issue #925): NANO_WORKFORCE_GIT_SHA env,
+            then the live .git checkout, then the release-baked build-info.json (the only source an
+            npm install has — this is the source HEAD the release was cut from).
         gitBranch:
           type: string
           nullable: true
+        gitTag:
+          type: string
+          nullable: true
+          description: >-
+            The release tag (e.g. "v0.206.0") naming the release commit, from the baked
+            build-info.json; null on a dev checkout. The tag commit's tree matches gitSha's tree
+            except for the version-bump metadata.
+        builtAt:
+          type: string
+          nullable: true
+          description: ISO-8601 time the release package was built (from build-info.json); null on a dev checkout.
         runtime:
           type: string
         pid:

package/operations/getVersion.test.ts

@@ -34,6 +34,9 @@ test("returns 200 with the app identity", async () => {
   assert("urbanVersion" in r.body);
   assert("gitSha" in r.body);
   assert("gitBranch" in r.body);
+  // Release-baked identity fields (issue #925): always present, null on a dev checkout.
+  assert("gitTag" in r.body);
+  assert("builtAt" in r.body);
   assert(typeof r.body.runtime === "string" && r.body.runtime.length > 0);
   assert(typeof r.body.startedAt === "string");
   assert(typeof r.body.uptimeSeconds === "number");

package/operations/listActivePrs.test.ts

@@ -66,6 +66,21 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
+test("carries the running app's identity as a top-level version object (issue #925)", async () => {
+  // `/status` is the endpoint everyone polls, so it must answer "is the fix live?" on its own:
+  // version.version + version.gitSha, derived from the SAME app/version.ts getter /version uses.
+  const app = memApp([]);
+  const res = (await handler(input(), app)) as any;
+  assertEquals(res.status, 200);
+  assert("version" in res.body, "the status payload carries a top-level version object");
+  assert("version" in res.body.version, "version.version is present (string|null)");
+  assert("gitSha" in res.body.version, "version.gitSha is present (string|null)");
+  const { buildVersionInfo } = await import("../app/version.ts");
+  const identity = buildVersionInfo();
+  assertEquals(res.body.version.version, identity.version, "derived from the app/version.ts getter, not re-read");
+  assertEquals(res.body.version.gitSha, identity.gitSha, "derived from the app/version.ts getter, not re-read");
+});
+
 test("surfaces the structured openEscalation from the user_tasks read model (both loops)", async () => {
   // Issue #666: openEscalation is derived from the ONE `user_tasks` read model (the same surface
   // `listEscalations` and the Convergence page consume), so `/status` carries the completable

package/operations/listActivePrs.ts

@@ -8,7 +8,7 @@
 // callers must present it via the x-hook-secret header. Unset → open (unchanged default).
 
 import { activeDeliveries, activePrs } from "../app/service.ts";
-import { envVar } from "../app/version.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
@@ -21,5 +21,8 @@ export default defineOperation("listActivePrs", async ({ req }, app) => {
     return { status: 401, body: { error: "unauthorized" } };
   }
   const [prs, deliveries] = await Promise.all([activePrs(app.data, app.engine), activeDeliveries(app.data)]);
-  return { status: 200, body: { count: prs.length, prs, deliveries } };
+  // The running app's identity, derived from the SAME app/version.ts getter /version uses (never
+  // re-read), so the endpoint everyone polls answers "is the fix live?" in one call (issue #925).
+  const { version, gitSha } = buildVersionInfo();
+  return { status: 200, body: { count: prs.length, prs, deliveries, version: { version, gitSha } } };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.205.2",
+  "version": "0.206.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -74,6 +74,7 @@
     "@nanobpm/urban-testkit": "^1.6.0",
     "@nanobpm/workflow": "^0.15.0",
     "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",
     "@semantic-release/npm": "^13.1.5",
     "@types/node": "^24.0.0",

package/scripts/write-build-info.test.ts

@@ -0,0 +1,87 @@
+// Tests for scripts/write-build-info.ts — the release-time bake of `build-info.json` (issue #925).
+//
+// The acceptance criterion is end-to-end: an `npm pack` of a tree whose build-info.json was written
+// by this script CONTAINS the file, with a 40-hex gitSha — i.e. the published tarball carries the
+// identity an npm-installed instance falls back to. Plus unit coverage of the payload the script
+// composes (source-HEAD sha, `v<version>` tag, ISO builtAt) and its validation.
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { buildInfoProblems, composeBuildInfo } from "./write-build-info.ts";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const BUILD_INFO = join(REPO_ROOT, "build-info.json");
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+test("composeBuildInfo records the checkout HEAD (40-hex), the v<version> tag, and an ISO builtAt", () => {
+  const head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" }).trim();
+  const info = composeBuildInfo("1.2.3", new Date("2026-01-02T03:04:05.000Z"));
+  assertEquals(info.gitSha, head);
+  assert(SHA_RE.test(info.gitSha));
+  assertEquals(info.gitTag, "v1.2.3");
+  assertEquals(info.builtAt, "2026-01-02T03:04:05.000Z");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo honours an explicit source SHA instead of the checkout HEAD", () => {
+  // The manual OIDC-recovery path checks out the release TAG, whose HEAD is the metadata-only
+  // release commit — so it passes the source HEAD explicitly. The explicit SHA must win over
+  // `git rev-parse HEAD` and must be validated against the 40-hex contract.
+  const sourceHead = "b".repeat(40);
+  const info = composeBuildInfo("2.0.0", new Date("2026-01-02T03:04:05.000Z"), sourceHead);
+  assertEquals(info.gitSha, sourceHead);
+  assertEquals(info.gitTag, "v2.0.0");
+  assertEquals(buildInfoProblems(info), []);
+});
+
+test("composeBuildInfo rejects a malformed explicit source SHA (fail closed)", () => {
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "not-a-sha"), Error, "non-SHA");
+  assertThrows(() => composeBuildInfo("2.0.0", new Date(), "abc123"), Error, "non-SHA");
+});
+
+test("buildInfoProblems rejects malformed payloads", () => {
+  assert(buildInfoProblems(null).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "not-a-sha", gitTag: "v1.0.0", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "", builtAt: "2026-01-02T03:04:05.000Z" }).length > 0);
+  assert(buildInfoProblems({ version: "1.0.0", gitSha: "a".repeat(40), gitTag: "v1.0.0", builtAt: "not-a-date" }).length > 0);
+});
+
+test("an npm pack of the package contains build-info.json with a 40-hex SHA", () => {
+  // Write the file exactly as the release pipeline does (prepare step), pack, inspect, then clean
+  // up — build-info.json is a build artifact and MUST NOT be committed (a stale committed copy
+  // would mislabel every later dev checkout), so the test restores the prior state in `finally`.
+  const prior = (() => {
+    try {
+      return readFileSync(BUILD_INFO, "utf8");
+    } catch {
+      return null;
+    }
+  })();
+  const packDir = mkdtempSync(join(tmpdir(), "nwf-pack-"));
+  try {
+    execFileSync("node", ["--experimental-strip-types", "scripts/write-build-info.ts", "0.0.0-packtest"], {
+      cwd: REPO_ROOT,
+      stdio: "pipe",
+    });
+    const out = execFileSync("npm", ["pack", "--pack-destination", packDir], { cwd: REPO_ROOT, encoding: "utf8" });
+    const tarball = join(packDir, out.trim().split("\n").pop() ?? "");
+    const listing = execFileSync("tar", ["-tzf", tarball], { encoding: "utf8" });
+    assert(
+      listing.split("\n").some((f) => f === "package/build-info.json" || f === "build-info.json"),
+      `the tarball must contain build-info.json; got:\n${listing.split("\n").slice(0, 5).join("\n")}…`,
+    );
+    const raw = execFileSync("tar", ["-xzOf", tarball, "package/build-info.json"], { encoding: "utf8" });
+    const packed: unknown = JSON.parse(raw);
+    assertEquals(buildInfoProblems(packed), [], `packed build-info.json must be well-formed: ${raw}`);
+    const gitSha = (packed as { gitSha: string }).gitSha;
+    assert(SHA_RE.test(gitSha), `packed gitSha must be 40-hex, got ${gitSha}`);
+  } finally {
+    if (prior == null) rmSync(BUILD_INFO, { force: true });
+    else writeFileSync(BUILD_INFO, prior);
+    rmSync(packDir, { recursive: true, force: true });
+  }
+});

package/scripts/write-build-info.ts

@@ -0,0 +1,126 @@
+// write-build-info — bake the release's build identity into `build-info.json` at the package root
+// (issue #925).
+//
+// WHY: an npm-installed instance has no `.git` directory and no `NANO_WORKFORCE_GIT_SHA` env var,
+// so `app/version.ts` reported `gitSha: null` on exactly the deploys an operator most needs to
+// identify ("is the fix live on merlin?"). The release pipeline writes this file during
+// semantic-release's `prepare` step — AFTER @semantic-release/npm bumps `package.json` to the
+// release version and BEFORE it packs/publishes the tarball — so every published package carries
+// its own identity and `app/version.ts` can fall back to it (env → .git → build-info.json).
+//
+// WHAT IT RECORDS (and why): `gitSha` is the SOURCE HEAD the release was cut from
+// (`git rev-parse HEAD` in the release checkout), NOT the `chore(release): X.Y.Z` commit
+// @semantic-release/git creates afterwards — that commit does not exist yet at prepare time, so it
+// cannot be recorded here. The release TAG `vX.Y.Z` is later placed on that release commit, whose
+// tree is identical to the source HEAD's tree except for the version-bump metadata (CHANGELOG.md,
+// package.json, package-lock.json). `gitTag` carries the tag name so an operator can resolve the
+// exact release commit (`git rev-list -1 <tag>`) when they need it; `gitSha` answers the
+// day-to-day question "which source code is running".
+//
+// USAGE:
+//   node --experimental-strip-types scripts/write-build-info.ts <version> [--sha <40-hex>]   # release pipeline
+//   node --experimental-strip-types scripts/write-build-info.ts --check                      # test: validate on disk
+//
+// `<version>` alone records the current checkout HEAD — correct at semantic-release `prepare` time.
+// The manual OIDC-recovery path runs from a fresh checkout of the release TAG, whose HEAD is the
+// metadata-only `chore(release)` commit, NOT the source HEAD; it passes `--sha "$(git rev-parse
+// v<version>^")"` so the recorded gitSha still names the source code (see release.yml's recovery
+// instructions).
+//
+// `--check` validates the committed/generated `build-info.json` (present, well-formed, 40-hex
+// gitSha) — used by the pack test to assert the release artifact contract without cutting a
+// release.
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const BUILD_INFO_PATH = join(REPO_ROOT, "build-info.json");
+
+export interface BuildInfo {
+  version: string;
+  gitSha: string;
+  gitTag: string;
+  builtAt: string;
+}
+
+// The ONE payload validator is shared with the reader (app/version.ts) so writer and reader can
+// never disagree on what a valid build-info.json is.
+export { buildInfoProblems } from "../app/version.ts";
+
+import { buildInfoProblems, SHA_RE } from "../app/version.ts";
+
+/**
+ * Compose the build-info payload for a release of `version`. `gitSha` is the SOURCE HEAD the
+ * release was cut from. By default it is read from the current checkout HEAD (`git rev-parse HEAD`)
+ * — correct at semantic-release `prepare` time, when HEAD is still the source commit. Callers that
+ * run LATER (the manual OIDC-recovery path, which checks out the release TAG) must pass `sha`
+ * explicitly as the source HEAD (`git rev-parse v<version>^`): by then HEAD is the metadata-only
+ * `chore(release)` commit, and recording it would mislabel the package with a commit whose only
+ * change is the version bump. An explicit `sha` is validated against the 40-hex contract.
+ */
+export function composeBuildInfo(version: string, now: Date = new Date(), sha?: string): BuildInfo {
+  const gitSha = (
+    sha ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd: REPO_ROOT, encoding: "utf8" })
+  ).trim();
+  if (!SHA_RE.test(gitSha)) throw new Error(`git rev-parse HEAD returned a non-SHA: ${JSON.stringify(gitSha)}`);
+  return {
+    version,
+    gitSha,
+    // The tag semantic-release will place on the release commit for this version.
+    gitTag: `v${version}`,
+    builtAt: now.toISOString(),
+  };
+}
+
+function main(argv: string[]): void {
+  const arg = argv[2];
+  if (arg === "--check") {
+    // Lazy import so the write path never needs fs/readFileSync beyond writeFileSync.
+    import("node:fs").then(({ readFileSync }) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(BUILD_INFO_PATH, "utf8"));
+      } catch (err) {
+        // biome-ignore lint/plugin: narrowing a caught unknown to Error for its message
+        console.error(`build-info.json is missing or invalid JSON: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      const problems = buildInfoProblems(parsed);
+      if (problems.length > 0) {
+        console.error(`build-info.json failed validation:\n - ${problems.join("\n - ")}`);
+        process.exit(1);
+      }
+      console.log(`build-info.json OK: ${JSON.stringify(parsed)}`);
+    });
+    return;
+  }
+  const version = arg?.trim();
+  if (!version) {
+    console.error("usage: write-build-info.ts <version> [--sha <40-hex>] | --check");
+    process.exit(1);
+  }
+  // Optional explicit source SHA (see composeBuildInfo). The manual OIDC-recovery path checks out
+  // the release TAG, whose HEAD is the release commit — so it passes the source HEAD
+  // (`git rev-parse v<version>^`) explicitly to keep gitSha pointing at the source code.
+  let sha: string | undefined;
+  const shaIdx = argv.indexOf("--sha");
+  if (shaIdx !== -1) {
+    sha = argv[shaIdx + 1]?.trim();
+    if (!sha || !SHA_RE.test(sha)) {
+      console.error(`--sha must be a 40-hex commit SHA, got ${JSON.stringify(argv[shaIdx + 1])}`);
+      process.exit(1);
+    }
+  }
+  const info = composeBuildInfo(version, new Date(), sha);
+  writeFileSync(BUILD_INFO_PATH, `${JSON.stringify(info, null, 2)}\n`);
+  console.log(`wrote build-info.json: version=${info.version} gitSha=${info.gitSha} gitTag=${info.gitTag}`);
+}
+
+// Run the CLI only when executed directly — importing this module (e.g. from the test) must not
+// parse argv or write files.
+const invokedAs = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (invokedAs === import.meta.url) {
+  main(process.argv);
+}