@yemi33/minions 0.1.1965 → 0.1.1967

package/docs/README.md

@@ -14,18 +14,21 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
-- [completion-reports.md](completion-reports.md) — Canonical schema for the per-dispatch completion JSON every agent writes (status, verdict, retryability, nonce trust boundary, artifacts).
+- [completion-reports.md](completion-reports.md) — Canonical schema for the per-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
 - [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.
 - [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`.
+- [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.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
-- [runtime-adapters.md](runtime-adapters.md) — Adapter contract (`engine/runtimes/<name>.js`), capability flags, runtime/model resolution helpers, and the "no `runtime.name === …` branching" rule.
+- [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.
 - [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop.
-- [skills.md](skills.md) — `.claude/skills/<name>/SKILL.md` format, `scope: minions` vs `scope: project`, auto-extraction from agent output, and per-runtime skill roots.
-- [team-memory.md](team-memory.md) — How `pinned.md`, `notes.md`, `knowledge/`, and per-agent memory files in `knowledge/agents/` flow into every agent prompt.
-- [watches.md](watches.md) — Persistent watch jobs: registry-driven target types, condition catalog, follow-up action registry, and the user-extensible `watches.d/` plugin folder.
+- [skills.md](skills.md) — Skill block format: how agents emit reusable `\`\`\`skill` blocks and how the engine extracts them into native personal-skill directories.
+- [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
+- [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.
+- [team-memory.md](team-memory.md) — Per-agent memory layer (`knowledge/agents/<id>.md`) and the consolidation/routing rules that populate it from `notes/inbox/`.
+- [watches.md](watches.md) — Persistent monitoring jobs (`engine/watches.json`): target-type registry, conditions, follow-up actions, and the `watches.d/` plugin folder.
 
 ## Operations
 
@@ -34,14 +37,8 @@ Operational runbooks for engine operators and fleet maintainers.
 - [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
-- [onboarding.md](onboarding.md) — First-run setup: installing the CLI, linking a project, the doctor preflight, and the first dispatch.
-
-## Design notes & explorations
-
-In-progress UX or architecture proposals; not yet shipped behavior.
-
-- [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX dashboard concept exploration (project picker, inline project link, decoupled folder picker).
-- [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Companion architecture suggestions for the slim-UX track.
+- [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.
+- [onboarding.md](onboarding.md) — First-30-minutes walkthrough for a new operator: install, init, dispatch a first work item, watch it land.
 
 ---
 

package/docs/managed-spawn.md

@@ -0,0 +1,259 @@
+# Managed-spawn primitive
+
+> Engine-owned long-running services with sidecar declaration, healthcheck-gated dispatch SUCCESS, and dashboard discovery.
+> Plan: [`plans/plan-w-mp7k1r760003b5dd-2026-05-15.md`](../plans/plan-w-mp7k1r760003b5dd-2026-05-15.md) · Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
+
+## Why this exists
+
+Before managed-spawn, Constellation (and similar multi-process projects) lost dev servers every time `minions restart` ran. The original Lambert/Ralph failure pattern:
+
+1. Agent spawned `bun dev` as a detached child.
+2. Wrote down PID in `keep-pids.json` so the engine wouldn't kill it.
+3. `minions restart` killed the engine but left the child running — *on Node*. **On `bun` + Windows the child died with the parent** because the Windows detached-spawn semantics differ across runtimes.
+4. Next dispatch landed against a dead URL with no signal it had died.
+
+Managed-spawn moves the spawn ownership from the agent into the engine. Agents *describe* services in a sidecar; the engine spawns them using the proven [`bin/minions.js spawnDashboard`](../bin/minions.js) pattern (works for Node, bun, python, docker, …), runs healthchecks, gates dispatch SUCCESS on first-healthy, sweeps dead PIDs / expired TTL, auto-injects live processes into downstream agent prompts, and exposes everything through `/api/managed-processes` + the dashboard.
+
+## When to use managed-spawn vs `keep_processes`
+
+| Need | Use this |
+|---|---|
+| Long-running dev server / emulator / build daemon that downstream agents need to hit | **managed-spawn** |
+| Short-lived helper the *same* agent needs alive past its exit (e.g. `gradle --daemon` for the next gradle invocation) | `meta.keep_processes` (existing per-agent `keep-pids.json`) |
+| One-shot script that exits on its own | Neither — just run it inline |
+
+Both can coexist. There's no plan to deprecate `keep_processes`; a future cleanup PR can revisit if managed-spawn fully subsumes its use cases.
+
+## Sidecar schema
+
+The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is read **once** by the engine in `onAgentClose`, after the agent's process exits. (Per-tick polling for sidecar edits is explicitly out of scope — pick a final shape before exit.)
+
+```jsonc
+{
+  "specs": [
+    {
+      "name": "constellation-host",          // kebab-case, ≤64 chars, unique within file
+      "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
+      "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
+        "base_url": "http://localhost:3001",
+        "framework": "vite"
+      },
+      "healthcheck": {                       // required for SUCCESS gating
+        "type": "http",                      // "http" | "command"
+        "url": "http://localhost:3001/health",
+        "expect_status": 200,
+        "interval_s": 1,
+        "timeout_s": 60                      // total wait for first-healthy before failing dispatch
+      }
+    }
+  ],
+  "written_by": "<your-agent-id>",
+  "wi_id": "<this-work-item-id>"
+}
+```
+
+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.
+
+## Healthcheck examples
+
+### HTTP — most common
+
+```jsonc
+"healthcheck": {
+  "type": "http",
+  "url": "http://localhost:3001/health",
+  "expect_status": 200,
+  "interval_s": 1,
+  "timeout_s": 60
+}
+```
+
+Probes `GET <url>` on `interval_s` cadence until `response.status === expect_status` or `timeout_s` elapses. No body assertion (deferred — see plan rejected items). Auth headers / cookies not supported (local dev only).
+
+### Command — anything that exits 0 + matches a regex
+
+```jsonc
+"healthcheck": {
+  "type": "command",
+  "cmd": "curl",
+  "args": ["-fsS", "http://localhost:3001/ready"],
+  "shell": false,
+  "expect_regex": "^ready$",
+  "interval_s": 2,
+  "timeout_s": 30
+}
+```
+
+Runs the command with `child_process.exec` / `spawn`, asserts both exit code 0 AND stdout matching `expect_regex`. The `cmd` must be on the same executable allowlist as `spec.cmd`. Use `command` healthchecks for:
+- Raw TCP — `Test-NetConnection -Port 3001 -ComputerName localhost` on Windows / `nc -z localhost 3001` on POSIX.
+- File presence — `Get-Content -Tail 1 log.txt` matching `^ready$`.
+- Database connectivity — `docker exec pg pg_isready`.
+
+`tcp` and `log-match` healthcheck types are intentionally not implemented — see the plan's Rejected items for the reasoning.
+
+## Lifecycle
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│ 1. Agent runs                                                     │
+│    - Playbook injects the managed-spawn hint when                 │
+│      work_item.meta.managed_spawn === true                        │
+│    - Agent writes agents/<id>/managed-spawn.json before exit      │
+└───────────────────────────────────┬───────────────────────────────┘
+                                    │ engine.onAgentClose
+                                    ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 2. evaluateManagedSpawnAcceptance(agentId)                        │
+│    - Validates schema, allowlists, caps                           │
+│    - Rejects → ERROR + alert + sidecar deleted                    │
+│      failure_class: invalid-managed-spawn (non-retryable)         │
+└───────────────────────────────────┬───────────────────────────────┘
+                                    │ accepted
+                                    ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 3. spawnManagedSpec(spec) per spec                                │
+│    - Uses the proven Windows detached-spawn pattern               │
+│    - Records each in engine/managed-processes.json (locked write) │
+│    - Stdio → engine/managed-logs/<name>.log (append fd, NOT pipe) │
+└───────────────────────────────────┬───────────────────────────────┘
+                                    │
+                                    ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 4. waitForFirstHealth(spec) per spec, in parallel                 │
+│    - Probes every interval_s, gives up at timeout_s               │
+│    - First success → state.healthy = true, last_health_at = now   │
+│    - Any failure → dispatch ERROR + sibling spawns left alive     │
+│      failure_class: managed-spawn-healthcheck (retryable)         │
+└───────────────────────────────────┬───────────────────────────────┘
+                                    │ all healthy
+                                    ▼
+┌───────────────────────────────────────────────────────────────────┐
+│ 5. Dispatch SUCCESS                                               │
+│    - Spec survives engine restart (PID detached + boot reconcile) │
+│    - Visible at /api/managed-processes + dashboard "Managed       │
+│      Processes" panel                                             │
+│    - Downstream agent prompts auto-inject a "## Live managed      │
+│      processes" block scoped to this project                      │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+Background work the engine does without further agent involvement:
+- **Per-tick** (cadence `engine.managedSpawn.sweepEvery: 30`, ~30 min): `sweepManagedSpawn()` drops dead-PID rows, kills + unlinks TTL-expired specs, rotates `managed-logs/<name>.log` past `logRotateBytes` (10MB).
+- **Per-engine-boot**: `bootReconcileManagedSpawn()` (timeout-bounded by `bootReconcileMaxMs: 2000` ms) drops dead PIDs, kills expired, runs one immediate healthcheck per survivor.
+- **Per-project-removal**: `removeManagedSpecsForProject(name)` (called from `engine/projects.js removeProject`) kills + unlinks specs whose `owner_project` matches.
+
+## WI 1 (build) → WI 2 (test) chained-validation pattern
+
+The canonical use case: split a build + smoke-test workflow across two work items so each can be retried / restarted independently.
+
+**WI 1 — build & host:**
+- `meta.managed_spawn: true`
+- Playbook: `implement` (or whichever fits)
+- Sidecar spec: dev server, emulator, or whatever the next WI needs.
+- `task_description`: build + verify locally, write the sidecar.
+- Engine gates SUCCESS on healthcheck → spec is healthy when this WI completes.
+
+**WI 2 — test against the live service:**
+- `dependencies: [WI-1-id]` (engine won't dispatch until WI 1 is SUCCESS)
+- `meta.managed_spawn: false` (or omit — no new specs to write)
+- Playbook auto-inject (from `engine/playbook.js`) ships a `## Live managed processes for project <name>` block in WI 2's prompt with WI 1's specs' `name`, `pid`, `attrs`, `log_path`, `ttl_expires_at`, and base URL.
+- WI 2 reads `attrs.base_url` from its prompt context, hits the live service, runs whatever test it needs to.
+
+Outcome: if WI 2 fails, the spec stays alive (TTL-managed) and the next dispatch of WI 2 reuses the same instance — no rebuild churn. If WI 1 fails healthcheck, WI 2 never dispatches; you fix WI 1 and retry.
+
+## Operating
+
+### Inspect at runtime
+
+| What you want | Where |
+|---|---|
+| All live specs (JSON) | `GET /api/managed-processes` |
+| Filtered to one project | `GET /api/managed-processes?project=<name>` |
+| One spec | `GET /api/managed-processes/by-name/<name>` |
+| Live log tail (SSE) | `GET /api/managed-processes/log-stream/<name>` |
+| Dashboard | http://localhost:7331/engine → "Managed Processes" |
+
+The list endpoint returns an ETag; pass it as `If-None-Match` on follow-up polls to get `304 Not Modified` when nothing changed. The dashboard panel does this automatically.
+
+### Force a restart / kill
+
+| Action | Endpoint | Dashboard |
+|---|---|---|
+| Kill (PID terminated, removed from state) | `POST /api/managed-processes/kill` `{"name":"…"}` | Per-row "Kill" button |
+| Restart (kill old PID, respawn from saved state, kick first healthcheck) | `POST /api/managed-processes/restart` `{"name":"…"}` | Per-row "Restart" button |
+
+Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale row in `managed-processes.json` until the next 30-tick sweep notices the dead PID. Prefer the API.
+
+### View logs
+
+`engine/managed-logs/<name>.log` — append-only, rotated to `<name>.log.1` at 10MB. The dashboard's "Log" button opens an SSE stream of the live tail.
+
+## Configuration
+
+All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
+
+| Key | Default | Notes |
+|---|---|---|
+| `enabled` | `true` | Global kill switch. `false` makes the engine ignore all sidecars + skip the sweep. |
+| `maxSpecsPerFile` | `5` | Per-agent cap. |
+| `maxTtlMinutes` | `1440` | Hard cap (24h). |
+| `defaultTtlMinutes` | `240` | Fallback when `ttl_minutes` omitted (4h). |
+| `sweepEvery` | `30` | Ticks between sweeps. Default tick = 60s ⇒ ~30 min. |
+| `defaultHealthIntervalSec` | `1` | Healthcheck cadence pre-first-healthy. |
+| `healthBackoffSec` | `30` | Healthcheck cadence post-first-healthy. |
+| `logRotateBytes` | `10485760` | Rotation threshold for `<name>.log`. |
+| `bootReconcileMaxMs` | `2000` | Boot-time reconcile hard timeout. |
+| `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. |
+
+## Failure modes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| 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. |
+| 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. |
+
+## Performance budget
+
+- **Per-tick contribution**: zero unless the 30-tick sweep fires. The sweep is `O(N)` over specs in `managed-processes.json` with one `process.kill(pid, 0)` per spec.
+- **Healthcheck loops**: per-spec, self-scheduled (not tick-coupled). 10 specs × 1s pre-healthy cadence ⇒ 10 probes/s peak. Post-healthy drops to one probe per `healthBackoffSec` (30s).
+- **Lock contention** on `managed-processes.json`: writes batch on transitions (healthy ↔ unhealthy), and `last_health_at` only persists every `healthBackoffSec` to avoid flap. See [`test/perf/managed-spawn-load.test.js`](../test/perf/managed-spawn-load.test.js) for the 10-spec / 3-project load assertion.
+- **Hard cap recommendation**: 50 specs across one engine. Above that, `process.kill(pid, 0)` shells out enough on Windows to dent tick latency.
+
+## Source map
+
+| File | Purpose |
+|---|---|
+| `engine/managed-spawn.js` | Schema, validator, spawn, healthcheck, sweep, state-file I/O. All pure helpers; no side effects on import. |
+| `engine.js` `onAgentClose` (line ~2247) | Acceptance gate (item 2) + healthcheck gate (item 3) wired into dispatch result. |
+| `engine.js` `tickInner` (line ~5687) | Per-30-tick `sweepManagedSpawn()` invocation. |
+| `engine/cli.js` | Boot-path `bootReconcileManagedSpawn()` invocation. |
+| `engine/playbook.js` | Auto-inject `## Live managed processes` block + `managed_spawn` hint section. |
+| `engine/projects.js` `removeProject` | `removeManagedSpecsForProject` cleanup hook. |
+| `dashboard.js` | 5 routes (`/api/managed-processes`, `…/by-name/<n>`, `…/kill`, `…/restart`, `…/log-stream/<n>`). |
+| `dashboard/js/render-managed.js` + `dashboard/pages/engine.html` | "Managed Processes" panel + log-viewer modal. |
+| `engine/shared.js` `ENGINE_DEFAULTS.managedSpawn` | All configurable knobs in one place. |
+
+## Plan items
+
+| # | PRD id | Lands what |
+|---|---|---|
+| 1 | P-7a3b1c92 | Schema, validator, sidecar reader, defaults |
+| 2 | P-2d5e8f04 | Engine spawn + locked state file |
+| 3 | P-9c1f47a6 | Healthcheck implementations + dispatch SUCCESS/ERROR gate |
+| 4 | P-4b8d2e57 | Discovery API (list / by-name / kill / restart + ETag) |
+| 5 | P-6e2a8b13 | Dashboard panel + SSE log viewer |
+| 6 | P-1f9c3a45 | Playbook auto-inject + dispatch hint |
+| 7 | P-8a4d6f29 | TTL sweep + boot reconcile + project-removal + log rotation |
+| 8 | P-3c7e9d18 | Load test + e2e + docs + Constellation smoke run *(this doc)* |

package/docs/watches.md

@@ -20,7 +20,7 @@ A watch is a small JSON record persisted to `engine/watches.json`. It binds:
 | `requires`   | Optional guard: array of predicate objects evaluated against `state` / `entity` / `prevState`; trigger is suppressed when any guard fails (false-or-error). Used to gate a watch on "PR is mergeable AND build passing" etc. |
 | `status`     | `WATCH_STATUS.ACTIVE` \| `PAUSED` \| `TRIGGERED` \| `EXPIRED`            |
 
-`createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists atomically via `mutateJsonFileLocked` *(source: `engine/watches.js:184`)*.
+`createWatch()` allocates a `watch-<uid>` id, defaults the fields above, and persists atomically via `mutateJsonFileLocked` *(source: `engine/watches.js:184-247`)*.
 
 ## Lifecycle (`WATCH_STATUS`)
 
@@ -33,7 +33,7 @@ Defined in `engine/shared.js:1875`:
 | `triggered` | Reserved status (set on demand by callers; not auto-applied)            |
 | `expired`   | Auto-set when `stopAfter` is reached, or on first trigger for absolute conditions when `stopAfter === 0`. The watch is left on disk for audit but no longer evaluated *(source: `engine/watches.js:507-508`)* |
 
-Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches.js:153-178`, `dashboard.js` `handleWatchesUpdate`)*.
+Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches.js` `updateWatch`, `dashboard.js` `handleWatchesUpdate`)*.
 
 ## Conditions (`WATCH_CONDITION`)
 
@@ -46,14 +46,16 @@ Defined in `engine/shared.js:1891-1929`. Conditions split into two families:
 
 When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR (or a permanently-true compound state assertion like `ready-for-merge`) doesn't keep notifying *(source: `engine/watches.js:507-508`)*.
 
+> **Per-target override (W-mp7hg58e000b5212):** the global `WATCH_ABSOLUTE_CONDITIONS` set is the legacy fallback. Each target type now declares its own `absoluteConditions: [...]` array in its spec; `registerTargetType` normalizes that into a `Set` that takes precedence at evaluation time. The plugin contract (see below) uses this to keep absolute-vs-change semantics local to each target type. Plugins that omit `absoluteConditions` get an empty set (all change-based).
+
 ### Change-based conditions
-`status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`, `head-commit-change`, `mergeable-flipped`, `behind-master`, `draft-flipped`, `dependency-met`, `stage-advanced`.
+`status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`, plus the predicate conditions added under P-w4e2f6a1 / P-w5b8d2c9 for the `pr`, `work-item`, `plan`, and `pipeline` target types (`head-commit-change`, `mergeable-flipped`, `behind-master`, `draft-flipped`, `stalled`, `dependency-met`, `stage-advanced`, `stuck-in-stage`). See `engine/shared.js:1891-1929` for the canonical enum.
+
+These compare the live entity against the watch's `_lastState` snapshot and run forever when `stopAfter === 0`. Baseline `_lastState` is captured on the first check so the very next change triggers the watch *(source: `engine/watches.js:434, 520`)*.
 
 ### Tick-counted conditions
 `stalled`, `stuck-in-stage` — require N consecutive unchanged captures (default `WATCH_STALLED_DEFAULT_TICKS = 12`, `WATCH_STUCK_STAGE_DEFAULT_TICKS = 12`, both in `engine/shared.js:1934-1935`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
 
-Change-based and tick-counted conditions compare the live entity against the watch's `_lastState` snapshot and run forever when `stopAfter === 0`. Baseline `_lastState` is captured on the first check so the very next change triggers the watch *(source: `engine/watches.js:434, 520`)*.
-
 ### Predicate conditions
 
 Several condition keys evaluate a derived predicate on the captured entity/state rather than comparing to `_lastState`. Built-in predicates per target type:
@@ -63,20 +65,21 @@ Several condition keys evaluate a derived predicate on the captured entity/state
 - **plan** — `all-items-done` (`items_done === items_total > 0`), `item-failed-n-times` (any `missing_features[*]._retryCount >= ENGINE_DEFAULTS.maxRetries`).
 - **pipeline** — `stage-advanced` (`current_stage_id` changed within the same `runId`), `stuck-in-stage` (current stage unchanged for `WATCH_STUCK_STAGE_DEFAULT_TICKS` checks, default 12).
 
-Compound state-assertion predicates (`ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`) live in `WATCH_ABSOLUTE_CONDITIONS` so they fire-once when `stopAfter === 0` — without that they would re-fire every tick while the assertion holds *(source: `engine/shared.js` `WATCH_ABSOLUTE_CONDITIONS`)*.
+Compound state-assertion predicates (`ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`) live in `WATCH_ABSOLUTE_CONDITIONS` so they fire-once when `stopAfter === 0` — without that they would re-fire every tick while the assertion holds *(source: `engine/shared.js:1938` `WATCH_ABSOLUTE_CONDITIONS`)*.
 
 ## Target Types — `TARGET_TYPES` Registry
 
-Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:101, 124-160`)*. Each spec must provide:
+Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:124-160`)*. Each spec must provide:
 
 - `label` — human name shown in dashboard pickers
 - `description` — short help text
 - `conditions` — non-empty array of accepted condition keys (also acts as the per-type allowlist)
+- `absoluteConditions` — *(optional)* subset of `conditions` that fire-once when `stopAfter === 0`; defaults to `[]` (all conditions treated as change-based)
 - `fetchEntity(target, state)` — entity-or-null lookup
 - `captureState(entity)` — snapshot used for change-detection diffs
 - `evaluate(condition, entity, prevState, target)` — returns `{ triggered, message }`
 
-The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard *(source: `engine/watches.js:124-184`)*.
+The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard *(source: `engine/watches.js:124-178`)*.
 
 ### User-extensible via `watches.d/` (W-mp7hg58e000b5212)
 
@@ -86,7 +89,7 @@ Canonical example: `watches.d/http.js` (W-mp7i22mu00191b07) — a generic HTTP p
 
 ### Built-in target types
 
-The eight built-ins are registered at module load *(source: `engine/watches.js:672-1271`)*. Constants live at `engine/shared.js:1881-1890` (`WATCH_TARGET_TYPE`).
+The eight built-ins are registered at module load *(source: `engine/watches.js:672-1311`)*. Constants live at `engine/shared.js:1881-1890` (`WATCH_TARGET_TYPE`).
 
 | `targetType`  | Target value                         | Conditions                                                                 | Notes |
 |---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
@@ -99,15 +102,38 @@ The eight built-ins are registered at module load *(source: `engine/watches.js:6
 | `dispatch`    | Dispatch entry id                    | `completed`, `failed`, `status-change`, `any`                              | Looks across `pending` / `active` / `completed` lists |
 | `agent`       | Agent id                             | `activity-change`, `status-change`, `any`                                  | `activity-change` fires only on transitions in/out of `'working'` |
 
-`evaluateWatch` dispatches to `tt.evaluate(...)`; unknown target types return `"Unknown target type: ..."` and unknown conditions return `"Unknown condition: ..."` — both are non-triggering *(source: `engine/watches.js:318+`)*.
+`evaluateWatch` dispatches to `tt.evaluate(...)`; unknown target types return `"Unknown target type: ..."` and unknown conditions return `"Unknown condition: ..."` — both are non-triggering *(source: `engine/watches.js:318-360`)*.
+
+### Plugin folder (`watches.d/`) — user-extensible target types
+
+W-mp7hg58e000b5212 added a **plugin folder** so operators can register new target types without editing engine source. At engine boot, `engine/watches.js` scans `<MINIONS_DIR>/watches.d/*.js` *after* the eight built-ins are registered (so plugins can override a built-in by re-using its key — last-write-wins) and calls `registerTargetType()` for each export *(source: `engine/watches.js:1313-1354`)*.
+
+Each `watches.d/<name>.js` file must export `{ name, spec }` (or an array of those):
+
+```js
+module.exports = {
+  name: 'my-target',
+  spec: {
+    label: 'My Target',
+    description: 'What it watches',
+    conditions: ['status-change', 'value-equals'],
+    absoluteConditions: ['value-equals'],          // optional, defaults to []
+    fetchEntity(target, state) { /* sync entity lookup */ },
+    captureState(entity) { /* snapshot for diffs */ },
+    evaluate(condition, entity, prevState, target) {
+      return { triggered: <bool>, message: '...' };
+    },
+  },
+};
+```
 
-### User-extensible target types via `watches.d/`
+Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both dev checkouts and installed `~/.minions/` layouts. Missing folder is silent; per-file failures are isolated (load errors log a `WARN` line, don't abort boot). Tests can re-scan via the exported `_loadPluginTargetTypes()`.
 
-`engine/watches.js` boot-loads optional plugin files from `~/.minions/watches.d/*.js` (and the equivalent under `MINIONS_DIR` for tests). Each plugin module exports `{ name, spec }` (or an array thereof) and is passed straight to `registerTargetType()`. Plugins can override built-ins by name, so a user can extend or replace shipped behavior without editing engine code. The shipped `http` target type (live URL polling: `status-change`, `failed`, `ran`, `any`) lands as the first reference plugin — see `watches.d/http.js` for the canonical example.
+**Canonical plugin example:** [`watches.d/http.js`](../watches.d/http.js) (W-mp7i22mu00191b07) ships a generic `http` target type — point a watch at any URL or `{ url, method, headers, body, extract, expected, regex, timeoutMs }` config and the plugin exposes `status-change`, `value-change`, `value-equals`, `value-matches`, and `http-error` conditions. Auth headers support `{{env.GH_TOKEN}}`-style substitution at fetch time (secrets are never stored in `watches.json`). All conditions are change-based (`absoluteConditions: []`).
 
 ## Tick Integration
 
-`engine.js` calls `checkWatches(config, state)` every 3 ticks (~3 min at the default 60s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:5449-5507`)*. The engine builds the state object from cached project files + module reads:
+`engine.js` calls `checkWatches(config, state)` every 3 ticks (~3 min at the default 60s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:5432-5485`)*. The engine builds the state object from cached project files + module reads:
 
 ```
 {
@@ -118,7 +144,7 @@ The eight built-ins are registered at module load *(source: `engine/watches.js:6
 }
 ```
 
-`checkWatches` walks every active watch and, inside a single `mutateJsonFileLocked` callback *(source: `engine/watches.js:410+`)*:
+`checkWatches` walks every active watch and, inside a single `mutateJsonFileLocked` callback *(source: `engine/watches.js:410-560`)*:
 
 1. Skips paused/expired watches and any watch checked within its `interval`.
 2. Captures a baseline `_lastState` on first check (so change conditions have something to diff).
@@ -128,11 +154,11 @@ The eight built-ins are registered at module load *(source: `engine/watches.js:6
 6. On non-trigger: writes a per-poll inbox note when `onNotMet === 'notify'`.
 7. Refreshes `_lastState` for the next check.
 
-I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up actions via `_runActionTask` (`Promise` per action, failures isolated). Each action's result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write *(source: `engine/watches.js:410+`)*.
+I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up actions via `_runActionTask` (`Promise` per action, failures isolated). Each action's result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write *(source: `engine/watches.js:562+` `_runActionTask`)*.
 
 ## Follow-Up Actions on Trigger
 
-`watch.action` is an optional structured action that runs after the inbox notification fires. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:112-115`, `engine/watch-actions.js:223-330`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
+`watch.action` is an optional structured action that runs after the inbox notification fires. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:184-247` `createWatch`, `engine/watch-actions.js:223-330` `registerActionType`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
 
 ### Built-in actions
 
@@ -148,7 +174,7 @@ I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up ac
 | `archive-plan`         | Set PRD `status="archived"` + `archivedAt`                                                    |
 | `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
 
-Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:1960+`); handlers in `engine/watch-actions.js:332-700`.
+Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:1960`); handlers in `engine/watch-actions.js`.
 
 ### Templating
 
@@ -208,20 +234,21 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 | Watch never fires                                                       | Check `status === 'active'`; check `last_checked` advancing each cycle; confirm engine tick is running and `interval` isn't longer than your test window |
 | `evaluateWatch` returns `"<label> <target> not found"`                   | `fetchEntity` got nothing back — wrong `target` (e.g. PR display id vs canonical id), the target type isn't loaded, or the underlying file (PR cache, plan PRD) doesn't exist |
 | `"Unknown target type"` / `"Unknown condition"`                         | The registry doesn't recognise the value. Check `GET /api/watches/target-types` to see what's registered server-side; condition must be in that target type's `conditions[]` |
-| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches.js:434, 520`)*. If you see this, suspect manual edits to `watches.json` |
+| Change condition fires immediately on first tick                        | Won't happen — baseline `_lastState` is captured on the first check before `evaluate` runs *(source: `engine/watches.js:434`)*. If you see this, suspect manual edits to `watches.json` |
 | Absolute watch fires forever instead of once                            | `stopAfter` is set to a non-zero value; only `stopAfter === 0` triggers fire-once expiration |
 | Action runs but inbox notification doesn't                              | `notify` field isn't `'inbox'`, or `owner` is empty. `notify` and `action` are independent — both can fire, or only one |
 | `_lastActionResult.ok === false` with `"unknown action type"`           | The `action.type` isn't registered. List with `listActionTypes()` / `GET /api/watches/action-types` |
 | Webhook action returns `"only http/https allowed"`                      | URLs must use `http://` or `https://` schemes; other protocols are rejected by design *(source: `engine/watch-actions.js` `WEBHOOK` handler)* |
 | Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, the project's `work-items.json` couldn't be written, or the WI landed in central `work-items.json` because no project was specified |
-| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:482`)* |
-| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:5453`)*. Inspect `engine/log.json` for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
+| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:482-484`)* |
+| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:5432`)*. Inspect `engine/log.json` for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
 
 ## See Also
 
 - `engine/shared.js:1875-1960` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
 - `engine/watches.js` — registry, lifecycle, tick integration, `watches.d/` plugin loader
 - `engine/watch-actions.js` — action registry and built-in handlers (including `minions-api`)
+- `watches.d/http.js` — canonical user-extensible target type plugin
 - `dashboard/pages/watches.html`, `dashboard/js/render-watches.js` — dashboard UI
 - `test/unit/watches-module.test.js`, `test/unit/watch-actions.test.js`, `test/unit/watches-plugin-loader.test.js` — module-level tests
 - [`auto-discovery.md`](auto-discovery.md) — overall tick cycle context

package/engine/cli.js

@@ -751,6 +751,45 @@ const commands = {
       }
     })();
 
+    // P-8a4d6f29 — Boot reconcile for managed-spawn: drop dead-PID rows from
+    // engine/managed-processes.json, kill TTL-expired specs, re-probe
+    // survivors once. Wrapped in Promise.race against
+    // ENGINE_DEFAULTS.managedSpawn.bootReconcileMaxMs (2s default) so a
+    // malformed or oversized state file cannot block engine boot. Async +
+    // fire-and-forget — the first tick is allowed to start regardless.
+    (function startupReconcileManagedSpawn() {
+      try {
+        const managedSpawn = require('./managed-spawn');
+        const limits = (require('./shared').ENGINE_DEFAULTS.managedSpawn || {});
+        if (limits.enabled === false) return;
+        const maxMs = Math.max(1, Number(limits.bootReconcileMaxMs) || 2000);
+        let settled = false;
+        const timeoutPromise = new Promise((resolve) => {
+          setTimeout(() => { if (!settled) { settled = true; resolve({ timedOut: true }); } }, maxMs).unref?.();
+        });
+        const reconcilePromise = Promise.resolve()
+          .then(() => managedSpawn.bootReconcileManagedSpawn())
+          .then((r) => { settled = true; return { timedOut: false, result: r }; })
+          .catch((err) => { settled = true; return { timedOut: false, error: err }; });
+        Promise.race([reconcilePromise, timeoutPromise]).then((outcome) => {
+          if (outcome.timedOut) {
+            e.log('warn', `Managed-spawn boot reconcile exceeded ${maxMs}ms; continuing without it`);
+            return;
+          }
+          if (outcome.error) {
+            e.log('warn', `Managed-spawn boot reconcile failed: ${outcome.error.message}`);
+            return;
+          }
+          const s = outcome.result && outcome.result.stats;
+          if (s && s.scanned > 0 && (s.ttlExpired || s.deadDropped || s.rotatedLogs)) {
+            console.log(`  Managed-spawn boot reconcile: scanned=${s.scanned} ttl=${s.ttlExpired} dead=${s.deadDropped} killed=${s.killedPids} rotated=${s.rotatedLogs}`);
+          }
+        });
+      } catch (err) {
+        e.log('warn', `Managed-spawn boot reconcile failed to start: ${err.message}`);
+      }
+    })();
+
     // W-mp73ya3e000me6c5 — Boot reconcile for the worktree pool: drop entries
     // whose path is gone (manual rm), whose borrower crashed before
     // returning, or whose idle TTL expired while the engine was down. The