@yemi33/minions 0.1.2124 → 0.1.2126

package/dashboard/js/settings.js

@@ -276,6 +276,15 @@ async function openSettings() {
       settingsField('Meeting Round Timeout', 'set-meetingRoundTimeout', e.meetingRoundTimeout || 900000, 'ms', 'Auto-advance meeting round after this') +
       settingsField('Steering Deferred Max', 'set-steeringDeferredMaxMs', e.steeringDeferredMaxMs || 900000, 'ms', 'Max wait for a runtime to emit a resumable checkpoint before a deferred steering message is flagged stranded. After this, the engine warns to live-output, marks _steeringStranded on the dispatch, and (when the steering store is present) sets store status=stranded. Default 15min; range 60s–4h.') +
       settingsField('Steering Max Kill Retries', 'set-steeringMaxKillRetries', e.steeringMaxKillRetries ?? 3, '', 'Cap on graceful+escalation kill attempts after a steering kill is issued. Ladder waits 30s → 60s → 120s between attempts (last interval reused). Attempt 1 is graceful; attempts 2..cap are platform hard kills (taskkill /F /T on Windows; descendant-tree SIGKILL + pkill on Unix). Past cap, the engine gives up with a [steering-stuck] log + inbox notice. Default 3; range 1–5.') +
+    '</div>' +
+    '<h4 style="margin:14px 0 4px;font-size:var(--text-md)">Spawn-phase watchdog</h4>' +
+    '<div class="settings-pane-sub">Kills agent processes that ran startup-only events (MCP init, hook fires) but never emitted real task progress, while CPU usage stayed below the threshold. Defense against MCP-init wedges that otherwise burn a worker slot until the 5h hard timeout. Fires only on fresh spawns (not engine-restart re-attaches).</div>' +
+    '<div class="settings-stack" style="margin-bottom:8px">' +
+      settingsToggle('Spawn-phase Watchdog', 'set-spawnPhaseWatchdogEnabled', e.spawnPhaseWatchdogEnabled !== false, 'Enable the spawn-phase MCP-init wedge detector. Default ON. Turn OFF only if you suspect false positives against a runtime whose legitimate startup exceeds the grace window.') +
+    '</div>' +
+    '<div class="settings-grid-2">' +
+      settingsField('Spawn-phase Grace', 'set-spawnPhaseGraceMs', e.spawnPhaseGraceMs || 120000, 'ms', 'Time after spawn before the watchdog can fire. Default 2min. A healthy startup ships a real event in seconds; this is generous headroom for slow MCP servers and corporate DNS.') +
+      settingsField('Spawn-phase CPU floor', 'set-spawnPhaseMaxCpuSeconds', e.spawnPhaseMaxCpuSeconds ?? 5, 's', 'Process is "idle" if cumulative CPU seconds ≤ this. Default 5s. A genuinely busy startup burns CPU on tokenizer bootstrap, MCP IPC, or model warmup; a wedged child sits in epoll near 0s.') +
     '</div>';
 
   const paneWorktree =
@@ -843,6 +852,9 @@ async function saveSettings() {
       meetingRoundTimeout: document.getElementById('set-meetingRoundTimeout').value,
       steeringDeferredMaxMs: document.getElementById('set-steeringDeferredMaxMs').value,
       steeringMaxKillRetries: document.getElementById('set-steeringMaxKillRetries').value,
+      spawnPhaseWatchdogEnabled: document.getElementById('set-spawnPhaseWatchdogEnabled').checked,
+      spawnPhaseGraceMs: document.getElementById('set-spawnPhaseGraceMs').value,
+      spawnPhaseMaxCpuSeconds: document.getElementById('set-spawnPhaseMaxCpuSeconds').value,
       operatorLogin: (document.getElementById('set-operatorLogin')?.value ?? '').trim(),
       autoApprovePlans: document.getElementById('set-autoApprovePlans').checked,
       evalLoop: document.getElementById('set-evalLoop').checked,

package/dashboard.js

@@ -9228,6 +9228,13 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // W-mq066js7000fff1f-c (Gap B/C): steering safety-net knobs.
           steeringDeferredMaxMs: [60000, 14400000],
           steeringMaxKillRetries: [1, 5],
+          // W-mq0e2dae000a003d — spawn-phase watchdog knobs. Grace must be
+          // at least one tick so the watchdog never fires before the
+          // runtime had a chance to emit. Upper bound 30min ≫ any legit
+          // startup. CPU floor 0–60s (60s would let half-busy processes
+          // through; the default 5s targets pure-idle epoll waits).
+          spawnPhaseGraceMs: [10000, 1800000],
+          spawnPhaseMaxCpuSeconds: [0, 60],
           versionCheckInterval: [60000],
           prPollStatusEvery: [1], prPollCommentsEvery: [1],
           agentBusyReassignMs: [0],
@@ -11477,7 +11484,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       invalidateStatusCache();
       return jsonReply(res, 200, { ok: true });
     }},
