@mmerterden/multi-agent-pipeline 16.25.1 → 16.27.0

package/pipeline/lib/credential-inventory.sh

@@ -148,6 +148,82 @@ classify_status() {
   esac
 }
 
+# Which Crashlytics tier can actually serve a request right now.
+#
+# Tier 1 (service account) is measured by the fetcher's own --probe, so the JWT
+# exchange has exactly one implementation; a copy here would be the one that
+# drifts. Tier 2 (interactive Firebase CLI session + the Firebase MCP server) is
+# measured here, because it is a property of the host, not of the credential.
+#
+# Tier 1 is preferred even when tier 2 is available: url-enrichment and the
+# autopilot flows run with nobody at the keyboard, and a browser login is not an
+# option there.
+firebase_tier() {
+  local t1="" fetcher=""
+  # Rule out before measuring. A stored value that is not service-account JSON
+  # cannot be fixed by any grant or any session, and saying so here means the
+  # verdict survives an install where the fetcher is absent - otherwise a broken
+  # credential and a missing fetcher both read as unreachable, which sends the
+  # user to debug a network over a re-onboarding.
+  #
+  # This is not the shape check that was removed. That one graded shape and
+  # concluded the credential WORKED; this one grades shape and concludes only
+  # that it CANNOT, which is the half shape can actually answer.
+  if ! bash "$STORE" get firebase 2>/dev/null | 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 "malformed"; return
+  fi
+  for c in "$(dirname "${BASH_SOURCE[0]:-$0}")/fetch-crashlytics.sh" \
+           "$HOME/.claude/lib/fetch-crashlytics.sh"; do
+    [ -f "$c" ] && { fetcher="$c"; break; }
+  done
+  if [ -n "$fetcher" ]; then
+    t1=$(bash "$fetcher" --probe 2>/dev/null \
+         | python3 -c 'import json,sys; print((json.load(sys.stdin) or {}).get("tier",""))' 2>/dev/null || true)
+  fi
+  case "$t1" in
+    tier-1-ready) echo "tier-1-ready"; return ;;
+    malformed)    echo "malformed";    return ;;
+  esac
+
+  # Tier 2 needs both halves: a logged-in CLI session AND a registered MCP
+  # server. Either alone reaches nothing, and reporting ready on half of it
+  # would repeat the mistake this function exists to end.
+  local logged_in=0 mcp=0
+  if command -v firebase >/dev/null 2>&1 \
+     && firebase login:list 2>/dev/null | grep -qi "logged in as"; then
+    logged_in=1
+  fi
+  if python3 - "$HOME" <<'MCPCHK' 2>/dev/null
+import json, os, sys
+home = sys.argv[1]
+def named(d):
+    return any("firebase" in k.lower() for k in (d or {}))
+for f in (os.path.join(home, ".claude.json"), os.path.join(home, ".claude", "settings.json")):
+    try:
+        d = json.load(open(f))
+    except Exception:
+        continue
+    if named(d.get("mcpServers")):
+        sys.exit(0)
+    for pv in (d.get("projects") or {}).values():
+        if named((pv or {}).get("mcpServers")):
+            sys.exit(0)
+sys.exit(1)
+MCPCHK
+  then
+    mcp=1
+  fi
+  if [ "$logged_in" -eq 1 ] && [ "$mcp" -eq 1 ]; then
+    echo "tier-2-ready"; return
+  fi
+
+  case "$t1" in
+    tier-1-no-grant) echo "tier-1-no-grant" ;;
+    *)               echo "unreachable" ;;
+  esac
+}
+
 # Reachability for one logical key. Never prints a credential; the value is piped
 # straight into curl's stdin config and discarded.
 #
@@ -207,8 +283,14 @@ probe_one() {
         status=$(probe_http "https://${host}/ssc/api/v1/projects?limit=1" \
           "Authorization" "FortifyToken $(printf '%s' "$tok" | base64 | tr -d '\n')")
       fi ;;
-    graylog)
-      host=$(pref global.hosts.graylog)
+    graylog|graylog_test)
+      # The test instance is a separate deployment with its own host key; probing it
+      # against the prod host would report a healthy token as broken.
+      if [ "$key" = "graylog_test" ]; then
+        host=$(pref global.hosts.graylogTest)
+      else
+        host=$(pref global.hosts.graylog)
+      fi
       [ -n "$host" ] || { echo "no-host-configured"; return; }
       # Graylog PATs authenticate as basic auth with the literal password "token", and
       # the API rejects requests without X-Requested-By. Both per fetch-graylog.sh.
