@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{playbook.js → agents/playbook.js}

@@ -1,27 +1,27 @@
 /**
- * engine/playbook.js — Playbook rendering, system prompt building, agent context,
+ * engine/agents/playbook.js — Playbook rendering, system prompt building, agent context,
  * task context resolution, and repo-host helpers.
  * Extracted from engine.js.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
-const { wrapUntrusted, buildSource } = require('./untrusted-fence');
-const { MINIONS_BRAND_URL } = require('./comment-format');
-const features = require('./features');
-const memoryRetrieval = require('./memory-retrieval');
-const memoryStore = require('./memory-store');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
+const { wrapUntrusted, buildSource } = require('../core/untrusted-fence');
+const { MINIONS_BRAND_URL } = require('../providers/comment-format');
+const features = require('../core/features');
+const memoryRetrieval = require('../memory/memory-retrieval');
+const memoryStore = require('../memory/memory-store');
 
 const { safeJsonArr, safeRead, getProjects, log, ts, dateStamp, truncateTextBytes, ENGINE_DEFAULTS, WI_STATUS, WORK_TYPE, PR_STATUS, DISPATCH_RESULT, getProjectOrg } = shared;
 const { getConfig, getDispatch, getNotes, getPrs, getKnowledgeBaseIndex, AGENTS_DIR } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
-const PLAYBOOKS_DIR = path.join(MINIONS_DIR, 'playbooks');
+const PLAYBOOKS_DIR = shared.resolveDefinitionDir('playbooks');
 
 // Import tempAgents from routing module
-const { tempAgents } = require('./routing');
+const { tempAgents } = require('../orchestration/routing');
 
 // ─── Repo Host Helpers ──────────────────────────────────────────────────────
 
@@ -70,7 +70,7 @@ function getPrCreateInstructions(project, config) {
       `- Use --head to specify your feature branch name\n` +
       (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.\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 "Visual evidence handling" section of the PR description audit.\n` +
       PR_ATTRIBUTION_INSTRUCTION;
   }
   // Default: Azure DevOps — prefer `az` CLI first, ADO REST API as fallback
@@ -85,7 +85,7 @@ function getPrCreateInstructions(project, config) {
     `- Use \`@<file>\` syntax for \`--description\` so Markdown, quotes, and newlines pass safely\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` +
+    `- 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 "Visual evidence handling" section of the PR description audit\n` +
     PR_ATTRIBUTION_INSTRUCTION + `\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.`;
@@ -165,7 +165,7 @@ function getPrVoteInstructions(project, config) {
       "<your review body here>\n" +
       "```\n" +
       `Then run: \`gh pr review <number> --comment --body-file <verdict.md> --repo ${org}/${repo}\`. Do NOT use \`--approve\` or \`--request-changes\` flags — they will fail.\n\n` +
-      `**Brand link:** whenever the body names "Minions" (e.g. the \`Reviewed by Minions (…)\` sign-off), render it as \`[Minions](${MINIONS_BRAND_URL})\` per the shared rules. On the GitHub path the engine also auto-links the first bare \`… by Minions\` trailer as a backstop (\`engine/comment-format.js#linkifyBrandTrailer\`), but write the link yourself so the first occurrence is correct.`;
+      `**Brand link:** whenever the body names "Minions" (e.g. the \`Reviewed by Minions (…)\` sign-off), render it as \`[Minions](${MINIONS_BRAND_URL})\` per the shared rules. On the GitHub path the engine also auto-links the first bare \`… by Minions\` trailer as a backstop (\`engine/providers/comment-format.js#linkifyBrandTrailer\`), but write the link yourself so the first occurrence is correct.`;
   }
   // Azure DevOps — prefer `az` CLI first, ADO REST API as fallback.
   // The platform reviewer vote is a POSITIVE mutation gated by autoApplyReviewVote
@@ -342,6 +342,7 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'acceptance_criteria',  // only set when item.acceptanceCriteria has entries
   'checkpoint_context',   // only set when resuming from a prior timeout
   'retry_context',      // only set when retrying after a validation-gate failure (#893)
+  'revision_feedback',  // only set when a plan-to-prd run is an operator revision (W-msa0mrus00mh466f)
   // Host-specific identifiers — always one of {ado_*, github_*} is empty
   // (project is either ADO or GitHub, never both). Keeping them as warns
   // produces ~96 noise lines per day on a single-host project.
@@ -417,6 +418,24 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'role',                  // 'primary' | 'co-service'
   'primary_project',       // canonical primary project name; empty on single-project sessions
   'co_services_json',      // JSON-encoded co-service project names (e.g. ["api","worker"]); empty when none
+  // W-msb9kgs402813a97-a — every managed-spawn the session owns, as
+  // [{name, project, primary, health, baseUrl, ports}]. DRAFT/EXECUTE address
+  // co-service origins through this; `managed_spawn_name` stays the primary.
+  // Empty string for non-QA-session dispatches.
+  'session_services_json',
+  // W-msb9kgs402813a97-b — absolute path of the DRAFT visual-journey manifest
+  // sidecar (agents/<id>/qa-session-draft-result.json). Populated only for the
+  // DRAFT phase; SETUP/EXECUTE and non-QA dispatches render ''.
+  'qa_draft_result_sidecar',
+  // W-msb9kgs402813a97-c — the DRAFT-accepted visual-journey manifest projected
+  // into the qa-run-result coverage-entry shape
+  // ([{journeyId, name, kind, projects, services}]). EXECUTE's evidence gate
+  // grades journeyCoverage against these ids verbatim, so the EXECUTE prompt
+  // has to carry them — the DRAFT sidecar that delivered them is consumed and
+  // unlinked, and the accepted manifest lives only on the session record.
+  // Populated ONLY for the EXECUTE phase of a session that persisted a
+  // manifest; SETUP/DRAFT, logs-only, legacy, and non-QA dispatches render ''.
+  'visual_journey_manifest_json',
   // M006 — typed handoff envelope fields. Set on a follow-up dispatch meta
   // when lifecycle.js queues the item after a completing agent so the
   // receiving agent has explicit context about who handed off and why.
@@ -430,6 +449,12 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // when no prior explore WI exists; the {{#prior_explore_context}} conditional
   // in fix.md renders the section only when non-empty.
   'prior_explore_context',
+  // W-ms5tb6ha016fda10 — declared execution surface for this dispatch.
+  // 'control-plane' when the work item validly opted out of a repository
+  // checkout; empty/'repo' otherwise. Playbooks don't reference it directly —
+  // renderPlaybook uses it to append the control-plane hint and to relax the
+  // project_path requirement.
+  'execution_surface',
 ]);
 
 
@@ -444,7 +469,11 @@ const PLAYBOOK_REQUIRED_VARS = {
   'explore':              ['task_description'],
   'ask':                  ['question'],
   'plan':                 ['task_description', 'project_path'],
-  'plan-to-prd':          ['plan_content', 'plan_file', 'prd_filename', 'project_path'],
+  // W-ms9tcry701xz0389 — `item_id` is required because the sidecar envelope
+  // binds itself to the work item via {{item_id}}. An unrendered token there
+  // would produce a permanently unimportable result, so fail the render loudly
+  // instead of shipping a poisoned contract to the agent.
+  'plan-to-prd':          ['plan_content', 'plan_file', 'prd_filename', 'project_path', 'item_id'],
   'decompose':            ['item_id', 'item_description', 'project_path'],
   'verify':               ['task_description'],
   'test':                 ['item_name'],
@@ -514,7 +543,16 @@ function validatePlaybookVars(playbookName, vars) {
   const required = PLAYBOOK_REQUIRED_VARS[playbookName];
   if (!required) return { valid: true, missing: [] };
 
-  const missing = required.filter(key => {
+  // W-ms5tb6ha016fda10 — a control-plane dispatch has no repository checkout,
+  // so `project_path` is legitimately empty. Requiring it would reject exactly
+  // the maintenance jobs the surface exists to make cheap. Every other
+  // required var still applies.
+  const controlPlane = vars?.execution_surface === 'control-plane';
+  const effective = controlPlane
+    ? required.filter(key => key !== 'project_path' && key !== 'worktree_path')
+    : required;
+
+  const missing = effective.filter(key => {
     const val = vars[key];
     return val === undefined || val === null || String(val).trim() === '';
   });
@@ -643,7 +681,7 @@ function buildQaValidateContextBlock({ runId, runbook, target, artifactsDir, res
     lines.push('');
   }
 
-  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, ...)\`.`);
+  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/orchestration/lifecycle.js\` and calls \`qaRuns.completeRun(runId, ...)\`.`);
 
   return lines.join('\n');
 }
@@ -872,7 +910,29 @@ function renderPlaybook(type, vars) {
           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));
+        // #3 pre-PR checklist: for dispatches that open or update a PR (every
+        // non read-only work type), frame the recalled lessons as an explicit
+        // gate the agent must clear before finalizing the PR, and tie each one
+        // back to the existing reviewLearningApplications completion contract so
+        // the confirmation is auditable. Read-only dispatches (ask/explore/plan/
+        // meeting) keep the informational framing — they open no PR to gate.
+        // The directive is trusted Minions instruction and stays OUTSIDE the
+        // untrusted fence; only the lesson bodies are fenced.
+        const recallType = String(vars.work_type || type || '').toLowerCase();
+        const prAuthoringDispatch = !shared.READ_ONLY_ROOT_TASK_TYPES.has(recallType);
+        const checklistDirective = prAuthoringDispatch
+          ? 'Treat the lessons below as a **pre-PR checklist**: each is a review finding raised on a '
+            + 'prior pull request for related code. Before you open or update this PR, confirm every one is '
+            + 'addressed in your current changes (or does not apply), verifying each against the live code — '
+            + 'do not assume a lesson still holds. In your completion report, record one '
+            + '`reviewLearningApplications` entry per lesson with outcome `applied`, '
+            + '`considered-not-applicable`, or `contradicted` and brief evidence.\n\n'
+          : '';
+        inertAppendices.push(
+          '\n\n---\n\n## Applicable Prior Review Lessons (task-selected; verify against live code)\n\n'
+          + checklistDirective
+          + (fenced || applicable.text)
+        );
       }
     } catch (e) {
       log('warn', `Review-learning recall failed for ${vars.item_id || vars.task_id || type}: ${e.message}`);
@@ -925,7 +985,7 @@ function renderPlaybook(type, vars) {
   // capability flag to avoid double-injection. Orthogonal to each runtime's
   // native AGENTS.md discovery (CLAUDE.md is never read by Copilot/Codex, so
   // there is nothing to conflict with). Bounded discovery (nearest-applicable
-  // walk-up, byte-capped) lives in engine/claude-md-context.js. Degrades
+  // walk-up, byte-capped) lives in engine/agents/claude-md-context.js. Degrades
   // silently on any error.
   //
   // These resolved facts (runtime, bare mode, propagation flag, and the ACTUAL
@@ -1029,13 +1089,28 @@ function renderPlaybook(type, vars) {
     } catch (e) { log('warn', `harness PR-section inject failed: ${e.message}`); }
   }
 
+  // W-ms5tb6ha016fda10 — control-plane execution surface. Injected only when
+  // the dispatcher set vars.execution_surface = 'control-plane' from the work
+  // item's validated `meta.executionSurface`. The agent has NO repository
+  // checkout, so it must be told that explicitly — otherwise a maintenance job
+  // wastes turns hunting for a worktree that was deliberately never allocated.
+  if (vars.execution_surface === 'control-plane') {
+    inertAppendices.push(buildControlPlaneHint({
+      projectName: vars.project_name,
+      repoName: vars.repo_name,
+      repoHost: vars.repo_host,
+      mainBranch: vars.main_branch,
+      cwd: MINIONS_DIR,
+    }));
+  }
+
   // 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
   // copy stays in sync with the engine-side caps it actually enforces.
   if (vars.keep_processes) {
     try {
-      const keepProcessSweep = require('./keep-process-sweep');
+      const keepProcessSweep = require('../processes/keep-process-sweep');
       const hint = keepProcessSweep.buildKeepProcessesHint({
         agentId: vars.agent_id,
         workItemId: vars.item_id || vars.task_id,
@@ -1052,7 +1127,7 @@ function renderPlaybook(type, vars) {
   // managed-spawn sidecar so the engine takes over spawn + healthcheck.
   if (vars.managed_spawn) {
     try {
-      const managedSpawn = require('./managed-spawn');
+      const managedSpawn = require('../processes/managed-spawn');
       const hint = managedSpawn.buildManagedSpawnHint({
         agentId: vars.agent_id,
         workItemId: vars.item_id || vars.task_id,
@@ -1072,7 +1147,7 @@ function renderPlaybook(type, vars) {
   // string is returned when nothing matches, so we short-circuit on falsy.
   if (vars.project_name) {
     try {
-      const managedSpawn = require('./managed-spawn');
+      const managedSpawn = require('../processes/managed-spawn');
       const liveBlock = managedSpawn.buildLiveManagedProcessesBlock({
         project: vars.project_name,
       });
@@ -1164,6 +1239,11 @@ function renderPlaybook(type, vars) {
     repoHost: vars.repo_host || vars.repoHost || dispatchProject.repoHost,
   };
   const repoHost = getRepoHost(renderProject);
+  const liveDashboard = shared.readDashboardPortFile(MINIONS_DIR);
+  const dashboardPort = liveDashboard?.port || shared.resolveDashboardPort({
+    env: process.env.MINIONS_DASHBOARD_PORT,
+    config: config.engine?.dashboardPort,
+  }).port;
   const projectVars = {
     project_name: renderProject.name || 'Unknown Project',
     ado_org: repoHost === 'ado' ? (renderProject.adoOrg || 'Unknown') : '',
@@ -1179,6 +1259,7 @@ function renderPlaybook(type, vars) {
     pr_fetch_instructions: getPrFetchInstructions(renderProject),
     pr_vote_instructions: getPrVoteInstructions(renderProject, config),
     repo_host_label: getRepoHostLabel(renderProject),
+    dashboard_port: dashboardPort,
   };
   const allVars = { ...projectVars, ...vars };
 
@@ -1385,7 +1466,7 @@ function buildAgentContext(agentId, config, project) {
   }
   // Also check the central SQL pull-request scope.
   try {
-    const centralPrs = require('./pull-requests-store').readPullRequestsForScope('central');
+    const centralPrs = require('../persistence/pull-requests-store').readPullRequestsForScope('central');
     for (const pr of centralPrs.filter(pr => pr.status === PR_STATUS.ACTIVE)) {
       if (!allPrs.some(p => p.id === pr.id)) allPrs.push({ ...pr, _project: 'central' });
     }
@@ -1452,6 +1533,57 @@ function buildBaseVars(agentId, config, project) {
   };
 }
 
+/**
+ * W-ms5tb6ha016fda10 — control-plane dispatch hint.
+ *
+ * Appended to the rendered prompt when the work item validly declared
+ * `meta.executionSurface: 'control-plane'`. The agent runs at the Minions root
+ * with NO repository checkout, so the contract has to be stated explicitly:
+ * project identity is available as context, the repo is not on disk, and
+ * anything that needs repository files belongs on a normal `repo` dispatch.
+ *
+ * Pure + platform-agnostic (no shell snippets, no hardcoded commands) so it
+ * behaves identically on Windows, Linux, and macOS.
+ */
+function buildControlPlaneHint({ projectName, repoName, repoHost, mainBranch, cwd } = {}) {
+  const lines = [
+    '## Execution surface: control-plane (no repository checkout)',
+    '',
+    'This work item declared `meta.executionSurface: "control-plane"`, so the engine '
+      + 'deliberately did **not** allocate a git worktree for it. Your working directory is the '
+      + 'Minions root (`' + (cwd || '') + '`), not a checkout of the target repository.',
+    '',
+    '**What that means**',
+    '',
+    '- The target repository is **not** on disk for this dispatch. Do not look for a worktree, '
+      + 'do not `git clone`, and do not run git commands against the operator\'s checkout.',
+    '- Do your work through the Minions dashboard API and the platform CLIs you already have '
+      + '(`gh` for GitHub, `az` for Azure DevOps). Those reach the remote directly and need no '
+      + 'local checkout.',
+    '- Do not create a branch, commit, or open a PR from this dispatch — there is nothing to '
+      + 'commit from.',
+  ];
+  const context = [];
+  if (projectName && projectName !== 'Unknown Project') context.push(`project \`${projectName}\``);
+  if (repoName && repoName !== 'Unknown') context.push(`repo \`${repoName}\``);
+  if (repoHost) context.push(`host \`${repoHost}\``);
+  if (mainBranch) context.push(`main branch \`${mainBranch}\``);
+  if (context.length) {
+    lines.push(
+      '',
+      '**Project context** (carried without a checkout): ' + context.join(', ') + '.',
+    );
+  }
+  lines.push(
+    '',
+    'If you discover the task genuinely requires reading or changing repository files, **stop** '
+      + 'and report that in your completion summary instead of improvising a checkout. The work '
+      + 'item should be re-declared as `executionSurface: "repo"` so the engine allocates an '
+      + 'isolated worktree for it.',
+  );
+  return lines.join('\n');
+}
+
 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