-    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message', handler: async (req, res) => {
+    { method: 'POST', path: '/api/agents/steer', desc: 'Inject steering message into a running agent', params: 'agent, message, supersede? (all|unacked|<steerId>), scope? (agent|current-dispatch)', handler: async (req, res) => {
       const body = await readBody(req);
       const { agent, message } = body;
       if (!agent || !message) return jsonReply(res, 400, { error: 'agent and message required' });
@@ -11491,7 +11498,54 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         return jsonReply(res, 409, { error: 'Agent session is finishing; retry when the next session starts' });
       }
 
-      const entry = steering.writeSteeringMessage(agentId, text);
+      // W-mq066js7000fff1f-e (Gap E) — supersede prior messages before
+      // writing the new one. Accept 'all', 'unacked', or a specific
+      // steerId. Bad shapes are silently ignored (best-effort).
+      const supersede = body.supersede ? String(body.supersede).trim() : '';
+      let superseded = [];
+      if (supersede) {
+        const provisionalSteerId = `steer-pending-${Date.now()}`;
+        superseded = steering.supersedeMessages(agentId, supersede, { reason: `superseded by new steer (${supersede})`, newSteerId: provisionalSteerId });
+      }
+
+      // W-mq066js7000fff1f-e — dedupe: if no supersede arg AND an
+      // identical body is already pending within the 5-min window, echo
+      // back the existing steerId instead of writing a duplicate file.
+      if (!supersede) {
+        const dup = steering.findRecentDuplicate(agentId, text);
+        if (dup) {
+          const delivery = _steeringDeliveryState(agentId);
+          return jsonReply(res, 200, {
+            ok: true,
+            deduplicated: true,
+            steerId: dup.steerId,
+            status: dup.status || steering.STATUS.QUEUED,
+            file: dup.file,
+            // Gap D observability URL — points at the SQL delivery-state row
+            // for /api/steering/:id (back-compat with master's contract).
+            deliveryUrl: dup.steerId ? `/api/steering/${dup.steerId}` : null,
+            message: 'Identical steering message already pending — returning existing entry',
+            ...delivery,
+            inboxCount: steering.listUnreadSteeringMessages(agentId).length,
+          });
+        }
+      }
+
+      // W-mq066js7000fff1f-f (Gap F) — per-dispatch scoping. With
+      // scope='current-dispatch' we stamp the active dispatch id so the
+      // engine filters this entry out of any future unrelated dispatch's
+      // resume prompt. With scope='agent' (default) the message is
+      // agent-wide and picks up on the next dispatch regardless of id.
+      const scope = body.scope ? String(body.scope).trim().toLowerCase() : 'agent';
+      let targetDispatchId = null;
+      let scopeApplied = scope;
+      if (scope === 'current-dispatch') {
+        const active = (getDispatchQueue().active || []).find(d => d.agent === agentId);
+        if (active?.id) targetDispatchId = String(active.id);
+        else scopeApplied = 'agent'; // no active dispatch → fall back
+      }
+
+      const entry = steering.writeSteeringMessage(agentId, text, { targetDispatchId });
       const delivery = _steeringDeliveryState(agentId);
 
       // Also append to live-output.log so it shows in the chat view
@@ -11506,12 +11560,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const steerId = entry?.steerId || null;
       return jsonReply(res, 200, {
         ok: true,
+        deduplicated: false,
+        steerId,
+        status: entry?.status || (steerId ? steering.STATUS.QUEUED : null),
+        targetDispatchId: entry?.targetDispatchId || null,
+        scope: scopeApplied,
+        superseded: superseded.map(s => ({ steerId: s.steerId, previousStatus: s.previousStatus })),
         message: delivery.pendingDelivery ? 'Steering message pending delivery' : 'Steering message queued',
         ...delivery,
         file: entry?.file || null,
         inboxCount: steering.listUnreadSteeringMessages(agentId).length,
-        steerId,
-        status: steerId ? 'queued' : null,
         deliveryUrl: steerId ? `/api/steering/${steerId}` : null,
       });
     }},

package/docs/README.md

@@ -19,7 +19,9 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
 - [cooldown-merge-semantics.md](cooldown-merge-semantics.md) — Scoping deliverable defining merge semantics for `saveCooldowns` (longer-of TTL merge, key-level upserts, gitignored on-disk format).
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
-- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target (accepted; implementation tracked in CHANGELOG.md Phases 0–7).
+- [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.
+- [design-state-storage.md](design-state-storage.md) — Design proposal evaluating five database options for replacing Minions' file-based JSON state; recommends `node:sqlite` as the medium-term target (accepted; implementation tracked in CHANGELOG.md Phases 0–9).
+- [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.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.

package/docs/design-state-storage.md

@@ -2,7 +2,7 @@
 
 > Author: Rebecca (Architect) | Date: 2026-04-07 | Status: **Accepted — implementation in progress**
 
-> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–8 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, and qa_runs + qa_sessions — see `CHANGELOG.md`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true) — when ops trust SQL as the source of truth for QA state, flip it false to halve write I/O on hot loops. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
+> **Implementation status (as of 2026-06):** The `node:sqlite` recommendation in §3 has been adopted ahead of schedule. Phases 0–9 have shipped (events, dispatches, work_items, pull_requests, logs, metrics, watches, schedule_runs + pipeline_runs + managed_processes + worktree_pool, qa_runs + qa_sessions, pr_links, cooldowns + pending_rebases + cc_sessions + doc_sessions, and steering_deliveries — see `CHANGELOG.md` and `engine/db/migrations/`). The SQLite schema lives under `engine/db/migrations/` and the singleton opens `engine/state.db` in WAL mode. Phase 8 added the first opt-out toggle for the JSON sidecars (`engine.qaDualWriteJson`, default true). Phase 9.4 went further and deleted the silent SQL-unavailable JSON fallbacks in the engine — SQL is now the only reader/writer for everything migrated; the JSON mirror layer is dual-written as a passive mirror and slated for deletion in Phase 9.5. The "Phase 2: estimated Node 26 LTS" timeline in §3 is now historical context; treat sections 1–3 as design rationale rather than a forward plan.
 
 ## Executive Summary
 

package/docs/watches.md

@@ -173,6 +173,7 @@ I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up ac
 | `trigger-pipeline`     | Start a new pipeline run (skipped if the pipeline already has an active run)                  |
 | `archive-plan`         | Set PRD `status="archived"` + `archivedAt`                                                    |
 | `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
+| `cc-triage`            | Invoke Command Center headlessly via the loopback `POST /api/command-center/triage` endpoint with the trigger context (and optional completion-report / live-output artifacts). Wraps the prompt in `<UNTRUSTED-INPUT>`, uses a default 10-min timeout (capped at 1 h), and is isolated from the user CC session |
 
 Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:2608`); handlers in `engine/watch-actions.js`.
 

