@notis_ai/cli 0.2.0-beta.132.1 → 0.2.0-beta.133.1

package/README.md

@@ -20,6 +20,17 @@ npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
 
 Use `notis login --paste-code` for the HTTPS copy-paste fallback on a remote machine.
 
+## Release channels
+
+`@latest` is the only tag worth documenting, for beta accounts too.
+
+The npm tag has to be chosen before the CLI starts, and the CLI only learns which Notis it talks to once it reads the profile — so no single install command can be right for both environments on its own. Instead the deployment answers the question: `/.well-known/oauth-protected-resource/cli` reports its channel, `notis login` pins it on the profile, and any later run that finds itself on the wrong build hands the whole invocation to the right one before it does anything else.
+
+- `notis doctor` reports `release_channel`, `cli_version`, and a `channel` check.
+- `--api-base <url>` decides the build for that one run, so a one-off call against another environment uses the matching CLI.
+- `./dev.sh` profiles and source checkouts are never re-executed: whatever you started stays in control.
+- `NOTIS_CLI_AUTO_CHANNEL=0` disables the hand-off; `doctor` then reports the mismatch instead of correcting it.
+
 ## Profiles
 
 A profile is one account paired with one API endpoint. Every profile keeps its own credential, so switching between them never signs any of them out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.132.1",
+  "version": "0.2.0-beta.133.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/skills/notis-cli/SKILL.md

