@yemi33/minions 0.1.2215 → 0.1.2216

package/bin/minions.js

@@ -649,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');

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;
           }
         }
       }

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

package/docs/specs/agent-configurability.md

@@ -0,0 +1,271 @@
+# Spec: Agent & Role Configurability
+
+**Status:** Draft
+**Owner:** @calebt
+**Audience:** Minions contributors working on the dashboard, engine config surface, and playbook/system-prompt rendering.
+
+> Companion reading: [`.github/copilot-instructions.md`](../../.github/copilot-instructions.md) and [`CLAUDE.md`](../../CLAUDE.md) for the engine/dashboard split and config conventions.
+
+## 1. Motivation
+
+Today a Minions "team" is a fixed roster of five hard-coded agents (`ripley`, `dallas`, `lambert`, `rebecca`, `ralph`) whose personas live in a mix of places: a free-text `role` string in `config.json`, a loosely-related `skills` string array, and a per-agent `charter.md` file. There is **no way to**:
+
+- See an agent's full definition (persona + skills + runtime) in one place.
+- Treat a "role" as a reusable, editable unit — it is just a label string today.
+- Add a brand-new role, or stand up a new named agent, from the dashboard.
+
+The goal is to make the fleet **user-configurable** through a **Role / Agent Library**, delivered in two phases:
+
+- **Phase 1 — Expose & edit.** Surface the skill + definition for each existing role/agent in one editable library view. No new roles or agents yet; just make what exists first-class and editable.
+- **Phase 2 — Create & assign.** Add new roles, and stand up new named agents bound to a role.
+
+## 2. Current state (grounding)
+
+This section is the factual baseline the design must respect. Citations are `file:line` against the repo at spec-authoring time.
+
+### 2.1 Agent object
+
+Agents live under `config.agents` keyed by lowercase id. Defaults are hard-coded:
+
+```js
+// engine/shared.js:4350-4356
+const DEFAULT_AGENTS = {
+  ripley:  { name: 'Ripley',  emoji: '🏗️', role: 'Lead / Explorer', skills: ['architecture', 'codebase-exploration', 'design-review'] },
+  dallas:  { name: 'Dallas',  emoji: '🔧', role: 'Engineer',        skills: ['implementation', 'typescript', 'docker', 'testing'] },
+  lambert: { name: 'Lambert', emoji: '📊', role: 'Analyst',         skills: ['gap-analysis', 'requirements', 'documentation'] },
+  rebecca: { name: 'Rebecca', emoji: '🧠', role: 'Architect',       skills: ['system-design', 'api-design', 'scalability', 'implementation'] },
+  ralph:   { name: 'Ralph',   emoji: '⚙️', role: 'Engineer',        skills: ['implementation', 'bug-fixes', 'testing', 'scaffolding'] },
+};
+```
+
+Runtime / budget fields are **optional per-agent overrides** resolved against `engine.*` fleet defaults via helpers in `engine/shared.js`:
+
+| Field | Resolver | Falls back to |
+|-------|----------|---------------|
+| `cli` | `resolveAgentCli` (shared.js:3142) | `engine.defaultCli` → `'copilot'` |
+| `model` | `resolveAgentModel` (shared.js:3202) | `engine.defaultModel` → undefined |
+| `maxBudgetUsd` / `monthlyBudgetUsd` | `resolveAgentMaxBudget` (shared.js:3231) | `engine.maxBudgetUsd` |
+| `bareMode` | `resolveAgentBareMode` (shared.js:3254) | `engine.claudeBareMode` → false |
+
+So the effective agent shape is:
+
+```jsonc
+{ "name": "Dallas", "emoji": "🔧", "role": "Engineer",
+  "skills": ["implementation","testing"],
+  "cli": "claude", "model": "haiku", "monthlyBudgetUsd": 5, "bareMode": false }
+```
+
+### 2.2 "Role" is a label, not an entity
+
+`role` is a **free-text string** on the agent. There is no role registry, no role schema, and routing does **not** reference roles — it references agent ids. The dashboard edits role as a plain text input (`dashboard/js/settings.js:72`) and persists it verbatim (`dashboard.js:10684`).
+
+### 2.3 `skills` is metadata, not real skills
+
+Two unrelated things share the word "skill":
+
+1. **`agent.skills`** — a string array, surfaced only as an `Expertise: …` line in the system prompt (`engine/playbook.js:950`). It is **not** linked to any executable capability.
+2. **Real `SKILL.md` files** — discovered from disk (`.claude/skills/`, `~/.claude/skills`, project harness dirs) by `collectSkillFiles()` / `getSkills()` (`engine/queries.js:1263-1400`), scoped global/project/plugin. These are **not** bound to a specific agent or role; every agent sees the same discovered catalog.
+
+This split is a key source of the "agents aren't really configurable" feeling and must be addressed explicitly (see §4.3).
+
+### 2.4 Charter = the real "agent definition"
+
+The substantive persona/instructions for an agent is `agents/<id>/charter.md`, read by `getAgentCharter()` (`engine/queries.js:677-678`) and injected into the system prompt as `## Your Charter` (`engine/playbook.js:942-954`). The system prompt assembled in `buildSystemPrompt()` is:
+
+```
+# You are {name} ({role})
+Agent ID: {id}
+Expertise: {skills joined}
+
+## Your Charter
+{charter.md contents}
+```
+(`engine/playbook.js:940-955`)
+
+Charter is already editable today, but only from the **agent detail panel → Charter tab** (`dashboard/js/detail-panel.js:115-126`) via `POST /api/agents/charter` (`dashboard.js:13205-13211`). It is disconnected from the Settings → Agents table.
+
+### 2.5 Routing
+
+`routing.md` is a markdown table mapping work-type → preferred/fallback **agent id** (`routing.md:8-27`), parsed by `engine/routing.js:31-52`. `resolveAgent()` (`engine/routing.js:192`) resolves the route, honoring `_author_` / `_any_` tokens, idleness, budget, and the self-review ban. Routing is edited via `POST /api/settings/routing`, which overwrites `routing.md` wholesale (`dashboard.js:10799-10805`).
+
+### 2.6 Config read / write surface
+
+- **Read:** `queries.getConfig()` (`engine/queries.js:181-225`); Settings read endpoint returns `{ engine, claude, agents, projects, routing }` (`dashboard.js:10362-10391`).
+- **Write:** `POST /api/settings` edits `engine`, `claude`, **existing** `agents[id]` (role, skills, cli, model, budget — `dashboard.js:10682-10705`), and projects, then saves `config.json`. **There is no agent create/delete path** — the loop `for (const [id, updates] of Object.entries(body.agents))` skips unknown ids (`dashboard.js:10683`).
+- **Reset:** restores `engine` defaults + `shared.DEFAULT_AGENTS` (`dashboard.js:10808-10815`).
+- **UI:** Settings → Runtime pane has an **edit-only** Agents table (Role, Skills, CLI, Model, Budget) — `dashboard/js/settings.js:152-157`. No add/remove.
+
+### 2.7 Gaps summary
+
+| Capability | Today |
+|------------|-------|
+| View an agent's full definition in one place | ✗ (split across settings table + charter tab) |
+| Role as a reusable, editable unit | ✗ (free-text label) |
+| Edit charter from the library/settings | ✗ (only detail panel) |
+| Bind skills to a role/agent meaningfully | ✗ (metadata only) |
+| Add a new role | ✗ |
+| Add a new named agent | ✗ |
+| Delete an agent | ✗ |
+
+## 3. Target model: the Role / Agent Library
+
+Introduce a **Role** as a first-class, reusable definition, and make **Agents** named instances that reference a role and optionally override pieces of it.
+
+```jsonc
+// config.json (additive — see §5 migration)
+{
+  "roles": {
+    "engineer": {
+      "label": "Engineer",                 // human-facing name
+      "definition": "<markdown persona>",  // the role-level charter (system-prompt body)
+      "skills": ["implementation", "testing", "bug-fixes"],
+      "defaultCli": null,                  // optional role-level runtime defaults
+      "defaultModel": null,
+      "builtin": true                      // seeded from DEFAULT_ROLES; protects from delete in P1
+    },
+    "architect": { "label": "Architect", "definition": "…", "skills": ["system-design","api-design"] }
+  },
+  "agents": {
+    "dallas": {
+      "name": "Dallas", "emoji": "🔧",
+      "role": "engineer",                  // now references roles{} key (was free text)
+      "skills": [],                        // agent-level ADDITIONS to the role's skills
+      "definitionOverride": null,          // optional per-agent charter override
+      "cli": null, "model": null, "monthlyBudgetUsd": null, "bareMode": false
+    }
+  }
+}
+```
+
+**Resolution rules (engine):**
+
+- Effective **definition** = `agent.definitionOverride` ?? `roles[agent.role].definition` ?? legacy `agents/<id>/charter.md`. (Keeps existing charters working — see §5.)
+- Effective **skills** = union of `roles[agent.role].skills` and `agent.skills`.
+- Effective **label** shown in `# You are {name} ({label})` = `roles[agent.role].label` ?? raw `agent.role` string (legacy).
+- Effective **cli/model** chain unchanged, with an inserted role tier: `agent.cli` → `roles[agent.role].defaultCli` → `engine.defaultCli` → `'copilot'`.
+
+This preserves every existing resolver's external behavior when `roles` is absent or when `agent.role` is still a free-text string (legacy), and layers the library in additively.
+
+## 4. Phase 1 — Expose & edit (no new roles/agents)
+
+**User story:** "For each of the different roles, I want to see and edit the skill and agent definition."
+
+### 4.1 Scope
+
+- A **Role / Agent Library** view in the dashboard listing the existing roles and the agents bound to each.
+- For each role: edit its **definition** (markdown persona) and **skills** list.
+- For each agent: edit its definition override + skills + runtime (consolidating the Settings table fields and the Charter tab into one place).
+- **No** create/delete of roles or agents in Phase 1.
+
+### 4.2 Data model (Phase 1)
+
+- Add `DEFAULT_ROLES` to `engine/shared.js`, derived from the distinct `role` strings in `DEFAULT_AGENTS` (`Lead / Explorer`, `Engineer`, `Analyst`, `Architect`). Seed each role's `definition` from the corresponding agent's existing `charter.md` content where a 1:1 mapping exists; otherwise leave a stub.
+- Migrate `agent.role` free-text → role key on first load (in-memory, mirroring `applyLegacyCcModelMigration`'s no-disk-rewrite pattern in shared.js) by slugifying the label and matching against `roles{}`. Unmatched strings remain as legacy free text and are rendered as an ad-hoc role.
+- Introduce the resolution rules in §3 behind the existing resolver helpers so engine behavior is unchanged when `roles` is absent.
+
+### 4.3 Skills: decide the binding (REQUIRED for this phase)
+
+Phase 1 must resolve the "two meanings of skill" ambiguity. Proposed: keep `roles[].skills` / `agent.skills` as **skill references** (tags), and in the system prompt render them as the `Expertise:` line **plus** — when a tag matches a discovered `SKILL.md` name from `getSkills()` — surface that skill's description inline. This makes the skills list meaningful without forcing a disk-layout change in P1. (Full per-role skill *scoping* of `collectSkillFiles` is deferred to a later phase; see §7.)
+
+### 4.4 API (Phase 1)
+
+- `GET /api/roles` → `{ roles: { <key>: { label, definition, skills, defaultCli, defaultModel, builtin, agentIds[] } } }`. Aggregates `config.roles` + reverse-maps `config.agents` by role.
+- `POST /api/roles/update` → `{ key, definition?, skills?, defaultCli?, defaultModel? }`. Edits an existing role only (P1). Writes through `mutateJsonFileLocked` on `config.json` (never `safeWrite` — see CLAUDE.md concurrency rules).
+- Extend `POST /api/settings` agent loop to accept `definitionOverride`.
+- Reuse/retire `POST /api/agents/charter`: in P1 it continues to write `agents/<id>/charter.md` for backward-compat, but the library writes `definitionOverride` into config; the resolver prefers the override. (Deprecation tracked in `docs/deprecated.json`.)
+
+### 4.5 UI (Phase 1)
+
+- New **Library** entry on the Settings rail (or a top-level sidebar page — decide in review). Layout: left column = role list; right pane = selected role's definition editor (markdown textarea with preview, reusing the Charter tab's editor pattern from `detail-panel.js`) + skills chips + the agents bound to that role (each expandable to its per-agent overrides).
+- Definition editor reuses the existing markdown view/edit toggle and `renderMd()` escaping already used by the Charter tab (`dashboard/js/detail-panel.js:115-126`) to satisfy the no-unsanitized lint gate (`npm run lint`).
+- Settings → Agents table gains a link/affordance into the Library for the definition (so the two surfaces don't drift).
+
+### 4.6 Phase 1 acceptance criteria
+
+1. Library view lists every existing role with its definition + skills, and the agents under each.
+2. Editing a role's definition changes the system prompt for every agent bound to that role (verified by `buildSystemPrompt` output).
+3. Editing an agent's definition override wins over the role definition for that agent only.
+4. Engine behavior is **unchanged** when `config.roles` is absent (back-compat).
+5. All writes go through `mutateJsonFileLocked`; no `safeWrite` on `config.json`.
+6. `npm test` green (add source-inspection + resolver unit tests near existing agent/charter tests); `npm run lint` green.
+7. Settings reset still restores a working fleet (now `DEFAULT_ROLES` + `DEFAULT_AGENTS`).
+
+## 5. Migration & backward compatibility
+
+- **Additive config.** `roles` is new and optional. Absent `roles` ⇒ legacy path (free-text role label, per-agent `charter.md`). No forced disk rewrite — migration is in-memory at load, matching `applyLegacyCcModelMigration`.
+- **Charters preserved.** `agents/<id>/charter.md` remains readable and is the lowest-priority definition source. `minions init`/upgrade already preserves charter files (`bin/minions.js:1361-1368`) — do not regress that.
+- **Routing unaffected in P1/P2-by-agent.** Routing still targets agent ids. (Routing-by-role is explicitly out of scope; see §7.)
+- **Deprecation.** If `POST /api/agents/charter` is superseded by the library's `definitionOverride`, add a `docs/deprecated.json` entry with a cleanup path.
+
+## 6. Phase 2 — Create & assign
+
+**User story:** "Add new roles, and assign new named agents with these roles."
+
+### 6.1 Scope
+
+- **Role CRUD:** create/rename/delete roles in the library. Deleting a role is blocked while agents reference it (or offers reassignment). `builtin` roles are delete-protected.
+- **Agent CRUD:** create a new named agent (id + name + emoji + role + optional overrides) and delete a non-builtin agent.
+- New agents become immediately routable (they appear to `resolveAgent` via `config.agents`) and selectable in `routing.md` (manual) — auto-wiring into routing is out of scope.
+
+### 6.2 Data model / engine
+
+- New agent ids validated: lowercase slug, unique, not colliding with `temp-*` reserved prefix.
+- `resolveAgent` already iterates `config.agents` generically, so new agents are picked up with no engine change (`engine/routing.js:192-249`). Deleting an agent must also: cancel/skip pending dispatches targeting it, and leave its history intact (mirror the conservative posture of project removal in `engine/projects.js`).
+- A new agent with no `charter.md` and no `definitionOverride` inherits its role's definition — this is the payoff of §3.
+
+### 6.3 API (Phase 2)
+
+- `POST /api/roles/create` `{ key, label, definition, skills, defaultCli?, defaultModel? }`.
+- `POST /api/roles/delete` `{ key, reassignTo? }` — refuses if agents reference it and no `reassignTo` given; refuses on `builtin`.
+- `POST /api/agents/create` `{ id, name, emoji, role, overrides? }`.
+- `POST /api/agents/delete` `{ id }` — refuses on builtin; drains/cancels pending dispatches first.
+- Extend `POST /api/settings/reset` semantics: reset clears user-created roles/agents back to `DEFAULT_ROLES`/`DEFAULT_AGENTS`.
+
+### 6.4 UI (Phase 2)
+
+- "+ New role" and "+ New agent" affordances in the Library.
+- Agent creation form (id/name/emoji/role picker + optional runtime overrides).
+- Delete with confirmation + reassignment flow for roles in use.
+
+### 6.5 Phase 2 acceptance criteria
+
+1. A user can create a role with a definition + skills and see it in the library.
+2. A user can create a named agent bound to a role; with no override it inherits the role definition; the engine can route work to it.
+3. Deleting a role in use is blocked or forces reassignment; builtin roles/agents cannot be deleted.
+4. Deleting an agent cancels its pending dispatches and preserves completed history.
+5. Settings reset returns to the default fleet.
+6. `npm test` + `npm run lint` green; new CRUD covered by unit tests; concurrency via `mutateJsonFileLocked`.
+
+## 7. Out of scope (explicitly deferred)
+
+- **Routing-by-role** (e.g. `routing.md` rows targeting a role instead of an agent id). Routing stays agent-id-based.
+- **Per-role/per-agent skill *scoping*** of on-disk `SKILL.md` discovery (`collectSkillFiles` stays global/project/plugin). P1 only makes the skills *list* meaningful in the prompt (§4.3).
+- **Per-project role overrides** (`projects/<name>/...`).
+- **Importing/sharing role libraries** across installs.
+- Any change to the meeting/plan agent-charter linkage beyond reading the new definition source.
+
+## 8. Open questions (resolve in review)
+
+1. **Library placement** — Settings rail entry vs. a dedicated top-level sidebar page?
+2. **Role↔agent cardinality framing** — do we surface roles as the primary list (agents nested under them), or keep agents primary with role as an attribute? (Spec assumes roles-primary in the Library; agents-primary stays in Settings.)
+3. **Charter vs definition naming** — adopt "definition" everywhere, or keep "charter" as the user-facing term to avoid churn in existing UI/tests?
+4. **Skills binding (§4.3)** — ship the "tag matches discovered SKILL.md → inline description" behavior in P1, or keep skills purely as the `Expertise:` line until a later phase?
+5. **Default role definitions** — seed from existing per-agent `charter.md`, or author fresh role-level definitions?
+
+## 9. Work breakdown (suggested PRD seeds)
+
+**Phase 1**
+- P1-a: `DEFAULT_ROLES` + in-memory legacy role migration + resolver tiering (engine/shared.js, playbook.js).
+- P1-b: `GET /api/roles`, `POST /api/roles/update`, `definitionOverride` on `POST /api/settings` (dashboard.js).
+- P1-c: Library UI (role list + definition editor + skills + nested agents) reusing the charter editor pattern.
+- P1-d: Tests (resolver unit tests, source-inspection for endpoints/UI) + `docs/deprecated.json` entry if `/api/agents/charter` is superseded + settings parity note in CLAUDE.md.
+
+**Phase 2**
+- P2-a: Role CRUD API + delete-guard/reassignment.
+- P2-b: Agent CRUD API + dispatch-drain on delete + id validation.
+- P2-c: Library create/delete UI flows.
+- P2-d: Tests + reset semantics + docs.
+
+---
+
+_Every new `engine.*`/config surface introduced here must also get a dashboard control and be documented in CLAUDE.md — config without UI is incomplete (see CLAUDE.md "Best Practices" #15)._

package/engine/cleanup.js

@@ -567,7 +567,7 @@ async function runCleanup(config, verbose = false) {
   // change to both locations, producing mirror-write leaks.
   // We only WARN here — removing someone else's worktree without consent could
   // destroy in-flight work. The operator runs `git worktree remove <path>`.
-  // P-a3f9b206: live-mode projects (worktreeMode === 'live') intentionally
+  // P-a3f9b206: live-mode projects (checkoutMode === 'live') intentionally
   // never create linked worktrees — `git worktree list` returns only the
   // operator's main checkout, which `shared.isPathInside` correctly excludes
   // (equal-path is not "inside"). An empty/main-only nested-worktree scan

package/engine/pr-clone-keep.js

@@ -264,7 +264,7 @@ function _record(plan, fields) {
  *   - `config` — full config; re-checks configured-project so a stale plan can't
  *     re-clone a repo that is already linked.
  *   - `registerOptions` — passed through to projects.addProject (name override,
- *     worktreeMode, observeAuthors, …).
+ *     checkoutMode, observeAuthors, …).
  *   - test seams: `gitClone`, `addProject`, `findConfiguredProject`, `fetchPrBranches`,
  *     `token`/`_resolveTokenForSlug`/`_acquireAdoToken`, `cloneRoot`, `_rm`, `_mkdir`.
  *

package/engine/preflight.js

@@ -12,6 +12,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execSync, execFileSync } = require('child_process');
+const shared = require('./shared');
 
 /**
  * Resolve the Claude Code CLI binary path. Legacy helper preserved for back-
@@ -190,13 +191,20 @@ function runPreflight(opts = {}) {
   const results = [];
   let allOk = true;
 
-  // 1. Node.js version >= 18
+  // 1. Node.js version >= 22.5.0 (built-in node:sqlite — issue #244). HARD FAIL
+  //    on older Node: node:sqlite is the only state backend post Phase 9.4, and
+  //    the --experimental-sqlite self-reexec is a no-op below 22.5, so every
+  //    getDb() throws a raw stack trace. Numeric comparison (shared helper) so
+  //    the 22.4.x → 22.5.0 boundary is correct and we never string-compare.
   const nodeVersion = process.versions.node;
-  const major = parseInt(nodeVersion.split('.')[0], 10);
-  if (major >= 18) {
+  if (shared.nodeSupportsBuiltinSqlite(nodeVersion)) {
     results.push({ name: 'Node.js', ok: true, message: `v${nodeVersion}` });
   } else {
-    results.push({ name: 'Node.js', ok: false, message: `v${nodeVersion} — requires >= 18. Upgrade at https://nodejs.org` });
+    // Message mirrors the canonical CLI-preflight remediation (minus the
+    // leading "Node.js: " label, which printPreflight already renders as the
+    // check name) so doctor and the preflight read identically.
+    const remediation = shared.nodeSqliteRemediationLine(nodeVersion).replace(/^Node\.js:\s*/, '');
+    results.push({ name: 'Node.js', ok: false, message: remediation });
     allOk = false;
   }
 
