pantheon-opencode 1.4.3 → 1.5.0-beta.10

package/scripts/probe-context-rehydrate.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+/**
+ * Offline/ambiental probe for context_rehydrate and context_session_summary.
+ *
+ * The Python child imports the installed persistence server and exercises the
+ * real FastMCP tools against a temporary SQLite database. No OpenCode command,
+ * network call, LLM, or user database is involved. Missing package/runtime is
+ * NOT_TESTED/AMBIENTAL rather than a false PASS.
+ */
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const requestedVersion = valueFor('--version')
+const jsonOutput = process.argv.includes('--json')
+const runtime = fileURLToPath(new URL('./mcp_persistence_server.py', import.meta.url))
+
+function valueFor(name) {
+  const index = process.argv.indexOf(name)
+  return index >= 0 ? process.argv[index + 1] : undefined
+}
+
+function emit(status, detail, checks = []) {
+  const result = { status, version: requestedVersion, detail, checks }
+  if (jsonOutput) process.stdout.write(JSON.stringify(result))
+  else process.stdout.write(`${status}: ${detail}\n`)
+  if (status === 'FAIL') process.exitCode = 1
+}
+
+function unavailable(detail) {
+  emit('NOT_TESTED', detail)
+}
+
+function pythonCandidates() {
+  const venvPython = process.env.HOME
+    ? join(process.env.HOME, '.config', 'opencode', '.venv', 'bin', 'python')
+    : undefined
+  return [process.env.PANTHEON_PYTHON, venvPython, 'python3'].filter(Boolean)
+}
+
+const PYTHON_HARNESS = `
+import asyncio
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+
+runtime_path = Path(sys.argv[1]).resolve()
+db_root = Path(sys.argv[2]).resolve()
+sys.path.insert(0, str(runtime_path.parent))
+sys.argv = [str(runtime_path), "--global-db", str(db_root / "global.db"),
+            "--project-db", str(db_root / "project.db")]
+
+spec = importlib.util.spec_from_file_location("probe_mcp_persistence", runtime_path)
+if spec is None or spec.loader is None:
+    raise RuntimeError("could not load persistence runtime")
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+async def call(name, arguments):
+    result = await module.mcp.call_tool(name, arguments)
+    if isinstance(result, tuple):
+        structured = result[1]
+        if structured is not None:
+            if isinstance(structured, dict) and "result" in structured:
+                return structured["result"]
+            return structured
+        result = result[0]
+    if isinstance(result, dict):
+        return result
+    if not result:
+        return None
+    text = getattr(result[0], "text", str(result[0]))
+    try:
+        return json.loads(text)
+    except (TypeError, ValueError, json.JSONDecodeError):
+        return text
+
+
+async def main():
+    checks = []
+    slug = "context-rehydrate-probe"
+    session_id = "synthetic-session"
+    checkpoint = {
+        "version": 1,
+        "goal": {"id": "probe-goal", "objective": "verify context recovery",
+                 "status": "in_progress"},
+        "phase": {"current": 2, "total": 3, "name": "offline validation"},
+        "delegations": {"in_flight": [{"alias": "apo-probe", "agent": "apollo",
+                                         "task_id": "probe-task"}]},
+    }
+    tail = ["phase 1 complete", "phase 2 payload validated"]
+
+    # context_save creates the real session-qualified latest pointer. Keeping
+    # tail under its own key also tests the runtime's latest/tail fallback.
+    await call("context_save", {"slug": slug, "key": "tail",
+                                 "content": json.dumps(tail),
+                                 "session_id": session_id})
+    await call("context_save", {"slug": slug, "key": "phase:2",
+                                 "content": json.dumps(checkpoint),
+                                 "session_id": session_id})
+    latest = await call("context_get", {"slug": slug, "key": "latest",
+                                         "session_id": session_id})
+    stored_tail = await call("context_get", {"slug": slug, "key": "tail",
+                                              "session_id": session_id})
+    if latest is None or stored_tail is None:
+        raise AssertionError("synthetic latest/tail checkpoint payload is null")
+    checks.append("synthetic latest/tail/goal/phase/delegation checkpoint: PASS")
+
+    os.environ.pop("PANTHEON_COMPACTION", None)
+    os.environ.pop("PANTHEON_SESSION_END_SUMMARY", None)
+    blocks = await call("context_rehydrate", {"slug": slug})
+    summary = await call("context_session_summary", {"slug": slug})
+    if not isinstance(blocks, list) or not blocks:
+        raise AssertionError("context_rehydrate returned a null/empty payload")
+    if not isinstance(summary, str) or not summary:
+        raise AssertionError("context_session_summary returned a null/empty payload")
+    for fragment in ("verify context recovery", "phase 2/3", "apo-probe",
+                     "phase 2 payload validated"):
+        if not any(fragment in block for block in blocks) and fragment not in summary:
+            raise AssertionError(f"payload is missing {fragment!r}")
+    checks.append("context_rehydrate non-null payload: PASS")
+    checks.append("context_session_summary non-null payload: PASS")
+
+    missing_blocks = await call("context_rehydrate", {"slug": "probe-absent"})
+    missing_summary = await call("context_session_summary", {"slug": "probe-absent"})
+    if missing_blocks is not None or missing_summary is not None:
+        raise AssertionError("absent checkpoint must return null payloads")
+    checks.append("absence returns null: PASS")
+
+    expired_slug = "context-expired-probe"
+    await call("context_save", {"slug": expired_slug, "key": "phase:1",
+                                 "content": json.dumps(checkpoint), "ttl": -1,
+                                 "session_id": session_id})
+    expired_blocks = await call("context_rehydrate", {"slug": expired_slug})
+    expired_summary = await call("context_session_summary", {"slug": expired_slug})
+    if expired_blocks is not None or expired_summary is not None:
+        raise AssertionError("expired checkpoint must return null payloads")
+    checks.append("expiration returns null: PASS")
+
+    invalid_slug = "context-invalid-probe"
+    await call("context_save", {"slug": invalid_slug, "key": "phase:1",
+                                 "content": "not-json", "session_id": session_id})
+    invalid_blocks = await call("context_rehydrate", {"slug": invalid_slug})
+    invalid_summary = await call("context_session_summary", {"slug": invalid_slug})
+    if invalid_blocks is not None or invalid_summary is not None:
+        raise AssertionError("invalid checkpoint must return null payloads")
+    checks.append("invalid payload returns null: PASS")
+
+    os.environ["PANTHEON_COMPACTION"] = "off"
+    switched_blocks = await call("context_rehydrate", {"slug": slug})
+    if switched_blocks is not None:
+        raise AssertionError("PANTHEON_COMPACTION=off must return null")
+    os.environ.pop("PANTHEON_COMPACTION", None)
+    os.environ["PANTHEON_SESSION_END_SUMMARY"] = "off"
+    switched_summary = await call("context_session_summary", {"slug": slug})
+    if switched_summary is not None:
+        raise AssertionError("PANTHEON_SESSION_END_SUMMARY=off must return null")
+    checks.append("kill-switches return null: PASS")
+    print(json.dumps({"checks": checks}))
+
+
+asyncio.run(main())
+`
+
+async function main() {
+  if (requestedVersion !== 'v1' && requestedVersion !== 'v2') {
+    emit('FAIL', 'usage: --version v1|v2 [--json]')
+    return
+  }
+  if (!existsSync(runtime)) {
+    unavailable('installed package does not include mcp_persistence_server.py')
+    return
+  }
+
+  const root = mkdtempSync(join(tmpdir(), 'pantheon-context-probe-'))
+  const dbRoot = join(root, 'db')
+  const python = pythonCandidates().find((candidate) =>
+    candidate.includes('/') ? existsSync(candidate) : true,
+  )
+  if (!python) {
+    rmSync(root, { recursive: true, force: true })
+    unavailable('Python persistence runtime is not available')
+    return
+  }
+
+  try {
+    const child = spawnSync(python, ['-c', PYTHON_HARNESS, runtime, dbRoot], {
+      encoding: 'utf8',
+      timeout: 30000,
+      env: process.env,
+    })
+    if (child.error) {
+      const detail = child.error instanceof Error ? child.error.message : String(child.error)
+      if (/EACCES|permission denied|not found/i.test(detail)) {
+        emit('AMBIENTAL', `persistence runtime unavailable: ${detail}`)
+      } else {
+        unavailable(`persistence runtime unavailable: ${detail}`)
+      }
+      return
+    }
+    if (child.signal === 'SIGTERM') {
+      emit('AMBIENTAL', 'persistence probe timed out after 30s')
+      return
+    }
+    if (child.status !== 0) {
+      const detail = `${child.stderr || child.stdout || 'persistence probe failed'}`.trim()
+      if (
+        /No module named|ModuleNotFoundError|can't open file|No such file|importerror/i.test(detail)
+      ) {
+        unavailable(`persistence runtime unavailable: ${detail.slice(0, 320)}`)
+      } else {
+        emit('FAIL', `offline persistence checks failed: ${detail.slice(0, 320)}`)
+      }
+      return
+    }
+
+    const lines = child.stdout.trim().split('\n').filter(Boolean)
+    const payload = JSON.parse(lines.at(-1) || '')
+    if (!Array.isArray(payload.checks) || payload.checks.length < 6) {
+      emit('FAIL', 'offline persistence probe returned incomplete checks')
+      return
+    }
+    emit(
+      'PASS',
+      'offline synthetic persistence checks passed; no LLM or user DB was used',
+      payload.checks,
+    )
+  } catch (error) {
+    emit('FAIL', error instanceof Error ? error.message : String(error))
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+await main()

package/scripts/probe-pantheon-cost.mjs

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+/**
+ * Offline/ambiental probe for pantheon_cost.
+ *
+ * The probe never reads or writes a user's real database. Without --fixture it
+ * reports AMBIENTAL because a real dependency/database is intentionally not
+ * exercised. With --fixture it imports the installed command and creates a
+ * temporary synthetic opencode database. A missing fixture runtime is also
+ * AMBIENTAL rather than a false PASS.
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const requestedVersion = valueFor('--version')
+const jsonOutput = process.argv.includes('--json')
+const fixtureMode = process.argv.includes('--fixture')
+
+function valueFor(name) {
+  const index = process.argv.indexOf(name)
+  return index >= 0 ? process.argv[index + 1] : undefined
+}
+
+function emit(status, detail, checks = []) {
+  const result = { status, version: requestedVersion, detail, checks }
+  if (jsonOutput) process.stdout.write(JSON.stringify(result))
+  else process.stdout.write(`${status}: ${detail}\n`)
+  if (status === 'FAIL') process.exitCode = 1
+}
+
+function diagnostic(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const stderr =
+    error && typeof error === 'object' && typeof error.stderr === 'string'
+      ? error.stderr.trim()
+      : ''
+  return stderr === '' ? message : `${message}; stderr: ${stderr}`
+}
+
+function ambiental(detail) {
+  emit('AMBIENTAL', detail)
+}
+
+function setEnvironment(values) {
+  const previous = new Map()
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, process.env[key])
+    if (value === undefined) delete process.env[key]
+    else process.env[key] = value
+  }
+  return () => {
+    for (const [key, value] of previous) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  }
+}
+
+function createSyntheticDb(DatabaseSync, path, rows) {
+  const db = new DatabaseSync(path)
+  db.exec('CREATE TABLE message (data TEXT NOT NULL, time_created INTEGER NOT NULL)')
+  const insert = db.prepare('INSERT INTO message (data, time_created) VALUES (?, ?)')
+  for (const data of rows) insert.run(JSON.stringify(data), Date.now())
+  db.close()
+}
+
+function createIncompatibleDb(DatabaseSync, path) {
+  const db = new DatabaseSync(path)
+  db.exec('CREATE TABLE not_message (value TEXT NOT NULL)')
+  db.close()
+}
+
+function requireOutput(output, fragment, label) {
+  if (!output.includes(fragment)) throw new Error(`${label}: missing ${fragment}`)
+}
+
+function assertTokensOnly(output, expectedRows, total) {
+  requireOutput(output, 'Tokens In | Tokens Out | Tokens Total', 'tokens-only header')
+  for (const row of expectedRows) {
+    requireOutput(
+      output,
+      `| ${row.agent} | ${row.phase} | ${row.input} | ${row.output} | ${row.total} |`,
+      'token row',
+    )
+  }
+  requireOutput(
+    output,
+    `| **Total** | — | **${total.input}** | **${total.output}** | **${total.total}** |`,
+    'token total',
+  )
+  if (/Cost \(USD\)|costUsd|\$\d|\bUSD\b/i.test(output)) {
+    throw new Error('tokens-only output contains a monetary value')
+  }
+}
+
+async function main() {
+  if (requestedVersion !== 'v1' && requestedVersion !== 'v2') {
+    emit('FAIL', 'usage: --version v1|v2 [--fixture] [--json]')
+    return
+  }
+
+  if (!fixtureMode) {
+    ambiental(
+      'real pantheon_cost dependency/database not exercised; use --fixture for synthetic checks',
+    )
+    return
+  }
+
+  const source = new URL('../src/pantheon/cost-command.ts', import.meta.url)
+  if (!existsSync(source)) {
+    ambiental(
+      'pantheon_cost dependency is unavailable: installed package lacks src/pantheon/cost-command.ts',
+    )
+    return
+  }
+
+  let DatabaseSync
+  let createCostCommand
+  try {
+    ;({ DatabaseSync } = await import('node:sqlite'))
+    ;({ createCostCommand } = await import(source.href))
+  } catch (error) {
+    ambiental(
+      `pantheon_cost fixture runtime unavailable: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return
+  }
+
+  const root = mkdtempSync(join(tmpdir(), 'pantheon-cost-probe-'))
+  const dataHome = join(root, 'data')
+  const opencodeDir = join(dataHome, 'opencode')
+  const selectedDb = join(opencodeDir, requestedVersion === 'v2' ? 'opencode-v2.db' : 'opencode.db')
+  const otherDb = join(root, 'other.db')
+  const envDb = join(root, 'env.db')
+  const explicitDb = join(root, 'explicit.db')
+  const incompatibleDb = join(root, 'incompatible.db')
+  const checks = []
+
+  try {
+    mkdirSync(opencodeDir, { recursive: true })
+    // These rows intentionally include a monetary-looking field to prove it is
+    // ignored; only input/output/total tokens may appear in the report.
+    const selectedRows =
+      requestedVersion === 'v2'
+        ? [
+            {
+              role: 'assistant',
+              agent: 'aphrodite',
+              phase: 'plan',
+              cost: 999.99,
+              tokens: { input: 7, output: 8 },
+            },
+            {
+              role: 'assistant',
+              agent: 'aphrodite',
+              phase: 'plan',
+              cost: 999.99,
+              tokens: { input: 1, output: 2 },
+            },
+            {
+              role: 'assistant',
+              agent: 'zeus',
+              phase: 'audit',
+              cost: 999.99,
+              tokens: { input: 4, output: 6 },
+            },
+          ]
+        : [
+            {
+              role: 'assistant',
+              agent: 'hermes',
+              phase: 'plan',
+              cost: 999.99,
+              tokens: { input: 10, output: 20 },
+            },
+            {
+              role: 'assistant',
+              agent: 'hermes',
+              phase: 'plan',
+              cost: 999.99,
+              tokens: { input: 3, output: 4 },
+            },
+            {
+              role: 'assistant',
+              agent: 'athena',
+              phase: 'review',
+              cost: 999.99,
+              tokens: { input: 2, output: 5 },
+            },
+          ]
+    createSyntheticDb(DatabaseSync, selectedDb, selectedRows)
+    createSyntheticDb(DatabaseSync, otherDb, [
+      {
+        role: 'assistant',
+        agent: 'wrong-version',
+        phase: 'other',
+        tokens: { input: 90, output: 90 },
+      },
+    ])
+    createSyntheticDb(DatabaseSync, envDb, [
+      { role: 'assistant', agent: 'env-agent', phase: 'override', tokens: { input: 1, output: 2 } },
+    ])
+    createSyntheticDb(DatabaseSync, explicitDb, [
+      {
+        role: 'assistant',
+        agent: 'explicit-agent',
+        phase: 'explicit',
+        tokens: { input: 9, output: 1 },
+      },
+    ])
+    createIncompatibleDb(DatabaseSync, incompatibleDb)
+
+    const restore = setEnvironment({
+      XDG_DATA_HOME: dataHome,
+      PANTHEON_OPENCODE_VERSION: requestedVersion,
+      PANTHEON_COST_DB: undefined,
+    })
+    try {
+      const selectedOutput = await createCostCommand().pantheon_cost.execute(
+        {},
+        { sessionID: 'cost-probe' },
+      )
+      assertTokensOnly(
+        selectedOutput,
+        requestedVersion === 'v2'
+          ? [
+              { agent: 'aphrodite', phase: 'plan', input: 8, output: 10, total: 18 },
+              { agent: 'zeus', phase: 'audit', input: 4, output: 6, total: 10 },
+            ]
+          : [
+              { agent: 'hermes', phase: 'plan', input: 13, output: 24, total: 37 },
+              { agent: 'athena', phase: 'review', input: 2, output: 5, total: 7 },
+            ],
+        requestedVersion === 'v2'
+          ? { input: 12, output: 16, total: 28 }
+          : { input: 15, output: 29, total: 44 },
+      )
+      checks.push('version-selected DB: PASS')
+    } finally {
+      restore()
+    }
+
+    const envRestore = setEnvironment({
+      XDG_DATA_HOME: dataHome,
+      PANTHEON_OPENCODE_VERSION: requestedVersion,
+      PANTHEON_COST_DB: envDb,
+    })
+    try {
+      const output = await createCostCommand().pantheon_cost.execute(
+        {},
+        { sessionID: 'cost-probe' },
+      )
+      requireOutput(output, '| env-agent | override | 1 | 2 | 3 |', 'PANTHEON_COST_DB')
+      if (output.includes('wrong-version') || output.includes('env-agent') === false) {
+        throw new Error('PANTHEON_COST_DB did not override the version-selected database')
+      }
+      checks.push('PANTHEON_COST_DB override: PASS')
+    } finally {
+      envRestore()
+    }
+
+    const explicitRestore = setEnvironment({
+      XDG_DATA_HOME: dataHome,
+      PANTHEON_OPENCODE_VERSION: requestedVersion,
+      PANTHEON_COST_DB: envDb,
+    })
+    try {
+      const output = await createCostCommand({ dbPath: explicitDb }).pantheon_cost.execute(
+        {},
+        { sessionID: 'cost-probe' },
+      )
+      requireOutput(output, '| explicit-agent | explicit | 9 | 1 | 10 |', 'explicit dbPath')
+      if (output.includes('env-agent')) throw new Error('explicit dbPath did not take precedence')
+      checks.push('explicit dbPath precedence: PASS')
+    } finally {
+      explicitRestore()
+    }
+
+    const missingRestore = setEnvironment({
+      XDG_DATA_HOME: join(root, 'missing-data'),
+      PANTHEON_OPENCODE_VERSION: requestedVersion,
+      PANTHEON_COST_DB: undefined,
+    })
+    try {
+      const output = await createCostCommand().pantheon_cost.execute(
+        {},
+        { sessionID: 'cost-probe' },
+      )
+      requireOutput(output, 'not found', 'missing DB')
+      requireOutput(
+        output,
+        requestedVersion === 'v2' ? 'opencode-v2.db' : 'opencode.db',
+        'selected missing DB path',
+      )
+      checks.push('missing DB: PASS')
+    } finally {
+      missingRestore()
+    }
+
+    const incompatibleOutput = await createCostCommand({
+      dbPath: incompatibleDb,
+    }).pantheon_cost.execute({}, { sessionID: 'cost-probe' })
+    requireOutput(incompatibleOutput, 'incompatible opencode.db schema', 'incompatible schema')
+    checks.push('incompatible schema: PASS')
+    emit('PASS', 'offline synthetic DB checks passed; no real DB was read', checks)
+  } catch (error) {
+    emit('FAIL', diagnostic(error), checks)
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+await main()

package/scripts/recover-zenodo-deposition.mjs

@@ -0,0 +1,146 @@
+import { pathToFileURL } from 'node:url'
+import { validateZenodoResponse } from './zenodo-release-state.mjs'
+
+export function zenodoReleaseMarker(tag) {
+  if (typeof tag !== 'string' || !/^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(tag))
+    throw new Error('Release tag is invalid.')
+  return `pantheon-opencode-release:${tag}`
+}
+
+function depositionDescription(deposition) {
+  return [deposition?.metadata?.description, deposition?.description]
+    .filter((value) => typeof value === 'string')
+    .join('\n')
+}
+
+function exactTotal(value) {
+  if (Number.isSafeInteger(value) && value >= 0) return value
+  if (
+    value &&
+    typeof value === 'object' &&
+    Number.isSafeInteger(value.value) &&
+    value.value >= 0 &&
+    (value.relation === undefined || value.relation === 'eq')
+  )
+    return value.value
+  return null
+}
+
+export async function findUniqueZenodoDeposition(
+  depositionsUrl,
+  token,
+  releaseMarker,
+  fetchImpl = fetch,
+) {
+  let url
+  try {
+    url = new URL(depositionsUrl)
+  } catch {
+    throw new Error('Zenodo deposition URL must be a valid absolute HTTPS URL.')
+  }
+  if (
+    url.protocol !== 'https:' ||
+    !url.hostname ||
+    url.username ||
+    url.password ||
+    url.hash ||
+    /%(?![0-9A-Fa-f]{2})/.test(depositionsUrl) ||
+    /[\s{}\\|^`]/.test(depositionsUrl)
+  )
+    throw new Error('Zenodo deposition URL must be a valid HTTPS URL without credentials.')
+  if (typeof releaseMarker !== 'string' || !releaseMarker)
+    throw new Error('Zenodo release marker is required.')
+  if (typeof token !== 'string' || !token) throw new Error('Zenodo token is required.')
+  url.searchParams.set('q', releaseMarker)
+  // Zenodo documents page/size for this endpoint.  The response's links are
+  // optional, so keep a deterministic fallback for the real hits/total shape.
+  url.searchParams.set('page', '1')
+  url.searchParams.set('size', '100')
+  const candidates = []
+  const visitedUrls = new Set()
+  let nextUrl = url
+  let pageNumber = 1
+  let expectedTotal = null
+  while (nextUrl) {
+    const currentUrl = String(nextUrl)
+    if (visitedUrls.has(currentUrl)) throw new Error('Zenodo search returned a pagination cycle.')
+    visitedUrls.add(currentUrl)
+    const response = await fetchImpl(nextUrl, {
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+    })
+    if (!response.ok) throw new Error(`Zenodo deposition search failed (${response.status}).`)
+    const payload = await response.json()
+    if (Array.isArray(payload)) {
+      throw new Error('Zenodo search returned ambiguous pagination.')
+    }
+    const page = payload?.hits?.hits
+    const total = payload?.hits?.total
+    const normalizedTotal = exactTotal(total)
+    if (!Array.isArray(page) || normalizedTotal === null)
+      throw new Error('Zenodo search returned ambiguous pagination.')
+    if (expectedTotal !== null && expectedTotal !== normalizedTotal)
+      throw new Error('Zenodo search returned inconsistent pagination totals.')
+    expectedTotal = normalizedTotal
+    candidates.push(...page)
+    const rawNext = payload?.links?.next
+    if (candidates.length >= expectedTotal) {
+      nextUrl = null
+    } else if (rawNext === null || rawNext === undefined || rawNext === '') {
+      // Some Zenodo Cloud responses omit links entirely.  Continue with the
+      // documented page parameter instead of treating the first page as the
+      // complete search result.
+      if (page.length === 0)
+        throw new Error('Zenodo search ended before all results were examined.')
+      pageNumber += 1
+      const pagedNext = new URL(url)
+      pagedNext.searchParams.set('page', String(pageNumber))
+      nextUrl = pagedNext
+    } else {
+      if (typeof rawNext !== 'string')
+        throw new Error('Zenodo search returned an invalid pagination link.')
+      let parsedNext
+      try {
+        parsedNext = new URL(rawNext, url)
+      } catch {
+        throw new Error('Zenodo search returned an invalid pagination link.')
+      }
+      if (
+        parsedNext.protocol !== 'https:' ||
+        parsedNext.origin !== url.origin ||
+        parsedNext.pathname !== url.pathname
+      )
+        throw new Error('Zenodo search returned an unsafe pagination link.')
+      const linkedPage = Number(parsedNext.searchParams.get('page'))
+      if (Number.isSafeInteger(linkedPage) && linkedPage > pageNumber) {
+        pageNumber = linkedPage
+      }
+      nextUrl = parsedNext
+    }
+  }
+  const escapedMarker = releaseMarker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const markerPattern = new RegExp(`(?:^|[^A-Za-z0-9._:-])${escapedMarker}(?![A-Za-z0-9.-])`)
+  const matches = candidates.filter((deposition) =>
+    markerPattern.test(depositionDescription(deposition)),
+  )
+  if (matches.length === 0) return null
+  if (matches.length !== 1) {
+    throw new Error(
+      `Zenodo recovery requires exactly one matching deposition; found ${matches.length}.`,
+    )
+  }
+  return validateZenodoResponse(matches[0])
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const result = await findUniqueZenodoDeposition(
+      process.env.ZENODO_DEPOSITIONS_URL,
+      process.env.ZENODO_TOKEN,
+      process.env.RELEASE_MARKER,
+    )
+    process.stdout.write(JSON.stringify(result))
+  } catch (error) {
+    console.error(`zenodo recovery: ${error.message}`)
+    process.exit(1)
+  }
+}