@mmerterden/multi-agent-pipeline 12.1.1 → 12.2.0

package/CHANGELOG.md

@@ -14,6 +14,14 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
+## [12.2.0] - 2026-07-21
+
+### Added
+- **Graylog log-fetch integration** — when a task's ticket/issue carries a transaction id (`trx`/`trxId`/`transaction id`) and/or a conversation id (`conversationId`/`convId`/`X-conversationId`), the pipeline fetches the matching Graylog log messages and injects them as advisory diagnostic context into Phase 1 analysis. Mirrors the Crashlytics analysis-context adapter (advisory only, no Phase-4 gate).
+  - New `lib/fetch-graylog.sh` adapter (mirrors the Fortify hosted-service shape): host from `prefs.global.hosts.graylog` (+ `GRAYLOG_HOST_OVERRIDE`), token via `prefs.global.keychainMapping.graylog` → `${USER}_Graylog_Access_Token` through the credential-store resolver. Graylog PAT auth is HTTP Basic `<token>:token` delivered only via a `curl -K` process-substitution config (never on argv). Universal/relative search by full-text OR of the ids, range + limit configurable via env.
+  - **Non-blocking by design:** any network/VPN failure degrades to an empty normalized result and exit 0 — a log fetch never blocks a run. Exit codes: 0 ok/degraded, 2 missing-token, 3 genuine auth rejection, 4 usage, 6 host-not-configured.
+  - Config surface: `graylog` added to `keychainMapping` + `hosts` in `schemas/prefs.schema.json` and `preferences-template.json`; keychain doc row (non-critical service). Extraction branch added to `lib/context-link-extractor.sh`. Phase-0 deep-fetch step (`state.graylogContext`) + Phase-1 dispatch row + external-context-injection dispatch row. `multi-agent:setup` prompts for the Graylog host (like the Jira host) and discovers the token key. Offline smoke coverage in `scripts/smoke-fetchers-offline.sh`.
+
 ## [12.1.1] - 2026-07-21
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "12.1.1",
+  "version": "12.2.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code and Copilot 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/setup/SKILL.md

@@ -99,6 +99,7 @@ These are the RECOMMENDED key names. When creating NEW keys, use these. But exis
 
 > Multi-agent setup onboards **both** Figma tokens because the pipeline's 3-tier Figma access chain (see `pipeline/rules/figma-pipeline.md`) uses them in priority order: Tier 1 = MCP (`figma_mcp`), Tier 2 = REST PAT (`figma_pat`), Tier 3 = user screenshot fallback. Missing either token forces a downshift; missing both leaves Tier 3 as the only path.
 | `fortify` | `${USER}_Fortify_Access_Token` | `fortify` |
+| `graylog` | `${USER}_Graylog_Access_Token` | `graylog` |
 | `firebase` | `${USER}_Firebase_Access_Json` | `firebase` (any variant: `sa`, `service`, `account`, `access`, `json`) |
 | `jenkins` | `${USER}_Jenkins_Access_Token` | `jenkins` |
 
@@ -180,6 +181,7 @@ Save the resolved mapping to preferences:
       "figma_pat": "${USER}_Figma_Access_Token",
       "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
       "fortify": null,
+      "graylog": null,
       "firebase": "${USER}_Firebase_Access_Json",
       "jenkins": null
     }
@@ -331,7 +333,7 @@ Update `prefs.global.keychainMapping.{service}` with the key name.
 Update `identity.servicePatMap.{service}` with the key name.
 Update `serviceStatus.{service} = { ok: true, checkedAt: <now> }`.
 
-**→ Next: if `{service}` is `jira` / `confluence` / `bitbucket` / `fortify` AND the corresponding
+**→ Next: if `{service}` is `jira` / `confluence` / `bitbucket` / `fortify` / `graylog` AND the corresponding
 `prefs.global.hosts.{service}` is unset, run Step 3.5 (Host Prompt) inline before
 the Auto-routing rule below. required  -  the pipeline cannot build API URLs without
 the host. Firebase is skipped here (host is always `console.firebase.google.com` /
@@ -352,7 +354,7 @@ This builds `platformIdentityRouting` incrementally  -  no separate Step 7 neede
 
 ### Step 3.5  -  Host Prompt (embedded in Token Save Flow)
 
-**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.
+**Not a standalone step**  -  runs inline at the end of the Token Save Flow whenever the saved token belongs to a **hosted service** (Jira, Confluence, Bitbucket, Fortify, Graylog) AND the host is not yet in `prefs.global.hosts`. Firebase tokens skip this step  -  Crashlytics is always on Google's fixed domains and `project_id` is embedded in the SA JSON.
 
 Right after Step D (identity mapping confirmed), ask:
 
@@ -380,6 +382,7 @@ Resulting shape:
       "confluence": "confluence.example.com",
       "bitbucket":  "bitbucket.example.com",
       "fortify":    "ssc.example.com",
+      "graylog":    "graylog.example.com",
       "corpDomain": "example.com"
     },
     "defaultJiraKey": "PROJ"
