@mmerterden/multi-agent-pipeline 13.2.0 → 13.4.0

package/pipeline/commands/multi-agent/ios-coding-standard/SKILL.md

@@ -5,17 +5,17 @@ argument-hint: "[module name or path]"
 allowed-tools: Skill, Bash, Read, Edit, Write, AskUserQuestion
 ---
 
-# multi-agent ios-coding-standard — Module audit → plan → dev handoff
+# multi-agent ios-coding-standard  -  Module audit → plan → dev handoff
 
-**Input**: $ARGUMENTS — optionally a module name or path. When absent, Phase 1 discovers and asks.
+**Input**: $ARGUMENTS  -  optionally a module name or path. When absent, Phase 1 discovers and asks.
 
 This routine is the **procedure**. The rules live in the `ios-coding-standard` skill, whose registry is
 `references/rules.yml` and whose teaching doc is `references/STANDARD.md`. Load that
 skill first; it is installed on every host and carried by the iOS stack plugin, so
-there is one registry rather than a copy per CLI. Never restate a rule here — cite its ID. A rule that is not in the
+there is one registry rather than a copy per CLI. Never restate a rule here  -  cite its ID. A rule that is not in the
 registry is not a rule; if the audit needs one, propose it as `status: proposed` and say so.
 
-Read-only + planning. This routine never edits source — the dev pipeline does.
+Read-only + planning. This routine never edits source  -  the dev pipeline does.
 
 **Goal.** A developer new to the repo can open any file in the module and understand it without a
 guided tour, and nothing sensitive leaks on the way. Rank every finding by "does fixing this
@@ -26,26 +26,26 @@ dev task) stay English.
 
 ---
 
-## Phase 1 — Discover and pick the module
+## Phase 1  -  Discover and pick the module
 
 1. Repo root via `git rev-parse --show-toplevel`.
-2. **Discover module roots** — any directory with a `Package.swift`, a `Sources/` subtree or an
+2. **Discover module roots**  -  any directory with a `Package.swift`, a `Sources/` subtree or an
    `.xcodeproj`. Sweep the container dirs that exist (`Domains/`, `Packages/`, `Modules/`,
    `Features/`, `Core/`, `Common/`, top-level module dirs) one level deep, then two if empty.
 3. Record per module: name · path · Swift files · lines · governance docs present · SPM targets.
-   Keep this **module registry** for the whole run — `MOD-*` greps every import against it.
+   Keep this **module registry** for the whole run  -  `MOD-*` greps every import against it.
    Classify each module's role, because the role decides which dependency edges are legal:
    **feature** · **core/common** · **seam** (cross-module contracts/bridges/navigation) ·
    **composition root** (legitimately knows every module).
 4. If `$ARGUMENTS` resolves to a module, skip the prompt. Otherwise `AskUserQuestion`
    (single-select, `outputLanguage`), documented modules first, each option showing file/line
    counts and `docs: yes/no`. If the list exceeds the question limit, group the smallest into an
-   "other" option and ask again — never truncate silently.
+   "other" option and ask again  -  never truncate silently.
 5. Scope = the whole module's sources across all its targets, unless the user narrows it.
 
-## Phase 2 — Resolve what applies to THIS module
+## Phase 2  -  Resolve what applies to THIS module
 
-### 2a. The registry is the standard — in-module prose docs are NOT consulted
+### 2a. The registry is the standard  -  in-module prose docs are NOT consulted
 
 The skill's `references/rules.yml` (+ a project `modules/<Module>.yml` overlay) is the single source of truth. **Do not read, cite, or
 derive rules from a module's own `*-CLAUDE.md`, `docs/` set or any other in-repo prose.** They are
@@ -64,7 +64,7 @@ the specs the generator reads, and the module registry from Phase 1.
    be `blocking`.
    *Why prohibitions need to be written down:* inference reads dominant patterns, and a rule
    obeyed everywhere has no counter-example to infer from. A ban at 100% compliance is invisible
-   to a scan — it survives only if the overlay states it.
+   to a scan  -  it survives only if the overlay states it.
 2. **Repo-level rules** (root `CLAUDE.md`, contributing docs) apply to every module.
 3. **The module's own dominant pattern is its de-facto convention.** Count variants per dimension;
    the minority instances are the finding. Internal consistency beats conformity to a sibling.
