@yemi33/minions 0.1.2142 → 0.1.2144

package/docs/deprecated.json

@@ -109,5 +109,60 @@
     "removalGate": "Two conditions must hold simultaneously: (a) grep `engine/ado.js` for `isAdoThrottled\\s*\\(\\s*\\)` and confirm zero arg-less call sites remain across the engine — every caller passes a concrete `orgBase` resolved via `shared.getAdoOrgBase(project)`; (b) `GET /api/diagnostics/ado-throttle` on a live engine has been observed for >=2 consecutive weeks reporting per-org keys (proves the per-org Map is populated under load and the global-OR isn't masking a regression). Once both hold, removal deletes the arg-less branch in isAdoThrottled and the global-OR fold; callers that still pass no argument become an immediate, surfaced bug rather than a silent over-throttle.",
     "targetRemovalDate": "2026-08-03",
     "notes": "Introduced by W-mq03l6zh0006f0a1 (Per-org ADO throttle isolation). 60-day window (2 release cycles + buffer) gives the in-flight per-org migration time to land + observe per-org keys on the diagnostics endpoint. Observable live at GET /api/diagnostics/ado-throttle — the endpoint reports a single `global` key while the arg-less shim is still load-bearing, and per-org `<orgBase>` keys once isolation is complete; that key shape is the human-readable signal for whether this shim can retire."
