@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/repo-controls/src/runtime.ts

@@ -0,0 +1,110 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+export type Env = Record<string, string | undefined>
+
+const AGENT_VAULT_ENV = ['AGENT_VAULT_ADDR', 'AGENT_VAULT_TOKEN', 'AGENT_VAULT_VAULT'] as const
+
+// Exactly `git rev-parse --local-env-vars`. Git exports these to hooks for the
+// repository that invoked the hook; forwarding them makes a command launched
+// in another repository keep operating on the hook's repository instead.
+const LOCAL_GIT_ENV = [
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_CONFIG',
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_CONFIG_COUNT',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_GRAFT_FILE',
+  'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_PREFIX',
+  'GIT_SHALLOW_FILE',
+  'GIT_COMMON_DIR',
+] as const
+
+export interface ChildEnvOptions {
+  /** Reserved for the validated Agent Vault command tree; all ordinary children are stripped. */
+  preserveAgentVault?: boolean
+}
+
+/** Children inherit caller overrides, but no hook-local Git state or Vault credentials by default. */
+export function childEnv(env: Env, options: ChildEnvOptions = {}): Record<string, string | undefined> {
+  const child = { ...process.env, ...env }
+  // `GIT_CONFIG_COUNT` owns a dynamic set that `--local-env-vars` does not
+  // enumerate. Removing the count but forwarding its values strands repository
+  // config (and potentially authorization headers) in every descendant.
+  for (const name of Object.keys(child)) {
+    if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(name)) delete child[name]
+  }
+  for (const name of LOCAL_GIT_ENV) delete child[name]
+  if (!options.preserveAgentVault) {
+    for (const name of AGENT_VAULT_ENV) delete child[name]
+  }
+  return child
+}
+
+export function which(command: string, env: Env): string | null {
+  return Bun.which(command, { PATH: env.PATH ?? '' })
+}
+
+export interface Captured {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+/** Ordinary commands never receive Vault credentials; only Agent Vault opts in explicitly. */
+export function capture(cmd: string[], cwd: string, env: Env = {}, options: ChildEnvOptions = {}): Captured {
+  const environment = childEnv(env, options)
+  const proc = Bun.spawnSync(cmd, { cwd, env: environment, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+  return { code: proc.exitCode ?? 1, stdout: proc.stdout.toString(), stderr: proc.stderr.toString() }
+}
+
+/** Local git config value, or null when unset. */
+export function gitConfigGet(repo: string, key: string): string | null {
+  const result = capture(['git', 'config', '--local', '--get', key], repo)
+  return result.code === 0 ? result.stdout.trim() : null
+}
+
+export function gitOrThrow(repo: string, args: string[]): string {
+  const result = capture(['git', ...args], repo)
+  if (result.code !== 0) throw new Error(`git ${args.join(' ')} failed: ${result.stderr.trim()}`)
+  return result.stdout
+}
+
+/** The work tree root for `path`; `path` must be that root. */
+export function resolveRepo(path: string): string {
+  const absolute = resolve(path)
+  if (!existsSync(absolute)) throw new Error(`repository path does not exist: ${absolute}`)
+  const result = capture(['git', 'rev-parse', '--show-toplevel'], absolute)
+  if (result.code !== 0) throw new Error(`not a git repository: ${absolute}`)
+  const top = result.stdout.trim()
+  if (realpathSync(absolute) !== realpathSync(top)) throw new Error(`--repo must be the repository root (${top})`)
+  return top
+}
+
+export interface BashVersion {
+  major: number
+  text: string
+}
+
+/** Version of the first `bash` on PATH — the one `#!/usr/bin/env bash` hooks get. */
+export function bashVersion(env: Env): BashVersion | null {
+  const bash = which('bash', env)
+  if (!bash) return null
+  const text = capture([bash, '-c', 'printf "%s.%s" "${BASH_VERSINFO[0]}" "${BASH_VERSINFO[1]}"'], '/', env).stdout.trim()
+  return { major: Number.parseInt(text, 10) || 0, text }
+}
+
+export function bashProblem(env: Env): string | null {
+  const version = bashVersion(env)
+  if (!version) return 'bash not found on PATH'
+  if (version.major < 4) {
+    return `bash ${version.text} found first on PATH; the bundled enact-m5 hook scripts need bash >= 4 (e.g. brew install bash)`
+  }
+  return null
+}

package/packages/repo-controls/src/workflows-drift.ts

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { HOOK_NAMES, HOOKS_PATH, INSTALL_HINT, LOCK_REL, MANAGED_ASSETS, VERSION } from './constants.ts'
+import { checkGitignoreBlock } from './gitignore-block.ts'
+import { readLock, stubText, type Lock } from './install.ts'
+
+export interface WorkflowsDriftFinding {
+  /** Same ids `doctor()` uses for the same surface (`promote`, `hook:pre-commit`, `version`, ...). */
+  id: string
+  message: string
+}
+
+export interface WorkflowsDriftReport {
+  repo: string
+  /** No drift: `.workflows/` matches exactly what THIS running package version ships. */
+  ok: boolean
+  /** The version of adl-repo-controls this check ran with — what a repair would install. */
+  packageVersion: string
+  /** The version recorded in the repository's own lock file, or null when there is no lock at all. */
+  lockVersion: string | null
+  findings: WorkflowsDriftFinding[]
+}
+
+/**
+ * Pure, read-only comparison of a repository's `.workflows/` projection
+ * against the CURRENTLY RUNNING package's canonical assets and lock file.
+ *
+ * Never mutates the repository and never calls `install` — this only
+ * detects drift, a caller (`adl repo doctor`, C9) decides what to do with
+ * it. Extracted from `doctor()`'s per-asset/hook/lock/gitignore/version
+ * checks (same problem strings, same ids) so a caller that only cares about
+ * `.workflows/` drift — not bash/bun/coverage/compliance/etc. — does not
+ * have to run and filter doctor's full report to get it.
+ *
+ * Written for exactly the drift this package's own dogfood install had on
+ * 2026-09-27: adl-agent-control's root `.workflows/repo-controls.lock.json`
+ * claimed version 0.3.2 with only `promote.ts` and the four hook stubs
+ * recorded, while `version-bump.sh` and
+ * `scripts/enable-integration-auto-complete.mjs` existed on disk with no
+ * lock entry at all, and the `adl-config.toml` the lock's own `config`
+ * record claimed to have created did not exist. `checkWorkflowsDrift` would
+ * report `version-bump` and `integration-auto-complete` findings for the
+ * missing lock entries and a `version` finding for the lock/package
+ * mismatch — `doctor()` already does, but nothing outside a full `doctor`
+ * run could ask for just this until now.
+ */
+export function checkWorkflowsDrift(repoRoot: string): WorkflowsDriftReport {
+  const findings: WorkflowsDriftFinding[] = []
+  const add = (id: string, message: string | null): void => {
+    if (message !== null) findings.push({ id, message })
+  }
+
+  let lock: Lock | null = null
+  try {
+    lock = readLock(repoRoot)
+    if (lock === null) add('lock', `${LOCK_REL} missing — ${INSTALL_HINT}`)
+  } catch (error) {
+    add('lock', (error as Error).message)
+  }
+
+  for (const asset of MANAGED_ASSETS) {
+    const path = join(repoRoot, asset.rel)
+    const canonical = readFileSync(asset.source)
+    const canonicalHash = createHash('sha256').update(canonical).digest('hex')
+    const stats = lstatSync(path, { throwIfNoEntry: false })
+    if (stats === undefined) {
+      add(asset.doctorId, `${asset.rel} is missing — ${INSTALL_HINT}`)
+      continue
+    }
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+      add(asset.doctorId, `${asset.rel} is not a real file — ${INSTALL_HINT}`)
+      continue
+    }
+    if (!readFileSync(path).equals(canonical)) {
+      add(asset.doctorId, `${asset.rel} differs from the installed asset — ${INSTALL_HINT}`)
+      continue
+    }
+    if (lock?.files[asset.rel]?.sha256 !== canonicalHash) {
+      add(asset.doctorId, `${asset.rel} lock hash does not match the installed asset — ${INSTALL_HINT}`)
+      continue
+    }
+    if ((stats.mode & 0o111) === 0) add(asset.doctorId, `${asset.rel} is not executable — ${INSTALL_HINT}`)
+  }
+
+  for (const name of HOOK_NAMES) {
+    const rel = `${HOOKS_PATH}/${name}`
+    const path = join(repoRoot, rel)
+    if (!existsSync(path)) {
+      add(`hook:${name}`, `${rel} is missing — ${INSTALL_HINT}`)
+    } else if (readFileSync(path, 'utf8') !== stubText(name)) {
+      add(`hook:${name}`, `${rel} differs from the installed stub — ${INSTALL_HINT}`)
+    } else if ((lstatSync(path).mode & 0o111) === 0) {
+      add(`hook:${name}`, `${rel} is not executable — ${INSTALL_HINT}`)
+    }
+  }
+
+  for (const finding of checkGitignoreBlock(repoRoot).findings) add(finding.id, finding.message)
+
+  const lockVersion = lock?.version ?? null
+  if (lockVersion !== null && lockVersion !== VERSION) {
+    add('version', `lock written by ${lockVersion}, running ${VERSION} — ${INSTALL_HINT}`)
+  }
+
+  return { repo: repoRoot, ok: findings.length === 0, packageVersion: VERSION, lockVersion, findings }
+}

package/packages/repo-controls/src/worktree-guard.ts

@@ -0,0 +1,272 @@
+/**
+ * The `post-checkout` worktree-count backstop (STATUS.md item 2, adl-m3-items,
+ * 2026-09-27 — "add a hook to detect existing worktrees and deny worktree
+ * creation — maximum worktrees allowed is 3 including the main folder").
+ *
+ * Git has no pre-worktree hook: nothing runs BEFORE `git worktree add` creates
+ * the new checkout. What git DOES run is `post-checkout`, and — per git's own
+ * documented behaviour — a `git worktree add` invokes it INSIDE THE NEW
+ * WORKTREE with the previous-HEAD argument set to the all-zero OID and the
+ * third (branch-checkout) argument set to `1`. `isWorktreeAddCheckout` below
+ * is that exact signature. (The same all-zero-previous-HEAD/flag=1 signature
+ * also fires for an ordinary `git clone`/`git init` first checkout in the MAIN
+ * working tree — `guardPostCheckout` tells the two apart by checking whether
+ * this checkout's own `--git-dir` differs from the repository's shared
+ * `--git-common-dir`; only a LINKED worktree's git-dir differs from the common
+ * one, so a fresh clone's own first checkout is correctly left alone.)
+ *
+ * Since this hook cannot run before the worktree exists, "deny" here means:
+ * let the worktree get created, count what `git worktree list` now reports,
+ * and if that is over the limit, actively remove the JUST-CREATED worktree
+ * with `git worktree remove --force <path>` — run from the MAIN worktree,
+ * because git refuses to remove the worktree a process's own cwd is inside —
+ * and exit non-zero. `git worktree add` itself then reports failure to
+ * whoever ran it (human or agent), and no 4th worktree survives on disk.
+ *
+ * Branch deletion (`git worktree add -b <branch>`): deliberately NOT
+ * attempted. Proving "this exact command is what created this branch, it
+ * points at the same commit, and nothing else already depends on it" is not
+ * something this hook's own inputs (three positional git-worktree-add
+ * arguments plus the post-facto `git worktree list --porcelain` state) can
+ * establish safely — the branch ref already exists by the time post-checkout
+ * runs, indistinguishable here from a branch that existed before this command
+ * and was merely checked out into a new worktree. Per the task's own
+ * instruction ("if that can't be proven safely, leave the branch and say
+ * so"), the branch is always left in place; only the worktree directory and
+ * its registration are removed.
+ *
+ * `-C <dir>` is not a thing for `git worktree add` (there is no per-command
+ * remote repository to redirect to the way `git push` has); the checkout this
+ * hook reasons about is always the one the hook is itself running in, which
+ * `runHook` (`./hook.ts`) has already resolved via `git rev-parse
+ * --show-toplevel` from the hook's own cwd before any hook-specific branch —
+ * see `postCheckoutWorktreeGuardStep` below.
+ */
+
+import { dirname } from 'node:path'
+import { MAX_WORKTREES } from './worktree-limit.ts'
+import { capture, type Env } from './runtime.ts'
+
+/** A parsed `git worktree list --porcelain` entry. */
+export interface WorktreeEntry {
+  readonly path: string
+  readonly bare: boolean
+  /** Branch name (without `refs/heads/`), or null when the worktree is detached. */
+  readonly branch: string | null
+  readonly headSha: string | null
+}
+
+/**
+ * Parse `git worktree list --porcelain` output.
+ *
+ * Format (per `git-worktree(1)`): one blank-line-separated block per
+ * worktree, each block a sequence of `key[ value]` lines — `worktree <path>`
+ * always first, then any of `HEAD <sha>`, `branch <ref>`, `bare`, `detached`,
+ * `locked[ <reason>]`, `prunable[ <reason>]`. Only the fields this guard
+ * actually consults are extracted; unrecognized lines are ignored rather than
+ * rejected, so a future porcelain field addition cannot break parsing.
+ */
+export function parseWorktreeList(porcelain: string): WorktreeEntry[] {
+  const entries: WorktreeEntry[] = []
+  let path: string | null = null
+  let bare = false
+  let branch: string | null = null
+  let head: string | null = null
+
+  const flush = (): void => {
+    if (path !== null) entries.push({ path, bare, branch, headSha: head })
+    path = null
+    bare = false
+    branch = null
+    head = null
+  }
+
+  for (const raw of porcelain.split('\n')) {
+    const line = raw.trimEnd()
+    if (line === '') {
+      flush()
+      continue
+    }
+    if (line.startsWith('worktree ')) {
+      flush()
+      path = line.slice('worktree '.length)
+    } else if (line === 'bare') {
+      bare = true
+    } else if (line.startsWith('HEAD ')) {
+      head = line.slice('HEAD '.length)
+    } else if (line.startsWith('branch ')) {
+      branch = line.slice('branch '.length).replace(/^refs\/heads\//, '')
+    } else if (line === 'detached') {
+      branch = null
+    }
+  }
+  flush()
+  return entries
+}
+
+export interface PostCheckoutArgs {
+  readonly previousHead: string
+  readonly newHead: string
+  readonly flag: string
+}
+
+/** Git's positional post-checkout args: `$1 $2 $3` = previous HEAD, new HEAD, branch-checkout flag. */
+export function parsePostCheckoutArgs(args: readonly string[]): PostCheckoutArgs | null {
+  const [previousHead, newHead, flag] = args
+  if (previousHead === undefined || newHead === undefined || flag === undefined) return null
+  return { previousHead, newHead, flag }
+}
+
+const ALL_ZERO_OID = /^0+$/
+
+/**
+ * `git worktree add`'s post-checkout signature: previous HEAD is the all-zero
+ * OID (there was no previous HEAD in the brand-new worktree) and the
+ * branch-checkout flag is `1`. Matches both SHA-1 (40 zeros) and SHA-256 (64
+ * zeros) object-id lengths by pattern rather than a fixed length.
+ *
+ * Also matches a fresh `git clone`/`git init`'s first checkout in the MAIN
+ * working tree (git fires the identical signature there) — `guardPostCheckout`
+ * excludes that case separately, by git-dir vs git-common-dir, rather than
+ * narrowing this predicate, which is the exact, documented trigger condition
+ * for BOTH cases and should stay literal.
+ */
+export function isWorktreeAddCheckout(args: PostCheckoutArgs): boolean {
+  return args.flag === '1' && ALL_ZERO_OID.test(args.previousHead)
+}
+
+function isMainWorktreeGitDir(commonGitDir: string): string {
+  return commonGitDir.endsWith('/.git') ? dirname(commonGitDir) : commonGitDir
+}
+
+export interface GitResult {
+  readonly code: number
+  readonly stdout: string
+  readonly stderr: string
+}
+
+export interface WorktreeGuardIo {
+  /** The checkout `post-checkout` is running in (the just-created worktree, for a `worktree add`). */
+  readonly cwd: string
+  /** `git rev-parse --path-format=absolute --git-dir`, run from `cwd`. */
+  readonly gitDir: () => GitResult
+  /** `git rev-parse --path-format=absolute --git-common-dir`, run from `cwd`. */
+  readonly gitCommonDir: () => GitResult
+  /** `git worktree list --porcelain`, run from `cwd` (any worktree can list every worktree in the repository). */
+  readonly listWorktrees: () => GitResult
+  /** `git worktree remove --force <targetPath>`, run with cwd = the MAIN worktree (git refuses to remove the worktree a process's own cwd is inside). */
+  readonly removeWorktree: (mainWorktreePath: string, targetPath: string) => GitResult
+}
+
+export type WorktreeGuardOutcome =
+  | { readonly kind: 'not-applicable' }
+  | { readonly kind: 'within-limit'; readonly count: number }
+  | { readonly kind: 'removed'; readonly message: string }
+  | { readonly kind: 'remove-failed'; readonly message: string }
+  | { readonly kind: 'indeterminate'; readonly message: string }
+
+const worktreeLimitMessage = (entries: readonly WorktreeEntry[], maxWorktrees: number): string =>
+  `worktree limit: this repository already has ${entries.length} checkouts (max ${maxWorktrees} including the main folder): ` +
+  `${entries.map((entry) => entry.path).join(', ')}. Reuse an existing checkout or remove one with \`git worktree remove <path>\`.`
+
+/**
+ * The pure decision: given one post-checkout invocation's args and injected
+ * git-command results, what should happen. No process spawning here — see
+ * `postCheckoutWorktreeGuardStep` for the real-I/O wrapper `./hook.ts` calls.
+ */
+export function guardPostCheckout(
+  args: PostCheckoutArgs,
+  io: WorktreeGuardIo,
+  maxWorktrees: number = MAX_WORKTREES,
+): WorktreeGuardOutcome {
+  if (!isWorktreeAddCheckout(args)) return { kind: 'not-applicable' }
+
+  const gitDir = io.gitDir()
+  const commonDir = io.gitCommonDir()
+  if (gitDir.code !== 0 || commonDir.code !== 0) {
+    // Cannot even resolve where we are. No known main-worktree path to run a
+    // removal from, and git itself not answering `rev-parse` is a far more
+    // fundamental problem than this guard can repair — fail closed (non-zero
+    // exit) but do not guess at a removal command that would likely also fail.
+    return {
+      kind: 'indeterminate',
+      message:
+        'worktree limit: could not resolve this checkout\'s git directory ' +
+        `(\`git rev-parse --git-dir\`/\`--git-common-dir\` failed: ${(gitDir.stderr || commonDir.stderr).trim()}). ` +
+        'Failing closed: this worktree is NOT verified to be within the limit and was left in place — check and remove it manually if needed.',
+    }
+  }
+
+  const thisGitDir = gitDir.stdout.trim()
+  const commonGitDir = commonDir.stdout.trim()
+  if (thisGitDir === commonGitDir) {
+    // We are in the MAIN worktree — see isWorktreeAddCheckout's doc for why a
+    // fresh clone/init also reaches here with the same args signature.
+    return { kind: 'not-applicable' }
+  }
+  const mainWorktreePath = isMainWorktreeGitDir(commonGitDir)
+
+  const listed = io.listWorktrees()
+  if (listed.code !== 0) {
+    // We know where the main worktree is, so still fail closed by removing
+    // the just-created one, even without a verified count — "the count can't
+    // be determined" is deny, per the task's own instruction, not "assume
+    // it's fine".
+    const removed = io.removeWorktree(mainWorktreePath, io.cwd)
+    const base =
+      'worktree limit: could not determine the current worktree count ' +
+      `(\`git worktree list --porcelain\` failed: ${listed.stderr.trim()}). Failing closed.`
+    if (removed.code !== 0) {
+      return {
+        kind: 'remove-failed',
+        message: `${base} Removal also failed (${removed.stderr.trim()}) — this worktree may still be present; remove it manually.`,
+      }
+    }
+    return { kind: 'removed', message: `${base} The just-created worktree at ${io.cwd} was removed.` }
+  }
+
+  const entries = parseWorktreeList(listed.stdout)
+  if (entries.length <= maxWorktrees) return { kind: 'within-limit', count: entries.length }
+
+  const message = worktreeLimitMessage(entries, maxWorktrees)
+  const removed = io.removeWorktree(mainWorktreePath, io.cwd)
+  if (removed.code !== 0) {
+    return {
+      kind: 'remove-failed',
+      message: `${message} (Removal itself failed: ${removed.stderr.trim()} — the checkout may still be present on disk; remove it manually with \`git worktree remove --force ${io.cwd}\`, run from ${mainWorktreePath}.)`,
+    }
+  }
+  return { kind: 'removed', message }
+}
+
+export function worktreeGuardExitCode(outcome: WorktreeGuardOutcome): number {
+  return outcome.kind === 'not-applicable' || outcome.kind === 'within-limit' ? 0 : 1
+}
+
+/** Real-I/O wrapper: builds `WorktreeGuardIo` from real `git` calls and reports through `context.err`. */
+export function postCheckoutWorktreeGuardStep(
+  repo: string,
+  hookArgs: readonly string[],
+  context: { env: Env; err: (line: string) => void },
+): number {
+  const args = parsePostCheckoutArgs(hookArgs)
+  // Malformed/missing positional args never come from real git (it always
+  // passes exactly three); treat as not-our-business rather than denying an
+  // ordinary checkout over an unexpected invocation shape.
+  if (!args) return 0
+
+  const io: WorktreeGuardIo = {
+    cwd: repo,
+    gitDir: () => capture(['git', 'rev-parse', '--path-format=absolute', '--git-dir'], repo, context.env),
+    gitCommonDir: () => capture(['git', 'rev-parse', '--path-format=absolute', '--git-common-dir'], repo, context.env),
+    listWorktrees: () => capture(['git', 'worktree', 'list', '--porcelain'], repo, context.env),
+    removeWorktree: (mainWorktreePath, targetPath) =>
+      capture(['git', 'worktree', 'remove', '--force', targetPath], mainWorktreePath, context.env),
+  }
+
+  const outcome = guardPostCheckout(args, io)
+  if (outcome.kind !== 'not-applicable' && outcome.kind !== 'within-limit') {
+    context.err(`post-checkout: FAIL — ${outcome.message}`)
+  }
+  return worktreeGuardExitCode(outcome)
+}

package/packages/repo-controls/src/worktree-limit.ts

@@ -0,0 +1,11 @@
+/**
+ * Maximum number of `git worktree list` entries a repository may have at once,
+ * counting the main working tree itself — so at most 2 linked worktrees beyond
+ * the main checkout. Enforced by `worktree-guard.ts`'s `post-checkout` hook and
+ * by `adl worktree add`.
+ *
+ * Kept in its own module with no imports: `constants.ts` reads `package.json`
+ * from disk when it loads, which a `bun build --compile` binary (the `adl` CLI)
+ * cannot do, so the CLI imports the limit from here, never from `constants.ts`.
+ */
+export const MAX_WORKTREES = 3

package/packages/repo-controls/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts", "bin/**/*.ts"]
+}

package/packages/repo-controls/workflows/scripts/release/verify-npm-artifact.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+/**
+ * Proves that an immutable npm version is the artifact built from this exact
+ * commit. A matching semantic version is not enough: npm never replaces a
+ * published version, so a prior publication from another commit must stop the
+ * release rather than make a later pipeline run look green.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { isAbsolute, join, normalize, resolve } from 'node:path'
+
+interface Metadata {
+  version?: unknown
+  gitHead?: unknown
+  'dist.tarball'?: unknown
+}
+
+interface Arguments {
+  packageName: string
+  version: string
+  gitHead: string
+  source: string
+}
+
+const usage =
+  'usage: bun workflows/scripts/release/verify-npm-artifact.ts --package <npm-package> --version <version> --git-head <build-source-version> --source <repo-relative-source-path>'
+
+const fail = (message: string): never => {
+  throw new Error(message)
+}
+
+function parseArguments(argv: string[]): Arguments {
+  const values = new Map<string, string>()
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index]
+    const value = argv[index + 1]
+    if (flag === undefined || value === undefined || !['--package', '--version', '--git-head', '--source'].includes(flag) || values.has(flag)) {
+      fail(usage)
+    }
+    values.set(flag, value)
+  }
+  const packageName = values.get('--package')
+  const version = values.get('--version')
+  const gitHead = values.get('--git-head')
+  const source = values.get('--source')
+  if (packageName === undefined || version === undefined || gitHead === undefined || source === undefined || values.size !== 4) fail(usage)
+  return { packageName, version, gitHead, source }
+}
+
+function command(commandName: string, args: string[]): { stdout: string; stderr: string } {
+  const result = Bun.spawnSync([commandName, ...args], { stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
+  const stdout = result.stdout.toString()
+  const stderr = result.stderr.toString()
+  if ((result.exitCode ?? 1) !== 0) {
+    fail(`${commandName} failed while verifying the published artifact${stderr.trim() === '' ? '' : `: ${stderr.trim()}`}`)
+  }
+  return { stdout, stderr }
+}
+
+function metadataFor(packageName: string, version: string): Metadata {
+  const { stdout } = command('npm', ['view', `${packageName}@${version}`, 'version', 'gitHead', 'dist.tarball', '--json'])
+  try {
+    return JSON.parse(stdout) as Metadata
+  } catch {
+    fail('npm returned malformed package metadata while verifying the published artifact')
+  }
+}
+
+function sourcePath(source: string): string {
+  if (isAbsolute(source) || source === '' || source.split(/[\\/]/).some((segment) => segment === '..' || segment === '')) {
+    fail(`source must be a non-empty repository-relative path: ${source}`)
+  }
+  const root = resolve(process.cwd())
+  const path = resolve(root, normalize(source))
+  if (!path.startsWith(`${root}/`) || !existsSync(path)) fail(`source file does not exist: ${source}`)
+  return path
+}
+
+function httpsTarball(value: string): string {
+  try {
+    if (new URL(value).protocol !== 'https:') fail('published dist.tarball must be an HTTPS URL')
+  } catch (error) {
+    if (error instanceof Error && error.message === 'published dist.tarball must be an HTTPS URL') throw error
+    fail('published dist.tarball must be an HTTPS URL')
+  }
+  return value
+}
+
+function main(): void {
+  const args = parseArguments(process.argv.slice(2))
+  const localSource = sourcePath(args.source)
+  const metadata = metadataFor(args.packageName, args.version)
+  if (metadata.version !== args.version) fail(`published version mismatch: expected ${args.version}, received ${String(metadata.version)}`)
+  if (metadata.gitHead !== args.gitHead) fail(`published gitHead mismatch: expected ${args.gitHead}, received ${String(metadata.gitHead)}`)
+  const tarball = metadata['dist.tarball']
+  if (typeof tarball !== 'string' || tarball === '') fail('published package metadata has no dist.tarball')
+  const verifiedTarball = httpsTarball(tarball)
+
+  const scratchRoot = join(process.cwd(), '.scratchpad')
+  mkdirSync(scratchRoot, { recursive: true })
+  const temporary = mkdtempSync(join(scratchRoot, 'release-artifact-'))
+  const archive = join(temporary, 'package.tgz')
+  try {
+    command('curl', ['--fail', '--location', '--silent', '--show-error', '--output', archive, '--', verifiedTarball])
+    const packed = command('tar', ['-xOzf', archive, `package/${args.source}`]).stdout
+    const local = readFileSync(localSource)
+    if (!Buffer.from(packed).equals(local)) fail(`published packed source mismatch: package/${args.source} does not match this checkout`)
+  } finally {
+    rmSync(temporary, { recursive: true, force: true })
+  }
+
+  console.log(`verified ${args.packageName}@${args.version}: gitHead and package/${args.source} match this checkout`)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`release artifact verification failed: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}