@yemi33/minions 0.1.1975 → 0.1.1977

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/docs/deprecated.json

@@ -1,4 +1,18 @@
 [
+  {
+    "id": "managed-spawn-env-allowlist",
+    "removedAt": "2026-05-18",
+    "reason": "ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist + envKeyAllowlistPrefixes removed; replaced by envKeyDenyPatterns + envKeyDenyOverrides. The allowlist shape required an engine PR for every new framework/project env prefix (W-mpbpa09c000rd513 tried per-project allowlist extension; user steered away — 'make sure that we are not hardcoding any env variables or being so rigid about it'). The denylist shape matches the actual credential-leakage threat model and lets plain project vars like CONSTELLATION_SERVER, DATABASE_URL, REDIS_HOST work with zero engine config while still blocking credential-shaped keys (AWS_*, *_TOKEN, *_SECRET, etc.). Per-project tightening is supported via project.managedSpawnExtraDenyPatterns (additive only, no per-project override list).",
+    "removedLocations": [
+      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlist (15 keys)",
+      "engine/shared.js ENGINE_DEFAULTS.managedSpawn.envKeyAllowlistPrefixes (8 prefixes)",
+      "engine/managed-spawn.js _envKeyAllowed (rewritten to deny+override+shape model)",
+      "engine/managed-spawn.js buildManagedSpawnHint (env-key guidance rewritten)",
+      "PR #2624 (closed, superseded — added per-project allowlist union; replaced here by per-project deny tightening)",
+      "test/unit/managed-spawn-validator.test.js 4e/4f/11a (rewritten for denylist semantics)"
+    ],
+    "notes": "Already removed in this PR; entry exists to track the breaking shape change in the deprecation log. Delete entry after 3 days per /cleanup-deprecated."
+  },
   {
     "id": "config-poll-key-migration",
     "location": "engine/queries.js:123-162",

package/docs/managed-spawn.md

@@ -36,7 +36,7 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
       "cmd": "bun",                          // must be on engine.managedSpawn.executableAllowlist
       "args": ["run", "dev"],                // ≤64 entries
       "cwd": "D:/repos/constellation",       // must be a real git worktree (requireGitWorkdir: true)
-      "env": { "VITE_HOST": "127.0.0.1" },   // ≤32 keys; allowlist + prefix-allowlist enforced
+      "env": { "CONSTELLATION_SERVER": "http://localhost:3000" },  // ≤32 keys; POSIX-shape + denylist enforced
       "ports": [3001],                       // 1024-65535; ≤20 per spec; advisory only (engine doesn't bind)
       "ttl_minutes": 240,                    // ≤1440 (24h hard cap); defaults to 240 (4h)
       "attrs": {                             // opaque per-spec metadata, ≤2048 bytes serialized
@@ -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
@@ -211,8 +219,8 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_D
 | `promptContextMaxBytes` | `2048` | Auto-injected `## Live managed processes` block cap. |
 | `requireGitWorkdir` | `true` | Reject specs whose `cwd` isn't a git worktree. |
 | `executableAllowlist` | `[node, bun, npm, …]` | Single global. Applies to `spec.cmd` AND `command` healthcheck `cmd`. |
-| `envKeyAllowlist` | `[NODE_ENV, PORT, …]` | Exact-match env keys. |
-| `envKeyAllowlistPrefixes` | `[VITE_, NEXT_, …]` | Prefix-match env keys. |
+| `envKeyDenyPatterns` | `[^AWS_, ^AZURE_, _SECRET, _TOKEN, _API_KEY, …]` | Regex source strings, matched case-insensitively. Keys matching ANY pattern are rejected unless exact-listed in `envKeyDenyOverrides`. Threat model: credential leakage, not env-key enumeration — plain project vars (`CONSTELLATION_SERVER`, `DATABASE_URL`, …) pass with no config. |
+| `envKeyDenyOverrides` | `[AWS_REGION, AWS_DEFAULT_REGION, AZURE_REGION, GCP_REGION, AWS_PROFILE]` | Exact-match exemptions for known-safe keys that would otherwise be caught by a broad prefix pattern. Case-sensitive. |
 
 ## Failure modes
 
@@ -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

@@ -64,15 +64,78 @@ function _isOnAllowlist(name, allowlist) {
   return false;
 }
 
-function _envKeyAllowed(key, limits) {
-  if (typeof key !== 'string' || key.length === 0) return false;
-  const allowlist = Array.isArray(limits.envKeyAllowlist) ? limits.envKeyAllowlist : [];
-  if (allowlist.indexOf(key) >= 0) return true;
-  const prefixes = Array.isArray(limits.envKeyAllowlistPrefixes) ? limits.envKeyAllowlistPrefixes : [];
-  for (const p of prefixes) {
-    if (typeof p === 'string' && p.length > 0 && key.indexOf(p) === 0) return true;
+// Env-key shape guard. Bash/POSIX-style identifier: leading letter or
+// underscore, followed by letters / digits / underscores. Rejects keys with
+// shell metachars ('FOO;BAR', 'FOO BAR', '$FOO') regardless of deny rules —
+// argv smuggling protection, separate from the credential-shape threat
+// model below.
+const _ENV_KEY_SHAPE_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Compile envKeyDenyPatterns once per validator invocation and cache. The
+// returned object also carries the override Set for fast exact-match lookup.
+// All patterns are compiled case-insensitively so '_secret' / '_SECRET' are
+// equivalent; overrides remain case-sensitive (exact match).
+function _compileDenyRules(limits, projectExtraPatterns) {
+  const globalPatterns = Array.isArray(limits.envKeyDenyPatterns) ? limits.envKeyDenyPatterns : [];
+  const extra = Array.isArray(projectExtraPatterns) ? projectExtraPatterns : [];
+  const overridesArr = Array.isArray(limits.envKeyDenyOverrides) ? limits.envKeyDenyOverrides : [];
+  const sources = [];
+  const compiled = [];
+  for (const src of globalPatterns.concat(extra)) {
+    if (typeof src !== 'string' || src.length === 0) continue;
+    let re;
+    try { re = new RegExp(src, 'i'); }
+    catch (_e) { continue; }
+    sources.push(src);
+    compiled.push(re);
   }
-  return false;
+  const overrides = new Set();
+  for (const k of overridesArr) {
+    if (typeof k === 'string' && k.length > 0) overrides.add(k);
+  }
+  return { sources, compiled, overrides };
+}
+
+// Check an env key against compiled deny rules. Returns
+// { allowed: true } when the key passes, or
+// { allowed: false, reason: 'env-key-denied (matched pattern X)' }
+// when blocked. Does NOT enforce the shape guard — callers do that
+// separately so shape-failures get a distinct reason.
+function _envKeyAllowed(key, denyRules) {
+  if (typeof key !== 'string' || key.length === 0) {
+    return { allowed: false, reason: 'env-key-empty' };
+  }
+  if (denyRules.overrides.has(key)) return { allowed: true };
+  for (let i = 0; i < denyRules.compiled.length; i++) {
+    if (denyRules.compiled[i].test(key)) {
+      return { allowed: false, reason: 'env-key-denied (matched pattern ' + denyRules.sources[i] + ')' };
+    }
+  }
+  return { allowed: true };
+}
+
+// Find the configured project whose `localPath` contains the spec's cwd.
+// Returns the most-specific match (longest matching localPath) so nested
+// project layouts (e.g. /repos/parent and /repos/parent/sub) prefer the
+// inner one. Returns null when no project matches or when inputs are
+// missing. Pure — does not touch disk.
+function _resolveProjectForCwd(cwd, projects) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return null;
+  if (!Array.isArray(projects) || projects.length === 0) return null;
+  let best = null;
+  let bestLen = -1;
+  for (const p of projects) {
+    if (!p || typeof p !== 'object') continue;
+    const lp = typeof p.localPath === 'string' ? p.localPath : '';
+    if (!lp) continue;
+    if (!shared.isPathInsideOrEqual(cwd, lp)) continue;
+    const len = path.resolve(lp).length;
+    if (len > bestLen) {
+      best = p;
+      bestLen = len;
+    }
+  }
+  return best;
 }
 
 // Extract the first executable-like token from a shell-style healthcheck cmd
@@ -229,7 +292,16 @@ function _validateSpec(spec, index, limits, opts) {
     }
   }
 
-  // env (optional)
+  // env (optional). Validation has three independent layers:
+  //   1. Shape guard: key matches /^[A-Za-z_][A-Za-z0-9_]*$/ (argv-smuggling
+  //      protection). Reason: env-key-invalid-shape.
+  //   2. Denylist: key does NOT match any credential-shaped pattern unless
+  //      explicitly listed in envKeyDenyOverrides. Per-project tightening
+  //      (project.managedSpawnExtraDenyPatterns) can add MORE patterns
+  //      when spec.cwd resolves under that project's localPath — projects
+  //      can only tighten, never loosen (asymmetric on purpose; no
+  //      per-project override list).
+  //   3. Value sanity: string, ≤1000 chars.
   const envRaw = spec.env == null ? {} : spec.env;
   if (typeof envRaw !== 'object' || Array.isArray(envRaw)) {
     return { ok: false, reason: 'env-not-object' };
@@ -239,10 +311,22 @@ function _validateSpec(spec, index, limits, opts) {
   if (envKeys.length > maxEnv) {
     return { ok: false, reason: 'env-too-many (>' + maxEnv + ')' };
   }
+  const projectForSpec = _resolveProjectForCwd(
+    typeof spec.cwd === 'string' ? spec.cwd : '',
+    opts && Array.isArray(opts.projects) ? opts.projects : null,
+  );
+  const projectExtraPatterns = projectForSpec && Array.isArray(projectForSpec.managedSpawnExtraDenyPatterns)
+    ? projectForSpec.managedSpawnExtraDenyPatterns
+    : null;
+  const denyRules = _compileDenyRules(limits, projectExtraPatterns);
   const env = {};
   for (const k of envKeys) {
-    if (!_envKeyAllowed(k, limits)) {
-      return { ok: false, reason: 'env-key-not-on-allowlist (' + k + ')' };
+    if (!_ENV_KEY_SHAPE_RE.test(k)) {
+      return { ok: false, reason: 'env-key-invalid-shape (' + k + ')' };
+    }
+    const decision = _envKeyAllowed(k, denyRules);
+    if (!decision.allowed) {
+      return { ok: false, reason: decision.reason };
     }
     const v = envRaw[k];
     if (typeof v !== 'string') return { ok: false, reason: 'env-value-not-string (' + k + ')' };
@@ -323,10 +407,25 @@ function validateManagedSpawnRecord(parsed, opts) {
     return { ok: false, reason: 'specs-too-many (>' + maxSpecs + ')' };
   }
 
+  // Resolve `projects` for per-project env-deny tightening. Callers (tests,
+  // future engine wiring) may pre-supply `opts.projects` for determinism;
+  // when undefined we lazy-load from MINIONS_DIR/config.json so the engine
+  // close-handler doesn't have to change signature. A read failure or a
+  // config without `projects` falls back to `[]` — unchanged behavior, the
+  // global deny patterns remain the only source.
+  let projects;
+  if (Array.isArray(opts.projects)) {
+    projects = opts.projects;
+  } else {
+    try { projects = shared.getProjects(); }
+    catch (_e) { projects = []; }
+  }
+  const specOpts = Object.assign({}, opts, { projects: projects });
+
   const seen = new Set();
   const out = [];
   for (let i = 0; i < parsed.specs.length; i++) {
-    const v = _validateSpec(parsed.specs[i], i, limits, opts);
+    const v = _validateSpec(parsed.specs[i], i, limits, specOpts);
     if (!v.ok) {
       // Preserve workdir-rejection prefix at the top level so the engine
       // close-handler gate can key off it the same way it does for
@@ -480,7 +579,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.',
     '',
@@ -489,13 +588,63 @@ function buildManagedSpawnHint(opts) {
     '- Specs per file: ≤ ' + maxSpecs,
     '- Name: kebab-case, ≤ 64 chars, unique within file',
     '- Executable (`cmd` and any `command` healthcheck cmd): on the engine\'s allowlist (node, bun, npm, npx, python, docker, adb, gradle, mvn, pwsh, …)',
-    '- Env keys: on the engine\'s allowlist or matching a known prefix (e.g. `VITE_`, `NEXT_`, `REACT_APP_`, `npm_config_`)',
+    '- Env keys: any well-formed POSIX identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`) is accepted EXCEPT keys matching credential-shaped deny patterns (`*_SECRET`, `*_TOKEN`, `*_API_KEY`, `*_PASSWORD`, `*_PRIVATE_KEY`, `*_CREDENTIALS`, `*_AUTH`, `*_PAT`, `AWS_*`, `AZURE_*`, `GCP_*`, `GH_TOKEN`, `GITHUB_TOKEN`, `OPENAI_*`, `ANTHROPIC_*`, `COPILOT_*`, `DOCKER_AUTH*`, `NPM_TOKEN`). Region/profile names (`AWS_REGION`, `AWS_PROFILE`, …) are exempt. If your service genuinely needs a credential-looking var, rename it (e.g. `DATABASE_URL` not `DB_API_KEY`) or stash the value in `attrs` and have the child read it from there. **The engine forwards env values verbatim — the deny shape is a tripwire, not a scrubber. Do not put real credentials in env even if the key passes.** Projects may tighten by adding patterns to `config.projects[N].managedSpawnExtraDenyPatterns`; projects cannot loosen.',
     '- Ports: 1024–65535, ≤ 20 per spec',
     '- TTL: ≤ ' + maxTtl + ' minutes (hard cap), defaults to ' + defaultTtl + ' if omitted',
     '- `attrs` serialized: ≤ 2048 bytes (opaque blob the engine surfaces to downstream agents)',
     '',
     '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/shared.js

@@ -1526,24 +1526,36 @@ const ENGINE_DEFAULTS = {
       'curl', 'wget',
       'git',
     ],
-    // Env-key allowlist (exact match). Tight by default so a managed spec
-    // can't leak credentials (AWS_*, AZURE_*, GH_TOKEN, etc.). Anything not
-    // here must match one of the allowed prefixes below.
-    envKeyAllowlist: [
-      'NODE_ENV', 'PORT', 'HOST', 'PATH',
-      'DEBUG', 'LOG_LEVEL',
-      'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP',
-      'LANG', 'LC_ALL',
-      'JAVA_HOME', 'ANDROID_HOME', 'ANDROID_SDK_ROOT',
+    // Env-key denylist (regex source strings, matched case-insensitively).
+    // The threat model is credential leakage, not env-key enumeration —
+    // any key NOT matching one of these patterns is accepted, so project
+    // vars like CONSTELLATION_SERVER / DATABASE_URL / REDIS_HOST work with
+    // zero engine config. Patterns are compiled lazily by the validator
+    // and tested in order; the first match wins for the reject reason, so
+    // the more specific prefix patterns are listed before the broad
+    // suffix patterns (a key like AWS_SECRET_ACCESS_KEY should report the
+    // narrower `^AWS_` cause, not the generic `_SECRET` cause). Extend
+    // with caution; broad patterns belong here, ecosystem allow
+    // exemptions belong in `envKeyDenyOverrides`.
+    envKeyDenyPatterns: [
+      // Prefix patterns first (more specific cause for vendor keys).
+      '^AWS_', '^AZURE_', '^GCP_', '^GOOGLE_APPLICATION_CREDENTIALS',
+      '^GH_TOKEN', '^GITHUB_TOKEN',
+      '^OPENAI_', '^ANTHROPIC_', '^COPILOT_',
+      '^DOCKER_AUTH', '^NPM_TOKEN',
+      // Suffix / substring patterns (generic credential shapes).
+      '_SECRET', '_TOKEN', '_API_KEY', '_APIKEY',
+      '_PASSWORD', '_PASSWD',
+      '_PRIVATE_KEY', '_PRIVKEY',
+      '_CREDENTIALS', '_AUTH', '_PAT',
     ],
-    // Env-key prefix allowlist. Standard ecosystem prefixes that frontends
-    // and tooling depend on (Vite, Next.js, CRA, npm scripts). Extend with
-    // caution; broad prefixes (`AWS_`, `AZURE_`) belong on a deny-list, not
-    // an allow-list.
-    envKeyAllowlistPrefixes: [
-      'VITE_', 'NEXT_', 'REACT_APP_', 'NUXT_', 'GATSBY_',
-      'npm_config_', 'NPM_CONFIG_',
-      'MINIONS_',
+    // Exact-match exemption list for keys that would otherwise be caught
+    // by a broad deny pattern (region/profile names aren't secrets).
+    // Match is case-sensitive — the override key must equal the spec key
+    // exactly.
+    envKeyDenyOverrides: [
+      'AWS_REGION', 'AWS_DEFAULT_REGION', 'AZURE_REGION', 'GCP_REGION',
+      'AWS_PROFILE',
     ],
   },
   // Backward-compat: keep `engine.claude.*` field family deprecation tracker. Listed here so preflight

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.1975",
+  "version": "0.1.1977",
   "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"