@yemi33/minions 0.1.2380 → 0.1.2382

package/engine.js

@@ -1430,15 +1430,15 @@ const _quarantinePathLocks = new Map();
 //      (Pure shared-branch callers pass quarantineOnUnsafe=false and DO NOT
 //      treat ahead-of-origin as dirty — that path's existing semantics are
 //      preserved. PR-targeted reused worktrees pass quarantineOnUnsafe=true
-//      and DO treat ahead-of-origin as unsafe because the underlying bug
-//      (#2996) was a 157-commit-ahead local branch.)
+//      and preserve clean strictly-ahead commits by pushing them before any
+//      quarantine fallback (#853).)
 //   3. If unsafe, decide:
 //      - Block (preserve dirty tree for inspection) when ANOTHER active
 //        dispatch claims the same branch (ownership ambiguity — NEVER
 //        quarantine, even when quarantineOnUnsafe=true).
-//      - Block when local commits exist that aren't on origin/<branch>
-//        (would lose unpushed work). When quarantineOnUnsafe=true,
-//        QUARANTINE instead: rename worktree to <path>-quarantine-<ts>,
+//      - When clean local commits are strictly ahead, push them to origin.
+//        If that push fails or the branch is genuinely diverged, quarantine:
+//        rename worktree to <path>-quarantine-<ts>,
 //        prune git's stale metadata, back up the local branch HEAD to
 //        refs/minions/quarantine/<sanitized>/<ts>, reset
 //        refs/heads/<branch> → origin/<branch>, and write a notes/inbox/
@@ -1458,6 +1458,124 @@ const _quarantinePathLocks = new Map();
 //      quarantined, quarantinedPath, backupRef } so the caller can fail
 //      fast with a first-class DIRTY_WORKTREE / WORKTREE_DIRTY /
 //      WORKTREE_DIVERGENT reason and retry semantics.
