@yemi33/minions 0.1.2143 → 0.1.2145

package/dashboard.js

@@ -240,6 +240,27 @@ function removePinnedEntryLocked(title) {
   return !missing;
 }
 
+// Edit a pinned note in place: replace the entry keyed on originalTitle with a
+// fresh title/content/level block, atomically (single lock — never a remove+add
+// race that could drop the note if the second write failed). Returns true if the
+// original was found and replaced; false means it was appended as a new entry
+// (upsert) so an edit never silently loses the content.
+function updatePinnedEntryLocked({ originalTitle, title, content, level }, now = new Date()) {
+  const levelTag = level === 'critical' ? '🔴 ' : level === 'warning' ? '🟡 ' : '';
+  const block = '\n\n### ' + levelTag + title + '\n\n' + content + '\n\n*Pinned by human on ' + now.toISOString().slice(0, 10) + '*';
+  let found = false;
+  mutateTextFileLocked(PINNED_PATH, existing => {
+    const base = existing || PINNED_DEFAULT_CONTENT;
+    const regex = new RegExp('\\n\\n###\\s*(?:🔴\\s*|🟡\\s*)?' + originalTitle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\n[\\s\\S]*?(?=\\n\\n###|$)', 'i');
+    if (regex.test(base)) {
+      found = true;
+      return base.replace(regex, block);
+    }
+    return base + block;
+  }, { defaultValue: PINNED_DEFAULT_CONTENT });
+  return found;
+}
+
 function setKbPinsLocked(pins) {
   return mutateJsonFileLocked(KB_PINS_PATH, () => pins, { defaultValue: [], skipWriteIfUnchanged: true });
 }
@@ -9786,7 +9807,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   async function serveSlimUx(req, res) {
     try {
       const { buildSlimHtml } = require('./dashboard-build');
-      const html = buildSlimHtml()
+      // Inject the same feature-flag bootstrap the classic dashboard ships so
+      // Slim UX can gate client behavior (e.g. the slim-ux-promo welcome popup)
+      // off window.MINIONS_FEATURES. Built per request so a flag toggle takes
+      // effect on the next slim load with no restart.
+      const slimFeaturesBoot = (() => {
+        const boot = { flags: {}, defaults: {} };
+        try {
+          for (const f of features.listFeatures(CONFIG)) { boot.flags[f.id] = f.enabled; boot.defaults[f.id] = f.default; }
+        } catch { /* keep empty bootstrap on registry error */ }
+        return boot;
+      })();
+      const html = buildSlimHtml({ featuresJson: JSON.stringify(slimFeaturesBoot) })
         .replace(/\{\{favicon_emoji\}\}/g, FAVICON_EMOJI)
         .replace(/\{\{title_suffix\}\}/g, TITLE_SUFFIX);
       res.statusCode = 200;
@@ -11330,6 +11362,17 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       invalidateStatusCache({ includeSlow: true });
       return jsonReply(res, 200, { ok: true });
     }},
+    { method: 'POST', path: '/api/pinned/update', desc: 'Edit a pinned note (replace the entry keyed on originalTitle)', params: 'originalTitle, title, content, level?', handler: async (req, res) => {
+      const body = await readBody(req);
+      const originalTitle = (body.originalTitle || '').trim();
+      const title = (body.title || '').trim();
+      const { content, level } = body;
+      if (!originalTitle || !title || !content) return jsonReply(res, 400, { error: 'originalTitle, title and content required' });
+      const found = updatePinnedEntryLocked({ originalTitle, title, content, level });
+      // pinned.md is in slow-state cache — opt-in invalidation so the edit is visible immediately
+      invalidateStatusCache({ includeSlow: true });
+      return jsonReply(res, 200, { ok: true, updated: found });
+    }},
 
     // KB pin state (server-side so CC can pin items)
     { method: 'GET', path: '/api/kb-pins', desc: 'Get pinned KB item keys', handler: async (req, res) => {

package/docs/README.md.rej

@@ -0,0 +1,9 @@
+diff a/docs/README.md b/docs/README.md	(rejected hunks)
+@@ -16,6 +16,7 @@ Architecture, design proposals, and lifecycle references for people working on t
+ - [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-spawn completion JSON: trust nonce, `failure_class` enum, `noop` semantics, `retryable` / `needs_rerun` shape, and the artifacts array.
+ - [constellation-bridge.md](constellation-bridge.md) — Read-only cross-repo bridge: `engine.constellationBridge.enabled` flag, marker-file contract, and the `minions bridge` subcommand for local debugging.
++- [constellation-style-telemetry.md](constellation-style-telemetry.md) — Feasibility study for a local-first usage/analytics layer modeled on Constellation's telemetry (typed event log + daily rollup + dashboard view), and why a 1:1 PostgreSQL/multi-tenant port is the wrong goal for Minions.
+ - [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`.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-05-28 against `engine.js` `tickInner()` and `routing.md`.
+> Last verified: 2026-06-06 against `engine.js` `tickInner()` and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -16,7 +16,7 @@ tick()
   1c. meetingTimeouts()          Advance round-based meetings whose timer fired
   2.  consolidateInbox()         Merge learnings into notes.md (Haiku-powered)
   2.1 autoSweepKb()              Periodic KB sweep (opt-in via engine.autoConsolidateMemory, 4h cadence)
-  2.5 runCleanup()               Periodic cleanup (every 10 ticks ≈ 10min)
+  2.5 runCleanup()               Periodic cleanup (every 60 ticks ≈ 10min)
   2.52 sweepKeepProcesses()      keep_processes TTL/dead-PID sweep (every 180 ticks)
   2.53 sweepManagedSpawn()       managed_spawn TTL/dead-PID/log-rotate sweep (every 180 ticks)
   2.55 checkWatches()            Persistent watch jobs (every 18 tick-equivalents)

package/docs/constellation-style-telemetry.md

@@ -0,0 +1,161 @@
+# Constellation-style telemetry for Minions — feasibility study
+
+**Status:** Design proposal (not implemented). **Audience:** Contributors.
+**Question answered:** Constellation (`~/code/constellation`) has a mature telemetry/usage
+stack. Should Minions build something similar, and if so, what shape?
+
+## TL;DR
+
+A **1:1 port is the wrong goal.** Constellation's telemetry is built for a *hosted,
+multi-tenant, server-side fleet*: PostgreSQL storage, WebSocket ingestion,
+per-constellation/per-device tenancy, and a bearer-authed global-admin dashboard.
+Minions is the structural opposite — *single-machine, local-first, zero-deps-beyond-Node,
+JSON-file state, loopback dashboard*.
+
+But the **valuable, portable subset is very feasible**, and Minions already has ~60% of it.
+The realistic target is a **local-first usage/analytics layer**: a typed append-only event
+log + a retention/rollup discipline + a dedicated dashboard "Usage" page, optionally a
+`/metrics` Prometheus endpoint. **No database, no new runtime dependencies, no new network
+egress** (preserves the "nothing leaves the machine" property — Minions' own code has no
+external telemetry today).
+
+## What Constellation does
+
+Database-first, no external SaaS (no Kusto/App Insights/Sentry/Segment/Datadog). Events are
+fire-and-forget INSERTs into PostgreSQL on the WebSocket hot path, spread across ~8 tables:
+
+| Table | Retention | Role |
+|---|---|---|
+| `events` | 7d | Session/device/tool-call/auth lifecycle (`event_type` + JSON `payload`) |
+| `sessions` | 30d | Session state + metadata |
+| `execution_log` | 30d | Mission/agent runs: `status`, `cost_usd`, `duration_ms`, `error_category` |
+| `session_launches` | 30d | Mission-wizard lifecycle + structured error capture (`error_code/category/message/stage`) |
+| `app_events` | 30d | Cross-app analytics (e.g. PRism PR review/resolve) |
+| `device_connection_log` | 90d | Per-day (device, agent_version) fingerprints |
+| `metrics_daily` | **unlimited** | Rolled-up daily aggregates that survive retention |
+
+Key design properties:
+
+- **Rollup-before-delete invariant.** A 6-hourly scheduler (`packages/server/src/utils/retention.ts`
+  `startCleanupScheduler`) runs `runMetricsRollup()` (`packages/server/src/utils/metrics-rollup.ts`)
+  **before** `runDataCleanup()`. If the rollup throws, retention is skipped that tick — live rows
+  are never deleted before they're aggregated. A sentinel watermark row tracks the last fully
+  aggregated UTC date; today is excluded (live queries cover it).
+- **Structured error taxonomy.** `WIZARD_ERROR_CATEGORIES` in `packages/shared/src/constants.ts`
+  (`validation`, `parse_error`, `agent_unavailable`, `agent_error`, `file_write`, `unknown_tool`,
+  `timeout`, `unknown`) drives failure dashboards.
+- **Emit API.** Direct DB writes (`db.execute('INSERT INTO events ...')`) at ~60–70 call sites;
+  a typed `logAuditEvent()` helper (`packages/server/src/utils/audit.ts`) for security events;
+  a frontend `recordPrismEvent()` using `navigator.sendBeacon` →
+  `POST /api/v1/prism/telemetry` (`packages/server/src/api/prism.ts`).
+- **Admin surface.** `GET /api/v1/global-admin/overview?window=24h|3d|7d|30d|90d|all`
+  (`packages/server/src/api/global-admin.ts`) returns windowed totals + daily time-series +
+  top-failing missions + recent wizard failures; queries live tables inside retention and
+  `metrics_daily` beyond it, merging by dimension. Separately, `GET /metrics`
+  (`packages/server/src/api/metrics.ts`) exposes Prometheus counters from an in-memory registry
+  (`terminal-metrics.ts`) — no Prometheus client library.
+- **Privacy.** Path truncation + field redaction (`packages/shared/src/privacy.ts`), configurable
+  retention windows, no sampling.
+- **Dependencies.** Only telemetry-relevant runtime dep is `pg`. No analytics SDKs anywhere.
+
+## What Minions already has (≈60%)
+
+| Constellation concept | Minions equivalent today |
+|---|---|
+| `metrics_daily` rollups | `metrics.json._daily.<YYYY-MM-DD>` → `{costUsd, inputTokens, outputTokens, cacheRead, tasks}` |
+| Per-entity aggregates | Per-agent counters: `tasksCompleted/Errored`, `prsCreated/Approved/Rejected/Merged`, `reviewsDone`, `totalCostUsd`, `totalInputTokens/OutputTokens/CacheRead`, `totalRuntimeMs`, `model`, `timedTasks` |
+| App/engine analytics | `metrics.json._engine`: `command-center`, `agent-dispatch`, `consolidation`, `agent_memory_reconcile` |
+| Emit helpers | `llm.trackEngineUsage()`, `trackReviewMetric()`, `updateMetrics()` (`engine/lifecycle.js`, `engine/llm.js`, `engine/shared.js`) |
+| Structured error taxonomy | `FAILURE_CLASS` constants (recorded per work-item; not yet aggregated as a metric) |
+| Diagnostic stream | `log.json` ring buffer (2500, secret-redacted via `redactSecrets()`) + `engine/dashboard-diagnostics.log` |
+| Admin overview query | `getMetrics()` (`engine/queries.js`) surfaced via `/api/status` |
+
+## The gap (the 40% worth building)
+
+1. **No typed, append-only *event log*.** Minions has aggregate *counters* and a generic
+   *diagnostic* log, but nothing like Constellation's `events`/`execution_log`/`session_launches`:
+   domain events with `event_type` + structured `payload` + timestamp that can be **sliced over
+   time** ("dispatches by type per day", "`failure_class` trend", "plan→PRD failures with full
+   error text"). This is the single biggest capability difference.
+2. **No dedicated usage/analytics *view*.** Dashboard pages are home/work/prs/plans/inbox/tools/
+   schedule/watches/pipelines/meetings + qa/engine. There is no cost trend, failure-category
+   breakdown, or throughput chart. `getMetrics()` data is collected but barely visualized.
+3. **No retention discipline on a structured event stream.** The `_daily` rollup exists, but there
+   is no domain-event log to retain/prune under the rollup-before-delete invariant.
+
+## Portability matrix
+
+| Constellation component | Verdict | Rationale |
+|---|---|---|
+| Typed event taxonomy + error categories | **Port (adapt)** | Reuse existing `WORK_TYPE` / `FAILURE_CLASS`; high value, low cost |
+| Append-only event log | **Port → JSONL** | `engine/events.jsonl` (one event/line, atomic append); matches zero-dep ethos, not a DB table |
+| Daily rollup + **rollup-before-delete** | **Adopt the discipline** | Generalize existing `_daily` to also fold event counts / failure categories; prune JSONL after rollup |
+| Retention windows | **Port (config knob)** | `engine.telemetryRetentionDays`; reuse an existing `cleanup` tick phase |
+| Usage/analytics dashboard page | **Port (scaled down)** | New `dashboard/pages/usage.html` + renderer over `getMetrics()` + rollups; inline SVG, no chart lib |
+| `GET /metrics` Prometheus endpoint | **Optional, easy** | ~40 lines, in-memory text exposition |
+| PostgreSQL backend | **Drop** | Violates "zero deps beyond Node built-ins"; JSON/JSONL suffice at single-machine volume. (See `design-state-storage.md` — if a DB ever lands, `node:sqlite` is the candidate, and this log would migrate with it.) |
+| Multi-tenant constellation/device model | **Drop** | Minions is one fleet on one machine |
+| WebSocket ingestion + `sendBeacon` | **Drop / reuse existing** | Engine already observes agents directly; dashboard already POSTs diagnostics |
+| Bearer-auth global-admin | **Drop** | Local loopback dashboard, no tenancy |
+
+## Recommended shape (phased, local-first)
+
+### Phase 1 — Event log + emit helper (small, ~½ day)
+Add `engine/telemetry.js` exporting `recordEvent(type, payload)` that appends a single redacted
+JSON line to `engine/events.jsonl`. Event types live in a `TELEMETRY_EVENT` constant set (no magic
+strings, per repo convention). Reuse `shared.redactSecrets()`. Wire ~10–15 high-value sites already
+on the tick path: dispatch start/done/fail (+`failure_class`), PR poll outcomes, plan→PRD,
+review verdicts, CC turns. Gitignored runtime file (add to the State Files list in `CLAUDE.md`).
+
+### Phase 2 — Rollup + retention (small, ~½ day)
+Extend the existing daily-rollup path so it also folds event counts + failure-category tallies into
+`metrics.json._daily`. Prune `events.jsonl` lines older than `telemetryRetentionDays` **after** the
+rollup write succeeds (Constellation's invariant). Slots into an existing periodic tick phase.
+All `metrics.json` writes stay inside `mutateJsonFileLocked()`.
+
+### Phase 3 — Usage dashboard page (medium, ~1–1.5 days)
+New sidebar page reading `getMetrics()` + `_daily`: cost/token trend, dispatches-by-type,
+`failure_class` breakdown, per-agent throughput, CC usage. Inline SVG sparklines — **no chart
+dependency**. Follow the fragment-assembly model (`dashboard/pages/usage.html` + a
+`dashboard/js/render-usage.js`) and bump `RENDER_VERSIONS` per the render-cache rules. Add a
+Settings toggle if gated behind a feature flag.
+
+### Phase 4 (optional) — `GET /metrics` (~2 hrs)
+Prometheus text exposition of the same counters for external scrapers. Strict-CSP-exempt route like
+the other HTML entry points; counters from an in-memory registry, no client library.
+
+## Effort & risk
+
+- **Effort:** Phase 1 ~½ day · Phase 2 ~½ day · Phase 3 ~1–1.5 days · Phase 4 ~2 hrs.
+  **Total ≈ 2.5–3 days** for the full local-first system; **Phases 1–2 alone deliver the core
+  capability in ~1 day.**
+- **Risk: low.** No new deps, no schema migrations, no network surface, no new external egress.
+  Watch-items: (a) JSONL append volume — bounded by retention + rollup; (b) `mutateJsonFileLocked`
+  concurrency rules for the rollup write; (c) source-inspection tests for any new dashboard page;
+  (d) CSP/route placement if Phase 4 ships.
+- **Cross-repo:** lands on `yemi33` origin and auto-mirrors to `opg`; nothing here touches
+  enterprise-only files.
+
+## Honest caveats
+
+- Constellation's *real* power is the **central warehouse aggregating many machines** — a SaaS
+  capability Minions structurally cannot replicate without a server + DB + tenancy, which would
+  break its design philosophy. If cross-machine fleet analytics is ever the actual goal, that is a
+  separate, much larger project (a hosted collector), not a port. (`constellation-bridge.md`
+  already defines a read-only cross-repo bridge; a telemetry collector would be a different beast.)
+- Much of Constellation's table sprawl (`sessions`, `devices`, `app_events`) maps to things Minions
+  either doesn't have or already tracks in JSON. **Don't recreate tables 1:1** — port the *event-log
+  + rollup + view* pattern, not the schema.
+
+## References
+
+- Constellation rollup: `packages/server/src/utils/metrics-rollup.ts`,
+  `packages/server/src/utils/retention.ts`
+- Constellation emit/admin: `packages/server/src/utils/audit.ts`,
+  `packages/server/src/api/global-admin.ts`, `packages/server/src/api/metrics.ts`,
+  `packages/server/src/api/prism.ts`, `packages/dashboard/src/prism/prism-telemetry.ts`
+- Constellation taxonomy/privacy: `packages/shared/src/constants.ts`,
+  `packages/shared/src/privacy.ts`
+- Minions today: `engine/metrics.json`, `getMetrics()` (`engine/queries.js`),
+  `trackEngineUsage()` (`engine/llm.js`), `FAILURE_CLASS` (`engine/shared.js`),
+  related design doc `design-state-storage.md`.

package/docs/engine-restart.md

@@ -1,6 +1,6 @@
 # Engine Restart & Agent Survival
 
-> Last verified: 2026-05-16 against `engine.js` (`engineRestartGraceUntil`, line 168) and `engine/shared.js` `ENGINE_DEFAULTS` (`restartGracePeriod: 1200000`, `heartbeatTimeout: 300000`, `agentTimeout: 18000000`).
+> Last verified: 2026-06-06 against `engine.js` (`engineRestartGraceUntil`, line 177) and `engine/shared.js` `ENGINE_DEFAULTS` (`restartGracePeriod: 1200000`, `heartbeatTimeout: 300000`, `agentTimeout: 18000000`).
 
 ## The Problem
 

package/docs/kb-sweep.md

@@ -37,7 +37,7 @@ The remaining survivors are sent to Claude Haiku in batches of `LLM_BATCH_SIZE =
 
 Each action archives the file via the same `_archiveKbFile()` helper used by Pass 1; reclassification rewrites the `category:` frontmatter line and moves the file into the new category directory (source: [`engine/kb-sweep.js:243-279`](../engine/kb-sweep.js#L243)).
 
-Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/shared.js:1012`](../engine/shared.js#L1012)); unknown categories are silently dropped.
+Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/shared.js:2139`](../engine/shared.js#L2139)); unknown categories are silently dropped.
 
 If a batch returns invalid JSON or the runtime is unavailable, that batch is skipped with a warning and the rest of the sweep continues (source: [`engine/kb-sweep.js:139-151`](../engine/kb-sweep.js#L139)).
 
@@ -116,7 +116,7 @@ Memory still wins when present; the disk file is a fallback (source: [`engine/kb
 
 ## Automatic Periodic Sweep (opt-in)
 
-The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js:1835`](../engine/shared.js#L1835)):
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js:2253`](../engine/shared.js#L2253)):
 
 - When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/kb-sweep.js`](../engine/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
 - The inbox→`notes.md` consolidation runs every tick *regardless* of this flag via `consolidateInbox()`; `autoConsolidateMemory` controls **only** the heavier `knowledge/` sweep.

package/docs/managed-spawn.md

@@ -203,7 +203,7 @@ Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale row in `
 
 ## Configuration
 
-All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
+All knobs live under `engine.managedSpawn` in `engine/shared.js:2494` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
 
 | Key | Default | Notes |
 |---|---|---|

package/docs/watches.md

@@ -24,7 +24,7 @@ A watch is a small JSON record persisted to `engine/watches.json`. It binds:
 
 ## Lifecycle (`WATCH_STATUS`)
 
-Defined in `engine/shared.js:2523`:
+Defined in `engine/shared.js:3163` (`WATCH_STATUS`):
 
 | Status      | Meaning                                                                 |
 |-------------|-------------------------------------------------------------------------|
@@ -37,10 +37,10 @@ Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `
 
 ## Conditions (`WATCH_CONDITION`)
 
-Defined in `engine/shared.js:2539-2577`. Conditions split into two families:
+Defined in `engine/shared.js:3179-3220` (`WATCH_CONDITION`). Conditions split into two families:
 
 ### Absolute conditions (`WATCH_ABSOLUTE_CONDITIONS`)
-*(source: `engine/shared.js:2586-2602`)*
+*(source: `engine/shared.js:3226-3245`)*
 
 `merged`, `build-fail`, `build-pass`, `completed`, `failed`, `concluded`, `approved`, `rejected`, `ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`.
 
@@ -49,12 +49,12 @@ When `stopAfter === 0`, these are **fire-once** — the engine flips the watch t
 > **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`, 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:2539-2577` for the canonical enum.
+`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:3179-3220` 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:2582-2583`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
+`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:3222-3223`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
 
 ### Predicate conditions
 
@@ -65,7 +65,7 @@ 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:2586` `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:3226` `WATCH_ABSOLUTE_CONDITIONS`)*.
 
 ## Target Types — `TARGET_TYPES` Registry
 
@@ -89,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-1313`)*. Constants live at `engine/shared.js:2529-2538` (`WATCH_TARGET_TYPE`).
+The eight built-ins are registered at module load *(source: `engine/watches.js:669-1268`)*. Constants live at `engine/shared.js:3169-3177` (`WATCH_TARGET_TYPE`).
 
 | `targetType`  | Target value                         | Conditions                                                                 | Notes |
 |---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
@@ -133,7 +133,7 @@ Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both d
 
 ## Tick Integration
 
-`engine.js` calls `checkWatches(config, state)` every `ENGINE_DEFAULTS.watchPollEvery` ticks (default 18 ⇒ ~3 min at the default 10s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:6386-6440`)*. The engine builds the state object from cached project files + module reads:
+`engine.js` calls `checkWatches(config, state)` every `ENGINE_DEFAULTS.watchPollEvery` ticks (default 18 ⇒ ~3 min at the default 10s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:7439-7470`)*. The engine builds the state object from cached project files + module reads:
 
 ```
 {
@@ -175,7 +175,7 @@ I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up ac
 | `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
 | `cc-triage`            | Invoke Command Center headlessly via the loopback `POST /api/command-center/triage` endpoint with the trigger context (and optional completion-report / live-output artifacts). Wraps the prompt in `<UNTRUSTED-INPUT>`, uses a default 10-min timeout (capped at 1 h), and is isolated from the user CC session |
 
-Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:2608`); handlers in `engine/watch-actions.js`.
+Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js:3248`); handlers in `engine/watch-actions.js`.
 
 ### Templating
 
@@ -242,11 +242,11 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 | 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-484`)* |
-| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:6386`)*. Inspect `engine/log.json` for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
+| `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick *(source: `engine.js:7443`)*. 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:2523-2618` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
+- `engine/shared.js:3163-3275` — `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

package/engine/cli.js

@@ -159,17 +159,20 @@ function handleCommand(cmd, args) {
   if (!cmd) {
     return commands.start();
   } else if (commands[cmd]) {
-    // W-mq07mjzi000s1cc9: Centralized help-flag interception.
+    // W-mq07mjzi000s1cc9 + W-mq0770160001ee50: Help-flag interception.
     //
-    // `minions work --help` was creating ghost work items with title='--help'
+    // `minions work --help` used to create ghost work items with title='--help'
     // because the bare-string `title` was truthy and bypassed the `!title`
-    // usage check. Same class of bug exists in `spawn`/`plan`/`complete` —
-    // every command that takes a positional arg and tests it with `if (!arg)`.
+    // usage check. The fix lives in per-command guards (`_isHelpArg` /
+    // `looksLikeFlagOrHelp`) on `work`/`spawn`/`plan`/`complete`, which print
+    // command-specific `Usage:` output. `pr` and `bridge` handle help inline.
     //
-    // Intercept here so a single guard covers the whole command set. `pr` and
-    // `bridge` already handle `help`/`--help`/`-h` inline (see their own
-    // first-arg branches), so let them route through unchanged.
-    if (cmd !== 'pr' && cmd !== 'bridge' && isHelpToken(args && args[0])) {
+    // For other commands (start/stop/status/etc.), fall back to printing the
+    // global command list — they take no positional args so `--help` is
+    // otherwise harmless. Commands with per-command help handling are excluded
+    // so their `Usage:` text is what the user sees.
+    const COMMANDS_WITH_OWN_HELP = new Set(['pr', 'bridge', 'work', 'spawn', 'plan', 'complete']);
+    if (!COMMANDS_WITH_OWN_HELP.has(cmd) && isHelpToken(args && args[0])) {
       console.log('Commands:');
       for (const line of formatCliCommandHelpLines()) console.log(line);
       return;
@@ -245,6 +248,15 @@ function formatCliCommandHelpLines() {
   return entries.map(([, { summary }], i) => lefts[i].padEnd(padTo) + summary);
 }
 
+// W-mq0770160001ee50 — `minions work --help` used to swallow `--help` as the
+// work-item title and queue a literal junk item titled "--help"; `minions plan
+// --help` dispatched a plan-to-prd agent against the inline text "--help".
+// Every handler that takes a free-form positional arg must call this BEFORE
+// using it as data so users get usage text instead of a state mutation.
+function _isHelpArg(arg) {
+  return arg === '--help' || arg === '-h' || arg === 'help';
+}
+
 // ─── Runtime fleet flags (--cli / --model / --effort) ────────────────────────
 //
 // Shared by `start`, `restart`, and `config set-cli`. Single source of truth
@@ -522,6 +534,39 @@ const commands = {
     try { shared.applyLegacyCcModelMigration(config, { logger: e.log }); }
     catch (err) { e.log('warn', `legacy ccModel migration failed: ${err.message}`); }
 
+    // W-mq5s5ttx000j7ab8-a — One-shot canonical-gate migration. Project the
+    // legacy `_contextOnly` / `_autoObserve` / `_manual` keys onto the
+    // canonical `contextOnly` field on every `projects/<name>/pull-
+    // requests.json` record BEFORE the first tick fires. `isAutoManagedPrRecord`
+    // now reads `contextOnly` only, so any record the migration doesn't reach
+    // before tick #1 would flip its auto-managed verdict. Idempotent.
+    try {
+      const projectsRoot = path.join(shared.MINIONS_DIR, 'projects');
+      shared.migratePrGateFlags(projectsRoot);
+    } catch (err) { e.log('warn', `pr-gate-migration failed: ${err.message}`); }
+
+    // One-time force-on of the CC worker pool. The pool has been the resolved
+    // default for copilot CC since PR #2492, but configs still carrying an
+    // explicit `ccUseWorkerPool: false` (set before the default flipped) stay
+    // opted out forever. Flip those to ON once, persisting the
+    // `engine._ccPoolForcedOnV1` marker so a deliberate later opt-out sticks.
+    // Disk-side re-derives from the on-disk copy so a concurrent dashboard
+    // write isn't clobbered; skipWriteIfUnchanged makes it a no-op once marked.
+    try {
+      const forced = shared.applyCcWorkerPoolForceOnMigration(config);
+      if (forced.changed) {
+        const configPath = path.join(shared.MINIONS_DIR, 'config.json');
+        shared.mutateJsonFileLocked(configPath, (onDisk) => {
+          shared.applyCcWorkerPoolForceOnMigration(onDisk);
+          return onDisk;
+        }, { defaultValue: {}, skipWriteIfUnchanged: true });
+        if (forced.flipped.length) {
+          e.log('info', `Forced CC worker pool ON — flipped explicit opt-out in: ${forced.flipped.join(', ')}`);
+          console.log(`  Forced CC worker pool ON (was explicitly off in: ${forced.flipped.join(', ')}).`);
+        }
+      }
+    } catch (err) { e.log('warn', `cc worker pool force-on migration failed: ${err.message}`); }
+
     // Auto-heal projects missing workSources (cloned-repo / hand-rolled-config
     // footgun): without this block, discoverFromWorkItems / discoverFromPrs
     // bail silently and the engine looks healthy but never dispatches. The
@@ -1355,7 +1400,7 @@ const commands = {
   },
 
   complete(id) {
-    if (!id) {
+    if (!id || _isHelpArg(id)) {
       console.log('Usage: minions complete <dispatch-id>');
       return;
     }
@@ -1398,7 +1443,7 @@ const commands = {
   spawn(agentId, ...promptParts) {
     const e = engine();
     const prompt = promptParts.join(' ');
-    if (!agentId || !prompt) {
+    if (!agentId || _isHelpArg(agentId) || !prompt) {
       console.log('Usage: node .minions/engine.js spawn <agent-id> "<prompt>"');
       return;
     }
@@ -1433,7 +1478,7 @@ const commands = {
 
   work(title, ...rest) {
     const e = engine();
-    if (!title) {
+    if (!title || _isHelpArg(title)) {
       console.log('Usage: node .minions/engine.js work "<title>" [options-json]');
       console.log('Options: {"id":"W-customid","type":"implement","priority":"high","agent":"dallas","description":"...","branch":"feature/...","project":"minions"}');
       console.log('  id  Optional caller-supplied work item ID. Defaults to a cuid-style W-<id>.');
@@ -1523,7 +1568,7 @@ const commands = {
 
   plan(source, projectName) {
     const e = engine();
-    if (!source) {
+    if (!source || _isHelpArg(source)) {
       console.log('Usage: node .minions/engine.js plan <source> [project]');
       console.log('');
       console.log('Source can be:');

package/engine/features.js

@@ -32,6 +32,17 @@ const FEATURES = {
     addedIn: '0.1.1757',
     expires: '2026-11-01',
   },
+  // slim-ux-promo — gates the Slim UX *entry point*, not Slim UX itself. When
+  // off (default) the "Try new Slim UX" button is hidden on the classic
+  // dashboard header AND the first-visit welcome popup is suppressed inside
+  // Slim UX. Slim UX stays reachable via the `slim-ux` flag / Settings; this
+  // only controls whether it's advertised to users.
+  'slim-ux-promo': {
+    description: 'Show the "Try new Slim UX" entry-point button on the classic dashboard and the first-visit welcome popup inside Slim UX. Off by default — Slim UX itself is still reachable via the slim-ux flag.',
+    default: false,
+    addedIn: '0.1.2057',
+    expires: '2026-11-01',
+  },
   // ccUseWorkerPool — sub-tasks B/C/D of W-mp2w003600196c51 (CC perf).
   // Routes Command Center / doc-chat through engine/cc-worker-pool.js
   // (persistent `copilot --acp` per CC tab) instead of spawning a fresh CLI