@lanes-sh/link 0.2.2 → 0.3.1

package/src/cli/commands/knowledge/migrate.ts

@@ -0,0 +1,180 @@
+import { ConfigError, KNOWLEDGE_LAYOUT, knowledgeRoot, type KnowledgeConfig } from '#profile';
+import type { BlobStore } from '#stores/blobs';
+import { commitFiles, type CommitFile } from '#deployments/adapters/github-commit.ts';
+import type { GithubRepository } from '#deployments/adapters/github-repo.ts';
+import { print, style } from '../../output.ts';
+
+/**
+ * Moving what is already stored, in whichever direction.
+ *
+ * Four steps, and the order is the whole of the safety: **read, commit, verify,
+ * then delete.** A migration that deleted first, or that trusted a write it had
+ * not read back, would leave an owner with no memory and a plausible-looking
+ * success line. Nothing here deletes anything until the destination has been
+ * re-read and found to hold every byte that was sent.
+ *
+ * The write is **one commit**, through the Git Data API rather than one
+ * Contents call per file. Two hundred commits each reading "Store memory
+ * a-note.md" is not a history anybody opens, and it is two hundred round trips
+ * against a limit this endpoint now shares.
+ */
+
+export interface Movable {
+  /** The key in the local store — `main/note.md`, or `triage/SKILL.md`. */
+  readonly key: string;
+  /** Where it goes in the repository. */
+  readonly path: string;
+  readonly area: 'memory' | 'skills';
+  readonly data: Uint8Array;
+}
+
+/**
+ * Everything this profile has stored locally, ready to move.
+ *
+ * Memory is read from the profile's blob root under the provider's own
+ * namespace rather than from the connections the config declares. A connection
+ * removed from the file leaves its entries behind, and those entries are still
+ * the owner's — leaving them on a disk that is about to stop being consulted is
+ * how they would be lost without anything saying so.
+ */
+export async function localContents(
+  storage: BlobStore,
+  skills: BlobStore,
+  knowledge: KnowledgeConfig,
+): Promise<Movable[]> {
+  const found: Movable[] = [];
+  const prefix = `${KNOWLEDGE_LAYOUT.memory}/`;
+
+  for (const entry of await storage.list(prefix)) {
+    const data = await storage.get(entry.key);
+    if (data === null) continue; // Listed then deleted; not worth failing over.
+    const key = entry.key.slice(prefix.length);
+    found.push({
+      key,
+      area: 'memory',
+      path: `${knowledgeRoot(knowledge, 'memory')}/${key}`,
+      data,
+    });
+  }
+
+  for (const entry of await skills.list()) {
+    const data = await skills.get(entry.key);
+    if (data === null) continue;
+    found.push({
+      key: entry.key,
+      area: 'skills',
+      path: `${knowledgeRoot(knowledge, 'skills')}/${entry.key}`,
+      data,
+    });
+  }
+
+  return found;
+}
+
+/** Paths the repository already holds that a migration would overwrite. */
+export async function collisions(
+  repository: GithubRepository,
+  movable: readonly Movable[],
+): Promise<string[]> {
+  const { entries } = await repository.entries();
+  return movable.filter((item) => entries.has(item.path)).map((item) => item.path);
+}
+
+/**
+ * Commit everything, then read it back before saying so.
+ *
+ * The verification is not ceremony. `commitFiles` reports what GitHub answered,
+ * and what this needs to know is what GitHub *stored* — which is a different
+ * question the moment a tree is built against a base that moved, or a blob
+ * upload succeeded and its tree entry did not. One extra request buys the right
+ * to delete the only other copy.
+ */
+export async function moveIn(
+  repository: GithubRepository,
+  movable: readonly Movable[],
+  message: string,
+): Promise<void> {
+  const files: CommitFile[] = movable.map((item) => ({ path: item.path, data: item.data }));
+  await commitFiles(repository, files, [], message);
+
+  const { entries } = await repository.entries();
+  const missing = movable.filter((item) => entries.get(item.path)?.size !== item.data.byteLength);
+
+  if (missing.length > 0) {
+    throw new ConfigError(
+      `The commit landed but ${missing.length} of ${movable.length} files did not read back ` +
+        `correctly (first: ${missing[0]?.path}). Nothing local has been deleted and the config ` +
+        'has not been changed, so this profile is exactly as it was. Try again.',
+    );
+  }
+}
+
+/** Remove what has been verified elsewhere. Never called before `moveIn`. */
+export async function removeLocal(
+  storage: BlobStore,
+  skills: BlobStore,
+  movable: readonly Movable[],
+): Promise<void> {
+  for (const item of movable) {
+    if (item.area === 'memory') await storage.delete(`${KNOWLEDGE_LAYOUT.memory}/${item.key}`);
+    else await skills.delete(item.key);
+  }
+}
+
+/**
+ * The other direction: everything in the repository, written back to the
+ * profile's own storage.
+ *
+ * Nothing is deleted from the repository. It is version control — the history
+ * holds every entry regardless of what the tip says — so removing the files
+ * would buy no privacy and would throw away the copy somebody may still want.
+ * The command says so rather than deciding it silently.
+ */
+export async function moveOut(
+  repository: GithubRepository,
+  knowledge: KnowledgeConfig,
+  storage: BlobStore,
+  skills: BlobStore,
+): Promise<{ memory: number; skills: number }> {
+  const { entries } = await repository.entries();
+  const roots = {
+    memory: `${knowledgeRoot(knowledge, 'memory')}/`,
+    skills: `${knowledgeRoot(knowledge, 'skills')}/`,
+  } as const;
+
+  const counts = { memory: 0, skills: 0 };
+
+  for (const entry of entries.values()) {
+    for (const area of ['memory', 'skills'] as const) {
+      if (!entry.path.startsWith(roots[area])) continue;
+
+      const key = entry.path.slice(roots[area].length);
+      const data = await repository.blob(entry.sha);
+
+      if (area === 'memory') await storage.put(`${KNOWLEDGE_LAYOUT.memory}/${key}`, data);
+      else await skills.put(key, data);
+
+      counts[area] += 1;
+    }
+  }
+
+  return counts;
+}
+
+/** `12 skills and 47 memory entries`, or whichever half of that is non-zero. */
+export function summarise(movable: readonly Movable[]): string {
+  const skills = movable.filter((item) => item.area === 'skills').length;
+  const memory = movable.length - skills;
+
+  const parts = [
+    ...(skills > 0 ? [`${skills} skill${skills === 1 ? '' : 's'}`] : []),
+    ...(memory > 0 ? [`${memory} memory entr${memory === 1 ? 'y' : 'ies'}`] : []),
+  ];
+  return parts.length === 0 ? 'nothing' : parts.join(' and ');
+}
+
+export function printMovable(movable: readonly Movable[]): void {
+  for (const item of movable) {
+    print(`  ${style.green('→')} ${style.dim(`${item.path}`)}`);
+  }
+}

