@lanes-sh/link 0.9.2 → 0.9.3

package/README.md

@@ -55,7 +55,7 @@ $ bun install -g @lanes-sh/link                # puts `lanes` on your PATH
 $ lanes auth login                             # opens a browser once
 $ lanes link profile add personal --workspace local
 $ lanes link profile members add --me --profile personal --workspace local
-$ lanes link start --profile personal --workspace local
+$ lanes link start --workspace local
 ok    serving http://127.0.0.1:7337/mcp
       profiles: personal
 ```
@@ -63,7 +63,7 @@ ok    serving http://127.0.0.1:7337/mcp
 Then, in another shell:
 
 ```console
-$ lanes link mcp add --profile personal --workspace local     # every agent installed; or name one: claude, codex
+$ lanes link mcp add --workspace local     # every agent installed; or name one: claude, codex
 ok    registered lanes-link with Claude Code (user scope)
 ok    registered lanes-link with Codex
 ```
@@ -75,8 +75,14 @@ Mail and calendar are the next step. **[Full quickstart →](https://lanes.sh/do
 **Why the sign-in.** A profile declares who may consume it, and there is nothing to check that
 against if the endpoint has no idea who is asking. That is a real dependency for a self-hostable
 tool and worth stating plainly; what it is not is a dependency per request. The network is needed
-to sign in and to refresh, and a machine offline for a day keeps serving. `lanes link token
-show` still mints a static token for CI, which has no browser to sign in with.
+to sign in and to refresh, and a machine offline for a day keeps serving.
+
+**Why `mcp add` names no profile.** One endpoint serves every profile in the workspace, and each
+call names one in its `profile` argument — so registering is about the endpoint, not a profile.
+Which profiles a client actually reaches is decided when its owner signs in: every profile whose
+`members:` lists them, and no others. A credential is an identity here, not a selection. For a
+runner with no browser, `lanes link token issue --me` mints a static token that reaches exactly
+what its subject is a member of.
 
 ## What you keep in it
 

package/instructions/skills/lanes-link/SKILL.md

@@ -346,9 +346,11 @@ changed, so a capability for a freshly connected account is not callable until
 the client reconnects. Say that, rather than reporting the connection as missing
 or asking them to connect again.
 
-One exception, and it is the one that matters here: the authenticator is built
-once at boot and is not re-read, so a `lanes link token rotate` does need the
-endpoint restarted before the new token opens anything.
+One exception used to be here — that a `token rotate` needed the endpoint
+restarted. It does not: the authenticator re-reads both the issued rows and
+their values on a seconds-long cache window, so `token issue`, `token rotate`
+and `token revoke` all take effect on a running endpoint. So does a change to a
+profile's `members:`, which is what decides where a token reaches.
 
 ## Operating the workspace
 
@@ -413,17 +415,35 @@ in the workspace and could be given it. Somebody with an unaccepted invitation
 has no subject yet, so they are listed, marked, and refused; the answer there is
 for them to accept, not for anyone to invent a subject.
 
-Removing somebody does not end a session they already hold: membership is read
-when a token is minted. Rotating the endpoint token closes that
-window now, and it names both flags: `lanes link token rotate --profile <name>
---workspace <name>`.
+Removing somebody does not end a browser session they already hold: membership
+is read when that token is minted. A **static** token is different — its
+membership is resolved on every call, so removing somebody takes effect within
+seconds for anything holding one.
 
-**A client is not given a token any more.** `lanes link mcp add` registers the
-bare URL, and the client discovers the endpoint, sends its owner to sign in, and
-comes back with a token of its own. The static token is for CI, which has no
-browser, and `--headless` is what writes it into a registration. If you are
-writing a registration command for somebody, do not add an `Authorization`
-header: it is no longer how a client connects.
+**A credential is an identity, not a selection.** Whether it arrived through a
+browser sign-in or is a static `llk_` token, it names a person, and what it
+reaches is every profile whose `members:` lists that person. There is nothing to
+scope at registration time and nothing to scope at deploy time; the member lists
+are the whole mechanism. `lanes link token show`, `rotate` and `revoke` refuse
+`--profile` outright rather than accept and ignore it.
+
+**A client is not given a token any more.** `lanes link mcp add --workspace
+<name>` registers the bare URL — no `--profile`, because one endpoint serves
+every profile and each call names one in its `profile` argument. The client
+discovers the endpoint, sends its owner to sign in, and comes back with a token
+of its own. If you are writing a registration command for somebody, do not add
+an `Authorization` header: it is no longer how a client connects.
+
+**For a runner with no browser**, issue one and say who it is for:
+
+```
+lanes link token issue --me --workspace <name>
+lanes link token list --workspace <name>
+```
+
+`--headless` on `mcp add` is what writes such a token into a registration. A
+workspace that has issued none is the ordinary healthy state, and `start` and
+`deploy` no longer mint or demand one.
 
 ## Deploying, and what it decides
 
@@ -437,14 +457,16 @@ resources that cost money, it implements no `--json` to inspect instead, and tha
 plan is the only place the consequences are visible while they are still
 avoidable.
 
-Two things it refuses to guess, and both are the owner's to answer:
+One thing it refuses to guess, and it is the owner's to answer:
 
-- **Whose bearer token opens the endpoint.** One token reaches every profile
-  behind that workspace, so this decides who gets in. With several candidates and
-  nothing recorded, it refuses and prints the command that names one.
 - **A first deploy.** A workspace that does not exist yet has nothing to derive
   a set from, so `--profile` is required there. It may be repeated, and the first
-  one named is the primary.
+  one named is the primary — which now decides only which profile's host and
+  port the endpoint binds, not who gets in.
+
+It used to refuse a second thing — *whose bearer token opens the endpoint* — and
+that question no longer has a subject. A token names a person and reaches what
+they are a member of, so there is no per-deploy choice of who gets in.
 
 **Never pass `--yes`, `--non-interactive`, `--access public` or
 `--service-account` yourself.** Each settles a question about who can reach their
@@ -474,45 +496,47 @@ existed in two copies that could disagree, and there is one copy now.
 
 ## Registering it, and re-registering it
 
-`lanes link mcp add --profile <name> --workspace <name>` runs each harness's own registration command and installs
-this skill where that harness keeps them. With no argument it does every harness
-installed; name one (`claude`, `codex`) to be specific. Run it again after
-`lanes link token rotate --profile <name> --workspace <name>` — add `--force`, since Claude Code stores the token as
-a value rather than a command.
+`lanes link mcp add --workspace <name>` runs each harness's own registration
+command and installs this skill where that harness keeps them. With no argument
+it does every harness installed; name one (`claude`, `codex`) to be specific.
 
-**Never paste the token.** There is a right way and a wrong way, and the
-difference matters:
+**It names no profile, and adding one changes nothing about who gets in.** One
+endpoint serves every profile in the workspace and each call names one in its
+`profile` argument, so a registration was never per-profile. What a client
+reaches is decided when its owner signs in: every profile whose `members:` lists
+them.
 
-```bash
-# RIGHT — the token goes from the CLI to the harness. You never see it.
-claude mcp add --transport http lanes-link http://127.0.0.1:7337/mcp \
-  --header "Authorization: Bearer $(lanes link token show --raw --profile <name> --workspace <name>)"
+**Do not write an `Authorization` header.** The registration is a bare URL:
 
