@link-assistant/agent 0.19.2 → 0.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.19.2",
+  "version": "0.20.2",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/cli/argv.ts

@@ -4,15 +4,15 @@
  */
 
 /**
- * Extract a named argument directly from process.argv.
+ * Extract a named argument from an arbitrary argv-like array.
  * Supports --name=value, --name value, and optional short aliases (-x=value, -x value).
- * @returns The argument value from CLI or null if not found
+ * @returns The argument value or null if not found
  */
-function getArgFromProcessArgv(
+function extractArgFromArray(
+  args: string[],
   longFlag: string,
   shortFlag?: string
 ): string | null {
-  const args = process.argv;
   const longPrefix = `--${longFlag}=`;
   const shortPrefix = shortFlag ? `-${shortFlag}=` : null;
   for (let i = 0; i < args.length; i++) {
@@ -43,6 +43,38 @@ function getArgFromProcessArgv(
   return null;
 }
 
+/**
+ * Extract a named argument directly from process.argv, falling back to Bun.argv.
+ * Bun global installs and compiled binaries may have different process.argv structures
+ * (see oven-sh/bun#22157), so we check both sources. (#192, #239)
+ * @returns The argument value from CLI or null if not found
+ */
+function getArgFromProcessArgv(
+  longFlag: string,
+  shortFlag?: string
+): string | null {
+  // Try process.argv first (standard Node.js / Bun behavior)
+  const fromProcess = extractArgFromArray(process.argv, longFlag, shortFlag);
+  if (fromProcess !== null) {
+    return fromProcess;
+  }
+
+  // Fallback: try Bun.argv if available — Bun global installs may have
+  // different process.argv structure (extra elements, shifted indices) (#239)
+  if (typeof globalThis.Bun !== 'undefined' && globalThis.Bun.argv) {
+    const fromBun = extractArgFromArray(
+      globalThis.Bun.argv,
+      longFlag,
+      shortFlag
+    );
+    if (fromBun !== null) {
+      return fromBun;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Extract model argument directly from process.argv
  * This is a safeguard against yargs caching issues (#192)
@@ -69,3 +101,14 @@ export function getCompactionModelFromProcessArgv(): string | null {
 export function getCompactionSafetyMarginFromProcessArgv(): string | null {
   return getArgFromProcessArgv('compaction-safety-margin');
 }
+
+/**
+ * Extract --compaction-models argument directly from process.argv
+ * The value is a links notation references sequence, e.g.:
+ *   "(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)"
+ * @returns The compaction models argument from CLI or null if not found
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+export function getCompactionModelsFromProcessArgv(): string | null {
+  return getArgFromProcessArgv('compaction-models');
+}

package/src/cli/defaults.ts

@@ -6,7 +6,7 @@
  */
 
 /** Default model used when no `--model` CLI argument is provided. */
-export const DEFAULT_MODEL = 'opencode/minimax-m2.5-free';
+export const DEFAULT_MODEL = 'opencode/qwen3.6-plus-free';
 
 /** Default provider ID extracted from DEFAULT_MODEL. */
 export const DEFAULT_PROVIDER_ID = DEFAULT_MODEL.split('/')[0];
@@ -23,6 +23,29 @@ export const DEFAULT_MODEL_ID = DEFAULT_MODEL.split('/').slice(1).join('/');
  */
 export const DEFAULT_COMPACTION_MODEL = 'opencode/gpt-5-nano';
 
+/**
+ * Default compaction models cascade, ordered from smallest/cheapest context to largest.
+ * During compaction, the system tries each model in order. If the used context exceeds
+ * a model's context limit, it skips to the next larger model. If a model's rate limit
+ * is reached, it also skips to the next model.
+ * The special value "same" means use the same model as `--model`.
+ *
+ * Parsed as links notation references sequence (single anonymous link):
+ *   "(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)"
+ *
+ * Context limits (approximate):
+ *   big-pickle:            ~200K
+ *   nemotron-3-super-free: ~262K
+ *   minimax-m2.5-free:     ~200K
+ *   gpt-5-nano:            ~400K
+ *   qwen3.6-plus-free:     ~1M
+ *   same:                  (base model's context)
+ *
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+export const DEFAULT_COMPACTION_MODELS =
+  '(big-pickle nemotron-3-super-free minimax-m2.5-free gpt-5-nano qwen3.6-plus-free same)';
+
 /**
  * Default compaction safety margin as a percentage of usable context window.
  * Applied only when the compaction model has a context window equal to or smaller

package/src/cli/model-config.js

@@ -1,6 +1,7 @@
 import {
   getModelFromProcessArgv,
   getCompactionModelFromProcessArgv,
+  getCompactionModelsFromProcessArgv,
   getCompactionSafetyMarginFromProcessArgv,
 } from './argv.ts';
 import { Log } from '../util/log.ts';
@@ -8,6 +9,7 @@ import {
   DEFAULT_PROVIDER_ID,
   DEFAULT_MODEL_ID,
   DEFAULT_COMPACTION_MODEL,
+  DEFAULT_COMPACTION_MODELS,
   DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT,
 } from './defaults.ts';
 
@@ -19,12 +21,25 @@ import {
  * @returns {Promise<{providerID: string, modelID: string}>}
  */
 export async function parseModelConfig(argv, outputError, outputStatus) {
-  // Safeguard: validate argv.model against process.argv to detect yargs/cache mismatch (#192, #196)
+  // Safeguard: validate argv.model against process.argv to detect yargs/cache mismatch (#192, #196, #239)
   // This is critical because yargs under Bun may fail to parse --model correctly,
   // returning the default value instead of the user's CLI argument.
   const cliModelArg = getModelFromProcessArgv();
   let modelArg = argv.model;
 
+  // Diagnostic logging: always log raw argv sources when debugging model resolution (#239)
+  // Bun global installs may have different process.argv structure (oven-sh/bun#22157)
+  Log.Default.info(() => ({
+    message: 'model resolution: argv sources',
+    processArgv: process.argv,
+    bunArgv:
+      typeof globalThis.Bun !== 'undefined' && globalThis.Bun.argv
+        ? globalThis.Bun.argv
+        : '(not available)',
+    cliModelArg: cliModelArg ?? '(null - not found in argv)',
+    yargsModel: modelArg,
+  }));
+
   // ALWAYS prefer the CLI value over yargs when available (#196)
   // The yargs default (DEFAULT_MODEL) can silently override user's --model argument
   if (cliModelArg) {
@@ -39,6 +54,29 @@ export async function parseModelConfig(argv, outputError, outputStatus) {
     // Always use CLI value when available, even if it matches yargs
     // This ensures we use the actual CLI argument, not a cached/default yargs value
     modelArg = cliModelArg;
+  } else if (modelArg === `${DEFAULT_PROVIDER_ID}/${DEFAULT_MODEL_ID}`) {
+    // cliModelArg is null AND yargs returned the default — check if process.argv
+    // actually contains --model to detect silent yargs/Bun mismatch (#239)
+    const rawArgvStr = process.argv.join(' ');
+    if (
+      rawArgvStr.includes('--model ') ||
+      rawArgvStr.includes('--model=') ||
+      rawArgvStr.includes('-m ') ||
+      rawArgvStr.includes('-m=')
+    ) {
+      Log.Default.error(() => ({
+        message:
+          'CRITICAL: --model flag detected in process.argv but both getModelFromProcessArgv() and yargs returned default. ' +
+          'This is likely a Bun/yargs argument parsing bug (oven-sh/bun#22157). ' +
+          'The requested model will NOT be used — the default model will be used instead.',
+        processArgv: process.argv,
+        bunArgv:
+          typeof globalThis.Bun !== 'undefined' && globalThis.Bun.argv
+            ? globalThis.Bun.argv
+            : '(not available)',
+        defaultModel: `${DEFAULT_PROVIDER_ID}/${DEFAULT_MODEL_ID}`,
+      }));
+    }
   }
 
   let providerID;
@@ -71,26 +109,41 @@ export async function parseModelConfig(argv, outputError, outputStatus) {
     // Validate that the model exists in the provider (#196, #231)
     // If user explicitly specified provider/model and the model is not found,
     // fail immediately instead of silently falling back to a different model.
+    // However, if the model is the default (no --model CLI flag), warn but proceed (#239).
+    // The models.dev API may lag behind the provider's actual model availability.
+    const isDefaultModel = !cliModelArg;
     try {
       const { Provider } = await import('../provider/provider.ts');
       const s = await Provider.state();
       const provider = s.providers[providerID];
       if (provider && !provider.info.models[modelID]) {
-        // Provider exists but model doesn't — fail with a clear error (#231)
-        // Silent fallback caused kimi-k2.5-free to be routed to minimax-m2.5-free
         const availableModels = Object.keys(provider.info.models).slice(0, 10);
-        Log.Default.error(() => ({
-          message:
-            'model not found in provider — refusing to proceed with explicit provider/model',
-          providerID,
-          modelID,
-          availableModels,
-        }));
-        throw new Error(
-          `Model "${modelID}" not found in provider "${providerID}". ` +
-            `Available models include: ${availableModels.join(', ')}. ` +
-            `Use --model ${providerID}/<model-id> with a valid model, or omit the provider prefix for auto-resolution.`
-        );
+        if (isDefaultModel) {
+          // Default model not in models.dev catalog — warn but proceed (#239)
+          // The provider may still accept it; models.dev can lag behind actual availability.
+          Log.Default.warn(() => ({
+            message:
+              'default model not found in models.dev catalog — proceeding anyway',
+            providerID,
+            modelID,
+            availableModels,
+          }));
+        } else {
+          // User explicitly specified provider/model — fail with a clear error (#231)
+          // Silent fallback caused kimi-k2.5-free to be routed to minimax-m2.5-free
+          Log.Default.error(() => ({
+            message:
+              'model not found in provider — refusing to proceed with explicit provider/model',
+            providerID,
+            modelID,
+            availableModels,
+          }));
+          throw new Error(
+            `Model "${modelID}" not found in provider "${providerID}". ` +
+              `Available models include: ${availableModels.join(', ')}. ` +
+              `Use --model ${providerID}/<model-id> with a valid model, or omit the provider prefix for auto-resolution.`
+          );
+        }
       }
     } catch (validationError) {
       // Re-throw if this is our own validation error (not an infrastructure issue)
@@ -173,20 +226,71 @@ export async function parseModelConfig(argv, outputError, outputStatus) {
   return { providerID, modelID, compactionModel: compactionModelResult };
 }
 
+/**
+ * Parse a links notation references sequence string into an array of model names.
+ * Format: "(model1 model2 model3)" — parenthesized space-separated list.
+ * @param {string} notation - Links notation sequence string
+ * @returns {string[]} Array of model name strings
+ * @see https://github.com/link-assistant/agent/issues/232
+ */
+function parseLinksNotationSequence(notation) {
+  const trimmed = notation.trim();
+  // Remove surrounding parentheses if present
+  const inner =
+    trimmed.startsWith('(') && trimmed.endsWith(')')
+      ? trimmed.slice(1, -1)
+      : trimmed;
+  // Split on whitespace and filter empty strings
+  return inner.split(/\s+/).filter((s) => s.length > 0);
+}
+
+/**
+ * Resolve a single compaction model entry (short name, provider/model, or "same").
+ * @returns {{ providerID: string, modelID: string, useSameModel: boolean }}
+ */
+async function resolveCompactionModelEntry(
+  modelArg,
+  baseProviderID,
+  baseModelID
+) {
+  const useSameModel = modelArg.toLowerCase() === 'same';
+
+  if (useSameModel) {
+    return {
+      providerID: baseProviderID,
+      modelID: baseModelID,
+      useSameModel: true,
+    };
+  }
+
+  if (modelArg.includes('/')) {
+    const parts = modelArg.split('/');
+    return {
+      providerID: parts[0],
+      modelID: parts.slice(1).join('/'),
+      useSameModel: false,
+    };
+  }
+
+  // Short name resolution
+  const { Provider } = await import('../provider/provider.ts');
+  const resolved = await Provider.parseModelWithResolution(modelArg);
+  return {
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    useSameModel: false,
+  };
+}
+
 /**
  * Parse compaction model config from argv.
- * Resolves --compaction-model and --compaction-safety-margin CLI arguments.
+ * Supports both --compaction-model (single) and --compaction-models (cascade).
+ * When --compaction-models is specified, it overrides --compaction-model.
  * The special value "same" means use the base model for compaction.
  * @see https://github.com/link-assistant/agent/issues/219
+ * @see https://github.com/link-assistant/agent/issues/232
  */
 async function parseCompactionModelConfig(argv, baseProviderID, baseModelID) {
-  // Get compaction model from CLI (safeguard against yargs caching)
-  const cliCompactionModelArg = getCompactionModelFromProcessArgv();
-  const compactionModelArg =
-    cliCompactionModelArg ??
-    argv['compaction-model'] ??
-    DEFAULT_COMPACTION_MODEL;
-
   // Get safety margin from CLI
   const cliSafetyMarginArg = getCompactionSafetyMarginFromProcessArgv();
   const compactionSafetyMarginPercent = cliSafetyMarginArg
@@ -194,49 +298,97 @@ async function parseCompactionModelConfig(argv, baseProviderID, baseModelID) {
     : (argv['compaction-safety-margin'] ??
       DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT);
 
-  // Special "same" alias — use the base model for compaction
-  const useSameModel = compactionModelArg.toLowerCase() === 'same';
+  // Check for --compaction-models (cascade) first — it overrides --compaction-model
+  const cliCompactionModelsArg = getCompactionModelsFromProcessArgv();
+  const compactionModelsArg =
+    cliCompactionModelsArg ??
+    argv['compaction-models'] ??
+    DEFAULT_COMPACTION_MODELS;
 
-  let compactionProviderID;
-  let compactionModelID;
+  // Parse the links notation sequence into an array of model names
+  const modelNames = parseLinksNotationSequence(compactionModelsArg);
+
+  if (modelNames.length > 0) {
+    // Resolve each model in the cascade
+    const compactionModels = [];
+    for (const name of modelNames) {
+      try {
+        const resolved = await resolveCompactionModelEntry(
+          name,
+          baseProviderID,
+          baseModelID
+        );
+        compactionModels.push({
+          providerID: resolved.providerID,
+          modelID: resolved.modelID,
+          useSameModel: resolved.useSameModel,
+        });
+      } catch (err) {
+        // If a model can't be resolved, log and skip it
+        Log.Default.warn(() => ({
+          message: 'skipping unresolvable compaction model in cascade',
+          model: name,
+          error: err?.message,
+        }));
+      }
+    }
 
-  if (useSameModel) {
-    compactionProviderID = baseProviderID;
-    compactionModelID = baseModelID;
-    Log.Default.info(() => ({
-      message:
-        'compaction model set to "same" — using base model for compaction',
-      compactionProviderID,
-      compactionModelID,
-    }));
-  } else if (compactionModelArg.includes('/')) {
-    const parts = compactionModelArg.split('/');
-    compactionProviderID = parts[0];
-    compactionModelID = parts.slice(1).join('/');
-    Log.Default.info(() => ({
-      message: 'using explicit compaction model',
-      compactionProviderID,
-      compactionModelID,
-    }));
-  } else {
-    // Short name resolution
-    const { Provider } = await import('../provider/provider.ts');
-    const resolved =
-      await Provider.parseModelWithResolution(compactionModelArg);
-    compactionProviderID = resolved.providerID;
-    compactionModelID = resolved.modelID;
     Log.Default.info(() => ({
-      message: 'resolved short compaction model name',
-      input: compactionModelArg,
-      compactionProviderID,
-      compactionModelID,
+      message: 'compaction models cascade configured',
+      models: compactionModels.map((m) =>
+        m.useSameModel ? 'same' : `${m.providerID}/${m.modelID}`
+      ),
+      source: cliCompactionModelsArg ? 'cli' : 'default',
     }));
+
+    // Use the first model as the primary compaction model (for backward compatibility)
+    // The full cascade is stored in compactionModels array
+    const primary = compactionModels[0] || {
+      providerID: baseProviderID,
+      modelID: baseModelID,
+      useSameModel: true,
+    };
+
+    return {
+      providerID: primary.providerID,
+      modelID: primary.modelID,
+      useSameModel: primary.useSameModel,
+      compactionSafetyMarginPercent,
+      compactionModels,
+    };
   }
 
+  // Fallback to single --compaction-model
+  const cliCompactionModelArg = getCompactionModelFromProcessArgv();
+  const compactionModelArg =
+    cliCompactionModelArg ??
+    argv['compaction-model'] ??
+    DEFAULT_COMPACTION_MODEL;
+
+  const resolved = await resolveCompactionModelEntry(
+    compactionModelArg,
+    baseProviderID,
+    baseModelID
+  );
+
+  Log.Default.info(() => ({
+    message: 'using single compaction model',
+    compactionProviderID: resolved.providerID,
+    compactionModelID: resolved.modelID,
+    useSameModel: resolved.useSameModel,
+  }));
+
   return {
-    providerID: compactionProviderID,
-    modelID: compactionModelID,
-    useSameModel,
+    providerID: resolved.providerID,
+    modelID: resolved.modelID,
+    useSameModel: resolved.useSameModel,
     compactionSafetyMarginPercent,
+    compactionModels: [
+      {
+        providerID: resolved.providerID,
+        modelID: resolved.modelID,
+        useSameModel: resolved.useSameModel,
+      },
+    ],
   };
 }

package/src/cli/run-options.js

@@ -1,6 +1,7 @@
 import {
   DEFAULT_MODEL,
   DEFAULT_COMPACTION_MODEL,
+  DEFAULT_COMPACTION_MODELS,
   DEFAULT_COMPACTION_SAFETY_MARGIN_PERCENT,
 } from './defaults.ts';
 
@@ -151,9 +152,17 @@ export function buildRunOptions(yargs) {
     .option('compaction-model', {
       type: 'string',
       description:
-        'Model to use for context compaction in format providerID/modelID. Use "same" to use the base model. Default: opencode/gpt-5-nano (free, 400K context).',
+        'Model to use for context compaction in format providerID/modelID. Use "same" to use the base model. Default: opencode/gpt-5-nano (free, 400K context). Overridden by --compaction-models if both are specified.',
       default: DEFAULT_COMPACTION_MODEL,
     })
+    .option('compaction-models', {
+      type: 'string',
+      description:
+        'Ordered cascade of compaction models in links notation sequence format: "(model1 model2 ... same)". ' +
+        "Models are tried from smallest/cheapest context to largest. If used context exceeds a model's limit or its rate limit is reached, the next model is tried. " +
+        'The special value "same" uses the base model. Overrides --compaction-model when specified.',
+      default: DEFAULT_COMPACTION_MODELS,
+    })
     .option('compaction-safety-margin', {
       type: 'number',
       description:

package/src/index.js

@@ -87,12 +87,22 @@ process.stderr.write = function (chunk, encoding, callback) {
     }
   }
 
-  // Wrap non-JSON stderr output in JSON envelope
-  const wrapped = `${JSON.stringify({
-    type: 'error',
-    errorType: 'RuntimeError',
-    message: trimmed,
-  })}\n`;
+  // Wrap non-JSON stderr output in JSON envelope.
+  // Verbose/debug messages should use "type": "log", not "type": "error" (#235).
+  const isVerboseMsg =
+    trimmed.startsWith('[verbose]') || trimmed.startsWith('[debug]');
+  const wrapped = isVerboseMsg
+    ? `${JSON.stringify({
+        type: 'log',
+        level: 'debug',
+        service: 'stderr',
+        message: trimmed,
+      })}\n`
+    : `${JSON.stringify({
+        type: 'error',
+        errorType: 'RuntimeError',
+        message: trimmed,
+      })}\n`;
   return originalStderrWrite(wrapped, encoding, callback);
 };
 

package/src/provider/models.ts

@@ -7,7 +7,12 @@ import { data } from './models-macro';
 
 export namespace ModelsDev {
   const log = Log.create({ service: 'models.dev' });
-  const verboseFetch = createVerboseFetch(fetch, { caller: 'models.dev' });
+  const verboseFetch = createVerboseFetch(fetch, {
+    caller: 'models.dev',
+    // models.dev/api.json response can be 200KB+; logging the full body
+    // crashes the subprocess in CI (#239). Keep preview small.
+    responseBodyMaxChars: 2000,
+  });
   const filepath = path.join(Global.Path.cache, 'models.json');
 
   export const Model = z

package/src/provider/provider.ts

@@ -1241,17 +1241,13 @@ export namespace Provider {
 
           // Log a one-time confirmation that the verbose wrapper is active for this provider.
           // This diagnostic breadcrumb confirms the wrapper is in the fetch chain.
-          // Also write to stderr as a redundant channel — stdout JSON may be filtered by wrappers.
           // See: https://github.com/link-assistant/agent/issues/215
+          // See: https://github.com/link-assistant/agent/issues/235
           if (!verboseWrapperConfirmed) {
             verboseWrapperConfirmed = true;
-            log.info('verbose HTTP logging active', {
+            log.debug('verbose HTTP logging active', {
               providerID: provider.id,
             });
-            // Redundant stderr confirmation — visible even if stdout is piped/filtered
-            process.stderr.write(
-              `[verbose] HTTP logging active for provider: ${provider.id}\n`
-            );
           }
 
           const url =
@@ -1623,30 +1619,51 @@ export namespace Provider {
     }
 
     if (!isSyntheticProvider && !info) {
-      // Model not found even after cache refresh — fail with a clear error (#231)
-      // Previously this created synthetic fallback info, which allowed the API call
-      // to proceed with the wrong model (e.g., kimi-k2.5-free routed to minimax-m2.5-free)
+      // Model not found even after cache refresh.
+      // Check if this is the default model — if so, create synthetic info and proceed (#239).
+      // The models.dev API can lag behind the provider's actual model availability.
+      // For user-specified models, fail with a clear error (#231) to prevent silent substitution.
+      const { DEFAULT_PROVIDER_ID, DEFAULT_MODEL_ID } =
+        await import('../cli/defaults.ts');
+      const isDefaultModel =
+        providerID === DEFAULT_PROVIDER_ID && modelID === DEFAULT_MODEL_ID;
       const availableInProvider = Object.keys(provider.info.models).slice(
         0,
         10
       );
-      log.error(() => ({
-        message:
-          'model not found in provider catalog after refresh — refusing to proceed',
-        providerID,
-        modelID,
-        availableModels: availableInProvider,
-        totalModels: Object.keys(provider.info.models).length,
-      }));
 
-      throw new ModelNotFoundError({
-        providerID,
-        modelID,
-        suggestion:
-          `Model "${modelID}" not found in provider "${providerID}" (checked ${Object.keys(provider.info.models).length} models). ` +
-          `Available models include: ${availableInProvider.join(', ')}. ` +
-          `Use --model ${providerID}/<model-id> with a valid model.`,
-      });
+      if (isDefaultModel) {
+        // Default model not in models.dev catalog — create synthetic info and try anyway (#239)
+        log.warn(() => ({
+          message:
+            'default model not in provider catalog — creating synthetic info to proceed',
+          providerID,
+          modelID,
+          availableModels: availableInProvider,
+        }));
+        info = {
+          id: modelID,
+          name: modelID,
+        } as typeof info;
+      } else {
+        log.error(() => ({
+          message:
+            'model not found in provider catalog after refresh — refusing to proceed',
+          providerID,
+          modelID,
+          availableModels: availableInProvider,
+          totalModels: Object.keys(provider.info.models).length,
+        }));
+
+        throw new ModelNotFoundError({
+          providerID,
+          modelID,
+          suggestion:
+            `Model "${modelID}" not found in provider "${providerID}" (checked ${Object.keys(provider.info.models).length} models). ` +
+            `Available models include: ${availableInProvider.join(', ')}. ` +
+            `Use --model ${providerID}/<model-id> with a valid model.`,
+        });
+      }
     }
 
     try {
@@ -1731,7 +1748,13 @@ export namespace Provider {
       priority = priority.filter((m) => m !== 'claude-haiku-4.5');
     }
     if (providerID === 'opencode' || providerID === 'local') {
-      priority = ['minimax-m2.5-free', 'gpt-5-nano', 'big-pickle'];
+      priority = [
+        'qwen3.6-plus-free',
+        'minimax-m2.5-free',
+        'gpt-5-nano',
+        'nemotron-3-super-free',
+        'big-pickle',
+      ];
     }
     if (providerID === 'kilo') {
       priority = [
@@ -1758,7 +1781,9 @@ export namespace Provider {
   }
 
   const priority = [
+    'qwen3.6-plus-free',
     'glm-5-free',
+    'nemotron-3-super-free',
     'minimax-m2.5-free',
     'gpt-5-nano',
     'big-pickle',
@@ -1841,7 +1866,7 @@ export namespace Provider {
    * 1. If model is uniquely available in one provider, use that provider
    * 2. If model is available in multiple providers, prioritize based on free model availability:
    *    - kilo: glm-5-free, glm-4.5-air-free, minimax-m2.5-free, giga-potato-free, deepseek-r1-free (unique to Kilo)
-   *    - opencode: big-pickle, gpt-5-nano (unique to OpenCode)
+   *    - opencode: big-pickle, gpt-5-nano, qwen3.6-plus-free, nemotron-3-super-free (unique to OpenCode)
    * 3. For shared models, prefer OpenCode first, then fall back to Kilo on rate limit
    *
    * @param modelID - Short model name without provider prefix

package/src/session/compaction.ts

@@ -36,15 +36,35 @@ export namespace SessionCompaction {
    */
   export const OVERFLOW_SAFETY_MARGIN = 0.85;
 
+  /**
+   * A single compaction model entry in the cascade.
+   * @see https://github.com/link-assistant/agent/issues/232
+   */
+  export interface CompactionModelEntry {
+    providerID: string;
+    modelID: string;
+    useSameModel: boolean;
+  }
+
   /**
    * Compaction model configuration passed from CLI.
+   * Supports both single model (backward compat) and cascade of models (#232).
    * @see https://github.com/link-assistant/agent/issues/219
+   * @see https://github.com/link-assistant/agent/issues/232
    */
   export interface CompactionModelConfig {
     providerID: string;
     modelID: string;
     useSameModel: boolean;
     compactionSafetyMarginPercent: number;
+    /**
+     * Ordered cascade of compaction models from smallest/cheapest to largest.
+     * When present, the system tries each model in order during compaction.
+     * If used context exceeds a model's limit or its rate limit is reached,
+     * the next model is tried.
+     * @see https://github.com/link-assistant/agent/issues/232
+     */
+    compactionModels?: CompactionModelEntry[];
   }
 
   /**

package/src/session/message-v2.ts

@@ -398,6 +398,15 @@ export namespace MessageV2 {
         modelID: z.string(),
         useSameModel: z.boolean(),
         compactionSafetyMarginPercent: z.number(),
+        compactionModels: z
+          .array(
+            z.object({
+              providerID: z.string(),
+              modelID: z.string(),
+              useSameModel: z.boolean(),
+            })
+          )
+          .optional(),
       })
       .optional(),
     system: z.string().optional(),

package/src/session/prompt.ts

@@ -95,6 +95,15 @@ export namespace SessionPrompt {
         modelID: z.string(),
         useSameModel: z.boolean(),
         compactionSafetyMarginPercent: z.number(),
+        compactionModels: z
+          .array(
+            z.object({
+              providerID: z.string(),
+              modelID: z.string(),
+              useSameModel: z.boolean(),
+            })
+          )
+          .optional(),
       })
       .optional(),
     agent: z.string().optional(),
@@ -295,15 +304,30 @@ export namespace SessionPrompt {
         // continue the loop to execute them instead of prematurely exiting.
         // See: https://github.com/link-assistant/agent/issues/194
         if (lastAssistant.finish === 'unknown') {
+          // First check for tool calls BEFORE checking zero tokens (#239)
+          // Some providers (e.g., OpenCode Zen / OpenRouter) return zero tokens and
+          // unknown finish reason even when the model successfully executed tool calls.
+          // We must check for tool calls first to avoid prematurely terminating
+          // a session that is actually making progress.
+          const lastAssistantParts = msgs.find(
+            (m) => m.info.id === lastAssistant.id
+          )?.parts;
+          const hasToolCalls = lastAssistantParts?.some(
+            (p) =>
+              p.type === 'tool' &&
+              (p.state.status === 'completed' || p.state.status === 'running')
+          );
+
           // SAFETY CHECK for issue #196: Detect zero-token responses as provider failures
           // When all tokens are 0 and finish reason is 'unknown', this indicates the provider
           // returned an empty/error response (e.g., rate limit, model unavailable, API failure).
-          // Log a clear error message so the problem is visible in logs.
+          // But ONLY treat this as fatal if there are NO tool calls (#239).
           const tokens = lastAssistant.tokens;
           if (
             tokens.input === 0 &&
             tokens.output === 0 &&
-            tokens.reasoning === 0
+            tokens.reasoning === 0 &&
+            !hasToolCalls
           ) {
             const errorMessage =
               `Provider returned zero tokens with unknown finish reason. ` +
@@ -331,20 +355,13 @@ export namespace SessionPrompt {
             break;
           }
 
-          const lastAssistantParts = msgs.find(
-            (m) => m.info.id === lastAssistant.id
-          )?.parts;
-          const hasToolCalls = lastAssistantParts?.some(
-            (p) =>
-              p.type === 'tool' &&
-              (p.state.status === 'completed' || p.state.status === 'running')
-          );
           if (hasToolCalls) {
             log.info(() => ({
               message:
                 'continuing loop despite unknown finish reason - tool calls detected',
               sessionID,
               finishReason: lastAssistant.finish,
+              zeroTokens: tokens.input === 0 && tokens.output === 0,
               hint: 'Provider returned undefined finishReason but made tool calls',
             }));
             // Don't break - continue the loop to handle tool call results
@@ -542,27 +559,109 @@ export namespace SessionPrompt {
 
       // pending compaction
       if (task?.type === 'compaction') {
-        // Use compaction model if configured, otherwise fall back to base model
+        // Use compaction model cascade if configured (#232)
         const compactionModelConfig = lastUser.compactionModel;
-        const compactionProviderID =
-          compactionModelConfig && !compactionModelConfig.useSameModel
-            ? compactionModelConfig.providerID
-            : model.providerID;
-        const compactionModelID =
-          compactionModelConfig && !compactionModelConfig.useSameModel
-            ? compactionModelConfig.modelID
-            : model.modelID;
-        const result = await SessionCompaction.process({
-          messages: msgs,
-          parentID: lastUser.id,
-          abort,
-          model: {
-            providerID: compactionProviderID,
-            modelID: compactionModelID,
-          },
-          sessionID,
-        });
-        if (result === 'stop') break;
+        const cascade = compactionModelConfig?.compactionModels;
+
+        if (cascade && cascade.length > 0) {
+          // Cascade logic: try each model in order (smallest to largest context)
+          // Skip models whose context limit is smaller than current used tokens
+          // Skip models that hit rate limits (try next)
+          const currentTokens = lastFinished
+            ? lastFinished.tokens.input +
+              lastFinished.tokens.cache.read +
+              lastFinished.tokens.output
+            : 0;
+
+          let compactionResult = 'stop';
+          for (const entry of cascade) {
+            const entryProviderID = entry.useSameModel
+              ? model.providerID
+              : entry.providerID;
+            const entryModelID = entry.useSameModel
+              ? model.modelID
+              : entry.modelID;
+
+            // Check if this model's context is large enough for the current tokens
+            if (!entry.useSameModel) {
+              try {
+                const entryModel = await Provider.getModel(
+                  entryProviderID,
+                  entryModelID
+                );
+                const entryContextLimit = entryModel.info?.limit?.context ?? 0;
+                if (
+                  entryContextLimit > 0 &&
+                  currentTokens > entryContextLimit
+                ) {
+                  log.info(() => ({
+                    message:
+                      'skipping compaction model — context too small for current tokens',
+                    modelID: entryModelID,
+                    providerID: entryProviderID,
+                    contextLimit: entryContextLimit,
+                    currentTokens,
+                  }));
+                  continue;
+                }
+              } catch {
+                log.info(() => ({
+                  message:
+                    'could not resolve compaction cascade model — skipping',
+                  modelID: entryModelID,
+                  providerID: entryProviderID,
+                }));
+                continue;
+              }
+            }
+
+            try {
+              compactionResult = await SessionCompaction.process({
+                messages: msgs,
+                parentID: lastUser.id,
+                abort,
+                model: {
+                  providerID: entryProviderID,
+                  modelID: entryModelID,
+                },
+                sessionID,
+              });
+              // If compaction succeeded, break the cascade
+              break;
+            } catch (err) {
+              // If rate limited or error, try next model in cascade
+              log.warn(() => ({
+                message: 'compaction model failed — trying next in cascade',
+                modelID: entryModelID,
+                providerID: entryProviderID,
+                error: err?.message,
+              }));
+              continue;
+            }
+          }
+          if (compactionResult === 'stop') break;
+        } else {
+          // Single model fallback (backward compatibility)
+          const compactionProviderID =
+            compactionModelConfig && !compactionModelConfig.useSameModel
+              ? compactionModelConfig.providerID
+              : model.providerID;
+          const compactionModelID =
+            compactionModelConfig && !compactionModelConfig.useSameModel
+              ? compactionModelConfig.modelID
+              : model.modelID;
+          const result = await SessionCompaction.process({
+            messages: msgs,
+            parentID: lastUser.id,
+            abort,
+            model: {
+              providerID: compactionProviderID,
+              modelID: compactionModelID,
+            },
+            sessionID,
+          });
+          if (result === 'stop') break;
+        }
         continue;
       }
 

package/src/storage/storage.ts

@@ -22,8 +22,15 @@ export namespace Storage {
 
   const MIGRATIONS: Migration[] = [
     async (dir) => {
-      const project = path.resolve(dir, '../project');
-      if (!fs.exists(project)) return;
+      // Sanitize path: strip null bytes that may appear in Bun runtime path operations (#239)
+      const project = path.resolve(dir, '../project').replace(/\0/g, '');
+      if (
+        !(await fs
+          .stat(project)
+          .then((s) => s.isDirectory())
+          .catch(() => false))
+      )
+        return;
       for await (const projectDir of new Bun.Glob('*').scan({
         cwd: project,
         onlyFiles: false,
@@ -45,7 +52,13 @@ export namespace Storage {
             if (worktree) break;
           }
           if (!worktree) continue;
-          if (!(await fs.exists(worktree))) continue;
+          if (
+            !(await fs
+              .stat(worktree)
+              .then((s) => s.isDirectory())
+              .catch(() => false))
+          )
+            continue;
           const [id] = await $`git rev-list --max-parents=0 --all`
             .quiet()
             .nothrow()
@@ -174,8 +187,8 @@ export namespace Storage {
   const state = lazy(async () => {
     const dir = path.join(Global.Path.data, 'storage');
     const migration = await Bun.file(path.join(dir, 'migration'))
-      .json()
-      .then((x) => parseInt(x))
+      .text()
+      .then((x) => parseInt(x.trim(), 10))
       .catch(() => 0);
     for (let index = migration; index < MIGRATIONS.length; index++) {
       log.info(() => ({ message: 'running migration', index }));

package/src/util/verbose-fetch.ts

@@ -79,7 +79,7 @@ export function sanitizeHeaders(
  */
 export function bodyPreview(
   body: BodyInit | null | undefined,
-  maxChars = 200000
+  maxChars = 4000
 ): string | undefined {
   if (!body) return undefined;
 
@@ -128,8 +128,8 @@ export function createVerboseFetch(
 ): typeof fetch {
   const {
     caller,
-    responseBodyMaxChars = 200000,
-    requestBodyMaxChars = 200000,
+    responseBodyMaxChars = 4000,
+    requestBodyMaxChars = 4000,
   } = options;
 
   return async (
@@ -330,10 +330,15 @@ export function resetHttpCallCount(): void {
 export function registerPendingStreamLogExitHandler(): void {
   process.once('exit', () => {
     if (pendingStreamLogs > 0) {
-      // Use stderr directly since the process is exiting and log infrastructure may be unavailable
-      process.stderr.write(
-        `[verbose] warning: ${pendingStreamLogs} HTTP stream response log(s) were still pending at process exit — response bodies may be missing from logs\n`
-      );
+      // Use stderr directly since the process is exiting and log infrastructure may be unavailable.
+      // Write as JSON to avoid the stderr interceptor wrapping it as "type": "error" (#235).
+      const warning = JSON.stringify({
+        type: 'log',
+        level: 'warn',
+        service: 'http',
+        message: `${pendingStreamLogs} HTTP stream response log(s) were still pending at process exit — response bodies may be missing from logs`,
+      });
+      process.stderr.write(warning + '\n');
     }
   });
 }