@yemi33/minions 0.1.1642 → 0.1.1644

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1644 (2026-04-30)
+
+### Fixes
+- harden action contracts so CC can't claim work it didn't do
+
 ## 0.1.1642 (2026-04-30)
 
 ### Features

package/dashboard/js/command-center.js

@@ -686,11 +686,30 @@ async function _ccDoSend(message, skipUserMsg, forceTabId) {
         if (evt.actions && evt.actions.length > 0) {
           _tagServerExecuted(evt.actions, evt.actionResults);
           for (var ai = 0; ai < evt.actions.length; ai++) { await ccExecuteAction(evt.actions[ai], activeTabId); }
+          // Surface per-action errors/warnings inline alongside the prose so the user can see
+          // exactly which actions failed or completed with caveats. Previously these only
+          // appeared as a small "executed" pill which gave no detail.
+          if (evt.actionResults && Array.isArray(evt.actionResults)) {
+            var failures = evt.actionResults.filter(function(r) { return r && r.error; });
+            var warnings = evt.actionResults.filter(function(r) { return r && r.warning; });
+            if (failures.length > 0) {
+              var failHtml = failures.map(function(r) { return '<li>' + escHtml(r.type || 'action') + ': ' + escHtml(r.error) + '</li>'; }).join('');
+              addMsg('system', '<div style="padding:6px 12px;font-size:11px;color:var(--red);background:var(--surface2);border-radius:6px;margin:4px 0">⚠️ ' + failures.length + ' action' + (failures.length > 1 ? 's' : '') + ' failed:<ul style="margin:4px 0 0 16px;padding:0">' + failHtml + '</ul></div>', false, activeTabId);
+            }
+            if (warnings.length > 0) {
+              var warnHtml = warnings.map(function(r) { return '<li>' + escHtml(r.type || 'action') + ': ' + escHtml(r.warning) + '</li>'; }).join('');
+              addMsg('system', '<div style="padding:6px 12px;font-size:11px;color:var(--orange);background:var(--surface2);border-radius:6px;margin:4px 0">ℹ️ ' + warnings.length + ' action' + (warnings.length > 1 ? '' : '') + ' completed with warnings:<ul style="margin:4px 0 0 16px;padding:0">' + warnHtml + '</ul></div>', false, activeTabId);
+            }
+          }
         } else if (evt.actionParseError) {
           // Issue #1834: server saw ===ACTIONS=== but couldn't parse the JSON.
           // Surface as an inline warning so the user knows actions were dropped
           // (was previously silent — appeared as "actions failed" with no signal).
           addMsg('system', '<div style="padding:6px 12px;font-size:11px;color:var(--red);background:var(--surface2);border-radius:6px;margin:4px 0">⚠️ Actions block emitted but JSON could not be parsed — no actions were executed. Resend or rephrase. (' + escHtml(String(evt.actionParseError).slice(0, 200)) + ')</div>', false, activeTabId);
+        } else if (evt.hallucinationWarning) {
+          // CC said it dispatched/queued/assigned something but emitted no actions block —
+          // surface the false-claim guard so the user knows nothing actually ran.
+          addMsg('system', '<div style="padding:6px 12px;font-size:11px;color:var(--orange);background:var(--surface2);border-radius:6px;margin:4px 0">⚠️ ' + escHtml(evt.hallucinationWarning) + '</div>', false, activeTabId);
         }
       } else if (evt.type === 'error') {
         terminalEventSeen = true;

package/dashboard.js

@@ -28,6 +28,7 @@ const watchesMod = require('./engine/watches');
 const routing = require('./engine/routing');
 const playbook = require('./engine/playbook');
 const dispatchMod = require('./engine/dispatch');
+const steering = require('./engine/steering');
 const os = require('os');
 
 const { safeRead, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeUnlink, mutateJsonFileLocked, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, reopenWorkItem } = shared;
@@ -148,6 +149,21 @@ function _resolveSkillReadPath({ file, dir, source, config, skillFiles } = {}) {
   return null;
 }
 
+function _agentSessionIsDraining(agentId) {
+  const activeForAgent = (getDispatchQueue().active || []).some(d => d.agent === agentId);
+  if (!activeForAgent) return false;
+  const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+  const tail = (safeRead(liveLogPath) || '').slice(-65536);
+  if (!tail) return false;
+  const lastSteer = tail.lastIndexOf('[human-steering]');
+  const terminalIdx = Math.max(
+    tail.lastIndexOf('[process-exit]'),
+    tail.lastIndexOf('"type":"session.task_complete"'),
+    tail.lastIndexOf('"type":"result"')
+  );
+  return terminalIdx >= 0 && terminalIdx > lastSteer;
+}
+
 const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
 const TEAMS_INBOX_PATH = path.join(ENGINE_DIR, 'teams-inbox.json');
 
@@ -1296,17 +1312,100 @@ function _parseWatchInterval(val) {
   return Math.max(60000, Math.round(u === 's' ? n * 1000 : u === 'm' ? n * 60000 : n * 3600000));
 }
 
+// Required-field validator for CC actions. Returns null when valid, an error string when not.
+// Centralises field-required checks so the model can't quietly emit a malformed action and have
+// the server silently fall back to placeholder values (e.g. "Untitled"). The handler invokes this
+// before `try` to avoid filling `results` with cryptic per-handler error messages.
+function _ccValidateAction(action) {
+  if (!action || typeof action !== 'object' || !action.type) return 'action is missing required field: type';
+  switch (action.type) {
+    case 'dispatch': case 'fix': case 'implement': case 'explore': case 'review': case 'test':
+      if (!action.title || typeof action.title !== 'string' || !action.title.trim()) return `${action.type} action missing required field: title`;
+      return null;
+    case 'build-and-test':
+      if (!action.pr) return 'build-and-test action missing required field: pr';
+      return null;
+    case 'note':
+      if (!action.title) return 'note action missing required field: title';
+      if (!action.content && !action.description) return 'note action missing required field: content (or description)';
+      return null;
+    case 'knowledge':
+      if (!action.title) return 'knowledge action missing required field: title';
+      if (!action.content) return 'knowledge action missing required field: content';
+      if (!action.category) return 'knowledge action missing required field: category';
+      return null;
+    case 'pin-to-pinned':
+      if (!action.title || !action.content) return 'pin-to-pinned action missing title or content';
+      return null;
+    case 'plan':
+      if (!action.title) return 'plan action missing required field: title';
+      return null;
+    default:
+      return null; // unknown types fall through to existing handler / generic fallback
+  }
+}
+
+// Hallucination guard: detect prose like "I dispatched ..." when no ===ACTIONS=== block was emitted.
+// The regex is intentionally narrow — we only want affirmative claims about completed work, not
+// hypotheticals like "I would dispatch this" or "consider dispatching X".
+function _detectClaimedActionWithoutBlock(displayText, actions) {
+  if (Array.isArray(actions) && actions.length > 0) return null; // there are actions, no false claim
+  const triggers = /\b(dispatched|enqueued|queued|created (?:a |the )?work item|assigned (?:this |it )?(?:to|for)|spun up|kicked off|i'?ll dispatch|i (?:have )?(?:just )?dispatched)\b/i;
+  if (!triggers.test(displayText || '')) return null;
+  return 'CC described an action ("dispatched", "assigned", etc.) but no ===ACTIONS=== block was emitted. No work was actually queued. Resend or rephrase the request.';
+}
+
 async function executeCCActions(actions) {
   const results = [];
   for (const action of actions) {
+    const validationError = _ccValidateAction(action);
+    if (validationError) {
+      results.push({ type: action?.type || 'unknown', error: validationError });
+      continue;
+    }
     try {
       switch (action.type) {
         case 'dispatch': case 'fix': case 'implement': case 'explore': case 'review': case 'test': {
           const workType = action.workType || (action.type !== 'dispatch' ? action.type : 'implement');
           const id = 'W-' + shared.uid();
           const project = action.project || '';
-          const targetProject = project ? PROJECTS.find(p => p.name?.toLowerCase() === project.toLowerCase()) : PROJECTS[0];
+
+          // Strict project resolution. Silent fallback to PROJECTS[0] when the model named an unknown
+          // project caused work items to land in the wrong repo. Now: unknown name → error; ambiguous
+          // (multiple projects + no field) → error; single-project deployments fall through; zero
+          // projects → root-level work-items.json (orchestration system standalone use).
+          let targetProject = null;
+          if (project) {
+            targetProject = PROJECTS.find(p => p.name?.toLowerCase() === project.toLowerCase());
+            if (!targetProject) {
+              const known = PROJECTS.map(p => p.name).join(', ') || '(none configured)';
+              results.push({ type: action.type, error: `Project "${project}" not found. Known projects: ${known}` });
+              break;
+            }
+          } else if (PROJECTS.length > 1) {
+            results.push({ type: action.type, error: `project field is required when ${PROJECTS.length} projects are configured: ${PROJECTS.map(p => p.name).join(', ')}` });
+            break;
+          } else if (PROJECTS.length === 1) {
+            targetProject = PROJECTS[0];
+          }
+          // PROJECTS.length === 0 → targetProject stays null, falls back to root work-items.json (existing behavior).
+
           const wiPath = targetProject ? shared.projectWorkItemsPath(targetProject) : path.join(MINIONS_DIR, 'work-items.json');
+
+          // Promote `agent` (singular) → `agents` (array). Models emit either shape and the prior code
+          // only read `action.agents`, silently dropping `agent: "lambert"` style hints.
+          const agentHints = (() => {
+            if (Array.isArray(action.agents) && action.agents.length > 0) return action.agents.map(String).filter(Boolean);
+            if (typeof action.agent === 'string' && action.agent) return [action.agent];
+            return [];
+          })();
+          const knownAgents = Object.keys(CONFIG.agents || {});
+          const unknownAgent = agentHints.find(a => !knownAgents.includes(a));
+          if (unknownAgent) {
+            results.push({ type: action.type, error: `Unknown agent "${unknownAgent}". Configured agents: ${knownAgents.join(', ') || '(none)'}` });
+            break;
+          }
+
           // Issue #1772: CC review/explore/test are human-initiated one-offs.
           // Mark oneShot so any discovered PR is tagged _contextOnly (skips eval loop).
           const ccOneShotTypes = new Set(['review', 'explore', 'test']);
@@ -1314,16 +1413,28 @@ async function executeCCActions(actions) {
           shared.mutateJsonFileLocked(wiPath, items => {
             if (!Array.isArray(items)) items = [];
             items.push({
-              id, title: action.title || 'Untitled', type: workType,
+              id, title: action.title, type: workType,
               priority: action.priority || 'medium', description: action.description || '',
               status: WI_STATUS.PENDING, created: new Date().toISOString(),
               createdBy: 'command-center', project,
-              ...(action.agents?.length ? { preferred_agent: action.agents[0], agents: action.agents } : {}),
+              ...(agentHints.length ? { preferred_agent: agentHints[0], agents: agentHints } : {}),
               ...(isOneShot ? { oneShot: true } : {}),
             });
             return items;
           }, { defaultValue: [] });
           results.push({ type: action.type, id, ok: true });
+
+          // Pre-flight routing check: warn the user if no agent is currently available so the new
+          // item won't sit pending invisibly. Routing failure is non-fatal — the WI was created.
+          try {
+            const resolvedAgent = routing.resolveAgent(workType, CONFIG, { agentHints });
+            if (!resolvedAgent) {
+              const lastResult = results[results.length - 1];
+              lastResult.warning = `Created ${id} but no agent is currently available to dispatch (routing returned no match for workType=${workType}${agentHints.length ? ', hints=' + agentHints.join(',') : ''}). Item will sit pending until an agent becomes available.`;
+            }
+          } catch (e) {
+            shared.log('warn', `CC dispatch routing pre-flight: ${e.message}`);
+          }
           break;
         }
         case 'build-and-test': {
@@ -4753,6 +4864,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const { _actionParseError, ...parsedReply } = parsed;
         const reply = { ...parsedReply, sessionId: ccSession.sessionId, newSession: !wasResume };
         if (_actionParseError) reply.actionParseError = _actionParseError;
+        const hallucinationWarning = _detectClaimedActionWithoutBlock(parsed.text, parsed.actions);
+        if (hallucinationWarning) reply.hallucinationWarning = hallucinationWarning;
         if (sessionReset) reply.sessionReset = true;
         return jsonReply(res, 200, reply);
       } finally {
@@ -5036,6 +5149,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // Issue #1834: surface action JSON parse failures so the UI can warn
         // instead of silently dropping. Client renders this as a small notice.
         if (_actionParseError) donePayload.actionParseError = _actionParseError;
+        const hallucinationWarning = _detectClaimedActionWithoutBlock(displayText, actions);
+        if (hallucinationWarning) donePayload.hallucinationWarning = hallucinationWarning;
         if (sessionReset) donePayload.sessionReset = true;
         liveState.donePayload = donePayload;
         if (liveState.writer) liveState.writer(donePayload);
@@ -5924,7 +6039,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             if (!pr.branch && prData.branch) {
               pr.branch = prData.branch;
               if (pr._branchResolutionError) delete pr._branchResolutionError;
-              if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+              if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
             }
             if (pr.agent === 'human' && prData.author) pr.agent = prData.author;
             return prs;
@@ -6002,21 +6117,30 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
     { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message', handler: async (req, res) => {
       const body = await readBody(req);
-      const { agent: agentId, message } = body;
-      if (!agentId || !message) return jsonReply(res, 400, { error: 'agent and message required' });
+      const { agent, message } = body;
+      if (!agent || !message) return jsonReply(res, 400, { error: 'agent and message required' });
+      const agentId = String(agent).replace(/[^a-zA-Z0-9_-]/g, '');
+      const text = String(message).trim();
+      if (!agentId || !text) return jsonReply(res, 400, { error: 'agent and message required' });
 
-      const steerPath = path.join(MINIONS_DIR, 'agents', agentId, 'steer.md');
       const agentDir = path.join(MINIONS_DIR, 'agents', agentId);
       if (!fs.existsSync(agentDir)) return jsonReply(res, 404, { error: 'Agent not found' });
+      if (_agentSessionIsDraining(agentId)) {
+        return jsonReply(res, 409, { error: 'Agent session is finishing; retry when the next session starts' });
+      }
 
-      // Write steering file
-      safeWrite(steerPath, message);
+      const entry = steering.writeSteeringMessage(agentId, text);
 
       // Also append to live-output.log so it shows in the chat view
       const liveLogPath = path.join(agentDir, 'live-output.log');
-      try { fs.appendFileSync(liveLogPath, '\n[human-steering] ' + message + '\n'); } catch { /* optional */ }
+      try { fs.appendFileSync(liveLogPath, '\n[human-steering] ' + text + '\n'); } catch { /* optional */ }
 
-      return jsonReply(res, 200, { ok: true, message: 'Steering message sent' });
+      return jsonReply(res, 200, {
+        ok: true,
+        message: 'Steering message queued',
+        file: entry?.file || null,
+        inboxCount: steering.listUnreadSteeringMessages(agentId).length,
+      });
     }},
     { method: 'POST', path: '/api/agents/cancel', desc: 'Cancel an active agent by ID or task substring', params: 'agent?, task?', handler: handleAgentsCancel },
     { method: 'POST', path: /^\/api\/agent\/([\w-]+)\/kill$/, desc: 'Kill a running agent: stop process, clear dispatch, reset work items to pending', handler: handleAgentKill },
@@ -6425,6 +6549,9 @@ module.exports = {
   _linkPullRequestForTracking: linkPullRequestForTracking,
   _resolveSkillReadPath,
   DOC_CHAT_DOCUMENT_DELIMITER,
+  _ccValidateAction,
+  _detectClaimedActionWithoutBlock,
+  executeCCActions,
 };
 
 // Start the HTTP server only when run directly (node dashboard.js).

package/engine/ado.js

@@ -268,7 +268,8 @@ async function forEachActivePr(config, token, callback) {
     if (!project.adoOrg || !project.adoProject) continue;
 
     const prs = getPrs(project);
-    const activePrs = prs.filter(pr => shared.PR_POLLABLE_STATUSES.has(pr.status));
+    const activePrs = prs.filter(pr => shared.PR_POLLABLE_STATUSES.has(pr.status)
+      && shared.isPrCompatibleWithProject(project, pr, pr.url || ''));
     if (activePrs.length === 0) continue;
 
     const adoRepositoryId = getAdoRepositoryId(project);
@@ -798,7 +799,7 @@ async function reconcilePrs(config) {
         if (existing && !existing.branch && branch) {
           existing.branch = branch;
           if (existing._branchResolutionError) delete existing._branchResolutionError;
-          if (existing._pendingReason === 'missing_pr_branch') delete existing._pendingReason;
+          if (existing._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete existing._pendingReason;
           metadataUpdated++;
         }
         // PR already tracked — write link to pr-links.json if we can extract an ID

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-04-30T20:24:03.227Z"
+  "cachedAt": "2026-04-30T21:06:17.577Z"
 }

package/engine/github.js

@@ -206,7 +206,8 @@ async function forEachActiveGhPr(config, callback) {
     if (isSlugInBackoff(slug)) continue;
 
     const prs = getPrs(project);
-    const activePrs = prs.filter(pr => PR_POLLABLE_STATUSES.has(pr.status));
+    const activePrs = prs.filter(pr => PR_POLLABLE_STATUSES.has(pr.status)
+      && shared.isPrCompatibleWithProject(project, pr, pr.url || ''));
     if (activePrs.length === 0) continue;
 
     // Probe repo accessibility before iterating PRs — avoids N warnings per inaccessible repo
@@ -285,7 +286,7 @@ async function forEachActiveGhPr(config, callback) {
             if (!pr.branch && prData.head?.ref) {
               pr.branch = prData.head.ref;
               if (pr._branchResolutionError) delete pr._branchResolutionError;
-              if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+              if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
             }
           }
         }
@@ -332,7 +333,7 @@ async function pollPrStatus(config) {
     if (headBranch && pr.branch !== headBranch) {
       pr.branch = headBranch;
       if (pr._branchResolutionError) delete pr._branchResolutionError;
-      if (pr._pendingReason === 'missing_pr_branch') delete pr._pendingReason;
+      if (pr._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete pr._pendingReason;
       updated = true;
     }
 
@@ -713,7 +714,7 @@ async function reconcilePrs(config) {
         if (existing && !existing.branch && branch) {
           existing.branch = branch;
           if (existing._branchResolutionError) delete existing._branchResolutionError;
-          if (existing._pendingReason === 'missing_pr_branch') delete existing._pendingReason;
+          if (existing._pendingReason === shared.PR_PENDING_REASON.MISSING_BRANCH) delete existing._pendingReason;
           metadataUpdated++;
         }
         if (confirmedItemId) {

package/engine/lifecycle.js

@@ -707,11 +707,46 @@ function reconcilePrdStatuses(config) {
 
 function syncPrsFromOutput(output, agentId, meta, config) {
 
-  const prMatches = new Set();
-  const urlPattern = /(?:visualstudio\.com|dev\.azure\.com)[^\s"]*?pullrequest\/(\d+)|github\.com\/[^\s"]*?\/pull\/(\d+)/g;
-  const textCreatedPattern = /(?:PR created|created PR|E2E PR)[:\s#-]*(\d{1,})/gi;
+  const prEvidence = new Map();
+  const trustedPrCreateToolIds = new Set();
+  const prUrlPattern = /(https?:\/\/github\.com\/[^\s"'\\)\]]+\/[^\s"'\\)\]]+\/pull\/(\d+)(?:[^\s"'\\)\]]*)?|https?:\/\/(?:dev\.azure\.com|[^/\s"'\\)\]]+\.visualstudio\.com)[^\s"'\\)\]]*?pullrequest\/(\d+)(?:[^\s"'\\)\]]*)?)/gi;
   let match;
 
+  function cleanPrUrl(url) {
+    return String(url || '').replace(/[.,;:]+$/, '');
+  }
+
+  function addPrUrlEvidence(text) {
+    if (!text) return;
+    prUrlPattern.lastIndex = 0;
+    while ((match = prUrlPattern.exec(String(text))) !== null) {
+      const prId = match[2] || match[3];
+      if (prId && !prEvidence.has(prId)) prEvidence.set(prId, cleanPrUrl(match[1]));
+    }
+  }
+
+  function addExplicitPrCreatedEvidence(text) {
+    if (!text) return;
+    const explicitPrCreatedPattern = /(?:^|\n)\s*\*{0,2}(?:PR|Pull\s+Request|E2E\s+PR)\s+(?:created|opened|submitted)\*{0,2}\s*[:\-]\s*([^\n]+)/gi;
+    let createdMatch;
+    while ((createdMatch = explicitPrCreatedPattern.exec(String(text))) !== null) {
+      addPrUrlEvidence(createdMatch[1]);
+    }
+  }
+
+  function isTrustedPrCreateToolUse(block) {
+    const name = String(block?.name || '');
+    if (/(?:create|open|submit)[_-]?(?:pull[_-]?request|pr)|(?:pull[_-]?request|pr)[_-]?(?:create|open|submit)/i.test(name)) {
+      return true;
+    }
+    const inputText = typeof block?.input === 'string' ? block.input : JSON.stringify(block?.input || {});
+    if (/\bgh(?:\.exe)?\s+pr\s+create\b/i.test(inputText)) return true;
+    if (/\baz(?:\.cmd|\.exe)?\s+repos\s+pr\s+create\b/i.test(inputText)) return true;
+    const callsAdoCreateApi = /_apis\/git\/repositories\/[^\s"'\\]+\/pullrequests\b/i.test(inputText);
+    const usesPost = /\bPOST\b|-X\s*POST|-Method\s+POST|method["']?\s*:\s*["']?POST/i.test(inputText);
+    return callsAdoCreateApi && usesPost;
+  }
+
   try {
     const lines = output.split('\n');
     for (const line of lines) {
@@ -720,60 +755,43 @@ function syncPrsFromOutput(output, agentId, meta, config) {
         const parsed = JSON.parse(line);
         const content = parsed.message?.content || [];
         for (const block of content) {
-          // Scan tool_result blocks in user messages for PR URLs (gh pr create output lands here)
+          if (block.type === 'tool_use' && block.id && isTrustedPrCreateToolUse(block)) {
+            trustedPrCreateToolIds.add(block.id);
+          }
+          // Tool output is trusted only when tied to a known PR-create command/API call.
           if (block.type === 'tool_result' && block.content) {
-            const text = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
-            while ((match = urlPattern.exec(text)) !== null) prMatches.add(match[1] || match[2]);
+            if (trustedPrCreateToolIds.has(block.tool_use_id)) {
+              const text = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
+              addPrUrlEvidence(text);
+            }
           }
-          // Also scan assistant text blocks for PR URLs and "PR created" patterns
+          // Assistant text must use the explicit Minions PR-created protocol line.
           if (block.type === 'text' && block.text) {
-            while ((match = urlPattern.exec(block.text)) !== null) prMatches.add(match[1] || match[2]);
-            textCreatedPattern.lastIndex = 0;
-            let m2;
-            while ((m2 = textCreatedPattern.exec(block.text)) !== null) prMatches.add(m2[1]);
+            addExplicitPrCreatedEvidence(block.text);
           }
         }
         if (parsed.type === 'result' && parsed.result) {
-          const resultText = parsed.result;
-          const createdPattern = /(?:created|opened|submitted|new PR|PR created)[^\n]*?(?:(?:visualstudio\.com|dev\.azure\.com)[^\s"]*?pullrequest\/(\d+)|github\.com\/[^\s"]*?\/pull\/(\d+))/gi;
-          while ((match = createdPattern.exec(resultText)) !== null) prMatches.add(match[1] || match[2]);
-          const createdIdPattern = /(?:created|opened|submitted|new)\s+PR[# -]*(\d{1,})/gi;
-          while ((match = createdIdPattern.exec(resultText)) !== null) prMatches.add(match[1]);
+          const resultText = typeof parsed.result === 'string' ? parsed.result : JSON.stringify(parsed.result);
+          addExplicitPrCreatedEvidence(resultText);
         }
       } catch {}
     }
   } catch {}
 
-  // prId → URL captured from inbox notes. Populated alongside prMatches so
-  // extractPrUrl below has a fallback when the agent's stdout doesn't contain
-  // the URL (the W-moljyu60wuzr / #1902 case — gh pr create ran in a sibling
-  // dispatch and only the inbox note carries the link).
-  const inboxUrls = new Map();
+  // Accept inbox fallback only when the agent wrote the explicit PR-created
+  // protocol line; generic PR mentions in findings/review notes are not evidence.
   const today = dateStamp();
   const inboxFiles = getInboxFiles().filter(f => f.includes(agentId) && f.includes(today));
   for (const f of inboxFiles) {
     const content = safeRead(path.join(INBOX_DIR, f));
     if (!content) continue;
-    // Match a PR declaration line in the agent's findings note: optional bold,
-    // optional "Pull Request" spelling, line-anchored so "see PR https://..."
-    // mid-paragraph mentions don't trigger a false-positive. The protocol
-    // and host prefix is optional so "PR: https://github.com/..." ,
-    // "**PR:** github.com/...", etc. all match.
-    const prHeaderPattern = /(?:^|\n)\s*\*{0,2}(?:PR|Pull\s+Request)[:\*]*\*?\s*[#-]*\s*(?:https?:\/\/)?[^\s"]*?(?:(?:visualstudio\.com|dev\.azure\.com)[^\s"]*?pullrequest\/(\d+)|github\.com\/[^\s"]*?\/pull\/(\d+))/gi;
+    const prHeaderPattern = /(?:^|\n)\s*\*{0,2}(?:PR|Pull\s+Request|E2E\s+PR)\s+(?:created|opened|submitted)\*{0,2}\s*[:\-]\s*([^\n]+)/gi;
     while ((match = prHeaderPattern.exec(content)) !== null) {
-      const prId = match[1] || match[2];
-      prMatches.add(prId);
-      // Pull the URL substring out of the matched chunk so we can hand it to
-      // extractPrUrl as a fallback. Prefer the first inbox URL we see for a
-      // given prId — later notes don't override the canonical record.
-      if (!inboxUrls.has(prId)) {
-        const urlMatch = match[0].match(/https?:\/\/[^\s"\\)]+/);
-        if (urlMatch) inboxUrls.set(prId, urlMatch[0].replace(/[.,;:]+$/, ''));
-      }
+      addPrUrlEvidence(match[1]);
     }
   }
 
-  if (prMatches.size === 0) return 0;
+  if (prEvidence.size === 0) return 0;
 
   const projects = shared.getProjects(config);
   if (projects.length === 0 && !meta?.project?.name) return 0;
@@ -798,13 +816,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   // doesn't contain the link (gh pr create may have run in a sibling dispatch
   // whose stdout was rotated; the inbox note is the durable artifact).
   function extractPrUrl(prId) {
-    // Stop at backslash in addition to whitespace/quotes — raw JSONL encodes newlines as \n (literal
-    // backslash-n), so without this the regex would capture e.g. "pull/1804\n/usr/bin/bash".
-    const ghMatch = output.match(new RegExp(`https?://github\\.com/[^\\s"'\\)\\]\\\\]*?/pull/${prId}(?:[^\\s"'\\)\\]\\\\]*)`, 'i'));
-    if (ghMatch) return ghMatch[0].replace(/[.,;:]+$/, '');
-    const adoMatch = output.match(new RegExp(`https?://(?:dev\\.azure\\.com|[^/]+\\.visualstudio\\.com)[^\\s"'\\)\\]\\\\]*?pullrequest/${prId}(?:[^\\s"'\\)\\]\\\\]*)`, 'i'));
-    if (adoMatch) return adoMatch[0].replace(/[.,;:]+$/, '');
-    return inboxUrls.get(prId) || '';
+    return prEvidence.get(prId) || '';
   }
 
   const agentName = config.agents?.[agentId]?.name || agentId;
@@ -814,7 +826,7 @@ function syncPrsFromOutput(output, agentId, meta, config) {
   // Group new PRs by target file path
   const newPrsByPath = new Map(); // prPath -> [{ prId, newEntry }]
 
-  for (const prId of prMatches) {
+  for (const prId of prEvidence.keys()) {
     const targetProject = useCentral ? null : resolveProjectForPr(prId);
     const targetName = targetProject ? targetProject.name : '_central';
     const prPath = targetProject ? shared.projectPrPath(targetProject) : centralPrPath;

package/engine/queries.js

@@ -8,6 +8,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const shared = require('./shared');
+const steering = require('./steering');
 
 const { safeRead, safeReadDir, safeJson, safeWrite, getProjects, mutateJsonFileLocked,
   projectWorkItemsPath, projectPrPath, parseSkillFrontmatter, KB_CATEGORIES,
@@ -418,12 +419,18 @@ function getAgents(config) {
     // runtime tag next to the agent name.
     const runtime = shared.resolveAgentCli(a, config.engine || {});
     const inboxFiles = allInboxFiles.filter(f => f.includes(a.id));
+    let steeringInboxFiles = [];
+    try { steeringInboxFiles = steering.listUnreadSteeringMessages(a.id); } catch { steeringInboxFiles = []; }
     const s = getAgentStatus(a.id); // derives from dispatch.json
 
     let lastAction = 'Waiting for assignment';
     if (s.status === 'working') lastAction = s._runningToolDescription ? `Running: ${s._runningToolDescription}` : `Working: ${s.task}`;
     else if (s.status === 'done') lastAction = `Done: ${s.task}`;
     else if (s.status === 'error') lastAction = `Error: ${s.task}`;
+    else if (steeringInboxFiles.length > 0) {
+      const lastSteer = steeringInboxFiles[steeringInboxFiles.length - 1];
+      lastAction = `Pending steering: ${lastSteer.file} (${timeSince(lastSteer.createdAtMs)})`;
+    }
     else if (inboxFiles.length > 0) {
       const lastOutput = path.join(INBOX_DIR, inboxFiles[inboxFiles.length - 1]);
       try { lastAction = `Output: ${path.basename(lastOutput)} (${timeSince(fs.statSync(lastOutput).mtimeMs)})`; } catch { /* optional */ }
@@ -440,7 +447,7 @@ function getAgents(config) {
       _blockingToolCall: s._blockingToolCall || null,
       _warning: s._warning || null,
       _permissionMode: s._permissionMode || null,
-      chartered, inboxCount: inboxFiles.length
+      chartered, inboxCount: inboxFiles.length + steeringInboxFiles.length
     };
   });
 }
@@ -458,6 +465,11 @@ function getAgentDetail(id) {
   const inboxContents = safeReadDir(INBOX_DIR)
     .filter(f => f.includes(id))
     .map(f => ({ name: f, content: safeRead(path.join(INBOX_DIR, f)) || '' }));
+  try {
+    for (const entry of steering.listUnreadSteeringMessages(id)) {
+      inboxContents.push({ name: entry.file, content: entry.raw || '', type: 'steering' });
+    }
+  } catch { /* optional */ }
 
   let recentDispatches = [];
   try {

package/engine/shared.js

@@ -1073,6 +1073,9 @@ const PRD_MATERIALIZABLE = new Set([PRD_ITEM_STATUS.MISSING, PRD_ITEM_STATUS.UPD
 const PR_STATUS = { ACTIVE: 'active', MERGED: 'merged', ABANDONED: 'abandoned', CLOSED: 'closed', LINKED: 'linked' };
 // PRs eligible for polling (status/build/comment checks) — excludes terminal statuses
 const PR_POLLABLE_STATUSES = new Set([PR_STATUS.ACTIVE, PR_STATUS.LINKED]);
+const PR_PENDING_REASON = {
+  MISSING_BRANCH: 'missing_pr_branch',
+};
 
 // Watch statuses — engine-level persistent watches that survive restarts
 const WATCH_STATUS = { ACTIVE: 'active', PAUSED: 'paused', TRIGGERED: 'triggered', EXPIRED: 'expired' };
@@ -1661,6 +1664,10 @@ function parseAdoPrUrl(url) {
   };
 }
 
+function parsePrUrl(url) {
+  return parseGitHubPrUrl(url) || parseAdoPrUrl(url);
+}
+
 function getProjectPrScope(project) {
   if (!project) return '';
   const host = String(project.repoHost || '').toLowerCase();
@@ -1705,16 +1712,47 @@ function getPrDisplayId(value, fallbackPrNumber = null) {
   return typeof value === 'object' ? String(value?.id || '') : String(value || '');
 }
 
+function getPrScopeInfo(prRef, url = '') {
+  const isObjectRef = !!prRef && typeof prRef === 'object';
+  const rawUrl = url || (isObjectRef ? prRef.url || '' : String(prRef || ''));
+  const parsedUrl = parsePrUrl(rawUrl);
+  if (parsedUrl) return { ...parsedUrl, source: 'url' };
+  const rawId = isObjectRef ? (prRef.id || '') : String(prRef || '');
+  const canonical = parseCanonicalPrId(rawId);
+  return canonical ? { ...canonical, source: 'id' } : null;
+}
+
+function getPrProjectScopeMismatch(project, prRef, url = '') {
+  const projectScope = getProjectPrScope(project);
+  if (!projectScope) return null;
+  const refScope = getPrScopeInfo(prRef, url)?.scope || '';
+  if (!refScope) return null;
+  if (refScope === projectScope) return null;
+  const [projectHost, projectRest = ''] = projectScope.split(':');
+  const [refHost, refRest = ''] = refScope.split(':');
+  if (projectHost === refHost && projectHost === 'ado' && !project.prUrlBase) {
+    const projectParts = projectRest.split('/');
+    const refParts = refRest.split('/');
+    if (projectParts[0] === refParts[0] && projectParts[1] === refParts[1]) return null;
+  }
+  return { reason: 'pr_scope_mismatch', projectScope, prScope: refScope };
+}
+
+function isPrCompatibleWithProject(project, prRef, url = '') {
+  return !getPrProjectScopeMismatch(project, prRef, url);
+}
+
 function getCanonicalPrId(project, prRef, url = '') {
   const isObjectRef = !!prRef && typeof prRef === 'object';
   const rawId = isObjectRef ? (prRef.id || '') : String(prRef || '');
+  const rawUrl = url || (isObjectRef ? prRef.url || '' : String(prRef || ''));
+  const parsedUrl = parsePrUrl(rawUrl);
+  if (parsedUrl) return `${parsedUrl.scope}#${parsedUrl.prNumber}`;
   const canonical = parseCanonicalPrId(rawId);
   if (canonical) return `${canonical.scope}#${canonical.prNumber}`;
-  const parsedUrl = parseGitHubPrUrl(url || (isObjectRef ? prRef.url || '' : ''))
-    || parseAdoPrUrl(url || (isObjectRef ? prRef.url || '' : ''));
   const prNumber = getPrNumber(isObjectRef ? (prRef.prNumber ?? prRef.id ?? prRef.url) : prRef);
   if (prNumber == null) return rawId;
-  const scope = getProjectPrScope(project) || parsedUrl?.scope || '';
+  const scope = getProjectPrScope(project) || '';
   return scope ? `${scope}#${prNumber}` : `PR-${prNumber}`;
 }
 
@@ -1755,6 +1793,17 @@ function normalizePrRecord(pr, project = null) {
     pr.id = canonicalId;
     changed = true;
   }
+  const mismatch = getPrProjectScopeMismatch(project, pr, pr.url || '');
+  if (mismatch) {
+    const current = pr._invalidProjectScope || {};
+    if (current.reason !== mismatch.reason || current.projectScope !== mismatch.projectScope || current.prScope !== mismatch.prScope) {
+      pr._invalidProjectScope = mismatch;
+      changed = true;
+    }
+  } else if (Object.prototype.hasOwnProperty.call(pr, '_invalidProjectScope')) {
+    delete pr._invalidProjectScope;
+    changed = true;
+  }
   return changed;
 }
 
@@ -2255,7 +2304,7 @@ module.exports = {
   resolveAgentMaxBudget, resolveAgentBareMode,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
@@ -2273,6 +2322,9 @@ module.exports = {
   getProjectPrScope,
   getPrNumber,
   getPrDisplayId,
+  getPrScopeInfo,
+  getPrProjectScopeMismatch,
+  isPrCompatibleWithProject,
   getCanonicalPrId,
   findPrRecord,
   normalizePrRecord,

package/engine/steering.js

@@ -0,0 +1,187 @@
+/**
+ * engine/steering.js — Durable agent-scoped steering inbox helpers.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+
+const AGENTS_DIR = path.join(shared.MINIONS_DIR, 'agents');
+
+function agentInboxDir(agentId) {
+  return path.join(AGENTS_DIR, agentId, 'inbox');
+}
+
+function _createdAtFromPath(filePath, stat) {
+  const base = path.basename(filePath);
+  const m = base.match(/^steering-(\d+)/);
+  if (m) {
+    const n = Number(m[1]);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return stat?.mtimeMs || Date.now();
+}
+
+function _stripFrontmatter(raw) {
+  const text = String(raw || '');
+  if (!text.startsWith('---\n')) return text;
+  const end = text.indexOf('\n---\n', 4);
+  return end >= 0 ? text.slice(end + 5) : text;
+}
+
+function _frontmatterValue(raw, key) {
+  const text = String(raw || '');
+  if (!text.startsWith('---\n')) return null;
+  const end = text.indexOf('\n---\n', 4);
+  if (end < 0) return null;
+  const fm = text.slice(4, end).split(/\r?\n/);
+  const prefix = key + ':';
+  for (const line of fm) {
+    if (line.startsWith(prefix)) return line.slice(prefix.length).trim();
+  }
+  return null;
+}
+
+function _messageFromRaw(raw) {
+  let body = _stripFrontmatter(raw).trim();
+  const forwarded = body.match(/Original steering from human:\s*([\s\S]*)$/i);
+  if (forwarded) body = forwarded[1].trim();
+  return body;
+}
+
+function _readEntry(filePath, legacy = false) {
+  let stat;
+  try { stat = fs.statSync(filePath); } catch { return null; }
+  const raw = shared.safeRead(filePath);
+  const fmCreatedAtMs = Number(_frontmatterValue(raw, 'createdAtMs'));
+  const createdAtMs = Number.isFinite(fmCreatedAtMs) && fmCreatedAtMs > 0
+    ? fmCreatedAtMs
+    : _createdAtFromPath(filePath, stat);
+  return {
+    path: filePath,
+    file: path.basename(filePath),
+    createdAtMs,
+    createdAt: new Date(createdAtMs).toISOString(),
+    raw,
+    message: _messageFromRaw(raw),
+    legacy,
+  };
+}
+
+function _uniqueSteeringPath(inboxDir, createdAtMs) {
+  let filePath = path.join(inboxDir, `steering-${createdAtMs}.md`);
+  for (let i = 1; fs.existsSync(filePath); i++) {
+    filePath = path.join(inboxDir, `steering-${createdAtMs}-${i}.md`);
+  }
+  return filePath;
+}
+
+function writeSteeringMessage(agentId, message, opts = {}) {
+  const createdAtMs = Number(opts.createdAtMs) || Date.now();
+  const createdAt = new Date(createdAtMs).toISOString();
+  const inboxDir = agentInboxDir(agentId);
+  fs.mkdirSync(inboxDir, { recursive: true });
+  const filePath = _uniqueSteeringPath(inboxDir, createdAtMs);
+  const body = [
+    '---',
+    `createdAt: ${createdAt}`,
+    `createdAtMs: ${createdAtMs}`,
+    `source: ${opts.source || 'human'}`,
+    '---',
+    '',
+    String(message || '').trim(),
+    '',
+  ].join('\n');
+  shared.safeWrite(filePath, body);
+  return _readEntry(filePath);
+}
+
+function listUnreadSteeringMessages(agentId, opts = {}) {
+  const includeLegacy = opts.includeLegacy !== false;
+  const entries = [];
+  const inboxDir = agentInboxDir(agentId);
+  for (const file of shared.safeReadDir(inboxDir)) {
+    if (!/^steering-.*\.md$/i.test(file)) continue;
+    const entry = _readEntry(path.join(inboxDir, file), false);
+    if (entry) entries.push(entry);
+  }
+
+  if (includeLegacy) {
+    const legacyPath = path.join(AGENTS_DIR, agentId, 'steer.md');
+    const legacy = _readEntry(legacyPath, true);
+    if (legacy) entries.push(legacy);
+  }
+
+  entries.sort((a, b) => (a.createdAtMs - b.createdAtMs) || a.file.localeCompare(b.file));
+  return entries;
+}
+
+function buildPendingSteeringPrompt(agentId) {
+  const entries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+  if (entries.length === 0) return { entries, prompt: '' };
+
+  const sections = [
+    '## Pending instructions from prior session',
+    '',
+    'These human steering messages were not confirmed processed before the previous session ended. Address them before continuing with the task.',
+  ];
+  entries.forEach((entry, idx) => {
+    sections.push('', `### Message ${idx + 1} — ${entry.createdAt}`, '', entry.message.trim());
+  });
+  return { entries, prompt: sections.join('\n') };
+}
+
+function _eventTimestampMs(obj, observedAtMs) {
+  const value = obj?.timestamp || obj?.createdAt || obj?.created_at || obj?.time || obj?.data?.timestamp;
+  const parsed = value ? Date.parse(value) : NaN;
+  if (Number.isFinite(parsed)) return parsed;
+  return Number(observedAtMs) || Date.now();
+}
+
+function _isProcessEvidenceEvent(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  const type = String(obj.type || '');
+  if (type === 'assistant' || type === 'tool_use') return true;
+  if (type.startsWith('assistant.') || type.startsWith('tool.')) return true;
+  if (Array.isArray(obj.message?.content)) {
+    return obj.message.content.some(block => block?.type === 'text' || block?.type === 'tool_use');
+  }
+  return false;
+}
+
+function _processEvidenceTimes(rawOutput, observedAtMs) {
+  const times = [];
+  for (const line of String(rawOutput || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('{')) continue;
+    try {
+      const obj = JSON.parse(trimmed);
+      if (_isProcessEvidenceEvent(obj)) times.push(_eventTimestampMs(obj, observedAtMs));
+    } catch { /* ignore non-JSON output */ }
+  }
+  return times;
+}
+
+function ackProcessedSteeringMessages(agentId, pendingEntries, rawOutput, opts = {}) {
+  const entries = Array.isArray(pendingEntries) ? pendingEntries : [];
+  if (entries.length === 0) return [];
+  const times = _processEvidenceTimes(rawOutput, opts.observedAtMs);
+  if (times.length === 0) return [];
+
+  const acked = [];
+  for (const entry of entries) {
+    if (!entry?.path) continue;
+    if (!times.some(t => t > entry.createdAtMs)) continue;
+    shared.safeUnlink(entry.path);
+    acked.push(entry);
+  }
+  return acked;
+}
+
+module.exports = {
+  agentInboxDir,
+  writeSteeringMessage,
+  listUnreadSteeringMessages,
+  buildPendingSteeringPrompt,
+  ackProcessedSteeringMessages,
+};

package/engine/timeout.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
+const steering = require('./steering');
 
 const { safeRead, safeWrite, safeJson, mutateJsonFileLocked, getProjects, projectWorkItemsPath, log, ts,
   ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
@@ -78,25 +79,20 @@ function checkSteering(config) {
     // Skip if already being steered (prevents double-kill race)
     if (info._steeringMessage || info._steeringAt) continue;
 
-    const steerPath = path.join(AGENTS_DIR, info.agentId, 'steer.md');
-    let steerMtime;
-    try { steerMtime = fs.statSync(steerPath).mtimeMs; } catch { continue; } // ENOENT = no steering message
-
-    // Read and consume the message immediately — always delete to prevent stale messages
-    const message = safeRead(steerPath);
-    try { fs.unlinkSync(steerPath); } catch { /* cleanup */ }
-    if (!message) continue;
+    const alreadyPending = new Set((info._pendingSteeringFiles || []).map(entry => entry.path || entry));
+    const unread = steering.listUnreadSteeringMessages(info.agentId);
+    for (const empty of unread.filter(entry => !entry.message.trim())) {
+      shared.safeUnlink(empty.path);
+    }
+    const steerEntry = unread.find(entry => entry.message.trim() && !alreadyPending.has(entry.path));
+    if (!steerEntry) continue; // ENOENT/no agents/<id>/inbox/steering-*.md message
+    const message = steerEntry.message.trim();
 
     const sessionId = info.sessionId;
     if (!sessionId) {
-      // No session to resume — kill agent and deliver message via inbox for retry.
+      // No session to resume — kill agent and leave message unread in inbox for retry.
       // Previously this silently skipped for up to 5m then deleted the message (#627).
-      log('info', `Steering: no sessionId for ${info.agentId} (${id}) — killing and forwarding message to inbox`);
-
-      // Write steering message to agent inbox so it survives the retry
-      const inboxDir = path.join(AGENTS_DIR, info.agentId, 'inbox');
-      try { fs.mkdirSync(inboxDir, { recursive: true }); } catch {}
-      safeWrite(path.join(inboxDir, `steering-${Date.now()}.md`), `# Steering Message (Forwarded)\n\nOriginal steering from human:\n\n${message}\n`);
+      log('info', `Steering: no sessionId for ${info.agentId} (${id}) — killing and keeping unread message in inbox`);
 
       // Append to live output so user sees confirmation in the dashboard
       try {
@@ -115,6 +111,7 @@ function checkSteering(config) {
     // Set steering state BEFORE kill — close event may fire synchronously on some platforms
     info._steeringMessage = message;
     info._steeringSessionId = sessionId;
+    info._steeringEntry = steerEntry;
     info._steeringAt = Date.now();
 
     shared.killImmediate(info.proc);

package/engine.js

@@ -107,6 +107,7 @@ const { mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatc
 // ─── Timeout / Steering / Idle (extracted to engine/timeout.js) ──────────────
 
 const { checkTimeouts, checkSteering, checkIdleThreshold } = require('./engine/timeout');
+const steering = require('./engine/steering');
 
 // ─── Cleanup (extracted to engine/cleanup.js) ────────────────────────────────
 
@@ -295,6 +296,17 @@ function _buildAgentSpawnFlags(runtime, opts = {}) {
   return flags;
 }
 
+function ackPendingSteeringFiles(agentId, procInfo, rawOutput, observedAtMs = Date.now()) {
+  if (!procInfo?._pendingSteeringFiles?.length || !rawOutput) return;
+  const acked = steering.ackProcessedSteeringMessages(agentId, procInfo._pendingSteeringFiles, rawOutput, { observedAtMs });
+  if (acked.length === 0) return;
+
+  const ackedPaths = new Set(acked.map(entry => entry.path));
+  procInfo._pendingSteeringFiles = procInfo._pendingSteeringFiles.filter(entry => !ackedPaths.has(entry.path));
+  if (procInfo._pendingSteeringFiles.length === 0) delete procInfo._pendingSteeringFiles;
+  log('info', `Steering: ACKed ${acked.length} processed message(s) for ${agentId}`);
+}
+
 // Resolve dependency plan item IDs to their PR branches
 function resolveDependencyBranches(depIds, sourcePlan, project, config) {
   const results = []; // [{ branch, prId }]
@@ -436,9 +448,13 @@ async function spawnAgent(dispatchItem, config) {
   // and this avoids blocking 200ms of file reads behind 20-60s of git operations
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
-  const fullTaskPrompt = agentContext
-    ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPrompt}`
+  const pendingSteering = steering.buildPendingSteeringPrompt(agentId);
+  const taskPromptWithSteering = pendingSteering.prompt
+    ? `${pendingSteering.prompt}\n\n---\n\n${taskPrompt}`
     : taskPrompt;
+  const fullTaskPrompt = agentContext
+    ? `## Agent Context\n\n${agentContext}\n---\n\n## Your Task\n\n${taskPromptWithSteering}`
+    : taskPromptWithSteering;
   const tmpDir = path.join(ENGINE_DIR, 'tmp');
   if (!fs.existsSync(tmpDir)) fs.mkdirSync(tmpDir, { recursive: true });
   const safeId = id.replace(/[:\\/*?"<>|]/g, '-');
@@ -1036,6 +1052,8 @@ async function spawnAgent(dispatchItem, config) {
         }
       } catch { /* JSON parse — output may not be valid JSON */ }
     }
+
+    ackPendingSteeringFiles(agentId, procInfo, chunk);
   });
 
   proc.stderr.on('data', (data) => {
@@ -1058,13 +1076,17 @@ async function spawnAgent(dispatchItem, config) {
       try { shared.safeUnlink(path.join(AGENTS_DIR, agentId, 'session.json')); } catch {}
     }
 
-    // Check if this was a steering kill — re-spawn with resume
     const procInfo = activeProcesses.get(id);
+    ackPendingSteeringFiles(agentId, procInfo, stdout);
+
+    // Check if this was a steering kill — re-spawn with resume
     if (procInfo?._steeringMessage) {
       const steerMsg = procInfo._steeringMessage;
       const steerSessionId = procInfo._steeringSessionId;
+      const steerEntry = procInfo._steeringEntry;
       delete procInfo._steeringMessage;
       delete procInfo._steeringSessionId;
+      delete procInfo._steeringEntry;
 
       // Guard: can't resume without a session
       if (!steerSessionId) {
@@ -1156,7 +1178,14 @@ async function spawnAgent(dispatchItem, config) {
       // into the resumed process, it kills the resumed session. The kill watcher only exists
       // to handle cases where the original kill didn't take effect — once the process has
       // exited and the resume is spawned, _steeringAt must not be present.
-      activeProcesses.set(id, { proc: resumeProc, agentId, startedAt: procInfo.startedAt, sessionId: steerSessionId, lastRealOutputAt: Date.now() });
+      activeProcesses.set(id, {
+        proc: resumeProc,
+        agentId,
+        startedAt: procInfo.startedAt,
+        sessionId: steerSessionId,
+        lastRealOutputAt: Date.now(),
+        _pendingSteeringFiles: steerEntry ? [steerEntry] : (procInfo._pendingSteeringFiles || []),
+      });
 
       // Reset output buffers so post-completion parsing only sees the resumed session
       stdout = '';
@@ -1167,6 +1196,7 @@ async function spawnAgent(dispatchItem, config) {
         realActivityMap.set(id, Date.now());
         if (stdout.length < MAX_OUTPUT) stdout += chunk.slice(0, MAX_OUTPUT - stdout.length);
         try { fs.appendFileSync(liveOutputPath, chunk); } catch { /* optional */ }
+        ackPendingSteeringFiles(agentId, activeProcesses.get(id), chunk);
       });
       resumeProc.stderr.on('data', (data) => {
         const chunk = data.toString();
@@ -1370,7 +1400,13 @@ async function spawnAgent(dispatchItem, config) {
   // realActivityMap was already seeded immediately after runFile() returned (#W-mo25loq8kjer);
   // don't re-seed here — the stdout/stderr handlers above can already have updated it with
   // a fresher timestamp, and overwriting would clobber the real "last activity" signal.
-  activeProcesses.set(id, { proc, agentId, startedAt, sessionId: cachedSessionId });
+  activeProcesses.set(id, {
+    proc,
+    agentId,
+    startedAt,
+    sessionId: cachedSessionId,
+    _pendingSteeringFiles: pendingSteering.entries,
+  });
 
   updateAgentStatus(id, AGENT_STATUS.RUNNING, `Process spawned for ${agentId}`);
 
@@ -1984,7 +2020,7 @@ function clearPendingHumanFeedbackFlag(projectMeta, prId) {
   } catch (e) { log('warn', 'clear pending human feedback flag: ' + e.message); }
 }
 
-const PR_PENDING_MISSING_BRANCH = 'missing_pr_branch';
+const PR_PENDING_MISSING_BRANCH = shared.PR_PENDING_REASON.MISSING_BRANCH;
 
 function normalizePrBranch(value) {
   const raw = value == null ? '' : String(value).trim();
@@ -2117,6 +2153,7 @@ async function discoverFromPrs(config, project) {
   const knownAgents = new Set(Object.keys(config.agents || {}));
   for (const pr of prs) {
     if (pr.status !== PR_STATUS.ACTIVE || pr._contextOnly) continue;
+    if (!shared.isPrCompatibleWithProject(project, pr, pr.url || '')) continue;
     const prDisplayId = shared.getPrDisplayId(pr);
     const prCanonicalId = shared.getCanonicalPrId(project, pr, pr.url || '');
     if (activePrIds.has(prCanonicalId)) continue; // Skip PRs with active dispatch (prevent race)

package/package.json

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

@@ -72,8 +72,17 @@ I'll dispatch dallas to fix that bug.
 
 **Generic fallback:** For any action not listed below, include `"endpoint": "/api/..."` and `"params": {...}` to call the API directly. Example: `{"type": "custom-op", "endpoint": "/api/some/endpoint", "params": {"key": "value"}}`.
 
+**Required fields per action type — server rejects with an error if missing:**
+
+- `dispatch` (and aliases: `fix`, `implement`, `explore`, `review`, `test`): `title` is REQUIRED. `description` recommended. `project` REQUIRED when multiple projects are configured (server returns the list of known names if you guess wrong). For agent hints emit either `agents: ["dallas"]` (array, preferred) or `agent: "dallas"` (string — auto-promoted server-side). Unknown agent names error.
+- `build-and-test`: `pr` REQUIRED (number, ID, or URL).
+- `note`: `title` and `content` (or `description`) REQUIRED.
+- `knowledge`: `title`, `content`, and `category` REQUIRED. Valid categories: architecture, conventions, project-notes, build-reports, reviews.
+
+If you describe an action in prose ("I'll dispatch this..."), you MUST emit a matching `===ACTIONS===` block. The server detects prose claims without action blocks and surfaces a warning to the user — i.e., your false claim becomes visible. Either dispatch or don't promise to.
+
 Core action types:
-- **dispatch**: title, workType, priority (low/medium/high), agents[] (optional), project, description
+- **dispatch**: title (REQUIRED), workType, priority (low/medium/high), agents[] or agent (optional — both shapes accepted), project (REQUIRED when multi-project), description
   workTypes: `explore` (research/report only, NO PR), `ask` (answer/report, NO PR), `implement` (new code, PR REQUIRED), `fix` (bug fix, PR REQUIRED), `review` (code review, NO PR), `test` (tests, PR if new), `verify` (merge/build/maintenance, NO PR)
   If the user wants a design/architecture artifact committed through a PR, dispatch `implement` or `docs` rather than `explore`.
   When the user names a specific agent ("assign this to lambert"), put exactly that one name in `agents` (e.g. `"agents": ["lambert"]`). A single-agent assignment is hard-pinned by the server — it will queue for that agent only and skip the routing table. Use multi-agent arrays only when the user names multiple agents or asks for fan-out.