-# WRONG — the token is now in your context, and in the transcript, forever.
-lanes link token show --show          # then copying the value into the command
+```bash
+claude mcp add --transport http lanes-link http://127.0.0.1:7337/mcp
 ```
 
-The token reaches every account of every profile the endpoint serves. Use the
-substitution form. If you have already printed one by accident, say so and offer
-`lanes link token rotate --profile <name> --workspace <name>`.
+The client reads this endpoint's protected-resource document, sends its owner to
+sign in, and comes back holding a token of its own. That is why a re-registration
+is not needed after a rotate, and why a harness config in a dotfiles repository
+is not a leak.
 
-Prefer `lanes link mcp add --profile <name> --workspace <name>` to writing the command yourself: it checks the
-endpoint is reachable, refuses to silently shadow an existing registration, and
-cannot mistype the token. For a harness it does not know, take the command from
-`lanes link outputs --profile <name> --workspace <name>` rather than writing it blind — that command checks whether
-`lanes` resolves on this machine and prints a longer working form if it does
-not, where guessing gives you an empty substitution, a `Bearer ` header, and a
-401 that reads as a bad token.
-
-If you register Codex, tell the user to export the token — Codex stores only the
-variable name, so nothing works until it is set:
+**A static token is CI's, and it belongs to a person.** For a runner with no
+browser, issue one and let the shell substitute it — never paste it, because a
+pasted token passes through the agent's context and into the transcript:
 
 ```bash
-export LANES_LINK_TOKEN="$(lanes link token show --raw --profile <name> --workspace <name>)"
+lanes link token issue --me --workspace <name>
+export LANES_LINK_TOKEN="$(lanes link token show --raw --workspace <name>)"
 ```
 