@@ -219,16 +301,19 @@ probe_one() {
       [ -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 ;;
+      # Crashlytics has three ways in and they fail differently, so a single
+      # yes/no was never an answer. This used to check the JSON's shape and call
+      # it "well-formed", on which capability_of() declared it would pull stack
+      # frames - a promise the credential could not keep: the account was sound
+      # and simply had no Crashlytics role, which shape can never reveal.
+      #
+      # Verdicts, best usable tier first:
+      #   tier-1-ready     the SA can read Crashlytics headlessly
+      #   tier-2-ready     tier 1 is a role away, but an interactive session works
+      #   tier-1-no-grant  the SA is sound, no role, and no interactive fallback
+      #   malformed        the stored value is not service-account JSON
+      #   unreachable      nothing answers
+      echo "$(firebase_tier)"; return ;;
     *)
       echo "not-probeable"; return ;;
   esac
@@ -240,22 +325,51 @@ probe_one() {
 # issue URL and I will pull the stack trace" is only sayable if the capability is
 # written down somewhere.
 capability_of() {
+  # $2 is the reachability verdict when the caller has one. Only Firebase reads
+  # it today, and it has to: the same stored credential buys a headless fetch, an
+  # interactive lookup, or nothing at all, depending on a role the JSON cannot
+  # show. Announcing the best of those unconditionally is what made the inventory
+  # promise stack frames from an account that could not read them.
+  if [ "$1" = "firebase" ]; then
+    case "${2:-}" in
+      tier-1-ready)
+        echo "pull a Crashlytics issue headlessly: stack frames, affected versions, device spread (needs the issue URL)"; return ;;
+      tier-2-ready)
+        echo "pull a Crashlytics issue through the signed-in Firebase MCP session; headless runs still need firebasecrashlytics.viewer on the service account"; return ;;
+      tier-1-no-grant)
+        echo "nothing yet - the service account authenticates but holds no Crashlytics role; ask an Owner for roles/firebasecrashlytics.viewer"; return ;;
+      malformed)
+        echo "nothing - the stored value is not service-account JSON; re-onboard the key issued by Firebase Console"; return ;;
+      unreachable)
+        echo "nothing reachable - neither the service account nor an interactive Firebase session answers"; return ;;
+    esac
+  fi
   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)" ;;
+    firebase)          echo "pull a Crashlytics issue: stack frames, affected versions, device spread (needs the issue URL and a readable tier)" ;;
     fortify)           echo "pull a static-analysis finding and its remediation guidance" ;;
     graylog)           echo "pull request logs by transaction or conversation id (advisory)" ;;
+    graylog_test)      echo "pull the same logs from the test environment (falls back to the graylog token when unset)" ;;
+    usage_ingest)      echo "report pipeline usage counters and send /multi-agent:feedback" ;;
     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" ;;
+    appstore_connect_key_id|appstore_connect_issuer_id)
+                       echo "validate an archive against App Store rules before submission (the .p8 itself is a file at ~/.appstoreconnect/private_keys/, never a mapping)" ;;
+    appstore_connect_apple_id|appstore_connect_password_item)
+                       echo "upload a build with an app-specific password (Tier 2 of the App Store Connect chain)" ;;
     claude_oauth_token|claude_oauth_token_fallback)
                        echo "run headless review and analysis passes" ;;
+    supabase_access)   echo "administer the personal-site Supabase project (Management API); no pipeline phase reads it" ;;
+    supabase_service_role)
+                       echo "read and write the personal-site database server-side; no pipeline phase reads it" ;;
+    bitbucket)         echo "legacy alias for bitbucket_token; migrate-prefs.mjs folds it into that key" ;;
+    figma_pat|figma_user|firebase_project|firebase_sa)
+                       echo "deprecated mapping kept only so an un-migrated preferences file validates; migrate-prefs.mjs removes it" ;;
     *)                 echo "(no capability recorded for this key)" ;;
   esac
 }
@@ -286,7 +400,8 @@ if [ -n "$QUERY" ]; then
   case "$rc" in
     0)
       if [ "$PROBE" = "1" ]; then
-        echo "$QUERY: present, $(probe_one "$QUERY")  -  can $(capability_of "$QUERY")"
+        _reach=$(probe_one "$QUERY")
+        echo "$QUERY: present, $_reach  -  can $(capability_of "$QUERY" "$_reach")"
       else
         echo "$QUERY: present  -  can $(capability_of "$QUERY")"
       fi
@@ -323,7 +438,7 @@ while IFS=$'\t' read -r key mapped; do
     state="mapped-but-missing"
     reach="not-probed"
   fi
-  ROWS="${ROWS}${key}\t${state}\t${reach}\t$(capability_of "$key")\n"
+  ROWS="${ROWS}${key}\t${state}\t${reach}\t$(capability_of "$key" "$reach")\n"
 done < <(mapping_keys)
 
 if [ -z "$ROWS" ]; then
@@ -362,8 +477,16 @@ with open(sys.argv[1]) as fh:
 
 # `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"}
+# A tier that can serve a request is reachable, whichever tier it is. "well-formed"
+# used to sit in this set and was the reason a shape check could report a
+# credential as reachable without anything having been reached.
+OK_REACH = {"reachable", "tier-1-ready", "tier-2-ready"}
 BLOCKED = {"auth-rejected", "malformed"}