package/engine/dispatch.js

@@ -467,6 +467,10 @@ const FORCE_DEMOTE_FAILURE_CLASSES = new Set([
   FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA,
   FAILURE_CLASS.INVALID_MANAGED_SPAWN,
   FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED,
+  // W-mq0e2dae000a003d: spawn-phase wedges should never claim success,
+  // but include here as defense-in-depth so a stray completion-report
+  // can't sneak through.
+  FAILURE_CLASS.SPAWN_PHASE_STALL,
 ]);
 
 function readLiveWorkItem(meta) {

package/engine/shared.js

@@ -2255,6 +2255,18 @@ const ENGINE_DEFAULTS = {
   allowedDashboardOrigins: [],
   meetingRoundTimeout: 900000, // 15min per meeting round — soft signal; logs a "still waiting" warning each tick
   meetingRoundHardTimeout: 3600000, // 60min hard backstop — non-terminal participants are marked failed and the round advances. Prevents permanent stalls if an agent's dispatch never spawns or its completion gets dropped.
+  // W-mq0e2dae000a003d — spawn-phase progress watchdog. Detects the
+  // MCP-init wedge where a runtime process starts, emits only startup-only
+  // events (Copilot session.mcp_*/skills_loaded/tools_updated/info or Claude
+  // system init/hook events), then sits idle indefinitely with no real task
+  // events. The watchdog fires only when BOTH (a) elapsed since spawn
+  // exceeds the grace and (b) per-process CPU seconds are below the
+  // threshold — preventing kills of legitimately busy startups. Re-attached
+  // processes (engine restart) are exempt; we only watchdog fresh spawns
+  // whose live-output we can fully account for.
+  spawnPhaseWatchdogEnabled: true,
+  spawnPhaseGraceMs: 120000,   // 2min — startup grace before the watchdog can fire
+  spawnPhaseMaxCpuSeconds: 5,  // process is "idle" if its CPU total is <= this many seconds
   // W-mq066js7000fff1f-c (steering Gap B): max wall-clock a steering message may
   // sit deferred (runtime hasn't emitted a resumable checkpoint yet — Copilot
   // pre-first-checkpoint, etc.). Past this window the message is flagged
@@ -3506,6 +3518,7 @@ const FAILURE_CLASS = {
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
   WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
   WORKSPACE_MANIFEST_URL: 'workspace-manifest-url-forbidden',   // W-mq07avbk000m5543: out-of-scope external URL fetch. Non-retryable as-is.
+  SPAWN_PHASE_STALL: 'spawn-phase-stall', // W-mq0e2dae000a003d: process spawned and ran startup-only events (MCP init / hooks) but never emitted real task progress; CPU usage stayed below threshold past the grace window. Engine kills the wedged child and treats this as retryable (fresh-session) so a re-spawn can clear a transient MCP wedge.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {
@@ -5552,6 +5565,58 @@ function killImmediate(proc) {
   }
 }
 
+// W-mq0e2dae000a003d — cross-platform CPU-seconds sampler used by the
+// spawn-phase watchdog to decide whether a process is genuinely wedged
+// vs busy. Returns the cumulative user+system CPU time in seconds, or
+// null when we can't determine it (process dead, sampler unavailable,
+// shell errored). Fail-open: a null result MUST NOT cause the watchdog
+// to fire — silence-from-the-OS is not the same as silence-from-the-process.
+function getProcessCpuSeconds(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return null;
+  try {
+    if (process.platform === 'win32') {
+      // PowerShell. CPU = total processor time in seconds (sum of user + kernel).
+      // 2.5s timeout keeps the tick budget bounded if PS is sluggish.
+      const out = _execSync(
+        `powershell -NoProfile -NonInteractive -Command "(Get-Process -Id ${n} -ErrorAction Stop).CPU"`,
+        { stdio: ['ignore', 'pipe', 'pipe'], timeout: 2500, windowsHide: true, encoding: 'utf8' }
+      );
+      const v = parseFloat(String(out).trim());
+      return Number.isFinite(v) ? v : null;
+    }
+    if (process.platform === 'linux') {
+      // /proc/<pid>/stat fields 14 (utime) + 15 (stime) in clock ticks.
+      // _SC_CLK_TCK is 100 on virtually every Linux distro; sysconf isn't
+      // exposed from Node so we use the conventional value. If a host
+      // ever ships USER_HZ != 100 this would under/over-report by a
+      // constant factor; safe within an order of magnitude for our gate.
+      const raw = fs.readFileSync(`/proc/${n}/stat`, 'utf8');
+      // The comm field can contain spaces and parens — slice past the last ')'
+      const close = raw.lastIndexOf(')');
+      if (close < 0) return null;
+      const fields = raw.slice(close + 2).split(/\s+/);
+      // After comm: state(0) ppid(1) pgrp(2) ... utime is index 11, stime 12
+      const utime = Number(fields[11]);
+      const stime = Number(fields[12]);
+      if (!Number.isFinite(utime) || !Number.isFinite(stime)) return null;
+      return (utime + stime) / 100;
+    }
+    if (process.platform === 'darwin') {
+      // `ps -p N -o cputime=` → "MM:SS.ss" or "HH:MM:SS"
+      const out = _execSync(`ps -p ${n} -o cputime=`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 2500, windowsHide: true, encoding: 'utf8' });
+      const t = String(out).trim();
+      if (!t) return null;
+      const parts = t.split(':').map(s => parseFloat(s));
+      if (!parts.every(p => Number.isFinite(p))) return null;
+      let secs = 0;
+      while (parts.length) secs = secs * 60 + parts.shift();
+      return secs;
+    }
+  } catch { /* fail-open */ }
+  return null;
+}
+
 // Single-PID kill (no /T tree walk) — used by the orphan-MCP sweep where we
 // already enumerated descendants ourselves and the parent is dead, so /T would
 // be a no-op anyway.
@@ -6441,6 +6506,7 @@ module.exports = {
   sleepMs,
   killGracefully,
   killImmediate,
+  getProcessCpuSeconds,
   killByPidImmediate,
   killByPidsImmediate,
   isProcessCommandLineMatchingAgent,

package/engine/spawn-phase-watchdog.js

@@ -0,0 +1,271 @@
+// engine/spawn-phase-watchdog.js — W-mq0e2dae000a003d
+//
+// Per-tick check that kills agent processes wedged in the spawn/MCP-init
+// phase. The classic failure mode is a Copilot or Claude child that emits
+// startup-only events (MCP server load, skill registration, hook firing)
+// and then sits idle indefinitely — no `assistant.*`, no `tool.*`, no
+// `result`, no completion-report. The agent never makes progress so the
+// hard timeout (5h) eventually kills it, wasting a worker slot for hours.
+//
+// Detection contract:
+//
+//   1. Process must be a fresh spawn (not re-attached after engine
+//      restart — `procInfo.reattached` is false/undefined). Re-attached
+//      processes already lost their early live-output and can look
+//      pre-wedged after the engine reads them mid-flight.
+//
+//   2. Time since spawn must exceed `spawnPhaseGraceMs` (default 2min).
+//      Short grace because a healthy startup ships a real event within
+//      seconds; 2min gives slow MCP servers and corp-network DNS plenty
+//      of headroom.
+//
+//   3. live-output.log tail must contain ZERO non-startup events. We tail
+//      ~16KB and parse JSON lines; any non-startup type means the runtime
+//      handed control to the task and the watchdog stands down.
+//
+//   4. Per-process CPU seconds must be <= `spawnPhaseMaxCpuSeconds`
+//      (default 5). A genuinely busy startup will burn CPU on tokenizer
+//      bootstrap, MCP IPC, or model warmup; a wedged child sits in epoll.
+//      The CPU gate is fail-open — if we can't sample, we DO NOT kill.
+//
+// On fire: kill the tracked process tree, complete the dispatch with
+// SPAWN_PHASE_STALL, mark agent-retryable so the next tick re-spawns the
+// agent with a fresh runtime invocation (resolves transient MCP wedges).
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const queries = require('./queries');
+const { ENGINE_DEFAULTS, FAILURE_CLASS } = shared;
+const AGENTS_DIR = queries.AGENTS_DIR;
+const log = (level, msg) => shared.log ? shared.log(level, msg) : console.log(`[${level}] ${msg}`);
+
+// Lazy require to break circular dep with dispatch.js (which lazy-requires engine.js).
+function dispatch() { return require('./dispatch'); }
+
+// ── Per-runtime startup-only event filters ──────────────────────────────────
+//
+// Anything NOT in these sets is treated as "real task activity" and the
+// watchdog stands down. These match the runtimes/*.js KNOWN_EVENT_TYPES
+// startup section — keep in sync.
+
+const COPILOT_STARTUP_TYPES = new Set([
+  'session.mcp_server_status_changed',
+  'session.mcp_servers_loaded',
+  'session.skills_loaded',
+  'session.tools_updated',
+  'session.info',
+]);
+
+// Claude stream-json prints {"type":"system","subtype":"init|hook_started|hook_response"}
+// during startup before any assistant/user/tool_use/result events fire.
+const CLAUDE_STARTUP_SUBTYPES = new Set(['init', 'hook_started', 'hook_response']);
+
+// Header line that engine.js writes at spawn: "[<iso>] pid: <n>"
+const HEADER_LINE_RE = /^\[[^\]]+\]\s+(?:pid:|spawn-failed)/;
+
+/**
+ * Inspect a tail of `live-output.log` and decide whether the runtime has
+ * emitted any real task progress events yet.
+ *
+ * Returns true when we found at least one non-startup event. Returns
+ * false when the tail is empty, header-only, or contains ONLY recognized
+ * startup events.
+ *
+ * Conservative on parse errors: a line that fails JSON.parse is treated
+ * as a real progress signal (could be a `[engine-system]` notice or
+ * codex plain-text output), so the watchdog stands down. Only structured
+ * JSON whose `type` we positively recognize as startup is filtered out.
+ */
+function hasRealTaskActivity(tailText, runtimeName) {
+  if (!tailText) return false;
+  const lines = String(tailText).split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (HEADER_LINE_RE.test(line)) continue;
+    // Bracketed engine sentinels like `[process-exit] code=0` shouldn't
+    // reach this code path (timeout.js would have completed first), but
+    // if they do, treat them as real activity so we never race timeout.
+    if (/^\[(?:process-exit|engine-system|steering-)/.test(line)) return true;
+    // Try to parse JSON. Non-JSON lines (codex plain text, partial flushes)
+    // count as real activity — only positively-identified startup events
+    // are filtered out.
+    let evt;
+    try { evt = JSON.parse(line); }
+    catch { return true; }
+    if (!evt || typeof evt !== 'object') continue;
+    const type = typeof evt.type === 'string' ? evt.type : null;
+    if (!type) {
+      // Object with no `type` — unusual; treat as activity to stay safe.
+      return true;
+    }
+    if (runtimeName === 'copilot') {
+      if (COPILOT_STARTUP_TYPES.has(type)) continue;
+      // Anything else from Copilot is real (assistant.*, tool.*, result,
+      // session.task_complete, user.message, function).
+      return true;
+    }
+    if (runtimeName === 'claude' || !runtimeName) {
+      // Claude stream-json: only {type:'system', subtype:'init|hook_*'} is startup.
+      if (type === 'system') {
+        const sub = typeof evt.subtype === 'string' ? evt.subtype : '';
+        if (CLAUDE_STARTUP_SUBTYPES.has(sub)) continue;
+        // Other `system` subtypes (e.g. errors, banners) — treat as activity.
+        return true;
+      }
+      return true;
+    }
+    // Unknown runtime — be conservative.
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Tick-loop hook. Iterates active processes, applies the four detection
+ * gates, kills + completes any that wedge.
+ *
+ * @param {Map<string, object>} activeProcesses  Engine's tracked-process map
+ * @param {object} config                        Live engine config
+ * @param {object} [opts]                        Test seams
+ * @param {() => number} [opts.now]              Clock injector
+ * @param {(pid:number) => number|null} [opts.cpuSampler]  CPU-sec sampler
+ * @param {(p:string) => string|null} [opts.tailReader]   live-output tail reader
+ * @param {(proc:object) => void} [opts.killer]  killImmediate injector
+ * @param {(dispatchId, result, reason, summary, opts) => void} [opts.completer]
+ */
+function checkSpawnPhaseStalls(activeProcesses, config, opts = {}) {
+  if (!activeProcesses || typeof activeProcesses.entries !== 'function') return;
+  const enabled = config?.engine?.spawnPhaseWatchdogEnabled
+    ?? ENGINE_DEFAULTS.spawnPhaseWatchdogEnabled;
+  if (enabled === false) return;
+
+  const graceMs = Math.max(1000, Number(config?.engine?.spawnPhaseGraceMs)
+    || ENGINE_DEFAULTS.spawnPhaseGraceMs);
+  const maxCpuSec = Math.max(0, Number(config?.engine?.spawnPhaseMaxCpuSeconds
+    ?? ENGINE_DEFAULTS.spawnPhaseMaxCpuSeconds));
+
+  const now = (opts.now || Date.now)();
+  const cpuSampler = opts.cpuSampler || ((pid) => shared.getProcessCpuSeconds(pid));
+  const tailReader = opts.tailReader || _defaultTailReader;
+  const killer = opts.killer || ((proc) => shared.killImmediate(proc));
+  const completer = opts.completer || ((id, result, reason, summary, o) => dispatch().completeDispatch(id, result, reason, summary, o));
+
+  for (const [id, procInfo] of activeProcesses.entries()) {
+    if (!procInfo) continue;
+    // Skip re-attached processes — we have no reliable spawn timestamp
+    // for their startup phase, and their live-output may be mid-stream.
+    if (procInfo.reattached) continue;
+    // Skip processes that have already been promoted past spawn phase
+    // by a prior watchdog tick (single-shot per spawn).
+    if (procInfo._spawnPhaseCleared) continue;
+    // Skip processes that the steering pipeline has already killed —
+    // a re-spawn will track itself.
+    if (procInfo._steeringAt) continue;
+    const proc = procInfo.proc;
+    if (!proc) continue;
+    // If the process already exited, let timeout.js / onAgentClose handle it.
+    if (Object.prototype.hasOwnProperty.call(proc, 'exitCode') && proc.exitCode !== null) continue;
+
+    const startedAtMs = procInfo.startedAt ? Date.parse(procInfo.startedAt) : NaN;
+    if (!Number.isFinite(startedAtMs)) continue;
+    const elapsed = now - startedAtMs;
+    if (elapsed < graceMs) continue;
+
+    const agentId = procInfo.agentId;
+    if (!agentId) continue;
+
+    const liveLogPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+    const tail = tailReader(liveLogPath);
+
+    if (hasRealTaskActivity(tail, procInfo.runtimeName)) {
+      // Promote out of spawn phase — never re-check this process again.
+      procInfo._spawnPhaseCleared = true;
+      continue;
+    }
+
+    // Still in spawn phase past the grace. Now gate on CPU.
+    const pid = proc.pid;
+    if (!pid) continue;
+    const cpuSec = cpuSampler(pid);
+    if (cpuSec == null) {
+      // Fail-open: can't sample → don't kill. Try again next tick.
+      continue;
+    }
+    if (cpuSec > maxCpuSec) {
+      // Process is doing work; just slow to emit. Stand down.
+      continue;
+    }
+
+    // All four gates passed — this is a wedge. Kill + complete.
+    const elapsedSec = Math.round(elapsed / 1000);
+    const reason = `Spawn-phase stall: no task events after ${elapsedSec}s (CPU ${cpuSec.toFixed(2)}s ≤ ${maxCpuSec}s)`;
+    log('warn', `spawn-phase-watchdog: killing ${agentId} (${id}) — ${reason}`);
+
+    // Write a structured inbox note BEFORE killing so the dispatch
+    // completion's failure-report doesn't overwrite our diagnostic.
+    try {
+      const noteContent = [
+        `# Spawn-phase stall: ${agentId}`,
+        '',
+        `**Dispatch:** \`${id}\``,
+        `**Agent:** ${agentId}`,
+        `**Runtime:** ${procInfo.runtimeName || '(unknown)'}`,
+        `**PID:** ${pid}`,
+        `**Elapsed since spawn:** ${elapsedSec}s`,
+        `**CPU seconds:** ${cpuSec.toFixed(2)} (threshold ${maxCpuSec})`,
+        `**Grace window:** ${Math.round(graceMs / 1000)}s`,
+        '',
+        '## Tail of live-output.log',
+        '```',
+        (tail || '(empty)').slice(-2000),
+        '```',
+        '',
+        'The runtime emitted only startup-only events (MCP init, hook fires) ' +
+        'and burned no CPU past the grace window. Engine treated this as a wedged ' +
+        'startup and killed the child; the dispatch is marked retryable so the next ' +
+        'tick will respawn with a fresh runtime invocation.',
+      ].join('\n');
+      shared.writeToInbox('engine', `spawn-phase-stall-${id}`, noteContent, null, {
+        dispatchId: id, agent: agentId, failureClass: FAILURE_CLASS.SPAWN_PHASE_STALL,
+      });
+    } catch (e) { log('warn', `spawn-phase-watchdog: inbox note: ${e.message}`); }
+
+    try { killer(proc); }
+    catch (e) { log('warn', `spawn-phase-watchdog: kill: ${e.message}`); }
+
+    try {
+      completer(id, shared.DISPATCH_RESULT.ERROR, reason, '', {
+        failureClass: FAILURE_CLASS.SPAWN_PHASE_STALL,
+        agentRetryable: true,
+        processWorkItemFailure: true,
+      });
+    } catch (e) { log('warn', `spawn-phase-watchdog: completeDispatch: ${e.message}`); }
+
+    // Clear the engine's tracking so the next discovery tick can rebuild.
+    try { activeProcesses.delete(id); } catch { /* defensive */ }
+  }
+}
+
+function _defaultTailReader(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.size) return '';
+    const maxBytes = 16384;
+    const tailSize = Math.min(stat.size, maxBytes);
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(tailSize);
+      fs.readSync(fd, buf, 0, tailSize, Math.max(0, stat.size - tailSize));
+      return buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+  } catch { return null; }
+}
+
+module.exports = {
+  checkSpawnPhaseStalls,
+  hasRealTaskActivity, // exported for testing
+  COPILOT_STARTUP_TYPES, // exported for testing
+  CLAUDE_STARTUP_SUBTYPES, // exported for testing
+};

package/engine/steering.js

@@ -19,6 +19,43 @@ function _generateSteerId() {
   return `steer-${crypto.randomBytes(8).toString('hex').slice(0, 10)}`;
 }
 
+// W-mq066js7000fff1f-e (Gap E): identical-text dedupe window. POST
+// /api/agents/steer collapses identical bodies within this window to
+// the existing steerId instead of writing a duplicate inbox file.
+const DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+
+// W-mq066js7000fff1f-e/f: status enum for the inbox frontmatter +
+// supersede operations. Mirrors the steering_deliveries observability
+// table (Gap D) so callers can speak the same vocabulary regardless
+// of which storage backend is live.
+const STATUS = Object.freeze({
+  QUEUED: 'queued',
+  LIVE_KILL: 'live_kill',
+  DEFERRED: 'deferred',
+  RE_SPAWNING: 're_spawning',
+  DELIVERED: 'delivered',
+  ACKNOWLEDGED: 'acknowledged',
+  STRANDED: 'stranded',
+  DROPPED: 'dropped',
+});
+
+const UNACKED_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.STRANDED,
+]);
+
+// Statuses that should still appear as "live" in the dedupe lookup.
+const DEDUPE_CANDIDATE_STATUSES = new Set([
+  STATUS.QUEUED,
+  STATUS.LIVE_KILL,
+  STATUS.DEFERRED,
+  STATUS.RE_SPAWNING,
+  STATUS.DELIVERED,
+]);
+
 function agentInboxDir(agentId) {
   return path.join(AGENTS_DIR, agentId, 'inbox');
 }
