forgedock 1.1.7 → 1.1.9

package/README.md

@@ -221,11 +221,10 @@ More ship today (web-property analytics, browser QA sweeps, self-benchmarking)
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
 ```bash
-npx forgedock          # project-scoped install: checks your environment, installs commands for this repo, detects your repo, and hands you a reviewed forge.yaml
-npx forgedock --global # global install: installs into ~/.claude/commands/ — available in every Claude Code session on this machine
+npx forgedock # checks your environment, installs commands into ~/.claude/commands/ (available in every Claude Code session on this machine), detects your repo, and hands you a reviewed forge.yaml
 ```
 
-**Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
+**Install is always global**, to `~/.claude/commands/`. `--global` is still accepted on the command line for backward compatibility but has no effect — there's no other install location to opt out of.
 
 > **Want engine-mode dispatch?** `npx forgedock` is transient — the `forgedock` binary isn't persisted in PATH after install. `/orchestrate` and `/autopilot` use agent dispatch mode by default, which is fully functional. To enable engine-mode dispatch (`forgedock run-issue`) with its durable phase table and fail-closed review gate, run `npm install -g forgedock` instead.
 
@@ -253,15 +252,13 @@ Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock
 
 **Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan; with an `ANTHROPIC_API_KEY`, `npx forgedock run` drives the same command specs through a hardened tool-use loop, and `npx forgedock run-issue <issue>` executes them on the durable engine (event-sourced run log, leases, crash-safe resume).
 
-**Install modes:**
+**Explicit install command:**
 
 ```bash
-npx forgedock install           # project-scoped: <cwd>/.claude/commands/ (default)
-npx forgedock install --global  # global: ~/.claude/commands/ (opt-in)
+npx forgedock install           # installs into ~/.claude/commands/
+npx forgedock install --global  # same thing — --global is accepted but is a no-op
 ```
 
-`uninstall`, `update`, and `doctor` auto-detect which mode is installed — no need to re-specify `--global` after a global install. To explicitly target global: `npx forgedock doctor --global`.
-
 **Maintenance:**
 
 ```bash
@@ -269,9 +266,9 @@ npx forgedock update      # relink commands + refresh the SessionStart hook
 npx forgedock enable      # turn ForgeDock on for this directory
 npx forgedock disable     # turn ForgeDock off for this directory
 npx forgedock status      # show ForgeDock's state for this directory
-npx forgedock doctor      # installation health check with fix hints (auto-detects mode)
+npx forgedock doctor      # installation health check with fix hints
 npx forgedock report      # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
-npx forgedock uninstall   # remove commands, the hook, and tracked copies (auto-detects mode)
+npx forgedock uninstall   # remove commands, the hook, and tracked copies
 npx forgedock help        # show everything
 ```
 
@@ -280,31 +277,11 @@ npx forgedock help        # show everything
 </details>
 
 <details>
-<summary><strong>Migrating from a global install</strong></summary>
-
-If you installed ForgeDock before project-scoped became the default, your commands live in `~/.claude/commands/`. You have two paths forward:
-
-**Keep the global install** — add `--global` going forward and nothing changes:
-
-```bash
-npx forgedock --global   # install / update globally as before
-```
+<summary><strong>A note on install location</strong></summary>
 
