@yemi33/minions 0.1.2378 → 0.1.2380

package/engine/llm.js

@@ -33,7 +33,7 @@ const EXIT_DRAIN_FALLBACK_MS = 100;
 //
 // Updates accumulate in an in-memory buffer and flush every
 // metricsFlushIntervalMs (default 10s). Replaces the per-call mutateJsonFileLocked
-// that was both serializing the LLM hot path and bumping metrics.json mtime
+// that was serializing the LLM hot path
 // on every call — defeating the dashboard fast-state mtime-based early-exit.
 
 let _pendingMetrics = { engine: Object.create(null), daily: Object.create(null) };

package/engine/logs-store.js

@@ -1,4 +1,4 @@
-// engine/logs-store.js — SQL-backed implementation of engine/log.json.
+// engine/logs-store.js — SQL-backed engine logs.
 //
 // Logs differ from work_items / pull_requests / dispatches: they are
 // pure append-only with a tail-cap, so the store exposes a different
@@ -168,7 +168,7 @@ function readRecentLogs(n, opts) {
   return out;
 }
 
-// Convenience: same shape as the legacy `JSON.parse(log.json).slice(-N)`
+// Convenience: return the latest N entries in chronological order.
 // — chronological order (oldest first). Inverts the readRecentLogs DESC
 // output so existing callers can drop in without re-sorting.
 function readRecentLogsChronological(n, opts) {

package/engine/managed-spawn.js

@@ -28,7 +28,6 @@ const queries = require('./queries');
 const { log, ENGINE_DEFAULTS } = shared;
 
 const MANAGED_SPAWN_FILENAME = 'managed-spawn.json';
-const MANAGED_PROCESSES_STATE_FILE = 'managed-processes.json';
 const MANAGED_LOGS_DIR = 'managed-logs';
 const INVALID_WORKDIR_REASON_PREFIX = 'invalid-workdir: ';
 
@@ -760,7 +759,7 @@ function buildManagedSpawnHint(opts) {
 //                                    spawnDashboard detached-spawn pattern.
 //                                    Returns {pid, started_at, log_path}.
 //   3. recordManagedSpec(spec,     → writes one entry to
-//      runtime, ctx)                 engine/managed-processes.json via
+//      runtime, ctx)                 SQL managed-process state via
 //                                    mutateJsonFileLocked. Replaces any
 //                                    existing entry with the same name
 //                                    (idempotent under retry).
@@ -777,16 +776,6 @@ function buildManagedSpawnHint(opts) {
 //                                    (playbook injection) + items 3/7
 //                                    (sweep + boot reconcile).
 //
-// All state writes go through mutateJsonFileLocked per the repo convention
-// ('Key conventions' in copilot-instructions.md). Callbacks stay synchronous
-// and fast — no kill / no spawn inside the lock callback. Healthcheck loops,
-// dispatch ERROR gating on healthcheck failure, per-tick sweep, boot
-// reconcile, and dashboard endpoints are deferred to items 3/4/5/7.
-
-function _getStatePath() {
-  return path.join(shared.MINIONS_DIR, 'engine', MANAGED_PROCESSES_STATE_FILE);
-}
-
 function _getLogsDir() {
   return path.join(shared.MINIONS_DIR, 'engine', MANAGED_LOGS_DIR);
 }
@@ -906,7 +895,6 @@ function _toStateRecord(spec, runtime, ctx) {
 
 function recordManagedSpec(spec, runtime, ctx) {
   if (!spec || !spec.name) throw new Error('recordManagedSpec: spec.name required');
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
@@ -921,7 +909,6 @@ function recordManagedSpec(spec, runtime, ctx) {
 
 function recordManagedBatch(items, ctx) {
   if (!Array.isArray(items) || items.length === 0) return;
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || typeof data !== 'object' || Array.isArray(data) || !Array.isArray(data.specs)) {
       data = _initialStateShape();
@@ -942,7 +929,6 @@ function recordManagedBatch(items, ctx) {
 function removeManagedSpec(name) {
   if (typeof name !== 'string' || name.length === 0) return;
   let killPid = null;
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const idx = data.specs.findIndex(s => s && s.name === name);
@@ -968,8 +954,7 @@ function removeManagedSpec(name) {
 
 function listManagedSpecs(opts) {
   opts = opts || {};
-  const statePath = _getStatePath();
-  const parsed = shared.safeJsonObj(statePath);
+  const parsed = require('./small-state-store').readManagedProcesses();
   const specs = (parsed && Array.isArray(parsed.specs)) ? parsed.specs : [];
   if (opts.project) return specs.filter(s => s && s.owner_project === opts.project);
   return specs.slice();
@@ -1090,7 +1075,6 @@ async function runHealthcheck(spec) {
 // waitForFirstHealth on the first pass. Callers MUST be outside any other
 // lock — this acquires its own.
 function _markHealthy(name, now) {
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
@@ -1404,7 +1388,6 @@ function _runManagedReconcile(opts) {
     rotatedLogs: 0,
     malformed: 0,
   };
-  const statePath = _getStatePath();
   const ttlPidsToKill = [];
   const survivors = []; // [{name, log_path}] post-mutation, used for log rotation + bootReconcile probes
   shared.mutateManagedProcesses((data) => {
@@ -1459,7 +1442,6 @@ function sweepManagedSpawn(opts) {
 // rely on the per-spec loop to refresh post-success, or item 7 boot reconcile
 // to (re)establish initial truth on engine restart).
 function _markBootProbe(name, result) {
-  const statePath = _getStatePath();
   shared.mutateManagedProcesses((data) => {
     if (!data || !Array.isArray(data.specs)) return data;
     const rec = data.specs.find(s => s && s.name === name);
@@ -1510,7 +1492,6 @@ function removeManagedSpecsForProject(projectName) {
   if (typeof projectName !== 'string' || projectName.length === 0) {
     return { killed: 0, unlinked: 0, scanned: 0 };
   }
-  const statePath = _getStatePath();
   let toKill = [];
   let logPaths = [];
   shared.mutateManagedProcesses((data) => {
@@ -1546,7 +1527,6 @@ function removeManagedSpecsForProject(projectName) {
 
 module.exports = {
   MANAGED_SPAWN_FILENAME: MANAGED_SPAWN_FILENAME,
-  MANAGED_PROCESSES_STATE_FILE: MANAGED_PROCESSES_STATE_FILE,
   MANAGED_LOGS_DIR: MANAGED_LOGS_DIR,
   INVALID_WORKDIR_REASON_PREFIX: INVALID_WORKDIR_REASON_PREFIX,
   HEALTHCHECK_TYPES: HEALTHCHECK_TYPES,
@@ -1561,7 +1541,6 @@ module.exports = {
   recordManagedBatch: recordManagedBatch,
   removeManagedSpec: removeManagedSpec,
   listManagedSpecs: listManagedSpecs,
-  getStatePath: _getStatePath,
   // Item 3 (P-9c1f47a6): healthcheck implementations + first-pass waiter.
   runHealthcheck: runHealthcheck,
   waitForFirstHealth: waitForFirstHealth,

package/engine/meeting.js

@@ -10,6 +10,7 @@ const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT, MEE
 const queries = require('./queries');
 const { getDispatch, getConfig } = queries;
 const { renderPlaybook } = require('./playbook');
+const dispatchModule = require('./dispatch');
 
 /** Patterns that indicate an agent returned no meaningful output */
 const EMPTY_OUTPUT_PATTERNS = ['(no output)', '(no findings)', '(no response)'];
@@ -514,7 +515,7 @@ function discoverMeetingWork(config) {
 
     // Pre-flight validation: meetings missing required template vars (agenda)
     // would otherwise fail playbook rendering on every tick (~1/min), spamming
-    // log.json with the same "missing required template variables: agenda"
+    // the engine log with the same "missing required template variables: agenda"
     // error. Skip them silently here; emit one structured warning per meeting
     // ID per process so the operator still has signal without the spam.
     if (!meeting.agenda || !String(meeting.agenda).trim()) {
@@ -757,12 +758,11 @@ function addMeetingNote(meetingId, note) {
 
 function _killMeetingDispatches(meetingId) {
   try {
-    const DISPATCH_PATH = path.join(shared.MINIONS_DIR, 'engine', 'dispatch.json');
     const tmpDir = path.join(shared.MINIONS_DIR, 'engine', 'tmp');
     const entriesToStop = [];
     const filesToDelete = [];
     const dispatchDirsToRemove = [];
-    shared.mutateJsonFileLocked(DISPATCH_PATH, (dp) => {
+    dispatchModule.mutateDispatch((dp) => {
       dp.pending = Array.isArray(dp.pending) ? dp.pending : [];
       dp.active = Array.isArray(dp.active) ? dp.active : [];
       dp.completed = Array.isArray(dp.completed) ? dp.completed : [];
@@ -828,7 +828,7 @@ function advanceMeetingRound(meetingId) {
   if (!existing || existing.status === MEETING_STATUS.COMPLETED || existing.status === MEETING_STATUS.ARCHIVED) return null;
 
   // CRITICAL: kill BEFORE acquiring the meeting lock. _killMeetingDispatches
-  // takes the dispatch.json lock and shells out to kill processes — never
+  // mutates dispatch state and shells out to kill processes — never
   // run that under the meeting lock (per CLAUDE.md, lock callbacks must
   // stay fast and never spawn / kill / await).
   _killMeetingDispatches(meetingId);
@@ -923,13 +923,13 @@ function checkMeetingTimeouts(config) {
     // BUG-H11: when a hard timeout will fire, kill in-flight meeting
     // dispatches BEFORE entering the meeting lock so they stop consuming
     // worker slots / LLM tokens immediately rather than draining over the
-    // next tens of minutes. _killMeetingDispatches takes the dispatch.json
+    // next tens of minutes. _killMeetingDispatches takes the dispatch
     // lock and shells out to kill processes — per CLAUDE.md and the
     // advanceMeetingRound/endMeeting/deleteMeeting pattern at L834, that
     // MUST run outside the meeting lock. We pre-evaluate eligibility from
     // the snapshot using the same predicate the mutate callback below
     // re-checks under lock; if the timeout has already advanced/cleared,
-    // the kill is a no-op on dispatch.json (no matching meetingId entries).
+    // the kill is a no-op in dispatch state (no matching meetingId entries).
     const snapshotRoundName = snapshot.status === 'investigating'
       ? 'investigate'
       : snapshot.status === 'debating'

package/engine/metrics-store.js

@@ -1,6 +1,6 @@
-// engine/metrics-store.js — SQL-backed implementation of engine/metrics.json.
+// engine/metrics-store.js — SQL-backed engine metrics.
 //
-// metrics.json is a single flat object whose top-level keys mix
+// Metrics expose a flat object whose top-level keys mix
 // per-agent counters with reserved keys (`_engine`, `_daily`,
 // `_contextPressure`). The store reconstructs that legacy shape for
 // reads, and reverses it for writes — each (kind, key) row holds one

package/engine/note-link-backfill.js

@@ -148,12 +148,7 @@ function repointItemNoteLinks(item, resolve) {
   return fixed;
 }
 
-// Repair broken note links across every work-items file (each project's plus
-// the central one), routed through shared.mutateWorkItems so the canonical SQL
-// store AND its JSON mirror stay consistent — the same write path the live
-// rewriter uses. Idempotent: only touches links that are provably broken AND
-// resolvable, so once healed a re-run writes nothing (skipWriteIfUnchanged).
-// Safe to call on every engine boot. Per-file try/catch isolates a bad scope.
+// Repair broken note links across every project scope plus central.
 function runNoteLinkBackfill(opts = {}) {
   const shared = require('./shared');
   const minionsDir = opts.minionsDir || shared.MINIONS_DIR;
@@ -172,14 +167,14 @@ function runNoteLinkBackfill(opts = {}) {
   const projects = Array.isArray(config.projects) ? config.projects : [];
   const candidates = [];
   for (const p of projects) {
-    if (p && p.name) candidates.push(path.join(minionsDir, 'projects', p.name, 'work-items.json'));
+    if (p && p.name) candidates.push(p);
   }
-  candidates.push(path.join(minionsDir, 'work-items.json'));
+  candidates.push('central');
 
   let scanned = 0, fixedItems = 0, fixedLinks = 0;
-  for (const wiPath of candidates) {
+  for (const scope of candidates) {
     try {
-      shared.mutateWorkItems(wiPath, (items) => {
+      shared.mutateWorkItems(scope, (items) => {
         if (!Array.isArray(items)) return items;
         for (const item of items) {
           if (!item) continue;
@@ -191,7 +186,7 @@ function runNoteLinkBackfill(opts = {}) {
         }
         return items;
       });
-    } catch { /* per-file isolation — one bad scope can't block the others */ }
+    } catch { /* one bad scope cannot block the others */ }
   }
 
   return { scanned, fixedItems, fixedLinks };

package/engine/pipeline.js

@@ -8,20 +8,18 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR, isPrdArchived } = shared;
+const { safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, 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');
 const { shouldRunNow } = require('./scheduler');
+const smallStateStore = require('./small-state-store');
 
 // All module-relative paths flow through MINIONS_DIR so MINIONS_TEST_DIR
 // (set by test/unit.test.js createTestMinionsDir) consistently redirects
 // pipeline writes into the temp root instead of the live runtime root.
 const PIPELINES_DIR = path.join(MINIONS_DIR, 'pipelines');
-const PIPELINE_RUNS_PATH = path.join(MINIONS_DIR, 'engine', 'pipeline-runs.json');
-const CENTRAL_WI_PATH = path.join(MINIONS_DIR, 'work-items.json');
 const MEETINGS_DIR = path.join(MINIONS_DIR, 'meetings');
 const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
-const PRD_DIR = path.join(MINIONS_DIR, 'prd');
 const NOTES_INBOX_DIR = path.join(MINIONS_DIR, 'notes', 'inbox');
 const NOTES_ARCHIVE_DIR = path.join(MINIONS_DIR, 'notes', 'archive');
 const CONFIG_PATH = path.join(MINIONS_DIR, 'config.json');
@@ -74,22 +72,11 @@ function deletePipeline(id) {
 // ── Run State ────────────────────────────────────────────────────────────────
 
 function getPipelineRuns() {
-  return safeJsonObj(PIPELINE_RUNS_PATH);
+  return smallStateStore.readPipelineRuns();
 }
 
-// W-mrcrh5hj0017d22f: SQL is the canonical (and only) work-items store post
-// Phase 9.4 — the JSON files (central work-items.json + each
-// projects/<name>/work-items.json) are passive, best-effort mirrors that can
-// legitimately lag behind a just-completed write (mirror failures are
-// swallowed by design so they never block the SQL write; see
-// work-items-store.js's `_mirrorJsonFromSql` comments). Reading those JSON
-// files directly (via safeJson/safeJsonArr) can therefore observe a work
-// item whose `status` mirrored to DONE but whose `resultSummary` write
-// hasn't landed in the mirror yet — which silently degraded stage-output
-// template substitution ({{stages.<id>.output}}) to the stage's own work
-// item id instead of its real completion text. Route every work-item read
-// in this module through the SQL-backed store so pipeline state always sees
-// the authoritative record.
+// 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();
 }
@@ -319,8 +306,8 @@ function _pipelineProjectSlug(project) {
   return project ? shared.safeSlugComponent(project.name || 'project', 32).toLowerCase() : 'central';
 }
 
-function _pipelineWorkItemsPath(project) {
-  return project ? shared.projectWorkItemsPath(project) : CENTRAL_WI_PATH;
+function _pipelineWorkItemScope(project) {
+  return project || 'central';
 }
 
 // ── Condition Evaluation ─────────────────────────────────────────────────────
@@ -435,7 +422,7 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
     for (const project of projectResolution.projects) {
       const projectSlug = _pipelineProjectSlug(project);
       const id = `PL-${run.runId.slice(4, 12)}-${stage.id}-${i}${projectResolution.projects.length > 1 || project ? '-' + projectSlug : ''}`;
-      const wiPath = _pipelineWorkItemsPath(project);
+      const wiScope = _pipelineWorkItemScope(project);
       const wiType = routing.normalizeWorkType(item.type || stage.taskType, WORK_TYPE.EXPLORE);
       // W-mp8ho6w500034a58: read-only stages don't commit, so a pipeline
       // branch label is meaningless to them — omit it entirely so the
@@ -443,7 +430,7 @@ function executeTaskStage(stage, stageState, run, config, pipeline = {}) {
       const wiBranch = READ_ONLY_ROOT_TASK_TYPES.has(wiType)
         ? null
         : `pipeline/${run.pipelineId}/${stage.id}`;
-      mutateWorkItems(wiPath, workItems => {
+      mutateWorkItems(wiScope, workItems => {
         if (workItems.some(w => w.id === id)) { createdIds.push(id); return workItems; }
         workItems.push({
           id,
@@ -574,12 +561,10 @@ const _VALID_EXISTING_PRD_STATUSES = new Set(Object.values(PLAN_STATUS));
 // permanently skip re-running plan-to-prd for a plan that never actually got
 // 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, prdDir) {
+function _findExistingPrdForPlan(planFile) {
   const prdFiles = require('./prd-store').listPrdRows().filter(row => !row.archived);
   const planKey = _canonicalPlanName(planFile);
   for (const { filename: pf, plan: prd } of prdFiles) {
-    // safeJsonNoRestore: PRDs are terminal artifacts — never restore archived
-    // PRDs from a stale .backup sidecar (W-mouptdh1000h9f39).
     if (!prd?.source_plan || _canonicalPlanName(path.basename(String(prd.source_plan))) !== planKey) continue;
     if (!(_VALID_EXISTING_PRD_STATUSES.has(prd.status) || isPrdArchived(prd)) || !Array.isArray(prd.missing_features)) {
       log('warn', `Pipeline plan-to-prd: found PRD "${pf}" for plan "${planFile}" but it lacks a valid status/missing_features (garbage/incomplete conversion) — treating plan-to-prd as not yet done`);
@@ -623,8 +608,7 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
       log('info', `Pipeline ${run.pipelineId}: reconciling plan stage — adopting existing plan "${existingPlanFile}"`);
 
       // Check if a PRD already exists for this plan (skip plan-to-prd entirely)
-      const prdDir = PRD_DIR;
-      const existingPrdFile = _findExistingPrdForPlan(existingPlanFile, prdDir);
+      const existingPrdFile = _findExistingPrdForPlan(existingPlanFile);
       if (existingPrdFile) {
         log('info', `Pipeline ${run.pipelineId}: PRD "${existingPrdFile}" already exists for plan "${existingPlanFile}" — skipping plan-to-prd`);
         return {
@@ -636,10 +620,10 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
       // Adopt or create plan-to-prd WIs atomically under lock for each target project.
       const adoptedWiIds = [];
       for (const project of targetProjects) {
-        const wiPath = _pipelineWorkItemsPath(project);
+        const wiScope = _pipelineWorkItemScope(project);
         const wiId = wiIdForProject(project);
         let adoptedWiId = wiId;
-        mutateWorkItems(wiPath, workItems => {
+        mutateWorkItems(wiScope, workItems => {
           const existing = workItems.find(w => w.type === WORK_TYPE.PLAN_TO_PRD && w.planFile === existingPlanFile);
           if (existing) {
             existing._pipelineRun = run.runId;
@@ -744,9 +728,9 @@ async function executePlanStage(stage, stageState, run, config, pipeline = {}) {
 
   const createdWiIds = [];
   for (const project of targetProjects) {
-    const wiPath = _pipelineWorkItemsPath(project);
+    const wiScope = _pipelineWorkItemScope(project);
     const wiId = wiIdForProject(project);
-    mutateWorkItems(wiPath, workItems => {
+    mutateWorkItems(wiScope, workItems => {
       if (!workItems.some(w => w.id === wiId)) {
         workItems.push({
           id: wiId,
@@ -986,7 +970,6 @@ function isStageComplete(stage, stageState, run, config) {
       if (!prdDone) return false;
 
       // Discover PRDs and their work items — collect into local arrays, then merge into artifacts
-      const prdDir = PRD_DIR;
       const plans = artifacts.plans || [];
       const discoveredPrds = [];
       const discoveredWiIds = [];
@@ -1019,9 +1002,8 @@ function isStageComplete(stage, stageState, run, config) {
       // Auto-approve if configured
       if (stage.autoApprove && artifacts.prds?.length > 0) {
         for (const prdFile of artifacts.prds) {
-          const prdPath = path.join(prdDir, prdFile);
           let approved = false;
-          mutateJsonFileLocked(prdPath, (prd) => {
+          require('./prd-store').mutatePrd(prdFile, (prd) => {
             if (prd && prd.status === PLAN_STATUS.AWAITING_APPROVAL) {
               prd.status = PLAN_STATUS.APPROVED;
               prd.approvedAt = ts();
@@ -1029,7 +1011,7 @@ function isStageComplete(stage, stageState, run, config) {
               approved = true;
             }
             return prd;
-          }, { skipWriteIfUnchanged: true });
+          });
           if (approved) log('info', `Pipeline ${run.pipelineId}: auto-approved PRD ${prdFile}`);
         }
       }
@@ -1047,7 +1029,7 @@ function isStageComplete(stage, stageState, run, config) {
       if (prIds.length === 0) return true; // nothing to merge
       const projects = shared.getProjects(config);
       for (const project of projects) {
-        const prs = safeJsonArr(shared.projectPrPath(project));
+        const prs = shared.readPullRequests(project);
         for (const prId of prIds) {
           const pr = shared.findPrRecord(prs, prId, project);
           if (pr && pr.status !== PR_STATUS.MERGED && pr.status !== PR_STATUS.ABANDONED) return false;

package/engine/playbook.js

@@ -1077,7 +1077,7 @@ function buildSystemPrompt(agentId, config, project) {
   prompt += `2. ${getRepoHostToolRule(project)}\n`;
   prompt += `3. Follow the project conventions in CLAUDE.md if present\n`;
   prompt += `4. Write learnings to the path specified in the task prompt (format: \`notes/inbox/{agent}-{work-item-id}-{date}-{time}.md\`)\n`;
-  prompt += `5. Agent status is managed by the engine via dispatch.json — agents do not need to track their own status\n\n`;
+  prompt += `5. Agent status is managed by the engine — agents do not need to track their own status\n\n`;
 
   // The lean system prompt (identity + rules) does not contain task-dispatch
   // sections (## Your Task, ## Tools, ## Constraints) by design — those live

package/engine/pooled-agent-process.js

@@ -45,9 +45,15 @@ class PooledAgentProcess extends EventEmitter {
    * @param {string} [opts.effort]
    * @param {Array} [opts.mcpServers]
    * @param {Array<string>} [opts.hermeticDirs]
-   * @param {string} opts.promptText - fully-built prompt (runtime.buildPrompt output)
+   * @param {object} [opts.processEnv] - worker-process environment
+   * @param {object} [opts.sessionContext] - trusted values scoped to this lease
+   * @param {string} [opts.systemPromptText] - trusted system instructions
+   * @param {string} opts.promptText - task/user prompt only
    */
-  constructor({ pool, dispatchId, cwd, model, effort, mcpServers, hermeticDirs, promptText }) {
+  constructor({
+    pool, dispatchId, cwd, model, effort, mcpServers, hermeticDirs,
+    processEnv, sessionContext, systemPromptText, promptText,
+  }) {
     super();
     this.pid = null;
     this.killed = false;
@@ -63,14 +69,21 @@ class PooledAgentProcess extends EventEmitter {
     // Fire-and-forget, mirroring child_process.spawn()'s async nature — the
     // facade is usable (event listeners can be attached) immediately, before
     // the underlying ACP worker has actually been acquired.
-    this._start({ cwd, model, effort, mcpServers, hermeticDirs, promptText });
+    this._start({
+      cwd, model, effort, mcpServers, hermeticDirs,
+      processEnv, sessionContext, systemPromptText, promptText,
+    });
   }
 
-  async _start({ cwd, model, effort, mcpServers, hermeticDirs, promptText }) {
+  async _start({
+    cwd, model, effort, mcpServers, hermeticDirs,
+    processEnv, sessionContext, systemPromptText, promptText,
+  }) {
     let handle;
     try {
       handle = await this._pool.acquireWorker({
         dispatchId: this._dispatchId, cwd, model, effort, mcpServers, hermeticDirs,
+        processEnv, sessionContext,
       });
     } catch (err) {
       // Mirrors child_process's 'error' event (spawn failed) — engine.js's
@@ -95,28 +108,35 @@ class PooledAgentProcess extends EventEmitter {
     this.emit('acquired');
 
     let sawError = false;
-    await handle.stream(promptText, {
-      onChunk: (text) => {
-        if (!text) return;
-        this._writeStdoutEvent({ type: 'assistant.message_delta', data: { deltaContent: text } });
-      },
-      onDone: (result) => {
-        this._writeStdoutEvent({
-          type: 'result',
-          sessionId: handle.sessionId || null,
-          usage: {
-            totalApiDurationMs: Date.now() - this._startedAt,
-            stopReason: (result && result.stopReason) || null,
-          },
-        });
-      },
-      onError: (err) => {
-        sawError = true;
-        try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
-      },
-    });
-
-    try { handle.release(); } catch { /* best-effort */ }
+    try {
+      await handle.stream(promptText, {
+        systemPromptText,
+        onChunk: (text) => {
+          if (!text) return;
+          this._writeStdoutEvent({ type: 'assistant.message_delta', data: { deltaContent: text } });
+        },
+        onDone: (result) => {
+          this._writeStdoutEvent({
+            type: 'result',
+            sessionId: handle.sessionId || null,
+            usage: {
+              totalApiDurationMs: Date.now() - this._startedAt,
+              stopReason: (result && result.stopReason) || null,
+            },
+          });
+        },
+        onError: (err) => {
+          sawError = true;
+          try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
+        },
+      });
+    } catch (err) {
+      sawError = true;
+      try { this.stderr.write(String((err && err.message) || err) + '\n'); } catch { /* best-effort */ }
+    } finally {
+      try { handle.release(); } catch { /* best-effort */ }
+      this._handle = null;
+    }
     this._finish(sawError ? 1 : 0);
   }