@@ -31,6 +31,8 @@ Use the registry-resolved published npm package everywhere:
 
 Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`. On a local machine the CLI holds its own OAuth grant: `notis login` authorizes one in the browser, and signing in to the Notis desktop app authorizes one automatically for that account. Either way the grant belongs to the CLI, which refreshes it without the desktop app running.
 
+`@latest` is correct for every account, including beta ones. Each deployment reports which published build belongs to it, `notis login` pins that on the profile, and a later run that finds itself on the wrong build hands the invocation to the right one before doing anything. Never substitute a channel by hand: pinning `@beta` on a production profile is how a machine ends up running a build its API does not expect. `notis doctor` reports the active channel, and `NOTIS_CLI_AUTO_CHANNEL=0` turns the hand-off off for a run.
+
 This `notis-cli` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
 
 ## Profiles: accounts and endpoints

package/src/cli.js

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,10 +7,17 @@ import { COMMAND_SPECS, GROUP_SUMMARIES } from './command-specs/index.js';
 import { OutputManager } from './runtime/output.js';
 import { asCliError } from './runtime/errors.js';
 import { reportCliCommand } from './runtime/telemetry.js';
+import {
+  CHANNEL_SWITCH_ENV,
+  resolveChannelSwitch,
+} from './runtime/channel.js';
 import {
   DEFAULT_PROFILE,
+  getProfile,
+  loadConfig,
   resolveOutputMode,
   resolveRuntimeProfile,
+  resolveWorktreeRuntime,
   workspacePath,
 } from './runtime/profiles.js';
 
@@ -232,7 +240,157 @@ export function createProgram() {
   return program;
 }
 
+/**
+ * Read the two global flags that decide which build should serve this run.
+ *
+ * Commander cannot help here: the decision has to be made before the program
+ * parses, because the answer may be to hand the whole invocation to a
+ * different process. Only `--profile` and `--api-base` matter, and both are
+ * plain `--flag value` pairs.
+ */
+export function readChannelRelevantFlags(args = []) {
+  const flags = {};
+  for (const [index, token] of args.entries()) {
+    for (const [flag, key] of [['--profile', 'profile'], ['--api-base', 'apiBase']]) {
+      if (token === flag) flags[key] = args[index + 1];
+      else if (token.startsWith(`${flag}=`)) flags[key] = token.slice(flag.length + 1);
+    }
+  }
+  return flags;
+}
+
+export function channelProfileForArgs(
+  args = [],
+  env = process.env,
+  { config: suppliedConfig, worktreeRuntime: suppliedWorktreeRuntime } = {},
+) {
+  // An explicit endpoint overrides the stored profile for this run, so it also
+  // decides the build: `--api-base https://api-beta.notis.ai` on a production
+  // profile is a deliberate one-off beta call.
+  const { profile: profileName, apiBase } = readChannelRelevantFlags(args);
+  if (apiBase) {
+    return { api_base: apiBase };
+  }
+  if (env.NOTIS_API_BASE) {
+    return { api_base: env.NOTIS_API_BASE };
+  }
+  const config = suppliedConfig || loadConfig();
+  const explicitProfile = profileName || env.NOTIS_PROFILE;
+  if (explicitProfile) {
+    return getProfile(config, explicitProfile);
+  }
+  const resolvedWorktree = suppliedWorktreeRuntime === undefined
+    ? resolveWorktreeRuntime()
+    : suppliedWorktreeRuntime;
+  // A stopped local-only worktree must reach the normal routing error on the
+  // current build. Switching based on an unrelated shared profile would escape
+  // the worktree boundary before that fail-closed check runs.
+  if (resolvedWorktree?.unavailable) {
+    return {};
+  }
+  if (resolvedWorktree?.profile) {
+    return resolvedWorktree;
+  }
+  // NOTIS_JWT replaces the credential, not the route. Unless NOTIS_API_BASE
+  // was explicit above, the selected/current profile still owns the channel.
+  return getProfile(config, config.current_profile || DEFAULT_PROFILE);
+}
+
+function interruptedExitCode(signal) {
+  if (signal === 'SIGINT') return 130;
+  if (signal === 'SIGTERM') return 143;
+  return 1;
+}
+
+export function executeChannelSwitch(
+  decision,
+  args,
+  env,
+  { spawn = spawnSync } = {},
+) {
+  const childEnv = { ...env, [CHANNEL_SWITCH_ENV]: '1' };
+  // First make npm resolve and boot the target package without executing the
+  // requested command. That distinguishes an unavailable tag/network from a
+  // legitimate non-zero exit of the handed-off CLI, which must be propagated
+  // rather than retried locally after a possible mutation.
+  const probe = spawn(decision.command, [...decision.args, '--version'], {
+    stdio: 'ignore',
+    env: childEnv,
+  });
+  if (probe.signal) {
+    return {
+      ...decision,
+      exitCode: interruptedExitCode(probe.signal),
+      reason: 'switch_interrupted',
+    };
+  }
+  if (probe.error || probe.status !== 0) {
+    return { ...decision, switch: false, reason: 'switch_unavailable' };
+  }
+
+  const result = spawn(decision.command, [...decision.args, ...args], {
+    stdio: 'inherit',
+    env: childEnv,
+  });
+  if (result.signal) {
+    return {
+      ...decision,
+      exitCode: interruptedExitCode(result.signal),
+      reason: 'switch_interrupted',
+    };
+  }
+  if (result.error || typeof result.status !== 'number') {
+    return { ...decision, switch: false, reason: 'switch_failed' };
+  }
+  return { ...decision, exitCode: result.status };
+}
+
+/**
+ * Hand this invocation to the published build the profile is pinned to.
+ *
+ * Returns the decision rather than exiting so tests can assert on it. Any
+ * failure to reach the other build is non-fatal: running the wrong channel is
+ * a much smaller problem than refusing to run at all.
+ */
+export function switchChannelIfNeeded(
+  argv = process.argv,
+  env = process.env,
+  { spawn = spawnSync, platform = process.platform, moduleDirectory } = {},
+) {
+  const args = argv.slice(2);
+  let profile;
+  try {
+    profile = channelProfileForArgs(args, env);
+  } catch {
+    return { switch: false, reason: 'profile_unreadable' };
+  }
+  const decision = resolveChannelSwitch({
+    runningVersion: CLI_VERSION,
+    profile,
+    moduleDirectory: moduleDirectory || dirname(fileURLToPath(import.meta.url)),
+    env,
+    platform,
+  });
+  if (!decision.switch) {
+    return decision;
+  }
+
+  const result = executeChannelSwitch(decision, args, env, { spawn });
+  if (!result.switch) {
+    process.stderr.write(
+      `Notis CLI could not start the ${decision.targetChannel} build for this profile; `
+      + `continuing on ${decision.runningChannel}.\n`,
+    );
+  }
+  return result;
+}
+
 export async function run(argv = process.argv) {
+  const switched = switchChannelIfNeeded(argv);
+  if (switched.switch) {
+    process.exitCode = switched.exitCode;
+    return;
+  }
   const program = createProgram();
   await program.parseAsync(argv);
 }

package/src/command-specs/meta.js

