@link-assistant/hive-mind 2.9.0 → 2.9.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.9.2
+
+### Patch Changes
+
+- a6d14db: Read the target repository's own agent instructions when deciding which Codex plugins and skills to provision. The capability preflight previously built its requirement corpus from the GitHub issue alone, so a repository that mandates a plugin in `AGENTS.md` — where the convention says to put it — provisioned nothing, and the model's own `request_plugin_install` attempt was rejected by Codex as an unrecognized `plugin_id`. Root and nested `AGENTS.md`, `CLAUDE.md` and `.codex/*.md` files under the checkout now feed the detector through a bounded walk that reports what it skipped, the zero-requirement path logs the sources it scanned instead of staying silent, a runtime plugin-install rejection is recognized and fails the run with a named diagnostic when the session produced no file changes, and `--require-codex-plugin` / `HIVE_MIND_CODEX_REQUIRED_PLUGINS` can state a requirement that no document spells out.
+
+## 2.9.1
+
+### Patch Changes
+
+- 3e48cb3: Resume Codex sessions after transient high-demand failures and preserve uncommitted work before uploading failure logs.
+
 ## 2.9.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.9.0",
+  "version": "2.9.2",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/agents-md-claude-support.lib.mjs

@@ -1,5 +1,5 @@
-const AGENTS_MD_FILENAMES = Object.freeze(['AGENTS.md', 'agents.md']);
-const CLAUDE_MD_FILENAME = 'CLAUDE.md';
+export const AGENTS_MD_FILENAMES = Object.freeze(['AGENTS.md', 'agents.md']);
+export const CLAUDE_MD_FILENAME = 'CLAUDE.md';
 
 const noopLog = async () => {};
 const fallbackFormatAligned = (_icon, label, value) => `${label} ${value}`;

package/src/codex-capability-preflight.lib.mjs

@@ -14,16 +14,20 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 
 import { CODEX_PLUGIN_CLI, buildPluginCachePath as buildAgentPluginCachePath, buildPluginPayloadRepairs, pluginIdParts, readMaterializedPluginSkills as readAgentMaterializedPluginSkills, repairPluginPayloads } from './agent-plugin-cache.lib.mjs';
+import { AGENTS_MD_FILENAMES, CLAUDE_MD_FILENAME } from './agents-md-claude-support.lib.mjs';
 
 const execFileAsync = promisify(execFile);
