amicus 1.0.0

package/src/utils/config.js

@@ -0,0 +1,291 @@
+/**
+ * Amicus Config Module
+ *
+ * Config directory resolution, file I/O, model alias resolution,
+ * config hashing, and alias table formatting.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { applyDirectApiFallback, autoRepairAlias } = require('./alias-resolver');
+const { getCompatEnv } = require('./env-compat');
+
+/** Default model alias map — derived from the curated-models single source (F5) */
+const { toDefaultAliases } = require('./curated-models');
+const DEFAULT_ALIASES = toDefaultAliases();
+
+/** @returns {string} Config directory path */
+function getConfigDir() {
+  const override = getCompatEnv('CONFIG_DIR');
+  if (override) {
+    const resolved = path.resolve(override);
+    if (resolved.includes('\0')) {
+      throw new Error('Invalid AMICUS_CONFIG_DIR: null bytes not allowed');
+    }
+    return resolved;
+  }
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const amicusDir = path.join(homeDir, '.config', 'amicus');
+  // DEPRECATED(amicus-shim): fall back to the legacy ~/.config/sidecar dir if it
+  // exists and the new one does not, so pre-rebrand credentials keep working.
+  // Remove in a future revision — see docs/SHIMS.md.
+  if (!fs.existsSync(amicusDir)) {
+    const legacyDir = path.join(homeDir, '.config', 'sidecar');
+    if (fs.existsSync(legacyDir)) {
+      return legacyDir;
+    }
+  }
+  return amicusDir;
+}
+
+/** @returns {string} Full path to config.json */
+function getConfigPath() {
+  return path.join(getConfigDir(), 'config.json');
+}
+
+/** @returns {object|null} Parsed config data, or null if missing/invalid */
+function loadConfig() {
+  const configPath = getConfigPath();
+  try {
+    if (!fs.existsSync(configPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(configPath, 'utf-8');
+    if (!content || content.trim().length === 0) {
+      return null;
+    }
+    return JSON.parse(content);
+  } catch (_err) {
+    return null;
+  }
+}
+
+/** Save config data to disk, creating the directory if needed. Strips invalid aliases. */
+function saveConfig(configData) {
+  if (configData && configData.aliases) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(configData.aliases)) {
+      if (key === 'null' || !value || typeof value !== 'string' || value === 'null') {
+        process.stderr.write(
+          `Notice: Removing invalid alias '${key}' (value: ${JSON.stringify(value)}) from config.\n`
+        );
+        continue;
+      }
+      cleaned[key] = value;
+    }
+    configData.aliases = cleaned;
+  }
+  const configDir = getConfigDir();
+  fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+  const configPath = getConfigPath();
+  fs.writeFileSync(configPath, JSON.stringify(configData, null, 2), { mode: 0o600 });
+}
+
+/** @returns {object} Copy of the default alias map */
+function getDefaultAliases() {
+  return { ...DEFAULT_ALIASES };
+}
+
+/**
+ * Resolve a model argument to a full model identifier
+ *
+ * Resolution order:
+ * 1. If modelArg contains '/' -> return as-is (full model string)
+ * 2. If modelArg is a key in config.aliases -> return resolved string
+ * 3. If modelArg is unknown alias -> throw Error mentioning 'sidecar setup'
+ * 4. If modelArg is undefined and config.default exists -> resolve that alias
+ * 5. If no default -> throw Error
+ *
+ * @param {string|undefined} modelArg - Model argument from CLI or undefined
+ * @returns {string} Resolved full model identifier
+ * @throws {Error} When alias is unknown or no default configured
+ */
+function resolveModel(modelArg) {
+  const config = loadConfig();
+
+  const effectiveAliases = getEffectiveAliases();
+
+  // If modelArg is provided
+  if (modelArg !== undefined && modelArg !== null) {
+    // Full model string with slash - return as-is
+    if (modelArg.includes('/')) {
+      return modelArg;
+    }
+
+    // Try to resolve as alias (user config + defaults)
+    if (effectiveAliases[modelArg] !== undefined) {
+      const resolved = effectiveAliases[modelArg];
+      if (!resolved || resolved === 'null') {
+        return autoRepairAlias(modelArg, config, DEFAULT_ALIASES, saveConfig);
+      }
+      return applyDirectApiFallback(resolved);
+    }
+
+    // Unknown alias
+    throw new Error(
+      `Unknown model alias '${modelArg}'. Run 'sidecar setup' to configure aliases.`
+    );
+  }
+
+  // modelArg is undefined - use default
+  if (!config || !config.default) {
+    throw new Error(
+      'No model specified and no default configured. Run \'sidecar setup\' to set a default model.'
+    );
+  }
+
+  const defaultValue = config.default;
+
+  // Default is a full model string
+  if (defaultValue.includes('/')) {
+    return defaultValue;
+  }
+
+  // Default is an alias - resolve via user config + defaults
+  if (effectiveAliases[defaultValue] !== undefined) {
+    const resolved = effectiveAliases[defaultValue];
+    if (!resolved || resolved === 'null') {
+      return autoRepairAlias(defaultValue, config, DEFAULT_ALIASES, saveConfig);
+    }
+    return applyDirectApiFallback(resolved);
+  }
+
+  // Default alias not found anywhere
+  throw new Error(
+    `Default alias '${defaultValue}' not found in aliases. Run 'sidecar setup' to fix configuration.`
+  );
+}
+
+/** @returns {string|null} 8-char hex hash of config file, or null if missing */
+function computeConfigHash() {
+  const configPath = getConfigPath();
+  try {
+    if (!fs.existsSync(configPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return crypto.createHash('sha256').update(content).digest('hex').slice(0, 8);
+  } catch (_err) {
+    return null;
+  }
+}
+
+/** @returns {string} Markdown alias table with (default) marker, or empty string */
+function buildAliasTable() {
+  const config = loadConfig();
+  if (!config || !config.aliases || Object.keys(config.aliases).length === 0) {
+    return '';
+  }
+
+  const defaultAlias = config.default || null;
+  const lines = [];
+
+  lines.push('| Alias | Model |');
+  lines.push('|-------|-------|');
+
+  for (const [alias, model] of Object.entries(config.aliases)) {
+    const marker = (alias === defaultAlias) ? ' (default)' : '';
+    lines.push(`| ${alias}${marker} | ${model} |`);
+  }
+
+  return lines.join('\n');
+}
+
+/** Check whether the config file has changed compared to a known hash */
+function checkConfigChanged(currentHash) {
+  const newHash = computeConfigHash();
+
+  if (currentHash === newHash) {
+    return { changed: false, newHash };
+  }
+
+  // Config has changed (or was created/removed)
+  const aliasTable = buildAliasTable();
+  const hashComment = newHash ? `<!-- amicus-config-hash: ${newHash} -->` : '';
+  const updateData = [hashComment, aliasTable].filter(Boolean).join('\n');
+
+  return {
+    changed: true,
+    newHash,
+    updateData: updateData || undefined,
+  };
+}
+
+/**
+ * Get effective aliases: defaults merged with user config (user wins)
+ * @returns {object} Merged alias map
+ */
+function getEffectiveAliases() {
+  const config = loadConfig();
+  const userAliases = (config && config.aliases) || {};
+  return { ...DEFAULT_ALIASES, ...userAliases };
+}
+
+/**
+ * Format alias names as a comma-separated string for tool descriptions
+ * @returns {string} e.g. "gemini, opus, gpt, deepseek, ..."
+ */
+function formatAliasNames() {
+  return Object.keys(getEffectiveAliases()).join(', ');
+}
+
+/**
+ * Non-throwing wrapper around resolveModel
+ * @param {string|undefined} modelArg - Model argument
+ * @returns {{model?: string, error?: string}} Resolved model or error message
+ */
+function tryResolveModel(modelArg) {
+  try {
+    return { model: resolveModel(modelArg) };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+/** Build OpenCode provider.models config from sidecar aliases.
+ * @returns {object} e.g. { openrouter: { models: { "x-ai/grok-4.3": {}, ... } } } */
+function buildProviderModels() {
+  const aliases = getEffectiveAliases();
+  const providers = {};
+
+  for (const fullModel of Object.values(aliases)) {
+    if (!fullModel || typeof fullModel !== 'string') { continue; }
+    const parts = fullModel.split('/');
+    if (parts.length < 2) { continue; }
+
+    const providerID = parts[0];
+    const modelID = parts.slice(1).join('/');
+
+    if (!providers[providerID]) {
+      providers[providerID] = { models: {} };
+    }
+    providers[providerID].models[modelID] = {};
+  }
+
+  return providers;
+}
+
+/** Detect if direct API fallback was applied during alias resolution */
+function detectFallback(alias, resolvedModel) {
+  if (!alias || alias.includes('/')) { return false; }
+  const val = getEffectiveAliases()[alias];
+  return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
+}
+
+module.exports = {
+  getConfigDir,
+  getConfigPath,
+  loadConfig,
+  saveConfig,
+  getDefaultAliases,
+  resolveModel,
+  detectFallback,
+  computeConfigHash,
+  buildAliasTable,
+  checkConfigChanged,
+  getEffectiveAliases,
+  formatAliasNames,
+  tryResolveModel,
+  buildProviderModels,
+};

package/src/utils/curated-models.js

@@ -0,0 +1,82 @@
+/**
+ * Curated Models — THE single source of truth for default model lists.
+ *
+ * Three consumers derive from this module (F5 anti-drift):
+ *   - src/utils/config.js DEFAULT_ALIASES   (toDefaultAliases)
+ *   - electron/setup-ui-model.js MODEL_CHOICES (getCuratedModels)
+ *   - src/sidecar/setup.js MODEL_CHOICES      (getCuratedModels)
+ * Never hand-edit a model id anywhere else. `amicus models --check`
+ * audits every route here against the live catalog.
+ */
+
+'use strict';
+
+/**
+ * Card entries (shown as wizard quick picks). `routes` maps provider →
+ * full model id; the openrouter route doubles as the default alias target.
+ * Direct (non-openrouter) route ids MUST be verified against the provider
+ * whenever they change.
+ */
+const CARDS = [
+  { alias: 'gemini', label: 'Gemini 3.1 Flash Lite', blurb: 'fast, large context',
+    routes: { openrouter: 'openrouter/google/gemini-3.1-flash-lite-preview',
+              google: 'google/gemini-3.1-flash-lite-preview' } },
+  { alias: 'gemini-pro', label: 'Gemini 3.1 Pro', blurb: 'advanced reasoning',
+    routes: { openrouter: 'openrouter/google/gemini-3.1-pro-preview',
+              google: 'google/gemini-3.1-pro-preview' } },
+  { alias: 'gpt', label: 'GPT-5.4', blurb: 'strong coding',
+    routes: { openrouter: 'openrouter/openai/gpt-5.4',
+              openai: 'openai/gpt-5.4' } },
+  { alias: 'opus', label: 'Claude Opus 4.6', blurb: 'deep analysis',
+    routes: { openrouter: 'openrouter/anthropic/claude-opus-4.6',
+              anthropic: 'anthropic/claude-opus-4-6' } },
+  { alias: 'deepseek', label: 'DeepSeek v3.2', blurb: 'open-source',
+    routes: { openrouter: 'openrouter/deepseek/deepseek-v3.2' } },
+];
+
+/** Alias-only entries (no wizard card); openrouter route only. */
+const CARDLESS = [
+  { alias: 'gpt-pro', routes: { openrouter: 'openrouter/openai/gpt-5.4-pro' } },
+  // codex: newest codex-specific model on OpenRouter (verified 2026-06-09).
+  { alias: 'codex', routes: { openrouter: 'openrouter/openai/gpt-5.3-codex' } },
+  { alias: 'claude', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
+  { alias: 'sonnet', routes: { openrouter: 'openrouter/anthropic/claude-sonnet-4.6' } },
+  { alias: 'haiku', routes: { openrouter: 'openrouter/anthropic/claude-haiku-4.5' } },
+  { alias: 'qwen', routes: { openrouter: 'openrouter/qwen/qwen3.5-397b-a17b' } },
+  { alias: 'qwen-coder', routes: { openrouter: 'openrouter/qwen/qwen3-coder-next' } },
+  { alias: 'qwen-flash', routes: { openrouter: 'openrouter/qwen/qwen3.5-flash-02-23' } },
+  { alias: 'mistral', routes: { openrouter: 'openrouter/mistralai/mistral-large-2512' } },
+  { alias: 'devstral', routes: { openrouter: 'openrouter/mistralai/devstral-2512' } },
+  { alias: 'glm', routes: { openrouter: 'openrouter/z-ai/glm-5' } },
+  { alias: 'minimax', routes: { openrouter: 'openrouter/minimax/minimax-m2.5' } },
+  { alias: 'grok', routes: { openrouter: 'openrouter/x-ai/grok-4.3' } },
+  { alias: 'kimi', routes: { openrouter: 'openrouter/moonshotai/kimi-k2.5' } },
+  { alias: 'seed', routes: { openrouter: 'openrouter/bytedance-seed/seed-2.0-mini' } },
+];
+
+/** @returns {Array<{alias,label,blurb,routes}>} card entries (wizard quick picks) */
+function getCuratedModels() {
+  return CARDS.map(c => ({ ...c, routes: { ...c.routes } }));
+}
+
+/** @returns {Object<string,string>} alias → preferred route (openrouter first) */
+function toDefaultAliases() {
+  const out = {};
+  for (const e of [...CARDS, ...CARDLESS]) {
+    out[e.alias] = e.routes.openrouter || Object.values(e.routes)[0];
+  }
+  return out;
+}
+
+/** @returns {Array<{alias,provider,model}>} every route of every entry, flattened */
+function listCuratedRoutes() {
+  const out = [];
+  for (const e of [...CARDS, ...CARDLESS]) {
+    for (const [provider, model] of Object.entries(e.routes)) {
+      out.push({ alias: e.alias, provider, model });
+    }
+  }
+  return out;
+}
+
+module.exports = { getCuratedModels, toDefaultAliases, listCuratedRoutes };

package/src/utils/env-compat.js

@@ -0,0 +1,38 @@
+/**
+ * Environment-variable compatibility shim (Amicus rebrand).
+ *
+ * DEPRECATED(amicus-shim): the SIDECAR_* fallbacks exist only for backward
+ * compatibility with pre-rebrand setups. Remove in a future revision once users
+ * have migrated to the AMICUS_* names. See docs/SHIMS.md.
+ */
+const { logger } = require('./logger');
+
+const warned = new Set();
+
+/**
+ * Read an env var by its canonical AMICUS_<suffix> name, falling back to the
+ * legacy SIDECAR_<suffix> name (with a one-time deprecation warning) if unset.
+ *
+ * @param {string} suffix - e.g. 'CONFIG_DIR' (no AMICUS_/SIDECAR_ prefix)
+ * @returns {string|undefined}
+ */
+function getCompatEnv(suffix) {
+  const amicusName = `AMICUS_${suffix}`;
+  if (process.env[amicusName] !== undefined) {
+    return process.env[amicusName];
+  }
+  const legacyName = `SIDECAR_${suffix}`;
+  if (process.env[legacyName] !== undefined) {
+    if (!warned.has(legacyName)) {
+      warned.add(legacyName);
+      logger.warn(
+        `${legacyName} is deprecated; use ${amicusName} instead. ` +
+        'Support will be removed in a future Amicus release.'
+      );
+    }
+    return process.env[legacyName];
+  }
+  return undefined;
+}
+
+module.exports = { getCompatEnv };

package/src/utils/env-loader.js

@@ -0,0 +1,54 @@
+/**
+ * Credential Loader
+ *
+ * Loads API keys from multiple sources into process.env at CLI bootstrap.
+ * Priority: process.env (already set) > amicus .env > auth.json
+ * Never overwrites existing process.env values.
+ */
+const { logger } = require('./logger');
+const { loadEnvEntries, PROVIDER_ENV_MAP, LEGACY_KEY_NAMES } = require('./api-key-store');
+const { readAuthJsonKeys } = require('./auth-json');
+
+/**
+ * Load credentials from all sources into process.env.
+ * Call once at CLI startup, before any validation.
+ *
+ * Sources (in priority order):
+ * 1. process.env - already set, never overwritten
+ * 2. ~/.config/amicus/.env - user-configured via `amicus setup`
+ *    (DEPRECATED(amicus-shim): falls back to ~/.config/sidecar/.env if the amicus .env absent)
+ * 3. ~/.local/share/opencode/auth.json - OpenCode SDK fallback
+ */
+function loadCredentials() {
+  // Step 1: Load from sidecar .env file
+  const fileEntries = loadEnvEntries();
+  for (const [, envVar] of Object.entries(PROVIDER_ENV_MAP)) {
+    if (!process.env[envVar]) {
+      const fromFile = fileEntries.get(envVar);
+      if (fromFile && fromFile.length > 0) {
+        process.env[envVar] = fromFile;
+        logger.info(`Loaded ${envVar} from amicus .env`);
+      }
+    }
+  }
+
+  // Step 1b: Handle legacy key names in process.env
+  for (const [oldName, newName] of Object.entries(LEGACY_KEY_NAMES)) {
+    if (process.env[oldName] && !process.env[newName]) {
+      process.env[newName] = process.env[oldName];
+      logger.info(`Migrated ${oldName} to ${newName}`);
+    }
+  }
+
+  // Step 2: Import from auth.json (lowest priority)
+  const authKeys = readAuthJsonKeys();
+  for (const [provider, key] of Object.entries(authKeys)) {
+    const envVar = PROVIDER_ENV_MAP[provider];
+    if (envVar && !process.env[envVar]) {
+      process.env[envVar] = key;
+      logger.info(`Loaded ${envVar} from auth.json`);
+    }
+  }
+}
+
+module.exports = { loadCredentials };

package/src/utils/idle-watchdog.js

@@ -0,0 +1,225 @@
+/**
+ * @module idle-watchdog
+ * IdleWatchdog - BUSY/IDLE state machine with self-terminating timer.
+ *
+ * Tracks whether a sidecar session is actively processing (BUSY) or
+ * waiting for work (IDLE). Fires an onTimeout callback after the
+ * configured idle period elapses. Supports stuck-stream protection to
+ * force-transition out of BUSY if a response stream never completes.
+ *
+ * Timeout priority (highest to lowest):
+ *   1. Per-mode env var (AMICUS_IDLE_TIMEOUT_HEADLESS, etc.) in minutes
+ *      (legacy SIDECAR_IDLE_TIMEOUT_* still honored via env-compat shim)
+ *   2. Blanket env var AMICUS_IDLE_TIMEOUT / SIDECAR_IDLE_TIMEOUT in minutes
+ *   3. Constructor option `timeout` in milliseconds
+ *   4. Mode default (headless=15m, interactive=60m, server=30m)
+ */
+
+'use strict';
+
+const { getCompatEnv } = require('./env-compat');
+
+/** @type {Object.<string, number>} Default timeouts per mode in milliseconds */
+const MODE_TIMEOUTS = {
+  headless: 15 * 60 * 1000,
+  interactive: 60 * 60 * 1000,
+  server: 30 * 60 * 1000,
+};
+
+/** @type {Object.<string, string>} Per-mode env-compat suffixes */
+const MODE_ENV_MAP = {
+  headless: 'IDLE_TIMEOUT_HEADLESS',
+  interactive: 'IDLE_TIMEOUT_INTERACTIVE',
+  server: 'IDLE_TIMEOUT_SERVER',
+};
+
+/**
+ * Resolve the effective timeout in milliseconds using the priority chain.
+ *
+ * @param {string} mode - The operating mode ('headless', 'interactive', 'server')
+ * @param {number|undefined} optionTimeout - Caller-supplied timeout in ms (or undefined)
+ * @returns {number} Effective timeout in ms, or Infinity if disabled
+ */
+function resolveTimeout(mode, optionTimeout) {
+  const modeSuffix = MODE_ENV_MAP[mode];
+  if (modeSuffix !== undefined) {
+    const modeEnv = getCompatEnv(modeSuffix);
+    if (modeEnv !== undefined) {
+      const mins = Number(modeEnv);
+      return mins === 0 ? Infinity : mins * 60 * 1000;
+    }
+  }
+
+  const blanket = getCompatEnv('IDLE_TIMEOUT');
+  if (blanket !== undefined) {
+    const mins = Number(blanket);
+    return mins === 0 ? Infinity : mins * 60 * 1000;
+  }
+
+  if (optionTimeout !== undefined) {
+    return optionTimeout === 0 ? Infinity : optionTimeout;
+  }
+
+  return MODE_TIMEOUTS[mode] || MODE_TIMEOUTS.headless;
+}
+
+/**
+ * IdleWatchdog - BUSY/IDLE state machine with configurable idle timeout.
+ *
+ * @example
+ * const wd = new IdleWatchdog({ mode: 'headless', timeout: 60000, onTimeout: () => process.exit(0) });
+ * wd.start();
+ * wd.markBusy();   // called when a stream starts
+ * wd.markIdle();   // called when a stream completes
+ * wd.touch();      // called during polling to reset the idle clock
+ * wd.cancel();     // stop all timers (e.g. on clean shutdown)
+ */
+class IdleWatchdog {
+  /**
+   * @param {object} options
+   * @param {'headless'|'interactive'|'server'} [options.mode='headless'] - Operating mode
+   * @param {number} [options.timeout] - Idle timeout in ms (0 = Infinity/disabled)
+   * @param {number} [options.stuckStreamTimeout] - Max ms to remain in BUSY before force-idle
+   * @param {Function} [options.onTimeout] - Called when idle timeout fires
+   * @param {object} [options.logger] - Logger with .warn() and .info() (defaults to console)
+   */
+  constructor(options = {}) {
+    const { mode = 'headless', timeout, stuckStreamTimeout, onTimeout, logger: log } = options;
+
+    /** @type {string} Current operating mode */
+    this.mode = mode;
+
+    /** @type {number} Effective idle timeout in ms */
+    this.timeout = resolveTimeout(mode, timeout);
+
+    /** @type {number} Max ms to stay BUSY before force-transitioning to IDLE */
+    this.stuckStreamTimeout = stuckStreamTimeout || 5 * 60 * 1000;
+
+    /** @type {Function} Callback fired on idle timeout */
+    this.onTimeout = onTimeout || (() => {});
+
+    /** @type {object} Logger instance */
+    this.logger = log || console;
+
+    /** @type {'IDLE'|'BUSY'} Current state */
+    this.state = 'IDLE';
+
+    /** @type {ReturnType<typeof setTimeout>|null} Active idle countdown timer */
+    this._timer = null;
+
+    /** @type {ReturnType<typeof setTimeout>|null} Stuck-stream detection timer */
+    this._stuckTimer = null;
+
+    /** @type {number} Epoch ms when this watchdog was created */
+    this._startedAt = Date.now();
+  }
+
+  /**
+   * Activate the watchdog and begin the idle countdown.
+   *
+   * @returns {IdleWatchdog} Returns `this` for chaining
+   */
+  start() {
+    this._resetTimer();
+    return this;
+  }
+
+  /**
+   * Transition to BUSY state, suspending the idle timer.
+   * Starts the stuck-stream protection timer.
+   * Idempotent: calling while already BUSY is a no-op for the state,
+   * but does refresh the stuck timer.
+   */
+  markBusy() {
+    this.state = 'BUSY';
+    clearTimeout(this._timer);
+    this._timer = null;
+    this._startStuckTimer();
+  }
+
+  /**
+   * Transition to IDLE state and restart the idle countdown.
+   * Cancels the stuck-stream protection timer.
+   */
+  markIdle() {
+    this.state = 'IDLE';
+    this._clearStuckTimer();
+    this._resetTimer();
+  }
+
+  /**
+   * Reset the idle countdown without changing state.
+   * Has no effect when in BUSY state.
+   */
+  touch() {
+    if (this.state === 'IDLE') {
+      this._resetTimer();
+    }
+  }
+
+  /**
+   * Cancel all active timers. The watchdog becomes inert.
+   * Call this on clean shutdown to prevent stray callbacks.
+   */
+  cancel() {
+    clearTimeout(this._timer);
+    this._timer = null;
+    this._clearStuckTimer();
+  }
+
+  /**
+   * Clear and restart the idle countdown timer.
+   *
+   * @private
+   */
+  _resetTimer() {
+    clearTimeout(this._timer);
+    if (this.timeout === Infinity) {
+      this._timer = null;
+      return;
+    }
+    this._timer = setTimeout(() => {
+      this.logger.info?.('Idle timeout reached', {
+        mode: this.mode,
+        uptimeMs: Date.now() - this._startedAt,
+      });
+      this.onTimeout();
+    }, this.timeout);
+    // Allow Node process to exit naturally if only this timer remains.
+    if (this._timer.unref) {
+      this._timer.unref();
+    }
+  }
+
+  /**
+   * Start the stuck-stream protection timer.
+   * If it fires, the watchdog force-transitions to IDLE.
+   *
+   * @private
+   */
+  _startStuckTimer() {
+    this._clearStuckTimer();
+    if (this.stuckStreamTimeout === Infinity) { return; }
+    this._stuckTimer = setTimeout(() => {
+      this.logger.warn?.('Stuck stream detected, force-transitioning to IDLE', {
+        stuckMs: this.stuckStreamTimeout,
+      });
+      this.markIdle();
+    }, this.stuckStreamTimeout);
+    if (this._stuckTimer.unref) {
+      this._stuckTimer.unref();
+    }
+  }
+
+  /**
+   * Clear the stuck-stream protection timer.
+   *
+   * @private
+   */
+  _clearStuckTimer() {
+    clearTimeout(this._stuckTimer);
+    this._stuckTimer = null;
+  }
+}
+
+module.exports = { IdleWatchdog, resolveTimeout };