@lanes-sh/link 0.2.0 → 0.2.2

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

@@ -185,3 +185,20 @@ URL and a token.
 user the command rather than backgrounding it silently on their behalf.
 Registration works while it is down — the harness simply cannot reach it yet,
 and the first symptom is a failed call much later.
+
+## When a call does not land
+
+Different from the above, and more common: calls were working, and then one does
+not go through. A deployed endpoint is one machine its owner runs, and a client
+can report it unreachable while it is up — sometimes without sending anything at
+all, which is why the endpoint's own log can show no trace of the attempt.
+
+Treat it as ordinary. **Say the call did not land, and stop there.** It is not a
+fault to diagnose, and it is not authorization that has lapsed — do not tell them
+to sign in again unless the endpoint itself said so.
+
+**Do not redo what already succeeded.** A call that returned is done, and the
+next one failing does not undo it. Re-deriving a finished answer, or rewriting a
+memory entry that was already written, is the expensive mistake here and the one
+that actually gets made. Say which parts landed, which did not, and offer to
+retry the rest.

package/package.json

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

package/src/auth/index.ts

@@ -212,9 +212,11 @@ export {
   challenge,
   protectedResourceMetadata,
   MCP_SCOPE,
+  type ChallengeError,
   type ResourceIdentity,
 } from './oauth/metadata.ts';
-export { OAuthServer, matchesRegistered, pkceChallengeFor, type AuthorizeRequest, type OAuthResult } from './oauth/server.ts';
+export { OAuthServer, pkceChallengeFor, type AuthorizeRequest, type OAuthResult } from './oauth/server.ts';
+export { matchesRegistered } from './oauth/redirects.ts';
 export { OAuthStore, hashToken, randomToken } from './oauth/store.ts';
 export { OidcVerifier, type OidcVerifierOptions, type VerifiedSubject } from './oidc.ts';
 export { IssuedTokenAuthenticator, OidcAuthenticator } from './remote.ts';

package/src/auth/oauth/metadata.ts

@@ -22,21 +22,62 @@ export interface ResourceIdentity {
 }
 
 /**
- * One scope, and it is not a permission axis.
+ * Two scopes, and neither is a permission axis.
  *
  * What a caller may do is decided by the profile's policy, per capability, per
  * call, and recorded in the audit log. A second permission system expressed as
  * scopes could only either duplicate that or disagree with it, and a client
- * cannot be trusted to ask for less than it wants anyway. The scope exists
- * because the protocol has a slot for one.
+ * cannot be trusted to ask for less than it wants anyway. The scopes exist
+ * because the protocol has a slot for them, and because a client reads that
+ * slot to decide what this endpoint will do for it.
  */
 export const MCP_SCOPE = 'mcp';
 
+/**
+ * OIDC Core §11's name for "issue me a refresh token", and the reason this
+ * endpoint stopped sending its owner back to a browser.
+ *
+ * A refresh token has always been issued here, unconditionally. What was missing
+ * was saying so. A client's requested scope defaults to whatever the *resource*
+ * document lists, and the reference MCP client appends `offline_access` only
+ * when the *authorization server* document advertises it:
+ *
+ * ```js
+ * let effectiveScope = requestedScope || resourceMetadata?.scopes_supported?.join(" ") || …
+ * if (effectiveScope && authServerMetadata?.scopes_supported?.includes("offline_access") && …)
+ *   effectiveScope = `${effectiveScope} offline_access`;
+ * ```
+ *
+ * So both documents matter and they matter differently. Advertising it in
+ * neither left a client no grounds to request, persist, or use the refresh
+ * token it was being handed — and a client with no grounds reconnects, which
+ * means its owner approving in a browser.
+ */
+export const OFFLINE_ACCESS_SCOPE = 'offline_access';
+
+/** Everything grantable here. A request for anything else is narrowed, not refused. */
+export const SUPPORTED_SCOPES = [MCP_SCOPE, OFFLINE_ACCESS_SCOPE] as const;
+
+/**
+ * The grantable part of what was asked for.
+ *
+ * Empty means the request named nothing we recognise, and the caller falls back
+ * to `MCP_SCOPE` — refusing with `invalid_scope` would turn an unknown token in
+ * a client's default string into a connector that cannot be added at all, and
+ * scope is not the thing protecting anything here.
+ */
+export function grantableScope(requested: string | null | undefined): string {
+  const asked = new Set((requested ?? '').split(/\s+/).filter(Boolean));
+  return SUPPORTED_SCOPES.filter((scope) => asked.has(scope)).join(' ');
+}
+
 export function protectedResourceMetadata(identity: ResourceIdentity): Record<string, unknown> {
   return {
     resource: identity.resource,
     authorization_servers: [identity.issuer],
-    scopes_supported: [MCP_SCOPE],
+    // Where a client's *default* requested scope comes from, so this is the
+    // list that decides what an untouched connector asks for.
+    scopes_supported: [...SUPPORTED_SCOPES],
     bearer_methods_supported: ['header'],
   };
 }
@@ -47,7 +88,9 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
     authorization_endpoint: `${origin}/authorize`,
     token_endpoint: `${origin}/token`,
     registration_endpoint: `${origin}/register`,
-    scopes_supported: [MCP_SCOPE],
+    // And this is the list that gates whether `offline_access` is appended at
+    // all. Both documents have to carry it; neither one alone is enough.
+    scopes_supported: [...SUPPORTED_SCOPES],
     response_types_supported: ['code'],
     grant_types_supported: ['authorization_code', 'refresh_token'],
     // Advertised because a spec-compliant client checks for it before starting
@@ -60,6 +103,27 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
   };
 }
 
+/**
+ * Why a credential was refused, in RFC 6750 §3.1's vocabulary.
+ *
+ * There is one code worth sending and it carries the whole distinction a client
+ * needs: `invalid_token` says the credential was *rejected*, where an otherwise
+ * identical challenge says only that authorization is required. A client that
+ * cannot tell those apart cannot tell "refresh — you hold a refresh token for
+ * this" from "start a new authorization", and the safe-looking guess is the
+ * second, which means the owner approving in a browser for a credential a
+ * silent refresh would have replaced.
+ *
+ * Deliberately absent when nothing was presented. RFC 6750 §3: a resource
+ * server SHOULD NOT include an error code where the request carried no
+ * authentication information — and sending one would set a client refreshing a
+ * credential it does not have.
+ */
+export interface ChallengeError {
+  readonly code: 'invalid_token';
+  readonly description: string;
+}
+
 /**
  * The `WWW-Authenticate` value on a 401.
  *
@@ -67,9 +131,19 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
  * has to guess the document's location by probing well-known paths, which costs
  * round trips and fails entirely on a host that does not serve them. Clients do
  * not honour this header on a `200`, so the status has to be right too.
+ *
+ * It stays on the header even when a token was rejected. A client that decides
+ * to authorize after all — because the refresh was refused too — must not have
+ * to go and find the document a second time.
  */