package/src/cli/commands/knowledge/setup.ts

@@ -0,0 +1,144 @@
+import { ConfigError, type KnowledgeConfig } from '#profile';
+import type { SecretStore } from '#secrets';
+import { GithubRepository, type RepositoryFacts } from '#deployments/adapters/github-repo.ts';
+import type { FetchLike } from '#deployments/knowledge.ts';
+import { heading, print, style } from '../../output.ts';
+import { askSecret, isInteractive } from '../../prompt.ts';
+
+/**
+ * Getting a token, and finding out whether the repository is a sane place to
+ * put somebody's memory.
+ *
+ * Both halves happen **before** anything is written — no config edit, no
+ * commit, no local deletion. A half-switched profile is the worst outcome
+ * available here: the config says one thing, the bytes are somewhere else, and
+ * the failure looks like an empty memory rather than like an error.
+ */
+
+/**
+ * The steps, shown when there is no token yet.
+ *
+ * The same shape as `src/providers/github/index.ts`'s `setup.steps`, and
+ * deliberately not the same token. That one talks to GitHub's MCP server and
+ * needs Contents **read**; this one writes and needs Contents **write**. Two
+ * permissions, two lifetimes, and two things to revoke separately — revoking
+ * an MCP connection must not quietly empty somebody's memory.
+ */
+const STEPS = [
+  'Create a repository for this, or pick one you already have. **Make it private** — memory entries are yours.',
+  'Open https://github.com/settings/personal-access-tokens and choose "Generate new token".',
+  'Name it "Lanes Link knowledge" — the name is how you revoke this one later without touching your other tokens — and set an expiry you are willing to renew.',
+  'Resource owner: yourself, or the organisation that owns the repository. An organisation may require an owner to approve the token before it works.',
+  'Repository access: **only** the one repository this will store in.',
+  'Permissions: Contents (read and write), Metadata (read, added for you). Nothing else is needed.',
+  'Generate, then copy the token. GitHub shows it once, and it starts with github_pat_.',
+];
+
+export function printSetupSteps(repo: string): void {
+  heading('A token for this repository');
+  print(style.dim(`  Storing memory and skills in ${repo} needs a token that may write to it.`));
+  print('');
+  for (const [index, step] of STEPS.entries()) {
+    print(`  ${style.dim(`${index + 1}.`)} ${step.replace(/\*\*(.+?)\*\*/g, (_, inner: string) => style.bold(inner))}`);
+  }
+  print('');
+}
+
+/**
+ * The token this profile will use, asked for only when it is not already
+ * stored.
+ *
+ * Read from a terminal without echo, or from stdin when there is no terminal —
+ * never from argv, which lands in shell history and in `ps` output while the
+ * command runs. The same rule `lanes link secrets set` states and for the same
+ * reasons.
+ */
+export async function resolveToken(
+  secrets: SecretStore,
+  ref: string,
+  repo: string,
+  /** `--profile x --target y`, so the command in the refusal is one that runs. */
+  selection: string,
+  options: { replace?: boolean | undefined } = {},
+): Promise<string> {
+  if (!options.replace) {
+    const stored = await secrets.get(ref);
+    if (stored) return stored;
+  }
+
+  if (!process.stdin.isTTY) {
+    const piped = (await Bun.stdin.text()).trim();
+    if (piped) return piped;
+
+    throw new ConfigError(
+      `No token stored at "${ref}", and stdin is a terminal-less pipe with nothing in it.\n` +
+        `  printf %s "<github_pat_…>" | lanes link knowledge use github --repo ${repo}${selection}\n` +
+        '  Pass it this way rather than as an argument: an argument is in your shell history.',
+    );
+  }
+
+  if (!isInteractive()) {
+    throw new ConfigError(`No token stored at "${ref}", and there is nobody to ask for one.`);
+  }
+
+  printSetupSteps(repo);
+  const token = await askSecret('  GitHub personal access token');
+  if (!token) throw new ConfigError('No token given, so nothing was changed.');
+  return token;
+}
+
+/**
+ * What the repository is, and whether this is somewhere memory may go.
+ *
+ * Three refusals, and the first is the one worth the flag. A public repository
+ * is a working store and a catastrophic one: every entry the owner has written,
+ * and every procedure naming their accounts and their colleagues, world-readable
+ * and indexed. It is refused rather than warned about, because a warning during
+ * a migration is read after the migration.
+ */
+export async function probe(
+  repository: GithubRepository,
+  options: { allowPublic?: boolean | undefined },
+): Promise<{ facts: RepositoryFacts; viewer: string }> {
+  const viewer = await repository.viewer();
+  const facts = await repository.facts();
+
+  if (!facts.canPush) {
+    throw new ConfigError(
+      `The token can read ${facts.fullName} but not write to it. Memory and skills are written, ` +
+        'not just read, so this needs Contents: read and write.\n' +
+        '  Regenerate at https://github.com/settings/personal-access-tokens, then run this again.',
+    );
+  }
+
+  if (!facts.private && options.allowPublic !== true) {
+    throw new ConfigError(
+      `${facts.fullName} is public. Memory entries are the owner's own notes and a skill names ` +
+        'the accounts and people it operates on — a public repository publishes both, permanently ' +
+        'and searchably.\n' +
+        '  Make it private, or pass --allow-public if you genuinely mean to publish them.',
+    );
+  }
+
+  return { facts, viewer };
+}
+
+/**
+ * A client for a repository, built from what the command was told.
+ *
+ * The one construction point in this command, so `use github` and `use local`
+ * cannot end up talking to different clients — and so a test has one thing to
+ * hand a `fetch` to.
+ */
+export function repositoryFor(
+  knowledge: KnowledgeConfig,
+  token: string,
+  call?: FetchLike,
+): GithubRepository {
+  return new GithubRepository({
+    repo: knowledge.repo,
+    token,
+    ...(knowledge.branch !== undefined ? { branch: knowledge.branch } : {}),
+    ...(call ? { fetch: call } : {}),
+  });
+}

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,10 @@
+/**
+ * `lanes link knowledge` — which store holds this profile's memory and skills.
+ *
+ * A barrel, matching `owner.ts` and `operate.ts` beside it, so `main.ts` binds
+ * one path per noun rather than one per file. The command itself is three files
+ * under `knowledge/`: the token and the repository probe, the migration, and
+ * the grammar that puts them in order.
+ */
+
+export { knowledgeShow, knowledgeUse, type KnowledgeFlags } from './knowledge/index.ts';