@@ -1523,6 +1655,7 @@ module.exports = {
   resolvePlaybookPath,
   renderPlaybook,
   validatePlaybookVars,
+  buildControlPlaneHint, // W-ms5tb6ha016fda10 — exported for testing
   PLAYBOOK_REQUIRED_VARS,
   PLAYBOOK_OPTIONAL_VARS,
   _parsePlaybookFrontmatter,

package/engine/{pooled-agent-process.js → agents/pooled-agent-process.js}

@@ -1,6 +1,6 @@
 /**
- * engine/pooled-agent-process.js — child_process-shaped facade over a leased
- * engine/agent-worker-pool.js worker (P-1d8f0b93).
+ * engine/agents/pooled-agent-process.js — child_process-shaped facade over a leased
+ * engine/agents/agent-worker-pool.js worker (P-1d8f0b93).
  *
  * engine.js#spawnAgent's downstream code (stdout/stderr `.on('data', ...)`
  * handlers, the `onAgentClose` completion listener, PID-file/timeout
@@ -30,7 +30,7 @@ const { PassThrough } = require('stream');
 const {
   resolveRuntimeByCapability,
   encodePooledOutput,
-} = require('./runtimes');
+} = require('../runtimes');
 
 const CANCEL_GRACE_MS = 1500;
 const DESCENDANT_INITIAL_SNAPSHOT_MS = 3000;
@@ -41,19 +41,21 @@ const _internals = {
   cancelGraceMs: CANCEL_GRACE_MS,
   killVerifyDelayMs: 50,
   listAllProcesses() {
-    return require('./shared').listAllProcessesAsync();
+    return require('../core/shared').listAllProcessesAsync();
   },
   listProcessDescendants(pid, processes) {
-    return require('./shared').listProcessDescendants(pid, processes);
+    return require('../core/shared').listProcessDescendants(pid, processes);
   },
   findProcessesWithCwdInside(cwd) {
-    return require('./shared').findProcessesWithCwdInsideAsync(cwd);
+    return require('../core/shared').findProcessesWithCwdInsideAsync(cwd);
   },
-  killByPidsImmediate(pids) {
-    return require('./shared').killByPidsImmediate(pids);
+  killByPidsImmediate(pids, expectedIdentities) {
+    return require('../core/shared').terminateProcess('engine.pooled-agent.descendants', pids, {
+      expectedIdentities,
+    });
   },
   computeReapPlan(pids, agentId, opts) {
-    return require('./keep-process-sweep').computeReapPlan(pids, agentId, opts);
+    return require('../processes/keep-process-sweep').computeReapPlan(pids, agentId, opts);
   },
 };
 
@@ -83,7 +85,7 @@ function dispatchOwnedDescendants(rootPid, baselinePids, processes) {
 class PooledAgentProcess extends EventEmitter {
   /**
    * @param {object} opts
-   * @param {object} opts.pool - engine/agent-worker-pool.js module (or a test double)
+   * @param {object} opts.pool - engine/agents/agent-worker-pool.js module (or a test double)
    * @param {object} opts.runtime - resolved runtime adapter
    * @param {string} opts.dispatchId
    * @param {string} opts.cwd
@@ -472,7 +474,7 @@ class PooledAgentProcess extends EventEmitter {
       if (currentStartedAt === startedAt) pids.push(pid);
     }
     if (pids.length === 0) return true;
-    _internals.killByPidsImmediate(pids);
+    _internals.killByPidsImmediate(pids, identities);
     const delayMs = Math.max(0, Number(_internals.killVerifyDelayMs) || 0);
     if (delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
     const processes = await _internals.listAllProcesses();
@@ -624,7 +626,7 @@ class PooledAgentProcess extends EventEmitter {
   // child_process.kill()-shaped primitive. Cancels the in-flight ACP turn and
   // releases its lease; the pool evicts the worker if that turn is not settled,
   // preventing a cancelled response from leaking into the next dispatch.
-  // Full timeout/steering-kill cancel-vs-kill wiring in engine/timeout.js is
+  // Full timeout/steering-kill cancel-vs-kill wiring in engine/orchestration/timeout.js is
   // P-6e2a4c15 — this method is the primitive that work item calls into.
   kill() {
     if (this.killed) return true;

package/engine/{preflight.js → agents/preflight.js}

@@ -1,5 +1,5 @@
 /**
- * engine/preflight.js — Prerequisite and health checks for Minions.
+ * engine/agents/preflight.js — Prerequisite and health checks for Minions.
  * Used by `minions init`, `minions start`, and `minions doctor`.
  *
  * Per-runtime binary + model-discovery checks (P-9e8a3f1d) — for every distinct
@@ -12,7 +12,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, execFileSync } = require('child_process');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 /**
  * Resolve the Claude Code CLI binary path. Legacy helper preserved for back-
@@ -120,7 +120,7 @@ function _distinctRuntimes(config) {
 function _checkRuntimeBinary(runtimeName, { optional = false } = {}) {
   let adapter;
   try {
-    adapter = require('./runtimes').resolveRuntime(runtimeName);
+    adapter = require('../runtimes').resolveRuntime(runtimeName);
   } catch (e) {
     return {
       name: `Runtime: ${runtimeName}`,
@@ -226,7 +226,7 @@ function runPreflight(opts = {}) {
   let runtimes = configuredRuntimes;
   if (opts.includeAllRegistered) {
     let registered = [];
-    try { registered = require('./runtimes').listRuntimes(); }
+    try { registered = require('../runtimes').listRuntimes(); }
     catch { /* registry may be missing during partial installs */ }
     runtimes = Array.from(new Set([...configuredRuntimes, ...registered])).sort();
   }
