@yemi33/minions 0.1.1984 → 0.1.1985

package/engine/ado-git-auth.js

@@ -0,0 +1,206 @@
+/**
+ * engine/ado-git-auth.js — W-mpcuc8i80003a7b3
+ *
+ * Inject a per-invocation Authorization: Bearer <token> http.extraHeader into
+ * git ops that touch an ADO origin. Solves the headless-dispatch failure mode
+ * where Git Credential Manager falls back to a TTY prompt (because the engine
+ * has no terminal) and emits:
+ *
+ *   fatal: could not read Username for 'https://office.visualstudio.com'
+ *
+ * The token is sourced via the existing `engine/ado-token.js#acquireAdoTokenSync`
+ * helper (az CLI first, azureauth fallback). We cache it for 30 minutes and
+ * back off acquisition retries for 10 minutes on failure so we don't hammer
+ * az / azureauth on every git op during an outage.
+ *
+ * Public API:
+ *   - getAdoGitExtraArgs(project, opts?) → string[]
+ *       Sync. Returns `['-c', 'http.<scope>.extraHeader=Authorization: Bearer <token>']`
+ *       for ADO projects, `[]` for everything else (GitHub/local/null). Plumbed
+ *       into shared.shellSafeGit via `opts.gitExtraArgs`.
+ *   - invalidateAdoTokenCache()
+ *       Drops the cached token so the next getAdoGitExtraArgs() re-acquires.
+ *       Used by runAdoGit on auth failure to handle mid-dispatch token expiry.
+ *   - isAdoAuthFailure(err) → boolean
+ *       Pure. Matches credential/auth-specific phrases against err.message,
+ *       err.stdout, err.stderr. Deliberately NARROW — does not match bare
+ *       "fatal: unable to access" since that also fires for DNS/TLS/proxy.
+ *   - runAdoGit(project, gitArgs, opts) → Promise<string>
+ *       Async wrapper around shellSafeGit. On ADO auth failure, invalidates
+ *       cache, re-acquires, retries ONCE in the same dispatch. Redacts the
+ *       bearer token from rethrown error messages so the token never lands in
+ *       logs / inbox alerts / completion reports.
+ *
+ * Argv-vs-env tradeoff: putting `-c http.extraHeader=Authorization: Bearer X`
+ * in argv is visible via process listing. The simpler alternative
+ * `GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=... GIT_CONFIG_VALUE_0=...` hides the
+ * token from `ps`. We chose argv to match the documented manual-verification
+ * recipe (matches the task spec) and explicitly redact on error rethrow.
+ * Migrate to env-form if argv exposure becomes a real concern.
+ */
+
+const shared = require('./shared');
+const adoToken = require('./ado-token');
+const { log } = shared;
+
+const TOKEN_TTL_MS = 30 * 60 * 1000;     // 30 min — matches gh-token cadence
+const ACQUIRE_BACKOFF_MS = 10 * 60 * 1000; // 10 min — same backoff as gh-token
+const ACQUIRE_TIMEOUT_MS = 30000;        // 30s — generous for slow IWA/broker auth
+
+let _cached = null;       // { token, expiresAt }
+let _backoffUntil = 0;    // epoch ms — no acquire attempts before this
+
+// Credential/auth patterns. Narrow on purpose: do NOT include bare
+// "fatal: unable to access" — that also fires for DNS, TLS, and proxy errors
+// which are correctly classified elsewhere (NETWORK_ERROR, retryable).
+const ADO_AUTH_PATTERNS = [
+  /could not read Username/i,
+  /could not read Password/i,
+  /Authentication failed/i,
+  /terminal prompts disabled/i,
+  /TF40081\d/i,                          // Azure DevOps auth error family
+  /HTTP\s*4(?:01|03)\b/i,                // explicit 401/403 in error text
+];
+
+function isAdoProject(project) {
+  return !!(project && project.repoHost === 'ado');
+}
+
+// Scope the header to the ADO host so a misconfigured remote pointing at
+// another host (e.g. github.com on a misclassified project) doesn't leak the
+// bearer token. Falls back to the unscoped `http.extraHeader` key when we
+// can't compute a host (still safe — git only sends extraHeader on HTTP/S
+// transfers, and the engine only invokes ado-git-auth for ADO projects).
+function _resolveScopeUrl(project) {
+  try {
+    if (!project || !project.adoOrg) return null;
+    const base = shared.getAdoOrgBase(project);
+    if (typeof base !== 'string' || !base.startsWith('http')) return null;
+    const m = base.match(/^(https?:\/\/[^/]+)/);
+    return m ? `${m[1]}/` : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+function _buildHeaderArgs(token, scopeUrl) {
+  const key = scopeUrl ? `http.${scopeUrl}.extraHeader` : 'http.extraHeader';
+  return ['-c', `${key}=Authorization: Bearer ${token}`];
+}
+
+function _acquireToken(opts = {}) {
+  const exec = opts.acquireAdoTokenSync || adoToken.acquireAdoTokenSync;
+  const result = exec({ timeout: opts.timeout || ACQUIRE_TIMEOUT_MS });
+  return result && result.token ? String(result.token) : null;
+}
+
+function getAdoGitExtraArgs(project, opts = {}) {
+  if (!isAdoProject(project)) return [];
+  const now = Date.now();
+  if (_cached && _cached.expiresAt > now) {
+    return _buildHeaderArgs(_cached.token, _resolveScopeUrl(project));
+  }
+  if (now < _backoffUntil) return [];
+  try {
+    const token = _acquireToken(opts);
+    if (!token) {
+      _backoffUntil = now + ACQUIRE_BACKOFF_MS;
+      log('warn', `ado-git-auth: acquireAdoTokenSync returned empty token; backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
+      return [];
+    }
+    _cached = { token, expiresAt: now + TOKEN_TTL_MS };
+    return _buildHeaderArgs(token, _resolveScopeUrl(project));
+  } catch (e) {
+    _backoffUntil = now + ACQUIRE_BACKOFF_MS;
+    const firstLine = String(e && e.message || e).split('\n')[0];
+    log('warn', `ado-git-auth: token acquire failed (${firstLine}); backing off ${ACQUIRE_BACKOFF_MS / 1000}s`);
+    return [];
+  }
+}
+
+function invalidateAdoTokenCache() {
+  _cached = null;
+}
+
+function isAdoAuthFailure(err) {
+  if (!err || typeof err !== 'object') return false;
+  const parts = [
+    err.message,
+    typeof err.stdout === 'string' ? err.stdout : '',
+    typeof err.stderr === 'string' ? err.stderr : '',
+  ].filter(Boolean).join('\n');
+  if (!parts) return false;
+  return ADO_AUTH_PATTERNS.some((p) => p.test(parts));
+}
+
+function _redactBearer(s) {
+  if (typeof s !== 'string') return s;
+  return s.replace(/Authorization:\s*Bearer\s+[A-Za-z0-9._\-]+/gi, 'Authorization: Bearer [REDACTED]');
+}
+
+function _redactErrorInPlace(err) {
+  if (!err || typeof err !== 'object') return err;
+  if (err.message) err.message = _redactBearer(err.message);
+  if (typeof err.stdout === 'string') err.stdout = _redactBearer(err.stdout);
+  if (typeof err.stderr === 'string') err.stderr = _redactBearer(err.stderr);
+  return err;
+}
+
+async function runAdoGit(project, gitArgs, opts = {}) {
+  const { acquireAdoTokenSync, _runGit, ...callerOpts } = opts;
+  const runGit = _runGit || shared.shellSafeGit;
+  const baseExtra = Array.isArray(callerOpts.gitExtraArgs) ? callerOpts.gitExtraArgs : [];
+  const adoOpts = { acquireAdoTokenSync };
+
+  const firstExtra = baseExtra.concat(getAdoGitExtraArgs(project, adoOpts));
+  const firstOpts = firstExtra.length ? { ...callerOpts, gitExtraArgs: firstExtra } : callerOpts;
+  try {
+    return await runGit(gitArgs, firstOpts);
+  } catch (err) {
+    if (!isAdoProject(project) || !isAdoAuthFailure(err)) {
+      throw _redactErrorInPlace(err);
+    }
+    // Token may have expired mid-dispatch — refresh and retry exactly once.
+    invalidateAdoTokenCache();
+    _backoffUntil = 0; // give the retry a chance to actually hit the token source
+    const refreshedExtra = getAdoGitExtraArgs(project, adoOpts);
+    if (!refreshedExtra.length) {
+      throw _redactErrorInPlace(err);
+    }
+    const retryExtra = baseExtra.concat(refreshedExtra);
+    try {
+      return await runGit(gitArgs, { ...callerOpts, gitExtraArgs: retryExtra });
+    } catch (err2) {
+      throw _redactErrorInPlace(err2);
+    }
+  }
+}
+
+// ── Test seams ──────────────────────────────────────────────────────────────
+
+function _setTokenForTest(token) {
+  if (token == null) { _cached = null; _backoffUntil = 0; return; }
+  _cached = { token: String(token), expiresAt: Date.now() + TOKEN_TTL_MS };
+  _backoffUntil = 0;
+}
+
+function _clearTokenCache() {
+  _cached = null;
+  _backoffUntil = 0;
+}
+
+function _isBackedOff() { return Date.now() < _backoffUntil; }
+
+module.exports = {
+  getAdoGitExtraArgs,
+  invalidateAdoTokenCache,
+  isAdoAuthFailure,
+  runAdoGit,
+  isAdoProject,
+  _setTokenForTest,
+  _clearTokenCache,
+  _isBackedOff,
+  TOKEN_TTL_MS,
+  ACQUIRE_BACKOFF_MS,
+  ADO_AUTH_PATTERNS,
+};

package/engine/cli.js

@@ -90,6 +90,32 @@ function summarizeActiveDispatchPids(activeItems = []) {
   return summary;
 }
 
+// W-mpcyvff6000pf828 (#2653) — Heartbeat writer decoupled from tickInner.
+// `writeHeartbeatNow` mirrors the legacy in-tick write (synchronous, fast,
+// non-throwing) but is driven from the main start loop on a 15s setInterval
+// instead. See engine.js#tickInner for the load-bearing rationale comment.
+const HEARTBEAT_INTERVAL_MS = 15000;
+
+function writeHeartbeatNow() {
+  try {
+    // Synchronous callback inside the lock — just `s.heartbeat = Date.now()`,
+    // no awaits, no other state mutation. Mirrors mutateControl's contract.
+    shared.mutateControl(c => { c.heartbeat = Date.now(); return c; });
+  } catch (err) {
+    try { engine().log('warn', `write heartbeat: ${err.message}`); }
+    catch { /* during shutdown logger can be torn down — silent */ }
+  }
+}
+
+// Factory used by tests to drive the heartbeat interval without spinning up
+// the full engine start loop. Returns the underlying timer so callers (the
+// real start handler in production, tests in unit/engine-heartbeat.test.js)
+// can clearInterval(...) on shutdown. Default to the production cadence.
+function createHeartbeatInterval(intervalMs = HEARTBEAT_INTERVAL_MS, writer = writeHeartbeatNow) {
+  return setInterval(writer, intervalMs);
+}
+
+
 function createControlOwner(pid = process.pid) {
   return { pid, ownerToken: `${pid}-${shared.uid()}` };
 }
@@ -872,6 +898,18 @@ const commands = {
     // Start tick loop
     const tickTimer = setInterval(() => e.tick(), interval);
 
+    // W-mpcyvff6000pf828 (#2653) — Heartbeat decoupled from tickInner.
+    // The dashboard flips the engine badge to STALE when
+    // `Date.now() - control.heartbeat > 120000`; tying the write to tickInner
+    // meant any legitimately slow tick (cold runtime spawn, sequential
+    // ADO/gh polls, slow worktree create) blocked the next heartbeat and
+    // surfaced a healthy engine as crashed. We now write every 15s on a
+    // dedicated interval — 8× headroom vs the 120s threshold even under
+    // event-loop pressure, and orders of magnitude under TICK_TIMEOUT_MS so
+    // a hung tick still looks distinct from a wedged event loop.
+    writeHeartbeatNow(); // prime control.heartbeat immediately
+    const heartbeatTimer = setInterval(writeHeartbeatNow, HEARTBEAT_INTERVAL_MS);
+
     // Fast poll: check steering every 1s (lightweight — just fs.stat per agent)
     // and wakeup signals every 1s (control.json read)
     const { checkSteering } = require('./timeout');
@@ -948,6 +986,7 @@ const commands = {
       console.log(`\n${signal} received — initiating graceful shutdown...`);
       clearInterval(tickTimer);
       clearInterval(fastPollTimer);
+      clearInterval(heartbeatTimer);
       for (const f of _watchedFiles) { try { fs.unwatchFile(f); } catch { /* cleanup */ } }
       const stoppingAt = e.ts();
       const stoppingWrite = markControlStoppingForOwner(controlOwner, stoppingAt);
@@ -1799,4 +1838,8 @@ module.exports = {
   _readDispatchPid: readDispatchPid,
   _normalizeSessionBranch: normalizeSessionBranch,
   _dispatchSessionBranch: dispatchSessionBranch,
+  // W-mpcyvff6000pf828 (#2653) — heartbeat writer + factory exported for tests
+  _writeHeartbeatNow: writeHeartbeatNow,
+  _createHeartbeatInterval: createHeartbeatInterval,
+  _HEARTBEAT_INTERVAL_MS: HEARTBEAT_INTERVAL_MS,
 };

package/engine/dispatch.js

@@ -343,6 +343,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
     const neverRetry = new Set([
       FAILURE_CLASS.CONFIG_ERROR,
       FAILURE_CLASS.PERMISSION_BLOCKED,
+      FAILURE_CLASS.AUTH, // W-mpcuc8i80003a7b3 — git/network credential failure; mechanical retry won't fix missing az / GCM creds
       FAILURE_CLASS.WORKTREE_PREFLIGHT, // pre-spawn worktree validation — recompute will produce the same failure
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, // W-mp6k7ywi000fa33c — keep-pids cwd is not a real git worktree; re-running won't fix the structural issue
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA, // W-mp7i902u000l991f — keep-pids.json failed shape validation; re-running with the same wrong file won't fix it
@@ -653,6 +654,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.OUT_OF_CONTEXT]: 'context window exhausted',
             [FAILURE_CLASS.CONFIG_ERROR]: 'configuration error',
             [FAILURE_CLASS.PERMISSION_BLOCKED]: 'permission or auth failure',
+            [FAILURE_CLASS.AUTH]: 'ADO/git authentication failed (missing or expired credentials)',
             [FAILURE_CLASS.WORKTREE_PREFLIGHT]: 'worktree preflight rejected (nested in project root or rootDir collapsed to drive root)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR]: 'keep_processes cwd is not a real git worktree (rerun in a `git worktree add` directory)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA]: 'keep-pids.json failed shape validation (wrong keys/types/values — see inbox alert for the canonical shape)',

package/engine/lifecycle.js

@@ -12,6 +12,7 @@ const { safeRead, safeJson, safeJsonNoRestore, safeWrite, mutateJsonFileLocked,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
 const { trackEngineUsage } = require('./llm');
 const { resolveRuntime } = require('./runtimes');
+const adoGitAuth = require('./ado-git-auth');
 const queries = require('./queries');
 const { isBranchActive } = require('./cooldown');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
@@ -2104,7 +2105,11 @@ async function rebaseBranchOntoMain(pr, project, config) {
   }
   const wtRoot = path.resolve(root, config.engine?.worktreeRoot || ENGINE_DEFAULTS.worktreeRoot);
   const tmpWt = path.join(wtRoot, `rebase-${shared.sanitizeBranch(branch)}-${Date.now()}`).replace(/\\/g, '/');
-  const _gitOpts = { cwd: root, timeout: 30000, windowsHide: true };
+  // W-mpcuc8i80003a7b3 — thread ADO bearer-token args through every remote-touching
+  // git op in the rebase flow so headless post-merge rebase against ADO origin
+  // survives missing GCM creds. For GitHub/local projects this is a no-op.
+  const _gitExtraArgs = adoGitAuth.getAdoGitExtraArgs(project);
+  const _gitOpts = { cwd: root, timeout: 30000, windowsHide: true, gitExtraArgs: _gitExtraArgs };
 
   // Refuse to create a worktree nested in the project root — would cause
   // glob/grep tools running with cwd=root to match both copies of every file
@@ -2135,8 +2140,8 @@ async function rebaseBranchOntoMain(pr, project, config) {
   }
 
   try {
-    await shared.shellSafeGit(['rebase', `origin/${validatedMain}`], { cwd: tmpWt, timeout: 120000, windowsHide: true });
-    await shared.shellSafeGit(['push', '--force-with-lease', 'origin', validatedBranch], { cwd: tmpWt, timeout: 30000, windowsHide: true });
+    await shared.shellSafeGit(['rebase', `origin/${validatedMain}`], { cwd: tmpWt, timeout: 120000, windowsHide: true, gitExtraArgs: _gitExtraArgs });
+    await shared.shellSafeGit(['push', '--force-with-lease', 'origin', validatedBranch], { cwd: tmpWt, timeout: 30000, windowsHide: true, gitExtraArgs: _gitExtraArgs });
     log('info', `Post-merge rebase: rebased ${branch} onto ${mainBranch} and force-pushed`);
     return { success: true };
   } catch (err) {

package/engine/recovery.js

@@ -28,6 +28,12 @@ const RECOVERY_RECIPES = new Map([
     freshSession: false,
     description: 'Permission/trust gate blocked — requires human intervention',
   }],
+  [FAILURE_CLASS.AUTH, {
+    maxAttempts: 0,
+    escalation: ESCALATION_POLICY.NO_RETRY,
+    freshSession: false,
+    description: 'Git/network authentication failed (missing az login, expired token, GCM prompt) — requires human credential fix before retry',
+  }],
   [FAILURE_CLASS.MERGE_CONFLICT, {
     maxAttempts: 2,
     escalation: ESCALATION_POLICY.RETRY_SAME,

package/engine/shared.js

@@ -1232,8 +1232,15 @@ function shellSafeGit(args, opts = {}) {
   if (!Array.isArray(args)) {
     return Promise.reject(new TypeError('shellSafeGit: args must be an array'));
   }
-  const { timeout, ...rest } = opts;
-  return _execFileAsync('git', args, {
+  // W-mpcuc8i80003a7b3 — `gitExtraArgs` is prepended to the git argv so callers
+  // can inject per-invocation `-c key=value` flags (e.g. ADO bearer-token
+  // auth header) without rewriting every shellSafeGit call site. Strip the
+  // key before delegating so it never reaches Node's execFile options.
+  const { timeout, gitExtraArgs, ...rest } = opts;
+  const finalArgs = (Array.isArray(gitExtraArgs) && gitExtraArgs.length > 0)
+    ? [...gitExtraArgs, ...args]
+    : args;
+  return _execFileAsync('git', finalArgs, {
     windowsHide: true,
     encoding: 'utf8',
     shell: false,
@@ -1249,9 +1256,13 @@ function shellSafeGitSync(args, opts = {}) {
   if (!Array.isArray(args)) {
     throw new TypeError('shellSafeGitSync: args must be an array');
   }
-  const { timeout, ...rest } = opts;
+  // W-mpcuc8i80003a7b3 — mirror the gitExtraArgs plumbing from the async variant.
+  const { timeout, gitExtraArgs, ...rest } = opts;
+  const finalArgs = (Array.isArray(gitExtraArgs) && gitExtraArgs.length > 0)
+    ? [...gitExtraArgs, ...args]
+    : args;
   const { execFileSync: _execFileSync } = require('child_process');
-  return _execFileSync('git', args, {
+  return _execFileSync('git', finalArgs, {
     windowsHide: true,
     encoding: 'utf8',
     shell: false,
@@ -2307,6 +2318,7 @@ const AGENT_STATUS = {
 const FAILURE_CLASS = {
   CONFIG_ERROR: 'config-error',           // Exit code 78, CLI not found, bad config
   PERMISSION_BLOCKED: 'permission-blocked', // Trust gate, permission denied, auth failure
+  AUTH: 'auth',                           // W-mpcuc8i80003a7b3: git/network credential failure (e.g. ADO bearer-token acquire or GCM prompt) — structural, never retryable mechanically
   MERGE_CONFLICT: 'merge-conflict',       // Git merge conflict in worktree or dependency
   BUILD_FAILURE: 'build-failure',         // Compilation, lint, or test failure
   TIMEOUT: 'timeout',                     // Hard runtime timeout or stale-orphan timeout

package/engine.js

@@ -30,6 +30,7 @@ const { exec, execAsync, execSilent, runFile, ts, ENGINE_DEFAULTS,
   FAILURE_CLASS } = shared;
 const { resolveRuntime } = require('./engine/runtimes');
 const { assertStaleHeadOk } = require('./engine/spawn-agent');
+const adoGitAuth = require('./engine/ado-git-auth');
 const queries = require('./engine/queries');
 
 // ─── Paths ──────────────────────────────────────────────────────────────────
@@ -194,6 +195,64 @@ function parseConflictFiles(mergeOutput) {
   return [...new Set(files)]; // dedupe
 }
 
+// Build the work item used by the dep-merge-failure auto-queue path
+// (W-mpcwojgr000a0244). Routes the conflict-fix through the shared-branch
+// dispatch path (`branchStrategy: 'shared-branch'` + `featureBranch:
+// depConflictBranch`) so spawnAgent's `git worktree add <wt> origin/<branch>`
+// (engine.js:1113) checks out the dep's existing branch directly. Commits land
+// back on that branch via `git push`, the existing PR picks them up, and no
+// redundant fresh-branch PR is opened.
+//
+// Cross-project caveat: the project field is stamped from the blocked item's
+// project. If the dep PR lives in a DIFFERENT project, the agent would still
+// be spawned in the blocked item's worktree root. That is a PRE-EXISTING
+// limitation of the dep-conflict-fix path — single-project plans (the common
+// case, and the trigger scenario P-wi1-bridge-readonly-{a,b,c}) are unaffected.
+function buildDepConflictFixItem({
+  depConflictBranch,
+  depConflictFiles = [],
+  isInterDepConflict = false,
+  preflightConflictPrev = null,
+  mainBranch,
+  blockedItem = null,
+  projectName = null,
+}) {
+  if (!depConflictBranch) throw new Error('buildDepConflictFixItem: depConflictBranch is required');
+  if (!mainBranch) throw new Error('buildDepConflictFixItem: mainBranch is required');
+  const conflictFixId = `conflict-fix-${depConflictBranch.replace(/[^a-zA-Z0-9-]/g, '-')}`;
+  const filesDesc = depConflictFiles.length > 0
+    ? `\n\nConflicting files:\n${depConflictFiles.map(f => '- ' + f).join('\n')}`
+    : '';
+  // Wording is explicit that the agent must push to the SAME branch — the
+  // shared-branch dispatch path puts them directly on `depConflictBranch`, so
+  // a fresh branch / new PR would defeat the whole point of this auto-queue.
+  const conflictFixDesc = isInterDepConflict && preflightConflictPrev
+    ? `Branch \`${depConflictBranch}\` conflicts with dependency branch \`${preflightConflictPrev}\`. Your worktree is already checked out on \`${depConflictBranch}\`. Rebase \`${depConflictBranch}\` onto \`${preflightConflictPrev}\` (or merge \`${preflightConflictPrev}\` into \`${depConflictBranch}\`), resolve conflicts, then \`git push\` to the SAME branch (\`--force-with-lease\` ok after rebase). Do NOT create a new branch and do NOT open a new PR. The existing PR for \`${depConflictBranch}\` will pick up your commits automatically.`
+    : `Branch \`${depConflictBranch}\` conflicts with \`${mainBranch}\`. Your worktree is already checked out on this branch. Merge \`${mainBranch}\` into it, resolve conflicts, then \`git push\` to the SAME branch — do NOT create a new branch and do NOT open a new PR. The existing PR for \`${depConflictBranch}\` will pick up your commits automatically.`;
+  const blockedSuffix = blockedItem
+    ? `\n\nBlocked downstream item: \`${blockedItem.id}\` — ${blockedItem.title || ''}`
+    : '';
+  return {
+    id: conflictFixId,
+    title: `Fix merge conflict: ${depConflictBranch} conflicts with ${isInterDepConflict ? preflightConflictPrev : mainBranch}`,
+    type: WORK_TYPE.FIX,
+    priority: 'high',
+    status: WI_STATUS.PENDING,
+    description: `${conflictFixDesc}${filesDesc}${blockedSuffix}`,
+    created: ts(),
+    createdBy: 'engine:dep-conflict-fix',
+    // Route through the shared-branch dispatch path (engine.js:4629, :4681,
+    // :1113) so the agent operates on the dep's existing branch — pushing
+    // straight into the existing PR instead of opening a new one.
+    branchStrategy: 'shared-branch',
+    featureBranch: depConflictBranch,
+    _branch: depConflictBranch,
+    _blockedItem: blockedItem ? blockedItem.id : null,
+    _isInterDepConflict: !!isInterDepConflict,
+    project: projectName || null,
+  };
+}
+
 // Prune dep branches that are ancestors of other dep branches (#958)
 // When B already contains A's commits, merging both A and B causes conflicts.
 async function pruneAncestorDeps(deps, gitOpts, cwd) {
@@ -816,7 +875,12 @@ async function spawnAgent(dispatchItem, config) {
   let branchName = _preBranchName;
   const worktreeCreateTimeout = Math.max(60000, Number(engineConfig.worktreeCreateTimeout) || ENGINE_DEFAULTS.worktreeCreateTimeout);
   const worktreeCreateRetries = Math.max(0, Math.min(3, Number(engineConfig.worktreeCreateRetries) || ENGINE_DEFAULTS.worktreeCreateRetries));
-  const _gitOpts = { stdio: 'pipe', timeout: 30000, windowsHide: true, env: shared.gitEnv() };
+  // W-mpcuc8i80003a7b3 — for ADO projects, inject a per-invocation
+  // `-c http.<host>.extraHeader=Authorization: Bearer <token>` so headless
+  // git ops survive missing/expired Git Credential Manager state. Returns
+  // [] for GitHub/local projects so this is a no-op there.
+  const _adoGitExtraArgs = adoGitAuth.getAdoGitExtraArgs(project);
+  const _gitOpts = { stdio: 'pipe', timeout: 30000, windowsHide: true, env: shared.gitEnv(), gitExtraArgs: _adoGitExtraArgs };
   const _worktreeGitOpts = { ..._gitOpts, timeout: worktreeCreateTimeout };
 
   // Build the initial prompt before worktree setup, then refresh shared-branch
@@ -1173,6 +1237,12 @@ async function spawnAgent(dispatchItem, config) {
           let depMergeFailed = false;
           let depConflictBranch = null; // track which dep branch caused the conflict
           let depConflictFiles = [];    // conflicting file names parsed from git output
+          // W-mpcuc8i80003a7b3 — track whether ANY git op in the dep phase
+          // failed with an ADO auth signature. If so, we escalate as
+          // FAILURE_CLASS.AUTH (non-retryable + dedup'd inbox alert) instead
+          // of FAILURE_CLASS.MERGE_CONFLICT (which retries 3x against the
+          // same broken auth path).
+          let _depAuthFailed = false;
           // Fetch all dependency branches in parallel (git fetches are independent)
           const fetchable = depBranches.filter(d => !_failedRefCache.has(d.branch));
           const unfetchable = depBranches.filter(d => _failedRefCache.has(d.branch));
@@ -1188,7 +1258,10 @@ async function spawnAgent(dispatchItem, config) {
           }
           const fetchResults = await Promise.allSettled(
             fetchable.map(({ branch: depBranch }) =>
-              shared.shellSafeGit(['fetch', 'origin', depBranch], { ..._gitOpts, cwd: rootDir }).then(() => depBranch)
+              // runAdoGit for ADO projects auto-retries once on auth failure
+              // with a refreshed bearer token (handles mid-dispatch expiry).
+              // For non-ADO projects it's a thin pass-through to shellSafeGit.
+              adoGitAuth.runAdoGit(project, ['fetch', 'origin', depBranch], { ..._gitOpts, cwd: rootDir }).then(() => depBranch)
             )
           );
           const hasFetchFailures = fetchResults.some(r => r.status === 'rejected');
@@ -1221,6 +1294,12 @@ async function spawnAgent(dispatchItem, config) {
               }
               _failedRefCache.add(failedBranch);
               log('warn', `Failed to fetch dependency ${failedBranch}: ${errMsg}`);
+              // W-mpcuc8i80003a7b3 — detect ADO bearer-token / GCM credential
+              // failures so we escalate as FAILURE_CLASS.AUTH below instead of
+              // mis-classifying as a merge conflict and burning 3 retries.
+              if (adoGitAuth.isAdoAuthFailure(fetchResults[i].reason)) {
+                _depAuthFailed = true;
+              }
               depMergeFailed = true;
             }
           }
@@ -1302,6 +1381,11 @@ async function spawnAgent(dispatchItem, config) {
                 // Merge failed — possibly due to diverged history from a force-pushed (rebased) dep branch.
                 // Abort partial merge, reset worktree to clean main base, and re-merge all deps from scratch.
                 log('warn', `Merge of ${depBranch} into ${branchName} failed: ${mergeErr.message} — attempting reset and re-merge of all deps`);
+                // W-mpcuc8i80003a7b3 — defense in depth. `git merge origin/<dep>`
+                // is local so an auth failure here is unexpected, but mark the
+                // flag so the final dispatch failure routes through the AUTH
+                // path instead of MERGE_CONFLICT.
+                if (adoGitAuth.isAdoAuthFailure(mergeErr)) _depAuthFailed = true;
                 try { await shared.shellSafeGit(['merge', '--abort'], { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
                 const mainRef = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
                 try {
@@ -1316,6 +1400,7 @@ async function spawnAgent(dispatchItem, config) {
                 } catch (resetErr) {
                   const errOutput = (resetErr.message || '') + '\n' + (resetErr.stdout?.toString?.() || '') + '\n' + (resetErr.stderr?.toString?.() || '');
                   log('warn', `Failed to reset and re-merge deps for ${branchName}: ${resetErr.message}`);
+                  if (adoGitAuth.isAdoAuthFailure(resetErr)) _depAuthFailed = true;
                   try { await shared.shellSafeGit(['merge', '--abort'], { ..._gitOpts, cwd: worktreePath }); } catch (_) { /* no merge in progress */ }
                   // Post-mortem: incremental simulation to identify which dep caused the conflict (#958)
                   // Uses same chained merge-tree approach as pre-flight to catch inter-dep conflicts
@@ -1366,6 +1451,58 @@ async function spawnAgent(dispatchItem, config) {
           _phaseT.depMergeEnd = Date.now();
           if (depMergeFailed) {
             _cleanupPromptFiles();
+            // W-mpcuc8i80003a7b3 — short-circuit to AUTH classification when any
+            // git op in the dep phase looked like an ADO credential failure.
+            // This BYPASSES the merge-conflict path entirely: no retries (auth
+            // is structural — re-running won't fix missing az / GCM creds),
+            // no conflict-fix WI (would just re-trigger the same auth wall),
+            // and a single dedup'd inbox alert pointing at the recovery steps.
+            if (_depAuthFailed) {
+              const projName = project.name || 'unknown';
+              const authFailReason = `ADO git authentication failed for project ${projName}: dependency fetch could not authenticate to origin (likely missing/expired az CLI token, no cached GCM credentials, or token broker unavailable in headless context)`;
+              try {
+                writeInboxAlert(`ado-auth-${projName}`, [
+                  `# ADO git authentication failed — ${projName}`,
+                  '',
+                  `Work item: \`${meta?.item?.id || '(unknown)'}\``,
+                  `Branch: \`${branchName || '(unknown)'}\``,
+                  '',
+                  '## Symptom',
+                  '',
+                  'Engine could not fetch dependency branches from the ADO origin. ',
+                  'Git Credential Manager has no cached credentials and falls back to ',
+                  'a TTY prompt, which the headless engine cannot satisfy:',
+                  '',
+                  '```',
+                  "fatal: could not read Username for 'https://<adoOrg>.visualstudio.com'",
+                  '```',
+                  '',
+                  '## Recovery',
+                  '',
+                  'From an interactive shell on the engine host, refresh ADO credentials:',
+                  '',
+                  '```bash',
+                  '# Option A — Azure CLI (preferred)',
+                  'az login',
+                  'az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv',
+                  '',
+                  '# Option B — azureauth (corp environments)',
+                  'azureauth ado token --mode iwa --mode broker --output token --timeout 1',
+                  '```',
+                  '',
+                  'Once a valid token can be acquired, the engine will pick it up automatically on the next tick (30-min cache + 10-min acquire backoff).',
+                  '',
+                  '## Why no auto-retry',
+                  '',
+                  'This dispatch is failed as `FAILURE_CLASS.AUTH` (non-retryable). Mechanical retry would burn slots against the same broken credential path. After you fix the credentials, manually retry the work item via the dashboard or `/api/work-items/retry`.',
+                ].join('\n'));
+              } catch (alertErr) {
+                log('warn', `Failed to write ADO auth inbox alert: ${alertErr.message}`);
+              }
+              completeDispatch(id, DISPATCH_RESULT.ERROR, authFailReason, '', { failureClass: FAILURE_CLASS.AUTH, agentRetryable: false });
+              cleanupTempAgent(agentId);
+              return;
+            }
             // Build actionable failReason identifying the conflicting branch and files (#958)
             const mainBranch = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
             let failReason = 'Dependency merge failed';
@@ -1380,39 +1517,29 @@ async function spawnAgent(dispatchItem, config) {
             }
             completeDispatch(id, DISPATCH_RESULT.ERROR, failReason, '', { failureClass: FAILURE_CLASS.MERGE_CONFLICT });
 
-            // Auto-queue conflict-fix work item when a specific dep branch is identified
+            // Auto-queue conflict-fix work item when a specific dep branch is identified.
+            // Routes through the shared-branch dispatch path (see buildDepConflictFixItem)
+            // so commits land on the dep's existing PR branch (W-mpcwojgr000a0244).
             if (depConflictBranch && meta?.item?.id && project) {
               try {
                 const wiPath = project.name
                   ? projectWorkItemsPath(project)
                   : path.join(MINIONS_DIR, 'work-items.json');
-                const conflictFixId = `conflict-fix-${depConflictBranch.replace(/[^a-zA-Z0-9-]/g, '-')}`;
-                const filesDesc = depConflictFiles.length > 0
-                  ? `\n\nConflicting files:\n${depConflictFiles.map(f => '- ' + f).join('\n')}`
-                  : '';
-                // Inter-dep conflict: rebase onto the conflicting dep; dep-vs-main: merge main (#958)
-                const conflictFixDesc = _isInterDepConflict && _preflightConflictPrev
-                  ? `Branch \`${depConflictBranch}\` conflicts with dependency branch \`${_preflightConflictPrev}\`. Rebase \`${depConflictBranch}\` onto \`${_preflightConflictPrev}\` (or merge \`${_preflightConflictPrev}\` into \`${depConflictBranch}\`) and resolve conflicts, then push.`
-                  : `Branch \`${depConflictBranch}\` conflicts with \`${mainBranch}\`. Merge ${mainBranch} into the branch and resolve conflicts, then push.`;
+                const newItem = buildDepConflictFixItem({
+                  depConflictBranch,
+                  depConflictFiles,
+                  isInterDepConflict: _isInterDepConflict,
+                  preflightConflictPrev: _preflightConflictPrev,
+                  mainBranch,
+                  blockedItem: meta.item,
+                  projectName: project.name || null,
+                });
                 mutateWorkItems(wiPath, items => {
                   // Don't create duplicate conflict-fix items
-                  const existing = items.find(i => i.id === conflictFixId && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED && i.status !== WI_STATUS.CANCELLED);
+                  const existing = items.find(i => i.id === newItem.id && i.status !== WI_STATUS.DONE && i.status !== WI_STATUS.FAILED && i.status !== WI_STATUS.CANCELLED);
                   if (existing) return;
-                  items.push({
-                    id: conflictFixId,
-                    title: `Fix merge conflict: ${depConflictBranch} conflicts with ${_isInterDepConflict ? _preflightConflictPrev : mainBranch}`,
-                    type: WORK_TYPE.FIX,
-                    priority: 'high',
-                    status: WI_STATUS.PENDING,
-                    description: `${conflictFixDesc}${filesDesc}\n\nBlocked downstream item: \`${meta.item.id}\` — ${meta.item.title || ''}`,
-                    created: ts(),
-                    createdBy: 'engine:dep-conflict-fix',
-                    _branch: depConflictBranch,
-                    _blockedItem: meta.item.id,
-                    _isInterDepConflict: _isInterDepConflict || false,
-                    project: project.name || null,
-                  });
-                  log('info', `Auto-queued conflict-fix work item ${conflictFixId} for ${depConflictBranch} (blocked: ${meta.item.id})`);
+                  items.push(newItem);
+                  log('info', `Auto-queued conflict-fix work item ${newItem.id} for ${depConflictBranch} (blocked: ${meta.item.id})`);
                 });
               } catch (e) { log('warn', `Failed to auto-queue conflict-fix: ${e.message}`); }
             }
@@ -3981,16 +4108,24 @@ async function discoverFromPrs(config, project) {
       const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
       const lastHumanDispatch = pr._lastDispatchByCause?.[shared.PR_FIX_CAUSE.HUMAN_FEEDBACK];
       const currentCommentId = String(pr.humanFeedback?.lastProcessedCommentId || '');
-      if (lastHumanDispatch?.outcome === 'noop'
+      // Issue #2632: this same-head/same-comment guard MUST be cause-local. A
+      // previous `continue` here aborted the whole PR iteration and starved
+      // the build-failure / re-review / conflict-fix evaluation blocks below
+      // (live repro on ADO PR `office-bohemia#5215610`: had `buildStatus=failing`
+      // + `buildFailureSignature` but no `build-fix-*` dispatch was ever
+      // queued). Skip only the human-feedback dispatch path; leave
+      // `fixDispatched=false` so downstream causes are still evaluated.
+      const skipHumanFeedback = !!(lastHumanDispatch?.outcome === 'noop'
         && lastHumanDispatch.headSha
         && currentHeadSha
         && lastHumanDispatch.headSha === currentHeadSha
         && lastHumanDispatch.lastProcessedCommentId
         && currentCommentId
-        && lastHumanDispatch.lastProcessedCommentId === currentCommentId) {
+        && lastHumanDispatch.lastProcessedCommentId === currentCommentId);
+      if (skipHumanFeedback) {
         log('info', `Skipping human-feedback fix for ${pr.id}: last human-feedback dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} and same comment ${currentCommentId.slice(0, 32)} (${(lastHumanDispatch.reason || '').slice(0, 120)})`);
-        continue;
       }
+      if (!skipHumanFeedback) {
       const key = humanFixKey;
       if (isPrAutomationCauseHandledOrPending(project, pr, humanCauseKey)) continue;
       let staleCoalesced = [];
@@ -4035,6 +4170,7 @@ async function discoverFromPrs(config, project) {
         review_note: reviewNote,
       }, `Fix ${pr.id}: ${pr.title || ''} — human feedback`, { dispatchKey: key, automationCauseKey: humanCauseKey, source: 'pr-human-feedback', pr, branch: prBranch, project: projMeta });
       if (item) { newWork.push(item); fixDispatched = true; }
+      } // end if (!skipHumanFeedback) — cause-local guard for #2632
     }
 
     // Re-review after fix: trigger when a fix was pushed after the last minions review,
@@ -4150,13 +4286,18 @@ async function discoverFromPrs(config, project) {
       // a new commit landed (live repro on PR #2433).
       const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
       const lastBuildDispatch = pr._lastDispatchByCause?.[shared.PR_FIX_CAUSE.BUILD_FAILURE];
-      if (lastBuildDispatch?.outcome === 'noop'
+      // Issue #2632 audit: cause-local guard. A previous `continue` here
+      // aborted the whole PR iteration and starved the conflict-fix block
+      // below — symmetric to the human-feedback bug. Skip only the build-fix
+      // dispatch path; downstream merge-conflict resolution must still run.
+      const skipBuildFix = !!(lastBuildDispatch?.outcome === 'noop'
         && lastBuildDispatch.headSha
         && currentHeadSha
-        && lastBuildDispatch.headSha === currentHeadSha) {
+        && lastBuildDispatch.headSha === currentHeadSha);
+      if (skipBuildFix) {
         log('info', `Skipping build-fix for ${pr.id}: last build-failure dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} (${(lastBuildDispatch.reason || '').slice(0, 120)})`);
-        continue;
       }
+      if (!skipBuildFix) {
       const buildCauseKey = getPrAutomationCauseKey('build', pr);
       const key = getPrAutomationDispatchKey(`build-fix-${project?.name || 'default'}-${prDisplayId}`, buildCauseKey);
       if (isPrAutomationCauseHandledOrPending(project, pr, buildCauseKey)) continue;
@@ -4245,6 +4386,7 @@ async function discoverFromPrs(config, project) {
           });
         } catch (e) { log('warn', 'mark build fail notified: ' + e.message); }
       }
+      } // end if (!skipBuildFix) — cause-local guard for #2632 audit
     }
 
     // PRs with merge conflicts — dispatch fix to resolve (gated by provider polling + autoFixConflicts)
@@ -5724,12 +5866,15 @@ async function tickInner() {
     process.exit(0);
   }
 
-  // Write heartbeat so dashboard can detect stale engine
-  try { mutateControl(c => ({ ...c, heartbeat: Date.now() })); } catch (e) { log('warn', 'write heartbeat: ' + e.message); }
+  // W-mpcyvff6000pf828 (#2653) — control.heartbeat is written by a dedicated
+  // 15s interval in engine/cli.js (createHeartbeatWriter), decoupled from
+  // tickInner so a slow tick (cold runtime spawn, sequential PR polls, slow
+  // worktree create) cannot starve heartbeats and flip the dashboard to STALE
+  // on an otherwise healthy engine.
 
   // P-c2e5a1d9-a — Initial wiring guard: bail immediately if a force-release
-  // reclaimed our lock while the heartbeat write was in flight. Per-phase
-  // guards inside the rest of tickInner are sub-task -b's scope.
+  // reclaimed our lock while the startup control-state read was in flight.
+  // Per-phase guards inside the rest of tickInner are sub-task -b's scope.
   if (_isTickStale(myGeneration)) return;
 
   const config = getConfig();
@@ -6400,6 +6545,7 @@ module.exports = {
   // Shared helpers (used by lifecycle.js and tests)
   reconcileItemsWithPrs, detectDependencyCycles,
   parseConflictFiles, pruneAncestorDeps, preflightMergeSimulation, // exported for testing
+  buildDepConflictFixItem, // exported for testing (W-mpcwojgr000a0244)
   isWorktreeRetryableError, removeStaleIndexLock, syncReusedWorktree, assertCleanSharedWorktree, // exported for testing
   pruneStaleWorktreeForBranch, // exported for testing
   _maxTurnsForType, buildProjectContext, normalizeAc, _buildAgentSpawnFlags, _classifyAgentFailure, // exported for testing

package/package.json

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