@@ -73,15 +110,22 @@ function _readEntry(filePath, legacy = false) {
     ? fmCreatedAtMs
     : _createdAtFromPath(filePath, stat);
   const steerId = _frontmatterValue(raw, 'steerId') || null;
+  const status = _frontmatterValue(raw, 'status') || STATUS.QUEUED;
+  const targetDispatchId = _frontmatterValue(raw, 'targetDispatchId') || null;
+  const lastError = _frontmatterValue(raw, 'lastError') || null;
+  const source = _frontmatterValue(raw, 'source') || 'human';
   return {
     path: filePath,
     file: path.basename(filePath),
     createdAtMs,
     createdAt: new Date(createdAtMs).toISOString(),
-    steerId,
     raw,
     message: _messageFromRaw(raw),
     steerId,
+    status,
+    targetDispatchId,
+    lastError,
+    source,
     legacy,
   };
 }
@@ -94,10 +138,6 @@ function _uniqueSteeringPath(inboxDir, createdAtMs) {
   return filePath;
 }
 
-function _generateSteerId() {
-  return crypto.randomBytes(6).toString('hex');
-}
-
 // Contract block describing the ACK-file protocol. Injected into the prompt
 // alongside any pending steering messages so the agent knows how to confirm
 // it has read+addressed a labeled message. Mirrored verbatim into