+# Neither reachable nor broken: the credential is sound and one grant short. It
+# gets its own bucket for the reason the others do - the user action is specific
+# (ask an Owner for a role), and folding it into any existing bucket sends them
+# to refresh a token that is fine or debug a VPN that is up.
+NEEDS_GRANT = {"tier-1-no-grant"}
 probed = [r for r in rows if r["reachability"] != "not-probed"]
 print(json.dumps({
     "status": "ok",
@@ -377,6 +500,7 @@ print(json.dumps({
     "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"],
+    "needsGrant": [r["logical"] for r in probed if r["reachability"] in NEEDS_GRANT],
     "credentials": rows,
 }, indent=2))
 PYJSON

package/pipeline/lib/fetch-crashlytics.sh

@@ -10,6 +10,7 @@
 #   ./fetch-crashlytics.sh <issue-url>
 #   ./fetch-crashlytics.sh --project <id> --platform <ios|android> \
 #                          --bundle <id> --issue-id <id> [--session-id <id>]
+#   ./fetch-crashlytics.sh --probe [--project <id>]
 #
 # Optional env:
 #   FIREBASE_TIMEOUT_SECONDS    default 20
@@ -48,6 +49,17 @@
 #   4  bad usage
 #   5  project mismatch  -  SA JSON project_id != URL project (configuration bug)
 #
+# --probe answers one question - can this service account read Crashlytics right
+# now - and answers it on stdout as {"tier":...,"reason":...} with exit 0 on every
+# outcome, because "no" is an answer, not a failure. It lives here rather than in
+# credential-inventory.sh so the JWT exchange has exactly one implementation; a
+# second copy would be the one that drifts. Verdicts:
+#
+#   tier-1-ready     the SA holds firebasecrashlytics.issues.get
+#   tier-1-no-grant  the SA authenticates but lacks that permission - a role away
+#   malformed        the stored value is not service-account JSON
+#   unreachable      no credential, no helper, or the exchange never answered
+#
 # Notes:
 #   Two v1alpha calls back this, because there is no get-issue-by-id endpoint:
 #   `reports/topIssues` for the summary and metrics, and `events?filter.issue.id`
@@ -65,8 +77,16 @@ PLATFORM=""
 BUNDLE=""
 ISSUE_ID=""
 SESSION_ID=""
+PROBE=0
 TIMEOUT="${FIREBASE_TIMEOUT_SECONDS:-20}"
 
+# Probe verdicts go to stdout and exit 0 - the caller reads the tier, it does not
+# read an exit status. Outside probe mode this is never called.
+probe_out() {
+  printf '{"tier":"%s","reason":"%s","projectId":"%s"}\n' "$1" "$2" "${3:-}"
+  exit 0
+}
+
 need_value() { [ $# -ge 2 ] || { echo "ERR: $1 needs a value" >&2; exit 4; }; }
 
 while [ $# -gt 0 ]; do
@@ -76,8 +96,9 @@ while [ $# -gt 0 ]; do
     --bundle)     need_value "$@"; BUNDLE="$2";     shift 2 ;;
     --issue-id)   need_value "$@"; ISSUE_ID="$2";   shift 2 ;;
     --session-id) need_value "$@"; SESSION_ID="$2"; shift 2 ;;
+    --probe)      PROBE=1; shift ;;
     -h|--help)
-      echo "usage: $0 <issue-url> | $0 --project ... --platform ... --bundle ... --issue-id ... [--session-id ...]" >&2
+      echo "usage: $0 <issue-url> | $0 --project ... --platform ... --bundle ... --issue-id ... [--session-id ...] | $0 --probe [--project <id>]" >&2
       exit 4 ;;
     *)
       if [ -z "$URL" ]; then URL="$1"; shift; else
@@ -118,7 +139,8 @@ PY
   SESSION_ID=$(printf '%s' "$PARSED" | cut -f5)
 fi
 
-if [ -z "$PROJECT_ID" ] || [ -z "$PLATFORM" ] || [ -z "$BUNDLE" ] || [ -z "$ISSUE_ID" ]; then
+if [ "$PROBE" -eq 0 ] \
+   && { [ -z "$PROJECT_ID" ] || [ -z "$PLATFORM" ] || [ -z "$BUNDLE" ] || [ -z "$ISSUE_ID" ]; }; then
   echo "ERR: missing required components  -  need project, platform, bundle, issue-id" >&2
   exit 4
 fi
@@ -179,38 +201,29 @@ for _cred_resolver in \
 done
 unset _cred_resolver
 if [ -z "${CRED_STORE:-}" ]; then
+  [ "$PROBE" -eq 1 ] && probe_out unreachable no-credential-helper "$PROJECT_ID"
   printf '%s\n' '{"status":"blocked","reason":"missing-credential-helper","service":"firebase","expected_key":"'"$TOKEN_KEY"'"}' >&2
   exit 2
 fi
 
