@yemi33/minions 0.1.1659 → 0.1.1661

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1661 (2026-05-01)
+
+### Other
+- Harden Copilot steering resume flow
+
+## 0.1.1660 (2026-05-01)
+
+### Fixes
+- less rigid agent orphan detection
+
 ## 0.1.1659 (2026-05-01)
 
 ### Other

package/engine/cli.js

@@ -21,6 +21,17 @@ function engine() {
 let _dispatchModule = null;
 function dispatchModule() { if (!_dispatchModule) _dispatchModule = require('./dispatch'); return _dispatchModule; }
 
+function normalizeSessionBranch(branch) {
+  if (!branch) return null;
+  return String(branch).replace(/^refs\/heads\//, '');
+}
+
+function dispatchSessionBranch(item) {
+  return normalizeSessionBranch(
+    item?.meta?.branch || item?.branch || item?.meta?.item?.branch || item?.meta?.item?.featureBranch
+  );
+}
+
 function isEngineProcessAlive(control) {
   if (!control?.pid) return false;
   if (control.pid === process.pid) return true;
@@ -396,13 +407,21 @@ const commands = {
         }
 
         if (agentPid) {
-          // Load sessionId from session.json for steering support
+          // Load sessionId from session.json for steering support, but only
+          // when its saved branch still matches the active dispatch branch.
           let sessionId = null;
           try {
             const sj = safeJson(path.join(AGENTS_DIR, agentId, 'session.json'));
-            if (sj?.sessionId) sessionId = sj.sessionId;
+            const expectedBranch = dispatchSessionBranch(item);
+            const savedBranch = normalizeSessionBranch(sj?.branch);
+            if (sj?.sessionId && (!expectedBranch || savedBranch === expectedBranch)) {
+              sessionId = sj.sessionId;
+            } else if (sj?.sessionId && expectedBranch) {
+              shared.log('warn', `Reattach: ignoring session for ${agentId} on branch ${savedBranch || 'unknown'}; expected ${expectedBranch}`);
+            }
           } catch {}
-          e.activeProcesses.set(item.id, { proc: { pid: agentPid > 0 ? agentPid : null }, agentId, startedAt: item.created_at, reattached: true, sessionId });
+          const runtimeName = item.runtimeName || item.runtime || item.meta?.runtimeName || item.meta?.runtime || null;
+          e.activeProcesses.set(item.id, { proc: { pid: agentPid > 0 ? agentPid : null }, agentId, startedAt: item.created_at, reattached: true, sessionId, runtimeName });
           // Sync work item status to dispatched — atomic write to avoid lifecycle lazy init issues
           if (item.meta?.item?.id && item.meta?.project?.localPath) {
             try {

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-01T05:34:43.680Z"
+  "cachedAt": "2026-05-01T06:25:57.091Z"
 }

package/engine/llm.js

@@ -163,7 +163,14 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
     maxBudget, bare, fallbackModel,
     stream, disableBuiltinMcps, suppressAgentsMd, reasoningSummaries,
   };
-  const finalPrompt = runtime.buildPrompt(promptText, sysPromptText);
+  // Capability-gate per-flag opts before prompt construction so adapters can
+  // make resume-aware prompt decisions from the same opts used for argv.
+  if (!caps.effortLevels) adapterOpts.effort = undefined;
+  if (!caps.sessionResume) adapterOpts.sessionId = undefined;
+  if (!caps.budgetCap) adapterOpts.maxBudget = undefined;
+  if (!caps.bareMode) adapterOpts.bare = undefined;
+  if (!caps.fallbackModel) adapterOpts.fallbackModel = undefined;
+  const finalPrompt = runtime.buildPrompt(promptText, sysPromptText, adapterOpts);
 
   // ── Direct path ──
   const resolved = direct ? _resolveBin(runtime) : null;
@@ -178,13 +185,6 @@ function _spawnProcess(promptText, sysPromptText, callOpts) {
       cleanupFiles.push(sysTmpPath);
       adapterOpts.sysPromptFile = sysTmpPath;
     }
-    // Capability-gate per-flag opts so the Claude path keeps emitting its
-    // historical flag set while Copilot only sees what it understands.
-    if (!caps.effortLevels) adapterOpts.effort = undefined;
-    if (!caps.sessionResume) adapterOpts.sessionId = undefined;
-    if (!caps.budgetCap) adapterOpts.maxBudget = undefined;
-    if (!caps.bareMode) adapterOpts.bare = undefined;
-    if (!caps.fallbackModel) adapterOpts.fallbackModel = undefined;
     // promptViaArg=true: the adapter splices `--prompt <text>` into args itself.
     if (caps.promptViaArg) adapterOpts.prompt = finalPrompt;
 

package/engine/runtimes/claude.js

@@ -581,6 +581,8 @@ const capabilities = {
   streaming: true,
   // `--resume <session-id>` resumes a previous turn
   sessionResume: true,
+  // Emits a resumable session ID before the terminal result event
+  midRunSessionId: true,
   // Accepts the system prompt via `--system-prompt-file`
   systemPromptFile: true,
   // Honours `--effort low|medium|high|xhigh`

package/engine/runtimes/copilot.js

@@ -344,8 +344,9 @@ function classifyFailure({ code, stdout = '', stderr = '', fallback } = {}) {
 // convention from Anthropic tool-use docs and is recognized as "system role"
 // content by every model in the Copilot catalog.
 
-function buildPrompt(promptText, sysPromptText) {
+function buildPrompt(promptText, sysPromptText, opts = {}) {
   const user = promptText == null ? '' : String(promptText);
+  if (opts && opts.sessionId) return user;
   if (sysPromptText == null || sysPromptText === '') return user;
   return `<system>\n${String(sysPromptText)}\n</system>\n\n${user}`;
 }
@@ -722,6 +723,8 @@ const capabilities = {
   streaming: true,
   // --resume=<id> resumes a session
   sessionResume: true,
+  // Copilot only exposes sessionId on the terminal result event
+  midRunSessionId: false,
   // No --system-prompt-file flag — system prompt is merged into stdin
   systemPromptFile: false,
   // --effort low|medium|high|xhigh (no 'max' — adapter maps it)

package/engine/shared.js

@@ -721,7 +721,19 @@ const ENGINE_DEFAULTS = {
   inboxConsolidateThreshold: 5,
   agentTimeout: 18000000,  // 5h
   heartbeatTimeout: 300000, // 5min — stale-orphan grace after process tracking is lost
-  heartbeatTimeouts: {}, // optional per-type stale-orphan overrides; merged at runtime (see timeout.js)
+  // 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
+  // restart). We give them headroom up to a typical build+tests cycle. Short-running types
+  // (decompose / meeting / etc.) keep the 5-min default by simply not appearing here.
+  heartbeatTimeouts: {
+    implement:       900000, // 15min — refactors, multi-file edits, builds
+    'implement:large': 900000, // 15min — same class of work, larger scope
+    fix:             900000, // 15min — fix runs often include builds + retries
+    test:            900000, // 15min — build-and-test against existing PR
+    verify:          900000, // 15min — full project verification cycle
+    plan:            600000, // 10min — research-heavy
+  },
   maxTurns: 100,
   worktreeCreateTimeout: 300000, // 5min for git worktree add on large Windows repos
   worktreeCreateRetries: 1, // retry once on transient timeout/lock races
@@ -785,7 +797,6 @@ const ENGINE_DEFAULTS = {
   copilotReasoningSummaries: false,  // Copilot --enable-reasoning-summaries (Anthropic-family models only)
   maxBudgetUsd: undefined,       // fleet USD ceiling for --max-budget-usd (per-agent override: agents.<id>.maxBudgetUsd). Honors 0 via ?? so a literal cap of $0 works
   disableModelDiscovery: false,  // skip runtime.listModels() REST calls fleet-wide (settings UI falls back to free-text)
-  heartbeatTimeouts: {},
   maxPendingContexts: 20, // cap pendingContexts arrays in cooldowns.json to prevent unbounded growth
   maxPendingContextEntryBytes: 256 * 1024, // 256 KB — cap each pendingContexts entry to prevent huge PR comments from bloating cooldowns.json
   maxDispatchPromptBytes: 1024 * 1024, // 1 MB — dispatch items with prompts larger than this sidecar to engine/contexts/ to prevent dispatch.json OOM (#1167)
@@ -2083,27 +2094,60 @@ function upsertPullRequestRecord(prPath, entry, { project = null, itemId = null,
 
 // ─── Cross-Platform Process Kill Helpers ─────────────────────────────────────
 
+function normalizeKillPid(proc) {
+  const pid = Number(proc?.pid);
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function unixChildPids(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return [];
+  try {
+    return _execSync(`pgrep -P ${pid}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 })
+      .split(/\r?\n/)
+      .map(line => Number(line.trim()))
+      .filter(childPid => Number.isInteger(childPid) && childPid > 0 && childPid !== pid);
+  } catch {
+    return [];
+  }
+}
+
+function killUnixProcessTree(pid, signal, seen = new Set()) {
+  if (!Number.isInteger(pid) || pid <= 0 || seen.has(pid)) return;
+  seen.add(pid);
+  for (const childPid of unixChildPids(pid)) {
+    killUnixProcessTree(childPid, signal, seen);
+  }
+  try { process.kill(pid, signal); } catch { /* process may be dead */ }
+}
+
+function unrefTimer(timer) {
+  if (timer && typeof timer.unref === 'function') timer.unref();
+  return timer;
+}
+
 function killGracefully(proc, graceMs = 5000) {
-  if (!proc || !proc.pid) return;
+  const pid = normalizeKillPid(proc);
+  if (!pid) return;
   if (process.platform === 'win32') {
-    try { _execSync(`taskkill /PID ${proc.pid} /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
-    setTimeout(() => {
-      try { _execSync(`taskkill /PID ${proc.pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
-    }, graceMs);
+    try { _execSync(`taskkill /PID ${pid} /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+    unrefTimer(setTimeout(() => {
+      try { _execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+    }, graceMs));
   } else {
-    try { proc.kill('SIGTERM'); } catch { /* process may be dead */ }
-    setTimeout(() => {
-      try { proc.kill('SIGKILL'); } catch { /* process may be dead */ }
-    }, graceMs);
+    killUnixProcessTree(pid, 'SIGTERM');
+    unrefTimer(setTimeout(() => {
+      killUnixProcessTree(pid, 'SIGKILL');
+    }, graceMs));
   }
 }
 
 function killImmediate(proc) {
-  if (!proc || !proc.pid) return;
+  const pid = normalizeKillPid(proc);
+  if (!pid) return;
   if (process.platform === 'win32') {
-    try { _execSync(`taskkill /PID ${proc.pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
+    try { _execSync(`taskkill /PID ${pid} /F /T`, { stdio: 'pipe', timeout: 3000, windowsHide: true }); } catch { /* process may be dead */ }
   } else {
-    try { proc.kill('SIGKILL'); } catch { /* process may be dead */ }
+    killUnixProcessTree(pid, 'SIGKILL');
   }
 }
 

package/engine/spawn-agent.js

@@ -100,9 +100,9 @@ function parseSpawnArgs(argv) {
  *   }
  */
 function buildSpawnInvocation({ runtime, resolved, promptText, sysPromptText, opts, passthrough, addDirs }) {
-  const finalPrompt = runtime.buildPrompt(promptText, sysPromptText);
   const adapterOpts = { ...opts };
   if (Array.isArray(addDirs) && addDirs.length) adapterOpts.addDirs = addDirs;
+  const finalPrompt = runtime.buildPrompt(promptText, sysPromptText, adapterOpts);
   const deliveryMode = typeof runtime.getPromptDeliveryMode === 'function'
     ? runtime.getPromptDeliveryMode(adapterOpts)
     : (runtime.capabilities && runtime.capabilities.promptViaArg ? 'arg' : 'stdin');

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, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
+  ENGINE_DEFAULTS, ENGINE_DIR, WI_STATUS, WORK_TYPE, DISPATCH_RESULT, AGENT_STATUS } = shared;
 const { getDispatch, getAgentStatus } = queries;
 const AGENTS_DIR = queries.AGENTS_DIR;
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -57,6 +57,27 @@ function checkIdleThreshold(config) {
 // How long to wait for a steered agent to exit before retrying the kill
 const STEERING_KILL_RETRY_MS = 30000;
 
+function runtimeSupportsMidRunSessionId(info) {
+  if (typeof info?.midRunSessionId === 'boolean') return info.midRunSessionId;
+  if (typeof info?.runtime?.capabilities?.midRunSessionId === 'boolean') return info.runtime.capabilities.midRunSessionId;
+  if (info?.runtimeName) {
+    try {
+      const { resolveRuntime } = require('./runtimes');
+      const runtime = resolveRuntime(info.runtimeName);
+      if (typeof runtime.capabilities?.midRunSessionId === 'boolean') return runtime.capabilities.midRunSessionId;
+    } catch {
+      return true;
+    }
+  }
+  return true;
+}
+
+function rememberDeferredSteering(info, steerEntry) {
+  const existing = new Set(Array.isArray(info._deferredSteeringFiles) ? info._deferredSteeringFiles : []);
+  if (steerEntry?.path) existing.add(steerEntry.path);
+  info._deferredSteeringFiles = Array.from(existing);
+}
+
 function checkSteering(config) {
   const activeProcesses = engine().activeProcesses;
   for (const [id, info] of activeProcesses) {
@@ -79,7 +100,10 @@ function checkSteering(config) {
     // Skip if already being steered (prevents double-kill race)
     if (info._steeringMessage || info._steeringAt) continue;
 
-    const alreadyPending = new Set((info._pendingSteeringFiles || []).map(entry => entry.path || entry));
+    const alreadyPending = new Set([
+      ...(info._pendingSteeringFiles || []).map(entry => entry.path || entry),
+      ...(info._deferredSteeringFiles || []),
+    ]);
     const unread = steering.listUnreadSteeringMessages(info.agentId);
     for (const empty of unread.filter(entry => !entry.message.trim())) {
       shared.safeUnlink(empty.path);
@@ -90,8 +114,19 @@ function checkSteering(config) {
 
     const sessionId = info.sessionId;
     if (!sessionId) {
-      // No session to resume — kill agent and leave message unread in inbox for retry.
-      // Previously this silently skipped for up to 5m then deleted the message (#627).
+      if (!runtimeSupportsMidRunSessionId(info)) {
+        log('info', `Steering: no mid-run sessionId for ${info.agentId} (${id}) — queued until resumable checkpoint`);
+        rememberDeferredSteering(info, steerEntry);
+        try {
+          const liveLogPath = path.join(AGENTS_DIR, info.agentId, 'live-output.log');
+          fs.appendFileSync(liveLogPath, `\n[steering] Message received. This runtime has not emitted a resumable session yet, so the message is queued until the agent reaches a resumable checkpoint or the next dispatch.\n`);
+        } catch { /* optional */ }
+        continue;
+      }
+
+      // No session to resume for a runtime that should have emitted one — kill
+      // agent and leave message unread in inbox for retry. Previously this
+      // silently skipped for up to 5m then deleted the message (#627).
       log('info', `Steering: no sessionId for ${info.agentId} (${id}) — killing and keeping unread message in inbox`);
 
       // Append to live output so user sees confirmation in the dashboard
@@ -142,6 +177,23 @@ function isTrackedProcessAlive(procInfo) {
   }
 }
 
+// Last-resort liveness check via the on-disk PID file (engine/tmp/pid-<safeId>.pid).
+// Used by orphan detection to avoid false-positive kills when the engine has lost the
+// tracked process handle (engine restart, never-tracked spawn, etc.) but the OS-level
+// child process is still alive and healthy. The safeId here mirrors engine.js spawn
+// (id.replace(/[:\\/*?"<>|]/g, '-')) — same pattern engine/cli.js uses to re-attach.
+function isOsPidAliveForDispatch(itemId) {
+  const safeId = String(itemId || '').replace(/[:\\/*?"<>|]/g, '-');
+  const pidPath = path.join(ENGINE_DIR, 'tmp', `pid-${safeId}.pid`);
+  let raw;
+  try { raw = fs.readFileSync(pidPath, 'utf8'); }
+  catch { return false; }
+  const pid = parseInt(String(raw).trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
 function checkTimeouts(config) {
   const activeProcesses = engine().activeProcesses;
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
@@ -335,6 +387,11 @@ function checkTimeouts(config) {
     } catch { /* ENOENT — keep default */ }
 
     if (!processAlive && silentMs > staleOrphanTimeout && (Date.now() > engineRestartGraceUntil || engineRestartGraceExempt?.has(item.id))) {
+      // Last-resort PID check: lost tracked handle but OS process may still be alive.
+      if (isOsPidAliveForDispatch(item.id)) {
+        log('info', `Orphan check: ${item.agent} (${item.id}) silent ${silentSec}s but OS PID is alive — keeping [${_logState}]`);
+        continue;
+      }
       // No tracked process AND no recent output past stale-orphan timeout AND (grace period expired OR confirmed-dead at restart) → orphaned
       log('warn', `Orphan detected: ${item.agent} (${item.id}) — no live process tracked, silent for ${silentSec}s [${_logState}]`);
       dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
@@ -424,4 +481,5 @@ module.exports = {
   checkTimeouts,
   checkSteering,
   checkIdleThreshold,
+  isOsPidAliveForDispatch,
 };

package/engine.js

@@ -1043,6 +1043,16 @@ async function spawnAgent(dispatchItem, config) {
     fs.appendFileSync(liveOutputPath, `[${new Date().toISOString()}] pid: ${proc.pid ?? 'unknown'}\n`);
   } catch { /* log stamp is best-effort — don't block spawn on fs failure */ }
 
+  const initialProcInfo = {
+    proc,
+    agentId,
+    startedAt,
+    runtimeName,
+    sessionId: cachedSessionId,
+    _pendingSteeringFiles: pendingSteering.entries,
+  };
+  activeProcesses.set(id, initialProcInfo);
+
   const MAX_OUTPUT = 1024 * 1024; // 1MB
   let stdout = '';
   let stderr = '';
@@ -1204,6 +1214,7 @@ async function spawnAgent(dispatchItem, config) {
         proc: resumeProc,
         agentId,
         startedAt: procInfo.startedAt,
+        runtimeName,
         sessionId: steerSessionId,
         lastRealOutputAt: Date.now(),
         _pendingSteeringFiles: mergePendingSteeringEntries(
@@ -1446,12 +1457,15 @@ async function spawnAgent(dispatchItem, config) {
   // realActivityMap was already seeded immediately after runFile() returned (#W-mo25loq8kjer);
   // don't re-seed here — the stdout/stderr handlers above can already have updated it with
   // a fresher timestamp, and overwriting would clobber the real "last activity" signal.
+  const existingProcInfo = activeProcesses.get(id) || {};
   activeProcesses.set(id, {
+    ...existingProcInfo,
     proc,
     agentId,
     startedAt,
-    sessionId: cachedSessionId,
-    _pendingSteeringFiles: pendingSteering.entries,
+    runtimeName,
+    sessionId: existingProcInfo.sessionId || cachedSessionId,
+    _pendingSteeringFiles: mergePendingSteeringEntries(existingProcInfo._pendingSteeringFiles, pendingSteering.entries),
   });
 
   updateAgentStatus(id, AGENT_STATUS.RUNNING, `Process spawned for ${agentId}`);

package/package.json

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