+`--headless` on `mcp add` writes such a token into a registration. If you have
+printed one by accident, say so and offer `lanes link token rotate --workspace
+<name>` — no `--profile`, which those commands refuse.
+
+Prefer `lanes link mcp add --workspace <name>` to writing the command yourself:
+it checks the endpoint is reachable and refuses to silently shadow an existing
+registration. For a harness it does not know, take the command from `lanes link
+outputs --workspace <name>` rather than writing it blind.
+
 One registration covers every profile. Do not add one per profile; they share a
-URL and a token.
+URL.
 
 `lanes link mcp list` needs neither flag and reports whether the registration and
 this document are current, out of date, or absent. That is the cheap first
@@ -521,8 +545,9 @@ copy means the rules you are reading are not the ones that shipped.
 
 Claude Desktop cannot be handed a URL, so it spawns the endpoint over stdio
 instead. That one is named in the client's own config file rather than registered
-by a command, as `lanes link mcp stdio --profile <name> --workspace <name>`; both
-flags are required, and nothing may be written to stdout.
+by a command, as `lanes link mcp stdio --workspace <name>`; the workspace is
+required, `--only --profile <name>` narrows what it serves, and nothing may be
+written to stdout.
 
 ## When it is not running
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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/auth/index.ts

@@ -32,10 +32,12 @@ export interface Principal {
   /**
    * Every profile this caller may reach, or `undefined` for "all of them".
    *
-   * `undefined` is the machine token and the stdio pipe: neither is a person,
-   * both reach the whole workspace, and saying so explicitly is better than
-   * enumerating a list that would then need keeping in step. A `member` always
-   * carries a list, because the list *is* the delegation (ADR-060).
+   * `undefined` is the stdio pipe and nothing else now (ADR-068). The pipe is
+   * its own proof — a process that can write to it already has the operator's
+   * shell — so there is no credential to carry a subject and no member list to
+   * match. Every token, static or issued, carries a list: a `member`'s because
+   * the list *is* the delegation (ADR-060), and a `machine`'s because a bearer
+   * token names the person it was issued to rather than opening everything.
    */
   readonly profiles?: readonly string[] | undefined;
 }
@@ -61,6 +63,25 @@ export function memberPrincipal(
   return { id: subject, profile, kind: 'member', profiles };
 }
 
+/**
+ * A static token's holder, and the profiles whose `members:` name them.
+ *
+ * The same shape as `memberPrincipal` and deliberately so — `kind` is the only
+ * difference, and it exists for the audit log rather than for policy. ADR-060
+ * described this principal and nothing minted one: the static token resolved to
+ * `ownerPrincipal`, reaching every profile in the workspace, which made it the
+ * one credential here that never had to say who was holding it. A row in
+ * `tokens:` names a subject (ADR-068), so this resolves the same way an OAuth
+ * token does and `mayReach` gets no special case.
+ */
+export function machinePrincipal(
+  subject: string,
+  profile: string,
+  profiles: readonly string[],
+): Principal {
+  return { id: subject, profile, kind: 'machine', profiles };
+}
+
 /**
  * The same caller, acting within a different profile.
  *
@@ -161,10 +182,39 @@ export function tokensMatch(a: string, b: string): boolean {
   return timingSafeEqual(hash(a), hash(b));
 }
 
+/**
+ * One issued token, as the authenticator needs it.
+ *
+ * Structurally what `connections.yaml` holds, declared here rather than
+ * imported: `auth` may not reach `#profile` (the architecture test enforces the
+ * direction), and the rows arrive as a closure for the same reason
+ * `profilesFor` does.
+ */
+export interface IssuedToken {
+  readonly id: string;
+  readonly subject: string;
+  readonly ref: SecretRef;
+}
+
 export interface AuthenticatorOptions {
+  /**
+   * The primary, which is what `principal.profile` starts as.
+   *
+   * Not what the token reaches — that is `profilesFor(subject)`. It is where
+   * the connection was opened, and every dispatch rewrites it with `forProfile`.
+   */
   readonly profile: string;
-  readonly tokenRef: SecretRef;
+  /** The workspace's issued tokens. Re-read on every reload, so a revoke lands. */
+  readonly tokens: () => Promise<readonly IssuedToken[]>;
   readonly credentials: SecretStore;
+  /**
+   * Which profiles list this subject as a member.
+   *
+   * The same resolver the OAuth path is handed (`server/endpoint.ts`), passed in
+   * rather than reached for, so discovery and enforcement cannot disagree about
+   * a subject's reach.
+   */
+  readonly profilesFor: (subject: string) => Promise<readonly string[]>;
   /** Injectable for tests. Only the cache window reads it. */
   readonly now?: () => number;
 }
