@yemi33/minions 0.1.2380 → 0.1.2381

package/engine/shared.js

@@ -2481,6 +2481,80 @@ function classifyInboxItem(name, content) {
 // 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' });
+const LEGACY_LIVE_VALIDATION_TYPE_ALIASES = Object.freeze({
+  'build-and-test': 'test',
+});
+
+function normalizeLiveValidationWorkType(value) {
+  if (typeof value !== 'string') return '';
+  const type = value.trim();
+  return LEGACY_LIVE_VALIDATION_TYPE_ALIASES[type] || type;
+}
+
+function inspectLiveValidation(value) {
+  if (value === undefined || value === null || value === '') {
+    return { configured: false, types: [], normalizedType: undefined, error: null };
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return {
+      configured: true,
+      types: [],
+      normalizedType: undefined,
+      error: 'Invalid liveValidation: must be an object { type, autoDispatch }.',
+    };
+  }
+
+  const rawType = value.type;
+  const rawTypes = Array.isArray(rawType) ? rawType : [rawType];
+  if (
+    (typeof rawType !== 'string' && !Array.isArray(rawType))
+    || rawTypes.length === 0
+    || !rawTypes.every(type => typeof type === 'string' && type.trim())
+  ) {
+    const accepted = [...LIVE_VALIDATION_WORK_TYPES].sort().join(', ');
+    return {
+      configured: true,
+      types: [],
+      normalizedType: undefined,
+      error: `Invalid liveValidation: "type" is required and must be a non-empty string, or a non-empty array of live-capable work-item types. Accepted values: ${accepted}.`,
+    };
+  }
+
+  const normalizedTypes = [...new Set(rawTypes.map(normalizeLiveValidationWorkType))];
+  const types = normalizedTypes.filter(type => LIVE_VALIDATION_WORK_TYPES.has(type));
+  const invalidTypes = normalizedTypes.filter(type => !LIVE_VALIDATION_WORK_TYPES.has(type));
+  let error = null;
+  if (invalidTypes.length > 0) {
+    const accepted = [...LIVE_VALIDATION_WORK_TYPES].sort().join(', ');
+    error = `Invalid liveValidation type(s): ${invalidTypes.join(', ')}. Accepted values: ${accepted}.`;
+  }
+  if (!error && Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
+    if (typeof value.autoDispatch !== 'boolean') {
+      error = 'Invalid liveValidation: "autoDispatch" must be a boolean.';
+    } else if (value.autoDispatch && !normalizedTypes.includes(WORK_TYPE.TEST)) {
+      error = 'Invalid liveValidation: autoDispatch requires "test" in liveValidation.type so the generated validation work item runs on the live checkout.';
+    }
+  }
+  return {
+    configured: true,
+    types,
+    normalizedType: Array.isArray(rawType) ? normalizedTypes : normalizedTypes[0],
+    error,
+  };
+}
+
+// Return the canonical, live-capable work-item types configured for a hybrid
+// project. Raw config is read defensively because config.json can predate the
+// validator; invalid entries are ignored rather than turning hybrid into full
+// live mode. `build-and-test` is retained as a read-compat alias for `test`.
+function resolveLiveValidationTypes(project) {
+  return inspectLiveValidation(project && project.liveValidation).types;
+}
+
+function isLiveValidationConfigInvalid(project) {
+  const inspection = inspectLiveValidation(project && project.liveValidation);
+  return inspection.configured && !!inspection.error;
+}
 
 // Resolve a project's effective checkout mode, honoring the legacy
 // `worktreeMode` field for back-compat. Reading order:
@@ -2492,37 +2566,37 @@ const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
 //
 // Optional second argument `workItemType` enables liveValidation routing:
 //   If checkoutMode === 'live' AND project.liveValidation is set:
-//     - workItemType matches liveValidation.type → 'live' (validation serialized)
-//     - otherwise → 'worktree' (coding escapes the live cap)
+//     - workItemType matches liveValidation.type → 'live'
+//     - otherwise → 'worktree'
 //   liveValidation without checkoutMode: 'live' is ignored with a warn log.
 function resolveCheckoutMode(project, workItemType) {
   if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
   const canonical = project.checkoutMode;
+  const legacy = project.worktreeMode;
+  let effectiveMode = CHECKOUT_MODES.WORKTREE;
+  if (canonical === CHECKOUT_MODES.LIVE || canonical === CHECKOUT_MODES.WORKTREE) {
+    effectiveMode = canonical;
+  } else if (legacy === 'live') {
+    effectiveMode = CHECKOUT_MODES.LIVE;
+  }
   // liveValidation without checkoutMode: 'live' is a misconfiguration — warn and ignore.
-  if (project.liveValidation && canonical !== CHECKOUT_MODES.LIVE) {
+  if (project.liveValidation && effectiveMode !== CHECKOUT_MODES.LIVE) {
     log('warn', 'resolveCheckoutMode: liveValidation is set but checkoutMode is not "live" — liveValidation ignored',
       { projectName: project.name });
   }
-  if (canonical === CHECKOUT_MODES.LIVE) {
+  if (effectiveMode === CHECKOUT_MODES.LIVE) {
     // Apply liveValidation routing when the block is present and workItemType is provided.
     // liveValidation.type may be a single string (legacy / back-compat) or an
     // array of strings (W-mr2m1ute000a9c01, multi-select hybrid types) —
     // normalize to an array and do a membership check so either shape works.
     if (project.liveValidation && workItemType !== undefined) {
-      const lvTypes = Array.isArray(project.liveValidation.type)
-        ? project.liveValidation.type
-        : [project.liveValidation.type];
-      return lvTypes.includes(workItemType)
+      const lvTypes = resolveLiveValidationTypes(project);
+      return lvTypes.includes(normalizeLiveValidationWorkType(workItemType))
         ? CHECKOUT_MODES.LIVE
         : CHECKOUT_MODES.WORKTREE;
     }
     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;
 }
 
@@ -2538,9 +2612,10 @@ function isLiveCheckoutProject(project) {
 // anything else (undefined / null / string) is treated as unset so the next
 // tier (or the `false` default) decides. When ON and a live-checkout tree is
 // dirty, `engine/live-checkout.js#prepareLiveCheckout` runs
-// `git fetch origin` + `git reset --hard origin/<branch>` instead of refusing
-// with LIVE_CHECKOUT_DIRTY (the reset DISCARDS the operator's uncommitted work,
-// so it is opt-in). Sibling of `resolveCheckoutMode` — pure, no I/O.
+// `git reset --hard HEAD` + `git clean -fd` instead of refusing with
+// LIVE_CHECKOUT_DIRTY. This discards uncommitted tracked and untracked work but
+// preserves the current branch and committed history, so it is opt-in. Sibling
+// of `resolveCheckoutMode` — pure, no I/O.
 function resolveLiveCheckoutAutoReset(project, engine) {
   if (project && typeof project === 'object' && typeof project.liveCheckoutAutoReset === 'boolean') {
     return project.liveCheckoutAutoReset;
@@ -2605,16 +2680,14 @@ function validateCheckoutMode(value) {
 }
 
 // Validate + normalize a per-project `liveValidation` block (hybrid mode).
-// Hybrid = checkoutMode:'live' + liveValidation:{ type, autoDispatch }: coding
-// work items author in isolated worktrees (escaping the live cap) while only
-// work items whose type is IN liveValidation.type run in-place on the live
-// checkout. See resolveCheckoutMode (which routes per work-item type) and
-// docs/live-checkout-mode.md.
+// Hybrid = checkoutMode:'live' + liveValidation:{ type, autoDispatch }: only
+// work items whose type is IN liveValidation.type run in-place; all other types
+// use isolated worktrees. See resolveCheckoutMode and docs/live-checkout-mode.md.
 //
 // `type` may be a single work-item-type string (legacy / back-compat) OR a
 // non-empty array of non-empty-string work-item types
 // (W-mr2m1ute000a9c01 — multi-select hybrid types, e.g. both "implement" and
-// "fix" validate live while other types stay in worktrees). Every reader of
+// "fix" run live while other types stay in worktrees). Every reader of
 // liveValidation.type (resolveCheckoutMode, lifecycle.autoDispatchLiveValidationWi,
 // dashboard project mapper / pill / CC label) must handle BOTH shapes —
 // existing config.json entries with a plain string `type` continue to work
@@ -2623,10 +2696,8 @@ function validateCheckoutMode(value) {
 // Returns:
 //   - undefined → caller should clear the field (empty / null / '' input)
 //   - { type, autoDispatch? } normalized object on success, where `type` is
-//     whatever shape the caller passed in (string stays a string; array stays
-//     a deduped array) — we intentionally do NOT force single-string input
-//     into an array so already-persisted single-type configs round-trip
-//     byte-identical through a Settings save that doesn't touch this field.
+//     the caller's input shape (string stays a string; array stays an array),
+//     with values trimmed, normalized, and deduplicated.
 // Throws HTTP 400 (via _httpError) on malformed input, or when the effective
 // checkout mode is not 'live' (liveValidation is meaningless without it — it is
 // silently ignored at resolve time, so we refuse to persist a misconfiguration).
@@ -2636,45 +2707,15 @@ function validateCheckoutMode(value) {
 // applied so the gate sees the intended final mode.
 function validateLiveValidation(value, opts) {
   if (value === undefined || value === null || value === '') return undefined;
-  if (typeof value !== 'object' || Array.isArray(value)) {
-    throw _httpError(400, 'Invalid liveValidation: must be an object { type, autoDispatch }.');
-  }
+  const inspection = inspectLiveValidation(value);
+  if (inspection.error) throw _httpError(400, inspection.error);
   const checkoutMode = opts && opts.checkoutMode;
   if (checkoutMode !== CHECKOUT_MODES.LIVE) {
     throw _httpError(400, 'liveValidation requires checkoutMode "live" (hybrid mode). Set checkoutMode to "live" first, or clear liveValidation.');
   }
-  const typeErrorMsg = 'Invalid liveValidation: "type" is required and must be a non-empty string, or a non-empty array of non-empty-string work-item types — the work-item type(s) that run on the live checkout (e.g. "build-and-test" or ["implement", "fix"]).';
-  const rawType = value.type;
-  let out;
-  if (typeof rawType === 'string') {
-    const trimmed = rawType.trim();
-    if (!trimmed) throw _httpError(400, typeErrorMsg);
-    out = { type: trimmed };
-  } else if (Array.isArray(rawType)) {
-    if (!rawType.every(t => typeof t === 'string' && t.trim().length > 0)) {
-      throw _httpError(400, typeErrorMsg);
-    }
-    // Dedupe (preserving first-seen order) and cap at the number of distinct
-    // work-item types the engine recognizes — a longer array can only be
-    // full of duplicates or invented types.
-    const deduped = [...new Set(rawType.map(t => t.trim()))];
-    if (deduped.length === 0) throw _httpError(400, typeErrorMsg);
-    if (deduped.length > VALID_WORK_TYPES.size) {
-      throw _httpError(400, `Invalid liveValidation: "type" array has ${deduped.length} entries, more than the ${VALID_WORK_TYPES.size} distinct work-item types the engine recognizes — remove duplicates or invalid types.`);
-    }
-    out = { type: deduped };
-  } else {
-    throw _httpError(400, typeErrorMsg);
-  }
-  // autoDispatch (optional): when true, lifecycle auto-creates a SINGLE
-  // validation WI after each coding WI completes with a PR
-  // (engine/lifecycle.js autoDispatchLiveValidationWi). Even when `type` is a
-  // multi-entry array (which drives checkout ROUTING — the types that run live),
-  // exactly one validation WI is filed, of the canonical `test` type when
-  // configured else the first configured live type. Coerce to a strict
-  // boolean; absent leaves it off so the operator opts in explicitly.
+  const out = { type: inspection.normalizedType };
   if (Object.prototype.hasOwnProperty.call(value, 'autoDispatch')) {
-    out.autoDispatch = !!value.autoDispatch;
+    out.autoDispatch = value.autoDispatch;
   }
   return out;
 }
@@ -3902,6 +3943,15 @@ const WORK_TYPE = {
   BUILD_FIX_COMPLEX: 'build-fix-complex',
 };
 
+const FIX_LIKE_WORK_TYPES = new Set([
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+]);
+
+function isFixLikeWorkType(type) {
+  return FIX_LIKE_WORK_TYPES.has(type);
+}
+
 // Work types whose dispatch path requires a per-project git worktree. The
 // engine's spawnAgent uses the project's `localPath` as the worktree root —
 // without an owning project the rootDir falls back to MINIONS_DIR's parent,
@@ -3940,6 +3990,21 @@ const WORKTREE_REQUIRING_TYPES = new Set([
   WORK_TYPE.DOCS,
 ]);
 
+// Hybrid routing is meaningful only for work types that would otherwise need
+// an isolated project worktree. Read-only root tasks already run from the
+// project/root path and therefore gain nothing from a live-validation entry.
+const LIVE_VALIDATION_WORK_TYPES = new Set(WORKTREE_REQUIRING_TYPES);
+
+function resolveLiveValidationAutoDispatchType(project) {
+  if (!project?.liveValidation || project.liveValidation.autoDispatch !== true) return null;
+  if (resolveCheckoutMode(project) !== CHECKOUT_MODES.LIVE) return null;
+  const inspection = inspectLiveValidation(project.liveValidation);
+  if (inspection.error) return null;
+  return inspection.types.includes(WORK_TYPE.TEST)
+    ? WORK_TYPE.TEST
+    : null;
+}
+
 // W-mpxqkkn300121d21 — Valid `type` strings the materializer will honor when a
 // PRD missing_feature carries one. Excludes orchestration-only types that the
 // plan→PRD→materializer pipeline never produces (PLAN, PLAN_TO_PRD, MEETING)
@@ -7295,7 +7360,12 @@ function classifyPrRefForVerification(prRef, project = null) {
 //   { skipped: true, reason }            — not a pr-requiring type / no ref / no URL / upsert error
 //   { alreadyEnrolled: true, id }        — PR already tracked
 //   { enrolled: true, id, scope }        — newly enrolled
-const _PR_REQUIRING_TYPES = new Set([WORK_TYPE.FIX, WORK_TYPE.REVIEW, WORK_TYPE.TEST]);
+const _PR_REQUIRING_TYPES = new Set([
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+  WORK_TYPE.REVIEW,
+  WORK_TYPE.TEST,
+]);
 function autoEnrollPrFromWorkItem(item, project, minionsDir) {
   if (!item || !_PR_REQUIRING_TYPES.has(item.type)) return { skipped: true, reason: 'not-pr-requiring-type' };
   const prRef = extractStructuredWorkItemPrRef(item);
@@ -8426,7 +8496,7 @@ module.exports = {
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
-  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, WORKTREE_REQUIRING_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
+  WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, isPrdArchived, isDefunctPrd, WORK_TYPE, isFixLikeWorkType, WORKTREE_REQUIRING_TYPES, LIVE_VALIDATION_WORK_TYPES, VALID_WORK_TYPES, resolveWorkItemTypeFromPrdItem, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, BUILD_STATUS, REVIEW_STATUS, FETCH_TIMEOUT_MS, RETRY_DELAY_MS, ADO_TOKEN_REFRESH_MAX_RETRIES, DISPATCH_RESULT, mutateMetrics, mutateWatches, mutateScheduleRuns, mutatePipelineRuns, mutateManagedProcesses, mutateWorktreePool, mutateQaRuns, mutateQaSessions, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject, extractPlanTargetProjects,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   WATCH_STALLED_DEFAULT_TICKS, WATCH_STUCK_STAGE_DEFAULT_TICKS,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
@@ -8546,6 +8616,10 @@ module.exports = {
   CHECKOUT_MODES,
   validateCheckoutMode,
   validateLiveValidation,
+  normalizeLiveValidationWorkType,
+  resolveLiveValidationTypes,
+  isLiveValidationConfigInvalid,
+  resolveLiveValidationAutoDispatchType,
   resolveCheckoutMode,
   isLiveCheckoutProject,
   resolveLiveCheckoutAutoReset,

package/engine.js

@@ -2711,7 +2711,7 @@ async function spawnAgent(dispatchItem, config) {
     // auto-stash is disabled, or because `applyLiveCheckoutAutoStash` itself
     // reported `outcome:'unchanged'` (the `git stash push` call failed) — and
     // the fleet/project auto-reset policy resolves true, NOW perform the
-    // destructive `fetch` + `reset --hard origin/<ref>` as a fallback, reusing
+    // destructive `reset --hard HEAD` + `clean -fd` WIP cleanup as a fallback, reusing
     // prepareLiveCheckout's existing reset logic by re-invoking it with an
     // explicit `autoReset: true` (bypassing config resolution, which we've
     // already evaluated). This only fires when the first prepareLiveCheckout
@@ -2761,6 +2761,27 @@ async function spawnAgent(dispatchItem, config) {
     if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'dirty') {
       const _dirtyFiles = Array.isArray(_liveResult.dirtyFiles) ? _liveResult.dirtyFiles : [];
       const _branchInfo = typeof _liveResult.branchInfo === 'string' ? _liveResult.branchInfo : '';
+      const _autoResetAttempt = _liveResult.autoResetAttempt;
+      const _resetAuditSlug = typeof _autoResetAttempt?.auditSlug === 'string'
+        ? _autoResetAttempt.auditSlug
+        : `live-checkout-autoreset-${id}`;
+      let _cleanAttemptStatus = 'not run';
+      let _statusCheckStatus = 'failed';
+      if (_autoResetAttempt?.cleanAttempted) {
+        _cleanAttemptStatus = _autoResetAttempt.cleanSucceeded ? 'succeeded' : 'failed or partially applied';
+      }
+      if (_autoResetAttempt?.recheckSucceeded) {
+        _statusCheckStatus = `${_dirtyFiles.length} dirty path(s) remain`;
+      }
+      const _resetAttemptSummary = _autoResetAttempt
+        ? [
+          'Automatic reset cleanup was attempted before this refusal:',
+          `- \`git reset --hard HEAD\`: ${_autoResetAttempt.resetSucceeded ? 'succeeded' : 'failed'}`,
+          `- \`git clean -fd\`: ${_cleanAttemptStatus}`,
+          `- post-cleanup status check: ${_statusCheckStatus}`,
+          `See the \`${_resetAuditSlug}\` inbox note for the full before/after audit.`,
+        ].join('\n')
+        : 'No automatic reset/clean recovery was attempted before this refusal.';
       // #329 + PL-live-checkout-reliability-hardening: two-strike dirty guard.
       // First dirty failure is retried once (a transient or engine-owned dirty
       // state — e.g. an agent's own leftover WIP, which dispatch-end restore now
@@ -2800,7 +2821,7 @@ async function spawnAgent(dispatchItem, config) {
         `**Dispatch:** ${id}`,
         ...(_branchInfo ? ['', `**Current checkout:** \`${_branchInfo}\``] : []),
         '',
-        `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.`,
+        `The engine refused to spawn the agent because \`${cwd}\` has uncommitted changes. Live-checkout mode runs in your project directly.`,
         '',
         '## Dirty files (`git status --porcelain=v1 -b`)',
         '',
@@ -2808,6 +2829,8 @@ async function spawnAgent(dispatchItem, config) {
         ...(_dirtyFiles.length > 0 ? _liveCheckout.capDirtyFileLines(_dirtyFiles) : ['(none reported)']),
         '```',
         '',
+        _resetAttemptSummary,
+        '',
         _autoCleanupEnabled
           ? 'Auto-cleanup (`liveCheckoutAutoReset`/`liveCheckoutAutoStash`) is active — the engine re-cleans the tree on each attempt, so this dispatch will be retried automatically (subject to the normal retry cap).'
           : (_alreadyDirtyFailed
@@ -4394,7 +4417,7 @@ async function spawnAgent(dispatchItem, config) {
   // agent never gets a chance to push over the rebased tip.
   // Read-only and non-fix dispatches are out of scope — implement tasks cut
   // their own branch from main, and review/verify don't push.
-  if (type === WORK_TYPE.FIX && branchName && worktreePath && cwd === worktreePath) {
+  if (shared.isFixLikeWorkType(type) && branchName && worktreePath && cwd === worktreePath) {
     _phaseT.staleHeadStart = Date.now();
     try {
       const guard = await assertStaleHeadOk({
@@ -8681,7 +8704,7 @@ function discoverFromWorkItems(config, project) {
       return b && b > 0 && getMonthlySpend(id) >= b && isAgentIdle(id);
     });
     if (!agentId) {
-      if (!budgetBlocked && !hardPinRequested && workType !== WORK_TYPE.FIX) {
+      if (!budgetBlocked && !hardPinRequested && !shared.isFixLikeWorkType(workType)) {
         reservedAgentId = resolveAgentReservation(workType, config, { agentHints });
         agentId = reservedAgentId && !hasAgentHints ? routing.ANY_AGENT : reservedAgentId;
       }
@@ -8723,7 +8746,7 @@ function discoverFromWorkItems(config, project) {
     const linkedPr = item.skipPr ? null : resolveWorkItemPrRecord(item, project);
     const promptItem = linkedPr ? withWorkItemPrContext(item, linkedPr) : item;
     const prBranch = linkedPr?.branch || '';
-    const isPrTargeted = !!(linkedPr && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
+    const isPrTargeted = !!(linkedPr && (shared.isFixLikeWorkType(workType) || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST));
     // Issue #607 — `linkedPr` above resolves through the LOOSE
     // extractWorkItemPrRef (title/first-paragraph-of-description text scan),
     // which is fine for prompt-context enrichment (promptItem, above) that
@@ -8745,7 +8768,7 @@ function discoverFromWorkItems(config, project) {
     // create-time stamp path keeps using the loose form — gate uses
     // structured-only; stamp uses loose. See engine/shared.js
     // extractStructuredWorkItemPrRef for the structured-source list.
-    if (!linkedPr && getStructuredWorkItemPrRef(item) && (workType === WORK_TYPE.FIX || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
+    if (!linkedPr && getStructuredWorkItemPrRef(item) && (shared.isFixLikeWorkType(workType) || workType === WORK_TYPE.REVIEW || workType === WORK_TYPE.TEST)) {
       if (item._pendingReason !== 'pr_not_found') { item._pendingReason = 'pr_not_found'; needsWrite = true; }
       log('warn', `Work item ${item.id} references PR ${getStructuredWorkItemPrRef(item)} but no tracked PR record was found`);
       continue;
@@ -9048,7 +9071,7 @@ function buildWorkItemDispatchVars(item, vars, config, options = {}) {
   // SHERLOC (P-mqyp0008v022w3x4): inject prior explore context for fix dispatches.
   // When a completed explore WI has a reference to this fix WI, surface its
   // resultSummary so the fix agent starts with pre-localized fault context.
-  if (workType === WORK_TYPE.FIX) {
+  if (shared.isFixLikeWorkType(workType)) {
     vars.prior_explore_context = resolvePriorExploreContext(item, config);
   }
 
@@ -9375,7 +9398,7 @@ function discoverCentralWorkItems(config) {
       const hardPinRequested = !!hardPinnedAgent;
       const agentId = hardPinnedAgent
         || resolveAgent(workType, config, { agentHints })
-        || (!hardPinRequested && workType !== WORK_TYPE.FIX ? resolveAgentReservation(workType, config, { agentHints }) : null);
+        || (!hardPinRequested && !shared.isFixLikeWorkType(workType) ? resolveAgentReservation(workType, config, { agentHints }) : null);
       if (!agentId) continue;
 
       const agentName = config.agents[agentId]?.name || agentId;
@@ -9757,7 +9780,7 @@ async function discoverWork(config) {
         // type-only filter below would silently start gating those
         // previously-ungated sources too. Scope the gate back down to
         // `meta.source === 'pr'` to preserve the original behavior exactly.
-        const isGateEligible = (w) => w.meta?.source === 'pr' && (w.type === WORK_TYPE.FIX || w.type === WORK_TYPE.REVIEW);
+        const isGateEligible = (w) => w.meta?.source === 'pr' && (shared.isFixLikeWorkType(w.type) || w.type === WORK_TYPE.REVIEW);
         const gated = items.filter(isGateEligible);
         if (gated.length > 0) {
           log('info', `Gating ${gated.length} fixes/reviews — implement items in progress and no free slots`);
@@ -9799,7 +9822,7 @@ async function discoverWork(config) {
       }));
     }
     for (const w of toDispatch) {
-      if (w.type === WORK_TYPE.FIX) persistedFixes++;
+      if (shared.isFixLikeWorkType(w.type)) persistedFixes++;
       else if (w.type === WORK_TYPE.REVIEW) persistedReviews++;
       else persistedOther++;
     }
@@ -9818,7 +9841,7 @@ async function discoverWork(config) {
     if (config.engine?.prDiscoveryEnabled !== false) {
       const prWork = await discoverFromPrs(config, project);
       projectWork.push(...prWork.filter(w =>
-        w.type === WORK_TYPE.FIX || w.type === WORK_TYPE.REVIEW || w.type === WORK_TYPE.TEST));
+        shared.isFixLikeWorkType(w.type) || w.type === WORK_TYPE.REVIEW || w.type === WORK_TYPE.TEST));
     }
 
     // Side-effect: specs → work items (picked up below)
@@ -10038,7 +10061,7 @@ function persistPendingDispatchAgent(item) {
 }
 
 function isSoftFixDispatch(item) {
-  return item?.type === WORK_TYPE.FIX && !routing.isAgentHardPinned(item.meta?.item);
+  return shared.isFixLikeWorkType(item?.type) && !routing.isAgentHardPinned(item.meta?.item);
 }
 
 function resolveMaxConcurrent(config) {
@@ -10945,7 +10968,15 @@ async function tickInner() {
             skipDirtyCheck: !!_precheckProjCfg.skipLiveCheckoutDirtyCheck,
           });
         } catch (e) { log('warn', `live-checkout precheck (dirty) failed for ${item.id}: ${e.message}`); }
-        if (_dirtyResult && _dirtyResult.dirty) {
+        const _autoStashEnabled = _liveCheckoutPrecheck.resolveLiveCheckoutAutoStash({
+          project: _precheckProjCfg,
+          engine: config.engine || {},
+        });
+        const _autoResetEnabled = shared.resolveLiveCheckoutAutoReset(
+          _precheckProjCfg,
+          config.engine || {},
+        );
+        if (_dirtyResult && _dirtyResult.dirty && !_autoStashEnabled && !_autoResetEnabled) {
           _persistPendingReason('live_checkout_dirty');
           try {
             const _alertBody = [
@@ -11131,11 +11162,12 @@ async function tickInner() {
   // post-dispatch active list so the annotation loop's reason is consistent
   // with whatever actually got spawned this tick.
   const postLiveProjectsInUse = new Set();
+  const postProjects = shared.getProjects(config);
   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);
+    const projCfg = shared.findProjectByName(postProjects, projName);
     if (shared.resolveCheckoutMode(projCfg, d.type) === 'live') {
       postLiveProjectsInUse.add(projName);
     }
@@ -11162,7 +11194,10 @@ async function tickInner() {
           && !READ_ONLY_ROOT_TASK_TYPES.has(item.type)
           && postLiveProjectsInUse.has(itemProjName)
         ) {
-          reason = 'live_checkout_busy';
+          const projCfg = shared.findProjectByName(postProjects, itemProjName);
+          if (shared.resolveCheckoutMode(projCfg, item.type) === 'live') {
+            reason = 'live_checkout_busy';
+          }
         }
       }
     }

package/package.json

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

package/prompts/cc-system.md

@@ -92,7 +92,7 @@ When genuinely in doubt about the size, delegate — agents have isolated worktr
 ### HARD STOP — never edit files yourself in a live/hybrid project
 This overrides everything above, **including the direct-handling override**. For any project whose effective checkout mode is `live` (or `hybrid` for a code-authoring work-item type — `implement`/`fix`/`docs`/`decompose`), you MUST NOT use `Edit`/`Write`/`Bash` (or any tool) to mutate files inside that project's `localPath`, **regardless of task size** — not even a Small 1-line change, and not even when the human explicitly says to do it yourself. The Step-3 "do it yourself" allowance and the Step-1 direct-handling override do **not** apply to writes inside a live/hybrid checkout.
 
-Why: live-mode projects have no worktree isolation — the engine runs agents in-place inside `localPath`, caps dispatch to one mutating operation at a time, and refuses to dispatch on a dirty tree (`live-checkout-dirty`, non-retryable). A stray CC edit leaves the checkout dirty in a way the dispatch bookkeeping does not track, and that dirty state then **blocks every subsequent live-mode dispatch** on the project until a human manually cleans it up. It is NOT covered by the engine's dispatch-time auto-stash/auto-reset recovery — those only run as part of an actual dispatch preflight, never for stray CC edits.
+Why: live-mode projects have no worktree isolation — the engine runs agents in-place inside `localPath` and caps dispatch to one mutating operation at a time. A stray CC edit is outside dispatch ownership: with dirty recovery disabled it causes a `live-checkout-dirty` refusal that blocks live work, while the default auto-stash policy can silently park that edit before the next dispatch, so the requested change is no longer present for the agent to validate or commit. Auto-stash/reset is a dispatch recovery mechanism, not ownership bookkeeping for CC edits.
 
 Instead, when a change is needed in a live/hybrid project, **dispatch a normal work item** (`POST /api/work-items`, `type: "implement"` or `"fix"` as usual) and let the engine own the live-checkout dispatch path (dirty-tree refusal, single-mutating-dispatch cap, auto-stash/auto-reset). Do not try to shortcut it with your own edit.
 
@@ -333,23 +333,23 @@ The `X-CC-Turn-Id` header is the audit trail — the handler stamps it onto the
 Every configured project has an effective **checkout mode** — surfaced in your state snapshot next to the project as `[worktree]`, `[live]`, or `[hybrid (live-validation: <type>)]`. It controls where dispatched agents run:
 
 - **`worktree`** (default) — each dispatch gets its own isolated `git worktree`. Agents run fully in parallel; nothing touches the operator's working tree. Use for normal repos.
-- **`live`** — agents run **in-place** inside the project's `localPath` (no worktree). The engine caps this to **one mutating dispatch at a time** per project and **refuses on a dirty tree**. Use only when worktrees are unworkable (e.g. Android `repo`, submodules, deep Windows paths, emulators that bind the real checkout).
-- **`hybrid`** — `live` **plus** a `liveValidation: { type, autoDispatch }` block. Coding work items (`implement`/`fix`/`docs`/`decompose`) author in **isolated worktrees** (full parallelism), while **only** work items whose type matches `liveValidation.type` (e.g. `build-and-test`) run **in-place on the live checkout**. This is the best of both: parallel code authoring + a real on-disk build/validation that can't run in a worktree. `type` accepts a single string (e.g. `"build-and-test"`) or an array of strings (e.g. `["implement","fix"]`) to route multiple work-item types to the live checkout at once.
+- **`live`** — agents run **in-place** inside the project's `localPath` (no worktree). The engine caps this to **one mutating dispatch at a time** per project. Dirty-tree behavior follows the configured auto-stash/reset policy (auto-stash defaults on); with recovery disabled, the item remains pending until the tree is clean. Use only when worktrees are unworkable.
+- **`hybrid`** — `live` **plus** a `liveValidation: { type, autoDispatch }` block. Work items not listed in `type` use isolated worktrees; listed live-capable canonical work-item types run in-place. The normal validation type is `test`. `build-and-test` is a playbook name, not a work-item type. `type` accepts one string or an array. When `autoDispatch:true`, `test` must be included; the engine creates one PR-targeted `test` WI with the `build-and-test` playbook after each eligible coding WI completes.
 
-**CC never writes into a live/hybrid checkout itself.** Because `live` (and the code-authoring surface of `hybrid`) runs in-place with no worktree isolation, a one-off CC edit inside such a project's `localPath` leaves the tree dirty and blocks every future live-mode dispatch (the engine refuses on a dirty tree, `live-checkout-dirty`, non-retryable — and it does not track or auto-recover stray CC edits). So for any needed change in a `live`/`hybrid` project you **dispatch a work item** and let the engine own the live-checkout path; you never `Edit`/`Write`/`Bash`-mutate files there yourself, regardless of task size or a direct-handling override. Read-only inspection remains fine. This is the same rule stated up top under "HARD STOP — never edit files yourself in a live/hybrid project"; the two sections agree by design.
+**CC never writes into a live/hybrid checkout itself.** A one-off CC edit leaves untracked operator dirt that the next dispatch may unexpectedly stash or may block on when recovery is disabled. For any needed change, **dispatch a work item** and let the engine own the live-checkout path; never `Edit`/`Write`/`Bash`-mutate files there yourself. Read-only inspection remains fine.
 
 **When to recommend hybrid:** the project's build/test/validation genuinely cannot run in an isolated worktree (it needs the real checkout — submodules, a `repo`-managed tree, an emulator/dev-server bound to `localPath`, deep-path tooling), **but** you still want coding agents to work in parallel rather than serialize through the single live checkout. If the *whole* workflow must run on the real tree, use plain `live`. If nothing needs the real tree, stay on `worktree`.
 
 **Configuring it** (via the projects array on `POST /api/settings` — never hand-edit `config.json`):
 ```bash
-# Switch a project to hybrid mode (live checkout + deferred build-and-test validation)
+# Switch a project to hybrid mode (live checkout + deferred test validation)
 curl -s -X POST http://localhost:{{dashboard_port}}/api/settings \
   -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
-  -d '{"projects":[{"name":"<project>","checkoutMode":"live","liveValidation":{"type":"build-and-test","autoDispatch":true}}]}'
+  -d '{"projects":[{"name":"<project>","checkoutMode":"live","liveValidation":{"type":"test","autoDispatch":true}}]}'
 # Clear hybrid (back to plain live): pass "liveValidation": null
 # Clear live entirely (back to worktree): pass "checkoutMode": "worktree" (also clear liveValidation)
 ```
-The server validates: `liveValidation` requires `checkoutMode:"live"` (400 otherwise) and a non-empty `type`. With `autoDispatch:true`, the engine auto-creates a `<type>` validation WI on the live checkout after each coding WI completes with a PR. **Always confirm the mode switch with the user before applying it** — it changes how every future dispatch on that project runs.
+The server validates: `liveValidation` requires `checkoutMode:"live"`, canonical live-capable work-item type(s), and a boolean `autoDispatch`; automatic validation additionally requires `test` in `type`. **Always confirm the mode switch with the user before applying it** — it changes how future dispatches run.
 
 ## GitHub auth