@elizaos/app-core 2.0.3-beta.2 → 2.0.3-beta.3

package/scripts/lib/renderer-build-manifest.mjs

@@ -0,0 +1,257 @@
+/**
+ * Renderer build manifest — the deterministic "build stamp" for the web/renderer
+ * bundle that every on-device artifact must carry.
+ *
+ * Issue #9309: the recurring on-device failure mode is a device booting STALE UI
+ * because a build step copied a cached `dist/` instead of the freshly built one.
+ * There was no machine-checkable identity for "which renderer is this", so a
+ * stale copy shipped silently.
+ *
+ * This module gives the renderer a content-derived identity:
+ *   - The vite `renderer-build-manifest` plugin writes `eliza-renderer-build.json`
+ *     into `dist/` at the end of EVERY renderer build (mobile, desktop, web).
+ *   - The file is copied into the device artifact alongside the bundle (cap sync
+ *     copies the whole webDir; desktop's Electrobun copy carries dist/), so it
+ *     ships on-device as an asserted build stamp.
+ *   - The platform orchestrators call `assertStagedRendererMatchesBuild()` after
+ *     staging so a stale/missing/partial renderer FAILS THE BUILD LOUDLY instead
+ *     of shipping old code.
+ *
+ * `buildId` is a sha256 over `index.html` + the sorted set of emitted asset
+ * file names (vite embeds each asset's content hash in its name) and their
+ * sizes. Two different source states therefore produce two different buildIds,
+ * which is exactly the freshness signal the issue asks for ("a real freshness
+ * check that fails the build when an input changed but the artifact didn't").
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const RENDERER_BUILD_MANIFEST_FILENAME = "eliza-renderer-build.json";
+export const RENDERER_BUILD_MANIFEST_SCHEMA = "elizaos.renderer.build/v1";
+
+function sha256(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+/**
+ * Deterministic content fingerprint of a built renderer directory.
+ * @param {string} distDir absolute path to the built renderer dir (has index.html)
+ * @returns {{ buildId: string, indexHtmlSha256: string, assetCount: number }}
+ */
+export function computeRendererFingerprint(distDir) {
+  const indexPath = path.join(distDir, "index.html");
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(
+      `[renderer-build-manifest] no index.html in ${distDir} — not a built renderer.`,
+    );
+  }
+  const indexHtmlSha256 = sha256(fs.readFileSync(indexPath));
+
+  const assetEntries = [];
+  const assetsDir = path.join(distDir, "assets");
+  if (fs.existsSync(assetsDir)) {
+    const walk = (dir, rel) => {
+      for (const name of fs.readdirSync(dir).sort()) {
+        const full = path.join(dir, name);
+        const relName = rel ? `${rel}/${name}` : name;
+        const stat = fs.statSync(full);
+        if (stat.isDirectory()) {
+          walk(full, relName);
+        } else {
+          assetEntries.push(`${relName}:${stat.size}`);
+        }
+      }
+    };
+    walk(assetsDir, "");
+  }
+  assetEntries.sort();
+  const buildId = sha256(`${indexHtmlSha256}\n${assetEntries.join("\n")}`);
+  return { buildId, indexHtmlSha256, assetCount: assetEntries.length };
+}
+
+/**
+ * Build the manifest object for a renderer dir (does not write it).
+ * @param {string} distDir
+ * @param {{ builtAt?: string, commit?: string|null, variant?: string|null,
+ *           capacitorTarget?: string|null, runtimeMode?: string|null }} [meta]
+ */
+export function buildRendererManifest(distDir, meta = {}) {
+  const fingerprint = computeRendererFingerprint(distDir);
+  return {
+    schema: RENDERER_BUILD_MANIFEST_SCHEMA,
+    buildId: fingerprint.buildId,
+    indexHtmlSha256: fingerprint.indexHtmlSha256,
+    assetCount: fingerprint.assetCount,
+    builtAt: meta.builtAt ?? new Date().toISOString(),
+    commit: meta.commit ?? null,
+    variant: meta.variant ?? null,
+    capacitorTarget: meta.capacitorTarget ?? null,
+    runtimeMode: meta.runtimeMode ?? null,
+  };
+}
+
+/**
+ * Write `eliza-renderer-build.json` into a built renderer dir. Returns manifest.
+ * @param {string} distDir
+ * @param {object} [meta]
+ */
+export function writeRendererBuildManifest(distDir, meta = {}) {
+  const manifest = buildRendererManifest(distDir, meta);
+  fs.writeFileSync(
+    path.join(distDir, RENDERER_BUILD_MANIFEST_FILENAME),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+  return manifest;
+}
+
+/**
+ * Read a renderer build manifest from a dir (the dir that holds index.html), or
+ * null if absent/unparseable.
+ * @param {string} dir
+ */
+export function readRendererBuildManifest(dir) {
+  const manifestPath = path.join(dir, RENDERER_BUILD_MANIFEST_FILENAME);
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assert a STAGED renderer directory carries exactly the renderer that was just
+ * built in `freshDistDir`. Throws loudly on any mismatch so a stale/missing/
+ * partial UI fails the build instead of shipping silently.
+ *
+ * @param {string} freshDistDir the just-built renderer (source of truth)
+ * @param {string} stagedDir    where it was staged for the device artifact
+ * @param {{ label?: string }} [opts]
+ * @returns the fresh manifest on success
+ */
+export function assertStagedRendererMatchesBuild(
+  freshDistDir,
+  stagedDir,
+  { label = "renderer" } = {},
+) {
+  const fresh = readRendererBuildManifest(freshDistDir);
+  if (!fresh) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: the freshly built renderer in ${freshDistDir} ` +
+        `has no ${RENDERER_BUILD_MANIFEST_FILENAME}. The renderer-build-manifest vite plugin ` +
+        `did not run — refusing to ship an unverifiable bundle.`,
+    );
+  }
+  const staged = readRendererBuildManifest(stagedDir);
+  if (!staged) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: staged renderer at ${stagedDir} has no ` +
+        `${RENDERER_BUILD_MANIFEST_FILENAME}. Capacitor sync / staging did not copy the freshly ` +
+        `built bundle — the device would boot stale or missing UI. Failing the build.`,
+    );
+  }
+  if (staged.buildId !== fresh.buildId) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: STALE RENDERER staged. ` +
+        `staged buildId=${staged.buildId} (built ${staged.builtAt}) != ` +
+        `freshly built buildId=${fresh.buildId} (built ${fresh.builtAt}). ` +
+        `The device would boot an OLD UI — failing the build instead of shipping it.`,
+    );
+  }
+  // A copied manifest paired with a partial/old index.html would pass the buildId
+  // check above; re-hash the staged index.html to defend against a torn copy.
+  const stagedIndex = path.join(stagedDir, "index.html");
+  if (!fs.existsSync(stagedIndex)) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: staged index.html missing in ${stagedDir}.`,
+    );
+  }
+  const stagedHtmlSha = sha256(fs.readFileSync(stagedIndex));
+  if (stagedHtmlSha !== fresh.indexHtmlSha256) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: staged index.html hash ${stagedHtmlSha} != ` +
+        `freshly built ${fresh.indexHtmlSha256} — partial or stale copy. Failing the build.`,
+    );
+  }
+  return fresh;
+}
+
+/**
+ * Stale-web guard: overlay the freshly built renderer onto a Capacitor `public`
+ * dir, then assert it matches. `cap sync` has been observed to leave a stale
+ * `public` (old hashed assets shipping an ancient UI). The fresh `dist` is the
+ * source of truth, so clear the hashed `assets/` and copy `dist` over `public`.
+ * Non-renderer payloads staged outside `dist` (e.g. `public/agent`, PGlite root
+ * extension assets) live outside `dist` and survive — only `public/assets` is
+ * cleared and cpSync never deletes existing non-dist files. Throws if the fresh
+ * renderer is missing or the staged result doesn't match (issue #9309).
+ *
+ * @param {string} freshDistDir the just-built renderer (source of truth)
+ * @param {string} targetPublicDir the Capacitor `public` dir to overlay
+ * @param {{ label?: string }} [opts]
+ * @returns the fresh manifest on success
+ */
+export function overlayFreshRendererIntoPublic(
+  freshDistDir,
+  targetPublicDir,
+  { label = "renderer" } = {},
+) {
+  if (!fs.existsSync(path.join(freshDistDir, "index.html"))) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: no freshly built renderer at ${freshDistDir} ` +
+        `(missing index.html). Refusing to stage a missing/stale UI.`,
+    );
+  }
+  fs.mkdirSync(targetPublicDir, { recursive: true });
+  fs.rmSync(path.join(targetPublicDir, "assets"), {
+    recursive: true,
+    force: true,
+  });
+  fs.cpSync(freshDistDir, targetPublicDir, { recursive: true });
+  return assertStagedRendererMatchesBuild(freshDistDir, targetPublicDir, {
+    label,
+  });
+}
+
+/**
+ * Assert a renderer manifest was (re)generated during THIS build invocation —
+ * i.e. it is not a stale leftover from a previous run. Used by the desktop build
+ * right after `vite build` to prove the renderer was actually rebuilt.
+ *
+ * @param {string} distDir
+ * @param {{ notBefore: number, expectVariant?: string|null, label?: string }} opts
+ *        notBefore: epoch ms captured immediately before the renderer build started
+ * @returns the manifest on success
+ */
+export function assertRendererRebuiltSince(
+  distDir,
+  { notBefore, expectVariant = null, label = "renderer" },
+) {
+  const manifest = readRendererBuildManifest(distDir);
+  if (!manifest) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: no ${RENDERER_BUILD_MANIFEST_FILENAME} in ${distDir} ` +
+        `after the renderer build. The build did not produce a verifiable renderer.`,
+    );
+  }
+  const builtAtMs = Date.parse(manifest.builtAt);
+  if (!Number.isFinite(builtAtMs) || builtAtMs < notBefore) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: renderer manifest is STALE. builtAt=${manifest.builtAt} ` +
+        `predates this build invocation (started ${new Date(notBefore).toISOString()}). ` +
+        `A cached/stale dist was reused instead of a fresh build — failing.`,
+    );
+  }
+  if (
+    expectVariant != null &&
+    manifest.variant != null &&
+    manifest.variant !== expectVariant
+  ) {
+    throw new Error(
+      `[renderer-build-manifest] ${label}: renderer built for variant '${manifest.variant}' ` +
+        `but this build targets '${expectVariant}'. A wrong-variant dist was reused — failing.`,
+    );
+  }
+  return manifest;
+}

