@lanes-sh/link 0.9.2 → 0.9.3

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

@@ -1,70 +1,340 @@
-import { announce, ok, print, style, warn } from '../../output.ts';
-import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
+import { CONNECTIONS_FILE, nextTokenId, readConnections, tokenRef } from '#profile';
+import { readSession } from '#auth/lanes/session.ts';
+import { ConfigError } from '#profile';
+import { ConfigDocument } from '../../config-edit.ts';
+import { openOrCreateConnections } from '../../config-repair-sweep.ts';
+import { heading, ok, print, style, warn } from '../../output.ts';
+import { openWorkspaceRuntime, type GlobalFlags } from '../../runtime.ts';
 
-/** `lanes link token` — the one bearer token this endpoint accepts. */
+/**
+ * `lanes link token` — the static tokens this workspace has issued.
+ *
+ * **A token names a person, and the workspace holds it** (ADR-068). Both halves
+ * changed at contract 5. It used to be one credential at `auth.token_ref`,
+ * whose default was the constant `profile/token` for every profile in a store
+ * that is one per workspace — so `--profile` was asked for and could not affect
+ * the answer, and removing a profile deleted the token its siblings were served
+ * by. And it resolved to the primary profile's owner with "every profile" as
+ * its reach, which made it the one credential on this endpoint that never said
+ * who was holding it.
+ *
+ * So `issue` takes a subject and `show`/`rotate`/`revoke` take a row id. What
+ * the token then reaches is whatever that subject is a member of, resolved on
+ * every call — the same rule an OAuth token has followed since ADR-060.
+ *
+ * These are for a machine with no browser. A person registers a client against
+ * the bare URL and signs in (ADR-062); `--headless` is the flag that says
+ * otherwise, and it is why this family still exists.
+ */
 
-/** The token, or enough of it to recognise. One shape, so the two commands agree. */
+export interface TokenFlags extends GlobalFlags {
+  readonly show?: boolean | undefined;
+  readonly raw?: boolean | undefined;
+  readonly id?: string | undefined;
+  readonly subject?: string | undefined;
+  readonly me?: boolean | undefined;
+  readonly label?: string | undefined;
+  readonly json?: boolean | undefined;
+}
+
+/** The token, or enough of it to recognise. One shape, so every command agrees. */
 function show(token: string, reveal: boolean | undefined): string {
   return reveal ? token : `${token.slice(0, 8)}…  ${style.dim('(--show to reveal)')}`;
 }
 
