@mmerterden/multi-agent-pipeline 13.3.0 → 13.5.0

package/pipeline/lib/figma-mcp-refresh.sh

@@ -20,7 +20,6 @@ set -euo pipefail
 
 PREFS_FILE="${PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
 TOKEN_ENDPOINT="https://api.figma.com/v1/oauth/token"
-ACCOUNT="${USER:-$(whoami)}"
 
 say() { printf '%s\n' "$*"; }
 
@@ -30,7 +29,36 @@ KEY_NAME=$(jq -r '.global.keychainMapping.figma_mcp // empty' "$PREFS_FILE")
 [ -n "$KEY_NAME" ] || { say "figma-mcp-refresh: keychainMapping.figma_mcp not set"; exit 2; }
 
 REFRESH_KEY="${KEY_NAME}_Refresh"
-REFRESH_TOKEN=$(security find-generic-password -s "$REFRESH_KEY" -w 2>/dev/null || true)
+
+# Locate the resolver with an existence check, not a `.`-chain.
+#
+# Sourcing a file that does not exist aborts the shell under `set -e` - `||` included -
+# so `. <candidate> || . <candidate> || { error }` reaches neither its later candidates
+# nor its error branch. Every fetcher used that shape starting from `$HOME/.claude/...`,
+# so on a Copilot-only or Codex-only install they all died with a bare exit 1 and no
+# message. Reordering does not help: whichever candidate is absent aborts at that point.
+# Checking for the file before sourcing it is the only safe form.
+for _cred_resolver in \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/credential-store-resolver.sh" \
+  "$HOME/.claude/lib/credential-store-resolver.sh" \
+  "$HOME/.copilot/lib/credential-store-resolver.sh" \
+  "$HOME/.codex/lib/credential-store-resolver.sh"; do
+  [ -f "$_cred_resolver" ] || continue
+  # shellcheck source=/dev/null
+  . "$_cred_resolver" 2>/dev/null || true
+  # `if`, not `[ ... ] && break`: the latter is the loop body's last command and returns
+  # 1 when CRED_STORE is still empty, which under `set -e` kills the loop on the first
+  # candidate that does not resolve - the very case the loop exists to survive.
+  if [ -n "${CRED_STORE:-}" ]; then break; fi
+done
+unset _cred_resolver
+if [ -z "${CRED_STORE:-}" ]; then
+  say "figma-mcp-refresh: credential helper not found  -  run the pipeline installer"
+  exit 2
+fi
+
+REFRESH_TOKEN=$("$CRED_STORE" get "$REFRESH_KEY" 2>/dev/null || true)
 [ -n "$REFRESH_TOKEN" ] || { say "figma-mcp-refresh: no refresh token at '$REFRESH_KEY'"; exit 2; }
 
 SCRIPT_PATH=$(jq -r '.global.tokenScripts.figma_mcp // empty' "$PREFS_FILE")
@@ -69,17 +97,13 @@ if [ -z "$NEW_ACCESS" ]; then
   exit 1
 fi
 
-# Keychain write: the add-generic-password command is fed to `security -i`
-# over stdin instead of the direct `security add-generic-password -w <secret>`
-# argv form, so the secret never shows up in process listings. printf is a
-# bash builtin, so no argv exposure there either. Attributes match the
-# previous direct call (-T "" -U). Figma tokens are URL-safe, so embedding in
-# the quoted command string is safe.
+# Keychain write through credential-store.sh with the `-` form, which reads the secret
+# from stdin: the value never lands on any argv (visible to ps), which is the property
+# the previous `security -i` call was carefully preserving. The store does the same thing
+# per platform, so that property now holds on Linux and Windows as well.
 save_keychain_secret() {
   local service="$1" secret="$2"
-  security delete-generic-password -s "$service" -a "$ACCOUNT" >/dev/null 2>&1 || true
-  printf 'add-generic-password -U -s "%s" -a "%s" -T "" -w "%s"\n' \
-    "$service" "$ACCOUNT" "$secret" | security -i >/dev/null
+  printf '%s' "$secret" | "$CRED_STORE" set "$service" - >/dev/null
 }
 
 # Save new access token first, then the rotated refresh token  -  order matters so a

package/pipeline/lib/figma-screenshot.sh