-**Switch to project-scoped** (recommended for multi-repo setups):
-
-```bash
-# 1. Check your current install mode
-npx forgedock status
-
-# 2. Remove the global install
-npx forgedock uninstall --global
-
-# 3. Install project-scoped in each repo you use ForgeDock in
-cd /path/to/your/project
-npx forgedock
-```
+ForgeDock briefly experimented with a project-scoped-by-default install mode. It was backed out after causing a "split-brain" bug (`detect` assumed project-scoped while the installer still wrote globally — [#1589](https://github.com/RapierCraftStudios/ForgeDock/issues/1589)), so every version you'd realistically install today only ever writes to `~/.claude/commands/`. `--global` is still accepted as a flag for old scripts/muscle memory, but it changes nothing.
 
-Run `npx forgedock doctor` after switching to confirm everything is healthy.
+If you're carrying an older `--global` habit in scripts or CI, it's harmless to leave it — `npx forgedock --global` and `npx forgedock` do exactly the same thing.
 
 </details>
 

package/bin/cinema.mjs

@@ -200,14 +200,32 @@ function badgeText(badge, mode) {
   return `${fg(rgb, mode)}[${label}]\x1b[0m`;
 }
 
-/** Ember-bordered fix card (wraps tui.box; border color applied when able). */
-export function fixCard(lines, mode) {
+/**
+ * Severity-banded fix card (wraps tui.box; border color/weight applied when
+ * able).
+ *
+ * - "error"   (default): ember/red bordered box — current look, unchanged.
+ * - "warning": amber bordered box — lighter than error, still boxed.
+ * - "info":    no border — plain, dimmed lines only.
+ *
+ * @param {string[]} lines
+ * @param {string} mode
+ * @param {'error'|'warning'|'info'} [severity]
+ */
+export function fixCard(lines, mode, severity = "error") {
+  if (severity === "info") {
+    const padded = lines.map((l) => ` ${l} `);
+    if (mode === "none") return padded.join("\n");
+    return padded.map((l) => `\x1b[2m${l}\x1b[22m`).join("\n");
+  }
+
   const boxed = box(lines.map((l) => ` ${l} `), { title: "fix" });
   if (mode === "none") return boxed;
-  const ember = fg([255, 107, 53], mode);
+  const rgb = severity === "warning" ? [232, 192, 96] : [255, 107, 53];
+  const color = fg(rgb, mode);
   return boxed
     .split("\n")
-    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${ember}${m}\x1b[0m`))
+    .map((l) => l.replace(/[╭╮╰╯─│]/gu, (m) => `${color}${m}\x1b[0m`))
     .join("\n");
 }
 
@@ -253,7 +271,7 @@ export async function revealRows(
     }
     writer.write(formatRow(row.label, res, mode) + "\n");
     if (!res.ok && res.fix && res.fix.length > 0) {
-      writer.write(fixCard(res.fix, mode) + "\n");
+      writer.write(fixCard(res.fix, mode, res.severity || "error") + "\n");
     }
     results.push(res);
   }

package/bin/engine/invariants.mjs

@@ -0,0 +1,361 @@
+/**
+ * bin/engine/invariants.mjs — ForgeDock pipeline invariant evaluator.
+ *
+ * Evaluates three classes of invariants declared in forge-invariants.yaml:
+ *
+ *   pretooluse  — preconditions checked in pre-tool-use.mjs before tool
+ *                 execution (e.g. branch-must-exist-on-remote)
+ *   runlog      — temporal ordering rules over the append-only run-log
+ *                 (e.g. review-precedes-merge)
+ *   close       — terminal-state assertions checked before trajectory post
+ *                 (e.g. issue-closed-at-terminal)
+ *
+ * === Design constraints ===
+ *
+ * • No circular imports: only imports node:fs, node:child_process, node:path,
+ *   node:url. Does NOT import engine.mjs or phases.mjs.
+ * • Fail-open: every exported function returns a result object on error
+ *   rather than throwing. A missing forge-invariants.yaml or yq returns [].
+ * • Single-pass temporal evaluation: O(n) over the run-log event list.
+ *   No GitHub API calls.
+ * • Named violations: every failed result includes { ok: false, id, violated }
+ *   so callers can surface the proposition by name.
+ *
+ * === Usage ===
+ *
+ * // Load all declared invariants:
+ * const invariants = loadInvariants(forgeInvariantsYamlPath);
+ *
+ * // Evaluate temporal rules over a run-log event stream:
+ * const results = evaluateTemporalRules(invariants, events);
+ *
+ * // Check a hook precondition (branch must exist):
+ * const result = await checkPrecondition(invariants, "branch_must_exist_on_remote", { branch });
+ *
+ * // Assert close-time invariants before posting trajectory:
+ * const results = assertCloseInvariants(invariants, events);
+ */
+
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ---------------------------------------------------------------------------
+// YAML loader — uses yq (pipeline dependency) for proper array support.
+// forge-utils.mjs's minimal parser does not handle YAML sequences.
+// ---------------------------------------------------------------------------
+
+/**
+ * Load invariant declarations from forge-invariants.yaml.
+ *
+ * Returns an empty array if:
+ *   - forge-invariants.yaml is absent (fresh install before file ships)
+ *   - yq is not installed (graceful degradation)
+ *   - any parse error occurs
+ *
+ * @param {string} [yamlPath] Absolute path to forge-invariants.yaml.
+ *   Defaults to {repo root}/forge-invariants.yaml resolved relative to
+ *   this file's location.
+ * @returns {Invariant[]}
+ */
+export function loadInvariants(yamlPath) {
+  // Default: resolve relative to bin/engine/ → repo root / forge-invariants.yaml
+  const DEFAULT_PATH = resolve(
+    fileURLToPath(import.meta.url),
+    "..", "..", "..", "forge-invariants.yaml",
+  );
+  const target = yamlPath || DEFAULT_PATH;
+
+  if (!existsSync(target)) return []; // file absent — fail-open, not an error
+
+  try {
+    // Use yq to convert YAML → JSON (handles arrays; yq is a pipeline dep).
+    const json = execFileSync("yq", ["-o", "json", ".", target], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    const parsed = JSON.parse(json);
+    const items = parsed?.invariants;
+    if (!Array.isArray(items)) return [];
+    return items.filter(
+      (i) => i && typeof i.id === "string" && typeof i.scope === "string",
+    );
+  } catch {
+    // yq not installed, parse error, or any other failure — fail-open.
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Temporal rule evaluation (single-pass, O(n), no I/O)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate all runlog-scope invariants against an event list.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {object[]}    events      Event list from readLog() / deriveState().
+ * @returns {InvariantResult[]}
+ */
+export function evaluateTemporalRules(invariants, events) {
+  const rules = invariants.filter((i) => i.scope === "runlog");
+  if (!rules.length || !events.length) return rules.map((r) => ({ ok: true, id: r.id }));
+
+  // Single-pass: collect per-event-type positions.
+  const phaseCommits = {}; // phase id → first commit seq
+  let firstTerminal = null;
+  let terminalCount = 0;
+  let terminalReason = null;
+
+  for (const e of events) {
+    if (e.event === "PHASE_COMMIT" && e.phase) {
+      if (!(e.phase in phaseCommits)) phaseCommits[e.phase] = e.seq;
+    } else if (e.event === "RUN_TERMINAL") {
+      terminalCount++;
+      if (firstTerminal === null) { firstTerminal = e.seq; terminalReason = e.reason; }
+    }
+  }
+
+  return rules.map((r) => {
+    try {
+      return evaluateOneRule(r, { phaseCommits, firstTerminal, terminalCount, terminalReason });
+    } catch {
+      return { ok: true, id: r.id }; // evaluator error → fail-open
+    }
+  });
+}
+
+function evaluateOneRule(rule, { phaseCommits, firstTerminal, terminalCount, terminalReason }) {
+  switch (rule.id) {
+    case "review_precedes_merge": {
+      // Only check when the run ended with 'merged'.
+      if (terminalReason !== "merged") return { ok: true, id: rule.id };
+      const reviewSeq = phaseCommits["review"] ?? null;
+      if (reviewSeq === null || (firstTerminal !== null && reviewSeq > firstTerminal)) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `RUN_TERMINAL(merged) at seq ${firstTerminal} but no PHASE_COMMIT(review) precedes it`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    case "gate_event_precedes_review": {
+      const buildSeq = phaseCommits["build"] ?? null;
+      const reviewSeq = phaseCommits["review"] ?? null;
+      if (reviewSeq !== null && (buildSeq === null || buildSeq > reviewSeq)) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `PHASE_COMMIT(review) at seq ${reviewSeq} but PHASE_COMMIT(build) ${buildSeq === null ? "absent" : `at seq ${buildSeq} (after review)`}`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    case "terminal_state_once": {
+      if (terminalCount > 1) {
+        return {
+          ok: false, id: rule.id,
+          violated: rule.proposition,
+          detail: `RUN_TERMINAL appears ${terminalCount} times in run-log (expected ≤1)`,
+        };
+      }
+      return { ok: true, id: rule.id };
+    }
+
+    default:
+      // Unknown runlog invariant ID — fail-open (future invariants not yet in evaluator).
+      return { ok: true, id: rule.id };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Hook precondition checks (async — may shell out for git ls-remote)
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a named pretooluse-scope precondition.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {string}      id         Invariant ID to evaluate.
+ * @param {object}      context    Evaluation context (e.g. { branch, repoPath }).
+ * @returns {Promise<InvariantResult>}
+ */
+export async function checkPrecondition(invariants, id, context) {
+  const inv = invariants.find((i) => i.scope === "pretooluse" && i.id === id);
+  if (!inv) return { ok: true, id }; // not declared — fail-open
+
+  try {
+    return await evaluateOnePrecondition(inv, context);
+  } catch {
+    return { ok: true, id }; // evaluator error → fail-open
+  }
+}
+
+/**
+ * Evaluate all pretooluse-scope preconditions matching a named context.
+ * Returns all results so the caller can surface the first failure.
+ *
+ * @param {Invariant[]} invariants
+ * @param {object}      context
+ * @returns {Promise<InvariantResult[]>}
+ */
+export async function checkAllPreconditions(invariants, context) {
+  const rules = invariants.filter((i) => i.scope === "pretooluse");
+  const results = [];
+  for (const r of rules) {
+    try {
+      results.push(await evaluateOnePrecondition(r, context));
+    } catch {
+      results.push({ ok: true, id: r.id }); // fail-open
+    }
+  }
+  return results;
+}
+
+async function evaluateOnePrecondition(inv, context) {
+  switch (inv.id) {
+    case "branch_must_exist_on_remote": {
+      const branch = context?.branch;
+      if (!branch) return { ok: true, id: inv.id }; // no branch in context — skip
+
+      // git ls-remote --exit-code: exits 0 if ref found, 2 if not found.
+      // Use a cached local-only check first (avoids network round-trip when
+      // the branch is already fetched).
+      try {
+        execFileSync("git", ["rev-parse", "--verify", `origin/${branch}`], {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 5000,
+        });
+        return { ok: true, id: inv.id }; // local origin ref exists
+      } catch {
+        // Not in local refs — fall through to remote check.
+      }
+
+      try {
+        const url = getRemoteUrl();
+        if (!url) return { ok: true, id: inv.id }; // no remote configured — fail-open
+
+        execFileSync("git", ["ls-remote", "--exit-code", "origin", branch], {
+          encoding: "utf-8",
+          stdio: ["pipe", "pipe", "pipe"],
+          timeout: 10000,
+        });
+        return { ok: true, id: inv.id }; // remote ref found
+      } catch (e) {
+        const exitCode = e?.status ?? null;
+        if (exitCode === 2) {
+          // Exit code 2 from ls-remote means ref not found.
+          return {
+            ok: false, id: inv.id,
+            violated: inv.proposition,
+            detail: `Branch '${branch}' not found on origin — checkout would fail`,
+          };
+        }
+        // Other errors (network, auth, etc.) → fail-open.
+        return { ok: true, id: inv.id };
+      }
+    }
+
+    default:
+      return { ok: true, id: inv.id }; // unknown precondition — fail-open
+  }
+}
+
+function getRemoteUrl() {
+  try {
+    return execFileSync("git", ["remote", "get-url", "origin"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3000,
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Close-time assertions (synchronous — run-log only, no I/O)
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert close-scope invariants before the trajectory annotation is posted.
+ * These run in the close phase after the PR is merged and issue is closed.
+ *
+ * @param {Invariant[]} invariants  Full invariant list from loadInvariants().
+ * @param {object[]}    events      Event list from readLog().
+ * @returns {InvariantResult[]}
+ */
+export function assertCloseInvariants(invariants, events) {
+  const assertions = invariants.filter((i) => i.scope === "close");
+  if (!assertions.length) return [];
+
+  return assertions.map((a) => {
+    try {
+      return evaluateOneCloseAssertion(a, events);
+    } catch {
+      return { ok: true, id: a.id }; // evaluator error → fail-open
+    }
+  });
+}
+
+function evaluateOneCloseAssertion(assertion, events) {
+  switch (assertion.id) {
+    case "run_log_terminal_at_close": {
+      const hasTerminal = events.some((e) => e.event === "RUN_TERMINAL");
+      if (!hasTerminal) {
+        return {
+          ok: false, id: assertion.id,
+          violated: assertion.proposition,
+          detail: "RUN_TERMINAL event absent from run-log — pipeline may have exited abnormally",
+        };
+      }
+      return { ok: true, id: assertion.id };
+    }
+
+    case "issue_closed_at_terminal":
+      // This assertion is evaluated externally (requires a gh CLI call in the
+      // close phase). The evaluator returns ok=true here so callers that do
+      // not pass GitHub state still pass without error. The close.md phase
+      // block implements the actual gh issue view check.
+      return { ok: true, id: assertion.id };
+
+    default:
+      return { ok: true, id: assertion.id }; // unknown close assertion — fail-open
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Convenience: format a violation for human output
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a failed InvariantResult into a human-readable block.
+ * Safe to call on ok:true results (returns null).
+ *
+ * @param {InvariantResult} result
+ * @returns {string|null}
+ */
+export function formatViolation(result) {
+  if (result.ok) return null;
+  return [
+    `[ForgeDock] INVARIANT VIOLATION: ${result.id}`,
+    ``,
+    `Violated proposition: "${result.violated}"`,
+    result.detail ? `Detail: ${result.detail}` : "",
+  ].filter((l) => l !== undefined).join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// JSDoc types
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ id: string, scope: string, proposition: string, enforcement: string, description?: string }} Invariant
+ * @typedef {{ ok: boolean, id: string, violated?: string, detail?: string }} InvariantResult
+ */

package/bin/engine-cli.mjs

@@ -6,17 +6,48 @@
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { runIssue } from "./engine.mjs";
 import { makeProjector } from "./engine/projector.mjs";
+import { readLog, deriveState } from "./engine/runlog.mjs";
+
+/**
+ * Workflow labels that mark an issue as "in the pipeline" (not yet terminal).
+ * Shared by resume-stalled's candidate enumeration and countEngineActivity()
+ * (the re-entry dashboard's in-flight/stalled counter, #1945) so both surfaces
+ * agree on what "in-flight" means — a single source of truth rather than two
+ * lists that can silently drift apart.
+ */
+export const ACTIVE_WORKFLOW_LABELS = [
+  "workflow:investigating",
+  "workflow:ready-to-build",
+  "workflow:building",
+  "workflow:in-review",
+];
 
 const pexec = promisify(execFile);
 
-/** Real gh/git accessors. */
+/**
+ * Real gh/git accessors.
+ *
+ * `timeout: 10000` matches the convention already used for the sibling
+ * `gh pr list` call in the interactive dashboard (bin/forgedock.mjs's
+ * gatherDashboardData()). Every io.gh()/io.git() call site issues a single,
+ * normally-fast metadata command (gh issue view, gh api .../comments,
+ * gh pr list/view, git rev-list --count) — none are legitimately
+ * long-running — so one shared timeout is appropriate across all callers
+ * (the interactive status dashboard, run-issue, and resume-stalled). A
+ * hung/black-holed gh process (flaky network, corporate proxy, stuck auth
+ * prompt) would otherwise hang commands like `npx forgedock status`
+ * indefinitely (#1962). Callers already wrap every io.gh()/io.git() call in
+ * try/catch and degrade to null/"unknown" on any rejection, so a timeout
+ * fails closed gracefully with no additional error handling required.
+ */
 export function makeIo() {
   const run = (bin) => async (args) => {
-    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024 });
+    const { stdout } = await pexec(bin, args, { maxBuffer: 100 * 1024 * 1024, timeout: 10000 });
     return stdout;
   };
   return { gh: run("gh"), git: run("git") };
@@ -88,6 +119,106 @@ export async function scanStalls(issues, io, now) {
   return stalled;
 }
 
+/**
+ * Read-only in-flight/stalled counter for the `status`/`install` re-entry
+ * dashboard (#1945). Reuses the exact same enumeration + lease-expiry logic
+ * as `resumeStalledFromCli` (workflow-label search via `gh issue list`, then
+ * `scanStalls` against the GitHub-authoritative FORGE:STATE via the
+ * projector) — GitHub is this codebase's source of truth for run state, not
+ * the local `~/.forge/runs` hot-path log, so the dashboard counts the same
+ * way the orchestrator does. Never dispatches or mutates anything.
+ *
+ * Best-effort: a `gh issue list` failure for one label is swallowed (treated
+ * as zero matches for that label) — consistent with resumeStalledFromCli's
+ * existing tolerance — so one bad label search never blocks the others.
+ *
+ * @param {{gh: Function}} io
+ * @param {string|null} repo - "owner/repo", or null to use gh's cwd-resolved default
+ * @param {number} now
+ * @returns {Promise<{total: number, inFlight: number, stalled: number}>}
+ */
+export async function countEngineActivity(io, repo, now) {
+  const repoFlag = repo ? ["--repo", repo] : [];
+  const issueSet = new Set();
+
+  for (const label of ACTIVE_WORKFLOW_LABELS) {
+    try {
+      const out = await io.gh([
+        "issue", "list",
+        ...repoFlag,
+        "--state", "open",
+        "--label", label,
+        "--limit", "100",
+        "--json", "number",
+      ]);
+      const items = JSON.parse(out);
+      for (const { number } of items) issueSet.add(number);
+    } catch {
+      // gh may return non-zero when no issues match, or fail transiently —
+      // treat as empty for this label rather than aborting the whole count.
+    }
+  }
+
+  if (issueSet.size === 0) return { total: 0, inFlight: 0, stalled: 0 };
+
+  const projector = makeProjector(io);
+  const candidates = [...issueSet];
+  const stalled = await scanStalls(candidates, projector, now);
+  return { total: candidates.length, inFlight: candidates.length - stalled.length, stalled: stalled.length };
+}
+
+/**
+ * Best-effort summary of the most recently modified local run-log under
+ * `~/.forge/runs` (runDir()). This is a MACHINE-LOCAL view — the crash-safe
+ * hot-path log described in engine/runlog.mjs, not the GitHub-authoritative
+ * state used by countEngineActivity() above. Appropriate only for a "what did
+ * I last run here" dashboard row, not for cross-machine in-flight/stalled
+ * counts.
+ *
+ * Never throws: returns null when the runs dir doesn't exist, holds no
+ * `.jsonl` files, or the newest file can't be read/parsed. A single corrupt
+ * or unreadable file is skipped in favor of the next-newest one rather than
+ * failing the whole lookup (forge#1528 — batch operations here must not abort
+ * on one bad item).
+ *
+ * @param {string} dir - runDir()
+ * @returns {{issue: number, terminal: boolean, terminalReason: string|null} | null}
+ */
+export function lastLocalRun(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+  } catch {
+    return null;
+  }
+
+  // Sort newest-first by mtime so a corrupt newest file falls through to the
+  // next-newest candidate instead of giving up entirely.
+  const withMtime = [];
+  for (const f of entries) {
+    try {
+      withMtime.push({ f, mtime: statSync(join(dir, f)).mtimeMs });
+    } catch {
+      // unreadable — skip
+    }
+  }
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+
+  for (const { f } of withMtime) {
+    const issue = parseInt(f.slice(0, -".jsonl".length), 10);
+    if (!Number.isInteger(issue)) continue;
+    try {
+      const events = readLog(dir, issue);
+      if (events.length === 0) continue;
+      const state = deriveState(events);
+      return { issue, terminal: state.terminal, terminalReason: state.terminalReason };
+    } catch {
+      continue; // corrupt file — try the next-newest
+    }
+  }
+  return null;
+}
+
 /**
  * @param {string[]} argv
  * @param {{io?: {gh: Function}, runIssue?: Function}} [deps]
@@ -147,18 +278,13 @@ export async function resumeStalledFromCli(argv, deps = {}) {
   const projector = makeProjector(io);
   const now = Date.now();
 
-  // Collect candidate issue numbers from all non-terminal workflow labels.
-  const ACTIVE_LABELS = [
-    "workflow:investigating",
-    "workflow:ready-to-build",
-    "workflow:building",
-    "workflow:in-review",
-  ];
-
+  // Collect candidate issue numbers from all non-terminal workflow labels
+  // (ACTIVE_WORKFLOW_LABELS — shared with countEngineActivity() so both
+  // surfaces agree on what "in-flight" means).
   const repoFlag = repo ? ["--repo", repo] : [];
   const issueSet = new Set();
 
-  for (const label of ACTIVE_LABELS) {
+  for (const label of ACTIVE_WORKFLOW_LABELS) {
     try {
       const out = await io.gh([
         "issue", "list",