akm-cli 0.9.5 → 0.9.7

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

@@ -29,7 +29,7 @@ export function describeGatedLanes(lanes) {
 }
 /** Configured capabilities that tasks doctor reports behind the autonomy gate. */
 export function configuredDirectAutonomyLanes() {
-    return ["memoryCleanup"];
+    return [...DIRECT_AUTONOMY_LANES];
 }
 /**
  * True when a lane may mutate. Used by the lane that bypasses the strategy

package/dist/commands/improve/consolidate.js

@@ -27,6 +27,7 @@ import { findEntryIdByRef, getAllEntries, getEntryById } from "../../storage/rep
 import { getNeighborsByEntryId } from "../../storage/repositories/index-vec-repository.js";
 import { isProposalSkipped, listProposals, listProposalsReadOnly, proposalContent, } from "../proposal/repository.js";
 import { hasSupersededStatus, validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
+import { DEFAULT_RANDOM_CLUSTER_FRACTION } from "./anti-collapse.js";
 import { cacheHash } from "./content-hash.js";
 import { resolveImproveLlmExecution } from "./execution.js";
 import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
@@ -190,14 +191,15 @@ async function clusterMemoriesBySimilarity(memories, config, stateDb, signal) {
         finally {
             embedMs += Date.now() - embedStart;
         }
-        // Upsert newly computed vectors into the cache.
+        // Upsert newly computed vectors into the cache. A skipped document
+        // (embedBatch reports it via `undefined` rather than throwing, #874) has
+        // no vector to cache — omit it rather than writing a bogus embedding.
         if (stateDb && missVecs.length === missTexts.length) {
             try {
-                const toUpsert = missIndices.map((idx, pos) => ({
-                    contentHash: contentHashes[idx],
-                    embedding: missVecs[pos],
-                    modelId,
-                }));
+                const toUpsert = missIndices.flatMap((idx, pos) => {
+                    const embedding = missVecs[pos];
+                    return embedding ? [{ contentHash: contentHashes[idx], embedding, modelId }] : [];
+                });
                 upsertBodyEmbeddings(stateDb, toUpsert);
             }
             catch {
@@ -783,26 +785,23 @@ async function judgeConsolidationChunks(args) {
                 ...(opts.onNotices ? { onNotices: opts.onNotices } : {}),
             });
         };
-        let raw = await callChunkLlm(`chunk ${chunkIdx + 1} failed`);
+        // callChunkLlm already retries once internally (llm/client.ts's
+        // chatCompletion, jittered 200-800ms backoff) — a second, outer retry
+        // here stacked an uncoordinated fixed 2s backoff on top of it. Removed;
+        // only mark the chunk failed once the single retry the client already
+        // performs has been exhausted.
+        const raw = await callChunkLlm(`chunk ${chunkIdx + 1} failed`);
         if (!raw.ok) {
-            // Single retry with 2s backoff before recording chunk as lost.
-            // Recovers transient Shredder LM Studio timeouts without significantly
-            // extending run time. Only marks failed if both attempts fail.
-            await new Promise((r) => setTimeout(r, 2_000));
-            const retry = await callChunkLlm(`chunk ${chunkIdx + 1} retry failed`);
-            if (!retry.ok) {
-                warn(retry.error ?? `chunk ${chunkIdx + 1} failed after retry`);
-                warnings.push(retry.error ?? `chunk ${chunkIdx + 1} failed after retry`);
-                totalChunksProcessed++;
-                accounting.totalChunksFailed++;
-                // Account for the chunk's memories under the failed-chunk bucket.
-                // judgedNoAction does NOT run on this path (it's after the success
-                // guards) so without this the accounting invariant breaks on every
-                // chunk-level transport/parse failure.
-                accounting.failedChunkMemories += chunk.length;
-                continue;
-            }
-            raw = retry;
+            warn(raw.error ?? `chunk ${chunkIdx + 1} failed`);
+            warnings.push(raw.error ?? `chunk ${chunkIdx + 1} failed`);
+            totalChunksProcessed++;
+            accounting.totalChunksFailed++;
+            // Account for the chunk's memories under the failed-chunk bucket.
+            // judgedNoAction does NOT run on this path (it's after the success
+            // guards) so without this the accounting invariant breaks on every
+            // chunk-level transport/parse failure.
+            accounting.failedChunkMemories += chunk.length;
+            continue;
         }
         // C9 action 1: AKM_DEBUG_LLM was a separate, undocumented env var for this
         // one diagnostic; folded into the standard AKM_VERBOSE gate (warnVerbose)
@@ -922,7 +921,7 @@ async function planConsolidation(opts, config, stashDir, _startMs, memories, war
             const antiCollapseForCluster = getImproveProcessConfig("consolidate", opts.improveProfile)?.antiCollapse ??
                 {};
             if (antiCollapseForCluster.enabled !== false && clusteredMemories.length > 2) {
-                const fraction = antiCollapseForCluster.randomClusterFraction ?? 0.05;
+                const fraction = antiCollapseForCluster.randomClusterFraction ?? DEFAULT_RANDOM_CLUSTER_FRACTION;
                 const randomCount = Math.max(1, Math.floor(clusteredMemories.length * fraction));
                 // Pick `randomCount` positions to inject random (un-clustered) members.
                 // Use a seeded-ish shuffle: sort by hash of the name so it's deterministic

package/dist/commands/improve/distill.js

@@ -73,7 +73,7 @@ import { stripFrontmatterBody as stripBodyForFidelity } from "./content-hash.js"
 import { autoRepairLessonFrontmatter, autoSwapDescriptionWhenToUse, collectLessonQualityFindings, repairLessonDescriptionTruncation, } from "./distill/content-repair.js";
 import { memoryKnowledgePromotionRequiresDispatch, planMemoryKnowledgePromotion, promoteMemoryToKnowledge, } from "./distill/promote-memory.js";
 import { fetchTopSimilarLessons, persistOutputEncodingSalience, runLessonQualityJudge, writeQualityRejection, } from "./distill/quality-gate.js";
-import { buildClsContext, checkDistillFidelity } from "./distill-guards.js";
+import { buildClsContext, checkDistillFidelity, DEFAULT_CLS_ADJACENT_COUNT } from "./distill-guards.js";
 import { deriveKnowledgeRef } from "./distill-promotion-policy.js";
 import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.js";
 import { resolveImproveLlmExecution } from "./execution.js";
@@ -1239,7 +1239,7 @@ async function buildDistillMessages(args) {
     let clsContext = "";
     if (clsConfig.enabled) {
         try {
-            const adjacentCount = clsConfig.adjacentCount ?? 3;
+            const adjacentCount = clsConfig.adjacentCount ?? DEFAULT_CLS_ADJACENT_COUNT;
             // Use the asset content or input ref as the query for adjacent retrieval.
             const clsQuery = assetContent ? assetContent.slice(0, 500) : inputRef;
             const adjacentItems = await fetchSimilarLessonsFn(clsQuery, adjacentCount);

package/dist/commands/improve/extract.js

@@ -44,6 +44,7 @@ import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { disposeLoweredExecutionDispatchLease, } from "../../integrations/agent/execution-lowering.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { preFilterSession } from "../../integrations/session-logs/pre-filter.js";
+import { isJsonSchemaKnownUnsupported } from "../../llm/client.js";
 import { callStructured, preflightStructuredLlmRunner } from "../../llm/structured-call.js";
 import { sha256Hex } from "../../runtime.js";
 import { getExtractedSessionsMap, getLastExtractRunAt, shouldSkipAlreadyExtractedSession, upsertExtractedSession, } from "../../storage/repositories/extract-sessions-repository.js";
@@ -563,7 +564,13 @@ async function runSessionExtractionLlmCall(args) {
                 return payload.parseFailure ? undefined : payload;
             },
             validate: (payload) => ({ ok: true, value: payload }),
-            maxAttempts: llmRunner.connection.supportsJsonSchema === true ? 1 : 2,
+            // One attempt when structured output is expected to work (not explicitly
+            // disabled, and this connection hasn't already proven otherwise this
+            // process — see `isJsonSchemaKnownUnsupported`); two when it's known
+            // unsupported and extraction is relying on looser prompt-contract JSON.
+            maxAttempts: llmRunner.connection.supportsJsonSchema !== false && !isJsonSchemaKnownUnsupported(llmRunner.connection)
+                ? 1
+                : 2,
             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)

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

@@ -114,7 +114,7 @@ export const improveCommand = defineCommand({
         },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, frequent, graph-refresh, memory-focus, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, graph-refresh, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",

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

@@ -4,9 +4,7 @@
 import catchup from "../../assets/improve-strategies/catchup.json" with { type: "json" };
 import consolidate from "../../assets/improve-strategies/consolidate.json" with { type: "json" };
 import defaultStrategy from "../../assets/improve-strategies/default.json" with { type: "json" };
-import frequent from "../../assets/improve-strategies/frequent.json" with { type: "json" };
 import graphRefresh from "../../assets/improve-strategies/graph-refresh.json" with { type: "json" };
-import memoryFocus from "../../assets/improve-strategies/memory-focus.json" with { type: "json" };
 import proactiveMaintenance from "../../assets/improve-strategies/proactive-maintenance.json" with { type: "json" };
 import quick from "../../assets/improve-strategies/quick.json" with { type: "json" };
 import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
@@ -45,9 +43,7 @@ const BUILTIN_STRATEGIES = {
     default: defaultStrategy,
     quick,
     thorough,
-    "memory-focus": memoryFocus,
     "graph-refresh": graphRefresh,
-    frequent,
     consolidate,
     catchup,
     "reflect-distill": reflectDistill,

package/dist/commands/improve/improve.js

@@ -35,7 +35,7 @@ import { akmDistill } from "./distill.js";
 import { buildLatestProposalTsMap, collectEligibleRefs, collectEligibleRefsReadOnly, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
 import { countEvalCases } from "./eval-cases.js";
 import { resolveImprovePlan, resolveImproveStrategy } from "./improve-strategies.js";
-import { improveLockPath, MIN_IMPROVE_LOCK_STALE_MS, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
+import { improveLockPath, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
 // The cycle loop / post-loop / maintenance stages live in ./loop-stages.
 import { runImproveLoopStage, runImprovePostLoopStage } from "./loop-stages.js";
 import { analyzeMemoryCleanup } from "./memory/memory-improve.js";
@@ -115,7 +115,7 @@ function createRunWriteJournal() {
 export async function akmImprove(options = {}) {
     const setup = resolveImproveRunSetup(options);
     options = setup.options;
-    const { budgetMs, budgetAbortController, scope, selectedStrategy, syncRepoDir, resolvedStateDbPath, resolvedLockPath, lockStaleAfterMs, } = setup;
+    const { budgetMs, budgetAbortController, scope, selectedStrategy, syncRepoDir, resolvedStateDbPath, resolvedLockPath, } = setup;
     let clearBudgetTimer = () => { };
     let initialGitPaths = new Set();
     const runJournal = createRunWriteJournal();
@@ -164,7 +164,7 @@ export async function akmImprove(options = {}) {
     }
     try {
         if (!options.dryRun) {
-            const acquisition = tryAcquireImproveLock(resolvedLockPath, lockStaleAfterMs, options.skipIfLocked, {
+            const acquisition = tryAcquireImproveLock(resolvedLockPath, options.skipIfLocked, {
                 // R25: C2 boundary-pinned path — the long-lived handle doesn't exist yet.
                 dbPath: resolvedStateDbPath,
             });
@@ -484,7 +484,6 @@ function resolveImproveRunSetup(options) {
     // triage, indexing, proposal work, maintenance, and final stash sync.
     const lockBaseDir = primaryStashDir ? path.join(primaryStashDir, ".akm") : path.join(options.stashDir ?? ".", ".akm");
     const resolvedLockPath = improveLockPath(lockBaseDir);
-    const lockStaleAfterMs = Math.max(MIN_IMPROVE_LOCK_STALE_MS, budgetMs + 10 * 60 * 1000);
     const effectiveSync = { ...improveProfile.sync, ...options.sync };
     return {
         startMs,
@@ -514,7 +513,6 @@ function resolveImproveRunSetup(options) {
         syncRepoDir,
         resolvedStateDbPath,
         resolvedLockPath,
-        lockStaleAfterMs,
         effectiveSync,
     };
 }

package/dist/commands/improve/locks.js

@@ -9,13 +9,12 @@ import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquire
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
 import { describeInaccessiblePath } from "../../core/path-access.js";
 import { warn } from "../../core/warn.js";
-export const MIN_IMPROVE_LOCK_STALE_MS = 4 * 60 * 60 * 1000;
 export function improveLockPath(lockBaseDir) {
     return path.join(lockBaseDir, "improve.lock");
 }
-export function tryAcquireImproveLock(lockPath, staleAfterMs, skipIfLocked, eventsCtx) {
+export function tryAcquireImproveLock(lockPath, skipIfLocked, eventsCtx) {
     let recoveryEvent;
-    const acquire = () => tryAcquireImproveLockUnlocked(lockPath, staleAfterMs, skipIfLocked, (event) => {
+    const acquire = () => tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, (event) => {
         recoveryEvent = event;
     });
     const result = skipIfLocked ? tryWithMaintenanceStartBarrier(acquire) : withMaintenanceStartBarrier(acquire);
@@ -37,14 +36,23 @@ export function tryAcquireImproveLock(lockPath, staleAfterMs, skipIfLocked, even
     }
     return result;
 }
-function tryAcquireImproveLockUnlocked(lockPath, staleAfterMs, skipIfLocked, onRecovered) {
+function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     const lockPayload = () => createLockPayload({ startedAt: new Date().toISOString() });
     let ownership = tryAcquireLockSync(lockPath, lockPayload());
     if (ownership) {
         return { state: "acquired", ownership };
     }
-    const probe = probeLock(lockPath, { staleAfterMs });
+    // No `staleAfterMs`: only a verifiably dead holder is ever reclaimed. A
+    // wedged-but-alive `akm improve` (SQLite WAL + busy_timeout + BEGIN
+    // IMMEDIATE already serialize concurrent writes to state.db at the
+    // correctness layer, so this lock only avoids duplicate LOGICAL work) must
+    // not have its lease silently taken away purely because a clock elapsed —
+    // that was the #872-shaped hazard here: a live holder passed the
+    // PID-liveness check forever, so only a multi-hour age window could ever
+    // free it, stranding every `akm improve --skip-if-locked` invocation for
+    // up to that long while reporting success.
+    const probe = probeLock(lockPath);
     // Race: the holder released the lock between our failed `tryAcquireLockSync`
     // and this probe, so the probe sees no file (`absent`). Retry acquisition once
     // rather than falling through to the contended skip/throw below — otherwise we

package/dist/commands/improve/loop-stages.js

@@ -13,7 +13,6 @@ import { getDbPath } from "../../core/paths.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info } from "../../core/warn.js";
 import { DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES, runGraphExtractionPass, } from "../../indexer/graph/graph-extraction.js";
-import { withIndexWriterLease } from "../../indexer/index-writer-lock.js";
 import { deriveWritableBundleIds } from "../../indexer/installations.js";
 import { collectPendingMemories, runMemoryInferencePass, } from "../../indexer/passes/memory-inference.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -679,13 +678,13 @@ export async function runImproveMaintenancePasses(args) {
         graphExtractionFn,
         reindexWithIndexDbReleased,
     };
-    const collected = await withIndexWriterLease({ purpose: "improve-maintenance", signal: budgetSignal }, () => runMaintenancePassesUnderLease(ctx, dbCell, {
+    const collected = await runMaintenancePassesUnderLease(ctx, dbCell, {
         actionableRefs: args.actionableRefs,
         memoryRefsForInference,
         consolidationRan: args.consolidationRan,
         allWarnings,
         openIndexDb,
-    }));
+    });
     return {
         ...(collected.memoryInference ? { memoryInference: collected.memoryInference } : {}),
         ...(collected.graphExtraction ? { graphExtraction: collected.graphExtraction } : {}),
@@ -697,12 +696,12 @@ export async function runImproveMaintenancePasses(args) {
     };
 }
 /**
- * The maintenance sequence run under the index-writer lease (formerly the
- * ~389-line anonymous `withIndexWriterLease` callback): memory inference →
- * reindex-after-inference → graph extraction → proposal hygiene (orphan purge,
- * expiration) → retention purges. Each pass returns its results and warnings;
- * this orchestrator folds warnings into the caller's `allWarnings` sink at the
- * same points the inline code pushed them.
+ * The maintenance sequence (formerly the ~389-line anonymous
+ * `withIndexWriterLease` callback, before #872 removed the index-rebuild
+ * lease): memory inference → reindex-after-inference → graph extraction →
+ * proposal hygiene (orphan purge, expiration) → retention purges. Each pass
+ * returns its results and warnings; this orchestrator folds warnings into the
+ * caller's `allWarnings` sink at the same points the inline code pushed them.
  */
 async function runMaintenancePassesUnderLease(ctx, dbCell, args) {
     const { allWarnings } = args;

package/dist/commands/improve/memory/memory-contradiction-detect.js

@@ -14,7 +14,7 @@
  * # Algorithm
  *
  *   1. Collect all derived memories grouped by `parentRef` family.
- *   2. For each family, enumerate candidate pairs (limited to MAX_FAMILY_SIZE).
+ *   2. For each family, enumerate candidate pairs.
  *   3. For each pair, call the LLM to judge whether the two memories are in
  *      direct factual conflict.
  *   4. For confirmed contradictions, write `contradictedBy` edges directly to
@@ -43,16 +43,6 @@ import { callStructured, preflightStructuredLlmRunner } from "../../../llm/struc
 import { resolveImproveLlmExecution } from "../execution.js";
 import { isDerivedMemory, memoryIdentityRef, resolveParentRef } from "./derived-ref.js";
 // ── Constants ────────────────────────────────────────────────────────────────
-/**
- * Maximum family size for pairwise contradiction checking. Families larger
- * than this are skipped to bound the LLM call count (O(n²) pairs).
- */
-const MAX_FAMILY_SIZE = 8;
-/**
- * Maximum number of contradiction pairs to check per improve run, across all
- * families. Prevents runaway LLM usage on stashes with many memories.
- */
-const MAX_PAIRS_PER_RUN = 20;
 /**
  * Minimum confidence required to write a contradiction edge. Below this
  * threshold the LLM may be flagging topic-overlap rather than genuine logical
@@ -218,15 +208,9 @@ export async function detectAndWriteContradictions(stashDir, config, chat, strat
     for (const [, family] of byParent) {
         if (family.length < 2)
             continue;
-        if (family.length > MAX_FAMILY_SIZE) {
-            result.warnings.push(`Skipping contradiction check for family of ${family.length} members (exceeds MAX_FAMILY_SIZE=${MAX_FAMILY_SIZE})`);
-            continue;
-        }
         result.familiesExamined++;
         for (let i = 0; i < family.length - 1; i++) {
             for (let j = i + 1; j < family.length; j++) {
-                if (candidatePairs.length >= MAX_PAIRS_PER_RUN)
-                    break;
                 const a = family[i];
                 const b = family[j];
                 if (!a || !b)
@@ -245,8 +229,6 @@ export async function detectAndWriteContradictions(stashDir, config, chat, strat
                     continue;
                 candidatePairs.push({ a, b, loser, winnerRef });
             }
-            if (candidatePairs.length >= MAX_PAIRS_PER_RUN)
-                break;
         }
     }
     if (candidatePairs.length === 0) {

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

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assembleAsset } from "../../../core/asset/asset-serialize.js";
 import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { MEMORY_ARCHIVE_REL } from "../../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString, groupBy, stringArray } from "../../../core/common.js";
 import { DERIVED_SUFFIX } from "../../../core/recognition-util.js";
@@ -553,7 +554,7 @@ function priorBeliefStateForArchive(candidate) {
 }
 function createArchiveDir(stashDir, ref, archivedAt) {
     const baseName = `${archivedAt.replace(/[:.]/g, "-")}-${sanitizeRef(ref)}`;
-    const root = path.join(stashDir, ".akm", "memory-cleanup", "archive");
+    const root = path.join(stashDir, MEMORY_ARCHIVE_REL);
     fs.mkdirSync(root, { recursive: true });
     let attempt = 0;
     while (true) {

package/dist/commands/improve/outcome-loop.js

@@ -9,12 +9,6 @@ import { getAllAssetOutcomes, getAssetOutcome, getOutcomeScoresByRef, upsertAsse
  * At α = 0.3 the window is ≈ 3 cycles.
  */
 export const OUTCOME_EMA_ALPHA = 0.3;
-/**
- * Maximum K improve cycles for the eligibility-trace window. Retrievals older
- * than K cycles contribute via the EMA decay naturally (they are already baked
- * into `expected_retrieval_rate`).
- */
-export const OUTCOME_TRACE_CYCLES = 5;
 /**
  * Warm-start cap: the maximum `outcome_score` a brand-new row can be seeded with
  * (from the utility EMA). Prevents a `[0,1]`-range utility value from generating

package/dist/commands/improve/preparation.js

@@ -760,7 +760,7 @@ async function runPreparationPrelude(args) {
     };
 }
 export async function runImprovePreparationStage(args) {
-    const { scope, options, plannedRefs, primaryStashDir, eventsCtx, initialCleanupWarnings, improveProfile, resolvedPlan, planOnly = options.dryRun === true, } = args;
+    const { scope, options, primaryStashDir, eventsCtx, initialCleanupWarnings, improveProfile, resolvedPlan, planOnly = options.dryRun === true, } = args;
     const actions = [];
     const cleanupWarnings = initialCleanupWarnings ? [...initialCleanupWarnings] : [];
     const { memoryIndexHealth, consolidationPass, extractPlan, extractResults, appliedCleanup, postCleanupRefs, cleanupGate, validationFailures, validationFailureRefs, schemaRepairs, } = await runPreparationPrelude({ ...args, planOnly, actions, cleanupWarnings });

package/dist/commands/improve/reflect.js

@@ -44,7 +44,7 @@ import { prepareInlineExecution, prepareInlineExecutionWithRunner } from "../../
 import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
 import { runnerIsLlm, runnerSupportsFileWrite } from "../../integrations/agent/runner.js";
 import { collectDispatchSensitiveValues } from "../../integrations/agent/runner-dispatch.js";
-import { LlmCallError } from "../../llm/client.js";
+import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
 import { callStructured } from "../../llm/structured-call.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
 import { isProposalSkipped, listProposalsReadOnly, proposalContent, } from "../proposal/repository.js";
@@ -578,8 +578,9 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
 }
 /**
  * JSON Schema for structured reflect output. Passed to `chatCompletion` when
- * the connection has `supportsJsonSchema: true` so the model returns a strict
- * JSON object containing only the target-scoped fields AKM cannot derive.
+ * {@link wantsJsonSchemaOutput} selects `outputMode: "json_schema"`, so the
+ * model returns a strict JSON object containing only the target-scoped
+ * fields AKM cannot derive.
  */
 const REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA = {
     type: "object",
@@ -626,6 +627,17 @@ const REFLECT_UNSCOPED_JSON_SCHEMA = {
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
+/**
+ * Whether to frame the reflect prompt for structured JSON output on this
+ * connection. Optimistic by default — `chatCompletion` attempts
+ * `response_format: json_schema` fresh on every call and falls back once on
+ * a 4xx, so there is no persisted verdict to consult here. `false` only when
+ * a human/workflow explicitly disabled it, or a real call already proved
+ * this connection rejects it earlier in the same process.
+ */
+function wantsJsonSchemaOutput(connection) {
+    return connection.supportsJsonSchema !== false && !isJsonSchemaKnownUnsupported(connection);
+}
 /** Critique prompt injected between prior draft and refinement request (Self-Refine loop). */
 const REFLECT_CRITIQUE_PROMPT = "Your previous proposal is shown above. Review it critically and provide an improved version that is more specific, actionable, and avoids any issues with the previous attempt. Return only the improved response using the output contract from the original prompt.";
 /**
@@ -778,7 +790,7 @@ function parseDirectReflectOutput(raw, mode, targetRef) {
 export async function runReflectViaLlm(opts) {
     const start = Date.now();
     let repairAttempts = 0;
-    const connection = opts.runner.connection;
+    const _connection = opts.runner.connection;
     const messages = [{ role: "user", content: opts.prompt ?? "" }];
     const configuredTimeout = Object.hasOwn(opts, "timeoutMs")
         ? (opts.timeoutMs ?? null)
@@ -1354,21 +1366,20 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
 }
 /**
  * Run the agent with the optional Self-Refine loop (R-1 / #372): up to
- * MAX_REFINE_ITERS invocations, each injecting the prior draft as self-critique
+ * `maxRefineIters` invocations, each injecting the prior draft as self-critique
  * context and exiting early on a no-op refinement. Synthesizes per-iteration
  * draft paths into `draftPathsToCleanup` (mutated) and returns the final agent
  * result + last draft path. Extracted verbatim from `akmReflect`.
  */
 async function runReflectRefineIterations(args) {
     const { options, parsedRef, assetContent, feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext, runnerSpec, lease, agentEnv, draftPathsToCleanup, onNotices, } = args;
-    const MAX_REFINE_ITERS = 3;
-    const maxRefineIters = Math.min(Math.max(1, options.maxRefineIters ?? 1), MAX_REFINE_ITERS);
+    const maxRefineIters = Math.max(1, options.maxRefineIters ?? 1);
     // Determine whether this dispatch can honour the file-write contract.
     // Agent CLI + OpenCode SDK runners both have filesystem access; the direct
     // LLM HTTP runner does NOT.
     const canRunnerWriteFile = runnerSupportsFileWrite(runnerSpec);
     const outputMode = runnerIsLlm(runnerSpec)
-        ? runnerSpec.connection.supportsJsonSchema
+        ? wantsJsonSchemaOutput(runnerSpec.connection)
             ? "json_schema"
             : "framed_markdown"
         : undefined;
@@ -1421,10 +1432,10 @@ async function runReflectRefineIterations(args) {
                 ...(options.signal ? { signal: options.signal } : {}),
                 priorDraft,
                 iteration: iter,
-                ...(runnerSpec.connection.supportsJsonSchema
+                ...(outputMode === "json_schema"
                     ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
                     : {}),
-                outputMode: runnerSpec.connection.supportsJsonSchema ? "json_schema" : "framed_markdown",
+                outputMode: outputMode ?? "framed_markdown",
                 ...(options.ref ? { targetRef: options.ref } : {}),
                 allowRepair: repairAttempts === 0,
                 ...(options.chat ? { chat: options.chat } : {}),