@yemi33/minions 0.1.2126 → 0.1.2128

package/dashboard/js/command-parser.js

@@ -33,8 +33,14 @@ function showToast(id, msg, ok, durationMs) {
   setTimeout(() => { el.classList.remove('success', 'error'); }, durationMs || (msg.includes('<a ') ? 15000 : 4000));
 }
 
-function detectWorkItemType(text) {
+function detectWorkItemType(text, hasPrRef) {
   const t = text.toLowerCase();
+  // When the caller doesn't pass an explicit PR-ref signal, derive it
+  // from the same text we're classifying. cmdParseInput passes the
+  // signal from RAW input (before `#projects` stripping) so canonical
+  // `#NNN` shorthand isn't lost; direct callers and tests get the
+  // ergonomic default of "scan the input you have."
+  const prRefPresent = (hasPrRef === undefined) ? _hasPrRef(text) : !!hasPrRef;
   const patterns = [
     { type: 'ask',      words: ['explain', 'why does', 'why is', 'what does', 'how do i', 'how do you', 'what\'s the', 'tell me', 'can you explain', 'walk me through'] },
     { type: 'explore',  words: ['explore', 'investigate', 'understand', 'analyze', 'audit', 'document', 'architecture', 'how does', 'what is', 'look into', 'research', 'survey', 'map out', 'codebase', 'make a note of', 'find out'] },
@@ -45,14 +51,51 @@ function detectWorkItemType(text) {
     { type: 'test',     words: ['test', 'write tests', 'add tests', 'unit test', 'e2e test', 'coverage', 'testing', 'build', 'run locally', 'localhost', 'start the', 'spin up', 'verify', 'check if it works'] },
   ];
   for (const { type, words } of patterns) {
-    if (words.some(w => t.includes(w))) return type;
+    if (words.some(w => t.includes(w))) {
+      // W-mq17dun7000f1150 — `type:fix` has a specific engine semantic
+      // ("responds to comments/builds on a tracked PR"). If the user's
+      // text matches the fix-verb list but doesn't reference any PR, the
+      // intent is a fresh repo-level bugfix that will open a NEW PR —
+      // i.e. `implement`, not `fix`. Without this gate, repo-level
+      // bugfix WIs hit the engine.js#discoverWork `pr_not_found` gate
+      // when shared.extractWorkItemPrRef finds a stale PR pointer in
+      // the description text and the WI is stuck indefinitely.
+      if (type === 'fix' && !prRefPresent) return 'implement';
+      return type;
+    }
   }
   return 'implement';
 }
 
+// _hasPrRef(rawText) -> bool. Recognises canonical PR pointers in free text:
+//   - `PR #N` / `PR-N` / `PR N`
+//   - `pull request N`
+//   - GitHub pull URLs: `github.com/<owner>/<repo>/pull/<N>`
+//   - Azure DevOps pull URLs: `.../pullrequest/<N>`
+//   - Canonical ids: `github:owner/repo#N`, `ado:org/proj/repo#N`
+// Does NOT match GitHub `issues/N` or bare `#N` — those are not PR pointers
+// (issues have their own URL shape and bare `#N` collides with hashtag /
+// project syntax in cmdParseInput).
+function _hasPrRef(rawText) {
+  if (!rawText || typeof rawText !== 'string') return false;
+  if (/\bpr[\s#-]+\d+\b/i.test(rawText)) return true;
+  if (/\bpull\s+request[\s#-]*\d+\b/i.test(rawText)) return true;
+  if (/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/i.test(rawText)) return true;
+  if (/\/pullrequest\/\d+/i.test(rawText)) return true;
+  if (/\bgithub:[\w.-]+\/[\w.-]+#\d+/i.test(rawText)) return true;
+  if (/\bado:[\w.-]+\/[\w.-]+\/[\w.-]+#\d+/i.test(rawText)) return true;
+  return false;
+}
+
 // Parse the unified input into structured intent
 function cmdParseInput(raw) {
   let text = raw.trim();
+  // W-mq17dun7000f1150 — capture the PR-ref signal on the RAW input before
+  // we strip `#projects` (which would eat `#NNN` PR shorthand). The signal
+  // is passed to detectWorkItemType so a naked "fix" verb without a PR
+  // pointer gets demoted to `implement` (the engine semantic for `fix`
+  // requires a tracked PR).
+  const hasPrRef = _hasPrRef(raw);
   const result = {
     intent: 'work-item', // 'work-item' | 'note' | 'plan'
     agents: [],           // assigned agent IDs
@@ -138,9 +181,9 @@ function cmdParseInput(raw) {
   result.description = lines.slice(1).join('\n').trim();
 
   // Auto-detect work type
-  result.type = detectWorkItemType(result.title + ' ' + result.description);
+  result.type = detectWorkItemType(result.title + ' ' + result.description, hasPrRef);
 
   return result;
 }
 
-window.MinionsCmdParser = { cmdUpdateAgentList, cmdUpdateProjectList, showToast, detectWorkItemType, cmdParseInput };
+window.MinionsCmdParser = { cmdUpdateAgentList, cmdUpdateProjectList, showToast, detectWorkItemType, cmdParseInput, _hasPrRef };

package/dashboard/js/settings.js

@@ -297,6 +297,7 @@ async function openSettings() {
       settingsField('Worktree Create Timeout', 'set-worktreeCreateTimeout', e.worktreeCreateTimeout || 300000, 'ms', 'Timeout for git worktree add (increase for large repos/Windows)') +
       settingsField('Worktree Create Retries', 'set-worktreeCreateRetries', e.worktreeCreateRetries || 1, '', 'Retry count for transient worktree add failures (0-3)') +
       settingsField('Worktree Root', 'set-worktreeRoot', e.worktreeRoot || '../worktrees', '', 'Relative or absolute path for git worktrees; on Windows prefer a short path like C:\\wt') +
+      settingsField('Assert-Clean Status Probe Timeout', 'set-assertCleanStatusTimeoutMs', e.assertCleanStatusTimeoutMs || 10000, 'ms', 'Timeout for the `git status --porcelain` preflight probe in assertCleanSharedWorktree. Raise this (e.g. 60000) on GVFS/Plastic-backed monorepos where sparse hydration runs longer than the 10s default. On timeout the engine quarantines the bad worktree and emits a RETRYABLE failure so the next dispatch starts fresh. Clamped 1000–120000ms.') +
     '</div>';
 
   const paneCopilot =
@@ -846,6 +847,7 @@ async function saveSettings() {
       worktreeCreateTimeout: document.getElementById('set-worktreeCreateTimeout').value,
       worktreeCreateRetries: document.getElementById('set-worktreeCreateRetries').value,
       worktreeRoot: document.getElementById('set-worktreeRoot').value,
+      assertCleanStatusTimeoutMs: document.getElementById('set-assertCleanStatusTimeoutMs').value,
       idleAlertMinutes: document.getElementById('set-idleAlertMinutes').value,
       shutdownTimeout: document.getElementById('set-shutdownTimeout').value,
       restartGracePeriod: document.getElementById('set-restartGracePeriod').value,

package/dashboard.js

@@ -3335,6 +3335,14 @@ function getWorkItemPrRef(input) {
   // description text — not just the canonical structured fields — and routes
   // the dispatch to the existing PR branch instead of a fresh `work/<wi-id>`
   // parallel branch (issue #2999 / W-mpx6i5kh000ac040).
+  //
+  // ASYMMETRY (W-mq18ec6h000p7b87): the engine's pr_not_found *gate* uses
+  // the strict `shared.extractStructuredWorkItemPrRef` — gate uses
+  // structured-only; stamp uses loose. Rationale: operators creating fix
+  // WIs via API often paste the PR URL in description prose and expect
+  // `targetPr` to get auto-stamped here (best-effort, reversible). The gate
+  // blocks dispatch and must require explicit operator intent (a structured
+  // field) before doing so.
   return shared.extractWorkItemPrRef(input);
 }
 
@@ -5486,6 +5494,20 @@ const server = http.createServer(async (req, res) => {
       // central WI silently land and loop. (W-mp631ux9000x6df0; reproduced by
       // W-mp629rn3000od581 — Rebecca's spawn looped 12+ times silently.)
       const normalizedType = routing.normalizeWorkType(body.type, WORK_TYPE.IMPLEMENT);
+      // plan-to-prd must carry a planFile — without it the agent has no plan to
+      // convert. engine.js #spawnAgent only populates `vars.plan_content` from
+      // the plan file when `item.planFile` is set (see engine.js ~line 6710);
+      // with no planFile that whole setup block is skipped, leaving the agent
+      // to produce an orphaned PRD with no source_plan linkage. Engine-internal
+      // chaining via `shared.queuePlanToPrd` always stamps planFile, so this
+      // guard only gates external callers hitting POST /api/work-items
+      // directly. (W-mq14txl5)
+      if (normalizedType === WORK_TYPE.PLAN_TO_PRD
+          && (!body.planFile || !String(body.planFile).trim())) {
+        return jsonReply(res, 400, {
+          error: 'planFile is required for type=plan-to-prd. Use POST /api/plan to create a new plan (the engine will auto-chain plan-to-prd) or POST /api/plans/execute for an existing .md draft.',
+        });
+      }
       if (WORKTREE_REQUIRING_TYPES.has(normalizedType)
           && PROJECTS.length !== 1
           && (!body.project || !String(body.project).trim())) {
@@ -5882,47 +5904,26 @@ const server = http.createServer(async (req, res) => {
       const requestedAgent = body.agent || body.agentId;
       const requestedTask = body.task || body.cancelTask;
       if (!requestedAgent && !requestedTask) return jsonReply(res, 400, { error: 'agent or task required' });
+
+      // Pre-read for response snapshot. Lockless — cleanDispatchEntries owns the actual mutation.
       const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
       const dispatch = safeJsonObj(dispatchPath);
-      const active = dispatch.active || [];
-      const cancelled = [];
-
-      for (const d of active) {
+      const active = Array.isArray(dispatch.active) ? dispatch.active : [];
+      const matchFn = (d) => {
         const matchAgent = requestedAgent && d.agent === requestedAgent;
         const matchTask = requestedTask && (d.task || '').toLowerCase().includes(String(requestedTask).toLowerCase());
-        if (!matchAgent && !matchTask) continue;
-
-        // Kill agent process
-        const statusPath = path.join(MINIONS_DIR, 'agents', d.agent, 'status.json');
-        try {
-          const status = safeJsonObj(statusPath);
-          if (status.pid) {
-            try {
-              const safePid = shared.validatePid(status.pid);
-              if (process.platform === 'win32') {
-                require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-              } else {
-                process.kill(safePid, 'SIGTERM');
-              }
-            } catch { /* process may be dead or invalid PID */ }
-          }
-          status.status = 'idle';
-          delete status.currentTask;
-          delete status.dispatched;
-          safeWrite(statusPath, status);
-        } catch (e) { console.error('agent cancel:', e.message); }
-
-        cancelled.push({ agent: d.agent, task: d.task });
-      }
-
-      // Remove cancelled from active dispatch
+        return Boolean(matchAgent || matchTask);
+      };
+      const cancelled = active.filter(matchFn).map(d => ({ agent: d.agent, task: d.task }));
+
+      // Route PID resolution + kill + dispatch removal through the canonical primitive.
+      // cleanDispatchEntries resolves the PID from engine/tmp/dispatch-<id>-*/pid-<id>.pid
+      // (see shared.findDispatchPidFile), kills outside the dispatch lock, and removes
+      // the entry via mutateDispatch (SQL + JSON mirror in one atomic write).
+      // The defunct per-agent status sidecar reads/writes that used to live here are gone
+      // (engine/queries.js documents that file no longer exists).
       if (cancelled.length > 0) {
-        const cancelledIds = new Set(cancelled.map(c => c.agent));
-        mutateJsonFileLocked(dispatchPath, (dp) => {
-          dp.active = Array.isArray(dp.active) ? dp.active : [];
-          dp.active = dp.active.filter(d => !cancelledIds.has(d.agent));
-          return dp;
-        }, { defaultValue: { pending: [], active: [], completed: [] } });
+        cleanDispatchEntries(matchFn);
       }
 
       return jsonReply(res, 200, { ok: true, cancelled });
@@ -6353,7 +6354,7 @@ const server = http.createServer(async (req, res) => {
     // safeJsonArr is sync but reads a single small file — leave as is.
     const centralWi = safeJsonArr(path.join(MINIONS_DIR, 'work-items.json'));
     const completedPrdFiles = new Set(
-      centralWi.filter(w => w.type === 'plan-to-prd' && DONE_STATUSES.has(w.status) && w.planFile)
+      centralWi.filter(w => w.type === WORK_TYPE.PLAN_TO_PRD && DONE_STATUSES.has(w.status) && w.planFile)
         .map(w => w.planFile)
     );
     const plans = [];
@@ -6604,7 +6605,7 @@ const server = http.createServer(async (req, res) => {
 
       // Propagate pause to materialized work items across all projects:
       // kill any active agent process and reset non-completed items to paused.
-      // Pattern: collect-then-release-then-act to avoid nested locks and long lock holds.
+      // Pattern: lockless reads → cleanDispatchEntries (atomic kill + remove) → mutateWorkItems.
       const wiPaths = [path.join(MINIONS_DIR, 'work-items.json')];
       for (const proj of PROJECTS) {
         wiPaths.push(shared.projectWorkItemsPath(proj));
@@ -6624,50 +6625,24 @@ const server = http.createServer(async (req, res) => {
         } catch { /* file may not exist */ }
       }
 
-      // Step 2: Read dispatch.json (read-only, no lock) to collect kill targets.
-      const killTargets = []; // { agent, pid, statusPath }
-      const dispatch = safeJsonObj(dispatchPath);
-      const activeEntries = Array.isArray(dispatch.active) ? dispatch.active : [];
-      for (const d of activeEntries) {
-        const itemId = d.meta?.item?.id;
-        const matchesById = itemId && dispatchedItemIds.has(itemId);
-        const matchesByKey = d.meta?.dispatchKey && [...dispatchedItemIds].some(id => d.meta.dispatchKey.includes(id));
-        if (matchesById || matchesByKey) {
-          const statusPath = path.join(MINIONS_DIR, 'agents', d.agent, 'status.json');
-          try {
-            const agentStatus = safeJsonObj(statusPath);
-            killTargets.push({ agent: d.agent, pid: agentStatus.pid || null, statusPath });
-          } catch { killTargets.push({ agent: d.agent, pid: null, statusPath }); }
-        }
-      }
-
-      // Step 3: Kill agent processes OUTSIDE any lock (expensive, may take seconds).
-      const killedAgents = new Set();
-      for (const target of killTargets) {
-        if (target.pid) {
-          try {
-            const safePid = shared.validatePid(target.pid);
-            if (process.platform === 'win32') {
-              require('child_process').execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-            } else {
-              process.kill(safePid, 'SIGTERM');
-            }
-          } catch { /* process may be dead or invalid PID */ }
-        }
-        // Reset agent status file (no lock needed — agent-specific file).
-        try {
-          const agentStatus = safeJsonObj(target.statusPath);
-          agentStatus.status = 'idle';
-          delete agentStatus.currentTask;
-          delete agentStatus.dispatched;
-          safeWrite(target.statusPath, agentStatus);
-        } catch (e) { console.error('agent reset:', e.message); }
-        killedAgents.add(target.agent);
+      // Step 2: Route PID resolution + kill + dispatch removal through the canonical primitive.
+      // cleanDispatchEntries resolves PIDs from engine/tmp/dispatch-<id>-*/pid-<id>.pid
+      // (see shared.findDispatchPidFile), kills outside the dispatch lock, and removes the
+      // entries via mutateDispatch (SQL + JSON mirror in one atomic write).
+      // The defunct per-agent status sidecar reads/writes that used to live here are gone
+      // (engine/queries.js documents that file no longer exists).
+      if (dispatchedItemIds.size > 0) {
+        const matchFn = (d) => {
+          const itemId = d.meta?.item?.id;
+          if (itemId && dispatchedItemIds.has(itemId)) return true;
+          if (d.meta?.dispatchKey && [...dispatchedItemIds].some(id => d.meta.dispatchKey.includes(id))) return true;
+          return false;
+        };
+        cleanDispatchEntries(matchFn);
       }
 
-      // Step 4: Mutate work-items.json per path — pause items (each lock held briefly, no nesting).
+      // Step 3: Mutate work-items.json per path — pause items (each lock held briefly, no nesting).
       let reset = 0;
-      const resetItemIds = new Set();
       for (const wiPath of wiPaths) {
         try {
           mutateWorkItems(wiPath, items => {
@@ -6682,24 +6657,11 @@ const server = http.createServer(async (req, res) => {
               delete w.dispatched_to;
               delete w.failReason;
               delete w.failedAt;
-              if (w.id) resetItemIds.add(w.id);
             }
           });
         } catch (e) { console.error('reset work items:', e.message); }
       }
 
-      // Step 5: Re-acquire dispatch lock to clean up active entries (brief lock, no nesting).
-      mutateJsonFileLocked(dispatchPath, (dispatchData) => {
-        dispatchData.active = Array.isArray(dispatchData.active) ? dispatchData.active : [];
-        dispatchData.active = dispatchData.active.filter(d => {
-          const itemId = d.meta?.item?.id;
-          if (itemId && resetItemIds.has(itemId)) return false;
-          if (killedAgents.has(d.agent)) return false;
-          return true;
-        });
-        return dispatchData;
-      }, { defaultValue: { pending: [], active: [], completed: [] } });
-
       invalidateStatusCache();
       invalidatePlansCache();
       return jsonReply(res, 200, { ok: true, status: 'paused', resetWorkItems: reset });
@@ -6873,7 +6835,7 @@ const server = http.createServer(async (req, res) => {
           const centralPath = path.join(MINIONS_DIR, 'work-items.json');
           mutateWorkItems(centralPath, items => {
             for (const w of items) {
-              if (w.type === 'plan-to-prd' && DONE_STATUSES.has(w.status) && w.planFile === prdSourcePlan) {
+              if (w.type === WORK_TYPE.PLAN_TO_PRD && DONE_STATUSES.has(w.status) && w.planFile === prdSourcePlan) {
                 w.status = WI_STATUS.CANCELLED;
                 w._cancelledBy = 'prd-deleted';
               }
@@ -7020,7 +6982,7 @@ const server = http.createServer(async (req, res) => {
       mutateWorkItems(wiPath, items => {
         items.push({
           id, title: 'Revise plan: ' + (plan.plan_summary || body.file),
-          type: 'plan-to-prd', priority: 'high',
+          type: WORK_TYPE.PLAN_TO_PRD, priority: 'high',
           description: 'Revision requested on plan file: ' + (body.file.endsWith('.json') ? 'prd/' : 'plans/') + body.file + '\n\nFeedback:\n' + body.feedback + '\n\nRevise the plan to address this feedback. Read the existing plan, apply the feedback, and overwrite the file with the updated version. Set status back to "awaiting-approval".',
           status: WI_STATUS.PENDING, created: new Date().toISOString(), createdBy: 'dashboard:revision',
           project: plan.project || '',
@@ -9223,6 +9185,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           tickInterval: [10000], maxConcurrent: [1, 50], inboxConsolidateThreshold: [1],
           agentTimeout: [60000], maxTurns: [5, 500], heartbeatTimeout: [60000],
           worktreeCreateTimeout: [60000], worktreeCreateRetries: [0, 3],
+          // W-mq1habhf: status-probe deadline inside assertCleanSharedWorktree.
+          // 1s floor (anything shorter races with git startup on cold caches);
+          // 2min ceiling (covers even a GVFS-backed sparse hydration without
+          // letting a config typo wedge dispatch for an hour).
+          assertCleanStatusTimeoutMs: [1000, 120000],
           idleAlertMinutes: [1], shutdownTimeout: [30000], restartGracePeriod: [60000],
           meetingRoundTimeout: [60000],
           // W-mq066js7000fff1f-c (Gap B/C): steering safety-net knobs.

package/engine/ado-git-auth.js

@@ -180,8 +180,15 @@ function getAdoGitExtraArgs(project, opts = {}) {
     return _composeAdoArgs(_buildHeaderArgs(token, _resolveScopeUrls(project)));
   } catch (e) {
     _backoffUntil = now + ACQUIRE_BACKOFF_MS;
-    const firstLine = String(e && e.message || e).split('\n')[0];
-    log('warn', `ado-git-auth: token acquire failed (${firstLine}); backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
+    // #3045 — log the FULL exec error (redacted) instead of just the first
+    // line. child_process.exec rejections start with "Command failed: <cmd>"
+    // and put the real stderr ("TF400813 unknown user", "HTTP 401", etc.)
+    // on the SECOND line; .split('\n')[0] threw that away and made every
+    // ADO auth failure look like an indistinguishable wall of "Command
+    // failed: ...". _redactBearer strips any bearer header echoed back by
+    // the failing git command so the token never reaches engine logs.
+    const fullMsg = _redactBearer(String(e && e.message || e));
+    log('warn', `ado-git-auth: token acquire failed (${fullMsg}); backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
     return [...CREDENTIAL_DISABLE_ARGS];
   }
 }
@@ -272,6 +279,7 @@ module.exports = {
   isAdoAuthFailure,
   runAdoGit,
   isAdoProject,
+  redactBearer: _redactBearer,
   _setTokenForTest,
   _clearTokenCache,
   _isBackedOff,

package/engine/ado-status.js

@@ -23,7 +23,7 @@
 
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeJsonArr, projectPrPath, getProjects } = shared;
+const { safeJson, safeJsonArr, projectPrPath, getProjects, MINIONS_DIR } = shared;
 
 // ── Arg parsing ──────────────────────────────────────────────────────────────
 
@@ -87,7 +87,7 @@ function findInCache(projects) {
 
 async function main() {
   // Use safeJson directly — pulling in queries.js would load all cached state unnecessarily
-  const config = safeJson(path.join(__dirname, '..', 'config.json')) || {};
+  const config = safeJson(path.join(MINIONS_DIR, 'config.json')) || {};
   const allProjects = getProjects(config).filter(p => p.repoHost === 'ado' || !p.repoHost);
   const projects = projectName
     ? allProjects.filter(p => p.name === projectName)

package/engine/cleanup.js

@@ -664,7 +664,7 @@ async function runCleanup(config, verbose = false) {
     const prs = safeJson(projectPrPath(project)) || [];
     const mergedBranches = new Set();
     for (const pr of prs) {
-      if (pr.status === shared.PR_STATUS.MERGED || pr.status === shared.PR_STATUS.ABANDONED || pr.status === shared.PLAN_STATUS.COMPLETED) {
+      if (pr.status === shared.PR_STATUS.MERGED || pr.status === shared.PR_STATUS.ABANDONED) {
         if (pr.branch) mergedBranches.add(pr.branch);
       }
     }
@@ -877,7 +877,7 @@ async function runCleanup(config, verbose = false) {
       const freshMergedBranches = new Set();
       const freshMergedPrByBranch = new Map();
       for (const pr of freshPrs) {
-        if (pr.status === shared.PR_STATUS.MERGED || pr.status === shared.PR_STATUS.ABANDONED || pr.status === shared.PLAN_STATUS.COMPLETED) {
+        if (pr.status === shared.PR_STATUS.MERGED || pr.status === shared.PR_STATUS.ABANDONED) {
           if (pr.branch) freshMergedBranches.add(pr.branch);
         }
         if (pr.status === shared.PR_STATUS.MERGED && pr.branch) {

package/engine/dispatch.js

@@ -986,7 +986,7 @@ function cleanDispatchEntries(matchFn) {
       const safePid = shared.validatePid(pid);
       if (process.platform === 'win32') {
         const { execFileSync } = require('child_process');
-        execFileSync('taskkill', ['/PID', String(safePid), '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
+        execFileSync('taskkill', ['/PID', String(safePid), '/F', '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
       } else {
         process.kill(safePid, 'SIGTERM');
       }

package/engine/meeting.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT } = shared;
+const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT, MEETING_STATUS } = shared;
 const queries = require('./queries');
 const { getDispatch, getConfig } = queries;
 const { renderPlaybook } = require('./playbook');
@@ -829,7 +829,7 @@ function advanceMeetingRound(meetingId) {
   // already terminal. The authoritative status check still runs INSIDE the
   // lock below.
   const existing = getMeeting(meetingId);
-  if (!existing || existing.status === 'completed' || existing.status === 'archived') return null;
+  if (!existing || existing.status === MEETING_STATUS.COMPLETED || existing.status === MEETING_STATUS.ARCHIVED) return null;
 
   // CRITICAL: kill BEFORE acquiring the meeting lock. _killMeetingDispatches
   // takes the dispatch.json lock and shells out to kill processes — never
@@ -838,7 +838,7 @@ function advanceMeetingRound(meetingId) {
   _killMeetingDispatches(meetingId);
 
   return mutateMeeting(meetingId, (meeting) => {
-    if (!meeting || meeting.status === 'completed' || meeting.status === 'archived') return null;
+    if (!meeting || meeting.status === MEETING_STATUS.COMPLETED || meeting.status === MEETING_STATUS.ARCHIVED) return null;
     if (meeting.status === 'investigating') { meeting.status = 'debating'; meeting.round = 2; }
     else if (meeting.status === 'debating') { meeting.status = 'concluding'; meeting.round = 3; }
     else if (meeting.status === 'concluding') { meeting.status = 'completed'; meeting.completedAt = ts(); }
@@ -857,7 +857,7 @@ function endMeeting(meetingId) {
 
   return mutateMeeting(meetingId, (meeting) => {
     if (!meeting) return null;
-    meeting.status = 'completed';
+    meeting.status = MEETING_STATUS.COMPLETED;
     meeting.completedAt = ts();
     return meeting;
   });
@@ -866,7 +866,7 @@ function endMeeting(meetingId) {
 function archiveMeeting(id) {
   return mutateMeeting(id, (meeting) => {
     if (!meeting) return null;
-    meeting.status = 'archived';
+    meeting.status = MEETING_STATUS.ARCHIVED;
     meeting.archivedAt = ts();
     return meeting;
   });

package/engine/queries.js

@@ -1717,9 +1717,10 @@ function resetPrdInfoCache() {
 }
 
 // ── Project git status (current branch + dirty/detached) ──────────────────
-// Cached per resolved localPath with a 5-minute TTL. `getProjectGitStatus` is
-// synchronous (returns the cached value or a pending placeholder) and NEVER
-// blocks the event loop — the actual git probes run asynchronously via
+// Cached per resolved localPath with a 15-second TTL (see
+// `PROJECT_GIT_STATUS_TTL` below). `getProjectGitStatus` is synchronous
+// (returns the cached value or a pending placeholder) and NEVER blocks the
+// event loop — the actual git probes run asynchronously via
 // child_process.execFile and write back into the cache when they settle. This
 // is critical for /api/status responsiveness: under the previous synchronous
 // implementation, four projects × three git invocations was ~12 sync shell-outs
@@ -1730,10 +1731,15 @@ function resetPrdInfoCache() {
 // stderr to suppress the `fatal: not a git repository` noise on non-git project
 // paths — same requirement enforced for install/boot paths in
 // test/unit/runtime-fleet-helpers.test.js:465.
-// Single map keyed by normalized localPath. Each entry holds `{ts, value, promise}`:
-//   ts:      last-settled timestamp (Date.now()), or 0 if never settled
-//   value:   last-settled status object (or PROJECT_GIT_STATUS_PENDING placeholder)
-//   promise: in-flight refresh Promise, or null when idle
+// Single map keyed by normalized localPath. Each entry holds
+// `{ts, value, promise, promiseStartedAt, refMtimes}`:
+//   ts:               last-settled timestamp (Date.now()), or 0 if never settled
+//   value:            last-settled status object (or PROJECT_GIT_STATUS_PENDING placeholder)
+//   promise:          in-flight refresh Promise, or null when idle
+//   promiseStartedAt: when the in-flight Promise started (Date.now()), 0 when idle
+//                     — used by the stale-pending guard to detect wedged probes
+//                       (W-mq19314k00101fc7)
+//   refMtimes:        snapshot of HEAD/FETCH_HEAD/refs/remotes mtimes at probe start
 // Folding state + in-flight into one map keeps reads/writes atomic and removes
 // the second-Map sync hazard.
 const _projectGitStatusCache = new Map();
@@ -1752,21 +1758,76 @@ const PROJECT_GIT_STATUS_PENDING = Object.freeze({ gitBranch: null, gitDetached:
 const PROJECT_GIT_STATUS_MISSING = Object.freeze({ gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'missing', remoteDefaultBranch: null, ahead: null, behind: null });
 const PROJECT_GIT_STATUS_NON_GIT = Object.freeze({ gitBranch: null, gitDetached: false, gitDirty: false, gitState: 'non-git', remoteDefaultBranch: null, ahead: null, behind: null });
 
+// Probe budget constants (W-mq19314k00101fc7). `PROBE_TIMEOUT_MS` is the
+// per-invocation execFile timeout; `PROBE_WATCHDOG_MS` is an OUTER
+// belt-and-suspenders rejection that always fires regardless of whether
+// execFile honored its `timeout` option. Production observation
+// (2026-06-05): on Windows, execFile's timeout can silently no-op when
+// Defender/AV stalls the child's I/O, leaving the in-flight Promise
+// pending indefinitely; every subsequent caller then got the dead Promise
+// back from the single-flight guard in `_scheduleProjectGitStatusRefresh`
+// and the cache wedged for minutes. The watchdog converts that hope into
+// a hard invariant: _gitExec always settles within PROBE_WATCHDOG_MS.
+const PROBE_TIMEOUT_MS = 10000;
+const PROBE_WATCHDOG_MS = 15000;
+let _probeTimeoutOverride = null;
+let _probeWatchdogOverride = null;
+// Test seam: shrink the watchdog budget so wedge regression tests can
+// run in <1s. Returns a restore function that resets to the production
+// default.
+function _setProbeWatchdogForTest({ timeoutMs, watchdogMs } = {}) {
+  const prevTimeout = _probeTimeoutOverride;
+  const prevWatchdog = _probeWatchdogOverride;
+  if (typeof timeoutMs === 'number') _probeTimeoutOverride = timeoutMs;
+  if (typeof watchdogMs === 'number') _probeWatchdogOverride = watchdogMs;
+  return () => { _probeTimeoutOverride = prevTimeout; _probeWatchdogOverride = prevWatchdog; };
+}
+function _getProbeTimeoutsForTest() {
+  return {
+    timeoutMs: _probeTimeoutOverride != null ? _probeTimeoutOverride : PROBE_TIMEOUT_MS,
+    watchdogMs: _probeWatchdogOverride != null ? _probeWatchdogOverride : PROBE_WATCHDOG_MS,
+  };
+}
+
 // Async git invocation. Promise-returning so getProjectGitStatus can fire
 // background refreshes without blocking the event loop. Pipes stderr to keep
 // `fatal: not a git repository` from leaking to the dashboard console.
+//
+// W-mq19314k00101fc7 — wraps execFile in an outer watchdog Promise.race so
+// the returned Promise ALWAYS settles within PROBE_WATCHDOG_MS, even if
+// execFile's own `timeout` option silently no-ops (the Windows production
+// failure mode). On watchdog fire, we SIGKILL the child explicitly so an
+// orphaned git.exe doesn't linger.
 function _gitExec(localPath, args) {
   const { execFile } = require('child_process');
+  const timeoutMs = _probeTimeoutOverride != null ? _probeTimeoutOverride : PROBE_TIMEOUT_MS;
+  const watchdogMs = _probeWatchdogOverride != null ? _probeWatchdogOverride : PROBE_WATCHDOG_MS;
   return new Promise((resolve, reject) => {
-    execFile('git', ['-C', localPath, ...args], {
+    let settled = false;
+    let watchdogTimer = null;
+    const child = execFile('git', ['-C', localPath, ...args], {
       encoding: 'utf8',
-      timeout: 10000,
+      timeout: timeoutMs,
       windowsHide: true,
       stdio: ['pipe', 'pipe', 'pipe'],
     }, (err, stdout) => {
+      if (settled) return;
+      settled = true;
+      if (watchdogTimer) clearTimeout(watchdogTimer);
       if (err) reject(err);
       else resolve(stdout);
     });
+    watchdogTimer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      // Belt-and-suspenders: explicitly kill the stuck child so it can't
+      // linger as an orphaned git.exe. SIGKILL on Unix, forced termination
+      // on Windows (Node maps both to TerminateProcess via libuv).
+      try { if (child && typeof child.kill === 'function') child.kill('SIGKILL'); }
+      catch { /* child may already be dead */ }
+      reject(new Error(`git probe watchdog: \`git ${args.join(' ')}\` did not settle within ${watchdogMs}ms`));
+    }, watchdogMs);
+    if (watchdogTimer && typeof watchdogTimer.unref === 'function') watchdogTimer.unref();
   });
 }
 
@@ -1874,8 +1935,26 @@ function _projectGitStatusEqual(a, b) {
 
 function _scheduleProjectGitStatusRefresh(localPath, key, configuredMainBranch) {
   const existing = _projectGitStatusCache.get(key);
-  if (existing && existing.promise) return existing.promise;
-  const entry = existing || { ts: 0, value: PROJECT_GIT_STATUS_PENDING, promise: null, refMtimes: null };
+  // Stale-pending safety net (W-mq19314k00101fc7 — option b). The _gitExec
+  // watchdog (option a) is the primary guarantee that an in-flight probe
+  // ALWAYS settles within PROBE_WATCHDOG_MS. This second-tier check is a
+  // belt-and-suspenders for any future async path that might wedge BEFORE
+  // _gitExec is reached (e.g. fs.existsSync hanging on a disconnected
+  // network drive, or a refactor introducing a pre-gitExec await). If
+  // `entry.promise` is older than 2× the watchdog budget, treat it as
+  // dead and schedule a fresh probe rather than serving the stuck Promise
+  // forever.
+  if (existing && existing.promise) {
+    const watchdogMs = _probeWatchdogOverride != null ? _probeWatchdogOverride : PROBE_WATCHDOG_MS;
+    const startedAt = existing.promiseStartedAt || 0;
+    const age = startedAt ? (Date.now() - startedAt) : 0;
+    if (!startedAt || age < (2 * watchdogMs)) return existing.promise;
+    // Past 2× budget — wedged. Fall through and schedule a fresh probe;
+    // the wedged Promise is intentionally orphaned (its later resolution,
+    // if any, can no longer race the new probe because we overwrite
+    // entry.promise + entry.promiseStartedAt below).
+  }
+  const entry = existing || { ts: 0, value: PROJECT_GIT_STATUS_PENDING, promise: null, promiseStartedAt: 0, refMtimes: null };
   const prevValue = entry.value;
   // Snapshot ref mtimes BEFORE the probe so the next call compares against
   // an exact baseline rather than a Date.now() timestamp. On Windows
@@ -1884,11 +1963,13 @@ function _scheduleProjectGitStatusRefresh(localPath, key, configuredMainBranch)
   // even when nothing actually changed.
   const probeStartTs = Date.now();
   const probeStartRefMtimes = _snapshotProjectGitRefMtimes(localPath, configuredMainBranch);
+  entry.promiseStartedAt = probeStartTs;
   entry.promise = _probeProjectGitStatus(localPath, configuredMainBranch).then(value => {
     entry.ts = probeStartTs;
     entry.refMtimes = probeStartRefMtimes;
     entry.value = value;
     entry.promise = null;
+    entry.promiseStartedAt = 0;
     if (_onProjectGitStatusChanged && !_projectGitStatusEqual(prevValue, value)) {
       try { _onProjectGitStatusChanged(key, value, prevValue); }
       catch { /* hook must never break the probe */ }
@@ -1896,6 +1977,7 @@ function _scheduleProjectGitStatusRefresh(localPath, key, configuredMainBranch)
     return value;
   }, () => {
     entry.promise = null;
+    entry.promiseStartedAt = 0;
     return null;
   });
   _projectGitStatusCache.set(key, entry);
@@ -2109,6 +2191,16 @@ function resetProjectGitStatusCache() {
   _projectGitStatusCache.clear();
 }
 
+// Test seam (W-mq19314k00101fc7): expose the internal cache Map so the
+// wedge regression test can inject a synthetic "stuck Promise + stale
+// promiseStartedAt" entry that mirrors the production failure mode without
+// having to wait out a real watchdog. Production callers must never read
+// or mutate this Map directly — always go through getProjectGitStatus /
+// warmProjectGitStatus.
+function _getProjectGitStatusCacheForTest() {
+  return _projectGitStatusCache;
+}
+
 /**
  * Files whose mtime must trigger a dashboard `_fastState` rebuild
  * (W-mpftp7na000td0f4). Single source of truth for the dashboard's
@@ -2378,6 +2470,9 @@ module.exports = {
   warmProjectGitStatus,
   _awaitPendingProjectGitStatusProbes,
   _setOnProjectGitStatusChanged,
+  _setProbeWatchdogForTest,
+  _getProbeTimeoutsForTest,
+  _getProjectGitStatusCacheForTest,
   // W-mpftp7na000td0f4 — engine→dashboard cache-invalidation registry
   getStatusFastStateMtimePaths,
   getStatusSlowStateMtimePaths,

package/engine/shared.js

@@ -2218,6 +2218,16 @@ const ENGINE_DEFAULTS = {
   worktreeCreateRetries: 1, // retry once on transient timeout/lock races
   worktreeRoot: '../worktrees',
   worktreeCountCacheTtl: 30000, // 30s — TTL for cached _countWorktrees() result in dashboard
+  // W-mq1habhf: timeout (ms) for the `git status --porcelain` probe inside
+  // engine.js assertCleanSharedWorktree. The default 10s is fine for ordinary
+  // repos but too tight for GVFS/Plastic-backed monorepos where the first
+  // status against a freshly-recreated worktree blocks on sparse hydration.
+  // When the probe times out the engine now quarantines the bad worktree
+  // (status-failed branch) and reports a RETRYABLE failure so the next
+  // dispatch starts on a fresh worktree. Operators on large repos should
+  // raise this knob (e.g. 60000) before tuning anything else. Clamped to
+  // [1000, 120000] in dashboard.js POST /api/settings.
+  assertCleanStatusTimeoutMs: 10000,
   workItemCreateDedupWindowMs: 15 * 60 * 1000, // 15min — collapse duplicate CC/API create races
   idleAlertMinutes: 15,
   fanOutTimeout: null, // falls back to agentTimeout
@@ -3428,7 +3438,7 @@ function queuePlanToPrd({ planFile, prdFile, title, description, project, create
   let item = null;
   mutateJsonFileLocked(centralWiPath, items => {
     if (!Array.isArray(items)) items = [];
-    const existing = items.find(w => w.type === 'plan-to-prd' && w.planFile === planFile && (w.status === 'pending' || w.status === 'dispatched'));
+    const existing = items.find(w => w.type === WORK_TYPE.PLAN_TO_PRD && w.planFile === planFile && (w.status === 'pending' || w.status === 'dispatched'));
     if (existing) {
       id = existing.id;
       item = existing;
@@ -3437,7 +3447,7 @@ function queuePlanToPrd({ planFile, prdFile, title, description, project, create
     const newItem = {
       id: 'W-' + uid(),
       title,
-      type: 'plan-to-prd',
+      type: WORK_TYPE.PLAN_TO_PRD,
       priority: 'high',
       description,
       status: 'pending',
@@ -5021,7 +5031,40 @@ function extractPrRefFromText(value) {
   return numberMatch ? numberMatch[1] : null;
 }
 
-function extractWorkItemPrRef(item) {
+// Cap for the description-text fallback scan in `extractWorkItemPrRef`.
+// Operators pasting a PR pointer put it at the TOP of the description;
+// long technical descriptions (CI failure reports, blast-radius examples,
+// 'upstream commit' references) mention OTHER PRs as context deeper in the
+// body — those mentions must not become the work-item's PR target.
+// See W-mq17dukn000ef114 (narrowing of W-mpx6i5kh000ac040 / issue #2999).
+const DESCRIPTION_PR_SCAN_MAX = 500;
+
+function _descriptionPrScanSlice(description) {
+  const text = String(description || '');
+  if (!text) return '';
+  // First paragraph boundary OR first DESCRIPTION_PR_SCAN_MAX chars,
+  // whichever is shorter. Paragraph split is blank-line (allowing trailing
+  // whitespace on the blank line).
+  const firstParagraph = text.split(/\n\s*\n/, 1)[0];
+  return firstParagraph.slice(0, DESCRIPTION_PR_SCAN_MAX);
+}
+
+// Structured-only PR-ref extraction (W-mq18ec6h000p7b87). Walks ONLY the
+// canonical structured sources — targetPr / pr / pr_id / prId / sourcePr /
+// pullRequest / prUrl / prNumber, references[*].url, meta.pr_followup
+// .parent_pr_url. Does NOT scan free-form description/title text. This is
+// the helper the engine's `pr_not_found` dispatch gate should call: it must
+// require explicit operator intent (a structured PR pointer) before blocking
+// dispatch, otherwise commentary like "see PR #3015 for context" in a
+// description trips the gate and a fresh refactor item with no real PR
+// target gets stuck in `_pendingReason: 'pr_not_found'` forever.
+//
+// Loose-form callers (branch derivation, prompt PR context, dashboard's
+// create-time stamp) should keep using `extractWorkItemPrRef` below — they
+// downgrade gracefully when no PR record matches the loose ref, and the
+// stamp path in particular preserves the operator UX of pasting a PR URL
+// into the description and getting `targetPr` auto-stamped.
+function extractStructuredWorkItemPrRef(item) {
   if (!item || typeof item !== 'object') return null;
   const structured = item.targetPr
     || item.pr
@@ -5032,8 +5075,6 @@ function extractWorkItemPrRef(item) {
     || item.prUrl
     || item.prNumber;
   if (structured) return structured;
-  // references[*].url — manual /api/work-items callers often supply the PR
-  // pointer here when no structured prId/targetPr is known up front.
   if (Array.isArray(item.references)) {
     for (const ref of item.references) {
       const url = ref && typeof ref === 'object' ? ref.url : null;
@@ -5041,14 +5082,26 @@ function extractWorkItemPrRef(item) {
       if (fromUrl) return fromUrl;
     }
   }
-  // meta.pr_followup.parent_pr_url — set by playbooks/templates/followup-dispatch.md.
   const followupUrl = item?.meta?.pr_followup?.parent_pr_url;
   if (followupUrl) {
     const fromFollowup = extractPrRefFromText(followupUrl);
     if (fromFollowup) return fromFollowup;
   }
-  // Last resort: scan description + title for a PR URL / canonical id.
-  const fromDescription = extractPrRefFromText(item.description);
+  return null;
+}
+
+function extractWorkItemPrRef(item) {
+  if (!item || typeof item !== 'object') return null;
+  const fromStructured = extractStructuredWorkItemPrRef(item);
+  if (fromStructured) return fromStructured;
+  // Last resort: scan the FIRST PARAGRAPH of description (capped at
+  // DESCRIPTION_PR_SCAN_MAX chars) + title for a PR URL / canonical id.
+  // The narrow slice prevents long `type: fix` descriptions that quote other
+  // PRs as context from false-positiving the fix WI onto the wrong PR
+  // (W-mq17dukn000ef114). This branch is intentionally separate from
+  // extractStructuredWorkItemPrRef so the dispatch gate can require
+  // structured-only intent (W-mq18ec6h000p7b87).
+  const fromDescription = extractPrRefFromText(_descriptionPrScanSlice(item.description));
   if (fromDescription) return fromDescription;
   return extractPrRefFromText(item.title) || null;
 }
@@ -6446,6 +6499,7 @@ module.exports = {
   parsePrUrl, // exported for testing
   extractPrRefFromText,
   extractWorkItemPrRef,
+  extractStructuredWorkItemPrRef,
   getProjectPrScope,
   getPrNumber,
   getPrDisplayId,

package/engine.js

@@ -744,18 +744,27 @@ async function _fetchWithTransientRetry(args, opts, label) {
     return true;
   } catch (e) {
     if (!_isTransientGitNetworkError(e)) {
-      log('warn', `git fetch ${label}: ${String(e.message || e).split('\n')[0]}`);
+      // #3045 — log the FULL exec error message (redacted), not just the first
+      // line. child_process.exec rejections format as "Command failed: <cmd>"
+      // on line 1 and the real stderr ("TF400813 unknown user", "HTTP 401",
+      // etc.) on line 2; pre-fix we kept only line 1 via a first-line split,
+      // throwing away the actionable stderr and making every swallowed fetch
+      // warning look identical, hiding ADO auth failures for the entire #3045
+      // incident. _redactBearer keeps any bearer header echoed in the failing
+      // git command out of engine logs.
+      log('warn', `git fetch ${label}: ${adoGitAuth.redactBearer(String(e.message || e))}`);
       return false; // swallow non-transient — caller falls back to local ref
     }
-    const firstMsg = String(e.message || e).split('\n')[0];
-    log('warn', `git fetch ${label}: transient (${firstMsg}) — retrying once after 1.5s`);
+    const transientMsg = adoGitAuth.redactBearer(String(e.message || e));
+    log('warn', `git fetch ${label}: transient (${transientMsg}) — retrying once after 1.5s`);
     await new Promise(r => setTimeout(r, 1500));
     try {
       await _attempt();
       log('info', `git fetch ${label}: succeeded on retry`);
       return true;
     } catch (e2) {
-      log('warn', `git fetch ${label}: retry also failed (${String(e2.message || e2).split('\n')[0]}) — falling back to local ref`);
+      const retryMsg = adoGitAuth.redactBearer(String(e2.message || e2));
+      log('warn', `git fetch ${label}: retry also failed (${retryMsg}) — falling back to local ref`);
       return false;
     }
   }
@@ -909,6 +918,14 @@ async function pruneStaleWorktreeForBranch(rootDir, branchName, gitOpts) {
 //      WORKTREE_DIVERGENT reason and retry semantics.
 async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, dispatchId, gitOpts = {}, opts = {}) {
   const quarantineOnUnsafe = !!opts.quarantineOnUnsafe;
+  // W-mq1habhf: status probe timeout is now configurable so large/GVFS repos
+  // can raise it past the 10s default. Clamped to [1000, 120000] to mirror
+  // the dashboard validator; mis-set values fall back to the default.
+  const statusTimeoutMs = (() => {
+    const raw = Number(opts.statusTimeoutMs);
+    if (!Number.isFinite(raw) || raw <= 0) return ENGINE_DEFAULTS.assertCleanStatusTimeoutMs;
+    return Math.max(1000, Math.min(120000, raw));
+  })();
   const result = {
     clean: false, healed: false, reason: null, dirtyFiles: [],
     ahead: 0, behind: 0,
@@ -917,11 +934,56 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
   // 1. Status probe (filesystem)
   let statusOut = '';
   try {
-    const r = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    const r = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
     statusOut = (r || '').toString().trim();
   } catch (e) {
+    // W-mq1habhf: previously this bailed out with the bad worktree intact,
+    // and every same-WI retry hit the identical timeout (the .git/worktrees/
+    // metadata + branch ref linger from the prior aborted dispatch, so
+    // reuse-by-branch keeps re-finding the same broken tree). When the
+    // caller opts into quarantineOnUnsafe and no other dispatch claims the
+    // branch, we now quarantine the worktree out of the way (rename →
+    // worktree prune → reset refs/heads/<branch>) so the next dispatch
+    // creates a fresh worktree. The caller emits a RETRYABLE failure
+    // (distinct from has-unpushed-commits/no-upstream which preserve
+    // potentially-unpushed work and stay non-retryable).
     result.reason = 'status-failed';
     result.error = e.message;
+    if (quarantineOnUnsafe) {
+      const sanitizedB = sanitizeBranch(branchName);
+      let otherActive = false;
+      try {
+        mutateDispatch((dp) => {
+          otherActive = (dp.active || []).some(d => {
+            if (d.id === dispatchId) return false;
+            const dBranch = d.meta?.branch ? sanitizeBranch(d.meta.branch) : '';
+            return dBranch === sanitizedB;
+          });
+          return dp;
+        });
+      } catch (errOwn) {
+        log('warn', `assertCleanSharedWorktree: dispatch read failed during status-failed (${errOwn.message}) — skipping quarantine`);
+        otherActive = true;
+      }
+      if (!otherActive) {
+        try {
+          const q = await _quarantineDirtyWorktree(
+            rootDir, worktreePath, branchName, gitOpts,
+            {
+              dispatchId,
+              reason: result.reason,
+              statusError: e.message,
+            },
+          );
+          result.quarantined = true;
+          result.quarantinedPath = q.quarantinedPath;
+          result.backupRef = q.backupRef;
+        } catch (qErr) {
+          result.quarantineError = qErr.message;
+          log('error', `assertCleanSharedWorktree: quarantine after status-failed failed for ${worktreePath}: ${qErr.message}`);
+        }
+      }
+    }
     return result;
   }
   if (statusOut) {
@@ -937,7 +999,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
   try {
     const r = await execAsync(
       `git rev-list --left-right --count refs/remotes/origin/${branchName}...HEAD`,
-      { ...gitOpts, cwd: worktreePath, timeout: 10000 },
+      { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs },
     );
     const parts = String(r || '').trim().split(/\s+/);
     const behind = parseInt(parts[0], 10);
@@ -1000,7 +1062,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     try {
       const r = await execAsync(
         `git rev-list ${opts.mainBranch}..HEAD --count`,
-        { ...gitOpts, cwd: worktreePath, timeout: 10000 },
+        { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs },
       );
       const parsed = parseInt(String(r || '').trim(), 10);
       if (Number.isFinite(parsed)) commitsAheadOfMain = parsed;
@@ -1059,7 +1121,7 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
 
   // 7. Re-verify
   try {
-    const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: 10000 });
+    const r2 = await execAsync('git status --porcelain', { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
     const after = (r2 || '').toString().trim();
     if (after) {
       result.reason = 'dirty-after-clean';
@@ -1853,7 +1915,10 @@ async function spawnAgent(dispatchItem, config) {
       _phaseT.cleanCheckStart = Date.now();
       const cleanResult = await assertCleanSharedWorktree(
         rootDir, worktreePath, branchName, id, _gitOpts,
-        { mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch) },
+        {
+          mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch),
+          statusTimeoutMs: engineConfig.assertCleanStatusTimeoutMs ?? ENGINE_DEFAULTS.assertCleanStatusTimeoutMs,
+        },
       );
       _phaseT.cleanCheckEnd = Date.now();
       if (!cleanResult.clean) {
@@ -1912,12 +1977,26 @@ async function spawnAgent(dispatchItem, config) {
       _phaseT.dirtyReusedCheckStart = Date.now();
       const cleanResult = await assertCleanSharedWorktree(
         rootDir, worktreePath, branchName, id, _gitOpts,
-        { quarantineOnUnsafe: true, mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch) },
+        {
+          quarantineOnUnsafe: true,
+          mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch),
+          statusTimeoutMs: engineConfig.assertCleanStatusTimeoutMs ?? ENGINE_DEFAULTS.assertCleanStatusTimeoutMs,
+        },
       );
       _phaseT.dirtyReusedCheckEnd = Date.now();
       if (!cleanResult.clean) {
         const previewFiles = (cleanResult.dirtyFiles || []).slice(0, 5).join(', ');
         const isDivergent = (cleanResult.ahead || 0) > 0 || cleanResult.reason === 'no-upstream';
+        // W-mq1habhf: status-failed is a different beast than
+        // has-unpushed-commits / no-upstream. We couldn't even read the
+        // worktree state, so there is nothing to lose by retrying after the
+        // quarantine has cleared the bad tree. Mark this branch retryable
+        // (agentRetryable: true) so the next dispatch creates a fresh
+        // worktree on the same WI without burning a retry slot against the
+        // quarantineAutoRecoveryMax counter. has-unpushed-commits /
+        // no-upstream / dirty-after-clean stay non-retryable because they
+        // protect potentially-unpushed agent work.
+        const isStatusProbeFailed = cleanResult.reason === 'status-failed';
         const failureClassValue = isDivergent ? FAILURE_CLASS.WORKTREE_DIVERGENT : FAILURE_CLASS.WORKTREE_DIRTY;
         const failureClassName = isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY';
         const reasonMsg = cleanResult.quarantined
@@ -1930,7 +2009,7 @@ async function spawnAgent(dispatchItem, config) {
           DISPATCH_RESULT.ERROR,
           reasonMsg.slice(0, 500),
           `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : ''}`,
-          { agentRetryable: false, failureClass: failureClassValue },
+          { agentRetryable: isStatusProbeFailed && cleanResult.quarantined, failureClass: failureClassValue },
         );
         cleanupTempAgent(agentId);
         return null;
@@ -5740,9 +5819,27 @@ function getWorkItemPrRef(item) {
   // (issue #2999 / W-mpx6i5kh000ac040). Defence in depth: even if a manual
   // /api/work-items create slipped through without structured PR fields, the
   // engine still detects the PR pointer here at dispatch time.
+  //
+  // NOTE: this loose form is for callers that downgrade gracefully on miss
+  // (resolveWorkItemPrRecord returning null, withWorkItemPrContext skipping
+  // injection, branch derivation falling through to default). The dispatch
+  // *gate* (`pr_not_found`) must NOT use this — it would trip on commentary
+  // like "see PR #3015 for context" in a description with no real PR target.
+  // The gate uses getStructuredWorkItemPrRef below (W-mq18ec6h000p7b87).
   return shared.extractWorkItemPrRef(item);
 }
 
+function getStructuredWorkItemPrRef(item) {
+  // Structured-only variant used ONLY by the dispatch `pr_not_found` gate
+  // (W-mq18ec6h000p7b87). Walks targetPr/pr/pr_id/prId/sourcePr/pullRequest
+  // /prUrl/prNumber, references[*].url, and meta.pr_followup.parent_pr_url
+  // — never description/title prose. This asymmetry is intentional:
+  //   - GATE (here): require explicit operator intent to block dispatch.
+  //   - STAMP (dashboard.js#getWorkItemPrRef): keep loose form so operators
+  //     pasting PR URLs in description prose get targetPr auto-stamped.
+  return shared.extractStructuredWorkItemPrRef(item);
+}
+
 function resolveWorkItemPrRecord(item, project) {
   if (!project) return null;
   const prRef = getWorkItemPrRef(item);
@@ -6058,9 +6155,16 @@ function discoverFromWorkItems(config, project) {
     const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
     const prBranch = linkedPr?.branch || '';
     const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
-    if (!linkedPr && getWorkItemPrRef(item) && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
+    // W-mq18ec6h000p7b87: gate on the STRUCTURED-only ref. Loose
+    // getWorkItemPrRef would also pick up description-scan refs (e.g. a
+    // refactor item whose prose mentioned "PR #3015 for context") and trip
+    // the gate even though the item has no real PR target. The dashboard's
+    // create-time stamp path keeps using the loose form — gate uses
+    // structured-only; stamp uses loose. See engine/shared.js
+    // extractStructuredWorkItemPrRef for the structured-source list.
+    if (!linkedPr && getStructuredWorkItemPrRef(item) && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
       if (item._pendingReason !== 'pr_not_found') { item._pendingReason = 'pr_not_found'; needsWrite = true; }
-      log('warn', `Work item ${item.id} references PR ${getWorkItemPrRef(item)} but no tracked PR record was found`);
+      log('warn', `Work item ${item.id} references PR ${getStructuredWorkItemPrRef(item)} but no tracked PR record was found`);
       continue;
     }
     const isShared = item.branchStrategy === 'shared-branch' && item.featureBranch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2126",
+  "version": "0.1.2128",
   "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"

package/prompts/cc-system.md

@@ -64,7 +64,7 @@ State the size in 3-4 words to yourself, then act:
 
 ### Step 2 — Delegate when ≥ Medium (the hard stop)
 Always delegate these to an agent — do not attempt them yourself even if they look small at first:
-- Code changes, fixes, refactors, new features → `POST /api/work-items` with `type: "implement"` or `"fix"`
+- Code changes, fixes, refactors, new features → `POST /api/work-items` with `type: "implement"` (use `"fix"` only when the work targets a specific tracked PR — see the type-selection note under "Calling the Minions API" below)
 - Exploration, investigation, research, audits → `POST /api/work-items` with `type: "explore"`
 - Code reviews → `POST /api/work-items` with `type: "review"`
 - Testing → `POST /api/work-items` with `type: "test"`
@@ -110,12 +110,20 @@ Returns `{routes: [{method, path, description, params}]}`. Use this when you nee
 
 **Worked examples** (always include `Content-Type: application/json` on POSTs with a JSON body):
 
-Dispatch a fix:
+Dispatch a fresh bugfix (no tracked PR yet — opens a new PR):
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/work-items \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"title":"Fix login bug","type":"fix","project":"MyApp","description":"...","agent":"dallas"}'
+  -d '{"title":"Fix login bug","type":"implement","project":"MyApp","description":"...","agent":"dallas"}'
+```
+
+Dispatch a fix against a tracked PR (responds to comments / failing builds on that PR):
+```
+curl -s -X POST http://localhost:{{dashboard_port}}/api/work-items \
+  -H 'Content-Type: application/json' \
+  -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"title":"Address review feedback on PR #2533","type":"fix","project":"MyApp","description":"...","references":[{"url":"https://github.com/owner/MyApp/pull/2533","label":"PR #2533"}],"agent":"dallas"}'
 ```
 
 Save a note:
@@ -155,7 +163,7 @@ Set up a "watch + CC triage" follow-up — fire CC headlessly when a watch trips
 curl -s -X POST http://localhost:{{dashboard_port}}/api/watches \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"target":"W-...","targetType":"work-item","condition":"failed","action":{"type":"cc-triage","params":{"prompt":"WI {{target}} failed. Read the completion report and tail of live-output. If it is a flaky CI failure (transient, unrelated to the diff), file a follow-up `fix` WI titled \"Investigate flake on {{target}}\". Otherwise post an inbox note explaining the root cause and do nothing else.","attachArtifacts":["completion-report","live-output"]}}}'
+  -d '{"target":"W-...","targetType":"work-item","condition":"failed","action":{"type":"cc-triage","params":{"prompt":"WI {{target}} failed. Read the completion report and tail of live-output. If it is a flaky CI failure (transient, unrelated to the diff), file a follow-up `implement` WI titled \"Investigate flake on {{target}}\" (no tracked PR yet — fresh bugfix opens a new PR, so type=implement, not fix). Otherwise post an inbox note explaining the root cause and do nothing else.","attachArtifacts":["completion-report","live-output"]}}}'
 ```
 The `cc-triage` action is internal — it runs in an isolated CC session (not your interactive ccSession) and never shows up in the user's tab list. Use it when "fire a single fixed work item" isn't expressive enough.
 
@@ -227,6 +235,7 @@ curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
 
 **Required fields per endpoint** — the server returns `{ error: "..." }` if missing. Common cases:
 - `POST /api/work-items`: `title` REQUIRED. `description` recommended. `project` REQUIRED when multiple projects are configured (server returns the list of known names if you guess wrong). `type` defaults to `implement`; valid values: `fix`, `implement`, `implement:large`, `setup`, `explore`, `ask`, `review`, `test`, `verify`. Agent hint via `agent` (string) or `agents` (array).
+  - **`fix` vs `implement` — pick deliberately.** `type: "fix"` in the engine means "this work item responds to comments or build failures on a tracked PR" — it requires a PR pointer (in `references[*].url`, `meta.pr_followup.parent_pr_url`, or `targetPr`/`pr_id`/`prNumber`) and is dispatched onto the PR's source branch. **Fresh bugfix work** that will open a NEW PR (engine bugs, default-branch CI failures, repo-level regressions found from logs) is `type: "implement"`, not `type: "fix"`. Emitting `type: "fix"` without a PR pointer trips the `pr_not_found` discovery gate (engine.js#discoverWork) and the WI stays blocked indefinitely. Rule of thumb: if the work could land on master via a brand-new PR, it's `implement`; if it must push commits into an existing PR's source branch, it's `fix`.
   - Exempt from the `project` requirement (these run rootless or via central paths): `ask`, `explore`, `plan`, `plan-to-prd`, `meeting`. (`docs` is intentionally NOT exempt — it's write-capable and lands in `WORKTREE_REQUIRING_TYPES`, so it needs a real project worktree. For minions-repo docs work, pass `project: "minions"` explicitly.) `setup` is also in the project-required set — it operates inside a real project worktree but produces no PR. Every other type needs a project worktree, so the server rejects project-less creates with `400 { error, knownProjects }` when ≠1 project is configured.
   - **`meta.keep_processes: true`** — opt-in flag that lets the agent leave specific descendant PIDs running after it exits (default: engine reaps EVERYTHING the agent spawned). **Set this whenever the user's intent is to leave a process alive after the agent finishes** — e.g. "spin up the dev server and exit", "start the watcher and leave it running", "set up my dev env", "keep the emulator open", "launch the daemon for me", "boot the constellation host and disconnect". Don't set it for normal build/test/run-once tasks (`npm test`, `npm run build`, one-shot scripts) — those should be reaped. Also accepts optional `meta.keep_processes_ttl_minutes` (default 60, hard-cap 1440 = 24h). When you set this flag, also make the WI title/description say something like "leave the dev server running" so the agent knows to write `agents/<id>/keep-pids.json` before exiting (the playbook injects the contract automatically when the flag is on). Example: `-d '{"title":"Spin up Constellation dev env and leave server running","type":"implement","project":"constellation","description":"Run bun install + bun run dev. Leave the dev server (port 5173) and Constellation host (port 3001) running after you exit so the user can iterate.","meta":{"keep_processes":true,"keep_processes_ttl_minutes":240}}'`. Inspect / kill kept PIDs anytime via `GET /api/keep-processes` and `POST /api/keep-processes/kill`.
   - **`skipPr: true`** — opt-in flag that tells the engine NOT to enforce the PR-attachment contract for this work item, so the WI can complete `done` without the missing-PR hard-fail. **Set this when the dispatch mutates state OUTSIDE any tracked git repo and therefore cannot produce a PR** — e.g. cleaning `~/.claude/skills/`, editing runtime config under `~/.config/`, resetting the dashboard cache, mutating engine JSON state files (`engine/*.json`) the engine itself owns, or local tooling installs. **Do NOT set it for any task that touches a tracked repo's source** — even one-line diffs in a real repo should produce a PR. Type-selection rule of thumb: prefer `type: "setup"` for infra/dev-env bootstrap tasks that mutate project state but produce no PR (it's implicitly PR-exempt — no `skipPr` needed); prefer `type: "explore"` for genuinely read-only tasks (rootless, no worktree, no PR contract); use `skipPr: true` only when the task is write-side mutation but the writes don't land in a git repo and `setup` doesn't fit (e.g. cleaning user-machine state outside any repo). Example: `-d '{"title":"Bootstrap Constellation dev stack","type":"setup","project":"constellation","description":"Run bun install + bun run dev and leave the dev server running.","meta":{"managed_spawn":true}}'`.

package/prompts/doc-chat-system.md

@@ -38,18 +38,27 @@ For explicit dispatch/delegation requests or medium/larger work without a direct
 
 Always include the `X-CC-Turn-Id: {{cc_turn_id}}` header on state-changing calls so the dashboard can correlate the work item with this conversation turn and surface a confirmation chip in your reply.
 
-Worked example for a dispatch:
+Worked example for a fresh-bugfix dispatch (no tracked PR yet — opens a new PR):
 
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/work-items \
   -H 'Content-Type: application/json' \
   -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"title":"Fix login bug","type":"fix","project":"MyApp","description":"...","agent":"dallas"}'
+  -d '{"title":"Fix login bug","type":"implement","project":"MyApp","description":"...","agent":"dallas"}'
+```
+
+Worked example for a PR-tied fix (responds to comments / failing builds on an existing tracked PR):
+
+```
+curl -s -X POST http://localhost:{{dashboard_port}}/api/work-items \
+  -H 'Content-Type: application/json' \
+  -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"title":"Address review feedback on PR #2533","type":"fix","project":"MyApp","description":"...","references":[{"url":"https://github.com/owner/MyApp/pull/2533","label":"PR #2533"}],"agent":"dallas"}'
 ```
 
 Body fields:
 - `title` REQUIRED.
-- `type` REQUIRED. Use `explore` for audits/investigations/research/architecture analysis/substantial queries needing a written report. Use `ask` for substantial but non-investigative answer-only requests. Use `implement`/`fix`/`review`/`test`/`verify` when the requested outcome matches those engine flows.
+- `type` REQUIRED. Use `explore` for audits/investigations/research/architecture analysis/substantial queries needing a written report. Use `ask` for substantial but non-investigative answer-only requests. Use `implement`/`fix`/`review`/`test`/`verify` when the requested outcome matches those engine flows. **`fix` vs `implement`:** `type: "fix"` is reserved for work targeting a specific tracked PR (responds to comments / build failures on that PR) — it requires a PR pointer (in `references[*].url` or `targetPr`/`pr_id`/`prNumber`) and dispatches onto the PR's source branch. **Fresh bugfix work** that will open a NEW PR (engine bugs, CI failures on the default branch, repo-level regressions) uses `type: "implement"`. Emitting `type: "fix"` without a tracked PR pointer blocks the WI at the engine's `pr_not_found` discovery gate.
 - `priority` optional: `low`/`medium`/`high`.
 - `description` recommended.
 - `project` REQUIRED when multiple projects are configured.