fix: improve cloud remote auth UX (#452)

Author: thymikee

skills/agent-device/references/remote-tenancy.md

@@ -15,7 +15,7 @@ Open this file for remote daemon HTTP flows that let an agent running in a Linux
 - `agent-device disconnect --remote-config <path>`
 - `agent-device connection status`
 - `agent-device auth status`
-- `AGENT_DEVICE_DAEMON_AUTH_TOKEN=...` for CI/service-token automation
+- `AGENT_DEVICE_DAEMON_AUTH_TOKEN=adc_live_...` for CI/service-token automation
 
 ## Most common mistake to avoid
 
@@ -42,7 +42,7 @@ agent-device fill @e3 "test@example.com"
 agent-device disconnect
 ```
 
-After `connect`, normal commands use the active remote connection. If cloud credentials are missing, `connect` starts login automatically in an interactive shell and stores a revocable CLI session that silently mints short-lived `adc_agent_...` command tokens. The cloud side remains responsible for token expiry, tenant/run claim checks, revocation, one-time device approval, and polling rate limits. End with `disconnect` to release the lease and stop the owned Metro companion.
+After `connect`, normal commands use the active remote connection. If cloud credentials are missing, `connect` starts login automatically in an interactive local shell and stores a revocable CLI session that silently mints short-lived `adc_agent_...` command tokens. Linux sandboxes, CI, and other non-interactive shells should set `AGENT_DEVICE_DAEMON_AUTH_TOKEN=adc_live_...` instead. The cloud side remains responsible for token expiry, tenant/run claim checks, revocation, one-time device approval, and polling rate limits. End with `disconnect` to release the lease and stop the owned Metro companion.
 
 ### Self-contained script flow
 
@@ -72,7 +72,7 @@ The first command that needs a lease or Metro runtime prepares and persists it.
 ## Behavior summary
 
 - `connect` stores local non-secret connection state and defers tenant lease allocation plus Metro preparation until a later command needs them.
-- Commands such as `install-from-source`, `open`, `snapshot`, and `apps` allocate or refresh the lease when needed.
+- Commands such as `install-from-source`, `open`, `snapshot`, `devices`, and `apps` allocate or refresh the lease when needed.
 - `open` prepares Metro runtime hints when the remote profile has Metro fields and no compatible runtime is already saved.
 - `metro reload` reuses saved Metro runtime hints and asks Metro to reload connected React Native apps without restarting the native process.
 - `batch` also prepares Metro when any step opens an app and that step does not provide its own runtime.
@@ -126,6 +126,7 @@ Optional overrides stay available for advanced cases:
 - Put `tenant`, `runId`, and `sessionIsolation` in the remote profile so agents can run `agent-device connect --remote-config ./remote-config.json` without extra scope flags. Add `platform`, `leaseBackend`, `session`, or Metro overrides only when the default inference is not enough for that flow.
 - Explicit command-line flags override connected defaults. Use them intentionally when switching session, platform, target, tenant, run, or lease scope.
 - For React Native Metro runs with `metroProxyBaseUrl`, `agent-device >= 0.11.12` can manage the local companion tunnel, but Metro itself still needs to be running locally. `metroProxyBaseUrl` is the bridge origin, not a prebuilt `/api/metro/...` route.
+- Set `AGENT_DEVICE_CLOUD_BASE_URL` to the bridge/control-plane API origin. It does not need to be the dashboard origin; `/api-keys` on the bridge can redirect to the dashboard for service-token setup.
 - For cloud stock React Native iOS, use the bridge descriptor's wildcard HTTPS Metro hints directly; do not install or launch the XCTest runner just to make Metro reachable.
 - Android keeps using bridge-provided `/api/metro/runtimes/<runtimeId>/...` Metro routes.
 - `metroPublicBaseUrl` is only needed for direct/non-bridge bundle hints. Bridged profiles can omit it.

src/__tests__/cli-config.test.ts

@@ -535,6 +535,74 @@ test('normal commands accept direct remote-config usage', async () => {
   fs.rmSync(root, { recursive: true, force: true });
 });
 
+test('devices allocates a pending remote lease before listing devices', async () => {
+  const { root, home, project } = makeTempWorkspace();
+  const stateDir = path.join(root, 'state');
+  const remoteConfig = path.join(project, 'agent-device.remote.json');
+  fs.writeFileSync(
+    remoteConfig,
+    JSON.stringify({
+      daemonBaseUrl: 'http://remote-mac.example.test:9124/agent-device',
+      tenant: 'acme',
+      runId: 'run-123',
+      platform: 'android',
+    }),
+    'utf8',
+  );
+
+  const connectResult = await runCliCapture(
+    ['connect', '--remote-config', remoteConfig, '--state-dir', stateDir, '--json'],
+    { cwd: project, env: { HOME: home } },
+  );
+  assert.equal(connectResult.code, null);
+
+  const result = await runCliCapture(['devices', '--state-dir', stateDir, '--json'], {
+    cwd: project,
+    env: { HOME: home },
+    sendToDaemon: async (req) => {
+      if (req.command === 'lease_allocate') {
+        return {
+          ok: true,
+          data: {
+            lease: {
+              leaseId: 'lease-devices-001',
+              tenantId: 'acme',
+              runId: 'run-123',
+              backend: 'android-instance',
+            },
+          },
+        };
+      }
+      if (req.command === 'devices') {
+        return {
+          ok: true,
+          data: {
+            devices: [
+              {
+                id: 'emulator-5554',
+                name: 'Pixel 8',
+                platform: 'android',
+                kind: 'emulator',
+                booted: true,
+              },
+            ],
+          },
+        };
+      }
+      throw new Error(`unexpected daemon command: ${req.command}`);
+    },
+  });
+
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 2);
+  assert.equal(result.calls[0]?.command, 'lease_allocate');
+  assert.equal(result.calls[1]?.command, 'devices');
+  assert.equal(result.calls[1]?.flags?.leaseId, 'lease-devices-001');
+  assert.equal(result.calls[1]?.meta?.leaseId, 'lease-devices-001');
+
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
 test('direct remote-config command does not fall back to unrelated active session', async () => {
   const { root, home, project } = makeTempWorkspace();
   const stateDir = path.join(root, 'state');

src/__tests__/cli-help.test.ts

@@ -34,6 +34,15 @@ test('appstate --help prints command help and skips daemon dispatch', async () =
   assert.match(result.stdout, /Global flags:/);
 });
 
+test('connect help documents cloud auth environment origins', async () => {
+  const result = await runCliCapture(['help', 'connect']);
+  assert.equal(result.code, 0);
+  assert.equal(result.calls.length, 0);
+  assert.match(result.stdout, /AGENT_DEVICE_CLOUD_BASE_URL/);
+  assert.match(result.stdout, /bridge\/control-plane API origin/);
+  assert.match(result.stdout, /AGENT_DEVICE_DAEMON_AUTH_TOKEN/);
+});
+
 test('help react-devtools prints passthrough command help and skips daemon dispatch', async () => {
   const result = await runCliCapture(['help', 'react-devtools']);
   assert.equal(result.code, 0);

src/__tests__/remote-connection.test.ts

@@ -189,6 +189,8 @@ test('connect reports deferred Metro runtime preparation when remote config has
     });
   });
 
+  assert.match(stdout, /Lease allocation is pending/);
+  assert.match(stdout, /open, snapshot, or devices/);
   assert.match(stdout, /Metro runtime is not prepared yet/);
   assert.match(stdout, /metro prepare --remote-config/);
   assert.equal(readActiveConnectionState({ stateDir })?.runtime, undefined);
@@ -677,6 +679,66 @@ test('deferred materialization heartbeats an existing lease before dispatch', as
   fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('deferred materialization allocates pending lease for devices', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-connect-devices-'));
+  const stateDir = path.join(tempRoot, '.state');
+  const remoteConfigPath = path.join(tempRoot, 'remote.json');
+  fs.writeFileSync(remoteConfigPath, JSON.stringify({ daemonBaseUrl: 'https://daemon.example' }));
+  writeRemoteConnectionState({
+    stateDir,
+    state: {
+      version: 1,
+      session: 'adc-android',
+      remoteConfigPath,
+      remoteConfigHash: hashRemoteConfigFile(remoteConfigPath),
+      daemon: { baseUrl: 'https://daemon.example' },
+      tenant: 'acme',
+      runId: 'run-123',
+      platform: 'android',
+      connectedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  });
+  let allocateCount = 0;
+
+  const materialized = await materializeRemoteConnectionForCommand({
+    command: 'devices',
+    flags: {
+      json: true,
+      help: false,
+      version: false,
+      stateDir,
+      remoteConfig: remoteConfigPath,
+      daemonBaseUrl: 'https://daemon.example',
+      tenant: 'acme',
+      runId: 'run-123',
+      session: 'adc-android',
+      platform: 'android',
+    },
+    client: createTestClient({
+      allocate: async (request) => {
+        allocateCount += 1;
+        return {
+          leaseId: 'lease-devices',
+          tenantId: request.tenant,
+          runId: request.runId,
+          backend: request.leaseBackend ?? 'android-instance',
+        };
+      },
+    }),
+  });
+
+  assert.equal(allocateCount, 1);
+  assert.equal(materialized.flags.leaseId, 'lease-devices');
+  assert.equal(materialized.flags.leaseBackend, 'android-instance');
+  assert.equal(
+    readRemoteConnectionState({ stateDir, session: 'adc-android' })?.leaseId,
+    'lease-devices',
+  );
+
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
 test('deferred materialization reallocates when the persisted lease is inactive', async () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-connect-stale-lease-'));
   const stateDir = path.join(tempRoot, '.state');

src/cli.ts

@@ -60,7 +60,6 @@ const REMOTE_MATERIALIZATION_DEFERRED_COMMANDS = new Set([
   'connect',
   'connection',
   'close',
-  'devices',
   'disconnect',
   'ensure-simulator',
   'metro',

src/cli/__tests__/auth-session.test.ts

@@ -12,6 +12,7 @@ import {
   summarizeCliSession,
   writeCliSession,
 } from '../auth-session.ts';
+import { normalizeError } from '../../utils/errors.ts';
 
 const baseFlags = {
   json: false,
@@ -63,6 +64,31 @@ test('remote auth fails in CI with service token instructions', async () => {
   fs.rmSync(tempRoot, { recursive: true, force: true });
 });
 
+test('non-interactive auth hint preserves safe API-token setup URL', async () => {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-auth-url-hint-'));
+
+  try {
+    await resolveRemoteAuth({
+      command: 'connect',
+      flags: { ...baseFlags, daemonBaseUrl: 'https://bridge.agent-device.dev' },
+      stateDir: tempRoot,
+      allowInteractiveLogin: true,
+      env: {
+        CI: 'true',
+        AGENT_DEVICE_CLOUD_BASE_URL: 'https://bridge.agent-device.dev',
+      },
+      io: { stdinIsTTY: true, stdoutIsTTY: true },
+    });
+    assert.fail('expected non-interactive auth to fail');
+  } catch (error) {
+    const normalized = normalizeError(error);
+    assert.match(normalized.hint ?? '', /https:\/\/bridge\.agent-device\.dev\/api-keys/);
+    assert.doesNotMatch(normalized.hint ?? '', /\[REDACTED\]/);
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('remote auth leaves non-cloud remote daemons to existing daemon auth validation', async () => {
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-auth-non-cloud-'));
   writeCliSession({

src/cli/commands/connection-runtime.ts

@@ -21,7 +21,6 @@ const leaseDeferredCommands = new Set([
   'connect',
   'connection',
   'close',
-  'devices',
   'disconnect',
   'ensure-simulator',
   'metro',

src/cli/commands/connection.ts

@@ -108,13 +108,15 @@ export const connectCommand: ClientCommandHandler = async ({ flags, client }) =>
     await stopReactDevtoolsCleanup({ stateDir, state: previous });
     await releasePreviousLease(client, previous);
   }
+  const leasePreparation = buildLeasePreparationNotice(state);
   const runtimePreparation = buildRuntimePreparationNotice(flags, state);
 
   writeCommandOutput(flags, serializeConnectionState(state, runtimePreparation), () =>
     [
       `Connected remote session "${session}" tenant "${tenant}" run "${runId}" ${
         state.leaseId ? `lease ${state.leaseId}` : 'lease pending'
       }`,
+      leasePreparation?.message,
       runtimePreparation?.message,
     ]
       .filter((line): line is string => Boolean(line))
@@ -185,13 +187,15 @@ export const connectionCommand: ClientCommandHandler = async ({ positionals, fla
     );
     return true;
   }
+  const leasePreparation = buildLeasePreparationNotice(state);
   const runtimePreparation = buildRuntimePreparationNoticeFromState(state);
   writeCommandOutput(flags, serializeConnectionState(state, runtimePreparation), () =>
     [
       `Connected remote session "${state.session}".`,
       `tenant=${state.tenant} runId=${state.runId} leaseId=${state.leaseId ?? 'pending'} backend=${state.leaseBackend ?? 'pending'}`,
       `remoteConfig=${state.remoteConfigPath}`,
       state.runtime ? 'metro=prepared' : 'metro=not-prepared',
+      leasePreparation?.message,
       runtimePreparation?.message,
     ]
       .filter((line): line is string => Boolean(line))
@@ -256,6 +260,12 @@ type RuntimePreparationNotice = {
   nextStep: string;
 };
 
+type LeasePreparationNotice = {
+  status: 'deferred';
+  message: string;
+  nextSteps: string[];
+};
+
 function buildRuntimePreparationNotice(
   flags: CliFlags,
   state: RemoteConnectionState,
@@ -274,6 +284,29 @@ function buildRuntimePreparationNoticeFromState(
   return buildDeferredRuntimeNotice(state.remoteConfigPath);
 }
 
+function buildLeasePreparationNotice(
+  state: RemoteConnectionState,
+): LeasePreparationNotice | undefined {
+  if (state.leaseId) return undefined;
+  const needsPlatform =
+    state.platform === undefined && state.leaseBackend === undefined
+      ? ' Add --platform ios|android if the profile does not set a platform.'
+      : '';
+  const nextSteps = [
+    'agent-device install-from-source <artifact-url> --platform ios|android',
+    'agent-device open <app-id> --relaunch',
+    'agent-device snapshot -i',
+    'agent-device devices',
+  ];
+  return {
+    status: 'deferred',
+    nextSteps,
+    message:
+      'Lease allocation is pending; run install-from-source, open, snapshot, or devices when ready to allocate or refresh the lease.' +
+      needsPlatform,
+  };
+}
+
 function buildDeferredRuntimeNotice(remoteConfigPath: string): RuntimePreparationNotice {
   const nextStep = `agent-device metro prepare --remote-config ${remoteConfigPath}`;
   return {
@@ -308,6 +341,7 @@ function serializeConnectionState(
   state: RemoteConnectionState,
   runtimePreparation?: RuntimePreparationNotice,
 ): Record<string, unknown> {
+  const leasePreparation = buildLeasePreparationNotice(state);
   return {
     connected: true,
     session: state.session,
@@ -324,6 +358,7 @@ function serializeConnectionState(
     metro: state.metro
       ? { prepared: true, projectRoot: state.metro.projectRoot }
       : { prepared: false },
+    ...(leasePreparation ? { leasePreparation } : {}),
     ...(runtimePreparation ? { runtimePreparation } : {}),
     connectedAt: state.connectedAt,
     updatedAt: state.updatedAt,

src/utils/__tests__/diagnostics.test.ts

@@ -63,6 +63,9 @@ test('diagnostics redacts sensitive fields', async () => {
           data: {
             token: 'secret-token',
             text: 'sensitive text',
+            responseText:
+              'access_token=oauth-access refresh_token:oauth-refresh password=https://secret.example/token',
+            setupHint: 'Create a service/API token: https://bridge.agent-device.dev/api-keys',
             nested: { authorization: 'Bearer abc' },
             agentToken: 'adc_agent_secret',
             deviceUrl: 'https://cloud.agent-device.dev/device?user_code=ABCD-EFGH',
@@ -83,9 +86,17 @@ test('diagnostics redacts sensitive fields', async () => {
     const payload = rows[0]?.data ?? {};
     assert.equal(payload.token, '[REDACTED]');
     assert.equal(payload.text, 'sensitive text');
+    assert.equal(
+      payload.responseText,
+      'access_token=[REDACTED] refresh_token:[REDACTED] password=[REDACTED]',
+    );
+    assert.equal(
+      payload.setupHint,
+      'Create a service/API token: https://bridge.agent-device.dev/api-keys',
+    );
     assert.equal(payload.nested?.authorization, '[REDACTED]');
     assert.equal(payload.agentToken, '[REDACTED]');
-    assert.equal(payload.deviceUrl, '[REDACTED]');
+    assert.equal(payload.deviceUrl, 'https://cloud.agent-device.dev/device?REDACTED');
     assert.equal(payload.userCode, '[REDACTED]');
     assert.equal(payload.safe, 'ok');
   } finally {