@yemi33/minions 0.1.2448 → 0.1.2449

package/engine/{meeting.js → orchestration/meeting.js}

@@ -1,16 +1,16 @@
 /**
- * engine/meeting.js — Team meeting orchestration.
+ * engine/orchestration/meeting.js — Team meeting orchestration.
  * Manages multi-round meetings: investigate → debate → conclude.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT, MEETING_STATUS } = shared;
-const apiValidation = require('./api-validation');
-const queries = require('./queries');
+const apiValidation = require('../api/api-validation');
+const queries = require('../core/queries');
 const { getDispatch, getConfig } = queries;
-const { renderPlaybook } = require('./playbook');
+const { renderPlaybook } = require('../agents/playbook');
 const dispatchModule = require('./dispatch');
 
 /** Patterns that indicate an agent returned no meaningful output */
@@ -971,17 +971,7 @@ function _killMeetingDispatches(meetingId) {
       return dp;
     }, { defaultValue: { pending: [], active: [], completed: [] } });
 
-    const pidsToKill = [];
-    for (const d of entriesToStop) {
-      try {
-        const pidFile = shared.findDispatchPidFile(d) || path.join(tmpDir, `pid-${d.id}.pid`);
-        const pid = shared.validatePid(fs.readFileSync(pidFile, 'utf8').trim());
-        pidsToKill.push(pid);
-      } catch { /* pending entries and already-finished agents may not have PID files */ }
-    }
-    for (const pid of pidsToKill) {
-      try { shared.killGracefully({ pid }); } catch { /* process may already be dead */ }
-    }
+    dispatchModule.stopDispatchProcesses(entriesToStop);
     for (const fp of filesToDelete) {
       try { fs.unlinkSync(fp); } catch { /* sidecar may not exist */ }
     }

package/engine/{pipeline.js → orchestration/pipeline.js}

@@ -1,5 +1,5 @@
 /**
- * engine/pipeline.js — Multi-stage pipeline orchestration.
+ * engine/orchestration/pipeline.js — Multi-stage pipeline orchestration.
  * Pipelines chain stages (task, meeting, plan, merge-prs, api, wait, parallel, condition)
  * with dependency tracking, artifact discovery, and conditional stop/termination.
  */
@@ -7,8 +7,8 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutateScheduleRuns, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, WORK_ITEM_PRIORITY, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR, isPrdArchived } = shared;
 const routing = require('./routing');
 const http = require('http');
@@ -18,9 +18,9 @@ const {
   buildSource,
   FENCE_OPEN_PREFIX,
   FENCE_CLOSE,
-} = require('./untrusted-fence');
-const smallStateStore = require('./small-state-store');
-const apiValidation = require('./api-validation');
+} = require('../core/untrusted-fence');
+const smallStateStore = require('../persistence/small-state-store');
+const apiValidation = require('../api/api-validation');
 const scheduler = require('./scheduler');
 
 // All module-relative paths flow through MINIONS_DIR so MINIONS_TEST_DIR
@@ -737,7 +737,7 @@ function deletePipeline(id) {
   } catch (e) {
     // TOCTOU: a concurrent delete of the same id may win the race between
     // existsSync and unlinkSync. Treat ENOENT as "already deleted" instead
-    // of throwing, mirroring deleteMeeting's unlink guard (engine/meeting.js).
+    // of throwing, mirroring deleteMeeting's unlink guard (engine/orchestration/meeting.js).
     if (e.code !== 'ENOENT') throw e;
     return false;
   }