@@ -252,7 +252,7 @@ function runPreflight(opts = {}) {
     // worktreeRoot check.
     try {
       let runtimeNames = [];
-      try { runtimeNames = require('./runtimes').listRuntimes(); }
+      try { runtimeNames = require('../runtimes').listRuntimes(); }
       catch { /* registry may be missing during partial installs */ }
       const warns = shared.runtimeConfigWarnings(opts.config, runtimeNames);
       for (const w of warns) {
@@ -358,7 +358,7 @@ function _fleetSummaryResults(config, { dispatch } = {}) {
   if (!config || typeof config !== 'object') return results;
   const engine = config.engine || {};
   const defaultCli = engine.defaultCli ? String(engine.defaultCli) : 'copilot';
-  const display = require('./queries').resolveRuntimeModelDisplay({
+  const display = require('../core/queries').resolveRuntimeModelDisplay({
     runtime: defaultCli,
     configuredModel: engine.defaultModel,
     dispatch,
@@ -398,7 +398,7 @@ async function _modelDiscoveryResults(config) {
   let md;
   try { md = require('./model-discovery'); } catch { return results; }
   let registry;
-  try { registry = require('./runtimes'); } catch { return results; }
+  try { registry = require('../runtimes'); } catch { return results; }
   const fleetDisabled = config.engine && config.engine.disableModelDiscovery === true;
   const runtimes = _distinctRuntimes(config);
   for (const runtimeName of runtimes) {
@@ -521,7 +521,7 @@ function _bypassFlagResults(config) {
   const results = [];
   if (!config || typeof config !== 'object') return results;
   let registry;
-  try { registry = require('./runtimes'); } catch { return results; }
+  try { registry = require('../runtimes'); } catch { return results; }
   const runtimes = _distinctRuntimes(config);
   for (const runtimeName of runtimes) {
     let adapter;
@@ -665,7 +665,7 @@ function doctor(minionsHome) {
     // for hours. Only flagged when installed AND broken; not-installed is a
     // neutral note since the watchdog is opt-in.
     try {
-      const watchdog = require(path.join(minionsHome, 'engine', 'watchdog'));
+      const watchdog = require(path.join(minionsHome, 'engine', 'recovery', 'watchdog'));
       const wh = watchdog.health({ minionsHome });
       if (!wh.installed) {
         runtimeResults.push({ name: 'Watchdog', ok: 'warn', message: wh.message });
@@ -698,6 +698,25 @@ function doctor(minionsHome) {
     const bypassResults = _bypassFlagResults(preflightConfig);
     runtimeResults.push(...bypassResults);
 
+    // Constellation companion presence (P-e93c85a1). Read-only and bounded:
+    // a marker read plus, at most, one loopback health request with an explicit
+    // timeout. Reporting only — Minions never downloads, executes, or installs
+    // Constellation, and an absent/incompatible companion is always a `warn`
+    // so `minions doctor` keeps its exit code on hosts without Constellation.
+    // Suppressed entirely (no row at all) by the documented opt-out.
+    try {
+      const companion = require('../api/companion');
+      const companionResult = await companion.probeCompanion({ config: preflightConfig });
+      const companionRow = companion.companionDoctorResult(companionResult);
+      if (companionRow) runtimeResults.push(companionRow);
+    } catch (err) {
+      runtimeResults.push({
+        name: 'Constellation companion',
+        ok: 'warn',
+        message: `companion-unknown — probe unavailable: ${(err && err.message) || err} (see docs/constellation-bridge.md)`,
+      });
+    }
+
     // Print all
     const allResults = [...results, ...runtimeResults];
     const ok = printPreflight(allResults, { label: 'Minions Doctor' });
@@ -861,7 +880,7 @@ function runHarnessDoctor(minionsHome, opts = {}) {
   const out = opts.out || (line => console.log(line));
 
   let registry;
-  try { registry = require('./runtimes'); }
+  try { registry = require('../runtimes'); }
   catch (e) {
     out(`Minions Runtime Harness Inventory`);
     out(`  Could not load runtime registry: ${e.message}`);

package/engine/{spawn-agent.js → agents/spawn-agent.js}

@@ -33,16 +33,16 @@
 
 const fs = require('fs');
 const path = require('path');
-const { runFile, cleanChildEnv, killImmediate, killByPidsImmediate, listProcessDescendants, ts, readFileNoFollow } = require('./shared');
+const { runFile, cleanChildEnv, terminateProcess, listAllProcesses, listProcessDescendants, ts, readFileNoFollow } = require('../core/shared');
 const {
   resolveRuntime,
   RUNTIME_OPTIONS_FLAG,
   RUNTIME_IMAGES_FILE_OPTION,
   decodeRuntimeOptions,
   prepareWorkspace: prepareRuntimeWorkspace,
-} = require('./runtimes');
-const { acquireAdoTokenSync, isLikelyAdoToken } = require('./ado-token');
-const keepProcessSweep = require('./keep-process-sweep');
+} = require('../runtimes');
+const { acquireAdoTokenSync, isLikelyAdoToken } = require('../ado/token');
+const keepProcessSweep = require('../processes/keep-process-sweep');
 const MAX_RUNTIME_IMAGES_FILE_BYTES = 32 * 1024 * 1024;
 
 // ─── Pure helpers (exported for tests) ──────────────────────────────────────
@@ -246,7 +246,7 @@ async function _worktreeDirtyFiles(execFn, opts) {
   const raw = typeof out === 'string'
     ? out
     : (out?.stdout?.toString?.() ?? String(out ?? ''));
-  const shared = require('./shared');
+  const shared = require('../core/shared');
   return String(raw)
     .split(/\r?\n/)
     .filter((line) => line.trim().length > 0)
@@ -329,7 +329,7 @@ async function assertStaleHeadOk({
   if (!cwd) throw new Error('assertStaleHeadOk: cwd is required');
   const execFn = typeof exec === 'function'
     ? exec
-    : require('./shared').execAsync;
+    : require('../core/shared').execAsync;
   const opts = { ...(gitOpts || {}), cwd };
 
   // Proof of engine ownership. Absence = cannot prove current-dispatch-safe,
@@ -339,7 +339,7 @@ async function assertStaleHeadOk({
     if (typeof isEngineOwned === 'function') {
       try { return !!isEngineOwned(cwd); } catch { return false; }
     }
-    try { return require('./shared').hasWorktreeOwnerMarker(cwd); } catch { return false; }
+    try { return require('../core/shared').hasWorktreeOwnerMarker(cwd); } catch { return false; }
   };
 
   const attempts = Math.max(1, Math.trunc(Number(maxRefreshAttempts) || 0));
@@ -632,7 +632,7 @@ function main() {
     deliverPromptToStdin(proc.stdin, invocation.finalPrompt, (err) => {
       console.error(`FATAL: child startup stdin delivery failed (${err.code || 'error'}): ${err.message}`);
       fs.appendFileSync(debugPath, `STDIN ERROR (${err.code || 'error'}): ${err.message}\n`);
-      killImmediate(proc);
+      terminateProcess('engine.spawn-agent.stdin-failure', proc);
       process.exit(1);
     });
   } else {
@@ -649,7 +649,7 @@ function main() {
   // `--add-dir` traversal, Windows process startup) the read can land well
   // after any short timer fires, leaving Claude to bail with
   // "System prompt file not found". The exit/SIGTERM handler below — plus the
-  // matching unlinks in engine/dispatch.js and engine/meeting.js on dispatch
+  // matching unlinks in engine/orchestration/dispatch.js and engine/orchestration/meeting.js on dispatch
   // completion — are sufficient to keep tmp files from leaking.
   function _cleanupSpawnTempFiles() {
     if (wantsSystemPromptFile) {
@@ -678,7 +678,7 @@ function main() {
   // that are actively working (incident: ralph-fix-mrz8ka5g0015124a pushed merge
   // commit 8b0e6ff1 and wrote a nonce-valid success report, yet the 180s timer's
   // killGracefully forced result:error). Startup-stall detection is owned by the
-  // engine-side spawn-phase watchdog (engine/spawn-phase-watchdog.js), which
+  // engine-side spawn-phase watchdog (engine/agents/spawn-phase-watchdog.js), which
   // distinguishes a genuinely wedged pre-task process (idle, no live-output task
   // activity, CPU below threshold past the grace window) from a productive-but-
   // silent one (burning CPU) — preserving the invariant that a live tracked agent
@@ -698,13 +698,18 @@ function main() {
   // taskkill /T against the dead parent PID no longer finds them. We snapshot
   // the descendant tree periodically while the runtime is alive so the close
   // handler can reap any survivors by PID after the parent has gone.
-  const trackedDescendants = new Set();
+  const trackedDescendants = new Map();
   let snapshotInFlight = false;
   function snapshotDescendants() {
     if (!proc.pid || snapshotInFlight) return;
     snapshotInFlight = true;
     try {
-      for (const pid of listProcessDescendants(proc.pid)) trackedDescendants.add(pid);
+      const processes = listAllProcesses();
+      const byPid = new Map(processes.map(entry => [Number(entry.pid), entry]));
+      for (const pid of listProcessDescendants(proc.pid, processes)) {
+        const startedAt = Number(byPid.get(pid)?.startedAt);
+        if (startedAt > 0) trackedDescendants.set(pid, startedAt);
+      }
     } catch { /* best-effort */ }
     finally { snapshotInFlight = false; }
   }
@@ -782,7 +787,7 @@ function main() {
         // (engine.js:1451 sets it to agents/<agentId>/live-output.log) and
         // subtract validated, alive PIDs from the kill set. Missing or
         // invalid file → fall through to today's behavior (reap everything).
-        let toKillPids = [...trackedDescendants];
+        let toKillPids = [...trackedDescendants.keys()];
         let kept = [];
         let keepRecord = null;
         let keepReason = null;
@@ -819,7 +824,13 @@ function main() {
         } else if (keepReason) {
           try { fs.appendFileSync(debugPath, `KEEP-PIDS skipped: ${keepReason}\n`); } catch {}
         }
-        const reaped = toKillPids.length ? killByPidsImmediate(toKillPids) : 0;
+        const reaped = toKillPids.length
+          ? terminateProcess('engine.spawn-agent.descendants', toKillPids, {
+              expectedIdentities: new Map(
+                toKillPids.map(pid => [pid, trackedDescendants.get(pid)]),
+              ),
+            })
+          : 0;
         try { fs.appendFileSync(debugPath, `DESCENDANTS reaped=${reaped}/${toKillPids.length} kept=${kept.length}\n`); } catch {}
       }
     }