+async function pushCleanAheadBranch({ rootDir, worktreePath, branchName, mainBranch, project, gitOpts = {} } = {}) {
+  const result = { pushed: false, reason: null, ahead: 0, behind: 0 };
+  if (!rootDir || !worktreePath || !branchName || !fs.existsSync(worktreePath)) {
+    return { ...result, reason: 'invalid-worktree' };
+  }
+  if (mainBranch && sanitizeBranch(branchName) === sanitizeBranch(mainBranch)) {
+    return { ...result, reason: 'main-branch' };
+  }
+  const { gitExtraArgs: _staleGitExtraArgs, ...networkGitOpts } = gitOpts;
+  const runNetworkGit = (args, opts) => project
+    ? adoGitAuth.runAdoGit(project, args, { ...networkGitOpts, ...opts })
+    : shared.shellSafeGit(args, { ...gitOpts, ...opts });
+  try {
+    const current = String(await shared.shellSafeGit(
+      ['symbolic-ref', '--quiet', '--short', 'HEAD'],
+      { ...gitOpts, cwd: worktreePath, timeout: 10000 },
+    ) || '').trim();
+    if (current !== branchName) return { ...result, reason: 'branch-mismatch' };
+
+    const status = String(await shared.shellSafeGit(
+      ['--no-optional-locks', 'status', '--porcelain'],
+      { ...gitOpts, cwd: worktreePath, timeout: 15000 },
+    ) || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean)
+      .filter(line => !shared.isWorktreeOwnerMarkerStatusLine(line));
+    if (status.length > 0) return { ...result, reason: 'dirty' };
+
+    let remoteExists = false;
+    let trackingRefExists = false;
+    try {
+      await shared.shellSafeGit(
+        ['show-ref', '--verify', '--quiet', `refs/remotes/origin/${branchName}`],
+        { ...gitOpts, cwd: rootDir, timeout: 10000 },
+      );
+      remoteExists = true;
+      trackingRefExists = true;
+    } catch {
+      // A first-attempt branch may not have a local remote-tracking ref. Only
+      // pay for ls-remote in that uncommon case; aligned dispatch closes stay
+      // local-only and do not add a network round trip.
+      try {
+        const remote = String(await runNetworkGit(
+          ['ls-remote', '--exit-code', '--heads', 'origin', branchName],
+          { cwd: rootDir, timeout: 15000 },
+        ) || '').trim();
+        remoteExists = !!remote;
+      } catch (err) {
+        if (err?.code !== 2 && err?.status !== 2) {
+          return { ...result, reason: 'remote-probe-failed', error: err.message };
+        }
+      }
+    }
+
+    if (remoteExists) {
+      if (trackingRefExists) {
+        const localCounts = String(await shared.shellSafeGit(
+          ['rev-list', '--left-right', '--count', `refs/remotes/origin/${branchName}...HEAD`],
+          { ...gitOpts, cwd: worktreePath, timeout: 15000 },
+        ) || '').trim().split(/\s+/).map(Number);
+        const locallyAhead = Number.isFinite(localCounts[1]) ? localCounts[1] : 0;
+        if (locallyAhead === 0) {
+          return {
+            ...result,
+            behind: Number.isFinite(localCounts[0]) ? localCounts[0] : 0,
+            reason: 'aligned',
+          };
+        }
+      }
+      try {
+        await runNetworkGit(
+          ['fetch', 'origin', branchName],
+          { cwd: rootDir, timeout: 30000 },
+        );
+      } catch (err) {
+        return { ...result, reason: 'fetch-failed', error: err.message };
+      }
+      const counts = String(await shared.shellSafeGit(
+        ['rev-list', '--left-right', '--count', `refs/remotes/origin/${branchName}...HEAD`],
+        { ...gitOpts, cwd: worktreePath, timeout: 15000 },
+      ) || '').trim().split(/\s+/).map(Number);
+      result.behind = Number.isFinite(counts[0]) ? counts[0] : 0;
+      result.ahead = Number.isFinite(counts[1]) ? counts[1] : 0;
+      if (result.behind > 0) return { ...result, reason: 'diverged' };
+      if (result.ahead === 0) return { ...result, reason: 'aligned' };
+    } else {
+      if (!mainBranch) return { ...result, reason: 'no-upstream-no-main' };
+      try {
+        result.ahead = Number(String(await shared.shellSafeGit(
+          ['rev-list', '--count', `refs/remotes/origin/${mainBranch}..HEAD`],
+          { ...gitOpts, cwd: worktreePath, timeout: 15000 },
+        ) || '').trim());
+      } catch (err) {
+        return { ...result, reason: 'main-compare-failed', error: err.message };
+      }
+      if (!Number.isFinite(result.ahead) || result.ahead <= 0) {
+        return { ...result, ahead: 0, reason: 'no-local-commits' };
+      }
+    }
+
+    try {
+      await runNetworkGit(
+        ['push', 'origin', `HEAD:refs/heads/${branchName}`],
+        { cwd: worktreePath, timeout: 30000 },
+      );
+      log('info', `Preserved ${result.ahead} clean local commit(s) by pushing ${branchName} to origin`);
+      return {
+        ...result,
+        pushed: true,
+        reason: remoteExists ? 'pushed-ahead' : 'pushed-new-branch',
+      };
+    } catch (err) {
+      log('warn', `Failed to preserve clean ahead branch ${branchName}: ${err.message}`);
+      return { ...result, reason: 'push-failed', error: err.message };
+    }
+  } catch (err) {
+    return { ...result, reason: 'probe-failed', error: err.message };
+  }
+}
+
 async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, dispatchId, gitOpts = {}, opts = {}) {
   const quarantineOnUnsafe = !!opts.quarantineOnUnsafe;
   // W-mq1habhf: status probe timeout is now configurable so large/GVFS repos
@@ -1638,6 +1756,41 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     }
   }
 
+  // #853 — a clean branch that is strictly ahead contains completed agent
+  // commits, not contamination. Preserve them on the PR/work branch before
+  // quarantine can move the work to a local-only backup ref. A rejected or
+  // non-fast-forward push falls through to the existing quarantine path.
+  if (!filesystemDirty && quarantineOnUnsafe && (result.ahead > 0 || !upstreamKnown)) {
+    const preservation = await pushCleanAheadBranch({
+      rootDir,
+      worktreePath,
+      branchName,
+      mainBranch: opts.mainBranch,
+      project: opts.project,
+      gitOpts,
+    });
+    const preservationProvedClean = preservation.pushed ||
+      ['aligned', 'no-local-commits'].includes(preservation.reason);
+    if (preservationProvedClean) {
+      result.clean = true;
+      result.pushed = preservation.pushed;
+      result.ahead = preservation.ahead;
+      result.behind = preservation.behind;
+      result.reason = preservation.reason;
+      return result;
+    }
+    result.pushFailure = preservation.reason;
+    result.pushError = preservation.error;
+    if (preservation.reason !== 'diverged') {
+      // A network/auth failure does not prove the branch is unsafe. Leave the
+      // clean ahead worktree intact so a later retry can push the same commits.
+      result.reason = preservation.reason;
+      return result;
+    }
+    result.ahead = preservation.ahead;
+    result.behind = preservation.behind;
+  }
+
   // 5. Unpushed-commit check — refuse to reset when local work would be lost.
   //    Use the ahead count we already computed (cheaper + correct vs.
   //    `git log @{u}..HEAD` which needs an upstream config and silently