@@ -42,13 +42,24 @@ set -euo pipefail
 # --- Globals ----------------------------------------------------------------
 
 PREFS="$HOME/.claude/multi-agent-preferences.json"
-# Locate the credential helper via the resolver so Copilot-only installs work.
-# The helper is optional here: the FIGMA_PAT env fallback still applies when
-# no helper is installed, so a resolver miss must not abort the script.
-# shellcheck disable=SC1090,SC1091
-. "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-  || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-  || true
+# Locate the resolver with an existence check, not a `.`-chain: sourcing a missing file
+# aborts the shell under `set -e`, `||` included, so a chain skips both its later
+# candidates and its trailing `|| true`. A missing store is tolerated here - CRED_STORE
+# simply stays empty and the caller falls back to an env-supplied token.
+for _cred_resolver in \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+  "$HOME/.claude/lib/credential-store-resolver.sh" \
+  "$HOME/.copilot/lib/credential-store-resolver.sh" \
+  "$HOME/.codex/lib/credential-store-resolver.sh"; do
+  [ -f "$_cred_resolver" ] || continue
+  # shellcheck source=/dev/null
+  . "$_cred_resolver" 2>/dev/null || true
+  # `if`, not `[ ... ] && break`: the latter is the loop body's last command and returns
+  # 1 when CRED_STORE is still empty, which under `set -e` kills the loop on the first
+  # candidate that does not resolve - the very case the loop exists to survive.
+  if [ -n "${CRED_STORE:-}" ]; then break; fi
+done
+unset _cred_resolver
 CRED_STORE="${CRED_STORE:-}"
 FIGMA_API="https://api.figma.com/v1"
 PARALLEL_DL=4

package/pipeline/lib/issue-fetcher.sh

