@yemi33/minions 0.1.1684 → 0.1.1685

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1685 (2026-05-02)
+
+### Features
+- harden agent completion sentinel (#1990)
+
 ## 0.1.1684 (2026-05-02)
 
 ### Other

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-02T16:47:10.817Z"
+  "cachedAt": "2026-05-02T18:11:21.378Z"
 }

package/engine/spawn-agent.js

@@ -128,6 +128,57 @@ function normalizeRuntimeExit(code, signal) {
   return 1;
 }
 
+const PROCESS_EXIT_SENTINEL_FLUSH_TIMEOUT_MS = 2000;
+
+function formatProcessExitSentinel(exitCode, signal) {
+  return `\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`;
+}
+
+function _appendSentinelFallback(outputPath, sentinel) {
+  if (!outputPath) return false;
+  try {
+    fs.appendFileSync(outputPath, sentinel);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _writeStdoutWithTimeout(stdout, sentinel, timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (flushed) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(flushed);
+    };
+    const timer = setTimeout(() => finish(false), Math.max(0, timeoutMs));
+    try {
+      if (!stdout || typeof stdout.write !== 'function') {
+        finish(false);
+        return;
+      }
+      stdout.write(sentinel, () => finish(true));
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+async function writeProcessExitSentinel({
+  exitCode,
+  signal = null,
+  stdout = process.stdout,
+  outputPath = process.env.MINIONS_LIVE_OUTPUT_PATH,
+  timeoutMs = PROCESS_EXIT_SENTINEL_FLUSH_TIMEOUT_MS,
+} = {}) {
+  const sentinel = formatProcessExitSentinel(exitCode, signal);
+  const stdoutFlushed = await _writeStdoutWithTimeout(stdout, sentinel, timeoutMs);
+  const outputPathWritten = stdoutFlushed ? false : _appendSentinelFallback(outputPath, sentinel);
+  return { sentinel, stdoutFlushed, outputPathWritten };
+}
+
 // ─── Main script execution ──────────────────────────────────────────────────
 
 function _installHint(name, runtime) {
@@ -287,20 +338,23 @@ function main() {
   }, MCP_STARTUP_TIMEOUT);
   proc.stdout.once('data', () => { gotFirstOutput = true; clearTimeout(startupTimer); });
 
-  proc.on('close', (code, signal) => {
+  proc.on('close', async (code, signal) => {
     clearTimeout(startupTimer);
     const exitCode = normalizeRuntimeExit(code, signal);
-    // Write process-exit sentinel to stdout so the engine can detect completion (#716).
-    try { process.stdout.write(`\n[process-exit] code=${exitCode}${signal ? ` signal=${signal}` : ''}\n`); } catch { /* stdout may be closed */ }
+    const sentinelResult = await writeProcessExitSentinel({ exitCode, signal });
     fs.appendFileSync(debugPath, `EXIT: code=${exitCode}${signal ? ` signal=${signal}` : ''}\nSTDERR: ${stderrBuf.slice(0, 500)}\n`);
+    if (!sentinelResult.stdoutFlushed && sentinelResult.outputPathWritten) {
+      fs.appendFileSync(debugPath, `EXIT SENTINEL FALLBACK: ${process.env.MINIONS_LIVE_OUTPUT_PATH}\n`);
+    }
     process.exit(exitCode);
   });
-  proc.on('error', (err) => {
+  proc.on('error', async (err) => {
     fs.appendFileSync(debugPath, `ERROR: ${err.message}\n`);
+    await writeProcessExitSentinel({ exitCode: 1 });
     process.exit(1);
   });
 }
 
-module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit };
+module.exports = { parseSpawnArgs, buildSpawnInvocation, normalizeRuntimeExit, writeProcessExitSentinel };
 
 if (require.main === module) main();

package/engine/timeout.js

@@ -217,6 +217,38 @@ function parseProcessExitCode(logText) {
   return lastMatch[1] === 'spawn-failed' ? -1 : parseInt(lastMatch[1], 10);
 }
 
+function terminalResultIndicatesError(obj) {
+  const subtype = String(obj?.subtype || '');
+  const terminalReason = String(obj?.terminal_reason || obj?.terminalReason || '');
+  return obj?.is_error === true ||
+    /^error/i.test(subtype) ||
+    /max[_-]?turns|error|fail|cancel|timeout/i.test(terminalReason);
+}
+
+function parseTerminalResultFallbackExitCode(logText) {
+  if (!logText) return null;
+  let exitCode = null;
+  for (const line of String(logText).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || !trimmed.includes('"result"') ||
+        (!trimmed.includes('terminal_reason') && !trimmed.includes('terminalReason'))) continue;
+
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj?.type === 'result' && (obj.terminal_reason || obj.terminalReason) && terminalResultIndicatesError(obj)) {
+        exitCode = 1;
+      }
+      continue;
+    } catch { /* fall through to regex fallback for diagnostic-prefixed JSON */ }
+
+    if (/"type"\s*:\s*"result"/.test(trimmed) &&
+        /"terminal_?reason"\s*:\s*"[^"]*(?:max[_-]?turns|error|fail|cancel|timeout)[^"]*"/i.test(trimmed)) {
+      exitCode = 1;
+    }
+  }
+  return exitCode;
+}
+
 function checkTimeouts(config) {
   const activeProcesses = engine().activeProcesses;
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
@@ -411,6 +443,12 @@ function checkTimeouts(config) {
           completeFromOutput(item, liveLogPath, processExitCode, fullLog, hasProcess);
           continue;
         }
+        const terminalResultExitCode = parseTerminalResultFallbackExitCode(fullLog);
+        if (terminalResultExitCode !== null) {
+          log('info', `Agent ${item.agent} (${item.id}) completed via stale terminal result fallback (exit code ${terminalResultExitCode})`);
+          completeFromOutput(item, liveLogPath, terminalResultExitCode, fullLog, hasProcess);
+          continue;
+        }
       } catch (e) { log('warn', 'orphan final output completion scan: ' + e.message); }
 
       // No tracked process AND no recent output past stale-orphan timeout AND (grace period expired OR confirmed-dead at restart) → orphaned

package/engine.js

@@ -995,6 +995,7 @@ async function spawnAgent(dispatchItem, config) {
   //   2. Log has stub only    → process started but died before its first write
   //   3. Log has stub + ...   → process alive but hung (the only case that warrants orphan kill+retry)
   const liveOutputPath = path.join(AGENTS_DIR, agentId, 'live-output.log');
+  childEnv.MINIONS_LIVE_OUTPUT_PATH = liveOutputPath;
 
   // Rotate previous live output to preserve session history (fixes #543: orphan recovery overwrites)
   // Only rotate if the existing file has meaningful content (beyond just the header stub)
@@ -1186,6 +1187,7 @@ async function spawnAgent(dispatchItem, config) {
       const spawnScript = path.join(ENGINE_DIR, 'spawn-agent.js');
       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();

package/package.json

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