@lanes-sh/link 0.6.8 → 0.6.9

package/README.md

@@ -81,6 +81,11 @@ with Claude Code or Codex.
 It runs the commands above rather than reimplementing them, so consent and the token stay here where
 they belong, and an endpoint set up in the app is the same one you get from a shell. Available from
 Lanes v0.47.0, as a research preview.
+
+```console
+$ lanes link desktop     # opens the app on that page, installing it if it is not there
+```
+
 **[How to use it →](https://lanes.sh/docs/desktop/lanes-link)**
 
 ## What your agent gets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "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/brand.ts

@@ -2,9 +2,10 @@
  * The Lanes design tokens, and the pieces every page this repository serves is
  * built from.
  *
- * Three surfaces render HTML — the authorization consent screen, the page a
- * connect flow lands on, and the dashboard — and until this file existed each
- * carried its own approximation of the brand. They had drifted: two greens and
+ * Two surfaces render HTML — the authorization consent screen and the page a
+ * connect flow lands on. There were three until ADR-053 retired the dashboard,
+ * and until this file existed each carried its own approximation of the brand.
+ * They had drifted: two greens and
  * two ambers that are not tokens at all, nine different alphas standing in for
  * one border colour, a destructive red with a dark variant the token does not
  * have, and the system font stack where Geist belongs.
@@ -154,8 +155,8 @@ a { color: inherit; }
  *
  * The font stylesheet and the faces it names are the only two origins any of
  * them reaches; `default-src 'none'` closes the rest. No `script-src`, because
- * these pages have no script — the dashboard, which has one listener, extends
- * this rather than replacing it.
+ * a page here has no script by default — the consent screen, which has one
+ * listener for its submit spinner, extends this rather than replacing it.
  */
 export const PAGE_CSP =
   "frame-ancestors 'none'; default-src 'none'; " +
@@ -165,10 +166,10 @@ export const PAGE_CSP =
 /**
  * Headers every page here answers with.
  *
- * `frame-ancestors` in both spellings: one of these pages asks for the endpoint
- * token and another lists the owner's accounts, and framing either is the cheap
- * half of a UI-redress attack. The URLs carry a `client_id`, a `redirect_uri`,
- * or a one-time key, none of which belongs in a Referer.
+ * `frame-ancestors` in both spellings: one of these pages is a consent screen
+ * with a submit button, and framing it is the cheap half of a UI-redress
+ * attack. The URLs carry a `client_id` and a `redirect_uri`, neither of which
+ * belongs in a Referer.
  */
 export const PAGE_HEADERS: Readonly<Record<string, string>> = {
   'content-type': 'text/html; charset=utf-8',

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

@@ -0,0 +1,333 @@
+import { credentialResolver, ReauthRequired } from '#connectivity/auth/index.ts';
+import type { ResolvedCredential } from '#connectivity/auth/credential.ts';
+import { credentialRefFor } from '#registry';
+import { announce, emit, fail, ok, print, warn } from '../../output.ts';
+import { openRuntime, type GlobalFlags, type Runtime } from '../../runtime.ts';
+
+/**
+ * Whether each connection could still authenticate, asked rather than guessed.
+ *
+ * `doctor` used to answer a version of this from the *age* of a stored
+ * credential, which is wrong in both directions: it dates a credential from
+ * when its access token was last refreshed, so a healthy connection nobody has
+ * called in a fortnight reads as stale, and a grant revoked an hour ago reads
+ * as fresh because nothing has tried to use it since.
+ *
+ * So this attempts the renewal instead. That is the only thing that actually
+ * knows, and it is cheap in the case that matters: resolving an OAuth
+ * credential short-circuits on the stored `expires_at` (`oauth-authcode/provider.ts`),
+ * so a connection whose access token is still live costs no network at all. The
+ * cost is one token-endpoint round trip per connection that has genuinely
+ * lapsed — which is exactly the set worth asking about.
+ *
+ * **This command writes.** A successful refresh persists the new token, which on
+ * a deployed target is a secret-store version per refreshed connection. That is
+ * deliberate — it is the same write the serve path makes, and it warms the token
+ * for the next real call — but it is why the read-only wording `check`, `plan`
+ * and `doctor` carry does not appear here.
+ */
+
+/** What can be said about one connection's ability to authenticate. */
+export type AuthVerdict =
+  /** Resolved. The vendor accepted it just now, or its access token is still live. */
+  | 'ok'
+  /** Stored, and cannot be renewed without a person. The signal this exists for. */
+  | 'reauth'
+  /** Nothing at the credential ref. */
+  | 'missing'
+  /** A static secret is present, and nothing here can exercise it. */
+  | 'stored'
+  /** `auth.kind: none` — the owner layer. Can never need signing in. */
+  | 'none'
+  /** The probe could not complete: a timeout, a network fault, an unexpected throw. */
+  | 'unknown';
+
+export interface ConnectionAuth {
+  readonly key: string;
+  readonly provider: string;
+  readonly id: string;
+  /** The manifest's `auth.kind`, so a reader can tell why a verdict is what it is. */
+  readonly method: string;
+  readonly verdict: AuthVerdict;
+  /** Whether answering cost a token-endpoint round trip. */
+  readonly refreshed: boolean;
+  readonly detail?: string;
+  readonly fix?: string;
+}
+
+/**
+ * What the probe observed, before it means anything.
+ *
+ * Separated from the verdict so the classification can be tested without a
+ * network, a credential store, or a runtime — every interesting case here is a
+ * question about *mapping*, and the mapping is where the mistakes are.
+ */
+export type ProbeResult =
+  /** A credential came back. `staleAccessToken` is the silent-failure case below. */
+  | { readonly outcome: 'resolved'; readonly staleAccessToken: boolean }
+  /** The resolver returned `resolveNone()` — there was nothing to resolve. */
+  | { readonly outcome: 'none' }
+  | { readonly outcome: 'timeout' }
+  | { readonly outcome: 'threw'; readonly error: unknown };
+
+/**
+ * One OAuth probe result, as a verdict.
+ *
+ * The two rules worth stating out loud, because both are ways this feature
+ * could lie:
+ *
+ * **An unexpected throw is `unknown`, never `reauth`.** Only `ReauthRequired`
+ * means a person is needed. Anything else — DNS, a 500, a bug in here — must
+ * not send someone through a consent screen, and a warning that is wrong once
+ * is a warning that gets scrolled past every time after.
+ *
+ * **A resolved token is not automatically `ok`.** `upstreamAccessToken` hands
+ * back the *stale* access token when there is no refresh token to renew with,
+ * and again when a refresh returns no `access_token`. Both are deliberate on
+ * the serve path, where letting the vendor's own 401 surface is the truthful
+ * instruction — but a health check that reported them as working would be
+ * saying the opposite of what the next real call will find. So the stored
+ * expiry is checked here rather than that behaviour being changed.
+ */
+export function classifyOAuth(result: ProbeResult): AuthVerdict {
+  switch (result.outcome) {
+    case 'resolved':
+      return result.staleAccessToken ? 'reauth' : 'ok';
+    case 'none':
+      return 'missing';
+    case 'timeout':
+      return 'unknown';
+    case 'threw':
+      return result.error instanceof ReauthRequired ? 'reauth' : 'unknown';
+  }
+}
+
+/**
+ * How many connections to probe at once.
+ *
+ * Small on purpose. The work is mostly waiting on token endpoints, so some
+ * concurrency is free, but a profile with twenty Google connections hitting one
+ * endpoint at once is a rate limit rather than a speed-up.
+ */
+const CONCURRENCY = 6;
+
+/**
+ * How long one connection may take before it is reported as `unknown`.
+ *
+ * `refreshDirectly` takes no `AbortSignal`, so this races rather than cancels —
+ * the request finishes into nothing. That is acceptable for a read-shaped
+ * command and avoids threading a signal through the refresh path for the
+ * benefit of one caller.
+ */
+const PER_CONNECTION_TIMEOUT_MS = 8_000;
+
+/** `expires_at` from a stored OAuth blob, or null when it is not one. */
+function storedExpiry(raw: string | null): number | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as { expires_at?: number };
+    return typeof parsed.expires_at === 'number' ? parsed.expires_at : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface AuthFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+  /** Narrow to one connection, by `provider.id`. A filter, not a second subject. */
+  readonly connection?: string | undefined;
+}
+
+/**
+ * Every connection's verdict, probed concurrently.
+ *
+ * Exported because `doctor` asks the same question and must not answer it a
+ * second, differently-wrong way — that divergence is the bug this replaced.
+ */
+export async function probeConnections(
+  runtime: Runtime,
+  connections: readonly Runtime['config']['connections'][number][],
+  forSelection: (command: string) => string,
+): Promise<ConnectionAuth[]> {
+  const resolve = credentialResolver(runtime.registry, runtime.credentials);
+
+  const probe = async (
+    connection: Runtime['config']['connections'][number],
+  ): Promise<ConnectionAuth> => {
+    const key = `${connection.provider}.${connection.id}`;
+    const manifest = runtime.manifestFor(connection.provider);
+    const method = manifest?.auth.kind ?? 'unknown';
+    const base = { key, provider: connection.provider, id: connection.id, method };
+
+    // A provider holding nothing to authenticate with can never need signing
+    // in, and saying so is more useful than saying nothing: it is the whole
+    // owner layer, and "why is memory not checked" is a real question.
+    if (!manifest || manifest.auth.kind === 'none') {
+      return { ...base, method: 'none', verdict: 'none', refreshed: false };
+    }
+
+    const ref = credentialRefFor(connection, manifest);
+    if (!ref) return { ...base, verdict: 'none', refreshed: false };
+
+    const missing = (): ConnectionAuth => ({
+      ...base,
+      verdict: 'missing',
+      refreshed: false,
+      detail: `Nothing stored at ${ref}.`,
+      fix: forSelection(`lanes link connect ${key}`),
+    });
+
+    if (!(await runtime.credentials.has(ref))) return missing();
+
+    // Everything that is not authcode OAuth is a secret sitting in the store.
+    // There is nothing to renew and no cheap way to exercise it, so presence is
+    // the whole of what can be said — and `strategy` in particular *must* take
+    // this path, because `credentialResolver` refuses it unconditionally (it
+    // signs its own requests) and routing it through would manufacture a
+    // failure that is not there.
+    if (manifest.auth.kind !== 'oauth') {
+      return { ...base, verdict: 'stored', refreshed: false };
+    }
+
+    const before = storedExpiry(await runtime.credentials.get(ref));
+    const lapsed = before !== null && before <= Date.now();
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const result = await Promise.race([
+      resolve(connection.provider, connection.id).then(
+        (credential: ResolvedCredential): ProbeResult =>
+          credential.kind === 'none'
+            ? { outcome: 'none' }
+            : { outcome: 'resolved', staleAccessToken: false },
+        (error: unknown): ProbeResult => ({ outcome: 'threw', error }),
+      ),
+      new Promise<ProbeResult>((settle) => {
+        timer = setTimeout(() => settle({ outcome: 'timeout' }), PER_CONNECTION_TIMEOUT_MS);
+      }),
+    ]);
+    if (timer) clearTimeout(timer);
+
+    // The silent-failure check. An expiry that is *still* in the past after
+    // resolving means the resolver went out and came back with nothing better,
+    // which is the case `classifyOAuth` documents.
+    const after = storedExpiry(await runtime.credentials.get(ref));
+    const stillLapsed = after !== null && after <= Date.now();
+
+    const settled: ProbeResult =
+      result.outcome === 'resolved'
+        ? { outcome: 'resolved', staleAccessToken: stillLapsed }
+        : result;
+
+    const verdict = classifyOAuth(settled);
+    const detail =
+      result.outcome === 'threw' && result.error instanceof Error
+        ? result.error.message
+        : result.outcome === 'timeout'
+          ? `Timed out after ${PER_CONNECTION_TIMEOUT_MS / 1000}s.`
+          : settled.outcome === 'resolved' && settled.staleAccessToken
+            ? 'The stored access token is expired and could not be renewed.'
+            : undefined;
+
+    return {
+      ...base,
+      verdict,
+      // Whether answering cost a round trip: a live token means the resolver
+      // short-circuited and never went out.
+      refreshed: lapsed,
+      ...(detail ? { detail } : {}),
+      ...(verdict === 'reauth' || verdict === 'missing'
+        ? { fix: forSelection(`lanes link connect ${key}`) }
+        : {}),
+    };
+  };
+
+  return mapWithLimit(connections, CONCURRENCY, probe);
+}
+
+export async function auth(flags: AuthFlags): Promise<void> {
+  const runtime = await openRuntime(flags);
+
+  try {
+    const { profile, target } = runtime.resolution;
+    const forSelection = (command: string) => `${command} --profile ${profile} --target ${target}`;
+
+    const wanted = flags.connection;
+    const connections = wanted
+      ? runtime.config.connections.filter((c) => `${c.provider}.${c.id}` === wanted)
+      : runtime.config.connections;
+
+    if (wanted && connections.length === 0) {
+      throw new Error(
+        `No connection "${wanted}" in profile ${profile}. Run: ${forSelection('lanes link status')}`,
+      );
+    }
+
+    const results = await probeConnections(runtime, connections, forSelection);
+    const needsSomeone = results.filter((r) => r.verdict === 'reauth' || r.verdict === 'missing');
+
+    // Always zero, and this is load-bearing rather than an oversight: the
+    // desktop app discards stdout when the CLI exits non-zero, which is exactly
+    // why it cannot read `doctor`. A connection needing a person is the answer
+    // this command was asked for, not a failure to produce one.
+    return emit(flags.json, { profile, target, ok: needsSomeone.length === 0, connections: results }, () => {
+      announce(runtime.resolution);
+
+      for (const result of results) {
+        const line = `${result.key} — ${describe(result.verdict)}`;
+        if (result.verdict === 'reauth') print(fail(`${line}\n      ${result.fix}`));
+        else if (result.verdict === 'missing') print(warn(`${line}\n      ${result.fix}`));
+        else print(ok(line));
+      }
+
+      if (needsSomeone.length > 0) {
+        print();
+        print(fail(`${needsSomeone.length} connection(s) need you to sign in again`));
+      }
+    });
+  } finally {
+    await runtime.close();
+  }
+}
+
+function describe(verdict: AuthVerdict): string {
+  switch (verdict) {
+    case 'ok':
+      return 'authenticated';
+    case 'reauth':
+      return 'signed out, and cannot renew itself';
+    case 'missing':
+      return 'no credential stored';
+    case 'stored':
+      return 'credential stored, not exercised';
+    case 'none':
+      return 'needs no credential';
+    case 'unknown':
+      return 'could not be checked';
+  }
+}
+
+/**
+ * `Promise.all` with a ceiling, in the ten lines it takes.
+ *
+ * A pool rather than chunks: chunking would make every batch wait for its
+ * slowest member, which is the shape this command is trying to avoid.
+ */
+async function mapWithLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  run: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = next++;
+      if (index >= items.length) return;
+      results[index] = await run(items[index]!);
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}

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

