@cortexkit/opencode-magic-context 0.49.15 → 0.49.16

package/dist/v2/{server-kmbarfmn.js → server-r9gjxcte.js}

@@ -10,9 +10,8 @@ import {
   withPrivilegedWriter2
 } from "./server-wafzvyhg.js";
 import {
-  bootQuietRemainingMs,
   scheduleAfterBootQuiet
-} from "./server-gvkm8xaj.js";
+} from "./server-e3ftpk7v.js";
 import {
   getHarness2,
   harnessOwnsOpenCodeStore2
@@ -40,8 +39,8 @@ import {
   configureContextDatabasePragmas2
 } from "./server-fb3zxn06.js";
 import {
-  startMessageFtsRowidMapBackfill
-} from "./server-yrvqaswb.js";
+  startMessageFtsRowidMapBackfill2
+} from "./server-785mb90s.js";
 import {
   LKG_SLOT_CHUNKS_DDL,
   SESSION_REPLAY_DECISIONS_DDL,
@@ -51,7 +50,7 @@ import {
   hasPendingMigrations,
   getMainThreadMigrationBodyCount,
   runMigrations
-} from "./server-k2bzedxk.js";
+} from "./server-00hx04yn.js";
 import {
   ensureColumn,
   installV95PerfSchema,
@@ -763,6 +762,8 @@ registerSlowWriteReporter2(logSlowWriteTransaction);
 registerSqliteDiagnosticSink2((message) => log2(message), getHarness2);
 var databases = new Map;
 var pendingAsyncOpens = new Map;
+var pendingDatabaseCloses = new Set;
+var startupBackfills = new WeakMap;
 var persistenceByDatabase = new WeakMap;
 var persistenceErrorByDatabase = new WeakMap;
 var pathByDatabase = new WeakMap;
@@ -1200,8 +1201,14 @@ function finishDatabaseOpen(db, dbPath, explicitDbPath, latestSupportedVersion)
   healWedgedChannel2Claims(db);
   if (!explicitDbPath) {
     const readsOpenCodeStore = harnessOwnsOpenCodeStore2();
+    const state = { controller: new AbortController };
+    startupBackfills.set(db, state);
+    const { signal } = state.controller;
     let busyRetryMs = 100;
     const runBackfills = () => withoutSqliteTransformPass2(() => withSqliteBackgroundWriter2(() => {
+      state.timer = undefined;
+      if (signal.aborted)
+        return;
       if (readsOpenCodeStore) {
         try {
           runToolOwnerBackfill(db);
@@ -1209,19 +1216,23 @@ function finishDatabaseOpen(db, dbPath, explicitDbPath, latestSupportedVersion)
           log2(`[magic-context] tool-owner backfill failed (continuing with lazy adoption fallback): ${getErrorMessage(error)}`);
         }
       }
-      startMessageFtsRowidMapBackfill(db).then(async () => {
-        if (!readsOpenCodeStore)
+      state.running = startMessageFtsRowidMapBackfill2(db, signal).then(async () => {
+        if (signal.aborted || !readsOpenCodeStore)
+          return;
+        const { readRawSessionMessagePage, readRawSessionMessages } = await importPluginModule(() => import("./read-session-chunk-7bpygfv2.js"));
+        const { startMessageTimeBackfill } = await importPluginModule(() => import("./message-time-backfill-q5pgxf0d.js"));
+        if (signal.aborted)
           return;
-        const { readRawSessionMessagePage, readRawSessionMessages } = await importPluginModule(() => import("./read-session-chunk-rq9nx1nn.js"));
-        const { startMessageTimeBackfill } = await importPluginModule(() => import("./message-time-backfill-bsteyc4d.js"));
         await startMessageTimeBackfill(db, Object.assign(readRawSessionMessages, {
           readPage: readRawSessionMessagePage
-        }));
+        }), signal);
       }).catch((error) => {
+        if (signal.aborted)
+          return;
         if (isTransientSqliteError2(error)) {
           withoutSqliteTransformPass2(() => {
-            const timer = setTimeout(runBackfills, busyRetryMs);
-            timer.unref();
+            state.timer = setTimeout(runBackfills, busyRetryMs);
+            state.timer.unref?.();
           });
           busyRetryMs = Math.min(30000, busyRetryMs * 2);
           return;
@@ -1229,10 +1240,7 @@ function finishDatabaseOpen(db, dbPath, explicitDbPath, latestSupportedVersion)
         log2(`[magic-context] message-index backfill failed (will resume next startup): ${getErrorMessage(error)}`);
       });
     }));
-    if (bootQuietRemainingMs() > 0)
-      scheduleAfterBootQuiet(runBackfills);
-    else
-      runBackfills();
+    state.timer = scheduleAfterBootQuiet(runBackfills);
   }
   setDatabase(db);
   loadToolDefinitionMeasurements(db);

package/dist/v2/{server-6cdy4rc0.js → server-vgpab6rd.js}

@@ -14,10 +14,10 @@ import {
 } from "./server-f2xf5gcb.js";
 import {
   managedAuthorityNoteRow
-} from "./server-k2bzedxk.js";
+} from "./server-00hx04yn.js";
 import {
   embedTextForProject2
-} from "./server-hek6z3w6.js";
+} from "./server-kr2kc9dz.js";
 import {
   saveEmbeddingIfHashMatches
 } from "./server-4dhv7mqz.js";

