@yemi33/minions 0.1.1683 → 0.1.1685

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1685 (2026-05-02)
+
+### Features
+- harden agent completion sentinel (#1990)
+
+## 0.1.1684 (2026-05-02)
+
+### Other
+- test(cooldown): add edge-case unit tests for _truncateContextEntry, loadCooldowns boundaries, isAlreadyDispatched (#1986)
+
 ## 0.1.1683 (2026-05-02)
 
 ### Fixes

package/engine/cooldown.js

@@ -201,4 +201,5 @@ module.exports = {
   clearCooldown,
   isAlreadyDispatched,
   isBranchActive,
+  _truncateContextEntry, // exported for testing
 };

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-02T15:30:24.792Z"
+  "cachedAt": "2026-05-02T18:11:21.378Z"
 }

package/engine/playbook.js

@@ -395,7 +395,7 @@ function renderPlaybook(type, vars) {
   content += '````\n```skill\n';
   content += `---\nname: short-descriptive-name\ndescription: One-line description of what this skill does\nallowed-tools: Bash, Read, Edit\ntrigger: when should an agent use this\nscope: minions\nproject: any\n---\n\n# Skill Title\n\n## Steps\n1. ...\n2. ...\n\n## Notes\n...\n`;
   content += '```\n````\n\n';
-  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to the selected runtime's native personal skills directory\n`;
+  content += `- Set \`scope: minions\` for cross-project or Minions-wide skills; the engine writes them to the selected runtime's native personal skills directory so they are available in normal runtime windows too\n`;
   content += `- Set \`scope: project\` + \`project: <name>\` only for repo-specific skills; the engine queues a PR to the selected runtime's native project skills directory\n`;
   content += `- Emit at most one skill block per task unless you uncovered two clearly distinct reusable workflows\n`;
   content += `- Do NOT create a skill for one-off bug fixes, isolated command output, obvious repo facts, or anything already covered by existing docs/playbooks/skills\n`;
@@ -546,7 +546,8 @@ function buildAgentContext(agentId, config, project) {
     context += `## Your Recent History (last 5 tasks)\n\n${trimmed}\n\n`;
   }
 
-  // Project conventions (from CLAUDE.md) — always relevant for code quality
+  // Project conventions and instruction files — explicit, inert context for
+  // every runtime. Runtime-native skills/commands stay in their native indexes.
   if (project.localPath) {
     appendContextFile('Project Conventions (from CLAUDE.md)', path.join(project.localPath, 'CLAUDE.md'), 8192);
     appendContextFile('Project Agent Instructions (from AGENTS.md)', path.join(project.localPath, 'AGENTS.md'), 8192,

package/engine/runtimes/claude.js

@@ -16,6 +16,9 @@
  *   - spawnScript: absolute path of the spawn wrapper (or null if direct-only)
  *   - buildArgs(opts) → string[] — CLI args excluding the binary
  *   - buildPrompt(promptText, sysPromptText) → string — final prompt delivered
+ *   - getUserAssetDirs(opts) → string[] — runtime-native global asset roots
+ *   - getSkillRoots(opts) → {scope,dir,projectName?}[] — skill discovery roots
+ *   - getSkillWriteTargets(opts) → {personal,project} — extraction targets
  *   - resolveModel(input) → string|undefined — shorthand expansion / passthrough
  *   - parseOutput(raw) → { text, usage, sessionId, model }
  *   - parseStreamChunk(line) → parsed event object or null
@@ -247,6 +250,31 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
+function getUserAssetDirs({ homeDir = os.homedir() } = {}) {
+  return [path.join(homeDir, '.claude')];
+}
+
+function getSkillRoots({ homeDir = os.homedir(), project = null } = {}) {
+  const roots = [
+    { scope: 'claude-code', dir: path.join(homeDir, '.claude', 'skills') },
+  ];
+  if (project?.localPath) {
+    roots.push({
+      scope: 'project',
+      projectName: project.name,
+      dir: path.join(project.localPath, '.claude', 'skills'),
+    });
+  }
+  return roots;
+}
+
+function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
+  return {
+    personal: path.join(homeDir, '.claude', 'skills'),
+    project: project?.localPath ? path.join(project.localPath, '.claude', 'skills') : null,
+  };
+}
+
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
   try {
@@ -322,29 +350,6 @@ function buildPrompt(promptText, /* sysPromptText */ _sys) {
   return String(promptText == null ? '' : promptText);
 }
 
-function getUserAssetDirs({ homeDir = os.homedir() } = {}) {
-  return [path.join(homeDir, '.claude')];
-}
-
-function getSkillRoots({ homeDir = os.homedir(), project = null } = {}) {
-  const roots = [{ dir: path.join(homeDir, '.claude', 'skills'), scope: 'claude-code' }];
-  if (project?.localPath) {
-    roots.push({
-      dir: path.resolve(project.localPath, '.claude', 'skills'),
-      scope: 'project',
-      projectName: project.name,
-    });
-  }
-  return roots;
-}
-
-function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
-  return {
-    personal: path.join(homeDir, '.claude', 'skills'),
-    project: project?.localPath ? path.resolve(project.localPath, '.claude', 'skills') : null,
-  };
-}
-
 // ── Output Parsing ───────────────────────────────────────────────────────────
 
 /**

package/engine/runtimes/copilot.js

@@ -270,6 +270,42 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
+function getUserAssetDirs({ homeDir = os.homedir() } = {}) {
+  return [
+    path.join(homeDir, '.copilot'),
+    path.join(homeDir, '.agents'),
+  ];
+}
+
+function getSkillRoots({ homeDir = os.homedir(), project = null } = {}) {
+  const roots = [
+    { scope: 'copilot', dir: path.join(homeDir, '.copilot', 'skills') },
+    { scope: 'agent-skill', dir: path.join(homeDir, '.agents', 'skills') },
+  ];
+  if (project?.localPath) {
+    roots.push(
+      {
+        scope: 'project',
+        projectName: project.name,
+        dir: path.join(project.localPath, '.github', 'skills'),
+      },
+      {
+        scope: 'project',
+        projectName: project.name,
+        dir: path.join(project.localPath, '.agents', 'skills'),
+      },
+    );
+  }
+  return roots;
+}
+
+function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
+  return {
+    personal: path.join(homeDir, '.copilot', 'skills'),
+    project: project?.localPath ? path.join(project.localPath, '.github', 'skills') : null,
+  };
+}
+
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
   try {
@@ -349,41 +385,6 @@ function buildPrompt(promptText, sysPromptText, opts = {}) {
   return `<system>\n${String(sysPromptText)}\n</system>\n\n${user}`;
 }
 
-function getUserAssetDirs({ homeDir = os.homedir() } = {}) {
-  return [
-    path.join(homeDir, '.copilot'),
-    path.join(homeDir, '.agents'),
-  ];
-}
-
-function getSkillRoots({ homeDir = os.homedir(), project = null } = {}) {
-  const roots = [
-    { dir: path.join(homeDir, '.copilot', 'skills'), scope: 'copilot' },
-    { dir: path.join(homeDir, '.agents', 'skills'), scope: 'agent-skill' },
-  ];
-  if (project?.localPath) {
-    for (const rel of [
-      ['.github', 'skills'],
-      ['.claude', 'skills'],
-      ['.agents', 'skills'],
-    ]) {
-      roots.push({
-        dir: path.resolve(project.localPath, ...rel),
-        scope: 'project',
-        projectName: project.name,
-      });
-    }
-  }
-  return roots;
-}
-
-function getSkillWriteTargets({ homeDir = os.homedir(), project = null } = {}) {
-  return {
-    personal: path.join(homeDir, '.copilot', 'skills'),
-    project: project?.localPath ? path.resolve(project.localPath, '.github', 'skills') : null,
-  };
-}
-
 // ── Output Parsing ──────────────────────────────────────────────────────────
 //
 // Whitelist of event types observed during the spike (docs/copilot-cli-schema.md

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) {
@@ -174,17 +225,17 @@ function main() {
     opts.sysPromptFile = sysTmpPath;
   }
 
-  // User asset discovery dirs — agents run with CWD set to an external repo
-  // worktree, so the adapter supplies any runtime-native global asset roots
-  // that should be visible from that cwd.
+  // Skill discovery dirs — agents run with CWD set to an external repo
+  // worktree, so runtime-native global assets would otherwise be invisible.
+  // The adapter owns both where those assets live and how to surface them.
   const minionsDir = path.resolve(__dirname, '..');
+  const addDirs = [minionsDir];
   const runtimeAssetDirs = typeof runtime.getUserAssetDirs === 'function'
     ? runtime.getUserAssetDirs({ homeDir: os.homedir() })
     : [];
-  const addDirs = [minionsDir];
-  for (const userAssetDir of runtimeAssetDirs) {
-    if (fs.existsSync(userAssetDir) && path.resolve(userAssetDir) !== path.resolve(minionsDir)) {
-      addDirs.push(userAssetDir);
+  for (const dir of runtimeAssetDirs) {
+    if (dir && fs.existsSync(dir) && path.resolve(dir) !== path.resolve(minionsDir)) {
+      addDirs.push(dir);
     }
   }
 
@@ -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.1683",
+  "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"