model-eol 0.2.4 → 0.3.0

package/bot/bot.mjs

@@ -0,0 +1,978 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { isDeepStrictEqual } from 'node:util'
+
+import {
+  branchFor,
+  daysRemaining,
+  hasMetadataMarker,
+  itemDigest,
+  markdownCode,
+  markdownLink,
+  markdownText,
+  matchesAnyGlob,
+  metadataLine,
+  parseMetadata,
+  repoPath,
+  sha256,
+} from './lib/common.mjs'
+import { validatePlanItems } from '../lib/apply.mjs'
+import { parseCliArgs } from '../lib/cli.mjs'
+import { loadConfig } from './lib/config.mjs'
+import { downloadFeeds } from './lib/feeds.mjs'
+import { readReportCapped, runEvalHook, reportForBody } from './lib/eval.mjs'
+import { GitHubClient, hasModelEolLabel } from './lib/github.mjs'
+import {
+  cloneRepository,
+  commitAll,
+  configureIdentity,
+  defaultBranch,
+  gitAuthentication,
+  originFor,
+  prepareBranch,
+  pushBranch,
+} from './lib/git.mjs'
+
+const ROOT = path.resolve(import.meta.dirname, '..')
+const CHECKER = path.join(ROOT, 'check.mjs')
+const VENDORED_FEEDS = path.join(ROOT, 'feeds')
+const PLAN_SCHEMA = 'model-eol.plan/0.1'
+const BOT_SCHEMA = 'model-eol.bot/0.1'
+const ISSUE_REASONS = new Set([
+  'not-direct-api',
+  'no-replacement',
+  'replacement-choice',
+  'replacement-unresolved',
+  'replacement-retiring',
+  'publisher-fallback',
+  'unresolved-channel',
+])
+const ACTIONABLE_STATUSES = new Set(['retired', 'retiring'])
+
+const asAbsolute = value => path.resolve(process.cwd(), value)
+
+export const parseArgs = argv => {
+  const { values } = parseCliArgs({
+    args: argv,
+    options: {
+      repo: { type: 'string' },
+      'target-dir': { type: 'string' },
+      config: { type: 'string' },
+      'dry-run': { type: 'boolean' },
+      eval: { type: 'boolean' },
+      'feeds-url': { type: 'string', multiple: true },
+      help: { type: 'boolean', short: 'h' },
+    },
+    help: 'node bot/bot.mjs --help',
+  })
+  const options = {
+    repo: values.repo ?? null,
+    targetDir: values['target-dir'] ?? process.cwd(),
+    configPath: values.config ?? null,
+    dryRun: values['dry-run'] ?? false,
+    evalEnabled: values.eval ?? false,
+    feedsUrls: [],
+    help: values.help ?? false,
+  }
+  for (const value of values['feeds-url'] ?? []) {
+    options.feedsUrls.push(...value.split(',').map(item => item.trim()).filter(Boolean))
+  }
+  return options
+}
+
+export const helpText = () => `model-eol bot
+
+Usage:
+  node bot/bot.mjs [--repo owner/name] [--target-dir PATH] [--config PATH] [--dry-run] [--eval] [--feeds-url URL[,URL...]]
+
+Environment:
+  GITHUB_TOKEN            Required unless --dry-run; authenticates the API and HTTPS Git remotes.
+  GITHUB_API_URL          GitHub API root, default https://api.github.com.
+  MODEL_EOL_TOKEN_KIND    Set to github-token to add the checks warning to PRs.
+`
+
+const validateRepo = repo => {
+  if (!repo || !/^[^/\s]+\/[^/\s]+$/.test(repo)) throw new Error('--repo must be owner/name')
+  return repo
+}
+
+const spawnPlan = ({ workDir, config, configPath = null, feedsDir, checkerPath = CHECKER, warn = console.error }) => {
+  const args = [checkerPath, 'plan', '.', '--days', String(config.days), '--scope', config.scope]
+  if (config.via) args.push('--via', config.via)
+  if (configPath) args.push('--config', configPath)
+  if (feedsDir) args.push('--feeds', feedsDir)
+  const result = spawnSync(process.execPath, args, {
+    cwd: workDir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (result.stderr?.trim()) warn(result.stderr.trim())
+  if (result.error || result.status !== 0) {
+    throw new Error(`plan subprocess failed: ${result.error?.message || result.stderr?.trim() || `exit ${result.status}`}`)
+  }
+  let plan
+  try {
+    plan = JSON.parse(result.stdout)
+  } catch (error) {
+    throw new Error(`plan subprocess did not emit JSON: ${error.message}`)
+  }
+  return validatePlan(plan)
+}
+
+export const runPlan = spawnPlan
+
+const validatePlan = plan => {
+  if (plan?.plan_schema !== PLAN_SCHEMA) {
+    throw new Error(`refusing plan schema ${plan?.plan_schema ?? 'missing'}; expected ${PLAN_SCHEMA}`)
+  }
+  if (!Array.isArray(plan.items) || !Array.isArray(plan.issues)) {
+    throw new Error('refusing malformed plan document: items and issues arrays are required')
+  }
+  try {
+    validatePlanItems(plan.items)
+  } catch (error) {
+    throw new Error(`refusing malformed plan document: ${error.message}`)
+  }
+  return plan
+}
+
+const readPlanFile = file => {
+  let plan
+  try {
+    plan = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`could not read plan artifact ${file}: ${error.message}`)
+  }
+  return validatePlan(plan)
+}
+
+const verifiedPlanArtifact = (file, generatedPlan) => {
+  if (!file) return generatedPlan
+  const artifact = readPlanFile(asAbsolute(file))
+  const { generated: artifactGenerated, ...artifactStable } = artifact
+  const { generated: regeneratedGenerated, ...regeneratedStable } = generatedPlan
+  if (!isDeepStrictEqual(artifactStable, regeneratedStable)) {
+    throw new Error('refusing plan artifact: it does not match the independently regenerated plan')
+  }
+  return artifact
+}
+
+const readEvalArtifact = (file, maxBytes, statusFile = null) => {
+  if (!file && !statusFile) return null
+  let exitCode = null
+  let statusError = null
+  if (!statusFile) {
+    statusError = 'eval status artifact is missing'
+  } else {
+    try {
+      const statusArtifact = readReportCapped(statusFile, 1024)
+      if (statusArtifact.missing) statusError = 'eval status artifact is missing'
+      else {
+        const statusText = statusArtifact.report.trim()
+        if (!/^-?\d+$/.test(statusText)) statusError = 'eval status artifact is malformed'
+        else {
+          const parsed = Number(statusText)
+          if (!Number.isSafeInteger(parsed)) statusError = 'eval status artifact is outside the safe integer range'
+          else exitCode = parsed
+        }
+      }
+    } catch (error) {
+      statusError = `eval status artifact is unreadable: ${error.message}`
+    }
+  }
+  let artifact
+  try {
+    artifact = file ? readReportCapped(file, maxBytes) : { missing: true, report: null }
+  } catch (error) {
+    return {
+      status: 'fail',
+      exit_code: exitCode,
+      report: `eval report artifact is unreadable: ${error.message}`,
+    }
+  }
+  if (statusError) {
+    return {
+      status: 'fail',
+      exit_code: exitCode,
+      report: artifact.report ? `${statusError}; report: ${artifact.report}` : statusError,
+    }
+  }
+  if (artifact.missing) {
+    return {
+      status: 'fail',
+      exit_code: exitCode,
+      report: exitCode === 0 ? 'eval report artifact is missing' : null,
+    }
+  }
+  if (artifact.report === '' && exitCode === 0) return null
+  return { status: exitCode === 0 ? 'pass' : 'fail', exit_code: exitCode, report: artifact.report || null }
+}
+
+const feedContext = feedsDir => {
+  const records = new Map()
+  let files = []
+  try {
+    files = fs.readdirSync(feedsDir).filter(file => file.endsWith('.json')).sort()
+  } catch {
+    return records
+  }
+  for (const file of files) {
+    let feed
+    try {
+      feed = JSON.parse(fs.readFileSync(path.join(feedsDir, file), 'utf8'))
+    } catch {
+      continue
+    }
+    if (feed?.spec !== 'model-eol/0.1' || !Array.isArray(feed.models)) continue
+    for (const entry of feed.models) {
+      for (const key of [entry.id, ...(entry.aliases ?? [])]) {
+        if (typeof key === 'string') records.set(`${feed.publisher}\0${key}`, { feed, entry })
+      }
+    }
+  }
+  return records
+}
+
+export const contextFor = (records, publisher, id, via) => {
+  const record = records.get(`${publisher}\0${id}`)
+  if (!record) return { announced: null, notes: [], entry: null }
+  const distribution = via ? (record.entry.distributions ?? []).find(item => item.via === via) : null
+  return {
+    announced: distribution ? distribution.announced ?? null : record.entry.announced ?? null,
+    notes: [record.feed.note, record.entry.notes].filter(Boolean),
+    entry: record.entry,
+  }
+}
+
+const ignoredModelIds = (plan, config) => {
+  const ignored = new Set(config.ignore.models)
+  const ids = new Set()
+  for (const item of [...plan.items, ...plan.issues]) {
+    if (item.id && (ignored.has(item.id) || ignored.has(item.matched))) ids.add(item.id)
+  }
+  return ids
+}
+
+const isIgnored = (entry, root, config, ignoredIds) => {
+  if (entry.id && ignoredIds.has(entry.id)) return true
+  if (entry.id && config.ignore.models.includes(entry.id)) return true
+  if (entry.matched && config.ignore.models.includes(entry.matched)) return true
+  return matchesAnyGlob(repoPath(entry.file, root), config.ignore.paths)
+}
+
+const buildModelGroups = (plan, config, root, records) => {
+  const ignoredIds = ignoredModelIds(plan, config)
+  const groups = new Map()
+  for (const item of plan.items) {
+    if (isIgnored(item, root, config, ignoredIds)) continue
+    const key = `${item.publisher}\0${item.id}`
+    if (!groups.has(key)) {
+      groups.set(key, {
+        kind: 'model',
+        id: item.id,
+        publisher: item.publisher,
+        items: [],
+        via: plan.via,
+        branch: branchFor(item.publisher, item.id, plan.via),
+        context: contextFor(records, item.publisher, item.id, plan.via),
+      })
+    }
+    groups.get(key).items.push(item)
+  }
+  for (const group of groups.values()) {
+    group.items.sort((a, b) => `${a.file}:${a.line}:${a.occurrence}`.localeCompare(`${b.file}:${b.line}:${b.occurrence}`))
+    group.feedDigest = itemDigest(group.items)
+  }
+  return [...groups.values()].sort((a, b) => `${a.publisher}/${a.id}`.localeCompare(`${b.publisher}/${b.id}`))
+}
+
+const buildIssueGroups = (plan, config, root, records) => {
+  const ignoredIds = ignoredModelIds(plan, config)
+  const groups = new Map()
+  for (const issue of plan.issues) {
+    if (!ISSUE_REASONS.has(issue.reason)) continue
+    if (issue.reason !== 'unresolved-channel' && !ACTIONABLE_STATUSES.has(issue.status)) continue
+    if (isIgnored(issue, root, config, ignoredIds)) continue
+    const channel = issue.reason === 'unresolved-channel' ? (issue.provider || issue.matched || 'unresolved-channel') : null
+    const subject = issue.id || channel || issue.matched || 'unresolved-model'
+    const key = `${issue.publisher || ''}\0${subject}\0${issue.shutdown ?? ''}`
+    if (!groups.has(key)) {
+      groups.set(key, {
+        kind: 'issue',
+        id: issue.id || null,
+        subject,
+        channel,
+        publisher: issue.publisher || 'unknown',
+        shutdown: issue.shutdown ?? null,
+        via: issue.via ?? plan.via,
+        issues: [],
+        root,
+        context: issue.id ? contextFor(records, issue.publisher, issue.id, issue.via ?? plan.via) : { announced: null, notes: [], entry: null },
+      })
+    }
+    groups.get(key).issues.push(issue)
+  }
+  for (const group of groups.values()) {
+    group.issues.sort((a, b) => `${a.file}:${a.line}:${a.reason}`.localeCompare(`${b.file}:${b.line}:${b.reason}`))
+    group.feedDigest = itemDigest(group.issues)
+  }
+  return [...groups.values()].sort((a, b) => `${a.publisher}/${a.subject}/${a.shutdown ?? ''}`.localeCompare(`${b.publisher}/${b.subject}/${b.shutdown ?? ''}`))
+}
+
+const sourcesFor = group => {
+  const values = group.kind === 'model'
+    ? group.items.flatMap(item => item.sources ?? [])
+    : group.issues.flatMap(issue => issue.sources ?? [])
+  return [...new Set(values.filter(Boolean))]
+}
+
+const notesFor = group => {
+  const planNotes = group.kind === 'model' ? group.items.map(item => item.notes) : group.issues.map(issue => issue.notes)
+  const values = [
+    ...(planNotes.some(Boolean) ? planNotes : (group.context?.notes ?? [])),
+  ]
+  return [...new Set(values.filter(Boolean))]
+}
+
+const sourceSection = group => {
+  const sources = sourcesFor(group)
+  return sources.length
+    ? sources.map(source => `- ${markdownLink(source, source)}`).join('\n')
+    : '- No source URL was included in the plan.'
+}
+
+const notesSection = group => {
+  const notes = notesFor(group)
+  return notes.length ? notes.map(note => `- ${markdownText(note)}`).join('\n') : '- No additional feed notes.'
+}
+
+const evalSection = result => {
+  if (!result) return ''
+  const exit = result.exit_code === null ? 'no exit code' : `exit code ${result.exit_code}`
+  const lines = [`## Eval`, `- Result: ${result.status} (${exit}).`]
+  if (result.report !== null) lines.push('', '```text', reportForBody(result.report), '```')
+  return lines.join('\n')
+}
+
+const tokenWarning = tokenKind => tokenKind === 'github-token'
+  ? '\n\n> Warning: checks may be skipped because PRs created with `GITHUB_TOKEN` do not trigger `pull_request` workflows. Use a fine-grained PAT or GitHub App token when checks must run.'
+  : ''
+
+const replacementOptionsText = options => options.map(markdownCode).join(' | ')
+
+const replacementSection = (item, now) => [
+  ...(item.replacement
+    ? [`replacement per feed as of ${now.toISOString().slice(0, 10)}: ${markdownCode(item.replacement)}. Treat as a snapshot in time, not a constant.`]
+    : []),
+  ...(item.replacement_options?.length
+    ? [`replacement options per feed as of ${now.toISOString().slice(0, 10)}: ${replacementOptionsText(item.replacement_options)}.`]
+    : []),
+  ...(item.replacement_note
+    ? [`replacement note: ${markdownText(item.replacement_note)}`]
+    : []),
+]
+
+export const buildPullBody = ({ group, headSha, now = new Date(), tokenKind = null, evalResult = null }) => {
+  const item = group.items[0]
+  const announced = markdownText(group.context?.announced ?? 'not specified')
+  const days = daysRemaining(item.shutdown, now)
+  const metadata = {
+    schema: BOT_SCHEMA,
+    id: group.id,
+    publisher: group.publisher,
+    shutdown: item.shutdown,
+    via: group.via ?? null,
+    replacement: item.replacement,
+    replacement_options: item.replacement_options,
+    replacement_note: item.replacement_note,
+    head_sha: headSha,
+    feed_digest: group.feedDigest,
+  }
+  const sections = [
+    metadataLine(metadata),
+    '',
+    '## What / when',
+    `- Announced: ${announced}`,
+    `- Shutdown: ${markdownText(item.shutdown)}`,
+    `- Days remaining: ${days}`,
+    '',
+    '## Replacement',
+    ...replacementSection(item, now),
+    '',
+    '## Sources',
+    sourceSection(group),
+    '',
+    '## Feed notes',
+    notesSection(group),
+  ]
+  if (group.via) {
+    sections.push('', '## Distributor clock', `This migration uses the ${markdownCode(group.via)} distributor clock; the shutdown date above is the date for that channel.`)
+  }
+  const evaluation = evalSection(evalResult)
+  if (evaluation) sections.push('', evaluation)
+  sections.push(
+    '',
+    '## Checklist',
+    '- [ ] Review the diff',
+    '- [ ] Run evals',
+    '- [ ] Verify params/behavior',
+  )
+  return sections.join('\n') + tokenWarning(tokenKind)
+}
+
+export const buildIssueBody = ({ group, now = new Date() }) => {
+  const issue = group.issues[0]
+  const metadata = {
+    schema: BOT_SCHEMA,
+    id: group.id || group.subject,
+    publisher: group.publisher,
+    shutdown: group.shutdown,
+    via: group.via ?? null,
+    replacement: issue.replacement ?? null,
+    replacement_options: issue.replacement_options,
+    replacement_note: issue.replacement_note,
+    head_sha: null,
+    feed_digest: group.feedDigest,
+    ...(group.channel ? { channel: group.channel } : {}),
+  }
+  const evidence = group.issues
+    .map(issue => `- ${markdownText(`${repoPath(issue.file, group.root || '.')}:${issue.line} - ${issue.reason}${issue.matched ? ` (${issue.matched})` : ''}`)}`)
+    .join('\n')
+  return [
+    metadataLine(metadata),
+    '',
+    '## Finding',
+    `- Subject: ${markdownCode(group.subject)}`,
+    `- Reason: ${markdownText(group.issues[0].reason)}`,
+    `- Status: ${markdownText(group.issues[0].status ?? 'unresolved')}`,
+    `- Shutdown: ${markdownText(group.shutdown ?? 'not scheduled')}`,
+    ...(issue.replacement
+      ? [`- Replacement per feed as of ${now.toISOString().slice(0, 10)}: ${markdownCode(issue.replacement)}. Treat as a snapshot in time, not a constant.`]
+      : []),
+    ...(issue.replacement_options?.length
+      ? [`- Replacement options per feed as of ${now.toISOString().slice(0, 10)}: ${replacementOptionsText(issue.replacement_options)}.`]
+      : []),
+    ...(issue.replacement_note
+      ? [`- Replacement note: ${markdownText(issue.replacement_note)}`]
+      : []),
+    `- Recorded on: ${now.toISOString().slice(0, 10)}`,
+    '',
+    '## Evidence',
+    evidence,
+    '',
+    '## Sources',
+    sourceSection(group),
+    '',
+    '## Feed notes',
+    notesSection(group),
+  ].join('\n')
+}
+
+const pullTitle = group => `model-eol: migrate ${group.id} before ${group.items[0].shutdown}`
+const issueTitle = group => `model-eol: investigate ${group.subject}${group.shutdown ? ` before ${group.shutdown}` : ''}`
+
+const isOpen = item => item.state === 'open'
+const isMerged = item => Boolean(item.merged_at || item.pull_request?.merged_at || item.merged === true)
+
+const matchingPulls = (pulls, group) => pulls
+  .filter(item => !item.labels || hasModelEolLabel(item) || item.head?.ref === group.branch || hasMetadataMarker(item.body))
+  .map(item => {
+    const metadata = parseMetadata(item.body)
+    return { item, metadata, conflict: hasMetadataMarker(item.body) && !metadata }
+  })
+  .filter(record => record.conflict || (
+    record.metadata?.id === group.id
+    && record.metadata?.publisher === group.publisher
+    && (record.metadata.via ?? null) === (group.via ?? null)
+  ))
+
+const matchingIssues = (issues, group) => issues
+  .filter(item => !item.labels || hasModelEolLabel(item) || hasMetadataMarker(item.body))
+  .map(item => {
+    const metadata = parseMetadata(item.body)
+    return { item, metadata, conflict: hasMetadataMarker(item.body) && !metadata }
+  })
+  .filter(record => {
+    if (record.conflict) return true
+    if (!record.metadata) return false
+    if (record.metadata.id !== (group.id || group.subject)) return false
+    if (record.metadata.publisher !== group.publisher) return false
+    if ((record.metadata.via ?? null) !== (group.via ?? null)) return false
+    return !group.channel || record.metadata.channel === group.channel || (record.metadata.id === group.channel && !record.metadata.channel)
+  })
+
+const currentHeadFor = async (api, pull, group) => {
+  if (pull.head?.sha) return pull.head.sha
+  const branch = pull.head?.ref || group.branch
+  const encoded = branch.split('/').map(part => encodeURIComponent(part)).join('/')
+  const { data } = await api.request('GET', `/repos/${api.repo}/git/ref/heads/${encoded}`)
+  return data?.object?.sha ?? null
+}
+
+const standingDownComment = (group, metadata, currentHead) =>
+  `model-eol is standing down for this branch. The branch head (${markdownCode(currentHead || 'unknown')}) no longer satisfies the bot lease checks for metadata head (${markdownCode(metadata?.head_sha || 'unknown')}), so a human change will not be overwritten. Please update or close this PR manually. An actor with push access can forge the configured identity.`
+
+const writeJson = (file, value) => fs.writeFileSync(file, JSON.stringify(value, null, 2))
+
+const gitStatusPaths = cwd => {
+  const result = spawnSync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (result.error || result.status !== 0) {
+    throw new Error(`could not inspect eval workspace: ${result.error?.message || result.stderr?.trim() || `exit ${result.status}`}`)
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map(line => line.slice(3).trim())
+    .filter(Boolean)
+}
+
+const gitHead = cwd => {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  if (result.error || result.status !== 0) throw new Error(`could not inspect eval commit: ${result.error?.message || result.stderr?.trim() || `exit ${result.status}`}`)
+  return result.stdout.trim()
+}
+
+const hashFiles = (root, files) => new Map(files.map(file => [file, sha256(fs.readFileSync(path.join(root, file)))]))
+
+const evalWorkspaceDrift = (root, planFiles, expectedHashes, expectedHead) => {
+  if (gitHead(root) !== expectedHead) return 'eval changed repository history'
+  for (const file of planFiles) {
+    let actual
+    try {
+      actual = sha256(fs.readFileSync(path.join(root, file)))
+    } catch (error) {
+      return `eval changed planned file ${file}: it is unreadable after evaluation (${error.message})`
+    }
+    if (actual !== expectedHashes.get(file)) return `eval changed planned file ${file}`
+  }
+  const unexpected = gitStatusPaths(root).filter(file => !planFiles.includes(file))
+  if (unexpected.length) return `eval changed unexpected repository file ${unexpected[0]}`
+  return null
+}
+
+const makePatch = ({ source, base, branch, expectedHead, group, plan, config, checkerPath, evalEnabled, root, warn, gitAuth }) => {
+  const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'model-eol-bot-work-'))
+  const planRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'model-eol-plan-'))
+  const clone = path.join(workRoot, 'repo')
+  const fullPlanPath = path.join(planRoot, 'plan.json')
+  const selectedPlanPath = path.join(planRoot, 'selected-plan.json')
+  const reportPath = path.join(planRoot, 'eval-report.md')
+  writeJson(fullPlanPath, plan)
+  writeJson(selectedPlanPath, { ...plan, items: group.items, issues: [] })
+  try {
+    cloneRepository(source, clone, gitAuth)
+    prepareBranch(clone, branch, base, gitAuth)
+    const applied = spawnSync(process.execPath, [checkerPath, 'apply', '--plan', selectedPlanPath], {
+      cwd: clone,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    if (applied.status !== 0 || applied.error) {
+      throw new Error(`apply subprocess failed: ${applied.error?.message || applied.stderr?.trim() || `exit ${applied.status}`}`)
+    }
+    const planFiles = [...new Set(group.items.map(item => repoPath(item.file, clone)))]
+    const postApplyHashes = hashFiles(clone, planFiles)
+    const postApplyHead = gitHead(clone)
+
+    let evalResult = null
+    if (evalEnabled && config.eval.command) {
+      try {
+        evalResult = runEvalHook({
+          command: config.eval.command,
+          timeoutMs: config.eval.timeout_ms,
+          maxReportBytes: config.eval.max_report_bytes,
+          passEnv: config.eval.pass_env,
+          cwd: clone,
+          oldId: group.id,
+          newId: group.items[0].replacement,
+          planPath: fullPlanPath,
+          reportPath,
+        })
+      } catch (error) {
+        warn(`model-eol: warning: eval runner failed for ${group.id}: ${error.message}`)
+        evalResult = { status: 'fail', exit_code: null, report: `eval runner error: ${error.message}` }
+      }
+    }
+    if (evalResult) {
+      const drift = evalWorkspaceDrift(clone, planFiles, postApplyHashes, postApplyHead)
+      if (drift) {
+        evalResult = {
+          ...evalResult,
+          status: 'fail',
+          report: [evalResult.report, drift].filter(Boolean).join('\n'),
+        }
+      }
+    }
+    if (evalResult && evalResult.status !== 'pass') {
+      const error = new Error(`eval hook did not pass: ${evalResult.status}`)
+      error.code = 'MODEL_EOL_EVAL_FAILED'
+      error.evalResult = evalResult
+      throw error
+    }
+
+    configureIdentity(clone)
+    const files = planFiles
+    const message = `model-eol: migrate ${group.id} to ${group.items[0].replacement} (${group.feedDigest.slice(0, 8)})`
+    const headSha = commitAll(clone, files, message)
+    pushBranch(clone, branch, expectedHead, gitAuth)
+    return { headSha, evalResult }
+  } finally {
+    fs.rmSync(workRoot, { recursive: true, force: true })
+    fs.rmSync(planRoot, { recursive: true, force: true })
+  }
+}
+
+const decision = (group, action, extra = {}) => ({ group, action, ...extra })
+
+const processModel = async ({ api, pulls, group, source, base, plan, config, checkerPath, evalEnabled, externalEval, root, now, tokenKind, warn, gitAuth }) => {
+  if (externalEval && externalEval.status !== 'pass') {
+    return decision(group, 'eval-failed', { evalResult: externalEval })
+  }
+  const matches = matchingPulls(pulls, group)
+  const conflict = matches.find(record => record.conflict)
+  if (conflict) return decision(group, 'conflict', { number: conflict.item.number })
+  const open = matches.find(record => isOpen(record.item))
+  const currentDigest = group.feedDigest
+  if (open) {
+    if (open.metadata.feed_digest === currentDigest) return decision(group, 'skip-unchanged', { number: open.item.number })
+    const currentHead = await currentHeadFor(api, open.item, group)
+    if (!currentHead || currentHead !== open.metadata.head_sha) {
+      await api.comment(open.item.number, standingDownComment(group, open.metadata, currentHead))
+      return decision(group, 'stand-down', { number: open.item.number })
+    }
+    let patch
+    try {
+      patch = makePatch({
+        source,
+        base,
+        branch: open.item.head?.ref || group.branch,
+        expectedHead: open.metadata.head_sha,
+        group,
+        plan,
+        config,
+        checkerPath,
+        evalEnabled,
+        root,
+        warn,
+        gitAuth,
+      })
+    } catch (error) {
+      if (error.code === 'MODEL_EOL_EVAL_FAILED') {
+        return decision(group, 'eval-failed', { number: open.item.number, evalResult: error.evalResult })
+      }
+      if (error.code !== 'MODEL_EOL_BRANCH_STAND_DOWN') throw error
+      await api.comment(open.item.number, standingDownComment(group, open.metadata, error.currentHead))
+      return decision(group, 'stand-down', { number: open.item.number })
+    }
+    if (patch.evalResult && patch.evalResult.status !== 'pass') {
+      return decision(group, 'eval-failed', { number: open.item.number, evalResult: patch.evalResult })
+    }
+    if (!patch.evalResult && externalEval) patch.evalResult = externalEval
+    const body = buildPullBody({ group, headSha: patch.headSha, now, tokenKind, evalResult: patch.evalResult })
+    await api.updatePull(open.item.number, { title: pullTitle(group), body })
+    return decision(group, 'update', { number: open.item.number, body, headSha: patch.headSha })
+  }
+
+  const replacement = group.items[0].replacement
+  // Legacy metadata without replacement keeps shutdown-only suppression.
+  const merged = matches.find(record => !isOpen(record.item) && isMerged(record.item) && record.metadata.shutdown === group.items[0].shutdown && (record.metadata.replacement === undefined || record.metadata.replacement === replacement))
+  if (merged) return decision(group, 'skip-merged', { number: merged.item.number })
+  const dismissed = matches.find(record => !isOpen(record.item) && !isMerged(record.item) && record.metadata.shutdown === group.items[0].shutdown && (record.metadata.replacement === undefined || record.metadata.replacement === replacement))
+  if (dismissed) return decision(group, 'skip-dismissed', { number: dismissed.item.number })
+
+  const previousBotHead = matches.find(record => record.metadata?.head_sha)?.metadata.head_sha ?? null
+  let patch
+  try {
+    patch = makePatch({
+      source,
+      base,
+      branch: group.branch,
+      expectedHead: previousBotHead,
+      group,
+      plan,
+      config,
+      checkerPath,
+      evalEnabled,
+      root,
+      warn,
+      gitAuth,
+    })
+  } catch (error) {
+    if (error.code === 'MODEL_EOL_EVAL_FAILED') {
+      return decision(group, 'eval-failed', { evalResult: error.evalResult })
+    }
+    if (error.code !== 'MODEL_EOL_BRANCH_STAND_DOWN') throw error
+    const prior = matches.find(record => record.metadata?.head_sha === previousBotHead)
+    if (prior) await api.comment(prior.item.number, standingDownComment(group, prior.metadata, error.currentHead))
+    return decision(group, 'stand-down', { number: prior?.item.number })
+  }
+  if (patch.evalResult && patch.evalResult.status !== 'pass') {
+    return decision(group, 'eval-failed', { evalResult: patch.evalResult })
+  }
+  if (!patch.evalResult && externalEval) patch.evalResult = externalEval
+  const body = buildPullBody({ group, headSha: patch.headSha, now, tokenKind, evalResult: patch.evalResult })
+  const latestMatches = matchingPulls(await api.listPullsByHead(group.branch), group)
+  const latestConflict = latestMatches.find(record => record.conflict)
+  if (latestConflict) return decision(group, 'conflict', { number: latestConflict.item.number })
+  const latestOpen = latestMatches.find(record => isOpen(record.item))
+  if (latestOpen) {
+    await api.updatePull(latestOpen.item.number, { title: pullTitle(group), body })
+    return decision(group, 'update', { number: latestOpen.item.number, body, headSha: patch.headSha })
+  }
+  const latestSuppressed = latestMatches.find(record => !isOpen(record.item) && record.metadata.shutdown === group.items[0].shutdown && (record.metadata.replacement === undefined || record.metadata.replacement === replacement))
+  if (latestSuppressed) return decision(group, isMerged(latestSuppressed.item) ? 'skip-merged' : 'skip-dismissed', { number: latestSuppressed.item.number })
+  const created = await api.createPull({
+    title: pullTitle(group),
+    head: group.branch,
+    base,
+    body,
+  })
+  return decision(group, 'create', { number: created.number, body, headSha: patch.headSha })
+}
+
+const processIssue = async ({ api, issues, group, now }) => {
+  const matches = matchingIssues(issues, group)
+  const conflict = matches.find(record => record.conflict)
+  if (conflict) return decision(group, 'conflict', { number: conflict.item.number })
+  const open = matches.find(record => isOpen(record.item))
+  const body = buildIssueBody({ group, now })
+  if (open) {
+    if (open.metadata.feed_digest === group.feedDigest) return decision(group, 'skip-unchanged', { number: open.item.number, body })
+    await api.updateIssue(open.item.number, { title: issueTitle(group), body })
+    return decision(group, 'update', { number: open.item.number, body })
+  }
+  const replacement = group.issues[0].replacement ?? null
+  const dismissed = matches.find(record => !isOpen(record.item) && record.metadata.shutdown === group.shutdown && (record.metadata.replacement === undefined || record.metadata.replacement === replacement))
+  if (dismissed) return decision(group, 'skip-dismissed', { number: dismissed.item.number })
+  const latestMatches = matchingIssues(await api.listIssues(), group)
+  const latestConflict = latestMatches.find(record => record.conflict)
+  if (latestConflict) return decision(group, 'conflict', { number: latestConflict.item.number })
+  const latestOpen = latestMatches.find(record => isOpen(record.item))
+  if (latestOpen) {
+    await api.updateIssue(latestOpen.item.number, { title: issueTitle(group), body })
+    return decision(group, 'update', { number: latestOpen.item.number, body })
+  }
+  const latestDismissed = latestMatches.find(record => !isOpen(record.item) && record.metadata.shutdown === group.shutdown && (record.metadata.replacement === undefined || record.metadata.replacement === replacement))
+  if (latestDismissed) return decision(group, 'skip-dismissed', { number: latestDismissed.item.number })
+  const created = await api.createIssue({ title: issueTitle(group), body, labels: ['model-eol'] })
+  return decision(group, 'create', { number: created.number, body })
+}
+
+const dryDecision = (group, now, tokenKind) => group.kind === 'model'
+  ? decision(group, 'create', {
+    body: buildPullBody({ group, headSha: 'dry-run', now, tokenKind }),
+    branch: group.branch,
+  })
+  : decision(group, 'create', { body: buildIssueBody({ group, now }) })
+
+const reportOnlyDecision = (group, now, tokenKind) => {
+  const result = dryDecision(group, now, tokenKind)
+  return { ...result, action: 'report-only' }
+}
+
+const prepareScan = ({ targetDir, source, dryRun, gitAuth }) => {
+  if (!dryRun || !String(targetDir).startsWith('file://')) return { path: targetDir, cleanup: () => {} }
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'model-eol-bot-scan-'))
+  const clone = path.join(root, 'repo')
+  cloneRepository(source, clone, gitAuth)
+  return { path: clone, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) }
+}
+
+const configFileFor = ({ targetDir, configPath, scanPath }) => {
+  if (configPath) return asAbsolute(configPath)
+  if (!String(targetDir).startsWith('file://')) {
+    const targetConfig = path.join(path.resolve(targetDir), '.model-eol.json')
+    if (fs.existsSync(targetConfig)) return targetConfig
+  }
+  const candidate = path.join(scanPath, '.model-eol.json')
+  return candidate
+}
+
+export const formatDecisions = (decisions, { degraded = false } = {}) => {
+  const lines = ['model-eol decision table']
+  if (degraded) lines.push('model-eol status: degraded - vendored feed fallback enabled; no GitHub writes')
+  for (const record of decisions) {
+    const group = record.group
+    const label = group.kind === 'model' ? `${group.publisher}/${group.id}` : `${group.publisher}/${group.subject}`
+    lines.push(`- ${record.action} ${label}`)
+    if (record.branch) lines.push(`  branch: ${record.branch}`)
+    if (record.body) lines.push('  body:', record.body.split('\n').map(line => `    ${line}`).join('\n'))
+  }
+  return lines.join('\n')
+}
+
+export const runBot = async ({
+  repo,
+  targetDir = process.cwd(),
+  configPath = null,
+  dryRun = false,
+  evalEnabled = false,
+  feedsUrls = [],
+  token = process.env.GITHUB_TOKEN,
+  apiUrl = process.env.GITHUB_API_URL || 'https://api.github.com',
+  tokenKind = process.env.MODEL_EOL_TOKEN_KIND || null,
+  transport = globalThis.fetch,
+  fetchImpl = globalThis.fetch,
+  checkerPath = CHECKER,
+  vendoredFeeds = VENDORED_FEEDS,
+  planFile = null,
+  evalReportFile = null,
+  evalStatusFile = null,
+  now = new Date(),
+  warn = message => console.error(message),
+} = {}) => {
+  if (!dryRun) {
+    validateRepo(repo)
+    if (!token) throw new Error('GITHUB_TOKEN is required unless --dry-run is used')
+  }
+  const targetIsUrl = String(targetDir).startsWith('file://')
+  const targetPath = targetIsUrl ? targetDir : path.resolve(targetDir)
+  const source = targetIsUrl ? targetDir : originFor(targetPath)
+  const gitAuth = gitAuthentication(source, token, apiUrl)
+  let scan = null
+  let baseClone = null
+  let ownedBaseRoot = null
+  let feedSet = null
+  try {
+    if (dryRun) {
+      scan = prepareScan({ targetDir: targetPath, source, dryRun, gitAuth })
+      const configFile = configFileFor({ targetDir, configPath, scanPath: scan.path })
+      if (configPath && !fs.existsSync(configFile)) throw new Error(`config file not found: ${configFile}`)
+      const config = loadConfig(configFile)
+      const planConfigPath = fs.existsSync(configFile) ? configFile : null
+      feedSet = await downloadFeeds({
+        urls: feedsUrls,
+        fetchImpl,
+        vendoredDir: vendoredFeeds,
+        allowVendoredFallback: config.feeds.allow_vendored_fallback,
+        warn,
+      })
+      const generatedPlan = runPlan({ workDir: scan.path, config, configPath: planConfigPath, feedsDir: feedSet.dir, checkerPath, warn })
+      const plan = verifiedPlanArtifact(planFile, generatedPlan)
+      const records = feedContext(feedSet.dir)
+      const models = buildModelGroups(plan, config, scan.path, records)
+      const issues = config.issues.enabled ? buildIssueGroups(plan, config, scan.path, records) : []
+      const report = group => feedSet.degraded ? reportOnlyDecision(group, now, tokenKind) : dryDecision(group, now, tokenKind)
+      const decisions = [...models.map(report), ...issues.map(report)]
+      return { plan, config, decisions, feedsDir: feedSet.dir, degraded: Boolean(feedSet.degraded) }
+    }
+
+    ownedBaseRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'model-eol-bot-base-'))
+    baseClone = path.join(ownedBaseRoot, 'repo')
+    cloneRepository(source, baseClone, gitAuth)
+    const base = defaultBranch(baseClone, gitAuth)
+    const configFile = configFileFor({ targetDir, configPath, scanPath: baseClone })
+    if (configPath && !fs.existsSync(configFile)) throw new Error(`config file not found: ${configFile}`)
+    const config = loadConfig(configFile)
+    const planConfigPath = fs.existsSync(configFile) ? configFile : null
+    feedSet = await downloadFeeds({
+      urls: feedsUrls,
+      fetchImpl,
+      vendoredDir: vendoredFeeds,
+      allowVendoredFallback: config.feeds.allow_vendored_fallback,
+      warn,
+    })
+    const generatedPlan = runPlan({ workDir: baseClone, config, configPath: planConfigPath, feedsDir: feedSet.dir, checkerPath, warn })
+    const plan = verifiedPlanArtifact(planFile, generatedPlan)
+    const records = feedContext(feedSet.dir)
+    const models = buildModelGroups(plan, config, baseClone, records)
+    const issues = config.issues.enabled ? buildIssueGroups(plan, config, baseClone, records) : []
+    if (feedSet.degraded) {
+      const report = group => reportOnlyDecision(group, now, tokenKind)
+      const decisions = [...models.map(report), ...issues.map(report)]
+      return { plan, config, decisions, feedsDir: feedSet.dir, degraded: true }
+    }
+    const externalEval = readEvalArtifact(
+      evalReportFile ? asAbsolute(evalReportFile) : null,
+      config.eval.max_report_bytes,
+      evalStatusFile ? asAbsolute(evalStatusFile) : null,
+    )
+    const api = new GitHubClient({ repo, apiUrl, token, transport, warn })
+    if (models.length || issues.length) await api.ensureModelEolLabel()
+    const pulls = models.length ? await api.listPulls() : []
+    const issueRecords = issues.length ? await api.listIssues() : []
+    const decisions = []
+    for (const group of models) {
+      decisions.push(await processModel({
+        api,
+        pulls,
+        group,
+        source,
+        base,
+        plan,
+        config,
+        checkerPath,
+        evalEnabled,
+        externalEval,
+        root: baseClone,
+        now,
+        tokenKind,
+        warn,
+        gitAuth,
+      }))
+    }
+    for (const group of issues) decisions.push(await processIssue({ api, issues: issueRecords, group, now }))
+    return { plan, config, decisions, feedsDir: feedSet.dir, degraded: false }
+  } finally {
+    scan?.cleanup()
+    if (ownedBaseRoot) fs.rmSync(ownedBaseRoot, { recursive: true, force: true })
+    feedSet?.cleanup()
+  }
+}
+
+export const main = async (argv = process.argv.slice(2), env = process.env) => {
+  const options = parseArgs(argv)
+  if (options.help) {
+    console.log(helpText())
+    return 0
+  }
+  const result = await runBot({
+    repo: options.repo || env.GITHUB_REPOSITORY,
+    targetDir: options.targetDir,
+    configPath: options.configPath,
+    dryRun: options.dryRun,
+    evalEnabled: options.evalEnabled,
+    feedsUrls: options.feedsUrls,
+    planFile: env.MODEL_EOL_PLAN_FILE || null,
+    evalReportFile: env.MODEL_EOL_EVAL_REPORT_FILE || null,
+    evalStatusFile: env.MODEL_EOL_EVAL_STATUS_FILE || null,
+    token: env.GITHUB_TOKEN,
+    apiUrl: env.GITHUB_API_URL || 'https://api.github.com',
+    tokenKind: env.MODEL_EOL_TOKEN_KIND || null,
+  })
+  if (options.dryRun) console.log(formatDecisions(result.decisions, { degraded: result.degraded }))
+  else {
+    if (result.degraded) console.log('model-eol status: degraded - vendored feed fallback enabled; no GitHub writes')
+    for (const item of result.decisions) console.log(`${item.action} ${item.group.publisher}/${item.group.kind === 'model' ? item.group.id : item.group.subject}`)
+  }
+  return 0
+}
+
+const invokedFile = (() => {
+  if (!process.argv[1]) return null
+  try {
+    return fs.realpathSync(process.argv[1])
+  } catch {
+    return path.resolve(process.argv[1])
+  }
+})()
+
+if (invokedFile === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  main().then(code => process.exit(code)).catch(error => {
+    console.error(`model-eol bot: ${error.message}`)
+    process.exit(2)
+  })
+}