@kontextmind/kxm 0.7.55 → 0.7.57

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.55",
+      "version": "0.7.57",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -35,6 +35,29 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **`kxm tenant status`: one composed read for the portal, with the authorities labelled.**
+  The portal needs hub metadata (roster, message queue, the hub's run projection) *and* the
+  Runtime's authoritative run state, and the failure mode S2 exists to prevent is rendering
+  one as the other. The new command reads both and labels every value with its source
+  (`hub-projection` vs `runtime-authoritative`); an unreadable upstream becomes
+  `unavailable` with a stable reason instead of being filled from the surviving source;
+  projection/authoritative disagreements are listed as `discrepancies` rather than averaged;
+  and `degraded` marks a partial read so `ok: true` never means "everything was seen". The
+  hub read resolves the **admin** credential only — a project token would 401 on the snapshot route —
+  and a malformed persisted record degrades that one source as `hub_credential_unreadable` rather than
+  aborting the Runtime read with it. Reads run concurrently with a 5 s hub deadline, a 200 with an
+  unusable body is `hub_response_invalid` rather than a healthy empty snapshot, and Runtime rows are
+  event-log folded (the listing endpoint now folds, so a cached row can no longer be presented as
+  state). A run whose fold refuses is labelled `runtime-cached` — the cache, not state — and is
+  excluded from the cross-check, which reports `unverifiedFoldRuns` (or `runtime_fold_failed`)
+  instead of letting a corrupt event log print "agree"; `kxm runs list` names the same failure on
+  the row instead of hiding it. The cross-check is honest about id spaces: hub runs and Runtime
+  runs mint ids independently, so zero shared ids reports `unverified` (`run_identity_link_absent`)
+  — never agreement — and only cleanly folded shared ids are compared. The Runtime read **attaches** to a live supervisor
+  (`attachKxmSupervisor`, new) and never starts one — a portal poller must not conjure a daemon, and
+  "nothing is running" is an answer to render, not a condition to repair. Exits non-zero only when
+  neither source could be read.
+
 - **A Pi producer reply can no longer mint its own success.** `determineOutcome` scanned the
   reply for any declared outcome *word* and, failing that, returned `passed`. So
   `"the gate did not pass, so I would not call this passed"` settled the step as passed — the

package/docs/configuration.md

@@ -273,6 +273,7 @@ The current hub command groups are `agent`, `session`, `workflow`, `gate`, `hub`
 | Command | Purpose |
 |---|---|
 | `kxm init` | Atomically create a provenance-tracked minimal KXM project, validate it without rewriting, resume a pinned interrupted create/repair, apply conflict-free non-authority template updates, or join an existing clone with repeatable `--repository <id=absolute-path>` member bindings stored outside Git. `--dry-run` performs no writes. Provenance-free/ambiguous repair and permission-expanding changes remain planning-only. These configuration slices do **not** activate a KXM Runtime. `kxm init` is project-only; bind a running hub with `kxm hub bind <url>` |
+| `kxm tenant status` | One composed read for machine clients (the portal backend): hub metadata (agent roster, message queue, plans, the hub own workflow runs with stages/progress) and the Runtime **authoritative** run state (event-log folded, per-run `homeRuntimeId`), every value labelled with its source. Reads both sources concurrently with a hub deadline (5 s default); an unreadable upstream becomes `unavailable` with a stable reason (`hub_unreachable`, `hub_timeout`, `hub_unauthorized`, `hub_response_invalid`, `hub_credential_unreadable`, `runtime_supervisor_not_running`) instead of being filled from the other source. The cross-check is honest about id spaces: hub and Runtime runs mint ids independently, so no shared id reports `unverified` (`run_identity_link_absent`) — never agreement; shared ids are compared and disagreements listed; a Runtime row whose event-log fold failed is labelled `runtime-cached` and excluded from the comparison (`unverifiedFoldRuns`), never counted as agreement. `degraded` marks a partial read. Attaches to a live supervisor and never starts one; resolves the **admin** credential only (a project token cannot read the snapshot). Requires a KXM project |
 | `kxm trust diff [--base <rev>]` | Print the structured `kxm.permission-diff.v1` report between a base Git revision (default `HEAD`, materialized into a temporary shadow with a sanitized environment) and the working tree: every authority-bearing field change classified as expansion, narrowing, or neutral with per-field hashes. Performs no project writes |
 | `kxm trust check [--base <rev>]` | Exit non-zero when any expansion exists, so an authority-bearing change cannot merge without a reviewed Git change. Formatting/description-only changes never require review |
 | `kxm run <workflow> [prompt]` | Auto-start the KXM Runtime supervisor if needed, then create an immutable run offline: pins `homeRuntimeId` plus config/executor/tool policy revisions and stores only the prompt hash. `--dry-run` prints the plan without creating anything |

package/docs/test-matrix.md

@@ -13,6 +13,7 @@ npm run verify
 
 | Feature | Automated evidence |
 |---|---|
+| Portal tenant read composes two labelled authorities: hub runs carry `hub-projection`, Runtime runs carry `runtime-authoritative`; a down hub leaves runtime state readable and vice versa with stable reasons; projection/authoritative disagreements surface as `discrepancies`; binding scope is labelled loopback/remote | `test/core/studio-layout.test.ts` |
 | Structured-result settlement only: outcome words in prose, empty replies, and outcomes outside the step's declared set all fail closed; a declared JSON object and a JSON result block inside prose both settle, and the engine records `outcome_unknown` and terminates `failed` | `test/core/pi-producer.test.ts`, `test/core/engine.test.ts` |
 | Health, readiness, metrics, request IDs, security headers | `test/core/hub-api.test.ts` |
 | Shared and per-project authentication, project isolation | `test/core/hub-api.test.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.55",
+  "version": "0.7.57",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.55",
+  "version": "0.7.57",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -19678,6 +19678,11 @@ function resolveClientHubAuthToken(env, project) {
   const record = readHubEnvRecord(env);
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || void 0;
 }
+function resolveClientAdminAuthToken(env = process.env) {
+  const envToken = env.KXM_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  return readHubEnvRecord(env)?.authToken?.trim() || void 0;
+}
 
 // plugins/kxm/src/project-name.ts
 import { readFileSync as readFileSync3 } from "node:fs";
@@ -25725,6 +25730,15 @@ async function probeSupervisor(port, expectedRuntimeId, token, timeoutMs = 750)
 function hashKxmTokenProof(token, nonce) {
   return createHmac("sha256", token).update(`kxm-runtime-token-proof\0${nonce}`, "utf8").digest("hex");
 }
+async function attachKxmSupervisor(options = {}) {
+  const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
+  const status = kxmSupervisorStatus(paths);
+  if (!status.running || !status.port || !status.runtimeId) return void 0;
+  const token = readKxmSupervisorToken(paths);
+  if (!token) return void 0;
+  if (!await probeSupervisor(status.port, status.runtimeId, token)) return void 0;
+  return { runtimeId: status.runtimeId, port: status.port, token, started: false };
+}
 async function ensureKxmSupervisor(options = {}) {
   const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
   const status = kxmSupervisorStatus(paths);
@@ -31761,6 +31775,176 @@ function initializeKxmProject(start = process.cwd(), options = {}) {
   return withKxmLocalBindingLock(gitRoot, storeOptions, (lock) => initializeKxmProjectAtGitRoot(start, gitRoot, options, lock));
 }
 
+// plugins/kxm/src/tenant-status.ts
+var TENANT_STATUS_SCHEMA = "kxm.tenant-status.v1";
+var DEFAULT_HUB_TIMEOUT_MS = 5e3;
+function hubSourceReason(status) {
+  if (status === 401 || status === 403) return "hub_unauthorized";
+  if (status === 404) return "hub_not_found";
+  return `hub_http_${status}`;
+}
+function asString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function assembleTenantStatus(input) {
+  const now = input.now ?? (() => /* @__PURE__ */ new Date());
+  const base = input.hubUrl.replace(/\/$/, "");
+  const at = () => now().toISOString();
+  const readHub = async () => {
+    const attemptedAt = at();
+    let token;
+    try {
+      token = input.resolveAdminToken();
+    } catch (error) {
+      void error;
+      return { state: "unavailable", observedAt: attemptedAt, reason: "hub_credential_unreadable" };
+    }
+    try {
+      const response = await input.fetchImpl(`${base}/v1/ops/snapshot?project=${encodeURIComponent(input.project)}`, {
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(input.hubTimeoutMs ?? DEFAULT_HUB_TIMEOUT_MS)
+      });
+      if (!response.ok) {
+        return { state: "unavailable", observedAt: attemptedAt, reason: hubSourceReason(response.status) };
+      }
+      let body;
+      try {
+        body = await response.json();
+      } catch (error) {
+        const name = error instanceof Error ? error.name : void 0;
+        if (name === "TimeoutError" || name === "AbortError") {
+          return { state: "unavailable", observedAt: attemptedAt, reason: "hub_timeout" };
+        }
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_response_invalid" };
+      }
+      if (!isObject(body) || typeof body.project !== "string" || typeof body.fetchedAt !== "string" || !Array.isArray(body.agents) || !Array.isArray(body.runs) || !Array.isArray(body.plans ?? []) || typeof body.openMessageTotal !== "number" || typeof body.runTotal !== "number") {
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_response_invalid" };
+      }
+      if (body.project !== input.project) {
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_project_mismatch" };
+      }
+      const runRows = body.runs.filter(isObject);
+      const value = {
+        project: body.project,
+        fetchedAt: body.fetchedAt,
+        agents: body.agents.filter(isObject).map((agent) => ({
+          id: asString(agent.id) ?? "",
+          name: asString(agent.name) ?? "",
+          online: agent.online === true
+        })),
+        openMessageTotal: body.openMessageTotal,
+        runTotal: body.runTotal,
+        runs: runRows.map((run) => {
+          const stages = Array.isArray(run.stages) ? run.stages.filter(isObject).map((stage) => ({
+            id: asString(stage.id) ?? "",
+            status: asString(stage.status) ?? "unknown",
+            ...typeof stage.attempts === "number" ? { attempts: stage.attempts } : {}
+          })) : void 0;
+          const done = stages?.filter((stage) => stage.status === "passed" || stage.status === "failed" || stage.status === "warning").length;
+          return {
+            id: asString(run.id) ?? "",
+            status: asString(run.status) ?? "unknown",
+            definitionId: asString(run.definitionId) ?? "",
+            ...asString(run.currentStage) ? { currentStage: asString(run.currentStage) } : {},
+            ...asString(run.targetAgentName) ? { targetAgentName: asString(run.targetAgentName) } : {},
+            ...asString(run.updatedAt) ? { updatedAt: asString(run.updatedAt) } : {},
+            ...stages !== void 0 ? { progress: { done: done ?? 0, total: stages.length }, stages } : {},
+            source: "hub-projection"
+          };
+        }),
+        plans: (Array.isArray(body.plans) ? body.plans : []).filter(isObject).map((plan) => ({
+          id: asString(plan.id) ?? "",
+          runId: asString(plan.runId) ?? "",
+          summary: asString(plan.summary) ?? "",
+          createdAt: asString(plan.createdAt) ?? "",
+          ...asString(plan.stageId) ? { stageId: asString(plan.stageId) } : {},
+          ...asString(plan.severity) ? { severity: asString(plan.severity) } : {}
+        }))
+      };
+      return { state: "ok", observedAt: attemptedAt, value };
+    } catch (error) {
+      const name = error instanceof Error ? error.name : void 0;
+      if (name === "TimeoutError" || name === "AbortError") {
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_timeout" };
+      }
+      return { state: "unavailable", observedAt: attemptedAt, reason: "hub_unreachable" };
+    }
+  };
+  const readRuntime = async () => {
+    const attemptedAt = at();
+    try {
+      const runs = await input.runtime.listRuns();
+      return { state: "ok", observedAt: attemptedAt, value: { runs } };
+    } catch (error) {
+      const code = error instanceof Error && "issues" in error && Array.isArray(error.issues) && typeof error.issues[0]?.code === "string" ? error.issues[0].code : void 0;
+      return { state: "unavailable", observedAt: attemptedAt, reason: code ?? "runtime_unavailable" };
+    }
+  };
+  const [hub, runtime] = await Promise.all([readHub(), readRuntime()]);
+  let runComparison;
+  if (!hub.value || !runtime.value) {
+    runComparison = {
+      state: "unavailable",
+      reason: !hub.value ? `hub_${hub.reason ?? "unavailable"}` : `runtime_${runtime.reason ?? "unavailable"}`
+    };
+  } else {
+    const authoritative = new Map(
+      runtime.value.runs.filter((run) => run.projectionError === void 0).map((run) => [run.runId, run.status])
+    );
+    const hubIds = new Set(hub.value.runs.map((run) => run.id));
+    const foldFailed = runtime.value.runs.filter((run) => run.projectionError !== void 0 && hubIds.has(run.runId));
+    const discrepancies = [];
+    let matched = 0;
+    for (const projected of hub.value.runs) {
+      const runtimeStatus = authoritative.get(projected.id);
+      if (runtimeStatus === void 0) continue;
+      matched += 1;
+      if (runtimeStatus !== projected.status) {
+        discrepancies.push({ runId: projected.id, hubStatus: projected.status, runtimeStatus });
+      }
+    }
+    if (matched > 0) {
+      runComparison = {
+        state: "compared",
+        matched,
+        ...foldFailed.length > 0 ? { unverifiedFoldRuns: foldFailed.length } : {},
+        ...discrepancies.length > 0 ? { discrepancies } : {}
+      };
+    } else {
+      runComparison = foldFailed.length > 0 ? { state: "unverified", reason: "runtime_fold_failed", matched: 0, unverifiedFoldRuns: foldFailed.length } : { state: "unverified", reason: "run_identity_link_absent", matched: 0 };
+    }
+  }
+  return {
+    schema: TENANT_STATUS_SCHEMA,
+    project: input.project,
+    generatedAt: at(),
+    hubUrl: input.hubUrl,
+    bindingScope: hubBindingScope(input.hubUrl),
+    hub,
+    runtime,
+    runComparison,
+    degraded: hub.state !== "ok" || runtime.state !== "ok"
+  };
+}
+function formatTenantStatus(payload) {
+  const hubLine = payload.hub.state === "ok" && payload.hub.value ? `hub ${payload.hub.value.agents.filter((agent) => agent.online).length}/${payload.hub.value.agents.length} agents online, ${payload.hub.value.runs.length} hub runs, ${payload.hub.value.openMessageTotal} open messages` : `hub unavailable (${payload.hub.reason ?? "unknown"})`;
+  const runtimeLine = payload.runtime.state === "ok" && payload.runtime.value ? (() => {
+    const cached = payload.runtime.value.runs.filter((run) => run.projectionError !== void 0).length;
+    const authoritative = payload.runtime.value.runs.length - cached;
+    return `runtime ${authoritative} runs (authoritative, on this box)${cached > 0 ? `, ${cached} cached (fold failed, not state)` : ""}`;
+  })() : `runtime unavailable (${payload.runtime.reason ?? "unknown"})`;
+  const comparisonLine = payload.runComparison.state === "compared" ? payload.runComparison.discrepancies && payload.runComparison.discrepancies.length > 0 ? `cross-check: ${payload.runComparison.discrepancies.length} of ${payload.runComparison.matched} matched run(s) disagree${payload.runComparison.unverifiedFoldRuns ? ` (${payload.runComparison.unverifiedFoldRuns} unverified: fold failed)` : ""}` : `cross-check: ${payload.runComparison.matched} matched run(s) agree${payload.runComparison.unverifiedFoldRuns ? ` (${payload.runComparison.unverifiedFoldRuns} unverified: fold failed)` : ""}` : payload.runComparison.state === "unverified" ? payload.runComparison.reason === "runtime_fold_failed" ? `cross-check: unavailable \u2014 ${payload.runComparison.unverifiedFoldRuns ?? 0} shared run(s) could not be verified (runtime fold failed)` : "cross-check: unavailable \u2014 no run id appears in both sources (independent id spaces)" : `cross-check: unavailable (${payload.runComparison.reason ?? "unknown"})`;
+  return [
+    `tenant ${payload.project} @ ${payload.hubUrl} (${payload.bindingScope})`,
+    hubLine,
+    runtimeLine,
+    comparisonLine
+  ].join("\n");
+}
+
 // plugins/kxm/src/cli/project.ts
 var kxmDriveCliSeams = {};
 function initPlanPayload(plan) {
@@ -32236,7 +32420,7 @@ async function cmdKxmRunList(runtime) {
       runtime.io,
       runtime.json,
       { ok: true, command: "runs list", runs },
-      runs.length === 0 ? "no runs" : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}`).join("\n")
+      runs.length === 0 ? "no runs" : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}${run.projectionError ? `  [state unverified: ${run.projectionError}]` : ""}`).join("\n")
     );
     return 0;
   } catch (error) {
@@ -32248,6 +32432,67 @@ async function cmdKxmRunList(runtime) {
     return 1;
   }
 }
+async function cmdTenantStatus(runtime) {
+  let projectRoot;
+  let projectId;
+  try {
+    projectRoot = discoverKxmProjectRoot(runtime.cwd) ?? void 0;
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "project_required" }, "kxm tenant status requires a KXM project (run kxm init first)");
+      return 1;
+    }
+    const bundle = loadKxmProject(projectRoot, {});
+    projectId = String(bundle.project.value.id);
+    const root = projectRoot;
+    const payload = await assembleTenantStatus({
+      project: projectId,
+      hubUrl: runtime.serverUrl,
+      // Admin-scoped route: resolve the admin credential only (a project token would 401),
+      // and resolve it inside the hub source so a malformed persisted record degrades that
+      // one source instead of aborting the Runtime read with it.
+      resolveAdminToken: () => resolveClientAdminAuthToken(runtime.env),
+      fetchImpl: runtime.fetchImpl,
+      runtime: {
+        listRuns: async () => {
+          const handle = await attachKxmSupervisor({ env: runtime.env });
+          if (!handle) {
+            throw runtimeError("runtime_supervisor_not_running", "runtime", "no live runtime supervisor on this box");
+          }
+          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
+          const runs = result.runs ?? [];
+          return runs.map((run) => ({
+            runId: String(run.runId ?? ""),
+            status: String(run.status ?? "unknown"),
+            homeRuntimeId: String(run.homeRuntimeId ?? ""),
+            ...typeof run.workflowId === "string" ? { workflowId: run.workflowId } : {},
+            ...typeof run.createdAt === "string" ? { createdAt: run.createdAt } : {},
+            ...typeof run.updatedAt === "string" ? { updatedAt: run.updatedAt } : {},
+            ...typeof run.projectionError === "string" ? { projectionError: run.projectionError } : {},
+            source: typeof run.projectionError === "string" ? "runtime-cached" : "runtime-authoritative"
+          }));
+        }
+      }
+    });
+    if (payload.hub.state !== "ok" && payload.runtime.state !== "ok") {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "tenant status", error: "tenant_status_no_source", payload },
+        `neither source could be read: hub ${payload.hub.reason ?? "unknown"}, runtime ${payload.runtime.reason ?? "unknown"}`
+      );
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: true, command: "tenant status", ...payload }, formatTenantStatus(payload));
+    return 0;
+  } catch (error) {
+    if (error instanceof KxmConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_failed", issues: error.issues }, `tenant status failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_io_failed" }, "tenant status failed because a local operation did not complete");
+    return 1;
+  }
+}
 async function cmdHarnessList(runtime) {
   const inventory = await probeHarnessesAsync({ env: runtime.env });
   print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));