+  },
+  {
+    "id": "pr-record-contextOnly-underscore-alias",
+    "description": "Legacy `pr._contextOnly` field on PR records (engine/<scope>/pull-requests.json + SQL). Renamed to canonical `pr.contextOnly` by the W-mq5s5ttx000j7ab8 PR-gate consolidation (the foundation sub-WI adds canonical `contextOnly` + a one-shot boot migration that copies `_contextOnly` → `contextOnly` for existing records). The underscore-prefixed alias is preserved on writes for one release so any out-of-process readers (dashboards, ops scripts) that still inspect `_contextOnly` continue to work.",
+    "code": [
+      { "file": "engine/shared.js", "note": "isAutoManagedPrRecord + normalizePrRecords write both `contextOnly` and `_contextOnly` until removal." },
+      { "file": "dashboard.js", "note": "GET /api/pull-requests responses include `_contextOnly` alias; POST /api/pull-requests/observe writes both fields until removal." },
+      { "file": "engine.js", "note": "discoverFromPrs reads `pr.contextOnly` only — `_contextOnly` is write-only legacy alias post-consolidation." }
+    ],
+    "deprecated": "2026-06-08",
+    "targetRemovalDate": "2026-06-16",
+    "notes": "Cleanup-date is 7 days from PR merge per the W-mq5s5ttx000j7ab8 docs sub-WI. Pair this entry's removal with `pr-record-autoObserve-underscore-alias`, `pr-record-manual-underscore-alias`, and `pr-link-autoObserve-body-param` — they share the same boot migration + dual-write window. Removal scope: delete the `_contextOnly` write site in `normalizePrRecords` (engine/shared.js), drop the `_contextOnly` field from `GET /api/pull-requests` shaping in dashboard.js, and remove the boot migration in engine/shared.js once telemetry confirms no record-with-`_contextOnly`-only on disk."
+  },
+  {
+    "id": "pr-record-autoObserve-underscore-alias",
+    "description": "Legacy `pr._autoObserve` boolean on PR records. Was one of 6 clauses in the old `isAutoManagedPrRecord` check; replaced by the canonical `pr.contextOnly` field (foreign-author PRs linked with `autoObserve: true` now land with `contextOnly: false` directly, so the dispatch gate no longer needs to inspect `_autoObserve`).",
+    "code": [
+      { "file": "engine/shared.js", "note": "isAutoManagedPrRecord no longer reads `_autoObserve`; normalizePrRecords still writes it for one release as a backward-compat alias." },
+      { "file": "dashboard.js", "note": "POST /api/pull-requests/link + POST /api/pull-requests/observe accept `contextOnly` as the canonical body param; `_autoObserve` is mirrored on the record for legacy readers." }
+    ],
+    "deprecated": "2026-06-08",
+    "targetRemovalDate": "2026-06-16",
+    "notes": "Cleanup-date is 7 days from PR merge per the W-mq5s5ttx000j7ab8 docs sub-WI. Removal is paired with `pr-record-contextOnly-underscore-alias` — same dual-write window, same boot migration. After removal, only `pr.contextOnly` exists on records; any external reader that still reads `_autoObserve` will get `undefined` and must migrate."
+  },
+  {
+    "id": "pr-record-manual-underscore-alias",
+    "description": "Legacy `pr._manual` boolean on PR records (set by `POST /api/pull-requests/link` to mark manually-linked PRs). Was the third clause in the old `isAutoManagedPrRecord` check (`pr._manual && !pr._contextOnly` → auto-managed). Post-consolidation, the dispatch gate reads only `pr.contextOnly`; the `_manual` provenance flag is preserved on records for dashboard display + audit but is no longer load-bearing for dispatch decisions.",
+    "code": [
+      { "file": "engine.js", "note": "discoverFromPrs no longer reads `_manual` post-consolidation (was at the inline `isAgentPr` check, now removed)." },
+      { "file": "engine/shared.js", "note": "isAutoManagedPrRecord no longer reads `_manual`; normalizePrRecords still writes it for one release as a provenance/UI alias." },
+      { "file": "dashboard.js", "note": "POST /api/pull-requests/link continues to set `_manual: true` for UI/audit; remove once dashboards stop displaying the badge." }
+    ],
+    "deprecated": "2026-06-08",
+    "targetRemovalDate": "2026-06-16",
+    "notes": "Disambiguation: this entry covers ONLY the PR-record `_manual` flag (engine/<scope>/pull-requests.json). Other `_manual`-named flags elsewhere in the engine (work items, dispatch records, etc.) are NOT covered by this entry and remain in active use. Cleanup-date is 7 days from PR merge per the W-mq5s5ttx000j7ab8 docs sub-WI; remove the write site in dashboard.js (POST /api/pull-requests/link record-build) and any remaining `_manual` reads in render-prs.js when dashboard UI no longer displays a 'manual link' badge."
+  },
+  {
+    "id": "pr-link-autoObserve-body-param",
+    "description": "Legacy `autoObserve` body parameter on `POST /api/pull-requests/link`. Replaced by canonical `contextOnly` body param (inverse boolean: `autoObserve: false` ⇔ `contextOnly: true`). Endpoint accepts both for one release: if `contextOnly` is present it wins; otherwise the handler maps `autoObserve` → `contextOnly = !autoObserve` and proceeds.",
+    "code": [
+      { "file": "dashboard.js", "note": "POST /api/pull-requests/link handler reads `body.contextOnly` first, then falls back to `!body.autoObserve` for backwards compat. Route registry params string still lists `autoObserve?` for one release." }
+    ],
+    "deprecated": "2026-06-08",
+    "targetRemovalDate": "2026-06-16",
+    "notes": "Cleanup-date is 7 days from PR merge per the W-mq5s5ttx000j7ab8 docs sub-WI. After removal, callers that still send `autoObserve` will see their value silently ignored (the record's `contextOnly` will fall back to whatever default the endpoint applies). Removal scope: drop the `body.autoObserve` fallback in the link handler in dashboard.js, drop `autoObserve?` from the route registry `params` string, and update any client (dashboard JS, ops scripts) that still POSTs `autoObserve`."
+  },
+  {
+    "id": "pr-observe-observe-body-param",
+    "description": "Legacy `observe` body parameter on `POST /api/pull-requests/observe`. The W-mq5s5ttx000j7ab8 endpoint sub-WI introduces canonical `contextOnly` as the inverse (`observe: false` ⇔ `contextOnly: true`) and keeps `observe` accepted for backward compat. Registering the deprecation here so the alias has a documented removal path; the WI explicitly notes this entry is the implementer's call (it is kept for backward compat and may live longer than the underscore-prefixed record fields).",
+    "code": [
+      { "file": "dashboard.js", "note": "POST /api/pull-requests/observe handler reads `body.contextOnly` first, then falls back to `!body.observe` for backwards compat." }
+    ],
+    "deprecated": "2026-06-08",
+    "targetRemovalDate": null,
+    "notes": "targetRemovalDate intentionally null — unlike the record-field aliases (`_contextOnly`, `_autoObserve`, `_manual`) which carry a 7-day clock, the `observe` body param is documented as a longer-lived back-compat alias. Set targetRemovalDate to a concrete future date once the dashboard UI + any client scripts are confirmed to POST `contextOnly` exclusively. Removal scope when the date is set: drop the `body.observe` fallback in dashboard.js, drop `observe` from the route registry params, and update any client still POSTing `observe`."
   }
 ]

package/engine/cleanup.js

@@ -1519,10 +1519,64 @@ function scrubStaleMetrics() {
   });
 }
 
