@mmerterden/multi-agent-pipeline 15.13.0 → 15.15.0

package/CHANGELOG.md

@@ -16,6 +16,41 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.15.0] - 2026-08-22
+
+### Added
+- **Graylog has two instances now, because it always did.** Test and production are separate Graylog deployments, and a trx id minted by a tester does not exist in production - so searching production alone answered "no logs" for a complaint that was fully logged one host over, and that answer was indistinguishable from a genuine miss. `hosts.graylogTest` and the optional `keychainMapping.graylog_test` (which falls back to the production key, correct for shared-token deployments) make the second instance addressable. `fetch-graylog.sh --env auto` is the new default: production first, test when production returns nothing or is unreachable. `--env prod` / `--env test` pin one.
+- **The payload names the instance that answered** (`source.environment`, `source.searchedEnvironments[]`), and `/multi-agent:complaint-analysis` now has to cite it. A production complaint corroborated only by test logs is `insufficient-evidence`, not a confirmed `bff` fault, and the old payload gave the triage no way to tell those apart.
+- `/multi-agent:setup` asks for the two things the previous release added a consumer for but no collector: the Graylog test host plus its optional separate token, and `fortify.versionIds`. `versionIds` shipped in 15.14.0 as the only way to resolve an instance-id-only Fortify ticket, and nothing asked for it, so that path silently no-opped for everyone.
+- **`smoke-graylog-environments.sh`**, 15 assertions over the resolution rules that are easy to get subtly wrong: auto stops at production when production answers, falls back on empty AND on unreachable, degrades (never blocks) when both are down, treats a pinned environment with no host as exit 6 rather than silently searching the other one, and lets a 401 on one instance fall through instead of masking a working answer from the other.
+
+### Fixed
+- A pinned `--env` with no configured host now exits 6 naming the exact pref, instead of falling back to whichever host happened to be set. Attaching test logs to a production complaint is worse than attaching none.
+
+### Changed
+- `fetch-graylog.sh` resolves host and token per environment instead of once at the top, and reads prefs through one helper rather than three near-identical inline python blocks.
+
+## [15.14.0] - 2026-08-22
+
+### Added
+- **A release can now be required, not just available.** `/multi-agent:update` stays exactly what it was, and most releases change nothing: the run-start check keeps reading `dist-tags.latest` and keeps asking politely. What is new is a second tag. `npm dist-tag add <pkg>@<version> required` names the oldest version a user may run, and an install below that floor is not behind, it is wrong - it would produce work against a contract that no longer holds, which then has to be redone. Below the floor, Phase 0 Step 0.6 halts: it runs the update flow and stops, and the user re-issues the command on the new version. It does not continue on the freshly updated install, because this run's phase docs, refs and scripts were already loaded from the old one, and that is the drift the floor exists to prevent. Interactive and autopilot behave identically - there is nothing to decide.
+- **`require-supported-version.sh`** turns the signal into an exit code for shell callers: 0 = proceed, 3 = halt, with `force|<local>|<latest>|<required>` on stdout and a human block on stderr. It shares `update-check.sh`'s cache, so a second command inside the TTL window costs no network call.
+
+### Fixed
+- **The Firebase Crashlytics fetcher called an endpoint that does not exist.** It built the app reference by hand as `<platform>:<bundle>` and asked for `/v1alpha/projects/<p>/apps/<ref>/issues/<issueId>`. The appId is opaque (`1:1234567890:ios:abcdef`) and cannot be derived from a bundle, and v1alpha has no get-issue-by-id route, so every fetch failed - and the failure was reported as `api-not-enabled`, which sent anyone debugging it to look at Google's API allowlist instead of at the URL. It now resolves the real appId through the Firebase Management API (`iosApps` / `androidApps`, matching `bundleId` / `packageName`), then reads `reports/topIssues` for the summary and metrics and `events?filter.issue.id=<id>` for the newest event. The payload gains what that event carries and the old shape could not: the full `stackTrace[]`, the breadcrumb and log timeline with screen names, session and occurrence counts, and the console URI. A multi-app project with no bundle match exits 3 as `app-not-found` rather than picking a neighbouring app.
+- **Fortify findings that arrive without a URL are no longer invisible.** A scanner-to-tracker bridge writes the instance id and the `file:line` into the ticket and never writes the SSC link - it knows the id, and the person reading the ticket never needed the URL. The extractor was URL-only, so those tickets produced an empty `contextLinks[]`, Phase 0 skipped the deep fetch, and Phase 4's Fortify gate reported `n/a` on a ticket that exists *because of* a security finding. It now also matches a labelled `Fortify Instance ID` / `issue instance id` / `fortify id` and emits a URL-less entry, the same shape graylog trx ids already used. `fetch-fortify.sh --instance-id <id>` resolves the project version by asking each id in `prefs.global.fortify.versionIds` in order. To stay off prose, the id must be at least 16 characters and contain a digit, and the bare label `instance id` is deliberately not matched.
+- **`prefs.global.fortify` did not exist.** Phase 4 Gate 5 documented `fortify.alwaysCheck` as its opt-in from the day it shipped, but `global` is closed to additional properties and the schema had no `fortify` object, so setting it failed validation - the gate could only ever run off a referenced URL. The object now exists with `alwaysCheck` and `versionIds`.
+- Fortify URLs of the form `/ssc/html/ssc/version/<id>` and `#/version/<id>` now yield a version id. Only the API shape `/projectVersions/<id>` was matched before, so the UI links people actually paste parsed to `projectId: null`.
+
+### Changed
+- `update-check.sh` reads both tags in one call and now uses the abbreviated packument (60 kB instead of 250 kB for the same answer). Its own contract is unchanged and deliberately so: it still always exits 0, still says nothing when the registry is unreachable, and still emits `<local>|<latest>` for a plain update. The floor appends a third field, `force`, which a `cut -f1`/`-f2` reader ignores. The cache file grows a third field too; a two-field cache written by an older install still reads, and its missing floor means "unknown", never "none".
+- **Fail-open, on purpose.** Offline, a blocked registry, an undeterminable local version, a `required` tag published above `latest`, or no tag at all: every one of these exits 0. A version gate that bricks the pipeline on a flaky network is worse than the drift it guards against.
+- **Not opt-out.** `updateCheck.enabled: false` silences the advisory "update available" prompt, which is what it always meant; it does not lift a floor. The single override is the env var `MULTI_AGENT_ALLOW_OUTDATED=1`, which exits 0 with a warning and is logged in the run record, so a broken release cannot strand someone mid-incident. Exempt commands - `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language` - are the remedy or cannot depend on a contract.
+- Phase-doc token budget: total 54050 -> 54400. Compression came first and took the new Step 0.6 prose from 469 tokens to 337, by moving the rationale, the exemption list and the `npm dist-tag add` recipe into `multi-agent-refs/rules.md` "Supported Version Gate" (loaded by 25 commands, outside this budget) and into the script header, leaving the phase doc with the call, the decision table and the halt.
+- `smoke-update-check.sh` grew from 12 to 27 assertions, covering the floor, the clamp, the legacy cache, the wrapper's three exit paths and the doc wiring on both sides.
+- **`smoke-context-links.sh`: the extractor has a behaviour test now.** A 250-line deterministic classifier that every Phase 0 deep fetch dispatches on had no test of its own, so a regression in any pattern would only ever surface as "the ticket had a link and nothing was enriched", with nothing red to point at. 32 assertions over every emitted type, both Fortify entry shapes, dedup, and the two things that must NOT match: prose containing the words, and a bare non-doc URL.
+- `sync/SKILL.md` lost a "Special inputs" table that repeated the argument table from the top of the same file, minus one row.
+
 ## [15.13.0] - 2026-08-22
 
 ### Fixed

