impel-cli 0.20.37 → 0.20.39

package/scripts/regen-managed-artifacts.mjs

@@ -0,0 +1,475 @@
+// Deterministic, offline regeneration of the Impel-managed on-disk artifacts
+// from fixed inputs, for the released-fixture corpus (docs/testing-protocol.md
+// §5 P0-2) and the version-bump tripwire (§5 P0-3, Law 7).
+//
+// Usage:
+//   node scripts/regen-managed-artifacts.mjs <output-dir> [--force]
+//
+// The script generates the managed profile TWICE, each time into its own
+// throwaway temp HOME (never a personal ~/.claude, ~/.codex, or desktop
+// profile), through the real production writers in src/ — never a
+// reimplementation. Both trees are post-processed with the repo's placeholder
+// convention (<HOME>, <NODE>, <REPOSITORY>) so the output is
+// machine-independent, then compared byte-for-byte. Any difference is a hard
+// failure: nondeterministic generation must never be captured as a fixture.
+//
+// Internal child mode (used for isolation because CONFIG_DIR in src/config.js
+// is frozen at module load):
+//   node scripts/regen-managed-artifacts.mjs --emit <home> [--tenant t]
+//     [--tenant-name n] [--gateway url] [--generated-at ts] [--pat p]
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+export const REPOSITORY_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "..");
+
+// Fixed generation inputs. Changing any of these changes every captured
+// fixture, so treat them as part of the fixture contract.
+export const FIXED_INPUTS = Object.freeze({
+  generatedAt: "2026-01-01T00:00:00.000Z",
+  tenantId: "impel",
+  tenantName: "Impel",
+  gatewayUrl: "https://gateway.example.test",
+  pat: "impel_pat_TEST",
+});
+
+// Vendor-download-derived (and, for the CLI profile, wall-clock-stamped) model
+// catalogs are excluded from the corpus: the honest enrichment source is the
+// pinned downloaded binary, which must never be fetched under `pnpm test`.
+export const EXCLUDED_BASENAMES = Object.freeze(["models.json"]);
+export const EXCLUSION_REASON =
+  "vendor model catalogs come from the pinned downloaded binary (and the CLI "
+  + "catalog stamps a live fetched_at); excluded so the corpus stays offline "
+  + "and deterministic";
+
+// Codex hook-trust hashes digest the machine-local node and repository paths,
+// so they cannot survive placeholder substitution. hooks.json carries the same
+// command content in placeholder-stable form, so normalizing the hash loses no
+// tripwire coverage.
+const TRUSTED_HASH_RE = /(trusted_hash = ")sha256:[0-9a-f]{64}(")/gu;
+export const TRUSTED_HASH_PLACEHOLDER = "sha256:<TRUSTED-HASH>";
+
+function replacePath(text, value, placeholder) {
+  const encoded = JSON.stringify(value).slice(1, -1);
+  return text.replaceAll(encoded, placeholder).replaceAll(value, placeholder);
+}
+
+function realPathVariants(target) {
+  const variants = [target];
+  try {
+    variants.push(fs.realpathSync(target));
+  } catch {
+    // A path that no longer resolves keeps its literal form only.
+  }
+  return [...new Set(variants)].sort((left, right) => right.length - left.length);
+}
+
+/**
+ * Platform canonicalization for the reviewed fixture comparison only (the
+ * same transform test/codex-config-contract.test.js applies): CRLF -> LF and
+ * backslash pairs -> forward slashes, so Windows-generated trees compare equal
+ * to the reviewed corpus. Generated profile files on disk are never rewritten.
+ */
+export function canonicalArtifactText(text) {
+  return text.replaceAll("\r\n", "\n").replaceAll("\\\\", "/");
+}
+
+/** Substitute machine-specific values with the repo's placeholder convention. */
+export function normalizeArtifactText(text, homeDir) {
+  let normalized = text;
+  for (const homePath of realPathVariants(homeDir)) {
+    normalized = replacePath(normalized, homePath, "<HOME>");
+  }
+  for (const nodePath of realPathVariants(process.execPath)) {
+    normalized = replacePath(normalized, nodePath, "<NODE>");
+  }
+  for (const repositoryPath of realPathVariants(REPOSITORY_ROOT)) {
+    normalized = replacePath(normalized, repositoryPath, "<REPOSITORY>");
+  }
+  normalized = normalized.replace(TRUSTED_HASH_RE, `$1${TRUSTED_HASH_PLACEHOLDER}$2`);
+  // Windows writes a few raw (non-JSON-escaped) paths, e.g. in the sh token
+  // helper; canonicalize the path remainder that follows a placeholder so the
+  // corpus compares equal across platforms.
+  normalized = normalized.replace(
+    /<(HOME|NODE|REPOSITORY)>((?:\\[^\\/:*?"<>|\r\n]+)+)/gu,
+    (match, name, rest) => `<${name}>${rest.replaceAll("\\", "/")}`,
+  );
+  return canonicalArtifactText(normalized);
+}
+
+// Artifacts whose embedded path strings the production writers emit through
+// JSON.stringify: JSON documents, and TOML files (every path in a managed
+// config.toml goes through tomlString = JSON.stringify into a TOML basic
+// string, where backslash is likewise an escape character). Substituting a
+// raw win32 path (C:\Users\...) into these would form invalid escapes; a real
+// Windows install has the JSON-escaped form (C:\\Users\\...) on disk.
+// Everything else (the sh token helper, preload/html assets) embeds raw text.
+const JSON_ESCAPED_ARTIFACT_RE = /\.(?:json|toml)$/u;
+
+/**
+ * Reverse the placeholder substitution to materialize a fixture on disk,
+ * using the escaping the production writer of that artifact would have used,
+ * so the materialized profile matches what a real install of that platform
+ * has on disk. The corpus is canonical-LF; normalize line endings first so
+ * materialization never silently depends on how a checkout treated the
+ * fixture bytes (the byte-exact guard for that lives in the tripwire's
+ * sha256 integrity test).
+ *
+ * `relativePath` selects the escaping context; omitting it yields raw
+ * substitution, which is only correct for artifacts without JSON/TOML string
+ * semantics (or on platforms whose paths need no escaping).
+ */
+export function materializeArtifactText(text, homeDir, relativePath = "") {
+  const encode = JSON_ESCAPED_ARTIFACT_RE.test(relativePath)
+    ? (value) => JSON.stringify(value).slice(1, -1)
+    : (value) => value;
+  return text
+    .replaceAll("\r\n", "\n")
+    .replaceAll("<HOME>", encode(homeDir))
+    .replaceAll("<NODE>", encode(process.execPath))
+    .replaceAll("<REPOSITORY>", encode(REPOSITORY_ROOT))
+    .replaceAll(TRUSTED_HASH_PLACEHOLDER, `sha256:${"0".repeat(64)}`);
+}
+
+/** True when two texts differ, but only by CRLF-vs-LF line endings. */
+export function eolOnlyDifference(left, right) {
+  return left !== right && left.replaceAll("\r\n", "\n") === right.replaceAll("\r\n", "\n");
+}
+
+function walkFiles(root) {
+  const files = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const target = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) pending.push(target);
+      else if (entry.isFile()) files.push(target);
+    }
+  }
+  return files.sort();
+}
+
+function toPosixRelative(root, target) {
+  return path.relative(root, target).split(path.sep).join("/");
+}
+
+/**
+ * Collect every generated artifact under one temp HOME's Impel config root as
+ * a Map of posix-relative path -> normalized text, plus the excluded paths.
+ */
+export function collectArtifacts(homeDir) {
+  const configRoot = path.join(homeDir, ".config", "impel");
+  const artifacts = new Map();
+  const excluded = [];
+  for (const file of walkFiles(configRoot)) {
+    const relative = toPosixRelative(configRoot, file);
+    if (EXCLUDED_BASENAMES.includes(path.basename(file))) {
+      excluded.push(relative);
+      continue;
+    }
+    artifacts.set(relative, normalizeArtifactText(fs.readFileSync(file, "utf8"), homeDir));
+  }
+  return { artifacts, excluded: excluded.sort() };
+}
+
+function firstDifferenceExcerpt(expected, actual, context = 2, width = 200) {
+  const expectedLines = expected.split("\n");
+  const actualLines = actual.split("\n");
+  const total = Math.max(expectedLines.length, actualLines.length);
+  for (let index = 0; index < total; index += 1) {
+    if (expectedLines[index] === actualLines[index]) continue;
+    const lines = [];
+    for (let nearby = Math.max(0, index - context); nearby < index; nearby += 1) {
+      lines.push(`   ${expectedLines[nearby] ?? ""}`.slice(0, width));
+    }
+    if (index < expectedLines.length) lines.push(` - ${expectedLines[index]}`.slice(0, width));
+    if (index < actualLines.length) lines.push(` + ${actualLines[index]}`.slice(0, width));
+    lines.unshift(` @@ line ${index + 1} @@`);
+    return lines.join("\n");
+  }
+  return " @@ contents differ only in trailing lines @@";
+}
+
+/**
+ * Compare two normalized artifact maps. Returns [] when identical, otherwise
+ * one entry per differing/missing/extra file with a short unified-ish excerpt.
+ */
+export function diffArtifactMaps(expected, actual) {
+  const differences = [];
+  for (const [relative, expectedText] of expected) {
+    if (!actual.has(relative)) {
+      differences.push({ path: relative, kind: "missing", excerpt: " @@ file missing from regenerated output @@" });
+      continue;
+    }
+    const actualText = actual.get(relative);
+    if (actualText !== expectedText) {
+      differences.push({
+        path: relative,
+        kind: "changed",
+        // Lines that differ only by CRLF-vs-LF render as visually identical
+        // in a plain diff excerpt; name the real cause instead.
+        excerpt: eolOnlyDifference(expectedText, actualText)
+          ? " @@ differs only in line endings (CRLF vs LF) — a checkout or writer rewrote them; ensure .gitattributes marks test/fixtures/released/** -text @@"
+          : firstDifferenceExcerpt(expectedText, actualText),
+      });
+    }
+  }
+  for (const relative of actual.keys()) {
+    if (!expected.has(relative)) {
+      differences.push({ path: relative, kind: "extra", excerpt: " @@ file not present in fixture @@" });
+    }
+  }
+  return differences.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+// Artifacts are stored with an inert suffix: `node --test` (pnpm test) treats
+// every *.js/*.mjs/*.cjs under test/ as a test file, and the corpus contains
+// generated .cjs preloads that must never execute as tests.
+export const FIXTURE_FILE_SUFFIX = ".fixture";
+
+/** Read a fixture (or regen output) directory back into an artifact map. */
+export function readArtifactTree(directory) {
+  const artifacts = new Map();
+  for (const file of walkFiles(directory)) {
+    const relative = toPosixRelative(directory, file);
+    if (relative === "metadata.json") continue;
+    if (!relative.endsWith(FIXTURE_FILE_SUFFIX)) {
+      throw new Error(`${file} is missing the ${FIXTURE_FILE_SUFFIX} suffix; not a captured artifact`);
+    }
+    artifacts.set(relative.slice(0, -FIXTURE_FILE_SUFFIX.length), fs.readFileSync(file, "utf8"));
+  }
+  return artifacts;
+}
+
+export function readFixtureMetadata(directory) {
+  return JSON.parse(fs.readFileSync(path.join(directory, "metadata.json"), "utf8"));
+}
+
+/** Latest <version> directory under test/fixtures/released, by semver order. */
+export function latestReleasedFixtureDir(root = path.join(REPOSITORY_ROOT, "test", "fixtures", "released")) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+  const versions = entries
+    .filter((entry) => entry.isDirectory() && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(entry.name))
+    .map((entry) => entry.name)
+    .sort(compareVersions);
+  if (versions.length === 0) return null;
+  return path.join(root, versions[versions.length - 1]);
+}
+
+export function compareVersions(left, right) {
+  const parse = (value) => {
+    const [core, prerelease = null] = value.split("-", 2);
+    return { parts: core.split(".").map(Number), prerelease };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (a.parts[index] !== b.parts[index]) return a.parts[index] - b.parts[index];
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === null) return 1; // release > its own prereleases
+  if (b.prerelease === null) return -1;
+  return a.prerelease < b.prerelease ? -1 : 1;
+}
+
+function sanitizedChildEnvironment(homeDir) {
+  const environment = { ...process.env };
+  for (const name of [
+    "IMPEL_APP_HOME",
+    "IMPEL_CONFIG_DIR",
+    "IMPEL_GATEWAY_URL",
+    "IMPEL_APP_URL",
+    "IMPEL_CLI_RUNTIME_BRAND",
+    "IMPEL_CLI_EXTENSION_ENTRYPOINT",
+    "CODEX_HOME",
+    "CLAUDE_CONFIG_DIR",
+  ]) {
+    delete environment[name];
+  }
+  environment.HOME = homeDir;
+  environment.USERPROFILE = homeDir;
+  environment.IMPEL_CONFIG_DIR = path.join(homeDir, ".config", "impel");
+  return environment;
+}
+
+function argumentValue(argv, flag, fallback) {
+  const index = argv.indexOf(flag);
+  return index !== -1 && argv[index + 1] !== undefined ? argv[index + 1] : fallback;
+}
+
+/**
+ * Child mode: generate one complete managed profile into `homeDir` through the
+ * production writers. Runs in its own process so CONFIG_DIR (frozen at module
+ * load in src/config.js) can be pointed at the temp HOME before src/ loads.
+ */
+async function emitManagedArtifacts(homeDir, argv = []) {
+  process.env.HOME = homeDir;
+  process.env.USERPROFILE = homeDir;
+  process.env.IMPEL_CONFIG_DIR = path.join(homeDir, ".config", "impel");
+  delete process.env.IMPEL_APP_HOME;
+  delete process.env.IMPEL_CLI_RUNTIME_BRAND;
+  delete process.env.IMPEL_CLI_EXTENSION_ENTRYPOINT;
+  delete process.env.CODEX_HOME;
+
+  const inputs = {
+    generatedAt: argumentValue(argv, "--generated-at", FIXED_INPUTS.generatedAt),
+    tenantId: argumentValue(argv, "--tenant", FIXED_INPUTS.tenantId),
+    tenantName: argumentValue(argv, "--tenant-name", FIXED_INPUTS.tenantName),
+    gatewayUrl: argumentValue(argv, "--gateway", FIXED_INPUTS.gatewayUrl),
+    pat: argumentValue(argv, "--pat", FIXED_INPUTS.pat),
+  };
+
+  // Real production generation functions only — never a reimplementation.
+  const { FALLBACK_MODELS, installManagedAppFiles } = await import("../src/apps.js");
+  const { ensureImpelClaudeProfile, ensureImpelCodexProfile } = await import("../src/cliProfiles.js");
+
+  const config = {
+    pat: inputs.pat,
+    gatewayUrl: inputs.gatewayUrl,
+    tenantId: inputs.tenantId,
+    tenantName: inputs.tenantName,
+  };
+  installManagedAppFiles({
+    config,
+    targets: ["claude", "chatgpt"],
+    models: FALLBACK_MODELS,
+    homeDir,
+    // Truthy non-existent paths: no vendor discovery, no vendor enrichment,
+    // and writeBundles:false keeps this to the pure config/manifest surface.
+    vendorPaths: {
+      claude: "/impel-regen/no-vendor/Claude.app",
+      chatgpt: "/impel-regen/no-vendor/ChatGPT.app",
+    },
+    writeBundles: false,
+    generatedAt: inputs.generatedAt,
+  });
+  ensureImpelClaudeProfile(inputs.gatewayUrl, inputs.tenantId, { crossAppModels: false });
+  ensureImpelCodexProfile(inputs.gatewayUrl, inputs.tenantId);
+}
+
+/**
+ * Run one isolated production generation pass over `homeDir` in a child
+ * process. Also the fixture tests' repair path: emitting over an existing
+ * materialized profile IS the managed regeneration/repair flow.
+ */
+export function spawnEmit(homeDir, extraArguments = []) {
+  const result = spawnSync(
+    process.execPath,
+    [SCRIPT_PATH, "--emit", homeDir, ...extraArguments],
+    { encoding: "utf8", env: sanitizedChildEnvironment(homeDir) },
+  );
+  if (result.status !== 0 || result.error) {
+    throw new Error(
+      `managed-artifact generation failed in ${homeDir}:\n${result.stderr || result.stdout || result.error}`,
+    );
+  }
+  return result;
+}
+
+/**
+ * Regenerate the managed artifacts into `outputDir`: two independent
+ * generations into fresh temp HOMEs, byte-compared after placeholder
+ * normalization, then written once with metadata.json. Returns the metadata.
+ */
+export async function regenerateManagedArtifacts(outputDir, { force = false } = {}) {
+  if (fs.existsSync(outputDir) && fs.readdirSync(outputDir).length > 0) {
+    if (!force) {
+      throw new Error(`${outputDir} already exists and is not empty (pass --force to replace it)`);
+    }
+    fs.rmSync(outputDir, { recursive: true, force: true });
+  }
+
+  const homes = [
+    fs.mkdtempSync(path.join(os.tmpdir(), "impel-regen-a-")),
+    fs.mkdtempSync(path.join(os.tmpdir(), "impel-regen-b-")),
+  ];
+  try {
+    for (const home of homes) spawnEmit(home);
+    const first = collectArtifacts(homes[0]);
+    const second = collectArtifacts(homes[1]);
+    const differences = diffArtifactMaps(first.artifacts, second.artifacts);
+    if (differences.length > 0) {
+      const report = differences
+        .map((difference) => `  ${difference.kind}: ${difference.path}\n${difference.excerpt}`)
+        .join("\n");
+      throw new Error(
+        "managed-artifact generation is not deterministic; refusing to write output.\n"
+        + "Two generations from identical fixed inputs produced different bytes:\n"
+        + report,
+      );
+    }
+
+    const packageJson = JSON.parse(fs.readFileSync(path.join(REPOSITORY_ROOT, "package.json"), "utf8"));
+    // Version markers come from the same production module the writers use.
+    const { CURRENT_CONFIG_VERSION, BUNDLE_BUILD_FINGERPRINT } = await import("../src/apps.js");
+
+    fs.mkdirSync(outputDir, { recursive: true });
+    const artifactRecords = [];
+    for (const [relative, text] of [...first.artifacts.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const target = path.join(outputDir, ...`${relative}${FIXTURE_FILE_SUFFIX}`.split("/"));
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, text);
+      artifactRecords.push({
+        path: relative,
+        sha256: crypto.createHash("sha256").update(text).digest("hex"),
+        bytes: Buffer.byteLength(text),
+      });
+    }
+    const metadata = {
+      cliVersion: packageJson.version,
+      configVersion: CURRENT_CONFIG_VERSION,
+      bundleFingerprint: BUNDLE_BUILD_FINGERPRINT,
+      capturedAt: FIXED_INPUTS.generatedAt,
+      inputs: { ...FIXED_INPUTS },
+      placeholders: ["<HOME>", "<NODE>", "<REPOSITORY>", TRUSTED_HASH_PLACEHOLDER],
+      excluded: first.excluded.map((relative) => ({ path: relative, reason: EXCLUSION_REASON })),
+      artifacts: artifactRecords,
+    };
+    fs.writeFileSync(path.join(outputDir, "metadata.json"), `${JSON.stringify(metadata, null, 2)}\n`);
+    return metadata;
+  } finally {
+    for (const home of homes) fs.rmSync(home, { recursive: true, force: true });
+  }
+}
+
+const isMain = process.argv[1]
+  && path.resolve(process.argv[1]) === SCRIPT_PATH;
+
+if (isMain) {
+  const argv = process.argv.slice(2);
+  if (argv[0] === "--emit") {
+    if (!argv[1]) {
+      console.error("usage: node scripts/regen-managed-artifacts.mjs --emit <home>");
+      process.exit(2);
+    }
+    await emitManagedArtifacts(path.resolve(argv[1]), argv.slice(2));
+  } else {
+    const outputDir = argv.find((argument) => !argument.startsWith("--"));
+    if (!outputDir) {
+      console.error("usage: node scripts/regen-managed-artifacts.mjs <output-dir> [--force]");
+      process.exit(2);
+    }
+    const metadata = await regenerateManagedArtifacts(path.resolve(outputDir), {
+      force: argv.includes("--force"),
+    });
+    console.log(
+      `regenerated ${metadata.artifacts.length} managed artifacts `
+      + `(configVersion ${metadata.configVersion}, ${metadata.bundleFingerprint}) `
+      + `into ${path.resolve(outputDir)}`,
+    );
+    console.log("determinism: two independent generations were byte-identical after normalization");
+  }
+}