-const REQUIREMENT_WORDS = /\b(?:depend(?:s|ency)?|install|invoke|mandatory|must|need(?:ed|s)?|preflight|required?|requires|use)\b/i;
+const REQUIREMENT_WORDS = /\b(?:depend(?:s|ency)?|install|invoke|mandatory|must|need(?:ed|s)?|preflight|required?|requires|us(?:e|es|ing))\b/i;
 const NEGATED_REQUIREMENT = /\b(?:does\s+not\s+require|not\s+required|optional)\b/i;
 // `(?!\.[a-z])` keeps email addresses and hostnames (`ops@example.com`) out of
 // the plugin selector space.
 const PLUGIN_SELECTOR = /\b([a-z0-9][a-z0-9-]*@[a-z0-9][a-z0-9-]*(?:-remote)?)\b(?!\.[a-z])/gi;
 const NAMESPACED_SKILL = /\b([a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*)\b/gi;
 const EXPLICIT_BARE_SKILL = /\$([a-z0-9][a-z0-9-]*)|`([a-z0-9][a-z0-9-]*)`\s+(?:agent\s+)?skill/gi;
-const CAPABILITY_PREFIX = /\b(?:depend(?:s|ed)?\s+on|install|invoke|must\s+(?:install|invoke|use)|need(?:ed|s)?(?:\s+to)?(?:\s+(?:install|invoke|use))?|require(?:d|s)?(?:\s+to)?(?:\s+(?:install|invoke|use))?|use)\s+(?:(?:the|an?)\s+)?(?:(?:agent\s+)?skill\s+)?(?:named\s+)?[`$]?$/i;
+// Issue #2102: `us(?:e|ing)` covers the imperative form (`Use \`ns:skill\``) and
+// the participle a repository AGENTS.md uses for the same instruction
+// (`Execute approved plans in an isolated worktree using \`ns:skill\``).
+const CAPABILITY_PREFIX = /\b(?:depend(?:s|ed)?\s+on|install|invoke|must\s+(?:install|invoke|use)|need(?:ed|s)?(?:\s+to)?(?:\s+(?:install|invoke|use))?|require(?:d|s)?(?:\s+to)?(?:\s+(?:install|invoke|use))?|us(?:e|ing))\s+(?:(?:the|an?)\s+)?(?:(?:agent\s+)?skill\s+)?(?:named\s+)?[`$]?$/i;
 const CAPABILITY_SUFFIX = /^`?\s+(?:agent\s+)?(?:skill|capability)\b/i;
 const STRUCTURED_DATA_VALUES = new Set(['array', 'boolean', 'false', 'integer', 'null', 'number', 'object', 'string', 'true']);
 
@@ -49,6 +53,11 @@ const PROSE_TOKENS = new Set(['agent', 'caution', 'codex', 'default', 'error', '
 
 const isCapabilityToken = value => CAPABILITY_TOKEN.test(value) && !PROSE_TOKENS.has(value);
 
+const skillParts = skill => {
+  const separator = skill.indexOf(':');
+  return separator === -1 ? { namespace: null, name: skill } : { namespace: skill.slice(0, separator), name: skill.slice(separator + 1) };
+};
+
 const hasExplicitCapabilityContext = (line, match) => {
   const before = line.slice(0, match.index);
   const after = line.slice(match.index + match[0].length);
@@ -89,7 +98,7 @@ export function normalizePluginSelector(selector) {
     .replace(/@openai-curated-remote$/u, '@openai-curated');
 }
 
-export function detectRequiredCodexCapabilities(text) {
+export function detectRequiredCodexCapabilities(text, { source = null } = {}) {
   const plugins = new Set();
   const skills = new Set();
   // Issue #2088: a fully qualified reference — `plugin@marketplace` in plugin
@@ -106,12 +115,12 @@ export function detectRequiredCodexCapabilities(text) {
 
   const accept = (target, value, line, { qualified = false } = {}) => {
     if (!isCapabilityName(value)) {
-      rejected.push({ capability: value, line });
+      rejected.push({ capability: value, line, source });
       return;
     }
     target.add(value);
     if (qualified) explicit.add(value);
-    evidence.push({ capability: value, line, explicit: qualified });
+    evidence.push({ capability: value, line, explicit: qualified, source });
   };
 
   for (const rawLine of String(text || '').split(/\r?\n/u)) {
@@ -121,12 +130,22 @@ export function detectRequiredCodexCapabilities(text) {
     for (const match of line.matchAll(PLUGIN_SELECTOR)) {
       const selector = normalizePluginSelector(match[1]);
       if (hasExplicitPluginContext(line, match)) accept(plugins, selector, line, { qualified: true });
-      else rejected.push({ capability: selector, line });
+      else rejected.push({ capability: selector, line, source });
     }
-    for (const match of line.matchAll(NAMESPACED_SKILL)) {
-      const skill = match[1].toLowerCase();
-      if (hasExplicitCapabilityContext(line, match)) accept(skills, skill, line, { qualified: true });
-      else rejected.push({ capability: skill, line });
+    // Issue #2102: a conjunction shares one requirement verb. `invoke `a:x` and
+    // `a:y`` only puts `a:x` in capability context, so a later reference to a
+    // namespace already qualified on the same line inherits the qualification
+    // instead of being dropped. Restricting inheritance to the same namespace,
+    // and still rejecting structured-data values, keeps issues #2077 and #2080
+    // from resurfacing: prose cannot produce a second `ns:name` token for a
+    // namespace that was just named in an explicit requirement.
+    const lineSkills = [...line.matchAll(NAMESPACED_SKILL)].map(match => ({ skill: match[1].toLowerCase(), qualified: hasExplicitCapabilityContext(line, match) }));
+    const qualifiedNamespaces = new Set(lineSkills.filter(entry => entry.qualified).map(entry => skillParts(entry.skill).namespace));
+    for (const entry of lineSkills) {
+      const { namespace, name } = skillParts(entry.skill);
+      const inherited = qualifiedNamespaces.has(namespace) && !STRUCTURED_DATA_VALUES.has(name);
+      if (entry.qualified || inherited) accept(skills, entry.skill, line, { qualified: true });
+      else rejected.push({ capability: entry.skill, line, source });
     }
     for (const match of line.matchAll(EXPLICIT_BARE_SKILL)) accept(skills, (match[1] || match[2]).toLowerCase(), line);
   }
@@ -231,11 +250,6 @@ const verifyModelVisibleSkills = async ({ command, env, runCommand, log, require
   throw skillVisibilityError({ missing: outcome.missing, visible: outcome.visible, requirements });
 };
 
-const skillParts = skill => {
-  const separator = skill.indexOf(':');
-  return separator === -1 ? { namespace: null, name: skill } : { namespace: skill.slice(0, separator), name: skill.slice(separator + 1) };
-};
-
 const pluginProvidesSkill = async (plugin, skill) => {
   const sourcePath = plugin?.source?.path;
   if (!sourcePath) return false;
@@ -316,14 +330,182 @@ export async function resolveRequiredPlugins(options) {
   return (await resolveRequiredCapabilities(options)).plugins;
 }
 
-const readIssueRequirementText = async ({ owner, repo, issueNumber, runCommand, env }) => {
+const readIssueRequirementSegments = async ({ owner, repo, issueNumber, runCommand, env }) => {
   const issueResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}`], env });
   const issue = parseJsonCommand(issueResult, 'Codex capability issue discovery');
   const commentsResult = await runCommand({ command: 'gh', args: ['api', `repos/${owner}/${repo}/issues/${issueNumber}/comments`, '--paginate'], env });
   const comments = parseJsonCommand(commentsResult, 'Codex capability comment discovery');
-  return [issue?.title, issue?.body, ...(Array.isArray(comments) ? comments.map(comment => comment?.body) : [])].filter(Boolean).join('\n');
+  const bodies = (Array.isArray(comments) ? comments : []).map(comment => comment?.body).filter(Boolean);
+  return {
+    segments: [{ source: `issue #${issueNumber}`, text: [issue?.title, issue?.body].filter(Boolean).join('\n') }, ...bodies.map((text, index) => ({ source: `comment ${index + 1}`, text }))],
+    sources: [`issue #${issueNumber}`, ...(bodies.length > 0 ? [`${bodies.length} comment${bodies.length === 1 ? '' : 's'}`] : [])],
+  };
 };
 
+// Issue #2102: the requirement corpus has to include the instructions the target
+// repository gives the agent. CEHR2005/GCS-TS#5 delegated its entire mandatory
+// workflow to `AGENTS.md` ("Follow the repository and nested engine `AGENTS.md`
+// instructions"), so an issue-only corpus detected nothing, provisioning was
+// skipped, and the model was left to call `request_plugin_install` — which
+// `codex exec` can never satisfy.
+//
+// `CLAUDE.md` is scanned for parity with `--tool claude` (see
+// `agents-md-claude-support.lib.mjs`, which presents `AGENTS.md` under that name)
+// and `.codex/*.md` for repositories that keep Codex-specific rules there.
+const AGENT_INSTRUCTION_FILENAMES = new Set([...AGENTS_MD_FILENAMES, CLAUDE_MD_FILENAME, 'claude.md']);
+const CODEX_INSTRUCTION_DIRECTORY = '.codex';
+// Vendored dependencies, build output and VCS internals carry instructions that
+// belong to other projects; reading them would invent requirements the task
+// never had.
+const SKIPPED_INSTRUCTION_DIRECTORIES = new Set(['__pycache__', 'build', 'coverage', 'dist', 'node_modules', 'out', 'target', 'tmp', 'vendor', 'venv']);
+const WALKED_HIDDEN_DIRECTORIES = new Set([CODEX_INSTRUCTION_DIRECTORY, '.github']);
+const INSTRUCTION_WALK_LIMITS = Object.freeze({ maxDepth: 3, maxFiles: 24, maxBytes: 256 * 1024 });
+
+const isInstructionFile = ({ name, directoryName }) => AGENT_INSTRUCTION_FILENAMES.has(name) || (directoryName === CODEX_INSTRUCTION_DIRECTORY && name.toLowerCase().endsWith('.md'));
+
+/**
+ * Bounded walk over the checked-out repository's agent instruction files.
+ *
+ * Bounded on purpose: depth, file count and file size are all capped. A
+ * candidate dropped by the count or size cap is reported in `skipped`, so a
+ * truncated scan is visible in the log instead of looking like "nothing to
+ * find"; directories excluded by name or depth are not reported, because
+ * listing every skipped `node_modules` would bury that signal. Symlinked
+ * directories are not followed, which also makes the walk cycle-free.
+ */
+export async function collectAgentInstructionFiles({ projectDir, maxDepth = INSTRUCTION_WALK_LIMITS.maxDepth, maxFiles = INSTRUCTION_WALK_LIMITS.maxFiles, maxBytes = INSTRUCTION_WALK_LIMITS.maxBytes } = {}) {
+  const files = [];
+  const skipped = [];
+  if (!projectDir) return { files, skipped };
+
+  const candidates = [];
+  const walk = async (directory, relative, depth) => {
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const directoryName = relative ? path.posix.basename(relative) : '';
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (depth >= maxDepth) continue;
+        if (SKIPPED_INSTRUCTION_DIRECTORIES.has(entry.name)) continue;
+        if (entry.name.startsWith('.') && !WALKED_HIDDEN_DIRECTORIES.has(entry.name)) continue;
+        await walk(path.join(directory, entry.name), relativePath, depth + 1);
+      } else if (entry.isFile() && isInstructionFile({ name: entry.name, directoryName })) {
+        candidates.push({ relativePath, absolutePath: path.join(directory, entry.name), depth });
+      }
+    }
+  };
+  await walk(projectDir, '', 0);
+
+  candidates.sort((left, right) => left.depth - right.depth || left.relativePath.localeCompare(right.relativePath));
+  for (const candidate of candidates) {
+    let stats;
+    try {
+      stats = await fs.stat(candidate.absolutePath);
+    } catch {
+      continue;
+    }
+    if (stats.size > maxBytes) {
+      skipped.push({ relativePath: candidate.relativePath, reason: 'too-large', bytes: stats.size });
+      continue;
+    }
+    if (files.length >= maxFiles) {
+      skipped.push({ relativePath: candidate.relativePath, reason: 'max-files' });
+      continue;
+    }
+    try {
+      files.push({ relativePath: candidate.relativePath, text: await fs.readFile(candidate.absolutePath, 'utf8'), bytes: stats.size });
+    } catch {
+      // An unreadable instruction file is not a requirement source.
+    }
+  }
+  return { files, skipped };
+}
+
+/**
+ * Issue #2102 escape hatch: `--require-codex-plugin` /
+ * `HIVE_MIND_CODEX_REQUIRED_PLUGINS` let an operator state a requirement that no
+ * text declares. A selector without a marketplace cannot be installed by
+ * `codex plugin add`, so it is reported rather than silently ignored.
+ */
+export function parseRequiredCapabilityOverrides(value) {
+  const tokens = (Array.isArray(value) ? value : [value])
+    .flatMap(entry =>
+      String(entry ?? '')
+        .split(/[,;\s]+/u)
+        .map(token => token.trim())
+    )
+    .filter(Boolean);
+  const plugins = new Set();
+  const invalid = [];
+  for (const token of tokens) {
+    const selector = normalizePluginSelector(token);
+    if (selector.includes('@') && isCapabilityName(selector)) plugins.add(selector);
+    else invalid.push(token);
+  }
+  return { plugins: [...plugins].sort(), invalid };
+}
+
+/**
+ * Requirement corpus for the Codex capability preflight: the issue (title, body,
+ * comments), the checked-out repository's agent instruction files, and operator
+ * overrides. `sources` names everything that was scanned so a zero-requirement
+ * result is explainable from the log alone (issue #2102).
+ */
+export async function collectCodexCapabilityRequirements({ owner, repo, issueNumber, projectDir, runCommand = defaultRunCommand, env = process.env, requiredPlugins, instructionLimits } = {}) {
+  const segments = [];
+  const sources = [];
+
+  if (owner && repo && issueNumber) {
+    const issue = await readIssueRequirementSegments({ owner, repo, issueNumber, runCommand, env });
+    segments.push(...issue.segments);
+    sources.push(...issue.sources);
+  }
+
+  const instructions = await collectAgentInstructionFiles({ projectDir, ...instructionLimits });
+  for (const file of instructions.files) {
+    segments.push({ source: file.relativePath, text: file.text });
+    sources.push(file.relativePath);
+  }
+
+  const plugins = new Set();
+  const skills = new Set();
+  const explicit = new Set();
+  const evidence = [];
+  const rejected = [];
+  for (const segment of segments) {
+    const detected = detectRequiredCodexCapabilities(segment.text, { source: segment.source });
+    for (const plugin of detected.plugins) plugins.add(plugin);
+    for (const skill of detected.skills) skills.add(skill);
+    for (const capability of detected.explicit) explicit.add(capability);
+    evidence.push(...detected.evidence);
+    rejected.push(...detected.rejected);
+  }
+
+  for (const { label, value } of [
+    { label: '--require-codex-plugin', value: requiredPlugins },
+    { label: 'HIVE_MIND_CODEX_REQUIRED_PLUGINS', value: env?.HIVE_MIND_CODEX_REQUIRED_PLUGINS },
+  ]) {
+    const overrides = parseRequiredCapabilityOverrides(value);
+    if (overrides.plugins.length === 0 && overrides.invalid.length === 0) continue;
+    sources.push(label);
+    for (const selector of overrides.plugins) {
+      plugins.add(selector);
+      // An operator override is as explicit as a requirement gets, so it fails
+      // closed like any other declared capability (issue #2088).
+      explicit.add(selector);
+      evidence.push({ capability: selector, line: `${label}=${selector}`, explicit: true, source: label });
+    }
+    for (const token of overrides.invalid) rejected.push({ capability: token, line: `${label}=${token} (expected plugin@marketplace)`, source: label });
+  }
+
+  return { plugins: [...plugins].sort(), skills: [...skills].sort(), explicit: [...explicit].sort(), evidence, rejected, sources, skippedInstructionFiles: instructions.skipped };
+}
+
 const replaceWithRelativeSymlink = async ({ source, target }) => {
   try {
     const current = await fs.readlink(target);
@@ -586,22 +768,35 @@ export async function runCodexCapabilityPreflight(options = {}) {
   }
 }
 
-async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir, env = process.env, baseCodexHome = env.HIVE_MIND_PARENT_CODEX_HOME || env.CODEX_HOME || path.join(os.homedir(), '.codex'), codexPath = 'codex', runCommand = defaultRunCommand, log = async () => {} } = {}) {
-  if (!owner || !repo || !issueNumber) return { required: false, plugins: [], codexHome: null };
+async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir, requiredPlugins, env = process.env, baseCodexHome = env.HIVE_MIND_PARENT_CODEX_HOME || env.CODEX_HOME || path.join(os.homedir(), '.codex'), codexPath = 'codex', runCommand = defaultRunCommand, log = async () => {} } = {}) {
+  // Issue #2102: requirements no longer come from the issue alone, so a missing
+  // issue number (a pull-request continuation, for example) must not skip the
+  // repository's own AGENTS.md/CLAUDE.md files or an operator override. Owner and
+  // repo are still required: the scoped CODEX_HOME is keyed on them.
+  if (!owner || !repo) return { required: false, plugins: [], codexHome: null };
 
   // `executeToolWithBun` uses a shell expression for execution. Preflight uses
   // execFile and therefore selects the installed Codex binary directly.
   const command = /\s/u.test(codexPath) ? 'codex' : codexPath;
-  const requirementText = await readIssueRequirementText({ owner, repo, issueNumber, runCommand, env });
-  const requirements = detectRequiredCodexCapabilities(requirementText);
-  for (const { capability, line } of requirements.rejected || []) {
-    await log(`   ⏭️  Ignored non-capability token '${capability}' from: ${line.slice(0, 160)}`, { verbose: true });
+  const requirements = await collectCodexCapabilityRequirements({ owner, repo, issueNumber, projectDir, runCommand, env, requiredPlugins });
+  const scanned = `sources: ${requirements.sources.join(', ') || 'none'}`;
+  for (const { capability, line, source } of requirements.rejected || []) {
+    await log(`   ⏭️  Ignored non-capability token '${capability}' from ${source || 'requirement text'}: ${line.slice(0, 160)}`, { verbose: true });
+  }
+  for (const { relativePath, reason, bytes } of requirements.skippedInstructionFiles || []) {
+    await log(`   ⏭️  Skipped instruction file ${relativePath} (${reason}${reason === 'too-large' ? `: ${bytes} bytes` : ''})`, { verbose: true });
+  }
+  // Issue #2102: a silent early return made a missed requirement indistinguishable
+  // from a task that has none. Name what was scanned so the next report is
+  // diagnosable from the log alone.
+  if (requirements.plugins.length === 0 && requirements.skills.length === 0) {
+    await log(`🔌 Codex capability preflight: no plugin or skill requirements detected (${scanned})`, { verbose: true });
+    return { required: false, plugins: [], codexHome: null, sources: requirements.sources };
   }
-  if (requirements.plugins.length === 0 && requirements.skills.length === 0) return { required: false, plugins: [], codexHome: null };
 
-  await log(`🔌 Codex capability preflight: detected ${requirements.plugins.length} plugin and ${requirements.skills.length} skill requirement(s)`);
-  for (const { capability, line } of requirements.evidence || []) {
-    await log(`   🔎 '${capability}' detected from: ${line.slice(0, 160)}`, { verbose: true });
+  await log(`🔌 Codex capability preflight: detected ${requirements.plugins.length} plugin and ${requirements.skills.length} skill requirement(s) (${scanned})`);
+  for (const { capability, line, source } of requirements.evidence || []) {
+    await log(`   🔎 '${capability}' detected from ${source || 'requirement text'}: ${line.slice(0, 160)}`, { verbose: true });
   }
   // Every Codex-side preflight operation runs from the checkout that the
   // solver will enter. Besides matching `codex exec`, this keeps any future
@@ -677,9 +872,12 @@ async function provisionCodexCapabilities({ owner, repo, issueNumber, projectDir
 export default {
   applyCodexCapabilityEnv,
   buildPluginCachePath,
+  collectAgentInstructionFiles,
+  collectCodexCapabilityRequirements,
   detectRequiredCodexCapabilities,
   isCapabilityName,
   isExplicitRequirement,
+  parseRequiredCapabilityOverrides,
   readMaterializedPluginSkills,
   repairScopedPluginPayloads,
   resolveRequiredCapabilities,

package/src/codex-health.lib.mjs

@@ -11,6 +11,7 @@
 // Both are re-exported from codex.lib.mjs for backward compatibility, so existing
 // importers (and tests) can keep importing them from either module.
 
+import { normalizePluginSelector } from './codex-capability-preflight.lib.mjs';
 import { isENOSPC } from './lib.mjs';
 
 const unwrapCodexErrorMessage = value => {
@@ -115,6 +116,84 @@ export const getCodexErrorEventSummary = codexJsonState => {
   };
 };
 
+// Issue #2102: `request_plugin_install` can never succeed under `codex exec`.
+// The tool validates its `plugin_id` against the server-driven
+// `<recommended_plugins>` list with an exact string comparison, and `codex exec`
+// auto-cancels the elicitation it would raise, so a model that reaches for it is
+// stuck in a loop it cannot exit. In the captured GCS-TS#5 runs that produced no
+// work at all, the only trace was in codex's OTEL text stream (the tool is a
+// builtin, so there is no NDJSON `mcp_tool_call` item to inspect):
+//
+//   INFO codex_otel.log_only: event.name="codex.tool_result"
+//     tool_name=request_plugin_install call_id=… arguments={"plugin_id":"…"}
+//     … success=false output=plugin_id must match one of the entries in the
+//     <recommended_plugins> list
+//   ERROR codex_core::tools::router: error=plugin_id must match one of the
+//     entries in the <recommended_plugins> list
+//
+// Both patterns are anchored at the beginning of the line rather than matched
+// anywhere in it: codex echoes the stdout of every command it runs back into its
+// own stream (issue #1955), and this repository's own case-study logs contain
+// these very lines. An echoed copy is always preceded by the emitting tool's own
+// prefix (`tool_name=shell … output=…`), so requiring `request_plugin_install` to
+// be the tool of the line's *own* event, and the router error to open the line,
+// keeps replayed text from being read as a live rejection.
+const PLUGIN_INSTALL_MESSAGE_TEXT = 'plugin_id must match one of the entries in the <recommended_plugins> list';
+const PLUGIN_INSTALL_MESSAGE_PATTERN = /plugin_id must match one of the entries in the <recommended_plugins> list/;
+const PLUGIN_INSTALL_TOOL_RESULT = /^(?:\S+\s+)?(?:TRACE|DEBUG|INFO|WARN|ERROR)\s+codex_otel\.log_only:\s+event\.name="codex\.tool_result"\s+tool_name=request_plugin_install\b/;
+const PLUGIN_INSTALL_ROUTER_ERROR = /^(?:\S+\s+)?ERROR\s+codex_core::tools::router:\s+error=plugin_id must match one of the entries in the <recommended_plugins> list/;
+const PLUGIN_INSTALL_CALL_ID = /\bcall_id=(\S+)/;
+const PLUGIN_INSTALL_PLUGIN_ID = /"plugin_id"\s*:\s*"([^"]+)"/;
+const PLUGIN_INSTALL_SUCCESS = /\bsuccess=(true|false)\b/;
+
+export const matchCodexPluginInstallRejection = line => {
+  const text = String(line || '');
+  if (PLUGIN_INSTALL_ROUTER_ERROR.test(text)) return { source: 'router', callId: null, pluginId: null, message: PLUGIN_INSTALL_MESSAGE_TEXT };
+  if (!PLUGIN_INSTALL_TOOL_RESULT.test(text)) return null;
+  if (!PLUGIN_INSTALL_MESSAGE_PATTERN.test(text)) return null;
+  if (PLUGIN_INSTALL_SUCCESS.exec(text)?.[1] === 'true') return null;
+  return { source: 'tool_result', callId: PLUGIN_INSTALL_CALL_ID.exec(text)?.[1] || null, pluginId: PLUGIN_INSTALL_PLUGIN_ID.exec(text)?.[1] || null, message: PLUGIN_INSTALL_MESSAGE_TEXT };
+};
+
+// Issue #2102: a rejected runtime install means the capability preflight did not
+// provision what the task needs, so the run cannot do the work it was asked to
+// do. It is reported as a failure only when nothing was produced: a model may
+// probe `request_plugin_install` and then complete the task without the plugin,
+// and failing that run retroactively would discard real output.
+export const getCodexPluginProvisioningHealth = (codexJsonState, { capabilityPreflight = null } = {}) => {
+  const rejections = codexJsonState?.pluginInstallRejections || [];
+  const requestedPlugins = [...new Set(rejections.map(entry => entry.pluginId).filter(Boolean))].sort();
+  const fileChanges = codexJsonState?.fileChanges || [];
+  const producedWork = fileChanges.length > 0;
+  const detected = rejections.length > 0;
+
+  const reasons = [];
+  const guidance = [];
+  if (detected) {
+    reasons.push(`Codex called request_plugin_install${requestedPlugins.length > 0 ? ` for ${requestedPlugins.join(', ')}` : ''} and codex rejected it: ${PLUGIN_INSTALL_MESSAGE_TEXT}. Under codex exec this tool can never install a plugin, so the model cannot recover on its own.`);
+    reasons.push(capabilityPreflight?.required ? `The Hive Mind Codex capability preflight ran for ${(capabilityPreflight.plugins || []).join(', ') || 'no plugins'}, so the plugin the model asked for was not among the requirements it discovered.` : 'The Hive Mind Codex capability preflight detected no requirements for this task, so nothing was provisioned before codex exec.');
+    for (const plugin of requestedPlugins.length > 0 ? requestedPlugins : ['<plugin>@<marketplace>']) {
+      // Issue #2102: the model asks for `@openai-curated-remote`, which is a
+      // synthesized namespace that `codex plugin add` cannot install; the
+      // preflight's normalization maps it onto the installable `@openai-curated`
+      // marketplace, so the guidance must quote the selector that actually works.
+      guidance.push(`Declare the requirement so the preflight provisions it: --require-codex-plugin ${normalizePluginSelector(plugin)} (or HIVE_MIND_CODEX_REQUIRED_PLUGINS).`);
+    }
+    guidance.push('Requirements declared in the target repository AGENTS.md / CLAUDE.md are discovered automatically; run with --verbose to see the sources the preflight scanned.');
+  }
+
+  return {
+    healthy: !detected || producedWork,
+    detected,
+    producedWork,
+    requestedPlugins,
+    rejections,
+    message: detected ? reasons[0] : null,
+    reasons,
+    guidance,
+  };
+};
+
 // Issue #1990: A Codex run can exit 0 with no fatal `turn.failed`/error event yet
 // still be fundamentally broken. Under docker isolation two long-running
 // `solve --tool codex` tasks reported SUCCESS (Exit Code: 0) while their
@@ -189,3 +268,47 @@ export const getCodexCompletionHealth = (codexJsonState, { lastMessage = '' } =
     reasons,
   };
 };
+
+// Reporting helpers for the run gates in codex.lib.mjs. They live here with the
+// analysis they narrate so codex.lib.mjs stays inside the 1500-line budget
+// (issues #1730 / #1990).
+export const logCodexResourceSnapshot = async ({ getResourceSnapshot, log }) => {
+  const resourcesAfter = await getResourceSnapshot();
+  await log('\n📈 System resources after execution:', { verbose: true });
+  await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
+  await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+};
+
+export const reportCodexCompletionFailure = async ({ completionHealth, log, getResourceSnapshot }) => {
+  await log('\n\n❌ Codex exited 0 but the run did not complete — treating as failure', { level: 'error' });
+  for (const reason of completionHealth.reasons) {
+    await log(`   • ${reason}`, { level: 'error' });
+  }
+  await log(`   📊 turn.started=${completionHealth.turnStarted}, turn.completed=${completionHealth.turnCompleted}, turn.failed=${completionHealth.turnFailed}`, { verbose: true });
+  if (completionHealth.diskPressureDetected) {
+    await log('   💽 Disk-exhaustion evidence (diagnostic):', { level: 'error' });
+    for (const evidence of completionHealth.diskEvidence.slice(0, 5)) {
+      await log(`      ↳ [${evidence.source}] ${evidence.text}`, { level: 'error' });
+    }
+    await log('   💡 Free disk space before retrying. Under docker isolation the container is preserved on failure for inspection.', { level: 'error' });
+  }
+  await logCodexResourceSnapshot({ getResourceSnapshot, log });
+};
+
+export const reportCodexPluginProvisioning = async ({ pluginProvisioning, log }) => {
+  if (!pluginProvisioning.detected) return;
+  if (!pluginProvisioning.healthy) {
+    await log('\n\n❌ Codex could not obtain a required plugin at runtime — treating as failure', { level: 'error' });
+    for (const reason of pluginProvisioning.reasons) {
+      await log(`   • ${reason}`, { level: 'error' });
+    }
+    for (const hint of pluginProvisioning.guidance) {
+      await log(`   💡 ${hint}`, { level: 'error' });
+    }
+    return;
+  }
+  await log(`\n⚠️ Codex asked to install ${pluginProvisioning.requestedPlugins.join(', ') || 'a plugin'} at runtime and was rejected, but the run still produced changes`, { level: 'warning' });
+  for (const hint of pluginProvisioning.guidance) {
+    await log(`   💡 ${hint}`, { level: 'warning', verbose: true });
+  }
+};

package/src/codex.lib.mjs

@@ -17,8 +17,8 @@ const os = (await use('os')).default;
 import { log } from './lib.mjs';
 // Issues #1955 / #1990: run-health analysis lives in its own module to keep this
 // file under the max-lines budget. Re-exported below for backward compatibility.
-import { getCodexErrorEventSummary, getCodexCompletionHealth } from './codex-health.lib.mjs';
-export { getCodexErrorEventSummary, getCodexCompletionHealth };
+import { getCodexErrorEventSummary, getCodexCompletionHealth, getCodexPluginProvisioningHealth, logCodexResourceSnapshot, matchCodexPluginInstallRejection, reportCodexCompletionFailure, reportCodexPluginProvisioning } from './codex-health.lib.mjs';
+export { getCodexErrorEventSummary, getCodexCompletionHealth, getCodexPluginProvisioningHealth, matchCodexPluginInstallRejection };
 import { reportError } from './sentry.lib.mjs';
 import { timeouts, retryLimits } from './config.lib.mjs';
 import { detectUsageLimit, formatUsageLimitMessage } from './usage-limit.lib.mjs';
@@ -351,6 +351,7 @@ export const parseCodexExecJsonOutput = (output, state = {}, requestedModelId =
     itemErrors: state.itemErrors || [],
     turnFailures: state.turnFailures || [],
     streamErrors: state.streamErrors || [],
+    pluginInstallRejections: state.pluginInstallRejections || [],
     observedUsageFieldSets: state.observedUsageFieldSets || [],
     observedModelDiagnosticPaths: state.observedModelDiagnosticPaths || [],
   };
@@ -371,6 +372,11 @@ export const parseCodexExecJsonOutput = (output, state = {}, requestedModelId =
     try {
       data = sanitizeObjectStrings(JSON.parse(line));
     } catch {
+      // Issue #2102: `request_plugin_install` is a codex builtin, so its rejection
+      // never arrives as an NDJSON item — it only exists in the interleaved OTEL
+      // text stream, which is exactly the set of lines that fail to parse here.
+      const rejection = matchCodexPluginInstallRejection(line);
+      if (rejection) nextState.pluginInstallRejections.push(rejection);
       continue;
     }
 
@@ -745,7 +751,10 @@ export const executeCodex = async params => {
   // it natively from .agents/skills/handoff/SKILL.md (no-op unless --use-handoff).
   await deployHandoffSkill({ tempDir, argv, log, $ });
   const codexBaseEnv = getCodexExecEnv(argv.verbose);
-  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log, env: codexBaseEnv });
+  // Issue #2102: the target repository's own agent instruction files are part of
+  // the requirement corpus, so the preflight needs the checkout; `--require-codex-plugin`
+  // is the explicit escape hatch for requirements no document states.
+  const capabilityPreflight = await runCodexCapabilityPreflight({ owner, repo, issueNumber, projectDir: tempDir, codexPath, log, env: codexBaseEnv, requiredPlugins: argv.requireCodexPlugin });
   // Execute the Codex command
   return await executeCodexCommand({
     tempDir,
@@ -961,6 +970,7 @@ export const executeCodexCommand = async params => {
         itemErrors: [],
         turnFailures: [],
         streamErrors: [],
+        pluginInstallRejections: [],
         observedUsageFieldSets: [],
         observedModelDiagnosticPaths: [],
       };
@@ -1127,13 +1137,25 @@ export const executeCodexCommand = async params => {
         await log(`⚠️ Codex public pricing estimate unavailable: ${pricingInfo.error}`, { level: 'warning', verbose: true });
       }
       const resultModelUsage = pricingInfo?.tokenUsage ? buildCodexResultModelUsage(firstActualModelId, pricingInfo.tokenUsage, pricingInfo) : null;
+      // Every exit from this run reports the same accounting fields; only the
+      // outcome-specific ones differ. `lastTextContent` is the result summary
+      // captured from the JSON output stream (issue #1263).
+      const buildRunResult = outcome => ({
+        sessionId,
+        limitReached,
+        limitResetTime,
+        pricingInfo,
+        publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
+        resultModelUsage,
+        subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
+        codexJsonDetails: codexJsonState,
+        resultSummary: lastTextContent || null,
+        ...outcome,
+      });
 
       // Check for authentication errors first - these should never be retried
       if (authError) {
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
         // Throw an error to stop retries and propagate the auth failure
         const error = new Error('Codex authentication failed - 401 Unauthorized. Please run: codex login');
@@ -1199,25 +1221,9 @@ export const executeCodexCommand = async params => {
           await log(`   Error events: item=${codexErrorSummary.counts.item}, turn=${codexErrorSummary.counts.turn}, stream=${codexErrorSummary.counts.stream}`, { level: 'error' });
         }
 
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: codexErrorSummary,
-          result: codexErrorSummary.message,
-          resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-        };
+        return buildRunResult({ success: false, errorInfo: codexErrorSummary, result: codexErrorSummary.message });
       }
 
       if (exitCode !== 0) {
@@ -1269,24 +1275,22 @@ export const executeCodexCommand = async params => {
           await log(`\n\n❌ Codex command failed with exit code ${exitCode}`, { level: 'error' });
         }
 
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await logCodexResourceSnapshot({ getResourceSnapshot, log });
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: getCodexErrorEventSummary(codexJsonState),
-          resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-        };
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState) });
+      }
+
+      // Issue #2102: a rejected `request_plugin_install` means codex asked for a
+      // capability the preflight did not provision, and under `codex exec` that
+      // request can never succeed — so a run that produced nothing is blocked,
+      // not finished. Reporting it as a named failure (instead of an empty
+      // success) is what makes the missing requirement visible.
+      const pluginProvisioning = getCodexPluginProvisioningHealth(codexJsonState, { capabilityPreflight });
+      await reportCodexPluginProvisioning({ pluginProvisioning, log });
+      if (!pluginProvisioning.healthy) {
+        if (sessionId && !argv.resume) argv.resume = sessionId;
+
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState), pluginProvisioning, result: [pluginProvisioning.message, ...pluginProvisioning.guidance].join(' ') });
       }
 
       // Issue #1990: exit code 0 and the absence of a fatal codex error event are
@@ -1297,23 +1301,7 @@ export const executeCodexCommand = async params => {
       // container filesystem needed to inspect and retry the failure (#1990).
       const completionHealth = getCodexCompletionHealth(codexJsonState, { lastMessage });
       if (!completionHealth.healthy) {
-        await log('\n\n❌ Codex exited 0 but the run did not complete — treating as failure', { level: 'error' });
-        for (const reason of completionHealth.reasons) {
-          await log(`   • ${reason}`, { level: 'error' });
-        }
-        await log(`   📊 turn.started=${completionHealth.turnStarted}, turn.completed=${completionHealth.turnCompleted}, turn.failed=${completionHealth.turnFailed}`, { verbose: true });
-        if (completionHealth.diskPressureDetected) {
-          await log('   💽 Disk-exhaustion evidence (diagnostic):', { level: 'error' });
-          for (const evidence of completionHealth.diskEvidence.slice(0, 5)) {
-            await log(`      ↳ [${evidence.source}] ${evidence.text}`, { level: 'error' });
-          }
-          await log('   💡 Free disk space before retrying. Under docker isolation the container is preserved on failure for inspection.', { level: 'error' });
-        }
-
-        const resourcesAfter = await getResourceSnapshot();
-        await log('\n📈 System resources after execution:', { verbose: true });
-        await log(`   Memory: ${resourcesAfter.memory.split('\n')[1]}`, { verbose: true });
-        await log(`   Load: ${resourcesAfter.load}`, { verbose: true });
+        await reportCodexCompletionFailure({ completionHealth, log, getResourceSnapshot });
 
         // Issue #1990: preserve the codex session so an outer full restart can
         // resume with context (mirrors the transient-error retry above and the
@@ -1323,23 +1311,7 @@ export const executeCodexCommand = async params => {
         // restart at the orchestration level.
         if (sessionId && !argv.resume) argv.resume = sessionId;
 
-        return {
-          success: false,
-          sessionId,
-          limitReached,
-          limitResetTime,
-          pricingInfo,
-          publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-          resultModelUsage,
-          subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-          codexJsonDetails: codexJsonState,
-          errorInfo: getCodexErrorEventSummary(codexJsonState),
-          completionHealth,
-          incompleteSession: completionHealth.incompleteSession,
-          diskPressureDetected: completionHealth.diskPressureDetected,
-          result: completionHealth.reasons.join(' '),
-          resultSummary: lastTextContent || null,
-        };
+        return buildRunResult({ success: false, errorInfo: getCodexErrorEventSummary(codexJsonState), completionHealth, pluginProvisioning, incompleteSession: completionHealth.incompleteSession, diskPressureDetected: completionHealth.diskPressureDetected, result: completionHealth.reasons.join(' ') });
       }
 
       await log('\n\n✅ Codex command completed');
@@ -1351,18 +1323,7 @@ export const executeCodexCommand = async params => {
         await log('⚠️ No result summary captured from Codex output or last-message file', { level: 'warning', verbose: true });
       }
 
-      return {
-        success: true,
-        sessionId,
-        limitReached,
-        limitResetTime,
-        pricingInfo,
-        publicPricingEstimate: pricingInfo?.totalCostUSD ?? null,
-        resultModelUsage,
-        subAgentCalls: codexJsonState.subAgentCalls.length > 0 ? codexJsonState.subAgentCalls : null,
-        codexJsonDetails: codexJsonState,
-        resultSummary: lastTextContent || null, // Issue #1263: Use last text content from JSON output stream
-      };
+      return buildRunResult({ success: true, pluginProvisioning });
     } catch (error) {
       // Don't report auth errors to Sentry as they are user configuration issues
       if (!error.isAuthError) {

package/src/option-suggestions.lib.mjs

@@ -247,6 +247,7 @@ const KNOWN_OPTION_NAMES = [
   'keep-going-until-all-requirements-are-fully-done',
   'keep-working',
   'keep-going',
+  'require-codex-plugin',
 ];
 
 /**

package/src/solve.config.lib.mjs

@@ -715,6 +715,15 @@ export const SOLVE_OPTION_DEFINITIONS = {
     type: 'string',
     description: 'Comma-separated list of MCP server names that gemini-cli is allowed to call (passes --allowed-mcp-server-names to gemini-cli). Only used when --tool gemini.',
   },
+  // Issue #2102: the Codex capability preflight discovers requirements from the
+  // issue text and the target repository's agent instruction files (AGENTS.md,
+  // CLAUDE.md, .codex/). This is the escape hatch for a requirement no document
+  // states — codex's own `request_plugin_install` can never install anything
+  // under `codex exec`, so declaring it here is the only way in.
+  'require-codex-plugin': {
+    type: 'string',
+    description: 'Comma-separated list of Codex plugins (plugin@marketplace) that must be installed into the scoped CODEX_HOME before codex exec starts, in addition to the ones discovered from the issue text and the repository AGENTS.md/CLAUDE.md files. Fails the run when a listed plugin is unavailable. Equivalent to HIVE_MIND_CODEX_REQUIRED_PLUGINS. Only used when --tool codex.',
+  },
 };
 
 function hasRawOption(rawArgs, optionName) {

package/src/solve.mjs

@@ -1117,6 +1117,17 @@ try {
       await log('');
     }
 
+    // Preserve work before remote diagnostics; issue #2101 ended during log upload.
+    try {
+      const { criticalErrorRecovery } = await import('./config.lib.mjs');
+      if (criticalErrorRecovery.autoCommitUncommittedChanges) {
+        const { commitUncommittedChangesOnCriticalError } = await import('./critical-error-commit.lib.mjs');
+        await commitUncommittedChangesOnCriticalError({ tempDir, branchName, $, log, reason: toolFailureMessage });
+      }
+    } catch (preserveError) {
+      await log(`  ⚠️  Could not auto-commit before failure exit: ${preserveError.message}`, { verbose: true });
+    }
+
     // Attach failure logs before exiting (Issues #1212, #1462: fall back to issue if no PR)
     const hasPR = global.createdPR && global.createdPR.number;
     const hasIssue = global.issueNumber;
@@ -1167,19 +1178,6 @@ try {
       }
     }
 
-    // Issue #1834 (PR #1835 feedback): "on all critical errors we auto commit uncommitted changes by
-    // default." A failed session exits here before the normal auto-commit chokepoint below, so commit
-    // + push any work first. On by default; disable via HIVE_MIND_AUTO_COMMIT_ON_CRITICAL_ERROR=false.
-    try {
-      const { criticalErrorRecovery } = await import('./config.lib.mjs');
-      if (criticalErrorRecovery.autoCommitUncommittedChanges) {
-        const { commitUncommittedChangesOnCriticalError } = await import('./critical-error-commit.lib.mjs');
-        await commitUncommittedChangesOnCriticalError({ tempDir, branchName, $, log, reason: toolFailureMessage });
-      }
-    } catch (preserveError) {
-      await log(`  ⚠️  Could not auto-commit before failure exit: ${preserveError.message}`, { verbose: true });
-    }
-
     await safeExit(1, toolFailureMessage);
   }
 

package/src/tool-retry.lib.mjs

@@ -47,7 +47,11 @@ export const classifyRetryableError = value => {
   // overloaded API anyway. Claude Code already exposes its own per-request fallback
   // via `--fallback-model` (wired in claude.lib.mjs), so we keep `--model` stable and
   // simply retry. Therefore isCapacity is false → retry with the same model.
-  if (lower.includes('overloaded') || lower.includes('overloaded_error')) {
+  // Issue #2101: Codex may exhaust its internal WebSocket/HTTPS attempts and
+  // surface only "We're currently experiencing high demand, which may cause
+  // temporary errors." The terminal message omits both the preceding 503 and
+  // the backend's concurrency_limit code, so it must be recognized directly.
+  if (lower.includes('overloaded') || lower.includes('overloaded_error') || lower.includes('currently experiencing high demand') || lower.includes('too many concurrent requests') || lower.includes('concurrency_limit')) {
     return { message, isRetryable: true, isCapacity: false, label: 'API overload' };
   }