package/docs/features.md

@@ -162,7 +162,11 @@ Existing tests are immutable during a task: deleting, renaming, or weakening an
 
 ### Update Check at Run Start
 
-Phase 0 Step 0.6, opt-out via `prefs.global.updateCheck`. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against `dist-tags.latest`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+Phase 0 Step 0.6. Once per `ttlHours` window (cached, 3s-bounded curl to the npm registry), the installed version is compared against two dist-tags.
+
+**`latest` - advisory**, opt-out via `prefs.global.updateCheck.enabled`. Newer version: interactive modes ask "Update now?" (yes runs the `/multi-agent:update` flow, then the run continues); autopilot logs one line and never asks. `autoUpdate: true` updates silently before the worktree exists. Offline and failed checks are silent - never blocks.
+
+**`required` - blocking** (v15.14.0+). Most releases do not publish this tag and nothing changes for them. A release that changed a contract a run depends on is promoted with `npm dist-tag add <pkg>@<version> required`, and an install below that floor is not behind, it is wrong: `require-supported-version.sh` exits 3, the run halts, `/multi-agent:update` runs, and the user re-issues the command on the new version rather than continuing on docs already loaded from the old one. Interactive and autopilot behave identically. The gate fails open on every undeterminable answer (offline, blocked registry, no tag), `updateCheck.enabled: false` does not disable it, and the single override is the env var `MULTI_AGENT_ALLOW_OUTDATED=1`, which is logged in the run record. Exemptions: `update`, `setup`, `uninstall`, `help`, `status`, `log`, `search`, `routines`, `forget`, `language`.
 
 ### Structured Handoff Blocks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.13.0",
+  "version": "15.15.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/complaint-analysis/SKILL.md

