@raidiant/notifai 10.1.0 → 10.1.1

package/src/cli-bin.test.ts

@@ -1,10 +1,60 @@
-import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { cliBinReadiness, isExecutablePath, pathNotifaiEntries } from './cli-bin.js'
+import { cliUpdateRecoveryCommand } from './cli-update-contract.js'
 
 describe('PATH notifai diagnosis', () => {
+  function posixInstall(root: string, name: string, version: string) {
+    const prefix = path.join(root, name)
+    const artifact = path.join(
+      prefix,
+      'lib',
+      'node_modules',
+      '@raidiant',
+      'notifai',
+      '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(path.dirname(path.dirname(artifact)), 'package.json'), JSON.stringify({ version }))
+    writeFileSync(artifact, '#!/usr/bin/env node\n')
+    chmodSync(artifact, 0o755)
+    symlinkSync(path.relative(path.dirname(command), artifact), command)
+    return { prefix, artifact, command }
+  }
+
+  function windowsInstall(root: string, name: string, version: string) {
+    const prefix = path.join(root, name)
+    const artifact = path.join(
+      prefix,
+      'node_modules',
+      '@raidiant',
+      'notifai',
+      'dist',
+      'main.js',
+    )
+    const command = path.join(prefix, 'notifai.cmd')
+    mkdirSync(path.dirname(artifact), { recursive: true })
+    writeFileSync(path.join(path.dirname(path.dirname(artifact)), 'package.json'), JSON.stringify({ version }))
+    writeFileSync(artifact, '#!/usr/bin/env node\n')
+    writeFileSync(
+      command,
+      '@ECHO off\r\nnode "%dp0%node_modules\\@raidiant\\notifai\\dist\\main.js" %*\r\n',
+    )
+    return { prefix, artifact, command }
+  }
+
   it('reports a non-executable PATH binary as a gap', () => {
     if (process.platform === 'win32') return
     const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-gap-'))
@@ -14,8 +64,10 @@ describe('PATH notifai diagnosis', () => {
     expect(isExecutablePath(file, 'darwin')).toBe(false)
     const state = cliBinReadiness({ PATH: directory }, 'darwin')
     expect(state.status).toBe('gap')
-    expect(state.detail).toContain(file)
-    expect(state.remedy?.command).toBe('npm install -g @raidiant/notifai')
+    expect(state.detail).not.toContain(file)
+    expect(state.technical).toMatchObject({ entries: [{ command_path: file, executable: false }] })
+    expect(state.remedy?.command).not.toBe('notifai update')
+    expect(state.remedy?.command).toMatch(/ update$/)
   })
 
   it('treats an executable PATH binary as ready', () => {
@@ -25,14 +77,100 @@ describe('PATH notifai diagnosis', () => {
     writeFileSync(file, '#!/usr/bin/env node\n')
     chmodSync(file, 0o755)
     expect(pathNotifaiEntries({ PATH: directory }, 'darwin')).toEqual([file])
-    expect(cliBinReadiness({ PATH: directory }, 'darwin').status).toBe('ready')
+    expect(
+      cliBinReadiness({ PATH: directory }, 'darwin', {
+        runningArtifactPath: file,
+        currentVersion: null,
+      }).status,
+    ).toBe('ready')
+  })
+
+  it('does not call an older executable PATH winner ready when this process is the current CLI', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-stale-winner-'))
+    const old = posixInstall(root, 'old', '3.0.1')
+    const current = posixInstall(root, 'current', '10.1.0')
+
+    const state = cliBinReadiness(
+      { PATH: `${path.dirname(old.command)}:${path.dirname(current.command)}` },
+      'darwin',
+      {
+        runningArtifactPath: current.artifact,
+        currentVersion: '10.1.0',
+      },
+    )
+
+    expect(state.status).toBe('gap')
+    expect(state.detail).not.toContain(old.command)
+    expect(state.remedy?.command).toBe(
+      cliUpdateRecoveryCommand(),
+    )
+    expect(state.remedy?.command).not.toContain(old.command)
+    expect(state.technical).toMatchObject({
+      current: { artifact_path: realpathSync(current.artifact), version: '10.1.0' },
+      effective: { command_path: old.command, artifact_path: realpathSync(old.artifact), version: '3.0.1' },
+    })
+  })
+
+  it('uses Windows Path order to reject an older executable winner', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-windows-winner-'))
+    const old = windowsInstall(root, 'old', '3.0.1')
+    const current = windowsInstall(root, 'current', '10.1.0')
+
+    const state = cliBinReadiness(
+      { Path: `${old.prefix};${current.prefix}` },
+      'win32',
+      {
+        runningArtifactPath: current.artifact,
+        currentVersion: '10.1.0',
+      },
+    )
+
+    expect(state.status).toBe('gap')
+    expect(state.remedy?.command).toBe(
+      cliUpdateRecoveryCommand(),
+    )
+    expect(state.technical).toMatchObject({
+      effective: {
+        command_path: old.command,
+        artifact_path: realpathSync(old.artifact),
+        version: '3.0.1',
+      },
+    })
+  })
+
+  it('keeps a healthy winner ready while reporting a later broken duplicate for cleanup', () => {
+    const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-later-broken-'))
+    const current = posixInstall(root, 'current', '10.1.0')
+    const broken = posixInstall(root, 'broken', '3.0.1')
+    chmodSync(broken.artifact, 0o644)
+
+    const state = cliBinReadiness(
+      { PATH: `${path.dirname(current.command)}:${path.dirname(broken.command)}` },
+      'darwin',
+      { runningArtifactPath: current.artifact, currentVersion: '10.1.0' },
+    )
+
+    expect(state.status).toBe('optional-gap')
+    expect(state.detail).toContain('ready')
+    expect(state.detail).not.toContain(broken.command)
+    expect(state.technical).toMatchObject({
+      effective: { command_path: current.command, executable: true },
+      entries: [
+        { command_path: current.command, executable: true },
+        { command_path: broken.command, executable: false },
+      ],
+    })
   })
 
-  it('is ready when PATH has no notifai entry', () => {
+  it('does not call a PATH with no notifai entry ready', () => {
     const directory = mkdtempSync(path.join(os.tmpdir(), 'notifai-bin-empty-'))
     mkdirSync(directory, { recursive: true })
     const state = cliBinReadiness({ PATH: directory }, process.platform)
-    expect(state.status).toBe('ready')
-    expect(state.detail).toContain('no notifai binary was on PATH')
+    // The running process proves nothing about the command every printed next
+    // step names — but it is running, so this cannot stand in the way either.
+    expect(state.status).toBe('optional-gap')
+    expect(state.detail).toContain('will not be found')
+    expect(state.remedy?.command).not.toBe('notifai update')
+    expect(state.remedy?.command).toMatch(/ update$/)
   })
 })

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

@@ -14,7 +14,8 @@ import {
   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
@@ -31,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
@@ -122,14 +138,32 @@ 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 \`${SETUP_COMMAND}\` 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
@@ -191,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}` : ''