@yemi33/minions 0.1.2377 → 0.1.2379

package/dashboard/js/refresh.js

@@ -130,7 +130,8 @@ function _detectPageChanges(data) {
 // for the same input. Cross-restart safety lives in the dashboardBuildId
 // reload path below — RENDER_VERSIONS handles the within-process case.
 const RENDER_VERSIONS = {
-  agents: 2,
+  // Bumped 2→3 for client-ticked relative last-action timestamps.
+  agents: 3,
   prdProgress: 2,
   prdPrs: 1,
   inbox: 2,
@@ -516,17 +517,19 @@ function _processStatusUpdate(data, opts) {
   // the /api/work-items + /api/pull-requests .then handlers
   // (_fireCrossSliceRender) where the FRESH fetched lists are available.
   // Agents now come from /api/agents — a dedicated fresh-JSON endpoint with
-  // input-mtime ETag (issue #2949). No /api/status outer cache in the path.
+  // input-mtime ETag (issue #2949). Conditional requests keep unchanged polls
+  // from reparsing the roster and rebuilding every card/timer.
   // cmdUpdateAgentList consumes the same slice but renders the command-line
   // chip pop-up so we feed it the fresh array too.
   _safeRender('agents', function() {
     const seq = (window._refreshSeq = (window._refreshSeq || 0) + 1);
     window._lastRequestedSeq = window._lastRequestedSeq || {};
     window._lastRequestedSeq.agents = seq;
-    fetch('/api/agents')
-      .then(function (r) { return r.ok ? r.json() : Promise.reject(); })
-      .then(function (fresh) {
+    _condFetchJson('/api/agents')
+      .then(function (resp) {
         if (seq < (window._lastRequestedSeq.agents || 0)) return;
+        if (resp.notModified) return;
+        const fresh = resp.data;
         const list = Array.isArray(fresh) ? fresh : window._lastAgents;
         if (list) window._lastAgents = list;
         _safeRender('agents', function() { renderAgents(list); });

package/dashboard/js/render-agents.js

@@ -44,6 +44,34 @@ function _modelChipHtml(model) {
   return '<span class="agent-model-tag" title="Model: ' + escapeHtml(model) + '" style="font-size:var(--text-xs);font-weight:600;letter-spacing:0.4px;padding:1px 5px;margin-left:4px;border:1px solid var(--muted);border-radius:3px;color:var(--muted);background:transparent">' + escapeHtml(model) + '</span>';
 }
 
+function _agentHasTimedAction(agent) {
+  return !!(agent && agent.lastActionPrefix && Number.isFinite(Number(agent.lastActionAt)));
+}
+
+function _formatAgentAction(prefix, actionAt, fallback) {
+  var actionAtMs = Number(actionAt);
+  var text = prefix && Number.isFinite(actionAtMs)
+    ? String(prefix) + ' (' + timeAgo(actionAtMs) + ')'
+    : String(fallback || '');
+  return text.length > 120 ? text.slice(0, 120) + '...' : text;
+}
+
+function _agentLastActionText(agent) {
+  return _formatAgentAction(agent.lastActionPrefix, agent.lastActionAt, agent.lastAction);
+}
+
+function _agentTimedActionAttrs(agent) {
+  return _agentHasTimedAction(agent)
+    ? ' data-action-prefix="' + escapeHtml(agent.lastActionPrefix) + '" data-action-at="' + Number(agent.lastActionAt) + '"'
+    : '';
+}
+
+function _agentActionHtml(agent) {
+  var text = _agentLastActionText(agent);
+  var attrs = _agentTimedActionAttrs(agent);
+  return '<div class="agent-action"' + attrs + ' title="' + escapeHtml(text) + '">' + escapeHtml(text) + '</div>';
+}
+
 function renderAgents(agents) {
   agentData = agents;
   const grid = document.getElementById('agents-grid');
@@ -56,7 +84,7 @@ function renderAgents(agents) {
         <span class="status-badge ${escapeHtml(a.status)}">${escapeHtml(a.status)}</span>
       </div>
       <div class="agent-role">${escapeHtml(a.role)}</div>
-      <div class="agent-action" title="${escapeHtml(a.lastAction)}">${escapeHtml(a.lastAction)}</div>
+      ${_agentActionHtml(a)}
       ${(function() {
         var s = a.started_at, c = a.completed_at;
         if (s && c) { var d = new Date(c) - new Date(s); if (d > 0) { var sec = Math.floor(d/1000)%60, min = Math.floor(d/60000)%60, hr = Math.floor(d/3600000); return '<div style="font-size:var(--text-xs);color:var(--muted)">Last run: ' + (hr > 0 ? hr + 'h ' : '') + min + 'm ' + sec + 's</div>'; } }
@@ -144,7 +172,7 @@ async function openAgentDetail(id) {
   // eslint-disable-next-line no-unsanitized/property -- reason: structural HTML is a string literal; status is an internal bounded enum and all user data is wrapped in escapeHtml()/renderMd() (fields: lastAction, blocking tool, resultSummary)
   document.getElementById('detail-status-line').innerHTML =
     '<span class="status-badge ' + badgeClass + '">' + agent.status.toUpperCase() + '</span> ' +
-    '<span style="color:var(--muted)">' + escapeHtml(agent.lastAction) + '</span>' +
+    '<span class="agent-detail-action"' + _agentTimedActionAttrs(agent) + ' style="color:var(--muted)">' + escapeHtml(_agentLastActionText(agent)) + '</span>' +
     (agent._blockingToolCall ? '<div style="margin-top:4px;padding:4px 8px;background:rgba(130,160,210,0.13);border:1px solid rgba(130,160,210,0.3);border-radius:4px;font-size:var(--text-base);color:var(--muted)">&#x23F3; Blocking tool call (' + escapeHtml(agent._blockingToolCall.tool) + ') &mdash; silent ' + Math.round(agent._blockingToolCall.silentMs/60000) + 'min, timeout in ' + Math.round(agent._blockingToolCall.remainingMs/60000) + 'min</div>' : '') +
     (agent.resultSummary ? '<div style="margin-top:4px;font-size:var(--text-base);color:var(--text);line-height:1.4">' + renderMd(agent.resultSummary.slice(0, 300)) + '</div>' : '');
 
@@ -168,11 +196,19 @@ async function openAgentDetail(id) {
 
 }
 
-// Tick running agent timers on cards every second
+// Tick wall-clock-derived card text every second.
 var _agentRuntimeTimer = null;
 function _tickAgentRuntimes() {
-  var els = document.querySelectorAll('.agent-runtime-tick');
-  if (els.length === 0) { if (_agentRuntimeTimer) { clearInterval(_agentRuntimeTimer); _agentRuntimeTimer = null; } return; }
+  var grid = document.getElementById('agents-grid');
+  var els = grid ? grid.querySelectorAll('.agent-runtime-tick') : [];
+  var actionEls = grid ? Array.from(grid.querySelectorAll('.agent-action[data-action-at]')) : [];
+  var detailStatus = document.getElementById('detail-status-line');
+  var detailAction = detailStatus && detailStatus.querySelector('.agent-detail-action[data-action-at]');
+  if (detailAction) actionEls.push(detailAction);
+  if (els.length === 0 && actionEls.length === 0) {
+    if (_agentRuntimeTimer) { clearInterval(_agentRuntimeTimer); _agentRuntimeTimer = null; }
+    return;
+  }
   var now = Date.now();
   els.forEach(function(el) {
     var ms = now - new Date(el.dataset.started).getTime();
@@ -180,13 +216,20 @@ function _tickAgentRuntimes() {
     var sec = Math.floor(ms / 1000) % 60, min = Math.floor(ms / 60000) % 60, hr = Math.floor(ms / 3600000);
     el.textContent = 'Running: ' + (hr > 0 ? hr + 'h ' : '') + min + 'm ' + sec + 's';
   });
+  actionEls.forEach(function(el) {
+    var text = _formatAgentAction(el.dataset.actionPrefix, Number(el.dataset.actionAt), el.textContent);
+    el.textContent = text;
+    el.title = text;
+  });
 }
-// Start ticker after each render if working agents exist
+// Start ticker after each render if any card has wall-clock-derived text.
 var _origRenderAgents = renderAgents;
 renderAgents = function(agents) {
   _origRenderAgents(agents);
   if (_agentRuntimeTimer) { clearInterval(_agentRuntimeTimer); _agentRuntimeTimer = null; }
-  if (agents.some(function(a) { return a.status === 'working' && a.started_at; })) {
+  if (agents.some(function(a) {
+    return (a.status === 'working' && a.started_at) || _agentHasTimedAction(a);
+  })) {
     _tickAgentRuntimes();
     _agentRuntimeTimer = setInterval(_tickAgentRuntimes, 1000);
   }

package/dashboard.js

@@ -2996,68 +2996,56 @@ function _stateReadContentType(ext) {
 // issue #2949 documented. This pattern bypasses both:
 //
 //   1. Caller supplies an array of input file paths.
-//   2. We statSync each one and take MAX(mtimeMs). That's the ETag.
+//   2. We asynchronously stat each one and take MAX(mtimeMs). That's the ETag.
 //   3. If the client's If-None-Match matches → 304 with no body.
 //   4. Otherwise call `builder()` to assemble the response from scratch
 //      (no outer cache layer to go stale).
 //   5. Stamp ETag + Content-Type and send.
 //
-// Cost per request when ETag matches: N statSync calls (microseconds).
-// Cost on a miss: same N statSync + the builder, which is exactly the
+// Cost per request when ETag matches: N asynchronous stat calls.
+// Cost on a miss: the same stat walk + the builder, which is exactly the
 // existing queries.getAgents() / getMetrics() / etc. that /api/status
 // already pays. Net change: same compute, no caching, always-fresh.
-function _maxInputMtimeMs(inputs) {
-  let max = 0;
-  for (const fp of inputs) {
-    try {
-      // Use lstatSync so a broken Windows junction (common after DevBox
-      // swap) or a circular symlink doesn't block the event loop on a
-      // ~30 s OS timeout trying to follow the link. Engine never writes
-      // symlinks into state dirs in normal operation, so an lstat that
-      // detects a symlink is treated as "skip" — the input is effectively
-      // not tracked. (Round-2 review finding #7.)
-      const s = fs.lstatSync(fp);
-      if (s.isSymbolicLink()) continue;
-      if (s.mtimeMs > max) max = s.mtimeMs;
-      // Directory inputs: dir mtime only advances on add/remove of
-      // immediate entries, not on in-place file edits. Walk two levels
-      // down so editing prd/<plan>.json in place (depth 1) and
-      // agents/<id>/live-output.log (depth 2) both bust the ETag.
-      // Steering edits at agents/<id>/inbox/steering-*.md (depth 3)
-      // currently rely on add/remove cadence rather than per-file content
-      // mtime — accept this lag rather than walking unbounded.
-      // (Review finding #6.)
-      if (s.isDirectory()) {
-        let level1;
-        try { level1 = fs.readdirSync(fp); } catch { level1 = []; }
-        for (const name of level1) {
-          const child = path.join(fp, name);
-          let cs;
-          try { cs = fs.lstatSync(child); } catch { continue; }
-          if (cs.isSymbolicLink()) continue;
-          if (cs.mtimeMs > max) max = cs.mtimeMs;
-          if (cs.isDirectory()) {
-            let level2;
-            try { level2 = fs.readdirSync(child); } catch { level2 = []; }
-            for (const inner of level2) {
-              try {
-                const is = fs.lstatSync(path.join(child, inner));
-                if (is.isSymbolicLink()) continue;
-                if (is.mtimeMs > max) max = is.mtimeMs;
-              } catch { /* skip unreadable */ }
-            }
-          }
-        }
-      }
-    } catch {
-      // Missing input = not yet on disk. Don't bust the ETag — a builder
-      // that legitimately depends on the file will surface its own empty
-      // state, and the ETag will move once the file appears.
-    }
+async function _freshnessEntryMtimeMs(fp, depth) {
+  let stat;
+  try {
+    // lstat avoids following broken Windows junctions or circular symlinks,
+    // which can incur long OS timeouts. State inputs never require symlinks.
+    stat = await fs.promises.lstat(fp);
+  } catch {
+    return 0;
   }
-  return Math.floor(max);
+  if (stat.isSymbolicLink()) return 0;
+
+  let max = stat.mtimeMs;
+  if (!stat.isDirectory() || depth <= 0) return max;
+
+  let names;
+  try {
+    names = await fs.promises.readdir(fp);
+  } catch {
+    return max;
+  }
+  const childMtimes = await Promise.all(
+    names.map(name => _freshnessEntryMtimeMs(path.join(fp, name), depth - 1)),
+  );
+  for (const childMtime of childMtimes) {
+    if (childMtime > max) max = childMtime;
+  }
+  return max;
+}
+
+async function _maxInputMtimeMs(inputs) {
+  // Directory mtime only advances on add/remove, not in-place edits. Walk two
+  // levels so prd/<plan>.json and agents/<id>/live-output.log both bust ETags.
+  // Deeper steering edits still rely on add/remove cadence, matching the prior
+  // bounded walk.
+  const mtimes = await Promise.all(
+    inputs.map(fp => _freshnessEntryMtimeMs(fp, 2)),
+  );
+  return Math.floor(mtimes.reduce((max, mtime) => Math.max(max, mtime), 0));
 }
-function serveFreshJson(req, res, opts) {
+async function serveFreshJson(req, res, opts) {
   const inputs = Array.isArray(opts && opts.inputs) ? opts.inputs : [];
   const builder = opts && typeof opts.builder === 'function' ? opts.builder : null;
   const tag = opts && opts.tag ? String(opts.tag) : 'v';
@@ -3067,7 +3055,7 @@ function serveFreshJson(req, res, opts) {
     res.end(JSON.stringify({ error: 'serveFreshJson: builder is required' }));
     return;
   }
-  const mtime = _maxInputMtimeMs(inputs);
+  const mtime = await _maxInputMtimeMs(inputs);
   const eventVersion = _getCurrentEventVersion();
   const etag = '"' + tag + '-' + mtime + '-' + eventVersion + '"';
   res.setHeader('ETag', etag);
@@ -7677,7 +7665,7 @@ const server = http.createServer(async (req, res) => {
       h = Math.imul(h ^ ((e.size || 0) >>> 0), 16777619);
       h = Math.imul(h ^ Math.floor(e.sortTs || 0), 16777619);
     }
-    const sweepMtime = _maxInputMtimeMs([
+    const sweepMtime = await _maxInputMtimeMs([
       path.join(ENGINE_DIR, 'kb-swept.json'),
       path.join(ENGINE_DIR, 'kb-sweep-state.json'),
     ]);

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/queries.js

@@ -758,6 +758,8 @@ function getAgents(config) {
     const s = getAgentStatus(a.id); // derives from dispatch.json
 
     let lastAction = 'Waiting for assignment';
+    let lastActionPrefix = null;
+    let lastActionAt = null;
     // Show the dispatch task as a stable label for the whole run — don't swap
     // in the transient per-tool-call `_runningToolDescription`, which reads like
     // a task change to operators (e.g. an agent's own "Wait until temp dirs
@@ -768,17 +770,23 @@ function getAgents(config) {
     else if (s.status === 'error') lastAction = `Error: ${s.task}`;
     else if (steeringInboxFiles.length > 0) {
       const lastSteer = steeringInboxFiles[steeringInboxFiles.length - 1];
-      lastAction = `Pending steering: ${lastSteer.file} (${timeSince(lastSteer.createdAtMs)})`;
+      lastActionPrefix = `Pending steering: ${lastSteer.file}`;
+      lastActionAt = lastSteer.createdAtMs;
+      lastAction = `${lastActionPrefix} (${timeSince(lastActionAt)})`;
     }
     else if (inboxFiles.length > 0) {
       const lastOutput = path.join(INBOX_DIR, inboxFiles[inboxFiles.length - 1]);
-      try { lastAction = `Output: ${path.basename(lastOutput)} (${timeSince(fs.statSync(lastOutput).mtimeMs)})`; } catch { /* optional */ }
+      try {
+        lastActionPrefix = `Output: ${path.basename(lastOutput)}`;
+        lastActionAt = fs.statSync(lastOutput).mtimeMs;
+        lastAction = `${lastActionPrefix} (${timeSince(lastActionAt)})`;
+      } catch { /* optional */ }
     }
 
     const chartered = fs.existsSync(path.join(AGENTS_DIR, a.id, 'charter.md'));
     if (lastAction.length > 120) lastAction = lastAction.slice(0, 120) + '...';
     return {
-      ...a, runtime, model, status: s.status, lastAction,
+      ...a, runtime, model, status: s.status, lastAction, lastActionPrefix, lastActionAt,
       // Descriptive capability tags; tolerate legacy `skills` configs by
       // normalizing to `expertise` for the dashboard/settings UI.
       expertise: a.expertise ?? a.skills ?? [],

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.2377",
+  "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"