@yemi33/minions 0.1.2424 → 0.1.2426

package/engine/playbook.js

@@ -29,30 +29,43 @@ function getRepoHost(project) {
   return project?.repoHost || 'ado';
 }
 
-function getPrCreateInstructions(project) {
+function getPrCreateInstructions(project, config) {
   const host = getRepoHost(project);
   const repoId = project?.repositoryId || '';
+  // W-mrtdy7xv — createPrsAsDraft: when ON, tell agents to open the PR
+  // as a draft (host-aware). Per-project-overridable (W-mrxv648b): a project
+  // can opt IN or OUT of draft PRs independent of the fleet-wide engine flag.
+  // Resolved via shared.resolveCreatePrsAsDraft(project, engine): explicit
+  // per-project boolean wins → else engine flag → else ENGINE_DEFAULTS (false).
+  const createPrsAsDraft = shared.resolveCreatePrsAsDraft(project, config?.engine);
   if (host === 'github') {
     const org = getProjectOrg(project);
     const repo = project?.repoName || '';
     const mainBranch = project?.localPath ? shared.resolveMainBranch(project.localPath, project.mainBranch) : (project?.mainBranch || 'main');
+    const draftFlag = createPrsAsDraft ? ' --draft' : '';
     return `Use \`gh pr create\` to create a pull request:\n` +
-      `- Write the PR description to a temporary Markdown file, then run: \`gh pr create --base ${mainBranch} --head <your-branch> --title "PR title" --body-file <body-file.md> --repo ${org}/${repo}\`\n` +
+      `- Write the PR description to a temporary Markdown file, then run: \`gh pr create --base ${mainBranch} --head <your-branch> --title "PR title" --body-file <body-file.md> --repo ${org}/${repo}${draftFlag}\`\n` +
       `- Always set --base to \`${mainBranch}\` (the main branch)\n` +
       `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
       `- Use --head to specify your feature branch name\n` +
-      `- Include a meaningful --title and body file describing the changes`;
+      (createPrsAsDraft ? `- Open the PR as a DRAFT: include the \`--draft\` flag exactly as shown above (the operator has "Create PRs as draft" enabled)\n` : '') +
+      `- Include a meaningful --title and body file describing the changes\n` +
+      `- If this PR contains a meaningful VISUAL/UI change (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), proactively capture + EMBED screenshots in the body — BEFORE/AFTER for fixes, AFTER-only for new UI. Publish PNGs as assets on a per-PR prerelease (\`gh release create pr-<num>-visual … --prerelease\`, or \`gh release upload … --clobber\` on re-dispatch) with a per-command \`GH_TOKEN\` for the ${org} account (NEVER \`gh auth switch\`), resolve each \`browser_download_url\`, and reference it as \`![view (after)](url)\`. Never \`git add\` a PNG; skip + record on failure. Full recipe: the "Screenshot handling" section of the PR description audit.`;
   }
   // Default: Azure DevOps — prefer `az` CLI first, ADO REST API as fallback
   const adoOrg = project?.adoOrg || '';
   const adoProject = project?.adoProject || '';
   const repoName = project?.repoName || '';
   const mainBranch = project?.localPath ? shared.resolveMainBranch(project.localPath, project.mainBranch) : (project?.mainBranch || 'main');
+  const adoDraftFlag = createPrsAsDraft ? ' --draft true' : '';
   return `For Azure DevOps, use the \`az\` CLI first to create a pull request:\n` +
     `- Run \`az devops configure --defaults organization=https://dev.azure.com/${adoOrg} project="${adoProject}"\` once per session if defaults are not yet set\n` +
-    `- Then: \`az repos pr create --repository "${repoName}" --source-branch <your-branch> --target-branch ${mainBranch} --title "PR title" --description @<body-file.md>\`\n` +
+    `- Then: \`az repos pr create --repository "${repoName}" --source-branch <your-branch> --target-branch ${mainBranch} --title "PR title" --description @<body-file.md>${adoDraftFlag}\`\n` +
     `- Use \`@<file>\` syntax for \`--description\` so Markdown, quotes, and newlines pass safely\n` +
-    `- Always set --target-branch to \`${mainBranch}\` (the main branch)\n\n` +
+    `- Always set --target-branch to \`${mainBranch}\` (the main branch)\n` +
+    (createPrsAsDraft ? `- Open the PR as a DRAFT: include \`--draft true\` exactly as shown above (the operator has "Create PRs as draft" enabled). For the REST API fallback, set \`"isDraft": true\` in the request body\n` : '') +
+    `- If this PR contains a meaningful VISUAL/UI change (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), proactively capture + EMBED screenshots in the description — BEFORE/AFTER for fixes, AFTER-only for new UI. Upload via \`PUT .../pullRequests/<id>/attachments/<filename>\` with the PNG bytes and reference the returned URL. Save PNGs under \`agents/<id>/screenshots/\` only; never \`git add\` a PNG; skip + record on failure. Full recipe: the "Screenshot handling" section of the PR description audit\n` +
+    `\n` +
     `If \`az\` is unavailable, fall back to the ADO REST API: get a token with \`az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv\` and \`POST .../_apis/git/repositories/${repoId}/pullrequests?api-version=7.1\` (Bearer auth). Do not use \`gh\` for Azure DevOps repositories.`;
 }
 
