forgedock 1.2.0 → 1.4.0

package/bin/forgedock.mjs

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 import { fileURLToPath } from "url";
-import { dirname, join, relative, resolve } from "path";
+import { dirname, join, relative, resolve, sep } from "path";
 import { mkdir, lstat, readlink, readdir, unlink, readFile, writeFile } from "fs/promises";
 import {
   existsSync,
@@ -13,7 +13,7 @@ import {
   renameSync,
   unlinkSync,
 } from "fs";
-import { execSync, execFileSync } from "child_process";
+import { execSync, execFileSync, spawnSync } from "child_process";
 import { homedir } from "os";
 import https from "https";
 import {
@@ -35,6 +35,17 @@ import {
   persistHome,
   PIPELINE_SCRIPTS,
 } from "./journey.mjs";
+import {
+  deriveWorkflowLabels,
+  FINDINGS_LANE_LABEL,
+  classifyFindingStatus,
+  hasWorkflowLabel,
+  normalizePriority,
+  parseSatelliteRepos,
+  buildHeartbeatBatchQuery,
+  parseHeartbeatBatchResponse,
+  chunkArray,
+} from "./watch-utils.mjs";
 import {
   removeSessionStartHook,
   removeSubagentStopHook,
@@ -1475,17 +1486,289 @@ async function printVersionAvailableChangelog(localVersion, latestVersion) {
   }
 }
 
+/**
+ * Resolve the absolute path npm's global install tree would use for a
+ * `forgedock` package, i.e. `{npm root -g}/forgedock`. Shared by
+ * `isGlobalNpmInstall()` and `findSeparateGlobalInstall()` (forge#2273) so
+ * the `npm root -g` shell-out and path-join logic exists in exactly one
+ * place instead of being duplicated across both callers.
+ *
+ * Fails closed (returns null) on any error, timeout, or empty `npm root -g`
+ * output — callers treat null identically to their pre-existing "detection
+ * inconclusive" fallback (isGlobalNpmInstall: false; findSeparateGlobalInstall: null).
+ *
+ * @returns {string|null} absolute path to `{globalRoot}/forgedock`, or null
+ */
+function resolveGlobalNpmForgedockDir() {
+  try {
+    const globalRoot = execSync("npm root -g", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+    if (!globalRoot) return null;
+    return resolve(join(globalRoot, "forgedock"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect whether FORGE_HOME resolves inside npm's global install tree, i.e.
+ * this process is running as a globally-installed `forgedock` package (not
+ * an ephemeral npx/dlx cache extraction). Used by update()'s npm-mode branch
+ * (forge#2133) to decide whether a newer published version can be installed
+ * in place with `npm install -g forgedock@latest`, versus the npx-cache case
+ * where there is nothing durable to reinstall over.
+ *
+ * Resolution: `resolveGlobalNpmForgedockDir()` (forge#2273) reports where npm's
+ * global install tree would place a `forgedock` package; if FORGE_HOME sits
+ * under that path, this is a global install. Fails closed (returns false) on
+ * any error — the pre-existing advisory-only behavior is always a safe
+ * fallback when detection is inconclusive.
+ *
+ * @returns {boolean}
+ */
+function isGlobalNpmInstall() {
+  const globalPkgDir = resolveGlobalNpmForgedockDir();
+  if (!globalPkgDir) return false;
+  const home = resolve(FORGE_HOME);
+  return home === globalPkgDir || home.startsWith(globalPkgDir + sep);
+}
+
+/**
+ * Detect a separate global npm install of `forgedock` that is NOT the
+ * `FORGE_HOME` this process resolved to (forge#2220). This is the classic
+ * `npx`-shadowing scenario: running `npx forgedock update` from inside a
+ * ForgeDock git clone resolves `FORGE_HOME` to the clone (because the clone
+ * itself is the `forgedock` package on disk), so the git-clone update path
+ * runs and updates the checkout — while a genuinely separate global npm
+ * install elsewhere on disk is silently left untouched.
+ *
+ * Resolution mirrors `isGlobalNpmInstall()` via the shared
+ * `resolveGlobalNpmForgedockDir()` helper (forge#2273): if a `forgedock`
+ * package exists at the resolved global path AND it is a different path than
+ * the current `FORGE_HOME`, a separate global install exists. Fails closed
+ * (returns null) on any error or timeout — this is an advisory notice only
+ * and must never block or alter the update itself.
+ *
+ * @returns {string|null} absolute path to the separate global install, or null
+ */
+function findSeparateGlobalInstall() {
+  const globalPkgDir = resolveGlobalNpmForgedockDir();
+  if (!globalPkgDir) return null;
+  const home = resolve(FORGE_HOME);
+  if (home === globalPkgDir || home.startsWith(globalPkgDir + sep)) {
+    // Current FORGE_HOME already IS the global install — nothing separate.
+    return null;
+  }
+  return existsSync(globalPkgDir) ? globalPkgDir : null;
+}
+
+/**
+ * Maximum number of additional self-update re-exec attempts allowed after the
+ * first (i.e. up to MAX_SELF_UPDATE_ATTEMPTS + 1 total `npm install -g`
+ * attempts across the parent process and its re-exec'd children). Guards
+ * against unbounded recursion when `npm install -g` reports success but the
+ * resolved version never actually advances (stale registry mirror/proxy,
+ * cache issue, mismatched FORGE_HOME resolution) — see forge#2158.
+ */
+const MAX_SELF_UPDATE_ATTEMPTS = 1;
+
+/**
+ * Strict semver-shape check for a version string before it is interpolated
+ * into a shell-invoked command (see forge#2180). Intentionally narrow —
+ * digits-dot-digits-dot-digits with an optional `-prerelease`/`+build`
+ * suffix restricted to `[0-9A-Za-z.-]` — so it accepts every real value
+ * `fetchLatestVersion()` can return from the npm registry's `version` field,
+ * while rejecting anything containing shell metacharacters
+ * (`; | & $ \` ( ) < > " ' \n` etc.) that `shell: true` would otherwise
+ * hand straight to cmd.exe/`/bin/sh`.
+ *
+ * The regex above is fully anchored (`^...$`) but its quantifiers (`\d+`,
+ * `[0-9A-Za-z.-]+`) are unbounded, so shape validity alone does not bound
+ * string *length* — a pathologically long value could still match. This
+ * is defense-in-depth only (see forge#2195): the character-class
+ * restriction already rules out shell metacharacters at any length, and
+ * `fetchLatestVersion()`'s 65536-byte HTTP response cap already bounds
+ * `version` in practice. The explicit length cap below rejects oversized
+ * input before the regex ever runs, closing the gap outright rather than
+ * relying on an upstream cap this function has no visibility into.
+ *
+ * @param {string} version
+ * @returns {boolean}
+ */
+function isValidSemverShape(version) {
+  const MAX_VERSION_LENGTH = 100;
+  return (
+    typeof version === "string" &&
+    version.length <= MAX_VERSION_LENGTH &&
+    /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)
+  );
+}
+
+/**
+ * Install the newer published version globally via `npm install -g
+ * forgedock@{version}`, then re-exec this same file path (which npm has just
+ * overwritten with the new package's contents) so the rest of update()'s
+ * persist/relink phase runs against the *new* payload instead of the stale
+ * in-memory one (forge#2133 — previously the advisory-only branch would
+ * persist/relink from whatever was already resolved, silently downgrading
+ * a newer persisted ~/.forge/ or leaving the global install stuck on the
+ * old version indefinitely).
+ *
+ * Depth guard (forge#2158): the re-exec'd child process could, in principle,
+ * observe the same "newer version available" condition again (e.g. a stale
+ * registry mirror/proxy reports success without the resolved version ever
+ * advancing) and recurse indefinitely, each cycle blocking up to ~125s. The
+ * attempt count is propagated across the re-exec via the
+ * `FORGEDOCK_SELF_UPDATE_ATTEMPT` environment variable (parent process env is
+ * never mutated — the counter is only passed to the spawned child's own
+ * environment). Once `MAX_SELF_UPDATE_ATTEMPTS` is reached, this function
+ * fails loudly with an actionable message and returns `false` instead of
+ * attempting another install/re-exec cycle.
+ *
+ * Fail-open: any error during install or re-exec falls back to the
+ * pre-existing advisory message — the caller must treat a `false` return as
+ * "could not self-update, printed manual instructions instead."
+ *
+ * Windows note (forge#2180): `npm` is a `.cmd` batch launcher on Windows, and
+ * Node's `execFileSync`/`spawnSync` cannot invoke `.cmd`/`.bat` files without
+ * `shell: true` (nodejs/node#3675) — confirmed empirically on a real Windows
+ * 11 machine: `execFileSync("npm", [...])` ENOENTs, and even the exact
+ * `npm.cmd` filename EINVALs, without a shell. `shell: true` is required
+ * here so the install actually runs on Windows. Because that widens the
+ * command line to shell interpretation, `version` — sourced from an
+ * unauthenticated `https://registry.npmjs.org` response in
+ * `fetchLatestVersion()` — is validated against a strict semver shape
+ * (`isValidSemverShape`) before it is ever interpolated into the command,
+ * closing the injection surface `shell: true` would otherwise open (see the
+ * repo-wide execSync→execFileSync shell-injection hardening precedent in
+ * forge#1703/forge#413).
+ *
+ * @param {string} version - target version to install (e.g. "1.2.0")
+ * @returns {boolean} true if re-exec was launched (process will exit before
+ *   returning in the success path); false if self-update failed, was capped
+ *   by the depth guard, and the caller should fall back to advisory-only
+ *   behavior.
+ */
+function selfUpdateGlobalInstall(version) {
+  // Math.max(0, ...) clamps out negative values: `Number.parseInt(x, 10) || 0`
+  // only substitutes 0 for NaN/0/"" — a negative numeric string (e.g. a
+  // corrupted or manually-set FORGEDOCK_SELF_UPDATE_ATTEMPT="-1") is truthy
+  // and passes through unclamped, which would let a negative attempt count
+  // stay perpetually below MAX_SELF_UPDATE_ATTEMPTS. Defense-in-depth only —
+  // no known path sets this env var to a negative value today. (forge#2168)
+  const attempt = Math.max(
+    0,
+    Number.parseInt(process.env.FORGEDOCK_SELF_UPDATE_ATTEMPT, 10) || 0,
+  );
+
+  // `attempt` counts completed installs so far (0 = no installs yet). The
+  // guard must allow MAX_SELF_UPDATE_ATTEMPTS + 1 total installs (see the
+  // doc comment above this function) — i.e. it should only trip once
+  // `attempt` has already reached that total, not one call early. Using
+  // `>=` here tripped after only 1 install instead of the documented 2
+  // (forge#2203 — the retry this guard exists to allow never actually ran).
+  if (attempt > MAX_SELF_UPDATE_ATTEMPTS) {
+    console.log(
+      `  ${YELLOW}Self-update did not converge after ${attempt} attempt(s) — the installed version may not be advancing (stale registry mirror/cache?).${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  // Validate before this value ever reaches the shell-invoked install below
+  // (forge#2180) — fail open to the same advisory message a failed install
+  // would print, rather than throwing or passing an unvalidated string to
+  // `shell: true`.
+  if (!isValidSemverShape(version)) {
+    console.log(
+      `  ${YELLOW}Self-update aborted: received an unexpected version string ("${version}").${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  try {
+    console.log(`  Installing ${CYAN}forgedock@${version}${RESET} globally...`);
+    // shell: true is required to resolve npm.cmd on Windows (see the
+    // Windows note in this function's doc comment, forge#2180). `version`
+    // is validated as strict semver above before this point.
+    execFileSync("npm", ["install", "-g", `forgedock@${version}`], {
+      stdio: "inherit",
+      timeout: 120000,
+      shell: true,
+    });
+  } catch (err) {
+    console.log(
+      `  ${YELLOW}Global self-update failed: ${err && err.message ? err.message : String(err)}${RESET}`,
+    );
+    console.log(
+      `  Run ${CYAN}npm install -g forgedock@latest${RESET} manually, then ${CYAN}npx forgedock update${RESET} again.`,
+    );
+    return false;
+  }
+
+  console.log(
+    `  ${GREEN}Installed v${version}.${RESET} Re-running update to finish persist/relink...`,
+  );
+  try {
+    const result = spawnSync(process.execPath, [__filename, "update"], {
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        FORGEDOCK_SELF_UPDATE_ATTEMPT: String(attempt + 1),
+      },
+    });
+    // `result.signal` is set (non-null) when the re-exec'd child was
+    // terminated by a signal (e.g. SIGTERM/SIGKILL) rather than exiting
+    // cleanly — in that case `result.status` is `null`, and
+    // `result.status ?? 0` would silently collapse a killed child into a
+    // reported "success" (exit 0). Exit non-zero explicitly for the
+    // signal-killed case; the non-signaled path is unchanged. (forge#2159)
+    process.exit(result.signal ? 1 : (result.status ?? 0));
+    // Unreachable — process.exit() above terminates the process. Present
+    // only to satisfy linters expecting a return on every path.
+    return true;
+  } catch (err) {
+    console.log(
+      `  ${YELLOW}Could not re-run update after install: ${err && err.message ? err.message : String(err)}${RESET}`,
+    );
+    console.log(`  Run ${CYAN}npx forgedock update${RESET} again manually.`);
+    return false;
+  }
+}
+
 async function update() {
   console.log("");
   console.log(`${BOLD}ForgeDock${RESET} — Checking for updates`);
   console.log("");
 
-  console.log(`  Mode: global (~/.claude)`);
   console.log(`  ${dim(getLogoTagline("update"))}`);
 
   // Check if installed via npm (no .git directory) or via git clone
   const gitDir = join(FORGE_HOME, ".git");
   if (existsSync(gitDir)) {
+    // forge#2220 — state the actual install being updated. Printing this
+    // only after the git-dir check (rather than an unconditional "global"
+    // line before it) is the fix: a clone resolved via npx-shadowing was
+    // previously reported as "Mode: global (~/.claude)", which reads as
+    // "your global install was updated" when in fact only this checkout was.
+    console.log(`  Mode: git clone at ${CYAN}${FORGE_HOME}${RESET}`);
+    const separateGlobalInstall = findSeparateGlobalInstall();
+    if (separateGlobalInstall) {
+      console.log(
+        `  ${YELLOW}Note: this updates the git clone above. Your global npm install at ${separateGlobalInstall} was NOT touched.${RESET}`,
+      );
+      console.log(
+        `  ${YELLOW}Run 'npm update -g forgedock', or 'npx forgedock update' from outside a clone, to update it.${RESET}`,
+      );
+    }
     try {
       const branch = execSync("git rev-parse --abbrev-ref HEAD", {
         cwd: FORGE_HOME,
@@ -1498,6 +1781,25 @@ async function update() {
       const isDetached = branch === "HEAD";
       const needsCheckout = branch !== "main";
       if (needsCheckout) {
+        // Dirty-tree guard: refuse to move HEAD in this clone if there are
+        // uncommitted TRACKED changes. Untracked files are intentionally
+        // excluded (--untracked-files=no) so a clean checkout with stray
+        // scratch/log files does not spuriously block the update.
+        const porcelain = execFileSync(
+          "git",
+          ["status", "--porcelain", "--untracked-files=no"],
+          { cwd: FORGE_HOME, encoding: "utf-8" },
+        ).trim();
+        if (porcelain) {
+          console.log(
+            `  ${YELLOW}Working tree has uncommitted changes on branch ${branch} — skipping update.${RESET}`,
+          );
+          console.log(
+            `  ${YELLOW}Commit or stash your changes before updating, or run from a clean clone. HEAD was NOT moved.${RESET}`,
+          );
+          return;
+        }
+
         if (isDetached) {
           console.log(
             `  ${YELLOW}Detached HEAD state — switching to main for update.${RESET}`,
@@ -1507,7 +1809,7 @@ async function update() {
             `  On branch ${CYAN}${branch}${RESET} — switching to ${CYAN}main${RESET} for update...`,
           );
         }
-        execSync("git checkout main --quiet", { cwd: FORGE_HOME });
+        execFileSync("git", ["checkout", "main", "--quiet"], { cwd: FORGE_HOME });
       }
 
       const before = execSync("git rev-parse HEAD", {
@@ -1534,7 +1836,7 @@ async function update() {
       // Restore original branch after a successful update.
       if (needsCheckout && !isDetached) {
         try {
-          execSync(`git checkout ${branch} --quiet`, { cwd: FORGE_HOME });
+          execFileSync("git", ["checkout", branch, "--quiet"], { cwd: FORGE_HOME });
           console.log(
             `  Restored branch ${CYAN}${branch}${RESET}.`,
           );
@@ -1554,6 +1856,18 @@ async function update() {
     // cache path (`npx forgedock`), which was never globally installed, so
     // "npm update -g forgedock" is a no-op. Check the actual published
     // version instead and give advice that reflects the real install model.
+    //
+    // forge#2220 — state the actual resolved install kind + path up front,
+    // computed once and reused below, so the mode line can never drift from
+    // the branch actually taken (isGlobalNpmInstall() is also consulted
+    // later to decide whether to self-update in place).
+    const globalInstall = isGlobalNpmInstall();
+    console.log(
+      globalInstall
+        ? `  Mode: global npm install at ${CYAN}${FORGE_HOME}${RESET}`
+        : `  Mode: npx (ad-hoc, not installed) — resolved from ${CYAN}${FORGE_HOME}${RESET}`,
+    );
+
     const localVersion = getVersion();
     const latestVersion = await fetchLatestVersion();
 
@@ -1569,8 +1883,25 @@ async function update() {
       console.log(
         `  ${GREEN}New version available: v${latestVersion}${RESET} (you have v${localVersion}).`,
       );
-      console.log(`  Run ${CYAN}npx forgedock@latest${RESET} to fetch it.`);
       await printVersionAvailableChangelog(localVersion, latestVersion);
+
+      // forge#2133 — a global npm install can actually be upgraded in place;
+      // do that instead of only printing an advisory (which previously left
+      // global installs stuck on whatever version was first installed,
+      // since every subsequent `npx forgedock update` re-resolves the same
+      // stale global binary). selfUpdateGlobalInstall() re-execs and exits
+      // the process on success, so anything after this block only runs when
+      // self-update wasn't attempted or failed.
+      if (globalInstall) {
+        selfUpdateGlobalInstall(latestVersion);
+        // selfUpdateGlobalInstall() only returns (rather than exiting the
+        // process) when the install or re-exec failed — it already printed
+        // manual-recovery instructions, so fall through to the persist
+        // refresh below using the still-stale local payload (fail-open,
+        // matches pre-existing behavior for this failure case).
+      } else {
+        console.log(`  Run ${CYAN}npx forgedock@latest${RESET} to fetch it.`);
+      }
     } else {
       console.log(`  Already up to date (v${localVersion}).`);
     }
@@ -2937,22 +3268,37 @@ async function demo() {
 /**
  * `forgedock watch` — live per-agent orchestration view
  *
- * Polls GitHub every 5 seconds for in-flight issues (those with workflow:*
- * labels) and renders a per-agent table with issue#, title, phase, elapsed
- * time, and staleness status.  All data is sourced from FORGE:HEARTBEAT
- * comments written by the pipeline at each phase boundary.
+ * Polls GitHub every 5 seconds for in-flight issues (those carrying any
+ * label in the workflow-prefixed / needs-human family, derived from
+ * bin/labels.json — see deriveWorkflowLabels() in bin/watch-utils.mjs,
+ * forge#2235) and renders
+ * a per-agent table with issue#, title, phase, elapsed time, and staleness
+ * status. All data is sourced from FORGE:HEARTBEAT comments written by the
+ * pipeline at each phase boundary.
+ *
+ * A second, independent "Findings" lane renders review-finding issues
+ * regardless of workflow:* state (forge#2235) — a finding is born without
+ * any workflow:* label and may never acquire one (deferred findings), so it
+ * must not depend on the in-flight label set to be visible. Findings render
+ * with a distinct queued/deferred/validated status, never "running".
  *
  * Stalled agents (no HEARTBEAT update within pipeline.stall_timeout_minutes)
  * are highlighted in yellow.
  *
+ * If `forge.yaml` defines `repos.satellites`, each satellite repo is watched
+ * in its own section in addition to the default/`--repo` repo.
+ *
  * Run:  npx forgedock watch [--repo owner/repo]
  * Exit: Ctrl+C
  */
 async function watch() {
   const POLL_INTERVAL_MS = 5000;
   const USE_ANSI_WATCH = process.stdout.isTTY === true && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+  const ISSUE_LIST_LIMIT = 500; // forge#2235 — was 30; matches phase-1-resolve.md's --limit 500 mandate
+  const HEARTBEAT_BATCH_CHUNK_SIZE = 25; // keep GraphQL query size/complexity bounded
 
-  // ── Resolve repo ──────────────────────────────────────────────────────────
+  // ── Resolve repo(s) ────────────────────────────────────────────────────────
+  const explicitRepoFlag = restArgs.includes("--repo");
   const watchRepo = resolveLabelsRepo(restArgs);
   if (!watchRepo) {
     process.stderr.write(
@@ -2963,6 +3309,22 @@ async function watch() {
     return;
   }
 
+  // Satellite repos (forge.yaml → repos.satellites) are watched in addition
+  // to the primary repo, unless the caller explicitly overrode --repo (an
+  // explicit --repo means "just this one repo"). Returns [] when no
+  // satellites section is present, so single-repo behavior is unchanged.
+  let satelliteRepos = [];
+  if (!explicitRepoFlag) {
+    const forgeYamlPathForSatellites = join(process.cwd(), "forge.yaml");
+    if (existsSync(forgeYamlPathForSatellites)) {
+      try {
+        const raw = readFileSync(forgeYamlPathForSatellites, "utf-8");
+        satelliteRepos = parseSatelliteRepos(raw).filter((r) => r !== watchRepo);
+      } catch { /* ignore — stay default-repo-only */ }
+    }
+  }
+  const watchedRepos = [watchRepo, ...satelliteRepos];
+
   // ── Validate gh CLI auth ───────────────────────────────────────────────────
   try {
     execSync("gh auth status", { stdio: ["ignore", "pipe", "ignore"] });
@@ -3026,26 +3388,88 @@ async function watch() {
   }
 
   // ── Render loop ────────────────────────────────────────────────────────────
-  const WORKFLOW_LABELS = [
-    "workflow:investigating",
-    "workflow:ready-to-build",
-    "workflow:building",
-    "workflow:in-review",
-    "needs-human",
-  ];
+  // Derived from bin/labels.json (forge#2235) instead of a hardcoded literal,
+  // so a newly-added workflow:* label (e.g. workflow:engine-error) is watched
+  // automatically without a code change. Falls back to a conservative
+  // built-in list if the manifest is missing/unreadable.
+  const WORKFLOW_LABELS = deriveWorkflowLabels(join(__dirname, "labels.json"));
+
+  // Batch-fetch the latest FORGE:HEARTBEAT comment for a set of issue numbers
+  // in ONE `gh api graphql` round-trip (chunked) instead of one REST call per
+  // issue (forge#2235 — de-N+1). Falls back to the old per-issue REST fetch
+  // for the whole set on any GraphQL error, so this optimization can never
+  // make watch() go blind.
+  async function fetchHeartbeatsBatch(repo, issueNumbers) {
+    const result = new Map();
+    if (issueNumbers.length === 0) return result;
+    const [owner, name] = repo.split("/");
+    if (!owner || !name) return fetchHeartbeatsPerIssueFallback(repo, issueNumbers);
 
-  async function render() {
-    const rows = [["#", "Title", "Phase", "Elapsed", "Status"]];
+    try {
+      for (const chunk of chunkArray(issueNumbers, HEARTBEAT_BATCH_CHUNK_SIZE)) {
+        const query = buildHeartbeatBatchQuery(owner, name, chunk);
+        const raw = execFileSync(
+          "gh",
+          ["api", "graphql", "-f", `query=${query}`],
+          { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
+        );
+        const parsed = parseHeartbeatBatchResponse(JSON.parse(raw));
+        for (const [num, body] of parsed) result.set(num, body);
+      }
+      return result;
+    } catch {
+      // GraphQL batch failed (auth scope gap, malformed query, rate limit) —
+      // fall back to the pre-forge#2235 per-issue REST behavior so watch()
+      // degrades gracefully instead of losing heartbeat data entirely.
+      return fetchHeartbeatsPerIssueFallback(repo, issueNumbers);
+    }
+  }
+
+  function fetchHeartbeatsPerIssueFallback(repo, issueNumbers) {
+    const result = new Map();
+    for (const num of issueNumbers) {
+      try {
+        const commentsJson = execFileSync(
+          "gh",
+          ["api", `repos/${repo}/issues/${num}/comments`,
+           "--jq", "[.[] | select(.body | contains(\"FORGE:HEARTBEAT\"))] | last | .body // \"\""],
+          { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
+        ).trim();
+        if (commentsJson && commentsJson !== '""' && commentsJson !== "") {
+          result.set(num, commentsJson.replace(/^"|"$/g, "").replace(/\\n/g, "\n"));
+        } else {
+          result.set(num, null);
+        }
+      } catch {
+        result.set(num, null);
+      }
+    }
+    return result;
+  }
+
+  // Renders a normalized priority for the "Pri" column, accepting both the
+  // canonical `priority:P<n>` label form and the bare `P<n>` form used by
+  // some consumer repos (forge#2232 / forge#2235).
+  function priorityCell(issue) {
+    return normalizePriority(issue.labels || []) || "—";
+  }
+
+  async function renderRepo(repo) {
+    const rows = [["#", "Pri", "Title", "Phase", "Elapsed", "Status"]];
+    const findingsRows = [["#", "Pri", "Title", "Status"]];
     let anyIssues = false;
+    const inFlightNumbers = new Set();
+    const issuesByLabel = [];
 
+    // ── In-flight lane: one query per workflow:*/needs-human label ──────────
     for (const label of WORKFLOW_LABELS) {
       let issueJson;
       try {
-        // Use execFileSync with argument array to avoid shell injection via watchRepo
+        // Use execFileSync with argument array to avoid shell injection via repo
         issueJson = execFileSync(
           "gh",
-          ["issue", "list", "-R", watchRepo, "--state", "open",
-           "--label", label, "--limit", "30", "--json", "number,title"],
+          ["issue", "list", "-R", repo, "--state", "open",
+           "--label", label, "--limit", String(ISSUE_LIST_LIMIT), "--json", "number,title,labels"],
           { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
         );
       } catch {
@@ -3055,26 +3479,32 @@ async function watch() {
       let issues;
       try { issues = JSON.parse(issueJson); } catch { continue; }
 
+      if (issues.length === ISSUE_LIST_LIMIT) {
+        process.stderr.write(
+          `${YELLOW}WARNING: label '${label}' on ${repo} returned exactly ${ISSUE_LIST_LIMIT} issues — ` +
+          `results may be truncated.${RESET}\n`,
+        );
+      }
+
+      issuesByLabel.push({ label, issues });
+      for (const issue of issues) inFlightNumbers.add(issue.number);
+    }
+
+    // Batch-fetch heartbeats once for every in-flight issue across all labels
+    const heartbeats = await fetchHeartbeatsBatch(repo, [...inFlightNumbers]);
+
+    for (const { label, issues } of issuesByLabel) {
       for (const issue of issues) {
         anyIssues = true;
         let phase = label.replace("workflow:", "");
         let elapsed = null;
 
-        // Fetch latest FORGE:HEARTBEAT comment for phase + timestamp
-        try {
-          const commentsJson = execFileSync(
-            "gh",
-            ["api", `repos/${watchRepo}/issues/${issue.number}/comments`,
-             "--jq", "[.[] | select(.body | contains(\"FORGE:HEARTBEAT\"))] | last | .body // \"\""],
-            { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
-          ).trim();
-          if (commentsJson && commentsJson !== '""' && commentsJson !== "") {
-            const body = commentsJson.replace(/^"|"$/g, "").replace(/\\n/g, "\n");
-            phase = extractPhase(body) || phase;
-            const ts = extractTimestamp(body);
-            elapsed = elapsedMin(ts);
-          }
-        } catch { /* use label-derived phase */ }
+        const body = heartbeats.get(issue.number);
+        if (body) {
+          phase = extractPhase(body) || phase;
+          const ts = extractTimestamp(body);
+          elapsed = elapsedMin(ts);
+        }
 
         const isStalled = elapsed !== null && elapsed >= stallMinutes;
         const isBlocked = label === "needs-human";
@@ -3093,6 +3523,7 @@ async function watch() {
 
         rows.push([
           `#${issue.number}`,
+          priorityCell(issue),
           titleColored,
           phaseShort,
           elapsedStr(elapsed),
@@ -3101,7 +3532,60 @@ async function watch() {
       }
     }
 
+    // ── Findings lane: review-finding issues, regardless of workflow:* state ─
+    // A finding is born without any workflow:* label and may never acquire
+    // one (deferred/PERMANENT_DEFERRED findings) — this lane makes them
+    // visible from creation instead of only during the narrow in-flight
+    // window (forge#2235).
+    let anyFindings = false;
+    try {
+      const findingsJson = execFileSync(
+        "gh",
+        ["issue", "list", "-R", repo, "--state", "open",
+         "--label", FINDINGS_LANE_LABEL, "--limit", String(ISSUE_LIST_LIMIT), "--json", "number,title,labels"],
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] },
+      );
+      const findings = JSON.parse(findingsJson);
+      if (findings.length === ISSUE_LIST_LIMIT) {
+        process.stderr.write(
+          `${YELLOW}WARNING: label '${FINDINGS_LANE_LABEL}' on ${repo} returned exactly ${ISSUE_LIST_LIMIT} issues — ` +
+          `results may be truncated.${RESET}\n`,
+        );
+      }
+      for (const issue of findings) {
+        // Findings that already carry a workflow:* label are in-flight and
+        // already rendered above — do not double-render them here.
+        if (hasWorkflowLabel(issue.labels || [], WORKFLOW_LABELS)) continue;
+
+        anyFindings = true;
+        const findingStatus = classifyFindingStatus(issue.labels || []); // validated | false-positive | queued | deferred
+        const statusDisplay = findingStatus.toUpperCase();
+        const statusColored = USE_ANSI_WATCH
+          ? (findingStatus === "validated" ? `\x1b[32m${statusDisplay}\x1b[0m`
+             : findingStatus === "false-positive" ? `\x1b[90m${statusDisplay}\x1b[0m`
+             : `\x1b[36m${statusDisplay}\x1b[0m`) // queued / deferred
+          : statusDisplay;
+
+        const titleTrunc = issue.title.length > 38 ? issue.title.slice(0, 35) + "..." : issue.title;
+
+        findingsRows.push([
+          `#${issue.number}`,
+          priorityCell(issue),
+          titleTrunc,
+          statusColored,
+        ]);
+      }
+    } catch { /* findings lane best-effort — never blocks the in-flight table */ }
+
+    return { repo, rows, anyIssues, findingsRows, anyFindings };
+  }
+
+  async function render() {
     const now = new Date().toISOString().replace("T", " ").slice(0, 19) + " UTC";
+    const results = [];
+    for (const repo of watchedRepos) {
+      results.push(await renderRepo(repo));
+    }
 
     if (USE_ANSI_WATCH) {
       process.stdout.write("\x1b[2J\x1b[H"); // clear screen + home
@@ -3109,12 +3593,26 @@ async function watch() {
       process.stdout.write(`\n${"─".repeat(60)}\n`);
     }
 
-    process.stdout.write(`${BOLD}ForgeDock Watch${RESET} — ${dim(watchRepo)}  ${dim(now)}\n\n`);
+    const repoLabel = watchedRepos.length > 1 ? `${watchedRepos.length} repos` : watchRepo;
+    process.stdout.write(`${BOLD}ForgeDock Watch${RESET} — ${dim(repoLabel)}  ${dim(now)}\n\n`);
 
-    if (!anyIssues || rows.length === 1) {
-      process.stdout.write(`  ${dim("No in-flight issues. All quiet.")}\n`);
-    } else {
-      process.stdout.write(table(rows, { header: true }));
+    for (const { repo, rows, anyIssues, findingsRows, anyFindings } of results) {
+      if (watchedRepos.length > 1) {
+        process.stdout.write(`${BOLD}${repo}${RESET}\n`);
+      }
+
+      if (!anyIssues || rows.length === 1) {
+        process.stdout.write(`  ${dim("No in-flight issues. All quiet.")}\n`);
+      } else {
+        process.stdout.write(table(rows, { header: true }));
+      }
+
+      if (anyFindings && findingsRows.length > 1) {
+        process.stdout.write(`\n${BOLD}Findings${RESET} ${dim("(review-finding — queued/deferred/validated)")}\n`);
+        process.stdout.write(table(findingsRows, { header: true }));
+      }
+
+      if (watchedRepos.length > 1) process.stdout.write("\n");
     }
 
     if (USE_ANSI_WATCH) {
@@ -3238,7 +3736,17 @@ switch (command) {
   case "run-issue": {
     const { runFromCli } = await import("./engine-cli.mjs");
     try {
-      await runFromCli(restArgs);
+      const result = await runFromCli(restArgs);
+      // forge#2175: make a needs-human escalation distinguishable from a
+      // successful run by exit code, mirroring the resume-stalled case's
+      // existing convention below (result.failed.length > 0 -> exitCode 1).
+      // forge#2261: "engine-error" (the engine/tool itself broke — a fail-fast
+      // CLI_BACKEND_FAILED/NO_API_KEY/NO_SDK, or an exhausted retry loop where
+      // the runner never once succeeded) previously reached this same case via
+      // an uncaught throw, which already set exitCode = 1 below. Now that
+      // runIssue() resolves cleanly with a terminalReason instead of throwing,
+      // preserve that same non-zero exit code for this reason too.
+      if (result && (result.terminalReason === "needs-human" || result.terminalReason === "engine-error")) exitCode = 1;
     } catch (err) {
       process.stderr.write(`${RED}${err.message}${RESET}\n`);
       exitCode = 1;