subconscious-cli 6.1.0 → 6.2.0

package/README.md

@@ -4,25 +4,59 @@ Log in to Subconscious, then run coding agents against the Subconscious gateway.
 
 ## Quick start
 
+Install with npm:
+
 ```bash
 npm install -g subconscious-cli
+```
+
+Or install on macOS or Linux without npm:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/subconscious-systems/subconscious/main/scripts/install.sh | bash
+```
+
+Then log in and launch an agent:
+
+```bash
 subc login
-subc marathon
+subc opencode
 subc claude
 ```
 
+The curl installer downloads the `subconscious-cli` tarball from the npm
+registry, checks it against the registry's integrity hash, and installs it in
+`~/.local/share/subconscious-cli` with a `subc` link in `~/.local/bin`. It does
+not need npm, so a registry policy that blocks `npm install -g` does not stop
+it. Node.js 18 or newer must already be installed, because `subc` runs on it.
+If `~/.local/bin` is not on your `PATH`, the installer prints the line to add.
+Run it again to reinstall or update. These variables change its defaults:
+
+| Variable | Default |
+| --- | --- |
+| `SUBC_VERSION` | `latest` (a version such as `6.1.0`, or a dist-tag) |
+| `SUBC_INSTALL_DIR` | `~/.local/share/subconscious-cli` |
+| `SUBC_BIN_DIR` | `~/.local/bin` |
+| `SUBC_REGISTRY` | `https://registry.npmjs.org` |
+
+On Windows, use npm (see [Native Windows support](#native-windows-support)).
+
+subc does not install the coding agents. Install each agent you use from its
+vendor. If an agent is missing, `subc <agent>` prints its install command and
+official install page, then exits with status 127.
+
 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.
+Update runs `npm install -g subconscious-cli@latest`, or the curl installer
+again if that is how subc was installed; 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 Subconscious Code, Claude Code, Codex, OpenCode, and DeepSeek Harness can launch immediately.
+so OpenCode, Claude Code, Codex, and DeepSeek Harness can launch immediately.
 Persistent editor and Pi integrations are installed per agent:
 
 ```bash
@@ -53,8 +87,8 @@ Every command accepts `help` as a subcommand. These only read the selected
 profile; they do not authenticate, install, configure, or launch anything:
 
 ```bash
+subc opencode help
 subc claude help
-subc marathon help
 subc codex help
 subc cursor help
 subc config help
@@ -69,7 +103,6 @@ gateway environment applied for that process. Arguments pass through as usual:
 
 ```bash
 subc claude --continue
-subc marathon -- -p "fix the tests"
 subc codex exec "write a test"
 subc opencode
 subc pi
@@ -105,8 +138,9 @@ Update with `npm.cmd install -g subconscious-cli@latest` or `subc.cmd upgrade --
 
 If PowerShell's execution policy blocks npm-generated `.ps1` entry points, use
 `npm.cmd` and `subc.cmd` or run the same commands in Command Prompt. No policy
-change is required. Pi must already be installed; other terminal agents offer
-their Windows installer when missing in an interactive terminal.
+change is required. subc does not install the agents on Windows either. If an
+agent is missing, subc prints its install command and official install page,
+then exits with status 127.
 
 Native executables and standard npm `.cmd` shims are supported. The launcher
 invokes the underlying executable or Node entry point directly, preserving
@@ -129,19 +163,6 @@ VS Code's secret store and prompts for its key. Its configuration goes under
 `%APPDATA%\Code\User` (or Code - Insiders/VSCodium). Rerun install after moving
 your Node installation, because hooks record the absolute Node executable path.
 
-To install the native x64 `marathon.exe` (stable releases starting with 0.1.4), clear
-any preview version pin from the current PowerShell session:
-
-```powershell
-Remove-Item Env:SC_CODE_VERSION -ErrorAction SilentlyContinue
-subc.cmd marathon install
-subc.cmd marathon
-```
-
-The installer requires the selected release's Windows asset and SHA-256
-checksum; it reports a clear error if unavailable and never downloads a Unix
-binary as a fallback. Windows ARM64 binaries are not currently published.
-
 Run `npm run test:windows` from the repository root for the separate Windows suite. The
 Windows CI job also builds/tests the Go TUI. Existing Unix tests and runbooks
 remain separate and unchanged.
@@ -152,18 +173,17 @@ The packaged integrations live in `bin/runbook`.
 
 | Command | Behavior |
 | --- | --- |
-| `subc marathon` | Launch Subconscious Code with the active gateway, key, model, and DLR transport |
+| `subc opencode` | Launch OpenCode with the runbook provider, client header, and context/output limits |
 | `subc claude` | Launch Claude Code with the runbook environment, context limits, subagent limits, and OTEL usage reporting |
 | `subc codex` | Launch Codex with the runbook provider, temporary model catalog, and surgically merged compaction hooks |
-| `subc opencode` | Launch OpenCode with the runbook provider, client header, and context/output limits |
-| `subc cursor install` | Install/update Cursor conversation and compaction hooks |
+| `subc cursor install` | Install/update Cursor conversation and compaction hooks (Cursor desktop app and IDE only — the Cursor CLI is not supported) |
 | `subc copilot install` | Install/update the VS Code custom endpoint and Copilot hooks |
 | `subc pi` | Refresh the Pi provider from the live catalog, then launch |
 | `subc dsh` | Launch the DeepSeek Harness Web UI with a temporary provider populated from the live catalog |
 
 ## Headless runs
 
-`subc <agent> headless PROMPT [args...]` runs one task without a terminal UI and exits with the agent's status. It works for `claude`, `codex`, `opencode`, `pi`, `marathon`, and `dsh`, and uses the same setup as an interactive launch. It never prompts: there is no update check, a missing agent fails with its install command, stdin is not read, and stdout carries only the agent's own output. Remaining arguments go to the agent, for example `subc claude headless "fix the failing test" --output-format stream-json --verbose`. subc reads `-p`/`--profile` and `--model` itself; put agent options with those names after `--`.
+`subc <agent> headless PROMPT [args...]` runs one task without a terminal UI and exits with the agent's status. It works for `claude`, `codex`, `opencode`, `pi`, and `dsh`, and uses the same setup as an interactive launch. It never prompts: there is no update check, a missing agent fails with its install command, stdin is not read, and stdout carries only the agent's own output. Remaining arguments go to the agent, for example `subc claude headless "fix the failing test" --output-format stream-json --verbose`. subc reads `-p`/`--profile` and `--model` itself; put agent options with those names after `--`.
 
 The agents keep their own permission defaults, so a run that should edit files usually needs the agent's permission flags in `[args...]`. For example, `codex exec` uses a read-only sandbox and requires a git repository unless given `--skip-git-repo-check`.
 
@@ -188,7 +208,6 @@ The endpoint must speak the same APIs as the Subconscious gateway: Anthropic Mes
 | `codex` | `codex exec -- PROMPT` |
 | `opencode` | `opencode run`, with the prompt on stdin |
 | `pi` | `pi --print`, with the prompt on stdin |
-| `marathon` | `marathon --print=PROMPT` |
 | `dsh` | `dsh --profile headless`, with the prompt on stdin |
 
 The prompt is always the argument after `headless`, including for `dsh`, which no longer reads a task piped into subc. Where the table says stdin, subc passes the prompt that way so it reaches the agent unchanged even when it starts with `-` or `@`. On Windows only `dsh` supports headless runs.
@@ -222,7 +241,7 @@ Each `harnesses.<id>` entry has:
 
 | Field | Meaning |
 | --- | --- |
-| `install` | `method`, `package` or `repository`, `version` or `channel`, `minimum_version`, release `targets`, and the per-OS `commands`. |
+| `install` | `method`, `package` or `repository`, `version` or `channel`, `minimum_version`, release `targets`, the per-OS `commands`, and `url`, the vendor's official install page. subc shows `commands` and `url` and never runs them. |
 | `prerequisites` | Commands the runbook needs, such as `jq`, with what needs them and whether they are required. `a\|b` means either one. |
 | `binary` | Executable name, or `null` for IDE integrations. |
 | `launch` | `argv` template, `headless_argv` for `subc <agent> headless` (absent when unsupported), `headless_stdin` when the prompt is passed on stdin instead, `headless_platforms` (`darwin`, `linux`, `win32`) where it works, `resume` and `handoff` argv for `subc sessions`, Codex's `config_flag`, and whether a launch also writes persistent files. |
@@ -240,7 +259,7 @@ Enumerated values:
 
 | Field | Values |
 | --- | --- |
-| `install.method` | `npm`, `script`, `github-release`, `user`, `null` |
+| `install.method` | `npm`, `user`, `null` |
 | `compaction.default` | `on`, `unknown` |
 | knob `kind` | `env`, `cli-config`, `config-field`, `model-catalog-field`, `null` |
 | `threshold.semantics` | `window`, `trigger` |
@@ -293,7 +312,7 @@ subc sessions resume codex:SESSION_ID --harness opencode
 ```
 
 The catalog discovers recent sessions written locally by Claude Code, Codex,
-OpenCode, Pi, and Subconscious Code. It shows each session's originating
+OpenCode, and Pi. It shows each session's originating
 harness, title, last activity, project directory, and model when the harness
 records one. Selecting the original harness uses its native resume mechanism.
 
@@ -309,26 +328,12 @@ conversation stores do not expose a stable local resume interface. A session
 whose local transcript is missing remains available for native resume but does
 not offer cross-harness destinations.
 
-If Subconscious Code, Claude Code, Codex, OpenCode, or DeepSeek Harness is missing, an interactive terminal offers
-to install it before launching. Pi refreshes its Subconscious provider on every
+subc never installs OpenCode, Claude Code, Codex, DeepSeek Harness, or Pi. If
+one is missing, subc prints its install command and official install page, then
+exits with status 127, in interactive and headless runs alike. Pi refreshes its Subconscious provider on every
 `subc pi` launch while preserving all other providers in `models.json`; its
 executable must already be installed.
 
-`subc marathon install` detects the operating system and architecture, then downloads
-and checksum-verifies the matching precompiled release from
-`subconscious-systems/subconscious-code`. Apple Silicon and Intel macOS plus
-x86_64 and ARM64 Linux and Windows x64 are supported; Cargo is not required.
-
-Starting with CLI 4.1.1, `subc marathon` is the native agent command. On Windows,
-the installer writes `marathon.exe`, avoiding the system `sc.exe` command.
-`subc sc` remains a compatibility alias but never launches Windows service
-control. Older pinned release binaries are also installed as `marathon.exe`.
-Starting with CLI 4.1.2 and native agent 0.1.6, macOS and Linux also install
-and launch `marathon`. Existing `.sc` settings, sessions, and `SC_*` variables
-are preserved on every platform. Shell behavior is unchanged. Older Unix
-release archives are installed under the new name; existing `sc` files are
-left untouched. `subc sc` remains a compatibility alias on every platform.
-
 `subc codex` disables Codex apps and plugin tools for that launch by default so
 requests remain below the gateway's 128-tool limit. Core coding tools remain
 available. Use `subc codex --external-tools` to opt back in when targeting a
@@ -383,7 +388,7 @@ rewritten. Run a one-shot task with `subc dsh headless "PROMPT"`.
 ```
 
 The file is mode `600` and contains the shared gateway URL, API key, model,
-optional per-agent key overrides, and all Subconscious Code/Claude/Codex/OpenCode/Pi/Copilot/
+optional per-agent key overrides, and all Claude/Codex/OpenCode/Pi/Copilot/
 DeepSeek Harness context and output settings used by the packaged runbook scripts.
 
 ```bash

package/bin/agent-data.js

@@ -77,6 +77,30 @@ function validateLaunch(launch, where) {
   }
 }
 
+function validateInstall(install, where) {
+  check(isObject(install), where, 'install block is required');
+  check(
+    typeof install.url === 'string' && install.url.startsWith('https://'),
+    where,
+    'install.url must be an https:// link to the official install page',
+  );
+  const { commands } = install;
+  if (commands === null) return;
+  check(
+    isObject(commands),
+    where,
+    'install.commands must be an object or null',
+  );
+  for (const [os, command] of Object.entries(commands)) {
+    check(PLATFORMS.has(os), where, `install.commands.${os} is not an OS`);
+    check(
+      typeof command === 'string' && command,
+      where,
+      `install.commands.${os}`,
+    );
+  }
+}
+
 function validateRunbook(runbook, where) {
   check(isObject(runbook), where, 'runbook block is required');
   check(MODES.has(runbook.mode), where, `bad runbook.mode ${runbook.mode}`);
@@ -101,7 +125,7 @@ export function validateAgent(agent, id) {
   for (const key of ['command', 'name', 'description', 'protocol'])
     check(typeof agent[key] === 'string' && agent[key], where, `${key}`);
   check(isStringList(agent.aliases), where, 'aliases must be a list');
-  check(isObject(agent.install), where, 'install block is required');
+  validateInstall(agent.install, where);
   check(isObject(agent.help), where, 'help block is required');
   check(Array.isArray(agent.help.options), where, 'help.options');
   validateRunbook(agent.runbook, where);
@@ -176,6 +200,18 @@ export function installCommands(agent) {
   );
 }
 
+/**
+ * The install command and official install page to show when the agent's
+ * binary is missing. subc prints these and never runs them. Windows never
+ * borrows the Linux command.
+ */
+export function installAdvice(agent, platform = process.platform) {
+  const commands = installCommands(agent);
+  const command =
+    commands?.[platform] ?? (platform === 'win32' ? null : commands?.linux);
+  return { command: command ?? null, url: agent.install.url };
+}
+
 /** The API key input that overrides API_KEY for this agent, if any. */
 export function agentKeyName(agent) {
   return (

package/bin/agent-help.js

@@ -1,7 +1,9 @@
 import {
+  agentBinary,
   agentCommandName,
   agentInputs,
   agentSetupActions,
+  installAdvice,
 } from './agent-data.js';
 import { c } from './colors.js';
 import { profileSettingsForAgent, resolvedProfileValues } from './profiles.js';
@@ -72,12 +74,18 @@ function printSetupHints(agent, profile) {
   console.log(
     `\n  Edit the env file with ${c.cyan}subc -p ${profile?.name || 'default'} config edit${c.reset}.`,
   );
+  if (agentBinary(agent)) {
+    const { command: install, url } = installAdvice(agent);
+    const how = install
+      ? `with ${c.cyan}${install}${c.reset}, or see ${c.cyan}${url}${c.reset}`
+      : `from ${c.cyan}${url}${c.reset}`;
+    console.log(`  subc doesn't install ${agent.name}. Install it ${how}.`);
+  }
   const actions = agentSetupActions(agent);
   if (actions.includes('install')) {
-    const what = agent.runbook.binary_install_script
-      ? 'Install the agent binary with'
-      : 'Install the persistent integration with';
-    console.log(`  ${what} ${c.cyan}subc ${command} install${c.reset}.`);
+    console.log(
+      `  Install the persistent integration with ${c.cyan}subc ${command} install${c.reset}.`,
+    );
   }
   if (actions.includes('uninstall')) {
     console.log(

package/bin/agent-install.js

@@ -1,4 +1,4 @@
-import { execFileSync, spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { constants as fsConstants } from 'node:fs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
@@ -9,26 +9,11 @@ import {
   agentById,
   agentCommandName,
   agentInstallDirs,
-  installCommands,
+  installAdvice,
 } from './agent-data.js';
-import { runbookScriptPath } from './agent-spawn.js';
 import { c } from './colors.js';
 import { compareVersions } from './update-check.js';
 
-/**
- * The install command for this OS, falling back to the Linux one, then any
- * command present; plus the optional fallback command.
- */
-export function resolveInstall(agent) {
-  const commands = installCommands(agent);
-  if (!commands) return { command: undefined, fallback: undefined };
-  const command =
-    commands[process.platform] ||
-    commands.linux ||
-    Object.entries(commands).find(([os]) => os !== 'fallback')?.[1];
-  return { command, fallback: commands.fallback };
-}
-
 /**
  * Common locations a freshly-installed coding-agent binary lands in but which
  * are often NOT on the current process's PATH (e.g. aider/claude install into
@@ -139,21 +124,6 @@ export function augmentPath(
   ].join(path.delimiter);
 }
 
-/** Ask a yes/no question on the TTY. Empty answer counts as yes. */
-function askYesNo(question) {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-    });
-    rl.question(question, (answer) => {
-      rl.close();
-      const a = answer.trim().toLowerCase();
-      resolve(a === '' || a === 'y' || a === 'yes');
-    });
-  });
-}
-
 function waitForEnter(prompt) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -167,113 +137,33 @@ function waitForEnter(prompt) {
   });
 }
 