package/dist/v2/{server-zc3e54vy.js → server-y5pznjt9.js}

@@ -11,7 +11,7 @@ import {
   PER_HARNESS_MODEL_KEYS,
   ConfigProfilesSchema,
   MagicContextConfigSchema
-} from "./server-th4y11y7.js";
+} from "./server-271qxsf5.js";
 import {
   isCompactionEnabled,
   migrateLegacyAgentEnabledInMemory

package/dist/v2/server-zyw55ygv.js

@@ -0,0 +1,96 @@
+import {
+  withMessageFtsSessionFilter
+} from "./server-kaqs6h31.js";
+import {
+  getSqliteDatabasePath2
+} from "./server-wafzvyhg.js";
+import {
+  runSessionWarmupWorker
+} from "./server-6714jebr.js";
+import {
+  estimateTokens
+} from "./server-0ppsweh6.js";
+import {
+  openCodeDbExists,
+  withReadOnlySessionDb
+} from "./server-d8tj10db.js";
+import {
+  hasRawMessageProvider2,
+  readRawSessionMessageIdOrdinalsForRange2
+} from "./server-1hcbw661.js";
+
+// src/tools/ctx-expand/search-archive.ts
+var archiveReadsOnThisThread = 0;
+function renderSearchArchive2(db, sessionId, start, end, tokenBudget, archiveOnly = false, readRawIds = () => readRawSessionMessageIdOrdinalsForRange2(sessionId, start, end)) {
+  archiveReadsOnThisThread += 1;
+  return withMessageFtsSessionFilter(db, sessionId, (sessionFirst) => {
+    let rawIds;
+    const rows = db.prepare(sessionFirst ? `SELECT f.message_ordinal AS ordinal, f.message_id AS id, f.role, f.content
+                   FROM message_fts_rowid_map AS m
+                   JOIN message_history_fts AS f ON f.rowid = m.fts_rowid
+                   WHERE m.session_id = ?1 AND m.message_ordinal BETWEEN ?2 AND ?3
+                     AND f.session_id = ?1 AND f.message_ordinal BETWEEN ?2 AND ?3
+                   ORDER BY m.message_ordinal` : `SELECT message_ordinal AS ordinal, message_id AS id, role, content
+                   FROM message_history_fts
+                   WHERE session_id = ?1 AND message_ordinal BETWEEN ?2 AND ?3
+                   ORDER BY CAST(message_ordinal AS INTEGER)`);
+    const blocks = [];
+    let tokens = 0;
+    let lastOrdinal = start - 1;
+    let truncated = false;
+    for (const row of rows.iterate(sessionId, start, end)) {
+      if (!row.content)
+        continue;
+      if (!archiveOnly) {
+        rawIds ??= readRawIds();
+        if (rawIds.get(row.id) === row.ordinal)
+          continue;
+      }
+      const block = `[${row.ordinal}] ${row.role === "user" ? "U" : "A"}: ${row.content}`;
+      const cost = estimateTokens(block);
+      if (blocks.length > 0 && tokens + cost > tokenBudget) {
+        truncated = true;
+        break;
+      }
+      blocks.push(block);
+      tokens += cost;
+      lastOrdinal = row.ordinal;
+    }
+    if (blocks.length === 0)
+      return null;
+    const text = [
+      "From the search archive: indexed text only; no surrounding messages or tool output.",
+      "",
+      ...blocks
+    ];
+    if (truncated) {
+      text.push("", `Truncated at message ${lastOrdinal} (budget: ~${tokenBudget} tokens). Call ctx_expand(start=${lastOrdinal + 1}, end=${end}) for more archived text.`);
+    }
+    return text.join(`
+`);
+  });
+}
+async function renderSearchArchiveOffThread2(db, sessionId, start, end, tokenBudget, archiveOnly = false) {
+  const path = getSqliteDatabasePath2(db);
+  if (!path)
+    return renderSearchArchive2(db, sessionId, start, end, tokenBudget, archiveOnly);
+  const provider = hasRawMessageProvider2(sessionId);
+  const rawPath = !archiveOnly && !provider && openCodeDbExists() ? withReadOnlySessionDb(getSqliteDatabasePath2) : null;
+  const result = await runSessionWarmupWorker({
+    path,
+    sessionId,
+    searchArchive: {
+      start,
+      end,
+      tokenBudget,
+      archiveOnly,
+      rawPath,
+      rawIds: !archiveOnly && provider ? [...readRawSessionMessageIdOrdinalsForRange2(sessionId, start, end)] : undefined
+    }
+  }, {});
+  if ("searchArchive" in result)
+    return result.searchArchive;
+  throw new Error(`Search archive worker unavailable: ${"failure" in result ? `${result.failure}: ${result.detail}` : "unexpected reply"}`);
+}
+
+export { renderSearchArchive2, renderSearchArchiveOffThread2 };

package/dist/v2/server.js

@@ -1,6 +1,6 @@
 import {
   loadPluginConfigDetailed
-} from "./server-zc3e54vy.js";
+} from "./server-y5pznjt9.js";
 import {
   setHarness2
 } from "./server-pavzsdc6.js";