@@ -111,9 +151,24 @@ function ackContractBlock() {
   ].join('\n');
 }
 
+function _renderFrontmatter(data) {
+  const createdAtMs = Number(data.createdAtMs) || Date.now();
+  const lines = [
+    '---',
+    `createdAt: ${new Date(createdAtMs).toISOString()}`,
+    `createdAtMs: ${createdAtMs}`,
+    `source: ${data.source || 'human'}`,
+    `steerId: ${data.steerId}`,
+    `status: ${data.status || STATUS.QUEUED}`,
+  ];
+  if (data.targetDispatchId) lines.push(`targetDispatchId: ${data.targetDispatchId}`);
+  if (data.lastError) lines.push(`lastError: ${String(data.lastError).replace(/[\r\n]+/g, ' ').trim()}`);
+  lines.push('---', '', String(data.message || '').trim(), '');
+  return lines.join('\n');
+}
+
 function writeSteeringMessage(agentId, message, opts = {}) {
   const createdAtMs = Number(opts.createdAtMs) || Date.now();
-  const createdAt = new Date(createdAtMs).toISOString();
   const inboxDir = agentInboxDir(agentId);
   fs.mkdirSync(inboxDir, { recursive: true });
   const filePath = _uniqueSteeringPath(inboxDir, createdAtMs);
@@ -134,17 +189,15 @@ function writeSteeringMessage(agentId, message, opts = {}) {
       steerId,
     }));
   }
