agent-tempo 1.1.0 → 1.3.1

package/dist/cli/help-text.js

@@ -57,102 +57,102 @@ const types_1 = require("../types");
 // adding a new adapter automatically updates this surface.
 const AGENT_OPTIONS = types_1.AGENT_TYPES.join('|');
 function printHelp() {
-    console.log(`
-${out.bold('agent-tempo')} — Multi-session Claude Code coordination via Temporal
-
-${out.bold('Getting started:')}
-  ${out.cyan('agent-tempo up')}                  Start infrastructure, then launch the TUI with ${out.dim('agent-tempo')}
-
-${out.bold('Usage:')}
-  agent-tempo                         Launch the TUI (auto-provisions + opens home view)
-  agent-tempo <ensemble>              Launch the TUI directly into an ensemble view
-  agent-tempo <command> [options]
-
-${out.bold('Commands:')}
-  ${out.cyan('up')}                       Start infrastructure only — Temporal, daemon, MCP registration
-  ${out.cyan('down')}                     Stop infrastructure; workflows stay parked for the next ${out.dim('up')}
-  ${out.cyan('down --destroy [-y]')}      Terminate every workflow across every ensemble, then stop infrastructure
-  ${out.cyan('server')}                   Start the Temporal dev server and register search attributes
-  ${out.cyan('status')}  [ensemble]       Show active sessions and Temporal health
-  ${out.cyan('ensemble')} <sub>           Manage saved ensemble lineups (save/list/show)
-  ${out.cyan('broadcast')} <message>      Send a message to all active players
-  ${out.cyan('destroy')} <ensemble> [-y]  Terminate every workflow in one ensemble (typed confirmation)
-  ${out.cyan('attachment-info')} <name>   Inspect the V2 attachment phase + current holder
-  ${out.cyan('recall')} <name>            Read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
-  ${out.cyan('hosts')}                    List daemons polling this Temporal namespace with advertised capabilities (--all/--json)
-  ${out.cyan('refresh-host-profile')}     Re-advertise this daemon's capability profile to the global Maestro
-  ${out.cyan('restore')} <ensemble>       Restore orphaned sessions in one ensemble on this host (--all-hosts for cluster-view listing)
-  ${out.cyan('release')} [ensemble]       Release all held players (unlock outbox, deliver messages)
-  ${out.cyan('agent-types')} <sub>        Manage player type definitions (list/show/init)
-  ${out.cyan('daemon')}    <sub>          Manage the worker daemon (start/stop/status/logs)
-  ${out.cyan('dashboard')}                Open the web dashboard (--no-open / --pair / --json)
-  ${out.cyan('upgrade')}  [version]       Upgrade agent-tempo to latest (or specific version)
-  ${out.cyan('config')}                   Configure Temporal connection settings
-  ${out.cyan('init')}                     Register MCP server globally (or --project for .mcp.json)
-  ${out.cyan('preflight')}                Run preflight checks only
-  ${out.cyan('help')}                     Show this help message
-
-${out.bold('Removed — use the TUI:')}
-  ${out.dim('stop / restart / detach / migrate')}   → ${out.dim('/destroy · /restart · /shutdown')}
-  ${out.dim('conduct / start / recruit / disband')} → ${out.dim('launch `agent-tempo` · /recruit · /destroy')}
-  ${out.dim('resume')}                              → ${out.dim('/play')}
-  See https://github.com/vinceblank/agent-tempo/issues/285 for the full migration table.
-
-${out.bold('Connection options (all commands):')}
-  --temporal-address <addr>    Temporal server address (default: localhost:7233)
-  --temporal-namespace <ns>    Temporal namespace (default: default)
-  --temporal-api-key <key>     Temporal API key (for Temporal Cloud)
-  --temporal-tls-cert <path>   Path to TLS client certificate
-  --temporal-tls-key <path>    Path to TLS client key
-
-${out.bold('Other options:')}
-  --name <name>                Set session window name (up only)
-  --agent <name>               Agent type to spawn — ${AGENT_OPTIONS} (default: from config; up)
-  --dev                        Use the dev profile (~/.agent-tempo-dev, port 8474, namespace agent-tempo-dev)
-  --skip-preflight             Skip preflight checks
-  --background                 Run Temporal in background (server only)
-  --project                    Use per-project .mcp.json instead of global (init only)
-  --keep-mcp                   Don't remove MCP config (down only)
-  --keep-daemon                Don't stop the worker daemon (down only)
-  --destroy                    Also terminate every workflow (down only)
-  --kill-shared-temporal       Tear down the Temporal dev server even if the other profile is active (down only, #423)
-  -y, --yes                    Skip confirmation prompt (down --destroy, destroy)
-  --lineup <name|file>         Load ensemble lineup by name or file path (up)
-  --scenario <name|path>       Force every mock player in the lineup into mockMode:scripted with this scenario (dev-mode-only, up + --lineup)
-  --no-hold                    Skip startup hold (requires --lineup on up)
-  --ensemble <name>            Target a specific ensemble (broadcast, destroy, restore)
-  --all-hosts                  List cross-host orphans across the whole namespace (restore — read-only, #151)
-  -d, --dir <path>             Target directory (default: cwd)
-
-${out.bold('Config command:')}
-  ${out.dim('agent-tempo config')}              Interactive connection setup
-  ${out.dim('agent-tempo config show')}         Show resolved config
-  ${out.dim('agent-tempo config set <k> <v>')}  Set a config value
-
-  Settings are saved to ~/.agent-tempo/config.json.
-  Also reads ~/.config/temporalio/temporal.yaml as a fallback.
-
-  ${out.bold('Resolution order:')} CLI flag > env var > config file > temporal CLI config > default
-
-${out.bold('First time? Run this:')}
-  ${out.dim('cd your-project')}
-  ${out.dim('agent-tempo up')}
-  ${out.dim('agent-tempo')}            # Launch the TUI
-
-${out.bold('Typical workflow:')}
-  ${out.dim('agent-tempo up')}                 Start infrastructure (once per host)
-  ${out.dim('agent-tempo')}                    Launch the TUI
-  ${out.dim('agent-tempo status myband')}      Check who's active in an ensemble
-
-${out.bold('Environment:')}
-  AGENT_TEMPO_ENSEMBLE       Default ensemble name (fallback: "default")
-  TEMPORAL_ADDRESS            Default Temporal address (fallback: localhost:7233)
-  TEMPORAL_NAMESPACE          Default Temporal namespace (fallback: "default")
-  TEMPORAL_API_KEY            Temporal API key
-  TEMPORAL_TLS_CERT_PATH      Path to TLS client certificate
-  TEMPORAL_TLS_KEY_PATH       Path to TLS client key
-  AGENT_TEMPO_DEFAULT_AGENT  Default agent type: claude or copilot (fallback: claude)
-  AGENT_TEMPO_DEV_MODE       Set to "1" or "true" to enable the dev profile (alternative to --dev)
-  AGENT_TEMPO_HOME_OVERRIDE  Override the home dir entirely (escape hatch for triple-isolated envs)
+    console.log(`
+${out.bold('agent-tempo')} — Multi-session Claude Code coordination via Temporal
+
+${out.bold('Getting started:')}
+  ${out.cyan('agent-tempo up')}                  Start infrastructure, then launch the TUI with ${out.dim('agent-tempo')}
+
+${out.bold('Usage:')}
+  agent-tempo                         Launch the TUI (auto-provisions + opens home view)
+  agent-tempo <ensemble>              Launch the TUI directly into an ensemble view
+  agent-tempo <command> [options]
+
+${out.bold('Commands:')}
+  ${out.cyan('up')}                       Start infrastructure only — Temporal, daemon, MCP registration
+  ${out.cyan('down')}                     Stop infrastructure; workflows stay parked for the next ${out.dim('up')}
+  ${out.cyan('down --destroy [-y]')}      Terminate every workflow across every ensemble, then stop infrastructure
+  ${out.cyan('server')}                   Start the Temporal dev server and register search attributes
+  ${out.cyan('status')}  [ensemble]       Show active sessions and Temporal health
+  ${out.cyan('ensemble')} <sub>           Manage saved ensemble lineups (save/list/show)
+  ${out.cyan('broadcast')} <message>      Send a message to all active players
+  ${out.cyan('destroy')} <ensemble> [-y]  Terminate every workflow in one ensemble (typed confirmation)
+  ${out.cyan('attachment-info')} <name>   Inspect the V2 attachment phase + current holder
+  ${out.cyan('recall')} <name>            Read a player's message history (--limit/--offset/--preview/--from/--since/--include-sent/--json)
+  ${out.cyan('hosts')}                    List daemons polling this Temporal namespace with advertised capabilities (--all/--json)
+  ${out.cyan('refresh-host-profile')}     Re-advertise this daemon's capability profile to the global Maestro
+  ${out.cyan('restore')} <ensemble>       Restore orphaned sessions in one ensemble on this host (--all-hosts for cluster-view listing)
+  ${out.cyan('release')} [ensemble]       Release all held players (unlock outbox, deliver messages)
+  ${out.cyan('agent-types')} <sub>        Manage player type definitions (list/show/init)
+  ${out.cyan('daemon')}    <sub>          Manage the worker daemon (start/stop/status/logs)
+  ${out.cyan('dashboard')}                Open the web dashboard (--no-open / --pair / --json)
+  ${out.cyan('upgrade')}  [version]       Upgrade agent-tempo to latest (or specific version)
+  ${out.cyan('config')}                   Configure Temporal connection settings
+  ${out.cyan('init')}                     Register MCP server globally (or --project for .mcp.json)
+  ${out.cyan('preflight')}                Run preflight checks only
+  ${out.cyan('help')}                     Show this help message
+
+${out.bold('Removed — use the TUI:')}
+  ${out.dim('stop / restart / detach / migrate')}   → ${out.dim('/destroy · /restart · /shutdown')}
+  ${out.dim('conduct / start / recruit / disband')} → ${out.dim('launch `agent-tempo` · /recruit · /destroy')}
+  ${out.dim('resume')}                              → ${out.dim('/play')}
+  See https://github.com/vinceblank/agent-tempo/issues/285 for the full migration table.
+
+${out.bold('Connection options (all commands):')}
+  --temporal-address <addr>    Temporal server address (default: localhost:7233)
+  --temporal-namespace <ns>    Temporal namespace (default: default)
+  --temporal-api-key <key>     Temporal API key (for Temporal Cloud)
+  --temporal-tls-cert <path>   Path to TLS client certificate
+  --temporal-tls-key <path>    Path to TLS client key
+
+${out.bold('Other options:')}
+  --name <name>                Set session window name (up only)
+  --agent <name>               Agent type to spawn — ${AGENT_OPTIONS} (default: from config; up)
+  --dev                        Use the dev profile (~/.agent-tempo-dev, port 8474, namespace agent-tempo-dev)
+  --skip-preflight             Skip preflight checks
+  --background                 Run Temporal in background (server only)
+  --project                    Use per-project .mcp.json instead of global (init only)
+  --keep-mcp                   Don't remove MCP config (down only)
+  --keep-daemon                Don't stop the worker daemon (down only)
+  --destroy                    Also terminate every workflow (down only)
+  --kill-shared-temporal       Tear down the Temporal dev server even if the other profile is active (down only, #423)
+  -y, --yes                    Skip confirmation prompt (down --destroy, destroy)
+  --lineup <name|file>         Load ensemble lineup by name or file path (up)
+  --scenario <name|path>       Force every mock player in the lineup into mockMode:scripted with this scenario (dev-mode-only, up + --lineup)
+  --no-hold                    Skip startup hold (requires --lineup on up)
+  --ensemble <name>            Target a specific ensemble (broadcast, destroy, restore)
+  --all-hosts                  List cross-host orphans across the whole namespace (restore — read-only, #151)
+  -d, --dir <path>             Target directory (default: cwd)
+
+${out.bold('Config command:')}
+  ${out.dim('agent-tempo config')}              Interactive connection setup
+  ${out.dim('agent-tempo config show')}         Show resolved config
+  ${out.dim('agent-tempo config set <k> <v>')}  Set a config value
+
+  Settings are saved to ~/.agent-tempo/config.json.
+  Also reads ~/.config/temporalio/temporal.yaml as a fallback.
+
+  ${out.bold('Resolution order:')} CLI flag > env var > config file > temporal CLI config > default
+
+${out.bold('First time? Run this:')}
+  ${out.dim('cd your-project')}
+  ${out.dim('agent-tempo up')}
+  ${out.dim('agent-tempo')}            # Launch the TUI
+
+${out.bold('Typical workflow:')}
+  ${out.dim('agent-tempo up')}                 Start infrastructure (once per host)
+  ${out.dim('agent-tempo')}                    Launch the TUI
+  ${out.dim('agent-tempo status myband')}      Check who's active in an ensemble
+
+${out.bold('Environment:')}
+  AGENT_TEMPO_ENSEMBLE       Default ensemble name (fallback: "default")
+  TEMPORAL_ADDRESS            Default Temporal address (fallback: localhost:7233)
+  TEMPORAL_NAMESPACE          Default Temporal namespace (fallback: "default")
+  TEMPORAL_API_KEY            Temporal API key
+  TEMPORAL_TLS_CERT_PATH      Path to TLS client certificate
+  TEMPORAL_TLS_KEY_PATH       Path to TLS client key
+  AGENT_TEMPO_DEFAULT_AGENT  Default agent type: claude or copilot (fallback: claude)
+  AGENT_TEMPO_DEV_MODE       Set to "1" or "true" to enable the dev profile (alternative to --dev)
+  AGENT_TEMPO_HOME_OVERRIDE  Override the home dir entirely (escape hatch for triple-isolated envs)
 `);
 }

package/dist/cli/sa-preflight.d.ts

@@ -6,10 +6,13 @@ export declare const REQUIRED_SEARCH_ATTRIBUTES: ReadonlyArray<{
 export interface SearchAttributePreflightOpts {
     temporalAddress: string;
     temporalNamespace: string;
+    /** API key for Temporal Cloud — triggers SDK-based probe when set. */
+    temporalApiKey?: string;
     /**
      * Optional test seam — given a namespace, return the set of search
      * attribute names that ARE currently registered. Defaults to
-     * {@link defaultProbeRegisteredAttributes} which shells out to
+     * {@link sdkProbeRegisteredAttributes} when `temporalApiKey` is set,
+     * otherwise {@link defaultProbeRegisteredAttributes} which shells out to
      * `temporal operator search-attribute list`.
      */
     probe?: (opts: {
@@ -35,15 +38,36 @@ export declare function defaultProbeRegisteredAttributes(opts: {
     temporalAddress: string;
     temporalNamespace: string;
 }): Promise<Set<string>>;
+/** Returns true if the address looks like a Temporal Cloud endpoint. */
+export declare function isTemporalCloud(address: string): boolean;
+/**
+ * SDK-based probe — uses the Temporal Client SDK to verify search attribute
+ * existence by issuing a visibility query. Works with Temporal Cloud API keys
+ * where the `temporal operator` CLI commands are unauthorized.
+ *
+ * Strategy: for each required attribute, issue `listWorkflowExecutions` with
+ * a query referencing that attribute. If the attribute is registered the query
+ * returns (possibly empty) results. If not registered, Temporal responds with
+ * INVALID_ARGUMENT containing "is not a valid search attribute".
+ */
+export declare function sdkProbeRegisteredAttributes(opts: {
+    temporalAddress: string;
+    temporalNamespace: string;
+    temporalApiKey?: string;
+}): Promise<Set<string>>;
 /**
  * Format the missing-SA error message. Paste-friendly: operators copy the
- * `temporal operator search-attribute create` block verbatim.
+ * registration commands verbatim. Cloud-aware: shows `tcld` commands for
+ * Temporal Cloud namespaces.
  */
-export declare function formatPreflightError(missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>, namespace: string, probeError?: string): string;
+export declare function formatPreflightError(missing: ReadonlyArray<typeof REQUIRED_SEARCH_ATTRIBUTES[number]>, namespace: string, probeError?: string, cloud?: boolean): string;
 /**
  * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
  * given namespace. Returns a structured result — callers decide whether
  * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ *
+ * When `temporalApiKey` is set (or address is a Cloud endpoint), uses the
+ * SDK-based probe instead of shelling out to `temporal operator`.
  */
 export declare function verifySearchAttributes(opts: SearchAttributePreflightOpts): Promise<SearchAttributePreflightResult>;
 /**

package/dist/cli/sa-preflight.js

@@ -1,7 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REQUIRED_SEARCH_ATTRIBUTES = void 0;
 exports.defaultProbeRegisteredAttributes = defaultProbeRegisteredAttributes;
+exports.isTemporalCloud = isTemporalCloud;
+exports.sdkProbeRegisteredAttributes = sdkProbeRegisteredAttributes;
 exports.formatPreflightError = formatPreflightError;
 exports.verifySearchAttributes = verifySearchAttributes;
 exports.classifyRegistrationOutput = classifyRegistrationOutput;
@@ -29,6 +64,16 @@ exports.assertSearchAttributesOrExit = assertSearchAttributesOrExit;
  *   - `src/daemon.ts` boot path calls {@link verifySearchAttributes}
  *     directly to fail fast on `agent-tempo daemon start` before the worker
  *     tries to register workflows.
+ *
+ * Cloud support:
+ *   Temporal Cloud's operator gRPC service is not accessible with namespace
+ *   API keys, causing `temporal operator search-attribute list/create` to
+ *   fail with "Request unauthorized". When a Cloud namespace is detected
+ *   (address contains `.tmprl.cloud` or an API key is configured), the
+ *   preflight uses an SDK-based probe: issue a visibility query referencing
+ *   each required attribute — a registered attribute returns an empty result
+ *   set; an unregistered one throws INVALID_ARGUMENT. Registration
+ *   instructions surface `tcld` commands instead of `temporal operator`.
  */
 const child_process_1 = require("child_process");
 /** Single source of truth — must match `SEARCH_ATTRIBUTES` in `src/cli/startup.ts`. */
@@ -73,22 +118,123 @@ async function defaultProbeRegisteredAttributes(opts) {
     }
     return names;
 }
+/** Returns true if the address looks like a Temporal Cloud endpoint. */
+function isTemporalCloud(address) {
+    return address.includes('.tmprl.cloud');
+}
+/**
+ * Substrings Temporal servers use to signal "this search attribute is not
+ * registered". The exact wording varies across server versions and storage
+ * backends (e.g. 'is not a valid search attribute', 'is not defined',
+ * 'no mapping defined for the field'), so we match a set rather than a
+ * single phrase — a wording change must not cause the probe to misclassify
+ * an unregistered SA as an unexpected error and re-throw.
+ */
+const UNREGISTERED_SA_MARKERS = [
+    'is not a valid search attribute',
+    'is not defined',
+    'no mapping defined for the field',
+    'unknown or unindexed search attribute',
+];
+/** gRPC status code for INVALID_ARGUMENT. */
+const GRPC_INVALID_ARGUMENT = 3;
+/**
+ * Classify a visibility-query error as "search attribute not registered".
+ *
+ * A registered-but-empty attribute returns results; an unregistered one
+ * fails. Temporal reports the failure as gRPC INVALID_ARGUMENT — we key on
+ * that status code first (wording-independent) and fall back to known
+ * message substrings for transports/versions that don't surface a code.
+ */
+function isUnregisteredAttributeError(err) {
+    const msg = (err?.message || '').toLowerCase();
+    if (UNREGISTERED_SA_MARKERS.some((m) => msg.includes(m)))
+        return true;
+    // gRPC ServiceError exposes a numeric `code`; INVALID_ARGUMENT means the
+    // query referenced an attribute the namespace doesn't know about.
+    if (err?.code === GRPC_INVALID_ARGUMENT)
+        return true;
+    return false;
+}
+/**
+ * SDK-based probe — uses the Temporal Client SDK to verify search attribute
+ * existence by issuing a visibility query. Works with Temporal Cloud API keys
+ * where the `temporal operator` CLI commands are unauthorized.
+ *
+ * Strategy: for each required attribute, issue `listWorkflowExecutions` with
+ * a query referencing that attribute. If the attribute is registered the query
+ * returns (possibly empty) results. If not registered, Temporal responds with
+ * INVALID_ARGUMENT containing "is not a valid search attribute".
+ */
+async function sdkProbeRegisteredAttributes(opts) {
+    const { Connection } = await Promise.resolve().then(() => __importStar(require('@temporalio/client')));
+    const tls = opts.temporalApiKey ? true : undefined;
+    const conn = await Connection.connect({
+        address: opts.temporalAddress,
+        tls: tls,
+        apiKey: opts.temporalApiKey,
+    });
+    const registered = new Set();
+    try {
+        for (const attr of exports.REQUIRED_SEARCH_ATTRIBUTES) {
+            // The probe value only has to be syntactically valid for the
+            // attribute's type so the visibility query parses. We support
+            // Keyword (quoted string literal) and Bool (`true`) here — the only
+            // two types in REQUIRED_SEARCH_ATTRIBUTES. A new SA type would need
+            // its own literal form added below.
+            const testValue = attr.type === 'Bool' ? 'true' : '"__probe__"';
+            try {
+                await conn.workflowService.listWorkflowExecutions({
+                    namespace: opts.temporalNamespace,
+                    query: `${attr.name} = ${testValue}`,
+                    pageSize: 1,
+                });
+                registered.add(attr.name);
+            }
+            catch (err) {
+                if (isUnregisteredAttributeError(err)) {
+                    // Attribute not registered — don't add to set
+                }
+                else {
+                    // Unexpected error — re-throw
+                    throw err;
+                }
+            }
+        }
+    }
+    finally {
+        await conn.close();
+    }
+    return registered;
+}
 /**
  * Format the missing-SA error message. Paste-friendly: operators copy the
- * `temporal operator search-attribute create` block verbatim.
+ * registration commands verbatim. Cloud-aware: shows `tcld` commands for
+ * Temporal Cloud namespaces.
  */
-function formatPreflightError(missing, namespace, probeError) {
+function formatPreflightError(missing, namespace, probeError, cloud) {
     const lines = [];
     lines.push(`Required search attributes not registered on namespace '${namespace}'.`);
     if (probeError) {
         lines.push(`(Could not probe namespace state: ${probeError})`);
     }
     lines.push('');
-    lines.push('Run these commands once per Temporal namespace, then restart the daemon:');
-    lines.push('');
-    for (const attr of missing) {
-        lines.push(`  temporal operator search-attribute create ` +
-            `--name ${attr.name} --type ${attr.type} --namespace ${namespace}`);
+    if (cloud) {
+        lines.push('Register via tcld (Temporal Cloud CLI) or the Cloud UI, then restart the daemon:');
+        lines.push('');
+        const saFlags = missing.map((attr) => `--sa "${attr.name}=${attr.type}"`).join(' \\\n    ');
+        lines.push(`  tcld namespace search-attributes add --namespace ${namespace} \\\n    ${saFlags}`);
+        lines.push('');
+        lines.push('Or add them manually in the Temporal Cloud UI:');
+        lines.push(`  https://cloud.temporal.io → Namespaces → ${namespace} → Search Attributes`);
+    }
+    else {
+        lines.push('Run these commands once per Temporal namespace, then restart the daemon:');
+        lines.push('');
+        for (const attr of missing) {
+            lines.push(`  temporal operator search-attribute create ` +
+                `--name ${attr.name} --type ${attr.type} --namespace ${namespace}`);
+        }
     }
     lines.push('');
     lines.push('(See docs/ops/v1.0-migration.md for the full upgrade walkthrough.)');
@@ -98,9 +244,23 @@ function formatPreflightError(missing, namespace, probeError) {
  * Verify all {@link REQUIRED_SEARCH_ATTRIBUTES} are registered on the
  * given namespace. Returns a structured result — callers decide whether
  * to log+continue (boot bootstrap step) or exit non-zero (daemon start).
+ *
+ * When `temporalApiKey` is set (or address is a Cloud endpoint), uses the
+ * SDK-based probe instead of shelling out to `temporal operator`.
  */
 async function verifySearchAttributes(opts) {
-    const probe = opts.probe ?? defaultProbeRegisteredAttributes;
+    const cloud = isTemporalCloud(opts.temporalAddress) || !!opts.temporalApiKey;
+    const defaultProbe = cloud
+        ? () => sdkProbeRegisteredAttributes({
+            temporalAddress: opts.temporalAddress,
+            temporalNamespace: opts.temporalNamespace,
+            temporalApiKey: opts.temporalApiKey,
+        })
+        : () => defaultProbeRegisteredAttributes({
+            temporalAddress: opts.temporalAddress,
+            temporalNamespace: opts.temporalNamespace,
+        });
+    const probe = opts.probe ?? defaultProbe;
     let registered;
     let probeError;
     try {
@@ -121,7 +281,7 @@ async function verifySearchAttributes(opts) {
         ok: false,
         missing,
         probeError,
-        message: formatPreflightError(missing, opts.temporalNamespace, probeError),
+        message: formatPreflightError(missing, opts.temporalNamespace, probeError, cloud),
     };
 }
 /**

package/dist/cli/startup.js

@@ -134,6 +134,7 @@ const TTL_60S = 60 * 1000;
 // (#605 consolidated the two duplicated literals).
 // ─────────────────────────────────────────────────────────────────────────
 const sa_preflight_1 = require("./sa-preflight");
+const global_wrapper_1 = require("./global-wrapper");
 // ─────────────────────────────────────────────────────────────────────────
 // Semver-aware outdated-version badge rendering (#289 pin item 4)
 // ─────────────────────────────────────────────────────────────────────────
@@ -376,14 +377,40 @@ async function stepSearchAttrs(cache, config, now) {
     if (isCacheFresh(cache.steps.searchAttrs, TTL_24H, now)) {
         return { status: 'skipped', durationMs: 0 };
     }
-    const { result: outcome, durationMs } = await timed(() => {
-        // Per-attr classification via `registerSearchAttribute` (#605) —
-        // distinguishes `already-exists` (idempotent expected case) from real
-        // failures. Pre-#605 every non-zero exit was swallowed as "already
-        // registered", masking the SQLite dev-server's 10-Keyword-per-namespace
-        // cap and other genuine errors until a downstream workflow start failed
-        // with the confusing `INVALID_ARGUMENT: search attribute ... is not
-        // defined`.
+    const cloud = (0, sa_preflight_1.isTemporalCloud)(config.temporalAddress) || !!config.temporalApiKey;
+    const { result: outcome, durationMs } = await timed(async () => {
+        if (cloud) {
+            // For Temporal Cloud, use SDK probe to verify SAs are present.
+            // Registration must be done via tcld or the Cloud UI — we cannot
+            // use `temporal operator search-attribute create`.
+            try {
+                const registered = await (0, sa_preflight_1.sdkProbeRegisteredAttributes)({
+                    temporalAddress: config.temporalAddress,
+                    temporalNamespace: config.temporalNamespace,
+                    temporalApiKey: config.temporalApiKey,
+                });
+                const missing = sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES.filter((a) => !registered.has(a.name));
+                if (missing.length > 0) {
+                    const saFlags = missing.map((a) => `--sa "${a.name}=${a.type}"`).join(' ');
+                    return {
+                        status: 'failed',
+                        durationMs: 0,
+                        detail: `${missing.length} search attribute(s) not registered on Temporal Cloud.\n` +
+                            `  Register via: tcld namespace search-attributes add --namespace ${config.temporalNamespace} ${saFlags}\n` +
+                            `  Or add them in the Cloud UI: https://cloud.temporal.io`,
+                    };
+                }
+                return { status: 'ok', durationMs: 0 };
+            }
+            catch (err) {
+                return {
+                    status: 'failed',
+                    durationMs: 0,
+                    detail: `SDK probe failed: ${err?.message || err}`,
+                };
+            }
+        }
+        // Self-hosted path: per-attr classification via `registerSearchAttribute` (#605)
         const failures = [];
         for (const attr of sa_preflight_1.REQUIRED_SEARCH_ATTRIBUTES) {
             const r = (0, sa_preflight_1.registerSearchAttribute)(attr, config.temporalAddress, config.temporalNamespace);
@@ -598,6 +625,16 @@ async function bootstrap(args) {
     // Steps 1–5: fail-fast on step 1 so we don't try to register MCP on an
     // incompatible Node. Each step mutates the cache in-place.
     const preflight = await stepPreflight(cache, now);
+    // Provision the global wrapper scripts (`~/.agent-tempo/bin/agent-tempo`)
+    // so the command is accessible without `npx`. Runs once per binary version
+    // (guarded by cache wipe on version change). Best-effort, non-blocking.
+    if (preflight.status !== 'failed') {
+        const { needsPathHint } = (0, global_wrapper_1.provisionWrapperScripts)();
+        if (needsPathHint) {
+            // Emit a one-time hint to stderr (won't pollute --json output).
+            process.stderr.write(`\n  hint: ${(0, global_wrapper_1.getPathHint)()}\n\n`);
+        }
+    }
     // Steps 2 + 3 are independent (MCP config is local fs/shell; Temporal
     // reachability is network), so run them in parallel — up to ~300ms
     // cold-path savings when the claude-mcp-list shell-out is slow.