@@ -21,7 +21,7 @@ import {
   union,
   tuple,
   record
-} from "./server-th4y11y7.js";
+} from "./server-271qxsf5.js";
 import {
   pushNotification2
 } from "./server-x8a7jmkh.js";
@@ -7874,7 +7874,7 @@ var require_src2 = __commonJS(function(exports, module) {
 // package.json
 var package_default = {
   name: "@cortexkit/opencode-magic-context",
-  version: "0.49.15",
+  version: "0.49.16",
   type: "module",
   description: "OpenCode plugin for Magic Context — cross-session memory and context management",
   main: "dist/index.js",
@@ -8195,7 +8195,7 @@ async function setup(context) {
   if (claimStorageBackupWarningCheck() && isMagicContextStorageOutsideEngram(storageDir)) {
     log2(`[magic-context] Magic Context storage is at ${storageDir}, outside the folder Engram backs up (~/.local/share/cortexkit/magic-context). It is not included in CortexKit backups.`);
   }
-  const { registerContext } = await import("./context-4qczzck7.js");
+  const { registerContext } = await import("./context-acw1nhv8.js");
   setHarness2("opencode2");
   bindStaleBuildNotice({}, import.meta.url, "opencode2");
   const duties = await registerContext(context);

package/dist/v2/{storage-tags-hcc2adpf.js → storage-tags-hkwtbp3g.js}

@@ -61,7 +61,7 @@ import {
   adoptNullOwnerToolTag2,
   getCandidateToolOwners2,
   pickNearestPriorOwner2
-} from "./server-atbc19ab.js";
+} from "./server-0mzjjw3s.js";
 import"./server-1zx87sdm.js";
 import"./server-pwv4ezb0.js";
 import"./server-0ppsweh6.js";

package/dist/v2/{wrapup-orchestrator-65pwye0d.js → wrapup-orchestrator-x4xj1782.js}

@@ -19,16 +19,18 @@ import {
   registerActiveCompartmentRun,
   setRecompStarting2,
   setRecompTerminal2
-} from "./server-dd0tz6cn.js";
-import"./server-hek6z3w6.js";
+} from "./server-6fyp0v67.js";
+import"./server-kr2kc9dz.js";
 import"./server-0ppsweh6.js";
 import"./server-rrqpvwqd.js";
 import {
   inRootAsyncContext2
 } from "./server-wafzvyhg.js";
-import"./server-yrvqaswb.js";
-import"./server-qhfvvfxj.js";
-import"./server-e298hswg.js";
+import"./server-51779zs2.js";
+import"./server-6714jebr.js";
+import"./server-785mb90s.js";
+import"./server-kqpawe1a.js";
+import"./server-g59aatsz.js";
 import {
   getWrapupInProgressState,
   acquireWrapupInProgress,
@@ -37,33 +39,31 @@ import {
   getHistorianFailureState,
   clearEmergencyRecovery,
   prepareRawSessionOrdinals2
-} from "./server-ehyava47.js";
+} from "./server-1hcbw661.js";
 import"./server-pwv4ezb0.js";
-import"./server-kmbarfmn.js";
+import"./server-r9gjxcte.js";
 import"./server-1zx87sdm.js";
-import"./server-atbc19ab.js";
-import"./server-th4y11y7.js";
-import"./server-51779zs2.js";
-import"./server-prg55b7k.js";
+import"./server-0mzjjw3s.js";
+import"./server-271qxsf5.js";
 import"./server-2ra6pwf3.js";
 import"./server-d8tj10db.js";
 import"./server-zs8d0s3b.js";
 import"./server-fr0wbhdn.js";
-import"./server-k2bzedxk.js";
-import"./server-gvkm8xaj.js";
+import"./server-00hx04yn.js";
+import"./server-e3ftpk7v.js";
 import"./server-fb3zxn06.js";
-import"./server-6cdy4rc0.js";
+import"./server-vgpab6rd.js";
 import {
   pushNotification2
 } from "./server-x8a7jmkh.js";
 import"./server-05xjtq6c.js";
 import"./server-qt1qqasc.js";
-import"./server-4gn3z5an.js";
+import"./server-hgg55hde.js";
 import"./server-4dhv7mqz.js";
-import"./server-g10mdym6.js";
-import"./server-ef89gdsx.js";
+import"./server-gha9x4qq.js";
+import"./server-aavz8pm6.js";
 import"./server-n78avt2p.js";
-import"./server-zc3e54vy.js";
+import"./server-y5pznjt9.js";
 import"./server-tbe1femw.js";
 import"./server-34kwfsr4.js";
 import"./server-h0410h0v.js";

package/dist/{wrapup-orchestrator-28xzsj5q.js → wrapup-orchestrator-vj2tbp22.js}

@@ -1,42 +1,42 @@
 import {
   runManagedWrapup2
-} from "./index-mc1cqza6.js";
-import"./index-1vc7jrkg.js";
-import"./index-snp5wbge.js";
+} from "./index-v9asb16b.js";
+import"./index-v63beg1z.js";
+import"./index-ayym1x7f.js";
 import"./index-f71thw8j.js";
-import"./index-bxdg2nbt.js";
-import"./index-thvnpfsv.js";
+import"./index-wv9n2zcq.js";
+import"./index-p4vde22c.js";
 import"./index-sd3egckz.js";
-import"./index-3kdm78zp.js";
-import"./index-y1qysm3q.js";
+import"./index-9nkg2dzk.js";
+import"./index-qrahzcqv.js";
 import"./index-n78avt2p.js";
 import"./index-4dhv7mqz.js";
 import"./index-v10f1rjv.js";
-import"./index-dgs16axy.js";
+import"./index-b17m64g9.js";
 import"./index-qt1qqasc.js";
-import"./index-944w16m0.js";
-import"./index-mht7bq0z.js";
+import"./index-j6zw70pf.js";
+import"./index-nd7m2a5a.js";
 import"./index-1zx87sdm.js";
-import"./index-1d289pq2.js";
-import"./index-mmfa86mt.js";
-import"./index-v0p37hm2.js";
+import"./index-mtw9e71a.js";
 import"./index-x8a7jmkh.js";
 import"./index-y9f76s3f.js";
-import"./index-e20m7284.js";
-import"./index-1sarmj9z.js";
+import"./index-7b2cfmaz.js";
+import"./index-wgypt3cs.js";
 import"./index-saews2s3.js";
-import"./index-3kx0kg0f.js";
+import"./index-hehkf6zm.js";
 import"./index-fkx2qnvw.js";
-import"./index-yxycg7fs.js";
+import"./index-cj9g0j7a.js";
 import"./index-fb3zxn06.js";
 import"./index-wk0n1cgt.js";
 import"./index-a8bvhwqs.js";
-import"./index-dyvbsvga.js";
+import"./index-dqe8pq4x.js";
 import"./index-fr0wbhdn.js";
 import"./index-nj7yykkx.js";
 import"./index-n6m03s3n.js";
 import"./index-bp5083x2.js";
 import"./index-58e3y90n.js";
+import"./index-7pa32z07.js";
+import"./index-v0p37hm2.js";
 import"./index-k29z4aqh.js";
 import"./index-hqkczed7.js";
 import"./index-wafzvyhg.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/opencode-magic-context",
-  "version": "0.49.15",
+  "version": "0.49.16",
   "type": "module",
   "description": "OpenCode plugin for Magic Context — cross-session memory and context management",
   "main": "dist/index.js",

package/src/config/schema/magic-context.ts

@@ -205,12 +205,14 @@ export type OmpEntry = z.infer<typeof OmpEntrySchema>;
 /** Strict model-resolution block used by historian.opencode. */
 export const OpenCodeHarnessBlockSchema = z
     .object({
-        model: OcEntrySchema.optional().describe("Primary OpenCode model entry."),
+        model: OcEntrySchema.optional().describe(
+            "Primary historian OpenCode model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. When absent, OpenCode inherits the session model.",
+        ),
         fallback_models: z
             .array(OcEntrySchema)
             .optional()
             .describe(
-                "Ordered fallback OpenCode entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+                "Ordered historian fallback OpenCode entries. A configured primary never adds the session model after this list. Requires an array; legacy singleton values migrate to a one-element array.",
             ),
         variant: z
             .string()
@@ -226,12 +228,14 @@ export type OpenCodeHarnessBlock = z.infer<typeof OpenCodeHarnessBlockSchema>;
 /** Strict model-resolution block used by historian.pi. */
 export const PiHarnessBlockSchema = z
     .object({
-        model: PiEntrySchema.optional().describe("Primary Pi model entry."),
+        model: PiEntrySchema.optional().describe(
+            "Primary historian Pi model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. When absent, Pi does not run the historian.",
+        ),
         fallback_models: z
             .array(PiEntrySchema)
             .optional()
             .describe(
-                "Ordered fallback Pi entries. New-shape configuration requires an array; legacy singleton values migrate to a one-element array.",
+                "Ordered historian fallback Pi entries. The session model is never appended. Requires an array; legacy singleton values migrate to a one-element array.",
             ),
         thinking_level: PiThinkingLevelSchema.describe(
             "Pi thinking level for the primary entry when it declares none. Fallback entries declare thinking levels per-entry.",
@@ -244,11 +248,15 @@ export type PiHarnessBlock = z.infer<typeof PiHarnessBlockSchema>;
 /** Strict model-resolution block used by historian.omp. */
 export const OmpHarnessBlockSchema = z
     .object({
-        model: OmpEntrySchema.optional().describe("Primary OMP model entry."),
+        model: OmpEntrySchema.optional().describe(
+            "Primary historian OMP model entry. When set, only this model and fallback_models are used; exhaustion reports failure, never the session model. An absent OMP block inherits the Pi block; a selected block without a model does not run the historian.",
+        ),
         fallback_models: z
             .array(OmpEntrySchema)
             .optional()
-            .describe("Ordered fallback OMP entries."),
+            .describe(
+                "Ordered historian fallback OMP entries. The session model is never appended.",
+            ),
         thinking_level: OmpThinkingLevelSchema.describe(
             "OMP thinking level for the primary entry when it declares none. Fallback entries declare thinking levels per-entry.",
         ),

package/src/shared/model-resolution.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { parsePluginConfig } from "../config";
 
 import {
     normalizeModelEntry,
@@ -9,6 +10,27 @@ import {
 } from "./model-resolution";
 
 describe("model-resolution", () => {
+    test("loader defaults and historian metadata do not configure a primary model", () => {
+        for (const harness of ["opencode", "pi", "omp"] as const) {
+            for (const input of [
+                {},
+                { historian: {} },
+                { historian: { temperature: 0, [harness]: {} } },
+            ]) {
+                expect(
+                    resolveHistorianModel(parsePluginConfig(input), harness).primary,
+                ).toBeUndefined();
+            }
+            for (const model of [" provider/explicit ", { model: "provider/explicit" }]) {
+                expect(
+                    resolveHistorianModel(
+                        parsePluginConfig({ historian: { [harness]: { model } } }),
+                        harness,
+                    ).primary?.model,
+                ).toBe("provider/explicit");
+            }
+        }
+    });
     test("keeps historian temperature opt-in while preserving explicit overrides", () => {
         const fixtures = [
             { temperature: undefined, expected: undefined },

package/src/shared/model-suggestion-retry.ts

@@ -72,6 +72,8 @@ export interface PromptAttemptInfo {
 export interface PromptRetryOptions {
     transport?: PromptTransport;
     timeoutMs?: number;
+    /** False for callers whose configured model chain must not accept provider suggestions. Defaults to true. */
+    allowModelSuggestions?: boolean;
     /** External abort signal — cancels the in-flight LLM prompt immediately when aborted */
     signal?: AbortSignal;
     /**
@@ -508,6 +510,7 @@ async function attemptOnce(
     callContext: string,
     label: string,
     transport?: PromptTransport,
+    allowModelSuggestions = true,
 ): Promise<void> {
     // Keep this snapshot separate from the object passed to the client. A
     // failed prompt facade may rewrite its request body before rejecting; the
@@ -518,9 +521,9 @@ async function attemptOnce(
         await promptWithTimeout(client, attemptArgs, timeoutMs, signal, transport);
         return;
     } catch (error) {
-        // If non-retryable (abort, overflow, timeout), bubble up immediately.
-        // Don't even try suggestion retry — caller needs the original error.
-        if (isNonRetryable(error, signal)) throw error;
+        // Non-retryable failures and callers with model suggestions disabled
+        // must surface the original error without accepting a provider suggestion.
+        if (isNonRetryable(error, signal) || !allowModelSuggestions) throw error;
 
         const suggestion = parseModelSuggestion(error);
         if (!suggestion || !originalBody.model) {
@@ -596,6 +599,7 @@ export async function promptSyncWithModelSuggestionRetry(
             callContext,
             explicitPrimaryLabel,
             options.transport,
+            options.allowModelSuggestions,
         );
         return;
     } catch (error) {
@@ -640,6 +644,7 @@ export async function promptSyncWithModelSuggestionRetry(
                 callContext,
                 label,
                 options.transport,
+                options.allowModelSuggestions,
             );
             log(
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
@@ -685,6 +690,7 @@ async function attemptAndValidate<TOutput, TValidated>(
             callContext,
             attempt.label,
             options.transport,
+            options.allowModelSuggestions,
         );
     } catch (error) {
         throw {

package/src/shared/resolve-fallbacks.test.ts

@@ -4,9 +4,8 @@ import { modelBodyField, parseProviderModel, resolveFallbackChain } from "./reso
 
 describe("resolveFallbackChain", () => {
     // Policy: user-config-only. There is NO builtin provider-agnostic chain —
-    // when the user configures no fallback_models the result is EMPTY, and the
-    // runner's session-model last resort (a model the user actually has) is the
-    // only fallback. A hardcoded chain named providers the user may not have and
+    // when the user configures no fallback_models the result is empty.
+    // A hardcoded chain named providers the user may not have and
     // produced `Model not found` retry storms.
     test("returns empty when user provides nothing (no builtin chain)", () => {
         expect(resolveFallbackChain(undefined)).toEqual([]);

package/src/shared/resolve-fallbacks.ts

@@ -9,9 +9,9 @@ import type { ModelInput, ResolvedModelEntry } from "./model-resolution";
  * inevitably names providers the user doesn't have (e.g. a metapi-only user got
  * a chain of google/github-copilot/opencode entries, every one a
  * `Model not found` retry), which produced confusing errors and wasted
- * attempts. If the user configured nothing, this returns an empty list and the
- * runner's session-model last resort (the model the user is actually using) is
- * the only fallback.
+ * attempts. If the user configured no alternates, this returns an empty list.
+ * A configured historian never adds the session model to this list; only an
+ * unconfigured OpenCode historian inherits the session model.
  *
  * The returned list does NOT include the primary model — it's the ordered list
  * of *alternates* to try after the primary fails. Each entry is