+// ─── Periodic worktree GC sweep (W-mq5o6bvy000x7191 Layer 2 + 3) ────────────
+
+/**
+ * Periodic per-tick worktree sweep. Aggregates the two pruners in
+ * `engine/worktree-gc.js` so a long-lived engine catches orphans the
+ * boot-only reconcile would miss:
+ *
+ *   - `pruneOrphanWorktrees`: walks `<localPath>/<worktreeRoot>` and reaps
+ *     orphan W-* dirs with no matching dispatch.
+ *   - `pruneOrphanWorktreesFromGitRegistry`: walks `git worktree list` per
+ *     project and reaps registered worktrees outside the configured
+ *     `worktreeRoot` (covers `D:/tmp-*`, `D:/squad-worktrees/*`, etc.).
+ *
+ * Both pruners share the SAME `dispatchSnap` from `queries.getDispatch()`
+ * so live work isn't yanked between scans. Returns aggregate stats for
+ * tick-level logging.
+ */
+function runPeriodicWorktreeSweep(config) {
+  const worktreeGc = require('./worktree-gc');
+  const projects = getProjects(config);
+  if (projects.length === 0) {
+    return { scanned: 0, kept: 0, evicted: 0, failed: 0, outOfRootEvicted: 0, prunedRegistry: 0 };
+  }
+  const dispatchSnap = getDispatch();
+  const worktreeRootRel = config?.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot;
+  const _log = (lvl, msg) => log(lvl, msg);
+
+  let scanned = 0, kept = 0, evicted = 0, failed = 0, outOfRootEvicted = 0, prunedRegistry = 0;
+  const _writeToInbox = (a, s, c) => { try { return shared.writeToInbox(a, s, c); } catch (_e) { return false; } };
+  try {
+    const r1 = worktreeGc.pruneOrphanWorktrees({
+      projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
+    });
+    scanned += r1.scanned || 0;
+    kept += r1.kept || 0;
+    evicted += r1.evicted || 0;
+    failed += r1.failed || 0;
+  } catch (e) { log('warn', `worktree-gc periodic in-root: ${e.message}`); }
+
+  try {
+    const r2 = worktreeGc.pruneOrphanWorktreesFromGitRegistry({
+      projects, dispatchSnap, worktreeRootRel, log: _log, config, writeToInbox: _writeToInbox,
+    });
+    scanned += r2.scanned || 0;
+    kept += r2.kept || 0;
+    outOfRootEvicted += r2.evicted || 0;
+    failed += r2.failed || 0;
+    prunedRegistry += r2.prunedRegistry || 0;
+  } catch (e) { log('warn', `worktree-gc periodic out-of-root: ${e.message}`); }
+
+  return { scanned, kept, evicted, failed, outOfRootEvicted, prunedRegistry };
+}
+
 // ─── Exports ─────────────────────────────────────────────────────────────────
 
 module.exports = {
   runCleanup,
+  runPeriodicWorktreeSweep, // W-mq5o6bvy000x7191 — exported for engine.js tick wiring + testing
   scrubStaleMetrics,
   sweepLeakedTestMeetings,   // exported for testing
   pruneStaleBackupSidecars,  // P-c91d4f76 — exported for testing

package/engine/cli.js

@@ -192,15 +192,25 @@ function isHelpToken(arg) {
   return arg === '--help' || arg === '-h' || arg === 'help';
 }
 
-// W-mq07mjzi000s1cc9: Stricter guard for command first-positionals.
+// W-mq07mjzi000s1cc9 + W-mq5hk4u200081043: Stricter guard for command first-positionals.
 //
 // Real work-item titles, agent ids, plan source paths, and dispatch ids never
-// start with `--`. Rejecting any leading-`--` token catches the exact bug
-// reported (`--help`) plus typos like `--hep`, `--h`, `-help` that would
-// otherwise still slip through as ghost-WI titles.
+// start with `-` and are never bare `?`/`help`. Rejecting these catches the
+// exact bug reported (`--help`) plus single-dash typos (`-X`, `-quiet`),
+// question-mark probing (`?`), case-variant help (`Help`, `HELP`), and
+// whitespace-only arguments that would otherwise create ghost WIs.
+//
+// handleCommand's narrow `isHelpToken` interceptor still handles the canonical
+// `--help`/`-h`/`help` triplet by printing the global command list; anything
+// else falls through to this defensive per-command guard which prints
+// command-specific usage and exits 2.
 function looksLikeFlagOrHelp(arg) {
-  if (isHelpToken(arg)) return true;
-  return typeof arg === 'string' && arg.startsWith('--');
+  if (typeof arg !== 'string') return false;
+  const t = arg.trim();
+  if (!t) return true;
+  if (t.startsWith('-')) return true;
+  if (/^(help|\?)$/i.test(t)) return true;
+  return false;
 }
 
 // SoT for engine-CLI metadata: drives handleCommand's help text and the
@@ -920,10 +930,29 @@ const commands = {
           dispatchSnap,
           worktreeRootRel,
           log: (lvl, msg) => e.log(lvl, msg),
+          config: cfg,
+          writeToInbox: (a, s, c) => { try { return sharedMod.writeToInbox(a, s, c); } catch (_e) { return false; } },
         });
         if (result.evicted > 0 || result.failed > 0) {
           console.log(`  Worktree boot reconcile: evicted ${result.evicted} orphan worktree(s)${result.failed ? `, ${result.failed} failed` : ''} (scanned ${result.scanned}, kept ${result.kept})`);
         }
