@mesh-tech/mesh-cli 0.31.1 → 0.33.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "3c02d5aa7",
-  "builtAt": "2026-09-22T17:09:01.518Z"
+  "commit": "b286e1b11",
+  "builtAt": "2026-09-22T20:38:52.960Z"
 }

package/dist/src/commands/app-check.d.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { type ProbeResult } from "./app-check-resolve.js";
 import { jsonReport, type Check, type CheckResult, type CheckStatus } from "./dev-doctor.js";
-export type AppCheckCode = "UNRESOLVABLE_IMPORT" | "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE" | "DOCS_SITE_PUBLIC" | "DOCS_AUDIENCE_IMPLICIT" | "DOCS_AUDIENCE_UNGRANTABLE" | "DOCS_VENDOR_AUDIENCE_PARTNER";
+export type AppCheckCode = "UNRESOLVABLE_IMPORT" | "UI_IN_API" | "NO_UI_SERVICE" | "NO_REGISTER" | "CUSTOM_SESSION_AUTH" | "NON_PLATFORM_LOGGER" | "LOCAL_AUTH_LIB" | "NO_AUTHZ_POINTER" | "METADATA_UNPUBLISHED" | "IAC_GRANTS" | "POINTER_PROJECT_OVERRIDE" | "PASSWORD_STORE" | "EMAIL_ALLOWLIST" | "USERS_TABLE" | "DOCS_SITE_PUBLIC" | "DOCS_AUDIENCE_IMPLICIT" | "DOCS_AUDIENCE_UNGRANTABLE" | "DOCS_VENDOR_AUDIENCE_PARTNER" | "EVENTS_ROLES_UNDECLARED";
 export interface AppCheckRule {
     gate: string;
     title: string;
@@ -35,6 +35,11 @@ export declare function docsSiteFindings(text: string): Array<{
     why: string;
 }>;
 export declare function statedKind(decl: Pick<SurfaceDeclaration, "ctor">, args: Map<string, string>): string | undefined;
+export declare function eventsRoleFindings(text: string): Array<{
+    code: AppCheckCode;
+    line: number;
+    why: string;
+}>;
 export declare function listApps(root: string): string[];
 export declare function probeResolution(root: string, appRel: string): ProbeResult;
 export declare function scanApp(root: string, appRel: string, resolution?: ProbeResult): Finding[];

package/dist/src/commands/app-check.js

@@ -127,6 +127,13 @@ export const APP_CHECK_RULES = {
         remediation: 'declare every audience role on the ZitadelAppIdentity (roles: ["docs"]) so the Hub can grant it from the app\'s Access tab — the audience is published on the surface\'s registry entry as the reader set for the Hub to admit by, and a role nobody can be granted admits nobody',
         scope: "app",
     },
+    EVENTS_ROLES_UNDECLARED: {
+        gate: "H",
+        title: "Events roles grantable from the Hub",
+        severity: "block",
+        remediation: "spread mesh.apps.EVENTS_PROJECT_ROLES into the ZitadelAppIdentity's roles (roles: [...schemaDef.coarseRoles, ...mesh.apps.EVENTS_PROJECT_ROLES]) so events:subscriber and events:admin are project roles the Hub's Access tab can grant — the primitive cannot add them, because the identity builds its roles before the events service exists and a role added afterwards is absent from the coarseRoles the Hub reads",
+        scope: "app",
+    },
     DOCS_VENDOR_AUDIENCE_PARTNER: {
         gate: "H",
         title: "Vendor reference never partner-readable",
@@ -257,7 +264,7 @@ const RE_HTML = /from ["']hono\/(html|jsx)["']|react-dom\/server|\bc\.html\(|<!d
 const RE_OIDC = /openid-client|code_verifier|authorization_code|buildAuthorizeUrl|end_session/;
 const RE_COOKIE = /setCookie\(|hono\/cookie|Set-Cookie/;
 const RE_LOGGER = /from ["'](pino|hono\/logger|winston|bunyan)["']|require\(["'](pino|winston|bunyan)["']\)|^[^/*]*\bconsole\.(log|info|warn|error)\(/;
-const RE_EXPOSURE = /ZitadelAppIdentity|createOAuthMiddleware|createAuthorizationMiddleware|zitadelJwtScheme|createAuthzMiddleware|bearerAuth|type: *"oidc"|^\s+auth: *\{|_ROLES *= *\{|coarseRoles|ZITADEL_(AUDIENCE|CLIENT_ID)|OIDC_CLIENT_ID|zitadel\.(ApplicationOidc|ApplicationApi|Project|UserGrant)\(/;
+const RE_EXPOSURE = /ZitadelAppIdentity|createOAuthMiddleware|createAuthorizationMiddleware|zitadelJwtScheme|createAuthzMiddleware|bearerAuth|type: *"oidc"|^\s+auth: *\{|_ROLES *= *\{|coarseRoles|ZITADEL_(AUDIENCE|CLIENT_ID)|OIDC_CLIENT_ID|zitadel\.(ApplicationOidc|ApplicationApi|Project|UserGrant)\(|mesh\.apps\.EventsService\(/;
 const RE_POINTER = /AppAuthzPointer/;
 const RE_METADATA = /compileOpsHubMetadata|ops-hub-metadata|SpiceDBSchema/;
 const RE_IAC_GRANT = /userId: *"[0-9]{6,}"/;
@@ -268,6 +275,8 @@ const RE_USERS_TABLE = /create table (if not exists )?"?(users|roles|user_roles|
 const RE_SURFACE_NEW = /new\s+mesh\.apps\.(ApiSurface|AppApiSurface|VendorApiSurface|Integration)\s*\(/g;
 const RE_APIDOCS_NEW = /new\s+mesh\.apps\.ApiDocs\s*\(/g;
 const RE_IDENTITY_NEW = /new\s+mesh\.auth\.(ZitadelAppIdentity)\s*\(/g;
+const RE_EVENTS_NEW = /new\s+mesh\.apps\.(EventsService)\s*\(/g;
+const EVENTS_PROJECT_ROLES = ["events:subscriber", "events:admin"];
 const RE_IDENTITY_BINDING = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::[^=]+)?=\s*new\s+mesh\.auth\.ZitadelAppIdentity\s*\(/g;
 const DEFAULT_PARTNER_DOCS_ROLES = ["docs"];
 export function stringList(value) {
@@ -557,6 +566,62 @@ export function statedKind(decl, args) {
         return "vendor";
     return /^["']([a-z]+)["']$/.exec(args.get("kind") ?? "")?.[1];
 }
+function programIdentities(text) {
+    const identities = [];
+    for (const d of surfaceDeclarations(text, RE_IDENTITY_NEW)) {
+        const options = optionsObject(d.body, text);
+        if (!options)
+            continue;
+        const binding = [...text.matchAll(RE_IDENTITY_BINDING)].find((m) => text.indexOf(d.body, m.index) === m.index + m[0].length - 1)?.[1];
+        identities.push({ binding, options: topLevelProperties(options) });
+    }
+    return identities;
+}
+function declaredProjectRoles(identity) {
+    const rolesText = identity.options.get("roles");
+    const coarseText = identity.options.get("coarseRoles");
+    if (rolesText !== undefined)
+        return stringList(rolesText);
+    if (coarseText !== undefined)
+        return stringList(coarseText);
+    return [];
+}
+export function eventsRoleFindings(text) {
+    const findings = [];
+    const identities = programIdentities(text);
+    for (const decl of surfaceDeclarations(text, RE_EVENTS_NEW)) {
+        const options = optionsObject(decl.body, text);
+        if (!options)
+            continue;
+        const args = topLevelProperties(options);
+        if (args.get("enabled") === "false")
+            continue;
+        if (identities.length === 0) {
+            continue;
+        }
+        const identityText = objectLiteralOf(args.get("identity"), text);
+        const projectExpr = identityText ? topLevelProperties(identityText).get("projectId") : undefined;
+        const projectRoot = projectExpr ? /^([A-Za-z_$][\w$]*)\.projectId\b/.exec(projectExpr.trim())?.[1] : undefined;
+        const identity = (projectRoot ? identities.find((id) => id.binding === projectRoot) : undefined) ??
+            (identities.length === 1 ? identities[0] : undefined);
+        if (!identity)
+            continue;
+        const declared = declaredProjectRoles(identity);
+        if (!declared)
+            continue;
+        const missing = EVENTS_PROJECT_ROLES.filter((r) => !declared.includes(r));
+        if (missing.length === 0)
+            continue;
+        findings.push({
+            code: "EVENTS_ROLES_UNDECLARED",
+            line: decl.line,
+            why: `mesh.apps.EventsService is declared but the app's ZitadelAppIdentity does not declare ${missing
+                .map((r) => `"${r}"`)
+                .join(" or ")} — the events service authorizes bearer callers by these project roles, and a role the identity never declares cannot be granted from the Hub's Access tab, so no subscriber can be admitted`,
+        });
+    }
+    return findings;
+}
 function docsAudienceUngrantable(text, decl, args, docs, httpText) {
     const findings = [];
     let roles;
@@ -569,14 +634,7 @@ function docsAudienceUngrantable(text, decl, args, docs, httpText) {
     }
     if (!roles || roles.length === 0)
         return findings;
-    const identities = [];
-    for (const d of surfaceDeclarations(text, RE_IDENTITY_NEW)) {
-        const options = optionsObject(d.body, text);
-        if (!options)
-            continue;
-        const binding = [...text.matchAll(RE_IDENTITY_BINDING)].find((m) => text.indexOf(d.body, m.index) === m.index + m[0].length - 1)?.[1];
-        identities.push({ binding, options: topLevelProperties(options) });
-    }
+    const identities = programIdentities(text);
     if (identities.length === 0)
         return findings;
     const docsAuth = objectLiteralOf(docs.get("auth"), text);
@@ -587,9 +645,7 @@ function docsAudienceUngrantable(text, decl, args, docs, httpText) {
         (identities.length === 1 ? identities[0] : undefined);
     if (!identity)
         return findings;
-    const rolesText = identity.options.get("roles");
-    const coarseText = identity.options.get("coarseRoles");
-    const declared = rolesText !== undefined ? stringList(rolesText) : coarseText !== undefined ? stringList(coarseText) : [];
+    const declared = declaredProjectRoles(identity);
     if (declared) {
         for (const role of roles) {
             if (declared.includes(role))
@@ -668,6 +724,8 @@ export function scanApp(root, appRel, resolution = probeResolution(root, appRel)
         }
         for (const f of docsSiteFindings(readText(index)))
             hit(f.code, `${indexRel}:${f.line}`, f.why);
+        for (const f of eventsRoleFindings(readText(index)))
+            hit(f.code, `${indexRel}:${f.line}`, f.why);
         for (const svc of serviceDirs(app)) {
             for (const f of srcFiles(svc)) {
                 const text = readText(f);

package/dist/src/commands/create-app.d.ts

@@ -27,10 +27,13 @@ export declare function generateComposableApp(appDir: string, context: {
     database: boolean;
     temporal: boolean;
     bucket: boolean;
+    events: boolean;
     region: string;
     workspaceDeps: boolean;
     meshRange: string;
     esmBundleRange: string;
+    eventsServiceRange: string;
+    authzRange: string;
     typesNodeRange: string;
     tsxRange: string;
     typescriptRange: string;

package/dist/src/commands/create-app.js

@@ -30,6 +30,7 @@ const PRIMITIVES = {
     database: "Database (PostgreSQL via Prisma)",
     temporal: "Temporal (workflow orchestration)",
     bucket: "S3 Bucket (file storage)",
+    events: "Events and webhooks (publish, subscriptions, signed delivery)",
 };
 const HUB_ACCOUNTS = {
     mesh: "159923586610",
@@ -198,6 +199,10 @@ async function promptForOptions(options) {
         primitives.push("service");
         logInfo("Added 'service' — bucket requires an API service for S3 helpers.");
     }
+    if (primitives.includes("events") && !primitives.includes("service")) {
+        primitives.push("service");
+        logInfo("Added 'service' — the events publisher lives in the api/ directory.");
+    }
     return { tenant, name, primitives };
 }
 export function copyTemplate(srcDir, destDir, context) {
@@ -311,6 +316,13 @@ export function generateComposableApp(appDir, context) {
         }
         copyTemplate(bucketDir, appDir, context);
     }
+    if (context.events) {
+        const eventsDir = path.join(fragmentsDir, "events");
+        if (!fs.existsSync(eventsDir)) {
+            throw new Error(`Fragment directory not found: ${eventsDir}`);
+        }
+        copyTemplate(eventsDir, appDir, context);
+    }
     const agentsDir = path.join(fragmentsDir, "agents");
     if (fs.existsSync(agentsDir)) {
         copyTemplate(agentsDir, appDir, context);
@@ -375,6 +387,10 @@ export function registerCreateAppCommand(program) {
             primitives.push("service");
             logInfo("Added 'service' — bucket requires an API service for S3 helpers.");
         }
+        if (primitives.includes("events") && !primitives.includes("service")) {
+            primitives.push("service");
+            logInfo("Added 'service' — the events publisher lives in the api/ directory.");
+        }
         await runComposable(tenant, name, primitives, options.test);
     });
 }
@@ -496,6 +512,12 @@ async function runComposable(tenant, name, primitives, test) {
     const esmBundle = workspaceDeps
         ? { range: "", resolved: true }
         : resolvePublishedRange("@mesh-tech/esm-bundle", repoRoot);
+    const eventsService = workspaceDeps || !primitives.includes("events")
+        ? { range: "", resolved: true }
+        : resolvePublishedRange("@mesh-tech/events-service", repoRoot);
+    const authz = workspaceDeps || !primitives.includes("events")
+        ? { range: "", resolved: true }
+        : resolvePublishedRange("@mesh-tech/authz", repoRoot);
     if (!workspaceDeps) {
         logInfo(mesh.resolved
             ? `@mesh-tech/* pinned to ${mesh.range} (current published line)`
@@ -508,10 +530,13 @@ async function runComposable(tenant, name, primitives, test) {
         database: primitives.includes("database"),
         temporal: primitives.includes("temporal"),
         bucket: primitives.includes("bucket"),
+        events: primitives.includes("events"),
         region,
         workspaceDeps,
         meshRange: mesh.range,
         esmBundleRange: esmBundle.range,
+        eventsServiceRange: eventsService.range,
+        authzRange: authz.range,
         typesNodeRange: SCAFFOLD_TOOLCHAIN["@types/node"],
         tsxRange: SCAFFOLD_TOOLCHAIN.tsx,
         typescriptRange: SCAFFOLD_TOOLCHAIN.typescript,

package/dist/src/commands/hub/index.d.ts

@@ -1,6 +1,11 @@
 import { Command } from "commander";
 import { type SessionState } from "../dev.js";
-export declare const HUB_SESSION = "mesh-hub-dev";
+export declare const HUB_SESSION_PREFIX = "mesh-hub-dev";
+export declare function hubSessionName(apiPort: number): string;
+export declare function isHubSession(name: string): boolean;
+export declare function listHubSessions(): string[];
+export declare function killTargets(live: string[], named: string | null): string[];
+export declare function killInstructions(targets: string[]): string[];
 export declare const DEFAULT_HUB_UI_PORT: number;
 export declare const DEFAULT_HUB_API_PORT = 3002;
 export interface DiscoveredSession {

package/dist/src/commands/hub/index.js

@@ -10,7 +10,37 @@ import { MeshCliError } from "../../utils/errors.js";
 import { DEFAULT_HUB_PORT } from "../local/stack.js";
 import { logInfo, logSuccess, logWarn } from "../../utils/log.js";
 import { findAppRoot } from "../../utils/pulumi.js";
-export const HUB_SESSION = "mesh-hub-dev";
+export const HUB_SESSION_PREFIX = "mesh-hub-dev";
+export function hubSessionName(apiPort) {
+    return `${HUB_SESSION_PREFIX}-${apiPort}`;
+}
+const HUB_SESSION_RE = new RegExp(`^${HUB_SESSION_PREFIX}(-\\d+)?$`);
+export function isHubSession(name) {
+    return HUB_SESSION_RE.test(name);
+}
+export function listHubSessions() {
+    try {
+        return execFileSync("tmux", ["list-sessions", "-F", "#{session_name}"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(isHubSession);
+    }
+    catch {
+        return [];
+    }
+}
+export function killTargets(live, named) {
+    return named ? live.filter((name) => name === named) : live;
+}
+export function killInstructions(targets) {
+    return targets.map((name) => {
+        const port = name.slice(HUB_SESSION_PREFIX.length + 1);
+        return port ? `  ${name}: mesh hub dev --kill --api-port ${port}` : `  ${name}: tmux kill-session -t ${name}`;
+    });
+}
 export const DEFAULT_HUB_UI_PORT = Number(DEFAULT_HUB_PORT);
 export const DEFAULT_HUB_API_PORT = 3002;
 export function devSessionsDir() {
@@ -248,8 +278,8 @@ function isPortListening(port) {
         socket.once("error", () => done(false));
     });
 }
-function hubEnvDir() {
-    return path.join(os.tmpdir(), "mesh-dev-sessions", HUB_SESSION);
+function hubEnvDir(sessionName) {
+    return path.join(os.tmpdir(), "mesh-dev-sessions", sessionName);
 }
 export function parsePort(raw, fallback, source) {
     if (raw === undefined)
@@ -273,20 +303,30 @@ export function redactEnv(env) {
 }
 async function hubDevAction(opts) {
     if (opts.kill) {
-        if (tmuxSessionExists(HUB_SESSION)) {
-            execFileSync("tmux", ["kill-session", "-t", HUB_SESSION], { stdio: "ignore" });
-            fs.rmSync(hubEnvDir(), { recursive: true, force: true });
-            logSuccess(`Killed Hub session '${HUB_SESSION}'.`);
+        const namedPort = opts.apiPort || process.env.MESH_HUB_DEV_API_PORT;
+        const named = namedPort
+            ? hubSessionName(parsePort(namedPort, DEFAULT_HUB_API_PORT, opts.apiPort ? "--api-port" : "MESH_HUB_DEV_API_PORT"))
+            : null;
+        const targets = killTargets(listHubSessions(), named);
+        if (targets.length === 0) {
+            logInfo(named ? `No '${named}' tmux session running.` : "No `mesh hub dev` session running.");
+            return;
         }
-        else {
-            logInfo(`No '${HUB_SESSION}' tmux session running.`);
+        if (targets.length > 1) {
+            throw new MeshCliError(`${targets.length} Hub sessions are running — name the one to stop.\n${killInstructions(targets).join("\n")}`, { remediation: { command: "mesh hub dev --kill --api-port <port>   # the API port that Hub was started on" } });
         }
+        const target = targets[0];
+        execFileSync("tmux", ["kill-session", "-t", target], { stdio: "ignore" });
+        fs.rmSync(hubEnvDir(target), { recursive: true, force: true });
+        logSuccess(`Killed Hub session '${target}'.`);
         return;
     }
     const uiPort = opts.port
         ? parsePort(opts.port, DEFAULT_HUB_UI_PORT, "--port")
         : parsePort(process.env.MESH_HUB_DEV_PORT, DEFAULT_HUB_UI_PORT, "MESH_HUB_DEV_PORT");
-    const apiPort = parsePort(opts.apiPort, DEFAULT_HUB_API_PORT, "--api-port");
+    const apiPort = opts.apiPort
+        ? parsePort(opts.apiPort, DEFAULT_HUB_API_PORT, "--api-port")
+        : parsePort(process.env.MESH_HUB_DEV_API_PORT, DEFAULT_HUB_API_PORT, "MESH_HUB_DEV_API_PORT");
     const platformDir = resolvePlatformDir(opts.platformDir, process.cwd());
     const cwdAppRoot = findAppRoot(process.cwd());
     const session = pickDevSession(listDevSessions(), { session: opts.session, cwdAppRoot });
@@ -309,9 +349,10 @@ async function hubDevAction(opts) {
             console.log(`  ${k}=${v}`);
         return;
     }
-    if (tmuxSessionExists(HUB_SESSION)) {
-        throw new MeshCliError(`A '${HUB_SESSION}' tmux session is already running.`, {
-            remediation: { command: "mesh hub dev --kill   # then re-run mesh hub dev" },
+    const hubSession = hubSessionName(apiPort);
+    if (tmuxSessionExists(hubSession)) {
+        throw new MeshCliError(`A '${hubSession}' tmux session is already running.`, {
+            remediation: { command: `mesh hub dev --kill --api-port ${apiPort}   # then re-run` },
         });
     }
     for (const [label, port, flag] of [
@@ -333,20 +374,20 @@ async function hubDevAction(opts) {
         logWarn(warning);
     const apiDir = path.join(platformDir, "apps", "hub", "api");
     const uiDir = path.join(platformDir, "apps", "hub", "ui");
-    execFileSync("tmux", ["new-session", "-d", "-s", HUB_SESSION, "-n", "api", "-c", apiDir]);
+    execFileSync("tmux", ["new-session", "-d", "-s", hubSession, "-n", "api", "-c", apiDir]);
     if (!assembled.apiEnv.DEV_USER_TOKEN_URL && assembled.apiEnv.DEV_USER_ID_TOKEN) {
         const platform = session.state.devOutput.platform;
         const credContext = `mesh.${platform.env}`;
         const tokenPort = await findFreePort();
         const tokenUrl = `http://127.0.0.1:${tokenPort}`;
-        execFileSync("tmux", ["new-window", "-t", HUB_SESSION, "-n", "token-server", "-c", platformDir]);
-        execFileSync("tmux", ["set-option", "-t", `${HUB_SESSION}:token-server`, "remain-on-exit", "on"], {
+        execFileSync("tmux", ["new-window", "-t", hubSession, "-n", "token-server", "-c", platformDir]);
+        execFileSync("tmux", ["set-option", "-t", `${hubSession}:token-server`, "remain-on-exit", "on"], {
             stdio: "ignore",
         });
         execFileSync("tmux", [
             "send-keys",
             "-t",
-            `${HUB_SESSION}:token-server`,
+            `${hubSession}:token-server`,
             `npx mesh dev __token-server ${tokenPort} ${credContext}`,
             "Enter",
         ]);
@@ -358,15 +399,15 @@ async function hubDevAction(opts) {
         logSuccess(`Dev-user token-server: ${tokenUrl} (context ${credContext})`);
     }
     const launch = (window, dir, env, cmd, createWindow) => {
-        const envFile = path.join(hubEnvDir(), `${window}.env.sh`);
+        const envFile = path.join(hubEnvDir(hubSession), `${window}.env.sh`);
         writeEnvFile(envFile, env);
         if (createWindow) {
-            execFileSync("tmux", ["new-window", "-t", HUB_SESSION, "-n", window, "-c", dir]);
+            execFileSync("tmux", ["new-window", "-t", hubSession, "-n", window, "-c", dir]);
         }
-        execFileSync("tmux", ["set-option", "-t", `${HUB_SESSION}:${window}`, "remain-on-exit", "on"], {
+        execFileSync("tmux", ["set-option", "-t", `${hubSession}:${window}`, "remain-on-exit", "on"], {
             stdio: "ignore",
         });
-        execFileSync("tmux", ["send-keys", "-t", `${HUB_SESSION}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
+        execFileSync("tmux", ["send-keys", "-t", `${hubSession}:${window}`, buildLaunchCommand(envFile, dir, cmd), "Enter"]);
     };
     launch("api", apiDir, assembled.apiEnv, "pnpm dev", false);
     launch("ui", uiDir, assembled.uiEnv, `pnpm dev --port ${uiPort} --strictPort`, true);
@@ -374,14 +415,14 @@ async function hubDevAction(opts) {
     const apiUp = await waitForPort("127.0.0.1", apiPort, 90_000);
     const uiUp = apiUp && (await waitForPort("127.0.0.1", uiPort, 90_000));
     if (!apiUp || !uiUp) {
-        throw new MeshCliError(`Hub ${apiUp ? "UI" : "API"} did not start listening (api :${apiPort}, ui :${uiPort}).`, { remediation: { command: `tmux attach -t ${HUB_SESSION}   # inspect the ${apiUp ? "ui" : "api"} window` } });
+        throw new MeshCliError(`Hub ${apiUp ? "UI" : "API"} did not start listening (api :${apiPort}, ui :${uiPort}).`, { remediation: { command: `tmux attach -t ${hubSession}   # inspect the ${apiUp ? "ui" : "api"} window` } });
     }
     console.log("");
     logSuccess(`Mesh Hub (dev-local scope ${assembled.scope.scopeTenants.join(",")} @ ${assembled.scope.scopeEnv})`);
     console.log(`  ${chalk.bold.cyan(`http://localhost:${uiPort}`)}  (also reachable on your tailnet)`);
     console.log(`  api  http://localhost:${apiPort}`);
-    console.log(`  logs tmux attach -t ${HUB_SESSION}`);
-    console.log(`  stop mesh hub dev --kill`);
+    console.log(`  logs tmux attach -t ${hubSession}`);
+    console.log(`  stop mesh hub dev --kill --api-port ${apiPort}`);
 }
 export function registerHubCommands(program) {
     const hub = program.command("hub").description("Local Hub over dev-local stacks");
@@ -392,9 +433,9 @@ export function registerHubCommands(program) {
         .option("--tenants <list>", "comma-separated HUB_SCOPE_TENANTS override (default: the session's tenant)")
         .option("--audience <who>", "who the Hub renders for: `operator` (platform staff — the default here) or `tenant` (a client's operators). Anything else reads as `tenant`")
         .option("--port <port>", `Hub UI host port (default: $MESH_HUB_DEV_PORT or ${DEFAULT_HUB_UI_PORT})`)
-        .option("--api-port <port>", `Hub API port (default: ${DEFAULT_HUB_API_PORT})`)
+        .option("--api-port <port>", `Hub API port, and the key its tmux session is named after — several Hubs coexist on different ones (default: $MESH_HUB_DEV_API_PORT or ${DEFAULT_HUB_API_PORT})`)
         .option("--platform-dir <dir>", "mesh-platform checkout to run the Hub from (default: $MESH_PLATFORM_DIR or walk up from cwd)")
         .option("--print-env", "print the assembled env (secrets redacted) and exit without launching")
-        .option("--kill", "tear down the running Hub session")
+        .option("--kill", "tear down a running Hub session; with several up, name it with --api-port (or $MESH_HUB_DEV_API_PORT)")
         .action(hubDevAction);
 }

package/dist/src/commands/temporal.js

@@ -533,7 +533,7 @@ var init_src = __esm({
       z.object({ op: z.string().trim().min(1) }),
       z.object({ unavailable: z.string().trim().min(1) })
     ]);
-    apiSurfaceKindSchema = z.enum(["app", "vendor"]);
+    apiSurfaceKindSchema = z.enum(["app", "vendor", "events"]);
     apiDocsSiteAudienceSchema = z.discriminatedUnion("readers", [
       z.object({ readers: z.literal("partner"), roles: z.array(z.string().min(1)) }),
       z.object({ readers: z.literal("operator") })