@@ -74,14 +74,14 @@ Findings from step 3 are tagged `inferred` and capped at **suggestion**. Only re
 overlay-backed rules may be `blocking`.
 
 **When the overlay is missing**, generate a draft from code evidence, print it for confirmation,
-and mark every slot it could not derive — a frozen UI target, a name lock, a carve-out and an
+and mark every slot it could not derive  -  a frozen UI target, a name lock, a carve-out and an
 operational constraint all look like ordinary code from the outside. Do not guess them; list them
 as Open Questions.
 
 ### 2c. Vocabulary
 
 Bind each slot to a real symbol by grepping the module, then the reference module. **An unbound
-slot disables its rules** — never invent a name, never import a sibling's.
+slot disables its rules**  -  never invent a name, never import a sibling's.
 
 `HandlerName` · `EventParam` · `CoordinatorType` · `ResultType` / `ErrorType` / `ErrorFactory` ·
 `DIResolver` / `DIConfigurator` · `RequestModelSuffix` / `ResponseModelSuffix` / `TransportSuffix` ·
@@ -94,14 +94,14 @@ slot disables its rules** — never invent a name, never import a sibling's.
 
 Print the resolved table before scanning so a wrong binding is caught early.
 
-### 2d. Sensitive-data inventory — required before any SEC rule runs
+### 2d. Sensitive-data inventory  -  required before any SEC rule runs
 
 The `SEC-*` rules are written against the **data classes** in `references/rules.yml →
 sensitive_data_classes`, never against one module's field names. Resolve the module's concrete
 instances of each class: grep entities, request/response models, storage calls and analytics
 events for the values the module actually handles, and map each to its class.
 
-Produce the inventory as a table — **class · concrete symbols · where it enters · required
+Produce the inventory as a table  -  **class · concrete symbols · where it enters · required
 lifetime (transient / survives-restart / survives-reinstall) · where it is actually stored ·
 where it is logged · where it leaves (network, analytics, pasteboard, another module)**.
 
@@ -117,13 +117,13 @@ whose required lifetime nobody can state, is an Open Question, not a silent pass
 
 This table is a deliverable in its own right, independent of whether any violation is found.
 
-## Phase 3 — Scan
+## Phase 3  -  Scan
 
 Apply the rules in `references/rules.yml` that survived Phase 2 binding, plus the module's own `validation`
 gate. Tag every finding: **rule ID · severity · source (`registry` / `doc` / `inferred`) ·
 onboarding impact (high/medium/low)**.
 
-### Coverage gate — on disk, not in memory
+### Coverage gate  -  on disk, not in memory
 
 Before scanning, write `.<module>-audit-coverage.tsv` to the scratch dir: one row per target
 (every screen under `ScreenRoot`, every shared component, every entity, every file in every
@@ -131,25 +131,25 @@ target) with columns `path · status · rules-applied`. Mark rows as you go.
 
 - Each target is **audited** or **explicitly skipped with a reason** (generated, fixture,
   vendored). No third state.
-- **The run is incomplete while any row is unmarked** — and the file, not a claim, is the proof.
+- **The run is incomplete while any row is unmarked**  -  and the file, not a claim, is the proof.
   Chunk the module if it is too large for one pass; the checklist survives a context reset.
 - No sampling. A partial audit reported as complete certifies the unscanned screens as clean.
 
 ### Grep hygiene
 
 Registry `mechanism` patterns are line-based and match doc comments. Filter
-`^[[:space:]]*//` — BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// …`
-through — then open each surviving hit and confirm it is real code. Report pre-filter and
+`^[[:space:]]*//`  -  BSD grep does not understand `\s`, so a `\s*//` filter silently lets `/// ...`
+through  -  then open each surviving hit and confirm it is real code. Report pre-filter and
 post-verification counts separately; a table padded with comment matches destroys trust.
 
 ### Judgement rules need evidence, not assertion
 
 For any rule marked `enforcement: judgement`, a finding must carry the measurement its `check`
-names — a reference count, a call-site count, a consumer count, a file list. **No count, no
+names  -  a reference count, a call-site count, a consumer count, a file list. **No count, no
 finding.** This is what keeps a subjective rule from becoming an opinion.
 
 Every judgement rule has a worked ✗/✓ pair in `EXAMPLES.md`, keyed by ID. Cite it in the finding's
-proposed fix rather than re-describing the shape — the developer applying the fix should be
+proposed fix rather than re-describing the shape  -  the developer applying the fix should be
 reading the same picture the audit used.
 
 ### Module-specific overrides
