@yemi33/minions 0.1.1996 → 0.1.1997

package/engine/playbook.js

@@ -9,6 +9,7 @@ const os = require('os');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
+const { wrapUntrusted, buildSource } = require('./untrusted-fence');
 
 const { safeJson, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT, getProjectOrg } = shared;
 const { getConfig, getDispatch, getNotes, getAgentCharter, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
@@ -184,7 +185,9 @@ function resolveTaskContext(item, config) {
           const planPath = path.join(MINIONS_DIR, 'plans', planFile);
           try {
             const content = safeRead(planPath);
-            resolved.additionalContext += `\n\n## Referenced Plan: ${planFile} (created by ${agent.name})\n\n${truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan')}`;
+            const truncated = truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan');
+            const fenced = wrapUntrusted(truncated, buildSource('wi-reference', { path: `plans/${planFile}` }));
+            resolved.additionalContext += `\n\n## Referenced Plan: ${planFile} (created by ${agent.name})\n\n${fenced || truncated}`;
             resolved.referencedFiles.push(planPath);
             log('info', `Context resolution: found plan "${planFile}" by ${agent.name} for work item ${item.id}`);
           } catch (e) { log('warn', 'resolve plan context: ' + e.message); }
@@ -195,7 +198,9 @@ function resolveTaskContext(item, config) {
             const planPath = path.join(MINIONS_DIR, 'plans', match);
             try {
               const content = safeRead(planPath);
-              resolved.additionalContext += `\n\n## Referenced Plan: ${match}\n\n${truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan')}`;
+              const truncated = truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan');
+              const fenced = wrapUntrusted(truncated, buildSource('wi-reference', { path: `plans/${match}` }));
+              resolved.additionalContext += `\n\n## Referenced Plan: ${match}\n\n${fenced || truncated}`;
               resolved.referencedFiles.push(planPath);
               log('info', `Context resolution: found plan "${match}" (name match) for work item ${item.id}`);
             } catch (e) { log('warn', 'resolve plan fallback context: ' + e.message); }
@@ -218,7 +223,9 @@ function resolveTaskContext(item, config) {
           .sort().reverse();
         if (files.length > 0) {
           const content = safeRead(path.join(inboxDir, files[0]));
-          resolved.additionalContext += `\n\n## Referenced Notes by ${agent.name}: ${files[0]}\n\n${truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedNotesBytes, 'referenced notes')}`;
+          const truncated = truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedNotesBytes, 'referenced notes');
+          const fenced = wrapUntrusted(truncated, buildSource('inbox', { filename: files[0] }));
+          resolved.additionalContext += `\n\n## Referenced Notes by ${agent.name}: ${files[0]}\n\n${fenced || truncated}`;
           resolved.referencedFiles.push(path.join(inboxDir, files[0]));
           log('info', `Context resolution: found notes "${files[0]}" by ${agent.name} for work item ${item.id}`);
         }
@@ -237,7 +244,9 @@ function resolveTaskContext(item, config) {
       if (plans.length > 0) {
         const planPath = path.join(MINIONS_DIR, 'plans', plans[0]);
         const content = safeRead(planPath);
-        resolved.additionalContext += `\n\n## Referenced Plan (latest): ${plans[0]}\n\n${truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan')}`;
+        const truncated = truncateReferencedContext(content, ENGINE_DEFAULTS.maxReferencedPlanBytes, 'referenced plan');
+        const fenced = wrapUntrusted(truncated, buildSource('wi-reference', { path: `plans/${plans[0]}` }));
+        resolved.additionalContext += `\n\n## Referenced Plan (latest): ${plans[0]}\n\n${fenced || truncated}`;
         resolved.referencedFiles.push(planPath);
         log('info', `Context resolution: using latest plan "${plans[0]}" for work item ${item.id}`);
       }
@@ -309,6 +318,7 @@ const PLAYBOOK_REQUIRED_VARS = {
   'test':                 ['item_name'],
   'docs':                 ['item_id', 'item_name'],
   'setup':                ['item_id', 'item_name', 'project_path'],
+  'qa-validate':          ['item_id', 'item_name', 'qa_run_id'],
   'work-item':            ['item_id', 'item_name'],
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],
@@ -391,6 +401,69 @@ function resolvePlaybookPath(projectName, playbookType) {
   return path.join(PLAYBOOKS_DIR, `${playbookTypeName}.md`);
 }
 
+// W-mpeiwz6k0005bf34-c — Build the QA Run Context block that renderPlaybook
+// injects when vars.qa_run_id is set. Pure formatter: takes the runbook +
+// target snapshot the dispatcher captured (and stored on the work item meta)
+// and renders a compact, prompt-friendly summary. Heavy guards against
+// missing fields because dispatch callers may supply partial snapshots when
+// the managed-process state has rotated between schedule and dispatch.
+function buildQaValidateContextBlock({ runId, runbook, target, artifactsDir }) {
+  if (!runId) return '';
+  const lines = [];
+  lines.push('## QA Run Context');
+  lines.push('');
+  lines.push(`- **runId:** \`${runId}\``);
+  if (artifactsDir) lines.push(`- **artifactsDir:** \`${artifactsDir}\``);
+  lines.push('');
+
+  const rb = runbook && typeof runbook === 'object' ? runbook : null;
+  if (rb) {
+    lines.push('### Runbook');
+    lines.push(`- **id:** \`${rb.id || ''}\``);
+    if (rb.name) lines.push(`- **name:** ${rb.name}`);
+    if (Array.isArray(rb.steps) && rb.steps.length > 0) {
+      lines.push('- **steps:**');
+      rb.steps.forEach((s, i) => {
+        if (!s || typeof s !== 'object') return;
+        const desc = String(s.description || '').trim();
+        const cmd = s.command ? `  \`${String(s.command).trim()}\`` : '';
+        lines.push(`  ${i + 1}. ${desc}${cmd}`);
+      });
+    }
+    if (Array.isArray(rb.expectedArtifacts) && rb.expectedArtifacts.length > 0) {
+      lines.push('- **expectedArtifacts:**');
+      for (const a of rb.expectedArtifacts) {
+        if (!a || typeof a !== 'object') continue;
+        const type = String(a.type || 'other');
+        const label = String(a.label || '').trim();
+        const hint = a.path ? ` (\`${a.path}\`)` : '';
+        lines.push(`  - \`${type}\` — ${label}${hint}`);
+      }
+    }
+    lines.push('');
+  }
+
+  const t = target && typeof target === 'object' ? target : null;
+  if (t) {
+    lines.push('### Target (managed-process snapshot)');
+    if (t.name) lines.push(`- **name:** \`${t.name}\``);
+    if (t.owner_project) lines.push(`- **project:** \`${t.owner_project}\``);
+    if (typeof t.healthy === 'boolean') lines.push(`- **healthy:** ${t.healthy}`);
+    if (Array.isArray(t.ports) && t.ports.length > 0) lines.push(`- **ports:** ${t.ports.join(', ')}`);
+    if (t.attrs && typeof t.attrs === 'object') {
+      const base = t.attrs.base_url || t.attrs.baseUrl;
+      const framework = t.attrs.framework;
+      if (base) lines.push(`- **base_url:** ${base}`);
+      if (framework) lines.push(`- **framework:** ${framework}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Use this context to execute the runbook against the live target. Write the result sidecar to `agents/<your-id>/qa-run-result.json` before exit — the engine consumes it in `engine/lifecycle.js` and calls `qaRuns.completeRun(runId, ...)`.');
+
+  return lines.join('\n');
+}
+
 
 // ─── Playbook Renderer ──────────────────────────────────────────────────────
 
@@ -411,15 +484,20 @@ function renderPlaybook(type, vars) {
 
   const inertAppendices = [];
 
-  // Inject pinned context (always visible to agents) — capped at 4KB
+  // Inject pinned context (always visible to agents) — capped at 4KB.
+  // F5 (W-mpeklod3000we69c): wrap in <UNTRUSTED-INPUT> fence — human-edited
+  // file that ends up in every agent prompt.
   let pinnedContent = '';
   try { pinnedContent = fs.readFileSync(path.join(MINIONS_DIR, 'pinned.md'), 'utf8'); } catch { /* optional */ }
   if (pinnedContent) {
     if (pinnedContent.length > 4096) pinnedContent = pinnedContent.slice(0, 4096) + '\n\n_...pinned.md truncated (read full file if needed)_';
-    inertAppendices.push('\n\n---\n\n## Pinned Context (CRITICAL — READ FIRST)\n\n' + pinnedContent);
+    const fenced = wrapUntrusted(pinnedContent, buildSource('pinned-note', { path: 'pinned.md' }));
+    inertAppendices.push('\n\n---\n\n## Pinned Context (CRITICAL — READ FIRST)\n\n' + (fenced || pinnedContent));
   }
 
-  // Inject team notes (single injection point — not in buildAgentContext) — capped via ENGINE_DEFAULTS
+  // Inject team notes (single injection point — not in buildAgentContext) — capped via ENGINE_DEFAULTS.
+  // F5: wrap in <UNTRUSTED-INPUT> fence — notes.md is an LLM-consolidated mix
+  // of agent inbox notes (semi-trusted) and human edits.
   let notes = getNotes();
   if (notes) {
     if (Buffer.byteLength(notes, 'utf8') > ENGINE_DEFAULTS.maxNotesPromptBytes) {
@@ -430,15 +508,19 @@ function renderPlaybook(type, vars) {
       const budget = Math.max(0, ENGINE_DEFAULTS.maxNotesPromptBytes - Buffer.byteLength(footer, 'utf8'));
       notes = truncateTextBytes(recent, budget, '\n\n_...notes truncated_') + footer;
     }
-    inertAppendices.push('\n\n---\n\n## Team Notes (MUST READ)\n\n' + notes);
+    const fenced = wrapUntrusted(notes, buildSource('team-notes', { path: 'notes.md' }));
+    inertAppendices.push('\n\n---\n\n## Team Notes (MUST READ)\n\n' + (fenced || notes));
   }
 
   // Inject per-agent memory file (knowledge/agents/<agentId>.md) — personal
   // notebook curated by the consolidation pipeline. Capped at the same
   // notes budget; missing file degrades gracefully (silent skip).
+  // F5: fence — agent-authored inbox notes routed into this file; any agent
+  // could include attacker-controlled quoted material.
   const agentIdForMemory = vars.agent_id;
   if (agentIdForMemory && /^[a-z][a-z0-9-]{0,40}$/i.test(agentIdForMemory) && !String(agentIdForMemory).toLowerCase().startsWith('temp-')) {
-    const agentMemPath = path.join(MINIONS_DIR, 'knowledge', 'agents', `${String(agentIdForMemory).toLowerCase()}.md`);
+    const agentMemRel = `knowledge/agents/${String(agentIdForMemory).toLowerCase()}.md`;
+    const agentMemPath = path.join(MINIONS_DIR, agentMemRel);
     let agentMem = '';
     try { agentMem = fs.readFileSync(agentMemPath, 'utf8'); } catch { /* optional — file may not exist */ }
     if (agentMem && agentMem.trim()) {
@@ -448,7 +530,8 @@ function renderPlaybook(type, vars) {
         const budget = Math.max(0, ENGINE_DEFAULTS.maxNotesPromptBytes);
         agentMem = truncateTextBytes(recent, budget, '\n\n_...agent memory truncated_');
       }
-      inertAppendices.push('\n\n---\n\n## Personal Memory (your past learnings — MUST READ)\n\n' + agentMem);
+      const fenced = wrapUntrusted(agentMem, buildSource('agent-memory', { path: agentMemRel }));
+      inertAppendices.push('\n\n---\n\n## Personal Memory (your past learnings — MUST READ)\n\n' + (fenced || agentMem));
     }
   }
 
@@ -503,6 +586,23 @@ function renderPlaybook(type, vars) {
     } catch (e) { log('warn', `managed-spawn live-processes inject failed: ${e.message}`); }
   }
 
+  // W-mpeiwz6k0005bf34-c — opt-in qa-validate context block. Injected only
+  // when the dispatcher set vars.qa_run_id (truthy) from the work item's
+  // `meta.qaRunId`. Mirrors the managed_spawn hint pattern: the playbook is
+  // pure markdown; this block surfaces the live runbook + target snapshot so
+  // the agent doesn't need to re-resolve them from disk.
+  if (vars.qa_run_id) {
+    try {
+      const block = buildQaValidateContextBlock({
+        runId: vars.qa_run_id,
+        runbook: vars.qa_runbook,
+        target: vars.qa_target,
+        artifactsDir: vars.qa_artifacts_dir,
+      });
+      if (block) inertAppendices.push(block);
+    } catch (e) { log('warn', `qa-validate context render failed: ${e.message}`); }
+  }
+
   // Inject KB guardrail
   content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
   content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;
@@ -846,6 +946,15 @@ function buildBaseVars(agentId, config, project) {
 }
 
 function selectPlaybook(workType, item) {
+  // W-mpeiwz6k0005bf34-c — explicit playbook override via item.meta.playbook.
+  // Used by /api/qa/runbooks/run to route a `test`-type work item to the
+  // qa-validate playbook without minting a new work-type. Validated against
+  // PLAYBOOK_REQUIRED_VARS so a typo'd override falls through to work-item
+  // rather than mis-rendering.
+  const playbookOverride = (item?.meta?.playbook || item?.playbook || '').toString().trim();
+  if (playbookOverride && PLAYBOOK_REQUIRED_VARS[playbookOverride]) {
+    return playbookOverride;
+  }
   if (item?.branchStrategy === 'shared-branch' && (workType === WORK_TYPE.IMPLEMENT || workType === WORK_TYPE.IMPLEMENT_LARGE)) {
     return 'implement-shared';
   }
@@ -893,6 +1002,7 @@ module.exports = {
   selectPlaybook,
   buildBaseVars,
   buildPrDispatch,
+  buildQaValidateContextBlock,
   resolveTaskContext,
   // Repo host helpers (used by engine.js for buildProjectContext)
   getRepoHost,

package/engine/qa-runs.js

@@ -43,8 +43,23 @@ const TERMINAL_STATUSES = new Set([
 ]);
 
 // Allowed forward transitions. Anything not enumerated here is rejected.
+//
+// PR #2697 review fix (W-mpeiwz6k0005bf34-c — Ripley): the lifecycle hook in
+// engine/lifecycle.js parses the agent's qa-run-result.json sidecar and calls
+// completeRun({status: 'passed'|'failed'|'errored'}) directly. It never calls
+// markRunning, because the agent may crash before writing the sidecar (in
+// which case the hook still needs to mark the run errored from `pending`).
+// Allowing pending → {passed,failed,errored} keeps the production path from
+// throwing "illegal transition" inside the hook's try/catch and leaving the
+// run perma-pending. The state machine still rejects double-completion
+// (terminal → terminal) so race-y double-writes can't silently overwrite.
 const ALLOWED_TRANSITIONS = {
-  [QA_RUN_STATUS.PENDING]: new Set([QA_RUN_STATUS.RUNNING]),
+  [QA_RUN_STATUS.PENDING]: new Set([
+    QA_RUN_STATUS.RUNNING,
+    QA_RUN_STATUS.PASSED,
+    QA_RUN_STATUS.FAILED,
+    QA_RUN_STATUS.ERRORED,
+  ]),
   [QA_RUN_STATUS.RUNNING]: new Set([
     QA_RUN_STATUS.PASSED,
     QA_RUN_STATUS.FAILED,
@@ -259,6 +274,31 @@ function getRunsForWorkItem(wi) {
     });
 }
 
+/**
+ * Back-fill workItemId on an existing run record. Used by the qa-validate
+ * dispatch endpoint (dashboard.js handleQaRunbookRun) when the WI is created
+ * after the run record so the dashboard can join the two. No-op (returns
+ * null) when the run id is unknown.
+ *
+ * @param {string} id - run id
+ * @param {string|null} workItemId - work-item id (or null to clear)
+ * @returns {object|null} updated run, or null if not found
+ */
+function setRunWorkItemId(id, workItemId) {
+  if (!id) return null;
+  let captured = null;
+  mutateJsonFileLocked(qaRunsPath(), (runs) => {
+    if (!Array.isArray(runs)) runs = [];
+    const run = runs.find(r => r && r.id === id);
+    if (run) {
+      run.workItemId = workItemId || null;
+      captured = run;
+    }
+    return runs;
+  }, { defaultValue: [] });
+  return captured;
+}
+
 module.exports = {
   QA_RUN_STATUS,
   TERMINAL_STATUSES,
@@ -269,6 +309,7 @@ module.exports = {
   createRun,
   markRunning,
   completeRun,
+  setRunWorkItemId,
   getRun,
   listRuns,
   getRunsForWorkItem,

package/engine/queries.js

@@ -1401,18 +1401,31 @@ function getPrdInfo(config) {
   const items = allPrdItems;
   const total = items.length;
 
-  // Build work item lookup — work item ID = PRD item ID
+  // Build work item lookups:
+  //   wiById     — PRD-item-keyed (sourcePlan only) — used by status sync + plan timings below
+  //   allWiById  — every WI, used solely by countDistinctPrdItems() to resolve sibling
+  //                sub-WIs (e.g. review-followup WIs) back to their owning PRD item
+  //                so they don't masquerade as a 2nd PRD item in the aggregate guard (W-mpem52qn).
   const wiById = {};
+  const allWiById = {};
   for (const project of projects) {
     try {
       const workItems = readJsonNoRestore(projectWorkItemsPath(project)) || [];
-      for (const wi of workItems) { if (!wi?.id) { console.warn(`[queries] Skipping work item without id in ${project.name}:`, JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan) wiById[wi.id] = wi; }
+      for (const wi of workItems) {
+        if (!wi?.id) { console.warn(`[queries] Skipping work item without id in ${project.name}:`, JSON.stringify(wi).slice(0, 120)); continue; }
+        if (!allWiById[wi.id]) allWiById[wi.id] = wi;
+        if (wi.sourcePlan) wiById[wi.id] = wi;
+      }
     } catch { /* optional */ }
   }
   // Also check central work-items.json
   try {
     const centralWi = readJsonNoRestore(path.join(MINIONS_DIR, 'work-items.json')) || [];
-    for (const wi of centralWi) { if (!wi?.id) { console.warn('[queries] Skipping central work item without id:', JSON.stringify(wi).slice(0, 120)); continue; } if (wi.sourcePlan && !wiById[wi.id]) wiById[wi.id] = wi; }
+    for (const wi of centralWi) {
+      if (!wi?.id) { console.warn('[queries] Skipping central work item without id:', JSON.stringify(wi).slice(0, 120)); continue; }
+      if (!allWiById[wi.id]) allWiById[wi.id] = wi;
+      if (wi.sourcePlan && !wiById[wi.id]) wiById[wi.id] = wi;
+    }
   } catch { /* optional */ }
 
   // PR-to-PRD linking — derived from PR.prdItems (single source of truth).
@@ -1422,14 +1435,43 @@ function getPrdInfo(config) {
   const prById = {};
   for (const pr of allPrs) prById[pr.id] = pr;
 
+  // Set of every known PRD item ID across all scanned PRD JSON files. Used to
+  // distinguish "this itemId is a PRD item" from "this itemId is a sub-WI" when
+  // counting how many distinct PRD items a PR truly spans.
+  const prdItemIdSet = new Set();
+  for (const it of allPrdItems) { if (it && typeof it.id === 'string' && it.id) prdItemIdSet.add(it.id); }
+
+  // Resolve a PR's prdItems list to the Set of distinct PRD items it actually
+  // belongs to. A PRD item + N sibling sub-WIs (review-followups, decomposition
+  // children) all resolve to size 1 — they're one PRD item's PR. Only PRs that
+  // genuinely span 2+ distinct PRD items return size ≥ 2. (W-mpem52qn)
+  function countDistinctPrdItems(itemIds) {
+    const set = new Set();
+    for (const itemId of (itemIds || [])) {
+      if (typeof itemId !== 'string' || !itemId) continue;
+      if (prdItemIdSet.has(itemId)) { set.add(itemId); continue; }
+      const wi = allWiById[itemId];
+      if (!wi) continue;
+      // Sub-WI may link to its PRD item via parent_id (decomposition pattern at line 1444).
+      if (typeof wi.parent_id === 'string' && prdItemIdSet.has(wi.parent_id)) {
+        set.add(wi.parent_id);
+      }
+    }
+    return set;
+  }
+
   const prdToPr = {};
   const prLinks = shared.getPrLinks(); // { "PR-xxxx": ["P-xxxx", "P-yyyy"] }
   for (const [prId, itemIds] of Object.entries(prLinks)) {
     const pr = prById[prId];
-    // Skip aggregate / E2E PRs from per-item mapping — they link to multiple items
-    // (or are typed as verify) and would bleed through as duplicate entries on every
-    // constituent item. They are surfaced via renderE2eSection instead. (#1220)
-    if ((itemIds || []).length > 1 || pr?.itemType === 'verify' || pr?.title?.startsWith('[E2E]')) continue;
+    // Skip aggregate / E2E PRs from per-item mapping — they link to multiple
+    // PRD items (or are typed as verify) and would bleed through as duplicate
+    // entries on every constituent item. They are surfaced via renderE2eSection
+    // instead. (#1220) The aggregate check counts DISTINCT PRD items the PR
+    // resolves to, not raw itemIds.length: a PRD item + sibling review-followup
+    // sub-WIs all resolve to one PRD item and must still render. (W-mpem52qn)
+    const distinctPrdCount = countDistinctPrdItems(itemIds).size;
+    if (distinctPrdCount > 1 || pr?.itemType === 'verify' || pr?.title?.startsWith('[E2E]')) continue;
     const url = buildPrUrlFromId(prId, pr, projects);
     for (const itemId of (itemIds || [])) {
       if (!prdToPr[itemId]) prdToPr[itemId] = [];

package/engine/shared.js

@@ -1784,6 +1784,7 @@ const ENGINE_DEFAULTS = {
   maxReferencedNotesBytes: 5 * 1024, // cap referenced inbox note excerpts injected via task context resolution
   maxResolvedTaskContextBytes: 20 * 1024, // bound the total implicit context injected from referenced plans/notes
   maxNotesPromptBytes: 8 * 1024, // cap Team Notes injected into every playbook prompt
+  untrustedFenceMaxBytes: 64 * 1024, // F5 (W-mpeklod3000we69c): per-block cap for `<UNTRUSTED-INPUT>` fences in engine/untrusted-fence.js. 64KB is long enough for realistic PR comments / pinned notes / agent memory sections, short enough that a megabyte-bomb comment cannot blow up the prompt. Content above the cap is truncated INSIDE the fence with a `[truncated N more bytes]` marker so the agent still sees the provenance attribute.
   maxMeetingPromptBytes: 16 * 1024, // cap meeting findings/debate context injected into prompts
   maxMeetingHumanNotesBytes: 2 * 1024, // cap human note bullet lists injected into meeting prompts
   maxPipelineMeetingContextBytes: 16 * 1024, // cap aggregated meeting/dependency context for pipeline plan generation
@@ -2597,6 +2598,7 @@ const FAILURE_CLASS = {
   INVALID_KEEP_PROCESSES_SCHEMA: 'invalid-keep-processes-schema', // W-mp7i902u000l991f: keep-pids.json failed validation for a reason other than workdir (pids-missing, ttl-too-long, expires_at-missing, pids-too-many, port-invalid, etc.) — agent wrote the wrong shape; never retryable until they fix the file
   INVALID_MANAGED_SPAWN: 'invalid-managed-spawn', // P-7a3b1c92: agents/<id>/managed-spawn.json failed validator (bad schema, broken workdir, executable/env not on allowlist, healthcheck shape wrong). Engine refuses to spawn any spec — agent must fix file; never retryable as-is.
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
+  INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {
@@ -2608,7 +2610,7 @@ const ESCALATION_POLICY = {
 };
 
 // Structured completion protocol — fields agents must produce in ```completion blocks
-const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce'];
+const COMPLETION_FIELDS = ['status', 'summary', 'files_changed', 'tests', 'pr', 'not_changed', 'failure_class', 'retryable', 'needs_rerun', 'verdict', 'artifacts', 'nonce', 'securityFlags'];
 
 const DEFAULT_AGENT_METRICS = {
   tasksCompleted: 0, tasksErrored: 0,

package/engine/untrusted-fence.js

@@ -0,0 +1,184 @@
+/**
+ * engine/untrusted-fence.js — F5 (W-mpeklod3000we69c).
+ *
+ * Wraps human-authored / external content in
+ *   <UNTRUSTED-INPUT source="…">…</UNTRUSTED-INPUT>
+ * fences before splicing it into agent prompts. Pairs with the directive in
+ * `playbooks/shared-rules.md` and `prompts/cc-system.md` that teaches agents
+ * to treat fenced content as data, not instructions.
+ *
+ * Zero dependencies beyond `engine/shared` (for the ENGINE_DEFAULTS byte cap).
+ * Pure helpers — safe to call from poll-time, render-time, and consolidation
+ * paths. Source attributes are sanitized so attacker-influenced parts
+ * (PR comment author, file paths) cannot break out of the fence header.
+ *
+ * Contributors adding a new splice site that includes human-authored,
+ * external, or otherwise-untrusted content into a prompt MUST wrap it with
+ * `wrapUntrusted(content, source)` (or `wrapUntrustedBlock`) — see
+ * `docs/security.md` §5 and `CLAUDE.md` "F5" for the policy.
+ */
+
+const FENCE_OPEN_PREFIX = '<UNTRUSTED-INPUT';
+const FENCE_CLOSE = '</UNTRUSTED-INPUT>';
+const FENCE_CLOSE_ESCAPED = '</UNTRUSTED-INPUT-ESCAPED>';
+
+// Match any flavor of the closing tag that an attacker might try to inject:
+//   </UNTRUSTED-INPUT>        — bare closer
+//   </untrusted-input>        — lowercase
+//   </UNTRUSTED-INPUT >       — trailing space before '>'
+//   </UNTRUSTED-INPUT attr="x"> — attributes before '>'
+// The first capture group is empty/optional; we always rewrite to the canonical
+// escaped marker, dropping any pretend-attribute.
+const INNER_CLOSE_RE = /<\/UNTRUSTED-INPUT(?:\s[^>]*)?>/gi;
+
+function _shared() {
+  // Late require — keep this module loadable in isolated test contexts that
+  // bust `engine/shared` from require.cache between runs.
+  return require('./shared');
+}
+
+function _maxBytes() {
+  try {
+    const { ENGINE_DEFAULTS } = _shared();
+    const n = ENGINE_DEFAULTS && ENGINE_DEFAULTS.untrustedFenceMaxBytes;
+    if (typeof n === 'number' && n > 0) return n;
+  } catch { /* fall through */ }
+  return 64 * 1024;
+}
+
+function _truncateUtf8(str, maxBytes) {
+  const buf = Buffer.from(String(str), 'utf8');
+  if (buf.length <= maxBytes) return { text: String(str), truncatedBytes: 0 };
+  // Step back one byte at a time so we don't slice mid-codepoint. The decoder
+  // would emit a replacement char otherwise.
+  let cut = maxBytes;
+  while (cut > 0 && (buf[cut] & 0xC0) === 0x80) cut--;
+  const head = buf.slice(0, cut).toString('utf8');
+  return { text: head, truncatedBytes: buf.length - cut };
+}
+
+function _escapeInnerClosers(content) {
+  return String(content).replace(INNER_CLOSE_RE, FENCE_CLOSE_ESCAPED);
+}
+
+// Strip characters that would break out of the fence header's source="…"
+// attribute. Conservative whitelist — keep ASCII letters/digits and a small
+// set of punctuation that real source attributes need.
+function _sanitizeSourceToken(value) {
+  return String(value == null ? '' : value)
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/[<>"'&`]/g, '')
+    .replace(/\s+/g, '_')
+    .slice(0, 200);
+}
+
+/**
+ * Build a canonical source-attribute string. Keys are emitted in a stable,
+ * domain-specific order so source-inspection tests can assert literal output.
+ *
+ * Known shapes:
+ *   buildSource('pr-comment', { host, slug, number, author }) →
+ *     'pr-comment:<host>:<slug>#<number>:author=<author>'   (GitHub)
+ *   buildSource('pr-comment', { host:'ado', org, project, repo, number, author }) →
+ *     'pr-comment:ado:<org>/<project>/<repo>!<number>:author=<author>'
+ *   buildSource('pinned-note', { path }) → 'pinned-note:<path>'
+ *   buildSource('team-notes', { path }) → 'team-notes:<path>'
+ *   buildSource('agent-memory', { path }) → 'agent-memory:<path>'
+ *   buildSource('inbox', { filename }) → 'inbox:<filename>'
+ *   buildSource('wi-reference', { path }) → 'wi-reference:<path>'
+ *   buildSource('doc-content', { path }) → 'doc-content:<path>'
+ *
+ * Unknown shapes fall through to a generic `kind:k=v:k=v` ordering by key,
+ * still sanitized.
+ */
+function buildSource(kind, parts) {
+  const k = _sanitizeSourceToken(kind || 'untrusted');
+  if (!parts || typeof parts !== 'object') return k;
+
+  const get = (key) => parts[key] == null ? '' : _sanitizeSourceToken(parts[key]);
+
+  if (k === 'pr-comment') {
+    const host = get('host');
+    const author = get('author');
+    if (host === 'ado') {
+      const ref = [get('org'), get('project'), get('repo')].filter(Boolean).join('/');
+      const num = get('number');
+      const tail = num ? `${ref}!${num}` : ref;
+      return [k, host, tail, author && `author=${author}`].filter(Boolean).join(':');
+    }
+    const slug = get('slug');
+    const num = get('number');
+    const tail = num ? `${slug}#${num}` : slug;
+    return [k, host, tail, author && `author=${author}`].filter(Boolean).join(':');
+  }
+
+  if (k === 'pinned-note' || k === 'team-notes' || k === 'agent-memory'
+   || k === 'wi-reference' || k === 'doc-content' || k === 'doc-selection') {
+    return parts.path ? `${k}:${get('path')}` : k;
+  }
+  if (k === 'inbox') {
+    return parts.filename ? `${k}:${get('filename')}` : k;
+  }
+  if (k === 'wi-description') {
+    return parts.wi ? `${k}:${get('wi')}` : k;
+  }
+  if (k === 'human-feedback') {
+    const wi = get('wi');
+    const author = get('author');
+    return [k, wi, author && `author=${author}`].filter(Boolean).join(':');
+  }
+  if (k === 'ci-log') {
+    const host = get('host');
+    const job = get('job');
+    const run = get('run');
+    return [k, host, job, run].filter(Boolean).join(':');
+  }
+
+  // Generic fallback: stable key order via Object.keys (insertion order).
+  const segs = Object.keys(parts)
+    .map(key => {
+      const v = get(key);
+      return v ? `${_sanitizeSourceToken(key)}=${v}` : '';
+    })
+    .filter(Boolean);
+  return [k, ...segs].join(':');
+}
+
+/**
+ * Wrap `content` in an <UNTRUSTED-INPUT> fence. Returns '' if `content` is
+ * empty or whitespace-only — callers should never see an empty fence in
+ * their rendered prompt.
+ */
+function wrapUntrusted(content, source) {
+  const raw = content == null ? '' : String(content);
+  if (!raw.trim()) return '';
+
+  const escaped = _escapeInnerClosers(raw);
+  const cap = _maxBytes();
+  const { text, truncatedBytes } = _truncateUtf8(escaped, cap);
+  const body = truncatedBytes > 0
+    ? `${text}\n\n[truncated ${truncatedBytes} more bytes]`
+    : text;
+
+  const srcAttr = _sanitizeSourceToken(source || 'untrusted');
+  return `${FENCE_OPEN_PREFIX} source="${srcAttr}">${body}${FENCE_CLOSE}`;
+}
+
+/**
+ * Convenience: prepend `\n\n` so callers can splice without worrying about
+ * adjacency. Still returns '' for empty content.
+ */
+function wrapUntrustedBlock(content, source) {
+  const fenced = wrapUntrusted(content, source);
+  return fenced ? `\n\n${fenced}` : '';
+}
+
+module.exports = {
+  wrapUntrusted,
+  wrapUntrustedBlock,
+  buildSource,
+  // Constants exported for source-inspection tests.
+  FENCE_OPEN_PREFIX,
+  FENCE_CLOSE,
+  FENCE_CLOSE_ESCAPED,
+};

package/engine.js

@@ -4535,6 +4535,17 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     managed_spawn_ttl_minutes: item.meta && Number.isFinite(Number(item.meta.managed_spawn_ttl_minutes))
       ? Math.floor(Number(item.meta.managed_spawn_ttl_minutes))
       : '',
+    // W-mpeiwz6k0005bf34-c — opt-in qa-validate context. The dispatch handler
+    // POST /api/qa/runbooks/run stamps meta.qaRunId + meta.qaRunbook (full
+    // spec) + meta.qaTarget (managed-process snapshot) on the work item;
+    // renderPlaybook injects them as a QA Run Context block + the
+    // qa-validate playbook references these vars by template literal.
+    qa_run_id: (item.meta && item.meta.qaRunId) || '',
+    qa_runbook: (item.meta && item.meta.qaRunbook) || null,
+    qa_target: (item.meta && item.meta.qaTarget) || null,
+    qa_artifacts_dir: item.meta && item.meta.qaRunId
+      ? path.posix.join('engine', 'qa-artifacts', String(item.meta.qaRunId))
+      : '',
   };
   const cpResult = buildWorkItemDispatchVars(item, vars, config, {
     worktreePath: vars.worktree_path || root,

package/package.json

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