@yemi33/minions 0.1.2214 → 0.1.2216

package/bin/minions.js

@@ -58,6 +58,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const net = require('net');
 const { spawn, spawnSync, execSync } = require('child_process');
 
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -136,6 +137,24 @@ function killByPort(port) {
 
 const isPortListening = (port) => getListeningPids(port).length > 0;
 
+/** Authoritative "is something accepting TCP connections on this port?" probe.
+ *  Resolves true iff a connection to 127.0.0.1:port completes within timeoutMs.
+ *  Unlike the netstat-based isPortListening, this can't false-negative under
+ *  CPU/event-loop load: the TCP handshake is satisfied by the OS listen backlog
+ *  even when the listener's JS event loop is momentarily blocked. Used by the
+ *  watchdog to overturn a transient `down` verdict before restarting a live
+ *  dashboard. Never throws; resolves false on any error/timeout. */
+function tcpPortAccepts(port, timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (val) => { if (!settled) { settled = true; try { socket.destroy(); } catch {} resolve(val); } };
+    const socket = net.connect({ host: '127.0.0.1', port: Number(port) });
+    socket.once('connect', () => done(true));
+    socket.once('error', () => done(false));
+    socket.setTimeout(timeoutMs, () => done(false));
+  });
+}
+
 /**
  * Wait until no process is listening on `port`, retrying a kill on each tick
  * for any stragglers that re-appeared (e.g. orphan child the original kill
@@ -630,6 +649,28 @@ const { cmd, rest, devMode, devPort } = (() => {
   const [firstCmd, ...restArgs] = out;
   return { cmd: firstCmd, rest: restArgs, devMode: dev, devPort: port || DEFAULT_DEV_DASH_PORT };
 })();
+
+// ── Node / node:sqlite version gate (issue #244) ────────────────────────────
+// node:sqlite is the only state backend post Phase 9.4 and exists only on
+// Node >= 22.5; the --experimental-sqlite self-reexec at the top of this file
+// is a no-op below 22.5. Without this gate, any command that touches getDb()
+// (`minions status`, `queue`, engine delegations, …) dumps a raw node:sqlite
+// stack trace. Fail closed with the canonical one-line remediation. Numeric
+// version compare via shared helper — never string compares, never throws.
+//
+// Exempt the commands a stranded user still needs: `doctor` re-emits the same
+// remediation as a structured FAIL (and suppresses the downstream fallout
+// warnings); help/version are pure; uninstall/nuke must stay reachable to
+// clean up. Everything else short-circuits before we spawn a child that would
+// only crash with the same trace.
+const NODE_GATE_EXEMPT = new Set([
+  'doctor', 'version', '--version', '-v', 'help', '--help', '-h', 'uninstall', 'nuke',
+]);
+if (!shared.nodeSupportsBuiltinSqlite() && cmd && !NODE_GATE_EXEMPT.has(cmd)) {
+  console.error(`\n  ${shared.nodeSqliteRemediationLine()}\n`);
+  process.exit(1);
+}
+
 let force = rest.includes('--force');
 const skipScan = rest.includes('--skip-scan');
 const skipStart = rest.includes('--skip-start') || rest.includes('--no-start');
@@ -1483,6 +1524,7 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
       dashPort: DASHBOARD_PORT,
       readEnginePid,
       isPortListening,
+      confirmPortUp: tcpPortAccepts,
       isStopIntentSet: shared.isStopIntentSet || (() => false),
     }).then(result => {
       // ALWAYS exit 0 — the scheduler must never see a failure for the

package/dashboard/js/render-other.js

@@ -73,18 +73,18 @@ function _renderProjectBranch(p) {
 }
 
 // Renders a compact pill indicating the project's dispatch mode (W-mqgzcrln002613b3):
-// "Worktrees" (isolated — default, agents run in their own git worktree) vs
+// "Worktrees" (worktree — default, agents run in their own git worktree) vs
 // "Live checkout" (live — agents run in-place inside the operator's working
-// tree). Driven by p.worktreeMode (shared.WORKTREE_MODES; engine defaults
-// unset → 'isolated'). Live is the riskier/special mode (capped to one mutating
+// tree). Driven by p.checkoutMode (shared.CHECKOUT_MODES; engine defaults
+// unset → 'worktree'). Live is the riskier/special mode (capped to one mutating
 // dispatch per project, refuses on a dirty tree) so it gets a more prominent
-// color than the muted isolated pill.
+// color than the muted worktree pill.
 function _renderWorktreeModePill(p) {
   if (!p) return '';
-  if (p.worktreeMode === 'live') {
+  if (p.checkoutMode === 'live') {
     return ' <span class="project-mode-pill project-mode-live" title="Live-checkout dispatch mode — agents run in-place inside the project working tree (no isolated worktree); capped to one mutating dispatch and refused on a dirty tree">⚡ Live checkout</span>';
   }
-  return ' <span class="project-mode-pill project-mode-isolated" title="Isolated dispatch mode (default) — each agent runs in its own git worktree">Worktrees</span>';
+  return ' <span class="project-mode-pill project-mode-isolated" title="Worktree dispatch mode (default) — each agent runs in its own git worktree">Worktrees</span>';
 }
 
 function _projectCachePath(project) {

package/dashboard/js/settings.js

@@ -259,20 +259,22 @@ async function openSettings() {
         '<div style="font-size:var(--text-xs);color:var(--muted);margin-top:1px">Parsed from <code>git symbolic-ref refs/remotes/origin/HEAD</code>' + (localBranch ? '. Local HEAD: <code>' + escHtml(localBranch) + '</code>' : '') + '.</div>' +
       '</div>' +
     '</div>';
-    // P-a3f9b207 — per-project worktreeMode dropdown + warning chip. Default
-    // 'isolated' (engine creates a dedicated worktree per dispatch); 'live'
-    // runs the agent directly in p.localPath for repos where worktrees are
-    // unworkable. Chip is hidden by default and toggled reactively below.
-    var currentWtMode = (p.worktreeMode === 'live') ? 'live' : 'isolated';
-    var wtModeSearch = 'worktree mode isolated live checkout dispatch';
+    // P-a3f9b207 (consolidated W-mqiaw974) — per-project checkoutMode dropdown
+    // + warning chip. Default 'worktree' (engine creates a dedicated worktree
+    // per dispatch); 'live' runs the agent directly in p.localPath for repos
+    // where worktrees are unworkable. p.checkoutMode is resolved server-side
+    // (honors the legacy worktreeMode field). Chip is hidden by default and
+    // toggled reactively below.
+    var currentWtMode = (p.checkoutMode === 'live') ? 'live' : 'worktree';
+    var wtModeSearch = 'checkout mode worktree isolated live dispatch';
     var worktreeModeBlock =
       '<div data-search="' + escHtml(wtModeSearch) + '" style="margin-bottom:6px">' +
-        '<label style="font-size:var(--text-sm);color:var(--muted);display:block;margin-bottom:2px">Worktree mode</label>' +
-        '<select id="set-worktreeMode-' + escHtml(p.name) + '" data-worktree-mode-select="' + escHtml(p.name) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-md)">' +
-          '<option value="isolated"' + (currentWtMode === 'isolated' ? ' selected' : '') + '>Isolated (default)</option>' +
+        '<label style="font-size:var(--text-sm);color:var(--muted);display:block;margin-bottom:2px">Checkout mode</label>' +
+        '<select id="set-checkoutMode-' + escHtml(p.name) + '" data-checkout-mode-select="' + escHtml(p.name) + '" style="width:100%;padding:4px 6px;background:var(--surface);border:1px solid var(--border);border-radius:4px;color:var(--text);font-size:var(--text-md)">' +
+          '<option value="worktree"' + (currentWtMode === 'worktree' ? ' selected' : '') + '>Worktree (default)</option>' +
           '<option value="live"' + (currentWtMode === 'live' ? ' selected' : '') + '>Live checkout</option>' +
         '</select>' +
-        '<div data-worktree-mode-chip="' + escHtml(p.name) + '" style="' + (currentWtMode === 'live' ? '' : 'display:none;') + 'margin-top:6px;padding:6px 8px;background:rgba(234,179,8,0.12);border:1px solid var(--yellow);border-radius:4px;color:var(--yellow);font-size:var(--text-xs);line-height:1.4">' +
+        '<div data-checkout-mode-chip="' + escHtml(p.name) + '" style="' + (currentWtMode === 'live' ? '' : 'display:none;') + 'margin-top:6px;padding:6px 8px;background:rgba(234,179,8,0.12);border:1px solid var(--yellow);border-radius:4px;color:var(--yellow);font-size:var(--text-xs);line-height:1.4">' +
           '⚠ Live mode: dispatches run directly in this repo\'s checkout. Only one mutating dispatch runs at a time. Dirty working trees block dispatch — commit or stash before running.' +
         '</div>' +
       '</div>';
@@ -666,14 +668,14 @@ async function openSettings() {
   });
 
   // P-a3f9b207 — toggle the live-mode warning chip reactively when the
-  // operator flips the per-project worktreeMode dropdown (before save). The
-  // chip is rendered once with display:none for isolated projects and
+  // operator flips the per-project checkoutMode dropdown (before save). The
+  // chip is rendered once with display:none for worktree-mode projects and
   // visible for already-live projects; this handler only flips the
   // display style — no markup is regenerated.
-  document.querySelectorAll('[data-worktree-mode-select]').forEach(function(sel) {
+  document.querySelectorAll('[data-checkout-mode-select]').forEach(function(sel) {
     sel.addEventListener('change', function() {
-      const projName = sel.getAttribute('data-worktree-mode-select');
-      const chip = document.querySelector('[data-worktree-mode-chip="' + (window.CSS && CSS.escape ? CSS.escape(projName) : projName) + '"]');
+      const projName = sel.getAttribute('data-checkout-mode-select');
+      const chip = document.querySelector('[data-checkout-mode-chip="' + (window.CSS && CSS.escape ? CSS.escape(projName) : projName) + '"]');
       if (!chip) return;
       chip.style.display = (sel.value === 'live') ? '' : 'none';
     });
@@ -1083,16 +1085,17 @@ async function saveSettings() {
       // Projects. Empty string = clear the override; the field stays optional.
       const mainBranchInput = document.getElementById('set-mainBranch-' + p.name);
       const mainBranchValue = mainBranchInput ? mainBranchInput.value.trim() : (p.mainBranch || '');
-      // P-a3f9b207 — per-project worktreeMode. Normalize to 'isolated' for
-      // any value other than 'live' so a stale DOM never POSTs garbage; the
-      // server-side validator (shared.validateWorktreeMode) is the
-      // authoritative gate for unknown values.
-      const wtModeInput = document.getElementById('set-worktreeMode-' + p.name);
-      const wtModeValue = (wtModeInput && wtModeInput.value === 'live') ? 'live' : 'isolated';
+      // P-a3f9b207 (consolidated W-mqiaw974) — per-project checkoutMode.
+      // Normalize to 'worktree' for any value other than 'live' so a stale DOM
+      // never POSTs garbage; the server-side validator
+      // (shared.validateCheckoutMode) is the authoritative gate for unknown
+      // values.
+      const wtModeInput = document.getElementById('set-checkoutMode-' + p.name);
+      const wtModeValue = (wtModeInput && wtModeInput.value === 'live') ? 'live' : 'worktree';
       return {
         name: p.name,
         mainBranch: mainBranchValue || null,
-        worktreeMode: wtModeValue,
+        checkoutMode: wtModeValue,
         workSources: {
           pullRequests: { enabled: document.getElementById('set-ws-prs-' + p.name)?.checked ?? true },
           workItems: { enabled: document.getElementById('set-ws-wi-' + p.name)?.checked ?? true }

package/dashboard.js

@@ -358,17 +358,21 @@ function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
       } else {
         delete currentProject.mainBranch;
       }
-      // P-a3f9b208 — mirror worktreeMode the same way: empty / unset on
-      // candidate clears the field so the engine falls back to "isolated".
+      // P-a3f9b208 — mirror checkoutMode the same way: empty / unset on
+      // candidate clears the field so the engine falls back to "worktree".
       // Without this branch the validated POST-body update (mutated on
       // `candidate` in handleSettingsUpdate) is silently dropped on the way
       // through mergeSettingsConfigUpdate → mutateDashboardConfig and never
       // reaches disk — the endpoint would return 200 but persist nothing.
-      if (Object.prototype.hasOwnProperty.call(candidateProject, 'worktreeMode')) {
-        currentProject.worktreeMode = candidateProject.worktreeMode;
+      if (Object.prototype.hasOwnProperty.call(candidateProject, 'checkoutMode')) {
+        currentProject.checkoutMode = candidateProject.checkoutMode;
       } else {
-        delete currentProject.worktreeMode;
+        delete currentProject.checkoutMode;
       }
+      // W-mqiaw974 (issue #241): the field was renamed from the legacy
+      // `worktreeMode`. Drop any stale legacy key on every settings save so a
+      // migrated project never carries both fields.
+      delete currentProject.worktreeMode;
     }
   }
   shared.pruneDefaultClaudeConfig(current);
@@ -1206,7 +1210,7 @@ const _PROJECT_LOCAL_FOOTGUN_WARNING =
   'git. A fresh `git worktree add` for a mutating dispatch will NOT see them, so ' +
   'the dispatched agent silently underperforms. Fix: commit them, move them to ' +
   'user scope (~/.claude/skills/..., ~/.copilot/skills/...), or flip the project ' +
-  'to live-checkout mode (worktreeMode: live).';
+  'to live-checkout mode (checkoutMode: live).';
 
 function _walkUncommittedHarnessAssets(absStart, rootDir, projectName) {
   const results = [];
@@ -2351,8 +2355,9 @@ function _buildStatusSlowState() {
         branchMismatch,
         // P-a3f9b209 / W-mqgzcrln002613b3 — surface the per-project dispatch
         // mode so the Projects view can render a "Worktrees" vs "Live checkout"
-        // pill. Default to isolated when unset (matches engine spawn behavior).
-        worktreeMode: p.worktreeMode || shared.WORKTREE_MODES.ISOLATED,
+        // pill. resolveCheckoutMode honors the legacy worktreeMode field and
+        // defaults to 'worktree' when unset (matches engine spawn behavior).
+        checkoutMode: shared.resolveCheckoutMode(p),
       };
     }),
     autoMode: {
@@ -8817,7 +8822,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           confirmToken: body.confirmToken,
           isValidToken: _consumeProjectConfirmToken,
           name: body.name,
-          worktreeMode: body.worktreeMode,
+          checkoutMode: body.checkoutMode ?? body.worktreeMode,
           observeAuthors: Array.isArray(body.observeAuthors) ? body.observeAuthors : undefined,
         });
       } catch (e) {
@@ -10369,10 +10374,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           name: p.name,
           localPath: p.localPath || null,
           mainBranch: p.mainBranch || null,
-          // P-a3f9b207 — surface worktreeMode so the Settings UI can pre-fill
-          // the per-project dropdown. null === absent (engine defaults to
-          // 'isolated' downstream); 'live' opts into the live-checkout path.
-          worktreeMode: p.worktreeMode || null,
+          // P-a3f9b207 — surface checkoutMode so the Settings UI can pre-fill
+          // the per-project dropdown. resolveCheckoutMode honors the legacy
+          // worktreeMode field; 'worktree' (default) or 'live'.
+          checkoutMode: shared.resolveCheckoutMode(p),
           workSources: {
             pullRequests: { enabled: p.workSources?.pullRequests?.enabled !== false, cooldownMinutes: p.workSources?.pullRequests?.cooldownMinutes ?? 30 },
             workItems: { enabled: p.workSources?.workItems?.enabled !== false, cooldownMinutes: p.workSources?.workItems?.cooldownMinutes ?? 0 }
@@ -10755,21 +10760,27 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             if (raw) proj.mainBranch = raw;
             else delete proj.mainBranch;
           }
-          // P-a3f9b201 — per-project worktreeMode enum ('isolated' default,
-          // 'live' for repos where worktrees are unworkable). Empty string /
-          // null clears the override (engine falls back to 'isolated'); any
-          // other value flows through shared.validateWorktreeMode which throws
-          // HTTP 400 on unknown values. Errors propagate to the outer catch
-          // and are returned via e.statusCode/e.message.
-          if (Object.prototype.hasOwnProperty.call(update, 'worktreeMode')) {
-            const raw = update.worktreeMode;
-            if (raw === '' || raw === null) {
-              delete proj.worktreeMode;
+          // P-a3f9b201 (consolidated W-mqiaw974) — per-project checkoutMode enum
+          // ('worktree' default, 'live' for repos where worktrees are
+          // unworkable). Empty string / null clears the override (engine falls
+          // back to 'worktree'); any other value flows through
+          // shared.validateCheckoutMode which throws HTTP 400 on unknown values
+          // (and silently coerces the legacy 'isolated' → 'worktree'). Accepts
+          // the legacy `worktreeMode` key for back-compat. Errors propagate to
+          // the outer catch and are returned via e.statusCode/e.message.
+          const hasCheckoutMode = Object.prototype.hasOwnProperty.call(update, 'checkoutMode');
+          const hasLegacyMode = Object.prototype.hasOwnProperty.call(update, 'worktreeMode');
+          if (hasCheckoutMode || hasLegacyMode) {
+            const raw = hasCheckoutMode ? update.checkoutMode : update.worktreeMode;
+            if (raw === '' || raw === null || raw === undefined) {
+              delete proj.checkoutMode;
             } else {
-              const validated = shared.validateWorktreeMode(raw);
-              if (validated === undefined) delete proj.worktreeMode;
-              else proj.worktreeMode = validated;
+              const validated = shared.validateCheckoutMode(raw);
+              if (validated === undefined) delete proj.checkoutMode;
+              else proj.checkoutMode = validated;
             }
+            // Drop the legacy field so a migrated project never carries both.
+            delete proj.worktreeMode;
           }
         }
       }
@@ -10909,6 +10920,28 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
+  // W-mqidhwcc000m897e — read-only ADO token-acquisition health snapshot.
+  // Surfaces the graduated-backoff + transient/persistent classification state
+  // so an operator can diagnose "ADO polling paused" from one place:
+  //   { token: { lastSuccessAt, lastFailureReason, classification,
+  //              backoffUntil, consecutiveFailures } }.
+  async function handleDiagnosticsAdoToken(req, res) {
+    try {
+      let token = { lastSuccessAt: 0, lastFailureReason: null, classification: null, backoffUntil: 0, consecutiveFailures: 0 };
+      if (typeof ado.getAdoTokenHealth === 'function') {
+        const h = ado.getAdoTokenHealth() || {};
+        token = {
+          lastSuccessAt: Number(h.lastSuccessAt) || 0,
+          lastFailureReason: h.lastFailureReason || null,
+          classification: h.classification || null,
+          backoffUntil: Number(h.backoffUntil) || 0,
+          consecutiveFailures: Number(h.consecutiveFailures) || 0,
+        };
+      }
+      return jsonReply(res, 200, { token });
+    } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
+  }
+
   // P-c3d4e5f6 — /api/diagnostics/memory.
   // Returns the latest in-process dashboard sample, the latest engine
   // sample (read fresh from engine/diagnostics-memory.json via safeJsonObj),
@@ -13651,6 +13684,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/diagnostics/refresh', desc: 'Append a dashboard refresh-diagnostic ring buffer batch to engine/dashboard-diagnostics.log (rotated at 1 MB)', params: 'entries[]', handler: handleDiagnosticsRefresh },
     // Diagnostics — per-org ADO throttle state (W-mq03l6zh0006f0a1-d).
     { method: 'GET', path: '/api/diagnostics/ado-throttle', desc: 'Snapshot of per-org ADO throttle tracker state — { orgs: { [orgBase]: { throttled, retryAfter, consecutiveHits } } }. Falls back to a single `global` key when running against pre-per-org engines.', handler: handleDiagnosticsAdoThrottle },
+    { method: 'GET', path: '/api/diagnostics/ado-token', desc: 'Read-only ADO token-acquisition health — { token: { lastSuccessAt, lastFailureReason, classification, backoffUntil, consecutiveFailures } }. Surfaces the graduated-backoff + transient/persistent classification state (W-mqidhwcc000m897e) so an operator can diagnose paused ADO polling from one line.', handler: handleDiagnosticsAdoToken },
     // Diagnostics — engine + dashboard memory baseline (P-c3d4e5f6).
     { method: 'GET', path: '/api/diagnostics/memory', desc: 'Latest in-process dashboard memory sample plus the most-recent engine sample read from engine/diagnostics-memory.json. engineStale=true when the sidecar is missing or its capturedAt is > 5 min old.', handler: handleDiagnosticsMemory },
     { method: 'GET', path: '/api/diagnostics/memory/history', desc: 'In-memory ring buffer of memory samples. process=dashboard returns the dashboard\'s own collector (populated by startPeriodicSampling on boot). process=engine returns the dashboard\'s polled accumulation of engine/diagnostics-memory.json — engine.js only persists the latest sample to the sidecar, so engine-side history is rebuilt by the dashboard poller (dedup by capturedAt). Optional limit caps returned newest-N samples.', params: 'process (engine|dashboard), limit?', handler: handleDiagnosticsMemoryHistory },

package/docs/README.md

@@ -15,6 +15,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: persistent Sonnet sessions, `--resume` semantics, system-prompt invalidation, and per-tab session storage.
+- [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library: Phase 1 exposes & edits each role's definition + skills; Phase 2 adds role/agent CRUD. Covers the additive `config.roles` model, resolver tiering, migration from per-agent `charter.md`, and API/UI surface.
 - [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.
@@ -30,7 +31,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, notes/inbox digest, work-item modal).
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
-- [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `worktreeMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
+- [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
 - [managed-spawn.md](managed-spawn.md) — Engine-owned long-running services (managed-spawn primitive): sidecar schema, healthcheck examples, lifecycle, dashboard API, and the WI 1 (build) → WI 2 (test) chained-validation pattern.
 - [plan-lifecycle.md](plan-lifecycle.md) — Full plan pipeline from `/plan` through PRD materialization, dispatch with dependency gating, verify task, and human archive.
 - [pr-auto-fix-dispatch.md](pr-auto-fix-dispatch.md) — Short reference table mapping each PR auto-fix / review dispatch site in `engine.js#discoverFromPrs` to its gate flag, plus the `pollingPaused` / `autoFixPaused` master kill-switches and the per-provider polling gates.

package/docs/deprecated.json

@@ -142,6 +142,18 @@
     "targetRemovalDate": "2026-06-16",
     "notes": "Unlike the three record-field aliases, nothing is written here — this is purely an input read-fallback. Removal scope (DEFERRED — gated on confirming no client still POSTs `autoObserve`, not on the expired calendar date): drop the `!body.autoObserve` fallback in the link handler in dashboard.js, drop `autoObserve?` from the route registry `params` string, and update any client (dashboard JS, ops scripts) that still POSTs `autoObserve`. After removal, callers that still send `autoObserve` will see their value silently ignored."
   },
+  {
+    "id": "worktreemode-field-rename",
+    "description": "Legacy `project.worktreeMode` config field (enum 'isolated'|'live'). Consolidated by W-mqiaw974 (issue #241) into a single `project.checkoutMode` field (enum 'worktree'|'live'): the old 'isolated' value became the implicit default 'worktree', and the overlapping/never-shipped 'shared' value was removed. The write side is migrated — buildProjectEntry, dashboard settings POST, and projects.addProject all write `checkoutMode`, and the dashboard settings/merge paths delete any stale `worktreeMode` key on save. What survives is a READ-BRIDGE ONLY: `shared.resolveCheckoutMode(project)` (and the `isLiveCheckoutProject` predicate built on it) reads canonical `checkoutMode` first, then falls back to the legacy `worktreeMode` field ('isolated'→'worktree', 'live'→'live') so an un-migrated config.json keeps dispatching live-checkout projects correctly. `validateCheckoutMode` also silently coerces a submitted legacy 'isolated' value to 'worktree'.",
+    "code": [
+      { "file": "engine/shared.js", "note": "resolveCheckoutMode reads project.worktreeMode as the fallback when checkoutMode is absent; validateCheckoutMode coerces 'isolated'→'worktree'. The only surviving reads of the legacy field are these two back-compat bridges." },
+      { "file": "engine/projects.js", "note": "addProject threads options.checkoutMode ?? options.worktreeMode into buildProjectEntry (accepts the legacy options key)." },
+      { "file": "dashboard.js", "note": "handleProjectsAdd reads body.checkoutMode ?? body.worktreeMode; handleSettingsUpdate + mergeSettingsConfigUpdate accept the legacy update.worktreeMode key and delete proj.worktreeMode on every save (active migration)." }
+    ],
+    "deprecated": "2026-06-17",
+    "targetRemovalDate": "2026-09-17",
+    "notes": "Safe to remove on or after 2026-09-17 (90 days, ~3 release windows) once a sweep of every persisted config.json confirms no `worktreeMode` key remains (the dashboard settings save actively migrates each project the next time it is touched, so the residue shrinks over time) AND no external tooling reads `project.worktreeMode`. Removal scope: drop the legacy-field fallback in shared.resolveCheckoutMode, the 'isolated' coercion in validateCheckoutMode, the `?? options.worktreeMode` / `?? body.worktreeMode` input fallbacks in projects.addProject + dashboard handleProjectsAdd, the `update.worktreeMode` acceptance + `delete proj.worktreeMode` migration in dashboard handleSettingsUpdate/mergeSettingsConfigUpdate, and the legacy back-compat tests in test/unit/{worktree-mode-schema,settings-worktree-mode,live-checkout-mode}.test.js."
+  },
   {
     "id": "pr-observe-observe-body-param",
     "description": "Legacy `observe` body parameter on `POST /api/pull-requests/observe`. The W-mq5s5ttx000j7ab8 endpoint sub-WI introduces canonical `contextOnly` as the inverse (`observe: false` ⇔ `contextOnly: true`) and keeps `observe` accepted for backward compat. Registering the deprecation here so the alias has a documented removal path; the WI explicitly notes this entry is the implementer's call (it is kept for backward compat and may live longer than the underscore-prefixed record fields).",

package/docs/harness-propagation.md

@@ -61,7 +61,7 @@ cwd**. Project-scope skills like `<repo>/.claude/skills/foo/SKILL.md` are
 loaded by the CLI only if `<cwd>/.claude/skills/foo/SKILL.md` exists at
 spawn time. See *The worktree-uncommitted footgun* below.
 
-Live-checkout mode (`project.worktreeMode: 'live'`) collapses both branches
+Live-checkout mode (`project.checkoutMode: 'live'`) collapses both branches
 to `cwd = project.localPath` for every dispatch type, so the agent sees
 the operator's working tree as-is (including uncommitted assets). The
 tradeoff is single-mutating-dispatch concurrency per project — see
@@ -149,7 +149,7 @@ so the only workarounds today are:
 - **Move it user-scope.** Drop it under `~/.claude/skills/bar/` instead —
   the CLI's user-skill discovery still works inside a worktree because
   `--add-dir` attaches `~/.claude`.
-- **Flip to live-checkout mode.** Set `project.worktreeMode = 'live'` on
+- **Flip to live-checkout mode.** Set `project.checkoutMode = 'live'` on
   the project so every dispatch runs in `project.localPath`. Caveats in
   `docs/live-checkout-mode.md`.
 
@@ -263,7 +263,7 @@ hand; `collectSkillFiles` / `collectCommandFiles` already do.
 ## Related docs
 
 - `docs/runtime-adapters.md` — full adapter interface table.
-- `docs/live-checkout-mode.md` — `project.worktreeMode: 'live'`
+- `docs/live-checkout-mode.md` — `project.checkoutMode: 'live'`
   contract (alternative to the worktree-add-dir story for repos where
   worktrees are unworkable).
 - `docs/skills.md` — skill block format and auto-extraction targets.

package/docs/live-checkout-mode.md

@@ -1,12 +1,14 @@
 # Live-checkout dispatch mode
 
-> Per-project opt-in (`project.worktreeMode: 'live'`) that runs Minions agents directly inside the operator's project checkout instead of an engine-managed git worktree.
+> Per-project opt-in (`project.checkoutMode: 'live'`) that runs Minions agents directly inside the operator's project checkout instead of an engine-managed git worktree.
 >
-> Plan: `plan-w-mq5rmtt9000a42f9-2026-06-08`. PRD: `prd/minions-opg-2026-06-10.json` (items `P-a3f9b201` … `P-a3f9b209`). Default for every project remains `'isolated'`; the rest of this doc only applies when a project flips itself to `'live'`.
+> Plan: `plan-w-mq5rmtt9000a42f9-2026-06-08`. PRD: `prd/minions-opg-2026-06-10.json` (items `P-a3f9b201` … `P-a3f9b209`). Default for every project remains `'worktree'`; the rest of this doc only applies when a project flips itself to `'live'`.
+>
+> **Field consolidation (W-mqiaw974 / issue #241).** The dispatch-mode field was renamed from the legacy `worktreeMode` (`'isolated'`|`'live'`) to a single `checkoutMode` (`'worktree'`|`'live'`). `'isolated'` became the implicit `'worktree'` (default). `shared.resolveCheckoutMode(project)` reads the canonical `checkoutMode` first and falls back to the legacy `worktreeMode` (`'isolated'`→`'worktree'`, `'live'`→`'live'`), so existing live-checkout configs keep working with no rewrite. See `docs/deprecated.json` (id `worktreemode-field-rename`).
 
 ## Motivation
 
-The default `isolated` mode spawns each dispatch inside its own git worktree under `../worktrees/`. That works for almost every repo, but it falls over when:
+The default `worktree` mode spawns each dispatch inside its own git worktree under `../worktrees/`. That works for almost every repo, but it falls over when:
 
 - **`repo`-managed multi-project trees** (Android AOSP / Office mobile / Chromium) where the manifest pins dozens of nested repos and `git worktree add` either errors out or strands sub-projects.
 - **Submodule-heavy repos** where worktrees skip `.gitmodules` configuration or leave submodules pointing at the wrong SHA.
@@ -60,9 +62,9 @@ Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate
 ### Enabling live mode (dashboard)
 
 1. Open the Minions dashboard → **Settings** → **Projects** → expand the target project.
-2. Set **Worktree mode** → **Live checkout**. A yellow warning chip appears immediately:
+2. Set **Checkout mode** → **Live checkout**. A yellow warning chip appears immediately:
    > ⚠ Live mode: dispatches run directly in this repo's checkout. Only one mutating dispatch runs at a time. Dirty working trees block dispatch — commit or stash before running.
-3. Click **Save**. The dashboard POSTs the change through `mergeSettingsConfigUpdate`; `shared.validateWorktreeMode` rejects anything other than `'isolated'` or `'live'` with HTTP 400.
+3. Click **Save**. The dashboard POSTs the change through `mergeSettingsConfigUpdate`; `shared.validateCheckoutMode` rejects anything other than `'worktree'` or `'live'` with HTTP 400 (the legacy `'isolated'` value is silently coerced to `'worktree'`).
 
 ### Enabling live mode (config.json)
 
@@ -71,13 +73,13 @@ Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate
   "projects": [{
     "name": "android-aosp",
     "localPath": "/home/yemi/aosp",
-    "worktreeMode": "live",
+    "checkoutMode": "live",
     // …
   }]
 }
 ```
 
-Absent / `null` / `''` reads as `'isolated'` (the default) — explicit is preferred.
+Absent / `null` / `''` reads as `'worktree'` (the default) — explicit is preferred. A legacy `"worktreeMode": "live"` is still honored (and `"worktreeMode": "isolated"` reads as `'worktree'`), but new configs should use `checkoutMode`.
 
 ### Recovering from `live_checkout_dirty` refusal
 
@@ -119,11 +121,11 @@ The engine has no opinion about local branches; this hygiene is the operator's r
 
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
-- **No `auto` mode.** The choice between `isolated` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
+- **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
 - **No auto-stash on dirty refusal.** The engine refuses and exits; it never `git stash`es to "make room" for a dispatch. Stashes silently mutate the operator's tree and conflate engine state with operator state.
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
-- **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `worktreeMode: 'isolated'` (the default).
-- **No per-WI override.** `worktreeMode` is per-project only. There is no `meta.worktreeMode` on a work item that overrides the project setting.
+- **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
+- **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
 - **No auto-pull / no fast-forward on existing branches.** See Guarantee 3. If a PR branch is checked out locally at a different SHA than `origin/<branch>`, the operator resolves it manually.
 - **No special timeout / kill handling.** Live-mode dispatches are killed by PID exactly like isolated-mode dispatches (`engine/timeout.js` header comment). The engine sends SIGTERM/SIGKILL to the tracked process and never touches the working tree on kill.
 
@@ -131,13 +133,13 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 
 | File | Purpose |
 |---|---|
-| `engine/shared.js` — `WORKTREE_MODES`, `validateWorktreeMode` | Enum + validator (P-a3f9b201). |
+| `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
 | `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, branch resolution from HEAD (no fetch, no `origin/<mainRef>` — issue #226) (P-a3f9b203). |
 | `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
 | `engine.js` — dispatcher `liveProjectsInUse` set | Per-project mutating-concurrency cap (P-a3f9b205). |
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
-| `dashboard/js/settings.js` — worktreeMode dropdown + chip | Operator-facing UI (P-a3f9b207). |
+| `dashboard/js/settings.js` — checkoutMode dropdown + chip | Operator-facing UI (P-a3f9b207). |
 | `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring}.test.js` | Wiring and contract tests (P-a3f9b208). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
 | `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY` from mechanical retry. |