-export function challenge(metadataUrl: string | null): string {
-  return metadataUrl
-    ? `Bearer realm="lanes-link", resource_metadata="${metadataUrl}"`
-    : 'Bearer realm="lanes-link"';
+export function challenge(metadataUrl: string | null, error?: ChallengeError): string {
+  // Every value is a quoted-string, so none may contain a quote. Both of these
+  // are constants in this repository and the types keep them that way.
+  const parts = [
+    'realm="lanes-link"',
+    ...(error ? [`error="${error.code}"`, `error_description="${error.description}"`] : []),
+    ...(metadataUrl ? [`resource_metadata="${metadataUrl}"`] : []),
+  ];
+
+  return `Bearer ${parts.join(', ')}`;
 }

package/src/auth/oauth/redirects.ts

@@ -0,0 +1,70 @@
+/**
+ * Which redirect URIs this server will send an authorization code to.
+ *
+ * Its own file because it is its own subject. `server.ts` is the flow as
+ * decisions — a code exchanged, a token rotated, an owner approving — and none
+ * of it is about URL shapes. Both halves stayed inside the file-size budget
+ * until they did not, and the budget exists to point at exactly this: it was
+ * not too long, it was two things.
+ *
+ * Nothing here consults configuration. What a client registered is checked
+ * against what it now presents, and the rules are RFC 8252's rather than ours.
+ */
+
+/**
+ * https, or loopback for a native client.
+ *
+ * A native client cannot receive an https redirect, so RFC 8252 has it listen
+ * on a loopback port instead. Everything else is refused: a redirect to `http://`
+ * on a routable host puts an authorization code on the wire in clear text.
+ */
+export function isSafeRedirect(uri: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return false;
+  }
+
+  if (parsed.protocol === 'https:') return true;
+  return parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname);
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]' || hostname === 'localhost';
+}
+
+/**
+ * Exact match, except for the port of a loopback URI.
+ *
+ * RFC 8252 §7.3 requires ignoring the port for the IP-literal form, because a
+ * native client binds an ephemeral one it cannot know at registration time.
+ * Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback`
+ * and then listens on whatever port it got, so the same allowance has to cover
+ * `localhost` or it never connects.
+ */
+export function matchesRegistered(candidate: string, registered: readonly string[]): boolean {
+  if (registered.includes(candidate)) return true;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return false;
+  }
+  if (!isLoopbackHost(parsed.hostname)) return false;
+
+  return registered.some((uri) => {
+    try {
+      const other = new URL(uri);
+      return (
+        isLoopbackHost(other.hostname) &&
+        other.protocol === parsed.protocol &&
+        other.hostname === parsed.hostname &&
+        other.pathname === parsed.pathname
+      );
+    } catch {
+      return false;
+    }
+  });
+}

package/src/auth/oauth/server.ts

@@ -1,4 +1,5 @@
-import { MCP_SCOPE } from './metadata.ts';
+import { grantableScope, MCP_SCOPE } from './metadata.ts';
+import { isSafeRedirect, matchesRegistered } from './redirects.ts';
 import {
   hashToken,
   randomToken,
@@ -26,6 +27,21 @@ import {
 const CODE_TTL_MS = 60_000;
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
+/**
+ * How long a spent refresh token still answers.
+ *
+ * A client whose refresh succeeded but whose *response* was lost holds a token
+ * the server has already spent, and retrying with it is the only move it has.
+ * Without a window that retry is `invalid_grant`, and the reference MCP client
+ * rethrows every `OAuthError` but `server_error` rather than recovering — so
+ * the connector dies and its owner is sent to a browser, over a network blip.
+ *
+ * Thirty seconds is the band Auth0's reuse interval (0–60 s) and Okta's grace
+ * period occupy. What it costs: a captured refresh token keeps working for up
+ * to this long after the real client next rotates it.
+ */
+const REFRESH_REUSE_MS = 30_000;
+
 export type OAuthResult =
   | { readonly kind: 'json'; readonly status: number; readonly body: unknown }
   | { readonly kind: 'redirect'; readonly location: string }
@@ -61,6 +77,9 @@ export interface OAuthServerOptions {
   /** Proof of being the owner. The same token the endpoint already accepts. */
   readonly verifyOwner: (presented: string) => Promise<boolean>;
   readonly accessTokenTtlMs: number;
+  /** Where a replayed refresh token is recorded. Structural, because this layer
+   * may not import `#connectivity`; the endpoint's own logger satisfies it. */
+  readonly log?: { warn(message: string, detail?: Record<string, unknown>): void };
   readonly now?: () => number;
 }
 
@@ -163,7 +182,11 @@ export class OAuthServer {
         redirectUri,
         codeChallenge: challenge,
         state: params.get('state') ?? undefined,
-        scope: params.get('scope') || MCP_SCOPE,
+        // The grantable part of what was asked for, not the request verbatim.
+        // Echoing it back through `#issue` was granting by echo, which was inert
+        // while `mcp` was the only scope and stops being inert now that there is
+        // a second one that means something.
+        scope: grantableScope(params.get('scope')) || MCP_SCOPE,
         resource: params.get('resource') ?? undefined,
       },
     };
@@ -198,7 +221,12 @@ export class OAuthServer {
       clientId: request.clientId,
       redirectUri: request.redirectUri,
       codeChallenge: request.codeChallenge,
-      scope: request.scope,
+      // Narrowed here as well as in `authorize`, and this is the one that
+      // matters: the request arrives back through hidden form fields, so a
+      // caller can post any scope it likes straight to this endpoint. Nothing
+      // round-tripped through the form is trusted — the client and the redirect
+      // URI are re-checked above for the same reason.
+      scope: grantableScope(request.scope) || MCP_SCOPE,
       ...(request.resource ? { resource: request.resource } : {}),
       expiresAt: this.#now() + CODE_TTL_MS,
     };
@@ -252,15 +280,25 @@ export class OAuthServer {
       return invalid('invalid_grant', 'That refresh token is unknown or expired.');
     }
 
-    // A spent token presented again is the one signal that it has been copied.
-    // Rotation alone does not answer it: whoever refreshes first walks away
-    // with a live pair, and rejecting only the token in hand leaves that pair
-    // working while the other party — usually the real client — is locked out.
-    // So the whole chain goes. A client retrying a response it never saw and a
-    // thief replaying are indistinguishable from here, and re-authorising is
-    // the cheaper of the two mistakes.
+    // A spent token presented again used to take its whole family with it, on
+    // the reading that a replay is a theft. Against a real connector that was
+    // wrong twice over, and ADR-035 has the evidence. Two answers replace it,
+    // and the tombstone's age is what tells them apart.
     if (record.kind === 'consumed') {
-      await this.#options.store.revokeFamily(record.family);
+      // Inside the window it is a retry of a request already answered, and the
+      // client is owed the answer rather than a dead connector. Not re-consumed:
+      // a client retrying twice is still retrying.
+      const spentAt = record.consumedAt;
+      if (spentAt !== undefined && this.#now() - spentAt <= REFRESH_REUSE_MS) {
+        return this.#issue(record.clientId, record.scope, randomToken('llr'), record.family);
+      }
+
+      // Outside it, refused on its own — and the family survives, which is the
+      // half that was taking live sessions down with it.
+      this.#options.log?.warn('refresh token replayed', {
+        clientId: record.clientId,
+        family: record.family,
+      });
       return invalid('invalid_grant', 'That refresh token has already been used.');
     }
 