@@ -81,12 +81,16 @@ For each complaint with at least one id and `skipGraylog: false`:
 ~/.claude/lib/fetch-graylog.sh --trx <trxId> --conv <convId>   # pass whichever exist
 ```
 
-Record per complaint: `graylog: {status: ok|degraded|skipped, totalResults, degradeReason}` plus the top messages (timestamp, source, level, message excerpt) kept in working context for Phase 2/3. Failure handling:
+Environment defaults to `auto`: production first, the test instance (`hosts.graylogTest`) when production returns nothing or is unreachable. A customer complaint is normally a production event, but a tester-minted id only exists on test, and prod-only search reports "no logs" for both cases identically. When the intake itself says which environment a complaint came from, pin it with `--env prod` / `--env test` rather than letting the fallback decide.
+
+Record per complaint: `graylog: {status: ok|degraded|skipped, environment, totalResults, degradeReason}` plus the top messages (timestamp, source, level, message excerpt) kept in working context for Phase 2/3. Failure handling:
 
 - Exit 0 with `degraded: true` -> `status: degraded`, keep the reason, continue.
 - Exit 2 / 3 / 6 (credential / auth / host) -> per `$HOME/.claude/multi-agent-refs/keychain.md` non-critical rule: warn ONCE (`WARN: Graylog unavailable (<reason>); remaining complaints proceed without log evidence.`), mark this and all remaining fetches `status: degraded`, continue. Never halt (Locked 1).
 - `skipGraylog: true` -> `status: skipped`.
 
+**Always name the environment when citing log evidence.** `source.environment` in the fetcher payload says which instance answered; the same lines mean different things depending on whether a production complaint was corroborated by production logs or only by test ones. A complaint whose only evidence came from test is `insufficient-evidence` for a production claim, not `bff`.
+
 Set `phase: "correlating_repos"`.
 
 ### Phase 2 - Repo evidence correlation (read-only)

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

@@ -107,6 +107,7 @@ These are the RECOMMENDED key names. When creating NEW keys, use these. But exis
 | `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | `figma` + `mcp` |
 | `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
 | `graylog` | `${USER}_Graylog_Access_Token` | `graylog` |
+| `graylog_test` | `${USER}_Graylog_Test_Access_Token` | `graylogTest` |
 | `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
 | `appstore_connect_key_id` | `${USER}_AppStoreConnect_Key_Id` | (`appstore` or `asc` or `app_store`) + (`key` or `keyid`) |
@@ -288,7 +289,7 @@ The Step 2 discovery summary is never the end of setup. Immediately after showin
 Loop rules:
 
 - **One prompt per service.** Never collapse the list into a single "add missing tokens now?" yes/no, and never offer one multi-select covering all services: each service has its own source URL, key name, identity binding and host prompt, so each gets its own Token Save Flow pass.
-- **Each service pass asks, in order: token → author → host.** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog). GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
+- **Each service pass asks, in order: token → author → host.** Step A/B collect the secret, Step C binds the git identity (author)  -  Bitbucket and GitHub included; every saved token gets an author  -  and Step 3.5 asks the host domain inline for hosted services (jira, confluence, bitbucket, fortify, graylog) - plus the Fortify project versions and the optional Graylog test instance. GitHub and Figma skip the host question (fixed domains); `bitbucket_user` skips author binding (username, not a PAT). Never end a service pass with the token saved but the author or a required host unasked.
 - **Skip is per-service.** A Skip answer leaves that service's `keychainMapping` at `null` and the loop continues with the next service. Skips never abort the loop.
 - **`figma` and `figma_mcp` are distinct credentials for distinct tiers  -  ask both.** Skipping the PAT does not imply skipping MCP, and vice versa. The `figma_mcp` pass opens with a Remote / Local mode question instead of a clipboard paste (see "Figma MCP Setup" below): Remote generates a `figu_` OAuth token for the current user, Local wires the PAT-based local server.
 - The loop ends only when every missing service has been asked exactly once; then continue to Step 4 (Verify all).
@@ -440,7 +441,9 @@ Service host  -  needed to build API URLs for this token.
   {Service} host (e.g. jira.example.com): ___
 ```
 
-Save to `prefs.global.hosts.{service}`. For Jira specifically, also ask for the default project key (the token is useless without one for new-issue creation):
+Save to `prefs.global.hosts.{service}`. For Fortify, also ask `Fortify project version ids (optional, comma-separated - e.g. 1234,5678)` → `prefs.global.fortify.versionIds`. A ticket naming only an instance id carries no version, so the lookup silently no-ops without these; URL-referenced findings resolve either way.
+
+For Jira specifically, also ask for the default project key (the token is useless without one for new-issue creation):
 
 ```
 Default Jira project key (e.g. PROJ): ___
@@ -476,6 +479,7 @@ Resulting shape:
       "bitbucket":  "bitbucket.example.com",
       "fortify":    "ssc.example.com",
       "graylog":    "graylog.example.com",
+      "graylogTest": "graylog-test.example.com",
       "corpDomain": "example.com"
     },
     "defaultJiraKey": "PROJ"