@@ -239,12 +247,9 @@ function runPreflight(opts = {}) {
   //    us the config. checkOrExit() / cli start() / doctor() pass it; legacy
   //    callers don't, in which case we skip silently.
   if (opts && opts.config && typeof opts.config === 'object') {
-    // Hoisted: `shared` is referenced by every check block below, including
-    // workSources warnings and the worktreeRoot check. Previously declared
-    // inside the first inner try, which left later blocks reading an
-    // undefined identifier (ReferenceError silently caught by the wrapping
-    // try/catch).
-    const shared = require('./shared');
+    // `shared` is module-level (required at top of file) and referenced by
+    // every check block below, including workSources warnings and the
+    // worktreeRoot check.
     try {
       let runtimeNames = [];
       try { runtimeNames = require('./runtimes').listRuntimes(); }
@@ -544,6 +549,13 @@ function doctor(minionsHome) {
   catch { /* missing/invalid config is its own check below */ }
   const { passed, results } = runPreflight({ config: preflightConfig });
 
+  // When Node is too old for built-in node:sqlite (issue #244) the engine
+  // cannot boot, so the stale-engine PID check and per-runtime model-discovery
+  // probes are GUARANTEED to fail/warn — noise that buries the one root cause.
+  // De-prioritize them: skip the model-discovery network probe entirely and
+  // mute the stale-PID entry to a single "expected — fix Node first" note.
+  const nodeCriticalFail = results.some(r => r.name === 'Node.js' && r.ok === false);
+
   // Runtime checks
   const runtimeResults = [];
 
@@ -600,7 +612,13 @@ function doctor(minionsHome) {
           alive = true;
         }
       } catch { /* process may be dead */ }
-      runtimeResults.push({ name: 'Engine', ok: alive, message: alive ? `running (PID ${control.pid})` : `stale PID ${control.pid} — run: minions start (see docs/engine-restart.md)` });
+      if (!alive && nodeCriticalFail) {
+        // Expected fallout of the Node version failure above — don't add a
+        // second critical fail competing for the operator's attention.
+        runtimeResults.push({ name: 'Engine', ok: 'warn', message: `stale PID ${control.pid} — expected while Node is too old; fix the Node.js check above first` });
+      } else {
+        runtimeResults.push({ name: 'Engine', ok: alive, message: alive ? `running (PID ${control.pid})` : `stale PID ${control.pid} — run: minions start (see docs/engine-restart.md)` });
+      }
     } else {
       runtimeResults.push({ name: 'Engine', ok: 'warn', message: `${control.state || 'stopped'} — run: minions start (see docs/engine-restart.md)` });
     }
@@ -641,8 +659,15 @@ function doctor(minionsHome) {
     // avoids a second JSON.parse round-trip.
     const fleetSummary = _fleetSummaryResults(preflightConfig);
     runtimeResults.push(...fleetSummary);
-    const modelResults = await _modelDiscoveryResults(preflightConfig);
-    runtimeResults.push(...modelResults);
+    if (nodeCriticalFail) {
+      // Model discovery shells out to the runtime CLI / REST API, which can't
+      // work while the engine can't boot. Skip the probe and emit one muted
+      // note instead of a per-runtime "discovery unavailable" warning storm.
+      runtimeResults.push({ name: 'Models', ok: 'warn', message: 'discovery skipped — fix the Node.js check above first (engine cannot boot on this Node)' });
+    } else {
+      const modelResults = await _modelDiscoveryResults(preflightConfig);
+      runtimeResults.push(...modelResults);
+    }
     // Verify each runtime CLI still recognizes the headless bypass flags the
     // adapters inject. Catches "user installed an outdated CLI" before the
     // first agent silently hangs on a permission prompt.

package/engine/project-discovery.js

@@ -432,15 +432,16 @@ function buildPrUrlBase({ repoHost, org, project, repoName, prUrlBase }) {
   return '';
 }
 
-function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase, worktreeMode, observeAuthors }) {
+function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase, checkoutMode, observeAuthors }) {
   const safeName = (name || 'project').replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'project';
   const host = repoHost || 'github';
   const isAdo = host === 'ado';
-  // P-a3f9b201: validateWorktreeMode returns undefined on absent/empty (so the
-  // field is omitted and resolves to 'isolated' downstream) and throws an HTTP
-  // 400 Error on unknown values. Run validation BEFORE building the entry so a
-  // typo at the dashboard or CLI never lands in config.json.
-  const resolvedWorktreeMode = shared.validateWorktreeMode(worktreeMode);
+  // P-a3f9b201 (consolidated W-mqiaw974): validateCheckoutMode returns undefined
+  // on absent/empty (so the field is omitted and resolves to 'worktree'
+  // downstream) and throws an HTTP 400 Error on unknown values. Run validation
+  // BEFORE building the entry so a typo at the dashboard or CLI never lands in
+  // config.json.
+  const resolvedCheckoutMode = shared.validateCheckoutMode(checkoutMode);
   const entry = {
     name: safeName,
     description: description || '',
@@ -458,7 +459,7 @@ function buildProjectEntry({ name, description, localPath, repoHost, repositoryI
       workItems: { enabled: true, cooldownMinutes: 0 },
     },
   };
-  if (resolvedWorktreeMode !== undefined) entry.worktreeMode = resolvedWorktreeMode;
+  if (resolvedCheckoutMode !== undefined) entry.checkoutMode = resolvedCheckoutMode;
   // W-mq8li79a000889fa — observeAuthors is the canonical list of author
   // identifiers consumed by the `ado-author-prs` watch (and any future
   // author-scoped watch). Currently only meaningful for ADO projects —

package/engine/projects.js

@@ -535,7 +535,7 @@ async function addProject(target, options = {}) {
     repoName: detected.repoName || name,
     mainBranch: detected.mainBranch || 'main',
     prUrlBase: detected.prUrlBase,
-    worktreeMode: options.worktreeMode,
+    checkoutMode: options.checkoutMode ?? options.worktreeMode,
     observeAuthors: Array.isArray(options.observeAuthors) ? options.observeAuthors : undefined,
   });
 

package/engine/shared.js

@@ -192,6 +192,54 @@ function ts() { return new Date().toISOString(); }
 function logTs() { return new Date().toLocaleTimeString(); }
 function dateStamp() { return new Date().toISOString().slice(0, 10); }
 
+// ── Node / node:sqlite version gate (issue #244) ────────────────────────────
+// `node:sqlite` (the only state backend post Phase 9.4) is built-in only on
+// Node >= 22.5.0. On older Node the `--experimental-sqlite` self-reexec is a
+// no-op and every getDb() throws a raw stack trace. These helpers give the CLI
+// preflight + `minions doctor` a single, NUMERIC (not lexical) version gate and
+// one canonical remediation line so both surfaces agree.
+const NODE_SQLITE_MIN_VERSION = '22.5.0';
+
+/**
+ * Numeric semver-ish comparison of two dotted version strings. Compares
+ * major/minor/patch as integers so '22.5.0' sorts AFTER '22.10.0' would NOT —
+ * i.e. it does NOT lexically compare ('9' > '22' under string compare). Missing
+ * components are treated as 0. Returns -1 (a<b), 0 (a==b), or 1 (a>b).
+ */
+function compareDottedVersions(a, b) {
+  const parse = (v) => String(v == null ? '' : v)
+    .split('.')
+    .map((n) => parseInt(n, 10) || 0);
+  const av = parse(a);
+  const bv = parse(b);
+  const len = Math.max(av.length, bv.length);
+  for (let i = 0; i < len; i++) {
+    const x = av[i] || 0;
+    const y = bv[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+/**
+ * True when the given Node version (default: the running runtime) can load the
+ * built-in `node:sqlite` module — i.e. Node >= 22.5.0. Numeric comparison, so
+ * the 22.4.x → 22.5.0 boundary is handled correctly and 22.10+ / 24+ pass.
+ */
+function nodeSupportsBuiltinSqlite(version = process.versions.node) {
+  return compareDottedVersions(version, NODE_SQLITE_MIN_VERSION) >= 0;
+}
+
+/**
+ * The canonical one-line remediation emitted by both `minions doctor` (as the
+ * failing Node.js check message) and the top-level CLI preflight when Node is
+ * too old for built-in node:sqlite. Keep the wording identical across surfaces.
+ */
+function nodeSqliteRemediationLine(version = process.versions.node) {
+  return `Node.js: v${version} - Minions requires Node >= 22.5 (24 LTS recommended) for built-in node:sqlite. Upgrade Node, then run minions start.`;
+}
+
 // ── F6 (P-f6commentedit): Comment-edit dedup helpers ────────────────────────
 // Shared by engine/github.js + engine/ado.js pollPrHumanComments so a comment
 // EDITED after first observation triggers a single re-dispatch (and only one).
@@ -2483,25 +2531,60 @@ function classifyInboxItem(name, content) {
   return 'project-notes';
 }
 
-// ── Worktree Mode Enum (P-a3f9b201) ─────────────────────────────────────────
-// Per-project switch between the default `isolated` mode (engine creates a
-// dedicated worktree per dispatch under ../worktrees) and `live` mode (the
+// ── Checkout Mode Enum (P-a3f9b201; consolidated W-mqiaw974, issue #241) ──────
+// Per-project switch between the default `worktree` mode (engine creates a
+// dedicated git worktree per dispatch under ../worktrees) and `live` mode (the
 // agent runs directly in the operator's working checkout — used for repos
 // where git worktrees are unworkable, e.g. submodules, hooks, large binary
-// caches). Default is `isolated`; absent/undefined `worktreeMode` on a
-// project entry MUST read as 'isolated' everywhere downstream. Unknown
+// caches). Default is `worktree`; absent/undefined `checkoutMode` on a
+// project entry MUST read as 'worktree' everywhere downstream. Unknown
 // values are rejected at the validators — never silently coerced — so a
 // typo in the dashboard or in config.json cannot wedge dispatch into an
 // unknown mode.
-const WORKTREE_MODES = Object.freeze({ ISOLATED: 'isolated', LIVE: 'live' });
-
-function validateWorktreeMode(value) {
+//
+// LEGACY FIELD (back-compat): this field used to be named `worktreeMode` with
+// the enum { isolated, live }. The rename consolidated the two overlapping
+// fields into a single `checkoutMode` { worktree, live }: `isolated` → the
+// implicit `worktree` behavior, `live` → `live`. `resolveCheckoutMode` still
+// reads the legacy `worktreeMode` field so existing live-checkout projects in
+// config.json keep working without an on-disk rewrite. Tracked in
+// docs/deprecated.json (id: worktreemode-field-rename).
+const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
+
+// Resolve a project's effective checkout mode, honoring the legacy
+// `worktreeMode` field for back-compat. Reading order:
+//   1. canonical `project.checkoutMode` ('worktree' | 'live')
+//   2. legacy `project.worktreeMode` ('isolated' → 'worktree', 'live' → 'live')
+//   3. default → 'worktree'
+// Always returns one of CHECKOUT_MODES — never undefined — so call sites can
+// compare against the enum without a falsy guard.
+function resolveCheckoutMode(project) {
+  if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
+  const canonical = project.checkoutMode;
+  if (canonical === CHECKOUT_MODES.LIVE) return CHECKOUT_MODES.LIVE;
+  if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
+  // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
+  const legacy = project.worktreeMode;
+  if (legacy === 'live') return CHECKOUT_MODES.LIVE;
+  // legacy 'isolated' (and anything else) → the default worktree behavior.
+  return CHECKOUT_MODES.WORKTREE;
+}
+
+// Convenience predicate: does this project dispatch in-place (live checkout)?
+function isLiveCheckoutProject(project) {
+  return resolveCheckoutMode(project) === CHECKOUT_MODES.LIVE;
+}
+
+function validateCheckoutMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value !== 'string') {
-    throw _httpError(400, `Invalid worktreeMode: must be a string (got ${typeof value}). Accepted values: 'isolated', 'live'.`);
+    throw _httpError(400, `Invalid checkoutMode: must be a string (got ${typeof value}). Accepted values: 'worktree', 'live'.`);
   }
-  if (value !== WORKTREE_MODES.ISOLATED && value !== WORKTREE_MODES.LIVE) {
-    throw _httpError(400, `Invalid worktreeMode: "${value}". Accepted values: 'isolated' (default), 'live'.`);
+  // Back-compat: silently coerce the legacy 'isolated' value to the canonical
+  // 'worktree' so an old client / cached dashboard tab doesn't 400.
+  if (value === 'isolated') return CHECKOUT_MODES.WORKTREE;
+  if (value !== CHECKOUT_MODES.WORKTREE && value !== CHECKOUT_MODES.LIVE) {
+    throw _httpError(400, `Invalid checkoutMode: "${value}". Accepted values: 'worktree' (default), 'live'.`);
   }
   return value;
 }
@@ -5564,7 +5647,9 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * field for read-only stages. Only code-mutating pipeline stages need a
  * worktree, and they take the normal code-mutating path below.
  *
- * **Live-checkout mode (P-a3f9b202).** When `project.worktreeMode === 'live'`
+ * **Live-checkout mode (P-a3f9b202).** When the project's resolved checkout
+ * mode is `'live'` (`shared.isLiveCheckoutProject(project)`; canonical
+ * `project.checkoutMode === 'live'` or legacy `project.worktreeMode === 'live'`)
  * the resolver short-circuits BEFORE both branches below and returns
  * `{ cwd: <abs localPath>, worktreeRootDir: null, liveMode: true }` for ALL
  * task types — read-only and code-mutating alike. The agent runs directly
@@ -5591,7 +5676,7 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  * caught post-resolve). The mutating containment check happens later in
  * spawnAgent, against the actual worktree path.
  *
- * @param {{ localPath?: string|null, worktreeMode?: string|null }|null|undefined} project
+ * @param {{ localPath?: string|null, checkoutMode?: string|null, worktreeMode?: string|null }|null|undefined} project
  * @param {string} type — work type (e.g. 'fix', 'explore', 'meeting')
  * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
  * @param {{ workdir?: string|null }} [options] — optional per-WI overrides
@@ -5603,7 +5688,7 @@ const READ_ONLY_ROOT_TASK_TYPES = new Set(['meeting', 'ask', 'explore', 'plan-to
  *      then runs shared.applyWorkdir(worktreePath, result.workdir) to land
  *      the agent inside the subpackage cwd)
  *   The optional `liveMode` discriminator lets callers branch on one boolean
- *   instead of re-reading `project.worktreeMode`.
+ *   instead of re-resolving the project's checkout mode.
  * @throws {Error} LIVE_CHECKOUT_NO_LOCALPATH (live mode, missing localPath),
  *                 INVALID_WORKDIR (live or read-only, workdir escapes base),
  *                 WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (isolated code-mutating),
@@ -5618,11 +5703,11 @@ function resolveSpawnPaths(project, type, minionsDir, options) {
   // Runs BEFORE the read-only / code-mutating split so live mode is the
   // single decision point regardless of task type — read-only tasks in
   // live mode still report liveMode:true so downstream callers don't have
-  // to re-read project.worktreeMode to know they're running in-place.
-  if (project?.worktreeMode === WORKTREE_MODES.LIVE) {
+  // to re-resolve the project's checkout mode to know they're running in-place.
+  if (isLiveCheckoutProject(project)) {
     if (!project.localPath) {
       const err = new Error(
-        'live-checkout mode requires project.localPath (worktreeMode === "live" but localPath is missing/falsy).'
+        'live-checkout mode requires project.localPath (checkoutMode === "live" but localPath is missing/falsy).'
       );
       err.code = 'LIVE_CHECKOUT_NO_LOCALPATH';
       throw err;
@@ -8368,6 +8453,11 @@ module.exports = {
   EDITS_SEEN_CAP, // F6 (P-f6commentedit)
   logTs,
   dateStamp,
+  // Node / node:sqlite version gate (issue #244)
+  NODE_SQLITE_MIN_VERSION,
+  compareDottedVersions,
+  nodeSupportsBuiltinSqlite,
+  nodeSqliteRemediationLine,
   log,
   safeRead,
   safeReadOrNull,
@@ -8561,8 +8651,10 @@ module.exports = {
   HAS_DANGEROUS_KEY_MAX_NODES,
   validateProjectName,
   validateProjectPath,
-  WORKTREE_MODES,
-  validateWorktreeMode,
+  CHECKOUT_MODES,
+  validateCheckoutMode,
+  resolveCheckoutMode,
+  isLiveCheckoutProject,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,

package/engine/timeout.js

@@ -1,7 +1,7 @@
 /**
  * engine/timeout.js — Runtime timeout, stale-orphan cleanup, steering, and idle checks.
  *
- * Live-checkout dispatches (project.worktreeMode === 'live') are killed by PID
+ * Live-checkout dispatches (project.checkoutMode === 'live') are killed by PID
  * exactly like isolated-mode dispatches — no special handling, no in-place
  * `git reset`/`git clean`, no working-tree cleanup. The engine only ever sends
  * SIGTERM/SIGKILL to the tracked process; the operator owns the checkout.

package/engine/worktree-pool.js

@@ -89,7 +89,7 @@ function getProjectPoolSize(projectName, config) {
   // borrow path in spawnAgent into running for a project that no longer
   // wants pooled worktrees. Beats both per-project worktreePoolSize and the
   // engine-wide fleet default.
-  if (proj && proj.worktreeMode === shared.WORKTREE_MODES.LIVE) return 0;
+  if (shared.isLiveCheckoutProject(proj)) return 0;
   if (proj && Number.isFinite(Number(proj.worktreePoolSize))) {
     return Math.max(0, Math.floor(Number(proj.worktreePoolSize)));
   }

package/engine.js

@@ -2046,7 +2046,7 @@ async function spawnAgent(dispatchItem, config) {
   }
 
   // ── Live-checkout mode handling (P-a3f9b204) ─────────────────────────────
-  // When project.worktreeMode === 'live', resolveSpawnPaths returned
+  // When the project's checkout mode is 'live', resolveSpawnPaths returned
   //   cwd = project.localPath, worktreeRootDir = null, liveMode = true.
   // Instead of creating an engine-managed worktree we run prepareLiveCheckout
   // in-place: it validates a clean tree and then checks out (or creates) the
@@ -9247,13 +9247,13 @@ async function tickInner() {
     if (d.meta?.branch) lockedBranches.add(sanitizeBranch(d.meta.branch));
   }
   // P-a3f9b205: Per-project mutating-concurrency gate for live-mode projects.
-  // When project.worktreeMode === 'live', the agent runs in-place inside the
-  // operator's localPath instead of a dedicated worktree, so two concurrent
+  // When the project's checkout mode is 'live', the agent runs in-place inside
+  // the operator's localPath instead of a dedicated worktree, so two concurrent
   // mutating dispatches to the same project would clobber each other's
   // index / working tree. Seed `liveProjectsInUse` from dispatch.active so
   // the gate survives across ticks (not just within one allocation pass).
   // Read-only types (meeting/ask/explore/plan/plan-to-prd) never write, so
-  // they are excluded from the cap. Isolated-mode projects are also
+  // they are excluded from the cap. Worktree-mode projects are also
   // excluded — they get a fresh worktree per dispatch and are naturally
   // safe.
   const liveProjectsInUse = new Set();
@@ -9262,7 +9262,7 @@ async function tickInner() {
     const projName = d.project || d.meta?.project?.name || null;
     if (!projName) continue;
     const projCfg = shared.findProjectByName(shared.getProjects(config), projName);
-    if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+    if (shared.isLiveCheckoutProject(projCfg)) {
       liveProjectsInUse.add(projName);
     }
   }
@@ -9439,7 +9439,7 @@ async function tickInner() {
       && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
     ) {
       const projCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
-      if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+      if (shared.isLiveCheckoutProject(projCfg)) {
         liveProjectsInUse.add(itemProjName);
       }
     }
@@ -9517,7 +9517,7 @@ async function tickInner() {
     const projName = d.project || d.meta?.project?.name || null;
     if (!projName) continue;
     const projCfg = shared.findProjectByName(shared.getProjects(config), projName);
-    if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+    if (shared.isLiveCheckoutProject(projCfg)) {
       postLiveProjectsInUse.add(projName);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2215",
+  "version": "0.1.2216",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"