+        // W-mq5o6bvy000x7191 (Layer 3): out-of-root scan — catches worktrees
+        // registered in `git worktree list` but living outside the configured
+        // `worktreeRoot` (e.g. ad-hoc `D:/tmp-*/` dirs left by previous
+        // experiments). Same dispatch snapshot so branch protection is
+        // consistent. Also runs `git worktree prune --expire=now` per project
+        // so manually-removed dirs drop out of the registry immediately.
+        const regResult = worktreeGc.pruneOrphanWorktreesFromGitRegistry({
+          projects,
+          dispatchSnap,
+          worktreeRootRel,
+          log: (lvl, msg) => e.log(lvl, msg),
+          config: cfg,
+          writeToInbox: (a, s, c) => { try { return sharedMod.writeToInbox(a, s, c); } catch (_e) { return false; } },
+        });
+        if (regResult.evicted > 0 || regResult.failed > 0 || regResult.prunedRegistry > 0) {
+          console.log(`  Worktree registry reconcile: scanned ${regResult.scanned}, evicted ${regResult.evicted}, kept ${regResult.kept}, failed ${regResult.failed}, registry-pruned ${regResult.prunedRegistry}`);
+        }
       } catch (err) {
         e.log('warn', `Worktree boot reconcile failed: ${err.message}`);
       }

package/engine/dispatch.js

@@ -358,7 +358,7 @@ function getStalePrDispatchReason(entry, config) {
   const prLabel = entry.meta.pr?.id || entry.meta.pr?.url || entry.id;
   if (!tracked) return `PR ${prLabel} is no longer tracked`;
   if (tracked.status !== PR_STATUS.ACTIVE) return `PR ${tracked.id || prLabel} is ${tracked.status || 'missing status'}`;
-  if (tracked._contextOnly) return `PR ${tracked.id || prLabel} is context-only`;
+  if (tracked._contextOnly && entry.meta?.source !== 'work-item') return `PR ${tracked.id || prLabel} is context-only`;
 
   const queuedBranch = entry.meta.branch || entry.meta.pr?.branch || '';
   const trackedBranch = tracked.branch || '';

package/engine/lifecycle.js

@@ -987,6 +987,258 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
   return added;
 }
 
