@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/report.mjs

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+// The release checkpoint summary: where this attempt actually is, rendered from the manifest at
+// every step transition.
+//
+// Why it exists. A release is long, mostly waiting, and outward-facing at nearly every step, so the
+// operator's question is always the same — what has actually happened to production, and what is
+// owed next? In pi session 019faea6 the agent answered that well in prose, but ad hoc: a different
+// shape each time, derived from whatever was in context rather than from recorded state. When the
+// session eventually parked at `blocked-manual`, reconstructing what had reached production took
+// reading the whole transcript.
+//
+// THE RULE THIS INHERITS FROM resolve-issues: a step is `done` only when the manifest carries the
+// EVIDENCE for it, never because `step` has moved past it. `step` is progress and evidence is
+// fact, and the gap between them is exactly where a release lies to itself — epic-986 recorded
+// four units `merge-ready` with `mergedSha: null` and reported them as delivered. So here, "the
+// candidate exists" is not `step === 'validate-candidate'`; it is a recorded attested identity
+// tuple. A step whose marker has passed but whose evidence is missing renders `undelivered`, which
+// is deliberately not a synonym for `done` — and where the manifest was never the home for that
+// proof, `unrecorded` says so instead of manufacturing a defect (see the three-status note below).
+//
+// It is a pure function of the manifest. No reads, no network — the manifest is the audit trail,
+// and a summary that consulted the world could disagree with the record it is supposed to be
+// reporting.
+
+// Every field name below is CANONICAL — it appears in this skill's own doctrine and in the
+// manifest `run-state.mjs` validates. That is not a stylistic note; the first version of this
+// ladder invented five (`candidateVerdict`, `servingRevision`, `trafficPercent`, `finalTag`,
+// `promotionPr`), none of which any release records. Steps 4a, 4b and 5 could therefore never read
+// `done`, so a perfectly successful release — tagged, shifted, verified — would have ended with
+// this summary insisting three steps were still owed. A summary written to stop a release lying to
+// itself would have lied in the opposite direction, and the noise is what gets a tool switched off.
+//
+// The tests did not catch it because they were self-consistent with the invention: they built
+// manifests using the same made-up names the reader looked for. `field-names-are-canonical` below
+// closes the class by checking the ladder against the doctrine rather than against my memory.
+//
+// THREE STATUSES, NOT TWO. `undelivered` means "this step should have recorded evidence and did
+// not" — a defect. `unrecorded` means "the manifest is not where this step's proof lives" — not a
+// defect, and conflating them is what produced the false alarm above. Step 4a's ALIVE verdict and
+// step 4b's post-shift health live in the durable evidence bundle and in `smoke-verdict.json`, so
+// the manifest genuinely cannot answer for them; the summary says where to look instead of
+// pretending the step failed.
+
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { isFinalizedVerification } from './finalize-release.mjs'
+import { METADATA_SYNC_SOURCE, metadataPrStatus } from './metadata-pr-status.mjs'
+import {
+  CANONICAL_RELEASE_MANIFEST_FIELDS,
+  CANONICAL_RELEASE_FIELDS as CONTRACT_RELEASE_FIELDS,
+  classifyReleaseManifest,
+  normalizeReleaseVerdict,
+} from '../../resolve-issues/scripts/release-state-contract.mjs'
+
+
+export { metadataPrStatus } from './metadata-pr-status.mjs'
+export const checkpointReleaseState = classifyReleaseManifest
+
+export const STEPS = [
+  {
+    id: 'preflight',
+    label: 'Pre-flight — probes + authorization envelope',
+    // `envelope` is a manifest-level field run-state validates, not a release.* one.
+    evidence: (r, m) => (m.envelope && Object.keys(m.envelope).length > 0 ? 'envelope recorded' : null),
+  },
+  {
+    id: 'assemble',
+    label: 'Steps 0-2 — intake, assemble, promotion PR',
+    // `cutCommit` is the recorded artifact of step 1b. Under the trunk + merge-queue topology step
+    // 1 assembles nothing and there is no cut commit, which is why an absence here is `unrecorded`
+    // rather than a defect — the topology decides whether this step had anything to record.
+    // In queue/verified-sha-github-flow modes, the selected eligible SHA plus the recorded
+    // release-readiness checklist is the equivalent evidence (#818).
+    evidence: (r) => {
+      if (r.cutCommit) return `cut commit ${short(r.cutCommit)}`
+      if (r.candidateSha && hasReleaseReadiness(r)) {
+        return `selected SHA ${short(r.candidateSha)}; release readiness recorded`
+      }
+      return null
+    },
+    unrecordedWhen: (r, m) => {
+      if (r.cutCommit) return false
+      if (r.candidateSha && hasReleaseReadiness(r)) return false
+      return isNoCutTopology(m)
+    },
+    unrecordedNote: 'no cut commit — expected under trunk + merge-queue / verified-sha-github-flow, where step 1 assembles nothing; GitFlow owes a cut commit',
+  },
+  {
+    id: 'candidate',
+    label: 'Step 3 — promote, build candidate at 0% traffic',
+    // The identity tuple, not the revision name: a revision name says where to look, the tuple
+    // says what is running there. Principle 12's whole point.
+    evidence: (r) => {
+      const id = r.candidateIdentity
+      if (id && id.sourceSha && id.revision) return `candidate ${id.revision} @ ${short(id.sourceSha)}${id.imageDigestSource ? ` (${id.imageDigestSource})` : ''}`
+      return null // a candidateRevision with no attested identity is not evidence
+    },
+  },
+  {
+    id: 'validate-candidate',
+    label: 'Step 4a — validate the candidate (read-only, pre-exposure)',
+    // The ALIVE/DEAD verdict is `smoke-verdict.json` plus the evidence bundle — deliberately not a
+    // manifest field, because `green-gate.mjs shift` reads the artifact so that "on that exact
+    // candidate" stays a comparison rather than a manifest assertion. When the manifest does carry
+    // a `candidateVerdict`, render it as the pointer to the artifact rather than leaving the step
+    // unrecorded (#818).
+    evidence: (r) => {
+      const v = normalizeReleaseVerdict(r.candidateVerdict)
+      if (!v || typeof v !== 'object') return null
+      // The required evidence tuple is the same for ALIVE and DEAD: state plus the
+      // artifact path, the generation time, and the target that was probed. All three
+      // must be non-empty strings; truthy object values rendered as [object Object] and
+      // let malformed records pass as done (#818 review finding).
+      if (v.state === 'ALIVE' && isNonEmptyString(v.artifactPath) && isNonEmptyString(v.generatedAt) && isNonEmptyString(v.target)) {
+        return `ALIVE at ${v.target} (${v.generatedAt}) — artifact ${v.artifactPath}`
+      }
+      if (v.state === 'DEAD' && isNonEmptyString(v.artifactPath) && isNonEmptyString(v.generatedAt) && isNonEmptyString(v.target)) {
+        return `DEAD — artifact ${v.artifactPath} at ${v.target} (${v.generatedAt})`
+      }
+      return null
+    },
+    unrecordedWhen: (r) => !r.candidateVerdict || typeof r.candidateVerdict !== 'object',
+    unrecordedNote: 'the ALIVE verdict lives in smoke-verdict.json and the evidence bundle, not the manifest',
+  },
+  {
+    id: 'expose',
+    label: 'Step 4b — shift traffic, confirm the serving revision',
+    // `recheckFence` is the canonical record of the pre-shift re-check. It is evidence the fence
+    // ran, which is the manifest's part; the post-shift serving confirmation is bundle evidence.
+    // Where durable processing was declared, `quiescence.servingRevisionAtResume` is the one
+    // serving read the manifest does carry.
+    evidence: (r) => {
+      const resumed = r.quiescence && r.quiescence.servingRevisionAtResume
+      if (resumed) return `fence recorded; serving ${resumed} at resume`
+      if (r.recheckFence) return 'pre-shift re-check fence recorded'
+      return null
+    },
+    unrecordedWhen: (r) => !r.recheckFence && !(r.quiescence && r.quiescence.servingRevisionAtResume),
+    unrecordedNote: 'no re-check fence recorded — if traffic shifted, the post-shift confirmation is in the evidence bundle',
+  },
+  {
+    id: 'verify',
+    label: 'Step 5 — route on the verdict, tag, publish, back-merge',
+    // The attempt reaching `released` is the lease CLOSE, not the terminal record — #963's
+    // finalizer owns the one durable transition that assembles the top-level `verification`
+    // block and advances `step` to done, and step 5 reads done only once that transition is
+    // recorded. The verification must be the shape the finalizer writes (isFinalizedVerification
+    // — finalizedBy + finalizedAt + the six required observations), never merely a non-null
+    // object: a hand-assembled `{}` rendering the release complete here while the finalizer
+    // refused it was the release-finalization-terminal-proof finding. A released attempt still
+    // sitting at `verify` is the Forex v0.1.12 shape: the lease freed while the resume key said
+    // mid-machine, and rendering it done here is what let the checkpoint claim a finished
+    // release the manifest could not prove. `backMerge` is the GitFlow-only follow-on and is
+    // reported when present rather than required.
+    evidence: (r, m) => {
+      if (r.attempt && r.attempt.state === 'released'
+        && m.step === 'done' && isFinalizedVerification(m.verification)) {
+        return `attempt released${r.backMerge ? ' (back-merge recorded)' : ''}`
+      }
+      return null
+    },
+  },
+]
+
+// Canonical `release.*` field names this ladder is allowed to read. Kept beside the ladder so the
+// guard test has one list to check against, and so adding a reader forces a decision about whether
+// the field is real. Sourced from this skill's references and from run-state.mjs's validation.
+export const CANONICAL_RELEASE_FIELDS = CONTRACT_RELEASE_FIELDS
+
+// Deploy-trigger resolution order for the checkpoint line. attempt and envelope.deployTrigger
+// are the declared homes; envelope.version.deployTrigger is what identity-v0.4.1 actually
+// recorded (the version plan nests the shape), and missing that path printed `(undeclared)`
+// while the envelope carried `rc-tag` (#800).
+export function resolveDeployTrigger(manifest) {
+  const m = manifest || {}
+  const r = m.release || {}
+  const attempt = r.attempt || {}
+  const envelope = m.envelope || {}
+  const version = envelope.version && typeof envelope.version === 'object' ? envelope.version : null
+  return attempt.deployTrigger
+    || envelope.deployTrigger
+    || (version && version.deployTrigger)
+    || null
+}
+
+// Metadata-PR completeness lives in metadata-pr-status.mjs so postmortem.mjs can use it
+// without importing this module (report.mjs dynamically imports postmortem.mjs).
+
+// ensure-target-green (#807) — tip check-runs repair phase. Surfaces time spent and outcome
+// on the checkpoint so a release that spent N minutes repairing tip is visible, not buried.
+export function ensureGreenStatus(release) {
+  const eg = release && release.ensureGreen
+  if (!eg || typeof eg !== 'object') return null
+  const outcome = eg.outcome || '(unknown)'
+  const head = eg.finalHead ? String(eg.finalHead).slice(0, 8) : '(none)'
+  const ms = Number.isFinite(eg.durationMs) ? eg.durationMs : null
+  const mins = ms != null ? `${Math.round(ms / 60000)}m` : null
+  const classes = Array.isArray(eg.failingClasses) && eg.failingClasses.length
+    ? ` classes=[${eg.failingClasses.join(',')}]`
+    : ''
+  const time = mins != null ? ` · ${mins}` : ''
+  return { line: `ensure-green: ${outcome} @ ${head}${time}${classes}` }
+}
+
+// Manifest-level fields, from `run-state.mjs`'s own validation. Guarded for the same reason as the
+// release list: `m.slug` was read here for the report title and no manifest has ever carried it —
+// the field is `runSlug` — so every summary would have fallen through to "(unnamed release)".
+export const CANONICAL_MANIFEST_FIELDS = CANONICAL_RELEASE_MANIFEST_FIELDS
+
+const short = (sha) => String(sha || '').slice(0, 8)
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function hasReleaseReadiness(release) {
+  return Array.isArray(release && release.releaseReadiness) && release.releaseReadiness.length > 0
+}
+
+function isNoCutTopology(manifest) {
+  const m = manifest || {}
+  return m.deliveryMode === 'queue' || (m.envelope && m.envelope.mode === 'verified-sha-github-flow')
+}
+
+// Terminal attempt states, and whether each one still holds the lease. `blocked-manual` is
+// terminal-VALUED but holds it — a release parked on a human is still in flight, and rendering it
+// as finished is how a second release starts on top of the first.
+const ATTEMPT_STATES = {
+  open: { holds: true, note: 'in flight' },
+  released: { holds: false, note: 'released' },
+  'failed-pre-promotion': { holds: false, note: 'failed before promotion — nothing exposed' },
+  'rolled-back': { holds: false, note: 'rolled back' },
+  revoked: { holds: false, note: 'revoked (rc tag retained — tags are immutable)' },
+  'blocked-manual': { holds: true, note: 'parked on a human — STILL HOLDS THE LEASE' },
+}
+
+export function stepStatuses(manifest) {
+  const m = manifest || {}
+  const r = m.release || {}
+  const currentIndex = STEPS.findIndex((s) => s.id === m.step)
+  return STEPS.map((step, i) => {
+    const evidence = step.evidence(r, m) || null
+    const unrecorded = !evidence && typeof step.unrecordedWhen === 'function' && step.unrecordedWhen(r, m)
+    let status
+    if (evidence) status = 'done'
+    // `unrecorded` outranks `undelivered` for a passed step: the manifest was never the place this
+    // proof lived, so calling it a defect is a false alarm — and a summary that cries wolf on a
+    // healthy release is one nobody reads by the third time.
+    else if (currentIndex >= 0 && i < currentIndex) status = unrecorded ? 'unrecorded' : 'undelivered'
+    else if (currentIndex >= 0 && i === currentIndex) status = 'current'
+    else status = 'pending'
+    return { id: step.id, label: step.label, status, evidence, note: unrecorded ? step.unrecordedNote : null }
+  })
+}
+
+const MARK = { done: '[x]', current: '[>]', undelivered: '[!]', unrecorded: '[~]', pending: '[ ]' }
+
+export function renderCheckpoint(manifest) {
+  const m = manifest || {}
+  const r = m.release || {}
+  const attempt = r.attempt || {}
+  const state = ATTEMPT_STATES[attempt.state] || null
+  const statuses = stepStatuses(m)
+  const lines = []
+
+  lines.push(`## Release checkpoint — ${m.runSlug || (r.versionPlan && r.versionPlan.nextVersion) || '(unnamed release)'}`)
+  lines.push('')
+  lines.push(`- attempt: \`${attempt.id || '(none)'}\` — ${attempt.state || '(no state)'}${state ? ` (${state.note})` : ''}`)
+  lines.push(`- lease: ${state ? (state.holds ? '**HELD**' : 'free') : '**UNKNOWN — treat as held**'}`)
+  const deployTrigger = resolveDeployTrigger(m)
+  lines.push(`- step: \`${m.step || '(none)'}\`  ·  deploy trigger: \`${deployTrigger || '(undeclared)'}\``)
+  if (r.rcTag) lines.push(`- rc tag: \`${r.rcTag}\``)
+  const meta = metadataPrStatus(r)
+  if (meta) lines.push(`- ${meta.line}`)
+  const ensureGreen = ensureGreenStatus(r)
+  if (ensureGreen) lines.push(`- ${ensureGreen.line}`)
+  lines.push('')
+
+  for (const s of statuses) {
+    const suffix = s.evidence ? ` — ${s.evidence}`
+      : s.status === 'undelivered' ? ' — **step passed with no evidence recorded — NOT done**'
+        : s.status === 'unrecorded' ? ` — not manifest-tracked: ${s.note}`
+          : ''
+    lines.push(`${MARK[s.status]} ${s.label}${suffix}`)
+  }
+
+  // What production is carrying right now, stated separately from progress. Between step 3 and the
+  // shift there is a revision no user reaches, and if the session dies only the manifest says it
+  // exists — so it is named even when nothing has been exposed.
+  lines.push('')
+  lines.push('**Production right now:**')
+  // Which revision is serving is INFERRED from the attempt's own terminal state, not read from a
+  // field — there is no `release.servingRevision`, and inventing one is what made the first version
+  // of this file unusable. The inference is stated so a reader can disbelieve it: `released` means
+  // the shift completed and the candidate is serving, `rolled-back` means it is not, and any other
+  // state means traffic never moved. Where the manifest carries a real post-resume serving read
+  // (`quiescence.servingRevisionAtResume`), that observation wins over any inference.
+  const observedServing = r.quiescence && r.quiescence.servingRevisionAtResume
+  const attemptState = attempt.state
+  if (observedServing) {
+    lines.push(`- serving: \`${observedServing}\` (observed at resume)`)
+  } else if (attemptState === 'released' && (r.candidateRevision || (r.candidateIdentity && r.candidateIdentity.revision))) {
+    lines.push(`- serving: \`${r.candidateRevision || r.candidateIdentity.revision}\` (inferred from attempt \`released\`)`)
+  } else if (r.previousRevision) {
+    lines.push(`- serving: \`${r.previousRevision}\` (incumbent — traffic has not moved${attemptState === 'rolled-back' ? ', restored by rollback' : ''})`)
+  } else {
+    lines.push('- serving: (not recorded)')
+  }
+  if (r.candidateRevision) {
+    const exposed = attemptState === 'released'
+    lines.push(`- candidate: \`${r.candidateRevision}\`${exposed ? ' (exposed)' : ' — at 0% traffic, reached by nobody'}${r.candidateIdentity ? '' : ' — **no attested identity recorded**'}`)
+  }
+  if (r.quiescence) {
+    lines.push(`- durable processing: paused=${!!r.quiescence.pausedAt} resumed=${!!r.quiescence.resumedAt}${r.quiescence.pausedAt && !r.quiescence.resumedAt ? ' — **PAUSED AND NOT RESUMED**' : ''}`)
+  }
+
+  // Only `undelivered` is owed. Counting `unrecorded` here is precisely the false alarm that made
+  // the first version of this summary unusable on a successful release.
+  const undelivered = statuses.filter((s) => s.status === 'undelivered')
+  const next = statuses.find((s) => s.status === 'current') || statuses.find((s) => s.status === 'pending')
+  lines.push('')
+  if (undelivered.length > 0) {
+    lines.push(`**Owed:** ${undelivered.length} step(s) passed without recording their evidence — ${undelivered.map((s) => s.id).join(', ')}. Record it or re-run them; the handoff must not report these as done.`)
+  }
+  lines.push(`**Next:** ${next ? next.label : 'nothing — every step has its evidence'}`)
+  return lines.join('\n')
+}
+
+if (isMainModule(import.meta.url)) {
+  const path = process.argv[2]
+  const flags = new Set(process.argv.slice(3))
+  if (!path) {
+    console.error('usage: report.mjs <run-manifest.json> [--postmortem] [--issue] [--no-save]\n\n'
+      + 'Renders the release checkpoint summary. A step is `done` only when the manifest carries its\n'
+      + 'evidence — `step` moving past it is not enough.\n\n'
+      + 'The post-mortem is computed and SAVED automatically once the release reaches a terminal step\n'
+      + '(done | discard | rollback). --postmortem prints it on demand, which is the only way to see\n'
+      + 'the profile of a release that STALLED — a stall is itself one of its findings.\n\n'
+      + 'When the manifest names a version and `durableEvidenceDir`, the VERSION-LEVEL post-mortem\n'
+      + '(#961) is computed, printed and saved alongside: the aggregate of every durable evidence\n'
+      + 'bundle the version left behind, across all of its attempts.')
+    process.exitCode = 2
+  } else {
+    const { readFileSync } = await import('node:fs')
+    const manifest = JSON.parse(readFileSync(path, 'utf8'))
+    const pm = await import('./postmortem.mjs')
+
+    // The version-level half (#961). The run-level pass profiles ONE manifest's record; this one
+    // aggregates every durable bundle the VERSION left behind, across all of its attempts — the
+    // shape a single-manifest pass cannot see (Forex v0.1.12: nine attempts, one repeated owner).
+    // Possible only when the manifest names both the version and the durable evidence dir; absent
+    // either, the run-level pass stands alone and nothing is invented. Returns null silently then,
+    // or { error } when the dir could not be read — a degraded report, never a failed handoff.
+    const versionLevel = async () => {
+      const version = pm.releaseVersion(manifest)
+      if (!isNonEmptyString(version) || !isNonEmptyString(manifest.durableEvidenceDir)) return null
+      const vpm = await import('./version-postmortem.mjs')
+      try {
+        return { profile: vpm.versionPostmortem({ dir: manifest.durableEvidenceDir, version, runSlug: manifest.runSlug }), vpm }
+      } catch (e) {
+        return { error: e?.message ?? String(e) }
+      }
+    }
+    // Print the attempt table + summary, and save into the shared series on the same terms as the
+    // run-level save. An aggregate that found NO bundles is reported but not persisted — an empty
+    // discovery is a statement about the dir, not a measurement of the version.
+    const versionReport = async ({ save }) => {
+      const vl = await versionLevel()
+      if (!vl) return
+      if (vl.error) {
+        console.error(`warn: version-level post-mortem could not be computed — ${vl.error}`)
+        return
+      }
+      const { profile: vp, vpm } = vl
+      if (!vp.attempts.length) {
+        console.log(`\nVERSION POST-MORTEM — no durable bundles found for ${vp.metrics.version} in ${manifest.durableEvidenceDir}`)
+        return
+      }
+      process.stdout.write(`\nVERSION POST-MORTEM — ${vp.metrics.version} across ${vp.metrics.attempts} attempt(s)\n`)
+      process.stdout.write(vpm.renderVersionPostmortem(vp))
+      if (save) {
+        const written = vpm.saveVersionPostmortem(vp)
+        if (written.saved) process.stdout.write(`  saved: ${written.paths.json}\n  series: ${written.paths.index}\n`)
+        else console.error(`warn: version-level post-mortem computed but NOT saved — ${written.error}`)
+      }
+    }
+
+    if (flags.has('--issue')) {
+      console.log(JSON.stringify(pm.renderReleasePostmortemIssue(manifest), null, 2))
+    } else if (flags.has('--postmortem')) {
+      process.stdout.write(pm.renderReleasePostmortem(manifest))
+      await versionReport({ save: !flags.has('--no-save') })
+      if (!flags.has('--no-save')) {
+        // NOT named `r`: that identifier is the release block everywhere else in this module,
+        // and report.test.mjs scans the source for `r.<field>` reads to catch invented
+        // release fields. Shadowing it would have made this code look like three of them.
+        const written = pm.saveReleasePostmortem(manifest)
+        if (written.saved) process.stdout.write(`\n  saved: ${written.paths.json}\n  series: ${written.paths.index}\n`)
+        else console.error(`warn: post-mortem computed but NOT saved — ${written.error}`)
+      }
+    } else {
+      console.log(renderCheckpoint(manifest))
+      // The automatic half. This script is run at EVERY step transition (SKILL.md § The
+      // release loop), so hanging the save on the terminal one makes the pass mandatory in
+      // practice rather than in prose — the same move as `progress` in the delivery lane.
+      if (pm.releaseIsTerminal(manifest) && !flags.has('--no-save')) {
+        const written = pm.saveReleasePostmortem(manifest)
+        if (written.saved) {
+          const n = pm.releaseProfile(manifest).findings.length
+          console.log(`\nPOST-MORTEM saved — ${written.paths.json}\n  ${n} finding(s). Read it: report.mjs ${path} --postmortem`)
+        } else {
+          console.error(`warn: release terminal but the post-mortem could not be saved — ${written.error}`)
+        }
+        await versionReport({ save: true })
+      }
+    }
+  }
+}

