@lanes-sh/link 0.2.1 → 0.3.0

package/src/cli/commands/connect/index.ts

@@ -1,18 +1,22 @@
-import { createMcpConnector } from '#connectivity/transports';
-import { bearerTokenAsStored } from '#connectivity/auth/index.ts';
-import type { DiscoveredCapability } from '#connectivity';
 import { credentialRefForConnection, WRITE_BUNDLE } from '#connectivity';
-import { ConfigDocument, ensureSetupConnection, repaired } from '../../config-edit.ts';
-import { emit, print, progress, style } from '../../output.ts';
+import { ConfigDocument } from '../../config-edit.ts';
+import { ensureSetupConnection, repaired } from '../../config-repair.ts';
+import { emit, print } from '../../output.ts';
 import { nonInteractivePrompter, terminalPrompter, type Prompter } from '../../prompt.ts';
 import { openRuntime, type GlobalFlags } from '../../runtime.ts';
-import { credentialApp, matchesRule, moveCredential, siblingAccountId } from './accounts.ts';
+import { matchesRule, moveCredential, siblingAccountId } from './accounts.ts';
+import { discoverCapabilities } from './discover.ts';
+import { connectFamily, familyMembers } from './family.ts';
+import { authoriseWithKey } from './assertion.ts';
 import { authorise } from './authorise.ts';
+import { authorisePastedToken } from './pasted-token.ts';
+import { chooseAuthMethod } from './method.ts';
 import { preflight } from './requirements.ts';
-import { ALREADY, NOTHING, renderOutcome, type ConnectOutcome } from './outcome.ts';
+import { ALREADY, NOTHING, renderOutcome, where, type ConnectOutcome } from './outcome.ts';
 import { nextAfterEdit, publishRuntimeEdit } from '#cli/publish.ts';
 import { ensureStaticCredential } from './setup.ts';
 import { settleIdentity } from './settle.ts';
+import { announceConnectTarget } from './target-note.ts';
 
 /**
  * `lanes link connect <provider>` — the one command that adds an account.
@@ -48,7 +52,23 @@ export interface ConnectOptions extends GlobalFlags {
    * and then forgotten, which is the right shape for a decision about a client
    * that is shared by every connection of that vendor.
    */
+  /**
+   * `--own-client`, the older spelling of one of the routes `--auth` now names.
+   *
+   * Kept because it is in scripts and in a year of documentation, and because
+   * it still says something true. It resolves to `--auth own_client`.
+   */
   readonly ownClient?: boolean | undefined;
+  /**
+   * `--auth <method>`: which way in, for a provider that offers more than one.
+   *
+   * Unset means ask, where there is somebody to ask and something to ask
+   * about. It is not sticky the way `--own-client` is: `--own-client` writes an
+   * `oauth_apps` entry that every connection of the vendor then reads, whereas
+   * this decides one connection's credential and is recorded by that credential
+   * existing. Two accounts on the same profile may honestly differ.
+   */
+  readonly auth?: string | undefined;
   /** Injected for tests. The broker is the only thing `connect` fetches. */
   readonly fetch?: typeof globalThis.fetch | undefined;
   readonly json?: boolean | undefined;
