@yemi33/minions 0.1.2149 → 0.1.2150

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

@@ -15,6 +15,10 @@ const _WI_ENRICHMENT_FIELDS = [
   '_pr', '_prUrl', '_pendingReason', '_skipReason', '_blockedBy',
   '_humanFeedback', '_reopened', '_managedSpawnPartial', '_securityFlag',
   '_artifacts', 'referencesCount', 'acceptanceCriteriaCount',
+  // W-mq5xg5e9000nec0e — slim shape marker so the detail/edit modals know
+  // to hydrate the full description via GET /api/work-items/<id> rather than
+  // pre-filling textareas with the truncated snippet.
+  '_descriptionTruncated',
   // W-mq08kuog001110a6 — _preDispatchEval IS persisted to disk by
   // engine/dispatch.js#_persistInvalidWorkItem, but the slim /api/status
   // overlay may drop it on later passes. Carry it across the overlay so
@@ -302,17 +306,19 @@ function renderWorkItems(items, opts) {
 async function editWorkItem(id, source) {
   const cached = allWorkItems.find(i => i.id === id);
   if (!cached) return;
-  // Hydrate the full record before rendering the form. The /api/status slice
-  // strips `description`, `references`, and `acceptanceCriteria` (replacing
-  // the arrays with referencesCount / acceptanceCriteriaCount integers — see
-  // dashboard.js:1796-1797). Without hydration the textareas would pre-fill
-  // with empty values, and Save would POST description='', references=[],
-  // acceptanceCriteria=[] back to handleWorkItemsUpdate, which treats those
-  // as defined (dashboard.js:5157, :5164-5165) and silently wipes the stored
-  // values: data-loss on every pencil-edit of a pending/failed WI.
+  // Hydrate the full record before rendering the form. The bulk
+  // /api/work-items list endpoint truncates `description` and replaces
+  // `references` / `acceptanceCriteria` arrays with `referencesCount` /
+  // `acceptanceCriteriaCount` integers (W-mphejzmj000718bf / W-mq5xg5e9000nec0e
+  // — see dashboard.js slimWorkItemForList). Without hydration the textareas
+  // would pre-fill with truncated or empty values, and Save would POST those
+  // back to handleWorkItemsUpdate, which treats them as defined
+  // (dashboard.js:5157, :5164-5165) and silently wipes the stored values:
+  // data-loss on every pencil-edit of a pending/failed WI.
   // See PR #2816 review feedback.
   let item = cached;
   const needsHydration = !cached.description ||
+    cached._descriptionTruncated === true ||
     (cached.acceptanceCriteriaCount > 0 && !Array.isArray(cached.acceptanceCriteria)) ||
     (cached.referencesCount > 0 && !Array.isArray(cached.references));
   if (needsHydration) {
@@ -802,12 +808,14 @@ function openWorkItemDetail(id) {
   if (!cached) return;
 
   // Render the modal immediately from the cached (slim) record so the click
-  // feels instant. The /api/status slice is the source of badges, status,
-  // PR link, artifacts, etc. — everything except the heavy free-text fields
-  // (description, full acceptanceCriteria, full references) — see
-  // W-mphejzmj000718bf. We then hydrate the missing fields from
-  // GET /api/work-items/<id> and re-render in place.
+  // feels instant. The bulk /api/work-items list is the source of badges,
+  // status, PR link, artifacts, etc. — everything except the heavy free-text
+  // fields (description hard-capped, full acceptanceCriteria, full references)
+  // — see W-mphejzmj000718bf / W-mq5xg5e9000nec0e. We then hydrate the
+  // missing/truncated fields from GET /api/work-items/<id> and re-render in
+  // place.
   const needsHydration = !cached.description ||
+    cached._descriptionTruncated === true ||
     (cached.acceptanceCriteriaCount > 0 && !Array.isArray(cached.acceptanceCriteria)) ||
     (cached.referencesCount > 0 && !Array.isArray(cached.references));
 

package/dashboard.js

@@ -4948,6 +4948,51 @@ function restartEngine() {
 // GET/HEAD/OPTIONS are treated as read-only/preflight and bypass these checks.
 const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
+// W-mq5xg5e9000nec0e — Slim a work-item record for the polled bulk
+// /api/work-items list endpoint. With ~744 items including done history,
+// the full shape ballooned to 4.2 MB (three plan-to-prd "meeting follow-up"
+// items each embedded a ~169 KB transcript inline in `description`); the
+// dashboard refresh loop re-downloads and re-renders that on every cycle
+// and the browser tab OOM-crashed. Three transforms:
+//
+//   * description — hard-cap to WORK_ITEMS_SLIM_DESCRIPTION_CAP chars (with
+//     a "… [truncated; fetch full record at /api/work-items/<id>]" marker)
+//     so a single oversized transcript can never reproduce a multi-hundred-
+//     KB list payload again. When truncation occurs, `_descriptionTruncated:
+//     true` is set so the detail/edit modal client paths
+//     (dashboard/js/render-work-items.js) know to hydrate via
+//     GET /api/work-items/<id> before rendering or pre-filling the edit form.
+//   * acceptanceCriteria → acceptanceCriteriaCount integer (drop array).
+//   * references         → referencesCount integer (drop array).
+//
+// GET /api/work-items/<id> (handleWorkItemsById) still returns the FULL
+// record — modal hydration depends on it. Frontend consumers are already
+// wired to read referencesCount / acceptanceCriteriaCount integers and to
+// lazy-fetch the full record on click (W-mphejzmj000718bf).
+//
+// Exported (as `_slimWorkItemForList`) for direct unit testing — production
+// callers go through the GET /api/work-items handler's builder closure.
+const WORK_ITEMS_SLIM_DESCRIPTION_CAP = 2048;
+const WORK_ITEMS_SLIM_DESCRIPTION_MARKER = '\n\n… [truncated; fetch full record at /api/work-items/<id>]';
+function slimWorkItemForList(item) {
+  if (!item || typeof item !== 'object') return item;
+  // Shallow copy — never mutate the cached item from queries.getWorkItems().
+  const slim = { ...item };
+  if (typeof slim.description === 'string' && slim.description.length > WORK_ITEMS_SLIM_DESCRIPTION_CAP) {
+    slim.description = slim.description.slice(0, WORK_ITEMS_SLIM_DESCRIPTION_CAP) + WORK_ITEMS_SLIM_DESCRIPTION_MARKER;
+    slim._descriptionTruncated = true;
+  }
+  if (Array.isArray(slim.acceptanceCriteria)) {
+    slim.acceptanceCriteriaCount = slim.acceptanceCriteria.length;
+    delete slim.acceptanceCriteria;
+  }
+  if (Array.isArray(slim.references)) {
+    slim.referencesCount = slim.references.length;
+    delete slim.references;
+  }
+  return slim;
+}
+
 const server = http.createServer(async (req, res) => {
   // ── Security headers (applied to every response) ──────────────────────────
   // Baseline CSP + clickjacking/mime/referrer protections. The dashboard HTML
@@ -5435,10 +5480,11 @@ const server = http.createServer(async (req, res) => {
   }
 
   // GET /api/work-items/<id> — return a single FULL work-item record by id
-  // (W-mphejzmj000718bf). The /api/status workItems slice ships a slimmed
-  // shape that omits description, full acceptanceCriteria, and full references
-  // to keep the SPA payload <500KB. The work-item detail modal calls this
-  // endpoint on click to fetch the full record on demand.
+  // (W-mphejzmj000718bf). The polled GET /api/work-items list endpoint ships
+  // the slim shape above (description truncated, acceptanceCriteria/references
+  // replaced with count integers) to keep the SPA payload < ~300 KB; the
+  // work-item detail/edit modals call THIS endpoint on demand for the full
+  // record. Always returns the unslimmed record.
   async function handleWorkItemsById(req, res, match) {
     try {
       const id = decodeURIComponent(match[1] || '').trim();
@@ -11070,7 +11116,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         builder: () => getAgents(),
       });
     }},
-    { method: 'GET', path: '/api/work-items', desc: 'Fully-enriched work items (per-project files joined + dispatch/PR cross-reference) — fresh on every request', handler: (req, res) => {
+    { method: 'GET', path: '/api/work-items', desc: 'Fully-enriched work items (per-project files joined + dispatch/PR cross-reference) — fresh on every request; description hard-capped + acceptanceCriteria/references replaced with *Count integers (W-mq5xg5e9000nec0e); detail modal lazy-loads the full record via GET /api/work-items/<id>', handler: (req, res) => {
       const config = queries.getConfig();
       const projects = config.projects || [];
       const inputs = [
@@ -11086,7 +11132,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return serveFreshJson(req, res, {
         tag: 'work-items',
         inputs,
-        builder: () => getWorkItems(),
+        // W-mq5xg5e9000nec0e — Slim every item before stringify so the polled
+        // refresh-loop payload stays < ~300 KB even when description fields
+        // include 100+ KB transcripts. slimWorkItemForList shallow-copies so
+        // queries.getWorkItems()'s in-memory cache is never mutated.
+        builder: () => getWorkItems().map(slimWorkItemForList),
       });
     }},
     { method: 'GET', path: '/api/pull-requests', desc: 'Fully-enriched pull requests (per-project files joined + url backfill + _project stamp)', handler: (req, res) => {
@@ -11350,10 +11400,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // GET /api/work-items/<id> — fetch a single FULL work-item record by id.
     // Registered AFTER all static /api/work-items/* routes so the regex never
     // shadows them (route matching is sequential, first match wins).
-    // W-mphejzmj000718bf: the /api/status workItems slice drops description /
-    // acceptanceCriteria-detail / references-detail to cut payload size; the
-    // detail modal calls this endpoint on click to fetch the full record.
-    { method: 'GET', path: /^\/api\/work-items\/([^/?]+)$/, template: '/api/work-items/<id>', desc: 'Fetch a single full work-item record by id (description, acceptanceCriteria, references). The /api/status workItems slice ships a slimmed shape; this endpoint backs the detail modal.', handler: handleWorkItemsById },
+    // W-mphejzmj000718bf / W-mq5xg5e9000nec0e: the bulk GET /api/work-items
+    // list endpoint ships a slimmed shape (description hard-capped to
+    // WORK_ITEMS_SLIM_DESCRIPTION_CAP chars, acceptanceCriteria/references
+    // arrays replaced with *Count integers) to cut payload size; the detail
+    // and edit modals call this endpoint to fetch the full record on demand.
+    { method: 'GET', path: /^\/api\/work-items\/([^/?]+)$/, template: '/api/work-items/<id>', desc: 'Fetch a single full work-item record by id (description, acceptanceCriteria, references). The bulk /api/work-items list ships a slimmed shape (description truncated + *Count integers); this endpoint backs the detail and edit modals.', handler: handleWorkItemsById },
 
     // Pinned notes
     { method: 'GET', path: '/api/pinned', desc: 'Get pinned notes', handler: async (req, res) => {
@@ -12337,6 +12389,11 @@ module.exports = {
   // staleness verdict it stamps on engine.heartbeatStale is the contract under
   // test. No production caller imports this; it is a test seam.
   _buildStatusFastState,
+  // W-mq5xg5e9000nec0e — exported for direct unit testing of the slim shape
+  // produced by GET /api/work-items. Production callers go through the
+  // route's `builder` closure (getWorkItems().map(slimWorkItemForList)).
+  _slimWorkItemForList: slimWorkItemForList,
+  _WORK_ITEMS_SLIM_DESCRIPTION_CAP: WORK_ITEMS_SLIM_DESCRIPTION_CAP,
 };
 
 // Start the HTTP server only when run directly (node dashboard.js).

package/docs/README.md

@@ -17,7 +17,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [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.
 - [constants.md](constants.md) — Cross-cutting status / type / condition constants (`WI_STATUS`, `WORK_TYPE`, `PR_STATUS`, `WATCH_CONDITION`, …) and the no-magic-strings invariant.
 - [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.
+- [constellation-style-telemetry.md](constellation-style-telemetry.md) — Feasibility study (design proposal, not implemented) for a local-first usage/analytics layer modelled on Constellation's telemetry stack — typed append-only event log + retention/rollup discipline + dashboard Usage page. Explains why a 1:1 PostgreSQL/multi-tenant port is the wrong goal for Minions.
 - [cooldown-merge-semantics.md](cooldown-merge-semantics.md) — Scoping deliverable defining merge semantics for `saveCooldowns` (longer-of TTL merge, key-level upserts, gitignored on-disk format).
 - [copilot-cli-schema.md](copilot-cli-schema.md) — Behavior and schema reference for the GitHub Copilot CLI adapter (capability flags, stdin vs `-p`, model discovery, effort levels).
 - [dead-code-audit-retractions.md](dead-code-audit-retractions.md) — Retracted dead-code-audit findings (false positives) that future audits MUST read before re-citing.

package/docs/auto-discovery.md

@@ -1,6 +1,6 @@
 # Auto-Discovery & Execution Pipeline
 
-> Last verified: 2026-06-06 against `engine.js` `tickInner()` and `routing.md`.
+> Last verified: 2026-06-09 against `engine.js` `tickInner()` and `routing.md`.
 
 How the minions engine finds work and dispatches agents automatically.
 
@@ -19,6 +19,7 @@ tick()
   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.54 pruneWorktreesPeriodic()  Periodic worktree GC: in-root + out-of-root git registry sweep (every worktreePruneIntervalTicks ≈ 30 ticks; catches Windows EPERM/EBUSY stragglers and `git worktree list` entries outside worktreeRoot)
   2.55 checkWatches()            Persistent watch jobs (every 18 tick-equivalents)
   2.6 pollPrStatus()             Poll ADO + GitHub for build, review, merge status (wall-clock cadence from prPollStatusEvery × tickInterval, default ≈ 12min)
        processPendingRebases()   Run any rebase work queued from the previous tick

package/docs/branch-derivation.md

@@ -0,0 +1,68 @@
+# Branch Derivation
+
+How the engine decides which branch a dispatch is going to push to.
+CLAUDE.md → Branch Naming holds the one-line summary; the structured
+vs. loose-extractor rules and the canonical PR-fix incident live here.
+
+> Source of truth: `engine/shared.js`
+> (`deriveWorkItemBranchName`, `extractStructuredWorkItemPrRef`,
+> `extractWorkItemPrRef`, `copyWorkItemPrFields`),
+> `engine.js#getWorkItemPrRef` + `getStructuredWorkItemPrRef`,
+> `dashboard.js POST /api/work-items`. Last verified: 2026-06-09.
+
+## Engine-side fallback
+
+`shared.deriveWorkItemBranchName(item, config)` is the single helper used
+by every engine.js fallback site and `dashboard.js POST /api/work-items`.
+It returns `work/<wi-id>` (sanitized). Agents authoring branches by hand
+follow the long-form `user/<loginname>/<wi-id>-<slug>` convention
+taught in `playbooks/shared-rules.md`. The engine fallback is
+intentionally short because the engine has no operator login context.
+
+Three rule overrides that skip the fallback:
+
+| Condition | Branch used |
+|-----------|-------------|
+| `item.branch` is set | Use as-is |
+| Item targets an existing PR (see below) | Reuse the PR's source branch |
+| Item is part of a shared-branch plan | Use `feature_branch` from the PRD |
+
+## PR-fix exception (issue #2999 / W-mpx6i5kh000ac040)
+
+`shared.extractWorkItemPrRef(item)` is the single source of truth for
+"does this WI target an existing PR?" — used by `dashboard.js#getWorkItemPrRef`
+and `engine.js#getWorkItemPrRef`. It walks, in order:
+
+1. Structured fields: `targetPr`, `pr_id`, `prUrl`, `prNumber`,
+   `pullRequest`, `sourcePr`, `pr`, `prId`.
+2. `references[*].url`.
+3. `meta.pr_followup.parent_pr_url`.
+4. **(loose only)** Regex-scans description and title for PR URLs or
+   canonical `github:owner/repo#N` / `ado:org/proj/repo#N` ids.
+
+When a ref is detected, `copyWorkItemPrFields` stamps
+`targetPr` / `pr_id` / `prNumber`, `item.branch` is unset, and
+`discoverFromWorkItems` reuses the PR's source branch.
+
+## Structured-vs-loose split (W-mq18ec6h000p7b87)
+
+The PR-ref extractor has **two** variants — pick the right one for the
+call site:
+
+| Helper | What it walks | Used by | Why |
+|--------|---------------|---------|-----|
+| `shared.extractStructuredWorkItemPrRef(item)` | Structured fields + `references[*].url` + `meta.pr_followup.parent_pr_url`. **No** description / title scan. | `engine.js#getStructuredWorkItemPrRef` → `pr_not_found` dispatch gate. | Gating blocks dispatch and MUST require explicit operator intent. A description like "see PR #3015 for context" must NOT trip the gate. |
+| `shared.extractWorkItemPrRef(item)` | Structured walk + last-resort description / title scan. | `engine.js#getWorkItemPrRef` (branch derivation, prompt PR context, `resolveWorkItemPrRecord`); `dashboard.js#getWorkItemPrRef` (POST `/api/work-items` create-time `targetPr` stamping). | Callers downgrade gracefully when no PR record matches; stamp path preserves the operator UX of pasting a PR URL into description prose and getting `targetPr` auto-stamped. |
+
+**Rule of thumb: gate uses structured-only; stamp uses loose.**
+Stamping is best-effort and reversible; gating blocks dispatch and should
+require explicit operator intent.
+
+## Canonical bad incident — P-c8a1d2e3 (2026-06-05)
+
+A refactor WI with no structured PR fields whose description merely
+mentioned PR #3015 / PR #3012 as cross-references got stuck in
+`_pendingReason: 'pr_not_found'` forever because the gate called the
+loose extractor. Fix: split the helpers so the gate calls
+`extractStructuredWorkItemPrRef` and the stamp path calls
+`extractWorkItemPrRef`.

package/docs/cooldown-merge-semantics.md

@@ -16,7 +16,7 @@ the window.
 
 `mutateCooldowns` already runs through `mutateJsonFileLocked`, which acquires
 an exclusive `withFileLock` for the read-modify-write
-(source: `engine/shared.js:1187-1192` and `:1123-1148`), so the callback
+(source: `engine/shared.js` `mutateCooldowns` ~L1625 and `mutateJsonFileLocked` ~L1542), so the callback
 receives the freshly-read `diskCooldowns` snapshot — but the current code
 throws that snapshot away.
 
@@ -113,8 +113,8 @@ acceptance from P-bfa3b verbatim.
 
 - `engine/cooldown.js:63-101` — current lost-update site
 - `engine/cooldown.js:38-60` — `loadCooldowns` + `_lastDiskCooldownKeys` baseline
-- `engine/shared.js:1187-1192` — `mutateCooldowns` (already lock-protected)
-- `engine/shared.js:1123-1148` — `mutateJsonFileLocked` (reads disk inside the
-  lock; `skipWriteIfUnchanged` enabled for cooldowns)
+- `engine/shared.js` `mutateCooldowns` (~L1625) — already lock-protected
+- `engine/shared.js` `mutateJsonFileLocked` (~L1542) — reads disk inside the
+  lock; `skipWriteIfUnchanged` enabled for cooldowns
 - `prd/bug-fix-plan-from-weekly-audit-2026-05-27.json` — P-bfa3a (this scoping)
   and P-bfa3b (implementation acceptance criteria)

package/docs/design-state-storage.md

@@ -30,11 +30,11 @@ Minions persists all runtime state as flat JSON files guarded by file-lock-based
 
 **Total live state:** ~1.8 MB across 9+ JSON files.
 
-(source: `engine/shared.js:233-252` for locking, `engine/queries.js:57-61` for paths, live file sizes from `ls -la engine/*.json`)
+(source: `engine/shared.js` `mutateJsonFileLocked` (~L1542) for locking, `engine/queries.js` for paths, live file sizes from `ls -la engine/*.json`)
 
 ### 1.2 Concurrency Model
 
-All mutations go through `mutateJsonFileLocked()` (source: `engine/shared.js:233-252`):
+All mutations go through `mutateJsonFileLocked()` (source: `engine/shared.js` ~L1542):
 
 ```
 acquire .lock file (exclusive create via fs.openSync 'wx')
@@ -46,10 +46,10 @@ release .lock file
 ```
 
 Key properties:
-- **Synchronous blocking** — `withFileLock` spins with `sleepMs(25)` until lock acquired or 5s timeout (source: `engine/shared.js:175-231`)
+- **Synchronous blocking** — `withFileLock` spins with `sleepMs(25)` until lock acquired or 5s timeout (source: `engine/shared.js` `withFileLock` ~L1329)
 - **Whole-file granularity** — updating one field in one work item rewrites all 180 items (370 KB)
 - **Stale lock recovery** — locks older than 5 min (`LOCK_STALE_MS = 300_000`) are force-removed; holders that recorded a `{pid, ts}` payload are kept alive past the threshold while `process.kill(pid, 0)` succeeds, with a hard last-resort cap at 5×LOCK_STALE_MS (source: `engine/shared.js`, P-b7d4e8f2)
-- **Read caching** — only `dispatch.json` has a 2s TTL cache (source: `engine/queries.js:82-91`)
+- **Read caching** — only `dispatch.json` has a 2s TTL cache (source: `engine/queries.js`)
 
 ### 1.3 Read vs Write Ratio
 
@@ -232,7 +232,7 @@ Stay with files. Fix the two highest-pain issues immediately:
 
 3. **Add read caches to `work-items.json` and `pull-requests.json`** — Same 2s TTL pattern as dispatch.json (source: `engine/queries.js:82-91`). These are read 8+ times per tick but only written 1-2 times.
 
-4. **Convert `log.json` to append-only JSONL** — Eliminates the parse-entire-file-to-append pattern in `_flushLogBuffer()` (source: `engine/shared.js:49-59`). Log rotation becomes `readFile → keep last 2000 lines → writeFile` instead of `parse JSON array → splice → stringify → write`.
+4. **Convert `log.json` to append-only JSONL** — Eliminates the parse-entire-file-to-append pattern in `_flushLogBuffer()` (source: `engine/shared.js` `_flushLogBuffer` ~L499). Log rotation becomes `readFile → keep last 2000 lines → writeFile` instead of `parse JSON array → splice → stringify → write`.
 
 ### Phase 2: `node:sqlite` Migration (When API stabilizes — estimated Node 26 LTS)
 

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:2139`](../engine/shared.js#L2139)); unknown categories are silently dropped.
+Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/shared.js`](../engine/shared.js) `KB_CATEGORIES`); 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:2253`](../engine/shared.js#L2253)):
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `false` — source: [`engine/shared.js`](../engine/shared.js) `ENGINE_DEFAULTS.autoConsolidateMemory`):
 
 - 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:2494` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
+All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
 
 | Key | Default | Notes |
 |---|---|---|

package/docs/timeouts-and-liveness.md

@@ -0,0 +1,120 @@
+# Timeouts & Liveness
+
+What kills (or doesn't kill) a live agent. CLAUDE.md → Timeouts & Liveness
+keeps the core invariant; the spawn-phase watchdog, steering safety nets,
+and stale-orphan detection details live here.
+
+> Source of truth: `engine/timeout.js`, `engine/spawn-phase-watchdog.js`,
+> `engine/shared.js` (`ENGINE_DEFAULTS`, `getProcessCpuSeconds`,
+> `killImmediate`), `engine/steering-store.js`. See also:
+> [engine-restart.md](engine-restart.md). Last verified: 2026-06-09.
+
+## Core invariant
+
+**A live tracked agent is never killed for being silent.** Long builds,
+installs, multi-file edits routinely produce no stdout for many minutes.
+
+Only two things kill a live tracked process (`engine/timeout.js`):
+
+1. **Hard wall-clock timeout** `engine.agentTimeout` (default 5h from
+   `startedAt`; per-fan-out `meta.deadline`).
+2. **Steering kill** — explicit human steering → `killImmediate()` so the
+   agent re-spawns with `--resume <session>`.
+
+**Don't add output-silence timers for live tracked processes.**
+
+## Stale-orphan detection
+
+`engine.heartbeatTimeout` (default 5 min) is the **grace window after the
+engine loses the tracked process handle** — not a heartbeat timer.
+
+Per-type overrides in `ENGINE_DEFAULTS.heartbeatTimeouts`:
+`implement` / `implement:large` / `fix` / `test` / `verify` → 15 min;
+`plan` → 10 min.
+
+Orphan declaration requires four checks (all must pass):
+
+1. `isTrackedProcessAlive` returns false.
+2. 64 KB tail scan for `[process-exit] code=N`.
+3. `isOsPidAliveForDispatch` returns false.
+4. Full-log re-scan still shows no completion.
+
+After engine restart, gated on `engineRestartGraceUntil` (default
+20 min) — see [engine-restart.md](engine-restart.md).
+
+## Steering safety nets (W-mq066js7000fff1f-c)
+
+Three knobs backstop the steering pipeline. `engine/timeout.js`
+defensively requires `./steering-store` and swallows `MODULE_NOT_FOUND`
+only, so the gates work even before the store has shipped.
+
+### Kill-retry escalation ladder
+
+`engine.steeringMaxKillRetries` (default `3`, range `1–5`). After a
+steering kill, if the process hasn't exited within 30 s:
+
+1. Retry gracefully at 60 s, 120 s (last interval reused past the cap).
+2. Fire a platform hard kill:
+   - **Windows:** `taskkill /F /T /PID <pid>`.
+   - **Unix:** descendant-tree SIGKILL — `pgrep -P` deepest-first +
+     `pkill -KILL -P <pid>`.
+3. After the cap: `[steering-stuck]` on `live-output.log` +
+   `[engine-system]` inbox notice; `_steeringGaveUp = true`.
+
+### Deferred-steering safety net
+
+`engine.steeringDeferredMaxMs` (default `900000` = 15 min, range
+`60_000–14_400_000`). Per-tick, any deferred message older than this
+without a `sessionId` is **stranded** — `[steering-warn]` +
+`_steeringStranded: true` via `mutateDispatch`; steering store →
+`status='stranded'`. Re-warn is guarded by
+`_deferredSteeringStrandedFiles`.
+
+### Stale-session purge
+
+`onAgentClose` clears `session.json` on `No conversation found`.
+`dropSteeringForPurgedSession(agentId, sessionId, liveOutputPath)` runs
+BEFORE the unlink, walks `steeringStore.listForAgent(agentId)` dropping
+`{queued, live_kill, deferred, re_spawning}` whose `_steeringSessionId`
+matches (status `dropped`, last_error `session-purged`) + writes:
+
+```
+[steering-failed] Session <id> was purged by runtime; message <id>
+dropped, please re-send.
+```
+
+## Spawn-phase watchdog (W-mq0e2dae000a003d)
+
+`engine/spawn-phase-watchdog.js#checkSpawnPhaseStalls` runs every tick
+alongside `checkTimeouts` / `checkSteering` and kills children wedged
+in MCP-init. Four gates, **ALL** required:
+
+1. Fresh spawn (skips `procInfo.reattached`).
+2. Elapsed since `procInfo.startedAt` ≥ `engine.spawnPhaseGraceMs`
+   (default 120000 ms).
+3. The last 16 KB of `live-output.log` contains zero non-startup events:
+   - Copilot startup-only set:
+     `session.{mcp_server_status_changed, mcp_servers_loaded, skills_loaded, tools_updated, info}`.
+   - Claude startup-only set:
+     `{type:'system', subtype:'init'|'hook_started'|'hook_response'}`.
+   - Non-JSON lines and any other JSON `type` count as real activity.
+4. Per-process CPU seconds (via `shared.getProcessCpuSeconds(pid)` —
+   PowerShell on Windows, `/proc/<pid>/stat` on Linux, `ps -o cputime=`
+   on macOS) ≤ `engine.spawnPhaseMaxCpuSeconds` (default 5).
+
+On fire:
+
+- Kill via `shared.killImmediate`.
+- Write a structured `spawn-phase-stall-<id>` inbox note with the
+  live-output tail.
+- Complete the dispatch with
+  `failureClass: SPAWN_PHASE_STALL` + `agentRetryable: true` so the next
+  tick re-spawns the agent with a fresh runtime invocation.
+
+`SPAWN_PHASE_STALL` is also in `FORCE_DEMOTE_FAILURE_CLASSES` as
+defense-in-depth — a stray completion report can't paper over a wedge.
+
+**CPU sampling fails open:** a null result skips the kill so OS-level
+glitches don't masquerade as wedges.
+
+Toggle off via `engine.spawnPhaseWatchdogEnabled: false`.

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:3163` (`WATCH_STATUS`):
+Defined in `engine/shared.js` (`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:3179-3220` (`WATCH_CONDITION`). Conditions split into two families:
+Defined in `engine/shared.js` (`WATCH_CONDITION`). Conditions split into two families:
 
 ### Absolute conditions (`WATCH_ABSOLUTE_CONDITIONS`)
-*(source: `engine/shared.js:3226-3245`)*
+*(source: `engine/shared.js` `WATCH_ABSOLUTE_CONDITIONS`)*
 
 `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:3179-3220` 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` `WATCH_CONDITION` 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:3222-3223`). 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`). 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:3226` `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` `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:669-1268`)*. Constants live at `engine/shared.js:3169-3177` (`WATCH_TARGET_TYPE`).
+The eight built-ins are registered at module load *(source: `engine/watches.js` — the long `registerTargetType(...)` block)*. Constants live in `WATCH_TARGET_TYPE` in `engine/shared.js`.
 
 | `targetType`  | Target value                         | Conditions                                                                 | Notes |
 |---------------|--------------------------------------|----------------------------------------------------------------------------|-------|
@@ -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:3248`); handlers in `engine/watch-actions.js`.
+Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js`); handlers in `engine/watch-actions.js`.
 
 ### Templating
 
@@ -246,7 +246,7 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 
 ## See Also
 
-- `engine/shared.js:3163-3275` — `WATCH_STATUS`, `WATCH_TARGET_TYPE`, `WATCH_CONDITION`, `WATCH_ABSOLUTE_CONDITIONS`, `WATCH_ACTION_TYPE` constants
+- `engine/shared.js` — `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/docs/worktree-lifecycle.md

@@ -0,0 +1,164 @@
+# Worktree Lifecycle
+
+Deep-dive for the four engine pieces that own git-worktree state for dispatch:
+the **pool** (recycling), the **live guard** (don't wipe an agent's work),
+the **quarantine path** (dirty/divergent → quarantine dir + retry), and the
+**Windows file-lock retry** (EPERM/EBUSY footgun). CLAUDE.md → Worktree
+Lifecycle keeps the cross-cutting invariants; the detail lives here.
+
+> Source of truth: `engine/worktree-pool.js`, `engine/shared.js#removeWorktree`
+> + `_retryFsOp`, `engine.js` (`_quarantineDirtyWorktree`, `_renameWithRetry`,
+> `_killGitDescendantsForWorktree`, `pruneOrphanWorktrees*`, `gcDispatchWorktreeIfOrphan`),
+> `engine/cleanup.js`. Last verified: 2026-06-09.
+
+## Live-worktree guard (W-mq5rwwss000f30a7)
+
+**Invariant:** every code path that wipes, renames, or recycles a worktree
+MUST call `shared.isWorktreePathLive(path, { db?, excludeDispatchId? })`
+first and skip on `true`. Originally added after W-mq5n1zx5000hcfb5 — an
+agent's worktree was wiped 4× consecutively by the reaper while the
+dispatch was still active.
+
+- **Backed by SQL** against `dispatches` (status IN ('pending','active')),
+  reading `json_extract(data, '$.worktreePath')` with a `data.meta.worktreePath`
+  fallback. The pending → active transition persists `item.worktreePath`
+  on the dispatch row so the guard has a path to correlate.
+- **Fails OPEN** (returns `true`) when SQLite is unreachable or the query
+  throws — better to leak a worktree than nuke an agent's unpushed work.
+- **Wired sites:** `shared.removeWorktree` (accepts `{ excludeDispatchId }`
+  forwarded to the guard); pool-return chain in `engine.js`
+  (`excludeDispatchId: id` so the dispatch can clean up its own worktree);
+  dispatch-end orphan GC (`gcDispatchWorktreeIfOrphan`); `_quarantineDirtyWorktree`
+  (returns `{ skipped: true, quarantinedPath: null }` on skip — callers
+  MUST honor `skipped` and not set `quarantined: true`); `engine/cleanup.js`
+  orphan-dir sweep.
+- **On skip:** drops a deduped operator note at
+  `notes/inbox/engine-worktree-skip-live-<basename>-<date>.md`.
+
+## Worktree pool (opt-in)
+
+`ENGINE_DEFAULTS.worktreePoolSize > 0` enables `engine/worktree-pool.js` to
+recycle worktree dirs across branches.
+
+- **Borrow** in `spawnAgent` only when (a) the new branch doesn't exist on
+  origin AND (b) the dispatch is not shared-branch / `useExistingBranch`.
+- **Return** in `onAgentClose` BEFORE `completeDispatch`:
+  `git reset --hard HEAD` → `git clean -fd` → `git fetch origin <main>`
+  → `git checkout --detach origin/<main>` → mark IDLE.
+- **State** at `engine/worktree-pool.json`; git ops outside any lock.
+
+## Quarantine path (dirty / divergent)
+
+When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,
+`WORKTREE_DIVERGENT`, or post-stuck state, `_quarantineDirtyWorktree`
+moves it to `<root>/.quarantined/<basename>-<utc>` and lets the next tick
+recreate a clean worktree. Six layered defenses cover the Windows EBUSY
+race when git status descendants still hold packfile handles
+(W-mq5n1zx5000hcfb5; PR #3156).
+
+### Layer 1b — `--no-optional-locks` on every status probe (load-bearing)
+
+`_statusPorcelainCmd()` emits `git --no-optional-locks status …`. Skips
+the `.git/index.lock` acquire around the untracked-cache refresh inside
+`status`. Typical probe duration under AV scanning drops from 6–12s to
+<500ms, which removes the timeout that leaks the child in the first
+place. **Most incidents are closed by 1b alone.**
+Toggle: `ENGINE_DEFAULTS.statusProbeUseNoOptionalLocks` (default `true`).
+
+### Layer 1a — `_renameWithRetry` with jittered backoff
+
+6 attempts × 250 ms base × 2^N exponential + 200 ms random jitter
+(~16 s worst-case). Only retries on `EBUSY|EPERM|EACCES|ENOTEMPTY`;
+rethrows other codes immediately. Toggles:
+`ENGINE_DEFAULTS.quarantineRenameRetryAttempts` (6),
+`quarantineRenameRetryBaseMs` (250).
+
+### Layer 2a — `_killGitDescendantsForWorktree` (Windows-only)
+
+PowerShell sweep, 2 s timeout. Shell-out built via single-quoted literal
+(`'` escaped as `''`) so worktree-path interpolation is injection-safe.
+POSIX no-op. Best-effort — failure logged, never throws.
+Toggle: `ENGINE_DEFAULTS.statusProbeKillDescendantsWin32` (default `true`).
+
+### Layer 2b — `git worktree remove --force` fallback
+
+Triggers only when 1a exhausts retries; destroys worktree contents (no
+quarantine dir preserved). Toggle:
+`ENGINE_DEFAULTS.quarantineForceRemoveFallback` (default `true`).
+
+### Layer 1c — `FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED`
+
+Routed when `cleanResult.quarantineError && !cleanResult.quarantined`.
+Added to `dispatch.js#isRetryableFailureReason` never-retry set so the
+per-agent retry counter doesn't bump (env failure, not the agent's fault).
+The auto-recovery loop in `engine.js#discoverFromWorkItems` recognizes
+the new class via both enum check and regex on legacy `failReason`
+strings, then re-queues under the existing
+`ENGINE_DEFAULTS.quarantineAutoRecoveryMax` (default 2) cap.
+
+### Layer 3a/3b — metrics + inbox alert
+
+Counters at
+`metrics._engine.worktreeQuarantineOutcomes.{attempts, success, successAfterRetry, fallbackForceRemove, totalFailure}`.
+Total-failure path writes a structured inbox alert with the exact
+PowerShell/POSIX recovery commands and `git worktree prune` instructions.
+
+### Auto-recovery cap
+
+`discoverFromWorkItems` auto-recovers `WORKTREE_DIRTY`/`WORKTREE_DIVERGENT`
+quarantine (#2996) up to `ENGINE_DEFAULTS.quarantineAutoRecoveryMax`
+(default 2, tracked on `_quarantineRecoveryCount`); after the cap,
+`_quarantineRecoveryGaveUp` triggers a warn-once.
+
+## Windows file-lock on removal (footgun #6 detail)
+
+`fs.rmSync` against an active git worktree can lose to lingering file
+handles (CC log streams, virus scanners, Explorer previews).
+`shared.removeWorktree` retries via `shared._retryFsOp`
+(`worktreeRemoveRetryAttempts` × exponential `worktreeRemoveRetryBaseMs`,
+codes `EPERM|EBUSY|EACCES|ENOTEMPTY`).
+
+After `worktreeStuckThreshold` consecutive failures the path is
+**escalated**:
+
+- A `notes/inbox/engine-worktree-stuck-<basename>-<date>.md` note with
+  Windows holder-identification hints is written (deduped per UTC day).
+- Per-tick warns are suppressed for `worktreeStuckSuppressMs`.
+- The retry cadence drops to `worktreeStuckSlowRetryMs`.
+- When the holder finally releases, a
+  `worktree-recovered-<basename>` note clears the alert.
+
+**Don't fight this with `fs.rmSync({force:true})` outside
+`removeWorktree`** — you'll bypass the retry, escalation, and metrics
+layers.
+
+## Periodic prune (W-mq5o6bvy000x7191)
+
+`pruneWorktreesPeriodic` runs `pruneOrphanWorktrees` (in-root) +
+`pruneOrphanWorktreesFromGitRegistry` (out-of-root via
+`git worktree list --porcelain`) per project at
+`ENGINE_DEFAULTS.worktreePruneIntervalTicks` cadence — catches Windows
+EPERM/EBUSY stragglers that the dispatch-end GC couldn't reap and sweeps
+the `git worktree list` registry for OUT-of-root entries the in-root
+scanner is blind to.
+
+## Holder identification + opt-in auto-reap (W-mq6f2fe0000557fa)
+
+Orphan-sweep escalations also run `shared.findProcessesWithCwdInside(wt)`
+(cross-platform: PowerShell `Get-CimInstance Win32_Process` on Windows;
+`/proc/*/cwd` walk on Linux; `lsof -d cwd` + `ps` on macOS) and append a
+`## Live holders` section listing pid / cmdline / age to the
+`engine-worktree-stuck-<basename>` escalation note.
+
+Setting `engine.autoReapOrphanWorktreeHolders: true`
+(Settings → Worker Pool & Worktrees → "Auto-reap orphan worktree holders")
+additionally kills any holder whose `cmdline` matches `spawn-agent.js`
+AND references the worktree basename AND whose age exceeds
+`engine.agentTimeout * 2`, then retries `removeWorktree` once. Default
+**OFF** — killing a foreign process is destructive.
+
+- Scan timeout: `engine.orphanHolderScanTimeoutMs` (default 5000ms,
+  clamped 1000–30000).
+- Motivating incident: W-mq1k8z6o003acd89 / stuck `spawn-agent.js`
+  PID 16828 that the periodic prune couldn't shake loose without manual
+  intervention.

package/engine/cli.js

@@ -163,8 +163,9 @@ function handleCommand(cmd, args) {
     //
     // `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

package/package.json

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