@@ -2711,7 +2864,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 +2914,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 +2974,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 +2982,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
@@ -3764,12 +3940,14 @@ async function spawnAgent(dispatchItem, config) {
         {
           quarantineOnUnsafe: true,
           mainBranch: shared.resolveMainBranch(rootDir, project.mainBranch),
+          project,
           statusTimeoutMs: engineConfig.assertCleanStatusTimeoutMs ?? ENGINE_DEFAULTS.assertCleanStatusTimeoutMs,
         },
       );
       _phaseT.dirtyReusedCheckEnd = Date.now();
       if (!cleanResult.clean) {
         const previewFiles = (cleanResult.dirtyFiles || []).slice(0, 5).join(', ');
+        const isPushBlocked = ['remote-probe-failed', 'fetch-failed', 'push-failed'].includes(cleanResult.reason);
         const isDivergent = (cleanResult.ahead || 0) > 0 || cleanResult.reason === 'no-upstream';
         // W-mq1habhf: status-failed is a different beast than
         // has-unpushed-commits / no-upstream. We couldn't even read the
@@ -3792,12 +3970,21 @@ async function spawnAgent(dispatchItem, config) {
         // the existing _quarantineRecoveryCount cap. This stops env failures
         // from burning the per-agent retry budget the way they did before.
         const isQuarantineEnvBlocked = !!(cleanResult.quarantineError && !cleanResult.quarantined);
-        const failureClassValue = isQuarantineEnvBlocked
-          ? FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED
-          : (isDivergent ? FAILURE_CLASS.WORKTREE_DIVERGENT : FAILURE_CLASS.WORKTREE_DIRTY);
-        const failureClassName = isQuarantineEnvBlocked
-          ? 'WORKTREE_QUARANTINE_ENV_BLOCKED'
-          : (isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY');
+        const isPushAuthBlocked = isPushBlocked && adoGitAuth.isAdoAuthFailure(
+          new Error(cleanResult.pushError || ''),
+        );
+        let failureClassValue = FAILURE_CLASS.WORKTREE_DIRTY;
+        let failureClassName = 'WORKTREE_DIRTY';
+        if (isPushBlocked) {
+          failureClassValue = isPushAuthBlocked ? FAILURE_CLASS.AUTH : FAILURE_CLASS.NETWORK_ERROR;
+          failureClassName = isPushAuthBlocked ? 'AUTH' : 'NETWORK_ERROR';
+        } else if (isQuarantineEnvBlocked) {
+          failureClassValue = FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED;
+          failureClassName = 'WORKTREE_QUARANTINE_ENV_BLOCKED';
+        } else if (isDivergent) {
+          failureClassValue = FAILURE_CLASS.WORKTREE_DIVERGENT;
+          failureClassName = 'WORKTREE_DIVERGENT';
+        }
         // #284: distinguish the ORIGINAL worktree-preflight failure from a
         // failure on the automatic fresh-worktree retry. The quarantine
         // auto-recovery loop (discoverFromWorkItems) flips a failed
@@ -3810,7 +3997,9 @@ async function spawnAgent(dispatchItem, config) {
         const retryLabel = priorQuarantineRetry > 0
           ? ` [retry-in-fresh-worktree #${priorQuarantineRetry} also failed]`
           : ' [original worktree-preflight issue]';
-        const reasonMsg = cleanResult.quarantined
+        const reasonMsg = isPushBlocked
+          ? `${failureClassName}: clean ahead worktree at ${worktreePath} could not be pushed (${cleanResult.reason}: ${cleanResult.pushError || 'unknown error'}). The worktree and local commits were preserved for retry.`
+          : cleanResult.quarantined
           ? `${failureClassName}: reused worktree at ${worktreePath} was dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} dirty file(s)${previewFiles ? ': ' + previewFiles : ''}) — quarantined to ${cleanResult.quarantinedPath}. Next dispatch will start fresh.`
           : `${failureClassName}: reused worktree at ${worktreePath} is dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}). Quarantine ${cleanResult.quarantineError ? 'errored: ' + cleanResult.quarantineError : (cleanResult.quarantineSkipped ? 'was skipped — another live dispatch claims the worktree (see notes/inbox/ engine-worktree-skip-live note).' : 'was not attempted (' + cleanResult.reason + ').')}`;
         log('error', reasonMsg);
@@ -3820,7 +4009,11 @@ async function spawnAgent(dispatchItem, config) {
           DISPATCH_RESULT.ERROR,
           reasonMsg.slice(0, 500),
           `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996).${retryLabel} Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}${isQuarantineEnvBlocked ? ' Environmental quarantine failure (Windows EBUSY); WI auto-recovery loop will re-queue without bumping per-agent retry counter.' : ''}`,
-          { agentRetryable: isStatusProbeFailed && cleanResult.quarantined, failureClass: failureClassValue },
+          {
+            agentRetryable: (isStatusProbeFailed && cleanResult.quarantined) ||
+              (isPushBlocked && !isPushAuthBlocked),
+            failureClass: failureClassValue,
+          },
         );
         cleanupTempAgent(agentId);
         return null;
@@ -4394,7 +4587,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({
@@ -4920,6 +5113,25 @@ async function spawnAgent(dispatchItem, config) {
     ackPendingSteeringFiles(agentId, procInfo, steeringAckStdout);
     promoteCheckpointSteeringForClose(agentId, procInfo, runtime, liveOutputPath);
 
+    // #853 — the child is gone, so its clean committed state is stable. Push
+    // any strictly-ahead dispatch branch before steering resume, pool return,
+    // quarantine, or dispatch-end GC can detach/remove the worktree.
+    const branchPath = worktreePath || (liveMode ? project?.localPath : null);
+    const branchRootDir = liveMode ? project?.localPath : rootDir;
+    if (branchPath && branchRootDir && branchName && fs.existsSync(branchPath)) {
+      const preservation = await pushCleanAheadBranch({
+        rootDir: branchRootDir,
+        worktreePath: branchPath,
+        branchName,
+        mainBranch: shared.resolveMainBranch(branchRootDir, project?.mainBranch),
+        project,
+        gitOpts: _gitOpts,
+      });
+      if (!preservation.pushed && !['aligned', 'dirty', 'no-local-commits'].includes(preservation.reason)) {
+        log('warn', `Dispatch-close branch preservation skipped for ${id}: ${preservation.reason}`);
+      }
+    }
+
     // Check if this was a steering kill — re-spawn with resume
     if (procInfo?._steeringMessage) {
       const steerMsg = procInfo._steeringMessage;
@@ -5249,7 +5461,7 @@ async function spawnAgent(dispatchItem, config) {
     // delete clears the entry.
     const expectedNonce = activeProcesses.get(id)?._completionNonce || null;
     const completionNonceRequired = engineConfig.completionNonceRequired ?? ENGINE_DEFAULTS.completionNonceRequired;
-    const { resultSummary, autoRecovered, completionContractFailure, structuredCompletion, agentReportedFailure, agentRetryable, nonceMismatch } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, { expectedNonce, completionNonceRequired });
+    const { resultSummary, autoRecovered, completionContractFailure, structuredCompletion, agentReportedFailure, agentRetryable, nonceMismatch, benignNoop } = await runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, { expectedNonce, completionNonceRequired });
     const retryableDecision = typeof agentRetryable === 'boolean' ? agentRetryable : failureInfo.retryable;
 
     // W-mp6k7ywi000fa33c — keep_processes acceptance gate. When the work
@@ -5655,7 +5867,7 @@ async function spawnAgent(dispatchItem, config) {
     const managedSpawnHealthcheckFail = !!managedSpawnHealthcheckFailure;
     const effectiveResult = (hardContractFail || nonceFail || keepProcessesAcceptanceFail || managedSpawnAcceptanceFail || managedSpawnHealthcheckFail)
       ? DISPATCH_RESULT.ERROR
-      : (((code === 0 && !agentReportedFailure) || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
+      : (((code === 0 && !agentReportedFailure) || autoRecovered || benignNoop) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
     const finalCompletionReportPath = structuredCompletion?._path || dispatchItem.meta?.completionReportPath || shared.dispatchCompletionReportPath(id);
     const completionOpts = {
       ...(finalCompletionReportPath ? { completionReportPath: finalCompletionReportPath } : {}),
@@ -8151,6 +8363,35 @@ function _buildRunnerBriefVars(item, project) {
 /**
  * Scan a project work-item scope for manually queued tasks.
  */
+/**
+ * W-mrdon0pe000l045a — collect directory/file path hints for CLAUDE.md
+ * propagation. These are the paths most relevant to a dispatch; the
+ * CLAUDE.md-context module walks UP from each toward the project root collecting
+ * the nearest applicable CLAUDE.md files. Sources (best-effort, cheap):
+ *   - item.meta.workdir (explicit sub-project directory)
+ *   - item.references[*].path (changed/relevant files)
+ * Returns a de-duplicated array of repo-relative path strings. Empty when no
+ * hints exist — the module still falls back to the project-root CLAUDE.md.
+ */
+function _deriveClaudeMdPathHints(item) {
+  const hints = [];
+  const seen = new Set();
+  const add = (p) => {
+    if (typeof p !== 'string') return;
+    const v = p.trim();
+    if (!v || seen.has(v)) return;
+    seen.add(v);
+    hints.push(v);
+  };
+  if (item && item.meta && typeof item.meta.workdir === 'string') add(item.meta.workdir);
+  if (item && Array.isArray(item.references)) {
+    for (const r of item.references) {
+      if (r && typeof r.path === 'string') add(r.path);
+    }
+  }
+  return hints;
+}
+
 function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, project, root, branchName, options = {}) {
   const worktreePath = options.worktreePath || path.resolve(root, config.engine?.worktreeRoot || '../worktrees', `${branchName}`);
   const vars = {
@@ -8304,6 +8545,14 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // failure via the qa-session-draft-failed / qa-session-execute-failed
     // path. (See playbooks/qa-session-draft.md → "Failure path" section.)
     ..._buildRunnerBriefVars(item, project),
+    // W-mrdon0pe000l045a — CLAUDE.md propagation context for non-Claude runtimes.
+    // renderPlaybook resolves the runtime capability + config flag and, when the
+    // runtime doesn't auto-load CLAUDE.md (Copilot/Codex), bounded-discovers the
+    // nearest applicable CLAUDE.md files walking up from these path hints toward
+    // the project root. runtime_cli lets renderPlaybook check the adapter's
+    // claudeMdNativeDiscovery capability without re-resolving the agent config.
+    runtime_cli: shared.resolveAgentCli(config.agents?.[agentId] || null, config.engine),
+    claude_md_path_hints: _deriveClaudeMdPathHints(item),
     // M006 — typed handoff envelope. Set on follow-up dispatch metas by
     // lifecycle.js when queuing an item after a completing agent. The
     // renderPlaybook path injects a "Handoff Context" section when truthy
@@ -8548,6 +8797,15 @@ function discoverFromWorkItems(config, project) {
     }
 
     if (item.status !== WI_STATUS.QUEUED && item.status !== WI_STATUS.PENDING) continue;
+    if (item._preDispatchEval?.exhausted === true
+        && item._preDispatchEval.description === String(item.description || '')) {
+      if (item._pendingReason !== 'pre_dispatch_eval_rejected') {
+        item._pendingReason = 'pre_dispatch_eval_rejected';
+        needsWrite = true;
+      }
+      skipped.gated++;
+      continue;
+    }
 
     // Dependency gate: skip items whose depends_on are not yet met; propagate failure
     if (item.depends_on && item.depends_on.length > 0) {
@@ -8681,7 +8939,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 +8981,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 +9003,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 +9306,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 +9633,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 +10015,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 +10057,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 +10076,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 +10296,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 +11203,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 +11397,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 +11429,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';
+          }
         }
       }
     }
@@ -11361,7 +11631,7 @@ module.exports = {
   gitOutputToString, gitErrorOutput, classifyDepMergeFailureOutput, listUnmergedFiles, // exported for testing
   buildDepConflictFixItem, deriveConflictFixKey, // exported for testing (W-mpcwojgr000a0244)
   runWorktreeAdd, // exported for testing (W-mqvaxv65000m76f2 — GVFS partial-checkout behavioral test)
-  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
+  isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, pushCleanAheadBranch, assertCleanSharedWorktree, _quarantineDirtyWorktree, // exported for testing
   _statusPorcelainCmd, _killGitDescendantsForWorktree, _bumpQuarantineOutcome, // exported for testing (W-mq5n1zx5)
   _reapWorktreeHolders, _findTerminalWorktreeOwners, // exported for testing (W-mqila0t5 — CWD-pinned holder reap)
   pruneStaleWorktreeForBranch, // exported for testing

package/package.json

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