@@ -753,7 +753,7 @@ function getPipelineRuns() {
 // Always read work items from the authoritative SQL store so stage-output
 // template substitution sees the latest completion metadata.
 function _allWorkItems() {
-  return require('./work-items-store').readAllWorkItems();
+  return require('../planning/work-items-store').readAllWorkItems();
 }
 
 function getActiveRun(pipelineId) {
@@ -1333,7 +1333,7 @@ function _isUsablePipelinePrd(prd) {
 // a usable PRD. Require both a recognized top-level status AND an array
 // `missing_features` field before counting the PRD as an existing conversion.
 function _findExistingPrdForPlan(planFile) {
-  const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived);
+  const prdFiles = require('../planning/prd-store').listPrdRows().filter(row => !row.archived);
   const planKey = _canonicalPlanName(planFile);
   for (const { filename: pf, plan: prd } of prdFiles) {
     if (!prd?.source_plan || _canonicalPlanName(path.basename(String(prd.source_plan))) !== planKey) continue;
@@ -1455,7 +1455,7 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
   // Use LLM to generate a structured plan (same approach as dashboard "Create Plan from Meeting" button)
   let content = '';
   try {
-    const llm = require('./llm');
+    const llm = require('../agents/llm');
     const planPrompt = 'Create an actionable implementation plan from this meeting. ' +
       'Extract concrete action items from the conclusion and debates. ' +
       'For each item include: what to do, which files/areas to change, priority (high/medium/low), and estimated complexity (small/medium/large). ' +
@@ -1821,7 +1821,7 @@ function isStageComplete(stage, stageState, run, config) {
       const plans = artifacts.plans || [];
       const discoveredPrds = [];
       const discoveredWiIds = [];
-      const prdRows = require('./prd-store').listPrdRows().filter(row => !row.archived);
+      const prdRows = require('../planning/prd-store').listPrdRows().filter(row => !row.archived);
       for (const planFile of plans) {
         const planKey = _canonicalPlanName(planFile);
         for (const { filename: pf, plan: prd } of prdRows) {
@@ -1860,7 +1860,7 @@ function isStageComplete(stage, stageState, run, config) {
       if (stage.autoApprove) {
         for (const prdFile of allPrds) {
           let approved = false;
-          require('./prd-store').mutatePrd(prdFile, (prd) => {
+          require('../planning/prd-store').mutatePrd(prdFile, (prd) => {
             if (prd && prd.status === PLAN_STATUS.AWAITING_APPROVAL) {
               prd.status = PLAN_STATUS.APPROVED;
               prd.approvedAt = ts();

package/engine/{pre-dispatch-eval.js → orchestration/pre-dispatch-eval.js}

@@ -1,5 +1,5 @@
 /**
- * engine/pre-dispatch-eval.js — Cheap LLM gate that screens work items for
+ * engine/orchestration/pre-dispatch-eval.js — Cheap LLM gate that screens work items for
  * clear/actionable/testable acceptance criteria *before* they are queued for
  * dispatch. Catches impossible or ambiguous items so a slow/expensive agent
  * run isn't burned on something that can't succeed.
@@ -18,7 +18,7 @@
  *   - Fail-open: any LLM error / runtime-unavailable / parse failure resolves
  *     `{ valid: true }` so the gate cannot wedge dispatch.
  *
- * Wired from engine/dispatch.js → addToDispatchWithValidation().
+ * Wired from engine/orchestration/dispatch.js → addToDispatchWithValidation().
  *
  * Source: Ripley §3 recommendation in
  *   knowledge/architecture/2026-05-11-ripley-daily-architecture-bug-review-ripley-s-investigati.md
@@ -28,9 +28,9 @@
  *   broaden validator to read description when criteria are missing.
  */
 
-const shared = require('./shared');
+const shared = require('../core/shared');
 const { log } = shared;
-const { callLLM } = require('./llm');
+const { callLLM } = require('../agents/llm');
 
 const SYSTEM_PROMPT = 'Output only JSON.';
 const DEFAULT_TIMEOUT_MS = 60000;
@@ -46,7 +46,7 @@ const DEFAULT_TIMEOUT_MS = 60000;
 const DESCRIPTION_MIN_CHARS = 80;
 
 // Guardrail appended to every prompt. The validator runs a pure text-reasoning
-// LLM call (direct: true, cwd hardcoded to MINIONS_DIR per engine/llm.js
+// LLM call (direct: true, cwd hardcoded to MINIONS_DIR per engine/agents/llm.js
 // _spawnProcess) with NO filesystem tools, so the model cannot see the target
 // project's code. P-b5e2a481 removed the read tools that were making the model
 // search MINIONS_DIR, but the model kept *asserting* unverified file-existence
@@ -145,7 +145,7 @@ function _parseResponse(text) {
  *   2. `shared.resolveCcModel(<engine sub-config>)` — defer to whatever the
  *      engine has configured for its CC/direct LLM path. Tolerates both the
  *      flat shape (`{ ccModel, defaultCli, ... }`, which is what
- *      `engine/dispatch.js addToDispatchWithValidation` actually passes today)
+ *      `engine/orchestration/dispatch.js addToDispatchWithValidation` actually passes today)
  *      and a nested shape (`{ engine: { ccModel, ... } }`) for callers that
  *      hand in the whole config blob.
  *   3. `undefined` — let the runtime adapter pick its own default. The Claude
@@ -181,7 +181,7 @@ function _resolveModel(opts) {
  * @param {object} [opts]
  * @param {object} [opts.engineConfig] - engine sub-config (flat
  *   `{ ccModel, defaultCli, ... }` as passed by
- *   `engine/dispatch.js addToDispatchWithValidation`, or the nested
+ *   `engine/orchestration/dispatch.js addToDispatchWithValidation`, or the nested
  *   `{ engine: { ... } }` whole-config shape). Used both for
  *   runtime/model resolution in `callLLM` and for resolving the validator's
  *   own model via `shared.resolveCcModel`.
@@ -190,7 +190,7 @@ function _resolveModel(opts) {
  *   (adapter default) when nothing is configured.
  * @param {object} [opts.project] - target-project identity for prompt context
  *   (`{ name, slug, localPath }`). Threaded by
- *   `engine/dispatch.js addToDispatchWithValidation` so the model knows which
+ *   `engine/orchestration/dispatch.js addToDispatchWithValidation` so the model knows which
  *   repo the work item targets (it CANNOT see any repo) and does not default to
  *   describing the Minions engine checkout it runs inside
  *   (W-mr25eg2400078d4b).
@@ -215,9 +215,10 @@ async function validateAcceptanceCriteria(workItem, opts = {}) {
       label: 'pre-dispatch-eval',
       model: _resolveModel(opts),
       maxTurns: 1,
+      disableTools: true,
       direct: true,
       // No tools at all. Direct callLLM spawns the runtime CLI with
-      // cwd=MINIONS_DIR (engine/llm.js _spawnProcess). P-b5e2a481 (2026-06-01
+      // cwd=MINIONS_DIR (engine/agents/llm.js _spawnProcess). P-b5e2a481 (2026-06-01
       // 23:44 UTC) removed write access (Edit/Write/Bash) after the validator
       // "previewed" work by editing dashboard/js/refresh.js in MINIONS_DIR, but
       // left Read/Grep/Glob in place. Those read tools made the model search the

package/engine/{routing.js → orchestration/routing.js}

@@ -1,12 +1,12 @@
 /**
- * engine/routing.js — Agent routing, budget checks, and routing table parsing.
+ * engine/orchestration/routing.js — Agent routing, budget checks, and routing table parsing.
  * Extracted from engine.js.
  */
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const queries = require('./queries');
+const shared = require('../core/shared');
+const queries = require('../core/queries');
 
 const { safeJson, safeRead, log, ts, WORK_TYPE } = shared;
 

package/engine/{schedule-bootstrap.js → orchestration/schedule-bootstrap.js}

@@ -1,5 +1,5 @@
 /**
- * engine/schedule-bootstrap.js — Batteries-included default schedules.
+ * engine/orchestration/schedule-bootstrap.js — Batteries-included default schedules.
  *
  * Historically the git-fetch-freshness schedule (git fetch origin, 12h cadence)
  * and the shared harness-sweep schedule (daily, explore type) only existed
@@ -22,13 +22,13 @@
  * Opt-out: `config.engine.bootstrapDefaultSchedules === false` disables all
  * bootstrap (the `ENGINE_DEFAULTS.bootstrapDefaultSchedules` default is `true`).
  *
- * Zero dependencies — Node built-ins + engine/shared only.
+ * Zero dependencies — Node built-ins + engine/core/shared only.
  */
 
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
-// Simplified cron is "minute hour dayOfWeek" (see engine/scheduler.js). These
+// Simplified cron is "minute hour dayOfWeek" (see engine/orchestration/scheduler.js). These
 // mirror the schedules that were previously created by hand for
 // src/constellation/fmf/minions/office-bohemia.
 const GIT_FETCH_CRON = '0 */12 *'; // every 12 hours, on the hour

package/engine/{scheduler.js → orchestration/scheduler.js}

@@ -1,5 +1,5 @@
 /**
- * engine/scheduler.js -- Cron-style scheduled task discovery.
+ * engine/orchestration/scheduler.js -- Cron-style scheduled task discovery.
  * Zero dependencies -- uses only Node.js built-ins.
  *
  * Config schema:
@@ -22,11 +22,11 @@
  */
 
 const fs = require('fs');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const routing = require('./routing');
-const harness = require('./harness');
+const harness = require('../agents/harness');
 const { safeJson, safeWrite, mutateJsonFileLocked, mutateScheduleRuns, ts, dateStamp, log, WI_STATUS, WORK_TYPE, WORK_ITEM_PRIORITY } = shared;
-const apiValidation = require('./api-validation');
+const apiValidation = require('../api/api-validation');
 
 const SCHEDULE_LIMITS = Object.freeze({
   id: 64,
@@ -142,6 +142,23 @@ function validateScheduleDefinition(schedule, options = {}) {
     optional: true,
     values: SCHEDULE_WORK_TYPES,
   });
+  // W-ms5tb6ha016fda10 — a schedule may declare `executionSurface:
+  // 'control-plane'` for maintenance jobs whose whole contract is Minions/REST
+  // API calls plus external CLIs (`gh`, `az`). Validated fail-closed against
+  // the schedule's resolved work type, so a repo-mutating schedule can never
+  // dispatch without a checkout.
+  if (schedule.executionSurface !== undefined) {
+    const surfaceType = routing.normalizeWorkType(schedule.type, WORK_TYPE.IMPLEMENT);
+    const surface = shared.validateExecutionSurface(schedule.executionSurface, surfaceType);
+    if (!surface.valid) {
+      _scheduleInputError(surface.error, {
+        code: surface.code || 'invalid-execution-surface',
+        path: 'executionSurface',
+        rejectedValue: schedule.executionSurface,
+        allowedValues: shared.EXECUTION_SURFACE_VALUES,
+      });
+    }
+  }
   _validateSchedulePriority(schedule.priority);
   _validateConfiguredProject(schedule.project, options.config, 'project');
   _validateConfiguredAgent(schedule.agent, options.config, 'agent');
@@ -239,9 +256,9 @@ function buildScheduleTemplateVars(extraVars) {
  *
  * Plus any caller-supplied `extraVars` (string-coerced). Callers should only
  * pass vars known at schedule time — pipeline-time vars like {{project_name}}
- * stay in engine/playbook.js where the dispatch context is available.
+ * stay in engine/agents/playbook.js where the dispatch context is available.
  *
- * Downstream playbook rendering (engine/playbook.js) is a single-pass replace,
+ * Downstream playbook rendering (engine/agents/playbook.js) is a single-pass replace,
  * so any {{var}} embedded in a schedule's title/description would survive
  * substitution of {{task_description}} and surface as an "unresolved template
  * variables: var" warning plus a literal "{{var}}" in agent filenames.
@@ -486,10 +503,18 @@ function createScheduledWorkItem(sched, extraVars) {
     throw new Error('schedule id and title are required');
   }
   const workItemId = `sched-${sched.id}-${Date.now()}`;
+  const workType = routing.normalizeWorkType(sched.type, WORK_TYPE.IMPLEMENT);
+  // W-ms5tb6ha016fda10 — carry a validly-declared control-plane surface onto
+  // the materialized work item so the dispatcher skips checkout allocation.
+  // Resolved fail-closed: an ineligible type silently materializes as a normal
+  // repo dispatch here (validateScheduleDefinition already 400s the operator
+  // at write time, and spawnAgent re-validates as the terminal gate).
+  const surface = shared.validateExecutionSurface(sched.executionSurface, workType);
+  const executionSurface = surface.valid ? surface.value : shared.EXECUTION_SURFACE.REPO;
   const workItem = {
     id: workItemId,
     title: sched.title,
-    type: routing.normalizeWorkType(sched.type, WORK_TYPE.IMPLEMENT),
+    type: workType,
     priority: sched.priority || WORK_ITEM_PRIORITY.MEDIUM,
     description: sched.description || sched.title,
     status: WI_STATUS.PENDING,
@@ -504,7 +529,12 @@ function createScheduledWorkItem(sched, extraVars) {
     // so the operator can navigate back to the dispatcher. Kept alongside
     // _scheduleId (used by queries / lifecycle / consolidation) so we don't
     // disturb the existing readers — meta.spawnedBy is purely additive.
-    meta: { spawnedBy: 'schedule:' + sched.id },
+    meta: {
+      spawnedBy: 'schedule:' + sched.id,
+      ...(executionSurface === shared.EXECUTION_SURFACE.CONTROL_PLANE
+        ? { executionSurface }
+        : {}),
+    },
   };
   // Walk every string-valued field on the work item so vars embedded in
   // nested fields (e.g. _harness.rubric added by callers, references[].url,