@mmerterden/multi-agent-pipeline 20.2.1 → 20.3.0

package/pipeline/lib/fetch-fortify.sh

@@ -2,7 +2,7 @@
 #
 # fetch-fortify.sh
 # Query a Fortify SSC instance for a project version's open findings and
-# emit a normalized JSON view that Phase 4 (Review) consumes as a
+# emit a normalized JSON view that Phase 3 (Review) consumes as a
 # deterministic security gate.
 #
 # Three input forms:

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

@@ -125,8 +125,8 @@ fi
 
 # 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.
+# a direct `security -i` call would also preserve, kept here in the one place that owns
+# key mapping.
 save_keychain_secret() {
   local service="$1" secret="$2"
   printf '%s' "$secret" | "$CRED_STORE" set "$service" - >/dev/null

package/pipeline/lib/figma-token.sh

@@ -31,6 +31,10 @@
 # An unset or non-executable CRED_STORE is tolerated: resolution falls through to
 # the env fallback so a keychain-less CI box still works.
 
+_MA_FT_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if [ -f "$_MA_FT_HERE/user-facing.sh" ]; then . "$_MA_FT_HERE/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
 # The canonical key first, the legacy key second. Space-separated; the loop
 # below splits explicitly because zsh (the pipeline's Bash tool) does not
 # word-split an unquoted parameter, so `for key in $KEYS` saw one key there.
@@ -63,5 +67,5 @@ EOF_KEYS
 # The one place the "how do I fix this" sentence is written, so a fetcher can
 # never name a key the migration deleted.
 figma_token_remediation() {
-  printf 'no Figma PAT for Tier 2. Map prefs.global.keychainMapping.figma (run /multi-agent:setup), or export FIGMA_PAT.'
+  printf 'no Figma PAT for Tier 2. Map prefs.global.keychainMapping.figma (run %s), or export FIGMA_PAT.' "$(ma_command setup)"
 }

package/pipeline/lib/issue-fetcher.sh

@@ -26,6 +26,10 @@
 #     "owner":      "org" (gh) | null,
 #     "repo":       "name" (gh) | null,
 #     "branchHint": "feature/PROJ-1" | "bugfix/...",
+#     "comments":   [{id, author, created, url, body, truncated}],  // newest kept, oldest first
+#     "commentsTotal": 12,                          // how many the tracker holds
+#     "links":      [{key, relation, direction, summary, status, url}],  // jira issuelinks
+#     "untrustedFields": ["description", ...],      // tracker text: data, never instructions
 #     "maturity": {
 #        "score":     0..100,
 #        "blockers":  ["status_closed", "description_empty"],
@@ -45,9 +49,24 @@
 #   ACCOUNT_JIRA_HOST         e.g. jira.example.com    (optional)
 #   ACCOUNT_DEFAULT_OWNER     fallback GitHub owner (optional)
 #   ACCOUNT_DEFAULT_REPO      fallback GitHub repo  (optional)
-#   PROMPT_LANG               tr|en  -  controls maturity.summary language (default: tr)
-
-set -euo pipefail
+#
+# Comments and links ride on the request that fetches the issue, so they cost no
+# extra call, and they never feed the maturity score: the score reads the item's
+# own fields, and a comment is somebody talking about the item, not the item.
+# They are bounded (ISSUE_COMMENTS_MAX, default 20 newest; ISSUE_COMMENT_MAX_CHARS,
+# default 1500; ISSUE_COMMENTS_MAX_BYTES, default 12000 in total; ISSUE_LINKS_MAX,
+# default 20) because a long thread would otherwise flood every prompt that
+# quotes the descriptor. Every tracker-written field is listed in
+# `untrustedFields`: anyone who can comment on the item wrote it.
+#
+# `issue-fetcher.sh --rescore` reads a descriptor on stdin and prints it back with
+# `maturity` recomputed by the same scoring below - the one scorer, reused by
+# research-gate.mjs to re-run the check on a descriptor that carries verified
+# research findings.
+#
+# `maturity.summary` is written for the person at the picker, so it renders in
+# `prefs.global.outputLanguage`; every other field is machine-readable and
+# stays English.
 
 # Sourcing this file hands a caller the provider helpers - `jira_search`,
 # `fetch_jira`, `fetch_github` and the `jira_curl` underneath them - without
@@ -61,6 +80,11 @@ set -euo pipefail
 MA_IF_EXECUTED=0
 [ "${BASH_SOURCE[0]}" = "$0" ] && MA_IF_EXECUTED=1
 
+# Strict mode belongs to the executed resolver. A sourcing caller keeps its own
+# error handling: jira-search.sh runs without errexit on purpose so that a
+# failed query reaches its own warning and exit code.
+if [ "$MA_IF_EXECUTED" = 1 ]; then set -euo pipefail; fi
+
 INPUT="${1:-}"
 if [ "$MA_IF_EXECUTED" = 1 ] && [ -z "$INPUT" ]; then
   echo '{"error":"input required"}'
@@ -71,7 +95,11 @@ JIRA_TOKEN_KEY="${ACCOUNT_JIRA_TOKEN_KEY:-}"
 JIRA_HOST="${ACCOUNT_JIRA_HOST:-}"
 DEFAULT_OWNER="${ACCOUNT_DEFAULT_OWNER:-}"
 DEFAULT_REPO="${ACCOUNT_DEFAULT_REPO:-}"
-PROMPT_LANG="${PROMPT_LANG:-tr}"
+
+_MA_IF_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+if [ -f "$_MA_IF_HERE/user-facing.sh" ]; then . "$_MA_IF_HERE/user-facing.sh"; elif [ -f "$HOME/.claude/lib/user-facing.sh" ]; then . "$HOME/.claude/lib/user-facing.sh"; fi
+if command -v ma_output_lang >/dev/null 2>&1; then SUMMARY_LANG=$(ma_output_lang); else SUMMARY_LANG=en; fi
 
 # --- Detect input kind --------------------------------------------------------
 detect_kind() {
@@ -105,6 +133,7 @@ detect_kind() {
 }
 
 KIND=$(detect_kind "$INPUT")
+[ "$INPUT" = "--rescore" ] && KIND=rescore
 
 # --- Helpers ------------------------------------------------------------------
 slugify() {
@@ -134,6 +163,41 @@ branch_for() {
 
 # --- Provider fetchers (return raw JSON or empty) -----------------------------
 
+# Shared by both provider parses: the newest comments, oldest first, inside a
+# count, a per-comment and a total byte budget. Prepended to each parse script
+# so the bound is one piece of code, not two.
+_PY_BOUND_COMMENTS='
+import os
+def _env_int(name, default):
+    v = os.environ.get(name)
+    try:
+        return int(v) if v not in (None, "") else default
+    except ValueError:
+        return default
+def bound_comments(rows):
+    cap = _env_int("ISSUE_COMMENTS_MAX", 20)
+    chars = _env_int("ISSUE_COMMENT_MAX_CHARS", 1500)
+    budget = _env_int("ISSUE_COMMENTS_MAX_BYTES", 12000)
+    kept, used = [], 0
+    for r in reversed(rows):
+        if len(kept) >= cap:
+            break
+        body = (r.get("body") or "").replace("\x1f", " ")
+        truncated = False
+        if chars > 0 and len(body) > chars:
+            body, truncated = body[:chars] + "...", True
+        size = len(body.encode("utf-8"))
+        if budget > 0 and used + size > budget:
+            if kept:
+                break
+            body = body.encode("utf-8")[:max(budget - 3, 0)].decode("utf-8", "ignore") + "..."
+            truncated, size = True, len(body.encode("utf-8"))
+        kept.append(dict(r, body=body, truncated=truncated))
+        used += size
+    kept.reverse()
+    return kept
+'
+
 # Bearer-auth via a curl config fed through process substitution so the
 # token never appears in argv (argv is visible to `ps` / process audit).
 jira_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$1"; }
@@ -178,7 +242,7 @@ jira_curl() {
     echo "ERR: Jira token not found in credential store ($JIRA_TOKEN_KEY)" >&2
     return 1
   fi
-  curl -sf -K <(jira_auth_cfg "$token") "https://$JIRA_HOST$path"
+  curl -sf -m 30 -K <(jira_auth_cfg "$token") "https://$JIRA_HOST$path"
 }
 
 # The field list is a parameter because the related-issue lookup wants a
@@ -207,7 +271,7 @@ fetch_github() {
     return 1
   fi
   gh issue view "$num" --repo "$owner/$repo" \
-    --json number,title,labels,state,url,body 2>/dev/null \
+    --json number,title,labels,state,url,body,comments 2>/dev/null \
     || { echo "ERR: GitHub fetch failed for $owner/$repo#$num" >&2; return 1; }
 }
 
@@ -217,7 +281,7 @@ fetch_github() {
 
 # Build the descriptor JSON, then attach maturity. Pythonized so escaping stays sane.
 emit_descriptor() {
-  python3 - "$PROMPT_LANG" "$@" <<'PY'
+  python3 - "$SUMMARY_LANG" "$@" <<'PY'
 import json, sys, re
 
 lang = sys.argv[1]
@@ -252,6 +316,21 @@ except Exception:
 if not isinstance(related, list):
     related = []
 
+def _json_field(name, want):
+    try:
+        v = json.loads(fields.get(name) or "null")
+    except Exception:
+        v = None
+    return v if isinstance(v, want) else None
+
+cblob = _json_field("comments", dict) or {}
+comments = cblob.get("items") if isinstance(cblob.get("items"), list) else []
+try:
+    comments_total = int(cblob.get("total") or len(comments))
+except (TypeError, ValueError):
+    comments_total = len(comments)
+links = _json_field("links", list) or []
+
 descriptor = {
     "kind":        fields.get("kind"),
     "key":         fields.get("key") or None,
@@ -271,6 +350,10 @@ descriptor = {
     "repo":        fields.get("repo") or None,
     "branchHint":  fields.get("branchHint") or None,
     "relatedIssues": related,
+    "comments":    comments,
+    "commentsTotal": comments_total,
+    "links":       links,
+    "untrustedFields": ["title", "description", "parentDescription", "relatedIssues", "comments", "links"],
 }
 extra = {}
 if fields.get("needsRepoPicker"):
@@ -380,17 +463,21 @@ if [ "$MA_IF_EXECUTED" = 1 ]; then
 case "$KIND" in
   jira-id)
     KEY="$INPUT"
-    raw=$(fetch_jira "$KEY") || raw=""
+    raw=$(fetch_jira "$KEY" "summary,status,issuetype,description,priority,resolution,fixVersions,parent,comment,issuelinks") || raw=""
+    commentsjson='{"items":[],"total":0}'; linksjson="[]"
     if [ -n "$raw" ]; then
       # Single python3 pass  -  emit all fields joined by U+001F (Unit Separator)
       # so we avoid spawning 7 interpreter startups per Jira fetch
       # (~200-300ms each). The separator is non-whitespace, so empty fields
       # (e.g. unresolved issues) are preserved by `read` instead of collapsed.
       # `read -d ''` lets descriptions with embedded newlines pass through.
-      parsed=$(printf '%s' "$raw" | python3 -c '
-import json, sys
+      parsed=$(printf '%s' "$raw" | SELF_KEY="$KEY" JIRA_HOST="$JIRA_HOST" python3 -c "$_PY_BOUND_COMMENTS"'
+import json, re, sys
 d = json.load(sys.stdin)
 f = d.get("fields", {}) or {}
+host = os.environ.get("JIRA_HOST", "")
+self_key = os.environ.get("SELF_KEY", "")
+key_re = re.compile(r"^[A-Z][A-Z0-9]*-[0-9]+$")
 def _name(x):
     return (x or {}).get("name", "") or ""
 title       = f.get("summary", "") or ""
@@ -401,11 +488,47 @@ priority    = _name(f.get("priority"))
 resolution  = _name(f.get("resolution"))
 fixversions = ",".join((v or {}).get("name", "") for v in (f.get("fixVersions") or []))
 parentkey   = (f.get("parent") or {}).get("key", "") or ""
+cblock = f.get("comment") or {}
+crows = []
+for c in cblock.get("comments") or []:
+    if not isinstance(c, dict):
+        continue
+    cid = str(c.get("id") or "")
+    crows.append({
+        "id": cid,
+        "author": ((c.get("author") or {}).get("displayName") or ""),
+        "created": c.get("created") or "",
+        "url": "https://%s/browse/%s?focusedCommentId=%s" % (host, self_key, cid) if host and cid else "",
+        "body": c.get("body") or "",
+    })
+comments = {"items": bound_comments(crows), "total": int(cblock.get("total") or len(crows))}
+links = []
+for l in f.get("issuelinks") or []:
+    if not isinstance(l, dict):
+        continue
+    t = l.get("type") or {}
+    other, direction = (l.get("outwardIssue"), "outward") if l.get("outwardIssue") else (l.get("inwardIssue"), "inward")
+    other = other or {}
+    lkey = other.get("key") or ""
+    if not key_re.match(lkey):
+        continue
+    of = other.get("fields") or {}
+    links.append({
+        "key": lkey,
+        "relation": (t.get(direction) or t.get("name") or ""),
+        "direction": direction,
+        "summary": of.get("summary") or "",
+        "status": _name(of.get("status")),
+        "url": "https://%s/browse/%s" % (host, lkey) if host else "",
+    })
+links = links[:max(_env_int("ISSUE_LINKS_MAX", 20), 0)]
 parts = [title, itype, status, description, priority, resolution, fixversions, parentkey]
 parts = [v.replace("\x1f", " ") for v in parts]
+parts += [json.dumps(comments, ensure_ascii=False), json.dumps(links, ensure_ascii=False)]
 sys.stdout.write("\x1f".join(parts))
 ')
-      IFS=$'\x1f' read -r -d '' title itype status description priority resolution fixversions parentkey <<< "$parsed" || true
+      IFS=$'\x1f' read -r -d '' title itype status description priority resolution fixversions parentkey commentsjson linksjson <<< "$parsed" || true
+      linksjson="${linksjson%$'\n'}"
       # `<<<` appends a trailing newline to its input; `read -d ''` has no
       # delimiter to stop on, so that newline folds into whichever field
       # comes last  -  now parentkey. Strip it, or a genuinely-empty parent
@@ -534,12 +657,49 @@ sys.stdout.write(json.dumps(out[:cap], ensure_ascii=False))
       "url=https://$JIRA_HOST/browse/$KEY" "branchHint=$branch" \
       "priority=$priority" "resolution=$resolution" "fixVersions=$fixversions" \
       "parentKey=$parentkey" "parentDescription=$parentdesc" \
-      "relatedIssues=$relatedjson"
+      "relatedIssues=$relatedjson" "comments=$commentsjson" "links=$linksjson"
     ;;
 
   jira-url)
     HOST=$(printf '%s' "$INPUT" | sed -E 's#https?://##; s#/.*##')
-    KEY=$(printf '%s' "$INPUT" | sed -E 's#.*/browse/##; s#[/?].*##')
+    KEY=$(printf '%s' "$INPUT" | sed -E 's#.*/browse/##; s#[/?#].*##')
+    # Re-dispatch only a real key. Anything else would fall through
+    # detect_kind to the freetext branch and start a run titled with a URL.
+    if ! [[ "$KEY" =~ ^[A-Z][A-Z0-9]*-[0-9]+$ ]]; then
+      echo '{"error":"no Jira issue key in URL"}'
+      exit 2
+    fi
+    # The link's host receives the Jira token on the re-dispatch, and a link is
+    # ticket or request text. HOST is the exact string curl will see, so it must
+    # be a bare host[:port] and name the configured Jira host; without one, only
+    # Atlassian Cloud, where the host is the tenant.
+    if ! [[ "$HOST" =~ ^[A-Za-z0-9.-]+(:[0-9]{1,5})?$ ]]; then
+      echo '{"error":"host-malformed"}'
+      exit 2
+    fi
+    _allowed="${JIRA_HOST:-}"
+    if [ -z "$_allowed" ]; then
+      _prefs="${MA_PREFS_FILE:-$HOME/.claude/multi-agent-preferences.json}"
+      _allowed=$(python3 - "$_prefs" <<'PY' 2>/dev/null || true
+import json, sys
+try:
+    print((json.load(open(sys.argv[1])).get("global", {}).get("hosts", {}) or {}).get("jira") or "")
+except Exception:
+    print("")
+PY
+)
+    fi
+    _allowed=$(printf '%s' "$_allowed" | tr '[:upper:]' '[:lower:]' | sed -E 's#^https?://##; s#/.*##; s#:.*##; s#\.$##')
+    _host=$(printf '%s' "$HOST" | tr '[:upper:]' '[:lower:]' | sed -E 's#:.*##; s#\.$##')
+    if [ -n "$_allowed" ]; then
+      [ "$_host" = "$_allowed" ] || { echo '{"error":"host-not-allowed"}'; exit 2; }
+    else
+      case "$_host" in
+        *.atlassian.net) ;;
+        *) echo '{"error":"host-not-configured"}'; exit 2 ;;
+      esac
+    fi
+    unset _allowed _prefs _host
     ACCOUNT_JIRA_HOST="$HOST" JIRA_HOST="$HOST" exec "$0" "$KEY"
     ;;
 
@@ -548,21 +708,38 @@ sys.stdout.write(json.dumps(out[:cap], ensure_ascii=False))
     REPO=$(printf '%s' "$INPUT" | sed -E 's#https?://github.com/[^/]+/##; s#/.*##')
     NUM=$(printf '%s' "$INPUT" | sed -E 's#.*/issues/##; s#[/?#].*##')
     raw=$(fetch_github "$OWNER" "$REPO" "$NUM") || raw=""
+    commentsjson='{"items":[],"total":0}'
     if [ -n "$raw" ]; then
       # Single python3 pass  -  see jira-id branch for rationale on the
       # U+001F separator + `read -d ''` combo.
-      parsed=$(printf '%s' "$raw" | python3 -c '
+      parsed=$(printf '%s' "$raw" | python3 -c "$_PY_BOUND_COMMENTS"'
 import json, sys
 d = json.load(sys.stdin)
 title       = d.get("title", "") or ""
 labels      = ",".join((l or {}).get("name", "") for l in (d.get("labels") or []))
 status      = d.get("state", "open") or "open"
 description = d.get("body", "") or ""
+crows = []
+for c in d.get("comments") or []:
+    if not isinstance(c, dict):
+        continue
+    crows.append({
+        "id": str(c.get("id") or ""),
+        "author": ((c.get("author") or {}).get("login") or ""),
+        "created": c.get("createdAt") or "",
+        "url": c.get("url") or "",
+        "body": c.get("body") or "",
+    })
+comments = {"items": bound_comments(crows), "total": len(crows)}
 parts = [title, labels, status, description]
 parts = [v.replace("\x1f", " ") for v in parts]
+parts.append(json.dumps(comments, ensure_ascii=False))
 sys.stdout.write("\x1f".join(parts))
 ')
-      IFS=$'\x1f' read -r -d '' title labels status description <<< "$parsed" || true
+      IFS=$'\x1f' read -r -d '' title labels status description commentsjson <<< "$parsed" || true
+      # Same `<<<` trailing newline as the jira-id branch; here the comments
+      # JSON is the last field and would carry it.
+      commentsjson="${commentsjson%$'\n'}"
     else
       title="(unfetched)"; labels=""; status="open"; description=""
     fi
@@ -572,7 +749,7 @@ sys.stdout.write("\x1f".join(parts))
       "kind=github" "key=$NUM" "title=$title" "type=$itype" "status=$status" \
       "description=$description" "host=github.com" \
       "url=https://github.com/$OWNER/$REPO/issues/$NUM" \
-      "owner=$OWNER" "repo=$REPO" "branchHint=$branch"
+      "owner=$OWNER" "repo=$REPO" "branchHint=$branch" "comments=$commentsjson"
     ;;
 
   gh-short)
@@ -600,6 +777,46 @@ sys.stdout.write("\x1f".join(parts))
     exec "$0" "https://github.com/$OWNER/$REPO/issues/$NUM"
     ;;
 
+  rescore)
+    # The descriptor's own fields, handed back to the one scorer. Read in full
+    # first: the argument list is built by a second process.
+    desc_in=$(cat)
+    rescore_args=()
+    while IFS= read -r -d '' a; do rescore_args+=("$a"); done < <(printf '%s' "$desc_in" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    d = None
+if not isinstance(d, dict):
+    sys.exit(0)
+def s(v):
+    return "" if v is None else str(v)
+comments = d.get("comments") if isinstance(d.get("comments"), list) else []
+out = {
+    "kind": s(d.get("kind")), "key": s(d.get("key")), "title": s(d.get("title")),
+    "type": s(d.get("type")), "status": s(d.get("status")), "description": s(d.get("description")),
+    "priority": s(d.get("priority")), "resolution": s(d.get("resolution")),
+    "fixVersions": ",".join(s(v) for v in (d.get("fixVersions") or [])),
+    "parentKey": s(d.get("parentKey")), "parentDescription": s(d.get("parentDescription")),
+    "host": s(d.get("host")), "url": s(d.get("url")), "owner": s(d.get("owner")),
+    "repo": s(d.get("repo")), "branchHint": s(d.get("branchHint")),
+    "relatedIssues": json.dumps(d.get("relatedIssues") or [], ensure_ascii=False),
+    "comments": json.dumps({"items": comments, "total": d.get("commentsTotal") or len(comments)}, ensure_ascii=False),
+    "links": json.dumps(d.get("links") or [], ensure_ascii=False),
+}
+if d.get("needsRepoPicker"):
+    out["needsRepoPicker"] = "1"
+for k, v in out.items():
+    sys.stdout.write("%s=%s\0" % (k, v.replace("\0", "")))
+')
+    if [ "${#rescore_args[@]}" -eq 0 ]; then
+      echo '{"error":"--rescore needs a descriptor JSON object on stdin"}'
+      exit 2
+    fi
+    emit_descriptor "${rescore_args[@]}"
+    ;;
+
   freetext)
     title="$INPUT"
     branch=$(branch_for "" "Task" "$title")

package/pipeline/lib/json-file-lock.mjs

@@ -0,0 +1,172 @@
+/**
+ * json-file-lock.mjs  -  synchronous read-modify-write of a small JSON file
+ * under a lock, replaced atomically with owner-only permissions.
+ *
+ * The lock is `<file>.lock`, created the way write-state.mjs creates it: the
+ * owning PID is written to a private stage file that is hard-linked into place,
+ * so the lock never exists without its PID. The two helpers therefore exclude
+ * each other on the same file. A lock whose PID is no longer alive is
+ * reclaimed by inode identity; a lock with no readable PID is reclaimed only
+ * once it is older than `staleMs`.
+ *
+ * The write goes to a temp file in the same directory, created exclusively at
+ * `mode`, and is renamed over the target, so a reader sees the old document or
+ * the new one and never a partial write.
+ *
+ * @module pipeline/lib/json-file-lock
+ */
+
+import {
+  chmodSync,
+  linkSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { readRegularJson } from "./regular-file.mjs";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DEFAULT_STALE_MS = 30_000;
+const POLL_MS = 50;
+
+export class FileLockTimeout extends Error {
+  constructor(lockPath, timeoutMs) {
+    super(`lock timeout on ${lockPath} after ${timeoutMs}ms`);
+    this.name = "FileLockTimeout";
+    this.code = "LOCK_TIMEOUT";
+  }
+}
+
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function staleIdentity(lockPath, staleMs) {
+  let pid;
+  let st;
+  try {
+    pid = parseInt(readFileSync(lockPath, "utf8").trim(), 10);
+    st = statSync(lockPath);
+  } catch {
+    return null;
+  }
+  const age = Date.now() - st.mtimeMs;
+  if (!Number.isInteger(pid) || pid <= 0) return age > staleMs ? st : null;
+  try {
+    process.kill(pid, 0);
+    return null;
+  } catch (err) {
+    return err.code === "ESRCH" ? st : null;
+  }
+}
+
+function acquire(lockPath, timeoutMs, staleMs) {
+  const stage = `${lockPath}.${process.pid}.stage`;
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      writeFileSync(stage, String(process.pid), { mode: 0o600 });
+      linkSync(stage, lockPath);
+      const ino = statSync(lockPath).ino;
+      unlinkSync(stage);
+      return ino;
+    } catch (err) {
+      rmSync(stage, { force: true });
+      if (err.code !== "EEXIST") throw err;
+    }
+    const stale = staleIdentity(lockPath, staleMs);
+    if (stale) {
+      try {
+        const now = statSync(lockPath);
+        if (now.ino === stale.ino && now.mtimeMs === stale.mtimeMs) unlinkSync(lockPath);
+      } catch {
+        /* gone already */
+      }
+      continue;
+    }
+    if (Date.now() >= deadline) throw new FileLockTimeout(lockPath, timeoutMs);
+    pause(POLL_MS);
+  }
+}
+
+function release(lockPath, ino) {
+  try {
+    if (statSync(lockPath).ino === ino) unlinkSync(lockPath);
+  } catch {
+    /* gone already */
+  }
+}
+
+/**
+ * Run `fn` while holding `<path>.lock`.
+ *
+ * @template T
+ * @param {string} path
+ * @param {() => T} fn
+ * @param {{timeoutMs?: number, staleMs?: number}} [opts]
+ * @returns {T}
+ */
+export function withFileLockSync(
+  path,
+  fn,
+  { timeoutMs = DEFAULT_TIMEOUT_MS, staleMs = DEFAULT_STALE_MS } = {},
+) {
+  const lockPath = `${path}.lock`;
+  const ino = acquire(lockPath, timeoutMs, staleMs);
+  try {
+    return fn();
+  } finally {
+    release(lockPath, ino);
+  }
+}
+
+/**
+ * Replace `path` with `data` as JSON, atomically, at `mode`.
+ *
+ * @param {string} path
+ * @param {unknown} data
+ * @param {{mode?: number}} [opts]
+ */
+export function writeJsonAtomicSync(path, data, { mode = 0o600 } = {}) {
+  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.tmp`);
+  rmSync(tmp, { force: true });
+  try {
+    writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode, flag: "wx" });
+    chmodSync(tmp, mode);
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * Lock, read, mutate and atomically replace a JSON file. `mutate` receives the
+ * parsed document (or `fallback` when the file is missing or unreadable) and
+ * returns the next one; returning `undefined` writes nothing.
+ *
+ * @param {string} path
+ * @param {(current: any) => any} mutate
+ * @param {{fallback?: any, mode?: number, timeoutMs?: number, staleMs?: number}} [opts]
+ * @returns {any} the document written, or undefined when nothing was
+ */
+export function updateJsonFileSync(path, mutate, { fallback = null, mode = 0o600, ...lock } = {}) {
+  return withFileLockSync(
+    path,
+    () => {
+      const next = mutate(readRegularJson(path, fallback));
+      if (next === undefined) return undefined;
+      writeJsonAtomicSync(path, next, { mode });
+      return next;
+    },
+    lock,
+  );
+}
+
+/** A lock timeout from `env.WRITE_STATE_LOCK_TIMEOUT_MS`, the knob write-state reads. */
+export function lockTimeoutFrom(env = process.env) {
+  const n = Number(env?.WRITE_STATE_LOCK_TIMEOUT_MS);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}

package/pipeline/lib/model-dispatch.sh

@@ -52,15 +52,8 @@ done
 
 emit() { printf '%s\n' "$1"; exit 0; }
 
-case "$CALL_SITE" in
-  subagent|bulk-read|research) ;;
-  *) emit "$DEFAULT_RUNG" ;;
-esac
-
 [ -n "$DEFAULT_RUNG" ] || DEFAULT_RUNG="sonnet"
 
-command -v jq >/dev/null 2>&1 || emit "$DEFAULT_RUNG"
-
 PREFS=""
 for candidate in \
   "${MULTI_AGENT_PREFS:-}" \
@@ -69,6 +62,23 @@ for candidate in \
 do
   [ -n "$candidate" ] && [ -f "$candidate" ] && { PREFS="$candidate"; break; }
 done
+
+# The fable rung exists only while modelFallback.fableEnabled is true, and it
+# ships false. A caller whose default is fable - a command that runs without
+# Phase 0, such as review - gets the documented resolution, opus, on every path
+# out of here: routing off, out of scope, no rule, or nothing readable.
+FABLE_ON=false
+if [ -n "$PREFS" ] && command -v jq >/dev/null 2>&1; then
+  FABLE_ON=$(jq -r '.global.modelFallback.fableEnabled // false' "$PREFS" 2>/dev/null || echo false)
+fi
+[ "$DEFAULT_RUNG" = "fable" ] && [ "$FABLE_ON" != "true" ] && DEFAULT_RUNG="opus"
+
+case "$CALL_SITE" in
+  subagent|bulk-read|research) ;;
+  *) emit "$DEFAULT_RUNG" ;;
+esac
+
+command -v jq >/dev/null 2>&1 || emit "$DEFAULT_RUNG"
 [ -n "$PREFS" ] || emit "$DEFAULT_RUNG"
 
 ENABLED=$(jq -r '.global.modelRouting.enabled // false' "$PREFS" 2>/dev/null) || emit "$DEFAULT_RUNG"
@@ -98,11 +108,10 @@ MATCH=$(jq -r \
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 COST_TABLE="$HERE/../scripts/cost-table.json"
 
-# The fable rung answers only when the fable switch is on. Routing is a policy
-# over what is available; it is not a second way to turn a rung on, or
-# `/multi-agent:model off` would stop meaning anything the moment a rule named
-# fable.
-FABLE_ON=$(jq -r '.global.modelFallback.fableEnabled // false' "$PREFS" 2>/dev/null)
+# The fable rung answers only when the fable switch is on (FABLE_ON, read
+# above). Routing is a policy over what is available; it is not a second way to
+# turn a rung on, or `/multi-agent:model off` would stop meaning anything the
+# moment a rule named fable.
 
 record() {
   [ -x "$HERE/../scripts/log-metric.sh" ] || return 0