package/skills/engineering/resolve-release/scripts/reprobe-credentials.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Re-probe the credential that performs step-4b platform reads.
+//
+// Pre-flight item 0 already runs this probe before the release opens, but the credential can
+// expire *between* the 4a validation and the traffic shift (pi session 019faea6: gcloud reauth
+// expired after the rc tag was pushed, leaving forty minutes of failed Cloud Run reads). This
+// script is the same probe, available as a stand-alone command so step 4b and any resume at
+// `validate`/`expose` can re-run it without re-running the whole pre-flight set.
+//
+// Fail closed: exit 0 only when the credential is live. A BLOCKED or UNKNOWN result exits 1
+// with the same remedy detail as pre-flight item 0, so the operator sees the same fix path.
+import { classifyCredential, DEFAULT_CREDENTIAL_COMMAND, sh } from './preflight-probes.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+export function evaluateCredential(command = DEFAULT_CREDENTIAL_COMMAND, timeout = 60_000) {
+  const result = sh(command, timeout)
+  return classifyCredential(result)
+}
+
+function takeValue(argv, i, flagName, args, key) {
+  const val = argv[++i]
+  if (val === undefined || val.startsWith('-')) {
+    if (val !== undefined) i-- // push flag-like token back so it is parsed as a flag/unknown
+    args.missing.push(flagName)
+    return i
+  }
+  args[key] = val
+  return i
+}
+
+function takeNumber(argv, i, flagName, args, key) {
+  const val = argv[++i]
+  if (val === undefined || val.startsWith('-')) {
+    if (val !== undefined) i--
+    args.missing.push(flagName)
+    return i
+  }
+  const n = Number(val)
+  if (!Number.isFinite(n)) {
+    args.missing.push(flagName)
+    return i
+  }
+  args[key] = n
+  return i
+}
+
+function parseArgs(argv) {
+  const args = { timeoutSeconds: 60, unknown: [], missing: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--command') { args.commandProvided = true; i = takeValue(argv, i, '--command', args, 'command') }
+    else if (a === '--timeout') i = takeNumber(argv, i, '--timeout', args, 'timeoutSeconds')
+    else if (a === '--json') args.json = true
+    else if (a === '--help' || a === '-h') args.help = true
+    else if (a !== undefined) args.unknown.push(a)
+  }
+  return args
+}
+
+function help() {
+  return `reprobe-credentials — re-probe the credential that performs step-4b platform reads.
+
+Usage:
+  reprobe-credentials [--command <cmd>] [--timeout <seconds>] [--json]
+
+Options:
+  --command <cmd>   credential liveness probe (default: ${DEFAULT_CREDENTIAL_COMMAND})
+  --timeout <sec>   probe timeout in seconds (default: 60)
+  --json            machine-readable summary on stdout
+
+Exit codes:
+  0  credential is live
+  1  credential blocked/unknown/expired — apply the remedy printed, then re-run
+  2  usage error
+
+This is the same probe preflight-probes.mjs item 0 runs. Run it at the start of
+step 4b and on resume when step is validate or expose, before any pause or shift.`
+}
+
+export function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  if (args.unknown.length > 0) {
+    console.error(`reprobe-credentials: unknown argument(s): ${args.unknown.join(', ')}`)
+    return 2
+  }
+  if (args.missing.length > 0) {
+    console.error(`reprobe-credentials: missing or invalid value for: ${args.missing.join(', ')}`)
+    return 2
+  }
+  if (!Number.isFinite(args.timeoutSeconds) || args.timeoutSeconds <= 0) {
+    console.error('reprobe-credentials: --timeout must be a positive number')
+    return 2
+  }
+  const command = args.command || DEFAULT_CREDENTIAL_COMMAND
+  const probe = evaluateCredential(command, args.timeoutSeconds * 1000)
+
+  if (args.json) {
+    console.log(JSON.stringify(probe, null, 2))
+  } else {
+    console.log(`${probe.state.toUpperCase()} — ${probe.detail}`)
+    if (probe.remedy && probe.state !== 'ok') {
+      console.log(`remedy: ${probe.remedy}`)
+    }
+  }
+  return probe.state === 'ok' ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2))
+}