@lanes-sh/link 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "A self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

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

@@ -49,6 +49,7 @@ export interface ConnectCustomOptions extends GlobalFlags, CustomFlags {
   /** Forwarded to `connect` untouched. */
   readonly id?: string | undefined;
   readonly displayName?: string | undefined;
+  readonly label?: string | undefined;
   readonly replace?: boolean | undefined;
   readonly nonInteractive?: boolean | undefined;
   readonly acceptBroadScopes?: boolean | undefined;
@@ -170,6 +171,7 @@ export async function connectCustom(
       quiet: options.quiet ?? false,
       ...(options.id ? { id: options.id } : {}),
       ...(options.displayName ? { displayName: options.displayName } : {}),
+      ...(options.label ? { label: options.label } : {}),
       ...(options.replace ? { replace: options.replace } : {}),
       ...(options.nonInteractive ? { nonInteractive: options.nonInteractive } : {}),
       ...(options.acceptBroadScopes ? { acceptBroadScopes: options.acceptBroadScopes } : {}),

package/src/cli/commands/connect/custom/spec.ts

@@ -227,6 +227,7 @@ export const CONNECT_CUSTOM_FLAGS: readonly string[] = [
   // and a broker's, and a synthesized manifest never declares a broker.
   'id',
   'display-name',
+  'label',
   'replace',
   'non-interactive',
   'accept-broad-scopes',

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

@@ -0,0 +1,76 @@
+import type { ConnectionConfig } from '#profile';
+import type { ConfigDocument } from '../../config-edit.ts';
+
+/**
+ * Writing the connection row — the one edit `connect` makes to the profile.
+ *
+ * Its own file because it answers its own question: given an account, an id and
+ * a name, which lines of YAML change? The five numbered steps around it are
+ * about vendors, browsers and credential stores, and none of that reaches here.
+ *
+ * Two fields, and the difference between them is the whole subject. `account` is
+ * an identity the provider reported, and three things read it as one — the
+ * reconnect match in `settleIdentity`, the id derived from it, and the `From`
+ * header `gmail.send_message` writes. `label` is what the operator calls the
+ * same row, addressed by nothing and displayed everywhere.
+ */
+export function declareConnection(input: {
+  readonly document: ConfigDocument;
+  /** The profile as it stands, which says whether this is an add or a repair. */
+  readonly connections: readonly ConnectionConfig[];
+  readonly providerId: string;
+  readonly connectionId: string;
+  readonly account: string;
+  readonly label: string;
+  /** Which route in, where the provider offered a choice. */
+  readonly method: string | undefined;
+}): readonly string[] {
+  const { document, connections, providerId, connectionId, account, label, method } = input;
+
+  const key = `${providerId}.${connectionId}`;
+  const index = connections.findIndex((c) => `${c.provider}.${c.id}` === key);
+  const changes: string[] = [];
+
+  if (index === -1) {
+    // No `credential_ref`: it derives to `<provider>/<id>`, which is exactly
+    // where the OAuth provider already looks. Writing it would add a line per
+    // connection that can only ever agree or be a bug.
+    //
+    // No `label` either, when it is the account. Pressing Enter at the prompt is
+    // the common answer, and a line repeating the address above it is a line to
+    // read past forever.
+    document.addTo(['connections'], {
+      id: connectionId,
+      provider: providerId,
+      account,
+      ...(label === account ? {} : { label }),
+    });
+    changes.push(`connections += ${key} (${account})`);
+    return changes;
+  }
+
+  // A reconnect. The credential was just replaced; the declaration stays as it
+  // is, so re-running connect after an expiry is a no-op on the file rather than
+  // a second row.
+  const declared = connections[index];
+
+  if (declared?.account !== account) {
+    document.setIn(['connections', index, 'account'], account);
+    changes.push(`connections.${key}.account = ${account}`);
+  }
+
+  // Compared against what the row is *called*, which is the account until
+  // somebody names it otherwise. Without the fallback, every reconnect of an
+  // unlabelled connection writes a label that says what the line above it says.
+  if ((declared?.label ?? declared?.account) !== label) {
+    document.setIn(['connections', index, 'label'], label);
+    changes.push(`connections.${key}.label = ${label}`);
+  }
+
+  // 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 ${key}${method ? ` with ${method}` : ''}`);
+  return changes;
+}

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

@@ -48,8 +48,13 @@ export function familyMembers(registry: ProviderRegistry, name: string): readonl
  * the target belongs to the account, not to each service under it, so it is
  * printed once here and suppressed in every member. Three copies of it is three
  * times nothing new.
+ *
+ * The label travels on the same argument: it too belongs to the account, so the
+ * first member asks what to call it and the rest are told.
  */
-export async function connectFamily<Options extends { readonly id?: string | undefined }>(input: {
+export async function connectFamily<
+  Options extends { readonly id?: string | undefined; readonly label?: string | undefined },
+>(input: {
   readonly name: string;
   readonly members: readonly string[];
   readonly options: Options;
@@ -64,9 +69,20 @@ export async function connectFamily<Options extends { readonly id?: string | und
 
   progress(style.dim(familyNote(name, members)));
 
-  const inherited = { ...options, id: options.id ?? namedId };
+  let inherited = { ...options, id: options.id ?? namedId };
   const outcomes: ConnectOutcome[] = [];
-  for (const member of members) outcomes.push(await connect(member, inherited, true));
+
+  for (const member of members) {
+    const outcome = await connect(member, inherited, true);
+    outcomes.push(outcome);
+
+    // One account, one name. Without this, connecting iCloud asks what to call
+    // it three times — and three different answers is three rows that read as
+    // three accounts.
+    if (inherited.label === undefined && outcome.label !== undefined) {
+      inherited = { ...inherited, label: outcome.label };
+    }
+  }
 
   return familyOutcome(outcomes);
 }

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

@@ -6,6 +6,7 @@ import { nonInteractivePrompter, terminalPrompter, type Prompter } from '../../p
 import { openRuntime, type GlobalFlags } from '../../runtime.ts';
 import { moveCredential, siblingAccountId } from './accounts.ts';
 import { grantProvider } from './grant.ts';
+import { declareConnection } from './declare.ts';
 import { discoverCapabilities } from './discover.ts';
 import { connectFamily, familyMembers } from './family.ts';
 import { authoriseWithKey } from './assertion.ts';
@@ -38,6 +39,14 @@ import { unknownProvider } from './unknown.ts';
 export interface ConnectOptions extends GlobalFlags {
   readonly id?: string | undefined;
   readonly displayName?: string | undefined;
+  /**
+   * `--label`: what to call this connection, instead of being asked.
+   *
+   * Distinct from `--display-name`, which answers *whose account this is* for a
+   * provider that cannot report it. This one never touches the identity, so it
+   * is safe to pass anything a person would say out loud.
+   */
+  readonly label?: string | undefined;
   /** Ask for the stored credential again — a key rotated, or a password revoked. */
   readonly replace?: boolean | undefined;
   /**
@@ -272,11 +281,12 @@ export async function runConnect(
     //    adding a new one. Without it, a retried connect appends a second row
     //    rather than repairing the first — which is how `main2` and `main3`
     //    ended up in a config describing two mailboxes.
-    const { connectionId, account } = await settleIdentity({
+    const { connectionId, account, label } = await settleIdentity({
       manifest,
       provisionalId,
       explicitId: named,
       account: options.displayName,
+      label: options.label,
       runtime,
       prompter,
     });
@@ -306,31 +316,18 @@ export async function runConnect(
     });
 
     // 4. Declare the connection, or update the one this account already has.
-    const existingIndex = runtime.config.connections.findIndex(
-      (c) => `${c.provider}.${c.id}` === connectionKey,
+    changes.push(
+      ...declareConnection({
+        document,
+        connections: runtime.config.connections,
+        providerId,
+        connectionId,
+        account,
+        label,
+        method: method.id,
+      }),
     );
 
-    if (existingIndex === -1) {
-      // No `credential_ref`: it derives to `<provider>/<id>`, which is exactly
-      // where the OAuth provider already looks. Writing it would add a line per
-      // connection that can only ever agree or be a bug.
-      document.addTo(['connections'], { id: connectionId, provider: providerId, account });
-      changes.push(`connections += ${connectionKey} (${account})`);
-    } else {
-      // A reconnect. The credential was just replaced above; the declaration
-      // stays as it is, so re-running connect after an expiry is a no-op on the
-      // file rather than a second row.
-      if (runtime.config.connections[existingIndex]?.account !== account) {
-        document.setIn(['connections', existingIndex, 'account'], account);
-        changes.push(`connections.${connectionKey}.account = ${account}`);
-      }
-      // 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 — one rule per provider; `grant.ts` says why not per capability.
     const granted = grantProvider(document, runtime.config.policy.allow, providerId);
 
@@ -365,6 +362,7 @@ export async function runConnect(
         ok: true,
         key: connectionKey,
         account,
+        label,
         ...where(runtime),
         discovered: discovered.length,
         next: ALREADY,
@@ -381,6 +379,7 @@ export async function runConnect(
       ok: true,
       key: connectionKey,
       account,
+      label,
       ...where(runtime),
       changes,
       granted,

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

@@ -17,6 +17,14 @@ export interface ConnectOutcome {
   readonly ok: boolean;
   readonly key?: string;
   readonly account?: string;
+  /**
+   * What the connection is called, where that is not just the account.
+   *
+   * Reported so the family path can carry it: `connect icloud` is three runs on
+   * one account, and the name belongs to the account rather than to each
+   * service under it.
+   */
+  readonly label?: 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. */

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

@@ -5,7 +5,7 @@ import type { Config } from '#profile';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { idFromAccount, resolveAccount } from '../../identity.ts';
 import { style } from '../../output.ts';
-import { terminalPrompter, type Prompter } from '../../prompt.ts';
+import { PromptCancelled, terminalPrompter, type Prompter } from '../../prompt.ts';
 import { accountSiblings } from './accounts.ts';
 
 /**
@@ -16,12 +16,26 @@ import { accountSiblings } from './accounts.ts';
  * connection already holds that account, we reuse *its* id, which is what turns
  * a re-run of `connect` into a repair rather than a duplicate. Only when
  * identity cannot be resolved at all do we ask.
+ *
+ * The *label* is settled last and separately, because it is the one thing here
+ * the provider cannot answer. `account` is load-bearing three times over — the
+ * reconnect match above, the id derived from it, and the `From` header
+ * `gmail.send_message` writes — so the operator's own words for a connection
+ * cannot be put there, and `label` is where they go instead.
  */
 export async function settleIdentity(input: {
   manifest: ProviderManifest;
   provisionalId: string;
   explicitId: string | undefined;
   account: string | undefined;
+  /**
+   * The label, where the caller already has one.
+   *
+   * `--label`, and the family path: `connect icloud` is three `connect` runs on
+   * one account, and asking what to call it once per service is asking the same
+   * question three times.
+   */
+  label?: string | undefined;
   runtime: {
     config: Config;
     credentials: SecretStore;
@@ -30,7 +44,7 @@ export async function settleIdentity(input: {
     authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
   };
   prompter?: Prompter;
-}): Promise<{ connectionId: string; account: string }> {
+}): Promise<{ connectionId: string; account: string; label: string }> {
   const { manifest, provisionalId, explicitId, runtime } = input;
   const prompter = input.prompter ?? terminalPrompter;
 
@@ -112,6 +126,11 @@ export async function settleIdentity(input: {
   const unaccounted = !account && manifest.auth.kind === 'none';
   if (unaccounted) account = manifest.name;
 
+  // Whether the name we hold is one the operator has just typed, rather than one
+  // a provider reported. It settles the label below: a name someone chose a
+  // second ago does not need confirming against itself.
+  let typed = false;
+
   if (!account) {
     // Nothing to go on. Asking beats inventing `main2`, and the answer is the
     // one piece of information the file cannot reconstruct later — which is
@@ -125,32 +144,85 @@ export async function settleIdentity(input: {
     }
 
     account =
-      (await prompter.ask(`Which account is this? ${style.dim('(label for this connection)')}`)) ||
+      (await prompter.ask(`Which account is this? ${style.dim('(the address or handle)')}`)) ||
       `${manifest.name} ${provisionalId}`;
+    typed = true;
   }
 
-  if (explicitId) return { connectionId: explicitId, account };
+  const taken = siblings.map((candidate) => candidate.id);
 
-  if (unaccounted) {
-    return {
-      connectionId: idFromAccount(
-        'main',
-        siblings.map((candidate) => candidate.id),
-      ),
-      account: account!,
-    };
-  }
-
-  const already = siblings.find(
-    (candidate) => candidate.account.toLowerCase() === account.toLowerCase(),
-  );
-  if (already) return { connectionId: already.id, account };
+  const connectionId =
+    explicitId ??
+    (unaccounted
+      ? idFromAccount('main', taken)
+      : (siblings.find(
+          (candidate) => candidate.account.toLowerCase() === account!.toLowerCase(),
+        )?.id ?? idFromAccount(account, taken)));
 
   return {
-    connectionId: idFromAccount(
-      account,
-      siblings.map((candidate) => candidate.id),
-    ),
+    connectionId,
     account,
+    label: await settleLabel({
+      given: input.label,
+      // What the row this is about to land on is already called. Looked up
+      // across the whole vendor account rather than this provider alone, for the
+      // reason `accountSiblings` exists: `connect icloud_calendar` adopts iCloud
+      // Mail's id, and should adopt the name that goes with it too.
+      declared: siblings.find((candidate) => candidate.id === connectionId)?.label,
+      account,
+      typed,
+      prompter,
+    }),
   };
 }
+
+/**
+ * What to call this connection, offering what it is already called.
+ *
+ * Asked on every interactive connect, not only where identity resolution failed.
+ * That was the old behaviour and it had the case exactly backwards: the run that
+ * could not name the account is the run where the operator has least to add,
+ * and the run that resolved `ada@example.com` — where they may well want "Work
+ * mail" — never asked at all.
+ *
+ * The suggestion is in the question and an empty answer takes it, so the cost of
+ * always asking is one keystroke. Nothing addresses a connection by its label,
+ * so there is no answer here that can break anything.
+ */
+async function settleLabel(input: {
+  given: string | undefined;
+  declared: string | undefined;
+  account: string;
+  typed: boolean;
+  prompter: Prompter;
+}): Promise<string> {
+  const { given, declared, account, typed, prompter } = input;
+
+  if (given) return given;
+
+  // A label already chosen wins over the account, so re-authorising an expired
+  // credential does not quietly undo the operator's own word for the row.
+  const suggestion = declared ?? account;
+
+  if (typed || !prompter.interactive) return suggestion;
+
+  try {
+    return (
+      (await prompter.ask(`What should this be called? ${style.dim(`[${suggestion}]`)}`)) ||
+      suggestion
+    );
+  } catch (refusal) {
+    // Ctrl-C is an answer: the operator stopped the command, and swallowing it
+    // here would finish a connect they interrupted.
+    if (refusal instanceof PromptCancelled) throw refusal;
+
+    // Anything else is `terminalPrompter` discovering there is no terminal —
+    // it reports itself interactive and finds out only when asked, so a piped
+    // `lanes link connect gmail` reaches this line having already opened a
+    // browser and stored a credential. Failing there for want of a display name
+    // would undo none of that. A label is worth having and never worth failing
+    // a connect over; the account above it is the identity, and that one still
+    // refuses rather than inventing a name.
+    return suggestion;
+  }
+}

package/src/cli/commands/connection.ts

@@ -297,9 +297,18 @@ export async function disconnect(key: string | undefined, flags: DisconnectFlags
   })
 }
 
+/**
+ * Rename a connection, writing `label` and never `account`.
+ *
+ * It wrote `account` until it was noticed that `account` is not a display name:
+ * `settleIdentity` matches on it to tell a repair from a new account,
+ * `idFromAccount` derives the id from it, and `gmail.send_message` writes it
+ * into a `From` header. Renaming through it therefore un-recognised the account
+ * it renamed — the next `connect` added a second row beside it.
+ */
 export async function renameConnection(
   key: string,
-  account: string,
+  label: string,
   flags: RelabelFlags,
 ): Promise<{ resolution: Resolution; relabelled: Relabelled }> {
   const runtime = await openRuntime(flags);
@@ -309,7 +318,7 @@ export async function renameConnection(
     const located = locate(config, key, resolution.profile);
     const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
 
-    document.setIn(['connections', located.index, 'account'], account);
+    document.setIn(['connections', located.index, 'label'], label);
     await document.save();
 
     return {
@@ -318,8 +327,10 @@ export async function renameConnection(
         profile: resolution.profile,
         target,
         key,
-        from: located.connection.account,
-        to: account,
+        // What it was called a moment ago, which is the account only until the
+        // first rename.
+        from: located.connection.label ?? located.connection.account,
+        to: label,
         published: nextAfterEdit(await publishProfileEdit({ resolution, config, target })),
       },
     };
@@ -330,13 +341,13 @@ export async function renameConnection(
 
 export async function relabel(
   key: string | undefined,
-  account: string | undefined,
+  label: string | undefined,
   flags: RelabelFlags,
 ): Promise<void> {
   if (!key) throw new Error('Which connection? Run: lanes link status');
-  if (!account) throw new Error(`What should ${key} be called? Run: lanes link relabel ${key} "New name"`);
+  if (!label) throw new Error(`What should ${key} be called? Run: lanes link relabel ${key} "New name"`);
 
-  const { resolution, relabelled: result } = await renameConnection(key, account, flags);
+  const { resolution, relabelled: result } = await renameConnection(key, label, flags);
 
   return emit(flags.json, result, () => {
     announce(resolution);

package/src/cli/commands/operate/status.ts

@@ -46,6 +46,9 @@ export async function status(flags: StatusFlags): Promise<void> {
         provider: connection.provider,
         id: connection.id,
         account: connection.account,
+        // Null rather than absent: a caller reading this to prefill a rename box
+        // needs to tell "called nothing in particular" from a field it forgot.
+        label: connection.label ?? null,
         state: byKey.get(key)?.status ?? 'not reconciled',
       };
     });
@@ -102,7 +105,14 @@ export async function status(flags: StatusFlags): Promise<void> {
               connection.state === 'active'
                 ? style.green(connection.state)
                 : style.yellow(connection.state),
-              style.dim(connection.account),
+              // Both, where they differ. The label is what the operator called
+              // it and the account is which mailbox it is; a row answering only
+              // one of those is the row this column already was.
+              style.dim(
+                connection.label && connection.label !== connection.account
+                  ? `${connection.label} — ${connection.account}`
+                  : connection.account,
+              ),
             ]),
           );
         }

package/src/cli/commands/update.ts

@@ -1,6 +1,7 @@
 import { homedir } from 'node:os';
 import { join, sep } from 'node:path';
-import { installRoot } from '#profile';
+import { installRoot, resolveWorkspaceRoot } from '#profile';
+import { repairOwnerLayer } from '../config-repair.ts';
 import { emit, fail, ok, print, printErr, progress, style, warn } from '../output.ts';
 import { PACKAGE, release, type ReleaseState } from '../release.ts';
 import { version } from '../version.ts';
@@ -152,6 +153,27 @@ export async function update(flags: UpdateFlags): Promise<void> {
   // was down would make this the flakiest check in it.
   if (flags.check === true && decision.action === 'install') process.exitCode = 1;
 
+  // Whatever the registry said, and before the branch that returns early.
+  //
+  // `start`, `connect` and `deploy` already repair a profile that is missing
+  // part of the owner layer, and for months that was enough. It is not: a
+  // release that adds a surface — `tasks` and `assets` in 0.5.0 — leaves every
+  // existing profile without it until one of those three next runs, and someone
+  // who serves their endpoint from elsewhere may run none of them for weeks. The
+  // page they look at meanwhile offers to *add* what they already have,
+  // which is where this was reported from.
+  //
+  // `update` is the command that means "bring me current", so it is the honest
+  // place for the other half of current. Not on `--check`, which is a question
+  // and must not write, and not conditional on an install having happened: the
+  // profile of someone already on the latest version is exactly the one this was
+  // reported against.
+  if (flags.check !== true) {
+    await repairOwnerLayer(resolveWorkspaceRoot(), undefined, {
+      ...(flags.json === true ? { report: progress } : {}),
+    });
+  }
+
   const report = {
     installed: current.installed,
     latest: current.latest,

package/src/cli/config-repair.ts

@@ -261,7 +261,14 @@ export function ensureIdentityConnection(document: ConfigDocument): SurfaceRepai
 export async function repairOwnerLayer(
   workspaceRoot: string,
   profiles: readonly string[] | undefined,
+  options: { report?: (line: string) => void } = {},
 ): Promise<void> {
+  // stdout by default, because every caller but one is printing a report a
+  // person reads. `update --json` passes `progress` instead: what it produces is
+  // a document, and a line of prose in front of it corrupts whatever is parsing.
+  // Routed rather than silenced — nothing else here widens a policy without
+  // saying so, and this must not be the exception.
+  const say = options.report ?? print;
   const wanted = profiles === undefined ? undefined : new Set(profiles);
 
   for (const name of await listProfiles(workspaceRoot)) {
@@ -274,13 +281,13 @@ export async function repairOwnerLayer(
 
       await document.save();
 
-      print(ok(`gave ${style.bold(name)} its own owner layer`));
-      for (const change of repairLines(repair)) print(`      ${style.dim(change)}`);
-      print(
+      say(ok(`gave ${style.bold(name)} its own owner layer`));
+      for (const change of repairLines(repair)) say(`      ${style.dim(change)}`);
+      say(
         `      ${style.dim('memory, tasks, assets, skills, vault and setup — your own material, no account behind any of them')}`,
       );
     } catch (error) {
-      print(
+      say(
         warn(
           `could not give ${name} its owner layer: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`,
         ),

package/src/cli/dashboard-page.ts

@@ -30,6 +30,8 @@ export interface DashboardConnection {
   readonly key: string;
   readonly provider: string;
   readonly account: string;
+  /** What the operator calls it, where that is not just the account. */
+  readonly label?: string | undefined;
   /** `active`, `unauthorized`, `disabled`, or `not reconciled`. */
   readonly state: string;
 }
@@ -155,7 +157,14 @@ function connectionsSection(view: DashboardView): string {
         mark(connection.provider) +
         `<code class="key">${escapeHtml(connection.key)}</code>` +
         statusPill(connection.state) +
-        `<span class="account">${escapeHtml(connection.account)}</span>` +
+        // The label reads, the account hovers: the row is one line wide and the
+        // address is the longer of the two, so putting both in it wraps every
+        // row to make one of them legible.
+        `<span class="account"${
+          connection.label && connection.label !== connection.account
+            ? ` title="${escapeHtml(connection.account)}"`
+            : ''
+        }>${escapeHtml(connection.label ?? connection.account)}</span>` +
         repair +
         '</div>'
       );

package/src/cli/main.ts

@@ -88,6 +88,7 @@ export async function run(argv: readonly string[]): Promise<void> {
             ...customFlags(flags, argv),
             id: text(flags, 'id'),
             displayName: text(flags, 'display-name'),
+            label: text(flags, 'label'),
             replace: flags['replace'] === true,
             nonInteractive: flags['non-interactive'] === true,
             acceptBroadScopes: flags['accept-broad-scopes'] === true,
@@ -104,6 +105,7 @@ export async function run(argv: readonly string[]): Promise<void> {
             ...global,
             id: text(flags, 'id'),
             displayName: text(flags, 'display-name'),
+            label: text(flags, 'label'),
             replace: flags['replace'] === true,
             nonInteractive: flags['non-interactive'] === true,
             acceptBroadScopes: flags['accept-broad-scopes'] === true,

package/src/cli/runtime/open.ts

@@ -240,6 +240,7 @@ export async function openRuntime(
         key: `${connection.provider}.${connection.id}`,
         provider: connection.provider,
         account: connection.account,
+        ...(connection.label ? { label: connection.label } : {}),
       }));
 
   // Read before the registry is built, so a store that cannot be reached is a

package/src/cli/selection.ts

@@ -306,6 +306,7 @@ const ACCEPTS: Record<string, readonly string[]> = {
   connect: [
     'id',
     'display-name',
+    'label',
     'replace',
     'non-interactive',
     'accept-broad-scopes',

package/src/cli/usage.ts

@@ -154,6 +154,9 @@ ${style.bold('Other flags')}
   --json                         machine-readable output, where a command offers it
   --non-interactive              never prompt: connect refuses with what to store,
                                  deploy takes the answers its config already holds
+  --label <text>                 what to call a connection, instead of being asked at the
+                                 end of connect. A display name only: nothing addresses
+                                 a connection by it. Use relabel to change one later
   --accept-broad-scopes          agree in advance to scopes broader than a provider needs
   --own-client                   register your own OAuth client instead of using the
                                  one this project operates (connect only)

package/src/profile/schema.ts

@@ -303,11 +303,20 @@ export const policySchema = z.object({
  * is *whose mailbox is this*. `id` is the stable key that `credential_ref` and
  * the agent's `connection` argument point at, and it is derived from `account`
  * so it means something too.
+ *
+ * `label` is the operator's own word for the same row, and it exists because
+ * `account` cannot be. Three things read `account` as an identity — the
+ * reconnect match in `settleIdentity`, the id derived from it, and the `From`
+ * header `gmail.send_message` writes — so a `relabel` that wrote "Work mail"
+ * there stopped the next `connect` recognising the account it had renamed.
+ * Nothing addresses a connection by its label; it is only ever displayed.
  */
 export const connectionSchema = z.object({
   id: z.string().regex(/^[a-z0-9][a-z0-9_]*$/, 'must be lowercase alphanumeric with underscores'),
   provider: identifier,
   account: z.string().min(1),
+  /** Absent means the row is shown as its account, which is the usual case. */
+  label: z.string().min(1).optional(),
   credential_ref: credentialRef.optional(),
   /** Provider-specific, validated later against that provider's own schema. */
   config: z.record(z.string(), z.unknown()).optional(),

package/src/providers/setup/provider.ts

@@ -185,7 +185,7 @@ export function createSetupProvider(options: SetupProviderOptions): ProviderDefi
 
 function renderOverview(
   options: SetupProviderOptions,
-  connections: ReadonlyArray<{ key: string; account: string }>,
+  connections: ReadonlyArray<{ key: string; account: string; label?: string | undefined }>,
   plans: readonly ProviderPlan[],
   self: string,
 ): string {
@@ -196,7 +196,15 @@ function renderOverview(
   } else {
     lines.push('Connected and reachable:');
     for (const connection of connections) {
-      lines.push(`  ${connection.key}  — ${connection.account}`);
+      // Account first, label in brackets. The other way round for a person
+      // reading `status`, and deliberately not here: an agent choosing which
+      // connection to call needs the identity, and "Work mail" is not one.
+      lines.push(
+        `  ${connection.key}  — ${connection.account}` +
+          (connection.label && connection.label !== connection.account
+            ? ` (${connection.label})`
+            : ''),
+      );
     }
   }
 

package/src/server/dashboard.ts

@@ -179,6 +179,7 @@ export async function handleDashboard(
       key: `${connection.provider}.${connection.id}`,
       provider: connection.provider,
       account: connection.account,
+      ...(connection.label ? { label: connection.label } : {}),
       state: byKey.get(`${connection.provider}.${connection.id}`)?.status ?? 'not reconciled',
     }));