@@ -324,62 +362,4 @@ function invalid(error: string, description: string): OAuthResult {
   return { kind: 'json', status: 400, body: { error, error_description: description } };
 }
 
-/**
- * https, or loopback for a native client.
- *
- * A native client cannot receive an https redirect, so RFC 8252 has it listen
- * on a loopback port instead. Everything else is refused: a redirect to `http://`
- * on a routable host puts an authorization code on the wire in clear text.
- */
-function isSafeRedirect(uri: string): boolean {
-  let parsed: URL;
-  try {
-    parsed = new URL(uri);
-  } catch {
-    return false;
-  }
-
-  if (parsed.protocol === 'https:') return true;
-  return parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname);
-}
-
-function isLoopbackHost(hostname: string): boolean {
-  return hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]' || hostname === 'localhost';
-}
-
-/**
- * Exact match, except for the port of a loopback URI.
- *
- * RFC 8252 §7.3 requires ignoring the port for the IP-literal form, because a
- * native client binds an ephemeral one it cannot know at registration time.
- * Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback`
- * and then listens on whatever port it got, so the same allowance has to cover
- * `localhost` or it never connects.
- */
-export function matchesRegistered(candidate: string, registered: readonly string[]): boolean {
-  if (registered.includes(candidate)) return true;
-
-  let parsed: URL;
-  try {
-    parsed = new URL(candidate);
-  } catch {
-    return false;
-  }
-  if (!isLoopbackHost(parsed.hostname)) return false;
-
-  return registered.some((uri) => {
-    try {
-      const other = new URL(uri);
-      return (
-        isLoopbackHost(other.hostname) &&
-        other.protocol === parsed.protocol &&
-        other.hostname === parsed.hostname &&
-        other.pathname === parsed.pathname
-      );
-    } catch {
-      return false;
-    }
-  });
-}
-
 export { hashToken };

package/src/auth/oauth/store.ts