@@ -1,6 +1,10 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
 import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
 import { findCommandSpec, formatDescribe } from '../runtime/help.js';
 import { createExpiredAuthError, getAuthRecovery } from '../runtime/auth-recovery.js';
+import { cliCommandForChannel, resolveChannelSwitch } from '../runtime/channel.js';
 import {
   credentialIsExpired,
   getProfile,
@@ -17,10 +21,40 @@ export function doctorToolRoundtripRuntime(runtime) {
   };
 }
 
+export function doctorChannelSummary(
+  runtime,
+  moduleDirectory = dirname(fileURLToPath(import.meta.url)),
+) {
+  const decision = resolveChannelSwitch({
+    runningVersion: runtime.cliVersion,
+    profile: {
+      channel: runtime.channel,
+      api_base: runtime.apiBase,
+    },
+    moduleDirectory,
+  });
+  const mismatch = Boolean(
+    decision.targetChannel
+    && decision.targetChannel !== decision.runningChannel,
+  );
+  const releaseChannel = runtime.worktreeRuntime ? 'dev' : runtime.channel;
+  return {
+    decision,
+    mismatch,
+    releaseChannel,
+    status: runtime.worktreeRuntime
+      ? 'dev'
+      : mismatch
+        ? `mismatch:${decision.reason}`
+        : decision.runningChannel,
+  };
+}
+
 async function doctorHandler(ctx) {
   const checks = {
     config: 'ok',
     auth: 'missing',
+    channel: 'unknown',
     routing: 'ok',
     health: 'unknown',
     tool_roundtrip: 'unknown',
@@ -76,7 +110,24 @@ async function doctorHandler(ctx) {
     }
   }
 
+  // A mismatch here means the automatic hand-off could not happen: a source
+  // checkout, an explicit opt-out, or a switch that could not reach npm. The
+  // profile still routes to the right API, so this reports rather than fails.
+  const {
+    decision: channelDecision,
+    mismatch: channelMismatch,
+    releaseChannel,
+    status: channelStatus,
+  } = doctorChannelSummary(ctx.runtime);
+  checks.channel = channelStatus;
+
   const hints = [];
+  if (channelMismatch) {
+    hints.push({
+      command: `${cliCommandForChannel(channelDecision.targetChannel)} doctor`,
+      reason: `Profile "${ctx.runtime.profileName}" belongs to the ${channelDecision.targetChannel} CLI channel`,
+    });
+  }
   if (checks.auth === 'missing') {
     hints.push(...getAuthRecovery(ctx.runtime, { mode: 'missing' }).hints);
   } else if (checks.auth === 'expired') {
@@ -104,6 +155,8 @@ async function doctorHandler(ctx) {
       profile: ctx.runtime.profileName,
       profile_source: ctx.runtime.profileSource,
       api_base: ctx.runtime.apiBase,
+      release_channel: releaseChannel || null,
+      cli_version: ctx.runtime.cliVersion || null,
       credential_source: ctx.runtime.credentialKind || null,
       ...(ctx.runtime.credentialKind === 'oauth'
         ? {

package/src/runtime/auth-recovery.js

@@ -1,6 +1,14 @@
 import { CliError, EXIT_CODES } from './errors.js';
+import { channelFromProfile, cliCommandForChannel } from './channel.js';
 
-const CLI_NPX = 'npx --package @notis_ai/cli@latest -- notis';
+// Recovery is only useful when the printed command is the one that will run:
+// telling a beta profile to reinstall `@latest` sends it back to the build it
+// just failed on.
+function cliNpx(runtime = {}) {
+  return cliCommandForChannel(
+    runtime.channel || channelFromProfile({ api_base: runtime.apiBase }),
+  );
+}
 
 export function quoteShellArgument(value) {
   return `'${String(value).replace(/'/g, `'"'"'`)}'`;
@@ -19,8 +27,9 @@ function profileSuffix(profileName) {
  * "expired" means the profile holds a grant the browser can renew, while
  * "missing" means this profile has never been authorized at all.
  */
-export function getAuthRecovery({ profileName } = {}, { mode = 'expired' } = {}) {
-  const suffix = profileSuffix(profileName);
+export function getAuthRecovery(runtime = {}, { mode = 'expired' } = {}) {
+  const CLI_NPX = cliNpx(runtime);
+  const suffix = profileSuffix(runtime.profileName);
   const hints = [
     {
       command: `${CLI_NPX} login${suffix}`,
@@ -41,6 +50,7 @@ export function getAuthRecovery({ profileName } = {}, { mode = 'expired' } = {})
 }
 
 export function createExpiredAuthError(runtime) {
+  const CLI_NPX = cliNpx(runtime || {});
   if (runtime?.credentialKind === 'worktree') {
     return new CliError({
       code: 'auth_expired',

package/src/runtime/channel.js

@@ -0,0 +1,133 @@
+/**
+ * Which published CLI build a profile should run.
+ *
+ * The npm tag has to be chosen before the CLI starts, and the CLI only learns
+ * which Notis it talks to after it reads the profile — so a single documented
+ * install command can never be right for both environments on its own. The
+ * deployment answers the question at login (`notis_cli_channel` in the CLI
+ * protected-resource metadata), the answer is pinned on the profile, and every
+ * later run re-executes the matching build. `@notis_ai/cli@latest` therefore
+ * stays the one command worth documenting, including for beta accounts.
+ */
+
+export const RELEASE_CHANNELS = ['stable', 'beta'];
+const CHANNEL_TAGS = { stable: 'latest', beta: 'beta' };
+export const CLI_PACKAGE_NAME = '@notis_ai/cli';
+// Set on the child so a build that disagrees about its own channel — a bad
+// version string, a half-published tag — cannot bounce the process forever.
+export const CHANNEL_SWITCH_ENV = 'NOTIS_CLI_CHANNEL_SWITCHED';
+export const CHANNEL_DISABLE_ENV = 'NOTIS_CLI_AUTO_CHANNEL';
+
+export function isReleaseChannel(value) {
+  return RELEASE_CHANNELS.includes(value);
+}
+
+export function packageTagForChannel(channel) {
+  return CHANNEL_TAGS[channel] || CHANNEL_TAGS.stable;
+}
+
+export function cliCommandForChannel(channel) {
+  return `npx --package ${CLI_PACKAGE_NAME}@${packageTagForChannel(channel)} -- notis`;
+}
+
+/**
+ * The channel of the build that is currently running.
+ *
+ * The publish pipeline stamps beta releases as prereleases
+ * (`0.2.0-beta.129.1`) and production releases as plain semver (`0.2.10`), so
+ * the manifest version is the only channel marker that cannot drift from what
+ * npm actually served.
+ */
+export function channelFromVersion(version) {
+  return String(version || '').includes('-') ? 'beta' : 'stable';
+}
+
+/**
+ * The channel a profile is pinned to.
+ *
+ * `channel` is written at login from the deployment's own metadata. The
+ * `beta` flag and the endpoint host are the fallbacks that let a profile
+ * authorized by an older CLI resolve without a second login.
+ */
+export function channelFromProfile(profile = {}) {
+  if (isReleaseChannel(profile.channel)) {
+    return profile.channel;
+  }
+  if (profile.beta === true) return 'beta';
+  if (profile.beta === false) return 'stable';
+  for (const candidate of [profile.oauth_api_base, profile.api_base]) {
+    if (typeof candidate !== 'string' || !candidate) continue;
+    try {
+      const { hostname } = new URL(candidate);
+      if (hostname === 'api-beta.notis.ai') return 'beta';
+      if (hostname === 'api.notis.ai') return 'stable';
+    } catch {
+      // A malformed endpoint says nothing about the channel.
+    }
+  }
+  return null;
+}
+
+/**
+ * A profile served by `./dev.sh` runs the CLI from that worktree on purpose.
+ * Re-executing it into a published build would swap both the code under test
+ * and the credential the worktree minted.
+ */
+export function isDevManagedProfile(profile = {}) {
+  if (profile.dev_access_token || profile.dev_workspace_root) {
+    return true;
+  }
+  if (typeof profile.api_base !== 'string' || !profile.api_base) {
+    return false;
+  }
+  try {
+    const { hostname } = new URL(profile.api_base);
+    return ['localhost', '127.0.0.1', '::1', '[::1]'].includes(hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A checkout run through `node bin/notis.js` is someone testing this source
+ * tree. Only an installed copy — one that npm placed under node_modules — may
+ * hand its invocation to a different published build.
+ */
+export function isInstalledPackage(moduleDirectory) {
+  return String(moduleDirectory || '').split(/[\\/]/).includes('node_modules');
+}
+
+/**
+ * Decide whether this process should hand over to another published build.
+ *
+ * Returns the reason in every case: the caller reports it under `--verbose`
+ * and the tests assert on it, so a switch that silently does not happen is
+ * still explainable.
+ */
+export function resolveChannelSwitch({
+  runningVersion,
+  profile = {},
+  moduleDirectory = '',
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const runningChannel = channelFromVersion(runningVersion);
+  const targetChannel = channelFromProfile(profile);
+  const stay = (reason) => ({ switch: false, reason, runningChannel, targetChannel });
+
+  if (env[CHANNEL_SWITCH_ENV] === '1') return stay('already_switched');
+  if (env[CHANNEL_DISABLE_ENV] === '0') return stay('disabled');
+  if (!targetChannel) return stay('profile_channel_unknown');
+  if (targetChannel === runningChannel) return stay('channel_matches');
+  if (isDevManagedProfile(profile)) return stay('dev_managed_profile');
+  if (!isInstalledPackage(moduleDirectory)) return stay('source_checkout');
+
+  return {
+    switch: true,
+    reason: 'channel_mismatch',
+    runningChannel,
+    targetChannel,
+    command: platform === 'win32' ? 'npx.cmd' : 'npx',
+    args: ['--yes', '--package', `${CLI_PACKAGE_NAME}@${packageTagForChannel(targetChannel)}`, '--', 'notis'],
+  };
+}

package/src/runtime/oauth.js

@@ -19,6 +19,11 @@ import { createInterface } from 'node:readline/promises';
 
 import { CliError, EXIT_CODES } from './errors.js';
 import { getAuthRecovery, quoteShellArgument } from './auth-recovery.js';
+import {
+  channelFromProfile,
+  cliCommandForChannel,
+  isReleaseChannel,
+} from './channel.js';
 import {
   credentialIsExpired,
   ensureProfile,
@@ -137,6 +142,12 @@ export async function discoverCliOAuth(apiBase, fetchImpl = fetch) {
     resource: protectedResource.resource,
     clientId: protectedResource.notis_cli_client_id || 'notis_cli',
     copyPasteRedirectUri: protectedResource.notis_cli_copy_paste_redirect_uri,
+    // A deployment that predates channel advertising, or a local one with no
+    // published build, leaves this null and the profile keeps resolving its
+    // channel from the endpoint it authorized against.
+    channel: isReleaseChannel(protectedResource.notis_cli_channel)
+      ? protectedResource.notis_cli_channel
+      : null,
     authorizationEndpoint: authorizationServer.authorization_endpoint,
     tokenEndpoint: authorizationServer.token_endpoint,
     revocationEndpoint: authorizationServer.revocation_endpoint,
@@ -718,6 +729,13 @@ function persistOAuthTokenResponse(runtime, metadata, tokenResponse) {
       // only endpoint the resulting token is accepted by.
       api_base: oauthApiBase || profile.api_base,
       beta: beta ?? profile.beta,
+      // The deployment that just authorized this profile also names the
+      // published build that belongs to it. Pinning it here is what lets the
+      // next run correct itself without the user knowing a channel exists.
+      channel: isReleaseChannel(metadata.channel)
+        ? metadata.channel
+        : channelFromProfile({ ...profile, beta: beta ?? profile.beta, api_base: oauthApiBase })
+          ?? profile.channel,
       oauth_api_base: oauthApiBase || profile.oauth_api_base,
       oauth_resource: metadata.resource,
       oauth_access_token: tokenResponse.access_token,
@@ -784,14 +802,20 @@ function clearPendingAuthorization(runtime, file = pendingAuthorizationFile(runt
   }
 }
 
-function redeemCommand(profileName) {
+function redeemCommand(profileName, channel) {
   return [
-    'npx --package @notis_ai/cli@latest -- notis',
+    cliCommandForChannel(channel),
     `--profile ${quoteShellArgument(profileName || 'default')}`,
     'login --code <code>',
   ].join(' ');
 }
 
+function authorizationChannel(metadata, runtime, pending = null) {
+  return metadata.channel
+    || pending?.channel
+    || channelFromProfile({ api_base: pending?.api_base || runtime.apiBase });
+}
+
 function updateRuntimeFromOAuthProfile(runtime, profile) {
   const oauthApiBase = getOAuthApiBase(profile);
   runtime.jwt = profile.oauth_access_token;
@@ -875,6 +899,7 @@ async function redeemAuthorizationCode(runtime, code, fetchImpl) {
     resource: pending.resource,
     clientId: pending.client_id,
     tokenEndpoint: pending.token_endpoint,
+    channel: pending.channel,
   };
   if (!metadata.issuer || !metadata.resource || !metadata.clientId || !metadata.tokenEndpoint) {
     throw oauthError(
@@ -961,7 +986,10 @@ export async function loginWithOAuth(runtime, options = {}, output, fetchImpl =
             scopes: pendingScopes,
           }),
           expires_in: Math.max(0, Number(pending.expires_at) - Math.floor(Date.now() / 1000)),
-          redeem_command: redeemCommand(runtime.profileName),
+          redeem_command: redeemCommand(
+            runtime.profileName,
+            authorizationChannel(metadata, runtime, pending),
+          ),
         },
       };
     }
@@ -1010,6 +1038,7 @@ export async function loginWithOAuth(runtime, options = {}, output, fetchImpl =
       client_id: metadata.clientId,
       token_endpoint: metadata.tokenEndpoint,
       authorization_endpoint: metadata.authorizationEndpoint,
+      channel: authorizationChannel(metadata, runtime),
       scopes,
       expires_at: Math.floor(Date.now() / 1000) + PENDING_LOGIN_TTL_SECONDS,
     });
@@ -1021,7 +1050,10 @@ export async function loginWithOAuth(runtime, options = {}, output, fetchImpl =
       agentAuthorization: {
         authorize_url: authorizeUrl,
         expires_in: PENDING_LOGIN_TTL_SECONDS,
-        redeem_command: redeemCommand(runtime.profileName),
+        redeem_command: redeemCommand(
+          runtime.profileName,
+          authorizationChannel(metadata, runtime),
+        ),
       },
     };
   }

package/src/runtime/profiles.js

@@ -12,6 +12,7 @@ import { homedir } from 'node:os';
 import { dirname, join, parse, resolve } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
 import { getAuthRecovery, quoteShellArgument } from './auth-recovery.js';
+import { channelFromProfile, cliCommandForChannel, isReleaseChannel } from './channel.js';
 
 export const CONFIG_DIR = join(homedir(), '.notis');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
@@ -95,6 +96,10 @@ function normalizeProfile(rawProfile = {}) {
   return {
     api_base: typeof raw.api_base === 'string' ? raw.api_base : undefined,
     beta: typeof raw.beta === 'boolean' ? raw.beta : undefined,
+    // Which published CLI build this profile runs, as the deployment reported
+    // it at login. Unknown values are dropped rather than trusted: this key
+    // decides which code executes on the next run.
+    channel: isReleaseChannel(raw.channel) ? raw.channel : undefined,
     label: typeof raw.label === 'string' ? raw.label : undefined,
     dev_access_token:
       typeof raw.dev_access_token === 'string' ? raw.dev_access_token : undefined,
@@ -877,7 +882,7 @@ export function resolveRuntimeProfile(
       exitCode: EXIT_CODES.auth,
       hints: [{
         command: [
-          'npx --package @notis_ai/cli@latest -- notis',
+          cliCommandForChannel(channelFromProfile({ api_base: normalizedRequestedApiBase })),
           `--profile ${quoteShellArgument(profileName)}`,
           `--api-base ${quoteShellArgument(normalizedRequestedApiBase)}`,
           'login',
@@ -929,6 +934,17 @@ export function resolveRuntimeProfile(
     profileName,
     profileSource,
     profileLabel: profile.label,
+    // Which published build serves this profile. Carried on the runtime so
+    // every recovery hint prints the command that will actually run.
+    channel: devRuntime
+      ? null
+      : channelFromProfile(
+          (globalOptions.apiBase || process.env.NOTIS_API_BASE)
+            // An explicit route owns this invocation even when the stored
+            // profile is pinned to the opposite release channel.
+            ? { api_base: apiBase }
+            : { ...profile, api_base: apiBase },
+        ),
     apiBase,
     requestedApiBase: normalizedRequestedApiBase,
     jwt,