package/scripts/verify-vendor-pins.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// Vendor pin-drift monitor (testing-protocol RC13 / P2-11).
+//
+// Vendors have re-published different bytes under the same pinned URL, and the
+// Microsoft Store has fulfilled a different build than the reviewed pin. This
+// script re-verifies every pinned artifact source against the recorded pin so
+// that drift becomes a red scheduled run instead of a user-discovered outage.
+//
+// - Direct downloads are streamed straight into SHA-256 (never written to
+//   disk) and compared with the pinned hash.
+// - The Windows ChatGPT/Codex pin has no hashable download URL (Store
+//   fulfillment), so its published update manifest is compared field-for-field
+//   with the pin, mirroring test/windows-chatgpt-store-contract.test.js.
+//
+// Usage:
+//   node scripts/verify-vendor-pins.mjs             # verify everything (CI)
+//   node scripts/verify-vendor-pins.mjs --only=claude:win32-x64
+//   node scripts/verify-vendor-pins.mjs --only=chatgpt
+//
+// Exit status is non-zero if any artifact mismatches or is unreachable, after
+// every artifact has been attempted (the run reports all drift, not the first).
+
+import crypto from "node:crypto";
+import process from "node:process";
+import { PINNED_VENDOR_APPS } from "../src/apps.js";
+
+const DOWNLOAD_TIMEOUT_MS = 20 * 60 * 1000;
+const MANIFEST_TIMEOUT_MS = 30 * 1000;
+const PROGRESS_EVERY_BYTES = 64 * 1024 * 1024;
+
+if (typeof fetch !== "function") {
+  console.error("verify-vendor-pins requires Node 18+ (global fetch).");
+  process.exit(1);
+}
+
+function collectArtifacts() {
+  const artifacts = [];
+  for (const [app, pin] of Object.entries(PINNED_VENDOR_APPS)) {
+    for (const [architecture, download] of Object.entries(pin.downloads ?? {})) {
+      artifacts.push({
+        label: `${app}:darwin-${architecture}`,
+        kind: "hash",
+        url: download.url,
+        sha256: download.sha256,
+      });
+    }
+    const windows = pin.windows;
+    if (!windows) continue;
+    if (windows.downloads) {
+      for (const [architecture, download] of Object.entries(windows.downloads)) {
+        artifacts.push({
+          label: `${app}:win32-${architecture}`,
+          kind: "hash",
+          url: download.url,
+          sha256: download.sha256,
+        });
+      }
+    } else if (windows.updateManifestUrl) {
+      artifacts.push({
+        label: `${app}:win32-store`,
+        kind: "store-manifest",
+        url: windows.updateManifestUrl,
+        expected: {
+          schemaVersion: 1,
+          buildVersion: windows.packageVersion,
+          storeProductId: windows.storeProductId,
+          packageIdentity: windows.packageName,
+        },
+      });
+    } else {
+      artifacts.push({
+        label: `${app}:win32`,
+        kind: "skip",
+        reason: "Windows pin exposes neither a hashable download URL nor an update manifest URL",
+      });
+    }
+  }
+  return artifacts;
+}
+
+async function sha256OfUrl(url, label) {
+  const response = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status} fetching ${url}`);
+  if (!response.body) throw new Error(`empty response body fetching ${url}`);
+  const hash = crypto.createHash("sha256");
+  let bytes = 0;
+  let nextProgress = PROGRESS_EVERY_BYTES;
+  for await (const chunk of response.body) {
+    hash.update(chunk);
+    bytes += chunk.length;
+    if (bytes >= nextProgress) {
+      console.log(`  [${label}] ${(bytes / 1024 / 1024).toFixed(0)} MiB hashed...`);
+      nextProgress += PROGRESS_EVERY_BYTES;
+    }
+  }
+  return { sha256: hash.digest("hex"), bytes };
+}
+
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+}
+
+async function verifyStoreManifest(artifact) {
+  const response = await fetch(artifact.url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(MANIFEST_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`HTTP ${response.status} fetching ${artifact.url}`);
+  const manifest = await response.json();
+  // Exact comparison, matching the Store contract test: an added field is
+  // vendor drift the pin review has not seen, and must go red too.
+  if (canonicalJson(manifest) !== canonicalJson(artifact.expected)) {
+    throw new Error(
+      `Store update manifest drifted from the pin.\n`
+        + `    expected: ${canonicalJson(artifact.expected)}\n`
+        + `    actual:   ${canonicalJson(manifest)}`,
+    );
+  }
+}
+
+function parseOnly(argv) {
+  const flag = argv.find((argument) => argument.startsWith("--only="));
+  if (!flag) return null;
+  const value = flag.slice("--only=".length).trim();
+  if (!value) {
+    console.error("--only requires a value, e.g. --only=claude:win32-x64 or --only=chatgpt");
+    process.exit(1);
+  }
+  return value;
+}
+
+const only = parseOnly(process.argv.slice(2));
+const allArtifacts = collectArtifacts();
+const artifacts = only
+  ? allArtifacts.filter(
+    (artifact) => artifact.label === only || artifact.label.split(":")[0] === only,
+  )
+  : allArtifacts;
+if (artifacts.length === 0) {
+  console.error(`--only=${only} matched no artifacts. Known labels:`);
+  for (const artifact of allArtifacts) console.error(`  ${artifact.label}`);
+  process.exit(1);
+}
+
+const failures = [];
+const hashCache = new Map();
+for (const artifact of artifacts) {
+  const startedAt = Date.now();
+  if (artifact.kind === "skip") {
+    console.log(`SKIPPED ${artifact.label}: ${artifact.reason}`);
+    continue;
+  }
+  console.log(`verifying ${artifact.label} <- ${artifact.url}`);
+  try {
+    if (artifact.kind === "hash") {
+      // Identical URLs (e.g. the universal Claude macOS zip pinned for both
+      // architectures) are downloaded once and reused.
+      let result = hashCache.get(artifact.url);
+      if (!result) {
+        result = await sha256OfUrl(artifact.url, artifact.label);
+        hashCache.set(artifact.url, result);
+      }
+      if (result.sha256 !== artifact.sha256) {
+        throw new Error(
+          `SHA-256 drifted from the pin (vendor re-published under the same URL?).\n`
+            + `    expected: ${artifact.sha256}\n`
+            + `    actual:   ${result.sha256} (${result.bytes} bytes)`,
+        );
+      }
+      console.log(
+        `OK ${artifact.label}: sha256 matches pin`
+          + ` (${(result.bytes / 1024 / 1024).toFixed(1)} MiB, ${((Date.now() - startedAt) / 1000).toFixed(1)}s)`,
+      );
+    } else if (artifact.kind === "store-manifest") {
+      await verifyStoreManifest(artifact);
+      console.log(
+        `OK ${artifact.label}: Store update manifest matches pin`
+          + ` (${((Date.now() - startedAt) / 1000).toFixed(1)}s)`,
+      );
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`FAIL ${artifact.label}: ${message}`);
+    failures.push({ label: artifact.label, url: artifact.url, message });
+  }
+}
+
+if (failures.length > 0) {
+  console.error(`\n${failures.length} pinned artifact source(s) drifted or were unreachable:`);
+  for (const failure of failures) {
+    console.error(`  ${failure.label} (${failure.url})`);
+  }
+  console.error(
+    "\nPin drift means the vendor changed the artifact behind a reviewed pin."
+      + " Re-review the build and update PINNED_VENDOR_APPS through a normal"
+      + " vendor-upgrade release; never loosen verification to make this pass.",
+  );
+  process.exit(1);
+}
+console.log(`\nAll ${artifacts.length} pinned artifact source(s) match their pins.`);