@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/evidence-lifecycle-contract.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export const LIFECYCLE_PHASES = [
+  'pr-head-authorization',
+  'queue-admission',
+  'synthetic-queue-head-execution',
+  'target-branch-ancestry',
+]
+
+const PHASES = {
+  'pr-head-authorization': {
+    rank: 0,
+    subjectKinds: ['pr-head-sha'],
+    transitions: ['authorize-enqueue'],
+  },
+  'queue-admission': {
+    rank: 1,
+    subjectKinds: ['pr-head-sha'],
+    transitions: ['enqueue'],
+  },
+  'synthetic-queue-head-execution': {
+    rank: 2,
+    subjectKinds: ['synthetic-queue-head-sha'],
+    transitions: ['record-queue-execution'],
+  },
+  'target-branch-ancestry': {
+    rank: 3,
+    subjectKinds: ['merge-commit-sha'],
+    transitions: ['finalize-delivery'],
+  },
+}
+
+const TRANSITION_RANK = {
+  'authorize-enqueue': 0,
+  enqueue: 1,
+  'record-queue-execution': 2,
+  'finalize-delivery': 3,
+}
+
+const PROVIDERS = {
+  github: {
+    'read-exact-pr-head-checks': {
+      phase: 'pr-head-authorization', subjectKind: 'pr-head-sha', producer: 'github-actions',
+    },
+  },
+  'resolve-issues': {
+    'evaluate-enqueue-eligibility': {
+      phase: 'queue-admission', subjectKind: 'pr-head-sha', producer: 'resolve-issues-orchestrator',
+    },
+  },
+  mergify: {
+    'read-synthetic-queue-checks': {
+      phase: 'synthetic-queue-head-execution', subjectKind: 'synthetic-queue-head-sha', producer: 'mergify-queue',
+    },
+  },
+  git: {
+    'fetch-target-and-check-ancestry': {
+      phase: 'target-branch-ancestry', subjectKind: 'merge-commit-sha', producer: 'target-branch',
+    },
+  },
+}
+
+const FAILURE_BEHAVIORS = ['block-transition', 'keep-candidate-frozen', 'mark-delivery-unproven']
+const ROOT_FIELDS = ['version', 'discoveredConditions', 'conditions']
+const CONDITION_FIELDS = [
+  'id', 'phase', 'subjectKind', 'producer', 'provider', 'acquisitionOperation',
+  'consumingTransition', 'failureBehavior',
+]
+const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0
+
+export function validateEvidenceLifecycleContract(artifact) {
+  const errors = []
+  if (artifact == null || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    return { ok: false, errors: ['artifact must be a JSON object'] }
+  }
+  for (const field of Object.keys(artifact)) {
+    if (!ROOT_FIELDS.includes(field)) errors.push(`artifact has unknown property: ${field}`)
+  }
+  if (artifact.version !== 1) errors.push('artifact.version must be 1')
+
+  const discovered = Array.isArray(artifact.discoveredConditions) ? artifact.discoveredConditions : []
+  if (!Array.isArray(artifact.discoveredConditions) || discovered.length === 0) {
+    errors.push('artifact.discoveredConditions must be a non-empty array')
+  }
+  if (discovered.some((id) => !nonEmpty(id))) errors.push('artifact.discoveredConditions entries must be non-empty strings')
+  const discoveredSet = new Set(discovered)
+  if (discoveredSet.size !== discovered.length) errors.push('artifact.discoveredConditions entries must be unique')
+
+  const conditions = Array.isArray(artifact.conditions) ? artifact.conditions : []
+  if (!Array.isArray(artifact.conditions) || conditions.length === 0) {
+    errors.push('artifact.conditions must be a non-empty array')
+  }
+  const conditionIds = []
+  for (const [index, condition] of conditions.entries()) {
+    const at = `conditions[${index}]`
+    if (condition == null || typeof condition !== 'object' || Array.isArray(condition)) {
+      errors.push(`${at} must be an object`)
+      continue
+    }
+    for (const field of Object.keys(condition)) {
+      if (!CONDITION_FIELDS.includes(field)) errors.push(`${at} has unknown property: ${field}`)
+    }
+    for (const field of CONDITION_FIELDS) {
+      if (!nonEmpty(condition[field])) errors.push(`${at}.${field} is required`)
+    }
+    if (nonEmpty(condition.id)) conditionIds.push(condition.id)
+
+    const phase = PHASES[condition.phase]
+    if (!phase && nonEmpty(condition.phase)) errors.push(`${at} has unknown phase: ${condition.phase}`)
+    const provider = PROVIDERS[condition.provider]
+    if (!provider && nonEmpty(condition.provider)) errors.push(`${at} has unknown provider: ${condition.provider}`)
+
+    const transitionRank = TRANSITION_RANK[condition.consumingTransition]
+    if (phase && transitionRank !== undefined && phase.rank > transitionRank) {
+      errors.push(`${at}: phase ${condition.phase} occurs after consuming transition ${condition.consumingTransition}; this requires future evidence before the transition that makes it available`)
+    }
+    if (phase && nonEmpty(condition.subjectKind) && !phase.subjectKinds.includes(condition.subjectKind)) {
+      errors.push(`${at}.subjectKind ${condition.subjectKind} does not match phase ${condition.phase}`)
+    }
+    if (phase && nonEmpty(condition.consumingTransition) && !phase.transitions.includes(condition.consumingTransition)) {
+      errors.push(`${at}.consumingTransition ${condition.consumingTransition} does not match phase ${condition.phase}`)
+    }
+    if (nonEmpty(condition.consumingTransition) && transitionRank === undefined) {
+      errors.push(`${at} has unknown consumingTransition: ${condition.consumingTransition}`)
+    }
+    if (nonEmpty(condition.failureBehavior) && !FAILURE_BEHAVIORS.includes(condition.failureBehavior)) {
+      errors.push(`${at} has unknown failureBehavior: ${condition.failureBehavior}`)
+    }
+
+    if (provider && nonEmpty(condition.acquisitionOperation)) {
+      const operation = provider[condition.acquisitionOperation]
+      if (!operation) {
+        errors.push(`${at} has unsupported acquisition operation ${condition.acquisitionOperation} for provider ${condition.provider}`)
+      } else {
+        if (nonEmpty(condition.producer) && condition.producer !== operation.producer) {
+          errors.push(`${at}.producer ${condition.producer} does not match ${condition.provider}/${condition.acquisitionOperation} producer ${operation.producer}`)
+        }
+        if (nonEmpty(condition.phase) && condition.phase !== operation.phase) {
+          errors.push(`${at}.phase ${condition.phase} does not match ${condition.provider}/${condition.acquisitionOperation} phase ${operation.phase}`)
+        }
+        if (nonEmpty(condition.subjectKind) && condition.subjectKind !== operation.subjectKind) {
+          errors.push(`${at}.subjectKind ${condition.subjectKind} does not match ${condition.provider}/${condition.acquisitionOperation} subject ${operation.subjectKind}`)
+        }
+      }
+    }
+  }
+
+  const conditionSet = new Set(conditionIds)
+  if (conditionSet.size !== conditionIds.length) errors.push('artifact.conditions ids must be unique')
+  for (const id of discoveredSet) {
+    if (!conditionSet.has(id)) errors.push(`discovered condition ${id} has no lifecycle row`)
+  }
+  for (const id of conditionSet) {
+    if (!discoveredSet.has(id)) errors.push(`condition ${id} was not declared as discovered`)
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+function usage() {
+  return 'usage: evidence-lifecycle-contract.mjs validate <artifact.json>\n'
+}
+
+export function runCli(argv = process.argv.slice(2)) {
+  if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) {
+    process.stdout.write(usage())
+    return 0
+  }
+  if (argv.length !== 2 || argv[0] !== 'validate') {
+    process.stderr.write(usage())
+    return 2
+  }
+  try {
+    const artifact = JSON.parse(fs.readFileSync(argv[1], 'utf8'))
+    const result = validateEvidenceLifecycleContract(artifact)
+    if (!result.ok) {
+      process.stderr.write(`evidence-lifecycle-contract: INVALID\n${result.errors.map((error) => `  - ${error}`).join('\n')}\n`)
+      return 1
+    }
+    process.stdout.write(`evidence-lifecycle-contract: VALID (${artifact.conditions?.length ?? 0} conditions)\n`)
+    return 0
+  } catch (error) {
+    process.stderr.write(`evidence-lifecycle-contract: ${error.message}\n`)
+    return 2
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = runCli()

package/skills/engineering/resolve-issues/scripts/exact-head-ci.mjs

@@ -0,0 +1,413 @@
+// exact-head-ci — transactional PR choreography for collecting CI evidence at one
+// immutable pull-request head. The provider command is the only external boundary:
+// it accepts one JSON operation on stdin and returns one JSON object on stdout.
+
+import fs from 'node:fs'
+import { execFile } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import {
+  EXACT_HEAD_ARTIFACT_VERSION,
+  EXACT_HEAD_COLLECTION_MODES,
+  providerWorkflowIdentityMatches,
+  sameExactHeadState,
+  validateExactHeadArtifact,
+} from '../../engineering-runtime/scripts/exact-head-artifact.mjs'
+import { checksForPhase, locallyReproducedJobs, validatePublishOnlyEvidence, validateRequiredCheckPlan } from '../../engineering-runtime/scripts/required-check-plan.mjs'
+
+export { EXACT_HEAD_ARTIFACT_VERSION, EXACT_HEAD_COLLECTION_MODES, validateExactHeadArtifact }
+export const PROVIDER_OPERATIONS = Object.freeze([
+  'snapshot',
+  'retarget',
+  'set-open',
+  'set-draft',
+  'set-labels',
+  'set-queue-inactive',
+  'dispatch-workflow',
+  'read-workflow',
+  'read-publish-only-checks',
+  'read-queue-execution',
+])
+export const CHOREOGRAPHY_ACTIONS = Object.freeze(['retarget', 'close', 'reopen', 'dispatch'])
+export const JOB_CONCLUSIONS = Object.freeze([
+  'success', 'failure', 'cancelled', 'skipped', 'neutral', 'timed_out',
+  'action_required', 'stale', 'startup_failure', null,
+])
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function uniqueStrings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.trim()) && new Set(value).size === value.length
+}
+
+export function validateRequest(request) {
+  const errors = []
+  if (!isObject(request)) return { ok: false, errors: ['request must be an object'] }
+  if (request.version !== 1) errors.push('request.version must be 1')
+  if (!EXACT_HEAD_COLLECTION_MODES.includes(request.collectionMode)) errors.push(`collectionMode must be one of ${EXACT_HEAD_COLLECTION_MODES.join('|')}`)
+  if (typeof request.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(request.repository)) errors.push('repository must be owner/name')
+  if (!Number.isInteger(request.pr) || request.pr < 1) errors.push('pr must be a positive integer')
+  if (typeof request.expectedHeadSha !== 'string' || !/^[0-9a-f]{40}$/i.test(request.expectedHeadSha)) errors.push('expectedHeadSha must be a full 40-character commit SHA')
+  if (!isObject(request.provider) || typeof request.provider.command !== 'string' || !request.provider.command.trim()) errors.push('provider.command must be a non-empty string')
+  if (request.provider?.args !== undefined && !uniqueStrings(request.provider.args)) errors.push('provider.args must be an array of unique non-empty strings')
+  if (request.provider?.config !== undefined && !isObject(request.provider.config)) errors.push('provider.config must be an object')
+  if (!isObject(request.workflow) || typeof request.workflow.id !== 'string' || !request.workflow.id.trim()) errors.push('workflow.id must be a non-empty string')
+  if (request.collectionMode === 'choreographed') {
+    if (typeof request.temporaryBase !== 'string' || !request.temporaryBase.trim()) errors.push('temporaryBase must be a non-empty string')
+    if (!Array.isArray(request.choreography) || request.choreography.length === 0) errors.push('choreography must be a non-empty array')
+    else {
+      for (const action of request.choreography) if (!CHOREOGRAPHY_ACTIONS.includes(action)) errors.push(`unsupported choreography action "${action}"`)
+      if (request.choreography.filter((action) => action === 'dispatch').length !== 1) errors.push('choreography must contain dispatch exactly once')
+      if (!request.choreography.includes('retarget')) errors.push('choreography must contain retarget')
+    }
+    if (typeof request.workflow?.ref !== 'string' || !request.workflow.ref.trim()) errors.push('workflow.ref must be a non-empty string')
+    if (request.workflow?.inputs !== undefined && !isObject(request.workflow.inputs)) errors.push('workflow.inputs must be an object')
+    if (Object.hasOwn(request.workflow || {}, 'runId')) errors.push('choreographed workflow must not supply runId; dispatch acquires provider run identity')
+  }
+  if (request.collectionMode === 'observed-existing-run') {
+    if (Object.hasOwn(request, 'temporaryBase')) errors.push('observed-existing-run must not contain temporaryBase')
+    if (Object.hasOwn(request, 'choreography')) errors.push('observed-existing-run must not contain choreography')
+    if (typeof request.workflow?.runId !== 'string' && typeof request.workflow?.runId !== 'number') errors.push('observed-existing-run workflow.runId must identify the existing provider run')
+    if (Object.hasOwn(request.workflow || {}, 'ref') || Object.hasOwn(request.workflow || {}, 'inputs')) errors.push('observed-existing-run workflow must contain only existing workflow/run identity, not dispatch ref or inputs')
+  }
+  if (!isObject(request.policy)) errors.push('policy must be an object')
+  if (Object.hasOwn(request.policy || {}, 'requiredJobs')) errors.push('policy.requiredJobs is legacy; put every live condition in requiredCheckPlan and derive local jobs from it')
+  if (Object.hasOwn(request.policy || {}, 'allowedSkippedJobs')) errors.push('policy.allowedSkippedJobs is legacy; put explicit allowed skips in requiredCheckPlan')
+  const plan = validateRequiredCheckPlan(request.requiredCheckPlan, { expectedHeadSha: request.expectedHeadSha })
+  errors.push(...plan.errors.map((error) => `requiredCheckPlan: ${error}`))
+  for (const field of ['pollIntervalMs', 'timeoutMs']) {
+    if (!Number.isInteger(request.policy?.[field]) || request.policy[field] < 1) errors.push(`policy.${field} must be a positive integer`)
+  }
+  if (Number.isInteger(request.policy?.pollIntervalMs) && Number.isInteger(request.policy?.timeoutMs) && request.policy.pollIntervalMs > request.policy.timeoutMs) {
+    errors.push('policy.pollIntervalMs cannot exceed policy.timeoutMs')
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+export function validateSnapshot(snapshot) {
+  const errors = []
+  if (!isObject(snapshot)) return { ok: false, errors: ['provider snapshot must be an object'] }
+  if (typeof snapshot.base !== 'string' || !snapshot.base.trim()) errors.push('snapshot.base must be a non-empty string')
+  if (typeof snapshot.headSha !== 'string' || !/^[0-9a-f]{40}$/i.test(snapshot.headSha)) errors.push('snapshot.headSha must be a full 40-character commit SHA')
+  if (typeof snapshot.open !== 'boolean') errors.push('snapshot.open must be boolean')
+  if (typeof snapshot.draft !== 'boolean') errors.push('snapshot.draft must be boolean')
+  if (!uniqueStrings(snapshot.labels)) errors.push('snapshot.labels must be an array of unique non-empty strings')
+  if (!isObject(snapshot.queue)) errors.push('snapshot.queue must be an object')
+  else if (typeof snapshot.queue.active !== 'boolean') errors.push('snapshot.queue.active must be boolean')
+  if (!isObject(snapshot.reviews)) errors.push('snapshot.reviews must be an object')
+  return { ok: errors.length === 0, errors }
+}
+
+export function classifyJobs(jobs, policy) {
+  const normalized = []
+  const errors = []
+  for (const [index, job] of (Array.isArray(jobs) ? jobs : []).entries()) {
+    if (!isObject(job) || (typeof job.id !== 'number' && typeof job.id !== 'string') || typeof job.name !== 'string' || !job.name.trim()) {
+      errors.push(`jobs[${index}] requires id and name`)
+      continue
+    }
+    const conclusion = job.conclusion == null ? null : String(job.conclusion).toLowerCase()
+    if (!JOB_CONCLUSIONS.includes(conclusion)) errors.push(`job "${job.name}" has unsupported conclusion "${job.conclusion}"`)
+    normalized.push({ id: job.id, name: job.name, status: job.status ?? null, conclusion })
+  }
+  if (!Array.isArray(jobs)) errors.push('workflow jobs must be an array')
+  const byName = new Map()
+  for (const job of normalized) {
+    if (byName.has(job.name)) errors.push(`workflow jobs have duplicate/ambiguous evidence for ${job.name}`)
+    else byName.set(job.name, job)
+  }
+  const requiredMissing = policy.requiredJobs.filter((name) => !byName.has(name))
+  const requiredNotSuccessful = policy.requiredJobs.filter((name) => byName.has(name) && byName.get(name).conclusion !== 'success')
+  const allowedSkipped = new Set(policy.allowedSkippedJobs)
+  const disallowedSkipped = normalized.filter((job) => job.conclusion === 'skipped' && !allowedSkipped.has(job.name)).map((job) => job.name)
+  const failed = normalized.filter((job) => !['success', 'skipped'].includes(job.conclusion)).map((job) => `${job.name} (${job.conclusion ?? 'pending'})`)
+  const skipped = normalized.filter((job) => job.conclusion === 'skipped').map((job) => job.name)
+  let outcome = 'success'
+  if (normalized.length === 0) outcome = 'zero-job-workflow-failure'
+  else if (normalized.some((job) => job.conclusion === 'cancelled')) outcome = 'cancelled'
+  else if (failed.length || requiredMissing.length || requiredNotSuccessful.length || disallowedSkipped.length || errors.length) outcome = 'failure'
+  else if (skipped.length) outcome = 'success-with-skipped'
+  return {
+    ok: outcome === 'success' || outcome === 'success-with-skipped',
+    jobs: normalized,
+    errors,
+    summary: { outcome, requiredMissing, requiredNotSuccessful, disallowedSkipped, failed, skipped },
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function providerCall(request, operation, fields = {}) {
+  if (!PROVIDER_OPERATIONS.includes(operation)) throw new Error(`forbidden provider operation "${operation}"`)
+  const payload = { version: 1, operation, repository: request.repository, pr: request.pr, providerConfig: request.provider.config || {}, ...fields }
+  const stdout = await new Promise((resolve, reject) => {
+    const child = execFile(request.provider.command, request.provider.args || [], {
+      encoding: 'utf8', timeout: request.policy.timeoutMs, maxBuffer: 16 * 1024 * 1024,
+    }, (error, output) => error ? reject(error) : resolve(output))
+    child.stdin.end(`${JSON.stringify(payload)}\n`)
+  })
+  let response
+  try { response = JSON.parse(stdout) } catch { throw new Error(`provider operation "${operation}" returned invalid JSON`) }
+  if (!isObject(response)) throw new Error(`provider operation "${operation}" must return an object`)
+  return response
+}
+
+function assertHead(snapshot, expected, at) {
+  if (snapshot.headSha !== expected) throw new Error(`head-drift at ${at}: expected ${expected}, observed ${snapshot.headSha}`)
+}
+
+async function mutate(request, operation, fields) {
+  const result = await providerCall(request, operation, fields)
+  if (result.ok !== true) throw new Error(`provider operation "${operation}" did not confirm success`)
+}
+
+async function restore(request, snapshot, { mutateState }) {
+  const operations = []
+  const errors = []
+  const attempt = async (operation, fields) => {
+    try {
+      await mutate(request, operation, fields)
+      operations.push({ operation, status: 'restored' })
+    } catch (error) {
+      const message = String(error.message || error)
+      operations.push({ operation, status: 'failed', error: message })
+      errors.push(`${operation}: ${message}`)
+    }
+  }
+  if (mutateState) {
+    await attempt('set-open', { open: true })
+    await attempt('set-draft', { draft: snapshot.draft })
+    await attempt('retarget', { base: snapshot.base })
+    if (!snapshot.queue.active) await attempt('set-queue-inactive', {})
+    await attempt('set-labels', { labels: snapshot.labels })
+    if (!snapshot.open) await attempt('set-open', { open: false })
+  }
+  let observed = null
+  try { observed = await providerCall(request, 'snapshot') } catch (error) { errors.push(`snapshot: ${String(error.message || error)}`) }
+  const valid = validateSnapshot(observed)
+  errors.push(...valid.errors.map((error) => `restoration ${error}`))
+  const proved = valid.ok && sameExactHeadState(snapshot, observed)
+  if (valid.ok && !proved) errors.push('restoration observation differs from original snapshot')
+  return { attempted: true, operations, observed, proved, errors }
+}
+
+export async function runExactHead(request, { now = () => new Date().toISOString(), interruption = () => null } = {}) {
+  const requestVerdict = validateRequest(request)
+  if (!requestVerdict.ok) throw new Error(`invalid exact-head request: ${requestVerdict.errors.join('; ')}`)
+  const derivedPolicy = {
+    requiredJobs: locallyReproducedJobs(request.requiredCheckPlan),
+    allowedSkippedJobs: request.requiredCheckPlan.allowedSkippedJobs,
+  }
+  let snapshot = null
+  let observationAfter = null
+  let workflow = {
+    id: request.workflow.id,
+    provider: null,
+    runId: request.collectionMode === 'observed-existing-run' ? request.workflow.runId : null,
+    status: request.collectionMode === 'observed-existing-run' ? 'existing' : 'not-created',
+    conclusion: null,
+    headSha: request.expectedHeadSha,
+  }
+  let jobs = []
+  let publishOnlyEvidence = []
+  let summary = { outcome: request.collectionMode === 'choreographed' ? 'workflow-creation-failure' : 'workflow-observation-failure', requiredMissing: [], requiredNotSuccessful: [], disallowedSkipped: [], failed: [], skipped: [] }
+  const errors = []
+  let restoration = { attempted: false, operations: [], observed: null, proved: false, errors: [] }
+  let mutated = false
+  const checkpoint = (at) => {
+    const signal = interruption()
+    if (signal) throw new Error(`interrupted by ${signal} at ${at}`)
+  }
+  const applyMutation = async (operation, fields) => {
+    mutated = true
+    await mutate(request, operation, fields)
+  }
+  try {
+    snapshot = await providerCall(request, 'snapshot')
+    const snapshotVerdict = validateSnapshot(snapshot)
+    if (!snapshotVerdict.ok) throw new Error(`invalid provider snapshot: ${snapshotVerdict.errors.join('; ')}`)
+    assertHead(snapshot, request.expectedHeadSha, 'initial snapshot')
+    if (request.collectionMode === 'choreographed') {
+      if (snapshot.queue.active) throw new Error('active queue state cannot be restored because this adapter must never enqueue; dequeue the PR explicitly before exact-head CI')
+      for (const action of request.choreography) {
+        checkpoint(`before ${action}`)
+        if (action === 'retarget') await applyMutation('retarget', { base: request.temporaryBase })
+        else if (action === 'close') await applyMutation('set-open', { open: false })
+        else if (action === 'reopen') await applyMutation('set-open', { open: true })
+        else if (action === 'dispatch') {
+          const beforeDispatch = await providerCall(request, 'snapshot')
+          const beforeVerdict = validateSnapshot(beforeDispatch)
+          if (!beforeVerdict.ok) throw new Error(`invalid pre-dispatch snapshot: ${beforeVerdict.errors.join('; ')}`)
+          assertHead(beforeDispatch, request.expectedHeadSha, 'before workflow dispatch')
+          const created = await providerCall(request, 'dispatch-workflow', {
+            workflow: request.workflow.id,
+            ref: request.workflow.ref,
+            inputs: request.workflow.inputs || {},
+            headSha: request.expectedHeadSha,
+          })
+          if (typeof created.runId !== 'string' && typeof created.runId !== 'number') throw new Error('workflow-creation-failure: provider returned no runId')
+          workflow = { ...workflow, runId: created.runId, status: 'created' }
+        }
+      }
+    }
+    const deadline = Date.now() + request.policy.timeoutMs
+    while (true) {
+      checkpoint('before workflow read')
+      const expectedRunId = workflow.runId
+      const observed = await providerCall(request, 'read-workflow', {
+        runId: expectedRunId,
+        workflowId: request.workflow.id,
+        headSha: request.expectedHeadSha,
+      })
+      workflow = {
+        ...workflow,
+        provider: observed.workflow ?? null,
+        runId: observed.runId,
+        status: observed.status ?? null,
+        conclusion: observed.conclusion ?? null,
+        headSha: observed.headSha ?? null,
+      }
+      if (typeof observed.runId !== 'string' && typeof observed.runId !== 'number') throw new Error('provider workflow observation returned no runId')
+      if (String(observed.runId) !== String(expectedRunId)) throw new Error(`workflow run identity mismatch: expected ${expectedRunId}, observed ${observed.runId}`)
+      if (!providerWorkflowIdentityMatches(request.workflow.id, observed.workflow)) {
+        const providerIdentity = observed.workflow?.name || observed.workflow?.path || observed.workflow?.id || 'missing'
+        throw new Error(`workflow identity mismatch: expected ${request.workflow.id}, observed ${providerIdentity}`)
+      }
+      if (workflow.headSha !== request.expectedHeadSha) throw new Error(`head-drift in workflow: expected ${request.expectedHeadSha}, observed ${workflow.headSha}`)
+      if (observed.status === 'completed') {
+        const classified = classifyJobs(observed.jobs, derivedPolicy)
+        jobs = classified.jobs
+        summary = classified.summary
+        errors.push(...classified.errors)
+        if (observed.conclusion === 'cancelled') summary.outcome = 'cancelled'
+        else if (observed.conclusion && observed.conclusion !== 'success' && summary.outcome !== 'zero-job-workflow-failure') summary.outcome = 'failure'
+        const publishOnly = checksForPhase(request.requiredCheckPlan, 'pr-head').filter((check) => check.classification === 'publish-only')
+        if (publishOnly.length) {
+          const observedPublishOnly = await providerCall(request, 'read-publish-only-checks', { headSha: request.expectedHeadSha, names: publishOnly.map((check) => check.name) })
+          if (!Array.isArray(observedPublishOnly.checks)) throw new Error('provider publish-only observation must return checks array')
+          publishOnlyEvidence = observedPublishOnly.checks
+        }
+        break
+      }
+      if (Date.now() >= deadline) throw new Error(`workflow timed out after ${request.policy.timeoutMs}ms`)
+      await sleep(request.policy.pollIntervalMs)
+    }
+  } catch (error) {
+    const message = String(error.message || error)
+    errors.push(message)
+    if (/interrupted by /.test(message)) summary.outcome = 'interrupted'
+    else if (/head-drift/.test(message)) summary.outcome = 'head-drift'
+    else if (workflow.runId == null) summary.outcome = 'workflow-creation-failure'
+  } finally {
+    if (snapshot && request.collectionMode === 'choreographed') {
+      restoration = await restore(request, snapshot, { mutateState: mutated })
+      errors.push(...restoration.errors)
+    }
+    if (snapshot && request.collectionMode === 'observed-existing-run') {
+      try {
+        observationAfter = await providerCall(request, 'snapshot')
+        const finalVerdict = validateSnapshot(observationAfter)
+        if (!finalVerdict.ok) throw new Error(`invalid final provider snapshot: ${finalVerdict.errors.join('; ')}`)
+        assertHead(observationAfter, request.expectedHeadSha, 'after provider evidence acquisition')
+      } catch (error) {
+        const message = String(error.message || error)
+        errors.push(message)
+        if (/head-drift/.test(message)) summary.outcome = 'head-drift'
+      }
+    }
+  }
+  const publishOnlyVerdict = validatePublishOnlyEvidence(request.requiredCheckPlan, publishOnlyEvidence, {
+    expectedHeadSha: request.expectedHeadSha,
+    expectedRepository: request.repository,
+    expectedPr: request.pr,
+  })
+  errors.push(...publishOnlyVerdict.errors)
+  const provisional = {
+    version: EXACT_HEAD_ARTIFACT_VERSION,
+    kind: 'exact-head-ci',
+    collectionMode: request.collectionMode,
+    repository: request.repository,
+    pr: request.pr,
+    headSha: request.expectedHeadSha,
+    publishOnlyEvidence,
+    generatedAt: now(),
+    provider: { command: request.provider.command },
+    ...(request.collectionMode === 'choreographed'
+      ? { choreography: request.choreography, snapshot }
+      : { observation: { before: snapshot, after: observationAfter } }),
+    workflow,
+    jobs,
+    requiredCheckPlan: request.requiredCheckPlan,
+    policy: {
+      requiredJobs: derivedPolicy.requiredJobs,
+      allowedSkippedJobs: derivedPolicy.allowedSkippedJobs,
+    },
+    summary,
+    ...(request.collectionMode === 'choreographed' ? { restoration } : {}),
+    errors,
+    status: 'fail',
+  }
+  const provenanceProved = request.collectionMode === 'choreographed'
+    ? restoration.proved
+    : observationAfter?.headSha === request.expectedHeadSha
+  const passing = provenanceProved && errors.length === 0 && ['success', 'success-with-skipped'].includes(summary.outcome)
+  return { ...provisional, status: passing ? 'pass' : 'fail' }
+}
+
+function parseArgs(argv) {
+  const options = {}
+  const positional = []
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index]
+    if (arg === '--input') options.input = argv[++index]
+    else if (arg === '--out') options.out = argv[++index]
+    else if (arg === '--head') options.head = argv[++index]
+    else positional.push(arg)
+  }
+  return { command: positional[0], file: positional[1], options }
+}
+
+export async function runCli(argv) {
+  const { command, file, options } = parseArgs(argv)
+  if (command === '--help' || command === '-h' || command === 'help') {
+    console.log('usage: exact-head-ci run --input <request.json> --out <artifact.json> | validate <artifact.json> --head <sha>')
+    return 0
+  }
+  if (command === 'run') {
+    if (!options.input || !options.out) { console.error('exact-head-ci run requires --input <request.json> --out <artifact.json>'); return 2 }
+    let interrupted = null
+    const onSignal = (signal) => { interrupted = signal }
+    process.on('SIGINT', onSignal)
+    process.on('SIGTERM', onSignal)
+    try {
+      const artifact = await runExactHead(JSON.parse(fs.readFileSync(options.input, 'utf8')), { interruption: () => interrupted })
+      fs.writeFileSync(options.out, `${JSON.stringify(artifact, null, 2)}\n`)
+      const provenance = artifact.collectionMode === 'choreographed'
+        ? `restoration ${artifact.restoration?.proved ? 'proved' : 'unproved'}`
+        : `live head observed before and after provider evidence acquisition${artifact.observation?.after?.headSha === artifact.headSha ? '' : ' (unproved)'}`
+      console.log(`exact-head-ci: ${artifact.status === 'pass' ? 'PASS' : 'FAIL'} at ${artifact.headSha} — ${artifact.summary.outcome}; collection ${artifact.collectionMode}; ${provenance}`)
+      return artifact.status === 'pass' ? 0 : 1
+    } catch (error) {
+      console.error(`exact-head-ci: ${String(error.message || error)}`)
+      return 2
+    } finally {
+      process.off('SIGINT', onSignal)
+      process.off('SIGTERM', onSignal)
+    }
+  }
+  if (command === 'validate') {
+    if (!file || !options.head) { console.error('exact-head-ci validate <artifact.json> --head <sha>'); return 2 }
+    const artifact = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const verdict = validateExactHeadArtifact(artifact, { expectedHeadSha: options.head })
+    if (verdict.ok) console.log(`exact-head-ci: valid PASS ${artifact.collectionMode} artifact at ${options.head}`)
+    else verdict.errors.forEach((error) => console.error(`error: ${error}`))
+    return verdict.ok ? 0 : 1
+  }
+  console.error('usage: exact-head-ci run --input <request.json> --out <artifact.json> | validate <artifact.json> --head <sha>')
+  return 2
+}
+
+if (isMainModule(import.meta.url)) process.exit(await runCli(process.argv.slice(2)))