@yemi33/minions 0.1.2378 → 0.1.2379

package/docs/README.md

@@ -41,6 +41,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [cross-repo-plans.md](cross-repo-plans.md) — Cross-repo plans: a single plan whose work items ship into two or more configured projects — per-item `project` field, per-project work-item fan-out, and one verify work item per touched repo.
 - [dead-code-audit-retractions.md](dead-code-audit-retractions.md) — Retracted dead-code-audit findings (false positives) that future audits MUST read before re-citing.
 - [deprecated-process.md](deprecated-process.md) — Schema for `docs/deprecated.json` and the weekly `cleanup-deprecated` audit walk that retires entries past their removal signal.
+- [design-inbox-entries-schema.md](design-inbox-entries-schema.md) — Implemented SQL schema and store contract for the future operator/agent inbox queue, including current indexes, mutators, event emission, and integration status.
 - [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` (accepted; implementation tracked in CHANGELOG.md Phases 0–10).
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
 - [harness-propagation.md](harness-propagation.md) — The native runtime

package/docs/design-inbox-entries-schema.md

@@ -1,7 +1,7 @@
 # inbox_entries Table Schema
 
 ## Overview
-The `inbox_entries` table is the persistent store for operator and agent inbox messages within the Minions orchestration engine. It provides a time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle.
+The `inbox_entries` table and `engine/inbox-store.js` implement a persistent, time-ordered, unread-tracking message queue decoupled from the runtime work-item/dispatch lifecycle. The store API exists, but production engine, dashboard, and consolidation paths do not consume it yet; those paths still use their existing inbox mechanisms.
 
 ## Schema Specification
 
@@ -9,26 +9,27 @@ The `inbox_entries` table is the persistent store for operator and agent inbox m
 
 | Column | Type | Constraints | Purpose |
 |--------|------|-----------|---------|
-| `id` | TEXT | PRIMARY KEY | Unique message identifier; generated as `<recipient>-<timestamp>-<sender>-<seq>` format |
+| `id` | TEXT | PRIMARY KEY | Unique message identifier; generated as `<recipient>-<timestamp>-<sender>-<seq>-<counter>-<random>` |
 | `recipient_session_id` | TEXT | NOT NULL | Session ID of the inbox owner (operator or agent); routes messages to specific actor |
 | `sender_id` | TEXT | NOT NULL | Identifier of the message originator; structured as `<agent-id>` or `'system'` or `'operator'` |
 | `sender_name` | TEXT | NOT NULL | Human-readable sender name for UI display; persisted at write-time for offline/archived reference |
-| `sender_type` | TEXT | NOT NULL | Enum: `'agent'`, `'system'`, `'operator'`; constrains allowed sender_id values |
-| `interaction_id` | TEXT | NOT NULL | Group ID linking related messages (e.g., work-item dispatch feedback, PR review batch); enables threading and deduplication |
-| `sequence` | INTEGER | NOT NULL, DEFAULT 0 | Per-interaction message counter; disambiguates bursts and enables ordering within same millisecond |
+| `sender_type` | TEXT | NOT NULL | Sender category; `createInboxEntry()` accepts `'agent'`, `'system'`, or `'operator'` |
+| `interaction_id` | TEXT | NOT NULL | Caller-supplied group ID for related messages |
+| `sequence` | INTEGER | NOT NULL, DEFAULT 0 | Caller-supplied per-interaction ordering metadata; not required to be unique |
 | `summary` | TEXT | NOT NULL | Title/subject line; used for list views and user scanning; always present even if content is truncated |
 | `content` | TEXT | NOT NULL | Full message body; may contain Markdown, code blocks, or structured JSON sidecars (not yet parsed at table level) |
-| `unread` | INTEGER | NOT NULL, DEFAULT 1 | Boolean flag (0/1); toggled by reader, cleared on archive/delete; enables fast unread-count queries |
+| `unread` | INTEGER | NOT NULL, DEFAULT 1 | Boolean flag (0/1); changed by the read/unread mutators |
 | `sent_at` | INTEGER | NOT NULL | Unix timestamp (milliseconds) of message creation; primary sort key for time-ordered display |
 | `read_at` | INTEGER | Nullable | Unix timestamp (milliseconds) when recipient first read the message; null until marked read |
 | `notified_at` | INTEGER | Nullable | Unix timestamp (milliseconds) of last notification event sent to operator; null if no notification dispatched |
 
 ### Constraints & Relationships
 
-- **PK constraint:** `id` is globally unique across all inboxes; collision risk is negligible given the composite structure (recipient + timestamp + sender + seq).
+- **PK constraint:** `id` is globally unique across all inboxes. The store combines caller context with a process-local counter and random suffix, then retries a conflicting insert up to five times.
 - **FK (soft):** `recipient_session_id` does NOT enforce a referential constraint to `sessions` table (sessions may be archived). Queries SHOULD handle missing recipients gracefully.
-- **FK (soft):** `sender_id` is informational only; no validation that the sender exists in the `config.agents` or active sessions. Invalid senders are logged but do not block writes.
-- **No composite index on (recipient_session_id, sent_at):** See Performance section.
+- **FK (soft):** `sender_id` is informational only; no validation requires it to exist in `config.agents` or active sessions.
+- **Application validation:** `createInboxEntry()` accepts only `agent`, `system`, or `operator` for `sender_type`; SQLite does not enforce that enum.
+- **Indexes:** Migration 019 creates composite recipient/time and interaction indexes. See Performance Considerations.
 
 ## Architectural Rationale
 
@@ -36,71 +37,62 @@ The `inbox_entries` table is the persistent store for operator and agent inbox m
 
 1. **Separate inbox table vs. inline dispatch/work-item attachments.**
    - Inboxes can outlive their source work items (e.g., a feedback message remains useful after the WI is done).
-   - Decoupling allows independent inbox lifecycle (archive, export, cleanup) without cascading work-item deletes.
-   - Supports rich async consolidation (team notes, KB articles) that don't belong to any single WI.
+   - Decoupling allows independent read/unread and deletion lifecycle without cascading work-item deletes.
 
 2. **`unread` flag instead of soft-delete or status enum.**
    - Fast count queries for badge (`SELECT COUNT(*) WHERE recipient_session_id = ? AND unread = 1`).
-   - Unread state is mutable; allows mark-as-read UX without data loss.
-   - Simplifies archive/export (no tombstone filtering needed).
+   - Unread state is mutable; allows mark-as-read and mark-as-unread behavior without deleting content.
 
 3. **`sender_type` as an explicit column.**
-   - Allows schema validation (e.g., "agent" senders must have valid IDs; "system" is always valid).
+   - Allows application-level validation of the sender category.
    - Enables filtered views ("show only agent messages" or "system alerts only") without string parsing.
 
 4. **`interaction_id` for grouping.**
-   - Enables undo/redo on related messages (e.g., canceling all build-failure notifications from one dispatch).
-   - Supports consolidation: multiple small notifications can be collapsed into one summary message.
+   - `getInboxByInteraction()` retrieves related messages in chronological order.
 
 5. **Persistent `sender_name` at write-time.**
    - Operator may rename agents or disable them; storing the name ensures historical accuracy.
-   - UI doesn't need to perform runtime lookups on archived inboxes.
+   - Future consumers can render the stored name without a runtime agent lookup.
 
 6. **Unix timestamps (milliseconds) instead of ISO strings.**
    - Enables range queries (`sent_at BETWEEN ? AND ?`) without parsing.
    - Smaller column footprint; easier to sort.
    - Downside: not human-readable; UI must convert to locale strings.
 
-### Entity Relationships
+### Integration Status
 
-- **inbox_entries ← dispatch WI feedback:** A failed dispatch may create multiple inbox entries (error summary, retry recommendation, logs snippet). Threaded via `interaction_id`.
-- **inbox_entries ← PR reviews:** Humans and auto-review agents post comments; summarized as inbox alerts to project owners via `interaction_id` per-PR.
-- **inbox_entries ← consolidation:** `engine/consolidation.js` reads inbox entries to extract `agent:` frontmatter and route findings into per-agent knowledge files.
+The table currently has no foreign keys and `engine/inbox-store.js` has no production callers. Dispatch feedback, PR notifications, dashboard inbox views, and consolidation are potential consumers, not implemented relationships. Until those call sites migrate, this table is not the source of truth for `notes/inbox/` or agent steering inbox files.
 
 ## Performance Considerations
 
 ### Indexing Strategy
 
-**Current indexes (recommended):**
-- `idx_recipient_sent` on `(recipient_session_id, sent_at DESC)` — enables efficient "unread count" and "latest N messages" queries without table scans.
-- `idx_interaction` on `(interaction_id)` — enables grouping/dedup queries (e.g., "was this interaction already notified?").
+**Current indexes (created by migration 019):**
+- `idx_inbox_recipient_sent` on `(recipient_session_id, sent_at DESC)` — supports recipient-scoped chronological reads.
+- `idx_inbox_interaction` on `(interaction_id)` — supports grouping by interaction.
 - PK `id` is implicit index.
 
 **Query patterns:**
-- **Unread count per session:** `SELECT COUNT(*) WHERE recipient_session_id = ? AND unread = 1` → must scan `idx_recipient_sent` to avoid full table.
-- **Latest messages:** `SELECT * WHERE recipient_session_id = ? ORDER BY sent_at DESC LIMIT 20` → seeks on `idx_recipient_sent` DESC.
-- **Thread view:** `SELECT * WHERE interaction_id = ? ORDER BY sent_at` → seeks on `idx_interaction`, then sorts in application or via secondary index.
-- **Cleanup:** `DELETE WHERE sent_at < ? AND unread = 0` → full table scan (acceptable; cleanup is infrequent, low-priority background task).
+- **Unread count per session:** `SELECT COUNT(*) ... WHERE recipient_session_id = ? AND unread = 1` narrows by recipient, then filters `unread`.
+- **Latest messages:** `SELECT * ... WHERE recipient_session_id = ? ORDER BY sent_at DESC LIMIT ? OFFSET ?` uses `idx_inbox_recipient_sent`.
+- **Thread view:** `SELECT * ... WHERE interaction_id = ? ORDER BY sent_at ASC` uses `idx_inbox_interaction`, then sorts matching rows.
+- **Cleanup:** `deleteInboxEntriesOlderThan(timestampMs, { unreadOnly })` deletes all older rows by default or only rows with `unread = 1`; no production cleanup job calls it yet.
 
 **Missing indexes (future optimization):**
 - `idx_sender_id` — if queries like "messages from this agent" are common, consider adding.
 - `idx_unread` — if badge ("N unread") is a hot query, consider combining with recipient (`idx_recipient_unread` on `(recipient_session_id, unread)`).
 
-### Size Estimates & Cleanup
+### Cleanup
 
-- **Row size:** ~500–2000 bytes (summary + content; content can be verbose with logs/code snippets).
-- **Growth:** ~5–50 entries/day (depends on agent activity and verbose flagging).
-- **Retention:** No automatic cleanup; operators may archive/export and manually delete aged entries. Engine does NOT auto-prune.
-- **Recommended**: Implement a dashboard setting to soft-delete entries older than N days (default 30) with an undo/export option.
+- **Retention:** No automatic cleanup is wired. The store exposes explicit single, batch, and age-based hard-delete helpers.
 
 ## Migration & Backward Compatibility
 
-- **Migration 018 or later** creates `inbox_entries` as part of SQL state cutover. Legacy `inbox/` Markdown files are NOT imported; operators must re-send or manually recreate critical messages.
-- **No schema versioning needed** for now; table is immutable-append-only (reads/writes only).
+- **Migration 019** creates `inbox_entries` and its two secondary indexes. It does not import existing Markdown inbox files.
+- The store supports inserts, read/unread updates, notification timestamps, and hard deletes. Every mutator attempts a best-effort `inbox` state event after a real change so dashboard cache versions can advance once consumers are wired.
 
 ## Related Code
 
-- **Writes:** `engine/inbox-store.js` (primary mutator; uses `getDb()` and `emitStateEvent`).
-- **Reads:** `engine/queries.js#getInboxForSession()`, dashboard `/api/inbox`, `engine/consolidation.js`.
-- **UI:** `dashboard/pages/inbox.html`, `dashboard/js/inbox.js`.
-
+- **Schema:** `engine/db/migrations/019-inbox-entries.js`.
+- **Store:** `engine/inbox-store.js` (reads, transactional mutators, and best-effort `emitStateEvent('inbox', ...)` after real changes).
+- **Consumers:** none in production yet.

package/engine/acp-transport.js

@@ -97,9 +97,10 @@ const WARM_MAX_CONCURRENT = 3;
 // W-mqid8uev). resolveBinary() resolves the real JS entry
 // (node_modules/@github/copilot/index.js) and reports whether to spawn it
 // directly (native) or under the current Node process (shim).
-function spawnAcp({ cwd } = {}) {
+function spawnAcp({ cwd, env } = {}) {
   const copilot = require('./runtimes/copilot');
-  const resolved = copilot.resolveBinary({ env: process.env });
+  const workerEnv = env || process.env;
+  const resolved = copilot.resolveBinary({ env: workerEnv });
   if (!resolved || !resolved.bin) {
     throw new Error(
       `copilot binary not resolvable -- ${copilot.installHint || 'install the GitHub Copilot CLI'}`
@@ -114,6 +115,7 @@ function spawnAcp({ cwd } = {}) {
   return spawn(execBin, execArgs, {
     stdio: ['pipe', 'pipe', 'pipe'],
     cwd: cwd || process.cwd(),
+    env: workerEnv,
     windowsHide: true,
     // Don't pass shell:true — the native/leadingArgs handling above already
     // produces a directly-spawnable argv, and a shell wrapper would swallow
@@ -139,6 +141,33 @@ function hashMcpServers(mcpServers) {
   return crypto.createHash('sha256').update(json).digest('hex');
 }
 
+function _stableObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+
+function hashProcessContext(processEnv) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(_stableObject(processEnv)))
+    .digest('hex');
+}
+
+function buildTrustedSessionContext(sessionContext) {
+  const context = _stableObject(sessionContext);
+  if (Object.keys(context).length === 0) return '';
+  const json = JSON.stringify(context, null, 2).replace(/<\/system/gi, '<\\/system');
+  return [
+    'Trusted pooled-dispatch context (session-scoped):',
+    'These values are the authoritative equivalents of the same-named environment variables for this ACP session.',
+    'Use them directly; do not try to recover them from the reusable worker process environment.',
+    json,
+  ].join('\n');
+}
+
 // Bug B (issue #2479): `model` and `effort` were stored on the Worker but
 // never forwarded to ACP `session/new`, so any model override was silently
 // dropped. Build the params object here and only include fields that are
@@ -216,12 +245,17 @@ function mapAcpToolCallToToolUse(update) {
  * logger (default no-op); consumers wire their own env-gated trace prefix.
  */
 class Worker {
-  constructor({ id, model, effort, mcpServers, mcpServersHash, systemPromptHash, cwd, internals, trace }) {
+  constructor({
+    id, model, effort, mcpServers, mcpServersHash, processEnv, processContextHash,
+    systemPromptHash, cwd, internals, trace,
+  }) {
     this.id = id;
     this.model = model;
     this.effort = effort;
     this.mcpServers = mcpServers || [];
     this.mcpServersHash = mcpServersHash;
+    this.processEnv = processEnv;
+    this.processContextHash = processContextHash;
     this.systemPromptHash = systemPromptHash;
     this.cwd = cwd || process.cwd();
     this._internals = internals;
@@ -249,7 +283,7 @@ class Worker {
   async _spawnAndInit() {
     let proc;
     try {
-      proc = this._internals.spawnAcp({ cwd: this.cwd });
+      proc = this._internals.spawnAcp({ cwd: this.cwd, env: this.processEnv });
     } catch (err) {
       // spawn() threw synchronously — typically ENOENT (copilot binary not
       // on PATH) or EACCES. Surface as worker-spawn-failed so the consumer
@@ -440,7 +474,10 @@ class Worker {
 
   // ── Stream a single turn ───────────────────────────────────────────────
   stream(promptText, opts = {}) {
-    const { onChunk, onToolUse, onToolUpdate, onDone, onError, signal, systemPromptText } = opts;
+    const {
+      onChunk, onToolUse, onToolUpdate, onDone, onError, signal,
+      systemPromptText, trustedSessionContext, deferSystemPrompt,
+    } = opts;
     if (this.killed) {
       const err = new Error('acp-transport: worker is closed');
       if (onError) try { onError(err); } catch { /* swallow */ }
@@ -458,10 +495,12 @@ class Worker {
     // adapter pattern of <system>...</system> prepended to the first user
     // message remains correct.
     let prompt = promptText;
-    if (!this.firstSystemPromptSent && systemPromptText) {
-      prompt = `<system>\n${systemPromptText}\n</system>\n\n${promptText}`;
+    const trustedContextText = buildTrustedSessionContext(trustedSessionContext);
+    const trustedSystemText = [systemPromptText, trustedContextText].filter(Boolean).join('\n\n');
+    if (!this.firstSystemPromptSent && trustedSystemText) {
+      prompt = `<system>\n${trustedSystemText}\n</system>\n\n${promptText}`;
     }
-    this.firstSystemPromptSent = true;
+    if (!deferSystemPrompt) this.firstSystemPromptSent = true;
 
     const id = this.nextReqId++;
     const inflight = {
@@ -586,6 +625,8 @@ module.exports = {
   spawnAcp,
   killImmediate,
   hashMcpServers,
+  hashProcessContext,
+  buildTrustedSessionContext,
   buildSessionNewParams,
   extractChunkText,
   mapAcpToolCallToToolUse,

package/engine/agent-worker-pool.js

@@ -59,7 +59,7 @@
  */
 
 const transport = require('./acp-transport');
-const { Worker, hashMcpServers } = transport;
+const { Worker, hashMcpServers, hashProcessContext } = transport;
 
 // Test seam — mirrors engine/cc-worker-pool.js's `_internals` pattern, but is
 // its OWN object (constructor-injected into Worker per acquisition) so this
@@ -106,6 +106,7 @@ let _nextWorkerId = 1;
 const _free = [];              // Worker[] — idle, unleased
 const _busy = new Map();       // dispatchId → Worker — currently leased
 const _queue = [];             // pending acquire requests, FIFO
+const _leaseContexts = new Map(); // dispatchId → mutable session-only context
 // Slots reserved for a worker that's mid-reuse/respawn/fresh-spawn — pulled
 // out of `_free` (or not yet spawned) but not yet placed in `_busy`. Counted
 // toward `_poolSize` so a burst of concurrent acquireWorker calls can't
@@ -130,7 +131,10 @@ function _pump() {
   while (_queue.length > 0) {
     const req = _queue[0];
 
-    const matchIdx = _free.findIndex((w) => w.mcpServersHash === req.mcpServersHash);
+    const matchIdx = _free.findIndex((w) =>
+      w.mcpServersHash === req.mcpServersHash
+      && w.processContextHash === req.processContextHash
+    );
     if (matchIdx >= 0) {
       _queue.shift();
       const worker = _free.splice(matchIdx, 1)[0];
@@ -215,6 +219,8 @@ async function _bootWorker(req) {
     effort: req.effort,
     mcpServers: req.mcpServers,
     mcpServersHash: req.mcpServersHash,
+    processEnv: req.processEnv,
+    processContextHash: req.processContextHash,
     cwd: req.cwd,
     internals: _internals,
     trace: _trace,
@@ -246,6 +252,7 @@ function _onWorkerExit(worker) {
   for (const [dispatchId, w] of _busy) {
     if (w === worker) {
       _busy.delete(dispatchId);
+      _clearLeaseContext(dispatchId);
       removed = true;
       break;
     }
@@ -272,6 +279,7 @@ async function _applyHermeticDirs(worker, hermeticDirs) {
       worker.stream(`/add-dir ${dir}`, {
         onDone: () => { _trace(`worker=${worker.id} add-dir ok: ${dir}`); resolve(); },
         onError: (err) => { _trace(`worker=${worker.id} add-dir failed: ${dir} (${err && err.message})`); resolve(); },
+        deferSystemPrompt: true,
       }).catch(() => resolve());
     });
   }
@@ -279,9 +287,19 @@ async function _applyHermeticDirs(worker, hermeticDirs) {
 
 // ── Public API ────────────────────────────────────────────────────────────
 
-async function acquireWorker({ dispatchId, cwd, model, effort, mcpServers, hermeticDirs } = {}) {
+function _clearLeaseContext(dispatchId) {
+  const context = _leaseContexts.get(dispatchId);
+  if (!context) return false;
+  for (const key of Object.keys(context)) delete context[key];
+  _leaseContexts.delete(dispatchId);
+  return true;
+}
+
+async function acquireWorker({
+  dispatchId, cwd, model, effort, mcpServers, hermeticDirs, processEnv, sessionContext,
+} = {}) {
   if (!dispatchId) throw new Error('agent-worker-pool.acquireWorker: dispatchId is required');
-  if (_busy.has(dispatchId)) {
+  if (_busy.has(dispatchId) || _leaseContexts.has(dispatchId)) {
     throw new Error(
       `agent-worker-pool.acquireWorker: dispatchId ${dispatchId} already has an active worker ` +
       '(1 worker : 1 active dispatch invariant — call release() before acquiring again)'
@@ -289,16 +307,34 @@ async function acquireWorker({ dispatchId, cwd, model, effort, mcpServers, herme
   }
 
   const mcpServersHash = hashMcpServers(mcpServers);
-  const req = { dispatchId, cwd, model, effort, mcpServers, mcpServersHash };
+  const workerProcessEnv = processEnv && typeof processEnv === 'object'
+    ? Object.freeze({ ...processEnv })
+    : undefined;
+  const processContextHash = hashProcessContext(workerProcessEnv);
+  const leaseContext = sessionContext && typeof sessionContext === 'object'
+    ? { ...sessionContext }
+    : {};
+  const req = {
+    dispatchId, cwd, model, effort, mcpServers, mcpServersHash,
+    processEnv: workerProcessEnv, processContextHash,
+  };
+  _leaseContexts.set(dispatchId, leaseContext);
 
-  const worker = await new Promise((resolve, reject) => {
-    req.resolve = resolve;
-    req.reject = reject;
-    _queue.push(req);
-    _pump();
-  });
+  let worker;
+  try {
+    worker = await new Promise((resolve, reject) => {
+      req.resolve = resolve;
+      req.reject = reject;
+      _queue.push(req);
+      _pump();
+    });
 
-  await _applyHermeticDirs(worker, hermeticDirs);
+    await _applyHermeticDirs(worker, hermeticDirs);
+    if (worker.killed) throw new Error('agent-worker-pool: worker died during acquisition');
+  } catch (err) {
+    _clearLeaseContext(dispatchId);
+    throw err;
+  }
   _busy.set(dispatchId, worker);
 
   return {
@@ -311,8 +347,20 @@ async function acquireWorker({ dispatchId, cwd, model, effort, mcpServers, herme
     // captured copy), since sessionId can rotate under a reused worker.
     get pid() { return (worker.proc && worker.proc.pid) || null; },
     get sessionId() { return worker.sessionId || null; },
-    stream: (promptText, opts) => worker.stream(promptText, opts),
-    cancel: () => worker.cancel(),
+    stream: async (promptText, opts = {}) => {
+      try {
+        return await worker.stream(promptText, {
+          ...opts,
+          trustedSessionContext: leaseContext,
+        });
+      } finally {
+        _clearLeaseContext(dispatchId);
+      }
+    },
+    cancel: () => {
+      _clearLeaseContext(dispatchId);
+      return worker.cancel();
+    },
     release: () => release(dispatchId),
   };
 }
@@ -325,6 +373,7 @@ async function acquireWorker({ dispatchId, cwd, model, effort, mcpServers, herme
 // never acquired) — safe to call defensively.
 function release(dispatchId) {
   const worker = _busy.get(dispatchId);
+  _clearLeaseContext(dispatchId);
   if (!worker) return false;
   _busy.delete(dispatchId);
   if (worker.killed) {
@@ -340,6 +389,7 @@ function release(dispatchId) {
 
 function shutdown() {
   for (const req of _queue.splice(0)) {
+    _clearLeaseContext(req.dispatchId);
     try { req.reject(new Error('agent-worker-pool: shutdown')); } catch { /* swallow */ }
   }
   for (const worker of _free.splice(0)) {
@@ -349,6 +399,7 @@ function shutdown() {
     try { worker.close(); } catch { /* swallow */ }
   }
   _busy.clear();
+  for (const dispatchId of [..._leaseContexts.keys()]) _clearLeaseContext(dispatchId);
   _reserved = 0;
 }
 
@@ -364,4 +415,5 @@ module.exports = {
   _free,
   _busy,
   _queue,
+  _leaseContexts,
 };

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);
   }
 

package/engine.js

@@ -4693,13 +4693,24 @@ async function spawnAgent(dispatchItem, config) {
       });
     } else {
       // P-1d8f0b93 — pooled copilot dispatch. No separate spawn-agent.js
-      // child process exists, so build the SAME combined prompt text that
-      // process would have received via runtime.buildPrompt(...) directly
-      // here, and hand it to a PooledAgentProcess facade instead of
-      // cold-spawning. Everything downstream (stdout/stderr handlers,
+      // child process exists, so hand the task and trusted system context to
+      // the PooledAgentProcess separately instead of cold-spawning. Everything
+      // downstream (stdout/stderr handlers,
       // onAgentClose, live-output.log, PID-file writing below) treats `proc`
       // identically to a real child_process either way.
-      const pooledPromptText = runtime.buildPrompt(fullTaskPrompt, systemPrompt, { sessionId: cachedSessionId });
+      const pooledSessionKeys = [
+        'MINIONS_COMPLETION_REPORT',
+        'MINIONS_COMPLETION_NONCE',
+        'MINIONS_LIVE_OUTPUT_PATH',
+        'MINIONS_STEERING_ACK_DIR',
+        'MINIONS_AGENT_CWD',
+      ];
+      const pooledProcessEnv = { ...childEnv };
+      const pooledSessionContext = {};
+      for (const key of pooledSessionKeys) {
+        if (pooledProcessEnv[key] !== undefined) pooledSessionContext[key] = pooledProcessEnv[key];
+        delete pooledProcessEnv[key];
+      }
       proc = new PooledAgentProcess({
         pool: agentWorkerPool,
         dispatchId: id,
@@ -4710,7 +4721,10 @@ async function spawnAgent(dispatchItem, config) {
         // flat top-level config array, not per-agent-resolved.
         mcpServers: (engineConfig && engineConfig.mcpServers) || [],
         hermeticDirs: addDirs,
-        promptText: pooledPromptText,
+        processEnv: pooledProcessEnv,
+        sessionContext: pooledSessionContext,
+        systemPromptText: systemPrompt,
+        promptText: fullTaskPrompt,
       });
       // The child_process PID file is normally written asynchronously by
       // spawn-agent.js itself (engine/spawn-agent.js:606) once it starts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2378",
+  "version": "0.1.2379",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"