+// ─── Post-hoc PR enrollment (W-mq5uzmc6001d708f) ─────────────────────────────
+//
+// When a work item has `_pr` set (e.g. via reconcileItemsWithPrs stamping from
+// pr-links, or via an old commit referencing the PR URL) but the `pull_requests`
+// SQL table has no matching row, the dashboard's PRD-progress synthesis falls
+// back to PR_STATUS.ACTIVE forever — the PR rings blue ○ even after it's
+// merged. This happens to PRs that were created AND merged inside one open-PR
+// poller gap (the engine never observed them as `open`, so it never enrolled
+// them).
+//
+// `enrollPrFromCanonicalId` is the write-side fix: given a canonical PR id and
+// the owning project, fetch live state from GitHub (or ADO, best-effort) and
+// insert a `_contextOnly: true` row into the project's `pull-requests.json`.
+// Idempotent — no-op if a record already exists. Always marks the record as
+// context-only so the engine doesn't try to re-dispatch fix/review loops on
+// an already-merged PR (matches the #1772 enrollment-flag semantics).
+
+let _enrollmentGhRunner = null;
+function _setEnrollmentGhRunnerForTest(fn) {
+  _enrollmentGhRunner = (typeof fn === 'function') ? fn : null;
+}
+
+async function _fetchGitHubPrStateForEnrollment(slug, prNumber) {
+  if (_enrollmentGhRunner) {
+    try {
+      return await _enrollmentGhRunner(slug, prNumber);
+    } catch (err) {
+      log('warn', `enrollPrFromCanonicalId: test runner failed for ${slug}#${prNumber}: ${err.message}`);
+      return null;
+    }
+  }
+  let token = null;
+  try {
+    const ghToken = require('./gh-token');
+    if (typeof ghToken.resolveTokenForSlug === 'function') {
+      token = ghToken.resolveTokenForSlug(slug);
+    }
+  } catch { /* gh-token optional in some test contexts */ }
+  const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
+  try {
+    const validatedSlug = shared.validateGhSlug(slug);
+    const args = ['pr', 'view', String(prNumber),
+      '--repo', validatedSlug,
+      '--json', 'state,mergedAt,closedAt,title,headRefName,baseRefName,url,number,isDraft'];
+    const stdout = await shared.shellSafeGh(args, { timeout: 15000, env });
+    if (!stdout || !stdout.trim()) return null;
+    return JSON.parse(stdout);
+  } catch (err) {
+    log('warn', `enrollPrFromCanonicalId: gh pr view ${slug}#${prNumber} failed: ${err.message}`);
+    return null;
+  }
+}
+
+function _liveGitHubStateToPrStatus(liveState) {
+  if (!liveState) return PR_STATUS.ACTIVE;
+  const state = String(liveState.state || '').toUpperCase();
+  if (state === 'MERGED' || liveState.mergedAt) return PR_STATUS.MERGED;
+  if (state === 'CLOSED') return PR_STATUS.ABANDONED;
+  return PR_STATUS.ACTIVE;
+}
+
+function _existingPrRecordForCanonicalId(canonicalPrId) {
+  try {
+    const store = require('./pull-requests-store');
+    if (typeof store.readAllPullRequests !== 'function') return null;
+    const all = store.readAllPullRequests() || [];
+    return all.find(pr => pr && pr.id === canonicalPrId) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enroll a PR (identified by canonical id, e.g. `github:owner/repo#123`) into
+ * the engine's pull-requests tracker if no record exists yet. Used to back-fill
+ * orphan `wi._pr` pointers from the legacy / pre-tracker era so the dashboard
+ * can render the real merged/abandoned status instead of a perpetual blue ○.
+ *
+ * Idempotent: returns `{ enrolled: false, reason: 'already_tracked' }` if a row
+ * already exists. Marks new records with `_contextOnly: true` so the engine
+ * doesn't try to manage them (no re-dispatch of fix/review loops). Live state
+ * is fetched via `gh pr view` for GitHub; ADO enrollment is best-effort with
+ * a conservative ACTIVE default.
+ *
+ * @param {string} canonicalPrId - canonical id like `github:owner/repo#42`
+ * @param {object|null} project - resolved project config; null routes to central
+ * @param {object} [opts]
+ * @param {string} [opts.itemId] - work-item id to link to the enrolled record
+ * @returns {Promise<{enrolled: boolean, status?: string, reason?: string, record?: object}>}
+ */
+async function enrollPrFromCanonicalId(canonicalPrId, project, opts = {}) {
+  if (!canonicalPrId || typeof canonicalPrId !== 'string') {
+    return { enrolled: false, reason: 'no_id' };
+  }
+  // Allow callers to pass a bare display id (e.g. `PR-3082`) plus project; the
+  // upsert helper will re-derive a canonical id from project + display id.
+  let parsed = shared.parseCanonicalPrId(canonicalPrId);
+  let scope;
+  let prNumber;
+  if (parsed) {
+    scope = parsed.scope;
+    prNumber = parsed.prNumber;
+  } else {
+    prNumber = shared.getPrNumber(canonicalPrId);
+    if (prNumber == null) return { enrolled: false, reason: 'unparseable_id' };
+    scope = shared.getProjectPrScope(project);
+    if (!scope) return { enrolled: false, reason: 'no_scope' };
+  }
+  // Normalize canonical id so an inbound `pr-3082` + project resolves to
+  // `github:owner/repo#3082` for the existence check below.
+  const normalizedCanonicalId = `${scope}#${prNumber}`;
+
+  const existing = _existingPrRecordForCanonicalId(normalizedCanonicalId);
+  if (existing) {
+    // Even when already tracked, opportunistically link the work item so
+    // pr-links stays consistent (#779 pattern).
+    if (opts.itemId && Array.isArray(existing.prdItems) && !existing.prdItems.includes(opts.itemId)) {
+      try {
+        const targetPath = project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json');
+        shared.upsertPullRequestRecord(targetPath, {
+          id: normalizedCanonicalId,
+          prNumber,
+          url: existing.url || '',
+          title: existing.title || '',
+          agent: existing.agent || 'engine',
+          status: existing.status || PR_STATUS.ACTIVE,
+        }, { project, itemId: opts.itemId });
+      } catch { /* best-effort link */ }
+    }
+    return { enrolled: false, reason: 'already_tracked', status: existing.status, record: existing };
+  }
+
+  let liveState = null;
+  let url = '';
+  let title = '';
+  let branch = '';
+  let baseBranch = '';
+  let status = PR_STATUS.ACTIVE;
+  let isDraft = false;
+
+  if (scope.startsWith('github:')) {
+    const slug = scope.slice('github:'.length);
+    liveState = await _fetchGitHubPrStateForEnrollment(slug, prNumber);
+    if (liveState) {
+      url = liveState.url || '';
+      title = String(liveState.title || '').slice(0, 200);
+      branch = liveState.headRefName || '';
+      baseBranch = liveState.baseRefName || '';
+      isDraft = !!liveState.isDraft;
+      status = _liveGitHubStateToPrStatus(liveState);
+    }
+    if (!url) {
+      url = `https://github.com/${slug}/pull/${prNumber}`;
+    }
+  } else if (scope.startsWith('ado:')) {
+    // ADO best-effort: fetchAdoPrMetadata returns title/branch but not status.
+    // Record the canonical id so the next ADO poll cycle can refresh status.
+    try {
+      const adoParts = scope.slice('ado:'.length).split('/');
+      if (adoParts.length === 3) {
+        const ado = require('./ado');
+        if (typeof ado.fetchAdoPrMetadata === 'function') {
+          const meta = await ado.fetchAdoPrMetadata(prNumber, adoParts[0], adoParts[1], adoParts[2]);
+          if (meta) {
+            title = String(meta.title || '').slice(0, 200);
+            branch = meta.branch || '';
+          }
+        }
+      }
+    } catch (err) {
+      log('warn', `enrollPrFromCanonicalId: ADO metadata fetch for ${normalizedCanonicalId} failed: ${err.message}`);
+    }
+    if (!url && project && project.prUrlBase) url = String(project.prUrlBase) + prNumber;
+  } else {
+    return { enrolled: false, reason: 'unsupported_scope' };
+  }
+
+  const prPath = project ? shared.projectPrPath(project) : path.join(MINIONS_DIR, 'pull-requests.json');
+  if (!prPath) return { enrolled: false, reason: 'no_pr_path' };
+
+  const entry = {
+    id: normalizedCanonicalId,
+    prNumber,
+    title: title || `PR #${prNumber}`,
+    agent: 'engine',
+    branch,
+    baseBranch,
+    reviewStatus: REVIEW_STATUS.PENDING,
+    status,
+    isDraft,
+    url,
+    prdItems: opts.itemId ? [opts.itemId] : [],
+    _attachedAt: ts(),
+    _contextOnly: true,
+    _enrolledBy: 'enrollPrFromCanonicalId',
+  };
+  if (liveState && liveState.mergedAt) entry.mergedAt = liveState.mergedAt;
+  if (liveState && liveState.closedAt && !liveState.mergedAt) entry.closedAt = liveState.closedAt;
+
+  try {
+    const result = shared.upsertPullRequestRecord(prPath, entry, {
+      project,
+      itemId: opts.itemId || null,
+    });
+    if (result.created) {
+      log('info', `enrollPrFromCanonicalId: enrolled ${normalizedCanonicalId} (status=${status}) into ${project?.name || 'central'}/pull-requests.json`);
+    }
+    return {
+      enrolled: !!(result.created || result.linked),
+      status,
+      reason: result.created ? 'created' : (result.linked ? 'linked' : 'noop'),
+      record: result.record,
+    };
+  } catch (err) {
+    log('warn', `enrollPrFromCanonicalId: upsert failed for ${normalizedCanonicalId}: ${err.message}`);
+    return { enrolled: false, reason: 'upsert_failed', error: err.message };
+  }
+}
+
+// Internal helper: after `syncPrsFromOutput` finishes the regex-evidence pass,
+// some work items still have `meta.item._pr` set without a tracker row (e.g.
+// the agent attached the PR via the structured-completion sidecar before the
+// poller could observe it as `open`, then it merged seconds later). Run a
+// best-effort enrollment so the PRD progress view sees the real status.
+async function _ensurePrEnrollmentForCompletedItem(meta, config) {
+  const itemPr = meta && meta.item && meta.item._pr;
+  if (!itemPr || typeof itemPr !== 'string') return null;
+  let project = null;
+  try {
+    const projectsList = (config && Array.isArray(config.projects)) ? config.projects : shared.getProjects(config);
+    const resolutionSource = meta.project?.name || meta.item?.project || meta.item?._source;
+    if (resolutionSource && Array.isArray(projectsList)) {
+      const resolution = shared.resolveProjectSource(resolutionSource, projectsList, { allowCentral: true });
+      project = resolution?.project || null;
+    }
+  } catch (err) {
+    log('warn', `_ensurePrEnrollmentForCompletedItem: project resolution failed: ${err.message}`);
+  }
+  let canonicalPrId = itemPr;
+  if (!shared.parseCanonicalPrId(itemPr) && project) {
+    canonicalPrId = shared.getCanonicalPrId(project, itemPr) || itemPr;
+  }
+  if (!shared.parseCanonicalPrId(canonicalPrId)) return null;
+  if (_existingPrRecordForCanonicalId(canonicalPrId)) return null;
+  try {
+    return await enrollPrFromCanonicalId(canonicalPrId, project, { itemId: meta.item.id });
+  } catch (err) {
+    log('warn', `_ensurePrEnrollmentForCompletedItem: enrollment failed for ${canonicalPrId}: ${err.message}`);
+    return null;
+  }
+}
+
 function isPrAttachmentRequired(type, item, meta = {}) {
   if (!item?.id || item.skipPr) return false;
   // SETUP (W-mpbi6f2q00104957) is implicitly PR-exempt — the type itself
@@ -4393,6 +4645,17 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     prsCreatedCount = syncPrsFromOutput(stdout, agentId, meta, config, { structuredCompletion }) || 0;
   } catch (err) { log('warn', `PR sync from output: ${err.message}`); }
 
+  // W-mq5uzmc6001d708f — back-fill enrollment for orphan `_pr` pointers.
+  // syncPrsFromOutput only enrolls PRs whose URL appeared in this dispatch's
+  // output. When meta.item._pr was stamped from an earlier dispatch (e.g. via
+  // reconcileItemsWithPrs against pr-links) but the canonical row never made
+  // it into pull-requests.json, the dashboard's PRD-progress synthesis
+  // defaults to ACTIVE forever. This catches those cases at the end of every
+  // post-completion run.
+  try {
+    await _ensurePrEnrollmentForCompletedItem(meta, config);
+  } catch (err) { log('warn', `PR enrollment back-fill: ${err.message}`); }
+
   // Structured completion may report PR even when regex didn't find it
   const scHasPr = structuredCompletion && structuredCompletion.pr && structuredCompletion.pr !== 'N/A';
   if (scHasPr && prsCreatedCount === 0) {
@@ -5311,4 +5574,7 @@ module.exports = {
   // Issue #2969 — exported for direct unit testing of the pause-flip alert
   // path without going through updatePrAfterFix's many guards.
   recordPrNoOpFixAttempt,
+  // W-mq5uzmc6001d708f — post-hoc PR enrollment for orphan `_pr` pointers.
+  enrollPrFromCanonicalId,
+  _setEnrollmentGhRunnerForTest,
 };

package/engine/queries.js

@@ -15,6 +15,63 @@ const { safeRead, safeReadDir, safeJson, safeWrite, getProjects, mutateJsonFileL
   projectWorkItemsPath, projectPrPath, parseSkillFrontmatter, KB_CATEGORIES,
   WI_STATUS, DONE_STATUSES, PRD_ITEM_STATUS, PR_STATUS, ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS } = shared;
 
+// ─── Defensive PR enrichment cache (W-mq5uzmc6001d708f) ──────────────────────
+//
+// buildPrdProgress runs on every /api/status poll. When a work item carries
+// `_pr` but no canonical row exists in pull-requests.json, the synthesis
+// fallback below used to default to PR_STATUS.ACTIVE forever (blue ○). Now
+// we cache the resolved status per canonical id and kick off a best-effort
+// fire-and-forget enrollment so the next poll cycle sees the real status.
+// Lifecycle is lazy-required to avoid the circular dep (lifecycle.js requires
+// queries at top-level).
+
+const PR_ENRICHMENT_TTL_MS = 5 * 60 * 1000;
+const _prEnrichmentCache = new Map(); // canonicalId -> { status, expiresAt }
+const _prEnrichmentInFlight = new Set();
+let _lifecycleModule = null;
+function _lifecycle() {
+  if (!_lifecycleModule) {
+    try { _lifecycleModule = require('./lifecycle'); }
+    catch { _lifecycleModule = null; }
+  }
+  return _lifecycleModule;
+}
+function _getCachedPrEnrichment(id) {
+  if (!id) return null;
+  const cached = _prEnrichmentCache.get(id);
+  if (!cached) return null;
+  if (Date.now() > cached.expiresAt) {
+    _prEnrichmentCache.delete(id);
+    return null;
+  }
+  return cached.status;
+}
+function _setCachedPrEnrichment(id, status) {
+  if (!id || !status) return;
+  _prEnrichmentCache.set(id, { status, expiresAt: Date.now() + PR_ENRICHMENT_TTL_MS });
+}
+function _scheduleAsyncPrEnrollment(canonicalPrId, project, itemId) {
+  if (!canonicalPrId) return;
+  if (_prEnrichmentInFlight.has(canonicalPrId)) return;
+  const lc = _lifecycle();
+  if (!lc || typeof lc.enrollPrFromCanonicalId !== 'function') return;
+  _prEnrichmentInFlight.add(canonicalPrId);
+  setImmediate(() => {
+    Promise.resolve()
+      .then(() => lc.enrollPrFromCanonicalId(canonicalPrId, project, { itemId }))
+      .then((result) => {
+        if (result && result.status) _setCachedPrEnrichment(canonicalPrId, result.status);
+      })
+      .catch(() => { /* best-effort enrollment — caller is the dashboard hot path */ })
+      .then(() => { _prEnrichmentInFlight.delete(canonicalPrId); });
+  });
+}
+// Exposed for tests so suites that toggle PR-enrollment state can reset.
+function _resetPrEnrichmentCacheForTest() {
+  _prEnrichmentCache.clear();
+  _prEnrichmentInFlight.clear();
+}
+
 /**
  * Read the first `bytes` and last `bytes` of a file efficiently using byte offsets.
  * For files <= 2*bytes, reads the whole file. Returns { head, tail } strings.
@@ -1625,7 +1682,21 @@ function getPrdInfo(config) {
     const displayMatches = exactPr ? [] : Object.values(prById).filter(candidate => shared.getPrDisplayId(candidate) === shared.getPrDisplayId(wi._pr));
     const pr = exactPr || (displayMatches.length === 1 ? displayMatches[0] : null);
     const url = buildPrUrlFromId(canonicalPrId || wi._pr, pr, projects);
-    prdToPr[wi.id] = [{ id: pr?.id || canonicalPrId || wi._pr, url, title: pr?.title || '', status: pr?.status || PR_STATUS.ACTIVE, _project: project?.name || '' }];
+    // W-mq5uzmc6001d708f — read-side defensive enrichment. When no record
+    // exists (orphan _pr pointer), use a cached status from a prior async
+    // enrollment if available, else synthesize ACTIVE and schedule a
+    // fire-and-forget enrollment so the next status poll renders correctly.
+    let synthesizedStatus = pr?.status;
+    if (!pr && canonicalPrId) {
+      const cachedStatus = _getCachedPrEnrichment(canonicalPrId);
+      if (cachedStatus) {
+        synthesizedStatus = cachedStatus;
+      } else {
+        synthesizedStatus = PR_STATUS.ACTIVE;
+        _scheduleAsyncPrEnrollment(canonicalPrId, project, wi.id);
+      }
+    }
+    prdToPr[wi.id] = [{ id: pr?.id || canonicalPrId || wi._pr, url, title: pr?.title || '', status: synthesizedStatus || PR_STATUS.ACTIVE, _project: project?.name || '' }];
   }
   // Aggregate sub-task PRs to decomposed parent (sub-tasks aren't PRD items but their PRs should show)
   for (const pr of allPrs) {
@@ -2501,4 +2572,7 @@ module.exports = {
 
   // Work items & PRD
   getWorkItems, invalidateWorkItemsCache, getPrdInfo,
+
+  // W-mq5uzmc6001d708f — test hooks for the defensive PR enrichment cache.
+  _resetPrEnrichmentCacheForTest,
 };