@@ -483,9 +487,18 @@ Resulting shape:
 }
 ```
 
-Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_HOST}`, `{GRAYLOG_HOST}`, `{CORP_DOMAIN}`, `{JIRA_KEY}` in skills/commands are resolved from this block at runtime. If a host is ever missing when a phase needs it, Phase 0 prompts the same Host Prompt inline.
+Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_HOST}`, `{GRAYLOG_HOST}`, `{GRAYLOG_TEST_HOST}`, `{CORP_DOMAIN}`, `{JIRA_KEY}` in skills/commands are resolved from this block at runtime. If a host is ever missing when a phase needs it, Phase 0 prompts the same Host Prompt inline.
+
+Graylog uses a **PAT** whose API auth is HTTP Basic with the token as username and the literal `token` as password  -  no separate username entry. It is optional by the null-mapping convention: `keychainMapping.graylog` or `hosts.graylog` left `null` degrades the log fetch to empty and never blocks a run.
+
+Graylog is asked **twice**  -  test and production are separate instances, and a tester-minted trx id does not exist in production. After the production host:
+
+```
+Graylog test host (optional  -  Enter to skip): ___
+Does the test instance use a different token? [y/N]
+```
 
-Graylog uses a **PAT (access token)** whose API auth is HTTP Basic with the token as the username and the literal `token` as the password (`<token>:token`)  -  no separate username entry. Its host prompt behaves exactly like the Jira host prompt (saved to `prefs.global.hosts.graylog`, resolved as `{GRAYLOG_HOST}`). Graylog is **automatically optional / non-blocking** via the null-mapping convention: leaving `keychainMapping.graylog` (and/or `hosts.graylog`) `null` simply means the log-fetch adapter degrades to empty and never blocks a run  -  no extra setup code.
+Test host → `hosts.graylogTest` (`{GRAYLOG_TEST_HOST}`); skipped means production-only search, which degrades nothing. Yes to the token question runs one more Token Save Flow pass for `graylog_test`; no (default) leaves it null and the fetcher reuses the production key. Run-time order is `--env auto`: production first, test on empty or unreachable, and the payload names which answered.
 
 **Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
 
@@ -706,7 +719,8 @@ Standard key names (used when creating NEW tokens). Discovery may find existing
 | `figma` | `${USER}_Figma_Access_Token` | PAT (Tier 2, REST API) | Figma Developer Settings (max 90 days). Token Save Flow prompt copy: "Figma Personal Access Token (for Tier 2)". |
 | `figma_mcp` | `${USER}_Figma_Mcp_Access_Token` | OAuth (Tier 1, MCP) | Automatic via Claude Code Figma MCP remote auth. Token Save Flow prompt copy: "Figma MCP token (for Tier 1)". |
 | `fortify` | `${USER}_Fortify_Access_Token` | API Token | Fortify SSC -> Token Management (VPN required) |
-| `graylog` | `${USER}_Graylog_Access_Token` | PAT (API Basic `<token>:token`) | Graylog -> System -> Users and Teams -> Edit Tokens (VPN required). Auth is HTTP Basic with the token as username and literal `token` as password. |
+| `graylog` | `${USER}_Graylog_Access_Token` | PAT (API Basic `<token>:token`) | Graylog -> System -> Users and Teams -> Edit Tokens (VPN required) |
+| `graylog_test` | `${USER}_Graylog_Test_Access_Token` | same | Same page on the TEST instance; optional |
 | `firebase` | `${USER}_Firebase_Access_Json` | Firebase JSON (base64) | Firebase Console -> Project settings -> Service accounts -> Generate new private key. Project id is parsed from the decoded JSON  -  no separate entry. |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | API Token | Jenkins -> User -> Configure -> API Token |
 |  -  | Git Identities | JSON (preferences) | Stored in `$HOME/.claude/multi-agent-preferences.json`  -  not Keychain |

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

@@ -72,15 +72,6 @@ Step 6: Report      Summary: synced targets, platform, changed files, deploy sta
 
 If nothing is stale → report "All targets up to date" and stop.
 
-## Special inputs
-
-| Input | Behaviour |
-|-------|----------|
-| (no args) | Full ecosystem sync (default) |
-| `release` | Full sync + version bump + tag + npm publish + website deploy |
-| `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
-| `"change description"` | Apply the description to EVERY target at once |
-
 ---
 
 ## Sync rules
@@ -427,6 +418,8 @@ npm publish --userconfig "$NPMRC"
 
 Verify the publish landed: on GitHub Packages `npm view <package> version --userconfig "$NPMRC"`; on npmjs read the registry directly (`curl -s https://registry.npmjs.org/<package>/latest`) rather than `npm view`, which can answer from a stale cache.
 
+**Required release** (optional; ask first even in `release` mode, it halts every older install): `npm dist-tag add "$(node -p "require('./package.json').name")@$VER" required --userconfig "$NPMRC"`. Out of band, so promote or demote any time. Contract: `multi-agent-refs/rules.md` "Supported Version Gate".
+
 **Approval**: outside autopilot and outside `release`, ask before shipping.
 
 > "multi-agent-toolkit moved (N changed files, M unpushed commits, v$VER). What should I do?"

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

@@ -25,9 +25,17 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
      echo "Registry unreachable ($REG) - check your network and retry."
      exit 1
    fi