@@ -45628,6 +45873,7 @@ var TOP_LEVEL_COMMANDS = [
   "restore",
   "run",
   "runs",
+  "tenant",
   "harness",
   "update",
   "runtime",
@@ -45656,6 +45902,7 @@ var TOP_LEVEL_COMMANDS = [
 ];
 var SUBCOMMANDS = {
   runs: ["status", "cancel", "list"],
+  tenant: ["status"],
   harness: ["list"],
   runtime: ["start", "status", "stop"],
   trust: ["diff", "check"],
@@ -47372,6 +47619,11 @@ function createProgram(ctx, result) {
   addGlobalOptions(runCmd.command("list").description("List recent runs for the current project")).action(async function runListAction() {
     result.code = await cmdKxmRunList(runtimeFrom(ctx, this));
   });
+  const tenantCmd = addGlobalOptions(program2.command("tenant").description("Composed tenant reads for machine clients (portal)"));
+  tenantCmd.helpCommand("help", "Show tenant help");
+  addGlobalOptions(tenantCmd.command("status").description("Read hub metadata and authoritative Runtime run state as one labeled view")).action(async function tenantStatusAction() {
+    result.code = await cmdTenantStatus(runtimeFrom(ctx, this));
+  });
   const modelsCmd = addGlobalOptions(program2.command("models").description("Manage model catalogs, roles, and route state"));
   modelsCmd.action(async function modelsScreenAction() {
     result.code = await cmdModelsScreen(runtimeFrom(ctx, this));

package/plugins/kxm/dist/mcp-server.js

@@ -17121,7 +17121,7 @@ async function deliverInboxNotification(messageId, delivered, notify) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.55";
+var VERSION = "0.7.57";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();
 var meshClient;

package/plugins/kxm/dist/runtime-supervisor.js

@@ -26837,6 +26837,15 @@ async function probeSupervisor(port, expectedRuntimeId, token, timeoutMs = 750)
 function hashKxmTokenProof(token, nonce) {
   return createHmac("sha256", token).update(`kxm-runtime-token-proof\0${nonce}`, "utf8").digest("hex");
 }
+async function attachKxmSupervisor(options = {}) {
+  const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
+  const status = kxmSupervisorStatus(paths);
+  if (!status.running || !status.port || !status.runtimeId) return void 0;
+  const token = readKxmSupervisorToken(paths);
+  if (!token) return void 0;
+  if (!await probeSupervisor(status.port, status.runtimeId, token)) return void 0;
+  return { runtimeId: status.runtimeId, port: status.port, token, started: false };
+}
 async function ensureKxmSupervisor(options = {}) {
   const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
   const status = kxmSupervisorStatus(paths);
@@ -27246,7 +27255,16 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now) {
             sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: `project ${requestedProjectId} is not the bound project ${context.projectId}` });
             return;
           }
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50);
+          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+            try {
+              return projectKxmRunReadOnly(context, stored.runId);
+            } catch (error) {
+              return {
+                ...stored,
+                projectionError: error instanceof KxmConfigError ? error.issues[0]?.code ?? "runtime_projection_failed" : "runtime_projection_failed"
+              };
+            }
+          });
           sendJson(response, 200, { ok: true, runs });
           return;
         }
