@raidiant/notifai 10.0.0 → 10.1.1

package/src/cli-bin.ts

@@ -1,10 +1,38 @@
-import { accessSync, constants, existsSync, lstatSync, realpathSync } from 'node:fs'
+import {
+  accessSync,
+  constants,
+  existsSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+} from 'node:fs'
 import path from 'node:path'
 import type { ReadinessState } from './readiness.js'
+import { packageVersion } from './release.js'
+import { cliUpdateRecoveryCommand } from './cli-update-contract.js'
 
 const POSIX_NAMES = ['notifai']
 const WINDOWS_NAMES = ['notifai.cmd', 'notifai.exe', 'notifai']
 
+export interface CliBinReadinessOptions {
+  runningArtifactPath?: string
+  currentVersion?: string | null
+}
+
+export interface CliPathEntry {
+  command_path: string
+  executable: boolean
+  artifact_path: string | null
+  version: string | null
+  install_prefix: string | null
+}
+
+export interface CliInstallationInspection {
+  current: { artifact_path: string; version: string | null }
+  effective: CliPathEntry | null
+  entries: CliPathEntry[]
+}
+
 export function pathNotifaiEntries(
   env: NodeJS.ProcessEnv,
   platform: NodeJS.Platform = process.platform,
@@ -36,32 +64,170 @@ export function isExecutablePath(file: string, platform: NodeJS.Platform = proce
   }
 }
 
