@yemi33/minions 0.1.1691 → 0.1.1692

package/CHANGELOG.md

@@ -1,8 +1,10 @@
 # Changelog
 
-## 0.1.1691 (2026-05-04)
+## 0.1.1692 (2026-05-04)
 
 ### Features
+- stop Azure auth for GitHub agents (#2005)
+- recover stalled runtime resumes (#2004)
 - preserve doc-chat response fragments (#2003)
 
 ## 0.1.1689 (2026-05-03)

package/README.md

@@ -310,6 +310,10 @@ Agents inherit MCP servers directly from `~/.claude.json` as Claude Code process
 
 Manually refresh with `minions mcp-sync`.
 
+### GitHub Users
+
+For GitHub repos, install and authenticate the [GitHub CLI](https://cli.github.com/). Agents should use `gh` for GitHub PR creation, PR lookup, comments, reviews, issues, and workflow checks. If GitHub or Copilot auth fails, refresh GitHub credentials with `gh auth status` and `gh auth login`, or provide `GH_TOKEN`/`COPILOT_GITHUB_TOKEN` from the environment. Azure DevOps authentication and tooling paths do not apply to GitHub repo work.
+
 ### Azure DevOps Users
 
 For the best experience with ADO repos, install the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) with the Azure DevOps extension. Agents should use the `az` CLI first for Azure DevOps operations such as PR creation, PR lookup, comments, reviewers, work items, and pipelines. Use the Azure DevOps MCP fallback only when `az` is unavailable in the environment or insufficient for a specific action.

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-04T01:58:05.343Z"
+  "cachedAt": "2026-05-04T01:58:58.614Z"
 }

package/engine/playbook.js

@@ -407,16 +407,27 @@ function renderPlaybook(type, vars) {
   const dispatchProject = (vars.repo_id && projects.find(p => p.repositoryId === vars.repo_id))
     || (vars.repo_name && projects.find(p => p.repoName === vars.repo_name))
     || projects[0] || {};
+  const renderProject = {
+    ...dispatchProject,
+    adoOrg: vars.ado_org || vars.adoOrg || dispatchProject.adoOrg,
+    adoProject: vars.ado_project || vars.adoProject || dispatchProject.adoProject,
+    repoName: vars.repo_name || vars.repoName || dispatchProject.repoName,
+    repoHost: vars.repo_host || vars.repoHost || dispatchProject.repoHost,
+  };
+  const repoHost = getRepoHost(renderProject);
   const projectVars = {
-    project_name: dispatchProject.name || 'Unknown Project',
-    ado_org: dispatchProject.adoOrg || 'Unknown',
-    ado_project: dispatchProject.adoProject || 'Unknown',
-    repo_name: dispatchProject.repoName || 'Unknown',
-    pr_create_instructions: getPrCreateInstructions(dispatchProject),
-    pr_comment_instructions: getPrCommentInstructions(dispatchProject),
-    pr_fetch_instructions: getPrFetchInstructions(dispatchProject),
-    pr_vote_instructions: getPrVoteInstructions(dispatchProject),
-    repo_host_label: getRepoHostLabel(dispatchProject),
+    project_name: renderProject.name || 'Unknown Project',
+    ado_org: renderProject.adoOrg || 'Unknown',
+    ado_project: renderProject.adoProject || 'Unknown',
+    repo_name: renderProject.repoName || 'Unknown',
+    repo_host: repoHost,
+    ado_shared_rules: repoHost === 'ado' ? '1' : '',
+    github_shared_rules: repoHost === 'github' ? '1' : '',
+    pr_create_instructions: getPrCreateInstructions(renderProject),
+    pr_comment_instructions: getPrCommentInstructions(renderProject),
+    pr_fetch_instructions: getPrFetchInstructions(renderProject),
+    pr_vote_instructions: getPrVoteInstructions(renderProject),
+    repo_host_label: getRepoHostLabel(renderProject),
   };
   const allVars = { ...projectVars, ...vars };
 
@@ -640,6 +651,7 @@ function buildBaseVars(agentId, config, project) {
     ado_org: project?.adoOrg || 'Unknown',
     ado_project: project?.adoProject || 'Unknown',
     repo_name: project?.repoName || 'Unknown',
+    repo_host: getRepoHost(project),
     main_branch: project?.mainBranch || 'main',
     date: dateStamp(),
   };

package/engine/runtimes/copilot.js

@@ -545,7 +545,7 @@ function parseError(rawOutput) {
   const lower = text.toLowerCase();
 
   if (/not authenticated|copilot login|please.*log.*in|401|403 forbidden|unauthorized/i.test(text)) {
-    return { message: 'Copilot authentication failed', code: 'auth-failure', retriable: false };
+    return { message: 'Copilot/GitHub authentication failed. Run `gh auth login` or provide GH_TOKEN/COPILOT_GITHUB_TOKEN with Copilot access.', code: 'auth-failure', retriable: false };
   }
   if (/rate limit|too many requests|\b429\b/i.test(text)) {
     return { message: 'Copilot rate limit hit', code: 'rate-limit', retriable: true };

package/engine/shared.js

@@ -751,6 +751,7 @@ const ENGINE_DEFAULTS = {
   inboxConsolidateThreshold: 5,
   agentTimeout: 18000000,  // 5h
   heartbeatTimeout: 300000, // 5min — stale-orphan grace after process tracking is lost
+  resumeHeartbeatTimeout: 300000, // 5min — max wait for a resumed runtime to emit its first output
   // Per-type stale-orphan overrides (merged with config.engine.heartbeatTimeouts at runtime — see timeout.js).
   // Heavy work types (multi-file edits, builds, test suites, full verify cycles) routinely go quiet for
   // longer than the 5-min default when the engine has lost their tracked handle (e.g. across an engine
@@ -1310,10 +1311,13 @@ function projectPrPath(project) {
 }
 
 function resolveProjectForPrPath(filePath, config = null) {
-  const resolvedPath = path.resolve(filePath);
+  const resolvedPaths = new Set([path.resolve(filePath)]);
+  if (filePath && !path.isAbsolute(filePath)) {
+    resolvedPaths.add(path.resolve(MINIONS_DIR, filePath));
+  }
   const projects = getProjects(config);
   for (const project of projects) {
-    if (path.resolve(projectPrPath(project)) === resolvedPath) return project;
+    if (resolvedPaths.has(path.resolve(projectPrPath(project)))) return project;
   }
   if (projects.length === 1) return projects[0];
   return null;

package/engine/spawn-agent.js

@@ -129,6 +129,10 @@ function normalizeRuntimeExit(code, signal) {
   return 1;
 }
 
+function shouldInjectAdoTokenEnv(env = process.env) {
+  return String(env.MINIONS_REPO_HOST || '').trim().toLowerCase() === 'ado';
+}
+
 function injectAdoTokenEnv(env, { execSync: _execSync, acquireToken, warn = (msg) => process.stderr.write(msg + '\n') } = {}) {
   let result;
   try {
@@ -149,6 +153,11 @@ function injectAdoTokenEnv(env, { execSync: _execSync, acquireToken, warn = (msg
   return true;
 }
 
+function injectAdoTokenEnvForRepoHost(env, opts) {
+  if (!shouldInjectAdoTokenEnv(env)) return false;
+  return injectAdoTokenEnv(env, opts);
+}
+
 const PROCESS_EXIT_SENTINEL_FLUSH_TIMEOUT_MS = 2000;
 
 function formatProcessExitSentinel(exitCode, signal) {
@@ -251,7 +260,7 @@ function main() {
   const { promptFile, sysPromptFile, runtimeName, opts, passthrough } = parsed;
 
   const env = cleanChildEnv();
-  injectAdoTokenEnv(env);
+  injectAdoTokenEnvForRepoHost(env);
 
   let runtime;
   try { runtime = resolveRuntime(runtimeName); }
@@ -399,6 +408,6 @@ function main() {
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, injectAdoTokenEnv, writeProcessExitSentinel, computeAddDirs };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, shouldInjectAdoTokenEnv, injectAdoTokenEnv, injectAdoTokenEnvForRepoHost, writeProcessExitSentinel, computeAddDirs };
 
 if (require.main === module) main();

package/engine/timeout.js

@@ -9,7 +9,7 @@ const queries = require('./queries');
 const steering = require('./steering');
 
 const { safeRead, safeWrite, safeJson, mutateJsonFileLocked, getProjects, projectWorkItemsPath, log, ts,
-  ENGINE_DEFAULTS, ENGINE_DIR, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
+  ENGINE_DEFAULTS, ENGINE_DIR, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS, FAILURE_CLASS } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -258,6 +258,7 @@ function checkTimeouts(config) {
 
   const timeout = config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout;
   const defaultStaleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
+  const runtimeResumeHeartbeatTimeout = config.engine?.resumeHeartbeatTimeout || ENGINE_DEFAULTS.resumeHeartbeatTimeout || defaultStaleOrphanTimeout;
 
   // Optional per-type stale-orphan timeouts: merge ENGINE_DEFAULTS ← config overrides.
   const perTypeStaleOrphanTimeouts = { ...ENGINE_DEFAULTS.heartbeatTimeouts, ...(config.engine?.heartbeatTimeouts || {}) };
@@ -274,8 +275,10 @@ function checkTimeouts(config) {
   }
 
   // 2. Stale-orphan check — for ALL active dispatch items (catches lost process handles after restart).
-  //    Silence is not a failure for tracked live processes: long CLI commands can legitimately
-  //    produce no stdout/stderr for extended periods.
+  //    Silence is not a failure for tracked live processes once a runtime has emitted output:
+  //    long CLI commands can legitimately produce no stdout/stderr for extended periods.
+  //    The exception is a resumed runtime that has not produced its first stdout/stderr
+  //    heartbeat after spawn; that is the "alive but stuck in --resume" failure mode.
   const dispatchData = getDispatch();
   const deadItems = [];
   const legacyAnnotationClears = new Set();
@@ -332,8 +335,9 @@ function checkTimeouts(config) {
     const liveLogPath = path.join(AGENTS_DIR, item.agent, 'live-output.log');
     let lastActivity = item.started_at ? new Date(item.started_at).getTime() : 0;
 
-    // live-output.log mtime is only used for stale-orphan cleanup and completion recovery.
-    // It is not used as an output-silence timeout for live tracked processes.
+    // live-output.log mtime is used for stale-orphan cleanup, completion recovery,
+    // and the resume first-output watchdog. It is not a general output-silence
+    // timeout for live tracked processes.
     try {
       const stat = fs.statSync(liveLogPath);
       lastActivity = Math.max(lastActivity, stat.mtimeMs);
@@ -394,6 +398,23 @@ function checkTimeouts(config) {
     if (procInfo?._steeringAt && Date.now() - procInfo._steeringAt < 60000) continue;
 
     if (processAlive) {
+      if (procInfo?._runtimeResumeAwaitingFirstOutput) {
+        const resumeStartedAt = Number(procInfo._runtimeResumeAt || 0);
+        const resumeHeartbeatAt = Math.max(lastActivity, resumeStartedAt);
+        const resumeSilentMs = Date.now() - resumeHeartbeatAt;
+        if (resumeSilentMs > runtimeResumeHeartbeatTimeout) {
+          const resumeSilentSec = Math.round(resumeSilentMs / 1000);
+          const reason = `Runtime resume stalled — no output heartbeat for ${resumeSilentSec}s`;
+          log('warn', `Runtime resume stalled: ${item.agent} (${item.id}) — no output heartbeat for ${resumeSilentSec}s; killing and retrying fresh`);
+          dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, reason);
+          try { fs.appendFileSync(liveLogPath, `\n[runtime-resume-timeout] ${reason}. Killing this resume attempt and retrying with a fresh session.\n`); } catch { /* optional */ }
+          // Clear the cached session so retry does not re-enter the same stuck --resume path.
+          try { shared.safeUnlink(path.join(AGENTS_DIR, item.agent, 'session.json')); } catch {}
+          activeProcesses.delete(item.id);
+          shared.killGracefully(procInfo.proc, 5000);
+          deadItems.push({ item, reason, failureClass: FAILURE_CLASS.TIMEOUT });
+        }
+      }
       continue;
     }
 
@@ -462,8 +483,8 @@ function checkTimeouts(config) {
   }
 
   // Clean up dead items
-  for (const { item, reason } of deadItems) {
-    completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason);
+  for (const { item, reason, failureClass } of deadItems) {
+    completeDispatch(item.id, DISPATCH_RESULT.ERROR, reason, '', failureClass ? { failureClass } : {});
   }
 
   // Clear legacy blocking-tool annotations; process liveness no longer depends on tool parsing.

package/engine.js

@@ -135,7 +135,7 @@ const { getRouting, parseRoutingTable, getRoutingTableCached, getMonthlySpend,
 const { renderPlaybook, validatePlaybookVars, PLAYBOOK_REQUIRED_VARS,
   buildSystemPrompt, buildAgentContext, selectPlaybook,
   buildBaseVars, buildPrDispatch, resolveTaskContext,
-  getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
+  getRepoHost, getRepoHostLabel, getRepoHostToolRule } = require('./engine/playbook');
 
 // sanitizeBranch imported from shared.js
 
@@ -975,13 +975,16 @@ async function spawnAgent(dispatchItem, config) {
   // Spawn the claude process
   const childEnv = shared.cleanChildEnv();
   if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
+  childEnv.MINIONS_REPO_HOST = getRepoHost(project);
 
-  // Inject cached ADO token so agents skip re-authentication (#998)
-  // getAdoToken() returns cached token (30-min TTL) or null — never blocks on browser auth
-  try {
-    const adoToken = await getAdoToken();
-    if (adoToken) childEnv.MINIONS_ADO_TOKEN = adoToken;
-  } catch { /* non-fatal — agent can still authenticate on its own */ }
+  if (getRepoHost(project) === 'ado') {
+    // Inject cached ADO token so ADO agents skip re-authentication (#998).
+    // getAdoToken() returns cached token (30-min TTL) or null — never blocks on browser auth.
+    try {
+      const adoToken = await getAdoToken();
+      if (adoToken) childEnv.MINIONS_ADO_TOKEN = adoToken;
+    } catch { /* non-fatal — agent can still authenticate on its own */ }
+  }
 
   // Spawn via wrapper script — node directly (no bash intermediary)
   // spawn-agent.js handles CLAUDECODE env cleanup and claude binary resolution
@@ -1052,6 +1055,10 @@ async function spawnAgent(dispatchItem, config) {
     startedAt,
     runtimeName,
     sessionId: cachedSessionId,
+    ...(cachedSessionId ? {
+      _runtimeResumeAt: Date.now(),
+      _runtimeResumeAwaitingFirstOutput: true,
+    } : {}),
     _pendingSteeringFiles: pendingSteering.entries,
   };
   activeProcesses.set(id, initialProcInfo);
@@ -1063,6 +1070,12 @@ async function spawnAgent(dispatchItem, config) {
   let _trustCheckDone = false;
   const _spawnTime = Date.now();
 
+  function markRuntimeResumeOutputSeen(procInfo) {
+    if (!procInfo?._runtimeResumeAwaitingFirstOutput) return;
+    procInfo._runtimeResumeAwaitingFirstOutput = false;
+    procInfo.lastRealOutputAt = Date.now();
+  }
+
   proc.stdout.on('data', (data) => {
     const chunk = data.toString();
     realActivityMap.set(id, Date.now());
@@ -1086,6 +1099,7 @@ async function spawnAgent(dispatchItem, config) {
     // Capture sessionId early for mid-session steering. Claude emits session_id;
     // Copilot emits sessionId, so use the runtime-neutral steering helper.
     const procInfo = activeProcesses.get(id);
+    markRuntimeResumeOutputSeen(procInfo);
     captureSessionIdFromStdoutChunk(agentId, id, branchName, runtime, procInfo, chunk, sessionCaptureState);
 
     ackPendingSteeringFiles(agentId, procInfo, chunk);
@@ -1096,6 +1110,7 @@ async function spawnAgent(dispatchItem, config) {
     realActivityMap.set(id, Date.now());
     if (stderr.length < MAX_OUTPUT) stderr += chunk.slice(0, MAX_OUTPUT - stderr.length);
     try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch { /* optional */ }
+    markRuntimeResumeOutputSeen(activeProcesses.get(id));
   });
 
   async function onAgentClose(code) {
@@ -1188,11 +1203,14 @@ async function spawnAgent(dispatchItem, config) {
       const childEnv = shared.cleanChildEnv();
       if (completionReportPath) childEnv.MINIONS_COMPLETION_REPORT = completionReportPath;
       childEnv.MINIONS_LIVE_OUTPUT_PATH = liveOutputPath;
-      // Inject cached ADO token for steering session too (#998)
-      try {
-        const adoToken = await getAdoToken();
-        if (adoToken) childEnv.MINIONS_ADO_TOKEN = adoToken;
-      } catch { /* non-fatal */ }
+      childEnv.MINIONS_REPO_HOST = getRepoHost(project);
+      if (getRepoHost(project) === 'ado') {
+        // Inject cached ADO token for steering session too (#998)
+        try {
+          const adoToken = await getAdoToken();
+          if (adoToken) childEnv.MINIONS_ADO_TOKEN = adoToken;
+        } catch { /* non-fatal */ }
+      }
       let resumeProc;
       try {
         resumeProc = runFile(process.execPath, [spawnScript, steerPromptPath, sysPromptPath, ...resumeArgs], {
@@ -1220,7 +1238,8 @@ async function spawnAgent(dispatchItem, config) {
         startedAt: procInfo.startedAt,
         runtimeName,
         sessionId: steerSessionId,
-        lastRealOutputAt: Date.now(),
+        _runtimeResumeAt: Date.now(),
+        _runtimeResumeAwaitingFirstOutput: true,
         _pendingSteeringFiles: mergePendingSteeringEntries(
           procInfo._pendingSteeringFiles,
           pendingForResume.entries,
@@ -1239,6 +1258,7 @@ async function spawnAgent(dispatchItem, config) {
         if (stdout.length < MAX_OUTPUT) stdout += chunk.slice(0, MAX_OUTPUT - stdout.length);
         try { fs.appendFileSync(liveOutputPath, chunk); } catch { /* optional */ }
         const resumeInfo = activeProcesses.get(id);
+        markRuntimeResumeOutputSeen(resumeInfo);
         captureSessionIdFromStdoutChunk(agentId, id, branchName, runtime, resumeInfo, chunk, sessionCaptureState);
         ackPendingSteeringFiles(agentId, resumeInfo, chunk);
       });
@@ -1247,6 +1267,7 @@ async function spawnAgent(dispatchItem, config) {
         realActivityMap.set(id, Date.now());
         if (stderr.length < MAX_OUTPUT) stderr += chunk.slice(0, MAX_OUTPUT - stderr.length);
         try { fs.appendFileSync(liveOutputPath, '[stderr] ' + chunk); } catch { /* optional */ }
+        markRuntimeResumeOutputSeen(activeProcesses.get(id));
       });
 
       // Re-wire close handler for the resumed process

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1691",
+  "version": "0.1.1692",
   "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/playbooks/shared-rules.md

@@ -78,6 +78,38 @@ Concretely:
 - If you skipped local validation, say so in the completion JSON (e.g. `tests: skipped — relying on PR pipeline`) and still exit.
 - Holding a slot to watch a pipeline is wasted capacity; the engine has its own pipeline-monitoring path.
 
+{{#github_shared_rules}}
+## Checking PR and Build Status
+
+When asked to check build status, CI results, or review state for a PR:
+
+**Preferred — read cached state (refreshed every `prPollStatusEvery` ticks, default ~12 min when engine is running):**
+Find the PR in `projects/<project-name>/pull-requests.json` by `prNumber`. Key fields:
+- `buildStatus` — `passing` | `failing` | `running` | `none`
+- `buildFailReason` — failing check/pipeline name when `buildStatus` is `failing`; inspect live CI logs yourself for details
+- `reviewStatus` — `approved` | `changes-requested` | `waiting` | `pending`
+- `status` — `active` | `merged` | `abandoned`
+- `url` — link to the PR on GitHub
+
+**Live status (when engine isn't running or you need up-to-the-moment results):**
+```bash
+gh pr view <prNumber> --json number,title,state,mergeable,reviewDecision,headRefName,baseRefName,statusCheckRollup --repo OWNER/REPO
+```
+
+## GitHub Tooling and Auth
+
+For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as `gh pr create`, `gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`.
+
+If GitHub or Copilot auth fails, check GitHub/Copilot credentials only:
+- `gh auth status`
+- `gh auth login`
+- `gh auth token` (for token visibility checks only; do not paste tokens into logs)
+- Set `GH_TOKEN` or `COPILOT_GITHUB_TOKEN` only when the environment already provides an appropriate GitHub token.
+
+Only GitHub/Copilot authentication guidance applies to GitHub repository work.
+{{/github_shared_rules}}
+
+{{#ado_shared_rules}}
 ## Checking PR and Build Status
 
 When asked to check build status, CI results, or review state for a PR:
@@ -107,3 +139,4 @@ Output is JSON with the same fields. Exit 0 on success, 1 if not found.
 For Azure DevOps repo operations, use the `az` CLI first. Prefer commands such as `az repos pr create`, `az repos pr show`, `az repos pr list`, `az repos pr comment`, `az repos pr reviewer`, `az boards work-item`, and `az pipelines` after setting defaults with `az devops configure`.
 
 Use ADO MCP fallback tools (`mcp__azure-ado__*`) only when `az` is unavailable in the environment or insufficient for a specific operation. Do not choose MCP first just because it exists, and do not use `gh` for Azure DevOps repositories.
+{{/ado_shared_rules}}