@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/preflight-probes.mjs

@@ -0,0 +1,498 @@
+#!/usr/bin/env node
+// Pre-flight readiness probes: the questions a release discovers the hard way if nobody asks
+// them first.
+//
+// Every one of these comes from pi session 019faea6, where each was found mid-flight instead of
+// before the attempt opened:
+//
+//   1. CREDENTIAL LIVENESS. `gcloud` reauthentication expired after the rc tag was pushed, so
+//      every Cloud Build and Cloud Run read failed for the next forty minutes. Pre-flight item 3
+//      already declares WHICH identity performs the exposure; nothing checked that the credential
+//      it names still works. A release whose credential dies mid-flight cannot verify what it
+//      deployed, which is principle 5 with no way to satisfy it.
+//
+//   2. TAG DIVERGENCE. `git fetch` refused `v0.3.1-rc.1` as a clobbering update — the local tag
+//      pointed at `43fc5398`, the remote at `06dd1b3d`. Tags are immutable by principle 10, so a
+//      divergence means one of the two is lying about what a version names, and version.mjs is
+//      about to read the local one.
+//
+//   3. TARGET-BRANCH GATE COLOUR. Post-deploy validation was already red on `main` for four
+//      consecutive SHAs before the release began. The release turned into a repair job — correct
+//      behaviour, but it should be a decision taken at pre-flight with the state named, not a
+//      surprise after the envelope was approved.
+//
+//   4. EXPOSURE-GATE CAPABILITY. The run reached a healthy candidate at 0% traffic and only then
+//      discovered the repo could not produce a deployed-profile verdict at all, so the attempt
+//      parked at `blocked-manual` having minted a tag and burned a build. The gate that cannot
+//      run is principle 13, and principle 13 is much cheaper to hit in the first thirty seconds.
+//
+// WHY A SCRIPT RATHER THAN SIX MORE SENTENCES OF PROSE. Each of these was already implied by an
+// existing rule; prose did not stop any of them, because "confirm the envelope" reads as a
+// conversation and these are commands. A probe that returns `blocked` with a remedy is not a
+// reminder to check — it is the check. This is the same reasoning as `run-state.mjs` mechanizing
+// the manifest rules instead of describing them.
+//
+// FAIL CLOSED, AND SAY WHICH KIND. `unknown` is not `ok`. A probe that could not run leaves the
+// question unanswered, and an unanswered readiness question is exactly principle 13's shape — so
+// `summarize` treats `unknown` as not-ready, and the CLI exits non-zero. What it does NOT do is
+// pretend to know the remedy: an `unknown` reports the raw failure so an operator can see whether
+// the probe or the world is broken.
+//
+// The exposure-gate probe (4) is a COMMAND THE CALLER SUPPLIES, not something inferred here.
+// Whether a repo can emit a deployed-profile verdict is a fact about that repo's smoke tooling,
+// and guessing at it from file paths is how a probe becomes confidently wrong. So the repo names
+// the command (`--exposure-gate-probe`), this script runs it, and an ABSENT command is `unknown`
+// rather than `ok` — a repo that never answers cannot silently release on the weaker path, the
+// same rule pre-flight item 3 applies to the identity legs.
+//
+// Issue #823: when the exposure executor is this skill (the smoke gate runs here, not in the
+// pipeline), a smoke secret that resolved to its resource-name string instead of its value will
+// fail at 4a with 401/403. That is a cannot-run, not a DEAD candidate — but it is still cheaper
+// to catch before the candidate is built. Probe declared smoke secrets with one dry fetch.
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+// Same blocking predicate as ensure-target-green — pending / empty-conclusion required
+// gates must never silent-green on either surface (#807 class pending-checks-not-green).
+import { isCheckBlocking } from './ensure-target-green.mjs'
+
+export const PROBE_STATES = { OK: 'ok', BLOCKED: 'blocked', UNKNOWN: 'unknown' }
+
+const probe = (id, state, detail, remedy = null) => ({ id, state, detail, remedy })
+
+// ---- 1. credential liveness -------------------------------------------------------------------
+//
+// The signal is specific and worth matching rather than treating any failure alike: gcloud's
+// expired-credential path prints "Reauthentication failed" / "cannot prompt during
+// non-interactive execution" and tells you to run `gcloud auth login`. That is BLOCKED with a
+// known remedy. A gcloud that is missing entirely, or fails some other way, is UNKNOWN — the
+// difference matters because the first is fixed by a human logging in and the second may mean the
+// probe is wrong about the platform.
+export function classifyCredential({ ok, stdout = '', stderr = '', missing = false } = {}) {
+  const text = `${stdout}\n${stderr}`
+  if (missing) {
+    return probe('credential-liveness', PROBE_STATES.UNKNOWN,
+      'the credential tool is not on PATH, so its liveness could not be read',
+      'install/configure the platform CLI, or declare a different exposure identity at pre-flight item 3')
+  }
+  if (ok) {
+    return probe('credential-liveness', PROBE_STATES.OK, 'the credential answered a token request')
+  }
+  if (/reauthentication failed|cannot prompt during non-interactive|auth login|invalid_grant|credentials.*expired/i.test(text)) {
+    return probe('credential-liveness', PROBE_STATES.BLOCKED,
+      `the credential requires interactive reauthentication: ${firstLine(text)}`,
+      'run `gcloud auth login` (or the platform equivalent) BEFORE opening the attempt — a credential that dies mid-release cannot verify what it deployed')
+  }
+  return probe('credential-liveness', PROBE_STATES.UNKNOWN,
+    `the credential check failed for a reason this probe does not recognise: ${firstLine(text)}`,
+    'read the error; an unrecognised failure is not evidence the credential is good')
+}
+
+// ---- 2. tag divergence ------------------------------------------------------------------------
+//
+// Compares local tag SHAs against the remote's. Only tags present on BOTH sides can diverge: a
+// local-only tag is an unpushed rc (ordinary mid-release state), and a remote-only tag is simply
+// not fetched yet. Neither is a lie about a version; a *differing* SHA is.
+export function classifyTagDivergence({ local = {}, remote = {}, readable = true } = {}) {
+  if (!readable) {
+    return probe('tag-divergence', PROBE_STATES.UNKNOWN,
+      'local or remote tags could not be listed',
+      'fix the git remote read; unlistable tags cannot be shown to agree')
+  }
+  const diverged = []
+  for (const [tag, sha] of Object.entries(local)) {
+    const remoteSha = remote[tag]
+    if (remoteSha && remoteSha !== sha) diverged.push({ tag, local: sha, remote: remoteSha })
+  }
+  if (diverged.length === 0) {
+    return probe('tag-divergence', PROBE_STATES.OK, `${Object.keys(local).length} local tag(s) agree with the remote`)
+  }
+  const named = diverged.map((d) => `${d.tag} (local ${d.local.slice(0, 8)} vs remote ${d.remote.slice(0, 8)})`).join('; ')
+  return probe('tag-divergence', PROBE_STATES.BLOCKED,
+    `tag(s) name different commits locally and remotely: ${named}`,
+    'tags are immutable (principle 10), so one side is wrong about what a version names — delete the local tag and re-fetch, and resolve it BEFORE version.mjs reads it')
+}
+
+// ---- 3. target-branch gate colour -------------------------------------------------------------
+//
+// A red target branch is not automatically a refusal — the release may legitimately be the thing
+// that repairs it, which is the repair lane. What it must not be is a discovery. So this reports
+// BLOCKED with the failing gates named, and the caller decides at pre-flight whether to repair
+// first or hand back. `--gate` narrows it to the gates that actually gate a release; with no
+// `--gate` every failing check-run counts, which is the conservative reading.
+export function classifyTargetGate({ checks, readable = true, gates = [] } = {}) {
+  if (!readable || !Array.isArray(checks)) {
+    return probe('target-gate-colour', PROBE_STATES.UNKNOWN,
+      'the target branch check-runs could not be read',
+      'fix the read; an unread gate is not a green gate')
+  }
+  const relevant = gates.length > 0 ? checks.filter((c) => gates.includes(c.name)) : checks
+  if (gates.length > 0) {
+    const missing = gates.filter((g) => !checks.some((c) => c.name === g))
+    if (missing.length > 0) {
+      // An ABSENT required gate reads as permanently unmet, which is a documented trap in this
+      // toolchain — never silently the same as passing.
+      return probe('target-gate-colour', PROBE_STATES.BLOCKED,
+        `required gate(s) reported no check-run on the target head: ${missing.join(', ')}`,
+        'an absent check is not a passing check — find out why it did not run before releasing off this head')
+    }
+  }
+  // Share isCheckBlocking with ensure-target-green so empty conclusion / IN_PROGRESS /
+  // non-COMPLETED status cannot silent-green here while that surface blocks (class:
+  // pending-checks-not-green). Pre-flight item 0 short-circuits before ensure-target-green
+  // when this probe reports ok — so this surface MUST use the same predicate.
+  const failing = relevant.filter((c) => isCheckBlocking(c))
+  if (failing.length === 0) {
+    return probe('target-gate-colour', PROBE_STATES.OK, `${relevant.length} check-run(s) on the target head are green or skipped`)
+  }
+  const label = (c) => {
+    const conclusion = String(c.conclusion || '').trim()
+    const status = String(c.status || '').trim()
+    if (conclusion) return `${c.name}=${conclusion}`
+    if (status) return `${c.name}=${status}`
+    return `${c.name}=PENDING`
+  }
+  return probe('target-gate-colour', PROBE_STATES.BLOCKED,
+    `the target branch head is red: ${failing.map(label).join(', ')}`,
+    'decide at pre-flight: run ensure-target-green (classify → repair/brief → re-probe) or hand back — do not discover it after the envelope is approved')
+}
+
+// ---- 4. tag-trigger topology -----------------------------------------------------------------
+//
+// The production build is owned by Cloud Build's tag trigger, not a controller-submitted
+// `gcloud builds submit`. The repository supplies a read-only command that evaluates its trigger
+// substitutions for one representative RC and prints the structured record below. This probe
+// verifies the specific path that failed in fmm-express: TAG_NAME → _DEPLOYED_VERSION (final
+// SemVer) and TAG_NAME → RC candidate tag. A source-SHA image can coexist, but cannot substitute
+// for this evidence.
+const RC_TAG_RE = /^v?(\d+\.\d+\.\d+)-rc\.[1-9]\d*$/
+
+export function classifyTagTopology({ topology = null, readable = true } = {}) {
+  if (!readable || topology == null || typeof topology !== 'object' || Array.isArray(topology)) {
+    return probe('rc-tag-topology', PROBE_STATES.UNKNOWN,
+      'the production build topology could not be read as a Cloud Build substitution record',
+      'run --topology-probe with the repository read that emits prodBuildTrigger, versionSource, candidateTagSource, and substitutions; an unread topology cannot authorize an RC tag')
+  }
+
+  const prodBuildTrigger = topology.prodBuildTrigger
+  const versionSource = topology.versionSource
+  const candidateTagSource = topology.candidateTagSource
+  const substitutions = topology.substitutions
+  const fields = { prodBuildTrigger, versionSource, candidateTagSource }
+  if (prodBuildTrigger !== 'tag-trigger' || versionSource !== 'TAG_NAME' || candidateTagSource !== 'TAG_NAME') {
+    return {
+      ...probe('rc-tag-topology', PROBE_STATES.BLOCKED,
+        'the production build topology is not tag-trigger / TAG_NAME / TAG_NAME',
+        'fix the trigger-owned Cloud Build derivation before minting an RC; controller-submitted substitutions and source-SHA images are not RC candidate evidence'),
+      ...fields,
+    }
+  }
+  if (substitutions == null || typeof substitutions !== 'object' || Array.isArray(substitutions)) {
+    return {
+      ...probe('rc-tag-topology', PROBE_STATES.BLOCKED,
+        'the topology record has no Cloud Build substitutions to prove the TAG_NAME derivation',
+        'emit TAG_NAME, _DEPLOYED_VERSION, and _CANDIDATE_TAG from the tag-trigger configuration before minting an RC'),
+      ...fields,
+    }
+  }
+
+  const tagName = String(substitutions.TAG_NAME || '')
+  const deployedVersion = String(substitutions._DEPLOYED_VERSION || '')
+  const candidateTag = String(substitutions._CANDIDATE_TAG || '')
+  const match = RC_TAG_RE.exec(tagName)
+  if (!match || deployedVersion !== match[1] || candidateTag !== tagName) {
+    return {
+      ...probe('rc-tag-topology', PROBE_STATES.BLOCKED,
+        `TAG_NAME does not derive the final _DEPLOYED_VERSION and RC candidate tag (TAG_NAME=${tagName || '(missing)'}, _DEPLOYED_VERSION=${deployedVersion || '(missing)'}, _CANDIDATE_TAG=${candidateTag || '(missing)'})`,
+        'make the tag-trigger build derive final SemVer and the RC candidate tag from TAG_NAME; a plain source-SHA image is informational, not candidate evidence'),
+      ...fields,
+    }
+  }
+  return {
+    ...probe('rc-tag-topology', PROBE_STATES.OK,
+      'Cloud Build tag trigger derives final SemVer and the RC candidate tag from TAG_NAME'),
+    ...fields,
+    substitutions: { TAG_NAME: tagName, _DEPLOYED_VERSION: deployedVersion, _CANDIDATE_TAG: candidateTag },
+  }
+}
+
+// ---- 5. exposure-gate capability --------------------------------------------------------------
+//
+// Asks the repo's own tooling whether the exposure profile can produce a verdict, by running the
+// command the repo names. Exit 0 is capable. A non-zero exit is BLOCKED — and the output is
+// quoted verbatim rather than interpreted, because the tool's own refusal id (`BLOCKED`,
+// `DEPLOYED_PROFILE_UNAUTHORIZED`, …) is the diagnosis and paraphrasing it loses the one string an
+// operator can search for.
+// ---- 5. smoke secrets (optional — only when exposure executor is this skill) ---------------
+//
+// Issue #823. When this skill runs the smoke gate (pre-flight item 3: exposure executor = skill),
+// the smoke manifest's `setup.env` names secrets/credentials the gate needs. A common failure
+// is an env var that contains the secret *resource name* (`projects/.../secrets/...`) instead
+// of the secret *value*, which produces 401/403 at drive time. A pre-flight dry fetch catches
+// that before a tag is minted and a candidate is built.
+//
+// The probe is intentionally platform-agnostic: by default it checks that each declared env
+// var is set and that its value does not look like a secret resource path. A repo that wants a
+// stronger check supplies `--smoke-secrets-command '<cmd> <name>'` and the probe substitutes
+// `<name>` with each env var name. If the command exits non-zero, the secret is BLOCKED.
+//
+// A missing manifest or absent env var is UNKNOWN, not ok: the question was not answered.
+const SECRET_RESOURCE_PATH_RE = /^projects\/[^/]+\/secrets\/[^/]+(\/versions\/[^/]+)?$/i
+
+export function classifySmokeSecrets({
+  manifestPath = null,
+  env = [],
+  values = {},
+  command = null,
+  // When the caller supplied a path but could not read/parse it, fail closed — never
+  // treat that as "no secrets to verify" (the empty-env OK path). Issue #823 review.
+  manifestError = null,
+} = {}) {
+  if (!manifestPath) {
+    return probe('smoke-secrets', PROBE_STATES.UNKNOWN,
+      'no smoke manifest was supplied, so declared smoke secrets were not dry-fetched',
+      'pass --smoke-manifest <path> when the exposure executor is this skill, so declared smoke secrets can be verified before the candidate is built')
+  }
+  if (manifestError) {
+    return probe('smoke-secrets', PROBE_STATES.UNKNOWN,
+      `smoke manifest at ${manifestPath} could not be read or parsed: ${manifestError}`,
+      'fix the --smoke-manifest path (file must exist and be valid JSON with setup.env) and re-run — an unreadable manifest is not "no secrets to verify"')
+  }
+  if (!Array.isArray(env) || env.length === 0) {
+    return probe('smoke-secrets', PROBE_STATES.OK, 'smoke manifest declares no env/secrets to verify')
+  }
+  const bad = []
+  for (const name of env) {
+    const value = values[name]
+    if (value === undefined || value === null || value === '') {
+      bad.push({ name, reason: 'not set' })
+      continue
+    }
+    if (typeof value === 'string' && SECRET_RESOURCE_PATH_RE.test(value.trim())) {
+      bad.push({ name, reason: 'value looks like a secret resource path, not the secret value' })
+    }
+  }
+  if (command) {
+    for (const name of env) {
+      const result = sh(command.replace(/<name>/g, name), 30_000)
+      if (!result.ok) {
+        bad.push({ name, reason: `dry-fetch command failed: ${firstLine(`${result.stdout}\n${result.stderr}`)}` })
+      }
+    }
+  }
+  if (bad.length === 0) {
+    return probe('smoke-secrets', PROBE_STATES.OK, `${env.length} declared smoke secret(s) look resolvable`)
+  }
+  const named = bad.map((b) => `${b.name} (${b.reason})`).join('; ')
+  return probe('smoke-secrets', PROBE_STATES.BLOCKED,
+    `declared smoke secret(s) are misconfigured or could not be dry-fetched: ${named}`,
+    'fix the smoke secret (the env var must hold the secret value, not its resource name) and re-run — a 401/403 at 4a is a CANNOT-RUN gate failure, not a DEAD candidate')
+}
+
+export function classifyExposureGate({ command = null, ok = false, stdout = '', stderr = '' } = {}) {
+  if (!command) {
+    return probe('exposure-gate-capability', PROBE_STATES.UNKNOWN,
+      'no exposure-gate probe command was supplied, so whether this repo can produce a deployed-profile verdict is unknown',
+      'pass --exposure-gate-probe "<command>" (the repo\'s own check that its exposure profile is authorized). Unknown is not ok: a repo that cannot produce the verdict parks at blocked-manual AFTER minting a tag and building a candidate')
+  }
+  if (ok) {
+    return probe('exposure-gate-capability', PROBE_STATES.OK, 'the repo reports its exposure profile can produce a verdict')
+  }
+  return probe('exposure-gate-capability', PROBE_STATES.BLOCKED,
+    `the repo cannot produce a verdict for its exposure profile: ${firstLine(`${stdout}\n${stderr}`)}`,
+    'this release can only end blocked-manual — close the capability gap first (the deployment verifier / authorized profile), or declare a different exposure executor at pre-flight item 3')
+}
+
+function firstLine(text) {
+  const line = String(text || '').split('\n').map((l) => l.trim()).find((l) => l.length > 0)
+  return line ? line.slice(0, 300) : '(no output)'
+}
+
+// `unknown` counts as not-ready, deliberately. The whole failure this script addresses is a
+// question nobody asked, and "we could not ask it" leaves the release in exactly that state.
+export function summarize(probes) {
+  const list = Array.isArray(probes) ? probes : []
+  const blocked = list.filter((p) => p.state === PROBE_STATES.BLOCKED)
+  const unknown = list.filter((p) => p.state === PROBE_STATES.UNKNOWN)
+  return {
+    ready: list.length > 0 && blocked.length === 0 && unknown.length === 0,
+    blocked: blocked.map((p) => p.id),
+    unknown: unknown.map((p) => p.id),
+    probes: list,
+  }
+}
+
+export function parseArgs(argv) {
+  const args = { gates: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--repo') args.repo = argv[++i]
+    else if (a === '--target-branch') args.targetBranch = argv[++i]
+    else if (a === '--credential-command') args.credentialCommand = argv[++i]
+    else if (a === '--exposure-gate-probe') args.exposureGateProbe = argv[++i]
+    else if (a === '--topology-probe') args.topologyProbe = argv[++i]
+    else if (a === '--smoke-manifest') args.smokeManifest = argv[++i]
+    else if (a === '--smoke-secrets-command') args.smokeSecretsCommand = argv[++i]
+    else if (a === '--gate') args.gates.push(argv[++i])
+    else if (a === '--json') args.json = true
+    else if (a === '--help' || a === '-h') args.help = true
+    else args.unknown = a
+  }
+  return args
+}
+
+export const DEFAULT_CREDENTIAL_COMMAND = 'gcloud auth print-access-token'
+
+// Exported so the `-d` can be asserted. The bug it prevents lives in the COMMAND, not the
+// parser, so no amount of parser testing catches its removal — see the comment at the call site.
+export const LOCAL_TAGS_COMMAND = 'git show-ref --tags -d'
+
+export function sh(command, timeout = 60_000) {
+  try {
+    const stdout = execFileSync('/bin/sh', ['-c', command], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout })
+    return { ok: true, stdout, stderr: '' }
+  } catch (error) {
+    return {
+      ok: false,
+      stdout: error.stdout?.toString?.() || '',
+      stderr: error.stderr?.toString?.() || error.message || '',
+      missing: /not found|ENOENT/i.test(error.message || ''),
+    }
+  }
+}
+
+function help() {
+  return `preflight-probes check --repo <owner/name> --target-branch <branch> [options]
+
+The readiness questions a release otherwise discovers mid-flight. Run BEFORE opening the
+attempt; the first four were found the hard way in pi session 019faea6, the topology probe catches
+tag-trigger drift before an RC is minted (#1025), and smoke-secrets catches misconfiguration before
+a candidate is built (#823).
+
+Options:
+  --credential-command <cmd>   liveness check, default: ${DEFAULT_CREDENTIAL_COMMAND}
+  --exposure-gate-probe <cmd>  the repo's own check that its exposure profile can produce a
+                               verdict. ABSENT is "unknown", which is NOT ready.
+  --topology-probe <cmd>       read-only repository command that prints JSON for one representative
+                               RC: prodBuildTrigger, versionSource, candidateTagSource, and
+                               substitutions.TAG_NAME/_DEPLOYED_VERSION/_CANDIDATE_TAG. ABSENT is
+                               "unknown", which is NOT ready.
+  --smoke-manifest <path>      smoke manifest to read declared env/secrets from. Use when the
+                               exposure executor is this skill.
+  --smoke-secrets-command <cmd> optional per-secret dry-fetch command; '<name>' is substituted
+                               with each env var name declared in the smoke manifest.
+  --gate <name>                a gate that must be present and green on the target head
+                               (repeatable). With none, every failing check-run counts.
+  --json                       machine-readable summary on stdout
+
+Exit codes:
+  0  ready — every probe ok
+  1  not ready — at least one blocked or unknown probe, each with a remedy
+  2  usage error
+
+"unknown" is never "ok": an unasked readiness question is the state this script exists to end.`
+}
+
+export async function runCli(argv) {
+  const args = parseArgs(argv)
+  if (args.help) { console.log(help()); return 0 }
+  const cmd = argv[0]
+  if (args.unknown && args.unknown !== cmd) { console.error(help()); return 2 }
+  if (cmd !== 'check') { console.error(help()); return 2 }
+  if (!args.repo || !args.targetBranch) { console.error(help()); return 2 }
+
+  const probes = []
+
+  const cred = sh(args.credentialCommand || DEFAULT_CREDENTIAL_COMMAND)
+  probes.push(classifyCredential(cred))
+
+  // `-d` (--dereference) is load-bearing, not tidiness: without it `show-ref --tags` prints only
+  // the TAG OBJECT sha for an annotated tag, while `ls-remote --tags` prints the tag object AND
+  // the `^{}` commit. Comparing one side's tag object against the other side's commit reports a
+  // divergence for every annotated tag in the repo — verified live against this skills repo, which
+  // returned six false positives (v0.1.0 "local 88493d4f vs remote a4afcc5d" is the same tag:
+  // 88493d4f is its tag object, a4afcc5d the commit). A probe that cries wolf on every release is
+  // a probe someone switches off, so both sides must dereference the same way.
+  const localTags = sh(`${LOCAL_TAGS_COMMAND} || true`)
+  const remoteTags = sh(`git ls-remote --tags ${shellQuote(`https://github.com/${args.repo}.git`)} || git ls-remote --tags origin`)
+  probes.push(classifyTagDivergence({
+    local: parseShowRef(localTags.stdout),
+    remote: parseLsRemote(remoteTags.stdout),
+    readable: localTags.ok && remoteTags.ok,
+  }))
+
+  // Fetch status alongside conclusion — IN_PROGRESS/QUEUED gates have conclusion:"" and
+  // must be classifiable by isCheckBlocking (same shape ensure-target-green fetchTip uses).
+  const checks = sh(`gh api repos/${args.repo}/commits/${shellQuote(args.targetBranch)}/check-runs --jq '[.check_runs[] | {name: .name, status: (.status // ""), conclusion: (.conclusion // "")}]'`)
+  probes.push(classifyTargetGate({
+    checks: checks.ok ? safeJson(checks.stdout) : null,
+    readable: checks.ok,
+    gates: args.gates,
+  }))
+
+  const topologyRead = args.topologyProbe ? sh(args.topologyProbe, 300_000) : {}
+  probes.push(classifyTagTopology({
+    topology: topologyRead.ok ? safeJson(topologyRead.stdout) : null,
+    readable: Boolean(args.topologyProbe) && topologyRead.ok,
+  }))
+
+  const exposure = args.exposureGateProbe ? sh(args.exposureGateProbe, 300_000) : {}
+  probes.push(classifyExposureGate({ command: args.exposureGateProbe || null, ...exposure }))
+
+  // Issue #823: optional smoke-secrets dry fetch when this skill runs the exposure gate.
+  // We read the manifest and the current process env values; the optional command lets a repo
+  // do a platform-specific real fetch if it wants one stronger than the resource-path heuristic.
+  if (args.smokeManifest) {
+    let manifest = null
+    let manifestError = null
+    try {
+      manifest = JSON.parse(fs.readFileSync(args.smokeManifest, 'utf8'))
+    } catch (err) {
+      // Prefer a short, actionable detail over a stack.
+      if (err && err.code === 'ENOENT') manifestError = 'file not found'
+      else if (err instanceof SyntaxError) manifestError = 'invalid JSON'
+      else manifestError = err && err.message ? err.message : String(err)
+    }
+    const env = !manifestError && manifest && Array.isArray(manifest.setup && manifest.setup.env)
+      ? manifest.setup.env
+      : []
+    probes.push(classifySmokeSecrets({
+      manifestPath: args.smokeManifest,
+      env,
+      values: Object.fromEntries(env.map((name) => [name, process.env[name]])),
+      command: args.smokeSecretsCommand || null,
+      manifestError,
+    }))
+  }
+
+  const summary = summarize(probes)
+  if (args.json) console.log(JSON.stringify(summary, null, 2))
+  else {
+    for (const p of summary.probes) {
+      console.log(`${p.state.toUpperCase().padEnd(7)} ${p.id} — ${p.detail}`)
+      if (p.remedy && p.state !== PROBE_STATES.OK) console.log(`        remedy: ${p.remedy}`)
+    }
+    console.log(summary.ready ? '\nREADY — every probe ok' : `\nNOT READY — blocked: [${summary.blocked}] unknown: [${summary.unknown}]`)
+  }
+  return summary.ready ? 0 : 1
+}
+
+const shellQuote = (s) => `'${String(s).replace(/'/g, "'\\''")}'`
+const safeJson = (t) => { try { return JSON.parse(t) } catch { return null } }
+
+export function parseShowRef(text) {
+  const out = {}
+  for (const line of String(text || '').split('\n')) {
+    const m = /^([0-9a-f]{40})\s+refs\/tags\/(.+?)(\^\{\})?$/.exec(line.trim())
+    // Annotated tags list twice: the tag object, then `^{}` for the commit it points at. The
+    // dereferenced line is the comparable one, so it wins where both appear.
+    if (m) { if (m[3] || !(m[2] in out)) out[m[2]] = m[1] }
+  }
+  return out
+}
+
+export const parseLsRemote = parseShowRef
+
+if (isMainModule(import.meta.url)) {
+  runCli(process.argv.slice(2)).then((code) => { process.exitCode = code })
+}