@yemi33/minions 0.1.2381 → 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
@@ -3787,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
@@ -3815,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
@@ -3833,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);
@@ -3843,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;
@@ -4943,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;
@@ -5272,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
@@ -5678,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 } : {}),
@@ -8174,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 = {
@@ -8327,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
@@ -8571,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) {
@@ -11396,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.2381",
+  "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"