-   echo "Current: v$CUR   Latest: v$LATEST"
+   # dist-tags.required is the supported-version floor (absent on most releases).
+   REQUIRED=$(curl -fsS -H 'Accept: application/vnd.npm.install-v1+json' \
+     "$REG/$(printf '%s' "$PKG" | sed 's|/|%2F|')" \
+     | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8"))["dist-tags"].required || ""' 2>/dev/null)
+   echo "Current: v$CUR   Latest: v$LATEST${REQUIRED:+   Required floor: v$REQUIRED}"
    ```
 
+   This command is never blocked by the floor  -  it is the remedy for it. The
+   line above is where the floor is reported, so the user sees why a run halted;
+   `$REQUIRED` does not survive into the later shell blocks.
+
 2. **Stop early when already current** (still refresh the marketplace, step 4b):
    ```bash
    [ "$CUR" = "$LATEST" ] && echo "✓ Already up to date: v$LATEST"

package/pipeline/lib/context-link-extractor.sh

@@ -10,7 +10,8 @@
 #   - swagger     : OpenAPI / Swagger JSON or YAML spec URLs
 #   - confluence  : Confluence pages (host pattern + display/spaces/pageId)
 #   - crashlytics : Firebase Crashlytics issue/session URLs
-#   - fortify     : Fortify SSC findings URLs
+#   - fortify     : Fortify SSC finding URLs, and (URL-less, like graylog)
+#                   labelled issue instance ids  -  "Fortify Instance ID: <id>"
 #   - graylog     : Graylog trx-id / conversation-id references. Unlike the
 #                   others this is matched from free text (labels like "trx",
 #                   "trxid", "transaction id", "conversationId", "convId",
@@ -31,7 +32,7 @@
 #     { "type": "confluence", "url": "...", "metadata": { "host": "...", "pageId": "...|null", "spaceKey": "...|null" } },
 #     { "type": "swagger",    "url": "...", "metadata": { "format": "json|yaml|unknown" } },
 #     { "type": "crashlytics","url": "...", "metadata": { "projectId": "...", "platform": "ios|android", "issueId": "...", "sessionId": "...|null" } },
-#     { "type": "fortify",    "url": "...", "metadata": { "host": "...", "projectId": "...|null" } },
+#     { "type": "fortify",    "url": "...|null", "metadata": { "host": "...|null", "versionId": "...|null", "instanceId": "...|null", "source": "url|label" } },
 #     { "type": "graylog",    "url": null,  "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
 #     { "type": "figma",      "url": "...", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "...|null" } },
 #     ...
@@ -155,11 +156,18 @@ def classify(url: str):
     #   https://<ssc-host>/ssc/html/ssc/...
     #   https://<ssc-host>/ssc/api/v1/projectVersions/<id>/...
     if "fortify" in host or "/ssc/" in path or "/api/v1/projectVersions/" in path:
-        project_id = None
-        m = re.search(r"/projectVersions/(?P<id>\d+)", path)
-        if m:
-            project_id = m.group("id")
-        return ("fortify", {"host": host, "projectId": project_id})
+        # The SSC UI keeps the version id in the fragment on some deployments
+        # and in the path on others; search both.
+        where = path + ("#" + parsed.fragment if parsed.fragment else "")
+        m = re.search(r"/(?:projectVersions|version)/(?P<id>\d+)", where)
+        version_id = m.group("id") if m else None
+        m2 = re.search(r"/fix/(?P<inst>[A-Za-z0-9_-]{8,})", where)
+        return ("fortify", {
+            "host": host,
+            "versionId": version_id,
+            "instanceId": m2.group("inst") if m2 else None,
+            "source": "url",
+        })
 
     # --- Generic doc fallbacks ---------------------------------------------
     # Notion, Google Docs, GitHub markdown blob/wiki, gists. Useful as
@@ -228,5 +236,45 @@ for m in GRAYLOG_RE.finditer(text):
         "metadata": {"idType": id_type, "id": gid, "label": label},
     })
 
+# --- Fortify issue instance ids (label-based, not URL) ---------------------
+# A finding often arrives as a ticket written by a scanner-to-tracker bridge,
+# which quotes the instance id and the file:line but no SSC deep link  -  the
+# bridge knows the id, the reader does not need the URL, and the pipeline then
+# saw nothing to enrich. Same shape as the graylog entries: "url": null, the id
+# in metadata. Resolution to a project version happens in fetch-fortify.sh,
+# which is where the prefs live.
+FORTIFY_ID_RE = re.compile(
+    r"(?P<label>"
+    r"fortify[\s_-]*instance[\s_-]*id"
+    r"|issue[\s_-]*instance[\s_-]*id"
+    r"|fortify[\s_-]*id"
+    r")"
+    r"[\s*_~`]*[:=#]?[\s*_~`]*"
+    r"[\"']?(?P<id>(?=[A-Za-z0-9._-]*[0-9])[A-Za-z0-9][A-Za-z0-9._-]{15,})",
+    re.IGNORECASE,
+)
+already_linked = {
+    e["metadata"].get("instanceId")
+    for e in out
+    if e["type"] == "fortify" and e["metadata"].get("instanceId")
+}
+for m in FORTIFY_ID_RE.finditer(text):
+    fid = m.group("id").rstrip(".,;:!?)")
+    key = ("fortify", fid)
+    if not fid or key in seen or fid in already_linked:
+        continue
+    seen.add(key)
+    out.append({
+        "type": "fortify",
+        "url": None,
+        "metadata": {
+            "host": None,
+            "versionId": None,
+            "instanceId": fid,
+            "source": "label",
+            "label": m.group("label"),
+        },
+    })
+
 print(json.dumps(out))
 PY

