subconscious-cli 4.0.0 → 4.0.1

package/README.md

@@ -10,6 +10,16 @@ subc login
 subc claude
 ```
 
+Every interactive `subc` command checks npm for a newer CLI release. When an
+update is available, a notice shows the installed and latest versions and lets
+you select **Update now** or **Skip for now** with the arrow keys and Enter.
+Each option describes what it will do, and the active option is highlighted.
+Update runs `npm install -g subconscious-cli@latest`; Skip continues the
+requested command.
+Non-interactive commands automatically skip, and registry errors and timeouts
+never block the requested command. Set `SUBC_DISABLE_UPDATE_CHECK=1` to suppress
+the check in offline automation.
+
 Login creates both the saved credential and a ready-to-use `default` profile,
 so Claude Code, Codex, and OpenCode can launch immediately. Persistent editor
 and Pi integrations are installed per agent:
@@ -156,7 +166,9 @@ values. A command-line `--model` override has the highest model precedence.
 
 ## Models and endpoint overrides
 
-List the available models with `subc models`:
+List the available models with `subc models`. The command fetches the active
+gateway's authenticated `/v1/models` catalog and falls back to the models
+packaged with the CLI when discovery is unavailable:
 
 ```text
 subconscious/glm-5.2 (default)
@@ -173,14 +185,17 @@ subc config --model subconscious/deepseek-v4-flash-marathon
 export SUBCONSCIOUS_MODEL=subconscious/glm-5.2
 ```
 
-The Claude Code, Codex, OpenCode, Pi, and Copilot integrations register all
-three models with their native model pickers. The profile's `MODEL` remains the
-active model where the agent supports setting one and is listed first in the
-other catalogs. Cursor requires adding the three model IDs in its OpenAI API
-Key Override settings; `subc cursor install` prints the complete list and the model
-selected by the active profile. Use the printed `/v1` Base URL in Cursor
-Settings; the profile itself stores the gateway origin so correlation hooks can
-post to `/v1/agent-hooks`.
+Every launch and install fetches the same live catalog without caching. Codex,
+OpenCode, Pi, Copilot, and Cursor receive the complete model list. The selected
+profile model is listed first only while the gateway still advertises it.
+If a saved profile default has been removed, launches use the first live model;
+an explicit `--model` or `SUBCONSCIOUS_MODEL` override is always preserved.
+Claude Code exposes four native Opus/Sonnet/Haiku/Fable picker slots plus one
+custom model option, so the CLI maps the first five models into those slots; any other
+model can still be selected with `subc claude --model MODEL`. Cursor requires adding
+the printed model IDs in its OpenAI API Key Override settings. Use the printed
+`/v1` Base URL in Cursor Settings; the profile itself stores the gateway origin
+so correlation hooks can post to `/v1/agent-hooks`.
 
 The default gateway is `https://api.subconscious.dev`. Profiles containing
 the former exact default (`https://api.subconscious.dev`) migrate automatically;

package/bin/agents.js

@@ -21,13 +21,14 @@ import { fileURLToPath } from 'node:url';
 import { c } from './colors.js';
 import { getApiKey } from './auth.js';
 import { profileSettingsForAgent, resolvedProfileValues } from './profiles.js';
+import { resolveModelCatalog } from './models.js';
 
 // --- Registry (single source of truth, generated copy shipped in the package).
 const registry = JSON.parse(
   readFileSync(new URL('./registry.generated.json', import.meta.url), 'utf-8'),
 );
 const DEFAULTS = registry.defaults;
-const SUPPORTED_MODELS =
+const PACKAGED_MODELS =
   Array.isArray(DEFAULTS.models) && DEFAULTS.models.length
     ? DEFAULTS.models
     : [DEFAULTS.model];