package/src/cli/commands/mcp/harnesses.ts

@@ -25,6 +25,16 @@ export interface AddInput {
   readonly token: string;
   readonly tokenEnv: string;
   readonly scope: string;
+  /**
+   * Which selection this registration is for.
+   *
+   * Not part of the URL — a deployed endpoint serves every profile in its bucket
+   * and each call names one. It is here because the shell commands a harness is
+   * told to run afterwards do need it, and a `lanes link token show` without it
+   * substitutes to nothing.
+   */
+  readonly profile: string;
+  readonly target: string;
 }
 
 export interface Harness {
@@ -125,10 +135,14 @@ export const HARNESSES: readonly Harness[] = [
     // installs to both unchanged. Codex has no subagent directory, so it gets
     // the skill and not the scout — and `mcp add` says which it did.
     skills: () => join(CODEX_HOME(), 'skills'),
-    afterAdd: ({ tokenEnv }) => [
+    afterAdd: ({ tokenEnv, profile, target }) => [
       `Codex reads the token from $${tokenEnv} when it starts, so set it where Codex will see it:`,
       '',
-      `    export ${tokenEnv}="$(lanes link token show --raw)"`,
+      // Both flags, and this line is the reason they matter more here than
+      // anywhere else: an unresolvable substitution yields the empty string, the
+      // header becomes "Bearer ", and the only symptom is a 401 that reads as a
+      // bad token rather than a command that refused.
+      `    export ${tokenEnv}="$(lanes link token show --raw --profile ${profile} --target ${target})"`,
       '',
       'Add that to your shell profile. This is the better half of the bargain: the token never',
       'reaches ~/.codex/config.toml, and a "lanes link token rotate" is picked up on next launch',

package/src/cli/commands/mcp/register.ts

@@ -78,7 +78,15 @@ export async function mcpAdd(target: string | undefined, options: McpAddOptions)
     // registered loopback with the agent: a registration that reports success,
     // names the right server, and points at a port with nothing behind it.
     const url = await endpointUrl(runtime.config, runtime.target);
-    const input: AddInput = { name, url, token, tokenEnv, scope };
+    const input: AddInput = {
+      name,
+      url,
+      token,
+      tokenEnv,
+      scope,
+      profile: runtime.resolution.profile,
+      target: runtime.resolution.target,
+    };
 
     // Registering an endpoint that is down is legitimate — the harness stores
     // the address and connects on demand — but it is usually a mistake worth

package/src/cli/commands/mcp/stdio.ts

@@ -20,6 +20,27 @@ import { startStdioEndpoint } from '#server/endpoint.ts';
 export async function mcpStdio(
   flags: GlobalFlags & { only?: boolean | undefined },
 ): Promise<void> {
+  // Its own refusal, written for the only person who will read it: someone
+  // looking at a client's MCP log after the server "disconnected". There is no
+  // command line here to add a flag to — the client's config file is the only
+  // place that can carry one — so the message has to be a paste rather than an
+  // instruction, and the generic "pass --profile" would be advice with nowhere
+  // to follow it.
+  if (!flags.profile || !flags.target) {
+    printErr(
+      'lanes link mcp stdio needs --profile and --target in its "args".\n' +
+        '\n' +
+        '  This client spawns the endpoint, so its config file is the only place\n' +
+        '  that can say which profile and target it serves:\n' +
+        '\n' +
+        '    "lanes-link": {\n' +
+        '      "command": "/path/to/lanes",\n' +
+        '      "args": ["link","mcp","stdio","--profile","<name>","--target","<name>"]\n' +
+        '    }\n',
+    );
+    process.exit(1);
+  }
+
   const endpoint = await startStdioEndpoint({
     flags,
     ...(flags.only ? { only: true } : {}),

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

@@ -0,0 +1,107 @@
+import { deploymentIdentity, endpointHealth, localUrl } from '../../endpoint-url.ts';
+import { defaultOpenBrowser } from '../../oauth.ts';
+import { announce, ok, print, style, warn } from '../../output.ts';
+import {
+  ensureProfileToken,
+  openRuntime,
+  resolveProfile,
+  type GlobalFlags,
+} from '../../runtime.ts';
+
+/**
+ * `lanes link dashboard` — open the page this endpoint serves.
+ *
+ * The command exists because the page cannot be reached without it. A browser
+ * navigating to `/dashboard` carries no `Authorization` header, so the token has
+ * to arrive some other way, and the only place it already exists is the
+ * credential store this command can read. It puts it in the URL once; the
+ * endpoint exchanges it for a session cookie and redirects to a URL without it.
+ *
+ * Local only, deliberately. See `#server/dashboard.ts` — ADR-018 leaves a
+ * deployed instance with no door a person at a browser can come through, and a
+ * command that opened a loopback URL for a target that is not there would be
+ * reporting success for a page nobody can load.
+ */
+
+export interface DashboardFlags extends GlobalFlags {
+  /** Print the URL instead of opening it. */
+  readonly print?: boolean | undefined;
+}
+
+export async function dashboard(flags: DashboardFlags): Promise<void> {
+  // `resolveProfile` rather than `openRuntime`, and the order is the point.
+  // Opening a runtime opens that target's adapters, so a deployed target sends
+  // this command to Secret Manager and a bucket before it can say the one thing
+  // it needs to — that the dashboard is not there. The refusal below would
+  // still be correct and nobody would ever read it, because a storage 403
+  // arrives first. This is the seam `runtime.ts` documents `deploy` and
+  // `secrets push` stopping at, for the same reason.
+  const { resolution, config, target } = await resolveProfile(flags);
+  announce(resolution);
+
+  const deployed = deploymentIdentity(config.targets[target]?.deploy);
+  if (deployed) {
+    throw new Error(
+      `Target "${target}" is deployed to ${deployed.platform}, and the dashboard is served only ` +
+        'by a local endpoint — a browser carries no bearer token, and Cloud Run\'s own gate ' +
+        'admits only a Google-signed identity token it cannot mint either (ADR-018).\n' +
+        `What a deployed target can answer: ` +
+        `lanes link status --profile ${resolution.profile} --target ${target}`,
+    );
+  }
+
+  const runtime = await openRuntime(flags);
+
+  try {
+    const { token } = await ensureProfileToken(runtime.credentials, runtime.config.auth.token_ref);
+
+    const url = new URL(localUrl(runtime.config));
+    url.pathname = '/dashboard';
+    url.searchParams.set('k', token);
+    // Named rather than left to the endpoint's primary, so the page opens on
+    // the profile this command resolved and printed above.
+    url.searchParams.set('profile', runtime.resolution.profile);
+
+    // The page is served by a running endpoint or by nothing. Saying so here
+    // beats opening a browser at a connection error.
+    const live = await endpointHealth(localUrl(runtime.config), token);
+    if (!live) {
+      // Both flags on both lines. They read as correct without them only
+      // because they were written while a missing one still resolved to the
+      // workspace default; with nothing to fall back on (ADR-037) each is a
+      // paste that refuses, and this one is printed at the moment somebody is
+      // least able to guess what it wanted.
+      const where = `--profile ${runtime.resolution.profile} --target ${target}`;
+
+      print(warn(`nothing is serving this port — run: lanes link start ${where}`));
+      print(style.dim(`  then: lanes link dashboard ${where}`));
+      return;
+    }
+
+    if (!live.profiles.includes(runtime.resolution.profile)) {
+      // `start --only` serves one profile. The URL would 404 on the rest, which
+      // is honest but unhelpful without being told why.
+      print(
+        warn(
+          `the endpoint on this port serves ${live.profiles.join(', ')} — ` +
+            `not "${runtime.resolution.profile}"`,
+        ),
+      );
+      return;
+    }
+
+    if (flags.print) {
+      // Printed, not opened: for a terminal on a machine with no browser, and
+      // for anyone who would rather see what they are about to open. It carries
+      // the token, which is why it is behind a flag rather than always shown.
+      print(url.href);
+      return;
+    }
+
+    defaultOpenBrowser(url.href);
+    print(ok(`opened ${style.bold(`${url.origin}/dashboard`)}`));
+    print(style.dim('  the link carries a one-time key; the page swaps it for a session cookie.'));
+  } finally {
+    await runtime.close();
+  }
+}

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

@@ -0,0 +1,151 @@
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+ *
+ * This is what replaced pinning an allow line per tool. `connect` writes
+ * `provider.*`, which is readable and which a vendor can quietly widen by
+ * shipping a new tool — so the widening has to be *visible* somewhere, and
+ * doctor is where you look when you want to know what changed.
+ *
+ * Compared against the discovery cache rather than against config, because the
+ * cache is what the running server actually serves. Failures are reported and
+ * skipped: an upstream being down is not a reason for doctor to fail, and it is
+ * already obvious from every other check.
+ *
+ * This used to open `if (kind !== 'mcp') continue`, which meant it watched the
+ * one connector kind whose capabilities this repository does not ship and
+ * ignored the two it does. Drive gained three operations in a commit and the
+ * endpoint served six for as long as the operator did not re-authorise; the
+ * check written to make exactly that visible never ran. `http` is no longer
+ * listed here because it no longer can drift — `runtime/discovery.ts` re-derives
+ * it at startup — so what is left is the kinds that genuinely still cache.
+ */
+export async function reportCapabilityDrift(
+  runtime: Awaited<ReturnType<typeof openRuntime>>,
+  say: (message: string) => void,
+): Promise<void> {
+  const policy = toPolicyDocument(runtime.config);
+  const principal = ownerPrincipal(runtime.config.instance.profile).id;
+
+  for (const entry of runtime.registry.list()) {
+    const connection = runtime.config.connections.find((c) => c.provider === entry.manifest.id);
+    if (!connection) continue;
+
+    const connector = runtime.connectorFor(entry.manifest.id, connection.id);
+    const probe = discoveryProbe(entry.manifest, connector);
+    // Re-derived every startup, so what is served is what is shipped. Probing
+    // it here would only ever compare a value against itself.
+    if (!probe || probe.cost === 'offline') continue;
+
+    const cached = runtime.registry.discovered(entry.manifest.id) ?? [];
+
+    let live: readonly DiscoveredCapability[];
+    try {
+      live = await probe.run();
+    } catch {
+      continue;
+    }
+
+    // A provider that was never discovered serves nothing at all, which reads
+    // from the outside like the provider being broken. Skipping it silently is
+    // how that stays a mystery.
+    if (cached.length === 0) {
+      say(
+        `${entry.manifest.name} has never been discovered, so none of its ${live.length} ` +
+          `capability(ies) are served — run: lanes link connect ${entry.manifest.id}`,
+      );
+      continue;
+    }
+
+    const diff = capabilityDiff(cached, live);
+
+    if (diff.added.length > 0) {
+      // Through the same `allowedConnections` the dispatcher enforces with,
+      // rather than reading `policy.allow` directly. The predicate this replaced
+      // ignored its own `name` argument, so the answer was all-or-nothing, and
+      // it never consulted `deny` — telling an operator their policy covered a
+      // capability they had explicitly withheld.
+      const reachable = diff.added.filter(
+        (name) =>
+          allowedConnections(
+            `${entry.manifest.id}.${name}`,
+            [`${entry.manifest.id}.${connection.id}`],
+            principal,
+            policy,
+          ).length > 0,
+      );
+
+      say(
+        `${entry.manifest.name} has ${diff.added.length} new capability(ies) since you connected: ` +
+          `${diff.added.slice(0, 5).join(', ')}${diff.added.length > 5 ? ', …' : ''}` +
+          (reachable.length > 0
+            ? `\n      Your policy covers ${reachable.length} of them — lanes link policy deny ${entry.manifest.id}.<name> to withhold one.`
+            : ''),
+      );
+    }
+
+    if (diff.removed.length > 0) {
+      say(`${entry.manifest.name} no longer offers: ${diff.removed.slice(0, 5).join(', ')}`);
+    }
+
+    // The case ADR-017 said `plan` structurally could not report: a schema or a
+    // description moved, the name did not, and the endpoint is serving the old
+    // shape until it restarts.
+    if (diff.changed.length > 0) {
+      say(
+        `${entry.manifest.name} changed the shape of: ${diff.changed.slice(0, 5).join(', ')}` +
+          `\n      Run: lanes link connect ${entry.manifest.id}, then restart the endpoint.`,
+      );
+    }
+  }
+}