subconscious-cli 0.3.0 → 4.0.0

package/README.md

@@ -1,7 +1,6 @@
 # subconscious-cli
 
-Log in to Subconscious, then run coding agents with the setup maintained in
-[`ol-runbook`](https://github.com/subconscious-systems/ol-runbook).
+Log in to Subconscious, then run coding agents against the Subconscious gateway.
 
 ## Quick start
 
@@ -11,39 +10,35 @@ subc login
 subc claude
 ```
 
-Login creates both the saved credential and a ready-to-use `default` runbook
-profile, so Claude Code, Codex, and OpenCode can launch immediately. To apply
-the persistent runbook setup for all six supported agents together, run:
+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:
 
 ```bash
-subc setup
+subc cursor install
+subc copilot install
+subc pi install
+subc <agent> uninstall
 ```
 
 Top-level help (`subc`, `subc help`, or `subc --help`) displays the
 Subconscious logo as portable ASCII art. Set `NO_COLOR=1` for a
 monochrome version; redirected output automatically uses a plain wordmark.
 
-Each coding agent also has integration-specific help. These commands only read
-the selected profile; they do not authenticate, install, configure, or launch
-anything:
+Every command accepts `help` as a subcommand. These only read the selected
+profile; they do not authenticate, install, configure, or launch anything:
 
 ```bash
-subc help claude
+subc claude help
 subc codex help
-subc opencode --help
-subc help cursor
-subc help copilot
-subc pi -h
+subc cursor help
+subc config help
+subc login help
 ```
 
-Agent help includes launch/setup behavior, supported integration options, and
+Agent help includes launch/install behavior, supported integration options, and
 every relevant profile setting with API keys redacted.
 
-This writes the Claude environment file; Codex provider, catalog, and hooks;
-OpenCode provider and compaction plugin; Cursor and Copilot hooks; and Pi
-provider and compaction extension. It configures integrations but does not
-install the underlying desktop applications or agent binaries.
-
 `subc claude` launches the normal `claude` executable with the Subconscious
 gateway environment applied for that process. Arguments pass through as usual:
 
@@ -56,21 +51,21 @@ subc pi
 
 ## Supported agents
 
-The packaged integrations are synced from `ol-runbook/coding-agents`.
+The packaged integrations live in `cli/bin/runbook`.
 
 | Command | Behavior |
 | --- | --- |
 | `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 compaction hooks |
+| `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/update the runbook Cursor conversation and compaction hooks |
-| `subc copilot` | Install/update the runbook VS Code custom endpoint and Copilot hooks |
-| `subc pi` | Launch Pi with the Subconscious provider and active profile model; never installs or rewrites configuration |
+| `subc cursor install` | Install/update Cursor conversation and compaction hooks |
+| `subc copilot install` | Install/update the VS Code custom endpoint and Copilot hooks |
+| `subc pi install` then `subc pi` | Merge the Pi provider, then launch |
 
 If Claude Code, Codex, or OpenCode is missing, an interactive terminal offers
-to install it before launching. Pi is launch-only: if its executable or
-Subconscious configuration is missing, the CLI exits with instructions instead
-of installing or changing anything.
+to install it before launching. Pi requires `subc pi install` first; if its
+executable or Subconscious provider is missing, the CLI exits with instructions
+instead of installing the binary.
 
 `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
@@ -79,53 +74,33 @@ gateway with a larger tool limit. It also defaults reasoning effort to `max`,
 which is the highest effort accepted by the Subconscious models; override it
 with `subc codex --reasoning-effort high` when desired.
 
-Cursor and Copilot are setup commands because their runbook integrations write
-user-level configuration. Pi's provider and extension are managed only through
-the aggregate setup command:
+Persistent writes are merge/unmerge only. They never replace a user's
+`config.toml`, `opencode.json`, `models.json`, `hooks.json`, or VS Code
+provider list. Remove Subconscious files with the matching uninstall command:
 
 ```bash
-subc cursor status
 subc cursor uninstall
-subc copilot status
-```
-
-You can inspect or remove every persistent integration together too:
-
-```bash
-subc setup
-subc setup status
-subc setup uninstall
-```
-
-Target one integration by adding its command name. Agent-specific install
-options pass through to that integration:
-
-```bash
-subc setup codex
-subc setup codex status
-subc setup opencode uninstall
-subc setup codex --subagents
-subc setup claude --compact-window 900000
+subc copilot uninstall
+subc pi uninstall
+subc codex uninstall
+subc claude uninstall
+subc opencode uninstall
 ```
 
-Claude Code and Codex also expose the runbook's persistent environment helpers:
-
-```bash
-subc setup codex use -- --resume
-source <(subc setup codex env)
-source <(subc setup codex unset)
-```
+`subc claude uninstall` and `subc opencode uninstall` only clean leftover files
+from older overwrite-style setup. Launch those agents with `subc claude` /
+`subc opencode`; they do not need install.
 
-Run `subc setup AGENT --help` for that integration's complete persistent setup
-options. A one-off `--api-key` passed to targeted setup takes precedence for
-that command but is not saved to the selected profile.
+Inspect a persistent integration with `subc <agent> status`. A one-off
+`--api-key` passed to install takes precedence for that command but is not
+saved to the selected profile.
 
 Cursor still requires enabling its OpenAI API Key Override in Cursor Settings.
 Copilot requires entering the custom endpoint key once through VS Code's
-Manage Language Models UI. The setup scripts print the relevant next steps.
+Manage Language Models UI. The install scripts print the relevant next steps.
 
-The runbook scripts require Bash. Cursor and Copilot setup also require `jq`
-and `curl`; Pi setup requires `jq`.
+The runbook scripts require Bash. Cursor, Copilot, Pi, and Codex hook merge
+also require `jq`; Cursor and Copilot also require `curl`.
 
 ## Runbook profiles
 
@@ -137,50 +112,44 @@ and `curl`; Pi setup requires `jq`.
 
 The file is mode `600` and contains the shared gateway URL, API key, model,
 optional per-agent key overrides, and all Claude/Codex/OpenCode/Pi/Copilot
-context and output settings used by the packaged runbook scripts. You can
-inspect or update it through the CLI:
+context and output settings used by the packaged runbook scripts.
 
 ```bash
-subc config
-subc config --model subconscious/glm-5.2
+subc config                         # list every profile and its file path
+subc -p staging config              # print that path and env file
+subc -p staging config --model subconscious/glm-5.2
 subc config --gateway-url https://gateway.example
 subc config path
-subc config list
-```
-
-Use the interactive settings wizard to choose or create a profile and edit
-shared settings, one agent's complete settings section, or every setting:
-
-```bash
-subc settings
-subc --profile work settings
-subc --profile staging config interactive
+subc config edit                    # open the selected profile in $VISUAL, $EDITOR, vim, or nano
+subc -p staging config edit vim
+subc config edit nano
 ```
 
-The wizard validates URLs, numeric ranges, and enumerated values; masks API-key
-input; and does not write anything until you choose **Save and exit**. Press
-Ctrl-C or choose **Cancel** to discard pending changes. In scripts and CI, keep
-using `subc config --gateway-url`, `--api-key`, and `--model` or edit the
-mode-`600` profile directly.
+`subc config` lists each profile next to its `.env` path. `subc -p NAME config`
+prints that path, then the file (API keys and other secrets redacted). Extra
+`KEY=value` lines in the file are passed through to launches and override
+Subconscious-injected defaults; resolved login identity (`GATEWAY_URL`,
+`API_KEY`, `MODEL`) still comes from login, `--model`, and the matching flags.
+In scripts and CI, keep using `subc config --gateway-url`, `--api-key`, and
+`--model`.
 
 Each agent section can hold its own API key. An agent-specific key takes
 precedence over the shared profile key and can be used on its own, so profiles
 do not need an `API_KEY` when every configured agent has an explicit key.
 
-Named profiles work like mbta profiles:
+Named profiles work like AWS CLI profiles:
 
 ```bash
-subc --profile staging config \
+subc -p staging config \
   --gateway-url https://staging.example \
   --api-key sk-staging-... \
   --model subconscious/glm-5.2
 
-subc --profile staging claude
-subc --profile staging setup
+subc -p staging claude
+subc -p staging cursor install
 ```
 
-You can also select one with `SUBC_PROFILE=staging` (`MBTA_PROFILE` is accepted
-as a compatibility fallback). Explicit shell variables
+You can also select one with `SUBC_PROFILE=staging`. Explicit shell variables
 such as `SUBCONSCIOUS_API_KEY`, `SUBCONSCIOUS_BASE_URL`,
 `SUBCONSCIOUS_MODEL`, and agent-specific tuning variables override profile
 values. A command-line `--model` override has the highest model precedence.
@@ -208,8 +177,10 @@ 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` prints the complete list and the model
-selected by the active profile.
+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`.
 
 The default gateway is `https://api.subconscious.dev`. Profiles containing
 the former exact default (`https://api.subconscious.dev`) migrate automatically;
@@ -223,7 +194,8 @@ SUBCONSCIOUS_BASE_URL=http://localhost:9999 subc claude
 Agent-specific runbook tuning variables are also honored, including
 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, `CODEX_CONTEXT_WINDOW`,
 `OPENCODE_CONTEXT_LIMIT`, `PI_CONTEXT_WINDOW`, and the corresponding output or
-max-context settings.
+max-context settings. Extra `KEY=value` lines in the profile env file are
+passed through the same way and override Subconscious-injected defaults.
 
 ## Authentication
 

package/bin/agents.js

@@ -1,9 +1,9 @@
 /**
  * Coding-agent launcher.
  *
- * `subc <agent>` resolves your saved API key and dispatches the vendored
- * ol-runbook integration. Terminal agents launch ephemerally; IDE/config-based
- * agents run their setup scripts.
+ * `subc <agent>` resolves your saved API key and runs the packaged integration.
+ * Terminal agents launch ephemerally; IDE/config-based
+ * agents and Pi persist a surgical integration via `subc <agent> install`.
  *
  * There is NO hardcoded agent data here: everything is read from
  * `registry.generated.json` (shipped under `bin/`), which is generated from the
@@ -105,62 +105,61 @@ export function agentList() {
   }));
 }
 
-export function setupAgentList() {
-  return AGENTS.filter((agent) => agent.runbook?.setupScript);
+const SETUP_ACTIONS = new Set(['install', 'status', 'uninstall']);
+const DROPPED_SETUP_HELPERS = new Set(['use', 'env', 'unset']);
+
+export function agentSetupActions(agent) {
+  return Array.isArray(agent.runbook?.setupActions) ? agent.runbook.setupActions : [];
 }
 
-const SETUP_ACTIONS = new Set(['install', 'status', 'uninstall']);
-const SETUP_HELPER_ACTIONS = new Set(['use', 'env', 'unset']);
-const SETUP_HELPER_AGENT_IDS = new Set(['claude-code', 'codex']);
-
-export function parseSetupRequest(argv = []) {
-  const [first, ...rest] = argv;
-  if (!first || SETUP_ACTIONS.has(first)) {
-    if (rest.length) {
-      throw new Error('Agent-specific setup options require a target agent');
-    }
-    return {
-      agents: setupAgentList(),
-      args: first ? [first] : [],
-      action: first || 'install',
-      targeted: false,
-    };
-  }
+export function agentCommandName(agent) {
+  return agent.command || agent.id;
+}
+
+export function parseAgentAction(agent, argv = []) {
+  const command = agentCommandName(agent);
+  const first = argv[0];
+  const actions = agentSetupActions(agent);
 
-  const agent = resolveAgent(first);
-  if (!agent) throw new Error(`Unknown coding agent or setup action: ${first}`);
-  if (!agent.runbook?.setupScript) {
-    throw new Error(`No persistent setup integration is available for ${agent.name}`);
+  if (DROPPED_SETUP_HELPERS.has(first)) {
+    throw new Error(
+      `${agent.name} no longer supports '${first}'. Launch with subc ${command}.`,
+    );
   }
 
-  const requestedAction = rest[0];
-  const helperAction = SETUP_HELPER_ACTIONS.has(requestedAction);
-  if (helperAction && !SETUP_HELPER_AGENT_IDS.has(agent.id)) {
-    throw new Error(`${agent.name} does not support the '${requestedAction}' setup action`);
+  if (SETUP_ACTIONS.has(first)) {
+    if (!agent.runbook?.setupScript || !actions.includes(first)) {
+      if (first === 'install') {
+        const uninstallHint = actions.includes('uninstall')
+          ? ` To remove leftover files: subc ${command} uninstall.`
+          : '';
+        throw new Error(
+          `${agent.name} is launch-only. Run subc ${command}.${uninstallHint}`,
+        );
+      }
+      throw new Error(
+        `${agent.name} does not support '${first}'. Try subc ${command} help.`,
+      );
+    }
+    return { action: first, args: argv };
   }
-  if (
-    requestedAction &&
-    !requestedAction.startsWith('-') &&
-    !SETUP_ACTIONS.has(requestedAction) &&
-    !helperAction
-  ) {
-    throw new Error(`Unknown setup action for ${agent.name}: ${requestedAction}`);
+
+  if (agent.runbook?.mode === 'setup') {
+    return { action: 'install', args: argv };
   }
 
-  return {
-    agents: [agent],
-    args: rest,
-    action:
-      SETUP_ACTIONS.has(requestedAction) || helperAction ? requestedAction : 'install',
-    targeted: true,
-  };
+  return { action: 'launch', args: argv };
 }
 
 const AGENT_HELP = {
   'claude-code': {
-    usage: 'subc [--profile NAME] claude [integration options] [Claude arguments...]',
-    behavior: 'Launches Claude Code with the active Subconscious profile and model picker.',
+    usage: 'subc [-p NAME] claude [help|status|uninstall] [Claude arguments...]',
+    behavior:
+      'Launches Claude Code with the active Subconscious profile and model picker. Persistent files are leftover-only: subc claude uninstall.',
     options: [
+      ['help', 'Show this help'],
+      ['status', 'Inspect leftover ~/.claude/subconscious-gateway.env'],
+      ['uninstall', 'Remove leftover ~/.claude/subconscious-gateway.env'],
       ['--model MODEL', 'Override the profile model for this launch'],
       ['--compact-window N', 'Override the Claude auto-compact window'],
       ['--max-context-tokens N', 'Override the maximum context tokens'],
@@ -168,9 +167,14 @@ const AGENT_HELP = {
     ],
   },
   codex: {
-    usage: 'subc [--profile NAME] codex [integration options] [Codex arguments...]',
-    behavior: 'Launches Codex with a temporary Subconscious provider catalog and compaction hooks.',
+    usage: 'subc [-p NAME] codex [help|install|status|uninstall] [Codex arguments...]',
+    behavior:
+      'Launches Codex with a temporary Subconscious provider catalog. Compaction hooks are merged into ~/.codex/hooks.json and removed with subc codex uninstall.',
     options: [
+      ['help', 'Show this help'],
+      ['install', 'Install only the Subconscious compaction hooks'],
+      ['status', 'Inspect the installed compaction hooks'],
+      ['uninstall', 'Remove only the Subconscious Codex hooks'],
       ['--model MODEL', 'Override the profile model for this launch'],
       ['--context-window N', 'Override catalog context_window'],
       ['--max-context-window N', 'Override catalog max_context_window'],
@@ -182,35 +186,47 @@ const AGENT_HELP = {
     ],
   },
   opencode: {
-    usage: 'subc [--profile NAME] opencode [OpenCode arguments...]',
-    behavior: 'Launches OpenCode with an ephemeral provider containing every Subconscious model.',
+    usage: 'subc [-p NAME] opencode [help|status|uninstall] [OpenCode arguments...]',
+    behavior:
+      'Launches OpenCode with an ephemeral provider containing every Subconscious model. Persistent files are leftover-only: subc opencode uninstall.',
     options: [
+      ['help', 'Show this help'],
+      ['status', 'Inspect leftover OpenCode Subconscious config'],
+      ['uninstall', 'Remove only the Subconscious OpenCode provider and plugin'],
       ['--model MODEL', 'Override the profile model for this launch'],
       ['ARGS...', 'Pass arguments directly to OpenCode'],
     ],
   },
   cursor: {
-    usage: 'subc [--profile NAME] cursor [install|status|uninstall]',
-    behavior: 'Manages Cursor correlation hooks; model endpoint setup is completed in Cursor Settings.',
+    usage: 'subc [-p NAME] cursor [help|install|status|uninstall]',
+    behavior:
+      'Manages Cursor correlation hooks; model endpoint setup is completed in Cursor Settings.',
     options: [
+      ['help', 'Show this help'],
       ['install', 'Install or update the Cursor hooks (default action)'],
       ['status', 'Inspect the installed hook configuration'],
       ['uninstall', 'Remove only the Subconscious Cursor hooks'],
     ],
   },
   copilot: {
-    usage: 'subc [--profile NAME] copilot [install|status|uninstall]',
+    usage: 'subc [-p NAME] copilot [help|install|status|uninstall]',
     behavior: 'Manages the VS Code model provider and Copilot correlation hooks.',
     options: [
+      ['help', 'Show this help'],
       ['install', 'Install or update the provider and hooks (default action)'],
       ['status', 'Inspect the installed provider and hooks'],
       ['uninstall', 'Remove the Subconscious provider and hooks'],
     ],
   },
   pi: {
-    usage: 'subc [--profile NAME] pi [Pi arguments...]',
-    behavior: 'Launches Pi read-only against the provider previously configured by subc setup.',
+    usage: 'subc [-p NAME] pi [help|install|status|uninstall] [Pi arguments...]',
+    behavior:
+      'Launches Pi read-only against the provider previously configured by subc pi install.',
     options: [
+      ['help', 'Show this help'],
+      ['install', 'Merge the Subconscious provider into ~/.pi/agent/models.json'],
+      ['status', 'Inspect the persistent Pi provider'],
+      ['uninstall', 'Remove only the Subconscious Pi provider and extension'],
       ['--model MODEL', 'Override the profile model for this launch'],
       ['ARGS...', 'Pass arguments directly to Pi'],
     ],
@@ -256,9 +272,21 @@ export function printAgentHelp(agent, profile) {
     console.log(`    ${c.cyan}${setting.key.padEnd(settingWidth)}${c.reset}  ${value}`);
     console.log(`    ${' '.repeat(settingWidth)}  ${c.dim}${setting.description}${c.reset}`);
   }
-  console.log(`\n  Edit these interactively with ${c.cyan}subc --profile ${profile?.name || 'default'} settings${c.reset}.`);
-  if (agent.runbook?.setupScript) {
-    console.log(`  Apply persistent integration setup with ${c.cyan}subc setup ${agent.command || agent.id}${c.reset}.`);
+  const command = agentCommandName(agent);
+  const profileFlag = profile?.name || 'default';
+  console.log(
+    `\n  Edit the env file with ${c.cyan}subc -p ${profileFlag} config edit${c.reset}.`,
+  );
+  const actions = agentSetupActions(agent);
+  if (actions.includes('install')) {
+    console.log(
+      `  Install the persistent integration with ${c.cyan}subc ${command} install${c.reset}.`,
+    );
+  }
+  if (actions.includes('uninstall')) {
+    console.log(
+      `  Remove it with ${c.cyan}subc ${command} uninstall${c.reset}.`,
+    );
   }
   console.log();
 }
@@ -488,7 +516,7 @@ async function ensureInstalled(agent) {
   process.exit(0);
 }
 
-/** Resolve and validate a script inside the packaged ol-runbook snapshot. */
+/** Resolve and validate a script inside the packaged runbook directory. */
 function runbookScriptPath(agent, relativeScript = agent.runbook.script) {
   const script = path.resolve(RUNBOOK_DIR, relativeScript);
   const relative = path.relative(RUNBOOK_DIR, script);
@@ -507,7 +535,7 @@ function spawnRunbook(agent, args, env, relativeScript) {
     child.on('error', (error) => {
       if (error.code === 'ENOENT') {
         reject(
-          new Error('The ol-runbook integrations require `bash`, but it was not found on PATH.'),
+          new Error('These coding-agent integrations require `bash`, but it was not found on PATH.'),
         );
         return;
       }
@@ -526,7 +554,7 @@ function spawnRunbook(agent, args, env, relativeScript) {
 }
 
 function isSetupWithoutAuth(argv) {
-  return ['status', 'uninstall', 'use', 'env', 'unset', '-h', '--help'].includes(argv[0]);
+  return ['status', 'uninstall', '-h', '--help', 'help'].includes(argv[0]);
 }
 
 function optionValue(argv, name) {
@@ -593,20 +621,20 @@ function claudeModelPickerEnv(agent, ctx) {
   );
 }
 
-function runbookEnv(apiKey, model, binDir, profile, agent) {
+export function runbookEnv(apiKey, model, binDir, profile, agent) {
   const ctx = buildContext(apiKey, model, profile);
   const extraDirs = [binDir, ...candidateBinDirs()].filter(Boolean);
   const specificApiKey = agentApiKeySetting(agent)?.key;
   return {
+    ...claudeModelPickerEnv(agent, ctx),
     ...(profile?.values || {}),
     ...process.env,
-    ...claudeModelPickerEnv(agent, ctx),
     GATEWAY_URL: ctx.baseUrl,
     API_KEY: apiKey,
     ...(specificApiKey ? { [specificApiKey]: apiKey } : {}),
     MODEL: model,
     SUBCONSCIOUS_MODELS: SUPPORTED_MODELS.join('\n'),
-    MBTA_ENV_FILE: os.devNull,
+    SUBC_ENV_FILE: os.devNull,
     PATH: augmentPath(extraDirs),
   };
 }
@@ -616,7 +644,7 @@ async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runb
     return spawnRunbook(agent, argv, {
       ...(profile?.values || {}),
       ...process.env,
-      MBTA_ENV_FILE: os.devNull,
+      SUBC_ENV_FILE: os.devNull,
     }, relativeScript);
   }
 
@@ -638,19 +666,7 @@ async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runb
   const installed = !['status', 'uninstall'].includes(rest[0]);
   if (code !== 0 || !installed) return code;
 
-  if (agent.id === 'cursor') {
-    const modelList = SUPPORTED_MODELS.map(
-      (supportedModel) => `    ${c.cyan}${supportedModel}${c.reset}`,
-    ).join('\n');
-    console.log(
-      `\n  ${c.bold}Finish in Cursor Settings${c.reset}\n` +
-        `  Enable OpenAI API Key Override, then use:\n` +
-        `    Base URL: ${c.cyan}${ctx.baseUrl}${c.reset}\n` +
-        `  Add the available custom models:\n${modelList}\n` +
-        `  Select ${c.cyan}${model}${c.reset} for this profile.\n` +
-        `  Paste your Subconscious API key there, then fully restart Cursor.\n`,
-    );
-  } else if (agent.id === 'pi') {
+  if (agent.id === 'pi') {
     console.log(`\n  ${c.dim}Start a fresh session with ${c.reset}${c.cyan}subc pi${c.reset}${c.dim}.${c.reset}\n`);
   }
   return code;
@@ -662,18 +678,34 @@ async function runRunbookSetup(agent, argv, profile, relativeScript = agent.runb
  */
 export async function runAgent(agent, argv, options = {}) {
   const profile = options.profile;
-  if (options.setup) {
-    if (!agent.runbook?.setupScript) {
-      throw new Error(`No setup integration is available for ${agent.name}`);
-    }
-    return runRunbookSetup(agent, argv, profile, agent.runbook.setupScript);
-  }
   if (isAgentHelpRequest(argv)) {
     printAgentHelp(agent, profile);
     return 0;
   }
-  if (agent.runbook?.mode === 'setup') {
-    return runRunbookSetup(agent, argv, profile);
+
+  const parsed = parseAgentAction(agent, argv);
+  if (parsed.action !== 'launch') {
+    if (!agent.runbook?.setupScript) {
+      throw new Error(`No persistent integration is available for ${agent.name}`);
+    }
+    const setupArgs =
+      parsed.args[0] === parsed.action ? parsed.args : [parsed.action, ...parsed.args];
+    const code = await runRunbookSetup(
+      agent,
+      setupArgs,
+      profile,
+      agent.runbook.setupScript,
+    );
+    if (code === 0) {
+      const message =
+        parsed.action === 'status'
+          ? `${agent.name} status check complete.`
+          : parsed.action === 'uninstall'
+            ? `${agent.name} integration removed.`
+            : `${agent.name} setup complete.`;
+      console.log(`\n  ${c.green}${c.bold}✓ ${message}${c.reset}\n`);
+    }
+    return code;
   }
 
   const { model, rest } = extractModel(argv, profile);
@@ -699,9 +731,9 @@ export async function runAgent(agent, argv, options = {}) {
   // if it was installed into a dir not yet on the parent shell's PATH.
   const extraDirs = [binDir, ...candidateBinDirs()].filter(Boolean);
   const env = {
+    ...envMap,
     ...(profile?.values || {}),
     ...process.env,
-    ...envMap,
     PATH: augmentPath(extraDirs),
   };
   const args = [...launchArgs, ...rest];