@yemi33/minions 0.1.1995 → 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-runbooks.js

@@ -0,0 +1,328 @@
+/**
+ * engine/qa-runbooks.js — W-mpeiwz6k0005bf34-a
+ *
+ * Per-project QA runbook persistence + CRUD helpers. Runbooks are test plans
+ * that travel with a project entry, mirroring the
+ * projects/<name>/pull-requests.json precedent. Each runbook is one JSON file
+ * at <MINIONS_DIR>/projects/<project>/runbooks/<id>.json.
+ *
+ * Pure persistence + validation only — this module does NOT spawn agents,
+ * dispatch runs, or touch UI. The dispatch endpoint, run records, and QA UI
+ * are intentionally deferred to follow-up plan items.
+ *
+ * All writes go through mutateJsonFileLocked per the repo convention. The id
+ * field is globally unique across projects (kebab-case, ≤64 chars) so reads
+ * by id can locate the file without the caller knowing the project.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+
+const RUNBOOKS_DIR = 'runbooks';
+
+const _KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// Mirrors shared.PROJECT_NAME_RE — kept local to avoid a require cycle and to
+// keep this module self-contained for path-traversal hardening (review feedback
+// on PR #2694: id/project params previously flowed into path.join without
+// validation, so `..%2F..%2F..%2Fconfig` could read MINIONS_DIR/config.json
+// and DELETE could wipe dispatch.json).
+const _PROJECT_NAME_RE = /^[a-zA-Z0-9_\-]{1,64}$/;
+
+const ARTIFACT_TYPES = ['screenshot', 'video', 'log', 'other'];
+
+const LIMITS = {
+  idMax: 64,
+  nameMax: 200,
+  targetNameMax: 200,
+  stepDescriptionMax: 500,
+  stepCommandMax: 2000,
+  artifactLabelMax: 200,
+  artifactPathMax: 500,
+  stepsMax: 20,
+  artifactsMax: 20,
+};
+
+function _projectsDir() {
+  return path.join(shared.MINIONS_DIR, 'projects');
+}
+
+function _runbooksDir(projectName) {
+  return path.join(_projectsDir(), projectName, RUNBOOKS_DIR);
+}
+
+function _runbookPath(projectName, id) {
+  return path.join(_runbooksDir(projectName), id + '.json');
+}
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+// Guards against path traversal at the module boundary. Mirrors the validation
+// saveRunbook already applies via validateRunbook(). Reject anything that isn't
+// a safe kebab-case id ≤ idMax chars so it can never reach path.join().
+function _isSafeId(id) {
+  return _isNonEmptyString(id) && id.length <= LIMITS.idMax && _KEBAB_RE.test(id);
+}
+
+// Guards against path traversal via the project segment. Project directory
+// names on disk follow shared.PROJECT_NAME_RE — anything outside that set
+// (path separators, `..`, null bytes, whitespace) cannot be a real project.
+function _isSafeProjectName(name) {
+  return _isNonEmptyString(name) && _PROJECT_NAME_RE.test(name);
+}
+
+/**
+ * Validate a runbook spec. Returns { ok: boolean, errors: string[] }.
+ * Never throws.
+ */
+function validateRunbook(spec) {
+  const errors = [];
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+    return { ok: false, errors: ['spec must be a plain object'] };
+  }
+
+  if (!_isNonEmptyString(spec.id)) {
+    errors.push('id is required (non-empty string)');
+  } else {
+    if (spec.id.length > LIMITS.idMax) errors.push('id exceeds ' + LIMITS.idMax + ' chars');
+    if (!_KEBAB_RE.test(spec.id)) errors.push('id must be kebab-case (a-z, 0-9, hyphens; no leading/trailing hyphen)');
+  }
+
+  if (!_isNonEmptyString(spec.name)) {
+    errors.push('name is required (non-empty string)');
+  } else if (spec.name.length > LIMITS.nameMax) {
+    errors.push('name exceeds ' + LIMITS.nameMax + ' chars');
+  }
+
+  if (!_isNonEmptyString(spec.project)) {
+    errors.push('project is required (non-empty string)');
+  } else if (!_PROJECT_NAME_RE.test(spec.project)) {
+    // Reject path-traversal / illegal project names at the schema layer so
+    // they never reach path.join in saveRunbook (review feedback on PR #2694:
+    // POST /api/qa/runbooks with project="../engine" previously wrote arbitrary
+    // JSON outside MINIONS_DIR).
+    errors.push('project must match ' + _PROJECT_NAME_RE.source + ' (alphanumerics, underscore, hyphen; 1-64 chars)');
+  }
+
+  if (!_isNonEmptyString(spec.targetName)) {
+    errors.push('targetName is required (non-empty string)');
+  } else if (spec.targetName.length > LIMITS.targetNameMax) {
+    errors.push('targetName exceeds ' + LIMITS.targetNameMax + ' chars');
+  }
+
+  if (!Array.isArray(spec.steps)) {
+    errors.push('steps must be an array');
+  } else {
+    if (spec.steps.length > LIMITS.stepsMax) {
+      errors.push('steps exceeds max of ' + LIMITS.stepsMax);
+    }
+    for (let i = 0; i < spec.steps.length; i++) {
+      const s = spec.steps[i];
+      if (!s || typeof s !== 'object' || Array.isArray(s)) {
+        errors.push('steps[' + i + '] must be an object');
+        continue;
+      }
+      if (!_isNonEmptyString(s.description)) {
+        errors.push('steps[' + i + '].description is required (non-empty string)');
+      } else if (s.description.length > LIMITS.stepDescriptionMax) {
+        errors.push('steps[' + i + '].description exceeds ' + LIMITS.stepDescriptionMax + ' chars');
+      }
+      if (s.command !== undefined && s.command !== null) {
+        if (typeof s.command !== 'string') {
+          errors.push('steps[' + i + '].command must be a string when present');
+        } else if (s.command.length > LIMITS.stepCommandMax) {
+          errors.push('steps[' + i + '].command exceeds ' + LIMITS.stepCommandMax + ' chars');
+        }
+      }
+    }
+  }
+
+  if (!Array.isArray(spec.expectedArtifacts)) {
+    errors.push('expectedArtifacts must be an array');
+  } else {
+    if (spec.expectedArtifacts.length > LIMITS.artifactsMax) {
+      errors.push('expectedArtifacts exceeds max of ' + LIMITS.artifactsMax);
+    }
+    for (let i = 0; i < spec.expectedArtifacts.length; i++) {
+      const a = spec.expectedArtifacts[i];
+      if (!a || typeof a !== 'object' || Array.isArray(a)) {
+        errors.push('expectedArtifacts[' + i + '] must be an object');
+        continue;
+      }
+      if (!_isNonEmptyString(a.type) || !ARTIFACT_TYPES.includes(a.type)) {
+        errors.push('expectedArtifacts[' + i + '].type must be one of: ' + ARTIFACT_TYPES.join(', '));
+      }
+      if (!_isNonEmptyString(a.label)) {
+        errors.push('expectedArtifacts[' + i + '].label is required (non-empty string)');
+      } else if (a.label.length > LIMITS.artifactLabelMax) {
+        errors.push('expectedArtifacts[' + i + '].label exceeds ' + LIMITS.artifactLabelMax + ' chars');
+      }
+      if (a.path !== undefined && a.path !== null) {
+        if (typeof a.path !== 'string') {
+          errors.push('expectedArtifacts[' + i + '].path must be a string when present');
+        } else if (a.path.length > LIMITS.artifactPathMax) {
+          errors.push('expectedArtifacts[' + i + '].path exceeds ' + LIMITS.artifactPathMax + ' chars');
+        }
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function _readRunbookFile(filePath) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); }
+  catch (_e) { return null; }
+  try { return JSON.parse(raw); }
+  catch (_e) { return null; }
+}
+
+function _listProjectNames() {
+  const dir = _projectsDir();
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (_e) { return []; }
+  return entries.filter(e => e.isDirectory()).map(e => e.name);
+}
+
+/**
+ * List runbooks across all projects, or filtered to a single project. Each
+ * returned record is the parsed file contents (already includes id + project
+ * + timestamps).
+ */
+function listRunbooks(project) {
+  let projects;
+  if (project === undefined || project === null || project === '') {
+    projects = _listProjectNames();
+  } else {
+    // Hardened: reject traversal/illegal project names instead of letting them
+    // flow into path.join (review feedback on PR #2694).
+    if (!_isSafeProjectName(project)) return [];
+    projects = [project];
+  }
+  const out = [];
+  for (const name of projects) {
+    const dir = _runbooksDir(name);
+    let files;
+    try { files = fs.readdirSync(dir); }
+    catch (_e) { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue;
+      const parsed = _readRunbookFile(path.join(dir, f));
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    }
+  }
+  return out;
+}
+
+/**
+ * Find a runbook by globally-unique id. Returns the parsed record or null.
+ */
+function getRunbook(id) {
+  // Hardened: reject traversal ids before they can reach path.join + existsSync
+  // (review feedback on PR #2694).
+  if (!_isSafeId(id)) return null;
+  for (const name of _listProjectNames()) {
+    const filePath = _runbookPath(name, id);
+    if (fs.existsSync(filePath)) {
+      return _readRunbookFile(filePath);
+    }
+  }
+  return null;
+}
+
+/**
+ * Locate the project that currently owns id, or null if not present.
+ */
+function _findOwningProject(id) {
+  for (const name of _listProjectNames()) {
+    if (fs.existsSync(_runbookPath(name, id))) return name;
+  }
+  return null;
+}
+
+/**
+ * Create or update a runbook. Sets createdAt on first save and updatedAt on
+ * every save. Throws on validation failure. Rejects cross-project renames —
+ * if id already exists under a different project, the caller must
+ * deleteRunbook(id) first.
+ */
+function saveRunbook(spec) {
+  const v = validateRunbook(spec);
+  if (!v.ok) {
+    const err = new Error('invalid runbook: ' + v.errors.join('; '));
+    err.validationErrors = v.errors;
+    throw err;
+  }
+  const existingProject = _findOwningProject(spec.id);
+  if (existingProject && existingProject !== spec.project) {
+    throw new Error('runbook id "' + spec.id + '" already exists under project "' + existingProject + '" — delete it before saving under "' + spec.project + '"');
+  }
+
+  const filePath = _runbookPath(spec.project, spec.id);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const nowIso = new Date().toISOString();
+  const result = shared.mutateJsonFileLocked(filePath, (data) => {
+    const prior = (data && typeof data === 'object' && !Array.isArray(data)) ? data : {};
+    return {
+      id: spec.id,
+      name: spec.name,
+      project: spec.project,
+      targetName: spec.targetName,
+      steps: spec.steps.map(s => {
+        const out = { description: s.description };
+        if (typeof s.command === 'string' && s.command.length > 0) out.command = s.command;
+        return out;
+      }),
+      expectedArtifacts: spec.expectedArtifacts.map(a => {
+        const out = { type: a.type, label: a.label };
+        if (typeof a.path === 'string' && a.path.length > 0) out.path = a.path;
+        return out;
+      }),
+      createdAt: _isNonEmptyString(prior.createdAt) ? prior.createdAt : nowIso,
+      updatedAt: nowIso,
+    };
+  }, { defaultValue: {} });
+  return result;
+}
+
+/**
+ * Remove a runbook by id. No-op when the id is not found. Returns true when
+ * a file was removed.
+ *
+ * Coordination: acquires the runbook's lock via withFileLock so a concurrent
+ * saveRunbook can't be mid-rename when we unlink. The unlink happens inside
+ * the lock callback (single fs call — keeps the callback synchronous and
+ * fast per the repo convention).
+ */
+function deleteRunbook(id) {
+  // Hardened: reject traversal ids before they can reach _findOwningProject /
+  // path.join / unlink (review feedback on PR #2694).
+  if (!_isSafeId(id)) return false;
+  const owning = _findOwningProject(id);
+  if (!owning) return false;
+  const filePath = _runbookPath(owning, id);
+  shared.withFileLock(filePath + '.lock', () => {
+    try { fs.unlinkSync(filePath); } catch (_e) { /* already gone */ }
+    try { fs.unlinkSync(filePath + '.backup'); } catch (_e) { /* optional */ }
+  });
+  return true;
+}
+
+module.exports = {
+  ARTIFACT_TYPES,
+  LIMITS,
+  validateRunbook,
+  listRunbooks,
+  getRunbook,
+  saveRunbook,
+  deleteRunbook,
+  // internals exposed for testing
+  _runbookPath,
+  _runbooksDir,
+};

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,