@alter-ai/cli 0.9.0 → 0.9.2

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.2",
   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.25.0",
     "@alter-vault/shared-types": "workspace:0.0.1",
     "@alter-vault/shared-utils": "workspace:0.0.1",
     "@eslint/js": "9.39.4",
@@ -4739,7 +4743,14 @@ var AmbiguousGrantError = class extends BackendError {
   // scoped to the caller's own accessible set. Retry with the chosen
   // `grantId`.
   candidates;
-  constructor(message, providerId, accountIdentifiers, accountWasProvided, appUserIds, details, grantIds, candidates) {
+  // True when more grants matched than the error body can carry. It bounds
+  // EVERY disambiguator on this error — `candidates`, `accountIdentifiers`,
+  // `appUserIds` and `grantIds` all come from the same capped set — so a
+  // grant, account or user missing from any of them is not proof it does not
+  // exist. Narrow the request or call `listGrants()` for the authoritative
+  // set.
+  candidatesTruncated;
+  constructor(message, providerId, accountIdentifiers, accountWasProvided, appUserIds, details, grantIds, candidates, candidatesTruncated) {
     super(message, details);
     this.name = "AmbiguousGrantError";
     this.providerId = providerId;
@@ -4748,6 +4759,7 @@ var AmbiguousGrantError = class extends BackendError {
     this.appUserIds = appUserIds ?? [];
     this.grantIds = grantIds ?? [];
     this.candidates = candidates ?? [];
+    this.candidatesTruncated = candidatesTruncated ?? false;
   }
 };
 var NoDelegatedGrantError = class extends BackendError {
@@ -5720,6 +5732,14 @@ var ConnectSession = class {
    * Python SDK's scope_constraint_warnings coercion (parity contract).
    */
   scopeConstraintWarnings;
+  /**
+   * True when the session names exactly one provider: the hosted UI shows no
+   * picker, confirmation screen or Alter-branded page, and the browser widget
+   * can open the provider window straight from the application's click when
+   * the value is passed through as `open({ direct })`. False on a malformed
+   * wire value (informational, not load-bearing).
+   */
+  direct;
   constructor(data) {
     _assertString(data.session_token, "session_token", "ConnectSession");
     _assertString(data.connect_url, "connect_url", "ConnectSession");
@@ -5741,10 +5761,12 @@ var ConnectSession = class {
         (w) => typeof w === "string"
       ) : []
     );
+    this.direct = data.direct === true;
     Object.freeze(this);
   }
   toJSON() {
     return {
+      direct: this.direct,
       session_token: this.sessionToken,
       connect_url: this.connectUrl,
       expires_in: this.expiresIn,
@@ -6255,7 +6277,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 +8169,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 +10198,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.24.0";
+var SDK_VERSION = "0.25.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 function pyUnquote(s) {
   if (!s.includes("%")) return s;
@@ -10243,8 +10269,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 +10550,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 +10855,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 +10903,9 @@ var HttpClient = class {
       return response;
     } finally {
       clearTimeout(timeoutId);
+      if (callerSignal !== void 0 && onCallerAbort !== void 0) {
+        callerSignal.removeEventListener("abort", onCallerAbort);
+      }
     }
   }
   /**
@@ -10958,7 +11018,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") {
@@ -11640,7 +11700,11 @@ ${label}:${value}`;
           appUserIds,
           errorData,
           grantIds,
-          candidates
+          candidates,
+          // Absent on the wire means "complete" — only a real cap emits the
+          // key, so a strict `=== true` keeps a stray falsy value from
+          // reading as truncation.
+          errorData.candidates_truncated === true
         );
       }
       if (errorData.error === "sibling_label_conflict") {
@@ -12163,9 +12227,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 +12765,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 +13142,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 +13957,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 +13987,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 +14012,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 +14149,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 +14166,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 +14179,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 +14228,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 +14481,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 +15109,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 +15145,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 +15227,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 +15281,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 +16098,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 +16519,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 +16776,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.2";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -16804,7 +17022,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);
@@ -17544,6 +17762,13 @@ var AgentsNamespace2 = class {
     return expectDict(body, "agents.undeprecate_key", 200);
   }
 };
+function isRedirectUriAliasSpec(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const spec = value;
+  return typeof spec.label === "string" && typeof spec.description === "string";
+}
 function isSharedDevProviderEntry(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     return false;
@@ -17565,7 +17790,7 @@ function isProviderCatalogEntry(value) {
   const v = value;
   return typeof v.id === "string" && typeof v.name === "string" && typeof v.display_name === "string" && (v.category === null || typeof v.category === "string") && (v.supports_refresh === null || typeof v.supports_refresh === "boolean") && (v.supports_pkce === null || typeof v.supports_pkce === "boolean") && (v.available_environments === void 0 || Array.isArray(v.available_environments) && v.available_environments.every(
     (environment) => environment === "production" || environment === "sandbox"
-  )) && (v.scopes_configured_on_provider === void 0 || typeof v.scopes_configured_on_provider === "boolean") && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
+  )) && (v.scopes_configured_on_provider === void 0 || typeof v.scopes_configured_on_provider === "boolean") && (v.redirect_uri_alias === void 0 || v.redirect_uri_alias === null || isRedirectUriAliasSpec(v.redirect_uri_alias)) && v.available_scopes !== null && typeof v.available_scopes === "object" && !Array.isArray(v.available_scopes) && Object.values(v.available_scopes).every(
     isProviderScopeCatalogEntry
   ) && (v.managed_credentials_available === void 0 || typeof v.managed_credentials_available === "boolean") && (v.managed_approved_scopes === void 0 || v.managed_approved_scopes === null || Array.isArray(v.managed_approved_scopes) && v.managed_approved_scopes.every(
     (scope) => typeof scope === "string"
@@ -17660,7 +17885,8 @@ var ProvidersNamespace = class {
       client_secret: options.client_secret,
       environment: options.environment,
       scopes: options.scopes,
-      redirect_uris: options.redirect_uris
+      redirect_uris: options.redirect_uris,
+      redirect_uri_alias: options.redirect_uri_alias
     });
     const body = await this.#client._call(
       "POST",
@@ -17697,6 +17923,7 @@ var ProvidersNamespace = class {
       environment: options.environment,
       scopes: options.scopes,
       redirect_uris: options.redirect_uris,
+      redirect_uri_alias: options.redirect_uri_alias,
       status: options.status
     });
     const body = await this.#client._call(
@@ -19535,6 +19762,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 +20346,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 +20359,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 +20384,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 +20649,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;
@@ -20534,7 +20825,9 @@ function buildAgentsCommand() {
       });
     }
   );
-  agents.command("create").description("Create a managed agent (returns one-shot API key)").option(APP_FLAG, APP_TARGET_DESC).option(
+  agents.command("create").description(
+    "Create a managed agent (returns its first API key ONCE, in the api_key field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).option(
     "--name <name>",
     "Agent name (stable identifier). Required unless --input is supplied."
   ).option("--display-name <name>", "Human-readable display name").option("--type <type>", "Type: agent|service (default: agent)", "agent").option(
@@ -20566,6 +20859,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 +20915,7 @@ function buildAgentsCommand() {
           "alter: the api_key field above is shown ONCE and cannot be retrieved later.\n"
         );
         surfaceApproverWarnings(result);
+        surfaceScopeWarnings(result);
       });
     }
   );
@@ -20840,6 +21135,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(
@@ -20936,7 +21232,9 @@ function buildAgentsCommand() {
 `);
     });
   });
-  agents.command("mint-key").description("Mint a fresh API key for the agent (plaintext returned ONCE)").option(APP_FLAG, APP_TARGET_DESC).requiredOption(
+  agents.command("mint-key").description(
+    "Mint a fresh API key for the agent (plaintext returned ONCE, in the api_key field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--agent <agent-id>",
     "Agent ID",
     parseUuidArgument("--agent")
@@ -35908,7 +36206,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 +36632,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 +36651,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 +37169,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)."
@@ -38012,7 +38316,25 @@ import { hostname as hostname3, platform as platform2 } from "os";
 import { spawn } from "child_process";
 var MIN_EPHEMERAL_PORT = 49152;
 var MAX_EPHEMERAL_PORT = 65535;
-var LISTENER_TIMEOUT_MS = 12e4;
+var LISTENER_TIMEOUT_MS = 6e5;
+function describeDeadline(ms) {
+  if (ms >= 6e4 && ms % 6e4 === 0) {
+    const minutes = ms / 6e4;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (ms >= 1e3) {
+    const seconds = Math.round(ms / 1e3);
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${ms} ms`;
+}
+var SELF_INSPECTION_SCOPE = "dashboard_pats:read";
+function withSelfInspectionScope(scopes) {
+  if (scopes.includes(SELF_INSPECTION_SCOPE)) {
+    return { scopes: [...scopes], added: false };
+  }
+  return { scopes: [...scopes, SELF_INSPECTION_SCOPE], added: true };
+}
 var CALLBACK_STATE_PATTERN = /^[0-9a-f]{64}$/;
 var DEFAULT_SCOPES = [
   "dashboard_apps:read",
@@ -38090,7 +38412,9 @@ function pickEphemeralPort() {
 }
 async function runBrowserDance(options) {
   const state = randomBytes2(32).toString("hex");
-  const scopes = options.scopes ?? DEFAULT_SCOPES;
+  const { scopes, added: addedSelfInspectionScope } = withSelfInspectionScope(
+    options.scopes ?? DEFAULT_SCOPES
+  );
   const dashboardUrl = options.dashboardUrl ?? deriveDashboardUrl(options.baseUrl);
   const openBrowser = options.openBrowser ?? defaultOpenBrowser;
   const timeoutMs = options.timeoutMs ?? LISTENER_TIMEOUT_MS;
@@ -38145,7 +38469,7 @@ async function runBrowserDance(options) {
       cleanupListener();
       reject(
         new Error(
-          "browser-dance timed out \u2014 operator did not complete the consent flow within 2 minutes"
+          `browser-dance timed out \u2014 operator did not complete the consent flow within ${describeDeadline(timeoutMs)}`
         )
       );
     }, timeoutMs);
@@ -38303,9 +38627,15 @@ async function runBrowserDance(options) {
     bindQuery = `&bind=cidr&cidr=${encodeURIComponent(options.cidrValue)}`;
   }
   const url2 = `${dashboardUrl}/cli-auth?port=${port}&state=${state}&scopes=${scopeQuery}&hostname=${encodeURIComponent(hostname3())}${bindQuery}`;
+  if (addedSelfInspectionScope) {
+    process.stderr.write(
+      `alter: added ${SELF_INSPECTION_SCOPE} to the requested scopes \u2014 the CLI verifies the sign-in (and \`alter auth status\`) with it.
+`
+    );
+  }
   process.stdout.write(
     `alter: opening browser at ${dashboardUrl}/cli-auth
-       (waiting up to 2 minutes for you to approve)\u2026
+       (waiting up to ${describeDeadline(timeoutMs)} for you to approve)\u2026
 `
   );
   openBrowser(url2);
@@ -38951,7 +39281,7 @@ function buildAuthCommand() {
     "Override the dashboard URL used by the browser-dance flow. Defaults to the backend URL with the leftmost `backend.` subdomain swapped for `portal.`. Use this when the dashboard isn't at the regex-derivable host (e.g. staging / self-hosted setups). Must use https://."
   ).option(
     "--scopes <list>",
-    "Comma-separated scope list to request on the browser-dance consent page (e.g. 'dashboard_apps:read,dashboard_keys:write'). Defaults to the full read+write set across the CLI surface \u2014 enough for every non-destructive day-to-day command. Opt in to admin / delete tiers explicitly: 'dashboard_keys:admin' for runtime-key admin ops, 'dashboard_apps:admin' to archive/unarchive an app, and 'dashboard_apps:delete' for cascade-delete an app (note the Destructive-Action Policy keeps :delete as its own verb, separate from :admin \u2014 :admin does not grant the cascade). Each entry is validated client-side against the dashboard scope catalog \u2014 typos fail fast. Mutually exclusive with --token / --token-file / --token-stdin \u2014 pre-minted PATs have their scope set baked at mint time on the dashboard's Settings page; combining the flags is a usage error."
+    "Comma-separated scope list to request on the browser-dance consent page (e.g. 'dashboard_apps:read,dashboard_keys:write'). Defaults to the full read+write set across the CLI surface \u2014 enough for every non-destructive day-to-day command. Opt in to admin / delete tiers explicitly: 'dashboard_keys:admin' for runtime-key admin ops, 'dashboard_apps:admin' to archive/unarchive an app, and 'dashboard_apps:delete' for cascade-delete an app (note the Destructive-Action Policy keeps :delete as its own verb, separate from :admin \u2014 :admin does not grant the cascade). The list REPLACES the default set, except that dashboard_pats:read is always added: the CLI verifies every sign-in (and `alter auth status`) with it, so a PAT without it cannot complete the login. Each entry is validated client-side against the dashboard scope catalog \u2014 typos fail fast. Mutually exclusive with --token / --token-file / --token-stdin \u2014 pre-minted PATs have their scope set baked at mint time on the dashboard's Settings page; combining the flags is a usage error."
   ).option(
     "--no-bind-ip",
     "Explicit opt-out of IP binding. This is now the DEFAULT for the browser-dance flow, so the flag is a no-op alias retained for scripts that pass it explicitly. The resulting PAT works from any source IP. Browser-dance flow only."
@@ -40696,7 +41026,9 @@ function buildKeysCommand() {
       emit2(format, row);
     });
   });
-  keys.command("mint").description("Mint a new scoped key (plaintext returned ONCE)").option(APP_FLAG, APP_TARGET_DESC).option(
+  keys.command("mint").description(
+    "Mint a new scoped key (plaintext returned ONCE, in the plain_key field \u2014 api_key is the key's metadata; capture it with --output json --fields plain_key or jq -r .plain_key)"
+  ).option(APP_FLAG, APP_TARGET_DESC).option(
     "--name <name>",
     "Display name. Required unless --input is supplied."
   ).option(
@@ -40758,7 +41090,7 @@ function buildKeysCommand() {
         }
         emit2(format, outcome2.result);
         process.stderr.write(
-          "alter: the plaintext key above is shown ONCE and cannot be retrieved later.\n"
+          "alter: the plain_key field above is the secret (api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
         );
         return;
       }
@@ -40851,7 +41183,7 @@ function buildKeysCommand() {
       }
       emit2(format, outcome.result);
       process.stderr.write(
-        "alter: the plaintext key above is shown ONCE and cannot be retrieved later.\n"
+        "alter: the plain_key field above is the secret (api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
       );
     }
   );
@@ -40868,7 +41200,7 @@ function buildKeysCommand() {
     });
   });
   keys.command("rotate").description(
-    "Rotate a key (new plaintext returned ONCE; old key enters grace until revoke). The app-key successor receives the organization's current finite default TTL. Requires dashboard_keys:write scope."
+    "Rotate a key (new plaintext returned ONCE, in the new_plain_key field; old key enters grace until revoke). The app-key successor receives the organization's current finite default TTL. Requires dashboard_keys:write scope."
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption("--key <key-id>", "Key ID", parseUuidArgument("--key")).option(
     "--scopes <list>",
     "Optional new scope set (defaults to the key's current scopes)"
@@ -40893,7 +41225,7 @@ function buildKeysCommand() {
         });
         emit2(format, result);
         process.stderr.write(
-          "alter: the new plaintext key above is shown ONCE and cannot be retrieved later.\n"
+          "alter: the new_plain_key field above is the new secret (new_api_key is metadata); it is shown ONCE and cannot be retrieved later.\n"
         );
       });
     }
@@ -40902,7 +41234,7 @@ function buildKeysCommand() {
     "Revoke a key immediately (cascades to derived keys). Requires dashboard_keys:admin scope."
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption("--key <key-id>", "Key ID", parseUuidArgument("--key")).option(
     "--force",
-    "Override the last-active-key guard (revoking an agent's only active key bricks it until a fresh key is minted)"
+    "Override the last-active-key guard (revoking the last active key on an app or an agent leaves whatever authenticates with it broken until a fresh key is minted)"
   ).option("--yes", "Skip the interactive y/N prompt").action(
     async (options) => {
       const resolvedAppId = await resolveAppOrExit(options.app);
@@ -41066,6 +41398,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 +41803,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 +42146,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 },
@@ -41818,10 +42162,20 @@ var SECRET_COLUMNS = [
   { label: "CREATED", get: (s) => s.created_at },
   { label: "UPDATED", get: (s) => s.updated_at ?? "\u2014" }
 ];
+var DEPTH_COLUMN = {
+  label: "DEPTH",
+  get: (g) => g.depth == null ? "?" : String(g.depth)
+};
+var PARENT_COLUMN = {
+  label: "PARENT",
+  get: (g) => g.parent_grant_id === void 0 ? "?" : g.parent_grant_id ?? "\u2014",
+  maxWidth: 36
+};
 var GRANT_COLUMNS2 = [
   { label: "GRANT_ID", get: (g) => g.grant_id, maxWidth: 36 },
   { label: "PRINCIPAL", get: (g) => g.principal_type },
   { label: "LABEL", get: (g) => g.label ?? "\u2014", maxWidth: 24 },
+  DEPTH_COLUMN,
   { label: "STATUS", get: (g) => g.status },
   { label: "CREATED", get: (g) => g.created_at },
   {
@@ -41833,6 +42187,9 @@ var GRANT_COLUMNS2 = [
     get: (g) => g.grant_expires_at ?? "\u2014"
   }
 ];
+var AGENT_GRANT_COLUMNS = GRANT_COLUMNS2.flatMap(
+  (col) => col === DEPTH_COLUMN ? [col, PARENT_COLUMN] : [col]
+);
 var USER_COLUMNS = [
   { label: "ID", get: (u) => u.id, maxWidth: 36 },
   { label: "EMAIL", get: (u) => u.email ?? "\u2014" },
@@ -41909,7 +42266,9 @@ function buildGrantsSubcommand() {
             label: isOptionalString,
             created_at: isString,
             expires_at: isOptionalString,
-            grant_expires_at: isAbsentOrOptionalString
+            grant_expires_at: isAbsentOrOptionalString,
+            parent_grant_id: isAbsentOrOptionalString,
+            depth: isAbsentOrOptionalNumber
           },
           "managed-secrets.grants.list"
         );
@@ -41957,11 +42316,14 @@ function buildGrantsSubcommand() {
             label: isOptionalString,
             created_at: isString,
             expires_at: isOptionalString,
-            grant_expires_at: isAbsentOrOptionalString
+            grant_expires_at: isAbsentOrOptionalString,
+            // Rendered through ``AGENT_GRANT_COLUMNS`` (adds PARENT).
+            parent_grant_id: isAbsentOrOptionalString,
+            depth: isAbsentOrOptionalNumber
           },
           "managed-secrets.grants.list-for-agent"
         );
-        emit2(format, rows, GRANT_COLUMNS2);
+        emit2(format, rows, AGENT_GRANT_COLUMNS);
       });
     }
   );
@@ -42275,7 +42637,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 +42654,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 +42772,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 +43157,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 +43461,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 +43478,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(
@@ -43418,7 +43807,9 @@ function buildIdentityProvidersCommand() {
   const webhook = idp.command("webhook").description(
     "Manage an identity provider's webhook integration (requires dashboard_identity_providers:webhooks)"
   );
-  webhook.command("enable").description("Enable webhook integration (returns the signing secret ONCE)").option(APP_FLAG, APP_TARGET_DESC).requiredOption(
+  webhook.command("enable").description(
+    "Enable webhook integration (returns the signing secret ONCE, in the webhook_secret field)"
+  ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--provider <provider-id>",
     "Identity provider ID",
     parseUuidArgument("--provider")
@@ -43450,7 +43841,7 @@ function buildIdentityProvidersCommand() {
         emit2(format, row);
         if (typeof row["webhook_secret"] === "string") {
           process.stderr.write(
-            "alter: the webhook_secret above is shown ONCE and cannot be retrieved later.\n"
+            "alter: the webhook_secret field above is shown ONCE and cannot be retrieved later.\n"
           );
         }
         return null;
@@ -43570,7 +43961,7 @@ alter: re-run with --force --confirm <issuer-host> to revoke those grants and di
     }
   );
   webhook.command("rotate").description(
-    "Rotate the webhook signing secret (invalidates the previous; returns the new one ONCE)"
+    "Rotate the webhook signing secret (invalidates the previous; returns the new one ONCE, in the webhook_secret field)"
   ).option(APP_FLAG, APP_TARGET_DESC).requiredOption(
     "--provider <provider-id>",
     "Identity provider ID",
@@ -43618,7 +44009,7 @@ alter: re-run with --force --confirm <issuer-host> to revoke those grants and di
         emit2(format, row);
         if (typeof row["webhook_secret"] === "string") {
           process.stderr.write(
-            "alter: the webhook_secret above is shown ONCE and cannot be retrieved later.\n"
+            "alter: the webhook_secret field above is shown ONCE and cannot be retrieved later.\n"
           );
         }
         return null;
@@ -45019,8 +45410,12 @@ function buildPolicyCommand() {
 import { Command as Command20 } from "commander";
 var CREDENTIAL_SOURCES = ["custom", "shared_dev"];
 var PROVIDER_ENVIRONMENTS = ["production", "sandbox"];
-async function providerCatalogError(client, providerId, environment, credentialSource, scopes, scopesRequired = false) {
-  if (environment === void 0 && scopes === void 0 && !scopesRequired) {
+async function providerCatalogError(client, providerId, environment, credentialSource, scopes, options = {}) {
+  const create = options.create === true;
+  const redirectUriAlias = options.redirectUriAlias;
+  const readStoredProvider = options.readStoredProvider;
+  const switchesToCustom = !create && credentialSource === "custom" && readStoredProvider !== void 0;
+  if (environment === void 0 && scopes === void 0 && redirectUriAlias === void 0 && !create && !switchesToCustom) {
     return null;
   }
   if (!providerId) {
@@ -45042,6 +45437,23 @@ async function providerCatalogError(client, providerId, environment, credentialS
   if (environment !== void 0 && credentialSource === "shared_dev" && environment !== "production") {
     return "alter: --credential-source shared_dev only supports --environment production; use custom sandbox credentials\n";
   }
+  const aliasSpec = provider.redirect_uri_alias ?? null;
+  const aliasError = redirectUriAliasError(
+    providerId,
+    aliasSpec,
+    credentialSource,
+    redirectUriAlias,
+    create
+  );
+  if (aliasError !== null) return aliasError;
+  if (switchesToCustom && readStoredProvider !== void 0 && aliasSpec !== null && redirectUriAlias === void 0) {
+    const storedAliasError = await redirectUriAliasStoredStateError(
+      readStoredProvider,
+      providerId,
+      aliasSpec
+    );
+    if (storedAliasError !== null) return storedAliasError;
+  }
   const availableScopes = provider.available_scopes ?? {};
   if (Object.keys(availableScopes).length === 0) {
     if (scopes !== void 0 && scopes.length > 0) {
@@ -45051,7 +45463,7 @@ async function providerCatalogError(client, providerId, environment, credentialS
     }
     return null;
   }
-  if (scopesRequired && scopes === void 0) {
+  if (create && scopes === void 0) {
     return `alter: provider '${providerId}' requires at least one scope (pass --scopes, or "scopes" in --input)
 `;
   }
@@ -45082,6 +45494,41 @@ async function providerCatalogError(client, providerId, environment, credentialS
   }
   return null;
 }
+function redirectUriAliasError(providerId, spec, credentialSource, redirectUriAlias, create) {
+  if (spec === null) {
+    return redirectUriAlias === void 0 ? null : `alter: --redirect-uri-alias is not used by ${providerId}
+`;
+  }
+  if (redirectUriAlias !== void 0 && credentialSource === "shared_dev") {
+    return `alter: --redirect-uri-alias is only accepted with --credential-source custom (Alter-managed credentials carry their own ${spec.label})
+`;
+  }
+  const custom3 = credentialSource === void 0 || credentialSource === "custom";
+  if (create && custom3 && redirectUriAlias === void 0) {
+    return redirectUriAliasRequiredError(providerId, spec);
+  }
+  return null;
+}
+function redirectUriAliasRequiredError(providerId, spec) {
+  return `alter: ${providerId} requires --redirect-uri-alias (${spec.label}): ${spec.description} (pass --redirect-uri-alias, or "redirect_uri_alias" in --input)
+`;
+}
+async function redirectUriAliasStoredStateError(readStoredProvider, providerId, spec) {
+  let current;
+  try {
+    const row = await readStoredProvider();
+    if (row === null || typeof row !== "object") return null;
+    current = row;
+  } catch {
+    return null;
+  }
+  const storedSource = typeof current.credential_source === "string" ? current.credential_source : "custom";
+  const storedAlias = typeof current.redirect_uri_alias === "string" ? current.redirect_uri_alias.trim() : "";
+  if (storedSource === "shared_dev" || storedAlias.length === 0) {
+    return redirectUriAliasRequiredError(providerId, spec);
+  }
+  return null;
+}
 function storedProviderReader(client, appId, providerId) {
   let pending2 = null;
   return () => pending2 ??= client.providers.get(appId, providerId);
@@ -45167,6 +45614,16 @@ var PROVIDER_COLUMNS = [
   // between test money and real money.
   { label: "ENV", get: (p) => p.environment ?? "production" },
   { label: "SCOPES", get: (p) => p.scopes.join(",") || "\u2014", maxWidth: 40 },
+  // The provider-issued redirect name (eBay's RuName). Its provider-side
+  // label is on ``list-catalog``'s REDIRECT ALIAS column. Wide enough for a
+  // real RuName (``<user>-<app>-<title>-<token>``, ~40–60 chars) to print
+  // untruncated — an operator copies this column back into a provider
+  // console, so a clipped value is worse than none.
+  {
+    label: "REDIRECT ALIAS",
+    get: (p) => p.redirect_uri_alias ?? "\u2014",
+    maxWidth: 60
+  },
   { label: "GRANTS", get: (p) => String(p.grants_count) },
   { label: "STATUS", get: (p) => p.status },
   {
@@ -45250,6 +45707,22 @@ function collectRedirectUris(value, previous = []) {
   const next = value.split(",").map((s) => s.trim()).filter(Boolean);
   return [...previous, ...next];
 }
+function validateRedirectUriAliasOrExit(raw, source = "--redirect-uri-alias") {
+  if (raw === void 0) return void 0;
+  const value = raw.trim();
+  if (value.length === 0) {
+    process.stderr.write(`alter: ${source} requires a non-empty value
+`);
+    process.exit(EXIT_USAGE);
+  }
+  if (value.length > 255) {
+    process.stderr.write(`alter: ${source} must be at most 255 characters
+`);
+    process.exit(EXIT_USAGE);
+  }
+  return value;
+}
+var INPUT_ALIAS_SOURCE = '"redirect_uri_alias" in --input';
 function surfaceProviderResponse(row) {
   if (typeof row !== "object" || row === null) return;
   const r = row;
@@ -45319,6 +45792,7 @@ function buildProvidersCommand() {
           // "production" — defeating the tolerance this line exists for.
           environment: isAbsentOrOptionalString,
           scopes: (v) => Array.isArray(v),
+          redirect_uri_alias: isAbsentOrOptionalString,
           status: isString,
           grants_count: (v) => typeof v === "number"
         },
@@ -45367,6 +45841,13 @@ function buildProvidersCommand() {
           get: (p) => p.managed_approved_scopes === void 0 ? "?" : p.managed_approved_scopes === null ? "\u2014" : p.managed_approved_scopes.join(",") || "(none)",
           maxWidth: 36
         },
+        // Providers that take a provider-issued NAME as redirect_uri
+        // instead of the callback URL show its label (eBay: RuName) —
+        // ``create`` then requires ``--redirect-uri-alias``.
+        {
+          label: "REDIRECT ALIAS",
+          get: (p) => p.redirect_uri_alias?.label ?? "\u2014"
+        },
         { label: "STATUS", get: (p) => p.status }
       ]);
     });
@@ -45395,9 +45876,12 @@ function buildProvidersCommand() {
     "--redirect-uri <uri>",
     "Add a redirect URI. Repeat the flag (``--redirect-uri A --redirect-uri B``) or pass a comma-separated list (``--redirect-uri A,B``); both forms accumulate.",
     collectRedirectUris
+  ).option(
+    "--redirect-uri-alias <name>",
+    "The provider-issued redirect name sent as redirect_uri in place of the callback URL \u2014 required for providers that use one (eBay's RuName); see `alter providers list-catalog`."
   ).option(
     "--input <path>",
-    "JSON wire body from file (@/path/to/body.json) or stdin (-). Mirrors ``gh api --input``. Replaces the per-field flags (``--provider``, ``--credential-source``, ``--client-id``, ``--client-secret``, ``--environment``, ``--scopes``, ``--redirect-uri``); the body is sent to ``POST /apps/<app>/providers`` verbatim. If both --input and per-field flags are supplied, --input wins and the per-field flags are ignored (with a warning)."
+    "JSON wire body from file (@/path/to/body.json) or stdin (-). Mirrors ``gh api --input``. Replaces the per-field flags (``--provider``, ``--credential-source``, ``--client-id``, ``--client-secret``, ``--environment``, ``--scopes``, ``--redirect-uri``, ``--redirect-uri-alias``); the body is sent to ``POST /apps/<app>/providers`` verbatim. If both --input and per-field flags are supplied, --input wins and the per-field flags are ignored (with a warning)."
   ).option(
     "--output <format>",
     "Output format: json|jsonl|table (default: json)",
@@ -45415,7 +45899,8 @@ function buildProvidersCommand() {
           "clientSecret",
           "environment",
           "scopes",
-          "redirectUri"
+          "redirectUri",
+          "redirectUriAlias"
         ].filter((k) => {
           if (k === "credentialSource")
             return options.credentialSource !== "custom";
@@ -45424,6 +45909,10 @@ function buildProvidersCommand() {
           return options[k] !== void 0;
         });
         warnInputOverridesPerFieldFlags(perField.map(optionKeyToFlag));
+        const bodyRedirectUriAlias = validateRedirectUriAliasOrExit(
+          inputBodyString(body, "redirect_uri_alias"),
+          INPUT_ALIAS_SOURCE
+        );
         const inputPreflightError = await withClient(
           async (client) => {
             const bodyEnvironment = inputBodyString(body, "environment");
@@ -45433,7 +45922,7 @@ function buildProvidersCommand() {
               bodyEnvironment,
               inputBodyString(body, "credential_source"),
               inputBodyStringArray(body, "scopes"),
-              true
+              { create: true, redirectUriAlias: bodyRedirectUriAlias }
             );
             if (catalogError !== null) return catalogError;
             const availabilityError = await sharedDevAvailabilityError(
@@ -45502,6 +45991,9 @@ function buildProvidersCommand() {
         validateUrlOrExit("--redirect-uri", uri);
       }
       const redirects = options.redirectUri && options.redirectUri.length > 0 ? options.redirectUri : void 0;
+      const redirectUriAlias = validateRedirectUriAliasOrExit(
+        options.redirectUriAlias
+      );
       const environmentPreflightError = await withClient(
         async (client) => {
           const catalogError = await providerCatalogError(
@@ -45510,7 +46002,7 @@ function buildProvidersCommand() {
             environment,
             credentialSource,
             scopes,
-            true
+            { create: true, redirectUriAlias }
           );
           if (catalogError !== null) return catalogError;
           const availabilityError = await sharedDevAvailabilityError(
@@ -45529,7 +46021,8 @@ function buildProvidersCommand() {
             // Scopeless provider with --scopes omitted: the dashboard's
             // exact wire body for these providers is ``scopes: []``.
             scopes: scopes ?? [],
-            redirect_uris: redirects
+            redirect_uris: redirects,
+            redirect_uri_alias: redirectUriAlias
           });
           surfaceProviderResponse(row);
           emit2(format, row);
@@ -45563,6 +46056,7 @@ function buildProvidersCommand() {
             credential_source: isOptionalString,
             environment: isAbsentOrOptionalString,
             scopes: (v) => Array.isArray(v),
+            redirect_uri_alias: isAbsentOrOptionalString,
             status: isString,
             grants_count: (v) => typeof v === "number"
           },
@@ -45590,6 +46084,9 @@ function buildProvidersCommand() {
     "--redirect-uri <uri>",
     "Replace redirect URIs. Repeat the flag or pass a comma-separated list; both forms accumulate.",
     collectRedirectUris
+  ).option(
+    "--redirect-uri-alias <name>",
+    "Replace the provider-issued redirect name sent as redirect_uri in place of the callback URL (eBay's RuName). Accepted only for providers that use one; see `alter providers list-catalog`."
   ).option(
     "--status <status>",
     "New status: active | disabled (rejected at the CLI if not exactly one of the two values)"
@@ -45619,24 +46116,33 @@ function buildProvidersCommand() {
           "environment",
           "scopes",
           "redirectUri",
+          "redirectUriAlias",
           "status"
         ].filter((k) => options[k] !== void 0);
         warnInputOverridesPerFieldFlags(perField.map(optionKeyToFlag));
+        const bodyRedirectUriAlias = validateRedirectUriAliasOrExit(
+          inputBodyString(body, "redirect_uri_alias"),
+          INPUT_ALIAS_SOURCE
+        );
         const inputPreflightError = await withClient(
           async (client) => {
+            const readStoredProvider = storedProviderReader(
+              client,
+              appId,
+              options.provider
+            );
             const catalogError = await providerCatalogError(
               client,
               options.provider,
               inputBodyString(body, "environment"),
               inputBodyString(body, "credential_source"),
-              inputBodyStringArray(body, "scopes")
+              inputBodyStringArray(body, "scopes"),
+              {
+                redirectUriAlias: bodyRedirectUriAlias,
+                readStoredProvider
+              }
             );
             if (catalogError !== null) return catalogError;
-            const readStoredProvider = storedProviderReader(
-              client,
-              appId,
-              options.provider
-            );
             const storedStateError = await sharedDevStoredStateError(
               readStoredProvider,
               options.provider,
@@ -45698,21 +46204,25 @@ function buildProvidersCommand() {
         validateUrlOrExit("--redirect-uri", uri);
       }
       const redirects = options.redirectUri && options.redirectUri.length > 0 ? options.redirectUri : void 0;
+      const redirectUriAlias = validateRedirectUriAliasOrExit(
+        options.redirectUriAlias
+      );
       const updatePreflightError = await withClient(
         async (client) => {
+          const readStoredProvider = storedProviderReader(
+            client,
+            appId,
+            options.provider
+          );
           const catalogError = await providerCatalogError(
             client,
             options.provider,
             environment,
             credentialSource,
-            scopes
+            scopes,
+            { redirectUriAlias, readStoredProvider }
           );
           if (catalogError !== null) return catalogError;
-          const readStoredProvider = storedProviderReader(
-            client,
-            appId,
-            options.provider
-          );
           const storedStateError = await sharedDevStoredStateError(
             readStoredProvider,
             options.provider,
@@ -45736,6 +46246,7 @@ function buildProvidersCommand() {
             ...options.skipPreflight ? { skip_preflight: true } : {},
             scopes,
             redirect_uris: redirects,
+            redirect_uri_alias: redirectUriAlias,
             status: providerStatus
           });
           surfaceProviderResponse(row);