@alter-ai/cli 0.9.0 → 0.9.1

package/dist/cli.js

@@ -33,7 +33,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.9.0",
+  version: "0.9.1",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -44,7 +44,8 @@ var package_default = {
     "dist",
     "README.md",
     "LICENSE",
-    "THIRD_PARTY_NOTICES"
+    "THIRD_PARTY_NOTICES",
+    "npm-shrinkwrap.json"
   ],
   scripts: {
     build: "tsup",
@@ -69,14 +70,17 @@ var package_default = {
   author: "Alter Labs, Inc.",
   license: "MIT",
   dependencies: {
-    commander: "^12.0.0",
-    "posthog-node": "^4.18.0"
+    commander: "12.1.0",
+    "posthog-node": "4.18.0"
   },
   optionalDependencies: {
-    keytar: "^7.9.0"
+    keytar: "7.9.0"
+  },
+  overrides: {
+    esbuild: "0.28.1"
   },
   devDependencies: {
-    "@alter-ai/alter-sdk": "workspace:0.24.0",
+    "@alter-ai/alter-sdk": "workspace:0.24.2",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",
@@ -6255,7 +6259,11 @@ var ConnectResult = class {
   providerId;
   accountIdentifier;
   scopes;
-  /** Ordinary Connect completion or in-place repair of a broken grant. */
+  /**
+   * "creation" when a new grant was minted; "reauth" when an existing
+   * grant was returned with its id preserved (credential repair, or reuse
+   * of an already-connected grant).
+   */
   operation;
   grantPolicy;
   /**
@@ -8143,7 +8151,7 @@ async function _raiseForStatus(response) {
   if (code === AgentConcurrentUpdateError.code && response.status === 409) {
     throw new AgentConcurrentUpdateError({ message, details: body, hint });
   }
-  const ExcCtor = ERROR_CODE_STATUS_MAP[`${code}:${response.status}`] ?? ERROR_CODE_MAP[code];
+  const ExcCtor = ERROR_CODE_STATUS_MAP[`${code}:${response.status}`] ?? (Object.hasOwn(ERROR_CODE_MAP, code) ? ERROR_CODE_MAP[code] : void 0);
   if (ExcCtor !== void 0) {
     throw new ExcCtor({ message, details: body, hint });
   }
@@ -10172,7 +10180,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.24.0";
+var SDK_VERSION = "0.24.2";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 function pyUnquote(s) {
   if (!s.includes("%")) return s;
@@ -10243,8 +10251,12 @@ function canonicalSigningQuery(rawQuery) {
   pairs.sort((p, q) => byCodePoint(p[0], q[0]) || byCodePoint(p[1], q[1]));
   return pairs.map(([k, v]) => `${pyQuotePlus(k)}=${pyQuotePlus(v)}`).join("&");
 }
+var DEFAULT_TIMEOUT_MS = 95e3;
+var _ApprovalDeadlineElapsed = class extends Error {
+};
 var AUTH_POLL_SERVER_WAIT_MS = 25e3;
 var AUTH_POLL_HTTP_BUFFER_MS = 15e3;
+var APPROVAL_POLL_SERVER_WAIT_MS = 25e3;
 var PERMANENT_POLL_STATUSES = /* @__PURE__ */ new Set([400, 401, 403, 404, 422]);
 var HTTP_FORBIDDEN = 403;
 var HTTP_NO_CONTENT2 = 204;
@@ -10520,6 +10532,23 @@ function validateAndSerializeContext(context) {
   return encoded;
 }
 var MAX_BODY_SIZE_BYTES = 1e4;
+var AUDIT_REFUSAL_BODY_MAX_CHARS = 65536;
+var REFUSAL_MESSAGE_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+var REFUSAL_MESSAGE_MAX_CHARS = 300;
+function sanitizeRefusalMessage(message) {
+  const cleaned = message.replace(REFUSAL_MESSAGE_CONTROL_CHARS, " ");
+  return cleaned.length > REFUSAL_MESSAGE_MAX_CHARS ? `${cleaned.slice(0, REFUSAL_MESSAGE_MAX_CHARS)}\u2026` : cleaned;
+}
+function _redactUrlForLog(url2) {
+  try {
+    const parsed = new URL(url2);
+    if (parsed.protocol && parsed.hostname) {
+      return `${parsed.protocol}//${parsed.hostname}`;
+    }
+  } catch {
+  }
+  return "<unparseable-url>";
+}
 var HTTP_CLIENT_ERROR_START = 400;
 var MAX_ACTOR_STRING_LENGTH = 255;
 var SAFE_HEADER_PATTERN = /^[\x20-\x7E]+$/;
@@ -10808,6 +10837,16 @@ var HttpClient = class {
         new DOMException("The operation timed out.", "TimeoutError")
       );
     }, effectiveTimeoutMs);
+    const callerSignal = options?.signal;
+    let onCallerAbort;
+    if (callerSignal !== void 0) {
+      if (callerSignal.aborted) {
+        controller.abort(callerSignal.reason);
+      } else {
+        onCallerAbort = () => controller.abort(callerSignal.reason);
+        callerSignal.addEventListener("abort", onCallerAbort);
+      }
+    }
     const init = {
       method,
       headers: mergedHeaders,
@@ -10846,6 +10885,9 @@ var HttpClient = class {
       return response;
     } finally {
       clearTimeout(timeoutId);
+      if (callerSignal !== void 0 && onCallerAbort !== void 0) {
+        callerSignal.removeEventListener("abort", onCallerAbort);
+      }
     }
   }
   /**
@@ -10958,7 +11000,7 @@ var _VaultClient = class __VaultClient {
       unresolvedBaseUrl,
       options.logger ?? console
     );
-    const timeoutMs = options.timeout ?? 3e4;
+    const timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.#caller = options.caller;
     const rawCallerType = options.callerType ?? "agent";
     if (rawCallerType !== "agent" && rawCallerType !== "service") {
@@ -12163,9 +12205,34 @@ ${label}:${value}`;
       });
       this.#cacheActorIdFromResponse(response);
       if (!response.ok) {
+        let detail = "";
+        try {
+          const raw = await response.text();
+          if (raw.length <= AUDIT_REFUSAL_BODY_MAX_CHARS) {
+            const body = JSON.parse(raw);
+            let message = body.message;
+            if (typeof message !== "string" || message === "") {
+              const inner = body.detail;
+              if (typeof inner === "string") {
+                message = inner;
+              } else if (inner !== null && typeof inner === "object") {
+                message = inner.message;
+              }
+            }
+            if (typeof message === "string" && message !== "") {
+              detail = `: ${sanitizeRefusalMessage(message)}`;
+            }
+          }
+        } catch {
+        }
         this.#logger.warn(
-          `Audit log failed with status ${response.status} (non-fatal)`
+          `Audit log failed with status ${response.status} (non-fatal)${detail} \u2014 this call's api-call audit row was not recorded (grant_id=${params.grantId}, method=${params.method}, url=${_redactUrlForLog(params.url)})`
         );
+      } else {
+        try {
+          await response.arrayBuffer();
+        } catch {
+        }
       }
     } catch (error51) {
       this.#logger.warn(
@@ -12676,7 +12743,7 @@ ${label}:${value}`;
         headers: hmacHeaders,
         // Cap the best-effort background report at 2s (parity with the Python
         // SDK's asyncio.wait_for). Without an override it would inherit the
-        // instance timeout (default 30s), so a hung backend could keep the
+        // instance timeout (default 95s), so a hung backend could keep the
         // fire-and-forget task — and close()'s drain of it — alive far longer
         // than the Python SDK does. Next provider 403 re-reports (self-healing).
         timeoutMs: 2e3
@@ -13053,8 +13120,11 @@ ${label}:${value}`;
    * @param options - Optional revocation options (reason for audit log).
    * @returns RevokeGrantResult confirming the revocation.
    * @throws {GrantNotFoundError} If the grant does not exist, is not
-   *   active, or (when a user token is configured) does not belong to
-   *   the calling user.
+   *   active, (when a user token is configured) does not belong to
+   *   the calling user, or — when this client holds an AGENT key — is
+   *   not a grant the agent is the principal of (its own delegation or
+   *   an agent-owned grant). An allowlist entry for the grant's provider
+   *   is never enough.
    * @throws {NetworkError} If connection to backend fails.
    * @throws {TimeoutError} If request to backend times out.
    */
@@ -13865,14 +13935,17 @@ ${label}:${value}`;
    * @returns One `ConnectResult` per provider the user completed
    *     within the session (multi-provider Connect sessions yield
    *     multiple results).
-   * @throws AlterValueError if `sessionToken` is blank, or `timeoutMs` /
-   *     `pollIntervalMs` is non-finite or not greater than zero.
+   * @throws AlterValueError if `sessionToken` is blank, `timeoutMs` /
+   *     `pollIntervalMs` is non-finite or not greater than zero, or
+   *     `onEvent` is provided but not a function.
    * @throws ConnectTimeoutError if the local `timeoutMs` elapses, or a
    *     session observed as pending expires before Alter receives a
    *     completion callback. `details.reason` distinguishes
    *     `poll_deadline_elapsed`, `session_expired`, and `rate_limited` (the
    *     whole budget was spent backing off a throttled poll —
-   *     `details.retryAfter` carries the last hint the server gave).
+   *     `details.retryAfter` carries the last hint the server gave). When
+   *     denials were observed before the timeout,
+   *     `details.declined_providers` lists them on EVERY variant.
    * @throws ConnectFlowError / ConnectDeniedError / ConnectConfigError
    *     for user denial, a first poll that finds an unavailable/expired
    *     session, unrecognized status, or a completed session whose every grant
@@ -13892,8 +13965,18 @@ ${label}:${value}`;
     const timeoutMs = options?.timeoutMs ?? 3e5;
     const pollIntervalMs = options?.pollIntervalMs ?? 2e3;
     validatePollingInputs(sessionToken, timeoutMs, pollIntervalMs);
+    if (options?.onEvent !== void 0 && typeof options.onEvent !== "function") {
+      throw new AlterValueError("onEvent must be a function when provided");
+    }
     const deadline = performance.now() + timeoutMs;
     let sawPending = false;
+    const seenDeclinedProviders = /* @__PURE__ */ new Set();
+    const withDeclined = (base) => {
+      if (seenDeclinedProviders.size > 0) {
+        base.declined_providers = [...seenDeclinedProviders].sort();
+      }
+      return base;
+    };
     while (true) {
       this.#assertNotClosed();
       let pollResult;
@@ -13907,11 +13990,11 @@ ${label}:${value}`;
         if (remaining2 <= 0) {
           throw new ConnectTimeoutError(
             `OAuth flow did not complete within ${Math.round(timeoutMs / 1e3)} seconds: polling was rate-limited for the remainder of the budget. The authorization may still have succeeded \u2014 retry the poll with a fresh timeout, or raise the API key's per-minute rate limit if Connect flows run concurrently.`,
-            {
+            withDeclined({
               timeoutMs,
               reason: "rate_limited",
               retryAfter: e.retryAfter
-            }
+            })
           );
         }
         let backoffMs = pollIntervalMs;
@@ -14044,7 +14127,10 @@ ${label}:${value}`;
         ].includes(errorCode)) {
           throw new ConnectConfigError(errorMessage, errorDetails);
         }
-        const identitySyncStatus = IDENTITY_SYNC_POLL_STATUS[errorCode];
+        const identitySyncStatus = Object.hasOwn(
+          IDENTITY_SYNC_POLL_STATUS,
+          errorCode
+        ) ? IDENTITY_SYNC_POLL_STATUS[errorCode] : void 0;
         if (identitySyncStatus !== void 0) {
           throw new BackendError(
             errorMessage,
@@ -14058,7 +14144,7 @@ ${label}:${value}`;
         if (sawPending) {
           throw new ConnectTimeoutError(
             "Connect session expired before authorization returned to Alter. The provider may have shown an error without redirecting, the browser may have been closed, or the user may not have completed the flow.",
-            { timeoutMs, reason: "session_expired" }
+            withDeclined({ timeoutMs, reason: "session_expired" })
           );
         }
         throw new ConnectFlowError(
@@ -14071,6 +14157,46 @@ ${label}:${value}`;
           { status: pollStatus }
         );
       }
+      const rawDeclined = pollResult.declined_providers;
+      if (Array.isArray(rawDeclined)) {
+        for (const entry of rawDeclined) {
+          if (entry === null || typeof entry !== "object") continue;
+          const declinedProvider = entry.provider_id;
+          if (typeof declinedProvider !== "string" || declinedProvider === "") {
+            continue;
+          }
+          const rawCode = entry.error_code;
+          if (typeof rawCode !== "string" || rawCode === "") continue;
+          if (seenDeclinedProviders.has(declinedProvider)) continue;
+          seenDeclinedProviders.add(declinedProvider);
+          if (!options?.onEvent) continue;
+          const rawDeclinedAt = entry.declined_at;
+          const logCallbackFailure = (error51) => {
+            this.#logger.warn(
+              "pollConnectSession onEvent callback threw (non-fatal)",
+              {
+                provider_id: declinedProvider,
+                error_type: error51 instanceof Error ? error51.constructor.name : typeof error51
+              }
+            );
+          };
+          try {
+            const result = options.onEvent({
+              type: "provider_declined",
+              provider_id: declinedProvider,
+              error_code: rawCode,
+              declined_at: typeof rawDeclinedAt === "string" ? rawDeclinedAt : null
+            });
+            if (result !== null && (typeof result === "object" || typeof result === "function") && typeof result.then === "function") {
+              void Promise.resolve(result).catch(
+                logCallbackFailure
+              );
+            }
+          } catch (error51) {
+            logCallbackFailure(error51);
+          }
+        }
+      }
       sawPending = true;
       const remaining = deadline - performance.now();
       if (remaining <= 0) break;
@@ -14080,7 +14206,7 @@ ${label}:${value}`;
     }
     throw new ConnectTimeoutError(
       `OAuth flow did not complete within ${Math.round(timeoutMs / 1e3)} seconds. Alter did not receive a completion callback; the provider may have shown an error without redirecting, the browser may have been closed, or the user may not have finished authorizing.`,
-      { timeoutMs, reason: "poll_deadline_elapsed" }
+      withDeclined({ timeoutMs, reason: "poll_deadline_elapsed" })
     );
   }
   /**
@@ -14333,7 +14459,10 @@ ${label}:${value}`;
           const errorMessage = typeof pollData.error_message === "string" && pollData.error_message ? pollData.error_message : "unknown error";
           const message = `Authentication failed: ${errorMessage}`;
           const syncCode = typeof pollData.error_code === "string" ? pollData.error_code : "";
-          const identitySyncStatus = IDENTITY_SYNC_POLL_STATUS[syncCode];
+          const identitySyncStatus = Object.hasOwn(
+            IDENTITY_SYNC_POLL_STATUS,
+            syncCode
+          ) ? IDENTITY_SYNC_POLL_STATUS[syncCode] : void 0;
           if (identitySyncStatus !== void 0) {
             const details = { error_code: syncCode };
             const retryAfter = _coerceInt(pollData.retry_after_seconds);
@@ -14958,10 +15087,34 @@ ${label}:${value}`;
       error: errCode
     });
   }
-  /** Single-shot poll of an approval. */
-  async getApprovalStatus(approvalId) {
+  /**
+   * Single-shot poll of an approval.
+   *
+   * `wait` asks the server to hold the request open until the approval's
+   * status changes, up to that many seconds (0 = return immediately, the
+   * default and the historical behaviour). It is a pure latency optimisation:
+   * the response shape is identical either way, and a backend that predates
+   * the parameter simply ignores it and answers immediately. The server caps
+   * `wait` at 25 seconds (`APPROVAL_POLL_SERVER_WAIT_MS`, mirroring the
+   * backend's `MAX_LONG_POLL_SECONDS`) and REJECTS larger values with a
+   * validation error (422) rather than clamping them.
+   *
+   * `signal` (internal — not exposed on App/Agent) lets `awaitApproval` abort
+   * an in-flight held request its local deadline has abandoned.
+   *
+   * @throws AlterValueError if `wait` is not a finite number.
+   */
+  async getApprovalStatus(approvalId, options = {}) {
     this.#assertNotClosed();
-    const sdkPath = `/sdk/approvals/${approvalId}`;
+    if (options !== null && options !== void 0 && typeof options !== "object") {
+      throw new AlterValueError("options must be an object");
+    }
+    const waitOption = options?.wait ?? 0;
+    if (typeof waitOption !== "number" || !Number.isFinite(waitOption)) {
+      throw new AlterValueError("wait must be a finite number");
+    }
+    const wait = Math.max(0, Math.floor(waitOption));
+    const sdkPath = wait > 0 ? `/sdk/approvals/${approvalId}?wait=${wait}` : `/sdk/approvals/${approvalId}`;
     const hmacHeaders = this.#computeHmacHeaders("GET", sdkPath, "");
     const traceparent = await ambientTraceparent();
     if (traceparent !== void 0) {
@@ -14970,7 +15123,18 @@ ${label}:${value}`;
     let response;
     try {
       response = await this.#alterClient.request("GET", sdkPath, {
-        headers: hmacHeaders
+        headers: hmacHeaders,
+        // A held request needs a wider per-request timeout than the client
+        // default, or the client aborts its own long-poll (see
+        // AUTH_POLL_HTTP_BUFFER_MS). Only applied when actually parking.
+        // Capped at the server's own ceiling: `wait` is deliberately NOT
+        // clamped on the wire (the backend owns that contract and answers an
+        // over-cap value with its documented validation error), but an
+        // unbounded `wait * 1000` overflows to `Infinity` for a huge finite
+        // value, and Node coerces such a timer to fire almost immediately —
+        // aborting the request before that very error can come back.
+        timeoutMs: wait > 0 ? Math.min(wait * 1e3, APPROVAL_POLL_SERVER_WAIT_MS) + AUTH_POLL_HTTP_BUFFER_MS : void 0,
+        signal: options?.signal
       });
     } catch (error51) {
       if (error51 instanceof Error && error51.name === "AbortError") {
@@ -15041,9 +15205,39 @@ ${label}:${value}`;
         throw this.#buildApprovalTimeout(approvalId, timeoutMs, lastTransient);
       }
       let status;
+      const raceController = new AbortController();
+      let deadlineTimer;
       try {
-        status = await this.getApprovalStatus(approvalId);
+        const serverWaitSeconds = Math.max(
+          0,
+          Math.min(
+            Math.floor(APPROVAL_POLL_SERVER_WAIT_MS / 1e3),
+            Math.floor((deadline - Date.now()) / 1e3)
+          )
+        );
+        const remainingMs = Math.max(0, deadline - Date.now());
+        status = await Promise.race([
+          this.getApprovalStatus(approvalId, {
+            wait: serverWaitSeconds,
+            signal: raceController.signal
+          }),
+          new Promise((_resolve, reject) => {
+            deadlineTimer = setTimeout(
+              () => reject(new _ApprovalDeadlineElapsed()),
+              remainingMs
+            );
+            deadlineTimer.unref?.();
+          })
+        ]);
       } catch (err2) {
+        if (err2 instanceof _ApprovalDeadlineElapsed) {
+          raceController.abort();
+          throw this.#buildApprovalTimeout(
+            approvalId,
+            timeoutMs,
+            lastTransient
+          );
+        }
         if (!__VaultClient.#isTransientPollError(err2)) {
           throw err2;
         }
@@ -15065,6 +15259,8 @@ ${label}:${value}`;
         );
         await new Promise((res) => setTimeout(res, sleep2));
         continue;
+      } finally {
+        if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
       }
       lastTransient = null;
       if (status.status === "executed" && !status.hasResult) {
@@ -15880,8 +16076,8 @@ var Agent = class _Agent {
     return this.#client.delegate(grantId, toAgentId, options);
   }
   // ── Approvals ──────────────────────────────────────────────────────────
-  async getApprovalStatus(approvalId) {
-    return this.#client.getApprovalStatus(approvalId);
+  async getApprovalStatus(approvalId, options = {}) {
+    return this.#client.getApprovalStatus(approvalId, options);
   }
   async awaitApproval(...args) {
     return this.#client.awaitApproval(...args);
@@ -16301,8 +16497,8 @@ var App = class _App {
     });
   }
   // ── Approvals ──────────────────────────────────────────────────────────
-  async getApprovalStatus(approvalId) {
-    return this.#client.getApprovalStatus(approvalId);
+  async getApprovalStatus(approvalId, options = {}) {
+    return this.#client.getApprovalStatus(approvalId, options);
   }
   async awaitApproval(...args) {
     return this.#client.awaitApproval(...args);
@@ -16558,8 +16754,8 @@ async function _listGrantsUnified(client, body) {
 var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
-var DEFAULT_TIMEOUT_MS = 3e4;
-var CLI_VERSION = "0.9.0";
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var CLI_VERSION = "0.9.1";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -16804,7 +17000,7 @@ var DashboardClient = class {
         );
       }
     }
-    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
     this.pats = new PATsNamespace(this);
     this.apps = new AppsNamespace(this);
     this.keys = new KeysNamespace2(this);
@@ -19535,6 +19731,38 @@ function resolveAppId(flagValue, options = {}) {
   return null;
 }
 
+// ../shared-utils/src/dns-host.ts
+var LABEL_SEPARATOR = /[.。．｡]/;
+var TRAILING_LABEL_SEPARATOR = /[.。．｡]$/;
+var isInvalidLabel = (label) => label.length === 0 || label.includes("_") || label.startsWith("-") || label.endsWith("-") || label.length >= 4 && label[2] === "-" && label[3] === "-" && !label.startsWith("xn--");
+var IDNA2008_LABEL = /^(?:(?!\u0640|\u07FA|\u302E|\u302F|[\u3031-\u3035]|\u303B)[\p{L}\p{Mn}\p{Mc}\p{Nd}\-\u00DF\u03C2\u06FD\u06FE\u0F0B\u3007\u00B7\u0375\u05F3\u05F4\u30FB]|\u200C|\u200D)*$/u;
+var isOutsideIdna2008Repertoire = (label) => !IDNA2008_LABEL.test(label);
+var canonicalizeDnsHost = (host) => {
+  let h = host;
+  if (!/^[\x20-\x7e]*$/.test(h)) {
+    if (/[/:@\s?#%\\]/.test(h)) return null;
+    const uLabels = h.normalize("NFKC").replace(TRAILING_LABEL_SEPARATOR, "").split(LABEL_SEPARATOR);
+    if (uLabels.some(isInvalidLabel)) return null;
+    if (uLabels.some(isOutsideIdna2008Repertoire)) return null;
+    let url2;
+    try {
+      url2 = new URL(`http://${h}`);
+    } catch {
+      return null;
+    }
+    if (url2.pathname !== "/" || url2.search !== "" || url2.hash !== "" || url2.port !== "" || url2.username !== "" || url2.password !== "") {
+      return null;
+    }
+    h = url2.hostname;
+    if (!/^[\x20-\x7e]*$/.test(h)) return null;
+    h = h.replace(/\.$/, "");
+    if (h.split(".").some(isInvalidLabel)) return null;
+  }
+  if (h.length > 253) return null;
+  if (h.split(".").some((label) => label.length > 63)) return null;
+  return h;
+};
+
 // src/commands/_helpers.ts
 async function withClient(fn) {
   const client = await createPortalClient();
@@ -20087,9 +20315,9 @@ function parseAllowedHostsOrExit(flag, entries) {
         fail(`${JSON.stringify(entry)} must not contain control characters`);
       }
     }