@@ -312,8 +313,10 @@ function buildContext(apiKey, model, profile) {
  * Falls back to SUBCONSCIOUS_MODEL, then the registry default.
  */
 function extractModel(argv, profile) {
-  let model =
-    process.env.SUBCONSCIOUS_MODEL?.trim() || profile?.values?.MODEL?.trim() || DEFAULTS.model;
+  const environmentModel = process.env.SUBCONSCIOUS_MODEL?.trim();
+  const profileModel = profile?.values?.MODEL?.trim();
+  let model = environmentModel || profileModel || DEFAULTS.model;
+  let modelSource = environmentModel ? 'environment' : profileModel ? 'profile' : 'default';
   const rest = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -321,17 +324,19 @@ function extractModel(argv, profile) {
       const v = argv[i + 1];
       if (v && !v.startsWith('-')) {
         model = v;
+        modelSource = 'command';
         i++;
       }
       continue;
     }
     if (a.startsWith('--model=')) {
       model = a.slice('--model='.length);
+      modelSource = 'command';
       continue;
     }
     rest.push(a);
   }
-  return { model, rest };
+  return { model, modelSource, rest };
 }
 
 /**
@@ -611,34 +616,102 @@ const CLAUDE_MODEL_PICKER_KEYS = [
   'ANTHROPIC_DEFAULT_HAIKU_MODEL',
   'ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME',
   'ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL_NAME',
+  'ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION_NAME',
+  'ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION',
 ];
 
-function claudeModelPickerEnv(agent, ctx) {
+function claudeModelPickerEnv(agent, ctx, models) {
   if (agent.id !== 'claude-code') return {};
   const configured = substitute(agent.env || {}, ctx);
+  const configuredModels = [
+    configured.ANTHROPIC_DEFAULT_OPUS_MODEL,
+    configured.ANTHROPIC_DEFAULT_SONNET_MODEL,
+    configured.ANTHROPIC_DEFAULT_HAIKU_MODEL,
+    configured.ANTHROPIC_DEFAULT_FABLE_MODEL,
+    configured.ANTHROPIC_CUSTOM_MODEL_OPTION,
+  ];
+  const pickerModels = [];
+  for (const model of [...models, ...configuredModels]) {
+    if (model && !pickerModels.includes(model)) pickerModels.push(model);
+  }
+  while (pickerModels.length < 3) pickerModels.push(pickerModels.at(-1) || ctx.model);
+
+  const roles = ['OPUS', 'SONNET', 'HAIKU', 'FABLE'];
+  const env = {};
+  for (let index = 0; index < roles.length; index++) {
+    const role = roles[index];
+    const model = pickerModels[index];
+    if (!model) continue;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL`] = model;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL_NAME`] = model;
+    env[`ANTHROPIC_DEFAULT_${role}_MODEL_DESCRIPTION`] = `Subconscious model ${model}`;
+  }
+  const customModel = pickerModels[4];
+  if (customModel) {
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION = customModel;
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION_NAME = customModel;
+    env.ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION = `Subconscious model ${customModel}`;
+  }
   return Object.fromEntries(
-    CLAUDE_MODEL_PICKER_KEYS.map((key) => [key, configured[key]]).filter(([, value]) => value),
+    CLAUDE_MODEL_PICKER_KEYS.map((key) => [key, env[key]]).filter(([, value]) => value),
   );
 }
 
-export function runbookEnv(apiKey, model, binDir, profile, agent) {
+export function runbookEnv(
+  apiKey,
+  model,
+  binDir,
+  profile,
+  agent,
+  models = PACKAGED_MODELS,
+) {
   const ctx = buildContext(apiKey, model, profile);
   const extraDirs = [binDir, ...candidateBinDirs()].filter(Boolean);
   const specificApiKey = agentApiKeySetting(agent)?.key;
   return {
-    ...claudeModelPickerEnv(agent, ctx),
+    ...claudeModelPickerEnv(agent, ctx, models),
     ...(profile?.values || {}),
     ...process.env,
     GATEWAY_URL: ctx.baseUrl,
     API_KEY: apiKey,
     ...(specificApiKey ? { [specificApiKey]: apiKey } : {}),
     MODEL: model,
-    SUBCONSCIOUS_MODELS: SUPPORTED_MODELS.join('\n'),
+    SUBCONSCIOUS_MODELS: models.join('\n'),
     SUBC_ENV_FILE: os.devNull,
     PATH: augmentPath(extraDirs),
   };
 }
 
+async function resolvedModelsForLaunch(profile, apiKey, selectedModel) {
+  const ctx = buildContext(apiKey, selectedModel, profile);
+  const catalog = await resolveModelCatalog({
+    baseUrl: ctx.baseUrl,
+    apiKey,
+    selectedModel,
+    fallbackModels: PACKAGED_MODELS,
+  });
+  if (catalog.error) {
+    console.error(
+      `  ${c.yellow}Could not fetch the live model catalog; using packaged defaults.${c.reset}`,
+    );
+    console.error(`  ${c.dim}${catalog.error.message}${c.reset}\n`);
+  }
+  return catalog;
+}
+
+export function selectLaunchModel(requestedModel, modelSource, catalog) {
+  const useLiveDefault =
+    catalog.source === 'gateway' &&
+    catalog.models.length > 0 &&
+    !catalog.models.includes(requestedModel) &&
+    (modelSource === 'profile' || modelSource === 'default');
+  return useLiveDefault ? catalog.models[0] : requestedModel;
+}
+
 async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runbook.script) {
   if (isSetupWithoutAuth(argv)) {
     return spawnRunbook(agent, argv, {
@@ -648,9 +721,16 @@ async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runb
     }, relativeScript);
   }
 
-  const { model, rest } = extractModel(argv, profile);
+  const { model: requestedModel, modelSource, rest } = extractModel(argv, profile);
   const apiKey = optionValue(rest, '--api-key') || (await requireApiKey(profile, agent));
   if (!apiKey) return 1;
+  const catalog = await resolvedModelsForLaunch(profile, apiKey, requestedModel);
+  const model = selectLaunchModel(requestedModel, modelSource, catalog);
+  if (model !== requestedModel) {
+    console.error(
+      `  ${c.yellow}Configured model ${requestedModel} is not in the live catalog; using ${model}.${c.reset}\n`,
+    );
+  }
   const ctx = buildContext(apiKey, model, profile);
   const authArgs = substitute(agent.runbook.authArgs || [], ctx);
 
@@ -660,7 +740,7 @@ async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runb
   const code = await spawnRunbook(
     agent,
     [...authArgs, ...rest],
-    runbookEnv(apiKey, model, undefined, profile, agent),
+    runbookEnv(apiKey, model, undefined, profile, agent, catalog.models),
     relativeScript,
   );
   const installed = !['status', 'uninstall'].includes(rest[0]);
@@ -708,17 +788,28 @@ export async function runAgent(agent, argv, options = {}) {
     return code;
   }
 
-  const { model, rest } = extractModel(argv, profile);
+  const { model: requestedModel, modelSource, rest } = extractModel(argv, profile);
   const apiKey = await requireApiKey(profile, agent);
   if (!apiKey) return 1;
 
   const binDir = await ensureInstalled(agent);
+  const catalog = await resolvedModelsForLaunch(profile, apiKey, requestedModel);
+  const model = selectLaunchModel(requestedModel, modelSource, catalog);
+  if (model !== requestedModel) {
+    console.error(
+      `  ${c.yellow}Configured model ${requestedModel} is not in the live catalog; using ${model}.${c.reset}\n`,
+    );
+  }
 
   if (agent.runbook?.mode === 'launch') {
     console.log(
       `  ${c.dim}Launching ${c.reset}${c.bold}${agent.name}${c.reset} ${c.dim}on Subconscious ${c.reset}${c.dim}(${model})${c.reset}\n`,
     );
-    return spawnRunbook(agent, rest, runbookEnv(apiKey, model, binDir, profile, agent));
+    return spawnRunbook(
+      agent,
+      rest,
+      runbookEnv(apiKey, model, binDir, profile, agent, catalog.models),
+    );
   }
 
   const ctx = buildContext(apiKey, model, profile);

package/bin/cli.js

@@ -15,6 +15,7 @@ import { renderBanner } from './branding.js';
 import {
   loginCommand,
   logoutCommand,
+  getApiKey,
   updateApiKeyCommand,
   whoamiCommand,
 } from './auth.js';
@@ -33,9 +34,13 @@ import {
   loadProfile,
   modelsCommand,
   printConfigHelp,
+  RUNBOOK_DEFAULTS,
+  SUPPORTED_MODELS as PACKAGED_MODELS,
   updateUrlCommand,
   validateProfileName,
 } from './profiles.js';
+import { resolveModelCatalog } from './models.js';
+import { showUpdateNotice } from './update-check.js';
 
 function isHelpArg(arg) {
   return arg === 'help' || arg === '-h' || arg === '--help';
@@ -220,6 +225,9 @@ function requireNamedProfile(profile) {
 }
 
 async function main() {
+  const update = await showUpdateNotice();
+  if (update?.action === 'updated' || update?.action === 'cancel') return;
+
   const parsed = extractProfile(process.argv.slice(2));
   const { args, profileName, profileExplicit } = parsed;
   const command = args[0];
@@ -285,7 +293,23 @@ async function main() {
       console.log(COMMAND_HELP.models);
       return;
     }
-    modelsCommand();
+    const profile = await loadProfile(profileName);
+    const auth = await getApiKey(profile);
+    const selectedModel =
+      process.env.SUBCONSCIOUS_MODEL?.trim() ||
+      profile.values.MODEL?.trim() ||
+      RUNBOOK_DEFAULTS.MODEL;
+    const baseUrl =
+      process.env.SUBCONSCIOUS_BASE_URL?.trim() ||
+      profile.values.GATEWAY_URL?.trim() ||
+      RUNBOOK_DEFAULTS.GATEWAY_URL;
+    const catalog = await resolveModelCatalog({
+      baseUrl,
+      apiKey: auth?.key,
+      selectedModel,
+      fallbackModels: PACKAGED_MODELS,
+    });
+    modelsCommand(catalog.models, { selectedModel, error: catalog.error });
     return;
   }
 

package/bin/colors.js

@@ -21,4 +21,5 @@ export const c = {
   yellow: ansi(33),
   magenta: ansi(35),
   underline: ansi(4),
+  inverse: ansi(7),
 };

package/bin/models.js

@@ -0,0 +1,104 @@
+/**
+ * Resolve the model catalog exposed by an OpenAI-compatible gateway.
+ *
+ * Live discovery is best-effort: launches should keep working with the
+ * packaged registry when the gateway is offline or does not expose /v1/models.
+ */
+
+const MODEL_ID_PATTERN = /^[-A-Za-z0-9._:/+]+$/;
+export const DEFAULT_MODEL_FETCH_TIMEOUT_MS = 3000;
+
+export function normalizeModelIds(modelIds = [], selectedModel) {
+  const models = [];
+  const seen = new Set();
+
+  for (const value of modelIds) {
+    const model = typeof value === 'string' ? value.trim() : '';
+    if (!model || !MODEL_ID_PATTERN.test(model) || seen.has(model)) continue;
+    seen.add(model);
+    models.push(model);
+  }
+
+  const selectedIndex = models.indexOf(selectedModel?.trim());
+  if (selectedIndex > 0) {
+    models.unshift(models.splice(selectedIndex, 1)[0]);
+  }
+
+  return models;
+}
+
+export async function fetchGatewayModels({
+  baseUrl,
+  apiKey,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_MODEL_FETCH_TIMEOUT_MS,
+}) {
+  if (!baseUrl?.trim()) throw new Error('Gateway URL is not configured');
+  if (!apiKey?.trim()) throw new Error('No API key is available for model discovery');
+  if (typeof fetchImpl !== 'function') {
+    throw new Error('This Node.js version does not support fetch');
+  }
+
+  const endpoint = `${baseUrl.trim().replace(/\/+$/, '')}/v1/models`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  timeout.unref?.();
+
+  try {
+    const response = await fetchImpl(endpoint, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey.trim()}`,
+        'Cache-Control': 'no-cache, no-store',
+        Pragma: 'no-cache',
+      },
+      cache: 'no-store',
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Model discovery returned HTTP ${response.status}`);
+    }
+
+    const payload = await response.json();
+    if (!Array.isArray(payload?.data)) {
+      throw new Error('Model discovery returned an invalid response');
+    }
+
+    const models = normalizeModelIds(payload.data.map((model) => model?.id));
+    if (!models.length) throw new Error('Model discovery returned no usable model IDs');
+    return models;
+  } catch (error) {
+    if (controller.signal.aborted) {
+      throw new Error(`Model discovery timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function resolveModelCatalog({
+  baseUrl,
+  apiKey,
+  selectedModel,
+  fallbackModels = [],
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_MODEL_FETCH_TIMEOUT_MS,
+}) {
+  try {
+    const discovered = await fetchGatewayModels({ baseUrl, apiKey, fetchImpl, timeoutMs });
+    return {
+      models: normalizeModelIds(discovered, selectedModel),
+      source: 'gateway',
+      error: null,
+    };
+  } catch (error) {
+    return {
+      models: normalizeModelIds([selectedModel, ...fallbackModels], selectedModel),
+      source: 'packaged',
+      error,
+    };
+  }
+}

package/bin/profiles.js

@@ -415,6 +415,22 @@ function migrateDefaultGateway(text) {
     : text;
 }
 
+function migrateCopilotTokenDefaults(text) {
+  const values = parseProfile(text);
+  const updates = {};
+  if (values.COPILOT_MAX_INPUT_TOKENS === '12288') {
+    updates.COPILOT_MAX_INPUT_TOKENS = RUNBOOK_DEFAULTS.COPILOT_MAX_INPUT_TOKENS;
+  }
+  if (values.COPILOT_MAX_OUTPUT_TOKENS === '4096') {
+    updates.COPILOT_MAX_OUTPUT_TOKENS = RUNBOOK_DEFAULTS.COPILOT_MAX_OUTPUT_TOKENS;
+  }
+  return Object.keys(updates).length ? upsertValues(text, updates) : text;
+}
+
+function migrateDefaults(text) {
+  return migrateCopilotTokenDefaults(migrateDefaultGateway(text));
+}
+
 async function writeProfile(file, text) {
   await fs.mkdir(PROFILES_DIR, { recursive: true });
   await fs.writeFile(file, text, { encoding: 'utf-8', mode: 0o600 });
@@ -425,7 +441,7 @@ export async function loadProfile(name = DEFAULT_PROFILE) {
   const file = profilePath(name);
   try {
     const text = await fs.readFile(file, 'utf-8');
-    const migratedText = migrateDefaultGateway(text);
+    const migratedText = migrateDefaults(text);
     if (migratedText !== text) await writeProfile(file, migratedText);
     return { name, path: file, exists: true, values: parseProfile(migratedText) };
   } catch (error) {
@@ -435,7 +451,7 @@ export async function loadProfile(name = DEFAULT_PROFILE) {
   // Migrate an existing profile on first use, leaving the legacy copy intact.
   if (LEGACY_PROFILES_DIR) {
     try {
-      const text = migrateDefaultGateway(
+      const text = migrateDefaults(
         await fs.readFile(path.join(LEGACY_PROFILES_DIR, `${name}.env`), 'utf-8'),
       );
       await writeProfile(file, text);
@@ -729,12 +745,19 @@ export async function configCommand(argv, profileName = DEFAULT_PROFILE, options
   await printProfile(await loadProfile(profileName));
 }
 
-export function modelsCommand() {
+export function modelsCommand(models = SUPPORTED_MODELS, options = {}) {
+  const selectedModel = options.selectedModel || registry.defaults.model;
   console.log(`\n  ${c.bold}Available models${c.reset}\n`);
-  for (const model of SUPPORTED_MODELS) {
-    const suffix = model === registry.defaults.model ? ` ${c.dim}(default)${c.reset}` : '';
+  for (const model of models) {
+    const suffix = model === selectedModel ? ` ${c.dim}(default)${c.reset}` : '';
     console.log(`  ${c.cyan}${model}${c.reset}${suffix}`);
   }
+  if (options.error) {
+    console.error(
+      `\n  ${c.yellow}Could not fetch the live model catalog; showing packaged defaults.${c.reset}`,
+    );
+    console.error(`  ${c.dim}${options.error.message}${c.reset}`);
+  }
   console.log();
 }
 

package/bin/runbook/codex/run.sh

@@ -123,8 +123,8 @@ add_supported_model() {
 }
 
 # Keep the requested model first while exposing the complete Subconscious
-# catalog in Codex's /model picker. The CLI supplies this list from the registry;
-# the fallback keeps the vendored runbook useful on its own.
+# catalog in Codex's /model picker. The CLI supplies the live gateway catalog;
+# the packaged fallback keeps the vendored runbook useful on its own.
 add_supported_model "$MODEL"
 while IFS= read -r model_id; do
   add_supported_model "$model_id"

package/bin/runbook/copilot/install.sh

@@ -40,6 +40,7 @@
 #           "vision": false,
 #           "maxInputTokens": 5000000,
 #           "maxOutputTokens": 65536,
+#           "thinking": true,
 #           "streaming": true,
 #           "requestHeaders": { "x-subconscious-client": "copilot" }
 #         }
@@ -279,7 +280,12 @@ write_config() {
   local user_dir="$1"
   local models_json="${user_dir}/chatLanguageModels.json"
   local base_url="${GATEWAY_URL%/}"
-  local chat_url="${base_url}/v1/chat/completions"
+  local chat_url
+  case "$base_url" in
+    */v1/chat/completions) chat_url="$base_url" ;;
+    */v1) chat_url="${base_url}/chat/completions" ;;
+    *) chat_url="${base_url}/v1/chat/completions" ;;
+  esac
 
   mkdir -p "$user_dir"
   local existing
@@ -302,6 +308,7 @@ write_config() {
         vision: false,
         maxInputTokens: $maxIn,
         maxOutputTokens: $maxOut,
+        thinking: true,
         streaming: true,
         requestHeaders: { "x-subconscious-client": "copilot" }
       }]')

package/bin/update-check.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+import { c } from './colors.js';
+
+export const PACKAGE_NAME = 'subconscious-cli';
+export const UPDATE_CHECK_TIMEOUT_MS = 1500;
+const UPDATE_ACTIONS = ['Update now', 'Skip for now'];
+
+function parseVersion(version) {
+  const match = String(version)
+    .trim()
+    .match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return {
+    core: match.slice(1, 4).map(Number),
+    prerelease: match[4]?.split('.') || [],
+  };
+}
+
+function comparePrerelease(a, b) {
+  if (!a.length && !b.length) return 0;
+  if (!a.length) return 1;
+  if (!b.length) return -1;
+
+  for (let index = 0; index < Math.max(a.length, b.length); index++) {
+    if (a[index] === undefined) return -1;
+    if (b[index] === undefined) return 1;
+    if (a[index] === b[index]) continue;
+
+    const aNumber = /^\d+$/.test(a[index]) ? Number(a[index]) : null;
+    const bNumber = /^\d+$/.test(b[index]) ? Number(b[index]) : null;
+    if (aNumber !== null && bNumber !== null) return Math.sign(aNumber - bNumber);
+    if (aNumber !== null) return -1;
+    if (bNumber !== null) return 1;
+    return a[index].localeCompare(b[index]);
+  }
+  return 0;
+}
+
+export function compareVersions(a, b) {
+  const parsedA = parseVersion(a);
+  const parsedB = parseVersion(b);
+  if (!parsedA || !parsedB) return 0;
+
+  for (let index = 0; index < parsedA.core.length; index++) {
+    if (parsedA.core[index] !== parsedB.core[index]) {
+      return Math.sign(parsedA.core[index] - parsedB.core[index]);
+    }
+  }
+  return comparePrerelease(parsedA.prerelease, parsedB.prerelease);
+}
+
+export async function currentVersion() {
+  const pkg = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf-8'));
+  return pkg.version;
+}
+
+export async function fetchLatestVersion(options = {}) {
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+  const timeoutMs = options.timeoutMs ?? UPDATE_CHECK_TIMEOUT_MS;
+  if (typeof fetchImpl !== 'function') throw new Error('fetch is unavailable');
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  timeout.unref?.();
+
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      headers: {
+        Accept: 'application/json',
+        'Cache-Control': 'no-cache, no-store',
+        Pragma: 'no-cache',
+      },
+      cache: 'no-store',
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`npm returned HTTP ${response.status}`);
+    const payload = await response.json();
+    if (!parseVersion(payload?.version)) throw new Error('npm returned an invalid version');
+    return payload.version;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function renderUpdateNotice(installedVersion, latestVersion) {
+  const title = 'Subconscious CLI update available';
+  const versions = `${installedVersion} -> ${latestVersion}`;
+  const width = Math.max(title.length, versions.length);
+  const border = `+${'-'.repeat(width + 2)}+`;
+  const row = (text, style = '') =>
+    `${c.yellow}|${c.reset} ${style}${text.padEnd(width)}${c.reset} ${c.yellow}|${c.reset}`;
+
+  return [
+    `  ${c.yellow}${border}${c.reset}`,
+    `  ${row(title, c.bold)}`,
+    `  ${row(versions, c.cyan)}`,
+    `  ${c.yellow}${border}${c.reset}`,
+  ].join('\n');
+}
+
+export function renderUpdateOptions(selectedIndex = 0, versions = {}) {
+  const descriptions = [
+    `Runs \`npm install -g ${PACKAGE_NAME}@latest\``,
+    versions.installedVersion
+      ? `Continue this command with version ${versions.installedVersion}`
+      : 'Continue this command without updating',
+  ];
+
+  return UPDATE_ACTIONS.map((label, index) => {
+    const active = index === selectedIndex;
+    const pointer = active ? `${c.cyan}>${c.reset}` : ' ';
+    const option = active
+      ? `${c.inverse}${c.bold} ${label} ${c.reset}`
+      : ` ${label} `;
+    const descriptionStyle = active ? c.cyan : c.dim;
+    return `  ${pointer} ${option}\n      ${descriptionStyle}${descriptions[index]}${c.reset}`;
+  }).join('\n');
+}
+
+export function moveUpdateSelection(selectedIndex, keyName) {
+  if (keyName === 'up') {
+    return (selectedIndex - 1 + UPDATE_ACTIONS.length) % UPDATE_ACTIONS.length;
+  }
+  if (keyName === 'down') return (selectedIndex + 1) % UPDATE_ACTIONS.length;
+  return selectedIndex;
+}
+
+export async function selectUpdateAction(options = {}) {
+  const input = options.input || process.stdin;
+  const output = options.output || process.stderr;
+  const initiallyRaw = input.isRaw === true;
+  let selectedIndex = options.selectedIndex ?? 0;
+  const instructions = `  ${c.dim}Use ↑/↓ to select • Enter to confirm${c.reset}`;
+  const render = () =>
+    `${renderUpdateOptions(selectedIndex, {
+      installedVersion: options.installedVersion,
+      latestVersion: options.latestVersion,
+    })}\n\n${instructions}`;
+  const renderedLineCount = render().split('\n').length;
+
+  readline.emitKeypressEvents(input);
+  input.setRawMode(true);
+  input.resume();
+  output.write(`\x1b[?25l${render()}`);
+
+  return new Promise((resolve) => {
+    const finish = (action) => {
+      input.off('keypress', onKeypress);
+      if (!initiallyRaw) input.setRawMode(false);
+      input.pause();
+      output.write('\n\x1b[?25h');
+      resolve(action);
+    };
+
+    const onKeypress = (_character, key = {}) => {
+      if (key.ctrl && key.name === 'c') {
+        process.exitCode = 130;
+        finish('cancel');
+        return;
+      }
+      if (key.name === 'return' || key.name === 'enter') {
+        finish(selectedIndex === 0 ? 'update' : 'skip');
+        return;
+      }
+
+      const nextIndex = moveUpdateSelection(selectedIndex, key.name);
+      if (nextIndex === selectedIndex) return;
+      selectedIndex = nextIndex;
+      output.write(`\r\x1b[${renderedLineCount - 1}A\x1b[0J${render()}`);
+    };
+
+    input.on('keypress', onKeypress);
+  });
+}
+
+export async function installLatest(options = {}) {
+  const spawnImpl = options.spawnImpl || spawn;
+  return new Promise((resolve) => {
+    const child = spawnImpl('npm', ['install', '-g', `${PACKAGE_NAME}@latest`], {
+      stdio: 'inherit',
+    });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => resolve(code === 0));
+  });
+}
+
+export async function showUpdateNotice(options = {}) {
+  const disabled =
+    options.disabled ?? process.env.SUBC_DISABLE_UPDATE_CHECK?.trim() === '1';
+  if (disabled) return null;
+
+  try {
+    const installedVersion = options.currentVersion || (await currentVersion());
+    const latestVersion =
+      options.latestVersion ||
+      (await fetchLatestVersion({
+        fetchImpl: options.fetchImpl,
+        timeoutMs: options.timeoutMs,
+      }));
+    if (compareVersions(latestVersion, installedVersion) <= 0) return null;
+
+    const notice = renderUpdateNotice(installedVersion, latestVersion);
+    const write = options.write || ((text) => process.stderr.write(text));
+    write(`\n${notice}\n\n`);
+
+    const interactive =
+      options.interactive ?? (process.stdin.isTTY === true && process.stderr.isTTY === true);
+    if (!interactive) return { installedVersion, latestVersion, action: 'skip' };
+
+    const select = options.select || selectUpdateAction;
+    const action = await select({ installedVersion, latestVersion });
+    if (action === 'cancel') return { installedVersion, latestVersion, action };
+    if (action === 'skip') {
+      write(`\n  ${c.dim}Skipping update.${c.reset}\n\n`);
+      return { installedVersion, latestVersion, action };
+    }
+
+    write(`\n  ${c.cyan}Updating ${PACKAGE_NAME} to ${latestVersion}...${c.reset}\n\n`);
+    const install = options.install || installLatest;
+    const installed = await install();
+    if (installed) {
+      write(
+        `\n  ${c.green}${c.bold}Update complete.${c.reset} Re-run your subc command.\n\n`,
+      );
+      return { installedVersion, latestVersion, action: 'updated' };
+    }
+
+    write(`\n  ${c.red}Update failed.${c.reset} Try it manually:\n\n`);
+    write(`    ${c.cyan}npm install -g ${PACKAGE_NAME}@latest${c.reset}\n\n`);
+    return { installedVersion, latestVersion, action: 'failed' };
+  } catch {
+    // Update discovery must never prevent the requested command from running.
+    return null;
+  }
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "subconscious-cli",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "CLI for Subconscious — run Claude Code, Codex, OpenCode, Cursor, Copilot, and Pi",
   "bin": {
-    "subc": "./bin/cli.js"
+    "subc": "bin/cli.js"
   },
   "scripts": {
     "test": "node --test"
@@ -17,7 +17,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/subconscious-systems/subconscious.git",
+    "url": "git+https://github.com/subconscious-systems/subconscious.git",
     "directory": "cli"
   },
   "keywords": [