@@ -63,18 +83,6 @@ export interface ConnectOptions extends GlobalFlags {
  */
 const PROVISIONAL_ID = 'pending';
 
-/**
- * What discovery is actually doing, per kind, so the wait is explained.
- *
- * They differ enough to be worth saying: reading a local OpenAPI file is
- * instant, while signing in to an IMAP server is a TLS handshake and a LOGIN
- * against a host that sometimes takes its time.
- */
-const DISCOVERY_NOTE: Record<string, string> = {
-  mcp: 'Discovering capabilities…',
-  http: 'Reading the API description…',
-};
-
 export async function connect(target: string, options: ConnectOptions): Promise<void> {
   const outcome = await runConnect(target, options);
 
@@ -83,7 +91,12 @@ export async function connect(target: string, options: ConnectOptions): Promise<
   return emit(options.json, outcome, () => renderOutcome(outcome));
 }
 
-async function runConnect(target: string, options: ConnectOptions): Promise<ConnectOutcome> {
+async function runConnect(
+  target: string,
+  options: ConnectOptions,
+  /** A family member — the account this belongs to has already said where it goes. */
+  announced = false,
+): Promise<ConnectOutcome> {
   const separator = target.indexOf('.');
   const providerId = separator === -1 ? target : target.slice(0, separator);
   const namedId = separator === -1 ? undefined : target.slice(separator + 1);
@@ -93,52 +106,29 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
   const runtime = await openRuntime(options);
 
   try {
+    // After the runtime rather than before, like every other command that
+    // announces: the alternative is resolving the profile twice, which for a
+    // `gs://` workspace is a second network read of the same YAML. Still long
+    // before the browser opens, which is the part that matters. Inside the
+    // `try` so the `finally` closes the runtime if the rendering throws.
+    if (!announced) announceConnectTarget(runtime, options.json);
+
     const registry = runtime.registry;
     const entry = registry.get(providerId);
 
-    // `lanes link connect icloud` — an account rather than a provider.
-    //
-    // Everyone models iCloud this way: Apple's own Settings, macOS Internet
-    // Accounts, Thunderbird, DAVx⁵. One authorisation, three services. It is
-    // three *providers* underneath because mail and calendars are different
-    // protocols, and because a policy line per provider is what lets someone
-    // allow `icloud_calendar.*` while never granting mail — but nobody should
-    // have to know that to connect their account.
+    // One name, several providers. `family.ts` says why iCloud is three.
     if (!entry) {
-      const family = registry
-        .list()
-        .filter((candidate) => credentialApp(candidate.manifest) === providerId)
-        .map((candidate) => candidate.manifest.id);
+      const members = familyMembers(registry, providerId);
 
-      if (family.length > 1) {
+      if (members.length > 1) {
         await runtime.close();
-        progress(
-          style.dim(`${providerId} is ${family.length} services on one account: ${family.join(', ')}`),
-        );
-        // In sequence, and the order matters: the first settles the account id
-        // and stores the credential, and the rest find both already there.
-        //
-        // The id travels as a flag because the family members are addressed by
-        // their own names: `connect icloud.will` parses `will` off a target
-        // that is then thrown away, and recursing with `options` alone dropped
-        // it — the command named an account and each member silently invented
-        // its own.
-        const inherited = { ...options, id: options.id ?? namedId };
-        const members: ConnectOutcome[] = [];
-        for (const member of family) members.push(await runConnect(member, inherited));
-
-        // The whole account succeeded only if every service did. A partial
-        // result is the case worth surfacing: one member blocked on a value
-        // leaves an account half connected, which `status` shows and prose does
-        // not.
-        return {
-          ...NOTHING,
-          ok: members.every((outcome) => outcome.ok),
+        return connectFamily({
+          name: providerId,
           members,
-          ...(members.find((outcome) => !outcome.ok)?.reason
-            ? { reason: members.find((outcome) => !outcome.ok)!.reason }
-            : {}),
-        };
+          options,
+          namedId,
+          connect: runConnect,
+        });
       }
     }
 
@@ -175,7 +165,26 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
 
     const profile = runtime.resolution.profile;
 
-    // 0. With nobody to ask, resolve everything up front or refuse saying why.
+    const prompter: Prompter =
+      options.nonInteractive === true
+        ? nonInteractivePrompter(`lanes link setup plan ${providerId} --profile ${profile}`)
+        : terminalPrompter;
+
+    // 0a. Which way in, before anything is resolved or written.
+    //
+    //     Ahead of the preflight because it changes the answer: one route needs
+    //     a browser and the other needs a key, and refusing a scripted run for
+    //     want of a browser it was never going to open is a refusal about the
+    //     wrong thing. Inert for every provider declaring one method, which is
+    //     all of them but one vendor's.
+    const method = await chooseAuthMethod({
+      manifest,
+      requested: options.auth,
+      ownClient: options.ownClient === true,
+      prompter,
+    });
+
+    // 0b. With nobody to ask, resolve everything up front or refuse saying why.
     //
     //    Before any write, so a refusal leaves the profile exactly as it was.
     //    The whole list comes back at once: discovering a missing value a
@@ -185,19 +194,36 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
         manifest,
         connectionId: named ?? adopted,
         profile,
+        target: runtime.target,
         credentials: runtime.credentials,
-        target,
+        spec: target,
+        method: method.kind,
       });
 
       if (blocked) return { ...NOTHING, ok: false, ...blocked };
     }
 
-    const prompter: Prompter =
-      options.nonInteractive === true
-        ? nonInteractivePrompter(`lanes link setup plan ${providerId} --profile ${profile}`)
-        : terminalPrompter;
-
-    if (manifest.auth.kind === 'oauth') {
+    if (method.kind === 'assertion') {
+      await authoriseWithKey({
+        manifest,
+        assertion: method.assertion,
+        connectionId: provisionalId,
+        credentials: runtime.credentials,
+        changes,
+        // Same reading as the static-credential arm below: naming a connection,
+        // or asking outright, is how someone says "that one again" — which is
+        // what a rotated key calls for.
+        replace: options.nonInteractive !== true && (options.replace === true || named !== undefined),
+        prompter,
+      });
+    } else if (method.kind === 'pasted') {
+      await authorisePastedToken({
+        manifest,
+        connectionId: provisionalId,
+        credentials: runtime.credentials,
+        prompter,
+      });
+    } else if (manifest.auth.kind === 'oauth') {
       await authorise({
         manifest,
         connectionId: provisionalId,
@@ -207,7 +233,7 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
         firstForProvider: !runtime.config.connections.some((c) => c.provider === providerId),
         target,
         profile,
-        ownClient: options.ownClient === true,
+        client: method.client,
         prompter,
         acceptBroadScopes: options.acceptBroadScopes === true,
         ...(options.fetch ? { fetch: options.fetch } : {}),
@@ -257,52 +283,18 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
       if (from && to && from !== to) await moveCredential(runtime.credentials, from, to);
     }
 
-    // 3. Ask the upstream what it exposes. A manifest never declares
-    //    capabilities for a proxied server — the server is the source of truth,
-    //    and a declared list would go stale the moment the vendor ships.
-    let discovered: DiscoveredCapability[] = [];
-
-    if (manifest.connector.kind !== 'local') {
-      progress(style.dim(DISCOVERY_NOTE[manifest.connector.kind] ?? 'Discovering capabilities…'));
-
-      // MCP is the one kind that does not use the runtime's connector here: it
-      // wants the token exactly as just written, without the refresh machinery
-      // that `bearerToken` wraps around it. Every other kind carries whatever
-      // credential it needs from the factory.
-      const connector =
-        manifest.connector.kind === 'mcp'
-          ? createMcpConnector({
-              endpoint: manifest.connector.endpoint,
-              ...(manifest.connector.headers ? { headers: manifest.connector.headers } : {}),
-              accessToken: () =>
-                bearerTokenAsStored(manifest, connectionId, runtime.credentials),
-            })
-          : runtime.connectorFor(providerId, connectionId);
-
-      if (connector) {
-        // Discovery takes the manifest and nothing else. What a provider exposes
-        // is a property of the provider, not of an account — which is just as
-        // well, because the connection being created does not exist in config
-        // until step 4 below.
-        discovered = await connector.discover({ manifest });
-
-        await runtime.state.kv.set('discovery', providerId, JSON.stringify(discovered));
-        registry.setDiscovered(providerId, discovered);
-      }
-    } else if (entry.definition) {
-      // Local capabilities carry their bundle from the manifest. Resources are
-      // included alongside tools: they need a policy grant too, and leaving
-      // them out would register a resource nothing is allowed to read.
-      const bundleOf = (name: string): string | undefined =>
-        manifest.bundles?.find((candidate) => candidate.capabilities.includes(name))?.name;
-
-      discovered = entry.definition.capabilities.map((capability) => ({
-        name: capability.name,
-        description: capability.description,
-        inputSchema: {},
-        ...(bundleOf(capability.name) ? { bundle: bundleOf(capability.name)! } : {}),
-      }));
-    }
+    // 3. Ask the upstream what it exposes.
+    const discovered = await discoverCapabilities({
+      entry,
+      manifest,
+      connectionId,
+      credentials: runtime.credentials,
+      connectorFor: runtime.connectorFor.bind(runtime),
+      remember: async (found) => {
+        await runtime.state.kv.set('discovery', providerId, JSON.stringify(found));
+        registry.setDiscovered(providerId, found);
+      },
+    });
 
     // 4. Declare the connection, or update the one this account already has.
     const existingIndex = runtime.config.connections.findIndex(
@@ -323,7 +315,11 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
         document.setIn(['connections', existingIndex, 'account'], account);
         changes.push(`connections.${connectionKey}.account = ${account}`);
       }
-      changes.push(`re-authorised ${connectionKey}`);
+      // Named where the provider offered a choice, because this is the line an
+      // operator reads to see that a re-connect swapped the route rather than
+      // refreshed it — and `--auth` reaches here having asked nothing. Unnamed
+      // for a provider with one way in, whose output is unchanged.
+      changes.push(`re-authorised ${connectionKey}${method.id ? ` with ${method.id}` : ''}`);
     }
 
     // 5. Grant it.
@@ -369,6 +365,7 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
         ok: true,
         key: connectionKey,
         account,
+        ...where(runtime),
         discovered: discovered.length,
         next: ALREADY,
       };
@@ -384,6 +381,7 @@ async function runConnect(target: string, options: ConnectOptions): Promise<Conn
       ok: true,
       key: connectionKey,
       account,
+      ...where(runtime),
       changes,
       granted,
       ...(notes.length > 0 ? { notes } : {}),

package/src/cli/commands/connect/method.ts

@@ -0,0 +1,237 @@
+import { hasOwnClientPath, type AuthAssertion, type ProviderManifest } from '#connectivity';
+import { progress, style } from '../../output.ts';
+import { terminalPrompter, type Prompter } from '../../prompt.ts';
+
+/**
+ * Which way in, where a provider offers more than one.
+ *
+ * Two questions that used to be asked in two different places and are one
+ * question to the person answering: what kind of credential, and — for the
+ * browser — whose OAuth client. The second was a flag, `--own-client`, which is
+ * to say it was a choice nobody discovered unless they already knew it existed.
+ *
+ * Most providers offer exactly one route and this file is inert for them:
+ * `options` returns a single entry, nothing is printed, and nothing is asked.
+ * That is the property worth protecting — adding routes to Google must not put
+ * a question, or a warning, in front of somebody connecting GitHub.
+ */
+
+export type ChosenMethod =
+  | {
+      readonly kind: 'assertion';
+      /** How `--auth` spells this route, for reporting what the connection became. */
+      readonly id: string;
+      readonly assertion: AuthAssertion;
+    }
+  /**
+   * The browser, and which client the exchange runs through.
+   *
+   * `undefined` means "whatever this profile already decided", which is the
+   * precedence `resolveOAuthClient` has always applied: a declared `oauth_apps`
+   * entry wins, otherwise the broker. It is what a provider with only one
+   * browser route resolves to, so nothing about those changes.
+   *
+   * `id` is unset for exactly those synthesised cases — `--auth oauth`,
+   * `--own-client`, and a provider with one route — because there was no choice
+   * to report. A provider that never offered two reads as it always did.
+   */
+  | { readonly kind: 'oauth'; readonly id?: string; readonly client: 'own' | 'hosted' | undefined }
+  /**
+   * A credential the operator already holds, for a provider that does OAuth.
+   *
+   * Offered where an OAuth manifest still declares a per-connection prompt,
+   * which is a thing to be only where the browser route can be closed by
+   * somebody who is not in the room: a Slack workspace on Enterprise Grid needs
+   * an admin to approve an app before it can authenticate anyone, and the
+   * person running `connect` may not be that admin.
+   */
+  | { readonly kind: 'pasted'; readonly id?: string };
+
+interface Option {
+  /** What `--auth` accepts, and how a chosen route is named back. */
+  readonly id: string;
+  readonly label: string;
+  readonly detail: string;
+  readonly chosen: ChosenMethod;
+}
+
+
+/**
+ * Every route this provider actually has, in the order they are offered.
+ *
+ * The key first, because it is the one that removes a recurring chore and the
+ * one nobody would guess at. Then the hosted client, which is the default and
+ * the thing "as it works today" means. Then a client of your own, which is
+ * twenty minutes in a console and is what an organisation forbidding
+ * third-party clients needs.
+ */
+export function options(manifest: ProviderManifest): readonly Option[] {
+  if (manifest.auth.kind !== 'oauth') return [];
+
+  const { assertion, broker } = manifest.auth;
+  const found: Option[] = [];
+
+  if (assertion) {
+    found.push({
+      id: assertion.method,
+      label: assertion.label,
+      detail: assertion.reach,
+      chosen: { kind: 'assertion', id: assertion.method, assertion },
+    });
+  }
+
+  if (broker) {
+    found.push({
+      id: 'hosted_client',
+      label: `Sign in through a browser, using the OAuth client ${broker.operator} operates`,
+      detail:
+        'nothing to register and no client secret on this machine. The exchange is performed by ' +
+        `${broker.operator}, and the connection is re-authorised whenever its token expires.`,
+      chosen: { kind: 'oauth', id: 'hosted_client', client: 'hosted' },
+    });
+  }
+
+  if (!broker || hasOwnClientPath(manifest)) {
+    found.push({
+      id: 'own_client',
+      label: 'Sign in through a browser, using an OAuth client you register',
+      detail: broker
+        ? 'a console walkthrough once per profile, after which nothing leaves this machine but ' +
+          'the browser. What an organisation that forbids third-party clients needs.'
+        : 'the whole account, and the connection is re-authorised whenever its token expires.',
+      // Undefined `client` rather than 'own' where it is the only browser route:
+      // there is nothing to override, and forcing it would write an `oauth_apps`
+      // entry for a provider whose manifest already says it is the only way.
+      chosen: { kind: 'oauth', id: 'own_client', client: broker ? 'own' : undefined },
+    });
+  }
+
+  // Last, always. It is the way in when the others are refused, not one anyone
+  // should be reaching for first: what it stores is the credential itself
+  // rather than a means of obtaining one, so rotating it is manual, and nothing
+  // can show what it is allowed to do.
+  const pasted = (manifest.setup?.prompts ?? []).filter((prompt) => prompt.scope === 'connection');
+  if (pasted.length > 0) {
+    found.push({
+      id: 'pasted_token',
+      label: `Paste a ${pasted.map((prompt) => prompt.label).join(', then ')} you already hold`,
+      detail:
+        'no browser, for a workspace that has not approved this app — which an admin decides, ' +
+        'not you. The credential is stored as given, so rotating it is manual and nothing can ' +
+        'say what it is allowed to do.',
+      chosen: { kind: 'pasted', id: 'pasted_token' },
+    });
+  }
+
+  return found;
+}
+
+/** What `--auth` will accept for this provider, for a message that lists them. */
+export function methodsFor(manifest: ProviderManifest): readonly string[] {
+  return options(manifest).map((option) => option.id);
+}
+
+/**
+ * Choose, from the flag or from the operator — and from nothing else.
+ *
+ * Nothing is inferred from what this account authenticates with today, which is
+ * a decision rather than an omission. A connection authenticates one way at a
+ * time: whichever route this run picks replaces the credential the account has
+ * now, and re-running `connect` is how somebody switches. Defaulting to the
+ * stored route would mean reading a credential to answer a question that is the
+ * operator's on every run, and would hide the replacement behind a default that
+ * reads as a no-op.
+ *
+ * It used to try. The route was read from the *provisional* connection id,
+ * which is `pending` until identity is settled — so it found nothing every
+ * time, fell back to the browser, and performed the silent swap it existed to
+ * prevent on anyone who pressed Enter. Saying what the choice does is the part
+ * that was actually missing.
+ */
+export async function chooseAuthMethod(input: {
+  readonly manifest: ProviderManifest;
+  /** `--auth <method>`, if it was given. */
+  readonly requested: string | undefined;
+  /** `--own-client`, which is the older spelling of one of these. */
+  readonly ownClient?: boolean;
+  readonly prompter?: Prompter;
+}): Promise<ChosenMethod> {
+  const { manifest, requested } = input;
+  const prompter = input.prompter ?? terminalPrompter;
+  const available = options(manifest);
+
+  if (requested !== undefined) {
+    // `oauth` is not an option id. It is the older, coarser spelling — "the
+    // browser, however this profile already resolves it" — and dropping it
+    // would break a scripted `--auth oauth` for no gain.
+    if (requested === 'oauth') return { kind: 'oauth', client: undefined };
+
+    const picked = available.find((option) => option.id === requested);
+    if (picked) return picked.chosen;
+
+    throw new Error(
+      `${manifest.name} cannot authenticate with "${requested}". ` +
+        `--auth accepts: ${['oauth', ...methodsFor(manifest)].join(', ')}.`,
+    );
+  }
+
+  if (input.ownClient === true) return { kind: 'oauth', client: 'own' };
+
+  // One route, or none this file knows about: decide nothing and say nothing.
+  if (available.length < 2) return { kind: 'oauth', client: undefined };
+
+  // Nobody to ask. The flag above is the non-interactive answer, deliberately —
+  // guessing picks which credential gets overwritten (ADR-038).
+  if (!prompter.interactive) return { kind: 'oauth', client: undefined };
+
+  return ask(manifest, available, prompter);
+}
+
+async function ask(
+  manifest: ProviderManifest,
+  available: readonly Option[],
+  prompter: Prompter,
+): Promise<ChosenMethod> {
+  // "As it works today" for anyone who has not chosen otherwise: the hosted
+  // client where there is one, and otherwise the browser. Never the key — it is
+  // listed first because it is the one worth knowing about, and defaulting to
+  // the first entry would make Enter mean "the route with a console visit in
+  // it" for someone who was not reading.
+  const hosted = available.findIndex((option) => option.id === 'hosted_client');
+  const fallback =
+    hosted !== -1 ? hosted : Math.max(available.findIndex((option) => option.chosen.kind === 'oauth'), 0);
+  const preferred = String(fallback + 1);
+
+  progress();
+  progress(style.bold(`${manifest.name} can authenticate ${count(available.length)} ways`));
+  progress();
+  for (const [index, option] of available.entries()) {
+    progress(`  ${index + 1}. ${option.label}`);
+    progress(style.dim(`     ${option.detail}`));
+  }
+  progress();
+  // Printed whether or not this account is already connected, because it is a
+  // statement about what the command does rather than a reading of what is
+  // stored — and on a first connect it is true with nothing to replace.
+  progress(style.dim('  Whichever you pick becomes the only way in for this account. It replaces'));
+  progress(
+    style.dim('  whatever is stored for it now — a connection authenticates one way at a time.'),
+  );
+  progress();
+
+  const answer = await prompter.ask(`  Which ${style.dim(`[${preferred}]`)}`);
+  const picked = answer.length === 0 ? preferred : answer;
+
+  const byNumber = available[Number(picked) - 1];
+  if (/^\d+$/.test(picked) && byNumber) return byNumber.chosen;
+
+  const byName = available.find((option) => option.id === picked);
+  if (byName) return byName.chosen;
+
+  throw new Error(
+    `"${picked}" is not one of the choices. Answer 1 to ${available.length}.`,
+  );
+}
+
+const WORDS = ['no', 'one', 'two', 'three', 'four', 'five'];
+const count = (total: number): string => WORDS[total] ?? String(total);

package/src/cli/commands/connect/outcome.ts

@@ -17,6 +17,10 @@ export interface ConnectOutcome {
   readonly ok: boolean;
   readonly key?: string;
   readonly account?: string;
+  /** The profile written to, for a caller that cannot see the announce line. */
+  readonly profile?: string;
+  /** The target written to — which credential store now holds this account. */
+  readonly target?: string;
   readonly changes: readonly string[];
   readonly granted: readonly string[];
   /**
@@ -45,6 +49,35 @@ export const NOTHING = { changes: [], granted: [], discovered: 0 } as const;
 
 export const ALREADY = 'Already connected — nothing changed.';
 
+/**
+ * One result for an account that turned out to be several services.
+ *
+ * The whole account succeeded only if every service did. A partial result is the
+ * case worth surfacing: one member blocked on a value leaves an account half
+ * connected, which `status` shows and prose does not.
+ */
+export function familyOutcome(members: readonly ConnectOutcome[]): ConnectOutcome {
+  const blocked = members.find((outcome) => !outcome.ok);
+
+  return {
+    ...NOTHING,
+    ok: members.every((outcome) => outcome.ok),
+    members,
+    ...(blocked?.reason ? { reason: blocked.reason } : {}),
+  };
+}
+
+/**
+ * Which store an account landed in, for the caller not reading the terminal.
+ *
+ * `announceConnectTarget` fixes the human channel. A `--json` caller had the
+ * same blindness the operator did — and an agent is exactly the reader who
+ * cannot see the line printed above it.
+ */
+export function where(runtime: { resolution: { profile: string; target: string } }) {
+  return { profile: runtime.resolution.profile, target: runtime.resolution.target };
+}
+
 /**
  * What `connect` says last.
  *
@@ -101,7 +134,15 @@ export function renderOutcome(outcome: ConnectOutcome): void {
  */
 function renderBlocked(outcome: ConnectOutcome): void {
   progress();
-  print(fail(outcome.reason === 'needs_browser' ? 'a browser is needed' : 'more is needed first'));
+  print(
+    fail(
+      outcome.reason === 'needs_browser'
+        ? 'a browser is needed'
+        : outcome.reason === 'needs_terminal'
+          ? 'a terminal is needed'
+          : 'more is needed first',
+    ),
+  );
 
   for (const line of (outcome.message ?? '').split('\n')) print(`      ${line}`);