@@ -27379,6 +27397,7 @@ async function kxmRuntimeRequest(handle, method, path, body) {
 export {
   DEFAULT_RUNTIME_STOP_GRACE_MS,
   MAX_RUNTIME_STOP_GRACE_MS,
+  attachKxmSupervisor,
   ensureKxmSupervisor,
   hashKxmSupervisorToken,
   hashKxmTokenProof,

package/plugins/kxm/dist/runtime.js

@@ -27349,6 +27349,15 @@ async function probeSupervisor(port, expectedRuntimeId, token, timeoutMs = 750)
 function hashKxmTokenProof(token, nonce) {
   return createHmac("sha256", token).update(`kxm-runtime-token-proof\0${nonce}`, "utf8").digest("hex");
 }
+async function attachKxmSupervisor(options = {}) {
+  const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
+  const status = kxmSupervisorStatus(paths);
+  if (!status.running || !status.port || !status.runtimeId) return void 0;
+  const token = readKxmSupervisorToken(paths);
+  if (!token) return void 0;
+  if (!await probeSupervisor(status.port, status.runtimeId, token)) return void 0;
+  return { runtimeId: status.runtimeId, port: status.port, token, started: false };
+}
 async function ensureKxmSupervisor(options = {}) {
   const paths = kxmRuntimePaths(options.stateRoot !== void 0 ? { stateRoot: options.stateRoot } : { ...options.env ? { env: options.env } : {} });
   const status = kxmSupervisorStatus(paths);
@@ -27758,7 +27767,16 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now) {
             sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: `project ${requestedProjectId} is not the bound project ${context.projectId}` });
             return;
           }
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50);
+          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+            try {
+              return projectKxmRunReadOnly(context, stored.runId);
+            } catch (error) {
+              return {
+                ...stored,
+                projectionError: error instanceof KxmConfigError ? error.issues[0]?.code ?? "runtime_projection_failed" : "runtime_projection_failed"
+              };
+            }
+          });
           sendJson(response, 200, { ok: true, runs });
           return;
         }
