@yemi33/minions 0.1.2379 → 0.1.2381

package/bin/minions.js

@@ -1404,9 +1404,21 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   // PowerShell is unavailable, the engine is hung, or its cmdline doesn't match.
   const oldEnginePid = readEnginePid(MINIONS_HOME);
   try { execSync(`node "${path.join(MINIONS_HOME, 'engine.js')}" stop`, { stdio: 'ignore', cwd: MINIONS_HOME, timeout: 10000, windowsHide: true }); } catch {}
-  // Force-kill the recorded engine PID (NOT the tree — agent children must
-  // survive so the new engine can re-attach them via PID files).
-  killPidOnly(oldEnginePid);
+  // Give the engine's graceful handler time to drain non-reattachable pooled
+  // leases. Detached cold agents are not part of that drain and remain alive
+  // for normal PID-file reattachment by the replacement engine.
+  const shutdownTimeout = (() => {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(MINIONS_HOME, 'config.json'), 'utf8'));
+      return Number(cfg?.engine?.shutdownTimeout) || shared.ENGINE_DEFAULTS.shutdownTimeout;
+    } catch { return shared.ENGINE_DEFAULTS.shutdownTimeout; }
+  })();
+  const gracefulEngineStop = waitForPidDeath(oldEnginePid, shutdownTimeout + 5000);
+  if (!gracefulEngineStop.ok) {
+    // Fallback for a hung engine. Kill only the engine PID, never its detached
+    // cold-agent children; pooled leases have already exceeded their drain budget.
+    killPidOnly(oldEnginePid);
+  }
   killByPort(restartResolved.port);
   killMinionsProcesses(['engine.js', 'dashboard.js', 'supervisor.js']);
   // Confirm the OS finished the asynchronous termination before we spawn new
