@yemi33/minions 0.1.2087 → 0.1.2088

package/engine/github.js

@@ -5,7 +5,7 @@
  */
 
 const shared = require('./shared');
-const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeJsonArr, safeWrite, mutateJsonFileLocked, mutatePullRequests, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, ENGINE_DEFAULTS, createThrottleTracker, getProjectOrg } = shared;
+const { exec, execAsync, getProjects, projectPrPath, projectWorkItemsPath, safeJson, safeJsonArr, safeWrite, mutateJsonFileLocked, mutatePullRequests, MINIONS_DIR, getPrLinks, backfillPrPrdItems, log, ts, dateStamp, PR_STATUS, PR_POLLABLE_STATUSES, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, ENGINE_DEFAULTS, createThrottleTracker, getProjectOrg } = shared;
 const { getPrs } = require('./queries');
 const { isPreviewStatusBody, hasMinionsMarker, hasVerdictPrefix } = require('./comment-classifier');
 const { wrapUntrusted, buildSource } = require('./untrusted-fence');
@@ -392,7 +392,7 @@ async function fetchGhBuildErrorLog(slug, failedRuns) {
         const args = ['api', `repos/${shared.validateGhSlug(slug)}/actions/jobs/${jobId}/logs`];
         const token = ghToken.resolveTokenForSlug(slug);
         const env = token ? { ...process.env, GH_TOKEN: token } : undefined;
-        const result = await _runShellSafeGh(args, { timeout: 15000, maxBuffer: GH_MAX_BUFFER, env });
+        const result = await _runShellSafeGh(args, { timeout: FETCH_TIMEOUT_MS.GH_CLI, maxBuffer: GH_MAX_BUFFER, env });
         if (result && !result.includes('Not Found')) {
           logParts.push(`--- ${run.name || 'Check'} (log) ---\n${result}`);
         }
@@ -485,8 +485,8 @@ async function forEachActiveGhPr(config, callback) {
           const idx = currentPrs.findIndex(p => p.id === after.id);
           if (idx >= 0) {
             // Never downgrade reviewStatus from 'approved' — it's a permanent terminal state
-            if (currentPrs[idx].reviewStatus === 'approved' && after.reviewStatus !== 'approved') {
-              after.reviewStatus = 'approved';
+            if (currentPrs[idx].reviewStatus === REVIEW_STATUS.APPROVED && after.reviewStatus !== REVIEW_STATUS.APPROVED) {
+              after.reviewStatus = REVIEW_STATUS.APPROVED;
             }
             // W-mp5trwh60008386d: never downgrade `status: merged` — terminal state. A stale
             // 404 reaching `prAbandonConfirmCount` could otherwise overwrite a concurrent
@@ -812,12 +812,12 @@ async function pollPrStatus(config) {
 
       if (newStatus === PR_STATUS.MERGED || newStatus === PR_STATUS.ABANDONED) {
         // Resolve stale 'waiting' review status — won't be polled again after this
-        if (pr.reviewStatus === 'waiting') {
-          pr.reviewStatus = newStatus === PR_STATUS.MERGED ? 'approved' : 'pending';
+        if (pr.reviewStatus === REVIEW_STATUS.WAITING) {
+          pr.reviewStatus = newStatus === PR_STATUS.MERGED ? REVIEW_STATUS.APPROVED : REVIEW_STATUS.PENDING;
           log('info', `PR ${pr.id} reviewStatus: waiting → ${pr.reviewStatus} (${newStatus})`);
         }
         // Clear stale build status — checks won't be polled after close
-        if (pr.buildStatus && pr.buildStatus !== 'none') {
+        if (pr.buildStatus && pr.buildStatus !== BUILD_STATUS.NONE) {
           delete pr.buildStatus;
           delete pr.buildFailReason;
           delete pr.buildErrorLog;
@@ -857,7 +857,7 @@ async function pollPrStatus(config) {
         // F6 not yet shipped (field absent).
         delete pr.humanFeedback.editsSeen;
         pr.fixDispatched = false;
-        if (pr.reviewStatus !== 'approved') pr.reviewStatus = 'pending';
+        if (pr.reviewStatus !== REVIEW_STATUS.APPROVED) pr.reviewStatus = REVIEW_STATUS.PENDING;
         log('info', `PR ${pr.id} reopened — reset transient state (reviewStatus=${pr.reviewStatus})`);
       }
     }
@@ -887,20 +887,20 @@ async function pollPrStatus(config) {
         pr.reviewedBy = reviewedBy; updated = true;
       }
 
-      let newReviewStatus = pr.reviewStatus || 'pending';
+      let newReviewStatus = pr.reviewStatus || REVIEW_STATUS.PENDING;
       // Once approved, it stays approved permanently
-      if (pr.reviewStatus === 'approved') {
-        newReviewStatus = 'approved';
+      if (pr.reviewStatus === REVIEW_STATUS.APPROVED) {
+        newReviewStatus = REVIEW_STATUS.APPROVED;
       } else if (states.some(s => s === 'CHANGES_REQUESTED')) {
-        if (pr.reviewStatus === 'waiting' && pr.minionsReview?.fixedAt && (!pr.lastPushedAt || pr.lastPushedAt <= pr.minionsReview.fixedAt)) {
-          newReviewStatus = 'waiting';
+        if (pr.reviewStatus === REVIEW_STATUS.WAITING && pr.minionsReview?.fixedAt && (!pr.lastPushedAt || pr.lastPushedAt <= pr.minionsReview.fixedAt)) {
+          newReviewStatus = REVIEW_STATUS.WAITING;
         } else {
-          newReviewStatus = 'changes-requested';
+          newReviewStatus = REVIEW_STATUS.CHANGES_REQUESTED;
         }
       }
-      else if (states.some(s => s === 'APPROVED')) newReviewStatus = 'approved';
-      else if (states.length > 0) newReviewStatus = 'pending';
-      else if (states.length === 0 && reviews.length > 0 && newReviewStatus === 'pending') newReviewStatus = 'waiting';
+      else if (states.some(s => s === 'APPROVED')) newReviewStatus = REVIEW_STATUS.APPROVED;
+      else if (states.length > 0) newReviewStatus = REVIEW_STATUS.PENDING;
+      else if (states.length === 0 && reviews.length > 0 && newReviewStatus === REVIEW_STATUS.PENDING) newReviewStatus = REVIEW_STATUS.WAITING;
 
       if (pr.reviewStatus !== newReviewStatus) {
         log('info', `PR ${pr.id} reviewStatus: ${pr.reviewStatus} → ${newReviewStatus}`);
@@ -919,7 +919,7 @@ async function pollPrStatus(config) {
         pr.lastBuildCheck = ts();
         updated = true;
         const runs = checksData.check_runs;
-        let buildStatus = 'none';
+        let buildStatus = BUILD_STATUS.NONE;
         let buildFailReason = '';
         let buildFailureSignature = '';
 
@@ -929,7 +929,7 @@ async function pollPrStatus(config) {
           const allPassed = runs.every(r => r.conclusion === 'success' || r.conclusion === 'skipped' || r.conclusion === 'neutral');
 
           if (hasFailed) {
-            buildStatus = 'failing';
+            buildStatus = BUILD_STATUS.FAILING;
             const failed = runs.find(r => r.conclusion === 'failure' || r.conclusion === 'timed_out');
             buildFailReason = failed?.name || 'Check failed';
             buildFailureSignature = shared.safeSlugComponent([
@@ -940,21 +940,21 @@ async function pollPrStatus(config) {
               failed?.output?.text,
             ].filter(Boolean).join('\n') || buildFailReason, 80);
           } else if (allDone && allPassed) {
-            buildStatus = 'passing';
+            buildStatus = BUILD_STATUS.PASSING;
           } else if (allDone) {
             // Terminal-but-not-passing conclusions (cancelled, action_required,
             // stale, etc.) — map to 'none' rather than 'failing'. These are not
             // actionable build failures, so we deliberately do not block merge or
             // dispatch build-fix agents. Previously fell through to 'running'
             // forever (P-bf02-github-cancelled-stuck).
-            buildStatus = 'none';
+            buildStatus = BUILD_STATUS.NONE;
           } else {
-            buildStatus = 'running';
+            buildStatus = BUILD_STATUS.RUNNING;
           }
         }
 
         if (pr.buildStatus !== buildStatus) {
-          log('info', `PR ${pr.id} build: ${pr.buildStatus || 'none'} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
+          log('info', `PR ${pr.id} build: ${pr.buildStatus || BUILD_STATUS.NONE} → ${buildStatus}${buildFailReason ? ' (' + buildFailReason + ')' : ''}`);
           pr.buildStatus = buildStatus;
           if (buildFailReason) pr.buildFailReason = buildFailReason;
           else delete pr.buildFailReason;
@@ -962,14 +962,14 @@ async function pollPrStatus(config) {
           else delete pr.buildFailureSignature;
           // Build transitioned — clear grace period and auto-complete flag
           delete pr._buildFixPushedAt;
-          if (buildStatus === 'failing') delete pr._autoCompleted; // allow re-merge after fix
-          if (buildStatus !== 'failing') {
+          if (buildStatus === BUILD_STATUS.FAILING) delete pr._autoCompleted; // allow re-merge after fix
+          if (buildStatus !== BUILD_STATUS.FAILING) {
             delete pr._buildFailNotified;
             // Preserve buildErrorLog + buildFixAttempts through transient 'none'/'running'
             // transitions — only clear on confirmed 'passing' recovery. Issue #1232:
             // clearing on every non-failing transition blinded the next fix agent
             // while a queued build was still running.
-            if (buildStatus === 'passing') {
+            if (buildStatus === BUILD_STATUS.PASSING) {
               delete pr.buildErrorLog;
               delete pr.buildFailureSignature;
               // Reset build fix retry counter on recovery — allows fresh auto-fix cycles if build breaks again
@@ -978,7 +978,7 @@ async function pollPrStatus(config) {
           }
           updated = true;
         }
-        if (buildStatus === 'failing') {
+        if (buildStatus === BUILD_STATUS.FAILING) {
           if (buildFailReason && pr.buildFailReason !== buildFailReason) {
             pr.buildFailReason = buildFailReason;
             updated = true;
@@ -1005,7 +1005,7 @@ async function pollPrStatus(config) {
     }
 
     // Auto-complete: merge PR when builds green + review approved
-    if (pr.status === PR_STATUS.ACTIVE && pr.reviewStatus === 'approved' && pr.buildStatus === 'passing' && !pr._autoCompleted) {
+    if (pr.status === PR_STATUS.ACTIVE && pr.reviewStatus === REVIEW_STATUS.APPROVED && pr.buildStatus === BUILD_STATUS.PASSING && !pr._autoCompleted) {
       const autoComplete = config.engine?.autoCompletePrs === true; // opt-in
       if (autoComplete) {
         try {
@@ -1271,7 +1271,7 @@ async function reconcilePrs(config) {
             title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
             agent: (linkedItem?.dispatched_to || ghPr.user?.login || 'unknown').toLowerCase(),
             branch,
-            reviewStatus: 'pending',
+            reviewStatus: REVIEW_STATUS.PENDING,
             status: 'active',
             created: ghPr.created_at || ts(),
             url: prUrl,
@@ -1297,7 +1297,7 @@ async function reconcilePrs(config) {
         title: (ghPr.title || `PR #${ghPr.number}`).slice(0, 120),
         agent: (linkedItem?.dispatched_to || ghPr.user?.login || 'unknown').toLowerCase(),
         branch,
-        reviewStatus: 'pending',
+        reviewStatus: REVIEW_STATUS.PENDING,
         status: 'active',
         created: ghPr.created_at || ts(),
         url: prUrl,
@@ -1358,10 +1358,10 @@ async function checkLiveReviewStatus(pr, project) {
       latestByUser.set(r.user?.login || '', r.state);
     }
     const states = [...latestByUser.values()];
-    if (states.some(s => s === 'CHANGES_REQUESTED')) return 'changes-requested';
-    if (states.some(s => s === 'APPROVED')) return 'approved';
-    if (states.length > 0) return 'pending';
-    return 'pending';
+    if (states.some(s => s === 'CHANGES_REQUESTED')) return REVIEW_STATUS.CHANGES_REQUESTED;
+    if (states.some(s => s === 'APPROVED')) return REVIEW_STATUS.APPROVED;
+    if (states.length > 0) return REVIEW_STATUS.PENDING;
+    return REVIEW_STATUS.PENDING;
   } catch (e) {
     log('warn', `Live review check for ${pr.id}: ${e.message}`);
     return null;
@@ -1527,14 +1527,14 @@ async function checkLiveBuildAndConflict(pr, project) {
         if (checksData && Array.isArray(checksData.check_runs)) {
           const runs = checksData.check_runs;
           if (runs.length === 0) {
-            buildStatus = 'none';
+            buildStatus = BUILD_STATUS.NONE;
           } else {
             const hasFailed = runs.some(r => r.conclusion === 'failure' || r.conclusion === 'timed_out');
             const allDone = runs.every(r => r.status === 'completed');
             const allPassed = runs.every(r => r.conclusion === 'success' || r.conclusion === 'skipped' || r.conclusion === 'neutral');
-            if (hasFailed) buildStatus = 'failing';
-            else if (allDone && allPassed) buildStatus = 'passing';
-            else buildStatus = 'running';
+            if (hasFailed) buildStatus = BUILD_STATUS.FAILING;
+            else if (allDone && allPassed) buildStatus = BUILD_STATUS.PASSING;
+            else buildStatus = BUILD_STATUS.RUNNING;
           }
         }
       } catch (e) {

package/engine/lifecycle.js

@@ -8,7 +8,7 @@ const path = require('path');
 const os = require('os');
 const shared = require('./shared');
 const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, projectPrPath, getPrLinks,
-  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, DISPATCH_RESULT,
+  log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PR_STATUS, REVIEW_STATUS, RETRY_DELAY_MS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
 const { resolveRuntime } = require('./runtimes');
@@ -907,7 +907,7 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       title: (title || `PR created by ${agentName}`).slice(0, 120),
       agent: agentName,
       branch: meta?.branch || '',
-      reviewStatus: 'pending',
+      reviewStatus: REVIEW_STATUS.PENDING,
       status: PR_STATUS.ACTIVE,
       // W-mpej044m00076d63: do NOT seed `created` with ts() (engine discovery time).
       // The next GitHub/ADO poll backfills `pr.created` from the platform's real
@@ -1161,7 +1161,7 @@ async function findOpenPrForBranch(meta, config) {
     if (!ghSlug) return null;
     const maxAttempts = ENGINE_DEFAULTS.prAutoLinkRetries;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
-      if (attempt > 0) await new Promise(r => setTimeout(r, 3000));
+      if (attempt > 0) await new Promise(r => setTimeout(r, RETRY_DELAY_MS));
       let raw = '';
       try {
         raw = await runFileCapture('gh', ['pr', 'list', '--head', String(meta.branch), '--repo', ghSlug, '--json', 'number,url,state', '--limit', '1'], { timeout: 15000 });
@@ -1225,7 +1225,7 @@ function _attachFoundPrToWi(found, meta, agentId, resultSummary, config) {
     title: meta.item?.title || `PR #${found.prNumber}`,
     agent: agentId,
     branch: meta.branch || '',
-    reviewStatus: 'pending',
+    reviewStatus: REVIEW_STATUS.PENDING,
     status: PR_STATUS.ACTIVE,
     // W-mpej044m00076d63: omit `created` — the next poll backfills from the
     // platform's real createdAt. `_attachedAt` is the discovery-time fallback.
@@ -1699,10 +1699,10 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
   //     live platform status into local reviewStatus below (which can promote the
   //     PR to 'approved' based on platform-side votes).
   const prevReviewStatus = reviewPr?.reviewStatus || '';
-  const wasNegative = prevReviewStatus === 'changes-requested' || prevReviewStatus === 'waiting'
-    || liveStatus === 'changes-requested' || liveStatus === 'waiting';
+  const wasNegative = prevReviewStatus === REVIEW_STATUS.CHANGES_REQUESTED || prevReviewStatus === REVIEW_STATUS.WAITING
+    || liveStatus === REVIEW_STATUS.CHANGES_REQUESTED || liveStatus === REVIEW_STATUS.WAITING;
   const autoApplyVote = config?.engine?.autoApplyReviewVote ?? ENGINE_DEFAULTS.autoApplyReviewVote;
-  const canDismissOwnPriorNegative = verdictRaw === 'approved' && !isSelfReview && wasNegative && projectObjForChecks;
+  const canDismissOwnPriorNegative = verdictRaw === REVIEW_STATUS.APPROVED && !isSelfReview && wasNegative && projectObjForChecks;
   if (canDismissOwnPriorNegative) {
     try {
       const reconcileFn = hostForChecks === 'github'
@@ -1726,7 +1726,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     }
   }
 
-  if (autoApplyVote && liveStatus && liveStatus !== 'pending') postReviewStatus = liveStatus;
+  if (autoApplyVote && liveStatus && liveStatus !== REVIEW_STATUS.PENDING) postReviewStatus = liveStatus;
 
   // Fallback: if live check returned pending (e.g., GitHub self-approval blocked), use the agent's completion report.
   if (!postReviewStatus) {
@@ -1740,7 +1740,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       // the verdict and skips the no-verdict retry path, so _retryCount stays
       // unchanged. REQUEST_CHANGES from a self-author is still accepted — a
       // self-author flagging issues on their own PR is harmless and useful.
-      if (verdict === 'approved' && isSelfReview) {
+      if (verdict === REVIEW_STATUS.APPROVED && isSelfReview) {
         log('warn', `review verdict rejected: self-review (reviewer=${reviewerName}, author=${reviewPr.agent})`);
       } else {
         postReviewStatus = verdict;
@@ -1757,7 +1757,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     if (!target) return prs;
     // Once approved, stays approved — only changes-requested can override
     if (postReviewStatus) {
-      if (target.reviewStatus === 'approved' && postReviewStatus !== 'changes-requested') {
+      if (target.reviewStatus === REVIEW_STATUS.APPROVED && postReviewStatus !== REVIEW_STATUS.CHANGES_REQUESTED) {
         // Keep approved — don't downgrade
       } else {
         target.reviewStatus = postReviewStatus;
@@ -1779,7 +1779,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       ...(reviewThreads.length > 0 ? { threads: reviewThreads } : {}),
       // Preserve fixedAt across re-reviews so the poller guard knows a fix was pushed.
       // Drop it when reviewer requests changes again — that starts a new fix cycle.
-      ...(target.minionsReview?.fixedAt && postReviewStatus !== 'changes-requested' ? { fixedAt: target.minionsReview.fixedAt } : {}),
+      ...(target.minionsReview?.fixedAt && postReviewStatus !== REVIEW_STATUS.CHANGES_REQUESTED ? { fixedAt: target.minionsReview.fixedAt } : {}),
     };
     updatedTarget = { ...reviewPr, ...target };
     return prs;
@@ -1796,7 +1796,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
     });
   }
 
-  log('info', `Updated ${reviewPr.id} → minions review: ${postReviewStatus || 'waiting'} by ${reviewerName}`);
+  log('info', `Updated ${reviewPr.id} → minions review: ${postReviewStatus || REVIEW_STATUS.WAITING} by ${reviewerName}`);
   if (updatedTarget) {
     createReviewFeedbackForAuthor(agentId, updatedTarget, config, {
       reviewContent: reviewNote,
@@ -2188,7 +2188,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
       if (target.humanFeedback && clearPendingFix) target.humanFeedback.pendingFix = false;
       if (explicitlyChangedBranch) {
         // Never downgrade from approved — fix was dispatched but PR is already approved
-        if (target.reviewStatus !== 'approved') target.reviewStatus = 'waiting';
+        if (target.reviewStatus !== REVIEW_STATUS.APPROVED) target.reviewStatus = REVIEW_STATUS.WAITING;
         target.minionsReview = { ...target.minionsReview, note: 'Fixed human feedback, awaiting re-review', fixedAt: ts() };
         if (clearPendingFix) {
           log('info', `Updated ${pr.id} → cleared humanFeedback.pendingFix, reset to waiting for re-review`);
@@ -2204,7 +2204,7 @@ function updatePrAfterFix(pr, project, source, options = {}, legacyDispatchId =
         }
       }
     } else {
-      if (target.reviewStatus !== 'approved') target.reviewStatus = 'waiting';
+      if (target.reviewStatus !== REVIEW_STATUS.APPROVED) target.reviewStatus = REVIEW_STATUS.WAITING;
       if (explicitlyChangedBranch) {
         target.minionsReview = { ...target.minionsReview, note: 'Fixed, awaiting re-review', fixedAt: ts() };
         log('info', `Updated ${pr.id} → reviewStatus: waiting (fix pushed)`);
@@ -3193,6 +3193,175 @@ function parseCompletionReportFile(dispatchItem, opts = {}) {
   return report;
 }
 
+function normalizeCompletionArtifacts(rawArtifacts) {
+  let artifacts = rawArtifacts;
+  if (typeof artifacts === 'string') {
+    const trimmed = artifacts.trim();
+    if (!trimmed) return [];
+    try { artifacts = JSON.parse(trimmed); } catch { return []; }
+  }
+  if (!Array.isArray(artifacts)) {
+    artifacts = shared.isPlainObject(artifacts) ? [artifacts] : [];
+  }
+  const out = [];
+  for (const artifact of artifacts) {
+    if (!shared.isPlainObject(artifact)) continue;
+    const normalized = {};
+    for (const key of ['type', 'path', 'title', 'id']) {
+      if (artifact[key] == null) continue;
+      const value = String(artifact[key]).trim();
+      if (value) normalized[key] = value;
+    }
+    if (!normalized.path && !normalized.id && !normalized.title) continue;
+    if (normalized.path) normalized.path = normalizeArtifactPath(normalized.path);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function normalizeArtifactPath(artifactPath) {
+  const raw = String(artifactPath || '').trim();
+  if (!raw) return '';
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) return raw;
+  let normalized = raw.replace(/\\/g, '/');
+  if (path.isAbsolute(raw)) {
+    try {
+      const rel = path.relative(MINIONS_DIR, raw).replace(/\\/g, '/');
+      if (rel && !rel.startsWith('../') && rel !== '..') normalized = rel;
+    } catch {}
+  }
+  return normalized.replace(/^\.\//, '');
+}
+
+function _artifactFilesystemPath(artifactPath) {
+  if (!artifactPath || /^[a-z][a-z0-9+.-]*:\/\//i.test(artifactPath)) return null;
+  if (path.isAbsolute(artifactPath)) return artifactPath;
+  return path.join(MINIONS_DIR, artifactPath);
+}
+
+function completionArtifactToNoteEntry(artifact) {
+  if (!shared.isPlainObject(artifact)) return null;
+  const type = String(artifact.type || '').toLowerCase();
+  const artifactPath = normalizeArtifactPath(artifact.path || '');
+  const notePath = artifactPath.replace(/\\/g, '/');
+  const isNote = type === 'note' || /(^|\/)notes\/(?:inbox|archive)\//.test(notePath);
+  if (!isNote || !notePath || /^[a-z][a-z0-9+.-]*:\/\//i.test(notePath)) return null;
+
+  const base = path.basename(notePath);
+  const file = notePath.includes('notes/archive/') ? `archive:${base}` : base;
+  if (!file || file === '.' || file === '/') return null;
+  const entry = { file };
+  if (artifact.id) entry.id = String(artifact.id);
+  if (artifact.title) entry.title = String(artifact.title);
+  if (artifact.path) entry.path = artifactPath;
+  if (!entry.id) {
+    const filePath = _artifactFilesystemPath(artifactPath);
+    if (filePath) {
+      const noteId = shared.parseNoteId(safeRead(filePath));
+      if (noteId) entry.id = noteId;
+    }
+  }
+  return entry;
+}
+
+function mergeCompletionArtifacts(existing, additions) {
+  const merged = [];
+  const seen = new Set();
+  function keyFor(artifact) {
+    if (!shared.isPlainObject(artifact)) return '';
+    return [
+      String(artifact.type || ''),
+      String(artifact.path || ''),
+      String(artifact.id || ''),
+      String(artifact.title || ''),
+    ].join('\u0000');
+  }
+  for (const artifact of [...(Array.isArray(existing) ? existing : []), ...(Array.isArray(additions) ? additions : [])]) {
+    if (!shared.isPlainObject(artifact)) continue;
+    const normalized = normalizeCompletionArtifacts([artifact])[0];
+    if (!normalized) continue;
+    const key = keyFor(normalized);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(normalized);
+  }
+  return merged;
+}
+
+function mergeArtifactNotes(existing, additions) {
+  const merged = [];
+  const seen = new Set();
+  function normalize(note) {
+    if (shared.isPlainObject(note)) {
+      const file = String(note.file || '').trim();
+      if (!file) return null;
+      const out = { file };
+      for (const key of ['id', 'title', 'path']) {
+        if (note[key] == null) continue;
+        const value = String(note[key]).trim();
+        if (value) out[key] = value;
+      }
+      return out;
+    }
+    const file = String(note || '').trim();
+    return file ? file : null;
+  }
+  function keyFor(note) {
+    return shared.isPlainObject(note)
+      ? String(note.file || '')
+      : String(note || '');
+  }
+  for (const note of [...(Array.isArray(existing) ? existing : []), ...(Array.isArray(additions) ? additions : [])]) {
+    const normalized = normalize(note);
+    if (!normalized) continue;
+    const key = keyFor(normalized);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(normalized);
+  }
+  return merged;
+}
+
+function promoteCompletionArtifacts(meta, agentId, dispatchId, structuredCompletion, opts = {}) {
+  const itemId = meta?.item?.id;
+  if (!itemId) return { artifacts: [], notes: [] };
+  const wiPath = resolveWorkItemPath(meta);
+  if (!wiPath) return { artifacts: [], notes: [] };
+
+  const artifacts = normalizeCompletionArtifacts(structuredCompletion?.artifacts);
+  const structuredNotes = artifacts.map(completionArtifactToNoteEntry).filter(Boolean);
+  const additionalNotes = Array.isArray(opts.additionalNotes) ? opts.additionalNotes : [];
+  const notes = mergeArtifactNotes(structuredNotes, additionalNotes);
+  const outputLog = opts.outputLog ? String(opts.outputLog) : '';
+  const branch = opts.branch || meta.branch || '';
+  const resultSummary = opts.resultSummary ? String(opts.resultSummary).slice(0, 500) : '';
+
+  if (artifacts.length === 0 && notes.length === 0 && !outputLog && !branch && !resultSummary) {
+    return { artifacts, notes };
+  }
+
+  mutateJsonFileLocked(wiPath, data => {
+    if (!Array.isArray(data)) return data;
+    const wi = data.find(i => i.id === itemId);
+    if (!wi) return data;
+    const arts = shared.isPlainObject(wi._artifacts) ? { ...wi._artifacts } : {};
+    if (outputLog) arts.outputLog = outputLog;
+    if (branch) arts.branch = branch;
+    if (wi._pr) arts.pr = wi._pr;
+    if (wi._prUrl) arts.prUrl = wi._prUrl;
+    if (notes.length > 0) arts.notes = mergeArtifactNotes(arts.notes, notes);
+    if (meta.item?.planFile) arts.plan = meta.item.planFile;
+    if (meta.item?._prdFilename) arts.prd = meta.item._prdFilename;
+    if (meta.item?.sourcePlan) arts.sourcePlan = meta.item.sourcePlan;
+    if (artifacts.length > 0) wi.artifacts = mergeCompletionArtifacts(wi.artifacts, artifacts);
+    if (resultSummary) wi.resultSummary = resultSummary;
+    wi._artifacts = arts;
+    return data;
+  }, { defaultValue: [], skipWriteIfUnchanged: true });
+
+  return { artifacts, notes, agentId, dispatchId };
+}
+
 function persistCompletionReport(dispatchItem, completion, source = 'fallback') {
   if (!dispatchItem?.id || !completion || typeof completion !== 'object') return completion;
   const reportPath = dispatchItem?.meta?.completionReportPath || shared.dispatchCompletionReportPath(dispatchItem.id);
@@ -3408,8 +3577,8 @@ function parseCompletionNoop(completion) {
 
 function normalizeReviewVerdict(verdict) {
   const value = String(verdict || '').trim().toLowerCase().replace(/[\s-]+/g, '_');
-  if (value === 'approve' || value === 'approved') return 'approved';
-  if (value === 'request_changes' || value === 'changes_requested' || value === 'changes-requested') return 'changes-requested';
+  if (value === 'approve' || value === 'approved') return REVIEW_STATUS.APPROVED;
+  if (value === 'request_changes' || value === 'changes_requested' || value === 'changes-requested') return REVIEW_STATUS.CHANGES_REQUESTED;
   return null;
 }
 
@@ -3795,8 +3964,8 @@ function dispatchReReviewForFix(fixDispatchItem, meta, config) {
     return null;
   }
   const reviewStatus = livePr.reviewStatus || '';
-  if (reviewStatus !== 'changes-requested' && reviewStatus !== 'waiting') {
-    log('info', `Re-review skipped for ${pr.id}: reviewStatus=${reviewStatus || 'pending'} (only changes-requested/waiting trigger closure-loop)`);
+  if (reviewStatus !== REVIEW_STATUS.CHANGES_REQUESTED && reviewStatus !== REVIEW_STATUS.WAITING) {
+    log('info', `Re-review skipped for ${pr.id}: reviewStatus=${reviewStatus || REVIEW_STATUS.PENDING} (only changes-requested/waiting trigger closure-loop)`);
     return null;
   }
 
@@ -4305,6 +4474,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       meta._noopReason = noopRationale.slice(0, 500);
     }
     updateWorkItemStatus(meta, WI_STATUS.DONE, '');
+    promoteCompletionArtifacts(meta, agentId, dispatchItem.id, structuredCompletion, { resultSummary });
   }
   // Failure retry is handled by completeDispatch in dispatch.js — not duplicated here.
   // Only clear _decomposing flag on failure so decompose items don't get permanently stuck.
@@ -4895,6 +5065,10 @@ module.exports = {
   enforcePrAttachmentContract,
   markMissingPrAttachment,
   parseCompletionReportFile,
+  normalizeCompletionArtifacts,
+  completionArtifactToNoteEntry,
+  mergeArtifactNotes,
+  promoteCompletionArtifacts,
   persistCompletionReport,
   runPostCompletionHooks,
   syncPrdFromPrs,

package/engine/projects.js

@@ -137,6 +137,10 @@ function removeProject(target, options = {}) {
     pipelineRefs: [],
     archivedTo: null,
     purgedDataDir: false,
+    // P-bfa2d-remove-project-cleanup — soft-delete tag counts for entries in
+    // the three central state files that survived the hard-cancel passes
+    // (steps 1, 2). See step 7.5 for the orphan-tag policy rationale.
+    orphanedRefs: { pullRequests: 0, workItems: 0, dispatches: 0 },
     warnings: [],
   };
 
@@ -300,6 +304,94 @@ function removeProject(target, options = {}) {
   } catch (e) { writeError = e; }
   if (writeError) return { ...summary, error: 'Failed to write config: ' + writeError.message };
 
+  // 7.5. P-bfa2d-remove-project-cleanup — Tag dangling refs in the three
+  //      CENTRAL state files (`pull-requests.json`, `work-items.json`,
+  //      `engine/dispatch.json`) so downstream consumers can filter or sweep
+  //      them. Project-local files in `projects/<name>/` are handled by
+  //      step 8 (archive or purge), so this step only touches central state.
+  //
+  //      Policy is soft-delete (`_orphaned_at` + `_orphaned_project` tags)
+  //      rather than hard-delete: preserves history for debugging, lets users
+  //      see exactly which records were affected if a wrong project name was
+  //      passed, and is reversible (strip the tags). Steps 1, 2 already
+  //      hard-cancel/drain matching pending entries; this step only catches
+  //      survivors (non-pending WIs, central PRs, defense-in-depth dispatch
+  //      survivors).
+  //
+  //      Lock acquisition is sequential and uses the mutate-* helpers from
+  //      engine/dispatch.js and engine/shared.js so we never hold two file
+  //      locks simultaneously. Order: dispatch.json → pull-requests.json →
+  //      work-items.json (alphabetical by basename). Each helper acquires
+  //      its own lock, runs the synchronous mutator, then releases before
+  //      the next helper runs.
+  try {
+    const orphanedAt = new Date().toISOString();
+    const orphanedProject = project.name;
+
+    // (a) engine/dispatch.json — defense-in-depth. cleanDispatchEntries in
+    //     step 2 should have already removed every matching entry; tag any
+    //     survivor so the operator can see the residue.
+    try {
+      dispatch.mutateDispatch((state) => {
+        for (const queue of ['pending', 'active', 'completed']) {
+          const arr = Array.isArray(state?.[queue]) ? state[queue] : [];
+          for (const d of arr) {
+            if (!d || d._orphaned_at) continue;
+            if (!_dispatchMatchesProject(d, project, projects)) continue;
+            d._orphaned_at = orphanedAt;
+            d._orphaned_project = orphanedProject;
+            summary.orphanedRefs.dispatches++;
+          }
+        }
+        return state;
+      });
+    } catch (e) { summary.warnings.push('orphan-tag dispatch: ' + e.message); }
+
+    // (b) MINIONS_DIR/pull-requests.json — central PR registry. PRs in this
+    //     file lack an explicit project field; match by canonical scope
+    //     (e.g. `github:owner/repo`) against the removed project's PR scope.
+    const centralPrPath = shared.centralPullRequestsPath();
+    if (fs.existsSync(centralPrPath)) {
+      try {
+        const projectScope = shared.getProjectPrScope(project);
+        if (projectScope) {
+          shared.mutatePullRequests(centralPrPath, (prs) => {
+            for (const pr of prs) {
+              if (!pr || pr._orphaned_at) continue;
+              const canonical = shared.parseCanonicalPrId(pr.id);
+              if (canonical?.scope !== projectScope) continue;
+              pr._orphaned_at = orphanedAt;
+              pr._orphaned_project = orphanedProject;
+              summary.orphanedRefs.pullRequests++;
+            }
+            return prs;
+          });
+        }
+      } catch (e) { summary.warnings.push('orphan-tag pull-requests: ' + e.message); }
+    }
+
+    // (c) MINIONS_DIR/work-items.json — central WI list. Pending/queued WIs
+    //     were already CANCELLED by cancelPendingWorkItems in step 1; tag
+    //     the remaining matchers (dispatched / done / failed / etc.) so
+    //     downstream consumers can filter them.
+    const centralWiPath = path.join(MINIONS_DIR, 'work-items.json');
+    if (fs.existsSync(centralWiPath)) {
+      try {
+        shared.mutateWorkItems(centralWiPath, (items) => {
+          for (const w of items) {
+            if (!w || w._orphaned_at) continue;
+            if (w.status === shared.WI_STATUS.CANCELLED) continue;
+            if (!_workItemMatchesProject(w, project, projects)) continue;
+            w._orphaned_at = orphanedAt;
+            w._orphaned_project = orphanedProject;
+            summary.orphanedRefs.workItems++;
+          }
+          return items;
+        });
+      } catch (e) { summary.warnings.push('orphan-tag work-items: ' + e.message); }
+    }
+  } catch (e) { summary.warnings.push('orphan-sweep: ' + e.message); }
+
   // 8. Move (or purge) projects/<name>/ — preserves PR/work-item history by
   //    default so a re-add can pick up where it left off.
   const dataDir = shared.projectStateDir(project);