-    if (/[/:@\s]/.test(e)) {
+    if (/[/:@\s?#%\\]/.test(e)) {
       fail(
-        `${JSON.stringify(entry)} must be a bare host \u2014 no scheme, port, path, or "@"`
+        `${JSON.stringify(entry)} must be a bare host \u2014 no scheme, port, path, "@", whitespace, or the URL delimiters ? # % \\`
       );
     }
     let normalized;
@@ -20100,12 +20328,23 @@ function parseAllowedHostsOrExit(flag, entries) {
           `${JSON.stringify(entry)} is a malformed wildcard \u2014 use "*.domain.tld"`
         );
       }
-      if (!rest.includes(".")) {
+      const canonicalRest = canonicalizeDnsHost(rest);
+      if (canonicalRest === null) {
+        fail(
+          `${JSON.stringify(entry)} is not a valid DNS name (IDNA-encodable, labels up to 63 characters)`
+        );
+      }
+      if (!canonicalRest.includes(".")) {
         fail(
           `${JSON.stringify(entry)}: wildcard must cover a domain, not a bare TLD (use "*.example.com", not "*.com")`
         );
       }
-      normalized = `*.${rest}`;
+      if (canonicalRest.length > 251) {
+        fail(
+          `${JSON.stringify(entry)} is too long for a wildcard \u2014 no host could ever match it`
+        );
+      }
+      normalized = `*.${canonicalRest}`;
     } else if (e.includes("*")) {
       fail(
         `${JSON.stringify(entry)}: "*" is only allowed as a leading subdomain wildcard ("*.domain.tld")`
@@ -20114,9 +20353,16 @@ function parseAllowedHostsOrExit(flag, entries) {
       normalized = e.replace(/\.+$/, "");
       if (!normalized) {
         fail(
-          `${JSON.stringify(entry)} must be a bare host \u2014 no scheme, port, path, or "@"`
+          `${JSON.stringify(entry)} must be a bare host \u2014 no scheme, port, path, "@", whitespace, or the URL delimiters ? # % \\`
+        );
+      }
+      const canonical = canonicalizeDnsHost(normalized);
+      if (canonical === null) {
+        fail(
+          `${JSON.stringify(entry)} is not a valid DNS name (IDNA-encodable, labels up to 63 characters)`
         );
       }
+      normalized = canonical;
     }
     if (seen.has(normalized)) continue;
     seen.add(normalized);
@@ -20372,6 +20618,20 @@ function surfaceCatalogWarnings(row) {
     );
   }
 }
+function surfaceScopeWarnings(row) {
+  if (typeof row !== "object" || row === null) return;
+  const warnings = row.scope_warnings;
+  if (!Array.isArray(warnings)) return;
+  for (const warning of warnings) {
+    if (typeof warning !== "string") continue;
+    const sanitized = sanitizeStderrText(warning);
+    if (sanitized.length === 0) continue;
+    process.stderr.write(
+      `alter: scope warning \u2014 ${sanitized} (save was allowed)
+`
+    );
+  }
+}
 function writeNextPageHint(page, noun) {
   if (typeof page !== "object" || page === null) return;
   const { has_more: hasMore, offset, limit } = page;
@@ -20566,6 +20826,7 @@ function buildAgentsCommand() {
             "alter: the api_key field above is shown ONCE and cannot be retrieved later.\n"
           );
           surfaceApproverWarnings(result);
+          surfaceScopeWarnings(result);
         });
         return;
       }
