@codyswann/lisa 3.16.0 → 3.17.0

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/tool-floor.mjs

@@ -0,0 +1,94 @@
+/**
+ * Derive the CLIs a project's own configuration already implies.
+ *
+ * The symmetric half of `routing-floor.mjs`. A credential and the binary that
+ * consumes it are the same question asked twice — can this agent do the work —
+ * and both were answered only by a hand-maintained list.
+ *
+ * `detect-tooling` already knows most of these pairings and states them well:
+ * "the work-item guardrails shell out to `gh` for every tracker read". But it
+ * knows them at *proposal* time, as suggestions a human runs a skill to see and
+ * then copies into config. Nothing derives them at runtime, so a project that
+ * never ran the skill — or ran it before it adopted Maestro — has a manifest
+ * that silently understates what its agents need.
+ *
+ * This promotes those pairings to a derivation. The floor is unioned into the
+ * required set, never written into config, so it cannot drift from the routing
+ * that produces it.
+ *
+ * Deliberately narrow. An entry belongs here only when the configuration that
+ * implies it makes the tool unavoidable — not merely likely. A project can have
+ * `quality.testCoverage` thresholds and run them through any runner, so no CLI
+ * is derived from that; `secrets.provider: "bitwarden"` on the other hand
+ * cannot resolve one credential without `bws`.
+ * @module tool-floor
+ */
+
+/**
+ * Config predicates that make a CLI unavoidable, with the reason to report.
+ *
+ * The reason is not decoration. A missing tool has two valid remedies — install
+ * it, or change the configuration that demands it — and an operator cannot pick
+ * between them without knowing which line of config is responsible.
+ */
+const DERIVATIONS = [
+  {
+    tool: "gh",
+    applies: cfg => cfg.tracker === "github" || cfg.source === "github",
+    reason: cfg =>
+      `${cfg.tracker === "github" ? "tracker" : "source"} is "github", and ` +
+      `the work-item guardrails shell out to gh for every tracker read`,
+  },
+  {
+    tool: "bws",
+    applies: cfg => cfg.secrets?.provider === "bitwarden",
+    reason: () =>
+      `secrets.provider is "bitwarden", and the CLI is how every secret is ` +
+      `resolved`,
+  },
+  {
+    tool: "doppler",
+    applies: cfg => cfg.secrets?.provider === "doppler",
+    reason: () => `secrets.provider is "doppler"`,
+  },
+  {
+    tool: "maestro",
+    // Keyed on the coverage block rather than a `.maestro` directory: config is
+    // the declaration that this project gates on Maestro, where a stray
+    // directory could be a leftover. `detect-tooling` uses the directory
+    // because it is guessing; here the project has already said so.
+    applies: cfg => cfg.quality?.e2eCoverage?.maestro !== undefined,
+    reason: () =>
+      `quality.e2eCoverage.maestro is configured, and nothing installs the ` +
+      `maestro binary`,
+  },
+];
+
+/**
+ * The CLIs a project's configuration makes mandatory.
+ * @param {object} [config] Parsed `.lisa.config.json` root.
+ * @returns {Array<{name: string, reason: string}>} Sorted derived tools.
+ */
+export function toolFloor(config = {}) {
+  return DERIVATIONS.filter(entry => safely(() => entry.applies(config)))
+    .map(entry => ({ name: entry.tool, reason: entry.reason(config) }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/**
+ * Evaluate a predicate, treating a malformed config as "does not apply".
+ *
+ * A config shaped unexpectedly is a problem for the schema validator to report
+ * in its own vocabulary. Throwing here would make a readiness check the place a
+ * structural defect first surfaces, with a message about tools that names
+ * nothing an operator can act on.
+ * @param {Function} predicate Test to run.
+ * @returns {boolean} The result, or false when it threw.
+ */
+function safely(predicate) {
+  try {
+    return Boolean(predicate());
+  } catch {
+    return false;
+  }
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs

@@ -25,8 +25,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
-import { readRemoteEnvConfig } from "./setup-remote-env.mjs";
-import { extractVersion } from "./toolchain.mjs";
+import { probe, readRemoteEnvConfig } from "./setup-remote-env.mjs";
+import { planToolchain } from "./toolchain.mjs";
 
 /** Collected results, so every check runs before anything reports failure. */
 const results = [];
@@ -84,39 +84,21 @@ function node(args) {
 
 /**
  * Assert each declared tool is present at its pinned or minimum version.
+ *
+ * Delegates every decision to `planToolchain` rather than probing here. This
+ * function used to run its own loop, and the copy silently forgot `minVersion`:
+ * a `require` entry passed as long as the binary answered `--version` at all,
+ * so a container verified clean against a node older than the manifest
+ * demanded. The plan-side check rejected exactly what this one accepted.
+ *
+ * That is the same failure the note validators had before one shared module
+ * replaced them, and it recurs for the same reason — two implementations of one
+ * question cannot be kept in step by intention. There is now one.
  * @param {object} tools Toolchain manifest.
  */
 function verifyToolchain(tools) {
-  for (const tool of tools.require ?? []) {
-    try {
-      const out = execFileSync(tool.name, ["--version"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      check(true, `tool ${tool.name}`, extractVersion(out) ?? "present");
-    } catch {
-      check(false, `tool ${tool.name}`, "required but not present");
-    }
-  }
-  for (const tool of tools.install ?? []) {
-    try {
-      const out = execFileSync(tool.name, ["--version"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      const found = extractVersion(out);
-      check(
-        found === tool.version,
-        `tool ${tool.name}`,
-        `${found} (pin ${tool.version})`
-      );
-    } catch {
-      check(
-        false,
-        `tool ${tool.name}`,
-        `pinned ${tool.version} but not installed`
-      );
-    }
+  for (const step of planToolchain(tools, probe, "remote")) {
+    check(step.action === "present", `tool ${step.name}`, step.reason);
   }
 }
 

package/plugins/lisa/hooks/secrets-preflight.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Prove at session start that this agent can actually do the work: that the
+# credentials the project needs resolve, and that the CLIs it needs are on PATH.
+#
+# One hook for both because it is one question — can this agent do the work —
+# and an operator reading two separate reports has to assemble the answer
+# themselves. Both halves also share the same failure mode if split: two hooks
+# means two subprocess spawns on every session start, for a check that is silent
+# almost every time.
+#
+# Injects rather than blocks, and that is deliberate. The right response to a
+# missing credential or tool is for the agent to know before it claims work and
+# to route the item to blocked with a reason a human can act on — not for the
+# session to die. A session that cannot reach the vault can still write code,
+# review a PR, or answer a question; killing it would tax every session for a
+# minority need, and a control people route around enforces nothing.
+#
+# The hard gates live where they can afford to be hard: `lisa doctor` and CI
+# run the same two scripts and exit non-zero on them.
+#
+# Silent on success on purpose. A control that announces itself when everything
+# is fine trains its readers to skim past it, and then it is decoration.
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+if [ -n "$INPUT" ]; then
+  HOOK_EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "SessionStart"' 2>/dev/null || echo "SessionStart")
+else
+  HOOK_EVENT="SessionStart"
+fi
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+SECRETS="$ROOT/skills/lisa-secrets-access/scripts/preflight-secrets.mjs"
+TOOLS="$ROOT/skills/lisa-setup-remote-env/scripts/preflight-tools.mjs"
+
+command -v node >/dev/null 2>&1 || exit 0
+# The hook's whole output is one `jq -n` document. Without jq there is nothing
+# to write, so exiting is the only honest outcome — the alternative is a hook
+# that prints `jq: command not found` and exits 127, which reports a failure
+# from a check designed never to block. The doctor and CI gates run the same
+# two scripts without jq involved.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# stderr carries each report; stdout is reserved for the hook's JSON. A script
+# that is absent (partial or older install) or fails to run at all contributes
+# nothing, because a broken hook must not manufacture a finding.
+REPORT=""
+for script in "$SECRETS" "$TOOLS"; do
+  [ -f "$script" ] || continue
+  # An escape hatch that is honest about what it costs, and scoped to what it
+  # names. Set when a surface has no secrets provider by design and the noise is
+  # not worth it; the doctor and CI gates are unaffected, so opting out here
+  # does not opt out of the check entirely. It must not also silence the
+  # TOOLING half — a variable about secrets that hides a missing `gh` or
+  # `maestro` is an opt-out from a check nobody opted out of.
+  if [ "$script" = "$SECRETS" ] && [ "${LISA_SKIP_SECRETS_PREFLIGHT:-}" = "1" ]; then
+    continue
+  fi
+  OUT=$(node "$script" 2>&1 >/dev/null) || true
+  [ -n "$OUT" ] || continue
+  [ -n "$REPORT" ] && REPORT+=$'\n\n'
+  REPORT+="$OUT"
+done
+
+[ -n "$REPORT" ] || exit 0
+
+CONTEXT="## Readiness preflight
+
+$REPORT"
+
+jq -n --arg event "$HOOK_EVENT" --arg ctx "$CONTEXT" \
+  '{"hookSpecificOutput": {"hookEventName": $event, "additionalContext": $ctx}}'

package/plugins/lisa/skills/lisa-doctor/SKILL.md

@@ -422,14 +422,93 @@ The verdict ladder is:
 - `READY_WITH_WARNINGS` — no `FAIL`, but one or more `WARN`.
 - `NOT_READY` — one or more `FAIL`.
 
+## Gate configuration
+
+```sh
+node scripts/lisa-gates.mjs validate                    # shape + unknown gate ids
+node scripts/lisa-gates.mjs list --moment=pull-request
+node scripts/lisa-gates.mjs contexts                    # branch-protection contexts
+```
+
+A gate is a **property** — *credential leakage* — not a tool. `gitleaks` is one way to prove
+that property, and which way is the project's choice: each gate names a task in the project's own
+runner, so swapping the tool changes one line of project config and nothing in Lisa.
+
+`validate` refuses an unknown gate id rather than ignoring it. A misspelled `credential-leakge`
+would otherwise read as an enabled guarantee and run nothing at all — the same silent-hole shape
+as a skipped required check. Gates a project invents carry an `x-` prefix, which Lisa runs without
+pretending to understand.
+
+`contexts` is the value that replaces a hand-transcribed branch-protection list. It is scoped to
+one environment: a gate required before a production deploy is **not** thereby a merge blocker on a
+pull request, and collapsing the two would promote every deploy-time gate into branch protection.
+
+When reconciling a ruleset against it, pass `--previous=` with any label retired in the last
+release. Downstream repositories call the shared workflow unpinned, so a renamed job reaches every
+repository before any of them has reconciled — and a required context that never reports leaves
+pull requests waiting indefinitely. The fastest way out of that is deleting the requirement, which
+is how a rename ends up removing a guarantee. Emitting both labels for one release avoids it.
+
+### Reconciling against the live ruleset
+
+`contexts` says what the repository *should* require. Reconciliation asks whether GitHub agrees:
+
+```sh
+node scripts/lisa-reconcile-policy.mjs --dry-run              # read-only: what would change
+node scripts/lisa-reconcile-policy.mjs --on-drift=report      # report, write nothing
+node scripts/lisa-reconcile-policy.mjs --on-drift=block       # exit 1 on any drift, for CI
+node scripts/lisa-reconcile-policy.mjs                        # honors policy.on_drift
+node scripts/lisa-reconcile-policy.mjs --previous="🧽 Lint"   # keep a renamed context required
+node scripts/lisa-reconcile-policy.mjs --prune                # also remove EXTRA contexts
+```
+
+It reads the live ruleset and repository settings through `gh`, compares them against the derived
+contexts and the `policy` block, and reports three sets: **MISSING** (declared, not live), **EXTRA**
+(live, not declared), **MATCHED**. `--dry-run` never writes, whatever `policy.on_drift` says.
+
+Three behaviors need an operator to understand them before reading a report.
+
+**1. `UNPROVEN` is not a pass.** If `gh` is missing, unauthenticated, or the API errors — a private
+repository on a plan without rulesets answers `403` — the verdict is `UNPROVEN` and the exit code is
+`2`. It is neither of its neighbours, and the distinction is the same one the secrets preflight
+draws with `unreachable`: reported as clean it is a vacuous green, clean precisely because nothing
+was learned; reported as drift it sends someone to fix a ruleset that may be perfectly correct. The
+drift sets come back `null` rather than empty, because empty is what a clean repository looks like.
+`on_drift` does not soften this — not even `report` — because `on_drift` decides what to do about a
+drift that was *measured*, and here nothing was. Map it to doctor's `WARN`/`FAIL` on the same rule
+as any other unavailable check surface: never `PASS`.
+
+**2. An `EXTRA` context is reported, never removed.** Lisa does not own the whole required list.
+`SonarCloud Code Analysis`, `GitGuardian Security Checks`, and `CodeRabbit` are posted by external
+apps that no gates block declares, so `contextsFor` cannot derive them and every one of them is
+EXTRA by construction. Under `repair` the script therefore ADDS what is missing and leaves what is
+extra alone, naming each one. Removing them requires `--prune`, and the right way to clear the list
+is one at a time: each EXTRA context is either an app to keep, or a gate that belongs in
+`.lisa.config.json` — decide which before pruning anything.
+
+**3. Keep both names during a rename.** `--previous=<old label>` requires the old and the new
+context simultaneously for one release. Without it the reconciliation reports the still-live old
+context as EXTRA (and `--prune` would delete it) while in-flight pull requests wait on a context
+that will never report again.
+
+Repair writes exactly two things: required contexts on a ruleset, and repository settings. Policy
+carried by the *shape* of a rule — linear history, signed commits, force-push and deletion
+protection, conversation resolution — is compared here and repaired by
+`scripts/lisa-github-rulesets.sh`, which owns rule construction; the reconciler reports those and
+names that script rather than reshaping rules it did not build. When more than one ruleset requires
+status checks it refuses to guess which owns the derived contexts and asks for `--ruleset=<name>`,
+because writing to the wrong one enforces a context under a different ref-name condition.
+
 ## Secrets configuration
 
 Run the secrets health checks through the skill that owns the contract, rather than reimplementing
 any part of it here:
 
 ```sh
-node .claude/skills/lisa-secrets-access/scripts/validate-config.mjs   # shape
-node .claude/skills/lisa-secrets-access/scripts/doctor-secrets.mjs    # health
+node .claude/skills/lisa-secrets-access/scripts/validate-config.mjs      # shape
+node .claude/skills/lisa-secrets-access/scripts/preflight-secrets.mjs    # credential readiness
+node .claude/skills/lisa-setup-remote-env/scripts/preflight-tools.mjs    # tooling readiness
+node .claude/skills/lisa-secrets-access/scripts/doctor-secrets.mjs       # health
 ```
 
 Run the validator first. It checks only the *shape* of the `secrets`, `remoteEnv`, and
@@ -438,6 +517,33 @@ would otherwise surface somewhere unhelpful: a container failing mid-setup, a sc
 never fires, a dispatch naming a surface nobody provisioned. The health check then asks whether the
 credentials actually resolve.
 
+The preflight in the middle is the same check the SessionStart hook runs, and it is here for the
+half the hook deliberately cannot do. The hook injects its verdict into an agent's context and
+never blocks — killing a session over a credential it may not need would tax every session for a
+minority need, and a control people route around enforces nothing. Doctor is where the same
+verdict is allowed to be a non-zero exit.
+
+It reports three outcomes, and the third carries the weight. `ok` and `missing` are self-evident.
+**`unreachable`** means the provider itself could not be asked — no CLI, no bootstrap token, an API
+that errored — and it is neither of its neighbours. Reported as `ok` it would be a vacuous green,
+clean precisely because nothing was learned. Reported as `missing` it would blame the vault for a
+fault in this machine's access and send someone to grant a credential that was never absent. Both
+fail; they differ in what they tell the reader to fix.
+
+The tooling preflight asks the same question about CLIs, and it is a *caller* of
+`planToolchain` rather than a second implementation — that distinction is the point.
+`verify-remote-env.mjs` previously ran its own toolchain loop which never consulted
+`minVersion`, so a container verified clean against a `node` older than the manifest
+demanded while the plan-side check rejected exactly that. One function now answers the
+question everywhere.
+
+It needs only two verdicts. A local binary cannot fail to be asked the way a vault can,
+and the analogous trap — a tool present at an unparseable version — already fails closed
+upstream, because an unknown version loses every `minVersion` comparison. What it does add
+is a split credentials have no equivalent for: a missing tool with a pinned, checksummed
+`install` entry is something Lisa can place itself, so it reports an action and exits zero,
+while a tool nothing can provision blocks and exits non-zero.
+
 It reports without ever printing a value, and compares two copies of the same credential by digest.
 Map its findings into the doctor's own verdicts: `error` → `FAIL`, `warn` → `WARN`.
 

package/plugins/lisa/skills/lisa-secrets-access/scripts/preflight-secrets.mjs

@@ -0,0 +1,324 @@
+/**
+ * Prove, before an agent starts work, that the credentials it needs resolve.
+ *
+ * The contract has always claimed this. `secrets.require` is documented as an
+ * assertion — "a listed name that does not resolve is a startup error, not a
+ * late surprise" — and that sentence is the literal text of an error message in
+ * `doctor-secrets.mjs`. But nothing ran it at startup. The only caller of
+ * either presence check was a bash line inside `lisa-doctor`'s SKILL.md, which
+ * an agent had to read and choose to execute. The guarantee was prose; the
+ * plumbing to deliver it did not exist.
+ *
+ * This module is the missing caller, and it answers the question the gate
+ * actually asks. `AGENTS.md` requires intake to establish that the factory has
+ * the tooling "*and provable access to that tooling*" before accepting work. A
+ * credential that resolves nowhere is precisely a failure of provable access,
+ * and discovering it forty minutes into a build — after a ticket is claimed and
+ * a branch is cut — converts a clean refusal into abandoned half-work.
+ *
+ * **Three verdicts, and the third is the point.** `ok` and `missing` are
+ * obvious. `unreachable` is what happens when the provider itself cannot be
+ * asked: no CLI installed, no bootstrap token, an API that errored. That state
+ * must never collapse into either neighbour. Folded into `ok` it is a vacuous
+ * green — the check reports clean precisely when it learned nothing, which is
+ * the failure mode that lets a suppressed error read as a measured zero. Folded
+ * into `missing` it blames the vault for a fault in the caller's access, and
+ * sends whoever reads it to grant a credential that was never absent.
+ *
+ * Both non-ok verdicts fail. They are distinguished in the *message*, not the
+ * exit code, because the remediation differs completely: `missing` means extend
+ * the grant in the vault, `unreachable` means fix this machine's access to it.
+ * @module preflight-secrets
+ */
+
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { fetchAll } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+import { readMaterialized } from "./resolve-secret.mjs";
+import {
+  routingFloorReasons,
+  SUBSTITUTE_SUBSTRATES,
+} from "./routing-floor.mjs";
+
+/** Verdicts this check can reach, worst last. */
+export const VERDICTS = ["ok", "missing", "unreachable"];
+
+/**
+ * The names that must resolve on this surface, and why each is required.
+ *
+ * The floor is *unioned* with `require` rather than checked against it. A
+ * project should not have to restate `GH_TOKEN` to be protected by a rule its
+ * own `tracker: "github"` already implies, and a required set that depends on
+ * someone having typed it is exactly the hand-maintained list this replaces.
+ *
+ * `require` keeps its second job untouched. It still narrows resolution — a
+ * name outside it cannot be fetched — and the floor deliberately does not feed
+ * that. Unioning the floor into `cfg.require` would switch narrowing *on* for
+ * every project that never opted into it, and every credential they resolve
+ * today that is not in the floor would start throwing.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Array<{name: string, reasons: string[]}>} Required names, sorted.
+ */
+export function requiredNames(cfg) {
+  const reasons = routingFloorReasons(cfg.routing ?? {});
+  const declared = cfg.require ?? [];
+  const names = [...new Set([...(cfg.requiredFloor ?? []), ...declared])];
+  return names
+    .sort((left, right) => left.localeCompare(right))
+    .map(name => ({ name, reasons: whyRequired(name, reasons, declared) }));
+}
+
+/**
+ * Why one name is required, never empty.
+ *
+ * `report` renders this as "NAME — required because <reasons>", so an empty
+ * list prints a sentence that stops mid-clause and tells the operator nothing
+ * about which line of config to change. A name can reach the required set
+ * through the floor without a routing reason — anything that hands `preflight`
+ * a `requiredFloor` it did not derive from `routing` does exactly that — so the
+ * renderer needs a cause it can always print.
+ * @param {string} name The credential name.
+ * @param {Record<string, string[]>} reasons Routing-derived causes.
+ * @param {string[]} declared Names listed in `secrets.require`.
+ * @returns {string[]} At least one reason.
+ */
+function whyRequired(name, reasons, declared) {
+  const routingReasons = Object.hasOwn(reasons, name) ? reasons[name] : [];
+  const causes = [
+    ...(routingReasons ?? []),
+    ...(declared.includes(name) ? ["declared in secrets.require"] : []),
+  ];
+  return causes.length
+    ? causes
+    : ["it is in this project's resolved secrets floor"];
+}
+
+/**
+ * Check every required credential against the resolution ladder.
+ *
+ * Values are never returned, printed, or written anywhere by this function. It
+ * reports names and whether each resolved, which is all a readiness check needs
+ * and the only shape safe to surface into an agent's context.
+ * @param {object} [cfg] Resolved configuration.
+ * @param {Function} [fetch] Provider view factory, injected for tests.
+ * @param {Function} [materialized] Materialized view factory, for tests.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @param {Function} [probe] Substrate probe runner, injected for tests.
+ * @returns {{verdict: string, required: Array<{name: string, reasons: string[]}>, missing: Array<{name: string, reasons: string[]}>, reason: string|null}}
+ */
+export function preflight(
+  cfg = readConfig(),
+  fetch = fetchAll,
+  materialized = readMaterialized,
+  env = process.env,
+  probe = runProbe
+) {
+  const required = requiredNames(cfg);
+  if (!required.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  const file = safely(() => materialized(cfg)) ?? new Map();
+
+  // Env and the materialized file are consulted before the provider, and a
+  // required name satisfied by either needs no provider call at all. A session
+  // whose credentials are already exported is the common case on CI, and paying
+  // a network round-trip to confirm what is already in the environment would
+  // make the cheapest surface the slowest.
+  const unresolvedLocally = required.filter(
+    ({ name }) =>
+      !present(env[name]) && !file.get(name) && !substrateSatisfies(name, probe)
+  );
+  if (!unresolvedLocally.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  let provider;
+  try {
+    provider = fetch(cfg);
+  } catch (err) {
+    return {
+      verdict: "unreachable",
+      required,
+      missing: unresolvedLocally,
+      reason: err.message,
+    };
+  }
+
+  const missing = unresolvedLocally.filter(
+    ({ name }) => !present(provider.get(name)?.value)
+  );
+  return {
+    verdict: missing.length ? "missing" : "ok",
+    required,
+    missing,
+    reason: null,
+  };
+}
+
+/**
+ * Render a verdict for whoever has to act on it.
+ *
+ * Written for a non-technical operator standing at the gate, per `AGENTS.md`:
+ * everything crossing a gate outward must be readable by the person being asked
+ * to decide. So each line names the credential, why it is required, and which
+ * of the two remedies applies.
+ * @param {object} result A {@link preflight} result.
+ * @param {object} cfg Resolved configuration.
+ * @returns {string} Operator-readable report, empty when nothing needs saying.
+ */
+export function report(result, cfg) {
+  if (result.verdict === "ok") return "";
+
+  const lines = [];
+  if (result.verdict === "unreachable") {
+    lines.push(
+      `Secrets preflight could NOT be completed on surface "${cfg.surface}".`,
+      `The "${cfg.provider}" provider could not be reached, so nothing is`,
+      `known about any credential — this is not a report that they are fine.`,
+      ``,
+      `  reason: ${result.reason}`,
+      ``,
+      `Fix this machine's access to the provider (bootstrap token, CLI`,
+      `install, network), then start a new session. Do not treat the`,
+      `credentials below as verified:`
+    );
+  } else {
+    lines.push(
+      `Secrets preflight FAILED on surface "${cfg.surface}".`,
+      `These credentials are required and resolve nowhere — not in the`,
+      `environment, not materialized, not in the "${cfg.provider}" grant.`,
+      `Extend the grant in the vault (or correct the routing that requires`,
+      `them), then start a new session:`
+    );
+  }
+  lines.push(``);
+  for (const { name, reasons } of result.missing) {
+    lines.push(`  ${name} — required because ${reasons.join("; ")}`);
+  }
+  lines.push(
+    ``,
+    `Work needing one of these cannot be completed. Route the item to`,
+    `blocked with this reason rather than claiming it and stopping partway.`
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Whether an alternative substrate already provides this capability.
+ * @param {string} name Required credential name.
+ * @param {Function} probe Probe runner, injected for tests.
+ * @returns {boolean} True when the substrate answered successfully.
+ */
+function substrateSatisfies(name, probe) {
+  const substrate = SUBSTITUTE_SUBSTRATES[name];
+  return substrate ? probe(substrate) : false;
+}
+
+/**
+ * How long a substrate probe may take before it counts as no answer.
+ *
+ * `gh auth status` contacts GitHub, and this runs on the session-start path.
+ * Unbounded, a hung connection holds the session open for as long as the child
+ * lives — the `catch` cannot help, because it is only reached once the call
+ * returns. Five seconds is far beyond a healthy round trip and far below the
+ * point where a person concludes the agent is broken.
+ */
+const PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * Run a substrate probe, treating any failure as "did not satisfy".
+ *
+ * Output is discarded rather than captured. The probe's job is to answer a
+ * yes/no question with its exit status, and a command that can print a
+ * credential is one whose stdout should never enter this process.
+ *
+ * A timeout throws, which the catch maps to false — the fail-closed answer. The
+ * credential is then checked against the environment, the materialized file and
+ * the provider as if no substrate existed, so a slow network costs a stricter
+ * check rather than a wrong verdict.
+ *
+ * Exported so the bound itself can be proved against a real slow command. A
+ * timeout that only exists as an option object is a claim; one that has been
+ * watched cut a hanging child off is a control.
+ * @param {{command: string, args: string[]}} substrate Probe definition.
+ * @returns {boolean} True when the command exited zero.
+ */
+export function runProbe(substrate) {
+  try {
+    execFileSync(substrate.command, substrate.args, {
+      stdio: "ignore",
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a resolved value counts as present.
+ * @param {unknown} value Candidate value.
+ * @returns {boolean} True when it is a non-blank string.
+ */
+function present(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Run a thunk, treating any throw as "no view available".
+ *
+ * The materialized file is optional on every surface and absent on most, so a
+ * failure to read it is not a preflight failure — the provider is still
+ * authoritative. Only the provider's own unavailability is a verdict.
+ * @param {Function} thunk Work to attempt.
+ * @returns {*} The result, or undefined when it threw.
+ */
+function safely(thunk) {
+  try {
+    return thunk();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * CLI entry point. Prints the report and exits non-zero on any failure.
+ */
+function main() {
+  const cfg = readConfig();
+  const result = preflight(cfg);
+  const text = report(result, cfg);
+  if (text) console.error(text);
+  if (result.verdict !== "ok") process.exit(1);
+}
+
+/**
+ * Whether this module is the entry point node was asked to run.
+ *
+ * Both sides are realpath'd rather than compared as text: `import.meta.url` is
+ * the resolved path while `process.argv[1]` is whatever the caller typed, so a
+ * symlinked path — every git worktree, and every `/tmp` path on macOS — makes a
+ * raw comparison false. The module then loads, runs nothing, and exits 0, which
+ * is a readiness check reporting clean because it never ran. Same rule and same
+ * reasoning as `scripts/lib/invoked-as-script.mjs`, written out here because a
+ * plugin payload has no `./lib/` to import from.
+ * @param {string} moduleUrl This module's own `import.meta.url`.
+ * @param {string} [argv1] Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the CLI body should run.
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  main();
+}