@@ -387,7 +390,9 @@ Resulting shape:
 }
 ```
 
-Placeholders `{JIRA_HOST}`, `{CONFLUENCE_HOST}`, `{BITBUCKET_HOST}`, `{FORTIFY_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}`, `{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 (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.
 
 **Re-run / update**: `/multi-agent:setup hosts` re-opens the prompt to edit values without touching tokens.
 
@@ -706,6 +711,7 @@ Standard key names (used when creating NEW tokens). Discovery may find existing
 | `figma_pat` | `${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. |
 | `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/lib/context-link-extractor.sh

@@ -11,6 +11,12 @@
 #   - confluence  : Confluence pages (host pattern + display/spaces/pageId)
 #   - crashlytics : Firebase Crashlytics issue/session URLs
 #   - fortify     : Fortify SSC findings URLs
+#   - graylog     : Graylog trx-id / conversation-id references. Unlike the
+#                   others this is matched from free text (labels like "trx",
+#                   "trxid", "transaction id", "conversationId", "convId",
+#                   "X-conversationId" followed by an id) rather than a URL, so
+#                   its entries carry "url": null. Advisory diagnostic context;
+#                   pattern-based + tolerant, a project may refine the labels.
 #   - figma       : Figma design / make / FigJam / slides URLs
 #   - generic-doc : http(s) URLs that didn't match a more specific type but
 #                   look like documentation (Notion, Google Docs, GitHub
@@ -26,6 +32,7 @@
 #     { "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": "graylog",    "url": null,  "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
 #     { "type": "figma",      "url": "...", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "...|null" } },
 #     ...
 #   ]
@@ -188,5 +195,38 @@ for url in RAW_URLS:
     seen.add(key)
     out.append({"type": typ, "url": url, "metadata": meta})
 
+# --- Graylog trx / conversation ids (label-based, not URL) -----------------
+# Recognise free-text references like "trxId: ABC123", "transaction id = ...",
+# "conversationId ...", "X-conversationId: ...". Pattern-based + tolerant  -  a
+# project can refine the label set. Longer/more-specific labels lead the
+# alternation so "trxid" is not shadowed by "trx". The id is alphanumeric plus
+# ._- and long enough (>= 6 chars) to avoid catching stray words.
+GRAYLOG_RE = re.compile(
+    r"(?P<label>"
+    r"x[\s_-]*conversation[\s_-]*id"
+    r"|conversation[\s_-]*id"
+    r"|conv[\s_-]*id"
+    r"|transaction[\s_-]*id"
+    r"|trx[\s_-]*id"
+    r"|trx"
+    r")"
+    r"\s*[:=#]?\s*"
+    r"[\"']?(?P<id>[A-Za-z0-9][A-Za-z0-9._-]{5,})",
+    re.IGNORECASE,
+)
+for m in GRAYLOG_RE.finditer(text):
+    gid = m.group("id").rstrip(".,;:!?)")
+    label = m.group("label")
+    id_type = "conversation" if "conv" in label.lower() else "trx"
+    key = ("graylog", gid)
+    if not gid or key in seen:
+        continue
+    seen.add(key)
+    out.append({
+        "type": "graylog",
+        "url": None,
+        "metadata": {"idType": id_type, "id": gid, "label": label},
+    })
+
 print(json.dumps(out))
 PY

package/pipeline/lib/fetch-graylog.sh

@@ -0,0 +1,233 @@
+#!/bin/bash
+#
+# fetch-graylog.sh
+# Query a Graylog instance for the log messages tied to a transaction or
+# conversation id and emit a normalized JSON view the pipeline can attach as
+# analysis context. A log fetch must never block a run: on any network failure
+# (VPN down, host unreachable) the fetcher degrades to an empty result and
+# exits 0.
+#
+# Input forms (at least one id is required):
+#   ./fetch-graylog.sh --trx <transaction-id>
+#   ./fetch-graylog.sh --conv <conversation-id>
+#   ./fetch-graylog.sh --trx <id> --conv <id>
+#
+# Required configuration:
+#   prefs.global.hosts.graylog            -  Graylog host (e.g. logs.example.com)
+#   prefs.global.keychainMapping.graylog  -  keychain key holding the API token
+#
+# Optional env:
+#   GRAYLOG_TIMEOUT_SECONDS    default 25
+#   GRAYLOG_HOST_OVERRIDE      forces the host (used by tests and CI dry-runs)
+#   GRAYLOG_RANGE_SECONDS      relative search window, default 86400 (24h)
+#   GRAYLOG_LIMIT              max messages to return, default 200
+#
+# Auth: Graylog personal access tokens authenticate as HTTP Basic with the
+# token as the username and the literal string "token" as the password. The
+# credential travels through a curl config via process substitution so it
+# never appears in argv (argv is visible to ps).
+#
+# Output (stdout, single JSON object):
+#   {
+#     "fetchedAt": "<ISO8601>",
+#     "source": { "host": "<host>", "transactionId": "..."|null,
+#                 "conversationId": "..."|null, "query": "..." },
+#     "totalResults": <n>,
+#     "messages": [
+#       { "timestamp": "...", "source": "...", "level": <n>|null,
+#         "message": "...", "fields": { ... } }
+#     ],
+#     "degraded": <bool>, "degradeReason": "..."|null
+#   }
+#
+# Exit codes:
+#   0  success, or degraded-empty on a network failure (never blocks a run)
+#   2  missing/expired credential (orchestrator handles the Save Flow)
+#   3  auth rejected on a reachable host (4xx)
+#   4  bad usage
+#   6  host not configured (prefs.global.hosts.graylog is empty)
+
+set -eu
+
+TRX_ID=""
+CONV_ID=""
+TIMEOUT="${GRAYLOG_TIMEOUT_SECONDS:-25}"
+RANGE="${GRAYLOG_RANGE_SECONDS:-86400}"
+LIMIT="${GRAYLOG_LIMIT:-200}"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --trx)  TRX_ID="$2";  shift 2 ;;
+    --conv) CONV_ID="$2"; shift 2 ;;
+    -h|--help)
+      echo "usage: $0 --trx <transaction-id> | --conv <conversation-id>" >&2
+      exit 4 ;;
+    *)
+      echo "ERR: unexpected arg $1" >&2; exit 4 ;;
+  esac
+done
+
+# Host comes from prefs (private config); skill templates only show {GRAYLOG_HOST}.
+PREFS="$HOME/.claude/multi-agent-preferences.json"
+HOST="${GRAYLOG_HOST_OVERRIDE:-}"
+if [ -z "$HOST" ] && [ -f "$PREFS" ]; then
+  HOST=$(python3 -c "
+import json
+try:
+    p = json.load(open('$PREFS'))
+    print(p.get('global', {}).get('hosts', {}).get('graylog') or '')
+except Exception:
+    print('')
+")
+fi
+if [ -z "$HOST" ]; then
+  printf '%s\n' '{"status":"blocked","reason":"host-not-configured","service":"graylog","expected_pref":"global.hosts.graylog"}' >&2
+  exit 6
+fi
+HOST=${HOST%/}  # strip trailing slash if any
+
+if [ -z "$TRX_ID" ] && [ -z "$CONV_ID" ]; then
+  echo "ERR: no id (pass --trx <transaction-id> and/or --conv <conversation-id>)" >&2
+  exit 4
+fi
+
+# Build the Graylog query from whichever ids were supplied.
+QUERY=""
+if [ -n "$TRX_ID" ]; then
+  QUERY="transactionId:\"$TRX_ID\""
+fi
+if [ -n "$CONV_ID" ]; then
+  if [ -n "$QUERY" ]; then
+    QUERY="$QUERY OR conversationId:\"$CONV_ID\""
+  else
+    QUERY="conversationId:\"$CONV_ID\""
+  fi
+fi
+
+# Token via keychain mapping.
+TOKEN_KEY=""
+if [ -f "$PREFS" ]; then
+  TOKEN_KEY=$(python3 -c "
+import json
+try:
+    p = json.load(open('$PREFS'))
+    print(p.get('global', {}).get('keychainMapping', {}).get('graylog') or '')
+except Exception:
+    print('')
+")
+fi
+[ -z "$TOKEN_KEY" ] && TOKEN_KEY="${USER}_Graylog_Access_Token"
+
+# 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 \
+  || { printf '%s\n' '{"status":"blocked","reason":"missing-credential-helper","service":"graylog","expected_key":"'"$TOKEN_KEY"'"}' >&2; exit 2; }
+
+TOKEN=$("$CRED_STORE" get "$TOKEN_KEY" 2>/dev/null || true)
+if [ -z "$TOKEN" ]; then
+  printf '%s\n' '{"status":"blocked","reason":"missing-token","service":"graylog","expected_key":"'"$TOKEN_KEY"'"}' >&2
+  exit 2
+fi
+
+API_BASE="https://$HOST/api"
+
+graylog_get() {
+  # Usage: graylog_get <path-and-query-relative-to-API_BASE>
+  # Prints "<body>\n<http_code>"; the caller splits the last line off.
+  local path="$1"
+  local url="$API_BASE/$path"
+  # PAT basic auth: username=<token>, password=literal "token". The credential
+  # goes through a curl config via process substitution so it never lands in
+  # argv (argv is visible to ps).
+  curl -sS --max-time "$TIMEOUT" --connect-timeout 5 -w "\n%{http_code}" \
+    -K <(printf 'user = "%s:token"\n' "$TOKEN") \
+    -H "Accept: application/json" \
+    -H "X-Requested-By: multi-agent-pipeline" \
+    "$url" 2>/dev/null || true
+}
+
+# Graylog relative universal search.
+ENC_QUERY=$(QUERY_IN="$QUERY" python3 -c "
+import os, urllib.parse as up
+print(up.quote(os.environ['QUERY_IN']))
+")
+SEARCH_PATH="search/universal/relative?query=$ENC_QUERY&range=$RANGE&limit=$LIMIT&sort=timestamp:desc"
+
+RESP=$(graylog_get "$SEARCH_PATH")
+HTTP=$(printf '%s' "$RESP" | tail -n1)
+BODY=$(printf '%s' "$RESP" | sed '$d')
+
+# A genuine auth rejection on a reachable host is the only hard failure.
+case "$HTTP" in
+  401|403)
+    echo "ERR: Graylog auth rejected (HTTP $HTTP)" >&2
+    exit 3 ;;
+esac
+
+# Any other non-200 (empty code on connection failure, 5xx, timeout) degrades
+# to an empty result so a log fetch never blocks a run.
+DEGRADED="false"
+DEGRADE_REASON=""
+if [ "$HTTP" != "200" ]; then
+  DEGRADED="true"
+  DEGRADE_REASON="graylog-unreachable"
+  BODY=""
+fi
+
+SRC_HOST="$HOST" SRC_TRX="$TRX_ID" SRC_CONV="$CONV_ID" SRC_QUERY="$QUERY" \
+DEGRADED_IN="$DEGRADED" DEGRADE_REASON_IN="$DEGRADE_REASON" \
+BODY_IN="$BODY" LIMIT_IN="$LIMIT" \
+python3 - <<'PY'
+import json, os, datetime
+
+def safe_load(s):
+    try:
+        return json.loads(s) if s else None
+    except Exception:
+        return None
+
+body = safe_load(os.environ.get("BODY_IN") or "") or {}
+raw = body.get("messages") or []
+
+try:
+    limit = int(os.environ.get("LIMIT_IN") or "200")
+except Exception:
+    limit = 200
+
+messages = []
+for item in raw[:limit]:
+    m = item.get("message") if isinstance(item, dict) else None
+    if not isinstance(m, dict):
+        continue
+    reserved = ("timestamp", "source", "level", "message")
+    fields = {k: v for k, v in m.items() if k not in reserved}
+    messages.append({
+        "timestamp": m.get("timestamp") or "",
+        "source": m.get("source") or "",
+        "level": m.get("level") if isinstance(m.get("level"), (int, float)) else None,
+        "message": (m.get("message") or "")[:2000],
+        "fields": fields,
+    })
+
+trx = os.environ.get("SRC_TRX") or None
+conv = os.environ.get("SRC_CONV") or None
+total = body.get("total_results")
+if not isinstance(total, int):
+    total = len(messages)
+
+result = {
+    "fetchedAt": datetime.datetime.utcnow().isoformat() + "Z",
+    "source": {
+        "host": os.environ["SRC_HOST"],
+        "transactionId": trx,
+        "conversationId": conv,
+        "query": os.environ.get("SRC_QUERY") or "",
+    },
+    "totalResults": total,
+    "messages": messages,
+    "degraded": os.environ.get("DEGRADED_IN") == "true",
+    "degradeReason": (os.environ.get("DEGRADE_REASON_IN") or None),
+}
+print(json.dumps(result, ensure_ascii=False))
+PY

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

@@ -22,6 +22,7 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 |---|---|---|
 | `crashlytics` | `~/.claude/lib/fetch-crashlytics.sh <url>` (already invoked in Phase 0 Step 1b.1 for the legacy `state.crashContext` field; Phase 1 reads that field directly) | `state.crashContext` |
 | `fortify` | `~/.claude/lib/fetch-fortify.sh <url>` (already invoked in Phase 0 Step 1b.2 for the legacy `state.fortifyFinding` field; Phase 1 reads that field, Phase 4 reads the full payload for the security gate) | `state.fortifyFinding` |
+| `graylog` | `~/.claude/lib/fetch-graylog.sh --trx <id>` / `--conv <id>` (already invoked in Phase 0 Step 1b.3 for the `state.graylogContext` field; Phase 1 reads that field directly). Diagnostic logs, **advisory only**  -  no Phase 4 gate, no generated task | `state.graylogContext` |
 | `swagger` | `~/.claude/lib/fetch-swagger.sh <url>` → endpoints[], request/response examples | `state.fetchedContext.swagger[]` |
 | `confluence` | `~/.claude/lib/fetch-confluence.sh <url>` → page body, code blocks, extracted API contracts | `state.fetchedContext.confluence[]` |
 | `figma` | no standalone fetcher - resolve via the Figma 3-tier chain (Tier 1 MCP tools, Tier 2 `~/.claude/lib/figma-screenshot.sh` + REST) when the task is a component; otherwise advisory only | `state.fetchedContext.figma[]` |
@@ -36,6 +37,8 @@ One fetcher per type. Each fetcher emits a normalized JSON view that the analysi
 
 Failures are never fatal at Phase 1  -  the agent still runs analysis, just without the referenced source.
 
+**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.
+
 ## Prompt injection shape
 
 Added immediately after the knowledge-injection block, before codebase exploration:

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

@@ -17,7 +17,7 @@ When a token resolves but the service rejects it (401 / 403), do not silently sk
 
 - **Regenerate** - the existing token is dead; open Save Flow Step B to replace `<KEY_NAME>` in place (same key name, clipboard path), then retry the operation.
 - **Use a different token** - map a new or existing Keychain entry for this service (Save Flow Step B + identity binding), then retry.
-- **Skip and continue** - drop this token's contribution. Non-critical services (Confluence enrichment, Fortify scan, Firebase events, Figma fallback tiers) continue with reduced evidence and a one-line warning. A token that is structurally required for the input (e.g. the Jira PAT for a Jira-ID input) halts instead, since the run cannot proceed without it.
+- **Skip and continue** - drop this token's contribution. Non-critical services (Confluence enrichment, Fortify scan, Graylog log fetch, Firebase events, Figma fallback tiers) continue with reduced evidence and a one-line warning. A token that is structurally required for the input (e.g. the Jira PAT for a Jira-ID input) halts instead, since the run cannot proceed without it.
 
 The question asks a *choice*; the replacement value still flows through the clipboard, never chat. `smoke-no-token-prompt.sh` greps for value-prompts (`enter token`, `paste token`, `API key:`) - decision labels like `Regenerate` / `Skip and continue` do not trip it.
 
@@ -64,6 +64,7 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 | `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            | `${USER}_Graylog_Access_Token`     | API Token         |
 | `firebase`         | Firebase           | `${USER}_Firebase_Access_Json`     | JSON (base64)     |
 | `jenkins`          | Jenkins CI         | `${USER}_Jenkins_Access_Token`     | API Token         |
 |  -                   | Git Identity       | Stored in preferences JSON         | Not Keychain      |
@@ -82,6 +83,7 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
       "figma": "${USER}_Figma_Access_Token",
       "figma_mcp": "${USER}_Figma_Mcp_Access_Token",
       "fortify": "${USER}_Fortify_Access_Token",
+      "graylog": "${USER}_Graylog_Access_Token",
       "firebase": "${USER}_Firebase_Access_Json",
       "jenkins": "${USER}_Jenkins_Access_Token"
     }

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

@@ -53,7 +53,7 @@ Then STOP Phase 0  -  do not proceed with a broken token state. This prevents th
 
 **Key design**: Every field is an **array of all historical values** (most recent first) → "recently used" list.
 
-**Token resolution rule**: ALWAYS check `prefs.global.keychainMapping.<service_id>` first for the key name  -  this holds the user's actual Keychain key name (which may differ from the standard convention). Fall back to standard key name ONLY when setup has never run (mapping absent). The standard fallback exists as a safety net, not as the primary path. Service IDs: `jira`, `bitbucket_token`, `bitbucket_user`, `github`, `confluence`, `figma`, `figma_mcp`, `fortify`, `firebase`, `jenkins`.
+**Token resolution rule**: ALWAYS check `prefs.global.keychainMapping.<service_id>` first for the key name  -  this holds the user's actual Keychain key name (which may differ from the standard convention). Fall back to standard key name ONLY when setup has never run (mapping absent). The standard fallback exists as a safety net, not as the primary path. Service IDs: `jira`, `bitbucket_token`, `bitbucket_user`, `github`, `confluence`, `figma`, `figma_mcp`, `fortify`, `firebase`, `jenkins`, `graylog`.
 
 **Jira project key resolution** (first match wins):
 
@@ -196,7 +196,7 @@ Sequential prompts (standard UX pattern with Recent suggestion): Project Key →
 
 **Token pre-check** (after parsing): Jira input → resolve key via `prefs.global.keychainMapping.jira`, verify token with a lightweight API call (e.g. `GET /myself`). GitHub input → verify `gh auth status`. On failure (missing key, 401, 403) → run the **Token Save Flow** from `setup.md` inline. This is the same clipboard-based flow used during setup  -  token never appears in terminal. If user skips and the token is critical for the input type (e.g. Jira token for Jira input), halt Phase 0.
 
-**VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 7, Fortify → skip scan. Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
+**VPN connectivity check**: Test VPN-dependent services (Jira, Bitbucket, Confluence, Fortify, Graylog) with `curl --connect-timeout 3`. If unreachable, warn and offer to continue. Fallback: Jira → manual input, Bitbucket → `git push` only, Confluence → skip Phase 7, Fortify → skip scan, Graylog → skip log fetch (advisory only, never blocks). Cache in `agent-state.json` → `"vpnServices": {"jira": true, ...}`.
 
 #### Step 1b  -  URL Enrichment (catalogue + targeted deep fetches)
 
@@ -225,6 +225,7 @@ Output schema (one array entry per URL  -  full contract in `~/.claude/lib/conte
   { "type": "confluence",  "url": "<url>", "metadata": { "host": "<host>", "pageId": "<id|null>", "spaceKey": "<key|null>" } },
   { "type": "crashlytics", "url": "<url>", "metadata": { "projectId": "...", "platform": "ios|android", "bundle": "...", "issueId": "...", "sessionId": "<id|null>" } },
   { "type": "fortify",     "url": "<url>", "metadata": { "host": "<host>", "projectId": "<id|null>" } },
+  { "type": "graylog",     "url": null,    "metadata": { "idType": "trx|conversation", "id": "...", "label": "..." } },
   { "type": "figma",       "url": "<url>", "metadata": { "kind": "design|make|board|slides", "fileKey": "...", "nodeId": "<id|null>" } },
   { "type": "generic-doc", "url": "<url>", "metadata": { "host": "<host>", "kind": "notion|google-docs|gist|github-doc" } }
 ]
@@ -258,7 +259,18 @@ URL pattern (caught by the extractor): `https://<prefs.global.hosts.fortify>/ssc
 - Phase 2 Planning injects `state.fortifyFinding` into the architectural-review prompt under a **Known Security Finding** section, and the generated task breakdown includes a task addressing the finding (naming convention: `sec(fortify-<issueId>): <issueName> at <file>:<line>`).
 - Soft-fail: 401 → re-run Token Save Flow for `fortify`; 403 → warn and skip; network timeout → respect VPN fallback (skip enrichment, mark `state.fortifyFinding = { skipped: "vpn-unreachable" }`).
 
-##### Step 1b.3  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
+##### Step 1b.3  -  Graylog deep fetch (runs when `type == "graylog"` present in `state.contextLinks[]`)
+
+The extractor emits `graylog` entries from free-text trx / conversation ids (labels like `trx`, `trxId`, `transaction id`, `conversationId`, `convId`, `X-conversationId`), not from a URL  -  so these entries carry `"url": null`. When at least one is present, pull the matching diagnostic logs.
+
+- Host comes from `prefs.global.hosts.graylog` (`GRAYLOG_HOST_OVERRIDE` env forces it for tests/CI); no literal host lives in any source file. Missing host → the fetcher exits `6`; log a setup hint and skip.
+- Token resolution: `prefs.global.keychainMapping.graylog` → `~/.claude/lib/credential-store.sh get "<key>"` → Graylog PAT (fallback key `${USER}_Graylog_Access_Token`). Auth is HTTP Basic with the token as username and the literal `token` as password; the token is fed to `curl` only via a `-K` config file (process substitution), never on argv.
+- Fetch logs (VPN required; respect `vpnServices.graylog`): call `~/.claude/lib/fetch-graylog.sh --trx <id>` (or `--conv <id>` for conversation ids) once per extracted id. The fetcher emits a normalized JSON object of matching log messages.
+- Store as `state.graylogContext = { idType, id, messages[], fetchedAt }` (or an array keyed per id when several were extracted).
+- Phase 1 Analysis prepends `state.graylogContext` to the agent prompt under the **Referenced External Sources** section as **diagnostic context, advisory only** (never contradicts code; no task is generated from it, no Phase 4 gate).
+- Soft-fail (non-blocking, mirrors Crashlytics): unreachable host / VPN down / network timeout → the fetcher emits a normalized empty object and exits `0`; mark `state.graylogContext = { skipped: "vpn-unreachable" }` and continue. Only a genuine auth rejection (4xx on a reachable host, fetcher exit `3`) is logged as `skipped` with the auth reason. A log fetch never blocks the run.
+
+##### Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)
 
 For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLinks[]`, no Phase 0 fetch runs. The entries pass through to Phase 1, which dispatches the matching fetcher (Block B work: `fetch-swagger.sh`, `fetch-confluence.sh`, etc.). Until those fetchers land, the entries are surfaced in Phase 1 context as "referenced but not fetched  -  agent should treat the URL as an authoritative external source and read it directly when relevant."
 
@@ -267,11 +279,11 @@ For `swagger`, `confluence`, `figma`, `generic-doc` entries in `state.contextLin
 **Log line shape** (progress contract):
 
 ```
-→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, figma:<n>, generic-doc:<n>}
-→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>
+→ context links: total=<N>, by-type={swagger:<n>, confluence:<n>, crashlytics:<n>, fortify:<n>, graylog:<n>, figma:<n>, generic-doc:<n>}
+→ URL deep fetch: crashlytics=<hit|miss|skipped>, fortify=<hit|miss|skipped>, graylog=<hit|miss|skipped>
 ```
 
-Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2  -  `miss` = URL type not present in catalogue (normal), `skipped` = URL present but auth/VPN/mismatch skipped the fetch, `hit` = URL-derived context stored in state.
+Two lines emit at the end of Step 1b. The first reports the catalogue from 1b.0 (always runs). The second reports the deep-fetch outcomes from 1b.1 / 1b.2 / 1b.3  -  `miss` = type not present in catalogue (normal), `skipped` = present but auth/VPN/mismatch skipped the fetch (for graylog this includes the non-blocking VPN-unreachable degrade), `hit` = context stored in state.
 
 #### Step 2  -  Project Selection
 
@@ -484,11 +496,12 @@ Single-repo mode (`projects.length === 1` or scalar-only) uses the legacy single
   "inputType": "github-issue-url|github-issue-number|jira-url|jira-id|free-text",
   "jiraId": "PROJ-XXXXX|null", "figmaUrl": "...|null",
   "contextLinks": [
-    { "type": "swagger|confluence|crashlytics|fortify|figma|generic-doc",
-      "url": "<full-url>", "metadata": { } }
+    { "type": "swagger|confluence|crashlytics|fortify|graylog|figma|generic-doc",
+      "url": "<full-url|null>", "metadata": { } }
   ],
   "crashContext": null,
   "fortifyFinding": null,
+  "graylogContext": null,
   "localMode": false, "instructionDriven": true|false, "instructionFiles": {},
   "identity": {"name": "...", "email": "...", "keychainKey": "..."},
   "currentPhase": 0, "status": "in_progress", "startedAt": "{ISO}", "shortId": "#N",

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -75,7 +75,7 @@ Progress lines:
 
 #### Step 1.5  -  External Context Injection (`state.contextLinks[]`)
 
-Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. Failures never fatal; pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
+Phase 0 Step 1b catalogued every typed external link from the task description into `state.contextLinks[]`. Phase 1 dispatches each entry to its matching fetcher (crashlytics, fortify, graylog, swagger, confluence, figma, generic-doc) and prepends results under a **Referenced External Sources** section in the analysis prompt  -  so the agent doesn't re-discover what the ticket already pointed at. `state.graylogContext` is injected there too, as diagnostic context (advisory only). Failures never fatal (a non-zero fetcher exit is marked skipped and the analysis still runs, exactly as for crashlytics); pending refs are advisories. Full dispatch table, exit-code handling, prompt injection shape, log line shape: `$HOME/.claude/multi-agent-refs/features/external-context-injection.md`.
 
 **Log line shape** (progress contract):
 

package/pipeline/preferences-template.json

@@ -11,6 +11,7 @@
       "figma": null,
       "figma_mcp": null,
       "fortify": null,
+      "graylog": null,
       "firebase": null,
       "jenkins": null
     },

package/pipeline/schemas/prefs.schema.json

@@ -157,6 +157,12 @@
                 "null"
               ]
             },
+            "graylog": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
             "firebase": {
               "type": [
                 "string",
@@ -482,6 +488,10 @@
               "type": "string",
               "description": "Fortify SSC host without scheme, e.g. ssc.example.com. Used by Phase 0 Step 1b URL enrichment to validate pasted Fortify URLs and for direct SSC REST API calls. Resolves {FORTIFY_HOST}."
             },
+            "graylog": {
+              "type": "string",
+              "description": "Graylog host without scheme, e.g. logs.example.com. Used by the Graylog log-fetch adapter for direct REST API calls. Resolves {GRAYLOG_HOST}."
+            },
             "corpDomain": {
               "type": "string",
               "description": "Corporate email / cookie domain, e.g. example.com. Resolves {CORP_DOMAIN}."

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -2,7 +2,7 @@
 .claude/CLAUDE.md	1
 .claude/agents	8
 .claude/commands	44
-.claude/lib	25
+.claude/lib	26
 .claude/multi-agent-preferences.json	1
 .claude/multi-agent-refs	51
 .claude/rules	12
@@ -13,7 +13,7 @@
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
-.copilot/lib	25
+.copilot/lib	26
 .copilot/schemas	23
 .copilot/scripts	193
 .copilot/skills	467

package/pipeline/scripts/smoke-fetchers-offline.sh

@@ -261,6 +261,30 @@ expect_rc 0 "stub token + offline curl degrades to empty result (exit 0)" \
   "$SH" "$LIB/fetch-fortify.sh" "$FORTIFY_URL"
 assert_in_file '"gateOutcome"' "$OUT" "normalized JSON still emitted"
 
+# -----------------------------------------------------------------------------
+note "4b. fetch-graylog.sh"
+# -----------------------------------------------------------------------------
+expect_rc 6 "no host configured exits 6" \
+  env HOME="$FAKE_HOME" USER=smoke \
+  "$SH" "$LIB/fetch-graylog.sh" --trx T123
+expect_rc 4 "host override + no ids exits 4 (usage)" \
+  env HOME="$FAKE_HOME" USER=smoke GRAYLOG_HOST_OVERRIDE=logs.example.com \
+  "$SH" "$LIB/fetch-graylog.sh"
+
+expect_rc 2 "host override + id reaches credential stage" \
+  env HOME="$FAKE_HOME" USER=smoke GRAYLOG_HOST_OVERRIDE=logs.example.com \
+  "$SH" "$LIB/fetch-graylog.sh" --trx T123 --conv C456
+assert_in_file "missing-token" "$ERR" "blocked JSON names missing-token"
+
+# Non-blocking contract: with a stub token and a failing curl, the fetch must
+# degrade to an empty normalized result (messages present) and exit 0 so a log
+# fetch never blocks a run.
+expect_rc 0 "stub token + offline curl degrades to empty result (exit 0)" \
+  env HOME="$FAKE_HOME" USER=smoke GRAYLOG_HOST_OVERRIDE=logs.example.com \
+      FAKE_CRED_VALUE=fake-token PATH="$BIN_CURL_FAIL:$PATH" \
+  "$SH" "$LIB/fetch-graylog.sh" --trx T123
+assert_in_file '"messages"' "$OUT" "normalized JSON still emitted"
+
 # -----------------------------------------------------------------------------
 note "5. figma-screenshot.sh"
 # -----------------------------------------------------------------------------
@@ -338,6 +362,7 @@ OWNED_FILES=(
   "$LIB/fetch-crashlytics.sh"
   "$LIB/fetch-swagger.sh"
   "$LIB/fetch-fortify.sh"
+  "$LIB/fetch-graylog.sh"
   "$LIB/figma-mcp-refresh.sh"
   "$LIB/figma-screenshot.sh"
   "$LIB/credential-store.sh"