nexus-agents 2.125.21 → 2.125.24

package/dist/cli.js

@@ -24,7 +24,7 @@ import {
 import {
   setupCommandAsync,
   verifyCommand
-} from "./chunk-DCCDTUUP.js";
+} from "./chunk-QIEXH2EA.js";
 import "./chunk-MMWNGT2K.js";
 import {
   AuthHandler,
@@ -144,7 +144,7 @@ import {
   validateCommand,
   validateWorkflow,
   wrapInMarkdownFence
-} from "./chunk-5NG2GBNM.js";
+} from "./chunk-SDA5GEWO.js";
 import "./chunk-3ACDP4E6.js";
 import {
   CATEGORY_DISPLAY_NAMES,
@@ -156,6 +156,7 @@ import {
   shutdownExpertBridge
 } from "./chunk-ZHBKDMHV.js";
 import {
+  ConsensusVoteInputSchema,
   DEFAULT_VOTE_TIMEOUT_MS,
   ErrorPolicySchema,
   VOTER_ROLES,
@@ -181,10 +182,12 @@ import {
 import {
   ImprovementReviewInputSchema,
   calculateFitnessScore,
+  classifySignalPriority,
+  consensusFor,
   createFitnessScoreCalculator,
   registerImprovementReviewTool,
   runImprovementReview
-} from "./chunk-Q2EZE5MP.js";
+} from "./chunk-QAI5JEE2.js";
 import {
   createDefaultPolicyFirewall
 } from "./chunk-K3MKXREZ.js";
@@ -243,7 +246,7 @@ import {
   loadConfig,
   runDoctor,
   validateNexusEnv
-} from "./chunk-B6X3YEEP.js";
+} from "./chunk-647PSXJ5.js";
 import "./chunk-NUBSJGQZ.js";
 import {
   capitalize,
@@ -4027,12 +4030,12 @@ function formatTopsisRanking(result) {
   lines.push(boxLine(color(" TOPSIS Ranking:", ANSI.bold)));
   result.topsisResult.scores.forEach((score, idx) => {
     const rank = idx + 1;
-    const pct = formatPercentage(score.closenessScore, 1);
+    const pct2 = formatPercentage(score.closenessScore, 1);
     const q = ((score.rawValues["quality"] ?? 0) * 10).toFixed(1);
     const c = ((1 - (score.rawValues["cost"] ?? 0)) * 10).toFixed(1);
     const l = ((1 - (score.rawValues["latency"] ?? 0)) * 10).toFixed(1);
     lines.push(
-      boxLine(`   ${String(rank)}. ${score.cliName.padEnd(8)} (${pct}) q=${q} c=${c} l=${l}`)
+      boxLine(`   ${String(rank)}. ${score.cliName.padEnd(8)} (${pct2}) q=${q} c=${c} l=${l}`)
     );
   });
   lines.push(color("\u251C" + horizontalLine() + "\u2524", ANSI.cyan));
@@ -4087,10 +4090,10 @@ function formatExplorationSection(stats) {
     color("\u2502", ANSI.yellow) + " Arm Distribution:".padEnd(BOX_WIDTH - 2) + color("\u2502", ANSI.yellow)
   );
   for (const arm of stats.exploration.armDistribution) {
-    const pct = formatPercentage(arm.proportion, 1);
+    const pct2 = formatPercentage(arm.proportion, 1);
     const bar = "\u2588".repeat(Math.round(arm.proportion * 20));
     lines.push(
-      color("\u2502", ANSI.yellow) + `   ${arm.name.padEnd(8)} ${pct.padStart(6)} ${bar}`.padEnd(BOX_WIDTH - 2) + color("\u2502", ANSI.yellow)
+      color("\u2502", ANSI.yellow) + `   ${arm.name.padEnd(8)} ${pct2.padStart(6)} ${bar}`.padEnd(BOX_WIDTH - 2) + color("\u2502", ANSI.yellow)
     );
   }
   lines.push(color("\u251C" + horizontalLine() + "\u2524", ANSI.yellow));
@@ -4107,9 +4110,9 @@ function formatFeatureImportanceSection(stats) {
     );
     const top3 = arm.featureImportance.slice(0, 3);
     for (const fi of top3) {
-      const pct = formatPercentage(fi.importance, 1);
+      const pct2 = formatPercentage(fi.importance, 1);
       lines.push(
-        color("\u2502", ANSI.yellow) + `     ${fi.feature.padEnd(18)} ${pct.padStart(6)}`.padEnd(BOX_WIDTH - 2) + color("\u2502", ANSI.yellow)
+        color("\u2502", ANSI.yellow) + `     ${fi.feature.padEnd(18)} ${pct2.padStart(6)}`.padEnd(BOX_WIDTH - 2) + color("\u2502", ANSI.yellow)
       );
     }
   }
@@ -9806,6 +9809,11 @@ var COMMAND_CATALOG = [
     description: "Observability-driven improvement loop (#2402). Surfaces threshold breaches; --file-issues opt-in.",
     audience: "advanced"
   },
+  {
+    command: "auto-remediate",
+    description: "Run one auto-remediation cycle (#3540). OFF unless NEXUS_AUTO_REMEDIATE=audit|enforce; never auto-merges.",
+    audience: "maintainer"
+  },
   // ── Maintainer (hidden by default) ───────────────────────────────────────
   {
     command: "demo",
@@ -11324,10 +11332,10 @@ function formatModelStats(models) {
     return lines;
   }
   for (const model of models) {
-    const pct = model.selectionPercent.toFixed(1);
+    const pct2 = model.selectionPercent.toFixed(1);
     const barLength = Math.min(20, Math.max(0, Math.round(model.selectionPercent * 0.2)));
     const bar = "\u2588".repeat(barLength) + "\u2591".repeat(20 - barLength);
-    lines.push(boxLine(`   ${model.name.padEnd(10)} ${bar} ${pct.padStart(5)}%`));
+    lines.push(boxLine(`   ${model.name.padEnd(10)} ${bar} ${pct2.padStart(5)}%`));
     const reward = model.avgReward.toFixed(2);
     const success = formatPercentage(model.successRate);
     lines.push(boxLine(`     reward: ${reward.padStart(5)} | success: ${success.padStart(4)}`));
@@ -17605,7 +17613,7 @@ function startImprovementReviewScheduler(options) {
   let running = false;
   const runOnce = async () => {
     try {
-      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-IR4BP23Z.js");
+      const { runImprovementReview: runImprovementReview2, ImprovementReviewInputSchema: ImprovementReviewInputSchema2 } = await import("./improvement-review-L7MSBESK.js");
       const input = ImprovementReviewInputSchema2.parse({ fileIssues });
       const result = await runImprovementReview2(input, { logger: logger19 });
       logger19.info("Scheduled improvement_review complete", {
@@ -18039,8 +18047,8 @@ async function initUpstreamServers(gatewayConfig, server, logger19) {
     servers: upstreamServers.length,
     tools: tools.length
   });
-  const { z: z8 } = await import("zod");
-  const passthroughSchema = z8.looseObject({});
+  const { z: z9 } = await import("zod");
+  const passthroughSchema = z9.looseObject({});
   for (const tool of tools) {
     const toolName = tool.name;
     const desc = tool.description ?? `Upstream tool: ${toolName}`;
@@ -21617,29 +21625,29 @@ function checkThreshold(value, threshold, comparison, label, format) {
   return `${label} ${format(value)} ${comparison === "min" ? "<" : ">"} ${format(threshold)}`;
 }
 function buildThresholdChecks(r, t) {
-  const { pct, dec, ms, bytes } = formatters;
+  const { pct: pct2, dec, ms, bytes } = formatters;
   return [
-    checkThreshold(r.recallAtK[5] ?? 0, t.minRecallAt5, "min", "Recall@5", pct),
-    checkThreshold(r.precisionAtK[5] ?? 0, t.minPrecisionAt5, "min", "Precision@5", pct),
+    checkThreshold(r.recallAtK[5] ?? 0, t.minRecallAt5, "min", "Recall@5", pct2),
+    checkThreshold(r.precisionAtK[5] ?? 0, t.minPrecisionAt5, "min", "Precision@5", pct2),
     checkThreshold(r.mrr, t.minMrr, "min", "MRR", dec),
     checkThreshold(r.latencyP95Ms, t.maxLatencyP95Ms, "max", "P95 latency", ms),
-    checkThreshold(r.coherenceScore, t.minCoherenceScore, "min", "Coherence", pct),
+    checkThreshold(r.coherenceScore, t.minCoherenceScore, "min", "Coherence", pct2),
     checkThreshold(r.growthRateBytesPerOp, t.maxGrowthRateBytesPerOp, "max", "Growth rate", bytes),
     checkThreshold(
       r.decayConsistencyScore,
       t.minDecayConsistencyScore,
       "min",
       "Decay consistency",
-      pct
+      pct2
     ),
     checkThreshold(
       r.promotionRetentionRate,
       t.minPromotionRetentionRate,
       "min",
       "Promotion retention",
-      pct
+      pct2
     ),
-    checkThreshold(r.decayRegretScore, t.maxDecayRegretScore, "max", "Decay regret", pct)
+    checkThreshold(r.decayRegretScore, t.maxDecayRegretScore, "max", "Decay regret", pct2)
   ];
 }
 function validateBenchmarkResults(result, thresholds) {
@@ -22562,19 +22570,19 @@ function renderMetricBar(value, max) {
 }
 function renderSwarmMetrics(w, health) {
   const c = colors;
-  const pct = (v) => `${(v * 100).toFixed(1)}%`;
+  const pct2 = (v) => `${(v * 100).toFixed(1)}%`;
   w(`  ${c.bold}Swarm Health Metrics${c.reset}
 `);
   w(
-    `  Agent Utilization:       ${renderMetricBar(health.agentUtilization, 1)} ${pct(health.agentUtilization)}
+    `  Agent Utilization:       ${renderMetricBar(health.agentUtilization, 1)} ${pct2(health.agentUtilization)}
 `
   );
   w(
-    `  Collaboration Efficiency:${renderMetricBar(health.collaborationEfficiency, 1)} ${pct(health.collaborationEfficiency)}
+    `  Collaboration Efficiency:${renderMetricBar(health.collaborationEfficiency, 1)} ${pct2(health.collaborationEfficiency)}
 `
   );
   w(
-    `  Routing Accuracy:        ${renderMetricBar(health.routingAccuracy, 1)} ${pct(health.routingAccuracy)}
+    `  Routing Accuracy:        ${renderMetricBar(health.routingAccuracy, 1)} ${pct2(health.routingAccuracy)}
 `
   );
   w(`  Weekly Regret:           ${health.weeklyRegret.toFixed(3)}
@@ -22593,10 +22601,10 @@ function renderCliHealth(w, entries) {
 `);
   for (const entry of entries) {
     const rateColor = entry.successRate >= 0.8 ? c.green : entry.successRate >= 0.6 ? c.yellow : c.red;
-    const pct = `${(entry.successRate * 100).toFixed(0)}%`;
+    const pct2 = `${(entry.successRate * 100).toFixed(0)}%`;
     const dur = entry.avgDurationMs >= 1e3 ? `${(entry.avgDurationMs / 1e3).toFixed(1)}s` : `${String(Math.round(entry.avgDurationMs))}ms`;
     w(
-      `  ${entry.cli.padEnd(12)} ${rateColor}${pct.padStart(4)}${c.reset}  ${String(entry.totalTasks).padStart(5)} tasks  ${c.dim}avg ${dur}${c.reset}
+      `  ${entry.cli.padEnd(12)} ${rateColor}${pct2.padStart(4)}${c.reset}  ${String(entry.totalTasks).padStart(5)} tasks  ${c.dim}avg ${dur}${c.reset}
 `
     );
   }
@@ -22905,6 +22913,674 @@ function printSignal(signal) {
   console.log("");
 }
 
+// src/mcp/tools/remediation-research.ts
+var ACTION_BY_CATEGORY = {
+  routing: "adjust-routing",
+  bug: "fix-bug",
+  "tech-debt": "refactor",
+  security: "investigate",
+  // conservative — security is p0/unanimous-gated regardless
+  consensus: "investigate"
+};
+function clip(s, max) {
+  return s.length > max ? s.slice(0, max) : s;
+}
+function buildRemediationPlanFromSignal(signal) {
+  return {
+    signalKey: signal.signalKey,
+    category: signal.category,
+    summary: clip(`Remediate the surfaced signal: ${signal.title}`, 1e3),
+    steps: [
+      {
+        kind: "investigate",
+        description: clip(`Diagnose the root cause behind "${signal.title}".`, 500)
+      },
+      {
+        kind: ACTION_BY_CATEGORY[signal.category],
+        description: clip(
+          `Address the ${signal.category} issue per the signal's evidence; keep the change minimal.`,
+          500
+        )
+      },
+      {
+        kind: "add-test",
+        description: "Add a regression test that fails without the fix and passes with it."
+      }
+    ]
+  };
+}
+
+// src/mcp/tools/remediation-vote-adapter.ts
+function buildVoteInput(proposal, algorithm) {
+  return ConsensusVoteInputSchema.parse({
+    proposal,
+    strategy: algorithm,
+    simulateVotes: false
+    // never gate auto-remediation on simulated votes
+  });
+}
+function makeDefaultRunner(logger19) {
+  return async (proposal, algorithm) => {
+    const { result } = await executeVoting(buildVoteInput(proposal, algorithm), logger19);
+    return {
+      approved: result.outcome === "approved",
+      approvalPercentage: result.approvalPercentage
+    };
+  };
+}
+function makeVoteAdapter(runner, logger19 = createLogger({ tool: "auto-remediation-vote" })) {
+  const run = runner ?? makeDefaultRunner(logger19);
+  return (input) => run(input.proposal, input.algorithm);
+}
+
+// src/mcp/tools/auto-remediation-lease.ts
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
+function lockRef(key) {
+  return `refs/locks/${key}`;
+}
+var defaultGhRunner = async (args) => {
+  try {
+    const { stdout, stderr } = await execFileAsync3("gh", [...args]);
+    return { exitCode: 0, stdout, stderr };
+  } catch (err2) {
+    const e = err2;
+    return {
+      exitCode: typeof e.code === "number" ? e.code : 1,
+      stdout: e.stdout ?? "",
+      stderr: e.stderr ?? e.message ?? "gh failed"
+    };
+  }
+};
+function makeGitRefLeaseAcquirer(opts) {
+  const gh = opts.gh ?? defaultGhRunner;
+  return async (key) => {
+    const ref = lockRef(key);
+    const res = await gh([
+      "api",
+      "-X",
+      "POST",
+      `repos/${opts.repo}/git/refs`,
+      "-f",
+      `ref=${ref}`,
+      "-f",
+      `sha=${opts.sha}`
+    ]);
+    if (res.exitCode !== 0) {
+      opts.logger?.info("auto-remediation lease not acquired (held or error) \u2014 fail-closed", {
+        ref,
+        stderr: res.stderr.slice(0, 200)
+      });
+      return null;
+    }
+    return {
+      release: async () => {
+        const del = await gh([
+          "api",
+          "-X",
+          "DELETE",
+          `repos/${opts.repo}/git/refs/${stripRefsPrefix(ref)}`
+        ]);
+        if (del.exitCode !== 0) {
+          opts.logger?.warn("auto-remediation lease release failed (stale lock; see #3646)", {
+            ref,
+            stderr: del.stderr.slice(0, 200)
+          });
+        }
+      }
+    };
+  };
+}
+function stripRefsPrefix(ref) {
+  return ref.replace(/^refs\//, "");
+}
+
+// src/mcp/tools/auto-remediation-deps.ts
+var NOT_READY = {
+  shadowSelections: 0,
+  judgedSelections: 0,
+  judgedSound: 0
+};
+function buildAutoRemediationDeps(opts = {}) {
+  const logger19 = opts.logger ?? createLogger({ tool: "auto-remediation" });
+  const acquireLease = opts.repo !== void 0 && opts.sha !== void 0 ? makeGitRefLeaseAcquirer({ repo: opts.repo, sha: opts.sha, logger: logger19 }) : (
+    // Fail-closed: without a configured repo/sha we can't take the cross-process
+    // lease, so enforce must not proceed. (Audit never calls this.)
+    async () => Promise.resolve(null)
+  );
+  return {
+    research: (signal) => Promise.resolve(buildRemediationPlanFromSignal(signal)),
+    vote: makeVoteAdapter(opts.voteRunner, logger19),
+    acquireLease,
+    readinessEvidence: opts.readiness ?? (() => Promise.resolve(NOT_READY)),
+    implement: () => Promise.reject(
+      new Error(
+        "auto-remediation implement adapter not wired yet (Option B, #3669) \u2014 enforce unavailable"
+      )
+    ),
+    audit: (event) => {
+      logger19.info(`[auto-remediation] ${event.step}`, {
+        ...event.signalKey !== void 0 ? { signalKey: event.signalKey } : {},
+        detail: event.detail
+      });
+    },
+    logger: logger19
+  };
+}
+
+// src/mcp/tools/improvement-remediation-guard.ts
+var DEFAULT_REMEDIATION_GUARD_CONFIG = {
+  cooldownMs: 6 * 60 * 60 * 1e3,
+  // 6h between attempts on the same signal
+  maxGenerations: 1,
+  // a remediation may not spawn a remediation that spawns another
+  maxPerWindow: 5,
+  // mirror MAX_ISSUES_PER_RUN
+  windowMs: 24 * 60 * 60 * 1e3,
+  // per day
+  maxHistory: 500
+};
+var RemediationGuard = class {
+  config;
+  attempts = [];
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_REMEDIATION_GUARD_CONFIG, ...config };
+  }
+  /**
+   * Decide whether a remediation for `signalKey` at `generation` may proceed at
+   * time `now`. Pure read — does not record the attempt (call
+   * {@link recordAttempt} only when the remediation actually proceeds).
+   */
+  canRemediate(signalKey, now, generation = 0) {
+    if (generation > this.config.maxGenerations) {
+      return {
+        allowed: false,
+        blockReason: "depth",
+        detail: `generation ${String(generation)} exceeds maxGenerations ${String(this.config.maxGenerations)} (runaway chain)`
+      };
+    }
+    const last = this.lastAttempt(signalKey);
+    if (last !== void 0 && now - last.timestamp < this.config.cooldownMs) {
+      const waitMs = this.config.cooldownMs - (now - last.timestamp);
+      return {
+        allowed: false,
+        blockReason: "cooldown",
+        detail: `signal '${signalKey}' attempted ${String(Math.round((now - last.timestamp) / 1e3))}s ago; cooldown ${String(Math.round(this.config.cooldownMs / 1e3))}s (wait ${String(Math.round(waitMs / 1e3))}s)`
+      };
+    }
+    const inWindow = this.countInWindow(now);
+    if (inWindow >= this.config.maxPerWindow) {
+      return {
+        allowed: false,
+        blockReason: "rate",
+        detail: `${String(inWindow)} attempts in the last ${String(Math.round(this.config.windowMs / 1e3))}s reaches the cap of ${String(this.config.maxPerWindow)}`
+      };
+    }
+    return { allowed: true, detail: "within cooldown, depth, and rate bounds" };
+  }
+  /** Record that a remediation proceeded. Bounded history (oldest evicted). */
+  recordAttempt(signalKey, now, generation = 0) {
+    this.attempts.push({ signalKey, timestamp: now, generation });
+    if (this.attempts.length > this.config.maxHistory) {
+      this.attempts.splice(0, this.attempts.length - this.config.maxHistory);
+    }
+  }
+  /** Most-recent attempt for a signalKey, if any. */
+  lastAttempt(signalKey) {
+    let found;
+    for (const a of this.attempts) {
+      if (a.signalKey === signalKey && (found === void 0 || a.timestamp > found.timestamp)) {
+        found = a;
+      }
+    }
+    return found;
+  }
+  /** Number of attempts within the rate window ending at `now`. */
+  countInWindow(now) {
+    const cutoff = now - this.config.windowMs;
+    return this.attempts.reduce((n, a) => a.timestamp >= cutoff ? n + 1 : n, 0);
+  }
+};
+var singletonGuard;
+function getRemediationGuard() {
+  singletonGuard ??= new RemediationGuard();
+  return singletonGuard;
+}
+
+// src/mcp/tools/improvement-enforce-readiness.ts
+var DEFAULT_ENFORCE_READINESS_CONFIG = {
+  minShadowSelections: 20,
+  minJudgedRate: 0.8,
+  minSoundnessRate: 0.9,
+  requireNamedEvaluator: true,
+  requireNamedOwner: true
+};
+function pct(n, d) {
+  return d === 0 ? 0 : n / d;
+}
+function presenceCriterion(name, label, value, required) {
+  const present = value !== "";
+  return {
+    name,
+    met: !required || present,
+    detail: present ? `${label}: ${value}` : `no named ${label}`
+  };
+}
+function evaluateEnforceReadiness(evidence, config = DEFAULT_ENFORCE_READINESS_CONFIG) {
+  const judgedRate = pct(evidence.judgedSelections, evidence.shadowSelections);
+  const soundnessRate = pct(evidence.judgedSound, evidence.judgedSelections);
+  const evaluator = evidence.evaluator?.trim() ?? "";
+  const owner = evidence.owner?.trim() ?? "";
+  const criteria = [
+    {
+      name: "volume",
+      met: evidence.shadowSelections >= config.minShadowSelections,
+      detail: `${String(evidence.shadowSelections)} shadow selections (need \u2265 ${String(config.minShadowSelections)})`
+    },
+    {
+      name: "judged-coverage",
+      met: judgedRate >= config.minJudgedRate,
+      detail: `${String(Math.round(judgedRate * 100))}% reviewed (need \u2265 ${String(Math.round(config.minJudgedRate * 100))}%)`
+    },
+    {
+      name: "soundness",
+      met: evidence.judgedSelections > 0 && soundnessRate >= config.minSoundnessRate,
+      detail: `${String(Math.round(soundnessRate * 100))}% of reviewed judged sound (need \u2265 ${String(Math.round(config.minSoundnessRate * 100))}%, with reviews present)`
+    },
+    presenceCriterion("named-evaluator", "evaluator", evaluator, config.requireNamedEvaluator),
+    presenceCriterion("named-owner", "owner", owner, config.requireNamedOwner)
+  ];
+  const blockers = criteria.filter((c) => !c.met).map((c) => c.name);
+  return { ready: blockers.length === 0, criteria, blockers };
+}
+
+// src/mcp/tools/improvement-remediation-capability.ts
+import { z as z8 } from "zod";
+var PHASE_CAPABILITIES = {
+  research: /* @__PURE__ */ new Set(["untrusted-input", "secrets"]),
+  implement: /* @__PURE__ */ new Set(["repo-write", "secrets"])
+};
+var RuleOfTwoViolation = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RuleOfTwoViolation";
+  }
+};
+var CapabilityLedger = class {
+  phase;
+  /** Enter a phase, setting its declared capability set as active. */
+  enterPhase(phase) {
+    this.phase = phase;
+  }
+  /** The active phase, or undefined if none entered. */
+  currentPhase() {
+    return this.phase;
+  }
+  /**
+   * Assert that `capability` is permitted right now. Throws {@link RuleOfTwoViolation}
+   * (fail-closed) if no phase is active or the active phase doesn't grant it —
+   * which structurally prevents the forbidden three-leg conjunction, since no
+   * phase grants more than two legs.
+   */
+  assertCapability(capability) {
+    if (this.phase === void 0) {
+      throw new RuleOfTwoViolation(
+        `capability '${capability}' requested before any remediation phase was entered (fail-closed)`
+      );
+    }
+    const allowed = PHASE_CAPABILITIES[this.phase];
+    if (!allowed.has(capability)) {
+      throw new RuleOfTwoViolation(
+        `capability '${capability}' is not permitted in phase '${this.phase}' (allowed: ${[...allowed].join(", ")})`
+      );
+    }
+  }
+};
+var RemediationActionKindSchema = z8.enum([
+  "investigate",
+  "adjust-routing",
+  "add-test",
+  "refactor",
+  "update-docs",
+  "fix-bug"
+]);
+var RemediationStepSchema = z8.object({
+  kind: RemediationActionKindSchema,
+  description: z8.string().min(1).max(500),
+  /** Optional path hint; bounded inert string, validated for traversal at use. */
+  targetPath: z8.string().min(1).max(300).optional()
+}).strict();
+var RemediationPlanSchema = z8.object({
+  /** Source signal key (mirrors ImprovementSignal.signalKey). */
+  signalKey: z8.string().min(1).max(200),
+  /** Signal category (mirrors SignalCategory). */
+  category: z8.enum(["routing", "tech-debt", "bug", "security", "consensus"]),
+  summary: z8.string().min(1).max(1e3),
+  steps: z8.array(RemediationStepSchema).min(1).max(20)
+}).strict();
+function parseRemediationPlan(raw) {
+  const result = RemediationPlanSchema.safeParse(raw);
+  if (!result.success) {
+    throw new RuleOfTwoViolation(
+      `RemediationPlan failed strict validation at the RESEARCH\u2192IMPLEMENT boundary: ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return result.data;
+}
+function renderPlanAsResearch(plan) {
+  const steps = plan.steps.map((s, i) => {
+    const target = s.targetPath !== void 0 ? ` (target: ${s.targetPath})` : "";
+    return `${String(i + 1)}. [${s.kind}] ${s.description}${target}`;
+  }).join("\n");
+  return `Remediation plan for signal '${plan.signalKey}' (category: ${plan.category}).
+
+${plan.summary}
+
+Steps:
+${steps}`;
+}
+
+// src/mcp/tools/remediation-circuit-breaker.ts
+var DEFAULT_CIRCUIT_BREAKER_CONFIG = { threshold: 3 };
+var RemediationCircuitBreaker = class {
+  threshold;
+  consecutiveFailures = 0;
+  tripped = false;
+  constructor(config = {}) {
+    this.threshold = config.threshold ?? DEFAULT_CIRCUIT_BREAKER_CONFIG.threshold;
+  }
+  /** A remediation succeeded — clears the failure streak (does NOT un-trip). */
+  recordSuccess() {
+    this.consecutiveFailures = 0;
+  }
+  /** A remediation was rejected/failed — trips once the streak reaches the threshold. */
+  recordFailure() {
+    this.consecutiveFailures += 1;
+    if (this.consecutiveFailures >= this.threshold) this.tripped = true;
+  }
+  /** Record by result (convenience). */
+  record(result) {
+    if (result === "success") this.recordSuccess();
+    else this.recordFailure();
+  }
+  /** True once the breaker has tripped — the enforce path must auto-revert to off. */
+  isTripped() {
+    return this.tripped;
+  }
+  /** Re-enable after a consensus re-vote. Clears the trip and the streak. */
+  reset() {
+    this.tripped = false;
+    this.consecutiveFailures = 0;
+  }
+  /** Snapshot for audit/telemetry. */
+  state() {
+    return {
+      tripped: this.tripped,
+      consecutiveFailures: this.consecutiveFailures,
+      threshold: this.threshold
+    };
+  }
+};
+var singleton;
+function getRemediationCircuitBreaker() {
+  singleton ??= new RemediationCircuitBreaker();
+  return singleton;
+}
+
+// src/mcp/tools/remediation-protected-paths.ts
+var PROTECTED_PATH_FRAGMENTS = [
+  // The capability-loop's own machinery (no self-modification).
+  "improvement-remediation",
+  "remediation-priority",
+  "remediation-circuit-breaker",
+  "remediation-protected-paths",
+  "auto-remediation-lease",
+  "improvement-enforce-readiness",
+  "improvement-review",
+  // Consensus / voter configuration (can't weaken its own judge).
+  "src/consensus/",
+  // Governance rules (Rule-of-Two, untrusted-input, etc.).
+  ".rules/",
+  "claude.md",
+  "agents.md",
+  "codeowners",
+  // CI / supply chain (secret exposure).
+  ".github/workflows/",
+  // Security + auth + secrets + access-control.
+  "src/security/",
+  "token-resolver",
+  "access-constraint",
+  "secret",
+  "credential"
+];
+function normalize2(path21) {
+  return path21.replace(/\\/g, "/").replace(/^\.\//, "").toLowerCase();
+}
+function isProtectedPath(path21) {
+  const p = normalize2(path21);
+  return PROTECTED_PATH_FRAGMENTS.some((frag) => p.includes(frag));
+}
+function planTouchesProtectedPath(plan) {
+  const hits = plan.steps.map((s) => s.targetPath).filter((t) => t !== void 0 && isProtectedPath(t));
+  return { protected: hits.length > 0, paths: hits };
+}
+
+// src/mcp/tools/improvement-remediation-enforce.ts
+var AUTO_REMEDIATE_ENV = "NEXUS_AUTO_REMEDIATE";
+var AUTO_REMEDIATE_LEASE_KEY = "auto-remediation";
+function resolveAutoRemediateMode(raw) {
+  if (raw === "enforce") return "enforce";
+  if (raw === "audit") return "audit";
+  return "off";
+}
+var MAX_PER_RUN_DEFAULT = 5;
+async function runAutoRemediation(signals, deps, config = {}) {
+  const mode = config.mode ?? resolveAutoRemediateMode(process.env[AUTO_REMEDIATE_ENV]);
+  const base = { mode, considered: signals.length, skipped: [], plans: [], remediated: [] };
+  if (mode === "off") return base;
+  deps.logger?.info(`auto-remediation starting in '${mode}' mode`, { signals: signals.length });
+  deps.audit({ step: "start", detail: `mode=${mode}, ${String(signals.length)} signals` });
+  let lease = null;
+  if (mode === "enforce") {
+    const gate = await checkEnforceGates(deps, config);
+    if (gate.abort !== void 0) {
+      deps.audit({ step: "abort", detail: gate.abort });
+      return { ...base, aborted: gate.abort };
+    }
+    lease = gate.lease;
+  }
+  try {
+    return await admitAndExecute(signals, deps, config, mode);
+  } finally {
+    if (lease !== null) await lease.release();
+  }
+}
+async function checkEnforceGates(deps, config) {
+  const breaker = config.breaker ?? getRemediationCircuitBreaker();
+  if (breaker.isTripped()) {
+    return {
+      abort: "circuit breaker tripped (sustained failures) \u2014 re-vote required to re-enable",
+      lease: null
+    };
+  }
+  const evidence = await deps.readinessEvidence();
+  const readiness = evaluateEnforceReadiness(
+    evidence,
+    config.readinessConfig ?? DEFAULT_ENFORCE_READINESS_CONFIG
+  );
+  if (!readiness.ready) {
+    return { abort: `not ready to enforce: ${readiness.blockers.join(", ")}`, lease: null };
+  }
+  const lease = await deps.acquireLease(AUTO_REMEDIATE_LEASE_KEY);
+  if (lease === null) {
+    return { abort: "another auto-remediation run holds the lease", lease: null };
+  }
+  return { lease };
+}
+async function admitAndExecute(signals, deps, config, mode) {
+  const guard = config.guard ?? getRemediationGuard();
+  const breaker = config.breaker ?? getRemediationCircuitBreaker();
+  const now = config.now ?? 0;
+  const maxPerRun = config.maxPerRun ?? MAX_PER_RUN_DEFAULT;
+  const skipped = [];
+  const plans = [];
+  const remediated = [];
+  for (const signal of signals) {
+    if (plans.length >= maxPerRun) {
+      skipped.push({
+        signalKey: signal.signalKey,
+        reason: `rate cap ${String(maxPerRun)} reached`
+      });
+      continue;
+    }
+    const o = await processSignal(signal, deps, mode, { guard, breaker, now });
+    if (o.kind === "skip") {
+      skipped.push({ signalKey: signal.signalKey, reason: o.reason });
+      continue;
+    }
+    plans.push({ signalKey: signal.signalKey });
+    if (o.kind === "remediated") remediated.push({ signalKey: signal.signalKey, ...o.pr });
+  }
+  return { mode, considered: signals.length, skipped, plans, remediated };
+}
+async function processSignal(signal, deps, mode, ctx) {
+  const admission = admitSignal(signal, ctx.guard, ctx.now);
+  if (!admission.admit) {
+    deps.audit({ step: "skip", signalKey: signal.signalKey, detail: admission.reason });
+    return { kind: "skip", reason: admission.reason };
+  }
+  const outcome = await executeOne(signal, deps, mode, {
+    guard: ctx.guard,
+    now: ctx.now,
+    requirement: admission.requirement
+  });
+  if (mode === "enforce" && outcome.result !== void 0) ctx.breaker.record(outcome.result);
+  if (outcome.error !== void 0) return { kind: "skip", reason: outcome.error };
+  if (outcome.pr !== void 0) return { kind: "remediated", pr: outcome.pr };
+  return { kind: "plan" };
+}
+function admitSignal(signal, guard, now) {
+  const priority = classifySignalPriority(signal);
+  const requirement = consensusFor(priority);
+  if (!requirement.autoRemediate) {
+    return { admit: false, reason: `${priority} \u2014 file-only (no auto-remediation)` };
+  }
+  const decision = guard.canRemediate(signal.signalKey, now);
+  if (!decision.allowed) return { admit: false, reason: `runaway guard: ${decision.detail}` };
+  return { admit: true, priority, requirement };
+}
+async function consensusGate(signal, plan, requirement, ledger, deps) {
+  const algorithm = requirement.algorithm;
+  if (algorithm === void 0) return "no consensus algorithm for tier";
+  const proposal = `Auto-remediation for '${signal.signalKey}'.
+
+${renderPlanAsResearch(plan)}`;
+  const vote = await deps.vote({ proposal, algorithm });
+  deps.audit({
+    step: "vote",
+    signalKey: signal.signalKey,
+    detail: `${algorithm}: ${vote.approved ? "approved" : "rejected"} (${String(Math.round(vote.approvalPercentage))}%)`
+  });
+  if (!vote.approved) {
+    return `consensus ${algorithm} not reached (${String(Math.round(vote.approvalPercentage))}%) \u2014 left as an issue`;
+  }
+  if (requirement.requiresDryRun) {
+    if (deps.dryRun === void 0) return "p0 requires a dry-run capability (fail-closed)";
+    const dry = await deps.dryRun(plan, ledger);
+    deps.audit({
+      step: "dry-run",
+      signalKey: signal.signalKey,
+      detail: dry.ok ? "ok" : dry.detail
+    });
+    if (!dry.ok) return `p0 dry-run failed: ${dry.detail}`;
+  }
+  return null;
+}
+async function executeOne(signal, deps, mode, ctx) {
+  const { guard, now, requirement } = ctx;
+  const ledger = new CapabilityLedger();
+  ledger.enterPhase("research");
+  let plan;
+  try {
+    plan = parseRemediationPlan(await deps.research(signal, ledger));
+  } catch (err2) {
+    const reason = `research/plan failed: ${err2 instanceof Error ? err2.message : String(err2)}`;
+    deps.audit({ step: "research-failed", signalKey: signal.signalKey, detail: reason });
+    return { error: reason };
+  }
+  deps.audit({
+    step: "plan",
+    signalKey: signal.signalKey,
+    detail: `${String(plan.steps.length)} steps`
+  });
+  const protectedPaths = planTouchesProtectedPath(plan);
+  if (protectedPaths.protected) {
+    const reason = `protected path(s) ${protectedPaths.paths.join(", ")} \u2014 human attestation required`;
+    deps.audit({ step: "protected-path", signalKey: signal.signalKey, detail: reason });
+    return { error: reason };
+  }
+  const blocked = await consensusGate(signal, plan, requirement, ledger, deps);
+  if (blocked !== null) return { error: blocked, result: "failure" };
+  if (mode === "audit") return {};
+  ledger.enterPhase("implement");
+  const pr = await deps.implement(plan, ledger);
+  guard.recordAttempt(signal.signalKey, now);
+  deps.recordOutcome?.(plan, pr);
+  deps.audit({ step: "pr-opened", signalKey: signal.signalKey, detail: pr.prUrl });
+  return { pr, result: "success" };
+}
+
+// src/mcp/tools/auto-remediation-cycle.ts
+function offResult() {
+  return { mode: "off", considered: 0, skipped: [], plans: [], remediated: [] };
+}
+async function runAutoRemediationCycle(config = {}, inject = {}) {
+  const logger19 = config.logger ?? createLogger({ tool: "auto-remediation" });
+  const mode = config.mode ?? resolveAutoRemediateMode(process.env[AUTO_REMEDIATE_ENV]);
+  if (mode === "off") {
+    logger19.debug("auto-remediation off (NEXUS_AUTO_REMEDIATE unset/off) \u2014 no-op");
+    return offResult();
+  }
+  const signals = await collectCycleSignals(inject, config, logger19);
+  const deps = resolveCycleDeps(inject, config, logger19);
+  logger19.info(`auto-remediation cycle: ${mode} over ${String(signals.length)} signals`);
+  return runAutoRemediation(signals, deps, { mode });
+}
+async function collectCycleSignals(inject, config, logger19) {
+  if (inject.collectSignals) return inject.collectSignals();
+  const input = ImprovementReviewInputSchema.parse(
+    config.lookbackDays !== void 0 ? { lookbackDays: config.lookbackDays } : {}
+  );
+  return (await runImprovementReview(input, { logger: logger19 })).signals;
+}
+function resolveCycleDeps(inject, config, logger19) {
+  if (inject.deps) return inject.deps;
+  return buildAutoRemediationDeps({
+    ...config.repo !== void 0 ? { repo: config.repo } : {},
+    ...config.sha !== void 0 ? { sha: config.sha } : {},
+    logger: logger19
+  });
+}
+
+// src/cli/auto-remediate-command.ts
+function summarize2(r) {
+  const head = `auto-remediation [${r.mode}]`;
+  if (r.aborted !== void 0) return `${head}: aborted \u2014 ${r.aborted}
+`;
+  return `${head}: ${String(r.considered)} considered \xB7 ${String(r.plans.length)} planned \xB7 ${String(r.remediated.length)} PR(s) \xB7 ${String(r.skipped.length)} skipped
+`;
+}
+async function handleAutoRemediateCommand(args) {
+  const result = await runAutoRemediationCycle();
+  if (args.options.format === "json") {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(summarize2(result));
+}
+
 // src/cli/migrate-command.ts
 import { cpSync, existsSync as existsSync22, mkdirSync as mkdirSync6, readdirSync as readdirSync3 } from "fs";
 import { homedir } from "os";
@@ -23114,6 +23790,8 @@ var ASYNC_COMMAND_HANDLERS = {
   usage: handleUsageCommand,
   // Issue #2444: improvement-review command (observability-driven improvement loop)
   "improvement-review": handleImprovementReviewCommand,
+  // #3540 phase 3 / #3671: run one auto-remediation cycle (mode from NEXUS_AUTO_REMEDIATE).
+  "auto-remediate": handleAutoRemediateCommand,
   // Issue #2879 / epic #2872: migrate command (relocate homedir state per-repo)
   migrate: handleMigrateCommand,
   // #2305 / #2308 / #2311: Init Portable Command (async because --install spawns npm)