@@ -30227,6 +30245,7 @@ export {
   acceptKxmRun,
   assertClosedGateObservation,
   assertKxmConfigError,
+  attachKxmSupervisor,
   backupDatabaseFile,
   buildImprovementReport,
   buildSshArgs,

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.55",
+  "version": "0.7.57",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/autocomplete.ts

@@ -6,6 +6,7 @@ const TOP_LEVEL_COMMANDS = [
   "restore",
   "run",
   "runs",
+  "tenant",
   "harness",
   "update",
   "runtime",
@@ -35,6 +36,7 @@ const TOP_LEVEL_COMMANDS = [
 
 const SUBCOMMANDS: Record<string, string[]> = {
   runs: ["status", "cancel", "list"],
+  tenant: ["status"],
   harness: ["list"],
   runtime: ["start", "status", "stop"],
   trust: ["diff", "check"],

package/plugins/kxm/src/cli/project.ts

@@ -16,11 +16,14 @@ import { diffKxmProjectAgainstRevision, formatKxmPermissionDiff } from "../permi
 import { readKxmLocalBindings, kxmUserStateRoot } from "../bindings.ts";
 import { loadKxmProject } from "../project-config.ts";
 import {
+  attachKxmSupervisor,
   ensureKxmSupervisor,
   kxmRuntimeRequest,
   kxmSupervisorStatus,
 } from "../runtime-supervisor.ts";
-import { kxmRuntimePaths } from "../runtime-store.ts";
+import { kxmRuntimePaths, runtimeError } from "../runtime-store.ts";
+import { assembleTenantStatus, formatTenantStatus } from "../tenant-status.ts";
+import { resolveClientAdminAuthToken } from "../hub-env.ts";
 import {
   formatHarnessInventory,
   probeHarnessesAsync,
@@ -568,12 +571,14 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
     const projectId = String(bundle.project.value.id);
     const supervisor = await ensureKxmSupervisor({ env: runtime.env });
     const result = await kxmRuntimeRequest(supervisor, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(projectRoot)}`);
-    const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string }>;
+    const runs = (result.runs ?? []) as Array<{ runId: string; status: string; workflowId: string; createdAt: string; projectionError?: string }>;
     print(
       runtime.io,
       runtime.json,
       { ok: true, command: "runs list", runs },
-      runs.length === 0 ? "no runs" : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}`).join("\n"),
+      runs.length === 0
+        ? "no runs"
+        : runs.map((run) => `${run.runId}  ${run.status}  ${run.workflowId}  ${run.createdAt}${run.projectionError ? `  [state unverified: ${run.projectionError}]` : ""}`).join("\n"),
     );
     return 0;
   } catch (error) {
@@ -586,6 +591,72 @@ export async function cmdKxmRunList(runtime: Runtime): Promise<number> {
   }
 }
 
+export async function cmdTenantStatus(runtime: Runtime): Promise<number> {
+  let projectRoot: string | undefined;
+  let projectId: string;
+  try {
+    projectRoot = discoverKxmProjectRoot(runtime.cwd) ?? undefined;
+    if (!projectRoot) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "project_required" }, "kxm tenant status requires a KXM project (run kxm init first)");
+      return 1;
+    }
+    const bundle = loadKxmProject(projectRoot, {});
+    projectId = String(bundle.project.value.id);
+    const root = projectRoot;
+
+    const payload = await assembleTenantStatus({
+      project: projectId,
+      hubUrl: runtime.serverUrl,
+      // Admin-scoped route: resolve the admin credential only (a project token would 401),
+      // and resolve it inside the hub source so a malformed persisted record degrades that
+      // one source instead of aborting the Runtime read with it.
+      resolveAdminToken: () => resolveClientAdminAuthToken(runtime.env),
+      fetchImpl: runtime.fetchImpl,
+      runtime: {
+        listRuns: async () => {
+          // Attach only: a status read must never conjure a supervisor. "Nothing is
+          // running" is an answer the portal can render, not a condition to repair.
+          const handle = await attachKxmSupervisor({ env: runtime.env });
+          if (!handle) {
+            throw runtimeError("runtime_supervisor_not_running", "runtime", "no live runtime supervisor on this box");
+          }
+          const result = await kxmRuntimeRequest(handle, "GET", `/v1/projects/${encodeURIComponent(projectId)}/runs?projectRoot=${encodeURIComponent(root)}`);
+          const runs = (result.runs ?? []) as Array<Record<string, unknown>>;
+          return runs.map((run) => ({
+            runId: String(run.runId ?? ""),
+            status: String(run.status ?? "unknown"),
+            homeRuntimeId: String(run.homeRuntimeId ?? ""),
+            ...(typeof run.workflowId === "string" ? { workflowId: run.workflowId } : {}),
+            ...(typeof run.createdAt === "string" ? { createdAt: run.createdAt } : {}),
+            ...(typeof run.updatedAt === "string" ? { updatedAt: run.updatedAt } : {}),
+            ...(typeof run.projectionError === "string" ? { projectionError: run.projectionError } : {}),
+            source: (typeof run.projectionError === "string" ? "runtime-cached" : "runtime-authoritative") as "runtime-cached" | "runtime-authoritative",
+          }));
+        },
+      },
+    });
+
+    if (payload.hub.state !== "ok" && payload.runtime.state !== "ok") {
+      print(
+        runtime.io,
+        runtime.json,
+        { ok: false, command: "tenant status", error: "tenant_status_no_source", payload },
+        `neither source could be read: hub ${payload.hub.reason ?? "unknown"}, runtime ${payload.runtime.reason ?? "unknown"}`,
+      );
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: true, command: "tenant status", ...payload }, formatTenantStatus(payload));
+    return 0;
+  } catch (error) {
+    if (error instanceof KxmConfigError) {
+      print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_failed", issues: error.issues }, `tenant status failed: ${error.message}`);
+      return 1;
+    }
+    print(runtime.io, runtime.json, { ok: false, command: "tenant status", error: "tenant_status_io_failed" }, "tenant status failed because a local operation did not complete");
+    return 1;
+  }
+}
+
 export async function cmdHarnessList(runtime: Runtime): Promise<number> {
   const inventory = await probeHarnessesAsync({ env: runtime.env });
   print(runtime.io, runtime.json, { ok: true, command: "harness list", ...inventory }, formatHarnessInventory(inventory));

package/plugins/kxm/src/cli.ts

@@ -107,6 +107,7 @@ cmdBackup,
   cmdKxmRunReceipt,
   cmdKxmRunCancel,
   cmdKxmRunList,
+  cmdTenantStatus,
   cmdHarnessList,
   cmdRouteChange,
   cmdModelsScreen,
@@ -395,6 +396,13 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdKxmRunList(runtimeFrom(ctx, this));
     });
 
