@yemi33/minions 0.1.2160 → 0.1.2162

package/dashboard/docs/typography.md

@@ -109,6 +109,12 @@ These declarations are intentional and exempt from the tripwire:
 - SVG `font-size='90'` inside the `data:image/svg+xml` favicon link in
   `dashboard/layout.html` and `dashboard/slim/layout.html` — runtime
   data URL, CSS variables don't resolve inside it.
-- The `--text-*` token declarations themselves in `:root` blocks.
+- The `--text-*` token declarations themselves in `:root` blocks. Each
+  primitive is `calc(<base>px * var(--minions-text-scale))` — the
+  `--minions-text-scale` knob (W-mq71mqtx00060fa9) nudges the dashboard's
+  real text size from one place (main `1.05`, slim pinned to `1` so the
+  slim UI keeps its current sizing). The base px stays the source of truth
+  and must match between `dashboard/styles.css` and
+  `dashboard/slim/styles.css`.
 
 Everything else MUST go through a token.

package/dashboard/js/refresh.js

@@ -146,7 +146,7 @@ const RENDER_VERSIONS = {
   dispatch: 2,
   engineLog: 2,
   metrics: 1,
-  workItems: 2,
+  workItems: 3,
   skills: 1,
   mcpServers: 1,
   schedules: 1,

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

@@ -35,12 +35,13 @@ const _WI_ENRICHMENT_FIELDS = [
 //
 // Triggers:
 //   * _preDispatchEval.valid === false (pre-dispatch acceptance gate rejected)
-//   * _pendingReason in { pr_not_found, no_agent, budget_exceeded, dependency_unmet }
+//   * _pendingReason in { pr_not_found, no_agent, budget_exceeded }
 //
 // Does NOT trigger for transient reasons that auto-clear:
 //   * cooldown / retry_cooldown — wait it out
 //   * already_dispatched — engine reconciles on next tick
 //   * branch_locked — wait for the holding dispatch
+//   * dependency_unmet — auto-clears when upstream dep finishes (engine discovery loop + DEPENDENCY_MET watch)
 //
 // Returns { kind, short, full } when the item needs attention, else null.
 // Pure helper (no DOM / escapeHtml deps) so it can be unit-tested in Node.
@@ -74,13 +75,6 @@ function needsAttentionInfo(item) {
     var budgetMsg = 'Assigned agent ' + agent + ' is over its maxBudgetUsd cap.';
     return { kind: 'budget_exceeded', short: budgetMsg, full: budgetMsg };
   }
-  if (reason === 'dependency_unmet') {
-    var deps = Array.isArray(item.depends_on) && item.depends_on.length
-      ? item.depends_on.join(', ')
-      : '<unknown>';
-    var depMsg = 'Waiting on dependencies: ' + deps + '. (One or more are not yet done.)';
-    return { kind: 'dependency_unmet', short: depMsg, full: depMsg };
-  }
   return null;
 }
 

package/dashboard/js/settings.js

@@ -229,6 +229,23 @@ 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';
+    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>' +
+          '<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">' +
+          '⚠ 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>';
     return '<div data-settings-project="' + escHtml(p.name) + '" data-search="project ' + escHtml(p.name.toLowerCase()) + '" style="border:1px solid var(--border);border-radius:6px;padding:10px 12px;margin-bottom:12px">' +
       '<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px">' +
         '<div style="font-size:var(--text-md);font-weight:600">' + escHtml(p.name) + '</div>' +
@@ -236,6 +253,7 @@ async function openSettings() {
       '</div>' +
       pathRow +
       branchGrid +
+      worktreeModeBlock +
       driftNote +
       '<div style="display:flex;flex-direction:column;gap:6px;margin-top:8px">' +
       settingsToggle('Discover from PRs', 'set-ws-prs-' + p.name, p.workSources.pullRequests.enabled, 'Discovery gate: scan repo for open PRs and surface them as review tasks. Independent of ADO/GitHub polling — does not affect already-tracked PRs.') +
@@ -563,6 +581,20 @@ 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
+  // 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) {
+    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) + '"]');
+      if (!chip) return;
+      chip.style.display = (sel.value === 'live') ? '' : 'none';
+    });
+  });
 }
 
 async function initRuntimeFleetUI(engineCfg, agentsCfg) {
@@ -939,9 +971,16 @@ 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';
       return {
         name: p.name,
         mainBranch: mainBranchValue || null,
+        worktreeMode: 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/slim/styles.css

@@ -28,10 +28,17 @@
          (template-baked into slim/layout.html), so we duplicate the
          token VALUES here verbatim — see dashboard/docs/typography.md.
          A tripwire test asserts the slim and main tokens stay in
-         sync (test/unit/dashboard-font-size-tokens.test.js). */
-      --text-xs: 10px; --text-sm: 11px; --text-base: 12px;
-      --text-md: 13px; --text-lg: 14px; --text-xl: 16px; --text-2xl: 18px;
-      --text-stat: 22px; --text-stat-lg: 28px; --text-display: 32px;
+         sync (test/unit/dashboard-font-size-tokens.test.js).
+
+         W-mq71mqtx00060fa9 — the primitive DECLARATIONS stay byte-identical
+         to main (`calc(Npx * var(--minions-text-scale))`), but slim pins
+         --minions-text-scale to 1 while main bumps it to 1.05. That keeps
+         the slim UI at its current text size — the global bump is excluded
+         here by design. Do NOT raise this value to match main. */
+      --minions-text-scale: 1;
+      --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(11px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
+      --text-md: calc(13px * var(--minions-text-scale)); --text-lg: calc(14px * var(--minions-text-scale)); --text-xl: calc(16px * var(--minions-text-scale)); --text-2xl: calc(18px * var(--minions-text-scale));
+      --text-stat: calc(22px * var(--minions-text-scale)); --text-stat-lg: calc(28px * var(--minions-text-scale)); --text-display: calc(32px * var(--minions-text-scale));
       --text-role-display:    var(--text-display);
       --text-heading:         var(--text-2xl);
       --text-subheading:      var(--text-xl);

package/dashboard/styles.css

@@ -15,13 +15,22 @@
     --space-1: 2px; --space-2: 4px; --space-3: 6px; --space-4: 8px;
     --space-5: 10px; --space-6: 12px; --space-7: 16px; --space-8: 20px; --space-9: 24px;
 
-    /* Typography — size primitives (raw px). Source of truth for the
+    /* Typography — size primitives. Source of truth for the
        ~700 callsites migrated in PR #66; do NOT introduce new raw `Npx`
        font-sizes outside this block. Tripwire:
-       test/unit/dashboard-font-size-tokens.test.js */
-    --text-xs: 10px; --text-sm: 11px; --text-base: 12px;
-    --text-md: 13px; --text-lg: 14px; --text-xl: 16px; --text-2xl: 18px;
-    --text-stat: 22px; --text-stat-lg: 28px; --text-display: 32px;
+       test/unit/dashboard-font-size-tokens.test.js
+
+       W-mq71mqtx00060fa9 — every primitive is scaled by --minions-text-scale
+       so the whole dashboard's real text size can be nudged from one knob
+       (currently +5%, a slight bump). This is an actual font-size change,
+       not a zoom. The base px values below stay the source of truth and
+       MUST match dashboard/slim/styles.css verbatim — slim multiplies by
+       its own (un-scaled) factor of 1, so the slim UI is excluded from the
+       bump by construction. */
+    --minions-text-scale: 1.05;
+    --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(11px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
+    --text-md: calc(13px * var(--minions-text-scale)); --text-lg: calc(14px * var(--minions-text-scale)); --text-xl: calc(16px * var(--minions-text-scale)); --text-2xl: calc(18px * var(--minions-text-scale));
+    --text-stat: calc(22px * var(--minions-text-scale)); --text-stat-lg: calc(28px * var(--minions-text-scale)); --text-display: calc(32px * var(--minions-text-scale));
 
     /* Typography — role aliases (W-mq1c8og40003a7cf). Prefer these for
        NEW code: the role names survive a size-scale redesign while the

package/dashboard.js

@@ -215,6 +215,17 @@ 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".
+      // 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;
+      } else {
+        delete currentProject.worktreeMode;
+      }
     }
   }
   shared.pruneDefaultClaudeConfig(current);
@@ -7908,6 +7919,10 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         repoName: detected.repoName || name,
         mainBranch: detected.mainBranch || 'main',
         prUrlBase: detected.prUrlBase,
+        // P-a3f9b201: thread worktreeMode from POST body. buildProjectEntry
+        // validates via shared.validateWorktreeMode — unknown values bubble
+        // up as HTTP 400 below.
+        worktreeMode: body.worktreeMode,
       });
 
       // Create centralized project state files.
@@ -9380,6 +9395,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,
           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 }
@@ -9747,6 +9766,22 @@ 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;
+            } else {
+              const validated = shared.validateWorktreeMode(raw);
+              if (validated === undefined) delete proj.worktreeMode;
+              else proj.worktreeMode = validated;
+            }
+          }
         }
       }
 

package/docs/live-checkout-mode.md

@@ -0,0 +1,143 @@
+# 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.
+>
+> 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'`.
+
+## 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:
+
+- **`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.
+- **Native build state** that lives next to the source (Gradle caches, Xcode `DerivedData`, CMake `build/`, sccache, `.cargo/`, Bazel `bazel-*` symlinks). A fresh worktree throws all of it away and the next build re-downloads / re-compiles.
+- **Deep Windows paths** that hit MAX_PATH (260 chars) once `../worktrees/dispatch-<long-id>-<slug>/<repo-name>/<deep/nested/path>` is appended.
+- **Sparse clones with custom hooks** (`.git/hooks/*`, `git lfs install --local`, `git config --local`) that the operator has set up by hand and that a fresh worktree does not inherit.
+
+For these repos, the operator usually already has one canonical checkout that builds correctly. Live-checkout mode lets the agent dispatch into that checkout instead of cloning a side-by-side copy.
+
+## Contract (four guarantees)
+
+Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has four guarantees; the engine enforces all four and fails dispatches that would violate them.
+
+### 1. Per-project mutating-concurrency cap of 1
+
+Only one mutating dispatch (fix / implement / review / test / verify / decompose / docs) runs per live-mode project at a time. Read-only types (meeting / ask / explore / plan / plan-to-prd) are excluded from the cap because they never write to disk.
+
+Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dispatch list at every allocation pass and per-tick re-annotation; pending items whose project is already in the set are skipped with a `skipReason` and re-tried on the next tick. (`engine.js:7198`, `engine.js:7460`.)
+
+### 2. Refuse-on-dirty (engine never resets the operator tree)
+
+Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) refuses the dispatch immediately:
+
+- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically).
+- Inbox alert written via `dispatch.writeInboxAlert('live-checkout-dirty-<wi-id>', body)`. The body lists the dirty files verbatim from `git status --porcelain`.
+- Work item stamped with `_pendingReason: 'live_checkout_dirty'` so the dashboard surfaces the block.
+- Completion summary: `live-checkout refused: N dirty file(s) in <localPath>`.
+
+The engine never calls `git reset --hard`, `git clean -fd`, `git stash`, or any other state-mutating command against the operator's checkout — not at spawn, not at cleanup, not on timeout, not on engine restart. Cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`).
+
+### 3. No auto-pull, no `--force`, no fast-forward
+
+After the clean-tree check, `prepareLiveCheckout`:
+
+1. Best-effort `git fetch origin <mainRef>` — failure is logged at `warn` and execution continues so offline operators can resume work on an already-checked-out branch.
+2. `git rev-parse --verify <branchName>`:
+   - Succeeds → branch exists locally → plain `git checkout <branchName>` (no `--force`, no `-B`, no pull, no reset). The operator owns the checkout state; if they have local commits or a stale tip relative to `origin/<branchName>`, those are preserved.
+   - Fails → `git checkout -b <branchName> origin/<mainRef>` (new branch, tracks `origin/<mainRef>` as its starting point).
+
+PR-source live dispatches (`meta.branch` set) and shared-branch live dispatches (`meta.branchStrategy === 'shared-branch'`) flow through the same code path with no special case. If the operator already has a PR branch checked out at a different SHA than `origin/<branch>`, the engine will not fast-forward it — that is the intended contract (see Open Q5 in the source PRD). Resolve manually with `git pull --ff-only` or commit the local divergence first.
+
+### 4. No worktree pool, no per-WI subdirectory isolation
+
+Live mode shares one checkout per project. There is no pool to recycle, no quarantine directory, no per-WI subdirectory under the project root. The mutating-concurrency cap (Guarantee 1) is the only isolation mechanism: agents take turns in the same directory.
+
+Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate on `worktreePath` truthiness and `!liveMode`, so the borrow / return / orphan-GC paths execute zero git commands when the project is live.
+
+## Operator workflow
+
+### 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:
+   > ⚠ 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.
+
+### Enabling live mode (config.json)
+
+```jsonc
+{
+  "projects": [{
+    "name": "android-aosp",
+    "localPath": "/home/yemi/aosp",
+    "worktreeMode": "live",
+    // …
+  }]
+}
+```
+
+Absent / `null` / `''` reads as `'isolated'` (the default) — explicit is preferred.
+
+### Recovering from `live_checkout_dirty` refusal
+
+When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. From the project checkout:
+
+```bash
+# Option A — preserve work for later
+git stash push --include-untracked --message "minions: pre-dispatch stash"
+
+# Option B — commit the changes (preferred if they are intentional)
+git add -A && git commit -m "wip: hand-off to minions"
+
+# Option C — discard the changes
+git checkout -- .
+git clean -fd
+```
+
+Then re-dispatch. The next tick will re-pick the pending work item; nothing else needs clearing on the engine side (the inbox alert is informational only).
+
+### Branch-leak mitigation
+
+Live mode never deletes branches it creates. Over time the project checkout accumulates `work/W-…` and `user/<login>/<wi>-<slug>` branches. Periodically prune merged branches:
+
+```bash
+# Delete all local branches already merged into the current branch (typically main).
+git checkout main && git pull --ff-only
+git branch --merged | grep -E '^\s+(work/|user/)' | xargs -r git branch -d
+
+# More aggressive (force-delete branches whose tip is gone from the remote):
+git fetch --prune origin
+git for-each-ref --format '%(refname:short) %(upstream:track)' refs/heads \
+  | awk '$2 == "[gone]" {print $1}' \
+  | xargs -r git branch -D
+```
+
+The engine has no opinion about local branches; this hygiene is the operator's responsibility in live mode.
+
+## Non-goals
+
+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-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 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.
+
+## Related code
+
+| File | Purpose |
+|---|---|
+| `engine/shared.js` — `WORKTREE_MODES`, `validateWorktreeMode` | Enum + validator (P-a3f9b201). |
+| `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, best-effort fetch, branch resolution (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). |
+| `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. |
+| `engine/timeout.js` header comment | Confirms no special live-mode kill handling. |

package/engine/cleanup.js

@@ -567,6 +567,12 @@ 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
+  // 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
+  // result is by-design for live mode; do not "fix" it by adding the main
+  // worktree to the warnings.
   cleaned.nestedWorktrees = 0;
   const _scannedRoots = new Set(); // dedup projects sharing localPath
   for (const project of projects) {

package/engine/dispatch.js

@@ -430,6 +430,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.INVALID_MANAGED_SPAWN, // W-mpbhxg3b000u8411 — managed-spawn.json failed validation; re-running with the same wrong file won't fix it
       FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED, // W-mpbhxg3b000u8411 — healthcheck timed out; agent must fix the spec or the service it spawned
       FAILURE_CLASS.INJECTION_FLAGGED, // F5 (W-mpeklod3000we69c) — agent spotted a prompt-injection attempt in spliced untrusted content; a human must review the source before re-dispatch
+      FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, // P-a3f9b204 — live-checkout refused to spawn because operator localPath is dirty; mechanical retry won't fix it (operator must commit/stash/discard)
     ]);
     if (neverRetry.has(failureClass)) return false;
   }

package/engine/live-checkout.js

@@ -0,0 +1,133 @@
+/**
+ * engine/live-checkout.js — P-a3f9b203
+ *
+ * Pure helper for the live-checkout dispatch mode (plan-w-mq5rmtt9000a42f9-2026-06-08).
+ *
+ * `prepareLiveCheckout({ localPath, branchName, mainRef, gitOpts, dispatchId, wiId, log, _git })`
+ *
+ * Lifecycle (called by spawnAgent in engine.js when resolveSpawnPaths returns liveMode:true):
+ *   1. `git status --porcelain` from localPath. Non-empty output → bail with
+ *      { ok:false, reason:'dirty', dirtyFiles:[…] } so spawnAgent can fail the
+ *      dispatch non-retryably and write an inbox alert. NO mutating git calls
+ *      after this point if dirty.
+ *   2. `git fetch origin <mainRef>` — BEST-EFFORT. Failure is logged via the
+ *      injected `log` (severity 'warn') and execution continues. Offline
+ *      operators can still resume work on a previously-checked-out branch.
+ *   3. Branch resolution:
+ *        a. `git rev-parse --verify <branchName>` succeeds → branch exists
+ *           locally → `git checkout <branchName>` (NO --force, NO auto-pull,
+ *           NO fast-forward, NO reset). The operator owns the checkout
+ *           state per the live-checkout contract; the engine never
+ *           overwrites local commits.
+ *        b. rev-parse fails → branch is new → `git checkout -b <branchName>
+ *           origin/<mainRef>` (tracks remote main as upstream-of-creation).
+ *   4. Returns { ok:true, branch, created:boolean }.
+ *
+ * PURE — does NOT call completeDispatch, does NOT write inbox alerts. That
+ * translation belongs in spawnAgent (engine.js). Keeping this helper free of
+ * side effects lets unit tests exercise every branch with a mocked git
+ * runner and zero filesystem touching.
+ *
+ * All git invocations route through `shared.shellSafeGit` (argv-form,
+ * shell:false, execFile). Branch and main-ref are validated via
+ * `shared.validateGitRef` before any argv is constructed, so a maliciously
+ * crafted branch name like "--evil-flag" is rejected before reaching git.
+ *
+ * Tests inject a mock runner via the private `_git` option (signature
+ * `(args:string[], opts:{cwd, gitExtraArgs?:string[]}) => Promise<string>`).
+ * Production callers omit `_git` and the helper falls back to
+ * `require('./shared').shellSafeGit`.
+ */
+
+'use strict';
+
+const shared = require('./shared');
+
+async function prepareLiveCheckout(opts = {}) {
+  const {
+    localPath,
+    branchName,
+    mainRef,
+    gitOpts,
+    dispatchId, // accepted for caller bookkeeping; not used by the helper
+    wiId,       // accepted for caller bookkeeping; not used by the helper
+    log,
+    _git,       // private injection for testing — defaults to shared.shellSafeGit
+  } = opts;
+
+  // ── Required-arg guards. Throw rather than return {ok:false} so a
+  //    caller's missing wiring fails loudly at the call site.
+  if (!localPath || typeof localPath !== 'string') {
+    throw new Error('prepareLiveCheckout: localPath is required (got ' + JSON.stringify(localPath) + ')');
+  }
+  if (!branchName || typeof branchName !== 'string') {
+    throw new Error('prepareLiveCheckout: branchName is required (got ' + JSON.stringify(branchName) + ')');
+  }
+  if (!mainRef || typeof mainRef !== 'string') {
+    throw new Error('prepareLiveCheckout: mainRef is required (got ' + JSON.stringify(mainRef) + ')');
+  }
+
+  // ── Validate refs before they hit git argv (defense in depth).
+  //    shellSafeGit uses execFile (shell:false) so metacharacters are inert,
+  //    but a leading-dash ref like "--evil" would still be parsed as a git
+  //    flag. validateGitRef throws on those cases (and on other rev-spec
+  //    quirks). Wrap so the caller-facing message mentions the field name.
+  try { shared.validateGitRef(branchName); }
+  catch (e) { throw new Error('prepareLiveCheckout: invalid branchName ref — ' + e.message); }
+  try { shared.validateGitRef(mainRef); }
+  catch (e) { throw new Error('prepareLiveCheckout: invalid mainRef — ' + e.message); }
+
+  const git = (typeof _git === 'function') ? _git : shared.shellSafeGit;
+  const baseOpts = { cwd: localPath, ...(gitOpts || {}) };
+
+  // Small log helper that's safe even when the caller didn't pass `log`.
+  const warn = (msg) => {
+    if (typeof log !== 'function') return;
+    try { log(msg, 'warn'); } catch { /* never let logging crash the helper */ }
+  };
+
+  // ── Step 1: git status --porcelain. Bail early on dirty tree. ─────────
+  // Porcelain format begins each line with a two-char XY status code (e.g.
+  // " M file.js", "?? new.js", "MM stage+unstage.js"). The leading space on
+  // unstaged-only lines is SIGNIFICANT, so we split first and strip ONLY
+  // trailing whitespace/CR per line — outer-trimming the whole blob would
+  // eat the leading XY space on the first line.
+  const statusRaw = await git(['status', '--porcelain'], baseOpts);
+  const statusStr = typeof statusRaw === 'string' ? statusRaw : '';
+  const dirtyFiles = statusStr
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+$/, ''))
+    .filter((line) => line.length > 0);
+  if (dirtyFiles.length > 0) {
+    return { ok: false, reason: 'dirty', dirtyFiles };
+  }
+
+  // ── Step 2: best-effort fetch of mainRef. Log + continue on failure. ──
+  try {
+    await git(['fetch', 'origin', mainRef], baseOpts);
+  } catch (e) {
+    const reason = (e && e.message) ? e.message : String(e);
+    warn('prepareLiveCheckout: git fetch origin ' + mainRef + ' failed (continuing): ' + reason);
+  }
+
+  // ── Step 3: branch resolution + checkout. ─────────────────────────────
+  let branchExists = false;
+  try {
+    await git(['rev-parse', '--verify', branchName], baseOpts);
+    branchExists = true;
+  } catch {
+    branchExists = false;
+  }
+
+  if (branchExists) {
+    // Plain checkout — NO --force, NO -B, NO pull. Operator owns local commits.
+    await git(['checkout', branchName], baseOpts);
+    return { ok: true, branch: branchName, created: false };
+  }
+
+  // New branch — create off of remote main.
+  await git(['checkout', '-b', branchName, 'origin/' + mainRef], baseOpts);
+  return { ok: true, branch: branchName, created: true };
+}
+
+module.exports = { prepareLiveCheckout };

package/engine/preflight.js

@@ -479,14 +479,14 @@ function _checkBypassFlagSupported(runtimeName, adapter, helpText) {
     return {
       name,
       ok: 'warn',
-      message: `adapter did not declare permissionBypassFlags — cannot verify ${runtimeName} CLI accepts headless bypass`,
+      message: `adapter did not declare permissionBypassFlags — cannot verify ${runtimeName} CLI accepts headless bypass. See docs/runtime-adapters.md.`,
     };
   }
   if (helpText == null || helpText === '') {
     return {
       name,
       ok: 'warn',
-      message: `could not invoke ${runtimeName} --help to verify ${flags.join(' ')} support — Minions will still pass the flag(s) but you may see permission prompts if the CLI doesn't accept them`,
+      message: `could not invoke ${runtimeName} --help to verify ${flags.join(' ')} support — Minions will still pass the flag(s) but you may see permission prompts if the CLI doesn't accept them. See docs/runtime-adapters.md.`,
     };
   }
   const missing = flags.filter(f => !helpText.includes(f));
@@ -494,7 +494,7 @@ function _checkBypassFlagSupported(runtimeName, adapter, helpText) {
     return {
       name,
       ok: 'warn',
-      message: `${runtimeName} --help does not list expected flag(s): ${missing.join(', ')} — your CLI may be outdated. Agents will hang on permission prompts. Update with the CLI's package manager (npm i -g @anthropic-ai/claude-code for Claude; winget upgrade Microsoft.CopilotCLI for Copilot)`,
+      message: `${runtimeName} --help does not list expected flag(s): ${missing.join(', ')} — your CLI may be outdated. Agents will hang on permission prompts. Update with the CLI's package manager (npm i -g @anthropic-ai/claude-code for Claude; winget upgrade Microsoft.CopilotCLI for Copilot). See docs/runtime-adapters.md.`,
     };
   }
   return {

package/engine/project-discovery.js

@@ -5,6 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync: defaultExecFileSync } = require('child_process');
+const shared = require('./shared');
 
 function decodeUrlSegment(segment) {
   try { return decodeURIComponent(String(segment || '')); } catch { return String(segment || ''); }
@@ -340,11 +341,16 @@ function buildPrUrlBase({ repoHost, org, project, repoName, prUrlBase }) {
   return '';
 }
 
-function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase }) {
+function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase, worktreeMode }) {
   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';
-  return {
+  // 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);
+  const entry = {
     name: safeName,
     description: description || '',
     localPath: (localPath || '').replace(/\\/g, '/'),
@@ -361,6 +367,8 @@ function buildProjectEntry({ name, description, localPath, repoHost, repositoryI
       workItems: { enabled: true, cooldownMinutes: 0 },
     },
   };
+  if (resolvedWorktreeMode !== undefined) entry.worktreeMode = resolvedWorktreeMode;
+  return entry;
 }
 
 function buildScanResult(repoPath, detected = {}, linked = false) {

package/engine/shared.js

@@ -2281,6 +2281,29 @@ 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
+// 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
+// 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) {
+  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'.`);
+  }
+  if (value !== WORKTREE_MODES.ISOLATED && value !== WORKTREE_MODES.LIVE) {
+    throw _httpError(400, `Invalid worktreeMode: "${value}". Accepted values: 'isolated' (default), 'live'.`);
+  }
+  return value;
+}
+
 // ── Engine Defaults ─────────────────────────────────────────────────────────
 // Single source of truth for engine configuration defaults.
 // Used by: engine.js, minions.js (init). config.template.json only has the project schema.
@@ -3724,6 +3747,7 @@ const FAILURE_CLASS = {
   INVALID_MANAGED_SPAWN: 'invalid-managed-spawn', // P-7a3b1c92: agents/<id>/managed-spawn.json failed validator (bad schema, broken workdir, executable/env not on allowlist, healthcheck shape wrong). Engine refuses to spawn any spec — agent must fix file; never retryable as-is.
   MANAGED_SPAWN_HEALTHCHECK_FAILED: 'managed-spawn-healthcheck-failed', // P-7a3b1c92: at least one managed-spawn spec was spawned but failed its healthcheck within timeout_s. Engine killed the failing PIDs; siblings stay alive. Dispatch ERROR with the failing spec name + log tail surfaced in the inbox alert.
   INJECTION_FLAGGED: 'injection-flagged', // F5 (W-mpeklod3000we69c): the agent set `securityFlags.injectionAttempt:true` in its completion report after spotting a prompt-injection attempt inside an <UNTRUSTED-INPUT> fence. Engine writes a security inbox note + stamps `_securityFlag` on the WI and treats the dispatch as non-retryable so a human can review the source before the agent re-runs.
+  LIVE_CHECKOUT_DIRTY: 'live-checkout-dirty', // P-a3f9b204 (live-checkout dispatch mode): spawnAgent ran prepareLiveCheckout against project.localPath and `git status --porcelain` reported uncommitted changes. Engine refused to spawn (it never runs `git reset`/`git clean` against the operator tree). Inbox alert lists dirty files; WI is stamped `_pendingReason: 'live_checkout_dirty'`. Non-retryable — operator must commit/stash/discard before re-dispatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).
   WORKSPACE_MANIFEST_REPO: 'workspace-manifest-repo-forbidden', // W-mq07avbk000m5543: dispatch routed an agent to a project/repo not present in its workspace_manifest.allowed_repos. Structural — never retryable until the manifest is widened or a different agent is chosen.
   WORKSPACE_MANIFEST_TOOL: 'workspace-manifest-tool-forbidden', // W-mq07avbk000m5543: out-of-scope tool call (manifest enforcement at the runtime gate). Non-retryable as-is.
@@ -4948,17 +4972,50 @@ 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.
  *
- * @param {{ localPath?: string|null }|null|undefined} project
+ * **Live-checkout mode (P-a3f9b202).** When `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
+ * in the operator's working checkout (no `git worktree add`), used for
+ * repos where worktrees are unworkable. Throws
+ * `LIVE_CHECKOUT_NO_LOCALPATH` if `localPath` is missing/falsy — live mode
+ * has no fallback because there is no neutral location to dispatch into.
+ *
+ * @param {{ localPath?: 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
- * @returns {{ cwd: string|null, worktreeRootDir: string|null }}
- *   - For read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
- *   - For code-mutating types: { cwd: null, worktreeRootDir: <project root> }
+ * @param {string} minionsDir — MINIONS_DIR fallback anchor (ignored in live mode)
+ * @returns {{ cwd: string|null, worktreeRootDir: string|null, liveMode?: boolean }}
+ *   - For live mode (any type): { cwd: <abs localPath>, worktreeRootDir: null, liveMode: true }
+ *   - For isolated read-only types: { cwd: <project dir or MINIONS_DIR>, worktreeRootDir: null }
+ *   - For isolated code-mutating types: { cwd: null, worktreeRootDir: <project root> }
  *     (caller defaults cwd to worktreeRootDir before worktree creation)
- * @throws {Error} WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (code-mutating only)
+ *   The optional `liveMode` discriminator lets callers branch on one boolean
+ *   instead of re-reading `project.worktreeMode`.
+ * @throws {Error} LIVE_CHECKOUT_NO_LOCALPATH (live mode, missing localPath),
+ *                 WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT (isolated code-mutating),
  *                 or WORKTREE_ROOTDIR_MISSING_BASE if neither anchor present.
  */
 function resolveSpawnPaths(project, type, minionsDir) {
+  // ── Live-checkout mode short-circuit (P-a3f9b202) ──────────────────────
+  // 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) {
+    if (!project.localPath) {
+      const err = new Error(
+        'live-checkout mode requires project.localPath (worktreeMode === "live" but localPath is missing/falsy).'
+      );
+      err.code = 'LIVE_CHECKOUT_NO_LOCALPATH';
+      throw err;
+    }
+    return {
+      cwd: path.resolve(String(project.localPath)),
+      worktreeRootDir: null,
+      liveMode: true,
+    };
+  }
+
   const isReadOnly = READ_ONLY_ROOT_TASK_TYPES.has(type);
   if (isReadOnly) {
     if (project?.localPath) return { cwd: path.resolve(String(project.localPath)), worktreeRootDir: null };
@@ -7558,6 +7615,8 @@ module.exports = {
   HAS_DANGEROUS_KEY_MAX_NODES,
   validateProjectName,
   validateProjectPath,
+  WORKTREE_MODES,
+  validateWorktreeMode,
   validatePid,
   PR_FIX_CAUSE,
   getPrFixAutomationCause,

package/engine/timeout.js

@@ -1,5 +1,10 @@
 /**
  * engine/timeout.js — Runtime timeout, stale-orphan cleanup, steering, and idle checks.
+ *
+ * Live-checkout dispatches (project.worktreeMode === '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.
  */
 
 const fs = require('fs');

package/engine/worktree-pool.js

@@ -79,11 +79,19 @@ function mutateWorktreePool(mutator) {
  */
 function getProjectPoolSize(projectName, config) {
   config = config || {};
+  let proj = null;
   if (projectName && Array.isArray(config.projects)) {
-    const proj = config.projects.find(p => p && p.name === projectName);
-    if (proj && Number.isFinite(Number(proj.worktreePoolSize))) {
-      return Math.max(0, Math.floor(Number(proj.worktreePoolSize)));
-    }
+    proj = config.projects.find(p => p && p.name === projectName) || null;
+  }
+  // P-a3f9b206: short-circuit for live-mode projects. The pool is meaningless
+  // when dispatches run in-place in the operator's local checkout — there is
+  // no "warm" worktree to recycle, and a non-zero pool size could trick the
+  // 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 (proj && Number.isFinite(Number(proj.worktreePoolSize))) {
+    return Math.max(0, Math.floor(Number(proj.worktreePoolSize)));
   }
   const fleet = config.engine?.worktreePoolSize ?? ENGINE_DEFAULTS.worktreePoolSize;
   if (Number.isFinite(Number(fleet))) return Math.max(0, Math.floor(Number(fleet)));

package/engine.js

@@ -1634,9 +1634,9 @@ async function spawnAgent(dispatchItem, config) {
   // stages now short-circuit alongside any other read-only WI (see the gate at
   // `if (branchName && READ_ONLY_ROOT_TASK_TYPES.has(type))` below).
   const _preBranchName = meta?.branch ? sanitizeBranch(meta.branch) : null;
-  let cwd, worktreeRootDir;
+  let cwd, worktreeRootDir, liveMode = false;
   try {
-    ({ cwd, worktreeRootDir } = shared.resolveSpawnPaths(project, type, MINIONS_DIR));
+    ({ cwd, worktreeRootDir, liveMode = false } = shared.resolveSpawnPaths(project, type, MINIONS_DIR));
   } catch (rootErr) {
     if (rootErr?.code === 'WORKTREE_ROOTDIR_COLLAPSED_TO_DRIVE_ROOT' || rootErr?.code === 'WORKTREE_ROOTDIR_MISSING_BASE') {
       log('error', `spawnAgent: project rootDir resolution failed for ${id}: ${rootErr.message}`);
@@ -1836,7 +1836,100 @@ async function spawnAgent(dispatchItem, config) {
     worktreePath = null;
   }
 
-  if (branchName) {
+  // ── Live-checkout mode handling (P-a3f9b204) ─────────────────────────────
+  // When project.worktreeMode === '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
+  // target branch. On dirty refusal we write an inbox alert, stamp
+  // `_pendingReason: 'live_checkout_dirty'` on the WI, complete the dispatch
+  // non-retryably with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, and return — the
+  // engine never runs `git reset`/`git clean` against the operator tree.
+  // On success we fall through; the worktree-creation block below is gated
+  // on `!liveMode`, so it never runs, and downstream cleanup paths
+  // (worktreePool.returnToPool, worktree-gc.gcDispatchWorktreeIfOrphan) are
+  // natural no-ops because worktreePath stays null.
+  // Read-only types short-circuited above (branchName was set to null) and
+  // skip this block — the agent already runs read-only in cwd=localPath in
+  // both isolated and live mode, so no in-place branch checkout is needed.
+  if (liveMode && branchName && !READ_ONLY_ROOT_TASK_TYPES.has(type)) {
+    const _liveMainRef = sanitizeBranch(shared.resolveMainBranch(cwd, project.mainBranch));
+    const _wiIdForAlert = meta?.item?.id || id;
+    const _liveCheckout = require('./engine/live-checkout');
+    let _liveResult;
+    try {
+      _liveResult = await _liveCheckout.prepareLiveCheckout({
+        localPath: cwd,
+        branchName,
+        mainRef: _liveMainRef,
+        gitOpts: _gitOpts,
+        dispatchId: id,
+        wiId: _wiIdForAlert,
+        log: (msg, lvl) => log(lvl || 'info', msg),
+      });
+    } catch (liveErr) {
+      log('error', `spawnAgent: live-checkout helper failed for ${id}: ${liveErr.message}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        `live-checkout failed: ${liveErr.message}`.slice(0, 800),
+        'Live-checkout helper threw before agent spawn; non-retryable until the underlying git state or invocation is fixed.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'dirty') {
+      const _dirtyFiles = Array.isArray(_liveResult.dirtyFiles) ? _liveResult.dirtyFiles : [];
+      const _alertBody = [
+        '# Live-checkout refused: dirty worktree',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**Branch:** ${branchName}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine refused to spawn the agent because \`${cwd}\` has uncommitted changes. Live-checkout mode runs in your project directly — the engine never \`git reset\` or \`git clean\` your tree.`,
+        '',
+        '## Dirty files (`git status --porcelain`)',
+        '',
+        '```',
+        ...(_dirtyFiles.length > 0 ? _dirtyFiles : ['(none reported)']),
+        '```',
+        '',
+        'Recovery: commit, stash, or discard the changes in the project checkout, then re-dispatch the work item.',
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-dirty-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = 'live_checkout_dirty';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      log('error', `spawnAgent: live-checkout refused for ${id}: ${_dirtyFiles.length} dirty file(s) in ${cwd}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        `live-checkout refused: ${_dirtyFiles.length} dirty file(s) in ${cwd}`.slice(0, 800),
+        'Live-checkout mode requires a clean tree; engine refuses to overwrite operator changes. Commit/stash/discard and re-dispatch.',
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_DIRTY, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
+    log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
+  }
+
+  if (branchName && !liveMode) {
     updateAgentStatus(id, AGENT_STATUS.WORKTREE_SETUP, `Setting up worktree for branch ${branchName}`);
     // W-mpwy3mp5 (#2996): track whether we ended up reusing an existing
     // worktree (rather than creating a fresh one) so the post-setup dirty/
@@ -1901,7 +1994,14 @@ async function spawnAgent(dispatchItem, config) {
       const _isSharedForPool = meta?.branchStrategy === 'shared-branch' || meta?.useExistingBranch;
       const _poolProject = project.name || 'default';
       const _poolSize = worktreePool.getProjectPoolSize(_poolProject, config);
-      if (_poolSize > 0 && !_isSharedForPool && branchName) {
+      // P-a3f9b206: belt-and-braces `!liveMode` gate. The borrow block lives
+      // inside the `if (branchName && !liveMode)` worktree-create gate from
+      // P-a3f9b204, so liveMode dispatches already skip it; this duplicates
+      // the check so a future refactor that hoists the borrow out of the
+      // create block still excludes live-mode projects. Combined with the
+      // worktree-pool `getProjectPoolSize` short-circuit, the pool is
+      // unreachable from three layers for live-mode dispatches.
+      if (_poolSize > 0 && !_isSharedForPool && branchName && !liveMode) {
         let _branchOnRemote = true;
         try {
           await shared.shellSafeGit(
@@ -8222,6 +8322,26 @@ async function tickInner() {
   for (const d of (dispatch.active || [])) {
     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
+  // 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
+  // excluded — they get a fresh worktree per dispatch and are naturally
+  // safe.
+  const liveProjectsInUse = new Set();
+  for (const d of (dispatch.active || [])) {
+    if (READ_ONLY_ROOT_TASK_TYPES.has(d.type)) continue;
+    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) {
+      liveProjectsInUse.add(projName);
+    }
+  }
   const seenPendingIds = new Set();
   const toDispatch = [];
   let generalSlots = slotsAvailable;
@@ -8367,11 +8487,38 @@ async function tickInner() {
     // Branch mutex: skip items targeting a branch already locked by an active or newly-dispatched task
     const itemBranch = item.meta?.branch ? sanitizeBranch(item.meta.branch) : null;
     if (itemBranch && lockedBranches.has(itemBranch)) continue;
+    // P-a3f9b205: Per-project mutating-concurrency gate. Two concurrent
+    // mutating dispatches against the same live-mode project would step on
+    // each other in the operator's localPath, so cap at 1 per project.
+    // The branch-mutex check above is the more-specific reason when both
+    // apply (same project + same branch), which is why this gate runs
+    // AFTER it.
+    const itemProjName = item.project || item.meta?.project?.name || null;
+    if (
+      itemProjName
+      && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
+      && liveProjectsInUse.has(itemProjName)
+    ) {
+      item._pendingReason = 'live_checkout_busy';
+      continue;
+    }
     if (generalSlots <= 0) continue;
     seenPendingIds.add(item.id);
     toDispatch.push(item);
     busyAgents.add(item.agent);
     if (itemBranch) lockedBranches.add(itemBranch);
+    // Track this project as in-use so subsequent pending items in the same
+    // tick hit the gate above. The seed loop already captured cross-tick
+    // active dispatches; this line covers within-tick fan-out.
+    if (
+      itemProjName
+      && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
+    ) {
+      const projCfg = shared.findProjectByName(shared.getProjects(config), itemProjName);
+      if (projCfg && projCfg.worktreeMode === shared.WORKTREE_MODES.LIVE) {
+        liveProjectsInUse.add(itemProjName);
+      }
+    }
     generalSlots--;
   }
 
@@ -8437,6 +8584,19 @@ async function tickInner() {
   for (const d of (postDispatch.active || [])) {
     if (d.meta?.branch) postLockedBranches.add(sanitizeBranch(d.meta.branch));
   }
+  // P-a3f9b205: Rebuild the per-project live-mode mutating set from the
+  // post-dispatch active list so the annotation loop's reason is consistent
+  // with whatever actually got spawned this tick.
+  const postLiveProjectsInUse = new Set();
+  for (const d of (postDispatch.active || [])) {
+    if (READ_ONLY_ROOT_TASK_TYPES.has(d.type)) continue;
+    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) {
+      postLiveProjectsInUse.add(projName);
+    }
+  }
   let skipReasonChanged = false;
   for (const item of (postDispatch.pending || [])) {
     let reason = null;
@@ -8449,6 +8609,18 @@ async function tickInner() {
       const pendingBranch = item.meta?.branch ? sanitizeBranch(item.meta.branch) : null;
       if (pendingBranch && postLockedBranches.has(pendingBranch)) {
         reason = 'branch_locked';
+      } else {
+        // P-a3f9b205: surface the per-project live-mode gate. Order matters:
+        // max_concurrency / agent_busy / branch_locked are all more specific
+        // and win when both apply.
+        const itemProjName = item.project || item.meta?.project?.name || null;
+        if (
+          itemProjName
+          && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
+          && postLiveProjectsInUse.has(itemProjName)
+        ) {
+          reason = 'live_checkout_busy';
+        }
       }
     }
     // Track when item first became blocked on a busy agent for reassignment threshold
@@ -8467,6 +8639,22 @@ async function tickInner() {
       item.skipReason = reason;
       skipReasonChanged = true;
     }
+    // P-a3f9b205: mirror _pendingReason for live_checkout_busy so the
+    // dashboard's pending-reason chip surfaces the value (it reads
+    // _pendingReason, not skipReason). Only the live-mode gate flows
+    // through _pendingReason here — other reasons keep their existing
+    // semantics (max_concurrency / agent_busy / branch_locked already
+    // have their own _pendingReason owners earlier in the tick).
+    if (reason === 'live_checkout_busy') {
+      if (item._pendingReason !== 'live_checkout_busy') {
+        item._pendingReason = 'live_checkout_busy';
+        skipReasonChanged = true;
+      }
+    } else if (item._pendingReason === 'live_checkout_busy') {
+      // Gate cleared — drop the stale pending reason so the chip clears.
+      delete item._pendingReason;
+      skipReasonChanged = true;
+    }
   }
   if (skipReasonChanged) {
     if (_isTickStale(myGeneration)) return;

package/package.json

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