@@ -53,6 +53,9 @@ export interface AuthorizationCode {
  * it arrived. A tombstone keeps the family id and nothing else useful, and it
  * opens no more than a deleted row does — every check that admits a credential
  * tests for `access` by name.
+ *
+ * What is *done* about a detected replay changed in ADR-035: the presented
+ * token is refused and the replay logged, rather than the family revoked.
  */
 export type TokenKind = 'access' | 'refresh' | 'consumed';
 
@@ -71,6 +74,15 @@ export interface IssuedToken {
    * the theft and the retry look identical from here.
    */
   readonly family: string;
+  /**
+   * When this token was spent, on a `consumed` tombstone and nowhere else.
+   *
+   * What makes the reuse interval possible: without it a spent token carries no
+   * hint whether it was spent a second ago or a month ago, and those are a retry
+   * and a replay. A tombstone written before this existed has no `consumedAt`
+   * and is read as the older one, which is the safe direction.
+   */
+  readonly consumedAt?: number;
 }
 
 export function hashToken(value: string): string {
@@ -182,16 +194,18 @@ export class OAuthStore {
     const key = hashToken(token);
     const record = await this.#read<IssuedToken>(TOKENS, key);
     if (!record) return;
-    await this.#state.set(TOKENS, key, JSON.stringify({ ...record, kind: 'consumed' }));
+    const spent: IssuedToken = { ...record, kind: 'consumed', consumedAt: this.#now() };
+    await this.#state.set(TOKENS, key, JSON.stringify(spent));
   }
 
   /**
    * Drop every token in a refresh family.
    *
-   * Called when a rotated-away refresh token is presented again, which is
-   * either a client retrying or a thief replaying. Both are answered the same
-   * way, because from here they are indistinguishable and the safe reading is
-   * the expensive one.
+   * A replay no longer calls this, and a replay was the only thing that did —
+   * see `OAuthServer.#refresh` and ADR-035. Kept because it is the shape a
+   * deliberate revocation takes: one authorization's whole chain, dropped on
+   * purpose. Nothing in `src/` reaches it today, so read a call site as new
+   * policy rather than as the old one returning.
    */
   async revokeFamily(family: string): Promise<void> {
     for (const key of await this.#state.keys(TOKENS)) {

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

@@ -10,6 +10,7 @@ import {
   toPolicyDocument,
 } from '#registry';
 import { announce, emit, fail, ok, print, warn } from '../../output.ts';
+import { staleNudge } from '../../release.ts';
 import { capabilityDiff, discoveryProbe } from '../../runtime/discovery.ts';
 import { openRuntime, resolveProfile, type GlobalFlags } from '../../runtime.ts';
 
@@ -189,6 +190,12 @@ export async function doctor(flags: DoctorFlags): Promise<void> {
       });
     }
 
+    // Every finding above is about this profile; this one is about the binary
+    // reading it. Silent when the registry cannot be reached — `doctor` is
+    // expected to work on a plane, and "could not check" is not a finding.
+    const stale = await staleNudge();
+    if (stale !== null) warnings.push({ kind: 'stale_release', message: stale });
+
     await reportCapabilityDrift(runtime, (message) =>
       warnings.push({ kind: 'capability_drift', message }),
     );

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

@@ -1,6 +1,7 @@
 import { startEndpoint } from '#server/endpoint.ts';
 import { streamLogger } from '#server/logging.ts';
 import { announce, ok, print, style, warn } from '../../output.ts';
+import { staleNudge } from '../../release.ts';
 import { resolveProfile, type GlobalFlags } from '../../runtime.ts';
 
 /** `lanes link start` — reconcile, then serve every profile on one endpoint. */
@@ -41,6 +42,12 @@ export async function start(
 
   print(ok(`serving ${style.bold(endpoint.url)}`));
   print(style.dim(`      profiles: ${endpoint.profiles.join(', ')}`));
+
+  // Last, not first: the endpoint is what someone ran this for, and a version
+  // note in front of it would be the first thing they read and the least useful.
+  const stale = await staleNudge();
+  if (stale !== null) print(warn(stale));
+
   print(style.dim('Ctrl-C to stop.'));
 
   const shutdown = async (): Promise<void> => {

package/src/cli/commands/update.ts

@@ -0,0 +1,255 @@
+import { homedir } from 'node:os';
+import { join, sep } from 'node:path';
+import { installRoot } from '#profile';
+import { emit, fail, ok, print, printErr, progress, style, warn } from '../output.ts';
+import { PACKAGE, release, type ReleaseState } from '../release.ts';
+import { version } from '../version.ts';
+
+/**
+ * `lanes link update` — install the newer release, or say why it will not.
+ *
+ * There is no build step and no compiled artifact, so updating means exactly
+ * one thing: replace the installed package directory with a newer tarball from
+ * the registry. `bin/lanes` resolves its own symlink chain and execs Bun on the
+ * `src/` inside that directory, so the shipped source *is* the running code and
+ * the symlink on the PATH never has to move.
+ *
+ * Bun is the only installer this drives. `bun install -g @lanes-sh/link` is the
+ * only install documented, `engines.bun` requires it, and the shim refuses to
+ * run without it — so inferring a package manager would be machinery serving a
+ * case nobody is told to create. The case that does exist is handled below
+ * rather than ignored: an `npm i -g` install updated with Bun gets a second
+ * copy somewhere else on the PATH, which this detects and reports instead of
+ * doing quietly.
+ *
+ * Nothing here is control plane — it touches the install, not a profile — so it
+ * resolves no profile and no target, and is the second command after `version`
+ * that prints no `announce` line.
+ */
+
+export interface UpdateFlags {
+  /** Report and exit without installing anything. */
+  readonly check?: boolean | undefined;
+  readonly json?: boolean | undefined;
+}
+
+/**
+ * What `update` would do, and why.
+ *
+ * `'checkout'` is a refusal: `bun link` puts a checkout on the same PATH entry
+ * a published install would occupy, so installing from the registry there would
+ * leave two copies of this CLI and no indication of which one answers. `git
+ * pull` is the update in a checkout, and saying so is more useful than doing
+ * something surprising.
+ */
+export type UpdateAction = 'install' | 'current' | 'ahead' | 'checkout' | 'unknown';
+
+export interface UpdateDecision {
+  readonly action: UpdateAction;
+  /** The argv to run, or `null` when nothing should be run. */
+  readonly install: readonly string[] | null;
+  readonly message: string;
+  /** Something true and unwelcome about this install, if there is anything. */
+  readonly warning: string | null;
+}
+
+export interface UpdateInput {
+  readonly installed: string;
+  readonly latest: string | null;
+  readonly state: ReleaseState;
+  /** Where this CLI is installed — `installRoot()`, not the workspace. */
+  readonly root: string;
+  /** Where Bun keeps global installs, so a copy landing elsewhere is visible. */
+  readonly bunGlobal: string;
+}
+
+/**
+ * The whole decision, as a function of five strings.
+ *
+ * Split from the spawn because the alternative is a command whose only test is
+ * one that replaces the copy of this CLI on the machine running the suite. Every
+ * branch below is reachable from `update.test.ts` with no network and no
+ * subprocess — including the stale branch, which the checkout this is written in
+ * can never reach on its own, being by definition the newest thing there is.
+ */
+export function updatePlan(input: UpdateInput): UpdateDecision {
+  const { installed, latest, state, root, bunGlobal } = input;
+
+  // A published install lives under `node_modules`; a checkout does not. Cheaper
+  // and steadier than looking for `.git`, which a tarball could carry and a
+  // shallow export could lack.
+  const published = root.split(sep).includes('node_modules');
+
+  if (!published) {
+    return {
+      action: 'checkout',
+      install: null,
+      message: `${root} is a checkout, not an install — git pull is the update here`,
+      warning: null,
+    };
+  }
+
+  if (state === 'unknown') {
+    return {
+      action: 'unknown',
+      install: null,
+      message:
+        latest === null
+          ? `could not reach the registry — ${installed} is installed`
+          : `cannot compare ${installed} against ${latest}`,
+      warning: null,
+    };
+  }
+
+  if (state === 'ahead') {
+    return {
+      action: 'ahead',
+      install: null,
+      message: `${installed} is installed, ahead of the published ${latest ?? 'release'}`,
+      warning: null,
+    };
+  }
+
+  if (state === 'current') {
+    return { action: 'current', install: null, message: `${installed} is current`, warning: null };
+  }
+
+  // Installed by npm, updated by Bun: `bun install -g` writes into its own
+  // global prefix and leaves the npm copy where it is, so both are on the PATH
+  // and its order decides which one answers. Worth saying before, not after.
+  const elsewhere = !root.startsWith(bunGlobal + sep);
+
+  return {
+    action: 'install',
+    install: ['install', '-g', PACKAGE],
+    message: `${installed} installed, ${latest} available`,
+    warning: elsewhere
+      ? `this copy is at ${root}, which is not under ${bunGlobal} — ` +
+        'Bun will install a second copy there rather than replace this one, ' +
+        'and your PATH order decides which one answers'
+      : null,
+  };
+}
+
+/** Where Bun keeps global installs, honouring `BUN_INSTALL`. */
+export function bunGlobalRoot(env: Record<string, string | undefined> = process.env): string {
+  return join(env['BUN_INSTALL'] ?? join(homedir(), '.bun'), 'install', 'global');
+}
+
+export async function update(flags: UpdateFlags): Promise<void> {
+  const current = await release();
+  const root = installRoot(import.meta.dir);
+  const decision = updatePlan({
+    installed: current.installed,
+    latest: current.latest,
+    state: current.state,
+    root,
+    bunGlobal: bunGlobalRoot(),
+  });
+
+  // A gate wants a non-zero exit for the one state that needs action. An
+  // unreachable registry is not that state — failing a build because a network
+  // was down would make this the flakiest check in it.
+  if (flags.check === true && decision.action === 'install') process.exitCode = 1;
+
+  const report = {
+    installed: current.installed,
+    latest: current.latest,
+    state: current.state,
+    action: decision.action,
+    root,
+    ...(decision.install !== null ? { install: `bun ${decision.install.join(' ')}` } : {}),
+    ...(decision.warning !== null ? { warning: decision.warning } : {}),
+  };
+
+  if (flags.check === true || decision.action !== 'install') {
+    return emit(flags.json, report, () => {
+      if (decision.action === 'install') {
+        print(warn(decision.message));
+        if (decision.warning !== null) print(style.dim(`      ${decision.warning}`));
+        print(style.dim('      run: lanes link update'));
+        return;
+      }
+
+      // Green for the two states that need nothing. A refusal and an
+      // unreachable registry are neither wrong nor fine, and `ok` would claim
+      // the second of those.
+      if (decision.action === 'current' || decision.action === 'ahead') {
+        print(ok(decision.message));
+        return;
+      }
+
+      print(style.dim(decision.message));
+    });
+  }
+
+  // Stderr, both of them. What this command produces is the version change, and
+  // with `--json` that is a document — a line of prose in front of it corrupts
+  // it for whatever is parsing, which is the whole reason `emit` exists.
+  if (decision.warning !== null) progress(warn(decision.warning));
+  progress(style.dim(`bun ${decision.install!.join(' ')}`));
+
+  const installed = await runInstall(decision.install!, flags.json === true);
+  if (!installed) {
+    printErr(fail('the install did not complete — nothing was changed'));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Read the version back off disk rather than trusting the exit code. `version()`
+  // reads `package.json` from the install root at call time, so this is the one
+  // question worth asking after a successful install: did *this* copy change?
+  // Unchanged after a clean install is the second-copy case above, seen from the
+  // other side.
+  const landed = version();
+
+  return emit(
+    flags.json,
+    {
+      ...report,
+      // The action was `install`; this is what came of it. Inventing a third
+      // action value would describe an outcome as a decision.
+      result: landed === current.installed ? 'unchanged' : 'installed',
+      installed: landed,
+      previous: current.installed,
+    },
+    () => {
+      if (landed === current.installed) {
+        print(warn(`bun reported success, but ${root} is still ${landed}`));
+        print(style.dim('      the copy it installed is somewhere else on your PATH'));
+        print(style.dim('      check with: which -a lanes'));
+        return;
+      }
+
+      print(ok(`${current.installed} → ${style.bold(landed)}`));
+      print(style.dim('      a running endpoint serves the old code until it is restarted'));
+    },
+  );
+}
+
+/**
+ * Hand the install to Bun and let it own the terminal.
+ *
+ * `process.execPath` rather than `Bun.which('bun')`: this process is already
+ * running under the Bun that should do the installing, and a PATH lookup can
+ * find a different one — which would resolve the dependency set with a
+ * different resolver than the one that will run the result.
+ *
+ * Output is inherited rather than captured. Bun prints its own progress and its
+ * own errors, and paraphrasing a package manager's failure is how a report ends
+ * up less useful than the thing it replaced. Its stdout is dropped under
+ * `--json` for the same reason the lines above go to stderr: the document on
+ * stdout has to be the only thing on stdout. Its stderr is kept either way,
+ * because a failure is worth reading in both modes.
+ */
+async function runInstall(argv: readonly string[], json: boolean): Promise<boolean> {
+  try {
+    const child = Bun.spawn([process.execPath, ...argv], {
+      stdout: json ? 'ignore' : 'inherit',
+      stderr: 'inherit',
+    });
+    return (await child.exited) === 0;
+  } catch {
+    return false;
+  }
+}

package/src/cli/main.ts

@@ -38,6 +38,7 @@ import {
   vaultRemove,
   vaultSet,
 } from './commands/owner.ts';
+import { update } from './commands/update.ts';
 import { globalFlags, ownerFlags, parseArgv, text } from './argv.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
@@ -335,6 +336,9 @@ export async function run(argv: readonly string[]): Promise<void> {
       print(version());
       return;
 
+    case 'update':
+      return update({ check: flags['check'] === true, json });
+
     default:
       throw new Error(`Unknown command "${first}". Run: ${PROGRAM} help`);
   }

package/src/cli/release.ts

@@ -0,0 +1,111 @@
+import { version } from './version.ts';
+
+/**
+ * Whether a newer release than this one has been published.
+ *
+ * `version.ts` answers which release is installed, which stopped being the
+ * whole question when this started shipping from npm: two machines can now sit
+ * a release apart with nothing on either to say so, and the only upgrade
+ * affordance in the tree was a `contract` mismatch telling someone to "Upgrade
+ * lanes-link" without naming a command.
+ *
+ * Every function here degrades to `null` or `'unknown'` rather than throwing. A
+ * version check is never the reason a command fails — `doctor`, `start`, and
+ * `deploy` each print one line from this and must all work on a plane.
+ */
+
+/** The npm package this CLI ships as, and the only thing `update` will install. */
+export const PACKAGE = '@lanes-sh/link';
+
+/**
+ * The dist-tags document, not the packument.
+ *
+ * `registry.npmjs.org/<name>` carries every version ever published with its
+ * full manifest — hundreds of kilobytes to answer a question whose answer is
+ * eighteen bytes. This endpoint returns `{"latest":"0.2.0"}` and nothing else.
+ */
+const DIST_TAGS = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE)}/dist-tags`;
+
+/**
+ * The same budget `endpointHealth` gives its probe.
+ *
+ * Long enough for a warm connection, short enough that a command which only
+ * mentions staleness in passing does not appear to hang on a captive-portal
+ * network that accepts the connection and then says nothing.
+ */
+const PROBE_TIMEOUT_MS = 700;
+
+export type ReleaseState = 'current' | 'stale' | 'ahead' | 'unknown';
+
+export interface Release {
+  readonly installed: string;
+  /** `null` when the registry could not be reached, or answered something else. */
+  readonly latest: string | null;
+  readonly state: ReleaseState;
+}
+
+/**
+ * How the installed version stands against the published one.
+ *
+ * `'ahead'` is not a mistake: a contributor running from a checkout is usually
+ * a version ahead of the registry, and telling them they are behind would be
+ * both wrong and the thing they see most often.
+ *
+ * Pure, and separate from the fetch, so every branch is testable without a
+ * network — which is the only way the stale path gets covered at all, given the
+ * checkout this is written in is by definition current.
+ */
+export function releaseState(installed: string, latest: string | null): ReleaseState {
+  if (latest === null) return 'unknown';
+
+  try {
+    const order = Bun.semver.order(installed, latest);
+    return order === 0 ? 'current' : order < 0 ? 'stale' : 'ahead';
+  } catch {
+    // `Bun.semver.order` throws on anything it cannot parse rather than
+    // ordering it arbitrarily. A registry that answers with something other
+    // than a version, or a hand-edited `package.json`, is an unknown state and
+    // not a reason to claim either answer.
+    return 'unknown';
+  }
+}
+
+/** What the registry calls `latest`, or `null` if it did not say. */
+export async function latestRelease(): Promise<string | null> {
+  try {
+    const response = await fetch(DIST_TAGS, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+    if (!response.ok) return null;
+
+    const body = (await response.json()) as { latest?: unknown };
+    return typeof body.latest === 'string' ? body.latest : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The installed version, the published one, and how they stand. */
+export async function release(): Promise<Release> {
+  const installed = version();
+  const latest = await latestRelease();
+
+  return { installed, latest, state: releaseState(installed, latest) };
+}
+
+/**
+ * The one line `doctor`, `start`, and `deploy` print when this install is behind.
+ *
+ * One string in one place, because three commands saying it three ways is how
+ * two of them end up naming a command that has been renamed. `null` for every
+ * state but `'stale'`: nothing is worth saying about an install that is current,
+ * and an unreachable registry is not news.
+ */
+export function staleLine(current: Release): string | null {
+  if (current.state !== 'stale') return null;
+
+  return `${current.installed} is installed, ${current.latest} is out — run: lanes link update`;
+}
+
+/** `staleLine` over a fresh probe, for a caller that has no `Release` in hand. */
+export async function staleNudge(): Promise<string | null> {
+  return staleLine(await release());
+}

package/src/cli/usage.ts

@@ -90,6 +90,7 @@ ${style.bold('Inspection')}
   ${PROGRAM} audit verify           has anything in the log been altered or removed
   ${PROGRAM} config show
   ${PROGRAM} version                    which release this is — same as lanes --version
+  ${PROGRAM} update [--check] [--json]  install the newer release, or say what is available
 
 ${style.bold('Attachments')}
   ${PROGRAM} attach <file> --connection <provider>.<account>

package/src/deployments/deploy.ts

@@ -1,5 +1,6 @@
 import { ConfigError, resolveDeployTarget, type DeployConfig } from '#profile';
 import { announce, fail, heading, ok, print, style, warn } from '#cli/output.ts';
+import { staleNudge } from '#cli/release.ts';
 import { confirm, isInteractive } from '#cli/prompt.ts';
 import { openSecretStoreFor, resolveProfile, type GlobalFlags } from '#cli/runtime.ts';
 import { resolveTarget, vaultEnv } from './bootstrap.ts';
@@ -57,6 +58,12 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // rejected on boot should be rejected here, not after a five-minute build.
   print(ok(`${resolution.profilePath} is valid`));
 
+  // The CLI planning this rollout, not the image it will build. An old one
+  // plans an old rollout, and a build is the most expensive place to find that
+  // out.
+  const stale = await staleNudge();
+  if (stale !== null) print(warn(stale));
+
   const declared = await resolveTarget({
     config,
     profilePath: resolution.profilePath,

package/src/deployments/gcp/driver.ts

@@ -113,6 +113,12 @@ export function deployPlan(input: PlanInput): DeployStep[] {
         // harness can mint one — so a target reached by a remote MCP client
         // declares `public` and gates the request in the application instead.
         cloudrun.access === 'iam' ? '--no-allow-unauthenticated' : '--allow-unauthenticated',
+        // Always passed, including the zero. Config is the source of truth here
+        // (ADR-004), and a flag sent only when non-zero would let a value be
+        // raised and never lowered — the revision would keep whatever the last
+        // deploy that bothered to mention it had set.
+        '--min-instances',
+        String(cloudrun.min_instances),
       ],
     },
   ];

package/src/deployments/gcp/survey.ts

@@ -127,6 +127,9 @@ export async function surveyCloudRun(input: SurveyInput): Promise<SurveyResult>
 
   const deploy: DeployConfig = {
     platform: 'cloudrun',
+    // Not asked about. Zero is right for almost every target and the question
+    // would cost every operator a decision to buy one of them a knob.
+    min_instances: current.min_instances ?? 0,
     project,
     region,
     service,

package/src/profile/authorization.ts

@@ -34,11 +34,20 @@ const selfAuthorizationSchema = z.object({
   /**
    * How long an issued access token lives.
    *
-   * Short by design and refreshed rather than lengthened: a client that holds a
-   * long-lived token has something worth stealing, and the refresh path is the
-   * one that can be revoked by dropping a row.
+   * Twelve hours, where this used to be one. The old reading — short by design,
+   * refreshed rather than lengthened — assumed the refresh happens. Expiry is
+   * in practice where a remote client loses its session: one observed against
+   * this endpoint let its access token lapse and reported needing authorization
+   * while the matching refresh token sat in the store unused, weeks from its
+   * own expiry. That is the client's bug and nothing here can fix it. What the
+   * endpoint can do is stop offering the chance twenty-four times a day.
+   *
+   * What is given up is real and bounded: a stolen access token is useful for
+   * longer. The revocable half is unchanged — the refresh path is still what a
+   * dropped row closes — and the refresh token was already the longer-lived of
+   * the pair at thirty days. `1440` is the ceiling, for one window a day.
    */
-  access_token_ttl_minutes: z.number().int().positive().max(1440).default(60),
+  access_token_ttl_minutes: z.number().int().positive().max(1440).default(720),
 });
 
 const oidcAuthorizationSchema = z.object({

package/src/profile/schema.ts

@@ -178,6 +178,20 @@ export const deployTargetSchema = z.object({
   billing_account: z.string().optional(),
   /** The identity the running revision assumes. Needs read access to the credential store. */
   service_account: z.string().optional(),
+  /**
+   * Instances kept running when nothing is calling.
+   *
+   * Zero is the default and the right answer for almost everything here: a cold
+   * start on the MCP path measures under three seconds, and the platform queues
+   * the request behind it, so scaling to zero is invisible to a caller.
+   *
+   * It is a knob because one path is not a caller. A client refreshes its token
+   * exactly when it wakes after an idle gap — which is exactly when the instance
+   * is cold — and a refresh that fails at the network level sends a remote
+   * client through a fresh browser authorization rather than surfacing an error.
+   * Raise it if a re-authorization ever lines up with a cold `/token`.
+   */
+  min_instances: z.number().int().min(0).max(10).default(0),
 });
 
 /**
@@ -221,7 +235,18 @@ export const targetSchema = z
   .transform(({ cloudrun, ...target }) =>
     target.deploy || !cloudrun
       ? target
-      : { ...target, deploy: { ...cloudrun, platform: 'cloudrun' as const, access: 'iam' as const } },
+      : {
+          ...target,
+          // The pre-`deploy` spelling predates both of these, so it gets the
+          // same defaults the current one would: the closed door, and no
+          // instance kept warm.
+          deploy: {
+            ...cloudrun,
+            platform: 'cloudrun' as const,
+            access: 'iam' as const,
+            min_instances: 0,
+          },
+        },
   );
 
 /**

package/src/server/endpoint.ts

@@ -169,6 +169,7 @@ function closeAll(runtimes: ReadonlyMap<string, Runtime>): Promise<unknown> {
  */
 async function openAuthorization(
   primary: Runtime,
+  log: Logger,
 ): Promise<{ surface: AuthorizationSurface; authenticator: Authenticator } | null> {
   const declared = primary.config.auth.authorization;
   if (!declared) return null;
@@ -210,6 +211,10 @@ async function openAuthorization(
   const server = new OAuthServer({
     store,
     accessTokenTtlMs: declared.access_token_ttl_minutes * 60_000,
+    // So a replayed refresh token leaves a line. It is refused rather than
+    // acted on (ADR-035), and a refusal nobody can see is how a connector
+    // losing its authorization came to need log forensics to explain.
+    log,
     // Approval is proof of holding the endpoint token, compared the same way
     // the request path compares it. There is one person behind this endpoint
     // and they already have exactly one credential; a second one invented for
@@ -228,6 +233,7 @@ async function openAuthorization(
 
 export async function startEndpoint(options: EndpointOptions): Promise<RunningEndpoint> {
   const reporter = options.reporter ?? SILENT;
+  const log = options.log ?? silentLogger();
   const { primary, runtimes } = await openReconciled(options);
 
   try {
@@ -251,7 +257,7 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       }
     }
 
-    const gate = await openAuthorization(primary);
+    const gate = await openAuthorization(primary, log);
 
     // The authenticator and the authorization gate are built once, from the
     // runtime this endpoint booted with, and are deliberately not part of what
@@ -273,7 +279,10 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       // not refresh skills`, and every `mcp handler error` the endpoint raises
       // all went to those empty methods. A silent endpoint is not a quiet one —
       // it is one whose failures have to be reconstructed from request sizes.
-      { primary: primary.resolution.profile, log: options.log ?? silentLogger() },
+      // `remoteClients` is the gate's existence, not a second setting: a profile
+      // declaring `auth.authorization` is one a connector reaches by URL, which
+      // is exactly the client the extra paragraph is written for.
+      { primary: primary.resolution.profile, log, ...(gate ? { remoteClients: true } : {}) },
     );
 
     const server = serve({
@@ -282,7 +291,7 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       authenticator: gate
         ? new AuthenticatorChain([primary.authenticator, gate.authenticator])
         : primary.authenticator,
-      log: options.log ?? silentLogger(),
+      log,
       ...(gate ? { authorization: gate.surface } : {}),
       ...(options.port !== undefined ? { port: options.port } : {}),
       ...(options.host !== undefined ? { host: options.host } : {}),

package/src/server/generation.ts

@@ -204,6 +204,7 @@ export class Generation {
           principal,
           clientLabel,
           ...(this.#deps.version ? { version: this.#deps.version } : {}),
+          ...(this.#deps.remoteClients ? { remoteClients: true } : {}),
         }),
       {
         onerror: (error: Error) =>

package/src/server/generations.ts

@@ -52,6 +52,8 @@ export interface GenerationDeps {
   readonly primary: string;
   readonly log: Logger;
   readonly version?: string | undefined;
+  /** Whether an authorization surface is published. See `BuildServerOptions`. */
+  readonly remoteClients?: boolean | undefined;
 }
 
 /** What a reload did, as the `/reload` route reports it. */

package/src/server/harness.ts

@@ -86,6 +86,14 @@ export { parseConfig } from '#profile';
 export interface HarnessOptions {
   profile: string;
   log?: Logger;
+  /**
+   * The clock the authorization server and its store share.
+   *
+   * Shared deliberately: a tombstone's `consumedAt` is written by the store and
+   * compared by the server, so two clocks would make the reuse interval
+   * untestable in the one direction that matters. Absent means `Date.now`.
+   */
+  now?: () => number;
   port: number;
   policy: string;
   token?: string;
@@ -218,13 +226,17 @@ export function startHarness(options: HarnessOptions): Harness {
   // The real wiring from `endpoint.ts`, not a stand-in: the flow under test is
   // the one a connector drives over HTTP, and a fake authorization server would
   // demonstrate that the fake works.
-  const store = options.authorization ? new OAuthStore(state.kv) : null;
+  const log = options.log ?? silentLogger();
+
+  const store = options.authorization ? new OAuthStore(state.kv, options.now) : null;
   const gate = store
     ? {
         surface: {
           server: new OAuthServer({
             store,
             accessTokenTtlMs: 3_600_000,
+            log,
+            ...(options.now ? { now: options.now } : {}),
             verifyOwner: (presented) => Promise.resolve(tokensMatch(presented, token)),
           }),
           issuer: (origin: string) => origin,
@@ -235,8 +247,6 @@ export function startHarness(options: HarnessOptions): Harness {
       }
     : null;
 
-  const log = options.log ?? silentLogger();
-
   const nothing = () => Promise.resolve();
   const generations = new Generations(
     { profiles, close: nothing },

package/src/server/index.ts

@@ -1,4 +1,4 @@
-import { challenge, type Authenticator } from '#auth';
+import { challenge, type Authenticator, type AuthOutcome, type ChallengeError } from '#auth';
 import type { Logger } from '#connectivity';
 import { capabilityIdForToolName } from '#server/mcp';
 import { ATTACHMENTS_PATH, stageAttachment } from './attachments.ts';
@@ -51,6 +51,34 @@ export interface ServerOptions {
   readonly allowedHostnames?: readonly string[] | undefined;
 }
 
+type RefusalReason = Extract<AuthOutcome, { ok: false }>['reason'];
+
+/**
+ * What a caller should do about each refusal.
+ *
+ * `invalid` is the only one a client can act on by itself: it presented a
+ * credential and this endpoint did not accept it, which is what a refresh is
+ * for. RFC 6750 §3.1 has a name for that and clients branch on it; the others
+ * mean there is nothing to refresh, and §3 says to stay quiet rather than send
+ * a client after a token it does not hold. `malformed` says nothing either —
+ * `invalid_request` carries a SHOULD of a 400 status, and changing that path's
+ * status is a larger question than this answers.
+ */
+const CHALLENGE: Partial<Record<RefusalReason, ChallengeError>> = {
+  invalid: {
+    code: 'invalid_token',
+    description: 'The credential is expired, revoked, or not one this endpoint issued.',
+  },
+};
+
+/** The same four, for whoever is reading the body rather than the header. */
+const HINTS: Record<RefusalReason, string> = {
+  missing: 'Present the profile token as: Authorization: Bearer <token>',
+  malformed: 'Present the profile token as: Authorization: Bearer <token>',
+  invalid: 'Refresh the credential. Authorize again only if the refresh is refused too.',
+  not_configured: 'This profile has no token yet. Run: lanes link token rotate',
+};
+
 export const MCP_PATH = '/mcp';
 export const RELOAD_PATH = '/reload';
 
@@ -174,16 +202,13 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
           JSON.stringify({
             error: 'unauthorized',
             reason: outcome.reason,
-            hint:
-              outcome.reason === 'not_configured'
-                ? 'This profile has no token yet. Run: lanes link token rotate'
-                : 'Present the profile token as: Authorization: Bearer <token>',
+            hint: HINTS[outcome.reason],
           }),
           {
             status: 401,
             headers: {
               'content-type': 'application/json',
-              'www-authenticate': challenge(metadata),
+              'www-authenticate': challenge(metadata, CHALLENGE[outcome.reason]),
             },
           },
         );

package/src/server/mcp/build.ts

@@ -46,7 +46,7 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
     // and `Implementation` would take it as an unknown extra and drop it from
     // `initialize` without complaining.
     {
-      instructions: serverInstructions(names, merged),
+      instructions: serverInstructions(names, merged, options.remoteClients),
       // Declared `false` because it is false, and the SDK defaults it to `true`.
       //
       // `listChanged` is a promise to send `notifications/tools/list_changed`

package/src/server/mcp/instructions.ts

@@ -34,10 +34,10 @@ import type { MergedCapability } from './visibility.ts';
 /**
  * The habits, in the order they are needed.
  *
- * Routing first because it gates every call; refusals last because that is when
- * an agent is most tempted to improvise. Second person, and specific about what
- * *not* to do — "ask which profile" is advice, "do not default to the first" is
- * a rule.
+ * Routing first because it gates every call; the two ways a call ends badly last,
+ * because that is when an agent is most tempted to improvise. Second person, and
+ * specific about what *not* to do — "ask which profile" is advice, "do not
+ * default to the first" is a rule.
  *
  * **Four of these are conditional**, and that is a correctness property rather
  * than a saving. This used to be one fixed string that told every client to
@@ -95,6 +95,27 @@ const REFUSAL = `**A refused call is the permission system working**, not an obs
 around. Report what was refused and let the owner decide whether to widen it.
 Every call, including a refused one, is recorded.`;
 
+/**
+ * The one about not reaching here at all.
+ *
+ * Only for a client that authorises against this endpoint over the network —
+ * the one that cannot be handed the bundled skill, and the one whose connector
+ * decides on its own whether this endpoint is available. Observed: with the
+ * endpoint up and idle, a connector reported it unreachable without issuing a
+ * request at all, and the model read that as a fault, then re-derived an answer
+ * it had already given and re-composed an entry it had already written. Nothing
+ * here can prevent it, because nothing here is consulted — the call never
+ * arrives. Telling the model what the state means is the whole of what is left.
+ *
+ * Deliberately *not* "the endpoint is asleep". Usually it is not, and prose
+ * asserting a cause the model cannot check is how a wrong diagnosis gets
+ * repeated with confidence.
+ */
+const AVAILABILITY = `**A call may simply not go through.** This endpoint is one machine its owner
+runs, and a client can report it unreachable while it is up. That is ordinary —
+not a fault to diagnose, and not authorization you have lost. Say the call did
+not land, do not redo what already succeeded, and offer to retry.`;
+
 /** Which paragraph each owner-layer provider brings, when it is reachable. */
 const OWNER_HABITS: Record<string, string> = {
   memory: MEMORY,
@@ -111,6 +132,11 @@ const OWNER_HABITS: Record<string, string> = {
  * it is the prompt to ask whether the paragraph belongs in the skill instead,
  * where it is loaded only when relevant.
  *
+ * It was raised once, from 2000, for `AVAILABILITY` — and that question was
+ * asked and answered the other way: the client that paragraph exists for is
+ * precisely the one that holds no skills directory, so the skill is not a place
+ * it can go. Only an endpoint serving remote clients spends it.
+ *
  * Exported because the test asserted `2000` as a literal while the code
  * reserved room against a second, differently-derived number — so the two could
  * disagree, and did. There is no separate listing allowance any more: `spent`
@@ -118,7 +144,7 @@ const OWNER_HABITS: Record<string, string> = {
  * exactly the final length, because `join` adds the same two characters the
  * reduce already counted.
  */
-export const MAX_INSTRUCTIONS = 2000;
+export const MAX_INSTRUCTIONS = 2300;
 
 /** Which of the owner-layer providers this principal can actually reach. */
 function ownerProviders(merged: ReadonlyMap<string, MergedCapability>): string[] {
@@ -172,6 +198,9 @@ function connectionsByProfile(
 export function serverInstructions(
   profiles: readonly string[],
   merged: ReadonlyMap<string, MergedCapability>,
+  /** Whether a client authorises against this endpoint rather than being handed
+   * a token — see `AVAILABILITY`, the only paragraph that reads it. */
+  remoteClients = false,
 ): string {
   const reachable = connectionsByProfile(profiles, merged);
   const owner = ownerProviders(merged);
@@ -185,6 +214,7 @@ export function serverInstructions(
     ...owner.map((id) => OWNER_HABITS[id]).filter((habit): habit is string => habit !== undefined),
     FILES,
     REFUSAL,
+    ...(remoteClients ? [AVAILABILITY] : []),
   ];
 
   if (reachable.size === 0) {

package/src/server/mcp/visibility.ts

@@ -53,6 +53,15 @@ export interface BuildServerOptions {
   /** Self-reported by the client. Recorded in audit; never used to authorize. */
   readonly clientLabel?: string | undefined;
   readonly version?: string;
+  /**
+   * Whether this endpoint publishes an authorization surface, and therefore
+   * serves clients that arrived by URL alone.
+   *
+   * Read only by the instructions, which gain a paragraph for them. Absent over
+   * a pipe and on a loopback endpoint, where the client holds the skill and the
+   * transport cannot fail the way this describes.
+   */
+  readonly remoteClients?: boolean | undefined;
 }
 
 /** One profile as the map the builder wants. */