akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/commands/improve/extract.js

@@ -17,6 +17,7 @@ import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { resolveStashDir, timestampForFilename } from "../../core/common.js";
 import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
+import { SHIPPED_ALIAS } from "../../core/config/model-aliases.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
@@ -25,14 +26,14 @@ import { redactErrorBody } from "../../core/redaction.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { resolveTypeConventions, typeConventionRef } from "../../core/standards/resolve-type-conventions.js";
 import { getStateDbPath, openStateDatabase } from "../../core/state-db.js";
-import { runStructured } from "../../core/structured.js";
 import { repairTruncatedDescription } from "../../core/text-truncation.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { warn, warnVerbose } from "../../core/warn.js";
+import { noticeSet } from "../../execution/notices.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
-import { assertRunnerCredentials } from "../../integrations/agent/runner-dispatch.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
+import { isRefused } from "../../llm/structured.js";
 import { getExtractedSessionsMap, getLastExtractRunAt, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../storage/repositories/extract-sessions-repository.js";
 import { listImproveLedgerRows } from "../../storage/repositories/improve-ledger-repository.js";
 import { getStateProposal } from "../../storage/repositories/proposals-repository.js";
@@ -43,7 +44,7 @@ import { buildExtractPrompt, EXTRACT_JSON_SCHEMA, parseExtractPayload, } from ".
 import { cloneAndFreeze, resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { isLedgerBlocked, ledgerKey, readLedgerDb } from "./ledger.js";
 import { buildSessionSummaryPrompt, parseSessionSummary, SESSION_SUMMARY_JSON_SCHEMA, sessionMeetsDurationGate, writeSessionAsset, } from "./session-asset.js";
-import { callStage, callStageOnce, mintProposal, noticeSet } from "./stage.js";
+import { callStage, callStageLoop, mintProposal } from "./stage.js";
 /** Minimum session duration (minutes) for writing a session asset. */
 const DEFAULT_MIN_SESSION_DURATION_MINUTES = 5;
 /** Raw session size (chars) below which the LLM call is skipped; only truly empty sessions are safe to skip. */
@@ -114,33 +115,31 @@ function acquireExtractSessionLock(lockPath) {
 }
 /** Resolve standalone extract selection once, before discovery, auto iteration or watch startup. */
 export function resolveStandaloneExtractPlan(config, selection) {
-    if (selection.engine && selection.strategy) {
-        throw new UsageError("--engine and --strategy are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
-    }
     const selected = resolveImproveStrategy(selection.strategy, config);
     const process = cloneAndFreeze(getImproveProcessConfig("extract", selected.config) ?? {});
     const resolved = resolveImproveExecution({
         config,
-        profile: selected.config,
-        process,
         current: {
+            ...(selection.connection ? { connection: selection.connection } : {}),
+            ...(selection.harness ? { harness: selection.harness } : {}),
             ...(selection.engine ? { engine: selection.engine } : {}),
+            ...(selection.model ? { model: selection.model } : {}),
             ...(Object.hasOwn(selection, "timeoutMs") ? { timeoutMs: selection.timeoutMs ?? null } : {}),
         },
         processName: "extract",
+        alias: SHIPPED_ALIAS.extract,
     });
     if (!resolved) {
-        throw new ConfigError("No engine configured for extract. Set defaults.llmEngine, pass --engine, or select an improve strategy with processes.extract.engine.", "LLM_NOT_CONFIGURED");
+        throw new ConfigError("No connection or harness is configured for extract. Run `akm setup`, pass --connection or --harness, or set improve.connection or improve.processes.extract.connection.", "LLM_NOT_CONFIGURED");
     }
     const runner = resolved.runner;
     return Object.freeze({
         strategy: selected.name,
-        engine: runner.engine,
+        engine: runner.name,
         // An explicit `akm extract` runs regardless of the strategy's improve-stage toggle.
         enabled: true,
         process,
         runner: cloneAndFreeze(runner),
-        timeoutMs: Object.hasOwn(runner, "timeoutMs") ? (runner.timeoutMs ?? null) : 600_000,
         embeddingConfig: cloneAndFreeze(config.embedding),
         ...(resolved.notices.length > 0 ? { notices: cloneAndFreeze(resolved.notices) } : {}),
     });
@@ -168,7 +167,7 @@ function emptyExtractResult(args) {
         sessions: [],
         warnings: [args.warning],
         durationMs: Date.now() - args.startMs,
-        ...(args.llmRunner ? { engine: args.llmRunner.engine, engineKind: args.llmRunner.kind } : {}),
+        ...(args.llmRunner ? { engine: args.llmRunner.name, engineKind: args.llmRunner.kind } : {}),
     };
 }
 /**
@@ -274,11 +273,11 @@ function sessionTriagePasses(data, minScore) {
  * `--force` overrides it, even for `--session-id`), the raw-size floor and the
  * triage score. Returns a skip, or what the prompt needs.
  */
-function runPreLlmSessionGates(harness, sessionRef, prior, force, gates) {
+async function runPreLlmSessionGates(harness, sessionRef, prior, force, gates) {
     const { sessionId } = sessionRef;
     let data;
     try {
-        data = harness.readSession(sessionRef);
+        data = await harness.readSession(sessionRef);
     }
     catch (err) {
         return {
@@ -333,7 +332,7 @@ function lockedConcurrentResult(harness, summary) {
  * Classify candidates read-only, up to `maxSessionsPerRun` model sessions
  * (explicit `--session-id` and `--force` are uncapped); the rest are deferred.
  */
-function planExtractSessions(args) {
+async function planExtractSessions(args) {
     const { candidates, options, harness, maxSessionsPerRun, locking } = args;
     const lockUnavailable = (summary) => locking &&
         extractSessionLockIsUnavailable(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath());
@@ -351,7 +350,7 @@ function planExtractSessions(args) {
             continue;
         }
         const prior = args.seenMap.get(summary.sessionId);
-        const gate = runPreLlmSessionGates(harness, summary, prior, options.force === true, args.gates);
+        const gate = await runPreLlmSessionGates(harness, summary, prior, options.force === true, args.gates);
         if ("skip" in gate) {
             plans.push({ kind: "skip", summary, result: gate.skip });
             continue;
@@ -366,58 +365,40 @@ function planExtractSessions(args) {
     }
     return { plans, deferredCandidates: [] };
 }
-const EXTRACT_LLM_UNAVAILABLE = Symbol("extract-llm-unavailable");
 /**
  * One session's extraction call, with one corrective retry; configuration
  * errors escape before any state is written.
  */
 async function extractFromSession(run, prompt) {
-    const { llmRunner } = run;
-    try {
-        const result = await runStructured({
-            dispatch: async (feedback) => {
-                // This loop parses and repairs the reply itself, so each attempt is one unvalidated dispatch.
-                const outcome = await callStageOnce({
-                    feature: "session_extraction",
-                    runner: llmRunner,
-                    prompt: feedback ? `${prompt}\n\n## Corrective output instruction\n\n${feedback}` : prompt,
-                    gate: { config: run.config },
-                    request: {
-                        timeoutMs: run.timeoutMs,
-                        responseSchema: EXTRACT_JSON_SCHEMA,
-                        ...(run.options.signal ? { signal: run.options.signal } : {}),
-                        ...(run.options.chat ? { chat: run.options.chat } : {}),
-                    },
-                    onNotices: run.notices.add,
-                });
-                if (!outcome.ok)
-                    throw EXTRACT_LLM_UNAVAILABLE;
-                return outcome.raw;
-            },
-            parse: (raw) => {
-                const payload = parseExtractPayload(raw);
-                return payload.parseFailure ? undefined : payload;
-            },
-            validate: (payload) => ({ ok: true, value: payload }),
-            buildFeedback: () => "Your previous response did not contain a valid extraction payload. Respond with ONLY a JSON object matching the requested schema, with a candidates array and no prose or code fences.",
-        });
-        if (result.ok)
-            return { kind: "success", payload: result.value, attempts: result.attempts };
-        return {
-            kind: "malformed",
-            raw: result.raw,
-            attempts: result.attempts,
-            failure: parseExtractPayload(result.raw).parseFailure ?? {
-                code: "invalid_payload",
-                message: result.errors.join("; "),
-            },
-        };
-    }
-    catch (err) {
-        if (err === EXTRACT_LLM_UNAVAILABLE)
-            return { kind: "unavailable" };
-        throw err;
-    }
+    // This loop parses and repairs the reply itself, so each attempt is one unvalidated dispatch.
+    const result = await callStageLoop({
+        runner: run.llmRunner,
+        prompt,
+        request: {
+            responseSchema: EXTRACT_JSON_SCHEMA,
+            ...(run.options.signal ? { signal: run.options.signal } : {}),
+            ...(run.options.chat ? { chat: run.options.chat } : {}),
+        },
+        onNotices: run.notices.add,
+    }, (raw) => {
+        const payload = parseExtractPayload(raw);
+        return payload.parseFailure
+            ? { ok: false, errors: [payload.parseFailure.message] }
+            : { ok: true, value: payload };
+    }, () => "## Corrective output instruction\n\nYour previous response did not contain a valid extraction payload. Respond with ONLY a JSON object matching the requested schema, with a candidates array and no prose or code fences.");
+    if (result.ok)
+        return { kind: "success", payload: result.value, attempts: result.attempts };
+    if (!isRefused(result))
+        return { kind: "unavailable" };
+    return {
+        kind: "malformed",
+        raw: result.raw,
+        attempts: result.attempts,
+        failure: parseExtractPayload(result.raw).parseFailure ?? {
+            code: "invalid_payload",
+            message: result.errors.join("; "),
+        },
+    };
 }
 /**
  * Write the session's searchable asset (`sessions/<harness>/<id>.md`). Fails
@@ -630,7 +611,7 @@ async function runExtractSessionLoop(run, planned, seenMap, stateDb, tracking, t
         deferred: 0,
     };
     const account = (result) => {
-        const stamped = { ...result, engine: run.llmRunner.engine };
+        const stamped = { ...result, engine: run.llmRunner.name };
         tally.sessions.push(stamped);
         const preempted = ["read_failed", "too_short", "already_extracted", "locked_concurrent"].includes(result.skipReason ?? "");
         if (gates.triage.enabled && !preempted) {
@@ -652,10 +633,10 @@ async function runExtractSessionLoop(run, planned, seenMap, stateDb, tracking, t
     };
     const workPlans = [...planned.plans];
     let remaining = planned.deferredCandidates;
-    const refillModelSlot = () => {
+    const refillModelSlot = async () => {
         if (remaining.length === 0 || options.signal?.aborted)
             return;
-        const refill = planExtractSessions({
+        const refill = await planExtractSessions({
             candidates: remaining,
             options,
             harness,
@@ -680,7 +661,7 @@ async function runExtractSessionLoop(run, planned, seenMap, stateDb, tracking, t
             const lock = acquireExtractSessionLock(extractSessionLockPath(harness.name, summary.sessionId, options.stateDbPath ?? getStateDbPath()));
             if (!lock.proceed) {
                 account(lockedConcurrentResult(harness.name, summary));
-                refillModelSlot();
+                await refillModelSlot();
                 continue;
             }
             lockOwnership = lock.ownership;
@@ -689,10 +670,10 @@ async function runExtractSessionLoop(run, planned, seenMap, stateDb, tracking, t
             const prior = stateDb
                 ? getExtractedSessionsMap(stateDb, harness.name, [summary.sessionId]).get(summary.sessionId)
                 : seenMap.get(summary.sessionId);
-            const gate = runPreLlmSessionGates(harness, summary, prior, options.force === true, gates);
+            const gate = await runPreLlmSessionGates(harness, summary, prior, options.force === true, gates);
             if ("skip" in gate) {
                 accountAndRecord(summary, gate.skip);
-                refillModelSlot();
+                await refillModelSlot();
                 continue;
             }
             const result = await processSession(run, summary, gate);
@@ -775,8 +756,8 @@ function recordSessionOutcome(stateDb, enabled, harness, summary, result, source
         warn(`[extract] failed to record session ${summary.sessionId} in state.db: ${err instanceof Error ? err.message : String(err)}`);
     }
 }
-/** The run's runner, budgets, gates and session-indexing settings (throws without an engine). */
-function resolveExtractRun(options, config, process, activeProfile) {
+/** The run's runner, budgets, gates and session-indexing settings (throws without a connection or harness). */
+function resolveExtractRun(options, config, process) {
     const notices = noticeSet();
     let llmRunner;
     if (options.resolvedPlan) {
@@ -787,32 +768,22 @@ function resolveExtractRun(options, config, process, activeProfile) {
         llmRunner = options.llmRunner;
     }
     else {
-        const resolved = resolveImproveExecution({ config, profile: activeProfile, process, processName: "extract" });
+        const resolved = resolveImproveExecution({ config, processName: "extract", alias: SHIPPED_ALIAS.extract });
         llmRunner = resolved?.runner;
         if (resolved)
             notices.add(resolved.notices);
     }
     if (!llmRunner) {
-        throw new ConfigError("No engine configured for extract. Set defaults.llmEngine or improve.strategies.<name>.processes.extract.engine.", "LLM_NOT_CONFIGURED");
+        throw new ConfigError("No connection or harness is configured for extract. Run `akm setup`, or set improve.connection or improve.processes.extract.connection.", "LLM_NOT_CONFIGURED");
     }
     const runner = llmRunner;
-    const timeoutMs = options.resolvedPlan
-        ? options.resolvedPlan.timeoutMs
-        : Object.hasOwn(options, "timeoutMs")
-            ? (options.timeoutMs ?? null)
-            : Object.hasOwn(runner, "timeoutMs")
-                ? (runner.timeoutMs ?? null)
-                : 600_000;
     const triage = process?.triage;
     // The default summary generator fails open: no summary, no session asset.
     const generate = async (data) => {
         const outcome = await callStage({
-            feature: "session_extraction",
             runner,
             prompt: buildSessionSummaryPrompt(data),
-            gate: { config },
             request: {
-                timeoutMs,
                 responseSchema: SESSION_SUMMARY_JSON_SCHEMA,
                 ...(options.signal ? { signal: options.signal } : {}),
                 ...(options.chat ? { chat: options.chat } : {}),
@@ -825,7 +796,6 @@ function resolveExtractRun(options, config, process, activeProfile) {
     return {
         llmRunner: runner,
         notices,
-        timeoutMs,
         gates: {
             maxTotalChars: typeof process?.maxTotalChars === "number" ? process.maxTotalChars : undefined,
             minContentChars: typeof process?.minContentChars === "number" ? process.minContentChars : DEFAULT_MIN_CONTENT_CHARS,
@@ -850,10 +820,10 @@ function resolveExtractRun(options, config, process, activeProfile) {
     };
 }
 /** The sessions to process: the `--session-id` target (or a not-found envelope) or the discovery window. */
-function discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun, llmRunner) {
+async function discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun, llmRunner) {
     const location = options.location ? { location: options.location } : {};
     if (options.sessionId) {
-        const target = harness.listSessions(location).find((s) => s.sessionId === options.sessionId);
+        const target = (await harness.listSessions(location)).find((s) => s.sessionId === options.sessionId);
         if (target)
             return { candidates: [target] };
         return {
@@ -874,7 +844,7 @@ function discoverExtractCandidates(options, harness, effectiveSince, startMs, dr
             ...(options.stateDbPath ? { stateDbPath: options.stateDbPath } : {}),
             ...(options.skipTracking ? { skipTracking: options.skipTracking } : {}),
         });
-    return { candidates: harness.listSessions({ sinceMs, ...location }) };
+    return { candidates: await harness.listSessions({ sinceMs, ...location }) };
 }
 function loadSeenMapReadOnly(options, harness, candidates, warnings) {
     if (options.skipTracking === true || candidates.length === 0)
@@ -922,7 +892,7 @@ export async function akmExtract(options) {
             startMs,
         });
     }
-    const resolved = resolveExtractRun(options, config, process, activeProfile);
+    const resolved = resolveExtractRun(options, config, process);
     const { llmRunner, notices } = resolved;
     const harness = (options.harnesses ?? getAvailableHarnesses()).find((h) => h.name === options.type);
     const unavailable = !harness
@@ -940,13 +910,13 @@ export async function akmExtract(options) {
             llmRunner,
         });
     }
-    const discovery = discoverExtractCandidates(options, harness, resolved.effectiveSince, startMs, dryRun, llmRunner);
+    const discovery = await discoverExtractCandidates(options, harness, resolved.effectiveSince, startMs, dryRun, llmRunner);
     if ("notFound" in discovery)
         return discovery.notFound;
     const topLevelWarnings = [];
     const tracking = options.skipTracking !== true;
     const seenMap = loadSeenMapReadOnly(options, harness.name, discovery.candidates, topLevelWarnings);
-    const planned = planExtractSessions({
+    const planned = await planExtractSessions({
         candidates: discovery.candidates,
         options,
         harness,
@@ -956,9 +926,6 @@ export async function akmExtract(options) {
         locking: tracking && !dryRun && !options.stateDb,
     });
     const modelPlanCount = planned.plans.filter((plan) => plan.kind === "model").length;
-    // Credentials are materialized once, after every read-only gate and before live state or a lock.
-    if (modelPlanCount > 0)
-        assertRunnerCredentials(llmRunner);
     let stateDb;
     let tally;
     try {
@@ -1011,7 +978,7 @@ export async function akmExtract(options) {
     for (const reason of EXTRACT_INFRASTRUCTURE_SKIP_REASONS) {
         const n = counts[reason];
         if (n)
-            topLevelWarnings.push(`${n} of ${tally.sessions.length} sessions skipped: ${reason} (engine "${llmRunner.engine}")`);
+            topLevelWarnings.push(`${n} of ${tally.sessions.length} sessions skipped: ${reason} (engine "${llmRunner.name}")`);
     }
     if (modelPlanCount > 0 && resolved.gates.triage.enabled && tally.triageEvaluated > 0) {
         appendEvent({
@@ -1039,7 +1006,7 @@ export async function akmExtract(options) {
         durationMs: Date.now() - startMs,
         ...notices.fields(),
         ...(Object.keys(counts).length > 0 ? { skipReasons: counts } : {}),
-        engine: llmRunner.engine,
+        engine: llmRunner.name,
         engineKind: llmRunner.kind,
     };
 }
@@ -1049,7 +1016,7 @@ export async function akmExtract(options) {
  * so a session counts as new when it has no seen row or a row without a
  * content hash; the exact hash check happens at extraction.
  */
-export function countNewExtractCandidates(_config, options = {}) {
+export async function countNewExtractCandidates(_config, options = {}) {
     const effectiveSince = options.since ?? getImproveProcessConfig("extract", options.improveProfile)?.defaultSince;
     const explicitSinceMs = effectiveSince ? parseSinceArg(effectiveSince) : undefined;
     const harnesses = (options.harnesses ?? getAvailableHarnesses()).filter((h) => h.isAvailable());
@@ -1064,7 +1031,10 @@ export function countNewExtractCandidates(_config, options = {}) {
                     ...(options.stateDbPath ? { stateDbPath: options.stateDbPath } : {}),
                     ...(options.readOnly && !options.stateDb ? { skipTracking: true } : {}),
                 });
-            const candidates = harness.listSessions({ sinceMs, ...(options.readOnly ? { isolatedSnapshot: true } : {}) });
+            const candidates = await harness.listSessions({
+                sinceMs,
+                ...(options.readOnly ? { isolatedSnapshot: true } : {}),
+            });
             if (candidates.length === 0)
                 continue;
             // A dry planner without state.db has no seen-session ledger by definition.

package/dist/commands/improve/improve-cli.js

@@ -4,20 +4,17 @@
 import path from "node:path";
 import { defineCommand } from "citty";
 import { findCittyTopLevelCommandIndex, getStringArg, hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { SELECTION_ARGS, selectionFromArgs } from "../../cli/selection.js";
 import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { isFullRefInput, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
+import { collectCredentialValues } from "../../core/config/credentials.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getRunLogDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
-import { clearLogFile, setLogFile } from "../../core/warn.js";
+import { clearLogFile, setLogFile, warnOnce } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
-import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
-import { defaultWhich } from "../../integrations/agent/detect.js";
-import { collectEngineCredentialValues, materializeLlmConnection, } from "../../integrations/agent/engine-resolution.js";
-import { llmUseFromRunner, sdkFallbackUseFromRunner } from "../../integrations/agent/runner.js";
-import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
 import { readStdin } from "../../runtime.js";
@@ -25,7 +22,7 @@ import { akmImprove, IMPROVE_TARGET_FLAG, resolveImproveReadSource } from "./imp
 import { runImproveReportQuery } from "./improve-report.js";
 import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
-import { resolveImprovePlan, resolveImproveStrategy, } from "./improve-strategies.js";
+import { resolveImprovePlan, resolveImproveStrategy } from "./improve-strategies.js";
 import { formatUsageReportTable } from "./improve-usage-report.js";
 import { renderReflectPromptPreview } from "./reflect.js";
 import { resolveQualityGateJudge, runReflectQualityJudge } from "./stage.js";
@@ -34,109 +31,6 @@ let akmImproveForRun = akmImprove;
 export function _setAkmImproveForTests(fake) {
     akmImproveForRun = fake ?? akmImprove;
 }
-/**
- * `--require-engines` (#957): fail before any side effect when an enabled
- * process cannot run, naming what each is missing — a scheduled run would
- * rather fail loudly than index and then skip everything.
- */
-function assertRequiredEnginesAvailable(plan) {
-    if (plan.engineUnavailable.length === 0)
-        return;
-    const lines = plan.engineUnavailable.map((item) => `  - ${item.process} (${item.configKey}): ${item.reason}`);
-    throw new ConfigError(`--require-engines: ${plan.engineUnavailable.length} improve process${plan.engineUnavailable.length === 1 ? "" : "es"} cannot run because ${plan.engineUnavailable.length === 1 ? "its" : "their"} engine is unavailable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
-}
-/** Every engine the plan would dispatch to, triage's judgment engine included. */
-function collectRequiredEngineTargets(plan) {
-    const runners = Object.entries(plan.processes)
-        .flatMap(([processName, process]) => (process.runner ? [[processName, process.runner]] : []))
-        .concat(plan.triageJudgment ? [["triage.judgment", plan.triageJudgment]] : []);
-    return runners.map(([processName, runner]) => {
-        // The runner's own timeout, else the connection's (sdkFallbackUseFromRunner already does this).
-        const use = runner.kind === "llm"
-            ? {
-                ...llmUseFromRunner(runner),
-                timeoutMs: runner.timeoutMs !== undefined ? runner.timeoutMs : (runner.connection.timeoutMs ?? null),
-            }
-            : runner.kind === "sdk"
-                ? sdkFallbackUseFromRunner(runner)
-                : undefined;
-        return {
-            process: processName,
-            engine: runner.engine,
-            ...(runner.kind === "llm" ? {} : { bin: runner.profile.bin }),
-            ...(use ? probeConnection(use) : {}),
-        };
-    });
-}
-/**
- * The connection the probe sends, built as a dispatch builds it: the runner
- * keeps its credential symbolic, so the key is read and injected here, or the
- * probe would go out without one.
- */
-function probeConnection(use) {
-    try {
-        return { connection: materializeLlmConnection(use) };
-    }
-    catch (err) {
-        return { connection: use.connection, error: err instanceof Error ? err.message : String(err) };
-    }
-}
-/**
- * The bound on `--require-engines`' probe: the connection's own request
- * timeout, at most two minutes. A local server busy with another job queues
- * the probe behind that job, and a fixed 3s bound failed every scheduled
- * improve run on 2026-09-27 against a reachable endpoint; the cap still ends a
- * hung endpoint (#957) long before a run's own multi-minute calls would.
- */
-export function requiredEngineProbeTimeoutMs(connection) {
-    return Math.min(connection.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS, REQUIRED_ENGINE_PROBE_MAX_MS);
-}
-const REQUIRED_ENGINE_PROBE_MAX_MS = 120_000;
-/**
- * `--require-engines`, live: probe each connection's real completion path
- * (a gateway can list a model whose completion route is dead, #980), once per
- * endpoint + model, within {@link requiredEngineProbeTimeoutMs}, and look each
- * agent harness's binary up on PATH. Returns each target's latency for the run
- * result (R17); an unreachable one fails the run.
- */
-export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, requiredEngineProbeTimeoutMs(connection)), which = defaultWhich) {
-    const targets = collectRequiredEngineTargets(plan);
-    if (targets.length === 0)
-        return [];
-    const probesByConnection = new Map();
-    const probeConnectionOnce = (connection) => {
-        const key = `${connection.endpoint.replace(/\/+$/, "")}|${connection.model}`;
-        let pending = probesByConnection.get(key);
-        if (!pending) {
-            const probeStartedAt = Date.now();
-            pending = probeReachable(connection).then((reach) => ({ reach, latencyMs: Date.now() - probeStartedAt }));
-            probesByConnection.set(key, pending);
-        }
-        return pending;
-    };
-    const probed = await Promise.all(targets.map(async (target) => {
-        if (target.bin !== undefined && which(target.bin) === undefined) {
-            return { ...target, reach: { reachable: false, error: `${target.bin} is not on PATH` }, latencyMs: 0 };
-        }
-        if (!target.connection)
-            return { ...target, reach: { reachable: true }, latencyMs: 0 };
-        if (target.error)
-            return { ...target, reach: { reachable: false, error: target.error }, latencyMs: 0 };
-        return { ...target, ...(await probeConnectionOnce(target.connection)) };
-    }));
-    const unreachable = probed.filter((item) => !item.reach.reachable);
-    if (unreachable.length > 0) {
-        const lines = unreachable.map((item) => `  - ${item.process} (engine "${item.engine}", ${item.connection?.endpoint ?? item.bin}): ${item.reach.error ?? "did not respond"}`);
-        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED", "Check that each listed endpoint is up and serves its model, and that each listed agent binary is installed. The endpoint probe is one short completion, bounded by the engine's timeoutMs (at most two minutes).");
-    }
-    return probed.map((item) => ({
-        process: item.process,
-        engine: item.engine,
-        endpoint: item.connection?.endpoint ?? item.bin,
-        reachable: item.reach.reachable,
-        latencyMs: item.latencyMs,
-    }));
-}
 /** `--show-prompt` (#952): print reflect's composed prompt for one ref — no lock, write or dispatch. */
 async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedPlan) {
     const readSource = resolveImproveReadSource(resolvedPlan.config, parsedRef, targetArg);
@@ -145,6 +39,9 @@ async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedP
         ...(taskArg ? { task: taskArg } : {}),
         improveProfile: resolvedPlan.strategy.config,
         config: resolvedPlan.config,
+        // A strategy that turns reflect off froze no runner for it; the preview resolves its own.
+        ...(resolvedPlan.processes.reflect.runner ? { llmRunner: resolvedPlan.processes.reflect.runner } : {}),
+        ...(resolvedPlan.run ? { run: resolvedPlan.run } : {}),
         stashDir: readSource.source.path,
     });
     const outputMode = getOutputMode();
@@ -184,7 +81,7 @@ const improveReportCommand = defineJsonCommand({
 });
 /**
  * `akm improve judge`: reflect's quality judge on one revision, read as
- * `{"source", "candidate", "feedback"}` JSON from stdin, with the engine the
+ * `{"source", "candidate", "feedback"}` JSON from stdin, on the connection or harness the
  * strategy's reflect quality gate names. It writes nothing.
  */
 const improveJudgeCommand = defineJsonCommand({
@@ -209,7 +106,7 @@ const improveJudgeCommand = defineJsonCommand({
         const config = loadConfig();
         const judge = resolveQualityGateJudge(config, resolveImproveStrategy(getStringArg(args, "strategy"), config).config, "reflect");
         if (!judge) {
-            throw new ConfigError("`akm improve judge` judges with the reflect quality gate's engine. Set processes.reflect.qualityGate.engine.", "INVALID_CONFIG_FILE");
+            throw new ConfigError("`akm improve judge` judges with the reflect quality gate's connection or harness. Set improve.qualityGate.connection.", "INVALID_CONFIG_FILE");
         }
         const notes = typeof feedback === "string" && feedback.trim() !== "" ? [feedback.trim()] : [];
         const verdict = await runReflectQualityJudge(config, candidate, source, notes, undefined, {
@@ -217,7 +114,7 @@ const improveJudgeCommand = defineJsonCommand({
             llmRunner: judge,
             ...(typeof ref === "string" && ref ? { ref } : {}),
         });
-        output("improve-judge", { engine: judge.engine, ...verdict });
+        output("improve-judge", { engine: judge.name, ...verdict });
     },
 });
 /** The subcommands `setup` withheld for this run, restored by `cleanup` (one command runs per process; in-process tests run many). */
@@ -282,20 +179,18 @@ export const improveCommand = defineCommand({
             description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 75). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
-        "require-engines": {
-            type: "boolean",
-            description: "Abort before any indexing, lock, or log side effect (exit 78) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe (the same probe akm health runs). Without this flag, improve degrades gracefully instead: it skips the affected processes and reports them in the result's skippedProcesses. Recommended alongside --skip-if-locked for scheduled runs.",
-            default: false,
-        },
+        // Retired: a run already stops at planning (exit 78) when no process has a connection or harness to run on.
+        "require-engines": { type: "boolean", hidden: true, description: "Retired: has no effect." },
         "show-prompt": {
             type: "boolean",
-            description: "Print the composed reflect prompt for one asset ref and exit — no lock, index write, or engine dispatch (#952). Requires a fully-qualified asset ref as the scope positional (e.g. `akm improve lessons/my-lesson --show-prompt`). JSON/yaml format carries the prompt as a `prompt` field; text format prints it directly.",
+            description: "Print the composed reflect prompt for one asset ref and exit — no lock, index write, or model call (#952). Requires a fully-qualified asset ref as the scope positional (e.g. `akm improve lessons/my-lesson --show-prompt`). JSON/yaml format carries the prompt as a `prompt` field; text format prints it directly.",
             default: false,
         },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (consolidate, default). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (consolidate, default). Controls which sub-processes run and which asset types are processed, never where they run.",
         },
+        ...SELECTION_ARGS,
         sync: {
             type: "boolean",
             description: "Sync the git-backed primary bundle like `akm sync` (fetch and merge the upstream, commit, push) before the run, and commit (and optionally push) when it finishes. Use --no-sync to disable. Default: on for git-backed bundles (per profile config).",
@@ -310,6 +205,9 @@ export const improveCommand = defineCommand({
             // citty runs this body after a subcommand it dispatched too.
             if (hasSubcommand(args, new Set(Object.keys(IMPROVE_SUBCOMMANDS))))
                 return;
+            if (args["require-engines"]) {
+                warnOnce("retired-flag:--require-engines", "--require-engines is retired and has no effect: akm improve already stops at planning (exit 78) when no process has a connection or harness to run on, and `akm health` checks the connections and harnesses.");
+            }
             const jsonToStdout = args["json-to-stdout"];
             const targetArg = getStringArg(args, "bundle");
             const taskArg = getStringArg(args, "task");
@@ -320,6 +218,8 @@ export const improveCommand = defineCommand({
             const requireFeedbackSignal = args["require-feedback-signal"];
             const skipIfLocked = args["skip-if-locked"];
             const strategyArg = getStringArg(args, "strategy");
+            // What the run selected is the nearest layer of every call in it, judges included.
+            const run = selectionFromArgs(args);
             const effectiveConfig = loadConfig();
             const scopeArg = getStringArg(args, "scope");
             const scopeRef = scopeArg && isFullRefInput(scopeArg) ? parseRefInput(scopeArg) : undefined;
@@ -330,7 +230,7 @@ export const improveCommand = defineCommand({
                     : resolveWriteTarget(effectiveConfig, targetArg, { flag: IMPROVE_TARGET_FLAG });
             // Every model-backed process resolves before any side effect; a dry run
             // never dispatches, so it tolerates every process being disabled.
-            const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });
+            const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, Object.keys(run).length > 0 ? { run } : {});
             if (args["show-prompt"]) {
                 if (!scopeArg || !scopeRef) {
                     throw new UsageError("`--show-prompt` requires a fully-qualified asset ref as the scope (e.g. `akm improve lessons/my-lesson --show-prompt`).", "INVALID_FLAG_VALUE");
@@ -338,13 +238,8 @@ export const improveCommand = defineCommand({
                 await runShowPromptCli(scopeArg, scopeRef, taskArg, targetArg, resolvedPlan);
                 return;
             }
-            let engineProbe;
-            if (args["require-engines"]) {
-                assertRequiredEnginesAvailable(resolvedPlan);
-                engineProbe = await assertRequiredEnginesReachable(resolvedPlan);
-            }
             const selectedStrategyName = resolvedPlan.strategy.name;
-            const sensitiveValues = collectEngineCredentialValues(effectiveConfig);
+            const sensitiveValues = collectCredentialValues(effectiveConfig);
             // Only flags actually passed override the strategy's `sync` block.
             const syncFlag = args.sync;
             const pushFlag = args.push;
@@ -403,7 +298,6 @@ export const improveCommand = defineCommand({
                         ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
                         ...(skipIfLocked ? { skipIfLocked } : {}),
                         ...(strategyArg !== undefined ? { strategy: strategyArg } : {}),
-                        ...(engineProbe !== undefined ? { engineProbe } : {}),
                         onBudgetHardKill: () => persistTerminated("budget_exhausted"),
                         ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
                     }),