@@ -415,7 +428,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'],
+  'qa-validate':          ['item_id', 'item_name', 'qa_run_id', 'qa_artifacts_dir', 'qa_result_sidecar'],
   // P-e6b3c2d8 — QA Session SETUP phase. Required vars are session
   // identification + target kind + flows + the deterministic managed-spawn
   // name the engine joins back to the session on. Conditional target_*
@@ -426,11 +439,11 @@ const PLAYBOOK_REQUIRED_VARS = {
   // flows + the live managed-spawn name + the runner adapter's
   // generateBrief() output. The brief is computed at render time by
   // engine.js (lazy-required qa-sessions + qa-runners + managed-spawn).
-  'qa-session-draft':     ['session_id', 'flows_raw', 'managed_spawn_name', 'runner_brief'],
+  'qa-session-draft':     ['session_id', 'flows_raw', 'managed_spawn_name', 'managed_spawn_lookup_url', 'qa_test_dir', 'runner_brief'],
   // P-f9a2e1b4 — QA Session EXECUTE phase. Required vars are session id +
   // live managed-spawn name + executeBrief() output + the qa-runs record id
   // (the agent stamps it on the result sidecar so lifecycle.js can ingest it).
-  'qa-session-execute':   ['session_id', 'managed_spawn_name', 'runner_execute_brief', 'qa_run_id'],
+  'qa-session-execute':   ['session_id', 'managed_spawn_name', 'managed_spawn_lookup_url', 'runner_execute_brief', 'qa_run_id', 'qa_artifacts_dir', 'qa_result_sidecar'],
   'work-item':            ['item_id', 'item_name'],
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],
@@ -443,6 +456,31 @@ const LIVE_VALIDATION_DEFERRED_PLAYBOOKS = new Set([
   'build-fix-complex',
 ]);
 