package/pipeline/lib/fetch-crashlytics.sh

@@ -19,16 +19,21 @@
 # Output (stdout, single JSON object):
 #   {
 #     "fetchedAt": "<ISO8601>",
-#     "source": { "url": "<url|null>", "projectId": "...", "platform": "ios|android",
-#                 "bundle": "...", "issueId": "...", "sessionId": "<id|null>" },
-#     "issue": { "title": "...", "subtitle": "...", "type": "fatal|nonFatal|ANR",
-#                "occurrences": <n>, "impactedUsers": <n>,
-#                "firstSeen": "<ISO8601>", "lastSeen": "<ISO8601>",
-#                "topStackFrame": { "file": "...", "line": <n>, "symbol": "..." },
+#     "source": { "url": "<url|null>", "projectId": "...", "appId": "<resolved|null>",
+#                 "platform": "ios|android", "bundle": "...", "issueId": "...",
+#                 "sessionId": "<id|null>" },
+#     "issue": { "title": "...", "subtitle": "...", "type": "FATAL|NON_FATAL|ANR",
+#                "state": "...", "consoleUri": "<url|null>",
+#                "occurrences": <n>, "impactedUsers": <n>, "sessions": <n>,
+#                "firstSeenVersion": "<v|null>", "lastSeenVersion": "<v|null>",
+#                "topStackFrame": { "file": "<library>", "line": 0, "symbol": "..." },
+#                "stackTrace": [ { "library": "...", "symbol": "..." }, ... ],
 #                "topDevices": [ "<name>", ... ],
 #                "topOS": [ "<version>", ... ],
 #                "affectedAppVersions": [ "<version>", ... ] },
-#     "session": null | { "id": "...", "events": [ { "type": "...", "time": "...", "summary": "..." } ] }
+#     "session": null | { "id": "<eventId>", "time": "<ISO8601>",
+#                         "events": [ { "type": "breadcrumb|log", "time": "...",
+#                                       "summary": "...", "screen": "<name|null>" } ] }
 #   }
 #
 # Exit codes:
@@ -39,11 +44,13 @@
 #   5  project mismatch  -  SA JSON project_id != URL project (configuration bug)
 #
 # Notes:
-#   The Firebase Crashlytics REST surface (`firebasecrashlytics.googleapis.com`)
-#   is currently invitation-only in some regions. When the API returns 404 for
-#   a valid project the script exits 3 with reason "api-not-enabled"; the
-#   orchestrator surfaces this as "fetcher unavailable, advisory only" to
-#   keep the pipeline moving.
+#   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`
+#   for the stack trace, device, OS and breadcrumbs. The opaque appId is resolved
+#   first through the Firebase Management API (`iosApps` / `androidApps`), since a
+#   console URL only ever carries the bundle id. Any failure exits 3 with a reason
+#   ("app-not-found", "crashlytics-unreachable"); the orchestrator surfaces that as
+#   "fetcher unavailable, advisory only" and keeps the pipeline moving.
 
 set -euo pipefail
 
@@ -279,80 +286,183 @@ fi
 # never appears in argv (argv is visible to ps).
 crashlytics_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$ACCESS_TOKEN"; }
 