+  const tenantCmd = addGlobalOptions(program.command("tenant").description("Composed tenant reads for machine clients (portal)"));
+  tenantCmd.helpCommand("help", "Show tenant help");
+  addGlobalOptions(tenantCmd.command("status").description("Read hub metadata and authoritative Runtime run state as one labeled view"))
+    .action(async function tenantStatusAction(this: Command) {
+      result.code = await cmdTenantStatus(runtimeFrom(ctx, this));
+    });
+
   const modelsCmd = addGlobalOptions(program.command("models").description("Manage model catalogs, roles, and route state"));
   modelsCmd.action(async function modelsScreenAction(this: Command) { result.code = await cmdModelsScreen(runtimeFrom(ctx, this)); });
   modelsCmd.helpCommand("help", "Show models help");

package/plugins/kxm/src/hub-env.ts

@@ -234,3 +234,16 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
   const record = readHubEnvRecord(env);
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || undefined;
 }
+
+/**
+ * Admin-scoped hub reads (`/v1/ops/snapshot`, …) are rejected with 401 by a project token,
+ * so this variant resolves the admin credential only: explicit `KXM_AUTH_TOKEN`, else the
+ * persisted record's admin token. It never falls back to a project token the route would
+ * refuse — handing the portal a 401 dressed as "configured" is worse than handing it none.
+ * Throws on a malformed persisted record, same as `resolveClientHubAuthToken`.
+ */
+export function resolveClientAdminAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const envToken = env.KXM_AUTH_TOKEN?.trim();
+  if (envToken) return envToken;
+  return readHubEnvRecord(env)?.authToken?.trim() || undefined;
+}