package/scripts/lib/renderer-build-manifest.test.mts

@@ -0,0 +1,277 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+  assertRendererRebuiltSince,
+  assertStagedRendererMatchesBuild,
+  buildRendererManifest,
+  computeRendererFingerprint,
+  overlayFreshRendererIntoPublic,
+  RENDERER_BUILD_MANIFEST_FILENAME,
+  readRendererBuildManifest,
+  writeRendererBuildManifest,
+} from "./renderer-build-manifest.mjs";
+
+let tmp: string;
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "renderer-manifest-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+/**
+ * Build a minimal renderer dist dir: index.html + assets/<name>. Mirrors what
+ * `vite build` emits (content-hashed asset names + an index.html referencing them).
+ */
+function makeDist(
+  dir: string,
+  {
+    indexHtml = "<!doctype html><html><body><div id=root></div></body></html>",
+    assets = { "index-abc123.js": "console.log(1)" },
+  }: { indexHtml?: string; assets?: Record<string, string> } = {},
+) {
+  fs.mkdirSync(path.join(dir, "assets"), { recursive: true });
+  fs.writeFileSync(path.join(dir, "index.html"), indexHtml);
+  for (const [name, body] of Object.entries(assets)) {
+    fs.writeFileSync(path.join(dir, "assets", name), body);
+  }
+}
+
+describe("computeRendererFingerprint", () => {
+  it("is deterministic for identical content", () => {
+    const a = path.join(tmp, "a");
+    const b = path.join(tmp, "b");
+    makeDist(a);
+    makeDist(b);
+    expect(computeRendererFingerprint(a).buildId).toBe(
+      computeRendererFingerprint(b).buildId,
+    );
+  });
+
+  it("changes when index.html changes", () => {
+    const a = path.join(tmp, "a");
+    const b = path.join(tmp, "b");
+    makeDist(a);
+    makeDist(b, {
+      indexHtml: "<!doctype html><html><body>changed</body></html>",
+    });
+    expect(computeRendererFingerprint(a).buildId).not.toBe(
+      computeRendererFingerprint(b).buildId,
+    );
+  });
+
+  it("changes when an asset is added or renamed (new content hash)", () => {
+    const a = path.join(tmp, "a");
+    const b = path.join(tmp, "b");
+    makeDist(a, { assets: { "index-abc123.js": "x" } });
+    makeDist(b, { assets: { "index-def456.js": "x" } });
+    expect(computeRendererFingerprint(a).buildId).not.toBe(
+      computeRendererFingerprint(b).buildId,
+    );
+  });
+
+  it("throws when index.html is missing", () => {
+    const a = path.join(tmp, "a");
+    fs.mkdirSync(a, { recursive: true });
+    expect(() => computeRendererFingerprint(a)).toThrow(/not a built renderer/);
+  });
+});
+
+describe("writeRendererBuildManifest / readRendererBuildManifest", () => {
+  it("round-trips and records metadata", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    const written = writeRendererBuildManifest(dist, {
+      builtAt: "2026-01-01T00:00:00.000Z",
+      commit: "deadbeef",
+      variant: "store",
+      capacitorTarget: "ios",
+    });
+    expect(
+      fs.existsSync(path.join(dist, RENDERER_BUILD_MANIFEST_FILENAME)),
+    ).toBe(true);
+    const read = readRendererBuildManifest(dist);
+    expect(read).toEqual(written);
+    expect(read?.variant).toBe("store");
+    expect(read?.capacitorTarget).toBe("ios");
+    expect(read?.buildId).toBe(computeRendererFingerprint(dist).buildId);
+  });
+
+  it("returns null when no manifest is present", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    expect(readRendererBuildManifest(dist)).toBeNull();
+  });
+});
+
+describe("assertStagedRendererMatchesBuild", () => {
+  it("passes when the staged renderer is a faithful copy of the build", () => {
+    const dist = path.join(tmp, "dist");
+    const staged = path.join(tmp, "public");
+    makeDist(dist);
+    writeRendererBuildManifest(dist);
+    fs.cpSync(dist, staged, { recursive: true });
+    expect(() => assertStagedRendererMatchesBuild(dist, staged)).not.toThrow();
+  });
+
+  it("fails when the fresh build has no manifest", () => {
+    const dist = path.join(tmp, "dist");
+    const staged = path.join(tmp, "public");
+    makeDist(dist);
+    fs.cpSync(dist, staged, { recursive: true });
+    expect(() => assertStagedRendererMatchesBuild(dist, staged)).toThrow(
+      /has no eliza-renderer-build\.json/,
+    );
+  });
+
+  it("fails when the staged renderer has no manifest (stale/missing copy)", () => {
+    const dist = path.join(tmp, "dist");
+    const staged = path.join(tmp, "public");
+    makeDist(dist);
+    writeRendererBuildManifest(dist);
+    makeDist(staged); // copied bundle but manifest never made it across
+    expect(() => assertStagedRendererMatchesBuild(dist, staged)).toThrow(
+      /staged renderer .* has no/,
+    );
+  });
+
+  it("fails loudly when the staged renderer is STALE (different buildId)", () => {
+    const dist = path.join(tmp, "dist");
+    const staged = path.join(tmp, "public");
+    // Stale staged renderer: built earlier from different content.
+    makeDist(staged, {
+      indexHtml: "<!doctype html><html><body>OLD UI</body></html>",
+      assets: { "index-old000.js": "old" },
+    });
+    writeRendererBuildManifest(staged);
+    // Fresh build with new content.
+    makeDist(dist, {
+      indexHtml: "<!doctype html><html><body>NEW UI</body></html>",
+      assets: { "index-new111.js": "new" },
+    });
+    writeRendererBuildManifest(dist);
+    expect(() => assertStagedRendererMatchesBuild(dist, staged)).toThrow(
+      /STALE RENDERER/,
+    );
+  });
+
+  it("fails when the manifest matches but index.html was torn during copy", () => {
+    const dist = path.join(tmp, "dist");
+    const staged = path.join(tmp, "public");
+    makeDist(dist);
+    writeRendererBuildManifest(dist);
+    fs.cpSync(dist, staged, { recursive: true });
+    // Corrupt the staged index.html after the manifest was copied.
+    fs.writeFileSync(path.join(staged, "index.html"), "partial");
+    expect(() => assertStagedRendererMatchesBuild(dist, staged)).toThrow(
+      /partial or stale copy/,
+    );
+  });
+});
+
+describe("overlayFreshRendererIntoPublic", () => {
+  it("overlays a stale public with the fresh build and preserves non-dist payloads", () => {
+    const dist = path.join(tmp, "dist");
+    const pub = path.join(tmp, "public");
+    // Fresh build.
+    makeDist(dist, {
+      indexHtml: "<!doctype html><html><body>NEW</body></html>",
+      assets: { "index-new111.js": "new" },
+    });
+    writeRendererBuildManifest(dist);
+    // Stale public with an OLD hashed asset + an on-device agent payload that
+    // lives outside dist and must survive the overlay.
+    fs.mkdirSync(path.join(pub, "assets"), { recursive: true });
+    fs.writeFileSync(path.join(pub, "index.html"), "OLD");
+    fs.writeFileSync(path.join(pub, "assets", "index-old000.js"), "old");
+    fs.mkdirSync(path.join(pub, "agent"), { recursive: true });
+    fs.writeFileSync(path.join(pub, "agent", "agent-bundle.js"), "AGENT");
+
+    overlayFreshRendererIntoPublic(dist, pub, { label: "ios" });
+
+    // Old hashed asset is gone; fresh one is present; index matches.
+    expect(fs.existsSync(path.join(pub, "assets", "index-old000.js"))).toBe(
+      false,
+    );
+    expect(fs.existsSync(path.join(pub, "assets", "index-new111.js"))).toBe(
+      true,
+    );
+    expect(fs.readFileSync(path.join(pub, "index.html"), "utf8")).toContain(
+      "NEW",
+    );
+    // The agent payload outside dist survived.
+    expect(
+      fs.readFileSync(path.join(pub, "agent", "agent-bundle.js"), "utf8"),
+    ).toBe("AGENT");
+    // And it now passes the staged-matches-build assertion.
+    expect(() => assertStagedRendererMatchesBuild(dist, pub)).not.toThrow();
+  });
+
+  it("throws when the fresh renderer is missing", () => {
+    const dist = path.join(tmp, "dist");
+    const pub = path.join(tmp, "public");
+    fs.mkdirSync(dist, { recursive: true }); // no index.html
+    expect(() => overlayFreshRendererIntoPublic(dist, pub)).toThrow(
+      /Refusing to stage a missing\/stale UI/,
+    );
+  });
+});
+
+describe("assertRendererRebuiltSince", () => {
+  it("passes when the manifest was built during this invocation", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    const notBefore = Date.now() - 1000;
+    writeRendererBuildManifest(dist, { variant: "base" });
+    expect(() =>
+      assertRendererRebuiltSince(dist, { notBefore, expectVariant: "base" }),
+    ).not.toThrow();
+  });
+
+  it("fails when the manifest is older than this build (stale dist reused)", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    writeRendererBuildManifest(dist, {
+      builtAt: "2020-01-01T00:00:00.000Z",
+    });
+    expect(() =>
+      assertRendererRebuiltSince(dist, { notBefore: Date.now() }),
+    ).toThrow(/STALE/);
+  });
+
+  it("fails when the renderer was built for a different variant", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    const notBefore = Date.now() - 1000;
+    writeRendererBuildManifest(dist, { variant: "direct" });
+    expect(() =>
+      assertRendererRebuiltSince(dist, { notBefore, expectVariant: "store" }),
+    ).toThrow(/wrong-variant/);
+  });
+
+  it("fails when no manifest exists after the build", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    expect(() =>
+      assertRendererRebuiltSince(dist, { notBefore: Date.now() - 1000 }),
+    ).toThrow(/no eliza-renderer-build\.json/);
+  });
+});
+
+describe("buildRendererManifest", () => {
+  it("defaults builtAt to an ISO timestamp and nulls unset metadata", () => {
+    const dist = path.join(tmp, "dist");
+    makeDist(dist);
+    const manifest = buildRendererManifest(dist);
+    expect(manifest.schema).toBe("elizaos.renderer.build/v1");
+    expect(Number.isFinite(Date.parse(manifest.builtAt))).toBe(true);
+    expect(manifest.commit).toBeNull();
+    expect(manifest.variant).toBeNull();
+    expect(manifest.capacitorTarget).toBeNull();
+  });
+});