-/** Run the agent's packaged binary installer, or its shell install command. */
-function runInstaller(
-  agent,
-  install = resolveInstall(agent).command,
-  usePackagedScript = true,
-) {
-  return new Promise((resolve) => {
-    const installScript =
-      usePackagedScript && agent.runbook.binary_install_script;
-    const child = installScript
-      ? spawn('bash', [runbookScriptPath(agent, installScript), 'install'], {
-          stdio: 'inherit',
-        })
-      : spawn(install, { shell: true, stdio: 'inherit' });
-    child.on('error', () => resolve(false));
-    child.on('exit', (code) => resolve(code === 0));
-  });
-}
-
-/** Print the resolved install command (plus any fallback) for an agent. */
-function printInstallCommands(agent) {
-  const { command, fallback } = resolveInstall(agent);
-  console.error(`    ${c.cyan}${command}${c.reset}`);
-  if (fallback) {
-    console.error(`  ${c.dim}or, as a fallback:${c.reset}`);
-    console.error(`    ${c.cyan}${fallback}${c.reset}`);
-  }
-  console.error('');
+/** Print the install command and official install page; subc runs neither. */
+function printInstallAdvice(agent) {
+  const { command, url } = installAdvice(agent);
+  if (command) console.error(`    ${c.cyan}${command}${c.reset}`);
+  console.error(
+    `  ${c.dim}Official install page:${c.reset} ${c.cyan}${url}${c.reset}\n`,
+  );
 }
 
 /**
- * Ensure the agent's binary is resolvable. If missing:
- *   - interactive TTY: offer to run the per-OS installer (with fallback), then
- *     re-resolve against PATH + candidate dirs.
- *   - non-interactive: print the resolved install command (+ fallback) and
- *     exit 127 without running anything.
- *
- * Returns the directory containing the bin (to prepend to the child's PATH) on
- * success. May exit the process on failure or when manual action is needed.
+ * Return the directory that holds the agent's binary. subc never installs a
+ * third-party agent: when the binary is missing it prints how to install it
+ * and exits 127, in every shell.
  */
-export async function ensureInstalled(agent, { mayPrompt = true } = {}) {
+export async function ensureInstalled(agent) {
   const bin = agentBinary(agent);
-  const { command: install, fallback } = resolveInstall(agent);
-  const preferredDirs = preferredBinDirsForAgent(agent);
-  const existing = await resolveBinPath(bin, preferredDirs);
+  const existing = await resolveBinPath(bin, preferredBinDirsForAgent(agent));
   if (existing) return existing;
 
-  // Agents without an installer are launch-only. Their setup integration may
-  // configure the provider, but `subc <agent>` must never install the binary.
-  if (!install) {
-    console.error(
-      `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
-    );
-    console.error(
-      `  Install ${agent.name} separately, then re-run ${c.cyan}subc ${agentCommandName(agent)}${c.reset}.\n`,
-    );
-    process.exit(127);
-  }
-
-  const interactive = mayPrompt && process.stdin.isTTY && process.stdout.isTTY;
-
-  if (!interactive) {
-    console.error(
-      `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
-    );
-    console.error(`  Install it with:\n`);
-    printInstallCommands(agent);
-    process.exit(127);
-  }
-
-  console.error(`\n  ${c.bold}${agent.name}${c.reset} isn't installed.`);
-  const ok = await askYesNo(`  Install it now? ${c.dim}[Y/n]${c.reset} `);
-  if (!ok) {
-    console.error(`\n  No problem. Install it yourself with:\n`);
-    printInstallCommands(agent);
-    process.exit(127);
-  }
-
   console.error(
-    `\n  ${c.dim}Running ${c.reset}${c.cyan}${install}${c.reset}\n`,
+    `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
   );
-  let installed = await runInstaller(agent);
-
-  // Primary failed and a fallback exists — try it once.
-  if (!installed && fallback) {
-    console.error(
-      `\n  ${c.dim}That didn't work. Trying the fallback: ${c.reset}${c.cyan}${fallback}${c.reset}\n`,
-    );
-    installed = await runInstaller(agent, fallback, false);
-  }
-
-  if (!installed) {
-    console.error(`\n  ${c.red}Install failed.${c.reset} Try it manually:\n`);
-    printInstallCommands(agent);
-    process.exit(127);
-  }
-
-  // PATH hardening: the freshly-installed binary is often not on the current
-  // process's PATH. Re-resolve against PATH + candidate dirs.
-  const found = await resolveBinPath(bin, preferredDirs);
-  if (found) return found;
-
   console.error(
-    `\n  ${c.dim}Installed ${agent.name}, but it isn't on this shell's PATH yet. ` +
-      `Open a new terminal (or add a bin dir to PATH) and re-run \`subc ${agentCommandName(agent)}\`.${c.reset}\n`,
+    `  subc doesn't install ${agent.name}. Install it yourself, then re-run ${c.cyan}subc ${agentCommandName(agent)}${c.reset}.\n`,
   );
-  process.exit(0);
+  printInstallAdvice(agent);
+  process.exit(127);
 }
 
 export function parseClaudeVersion(text) {
@@ -335,14 +225,8 @@ export async function ensureMinimumVersion(
   console.error(
     `\n  Minimum supported ${agent.name} version is ${minimum}. Your version is ${version}. Upgrade to get the best experience.\n`,
   );
-  const { command, fallback } = resolveInstall(agent);
   console.error(`  Upgrade it with:`);
-  console.error(`    ${c.cyan}${command}${c.reset}`);
-  if (fallback) {
-    console.error(`  or`);
-    console.error(`    ${c.cyan}${fallback}${c.reset}`);
-  }
-  console.error('');
+  printInstallAdvice(agent);
   if (
     mayPrompt &&
     process.stdin.isTTY === true &&

package/bin/agents.js

@@ -283,7 +283,8 @@ export const RUNBOOK_ENV_DESCRIPTION = Object.freeze({
     {
       name: 'SUBCONSCIOUS_MODELS',
       value: '{catalog}',
-      description: 'Newline-separated live model catalog.',
+      description:
+        'Newline-separated model catalog. Set by the caller, it pins the catalog and skips live discovery; otherwise it is the live catalog.',
     },
     {
       name: 'PATH',
@@ -362,6 +363,7 @@ async function resolvedModelsForLaunch(profile, apiKey, selectedModel) {
     apiKey,
     selectedModel,
     fallbackModels: PACKAGED_MODELS,
+    pinnedModels: process.env.SUBCONSCIOUS_MODELS,
   });
   if (catalog.source === 'public' && apiKey) {
     console.error(`  ${c.dim}${PUBLIC_CATALOG_FALLBACK_MESSAGE}${c.reset}\n`);
@@ -390,7 +392,7 @@ export function selectLaunchModel(requestedModel, modelSource, catalog) {
 async function runRunbookSetup(agent, argv, profile) {
   const script = agent.runbook.setup_script;
   if (isSetupWithoutAuth(argv) || agent.runbook.setup_needs_auth === false) {
-    // Status, uninstall, and Marathon's binary install read no model or
+    // Status and uninstall read no model or
     // agent setting, so an invalid saved one must not block them.
     const lenient = { strict: false };
     const base = { ...(profile?.values || {}), ...process.env };
@@ -521,9 +523,8 @@ async function launchAgent(agent, argv, profile, headless) {
   const apiKey = await requireApiKey(profile, agent);
   if (!apiKey) return 1;
 
-  const mayPrompt = !headless;
-  const binDir = await ensureInstalled(agent, { mayPrompt });
-  await ensureMinimumVersion(agent, binDir, { mayPrompt });
+  const binDir = await ensureInstalled(agent);
+  await ensureMinimumVersion(agent, binDir, { mayPrompt: !headless });
   const catalog = await resolvedModelsForLaunch(
     profile,
     apiKey,

package/bin/cli.js

@@ -159,7 +159,8 @@ Usage:
   subc upgrade --latest
   subc upgrade help
 
-Upgrade subconscious-cli to the latest published version.
+Upgrade subconscious-cli to the latest published version, the same way it
+was installed: npm (or pnpm, yarn, bun), or the curl installer.
 
   subc upgrade           Prompt "Do you want to upgrade?" then install @latest
   subc upgrade --latest  Skip the prompt and install @latest

package/bin/models.js

@@ -175,10 +175,22 @@ export async function resolveModelCatalog({
   apiKey,
   selectedModel,
   fallbackModels = [],
+  pinnedModels,
   fetchImpl = globalThis.fetch,
   timeoutMs = DEFAULT_MODEL_FETCH_TIMEOUT_MS,
   signal,
 }) {
+  // A caller that names its catalog (a benchmark run, a CI job) needs the same
+  // models on every launch, whatever the gateway lists that day.
+  const pinned = pinnedModels?.split(/\r?\n/).filter((id) => id.trim());
+  if (pinned?.length) {
+    return {
+      models: normalizeModelIds(pinned, selectedModel),
+      source: 'pinned',
+      error: null,
+    };
+  }
+
   const key = apiKey?.trim() || '';
 
   if (key) {

package/bin/runbook/README.md

@@ -8,7 +8,6 @@ the default gateway, model capabilities, and the settings every agent uses
 
 | Agent | Launch | Setup |
 | --- | --- | --- |
-| `subconscious-code` (Marathon) | binary | `install.sh` (binary installer) |
 | `claude-code` | binary | `install.sh` (leftover status/uninstall) |
 | `codex` | `run.sh` | `install.sh` (hooks) |
 | `opencode` | binary | `install.sh` (leftover status/uninstall) |
@@ -22,7 +21,7 @@ the default gateway, model capabilities, and the settings every agent uses
 | Field | Read by |
 | --- | --- |
 | `id`, `command`, `aliases`, `name`, `description` | routing, `subc help`, the TUI menu |
-| `install` | the installer prompt, `--version` warning (`minimum_version`), Windows installs; `{package}` fills in the commands |
+| `install` | the missing-agent message, agent help, and the upgrade warning (`minimum_version`); `{package}` fills in `commands` |
 | `runbook` | which script launches the agent (none means the binary is run directly) and which setup actions exist |
 | `help` | `subc <agent> help`; flags with a `help` text are added from `inputs` |
 | `sessions`, `launch.resume`, `launch.handoff` | `subc sessions resume` |
@@ -32,6 +31,18 @@ the default gateway, model capabilities, and the settings every agent uses
 | `config` | `cli-config` entries become `config_flag NAME=VALUE` (Codex `-c`) when `when` holds; other entries describe files the runbooks write |
 | `capabilities`, `prerequisites` | the harness manifest only |
 
+## Install data is display-only
+
+subc never installs an agent. When an agent's binary is missing, subc prints
+`install.commands` for the current OS and `install.url`, then exits with
+status 127. Windows never shows the Linux command. Rules for `install`, checked
+by `bin/agent-data.js` and `test/agent-install-policy.test.js`:
+
+- `url` is required: an `https://` link to the vendor's official install page.
+- `commands` is `null`, or an object keyed by `darwin`, `linux`, and `win32`.
+- A command is one the user can paste, such as `npm i -g {package}`. It never
+  pipes a downloaded script into a shell.
+
 Values may use `{baseUrl}`, `{baseUrlV1}`, `{apiKey}`, `{model}`, `{prompt}`,
 `{args}`, `{config}`, and `${NAME}` for another input or env entry.
 `subc harness-manifest --json` prints every agent file with `${NAME}` replaced

package/bin/runbook/claude-code/agent.json

@@ -8,15 +8,15 @@
   "homepage": "https://docs.anthropic.com/en/docs/claude-code",
   "install": {
     "commands": {
-      "darwin": "curl -fsSL https://claude.ai/install.sh | bash",
-      "linux": "curl -fsSL https://claude.ai/install.sh | bash",
-      "win32": "powershell -ExecutionPolicy Bypass -Command \"irm https://claude.ai/install.ps1 | iex\"",
-      "fallback": "npm i -g {package}"
+      "darwin": "npm i -g {package}",
+      "linux": "npm i -g {package}",
+      "win32": "npm i -g {package}"
     },
-    "method": "script",
+    "url": "https://code.claude.com/docs/en/setup",
+    "method": "npm",
     "package": "@anthropic-ai/claude-code",
     "version": null,
-    "channel": "installer default (unpinned)",
+    "channel": "latest (unpinned)",
     "minimum_version": "2.1.242",
     "verified": true,
     "note": "subc warns, and does not block, below minimum_version."

package/bin/runbook/codex/agent.json

@@ -12,6 +12,7 @@
       "linux": "npm i -g {package}",
       "win32": "npm i -g {package}"
     },
+    "url": "https://developers.openai.com/codex/cli",
     "method": "npm",
     "package": "@openai/codex",
     "version": null,