@@ -158,79 +158,79 @@ The module's own docs win over the registry, including where they contradict a s
 Never apply one module's dialect to another. List every override honoured, so the reader sees why
 a registry rule was not raised.
 
-## Phase 4 — Produce the plan
+## Phase 4  -  Produce the plan
 
 No findings → report compliant and stop. Otherwise write
 `<ModulePath>/ios-coding-standard-plan-<module>.md` (or the repo's scratch/docs dir if the module
 tree must stay clean), containing, in order:
 
-1. **Coverage ledger** — total targets · audited · skipped with reasons. Not 100% accounted for
+1. **Coverage ledger**  -  total targets · audited · skipped with reasons. Not 100% accounted for
    means the plan is not deliverable.
-2. **Summary** — counts by severity and source, resolved vocabulary, branch to create.
-3. **Sensitive-data inventory** (Phase 2d) — first, because it is the highest-risk content.
-4. **Screen × role matrix** `[STRUCT-02]` — screens as rows, manifest roles as columns, cells
+2. **Summary**  -  counts by severity and source, resolved vocabulary, branch to create.
+3. **Sensitive-data inventory** (Phase 2d)  -  first, because it is the highest-risk content.
+4. **Screen × role matrix** `[STRUCT-02]`  -  screens as rows, manifest roles as columns, cells
    `✓ / missing / misplaced`. The structural map a newcomer reads first.
-5. **Type placement table** `[STRUCT-05]` — type · location · consumer count · correct tier ·
+5. **Type placement table** `[STRUCT-05]`  -  type · location · consumer count · correct tier ·
    move required. Paired with the nested-type list `[STRUCT-01]`: owner · nested type · kind ·
    reference count · verdict.
-6. **Visibility report** `[VIS-01, VIS-02]` — over-exposed declarations per file, non-final
+6. **Visibility report** `[VIS-01, VIS-02]`  -  over-exposed declarations per file, non-final
    classes with no subclass.
-7. **Boundary report** `[MOD-*]` — import graph (allowed vs forbidden, with coupling depth) ·
+7. **Boundary report** `[MOD-*]`  -  import graph (allowed vs forbidden, with coupling depth) ·
    manifest graph (declared vs legal for the role, plus dead edges) · **removability delta**
-   ("removing X touches N files: …") · inbound test (tests compile with no sibling present).
-8. **Testability seam report** `[TEST-*]` — types reaching for the environment, logic requiring a
+   ("removing X touches N files: ...") · inbound test (tests compile with no sibling present).
+8. **Testability seam report** `[TEST-*]`  -  types reaching for the environment, logic requiring a
    view to execute, doubles whose signatures have drifted.