package/plugins/kxm/src/mcp-server.ts

@@ -8,7 +8,7 @@ import { AGENT_COMMANDS_MAP, enforceToolPolicy, getMcpTools, reconcileInbox } fr
 import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 
-const VERSION = "0.7.55";
+const VERSION = "0.7.57";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();
 let meshClient: HubClient | undefined;

package/plugins/kxm/src/runtime-supervisor.ts

@@ -179,6 +179,28 @@ export interface KxmSupervisorHandle {
   started: boolean;
 }
 
+/**
+ * Attach to a live supervisor, or return `undefined`. Never starts one.
+ *
+ * `ensureKxmSupervisor` is for operators: an absent supervisor is a problem to fix, so it
+ * spawns. A poller — the portal tenant read, a status screen — has the opposite contract:
+ * polling must not conjure a daemon, and "nothing is running" is an answer to report, not
+ * a condition to repair. Returns `undefined` for every not-running shape: no claim, a
+ * supervisor registered but dead, a missing token file, or a probe that fails the
+ * token-proof challenge.
+ */
+export async function attachKxmSupervisor(
+  options: { stateRoot?: string; env?: NodeJS.ProcessEnv } = {},
+): Promise<KxmSupervisorHandle | undefined> {
+  const paths = kxmRuntimePaths(options.stateRoot !== undefined ? { stateRoot: options.stateRoot } : { ...(options.env ? { env: options.env } : {}) });
+  const status = kxmSupervisorStatus(paths);
+  if (!status.running || !status.port || !status.runtimeId) return undefined;
+  const token = readKxmSupervisorToken(paths);
+  if (!token) return undefined;
+  if (!(await probeSupervisor(status.port, status.runtimeId, token))) return undefined;
+  return { runtimeId: status.runtimeId, port: status.port, token, started: false };
+}
+
 /** Ensure a supervisor is running: reuse a live one, otherwise auto-start. */
 export async function ensureKxmSupervisor(
   options: { stateRoot?: string; env?: NodeJS.ProcessEnv; spawnImpl?: (scriptPath: string, env: NodeJS.ProcessEnv) => number } = {},
@@ -658,7 +680,25 @@ async function startKxmRuntimeSupervisorInner(
             sendJson(response, 400, { ok: false, error: "runtime_request_invalid", message: `project ${requestedProjectId} is not the bound project ${context.projectId}` });
             return;
           }
-          const runs = context.eventStore.runsForProject(requestedProjectId, 50);
+          // The stored `runs` row is a cache, not the state: per-run reads fold the event
+          // log (`projectKxmRunReadOnly`) precisely because the row can be stale. A listing
+          // that returned raw rows would let every consumer — including the portal's
+          // tenant read — present cached status as authoritative. Folding replays each
+          // run's events; workflows are transition-bounded, so this stays cheap at the
+          // 50-run cap. A run that refuses to fold is returned with its cached row plus
+          // `projectionError`, so one corrupt run cannot make the listing lie by omission.
+          const runs = context.eventStore.runsForProject(requestedProjectId, 50).map((stored) => {
+            try {
+              return projectKxmRunReadOnly(context, stored.runId);
+            } catch (error) {
+              return {
+                ...stored,
+                projectionError: error instanceof KxmConfigError
+                  ? (error.issues[0]?.code ?? "runtime_projection_failed")
+                  : "runtime_projection_failed",
+              };
+            }
+          });
           sendJson(response, 200, { ok: true, runs });
           return;
         }

package/plugins/kxm/src/tenant-status.ts

