@yemi33/minions 0.1.1974 → 0.1.1976

package/dashboard/js/render-work-items.js

@@ -51,6 +51,15 @@ function wiRow(item) {
       (item._reopened ? ' <span style="font-size:9px;color:var(--purple);margin-left:4px" title="This item was reopened from a previously completed state">reopened</span>' : '') +
       (item._pendingReason && item.status === 'pending' && item._pendingReason !== 'already_dispatched' ? ' <span style="font-size:9px;color:var(--muted);margin-left:4px" title="Pending reason: ' + escapeHtml(item._pendingReason) + '">' + escapeHtml(item._pendingReason.replace(/_/g, ' ')) + '</span>' : '') +
       (item._pendingReason === 'already_dispatched' && item.status === 'pending' ? ' <span style="font-size:9px;color:var(--blue);margin-left:4px" title="In dispatch queue, waiting to be assigned">queued</span>' : '') +
+      (item._managedSpawnPartial && Array.isArray(item._managedSpawnPartial.failed) && item._managedSpawnPartial.failed.length
+        ? ' <span style="font-size:9px;color:var(--yellow);margin-left:4px;border:1px solid var(--yellow);padding:0 4px;border-radius:6px" title="managed-spawn: '
+            + escapeHtml(((item._managedSpawnPartial.healthy || []).length) + '/' + (((item._managedSpawnPartial.healthy || []).length) + item._managedSpawnPartial.failed.length))
+            + ' healthy — failed: '
+            + escapeHtml(item._managedSpawnPartial.failed.map(function(f){ return (f && f.name) || '?'; }).join(', '))
+            + '. Click row for details.">&#x26A0; managed-spawn: '
+            + escapeHtml(((item._managedSpawnPartial.healthy || []).length) + '/' + (((item._managedSpawnPartial.healthy || []).length) + item._managedSpawnPartial.failed.length))
+            + ' healthy</span>'
+        : '') +
       (item._skipReason && item.status === 'pending' ? ' <span style="font-size:9px;color:var(--yellow);margin-left:4px" title="Dispatch blocked: ' + escapeHtml(item._skipReason) + (item._blockedBy ? ' (by ' + escapeHtml(item._blockedBy) + ')' : '') + '">' + escapeHtml(item._skipReason.replace(/_/g, ' ')) + (item._blockedBy ? ' <span style="color:var(--muted)">(' + escapeHtml(item._blockedBy) + ')</span>' : '') + '</span>' : '') +
       (item.status === 'failed' ? ' ' + wiRetryBtn(item) : '') +
     '</td>' +
@@ -472,6 +481,26 @@ function openWorkItemDetail(id) {
   if (item.completedAt) html += field('Completed', escapeHtml(formatLocalDateTime(item.completedAt)));
   if (item.failReason) html += field('Failure Reason', '<span style="color:var(--red)">' + escapeHtml(item.failReason) + '</span>');
   if (item._pendingReason && item.status === 'pending') html += field('Pending Reason', item._pendingReason === 'already_dispatched' ? 'Queued — waiting for available agent slot' : escapeHtml(item._pendingReason.replace(/_/g, ' ')));
+  if (item._managedSpawnPartial && Array.isArray(item._managedSpawnPartial.failed) && item._managedSpawnPartial.failed.length) {
+    var _msp = item._managedSpawnPartial;
+    var _mspHealthy = Array.isArray(_msp.healthy) ? _msp.healthy : [];
+    var _mspTotal = _mspHealthy.length + _msp.failed.length;
+    var _mspBody = '<div style="color:var(--yellow);font-size:11px;margin-bottom:6px">'
+      + escapeHtml(_mspHealthy.length + '/' + _mspTotal) + ' specs healthy. Failed: '
+      + escapeHtml(_msp.failed.map(function(f){ return (f && f.name) || '?'; }).join(', '))
+      + (_msp.evaluated_at ? ' <span style="color:var(--muted)">(evaluated ' + escapeHtml(_msp.evaluated_at) + ')</span>' : '')
+      + '</div>';
+    _mspBody += _msp.failed.map(function(f) {
+      var name = escapeHtml((f && f.name) || '?');
+      var reason = escapeHtml((f && f.reason) || 'unknown');
+      var tail = (f && f.log_tail) || '';
+      return '<details style="margin-bottom:6px"><summary style="cursor:pointer;font-size:11px"><strong>' + name + '</strong> — ' + reason + '</summary>'
+        + '<pre style="font-size:10px;max-height:240px;overflow:auto;padding:6px;background:var(--surface2);border:1px solid var(--border);border-radius:var(--radius-sm);margin:4px 0 0 0">'
+        + escapeHtml(tail || '(no log tail captured)')
+        + '</pre></details>';
+    }).join('');
+    html += field('Managed-spawn partial failure', _mspBody);
+  }
   if (item._skipReason && item.status === 'pending') html += field('Dispatch Blocked', '<span style="color:var(--yellow)">' + escapeHtml(item._skipReason.replace(/_/g, ' ')) + '</span>' + (item._blockedBy ? ' — blocked by <strong>' + escapeHtml(item._blockedBy) + '</strong>' : ''));
   // Defensive: CC dispatches can land here with these fields as strings
   // (e.g. acceptanceCriteria: "fix the login bug"). Coerce to arrays so

package/dashboard/styles.css

@@ -571,6 +571,7 @@
   .dispatch-type.decompose { background: rgba(188,140,255,0.2); color: var(--purple); }
   .dispatch-type.manual { background: rgba(139,148,158,0.15); color: var(--muted); }
   .dispatch-type.docs { background: rgba(56,189,248,0.15); color: #38bdf8; }
+  .dispatch-type.setup { background: rgba(20,184,166,0.15); color: #14b8a6; }
   .dispatch-agent { font-weight: 600; color: var(--text); }
   .dispatch-task { flex: 1; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
   .dispatch-time { font-size: var(--text-sm); color: var(--border); }

package/docs/managed-spawn.md

@@ -59,6 +59,14 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
 
 The renderer in [`buildManagedSpawnHint`](../engine/managed-spawn.js) at `engine/managed-spawn.js:419` emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
 
+### Smoke-test before writing the sidecar (mandatory, W-mpbpexrg00110661)
+
+The hint mandates that agents run each `cmd args` in the declared `cwd` for at least 5 seconds AND confirm the healthcheck endpoint returns the expected status BEFORE writing `managed-spawn.json`. Sidecars written from guessed-at commands are how dispatches silently lose specs: the engine spawns what the agent declared; if the command crashes on first launch, the engine kills the spec, removes it from state, and (for partial failures) marks the WI with `_managedSpawnPartial` rather than demoting it — the agent's primary work succeeded by validator standards. The cost of guessing wrong is the operator finding out hours later that half the stack is down.
+
+Real failure class to internalize: workspace-filter resolution (`bun -F <name>`, `pnpm --filter <name>`) failing because workspace deps were never installed in the worktree. Exits 1 in <1s with `No packages matched the filter`. Smoke-test catches it in seconds; an operator finding it catches it in hours (incident W-mpbolwvt000gb9b1: 1 of 3 Constellation specs survived, WI showed `done`).
+
+Both a PowerShell (Windows) and bash (macOS/Linux) example are inlined in the hint — see `buildManagedSpawnHint` for the canonical patterns.
+
 ## Healthcheck examples
 
 ### HTTP — most common
@@ -220,6 +228,7 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_D
 |---|---|---|
 | Dispatch ERROR `failure_class: invalid-managed-spawn` | Sidecar schema/allowlist violation | Read inbox alert; the validator includes a precise reason. Non-retryable — fix and re-dispatch. |
 | Dispatch ERROR `failure_class: managed-spawn-healthcheck` | `timeout_s` elapsed before any spec became healthy | Check `engine/managed-logs/<name>.log` for the child's crash output. Sibling spawns are left alive. Retryable. |
+| WI shows yellow `⚠ managed-spawn: N/M healthy` chip on dashboard | Partial healthcheck failure: ≥1 spec passed, ≥1 failed. WI keeps `status: done` (the agent's primary work — getting an accepted sidecar — succeeded); annotation `_managedSpawnPartial = { healthy, failed[{name, reason, log_tail}], evaluated_at }` lives on the WI. Click the row to see per-spec failure reasons + last 20 log lines. Dispatch is still recorded ERROR with `failure_class: managed-spawn-healthcheck-failed`. Restart the failing spec via `POST /api/managed-processes/restart` once you've fixed the root cause (often: workspace deps not installed; see smoke-test rule in the hint). W-mpbpexrg00110661. |
 | Spec gone after `minions restart` | Bun child died with parent (the original failure mode) | Should be fixed by item 2's detached-spawn pattern. If it recurs, verify `bin/minions.js spawnDashboard` semantics still work for the runtime — that's the canonical reference. |
 | Spec listed `alive: true, healthy: false` for >30s | Healthcheck loop self-detected service degradation | The spec did not pass a subsequent healthcheck. Inspect the service; restart via API once recovered. |
 | Stale row sticks around with dead PID | Spec killed outside Minions | Wait one sweep cycle (~30 min) or call `POST /api/managed-processes/kill` manually. |

package/engine/managed-spawn.js

@@ -480,7 +480,7 @@ function buildManagedSpawnHint(opts) {
     '1. Reads your sidecar after you exit.',
     '2. Spawns each spec detached (the working Windows pattern is centralised in the engine — you do **not** need to write `Start-Process` or `spawn({ detached: true })` yourself).',
     '3. Drives the healthcheck loop until each spec passes its first check (within `timeout_s`).',
-    '4. **Fails this dispatch (ERROR) if any spec fails its healthcheck.** Surviving siblings stay alive; failing PIDs are killed.',
+    '4. **Fails this dispatch (ERROR) if any spec fails its healthcheck.** Surviving siblings stay alive; failing PIDs are killed. When at least one spec stays healthy (partial failure) the engine also writes a `_managedSpawnPartial` annotation onto the WI (status stays `done`) so the dashboard surfaces a warning chip instead of silently swallowing the failure. When ALL specs fail the WI is demoted to FAILED via the normal force-demote path.',
     '5. Auto-injects a `## Live managed processes` block into downstream agents\' prompts (scoped to your project) so the next dispatch can find the service without you telling it.',
     '6. Sweeps dead PIDs / TTL-expired specs every ' + (limits.sweepEvery || 30) + ' ticks; kills + unlinks at TTL.',
     '',
@@ -496,6 +496,56 @@ function buildManagedSpawnHint(opts) {
     '',
     'If your file is invalid the engine marks this dispatch ERROR with `failure_class: invalid-managed-spawn` (non-retryable) — fix the file shape, don\'t retry blindly.',
     '',
+    '### Mandatory: smoke-test before writing the sidecar',
+    '',
+    'Before writing `managed-spawn.json`, run each `cmd args` in the declared `cwd` for at least 5 seconds. Confirm the process stays alive AND its healthcheck endpoint returns the expected status. Kill the test process. THEN write the sidecar. Sidecars written from guessed-at commands are how dispatches silently lose specs — the engine spawns what you declared; if you declared a command that crashes, the engine kills it and removes it from state without alerting the WI as failed. The cost of guessing wrong is the user finding out hours later that half the stack is down.',
+    '',
+    'Concrete failure class to avoid: workspace-filter resolution (e.g. `bun -F <name>` or `pnpm --filter <name>`) failing because the workspace deps were never installed in the worktree. The command exits 1 in <1s with `No packages matched the filter` and the engine kills the spec without surfacing anything beyond a partial-healthcheck annotation. Smoke-test catches this in seconds; the user finding out catches it in hours.',
+    '',
+    'Smoke-test pattern (PowerShell — Windows):',
+    '',
+    '```powershell',
+    '# Replace <cwd>, <cmd>, <args...>, <healthcheck-url>, <expected-status> with your spec values.',
+    'Push-Location <cwd>',
+    '$proc = Start-Process -FilePath <cmd> -ArgumentList \'<arg1>\',\'<arg2>\' -PassThru -WindowStyle Hidden -RedirectStandardOutput smoke.out -RedirectStandardError smoke.err',
+    'try {',
+    '  $deadline = (Get-Date).AddSeconds(15)',
+    '  $healthy  = $false',
+    '  while ((Get-Date) -lt $deadline) {',
+    '    if ($proc.HasExited) { throw "spec exited early with code $($proc.ExitCode); tail smoke.err for the reason" }',
+    '    try {',
+    '      $r = Invoke-WebRequest -Uri \'<healthcheck-url>\' -UseBasicParsing -TimeoutSec 2',
+    '      if ($r.StatusCode -eq <expected-status>) { $healthy = $true; break }',
+    '    } catch { Start-Sleep -Milliseconds 500 }',
+    '  }',
+    '  if (-not $healthy) { throw "spec stayed alive but healthcheck never returned <expected-status> within 15s" }',
+    '  Write-Host "smoke-test OK — spec stayed alive AND healthcheck passed"',
+    '} finally {',
+    '  if (-not $proc.HasExited) { Stop-Process -Id $proc.Id -Force }',
+    '  Pop-Location',
+    '}',
+    '```',
+    '',
+    'Smoke-test pattern (bash — macOS/Linux):',
+    '',
+    '```bash',
+    '# Replace <cwd>, <cmd>, <args...>, <healthcheck-url>, <expected-status> with your spec values.',
+    'cd <cwd>',
+    '<cmd> <arg1> <arg2> >smoke.out 2>smoke.err &',
+    'pid=$!',
+    'healthy=0',
+    'for _ in $(seq 1 15); do',
+    '  if ! kill -0 "$pid" 2>/dev/null; then echo "spec exited early; tail smoke.err for the reason" >&2; break; fi',
+    '  if [ "$(curl -s -o /dev/null -w \'%{http_code}\' --max-time 2 \'<healthcheck-url>\')" = "<expected-status>" ]; then healthy=1; break; fi',
+    '  sleep 1',
+    'done',
+    'kill "$pid" 2>/dev/null || true',
+    'wait "$pid" 2>/dev/null || true',
+    '[ "$healthy" = 1 ] && echo "smoke-test OK — spec stayed alive AND healthcheck passed" || { echo "smoke-test FAILED" >&2; exit 1; }',
+    '```',
+    '',
+    'A passing smoke-test is the entry gate to writing the sidecar — not a nice-to-have. If you skip it, you are betting the WI completion against a command you never ran.',
+    '',
     '### Verify before exit',
     '',
     'After you write the file, query the engine to confirm acceptance:',

package/engine.js

@@ -2393,12 +2393,35 @@ async function spawnAgent(dispatchItem, config) {
             try { managedSpawn.removeManagedSpec(f.name); }
             catch (e) { log('warn', `managed-spawn healthcheck: cleanup failed for ${f.name}: ${e.message}`); }
           }
+          // W-mpbpexrg00110661 — capture per-spec log tails (last 20 lines) so
+          // the WI annotation can surface them in the dashboard chip without
+          // re-reading the log files later. Use the same tailManagedLog helper
+          // the inbox alert uses; cap each tail to 2KB to bound the WI write.
+          const _failedDetails = failed.map(f => {
+            let tail = '';
+            try { tail = (managedSpawn.tailManagedLog(f.name, 20) || '').slice(-2048); }
+            catch (_e) { tail = ''; }
+            return { name: f.name, reason: f.error, log_tail: tail };
+          });
+          const _survivedNames = items.filter(it => !failed.some(f => f.name === it.name)).map(it => it.name);
           managedSpawnHealthcheckFailure = {
             failed: failed,
-            survivedNames: items.filter(it => !failed.some(f => f.name === it.name)).map(it => it.name),
+            survivedNames: _survivedNames,
+            // partial = at least one spec survived. Drives the
+            // processWorkItemFailure: false override below so the WI stays
+            // `done` (the agent's primary work — declaring an accepted sidecar
+            // — succeeded; the dashboard surfaces the warning via
+            // _managedSpawnPartial instead of demoting to FAILED).
+            partial: _survivedNames.length > 0,
+            annotation: {
+              healthy: _survivedNames,
+              failed: _failedDetails,
+              evaluated_at: new Date().toISOString(),
+            },
           };
-          log('warn', `managed-spawn healthcheck: ${failed.length}/${items.length} spec(s) failed for ${agentId} (${id}); ` +
-            failed.map(f => `${f.name}=${f.error}`).join('; '));
+          log('warn', `managed-spawn healthcheck: ${failed.length}/${items.length} spec(s) failed for ${agentId} (${id})` +
+            (managedSpawnHealthcheckFailure.partial ? ' (partial — WI stays done, annotated)' : ' (total — WI will be demoted)') +
+            `; ` + failed.map(f => `${f.name}=${f.error}`).join('; '));
           try {
             const wiId = dispatchItem.meta?.item?.id || '';
             const logTails = failed.map(f => {
@@ -2468,7 +2491,18 @@ async function spawnAgent(dispatchItem, config) {
           : FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA)
       : null;
     const completeOpts = managedSpawnHealthcheckFail
-      ? { ...completionOpts, failureClass: FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED, agentRetryable: false }
+      ? {
+          ...completionOpts,
+          failureClass: FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED,
+          agentRetryable: false,
+          // W-mpbpexrg00110661 — partial healthcheck failure: at least one spec
+          // stayed healthy. The agent's primary work (declaring + getting an
+          // accepted sidecar) succeeded, so don't force-demote the WI. The
+          // _managedSpawnPartial annotation written after completeDispatch is
+          // the visibility lever. Total failure (no survivors) still
+          // force-demotes through the normal FORCE_DEMOTE_FAILURE_CLASSES path.
+          ...(managedSpawnHealthcheckFailure.partial ? { processWorkItemFailure: false } : {}),
+        }
       : (managedSpawnAcceptanceFail
         ? { ...completionOpts, failureClass: FAILURE_CLASS.INVALID_MANAGED_SPAWN, agentRetryable: false }
         : (keepProcessesAcceptanceFail
@@ -2581,6 +2615,31 @@ async function spawnAgent(dispatchItem, config) {
 
     completeDispatch(id, effectiveResult, errorReason, resultSummary, completeOpts);
 
+    // W-mpbpexrg00110661 — surface managed-spawn partial-healthcheck failures
+    // on the WI so the dashboard renders a warning chip instead of silently
+    // swallowing the loss. This runs regardless of partial vs total failure:
+    //   - Partial (survivors > 0): WI status stayed `done` because we passed
+    //     processWorkItemFailure:false above; the annotation tells operators
+    //     half the stack is down.
+    //   - Total (no survivors): WI was force-demoted to FAILED by the
+    //     FORCE_DEMOTE_FAILURE_CLASSES path; the annotation still attaches
+    //     for forensics so the dashboard can show which specs failed and
+    //     their log tails without operators having to dig through
+    //     engine/managed-logs/.
+    if (managedSpawnHealthcheckFailure && managedSpawnHealthcheckFailure.annotation && dispatchItem.meta?.item?.id) {
+      try {
+        const wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (wiPath) {
+          mutateWorkItems(wiPath, items => {
+            const wi = items.find(i => i.id === dispatchItem.meta.item.id);
+            if (!wi) return items;
+            wi._managedSpawnPartial = managedSpawnHealthcheckFailure.annotation;
+            return items;
+          });
+        }
+      } catch (e) { log('warn', `managed-spawn partial-healthcheck: failed to annotate WI: ${e.message}`); }
+    }
+
     // W-mp6k7ywi000fa33c / W-mp7i902u000l991f — surface the keep_processes
     // rejection on the WI so the dashboard pending-reason area shows the
     // missing structure instead of a bare failure_class label. _pendingReason

package/package.json

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