@hediet/linkrpc-cli 0.0.1

package/dist/chunks/runComplete-BkQwzPbF.js

@@ -0,0 +1,3949 @@
+import { ErrorCode, InMemoryManagedIdentity, JsonRpcChannel, RpcError, SigningSender, TransportPair, capabilityFreshAt, computeInterfaceHash, defineInterface, isAssignable, permissionMatchesTarget, requestType, traceMessageTransport } from "@hediet/linkrpc";
+import { z } from "zod";
+import { LINKRPC_ENDPOINT_VAR, LINKRPC_TOKEN_VAR, WebSocketTransport, connectNdjson, createManagedPrincipal, createSelfManagedPrincipal, createSelfManagedPrincipalFromFile, isHubEndpoint, loadOrCreateIdentity, openWebSocket, parseEndpointUri, runInitializeHandshake } from "@hediet/linkrpc/node";
+import { Hub, HubConnectionAcceptor, RootOverlay, anonymousHandler, createHubServiceInterfaces, registerHubServices, registerIdentityServices } from "@hediet/linkrpc-hub/hub/server/client";
+import { SocketServer } from "@hediet/linkrpc-hub/hub/server/node";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import * as fs$1 from "node:fs";
+import * as os from "node:os";
+import * as path$1 from "node:path";
+import { resolve } from "node:path";
+import { spawnCommand, spawnCommand as spawnCommand$1 } from "@hediet/linkrpc-hub/spawn";
+import { tapTransport } from "@hediet/linkrpc-hub/hub/server/transit";
+import * as net from "node:net";
+import "@hediet/linkrpc-hub/config";
+import * as fs from "node:fs/promises";
+import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { fetchSchema as fetchSchema$1, findMethodInSchema, hubAccessInterface, walkHub, walkHubDetailed } from "@hediet/linkrpc/hub/common";
+//#region src/mcpForward.interface.ts
+/**
+* Transparent MCP tunnel.
+*
+* A single long-lived {@link mcpForwardInterface.connect} request opens one MCP
+* session "leg". The MCP JSON-RPC byte stream rides the linkrpc `$stream` duplex
+* correlated to that request — **no MCP method is modeled here**. Payloads are
+* opaque JSON-RPC messages, exactly as MCP emits them, so the forwarder that
+* serves this interface stays dumb: it shuttles frames between a child process'
+* stdio and the stream without ever parsing them.
+*
+* Why one duplex stream instead of request/response per MCP message: MCP is
+* bidirectional and asynchronous (server-initiated `notifications/.../
+* list_changed`, sampling requests). `$stream` already provides an ordered,
+* request-correlated, cancellable duplex that the runtime keeps alive with
+* periodic pings, so one stream == one MCP session leg.
+*
+* Lifecycle:
+*  - The consumer (the aggregator) calls `connect()`, obtaining
+*    `{ result, send, cancel, onMessage }`.
+*  - `send({ frame })` carries a frame **to** the child (stdin);
+*    `onMessage(({ frame }) => …)` receives frames **from** the child (stdout).
+*  - Child exit → the forwarder resolves the request (`connect` returns) → the
+*    consumer drops the client.
+*  - Consumer dispose / service removed → `cancel()` → the forwarder kills the
+*    child.
+*
+* Lives in the CLI package because the producer (`hub mcp-forward`) is a CLI
+* command; the in-extension aggregator imports this contract from here too.
+*/
+const mcpForwardInterface = defineInterface({
+	id: "vscode.mcp-forward",
+	description: "Transparent MCP tunnel: one streaming request carries a full MCP JSON-RPC session as opaque duplex stream frames."
+}, { connect: requestType(z.object({ 
+/**
+* Advertised so a consumer can label/version the leg without
+* opening the inner MCP session. Purely informational.
+*/
+clientInfo: z.object({
+	name: z.string(),
+	version: z.string()
+}).optional() }), z.object({ 
+/** Informational server identity, if the forwarder knows it. */
+serverInfo: z.object({
+	name: z.string(),
+	version: z.string()
+}).optional() }), { description: "Open one MCP session leg. Resolves (void-ish) only when the session ends (child exits or the caller cancels). The MCP traffic is the stream, not the result." }).withStream({
+	client: z.object({ frame: z.unknown() }),
+	server: z.object({ frame: z.unknown() })
+}) });
+//#endregion
+//#region src/methodRef.ts
+/**
+* A method reference as accepted on the CLI: `[serviceId::][interfaceId::]name[@hash]`.
+*/
+var MethodRefWithOptHash = class MethodRefWithOptHash {
+	serviceId;
+	interfaceId;
+	methodName;
+	hash;
+	static parseMethodRef(input) {
+		if (input.length === 0) throw new Error("Method reference is empty.");
+		let hash;
+		let core = input;
+		const atIdx = input.lastIndexOf("@");
+		if (atIdx >= 0) {
+			const candidate = input.slice(atIdx + 1);
+			if (candidate.length > 0 && !candidate.includes("::")) {
+				hash = candidate;
+				core = input.slice(0, atIdx);
+			}
+		}
+		const parts = core.split("::");
+		if (parts.length === 0 || parts.some((p) => p.length === 0)) throw new Error(`Invalid method reference: "${input}"`);
+		if (parts.length > 3) throw new Error(`Invalid method reference: too many "::" separators in "${input}"`);
+		if (parts.length === 1) return new MethodRefWithOptHash(void 0, void 0, parts[0], hash);
+		if (parts.length === 2) return new MethodRefWithOptHash(void 0, parts[0], parts[1], hash);
+		return new MethodRefWithOptHash(parts[0], parts[1], parts[2], hash);
+	}
+	constructor(serviceId, interfaceId, methodName, hash) {
+		this.serviceId = serviceId;
+		this.interfaceId = interfaceId;
+		this.methodName = methodName;
+		this.hash = hash;
+	}
+	/** Method name as it goes on the wire (no hash, no whitespace). */
+	getMethodOnWire() {
+		if (this.serviceId !== void 0 && this.interfaceId !== void 0) return `${this.serviceId}::${this.interfaceId}::${this.methodName}`;
+		if (this.interfaceId !== void 0) return `${this.interfaceId}::${this.methodName}`;
+		return this.methodName;
+	}
+};
+//#endregion
+//#region src/paramParsing.ts
+function parseParamOverride(raw) {
+	const eq = raw.indexOf("=");
+	if (eq <= 0) throw new Error(`Invalid --param "${raw}" (expected key=value)`);
+	const key = raw.slice(0, eq);
+	const valueStr = raw.slice(eq + 1);
+	const path = key.split(".");
+	if (path.some((p) => p.length === 0)) throw new Error(`Invalid --param key "${key}" (empty segment)`);
+	return {
+		path,
+		value: parseScalar(valueStr)
+	};
+}
+function parseScalar(raw) {
+	if (raw.length === 0) return "";
+	const first = raw[0];
+	if (first === "\"" || first === "{" || first === "[" || first === "-" || first === "t" || first === "f" || first === "n" || first >= "0" && first <= "9") try {
+		return JSON.parse(raw);
+	} catch {}
+	return raw;
+}
+function mergeParams(opts) {
+	const base = opts.base !== void 0 ? cloneJson(opts.base) : void 0;
+	const overrides = opts.overrides ?? [];
+	if (overrides.length === 0) return base;
+	let root = base;
+	for (const raw of overrides) {
+		const { path, value } = parseParamOverride(raw);
+		root = setDeep(root, path, value);
+	}
+	return root;
+}
+function setDeep(root, path, value) {
+	if (path.length === 1) {
+		const target = asPlainObject(root) ?? {};
+		target[path[0]] = value;
+		return target;
+	}
+	const target = asPlainObject(root) ?? {};
+	const [head, ...rest] = path;
+	target[head] = setDeep(target[head], rest, value);
+	return target;
+}
+function asPlainObject(v) {
+	if (v && typeof v === "object" && !Array.isArray(v)) return v;
+}
+function cloneJson(v) {
+	if (v === void 0) return v;
+	return JSON.parse(JSON.stringify(v));
+}
+//#endregion
+//#region src/validation.ts
+/**
+* Validate a concrete value against an `SvcJsonSchema`. Reuses linkrpc's
+* structural assignability — the value is lowered to a closed, const-shaped
+* schema and then asked "is this assignable to the target?". This avoids
+* pulling in a separate JSON-Schema validator and stays consistent with how
+* the connection layer reasons about interface compatibility.
+*
+* Returns `undefined` if the value is valid, or a short reason string.
+*/
+function validateValueAgainstSchema(value, target, components = {}) {
+	const actual = valueToConstSchema(value);
+	try {
+		return isAssignable(actual, target, { schemas: components }) ? void 0 : "does not match schema";
+	} catch (e) {
+		return e.message;
+	}
+}
+/**
+* Lower a JSON value to the tightest `SvcJsonSchema` that matches only it.
+* Primitives become `{ const }`; arrays become tuples with `items: false`
+* (forbidding extras); objects become closed records with every property
+* required.
+*
+* `undefined` becomes the empty closed object — that's the
+* "no params supplied" case, which is only assignable to a target that has
+* no required properties.
+*/
+function valueToConstSchema(v) {
+	if (v === void 0) return {
+		type: "object",
+		properties: {},
+		additionalProperties: false
+	};
+	if (v === null || typeof v === "boolean" || typeof v === "number" || typeof v === "string") return { const: v };
+	if (Array.isArray(v)) return {
+		type: "array",
+		prefixItems: v.map(valueToConstSchema),
+		items: false
+	};
+	const obj = v;
+	const properties = {};
+	const required = [];
+	for (const [k, val] of Object.entries(obj)) {
+		properties[k] = valueToConstSchema(val);
+		required.push(k);
+	}
+	return {
+		type: "object",
+		properties,
+		required,
+		additionalProperties: false
+	};
+}
+/**
+* Walk `value` against `schema` and collect every mismatch we can pinpoint.
+* Returns `[]` on success. Each issue has a JSON-style path plus a single
+* line saying why that location is wrong — designed to be printed directly
+* under a "Param validation failed:" header.
+*
+* Coverage is best-effort: scalar / object / array / tuple / const / enum /
+* union / `$ref`. Unions report the branch with the fewest mismatches
+* (heuristic) so the user gets one concrete trail to fix instead of a
+* cascade of "no branch matched".
+*/
+function explainValidation(value, schema, components = {}) {
+	const issues = [];
+	_walk(value, schema, "", components, issues);
+	return issues;
+}
+function _walk(value, schema, path, components, out) {
+	if (schema === true) return;
+	if (schema === false) {
+		out.push({
+			path,
+			reason: "no value is valid here"
+		});
+		return;
+	}
+	if ("$ref" in schema) {
+		const resolved = _resolveRef(schema.$ref, components);
+		if (!resolved) {
+			out.push({
+				path,
+				reason: `unresolved $ref ${schema.$ref}`
+			});
+			return;
+		}
+		_walk(value, resolved, path, components, out);
+		return;
+	}
+	if ("const" in schema) {
+		if (!_jsonEq(value, schema.const)) out.push({
+			path,
+			reason: `expected ${_jsonShow(schema.const)}, got ${_describeValue(value)}`
+		});
+		return;
+	}
+	if ("enum" in schema) {
+		if (!schema.enum.some((v) => _jsonEq(value, v))) {
+			const opts = schema.enum.slice(0, 5).map(_jsonShow).join(" | ");
+			const more = schema.enum.length > 5 ? ` | …` : "";
+			out.push({
+				path,
+				reason: `expected one of ${opts}${more}, got ${_describeValue(value)}`
+			});
+		}
+		return;
+	}
+	if ("anyOf" in schema || "oneOf" in schema) {
+		const branches = "anyOf" in schema ? schema.anyOf : schema.oneOf;
+		let best;
+		for (const b of branches) {
+			const sub = [];
+			_walk(value, b, path, components, sub);
+			if (sub.length === 0) return;
+			if (!best || sub.length < best.length) best = sub;
+		}
+		if (best) out.push(...best);
+		else out.push({
+			path,
+			reason: "value does not match any union branch"
+		});
+		return;
+	}
+	switch (schema.type) {
+		case "null":
+			if (value !== null) out.push({
+				path,
+				reason: `expected null, got ${_describeValue(value)}`
+			});
+			return;
+		case "boolean":
+			if (typeof value !== "boolean") out.push({
+				path,
+				reason: `expected boolean, got ${_describeValue(value)}`
+			});
+			return;
+		case "number":
+			if (typeof value !== "number") out.push({
+				path,
+				reason: `expected number, got ${_describeValue(value)}`
+			});
+			return;
+		case "integer":
+			if (typeof value !== "number" || !Number.isInteger(value)) out.push({
+				path,
+				reason: `expected integer, got ${_describeValue(value)}`
+			});
+			return;
+		case "string":
+			if (typeof value !== "string") out.push({
+				path,
+				reason: `expected string, got ${_describeValue(value)}`
+			});
+			return;
+		case "array":
+			_walkArray(value, schema, path, components, out);
+			return;
+		case "object":
+			_walkObject(value, schema, path, components, out);
+			return;
+		default: out.push({
+			path,
+			reason: "does not match schema"
+		});
+	}
+}
+function _walkObject(value, schema, path, components, out) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		out.push({
+			path: path || "(root)",
+			reason: `expected object, got ${_describeValue(value)}`
+		});
+		return;
+	}
+	const obj = value;
+	for (const req of schema.required ?? []) if (!(req in obj)) {
+		const p = _joinKey(path, req);
+		const propSchema = schema.properties[req];
+		const typeHint = propSchema ? ` (${_typeHint(propSchema, components)})` : "";
+		out.push({
+			path: p,
+			reason: `required${typeHint}, but missing`
+		});
+	}
+	for (const [k, v] of Object.entries(obj)) {
+		const propSchema = schema.properties[k];
+		const p = _joinKey(path, k);
+		if (propSchema !== void 0) _walk(v, propSchema, p, components, out);
+		else if (schema.additionalProperties === false) out.push({
+			path: p,
+			reason: "unknown property"
+		});
+		else _walk(v, schema.additionalProperties, p, components, out);
+	}
+}
+function _walkArray(value, schema, path, components, out) {
+	if (!Array.isArray(value)) {
+		out.push({
+			path: path || "(root)",
+			reason: `expected array, got ${_describeValue(value)}`
+		});
+		return;
+	}
+	const prefix = schema.prefixItems ?? [];
+	for (let i = 0; i < value.length; i++) if (i < prefix.length) _walk(value[i], prefix[i], `${path}[${i}]`, components, out);
+	else if (schema.items === false) out.push({
+		path: `${path}[${i}]`,
+		reason: "extra element (tuple is closed)"
+	});
+	else if (schema.items !== void 0) _walk(value[i], schema.items, `${path}[${i}]`, components, out);
+	if (prefix.length > 0 && value.length < prefix.length && schema.items === false) out.push({
+		path: path || "(root)",
+		reason: `expected tuple of length ${prefix.length}, got ${value.length}`
+	});
+}
+/**
+* Render an `SvcJsonSchema` as a short, copy-paste-friendly type expression.
+* Used as a hint next to required-property errors (`"name required (string)"`)
+* and as the "Expected" footer when full-on params reporting fires.
+*/
+function describeSchema(schema, components = {}, depth = 0) {
+	if (schema === true) return "any";
+	if (schema === false) return "never";
+	if ("$ref" in schema) return schema.$ref.split("/").pop() ?? schema.$ref;
+	if ("const" in schema) return _jsonShow(schema.const);
+	if ("enum" in schema) return schema.enum.slice(0, 6).map(_jsonShow).join(" | ") + (schema.enum.length > 6 ? " | …" : "");
+	if ("anyOf" in schema || "oneOf" in schema) return ("anyOf" in schema ? schema.anyOf : schema.oneOf).map((b) => describeSchema(b, components, depth + 1)).join(" | ");
+	const t = schema.type;
+	switch (t) {
+		case "null":
+		case "boolean":
+		case "number":
+		case "integer":
+		case "string": return t;
+		case "array": {
+			const arr = schema;
+			if (arr.prefixItems && arr.prefixItems.length > 0) {
+				const head = arr.prefixItems.map((s) => describeSchema(s, components, depth + 1)).join(", ");
+				if (arr.items === false || arr.items === void 0) return `[${head}]`;
+				return `[${head}, …${describeSchema(arr.items, components, depth + 1)}]`;
+			}
+			return arr.items === false || arr.items === void 0 ? "[]" : `${describeSchema(arr.items, components, depth + 1)}[]`;
+		}
+		case "object": {
+			if (depth >= 2) return "object";
+			const obj = schema;
+			const reqSet = new Set(obj.required ?? []);
+			return `{ ${Object.entries(obj.properties).map(([k, v]) => {
+				return `${k}${reqSet.has(k) ? "" : "?"}: ${describeSchema(v, components, depth + 1)}`;
+			}).join("; ")} }`;
+		}
+	}
+	return "any";
+}
+/**
+* Multi-line table of an object schema's properties: name, required-marker,
+* type, and description. Used as the "Expected params:" footer printed under
+* a validation error. Returns `undefined` if `schema` is not an object —
+* fall back to a single `describeSchema` line in that case.
+*/
+function describeObjectParams(schema, components = {}) {
+	const resolved = _resolveTop(schema, components);
+	if (!resolved || typeof resolved !== "object" || !("type" in resolved) || resolved.type !== "object") return;
+	const obj = resolved;
+	const required = new Set(obj.required ?? []);
+	const rows = [];
+	for (const [k, v] of Object.entries(obj.properties)) {
+		const resolvedV = _resolveTop(v, components);
+		const desc = (resolvedV && typeof resolvedV === "object" && "description" in resolvedV ? resolvedV.description : void 0) ?? "";
+		rows.push({
+			name: k,
+			type: describeSchema(v, components, 1),
+			req: required.has(k) ? "required" : "optional",
+			desc
+		});
+	}
+	if (rows.length === 0) return "(no params)";
+	const nameW = Math.max(...rows.map((r) => r.name.length));
+	const typeW = Math.max(...rows.map((r) => r.type.length));
+	const reqW = Math.max(...rows.map((r) => r.req.length));
+	return rows.map((r) => {
+		const head = `  ${r.name.padEnd(nameW)}  ${r.type.padEnd(typeW)}  ${r.req.padEnd(reqW)}`;
+		return r.desc ? `${head}  ${r.desc}` : head;
+	}).join("\n");
+}
+function _resolveTop(schema, components) {
+	if (schema === true || schema === false) return schema;
+	if ("$ref" in schema) return _resolveRef(schema.$ref, components);
+	return schema;
+}
+function _resolveRef(ref, components) {
+	if (!ref.startsWith("#/components/schemas/")) return void 0;
+	return components[ref.slice(21)];
+}
+function _typeHint(schema, components) {
+	return describeSchema(schema, components, 1);
+}
+function _joinKey(parent, key) {
+	if (/^[A-Za-z_$][\w$]*$/.test(key)) return `${parent}.${key}`;
+	return `${parent}[${JSON.stringify(key)}]`;
+}
+function _jsonEq(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+function _jsonShow(v) {
+	return typeof v === "string" ? JSON.stringify(v) : String(v);
+}
+function _describeValue(v) {
+	if (v === null) return "null";
+	if (v === void 0) return "undefined";
+	if (Array.isArray(v)) return `array (length ${v.length})`;
+	if (typeof v === "object") return "object";
+	if (typeof v === "string") return `string (${JSON.stringify(v.length > 40 ? v.slice(0, 37) + "…" : v)})`;
+	return `${typeof v} (${JSON.stringify(v)})`;
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/localHub.ts
+/** Default serviceId namespace the local-hub child may claim (and sees via `hubGrantedServiceId::get`). */
+const DEFAULT_LOCAL_NAMESPACE = "local";
+/** Subfolder (under the linkrpc data dir) holding provisioned identity slots. */
+const PROVISION_SUBDIR = "provisioned-identities";
+/** Provisioned slots untouched for longer than this are swept on next run. */
+const PROVISION_MAX_AGE_MS = 2592e6;
+/**
+* Start an in-process hub on a private socket, spawn `command` as a participant
+* (handing it the socket + token via `LINKRPC_ENDPOINT` / `LINKRPC_TOKEN`), and
+* resolve once the child has registered a service under {@link LOCAL_NAMESPACE}.
+*
+* The hub is single-tenant and local: no claim policy (every well-formed claim
+* is allowed) and no provenance. Identity is either ephemeral (fresh per run)
+* or, when `provisionSlot` is set, a persisted managed identity so the child's
+* HPKE wrap/unwrap keys survive across runs.
+*/
+async function startLocalHub(opts) {
+	const resolveIdentity = _makeIdentityResolver(opts.provisionSlot);
+	const grantedNs = DEFAULT_LOCAL_NAMESPACE;
+	const hub = new Hub();
+	createHubServiceInterfaces(hub);
+	const socketPath = SocketServer.allocSocketPath();
+	const token = randomBytes(16).toString("hex");
+	const socketServer = await SocketServer.start({ endpoint: socketPath });
+	const acceptor = new HubConnectionAcceptor({
+		server: socketServer,
+		hub,
+		handlers: [anonymousHandler({
+			grantedServiceIdNamespace: grantedNs,
+			...resolveIdentity ? { resolveIdentity } : {}
+		})]
+	});
+	const child = spawnCommand(opts.command, {
+		stdio: [
+			"inherit",
+			"inherit",
+			"inherit"
+		],
+		env: {
+			...process.env,
+			...opts.env,
+			LINKRPC_ENDPOINT: socketPath,
+			LINKRPC_TOKEN: token
+		},
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
+	});
+	let childExited = false;
+	child.once("exit", () => {
+		childExited = true;
+	});
+	const dispose = () => {
+		if (!child.killed) child.kill();
+		acceptor.dispose();
+		socketServer.dispose();
+		if (process.platform !== "win32") try {
+			fs$1.unlinkSync(socketPath);
+		} catch {}
+	};
+	try {
+		await _waitForClaim(hub, grantedNs, () => childExited, opts.readyTimeoutMs ?? 3e4);
+	} catch (e) {
+		dispose();
+		throw e;
+	}
+	return {
+		socketPath,
+		token,
+		dispose
+	};
+}
+/**
+* The overlay's claim front door has no routing table to write: the tunnel owns
+* the real claim on the source hub, and the splitter relays every uplink request
+* to the child regardless. So `hubGrantedServiceId::register` succeeds as a
+* no-op through this stub link.
+*/
+const _noopUpstream = {
+	claimPrefix: () => {},
+	releasePrefix: () => false,
+	edgeId: "overlay-uplink",
+	dispose: () => {}
+};
+async function startLocalOverlay(opts) {
+	const resolveIdentity = _makeIdentityResolver(opts.provisionSlot);
+	const socketPath = SocketServer.allocSocketPath();
+	const token = randomBytes(16).toString("hex");
+	const socketServer = await SocketServer.start({ endpoint: socketPath });
+	const accepted = new Promise((resolve) => {
+		socketServer.setConnectionHandler((t) => resolve(t));
+	});
+	const child = spawnCommand(opts.command, {
+		stdio: [
+			"ignore",
+			"inherit",
+			"inherit"
+		],
+		env: {
+			...process.env,
+			...opts.env,
+			LINKRPC_ENDPOINT: socketPath,
+			LINKRPC_TOKEN: token
+		},
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
+	});
+	const pair = new TransportPair();
+	const overlay = new RootOverlay({ uplink: pair.a });
+	registerHubServices(overlay.root, _noopUpstream, { grantedServiceIdNamespace: opts.grantedNamespace });
+	if (resolveIdentity !== void 0) registerIdentityServices(overlay.root, { resolveIdentity });
+	const dispose = () => {
+		if (!child.killed) child.kill();
+		overlay.dispose();
+		pair.a.dispose();
+		pair.b.dispose();
+		socketServer.dispose();
+		if (process.platform !== "win32") try {
+			fs$1.unlinkSync(socketPath);
+		} catch {}
+	};
+	const childTransport = await Promise.race([accepted, new Promise((_resolve, reject) => {
+		child.once("exit", (code) => reject(/* @__PURE__ */ new Error(`overlay: cmd-env child exited (code ${code ?? "?"}) before connecting`)));
+	})]).catch((err) => {
+		dispose();
+		throw err;
+	});
+	overlay.connectParticipant(childTransport);
+	return {
+		uplink: pair.b,
+		dispose
+	};
+}
+/**
+* Build the hub's `resolveIdentity`, or `undefined` when no identity should be
+* provided. Without `provisionSlot` the hub serves no identity at all — a child
+* that needs `identity::*` will fail. With it, a single persisted managed
+* identity is shared by all connections (stale slots swept first), so the
+* child's HPKE wrap/unwrap keys survive across runs.
+*/
+function _makeIdentityResolver(provisionSlot) {
+	if (provisionSlot === void 0) return;
+	const dir = _provisionDir();
+	_sweepProvisionedIdentities(dir);
+	let shared;
+	return () => {
+		if (!shared) shared = (async () => {
+			const persisted = await loadOrCreateIdentity({
+				id: provisionSlot,
+				storeDir: dir
+			});
+			return new InMemoryManagedIdentity(persisted.keypair, persisted.wrapKeypair);
+		})();
+		return shared;
+	};
+}
+/** Resolve the slot id for a `--provision-identity` / `--provision-identity-slot` run. */
+function resolveProvisionSlot(explicitSlot, provisionIdentity, commandString) {
+	if (explicitSlot !== void 0) return explicitSlot;
+	if (provisionIdentity) return JSON.stringify({
+		cwd: process.cwd(),
+		cmdStr: commandString
+	});
+}
+/** Dedicated provisioned-identity folder (sibling of linkrpc's user identities). */
+function _provisionDir() {
+	const home = os.homedir();
+	let base;
+	if (process.platform === "win32") base = process.env.APPDATA ?? path$1.join(home, "AppData", "Roaming");
+	else if (process.platform === "darwin") base = path$1.join(home, "Library", "Application Support");
+	else base = process.env.XDG_CONFIG_HOME ?? path$1.join(home, ".config");
+	return path$1.join(base, "linkrpc", PROVISION_SUBDIR);
+}
+/** Delete provisioned identity files whose mtime is older than the max age. */
+function _sweepProvisionedIdentities(dir) {
+	let entries;
+	try {
+		entries = fs$1.readdirSync(dir);
+	} catch {
+		return;
+	}
+	const cutoff = Date.now() - PROVISION_MAX_AGE_MS;
+	for (const name of entries) {
+		if (!name.endsWith(".json")) continue;
+		const file = path$1.join(dir, name);
+		try {
+			if (fs$1.statSync(file).mtimeMs < cutoff) fs$1.unlinkSync(file);
+		} catch {}
+	}
+}
+/** Resolve once the child claims `prefix` (or a sub-prefix), else reject. */
+function _waitForClaim(hub, prefix, childExited, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	return new Promise((resolve, reject) => {
+		const check = () => {
+			if (hub.claimedPrefixes().some((p) => p === prefix || p.startsWith(`${prefix}/`))) {
+				resolve();
+				return;
+			}
+			if (childExited()) {
+				reject(/* @__PURE__ */ new Error("connect: command exited before registering a service"));
+				return;
+			}
+			if (Date.now() >= deadline) {
+				reject(/* @__PURE__ */ new Error(`connect: timed out waiting for command to register a service under '${prefix}'`));
+				return;
+			}
+			setTimeout(check, 50);
+		};
+		check();
+	});
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/endpoint.ts
+/**
+* Endpoint resolution for the CLI = "where the linkrpc server lives, and how to
+* reach (or start) it". The parsed truth is the {@link ResolvedEndpoint} union from
+* `@hediet/linkrpc/node`; this module turns the ergonomic flags / env vars into
+* one.
+*
+* Sources, highest precedence first:
+*   1. `--endpoint-cmd <command>`        → spawn a server, connect via injected env
+*   2. `--endpoint-cmd-stdio <command>`  → spawn a child, talk over its stdio
+*   3. `--endpoint <uri>`                → a literal strict endpoint URI
+*   4. `LINKRPC_ENDPOINT` / `HUBRPC_ENDPOINT` env vars → bare path / ws url
+*
+* `--endpoint-token` only applies to socket / ws endpoint URIs that contain an
+* exact `token=%` placeholder. Env vars support both `LINKRPC_*` and legacy
+* `HUBRPC_*`, with `LINKRPC_*` taking precedence. At most one of `--endpoint*`
+* may be given.
+* `ws-no-init:` preserves its query string verbatim and therefore does not use
+* `--endpoint-token`.
+*/
+const LEGACY_ENDPOINT_VAR = "HUBRPC_ENDPOINT";
+const LEGACY_TOKEN_VAR = "HUBRPC_TOKEN";
+const TOKEN_PLACEHOLDER = "%";
+const TOKEN_PLACEHOLDER_PATTERN = /(?:[?&])token=(?<value>[^&#]*)/g;
+/** Apply a token override to socket / ws specs; commands carry no token. */
+function _withToken(spec, token) {
+	if (token === void 0) return spec;
+	if (spec.kind === "socket") return {
+		...spec,
+		token
+	};
+	if (spec.kind === "ws") return {
+		...spec,
+		token
+	};
+	return spec;
+}
+function _getEnvValue(env, currentName, legacyName) {
+	return env[currentName] ?? env[legacyName];
+}
+function _resolveUriEndpoint(uri, tokenOverride, fallbackToken, tokenFlagName, endpointName) {
+	const spec = parseEndpointUri(uri);
+	if (tokenOverride !== void 0) return _applyTokenOverride(spec, uri, tokenOverride, tokenFlagName, endpointName);
+	const rawTokenParams = [...uri.matchAll(TOKEN_PLACEHOLDER_PATTERN)].map((match) => match.groups?.value ?? "");
+	if (rawTokenParams.includes(TOKEN_PLACEHOLDER)) {
+		if (rawTokenParams.length !== 1) throw new Error(`${endpointName} must contain at most one token parameter`);
+		if (fallbackToken === void 0) throw new Error(`${endpointName} contains token=% but no token value was provided`);
+		return _withToken(spec, fallbackToken);
+	}
+	return _withToken(spec, ("token" in spec ? spec.token : void 0) ?? fallbackToken);
+}
+function _applyTokenOverride(spec, uri, token, tokenFlagName, endpointName) {
+	if (spec.kind !== "socket" && spec.kind !== "ws") throw new Error(`${tokenFlagName} is only supported for socket/unix/npipe and ws/wss ${endpointName} values`);
+	if (token === TOKEN_PLACEHOLDER) throw new Error(`${tokenFlagName} must not be '${TOKEN_PLACEHOLDER}'`);
+	const tokenParams = [...uri.matchAll(TOKEN_PLACEHOLDER_PATTERN)].map((m) => m.groups?.value ?? "");
+	if (tokenParams.length !== 1 || tokenParams[0] !== TOKEN_PLACEHOLDER) throw new Error(`${tokenFlagName} requires ${endpointName} to contain exactly '?token=%' or '&token=%'`);
+	return _withToken(spec, token);
+}
+/**
+* Resolve the effective endpoint from flags + environment. Returns
+* `{ endpoint: undefined }` when nothing is configured (the caller may then
+* error out). Mutually-exclusive `--endpoint*` flags yield an `error`.
+*/
+function resolveEndpoint(input) {
+	const env = input.env ?? process.env;
+	const envEndpoint = _getEnvValue(env, LINKRPC_ENDPOINT_VAR, LEGACY_ENDPOINT_VAR);
+	if ([
+		input.endpoint,
+		input.endpointCmd,
+		input.endpointCmdStdio
+	].filter((v) => v !== void 0).length > 1) return {
+		endpoint: void 0,
+		error: "specify at most one of --endpoint, --endpoint-cmd, --endpoint-cmd-stdio"
+	};
+	if ((input.provisionIdentity === true || input.provisionIdentitySlot !== void 0) && input.endpointCmd === void 0 && input.provisioningHandledElsewhere !== true) return {
+		endpoint: void 0,
+		error: "--provision-identity / --provision-identity-slot require --endpoint-cmd"
+	};
+	if (input.endpointToken !== void 0 && input.endpoint === void 0 && envEndpoint === void 0) return {
+		endpoint: void 0,
+		error: "--endpoint-token requires --endpoint or an endpoint environment variable containing token=%"
+	};
+	const cmdEnv = input.endpointCmdEnv;
+	const cmdCwd = input.endpointCmdCwd;
+	if (cmdEnv !== void 0 && Object.keys(cmdEnv).length > 0 && input.endpointCmd === void 0 && input.endpointCmdStdio === void 0) return {
+		endpoint: void 0,
+		error: "--endpoint-cmd-env requires --endpoint-cmd or --endpoint-cmd-stdio"
+	};
+	if (cmdCwd !== void 0 && input.endpointCmd === void 0 && input.endpointCmdStdio === void 0) return {
+		endpoint: void 0,
+		error: "--endpoint-cmd-cwd requires --endpoint-cmd or --endpoint-cmd-stdio"
+	};
+	try {
+		if (input.endpointCmd !== void 0) {
+			const provisionSlot = resolveProvisionSlot(input.provisionIdentitySlot, input.provisionIdentity === true, input.endpointCmd);
+			return {
+				endpoint: {
+					kind: "cmd-env",
+					command: { command: input.endpointCmd },
+					...provisionSlot !== void 0 ? { provisionSlot } : {},
+					...cmdEnv !== void 0 ? { env: cmdEnv } : {},
+					...cmdCwd !== void 0 ? { cwd: cmdCwd } : {}
+				},
+				error: void 0
+			};
+		}
+		if (input.endpointCmdStdio !== void 0) return {
+			endpoint: {
+				kind: "cmd-stdio",
+				command: { command: input.endpointCmdStdio },
+				...cmdEnv !== void 0 ? { env: cmdEnv } : {},
+				...cmdCwd !== void 0 ? { cwd: cmdCwd } : {}
+			},
+			error: void 0
+		};
+		if (input.endpoint !== void 0) return {
+			endpoint: _resolveUriEndpoint(input.endpoint, input.endpointToken, void 0, "--endpoint-token", "--endpoint"),
+			error: void 0
+		};
+		if (envEndpoint) return {
+			endpoint: _resolveUriEndpoint(envEndpoint, input.endpointToken, _getEnvValue(env, LINKRPC_TOKEN_VAR, LEGACY_TOKEN_VAR), "--endpoint-token", `${LINKRPC_ENDPOINT_VAR}/${LEGACY_ENDPOINT_VAR}`),
+			error: void 0
+		};
+	} catch (e) {
+		return {
+			endpoint: void 0,
+			error: e.message
+		};
+	}
+	return {
+		endpoint: void 0,
+		error: void 0
+	};
+}
+/**
+* Resolve a *target* endpoint from `--target-*` flags. Mirrors
+* {@link resolveEndpoint} for tunnel-style commands that have both a source
+* (the hub the CLI claims on) and a target (the implementation that handles
+* inbound requests). Returns `{ endpoint: undefined }` when no `--target-*`
+* flag is set so the caller can error with a command-specific message.
+*
+* Unlike {@link resolveEndpoint}, no env-var fallback is consulted \u2014 the
+* target is always explicit.
+*/
+function resolveTargetEndpoint(input) {
+	if ([
+		input.targetEndpoint,
+		input.targetEndpointCmd,
+		input.targetEndpointCmdStdio
+	].filter((v) => v !== void 0).length > 1) return {
+		endpoint: void 0,
+		error: "specify at most one of --target-endpoint, --target-endpoint-cmd, --target-endpoint-cmd-stdio"
+	};
+	if ((input.provisionIdentity === true || input.provisionIdentitySlot !== void 0) && input.targetEndpointCmd === void 0) return {
+		endpoint: void 0,
+		error: "--provision-identity / --provision-identity-slot require --target-endpoint-cmd"
+	};
+	if (input.targetEndpointToken !== void 0 && input.targetEndpoint === void 0) return {
+		endpoint: void 0,
+		error: "--target-endpoint-token requires --target-endpoint containing token=%"
+	};
+	const cmdEnv = input.targetEndpointCmdEnv;
+	const cmdCwd = input.targetEndpointCmdCwd;
+	if (cmdEnv !== void 0 && Object.keys(cmdEnv).length > 0 && input.targetEndpointCmd === void 0 && input.targetEndpointCmdStdio === void 0) return {
+		endpoint: void 0,
+		error: "--target-endpoint-cmd-env requires --target-endpoint-cmd or --target-endpoint-cmd-stdio"
+	};
+	if (cmdCwd !== void 0 && input.targetEndpointCmd === void 0 && input.targetEndpointCmdStdio === void 0) return {
+		endpoint: void 0,
+		error: "--target-endpoint-cmd-cwd requires --target-endpoint-cmd or --target-endpoint-cmd-stdio"
+	};
+	try {
+		if (input.targetEndpointCmd !== void 0) {
+			const provisionSlot = resolveProvisionSlot(input.provisionIdentitySlot, input.provisionIdentity === true, input.targetEndpointCmd);
+			return {
+				endpoint: {
+					kind: "cmd-env",
+					command: { command: input.targetEndpointCmd },
+					...provisionSlot !== void 0 ? { provisionSlot } : {},
+					...cmdEnv !== void 0 ? { env: cmdEnv } : {},
+					...cmdCwd !== void 0 ? { cwd: cmdCwd } : {}
+				},
+				error: void 0
+			};
+		}
+		if (input.targetEndpointCmdStdio !== void 0) return {
+			endpoint: {
+				kind: "cmd-stdio",
+				command: { command: input.targetEndpointCmdStdio },
+				...cmdEnv !== void 0 ? { env: cmdEnv } : {},
+				...cmdCwd !== void 0 ? { cwd: cmdCwd } : {}
+			},
+			error: void 0
+		};
+		if (input.targetEndpoint !== void 0) return {
+			endpoint: _resolveUriEndpoint(input.targetEndpoint, input.targetEndpointToken, void 0, "--target-endpoint-token", "--target-endpoint"),
+			error: void 0
+		};
+	} catch (e) {
+		return {
+			endpoint: void 0,
+			error: e.message
+		};
+	}
+	return {
+		endpoint: void 0,
+		error: void 0
+	};
+}
+/**
+* Lower a resolved endpoint into a declarative {@link EndpointConfig} entry,
+* applying the given routing fields. Used by `tunnel -c, --config` to append
+* the source hub to a loaded config as a claiming endpoint, so the in-process
+* hub registers the service id on the source and routes its inbound calls
+* through the config-described target.
+*
+* A `cmd-env` endpoint's `provisionSlot` is carried over as a slotted managed
+* identity so the claim signs with a persistent identity.
+*/
+function resolvedEndpointToConfig(spec, routing) {
+	const claimServiceIds = [...routing.claimServiceIds];
+	switch (spec.kind) {
+		case "socket": return {
+			kind: "socket",
+			path: spec.path,
+			...spec.token !== void 0 ? { token: spec.token } : {},
+			routeServiceIds: [],
+			claimServiceIds,
+			defaultRoute: false
+		};
+		case "ws": return {
+			kind: "ws",
+			url: spec.url,
+			...spec.token !== void 0 ? { token: spec.token } : {},
+			routeServiceIds: [],
+			claimServiceIds,
+			defaultRoute: false
+		};
+		case "ws-no-init": throw new Error("ws-no-init endpoints cannot be used as declarative hub routes");
+		case "cmd-env": return {
+			kind: "cmd-env",
+			..._commandFields(spec.command),
+			...spec.env !== void 0 ? { env: { ...spec.env } } : {},
+			...spec.cwd !== void 0 ? { cwd: spec.cwd } : {},
+			routeServiceIds: [],
+			claimServiceIds,
+			defaultRoute: false,
+			...spec.provisionSlot !== void 0 ? { managedIdentity: { slot: spec.provisionSlot } } : {}
+		};
+		case "cmd-stdio": return {
+			kind: "cmd-stdio",
+			..._commandFields(spec.command),
+			...spec.env !== void 0 ? { env: { ...spec.env } } : {},
+			...spec.cwd !== void 0 ? { cwd: spec.cwd } : {},
+			routeServiceIds: [],
+			claimServiceIds,
+			defaultRoute: false
+		};
+	}
+}
+/** Lower an {@link EndpointCommand} into the config's `cmd` / `argv` fields. */
+function _commandFields(command) {
+	return "command" in command ? { cmd: command.command } : { argv: [...command.argv] };
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/connect.ts
+async function connect(endpoint, log) {
+	switch (endpoint.kind) {
+		case "cmd-stdio": return _connectCmdStdio(endpoint.command, endpoint.env, endpoint.cwd, log);
+		case "cmd-env": return _connectCmdEnv(endpoint.command, endpoint.provisionSlot, endpoint.env, endpoint.cwd, log);
+		case "ws": return _connectWs(endpoint, log);
+		case "ws-no-init": return _connectWs(endpoint, log);
+		case "socket": return _connectSocket(endpoint.path, endpoint.token, log);
+	}
+}
+/**
+* Spawn a child from a command spec. `{ command }` is run through the OS shell
+* (so quoting / splitting follows the shell's rules); `{ argv }` is run
+* directly (no shell), except on Windows where `.cmd` shims need one.
+*/
+async function _connectCmdStdio(command, env, cwd, log) {
+	const child = spawnCommand$1(command, {
+		stdio: [
+			"pipe",
+			"pipe",
+			"inherit"
+		],
+		...env !== void 0 ? { env: {
+			...process.env,
+			...env
+		} } : {},
+		...cwd !== void 0 ? { cwd } : {}
+	});
+	if (!child.stdin || !child.stdout) throw new Error("connect: child process exposes no stdio");
+	const { transport } = await connectNdjson({
+		input: child.stdout,
+		output: child.stdin,
+		onClose: () => {
+			if (!child.killed) child.kill();
+		},
+		trace: log?.trace
+	});
+	return _makeCliConnection(transport, () => {
+		if (!child.killed) child.kill();
+	}, log);
+}
+/**
+* Start a private in-process hub, spawn the child as a participant, then
+* connect to the hub's socket. The child registers its services against the
+* hub exactly as it would against a remote one; we tear the hub + child down
+* when the connection closes.
+*/
+async function _connectCmdEnv(command, provisionSlot, env, cwd, log) {
+	return connectViaLocalHub({
+		command,
+		provisionSlot,
+		env,
+		cwd,
+		log
+	});
+}
+/**
+* Spawn a child under an in-process local hub (`startLocalHub`) and connect
+* to that hub over a socket. Backs the standard `cmd-env` endpoint path; the
+* hub + child are torn down when the connection closes.
+*/
+async function connectViaLocalHub(opts) {
+	const hub = await startLocalHub({
+		command: opts.command,
+		provisionSlot: opts.provisionSlot,
+		env: opts.env,
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {}
+	});
+	try {
+		const conn = await _connectSocket(hub.socketPath, hub.token, opts.log);
+		return {
+			...conn,
+			close: () => {
+				conn.close();
+				hub.dispose();
+			}
+		};
+	} catch (e) {
+		hub.dispose();
+		throw e;
+	}
+}
+/**
+* Connect to a spawned `cmd-env` child through a {@link startLocalOverlay}
+* RootOverlay instead of a full local hub. Root-form calls (`identity::*`,
+* `hubGrantedServiceId::*`, `hubrpc.directory`, `hubAccess`) are served locally;
+* every prefixed request/response is relayed over the returned connection's
+* channel. Used by `tunnel --target-endpoint-cmd`: the tunnel forwards each
+* claimed request onto this channel and the overlay delivers it to the child —
+* no hub, no `hub` service id, no claim-wait, but `identity::*` still served so
+* `--provision-identity` targets work.
+*/
+async function connectViaRootOverlay(opts) {
+	const overlay = await startLocalOverlay({
+		command: opts.command,
+		provisionSlot: opts.provisionSlot,
+		...opts.env !== void 0 ? { env: opts.env } : {},
+		...opts.cwd !== void 0 ? { cwd: opts.cwd } : {},
+		grantedNamespace: opts.grantedNamespace
+	});
+	return _makeCliConnection(overlay.uplink, overlay.dispose, opts.log);
+}
+function _connectWs(endpoint, log) {
+	return openWebSocket(endpoint.url).then(async (ws) => {
+		const closeWs = () => {
+			try {
+				ws.close();
+			} catch {}
+		};
+		const baseTransport = new WebSocketTransport(ws, closeWs);
+		const transport = log?.trace === void 0 ? baseTransport : traceMessageTransport(baseTransport, log.trace);
+		if (endpoint.kind === "ws") try {
+			await runInitializeHandshake(transport, {
+				kind: "client",
+				token: endpoint.token ?? ""
+			});
+		} catch (err) {
+			transport.dispose();
+			closeWs();
+			throw err;
+		}
+		return _makeCliConnection(transport, closeWs, log);
+	});
+}
+async function _connectSocket(socketPath, token, log) {
+	const socket = net.createConnection(socketPath);
+	await new Promise((resolve, reject) => {
+		const onConnect = () => {
+			socket.removeListener("error", onError);
+			resolve();
+		};
+		const onError = (error) => {
+			socket.removeListener("connect", onConnect);
+			socket.destroy();
+			reject(error);
+		};
+		socket.once("connect", onConnect);
+		socket.once("error", onError);
+	});
+	socket.on("error", () => socket.destroy());
+	const { transport } = await connectNdjson({
+		input: socket,
+		output: socket,
+		onClose: () => socket.destroy(),
+		initialize: {
+			kind: "client",
+			token: token ?? ""
+		},
+		trace: log?.trace
+	});
+	return _makeCliConnection(transport, () => socket.destroy(), log);
+}
+/**
+* In-memory connection — for tests. The caller hands us a transport already
+* wired to a server-side channel (typically via `TransportPair`).
+*/
+function connectViaTransport(transport) {
+	return _makeCliConnection(transport, () => {});
+}
+function _makeCliConnection(transport, onClose, log) {
+	const tapped = log?.log === void 0 ? transport : tapTransport(transport, {
+		log: log.log,
+		localLabel: "cli",
+		remoteLabel: log.remoteLabel ?? "peer",
+		...log.maxPayload !== void 0 ? { maxPayload: log.maxPayload } : {}
+	});
+	const signing = {};
+	const wrapped = SigningSender.wrapChannel(JsonRpcChannel.create(tapped), signing);
+	const channel = wrapped.sender;
+	return {
+		channel,
+		rpcChannel: wrapped,
+		signing,
+		setRequestHandler: (handler) => wrapped.setRequestHandler(handler),
+		close: () => {
+			channel.close();
+			onClose();
+		}
+	};
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/principal.ts
+/**
+* Identity slot the managed-with-fallback default falls back to when the peer
+* does not offer a managed identity overlay (e.g. a plain stdio server). Maps
+* to the same on-disk slot `logout` clears.
+*/
+const MANAGED_FALLBACK_USER_ID = "hubrpc-cli";
+/**
+* Parse a `--principal` value. `undefined` and `managed` both yield the
+* managed-with-fallback default. Throws on malformed input.
+*/
+function parsePrincipalSpec(raw) {
+	if (raw === void 0 || raw === "managed") return { kind: "managed" };
+	if (raw.startsWith("user:")) {
+		const id = raw.slice(5);
+		if (id === "") throw new Error("--principal \"user:<id>\" requires a non-empty id");
+		return {
+			kind: "user",
+			id
+		};
+	}
+	if (raw.startsWith("file:")) {
+		const path = raw.slice(5);
+		if (path === "") throw new Error("--principal \"file:<path>\" requires a non-empty path");
+		return {
+			kind: "file",
+			path
+		};
+	}
+	throw new Error(`invalid --principal "${raw}" (expected "managed", "user:<id>", or "file:<path>")`);
+}
+/**
+* Resolve a {@link PrincipalSpec} into a concrete {@link Principal}, given the
+* (signed) sender used to bootstrap a managed identity. Cheap/idempotent, so
+* it can be re-derived on each reconnect. Also reports the {@link PrincipalSource}
+* that was actually used, including whether `managed` fell back to a local key.
+*/
+async function resolvePrincipal(spec, sender) {
+	switch (spec.kind) {
+		case "managed": try {
+			return {
+				principal: await createManagedPrincipal(sender),
+				source: { kind: "managed" }
+			};
+		} catch {
+			return {
+				principal: await createSelfManagedPrincipal(MANAGED_FALLBACK_USER_ID),
+				source: {
+					kind: "managed-fallback",
+					userId: MANAGED_FALLBACK_USER_ID
+				}
+			};
+		}
+		case "user": return {
+			principal: await createSelfManagedPrincipal(spec.id),
+			source: {
+				kind: "user",
+				id: spec.id
+			}
+		};
+		case "file": return {
+			principal: await createSelfManagedPrincipalFromFile(spec.path),
+			source: {
+				kind: "file",
+				path: spec.path
+			}
+		};
+	}
+}
+/**
+* Render a one-line, human-readable description of the identity used to sign
+* calls, e.g. `managed (node abcd012345…)` or
+* `local user:hubrpc-cli (node abcd012345…)`. `nodeId` is truncated to its
+* first 10 characters.
+*/
+function formatPrincipalSource(source, nodeId) {
+	const node = `node ${nodeId.slice(0, 10)}…`;
+	switch (source.kind) {
+		case "managed": return `managed (${node})`;
+		case "managed-fallback": return `local user:${source.userId} (managed unavailable) (${node})`;
+		case "user": return `local user:${source.id} (${node})`;
+		case "file": return `local file:${source.path} (${node})`;
+	}
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/identity.ts
+/**
+* Stable slot id for the on-disk keypair used by the managed-with-fallback
+* default (and `--principal user:hubrpc-cli`). The same slot always loads the
+* same keypair so persistent caps issued by the hub keep working across CLI
+* invocations.
+*/
+/**
+* Delete the CLI's persistent identity keypair and its cached caps. The
+* next CLI command will mint a fresh keypair and trigger a new consent
+* modal. Returns the files that were removed (empty when there was no
+* stored state).
+*/
+async function logoutCliIdentity() {
+	const identity = await loadOrCreateIdentity({ id: MANAGED_FALLBACK_USER_ID });
+	const capsFile = _capsFile(identity.file);
+	const removed = [];
+	for (const f of [identity.file, capsFile]) try {
+		await fs.unlink(f);
+		removed.push(f);
+	} catch (e) {
+		if (e.code !== "ENOENT") throw e;
+	}
+	return removed;
+}
+function _capsFile(identityFile) {
+	return identityFile.replace(/\.json$/, ".caps.json");
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/reflection.ts
+async function fetchDefaults(channel) {
+	const raw = await channel.sendRequest("hubrpc.defaults::get", {});
+	if (!raw) return {};
+	return {
+		serviceId: raw.serviceId,
+		interfaceId: raw.interfaceId,
+		hash: raw.interfaceHash
+	};
+}
+//#endregion
+//#region ../../packages-private/linkrpc-client/src/hubSigning.ts
+/** How long before expiry to refresh a capability (2 seconds = transit + skew). */
+const CAP_FRESHNESS_MARGIN_MS = 2e3;
+/**
+* The reflection interfaces the CLI walks for `ls` / `schema` / `defaults`
+* / the TUI bus walk. We request all of them, across every service, in a
+* single up-front consent prompt so exploration doesn't re-prompt per
+* service id. See {@link requestReflectionAccess}.
+*/
+const REFLECTION_INTERFACE_IDS = [
+	"hubrpc.directory",
+	"hubrpc.schemas",
+	"hubrpc.defaults"
+];
+const TOPOLOGY_INTERFACE_ID = "hubrpc.topology";
+/**
+* Install signing on `signing` for any endpoint. Resolves the
+* {@link PrincipalSpec} into a concrete {@link Principal} (managed-with-
+* fallback, a user slot, or a file-backed keypair) and points the channel's
+* `SigningSender` at it so every outbound call is signed.
+*
+* When `negotiateHubCaps` is set (hub endpoints), it also ensures a persistent
+* `hubAccess` capability is cached on the principal's {@link CapBag} — requesting
+* one with a single signed round-trip on first run / cache miss. For hub
+* endpoints, it also installs a sign-time capability provider.
+*
+* By default (`autoNegotiatePerCall !== false`) that provider negotiates
+* per-call authority lazily using `callIntent` (method + params + nonce +
+* signedAtMs + optional interfaceHash), so one-shot grants can be pinned to the
+* exact call bytes being signed. Set `autoNegotiatePerCall: false` to disable
+* that: the provider then only presents caps already in the bag, and the caller
+* is expected to request access explicitly via
+* {@link SigningSession.requestAccess}.
+*/
+async function setupSigning(channel, signing, principalSpec, opts) {
+	const { principal, source: principalSource } = await resolvePrincipal(principalSpec, channel);
+	signing.principal = principal;
+	signing.oneShotCaps = void 0;
+	signing.capProvider = void 0;
+	const hubAccessMethod = `${hubAccessInterface.info.id}::requestAccess`;
+	const consumerPrincipalId = principal.id;
+	if (opts.negotiateHubCaps) {
+		let inAccessNegotiation = false;
+		const provider = async ({ method, params, nonce, signedAtMs, interfaceHash }) => {
+			let presentCaps = principal.capBag.capabilities;
+			presentCaps = presentCaps.filter((c) => capabilityFreshAt(c, signedAtMs, CAP_FRESHNESS_MARGIN_MS));
+			const present = presentCaps.length > 0 ? { capabilities: presentCaps } : {};
+			if (inAccessNegotiation) return {};
+			const call = _wireMethodToCall(method);
+			if (!call) return present;
+			if (call.serviceId === "" || call.interfaceId === hubAccessInterface.info.id) return present;
+			if (_capBagCovers(presentCaps, call)) return present;
+			if (opts.autoNegotiatePerCall === false) return present;
+			inAccessNegotiation = true;
+			try {
+				const granted = await _requestAccessForCall(channel, hubAccessMethod, consumerPrincipalId, {
+					call,
+					method,
+					params,
+					nonce,
+					signedAtMs,
+					interfaceHash
+				});
+				if (granted.length === 0) return present;
+				const oneShot = granted.filter(_isOneShotCap);
+				const persistent = granted.filter((c) => !_isOneShotCap(c));
+				if (persistent.length > 0) await principal.capBag.add(...persistent);
+				const durable = principal.capBag.capabilities.filter((c) => capabilityFreshAt(c, signedAtMs, CAP_FRESHNESS_MARGIN_MS));
+				if (oneShot.length > 0) return { capabilities: [...durable, ...oneShot] };
+				return durable.length > 0 ? { capabilities: durable } : {};
+			} catch (err) {
+				process.stderr.write(`linkrpc: capability negotiation skipped (${err.message})\n`);
+				return present;
+			} finally {
+				inAccessNegotiation = false;
+			}
+		};
+		signing.capProvider = provider;
+	}
+	return {
+		principal,
+		principalSource,
+		hubAccessMethod,
+		listGrants: () => principal.capBag.capabilities,
+		requestAccess: (req) => _sessionRequestAccess(channel, hubAccessMethod, principal, req)
+	};
+}
+/**
+* Up-front, explicit batched request for reflection access across *every*
+* service: `hubrpc.directory` / `hubrpc.schemas` / `hubrpc.defaults` with a
+* wildcard `serviceId` (`{ prefix: '' }`). One consent prompt covers the whole
+* bus, so `ls` / `schema` / `defaults` / the TUI walk stop re-prompting per
+* service id.
+*
+* Best-effort and fail-soft: a `denied` decision (or an open hub with no access
+* handler that rejects the call) is swallowed. Per-call auto-cap negotiation in
+* {@link setupSigning} then remains the fallback for individual gated calls.
+*
+* Returns the granted status so callers can log it; never throws.
+*/
+async function requestReflectionAccess(session, opts = {}) {
+	if (REFLECTION_INTERFACE_IDS.every((interfaceId) => _hasInterfaceAccess(session, interfaceId, { prefix: "" }))) return "granted";
+	try {
+		return (await session.requestAccess({
+			consumer: {
+				name: "linkrpc-cli",
+				purpose: "Reflect on every service exposed by the hub (ls / schema / defaults)."
+			},
+			permissions: REFLECTION_INTERFACE_IDS.map((id) => ({
+				target: {
+					serviceId: { prefix: "" },
+					interfaceId: { exact: id },
+					members: [{ prefix: "" }]
+				},
+				canInvoke: true
+			})),
+			duration: opts.duration ?? "persistent"
+		})).status === "granted" ? "granted" : "denied";
+	} catch {
+		return "skipped";
+	}
+}
+/**
+* Request topology access in one consent operation before fan-out begins.
+* Discovery mode needs both directory traversal and topology calls across the
+* bus; fixed-source mode requests topology only for those exact service ids.
+*/
+async function requestTopologyAccess(session, opts = {}) {
+	const sourceServiceIds = opts.sourceServiceIds === void 0 ? void 0 : [...new Set(opts.sourceServiceIds)].sort();
+	const targets = sourceServiceIds === void 0 ? [{ prefix: "" }] : sourceServiceIds.map((serviceId) => ({ exact: serviceId }));
+	const needsDirectory = sourceServiceIds === void 0;
+	if ((!needsDirectory || _hasInterfaceAccess(session, "hubrpc.directory", { prefix: "" })) && targets.every((target) => _hasInterfaceAccess(session, TOPOLOGY_INTERFACE_ID, target))) return "granted";
+	const permissions = [];
+	if (needsDirectory) permissions.push({
+		target: {
+			serviceId: { prefix: "" },
+			interfaceId: { exact: "hubrpc.directory" },
+			members: [{ prefix: "" }]
+		},
+		canInvoke: true
+	});
+	for (const serviceId of targets) permissions.push({
+		target: {
+			serviceId,
+			interfaceId: { exact: TOPOLOGY_INTERFACE_ID },
+			members: [{ prefix: "" }]
+		},
+		canInvoke: true
+	});
+	try {
+		return (await session.requestAccess({
+			consumer: {
+				name: "linkrpc-cli",
+				purpose: sourceServiceIds === void 0 ? "Discover and inspect the topology exposed by every service on the hub." : "Inspect topology for the selected services."
+			},
+			permissions,
+			duration: opts.duration ?? "persistent"
+		})).status === "granted" ? "granted" : "denied";
+	} catch {
+		return "skipped";
+	}
+}
+function _hasInterfaceAccess(session, interfaceId, requestedServiceId) {
+	const now = Date.now();
+	return session.listGrants().some((capability) => capability.audience === session.principal.id && capabilityFreshAt(capability, now, CAP_FRESHNESS_MARGIN_MS) && capability.permissions.some((permission) => {
+		if (permission.canInvoke !== true || permission.callBind !== void 0 || permission.params !== void 0 || permission.target.interfaceHash !== void 0 || !permission.target.members.some((member) => "prefix" in member && member.prefix === "")) return false;
+		if ("prefix" in requestedServiceId) {
+			const grantedServiceId = permission.target.serviceId;
+			return "prefix" in grantedServiceId && grantedServiceId.prefix === "" && permissionMatchesTarget({
+				serviceId: "",
+				interfaceId,
+				member: ""
+			}, permission);
+		}
+		return permissionMatchesTarget({
+			serviceId: requestedServiceId.exact,
+			interfaceId,
+			member: ""
+		}, permission);
+	}));
+}
+/** Parse a wire method into a {@link CallTarget}, or `undefined` for form-1/2. */
+function _wireMethodToCall(wireMethod) {
+	const parts = wireMethod.split("::");
+	if (parts.length !== 3) return void 0;
+	const [serviceId, interfaceId, member] = parts;
+	return {
+		serviceId,
+		interfaceId,
+		member
+	};
+}
+/** A cap is one-shot when any permission is pinned to a single call via `callBind`. */
+function _isOneShotCap(sc) {
+	return sc.permissions.some((p) => p.callBind !== void 0);
+}
+/** True when a durable (non-one-shot) cap in the bag authorises `target`. */
+function _capBagCovers(caps, target) {
+	return caps.some((sc) => !_isOneShotCap(sc) && sc.permissions.some((p) => permissionMatchesTarget(target, p)));
+}
+async function _requestAccessForCall(channel, hubAccessMethod, consumerPrincipalId, req) {
+	const result = await _sendRequestAccess(channel, hubAccessMethod, {
+		consumer: {
+			name: "linkrpc-cli",
+			principal: consumerPrincipalId,
+			purpose: `Invoke ${req.method}.`
+		},
+		permissions: [{
+			target: {
+				serviceId: { exact: req.call.serviceId },
+				interfaceId: { exact: req.call.interfaceId },
+				members: [{ exact: req.call.member }]
+			},
+			canInvoke: true,
+			callIntent: {
+				method: req.method,
+				params: req.params,
+				nonce: req.nonce,
+				signedAtMs: req.signedAtMs,
+				...req.interfaceHash !== void 0 ? { interfaceHash: req.interfaceHash } : {},
+				suggestion: "once"
+			}
+		}],
+		duration: "once"
+	});
+	if (result.status !== "granted") return [];
+	return result.capabilities ?? [];
+}
+async function _sendRequestAccess(channel, hubAccessMethod, params) {
+	return await _awaitWithApprovalNotice(channel.sendRequest(hubAccessMethod, params));
+}
+/** Delay before we tell the user an access request is parked awaiting approval. */
+const APPROVAL_NOTICE_DELAY_MS = 750;
+/**
+* Await a `hubAccess::requestAccess` round-trip, printing a one-line hint to
+* stderr if it doesn't resolve quickly. Access requests park at the hub until a
+* human approver (admin) decides them, so without this notice the CLI looks
+* hung — it blocks with no output until approval. Fast requests (auto-approved
+* / open hub) stay silent because the notice only fires after
+* {@link APPROVAL_NOTICE_DELAY_MS}.
+*/
+async function _awaitWithApprovalNotice(pending) {
+	const timer = setTimeout(() => {
+		process.stderr.write("linkrpc: access request sent — waiting for the hub admin to approve it...\n");
+	}, APPROVAL_NOTICE_DELAY_MS);
+	timer.unref?.();
+	try {
+		return await pending;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Backs {@link SigningSession.requestAccess}. Sends a batched
+* `hubAccess::requestAccess`, then adds any durable (non-one-shot) caps the hub
+* minted to the principal's cap bag so later calls present them automatically.
+*/
+async function _sessionRequestAccess(channel, hubAccessMethod, principal, req) {
+	const result = await _sendRequestAccess(channel, hubAccessMethod, {
+		consumer: {
+			...req.consumer,
+			principal: principal.id
+		},
+		permissions: req.permissions,
+		...req.duration !== void 0 ? { duration: req.duration } : {}
+	});
+	if (result.status === "granted") {
+		const capabilities = result.capabilities ?? [];
+		const durable = capabilities.filter((c) => !_isOneShotCap(c));
+		if (durable.length > 0) await principal.capBag.add(...durable);
+		return {
+			status: "granted",
+			capabilities,
+			addedDurable: durable.length
+		};
+	}
+	return {
+		status: result.status,
+		reason: result.reason
+	};
+}
+//#endregion
+//#region src/completions/directorySource.ts
+/**
+* Hub-backed source of completion candidates. Abstracted so the orchestrator
+* in {@link ./complete.ts} stays unit-testable: tests inject a hand-written
+* source, production wires {@link ChannelDirectorySource} which talks to a
+* live hub via the standard reflection helpers (with an optional file cache
+* provided by {@link ./cache}).
+*
+* The interface intentionally has three primitive operations:
+*   - {@link entries} — the bus snapshot (serviceId, interfaceId) pairs
+*   - {@link methodsOnInterface} — method names per (serviceId, interfaceId)
+*   - {@link paramNamesForMethod} — param property names per method
+*
+* Everything else (distinct serviceIds, interfaces-on-service) is derived
+* by the orchestrator. This keeps cache coordination trivial: one snapshot,
+* one per-interface schema fetch per (sid, iid).
+*/
+/** Distinct, sorted serviceIds (drops the empty `''` root). */
+function distinctServiceIds(entries) {
+	return [...new Set(entries.map((e) => e.serviceId).filter((s) => s.length > 0))].sort();
+}
+/** Distinct, sorted interface ids across all services. */
+function distinctInterfaceIds(entries) {
+	return [...new Set(entries.map((e) => e.interfaceId))].sort();
+}
+/** Distinct, sorted interface ids registered on a particular serviceId. */
+function interfacesOnService(entries, serviceId) {
+	return [...new Set(entries.filter((e) => e.serviceId === serviceId).map((e) => e.interfaceId))].sort();
+}
+/**
+* Live source: walks the hub once (memoized for the instance lifetime),
+* then derives every entry / methods lookup from that single snapshot +
+* lazy `fetchSchema` calls. Each (sid, iid) schema is fetched at most once
+* per instance regardless of how many downstream queries reference it.
+*/
+var ChannelDirectorySource = class {
+	_channel;
+	_walkPromise;
+	_schemaCache = /* @__PURE__ */ new Map();
+	constructor(_channel) {
+		this._channel = _channel;
+	}
+	entries() {
+		if (!this._walkPromise) this._walkPromise = walkHub(this._channel).then((listings) => listings.map((l) => ({
+			serviceId: l.serviceId,
+			interfaceId: l.interfaceId,
+			hash: l.hash
+		})));
+		return this._walkPromise;
+	}
+	async methodsOnInterface(serviceId, interfaceId) {
+		return (await this._fetchSchema(serviceId, interfaceId)).methods;
+	}
+	async paramNamesForMethod(serviceId, interfaceId, methodName) {
+		return (await this._fetchSchema(serviceId, interfaceId)).paramsByMethod.get(methodName) ?? [];
+	}
+	_fetchSchema(serviceId, interfaceId) {
+		const key = `${serviceId ?? ""}::${interfaceId}`;
+		let cached = this._schemaCache.get(key);
+		if (!cached) {
+			cached = (async () => {
+				const schema = await fetchSchema$1(this._channel, interfaceId, void 0, serviceId);
+				const methods = Object.keys(schema.methods).sort();
+				const paramsByMethod = /* @__PURE__ */ new Map();
+				for (const [name, method] of Object.entries(schema.methods)) {
+					const params = method.params;
+					if (typeof params === "object" && params !== null && params.type === "object") {
+						const props = params.properties ?? {};
+						paramsByMethod.set(name, Object.keys(props));
+					} else paramsByMethod.set(name, []);
+				}
+				return {
+					methods,
+					paramsByMethod
+				};
+			})();
+			this._schemaCache.set(key, cached);
+		}
+		return cached;
+	}
+};
+//#endregion
+//#region src/completions/parse.ts
+/** Whitespace per the simple POSIX rule (space, tab, newline). */
+function _isWs(ch) {
+	return ch === " " || ch === "	" || ch === "\n" || ch === "\r";
+}
+function tokenize(line) {
+	const tokens = [];
+	let i = 0;
+	while (i < line.length) {
+		while (i < line.length && _isWs(line[i])) i++;
+		if (i >= line.length) break;
+		const start = i;
+		const ch = line[i];
+		let text = "";
+		let quoted = false;
+		if (ch === "\"" || ch === "'") {
+			quoted = true;
+			const q = ch;
+			i++;
+			while (i < line.length && line[i] !== q) text += line[i++];
+			if (i < line.length) i++;
+		} else while (i < line.length && !_isWs(line[i])) text += line[i++];
+		tokens.push({
+			text,
+			start,
+			end: i,
+			quoted
+		});
+	}
+	return tokens;
+}
+/**
+* Split `line` at `point` (0-indexed cursor position) into a previous-tokens
+* list + a possibly in-progress current word. Cursor inside or at the end of
+* a token = that token is the current word; cursor in whitespace = no current
+* token, new empty word at this position.
+*/
+function parseLine(line, point) {
+	const tokens = tokenize(line);
+	const safePoint = Math.max(0, Math.min(line.length, point));
+	if (_isWs(safePoint > 0 ? line[safePoint - 1] : " ") || safePoint === 0) return {
+		tokens,
+		tokensBefore: tokens.filter((t) => t.end <= safePoint),
+		currentToken: void 0,
+		currentWordPrefix: ""
+	};
+	const cur = tokens.find((t) => t.start <= safePoint - 1 && safePoint - 1 < t.end);
+	if (!cur) return {
+		tokens,
+		tokensBefore: tokens.filter((t) => t.end <= safePoint),
+		currentToken: void 0,
+		currentWordPrefix: ""
+	};
+	return {
+		tokens,
+		tokensBefore: tokens.filter((t) => t.end <= cur.start),
+		currentToken: cur,
+		currentWordPrefix: cur.text.slice(0, safePoint - cur.start)
+	};
+}
+//#endregion
+//#region src/completions/tree.ts
+const ENDPOINT_GLOBAL_OPTIONS = [
+	{
+		name: "--endpoint",
+		takesValue: true,
+		valueType: "free",
+		description: "endpoint URI"
+	},
+	{
+		name: "--endpoint-cmd",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--endpoint-cmd-stdio",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--endpoint-cmd-env",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--endpoint-cmd-cwd",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--endpoint-token",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--context",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--context-set",
+		takesValue: false
+	},
+	{
+		name: "--new-context",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--schema",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--validation",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--use-env",
+		takesValue: false
+	},
+	{
+		name: "--no-use-env",
+		takesValue: false
+	},
+	{
+		name: "--provision-identity",
+		takesValue: false
+	},
+	{
+		name: "--provision-identity-slot",
+		takesValue: true,
+		valueType: "free"
+	},
+	{
+		name: "--principal",
+		takesValue: true,
+		valueType: "free",
+		description: "\"managed\", \"user:<id>\", or \"file:<path>\""
+	}
+];
+const HUB_GLOBAL_OPTIONS = [...ENDPOINT_GLOBAL_OPTIONS, {
+	name: "--config",
+	takesValue: true,
+	valueType: "free"
+}];
+const SHARED_COMMANDS = [
+	{
+		name: "ls",
+		description: "List services and interfaces.",
+		positionals: [],
+		options: [
+			{
+				name: "--interface",
+				takesValue: true,
+				valueType: "interfaceId"
+			},
+			{
+				name: "--service",
+				takesValue: true,
+				valueType: "serviceId"
+			},
+			{
+				name: "--depth",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--with-members",
+				takesValue: false
+			},
+			{
+				name: "--json",
+				takesValue: false
+			},
+			{
+				name: "--dump",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--dump-patches",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--stream",
+				takesValue: false
+			},
+			{
+				name: "--watch",
+				takesValue: false
+			}
+		]
+	},
+	{
+		name: "defaults",
+		description: "Print the preset service / interface.",
+		positionals: [],
+		options: [{
+			name: "--json",
+			takesValue: false
+		}]
+	},
+	{
+		name: "schema",
+		description: "Inspect, hash, and compare interface schemas.",
+		positionals: [{
+			name: "interfaceRef",
+			type: "interfaceRef"
+		}],
+		options: [],
+		subcommands: [
+			{
+				name: "show",
+				description: "Print an interface schema.",
+				positionals: [{
+					name: "interfaceRef",
+					type: "interfaceRef"
+				}],
+				options: [
+					{
+						name: "--method",
+						takesValue: true,
+						valueType: "free"
+					},
+					{
+						name: "--service",
+						takesValue: true,
+						valueType: "serviceId"
+					},
+					{
+						name: "--json",
+						takesValue: false
+					}
+				]
+			},
+			{
+				name: "hash",
+				description: "Hash a local schema.",
+				positionals: [{
+					name: "schema",
+					type: "free"
+				}],
+				options: []
+			},
+			{
+				name: "check-compat",
+				description: "Compare a local schema against the live one.",
+				positionals: [{
+					name: "interfaceId",
+					type: "interfaceId"
+				}, {
+					name: "local",
+					type: "free"
+				}],
+				options: []
+			}
+		]
+	},
+	{
+		name: "call",
+		description: "Invoke a request.",
+		positionals: [{
+			name: "methodRef",
+			type: "methodRef"
+		}],
+		options: [
+			{
+				name: "--params",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--param",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--no-validate",
+				takesValue: false
+			}
+		]
+	},
+	{
+		name: "notify",
+		description: "Fire a notification (no response).",
+		positionals: [{
+			name: "methodRef",
+			type: "methodRef"
+		}],
+		options: [
+			{
+				name: "--params",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--param",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--no-validate",
+				takesValue: false
+			}
+		]
+	},
+	{
+		name: "batch",
+		description: "Run sequential calls and notifications.",
+		positionals: [],
+		variadic: "free",
+		options: []
+	},
+	{
+		name: "connection",
+		description: "Manage persistent RPC connections.",
+		positionals: [],
+		options: [],
+		subcommands: [
+			{
+				name: "create",
+				description: "Create a persistent connection.",
+				positionals: [],
+				options: [
+					{
+						name: "--timeout",
+						takesValue: true,
+						valueType: "free"
+					},
+					{
+						name: "--ttl",
+						takesValue: true,
+						valueType: "free"
+					},
+					{
+						name: "--notification-limit",
+						takesValue: true,
+						valueType: "free"
+					}
+				]
+			},
+			{
+				name: "status",
+				description: "Show persistent connection status.",
+				positionals: [],
+				options: []
+			},
+			{
+				name: "notifications",
+				description: "Read buffered server notifications.",
+				positionals: [],
+				options: [
+					{
+						name: "--after",
+						takesValue: true,
+						valueType: "free"
+					},
+					{
+						name: "--wait",
+						takesValue: true,
+						valueType: "free"
+					},
+					{
+						name: "--follow",
+						takesValue: false
+					}
+				]
+			},
+			{
+				name: "destroy",
+				description: "Destroy a persistent connection.",
+				positionals: [],
+				options: []
+			}
+		]
+	},
+	{
+		name: "context",
+		description: "Show how the active context resolves, or modify its defaults.",
+		positionals: [],
+		options: [],
+		subcommands: [
+			{
+				name: "show",
+				description: "Show stored context defaults only.",
+				positionals: [],
+				options: []
+			},
+			{
+				name: "list",
+				description: "List stored contexts.",
+				positionals: [],
+				options: []
+			},
+			{
+				name: "set",
+				description: "Set values on the selected context.",
+				positionals: [],
+				options: [{
+					name: "--unset",
+					takesValue: true,
+					valueType: "free"
+				}]
+			},
+			{
+				name: "remove",
+				description: "Remove the selected context.",
+				positionals: [],
+				options: []
+			}
+		]
+	},
+	{
+		name: "ping",
+		description: "One reflection round-trip; prints latency.",
+		positionals: [],
+		options: []
+	},
+	{
+		name: "ui",
+		description: "Launch the terminal UI.",
+		positionals: [],
+		options: []
+	},
+	{
+		name: "completions",
+		description: "Print a shell completion script for the requested shell.",
+		positionals: [{
+			name: "shell",
+			type: "shell"
+		}],
+		options: []
+	},
+	{
+		name: "_complete",
+		description: "(internal) Emit completion candidates for a partial command line.",
+		positionals: [],
+		options: [{
+			name: "--line",
+			takesValue: true,
+			valueType: "free"
+		}, {
+			name: "--point",
+			takesValue: true,
+			valueType: "free"
+		}],
+		hidden: true
+	},
+	{
+		name: "connect",
+		description: "Legacy alias for connection create.",
+		positionals: [],
+		options: [
+			{
+				name: "--timeout",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--ttl",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--notification-limit",
+				takesValue: true,
+				valueType: "free"
+			}
+		]
+	},
+	{
+		name: "connection-status",
+		description: "Legacy alias for connection status.",
+		positionals: [],
+		options: []
+	},
+	{
+		name: "notifications",
+		description: "Legacy alias for connection notifications.",
+		positionals: [],
+		options: [
+			{
+				name: "--after",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--wait",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--follow",
+				takesValue: false
+			}
+		]
+	},
+	{
+		name: "disconnect",
+		description: "Legacy alias for connection destroy.",
+		positionals: [],
+		options: []
+	},
+	{
+		name: "hash",
+		description: "Legacy alias for schema hash.",
+		positionals: [{
+			name: "schema",
+			type: "free"
+		}],
+		options: []
+	},
+	{
+		name: "check-compat",
+		description: "Legacy alias for schema check-compat.",
+		positionals: [{
+			name: "interfaceId",
+			type: "interfaceId"
+		}, {
+			name: "local",
+			type: "free"
+		}],
+		options: []
+	}
+];
+const HUB_ONLY_COMMANDS = [
+	{
+		name: "topology",
+		description: "Inspect the merged transport topology.",
+		positionals: [],
+		options: [
+			{
+				name: "--source",
+				takesValue: true,
+				valueType: "serviceId"
+			},
+			{
+				name: "--depth",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--node",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--service",
+				takesValue: true,
+				valueType: "serviceId"
+			},
+			{
+				name: "--kind",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--search",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--format",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--json",
+				takesValue: false
+			},
+			{
+				name: "--stream",
+				takesValue: false
+			},
+			{
+				name: "--watch",
+				takesValue: false
+			}
+		],
+		subcommands: [{
+			name: "participants",
+			description: "List participant nodes.",
+			positionals: [],
+			options: [{
+				name: "--search",
+				takesValue: true,
+				valueType: "free"
+			}, {
+				name: "--json",
+				takesValue: false
+			}]
+		}]
+	},
+	{
+		name: "traffic",
+		description: "Observe participant traffic.",
+		positionals: [],
+		options: [],
+		subcommands: [{
+			name: "watch",
+			description: "Watch node-wide traffic.",
+			positionals: [],
+			options: [
+				{
+					name: "--search",
+					takesValue: true,
+					valueType: "free"
+				},
+				{
+					name: "--node",
+					takesValue: true,
+					valueType: "free"
+				},
+				{
+					name: "--method",
+					takesValue: true,
+					valueType: "free"
+				},
+				{
+					name: "--payloads",
+					takesValue: true,
+					valueType: "free"
+				},
+				{
+					name: "--format",
+					takesValue: true,
+					valueType: "free"
+				},
+				{
+					name: "--resume",
+					takesValue: true,
+					valueType: "free"
+				}
+			]
+		}]
+	},
+	{
+		name: "identity",
+		description: "Inspect the persistent principal used by connected CLI commands.",
+		positionals: [],
+		options: [],
+		subcommands: [{
+			name: "show",
+			description: "Show the resolved principal.",
+			positionals: [],
+			options: [{
+				name: "--json",
+				takesValue: false
+			}]
+		}]
+	},
+	{
+		name: "approval",
+		description: "Inspect and decide pending Hub access approval requests.",
+		positionals: [],
+		options: [],
+		subcommands: [
+			{
+				name: "requests",
+				description: "List pending requests.",
+				positionals: [],
+				options: [{
+					name: "--json",
+					takesValue: false
+				}]
+			},
+			{
+				name: "approve",
+				description: "Approve a pending request.",
+				positionals: [{
+					name: "request-id",
+					type: "free"
+				}],
+				options: [{
+					name: "--json",
+					takesValue: false
+				}]
+			},
+			{
+				name: "deny",
+				description: "Deny a pending request.",
+				positionals: [{
+					name: "request-id",
+					type: "free"
+				}],
+				options: [{
+					name: "--reason",
+					takesValue: true,
+					valueType: "free"
+				}, {
+					name: "--json",
+					takesValue: false
+				}]
+			},
+			{
+				name: "ui",
+				description: "Open the approval UI.",
+				positionals: [],
+				options: []
+			}
+		]
+	},
+	{
+		name: "serve",
+		description: "Run a configured hub.",
+		positionals: [{
+			name: "config",
+			type: "free"
+		}],
+		options: [{
+			name: "--print-schema",
+			takesValue: false
+		}, {
+			name: "--cmd-interactive",
+			takesValue: false
+		}]
+	},
+	{
+		name: "tunnel",
+		description: "Claim a serviceId on the source hub and forward to a target.",
+		positionals: [{
+			name: "serviceId",
+			type: "serviceId"
+		}],
+		options: [
+			{
+				name: "--target-endpoint",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-stdio",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-env",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-cwd",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-token",
+				takesValue: true,
+				valueType: "free"
+			}
+		]
+	},
+	{
+		name: "connect-as",
+		description: "Mint a slot identity from a connectionTokenBinder service and splice a target onto the hub as that slot.",
+		positionals: [{
+			name: "binderServiceId",
+			type: "serviceId"
+		}, {
+			name: "slot",
+			type: "free"
+		}],
+		options: [
+			{
+				name: "--hub-endpoint",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-stdio",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-env",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-cmd-cwd",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--target-endpoint-token",
+				takesValue: true,
+				valueType: "free"
+			},
+			{
+				name: "--granted-service-id",
+				takesValue: true,
+				valueType: "serviceId"
+			}
+		]
+	},
+	{
+		name: "mcp-forward",
+		description: "Expose an MCP server through the hub.",
+		positionals: [],
+		variadic: "free",
+		options: [{
+			name: "--serviceId",
+			takesValue: true,
+			valueType: "serviceId"
+		}, {
+			name: "--env",
+			takesValue: true,
+			valueType: "free"
+		}]
+	},
+	{
+		name: "logout",
+		description: "Delete the stored CLI identity.",
+		positionals: [],
+		options: []
+	}
+];
+const HUB_COMMAND_TREE = {
+	globalOptions: HUB_GLOBAL_OPTIONS,
+	subcommands: [...SHARED_COMMANDS, ...HUB_ONLY_COMMANDS]
+};
+const RPC_COMMAND_TREE = {
+	globalOptions: ENDPOINT_GLOBAL_OPTIONS,
+	subcommands: [...SHARED_COMMANDS, {
+		name: "hub",
+		description: "Use the hub profile.",
+		positionals: [],
+		options: [{
+			name: "--config",
+			takesValue: true,
+			valueType: "free"
+		}],
+		subcommands: [...SHARED_COMMANDS, ...HUB_ONLY_COMMANDS]
+	}]
+};
+/** Hub-profile tree retained as the default for direct resolver consumers. */
+const COMMAND_TREE = HUB_COMMAND_TREE;
+/**
+* Look up a flag by its long-form name from the leaf command through its
+* ancestors, then from the global options.
+*/
+function findFlag(name, commandPath, tree) {
+	const eq = name.indexOf("=");
+	const flagName = eq >= 0 ? name.slice(0, eq) : name;
+	for (let index = commandPath.length - 1; index >= 0; index--) {
+		const flag = commandPath[index].options.find((option) => option.name === flagName);
+		if (flag !== void 0) return flag;
+	}
+	return tree.globalOptions.find((option) => option.name === flagName);
+}
+//#endregion
+//#region src/completions/resolve.ts
+/**
+* Walk the tokens before the cursor, tracking subcommand selection, current
+* positional index, and whether the next token is the value for a flag.
+* Returns the slot the cursor itself is in plus the surrounding context.
+*/
+function resolveSlot(parsed, tree) {
+	const tokens = parsed.tokensBefore;
+	let subcommand;
+	const commandPath = [];
+	let positionalIndex = 0;
+	let expectingValueFor;
+	const seenFlagValues = /* @__PURE__ */ new Map();
+	const seenPositionals = [];
+	for (let i = 1; i < tokens.length; i++) {
+		const t = tokens[i].text;
+		if (expectingValueFor !== void 0) {
+			seenFlagValues.set(expectingValueFor.name, t);
+			expectingValueFor = void 0;
+			continue;
+		}
+		if (t.startsWith("-") && t.length > 1) {
+			const eq = t.indexOf("=");
+			const flag = findFlag(eq >= 0 ? t.slice(0, eq) : t, commandPath, tree);
+			if (flag?.takesValue) {
+				if (eq >= 0) seenFlagValues.set(flag.name, t.slice(eq + 1));
+				else expectingValueFor = flag;
+			} else if (flag) seenFlagValues.set(flag.name, void 0);
+			continue;
+		}
+		if (subcommand === void 0) {
+			const sub = tree.subcommands.find((s) => s.name === t);
+			if (!sub) return {
+				slot: { kind: "none" },
+				subcommand: void 0,
+				commandPath,
+				seenFlagValues,
+				seenPositionals
+			};
+			subcommand = sub;
+			commandPath.push(sub);
+			positionalIndex = 0;
+		} else if (subcommand.subcommands !== void 0 && seenPositionals.length === 0) {
+			const child = subcommand.subcommands.find((candidate) => candidate.name === t);
+			if (child === void 0) {
+				if (subcommand.positionals.length === 0 && subcommand.variadic === void 0) return {
+					slot: { kind: "none" },
+					subcommand,
+					commandPath,
+					seenFlagValues,
+					seenPositionals
+				};
+				seenPositionals.push(t);
+				positionalIndex++;
+				continue;
+			}
+			subcommand = child;
+			commandPath.push(child);
+			positionalIndex = 0;
+			seenPositionals.length = 0;
+		} else {
+			seenPositionals.push(t);
+			positionalIndex++;
+		}
+	}
+	const word = parsed.currentWordPrefix;
+	if (expectingValueFor !== void 0) return {
+		slot: {
+			kind: "flag-value",
+			flag: expectingValueFor,
+			subcommand
+		},
+		subcommand,
+		commandPath,
+		seenFlagValues,
+		seenPositionals
+	};
+	if (word.startsWith("-")) {
+		const eq = word.indexOf("=");
+		if (eq >= 0) {
+			const flag = findFlag(word.slice(0, eq), commandPath, tree);
+			if (flag?.takesValue) return {
+				slot: {
+					kind: "flag-value",
+					flag,
+					subcommand
+				},
+				subcommand,
+				commandPath,
+				seenFlagValues,
+				seenPositionals
+			};
+		}
+		return {
+			slot: {
+				kind: "flag-name",
+				subcommand
+			},
+			subcommand,
+			commandPath,
+			seenFlagValues,
+			seenPositionals
+		};
+	}
+	if (subcommand === void 0) return {
+		slot: {
+			kind: "subcommand",
+			parent: void 0
+		},
+		subcommand: void 0,
+		commandPath,
+		seenFlagValues,
+		seenPositionals
+	};
+	if (subcommand.subcommands !== void 0 && seenPositionals.length === 0) {
+		const childMatches = subcommand.subcommands.some((child) => child.name.startsWith(word));
+		if (word.length > 0 && !childMatches && subcommand.positionals[positionalIndex] !== void 0) return {
+			slot: {
+				kind: "positional",
+				type: subcommand.positionals[positionalIndex].type,
+				subcommand,
+				index: positionalIndex
+			},
+			subcommand,
+			commandPath,
+			seenFlagValues,
+			seenPositionals
+		};
+		return {
+			slot: {
+				kind: "subcommand",
+				parent: subcommand
+			},
+			subcommand,
+			commandPath,
+			seenFlagValues,
+			seenPositionals
+		};
+	}
+	const positional = subcommand.positionals[positionalIndex];
+	if (positional !== void 0) return {
+		slot: {
+			kind: "positional",
+			type: positional.type,
+			subcommand,
+			index: positionalIndex
+		},
+		subcommand,
+		commandPath,
+		seenFlagValues,
+		seenPositionals
+	};
+	if (subcommand.variadic !== void 0) return {
+		slot: {
+			kind: "positional",
+			type: subcommand.variadic,
+			subcommand,
+			index: positionalIndex
+		},
+		subcommand,
+		commandPath,
+		seenFlagValues,
+		seenPositionals
+	};
+	return {
+		slot: { kind: "none" },
+		subcommand,
+		commandPath,
+		seenFlagValues,
+		seenPositionals
+	};
+}
+//#endregion
+//#region src/cliInvocation.ts
+const INHERITED_OPTIONS_WITH_VALUE = /* @__PURE__ */ new Set([
+	"--endpoint",
+	"--endpoint-cmd",
+	"--endpoint-cmd-stdio",
+	"--endpoint-cmd-env",
+	"--endpoint-token",
+	"--endpoint-cmd-cwd",
+	"--config",
+	"-c",
+	"--provision-identity-slot",
+	"--principal",
+	"--context",
+	"--new-context",
+	"--schema",
+	"--validation"
+]);
+const LEGACY_COMMANDS = {
+	connect: ["connection", "create"],
+	"connection-status": ["connection", "status"],
+	notifications: ["connection", "notifications"],
+	disconnect: ["connection", "destroy"],
+	hash: ["schema", "hash"],
+	"check-compat": ["schema", "check-compat"]
+};
+const SCHEMA_SUBCOMMANDS = /* @__PURE__ */ new Set([
+	"show",
+	"hash",
+	"check-compat",
+	"help"
+]);
+function resolveCliInvocation(rawArgv, executablePath) {
+	const executable = normalizeCliExecutable(executablePath);
+	let profile = executable === "hub" ? "hub" : "rpc";
+	let argv = [...rawArgv];
+	let commandIndex = findCommandIndex(argv);
+	if (profile === "rpc" && commandIndex !== void 0 && argv[commandIndex] === "hub") {
+		argv.splice(commandIndex, 1);
+		profile = "hub";
+		commandIndex = findCommandIndex(argv);
+	}
+	if (commandIndex !== void 0) {
+		const command = argv[commandIndex];
+		const replacement = LEGACY_COMMANDS[command];
+		if (replacement !== void 0) argv.splice(commandIndex, 1, ...replacement);
+		else if (command === "schema") {
+			const schemaMemberIndex = findCommandIndex(argv, commandIndex + 1);
+			const schemaMember = schemaMemberIndex === void 0 ? void 0 : argv[schemaMemberIndex];
+			if (schemaMember !== void 0 && !SCHEMA_SUBCOMMANDS.has(schemaMember)) argv.splice(commandIndex + 1, 0, "show");
+		}
+	}
+	const baseName = executable === "hub" ? "hub" : executable === "rpc" ? "rpc" : "linkrpc";
+	return {
+		argv,
+		profile,
+		programName: profile === "hub" && executable !== "hub" ? `${baseName} hub` : baseName
+	};
+}
+function normalizeCliExecutable(executablePath) {
+	if (executablePath === void 0) return "linkrpc";
+	return (executablePath.split(/[\\/]/).pop() ?? executablePath).replace(/\.(?:cmd|exe|js|mjs|cjs)$/i, "");
+}
+function findCommandIndex(argv, start = 0) {
+	for (let index = start; index < argv.length; index++) {
+		const arg = argv[index];
+		if (arg === "--") return void 0;
+		if (arg.startsWith("--") && arg.includes("=")) continue;
+		if (INHERITED_OPTIONS_WITH_VALUE.has(arg)) {
+			index++;
+			continue;
+		}
+		if (arg.startsWith("-")) continue;
+		return index;
+	}
+}
+//#endregion
+//#region src/completions/complete.ts
+/**
+* Top-level completion orchestrator. Takes a command line + cursor position,
+* resolves what's being completed, and returns the candidate list. The
+* resolver is the only thing that needs to be wire-aware (subcommand /
+* positional / flag / flag-value); everything past that is either a static
+* filter against the {@link CommandTree} or a query against a
+* {@link DirectorySource}.
+*/
+const SHELLS = [
+	"powershell",
+	"bash",
+	"zsh",
+	"fish"
+];
+/**
+* Resolve completion candidates for the cursor at `point` in `line`.
+*
+* The slot kinds returned by {@link resolveSlot} map to:
+*   - `subcommand` / `flag-name` / static-typed `flag-value` / static-typed
+*     `positional` → filter against the {@link CommandTree}
+*   - `flag-value` / `positional` with a dynamic slot type → call into
+*     `directory` (skipped when `directory` is `undefined`)
+*   - `flag-name` under `call`/`notify` with a methodRef typed → adds
+*     `--p:<name>` shortcuts for the live params
+*   - `none` → empty
+*
+* Candidates are always prefix-filtered so the caller (PowerShell) can
+* enumerate the result as-is. The output is sorted and de-duplicated.
+*/
+async function complete(opts) {
+	const parsed = parseLine(opts.line, opts.point);
+	const executable = normalizeCliExecutable(parsed.tokensBefore[0]?.text);
+	const tree = opts.tree ?? (executable === "hub" ? HUB_COMMAND_TREE : RPC_COMMAND_TREE);
+	const ctx = resolveSlot(parsed, tree);
+	const prefix = parsed.currentWordPrefix;
+	const stat = _staticCandidates(ctx, prefix, tree);
+	const dyn = opts.directory ? await _dynamicCandidates(ctx, prefix, opts.directory) : [];
+	const seen = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const c of [...stat, ...dyn]) {
+		if (seen.has(c.text)) continue;
+		seen.add(c.text);
+		merged.push(c);
+	}
+	return merged.sort((a, b) => a.text < b.text ? -1 : a.text > b.text ? 1 : 0);
+}
+function _staticCandidates(ctx, prefix, tree) {
+	const slot = ctx.slot;
+	if (slot.kind === "subcommand") return (slot.parent?.subcommands ?? tree.subcommands).filter((s) => !s.hidden && s.name.startsWith(prefix)).map((s) => ({
+		text: s.name,
+		tooltip: s.description
+	}));
+	if (slot.kind === "flag-name") {
+		const flags = [...ctx.commandPath.flatMap((command) => command.options), ...tree.globalOptions];
+		const eq = prefix.indexOf("=");
+		const lookupPrefix = eq >= 0 ? prefix.slice(0, eq) : prefix;
+		return flags.filter((f) => f.name.startsWith(lookupPrefix)).map((f) => ({
+			text: f.name,
+			tooltip: f.description
+		}));
+	}
+	if (slot.kind === "flag-value" || slot.kind === "positional") {
+		if ((slot.kind === "flag-value" ? slot.flag.valueType ?? "free" : slot.type) === "shell") return SHELLS.filter((s) => s.startsWith(prefix)).map((s) => ({ text: s }));
+	}
+	return [];
+}
+async function _dynamicCandidates(ctx, prefix, dir) {
+	const slot = ctx.slot;
+	if ((slot.kind === "flag-name" || slot.kind === "none" && (prefix === "" || prefix.startsWith("-"))) && (ctx.subcommand?.name === "call" || ctx.subcommand?.name === "notify") && ctx.seenPositionals.length >= 1) {
+		const methodRef = ctx.seenPositionals[0];
+		const ref = _parseMethodRefForCompletion(methodRef);
+		if (ref !== void 0 && ref.interfaceId !== void 0) return (await _safeParams(dir, ref.serviceId, ref.interfaceId, ref.methodName)).map((n) => `--p:${n}`).filter((c) => c.startsWith(prefix)).map((c) => ({
+			text: c,
+			tooltip: `method param: ${c.slice(4)}`
+		}));
+	}
+	let type;
+	if (slot.kind === "flag-value") type = slot.flag.valueType;
+	else if (slot.kind === "positional") type = slot.type;
+	if (!type) return [];
+	if (type === "serviceId") return distinctServiceIds(await dir.entries()).filter((s) => s.startsWith(prefix)).map((s) => ({ text: s }));
+	if (type === "interfaceId" || type === "interfaceRef") return distinctInterfaceIds(await dir.entries()).filter((i) => i.startsWith(prefix)).map((i) => ({ text: i }));
+	if (type === "methodRef") return _completeMethodRef(prefix, dir);
+	return [];
+}
+/**
+* Complete a `[serviceId::][interfaceId::]methodName[@hash]` reference. The
+* three forms are disambiguated by how many `::` the prefix contains so far.
+* Each TAB-cycle is a complete word (no trailing `::`) — the user adds the
+* next separator themselves to drill in. That keeps PowerShell's TAB-cycle
+* advancing through peer candidates instead of re-stalling on a separator.
+*
+*   0 sep:  `vscode.window`        → serviceIds + root-hosted interfaceIds
+*                                     (NOT service-bound interfaces, since
+*                                     calling them bare won't route)
+*   1 sep:  `azure-cli::Runner`    → if `azure-cli` is a serviceId, suggest
+*                                     `azure-cli::<iface>`; if it's also a
+*                                     root interfaceId, suggest its methods
+*                                     (form-2). Skip form-2 entirely when
+*                                     `azure-cli` isn't root-hosted — fetching
+*                                     a schema for any typed string would
+*                                     spam the hub on every keystroke.
+*   2 sep:  `azure-cli::Runner::g` → method names on (serviceId, interfaceId)
+*/
+async function _completeMethodRef(prefix, dir) {
+	const parts = prefix.split("::");
+	const seps = parts.length - 1;
+	const entries = await dir.entries();
+	const sids = distinctServiceIds(entries);
+	const rootInterfaceIds = new Set(entries.filter((e) => e.serviceId === "").map((e) => e.interfaceId));
+	if (seps === 0) {
+		const out = [];
+		for (const sid of sids) if (sid.startsWith(prefix)) out.push({
+			text: sid,
+			tooltip: `service ${sid}`
+		});
+		for (const iid of [...rootInterfaceIds].sort()) if (iid.startsWith(prefix)) out.push({
+			text: iid,
+			tooltip: `interface ${iid}`
+		});
+		return out;
+	}
+	if (seps === 1) {
+		const [first] = parts;
+		const out = [];
+		if (sids.includes(first)) for (const iid of interfacesOnService(entries, first)) {
+			const c = `${first}::${iid}`;
+			if (c.startsWith(prefix)) out.push({
+				text: c,
+				tooltip: `${first} :: ${iid}`
+			});
+		}
+		if (rootInterfaceIds.has(first)) {
+			const formTwoMethods = await _safeMethods(dir, void 0, first);
+			for (const m of formTwoMethods) {
+				const c = `${first}::${m}`;
+				if (c.startsWith(prefix)) out.push({
+					text: c,
+					tooltip: `${first} :: ${m}`
+				});
+			}
+		}
+		return out;
+	}
+	if (seps === 2) {
+		const [sid, iid] = parts;
+		return (await _safeMethods(dir, sid, iid)).map((m) => `${sid}::${iid}::${m}`).filter((c) => c.startsWith(prefix)).map((c) => ({ text: c }));
+	}
+	return [];
+}
+async function _safeMethods(dir, serviceId, interfaceId) {
+	try {
+		return await dir.methodsOnInterface(serviceId, interfaceId);
+	} catch {
+		return [];
+	}
+}
+async function _safeParams(dir, serviceId, interfaceId, methodName) {
+	try {
+		return await dir.paramNamesForMethod(serviceId, interfaceId, methodName);
+	} catch {
+		return [];
+	}
+}
+/**
+* Parse `[serviceId::][interfaceId::]methodName[@hash]` enough to look up
+* the method's params. Returns `undefined` for unrecognized shapes so the
+* orchestrator can skip the dynamic call. Independent of
+* `MethodRefWithOptHash` to keep the completions module dependency-free.
+*/
+function _parseMethodRefForCompletion(raw) {
+	if (raw.length === 0) return void 0;
+	const at = raw.lastIndexOf("@");
+	const parts = (at >= 0 && !raw.slice(at + 1).includes("::") ? raw.slice(0, at) : raw).split("::");
+	if (parts.some((p) => p.length === 0)) return void 0;
+	if (parts.length === 1) return {
+		serviceId: void 0,
+		interfaceId: void 0,
+		methodName: parts[0]
+	};
+	if (parts.length === 2) return {
+		serviceId: void 0,
+		interfaceId: parts[0],
+		methodName: parts[1]
+	};
+	if (parts.length === 3) return {
+		serviceId: parts[0],
+		interfaceId: parts[1],
+		methodName: parts[2]
+	};
+}
+//#endregion
+//#region src/completions/cache.ts
+/**
+* File-backed JSON cache for the directory snapshot + per-interface method
+* lists. Keyed by a stable identifier of the target hub (typically the
+* resolved endpoint URI sha) so TAB completion against different endpoints
+* doesn't share state.
+*
+* Cache lives under `os.tmpdir()/linkrpc-completions/`. I/O failures are
+* silently absorbed — the wrapper falls through to the inner source rather
+* than failing the completion request.
+*/
+/** TTL for the bus snapshot (services + interfaces). */
+const SNAPSHOT_TTL_MS = 6e4;
+/** TTL for per-interface method lists (schemas change rarely). */
+const METHODS_TTL_MS = 3e5;
+const CACHE_DIR = path$1.join(os.tmpdir(), "linkrpc-completions");
+/**
+* Wrap `inner` with a JSON-file cache scoped to `endpointKey`. Reads the
+* cache file once at construction; refills the bus snapshot lazily on the
+* first `entries()` call when the cache is missing or stale.
+*/
+function withFileCache(inner, endpointKey) {
+	const file = _cacheFile(endpointKey);
+	let cached = _loadFresh(file);
+	let entriesPromise;
+	const ensureEntries = () => {
+		if (cached !== void 0) return Promise.resolve(cached.entries);
+		if (!entriesPromise) entriesPromise = inner.entries().then((entries) => {
+			cached = {
+				ts: Date.now(),
+				entries,
+				methods: {}
+			};
+			_save(file, cached);
+			return entries;
+		});
+		return entriesPromise;
+	};
+	return {
+		entries: ensureEntries,
+		async methodsOnInterface(serviceId, interfaceId) {
+			const key = `${serviceId ?? ""}::${interfaceId}`;
+			if (cached && cached.methods[key]) {
+				const entry = cached.methods[key];
+				if (Date.now() - entry.ts <= METHODS_TTL_MS) return entry.names;
+			}
+			const names = await inner.methodsOnInterface(serviceId, interfaceId);
+			if (cached) {
+				cached = {
+					...cached,
+					methods: {
+						...cached.methods,
+						[key]: {
+							ts: Date.now(),
+							names: [...names]
+						}
+					}
+				};
+				_save(file, cached);
+			}
+			return names;
+		},
+		async paramNamesForMethod(serviceId, interfaceId, methodName) {
+			const key = `${serviceId ?? ""}::${interfaceId}::${methodName}`;
+			if (cached && cached.params && cached.params[key]) {
+				const entry = cached.params[key];
+				if (Date.now() - entry.ts <= METHODS_TTL_MS) return entry.names;
+			}
+			const names = await inner.paramNamesForMethod(serviceId, interfaceId, methodName);
+			if (cached) {
+				const params = {
+					...cached.params ?? {},
+					[key]: {
+						ts: Date.now(),
+						names: [...names]
+					}
+				};
+				cached = {
+					...cached,
+					params
+				};
+				_save(file, cached);
+			}
+			return names;
+		}
+	};
+}
+function _loadFresh(file) {
+	try {
+		const raw = fs$1.readFileSync(file, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed.ts !== "number" || !Array.isArray(parsed.entries)) return;
+		if (Date.now() - parsed.ts > SNAPSHOT_TTL_MS) return void 0;
+		return parsed;
+	} catch {
+		return;
+	}
+}
+function _save(file, snap) {
+	try {
+		fs$1.mkdirSync(CACHE_DIR, { recursive: true });
+		fs$1.writeFileSync(file, JSON.stringify(snap));
+	} catch {}
+}
+function _cacheFile(endpointKey) {
+	const hash = createHash("sha256").update(endpointKey).digest("hex").slice(0, 16);
+	return path$1.join(CACHE_DIR, `${hash}.json`);
+}
+//#endregion
+//#region src/contexts.ts
+var ContextStore = class {
+	_file;
+	_cwd;
+	constructor(options = {}) {
+		this._file = options.file ?? defaultContextStoreFile();
+		this._cwd = path$1.resolve(options.cwd ?? process.cwd());
+	}
+	get file() {
+		return this._file;
+	}
+	async select(options = {}) {
+		const contexts = await this._read();
+		if (options.selector !== void 0) {
+			const reference = await this.resolveReference(options.selector);
+			return this._selectedReference(contexts, reference, "argument", true, options.allowMissing === true);
+		}
+		if (options.environmentSelector !== void 0 && options.environmentSelector !== "") {
+			const reference = await this.resolveReference(options.environmentSelector);
+			return this._selectedReference(contexts, reference, "environment", false, options.allowMissing === true);
+		}
+		let cursor = await canonicalDirectory(this._cwd);
+		while (true) {
+			const reference = normalizeContextReference({
+				kind: "path",
+				path: cursor
+			});
+			const context = contexts.get(contextKey(reference));
+			if (context !== void 0) return {
+				reference,
+				context,
+				selectedBy: reference.kind === "root" ? "root" : "cwd",
+				explicitlySelected: false
+			};
+			const parent = path$1.dirname(cursor);
+			if (parent === cursor) break;
+			cursor = parent;
+		}
+		const rootReference = { kind: "root" };
+		const root = contexts.get(contextKey(rootReference));
+		if (root !== void 0) return {
+			reference: rootReference,
+			context: root,
+			selectedBy: "root",
+			explicitlySelected: false
+		};
+		return {
+			reference: { kind: "empty" },
+			context: void 0,
+			selectedBy: "empty",
+			explicitlySelected: false
+		};
+	}
+	async resolveReference(selector) {
+		if (selector === ":empty") return { kind: "empty" };
+		if (selector === ":root") return { kind: "root" };
+		if (selector.startsWith("id:")) {
+			const id = selector.slice(3);
+			if (id.length === 0) throw new Error("context selector \"id:\" requires a non-empty id");
+			return {
+				kind: "id",
+				id
+			};
+		}
+		if (selector.startsWith(":")) throw new Error(`unknown context selector "${selector}" (expected a folder, id:<name>, :root, or :empty)`);
+		return normalizeContextReference({
+			kind: "path",
+			path: await canonicalDirectory(path$1.resolve(this._cwd, selector))
+		});
+	}
+	async set(reference, values, options = {}) {
+		reference = normalizeContextReference(reference);
+		return this._mutate((contexts) => {
+			const key = contextKey(reference);
+			const existing = contexts.get(key);
+			if (options.createOnly === true && existing !== void 0) throw new Error(`context ${formatContextReference(reference)} already exists`);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const context = {
+				key,
+				reference,
+				values: existing === void 0 ? normalizeContextValues(values) : mergeContextValues(existing.values, values),
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now
+			};
+			contexts.set(key, context);
+			return {
+				value: context,
+				changed: true
+			};
+		});
+	}
+	async assertCanCreate(reference) {
+		reference = normalizeContextReference(reference);
+		if ((await this._read()).has(contextKey(reference))) throw new Error(`context ${formatContextReference(reference)} already exists`);
+	}
+	async replace(reference, values, options = {}) {
+		reference = normalizeContextReference(reference);
+		return this._mutate((contexts) => {
+			const key = contextKey(reference);
+			const existing = contexts.get(key);
+			if (options.createOnly === true && existing !== void 0) throw new Error(`context ${formatContextReference(reference)} already exists`);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const context = {
+				key,
+				reference,
+				values: normalizeContextValues(values),
+				createdAt: existing?.createdAt ?? now,
+				updatedAt: now
+			};
+			contexts.set(key, context);
+			return {
+				value: context,
+				changed: true
+			};
+		});
+	}
+	async unset(reference, keys) {
+		reference = normalizeContextReference(reference);
+		return this._mutate((contexts) => {
+			const key = contextKey(reference);
+			const existing = contexts.get(key);
+			if (existing === void 0) throw new Error(`context ${formatContextReference(reference)} does not exist`);
+			const values = { ...existing.values };
+			for (const item of keys) delete values[item];
+			const context = {
+				...existing,
+				values: normalizeContextValues(values),
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			contexts.set(key, context);
+			return {
+				value: context,
+				changed: true
+			};
+		});
+	}
+	async remove(reference) {
+		if (reference.kind === "empty") throw new Error(":empty is immutable and cannot be removed");
+		reference = normalizeContextReference(reference);
+		return this._mutate((contexts) => {
+			const removed = contexts.delete(contextKey(reference));
+			return {
+				value: removed,
+				changed: removed
+			};
+		});
+	}
+	async list() {
+		return [...(await this._read()).values()].sort((a, b) => formatContextReference(a.reference).localeCompare(formatContextReference(b.reference)));
+	}
+	_selectedReference(contexts, reference, selectedBy, explicitlySelected, allowMissing) {
+		if (reference.kind === "empty") return {
+			reference,
+			context: void 0,
+			selectedBy,
+			explicitlySelected
+		};
+		const context = contexts.get(contextKey(reference));
+		if (context === void 0 && !allowMissing) throw new Error(`context ${formatContextReference(reference)} does not exist`);
+		return {
+			reference,
+			context,
+			selectedBy,
+			explicitlySelected
+		};
+	}
+	async _read() {
+		let text;
+		try {
+			text = await readFile(this._file, "utf8");
+		} catch (error) {
+			if (error.code === "ENOENT") return /* @__PURE__ */ new Map();
+			throw error;
+		}
+		const value = JSON.parse(text);
+		if (value.version !== 1 || !Array.isArray(value.contexts)) throw new Error(`invalid context store ${this._file}`);
+		const contexts = /* @__PURE__ */ new Map();
+		for (const raw of value.contexts) {
+			const context = parseStoredContext(raw);
+			if (contexts.has(context.key)) throw new Error(`duplicate context key "${context.key}" in ${this._file}`);
+			contexts.set(context.key, context);
+		}
+		return contexts;
+	}
+	async _write(contexts) {
+		await mkdir(path$1.dirname(this._file), { recursive: true });
+		const document = {
+			version: 1,
+			contexts: [...contexts.values()]
+		};
+		const temporary = `${this._file}.${process.pid}.${randomUUID()}.tmp`;
+		await writeFile(temporary, JSON.stringify(document, void 0, 2) + "\n", { mode: 384 });
+		await rename(temporary, this._file);
+		if (process.platform !== "win32") await chmod(this._file, 384);
+	}
+	async _mutate(update) {
+		const release = await acquireContextStoreLock(this._file);
+		try {
+			const contexts = await this._read();
+			const result = update(contexts);
+			if (result.changed) await this._write(contexts);
+			return result.value;
+		} finally {
+			await release();
+		}
+	}
+};
+function mergeContextValues(base, overrides) {
+	const result = { ...base };
+	const endpointSelectors = [
+		["endpoint", overrides.endpoint],
+		["endpointCmd", overrides.endpointCmd],
+		["endpointCmdStdio", overrides.endpointCmdStdio]
+	].filter((entry) => entry[1] !== void 0);
+	if (endpointSelectors.length === 1) {
+		delete result.endpoint;
+		delete result.endpointCmd;
+		delete result.endpointCmdStdio;
+		const selector = endpointSelectors[0][0];
+		if (selector === "endpoint") {
+			delete result.endpointCmdEnv;
+			delete result.endpointCmdCwd;
+			delete result.provisionIdentity;
+			delete result.provisionIdentitySlot;
+			const endpoint = overrides.endpoint;
+			if (overrides.endpointToken === void 0 && endpoint !== void 0 && !/(?:[?&])token=%(?:[&#]|$)/.test(endpoint)) delete result.endpointToken;
+		} else {
+			delete result.endpointToken;
+			if (selector === "endpointCmdStdio") {
+				delete result.provisionIdentity;
+				delete result.provisionIdentitySlot;
+			}
+		}
+	}
+	for (const [key, value] of Object.entries(overrides)) if (value !== void 0) result[key] = value;
+	return normalizeContextValues(result);
+}
+async function acquireContextStoreLock(file) {
+	const lockFile = `${file}.lock`;
+	const deadline = Date.now() + 5e3;
+	await mkdir(path$1.dirname(file), { recursive: true });
+	while (true) {
+		try {
+			const handle = await open(lockFile, "wx", 384);
+			try {
+				await handle.writeFile(`${process.pid}\n${(/* @__PURE__ */ new Date()).toISOString()}\n`);
+			} catch (error) {
+				await handle.close();
+				await unlink(lockFile);
+				throw error;
+			}
+			return async () => {
+				await handle.close();
+				try {
+					await unlink(lockFile);
+				} catch (error) {
+					if (error.code !== "ENOENT") throw error;
+				}
+			};
+		} catch (error) {
+			if (error.code !== "EEXIST") throw error;
+		}
+		try {
+			const lockInfo = await stat(lockFile);
+			if (Date.now() - lockInfo.mtimeMs > 3e4) {
+				await unlink(lockFile);
+				continue;
+			}
+		} catch (error) {
+			if (error.code === "ENOENT") continue;
+			throw error;
+		}
+		if (Date.now() >= deadline) throw new Error(`timed out waiting for context store lock ${lockFile}`);
+		await new Promise((resolve) => setTimeout(resolve, 25));
+	}
+}
+function contextKey(reference) {
+	reference = normalizeContextReference(reference);
+	switch (reference.kind) {
+		case "empty": return ":empty";
+		case "root": return ":root";
+		case "id": return `id:${reference.id}`;
+		case "path": {
+			const normalized = path$1.normalize(reference.path);
+			return `path:${process.platform === "win32" ? normalized.toLowerCase() : normalized}`;
+		}
+	}
+}
+function formatContextReference(reference) {
+	reference = normalizeContextReference(reference);
+	switch (reference.kind) {
+		case "empty": return ":empty";
+		case "root": return ":root";
+		case "id": return `id:${reference.id}`;
+		case "path": return reference.path;
+	}
+}
+function defaultContextStoreFile() {
+	const home = os.homedir();
+	if (process.platform === "win32") return path$1.join(process.env.APPDATA ?? path$1.join(home, "AppData", "Roaming"), "linkrpc", "contexts.json");
+	if (process.platform === "darwin") return path$1.join(home, "Library", "Application Support", "linkrpc", "contexts.json");
+	return path$1.join(process.env.XDG_CONFIG_HOME ?? path$1.join(home, ".config"), "linkrpc", "contexts.json");
+}
+async function canonicalDirectory(folder) {
+	let info;
+	try {
+		info = await stat(folder);
+	} catch (error) {
+		if (error.code === "ENOENT") throw new Error(`context folder does not exist: ${folder}`);
+		throw error;
+	}
+	if (!info.isDirectory()) throw new Error(`context path is not a directory: ${folder}`);
+	return path$1.normalize(await realpath(folder));
+}
+function normalizeContextReference(reference) {
+	if (process.platform !== "win32" && reference.kind === "path" && path$1.parse(path$1.normalize(reference.path)).root === path$1.normalize(reference.path)) return { kind: "root" };
+	return reference;
+}
+function normalizeContextValues(values) {
+	return JSON.parse(JSON.stringify(values));
+}
+function parseStoredContext(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("invalid context entry");
+	const raw = value;
+	if (typeof raw.key !== "string" || typeof raw.createdAt !== "string" || typeof raw.updatedAt !== "string" || typeof raw.reference !== "object" || raw.reference === null || typeof raw.values !== "object" || raw.values === null) throw new Error("invalid context entry");
+	const reference = raw.reference;
+	if (reference.kind === "empty" || ![
+		"root",
+		"id",
+		"path"
+	].includes(reference.kind) || reference.kind === "id" && typeof reference.id !== "string" || reference.kind === "path" && typeof reference.path !== "string") throw new Error("invalid context reference");
+	if (raw.key !== contextKey(reference)) throw new Error(`context key mismatch for ${formatContextReference(reference)}`);
+	return {
+		key: raw.key,
+		reference,
+		values: normalizeContextValues(raw.values),
+		createdAt: raw.createdAt,
+		updatedAt: raw.updatedAt
+	};
+}
+//#endregion
+//#region src/invocationContext.ts
+async function resolveInvocationContext(options) {
+	const env = options.env ?? process.env;
+	const environmentSelector = firstDefined(env.LINKRPC_CONTEXT, env.HUBRPC_CONTEXT);
+	const selected = await options.store.select({
+		...options.selector !== void 0 ? { selector: options.selector } : {},
+		...options.selector === void 0 && environmentSelector !== void 0 ? { environmentSelector } : {},
+		...options.allowMissingContext === true ? { allowMissing: true } : {}
+	});
+	const environmentApplied = options.useEnvironment ?? (options.profile === "hub" && options.selector === void 0);
+	const contextValues = selected.context?.values ?? {};
+	const environmentValues = environmentApplied ? contextValuesFromEnvironment(env) : {};
+	const cliOverrides = options.cliOverrides ?? {};
+	return {
+		profile: options.profile,
+		selected,
+		contextValues,
+		environmentValues,
+		values: mergeContextValues(mergeContextValues(contextValues, environmentValues), cliOverrides),
+		cliOverrides,
+		environmentApplied
+	};
+}
+function contextValuesFromEnvironment(env) {
+	const endpoint = firstDefined(env.LINKRPC_ENDPOINT, env.HUBRPC_ENDPOINT);
+	const endpointToken = firstDefined(env.LINKRPC_TOKEN, env.HUBRPC_TOKEN);
+	return {
+		...endpoint !== void 0 ? { endpoint } : {},
+		...endpointToken !== void 0 ? { endpointToken } : {}
+	};
+}
+async function mutationReference(store, selected) {
+	if (selected.reference.kind !== "empty" && selected.reference.kind !== "root") return selected.reference;
+	const cwd = await store.resolveReference(".");
+	if (cwd.kind === "empty") throw new Error("current directory cannot be used as a context");
+	return cwd;
+}
+function validationDefault(profile) {
+	return profile === "hub" ? "required" : "auto";
+}
+function resolveInvocationEndpoint(invocation, provisioningHandledElsewhere = false) {
+	const cli = invocation.cliOverrides;
+	const context = invocation.contextValues;
+	const environment = invocation.environmentValues;
+	const cliHasEndpoint = hasEndpointSelector(cli);
+	const environmentHasEndpoint = environment.endpoint !== void 0;
+	let input;
+	if (cliHasEndpoint) {
+		const inheritedToken = cli.endpoint !== void 0 && hasTokenPlaceholder(cli.endpoint) ? environment.endpointToken ?? context.endpointToken : void 0;
+		const token = cli.endpointToken ?? inheritedToken;
+		input = {
+			...endpointInput(cli),
+			...token !== void 0 ? { endpointToken: token } : {},
+			provisioningHandledElsewhere,
+			env: {}
+		};
+	} else if (environmentHasEndpoint) input = {
+		...endpointInput(cli),
+		...cli.endpointToken !== void 0 ? { endpointToken: cli.endpointToken } : {},
+		provisioningHandledElsewhere,
+		env: {
+			LINKRPC_ENDPOINT: environment.endpoint,
+			...environment.endpointToken !== void 0 ? { LINKRPC_TOKEN: environment.endpointToken } : {}
+		}
+	};
+	else {
+		const values = {
+			...context,
+			...cli
+		};
+		const token = cli.endpointToken ?? environment.endpointToken ?? context.endpointToken;
+		input = {
+			...endpointInput(values),
+			...token !== void 0 ? { endpointToken: token } : {},
+			provisioningHandledElsewhere,
+			env: {}
+		};
+	}
+	const result = resolveEndpoint(input);
+	if (result.error !== void 0) throw new Error(result.error);
+	return result.endpoint;
+}
+function endpointInput(values) {
+	return {
+		...values.endpoint !== void 0 ? { endpoint: values.endpoint } : {},
+		...values.endpointCmd !== void 0 ? { endpointCmd: values.endpointCmd } : {},
+		...values.endpointCmdStdio !== void 0 ? { endpointCmdStdio: values.endpointCmdStdio } : {},
+		...values.endpointCmdEnv !== void 0 ? { endpointCmdEnv: values.endpointCmdEnv } : {},
+		...values.endpointCmdCwd !== void 0 ? { endpointCmdCwd: values.endpointCmdCwd } : {},
+		...values.provisionIdentity !== void 0 ? { provisionIdentity: values.provisionIdentity } : {},
+		...values.provisionIdentitySlot !== void 0 ? { provisionIdentitySlot: values.provisionIdentitySlot } : {}
+	};
+}
+function hasEndpointSelector(values) {
+	return values.endpoint !== void 0 || values.endpointCmd !== void 0 || values.endpointCmdStdio !== void 0;
+}
+function hasTokenPlaceholder(endpoint) {
+	return /(?:[?&])token=%(?:[&#]|$)/.test(endpoint);
+}
+function firstDefined(...values) {
+	return values.find((value) => value !== void 0);
+}
+//#endregion
+//#region src/staticHubSchema.ts
+function resolveStaticHubSchemaSource(source) {
+	return isHttpUrl(source) ? source : resolve(source);
+}
+async function loadStaticHubSchema(source) {
+	let raw;
+	try {
+		let text;
+		if (isHttpUrl(source)) {
+			const response = await fetch(source);
+			if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`.trimEnd());
+			text = await response.text();
+		} else text = await readFile(source, "utf8");
+		raw = JSON.parse(text);
+	} catch (error) {
+		throw new Error(`Failed to load hub schema '${source}': ${error.message}`);
+	}
+	try {
+		return parseStaticHubSchema(raw);
+	} catch (error) {
+		throw new Error(`Invalid hub schema '${source}': ${error.message}`);
+	}
+}
+function isHttpUrl(source) {
+	return /^https?:\/\//i.test(source);
+}
+function parseStaticHubSchema(value) {
+	const root = expectRecord(value, "hub schema");
+	const rawServices = expectArray(root.services, "services");
+	const interfaceSchemas = expectArray(root.interfaceSchemas, "interfaceSchemas").map((schema, index) => parseInterfaceSchema(schema, `interfaceSchemas[${index}]`));
+	const schemasByKey = /* @__PURE__ */ new Map();
+	for (const schema of interfaceSchemas) {
+		const key = interfaceKey$1(schema.id, schema.hash);
+		if (schemasByKey.has(key)) throw new Error(`interfaceSchemas contains duplicate ${schema.id}@${schema.hash}`);
+		schemasByKey.set(key, schema);
+	}
+	const services = rawServices.map((service, index) => parseService(service, `services[${index}]`));
+	for (const [serviceIndex, service] of services.entries()) for (const [interfaceIndex, ref] of service.interfaces.entries()) requireResolvedReference(ref, schemasByKey, `services[${serviceIndex}].interfaces[${interfaceIndex}]`);
+	const defaultInterface = root.defaultInterface === void 0 ? void 0 : parseInterfaceReference(root.defaultInterface, "defaultInterface");
+	if (defaultInterface !== void 0) requireResolvedReference(defaultInterface, schemasByKey, "defaultInterface");
+	return {
+		services,
+		...defaultInterface === void 0 ? {} : { defaultInterface },
+		interfaceSchemas
+	};
+}
+function parseService(value, path) {
+	const service = expectRecord(value, path);
+	if (typeof service.serviceId !== "string") throw new Error(`${path}.serviceId must be a string`);
+	return {
+		serviceId: service.serviceId,
+		interfaces: expectArray(service.interfaces, `${path}.interfaces`).map((ref, index) => parseInterfaceReference(ref, `${path}.interfaces[${index}]`))
+	};
+}
+function parseInterfaceReference(value, path) {
+	const ref = expectRecord(value, path);
+	if (typeof ref.interfaceId !== "string" || ref.interfaceId.length === 0) throw new Error(`${path}.interfaceId must be a non-empty string`);
+	if (typeof ref.interfaceHash !== "string" || ref.interfaceHash.length === 0) throw new Error(`${path}.interfaceHash must be a non-empty string`);
+	return {
+		interfaceId: ref.interfaceId,
+		interfaceHash: ref.interfaceHash
+	};
+}
+function parseInterfaceSchema(value, path) {
+	const schema = expectRecord(value, path);
+	if (typeof schema.id !== "string" || schema.id.length === 0) throw new Error(`${path}.id must be a non-empty string`);
+	if (typeof schema.hash !== "string" || schema.hash.length === 0) throw new Error(`${path}.hash must be a non-empty string`);
+	if (typeof schema.methods !== "object" || schema.methods === null || Array.isArray(schema.methods)) throw new Error(`${path}.methods must be an object`);
+	for (const [name, method] of Object.entries(schema.methods)) {
+		if (name.length === 0) throw new Error(`${path}.methods keys must be non-empty strings`);
+		const parsed = expectRecord(method, `${path}.methods.${name}`);
+		if (!Object.hasOwn(parsed, "params")) throw new Error(`${path}.methods.${name}.params is required`);
+	}
+	const typed = schema;
+	const computedHash = computeInterfaceHash(typed);
+	if (computedHash !== typed.hash) throw new Error(`${path} hash mismatch for ${typed.id}: declared ${typed.hash}, computed ${computedHash}`);
+	return typed;
+}
+function requireResolvedReference(ref, schemasByKey, path) {
+	if (!schemasByKey.has(interfaceKey$1(ref.interfaceId, ref.interfaceHash))) throw new Error(`${path} ${formatReference(ref)} does not resolve to an interface schema`);
+}
+function formatReference(ref) {
+	return `${ref.interfaceId}@${ref.interfaceHash}`;
+}
+function interfaceKey$1(interfaceId, interfaceHash) {
+	return `${interfaceId}\0${interfaceHash}`;
+}
+function expectRecord(value, path) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`);
+	return value;
+}
+function expectArray(value, path) {
+	if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
+	return value;
+}
+//#endregion
+//#region src/commands/staticHubReflection.ts
+const DIRECTORY_INTERFACE_ID = "hubrpc.directory";
+const SCHEMAS_INTERFACE_ID = "hubrpc.schemas";
+const DEFAULTS_INTERFACE_ID = "hubrpc.defaults";
+const DIRECTORY_LIST_METHOD = `${DIRECTORY_INTERFACE_ID}::list`;
+const DIRECTORY_WATCH_METHOD = `${DIRECTORY_INTERFACE_ID}::watch`;
+const SCHEMAS_GET_METHOD = `${SCHEMAS_INTERFACE_ID}::get`;
+const DEFAULTS_GET_METHOD = `${DEFAULTS_INTERFACE_ID}::get`;
+var StaticHubReflection = class {
+	_schema;
+	_directory;
+	_schemasByKey = /* @__PURE__ */ new Map();
+	_activeHashesById = /* @__PURE__ */ new Map();
+	_hashesByServiceInterface = /* @__PURE__ */ new Map();
+	constructor(_schema) {
+		this._schema = _schema;
+		this._directory = _schema.services.flatMap((service) => service.interfaces.map((ref) => ({
+			serviceId: service.serviceId,
+			interfaceId: ref.interfaceId,
+			interfaceHash: ref.interfaceHash
+		})));
+		for (const schema of _schema.interfaceSchemas) this._schemasByKey.set(interfaceKey(schema.id, schema.hash), schema);
+		for (const item of this._directory) {
+			const hashes = this._activeHashesById.get(item.interfaceId) ?? /* @__PURE__ */ new Set();
+			hashes.add(item.interfaceHash);
+			this._activeHashesById.set(item.interfaceId, hashes);
+			const serviceKey = interfaceKey(item.serviceId, item.interfaceId);
+			const serviceHashes = this._hashesByServiceInterface.get(serviceKey) ?? /* @__PURE__ */ new Set();
+			serviceHashes.add(item.interfaceHash);
+			this._hashesByServiceInterface.set(serviceKey, serviceHashes);
+		}
+		if (_schema.defaultInterface !== void 0) {
+			const ref = _schema.defaultInterface;
+			const hashes = this._activeHashesById.get(ref.interfaceId) ?? /* @__PURE__ */ new Set();
+			hashes.add(ref.interfaceHash);
+			this._activeHashesById.set(ref.interfaceId, hashes);
+		}
+	}
+	tryHandleRequest(call) {
+		return this.tryHandle(call.method, call.params, call.signal);
+	}
+	tryHandle(method, params, signal) {
+		const reflectionCall = parseReflectionMethod(method);
+		if (reflectionCall === void 0) return;
+		switch (reflectionCall.method) {
+			case DIRECTORY_LIST_METHOD: return Promise.resolve(this._listDirectory(params));
+			case DIRECTORY_WATCH_METHOD: return this._watchDirectory(params, signal);
+			case SCHEMAS_GET_METHOD: return Promise.resolve(this._getSchema(params, reflectionCall.serviceId));
+			case DEFAULTS_GET_METHOD: return Promise.resolve({ result: this._schema.defaultInterface === void 0 ? {} : {
+				interfaceId: this._schema.defaultInterface.interfaceId,
+				interfaceHash: this._schema.defaultInterface.interfaceHash
+			} });
+			default: return Promise.resolve(methodNotFound(method));
+		}
+	}
+	_listDirectory(params) {
+		const parsed = parseDirectoryParams(params);
+		if ("error" in parsed) return parsed;
+		const filtered = this._directory.filter((item) => parsed.interfaceId === void 0 || item.interfaceId === parsed.interfaceId).filter((item) => parsed.serviceId === void 0 || item.serviceId === parsed.serviceId);
+		const start = parsed.cursor ?? 0;
+		if (start > filtered.length) return invalidParams("directory cursor is outside the result set");
+		const end = parsed.limit === void 0 ? filtered.length : Math.min(filtered.length, start + parsed.limit);
+		return { result: {
+			items: filtered.slice(start, end),
+			...end < filtered.length ? { nextCursor: String(end) } : {}
+		} };
+	}
+	_watchDirectory(params, signal) {
+		const parsed = parseDirectoryParams(params, false);
+		if ("error" in parsed) return Promise.resolve(parsed);
+		return new Promise((resolve) => {
+			const done = () => resolve({ result: {} });
+			if (signal.aborted) {
+				done();
+				return;
+			}
+			signal.addEventListener("abort", done, { once: true });
+		});
+	}
+	_getSchema(params, serviceId) {
+		if (!isRecord(params)) return invalidParams("schemas.get params must be an object");
+		const interfaceId = params.interfaceId;
+		const hash = params.hash;
+		if (typeof interfaceId !== "string" || interfaceId.length === 0) return invalidParams("schemas.get interfaceId must be a non-empty string");
+		if (hash !== void 0 && typeof hash !== "string") return invalidParams("schemas.get hash must be a string");
+		let resolvedHash = hash;
+		if (resolvedHash === void 0) {
+			const active = serviceId === void 0 ? [...this._activeHashesById.get(interfaceId) ?? []] : [...this._hashesByServiceInterface.get(interfaceKey(serviceId, interfaceId)) ?? []];
+			if (active.length !== 1) return { error: {
+				code: ErrorCode.methodNotFound,
+				message: `Interface not found: ${interfaceId}`,
+				data: {
+					reason: "unknown-interface",
+					interfaceId
+				}
+			} };
+			resolvedHash = active[0];
+		}
+		const schema = this._schemasByKey.get(interfaceKey(interfaceId, resolvedHash));
+		if (schema === void 0) return { error: {
+			code: ErrorCode.methodNotFound,
+			message: `Interface not found: ${interfaceId}@${resolvedHash}`,
+			data: {
+				reason: "unknown-interface",
+				interfaceId,
+				hash: resolvedHash
+			}
+		} };
+		return { result: { schema } };
+	}
+};
+function withStaticHubReflection(sender, schema) {
+	const reflection = new StaticHubReflection(schema);
+	const handle = (method, params, signal) => {
+		return reflection.tryHandle(method, params, signal)?.then(unwrapResult);
+	};
+	return {
+		sendRequest: (method, params, opts) => handle(method, params, new AbortController().signal) ?? sender.sendRequest(method, params, opts),
+		sendNotification: (method, params, opts) => sender.sendNotification(method, params, opts),
+		sendRequestWithStream: (method, params, opts) => {
+			const controller = new AbortController();
+			const result = handle(method, params, controller.signal);
+			if (result === void 0) return sender.sendRequestWithStream(method, params, opts);
+			return {
+				result,
+				send: () => {},
+				cancel: () => controller.abort(),
+				dispose: () => controller.abort(),
+				ping: () => Promise.resolve()
+			};
+		},
+		close: () => sender.close()
+	};
+}
+function unwrapResult(result) {
+	if ("error" in result) throw new RpcError(result.error.message, result.error.code, result.error.data);
+	return result.result;
+}
+function parseDirectoryParams(params, allowPagination = true) {
+	if (params === void 0) return {};
+	if (!isRecord(params)) return invalidParams("directory params must be an object");
+	const interfaceId = optionalString(params.interfaceId);
+	if (interfaceId === false) return invalidParams("directory interfaceId must be a string");
+	const serviceId = optionalString(params.serviceId);
+	if (serviceId === false) return invalidParams("directory serviceId must be a string");
+	const result = {
+		...interfaceId === void 0 ? {} : { interfaceId },
+		...serviceId === void 0 ? {} : { serviceId }
+	};
+	if (!allowPagination) return result;
+	if (params.cursor !== void 0) {
+		if (typeof params.cursor !== "string" || !/^(0|[1-9]\d*)$/.test(params.cursor)) return invalidParams("directory cursor must be a non-negative integer string");
+		result.cursor = Number(params.cursor);
+	}
+	if (params.limit !== void 0) {
+		if (typeof params.limit !== "number" || !Number.isSafeInteger(params.limit) || params.limit <= 0) return invalidParams("directory limit must be a positive integer");
+		result.limit = params.limit;
+	}
+	return result;
+}
+function parseReflectionMethod(method) {
+	const parts = method.split("::");
+	const candidate = parts.length === 2 ? method : parts.length === 3 ? `${parts[1]}::${parts[2]}` : void 0;
+	if (candidate?.startsWith(`${DIRECTORY_INTERFACE_ID}::`) || candidate?.startsWith(`${SCHEMAS_INTERFACE_ID}::`) || candidate?.startsWith(`${DEFAULTS_INTERFACE_ID}::`)) return {
+		method: candidate,
+		serviceId: parts.length === 3 ? parts[0] : void 0
+	};
+}
+function methodNotFound(method) {
+	return { error: {
+		code: ErrorCode.methodNotFound,
+		message: `Unknown static reflection method: ${method}`
+	} };
+}
+function invalidParams(message) {
+	return { error: {
+		code: ErrorCode.invalidParams,
+		message
+	} };
+}
+function optionalString(value) {
+	if (value === void 0) return void 0;
+	return typeof value === "string" ? value : false;
+}
+function interfaceKey(interfaceId, interfaceHash) {
+	return `${interfaceId}\0${interfaceHash}`;
+}
+function isRecord(value) {
+	return value !== void 0 && value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/completions/runComplete.ts
+/**
+* Shared completion core: resolve a command line + cursor into a structured
+* candidate list, opening a best-effort hub connection when the slot needs
+* dynamic data.
+*
+* This is the reusable engine behind two front-ends:
+*   - the CLI's `_complete` command (see `../commands/internalComplete.ts`),
+*     which formats the result as `text\ttooltip` lines for shell scripts;
+*   - the VS Code extension's terminal completion provider, which maps the
+*     structured result onto `TerminalCompletionItem`s.
+*
+* Endpoint selection is caller-controllable: `endpointOverride` wins over the
+* line's `--endpoint`, and `env` controls (or disables, via `{}`) the
+* `LINKRPC_ENDPOINT` fallback — the extension passes `{}` so completion targets
+* the endpoint named on the line rather than the extension host's environment.
+*/
+/** Slot types that require talking to a hub. Anything else is static-only. */
+const DYNAMIC_SLOT_TYPES = /* @__PURE__ */ new Set([
+	"serviceId",
+	"interfaceId",
+	"interfaceRef",
+	"methodRef"
+]);
+/**
+* Resolve completion candidates for the cursor at `point` in `line`, opening a
+* hub connection only when the slot needs dynamic data.
+*/
+async function completeForLine(opts) {
+	const parsed = parseLine(opts.line, opts.point);
+	const executable = normalizeCliExecutable(parsed.tokensBefore[0]?.text);
+	const tree = executable === "hub" ? HUB_COMMAND_TREE : RPC_COMMAND_TREE;
+	const ctx = resolveSlot(parsed, tree);
+	const profile = executable === "hub" || ctx.commandPath[0]?.name === "hub" ? "hub" : "rpc";
+	const prefix = parsed.currentWordPrefix;
+	let directory = opts.directoryOverride;
+	let closeConnection;
+	if (!directory && !opts.skipConnect && _slotWantsDynamic(ctx.slot)) {
+		const opened = await _openDirectoryFromLine(ctx.seenFlagValues, {
+			endpointOverride: opts.endpointOverride,
+			env: opts.env,
+			profile
+		});
+		directory = opened?.source;
+		closeConnection = opened?.close;
+	}
+	try {
+		return {
+			candidates: await complete({
+				line: opts.line,
+				point: opts.point,
+				tree,
+				...directory !== void 0 ? { directory } : {}
+			}),
+			slot: ctx.slot,
+			replacementIndex: opts.point - prefix.length,
+			replacementLength: prefix.length
+		};
+	} finally {
+		closeConnection?.();
+	}
+}
+function _slotWantsDynamic(slot) {
+	if (slot.kind === "flag-value") return slot.flag.valueType !== void 0 && DYNAMIC_SLOT_TYPES.has(slot.flag.valueType);
+	if (slot.kind === "positional") return DYNAMIC_SLOT_TYPES.has(slot.type);
+	return false;
+}
+/**
+* Try to open a `DirectorySource` against the hub the partial command line
+* points at (or `endpointOverride`). The returned `close()` MUST be called:
+* the underlying socket otherwise keeps the process alive past action return,
+* hanging the user's prompt.
+*
+* Any failure → `undefined` (the orchestrator falls back to static-only).
+*/
+async function _openDirectoryFromLine(seenFlagValues, opts) {
+	try {
+		return await _openDirectoryFromLineCore(seenFlagValues, opts);
+	} catch {
+		return;
+	}
+}
+async function _openDirectoryFromLineCore(seenFlagValues, opts) {
+	const invocation = await resolveInvocationContext({
+		profile: opts.profile,
+		store: new ContextStore(),
+		selector: seenFlagValues.get("--context"),
+		cliOverrides: completionContextOverrides(seenFlagValues, opts.endpointOverride),
+		env: opts.env,
+		useEnvironment: seenFlagValues.has("--use-env") ? true : seenFlagValues.has("--no-use-env") ? false : void 0
+	});
+	let endpoint;
+	try {
+		endpoint = resolveInvocationEndpoint(invocation);
+	} catch {
+		return;
+	}
+	if (endpoint === void 0) return void 0;
+	if (endpoint.kind !== "socket" && endpoint.kind !== "ws" && endpoint.kind !== "ws-no-init") return void 0;
+	const opened = await _connectWithDeadline(endpoint, 800);
+	if (!opened) return void 0;
+	const isRaw = endpoint.kind === "ws-no-init" || endpoint.kind === "socket" && endpoint.brokerMode === "raw";
+	if (opts.profile === "hub" && !isRaw) try {
+		const principalSpec = parsePrincipalSpec(invocation.values.principal);
+		await _withDeadline(setupSigning(opened.channel, opened.signing, principalSpec, { negotiateHubCaps: isHubEndpoint(endpoint) }), 800);
+	} catch {
+		opened.close();
+		return;
+	}
+	const staticSchema = invocation.values.schema === void 0 ? void 0 : await loadStaticHubSchema(invocation.values.schema);
+	return {
+		source: withFileCache(new ChannelDirectorySource(staticSchema === void 0 ? opened.channel : withStaticHubReflection(opened.channel, staticSchema)), _endpointCacheKey(endpoint, staticSchema)),
+		close: () => opened.close()
+	};
+}
+function completionContextOverrides(seen, endpointOverride) {
+	const endpoint = endpointOverride ?? seen.get("--endpoint");
+	return {
+		...endpoint !== void 0 ? { endpoint } : {},
+		...seen.get("--endpoint-cmd") !== void 0 ? { endpointCmd: seen.get("--endpoint-cmd") } : {},
+		...seen.get("--endpoint-cmd-stdio") !== void 0 ? { endpointCmdStdio: seen.get("--endpoint-cmd-stdio") } : {},
+		...endpointOverride === void 0 && seen.get("--endpoint-token") !== void 0 ? { endpointToken: seen.get("--endpoint-token") } : {},
+		...seen.has("--provision-identity") ? { provisionIdentity: true } : {},
+		...seen.get("--provision-identity-slot") !== void 0 ? { provisionIdentitySlot: seen.get("--provision-identity-slot") } : {},
+		...seen.get("--principal") !== void 0 ? { principal: seen.get("--principal") } : {},
+		...seen.get("--schema") !== void 0 ? { schema: seen.get("--schema") } : {}
+	};
+}
+/**
+* Race `connect` against a soft deadline. On timeout, the connect promise's
+* resolved connection (if any) is closed so it doesn't leak.
+*/
+async function _connectWithDeadline(endpoint, deadlineMs) {
+	let timer;
+	let timedOut = false;
+	const timeout = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			timedOut = true;
+			resolve(void 0);
+		}, deadlineMs);
+	});
+	try {
+		const connectPromise = connect(endpoint).catch(() => void 0);
+		const conn = await Promise.race([connectPromise, timeout]);
+		if (timedOut) {
+			connectPromise.then((late) => late?.close());
+			return;
+		}
+		return conn ?? void 0;
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+/** Reject `p` with a timeout error after `deadlineMs`, without leaking the timer. */
+async function _withDeadline(p, deadlineMs) {
+	let timer;
+	const timeout = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error("deadline exceeded")), deadlineMs);
+	});
+	try {
+		return await Promise.race([p, timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+function _endpointCacheKey(endpoint, staticSchema) {
+	const endpointKey = endpoint.kind === "socket" ? `socket:${endpoint.path}` : endpoint.kind === "ws" ? `ws:${endpoint.url}` : endpoint.kind === "ws-no-init" ? `ws-no-init:${endpoint.url}` : `${endpoint.kind}:?`;
+	return staticSchema === void 0 ? endpointKey : `${endpointKey}|schema:${JSON.stringify(staticSchema)}`;
+}
+//#endregion
+export { connectViaRootOverlay as A, parseParamOverride as B, findMethodInSchema as C, formatPrincipalSource as D, logoutCliIdentity as E, describeSchema as F, mcpForwardInterface as H, explainValidation as I, validateValueAgainstSchema as L, resolveTargetEndpoint as M, resolvedEndpointToConfig as N, parsePrincipalSpec as O, describeObjectParams as P, valueToConstSchema as R, fetchSchema$1 as S, walkHubDetailed as T, MethodRefWithOptHash as V, ChannelDirectorySource as _, resolveStaticHubSchemaSource as a, setupSigning as b, resolveInvocationEndpoint as c, formatContextReference as d, complete as f, parseLine as g, COMMAND_TREE as h, loadStaticHubSchema as i, connectViaTransport as j, connect as k, validationDefault as l, resolveSlot as m, StaticHubReflection as n, mutationReference as o, resolveCliInvocation as p, withStaticHubReflection as r, resolveInvocationContext as s, completeForLine as t, ContextStore as u, requestReflectionAccess as v, walkHub as w, fetchDefaults as x, requestTopologyAccess as y, mergeParams as z };
+
+//# sourceMappingURL=runComplete-BkQwzPbF.js.map