@@ -183,10 +233,16 @@ export interface AuthenticatorOptions {
  */
 const CACHE_TTL_MS = 5_000;
 
+/** An issued row, with its value read out of the store. */
+interface LoadedToken {
+  readonly subject: string;
+  readonly value: string;
+}
+
 export class BearerAuthenticator implements Authenticator {
   readonly #options: AuthenticatorOptions;
   readonly #now: () => number;
-  #cached: string | null = null;
+  #cached: readonly LoadedToken[] | null = null;
   #readAt = 0;
 
   constructor(options: AuthenticatorOptions) {
@@ -195,48 +251,79 @@ export class BearerAuthenticator implements Authenticator {
   }
 
   async authenticate(authorizationHeader: string | null | undefined): Promise<AuthOutcome> {
-    const { profile } = this.#options;
-
     const presented = parseBearer(authorizationHeader);
     if (presented === null) {
       return { ok: false, reason: authorizationHeader ? 'malformed' : 'missing' };
     }
 
     const fresh = this.#cached !== null && this.#now() - this.#readAt < CACHE_TTL_MS;
-    let expected = fresh ? this.#cached : await this.#reload();
+    let rows = fresh ? this.#cached! : await this.#reload();
+    let matched = find(presented, rows);
 
-    // A mismatch against a *cached* value is ambiguous: either the credential is
+    // A miss against a *cached* set is ambiguous: either the credential is
     // wrong, or it is the right one and this process has not seen the rotation
-    // that produced it. One re-read separates the two, and it is what makes a
-    // rotated-in token work on its first call rather than after the window.
-    // Only a cached comparison can be wrong this way, so a fresh read never
-    // pays for a second one — which is what keeps a wrong token from costing a
-    // store read per attempt.
-    if (fresh && (expected === null || !tokensMatch(presented, expected))) {
-      expected = await this.#reload();
+    // or the issue that produced it. One re-read separates the two, and it is
+    // what makes a rotated-in token work on its first call rather than after
+    // the window. Only a cached comparison can be wrong this way, so a fresh
+    // read never pays for a second one — which is what keeps a wrong token from
+    // costing a store read per attempt.
+    if (fresh && matched === null) {
+      rows = await this.#reload();
+      matched = find(presented, rows);
     }
 
-    if (expected === null) {
-      // The profile has no token yet. Fail closed and let `lanes link doctor` explain.
+    if (rows.length === 0) {
+      // No token has been issued. Fail closed, and distinctly from a wrong one:
+      // `lanes link doctor` reads this to say "issue one" rather than "check it".
       return { ok: false, reason: 'not_configured' };
     }
 
-    return tokensMatch(presented, expected)
-      ? { ok: true, principal: ownerPrincipal(profile) }
-      : { ok: false, reason: 'invalid' };
+    if (matched === null) return { ok: false, reason: 'invalid' };
+
+    // **Resolved per request, not cached with the value.** Membership is read
+    // when a token is minted for an OAuth client (ADR-060) because there is a
+    // mint to read it at; a static token has none, so this is the only place
+    // the question can be asked. It is what makes `profile members remove`
+    // take effect on the next call rather than on the next rotation.
+    //
+    // A resolver that throws fails closed. The alternative — falling back to
+    // "every profile" — would restore exactly the behaviour ADR-068 removes,
+    // and would do it precisely when something is already wrong.
+    let profiles: readonly string[];
+    try {
+      profiles = await this.#options.profilesFor(matched.subject);
+    } catch {
+      return { ok: false, reason: 'invalid' };
+    }
+
+    return {
+      ok: true,
+      principal: machinePrincipal(matched.subject, this.#options.profile, profiles),
+    };
   }
 
-  async #reload(): Promise<string | null> {
+  async #reload(): Promise<readonly LoadedToken[]> {
     // Both caches, or neither: the store holds its own decrypted copy, so
     // re-reading without dropping that first re-reads the same stale value.
     this.#options.credentials.refresh?.();
-    this.#cached = await this.#options.credentials.get(this.#options.tokenRef);
+
+    const rows = await this.#options.tokens();
+    const loaded: LoadedToken[] = [];
+    for (const row of rows) {
+      const value = await this.#options.credentials.get(row.ref);
+      // A row whose credential is gone is not an error to report here. It is
+      // what a half-finished `secrets push` looks like, and the row simply
+      // matches nothing — `doctor` is where that is worth a sentence.
+      if (value) loaded.push({ subject: row.subject, value });
+    }
+
+    this.#cached = loaded;
     this.#readAt = this.#now();
-    return this.#cached;
+    return loaded;
   }
 
   /**
-   * Drop the cached value immediately.
+   * Drop the cached set immediately.
    *
    * The window above already bounds how long a rotation goes unnoticed, so this
    * is an optimisation rather than the mechanism — nothing's correctness may
@@ -247,6 +334,20 @@ export class BearerAuthenticator implements Authenticator {
   }
 }
 
+/**
+ * The row a presented token matches, or null.
+ *
+ * Every row is compared even after one matches. Returning early would make the
+ * time taken describe *which* row answered, and the whole point of
+ * `tokensMatch` is that a comparison here leaks nothing about the value it is
+ * comparing against.
+ */
+function find(presented: string, rows: readonly LoadedToken[]): LoadedToken | null {
+  let found: LoadedToken | null = null;
+  for (const row of rows) if (tokensMatch(presented, row.value)) found = row;
+  return found;
+}
+
 /**
  * Mint a profile token: 32 random bytes, base64url, prefixed so it is
  * recognisable in a config file and greppable in a leak.

package/src/cli/accepts.ts

@@ -68,8 +68,14 @@ export const ACCEPTS: Record<string, readonly string[]> = {
   'target show': ['workspace'],
   'mcp install-instructions': ['client'],
   pair: ['print', 'rotate', 'yes'],
-  'token show': ['show', 'raw'],
-  'token rotate': ['show', 'raw', 'yes'],
+  // `--id` names which row, and is required once more than one is issued.
+  // `--subject`/`--me` say who a new one is for, which is the whole of ADR-068.
+  token: ['json'],
+  'token list': ['json'],
+  'token issue': ['show', 'subject', 'me', 'label'],
+  'token show': ['show', 'raw', 'id'],
+  'token rotate': ['show', 'raw', 'yes', 'id'],
+  'token revoke': ['yes', 'id'],
   'audit tail': ['limit', 'denied-only', 'format'],
   'audit verify': ['limit', 'format'],
   attach: ['connection'],
@@ -77,7 +83,11 @@ export const ACCEPTS: Record<string, readonly string[]> = {
   start: ['port', 'only'],
   'mcp stdio': ['only'],
   'mcp add': ['name', 'scope', 'token-env', 'dry-run', 'force', 'no-skill', 'headless'],
-  'mcp skill': ['print', 'force'],
+  // No `--force`: `mcp skill` prints a path or the document and writes nothing,
+  // so there was nothing for it to force. It was accepted and ignored, which is
+  // the defect `selection.ts` exists to prevent. `mcp add --force` is the flag
+  // that replaces a registration.
+  'mcp skill': ['print'],
   'mcp list': ['name', 'scope'],
   // `--yes` because it installs the app when nothing answers the scheme, and
   // that is the one prompt in this CLI that puts an application on the machine.

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

@@ -22,6 +22,14 @@ export function declareConnection(input: {
   readonly connectionId: string;
   readonly account: string;
   readonly label: string;
+  /**
+   * What the row is called with nobody's word for it, from `settleIdentity`.
+   *
+   * The provider's name and the account composed by `defaultConnectionLabel`,
+   * which is what every reader falls back to. A label equal to it is a line
+   * saying what the two lines above it already say, so it is not written.
+   */
+  readonly defaultLabel: string;
   /** Which route in, where the provider offered a choice. */
   readonly method: string | undefined;
   /**
@@ -34,6 +42,7 @@ export function declareConnection(input: {
   readonly config: Readonly<Record<string, string>>;
 }): readonly string[] {
   const { document, connections, providerId, connectionId, account, label, method } = input;
+  const derived = input.defaultLabel;
   const config = input.config;
 
   const key = `${providerId}.${connectionId}`;
@@ -45,14 +54,14 @@ export function declareConnection(input: {
     // 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.
+    // No `label` either, when it is the one every reader derives anyway.
+    // Pressing Enter at the prompt is the common answer, and a line repeating
+    // the provider and the address above it is a line to read past forever.
     document.addTo(['connections'], {
       id: connectionId,
       provider: providerId,
       account,
-      ...(label === account ? {} : { label }),
+      ...(label === derived ? {} : { label }),
       ...(Object.keys(config).length > 0 ? { config } : {}),
     });
     changes.push(`connections += ${key} (${account})`);
@@ -69,10 +78,10 @@ export function declareConnection(input: {
     changes.push(`connections.${key}.account = ${account}`);
   }
 
-  // Compared against what the row is *called*, which is the account until
+  // Compared against what the row is *called*, which is the derived name 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) {
+  // unlabelled connection writes a label that says what the lines above it say.
+  if ((declared?.label ?? derived) !== label) {
     document.setIn(['connections', index, 'label'], label);
     changes.push(`connections.${key}.label = ${label}`);
   }

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

@@ -237,7 +237,7 @@ 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, label } = await settleIdentity({
+    const settled = await settleIdentity({
       manifest,
       provisionalId,
       explicitId: named,
@@ -246,6 +246,7 @@ export async function runConnect(
       runtime: { ...runtime, connectorFor: address.connectorFor },
       prompter,
     });
+    const { connectionId, account, label } = settled;
 
     const connectionKey = `${providerId}.${connectionId}`;
 
@@ -277,9 +278,8 @@ export async function runConnect(
         document: connectionsDocument,
         connections: runtime.workspaceConnections,
         providerId,
-        connectionId,
-        account,
-        label,
+        // The settled identity as one value: the row, the account, the name.
+        ...settled,
         method: method.id,
         config: address.values,
       }),

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

@@ -1,6 +1,7 @@
 import { createMcpConnector } from '#connectivity/transports';
 import { bearerTokenAsStored } from '#connectivity/auth/index.ts';
 import type { SecretStore } from '#secrets';
+import { defaultConnectionLabel } from '#profile';
 import type { ConnectionConfig, Config } from '#profile';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { nextConnectionId, resolveAccount } from '../../identity.ts';
@@ -46,7 +47,21 @@ export async function settleIdentity(input: {
     authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
   };
   prompter?: Prompter;
-}): Promise<{ connectionId: string; account: string; label: string }> {
+}): Promise<{
+  connectionId: string;
+  account: string;
+  label: string;
+  /**
+   * What this row is called with nobody's word for it, carried to the writer.
+   *
+   * `declareConnection` writes no label equal to it, for the reason it never
+   * wrote one equal to the account: a line saying what the two lines above it
+   * say is a line to read past forever. Returned rather than derived twice, so
+   * the string the operator was offered and the string compared against it
+   * cannot come apart.
+   */
+  defaultLabel: string;
+}> {
   const { manifest, provisionalId, explicitId, runtime } = input;
   const prompter = input.prompter ?? terminalPrompter;
 
@@ -169,17 +184,20 @@ export async function settleIdentity(input: {
           (candidate) => candidate.account.toLowerCase() === account!.toLowerCase(),
         )?.id ?? nextConnectionId(taken, false)));
 
+  const defaultLabel = defaultConnectionLabel(manifest.name, account);
+
   return {
     connectionId,
     account,
+    defaultLabel,
     label: await settleLabel({
       given: input.label,
+      fallback: defaultLabel,
       // 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,
     }),
@@ -198,21 +216,29 @@ export async function settleIdentity(input: {
  * 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.
+ *
+ * **The suggestion is the provider and the account, not the account.** It was
+ * the address alone, which made the label a second copy of the field beside it
+ * — and left every surface that shows a name without one, because a default
+ * that only repeats another line is a default nothing writes down.
+ * `defaultConnectionLabel` is the whole rule and every reader derives the same
+ * string from it.
  */
 async function settleLabel(input: {
   given: string | undefined;
   declared: string | undefined;
-  account: string;
+  /** What this row is called when nobody says otherwise. */
+  fallback: string;
   typed: boolean;
   prompter: Prompter;
 }): Promise<string> {
-  const { given, declared, account, typed, prompter } = input;
+  const { given, declared, fallback, 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;
+  // A label already chosen wins over the derived one, so re-authorising an
+  // expired credential does not quietly undo the operator's own word for the row.
+  const suggestion = declared ?? fallback;
 
   if (typed || !prompter.interactive) return suggestion;