package/scripts/lib/stage-android-agent.mjs

@@ -926,6 +926,7 @@ export async function stageAndroidAgentRuntime({
   spikeDir,
   cacheDir,
   bunChannel: preferredBunChannel,
+  objective = false,
   log = console.log,
 } = {}) {
   if (!androidDir)
@@ -959,7 +960,7 @@ export async function stageAndroidAgentRuntime({
   let stagedCount = 0;
   const stagedFiles = [];
   const riscv64Artifact = {
-    required: true,
+    required: objective,
     filename: RISCV64_BUN_ARTIFACT_FILENAME,
     sha256: riscv64BunSha256(),
     source: riscv64BunArtifactSource(),
@@ -976,10 +977,18 @@ export async function stageAndroidAgentRuntime({
     if (bunArch === "riscv64") {
       const riscvFile = riscv64BunFilePath();
       const riscvUrl = riscv64BunUrl();
-      const optional = process.env.ELIZA_BUN_RISCV64_OPTIONAL === "1";
-      if (!riscvFile && !riscvUrl && optional) {
+      // riscv64 is fail-closed ONLY for objective AOSP/chip builds (they ship
+      // riscv64 and must prove it). A stock arm64 phone build skips the slice
+      // when no artifact is configured instead of aborting — upstream Bun has
+      // no riscv64-linux-musl release, so a plain `build:android` would
+      // otherwise demand a binary it never packages. ELIZA_BUN_RISCV64_OPTIONAL=1
+      // still force-skips even for objective builds (native-lib iteration). A
+      // genuine riscv64 build supplies ELIZA_BUN_RISCV64_FILE/_URL, so the slice
+      // stages either way — the skip only fires when there is no artifact at all.
+      const forceSkip = process.env.ELIZA_BUN_RISCV64_OPTIONAL === "1";
+      if (!riscvFile && !riscvUrl && (!objective || forceSkip)) {
         tlog(
-          `Skipping optional ABI ${androidAbi}: no ELIZA_BUN_RISCV64_FILE or URL is set ` +
+          `Skipping ABI ${androidAbi}: no ELIZA_BUN_RISCV64_FILE or URL is set ` +
             `(upstream Bun has no riscv64-linux-musl release). Build with ` +
             `packages/app-core/scripts/bun-riscv64/build.sh and re-run for AOSP/chip evidence.`,
         );

package/scripts/lib/verify-ondevice-artifact.d.mts

@@ -0,0 +1,16 @@
+/**
+ * Type declarations for `verify-ondevice-artifact.mjs` — post-build artifact
+ * verification gate (issue #9309).
+ */
+import type { RendererBuildManifest } from "./renderer-build-manifest.d.mts";
+
+export function verifyStagedArtifact(opts: {
+  rendererDir: string;
+  freshDistDir?: string | null;
+  requiredFiles?: string[];
+  label?: string;
+}): {
+  ok: boolean;
+  problems: string[];
+  manifest: RendererBuildManifest | null;
+};

package/scripts/lib/verify-ondevice-artifact.mjs

@@ -0,0 +1,61 @@
+/**
+ * Build-verification for an on-device artifact (issue #9309).
+ *
+ * Asserts a staged platform artifact contains (a) the freshly built renderer
+ * (via the build stamp), and (b) every required companion file — the agent
+ * bundle and the platform's native lib set. Used as a post-build CI gate so a
+ * device artifact that is missing the latest renderer, the agent bundle, or a
+ * native lib FAILS loudly instead of shipping a half-staged build.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  assertStagedRendererMatchesBuild,
+  readRendererBuildManifest,
+} from "./renderer-build-manifest.mjs";
+
+/**
+ * @param {{
+ *   rendererDir: string,            // the staged web root (holds index.html + the build stamp)
+ *   freshDistDir?: string|null,     // the just-built dist to match against (optional)
+ *   requiredFiles?: string[],       // companion files (agent bundle, native libs); relative→rendererDir
+ *   label?: string,
+ * }} opts
+ * @returns {{ ok: boolean, problems: string[], manifest: object|null }}
+ */
+export function verifyStagedArtifact({
+  rendererDir,
+  freshDistDir = null,
+  requiredFiles = [],
+  label = "artifact",
+}) {
+  const problems = [];
+  let manifest = null;
+
+  if (freshDistDir) {
+    try {
+      manifest = assertStagedRendererMatchesBuild(freshDistDir, rendererDir, {
+        label,
+      });
+    } catch (error) {
+      problems.push(error instanceof Error ? error.message : String(error));
+    }
+  } else {
+    manifest = readRendererBuildManifest(rendererDir);
+    if (!manifest) {
+      problems.push(
+        `${label}: no renderer build stamp in ${rendererDir} — unverifiable renderer.`,
+      );
+    }
+  }
+
+  for (const file of requiredFiles) {
+    const abs = path.isAbsolute(file) ? file : path.join(rendererDir, file);
+    if (!fs.existsSync(abs)) {
+      problems.push(`${label}: missing required artifact file ${file}`);
+    }
+  }
+
+  return { ok: problems.length === 0, problems, manifest };
+}