-SA_JSON_B64=$("$CRED_STORE" get "$TOKEN_KEY" 2>/dev/null || true)
-if [ -z "$SA_JSON_B64" ]; then
+SA_JSON_RAW=$("$CRED_STORE" get "$TOKEN_KEY" 2>/dev/null || true)
+if [ -z "$SA_JSON_RAW" ]; then
+  [ "$PROBE" -eq 1 ] && probe_out unreachable no-credential "$PROJECT_ID"
   printf '%s\n' '{"status":"blocked","reason":"missing-token","service":"firebase","expected_key":"'"$TOKEN_KEY"'"}' >&2
   exit 2
 fi
 
-# The credential store may return raw JSON or base64-encoded JSON (the user's
-# setup convention). Try base64-decode first, fall back to raw. The decoded
-# payload contains a GCP private key, so it goes into a 0600 mktemp file with
-# cleanup traps registered BEFORE the secret is written.
-SA_TMP=""
-cleanup_sa_tmp() {
-  if [ -n "$SA_TMP" ]; then rm -f "$SA_TMP"; fi
-}
-trap cleanup_sa_tmp EXIT
-trap 'cleanup_sa_tmp; exit 130' INT
-trap 'cleanup_sa_tmp; exit 143' TERM
-SA_TMP=$(umask 077; mktemp "${TMPDIR:-/tmp}/fc-sa.XXXXXX")
-
-SA_JSON=""
-if printf '%s' "$SA_JSON_B64" | base64 -d > "$SA_TMP" 2>/dev/null \
-   && python3 -c "import json, sys; json.load(open(sys.argv[1]))" "$SA_TMP" 2>/dev/null; then
-  SA_JSON=$(cat "$SA_TMP")
-else
-  SA_JSON="$SA_JSON_B64"
-fi
-rm -f "$SA_TMP"
-SA_TMP=""
+# The credential store returns the JSON as stored - encoding is its internal
+# business, not this script's. The base64 attempt that used to live here was
+# guesswork that never fired: what actually broke the fetcher was the store
+# returning bare hex for any multi-line value, which is neither base64-of-JSON
+# nor JSON, so both branches failed and the failure surfaced three layers later
+# as a token-exchange error.
+#
+# With no decode step there is nothing to stage on disk, so the temp file and its
+# cleanup traps went with it: the service-account JSON now only ever exists in a
+# shell variable, which is one fewer place a GCP private key can be left behind.
+SA_JSON="$SA_JSON_RAW"
 
 # Verify project_id from SA JSON matches the URL  -  protects against pasting a
 # crash URL from another GCP project than the keychain's SA covers.
@@ -222,6 +235,17 @@ try:
 except Exception:
     print('')
 ")
+if [ "$PROBE" -eq 1 ]; then
+  # A stored value that is not service-account JSON has no project_id, and no
+  # amount of network access makes it usable. Say malformed here rather than
+  # letting the exchange fail and reporting it as unreachable - the two need
+  # different fixes, and conflating them is what sent the last diagnosis three
+  # layers away from the defect.
+  if [ -z "$SA_PROJECT" ]; then
+    probe_out malformed not-service-account-json "$PROJECT_ID"
+  fi
+  [ -z "$PROJECT_ID" ] && PROJECT_ID="$SA_PROJECT"
+fi
 if [ -n "$SA_PROJECT" ] && [ "$SA_PROJECT" != "$PROJECT_ID" ]; then
   # Still a hard error, but say which key was used and how to map the right one:
   # with several Firebase projects in play, "project mismatch" alone does not
@@ -308,10 +332,50 @@ PY
 ) || TOKEN_RC=$?
 
 if [ "$TOKEN_RC" -ne 0 ] || [ -z "$ACCESS_TOKEN" ]; then
+  [ "$PROBE" -eq 1 ] && probe_out unreachable token-exchange-failed "$PROJECT_ID"
   echo "ERR: Firebase token exchange failed (exchange rc=$TOKEN_RC)" >&2
   exit 3
 fi
 
