@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/metadata-sync.mjs

@@ -0,0 +1,1538 @@
+#!/usr/bin/env node
+// metadata-sync — post-release metadata adapter for the verified-SHA GitHub Flow mode (#800).
+//
+// verified-sha-github-flow.md already requires: after the final tag, open a PR against current
+// main that cuts the CHANGELOG section and synchronizes package version metadata, preserving
+// newer unreleased work. Nothing ran it. identity v0.4.1 shipped with package.json still at
+// 0.2.0 and no CHANGELOG [0.4.1] until a hand-rolled PR (identity#678).
+//
+// This script is that adapter:
+//   metadata-sync.mjs plan  — compute the file edits (CHANGELOG + package versions)
+//   metadata-sync.mjs open  — isolate and reconcile the exact branch, commit, and PR
+//   metadata-sync.mjs record-delivery — prove the merge, then record canonical merged state
+//   metadata-sync.mjs na    — record an explicit n/a with reason (required for completeness)
+//
+// Pure helpers are exported so the unit suite can pin the planning/recording surface without
+// a network. The CLI injects git/gh runners for the open path; tests pass stubs.
+//
+// FAIL CLOSED: open without --version/--sha is usage (exit 2). n/a without a reason is exit 2.
+// An opened record without a PR number/url is incomplete (validateMetadataPr). A released
+// attempt without metadataPr is incomplete in report.mjs — that is the handoff half.
+//
+// Doctrine: references/verified-sha-github-flow.md § Final claim and metadata ordering.
+// Regression: identity-v0.4.1 · identity#677 (CF Insights) · identity#678 (metadata PR).
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { spawnSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { createHash } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import {
+  insertSection,
+  renderChangelogSection,
+} from './version.mjs'
+import { METADATA_SYNC_SOURCE } from './metadata-pr-status.mjs'
+import { RELEASE_STATE_CONTRACT } from '../../resolve-issues/scripts/release-state-contract.mjs'
+
+const VERSION_SCRIPT = fileURLToPath(new URL('./version.mjs', import.meta.url))
+
+export const USAGE = `metadata-sync — post-release metadata adapter (verified-sha-github-flow).
+
+After the final release claim, open a PR against current main that cuts the CHANGELOG
+section and bumps declared package version files, then record release.metadataPr on the
+manifest. A released attempt without that record is incomplete unless status is n/a with
+a reason (report.mjs).
+  plan  --version <v> --date <YYYY-MM-DD> [--changes <json>] [--package-file <path>]...
+        [--cwd <dir>] [--changelog <path>] [--dry-run]
+      Compute the file edits. Prints JSON {version, branch, changelog, packages}.
+
+  open  --manifest <run.json> --version <v> --sha <shipped> --date <YYYY-MM-DD>
+        [--changes <json-or-safe-relative-file>] [--package-file <path>]... [--cwd <dir>] [--changelog <path>]
+        [--repo <owner/name>] [--base <branch=main>] [--branch <name>]
+        [--title <t>] [--body <b>]
+        [--lock-file <path> --lock-command <repository-command>]
+        [--dry-run] [--record-plan]
+      Build from fresh origin/<base> in a disposable worktree. Reconcile exact repo,
+      base, branch, version, shipped SHA, expected content, commit, and PR identities;
+      refuse divergence without force. Metadata paths must be normalized, single-link
+      regular repository files (symlinks/non-regular files are rejected); a missing,
+      unparseable, or unsupported package fails closed, while a missing CHANGELOG is
+      created in the commit. Planned bytes go directly to a disposable Git index and
+      private execution tree, never caller metadata pathnames. Requested package/lock
+      versions are verified before and after ordinary commit hooks. Push is ordinary;
+      only a known Mergify pre-push rejection receives one --no-verify retry. The
+      manifest must live outside the caller repository.
+      --dry-run skips git/gh; with --record-plan also writes status:"planned".
+
+
+  record-delivery  --manifest <run.json> --watch-result <watcher.json> [--cwd <dir>]
+      Consume terminal JSON from watch-pr-delivery.mjs, then independently re-read the
+      exact PR and prove commit->merge->fresh-base ancestry plus expected file hashes
+      before recording release.metadataPr.status="merged" through the canonical contract.
+
+  na    --manifest <run.json> --reason <text> [--version <v>]
+      Record release.metadataPr = {status:"n/a", reason} (reason REQUIRED).
+
+  migrate  --manifest <run.json>
+      Convert a legacy hand-written release.metadataSync record into a canonical
+      release.metadataPr with source metadata-sync.mjs. Reject-only by default; this
+      is the opt-in migration path.
+
+Exit codes:
+  0  ok
+  1  open/plan failed (git/gh non-zero, incomplete PR record)
+  2  usage / unreadable input
+
+Why: identity v0.4.1 shipped without the adapter; metadata landed as identity#678.
+See references/verified-sha-github-flow.md and issue #800.`
+
+// ---- pure planning / recording --------------------------------------------------------------
+
+export function defaultBranchName(version) {
+  return `chore/release-metadata-${String(version).replace(/^v/, '')}`
+}
+
+// ---- package-file parsers -------------------------------------------------------------------
+//
+// Supported version metadata: JSON (`{"version": ...}`) and TOML with a `version` key in
+// the `[project]` or `[tool.poetry]` table (PEP 621 / Poetry). Anything else fails closed
+// with an unsupported-format error — the adapter never guesses at a format it cannot verify.
+
+const TOML_VERSION_TABLES = new Set(['project', 'tool.poetry'])
+
+export function packageParserFor(rel) {
+  const base = path.basename(String(rel)).toLowerCase()
+  if (base.endsWith('.json')) return 'json'
+  // uv.lock / Cargo.lock are TOML; parsing them as TOML lets a lock requested directly
+  // fail with the actionable "use --lock-file/--lock-command" unsupported-format error.
+  if (base.endsWith('.toml') || base.endsWith('.lock')) return 'toml'
+  return null
+}
+
+// Minimal line-based TOML reader for the version-metadata subset. Returns
+// { version, name, line } (line = index of the version assignment) or null when no
+// supported table carries a version key.
+export function parseTomlMetadata(raw) {
+  const lines = String(raw).split('\n')
+  let table = null
+  let name = null
+  let hit = null
+  for (let i = 0; i < lines.length; i += 1) {
+    const header = lines[i].match(/^\s*\[([^\]]+)\]\s*$/)
+    if (header) {
+      table = header[1].trim()
+      continue
+    }
+    if (table === 'project' && name == null) {
+      const nm = lines[i].match(/^\s*name\s*=\s*(["'])(.*?)\1/)
+      if (nm) name = nm[2]
+    }
+    if (hit == null && TOML_VERSION_TABLES.has(table)) {
+      const vm = lines[i].match(/^\s*version\s*=\s*(["'])(.*?)\1/)
+      if (vm) hit = { version: vm[2], line: i }
+    }
+  }
+  if (!hit) return null
+  return { version: hit.version, name, line: hit.line }
+}
+
+// Rewrite only the version literal on its own line, preserving the rest of the file
+// byte-for-byte. Returns null when the file has no supported version key.
+export function updateTomlVersion(raw, nextVersion) {
+  const parsed = parseTomlMetadata(raw)
+  if (!parsed) return null
+  const lines = String(raw).split('\n')
+  lines[parsed.line] = lines[parsed.line].replace(
+    /^(\s*version\s*=\s*)(["']).*?\2/,
+    `$1$2${nextVersion}$2`,
+  )
+  return lines.join('\n')
+}
+
+// { version, name? } or null when the raw content cannot be read with the given parser.
+function readPackageVersion(raw, parser) {
+  if (parser === 'json') {
+    try {
+      const json = JSON.parse(raw)
+      return {
+        version: json.version != null ? String(json.version) : null,
+        name: json.name != null ? String(json.name) : null,
+      }
+    } catch {
+      return null
+    }
+  }
+  if (parser === 'toml') {
+    const parsed = parseTomlMetadata(raw)
+    return parsed ? { version: parsed.version, name: parsed.name } : null
+  }
+  return null
+}
+
+// Lock verification accepts uv.lock-style TOML and npm package-lock JSON. Both formats
+// must identify the root project and hold the target version; an ambiguous or incomplete
+// root entry never counts as proof.
+export function verifyLockMetadata(raw, { name, version } = {}) {
+  if (!name) {
+    return { ok: false, reason: 'cannot verify lock metadata without a project name' }
+  }
+
+  const text = String(raw)
+  if (text.trimStart().startsWith('{')) {
+    let lock
+    try {
+      lock = JSON.parse(text)
+    } catch {
+      return { ok: false, reason: 'invalid npm package-lock JSON' }
+    }
+    const entries = []
+    if (lock && typeof lock === 'object' && !Array.isArray(lock) && ('name' in lock || 'version' in lock)) {
+      entries.push({ location: 'top-level', name: lock.name, version: lock.version })
+    }
+    const root = lock?.packages?.['']
+    if (root && typeof root === 'object' && !Array.isArray(root) && ('name' in root || 'version' in root)) {
+      entries.push({ location: 'packages[""]', name: root.name, version: root.version })
+    }
+    if (entries.length === 0) {
+      return { ok: false, reason: 'no npm root package metadata entry' }
+    }
+    for (const entry of entries) {
+      if (entry.name == null) {
+        return { ok: false, reason: `npm root package metadata at ${entry.location} is missing name` }
+      }
+      if (String(entry.name) !== name) {
+        return {
+          ok: false,
+          reason: `npm root package at ${entry.location} is named ${JSON.stringify(String(entry.name))}, expected ${JSON.stringify(name)}`,
+        }
+      }
+      if (entry.version == null) {
+        return { ok: false, reason: `npm root package metadata at ${entry.location} is missing version` }
+      }
+      if (String(entry.version) !== version) {
+        return {
+          ok: false,
+          reason: `${name} at ${entry.location} is ${JSON.stringify(String(entry.version))}, expected ${JSON.stringify(version)}`,
+        }
+      }
+    }
+    return { ok: true }
+  }
+
+  let current = null
+  const blocks = []
+  for (const line of text.split('\n')) {
+    if (/^\s*\[\[package\]\]/.test(line)) {
+      current = {}
+      blocks.push(current)
+      continue
+    }
+    if (/^\s*\[/.test(line)) {
+      current = null
+      continue
+    }
+    if (current) {
+      const kv = line.match(/^\s*(name|version)\s*=\s*(["'])(.*?)\2/)
+      if (kv && current[kv[1]] == null) current[kv[1]] = kv[3]
+    }
+  }
+  const entry = blocks.find((b) => b.name === name)
+  if (!entry) {
+    return { ok: false, reason: `no [[package]] entry named ${JSON.stringify(name)}` }
+  }
+  if (entry.version !== version) {
+    return {
+      ok: false,
+      reason: `${name} at ${JSON.stringify(entry.version ?? null)}, expected ${JSON.stringify(version)}`,
+    }
+  }
+  return { ok: true }
+}
+
+export function planMetadataSync({
+  cwd = process.cwd(),
+  version,
+  date,
+  changes = [],
+  packageFiles = ['package.json'],
+  changelogPath = 'CHANGELOG.md',
+  repo = null,
+  branch = null,
+  sources = null,
+} = {}) {
+  if (!version) throw new Error('planMetadataSync: --version is required')
+  if (!date) throw new Error('planMetadataSync: --date is required')
+  const ver = String(version).replace(/^v/, '')
+  if (!sources) sources = filesystemSources(cwd, metadataDeclarations(packageFiles, changelogPath))
+  const absChangelog = path.resolve(cwd, changelogPath)
+  const currentChangelog = sources.get(changelogPath)?.raw ?? ''
+  const section = renderChangelogSection({ version: ver, date, changes, repo })
+  const inserted = insertSection(currentChangelog, section, ver)
+
+  const packages = []
+  for (const rel of packageFiles) {
+    const abs = path.resolve(cwd, rel)
+    const parser = packageParserFor(rel)
+    const source = sources.get(rel)
+    if (!source || source.missing) {
+      packages.push({
+        path: rel, abs, parser, from: null, to: ver,
+        missing: true, noop: false, error: `missing: ${rel}`,
+      })
+      continue
+    }
+    const raw = source.raw
+    if (parser == null) {
+      packages.push({
+        path: rel, abs, parser, from: null, to: ver, noop: false,
+        error: `unsupported-format: ${rel} (supported: .json version field, .toml [project]/[tool.poetry] version)`,
+      })
+      continue
+    }
+    const current = readPackageVersion(raw, parser)
+    if (!current || current.version == null) {
+      packages.push({
+        path: rel, abs, parser, from: null, to: ver, noop: false,
+        error: parser === 'toml'
+          ? `unsupported-format: ${rel} has no version key in [project] or [tool.poetry]; declare a repository command via --lock-file/--lock-command or drop the file`
+          : `unparseable: ${rel} is not valid ${parser} version metadata`,
+      })
+      continue
+    }
+    const from = current.version
+    if (from === ver) {
+      packages.push({ path: rel, abs, parser, from, to: ver, name: current.name, noop: true, next: raw })
+      continue
+    }
+    const next = parser === 'toml'
+      ? updateTomlVersion(raw, ver)
+      : `${JSON.stringify({ ...JSON.parse(raw), version: ver }, null, 2)}\n`
+    if (next == null) {
+      packages.push({
+        path: rel, abs, parser, from, to: ver, noop: false,
+        error: `unsupported-format: could not rewrite version in ${rel}`,
+      })
+      continue
+    }
+    packages.push({ path: rel, abs, parser, from, to: ver, name: current.name, noop: false, next })
+  }
+
+  return {
+    version: ver,
+    date,
+    branch: branch || defaultBranchName(ver),
+    changelogPath,
+    changelog: {
+      path: absChangelog,
+      rel: changelogPath,
+      next: inserted.text,
+      noop: !!inserted.noop,
+    },
+    packages,
+    cwd,
+  }
+}
+
+// Requested package files that could not be planned. open refuses while this is non-empty;
+// plan reports it and exits 1. A missing/unparseable/unsupported file is never a noop.
+export function planPackageErrors(plan) {
+  return (plan?.packages || []).filter((p) => p.error || p.missing)
+}
+
+// Post-apply gate: re-read every requested package file (and the declared lock, if any)
+// from disk and prove it holds the target version. Runs before commit and before
+// release.metadataPr is recorded — a PR record without this proof is the forex#198 bug.
+export function verifyAppliedPlan(plan, { lock } = {}) {
+  const failures = []
+  for (const p of plan?.packages || []) {
+    if (p.error || p.missing) {
+      failures.push(`${p.path}: ${p.error || 'missing'}`)
+      continue
+    }
+    let raw
+    try {
+      raw = fs.readFileSync(path.resolve(plan.cwd, p.path), 'utf8')
+    } catch (err) {
+      failures.push(`${p.path}: unreadable after apply (${err.message})`)
+      continue
+    }
+    const current = readPackageVersion(raw, p.parser)
+    if (!current || current.version !== plan.version) {
+      failures.push(
+        `${p.path}: holds ${JSON.stringify(current?.version ?? null)} after apply, expected ${JSON.stringify(plan.version)}`,
+      )
+    }
+  }
+  if (lock) {
+    let raw = null
+    try {
+      raw = fs.readFileSync(path.resolve(plan.cwd, lock.rel), 'utf8')
+    } catch (err) {
+      failures.push(`${lock.rel}: unreadable after lock command (${err.message})`)
+    }
+    if (raw != null) {
+      const checked = verifyLockMetadata(raw, { name: lock.name, version: plan.version })
+      if (!checked.ok) failures.push(`${lock.rel}: ${checked.reason}`)
+    }
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+// Post-commit gate: re-verify the COMMITTED tree. Commit hooks (pre-commit /
+// commit-msg / prepare-commit-msg) run after the pre-commit verification and can
+// rewrite — and re-stage — requested metadata, so HEAD is no longer proof by
+// construction. `show(rel)` must run `git show HEAD:<rel>` and return the runner
+// result ({ status, stdout, stderr }); fail closed when it is absent, when an entry
+// is unreadable, or when any requested package file / declared lock in HEAD does not
+// hold the target version (#960 round 2 — the recorded PR must never advertise a
+// version the branch does not contain).
+export function verifyCommittedPlan(plan, { lock, show } = {}) {
+  const failures = []
+  if (typeof show !== 'function') {
+    return { ok: false, failures: ['verifyCommittedPlan: a show runner (git show HEAD:<path>) is required'] }
+  }
+  for (const p of plan?.packages || []) {
+    if (p.error || p.missing) {
+      failures.push(`${p.path}: ${p.error || 'missing'}`)
+      continue
+    }
+    const r = show(p.path)
+    if ((r?.status ?? 1) !== 0) {
+      failures.push(`${p.path}: unreadable in committed tree (${String(r?.stderr || r?.stdout || 'git show failed').trim()})`)
+      continue
+    }
+    const current = readPackageVersion(r.stdout || '', p.parser)
+    if (!current || current.version !== plan.version) {
+      failures.push(
+        `${p.path}: committed tree holds ${JSON.stringify(current?.version ?? null)}, expected ${JSON.stringify(plan.version)}`,
+      )
+    }
+  }
+  if (lock) {
+    const r = show(lock.rel)
+    if ((r?.status ?? 1) !== 0) {
+      failures.push(`${lock.rel}: unreadable in committed tree (${String(r?.stderr || r?.stdout || 'git show failed').trim()})`)
+    } else {
+      const checked = verifyLockMetadata(r.stdout || '', { name: lock.name, version: plan.version })
+      if (!checked.ok) failures.push(`${lock.rel}: committed tree: ${checked.reason}`)
+    }
+  }
+  return { ok: failures.length === 0, failures }
+}
+
+
+export function applyMetadataFiles(plan, { runGit } = {}) {
+  if (!plan) throw new Error('applyMetadataFiles: plan required')
+  if (typeof runGit !== 'function') {
+    throw new Error('applyMetadataFiles: a disposable Git index runner is required')
+  }
+  stageMetadataPlan(runGit, plan)
+  return plan
+}
+
+export function validateMetadataPr(meta) {
+  if (!meta || typeof meta !== 'object') {
+    return { ok: false, reason: 'missing release.metadataPr' }
+  }
+  if (meta.status === 'n/a') {
+    if (!meta.reason || !String(meta.reason).trim()) {
+      return { ok: false, reason: 'n/a requires a reason' }
+    }
+    return { ok: true }
+  }
+  if (meta.status === 'opened' || meta.status === 'merged') {
+    if (meta.number == null && !meta.url) {
+      return { ok: false, reason: `${meta.status} requires number or url` }
+    }
+    return { ok: true }
+  }
+  if (meta.status === 'planned') {
+    // dry-run / record-plan intermediate — not complete for handoff, but structurally valid
+    return { ok: true, complete: false }
+  }
+  return { ok: false, reason: `unknown status ${JSON.stringify(meta.status)}` }
+}
+
+export function recordMetadataPr(manifest, entry) {
+  const m = structuredClone(manifest || {})
+  if (!m.release || typeof m.release !== 'object') m.release = {}
+  const checked = validateMetadataPr(entry)
+  if (!checked.ok) throw new Error(`recordMetadataPr: ${checked.reason}`)
+  m.release.metadataPr = {
+    ...entry,
+    source: entry.source || METADATA_SYNC_SOURCE,
+    recordedAt: entry.recordedAt || new Date().toISOString(),
+  }
+  return m
+}
+
+// Opt-in migration from a hand-written `release.metadataSync` to the canonical
+// `release.metadataPr`. Hand-written records do NOT satisfy the completeness gate
+// on their own; this helper lets an operator convert them under adapter control.
+export function migrateMetadataSync(manifest) {
+  const m = manifest || {}
+  const r = m.release || {}
+  const legacy = r.metadataSync
+  if (legacy == null) {
+    throw new Error('migrateMetadataSync: no release.metadataSync to migrate')
+  }
+  if (typeof legacy === 'string') {
+    return {
+      status: 'opened',
+      number: parsePrNumber(legacy),
+      url: legacy,
+      source: METADATA_SYNC_SOURCE,
+    }
+  }
+  if (typeof legacy !== 'object' || Array.isArray(legacy)) {
+    throw new Error(`migrateMetadataSync: cannot migrate metadataSync of this shape (${typeof legacy})`)
+  }
+  if (legacy.status === 'n/a') {
+    return {
+      status: 'n/a',
+      reason: legacy.reason,
+      version: legacy.version || null,
+      source: METADATA_SYNC_SOURCE,
+    }
+  }
+  return {
+    status: 'opened',
+    number: legacy.number != null ? legacy.number : null,
+    url: legacy.url || null,
+    version: legacy.version || null,
+    source: METADATA_SYNC_SOURCE,
+  }
+}
+
+export function parsePrNumber(urlOrText) {
+  const text = String(urlOrText || '')
+  const m = text.match(/\/pull\/(\d+)/) || text.match(/#(\d+)\b/)
+  return m ? Number(m[1]) : null
+}
+
+// ---- CLI ------------------------------------------------------------------------------------
+
+export function parseArgs(argv) {
+  const args = { packageFiles: [], positional: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') args.help = true
+    else if (a === '--manifest') args.manifest = argv[++i]
+    else if (a === '--version') args.version = argv[++i]
+    else if (a === '--sha') args.sha = argv[++i]
+    else if (a === '--date') args.date = argv[++i]
+    else if (a === '--changes') args.changes = argv[++i]
+    else if (a === '--package-file') args.packageFiles.push(argv[++i])
+    else if (a === '--cwd') args.cwd = argv[++i]
+    else if (a === '--changelog') args.changelog = argv[++i]
+    else if (a === '--base') args.base = argv[++i]
+    else if (a === '--branch') args.branch = argv[++i]
+    else if (a === '--title') args.title = argv[++i]
+    else if (a === '--body') args.body = argv[++i]
+    else if (a === '--reason') args.reason = argv[++i]
+    else if (a === '--repo') args.repo = argv[++i]
+    else if (a === '--watch-result') args.watchResult = argv[++i]
+    else if (a === '--lock-file') args.lockFile = argv[++i]
+    else if (a === '--lock-command') args.lockCommand = argv[++i]
+    else if (a === '--dry-run') args.dryRun = true
+    else if (a === '--record-plan') args.recordPlan = true
+    else if (a === '--json') args.json = true
+    else if (a.startsWith('-')) args.unknown = a
+    else args.positional.push(a)
+  }
+  args.cmd = args.positional[0] || null
+  if (args.packageFiles.length === 0) args.packageFiles = ['package.json']
+  return args
+}
+
+function loadJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function parseChanges(raw, cwd, runGit = null) {
+  if (!raw) return []
+  if (raw.startsWith('[') || raw.startsWith('{')) {
+    const parsed = JSON.parse(raw)
+    return Array.isArray(parsed) ? parsed : [parsed]
+  }
+  const rel = safeRelativePath(raw, '--changes file')
+  const declarations = [{ rel, label: '--changes file' }]
+  const materialized = filesystemSources(cwd, declarations).get(rel)
+  const source = runGit ? gitTreeSources(runGit, cwd, declarations).get(rel) : materialized
+  if (!source || source.missing) {
+    throw new Error(`metadata-sync: --changes file ${JSON.stringify(rel)} must exist as a regular repository file`)
+  }
+  const parsed = JSON.parse(source.raw)
+  return Array.isArray(parsed) ? parsed : [parsed]
+}
+
+function defaultRun(cmd, args, { cwd, input } = {}) {
+  return spawnSync(cmd, args, { encoding: 'utf8', cwd, input })
+}
+
+function safeRelativePath(value, label) {
+  if (typeof value !== 'string' || value === '' || path.isAbsolute(value) || path.win32.isAbsolute(value)) {
+    throw new Error(`metadata-sync: ${label} must be a relative path inside the disposable worktree`)
+  }
+  const segments = value.split(/[\\/]/)
+  if (segments.includes('..')) throw new Error(`metadata-sync: ${label} may not contain .. segments`)
+  return value
+}
+
+function assertManifestOutsideCaller(file, cwd, runGit) {
+  const root = checked(runGit(['rev-parse', '--show-toplevel']), 'git rev-parse --show-toplevel').stdout.trim()
+  const rootReal = fs.realpathSync(root)
+  const manifestReal = fs.realpathSync(file)
+  const relative = path.relative(rootReal, manifestReal)
+  const inside = relative === '' || (
+    relative !== '..' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  )
+  if (inside) {
+    throw new Error('metadata-sync: --manifest must live outside the caller repository so caller bytes/status remain unchanged')
+  }
+}
+
+function redact(value) {
+  return String(value || '')
+    .replace(/:\/\/[^\s/@:]+:[^\s/@]+@/g, '://[REDACTED]@')
+    .replace(/(gh[opsu]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,})/g, '[REDACTED]')
+    .trim()
+}
+
+function checked(result, label) {
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(`${label} failed: ${redact(result.stderr || result.stdout || '')}`.trim())
+  }
+  return result
+}
+
+function parseJsonOutput(result, label) {
+  checked(result, label)
+  try {
+    return JSON.parse(String(result.stdout || ''))
+  } catch (error) {
+    throw new Error(`${label} returned invalid JSON on stdout: ${error.message}`)
+  }
+}
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex')
+}
+
+function validateRepo(repo) {
+  if (typeof repo !== 'string' || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
+    throw new Error('metadata-sync: target repo must be an exact owner/name identity')
+  }
+  return repo
+}
+
+function repoFromRemoteUrl(value) {
+  const text = String(value || '').trim().replace(/\.git$/, '')
+  const scp = /^[^@\s]+@[^:]+:(.+)$/.exec(text)
+  if (scp) return scp[1].split('/').slice(-2).join('/')
+  try {
+    const parsed = new URL(text)
+    return parsed.pathname.replace(/^\//, '').split('/').slice(-2).join('/')
+  } catch {}
+  const parts = text.split(/[\\/]/).filter(Boolean)
+  return parts.slice(-2).join('/')
+}
+
+function resolveRef(runGit, ref, cwd) {
+  const result = runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], { cwd })
+  return (result.status ?? 1) === 0 ? String(result.stdout || '').trim() : null
+}
+
+function gitTreeSources(runGit, cwd, declarations) {
+  const sources = new Map()
+  const seen = new Set()
+  for (const declaration of declarations) {
+    const rel = safeRelativePath(declaration.rel, declaration.label)
+    const normalized = path.normalize(rel)
+    if (normalized === '.' || normalized !== rel || rel.includes('\0')) {
+      throw new Error(`metadata-sync: ${declaration.label} must be a normalized relative path`)
+    }
+    if (seen.has(normalized)) {
+      throw new Error(`metadata-sync: metadata path ${JSON.stringify(normalized)} is declared more than once`)
+    }
+    seen.add(normalized)
+    const result = runGit(['ls-tree', '-z', 'HEAD', '--', normalized], { cwd })
+    checked(result, `inspect ${declaration.label}`)
+    const row = String(result.stdout || '')
+    if (!row) {
+      sources.set(normalized, { missing: true, raw: '' })
+      continue
+    }
+    const tab = row.indexOf('\t')
+    const fields = row.slice(0, tab).trim().split(/\s+/)
+    const foundPath = row.slice(tab + 1).replace(/\0$/, '')
+    if (tab < 0 || foundPath !== normalized || fields.length !== 3) {
+      throw new Error(`metadata-sync: ${declaration.label} ${JSON.stringify(normalized)} has ambiguous Git identity`)
+    }
+    const [mode, type, object] = fields
+    if (!['100644', '100755'].includes(mode) || type !== 'blob') {
+      throw new Error(`metadata-sync: ${declaration.label} ${JSON.stringify(normalized)} must be a regular repository file; symlinks and non-regular entries are rejected`)
+    }
+    const raw = checked(runGit(['cat-file', 'blob', object], { cwd }), `read ${declaration.label}`).stdout
+    sources.set(normalized, { missing: false, raw, mode })
+  }
+  return sources
+}
+
+function filesystemSources(cwd, declarations) {
+  if (!fs.constants.O_NOFOLLOW) {
+    throw new Error('metadata-sync: this platform cannot enforce no-follow metadata reads')
+  }
+  const root = path.resolve(cwd)
+  const rootReal = fs.realpathSync(root)
+  const sources = new Map()
+  const seen = new Set()
+  for (const declaration of declarations) {
+    const rel = safeRelativePath(declaration.rel, declaration.label)
+    const normalized = path.normalize(rel)
+    if (normalized === '.' || normalized !== rel || rel.includes('\0')) {
+      throw new Error(`metadata-sync: ${declaration.label} must be a normalized relative path`)
+    }
+    if (seen.has(normalized)) {
+      throw new Error(`metadata-sync: metadata path ${JSON.stringify(normalized)} is declared more than once`)
+    }
+    seen.add(normalized)
+    const abs = path.join(root, normalized)
+    let parent = path.dirname(abs)
+    let missingParent = false
+    while (true) {
+      let stat
+      try {
+        stat = fs.lstatSync(parent, { bigint: true })
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error
+        missingParent = true
+        parent = path.dirname(parent)
+        continue
+      }
+      const relative = path.relative(rootReal, fs.realpathSync(parent))
+      const contained = relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+      if (stat.isSymbolicLink() || !stat.isDirectory() || !contained) {
+        throw new Error(`metadata-sync: parent of ${declaration.label} ${JSON.stringify(normalized)} must be a contained real directory`)
+      }
+      if (parent === root) break
+      parent = path.dirname(parent)
+    }
+    if (missingParent) {
+      sources.set(normalized, { missing: true, raw: '' })
+      continue
+    }
+    let before
+    try {
+      before = fs.lstatSync(abs, { bigint: true })
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+      sources.set(normalized, { missing: true, raw: '' })
+      continue
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1n) {
+      throw new Error(`metadata-sync: ${declaration.label} ${JSON.stringify(normalized)} must be a single-link regular file; symlinks and non-regular files are rejected`)
+    }
+    const targetRelative = path.relative(rootReal, fs.realpathSync(abs))
+    if (targetRelative === '..' || targetRelative.startsWith(`..${path.sep}`) || path.isAbsolute(targetRelative)) {
+      throw new Error(`metadata-sync: ${declaration.label} ${JSON.stringify(normalized)} escapes the workspace`)
+    }
+    const fd = fs.openSync(abs, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+    try {
+      const opened = fs.fstatSync(fd, { bigint: true })
+      if (!opened.isFile() || opened.nlink !== 1n || opened.dev !== before.dev || opened.ino !== before.ino) {
+        throw new Error(`metadata-sync: ${declaration.label} ${JSON.stringify(normalized)} changed during validation`)
+      }
+      sources.set(normalized, { missing: false, raw: fs.readFileSync(fd, 'utf8') })
+    } finally {
+      fs.closeSync(fd)
+    }
+  }
+  return sources
+}
+function writePlannedMetadataFiles(plan, cwd) {
+  const entries = [
+    { rel: plan.changelog.rel, next: plan.changelog.next, noop: plan.changelog.noop },
+    ...plan.packages.map((item) => ({ rel: item.path, next: item.next, noop: item.noop || item.missing || item.error })),
+  ]
+  for (const entry of entries) {
+    if (entry.noop) continue
+    const target = path.resolve(cwd, entry.rel)
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.writeFileSync(target, entry.next)
+  }
+}
+
+function createDryRunExecutionTree(cwd, plan) {
+  const executionTree = fs.mkdtempSync(path.join(os.tmpdir(), 'metadata-sync-dry-run-'))
+  try {
+    fs.cpSync(cwd, executionTree, {
+      recursive: true,
+      filter(source) {
+        const relative = path.relative(cwd, source)
+        const firstSegment = relative.split(path.sep)[0]
+        return !['.git', 'node_modules'].includes(firstSegment)
+      },
+    })
+    writePlannedMetadataFiles(plan, executionTree)
+    return executionTree
+  } catch (error) {
+    fs.rmSync(executionTree, { recursive: true, force: true })
+    throw error
+  }
+}
+
+function runLockCommandAndVerify({ lockFile, lockCommand, plan, cwd, exec, stageLock = null }) {
+  if (!lockFile) return null
+  const lockRel = safeRelativePath(lockFile, '--lock-file')
+  const source = filesystemSources(cwd, [{ rel: lockRel, label: '--lock-file' }]).get(lockRel)
+  const lockBefore = source?.missing ? null : source.raw
+  const lockResult = exec(lockCommand, { cwd })
+  if ((lockResult.status ?? 1) !== 0) {
+    throw new Error(`metadata-sync: lock command failed (${lockCommand}): ${redact(lockResult.stderr || lockResult.stdout)}`)
+  }
+  const generated = filesystemSources(cwd, [{ rel: lockRel, label: '--lock-file' }]).get(lockRel)
+  if (!generated || generated.missing) {
+    throw new Error(`metadata-sync: declared lock ${lockRel} is missing after lock command`)
+  }
+  const name = plan.packages.find((item) => item.name)?.name || null
+  const lock = { rel: lockRel, raw: generated.raw, name }
+  if (generated.raw !== lockBefore && stageLock) stageLock(lock)
+  return lock
+}
+
+function versionChangelogPlan({ cwd, version, date, changes, repo, base, changelogRaw, runVersion }) {
+  const result = runVersion([
+    VERSION_SCRIPT, 'changelog', '--target-branch', base, '--production-branch', base,
+    '--version', version, '--date', date, '--changes', JSON.stringify(changes),
+    '--repo', repo, '--file', '-', '--dry-run', '--format', 'json',
+  ], { cwd, input: Buffer.from(changelogRaw) })
+  const payload = parseJsonOutput(result, 'version changelog --dry-run --format json')
+  const normalizedVersion = String(version).replace(/^v/, '')
+  if (payload.version !== normalizedVersion || payload.file !== '-' || typeof payload.markdown !== 'string') {
+    throw new Error('metadata-sync: version changelog JSON does not match the requested version/file contract')
+  }
+  return payload
+}
+
+function planFromSources({ cwd, version, date, changes, packageFiles, changelogPath, repo, branch, base, runVersion, sources }) {
+  const safeChangelog = safeRelativePath(changelogPath, '--changelog')
+  const safePackages = packageFiles.map((item) => safeRelativePath(item, '--package-file'))
+  const changelog = versionChangelogPlan({
+    cwd, version, date, changes, repo, base,
+    changelogRaw: sources.get(safeChangelog)?.raw ?? '', runVersion,
+  })
+  const plan = planMetadataSync({
+    cwd, version, date, changes: [], packageFiles: safePackages,
+    changelogPath: safeChangelog, repo, branch, sources,
+  })
+  plan.cwd = cwd
+  plan.changelog.next = changelog.markdown
+  plan.changelog.noop = changelog.noop
+  return plan
+}
+
+function metadataDeclarations(packageFiles, changelogPath, lockFile = null) {
+  return [
+    { rel: changelogPath, label: '--changelog' },
+    ...packageFiles.map((rel) => ({ rel, label: '--package-file' })),
+    ...(lockFile ? [{ rel: lockFile, label: '--lock-file' }] : []),
+  ]
+}
+
+function planInWorkspace(options) {
+  const sources = filesystemSources(
+    options.cwd,
+    metadataDeclarations(options.packageFiles, options.changelogPath, options.lockFile),
+  )
+  return planFromSources({ ...options, sources })
+}
+
+function planFromGitTree(runGit, options) {
+  const declarations = metadataDeclarations(options.packageFiles, options.changelogPath, options.lockFile)
+  filesystemSources(options.cwd, declarations)
+  const sources = gitTreeSources(runGit, options.cwd, declarations)
+  return planFromSources({ ...options, sources })
+}
+
+function stageMetadataPlan(runGit, plan) {
+  const entries = [
+    { rel: plan.changelog.rel, next: plan.changelog.next, noop: plan.changelog.noop },
+    ...plan.packages.map((item) => ({ rel: item.path, next: item.next, noop: item.noop || item.missing || item.error })),
+  ]
+  for (const entry of entries) {
+    if (entry.noop) continue
+    const blob = checked(
+      runGit(['hash-object', '-w', '--stdin'], { cwd: plan.cwd, input: entry.next }),
+      `stage metadata blob ${entry.rel}`,
+    ).stdout.trim()
+    if (!/^[0-9a-f]{40,64}$/.test(blob)) {
+      throw new Error(`metadata-sync: invalid blob identity for ${entry.rel}`)
+    }
+    checked(
+      runGit(['update-index', '--add', '--cacheinfo', `100644,${blob},${entry.rel}`], { cwd: plan.cwd }),
+      `stage metadata path ${entry.rel}`,
+    )
+  }
+}
+
+function contentIdentity(plan, lock = null) {
+  const entries = [
+    { path: plan.changelog.rel, content: plan.changelog.next },
+    ...plan.packages
+      .filter((item) => !item.missing && !item.error)
+      .map((item) => ({ path: item.path, content: item.next })),
+    ...(lock ? [{ path: lock.rel, content: lock.raw }] : []),
+  ]
+  return entries.sort((left, right) => left.path.localeCompare(right.path)).map((entry) => ({
+    path: entry.path,
+    sha256: sha256(Buffer.from(entry.content)),
+  }))
+}
+function assertCommitIdentity(runGit, { cwd, commit, baseSha, changedPaths, content, title, body }) {
+  const row = checked(runGit(['rev-list', '--parents', '-n', '1', commit], { cwd }), `inspect commit ${commit}`).stdout.trim().split(/\s+/)
+  if (row.length !== 2) {
+    throw new Error(`metadata-sync: commit ${commit} must have exactly one parent`)
+  }
+  if ((runGit(['merge-base', '--is-ancestor', row[1], baseSha], { cwd }).status ?? 1) !== 0) {
+    throw new Error(`metadata-sync: commit ${commit} is not based on an ancestor of fresh base ${baseSha}`)
+  }
+  const changed = checked(
+    runGit(['diff-tree', '--no-commit-id', '--name-only', '-r', commit], { cwd }),
+    `inspect changed paths ${commit}`,
+  ).stdout.split('\n').filter(Boolean).sort()
+  const expectedPaths = [...changedPaths].sort()
+  if (!sameJson(changed, expectedPaths)) {
+    throw new Error(`metadata-sync: commit ${commit} changed paths do not match expected metadata content`)
+  }
+  for (const expected of content) {
+    const blob = checked(runGit(['show', `${commit}:${expected.path}`], { cwd }), `read ${commit}:${expected.path}`).stdout
+    if (sha256(Buffer.from(blob)) !== expected.sha256) {
+      throw new Error(`metadata-sync: commit ${commit} content diverges at ${expected.path}`)
+    }
+  }
+  const actualMessage = checked(
+    runGit(['show', '-s', '--format=%B', commit], { cwd }),
+    `inspect message ${commit}`,
+  ).stdout.trim()
+  if (actualMessage !== `${title}\n\n${body}`.trim()) {
+    throw new Error(`metadata-sync: commit ${commit} message does not match the exact metadata identity`)
+  }
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(left ?? null) === JSON.stringify(right ?? null)
+}
+
+function assertRecordedIdentity(meta, expected) {
+  if (!meta) return
+  for (const field of ['repo', 'base', 'branch', 'version', 'sha']) {
+    if (meta[field] != null && meta[field] !== expected[field]) {
+      throw new Error(`metadata-sync: recorded ${field} ${JSON.stringify(meta[field])} does not match ${JSON.stringify(expected[field])}`)
+    }
+  }
+  if (meta.content != null && !sameJson(meta.content, expected.content)) {
+    throw new Error('metadata-sync: recorded expected content does not match the current metadata plan')
+  }
+}
+
+function normalizePr(raw) {
+  const headOwner = raw?.headRepositoryOwner?.login || null
+  const headName = raw?.headRepository?.name || null
+  return {
+    number: raw?.number ?? null,
+    url: raw?.url || null,
+    state: raw?.state || null,
+    base: raw?.baseRefName || null,
+    branch: raw?.headRefName || null,
+    commit: raw?.headRefOid || null,
+    repo: raw?.headRepository?.nameWithOwner || (headOwner && headName ? `${headOwner}/${headName}` : null),
+    mergeCommit: raw?.mergeCommit?.oid || null,
+    mergedAt: raw?.mergedAt || null,
+  }
+}
+
+function assertPrCoordinates(pr, expected) {
+  if (pr.repo !== expected.repo || pr.base !== expected.base || pr.branch !== expected.branch) {
+    throw new Error(
+      `metadata-sync: PR identity mismatch for #${pr.number ?? 'unknown'}; ` +
+      `expected ${expected.repo} ${expected.base}<-${expected.branch}`,
+    )
+  }
+  return pr
+}
+
+function assertPrIdentity(pr, expected) {
+  assertPrCoordinates(pr, expected)
+  if (pr.commit !== expected.commit) {
+    throw new Error(
+      `metadata-sync: PR identity mismatch for #${pr.number ?? 'unknown'}; ` +
+      `expected ${expected.repo} ${expected.base}<-${expected.branch}@${expected.commit}`,
+    )
+  }
+  return pr
+}
+
+const PR_FIELDS = 'number,url,state,baseRefName,headRefName,headRefOid,headRepository,headRepositoryOwner,mergeCommit,mergedAt'
+
+function findExistingPr({ gh, cwd, repo, branch, recordedNumber }) {
+  if (recordedNumber != null) {
+    return normalizePr(parseJsonOutput(
+      gh(['pr', 'view', String(recordedNumber), '--repo', repo, '--json', PR_FIELDS], { cwd }),
+      `gh pr view ${recordedNumber}`,
+    ))
+  }
+  const rows = parseJsonOutput(
+    gh(['pr', 'list', '--repo', repo, '--state', 'all', '--head', branch, '--json', PR_FIELDS], { cwd }),
+    'gh pr list',
+  )
+  if (!Array.isArray(rows)) throw new Error('metadata-sync: gh pr list did not return an array')
+  if (rows.length > 1) {
+    throw new Error(`metadata-sync: multiple PRs claim head ${branch}; refusing ambiguous adoption`)
+  }
+  return rows.length === 1 ? normalizePr(rows[0]) : null
+}
+
+function createPr({ gh, cwd, repo, base, branch, title, body }) {
+  const created = checked(gh([
+    'pr', 'create', '--repo', repo, '--base', base, '--head', branch,
+    '--title', title, '--body', body,
+  ], { cwd }), 'gh pr create')
+  const url = String(created.stdout || '').trim().split('\n').filter(Boolean).pop()
+  const number = parsePrNumber(url)
+  if (number == null) throw new Error('metadata-sync: gh pr create returned no parseable PR URL')
+  return findExistingPr({ gh, cwd, repo, branch, recordedNumber: number })
+}
+
+function recordMergedDelivery({ args, cwd, git, gh, now }) {
+  if (!args.manifest || !args.watchResult) {
+    throw new Error('metadata-sync: record-delivery requires --manifest and --watch-result')
+  }
+  const runGit = (gitArgs) => git(gitArgs, { cwd })
+  assertManifestOutsideCaller(args.manifest, cwd, runGit)
+  const originRepo = validateRepo(repoFromRemoteUrl(
+    checked(runGit(['remote', 'get-url', 'origin']), 'git remote get-url origin').stdout,
+  ))
+  if (!RELEASE_STATE_CONTRACT.fields.release.includes('metadataPr')) {
+    throw new Error('metadata-sync: canonical release-state contract does not declare release.metadataPr')
+  }
+  const manifest = loadJson(args.manifest)
+  const meta = manifest?.release?.metadataPr
+  if (!meta || meta.source !== METADATA_SYNC_SOURCE || !['opened', 'merged'].includes(meta.status)) {
+    throw new Error('metadata-sync: record-delivery requires a canonical opened or merged metadataPr record')
+  }
+  for (const field of ['repo', 'base', 'branch', 'commit', 'version', 'sha']) {
+    if (typeof meta[field] !== 'string' || meta[field].trim() === '') {
+      throw new Error(`metadata-sync: opened metadataPr is missing exact ${field} identity`)
+    }
+  }
+  if (!Number.isInteger(meta.number) || !Array.isArray(meta.content) || meta.content.length === 0) {
+    throw new Error('metadata-sync: opened metadataPr requires PR number and expected content')
+  }
+  if (meta.repo !== originRepo) {
+    throw new Error(`metadata-sync: recorded repo ${meta.repo} does not match origin identity ${originRepo}`)
+  }
+  const watcher = loadJson(args.watchResult)
+  if (watcher.outcome !== 'MERGED' || typeof watcher.mergedSha !== 'string' || !/^[0-9a-f]{40}$/.test(watcher.mergedSha)) {
+    throw new Error('metadata-sync: watcher result is not a terminal MERGED verdict with mergedSha')
+  }
+
+  const pr = assertPrIdentity(findExistingPr({
+    gh, cwd, repo: validateRepo(meta.repo), branch: meta.branch, recordedNumber: meta.number,
+  }), meta)
+  if (pr.state !== 'MERGED' || pr.mergeCommit !== watcher.mergedSha || !pr.mergedAt) {
+    throw new Error('metadata-sync: watcher result does not match the fresh merged PR observation')
+  }
+
+  checked(runGit([
+    'fetch', '--quiet', '--no-tags', 'origin',
+    `refs/heads/${meta.base}:refs/remotes/origin/${meta.base}`,
+  ]), `fetch origin ${meta.base}`)
+  const baseSha = resolveRef(runGit, `refs/remotes/origin/${meta.base}`, cwd)
+  const commit = resolveRef(runGit, meta.commit, cwd)
+  const mergedSha = resolveRef(runGit, watcher.mergedSha, cwd)
+  if (commit !== meta.commit || mergedSha !== watcher.mergedSha || !baseSha) {
+    throw new Error('metadata-sync: recorded commit, merge commit, or fresh base does not resolve exactly')
+  }
+  if ((runGit(['merge-base', '--is-ancestor', commit, mergedSha]).status ?? 1) !== 0) {
+    throw new Error('metadata-sync: metadata commit is not an ancestor of the watcher merge commit')
+  }
+  if ((runGit(['merge-base', '--is-ancestor', mergedSha, baseSha]).status ?? 1) !== 0) {
+    throw new Error(`metadata-sync: watcher merge commit is not an ancestor of fresh origin/${meta.base}`)
+  }
+
+  const contentProof = meta.content.map((expected) => {
+    if (typeof expected?.path !== 'string' || !/^[0-9a-f]{64}$/.test(expected?.sha256 || '')) {
+      throw new Error('metadata-sync: malformed expected content identity')
+    }
+    safeRelativePath(expected.path, 'recorded content path')
+    const blob = checked(runGit(['show', `${mergedSha}:${expected.path}`]), `read merged ${expected.path}`).stdout
+    const actual = sha256(Buffer.from(blob))
+    if (actual !== expected.sha256) {
+      throw new Error(`metadata-sync: merged content mismatch for ${expected.path}`)
+    }
+    return { path: expected.path, sha256: actual }
+  })
+  const entry = {
+    ...meta,
+    status: 'merged',
+    mergeCommit: mergedSha,
+    mergedAt: pr.mergedAt,
+    recordedAt: now(),
+    delivery: {
+      watcher: { outcome: 'MERGED', mergedSha },
+      ancestry: { commit, mergeCommit: mergedSha, base: meta.base, baseSha },
+      content: contentProof,
+    },
+  }
+  writeJson(args.manifest, recordMetadataPr(manifest, entry))
+  console.log(JSON.stringify({ ok: true, metadataPr: entry }, null, 2))
+  return 0
+}
+
+function openIsolated({ args, cwd, date, changes, git, gh, exec, runVersion, now }) {
+  const base = args.base || 'main'
+  const branch = args.branch || defaultBranchName(args.version)
+  const runGit = (gitArgs, options = {}) => git(gitArgs, { cwd: options.cwd || cwd, input: options.input })
+  if (!args.manifest) {
+    throw new Error('metadata-sync: open requires --manifest outside the caller repository')
+  }
+  assertManifestOutsideCaller(args.manifest, cwd, runGit)
+  const remoteUrl = checked(runGit(['remote', 'get-url', 'origin']), 'git remote get-url origin').stdout.trim()
+  const derivedRepo = validateRepo(repoFromRemoteUrl(remoteUrl))
+  const repo = validateRepo(args.repo || derivedRepo)
+  if (repo !== derivedRepo) {
+    throw new Error(`metadata-sync: requested repo ${repo} does not match origin identity ${derivedRepo}`)
+  }
+
+  checked(runGit([
+    'fetch', '--quiet', '--no-tags', 'origin',
+    `refs/heads/${base}:refs/remotes/origin/${base}`,
+  ]), `fetch origin ${base}`)
+  const baseSha = resolveRef(runGit, `refs/remotes/origin/${base}`, cwd)
+  if (!baseSha) throw new Error(`metadata-sync: fetched base origin/${base} does not resolve`)
+  const shippedSha = resolveRef(runGit, args.sha, cwd)
+  if (!shippedSha) throw new Error(`metadata-sync: shipped SHA ${JSON.stringify(args.sha)} does not resolve`)
+  if ((runGit(['merge-base', '--is-ancestor', shippedSha, baseSha]).status ?? 1) !== 0) {
+    throw new Error(`metadata-sync: shipped SHA ${shippedSha} is not an ancestor of fresh origin/${base}`)
+  }
+
+  const recorded = loadJson(args.manifest)?.release?.metadataPr || null
+  const existingPr = findExistingPr({
+    gh, cwd, repo, branch, recordedNumber: recorded?.number ?? null,
+  })
+  if (existingPr) {
+    assertPrCoordinates(existingPr, { repo, base, branch })
+    if (existingPr.state !== 'OPEN' || !/^[0-9a-f]{40}$/.test(existingPr.commit || '')) {
+      throw new Error(
+        `metadata-sync: existing PR #${existingPr.number} must be OPEN with an exact head commit; ` +
+        'use record-delivery for a merged PR',
+      )
+    }
+  }
+  runGit([
+    'fetch', '--quiet', '--no-tags', 'origin',
+    `refs/heads/${branch}:refs/remotes/origin/${branch}`,
+  ])
+  runGit(['update-ref', '-d', `refs/remotes/origin/${branch}`])
+  runGit(['fetch', '--quiet', '--no-tags', 'origin', `refs/heads/${branch}:refs/remotes/origin/${branch}`])
+  const remoteCommit = resolveRef(runGit, `refs/remotes/origin/${branch}`, cwd)
+  if (existingPr && !resolveRef(runGit, existingPr.commit, cwd)) {
+    runGit(['fetch', '--quiet', '--no-tags', 'origin', `refs/pull/${existingPr.number}/head`])
+  }
+  const localCommit = resolveRef(runGit, `refs/heads/${branch}`, cwd)
+  const recordedCommit = recorded?.commit || null
+  const prCommit = existingPr?.commit || null
+  const distinctCommits = new Set([localCommit, remoteCommit, recordedCommit, prCommit].filter(Boolean))
+  if (distinctCommits.size > 1) {
+    throw new Error(`metadata-sync: local, remote, recorded, and PR ${branch} artifacts diverge; refusing without force`)
+  }
+  if (prCommit && !resolveRef(runGit, prCommit, cwd)) {
+    throw new Error(`metadata-sync: PR #${existingPr.number} head commit ${prCommit} cannot be fetched exactly`)
+  }
+
+  const worktree = fs.mkdtempSync(path.join(os.tmpdir(), 'metadata-sync-worktree-'))
+  let executionTree = null
+  let keepWorktree = false
+  let published = remoteCommit != null
+  let createdCommit = false
+  try {
+    checked(runGit(['worktree', 'add', '--detach', worktree, baseSha]), 'git worktree add')
+    const worktreeChanges = parseChanges(args.changes, worktree, runGit)
+    const plan = planFromGitTree(runGit, {
+      cwd: worktree,
+      version: args.version,
+      date,
+      changes: worktreeChanges,
+      packageFiles: args.packageFiles,
+      changelogPath: args.changelog || 'CHANGELOG.md',
+      repo,
+      branch,
+      base,
+      runVersion,
+      lockFile: args.lockFile || null,
+    })
+    const packageErrors = planPackageErrors(plan)
+    if (packageErrors.length) {
+      throw new Error(`metadata-sync: refusing to open: ${packageErrors.map((item) => `${item.path} (${item.error})`).join('; ')}`)
+    }
+    filesystemSources(
+      worktree,
+      metadataDeclarations(args.packageFiles, args.changelog || 'CHANGELOG.md', args.lockFile || null),
+    )
+    applyMetadataFiles(plan, { runGit })
+
+    // Commands and ordinary commit hooks run only in this second disposable tree.
+    executionTree = fs.mkdtempSync(path.join(os.tmpdir(), 'metadata-sync-exec-'))
+    const gitDir = checked(
+      runGit(['rev-parse', '--git-dir'], { cwd: worktree }),
+      'resolve disposable Git directory',
+    ).stdout.trim()
+    fs.writeFileSync(path.join(executionTree, '.git'), `gitdir: ${path.resolve(worktree, gitDir)}\n`)
+    checked(
+      runGit(['checkout-index', '-a', '-f'], { cwd: executionTree }),
+      'materialize private metadata execution tree',
+    )
+
+    const lock = runLockCommandAndVerify({
+      lockFile: args.lockFile,
+      lockCommand: args.lockCommand,
+      plan,
+      cwd: executionTree,
+      exec,
+      stageLock({ rel, raw }) {
+        const lockBlob = checked(
+          runGit(['hash-object', '-w', '--stdin'], { cwd: executionTree, input: raw }),
+          `stage lock blob ${rel}`,
+        ).stdout.trim()
+        if (!/^[0-9a-f]{40,64}$/.test(lockBlob)) {
+          throw new Error(`metadata-sync: invalid blob identity for ${rel}`)
+        }
+        checked(
+          runGit(['update-index', '--add', '--cacheinfo', `100644,${lockBlob},${rel}`], { cwd: executionTree }),
+          `stage lock path ${rel}`,
+        )
+      },
+    })
+
+    const beforeCommit = verifyAppliedPlan({ ...plan, cwd: executionTree }, { lock })
+    if (!beforeCommit.ok) {
+      throw new Error(`metadata-sync: verification failed before commit: ${beforeCommit.failures.join('; ')}`)
+    }
+    const changedPaths = checked(
+      runGit(['diff', '--cached', '--name-only'], { cwd: executionTree }),
+      'inspect staged metadata paths',
+    ).stdout.split('\n').filter(Boolean).sort()
+    if (changedPaths.length === 0) {
+      if (args.manifest) {
+        writeJson(args.manifest, recordMetadataPr(loadJson(args.manifest), {
+          status: 'n/a',
+          reason: 'metadata already present on base; nothing to commit',
+          version: plan.version,
+          sha: shippedSha,
+          recordedAt: now(),
+        }))
+      }
+      console.log(JSON.stringify({ ok: true, noop: true, reason: 'nothing to commit' }, null, 2))
+      return 0
+    }
+    const content = contentIdentity(plan, lock)
+    const title = args.title || `chore(release): metadata for v${plan.version}`
+    const body = args.body || [
+      `Post-release metadata sync for \`${plan.version}\` (shipped \`${shippedSha}\`).`,
+      '',
+      'Cuts the CHANGELOG section and bumps package version fields after the final',
+      'release tag, preserving newer unreleased work on main.',
+      '',
+      'Opened by `metadata-sync.mjs` (resolve-release / verified-sha-github-flow).',
+      '',
+      'Refs: identity-v0.4.1 · #800 · identity#678',
+    ].join('\n')
+    assertRecordedIdentity(args.manifest ? loadJson(args.manifest)?.release?.metadataPr : null, {
+      repo, base, branch, version: plan.version, sha: shippedSha, content,
+    })
+
+    let commit = localCommit || remoteCommit || recordedCommit || prCommit
+    if (commit) {
+      assertCommitIdentity(runGit, { cwd: worktree, commit, baseSha, changedPaths, content, title, body })
+    } else {
+      checked(runGit(['commit', '-m', title, '-m', body], { cwd: executionTree }), 'git commit metadata')
+      commit = resolveRef(runGit, 'HEAD', executionTree)
+      createdCommit = true
+      checked(
+        runGit(['update-ref', `refs/heads/${branch}`, commit, '0'.repeat(40)]),
+        `create local branch ${branch}`,
+      )
+    }
+    assertCommitIdentity(runGit, { cwd: worktree, commit, baseSha, changedPaths, content, title, body })
+
+    const postCommitDisk = verifyAppliedPlan({ ...plan, cwd: executionTree }, { lock })
+    const committed = verifyCommittedPlan(plan, {
+      lock,
+      show: (rel) => runGit(['show', `${commit}:${rel}`], { cwd: executionTree }),
+    })
+    if (!postCommitDisk.ok || !committed.ok) {
+      throw new Error(
+        `metadata-sync: post-commit verification failed (a commit hook mutated staged metadata?): ${[...postCommitDisk.failures, ...committed.failures].join('; ')}`,
+      )
+    }
+
+    if (!localCommit && !remoteCommit && (recordedCommit || prCommit)) {
+      checked(
+        runGit(['update-ref', `refs/heads/${branch}`, commit, '0'.repeat(40)]),
+        `restore local branch ${branch}`,
+      )
+    }
+
+    let pushHookBypass = null
+    if (!remoteCommit) {
+      const pushArgs = ['push', 'origin', `refs/heads/${branch}:refs/heads/${branch}`]
+      let pushed = runGit(pushArgs, { cwd: executionTree })
+      if ((pushed.status ?? 1) !== 0) {
+        const output = `${pushed.stderr || ''}\n${pushed.stdout || ''}`.trim()
+        if (/mergify/i.test(output)) {
+          pushHookBypass = 'pre-push'
+          pushed = runGit([...pushArgs, '--no-verify'], { cwd: executionTree })
+          if ((pushed.status ?? 1) !== 0) {
+            throw new Error(`metadata-sync: git push --no-verify failed after known-hook retry: ${redact(pushed.stderr || pushed.stdout)}`)
+          }
+        } else {
+          throw new Error(`metadata-sync: branch push rejected without force: ${redact(output)}`)
+        }
+      }
+      published = true
+    } else if (remoteCommit !== commit) {
+      throw new Error(`metadata-sync: remote ${branch} points at ${remoteCommit}, not exact commit ${commit}`)
+    }
+
+    const expectedPr = { repo, base, branch, commit }
+    let pr = existingPr
+    if (pr) pr = assertPrIdentity(pr, expectedPr)
+    else pr = assertPrIdentity(createPr({ gh, cwd: executionTree, repo, base, branch, title, body }), expectedPr)
+    const entry = {
+      status: 'opened',
+      number: pr.number,
+      url: pr.url,
+      repo,
+      base,
+      branch,
+      commit,
+      content,
+      version: plan.version,
+      sha: shippedSha,
+      recordedAt: now(),
+      ...(pushHookBypass ? { pushHookBypass } : {}),
+    }
+    if (args.manifest) writeJson(args.manifest, recordMetadataPr(loadJson(args.manifest), entry))
+    console.log(JSON.stringify({
+      ok: true,
+      resumed: Boolean(localCommit || remoteCommit || recordedCommit || existingPr),
+      metadataPr: entry,
+      ...(pushHookBypass ? { push: { hookBypass: pushHookBypass } } : {}),
+      ...(lock ? { lock: { file: lock.rel, command: args.lockCommand } } : {}),
+    }, null, 2))
+    return 0
+  } catch (error) {
+    const preservedCommit = resolveRef(runGit, `refs/heads/${branch}`, cwd)
+    if (!published && createdCommit && !preservedCommit) keepWorktree = true
+    if (keepWorktree) {
+      throw new Error(`${error.message}; unpublished metadata worktree retained at ${JSON.stringify(worktree)}`)
+    }
+    if (!published && preservedCommit) {
+      throw new Error(
+        `${error.message}; unpublished metadata commit preserved at refs/heads/${branch} ${preservedCommit}`,
+      )
+    }
+    throw error
+  } finally {
+    if (!keepWorktree) {
+      runGit(['worktree', 'remove', '--force', worktree])
+      fs.rmSync(worktree, { recursive: true, force: true })
+    }
+    if (executionTree) fs.rmSync(executionTree, { recursive: true, force: true })
+  }
+}
+
+export function main(argv, deps = {}) {
+  const args = parseArgs(argv)
+  if (args.help || args.cmd === 'help') {
+    console.log(USAGE)
+    return 0
+  }
+  if (args.unknown) {
+    console.error(`metadata-sync: unknown flag ${args.unknown}`)
+    return 2
+  }
+  if (!args.cmd || !['plan', 'open', 'record-delivery', 'na', 'migrate'].includes(args.cmd)) {
+    console.error('metadata-sync: use plan|open|record-delivery|na|migrate (see --help)')
+    return 2
+  }
+
+  const git = deps.git || ((a, o) => defaultRun('git', a, o))
+  const gh = deps.gh || ((a, o) => defaultRun('gh', a, o))
+  const exec = deps.exec || ((cmd, { cwd: commandCwd } = {}) => spawnSync(cmd, { encoding: 'utf8', cwd: commandCwd, shell: true }))
+  const runVersion = deps.runVersion || ((a, o) => defaultRun(process.execPath, a, o))
+  const now = deps.now || (() => new Date().toISOString())
+  const cwd = args.cwd || process.cwd()
+
+  try {
+    if (args.cmd === 'record-delivery') {
+      return recordMergedDelivery({ args, cwd, git, gh, now })
+    }
+
+    if (args.cmd === 'migrate') {
+      if (!args.manifest) {
+        console.error('metadata-sync: migrate requires --manifest')
+        return 2
+      }
+      const manifest = loadJson(args.manifest)
+      const entry = migrateMetadataSync(manifest)
+      const next = recordMetadataPr(manifest, entry)
+      delete next.release.metadataSync
+      writeJson(args.manifest, next)
+      console.log(JSON.stringify({ ok: true, metadataPr: next.release.metadataPr }, null, 2))
+      return 0
+    }
+
+    if (args.cmd === 'na') {
+      if (!args.manifest) {
+        console.error('metadata-sync: na requires --manifest')
+        return 2
+      }
+      if (!args.reason || !String(args.reason).trim()) {
+        console.error('metadata-sync: na requires --reason <text>')
+        return 2
+      }
+      const manifest = loadJson(args.manifest)
+      const next = recordMetadataPr(manifest, {
+        status: 'n/a',
+        reason: args.reason,
+        version: args.version || null,
+        recordedAt: now(),
+      })
+      writeJson(args.manifest, next)
+      console.log(JSON.stringify({ ok: true, metadataPr: next.release.metadataPr }, null, 2))
+      return 0
+    }
+
+    if (args.cmd === 'plan' || args.cmd === 'open') {
+      if (!args.version) {
+        console.error(`metadata-sync: ${args.cmd} requires --version`)
+        return 2
+      }
+      if (args.cmd === 'open' && !args.sha) {
+        console.error('metadata-sync: open requires --sha <shipped>')
+        return 2
+      }
+      if ((args.lockFile == null) !== (args.lockCommand == null)) {
+        console.error('metadata-sync: --lock-file and --lock-command must be declared together')
+        return 2
+      }
+      const date = args.date || now().slice(0, 10)
+      const changes = args.cmd === 'open' && !args.dryRun
+        ? null
+        : parseChanges(args.changes, cwd)
+
+      if (args.cmd === 'plan') {
+        const plan = planInWorkspace({
+          cwd,
+          version: args.version,
+          date,
+          changes,
+          packageFiles: args.packageFiles,
+          changelogPath: args.changelog || 'CHANGELOG.md',
+          repo: args.repo || null,
+          branch: args.branch || null,
+          base: args.base || 'main',
+          runVersion,
+          lockFile: args.lockFile || null,
+        })
+        console.log(JSON.stringify(plan, null, 2))
+        const packageErrors = planPackageErrors(plan)
+        if (packageErrors.length) {
+          console.error(`metadata-sync: ${packageErrors.length} requested package file(s) failed: ${packageErrors.map((item) => `${item.path} (${item.error})`).join('; ')}`)
+          return 1
+        }
+        return 0
+      }
+
+      const base = args.base || 'main'
+      const branch = args.branch || defaultBranchName(args.version)
+
+      if (args.dryRun) {
+        const plan = planInWorkspace({
+          cwd,
+          version: args.version,
+          date,
+          changes,
+          packageFiles: args.packageFiles,
+          changelogPath: args.changelog || 'CHANGELOG.md',
+          repo: args.repo || null,
+          branch,
+          base,
+          runVersion,
+          lockFile: args.lockFile || null,
+        })
+        const packageErrors = planPackageErrors(plan)
+        if (packageErrors.length) {
+          console.log(JSON.stringify({ dryRun: true, plan }, null, 2))
+          console.error(`metadata-sync: ${packageErrors.length} requested package file(s) failed: ${packageErrors.map((item) => `${item.path} (${item.error})`).join('; ')}`)
+          return 1
+        }
+        let executionTree = null
+        try {
+          if (args.lockFile) {
+            executionTree = createDryRunExecutionTree(cwd, plan)
+            const lock = runLockCommandAndVerify({
+              lockFile: args.lockFile,
+              lockCommand: args.lockCommand,
+              plan,
+              cwd: executionTree,
+              exec,
+            })
+            const verified = verifyAppliedPlan({ ...plan, cwd: executionTree }, { lock })
+            if (!verified.ok) {
+              throw new Error(`metadata-sync: dry-run lock verification failed: ${verified.failures.join('; ')}`)
+            }
+          }
+        } finally {
+          if (executionTree) fs.rmSync(executionTree, { recursive: true, force: true })
+        }
+        if (args.recordPlan && args.manifest) {
+          const manifest = loadJson(args.manifest)
+          const next = recordMetadataPr(manifest, {
+            status: 'planned',
+            version: plan.version,
+            sha: args.sha,
+            branch: plan.branch,
+            recordedAt: now(),
+          })
+          writeJson(args.manifest, next)
+        }
+        console.log(JSON.stringify({ dryRun: true, plan }, null, 2))
+        return 0
+      }
+
+      return openIsolated({
+        args, cwd, date, changes, git, gh, exec, runVersion, now,
+      })
+
+    }
+  } catch (err) {
+    console.error(`metadata-sync: ${err.message || err}`)
+    return err.message && /requires|unknown|use plan/.test(err.message) ? 2 : 1
+  }
+  return 2
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)))
+}