@@ -1491,15 +1503,13 @@ ${fs.existsSync(path.join(PKG_ROOT, '.git')) ? `
   const engineDir = path.join(MINIONS_HOME, 'engine');
 
   // Engine state
-  for (const f of ['dispatch.json', 'control.json', 'log.json', 'metrics.json', 'cooldowns.json', 'schedule-runs.json', 'kb-checkpoint.json', 'cc-session.json', 'doc-sessions.json', 'pipeline-runs.json']) rm(path.join(engineDir, f));
+  require(path.join(PKG_ROOT, 'engine', 'db')).cleanupRetiredJsonFiles(MINIONS_HOME);
+  for (const f of ['state.db', 'state.db-wal', 'state.db-shm', 'control.json', 'kb-checkpoint.json']) {
+    rm(path.join(engineDir, f));
+  }
   glob(engineDir, /^pid-.*\.pid$/).forEach(rm);
   rmDir(path.join(engineDir, 'tmp'));
 
-  // Work items + PRs
-  rm(path.join(MINIONS_HOME, 'work-items.json'));
-  rm(path.join(MINIONS_HOME, 'work-items-archive.json'));
-  rm(path.join(MINIONS_HOME, 'pull-requests.json'));
-
   // Plans + PRDs + Pipelines + Meetings
   rmDir(path.join(MINIONS_HOME, 'plans'));
   rmDir(path.join(MINIONS_HOME, 'prd'));

package/dashboard/js/refresh.js

@@ -138,7 +138,7 @@ const RENDER_VERSIONS = {
   // Bumped 4→5 for the clickable checkout-mode pill + picker (W-mr1b67zi0006b788).
   // Bumped 5→6 for multi-select hybrid liveValidation.type support (W-mr2m1ute000a9c01).
   // Bumped 6→7 for the liveValidation.autoDispatch toggle + pill "· auto-validate" suffix (W-mr2q361a00097e5c).
-  projects: 7,
+  projects: 9,
   notes: 1,
   prd: 3,
   prs: 3,
@@ -151,9 +151,8 @@ const RENDER_VERSIONS = {
   dispatch: 2,
   engineLog: 2,
   metrics: 1,
-  // Bumped 7→8: WI detail modal's branch pill moved out of the Artifacts
-  // chip row into its own non-interactive "Branch" field (W-mr2qjr3b0002522f).
-  workItems: 8,
+  // Bumped 8->9: row actions now preserve work-item source scope when IDs collide.
+  workItems: 9,
   skills: 1,
   commands: 1,
   mcpServers: 1,

package/dashboard/js/render-other.js

@@ -105,13 +105,13 @@ function _renderProjectBranch(p) {
 // "Live checkout" (live — agents run in-place inside the operator's working
 // 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 worktree pill.
+// dispatch per project, with configurable dirty-tree recovery) so it gets a
+// more prominent color than the muted worktree pill.
 //
 // Hybrid live-validation: when checkoutMode is 'live' AND p.liveValidationType
-// is set, coding WIs author in isolated worktrees and only the named validation
-// type runs in-place on the live checkout. This is a materially different
-// dispatch profile from full-live, so it gets its own pill.
+// is set, only selected WI types run in-place and all others use isolated
+// worktrees. This is a materially different dispatch profile from full-live,
+// so it gets its own pill.
 // W-mr1b67zi0006b788: the pill is clickable — opens an inline picker (see
 // _openCheckoutModeMenu below) to switch between Worktrees / Live checkout /
 // Hybrid dispatch modes without leaving the Projects view. Shared
@@ -125,6 +125,10 @@ function _renderWorktreeModePill(p) {
   const common = ' data-checkout-pill="' + name + '" role="button" tabindex="0" aria-haspopup="true" aria-label="Change checkout mode"';
   if (p.checkoutMode === 'live') {
     const types = _liveValidationTypesArray(p);
+    if (p.liveValidationInvalid) {
+      const effectiveTypes = types.length > 0 ? types.join(', ') : 'none';
+      return ' <span class="project-mode-pill project-mode-hybrid project-mode-pill-clickable project-warn"' + common + ' title="Invalid hybrid configuration — unsupported settings are ignored. Effective live work-item types: ' + escHtml(effectiveTypes) + '. Click to repair.">⚠ Hybrid · invalid</span>';
+    }
     if (types.length > 0) {
       const typesText = types.join(', ');
       const vt = escapeHtml(typesText);
@@ -134,20 +138,19 @@ function _renderWorktreeModePill(p) {
       const autoDispatch = p.liveValidationAutoDispatch === true;
       const autoSuffix = autoDispatch ? ' · auto-validate' : '';
       const autoTitleBit = autoDispatch
-        ? ' A validation work item is automatically dispatched after each coding work item completes.'
-        : ' Auto-validation is OFF — validation must be dispatched manually after each coding work item completes.';
-      return ' <span class="project-mode-pill project-mode-hybrid project-mode-pill-clickable"' + common + ' title="Hybrid live-validation — coding work items author in isolated worktrees; only the &quot;' + vt + '&quot; validation type(s) run in-place on the live checkout (capped to one mutating dispatch, refused on a dirty tree).' + escHtml(autoTitleBit) + ' Click to change.">⚡ Hybrid · ' + vt + escHtml(autoSuffix) + '</span>';
+        ? ' A test work item is automatically dispatched after each eligible coding work item completes.'
+        : ' Auto-validation is OFF — validation must be dispatched manually.';
+      return ' <span class="project-mode-pill project-mode-hybrid project-mode-pill-clickable"' + common + ' title="Hybrid dispatch — only the &quot;' + vt + '&quot; work-item type(s) run in-place; all others use isolated worktrees. Live work is capped to one mutating dispatch, and dirty-tree handling follows the configured auto-stash/reset policy.' + escHtml(autoTitleBit) + ' Click to change.">⚡ Hybrid · ' + vt + escHtml(autoSuffix) + '</span>';
     }
-    return ' <span class="project-mode-pill project-mode-live project-mode-pill-clickable"' + common + ' 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. Click to change.">⚡ Live checkout</span>';
+    return ' <span class="project-mode-pill project-mode-live project-mode-pill-clickable"' + common + ' title="Live-checkout dispatch mode — agents run in-place inside the project working tree (no isolated worktree); capped to one mutating dispatch. Dirty-tree handling follows the configured auto-stash/reset policy. Click to change.">⚡ Live checkout</span>';
   }
   return ' <span class="project-mode-pill project-mode-isolated project-mode-pill-clickable"' + common + ' title="Worktree dispatch mode (default) — each agent runs in its own git worktree. Click to change.">Worktrees</span>';
 }
 
-// Work-item types eligible for hybrid live-validation (W-mr1b67zi0006b788).
-// Mirrors the set the server documents for project.liveValidation.type;
-// intentionally excludes the illustrative "build-and-test" example from the
-// server comments since that isn't a real WORK_TYPE value.
-const CHECKOUT_MODE_HYBRID_TYPES = ['implement', 'fix', 'docs', 'decompose', 'explore', 'ask', 'review', 'test', 'verify', 'setup'];
+// Canonical work-item types that can meaningfully use the live checkout.
+// Read-only root tasks are omitted because hybrid routing cannot change where
+// they run. `build-and-test` is a playbook alias; `test` is the WI type.
+const CHECKOUT_MODE_HYBRID_TYPES = ['test', 'implement', 'implement:large', 'fix', 'build-fix-complex', 'docs', 'decompose', 'review', 'verify', 'setup'];
 const CHECKOUT_MODE_HYBRID_DEFAULT_TYPE = 'test';
 
 function _findProjectInLastStatus(name) {
@@ -230,9 +233,10 @@ function _openCheckoutModeMenu(projectName, anchorEl) {
       desc.textContent = descText;
       item.appendChild(desc);
     }
+    const liveTypes = _liveValidationTypesArray(project);
     const isActive = (mode === 'worktree' && project.checkoutMode !== 'live')
-      || (mode === 'live' && project.checkoutMode === 'live' && _liveValidationTypesArray(project).length === 0)
-      || (mode === 'hybrid' && project.checkoutMode === 'live' && _liveValidationTypesArray(project).length > 0);
+      || (mode === 'live' && project.checkoutMode === 'live' && liveTypes.length === 0 && !project.liveValidationInvalid)
+      || (mode === 'hybrid' && project.checkoutMode === 'live' && (liveTypes.length > 0 || project.liveValidationInvalid));
     if (isActive) {
       item.setAttribute('aria-checked', 'true');
       item.classList.add('checkout-mode-menu-item-active');
@@ -254,8 +258,8 @@ function _openCheckoutModeMenu(projectName, anchorEl) {
   }
 
   addItem('Worktrees (default)', 'worktree', 'Each dispatch runs in its own isolated git worktree. Fully parallel, never touches your working directory.');
-  addItem('Live checkout', 'live', 'Agents run in-place in the project folder. One mutating dispatch at a time; refuses to run on a dirty tree.');
-  addItem('Hybrid dispatch…', 'hybrid', 'Coding work authors in isolated worktrees; only a chosen validation step (e.g. build-and-test) runs on the real checkout.');
+  addItem('Live checkout', 'live', 'Agents run in-place in the project folder. One mutating dispatch at a time; dirty-tree handling follows the auto-stash/reset policy.');
+  addItem('Hybrid dispatch…', 'hybrid', 'Only chosen work-item types (normally test) use the real checkout; all others use isolated worktrees.');
 
   document.body.appendChild(menu);
   const rect = anchorEl.getBoundingClientRect();
@@ -286,7 +290,7 @@ function _renderCheckoutModeHybridStep(menu, projectName) {
 
   const label = document.createElement('div');
   label.className = 'checkout-mode-menu-item';
-  label.textContent = 'Work-item type(s) to validate live:';
+  label.textContent = 'Work-item type(s) to run live:';
   menu.appendChild(label);
 
   const currentTypes = _liveValidationTypesArray(project);
@@ -325,10 +329,23 @@ function _renderCheckoutModeHybridStep(menu, projectName) {
   autoDispatchCb.className = 'checkout-mode-menu-checkbox checkout-mode-menu-autodispatch-checkbox';
   autoDispatchCb.checked = project.liveValidationAutoDispatch === true;
   const autoDispatchText = document.createElement('span');
-  autoDispatchText.textContent = 'Automatically validate after each coding work item completes';
+  autoDispatchText.textContent = 'Automatically run a test validation after each eligible coding work item completes';
   autoDispatchRow.appendChild(autoDispatchCb);
   autoDispatchRow.appendChild(autoDispatchText);
   menu.appendChild(autoDispatchRow);
+  const testTypeCheckbox = checkboxes.find(function(cb) {
+    return cb.value === CHECKOUT_MODE_HYBRID_DEFAULT_TYPE;
+  });
+  function syncAutoDispatchType() {
+    if (autoDispatchCb.checked && testTypeCheckbox) testTypeCheckbox.checked = true;
+  }
+  autoDispatchCb.addEventListener('change', syncAutoDispatchType);
+  if (testTypeCheckbox) {
+    testTypeCheckbox.addEventListener('change', function() {
+      if (!testTypeCheckbox.checked) autoDispatchCb.checked = false;
+    });
+  }
+  syncAutoDispatchType();
 
   const actions = document.createElement('div');
   actions.className = 'checkout-mode-menu-actions';
@@ -349,9 +366,9 @@ function _renderCheckoutModeHybridStep(menu, projectName) {
   applyBtn.className = 'checkout-mode-menu-btn checkout-mode-menu-btn-primary';
   applyBtn.textContent = 'Apply';
   applyBtn.addEventListener('click', function() {
+    const autoDispatch = autoDispatchCb.checked;
     const types = checkboxes.filter(function(cb) { return cb.checked; }).map(function(cb) { return cb.value; });
     if (types.length === 0) return; // require at least one selected type
-    const autoDispatch = autoDispatchCb.checked;
     _closeCheckoutModeMenu();
     _applyCheckoutModeChange(projectName, 'live', types, autoDispatch);
   });
@@ -392,8 +409,8 @@ async function _applyCheckoutModeChange(projectName, newMode, liveValidationType
   // explicitly in the confirm message rather than burying it in the label.
   const autoDispatchNote = typesForLabel.length > 0
     ? (autoDispatchOn
-      ? ' Auto-validation will be turned ON — a validation work item will be dispatched automatically after each coding work item completes, and coding agents will skip local builds/tests.'
-      : ' Auto-validation will be OFF — you will need to dispatch validation manually after each coding work item completes.')
+      ? ' Auto-validation will be turned ON — a test work item will be dispatched automatically after each eligible coding work item completes, and eligible coding agents will skip local builds/tests.'
+      : ' Auto-validation will be OFF — you will need to dispatch validation manually.')
     : '';
   const ok = await confirmDialog({
     title: 'Change checkout mode?',
@@ -407,12 +424,14 @@ async function _applyCheckoutModeChange(projectName, newMode, liveValidationType
   const prevMode = project.checkoutMode;
   const prevType = project.liveValidationType;
   const prevAutoDispatch = project.liveValidationAutoDispatch;
+  const prevInvalid = project.liveValidationInvalid;
   const nextType = (newMode === 'live' && liveValidationType) ? liveValidationType : null;
   // Optimistic flip BEFORE awaiting the API call (per dashboard convention —
   // see projectChipRemove / removePinnedNote); reverted in the catch below.
   project.checkoutMode = newMode;
   project.liveValidationType = nextType;
   project.liveValidationAutoDispatch = nextType ? autoDispatchOn : false;
+  project.liveValidationInvalid = false;
   if (window._lastStatus && Array.isArray(window._lastStatus.projects)) renderProjects(window._lastStatus.projects);
 
   try {
@@ -434,6 +453,7 @@ async function _applyCheckoutModeChange(projectName, newMode, liveValidationType
     project.checkoutMode = prevMode;
     project.liveValidationType = prevType;
     project.liveValidationAutoDispatch = prevAutoDispatch;
+    project.liveValidationInvalid = prevInvalid;
     if (window._lastStatus && Array.isArray(window._lastStatus.projects)) renderProjects(window._lastStatus.projects);
     showToast('cmd-toast', 'Failed to update checkout mode: ' + (err && err.message || err), false);
   }

package/dashboard/js/render-prd.js

@@ -855,7 +855,7 @@ async function prdItemEdit(source, itemId) {
 
     completionHtml = '<div style="background:var(--surface);border:1px solid var(--border);border-left:3px solid ' + statusColor + ';border-radius:4px;padding:10px 12px;margin-bottom:12px">' +
       '<div style="display:flex;align-items:center;gap:8px;margin-bottom:6px">' +
-        (wi ? '<a href="#" onclick="event.preventDefault();event.stopPropagation();openWorkItemDetail(\'' + escHtml(wi.id) + '\')" title="Open ' + escHtml(wi.id) + ' detail" style="font-size:var(--text-base);font-weight:700;color:' + statusColor + ';text-decoration:none;cursor:pointer" onmouseover="this.style.textDecoration=\'underline\'" onmouseout="this.style.textDecoration=\'none\'">' + statusLabel + ' &rarr;</a>' : '<span style="font-size:var(--text-base);font-weight:700;color:' + statusColor + '">' + statusLabel + '</span>') +
+        (wi ? '<a href="#" onclick="event.preventDefault();event.stopPropagation();openWorkItemDetail(\'' + escHtml(wi.id) + '\',\'' + escHtml(wi._source || '') + '\')" title="Open ' + escHtml(wi.id) + ' detail" style="font-size:var(--text-base);font-weight:700;color:' + statusColor + ';text-decoration:none;cursor:pointer" onmouseover="this.style.textDecoration=\'underline\'" onmouseout="this.style.textDecoration=\'none\'">' + statusLabel + ' &rarr;</a>' : '<span style="font-size:var(--text-base);font-weight:700;color:' + statusColor + '">' + statusLabel + '</span>') +
         typePillHtml +
         (agent ? '<span style="font-size:var(--text-base);color:var(--muted)">by ' + escHtml(agent) + '</span>' : '') +
         (completedAt ? '<span style="font-size:var(--text-sm);color:var(--muted)">' + escHtml(completedAt.slice(0, 16).replace('T', ' ')) + '</span>' : '') +

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

@@ -192,7 +192,7 @@ function wiRow(item) {
     var prLabel = prNumMatch ? ('PR #' + prNumMatch[1]) : 'parent PR';
     followupChip = ' <a class="pr-badge draft" style="font-size:var(--text-xs);text-decoration:none" target="_blank" rel="noopener" href="' + escapeHtml(prFollowup.parent_pr_url) + '" title="Follow-up dispatched from ' + escapeHtml(prRef) + (prFollowup.parent_comment_author ? ' by ' + escapeHtml(prFollowup.parent_comment_author) : '') + '" onclick="event.stopPropagation()">&#8617; from ' + escapeHtml(prLabel) + '</a>';
   }
-  return '<tr data-wi-id="' + escapeHtml(item.id) + '" style="cursor:pointer" onclick="if(shouldIgnoreSelectionClick(event))return;openWorkItemDetail(\'' + escapeHtml(item.id) + '\')">' +
+  return '<tr data-wi-id="' + escapeHtml(item.id) + '" style="cursor:pointer" onclick="if(shouldIgnoreSelectionClick(event))return;openWorkItemDetail(\'' + escapeHtml(item.id) + '\',\'' + escapeHtml(item._source || '') + '\')">' +
     '<td style="min-width:280px;max-width:320px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escapeHtml((item.title || '').slice(0, 200)) + '">' + escapeHtml(item.title || '') + followupChip + '</td>' +
     '<td><span style="font-size:var(--text-sm);color:var(--muted)">' + escapeHtml(item._source || '') + '</span>' +
       (item.scope === 'fan-out' ? ' <span class="pr-badge ' + (item.status === 'done' || item.status === 'failed' ? 'draft' : 'building') + '" style="font-size:var(--text-xs)">fan-out</span>' : '') + '</td>' +
@@ -312,7 +312,8 @@ function renderWorkItems(items, opts) {
 }
 
 async function editWorkItem(id, source) {
-  const cached = allWorkItems.find(i => i.id === id);
+  source = source || '';
+  const cached = allWorkItems.find(i => i.id === id && (!source || i._source === source));
   if (!cached) return;
   // Hydrate the full record before rendering the form. The bulk
   // /api/work-items list endpoint truncates `description` and replaces
@@ -331,7 +332,7 @@ async function editWorkItem(id, source) {
     (cached.referencesCount > 0 && !Array.isArray(cached.references));
   if (needsHydration) {
     try {
-      const r = await fetch('/api/work-items/' + encodeURIComponent(id));
+      const r = await fetch('/api/work-items/' + encodeURIComponent(id) + '?source=' + encodeURIComponent(source));
       if (!r.ok) throw new Error('HTTP ' + r.status);
       const data = await r.json();
       const full = data && data.item;
@@ -972,9 +973,15 @@ function _wiRenderDetail(item) {
   return html;
 }
 
-function openWorkItemDetail(id) {
+function openWorkItemDetail(id, source) {
   if (window.getSelection && window.getSelection().toString().length > 0) return;
-  const cached = allWorkItems.find(i => i.id === id);
+  source = source || '';
+  const matches = allWorkItems.filter(i => i.id === id && (!source || i._source === source));
+  if (!source && matches.length > 1) {
+    alert('Multiple work items share this ID. Open it from the Work Items page to select the project.');
+    return;
+  }
+  const cached = matches[0];
   if (!cached) return;
 
   // Render the modal immediately from the cached (slim) record so the click
@@ -999,7 +1006,7 @@ function openWorkItemDetail(id) {
 
   if (!needsHydration) return;
 
-  fetch('/api/work-items/' + encodeURIComponent(id))
+  fetch('/api/work-items/' + encodeURIComponent(id) + '?source=' + encodeURIComponent(source))
     .then(function(r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.json(); })
     .then(function(data) {
       // Guard against modal navigation away from this WI during the fetch.

package/dashboard/js/settings.js

@@ -277,16 +277,18 @@ async function openSettings() {
     // (honors the legacy worktreeMode field). Chip is hidden by default and
     // toggled reactively below.
     // W-mr9mx93d000x1dda — third option "Hybrid dispatch": checkoutMode:'live'
-    // PLUS a liveValidation block (coding WIs author in isolated worktrees; only
-    // the chosen validation type(s) run in-place on the live checkout, with an
-    // optional auto-dispatch-after-coding toggle). This mirrors the Projects-bar
+    // PLUS a liveValidation block (only chosen work-item types run in-place;
+    // all others use isolated worktrees, with an optional test auto-dispatch
+    // after eligible coding work). This mirrors the Projects-bar
     // picker (render-other.js _openCheckoutModeMenu / _renderCheckoutModeHybridStep)
     // so both surfaces configure the SAME liveValidation shape identically.
     var currentWtMode = (p.checkoutMode === 'live') ? 'live' : 'worktree';
     var lvTypes = (window._liveValidationTypesArray ? window._liveValidationTypesArray(p) : []);
-    // 3-way UI mode: worktree / live / hybrid. Hybrid = live + >=1 validation type.
+    // 3-way UI mode: worktree / live / hybrid. Keep invalid persisted hybrid
+    // blocks in the hybrid editor so saving can repair rather than hide them as
+    // full-live.
     var currentCheckoutMode = (currentWtMode === 'live')
-      ? (lvTypes.length > 0 ? 'hybrid' : 'live')
+      ? ((lvTypes.length > 0 || p.liveValidationInvalid) ? 'hybrid' : 'live')
       : 'worktree';
     var hybridTypes = window.CHECKOUT_MODE_HYBRID_TYPES || [];
     var hybridDefaultType = window.CHECKOUT_MODE_HYBRID_DEFAULT_TYPE || 'test';
@@ -303,26 +305,26 @@ async function openSettings() {
     var hybridPanel =
       '<div data-checkout-hybrid-panel="' + escHtml(p.name) + '" style="' + (currentCheckoutMode === 'hybrid' ? '' : 'display:none;') + 'margin-top:6px">' +
         '<div style="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;margin-bottom:6px">' +
-          '⚠ Hybrid mode: coding work items author in isolated worktrees; only the chosen validation type(s) run in-place on the live checkout (one mutating dispatch at a time; refused on a dirty tree).' +
+          '⚠ Hybrid mode: only the chosen work-item type(s) run in-place on the live checkout; all others use isolated worktrees (one mutating dispatch at a time; dirty-tree recovery follows the live-checkout auto-stash/reset settings).' +
         '</div>' +
-        '<div style="font-size:var(--text-sm);color:var(--muted);margin-bottom:2px">Work-item type(s) to validate live:</div>' +
+        '<div style="font-size:var(--text-sm);color:var(--muted);margin-bottom:2px">Work-item type(s) to run live:</div>' +
         '<div style="margin-bottom:4px">' + hybridTypeChecks + '</div>' +
         '<label style="display:inline-flex;align-items:center;gap:6px;font-size:var(--text-sm);color:var(--text);margin-top:2px">' +
           '<input type="checkbox" id="set-liveValidationAutoDispatch-' + escHtml(p.name) + '"' + (hybridAutoPre ? ' checked' : '') + '>' +
-          '<span>Automatically validate after each coding work item completes</span>' +
+          '<span>Automatically run a test validation after each eligible coding work item completes</span>' +
         '</label>' +
-        '<div data-checkout-hybrid-error="' + escHtml(p.name) + '" style="display:none;margin-top:6px;color:var(--red);font-size:var(--text-xs)">Select at least one work-item type to validate live.</div>' +
+        '<div data-checkout-hybrid-error="' + escHtml(p.name) + '" style="display:none;margin-top:6px;color:var(--red);font-size:var(--text-xs)">Select at least one work-item type to run live.</div>' +
       '</div>';
     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">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" title="Each dispatch runs in its own isolated git worktree. Fully parallel, never touches your working directory."' + (currentCheckoutMode === 'worktree' ? ' selected' : '') + '>Worktree (default)</option>' +
-          '<option value="live" title="Agents run in-place in the project folder. One mutating dispatch at a time; refuses to run on a dirty tree."' + (currentCheckoutMode === 'live' ? ' selected' : '') + '>Live checkout</option>' +
-          '<option value="hybrid" title="Coding work authors in isolated worktrees; only a chosen validation step runs on the real checkout."' + (currentCheckoutMode === 'hybrid' ? ' selected' : '') + '>Hybrid dispatch</option>' +
+          '<option value="live" title="Agents run in-place in the project folder. One mutating dispatch at a time; dirty-tree handling follows the auto-stash/reset policy."' + (currentCheckoutMode === 'live' ? ' selected' : '') + '>Live checkout</option>' +
+          '<option value="hybrid" title="Only chosen work-item types run on the real checkout; all others use isolated worktrees."' + (currentCheckoutMode === 'hybrid' ? ' selected' : '') + '>Hybrid dispatch</option>' +
         '</select>' +
         '<div data-checkout-mode-chip="' + escHtml(p.name) + '" style="' + (currentCheckoutMode === '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.' +
+          '⚠ Live mode: dispatches run directly in this repo\'s checkout. Only one mutating dispatch runs at a time. Dirty-tree behavior follows the auto-stash/reset settings below.' +
         '</div>' +
         hybridPanel +
       '</div>';
@@ -774,6 +776,17 @@ async function openSettings() {
       if (hybridPanel) hybridPanel.style.display = (sel.value === 'hybrid') ? '' : 'none';
     });
   });
+  document.querySelectorAll('[id^="set-liveValidationAutoDispatch-"]').forEach(function(autoDispatch) {
+    autoDispatch.addEventListener('change', function() {
+      if (!autoDispatch.checked) return;
+      const projectName = autoDispatch.id.slice('set-liveValidationAutoDispatch-'.length);
+      const esc = (window.CSS && CSS.escape ? CSS.escape(projectName) : projectName);
+      const testType = document.querySelector(
+        '[data-live-validation-type="' + esc + '"][value="test"]',
+      );
+      if (testType) testType.checked = true;
+    });
+  });
 }
 
 // Lazily open/close the per-agent charter editor in the Settings Agents table.
@@ -1244,13 +1257,23 @@ async function saveSettings() {
         const types = [];
         typeEls.forEach(function(el) { if (el && el.checked) types.push(el.value); });
         const errEl = document.querySelector('[data-checkout-hybrid-error="' + esc + '"]');
+        const autoEl = document.getElementById('set-liveValidationAutoDispatch-' + p.name);
+        const autoDispatch = autoEl?.checked === true;
         if (types.length === 0) {
-          hybridValidationErrors.push(p.name);
-          if (errEl) errEl.style.display = '';
+          hybridValidationErrors.push(p.name + ': select at least one live type');
+          if (errEl) {
+            errEl.textContent = 'Select at least one work-item type to run live.';
+            errEl.style.display = '';
+          }
+        } else if (autoDispatch && types.indexOf('test') === -1) {
+          hybridValidationErrors.push(p.name + ': auto-validation requires test');
+          if (errEl) {
+            errEl.textContent = 'Automatic validation requires the test type.';
+            errEl.style.display = '';
+          }
         } else {
           if (errEl) errEl.style.display = 'none';
-          const autoEl = document.getElementById('set-liveValidationAutoDispatch-' + p.name);
-          liveValidation = { type: types, autoDispatch: !!(autoEl && autoEl.checked) };
+          liveValidation = { type: types, autoDispatch };
         }
       }
       // W-mqtvnnj1000357fa — per-project live-checkout auto-stash override.
@@ -1280,7 +1303,7 @@ async function saveSettings() {
     });
 
     if (hybridValidationErrors.length > 0) {
-      throw new Error('Hybrid dispatch needs at least one validation work-item type for: ' + hybridValidationErrors.join(', '));
+      throw new Error('Invalid hybrid dispatch configuration: ' + hybridValidationErrors.join(', '));
     }
 
     // Save config