create-agdf 0.14.1 → 0.14.2

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/opencode.js

@@ -0,0 +1,234 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import process from "node:process";
+import { validateEvaluation } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+import { buildEvaluatorPrompt } from "./prompt.js";
+
+export const OPENCODE_EVALUATOR_AGENT = "agdf-evaluator";
+
+export const OPENCODE_DENY_PERMISSIONS = Object.freeze({
+  "*": "deny",
+  read: "deny",
+  edit: "deny",
+  bash: "deny",
+  task: "deny",
+  webfetch: "deny",
+  websearch: "deny",
+  skill: "deny",
+  lsp: "deny",
+  todowrite: "deny",
+  question: "deny",
+  external_directory: "deny",
+});
+
+const executablePermissions = Object.freeze([
+  "edit", "bash", "task", "webfetch", "websearch", "skill", "lsp", "todowrite", "question",
+]);
+
+export function openCodePermissionEnvironment(env = process.env) {
+  return {
+    ...env,
+    OPENCODE_PERMISSION: JSON.stringify(OPENCODE_DENY_PERMISSIONS),
+  };
+}
+
+function preflightFailure(code, detail, evidence = []) {
+  return {
+    surface: "opencode",
+    status: "failed",
+    code,
+    detail,
+    evidence,
+  };
+}
+
+function extractAgentPermissions(output, agentName) {
+  const marker = `${agentName} (`;
+  const lines = output.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.startsWith(marker));
+  if (start < 0) return null;
+  const mode = lines[start].slice(marker.length).split(")")[0];
+  let jsonStart = -1;
+  let depth = 0;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    const line = lines[index].trim();
+    if (jsonStart < 0 && line === "[") {
+      jsonStart = index;
+      depth = 1;
+      continue;
+    }
+    if (jsonStart >= 0) {
+      for (const character of line) {
+        if (character === "[") depth += 1;
+        if (character === "]") depth -= 1;
+      }
+      if (depth === 0) return { mode, permissions: JSON.parse(lines.slice(jsonStart, index + 1).join("\n")) };
+    }
+  }
+  return null;
+}
+
+function terminalPermissionDecision(permissions, permissionName) {
+  let decision = null;
+  for (const entry of permissions) {
+    if (entry?.pattern === "*" && (entry.permission === "*" || entry.permission === permissionName)) {
+      decision = entry.action;
+    }
+  }
+  return decision;
+}
+
+export function preflightOpenCodeEvaluator(options = {}) {
+  const executable = options.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
+  const run = options.execFileSync ?? execFileSync;
+  const cwd = options.cwd ?? process.cwd();
+  const agentName = options.agentName ?? OPENCODE_EVALUATOR_AGENT;
+  const env = openCodePermissionEnvironment(options.env ?? process.env);
+  let runtime;
+  let help;
+  let agents;
+  try {
+    runtime = run(executable, ["--version"], {
+      cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+    }).trim();
+  } catch (error) {
+    return preflightFailure("opencode_host_unavailable", (error.stderr || error.message).toString().trim());
+  }
+  try {
+    if (options.execFileSync) {
+      help = run(executable, ["run", "--help"], {
+        cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+      });
+    } else {
+      const helpProbe = (options.spawnSync ?? spawnSync)(executable, ["run", "--help"], {
+        cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+      });
+      if (helpProbe.error || helpProbe.status !== 0) throw helpProbe.error ?? new Error(helpProbe.stderr || "OpenCode run help failed.");
+      help = `${helpProbe.stdout ?? ""}\n${helpProbe.stderr ?? ""}`;
+    }
+  } catch (error) {
+    return preflightFailure("opencode_run_unavailable", (error.stderr || error.message).toString().trim(), [`opencode ${runtime}`]);
+  }
+  const requiredFlags = ["--pure", "--agent", "--format", "--dir"];
+  const missingFlags = requiredFlags.filter((flag) => !help.includes(flag));
+  if (missingFlags.length) {
+    return preflightFailure("opencode_run_capability_missing", `Missing required flags: ${missingFlags.join(", ")}`, [`opencode ${runtime}`]);
+  }
+  try {
+    agents = run(executable, ["agent", "list", "--pure"], {
+      cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10000,
+    });
+  } catch (error) {
+    return preflightFailure("opencode_agent_probe_failed", (error.stderr || error.message).toString().trim(), [`opencode ${runtime}`]);
+  }
+  let projection;
+  try {
+    projection = extractAgentPermissions(agents, agentName);
+  } catch (error) {
+    return preflightFailure("opencode_agent_permissions_unparseable", error.message, [`opencode ${runtime}`]);
+  }
+  if (!projection) {
+    return preflightFailure("opencode_evaluator_agent_missing", `OpenCode agent ${agentName} is not available.`, [`opencode ${runtime}`]);
+  }
+  if (projection.mode !== "primary") {
+    return preflightFailure("opencode_evaluator_agent_incompatible", `OpenCode agent ${agentName} must be primary for opencode run --agent; observed ${projection.mode || "unknown"}.`, [
+      `opencode ${runtime}`,
+      `agent:${agentName}`,
+    ]);
+  }
+  const unsafe = executablePermissions.filter((permission) => terminalPermissionDecision(projection.permissions, permission) !== "deny");
+  if (unsafe.length) {
+    return preflightFailure("opencode_evaluator_permissions_unsafe", `Terminal deny is not effective for: ${unsafe.join(", ")}`, [
+      `opencode ${runtime}`,
+      `agent:${agentName}`,
+    ]);
+  }
+  return {
+    surface: "opencode",
+    status: "passed",
+    code: "opencode_evaluator_ready",
+    invocation_id: `${process.pid}-${Date.now()}`,
+    runtime,
+    agent: agentName,
+    evidence: [
+      `opencode ${runtime}`,
+      "opencode run --pure --agent agdf-evaluator --format json",
+      "effective executable permissions terminal-deny",
+    ],
+    env,
+  };
+}
+
+export function parseOpenCodeEvaluatorOutput(raw) {
+  const text = [];
+  for (const line of raw.split(/\r?\n/).filter(Boolean)) {
+    const event = JSON.parse(line);
+    if (event?.type === "error") {
+      const status = event.error?.data?.statusCode;
+      const detail = event.error?.data?.message || event.error?.message || "unknown OpenCode evaluator error";
+      const error = new Error(`OpenCode evaluator error${status ? ` (${status})` : ""}: ${detail}`);
+      error.code = status === 401 || /auth|credential|provider available/i.test(detail)
+        ? "OPENCODE_EVALUATOR_AUTHENTICATION_FAILED"
+        : "OPENCODE_EVALUATOR_UNAVAILABLE";
+      throw error;
+    }
+    if (event?.part?.type === "text" && typeof event.part.text === "string") text.push(event.part.text);
+    else if (event?.type === "text" && typeof event.text === "string") text.push(event.text);
+  }
+  if (!text.length) throw new Error("OpenCode evaluator returned no text event.");
+  if (text.length !== 1) throw new Error(`OpenCode evaluator returned ${text.length} text events; exactly one final payload is required.`);
+  return JSON.parse(text[0]);
+}
+
+function fatalEvaluatorError(error) {
+  const wrapped = new Error(error.message);
+  wrapped.code = typeof error.code === "string" && error.code.startsWith("OPENCODE_EVALUATOR_")
+    ? error.code
+    : error.code === "GENERATOR_MUTATION_DETECTED"
+    ? "OPENCODE_EVALUATOR_MUTATION_DETECTED"
+    : error.code === "GENERATOR_TIMEOUT"
+      ? "OPENCODE_EVALUATOR_TIMEOUT"
+      : error.code === "ENOENT"
+        ? "OPENCODE_EVALUATOR_UNAVAILABLE"
+        : /auth|unauthorized|credential/i.test(`${error.message}\n${error.stderr ?? ""}`)
+          ? "OPENCODE_EVALUATOR_AUTHENTICATION_FAILED"
+          : "OPENCODE_EVALUATOR_OUTPUT_INVALID";
+  wrapped.fatalEvaluator = true;
+  return wrapped;
+}
+
+export function openCodeEvaluator(options = {}) {
+  if (options.preflight?.status !== "passed" || options.preflight.surface !== "opencode") {
+    throw new Error("OpenCode evaluator requires a successful current-invocation preflight.");
+  }
+  const executable = options.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
+  const agentName = options.preflight.agent ?? OPENCODE_EVALUATOR_AGENT;
+  return {
+    name: "opencode",
+    metadata: {
+      name: "opencode",
+      runtime: options.preflight.runtime,
+      agent: agentName,
+      preflight: options.preflight.code,
+    },
+    async evaluate(input, candidate) {
+      const args = [
+        "run", "--pure", "--agent", agentName, "--format", "json", "--dir", options.cwd,
+      ];
+      if (options.model) args.push("--model", options.model);
+      args.push(buildEvaluatorPrompt(input, candidate));
+      try {
+        const raw = guardedExecFileSync(executable, args, {
+          cwd: options.cwd,
+          env: options.preflight.env,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          timeout: options.timeoutMs ?? 120000,
+        });
+        return validateEvaluation(parseOpenCodeEvaluatorOutput(raw), candidate.id);
+      } catch (error) {
+        throw fatalEvaluatorError(error);
+      }
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/prompt.js

@@ -0,0 +1,13 @@
+export function buildEvaluatorPrompt(input, candidate) {
+  return [
+    "You are an evaluation-only component. Do not use tools, execute commands, inspect files, delegate work or modify state.",
+    `Return only one JSON object matching contract version ${input.contract_version}.`,
+    `Objective: ${input.objective}`,
+    `Current gate: ${input.current_gate}`,
+    `Candidate id: ${candidate.id}`,
+    `Candidate action: ${candidate.action}`,
+    "Score scope_fit, gate_readiness, risk_reduction, evidence_gain, testability, reversibility and cost from 0 to 5.",
+    "Cost 0 is low and 5 is high. uncertainty is 0 low to 5 high.",
+    "Keep rationale concise. child_actions must only contain actions permitted by the current gate.",
+  ].join("\n");
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/protocol.js

@@ -0,0 +1,13 @@
+import { validateEvaluation } from "../contracts.js";
+
+export function fixtureEvaluator(evaluations) {
+  return {
+    name: "fixture",
+    metadata: { name: "fixture", runtime: "deterministic-test" },
+    async evaluate(_input, candidate) {
+      const value = evaluations[candidate.id];
+      if (!value) throw new Error(`missing fixture evaluation for ${candidate.id}`);
+      return validateEvaluation(value, candidate.id);
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/claude.js

@@ -0,0 +1,40 @@
+import { execFileSync } from "node:child_process";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function claudeGenerator(options = {}) {
+  const claudeBin = options.claudeBin ?? "claude";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "claude version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "claude",
+    metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const prompt = [
+        "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+        "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+        `Normalized request: ${JSON.stringify(request)}`,
+      ].join("\n");
+      const args = ["-p", "--disallowedTools", "Edit,Write,Bash", "--output-format", "json", "--json-schema", JSON.stringify(generatorOutputSchema())];
+      if (options.model) args.push("--model", options.model);
+      args.push(prompt);
+      let raw;
+      try {
+        raw = execute(claudeBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+      } catch (error) {
+        const providerOutput = String(error?.stdout ?? "");
+        if (/not logged in|unauthorized|authentication/i.test(providerOutput)) {
+          const authentication = new Error("claude generator authentication failed");
+          authentication.code = "GENERATOR_AUTHENTICATION_FAILED";
+          throw authentication;
+        }
+        throw error;
+      }
+      const response = JSON.parse(raw);
+      if (response.is_error) throw new Error(`claude generator returned an error: ${response.result ?? "unknown error"}`);
+      return validateGeneratorResponse(JSON.parse(response.result));
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/codex.js

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { guardedExecFileSync } from "../transports/read-only-guard.js";
+
+export function codexGenerator(options = {}) {
+  const codexBin = options.codexBin ?? "codex";
+  const execute = options.execute ?? guardedExecFileSync;
+  let runtime = options.runtime ?? "codex version unavailable";
+  if (!options.runtime) try { runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  return {
+    name: "codex",
+    metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },
+    async generate(requestValue) {
+      const request = validateGeneratorRequest(requestValue);
+      const temp = mkdtempSync(join(tmpdir(), "agdf-dps-generator-"));
+      const schemaPath = join(temp, "schema.json");
+      const outputPath = join(temp, "output.json");
+      try {
+        writeFileSync(schemaPath, `${JSON.stringify(generatorOutputSchema(), null, 2)}\n`, "utf8");
+        const prompt = [
+          "Generate bounded advisory delivery-path proposals. Do not use tools, execute commands, or modify files.",
+          "Return only JSON matching the supplied schema. Do not include hidden reasoning.",
+          `Normalized request: ${JSON.stringify(request)}`,
+        ].join("\n");
+        const args = ["exec", "--sandbox", "read-only", "--ephemeral", "--ignore-user-config", "--output-schema", schemaPath, "--output-last-message", outputPath, "--color", "never"];
+        if (options.model) args.push("--model", options.model);
+        args.push(prompt);
+        execute(codexBin, args, { cwd: options.cwd, timeout: options.timeoutMs ?? request.budgets.max_duration_ms });
+        return validateGeneratorResponse(JSON.parse(readFileSync(outputPath, "utf8")));
+      } finally {
+        rmSync(temp, { recursive: true, force: true });
+      }
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/protocol.js

@@ -0,0 +1,12 @@
+import { validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+
+export function fixtureGenerator(response, metadata = { name: "fixture-generator" }) {
+  return {
+    name: metadata.name,
+    metadata,
+    async generate(request) {
+      validateGeneratorRequest(request);
+      return validateGeneratorResponse(response);
+    },
+  };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/persistence.js

@@ -0,0 +1,39 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function safeResult(result) {
+  return JSON.parse(JSON.stringify(result, (key, value) => {
+    if (/(prompt|hidden_reasoning|secret|credential|source_snapshot)/i.test(key)) return undefined;
+    return value;
+  }));
+}
+
+export function persistSearchResult(targetDir, result) {
+  const root = join(targetDir, ".agdf", "control", "artefacts", result.scope_key);
+  const jsonPath = join(root, "DELIVERY_PATH_SEARCH.json");
+  const markdownPath = join(root, "DELIVERY_PATH_SEARCH.md");
+  mkdirSync(dirname(jsonPath), { recursive: true });
+  const safe = safeResult(result);
+  writeFileSync(jsonPath, `${JSON.stringify(safe, null, 2)}\n`, "utf8");
+  const recommendation = safe.recommendation?.action ?? "No safe recommendation";
+  writeFileSync(markdownPath, [
+    "# Delivery Path Search Decision",
+    "",
+    `- status: ${safe.status}`,
+    `- current_gate: ${safe.current_gate}`,
+    `- enforcement: ${safe.enforcement.level}`,
+    `- recommendation: ${recommendation}`,
+    `- stopping_reason: ${safe.stopping_reason}`,
+    `- evaluations: ${safe.budgets.evaluations}`,
+    `- generation_status: ${safe.generation?.status ?? "legacy_deterministic"}`,
+    `- generated_candidates: ${safe.generation ? `${safe.generation.accepted}/${safe.generation.returned}` : "0/0"}`,
+    `- generation_cost_units: ${safe.generation?.cost_units ?? 0}`,
+    `- generation_duration_ms: ${safe.generation?.duration_ms ?? 0}`,
+    ...(safe.generation?.failure_code ? [`- generation_failure: ${safe.generation.failure_code}`] : []),
+    `- next_gate_action: ${safe.next_gate_action}`,
+    "",
+    "This summary contains model judgements, not measured facts. Canonical AGDF gate-check remains authoritative.",
+    "",
+  ].join("\n"), "utf8");
+  return { jsonPath, markdownPath };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/scoring.js

@@ -0,0 +1,21 @@
+import { SCORING_POLICY_VERSION } from "./contracts.js";
+
+export const DEFAULT_WEIGHTS = Object.freeze({
+  scope_fit: 3,
+  gate_readiness: 3,
+  risk_reduction: 2,
+  evidence_gain: 2,
+  testability: 2,
+  reversibility: 1,
+  cost: -1,
+  uncertainty: -2,
+});
+
+const enforcementPenalty = { full: 0, tool_enforced: 1, instruction_only: 4 };
+
+export function scoreEvaluation(evaluation, enforcementLevel, weights = DEFAULT_WEIGHTS) {
+  const contributions = Object.fromEntries(Object.entries(weights).map(([key, weight]) => [key, evaluation[key] * weight]));
+  const penalty = enforcementPenalty[enforcementLevel] ?? 4;
+  const score = Object.values(contributions).reduce((sum, value) => sum + value, 0) - penalty;
+  return { score, contributions, enforcement_penalty: penalty, scoring_policy_version: SCORING_POLICY_VERSION };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/search-engine.js

@@ -0,0 +1,155 @@
+import { CONTRACT_VERSION, SCORING_POLICY_VERSION, validateEvaluation, validateSearchInput } from "./contracts.js";
+import { candidateLegality, candidatesFromInput, generatedCandidatesFromResponse } from "./candidate-policy.js";
+import { scoreEvaluation } from "./scoring.js";
+import { generatorRequestFromInput } from "./state-adapter.js";
+
+function generatorFailureCode(error) {
+  if (error?.code === "GENERATOR_MUTATION_DETECTED") return "generator_mutation_detected";
+  if (error?.code === "GENERATOR_TIMEOUT") return "generator_timeout";
+  if (error?.code === "GENERATOR_AUTHENTICATION_FAILED") return "generator_authentication_failed";
+  if (error?.code === "ENOENT") return "generator_unavailable";
+  if (/auth/i.test(error?.message ?? "")) return "generator_authentication_failed";
+  if (/context|disallowed/i.test(error?.message ?? "")) return "generator_context_rejected";
+  if (/budget/i.test(error?.message ?? "")) return "generator_budget_exceeded";
+  return "generator_schema_invalid";
+}
+
+export async function runDeliveryPathSearch(inputValue, evaluator, options = {}) {
+  const input = validateSearchInput(inputValue);
+  const startedAt = Date.now();
+  const baseline = [...(options.candidates ?? candidatesFromInput(input))];
+  const queue = [...baseline];
+  const rejected = [];
+  const evaluated = [];
+  let evaluations = 0;
+  let costUnits = 0;
+  let lastLeaderId = null;
+  let stableComparisons = 0;
+  let stoppingReason = "candidate_queue_exhausted";
+  const generation = {
+    status: input.generation?.enabled ? "failed" : "disabled",
+    adapter: options.generator?.metadata ?? null,
+    budgets: input.generation ?? null,
+    returned: 0,
+    accepted: 0,
+    rejected: [],
+    cost_units: 0,
+    duration_ms: 0,
+    failure_code: null,
+  };
+
+  if (input.generation?.enabled) {
+    if (!options.generator) {
+      generation.failure_code = "generator_unavailable";
+    } else {
+      const generationStartedAt = Date.now();
+      try {
+        const response = await options.generator.generate(generatorRequestFromInput(input));
+        const elapsed = Date.now() - generationStartedAt;
+        generation.returned = response.proposals.length;
+        generation.cost_units = response.cost_units;
+        costUnits += response.cost_units;
+        if (elapsed > input.generation.max_duration_ms) {
+          const error = new Error("generator duration budget exceeded");
+          error.code = "GENERATOR_TIMEOUT";
+          throw error;
+        }
+        if (response.cost_units > input.generation.max_cost_units || response.proposals.length > input.generation.max_proposals) {
+          const error = new Error("generator response exceeds configured budget");
+          error.code = "GENERATOR_BUDGET_EXCEEDED";
+          throw error;
+        }
+        const filtered = generatedCandidatesFromResponse(response, input, baseline);
+        generation.accepted = filtered.accepted.length;
+        generation.rejected = filtered.rejected;
+        queue.push(...filtered.accepted.slice(0, input.generation.max_proposals));
+        generation.status = filtered.accepted.length === response.proposals.length ? "success" : "partial";
+        if (!filtered.accepted.length) generation.failure_code = "generator_no_diverse_proposals";
+      } catch (error) {
+        generation.failure_code = generatorFailureCode(error);
+        if (generation.failure_code === "generator_mutation_detected") throw error;
+      } finally {
+        generation.duration_ms = Date.now() - generationStartedAt;
+      }
+    }
+  }
+
+  while (queue.length > 0) {
+    if (evaluations >= input.budgets.max_evaluations) { stoppingReason = "evaluation_budget_exhausted"; break; }
+    if (costUnits >= input.budgets.max_cost_units) { stoppingReason = "cost_budget_exhausted"; break; }
+    if (Date.now() - startedAt >= input.budgets.max_duration_ms) { stoppingReason = "duration_budget_exhausted"; break; }
+    const candidate = queue.shift();
+    const legality = candidateLegality(candidate, input);
+    if (!legality.legal) {
+      rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: legality.reason });
+      continue;
+    }
+
+    try {
+      const evaluation = validateEvaluation(await evaluator.evaluate(input, candidate), candidate.id);
+      evaluations += 1;
+      costUnits += evaluation.cost;
+      const scored = scoreEvaluation(evaluation, input.enforcement.level);
+      evaluated.push({ candidate, evaluation, ...scored });
+      const currentLeader = [...evaluated].sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id))[0];
+      if (currentLeader?.candidate.id === lastLeaderId) stableComparisons += 1;
+      else stableComparisons = 1;
+      lastLeaderId = currentLeader?.candidate.id ?? null;
+      if (evaluated.length > 1 && stableComparisons >= input.budgets.stability_window) {
+        stoppingReason = "stable_leader";
+        break;
+      }
+      if ((candidate.depth ?? 0) + 1 < input.budgets.max_depth) {
+        for (const [index, action] of evaluation.child_actions.slice(0, input.budgets.max_candidates).entries()) {
+          queue.push({
+            id: `${candidate.id}.${index + 1}`,
+            parent_id: candidate.id,
+            depth: (candidate.depth ?? 0) + 1,
+            action,
+            source: "expanded",
+            expected_evidence: [],
+            tests: [],
+            assumptions: evaluation.assumptions,
+          });
+        }
+      }
+    } catch (error) {
+      if (error?.fatalEvaluator === true) throw error;
+      rejected.push({ candidate_id: candidate.id, action: candidate.action, reason: `invalid_evaluation: ${error.message}` });
+    }
+  }
+
+  evaluated.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+  const leader = evaluated[0];
+  if (!leader) stoppingReason = rejected.length ? "no_safe_candidate" : stoppingReason;
+  return {
+    contract_version: CONTRACT_VERSION,
+    scoring_policy_version: SCORING_POLICY_VERSION,
+    scope_key: input.scope_key,
+    current_gate: input.current_gate,
+    status: leader ? "recommendation" : "no_safe_recommendation",
+    recommendation: leader ? {
+      candidate_id: leader.candidate.id,
+      action: leader.candidate.action,
+      score: leader.score,
+      rationale: leader.evaluation.rationale,
+      expected_evidence: leader.candidate.expected_evidence,
+      tests: leader.candidate.tests,
+      risks: leader.evaluation.risks,
+      assumptions: leader.evaluation.assumptions,
+    } : null,
+    alternatives: evaluated.slice(1).map((item) => ({
+      candidate_id: item.candidate.id,
+      action: item.candidate.action,
+      score: item.score,
+      rejection_reason: `ranked_below_${leader?.candidate.id ?? "safety_threshold"}`,
+    })),
+    rejected,
+    enforcement: input.enforcement,
+    evaluator: evaluator.metadata ?? { name: evaluator.name ?? "unknown" },
+    generation,
+    budgets: { configured: input.budgets, evaluations, cost_units: costUnits, stable_comparisons: stableComparisons, duration_ms: Date.now() - startedAt },
+    stopping_reason: stoppingReason,
+    next_gate_action: "Run canonical AGDF gate-check; search does not grant permission.",
+  };
+}