-export async function tokenShow(
-  flags: GlobalFlags & { show?: boolean | undefined; raw?: boolean | undefined },
-): Promise<void> {
-  const runtime = await openRuntime(flags);
-  try {
-    const { token, created } = await ensureProfileToken(
-      runtime.credentials,
-      runtime.config.auth.token_ref,
+/**
+ * Which subject a row is being issued to.
+ *
+ * `--me` reads the signed-in session rather than asking, because typing your own
+ * subject out of `lanes auth status` is a transcription step with a silent
+ * failure mode: a mistyped subject is a valid-looking row that matches no
+ * member, and the token it holds then reaches nothing for a reason nothing
+ * prints. Neither flag is a guess — one of the two is required.
+ */
+async function subjectFor(flags: TokenFlags): Promise<string> {
+  if (flags.subject !== undefined && flags.me === true) {
+    throw new ConfigError(
+      '--subject and --me both name who the token is for, so pass one.\n' +
+        '  --me reads the subject you are signed in as.',
+    );
+  }
+
+  if (flags.subject !== undefined) return flags.subject;
+
+  if (flags.me !== true) {
+    throw new ConfigError(
+      'A token is issued to somebody, so say who.\n' +
+        '  --me                 the subject you are signed in as\n' +
+        '  --subject lanes:<id> somebody else, as "lanes members list" reports them\n' +
+        '  What it reaches is whatever that subject is a member of, and nothing else.',
+    );
+  }
+
+  const session = await readSession().catch(() => null);
+  if (!session?.subject) {
+    throw new ConfigError(
+      '--me needs a signed-in session, and there is none.\n' +
+        '  Run: lanes auth login',
     );
+  }
+  return session.subject;
+}
+
+/**
+ * Refuse a `--profile` that can no longer mean anything.
+ *
+ * The alternative is accepting and ignoring it, which `selection.ts` names as
+ * the defect it exists to prevent: an operator who passes `--profile work` here
+ * believes they scoped the token to one profile, and it is the member list that
+ * decides. Saying so is the whole fix.
+ */
+function assertNoProfile(flags: TokenFlags, command: string): void {
+  if (flags.profile === undefined) return;
+  throw new ConfigError(
+    `--profile does not scope "lanes link token ${command}" (ADR-068).\n` +
+      '  A token names the person it was issued to, and reaches every profile whose\n' +
+      '  members list them. To narrow what one reaches, edit the member lists:\n' +
+      '    lanes link profile members remove --subject <id> --profile <name> --workspace <name>',
+  );
+}
+
+export async function tokenIssue(flags: TokenFlags): Promise<void> {
+  assertNoProfile(flags, 'issue');
+  const subject = await subjectFor(flags);
+
+  const runtime = await openWorkspaceRuntime(flags);
+  try {
+    const root = runtime.resolution.workspaceRoot;
+    const existing = (await readConnections(root)).tokens;
+    const id = nextTokenId(existing.map((row) => row.id));
+    const ref = tokenRef(id);
+
+    const { generateProfileToken } = await import('#auth');
+    const token = generateProfileToken();
+
+    // The credential first, then the row. The other order leaves a row naming a
+    // ref with nothing behind it, which reads to the authenticator as a token
+    // that matches nothing — a working-looking registry whose token is refused.
+    await runtime.credentials.set(ref, token);
+
+    // Created from the template if absent, which is what a workspace whose
+    // profiles predate `connections.yaml` looks like — and `token issue` is a
+    // plausible first write into a fresh one.
+    const document = await openOrCreateConnections(root);
+    document.addTo(['tokens'], {
+      id,
+      subject,
+      ref,
+      ...(flags.label === undefined ? {} : { label: flags.label }),
+      issued_at: new Date().toISOString(),
+    });
+    await document.save();
+
+    print(ok(`issued ${style.bold(id)} to ${subject}`));
+    print(`  ${show(token, flags.show)}`);
+    print();
+
+    const reaches = await profilesFor(root, subject);
+    if (reaches.length === 0) {
+      print(warn('no profile in this workspace lists that subject, so this token reaches nothing'));
+      print(
+        style.dim(
+          '  Add them: lanes link profile members add --subject ' +
+            `${subject} --profile <name> --workspace ${runtime.target}`,
+        ),
+      );
+    } else {
+      print(style.dim(`  Reaches: ${reaches.join(', ')} — every profile listing that subject.`));
+    }
+  } finally {
+    await runtime.close();
+  }
+}
+
+export async function tokenList(flags: TokenFlags): Promise<void> {
+  const runtime = await openWorkspaceRuntime(flags);
+  try {
+    const root = runtime.resolution.workspaceRoot;
+    const rows = (await readConnections(root)).tokens;
+
+    if (flags.json) {
+      const payload = await Promise.all(
+        rows.map(async (row) => ({
+          id: row.id,
+          subject: row.subject,
+          ...(row.label === undefined ? {} : { label: row.label }),
+          ...(row.issued_at === undefined ? {} : { issued_at: row.issued_at }),
+          reaches: await profilesFor(root, row.subject),
+          present: (await runtime.credentials.get(row.ref)) !== null,
+        })),
+      );
+      print(JSON.stringify({ target: runtime.target, tokens: payload }, null, 2));
+      return;
+    }
+
+    if (rows.length === 0) {
+      print('No token has been issued in this workspace.');
+      print(
+        style.dim(
+          '  A person does not need one: a client registers against the bare URL and signs in.\n' +
+            `  For a machine with no browser: lanes link token issue --me --workspace ${runtime.target}`,
+        ),
+      );
+      return;
+    }
+
+    heading(`Tokens (${rows.length})`);
+    for (const row of rows) {
+      const reaches = await profilesFor(root, row.subject);
+      // A row whose credential is gone matches nothing, and reads exactly like a
+      // wrong token from the client's side. Naming it here is the cheap half of
+      // what `doctor` says at length.
+      const missing = (await runtime.credentials.get(row.ref)) === null;
+      print(
+        `  ${row.id}  ${row.subject}` +
+          (row.label ? `  ${style.dim(`(${row.label})`)}` : '') +
+          `  ${reaches.length > 0 ? reaches.join(', ') : style.dim('reaches nothing')}` +
+          (missing ? `  ${style.dim('— value missing from the store')}` : ''),
+      );
+    }
+    print(style.dim('  What each reaches is every profile whose members list its subject.'));
+  } finally {
+    await runtime.close();
+  }
+}
+
+export async function tokenShow(flags: TokenFlags): Promise<void> {
+  assertNoProfile(flags, 'show');
+  const runtime = await openWorkspaceRuntime(flags);
+  try {
+    const root = runtime.resolution.workspaceRoot;
+    const row = pick((await readConnections(root)).tokens, flags, runtime.target);
+    const token = await runtime.credentials.get(row.ref);
+
+    if (token === null) {
+      throw new ConfigError(
+        `Token "${row.id}" has a row but no value at "${row.ref}" in this workspace's store.\n` +
+          `  Re-mint it: lanes link token rotate --id ${row.id} --workspace ${runtime.target}`,
+      );
+    }
 
     // `--raw` prints the token and nothing else, for command substitution:
     //
-    //   claude mcp add … --header "Authorization: Bearer $(lanes link token show --raw)"
+    //   export LANES_LINK_TOKEN="$(lanes link token show --raw --workspace local)"
     //
-    // That is the recommended way to register an instance, and the reason is
-    // not convenience. A token pasted from `--show` passes through the agent's
-    // context and into its transcript; substituted by the shell it goes from
-    // this process to the harness and is never seen by the model at all.
+    // A token pasted from `--show` passes through the agent's context and into
+    // its transcript; substituted by the shell it goes from this process to the
+    // consumer and is never seen by the model at all.
     if (flags.raw) {
       process.stdout.write(`${token}\n`);
       return;
     }
 
-    announce(runtime.resolution);
-    if (created) print(warn('no token existed; a new one was minted'));
+    print(`${row.id}  ${row.subject}`);
     print(show(token, flags.show));
   } finally {
     await runtime.close();
   }
 }
 
-export async function tokenRotate(
-  flags: GlobalFlags & { show?: boolean | undefined },
-): Promise<void> {
-  const runtime = await openRuntime(flags);
+export async function tokenRotate(flags: TokenFlags): Promise<void> {
+  assertNoProfile(flags, 'rotate');
+  const runtime = await openWorkspaceRuntime(flags);
   try {
-    announce(runtime.resolution);
+    const root = runtime.resolution.workspaceRoot;
+    const row = pick((await readConnections(root)).tokens, flags, runtime.target);
 
     const { generateProfileToken } = await import('#auth');
     const token = generateProfileToken();
-    await runtime.credentials.set(runtime.config.auth.token_ref, token);
+    await runtime.credentials.set(row.ref, token);
 
-    print(ok('token rotated'));
-    // Gated the way `tokenShow` gates it, and for the reason given above: a
-    // token printed here goes into the transcript of whatever ran the command.
+    print(ok(`rotated ${style.bold(row.id)}`));
+    // Gated the way `tokenShow` gates it, and for the same reason: a token
+    // printed here goes into the transcript of whatever ran the command.
     // Rotating is what an operator does *because* a token leaked, so printing
     // the replacement unasked is the one moment it costs the most.
     print(`  ${show(token, flags.show)}`);
     print();
-    // Rotating invalidates every agent using this endpoint, which is the cost
-    // of one token per endpoint rather than one per agent. Say so plainly —
-    // and say how, because `claude mcp add` stores the substituted value rather
-    // than the command, so nothing re-reads this on its own.
-    print(warn('every agent configured with the old token must be re-registered'));
-    print(style.dim('  A harness stores the token it was given, not the command that produced it.'));
-    print(style.dim('  Run: lanes link outputs with this profile and target for the command to re-run.'));
+    // Narrower than it used to be, and worth saying so. A rotate used to
+    // invalidate every agent on the endpoint, because there was one token and
+    // every registration carried it. Registrations do not carry one now
+    // (ADR-062), so this affects only what was given *this* row's value.
+    print(warn(`anything holding ${row.id} must be given the new value`));
+    print(style.dim('  Clients that signed in through a browser are unaffected — they hold their own tokens.'));
   } finally {
     await runtime.close();
   }
 }
+
+export async function tokenRevoke(flags: TokenFlags): Promise<void> {
+  assertNoProfile(flags, 'revoke');
+  const runtime = await openWorkspaceRuntime(flags);
+  try {
+    const root = runtime.resolution.workspaceRoot;
+    const rows = (await readConnections(root)).tokens;
+    const row = pick(rows, flags, runtime.target);
+
+    // The row first, then the credential. This is the reverse of `issue` and
+    // for the same reason read the other way: what must never survive a partial
+    // failure is a *usable* token, so the thing that makes it usable goes last.
+    const document = await ConfigDocument.openKey(root, CONNECTIONS_FILE);
+    document.removeFrom(['tokens'], rows.indexOf(row));
+    await document.save();
+
+    await runtime.credentials.delete(row.ref);
+
+    print(ok(`revoked ${style.bold(row.id)}`));
+    print(style.dim('  It is refused within the authenticator\'s cache window, which is seconds.'));
+  } finally {
+    await runtime.close();
+  }
+}
+
+/**
+ * The row a command acts on.
+ *
+ * With one row and no `--id`, that row: naming it would be ceremony, and the
+ * common workspace has exactly one. With several, it refuses and lists them —
+ * the `deploy` rule, for the same reason. Nothing is chosen from among
+ * candidates.
+ */
+function pick(
+  rows: readonly { id: string; subject: string; ref: string }[],
+  flags: TokenFlags,
+  target: string,
+): { id: string; subject: string; ref: string } {
+  if (rows.length === 0) {
+    throw new ConfigError(
+      'No token has been issued in this workspace.\n' +
+        `  Issue one: lanes link token issue --me --workspace ${target}`,
+    );
+  }
+
+  if (flags.id !== undefined) {
+    const found = rows.find((row) => row.id === flags.id);
+    if (!found) {
+      throw new ConfigError(
+        `No token "${flags.id}" in this workspace. Have: ${rows.map((row) => row.id).join(', ')}.`,
+      );
+    }
+    return found;
+  }
+
+  if (rows.length > 1) {
+    throw new ConfigError(
+      `This workspace has ${rows.length} tokens, so this command needs --id.\n` +
+        rows.map((row) => `    ${row.id}  ${row.subject}`).join('\n'),
+    );
+  }
+
+  return rows[0]!;
+}
+
+/** Every profile in this workspace whose `members:` names a subject. */
+async function profilesFor(root: string, subject: string): Promise<string[]> {
+  const { loadWorkspaceProfiles } = await import('#profile');
+  const { loaded } = await loadWorkspaceProfiles(root);
+  return loaded
+    .filter((entry) => entry.config.members.some((member) => member.subject === subject))
+    .map((entry) => entry.profile);
+}

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

@@ -1,7 +1,8 @@
 import { capabilityIdForToolName } from '#server/mcp';
+import { anyIssuedToken } from '#profile';
 import { deployedUrl, endpointHealth, localUrl } from '../../endpoint-url.ts';
 import { announce, emit, heading, print, style, warn } from '../../output.ts';
-import { ensureProfileToken, openRuntime, type GlobalFlags } from '../../runtime.ts';
+import { openRuntime, type GlobalFlags } from '../../runtime.ts';
 
 export interface ToolsFlags extends GlobalFlags {
   readonly json?: boolean | undefined;
@@ -27,7 +28,12 @@ export async function tools(flags: ToolsFlags): Promise<void> {
   const runtime = await openRuntime(flags);
 
   try {
-    const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
+    // Any token the workspace holds, or none (ADR-068). `tools` reports a
+    // profile's resolved surface, so it still names one — what it no longer
+    // does is mint a credential in order to read.
+    const token = (
+      await anyIssuedToken(runtime.resolution.workspaceRoot, runtime.credentials)
+    )?.value;
     const declared = runtime.declared.deploy;
     const deployed = await deployedUrl(declared);
     // Not `endpointUrl`, which asks the platform a second time for an answer
@@ -40,9 +46,26 @@ export async function tools(flags: ToolsFlags): Promise<void> {
     // token that works. Reporting that as the deployed endpoint's surface is
     // the failure `endpoint-url.ts` calls "silent in the worst way".
     const live = await endpointHealth(url, token);
-    const mine = live?.profile === runtime.resolution.profile;
-
-    const surface = await askEndpoint(url, token);
+    const mine =
+      token === undefined ? live !== null : live?.profile === runtime.resolution.profile;
+
+    // **Nothing to ask with** is a reportable state rather than a failure
+    // (ADR-068). Asking the endpoint for its tool list means being a client of
+    // it, and a client authenticates; a workspace that has issued no static
+    // token has nothing this command can present, and minting one would bind a
+    // credential to a subject nobody chose. What is still true without it is
+    // everything on the left of the comparison — the capabilities this
+    // *config* resolves to — which is most of what the command is for.
+    const surface =
+      token === undefined
+        ? {
+            reachable: false,
+            reason:
+              'no static token is issued in this workspace, so the endpoint cannot be queried',
+            names: [],
+            bytes: 0,
+          }
+        : await askEndpoint(url, token);
     const providers = [...new Set(runtime.registry.capabilities().map(({ id }) => id))];
 
     await emit(

package/src/cli/commands/operate.ts

@@ -30,5 +30,11 @@ export { pair, PAIR_CERT_REF, PAIR_KEY_REF, PAIR_TOKEN_REF, type PairFlags } fro
 export { desktop, settingsUrl, type DesktopFlags } from './operate/desktop.ts';
 export { auditTail, auditVerify, markdownCell } from './operate/audit.ts';
 export { attachFile } from './operate/attach.ts';
-export { tokenRotate, tokenShow } from './operate/token.ts';
+export {
+  tokenIssue,
+  tokenList,
+  tokenRevoke,
+  tokenRotate,
+  tokenShow,
+} from './operate/token.ts';
 export { configShow, policyList, policyRule } from './operate/policy.ts';

package/src/cli/commands/profile/removal.ts

@@ -51,17 +51,19 @@ export function declaredRefs(
    * What the profiles that are staying declare.
    *
    * Nothing in here is deleted, however plainly the profile being removed also
-   * declares it. The credential store is one file per *workspace* since
-   * contract 3, and every profile takes the template default
-   * `token_ref: profile/token` — so removing one profile deleted the endpoint
-   * token the others are served by, and the deployed revision then refused every
-   * request with "No profile token in this target's credential store". The vault
-   * ref is read off the target and is identical for every profile there, which
-   * made the sibling's sealed items unrecoverable in the same command.
+   * declares it. The vault ref is read off the target and is identical for every
+   * profile there, which once made a sibling's sealed items unrecoverable in
+   * this command.
+   *
+   * **The endpoint token was the sharpest case here and is no longer a case.**
+   * Every profile took the default `token_ref: profile/token` out of one
+   * per-workspace store, so removing one deleted the token its siblings were
+   * served by. What fixed it is not a better survivor check: the token was never
+   * a profile's to declare (ADR-068), so removing one cannot reach it now.
    */
   survivors: readonly Config[] = [],
 ): string[] {
-  const refs = new Set<string>([config.auth.token_ref]);
+  const refs = new Set<string>();
 
   // Read off the *target*, not the profile. `vaultTargetSchema` sits inside
   // `targetSchema`, so two targets may seal the same items in different places;
@@ -100,7 +102,6 @@ export function declaredRefs(
   // declare" has to have one answer.
   const kept = new Set(
     survivors.flatMap((other) => [
-      other.auth.token_ref,
       ...(declared.vault?.adapter === 'secret' ? [vaultRef(declared, other)] : []),
       ...(other.auth.authorization?.mode === 'oidc'
         ? [other.auth.authorization.client_id_ref]

package/src/cli/config-repair-sweep.ts

@@ -42,14 +42,28 @@ import { DEFAULT_SURFACES, ensureOwnerLayer, repairLines, repaired } from './con
  * for the workspaces 0.9.0 already migrated. One spelling, for the reason the
  * template and `ensureOwnerLayer` share one: two would have to agree forever.
  */
-export async function ensureRegistryContract(workspaceRoot: string): Promise<boolean> {
+export async function ensureRegistryContract(
+  workspaceRoot: string,
+  /**
+   * The contract to stamp, which is the one the caller is *producing*.
+   *
+   * Defaulted to the newest for the repair sweep, and passed explicitly by each
+   * migration step. A step that stamped the newest would put the registry ahead
+   * of the profiles it just wrote — and `isUnmigrated` reads exactly this field,
+   * so the registry would report the workspace as migrated with a later step
+   * still to run. That is the same defect the note on
+   * `the contract it stamps on the registry` describes, in the direction that
+   * fails silently rather than loudly.
+   */
+  contract: number = SUPPORTED_CONTRACT,
+): Promise<boolean> {
   const files = workspaceFiles(workspaceRoot);
   if (!(await files.has(WORKSPACE_FILE))) return false;
 
   const document = await ConfigDocument.openKey(workspaceRoot, WORKSPACE_FILE);
-  if (document.getIn(['contract']) === SUPPORTED_CONTRACT) return false;
+  if (document.getIn(['contract']) === contract) return false;
 
-  document.setIn(['contract'], SUPPORTED_CONTRACT);
+  document.setIn(['contract'], contract);
   await document.save();
   return true;
 }
@@ -79,7 +93,7 @@ function listSurfaces(): string {
 }
 
 /** The workspace's connections document, written from the template if missing. */
-async function openOrCreateConnections(workspaceRoot: string): Promise<ConfigDocument> {
+export async function openOrCreateConnections(workspaceRoot: string): Promise<ConfigDocument> {
   try {
     return await ConfigDocument.openKey(workspaceRoot, CONNECTIONS_FILE);
   } catch {

package/src/cli/config-repair.ts

@@ -18,7 +18,7 @@ import { nextConnectionId } from './identity.ts';
  */
 
 /** Lanes' own provider ids, and the label each row carries. */
-const RESERVED_SURFACES = {
+export const RESERVED_SURFACES = {
   lanes_memory: 'Memory',
   lanes_tasks: 'Tasks',
   lanes_assets: 'Assets',

package/src/cli/config-templates.ts

@@ -27,7 +27,7 @@ export function newProfileTemplate(profile: string, port: number, subject?: stri
 #
 # Edit it by hand or through the CLI; both are supported, and CLI edits preserve
 # your comments and ordering.
-contract: 4
+contract: 5
 
 instance:
   profile: ${profile}
@@ -47,12 +47,13 @@ instance:
 #
 #     lanes link status --profile ${profile} --workspace <name>
 #
-# The bearer token below is for CI. People sign in instead: a client that asks
-# for authorization is sent to the Lanes login, and comes back as somebody
-# (ADR-062). "lanes link token show" is for a runner with no browser.
+# No token here. A profile declares no endpoint credential (ADR-068) — the
+# workspace does, in "tokens:" in connections.yaml, one row per person it was
+# issued to. People sign in rather than holding one: a client that asks for
+# authorization is sent to the Lanes login and comes back as somebody
+# (ADR-062). "lanes link token issue" is for a runner with no browser.
 auth:
   mode: bearer
-  token_ref: profile/token
   authorization:
     mode: self
 
@@ -146,7 +147,7 @@ export function newWorkspaceTemplate(): string {
 # uses it prints which one it got. Commands that publish or destroy — deploy,
 # sync, secrets push, profile remove, disconnect, token rotate — refuse it and
 # make you type the name (ADR-061).
-contract: 4
+contract: 5
 default_workspace: local
 workspaces:
   local:
@@ -182,7 +183,7 @@ export function newConnectionsTemplate(): string {
 # still keeps its own bytes — what you write through one profile is absent in
 # another (ADR-066). A second instance is for holding two of something in one
 # profile: "lanes link connect lanes_memory --id lan9".
-contract: 4
+contract: 5
 
 connections:
   - { id: lan1, provider: lanes_memory, account: Memory }
@@ -195,6 +196,12 @@ connections:
 
 # App registrations, shared by every connection of that vendor.
 oauth_apps: {}
+
+# Static endpoint tokens, one row per person one was issued to (ADR-068). Empty
+# is the ordinary state: a client registers against the bare URL and signs in,
+# so nothing needs one until something headless does. A row reaches whatever its
+# subject is a member of — "lanes link token issue --me --workspace <name>".
+tokens: []
 `;
 }
 

package/src/cli/contract3-credentials.ts

@@ -145,10 +145,10 @@ async function readMerged(
       // values for one key, and there is no merge that means anything.
       //
       // Left behind rather than picked between. It is minted locally rather
-      // than granted by anybody, `ensureProfileToken` writes a fresh one the
-      // first time a command asks, and the old stores are not deleted — so the
-      // cost is re-registering a client, and no account has to be authorised
-      // again.
+      // than granted by anybody and the old stores are not deleted, so the cost
+      // is re-registering a client and no account has to be authorised again.
+      // Contract 5 ends this problem rather than solving it: the token is the
+      // workspace's, so there are no longer several to merge (ADR-068).
       let value: string | null;
       try {
         value = await store.get(ref);
@@ -212,10 +212,10 @@ async function readMerged(
   // routine `update`, for a conflict that did not exist.
   //
   // Where they do disagree it is still left behind rather than picked between.
-  // It is minted locally rather than granted by anybody, `ensureProfileToken`
-  // writes a fresh one the first time a command asks, and the old stores are not
-  // deleted — so the cost is re-registering a client, and no account has to be
-  // authorised again.
+  // It is minted locally rather than granted by anybody and the old stores are
+  // not deleted, so the cost is re-registering a client and no account has to be
+  // authorised again. Contract 5 removes the possibility of the disagreement:
+  // one token registry per workspace (ADR-068).
   for (const [ref, byProfile] of endpoint) {
     const values = new Set(byProfile.values());
     const agreed = values.size === 1 ? [...values][0] : undefined;

package/src/cli/contract4.ts

@@ -159,7 +159,9 @@ export async function migrateToContract4(
   // unchanged. Here rather than inside `renameRegistry` because that function
   // returns early on a workspace already holding `workspaces.yaml`, which is
   // exactly the workspace whose stamp is stale.
-  await ensureRegistryContract(workspaceRoot);
+  // Four, not the newest: contract 5 runs after this, and a registry claiming it
+  // makes `isUnmigrated` report a finished migration with a step still to go.
+  await ensureRegistryContract(workspaceRoot, 4);
   await applyMoves(files, plan.moves);
 
   // Credentials before the rows: a ref is derived from the id, so the rows must
@@ -185,7 +187,10 @@ export async function migrateToContract4(
   for (const profile of profiles) {
     const document = await ConfigDocument.openKey(workspaceRoot, layout.profileConfig(profile));
     document.setIn(['contract'], 4);
-    await document.save();
+    // The contract it is *producing*, which is not the newest one any more:
+    // contract 5 exists, so a bare `save()` here validates this document
+    // against a schema it is one step short of and refuses its own output.
+    await document.save({ contract: 4 });
   }
 
   return {