@@ -0,0 +1,220 @@
+import { ok, print, progress, style, warn } from '../../output.ts';
+import { confirm, isInteractive } from '../../prompt.ts';
+
+/**
+ * `lanes link desktop` — open the Lanes app, on its Lanes Link page.
+ *
+ * `lanes link dashboard` is the same command under its older name. That name
+ * used to mean a page this endpoint served at `/dashboard`, and ADR-053 retired
+ * it: the desktop app has a Lanes Link settings page that runs these same
+ * commands, so the served page was the second, weaker copy of one surface.
+ *
+ * It resolves no profile and opens no runtime, which is what lets it be `'none'`
+ * in `selection.ts` — nothing here depends on which profile or target you meant.
+ * The app holds its own selection, and a command that demanded two values it
+ * then discarded would only be asking out of habit.
+ */
+
+/**
+ * The scheme the released Lanes app registers with LaunchServices.
+ *
+ * `lanes-dev` and `lanes-stage` are separate builds registering separate
+ * schemes, so testing against either means naming it — see
+ * `LANES_LINK_APP_SCHEME` below.
+ */
+const SCHEME = 'lanes';
+
+/**
+ * The settings page id.
+ *
+ * A contract with another repository: it is `SETTINGS_PAGE_IDS` in the app's
+ * `src/settings/nav.ts`, and a test there pins this spelling precisely because
+ * renaming it would break this command with nothing on either side reporting a
+ * failure. The app opens Settings on its current page rather than refusing an
+ * id it does not have, so a mismatch degrades instead of dying — which also
+ * means it is invisible.
+ */
+const PAGE = 'integrations-link';
+
+/**
+ * How the app is installed, in the tap's own spelling.
+ *
+ * Homebrew rather than a download, for the same reason the app installs this
+ * CLI with `bun install -g` rather than sending someone to npm: an install a
+ * command performs has to be one an upgrade later finds. It is only ever
+ * reached on darwin, since the platform check turns everything else away first.
+ */
+const INSTALL = ['brew', 'install', '--cask', 'lanes-sh/lanes/lanes'] as const;
+
+/** Enough of the tail to explain an exit code, and no more. */
+const KEPT_STDERR = 4096;
+
+export interface DesktopFlags {
+  /** Print the URL instead of opening it. */
+  readonly print?: boolean | undefined;
+  /** Install without asking first. */
+  readonly yes?: boolean | undefined;
+}
+
+/** Injected in tests. Every field is the real thing when absent. */
+export interface DesktopDeps {
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly platform?: NodeJS.Platform | undefined;
+  /** Hand the URL to the OS. Resolves false when nothing claimed the scheme. */
+  readonly open?: ((url: string) => Promise<boolean>) | undefined;
+  /** Where `brew` is, or null. */
+  readonly brew?: (() => string | null) | undefined;
+  /** Run the install. Resolves an error tail, or null on success. */
+  readonly install?: ((brew: string) => Promise<string | null>) | undefined;
+  readonly interactive?: boolean | undefined;
+  readonly confirm?: ((question: string) => Promise<boolean>) | undefined;
+}
+
+/** The deep link, and the one env var that points it at another build. */
+export function settingsUrl(env: Record<string, string | undefined> = process.env): string {
+  // `||`, not `??`: an empty `LANES_LINK_APP_SCHEME` is someone unsetting it in
+  // a shell, and `://settings` is not a URL anything can open.
+  return `${env['LANES_LINK_APP_SCHEME'] || SCHEME}://settings?page=${PAGE}`;
+}
+
+/**
+ * Awaited, unlike `defaultOpenBrowser` in `oauth.ts`, and not the same function.
+ *
+ * That one is fire-and-forget because an OAuth consent has to outlive the
+ * command and `xdg-open` can block for as long as the browser it exec'd. This
+ * one runs on darwin only, where `open` hands off to LaunchServices and returns
+ * immediately — so the exit code is free, and it is the only thing that
+ * separates "the app is installed" from "nothing on this machine answers
+ * `lanes://`". Merging the two would give one of them the wrong behaviour.
+ */
+async function openUrl(url: string): Promise<boolean> {
+  try {
+    // An argument array, never a shell string: the URL carries a query.
+    const child = Bun.spawn(['open', url], { stdout: 'ignore', stderr: 'ignore' });
+    return (await child.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run the cask install, streaming it.
+ *
+ * Streamed rather than captured for the reason `runGcloud` is: a download of
+ * this size takes long enough that silence is indistinguishable from a hang.
+ * stderr is kept as well as shown, because "no such cask" and "the tap is
+ * unreachable" both exit 1 and need different answers.
+ */
+async function runInstall(brew: string): Promise<string | null> {
+  const child = Bun.spawn([brew, ...INSTALL.slice(1)], { stdout: 'inherit', stderr: 'pipe' });
+
+  let captured = '';
+  const decoder = new TextDecoder();
+  const reader = (child.stderr as ReadableStream<Uint8Array>).getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    const text = decoder.decode(value, { stream: true });
+    process.stderr.write(text);
+    captured = (captured + text).slice(-KEPT_STDERR);
+  }
+
+  return (await child.exited) === 0 ? null : captured.trim();
+}
+
+/**
+ * Install the app, having established that nothing answers the scheme.
+ *
+ * It asks first. Everything else this CLI installs is a file in the workspace
+ * it already owns; this puts an application on the machine, which is the
+ * largest side effect any command here has and the one a person is most
+ * entitled to decline. `--yes` is for the run that already decided, and a
+ * pipe with no terminal is refused rather than assumed — the same split
+ * `knowledge use` makes (ADR-041).
+ */
+async function install(flags: DesktopFlags, deps: DesktopDeps): Promise<void> {
+  const line = INSTALL.join(' ');
+  const brew = (deps.brew ?? (() => Bun.which('brew')))();
+
+  if (!brew) {
+    // Nothing to offer: this is the one path where the command cannot finish
+    // the job, so it hands over the whole of it.
+    throw new Error(
+      'The Lanes app is not installed, and neither is Homebrew.\n' +
+        `  With Homebrew: ${line}\n` +
+        '  Without it, download the app: https://lanes.sh/desktop',
+    );
+  }
+
+  print(warn('the Lanes app is not installed'));
+  print(style.dim(`  ${line}`));
+
+  const interactive = deps.interactive ?? isInteractive();
+  if (!flags.yes) {
+    if (!interactive) {
+      // A script cannot answer, and installing an application because nobody
+      // was there to say no is the wrong way to resolve that.
+      throw new Error(
+        `Nothing here can answer a prompt. Run the line above, or pass --yes to install it.`,
+      );
+    }
+    if (!(await (deps.confirm ?? ((q: string) => confirm(q)))('Install it now?'))) {
+      throw new Error(`Not installed. When you want it: ${line}`);
+    }
+  }
+
+  progress(style.dim('  installing, which takes a minute the first time…'));
+  const failed = await (deps.install ?? runInstall)(brew);
+  if (failed !== null) {
+    throw new Error(`${line} failed.\n${failed || '  It printed nothing that explains why.'}`);
+  }
+  print(ok('installed Lanes'));
+}
+
+export async function desktop(flags: DesktopFlags, deps: DesktopDeps = {}): Promise<void> {
+  const url = settingsUrl(deps.env ?? process.env);
+
+  if (flags.print) {
+    // Alone on stdout, so `open "$(lanes link desktop --print)"` works. Unlike
+    // the URL this printed when it opened a served page, it carries no token
+    // and is the same string every time.
+    print(url);
+    return;
+  }
+
+  const platform = deps.platform ?? process.platform;
+  if (platform !== 'darwin') {
+    // The app is macOS-only; this CLI is not. Saying so beats spawning
+    // `xdg-open` at a scheme no Linux machine has ever registered.
+    throw new Error(
+      `The Lanes desktop app is macOS-only, and this is ${platform}.\n` +
+        `  What it would have opened: ${url}\n` +
+        '  Everything that page does is a command here — start with: lanes link status',
+    );
+  }
+
+  const open = deps.open ?? openUrl;
+  if (await open(url)) {
+    print(ok(`opened ${style.bold('Lanes')} → Settings → Integrations → Lanes Link`));
+    // The one failure this command cannot see. An older Lanes is still
+    // registered for `lanes://`, so `open` exits 0, and it then ignores an
+    // action it does not know — the app comes forward on whatever page it was
+    // already on. Not printed after an install below, where the version is
+    // whatever the tap just handed over.
+    print(style.dim('  needs Lanes 0.48.0 or newer; an older app ignores the link.'));
+    return;
+  }
+
+  await install(flags, deps);
+
+  if (!(await open(url))) {
+    // Installed, and the scheme still unclaimed. LaunchServices registers a
+    // cask's bundle as it lands, but not always before the next process asks.
+    throw new Error(
+      'Lanes is installed, but nothing answers a lanes:// link yet.\n' +
+        '  macOS registers the scheme a moment after the app lands. Try again: lanes link desktop',
+    );
+  }
+
+  print(ok(`opened ${style.bold('Lanes')} → Settings → Integrations → Lanes Link`));
+}

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

@@ -1,53 +1,24 @@
 import { ownerPrincipal } from '#auth';
 import type { DiscoveredCapability } from '#connectivity';
-import { BROKERED } from '#connectivity/auth/index.ts';
 import { allowedConnections } from '#policy';
 import { toPolicyDocument } from '#registry';
 import { capabilityDiff, discoveryProbe } from '../../runtime/discovery.ts';
 import type { openRuntime } from '../../runtime.ts';
 
 /**
- * The two things `doctor` has to work out rather than simply read.
+ * The one thing `doctor` has to work out rather than simply read.
  *
  * Everything else in `inspect.ts` is a lookup — is the token there, does the
- * credential resolve, does the connection name a provider that exists — and
- * these two are analyses: one dates a credential from what the OAuth provider
- * stamped on it, and the other diffs what an upstream now offers against what
- * the endpoint is serving. They are the length in that file, and they are the
- * part that changes for reasons the gate order has nothing to do with.
- */
-
-/**
- * How old a stored OAuth credential is.
+ * connection name a provider that exists — and this is an analysis: it diffs
+ * what an upstream now offers against what the endpoint is serving. It is the
+ * length in that file, and it is the part that changes for reasons the gate
+ * order has nothing to do with.
  *
- * Derived from the `expires_at` the OAuth provider stamps when saving tokens.
- * Returns null for anything that is not a token blob — an app password has no
- * meaningful age, and guessing one would produce a confusing warning.
+ * `credentialAge` used to sit beside it and date a credential from the OAuth
+ * provider's stamp. It is gone: dating a credential answers "when did this last
+ * refresh", which is not the question anyone was asking. `operate/auth.ts`
+ * asks the real one by attempting the renewal.
  */
-export async function credentialAge(
-  credentials: { get(ref: string): Promise<string | null> },
-  ref: string,
-): Promise<{ days: number; brokered: boolean } | null> {
-  const raw = await credentials.get(ref);
-  if (!raw) return null;
-
-  try {
-    const parsed = JSON.parse(raw) as {
-      expires_at?: number;
-      expires_in?: number;
-      authorized_via?: string;
-    };
-    if (typeof parsed.expires_at !== 'number') return null;
-
-    const issued = parsed.expires_at - (parsed.expires_in ?? 3600) * 1000;
-    return {
-      days: Math.floor((Date.now() - issued) / 86_400_000),
-      brokered: parsed.authorized_via === BROKERED,
-    };
-  } catch {
-    return null;
-  }
-}
 
 /**
  * Capabilities the upstream has grown since you connected.