@yemi33/minions 0.1.2292 → 0.1.2294

package/engine/prd-store.js

@@ -74,7 +74,10 @@ function _upsertPrd(db, filename, archived, prd, now) {
       sourcePlan, prd.sourcePlanModifiedAt || prd.source_plan_modified_at || null,
       JSON.stringify(prd), now, prdId,
     );
-    db.prepare('DELETE FROM prd_items WHERE prd_id=?').run(prdId);
+    // NOTE: prd_items are NOT bulk-deleted here — they are upserted by their
+    // stable (prd_id, feature_id) key below so prd_items.id survives a re-mirror
+    // (work_items.prd_item_id is an FK to it). prd_verify_prs carries no FK, so
+    // a cheap delete+reinsert is fine.
     db.prepare('DELETE FROM prd_verify_prs WHERE prd_id=?').run(prdId);
   } else {
     const info = db.prepare(`
@@ -91,18 +94,73 @@ function _upsertPrd(db, filename, archived, prd, now) {
     prdId = Number(info.lastInsertRowid);
   }
 
-  const insItem = db.prepare(`
+  // Upsert prd_items by their STABLE natural key (prd_id, feature_id) instead of
+  // delete-all-then-reinsert, so the surrogate prd_items.id is durable across
+  // re-mirrors. work_items.prd_item_id is an FK to this id; churning it (via
+  // AUTOINCREMENT on every mirror) dangled every stamped row — the Phase-10
+  // step-4 join-flip blocker. feature_id-less legacy items can't be keyed (NULL
+  // != NULL under UNIQUE), so they are swept + reinserted each time; they are
+  // never FK targets, so their churn is harmless.
+  const features = Array.isArray(prd.missing_features) ? prd.missing_features : [];
+  const keepIds = [];
+  for (const ft of features) { if (ft && typeof ft === 'object' && ft.id) keepIds.push(String(ft.id)); }
+  // Drop id-bearing items no longer on the PRD, plus all NULL-feature_id rows.
+  if (keepIds.length) {
+    db.prepare(
+      `DELETE FROM prd_items WHERE prd_id=? AND feature_id IS NOT NULL AND feature_id NOT IN (${keepIds.map(() => '?').join(',')})`
+    ).run(prdId, ...keepIds);
+  } else {
+    db.prepare('DELETE FROM prd_items WHERE prd_id=? AND feature_id IS NOT NULL').run(prdId);
+  }
+  db.prepare('DELETE FROM prd_items WHERE prd_id=? AND feature_id IS NULL').run(prdId);
+
+  const upsertItem = db.prepare(`
     INSERT INTO prd_items (prd_id, feature_id, name, project, status, type, work_item_id, data, updated_at)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(prd_id, feature_id) DO UPDATE SET
+      name=excluded.name, project=excluded.project, status=excluded.status,
+      type=excluded.type, work_item_id=excluded.work_item_id,
+      data=excluded.data, updated_at=excluded.updated_at
   `);
-  const features = Array.isArray(prd.missing_features) ? prd.missing_features : [];
+  const insItemNoId = db.prepare(`
+    INSERT INTO prd_items (prd_id, feature_id, name, project, status, type, work_item_id, data, updated_at)
+    VALUES (?, NULL, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const selItemId = db.prepare('SELECT id FROM prd_items WHERE prd_id=? AND feature_id=?');
+  // Stamp the materialized work item(s) → prd_items.id. The two backref paths
+  // mirror the migration-015 backfill: an explicit feature.workItemId (set by
+  // lifecycle.stampPrdItemWorkItemId), and the sourcePlan(=PRD filename) +
+  // feature-id equality the legacy JSON model joined on. Self-heals on every
+  // mirror, so a WI materialized after this PRD was first seen still gets its FK.
+  const stampWiById = db.prepare(
+    'UPDATE work_items SET prd_item_id=? WHERE id=? AND (prd_item_id IS NULL OR prd_item_id<>?)'
+  );
+  const stampWiBySourcePlan = db.prepare(
+    `UPDATE work_items SET prd_item_id=? WHERE json_extract(data,'$.sourcePlan')=? AND json_extract(data,'$.id')=? AND (prd_item_id IS NULL OR prd_item_id<>?)`
+  );
   for (const ft of features) {
     if (!ft || typeof ft !== 'object') continue;
+    const proj = ft.project || prd.project || null;
+    const explicitWi = ft.workItemId || ft.work_item_id || null;
+    if (!ft.id) {
+      try {
+        insItemNoId.run(prdId, ft.name || null, proj, ft.status || null, ft.type || null,
+          explicitWi, JSON.stringify(ft), now);
+      } catch { /* best-effort */ }
+      continue;
+    }
+    const featureId = String(ft.id);
     try {
-      insItem.run(prdId, ft.id || null, ft.name || null, ft.project || prd.project || null,
-        ft.status || null, ft.type || null, ft.workItemId || ft.work_item_id || null,
-        JSON.stringify(ft), now);
-    } catch { /* dup (prd_id, feature_id) → skip */ }
+      upsertItem.run(prdId, featureId, ft.name || null, proj, ft.status || null, ft.type || null,
+        explicitWi, JSON.stringify(ft), now);
+    } catch { continue; }
+    let prdItemId;
+    try { prdItemId = selItemId.get(prdId, featureId)?.id; } catch { /* ignore */ }
+    if (!prdItemId) continue;
+    if (explicitWi) {
+      try { stampWiById.run(prdItemId, String(explicitWi), prdItemId); } catch { /* best-effort */ }
+    }
+    try { stampWiBySourcePlan.run(prdItemId, filename, featureId, prdItemId); } catch { /* best-effort */ }
   }
 
   const insVp = db.prepare(`
@@ -235,6 +293,53 @@ function reconcilePrdsFromDisk() {
   return { ok: true, mirrored, removed };
 }
 
+// Idempotent boot sweep: populate work_items.prd_item_id for rows that predate
+// the dual-write stamp (everything materialized before #546), or that a JSON
+// re-hydrate transiently zeroed. The per-mirror stamp in _upsertPrd only fires
+// for PRDs that are re-mirrored, and reconcile is mtime-gated — so a PRD that
+// never changes again never re-stamps its historical WIs. This catch-up is
+// set-based (two SQL UPDATEs, no per-row loop), only touches NULL FKs, and
+// prefers the live (archived=0) prd_item when a basename exists in both buckets.
+// Safe to run on every boot — a no-op once every matchable WI is linked.
+// Returns { ok, byWorkItemId, bySourcePlan } counts.
+function backfillWorkItemPrdItemIds() {
+  let db;
+  try { db = require('./db').getDb(); } catch { return { ok: false }; }
+  try {
+    return require('./db').withTransaction(db, () => {
+      // Path 1 — explicit prd_items.work_item_id backref (most precise).
+      const r1 = db.prepare(`
+        UPDATE work_items SET prd_item_id = (
+          SELECT pi.id FROM prd_items pi JOIN prds p ON p.id = pi.prd_id
+          WHERE pi.work_item_id = work_items.id
+          ORDER BY p.archived ASC, pi.id ASC LIMIT 1
+        )
+        WHERE prd_item_id IS NULL
+          AND EXISTS (SELECT 1 FROM prd_items pi WHERE pi.work_item_id = work_items.id)
+      `).run();
+      // Path 2 — sourcePlan(=PRD filename) + feature-id equality on the WI blob,
+      // for WIs the PRD side never stamped with an explicit workItemId.
+      const r2 = db.prepare(`
+        UPDATE work_items SET prd_item_id = (
+          SELECT pi.id FROM prd_items pi JOIN prds p ON p.id = pi.prd_id
+          WHERE p.filename = json_extract(work_items.data, '$.sourcePlan')
+            AND pi.feature_id = json_extract(work_items.data, '$.id')
+          ORDER BY p.archived ASC, pi.id ASC LIMIT 1
+        )
+        WHERE prd_item_id IS NULL
+          AND EXISTS (
+            SELECT 1 FROM prd_items pi JOIN prds p ON p.id = pi.prd_id
+            WHERE p.filename = json_extract(work_items.data, '$.sourcePlan')
+              AND pi.feature_id = json_extract(work_items.data, '$.id')
+          )
+      `).run();
+      return { ok: true, byWorkItemId: Number(r1.changes) || 0, bySourcePlan: Number(r2.changes) || 0 };
+    });
+  } catch (e) {
+    return { ok: false, reason: e && e.message };
+  }
+}
+
 // List every PRD row as { filename, archived, plan } where plan is the parsed
 // data blob. Sorted by (archived, filename) for deterministic consumer order
 // (matches the disk-scan order once the caller also sorts). Read-flip source.
@@ -258,6 +363,7 @@ module.exports = {
   removePrdFromSql,
   readPrdFromSql,
   reconcilePrdsFromDisk,
+  backfillWorkItemPrdItemIds,
   listPrdRows,
   _reconcileMtimes, // exported for tests (reset between cases)
   _upsertPrd, // exported for tests

package/engine/queries.js

@@ -2077,8 +2077,7 @@ function getWorkItems(config, opts) {
 
 // ── PRD Progress ────────────────────────────────────────────────────────────
 
-// Module-level caches for getPrdInfo() — avoids re-reading unchanged PRD files
-const _prdFileCache = new Map();       // filePath → { mtimeMs, plan }
+// Module-level caches for getPrdInfo() — avoids re-reading unchanged PRD data
 let _prdDirMtimes = { prd: 0, archive: 0 }; // directory mtimes to detect new/deleted files
 let _prdResultCache = null;            // cached final result
 let _prdResultInputHash = '';          // hash of all input mtimes to detect any change
@@ -2141,21 +2140,22 @@ function getPrdInfo(config) {
   const verifyPrsByPlan = {};
   let latestStat = null;
 
-  // Check if directory listings need refresh
-  const dirsChanged = prdDirMtime !== _prdDirMtimes.prd || archiveDirMtime !== _prdDirMtimes.archive;
+  // Check if directory listings need refresh (used by mtime hash)
   _prdDirMtimes = { prd: prdDirMtime, archive: archiveDirMtime };
 
-  // Scan active PRDs and archived PRDs (completed PRDs still need to show progress)
-  const planDirs = [
-    { dir: PRD_DIR, archived: false },
-    { dir: path.join(PRD_DIR, 'archive'), archived: true },
-  ];
-
-  // Phase 10 step 3 (read-flip) — both the disk scan and the SQL-mirror source
-  // funnel each PRD through this one processor, so the consumed shape
+  // Phase 10 step 4.3 — FK-based WI↔PRD-item join scaffolding. `prdItemIdByKey`
+  // maps `${physicalArchived} ${filename} ${feature_id}` → prd_items.id so each
+  // PRD item carries its stable surrogate id. Declared here so processPrd's
+  // closure can stamp `_prdItemId` at push time. Null when the FK join is off /
+  // SQL unavailable → the per-item join falls back to the legacy feature-id
+  // string match.
+  let useFkJoin = false;
+  try { useFkJoin = require('./features').isFeatureOn('prdJoinFromFk', config); } catch { /* fall back to string join */ }
+  let prdItemIdByKey = null;
+
+  // Phase 10 step 3 (read-flip complete) — both disk-write and SQL-mirror sources
+  // funnel each PRD through this one processor so the consumed shape
   // (existingPrds / verifyPrsByPlan / allPrdItems) is identical by construction.
-  // The only difference is where `plan` + `mtimeMs` come from. Equivalence of the
-  // two paths is proven by test/unit/db-phase10-read-flip.test.js.
   const processPrd = (pf, archived, plan, mtimeMs) => {
     if (!plan || !plan.missing_features) return;
     // Phase 10 step 4.2: archived-ness is the FLAG, not the directory. `archived`
@@ -2187,6 +2187,11 @@ function getPrdInfo(config) {
       }));
     }
     for (const f of plan.missing_features) {
+      // Stamp the stable surrogate prd_items.id, keyed on the PHYSICAL archived
+      // bit (the `archived` param == SQL location), not the logical `isArch`.
+      const prdItemId = (prdItemIdByKey && f && f.id != null)
+        ? (prdItemIdByKey.get(`${archived ? 1 : 0} ${pf} ${f.id}`) ?? null)
+        : null;
       allPrdItems.push({
         ...f, _source: pf, _planStatus: plan.status || 'active',
         _planSummary: plan.plan_summary || pf, _planProject: plan.project || '',
@@ -2195,72 +2200,45 @@ function getPrdInfo(config) {
         _planStale: planStale || plan.planStale || false, _lastSyncedFromPlan: plan.lastSyncedFromPlan || null,
         _prdUpdatedAt: new Date(mtimeMs).toISOString(),
         _prdCompletedAt: plan.completedAt || '',
+        _prdItemId: prdItemId,
       });
     }
   };
 
-  let useSqlReads = false;
-  try { useSqlReads = require('./features').isFeatureOn('prdReadsFromSql', config); } catch { /* fall back to disk */ }
-
-  if (useSqlReads) {
-    // SQL source: reconcile the mirror from disk (catches PRDs written outside
-    // the dual-write chokepoint — plan-to-prd agent direct writes, archive
-    // moves, deletes), then read each PRD's content from SQL. Files still live on
-    // disk in this phase, so stat them for the mtime fields + `age`.
+  // Build the feature → prd_items.id map before the read loop so processPrd can
+  // stamp _prdItemId. SQL is the unconditional source (Phase 10 step 3 complete),
+  // so the FK join just needs useFkJoin. Best-effort: any failure leaves
+  // prdItemIdByKey null and the join silently falls back to the legacy
+  // feature-id string match.
+  if (useFkJoin) {
     try {
-      const prdStore = require('./prd-store');
-      prdStore.reconcilePrdsFromDisk();
-      for (const { filename, archived, plan } of prdStore.listPrdRows()) {
-        try {
-          const dir = archived ? path.join(PRD_DIR, 'archive') : PRD_DIR;
-          let mtimeMs = 0;
-          try {
-            const stat = fs.statSync(path.join(dir, filename));
-            mtimeMs = stat.mtimeMs;
-            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
-          } catch { /* file may have just moved/deleted between reconcile and read */ }
-          processPrd(filename, archived, plan, mtimeMs);
-        } catch { /* optional */ }
+      const db = require('./db').getDb();
+      const map = new Map();
+      for (const r of db.prepare('SELECT p.filename AS filename, p.archived AS archived, pi.feature_id AS feature_id, pi.id AS id FROM prd_items pi JOIN prds p ON p.id = pi.prd_id WHERE pi.feature_id IS NOT NULL').all()) {
+        map.set(`${r.archived ? 1 : 0} ${r.filename} ${r.feature_id}`, r.id);
       }
-    } catch {
-      // Hard SQL failure → fall back to the disk scan so the dashboard never
-      // goes blank on a transient DB problem.
-      useSqlReads = false;
-    }
+      prdItemIdByKey = map;
+    } catch { prdItemIdByKey = null; }
   }
 
-  if (!useSqlReads) {
-    for (const { dir, archived } of planDirs) {
+  // Phase 10 step 3 (read-flip complete) — SQL mirror is the unconditional
+  // source. reconcilePrdsFromDisk() catches PRDs written outside the dual-write
+  // chokepoint (plan-to-prd agent direct writes, archive moves, deletes). Files
+  // still live on disk in this phase, so stat them for mtime fields + `age`.
+  const prdStore = require('./prd-store');
+  prdStore.reconcilePrdsFromDisk();
+  for (const { filename, archived, plan } of prdStore.listPrdRows()) {
+    try {
+      const dir = archived ? path.join(PRD_DIR, 'archive') : PRD_DIR;
+      let mtimeMs = 0;
       try {
-        const planFiles = fs.readdirSync(dir).filter(f => f.endsWith('.json')).sort();
-        for (const pf of planFiles) {
-          try {
-            const filePath = path.join(dir, pf);
-            const stat = fs.statSync(filePath);
-            if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
-
-            // Per-file mtime cache: only re-read files that changed
-            const cached = _prdFileCache.get(filePath);
-            let plan;
-            if (cached && cached.mtimeMs === stat.mtimeMs) {
-              plan = cached.plan;
-            } else {
-              plan = readJsonNoRestore(filePath);
-              _prdFileCache.set(filePath, { mtimeMs: stat.mtimeMs, plan });
-            }
-            processPrd(pf, archived, plan, stat.mtimeMs);
-          } catch { /* optional */ }
-        }
-        // Clean stale entries from file cache when dirs changed
-        if (dirsChanged) {
-          for (const cachedPath of _prdFileCache.keys()) {
-            if (cachedPath.startsWith(dir) && !fs.existsSync(cachedPath)) _prdFileCache.delete(cachedPath);
-          }
-        }
-      } catch { /* optional */ }
-    }
+        const stat = fs.statSync(path.join(dir, filename));
+        mtimeMs = stat.mtimeMs;
+        if (!latestStat || stat.mtimeMs > latestStat.mtimeMs) latestStat = stat;
+      } catch { /* file may have just moved/deleted between reconcile and read */ }
+      processPrd(filename, archived, plan, mtimeMs);
+    } catch { /* optional */ }
   }
-
   if (allPrdItems.length === 0) return { progress: null, status: null };
 
   const items = allPrdItems;
@@ -2293,6 +2271,29 @@ function getPrdInfo(config) {
     }
   } catch { /* optional */ }
 
+  // Phase 10 step 4.3 — index the (JSON-sourced) work items by their stable SQL
+  // FK so the per-item join can resolve PRD item → WI by prd_items.id rather
+  // than the feature-id string. The FK itself lives only in SQL (it's not in the
+  // JSON mirror), so read work_items.prd_item_id once and join it to the WI
+  // objects we already loaded, keyed by wi.id (first-wins, matching allWiById).
+  // Best-effort: null map → the join falls back to the legacy string match.
+  let wiByPrdItemId = null;
+  if (useFkJoin && prdItemIdByKey) {
+    try {
+      const db = require('./db').getDb();
+      const fkByWiId = new Map();
+      for (const r of db.prepare('SELECT id, prd_item_id FROM work_items WHERE prd_item_id IS NOT NULL').all()) {
+        if (!fkByWiId.has(r.id)) fkByWiId.set(r.id, r.prd_item_id);
+      }
+      const map = {};
+      for (const wi of Object.values(allWiById)) {
+        const fk = fkByWiId.get(wi.id);
+        if (fk != null && map[fk] === undefined) map[fk] = wi;
+      }
+      wiByPrdItemId = map;
+    } catch { wiByPrdItemId = null; }
+  }
+
   // PR-to-PRD linking — derived from PR.prdItems (single source of truth).
   // getPullRequests includes records from unconfigured project subdirs so PRD
   // links can resolve to last-known status even after a project is removed.
@@ -2383,12 +2384,33 @@ function getPrdInfo(config) {
     }
   }
 
+  // Fallback (P-b6c8d0e2): PR records stamped with prdItemId/sourcePlan at sync
+  // time. When the standard prLinks chain doesn't cover a PRD item (e.g. the WI
+  // id differs from the PRD feature id, or prLinks is stale), use the PR record's
+  // own prdItemId field to ensure the PRD view shows the PR.
+  for (const pr of allPrs) {
+    const prdItemIdFromPr = typeof pr.prdItemId === 'string' ? pr.prdItemId : '';
+    if (!prdItemIdFromPr || !prdItemIdSet.has(prdItemIdFromPr)) continue;
+    if (prdToPr[prdItemIdFromPr] && prdToPr[prdItemIdFromPr].length > 0) continue; // already covered
+    if (!prdToPr[prdItemIdFromPr]) prdToPr[prdItemIdFromPr] = [];
+    const url = buildPrUrlFromId(pr.id, pr, projects);
+    prdToPr[prdItemIdFromPr].push({ id: pr.id, url, title: pr.title || '', status: pr.status || PR_STATUS.ACTIVE, _project: pr._project || '' });
+  }
+
+
   // PRD JSON status is the source of truth — kept in sync with work item by syncPrdItemStatus.
   // Map from PRD JSON values to display values (pending → missing for undispatched items)
   // Augment each item with execution metadata from the work item.
   const statusDisplay = { pending: 'missing', dispatched: 'in-progress' };
   for (const item of items) {
-    const wi = wiById[item.id];
+    // Phase 10 step 4.3 — resolve the work item via the stable SQL FK
+    // (item._prdItemId → prd_items.id → work_items.prd_item_id) first; fall back
+    // to the legacy feature-id string match (wiById[item.id]) for unstamped rows,
+    // a NULL FK, the flag OFF, or SQL unavailable. The fallback reproduces the
+    // pre-flip behavior exactly, so a live+archived feature-id collision (footgun
+    // #7) is corrected when the FK is present and degrades to legacy otherwise.
+    const wi = (wiByPrdItemId && item._prdItemId != null && wiByPrdItemId[item._prdItemId])
+      || wiById[item.id];
     // PRD 'updated'/'missing' = intentional rework signal — takes priority over a done work item (#930).
     // Otherwise work item status is source of truth when available (PRD JSON may lag behind).
     // If PRD says dispatched/failed but no work item exists, treat as pending (orphaned — #779)
@@ -2462,7 +2484,6 @@ function getPrdInfo(config) {
 
 /** Reset PRD info cache — exported for testing */
 function resetPrdInfoCache() {
-  _prdFileCache.clear();
   _prdDirMtimes = { prd: 0, archive: 0 };
   _prdResultCache = null;
   _prdResultInputHash = '';

package/engine/shared.js

@@ -1005,14 +1005,18 @@ function _routeJsonReadToSql(p) {
  * stale `.backup` is actively harmful. See its JSDoc for selection guidance.
  */
 
-// PL-prd-no-backup (W-mqub65ez0004b3bd) — archived PRDs under prd/archive/ are
-// permanently removed terminal artifacts. They must NOT auto-restore from a
-// stale `.backup` sidecar (W-mouptdh1000h9f39: archived PRD came back and
-// re-dispatched work). Intentionally NARROW to prd/archive/ only:
-//   - prd/archive/*.json → no backup write + no safeJson restore
-//   - prd/*.json (root-level canonical)  → normal backup/restore lifecycle
-//     preserved so concurrent-sweep loss is recoverable (prd-rename-race.test.js).
-const _NO_BACKUP_JSON_RE = /(?:^|[\\/])prd[\\/]archive[\\/][^\\/]+\.json$/i;
+// PL-prd-no-backup (W-mqub65ez0004b3bd) — PRD `.json` files must NOT auto-restore
+// from a stale `.backup` sidecar: a removed/archived PRD coming back and
+// re-dispatching work is the original resurrection footgun (W-mouptdh1000h9f39).
+// Phase 10 step 4.3 — BROADENED from prd/archive/ to ALL prd/*.json (root +
+// archive). The root-level backup lifecycle previously survived ONLY to recover
+// the enforceDeclaredPlanProject rename-race (a concurrent sweep deleting a
+// just-renamed PRD); that rename is now retired and SQL is the canonical store,
+// so the sidecar is pure resurrection fuel with no remaining benefit:
+//   - prd/*.json AND prd/archive/*.json → no backup write + no safeJson restore.
+// Matches a single filename segment under prd/ (optionally one archive/ level),
+// so nested non-PRD paths and plans/ (which are .md) are unaffected.
+const _NO_BACKUP_JSON_RE = /(?:^|[\\/])prd[\\/](?:archive[\\/])?[^\\/]+\.json$/i;
 function _isNoBackupJsonPath(p) {
   return typeof p === 'string' && _NO_BACKUP_JSON_RE.test(p);
 }
@@ -1778,6 +1782,23 @@ function _tryRouteMutateToSql(filePath, mutateFn, onWrote) {
   if (smallRoute) {
     if (!fpNorm.endsWith('/engine/' + baseName)) return null;
     const store = require('./small-state-store');
+    // Pre-warm the SQLite DB BEFORE acquiring the file lock. On the very first
+    // call from a process (or after a test-isolation MINIONS_TEST_DIR swap),
+    // getDb() opens the DB file and runs migrations — which can take tens of
+    // milliseconds on a loaded box. When 5+ concurrent processes all hit this
+    // path simultaneously, whichever one wins the file lock holds it for the
+    // entire DB-init duration. The other 4 processes each have only a 5-second
+    // timeout window to acquire the lock; if DB init exceeds that, they throw
+    // "Lock timeout" and exit 1 (observed in CI after opg#552 backport which
+    // added a new test that increases system load during parallel runs).
+    // Pre-warming here means getDb() returns the cached _db instantly when
+    // called again inside the lock, so the lock is held only for the fast
+    // SQL transaction + mirror write — not for DB initialization.
+    try {
+      require('./db').getDb();
+    } catch (e) {
+      throw new Error(`small-state-store: SQLite unavailable — ${e.message}`);
+    }
     // Hold the JSON file lock across the SQL transaction AND the mirror
     // write. The SQL transaction itself is cross-process serialized via
     // BEGIN IMMEDIATE inside the SQL store, but the JSON mirror is a
@@ -2675,21 +2696,12 @@ const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
 function resolveCheckoutMode(project, workItemType) {
   if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
   const canonical = project.checkoutMode;
-  // Resolve the effective mode: canonical field first, then legacy worktreeMode fallback.
-  let effectiveMode;
-  if (canonical === CHECKOUT_MODES.LIVE || canonical === CHECKOUT_MODES.WORKTREE) {
-    effectiveMode = canonical;
-  } else if (project.worktreeMode === 'live') {
-    effectiveMode = CHECKOUT_MODES.LIVE;
-  } else {
-    effectiveMode = CHECKOUT_MODES.WORKTREE;
-  }
-  // liveValidation without an effective live mode is a misconfiguration — warn and ignore.
-  if (project.liveValidation && effectiveMode !== CHECKOUT_MODES.LIVE) {
+  // liveValidation without checkoutMode: 'live' is a misconfiguration — warn and ignore.
+  if (project.liveValidation && canonical !== CHECKOUT_MODES.LIVE) {
     log('warn', 'resolveCheckoutMode: liveValidation is set but checkoutMode is not "live" — liveValidation ignored',
       { projectName: project.name });
   }
-  if (effectiveMode === CHECKOUT_MODES.LIVE) {
+  if (canonical === CHECKOUT_MODES.LIVE) {
     // Apply liveValidation routing when the block is present and workItemType is provided.
     if (project.liveValidation && workItemType !== undefined) {
       return workItemType === project.liveValidation.type
@@ -2698,6 +2710,11 @@ function resolveCheckoutMode(project, workItemType) {
     }
     return CHECKOUT_MODES.LIVE;
   }
+  if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
+  // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
+  const legacy = project.worktreeMode;
+  if (legacy === 'live') return CHECKOUT_MODES.LIVE;
+  // legacy 'isolated' (and anything else) → the default worktree behavior.
   return CHECKOUT_MODES.WORKTREE;
 }
 
@@ -3639,8 +3656,14 @@ let _legacyCcModelMigrationLogged = false;
 function applyLegacyCcModelMigration(config, { logger = log } = {}) {
   if (!config || !config.engine || typeof config.engine !== 'object') return false;
   const e = config.engine;
-  if (e.defaultModel !== undefined && e.defaultModel !== null && e.defaultModel !== '') return false;
-  if (!(e.ccModel !== undefined && e.ccModel !== null && e.ccModel !== '')) return false;
+  if (e.defaultModel !== undefined && e.defaultModel !== null && e.defaultModel !== '') {
+    logger('info', 'legacy-cc-model-migration: no-op (0 records migrated), safe to schedule removal.');
+    return false;
+  }
+  if (!(e.ccModel !== undefined && e.ccModel !== null && e.ccModel !== '')) {
+    logger('info', 'legacy-cc-model-migration: no-op (0 records migrated), safe to schedule removal.');
+    return false;
+  }
   e.defaultModel = e.ccModel;
   if (!_legacyCcModelMigrationLogged) {
     _legacyCcModelMigrationLogged = true;
@@ -4856,12 +4879,6 @@ function agentCanUseRepo(agent, repoTarget) {
   return false;
 }
 
-/** Return the agent's effective memory scope. Unknown values fall back to 'shared'. */
-function agentMemoryScope(agent) {
-  const manifest = resolveAgentManifest(agent);
-  return MEMORY_SCOPES.includes(manifest.memory_scope) ? manifest.memory_scope : 'shared';
-}
-
 /**
  * Merge a manifest's `allowed_tools` list into the runtime adapter's existing
  * `allowedTools` CSV baseline. Returns the merged CSV string the runtime
@@ -7064,6 +7081,91 @@ function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } =
   });
 }
 
+// Fields copied from "loser" duplicates into the winner when collapsing.
+// Additive (array-merge) fields are listed separately.
+const _DEDUP_MERGE_SCALAR_KEYS = [
+  'url', 'title', 'agent', 'branch', 'description', 'sourcePlan', 'itemType',
+  'mergedAt', 'closedAt', 'created', 'reviewStatus',
+  'minionsReview', '_automationFixCauses',
+];
+
+// Pick the "most complete" record from a list of duplicates.
+// Preference order:
+//   1. merged status (most terminal / most informative)
+//   2. record with a URL (enables live polling)
+//   3. record with more own keys (richer data)
+function _pickBestPrRecord(candidates) {
+  if (candidates.length === 1) return candidates[0];
+  const merged = candidates.filter(c => c && c.status === PR_STATUS.MERGED);
+  const pool = merged.length > 0 ? merged : candidates.filter(Boolean);
+  const withUrl = pool.filter(c => c.url);
+  const final = withUrl.length > 0 ? withUrl : pool;
+  return final.reduce((a, b) => Object.keys(b || {}).length > Object.keys(a || {}).length ? b : a);
+}
+
+// Merge non-conflicting fields from a loser duplicate into the winner.
+// Scalar fields are filled when winner is empty; prdItems are union-merged.
+function _mergeDuplicatePrInto(winner, loser) {
+  if (!winner || !loser) return;
+  for (const key of _DEDUP_MERGE_SCALAR_KEYS) {
+    if ((winner[key] == null || winner[key] === '') && loser[key] != null && loser[key] !== '') {
+      winner[key] = loser[key];
+    }
+  }
+  winner.prdItems = normalizePrLinkItems([...(winner.prdItems || []), ...(loser.prdItems || [])]);
+}
+
+/**
+ * P-e9f0a2b4 — One-time repair helper: collapse duplicate PR records that share
+ * the same `prNumber` within a single `pull-requests.json` file.
+ *
+ * Call this at engine start for every project's PR file (and the central file).
+ * Idempotent — no-op when no duplicates exist.
+ *
+ * Selection rule (matching the task spec):
+ *   1. Prefer `merged` status over any other status.
+ *   2. Among tied: prefer the record with a URL.
+ *   3. Among tied: prefer the record with more fields (richer data).
+ *   Fields unique to the losers are merged into the winner:
+ *     • scalar fields: filled only when the winner's field is empty
+ *     • prdItems: union-merged
+ *
+ * @param {string} prPath  Path to the pull-requests.json file.
+ * @param {{ project?: object|null }} opts  Optional project config for normalization.
+ * @returns {{ collapsed: number }}  Number of duplicate records removed.
+ */
+function collapseDuplicatePrRecords(prPath, { project = null } = {}) {
+  let collapsed = 0;
+  mutatePullRequests(prPath, (prs) => {
+    normalizePrRecords(prs, project);
+    // Group by prNumber.
+    const byNumber = new Map();
+    for (const pr of prs) {
+      if (!pr) continue;
+      const num = getPrNumber(pr);
+      if (num == null) continue;
+      if (!byNumber.has(num)) byNumber.set(num, []);
+      byNumber.get(num).push(pr);
+    }
+    // Identify loser records to remove (by object reference, not id, because
+    // normalization may have changed multiple records to the same canonical id).
+    const toRemove = new Set();
+    for (const [, group] of byNumber) {
+      if (group.length <= 1) continue;
+      const best = _pickBestPrRecord(group);
+      for (const dup of group) {
+        if (!dup || dup === best) continue;
+        _mergeDuplicatePrInto(best, dup);
+        toRemove.add(dup);
+        collapsed++;
+      }
+    }
+    if (toRemove.size === 0) return prs;
+    return prs.filter(pr => !toRemove.has(pr));
+  });
+  return { collapsed };
+}
+
 /**
  * Canonical PR-producing work contract helper.
  *
@@ -7117,6 +7219,26 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
       skipped = true;
       return prs;
     }
+    // P-e9f0a2b4 — When findPrRecord returns null but multiple records share the
+    // same prNumber (e.g. cross-scope contamination or a project-config change
+    // that shifted canonical IDs), collapse the duplicates before inserting.
+    // Without this check, every subsequent upsert would append yet another record
+    // because numberMatches.length > 1 forces findPrRecord to return null.
+    if (!target && prNumber != null) {
+      const numberMatches = prs.filter(pr => pr && !pr.userDeleted && getPrNumber(pr) === prNumber);
+      if (numberMatches.length > 1) {
+        const best = _pickBestPrRecord(numberMatches);
+        const toRemoveIds = new Set(numberMatches.filter(p => p !== best).map(p => p.id));
+        for (const dup of numberMatches) {
+          if (dup === best) continue;
+          _mergeDuplicatePrInto(best, dup);
+        }
+        for (let i = prs.length - 1; i >= 0; i--) {
+          if (prs[i] && toRemoveIds.has(prs[i].id)) prs.splice(i, 1);
+        }
+        target = best; // update the surviving record instead of inserting new
+      }
+    }
     if (!target && typeof beforeInsert === 'function' && beforeInsert(prs, normalizedEntry) === false) {
       skipped = true;
       return prs;
@@ -7129,7 +7251,7 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
       target.id = canonicalId;
       if (prNumber != null) target.prNumber = prNumber;
       const targetWasAutoManaged = isAutoManagedPrRecord(target);
-      for (const key of ['url', 'title', 'description', 'agent', 'branch', 'reviewStatus', 'status', 'created', 'sourcePlan', 'itemType']) {
+      for (const key of ['url', 'title', 'description', 'agent', 'branch', 'reviewStatus', 'status', 'created', 'sourcePlan', 'itemType', 'prdItemId']) {
         if (normalizedEntry[key] != null && normalizedEntry[key] !== '' && (target[key] == null || target[key] === '')) {
           target[key] = normalizedEntry[key];
         }
@@ -8965,7 +9087,6 @@ module.exports = {
   validateWorkspaceManifest,
   resolveAgentManifest,
   agentCanUseRepo,
-  agentMemoryScope,
   mergeManifestAllowedTools,
   formatManifestRejection,
   getProjects,
@@ -9017,6 +9138,7 @@ module.exports = {
   mergePrLinkItems, // exported for testing
   isContextOnlyPrRecord,
   upsertPullRequestRecord,
+  collapseDuplicatePrRecords, // P-e9f0a2b4 — one-time repair helper
   isAutoManagedPrRecord, // W-mq5s5ttx000j7ab8-a — exported for engine + watch-plugin gate consolidation
   autoEnrollPrFromWorkItem,
   autoEnrollPrFromFixWorkItem,