@@ -0,0 +1,371 @@
+import { hubBindingScope } from "./hub-binding.ts";
+
+export const TENANT_STATUS_SCHEMA = "kxm.tenant-status.v1" as const;
+
+/**
+ * One upstream of the tenant view, with its own reachability. A source that could not be
+ * read is reported as `unavailable` with a stable reason — never silently filled from the
+ * other source, because the two sources answer different questions: the hub holds
+ * *metadata* (agent roster, message queue, its own workflow runs), the Runtime holds the
+ * *authoritative* run state on the box that owns the run. Blurring them is how a portal
+ * ends up rendering one as the other.
+ */
+export type TenantSourceState = "ok" | "unavailable";
+
+export interface TenantSource<T> {
+  state: TenantSourceState;
+  /** When this source was read (or attempted), so a consumer can age the data itself. */
+  observedAt: string;
+  /** Stable machine code (`hub_unreachable`, `hub_timeout`, `runtime_supervisor_not_running`, …). */
+  reason?: string;
+  value?: T;
+}
+
+/** Hub-side roster entry: presence and liveness, per the hub's own observation. */
+export interface TenantHubAgent {
+  id: string;
+  name: string;
+  online: boolean;
+}
+
+export interface TenantHubStage {
+  id: string;
+  status: string;
+  attempts?: number | undefined;
+}
+
+/**
+ * A run as the hub records it. The hub mints its own run ids at workflow start; this is a
+ * hub workflow run — metadata about work, not the Runtime's state for it.
+ */
+export interface TenantHubRun {
+  id: string;
+  status: string;
+  definitionId: string;
+  currentStage?: string | undefined;
+  targetAgentName?: string | undefined;
+  updatedAt?: string | undefined;
+  progress?: { done: number; total: number };
+  stages?: TenantHubStage[];
+  source: "hub-projection";
+}
+
+export interface TenantHubPlan {
+  id: string;
+  runId: string;
+  summary: string;
+  createdAt: string;
+  stageId?: string | undefined;
+  severity?: string | undefined;
+}
+
+export interface TenantHubValue {
+  project: string;
+  fetchedAt: string;
+  agents: TenantHubAgent[];
+  openMessageTotal: number;
+  runTotal: number;
+  runs: TenantHubRun[];
+  plans: TenantHubPlan[];
+}
+
+/** A run as the Runtime that owns it records it. This is the authoritative state. */
+export interface TenantRuntimeRun {
+  runId: string;
+  status: string;
+  homeRuntimeId: string;
+  workflowId?: string | undefined;
+  createdAt?: string | undefined;
+  updatedAt?: string | undefined;
+  /** Set when the stored row exists but the event-log fold refused; `status` is then the
+   * cached row, and a consumer must not present it as folded state. */
+  projectionError?: string | undefined;
+  /** `runtime-cached` exactly when `projectionError` is set: the row is the cache, not the
+   * folded state, and neither the label nor the cross-check may treat it as authoritative. */
+  source: "runtime-authoritative" | "runtime-cached";
+}
+
+export interface TenantRuntimeValue {
+  runs: TenantRuntimeRun[];
+}
+
+export interface TenantRunDiscrepancy {
+  runId: string;
+  hubStatus: string;
+  runtimeStatus: string;
+}
+
+/**
+ * Cross-check between the two run populations. Hub runs and Runtime runs mint their ids
+ * independently (`newId("run")` on each side), so an id appearing in both means a hub run
+ * that this box drove — and only then is a status comparison meaningful. With no overlap
+ * the comparison is **unverified, not agreed**: "no matching ids" says the populations did
+ * not intersect, nothing more, and reporting agreement there would fabricate a green light
+ * out of an empty set.
+ */
+export interface TenantRunComparison {
+  state: "compared" | "unverified" | "unavailable";
+  reason?: string;
+  matched?: number;
+  /** Shared ids whose Runtime row failed to fold: present in both stores, but the
+   * authoritative side could not be read, so those runs are unverified rather than agreed. */
+  unverifiedFoldRuns?: number;
+  discrepancies?: TenantRunDiscrepancy[];
+}
+
+export interface TenantStatusPayload {
+  schema: typeof TENANT_STATUS_SCHEMA;
+  project: string;
+  generatedAt: string;
+  hubUrl: string;
+  /** Reuses the `kxm hub bind` classification: `loopback` and `remote` ship different rules. */
+  bindingScope: "loopback" | "remote";
+  hub: TenantSource<TenantHubValue>;
+  runtime: TenantSource<TenantRuntimeValue>;
+  runComparison: TenantRunComparison;
+  /** True when any source is unavailable. Assembling a payload is not the same as seeing. */
+  degraded: boolean;
+}
+
+export interface TenantStatusRuntimeReader {
+  listRuns(): Promise<TenantRuntimeRun[]>;
+}
+
+const DEFAULT_HUB_TIMEOUT_MS = 5_000;
+
+function hubSourceReason(status: number): string {
+  if (status === 401 || status === 403) return "hub_unauthorized";
+  if (status === 404) return "hub_not_found";
+  return `hub_http_${status}`;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Compose the tenant view from the two authorities that actually hold the data.
+ *
+ * Both sources are read **concurrently and independently**: a hub that hangs to its
+ * deadline cannot delay or suppress the Runtime half of the view, and a Runtime that is
+ * not running cannot take the hub metadata down with it. The hub is read over HTTP
+ * (`/v1/ops/snapshot`, admin credential); the Runtime is read through an injected reader
+ * so this function stays pure and testable — the CLI passes a reader that attaches to the
+ * live supervisor, and a test passes whatever it likes.
+ */
+export async function assembleTenantStatus(input: {
+  project: string;
+  hubUrl: string;
+  /** Resolves the admin credential. May throw on a malformed persisted record; that
+   * failure belongs to the hub source alone and never aborts the Runtime read. */
+  resolveAdminToken: () => string | undefined;
+  fetchImpl: typeof fetch;
+  runtime: TenantStatusRuntimeReader;
+  hubTimeoutMs?: number | undefined;
+  now?: () => Date;
+}): Promise<TenantStatusPayload> {
+  const now = input.now ?? ((): Date => new Date());
+  const base = input.hubUrl.replace(/\/$/, "");
+  const at = (): string => now().toISOString();
+
+  const readHub = async (): Promise<TenantSource<TenantHubValue>> => {
+    const attemptedAt = at();
+    let token: string | undefined;
+    try {
+      token = input.resolveAdminToken();
+    } catch (error) {
+      // A malformed hub-env record is a configuration failure with a specific repair.
+      // It belongs to this source; the Runtime read proceeds regardless.
+      void error;
+      return { state: "unavailable", observedAt: attemptedAt, reason: "hub_credential_unreadable" };
+    }
+    try {
+      const response = await input.fetchImpl(`${base}/v1/ops/snapshot?project=${encodeURIComponent(input.project)}`, {
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(input.hubTimeoutMs ?? DEFAULT_HUB_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        return { state: "unavailable", observedAt: attemptedAt, reason: hubSourceReason(response.status) };
+      }
+      let body: unknown;
+      try {
+        body = await response.json();
+      } catch (error) {
+        // A deadline can expire mid-body; that is a timeout, not malformed content, and
+        // classifying it as `hub_response_invalid` would hide the one fact that matters.
+        const name = error instanceof Error ? error.name : undefined;
+        if (name === "TimeoutError" || name === "AbortError") {
+          return { state: "unavailable", observedAt: attemptedAt, reason: "hub_timeout" };
+        }
+        // Reachable but not a JSON document: a different failure than a dead socket.
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_response_invalid" };
+      }
+      if (!isObject(body)
+        || typeof body.project !== "string"
+        || typeof body.fetchedAt !== "string"
+        || !Array.isArray(body.agents)
+        || !Array.isArray(body.runs)
+        || !Array.isArray(body.plans ?? [])
+        || typeof body.openMessageTotal !== "number"
+        || typeof body.runTotal !== "number") {
+        // A 200 with an unusable body must not become a healthy empty snapshot.
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_response_invalid" };
+      }
+      if (body.project !== input.project) {
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_project_mismatch" };
+      }
+      const runRows = body.runs.filter(isObject);
+      const value: TenantHubValue = {
+        project: body.project,
+        fetchedAt: body.fetchedAt,
+        agents: body.agents.filter(isObject).map((agent) => ({
+          id: asString(agent.id) ?? "",
+          name: asString(agent.name) ?? "",
+          online: agent.online === true,
+        })),
+        openMessageTotal: body.openMessageTotal,
+        runTotal: body.runTotal,
+        runs: runRows.map((run) => {
+          const stages = Array.isArray(run.stages)
+            ? run.stages.filter(isObject).map((stage) => ({
+              id: asString(stage.id) ?? "",
+              status: asString(stage.status) ?? "unknown",
+              ...(typeof stage.attempts === "number" ? { attempts: stage.attempts } : {}),
+            }))
+            : undefined;
+          const done = stages?.filter((stage) => stage.status === "passed" || stage.status === "failed" || stage.status === "warning").length;
+          return {
+            id: asString(run.id) ?? "",
+            status: asString(run.status) ?? "unknown",
+            definitionId: asString(run.definitionId) ?? "",
+            ...(asString(run.currentStage) ? { currentStage: asString(run.currentStage) } : {}),
+            ...(asString(run.targetAgentName) ? { targetAgentName: asString(run.targetAgentName) } : {}),
+            ...(asString(run.updatedAt) ? { updatedAt: asString(run.updatedAt) } : {}),
+            ...(stages !== undefined ? { progress: { done: done ?? 0, total: stages.length }, stages } : {}),
+            source: "hub-projection" as const,
+          };
+        }),
+        plans: (Array.isArray(body.plans) ? body.plans : []).filter(isObject).map((plan) => ({
+          id: asString(plan.id) ?? "",
+          runId: asString(plan.runId) ?? "",
+          summary: asString(plan.summary) ?? "",
+          createdAt: asString(plan.createdAt) ?? "",
+          ...(asString(plan.stageId) ? { stageId: asString(plan.stageId) } : {}),
+          ...(asString(plan.severity) ? { severity: asString(plan.severity) } : {}),
+        })),
+      };
+      return { state: "ok", observedAt: attemptedAt, value };
+    } catch (error) {
+      const name = error instanceof Error ? error.name : undefined;
+      if (name === "TimeoutError" || name === "AbortError") {
+        return { state: "unavailable", observedAt: attemptedAt, reason: "hub_timeout" };
+      }
+      return { state: "unavailable", observedAt: attemptedAt, reason: "hub_unreachable" };
+    }
+  };
+
+  const readRuntime = async (): Promise<TenantSource<TenantRuntimeValue>> => {
+    const attemptedAt = at();
+    try {
+      const runs = await input.runtime.listRuns();
+      return { state: "ok", observedAt: attemptedAt, value: { runs } };
+    } catch (error) {
+      const code = error instanceof Error && "issues" in error
+        && Array.isArray((error as { issues: Array<{ code?: unknown }> }).issues)
+        && typeof (error as { issues: Array<{ code?: unknown }> }).issues[0]?.code === "string"
+        ? (error as { issues: Array<{ code: string }> }).issues[0]!.code
+        : undefined;
+      return { state: "unavailable", observedAt: attemptedAt, reason: code ?? "runtime_unavailable" };
+    }
+  };
+
+  const [hub, runtime] = await Promise.all([readHub(), readRuntime()]);
+
+  let runComparison: TenantRunComparison;
+  if (!hub.value || !runtime.value) {
+    runComparison = {
+      state: "unavailable",
+      reason: !hub.value ? `hub_${hub.reason ?? "unavailable"}` : `runtime_${runtime.reason ?? "unavailable"}`,
+    };
+  } else {
+    // Only cleanly folded rows are authoritative. A row whose fold failed is the cache, and
+    // counting it as agreement is precisely the lie this comparison exists to prevent: a
+    // corrupt event log under a hub run's id would otherwise print "agree".
+    const authoritative = new Map(
+      runtime.value.runs
+        .filter((run) => run.projectionError === undefined)
+        .map((run) => [run.runId, run.status] as const),
+    );
+    const hubIds = new Set(hub.value.runs.map((run) => run.id));
+    const foldFailed = runtime.value.runs.filter((run) => run.projectionError !== undefined && hubIds.has(run.runId));
+    const discrepancies: TenantRunDiscrepancy[] = [];
+    let matched = 0;
+    for (const projected of hub.value.runs) {
+      const runtimeStatus = authoritative.get(projected.id);
+      if (runtimeStatus === undefined) continue;
+      matched += 1;
+      if (runtimeStatus !== projected.status) {
+        discrepancies.push({ runId: projected.id, hubStatus: projected.status, runtimeStatus });
+      }
+    }
+    if (matched > 0) {
+      runComparison = {
+        state: "compared",
+        matched,
+        ...(foldFailed.length > 0 ? { unverifiedFoldRuns: foldFailed.length } : {}),
+        ...(discrepancies.length > 0 ? { discrepancies } : {}),
+      };
+    } else {
+      runComparison = foldFailed.length > 0
+        ? { state: "unverified", reason: "runtime_fold_failed", matched: 0, unverifiedFoldRuns: foldFailed.length }
+        : { state: "unverified", reason: "run_identity_link_absent", matched: 0 };
+    }
+  }
+
+  return {
+    schema: TENANT_STATUS_SCHEMA,
+    project: input.project,
+    generatedAt: at(),
+    hubUrl: input.hubUrl,
+    bindingScope: hubBindingScope(input.hubUrl),
+    hub,
+    runtime,
+    runComparison,
+    degraded: hub.state !== "ok" || runtime.state !== "ok",
+  };
+}
+
+/** One line per source for humans; the portal reads the JSON, operators read this. */
+export function formatTenantStatus(payload: TenantStatusPayload): string {
+  const hubLine = payload.hub.state === "ok" && payload.hub.value
+    ? `hub ${payload.hub.value.agents.filter((agent) => agent.online).length}/${payload.hub.value.agents.length} agents online, ${payload.hub.value.runs.length} hub runs, ${payload.hub.value.openMessageTotal} open messages`
+    : `hub unavailable (${payload.hub.reason ?? "unknown"})`;
+  const runtimeLine = payload.runtime.state === "ok" && payload.runtime.value
+    ? (() => {
+      const cached = payload.runtime.value!.runs.filter((run) => run.projectionError !== undefined).length;
+      const authoritative = payload.runtime.value!.runs.length - cached;
+      // A fold-failed row is the cache; printing it under "authoritative" would put the
+      // lie back in exactly the place an operator reads first.
+      return `runtime ${authoritative} runs (authoritative, on this box)${cached > 0 ? `, ${cached} cached (fold failed, not state)` : ""}`;
+    })()
+    : `runtime unavailable (${payload.runtime.reason ?? "unknown"})`;
+  const comparisonLine = payload.runComparison.state === "compared"
+    ? payload.runComparison.discrepancies && payload.runComparison.discrepancies.length > 0
+      ? `cross-check: ${payload.runComparison.discrepancies.length} of ${payload.runComparison.matched} matched run(s) disagree${payload.runComparison.unverifiedFoldRuns ? ` (${payload.runComparison.unverifiedFoldRuns} unverified: fold failed)` : ""}`
+      : `cross-check: ${payload.runComparison.matched} matched run(s) agree${payload.runComparison.unverifiedFoldRuns ? ` (${payload.runComparison.unverifiedFoldRuns} unverified: fold failed)` : ""}`
+    : payload.runComparison.state === "unverified"
+      ? payload.runComparison.reason === "runtime_fold_failed"
+        ? `cross-check: unavailable — ${payload.runComparison.unverifiedFoldRuns ?? 0} shared run(s) could not be verified (runtime fold failed)`
+        : "cross-check: unavailable — no run id appears in both sources (independent id spaces)"
+      : `cross-check: unavailable (${payload.runComparison.reason ?? "unknown"})`;
+  return [
+    `tenant ${payload.project} @ ${payload.hubUrl} (${payload.bindingScope})`,
+    hubLine,
+    runtimeLine,
+    comparisonLine,
+  ].join("\n");
+}