npm - @yemi33/minions - Versions diffs - 0.1.2149 → 0.1.2151 - Mend

@yemi33/minions 0.1.2149 → 0.1.2151

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/bin/minions.js +99 -6
package/dashboard/docs/typography-audit.md +128 -0
package/dashboard/docs/typography.md +114 -0
package/dashboard/js/render-agents.js +1 -1
package/dashboard/js/render-work-items.js +21 -13
package/dashboard/js/utils.js +1 -1
package/dashboard/slim/body.html +2 -2
package/dashboard/slim/styles.css +112 -77
package/dashboard/styles.css +37 -3
package/dashboard.js +67 -10
package/docs/README.md +1 -1
package/docs/auto-discovery.md +2 -1
package/docs/branch-derivation.md +68 -0
package/docs/cooldown-merge-semantics.md +4 -4
package/docs/design-state-storage.md +5 -5
package/docs/kb-sweep.md +2 -2
package/docs/managed-spawn.md +1 -1
package/docs/timeouts-and-liveness.md +120 -0
package/docs/watches.md +9 -9
package/docs/worktree-lifecycle.md +164 -0
package/engine/cli.js +8 -5
package/engine/dispatch.js +26 -1
package/package.json +6 -1

package/dashboard/styles.css CHANGED Viewed

@@ -3,7 +3,7 @@
        [data-font-size] on <html>. 'small' is the historic default (1.0) so
        existing users see no change. Body-level CSS `zoom` is the cheapest
        way to scale every px/em/rem rule across the SPA (typography tokens
-       below, slim.html, and the many inline `font-size:11px` styles) without
+       below, slim.html, and the many inline font-size Npx styles) without
        rewriting every rule. Scales modals, drawers, and fixed-position
        elements because they all live inside <body>. */
     --minions-font-scale: 1;
@@ -15,11 +15,30 @@
     --space-1: 2px; --space-2: 4px; --space-3: 6px; --space-4: 8px;
     --space-5: 10px; --space-6: 12px; --space-7: 16px; --space-8: 20px; --space-9: 24px;
-    /* Typography scale */
+    /* Typography — size primitives (raw px). Source of truth for the
+       ~700 callsites migrated in PR #66; do NOT introduce new raw `Npx`
+       font-sizes outside this block. Tripwire:
+       test/unit/dashboard-font-size-tokens.test.js */
     --text-xs: 10px; --text-sm: 11px; --text-base: 12px;
     --text-md: 13px; --text-lg: 14px; --text-xl: 16px; --text-2xl: 18px;
     --text-stat: 22px; --text-stat-lg: 28px; --text-display: 32px;
+    /* Typography — role aliases (W-mq1c8og40003a7cf). Prefer these for
+       NEW code: the role names survive a size-scale redesign while the
+       primitives do not. Existing callsites that still reference the
+       size primitives directly are kept (they're correct by
+       construction — every role alias is just an indirection). See
+       dashboard/docs/typography.md for the role → primitive map and
+       intended use. */
+    --text-role-display:    var(--text-display);  /* 32px — hero / page title */
+    --text-heading:         var(--text-2xl);      /* 18px — section + modal headers */
+    --text-subheading:      var(--text-xl);       /* 16px — secondary headers, card titles */
+    --text-body:            var(--text-lg);       /* 14px — default body text */
+    --text-meta:            var(--text-md);       /* 13px — captions, timestamps, secondary metadata */
+    --text-caption:         var(--text-base);     /* 12px — small labels, table cells */
+    --text-micro:           var(--text-sm);       /* 11px — chip / tag pill labels */
+    --text-code:            0.9em;                /* inline code; relative so it scales with the surrounding text */
     /* Border radius */
     --radius-sm: 4px; --radius-md: 6px; --radius-lg: 8px; --radius-xl: 10px; --radius-full: 50%;
@@ -43,6 +62,21 @@
   html, body { height: 100%; margin: 0; overflow: hidden; }
   body { background: var(--bg); color: var(--text); font-family: 'Segoe UI', system-ui, sans-serif; font-size: var(--text-xl); display: flex; flex-direction: column; zoom: var(--minions-font-scale, 1); }
+  /* Typography utility classes (W-mq1c8og40003a7cf).
+     One class per role token. Apply directly on any element
+     (`<span class="text-meta">`) so JS/HTML callsites don't need to
+     hand-roll inline `style="font-size:var(--text-*)"`. The classes
+     ONLY set font-size — weight, color, line-height stay with the
+     caller. Mirrors the `.btn-add` consolidation in spirit. */
+  .text-display    { font-size: var(--text-role-display); }
+  .text-heading    { font-size: var(--text-heading); }
+  .text-subheading { font-size: var(--text-subheading); }
+  .text-body       { font-size: var(--text-body); }
+  .text-meta       { font-size: var(--text-meta); }
+  .text-caption    { font-size: var(--text-caption); }
+  .text-micro      { font-size: var(--text-micro); }
+  .text-code       { font-size: var(--text-code); }
   header {
     background: var(--surface); border-bottom: 1px solid var(--border);
     padding: var(--space-6) 14px; display: flex; align-items: center; justify-content: space-between;
@@ -240,7 +274,7 @@
   .prd-item-row.st-needs-human-review { border-left-color: var(--orange); }
   .prd-item-row.st-updated { border-left-color: var(--purple); }
   .prd-item-row.st-paused { border-left-color: var(--muted); opacity: 0.5; }
-  .prd-item-id { font-family: Consolas, monospace; color: var(--muted); min-width: 36px; font-size: 0.9em; }
+  .prd-item-id { font-family: Consolas, monospace; color: var(--muted); min-width: 36px; font-size: var(--text-code); }
   .prd-item-name { flex: 1; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
   .prd-item-priority { font-size: var(--text-sm); padding: var(--space-1) var(--space-3); border-radius: var(--radius-lg); }
   .prd-item-priority.high { background: rgba(248,81,73,0.15); color: var(--red); }

package/dashboard.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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