+function canonicalPath(file: string): string {
+  try {
+    return realpathSync(file)
+  } catch {
+    return path.resolve(file)
+  }
+}
+
+function windowsShimArtifact(file: string): string | null {
+  if (path.extname(file).toLowerCase() !== '.cmd') return null
+  try {
+    const source = readFileSync(file, 'utf8')
+    const match = /(?:%dp0%|%~dp0)?([^"\r\n]*node_modules[\\/]@raidiant[\\/]notifai[\\/]dist[\\/]main\.js)/i.exec(source)
+    if (match?.[0] === undefined) return null
+    const expanded = match[0]
+      .replace(/^%~?dp0%/i, `${path.dirname(file)}${path.sep}`)
+      .replaceAll('\\', path.sep)
+    return canonicalPath(expanded)
+  } catch {
+    return null
+  }
+}
+
+function artifactForCommand(file: string, platform: NodeJS.Platform): string | null {
+  const shim = platform === 'win32' ? windowsShimArtifact(file) : null
+  if (shim !== null) return shim
+  try {
+    return canonicalPath(file)
+  } catch {
+    return null
+  }
+}
+
+function artifactVersion(artifact: string | null): string | null {
+  if (artifact === null) return null
+  try {
+    const parsed: unknown = JSON.parse(
+      readFileSync(path.join(path.dirname(artifact), '..', 'package.json'), 'utf8'),
+    )
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const version = (parsed as { version?: unknown }).version
+    return typeof version === 'string' && version !== '' ? version : null
+  } catch {
+    return null
+  }
+}
+
+function installPrefix(artifact: string | null): string | null {
+  if (artifact !== null) {
+    const marker = /[\\/]lib[\\/]node_modules[\\/]@raidiant[\\/]notifai[\\/]/i.exec(artifact)
+      ?? /[\\/]node_modules[\\/]@raidiant[\\/]notifai[\\/]/i.exec(artifact)
+    if (marker?.index !== undefined) return artifact.slice(0, marker.index)
+  }
+  return null
+}
+
+export function inspectCliInstallations(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform = process.platform,
+  options: CliBinReadinessOptions = {},
+): CliInstallationInspection {
+  const runningArtifact = canonicalPath(options.runningArtifactPath ?? process.argv[1] ?? 'notifai')
+  const entries = pathNotifaiEntries(env, platform).map((command): CliPathEntry => {
+    const artifact = artifactForCommand(command, platform)
+    return {
+      command_path: command,
+      executable: isExecutablePath(command, platform),
+      artifact_path: artifact,
+      version: artifactVersion(artifact),
+      install_prefix: installPrefix(artifact),
+    }
+  })
+  return {
+    current: {
+      artifact_path: runningArtifact,
+      version: options.currentVersion === undefined ? packageVersion() : options.currentVersion,
+    },
+    effective: entries.find((entry) => entry.executable) ?? null,
+    entries,
+  }
+}
+
 export function cliBinReadiness(
   env: NodeJS.ProcessEnv,
   platform: NodeJS.Platform = process.platform,
+  options: CliBinReadinessOptions = {},
 ): ReadinessState {
-  const entries = pathNotifaiEntries(env, platform)
-  const broken = entries.find((file) => !isExecutablePath(file, platform))
-  if (broken !== undefined) {
+  const inspection = inspectCliInstallations(env, platform, options)
+  const { current, effective, entries } = inspection
+  const updateCommand = cliUpdateRecoveryCommand()
+  if (effective === null && entries.length > 0) {
     return {
       id: 'cli-bin',
       title: 'notifai command',
       status: 'gap',
-      detail: `${broken} is on PATH but is not executable`,
+      detail: 'the notifai command is on PATH but cannot run',
+      technical: inspection,
       remedy: {
         by: 'user-here',
         summary: 'repair the global notifai command so it can run',
-        command: 'npm install -g @raidiant/notifai',
+        command: updateCommand,
+      },
+    }
+  }
+  // A global install that landed outside PATH used to report `ready` with
+  // "this process can run" — which is true of the running process and false of
+  // every instruction it goes on to print. Hooks embed absolute paths, so
+  // nothing visibly breaks until the reader types `notifai` themselves.
+  //
+  // Not a blocker: this process is already running, so the whole setup —
+  // pairing, the app, the delivery proof — still completes. It is the later
+  // `notifai …` lines that will not be found, and saying so is the fix.
+  if (effective === null) {
+    return {
+      id: 'cli-bin',
+      title: 'notifai command',
+      status: 'optional-gap',
+      detail:
+        'no `notifai` on PATH — this process runs, but a typed `notifai …` command will not be found',
+      remedy: {
+        by: 'user-here',
+        summary: 'install notifai globally so the command is on your PATH',
+        command: updateCommand,
+      },
+    }
+  }
+
+  const effectiveIsCurrent =
+    effective.artifact_path === current.artifact_path ||
+    (effective.version !== null && current.version !== null && effective.version === current.version)
+  if (!effectiveIsCurrent) {
+    return {
+      id: 'cli-bin',
+      title: 'notifai command',
+      status: 'gap',
+      detail: 'the notifai command resolves to a different installation than this current CLI',
+      technical: inspection,
+      remedy: {
+        by: 'user-here',
+        summary: 'update the notifai command that wins PATH',
+        command: updateCommand,
       },
     }
   }
+
+  const duplicateNeedsCleanup = entries.some(
+    (entry) =>
+      entry !== effective &&
+      (!entry.executable || entry.artifact_path !== effective.artifact_path),
+  )
+  if (duplicateNeedsCleanup) {
+    return {
+      id: 'cli-bin',
+      title: 'notifai command',
+      status: 'optional-gap',
+      detail: 'the notifai command is ready; another installation remains for cleanup',
+      technical: inspection,
+    }
+  }
   return {
     id: 'cli-bin',
     title: 'notifai command',
     status: 'ready',
-    detail:
-      entries[0] === undefined
-        ? 'this process can run; no notifai binary was on PATH'
-        : `${entries[0]} is executable`,
+    detail: 'the notifai command is ready',
+    technical: inspection,
   }
 }

package/src/cli-update-contract.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve the current published CLI independently of every installed
+ * `notifai` command. The fetched build owns the locally derived prefix repair,
+ * so this action neither invokes the stale PATH winner nor exposes local
+ * installation paths.
+ */
+export function cliUpdateRecoveryCommand(): string {
+  return 'npx --yes @raidiant/notifai@latest update'
+}

package/src/cli-update.test.ts

@@ -0,0 +1,125 @@
+import { spawnSync } from 'node:child_process'
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import type { CommandDeps, CommandIo } from './commands-core.js'
+import { cliUpdateCommand } from './commands-update.js'
+import { installHookAdapter, inspectHookAdapter } from './hook-adapter.js'
+import { packageVersion } from './release.js'
+
+class CapturedIo implements CommandIo {
+  outLines: string[] = []
+  errLines: string[] = []
+  out(line: string) { this.outLines.push(line) }
+  err(line: string) { this.errLines.push(line) }
+  async confirm() { return false }
+  openUrl() {}
+}
+
+function npmInstall(root: string, name: string, version: string) {
+  const prefix = path.join(root, name)
+  const packageRoot = path.join(prefix, 'lib', 'node_modules', '@raidiant', 'notifai')
+  const artifact = path.join(packageRoot, 'dist', 'main.js')
+  const command = path.join(prefix, 'bin', 'notifai')
+  mkdirSync(path.dirname(artifact), { recursive: true })
+  mkdirSync(path.dirname(command), { recursive: true })
+  writeFileSync(path.join(packageRoot, 'package.json'), JSON.stringify({ version }))
+  writeFileSync(artifact, `#!${process.execPath}\nprocess.stdout.write(${JSON.stringify(version)} + "\\n")\n`)
+  chmodSync(artifact, 0o755)
+  symlinkSync(path.relative(path.dirname(command), artifact), command)
+  return { prefix, packageRoot, artifact, command }
+}
+
+describe('CLI update recovery', () => {
+  it('updates the PATH winner prefix and retargets the shared hook adapter in one action', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-update-loop-'))
+    const currentVersion = packageVersion()
+    if (currentVersion === null) throw new Error('test build has no package version')
+    const stale = npmInstall(root, 'stale-prefix', '3.0.1')
+    const current = npmInstall(root, 'current-prefix', currentVersion)
+    const managerPrefix = path.join(root, 'manager-prefix')
+    const managerBin = path.join(managerPrefix, 'bin')
+    const npm = path.join(managerBin, 'npm')
+    const calls = path.join(root, 'npm-calls.jsonl')
+    mkdirSync(managerBin, { recursive: true })
+    writeFileSync(
+      npm,
+      `#!${process.execPath}
+const fs = require('node:fs');
+const path = require('node:path');
+const args = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(calls)}, JSON.stringify(args) + '\\n');
+if (args[0] === 'prefix') {
+  process.stdout.write(${JSON.stringify(managerPrefix)} + '\\n');
+  process.exit(0);
+}
+const prefix = args[args.indexOf('--prefix') + 1];
+const packageRoot = path.join(prefix, 'lib', 'node_modules', '@raidiant', 'notifai');
+const artifact = path.join(packageRoot, 'dist', 'main.js');
+fs.mkdirSync(path.dirname(artifact), { recursive: true });
+fs.writeFileSync(path.join(packageRoot, 'package.json'), JSON.stringify({ version: ${JSON.stringify(currentVersion)} }));
+fs.writeFileSync(artifact, '#!${process.execPath}\\nprocess.stdout.write(${JSON.stringify(`${currentVersion}\\n`)})\\n', { mode: 0o755 });
+`,
+    )
+    chmodSync(npm, 0o755)
+
+    const home = path.join(root, 'home')
+    installHookAdapter({ execPath: process.execPath, scriptPath: stale.artifact }, home)
+    const io = new CapturedIo()
+    const deps: CommandDeps = {
+      io,
+      store: { load: () => null, save: () => {}, clear: () => {}, describe: () => 'test' },
+      env: {
+        PATH: [managerBin, path.dirname(stale.command), path.dirname(current.command)].join(':'),
+      },
+      cwd: root,
+      hookAdapterHome: home,
+      hookInstallTarget: { execPath: process.execPath, scriptPath: current.artifact },
+      hookPlatform: 'darwin',
+    }
+
+    expect(cliUpdateCommand(deps, {})).toBe(0)
+    expect(JSON.parse(readFileSync(path.join(stale.packageRoot, 'package.json'), 'utf8'))).toMatchObject({
+      version: currentVersion,
+    })
+    expect(
+      readFileSync(calls, 'utf8').trim().split('\n').map((line) => JSON.parse(line)),
+    ).toEqual([
+      ['prefix', '--global'],
+      ['install', '--global', '--prefix', realpathSync(stale.prefix), '@raidiant/notifai'],
+    ])
+    expect(spawnSync(stale.command, ['--version'], { encoding: 'utf8' }).stdout.trim()).toBe(currentVersion)
+    expect(inspectHookAdapter(home).target).toMatchObject({ scriptPath: realpathSync(stale.artifact) })
+    expect(io.outLines).toEqual(['Notifai is updated. Re-run `notifai init` to continue setup.'])
+    expect(io.outLines.join('\n')).not.toContain(root)
+    expect(io.errLines).toEqual([])
+
+    io.outLines = []
+    expect(cliUpdateCommand(deps, { json: true })).toBe(0)
+    const result = JSON.parse(io.outLines[0] ?? '{}') as Record<string, unknown>
+    expect(result).toMatchObject({
+      ok: true,
+      package_manager_prefix: managerPrefix,
+      update_prefix: realpathSync(stale.prefix),
+      after: {
+        effective: {
+          command_path: stale.command,
+          artifact_path: realpathSync(stale.artifact),
+          version: currentVersion,
+        },
+      },
+      hook_adapter: {
+        target: { scriptPath: realpathSync(stale.artifact) },
+      },
+    })
+  })
+})

package/src/client.ts

@@ -1,5 +1,6 @@
 import type {
   ApiErrorBody,
+  AccountAccessRequestResponse,
   AccountAccessResponse,
   BeginPairingResponse,
   CapabilityDocument,
@@ -78,6 +79,11 @@ export interface ApiClient {
   }): Promise<BeginPairingResponse>
   pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
   accessStatus(): Promise<AccountAccessResponse>
+  /**
+   * Read-only. There is no client-side write: filing this errand is the
+   * User's decision, and the server refuses it from a machine credential.
+   */
+  accessRequest(): Promise<AccountAccessRequestResponse>
   listDevices(): Promise<ListDevicesResponse>
   listSounds(): Promise<ListSoundsResponse>
   capabilities(
@@ -254,6 +260,7 @@ export function createClient(
         poll_verifier: pollVerifier,
       }),
     accessStatus: () => call('GET', '/api/v1/account/access'),
+    accessRequest: () => call('GET', '/api/v1/account/alpha-access-request'),
     listDevices: () => call('GET', '/api/v1/devices'),
     listSounds: () => call('GET', '/api/v1/sounds'),
     capabilities: (platform = 'ios', appVersion, appBuild) => {

package/src/codex-wake.ts

@@ -137,6 +137,8 @@ export function codexWakeRoute(options: {
   sourcePid: number
   env?: NodeJS.ProcessEnv
   adapters?: CodexWakeAdapters
+  /** False for a detached recovery owner whose stdout no harness will read. */
+  continuationActive?: boolean
 }): EscalationDeliveryRoute {
   const env = options.env ?? process.env
   const adapters = options.adapters ?? systemCodexWakeAdapters(env)
@@ -144,7 +146,9 @@ export function codexWakeRoute(options: {
   return {
     kind: 'hook-continuation',
     async deliver(event: ContinuationEvent): Promise<DeliveryOutcome> {
-      if (adapters.sourceAlive(options.sourcePid)) return continuation.deliver(event)
+      if (options.continuationActive !== false && adapters.sourceAlive(options.sourcePid)) {
+        return continuation.deliver(event)
+      }
 
       // Probe immediately before the spawn, twice, and never trust the earlier
       // answer: ownership is a kernel fact that can change between two syscalls,

package/src/commands-auth.ts

@@ -7,13 +7,15 @@ import { type FlagOverrides } from './config.js'
 import { checkApproveUrl } from './url-policy.js'
 import {
   EXIT,
+  SETUP_COMMAND,
   authedClient,
   loadLoggedConfig,
   makeClient,
   reportError,
   type CommandDeps,
 } from './commands-core.js'
-import { supportPageUrl } from './commands-devices.js'
+import { setupAccessUrl } from './setup-destinations.js'
+import type { ReadinessState } from './readiness.js'
 
 // ---------------------------------------------------------------------------
 // login / logout / auth status
@@ -30,9 +32,24 @@ export function pairingApprovalUrl(approveUrl: string, confirmationSecret: strin
   return url.toString()
 }
 
+/**
+ * Why a sign-in stopped, in the shape the close line renders.
+ *
+ * Without it, `init` fell back to the state it had before the attempt — "this
+ * machine is not paired … run `notifai init`" — so the last thing a User read
+ * contradicted the correct line three lines above it and pointed back at the
+ * command that had just failed, for a reason it never mentioned.
+ *
+ * Passing one also transfers the errand: whoever takes the blocker prints the
+ * close, so this command stops after naming what stopped. A sign-in run on its
+ * own has no such caller and states the errand itself.
+ */
+export type LoginBlockedSink = (blocker: ReadinessState) => void
+
 export async function loginCommand(
   deps: CommandDeps,
   flags: { name?: string; baseUrl?: string; open?: boolean },
+  onBlocked?: LoginBlockedSink,
 ): Promise<number> {
   const config = loadLoggedConfig(deps, { cwd: deps.cwd, env: deps.env, flags: { base_url: flags.baseUrl } as FlagOverrides })
   const baseUrl = config.base_url.value
@@ -121,21 +138,39 @@ export async function loginCommand(
       deps.io.err('Pairing was denied from the dashboard.')
       return EXIT.auth
     }
+    // Proof-gated: the server never returns this from lookup. Stop now rather
+    // than waiting out a TTL no approval can arrive within.
     if (poll.status === 'no_active_plan') {
-      const next =
-        poll.next_action ??
-        `Open ${supportPageUrl(baseUrl)} to request Alpha access, then retry.`
-      spinner?.error('Account has no Alpha access')
-      deps.io.err('This account has no active plan or temporary Alpha access.')
-      deps.io.err(`next: ${next}`)
-      deps.io.err('After access is granted, run `notifai login` again.')
+      // The server owns which access errand is current — requesting it today,
+      // choosing a plan after cutover — so its line wins whenever it sends one.
+      const next = poll.next_action ?? `Open ${setupAccessUrl(baseUrl)} to set up access, then retry.`
+      // Ends the wait, like its three siblings above and below; the wall
+      // itself belongs to the line under it, which said the same sentence a
+      // second time when this one tried to say it first.
+      spinner?.error('Pairing stopped')
+      // One wall, said once. When a caller takes the blocker it closes the
+      // visit on this exact errand, so repeating the destination here — and
+      // naming `init` as the way past a wall no command of theirs can open —
+      // would leave the User three phrasings of one step to choose between.
+      if (onBlocked === undefined) {
+        deps.io.err('This account has no active plan or temporary Alpha access.')
+        deps.io.err(`next: ${next}`)
+        deps.io.err(`After access is granted, run \`${SETUP_COMMAND}\` again.`)
+      }
+      onBlocked?.({
+        id: 'auth',
+        title: 'Access',
+        status: 'gap',
+        detail: 'this account does not have access to Notifai yet',
+        remedy: { by: 'user-elsewhere', summary: next },
+      })
       return EXIT.auth
     }
     if (poll.status === 'expired') break
     spinner?.message(approvalWaitMessage())
   }
   spinner?.error('Pairing expired')
-  deps.io.err('Pairing expired before it was approved. Run `notifai login` again.')
+  deps.io.err(`Pairing expired before it was approved. Run \`${SETUP_COMMAND}\` again.`)
   return EXIT.auth
 }
 
@@ -166,7 +201,7 @@ export function authStatusCommand(deps: CommandDeps, flags: { json?: boolean }):
     return credential ? EXIT.ok : EXIT.auth
   }
   if (!credential) {
-    deps.io.err('Not signed in. Run `notifai login`.')
+    deps.io.err(`Not signed in. Run \`${SETUP_COMMAND}\`; it will coordinate machine login and device setup.`)
     return EXIT.auth
   }
   deps.io.out(`Signed in as machine "${credential.machineName}" (${credential.machineId})`)
@@ -190,9 +225,8 @@ export async function accessStatusCommand(
       return access.status === 'active' ? EXIT.ok : EXIT.failed
     }
     if (access.status === 'no_active_plan') {
-      const supportUrl = supportPageUrl(authed.baseUrl)
-      deps.io.out('No active plan or temporary Alpha access for this account.')
-      deps.io.out(`next: Open ${supportUrl} to request Alpha access, then retry.`)
+      deps.io.out('This account does not have access to Notifai yet.')
+      deps.io.out(`next: Open ${setupAccessUrl(authed.baseUrl)} to set up access, then retry.`)
       return EXIT.failed
     }
     const expiry = access.expires_at ? ` until ${access.expires_at}` : ''

package/src/commands-core.ts

@@ -14,8 +14,10 @@ import { type HookAdapterTarget } from './hook-adapter.js'
 import { logConfigResolved, logSettingsFrom, nullLogger, type Logger } from './logging.js'
 import type { NativeSkills } from './native-skills.js'
 import type { OrcaSessionTitleLookup } from './orca-session-title.js'
+import type { QuestionSettlementLaunch } from './question-settlement-process.js'
 import { packageVersion } from './release.js'
 import type { Tone } from './ui/theme.js'
+import { cliUpdateRecoveryCommand } from './cli-update-contract.js'
 
 export interface CommandIo {
   out(line: string): void
@@ -80,6 +82,8 @@ export interface CommandDeps {
   /** Test seams for the Codex thread-writer probe and cold resume. */
   codexWake?: CodexWakeAdapters
   codexSourcePid?: number
+  /** Test seam for the detached owner recovered from a pre-Stop User prompt. */
+  spawnQuestionSettlement?: (launch: QuestionSettlementLaunch) => void
   /** Test seam and production adapter for the external native skills installer. */
   nativeSkills?: NativeSkills
   /** Test seam for Orca's exact-worktree task/session title lookup. */
@@ -184,7 +188,16 @@ export function authedClient(deps: CommandDeps, config: CliConfig): { client: Ap
   }
 }
 
-export const UPDATE_CLI_COMMAND = 'npm install -g @raidiant/notifai'
+/**
+ * Resolve a current CLI independently of PATH. A bare `notifai update` would
+ * be captured by the stale winner this action is meant to repair.
+ */
+export function updateCliCommand(_deps: Pick<CommandDeps, 'hookInstallTarget' | 'hookPlatform'>): string {
+  return cliUpdateRecoveryCommand()
+}
+
+/** The one first-run command an unsigned machine is told to run. */
+export const SETUP_COMMAND = 'notifai init'
 
 function affectedDeviceNames(details: unknown): string[] {
   if (typeof details !== 'object' || details === null || !('device_names' in details)) return []
@@ -199,10 +212,14 @@ function naturalList(values: readonly string[]): string {
   return `${values.slice(0, -1).join(', ')}, and ${values.at(-1)}`
 }
 
-function localRecovery(action: RecoveryAction | null, details: unknown): string | null {
+function localRecovery(
+  deps: Pick<CommandDeps, 'hookInstallTarget' | 'hookPlatform'>,
+  action: RecoveryAction | null,
+  details: unknown,
+): string | null {
   switch (action) {
     case 'update_cli':
-      return `next: ${UPDATE_CLI_COMMAND}`
+      return `next: ${updateCliCommand(deps)}`
     case 'update_companion': {
       const names = affectedDeviceNames(details)
       return names.length > 0
@@ -268,7 +285,7 @@ export function reportError(
     const recovery =
       err.code === 'no_active_devices'
         ? 'next: Run `notifai init` to connect an active Companion App; it will complete machine setup and identify any human-only device step.'
-        : localRecovery(err.recoveryAction, err.details)
+        : localRecovery(deps, err.recoveryAction, err.details)
     if (recovery !== null) deps.io.err(recovery)
     else if (err.recoveryAction === null && err.nextAction) deps.io.err(`next: ${err.nextAction}`)
     if (err.code === 'auth_required' || err.code === 'machine_revoked') return EXIT.auth

package/src/commands-devices.ts

@@ -8,6 +8,11 @@ import {
   resolvedBaseUrl,
   type CommandDeps,
 } from './commands-core.js'
+import {
+  companionPlatformLabel,
+  setupCompanionUrl,
+  type CompanionPlatform,
+} from './setup-destinations.js'
 
 // ---------------------------------------------------------------------------
 // devices / capabilities
@@ -40,15 +45,15 @@ export async function devicesCommand(
         deps.io.out(`No ${platform} devices registered.`)
         return EXIT.ok
       }
-      const supportUrl = supportPageUrl(authed.baseUrl)
+      const setupUrl = setupCompanionUrl(authed.baseUrl)
       let email: string | null = null
       try {
         email = (await authed.client.accessStatus()).email
       } catch {
-        // Best-effort: the empty-state copy still points at /support without it.
+        // Best-effort: the empty-state copy still names the destination.
       }
       deps.io.out(
-        `No devices yet. Install Notifai from ${supportUrl}, ${sameAccountSignInLine(email)}, and allow notifications.`,
+        `No devices yet. Set up a Companion App at ${setupUrl}, ${sameAccountSignInLine(email)}, and allow notifications.`,
       )
       return EXIT.ok
     }
@@ -120,14 +125,6 @@ export async function capabilitiesCommand(
   }
 }
 
-export function supportPageUrl(baseUrl: string): string {
-  const normalized = baseUrl.replace(/\/+$/, '')
-  if (normalized === 'https://api.notifai.sh' || normalized === 'https://notifai.fly.dev') {
-    return 'https://app.notifai.sh/support'
-  }
-  return `${normalized}/support`
-}
-
 /** Same-account line for the device hop; prefers the real email when known. */
 export function sameAccountSignInLine(email: string | null | undefined): string {
   return email
@@ -135,18 +132,28 @@ export function sameAccountSignInLine(email: string | null | undefined): string
     : 'sign in with the same email as this account'
 }
 
+/**
+ * What is actually left to do on the phone.
+ *
+ * Three sub-states, three remedies. "Install the app" is useless advice to
+ * someone who installed it and then declined the permission prompt, and
+ * offering install steps to a registered device says this terminal did not
+ * read the state it just fetched.
+ */
 export function deviceInstallRemedy(options: {
   baseUrl: string
   email: string | null
   devices: readonly RoutableDevice[]
+  platform?: CompanionPlatform
 }): string {
-  const support = supportPageUrl(options.baseUrl)
   const sameEmail = sameAccountSignInLine(options.email)
   if (options.devices.length === 0) {
-    return (
-      `open the Companion App install steps at ${support} on a supported device, ` +
-      `install Notifai, ${sameEmail}, and allow notifications`
-    )
+    const destination = setupCompanionUrl(options.baseUrl, options.platform)
+    const named =
+      options.platform === undefined
+        ? 'the Companion App'
+        : `Notifai on ${companionPlatformLabel(options.platform)}`
+    return `open the steps for ${named} at ${destination}, install it, ${sameEmail}, and allow notifications`
   }
   if (options.devices.some((d) => d.permission_status === 'denied')) {
     return "allow notifications for Notifai in the device's Settings"