-# Construct the appId in the form Firebase expects:
-#   ios:   ios:<bundleId>   →  api: /projects/<n>/apps/<bundleId> (looked up via list)
-#   android: android:<package>
-# In practice the appId is opaque (1:1234567890:ios:abcdef). We try the
-# Crashlytics v1alpha endpoint with the bundle as a fallback "app"  -  the API
-# accepts the package/bundle when scoped to the project.
-APP_REF="$PLATFORM:$BUNDLE"
-ISSUE_URL_API="https://firebasecrashlytics.googleapis.com/v1alpha/projects/$PROJECT_ID/apps/$APP_REF/issues/$ISSUE_ID"
-
-ISSUE_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
-  -K <(crashlytics_auth_cfg) -H "Accept: application/json" \
-  "$ISSUE_URL_API" 2>/dev/null || true)
-
-if [ -z "$ISSUE_JSON" ]; then
-  printf '{"status":"failed","reason":"api-not-enabled-or-app-mismatch","appRef":"%s","issueId":"%s"}\n' "$APP_REF" "$ISSUE_ID" >&2
+fb_get() {
+  curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
+    -K <(crashlytics_auth_cfg) -H "Accept: application/json" "$1" 2>/dev/null || true
+}
+
+# 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.
+FB_MGMT="https://firebase.googleapis.com/v1beta1/projects/$PROJECT_ID"
+if [ "$PLATFORM" = "ios" ]; then
+  APPS_JSON=$(fb_get "$FB_MGMT/iosApps?pageSize=200")
+  MATCH_FIELD="bundleId"
+else
+  APPS_JSON=$(fb_get "$FB_MGMT/androidApps?pageSize=200")
+  MATCH_FIELD="packageName"
+fi
+
+APP_ID=$(APPS_IN="$APPS_JSON" WANT="$BUNDLE" FIELD="$MATCH_FIELD" python3 -c "
+import json, os
+try:
+    apps = (json.loads(os.environ['APPS_IN'] or '{}').get('apps') or [])
+except Exception:
+    apps = []
+want = (os.environ['WANT'] or '').lower()
+field = os.environ['FIELD']
+for a in apps:
+    if str(a.get(field) or '').lower() == want:
+        print(a.get('appId') or '')
+        break
+else:
+    # A single-app project needs no disambiguation; anything else stays unresolved
+    # rather than guessing at the wrong app.
+    print(apps[0].get('appId') or '' if len(apps) == 1 else '')
+" 2>/dev/null || true)
+
+if [ -z "$APP_ID" ]; then
+  printf '{"status":"failed","reason":"app-not-found","platform":"%s","bundle":"%s","projectId":"%s"}\n' \
+    "$PLATFORM" "$BUNDLE" "$PROJECT_ID" >&2
   exit 3
 fi
 
-SESSION_JSON=""
-if [ -n "$SESSION_ID" ]; then
-  SESSION_URL_API="$ISSUE_URL_API/sessions/$SESSION_ID"
-  SESSION_JSON=$(curl -sS --fail --max-time "$TIMEOUT" --connect-timeout 5 \
-    -K <(crashlytics_auth_cfg) -H "Accept: application/json" \
-    "$SESSION_URL_API" 2>/dev/null || true)
+CRASHLYTICS_APP="https://firebasecrashlytics.googleapis.com/v1alpha/projects/$PROJECT_ID/apps/$APP_ID"
+
+# There is no get-issue-by-id endpoint on v1alpha. The issue summary comes from
+# the topIssues report (filtered to the id we want) and the stack trace, device,
+# OS and breadcrumbs come from the issue's most recent event. An earlier version
+# of this script called /issues/<id> with a guessed "<platform>:<bundle>" app
+# reference; neither the path nor the reference exists, so every fetch failed and
+# reported it as "api-not-enabled".
+#
+# Two partial answers are treated as answers, not failures. A long-tail issue
+# outside the top 200 leaves the summary empty and the event still carries the
+# stack trace, and an event fetch that comes back empty still leaves the summary.
+# Only both being empty is a failure. A URL naming a specific session gets that
+# issue's most recent event instead: v1alpha exposes no per-session read, and
+# `source.sessionId` is passed through so the caller can see what was asked for.
+ISSUE_ID_ENC=$(ISSUE_IN="$ISSUE_ID" python3 -c "
+import os, urllib.parse
+print(urllib.parse.quote(os.environ['ISSUE_IN'], safe=''))
+" 2>/dev/null || printf '%s' "$ISSUE_ID")
+TOP_ISSUES_JSON=$(fb_get "$CRASHLYTICS_APP/reports/topIssues?pageSize=200")
+EVENT_JSON=$(fb_get "$CRASHLYTICS_APP/events?filter.issue.id=$ISSUE_ID_ENC&pageSize=1")
+
+if [ -z "$TOP_ISSUES_JSON" ] && [ -z "$EVENT_JSON" ]; then
+  printf '{"status":"failed","reason":"crashlytics-unreachable","appId":"%s","issueId":"%s"}\n' "$APP_ID" "$ISSUE_ID" >&2
+  exit 3
 fi
 
+ISSUE_JSON="$TOP_ISSUES_JSON"
+SESSION_JSON="$EVENT_JSON"
+
 SRC_URL="$URL" SRC_PROJECT="$PROJECT_ID" SRC_PLATFORM="$PLATFORM" SRC_BUNDLE="$BUNDLE" \
-SRC_ISSUE="$ISSUE_ID" SRC_SESSION="$SESSION_ID" \
+SRC_ISSUE="$ISSUE_ID" SRC_SESSION="$SESSION_ID" SRC_APPID="$APP_ID" \
 ISSUE_JSON_IN="$ISSUE_JSON" SESSION_JSON_IN="$SESSION_JSON" \
 python3 - <<'PY'
 import json, os, datetime
 
-issue = json.loads(os.environ["ISSUE_JSON_IN"] or "{}")
-session_raw = os.environ.get("SESSION_JSON_IN") or ""
-session = json.loads(session_raw) if session_raw else None
+def load(name):
+    raw = os.environ.get(name) or ""
+    try:
+        return json.loads(raw) if raw else {}
+    except Exception:
+        return {}
+
+issue_id = os.environ["SRC_ISSUE"]
+
+# topIssues returns groups: {"issue": {...}, "metrics": [{...}]}. Find ours.
+groups = load("ISSUE_JSON_IN").get("topIssues") or load("ISSUE_JSON_IN").get("issues") or []
+group = {}
+for g in groups:
+    if str(((g or {}).get("issue") or {}).get("id") or "") == issue_id:
+        group = g
+        break
+issue = (group.get("issue") or {}) if isinstance(group, dict) else {}
+metrics_list = (group.get("metrics") or []) if isinstance(group, dict) else []
+metrics = metrics_list[0] if metrics_list else {}
+
+def count(value):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+events_body = load("SESSION_JSON_IN")
+events = events_body.get("events") or events_body.get("errorEvents") or []
+event = events[0] if events else {}
+
+exceptions = event.get("exceptions") or []
+top_exception = exceptions[0] if exceptions else {}
+frames = top_exception.get("frames") or []
+top_frame = frames[0] if frames else {}
+
+# v1alpha frames carry library + symbol, not file + line. Keeping the documented
+# key names with the library in "file" beats inventing a second shape for the
+# one consumer (Phase 1 prompt injection) that reads them.
+stack = [
+    {"library": f.get("library") or "", "symbol": f.get("symbol") or f.get("rawSymbol") or ""}
+    for f in frames[:40]
+]
+
+versions = []
+for v in (issue.get("firstSeenVersion"), issue.get("lastSeenVersion"),
+          ((event.get("version") or {}).get("displayName"))):
+    if v and v not in versions:
+        versions.append(v)
 
-def first(d, *keys, default=None):
-    for k in keys:
-        if isinstance(d, dict) and k in d:
-            return d[k]
-    return default
+timeline = []
+for crumb in (event.get("breadcrumbs") or [])[:25]:
+    screen = ((crumb.get("params") or {}).get("firebase_screen_class")) or None
+    timeline.append({
+        "type": "breadcrumb",
+        "time": crumb.get("eventTime") or "",
+        "summary": crumb.get("title") or "",
+        "screen": screen,
+    })
+for log in (event.get("logs") or [])[:25]:
+    message = log.get("message") or ""
+    if message:
+        timeline.append({"type": "log", "time": "", "summary": message, "screen": None})
 
-top_frame_raw = first(issue, "topFrame", "frame", default={}) or {}
 result = {
-    "fetchedAt": datetime.datetime.utcnow().isoformat() + "Z",
+    "fetchedAt": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
     "source": {
         "url": os.environ.get("SRC_URL") or None,
         "projectId": os.environ["SRC_PROJECT"],
+        "appId": os.environ.get("SRC_APPID") or None,
         "platform": os.environ["SRC_PLATFORM"],
         "bundle": os.environ["SRC_BUNDLE"],
-        "issueId": os.environ["SRC_ISSUE"],
+        "issueId": issue_id,
         "sessionId": os.environ.get("SRC_SESSION") or None,
     },
     "issue": {
-        "title": first(issue, "title", "errorTitle", "subtitle", default=""),
-        "subtitle": first(issue, "subtitle", "errorMessage", default=""),
-        "type": first(issue, "type", "errorType", default="unknown"),
-        "occurrences": first(issue, "occurrences", "eventCount", default=0),
-        "impactedUsers": first(issue, "impactedUsers", "userCount", default=0),
-        "firstSeen": first(issue, "firstSeen", "createTime", default=None),
-        "lastSeen": first(issue, "lastSeen", "updateTime", default=None),
+        "title": issue.get("title") or top_exception.get("title") or "",
+        "subtitle": issue.get("subtitle") or "",
+        "type": issue.get("errorType") or "unknown",
+        "state": issue.get("state") or "",
+        "consoleUri": issue.get("uri") or None,
+        "occurrences": count(metrics.get("eventsCount")),
+        "impactedUsers": count(metrics.get("impactedUsersCount")),
+        "sessions": count(metrics.get("sessionsCount")),
+        "firstSeenVersion": issue.get("firstSeenVersion") or None,
+        "lastSeenVersion": issue.get("lastSeenVersion") or None,
         "topStackFrame": {
-            "file": first(top_frame_raw, "fileName", "file", default=""),
-            "line": first(top_frame_raw, "lineNumber", "line", default=0),
-            "symbol": first(top_frame_raw, "symbol", "function", default=""),
+            "file": top_frame.get("library") or "",
+            "line": 0,
+            "symbol": top_frame.get("symbol") or top_frame.get("rawSymbol") or "",
         },
-        "topDevices": (issue.get("topDevices") or [])[:5],
-        "topOS": (issue.get("topOperatingSystems") or issue.get("topOS") or [])[:5],
-        "affectedAppVersions": (issue.get("affectedVersions") or issue.get("appVersions") or [])[:5],
+        "stackTrace": stack,
+        "topDevices": [d for d in [((event.get("device") or {}).get("displayName"))] if d],
+        "topOS": [o for o in [((event.get("operatingSystem") or {}).get("displayName"))] if o],
+        "affectedAppVersions": versions,
     },
     "session": ({
-        "id": os.environ.get("SRC_SESSION") or "",
-        "events": (session.get("events") if isinstance(session, dict) else None) or [],
-    } if session else None),
+        "id": event.get("eventId") or os.environ.get("SRC_SESSION") or "",
+        "time": event.get("eventTime") or "",
+        "events": timeline,
+    } if event else None),
 }
 print(json.dumps(result, ensure_ascii=False))
 PY