+if [ "$PROBE" -eq 1 ]; then
+  # Ask IAM what this service account may do rather than calling Crashlytics and
+  # reading the error: a 403 from topIssues means "no permission", but so does a
+  # 403 from a disabled API or a project holding no crash data, and those need
+  # different fixes. testIamPermissions answers only the question asked, and
+  # answers it without touching crash data.
+  PERM_VERDICT=$(PROBE_TOKEN="$ACCESS_TOKEN" PROBE_PROJECT="$PROJECT_ID" python3 - <<'IAM'
+import json, os, sys, urllib.error, urllib.request
+
+WANT = "firebasecrashlytics.issues.get"
+body = json.dumps({"permissions": [WANT, "firebasecrashlytics.issues.list"]}).encode()
+req = urllib.request.Request(
+    "https://cloudresourcemanager.googleapis.com/v1/projects/%s:testIamPermissions"
+    % os.environ["PROBE_PROJECT"],
+    data=body,
+    headers={"Authorization": "Bearer %s" % os.environ["PROBE_TOKEN"],
+             "Content-Type": "application/json"},
+)
+try:
+    with urllib.request.urlopen(req, timeout=int(os.environ.get("FIREBASE_TIMEOUT_SECONDS", "20"))) as r:
+        held = json.loads(r.read().decode()).get("permissions") or []
+except urllib.error.HTTPError as e:
+    # The token was minted, so the account is real; a refusal here is still a
+    # grant question, not a reachability one.
+    print("tier-1-no-grant" if e.code in (401, 403) else "unreachable")
+    sys.exit(0)
+except Exception:
+    print("unreachable")
+    sys.exit(0)
+print("tier-1-ready" if WANT in held else "tier-1-no-grant")
+IAM
+) || PERM_VERDICT="unreachable"
+  case "$PERM_VERDICT" in
+    tier-1-ready)    probe_out tier-1-ready crashlytics-readable "$PROJECT_ID" ;;
+    tier-1-no-grant) probe_out tier-1-no-grant missing-crashlytics-role "$PROJECT_ID" ;;
+    *)               probe_out unreachable iam-check-failed "$PROJECT_ID" ;;
+  esac
+fi
+
 # Bearer auth via a curl config fed through process substitution so the token
 # never appears in argv (argv is visible to ps).
 crashlytics_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$ACCESS_TOKEN"; }
@@ -322,9 +386,39 @@ fb_get() {
 }
 
 # The appId is opaque (1:1234567890:ios:abcdef) and cannot be derived from the
