@yemi33/minions 0.1.1004 → 0.1.1006

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 0.1.1004 (2026-04-15)
+## 0.1.1006 (2026-04-16)
 
 ### Features
+- cap pendingContexts in cooldowns.json to prevent bloat (#1126)
 - fix stopAfter=0 watch expiry — run forever for all conditions (#1117)
 - fix doc-chat Clear chat not persisting session deletion to localStorage (#1102)
 - remove DEFAULTS alias from timeout.js (#1101)
@@ -22,9 +23,9 @@
 - reassign tasks when preferred agent is busy too long
 - wire agentBusyReassignMs into settings UI and persist
 -  ADO throttle detection, poll guards, and dashboard banner (#1051)
-- gate auto-fix conflict dispatch behind autoFixConflicts flag
 
 ### Fixes
+-  harden repo-scoped PR identity handling
 -  only gate reviews/fixes when no free agent slots remain
 -  extend auto-link fallback to ADO projects
 -  auto-link existing GitHub PR when agent completes without creating one
@@ -44,7 +45,6 @@
 -  defer review setCooldown to post-gating in discoverWork
 -  move review verdict check before updateWorkItemStatus(DONE)
 -  address review feedback — move writeToInbox outside lock, add absolute condition auto-expire
-- fix watches feature gaps — human notifications, branch stub, status-change init, unique keys
 
 ### Other
 - refactor: migrate PR links to array format and consolidate shared helpers

package/dashboard.js

@@ -2172,7 +2172,11 @@ const server = http.createServer(async (req, res) => {
       }
 
       // Build a manifest of all KB entries with their content (skip pinned — user wants to keep them)
-      const pinnedKeys = new Set(body.pinnedKeys || []);
+      const requestPinnedKeys = Array.isArray(body.pinnedKeys)
+        ? body.pinnedKeys.filter(k => typeof k === 'string' && k.startsWith('knowledge/'))
+        : [];
+      const serverPinnedKeys = shared.getPinnedItems().filter(k => k.startsWith('knowledge/'));
+      const pinnedKeys = new Set([...serverPinnedKeys, ...requestPinnedKeys]);
       const manifest = [];
       for (const e of entries) {
         if (pinnedKeys.has('knowledge/' + e.cat + '/' + e.file)) continue;
@@ -2180,6 +2184,11 @@ const server = http.createServer(async (req, res) => {
         if (!content) continue;
         manifest.push({ category: e.cat, file: e.file, title: e.title, agent: e.agent, date: e.date, content: content.slice(0, 3000) });
       }
+      if (manifest.length < 2) {
+        global._kbSweepLastResult = { ok: true, summary: 'nothing to sweep (< 2 unpinned entries)' };
+        global._kbSweepLastCompletedAt = Date.now();
+        return;
+      }
 
       const { callLLM, trackEngineUsage } = require('./engine/llm');
       const BATCH_SIZE = 30; // ~30 entries per batch to stay within Haiku context
@@ -4364,7 +4373,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // Extract PR number from URL
       const prNumMatch = url.match(/\/pull\/(\d+)|pullrequest\/(\d+)/);
       const prNum = prNumMatch ? (prNumMatch[1] || prNumMatch[2]) : Date.now().toString().slice(-6);
-      const prId = 'PR-' + prNum;
+      const prId = shared.getCanonicalPrId(targetProject, prNum, url);
 
       // Atomic check-and-insert to prevent duplicates and races with polling loops
       let duplicate = false;
@@ -4373,6 +4382,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         if (prs.some(p => p.id === prId || p.url === url)) { duplicate = true; return prs; }
         prs.push({
           id: prId,
+          prNumber: parseInt(prNum, 10) || null,
           title: (title || 'PR #' + prNum + ' (polling...)').slice(0, 120),
           description: '',
           agent: 'human',

package/engine/ado-status.js

@@ -57,7 +57,8 @@ const prNumber = parseInt(prNumberArg, 10);
 function findInCache(projects) {
   for (const project of projects) {
     const prs = safeJsonArr(projectPrPath(project));
-    const pr = prs.find(p => p.prNumber === prNumber || p.id === `PR-${prNumber}`);
+    shared.normalizePrRecords(prs, project);
+    const pr = prs.find(p => p.prNumber === prNumber || p.id === shared.getCanonicalPrId(project, prNumber) || shared.getPrDisplayId(p) === `PR-${prNumber}`);
     if (!pr) continue;
     const out = {
       prNumber: pr.prNumber || prNumber,

package/engine/ado.js

@@ -255,7 +255,7 @@ async function forEachActivePr(config, token, callback) {
     for (let i = 0; i < activePrs.length; i += CONCURRENCY) {
       const batch = activePrs.slice(i, i + CONCURRENCY);
       const results = await Promise.allSettled(batch.map(async (pr) => {
-        const prNum = (pr.id || '').replace('PR-', '');
+        const prNum = shared.getPrNumber(pr);
         if (!prNum) return false;
         return callback(project, pr, prNum, orgBase);
       }));
@@ -680,6 +680,7 @@ async function reconcilePrs(config) {
 
     const prPath = shared.projectPrPath(project);
     const existingPrs = shared.safeJson(prPath) || [];
+    shared.normalizePrRecords(existingPrs, project);
     const existingIds = new Set(existingPrs.map(p => p.id));
     let projectAdded = 0;
 
@@ -692,7 +693,8 @@ async function reconcilePrs(config) {
 
     let projectUpdated = 0;
     for (const adoPr of adoPrs) {
-      const prId = `PR-${adoPr.pullRequestId}`;
+      const prUrl = getAdoPrUrl(project, adoPr.pullRequestId);
+      const prId = shared.getCanonicalPrId(project, adoPr.pullRequestId, prUrl);
       const branch = stripRefsHeads(adoPr.sourceRefName);
       const title = adoPr.title || '';
       // Extract item ID from branch name or PR title (e.g., feat(P-2cafdc2a): ...)
@@ -710,7 +712,7 @@ async function reconcilePrs(config) {
         }
         // PR already tracked — write link to pr-links.json if we can extract an ID
         if (confirmedItemId) {
-          addPrLink(prId, confirmedItemId);
+          addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -725,7 +727,6 @@ async function reconcilePrs(config) {
       // are human-authored and should not be auto-tracked or auto-reviewed.
       if (!confirmedItemId) continue;
 
-      const prUrl = project.prUrlBase ? project.prUrlBase + adoPr.pullRequestId : '';
       existingPrs.push({
         id: prId,
         prNumber: adoPr.pullRequestId,
@@ -738,7 +739,7 @@ async function reconcilePrs(config) {
         url: prUrl,
         prdItems: [confirmedItemId],
       });
-      addPrLink(prId, confirmedItemId);
+      addPrLink(prId, confirmedItemId, { project, prNumber: adoPr.pullRequestId, url: prUrl });
       existingIds.add(prId);
       projectAdded++;
       log('info', `PR reconciliation: added ${prId} (branch: ${branch}, linked to ${confirmedItemId}) to ${project.name}`);
@@ -747,7 +748,7 @@ async function reconcilePrs(config) {
     // Backfill prNumber from pr.id for any PR missing it (e.g. created before prNumber was stored)
     for (const pr of existingPrs) {
       if (pr.prNumber == null) {
-        const derived = parseInt((pr.id || '').replace(/^PR-/, ''), 10);
+        const derived = shared.getPrNumber(pr);
         if (derived) pr.prNumber = derived;
       }
     }
@@ -786,7 +787,8 @@ async function checkLiveReviewStatus(pr, project) {
     const token = await getAdoToken();
     if (!token) return null;
     const orgBase = shared.getAdoOrgBase(project);
-    const prNum = (pr.id || '').replace(/^PR-/, '');
+    const prNum = shared.getPrNumber(pr);
+    if (!prNum) return null;
     const url = `${orgBase}/${project.adoProject}/_apis/git/repositories/${project.repositoryId}/pullrequests/${prNum}?api-version=7.1`;
     const result = await execAsync(`curl -s --max-time 4 -H "Authorization: Bearer ${token}" "${url}"`, { encoding: 'utf-8', timeout: 5000, windowsHide: true });
     const prData = JSON.parse(result);
@@ -851,7 +853,7 @@ async function fetchSinglePrBuildStatus(project, prNumber) {
       }));
       const logParts = [];
       const seenBuildIds = new Set();
-      const pr = { id: `PR-${prNumber}`, branch: stripRefsHeads(prData.sourceRefName) };
+      const pr = { id: shared.getCanonicalPrId(project, prNumber, getAdoPrUrl(project, prNumber)), branch: stripRefsHeads(prData.sourceRefName) };
       for (const fb of failedBuilds.slice(0, 3)) {
         const errorLog = await fetchAdoBuildErrorLog(orgBase, project, fb, token, pr, seenBuildIds);
         if (errorLog) logParts.push(errorLog);

package/engine/cleanup.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { exec, execSilent, log, ts } = shared;
+const { exec, execSilent, log, ts, ENGINE_DEFAULTS } = shared;
 const { safeJson, safeWrite, safeReadDir, mutateWorkItems, getProjects, projectWorkItemsPath, projectPrPath,
   sanitizeBranch, KB_CATEGORIES } = shared;
 const { getDispatch, getAgentStatus } = queries;
@@ -597,11 +597,23 @@ function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'prune doc-sessions: ' + e.message); }
 
   // 11. Cap cooldowns.json — keep at most 500 entries (on top of 24h TTL in cooldown.js)
+  //     Also trim pendingContexts arrays to ENGINE_DEFAULTS.maxPendingContexts to prevent bloat.
   cleaned.cooldowns = 0;
+  cleaned.pendingContextsTrimmed = 0;
   try {
     const cooldownPath = path.join(ENGINE_DIR, 'cooldowns.json');
     const cooldowns = safeJson(cooldownPath);
     if (cooldowns && typeof cooldowns === 'object') {
+      let dirty = false;
+      // Trim oversized pendingContexts arrays (one-time migration + ongoing cap)
+      const pendingCtxCap = ENGINE_DEFAULTS.maxPendingContexts;
+      for (const v of Object.values(cooldowns)) {
+        if (Array.isArray(v.pendingContexts) && v.pendingContexts.length > pendingCtxCap) {
+          v.pendingContexts = v.pendingContexts.slice(-pendingCtxCap);
+          cleaned.pendingContextsTrimmed++;
+          dirty = true;
+        }
+      }
       const entries = Object.entries(cooldowns);
       const COOLDOWN_CAP = 500;
       if (entries.length > COOLDOWN_CAP) {
@@ -610,6 +622,8 @@ function runCleanup(config, verbose = false) {
         const keep = Object.fromEntries(entries.slice(0, COOLDOWN_CAP));
         cleaned.cooldowns = entries.length - COOLDOWN_CAP;
         safeWrite(cooldownPath, keep);
+      } else if (dirty) {
+        safeWrite(cooldownPath, cooldowns);
       }
     }
   } catch (e) { log('warn', 'cap cooldowns: ' + e.message); }
@@ -653,8 +667,8 @@ function runCleanup(config, verbose = false) {
     }
   } catch { /* optional — file may not exist */ }
 
-  if (cleaned.ccSessions + cleaned.docSessions + cleaned.cooldowns + cleaned.pidFiles > 0) {
-    log('info', `Cleanup (resources): ${cleaned.ccSessions} cc-sessions, ${cleaned.docSessions} doc-sessions, ${cleaned.cooldowns} cooldowns, ${cleaned.pidFiles} PID files`);
+  if (cleaned.ccSessions + cleaned.docSessions + cleaned.cooldowns + cleaned.pidFiles + cleaned.pendingContextsTrimmed > 0) {
+    log('info', `Cleanup (resources): ${cleaned.ccSessions} cc-sessions, ${cleaned.docSessions} doc-sessions, ${cleaned.cooldowns} cooldowns, ${cleaned.pendingContextsTrimmed} pendingCtx trimmed, ${cleaned.pidFiles} PID files`);
   }
 
   return cleaned;

package/engine/consolidation.js

@@ -25,7 +25,8 @@ function consolidateInbox(config) {
 
   const { ENGINE_DEFAULTS } = shared;
   const threshold = config.engine?.inboxConsolidateThreshold || ENGINE_DEFAULTS.inboxConsolidateThreshold;
-  const files = getInboxFiles().filter(f => !_processingFiles.has(f));
+  const pinnedInboxKeys = new Set(shared.getPinnedItems().filter(k => k.startsWith('notes/inbox/')));
+  const files = getInboxFiles().filter(f => !_processingFiles.has(f) && !pinnedInboxKeys.has('notes/inbox/' + f));
   if (files.length < threshold) return;
   // Auto-reset stale flag if consolidation has been running for >5 minutes (process died without cleanup)
   if (_consolidationInFlight && (Date.now() - _consolidationStartedAt) > 300000) {
@@ -485,4 +486,3 @@ module.exports = {
   classifyToKnowledgeBase,
   checkDuplicateHash,
 };
-

package/engine/cooldown.js

@@ -7,7 +7,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeWrite, log } = shared;
+const { safeJson, safeWrite, log, ENGINE_DEFAULTS } = shared;
 const { ENGINE_DIR } = queries;
 
 const COOLDOWN_PATH = path.join(ENGINE_DIR, 'cooldowns.json');
@@ -37,6 +37,13 @@ function saveCooldowns() {
     for (const [k, v] of dispatchCooldowns) {
       if (now - v.timestamp > 24 * 60 * 60 * 1000) dispatchCooldowns.delete(k);
     }
+    // Trim pendingContexts arrays before writing to prevent bloat
+    const cap = ENGINE_DEFAULTS.maxPendingContexts;
+    for (const [, v] of dispatchCooldowns) {
+      if (Array.isArray(v.pendingContexts) && v.pendingContexts.length > cap) {
+        v.pendingContexts = v.pendingContexts.slice(-cap);
+      }
+    }
     const obj = Object.fromEntries(dispatchCooldowns);
     try {
       safeWrite(COOLDOWN_PATH, obj);
@@ -61,8 +68,11 @@ function setCooldown(key) {
 
 function setCooldownWithContext(key, context) {
   const existing = dispatchCooldowns.get(key);
-  const pendingContexts = existing?.pendingContexts || [];
+  let pendingContexts = existing?.pendingContexts || [];
   if (context) pendingContexts.push(context);
+  // Cap to last N entries to prevent unbounded growth (cooldowns.json bloat)
+  const cap = ENGINE_DEFAULTS.maxPendingContexts;
+  if (pendingContexts.length > cap) pendingContexts = pendingContexts.slice(-cap);
   dispatchCooldowns.set(key, {
     timestamp: Date.now(),
     failures: existing?.failures || 0,

package/engine/dispatch.js

@@ -223,7 +223,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
         try {
           const prsPath = projectPrPath(project);
           mutatePullRequests(prsPath, prs => {
-            const target = prs.find(p => p.id === prId);
+            const target = shared.findPrRecord(prs, { id: prId }, project);
             if (target?.humanFeedback) target.humanFeedback.pendingFix = true;
           });
           log('info', `Restored pendingFix=true on ${prId} after failed human-feedback fix`);
@@ -246,9 +246,10 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
 
 function writeInboxAlert(slug, content) {
   try {
-    const file = path.join(INBOX_DIR, `engine-alert-${slug}-${dateStamp()}.md`);
+    const safeSlug = shared.safeSlugComponent(slug, 100);
+    const file = path.join(INBOX_DIR, `engine-alert-${safeSlug}-${dateStamp()}.md`);
     // Dedupe: don't write the same alert twice in the same day
-    const existing = safeReadDir(INBOX_DIR).find(f => f.startsWith(`engine-alert-${slug}-${dateStamp()}`));
+    const existing = safeReadDir(INBOX_DIR).find(f => f.startsWith(`engine-alert-${safeSlug}-${dateStamp()}`));
     if (existing) return;
     safeWrite(file, content);
   } catch (e) { log('warn', 'write inbox alert: ' + e.message); }

package/engine/github.js

@@ -199,7 +199,7 @@ async function forEachActiveGhPr(config, callback) {
     let projectUpdated = 0;
 
     for (const pr of activePrs) {
-      const prNum = (pr.id || '').replace('PR-', '');
+      const prNum = shared.getPrNumber(pr);
       if (!prNum) continue;
 
       try {
@@ -621,6 +621,7 @@ async function reconcilePrs(config) {
 
     const prPath = projectPrPath(project);
     const currentPrs = safeJson(prPath) || [];
+    shared.normalizePrRecords(currentPrs, project);
     const existingIds = new Set(currentPrs.map(p => p.id));
     let projectAdded = 0;
 
@@ -632,7 +633,8 @@ async function reconcilePrs(config) {
     const allItems = [...workItems, ...centralItems];
 
     for (const ghPr of ghPrs) {
-      const prId = `PR-${ghPr.number}`;
+      const prUrl = project.prUrlBase ? project.prUrlBase + ghPr.number : ghPr.html_url || '';
+      const prId = shared.getCanonicalPrId(project, ghPr.number, prUrl);
       const branch = ghPr.head?.ref || '';
       const wiMatch = branch.match(/(P-[a-z0-9]{6,})/i) || branch.match(/(W-[a-z0-9]{6,})/i) || branch.match(/(PL-[a-z0-9]{6,})/i);
       const linkedItemId = wiMatch ? wiMatch[1] : null;
@@ -646,7 +648,7 @@ async function reconcilePrs(config) {
           existing.prNumber = ghPr.number;
         }
         if (confirmedItemId) {
-          addPrLink(prId, confirmedItemId);
+          addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
           if (existing && !(existing.prdItems || []).includes(confirmedItemId)) {
             existing.prdItems = Array.isArray(existing.prdItems) ? existing.prdItems : [];
             existing.prdItems.push(confirmedItemId);
@@ -661,8 +663,6 @@ async function reconcilePrs(config) {
       // Only auto-track PRs linked to a minions work item — skip human-authored PRs
       if (!confirmedItemId && !isE2eBranch) continue;
 
-      const prUrl = project.prUrlBase ? project.prUrlBase + ghPr.number : ghPr.html_url || '';
-
       currentPrs.push({
         id: prId,
         prNumber: ghPr.number,
@@ -675,7 +675,7 @@ async function reconcilePrs(config) {
         url: prUrl,
         prdItems: [confirmedItemId],
       });
-      addPrLink(prId, confirmedItemId);
+      addPrLink(prId, confirmedItemId, { project, prNumber: ghPr.number, url: prUrl });
       existingIds.add(prId);
       projectAdded++;
 
@@ -685,7 +685,7 @@ async function reconcilePrs(config) {
     // Backfill prNumber from pr.id for any PR missing it (e.g. created before prNumber was stored)
     for (const pr of currentPrs) {
       if (pr.prNumber == null) {
-        const derived = parseInt((pr.id || '').replace(/^PR-/, ''), 10);
+        const derived = shared.getPrNumber(pr);
         if (derived) pr.prNumber = derived;
       }
     }
@@ -719,7 +719,8 @@ async function checkLiveReviewStatus(pr, project) {
   try {
     const slug = getRepoSlug(project);
     if (!slug) return null;
-    const prNum = (pr.id || '').replace(/^PR-/, '');
+    const prNum = shared.getPrNumber(pr);
+    if (!prNum) return null;
     const reviews = await ghApi(`/pulls/${prNum}/reviews`, slug);
     if (!reviews || !Array.isArray(reviews)) return null;
     const latestByUser = new Map();

package/engine/lifecycle.js

@@ -781,10 +781,11 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   const newPrsByPath = new Map(); // prPath -> [{ prId, newEntry }]
 
   for (const prId of prMatches) {
-    const fullId = `PR-${prId}`;
     const targetProject = useCentral ? null : resolveProjectForPr(prId);
     const targetName = targetProject ? targetProject.name : '_central';
     const prPath = targetProject ? shared.projectPrPath(targetProject) : centralPrPath;
+    const prUrl = extractPrUrl(prId);
+    const fullId = shared.getCanonicalPrId(targetProject, prId, prUrl);
 
     let title = meta?.item?.title || '';
     const titleMatch = output.match(new RegExp(`${prId}[^\\n]*?[—–-]\\s*([^\\n]+)`, 'i'));
@@ -793,7 +794,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
       title = meta?.item?.title || '';
     }
 
-    if (!newPrsByPath.has(prPath)) newPrsByPath.set(prPath, { name: targetName, entries: [] });
+    if (!newPrsByPath.has(prPath)) newPrsByPath.set(prPath, { name: targetName, project: targetProject, entries: [] });
     newPrsByPath.get(prPath).entries.push({
       prId, fullId,
       entry: {
@@ -805,7 +806,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
         reviewStatus: 'pending',
         status: PR_STATUS.ACTIVE,
         created: ts(),
-        url: extractPrUrl(prId),
+        url: prUrl,
         prdItems: meta?.item?.id ? [meta.item.id] : [],
         sourcePlan: meta?.item?.sourcePlan || '',
         itemType: meta?.item?.itemType || ''
@@ -813,7 +814,8 @@ function syncPrsFromOutput(output, agentId, meta, config) {
     });
   }
 
-  for (const [prPath, { name, entries }] of newPrsByPath) {
+  for (const [prPath, { name, project: targetProject, entries }] of newPrsByPath) {
+    const linksToPersist = [];
     mutateJsonFileLocked(prPath, (data) => {
       const prs = Array.isArray(data) ? data : [];
       // Normalize legacy YYYY-MM-DD created dates to ISO
@@ -821,13 +823,18 @@ function syncPrsFromOutput(output, agentId, meta, config) {
         if (p.created && p.created.length === 10) p.created = p.created + 'T00:00:00.000Z';
       }
       for (const { prId, fullId, entry } of entries) {
-        if (prs.some(p => p.id === fullId || String(p.id) === String(prId))) continue;
+        if (prs.some(p => p.id === fullId || (p.url && p.url === entry.url))) continue;
         prs.push(entry);
-        if (meta?.item?.id) addPrLink(fullId, meta.item.id);
+        if (meta?.item?.id) {
+          linksToPersist.push({ prId: fullId, itemId: meta.item.id, project: targetProject, prNumber: entry.prNumber, url: entry.url });
+        }
         added++;
       }
       return prs;
     });
+    for (const { prId, itemId, project, prNumber, url } of linksToPersist) {
+      addPrLink(prId, itemId, { project, prNumber, url });
+    }
     log('info', `Synced PR(s) from ${agentName}'s output to ${name === '_central' ? 'central' : name}/pull-requests.json`);
   }
   return added;
@@ -894,7 +901,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary)
   let updatedTarget = null;
   shared.mutateJsonFileLocked(prPath, (prs) => {
     if (!Array.isArray(prs)) return prs;
-    const target = prs.find(p => p.id === pr.id);
+    const target = shared.findPrRecord(prs, pr, project);
     if (!target) return prs;
     // Once approved, stays approved — only changes-requested can override
     if (postReviewStatus) {
@@ -938,7 +945,7 @@ function updatePrAfterFix(pr, project, source) {
   const prPath = project ? shared.projectPrPath(project) : path.join(path.resolve(MINIONS_DIR, '..'), '.minions', 'pull-requests.json');
   shared.mutateJsonFileLocked(prPath, (prs) => {
     if (!Array.isArray(prs)) return prs;
-    const target = prs.find(p => p.id === pr.id);
+    const target = shared.findPrRecord(prs, pr, project);
     if (!target) return prs;
     // Never downgrade from approved — fix was dispatched but PR is already approved
     if (target.reviewStatus !== 'approved') target.reviewStatus = 'waiting';
@@ -1083,7 +1090,7 @@ async function processPendingRebases(config) {
 
 async function handlePostMerge(pr, project, config, newStatus) {
 
-  const prNum = (pr.id || '').replace('PR-', '');
+  const prNum = shared.getPrNumber(pr);
 
   if (pr.branch && project) {
     const root = path.resolve(project.localPath);
@@ -1329,7 +1336,8 @@ function createReviewFeedbackForAuthor(reviewerAgentId, pr, config) {
   const reviewFiles = inboxFiles.filter(f => f.includes(reviewerAgentId) && f.includes(today));
   if (reviewFiles.length === 0) return;
   const reviewContent = reviewFiles.map(f => safeRead(path.join(INBOX_DIR, f))).filter(Boolean).join('\n\n');
-  const feedbackFile = `feedback-${authorAgentId}-from-${reviewerAgentId}-${pr.id}-${today}.md`;
+  const prSlug = shared.safeSlugComponent(pr.id, 60);
+  const feedbackFile = `feedback-${authorAgentId}-from-${reviewerAgentId}-${prSlug}-${today}.md`;
   const feedbackPath = shared.uniquePath(path.join(INBOX_DIR, feedbackFile));
   const content = `# Review Feedback for ${config.agents[authorAgentId]?.name || authorAgentId}\n\n` +
     `**PR:** ${pr.id} — ${pr.title || ''}\n` +
@@ -1845,7 +1853,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
             log('debug', `Skipping branch PR lookup for unsupported repo host "${host}" on ${projectObj.name}`);
           }
           if (found) {
-            const fullId = `PR-${found.prNumber}`;
+            const fullId = shared.getCanonicalPrId(projectObj, found.prNumber, found.url);
             const prPath = shared.projectPrPath(projectObj);
             mutateJsonFileLocked(prPath, prs => {
               if (!Array.isArray(prs)) prs = [];

package/engine/pipeline.js

@@ -703,7 +703,7 @@ function isStageComplete(stage, stageState, run, config) {
       for (const project of projects) {
         const prs = safeJson(shared.projectPrPath(project)) || [];
         for (const prId of prIds) {
-          const pr = prs.find(p => p.id === prId);
+          const pr = shared.findPrRecord(prs, prId, project);
           if (pr && pr.status !== PR_STATUS.MERGED && pr.status !== PR_STATUS.ABANDONED) return false;
         }
       }

package/engine/queries.js

@@ -419,7 +419,11 @@ function getAgentDetail(id) {
 // ── Pull Requests ───────────────────────────────────────────────────────────
 
 function getPrs(project) {
-  if (project) return safeJson(projectPrPath(project)) || [];
+  if (project) {
+    const prs = safeJson(projectPrPath(project)) || [];
+    shared.normalizePrRecords(prs, project);
+    return prs;
+  }
   const config = getConfig();
   const all = [];
   for (const p of getProjects(config)) all.push(...getPrs(p));
@@ -433,9 +437,13 @@ function getPullRequests(config) {
   for (const project of projects) {
     const prs = safeJson(projectPrPath(project));
     if (!prs) continue;
+    shared.normalizePrRecords(prs, project);
     const base = project.prUrlBase || '';
     for (const pr of prs) {
-      if (!pr.url && base && pr.id) pr.url = base + String(pr.id).replace('PR-', '');
+      if (!pr.url && base) {
+        const prNumber = shared.getPrNumber(pr);
+        if (prNumber != null) pr.url = base + prNumber;
+      }
       pr._project = project.name || 'Project';
       allPrs.push(pr);
     }
@@ -444,6 +452,7 @@ function getPullRequests(config) {
   const centralPath = path.join(MINIONS_DIR, 'pull-requests.json');
   const centralPrs = safeJson(centralPath);
   if (centralPrs) {
+    shared.normalizePrRecords(centralPrs, null);
     for (const pr of centralPrs) {
       if (!allPrs.some(p => p.id === pr.id)) {
         pr._project = 'central';
@@ -737,9 +746,16 @@ function getWorkItems(config) {
   const allPrs = getPullRequests(config);
   for (const item of allItems) {
     if (item._pr && !item._prUrl) {
-      const prId = String(item._pr).replace('PR-', '');
-      const pr = allPrs.find(p => String(p.id).includes(prId));
-      if (pr) item._prUrl = pr.url;
+      const project = projects.find(p => p.name === item.project || p.name === item._source) || null;
+      const canonicalPrId = shared.getCanonicalPrId(project, item._pr);
+      const displayPrId = shared.getPrDisplayId(item._pr);
+      const exactPr = allPrs.find(p => p.id === canonicalPrId);
+      const displayMatches = exactPr ? [] : allPrs.filter(p => shared.getPrDisplayId(p) === displayPrId);
+      const pr = exactPr || (displayMatches.length === 1 ? displayMatches[0] : null);
+      if (pr) {
+        item._pr = pr.id;
+        item._prUrl = pr.url;
+      }
     }
     if (!item._pr) {
       // Derive from PR.prdItems (single source of truth)
@@ -953,7 +969,8 @@ function getPrdInfo(config) {
   for (const [prId, itemIds] of Object.entries(prLinks)) {
     const pr = prById[prId];
     const project = projects.find(p => p.name === pr?._project) || projects[0] || null;
-    const url = pr?.url || (project?.prUrlBase ? project.prUrlBase + prId.replace('PR-', '') : '');
+    const prNumber = shared.getPrNumber(pr || prId);
+    const url = pr?.url || (project?.prUrlBase && prNumber != null ? project.prUrlBase + prNumber : '');
     for (const itemId of (itemIds || [])) {
       if (!prdToPr[itemId]) prdToPr[itemId] = [];
       prdToPr[itemId].push({ id: prId, url, title: pr?.title || '', status: pr?.status || 'active', _project: pr?._project || '' });
@@ -962,10 +979,14 @@ function getPrdInfo(config) {
   // Fallback: work item _pr field for anything still missing
   for (const wi of Object.values(wiById)) {
     if (!wi._pr || prdToPr[wi.id]?.length) continue;
-    const pr = prById[wi._pr];
-    const project = projects.find(p => p.name === wi.project || p.name === wi._source);
-    const url = pr?.url || (project?.prUrlBase ? project.prUrlBase + wi._pr.replace('PR-', '') : '');
-    prdToPr[wi.id] = [{ id: wi._pr, url, title: pr?.title || '', status: pr?.status || 'active', _project: project?.name || '' }];
+    const project = projects.find(p => p.name === wi.project || p.name === wi._source) || null;
+    const canonicalPrId = shared.getCanonicalPrId(project, wi._pr);
+    const exactPr = prById[canonicalPrId] || null;
+    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 prNumber = shared.getPrNumber(pr || wi._pr);
+    const url = pr?.url || (project?.prUrlBase && prNumber != null ? project.prUrlBase + prNumber : '');
+    prdToPr[wi.id] = [{ id: pr?.id || canonicalPrId || wi._pr, url, title: pr?.title || '', status: 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) {
@@ -978,7 +999,8 @@ function getPrdInfo(config) {
       if (!prdToPr[parentId]) prdToPr[parentId] = [];
       if (!prdToPr[parentId].some(p => p.id === pr.id)) {
         const project = projects.find(p => p.name === pr._project) || projects[0] || null;
-        const url = pr.url || (project?.prUrlBase ? project.prUrlBase + pr.id.replace('PR-', '') : '');
+        const prNumber = shared.getPrNumber(pr);
+        const url = pr.url || (project?.prUrlBase && prNumber != null ? project.prUrlBase + prNumber : '');
         prdToPr[parentId].push({ id: pr.id, url, title: pr.title || '', status: pr.status || 'active', _project: pr._project || '' });
       }
     }

package/engine/shared.js

@@ -5,9 +5,11 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 const MINIONS_DIR = process.env.MINIONS_TEST_DIR || path.resolve(__dirname, '..');
 const PR_LINKS_PATH = path.join(MINIONS_DIR, 'engine', 'pr-links.json');
+const PINNED_ITEMS_PATH = path.join(MINIONS_DIR, 'engine', 'kb-pins.json');
 const LOG_PATH = path.join(MINIONS_DIR, 'engine', 'log.json');
 
 // ── Timestamps & Logging ────────────────────────────────────────────────────
@@ -244,6 +246,9 @@ function mutateJsonFileLocked(filePath, mutateFn, {
     // Back up last-known-good state before mutation (best-effort)
     const backupPath = filePath + '.backup';
     try { if (fs.existsSync(filePath)) fs.copyFileSync(filePath, backupPath); } catch { /* backup is best-effort */ }
+    if (path.basename(filePath) === 'pull-requests.json' && Array.isArray(data)) {
+      normalizePrRecords(data, resolveProjectForPrPath(filePath));
+    }
     const next = mutateFn(data);
     const finalData = next === undefined ? data : next;
     safeWrite(filePath, finalData);
@@ -298,7 +303,8 @@ function parseNoteId(content) {
 function writeToInbox(agentId, slug, content, _inboxDir, metadata) {
   try {
     const inboxDir = _inboxDir || path.join(MINIONS_DIR, 'notes', 'inbox');
-    const prefix = `${agentId}-${slug}-${dateStamp()}`;
+    const safeSlug = safeSlugComponent(slug, 80);
+    const prefix = `${agentId}-${safeSlug}-${dateStamp()}`;
     const existing = safeReadDir(inboxDir).find(f => f.startsWith(prefix));
     if (existing) return false;
     const noteId = `NOTE-${uid()}`;
@@ -563,6 +569,7 @@ const ENGINE_DEFAULTS = {
   ccModel: 'sonnet', // model for Command Center and doc-chat (sonnet, haiku, opus)
   ccEffort: null, // effort level for CC/doc-chat (null, 'low', 'medium', 'high')
   heartbeatTimeouts: {}, // populated after WORK_TYPE is defined (below)
+  maxPendingContexts: 20, // cap pendingContexts arrays in cooldowns.json to prevent unbounded growth
   ccMaxTurns: 50, // max tool-use turns for CC/doc-chat before CLI stops
   // Teams integration — config.teams shape: { enabled, appId, appPassword, certPath, privateKeyPath, tenantId, notifyEvents, ccMirror, inboxPollInterval }
   // Auth modes: (1) appId + appPassword (client secret), or (2) appId + certPath + privateKeyPath + tenantId (certificate)
@@ -738,6 +745,7 @@ const DEFAULT_CLAUDE = {
 // ── Project Helpers ──────────────────────────────────────────────────────────
 
 function getProjects(config) {
+  if (!config) config = safeJson(path.join(MINIONS_DIR, 'config.json')) || {};
   if (config && config.projects && Array.isArray(config.projects)) {
     return config.projects.filter(p => {
       if (!p || typeof p !== 'object') return false;
@@ -771,6 +779,14 @@ function projectPrPath(project) {
   return path.join(projectStateDir(project), 'pull-requests.json');
 }
 
+function resolveProjectForPrPath(filePath, config = null) {
+  const resolvedPath = path.resolve(filePath);
+  for (const project of getProjects(config)) {
+    if (path.resolve(projectPrPath(project)) === resolvedPath) return project;
+  }
+  return null;
+}
+
 // ── ID Generation ────────────────────────────────────────────────────────────
 
 function nextWorkItemId(items, prefix) {
@@ -859,9 +875,151 @@ function parseSkillFrontmatter(content, filename) {
 // Stable single-writer file: maps PR IDs → PRD item IDs.
 // Never touched by polling loops — only written when a PR is first linked to a PRD item.
 
+function normalizePrScopeSegment(value) {
+  return String(value || '').trim().replace(/^\/+|\/+$/g, '').toLowerCase();
+}
+
+function parseCanonicalPrId(value) {
+  const match = String(value || '').trim().match(/^(github|ado):(.+?)#(\d+)$/i);
+  if (!match) return null;
+  const scope = `${match[1].toLowerCase()}:${match[2].split('/').map(normalizePrScopeSegment).join('/')}`;
+  return { scope, prNumber: parseInt(match[3], 10) };
+}
+
+function parseGitHubPrUrl(url) {
+  const match = String(url || '').match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i);
+  if (!match) return null;
+  return {
+    scope: `github:${normalizePrScopeSegment(match[1])}/${normalizePrScopeSegment(match[2])}`,
+    prNumber: parseInt(match[3], 10),
+  };
+}
+
+function parseAdoPrUrl(url) {
+  const devAzure = String(url || '').match(/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)/i);
+  if (devAzure) {
+    return {
+      scope: `ado:${normalizePrScopeSegment(devAzure[1])}/${normalizePrScopeSegment(devAzure[2])}/${normalizePrScopeSegment(decodeURIComponent(devAzure[3]))}`,
+      prNumber: parseInt(devAzure[4], 10),
+    };
+  }
+  const visualStudio = String(url || '').match(/https?:\/\/([^/.]+)\.visualstudio\.com\/(?:DefaultCollection\/)?([^/]+)\/_git\/([^/]+)\/pullrequest\/(\d+)/i);
+  if (!visualStudio) return null;
+  return {
+    scope: `ado:${normalizePrScopeSegment(visualStudio[1])}/${normalizePrScopeSegment(visualStudio[2])}/${normalizePrScopeSegment(decodeURIComponent(visualStudio[3]))}`,
+    prNumber: parseInt(visualStudio[4], 10),
+  };
+}
+
+function getProjectPrScope(project) {
+  if (!project) return '';
+  const host = String(project.repoHost || '').toLowerCase();
+  if (host === 'github') {
+    const parsed = parseGitHubPrUrl(project.prUrlBase || '');
+    if (parsed?.scope) return parsed.scope;
+    const owner = normalizePrScopeSegment(project.adoOrg);
+    const repo = normalizePrScopeSegment(project.repoName);
+    return owner && repo ? `github:${owner}/${repo}` : '';
+  }
+  if (host === 'ado' || !host) {
+    const parsed = parseAdoPrUrl(project.prUrlBase || '');
+    if (parsed?.scope) return parsed.scope;
+    const org = normalizePrScopeSegment(project.adoOrg);
+    const adoProject = normalizePrScopeSegment(project.adoProject);
+    const repo = normalizePrScopeSegment(project.repoName || project.repositoryId);
+    return org && adoProject && repo ? `ado:${org}/${adoProject}/${repo}` : '';
+  }
+  return '';
+}
+
+function getPrNumber(value) {
+  if (value && typeof value === 'object') {
+    if (value.prNumber != null && /^\d+$/.test(String(value.prNumber))) {
+      return parseInt(String(value.prNumber), 10);
+    }
+    return getPrNumber(value.id || value.url || '');
+  }
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  const canonical = parseCanonicalPrId(raw);
+  if (canonical) return canonical.prNumber;
+  const parsedUrl = parseGitHubPrUrl(raw) || parseAdoPrUrl(raw);
+  if (parsedUrl) return parsedUrl.prNumber;
+  const legacy = raw.match(/^PR-(\d+)$/i) || raw.match(/^(\d+)$/);
+  return legacy ? parseInt(legacy[1], 10) : null;
+}
+
+function getPrDisplayId(value, fallbackPrNumber = null) {
+  const prNumber = getPrNumber(value) ?? getPrNumber(fallbackPrNumber);
+  if (prNumber != null) return `PR-${prNumber}`;
+  return typeof value === 'object' ? String(value?.id || '') : String(value || '');
+}
+
+function getCanonicalPrId(project, prRef, url = '') {
+  const isObjectRef = !!prRef && typeof prRef === 'object';
+  const rawId = isObjectRef ? (prRef.id || '') : String(prRef || '');
+  const canonical = parseCanonicalPrId(rawId);
+  if (canonical) return `${canonical.scope}#${canonical.prNumber}`;
+  const parsedUrl = parseGitHubPrUrl(url || (isObjectRef ? prRef.url || '' : ''))
+    || parseAdoPrUrl(url || (isObjectRef ? prRef.url || '' : ''));
+  const prNumber = getPrNumber(isObjectRef ? (prRef.prNumber ?? prRef.id ?? prRef.url) : prRef);
+  if (prNumber == null) return rawId;
+  const scope = getProjectPrScope(project) || parsedUrl?.scope || '';
+  return scope ? `${scope}#${prNumber}` : `PR-${prNumber}`;
+}
+
+function findPrRecord(prs, prRef, project = null) {
+  if (!Array.isArray(prs) || !prRef) return null;
+  const isObjectRef = typeof prRef === 'object';
+  const rawId = isObjectRef ? String(prRef.id || '') : String(prRef || '');
+  const refUrl = isObjectRef ? String(prRef.url || '') : '';
+  const canonicalId = getCanonicalPrId(project, prRef, refUrl);
+  if (canonicalId) {
+    const canonicalMatch = prs.find(pr => pr?.id === canonicalId);
+    if (canonicalMatch) return canonicalMatch;
+  }
+  if (rawId) {
+    const rawMatch = prs.find(pr => pr?.id === rawId);
+    if (rawMatch) return rawMatch;
+  }
+  if (refUrl) {
+    const urlMatch = prs.find(pr => pr?.url === refUrl);
+    if (urlMatch) return urlMatch;
+  }
+  const refNumber = getPrNumber(isObjectRef ? (prRef.prNumber ?? prRef.id ?? prRef.url) : prRef);
+  if (refNumber == null) return null;
+  const numberMatches = prs.filter(pr => getPrNumber(pr) === refNumber);
+  return numberMatches.length === 1 ? numberMatches[0] : null;
+}
+
+function normalizePrRecord(pr, project = null) {
+  if (!pr || typeof pr !== 'object') return false;
+  let changed = false;
+  const prNumber = getPrNumber(pr.prNumber ?? pr.id ?? pr.url);
+  if (prNumber != null && pr.prNumber !== prNumber) {
+    pr.prNumber = prNumber;
+    changed = true;
+  }
+  const canonicalId = getCanonicalPrId(project, pr, pr.url || '');
+  if (canonicalId && pr.id !== canonicalId) {
+    pr.id = canonicalId;
+    changed = true;
+  }
+  return changed;
+}
+
+function normalizePrRecords(prs, project = null) {
+  if (!Array.isArray(prs)) return 0;
+  let changed = 0;
+  for (const pr of prs) {
+    if (normalizePrRecord(pr, project)) changed++;
+  }
+  return changed;
+}
+
 function normalizePrLinkItems(value) {
   const items = Array.isArray(value) ? value : [value];
-  return [...new Set(items.filter(Boolean))];
+  return [...new Set(items.filter(item => typeof item === 'string' && item))];
 }
 
 function mergePrLinkItems(links, prId, itemIds) {
@@ -872,25 +1030,56 @@ function mergePrLinkItems(links, prId, itemIds) {
 
 function getPrLinks() {
   const links = {};
+  const knownPrIdsByDisplay = new Map();
+  const registerPrId = (pr) => {
+    if (!pr?.id) return;
+    const displayId = getPrDisplayId(pr);
+    if (!displayId) return;
+    if (!knownPrIdsByDisplay.has(displayId)) knownPrIdsByDisplay.set(displayId, new Set());
+    knownPrIdsByDisplay.get(displayId).add(pr.id);
+  };
   // Primary source: derive from all projects/*/pull-requests.json prdItems
   const projectsDir = path.join(MINIONS_DIR, 'projects');
+  const projectsByName = new Map(getProjects().map(project => [project.name || path.basename(project.localPath || ''), project]));
   try {
     for (const d of fs.readdirSync(projectsDir, { withFileTypes: true })) {
       if (!d.isDirectory()) continue;
       try {
         const prs = JSON.parse(fs.readFileSync(path.join(projectsDir, d.name, 'pull-requests.json'), 'utf8'));
+        const project = projectsByName.get(d.name) || null;
+        normalizePrRecords(prs, project);
         for (const pr of prs) {
           if (!pr.id) continue;
+          registerPrId(pr);
           mergePrLinkItems(links, pr.id, pr.prdItems || []);
         }
       } catch { /* missing or invalid */ }
     }
   } catch { /* projects dir missing */ }
+  try {
+    const centralPrs = JSON.parse(fs.readFileSync(path.join(MINIONS_DIR, 'pull-requests.json'), 'utf8'));
+    normalizePrRecords(centralPrs, null);
+    for (const pr of centralPrs) {
+      if (!pr.id) continue;
+      registerPrId(pr);
+      mergePrLinkItems(links, pr.id, pr.prdItems || []);
+    }
+  } catch { /* central file optional */ }
   // Fallback: static pr-links.json for entries not covered above
   try {
     const static_ = JSON.parse(fs.readFileSync(PR_LINKS_PATH, 'utf8'));
     for (const [k, v] of Object.entries(static_)) {
-      if (!links[k]) mergePrLinkItems(links, k, v);
+      const canonical = parseCanonicalPrId(k);
+      let normalizedKey = canonical ? `${canonical.scope}#${canonical.prNumber}` : k;
+      if (!canonical) {
+        const candidates = knownPrIdsByDisplay.get(getPrDisplayId(k));
+        if (candidates?.size === 1) normalizedKey = [...candidates][0];
+        else if (candidates?.size > 1) {
+          log('warn', `Skipping ambiguous legacy PR link "${k}" — multiple canonical PR IDs share display ID ${getPrDisplayId(k)}`);
+          continue;
+        }
+      }
+      if (!links[normalizedKey]) mergePrLinkItems(links, normalizedKey, v);
     }
   } catch { /* missing */ }
   return links;
@@ -913,13 +1102,48 @@ function backfillPrPrdItems(prs, prLinks) {
   return backfilled;
 }
 
-function addPrLink(prId, itemId) {
-  if (!prId || !itemId) return;
-  const links = safeJson(PR_LINKS_PATH) || {};
-  const current = normalizePrLinkItems(links[prId]);
-  if (current.includes(itemId)) return; // already correct, no write needed
-  links[prId] = [...current, itemId];
-  safeWrite(PR_LINKS_PATH, links);
+function addPrLink(prId, itemId, { project = null, url = '', prNumber = null } = {}) {
+  const canonicalPrId = getCanonicalPrId(project, prNumber ?? prId, url);
+  const effectivePrId = canonicalPrId || prId;
+  if (!effectivePrId || !itemId) return;
+  const legacyPrId = String(prId || '');
+  mutateJsonFileLocked(PR_LINKS_PATH, (links) => {
+    if (!links || Array.isArray(links) || typeof links !== 'object') links = {};
+    const mergedCurrent = new Set(normalizePrLinkItems(links[effectivePrId]));
+    if (legacyPrId && legacyPrId !== effectivePrId && links[legacyPrId]) {
+      for (const linkedItem of normalizePrLinkItems(links[legacyPrId])) mergedCurrent.add(linkedItem);
+      delete links[legacyPrId];
+    }
+    if (!mergedCurrent.has(itemId)) mergedCurrent.add(itemId);
+    links[effectivePrId] = [...mergedCurrent];
+    return links;
+  }, { defaultValue: {} });
+
+  if (!project) return;
+  const prPath = projectPrPath(project);
+  const effectivePrNumber = getPrNumber(prNumber ?? effectivePrId);
+  const prLockPath = `${prPath}.lock`;
+  withFileLock(prLockPath, () => {
+    if (!fs.existsSync(prPath)) return;
+    let prs = safeJson(prPath);
+    if (!Array.isArray(prs)) prs = [];
+    normalizePrRecords(prs, project);
+    const existingPr = prs.find(pr =>
+      pr?.id === effectivePrId
+      || (url && pr?.url === url)
+      || (effectivePrNumber != null && getPrNumber(pr) === effectivePrNumber)
+    );
+    if (!existingPr) return;
+    const backupPath = prPath + '.backup';
+    try { if (fs.existsSync(prPath)) fs.copyFileSync(prPath, backupPath); } catch { /* backup is best-effort */ }
+    existingPr.prdItems = Array.isArray(existingPr.prdItems) ? existingPr.prdItems : [];
+    if (existingPr.prdItems.includes(itemId)) return;
+    existingPr.prdItems.push(itemId);
+    safeWrite(prPath, prs);
+  }, {
+    retries: ENGINE_DEFAULTS.lockRetries,
+    retryBackoffMs: ENGINE_DEFAULTS.lockRetryBackoffMs
+  });
 }
 
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
@@ -1089,10 +1313,24 @@ function slugify(text, maxLen = 50) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, maxLen);
 }
 
+function safeSlugComponent(text, maxLen = 80) {
+  const raw = String(text || '').trim();
+  if (!raw) return 'item';
+  if (/^[A-Za-z0-9._-]+$/.test(raw) && raw.length <= maxLen) return raw;
+  const hash = crypto.createHash('md5').update(raw).digest('hex').slice(0, 8);
+  const base = slugify(raw, Math.max(8, maxLen - 9)) || 'item';
+  return `${base}-${hash}`.slice(0, maxLen);
+}
+
 function formatTranscriptEntry(t) {
   return '### ' + (t.agent || 'agent') + ' (' + (t.type || '') + ', Round ' + (t.round || '?') + ')\n\n' + (t.content || '');
 }
 
+function getPinnedItems() {
+  const pins = safeJson(PINNED_ITEMS_PATH);
+  return Array.isArray(pins) ? pins.filter(item => typeof item === 'string' && item) : [];
+}
+
 // ── Throttle Tracker Factory ────────────────────────────────────────────────
 // Generic rate-limit tracker reusable by both ADO and GitHub integrations.
 // Returns an object with recordThrottle, recordSuccess, isThrottled, getState.
@@ -1149,6 +1387,7 @@ function createThrottleTracker({ label, baseBackoffMs = 60000, maxBackoffMs = 32
 module.exports = {
   MINIONS_DIR,
   PR_LINKS_PATH,
+  PINNED_ITEMS_PATH,
   LOG_PATH,
   ts,
   logTs,
@@ -1193,6 +1432,14 @@ module.exports = {
   projectPrPath,
   getPrLinks,
   addPrLink,
+  parseCanonicalPrId,
+  getProjectPrScope,
+  getPrNumber,
+  getPrDisplayId,
+  getCanonicalPrId,
+  findPrRecord,
+  normalizePrRecord,
+  normalizePrRecords,
   nextWorkItemId,
   getAdoOrgBase,
   sanitizePath,
@@ -1208,7 +1455,9 @@ module.exports = {
   LOCK_STALE_MS,
   flushLogs,
   slugify,
+  safeSlugComponent,
   formatTranscriptEntry,
+  getPinnedItems,
   _logBuffer, // exported for testing
   createThrottleTracker,
   backfillPrPrdItems,

package/engine/teams.js

@@ -543,7 +543,7 @@ async function teamsNotifyPrEvent(pr, event, project, prFilePath) {
     if (prFilePath) {
       mutateJsonFileLocked(prFilePath, (prs) => {
         if (!Array.isArray(prs)) return prs;
-        const target = prs.find(p => p.id === pr.id);
+        const target = shared.findPrRecord(prs, pr);
         if (target) {
           if (!target._teamsNotifiedEvents) target._teamsNotifiedEvents = [];
           if (!target._teamsNotifiedEvents.includes(event)) {

package/engine/watches.js

@@ -20,6 +20,14 @@ function _watchesPath() { return path.join(shared.MINIONS_DIR, 'engine', 'watche
 // so watches are checked every N ticks where N = ceil(interval / tickInterval).
 const DEFAULT_WATCH_INTERVAL = 300000;
 
+/** Find a PR by target (prNumber, canonical ID, or display ID). */
+function findPrByTarget(pullRequests, target) {
+  const t = String(target);
+  return (pullRequests || []).find(p =>
+    String(p.prNumber) === t || p.id === t || shared.getPrDisplayId(p) === t
+  );
+}
+
 /**
  * Read all watches from disk.
  * @returns {Array<object>}
@@ -131,9 +139,7 @@ function evaluateWatch(watch, state) {
   const { target, targetType, condition } = watch;
 
   if (targetType === WATCH_TARGET_TYPE.PR) {
-    const pr = (state.pullRequests || []).find(p =>
-      String(p.prNumber) === String(target) || p.id === target
-    );
+    const pr = findPrByTarget(state.pullRequests, target);
     if (!pr) return { triggered: false, message: `PR ${target} not found` };
 
     // Store previous state for status-change detection
@@ -290,9 +296,7 @@ function checkWatches(config, state) {
  */
 function _captureState(watch, state) {
   if (watch.targetType === WATCH_TARGET_TYPE.PR) {
-    const pr = (state.pullRequests || []).find(p =>
-      String(p.prNumber) === String(watch.target) || p.id === watch.target
-    );
+    const pr = findPrByTarget(state.pullRequests, watch.target);
     if (pr) return { status: pr.status, buildStatus: pr.buildStatus, reviewStatus: pr.reviewStatus, lastCommentDate: pr.humanFeedback?.lastProcessedCommentDate || null };
   }
   if (watch.targetType === WATCH_TARGET_TYPE.WORK_ITEM) {

package/engine.js

@@ -1878,7 +1878,7 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   try {
     const prsPath = projectPrPath(projectMeta);
     mutatePullRequests(prsPath, prs => {
-      const target = prs.find(p => p.id === prId);
+      const target = shared.findPrRecord(prs, prId, projectMeta);
       if (!target?.humanFeedback?.pendingFix) return;
       target.humanFeedback.pendingFix = false;
     });
@@ -1892,11 +1892,12 @@ async function discoverFromPrs(config, project) {
   const src = project?.workSources?.pullRequests || config.workSources?.pullRequests;
   if (!src?.enabled) return [];
 
-  const prs = safeJson(projectPrPath(project)) || [];
+  const prs = queries.getPrs(project);
   const cooldownMs = (src.cooldownMinutes || 30) * 60 * 1000;
   const newWork = [];
 
   const projMeta = { name: project?.name, localPath: project?.localPath };
+  const projectsByName = new Map(shared.getProjects(config).map(p => [p.name, p]));
 
   // Resolve poll-enabled per project — stale reviewStatus is untrustworthy without poller
   const isAdoProject = project?.repoHost !== 'github';
@@ -1908,12 +1909,21 @@ async function discoverFromPrs(config, project) {
   // Collect active PR dispatches to prevent simultaneous review+fix on same PR
   const dispatch = getDispatch();
   const activePrIds = new Set(
-    (dispatch.active || []).filter(d => d.meta?.pr?.id).map(d => d.meta.pr.id)
+    (dispatch.active || [])
+      .filter(d => d.meta?.pr?.id)
+      .map(d => {
+        const dispatchProject = d.meta?.project?.name
+          ? (projectsByName.get(d.meta.project.name) || d.meta.project)
+          : (d.meta?.project || null);
+        return shared.getCanonicalPrId(dispatchProject, d.meta.pr, d.meta.pr?.url || '');
+      })
+      .filter(Boolean)
   );
 
   const knownAgents = new Set(Object.keys(config.agents || {}));
   for (const pr of prs) {
     if (pr.status !== PR_STATUS.ACTIVE || pr._contextOnly) continue;
+    const prDisplayId = shared.getPrDisplayId(pr);
     if (activePrIds.has(pr.id)) continue; // Skip PRs with active dispatch (prevent race)
     // Branch mutex: skip if PR branch is locked by any active dispatch (cross-type collision)
     if (pr.branch && isBranchActive(pr.branch)) {
@@ -1925,7 +1935,7 @@ async function discoverFromPrs(config, project) {
     const isAgentPr = knownAgents.has((pr.agent || '').toLowerCase()) || (pr.prdItems && pr.prdItems.length > 0) || pr._autoObserve;
     if (!isAgentPr) continue;
 
-    const prNumber = (pr.id || '').replace(/^PR-/, '');
+    const prNumber = shared.getPrNumber(pr);
     // Use reviewStatus as single source of truth (synced from ADO/GitHub votes)
     // minionsReview tracks metadata (reviewer, note) but not the authoritative status
     const reviewStatus = pr.reviewStatus || 'pending';
@@ -1939,13 +1949,13 @@ async function discoverFromPrs(config, project) {
     const evalCycles = pr._reviewFixCycles || 0;
     const evalEscalated = evalCycles >= evalMax;
     if (evalEscalated && !pr._evalEscalated) {
-      writeInboxAlert(`eval-escalated-${pr.agent || 'unassigned'}-${pr.id}`,
+      writeInboxAlert(`eval-escalated-${pr.agent || 'unassigned'}-${prDisplayId}`,
         `# Review Loop Escalation\n\n**PR ${pr.id}**: ${pr.title || ''} on branch \`${pr.branch || 'unknown'}\` has gone through **${evalCycles}** review→fix cycles without approval.\n\n` +
         `Last review: ${pr.minionsReview?.note ? pr.minionsReview.note.slice(0, 200) : 'See PR thread'}\n\n` +
         `Auto-dispatch of reviews and fixes has been suspended. Please review the PR manually.`);
       try {
         mutatePullRequests(projectPrPath(project), prs => {
-          const target = prs.find(p => p.id === pr.id);
+          const target = shared.findPrRecord(prs, pr, project);
           if (target) target._evalEscalated = true;
         });
       } catch (e) { log('warn', 'mark eval escalated: ' + e.message); }
@@ -1957,7 +1967,7 @@ async function discoverFromPrs(config, project) {
     const alreadyReviewed = pr.lastReviewedAt && (!pr.lastPushedAt || pr.lastPushedAt <= pr.lastReviewedAt);
     const needsReview = reviewEnabled && reviewStatus === 'pending' && !alreadyReviewed && !evalEscalated;
     if (needsReview) {
-      const key = `review-${project?.name || 'default'}-${pr.id}`;
+      const key = `review-${project?.name || 'default'}-${prDisplayId}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
 
       // Pre-dispatch live vote check — cached reviewStatus may be stale (poll lag ~6 min)
@@ -1972,7 +1982,7 @@ async function discoverFromPrs(config, project) {
           try {
             mutateJsonFileLocked(projectPrPath(project), data => {
               if (!Array.isArray(data)) return data;
-              const target = data.find(p => p.id === pr.id);
+              const target = shared.findPrRecord(data, pr, project);
               if (target && target.reviewStatus !== 'approved') target.reviewStatus = liveStatus;
               return data;
             });
@@ -1998,7 +2008,7 @@ async function discoverFromPrs(config, project) {
     const needsReReview = reviewEnabled && reviewStatus === 'waiting' &&
       fixedAfterReview && !evalEscalated;
     if (needsReReview) {
-      const key = `rereview-${project?.name || 'default'}-${pr.id}`;
+      const key = `rereview-${project?.name || 'default'}-${prDisplayId}`;
       // Skip isAlreadyDispatched — fixedAfterReview/lastReviewedAt already dedupe; the 1hr
       // completed-dispatch window would block legitimate re-reviews within the hour after a fix
       if (isOnCooldown(key, cooldownMs)) continue;
@@ -2013,7 +2023,7 @@ async function discoverFromPrs(config, project) {
           try {
             mutateJsonFileLocked(projectPrPath(project), data => {
               if (!Array.isArray(data)) return data;
-              const target = data.find(p => p.id === pr.id);
+              const target = shared.findPrRecord(data, pr, project);
               if (target && target.reviewStatus !== 'approved') target.reviewStatus = liveStatus;
               return data;
             });
@@ -2036,7 +2046,7 @@ async function discoverFromPrs(config, project) {
     // Gate on evalLoopEnabled — the review→fix cycle is the eval loop
     let fixDispatched = false;
     if (evalLoopEnabled && reviewStatus === 'changes-requested' && !awaitingReReview && !evalEscalated) {
-      const key = `fix-${project?.name || 'default'}-${pr.id}`;
+      const key = `fix-${project?.name || 'default'}-${prDisplayId}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
       const agentId = resolveAgent('fix', config, pr.agent);
       if (!agentId) continue;
@@ -2050,7 +2060,7 @@ async function discoverFromPrs(config, project) {
         // Increment review→fix cycle counter
         try {
           mutatePullRequests(projectPrPath(project), prs => {
-            const target = prs.find(p => p.id === pr.id);
+            const target = shared.findPrRecord(prs, pr, project);
             if (target) target._reviewFixCycles = (target._reviewFixCycles || 0) + 1;
           });
         } catch (e) { log('warn', 'increment review-fix cycles: ' + e.message); }
@@ -2058,7 +2068,7 @@ async function discoverFromPrs(config, project) {
     }
 
     // PRs with pending human feedback (skip if review-fix already dispatched above)
-    const humanFixKey = `human-fix-${project?.name || 'default'}-${pr.id}`;
+    const humanFixKey = `human-fix-${project?.name || 'default'}-${prDisplayId}`;
     const hasCoalescedFeedback = (dispatchCooldowns.get(humanFixKey)?.pendingContexts || []).length > 0;
     if ((pr.humanFeedback?.pendingFix || hasCoalescedFeedback) && !awaitingReReview && !fixDispatched) {
       const key = humanFixKey;
@@ -2109,7 +2119,7 @@ async function discoverFromPrs(config, project) {
       // Check if max retry cap reached — escalate to human instead of dispatching another fix
       if ((pr.buildFixAttempts || 0) >= maxBuildFix) {
         if (!pr.buildFixEscalated) {
-          writeInboxAlert(`build-fix-escalated-${pr.agent || 'unassigned'}-${pr.id}`,
+          writeInboxAlert(`build-fix-escalated-${pr.agent || 'unassigned'}-${prDisplayId}`,
             `# Build Fix Escalation\n\n` +
             `**PR ${pr.id}**: ${pr.title || ''} on branch \`${pr.branch || 'unknown'}\` has failed **${pr.buildFixAttempts}** consecutive auto-fix attempts.\n` +
             `**Last failure:** ${pr.buildFailReason || 'Check CI pipeline for details'}\n\n` +
@@ -2118,7 +2128,7 @@ async function discoverFromPrs(config, project) {
           try {
             const prPath = projectPrPath(project);
             mutatePullRequests(prPath, prs => {
-              const target = prs.find(p => p.id === pr.id);
+              const target = shared.findPrRecord(prs, pr, project);
               if (target) target.buildFixEscalated = true;
             });
           } catch (e) { log('warn', 'mark build fix escalated: ' + e.message); }
@@ -2127,7 +2137,7 @@ async function discoverFromPrs(config, project) {
         continue;
       }
 
-      const key = `build-fix-${project?.name || 'default'}-${pr.id}`;
+      const key = `build-fix-${project?.name || 'default'}-${prDisplayId}`;
       if (isAlreadyDispatched(key) || isOnCooldown(key, cooldownMs)) continue;
       const agentId = resolveAgent('fix', config, pr.agent);
       if (!agentId) continue;
@@ -2147,7 +2157,7 @@ async function discoverFromPrs(config, project) {
         try {
           const prPath = projectPrPath(project);
           mutatePullRequests(prPath, prs => {
-            const target = prs.find(p => p.id === pr.id);
+            const target = shared.findPrRecord(prs, pr, project);
             if (target) {
               target.buildFixAttempts = (target.buildFixAttempts || 0) + 1;
               target._buildFixPushedAt = ts();
@@ -2167,12 +2177,12 @@ async function discoverFromPrs(config, project) {
           alertBody += `**Error preview:**\n\`\`\`\n${logPreview}\n\`\`\`\n\n`;
         }
         alertBody += `A fix agent has been dispatched to address this. Review the fix when complete.\n`;
-        writeInboxAlert(`build-fail-${pr.agent}-${pr.id}`, alertBody);
+        writeInboxAlert(`build-fail-${pr.agent}-${prDisplayId}`, alertBody);
         // Mark notified to prevent duplicate alerts
         try {
           const prPath = projectPrPath(project);
           mutatePullRequests(prPath, prs => {
-            const target = prs.find(p => p.id === pr.id);
+            const target = shared.findPrRecord(prs, pr, project);
             if (target) {
               target._buildFailNotified = true;
             }
@@ -2184,7 +2194,7 @@ async function discoverFromPrs(config, project) {
     // PRs with merge conflicts — dispatch fix to resolve (gated by autoFixConflicts)
     const autoFixConflicts = config.engine?.autoFixConflicts ?? ENGINE_DEFAULTS.autoFixConflicts;
     if (autoFixConflicts && pr.status === PR_STATUS.ACTIVE && pr._mergeConflict && !fixDispatched) {
-      const key = `conflict-fix-${project?.name || 'default'}-${pr.id}`;
+      const key = `conflict-fix-${project?.name || 'default'}-${prDisplayId}`;
       // Suppress re-dispatch for 10 min after last attempt — ADO/GitHub recomputes
       // mergeStatus asynchronously (1–5 min lag), so the flag may stay set even after
       // a successful push. _conflictFixedAt is cleared when the poller confirms clean status.
@@ -2203,7 +2213,7 @@ async function discoverFromPrs(config, project) {
             // Record dispatch timestamp so re-dispatch is suppressed during ADO lag window
             try {
               mutatePullRequests(projectPrPath(project), prs => {
-                const target = prs.find(p => p.id === pr.id);
+                const target = shared.findPrRecord(prs, pr, project);
                 if (target) target._conflictFixedAt = new Date().toISOString();
               });
             } catch (e) { log('warn', `conflict-fix timestamp: ${e.message}`); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1004",
+  "version": "0.1.1006",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"