@yemi33/minions 0.1.2148 → 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/settings.js

@@ -292,12 +292,19 @@ async function openSettings() {
     '<div class="settings-pane-sub">Persistent CC worker pool and git worktree provisioning. Tune these only if you see worktree-create timeouts or slow CC cold-spawns.</div>' +
     '<div class="settings-stack" style="margin-bottom:12px">' +
       settingsToggle('CC Worker Pool', 'set-ccUseWorkerPool', (e.ccUseWorkerPool === undefined ? ((e.ccCli || e.defaultCli) === 'copilot') : !!e.ccUseWorkerPool), 'Route Command Center / doc-chat through a persistent copilot --acp worker per tab instead of spawning a fresh CLI per turn. Copilot-only (Agent Client Protocol transport); Claude does not implement ACP, so this toggle has no effect when CC runtime is Claude. Default ON for copilot (cold-spawn ~20s on Windows); forced OFF for non-copilot CC runtimes regardless of this toggle.') +
+      // W-mq6f2fe0000557fa — opt-in: auto-kill orphan spawn-agent processes
+      // holding a stuck worktree's cwd. Gated by safe-reap criteria (cmdline
+      // matches spawn-agent.js + basename + age > agentTimeout * 2). Default
+      // OFF because killing a foreign process is destructive.
+      settingsToggle('Auto-reap orphan worktree holders', 'set-autoReapOrphanWorktreeHolders', !!e.autoReapOrphanWorktreeHolders,
+        'When ON, the periodic orphan-worktree sweep automatically kills unambiguous orphan `spawn-agent.js` processes holding a stuck worktree\'s cwd (Windows file-lock pattern, e.g. W-mq1k8z6o003acd89 / PID 16828). Safe-reap criteria: cmdline must match spawn-agent.js, reference the worktree basename, AND process age must exceed `engine.agentTimeout * 2`. Default OFF because killing a foreign process is destructive. The holder SCAN runs either way and is appended to the escalation inbox note.') +
     '</div>' +
     '<div class="settings-grid-2">' +
       settingsField('Worktree Create Timeout', 'set-worktreeCreateTimeout', e.worktreeCreateTimeout || 300000, 'ms', 'Timeout for git worktree add (increase for large repos/Windows)') +
       settingsField('Worktree Create Retries', 'set-worktreeCreateRetries', e.worktreeCreateRetries || 1, '', 'Retry count for transient worktree add failures (0-3)') +
       settingsField('Worktree Root', 'set-worktreeRoot', e.worktreeRoot || '../worktrees', '', 'Relative or absolute path for git worktrees; on Windows prefer a short path like C:\\wt') +
       settingsField('Assert-Clean Status Probe Timeout', 'set-assertCleanStatusTimeoutMs', e.assertCleanStatusTimeoutMs || 10000, 'ms', 'Timeout for the `git status --porcelain` preflight probe in assertCleanSharedWorktree. Raise this (e.g. 60000) on GVFS/Plastic-backed monorepos where sparse hydration runs longer than the 10s default. On timeout the engine quarantines the bad worktree and emits a RETRYABLE failure so the next dispatch starts fresh. Clamped 1000–120000ms.') +
+      settingsField('Orphan-holder scan timeout', 'set-orphanHolderScanTimeoutMs', e.orphanHolderScanTimeoutMs || 5000, 'ms', 'Cap on the cross-platform scan (PowerShell / /proc walk / lsof) that identifies the OS process holding a stuck worktree\'s cwd. Bumps up only matter on heavily-loaded hosts where the holder scan races the sweep tick. Clamped 1000–30000ms.') +
     '</div>';
 
   const paneCopilot =
@@ -873,6 +880,8 @@ async function saveSettings() {
       autoFixHumanComments: document.getElementById('set-autoFixHumanComments').checked,
       autoCompletePrs: document.getElementById('set-autoCompletePrs').checked,
       ccUseWorkerPool: !!document.getElementById('set-ccUseWorkerPool')?.checked,
+      autoReapOrphanWorktreeHolders: !!document.getElementById('set-autoReapOrphanWorktreeHolders')?.checked,
+      orphanHolderScanTimeoutMs: document.getElementById('set-orphanHolderScanTimeoutMs')?.value,
       adoPollEnabled: document.getElementById('set-adoPollEnabled').checked,
       ghPollEnabled: document.getElementById('set-ghPollEnabled').checked,
       prPollStatusEvery: document.getElementById('set-prPollStatusEvery').value,

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();
@@ -9361,6 +9407,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // 2min ceiling (covers even a GVFS-backed sparse hydration without
           // letting a config typo wedge dispatch for an hour).
           assertCleanStatusTimeoutMs: [1000, 120000],
+          // W-mq6f2fe0000557fa — cap on the cross-platform holder scan for the
+          // orphan-worktree GC. 1s floor (PowerShell startup alone is 0.5–1s);
+          // 30s ceiling (the scan runs once per orphan-sweep tick and a slow
+          // scan must not block the rest of the sweep for minutes).
+          orphanHolderScanTimeoutMs: [1000, 30000],
           idleAlertMinutes: [1], shutdownTimeout: [30000], restartGracePeriod: [60000],
           meetingRoundTimeout: [60000],
           // W-mq066js7000fff1f-c (Gap B/C): steering safety-net knobs.
@@ -11065,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 = [
@@ -11081,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) => {
@@ -11345,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) => {
@@ -12332,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