-  const body = [
-    '---',
-    `createdAt: ${createdAt}`,
-    `createdAtMs: ${createdAtMs}`,
-    `source: ${source}`,
-    `steerId: ${steerId}`,
-    '---',
-    '',
-    bodyText,
-    '',
-  ].join('\n');
+  const body = _renderFrontmatter({
+    createdAtMs,
+    source,
+    steerId,
+    status: opts.status || STATUS.QUEUED,
+    targetDispatchId: opts.targetDispatchId || null,
+    lastError: opts.lastError || null,
+    message: bodyText,
+  });
   shared.safeWrite(filePath, body);
 
   // W-mq066js7000fff1f-a (Gap D): insert a 'queued' row into the
@@ -169,7 +222,22 @@ function writeSteeringMessage(agentId, message, opts = {}) {
   return _readEntry(filePath);
 }
 
-function listUnreadSteeringMessages(agentId, opts = {}) {
+function _updateEntryStatus(entry, newStatus, opts = {}) {
+  if (!entry?.path) return null;
+  const body = _renderFrontmatter({
+    createdAtMs: entry.createdAtMs,
+    source: entry.source || 'human',
+    steerId: entry.steerId,
+    status: newStatus,
+    targetDispatchId: entry.targetDispatchId,
+    lastError: opts.lastError !== undefined ? opts.lastError : entry.lastError,
+    message: entry.message,
+  });
+  shared.safeWrite(entry.path, body);
+  return _readEntry(entry.path);
+}
+
+function listAllSteeringEntries(agentId, opts = {}) {
   const includeLegacy = opts.includeLegacy !== false;
   const entries = [];
   const inboxDir = agentInboxDir(agentId);
@@ -189,8 +257,40 @@ function listUnreadSteeringMessages(agentId, opts = {}) {
   return entries;
 }
 
-function buildPendingSteeringPrompt(agentId) {
-  const entries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+function listUnreadSteeringMessages(agentId, opts = {}) {
+  // Back-compat shape: "unread" = anything still pending agent attention
+  // (queued/live_kill/deferred/re_spawning/delivered/stranded). Explicit
+  // 'dropped' or 'acknowledged' rows are filtered so supersede/ack don't
+  // resurrect carry-over messages on the next dispatch.
+  return listAllSteeringEntries(agentId, opts).filter(entry => {
+    const status = entry.status || STATUS.QUEUED;
+    return status !== STATUS.DROPPED && status !== STATUS.ACKNOWLEDGED;
+  });
+}
+
+// W-mq066js7000fff1f-f (Gap F): per-dispatch scoping. Callers that know
+// which dispatch they're about to spawn can pass {currentDispatchId} so
+// messages tagged for a different (older) dispatch are filtered out.
+// Pre-spawn messages (targetDispatchId null) always pass through.
+// Without currentDispatchId, no filtering happens — back-compat for
+// callers that haven't been updated to pass the dispatch id yet.
+function buildPendingSteeringPrompt(agentId, opts = {}) {
+  const includePrior = opts.includePrior === true;
+  const currentDispatchId = opts.currentDispatchId || null;
+  const allEntries = listUnreadSteeringMessages(agentId).filter(entry => entry.message.trim());
+  const entries = includePrior
+    ? allEntries
+    : allEntries.filter(entry => {
+        // Pre-spawn / agent-scoped messages (null targetDispatchId) always
+        // pick up on the next dispatch — the agent never had a chance to
+        // hear them yet.
+        if (!entry.targetDispatchId) return true;
+        // No dispatch context → don't try to filter (back-compat).
+        if (!currentDispatchId) return true;
+        // Per-dispatch messages only belong to their tagged dispatch.
+        return entry.targetDispatchId === currentDispatchId;
+      });
+
   if (entries.length === 0) return { entries, prompt: '' };
 
   const sections = [
@@ -206,6 +306,69 @@ function buildPendingSteeringPrompt(agentId) {
   return { entries, prompt: sections.join('\n') };
 }
 
+// W-mq066js7000fff1f-e (Gap E): dedupe lookup for POST /api/agents/steer.
+// Returns the existing entry whose normalized body matches `message` and
+// was created within `opts.windowMs` (default 5 min); null otherwise.
+// Only entries in "live" delivery states qualify — dropped/acknowledged
+// rows are ignored so a previously-superseded duplicate body is allowed
+// to be re-sent.
+function findRecentDuplicate(agentId, message, opts = {}) {
+  const trimmed = String(message || '').trim();
+  if (!trimmed) return null;
+  const windowMs = Number(opts.windowMs) > 0 ? Number(opts.windowMs) : DEDUPE_WINDOW_MS;
+  const now = Number(opts.now) > 0 ? Number(opts.now) : Date.now();
+  const entries = listAllSteeringEntries(agentId);
+  // Newest first — UI usually steers in a tight loop, the most recent
+  // identical message is the one we want to deduplicate against.
+  entries.sort((a, b) => b.createdAtMs - a.createdAtMs);
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    if (!DEDUPE_CANDIDATE_STATUSES.has(status)) continue;
+    if (now - entry.createdAtMs > windowMs) continue;
+    if (entry.message.trim() !== trimmed) continue;
+    return entry;
+  }
+  return null;
+}
+
+// W-mq066js7000fff1f-e (Gap E): supersede prior steering messages.
+// mode:
+//   'all'      — drop every entry whose status is neither dropped nor
+//                acknowledged (queued/live_kill/deferred/re_spawning/
+//                delivered/stranded).
+//   'unacked'  — drop queued/live_kill/deferred/re_spawning/stranded but
+//                leave 'delivered' alone (agent already saw it).
+//   <steerId>  — drop the single entry with that steerId.
+// Returns the list of dropped {steerId, file, path, previousStatus}.
+function supersedeMessages(agentId, mode, opts = {}) {
+  if (!mode) return [];
+  const newSteerId = opts.newSteerId || null;
+  const reason = opts.reason || (newSteerId ? `superseded by ${newSteerId}` : 'superseded');
+  const entries = listAllSteeringEntries(agentId);
+  const dropped = [];
+  for (const entry of entries) {
+    const status = entry.status || STATUS.QUEUED;
+    let target = false;
+    if (mode === 'all') {
+      if (status !== STATUS.ACKNOWLEDGED && status !== STATUS.DROPPED) target = true;
+    } else if (mode === 'unacked') {
+      if (UNACKED_STATUSES.has(status)) target = true;
+    } else {
+      // Specific steerId
+      if (entry.steerId && entry.steerId === mode) target = true;
+    }
+    if (!target) continue;
+    _updateEntryStatus(entry, STATUS.DROPPED, { lastError: reason });
+    dropped.push({
+      steerId: entry.steerId,
+      file: entry.file,
+      path: entry.path,
+      previousStatus: status,
+    });
+  }
+  return dropped;
+}
+
 function _eventTimestampMs(obj, observedAtMs) {
   const value = obj?.timestamp || obj?.createdAt || obj?.created_at || obj?.time || obj?.data?.timestamp;
   const parsed = value ? Date.parse(value) : NaN;
@@ -342,9 +505,17 @@ module.exports = {
   ackContractBlock,
   writeSteeringMessage,
   listUnreadSteeringMessages,
+  listAllSteeringEntries,
   buildPendingSteeringPrompt,
+  findRecentDuplicate,
+  supersedeMessages,
   sessionIdFromEvent,
   sessionIdFromOutputLine,
   ackProcessedSteeringMessages,
   ackSteeringFromAckDir,
+  STATUS,
+  DEDUPE_WINDOW_MS,
+  // Exposed for unit tests only.
+  _updateEntryStatus,
+  _generateSteerId,
 };

package/engine.js

@@ -1326,7 +1326,7 @@ async function spawnAgent(dispatchItem, config) {
   // work-item prompts after setup because reused worktrees can live at arbitrary paths.
   const systemPrompt = buildSystemPrompt(agentId, config, project);
   const agentContext = buildAgentContext(agentId, config, project);
-  const pendingSteering = steering.buildPendingSteeringPrompt(agentId);
+  const pendingSteering = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
   const completionReportPath = shared.dispatchCompletionReportPath(id);
   if (completionReportPath) {
     try {
@@ -2793,7 +2793,7 @@ async function spawnAgent(dispatchItem, config) {
       // Write new prompt with all unACKed steering messages. This keeps delivery
       // durable if the killed process had older pending messages that never
       // produced processing evidence before the resume.
-      const pendingForResume = steering.buildPendingSteeringPrompt(agentId);
+      const pendingForResume = steering.buildPendingSteeringPrompt(agentId, { currentDispatchId: id });
       const steerPromptBody = pendingForResume.prompt || steerMsg;
       const steerPrompt = `Message from your human teammate:\n\n${steerPromptBody}\n\nRespond to this, then continue working on your current task.`;
       const steerPromptPath = path.join(dispatchTmpDir, `prompt-steer-${safeId}.md`);
@@ -7254,6 +7254,10 @@ async function tickInner() {
   // 1. Check for timed-out agents, steering messages, and idle threshold
   safe('checkTimeouts', () => checkTimeouts(config));
   safe('checkSteering', () => checkSteering(config));
+  safe('checkSpawnPhaseStalls', () => {
+    const { checkSpawnPhaseStalls } = require('./engine/spawn-phase-watchdog');
+    checkSpawnPhaseStalls(activeProcesses, config);
+  });
   safe('checkIdleThreshold', () => checkIdleThreshold(config));
 
   // 1b. Check for meeting round timeouts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2124",
+  "version": "0.1.2126",
   "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"