@yemi33/minions 0.1.2381 → 0.1.2383

package/engine/runtimes/copilot.js

@@ -37,6 +37,14 @@ const { FAILURE_CLASS, safeWrite, ts, resolveEngineCacheDir } = require('../shar
 const ENGINE_DIR = __dirname.replace(/[\\/]runtimes$/, '');
 const _CACHE_DIR = resolveEngineCacheDir(ENGINE_DIR);
 const isWin = process.platform === 'win32';
+const RUNTIME_NAME = 'copilot';
+const SPAWN_STARTUP_TYPES = new Set([
+  'session.mcp_server_status_changed',
+  'session.mcp_servers_loaded',
+  'session.skills_loaded',
+  'session.tools_updated',
+  'session.info',
+]);
 
 // ── Binary Resolution ───────────────────────────────────────────────────────
 //
@@ -529,7 +537,7 @@ function buildArgs(opts = {}) {
 }
 
 function buildSpawnFlags(opts = {}) {
-  const flags = ['--runtime', 'copilot'];
+  const flags = ['--runtime', RUNTIME_NAME];
   if (opts.maxTurns != null) flags.push('--max-turns', String(opts.maxTurns));
   if (opts.model) flags.push('--model', String(opts.model));
   if (opts.allowedTools) flags.push('--allowedTools', String(opts.allowedTools));
@@ -552,12 +560,66 @@ function buildSpawnFlags(opts = {}) {
   return flags;
 }
 
-// Stamped into every session.json this adapter writes so the pre-spawn resume
-// path can detect "session was produced by a different runtime" — Copilot
-// rejects Claude session IDs (and vice versa) with "No conversation found",
-// which would otherwise burn a retry slot before the post-failure cleanup at
-// engine.js:1195 fires. See W-mot9fwya000d09cb.
-const RUNTIME_NAME = 'copilot';
+function resolveInvocationOptions({
+  options = {},
+  engineConfig = {},
+  failureClass = null,
+} = {}) {
+  const resolved = { ...options };
+  if (resolved.stream == null) resolved.stream = engineConfig.copilotStreamMode;
+  if (resolved.disableBuiltinMcps == null) {
+    resolved.disableBuiltinMcps = engineConfig.copilotDisableBuiltinMcps;
+  }
+  if (resolved.reasoningSummaries == null) {
+    resolved.reasoningSummaries = engineConfig.copilotReasoningSummaries;
+  }
+  if (failureClass === FAILURE_CLASS.MODEL_UNAVAILABLE && engineConfig.copilotFallbackModel) {
+    resolved.model = engineConfig.copilotFallbackModel;
+  }
+  return resolved;
+}
+
+function isSpawnStartupEvent(event) {
+  return !!event && SPAWN_STARTUP_TYPES.has(event.type);
+}
+
+function shouldSuppressPostMutationError({ mutationApplied, error } = {}) {
+  if (mutationApplied !== true || !error) return false;
+  return error.errorClass === 'unknown-model' || error.errorClass === 'model-unavailable';
+}
+
+function buildWorkerArgs() {
+  return ['--acp', '--allow-all', '--max-autopilot-continues', '1'];
+}
+
+function encodePooledOutput(event = {}) {
+  if (event.kind === 'model') {
+    return JSON.stringify({
+      type: 'session.tools_updated',
+      data: { model: event.model || null },
+    }) + '\n';
+  }
+  if (event.kind === 'chunk') {
+    return JSON.stringify({
+      type: 'assistant.message_delta',
+      data: { deltaContent: event.text || '' },
+    }) + '\n';
+  }
+  if (event.kind === 'result') {
+    return JSON.stringify({
+      type: 'result',
+      sessionId: event.sessionId || null,
+      usage: {
+        totalApiDurationMs: event.durationMs,
+        stopReason: event.stopReason || null,
+      },
+    }) + '\n';
+  }
+  throw new Error(`Unsupported pooled output event kind: ${event.kind || '<missing>'}`);
+}
+
+// RUNTIME_NAME is stamped into every session.json so the pre-spawn resume path
+// can reject session IDs produced by another adapter before invoking the CLI.
 
 function getResumeSessionId({ agentId, branchName, agentsDir, maxAgeMs = 2 * 60 * 60 * 1000, logger = console } = {}) {
   if (!agentId || agentId.startsWith('temp-') || !agentsDir) return null;
@@ -1273,6 +1335,13 @@ const capabilities = {
   budgetCap: false,
   // No --bare equivalent.
   bareMode: false,
+  // Copilot has NO native CLAUDE.md auto-load — it only reads its own AGENTS.md
+  // (native custom-instruction discovery owned by the CLI itself). FALSE
+  // here opts this runtime INTO the engine's CLAUDE.md-propagation layer
+  // (engine/claude-md-context.js) so repo-authored CLAUDE.md guidance is
+  // surfaced in the prompt. This is orthogonal to AGENTS.md discovery —
+  // CLAUDE.md carries no split-brain risk because Copilot never reads it itself.
+  claudeMdNativeDiscovery: false,
   // No --fallback-model
   fallbackModel: false,
   // Copilot manages session state internally in ~/.copilot/session-state/
@@ -1363,7 +1432,8 @@ function getMcpConfigPaths({ homeDir = os.homedir(), project = null } = {}) {
 }
 
 module.exports = {
-  name: 'copilot',
+  apiVersion: 1,
+  name: RUNTIME_NAME,
   capabilities,
   resolveBinary,
   capsFile: CAPS_FILE,
@@ -1372,7 +1442,11 @@ module.exports = {
   // Use the same wrapper as Claude — spawn-agent.js is runtime-agnostic per P-9c4f2d6a
   spawnScript: path.join(ENGINE_DIR, 'spawn-agent.js'),
   installHint: INSTALL_HINT,
+  workerErrorHint: 'copilot --acp failed -- ensure copilot CLI >=1.0.46 and copilot login is complete',
+  resolveInvocationOptions,
   buildSpawnFlags,
+  buildWorkerArgs,
+  encodePooledOutput,
   buildArgs,
   buildPrompt,
   getUserAssetDirs,
@@ -1392,6 +1466,8 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  isSpawnStartupEvent,
+  shouldSuppressPostMutationError,
   permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — engine code MUST go through resolveRuntime + the
   // adapter contract; never reach into these helpers directly.
@@ -1412,4 +1488,5 @@ module.exports = {
   _extractInvalidModelName,
   CAPS_SCHEMA_VERSION,
   KNOWN_EVENT_TYPES,
+  SPAWN_STARTUP_TYPES,
 };

package/engine/runtimes/index.js

@@ -7,18 +7,16 @@
  * runtime name fails loudly with a clear list of registered options.
  *
  * Adding a new runtime:
- *   1. Implement the full adapter contract documented in claude.js.
- *   2. `registry.set('<name>', require('./<name>'));` below.
+ *   1. Implement API version 1 from contract.js.
+ *   2. `registerRuntime('<name>', require('./<name>'), { strict: true });`.
  *   3. Expose its capabilities via the `/api/runtimes` endpoint (free).
  *
  * Engine code MUST gate behavior on `runtime.capabilities.*` flags, not on
  * `runtime.name === 'claude'` comparisons. The whole point of this layer.
  */
 
+const contract = require('./contract');
 const registry = new Map();
-registry.set('claude', require('./claude'));
-registry.set('codex', require('./codex'));
-registry.set('copilot', require('./copilot'));
 
 /**
  * Look up a runtime adapter by name. Throws when the name is unknown so
@@ -47,16 +45,46 @@ function listRuntimes() {
  * Register a runtime adapter. Exposed for tests and for downstream tooling
  * that wants to register a custom runtime without editing this file.
  */
-function registerRuntime(name, adapter) {
-  if (!name || typeof name !== 'string') throw new Error('registerRuntime: name must be a non-empty string');
-  if (!adapter || typeof adapter !== 'object') throw new Error('registerRuntime: adapter must be an object');
-  registry.set(name, adapter);
+function registerRuntime(name, adapter, options) {
+  const normalized = contract.normalizeRuntimeAdapter(name, adapter, options);
+  registry.set(name, normalized);
+  return normalized;
 }
 
+function resolveRuntimeByCapability(capability) {
+  const matches = listRuntimes()
+    .map(name => registry.get(name))
+    .filter(adapter => adapter?.capabilities?.[capability] === true);
+  if (matches.length === 0) {
+    throw new Error(
+      `No registered runtime declares capability "${capability}"`
+    );
+  }
+  return matches[0];
+}
+
+registerRuntime('claude', require('./claude'), { strict: true });
+registerRuntime('codex', require('./codex'), { strict: true });
+registerRuntime('copilot', require('./copilot'), { strict: true });
+
 module.exports = {
+  ADAPTER_API_VERSION: contract.ADAPTER_API_VERSION,
+  RUNTIME_OPTIONS_FLAG: contract.RUNTIME_OPTIONS_FLAG,
+  RUNTIME_IMAGES_FILE_OPTION: contract.RUNTIME_IMAGES_FILE_OPTION,
   resolveRuntime,
+  resolveRuntimeByCapability,
   listRuntimes,
   registerRuntime,
+  sanitizeInvocationOptions: contract.sanitizeInvocationOptions,
+  resolveInvocationOptions: contract.resolveInvocationOptions,
+  decodeRuntimeOptions: contract.decodeRuntimeOptions,
+  buildSpawnFlags: contract.buildSpawnFlags,
+  prepareWorkspace: contract.prepareWorkspace,
+  isSpawnStartupEvent: contract.isSpawnStartupEvent,
+  shouldSuppressPostMutationError: contract.shouldSuppressPostMutationError,
+  buildWorkerArgs: contract.buildWorkerArgs,
+  encodePooledOutput: contract.encodePooledOutput,
+  validateRuntimeAdapter: contract.normalizeRuntimeAdapter,
   // Exposed for tests — engine code MUST go through resolveRuntime/listRuntimes
   _registry: registry,
 };

package/engine/shared.js

@@ -1037,8 +1037,16 @@ function validateDispatchTmpDir(dirPath) {
 
 function removeDispatchTmpDir(dirPath) {
   if (!validateDispatchTmpDir(dirPath)) return false;
-  try { fs.rmSync(dirPath, { recursive: true, force: true }); return true; }
-  catch { return false; }
+  try {
+    _retryFsOp(
+      () => fs.rmSync(dirPath, { recursive: true, force: true }),
+      `removeDispatchTmpDir(${dirPath})`
+    );
+    return true;
+  } catch (e) {
+    log('warn', `removeDispatchTmpDir failed after retries: ${e.message}`, { path: dirPath, error: e.code });
+    return false;
+  }
 }
 
 // Read a file using O_NOFOLLOW where the platform supports it. On Windows
@@ -1439,48 +1447,37 @@ function withFileLock(lockPath, fn, {
         const isLockRaceErr = err.code === 'EEXIST' ||
           (process.platform === 'win32' && err.code === 'EPERM');
         if (!isLockRaceErr) throw err;
-        // P-b7d4e8f2 — Stale-lock check combines mtime age with PID liveness:
-        //   1. If mtime <= LOCK_STALE_MS  → never reap (recently active).
-        //   2. If JSON-parsable {pid, ts}:
-        //      - dead PID                 → reap.
-        //      - alive PID, mtime <= 5×   → don't reap (legitimate slow holder).
-        //      - alive PID, mtime > 5×    → reap (last-resort guard against
-        //                                    stuck holders that never released).
-        //   3. Legacy / empty / non-JSON lockfile → mtime-only path (reap).
+        // PID-owned locks are safe to reap as soon as their owner is dead.
+        // Alive owners retain the 5× stale window; legacy/partial lockfiles
+        // without a readable PID retain the mtime-only stale window.
         try {
           const stat = fs.statSync(lockPath);
           const mtimeAge = Date.now() - stat.mtimeMs;
-          if (mtimeAge > LOCK_STALE_MS) {
-            let holderPid = null;
-            try {
-              const raw = fs.readFileSync(lockPath, 'utf8');
-              const parsed = JSON.parse(raw);
-              if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
-                holderPid = parsed.pid;
-              }
-            } catch { /* legacy/empty/corrupt lock → fall through to mtime-only */ }
-
-            let shouldReap;
-            if (holderPid !== null) {
-              shouldReap = !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5;
-            } else {
-              // Legacy empty/non-JSON lockfile: trust mtime alone
-              shouldReap = true;
+          let holderPid = null;
+          try {
+            const raw = fs.readFileSync(lockPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed && Number.isFinite(parsed.pid) && parsed.pid > 0) {
+              holderPid = parsed.pid;
             }
+          } catch { /* legacy/empty/corrupt lock → mtime-only fallback */ }
 
-            if (shouldReap) {
-              try {
-                fs.unlinkSync(lockPath);
-              } catch (unlinkErr) {
-                // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
-                // EPERM on Windows: file is in 'pending delete' state from a concurrent
-                // reaper — the OS will finalize the delete shortly; retry will succeed.
-                const tolerable = unlinkErr.code === 'ENOENT' ||
-                  (process.platform === 'win32' && unlinkErr.code === 'EPERM');
-                if (!tolerable) throw unlinkErr;
-              }
-              continue; // lock just removed — retry immediately
+          const shouldReap = holderPid !== null
+            ? !processUtils.isPidAlive(holderPid) || mtimeAge > LOCK_STALE_MS * 5
+            : mtimeAge > LOCK_STALE_MS;
+
+          if (shouldReap) {
+            try {
+              fs.unlinkSync(lockPath);
+            } catch (unlinkErr) {
+              // ENOENT: another process deleted the lock between stat and unlink — safe to retry.
+              // EPERM on Windows: file is in 'pending delete' state from a concurrent
+              // reaper — the OS will finalize the delete shortly; retry will succeed.
+              const tolerable = unlinkErr.code === 'ENOENT' ||
+                (process.platform === 'win32' && unlinkErr.code === 'EPERM');
+              if (!tolerable) throw unlinkErr;
             }
+            continue; // lock just removed — retry immediately
           }
         } catch (staleErr) {
           // ENOENT from statSync: lock file disappeared between EEXIST and stat — retry will succeed.
@@ -3120,9 +3117,8 @@ const ENGINE_DEFAULTS = {
   // description the validator will never accept (see stage-output
   // substitution bug above) got re-evaluated forever, once per tick,
   // invisible to the dashboard. Once the SAME (unchanged) description is
-  // rejected this many consecutive times, the WI is flipped to `failed`
-  // with FAILURE_CLASS.PRE_DISPATCH_EVAL_STUCK instead of being silently
-  // re-queued into review again.
+  // rejected this many consecutive times, the WI stays pending but is marked
+  // exhausted so discovery pauses until an operator edits it.
   preDispatchEvalMaxRejections: 5,
   completionNonceRequired: false, // P-d2a8f6c1 (agent trust boundary F8): when true, a missing `nonce` field in the completion JSON hard-fails the dispatch with failure_class:'completion-nonce-mismatch'. Default false for one release so older agents/runtime caches that haven't picked up the prompt change degrade with a warning instead of breaking. Mismatched nonces hard-fail regardless of this flag. See docs/completion-reports.md → "Trust boundary".
   autoApplyReviewVote: false, // Master gate for platform vote mutations; local verdicts remain informational when false.
@@ -3255,6 +3251,7 @@ const ENGINE_DEFAULTS = {
   maxMeetingPromptBytes: 16 * 1024, // cap meeting findings/debate context injected into prompts
   maxMeetingHumanNotesBytes: 2 * 1024, // cap human note bullet lists injected into meeting prompts
   maxPipelineMeetingContextBytes: 16 * 1024, // cap aggregated meeting/dependency context for pipeline plan generation
+  maxPipelineStageHandoffBytes: 32 * 1024, // cap current-run note content exposed through {{stages.<id>.handoff}}
   notesArchiveMaxFiles: 2000, // keep notes/archive bounded during periodic cleanup
   // ── Worktree pool (W-mp73ya3e000me6c5) ─────────────────────────────────────
   // Per-project warm pool: completed worktrees are parked detached at
@@ -3324,7 +3321,7 @@ const ENGINE_DEFAULTS = {
       'node', 'bun', 'npm', 'npx', 'pnpm', 'yarn',
       'python', 'python3', 'pip', 'pip3',
       'docker', 'podman',
-      'adb', 'emulator',
+      'adb', 'emulator', 'maestro',
       'gradle', 'gradlew', 'mvn',
       'pwsh', 'powershell', 'bash', 'sh',
       'curl', 'wget',
@@ -3431,9 +3428,9 @@ function resolvePollFlag(engineCfg, granularKey, legacyMacroKey) {
 
 // ─── Runtime Fleet Resolution (P-3b8e5f1d) ──────────────────────────────────
 //
-// Six helpers that are the single source of truth for "which CLI runtime + model
-// + budget + bare-mode applies to this spawn?". Engine code MUST go through
-// these — never read `agent.cli`, `engine.defaultCli`, etc. directly. Future
+// Runtime helpers are the single source of truth for "which CLI runtime + model
+// + tool ceiling + budget + bare-mode applies to this spawn?". Engine code MUST
+// go through these — never read `agent.cli`, `engine.defaultCli`, etc. directly. Future
 // agents adding new resolution rules should extend these helpers, not bypass
 // them.
 //
@@ -3479,28 +3476,27 @@ function resolveCcCli(engine) {
 /**
  * Resolve whether the Command Center / doc-chat path should route through the
  * persistent ACP worker pool. Priority:
- *   1. CC runtime guard — pool spawns `copilot --acp` (Agent Client Protocol).
- *      Claude Code does not implement ACP, and `_invokeCcStream` would silently
- *      switch a Claude operator's CC turns to copilot if the pool ran for them.
- *      Refuse the pool when CC runtime is not copilot, even if explicit-true is
- *      set. Future runtimes that don't implement ACP fall into the same bucket.
+ *   1. Runtime capability guard. Refuse the pool unless the selected adapter
+ *      declares `acpWorkerPool`, even if explicit-true is set, so pooling can
+ *      never switch the configured harness.
  *      (W-mphlriic00095f69)
  *   2. `engine.ccUseWorkerPool` explicit true/false — operator override wins
- *      *within* the copilot runtime
- *   3. Runtime-aware default: ON when CC runtime resolves to `copilot`
- *      (Copilot's cold-spawn is 18-21s on Windows — pool turns subsequent turns
- *      from 47-140s back into a few seconds).
+ *      within an ACP-capable runtime.
+ *   3. Runtime-aware default: ON for any ACP-capable adapter.
  *   4. ENGINE_DEFAULTS.ccUseWorkerPool — final fallback
  *
  * Strict boolean check on the override so a literal `false` opts out even on
- * Copilot, matching the "treat empty/null/undefined as unset" semantics used
+ * ACP runtimes, matching the "treat empty/null/undefined as unset" semantics used
  * throughout the resolve* helpers for boolean flags.
  */
 function resolveCcUseWorkerPool(engine) {
-  // Guard 1 (W-mphlriic00095f69): pool transport is ACP-only. If CC runtime
-  // isn't copilot, the pool cannot run regardless of operator opt-in — don't
-  // silently switch their runtime to copilot.
-  if (resolveCcCli(engine) !== 'copilot') return false;
+  let runtime;
+  try {
+    runtime = require('./runtimes').resolveRuntime(resolveCcCli(engine));
+  } catch {
+    return false;
+  }
+  if (runtime?.capabilities?.acpWorkerPool !== true) return false;
   if (engine && (engine.ccUseWorkerPool === true || engine.ccUseWorkerPool === false)) {
     return engine.ccUseWorkerPool;
   }
@@ -3514,7 +3510,7 @@ function resolveCcUseWorkerPool(engine) {
  * adapter (as returned by `resolveRuntime(resolveAgentCli(agent, engine))`)
  * rather than re-deriving it, since callers on the agent-spawn path already
  * have it in hand. Priority:
- *   1. Capability guard — pool transport is ACP-only (`copilot --acp`). Hard
+ *   1. Capability guard — pool transport is ACP-only. Hard
  *      false whenever `runtime.capabilities.acpWorkerPool` isn't `true`,
  *      regardless of operator override, so a future non-ACP runtime can never
  *      be silently routed through the pool (same rationale as
@@ -3588,6 +3584,17 @@ function resolveCcModel(engine) {
   return undefined;
 }
 
+/**
+ * Resolve the fleet tool ceiling for an agent spawn.
+ *
+ * `config.claude.allowedTools` predates runtime adapters but has always applied
+ * to every selected runtime. Keep that cross-runtime contract centralized here
+ * until the field is migrated to a runtime-neutral config namespace.
+ */
+function resolveAgentAllowedTools(config) {
+  return config?.claude?.allowedTools;
+}
+
 /**
  * Resolve the per-spawn USD budget cap. Priority:
  *   1. `agent.maxBudgetUsd`     — per-agent override
@@ -3629,6 +3636,28 @@ function resolveAgentBareMode(agent, engine) {
   return false;
 }
 
+// W-mrdon0pe000l045a — resolve whether repo-authored CLAUDE.md instructions
+// should be propagated into the prompt for runtimes that don't auto-discover
+// CLAUDE.md natively (Copilot/Codex). Precedence mirrors
+// `resolveLiveCheckoutAutoReset`:
+//   1. per-project boolean `project.propagateClaudeMdForNonClaudeRuntimes`
+//   2. fleet-wide boolean `engine.propagateClaudeMdForNonClaudeRuntimes`
+//   3. hardcoded default TRUE (additive, on by default)
+// Only an explicit boolean counts as "set" at either level — undefined/null/
+// string are treated as unset so the next tier (or the TRUE default) decides.
+// This gate is orthogonal to each runtime's native AGENTS.md / repo-instruction
+// discovery by design (see ENGINE_DEFAULTS.propagateClaudeMdForNonClaudeRuntimes).
+// Pure, no I/O.
+function resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine) {
+  if (project && typeof project === 'object' && typeof project.propagateClaudeMdForNonClaudeRuntimes === 'boolean') {
+    return project.propagateClaudeMdForNonClaudeRuntimes;
+  }
+  if (engine && typeof engine === 'object' && typeof engine.propagateClaudeMdForNonClaudeRuntimes === 'boolean') {
+    return engine.propagateClaudeMdForNonClaudeRuntimes;
+  }
+  return true;
+}
+
 // ─── Legacy ccModel → defaultModel Migration ─────────────────────────────────
 //
 // Pre-P-3b8e5f1d, `engine.ccModel` was the single fleet-wide model knob (it
@@ -4500,7 +4529,7 @@ const FAILURE_CLASS = {
   OUTPUT_TRUNCATED: 'output-truncated',   // P-8e4c2a17: the agent streamed more stdout than the engine's hard capture cap (engine.js AGENT_OUTPUT_CAP_BYTES, 1MB) BEFORE the terminal `result` event arrived. The result (session id, completion block, final text) lives at the END of the stream, so it fell outside the captured window and parseOutput found nothing — the dispatch would otherwise fail as an opaque UNKNOWN and retry to death. Surfaced loudly with an actionable message; non-retryable (mechanical retry just reproduces the overflow — the agent must reduce output volume or the task must be split).
   VERIFY_MISSING_PR: 'verify-missing-pr', // Verify completed without an attached or tracked PR.
   PROJECT_NOT_FOUND: 'project_not_found', // W-mqv2wsy30002e090: a work item's `project` field names a project that is not configured (resolveConfiguredProject / formatUnknownProjectError → `Project "<name>" not found. Known projects: …`). Stamped at discovery time so the dashboard PR-column renderer surfaces the red failReason snippet like other non-retryable failures instead of burying it in the Agent column. Non-retryable — operator must fix the WI's project field or configure the project.
-  PRE_DISPATCH_EVAL_STUCK: 'pre-dispatch-eval-stuck', // W-mrcrh5hj0017d22f: pre-dispatch-eval rejected the SAME (unchanged) description ENGINE_DEFAULTS.preDispatchEvalMaxRejections times in a row without the WI status ever leaving pending — previously this burned an LLM validation call every discovery tick forever with nothing surfaced to the dashboard (constant-bug-bash's file-fixes stage wedged 16+ consecutive rejections, one/minute, until a human manually cancelled it). Engine now flips the WI to failed with this class so the stalled item is visible and stops silently re-evaluating; non-retryable until the description changes.
+  PRE_DISPATCH_EVAL_STUCK: 'pre-dispatch-eval-stuck', // Legacy persisted classification normalized by migration 025. New exhausted evaluations remain pending with _preDispatchEval.exhausted so they are not counted as agent execution failures.
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 
@@ -6024,7 +6053,7 @@ function validateProjectPath(pathStr, options = {}) {
 
 function parseSkillFrontmatter(content, filename) {
   let name = filename.replace('.md', '');
-  let trigger = '', description = '', project = 'any', author = '', created = '', allowedTools = '';
+  let trigger = '', description = '', project = 'any', author = '', created = '', allowedTools = '', scope = 'minions';
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (fmMatch) {
     const fm = fmMatch[1];
@@ -6036,8 +6065,52 @@ function parseSkillFrontmatter(content, filename) {
     author = m('author');
     created = m('created');
     allowedTools = m('allowed-tools');
+    scope = m('scope') || scope;
+  }
+  return { name, trigger, description, project, author, created, allowedTools, scope };
+}
+
+function syncBundledPersonalSkills(skillsDir, opts = {}) {
+  const result = { created: [], updated: [], unchanged: [] };
+  if (!skillsDir || !fs.existsSync(skillsDir)) return result;
+
+  const homeDir = opts.homeDir || os.homedir();
+  const { listRuntimes, resolveRuntime } = require('./runtimes');
+  const personalRoots = new Set();
+  for (const runtimeName of listRuntimes()) {
+    const runtime = resolveRuntime(runtimeName);
+    if (typeof runtime.getSkillWriteTargets !== 'function') continue;
+    const personal = runtime.getSkillWriteTargets({ homeDir }).personal;
+    if (typeof personal === 'string' && personal.trim()) {
+      personalRoots.add(path.resolve(personal));
+    }
+  }
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const sourcePath = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (!fs.existsSync(sourcePath)) continue;
+    const content = fs.readFileSync(sourcePath, 'utf8');
+    const skill = parseSkillFrontmatter(content, `${entry.name}.md`);
+    if (skill.scope !== 'minions') continue;
+    const skillName = String(skill.name || entry.name).replace(/[^a-z0-9-]/g, '-');
+    if (!skillName) throw new Error(`Bundled skill has an invalid name: ${sourcePath}`);
+
+    for (const personalRoot of personalRoots) {
+      const targetPath = path.join(personalRoot, skillName, 'SKILL.md');
+      const exists = fs.existsSync(targetPath);
+      if (exists && fs.readFileSync(targetPath, 'utf8') === content) {
+        result.unchanged.push(targetPath);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.copyFileSync(sourcePath, targetPath);
+      result[exists ? 'updated' : 'created'].push(targetPath);
+    }
   }
-  return { name, trigger, description, project, author, created, allowedTools };
+  return result;
 }
 
 // ── PR → PRD Links ────────────────────────────────────────────────────────────
@@ -7721,6 +7794,7 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
     evidence.lastReviewedAt = pr?.lastReviewedAt || '';
     evidence.reviewedAt = review.reviewedAt || '';
     evidence.reviewNote = review.note || pr?.reviewNote || '';
+    evidence.findingId = prReviewFindingIdentity(pr);
     // #2979 — same rationale as BUILD_FAILURE: review feedback fingerprints
     // were sticky across force-push because reviewStatus / reviewedAt /
     // reviewNote don't change when the author rebases. Adding the head SHA
@@ -7732,6 +7806,23 @@ function prFixEvidenceFingerprint(pr, cause = PR_FIX_CAUSE.UNKNOWN) {
   return crypto.createHash('sha1').update(JSON.stringify(evidence)).digest('hex').slice(0, 16);
 }
 
+function prReviewFindingIdentity(pr) {
+  const review = pr?.minionsReview || {};
+  const threads = Array.isArray(review.threads)
+    ? review.threads.map(value => String(value)).filter(Boolean).sort()
+    : [];
+  const evidence = {
+    pr: pr?.id || pr?.url || '',
+    sourceItem: review.sourceItem || '',
+    dispatchId: review.dispatchId || '',
+    reviewer: review.reviewer || '',
+    reviewedAt: review.reviewedAt || pr?.lastReviewedAt || '',
+    threads,
+    note: review.note || pr?.reviewNote || '',
+  };
+  return `review-${crypto.createHash('sha1').update(JSON.stringify(evidence)).digest('hex').slice(0, 16)}`;
+}
+
 function getPrNoOpFixRecord(pr, cause) {
   if (!pr || !cause || !pr._noOpFixes || typeof pr._noOpFixes !== 'object') return null;
   const record = pr._noOpFixes[cause];
@@ -8491,7 +8582,7 @@ module.exports = {
   ENGINE_DEFAULTS,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentUseWorkerPool, resolveAgentAcpPoolSize, resolveAgentModel, resolveCcModel,
-  resolveAgentMaxBudget, resolveAgentBareMode,
+  resolveAgentAllowedTools, resolveAgentMaxBudget, resolveAgentBareMode, resolvePropagateClaudeMdForNonClaudeRuntimes,
   applyLegacyCcModelMigration, _resetLegacyCcModelMigrationFlag,
   runtimeConfigWarnings,
   projectWorkSourceWarnings,
@@ -8629,6 +8720,7 @@ module.exports = {
   PR_FIX_CAUSE,
   getPrFixAutomationCause,
   prFixEvidenceFingerprint,
+  prReviewFindingIdentity,
   prMergeConflictGuardKey,
   resetMergeConflictStateOnRetarget,
   getPrNoOpFixRecord,
@@ -8636,6 +8728,7 @@ module.exports = {
   getPrPausedCauses,
   isBuildFixIneffectivePaused,
   parseSkillFrontmatter,
+  syncBundledPersonalSkills,
   sleepMs,
   clearWorktreeFailureCache,
   removeWorktree,