@@ -113,10 +113,25 @@ fetch_jira() {
   # A pre-set CRED_STORE (tests, custom installs) is honored as-is.
   if [ -z "${CRED_STORE:-}" ]; then
     # shellcheck disable=SC1090,SC1091
-    . "$(cd "$(dirname "$0")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
-      || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-      || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-      || { echo "ERR: credential helper not found" >&2; return 1; }
+    # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
+    # `||` included, so a `.`-chain reaches neither its later candidates nor its error
+    # branch. The loop also covers all three hosts - the chain it replaced knew only
+    # .claude and .copilot, so a Codex-only install could not resolve at all.
+    for _cred_resolver in \
+      "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+      "$HOME/.claude/lib/credential-store-resolver.sh" \
+      "$HOME/.copilot/lib/credential-store-resolver.sh" \
+      "$HOME/.codex/lib/credential-store-resolver.sh"; do
+      [ -f "$_cred_resolver" ] || continue
+      # shellcheck source=/dev/null
+      . "$_cred_resolver" 2>/dev/null || true
+      if [ -n "${CRED_STORE:-}" ]; then break; fi
+    done
+    unset _cred_resolver
+    if [ -z "${CRED_STORE:-}" ]; then
+      echo "ERR: credential helper not found" >&2
+      return 1
+    fi
   fi
   local token
   token=$("$CRED_STORE" get "$JIRA_TOKEN_KEY" 2>/dev/null || true)

package/pipeline/lib/post-pr-review.sh

@@ -104,7 +104,14 @@ echo "post-pr-review: decision=$DECISION (blocking=$ACCEPTED_BLOCKING, important
 # when the suggested fix wording changes slightly between iterations.
 finding_fingerprint() {
   local path="$1" line="$2" issue="$3"
-  printf '%s|%s|%s' "$path" "$line" "$issue" | shasum -a 256 | cut -c1-16
+  # sha256sum (coreutils) or shasum (perl), whichever this platform has. A bare
+  # `shasum` produced an empty fingerprint on slim Linux images, which made every
+  # finding look new and re-posted the whole review on each iteration.
+  if command -v sha256sum >/dev/null 2>&1; then
+    printf '%s|%s|%s' "$path" "$line" "$issue" | sha256sum | cut -c1-16
+  else
+    printf '%s|%s|%s' "$path" "$line" "$issue" | shasum -a 256 | cut -c1-16
+  fi
 }
 
 render_inline_body() {
@@ -307,9 +314,25 @@ post_bitbucket_server() {
   # Credential Manager / Linux libsecret)  -  sourced lazily so this script keeps
   # working when run from either ~/.claude/lib or ~/.copilot/lib.
   # shellcheck disable=SC1090
-  . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-    || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-    || { echo "post-pr-review: credential helper not found" >&2; return 4; }
+  # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
+  # `||` included, so a `.`-chain reaches neither its later candidates nor its error
+  # branch. The loop also covers all three hosts - the chain it replaced knew only
+  # .claude and .copilot, so a Codex-only install could not resolve at all.
+  for _cred_resolver in \
+    "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+    "$HOME/.claude/lib/credential-store-resolver.sh" \
+    "$HOME/.copilot/lib/credential-store-resolver.sh" \
+    "$HOME/.codex/lib/credential-store-resolver.sh"; do
+    [ -f "$_cred_resolver" ] || continue
+    # shellcheck source=/dev/null
+    . "$_cred_resolver" 2>/dev/null || true
+    if [ -n "${CRED_STORE:-}" ]; then break; fi
+  done
+  unset _cred_resolver
+  if [ -z "${CRED_STORE:-}" ]; then
+    echo "post-pr-review: credential helper not found" >&2
+    return 4
+  fi
   resolve_credential_store || return 4
 
   auth_user=$("$CRED_STORE" get "$user_key" 2>/dev/null || true)

package/pipeline/lib/repo-cache.sh

@@ -142,10 +142,25 @@ print(json.dumps(out))
     # A pre-set CRED_STORE (tests, custom installs) is honored as-is.
     if [ -z "${CRED_STORE:-}" ]; then
       # shellcheck disable=SC1090,SC1091
-      . "$(cd "$(dirname "$0")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
-        || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-        || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-        || { echo "ERR: credential helper not found" >&2; exit 3; }
+      # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
+      # `||` included, so a `.`-chain reaches neither its later candidates nor its error
+      # branch. The loop also covers all three hosts - the chain it replaced knew only
+      # .claude and .copilot, so a Codex-only install could not resolve at all.
+      for _cred_resolver in \
+        "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+        "$HOME/.claude/lib/credential-store-resolver.sh" \
+        "$HOME/.copilot/lib/credential-store-resolver.sh" \
+        "$HOME/.codex/lib/credential-store-resolver.sh"; do
+        [ -f "$_cred_resolver" ] || continue
+        # shellcheck source=/dev/null
+        . "$_cred_resolver" 2>/dev/null || true
+        if [ -n "${CRED_STORE:-}" ]; then break; fi
+      done
+      unset _cred_resolver
+      if [ -z "${CRED_STORE:-}" ]; then
+        echo "ERR: credential helper not found" >&2
+        exit 3
+      fi
     fi
     BB_USER="${BB_USER:-${BB_USER_KEY:+$("$CRED_STORE" get "$BB_USER_KEY" 2>/dev/null || true)}}"
     BB_TOKEN=$("$CRED_STORE" get "$BB_TOKEN_KEY" 2>/dev/null || true)

package/pipeline/lib/vercel-deploy.sh

@@ -115,10 +115,21 @@ cmd_deploy() {
     # The resolver ships alongside this wrapper in lib/; fall back to the
     # per-CLI install locations when running from a different cwd layout.
     # shellcheck source=/dev/null
-    . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/credential-store-resolver.sh" 2>/dev/null \
-      || . "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-      || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-      || true
+    # Existence check before sourcing: `. <missing>` aborts the shell under `set -e`,
+    # `||` included, so a `.`-chain reaches neither its later candidates nor its error
+    # branch. The loop also covers all three hosts - the chain it replaced knew only
+    # .claude and .copilot, so a Codex-only install could not resolve at all.
+    for _cred_resolver in \
+      "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+      "$HOME/.claude/lib/credential-store-resolver.sh" \
+      "$HOME/.copilot/lib/credential-store-resolver.sh" \
+      "$HOME/.codex/lib/credential-store-resolver.sh"; do
+      [ -f "$_cred_resolver" ] || continue
+      # shellcheck source=/dev/null
+      . "$_cred_resolver" 2>/dev/null || true
+      if [ -n "${CRED_STORE:-}" ]; then break; fi
+    done
+    unset _cred_resolver
     echo "ERROR: VERCEL_TOKEN not set. Resolve via env or keychain ('${CRED_STORE:-credential-store.sh} get <vercel-key>')." >&2
     echo "Hint: vercel CLI accepts the token via env var; do NOT pass --token= on argv (leaks on retry)." >&2
     exit 1

package/pipeline/multi-agent-refs/features/external-context-injection.md

@@ -32,12 +32,53 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 
 - `0` (success) → output appended to `state.fetchedContext.<type>[]` and injected into the prompt.
 - `2` (blocked / missing token) → run the inline Token Save Flow per `setup.md`; on skip, mark the entry as `{status: "skipped", reason: "missing-token"}` and continue.
-- `3` (network/auth) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue.
+- `3` (network/auth) → **surface the Unreachable-source decision below.** Never silently downgrade.
 - `4`/`5`/`6` (config errors) → mark as `{status: "failed", reason: "<exit-msg>"}`, continue and log a setup hint.
 
-Failures are never fatal at Phase 1  -  the agent still runs analysis, just without the referenced source.
+### MUST: an unreachable source is announced, not absorbed (BLOCKING)
 
-**Graylog specifics.** `fetch-graylog.sh` degrades to empty on any network/VPN failure: it emits a normalized empty object and exits `0`, so an unreachable host reads as `{status:"skipped", reason:"vpn-unreachable"}` and never blocks. Only a genuine auth rejection on a reachable host exits `3` (marked `failed`, still non-fatal here). `state.graylogContext` is prepended to the analysis prompt inside the **Referenced External Sources** section as diagnostic context that is **advisory only**  -  the agent may use it to orient on a reported error, but code remains ground truth, and there is no Phase 4 review gate for logs.
+A fetcher that fails is the pipeline losing the ground truth it was told to use. The
+user is the only one who can fix it - the token is theirs to refresh, the VPN is theirs
+to connect - and they cannot fix what they are not told about.
+
+This used to read "mark as failed, continue". The observed result: an expired token and
+a VPN-off remote both reached the analysis phase as *no data*, indistinguishable from a
+ticket that referenced nothing. The run then produced a plan from a partial picture and
+reported success, and the user found out by reading the output.
+
+So on exit `3`, classify the stderr and surface an `AskUserQuestion` before continuing.
+The classification is the same shape the Phase 6 remote gate uses, because the failures
+are the same failures:
+
+| stderr signal | Diagnosis | Question offers |
+|---|---|---|
+| `401`, `403`, `invalid_grant`, `token expired`, `unauthorized` | the credential is dead | **Refresh `<KEY_NAME>`** (Save Flow Step B, then retry) · **Continue without this source** · **Abort** |
+| `could not resolve host`, `connection refused`, `timed out`, `network is unreachable`, corporate host in the URL | the host is unreachable, VPN almost certainly off | **Connect the VPN, then retry** (default) · **Continue without this source** · **Abort** |
+| `404`, `no such issue`, `not found` | the reference is stale or the link points at something deleted | **Supply a current URL** · **Continue without this source** · **Abort** |
+| anything else | unknown | verbatim stderr in the `description`, same three options |
+
+Rules that make this actionable rather than decorative:
+
+1. **Name the thing.** The question states which source (`crashlytics`), which URL, and
+   which credential key by its logical name (`firebase`, never the raw Keychain item).
+2. **Say what is lost.** "Without it I plan from the exception message alone, with no
+   stack frames and no affected-version spread" beats "continuing without context".
+3. **Retry is a real branch.** On "Connect the VPN, then retry" / "Refresh", re-run the
+   same fetcher and re-enter this table on a second failure. Do not fall through to
+   "continue" after one attempt.
+4. **Record the choice.** `state.fetchedContext.<type>[].status` ∈ `ok | skipped | failed`
+   plus `userDecision` ∈ `retried-ok | continued-without | aborted`, so Phase 1 can put
+   "planned without Crashlytics, user's choice at <ts>" in the analysis doc's limitations
+   section instead of leaving a silent hole.
+5. **Autopilot still reports.** Autopilot takes "continue without this source" without
+   asking, but the skipped source is logged and carried into the Phase 7 report. An
+   autopilot run that quietly planned from a partial picture is the same defect with a
+   flag on it.
+
+Failures remain non-fatal at Phase 1 by default - the agent still runs analysis. What
+changed is that the user learns about it while the choice is still theirs to make.
+
+**Graylog specifics.** `fetch-graylog.sh` degrades to empty on any network/VPN failure: it emits a normalized empty object and exits `0`, so an unreachable host reads as `{status:"skipped", reason:"vpn-unreachable"}` and never blocks. **Exiting `0` is not permission to stay quiet.** The payload carries `degraded: true` and a `degradeReason`; when it does, log one line naming the host and the reason, and carry it into the Phase 7 report. Logs are advisory, so this never asks a question and never blocks - but "I searched the logs and found nothing" and "I never reached the log server" are different statements, and only one of them is true. Only a genuine auth rejection on a reachable host exits `3` (marked `failed`, still non-fatal here). `state.graylogContext` is prepended to the analysis prompt inside the **Referenced External Sources** section as diagnostic context that is **advisory only**  -  the agent may use it to orient on a reported error, but code remains ground truth, and there is no Phase 4 review gate for logs.
 
 ## Prompt injection shape
 

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

@@ -40,6 +40,69 @@ Reasons:
 
 The smoke gate `pipeline/scripts/smoke-no-token-prompt.sh` greps the pipeline source for hardcoded "enter token" / "paste token" / "API key:" prompts and fails the build if any are introduced. Token I/O is exclusively `credential-store.sh` calls.
 
+### Rule 2  -  MUST: never ask the user for what a mapped credential can fetch (BLOCKING)
+
+Before asking the user for data that an external system holds - a stack trace, a log
+line, a page body, a finding, a design frame - inventory the credentials first:
+
+```bash
+bash "$HOME/.claude/lib/credential-inventory.sh" --json            # what is configured
+bash "$HOME/.claude/lib/credential-inventory.sh" --json --probe    # and what actually answers
+bash "$HOME/.claude/lib/credential-inventory.sh" --key firebase     # exit 0 = usable
+```
+
+The inventory reads `prefs.global.keychainMapping`, probes each logical key through
+`credential-store.sh get` with the value discarded, and reports `present` /
+`mapped-but-missing` / `unmapped` alongside what each key unlocks. Values are never
+printed.
+
+The answer then decides the shape of the question:
+
+| Inventory says | The question must be |
+|---|---|
+| `present` | ask for the **pointer**, not the payload, and say you will fetch it: "Give me the Crashlytics issue URL - I have the Firebase service account mapped and will pull the stack frames, affected versions and device spread myself." |
+| `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." |
+
+**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
+certain route", while a valid Firebase service-account JSON sat in the Keychain mapped
+as `firebase`. The user had configured that key precisely so the pipeline would not ask.
+
+**State the limit honestly too.** A credential is not omniscience: the Crashlytics
+fetcher resolves a specific issue and needs its URL, so "I have the key" does not mean
+"I can find the crash from an exception message alone". Say which piece is missing and
+why, rather than implying either more or less capability than exists.
+
+#### Present is not the same as working
+
+`--probe` makes one cheap authenticated request per configured credential, because
+"the key is in the Keychain" and "the service answers" are different claims and the user
+fixes them in different ways:
+
+| Verdict | What it means | What to tell the user |
+|---|---|---|
+| `reachable` | the service answered and accepted the credential | nothing - proceed |
+| `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) |
+| `not-probeable` | no cheap probe exists for this credential type | do not claim it works, do not claim it fails |
+
+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.
+
+Probe only what is configured. An unmapped key is a capability the user chose not to
+enable - reporting it as a problem trains them to ignore the report. Cache the result in
+`prefs.global.serviceStatus.<service>` (`{ok, checkedAt, error?}`, TTL
+`settings.serviceStatusCacheSeconds`) so a phase chain probes once, not per fetcher.
+
+Record what the inventory found in `agent-state.json.credentialInventory`
+(`{usable: [...], needsAttention: [...], at: <ts>}`) so a later phase can tell "the
+source was unreachable" from "nobody looked".
+
 **Retrieve pattern (always use mapping):**
 
 ```bash

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -136,6 +136,22 @@ Results are cached in `global.serviceStatus` (existing TTL contract, default 300
 
 Probe failures caused by network (timeout, DNS) are NOT treated as expiry  -  log and continue; the mid-run 401 path still exists as the safety net.
 
+**Record the inventory.** After the probes, persist what is reachable:
+
+```bash
+# --probe when the task references an external source (Jira ID, Crashlytics/Fortify URL,
+# a remote to fetch): "the key is in the Keychain" and "the service answers" are
+# different claims, and only the second one lets the run proceed.
+bash "$HOME/.claude/lib/credential-inventory.sh" --json --probe > /tmp/cred-inventory-${TASK_ID}.json
+```
+
+Write `{usable, needsAttention, at}` into `agent-state.json.credentialInventory`. Later
+phases read it instead of re-probing, and it is what makes `keychain.md` Rule 2
+enforceable: any question that asks the user for data an external system holds must be
+shaped by this file. A run that asks the user to paste a Crashlytics stack trace while
+`firebase` is listed under `usable` is a Rule 2 violation, and the inventory is the
+evidence.
+
 #### Step 1  -  Parse Input
 
 **Branch from input**: If the user provided a branch name after the issue reference (space-separated), store as `baseBranch` and skip Step 3. Otherwise Step 3 asks interactively.
@@ -233,18 +249,30 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
      | grep -E '(develop|release|main|master)' \
      | grep -v -E '(feature/|bugfix/|fix/|hotfix/|chore/)'
    ```
-6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Present numbered list with standard UX pattern:
+6. Sort: `develop*` first, then `release/*`, then `main`/`master`. Surface through the
+   **native picker** per `picker-contract.md` (`AskUserQuestion` on Claude Code,
+   `ask_choice.sh` on Copilot CLI) - `question` + `description` in `outputLanguage`,
+   `label` English, the recent branch first and marked `(Recommended)`. The ASCII sketch
+   below is what the options carry, not a menu to print:
+
    ```
-   Base branch:
-     Recent: → develop (enter to reuse)
-     ────────────────────
-     1. origin/develop
-     2. origin/main
-     ...
-   Select [number] or enter for suggested:
+   header: "Base branch"
+   options: origin/develop (Recommended, reused from last run) | origin/main | release/8.4.0 | Other
    ```
 7. User picks → store as `baseBranch`. Save to `prefs.projects[{project}].branches` (dedup, max 10).
 
+**MUST: this step is not skippable (BLOCKING).** The only legitimate skip is rule 4
+above - `baseBranch` already supplied in the input. Everything else asks. A run once
+took a Jira ID and implemented straight onto whatever the local checkout was pointing
+at, with neither the project nor the branch picker ever shown; nothing failed, so
+nothing surfaced it. `phase0-exit-gate.mjs` now refuses to close Phase 0 unless
+`agent-state.json` carries `baseBranch` and `baseFetchStatus`, so a skipped picker is a
+gate failure rather than a silent default.
+
+This holds in every mode. `--dev` skips the *LLM* phases (Analysis, Planning); it does
+not skip Phase 0's pickers. Autopilot resolves them to their defaults without prompting,
+which still writes the fields - it does not leave them unset.
+
 **TTL filter for recent branches**:
 
 - `prefs.global.recentBranches[{projectKey}][]` carries `{name, lastUsed}`. Filter to those whose `lastUsed` is within `settings.branchTtlDays` (default 15).
@@ -253,20 +281,25 @@ Scan `$HOME` (maxdepth 2) for project markers (`.xcodeproj`, `Package.swift`, `b
 
 **Fetch-fail handling** (replaces silent `git fetch origin` failure):
 
-The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, present 4 options (per `feedback_multi_agent_fetch_fail`):
+The legacy `git -C $PROJECT_ROOT fetch origin` step (line 110 above) MUST not silently fall back to a stale cached ref. On non-zero exit, surface the **native picker** (per `picker-contract.md`) with 4 options:
 
 ```
-git fetch origin failed for {project} (exit {code}, last attempt {ts}).
-Likely causes: VPN closed, host unreachable, auth expired.
-
-  [1] Connect VPN / fix network, then resume #{taskId}     (safest)
-  [2] Use cached origin/{baseBranch} ref                    (stale risk: base sha {sha}, fetched {since})
-  [3] Use local branch "{baseBranch}" as base               (only if local branch exists; commit {sha})
-  [4] Abort  -  no worktree, no branch, no state file
-
-Select:
+question:    "git fetch failed for {project} - the base ref may be stale. How should I proceed?"
+description: "exit {code}, last successful fetch {ts}. Likely: VPN closed, host unreachable, auth expired."
+header:      "Base ref"
+options:
+  Connect VPN and retry      (Recommended)  re-run the fetch, then continue with a fresh ref
+  Use cached origin ref                     stale risk: base sha {sha}, fetched {since}
+  Use local branch as base                  only offered when the local branch exists; commit {sha}
+  Abort                                     no worktree, no branch, no state file
 ```
 
+**Say which is which.** The question must name the corporate host when the remote points
+at one - a `{BITBUCKET_HOST}` remote failing to resolve is almost always the VPN, and
+telling the user that is the difference between a five-second fix and a run built on a
+month-old ref. "Connect VPN and retry" re-runs the fetch and re-enters this picker if it
+fails again; it is a real retry, not a label.
+
 Persist user choice in `agent-state.json.baseFetchStatus` ∈ `"fresh" | "cached-stale" | "local-branch" | "aborted"`. On any non-fresh choice, log:
 ```
 ⚠️ Base ref stale (fetch fail @ {ts}, choice: {cached-stale|local-branch})

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

@@ -163,10 +163,10 @@ Provider tools that print failed argv on retry leak credentials into the convers
 # goes through the cross-platform credential helper so the same snippet works
 # on macOS / Linux / Windows installs:
 VERCEL_TOKEN="$(~/.claude/lib/credential-store.sh get mmerterden_Vercel_Access_Token)" \
-  bash $HOME/.claude/scripts/vercel-deploy.sh deploy --prod
+  bash $HOME/.claude/lib/vercel-deploy.sh deploy --prod
 
 # Health check before deploy:
-bash $HOME/.claude/scripts/vercel-deploy.sh doctor
+bash $HOME/.claude/lib/vercel-deploy.sh doctor
 ```
 
 **Forbidden:**
@@ -177,7 +177,7 @@ vercel deploy --token=vcp_...
 vercel deploy --token "$VERCEL_TOKEN"
 ```
 
-The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/scripts/vercel-deploy.sh` and `~/.copilot/scripts/vercel-deploy.sh`) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_...`, `Bearer ...`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
+The wrapper at `pipeline/lib/vercel-deploy.sh` (installed to `~/.claude/lib/`, `~/.copilot/lib/` and `~/.codex/lib/` with the rest of the shell libraries) refuses any `--token=` argv input, runs the CLI with `VERCEL_TOKEN` env, and pipes every stdout/stderr line through a redact filter that scrubs `vcp_...`, `Bearer ...`, and JSON-body token shapes. Regression gate: `smoke-vercel-deploy-redact.sh` (12 assertions).
 
 Same rule applies to any future provider wrapper (e.g. `cloudflare-deploy.sh`, `npm-publish.sh`)  -  never pass tokens via argv when the underlying CLI may echo argv on failure.
 

package/pipeline/scripts/audit-log.sh

@@ -48,12 +48,18 @@ json_escape() {
 hash_url() {
   local url="$1"
   [ -z "$url" ] && { echo ""; return; }
-  if command -v shasum >/dev/null 2>&1; then
-    printf '%s' "$url" | shasum -a 256 | awk '{print $1}'
-  elif command -v sha256sum >/dev/null 2>&1; then
+  # sha256sum first: it is the coreutils tool, present on Linux and in slim containers
+  # where `shasum` (a perl script) is not.
+  if command -v sha256sum >/dev/null 2>&1; then
     printf '%s' "$url" | sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    printf '%s' "$url" | shasum -a 256 | awk '{print $1}'
   else
-    echo "unhashed:$url"  # last-resort fallback (should never happen on macOS/Linux)
+    # The previous fallback printed `unhashed:<url>`, writing the plaintext remote into
+    # the audit log - the exact thing this hashing exists to prevent, and it would have
+    # carried any credentials embedded in the remote URL with it. Losing one field beats
+    # leaking one.
+    echo "unhashable-no-sha256-tool"
   fi
 }
 

package/pipeline/scripts/keychain-save.sh

@@ -53,11 +53,33 @@ case "$CHOICE" in
         ;;
 esac
 
-# Locate the credential helper via the resolver so Copilot-only installs work.
-# shellcheck disable=SC1090,SC1091
-. "$HOME/.claude/lib/credential-store-resolver.sh" 2>/dev/null \
-  || . "$HOME/.copilot/lib/credential-store-resolver.sh" 2>/dev/null \
-  || { echo "Hata: credential-store bulunamadi. Kurulum: npx @mmerterden/multi-agent-pipeline install"; exit 1; }
+# Locate the resolver with an existence check, not a `.`-chain.
+#
+# Sourcing a file that does not exist aborts the shell under `set -e` - `||` included -
+# so `. <candidate> || . <candidate> || { error }` reaches neither its later candidates
+# nor its error branch. Every fetcher used that shape starting from `$HOME/.claude/...`,
+# so on a Copilot-only or Codex-only install they all died with a bare exit 1 and no
+# message. Reordering does not help: whichever candidate is absent aborts at that point.
+# Checking for the file before sourcing it is the only safe form.
+for _cred_resolver in \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/credential-store-resolver.sh" \
+  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../lib" 2>/dev/null && pwd)/credential-store-resolver.sh" \
+  "$HOME/.claude/lib/credential-store-resolver.sh" \
+  "$HOME/.copilot/lib/credential-store-resolver.sh" \
+  "$HOME/.codex/lib/credential-store-resolver.sh"; do
+  [ -f "$_cred_resolver" ] || continue
+  # shellcheck source=/dev/null
+  . "$_cred_resolver" 2>/dev/null || true
+  # `if`, not `[ ... ] && break`: the latter is the loop body's last command and returns
+  # 1 when CRED_STORE is still empty, which under `set -e` kills the loop on the first
+  # candidate that does not resolve - the very case the loop exists to survive.
+  if [ -n "${CRED_STORE:-}" ]; then break; fi
+done
+unset _cred_resolver
+if [ -z "${CRED_STORE:-}" ]; then
+  echo "Hata: credential-store bulunamadi. Kurulum: npx @mmerterden/multi-agent-pipeline install"
+  exit 1
+fi
 CRED="$CRED_STORE"
 
 "$CRED" delete "$SERVICE_NAME" >/dev/null 2>&1 || true

package/pipeline/scripts/phase-tracker.sh

@@ -193,6 +193,25 @@ MA_DECODE_JS
   printf '%s' "$out"
 }
 
+# Portable SHA-256 over stdin, printing the same "<hex>  -" shape as either tool.
+#
+# GNU coreutils ships sha256sum; macOS ships shasum (a perl script). Neither is
+# universal - Alpine and slim container images typically have sha256sum but no perl, and
+# some hardened macOS setups have neither on a restricted PATH. Trying both keeps the
+# tracker working on all three supported platforms, and the no-hasher branch emits an
+# obviously-synthetic value rather than an empty string, so a broken environment shows
+# up as a visibly fake id instead of a silently blank field.
+sha256_hex() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256
+  else
+    cat >/dev/null
+    printf '%s  -\n' "0000000000000000000000000000000000000000000000000000000000nohash"
+  fi
+}
+
 # OTel-compatible span emission  -  v6.1.0+, opt-in via $MULTI_AGENT_OTEL_SPANS.
 # Appends one JSON line to otel-spans.jsonl. Never fatal on failure.
 #
@@ -218,9 +237,14 @@ emit_otel_span() {
   local spans_file="${TRACKER_DIR}/otel-spans.jsonl"
 
   # Deterministic 128-bit trace_id from task_id, 64-bit span_id from event+phase+timestamp.
+  #
+  # sha256_hex, not `shasum` directly: this runs on every phase on every host, and
+  # `shasum` is a perl script that is absent from minimal Linux images and many
+  # containers. Without a fallback the ids came back empty and the span was written with
+  # blank trace/span - valid JSON, useless telemetry, and no error to notice.
   local trace_id span_id
-  trace_id=$(printf "%s" "$task_id" | shasum -a 256 | awk '{print substr($1,1,32)}')
-  span_id=$(printf "%s:%s:%s" "$event" "$phase_id" "$now_ns" | shasum -a 256 | awk '{print substr($1,1,16)}')
+  trace_id=$(printf "%s" "$task_id" | sha256_hex | awk '{print substr($1,1,32)}')
+  span_id=$(printf "%s:%s:%s" "$event" "$phase_id" "$now_ns" | sha256_hex | awk '{print substr($1,1,16)}')
 
   jq -nc \
     --arg trace "$trace_id" --arg span "$span_id" \