@@ -20621,6 +20882,7 @@ function buildAgentsCommand() {
           "alter: the api_key field above is shown ONCE and cannot be retrieved later.\n"
         );
         surfaceApproverWarnings(result);
+        surfaceScopeWarnings(result);
       });
     }
   );
@@ -20840,6 +21102,7 @@ function buildAgentsCommand() {
             }
           );
           emit2(format, row);
+          surfaceScopeWarnings(row);
         } catch (error51) {
           if (error51 instanceof PortalBackendError && error51.statusCode === 409 && error51.code === "agent_concurrent_update") {
             throw new PortalBackendError(
@@ -35908,7 +36171,7 @@ var RULE_TYPE_LABELS = /* @__PURE__ */ new Map([
   ["json_match", "Request condition"],
   ["ip_allowlist", "IP allowlist"],
   ["time_window", "Time window"],
-  ["require_approval", "Require approval"],
+  ["require_approval", "Human in the loop (HITL)"],
   ["restriction", "Method and endpoint allowlist"],
   ["quota", "Request quota"],
   ["content_match", "Operation and parameter policy"]
@@ -36334,10 +36597,13 @@ function buildPolicyRulePresentation(rule) {
     });
   }
   if (rule.display?.inherited) {
-    displayItems.push({ label: "Relationship", value: "Inherited policy" });
+    displayItems.push({
+      label: "Relationship",
+      value: "Inherited runtime policy"
+    });
   }
   if (displayItems.length > 0) {
-    groups.unshift({ label: "Policy scope", items: displayItems });
+    groups.unshift({ label: "Runtime policy scope", items: displayItems });
   }
   return {
     typeLabel: policyRuleTypeLabel(rule.rule_type),
@@ -36350,7 +36616,10 @@ function formatPolicyRuleAsText(rule) {
   const lines = [
     ...rule.name ? [`Name: ${rule.name}`] : [],
     ...rule.id ? [`Policy ID: ${rule.id}`] : [],
-    `Type: ${presentation.typeLabel}`,
+    // The friendly label matches the dashboard; the wire identifier is what
+    // `alter policy rules create --type <rule_type>` accepts, so the text
+    // view prints both for operators who script from it.
+    `Type: ${presentation.typeLabel} [${rule.rule_type}]`,
     `Effect: ${presentation.effectLabel}`,
     `Status: ${rule.enabled === false ? "Disabled" : "Enabled"}`,
     presentation.summary,
@@ -36865,7 +37134,7 @@ function buildAppsCommand() {
     "table"
   ).option(
     "--no-include-stats",
-    "Skip per-app statistics (grant / key / API-call counts)"
+    "Skip per-app statistics (grant / connection / secret / provider / key / API-call counts)"
   ).option(
     "--include-archived",
     "Include archived (soft-deleted) apps. Default is active-only \u2014 archive's whole point is to hide clutter from the default view, so opt in only when you want the full set (e.g. before unarchiving something)."
@@ -41066,6 +41335,7 @@ async function runStatus() {
 // src/commands/managed-secrets.ts
 import { readFileSync as readFileSync9 } from "fs";
 import { Command as Command16, Option } from "commander";
+var MAX_SEARCH_LENGTH = 255;
 var PRINCIPAL_TYPES = ["user", "group", "system", "agent"];
 var CREDENTIAL_TYPES = [
   "bearer_token",
@@ -41470,6 +41740,13 @@ function surfaceManagedSecretResponse(row) {
   }
   surfaceApproverWarnings(row);
 }
+function derivedAllowlistMessage(e) {
+  if (!(e instanceof PortalBackendError) || e.statusCode !== 409 || e.code !== "managed_secret_allowed_hosts_derived") {
+    return null;
+  }
+  const detail = e.body?.detail;
+  return typeof detail?.message === "string" ? sanitizeStderrText(detail.message) : "This secret's allowed hosts are derived from its provider binding and cannot be edited directly.";
+}
 function groupPrincipalGateMessage(e) {
   if (!(e instanceof PortalBackendError) || e.statusCode !== 422 || e.code !== "group_principal_unsupported_idp") {
     return null;
@@ -41806,7 +42083,11 @@ var TEMPLATE_COLUMNS = [
     get: (t) => t.form_schema?.fields.map(
       (field) => `${credentialFieldFlag(field)}${field.required ? "" : " (optional)"}`
     ).join(" ") || "\u2014"
-  }
+  },
+  // The field a bound template derives its allowlist from — the operator
+  // needs it to know which --credential-field sets (and later retargets,
+  // via rotate) the secret's allowed hosts.
+  { label: "BINDING", get: (t) => t.allowed_hosts_from_field ?? "\u2014" }
 ];
 var SECRET_COLUMNS = [
   { label: "ID", get: (s) => s.id, maxWidth: 36 },
@@ -42275,7 +42556,7 @@ function buildGroupsSubcommand() {
   );
   groups.command("list").description("List app-user-groups (Group-tab picker source)").option(APP_FLAG, APP_TARGET_DESC).option("--idp <uuid>", "Filter by identity provider id").option(
     "--search <substring>",
-    "Substring search on group name / external_group_id"
+    "Substring search on group name / external_group_id (max 255 chars)"
   ).option(
     "--limit <n>",
     "Page size (default: 50)",
@@ -42292,6 +42573,12 @@ function buildGroupsSubcommand() {
     async (options) => {
       const format = coerceOutputFormat(options.output);
       if (options.idp !== void 0) validateUuidOrExit("--idp", options.idp);
+      if (options.search !== void 0)
+        validateMaxLengthOrExit(
+          "--search",
+          options.search,
+          MAX_SEARCH_LENGTH
+        );
       const resolvedAppId = await resolveAppOrExit(options.app);
       await withClient(async (client) => {
         const response = await client.managedSecrets.listGroups(
@@ -42404,7 +42691,8 @@ function buildManagedSecretsCommand() {
             credential_type: isString,
             category: isOptionalString,
             popular: (v) => typeof v === "boolean",
-            form_schema: isTemplateFormSchema
+            form_schema: isTemplateFormSchema,
+            allowed_hosts_from_field: isAbsentOrOptionalString
           },
           "managed-secrets.templates"
         );
@@ -42788,11 +43076,25 @@ function buildManagedSecretsCommand() {
       }
       const hostList = options.clear ? null : parseAllowedHostsOrExit("--host", options.host);
       await withClient(async (client) => {
-        const row = await client.managedSecrets.setAllowedHosts(
-          appId,
-          secretId,
-          hostList
-        );
+        let row;
+        try {
+          row = await client.managedSecrets.setAllowedHosts(
+            appId,
+            secretId,
+            hostList
+          );
+        } catch (e) {
+          const derived = derivedAllowlistMessage(e);
+          if (derived !== null) {
+            process.stderr.write(`alter: ${derived}
+`);
+            process.stderr.write(
+              "alter: rotate the credential (`alter managed-secrets rotate`) to change its binding\n"
+            );
+            process.exit(EXIT_CONFLICT);
+          }
+          throw e;
+        }
         emit2(format, row);
         if (options.clear) {
           process.stderr.write(
@@ -43078,7 +43380,7 @@ function buildManagedSecretsCommand() {
   );
   root.command("users").description("List app-users (User-tab picker source for grants create)").option(APP_FLAG, APP_TARGET_DESC).option("--idp <uuid>", "Filter by identity provider id").option(
     "--search <substring>",
-    "Substring search on email / display_name / external_subject_id"
+    "Substring search on email / display_name / external_subject_id (max 255 chars)"
   ).option(
     "--limit <n>",
     "Page size (default: 50)",
@@ -43095,6 +43397,12 @@ function buildManagedSecretsCommand() {
     async (options) => {
       const format = coerceOutputFormat(options.output);
       if (options.idp !== void 0) validateUuidOrExit("--idp", options.idp);
+      if (options.search !== void 0)
+        validateMaxLengthOrExit(
+          "--search",
+          options.search,
+          MAX_SEARCH_LENGTH
+        );
       const resolvedAppId = await resolveAppOrExit(options.app);
       await withClient(async (client) => {
         const response = await client.managedSecrets.listUsers(