-9. **Change-cost probe** `[FLEX-*]` — pick two plausible upcoming changes (a new variant of an
+9. **Change-cost probe** `[FLEX-*]`  -  pick two plausible upcoming changes (a new variant of an
    existing screen; a new field on a shared entity) and state what each costs in files today.
-10. **Findings table** — rule ID · `file:line` · current state · proposed fix · severity · source ·
+10. **Findings table**  -  rule ID · `file:line` · current state · proposed fix · severity · source ·
     onboarding impact.
-11. **Per-file work** — grouped per file, blocking → important → suggestion; within a severity,
+11. **Per-file work**  -  grouped per file, blocking → important → suggestion; within a severity,
     highest onboarding impact first.
-12. **Behaviour-preservation guard** — splitting files, adding MARKs, extracting extensions and
+12. **Behaviour-preservation guard**  -  splitting files, adding MARKs, extracting extensions and
     moving types must not change behaviour. Anything requiring a behaviour change (a missing
     analytics event, a wrong result type, a timezone fix, a storage migration) goes in a
     **separate group**, reviewed and tested on its own, never inside a mechanical split commit.
-13. **Tooling delegation & the ratchet** — the section that decides whether any of this survives.
+13. **Tooling delegation & the ratchet**  -  the section that decides whether any of this survives.
     - Classify each applied rule by its registry `enforcement`. For every `lint` / `format` /
       `scan` rule, state the concrete mechanism and whether that toolchain exists in the repo
       (`LintToolchain`). **When it does not exist, saying so is a finding**, ranked above most
       individual violations it would have caught.
     - Recommend **baseline-and-ratchet, never big-bang**: grandfather existing violations, surface
-      only new ones, drain the backlog behind a green build. Order the plan the same way — stop
+      only new ones, drain the backlog behind a green build. Order the plan the same way  -  stop
       the bleeding, then clean up.
     - Custom lint rule identifiers **are** the registry IDs (`sec_01_no_plaintext_persistence`,
       `mod_01_no_sibling_import`) so a violation points straight at the rule entry.
-    - **Linting is local-only by decision** — the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
+    - **Linting is local-only by decision**  -  the skill's `references/lint-local.sh` with `references/swiftlint.draft.yml`, config
       and baseline kept outside the repository; no committed config, no build phase, no CI job.
       State this honestly in the plan rather than describing a gate that does not exist: a
       pre-PR habit catches less than a wall, so the residual risk is real and belongs in the
-      report. Adopting it project-wide remains an open decision — record it as one so it stays
+      report. Adopting it project-wide remains an open decision  -  record it as one so it stays
       visible instead of quietly lapsing.
     - Never imply the audit substitutes for the linter, or the linter for a gate. The audit finds
       the debt once; the linter keeps a developer honest; only a gate stops it returning.
-14. **Numeric exit criteria** — target and today's measured value side by side: lint violations
+14. **Numeric exit criteria**  -  target and today's measured value side by side: lint violations
     per 1k lines (<1) · public-surface ratio, public declarations ÷ externally consumed symbols
     (≈1) · forbidden cross-module imports (0) · removability delta · files over threshold and
     files >120 lines with no sectioning (0) · screens missing a manifest role (0) · escape-hatch
     count `[CONC-03]` (flat or falling) · exception-marker count (flat or falling) · dead code (0)
     · screens with logic and no mirrored tests (0) · unclassified sensitive symbols (0).
-15. **Exception ledger** — every `// standard:exception(<ID>)` in the module: rule · reason ·
+15. **Exception ledger**  -  every `// standard:exception(<ID>)` in the module: rule · reason ·
     expiry · expired yes/no.
-16. **Open Questions** — Phase 2b dimensions with no majority, and unclassifiable symbols.
-17. **Suggested commit slicing** — one commit per file-group / concern.
-18. **Scope guard** — only this module is touched; definition of done is the module's own
+16. **Open Questions**  -  Phase 2b dimensions with no majority, and unclassifiable symbols.
+17. **Suggested commit slicing**  -  one commit per file-group / concern.
+18. **Scope guard**  -  only this module is touched; definition of done is the module's own
     verification path.
 
 Then write a **separate one-page onboarding summary** beside the plan, aimed at a developer
 joining next week rather than at whoever does the remediation: the ten always/never lines
 specialised to this module, the screen file manifest, the placement ladder, the sensitive-data
-classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit —
+classes in play, and the verification command. Nobody learns a codebase from a 40-finding audit -
 this page is the actual deliverable, and the audit is how you earn the right to write it
-accurately. Derive it from `references/STANDARD.md § 0`, do not re-invent it.
+accurately. Derive it from `references/STANDARD.md section 0`, do not re-invent it.
 
 Show a concise version of the plan to the user too.
 
-## Phase 5 — Hand off
+## Phase 5  -  Hand off
 
 `AskUserQuestion` (single-select, `outputLanguage`):
 
@@ -245,10 +245,10 @@ verifies, and commits only when asked. This routine ends at the handoff.
 
 ## Notes
 
-- **Verification reality is per-module — establish it, do not assume it.** Some targets cannot be
+- **Verification reality is per-module  -  establish it, do not assume it.** Some targets cannot be
   compiled from the CLI (asset symbol generation, UIKit-dependent packages, a dependency failing
   earlier in the graph); there, verification is Xcode and a manifest dump validates the manifest
-  only. Never trust a piped build's exit code — a pipe reports the tail's status. Record the
+  only. Never trust a piped build's exit code  -  a pipe reports the tail's status. Record the
   module's actual verification command in the plan.
 - One module per run. Several modules means several runs and several plans, never one
   cross-module churn commit.

package/pipeline/commands/multi-agent/setup/SKILL.md

@@ -633,7 +633,8 @@ Entries are objects (not bare strings). The schema `recentProjects.items` is a `
 
 **7g. Skip / degrade rules**
 
-- Source failure (network, VPN, 401, rate-limit) skips that source silently; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- Source failure (network, VPN, 401, rate-limit) skips that source; the others still run. Failure is recorded in `serviceStatus.{service} = { ok: false, checkedAt: <now>, reason: <short> }` so Phase 0 can also read that cache.
+- **Report the skip, do not swallow it.** Setup is where the user is actively configuring things, so a source that could not be reached is exactly what they need to hear about, and the reason decides their next move: a 401 means refresh that token, no response at all on a corporate host means connect the VPN, and a missing `global.hosts.<service>` means the token has nowhere to point. Print one line per skipped source with its classification (see `refs/keychain.md` Rule 2) before moving on. A discovery pass that quietly returned three repos out of forty reads as "you only have three repos".
 - If all three sources yield zero hits, Step 5 is a no-op  -  the picker in Phase 0 falls back to manual path entry.
 - Discovery is **never destructive**: it never modifies git state, never writes outside `PREFS_FILE`.
 - Step 5 is idempotent. Re-running it refreshes `recentProjects` and `serviceStatus` but preserves user-curated entries unless explicitly deselected.

package/pipeline/lib/credential-inventory.sh

@@ -0,0 +1,351 @@
+#!/usr/bin/env bash
+# credential-inventory.sh  -  what the pipeline can reach right now, and what it cannot.
+#
+# WHY THIS EXISTS
+#
+# A run asked the user to paste a Crashlytics stack trace by hand while a Firebase
+# service-account JSON sat in the Keychain, mapped as `firebase`, fully valid. Nothing
+# was broken - the pipeline simply never asked itself "do I already hold a credential
+# that answers this?" before asking the user. From the user's side that is worse than a
+# failure: they had supplied the key precisely so this would not happen.
+#
+# One command, so there is no excuse for asking blind. Run it before any question that
+# requests data an external system holds, and let the answer shape the question:
+#
+#   - credential present  -> ask for the *pointer* (the issue URL), not the payload,
+#                            and say you will fetch it
+#   - credential missing  -> say which logical key is unmapped and offer the Save Flow
+#   - credential dead     -> say it is expired and offer to refresh it
+#
+# SAFETY
+#
+# Values are never printed, never stored in a variable that reaches stdout, and never
+# logged. Presence is probed through `credential-store.sh get` with stdout discarded, so
+# the secret goes to /dev/null and only the exit status is read.
+#
+# Usage:
+#   credential-inventory.sh              # human-readable table
+#   credential-inventory.sh --json       # machine-readable, for state files
+#   credential-inventory.sh --probe      # also verify each configured service answers
+#   credential-inventory.sh --key firebase   # single logical key, exit 0 present / 1 not
+#
+# PRESENT IS NOT THE SAME AS WORKING
+#
+# Without --probe this reports what is configured. With --probe each configured
+# credential makes one cheap authenticated request, and the verdict distinguishes the
+# three failures that need three different user actions:
+#
+#   reachable          the service answered and accepted the credential
+#   auth-rejected      401/403 - the credential is dead, the user must refresh it
+#   unreachable        no response at all - on a corporate host, almost always the VPN
+#   no-host-configured a token exists but its host was never recorded in preferences
+#   well-formed        structurally valid, liveness not checkable without more input
+#   not-probeable      no cheap probe exists for this credential type
+#
+# Only configured credentials are probed. An unmapped key is a capability the user chose
+# not to enable, not a problem to report.
+#
+# Exit codes: 0 = inventory produced (or the queried key is present), 1 = queried key
+# absent, 3 = usage error.
+
+set -uo pipefail
+
+PREFS="${MULTI_AGENT_PREFS:-$HOME/.claude/multi-agent-preferences.json}"
+
+STORE=""
+for c in "$HOME/.claude/lib/credential-store.sh" "$HOME/.copilot/lib/credential-store.sh" \
+         "$HOME/.codex/lib/credential-store.sh" "$(dirname "$0")/credential-store.sh"; do
+  [ -f "$c" ] && { STORE="$c"; break; }
+done
+
+MODE="table"
+QUERY=""
+PROBE=0
+TIMEOUT="${MULTI_AGENT_PROBE_TIMEOUT:-6}"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json)  MODE="json"; shift ;;
+    --probe) PROBE=1; shift ;;
+    --key)   QUERY="${2:-}"; shift 2 || shift ;;
+    -h|--help)
+      echo "usage: $0 [--json] [--probe] [--key <logical-key>]" >&2; exit 3 ;;
+    *) echo "ERR: unexpected arg $1" >&2; exit 3 ;;
+  esac
+done
+
+pref() {  # pref <dotted.path> -> value or empty
+  [ -f "$PREFS" ] || return 0
+  python3 - "$PREFS" "$1" <<'PYPREF' 2>/dev/null
+import json, sys
+try:
+    d = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+for k in sys.argv[2].split("."):
+    if not isinstance(d, dict):
+        sys.exit(0)
+    d = d.get(k)
+    if d is None:
+        sys.exit(0)
+print(d if not isinstance(d, (dict, list)) else "")
+PYPREF
+}
+
+# An authenticated request whose credential never appears in argv.
+#
+# `curl -H "Authorization: Bearer $TOK"` puts the secret in the process command line,
+# where any `ps` on the machine can read it. `--config -` takes both the header and the
+# URL from stdin instead, so the token exists only in the pipe. Same reason the Vercel
+# wrapper refuses a `--token=` argv.
+#
+# probe_http <url> <header-name> <header-value> -> prints the HTTP status
+probe_http() {
+  local url="$1" hname="$2" hval="$3" out
+  # No `|| echo 000` here: curl already writes `000` through write-out when it never
+  # got a response, and exits non-zero as well. Appending produced `000000`, which fell
+  # through classify_status into a bogus `unexpected-000000` verdict for what was simply
+  # a closed VPN.
+  out=$(printf 'url = "%s"\nheader = "%s: %s"\nsilent\noutput = "/dev/null"\nwrite-out = "%%{http_code}"\nmax-time = %s\n' \
+    "$url" "$hname" "$hval" "$TIMEOUT" | curl --config - 2>/dev/null)
+  printf '%s' "${out:-000}"
+}
+
+# probe_basic <url> <user> <pass> -> prints the HTTP status
+probe_basic() {
+  local url="$1" u="$2" p="$3" out
+  out=$(printf 'url = "%s"\nuser = "%s:%s"\nsilent\noutput = "/dev/null"\nwrite-out = "%%{http_code}"\nmax-time = %s\n' \
+    "$url" "$u" "$p" "$TIMEOUT" | curl --config - 2>/dev/null)
+  printf '%s' "${out:-000}"
+}
+
+# Map an HTTP status onto the vocabulary the pipeline reasons about. `000` is curl's
+# "never got a response" - DNS failure, refused connection, timeout - which on a
+# corporate host is almost always a closed VPN, and is a completely different user
+# action from a rejected credential.
+classify_status() {
+  case "$1" in
+    2??)      echo "reachable" ;;
+    401|403)  echo "auth-rejected" ;;
+    404)      echo "reachable" ;;   # endpoint answered; the probe path may just not exist
+    000|"")   echo "unreachable" ;;
+    5??)      echo "server-error" ;;
+    # Anything that is not a three-digit status means the probe itself misbehaved.
+    # Saying so beats inventing a service verdict from a malformed value.
+    *)        echo "probe-error" ;;
+  esac
+}
+
+# Reachability for one logical key. Never prints a credential; the value is piped
+# straight into curl's stdin config and discarded.
+#
+# Hosts always come from preferences - a self-hosted Jira / Bitbucket / Confluence /
+# Fortify / Graylog address is deployment-specific and must never be baked in. Only
+# genuinely global public APIs are named literally. Host keys live at
+# `global.hosts.<service>` per prefs.schema.json - an earlier version of this probe
+# guessed `global.<service>Host` and reported no-host-configured for every
+# self-hosted service the user had actually configured.
+probe_one() {
+  local key="$1" tok host status
+  tok=$(bash "$STORE" get "$key" 2>/dev/null) || { echo "no-credential"; return; }
+  [ -n "$tok" ] || { echo "no-credential"; return; }
+
+  case "$key" in
+    jira)
+      host=$(pref global.hosts.jira)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/rest/api/2/myself" "Authorization" "Bearer $tok") ;;
+    confluence)
+      host=$(pref global.hosts.confluence)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/rest/api/user/current" "Authorization" "Bearer $tok") ;;
+    bitbucket_token)
+      host=$(pref global.hosts.bitbucket)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      local bbuser bbkey
+      bbkey=$(pref global.keychainMapping.bitbucket_user)
+      bbuser=$([ -n "$bbkey" ] && bash "$STORE" get bitbucket_user 2>/dev/null || echo "")
+      if [ -n "$bbuser" ]; then
+        status=$(probe_basic "https://${host}/rest/api/1.0/repos?limit=1" "$bbuser" "$tok")
+      else
+        status=$(probe_http "https://${host}/rest/api/1.0/repos?limit=1" "Authorization" "Bearer $tok")
+      fi ;;
+    github)
+      status=$(probe_http "https://api.github.com/user" "Authorization" "Bearer $tok") ;;
+    figma)
+      status=$(probe_http "https://api.figma.com/v1/me" "X-Figma-Token" "$tok") ;;
+    figma_mcp)
+      # An OAuth token for the Figma MCP server, not a REST PAT. Sending it to
+      # api.figma.com returns 403 for a perfectly healthy token, which is worse than
+      # not probing: it would send the user to regenerate something that works.
+      # Liveness for this one belongs to figma-mcp-refresh.sh, which owns the grant.
+      printf '%s' "$tok" | grep -q . && echo "not-probeable" || echo "malformed"
+      return ;;
+    npm)
+      status=$(probe_http "https://registry.npmjs.org/-/whoami" "Authorization" "Bearer $tok") ;;
+    fortify)
+      host=$(pref global.hosts.fortify)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/v1/projects?limit=1" "Authorization" "Bearer $tok") ;;
+    graylog)
+      host=$(pref global.hosts.graylog)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/system" "Authorization" "Bearer $tok") ;;
+    jenkins)
+      host=$(pref global.hosts.jenkins)
+      [ -n "$host" ] || { echo "no-host-configured"; return; }
+      status=$(probe_http "https://${host}/api/json" "Authorization" "Bearer $tok") ;;
+    firebase)
+      # A service-account JSON, not a bearer token: an OAuth exchange would be needed
+      # to reach Crashlytics, and the fetcher does that per issue. Verifying the shape
+      # is honest about what is known - well-formed, not proven reachable.
+      if printf '%s' "$tok" | python3 -c 'import json,sys; d=json.load(sys.stdin); sys.exit(0 if d.get("project_id") and d.get("private_key") else 1)' 2>/dev/null; then
+        echo "well-formed"; return
+      fi
+      echo "malformed"; return ;;
+    appstore_connect_private_key)
+      printf '%s' "$tok" | grep -q "BEGIN PRIVATE KEY" && echo "well-formed" || echo "malformed"
+      return ;;
+    *)
+      echo "not-probeable"; return ;;
+  esac
+  classify_status "$status"
+}
+
+# What each logical key unlocks, in the pipeline's own terms. This is the column that
+# turns an inventory into an actionable question: "I hold `firebase`, so give me the
+# issue URL and I will pull the stack trace" is only sayable if the capability is
+# written down somewhere.
+capability_of() {
+  case "$1" in
+    jira)              echo "read the ticket, its comments and its linked issues; post the Phase 7 comment" ;;
+    bitbucket_token)   echo "read the repo, open and update pull requests" ;;
+    bitbucket_user)    echo "identify the PR author (paired with bitbucket_token)" ;;
+    github)            echo "read issues, open pull requests, read Actions runs" ;;
+    confluence)        echo "read linked pages and publish the analysis document" ;;
+    firebase)          echo "pull a Crashlytics issue: stack frames, affected versions, device spread (needs the issue URL)" ;;
+    fortify)           echo "pull a static-analysis finding and its remediation guidance" ;;
+    graylog)           echo "pull request logs by transaction or conversation id (advisory)" ;;
+    figma|figma_mcp)   echo "fetch design context, screenshots and Code Connect mappings" ;;
+    jenkins)           echo "read build results" ;;
+    npm)               echo "publish to the npm registry" ;;
+    appstore_connect_key_id|appstore_connect_issuer_id|appstore_connect_private_key)
+                       echo "validate an archive against App Store rules before submission" ;;
+    claude_oauth_token|claude_oauth_token_fallback)
+                       echo "run headless review and analysis passes" ;;
+    *)                 echo "(no capability recorded for this key)" ;;
+  esac
+}
+
+mapping_keys() {
+  [ -f "$PREFS" ] || return 0
+  python3 - "$PREFS" <<'PY' 2>/dev/null
+import json, sys
+try:
+    p = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+m = (p.get("global") or {}).get("keychainMapping") or {}
+for k, v in m.items():
+    print(f"{k}\t{'1' if v else '0'}")
+PY
+}
+
+# Presence probe. The value lands in /dev/null; only the exit status is observed.
+probe() {
+  [ -n "$STORE" ] || return 2
+  bash "$STORE" get "$1" >/dev/null 2>&1
+}
+
+if [ -n "$QUERY" ]; then
+  probe "$QUERY"
+  rc=$?
+  case "$rc" in
+    0)
+      if [ "$PROBE" = "1" ]; then
+        echo "$QUERY: present, $(probe_one "$QUERY")  -  can $(capability_of "$QUERY")"
+      else
+        echo "$QUERY: present  -  can $(capability_of "$QUERY")"
+      fi
+      exit 0 ;;
+    2) echo "$QUERY: no credential helper on this host" >&2; exit 1 ;;
+    *) echo "$QUERY: NOT AVAILABLE  -  onboard it via /multi-agent:setup before relying on it" >&2; exit 1 ;;
+  esac
+fi
+
+ROWS=""
+while IFS=$'\t' read -r key mapped; do
+  [ -z "$key" ] && continue
+  if [ "$mapped" != "1" ]; then
+    state="unmapped"
+    reach="not-probed"
+  elif probe "$key"; then
+    state="present"
+    # Only configured credentials are probed. A key the user never onboarded is not a
+    # problem to report - it is a capability they chose not to enable.
+    reach=$([ "$PROBE" = "1" ] && probe_one "$key" || echo "not-probed")
+  else
+    state="mapped-but-missing"
+    reach="not-probed"
+  fi
+  ROWS="${ROWS}${key}\t${state}\t${reach}\t$(capability_of "$key")\n"
+done < <(mapping_keys)
+
+if [ -z "$ROWS" ]; then
+  if [ "$MODE" = "json" ]; then
+    echo '{"status":"empty","reason":"no keychainMapping in preferences","credentials":[]}'
+  else
+    echo "no keychainMapping found in $PREFS  -  run /multi-agent:setup" >&2
+  fi
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  # The rows travel through a temp file, not a pipe. `python3 - <<EOF` takes its SCRIPT
+  # from stdin, so a piped payload never reaches sys.stdin: --json came back with empty
+  # arrays while the table mode looked correct. Caught by smoke-credential-awareness.
+  ROWS_FILE="$(mktemp)"
+  trap 'rm -f "$ROWS_FILE"' EXIT
+  printf '%b' "$ROWS" > "$ROWS_FILE"
+  python3 - "$ROWS_FILE" <<'PYJSON'
+import json, sys
+rows = []
+with open(sys.argv[1]) as fh:
+    for line in fh:
+        line = line.rstrip("\n")
+        if not line:
+            continue
+        parts = line.split("\t")
+        if len(parts) < 4:
+            continue
+        rows.append({
+            "logical": parts[0],
+            "state": parts[1],
+            "reachability": parts[2],
+            "capability": parts[3],
+        })
+
+# `usable` is presence only, so a caller that never probed still gets a meaningful
+# answer. `reachable` is the stronger claim and exists only after --probe.
+OK_REACH = {"reachable", "well-formed"}
+BLOCKED = {"auth-rejected", "malformed"}
+probed = [r for r in rows if r["reachability"] != "not-probed"]
+print(json.dumps({
+    "status": "ok",
+    "probed": bool(probed),
+    "usable": [r["logical"] for r in rows if r["state"] == "present"],
+    "needsAttention": [r["logical"] for r in rows if r["state"] != "present"],
+    # Separated on purpose: a dead token is the user's to refresh, an unreachable host
+    # is usually a closed VPN, and a missing host is a setup gap. Collapsing them into
+    # one "failed" bucket is what made the pipeline ask blind questions.
+    "reachable": [r["logical"] for r in probed if r["reachability"] in OK_REACH],
+    "authRejected": [r["logical"] for r in probed if r["reachability"] in BLOCKED],
+    "unreachable": [r["logical"] for r in probed if r["reachability"] == "unreachable"],
+    "noHostConfigured": [r["logical"] for r in probed if r["reachability"] == "no-host-configured"],
+    "credentials": rows,
+}, indent=2))
+PYJSON
+else
+  printf '%b' "$ROWS" | awk -F'\t' '
+    BEGIN { printf "%-28s %-20s %-20s %s\n", "LOGICAL KEY", "STATE", "REACHABILITY", "UNLOCKS" }
+    { printf "%-28s %-20s %-20s %s\n", $1, $2, $3, $4 }'
+fi