@catheadowl/ukp 0.1.1 → 0.2.1

package/src/commands/inventory.ts

@@ -2,7 +2,7 @@ import { ENDPOINT_NAME, loadManifest } from "../config/manifest.ts";
 import { FILE_NATIVE_CAPABILITIES, isFileNativeCapability } from "../config/file-native.ts";
 import { diagnoseService, type ProviderResolver } from "./diagnose.ts";
 import {
-  assertRemoteUrlAllowed,
+  assertRegistrableRemoteUrl,
   isRemoteBinding,
   parseRemoteUrl,
   readRegistry,
@@ -56,7 +56,9 @@ export const REGISTER_SPEC: UkpCommandSpec = {
   usage: "[options]",
   strictArguments: true,
   options: [
-    { flags: "--url <url>", help: "register a remote ukp-serve endpoint (https, ssh://host[:port][/endpoint], or loopback http); a host door url (its document declares scope:\"host\") imports every endpoint behind the door — binding urls gain the endpoint-name path (ssh://ali/notes)" },
+    { flags: "--url <url>", help: "register a remote ukp-serve endpoint (https://host[:port], ssh://host[/endpoint] — ssh takes no port, the woken door picks its own — or loopback http); a host door url (its document declares scope:\"host\") imports every endpoint behind the door — binding urls gain the endpoint-name path (ssh://ali/notes)" },
+    { flags: "--endpoint <name>", help: "assert the remote-declared name of the endpoint being registered (expected-name assertion; with a host door this imports only that endpoint)" },
+    { flags: "--name <handle>", help: "remote only: register under this local handle — the registry key and ukp:// authority — instead of the declared name; use it when the declared name is already taken" },
     { flags: "--select <names>", help: "with a host door url: import only the named endpoints (comma-separated); a name not on the door is a usage error" },
     { flags: "--token <token>", help: "store the bearer token in the binding (plaintext, 0600 registry file); with a host door it is copied into every imported binding; UKP_ENDPOINT_<NAME>_TOKEN overrides it at call time" },
   ],
@@ -70,17 +72,23 @@ export const REGISTER_SPEC: UkpCommandSpec = {
     "Binding:",
     "  The Host Registry binds the Service Manifest's effective name to this",
     "  folder's location; 'ukp list' shows the resulting bindings.",
-    "  With --url, the name and instance identity come from the remote",
-    "  discovery document (/.well-known/ukp.json) and are pinned TOFU-style;",
-    "  bearer-token services read UKP_ENDPOINT_<NAME>_TOKEN at call time.",
+    "  With --url, the declared name and instance identity come from the",
+    "  remote discovery document (/.well-known/ukp.json) and are pinned",
+    "  TOFU-style as provenance; your registry binds them under a local",
+    "  handle — the declared name by default, or --name <handle> when that",
+    "  name is already taken. Use --endpoint <name> as an expected-name",
+    "  assertion on the declared name; bearer-token services read",
+    "  UKP_ENDPOINT_<NAME>_TOKEN (keyed by the handle) at call time.",
     "",
-    "Host doors (ADR-REM-004):",
+    "Host doors:",
     "  'ukp register --url ssh://ali' fetches the door's discovery document",
     "  and imports every endpoint behind it (a door url may also name one",
     "  endpoint: ssh://ali/notes). Import is explicit and idempotent:",
     "  re-running refreshes TOFU pins and tokens. Name conflicts are skipped",
-    "  with a visible reason (never silently renamed); --select narrows the",
-    "  import; door growth shows in 'ukp list' as drift notes until imported.",
+    "  with a visible reason (never silently renamed) — re-register that one",
+    "  endpoint with --name to land it under another handle; --select narrows",
+    "  the import; door growth shows in 'ukp list' as drift notes until",
+    "  imported.",
     "",
   ].join("\n"),
 };
@@ -146,14 +154,30 @@ export function executeRegisterCommand(
   }
 
   try {
-    const parsed = parseKitArgs<{ url?: string; token?: string; select?: string }>(REGISTER_SPEC, args);
+    const parsed = parseKitArgs<{ url?: string; token?: string; select?: string; endpoint?: string; name?: string }>(REGISTER_SPEC, args);
+    const expectedName = parsed.options.endpoint;
+    if (expectedName !== undefined && !ENDPOINT_NAME.test(expectedName)) {
+      throw new KitUsageError("--endpoint requires a valid endpoint name");
+    }
+    const handleName = parsed.options.name;
+    if (handleName !== undefined && !ENDPOINT_NAME.test(handleName)) {
+      throw new KitUsageError("--name requires a valid endpoint name");
+    }
+    if (handleName !== undefined && parsed.options.url === undefined) {
+      // N-1 (ADR-REM-007): a local name lives in the Service Manifest the
+      // folder owner controls; the registry naming slot is remote-only.
+      throw new KitUsageError("--name chooses a remote registration handle and requires --url");
+    }
     if (parsed.options.url !== undefined) {
-      return executeRegisterRemote(parsed.options.url, parsed.options.token, parsed.options.select, context);
+      return executeRegisterRemote(parsed.options.url, parsed.options.token, parsed.options.select, expectedName, handleName, context);
     }
     if (parsed.options.select !== undefined) {
       throw new KitUsageError("--select requires --url <door url>");
     }
     const report = diagnoseService(context.currentDirectory, context.resolveProvider);
+    if (expectedName !== undefined && expectedName !== report.service.effectiveName) {
+      throw new Error(`expected endpoint '${expectedName}', but this Service effective name is '${report.service.effectiveName}'`);
+    }
     registerAt(context.registryPath, report.service.effectiveName, report.service.folder);
     const lines = [
       `registered: ${report.service.effectiveName}`,
@@ -197,37 +221,71 @@ function declaredCapabilitySummary(capabilities: Record<string, unknown>): strin
   return extras.length > 0 ? extras.join(",") : "-";
 }
 
-/** Import the door roster into the registry (ADR-REM-004 / O-4): default is
- * every endpoint, `--select` narrows, name/url conflicts are skipped with a
- * visible reason (RQ-14: never silently renamed), and same name+url is the
- * idempotent refresh (TOFU pin + token, the W4 semantics in batch). ≥1
- * import/refresh exits 0; all-skipped exits 1. */
+/** Import the door roster into the registry (ADR-REM-004 / O-4; naming
+ * residence ADR-REM-007 / D-086): default is every endpoint, `--select`
+ * narrows, conflicts are skipped with a visible reason plus the
+ * single-endpoint `--name` remedy (never silently renamed), and same
+ * url+declared name is the idempotent refresh under the existing handle
+ * (TOFU pin + token, the W4 semantics in batch). ≥1 import/refresh exits 0;
+ * all-skipped exits 1. */
 function importDoorEndpoints(
   origin: string,
   door: { endpoints: ReadonlyArray<{ name: string; instance_uid: string; capabilities: Record<string, unknown> }> },
   targets: ReadonlyArray<{ name: string; instance_uid: string; capabilities: Record<string, unknown> }>,
   credentials: { token?: string; tls_cert?: string; tls_pin?: string },
   context: InventoryCommandContext,
+  handleOverride?: string,
 ): InventoryCommandResult {
   const existing = readRegistry(context.registryPath);
   const lines = [`door ${origin}: ${door.endpoints.length} endpoint(s)`];
   let landed = 0;
   for (const target of targets) {
+    // N-5 (ADR-REM-007): the url path segment stays the door-declared name —
+    // the door routes by it; only the local handle may differ.
     const url = doorEndpointUrl(origin, target.name);
-    const sameName = existing.find((endpoint) => endpoint.name === target.name);
-    if (sameName !== undefined && !(sameName.kind === "remote" && sameName.url === url)) {
-      lines.push(`skipped:  ${target.name}  (already bound to ${sameName.kind === "remote" ? sameName.url : sameName.path})`);
+    const handle = handleOverride ?? target.name;
+    // Mirror of registerRemoteBinding's same-url branch (registry.ts):
+    // skip-line wording lives here, refusal semantics there — keep in step.
+    const sameUrl = existing.find((endpoint) => endpoint.kind === "remote" && endpoint.url === url);
+    if (sameUrl !== undefined) {
+      // Legacy bindings carry no declared_name; their handle stood in for it.
+      const existingDeclared = sameUrl.declared_name ?? sameUrl.name;
+      if (existingDeclared !== target.name) {
+        lines.push(`skipped:  ${target.name}  (url ${url} is bound to '${sameUrl.name}' declaring '${existingDeclared}')`);
+        continue;
+      }
+      // A default gesture (no --name) refreshes the instance under its
+      // EXISTING handle (N-2); an explicit --name must match it — explicit
+      // means explicit, renaming goes through unregister.
+      if (sameUrl.name !== handle && (handleOverride !== undefined || handle !== target.name)) {
+        lines.push(`skipped:  ${target.name}  (url ${url} already bound to '${sameUrl.name}'; unregister it to change the handle)`);
+        continue;
+      }
+      registerRemoteAt(context.registryPath, {
+        name: sameUrl.name,
+        declared_name: target.name,
+        url,
+        instance_uid: target.instance_uid,
+        ...(credentials.token !== undefined ? { token: credentials.token } : {}),
+        ...(credentials.tls_cert !== undefined && credentials.tls_pin !== undefined
+          ? { tls_cert: credentials.tls_cert, tls_pin: credentials.tls_pin }
+          : {}),
+      });
+      landed += 1;
+      lines.push(`refreshed: ${sameUrl.name}  (TOFU pin/credentials refreshed)`);
       continue;
     }
-    const sameUrl = existing.find(
-      (endpoint) => endpoint.kind === "remote" && endpoint.url === url && endpoint.name !== target.name,
-    );
-    if (sameUrl !== undefined) {
-      lines.push(`skipped:  ${target.name}  (url ${url} already bound to '${sameUrl.name}')`);
+    const sameName = existing.find((endpoint) => endpoint.name === handle);
+    if (sameName !== undefined) {
+      lines.push(
+        `skipped:  ${target.name}  (name '${handle}' already bound to ${sameName.kind === "remote" ? sameName.url : sameName.path}; `
+          + `re-register this endpoint with --name <handle> to land it under another)`,
+      );
       continue;
     }
     registerRemoteAt(context.registryPath, {
-      name: target.name,
+      name: handle,
+      declared_name: target.name,
       url,
       instance_uid: target.instance_uid,
       ...(credentials.token !== undefined ? { token: credentials.token } : {}),
@@ -237,9 +295,9 @@ function importDoorEndpoints(
     });
     landed += 1;
     lines.push(
-      sameName !== undefined
-        ? `refreshed: ${target.name}  (TOFU pin/credentials refreshed)`
-        : `imported: ${target.name}  (${declaredCapabilitySummary(target.capabilities)})`,
+      handle !== target.name
+        ? `imported: ${handle}  (declares ${target.name}; ${declaredCapabilitySummary(target.capabilities)})`
+        : `imported: ${handle}  (${declaredCapabilitySummary(target.capabilities)})`,
     );
   }
   return {
@@ -250,17 +308,21 @@ function importDoorEndpoints(
 }
 
 /** Remote registration (D-077/D-078 / spec endpoint-registration; host doors
- * since W7 / ADR-REM-004): the well-known document at the url's origin
- * self-describes — an endpoint document (no `scope`) registers one endpoint
- * (today's behavior, name from the document per RQ-14, TOFU pin, --token in
- * the binding); a door document (`scope:"host"`) runs the import flow above.
- * ssh:// urls tunnel transparently; https urls probe TLS first (W5' / D-079):
- * a public-CA chain validates normally, a self-signed certificate is
- * TOFU-pinned into the binding(s) and verified on every later call. */
+ * since W7 / ADR-REM-004; naming residence ADR-REM-007): the well-known
+ * document at the url's origin self-describes — an endpoint document (no
+ * `scope`) registers one endpoint (declared name from the document as
+ * provenance, local handle = declared name or --name, TOFU pin, --token in
+ * the binding); a door document (`scope:"host"`) runs the import flow above
+ * (--name only when exactly one target results). ssh:// urls tunnel
+ * transparently; https urls probe TLS first (W5' / D-079): a public-CA chain
+ * validates normally, a self-signed certificate is TOFU-pinned into the
+ * binding(s) and verified on every later call. */
 async function executeRegisterRemote(
   url: string,
   token: string | undefined,
   select: string | undefined,
+  expectedName: string | undefined,
+  handleName: string | undefined,
   context: InventoryCommandContext,
 ): Promise<InventoryCommandResult> {
   const selected = select === undefined
@@ -269,10 +331,15 @@ async function executeRegisterRemote(
   if (selected !== undefined && selected.length === 0) {
     throw new KitUsageError("--select requires at least one endpoint name");
   }
+  if (selected !== undefined && expectedName !== undefined) {
+    throw new KitUsageError("--endpoint and --select cannot be used together");
+  }
 
   let pool: RemoteTransportPool | undefined;
   try {
-    assertRemoteUrlAllowed(url);
+    // D-089: registration intake rejects an explicit ssh:// port (dead
+    // grammar since the W9 wake); parse-time surfaces stay permissive.
+    assertRegistrableRemoteUrl(url);
     const parts = parseRemoteUrl(url);
     if (parts === undefined) {
       throw new Error(`remote endpoint url is not admissible: ${url}`);
@@ -296,6 +363,11 @@ async function executeRegisterRemote(
       const rosterNames = roster.map((endpoint) => endpoint.name).join(", ");
       let targets;
       if (parts.endpointName !== undefined) {
+        if (expectedName !== undefined && expectedName !== parts.endpointName) {
+          throw new KitUsageError(
+            `remote url selects endpoint '${parts.endpointName}', but --endpoint asserts '${expectedName}'`,
+          );
+        }
         // A path segment addresses ONE endpoint through the door (H-rehearsal):
         // membership is checked against the live roster, unknown names say so.
         const found = roster.find((endpoint) => endpoint.name === parts.endpointName);
@@ -303,6 +375,12 @@ async function executeRegisterRemote(
           throw new Error(`no such endpoint '${parts.endpointName}' on door ${parts.origin} (available: ${rosterNames})`);
         }
         targets = [found];
+      } else if (expectedName !== undefined) {
+        const found = roster.find((endpoint) => endpoint.name === expectedName);
+        if (found === undefined) {
+          throw new Error(`no such endpoint '${expectedName}' on door ${parts.origin} (available: ${rosterNames})`);
+        }
+        targets = [found];
       } else if (selected !== undefined) {
         const unknown = selected.filter((name) => !roster.some((endpoint) => endpoint.name === name));
         if (unknown.length > 0) {
@@ -314,6 +392,11 @@ async function executeRegisterRemote(
       } else {
         targets = [...roster];
       }
+      if (handleName !== undefined && targets.length !== 1) {
+        throw new KitUsageError(
+          `--name applies to a single endpoint, but this import targets ${targets.length}; narrow with --select/--endpoint or drop --name`,
+        );
+      }
       const result = importDoorEndpoints(
         parts.origin,
         { endpoints: roster },
@@ -325,6 +408,7 @@ async function executeRegisterRemote(
             : {}),
         },
         context,
+        handleName,
       );
       const nameHint = wellKnown.door.bearerRequired && token === undefined
         ? [`note: this door requires a bearer token; pass --token or set UKP_ENDPOINT_<NAME>_TOKEN per endpoint`]
@@ -344,15 +428,41 @@ async function executeRegisterRemote(
     if (selected !== undefined) {
       throw new KitUsageError(`--select requires a host door url: ${parts.origin} serves a single endpoint`);
     }
-    const name = wellKnown.discovery.doc.name;
-    if (!ENDPOINT_NAME.test(name)) {
-      throw new Error(`discovery document declares an invalid endpoint name '${name}'`);
+    const declaredName = wellKnown.discovery.doc.name;
+    if (!ENDPOINT_NAME.test(declaredName)) {
+      throw new Error(`discovery document declares an invalid endpoint name '${declaredName}'`);
+    }
+    if (expectedName !== undefined && expectedName !== declaredName) {
+      throw new Error(`expected endpoint '${expectedName}', but discovery document declares '${declaredName}'`);
     }
     if (wellKnown.discovery.doc.instance_uid === undefined || typeof wellKnown.discovery.doc.instance_uid !== "string") {
       throw new Error("discovery document carries no instance_uid; the service must run a ukp-remote v1 server");
     }
+    // ADR-REM-007 / D-086: the handle is the consumer-chosen local name
+    // (defaults to the declared name); the declared name is stored as
+    // provenance and stays the target of the expected-name assertion above.
+    // N-2: a default-gesture re-registration of an already-tracked instance
+    // (same url, same declared name) refreshes it under its EXISTING handle —
+    // an explicitly different --name is refused first (explicit means
+    // explicit; renaming goes through unregister).
+    const requestedHandle = handleName ?? declaredName;
+    const tracked = readRegistry(context.registryPath).find(
+      (endpoint) => endpoint.kind === "remote" && endpoint.url === url,
+    );
+    if (
+      tracked !== undefined && handleName !== undefined && handleName !== tracked.name
+      && (tracked.declared_name ?? tracked.name) === declaredName
+    ) {
+      throw new Error(`remote endpoint ${url} is already registered as '${tracked.name}'; unregister it first to change the handle`);
+    }
+    const handle = tracked !== undefined
+      && (tracked.declared_name ?? tracked.name) === declaredName
+      && requestedHandle === declaredName
+      ? tracked.name
+      : requestedHandle;
     registerRemoteAt(context.registryPath, {
-      name,
+      name: handle,
+      declared_name: declaredName,
       url,
       instance_uid: wellKnown.discovery.doc.instance_uid,
       ...(token !== undefined ? { token } : {}),
@@ -360,9 +470,10 @@ async function executeRegisterRemote(
         ? { tls_cert: tlsProbe.certPem, tls_pin: tlsProbe.spkiPin }
         : {}),
     });
-    const envToken = remoteTokenFor(name);
+    const envToken = remoteTokenFor(handle);
     const lines = [
-      `registered (remote): ${name}`,
+      `registered (remote): ${handle}`,
+      ...(handle !== declaredName ? [`declares: ${declaredName} (remote-declared name, stored as provenance)`] : []),
       `url: ${url}`,
       `instance_uid: ${wellKnown.discovery.doc.instance_uid}`,
       ...(pinSelfSigned && tlsProbe !== undefined
@@ -370,9 +481,9 @@ async function executeRegisterRemote(
         : []),
       ...(wellKnown.discovery.doc.description !== undefined ? [`description: ${wellKnown.discovery.doc.description}`] : []),
       ...(token !== undefined
-        ? [`auth: token stored in registry binding (plaintext; env UKP_ENDPOINT_${name.toUpperCase().replace(/-/g, "_")}_TOKEN overrides)`]
+        ? [`auth: token stored in registry binding (plaintext; env UKP_ENDPOINT_${handle.toUpperCase().replace(/-/g, "_")}_TOKEN overrides)`]
         : wellKnown.discovery.bearerRequired && envToken === undefined
-          ? [`note: this endpoint requires a bearer token; pass --token or set UKP_ENDPOINT_${name.toUpperCase().replace(/-/g, "_")}_TOKEN`]
+          ? [`note: this endpoint requires a bearer token; pass --token or set UKP_ENDPOINT_${handle.toUpperCase().replace(/-/g, "_")}_TOKEN`]
           : []),
     ];
     return { exitCode: 0, stdout: lines.join("\n"), stderr: "" };
@@ -424,7 +535,7 @@ export function executeListCommand(
           rendered.push(await renderRemoteListRow(endpoint, pool));
         }
         const drift = await collectDoorDriftNotes(endpoints, pool);
-        return renderListOutput(rendered, drift);
+        return renderListOutput(rendered, [...collectSameInstanceNotes(endpoints), ...drift]);
       } finally {
         pool.close();
       }
@@ -460,12 +571,16 @@ function renderListOutput(
  * endpoints degrade to `(unavailable)` + one stderr warning — the same
  * inventory semantics as an unreadable local manifest. Door-form bindings
  * (`ssh://ali/notes`) fetch their per-endpoint document through the shared
- * pool's tunnel. */
+ * pool's tunnel. A handle that differs from the declared name (ADR-REM-007)
+ * carries the declaration inline for audit. */
 async function renderRemoteListRow(
   endpoint: RegistryBinding,
   pool: RemoteTransportPool,
 ): Promise<{ line: string; warning?: string }> {
   const url = endpoint.url!;
+  const declaredNote = endpoint.declared_name !== undefined && endpoint.declared_name !== endpoint.name
+    ? ` (declares ${endpoint.declared_name})`
+    : "";
   try {
     const transport = await pool.acquire(endpoint);
     const discovery = await fetchDiscoveryDocument(endpoint, transport, resolveRemoteToken(endpoint));
@@ -474,16 +589,40 @@ async function renderRemoteListRow(
       .map(([name]) => name)
       .sort();
     const warnings = discovery.warnings.length > 0 ? { warning: discovery.warnings.join("; ") } : {};
-    return { line: `${endpoint.name}\t${url}\t${extras.length > 0 ? extras.join(",") : "-"}`, ...warnings };
+    return { line: `${endpoint.name}${declaredNote}\t${url}\t${extras.length > 0 ? extras.join(",") : "-"}`, ...warnings };
   } catch (error) {
     const headline = (error instanceof Error ? error.message : String(error)).split("\n")[0];
     return {
-      line: `${endpoint.name}\t${url}\t(unavailable)`,
+      line: `${endpoint.name}${declaredNote}\t${url}\t(unavailable)`,
       warning: `endpoint '${endpoint.name}' capabilities unavailable: ${headline}`,
     };
   }
 }
 
+/** Same-instance double-handle note (ADR-REM-007 / N-2): two handles may
+ * legitimately point at one service through different urls (e.g. an ssh door
+ * and an https door of the same host); the shared instance_uid makes it
+ * visible. A note, not an error — each handle is a valid addressing surface,
+ * but ukp:// references under the two handles are not interchangeable. */
+function collectSameInstanceNotes(endpoints: readonly RegistryBinding[]): string[] {
+  const byUid = new Map<string, string[]>();
+  for (const endpoint of endpoints) {
+    if (!isRemoteBinding(endpoint) || endpoint.instance_uid === undefined) continue;
+    const handles = byUid.get(endpoint.instance_uid) ?? [];
+    handles.push(endpoint.name);
+    byUid.set(endpoint.instance_uid, handles);
+  }
+  const notes: string[] = [];
+  for (const [uid, handles] of byUid) {
+    if (handles.length > 1) {
+      notes.push(
+        `note: ${[...handles].sort().map((handle) => `'${handle}'`).join(" and ")} pin the same instance_uid ${uid} — one service under two handles`,
+      );
+    }
+  }
+  return notes;
+}
+
 /** Door drift notes (ADR-REM-004 / O-4): group door-form bindings by their
  * url origin, fetch each door's document ONCE per invocation (riding the
  * pool's shared tunnel), and note the endpoints the door serves that the
@@ -505,7 +644,9 @@ async function collectDoorDriftNotes(
       origins.set(parts.origin, group);
     }
     group.members.push(endpoint);
-    group.imported.add(endpoint.name);
+    // The roster speaks declared names; a handle that differs from the
+    // declared name (ADR-REM-007) must not read as "not imported".
+    group.imported.add(endpoint.declared_name ?? endpoint.name);
   }
   const notes: string[] = [];
   for (const [origin, group] of [...origins.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)) {

package/src/commands/nav.ts

@@ -125,7 +125,7 @@ export function executeNavCommand(
     if (error instanceof HelpRequestError) {
       return { exitCode: 0, stdout: renderNavHelp(), stderr: "" };
     }
-    if (error instanceof KitUsageError) {
+    if (error instanceof KitUsageError || error instanceof NavUsageError) {
       return { exitCode: 2, stdout: "", stderr: renderNavUsageError(error.message) };
     }
     throw error;

package/src/commands/read.ts

@@ -11,7 +11,8 @@ import {
   type ReadRequest,
   type LineRange,
 } from "../capabilities/read.ts";
-import { isValidPin } from "../capabilities/rename-recovery.ts";
+import { isValidPin, pinHashOf } from "../capabilities/rename-recovery.ts";
+import { isBareDocidReference, stripDocidHash } from "../capabilities/qmd.ts";
 import {
   fetchDiscoveryDocument,
   openRemoteTransport,
@@ -89,7 +90,14 @@ export const READ_SPEC: UkpCommandSpec = {
       flags: "--from <route>",
       help: "resolve a document-relative reference (../x.md, bare filename) against this source document's endpoint-relative route",
     },
-    { flags: "--pin <sha256-hex>", help: "verify rename recovery against this ukp-pin content hash (sha256-<64 hex>)" },
+    {
+      flags: "--pin <sha256-hex>",
+      help: "verify rename recovery against this ukp-pin content hash (sha256-<64 hex>; emit the current pin with --show-pin)",
+    },
+    {
+      flags: "--show-pin",
+      help: "emit the ukp-pin for the read resource on stderr (<!-- ukp-pin: sha256-… -->, whole-file LF-normalized sha256; embed next to a ukp:// reference to power rename recovery). Local reads allow a line window — the pin still covers the whole file; remote reads need the whole file, so drop the window there",
+    },
     { flags: "--format <mode>", help: "output mode: 'json' emits a structured failure envelope (body still goes to stdout); default is human output" },
   ],
   helpSuffix: [
@@ -111,6 +119,7 @@ interface ReadCommandOptions extends Record<string, unknown> {
   lines?: string;
   from?: string;
   pin?: string;
+  showPin?: boolean;
   format?: string;
 }
 
@@ -266,11 +275,22 @@ function parseReadWithFormat(args: readonly string[]): { request: ReadRequest; f
   if (parsed.options.pin !== undefined && !isValidPin(parsed.options.pin)) {
     // Q7-narrowed SRI form only: no multi-algorithm negotiation, no upper-case
     // hex tolerance — the pin is machine-written, not hand-typed.
-    throw new KitUsageError("--pin must use sha256-<64 lowercase hex> (the ukp-pin form emitted next to ukp:// references)");
+    throw new KitUsageError("--pin must use sha256-<64 lowercase hex> (the ukp-pin form embedded next to ukp:// references; emit one with --show-pin)");
   }
   if (parsed.options.format !== undefined && parsed.options.format !== "json") {
     throw new KitUsageError("--format only supports 'json'");
   }
+  // The ukp-pin is a file-slot concept (same boundary as pin verification in
+  // the recovery descent): provider-tier references never expose whole-file
+  // content, so emission is refused by input shape at parse time.
+  if (parsed.options.showPin === true && path !== undefined) {
+    const barePath = stripDocidHash(path);
+    if (path.startsWith("qmd://") || isBareDocidReference(barePath)) {
+      throw new KitUsageError(
+        "--show-pin is file-slot-only: the ukp-pin covers whole-file content, and provider references (docid, qmd://) do not expose it",
+      );
+    }
+  }
   const pin = parsed.options.pin;
   if (parsed.options.g) throw new KitUsageError("read requires --endpoint <name> and does not support -g");
   // Unexpected positionals are rejected before the missing-flag checks so the
@@ -280,15 +300,19 @@ function parseReadWithFormat(args: readonly string[]): { request: ReadRequest; f
       `unexpected argument '${unexpected}'; read accepts exactly one reference. Use '--endpoint <name>' to select an endpoint.`,
     );
   }
-  const withPin = <T extends object>(request: T): T & { pin?: string } =>
-    parsed.options.pin === undefined ? request : { ...request, pin: parsed.options.pin };
+  const withPinOptions = <T extends object>(request: T): T & { pin?: string; emitPin?: boolean } => {
+    let out: T & { pin?: string; emitPin?: boolean } = request;
+    if (parsed.options.pin !== undefined) out = { ...out, pin: parsed.options.pin };
+    if (parsed.options.showPin === true) out = { ...out, emitPin: true };
+    return out;
+  };
   const format = parsed.options.format === "json" ? ("json" as const) : undefined;
 
   if (path !== undefined && UKP_URI_PREFIX_RE.test(path)) {
     if (parsed.options.from !== undefined) {
       throw new KitUsageError("a ukp:// URI carries its own endpoint; --from is for document-relative references");
     }
-    return { request: withPin(parseUkpUri(path, { endpoint: parsed.options.endpoint, lines: parsed.options.lines })), ...(format ? { format } : {}) };
+    return { request: withPinOptions(parseUkpUri(path, { endpoint: parsed.options.endpoint, lines: parsed.options.lines })), ...(format ? { format } : {}) };
   }
   // Tolerant tier (ADR-URI-001): an absolute filesystem path carries its own
   // endpoint (Registry-matched), so --endpoint is neither required nor
@@ -303,7 +327,7 @@ function parseReadWithFormat(args: readonly string[]): { request: ReadRequest; f
       );
     }
     return {
-      request: withPin({
+      request: withPinOptions({
         path,
         ...(parsed.options.lines === undefined ? {} : { lines: parseLineRange(parsed.options.lines) }),
       }),
@@ -321,7 +345,7 @@ function parseReadWithFormat(args: readonly string[]): { request: ReadRequest; f
   }
 
   return {
-    request: withPin({
+    request: withPinOptions({
       endpoint: parsed.options.endpoint,
       path,
       ...(parsed.options.from === undefined ? {} : { fromRef: parsed.options.from }),
@@ -450,6 +474,17 @@ async function executeRemoteRead(
   binding: RegistryBinding,
   registryPath?: string,
 ): Promise<ReadCommandResult> {
+  // Remote emission needs whole-file content, and a line window would arrive
+  // windowed from the server — refuse before opening any transport.
+  if (request.emitPin === true && request.lines !== undefined) {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: renderReadUsageError(
+        "--show-pin needs whole-file content; drop the line window (--lines / #L) — the pin always covers the whole file",
+      ),
+    };
+  }
   const token = resolveRemoteToken(binding);
   const warnings: string[] = [];
   let transport: RemoteTransportHandle | undefined;
@@ -516,9 +551,13 @@ async function executeRemoteRead(
     transport.close();
   }
   if (result.ok) {
+    // No line window can be present here (rejected above), so the server
+    // returned the whole file — the client-side hash is the same contract as
+    // the local capability's pre-window computation.
+    const pin = request.emitPin === true ? `sha256-${pinHashOf(result.content)}` : undefined;
     return renderReadOutcome(
       request,
-      { ok: true, result: { content: result.content, recoveryWarnings: [] } },
+      { ok: true, result: { content: result.content, ...(pin !== undefined ? { pin } : {}), recoveryWarnings: [] } },
       format,
       warnings,
     );

package/src/commands/rg.ts

@@ -282,7 +282,10 @@ async function executeMixedRg(
   const remoteOutcomes = new Map<string, RgEndpointOutcome>();
   // One transport pool for the whole invocation (W7 / O-5): same-origin door
   // bindings share a single ssh tunnel instead of one per row.
-  const pool = createTransportPool({ registryPath: context.registryPath });
+  const pool = createTransportPool({
+    registryPath: context.registryPath,
+    ...(context.sshCommand === undefined ? {} : { sshCommand: context.sshCommand }),
+  });
   try {
     for (const binding of remotes) {
       if (interrupted) {

package/src/commands/search.ts

@@ -223,7 +223,10 @@ async function executeMixedSearch(
   const remoteOutcomes = new Map<string, SearchEndpointOutcome>();
   // One transport pool for the whole invocation (W7 / O-5): same-origin door
   // bindings share a single ssh tunnel instead of one per row.
-  const pool = createTransportPool({ registryPath: context.registryPath });
+  const pool = createTransportPool({
+    registryPath: context.registryPath,
+    ...(context.sshCommand === undefined ? {} : { sshCommand: context.sshCommand }),
+  });
   try {
     for (const binding of remotes) {
       const token = resolveRemoteToken(binding);