akm-cli 0.9.24 → 0.9.25-alpha.2

package/dist/commands/improve/reflect.js

@@ -11,7 +11,6 @@
  * pre-dispatch refusals still emit both).
  */
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
@@ -31,20 +30,20 @@ import { lookup } from "../../indexer/indexer.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
-import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, REFLECT_CONTENT_CAP, REFLECT_TRUNCATION_MARKER, } from "../../integrations/agent/prompts.js";
-import { runnerIsLlm, runnerSupportsFileWrite } from "../../integrations/agent/runner.js";
-import { assertRunnerCredentials, collectDispatchSensitiveValues, runExecution, } from "../../integrations/agent/runner-dispatch.js";
+import { buildReflectOutputRepairPrompt, buildReflectPrompt, parseAgentProposalPayload, REFLECT_CONTENT_CAP, REFLECT_TRUNCATION_MARKER, } from "../../integrations/agent/prompts.js";
+import { runnerIsLlm } from "../../integrations/agent/runner.js";
+import { assertRunnerCredentials, collectDispatchSensitiveValues, } from "../../integrations/agent/runner-dispatch.js";
 import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 import { deriveLessonRef } from "./distill.js";
 import { findAssetFilePath } from "./eligibility.js";
-import { resolveImproveLlmExecution } from "./execution.js";
+import { resolveImproveExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
-import { classifyReflectChange, splitFrontmatter } from "./reflect-noise.js";
+import { classifyReflectChange, findReflectDefect, splitFrontmatter } from "./reflect-noise.js";
 import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-gate.js";
-import { callStage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
+import { callStageOnce, errMessage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 function readOnlyEventsContext(ctx) {
@@ -83,16 +82,6 @@ export const REFLECT_ALLOWED_TYPES = new Set([
 const REFLECT_REFUSED_TYPES = new Set(["secret"]);
 /** Identity fields the model may never change (a renamed `name` breaks ref resolution). */
 const PROTECTED_FRONTMATTER_FIELDS = new Set(["name", "ref", "id", "slug", "type"]);
-/**
- * A fresh tmp path per iteration for the agent/SDK file-write contract (long
- * bodies are written to a file instead of fenced JSON on stdout). The direct
- * LLM runner has no filesystem and never gets one.
- */
-function synthesizeReflectDraftPath(ref) {
-    const safeRef = (ref ?? "no-ref").replace(/[^a-z0-9_-]/gi, "_");
-    const rand = Math.random().toString(36).slice(2, 8);
-    return path.join(os.tmpdir(), `akm-reflect-${safeRef}-${Date.now()}-${rand}.md`);
-}
 /** Lesson lint findings for the prompt: a concrete starting point for the revision. */
 function buildSchemaHints(type, content) {
     if (!content || type !== "lesson")
@@ -328,7 +317,12 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
         ...(truncationMarkerLeaked ? { truncationMarkerLeaked } : {}),
     };
 }
-// ── Direct-LLM output contract ───────────────────────────────────────────────
+// ── Output contract ──────────────────────────────────────────────────────────
+//
+// Every engine kind is asked for the same reply: the JSON object of
+// REFLECT_JSON_SCHEMA, or the framed-markdown frame for an LLM engine that
+// rejects JSON Schema. The reply is validated by the parse functions below and
+// repaired once, whatever engine produced it.
 const REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA = {
     type: "object",
     required: ["description", "when_to_use"],
@@ -366,7 +360,7 @@ const REFLECT_UNSCOPED_JSON_SCHEMA = {
     },
 };
 /**
- * Frame for JSON Schema unless the connection disabled it or already proved
+ * Frame for JSON Schema unless the LLM connection disabled it or already proved
  * this process that it rejects it (the transport retries plain text on a 4xx).
  */
 function wantsJsonSchemaOutput(connection) {
@@ -379,7 +373,7 @@ function parsedRecord(result) {
         ? result.parsed
         : undefined;
 }
-function reflectLlmTelemetry(result) {
+function reflectTelemetry(result) {
     const parsed = parsedRecord(result);
     if (!parsed || (parsed.outputMode !== "json_schema" && parsed.outputMode !== "framed_markdown"))
         return undefined;
@@ -484,13 +478,17 @@ function parseFramedReflectOutput(raw, targetRef) {
     return { ref, content, confidence, ...(frontmatter ? { frontmatter } : {}) };
 }
 /**
- * One reflect iteration through the direct LLM runner, as an agent-shaped
- * result (errors captured, never thrown except configuration). An unparseable
- * response gets one repair turn within the original deadline.
+ * One reflect iteration on any engine, as an agent-shaped result (errors
+ * captured, never thrown except configuration). Every engine kind is sent the
+ * same request, with the reply's schema as the output schema, and its reply is
+ * held to the same contract: an unparseable reply gets one repair turn within
+ * the original deadline, then fails. A failed agent or SDK dispatch is reported
+ * as it ran, with its exit code and stderr; an LLM call has only its message.
  */
-export async function runReflectViaLlm(opts) {
+export async function runReflectIteration(opts) {
     const start = Date.now();
     let repairAttempts = 0;
+    // Model work is bounded: with no timeout from the caller or the runner, the default.
     const configuredTimeout = Object.hasOwn(opts, "timeoutMs")
         ? (opts.timeoutMs ?? null)
         : Object.hasOwn(opts.runner, "timeoutMs")
@@ -505,7 +503,7 @@ export async function runReflectViaLlm(opts) {
         ? parseSchemaReflectOutput(raw, opts.targetRef)
         : parseFramedReflectOutput(raw, opts.targetRef);
     const failure = (err, reason, stdout = "", exitCode = 1) => {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = errMessage(err);
         return {
             ok: false,
             stdout,
@@ -517,8 +515,13 @@ export async function runReflectViaLlm(opts) {
             parsed: { outputMode: opts.outputMode, repairAttempts },
         };
     };
+    // A reply that broke the contract; its message is the parser's, on every engine kind.
+    const invalidReply = (err, reply) => failure(err, "parse_error", reply, 0);
+    // The result of the dispatch that failed, kept for an agent or SDK engine.
+    let dispatched;
+    // Reflect parses and repairs its own reply (the repair turn below), so one dispatch, unvalidated.
     const call = async (callMessages, repairTimeoutMs) => {
-        const outcome = await callStage({
+        const outcome = await callStageOnce({
             feature: "reflect_proposal",
             runner: opts.runner,
             prompt: callMessages.at(-1)?.content ?? "",
@@ -535,13 +538,18 @@ export async function runReflectViaLlm(opts) {
                 // Visible chain-of-thought can exhaust the output before the envelope.
                 enableThinking: false,
                 ...(opts.chat ? { chat: opts.chat } : {}),
+                ...(opts.runSdk ? { runSdk: opts.runSdk } : {}),
+                ...(opts.runOptions ? { runOptions: opts.runOptions } : {}),
             },
+            ...(opts.environment ? { current: { environment: opts.environment } } : {}),
             ...(opts.onNotices ? { onNotices: opts.onNotices } : {}),
         });
         if (!outcome.ok) {
+            if (!runnerIsLlm(opts.runner))
+                dispatched = outcome.result;
             throw outcome.reason === "timeout"
                 ? new LlmCallError(outcome.error ?? "timeout", "timeout")
-                : new Error(outcome.error ?? "LLM call failed");
+                : new Error(outcome.error ?? "dispatch failed");
         }
         return outcome.raw;
     };
@@ -556,7 +564,7 @@ export async function runReflectViaLlm(opts) {
         }
         catch (err) {
             if (opts.allowRepair === false)
-                return failure(err, "parse_error", stdout, 0);
+                return invalidReply(err, stdout);
             if (opts.signal?.aborted)
                 return failure(new Error("Reflect request aborted"), "aborted", stdout);
             const remaining = deadline === undefined ? undefined : deadline - Date.now();
@@ -570,7 +578,7 @@ export async function runReflectViaLlm(opts) {
                 payload = parse(acceptedOutput);
             }
             catch (repairErr) {
-                return failure(repairErr, "parse_error", acceptedOutput, 0);
+                return invalidReply(repairErr, acceptedOutput);
             }
         }
         return {
@@ -585,6 +593,8 @@ export async function runReflectViaLlm(opts) {
     catch (err) {
         if (err instanceof ConfigError)
             throw err;
+        if (dispatched)
+            return { ...dispatched, parsed: { outputMode: opts.outputMode, repairAttempts } };
         const reason = opts.signal?.aborted
             ? "aborted"
             : err instanceof LlmCallError && err.code === "timeout"
@@ -685,8 +695,9 @@ async function resolveReflectSource(options, stash, emitFailed) {
 }
 /**
  * The single engine for this invocation: `--engine`, the improve strategy's
- * LLM-only reflect process, or `defaults.engine` (announced when it falls back
- * to the SDK binary). Unattended improve refuses a tool-capable engine.
+ * reflect process, or `defaults.engine` (announced when it falls back to the
+ * SDK binary). Whatever its kind, reflect runs it under the model-work tool
+ * policy.
  */
 function resolveReflectRunner(options) {
     const config = options.config ?? loadConfig();
@@ -700,14 +711,14 @@ function resolveReflectRunner(options) {
         lowered = lower({ content: "reflect engine selection", config, current: { engine: options.engine } });
     }
     else if (options.improveProfile) {
-        const resolved = resolveImproveLlmExecution({
+        const resolved = resolveImproveExecution({
             config,
             profile: activeStrategy,
             process: activeStrategy?.processes?.reflect,
             processName: "reflect",
         });
         if (!resolved) {
-            throw new ConfigError("Reflect requires an LLM engine for the active improve strategy.", "LLM_NOT_CONFIGURED", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine.");
+            throw new ConfigError("Reflect requires an engine for the active improve strategy.", "LLM_NOT_CONFIGURED", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine.");
         }
         lowered = resolved;
     }
@@ -723,19 +734,20 @@ function resolveReflectRunner(options) {
         lowered = lower({ content: "reflect engine selection", config });
     }
     const runnerSpec = lowered.runner;
-    if (options.eventSource === "improve" && !runnerIsLlm(runnerSpec)) {
-        throw new ConfigError(`Unattended improve requires an LLM engine for reflect; engine "${runnerSpec.engine ?? options.engine ?? "unknown"}" is tool-capable.`, "INVALID_CONFIG_FILE", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine to an LLM engine.");
-    }
     const engineName = runnerSpec.engine ?? options.engine;
     if (!engineName)
         throw new ConfigError("Reflect requires a named engine.", "INVALID_CONFIG_FILE");
     return { config, activeStrategy, runnerSpec, engineName, notices: lowered.notices };
 }
-/** Lower a runner and check its credentials, so a bad transport fails before any work. */
+/**
+ * Lower a runner under the model-work tool policy and check its credentials,
+ * so a bad transport, or one that cannot confine the policy, fails before any work.
+ */
 function preflightReflectDispatch(runnerSpec, onNotices) {
     const prepared = resolveExecution({
         content: "Validate reflect operation transport before dispatch.",
         runner: runnerSpec,
+        modelWork: true,
     });
     const lowered = buildExecution(prepared.request, prepared.runner);
     onNotices(lowered.notices);
@@ -767,13 +779,10 @@ async function gatherReflectPromptSources(options, stash, parsedRef, assetConten
 }
 /** The exact prompt reflect sends, shared by dispatch and `--show-prompt`. */
 function buildReflectPromptText(args) {
-    const { options, parsedRef, assetContent, sources, runnerSpec, draftFilePath, priorDraft } = args;
+    const { options, parsedRef, assetContent, sources, runnerSpec, priorDraft } = args;
     const { feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext } = sources;
-    const outputMode = runnerIsLlm(runnerSpec)
-        ? wantsJsonSchemaOutput(runnerSpec.connection)
-            ? "json_schema"
-            : "framed_markdown"
-        : undefined;
+    // An LLM engine that rejects JSON Schema gets the framed contract; every other engine gets the JSON object.
+    const outputMode = runnerIsLlm(runnerSpec) && !wantsJsonSchemaOutput(runnerSpec.connection) ? "framed_markdown" : "json_schema";
     const input = {
         ...(options.ref ? { ref: options.ref } : {}),
         ...(parsedRef?.type ? { type: parsedRef.type } : {}),
@@ -787,89 +796,65 @@ function buildReflectPromptText(args) {
         ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
         ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
         ...(priorDraft !== undefined ? { priorDraft } : {}),
-        ...(draftFilePath ? { draftFilePath } : {}),
-        ...(outputMode ? { outputMode } : {}),
+        outputMode,
     };
     const contentBudgetChars = computeReflectContentBudgetChars(input, runnerSpec);
     const { prompt } = buildReflectPrompt({
         ...input,
         ...(contentBudgetChars !== undefined ? { contentBudgetChars } : {}),
     });
-    return { prompt, ...(outputMode ? { outputMode } : {}) };
+    return { prompt, outputMode };
 }
 /**
  * Dispatch with the optional self-refine loop: up to `maxRefineIters` passes,
- * each critiquing the prior draft, stopping early on an unchanged draft. The
- * direct-LLM repair budget is shared across passes.
+ * each critiquing the prior draft, stopping early on an unchanged draft. Every
+ * engine kind runs the same iteration, and the repair budget is shared across
+ * passes. Under the model-work tool policy an agent can edit only its own
+ * scratch directory, which is gone once it returns, so it returns the proposal
+ * as its reply, as an LLM does.
  */
 async function runReflectRefineIterations(args) {
-    const { run, parsedRef, assetContent, sources, agentEnv, draftPaths } = args;
+    const { run, parsedRef, assetContent, sources, agentEnv } = args;
     const { options, runnerSpec } = run;
     const maxRefineIters = Math.max(1, options.maxRefineIters ?? 1);
-    const canWriteFile = runnerSupportsFileWrite(runnerSpec);
     let result = {};
     let priorDraft;
-    let lastDraftPath;
     let repairAttempts = 0;
+    // Only an agent or SDK engine runs a child process, with an environment and spawn or SDK seams.
+    const childProcess = runnerIsLlm(runnerSpec)
+        ? {}
+        : {
+            ...(Object.keys(agentEnv).length > 0 ? { environment: agentEnv } : {}),
+            ...(options.runSdk ? { runSdk: options.runSdk } : {}),
+            ...(options.runAgentOptions ? { runOptions: options.runAgentOptions } : {}),
+        };
     for (let iter = 0; iter < maxRefineIters; iter++) {
-        const draftFilePath = canWriteFile ? synthesizeReflectDraftPath(options.ref) : undefined;
-        if (draftFilePath) {
-            draftPaths.push(draftFilePath);
-            lastDraftPath = draftFilePath;
-        }
         const { prompt, outputMode } = buildReflectPromptText({
             options,
             parsedRef,
             assetContent,
             sources,
             runnerSpec,
-            draftFilePath,
             priorDraft,
         });
-        let iterResult;
-        if (runnerIsLlm(runnerSpec)) {
-            iterResult = await runReflectViaLlm({
-                prompt,
-                runner: runnerSpec,
-                ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
-                ...(options.signal ? { signal: options.signal } : {}),
-                priorDraft,
-                iteration: iter,
-                ...(outputMode === "json_schema"
-                    ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
-                    : {}),
-                outputMode: outputMode ?? "framed_markdown",
-                ...(options.ref ? { targetRef: options.ref } : {}),
-                allowRepair: repairAttempts === 0,
-                ...(options.chat ? { chat: options.chat } : {}),
-                onNotices: run.notices.add,
-            });
-        }
-        else {
-            const conversation = priorDraft !== undefined && iter > 0
-                ? [
-                    { role: "user", content: prompt },
-                    { role: "assistant", content: priorDraft },
-                ]
-                : undefined;
-            const current = {
-                ...(Object.hasOwn(options, "timeoutMs") ? { timeout: options.timeoutMs } : {}),
-                ...(Object.keys(agentEnv).length > 0 ? { environment: agentEnv } : {}),
-            };
-            const prepared = resolveExecution({
-                content: conversation ? REFLECT_CRITIQUE_PROMPT : prompt,
-                ...(conversation ? { conversation } : {}),
-                runner: runnerSpec,
-                ...(Object.keys(current).length > 0 ? { current } : {}),
-            });
-            const lowered = buildExecution(prepared.request, prepared.runner);
-            run.notices.add(lowered.notices);
-            iterResult = await runExecution(lowered, {
-                ...(options.runSdk ? { runSdk: options.runSdk } : {}),
-                runOptions: { ...(options.signal ? { signal: options.signal } : {}), ...(options.runAgentOptions ?? {}) },
-            });
-        }
-        const telemetry = reflectLlmTelemetry(iterResult);
+        const iterResult = await runReflectIteration({
+            prompt,
+            runner: runnerSpec,
+            ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+            priorDraft,
+            iteration: iter,
+            ...(outputMode === "json_schema"
+                ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
+                : {}),
+            outputMode,
+            ...(options.ref ? { targetRef: options.ref } : {}),
+            allowRepair: repairAttempts === 0,
+            ...(options.chat ? { chat: options.chat } : {}),
+            ...childProcess,
+            onNotices: run.notices.add,
+        });
+        const telemetry = reflectTelemetry(iterResult);
         if (telemetry)
             repairAttempts += telemetry.repairAttempts;
         result = telemetry
@@ -878,47 +863,25 @@ async function runReflectRefineIterations(args) {
         if (!result.ok)
             break;
         if (iter < maxRefineIters - 1) {
-            const priorFromLlm = parsedRecord(result)?.priorDraft;
-            const nextDraft = typeof priorFromLlm === "string" ? priorFromLlm : (result.stdout ?? "");
+            const priorFromReply = parsedRecord(result)?.priorDraft;
+            const nextDraft = typeof priorFromReply === "string" ? priorFromReply : (result.stdout ?? "");
             if (priorDraft !== undefined && nextDraft === priorDraft)
                 break;
             priorDraft = nextDraft;
         }
     }
-    return { result, lastDraftPath };
+    return result;
 }
-/**
- * The proposal payload from a successful run: the agent's draft file
- * (file-write contract, `DRAFT_WRITTEN confidence=<n>` on stdout) or the JSON
- * payload on stdout.
- */
-function resolveReflectPayload(run, result, lastDraftPath, sensitiveValues) {
+/** The proposal payload from a successful run: the JSON payload on stdout. */
+function resolveReflectPayload(run, result) {
     const { options } = run;
-    const draftFileExists = lastDraftPath !== undefined && fs.existsSync(lastDraftPath) && fs.statSync(lastDraftPath).size > 0;
-    const draftSignaled = /\bDRAFT_WRITTEN\b/.test(result.stdout ?? "");
-    if (draftSignaled && lastDraftPath && !draftFileExists) {
-        run.emitFailed("parse_error", "draft_missing", options.ref, exitCodeMeta(result));
-        return {
-            failure: reflectFailure(run, result, "parse_error", `Agent emitted DRAFT_WRITTEN but draft file is missing or empty (${lastDraftPath}). The file-write contract failed; either the agent's file tools are broken or the path was unwritable.`, true),
-        };
-    }
-    if (draftFileExists && lastDraftPath) {
-        const draftConfidence = extractDraftConfidence(result.stdout);
-        return {
-            payload: {
-                ref: options.ref ?? "",
-                content: redactSensitiveText(fs.readFileSync(lastDraftPath, "utf8"), sensitiveValues),
-                ...(draftConfidence !== undefined ? { confidence: draftConfidence } : {}),
-            },
-        };
-    }
     try {
         return { payload: parseAgentProposalPayload(result.stdout ?? "") };
     }
     catch (err) {
         run.emitFailed("parse_error", "parse_error", options.ref, {
             ...exitCodeMeta(result),
-            ...(reflectLlmTelemetry(result) ?? {}),
+            ...(reflectTelemetry(result) ?? {}),
         });
         return {
             failure: reflectFailure(run, result, "parse_error", err instanceof Error ? err.message : String(err), true),
@@ -935,12 +898,13 @@ const NOISE_SUBREASONS = {
  * exact content that would be persisted, then mint. A judge pass is staged only
  * when the body is unchanged: a body edit the judge passes, or one made with the
  * gate off, waits for review. Size-flagged or truncation-leaking content skips
- * the judge and waits for review.
+ * the judge and waits for review. A revision with a deterministic defect is
+ * refused before the judge runs, whether or not the gate is on.
  */
 async function finalizeReflectProposal(args) {
     const { run, assetContent, result, judge, feedback } = args;
     const { options } = run;
-    const telemetry = reflectLlmTelemetry(result) ?? {};
+    const telemetry = reflectTelemetry(result) ?? {};
     const sanitized = sanitizeReflectPayload({ content: args.payload.content, ...(args.payload.frontmatter ? { frontmatter: args.payload.frontmatter } : {}) }, assetContent, args.payload.ref);
     const payload = {
         ...args.payload,
@@ -981,11 +945,16 @@ async function finalizeReflectProposal(args) {
         }, options.eventsCtx);
         return reflectFailure(run, result, "quality_rejected", message, false);
     };
+    // A defect no judge needs to weigh is refused before any judge call, whether or not the gate is on.
+    const defect = assetContent === undefined ? undefined : findReflectDefect(assetContent, payload.content, options.defectFilter);
+    if (defect)
+        return refuse(defect, { reflectDefect: defect }, `Reflect proposal refused before the judge: ${defect}`);
     let verdict;
     let judgeFailed = false;
     if (judged) {
         verdict = await runReflectQualityJudge(run.config, payload.content, assetContent ?? "", feedback, options.chat, {
             runnerSelectionFrozen: true,
+            ref: payload.ref,
             ...(judge.runner ? { llmRunner: judge.runner } : {}),
             ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.signal ? { signal: options.signal } : {}),
@@ -1114,8 +1083,6 @@ export async function renderReflectPromptPreview(options) {
         assetContent: source.assetContent,
         sources,
         runnerSpec,
-        // The same tmp-path shape a dispatch would use; never written.
-        draftFilePath: runnerSupportsFileWrite(runnerSpec) ? synthesizeReflectDraftPath(ref) : undefined,
         priorDraft: undefined,
     });
     return { ref, prompt, engine: engineName, engineKind: runnerSpec.kind };
@@ -1143,7 +1110,7 @@ export async function akmReflect(options = {}) {
             judgeRunner = runnerSpec;
         }
         else {
-            const resolved = resolveImproveLlmExecution({ config, processName: "reflect_proposal_quality-judge" });
+            const resolved = resolveImproveExecution({ config, processName: "reflect_proposal_quality-judge" });
             if (resolved)
                 notices.add(resolved.notices);
             judgeRunner = resolved?.runner;
@@ -1151,7 +1118,7 @@ export async function akmReflect(options = {}) {
     }
     const skippedNoJudge = judgeWanted && !judgeRunner;
     if (skippedNoJudge) {
-        warnOnce("reflect-quality-gate-no-judge", "Reflect proposal quality gate has no LLM configured to judge proposals (set defaults.llmEngine). Skipping the gate for this run; the proposal is queued for human review instead.");
+        warnOnce("reflect-quality-gate-no-judge", "Reflect proposal quality gate has no engine configured to judge proposals (set defaults.llmEngine). Skipping the gate for this run; the proposal is queued for human review instead.");
     }
     preflightReflectDispatch(runnerSpec, notices.add);
     if (judgeRunner && judgeRunner !== runnerSpec)
@@ -1162,13 +1129,11 @@ export async function akmReflect(options = {}) {
         ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
         ...(options.runAgentOptions ?? {}),
     });
-    const draftPaths = [];
     let result;
     let payload;
     try {
-        const iterated = await runReflectRefineIterations({ run, parsedRef, assetContent, sources, agentEnv, draftPaths });
+        result = await runReflectRefineIterations({ run, parsedRef, assetContent, sources, agentEnv });
         emitInvoked();
-        result = iterated.result;
         if (!result.ok) {
             if (isEnoentFailure(result)) {
                 emitFailed("spawn_failed", "enoent", options.ref, {
@@ -1191,11 +1156,11 @@ export async function akmReflect(options = {}) {
             };
             emitFailed(envelope.reason, envelope.reason === "parse_error" ? "parse_error" : "agent_crash", options.ref, {
                 ...(envelope.exitCode !== null ? { exitCode: envelope.exitCode } : {}),
-                ...(reflectLlmTelemetry(result) ?? {}),
+                ...(reflectTelemetry(result) ?? {}),
             });
             return { ...envelope, ...notices.fields() };
         }
-        const resolved = resolveReflectPayload(run, result, iterated.lastDraftPath, sensitiveValues);
+        const resolved = resolveReflectPayload(run, result);
         if ("failure" in resolved)
             return resolved.failure;
         payload = resolved.payload;
@@ -1205,43 +1170,11 @@ export async function akmReflect(options = {}) {
             emitInvoked();
         throw error;
     }
-    finally {
-        for (const draftPath of draftPaths) {
-            try {
-                if (fs.existsSync(draftPath))
-                    fs.unlinkSync(draftPath);
-            }
-            catch {
-                // best-effort
-            }
-        }
-    }
     const unsafeContent = generatedContentRejection(payload.content, redactSensitiveText(payload.content, sensitiveValues));
     if (unsafeContent) {
         emitFailed("parse_error", "parse_error", options.ref, exitCodeMeta(result));
         return reflectFailure(run, result, "parse_error", unsafeContent, false);
     }
-    // A retargeted proposal is refused (malformed refs are left to proposal validation).
-    if (options.ref) {
-        let retargeted = false;
-        try {
-            const expected = parseRefInput(options.ref);
-            const actual = parseRefInput(payload.ref);
-            retargeted = expected.type !== actual.type || expected.name !== actual.name;
-        }
-        catch {
-            retargeted = false;
-        }
-        if (retargeted) {
-            emitFailed("parse_error", "ref_mismatch", options.ref, {
-                expectedRef: options.ref,
-                actualRef: payload.ref,
-                ...exitCodeMeta(result),
-                ...(reflectLlmTelemetry(result) ?? {}),
-            });
-            return reflectFailure(run, result, "parse_error", `Agent retargeted proposal: expected ref "${options.ref}" but got "${payload.ref}". Proposal rejected to prevent silent ref hallucination.`, true);
-        }
-    }
     return finalizeReflectProposal({
         run,
         payload,

package/dist/commands/improve/retrieval-gate.js

@@ -32,6 +32,10 @@ const GRADE_SCHEMA = {
     additionalProperties: false,
     properties: { grade: { type: "integer", minimum: 0, maximum: 3 }, reason: { type: "string" } },
 };
+function parseGrade(raw) {
+    const grade = parseEmbeddedJsonResponse(raw)?.grade;
+    return typeof grade === "number" && Number.isInteger(grade) && grade >= 0 && grade <= 3 ? grade : undefined;
+}
 /** Up to five distinct task queries, in the given order, whitespace collapsed. */
 export function usableRetrievalQueries(raw) {
     const out = [];
@@ -100,10 +104,11 @@ export async function runRetrievalRegressionGate(args) {
                     ...(args.signal ? { signal: args.signal } : {}),
                     ...(args.chat ? { chat: args.chat } : {}),
                 },
+                parse: parseGrade,
                 ...(args.onNotices ? { onNotices: args.onNotices } : {}),
             });
-            const grade = outcome.ok ? parseEmbeddedJsonResponse(outcome.raw)?.grade : undefined;
-            if (typeof grade !== "number" || !Number.isInteger(grade) || grade < 0 || grade > 3) {
+            const grade = outcome.ok ? parseGrade(outcome.raw) : undefined;
+            if (grade === undefined) {
                 return {
                     pass: false,
                     queries: args.queries.length,