+// W-mrtdmtwq000kf391 — playbooks whose completion can open or update a
+// Minions-authored PR body. Only these dispatches get the "Repo harnesses used"
+// PR-body appendix, AND only when the work item's resolved PR contract actually
+// produces/updates a PR (see the `skip_pr` / `shared_branch` gates at the
+// injection site). Review/explore/ask/plan/meeting dispatches post comments or
+// produce artifacts rather than authoring a PR body, so they are excluded.
+//
+// This set is aligned with the real per-playbook PR contract, NOT a loose
+// name allowlist (reviewer BLOCKING, PR #898):
+//   - `setup` (playbooks/setup.md) explicitly produces NO PR — excluded.
+//   - `build-and-test` (playbooks/build-and-test.md) is read-only ("Do not
+//     create pull requests or push commits") — excluded.
+//   - `test` (playbooks/test.md) CAN create a PR when it changes files — included
+//     (the fenced block is a no-op when the dispatch opens no PR, since the agent
+//     only appends it to a PR body it actually authors).
+const PR_AUTHORING_PLAYBOOKS = new Set([
+  'implement',
+  'work-item',
+  'fix',
+  'build-fix-complex',
+  'verify',
+  'docs',
+  'test',
+]);
+
 /**
  * Validate that all required template variables for a playbook type are present
  * and non-empty in the provided vars object.
@@ -530,13 +568,14 @@ function resolvePlaybookPath(projectName, playbookType) {
 // 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 }) {
+function buildQaValidateContextBlock({ runId, runbook, target, artifactsDir, resultSidecar }) {
   if (!runId) return '';
   const lines = [];
   lines.push('## QA Run Context');
   lines.push('');
   lines.push(`- **runId:** \`${runId}\``);
   if (artifactsDir) lines.push(`- **artifactsDir:** \`${artifactsDir}\``);
+  if (resultSidecar) lines.push(`- **resultSidecar:** \`${resultSidecar}\``);
   lines.push('');
 
   const rb = runbook && typeof runbook === 'object' ? runbook : null;
@@ -582,7 +621,7 @@ function buildQaValidateContextBlock({ runId, runbook, target, artifactsDir }) {
     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, ...)`.');
+  lines.push(`Use this context to execute the runbook against the live target. Write the result sidecar to \`${resultSidecar || 'the injected qa_result_sidecar path'}\` before exit — the engine consumes it in \`engine/lifecycle.js\` and calls \`qaRuns.completeRun(runId, ...)\`.`);
 
   return lines.join('\n');
 }
@@ -744,6 +783,80 @@ function renderPlaybook(type, vars) {
     }
   }
 
+  // Reserved deterministic review-lesson recall (P-a6137579). A dedicated
+  // project + audience path, independent of the generic memory budget above and
+  // gated on its own feature flag. Review-learning records are globally excluded
+  // from generic recall, so with recall off (capture-only) the rendered prompt
+  // is unchanged with respect to those records. Only dispatches with a resolved
+  // project context are eligible; projectless CC / central work get no section.
+  if (projectName && features.isFeatureOn('review-learning-recall', configEarly)) {
+    try {
+      const applicable = memoryRetrieval.retrieveApplicableReviewLearnings({
+        title: vars.item_name || vars.pr_title || '',
+        description: vars.item_description || vars.task_description || vars.pr_description || '',
+        type: vars.work_type || type,
+        project: projectName,
+        agent: vars.agent_id || '',
+        failureClass: vars.failure_class || '',
+        sourcePlan: vars.source_plan || '',
+        references: vars.references || '',
+        prTitle: vars.pr_title || '',
+        prBranch: vars.pr_branch || '',
+      });
+      memoryStore.recordRetrievalRun({
+        workItemId: vars.item_id || null,
+        dispatchId: vars.task_id || null,
+        project: projectName,
+        agent: vars.agent_id || null,
+        retrievalKind: 'review-learning',
+        query: [...applicable.hints.files, ...applicable.hints.symbols, ...applicable.hints.tags].join(' '),
+        candidateCount: applicable.candidates.length,
+        selectedCount: applicable.selected.length,
+        selectedBytes: applicable.bytes,
+        durationMs: applicable.durationMs,
+        selectedIds: applicable.selectedIds,
+        decisionTrace: applicable.decisionTrace,
+      });
+      // P-bfc75585 — per-lesson `retrieved` lifecycle events. The retrieval run
+      // above records the aggregate selection; these events give the per-lesson
+      // audit trail that the completion's reviewLearningApplications are matched
+      // against. Deterministic event keys (dispatchId + memoryId) keep re-renders
+      // idempotent. Best-effort: an audit write must never break prompt render.
+      for (const record of applicable.selected || []) {
+        if (!record || !record.id) continue;
+        try {
+          memoryStore.recordMemoryLifecycleEvent({
+            eventType: 'retrieved',
+            memoryId: record.id,
+            findingKey: record.sourceRef || null,
+            project: projectName,
+            agent: vars.agent_id || null,
+            area: record.metadata?.area || 'general',
+            disposition: record.metadata?.disposition || null,
+            workItemId: vars.item_id || null,
+            dispatchId: vars.task_id || null,
+            identity: record.id,
+            metadata: {
+              audience: record.metadata?.audience || 'project-team',
+              retrievalKind: 'review-learning',
+            },
+          });
+        } catch (eventErr) {
+          log('warn', `Review-learning retrieved-event failed for ${record.id}: ${eventErr.message}`);
+        }
+      }
+      if (applicable.text) {
+        const fenced = wrapUntrusted(
+          applicable.text,
+          buildSource('review-learning', { item: vars.item_id || vars.task_id || 'unknown' })
+        );
+        inertAppendices.push('\n\n---\n\n## Applicable Prior Review Lessons (task-selected; verify against live code)\n\n' + (fenced || applicable.text));
+      }
+    } catch (e) {
+      log('warn', `Review-learning recall failed for ${vars.item_id || vars.task_id || type}: ${e.message}`);
+    }
+  }
+
   // 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.
@@ -792,19 +905,33 @@ function renderPlaybook(type, vars) {
   // there is nothing to conflict with). Bounded discovery (nearest-applicable
   // walk-up, byte-capped) lives in engine/claude-md-context.js. Degrades
   // silently on any error.
+  //
+  // These resolved facts (runtime, bare mode, propagation flag, and the ACTUAL
+  // injected file list) are hoisted so the "Repo harnesses used" PR-body section
+  // below reports the same resolved reality the engine actually injected, rather
+  // than re-discovering statically (reviewer BLOCKING, PR #898).
+  const harnessAgentCfg = configEarly?.agents?.[vars.agent_id] || null;
+  const harnessCliName = vars.runtime_cli || shared.resolveAgentCli(harnessAgentCfg, configEarly?.engine);
+  const harnessBareMode = shared.resolveAgentBareMode(harnessAgentCfg, configEarly?.engine);
+  let harnessClaudeMdCtx = null;
+  try { harnessClaudeMdCtx = require('./claude-md-context'); } catch { /* optional */ }
+  const runtimeNativeClaudeMd = harnessClaudeMdCtx
+    ? !!harnessClaudeMdCtx.runtimeAutoDiscoversClaudeMd(harnessCliName) : false;
+  const propagateClaudeMd = shared.resolvePropagateClaudeMdForNonClaudeRuntimes(matchedProject, configEarly?.engine);
+  let claudeMdInjectedFiles = [];
   try {
-    const claudeMdCtx = require('./claude-md-context');
-    const cliName = vars.runtime_cli || shared.resolveAgentCli(null, configEarly?.engine);
     const projectRoot = matchedProject?.localPath;
     if (projectRoot
-        && !claudeMdCtx.runtimeAutoDiscoversClaudeMd(cliName)
-        && shared.resolvePropagateClaudeMdForNonClaudeRuntimes(matchedProject, configEarly?.engine)) {
+        && harnessClaudeMdCtx
+        && !runtimeNativeClaudeMd
+        && propagateClaudeMd) {
       const pathHints = Array.isArray(vars.claude_md_path_hints) ? vars.claude_md_path_hints : [];
-      const { block } = claudeMdCtx.buildClaudeMdPropagationBlock({
+      const { block, files } = harnessClaudeMdCtx.buildClaudeMdPropagationBlock({
         projectRoot,
         pathHints,
         maxBytes: ENGINE_DEFAULTS.maxNotesPromptBytes,
       });
+      claudeMdInjectedFiles = Array.isArray(files) ? files : [];
       if (block) {
         const fenced = wrapUntrusted(block, buildSource('project-instructions', { path: 'CLAUDE.md' }));
         inertAppendices.push(
@@ -819,6 +946,67 @@ function renderPlaybook(type, vars) {
     }
   } catch (e) { log('warn', `CLAUDE.md propagation inject failed: ${e.message}`); }
 
+  // W-mrtdmtwq000kf391 — surface the repo HARNESS assets in effect for this
+  // dispatch (runtime + project) in the Minions-authored PR body. We compute a
+  // compact, deterministic inventory from the read-only harness-diagnostics
+  // source and instruct the agent to append it (verbatim, fenced) to its PR
+  // description. Gated on: the flag (default on), a resolved project, a
+  // PR-authoring playbook, and the work item's resolved PR contract — NOT a
+  // shared-branch item (those never self-PR) and NOT a `skipPr` item (QA-session
+  // SETUP/DRAFT/EXECUTE and any PR-less work). Reporting only — no
+  // propagation/attestation (docs/harness-propagation.md).
+  //
+  // The inventory is derived from the RESOLVED dispatch: the same runtime, bare
+  // mode, propagation flag, injected CLAUDE.md files, and dispatch worktree the
+  // engine actually used — so the section never over-claims context the runtime
+  // never saw (reviewer BLOCKING, PR #898).
+  if (matchedProject
+      && !vars.shared_branch
+      && !vars.skip_pr
+      && PR_AUTHORING_PLAYBOOKS.has(type)
+      && (configEarly?.engine?.includeHarnessSectionInPrBody !== false)) {
+    try {
+      const harnessCtx = require('./harness-context');
+      const { inventory, section } = harnessCtx.renderHarnessSectionForDispatch({
+        runtimeCli: harnessCliName,
+        project: matchedProject,
+        worktreePath: vars.worktree_path || '',
+        bareMode: harnessBareMode,
+        nativeClaudeMd: runtimeNativeClaudeMd,
+        claudeMdInjectedFiles,
+        propagateClaudeMd,
+        pathHints: Array.isArray(vars.claude_md_path_hints) ? vars.claude_md_path_hints : [],
+      });
+      if (section) {
+        // Skills are the one category the engine can't resolve ahead of time —
+        // it knows which project skills are AVAILABLE but not which the agent
+        // will actually invoke. Hand the available list to the agent as a
+        // reference (prompt only, never the PR body) and have it report the
+        // subset it actually used. This keeps the block "used, not discovered".
+        const availableSkills = Array.isArray(inventory?.availableSkills) ? inventory.availableSkills : [];
+        const skillsGuidance = availableSkills.length
+          ? 'If — and only if — you actually invoked one or more repo skills while doing this '
+            + 'work, add a single `- **Skills used:** <comma-separated names>` line inside the '
+            + 'block (before the end marker), listing ONLY the skills you actually used. Omit '
+            + 'the line entirely if you used none. Do NOT list skills you did not use. The '
+            + 'project skills available to you this dispatch were: '
+            + availableSkills.join(', ') + '.\n\n'
+          : '';
+        inertAppendices.push(
+          '\n\n---\n\n## Repo harnesses — include in your PR body\n\n'
+          + 'When you open or update the PR for this dispatch, append the block below to the PR '
+          + 'description (keep the `' + harnessCtx.HARNESS_BLOCK_START + '` / `'
+          + harnessCtx.HARNESS_BLOCK_END + '` markers). If the PR body already contains a block '
+          + 'between those markers, replace it in place instead of adding a second copy. The '
+          + 'engine-resolved lines (runtime, CLAUDE.md, AGENTS.md, MCP) report what was actually '
+          + 'in effect for this runtime + project — keep them as given.\n\n'
+          + skillsGuidance
+          + section,
+        );
+      }
+    } catch (e) { log('warn', `harness PR-section inject failed: ${e.message}`); }
+  }
+
   // W-mp68q6ke0010de68 — opt-in keep_processes hint. Injected only when the
   // dispatcher set vars.keep_processes (truthy) from the work item's
   // `meta.keep_processes`. Built via the keep-process-sweep module so the
@@ -882,6 +1070,7 @@ function renderPlaybook(type, vars) {
         runbook: vars.qa_runbook,
         target: vars.qa_target,
         artifactsDir: vars.qa_artifacts_dir,
+        resultSidecar: vars.qa_result_sidecar,
       });
       if (block) inertAppendices.push(block);
     } catch (e) { log('warn', `qa-validate context render failed: ${e.message}`); }
@@ -962,7 +1151,7 @@ function renderPlaybook(type, vars) {
     repo_host: repoHost,
     ado_shared_rules: repoHost === 'ado' ? '1' : '',
     github_shared_rules: repoHost === 'github' ? '1' : '',
-    pr_create_instructions: getPrCreateInstructions(renderProject),
+    pr_create_instructions: getPrCreateInstructions(renderProject, config),
     pr_comment_instructions: getPrCommentInstructions(renderProject),
     pr_fetch_instructions: getPrFetchInstructions(renderProject),
     pr_vote_instructions: getPrVoteInstructions(renderProject, config),
@@ -1139,7 +1328,7 @@ function buildAgentContext(agentId, config, project) {
   if (history && history.trim() !== '# Agent History') {
     const entries = history.split(/(?=^### )/m);
     const header = entries[0].startsWith('#') && !entries[0].startsWith('### ') ? entries.shift() : '';
-    const recent = entries.slice(-5);
+    const recent = entries.slice(0, 5);
     const trimmed = (header ? header + '\n' : '') + recent.join('');
     context += `## Your Recent History (last 5 tasks)\n\n${trimmed}\n\n`;
   }

package/engine/pooled-agent-process.js

@@ -16,8 +16,13 @@
  * ACP lease.
  *
  * Output translation (parity, not full fidelity) is adapter-owned through
- * `encodePooledOutput()`. The facade only forwards semantic chunk/result
+ * `encodePooledOutput()`. The facade only forwards semantic model/chunk/result
  * events, so a harness can change its JSONL schema without changing this file.
+ *
+ * Before returning a healthy worker, the facade snapshots and reaps process
+ * trees created by this lease while preserving baseline worker/MCP descendants
+ * and validated keep_processes anchors. Cleanup uncertainty discards the worker
+ * instead of exposing its leftover processes to the next dispatch.
  */
 
 const { EventEmitter } = require('events');

package/engine/pr-action.js

@@ -278,7 +278,7 @@ function resolvePrActionRequest({ url, action } = {}) {
   if (!rawUrl) throw new PrActionError('url required');
 
   const ref = prResolve.normalizePrRef(rawUrl);
-  if (!ref) throw new PrActionError(`unrecognized PR reference: ${JSON.stringify(rawUrl.slice(0, 120))}`);
+  if (!ref) throw new PrActionError('unrecognized PR reference');
 
   return { action: act, ref };
 }