-# bundle id. Ask the Firebase Management API which app owns this bundle; the
-# console URL only ever carries the bundle.
+# bundle id, so it has to come from somewhere. Preferences first: the repo's own
+# GoogleService-Info*.plist / google-services.json already name the pair, and
+# firebase-app-discovery.sh writes them into
+# prefs.global.firebase.accounts[].apps[] at setup. A hit there costs nothing; a
+# miss falls through to the Management API exactly as before, so an install that
+# never ran discovery behaves identically.
+APP_ID=""
+if [ -f "$PREFS" ]; then
+  APP_ID=$(WANT_PROJECT="$PROJECT_ID" WANT_BUNDLE="$BUNDLE" WANT_PLATFORM="$PLATFORM" \
+    python3 -c "
+import json, os
+try:
+    g = json.load(open('$PREFS')).get('global', {})
+except Exception:
+    g = {}
+want_p = os.environ.get('WANT_PROJECT') or ''
+want_b = os.environ.get('WANT_BUNDLE') or ''
+want_pl = os.environ.get('WANT_PLATFORM') or ''
+for a in (g.get('firebase', {}) or {}).get('accounts') or []:
+    if not isinstance(a, dict) or str(a.get('projectId') or '') != want_p:
+        continue
+    for app in a.get('apps') or []:
+        if not isinstance(app, dict):
+            continue
+        if str(app.get('bundleId') or '') == want_b and str(app.get('platform') or '') == want_pl:
+            print(app.get('appId') or '')
+            raise SystemExit(0)
+print('')
+" 2>/dev/null || printf '')
+fi
+
 FB_MGMT="https://firebase.googleapis.com/v1beta1/projects/$PROJECT_ID"
+if [ -z "$APP_ID" ]; then
 if [ "$PLATFORM" = "ios" ]; then
   APPS_JSON=$(fb_get "$FB_MGMT/iosApps?pageSize=200")
   MATCH_FIELD="bundleId"
@@ -350,6 +444,7 @@ else:
     # rather than guessing at the wrong app.
     print(apps[0].get('appId') or '' if len(apps) == 1 else '')
 " 2>/dev/null || true)
+fi
 
 if [ -z "$APP_ID" ]; then
   printf '{"status":"failed","reason":"app-not-found","platform":"%s","bundle":"%s","projectId":"%s"}\n' \

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -46,7 +46,7 @@ The catalogue is the single source of truth for downstream phases  -  they read
 URL pattern (caught by the extractor): `console.firebase.google.com/(u/[0-9]+/)?project/<projectId>/crashlytics/app/(ios|android)(:|%3A)<bundleOrPackage>/issues/<issueId>(/sessions/<sessionId>)?`
 
 - Host is fixed (`console.firebase.google.com`); no `hosts.firebase` pref needed.
-- Token resolution, in order: env `FIREBASE_TOKEN_KEY`; the `prefs.global.firebase.accounts[]` entry whose `projectId` equals the URL's project; `prefs.global.keychainMapping.firebase` (single-project setups). Then `~/.claude/lib/credential-store.sh get "<key>" | base64 -d` → Service Account JSON. `project_id` read from the decoded JSON  -  verify it matches the `<projectId>` from the URL; mismatch → the fetcher exits `5` naming the key it used and the `accounts[]` entry to add, and enrichment is skipped. Several Firebase projects per team is the normal case (legacy plus redesign, staging plus prod), which is what `accounts[]` exists for.
+- Token resolution, in order: env `FIREBASE_TOKEN_KEY`; the `prefs.global.firebase.accounts[]` entry whose `projectId` equals the URL's project; `prefs.global.keychainMapping.firebase` (single-project setups). Then `~/.claude/lib/credential-store.sh get "<key>"` → Service Account JSON. `project_id` read from that JSON  -  verify it matches the `<projectId>` from the URL; mismatch → the fetcher exits `5` naming the key it used and the `accounts[]` entry to add, and enrichment is skipped. Several Firebase projects per team is the normal case (legacy plus redesign, staging plus prod), which is what `accounts[]` exists for.
 - Exchange the SA JSON for a short-lived GCP access token (scope `https://www.googleapis.com/auth/firebase https://www.googleapis.com/auth/cloud-platform`) using `google-auth` (Python) or an inline JWT exchange (OpenSSL sign → `https://oauth2.googleapis.com/token`). Cache in-memory for the pipeline run only  -  never persist.
 - Resolve the opaque `appId` first: `GET https://firebase.googleapis.com/v1beta1/projects/<projectId>/(iosApps|androidApps)?pageSize=200` and match `bundleId` (iOS) / `packageName` (Android) against the bundle from the URL. The console URL only carries the bundle, and the Crashlytics API only accepts the appId (`1:1234567890:ios:abcdef`). No match in a multi-app project → exit `3`, reason `app-not-found`; never guess at another app.
 - Fetch crash detail with two calls  -  v1alpha has no get-issue-by-id endpoint: `GET .../v1alpha/projects/<projectId>/apps/<appId>/reports/topIssues?pageSize=200` for the summary and metrics (filter to the issue id), and `GET .../apps/<appId>/events?filter.issue.id=<issueId>&pageSize=1` for the newest event, which carries the stack frames, device, OS and breadcrumbs.

package/pipeline/multi-agent-refs/keychain.md

@@ -64,6 +64,24 @@ The answer then decides the shape of the question:
 | `mapped-but-missing` | say the credential is configured but not resolving, name the logical key, and offer the Save Flow: "`firebase` is mapped but the Keychain item is not resolving - refresh it, or paste the trace and I continue without it." |
 | `unmapped` | say the capability is not configured and offer setup: "No `firebase` key is mapped, so I cannot reach Crashlytics. Onboard it via `/multi-agent:setup`, or paste the trace." |
 
+**`present` is not the same as usable, and Firebase is where that bites.** A
+service-account JSON that resolves perfectly still reads nothing until an Owner
+grants it a Crashlytics role, so the mapping-state column above is too coarse for
+this one credential: run `--probe` and let the tier decide the question.
+
+| Probe says | Ask this |
+|---|---|
+| `tier-1-ready` | ask nothing about access - ask for the issue URL and fetch |
+| `tier-2-ready` | fetch through the signed-in session, and say once that headless runs (autopilot, url-enrichment) still need the role |
+| `tier-1-no-grant` | offer both, in this order: **the durable fix** - one line to an Owner asking for `roles/firebasecrashlytics.viewer` on that service account, which also fixes headless runs; **the fast fix** - `firebase login` plus the MCP server, about two minutes, this machine only, expires |
+| `malformed` | the stored value is not service-account JSON; offer the Save Flow, do not blame Crashlytics |
+| `unreachable` | now the trace is worth asking for - and say it is the third option, and why the other two are unavailable |
+
+Offering the paste before that measurement is the same defect in a new place: the
+user is asked to do by hand what a credential they configured was supposed to do,
+and this time the credential really was one grant away. Setup mechanics for both
+tiers: `refs/setup/firebase.md`.
+
 **Never** present "paste it yourself" as the first and most efficient option when a
 credential is present. That is the defect this rule exists for: a run asked the user to
 paste a Crashlytics stack trace, offering the manual path as "the fastest and most
@@ -87,9 +105,18 @@ fixes them in different ways:
 | `auth-rejected` | 401/403: the credential is dead | name the logical key, run the Expired-token decision (Rule 1) |
 | `unreachable` | no response at all | on a corporate host this is almost always the VPN: "`{FORTIFY_HOST}` is not answering - connect the VPN and I will retry, or I continue without the finding" |
 | `no-host-configured` | a token exists but `global.hosts.<service>` was never recorded | "I hold the `jira` token but no Jira host is configured, so I cannot build a request URL - set it via `/multi-agent:setup`" |
-| `well-formed` | structurally valid, liveness not checkable yet | say what is still needed (the Crashlytics issue URL) |
+| `tier-1-ready` | the Firebase service account can read Crashlytics headlessly | nothing - proceed, autopilot and url-enrichment work too |
+| `tier-2-ready` | tier 1 is a role away, but a signed-in Firebase MCP session answers | proceed interactively; say that headless runs still need the role |
+| `tier-1-no-grant` | the service account authenticates and holds no Crashlytics role | one line to an Owner: `roles/firebasecrashlytics.viewer` on that service account |
+| `malformed` | the stored value is not the credential type this key expects | re-onboard the key; do not blame the service |
 | `not-probeable` | no cheap probe exists for this credential type | do not claim it works, do not claim it fails |
 
+`well-formed` used to sit in this table for Firebase, and it was the wrong kind of
+answer: it graded the JSON's shape, which is the one thing that was never in doubt.
+The account was sound and simply held no Crashlytics role - invisible to any shape
+check, and the reason the inventory promised stack frames it could not deliver.
+Shape is not access; measure the access.
+
 Never collapse these into one "failed" bucket. A dead token, a closed VPN and a missing
 host look identical in a `{status: "failed"}` field and lead the user to three different
 wrong actions.
@@ -117,25 +144,25 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 
 **Standard key names (convention for new tokens):**
 
-| Service ID         | Context            | Standard Key Name                  | Type              |
-| ------------------ | ------------------ | ---------------------------------- | ----------------- |
-| `jira`             | Jira issue fetch   | `${USER}_Jira_Access_Token`        | PAT               |
-| `bitbucket_token`  | Bitbucket PR/push  | `${USER}_Bitbucket_Access_Token`   | App Password      |
-| `bitbucket_user`   | Bitbucket username | `${USER}_Bitbucket_Username`       | Plain text        |
-| `github`           | GitHub issue/PR    | `${USER}_Github_Access_Token`      | PAT (+ `gh auth`) |
-| `confluence`       | Confluence docs    | `${USER}_Confluence_Access_Token`  | PAT               |
-| `figma`            | Figma              | `${USER}_Figma_Access_Token`       | PAT               |
-| `figma_mcp`        | Figma MCP          | `${USER}_Figma_Mcp_Access_Token`   | OAuth             |
-| `fortify`          | Fortify            | `${USER}_Fortify_Access_Token`     | API Token         |
-| `graylog`          | Graylog (prod)     | `${USER}_Graylog_Access_Token`     | API Token         |
-| `graylog_test`     | Graylog (test)     | `${USER}_Graylog_Test_Access_Token` | API Token, optional  -  unset falls back to `graylog` |
-| `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | JSON (base64). One key per Firebase project; extras are named `..._Json_<projectId>` and listed in `global.firebase.accounts[]` |
-| `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token         |
-| `appstore_connect_key_id` | App Store Connect | `${USER}_AppStoreConnect_Key_Id` | Identifier, not a secret |
-| `appstore_connect_issuer_id` | App Store Connect | `${USER}_AppStoreConnect_Issuer_Id` | Identifier, not a secret |
-| `appstore_connect_apple_id` | App Store Connect | `${USER}_AppStoreConnect_Apple_Id` | Email address |
-| `appstore_connect_password_item` | App Store Connect | `${USER}_AppStoreConnect_Password_Item` | Keychain ITEM NAME, not a password |
-|  -                   | Git Identity       | Stored in preferences JSON         | Not Keychain      |
+| Service ID         | Context            | Standard Key Name                  | Type              | Where to Get |
+| ------------------ | ------------------ | ---------------------------------- | ----------------- | ------------ |
+| `jira`             | Jira issue fetch   | `${USER}_Jira_Access_Token`        | PAT | Jira -> Profile -> Personal Access Tokens (VPN) |
+| `bitbucket_token`  | Bitbucket PR/push  | `${USER}_Bitbucket_Access_Token`   | App Password | Bitbucket -> Personal settings -> App passwords |
+| `bitbucket_user`   | Bitbucket username | `${USER}_Bitbucket_Username`       | Plain text | Bitbucket profile username (plain text, not a PAT) |
+| `github`           | GitHub issue/PR    | `${USER}_Github_Access_Token`      | PAT (+ `gh auth`) | GitHub Settings -> Tokens (scopes: repo, read:org, project) |
+| `confluence`       | Confluence docs    | `${USER}_Confluence_Access_Token`  | PAT | Confluence -> Profile -> Personal Access Tokens (VPN) |
+| `figma`            | Figma              | `${USER}_Figma_Access_Token`       | PAT | Figma Developer Settings (max 90 days). Tier 2 / REST |
+| `figma_mcp`        | Figma MCP          | `${USER}_Figma_Mcp_Access_Token`   | OAuth | Automatic via Claude Code Figma MCP remote auth. Tier 1 |
+| `fortify`          | Fortify            | `${USER}_Fortify_Access_Token`     | API Token | Fortify SSC -> Token Management (VPN) |
+| `graylog`          | Graylog (prod)     | `${USER}_Graylog_Access_Token`     | API Token | Graylog -> System -> Users and Teams -> Edit Tokens (VPN) |
+| `graylog_test`     | Graylog (test)     | `${USER}_Graylog_Test_Access_Token` | API Token, optional  -  unset falls back to `graylog` | Same page on the TEST instance; optional |
+| `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | Service-account JSON, as issued. One key per Firebase project; extras are named `..._Json_<projectId>` and listed in `global.firebase.accounts[]` | Firebase Console -> Project settings -> Service accounts -> Generate new private key |
+| `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token | Jenkins -> User -> Configure -> API Token |
+| `appstore_connect_key_id` | App Store Connect | `${USER}_AppStoreConnect_Key_Id` | Identifier, not a secret | App Store Connect -> Users and Access -> Integrations -> App Store Connect API |
+| `appstore_connect_issuer_id` | App Store Connect | `${USER}_AppStoreConnect_Issuer_Id` | Identifier, not a secret | Same page as the key id; one issuer id per team |
+| `appstore_connect_apple_id` | App Store Connect | `${USER}_AppStoreConnect_Apple_Id` | Email address | The Apple ID itself; no generation step |
+| `appstore_connect_password_item` | App Store Connect | `${USER}_AppStoreConnect_Password_Item` | Keychain ITEM NAME, not a password | `xcrun altool --store-password-in-keychain-item`; map only the item NAME |
+|  -                   | Git Identity       | Stored in preferences JSON         | Not Keychain | Written to preferences by setup Step 4 |
 
 **Key name mapping lives in preferences:**
 
@@ -171,3 +198,21 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 ```bash
 bash "$HOME/.claude/scripts/keychain-save.sh" <service-id>
 ```
+
+## Cross-platform mechanics
+
+Moved out of `setup/SKILL.md`: it is reference detail every credential path shares,
+and the setup skill only needs to route to it.
+
+The credential store is platform-agnostic  -  every read/write goes through `~/.claude/lib/credential-store.sh`, which dispatches to the right backend (`security` on macOS, `secret-tool` on Linux, PowerShell `CredentialManager` on Windows). On macOS / Linux the shell driver delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. You almost never need the platform-native commands directly.
+
+Clipboard helpers (`pbpaste`, `pbcopy`) are macOS-specific  -  for Copilot CLI on Linux substitute:
+
+| macOS command | Linux equivalent | Notes |
+|---|---|---|
+| `pbpaste` | `xclip -selection clipboard -o` (X11) or `wl-paste` (Wayland) | Install with `apt install xclip` or `apt install wl-clipboard` |
+| `pbcopy < /dev/null` | `xclip -selection clipboard < /dev/null` or `wl-copy --clear` | Same intent: clear clipboard after token paste |
+
+If you need to bypass the helper (debugging, raw inspection), the underlying platform commands are documented at the top of `$HOME/.claude/lib/credential-store.sh`. Otherwise stay on the helper  -  it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes on macOS.
+
+If no backend is available, setup falls back to a plain-text prompt + a warning that the token is **not persisted**  -  pipeline phases will re-ask each session.

package/pipeline/multi-agent-refs/knowledge.md

@@ -67,6 +67,33 @@ Knowledge files grow over time. Maintenance rules:
 
 ---
 
+## Retrieval order, and what each layer costs
+
+Every durable store here answers in layers, and the order costs more than the
+query does. Filter first, fetch second.
+
+| # | Call | Returns | Rough cost per hit |
+|---|---|---|---|
+| 1 | `query` / `brief` / `search --semantic` | pointers: id, file, one line | ~50-100 tokens |
+| 2 | `timeline --anchor <id>` | the rows recorded around one hit | ~50-100 tokens each |
+| 3 | `show --id <id>` | one full row | ~500-1000 tokens |
+| 4 | the artefact behind a `[[ref:<id>]]` | the raw payload | thousands |
+
+Starting at layer 3 is the mistake worth naming: a `show` on twenty pointers
+costs more than the search that produced them, and answers a question nobody
+asked. Narrow at 1, widen at 2 only around what survived, and open 3 for the
+handful that will actually be read.
+
+Layer 2 is the one that gets skipped. A finding rarely stands alone - the same
+review pass produced its neighbours, and those are usually what makes an old row
+legible a year later. Both JSONL stores are append-only, so line adjacency is
+chronological adjacency and the neighbourhood needs no index to answer:
+
+```bash
+node "$HOME/.claude/scripts/triage-memory.mjs"    timeline --anchor T:<id> --before 3 --after 3
+node "$HOME/.claude/scripts/learnings-ledger.mjs" timeline --anchor L:<id> --before 3 --after 3
+```
+
 ## Skill Injection Strategy
 
 When calling sub-agents, inject task-specific context from previous phases: