@warmhub/cli 0.52.1 → 0.53.0

package/dist/wh.js

@@ -18914,6 +18914,10 @@ var RUNTIME_ACCESS_BUILTINS = new Set([
   "ComponentConfig",
   ...BUILTIN_SHAPE_NAMES
 ]);
+var SUBSCRIPTION_TRIGGER_BUILTINS = new Set([
+  "ComponentInstall",
+  "ComponentConfig"
+]);
 function validateProvisioning(obj, path, errors) {
   if (!("provisioning" in obj))
     return;
@@ -19206,8 +19210,19 @@ function validateManifestSemantics(manifest) {
   }
   const shapeNames = new Set(manifest.shapes.map((s) => s.name));
   const credentialNames = new Set(manifest.credentials.map((c) => c.name));
-  const knownShapes = new Set([...shapeNames, "ComponentConfig"]);
+  const knownSubscriptionTriggerShapes = new Set([
+    ...shapeNames,
+    ...SUBSCRIPTION_TRIGGER_BUILTINS
+  ]);
+  const knownSeedShapes = new Set([...shapeNames, "ComponentConfig"]);
   for (const sub of manifest.subscriptions) {
+    if (sub.trigger.kind === "event" && !knownSubscriptionTriggerShapes.has(sub.trigger.shape)) {
+      findings.push({
+        level: "error",
+        code: "MISSING_SUBSCRIPTION_TRIGGER_SHAPE_REF",
+        message: `subscription "${sub.name}" trigger references shape "${sub.trigger.shape}" which is not declared and is not a supported subscription trigger built-in`
+      });
+    }
     if (sub.credentials) {
       if (sub.credentials.length > 1) {
         findings.push({
@@ -19236,7 +19251,7 @@ function validateManifestSemantics(manifest) {
     }
   }
   for (const seed of manifest.seeds) {
-    if (!knownShapes.has(seed.shape)) {
+    if (!knownSeedShapes.has(seed.shape)) {
       findings.push({
         level: "error",
         code: "MISSING_SHAPE_REF",
@@ -19381,6 +19396,11 @@ function joinFieldIdentityPath(...segments) {
 function joinFieldPathWithEscaper(escapeSegment, segments) {
   return segments.map((segment) => typeof segment === "number" ? `[${segment}]` : escapeSegment(segment)).join(".").replace(/\.\[/g, "[");
 }
+// ../../packages/rules/src/permission-scopes.ts
+var PUBLIC_ORG_PERMISSIONS = new Set([
+  "org:read",
+  "components:read"
+]);
 // ../../packages/rules/src/platform-status.ts
 var PLATFORM_STATUS_CATALOG_SHAPE = "PlatformStatusCatalog";
 var PLATFORM_STATUS_CATALOG_NAME = "main";
@@ -21213,6 +21233,7 @@ function nestedObjectFields(typeDef) {
 }
 // ../../packages/rules/src/system-components/system.ts
 var SYSTEM_COMPONENT_ID = "com.warmhub.system";
+var SYSTEM_REGISTERED_COMPONENT_REF = "warmhub/system";
 var COMPONENT_INSTALL_FIELDS = {
   componentId: "string",
   name: "string",
@@ -21273,7 +21294,7 @@ function findSystemComponent(componentId) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.52.0",
+  version: "0.52.1",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -21601,7 +21622,7 @@ async function submitOperationsViaStream(client, args) {
           orgName: args.orgName,
           repoName: args.repoName,
           streamId,
-          componentId: args.componentId,
+          componentRef: args.componentRef,
           committer: args.committer,
           message: args.message,
           operations: chunk
@@ -22107,23 +22128,9 @@ class WarmHubClient {
     }
   };
   access = {
-    checkRepoPermission: async (orgName, repoName, permission) => {
+    resolve: async (input) => {
       try {
-        return await this.trpc.access.checkRepoPermission.query({
-          orgName,
-          repoName,
-          permission
-        });
-      } catch (error) {
-        throw toWarmHubError(error);
-      }
-    },
-    checkOrgPermission: async (orgName, permission) => {
-      try {
-        return await this.trpc.access.checkOrgPermission.query({
-          orgName,
-          permission
-        });
+        return await this.trpc.access.resolve.query(input);
       } catch (error) {
         throw toWarmHubError(error);
       }
@@ -22177,12 +22184,12 @@ class WarmHubClient {
         throw toWarmHubError(error);
       }
     },
-    get: async (orgName, repoName, componentId) => {
+    get: async (orgName, repoName, componentRef) => {
       try {
         return await this.trpc.component.get.query({
           orgName,
           repoName,
-          componentId
+          componentRef
         });
       } catch (error) {
         throw toWarmHubError(error);
@@ -22277,7 +22284,7 @@ class WarmHubClient {
           repoName,
           committer: opts?.committer,
           message,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           chunkSize: opts?.chunkSize,
           skipExisting: opts?.skipExisting,
           streamId: opts?.streamId,
@@ -22715,7 +22722,7 @@ class WarmHubClient {
           orgName,
           repoName,
           match: opts?.match,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           includeRetracted: opts?.includeRetracted
         });
@@ -23061,7 +23068,7 @@ class WarmHubClient {
           includeRetracted: opts?.includeRetracted,
           limit: opts?.limit,
           cursor: opts?.cursor,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
           where: opts?.where
@@ -23282,7 +23289,7 @@ class WarmHubClient {
           resolveCollections: opts?.resolveCollections,
           limit: opts?.limit,
           cursor: opts?.cursor,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
           where: opts?.where
@@ -23313,7 +23320,7 @@ class WarmHubClient {
           resolveCollections: opts?.resolveCollections,
           limit: opts?.limit,
           cursor: opts?.cursor,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
           mode: opts?.mode
@@ -23334,7 +23341,7 @@ class WarmHubClient {
           match: opts?.match,
           includeRetracted: opts?.includeRetracted,
           resolveCollections: opts?.resolveCollections,
-          componentId: opts?.componentId,
+          componentRef: opts?.componentRef,
           excludeComponents: opts?.excludeComponents,
           excludeInfraShapes: opts?.excludeInfraShapes,
           where: opts?.where
@@ -25176,7 +25183,7 @@ function loadProfileStore(path) {
   } catch (cause) {
     throw corruptedAuthError(p, cause);
   }
-  if (parsed === null || typeof parsed !== "object" || parsed.version !== 1 || parsed.profiles === null || typeof parsed.profiles !== "object") {
+  if (parsed === null || typeof parsed !== "object" || parsed.version !== 1 || parsed.profiles === null || typeof parsed.profiles !== "object" || Array.isArray(parsed.profiles)) {
     throw corruptedAuthError(p);
   }
   return parsed;
@@ -25481,20 +25488,34 @@ function recordBenchmarkResponse(response, benchmarkId) {
     benchmarkTelemetry.requestDbQueryCountSum += requestDbQueryCount;
   }
 }
-function createBenchmarkAwareFetch(benchmarkId) {
-  if (!benchmarkId)
+function createBenchmarkAwareFetch(benchmarkId, signal) {
+  if (!benchmarkId && !signal)
     return;
   return async (input, init) => {
     const headers = new Headers(init?.headers);
-    headers.set(BENCHMARK_HEADER, benchmarkId);
+    if (benchmarkId)
+      headers.set(BENCHMARK_HEADER, benchmarkId);
     const response = await fetch(input, {
       ...init,
-      headers
+      headers,
+      signal: mergeAbortSignals(init?.signal, signal)
     });
-    recordBenchmarkResponse(response, benchmarkId);
+    if (benchmarkId)
+      recordBenchmarkResponse(response, benchmarkId);
     return response;
   };
 }
+function mergeAbortSignals(requestSignal, liveSignal) {
+  if (!requestSignal)
+    return liveSignal;
+  if (!liveSignal)
+    return requestSignal;
+  if (requestSignal.aborted)
+    return requestSignal;
+  if (liveSignal.aborted)
+    return liveSignal;
+  return AbortSignal.any([requestSignal, liveSignal]);
+}
 function resetBenchmarkTelemetry() {
   benchmarkTelemetry = emptyBenchmarkTelemetry();
 }
@@ -25522,18 +25543,34 @@ function createClient(config, opts = {}) {
 function wantsStructuredLiveOutput(format) {
   return format === "json" || format === "jsonl";
 }
+var LIVE_ABORTED = Symbol("live-aborted");
+function pollUntilAbort(poll, signal) {
+  if (signal.aborted)
+    return Promise.resolve(LIVE_ABORTED);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => resolve(LIVE_ABORTED);
+    signal.addEventListener("abort", onAbort, { once: true });
+    poll.then((result) => {
+      signal.removeEventListener("abort", onAbort);
+      resolve(result);
+    }, (error) => {
+      signal.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+  });
+}
 async function runLive(opts) {
   const auth = opts.auth ?? {
     getToken: async () => await getValidToken(opts.profile) ?? undefined
   };
   const benchmarkId = process.env.WH_BENCHMARK_ID?.trim();
+  const controller = new AbortController;
   const client = new WarmHubClient({
     apiUrl: opts.apiUrl,
     auth,
-    fetch: createBenchmarkAwareFetch(benchmarkId),
+    fetch: createBenchmarkAwareFetch(benchmarkId, controller.signal),
     functionLogs: opts.functionLogs
   });
-  const controller = new AbortController;
   if (opts.signal) {
     if (opts.signal.aborted)
       controller.abort();
@@ -25557,7 +25594,12 @@ async function runLive(opts) {
       startTimer = setTimeout(() => controller.abort(), opts.startTimeoutMs);
     }
     while (!controller.signal.aborted) {
-      const result = await opts.poll(client);
+      const poll = opts.poll(client, controller.signal);
+      const result = await pollUntilAbort(poll, controller.signal);
+      if (result === LIVE_ABORTED) {
+        poll.catch(() => {});
+        break;
+      }
       updates += 1;
       if (startTimer) {
         clearTimeout(startTimer);
@@ -26570,14 +26612,14 @@ function renderBatchView(out, c, result, wrefs, flagsVersion) {
 // ../../packages/warmhub-cli/src/domains/thing/graph.ts
 var graphFlags = {
   depth: flag.number({
-    description: "Resolve embedded graph to this depth (default: 2, max: 5)"
+    description: "Resolve outbound wref fields, assertion backlinks, and assertion about targets to this depth (default: 2, max: 5)"
   }),
   version: flag.number({ description: "Specific version number" })
 };
 var handleThingGraph = async (ctx, { flags, args }) => {
   const wref = args[0];
   if (!wref) {
-    usageError("Usage: wh thing graph <wref> [--depth N]", "wh thing graph Game/base");
+    usageError("Usage: wh thing graph <wref> [--depth N]", "wh thing graph Game/base", "wh thing refs Game/base --inbound");
   }
   const depth = flags.depth;
   if (depth !== undefined && (depth < 1 || depth > 5)) {
@@ -26758,8 +26800,8 @@ function validateKind(value, flagName = "--kind") {
 function resolveRepoContext(ctx) {
   return parseOrgRepo(getRepoRef(ctx), ctx.config);
 }
-function validateComponentFilters(componentId, excludeComponents, ...examples) {
-  if (componentId && excludeComponents) {
+function validateComponentFilters(componentRef, excludeComponents, ...examples) {
+  if (componentRef && excludeComponents) {
     usageError("Cannot combine --component with --exclude-components.", ...examples);
   }
 }
@@ -26835,7 +26877,7 @@ var headFlags = {
     description: "Include retracted things"
   }),
   component: flag.string({
-    description: "Filter to things owned by this component ID"
+    description: "Filter to things owned by this component (Org/Name ref)"
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned things from results"
@@ -26861,15 +26903,15 @@ var handleHead = async (ctx, { flags, args }) => {
     if (cursor || all || limit || ctx.liveMode) {
       usageError("Usage: wh thing list --count [--shape SHAPE] [--kind KIND] [--match PATTERN]", "wh thing list --shape Player --count");
     }
-    const componentId2 = flags.component;
+    const componentRef2 = flags.component;
     const strictExclude2 = !!flags["exclude-components"];
-    validateComponentFilters(componentId2, strictExclude2, "wh thing list --component com.example.pkg");
+    validateComponentFilters(componentRef2, strictExclude2, "wh thing list --component acme/veritas");
     return handleCount(ctx, org, repo, {
       shape,
       kind,
       match,
       includeRetracted,
-      componentId: componentId2,
+      componentRef: componentRef2,
       excludeComponents: strictExclude2,
       excludeInfraShapes: !strictExclude2 && !shape,
       where: where.length > 0 ? where : undefined
@@ -26883,10 +26925,10 @@ var handleHead = async (ctx, { flags, args }) => {
   }
   const boundedLimit = Math.min(limit ?? DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT);
   const pageLimit = all ? Math.min(limit ?? AUTO_PAGE_LIMIT, MAX_PAGE_LIMIT) : boundedLimit;
-  const componentId = flags.component;
+  const componentRef = flags.component;
   const hasShape = !!shape;
   const strictExclude = !!flags["exclude-components"];
-  validateComponentFilters(componentId, strictExclude, "wh thing list --component com.example.pkg");
+  validateComponentFilters(componentRef, strictExclude, "wh thing list --component acme/veritas");
   const excludeComponents = strictExclude;
   const excludeInfraShapes = !strictExclude && !hasShape;
   const headOpts = {
@@ -26896,7 +26938,7 @@ var handleHead = async (ctx, { flags, args }) => {
     includeRetracted,
     limit: pageLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -26928,7 +26970,7 @@ var handleHead = async (ctx, { flags, args }) => {
     includeRetracted,
     limit: pageLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -26939,7 +26981,7 @@ var handleHead = async (ctx, { flags, args }) => {
     includeRetracted,
     limit: boundedLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -26960,7 +27002,7 @@ async function fetchAllHeadPages(ctx, org, repo, opts) {
       includeRetracted: opts.includeRetracted,
       limit: opts.limit,
       cursor,
-      componentId: opts.componentId,
+      componentRef: opts.componentRef,
       excludeComponents: opts.excludeComponents,
       excludeInfraShapes: opts.excludeInfraShapes,
       where: opts.where
@@ -26992,7 +27034,7 @@ var queryFlags = {
     description: "Include assertions about collections (Pair/Triple/Set/List) containing the target. Only applies with --about."
   }),
   component: flag.string({
-    description: "Filter to things owned by this component ID"
+    description: "Filter to things owned by this component (Org/Name ref)"
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned things from results"
@@ -27014,10 +27056,10 @@ var handleQuery = async (ctx, { flags }) => {
   const count = flags.count;
   const includeRetracted = flags["include-retracted"];
   const resolveCollections = flags["resolve-collections"];
-  const componentId = flags.component;
+  const componentRef = flags.component;
   const hasShape = !!shape;
   const strictExclude = !!flags["exclude-components"];
-  validateComponentFilters(componentId, strictExclude, "wh thing query --component com.example.pkg");
+  validateComponentFilters(componentRef, strictExclude, "wh thing query --component acme/veritas");
   const excludeComponents = strictExclude;
   const excludeInfraShapes = !strictExclude && !hasShape;
   const c = ctx.colors;
@@ -27034,7 +27076,7 @@ var handleQuery = async (ctx, { flags }) => {
       about,
       includeRetracted,
       resolveCollections,
-      componentId,
+      componentRef,
       excludeComponents,
       excludeInfraShapes,
       where: where.length > 0 ? where : undefined
@@ -27057,7 +27099,7 @@ var handleQuery = async (ctx, { flags }) => {
     resolveCollections,
     limit: pageLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -27091,7 +27133,7 @@ var handleQuery = async (ctx, { flags }) => {
     resolveCollections,
     limit: pageLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -27104,7 +27146,7 @@ var handleQuery = async (ctx, { flags }) => {
     resolveCollections,
     limit: boundedLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes,
     where: where.length > 0 ? where : undefined
@@ -27127,7 +27169,7 @@ async function fetchAllQueryPages(ctx, org, repo, opts) {
       resolveCollections: opts.resolveCollections,
       limit: opts.limit,
       cursor,
-      componentId: opts.componentId,
+      componentRef: opts.componentRef,
       excludeComponents: opts.excludeComponents,
       excludeInfraShapes: opts.excludeInfraShapes,
       where: opts.where
@@ -27405,7 +27447,7 @@ var searchFlags = {
   cursor: flag.string({ description: "Opaque pagination cursor (text mode)" }),
   all: flag.boolean({ description: "Fetch all pages (text mode)" }),
   component: flag.string({
-    description: "Filter to things owned by this component ID"
+    description: "Filter to things owned by this component (Org/Name ref)"
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned things from results"
@@ -27442,10 +27484,10 @@ var handleSearch = async (ctx, { flags, args }) => {
   const pageLimit = all ? Math.min(limit ?? AUTO_PAGE_LIMIT, MAX_PAGE_LIMIT) : boundedTextLimit;
   const resolveCollections = mode !== "hybrid" ? flags["resolve-collections"] : undefined;
   const supportsComponentFilters = !mode || mode === "text";
-  const componentId = supportsComponentFilters ? flags.component : undefined;
+  const componentRef = supportsComponentFilters ? flags.component : undefined;
   const hasShape = !!flags.shape;
   const strictExclude = supportsComponentFilters ? !!flags["exclude-components"] : false;
-  validateComponentFilters(componentId, strictExclude, 'wh thing search "policy" --component com.example.pkg');
+  validateComponentFilters(componentRef, strictExclude, 'wh thing search "policy" --component acme/veritas');
   const excludeComponents = supportsComponentFilters && strictExclude ? true : undefined;
   const excludeInfraShapes = supportsComponentFilters && !strictExclude && !hasShape ? true : undefined;
   const rawResult = all ? await fetchAllSearchPages(ctx, org, repo, queryText, {
@@ -27456,7 +27498,7 @@ var handleSearch = async (ctx, { flags, args }) => {
     resolveCollections,
     limit: pageLimit,
     cursor,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes
   }) : await ctx.client.thing.search(org, repo, queryText, {
@@ -27468,7 +27510,7 @@ var handleSearch = async (ctx, { flags, args }) => {
     limit: boundedTextLimit,
     cursor,
     mode,
-    componentId,
+    componentRef,
     excludeComponents,
     excludeInfraShapes
   });
@@ -27494,7 +27536,7 @@ async function fetchAllSearchPages(ctx, org, repo, queryText, opts) {
       limit: opts.limit,
       cursor,
       mode: "text",
-      componentId: opts.componentId,
+      componentRef: opts.componentRef,
       excludeComponents: opts.excludeComponents,
       excludeInfraShapes: opts.excludeInfraShapes
     });
@@ -27847,13 +27889,16 @@ var THING_DOMAIN = defineDomain({
     },
     graph: {
       prime: true,
-      summary: "Fetch a thing's graph (forward + reverse references) at a given depth",
+      summary: "Fetch a thing's graph (outbound wref fields, assertion backlinks, and assertion about targets)",
       args: "<wref>",
       flags: graphFlags,
       examples: [
         "wh thing graph Game/base",
         "wh thing graph Game/base --depth 2"
       ],
+      notes: [
+        "`graph` does not traverse inbound wref-field references; use `wh thing refs <wref> --inbound` to find things whose fields point at this thing."
+      ],
       handler: handleThingGraph
     }
   }
@@ -29417,7 +29462,7 @@ function ndjsonMessage(msg) {
   return `${JSON.stringify(msg)}
 `;
 }
-function createMessageReader(input, onMessage) {
+function createMessageReader(input, onMessage, onError = () => {}) {
   let buffer = "";
   let mode = null;
   function drain() {
@@ -29440,9 +29485,12 @@ function createMessageReader(input, onMessage) {
             continue;
           }
         } else {
-          const idx = buffer.indexOf(HEADER_DELIMITER);
-          if (idx !== -1) {
-            buffer = buffer.slice(idx + 4);
+          const headerEnd = buffer.indexOf(HEADER_DELIMITER);
+          if (headerEnd !== -1) {
+            const resyncFrom = headerEnd + HEADER_DELIMITER.length;
+            const nextHeaderMatch = /Content-Length:/i.exec(buffer.slice(resyncFrom));
+            const nextHeader = nextHeaderMatch === null ? -1 : resyncFrom + nextHeaderMatch.index;
+            buffer = nextHeader === -1 ? "" : buffer.slice(nextHeader);
             continue;
           }
         }
@@ -29462,12 +29510,14 @@ function createMessageReader(input, onMessage) {
   };
   input.setEncoding("utf8");
   input.on("data", onData);
+  input.on("error", onError);
   if ("resume" in input && typeof input.resume === "function") {
     input.resume();
   }
   return {
     close() {
       input.removeListener("data", onData);
+      input.removeListener("error", onError);
     }
   };
 }
@@ -29477,9 +29527,25 @@ var MCP_PROTOCOL_VERSION2 = "2025-11-25";
 function createChannelServer(opts) {
   let reader = null;
   let resolveReady;
-  const onReady = new Promise((resolve) => {
+  let rejectReady;
+  let readySettled = false;
+  const onReady = new Promise((resolve, reject) => {
     resolveReady = resolve;
+    rejectReady = reject;
   });
+  function settleReady() {
+    if (readySettled)
+      return;
+    readySettled = true;
+    resolveReady();
+  }
+  function failReady(error) {
+    if (readySettled)
+      return;
+    readySettled = true;
+    reader?.close();
+    rejectReady(error);
+  }
   function send(msg) {
     opts.output.write(ndjsonMessage(msg));
   }
@@ -29502,7 +29568,7 @@ function createChannelServer(opts) {
       return;
     }
     if (method === "notifications/initialized") {
-      resolveReady();
+      settleReady();
       return;
     }
     if (method === "ping") {
@@ -29519,7 +29585,7 @@ function createChannelServer(opts) {
   }
   return {
     start() {
-      reader = createMessageReader(opts.input, handleMessage);
+      reader = createMessageReader(opts.input, handleMessage, failReady);
     },
     notify(content, meta) {
       send({
@@ -29531,6 +29597,7 @@ function createChannelServer(opts) {
     onReady,
     close() {
       reader?.close();
+      settleReady();
     }
   };
 }
@@ -29593,7 +29660,16 @@ var handleChannel = async (ctx) => {
     else
       signal.addEventListener("abort", () => resolve("aborted"), { once: true });
   });
-  const ready = await Promise.race([server.onReady, aborted]);
+  let ready;
+  try {
+    ready = await Promise.race([server.onReady.then(() => {
+      return;
+    }), aborted]);
+  } catch (err) {
+    server.close();
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new CliError(4 /* Backend */, "BACKEND", `channel startup failed: ${msg}`);
+  }
   if (ready === "aborted") {
     server.close();
     return;
@@ -30969,13 +31045,16 @@ async function refreshFromSummaries(repoSlug, parsed, activeItems, client, now,
   const components = {};
   let detailReadFailures = 0;
   for (const item of activeItems) {
+    if (!item.ref)
+      continue;
+    const itemRef = item.ref;
     let detail;
     try {
-      detail = await client.component.get(parsed.org, parsed.repo, item.componentId);
+      detail = await client.component.get(parsed.org, parsed.repo, itemRef);
     } catch {
       detailReadFailures++;
       const previousEntry = previousCache?.components[item.componentName];
-      if (previousEntry?.componentId === item.componentId) {
+      if (previousEntry?.ref === itemRef) {
         components[item.componentName] = previousEntry;
       }
       continue;
@@ -30990,7 +31069,7 @@ async function refreshFromSummaries(repoSlug, parsed, activeItems, client, now,
     if (!ref)
       continue;
     components[item.componentName] = {
-      componentId: item.componentId,
+      ref: itemRef,
       ownerOrgName: ref.ownerOrgName,
       registeredComponentName: ref.registeredComponentName,
       version: manifest.component.version ?? item.version ?? "",
@@ -31350,7 +31429,7 @@ var handleComponentExec = async (ctx, { args, terminator }) => {
   }
   const method = entry.methods.find((m) => m.name === methodName);
   if (!method) {
-    throw new CliError(2 /* UserInput */, "USER_INPUT", `Method '${methodName}' not found on component '${componentName}'.`, undefined, `Available: ${entry.methods.map((m) => m.name).join(", ")}. Run wh component update ${componentName} --repo ${installRepo} if you expect a newer method.`);
+    throw new CliError(2 /* UserInput */, "USER_INPUT", `Method '${methodName}' not found on component '${componentName}'.`, undefined, `Available: ${entry.methods.map((m) => m.name).join(", ")}. Run wh component update ${entry.ref} --repo ${installRepo} if you expect a newer method.`);
   }
   if (helpRequested) {
     renderMethodHelp(ctx, componentName, method);
@@ -31459,7 +31538,7 @@ async function ensureSharedInfra(client, org, repo) {
           name: shape.name,
           data: { fields: shape.fields }
         }
-      ], { componentId: SYSTEM_COMPONENT_ID });
+      ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
     } catch (err) {
       if (!isAlreadyExistsError(err)) {
         throw err;
@@ -31472,7 +31551,7 @@ async function ensureSharedInfra(client, org, repo) {
             name: shape.name,
             data: { fields: shape.fields }
           }
-        ], { componentId: SYSTEM_COMPONENT_ID });
+        ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
       } catch {}
     }
   }
@@ -31505,6 +31584,15 @@ async function doctorComponent(client, org, repo, componentId) {
     };
   }
   const componentName = typeof installData.name === "string" ? installData.name : componentId;
+  const registeredComponentRef = typeof installData.registeredComponentRef === "string" && installData.registeredComponentRef.length > 0 ? installData.registeredComponentRef : undefined;
+  if (!registeredComponentRef) {
+    findings.push({
+      resource: "ComponentInstall",
+      status: "error",
+      message: "Install record is missing registeredComponentRef"
+    });
+    return { componentId, componentName, state: "error", findings };
+  }
   const existingState = typeof installData.state === "string" ? installData.state : undefined;
   if (existingState === "error") {
     findings.push({
@@ -31543,12 +31631,12 @@ async function doctorComponent(client, org, repo, componentId) {
           message: `Shape "${shape.name}" exists but is inactive`
         });
       } else {
-        const shapeComponentId = s && typeof s === "object" && "componentId" in s ? s.componentId : undefined;
-        if (shapeComponentId !== undefined && shapeComponentId !== componentId) {
+        const shapeComponentRef = s && typeof s === "object" && "componentRef" in s ? s.componentRef : undefined;
+        if (shapeComponentRef !== undefined && shapeComponentRef !== registeredComponentRef) {
           findings.push({
             resource: `shape:${shape.name}`,
             status: "warning",
-            message: `Shape "${shape.name}" exists but is owned by "${shapeComponentId}"`
+            message: `Shape "${shape.name}" exists but is owned by "${shapeComponentRef}"`
           });
         } else {
           const expectedShapeData = manifestShapeData(shape);
@@ -31582,19 +31670,19 @@ async function doctorComponent(client, org, repo, componentId) {
     hasSubs = true;
     try {
       const s = await client.subscription.get(org, repo, sub.name);
-      const subComponentId = s && typeof s === "object" && "componentId" in s ? s.componentId : undefined;
-      if (!s.active) {
+      const subComponentRef = s && typeof s === "object" && "componentRef" in s ? s.componentRef : undefined;
+      if (subComponentRef !== undefined && subComponentRef !== registeredComponentRef) {
+        allSubsPaused = false;
         findings.push({
           resource: `sub:${sub.name}`,
-          status: "inactive",
-          message: `Subscription "${sub.name}" is paused`
+          status: "warning",
+          message: `Subscription "${sub.name}" is owned by "${subComponentRef}"`
         });
-      } else if (subComponentId !== undefined && subComponentId !== componentId) {
-        allSubsPaused = false;
+      } else if (!s.active) {
         findings.push({
           resource: `sub:${sub.name}`,
-          status: "warning",
-          message: `Subscription "${sub.name}" is owned by "${subComponentId}"`
+          status: "inactive",
+          message: `Subscription "${sub.name}" is paused`
         });
       } else {
         allSubsPaused = false;
@@ -31664,10 +31752,11 @@ async function doctorComponent(client, org, repo, componentId) {
   const hasMissing = findings.some((f) => f.status === "missing");
   const hasInactive = findings.some((f) => f.status === "inactive" && !f.resource.startsWith("sub:"));
   const hasShapeDrift = findings.some((f) => f.resource.startsWith("shape:") && f.status === "warning" && f.message.includes("differs from installed manifest"));
+  const hasOwnershipConflict = findings.some((f) => (f.resource.startsWith("shape:") || f.resource.startsWith("sub:")) && f.status === "warning" && f.message.includes("owned by"));
   let state;
-  if (hasSubs && allSubsPaused && !hasMissing && !hasInactive && !hasShapeDrift) {
+  if (hasSubs && allSubsPaused && !hasMissing && !hasInactive && !hasShapeDrift && !hasOwnershipConflict) {
     state = "paused";
-  } else if (hasMissing || hasInactive || hasShapeDrift) {
+  } else if (hasMissing || hasInactive || hasShapeDrift || hasOwnershipConflict) {
     state = "degraded";
   } else {
     state = "ready";
@@ -31680,7 +31769,7 @@ async function doctorComponent(client, org, repo, componentId) {
         name: `ComponentInstall/${componentId}`,
         data: { ...installData, state, checkedAt: new Date().toISOString() }
       }
-    ], { componentId: SYSTEM_COMPONENT_ID });
+    ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
   } catch {
     findings.push({
       resource: "state-update",
@@ -31774,6 +31863,22 @@ async function teardownComponent(client, org, repo, componentId) {
     };
   }
   const componentName = typeof installData.name === "string" ? installData.name : componentId;
+  const registeredComponentRef = typeof installData.registeredComponentRef === "string" && installData.registeredComponentRef.length > 0 ? installData.registeredComponentRef : undefined;
+  if (!registeredComponentRef) {
+    return {
+      componentId,
+      componentName,
+      state: "error",
+      steps: [
+        {
+          step: "load-install",
+          status: "error",
+          message: "Install record is missing registeredComponentRef"
+        }
+      ],
+      errors: ["Install record is missing registeredComponentRef"]
+    };
+  }
   let subscriptionNames = [];
   let teardownPolicy = {};
   try {
@@ -31796,9 +31901,9 @@ async function teardownComponent(client, org, repo, componentId) {
     for (const subName of subscriptionNames) {
       try {
         const sub = await client.subscription.get(org, repo, subName);
-        const ownerComponentId = sub && typeof sub === "object" && "componentId" in sub ? sub.componentId : undefined;
-        if (typeof ownerComponentId === "string" && ownerComponentId !== componentId) {
-          const msg = `Subscription "${subName}" is owned by "${ownerComponentId}", not "${componentId}"`;
+        const ownerComponentRef = sub && typeof sub === "object" && "componentRef" in sub ? sub.componentRef : undefined;
+        if (typeof ownerComponentRef === "string" && ownerComponentRef !== registeredComponentRef) {
+          const msg = `Subscription "${subName}" is owned by "${ownerComponentRef}", not "${registeredComponentRef}"`;
           errors.push(msg);
           steps.push({
             step: `pause-${subName}`,
@@ -31847,7 +31952,7 @@ async function teardownComponent(client, org, repo, componentId) {
           updatedAt: new Date().toISOString()
         }
       }
-    ], { componentId: SYSTEM_COMPONENT_ID });
+    ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
     steps.push({ step: "update-state", status: "ok" });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -32069,38 +32174,11 @@ function componentInstallCanonicalId(item) {
   const data = asRecord(item.data);
   return componentInstallIdFromWref(item.wref) ?? readString(data, "id") ?? readString(data, "componentId") ?? item.name;
 }
-function uniqueStrings(values) {
-  return [...new Set(values.filter((value) => Boolean(value)))];
-}
-function componentInstallIdentityIds(item) {
-  const data = asRecord(item.data);
-  return uniqueStrings([
-    componentInstallCanonicalId(item),
-    readString(data, "id"),
-    readString(data, "componentId"),
-    item.name
-  ]);
-}
-function componentInstallHasExactId(item, name) {
-  return componentInstallIdentityIds(item).includes(name);
+function componentInstallHasRegisteredRef(item, ref) {
+  return readString(asRecord(item.data), "registeredComponentRef") === ref;
 }
-function componentInstallHasDisplayName(item, name) {
-  return readString(asRecord(item.data), "name") === name;
-}
-function formatComponentInstallAmbiguity(name, matches) {
-  const componentIds = uniqueStrings(matches.map((item) => componentInstallCanonicalId(item)));
-  const listedIds = componentIds.map((id) => `- ${id}`).join(`
-`);
-  const exampleId = componentIds[0] ?? name;
-  return {
-    message: `Component name "${name}" is ambiguous. It matches multiple installed components:
-${listedIds}`,
-    hint: `Use a component id instead, for example: wh component doctor ${exampleId}`
-  };
-}
-async function resolveComponentDoctorId(client, org, repo, name) {
+async function resolveInstalledComponentRefId(client, org, repo, ref) {
   let cursor;
-  const displayNameMatches = [];
   do {
     const result = await client.thing.head(org, repo, {
       shape: "ComponentInstall",
@@ -32109,35 +32187,27 @@ async function resolveComponentDoctorId(client, org, repo, name) {
       cursor
     });
     const items = result.items ?? [];
-    const exactMatch = items.find((item) => componentInstallHasExactId(item, name));
+    const exactMatch = items.find((item) => componentInstallHasRegisteredRef(item, ref));
     const resolved = exactMatch ? componentInstallCanonicalId(exactMatch) : undefined;
     if (resolved) {
       return resolved;
     }
-    displayNameMatches.push(...items.filter((item) => componentInstallHasDisplayName(item, name)));
     cursor = result.nextCursor;
   } while (cursor);
-  if (displayNameMatches.length === 1) {
-    return componentInstallCanonicalId(displayNameMatches[0]) ?? name;
-  }
-  if (displayNameMatches.length > 1) {
-    const { message, hint } = formatComponentInstallAmbiguity(name, displayNameMatches);
-    throw new CliError(2 /* UserInput */, "USER_INPUT", message, undefined, hint);
-  }
-  return name;
+  throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${ref}' is not installed. Run 'wh component install <org>/<name>' first.`);
 }
 var handleUpdate = async (ctx, { args }) => {
-  const name = args[0];
-  if (!name) {
-    usageError("Usage: wh component update <name> --repo org/repo", "wh component update research-knowledge --repo org/repo");
+  const ref = args[0];
+  const usage = "Usage: wh component update <org/name> --repo org/repo";
+  const example = "wh component update warmhub/research-knowledge --repo org/repo";
+  if (!ref) {
+    usageError(usage, example);
   }
-  const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
-  try {
-    await ctx.client.thing.get(org, repo, `ComponentInstall/${name}`);
-  } catch {
-    throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${name}' is not installed. Run 'wh component install <org>/<name>' first.`);
+  resolveRegisteredComponentRef(ref, usage, example);
+  if (ctx.liveMode === false) {
+    usageError("Dry-run is not supported for component update.", "wh component update warmhub/research-knowledge --repo org/repo");
   }
-  throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${name}' was not installed from a registered component and can no longer be updated in place.`, undefined, "Register the component (`wh component register <name> --org <org> --manifest <path>`) and reinstall it with `wh component install <org>/<name>`.");
+  throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${ref}' could not be updated through the component shell boundary.`, undefined, "Run `wh component update <org/name> --repo org/repo` without --dry-run.");
 };
 var handleRegister = async (ctx, { flags, args }) => {
   const componentName = args[0];
@@ -32230,8 +32300,7 @@ var handleRegistryUpdate = async (ctx, { flags, args }) => {
 };
 var handleInstall = async (ctx, { args }) => {
   const source = args[0];
-  const usage = `Usage: wh component install <source> --repo org/repo
-  source: <org>/<name> (registered component)`;
+  const usage = "Usage: wh component install <org/name> --repo org/repo";
   const example = "wh component install warmhub/veritas --repo myorg/myrepo";
   if (!source) {
     usageError(usage, example);
@@ -32276,7 +32345,7 @@ var handleList2 = async (ctx, { flags }) => {
       const state = item.state ?? "unknown";
       const source = item.source ?? "-";
       const stateColor = stateToColor(c, state);
-      ctx.out(`  ${c.cyan}${item.componentId}${c.reset}  ${stateColor}${state}${c.reset}  ${c.dim}v${version}${c.reset}  ${source}`);
+      ctx.out(`  ${c.cyan}${item.ref ?? item.componentName}${c.reset}  ${stateColor}${state}${c.reset}  ${c.dim}v${version}${c.reset}  ${source}`);
     }
   });
 };
@@ -32289,7 +32358,7 @@ var handleSearch2 = async (ctx, { flags, args }) => {
   const c = ctx.colors;
   const { items: allItems, nextCursor } = await fetchComponentPages(ctx.client, org, repo, { all: flags.all, limit: flags.limit, cursor: flags.cursor });
   const needle = query.toLowerCase();
-  const items = allItems.filter((item) => [item.componentId, item.componentName, item.source].filter((value) => typeof value === "string").some((value) => value.toLowerCase().includes(needle)));
+  const items = allItems.filter((item) => [item.ref, item.componentName, item.source].filter((value) => typeof value === "string").some((value) => value.toLowerCase().includes(needle)));
   if (!flags.all && nextCursor) {
     ctx.status(`${c.yellow}${allItems.length} component(s) searched, more pages available${c.reset} — matches beyond this page were not searched. ` + `Use ${c.cyan}--all${c.reset} to search every page, ` + `or re-run the same command plus ${c.cyan}--cursor=${nextCursor}${c.reset} to continue from here.`);
   }
@@ -32305,22 +32374,22 @@ var handleSearch2 = async (ctx, { flags, args }) => {
       const state = item.state ?? "unknown";
       const source = item.source ?? "-";
       const stateColor = stateToColor(c, state);
-      ctx.out(`  ${c.cyan}${item.componentId}${c.reset}  ${stateColor}${state}${c.reset}  ${c.dim}v${version}${c.reset}  ${source}`);
+      ctx.out(`  ${c.cyan}${item.ref ?? item.componentName}${c.reset}  ${stateColor}${state}${c.reset}  ${c.dim}v${version}${c.reset}  ${source}`);
     }
   });
 };
 var handleView3 = async (ctx, { args }) => {
-  const name = args[0];
-  const usage = "Usage: wh component view <name> --repo org/repo";
-  const example = "wh component view research-knowledge --repo myorg/myrepo";
-  if (!name) {
+  const ref = args[0];
+  const usage = "Usage: wh component view <org/name> --repo org/repo";
+  const example = "wh component view myorg/research-knowledge --repo myorg/myrepo";
+  if (!ref) {
     usageError(usage, example);
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
-  const viewData = await ctx.client.component.get(org, repo, name);
+  const viewData = await ctx.client.component.get(org, repo, ref);
   writeOutput(ctx, viewData, () => {
     const c = ctx.colors;
-    ctx.out(`${c.bold}Component:${c.reset} ${c.cyan}${name}${c.reset}`);
+    ctx.out(`${c.bold}Component:${c.reset} ${c.cyan}${viewData.ref ?? ref}${c.reset}`);
     ctx.out(`${c.bold}Version:${c.reset} ${viewData.version ?? "unknown"}`);
     ctx.out(`${c.bold}State:${c.reset} ${viewData.state ?? "-"}`);
     ctx.out(`${c.bold}Source:${c.reset} ${viewData.source ?? "-"}`);
@@ -32396,23 +32465,24 @@ function renderValidationResult(ctx, result) {
 var handleDoctor = async (ctx, { args }) => {
   const name = args[0];
   if (!name) {
-    usageError("Usage: wh component doctor <name> --repo org/repo", "wh component doctor research-knowledge --repo myorg/myrepo");
+    usageError("Usage: wh component doctor <org/name> --repo org/repo", "wh component doctor warmhub/research-knowledge --repo myorg/myrepo");
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
-  const componentId = await resolveComponentDoctorId(ctx.client, org, repo, name);
+  const componentId = await resolveInstalledComponentRefId(ctx.client, org, repo, name);
   const result = await doctorComponent(ctx.client, org, repo, componentId);
   writeOutput(ctx, result, () => renderDoctorResult(ctx, result));
 };
 var handleTeardown = async (ctx, { args }) => {
   const name = args[0];
   if (!name) {
-    usageError("Usage: wh component teardown <name> --repo org/repo", "wh component teardown research-knowledge --repo myorg/myrepo");
+    usageError("Usage: wh component teardown <org/name> --repo org/repo", "wh component teardown warmhub/research-knowledge --repo myorg/myrepo");
   }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const repoSlug = `${org}/${repo}`;
+  const componentId = await resolveInstalledComponentRefId(ctx.client, org, repo, name);
   let result;
   try {
-    result = await teardownComponent(ctx.client, org, repo, name);
+    result = await teardownComponent(ctx.client, org, repo, componentId);
   } catch (error) {
     invalidateInstallSnapshotCache(repoSlug);
     throw error;
@@ -32543,7 +32613,7 @@ var COMPONENT_DOMAIN = defineDomain({
     install: {
       prime: true,
       summary: "Install a registered component by its <org>/<name> ref",
-      args: "<source>",
+      args: "<org/name>",
       flags: installFlags,
       examples: [
         "wh component install warmhub/identity --repo org/repo",
@@ -32553,9 +32623,9 @@ var COMPONENT_DOMAIN = defineDomain({
     },
     update: {
       summary: "Update an installed registered component to the latest manifest",
-      args: "<name>",
+      args: "<org/name>",
       flags: updateFlags,
-      examples: ["wh component update research-knowledge --repo org/repo"],
+      examples: ["wh component update warmhub/identity --repo org/repo"],
       handler: handleUpdate
     },
     list: {
@@ -32569,25 +32639,25 @@ var COMPONENT_DOMAIN = defineDomain({
     view: {
       prime: true,
       summary: "Show component details",
-      args: "<name>",
+      args: "<org/name>",
       flags: viewFlags3,
-      examples: ["wh component view research-knowledge --repo org/repo"],
+      examples: ["wh component view warmhub/identity --repo org/repo"],
       handler: handleView3
     },
     teardown: {
       prime: true,
       summary: "Pause component subscriptions",
-      args: "<name>",
+      args: "<org/name>",
       flags: teardownFlags,
-      examples: ["wh component teardown research-knowledge --repo org/repo"],
+      examples: ["wh component teardown warmhub/identity --repo org/repo"],
       handler: handleTeardown
     },
     doctor: {
       prime: true,
       summary: "Run component health checks",
-      args: "<name>",
+      args: "<org/name>",
       flags: doctorFlags,
-      examples: ["wh component doctor research-knowledge --repo org/repo"],
+      examples: ["wh component doctor warmhub/identity --repo org/repo"],
       handler: handleDoctor
     },
     init: {
@@ -33035,7 +33105,7 @@ import { basename } from "node:path";
 // ../../packages/warmhub-cli/src/harness.ts
 import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir as homedir4 } from "node:os";
-import { dirname as dirname6, join as join6 } from "node:path";
+import { dirname as dirname6, join as join5 } from "node:path";
 var AGENTS_BEGIN_MARKER = "<!-- BEGIN WARMHUB CLI INTEGRATION -->";
 var AGENTS_END_MARKER = "<!-- END WARMHUB CLI INTEGRATION -->";
 var PRIME_COMMAND = "wh prime";
@@ -33055,10 +33125,10 @@ function getHarnessPaths(opts) {
   const userHome = opts?.homeDir ?? homedir4();
   return {
     repoDir,
-    agentsPath: join6(repoDir, "AGENTS.md"),
-    projectSettingsPath: join6(repoDir, ".claude", "settings.json"),
-    projectLocalSettingsPath: join6(repoDir, ".claude", "settings.local.json"),
-    globalSettingsPath: join6(userHome, ".claude", "settings.json")
+    agentsPath: join5(repoDir, "AGENTS.md"),
+    projectSettingsPath: join5(repoDir, ".claude", "settings.json"),
+    projectLocalSettingsPath: join5(repoDir, ".claude", "settings.local.json"),
+    globalSettingsPath: join5(userHome, ".claude", "settings.json")
   };
 }
 async function readJsonFile(path2) {
@@ -34459,17 +34529,18 @@ cat wrefs.txt | wh thing view --format jsonl        # one JSON line per *deduped
 - \`wh credential revoke <setName> [--repo org/repo | --org org] [--reason]\` — Revoke a credential set (blocks new binds and strips auth from existing webhook deliveries)
 
 ### component — Component management
-- \`wh component validate <path>\` — Validate a component package from disk
-- \`wh component install <source>\` — Install a component from a bundled system id or a registered \`<org>/<name>\`
-- \`wh component register <name> --org <org> --manifest <path> [flags]\` — Register a component identity (first manifest version) for \`install <org/name>\`
+- \`wh component validate <path>\` — Validate package
+- \`wh component install <org/name>\` — Install a registered component
+- \`wh component register <name> --org <org> --manifest <path> [flags]\` — Register component identity
 - \`wh component unregister <org/name>\` — Remove a registered component identity
 - \`wh component registry list --org <org>\` — List registered components
 - \`wh component registry view <org/name>\` — View a registered component
 - \`wh component registry update <org/name> [flags]\` — Update a registered component
 - \`wh component list\` — List installed components
-- \`wh component view <name>\` — Show component details (alias: show)
-- \`wh component doctor <name>\` — Run component health checks
-- \`wh component teardown <name>\` — Pause component subscriptions
+- \`wh component update <org/name>\` — Update installed component
+- \`wh component view <org/name>\` — Show component details (alias: show)
+- \`wh component doctor <org/name>\` — Run component health checks
+- \`wh component teardown <org/name>\` — Pause component subscriptions
 
 ### Getting More Info
 - \`wh help\` — full help overview
@@ -35481,7 +35552,7 @@ var FIELD_CONSTRAINTS_NOTES = [
 var listFlags4 = {
   match: flag.string({ description: "Filter by name glob pattern" }),
   component: flag.string({
-    description: "Filter to shapes owned by this component ID"
+    description: "Filter to shapes owned by this component (Org/Name ref)"
   }),
   "exclude-components": flag.boolean({
     description: "Exclude component-owned shapes from results"
@@ -35494,13 +35565,13 @@ var handleList6 = async (ctx, { flags }) => {
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const c = ctx.colors;
   const match = flags.match;
-  const componentId = flags.component;
+  const componentRef = flags.component;
   const excludeComponents = !!flags["exclude-components"];
   const includeRetracted = flags["include-retracted"];
-  validateComponentFilters(componentId, excludeComponents, "wh shape list --component com.example.pkg", "wh shape list --exclude-components");
+  validateComponentFilters(componentRef, excludeComponents, "wh shape list --component acme/veritas", "wh shape list --exclude-components");
   const result = await ctx.client.shape.list(org, repo, {
     match,
-    componentId,
+    componentRef,
     excludeComponents,
     includeRetracted
   });
@@ -35567,9 +35638,9 @@ var handleView7 = async (ctx, { flags, args }) => {
     if (typeof shapeDescription === "string" && shapeDescription) {
       ctx.out(`  ${c.dim}${shapeDescription}${c.reset}`);
     }
-    const cid = result.componentId;
-    if (cid) {
-      ctx.out(`  ${c.dim}owner:${c.reset} ${c.yellow}${cid}${c.reset}`);
+    const componentRef = result.componentRef;
+    if (componentRef) {
+      ctx.out(`  ${c.dim}owner:${c.reset} ${c.yellow}${componentRef}${c.reset}`);
     }
     const fields = shapeData?.fields;
     if (fields) {
@@ -37869,10 +37940,6 @@ async function dispatch(ctx) {
   const { command } = ctx.invocation;
   if (!command || command === "help") {
     const helpTarget = command === "help" ? ctx.invocation.positional[0] : undefined;
-    if (ctx.format === "json") {
-      printJson(ctx.out, buildCliSpec());
-      return;
-    }
     if (helpTarget) {
       const domain = registry.getDomain(helpTarget);
       if (domain) {
@@ -37881,6 +37948,10 @@ async function dispatch(ctx) {
         throw new CliError(2 /* UserInput */, "USER_INPUT", `Unknown command: ${helpTarget}`, undefined, "Run 'wh help' for available commands.");
       }
     } else {
+      if (ctx.format === "json") {
+        printJson(ctx.out, buildCliSpec());
+        return;
+      }
       let repoSlug;
       try {
         const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
@@ -37932,6 +38003,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
   const errors = [];
   const { meta, manifest } = pkg;
   const componentId = meta.id;
+  const componentRef = source.registeredComponentRef;
   const validation = validateComponentPackage(pkg);
   if (!validation.valid) {
     const validationErrors = validation.findings.filter((f) => f.level === "error").map((f) => f.message);
@@ -37982,7 +38054,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
   const oldCredNames = wasIncomplete ? new Set : new Set(oldManifest?.credentials?.map((c) => c.name) ?? []);
   const liveShapeNames = new Set;
   const liveShapeDataByName = new Map;
-  const liveShapeComponentIdByName = new Map;
+  const liveShapeComponentRefByName = new Map;
   for (const shape of reconcileShapes) {
     if (isFailedInstallState || previousState !== "degraded" && !oldShapeNames.has(shape.name)) {
       continue;
@@ -37999,7 +38071,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
           includeRetracted: true
         });
         liveShapeDataByName.set(shape.name, liveShape.version?.data);
-        liveShapeComponentIdByName.set(shape.name, liveShape.componentId);
+        liveShapeComponentRefByName.set(shape.name, liveShape.componentRef);
       } catch {}
     } catch {}
   }
@@ -38034,7 +38106,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
       data: manifestShapeData(shape)
     }));
     try {
-      await client.commit.apply(org, repo, `Add new shapes for ${meta.name}`, shapeOps, { componentId });
+      await client.commit.apply(org, repo, `Add new shapes for ${meta.name}`, shapeOps, { componentRef });
       steps.push({ step: "add-new-shapes", status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -38050,8 +38122,8 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
     if (!liveShapeNames.has(shape.name))
       return false;
     const liveData = liveShapeDataByName.get(shape.name);
-    const liveComponentId = liveShapeComponentIdByName.get(shape.name);
-    return liveComponentId !== componentId || !shapeDataEquals(manifestShapeData(shape), liveData);
+    const liveComponentRef = liveShapeComponentRefByName.get(shape.name);
+    return liveComponentRef !== componentRef || !shapeDataEquals(manifestShapeData(shape), liveData);
   });
   if (changedShapes.length > 0) {
     const shapeOps = changedShapes.map((shape) => ({
@@ -38061,7 +38133,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
       data: manifestShapeData(shape)
     }));
     try {
-      await client.commit.apply(org, repo, `Reconcile shapes for ${meta.name}`, shapeOps, { componentId });
+      await client.commit.apply(org, repo, `Reconcile shapes for ${meta.name}`, shapeOps, { componentRef });
       steps.push({ step: "claim-existing-shapes", status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -38127,7 +38199,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
         filterJson: compiled.filterJson,
         webhookUrl: compiled.webhookUrl,
         fallbackWebhookUrl: compiled.fallbackWebhookUrl,
-        componentId
+        componentRef
       });
       steps.push({ step: `add-sub-${sub.name}`, status: "ok" });
     } catch (err) {
@@ -38166,8 +38238,8 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
     }
     try {
       const liveSub = await client.subscription.get(org, repo, sub.name);
-      if (liveSub.componentId && liveSub.componentId !== componentId) {
-        const msg = `Subscription "${sub.name}" is owned by component "${liveSub.componentId}"`;
+      if (liveSub.componentRef && liveSub.componentRef !== componentRef) {
+        const msg = `Subscription "${sub.name}" is owned by component "${liveSub.componentRef}"`;
         errors.push(msg);
         steps.push({ step: stepName, status: "error", message: msg });
         continue;
@@ -38185,7 +38257,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
             filterJson: compiled.filterJson,
             webhookUrl: compiled.webhookUrl,
             fallbackWebhookUrl: compiled.fallbackWebhookUrl,
-            componentId
+            componentRef
           });
         } catch (createErr) {
           const createMsg = createErr instanceof Error ? createErr.message : String(createErr);
@@ -38242,7 +38314,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
             name: `${seed.shape}/${seed.name}`,
             data: seed.data
           }
-        ], { componentId });
+        ], { componentRef });
       } catch (reviseErr) {
         const reviseMsg = reviseErr instanceof Error ? reviseErr.message : String(reviseErr);
         const reviseLooksMissing = reviseMsg.includes("not found") || reviseMsg.includes("NOT_FOUND");
@@ -38258,7 +38330,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
               name: `${seed.shape}/${seed.name}`,
               data: seed.data
             }
-          ], { componentId });
+          ], { componentRef });
         } catch (addErr) {
           const msg = addErr instanceof Error ? addErr.message : String(addErr);
           if (!isAlreadyExistsError(addErr)) {
@@ -38283,8 +38355,8 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
           componentId,
           name: meta.name,
           version: meta.version,
-          source: source.githubUrl ?? "local",
-          sourceKind: source.sourceKind ?? (source.githubUrl ? "github" : "local"),
+          source: "registry",
+          sourceKind: "registered",
           sourceRef: source.ref ?? "",
           resolvedSha: source.resolvedSha ?? "",
           ...source.registeredComponentRef ? { registeredComponentRef: source.registeredComponentRef } : {},
@@ -38296,7 +38368,7 @@ async function reconcileComponent(client, org, repo, pkg, source, existingInstal
           ...source.installId ?? persistedInstallId ? { installId: source.installId ?? persistedInstallId } : {}
         }
       }
-    ], { componentId: SYSTEM_COMPONENT_ID });
+    ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
     steps.push({ step: "update-install-record", status: "ok" });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -38411,8 +38483,8 @@ async function installComponent(client, org, repo, pkg, source) {
           componentId,
           name: meta.name,
           version: meta.version,
-          source: source.githubUrl ?? "local",
-          sourceKind: source.sourceKind ?? (source.githubUrl ? "github" : "local"),
+          source: "registry",
+          sourceKind: "registered",
           sourceRef: source.ref ?? "",
           resolvedSha: source.resolvedSha ?? "",
           ...source.registeredComponentRef ? { registeredComponentRef: source.registeredComponentRef } : {},
@@ -38423,7 +38495,7 @@ async function installComponent(client, org, repo, pkg, source) {
           ...source.installId ? { installId: source.installId } : {}
         }
       }
-    ], { componentId: SYSTEM_COMPONENT_ID });
+    ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
     steps.push({ step: "create-install-record", status: "ok" });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -38439,13 +38511,13 @@ async function installComponent(client, org, repo, pkg, source) {
       data: manifestShapeData(shape)
     }));
     try {
-      await client.commit.apply(org, repo, `Add shapes for ${meta.name}`, shapeOps, { componentId });
+      await client.commit.apply(org, repo, `Add shapes for ${meta.name}`, shapeOps, { componentRef: source.registeredComponentRef });
       steps.push({ step: "create-shapes", status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (isAlreadyExistsError(err)) {
         try {
-          await reconcileShapesAfterCreateConflict(client, org, repo, pkg);
+          await reconcileShapesAfterCreateConflict(client, org, repo, pkg, source);
           steps.push({
             step: "create-shapes",
             status: "ok",
@@ -38522,7 +38594,7 @@ async function installComponent(client, org, repo, pkg, source) {
         filterJson: compiled.filterJson,
         webhookUrl: compiled.webhookUrl,
         fallbackWebhookUrl: compiled.fallbackWebhookUrl,
-        componentId
+        componentRef: source.registeredComponentRef
       });
       steps.push({ step: `create-sub-${sub.name}`, status: "ok" });
     } catch (err) {
@@ -38561,7 +38633,7 @@ async function installComponent(client, org, repo, pkg, source) {
           name: seedName,
           data: seed.data
         }
-      ], { componentId });
+      ], { componentRef: source.registeredComponentRef });
       steps.push({ step: `seed-${seedName}`, status: "ok" });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -38588,8 +38660,8 @@ async function installComponent(client, org, repo, pkg, source) {
           componentId,
           name: meta.name,
           version: meta.version,
-          source: source.githubUrl ?? "local",
-          sourceKind: source.sourceKind ?? (source.githubUrl ? "github" : "local"),
+          source: "registry",
+          sourceKind: "registered",
           sourceRef: source.ref ?? "",
           resolvedSha: source.resolvedSha ?? "",
           ...source.registeredComponentRef ? { registeredComponentRef: source.registeredComponentRef } : {},
@@ -38601,7 +38673,7 @@ async function installComponent(client, org, repo, pkg, source) {
           ...source.installId ? { installId: source.installId } : {}
         }
       }
-    ], { componentId: SYSTEM_COMPONENT_ID });
+    ], { componentRef: SYSTEM_REGISTERED_COMPONENT_REF });
     steps.push({ step: "finalize", status: "ok" });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -38619,12 +38691,12 @@ function assertCliMethodsAllowedForSource(pkg, source) {
   const hasCliMethods = (pkg.manifest.cli?.methods?.length ?? 0) > 0;
   if (!hasCliMethods)
     return;
-  if (source.sourceKind === "registered" && typeof source.registeredComponentRef === "string" && source.registeredComponentRef.length > 0) {
+  if (typeof source.registeredComponentRef === "string" && source.registeredComponentRef.length > 0) {
     return;
   }
   throw new CliError(2 /* UserInput */, "USER_INPUT", "Components that declare manifest.cli.methods must be installed from the registry.", undefined, "Register the component, then install it as <org>/<name>. Local path and GitHub URL installs cannot expose CLI methods.");
 }
-async function reconcileShapesAfterCreateConflict(client, org, repo, pkg) {
+async function reconcileShapesAfterCreateConflict(client, org, repo, pkg, source) {
   const { meta, manifest } = pkg;
   const existingShapes = new Map;
   for (const shape of manifest.shapes) {
@@ -38632,8 +38704,8 @@ async function reconcileShapesAfterCreateConflict(client, org, repo, pkg) {
       const existingShape = await client.shape.get(org, repo, shape.name, {
         includeRetracted: true
       });
-      if (existingShape.componentId !== meta.id) {
-        const owner = existingShape.componentId ? `owned by component "${existingShape.componentId}"` : "not owned by this component";
+      if (existingShape.componentRef !== source.registeredComponentRef) {
+        const owner = existingShape.componentRef ? `owned by component "${existingShape.componentRef}"` : "not owned by this component";
         throw new Error(`Shape "${shape.name}" already exists and is ${owner}; cannot reconcile during fresh install`);
       }
       existingShapes.set(shape.name, existingShape);
@@ -38655,7 +38727,7 @@ async function reconcileShapesAfterCreateConflict(client, org, repo, pkg) {
           name: shape.name,
           data
         }
-      ], { componentId: meta.id });
+      ], { componentRef: source.registeredComponentRef });
       continue;
     }
     try {
@@ -38666,7 +38738,7 @@ async function reconcileShapesAfterCreateConflict(client, org, repo, pkg) {
           name: shape.name,
           data
         }
-      ], { componentId: meta.id });
+      ], { componentRef: source.registeredComponentRef });
     } catch (err) {
       if (isAlreadyExistsError(err)) {
         throw new Error(`Shape "${shape.name}" already exists but ownership could not be verified; cannot reconcile during fresh install`);
@@ -39081,7 +39153,7 @@ function resolveLogLevel(flags, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.52.1",
+  version: "0.53.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -39228,14 +39300,17 @@ async function maybeHandleComponentShellBoundary(argv, deps = {}) {
         callRegisteredSetup: callRegisteredSetupImpl
       });
     }
-    const name = invocation.positional[1];
-    if (!name) {
+    const componentRef = invocation.positional[1];
+    if (!componentRef) {
       return;
     }
+    if (!isRegisteredComponentSource(componentRef)) {
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid component reference '${componentRef}'. Expected '<org>/<name>' with no extra slashes and no empty parts.`, undefined, "Usage: wh component update <org/name> --repo org/repo");
+    }
     const repoFlag = getStringFlag(invocation.flags, "repo") ?? config.defaultRepo;
     const refOverride = getStringFlag(invocation.flags, "ref");
     return await handleComponentUpdate({
-      name,
+      componentRef,
       repoFlag,
       refOverride,
       client,
@@ -39306,7 +39381,6 @@ async function performRegisteredInstall(args) {
   invalidateInstallSnapshotCache(installRepo);
   const result = await args.installFromManifest(args.client, args.parsedRepo.org, args.parsedRepo.repo, resolved.manifest, {
     installId,
-    sourceKind: "registered",
     registeredComponentRef: args.componentRef
   });
   if (!result.ok) {
@@ -39371,11 +39445,15 @@ function warmHubErrorBackendCode(error) {
 async function handleComponentUpdate(args) {
   const parsedRepo = parseOrgRepo(args.repoFlag, args.config);
   const installRepo = `${parsedRepo.org}/${parsedRepo.repo}`;
-  const installThing = await args.client.thing.get(parsedRepo.org, parsedRepo.repo, `ComponentInstall/${args.name}`);
+  const componentId = await resolveInstalledComponentRefId(args.client, parsedRepo.org, parsedRepo.repo, args.componentRef);
+  const installThing = await args.client.thing.get(parsedRepo.org, parsedRepo.repo, `ComponentInstall/${componentId}`);
   const installData = installThing.data && typeof installThing.data === "object" ? installThing.data : {};
   const source = resolveComponentUpdateSource(installData);
   if (source.kind === "registered") {
     rejectRefForRegistered(source.componentRef, args.refOverride);
+    if (source.componentRef !== args.componentRef) {
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${args.componentRef}' resolved to an install for '${source.componentRef}', which is inconsistent with the install record.`);
+    }
     return performRegisteredInstall({
       componentRef: source.componentRef,
       persistedInstallData: installData,
@@ -39391,9 +39469,9 @@ async function handleComponentUpdate(args) {
     });
   }
   if (source.kind === "system") {
-    throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${args.name}' is a platform-managed system install and cannot be updated via the CLI; it is reconciled automatically by the WarmHub backend.`);
+    throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${args.componentRef}' is a platform-managed system install and cannot be updated via the CLI; it is reconciled automatically by the WarmHub backend.`);
   }
-  throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${args.name}' was not installed from a registered component and can no longer be updated in place.`, undefined, "Register the component (`wh component register <name> --org <org> --manifest <path>`) and reinstall it with `wh component install <org>/<name>`.");
+  throw new CliError(2 /* UserInput */, "USER_INPUT", `Component '${args.componentRef}' was not installed from a registered component and can no longer be updated in place.`, undefined, "Register the component (`wh component register <name> --org <org> --manifest <path>`) and reinstall it with `wh component install <org>/<name>`.");
 }
 async function writeInstallResult(writeOut, writeErr, format, verb, result, installRepo, client) {
   if (result.ok) {
@@ -39866,4 +39944,4 @@ if (!updateCheckSuppressedByArgv && shouldRunUpdateCheck(updateEligibility)) {
 var interceptedExitCode = await maybeHandleComponentShellBoundary(dispatchArgv);
 process.exitCode = interceptedExitCode === undefined ? await runCli(dispatchArgv, { version: package_default3.version }) : interceptedExitCode;
 
-//# debugId=4117FD49D270041C64756E2164756E21
+//# debugId=E69740B781D6D4C864756E2164756E21