@alter-ai/cli 0.8.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.8.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.23.3",
+    "@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",
@@ -4618,7 +4622,7 @@ var AlterSDKError = class extends Error {
   constructor(message, details) {
     super(message);
     this.name = "AlterSDKError";
-    this.details = details ?? {};
+    this.details = details !== null && typeof details === "object" && !Array.isArray(details) ? details : {};
     Object.setPrototypeOf(this, new.target.prototype);
   }
   toString() {
@@ -4836,9 +4840,9 @@ var InsufficientScopeError = class _InsufficientScopeError extends BackendError
   constructor(message = "Insufficient scope", options = {}) {
     super(message, options.details);
     this.name = "InsufficientScopeError";
-    this.required = options.required ?? [];
-    this.granted = options.granted ?? [];
-    this.missing = options.missing ?? [];
+    this.required = options.required ? [...options.required] : [];
+    this.granted = options.granted ? [...options.granted] : [];
+    this.missing = options.missing ? [...options.missing] : [];
     this.scopeVersion = options.scopeVersion ?? null;
     this.currentScopeVersion = options.currentScopeVersion ?? null;
     this.scopeVersionMismatch = options.scopeVersionMismatch ?? false;
@@ -4871,7 +4875,9 @@ var InsufficientScopeError = class _InsufficientScopeError extends BackendError
    */
   static fromErrorBody(errorData) {
     return new _InsufficientScopeError(
-      typeof errorData.message === "string" ? errorData.message : "Insufficient scope",
+      // Non-empty string only (parity with `_messageOr` / Python
+      // `from_error_body`): an empty wire message is as uninformative as none.
+      typeof errorData.message === "string" && errorData.message ? errorData.message : "Insufficient scope",
       {
         // Element-level filtering: a non-array coerces to [], and non-string
         // elements inside an array are dropped (a bare cast would smuggle
@@ -5056,7 +5062,7 @@ var AgentError = class extends BackendError {
   hint;
   constructor(opts = {}) {
     const subclassCode = new.target.code;
-    super(opts.message ?? subclassCode, opts.details);
+    super(opts.message || subclassCode, opts.details);
     this.name = "AgentError";
     this.code = subclassCode;
     this.hint = opts.hint;
@@ -6253,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;
   /**
@@ -6796,12 +6806,13 @@ var ApprovalResult = class {
       headers: this.headers,
       body_b64: this.bodyB64,
       body_truncated: this.bodyTruncated,
-      // Included, unlike the deliberately-omitted ``durationMs``: that one is
-      // OBSERVATIONAL (how long this particular call took), while this is part
-      // of the result's meaning — the reason the provider rejected the
-      // credential. A caller serializing a failure for a log or a bug report
-      // needs the explanation to survive; the timing of that one attempt does
-      // not.
+      // Include duration_ms so JSON round-trips carry the timing metadata.
+      // The Python twin's ApprovalResult is a plain Pydantic model whose
+      // model_dump() includes EVERY public field — duration_ms and
+      // credential_hint alike — so omitting either here would make a TS
+      // JSON round-trip lossy where the Python one is not (wire-shape
+      // parity: toJSON() must serialize the same field set as model_dump()).
+      duration_ms: this.durationMs,
       credential_hint: this.credentialHint
     };
   }
@@ -8112,7 +8123,7 @@ async function _raiseForStatus(response) {
   const rawCode = body.error;
   const code = typeof rawCode === "string" ? rawCode : "";
   const rawMessage = body.message;
-  const message = typeof rawMessage === "string" ? rawMessage : `Backend error ${response.status}`;
+  const message = typeof rawMessage === "string" && rawMessage ? rawMessage : `Backend error ${response.status}`;
   const rawHint = body.hint;
   const hint = typeof rawHint === "string" ? rawHint : void 0;
   if (code === "insufficient_scope") {
@@ -8120,7 +8131,7 @@ async function _raiseForStatus(response) {
   }
   if (code === "rate_limit_exceeded") {
     throw new RateLimitError(
-      typeof body.message === "string" ? body.message : "Rate limit exceeded \u2014 retry after the window resets.",
+      typeof body.message === "string" && body.message ? body.message : "Rate limit exceeded \u2014 retry after the window resets.",
       _parseRetryAfter(response.headers.get("Retry-After"), body.retry_after),
       body,
       typeof body.scope === "string" ? body.scope : void 0,
@@ -8140,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 });
   }
@@ -8318,9 +8329,15 @@ var AgentsNamespace = class {
     const limit = options.limit ?? 100;
     const offset = options.offset ?? 0;
     const includeRevoked = options.includeRevoked ?? false;
+    if (!Number.isInteger(limit)) {
+      throw new AlterValueError("limit must be an integer");
+    }
     if (limit < 1 || limit > LIST_LIMIT_MAX) {
       throw new AlterValueError("limit must be between 1 and 1000");
     }
+    if (!Number.isInteger(offset)) {
+      throw new AlterValueError("offset must be an integer");
+    }
     if (offset < 0) {
       throw new AlterValueError("offset must be >= 0");
     }
@@ -8766,7 +8783,7 @@ function _optionalStringArray(raw, key, context) {
 }
 function _normalizeKeyId(value, operation) {
   if (typeof value === "string") {
-    if (value.length === 0) {
+    if (value.trim().length === 0) {
       throw new AlterValueError(`${operation}() requires a non-empty keyId`);
     }
     return value;
@@ -9468,6 +9485,26 @@ var SpansNamespace = class {
           `spans[${index}] must be a UserSpan with traceId, name, and startTime`
         );
       }
+      if (span.traceId.length < 1 || span.traceId.length > 255) {
+        throw new AlterValueError(
+          `spans[${index}].traceId must be 1\u2013255 characters`
+        );
+      }
+      if (span.name.length < 1 || span.name.length > 255) {
+        throw new AlterValueError(
+          `spans[${index}].name must be 1\u2013255 characters`
+        );
+      }
+      if (span.spanId !== void 0 && (typeof span.spanId !== "string" || span.spanId.length < 1 || span.spanId.length > 32)) {
+        throw new AlterValueError(
+          `spans[${index}].spanId must be 1\u201332 characters when provided`
+        );
+      }
+      if (span.parentSpanId !== void 0 && (typeof span.parentSpanId !== "string" || span.parentSpanId.length < 1 || span.parentSpanId.length > 32)) {
+        throw new AlterValueError(
+          `spans[${index}].parentSpanId must be 1\u201332 characters when provided`
+        );
+      }
     });
     const body = {
       spans: spans.map((span) => {
@@ -9794,8 +9831,14 @@ var FORBIDDEN_INJECTION_HEADERS2 = /* @__PURE__ */ new Set([
 function _coerceInt(value) {
   return Number.isInteger(value) && value >= 0 ? value : void 0;
 }
+var IDENTITY_SYNC_POLL_STATUS = {
+  service_unavailable: 503,
+  identity_provider_inactive: 409,
+  identity_group_name_ambiguous: 409
+};
 function _messageOr(errorData, fallback) {
-  return typeof errorData.message === "string" ? errorData.message : fallback;
+  const raw = errorData.message;
+  return typeof raw === "string" && raw ? raw : fallback;
 }
 function _errorPayload(errorData) {
   const nested = errorData.details;
@@ -9918,7 +9961,8 @@ function validateTokenInjectionMetadata(tokenData) {
   let additionalCredentials = null;
   if (additionalCredentialsRaw != null) {
     if (typeof additionalCredentialsRaw !== "object" || Array.isArray(additionalCredentialsRaw) || Object.keys(additionalCredentialsRaw).length > MAX_ADDITIONAL_CREDENTIAL_KEYS || !Object.entries(additionalCredentialsRaw).every(
-      ([key, value]) => key.length <= MAX_ADDITIONAL_CREDENTIAL_KEY_LENGTH && typeof value === "string" && value.trim().length > 0 && value.length <= MAX_ADDITIONAL_CREDENTIAL_VALUE_LENGTH && // eslint-disable-next-line no-control-regex
+      ([key, value]) => key.length <= MAX_ADDITIONAL_CREDENTIAL_KEY_LENGTH && typeof value === "string" && // pythonStrip: match the backend's Python str.strip() (see token_type).
+      pythonStrip(value).length > 0 && value.length <= MAX_ADDITIONAL_CREDENTIAL_VALUE_LENGTH && // eslint-disable-next-line no-control-regex
       !/[\r\n\x00]/.test(value)
     )) {
       throw new BackendError("Backend returned invalid additional_credentials");
@@ -10016,7 +10060,23 @@ function isValidOffsetDateTime(value) {
   const hour = Number(hourText);
   const minute = Number(minuteText);
   const second = Number(secondText);
-  if (month < 1 || month > 12 || day < 1 || day > new Date(Date.UTC(year, month, 0)).getUTCDate() || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
+  const isLeapYear = year % 4 === 0 && year % 100 !== 0 || year % 400 === 0;
+  const daysInMonth = [
+    31,
+    isLeapYear ? 29 : 28,
+    31,
+    30,
+    31,
+    30,
+    31,
+    31,
+    30,
+    31,
+    30,
+    31
+  ];
+  const maxDay = daysInMonth[month - 1] ?? 0;
+  if (year < 1 || month < 1 || month > 12 || day < 1 || day > maxDay || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
     return false;
   }
   return !Number.isNaN(Date.parse(value));
@@ -10036,7 +10096,10 @@ function validateTokenResponseContract(tokenData) {
     throw new BackendError("Backend returned an invalid access_token");
   }
   const tokenType = tokenData.token_type === void 0 ? "Bearer" : tokenData.token_type;
-  if (typeof tokenType !== "string" || tokenType.trim().length === 0 || tokenType !== tokenType.trim() || tokenType.length > 255 || // eslint-disable-next-line no-control-regex
+  if (typeof tokenType !== "string" || // pythonStrip (not .trim()): the backend normalizes with Python str.strip(),
+  // whose whitespace set differs from JS trim() at the edges (NEL/BOM/C0
+  // separators). Match the backend so the two SDKs accept/reject identically.
+  pythonStrip(tokenType).length === 0 || tokenType !== pythonStrip(tokenType) || tokenType.length > 255 || // eslint-disable-next-line no-control-regex
   /[\x00-\x1f\x7f]/.test(tokenType)) {
     throw new BackendError("Backend returned an invalid token_type");
   }
@@ -10050,7 +10113,8 @@ function validateTokenResponseContract(tokenData) {
   }
   const scopes = tokenData.scopes === void 0 ? [] : tokenData.scopes;
   if (!Array.isArray(scopes) || scopes.some(
-    (scope) => typeof scope !== "string" || scope.trim().length === 0 || scope !== scope.trim() || // eslint-disable-next-line no-control-regex
+    (scope) => typeof scope !== "string" || // pythonStrip: match the backend's Python str.strip() (see token_type).
+    pythonStrip(scope).length === 0 || scope !== pythonStrip(scope) || // eslint-disable-next-line no-control-regex
     /[\x00-\x1f\x7f]/.test(scope)
   )) {
     throw new BackendError("Backend returned invalid scopes");
@@ -10060,7 +10124,8 @@ function validateTokenResponseContract(tokenData) {
     throw new BackendError("Backend returned an invalid grant_id");
   }
   const providerId = tokenData.provider_id === void 0 ? "" : tokenData.provider_id;
-  if (typeof providerId !== "string" || providerId !== providerId.trim() || providerId.length > 255 || // eslint-disable-next-line no-control-regex
+  if (typeof providerId !== "string" || // pythonStrip: match the backend's Python str.strip() (see token_type).
+  providerId !== pythonStrip(providerId) || providerId.length > 255 || // eslint-disable-next-line no-control-regex
   /[\x00-\x1f\x7f]/.test(providerId)) {
     throw new BackendError("Backend returned an invalid provider_id");
   }
@@ -10089,7 +10154,10 @@ function isRetryErrorInfoPayload(x) {
     return false;
   }
   const e = x;
-  return typeof e.attempt === "number" && Number.isFinite(e.attempt) && e.attempt >= 1 && typeof e.error === "string" && e.error.length <= 500 && typeof e.error_type === "string" && typeof e.delay_s === "number" && Number.isFinite(e.delay_s) && e.delay_s >= 0 && (e.permanent === void 0 || typeof e.permanent === "boolean");
+  return typeof e.attempt === "number" && // Integer-only (not merely finite) — mirrors the backend Pydantic `int`
+  // schema and the Python SDK's strict `RetryErrorInfo.attempt`, so a
+  // fractional attempt (e.g. 1.5) is dropped identically in both SDKs.
+  Number.isInteger(e.attempt) && e.attempt >= 1 && typeof e.error === "string" && e.error.length <= 500 && typeof e.error_type === "string" && typeof e.delay_s === "number" && Number.isFinite(e.delay_s) && e.delay_s >= 0 && (e.permanent === void 0 || typeof e.permanent === "boolean");
 }
 var _tokenStore = /* @__PURE__ */ new WeakMap();
 var _additionalCredsStore = /* @__PURE__ */ new WeakMap();
@@ -10112,7 +10180,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.23.3";
+var SDK_VERSION = "0.24.2";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 function pyUnquote(s) {
   if (!s.includes("%")) return s;
@@ -10183,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;
@@ -10381,7 +10453,14 @@ var PROXY_FORBIDDEN_HEADER_NAMES = /* @__PURE__ */ new Set([
   "x-goog-authorization",
   "x-goog-iam-authorization-token",
   "x-stripe-account",
-  "x-shopify-access-token"
+  "x-shopify-access-token",
+  // Method tunnelling: OData V2 (SAP S/4HANA) and several enterprise APIs
+  // honour these as an override of the real HTTP verb. The policy gate
+  // classifies on the wire method, so a tunnelled verb would split the
+  // operation the gate names from the one the provider executes.
+  "x-http-method",
+  "x-http-method-override",
+  "x-method-override"
 ]);
 var MAX_CONTEXT_LENGTH = 4096;
 var MAX_CONTEXT_KEYS = 20;
@@ -10418,9 +10497,10 @@ function validateAndSerializeContext(context) {
         `context keys must be strings, got ${typeof k}`
       );
     }
-    if (k.length > MAX_CONTEXT_KEY_LENGTH) {
+    const keyLength = [...k].length;
+    if (keyLength > MAX_CONTEXT_KEY_LENGTH) {
       throw new AlterValueError(
-        `context key "${k.slice(0, 32)}" exceeds max length (${k.length} > ${MAX_CONTEXT_KEY_LENGTH})`
+        `context key "${k.slice(0, 32)}" exceeds max length (${keyLength} > ${MAX_CONTEXT_KEY_LENGTH})`
       );
     }
     const v = context[k];
@@ -10429,9 +10509,10 @@ function validateAndSerializeContext(context) {
         `context value for key "${k}" must be a string, got ${typeof v}`
       );
     }
-    if (v.length > MAX_CONTEXT_VALUE_LENGTH) {
+    const valueLength = [...v].length;
+    if (valueLength > MAX_CONTEXT_VALUE_LENGTH) {
       throw new AlterValueError(
-        `context value for key "${k}" exceeds max length (${v.length} > ${MAX_CONTEXT_VALUE_LENGTH})`
+        `context value for key "${k}" exceeds max length (${valueLength} > ${MAX_CONTEXT_VALUE_LENGTH})`
       );
     }
   }
@@ -10451,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]+$/;
@@ -10531,11 +10629,28 @@ function connectMetadataToWire(metadata) {
   }
   return wire;
 }
-var GRANT_POLICY_INPUT_KEYS = /* @__PURE__ */ new Set([
-  "expiresAt",
-  "maxTtlSeconds",
-  "defaultTtlSeconds"
-]);
+var GRANT_POLICY_CAMEL_TO_WIRE = [
+  ["expiresAt", "expires_at"],
+  ["maxTtlSeconds", "max_ttl_seconds"],
+  ["defaultTtlSeconds", "default_ttl_seconds"]
+];
+var GRANT_POLICY_INPUT_KEYS = new Set(
+  GRANT_POLICY_CAMEL_TO_WIRE.map(([camelKey]) => camelKey)
+);
+function assertParseableExpiresAt(value) {
+  if (typeof value !== "string" || value.length === 0 || Number.isNaN(Date.parse(value))) {
+    throw new AlterValueError(
+      "grantPolicy.expiresAt must be a non-empty ISO 8601 string when provided"
+    );
+  }
+}
+function assertPositiveIntegerSeconds(camelKey, value) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new AlterValueError(
+      `grantPolicy.${camelKey} must be a positive integer (seconds) when provided`
+    );
+  }
+}
 function grantPolicyInputToWire(policy) {
   if (policy === null || typeof policy !== "object" || Array.isArray(policy)) {
     throw new AlterValueError(
@@ -10545,32 +10660,57 @@ function grantPolicyInputToWire(policy) {
   for (const key of Object.keys(policy)) {
     if (!GRANT_POLICY_INPUT_KEYS.has(key)) {
       throw new AlterValueError(
-        `grantPolicy contains unknown key "${key}" (allowed: expiresAt, maxTtlSeconds, defaultTtlSeconds). Note: keys are camelCase in the TypeScript SDK \u2014 snake_case keys like max_ttl_seconds are the Python SDK surface.`
+        `grantPolicy contains unknown key "${key}" (allowed: ${[...GRANT_POLICY_INPUT_KEYS].join(", ")}). Note: keys are camelCase in the TypeScript SDK \u2014 snake_case keys like max_ttl_seconds are the Python SDK surface.`
       );
     }
   }
   const wire = {};
-  if (policy.expiresAt !== void 0 && policy.expiresAt !== null) {
-    if (typeof policy.expiresAt !== "string" || policy.expiresAt.length === 0) {
+  for (const [camelKey, wireKey] of GRANT_POLICY_CAMEL_TO_WIRE) {
+    const value = policy[camelKey];
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (camelKey === "expiresAt") {
+      assertParseableExpiresAt(value);
+    } else {
+      assertPositiveIntegerSeconds(camelKey, value);
+    }
+    wire[wireKey] = value;
+  }
+  return wire;
+}
+function _mintGrantPolicyToWire(policy) {
+  for (const spelling of ["defaultTtlSeconds", "default_ttl_seconds"]) {
+    if (Object.prototype.hasOwnProperty.call(policy, spelling)) {
       throw new AlterValueError(
-        "grantPolicy.expiresAt must be a non-empty ISO 8601 string when provided"
+        `grantPolicy.${spelling} is not supported on mint \u2014 a default TTL is accepted only by Connect sessions (createConnectSession / connect) and createManagedSecretGrant`
       );
     }
-    wire.expires_at = policy.expiresAt;
   }
-  for (const [camelKey, wireKey] of [
-    ["maxTtlSeconds", "max_ttl_seconds"],
-    ["defaultTtlSeconds", "default_ttl_seconds"]
-  ]) {
+  const wire = {};
+  for (const [key, value] of Object.entries(policy)) {
+    if (!GRANT_POLICY_INPUT_KEYS.has(key)) {
+      wire[key] = value;
+    }
+  }
+  for (const [camelKey, wireKey] of GRANT_POLICY_CAMEL_TO_WIRE) {
     const value = policy[camelKey];
-    if (value === void 0 || value === null) {
+    if (value === void 0) {
       continue;
     }
-    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    if (Object.prototype.hasOwnProperty.call(policy, wireKey)) {
       throw new AlterValueError(
-        `grantPolicy.${camelKey} must be a positive integer (seconds) when provided`
+        `grantPolicy sets both "${camelKey}" and "${wireKey}" \u2014 supply exactly one spelling of the field`
       );
     }
+    if (value === null) {
+      continue;
+    }
+    if (camelKey === "expiresAt") {
+      assertParseableExpiresAt(value);
+    } else {
+      assertPositiveIntegerSeconds(camelKey, value);
+    }
     wire[wireKey] = value;
   }
   return wire;
@@ -10697,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,
@@ -10735,6 +10885,9 @@ var HttpClient = class {
       return response;
     } finally {
       clearTimeout(timeoutId);
+      if (callerSignal !== void 0 && onCallerAbort !== void 0) {
+        callerSignal.removeEventListener("abort", onCallerAbort);
+      }
     }
   }
   /**
@@ -10847,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") {
@@ -11428,8 +11581,13 @@ ${label}:${value}`;
         };
         throw new ScopeReauthRequiredError(
           _messageOr(errorData, "Grant is missing required scopes"),
-          details.grant_id ?? void 0,
-          details.provider_id ?? void 0,
+          // `?? undefined` alone only replaces null — a NON-string grant_id /
+          // provider_id (number, object, bool) would be cast `as string` and
+          // flow through as the wrong runtime value. typeof-guard instead, to
+          // match every sibling branch in this method AND the Python SDK's
+          // `_handle_forbidden` scope_mismatch branch (isinstance → None).
+          typeof details.grant_id === "string" ? details.grant_id : void 0,
+          typeof details.provider_id === "string" ? details.provider_id : void 0,
           response.status,
           // No provider response body on this path — the backend refused at
           // /sdk/token before any provider call, so responseBody is left unset
@@ -11471,6 +11629,15 @@ ${label}:${value}`;
     }
     if (response.status === HTTP_CONFLICT) {
       const errorData = await __VaultClient.#safeParseJson(response);
+      if (errorData.error === "managed_oauth_scope_approval_required") {
+        throw new ConnectConfigError(
+          _messageOr(
+            errorData,
+            "The requested permissions require managed OAuth approval."
+          ),
+          errorData
+        );
+      }
       if (errorData.error === "token_refresh_in_progress") {
         throw new TokenRefreshInProgressError(
           _messageOr(
@@ -12038,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(
@@ -12551,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
@@ -12928,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.
    */
@@ -13350,6 +13545,16 @@ ${label}:${value}`;
    *   entry. Thrown before any wire traffic (parity with the Python SDK).
    * @throws AlterSDKError if the SDK instance is closed
    * @throws NetworkError if the connection to the backend fails
+   * @throws ConnectConfigError if the session's requested scopes exceed what
+   *   the Alter-managed OAuth client is approved for (HTTP 409
+   *   `managed_oauth_scope_approval_required`). NOT a `BackendError` — a
+   *   caller that branches only on `BackendError` leaves this uncaught.
+   *   `details` carries the whole 409 body: `details.details.provider_id` and
+   *   `details.details.unapproved_scopes` name what needs approving,
+   *   `details.remediation.action` / `.description` carry the typed remedy,
+   *   and `details.retryable` is `false`. Retrying is futile: contact Alter to
+   *   approve the scopes, or narrow the app's configured scopes to the
+   *   approved set, and only then create a new Connect session.
    * @throws BackendError if the backend rejects the request (e.g.
    *   `scope_not_allowed` when a requested scope is not in the app's Dev
    *   Portal allowlist)
@@ -13682,6 +13887,10 @@ ${label}:${value}`;
    *   authorized grant is revoked because the user's usage limits could not be
    *   applied. In the last case, `details.failed_grants` contains the typed
    *   failure data in snake_case wire form.
+   * @throws BackendError if identity synchronization could not be completed —
+   *   `statusCode` 503 (transient, with `details.retry_after_seconds`) or 409
+   *   (an operator must repair the provider; no retry hint). Not a
+   *   `ConnectFlowError`: the flow itself was fine.
    * @throws AlterSDKError if SDK is closed or session creation fails
    */
   async connect(options) {
@@ -13726,12 +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` from `session_expired`.
+   *     `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). 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
@@ -13739,6 +13953,11 @@ ${label}:${value}`;
    *     total-failure error carries
    *     `details.failed_grants`; partial failures are surfaced on every
    *     returned result as `failedGrants`.
+   * @throws BackendError if identity synchronization could not be completed.
+   *     `statusCode` says whether to come back: 503 is transient contention
+   *     and `details.retry_after_seconds` carries the backoff hint, while 409
+   *     is an operator-repairable provider fault (disabled provider, duplicate
+   *     group name) that no retry will clear and which carries no hint.
    * @throws AlterSDKError if the SDK instance has been closed.
    */
   async pollConnectSession(sessionToken, options) {
@@ -13746,11 +13965,48 @@ ${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();
-      const pollResult = await this.#pollSession(sessionToken);
+      let pollResult;
+      try {
+        pollResult = await this.#pollSession(sessionToken);
+      } catch (e) {
+        if (!(e instanceof RateLimitError)) {
+          throw e;
+        }
+        const remaining2 = deadline - performance.now();
+        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;
+        if (typeof e.retryAfter === "number" && e.retryAfter > 0) {
+          backoffMs = Math.max(e.retryAfter * 1e3, pollIntervalMs);
+        }
+        await new Promise(
+          (resolve5) => setTimeout(resolve5, Math.min(backoffMs, remaining2))
+        );
+        this.#assertNotClosed();
+        continue;
+      }
       const pollStatus = pollResult.status;
       if (pollStatus === "completed") {
         const rawGrants = pollResult.grants;
@@ -13848,7 +14104,15 @@ ${label}:${value}`;
             }
           );
         }
-        const errorDetails = { error_code: errorCode };
+        const errorDetails = {
+          error_code: errorCode
+        };
+        const retryAfter = _coerceInt(
+          err2.retry_after_seconds
+        );
+        if (retryAfter !== void 0) {
+          errorDetails.retry_after_seconds = retryAfter;
+        }
         if (errorCode === "connect_denied") {
           throw new ConnectDeniedError(errorMessage, errorDetails);
         }
@@ -13858,17 +14122,29 @@ ${label}:${value}`;
           "invalid_client",
           "unauthorized_client",
           "provider_configuration_unavailable",
-          "shared_dev_credential_unavailable"
+          "shared_dev_credential_unavailable",
+          "managed_oauth_scope_approval_required"
         ].includes(errorCode)) {
           throw new ConnectConfigError(errorMessage, errorDetails);
         }
+        const identitySyncStatus = Object.hasOwn(
+          IDENTITY_SYNC_POLL_STATUS,
+          errorCode
+        ) ? IDENTITY_SYNC_POLL_STATUS[errorCode] : void 0;
+        if (identitySyncStatus !== void 0) {
+          throw new BackendError(
+            errorMessage,
+            errorDetails,
+            identitySyncStatus
+          );
+        }
         throw new ConnectFlowError(errorMessage, errorDetails);
       }
       if (pollStatus === "expired") {
         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(
@@ -13881,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;
@@ -13890,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" })
     );
   }
   /**
@@ -13955,6 +14271,14 @@ ${label}:${value}`;
    *     shape (popup, mobile redirect, headless). The convenience
    *     method doesn't infer these from the error.
    * @throws AlterValueError if `error.providerId` is `undefined`.
+   * @throws ConnectConfigError if the recovery session could not be minted
+   *     because the Alter-managed OAuth client is not approved for the scopes
+   *     this app requests (HTTP 409 `managed_oauth_scope_approval_required`).
+   *     This helper forwards to `createConnectSession`, so it throws
+   *     everything that method throws — see its `@throws` list for the
+   *     `details` payload. Retrying is futile: contact Alter to approve the
+   *     scopes, or narrow the app's configured scopes to the approved set, and
+   *     only then mint a recovery session.
    */
   async createConnectSessionForError(error51, options) {
     const providerId = error51.providerId;
@@ -14096,6 +14420,11 @@ ${label}:${value}`;
    *   `pollIntervalMs` is non-finite or not greater than zero.
    * @throws AlterSDKError if the SDK is closed or the IDP returned a terminal
    *   error / the session expired.
+   * @throws BackendError if identity synchronization could not be completed.
+   *   Surfaced separately from the terminal `AlterSDKError` above precisely
+   *   because it is NOT a rejected login: `statusCode` 503 is transient
+   *   contention carrying `details.retry_after_seconds`, and 409 is an
+   *   operator-repairable provider fault that no retry will clear.
    * @throws ConnectTimeoutError if the user did not complete login in time
    *   (`details.reason` is `"poll_deadline_elapsed"`).
    */
@@ -14127,8 +14456,22 @@ ${label}:${value}`;
           });
         }
         if (pollData.status === "error") {
-          const errorMessage = pollData.error_message || "unknown error";
-          throw new AlterSDKError(`Authentication failed: ${errorMessage}`);
+          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 = 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);
+            if (retryAfter !== void 0) {
+              details.retry_after_seconds = retryAfter;
+            }
+            throw new BackendError(message, details, identitySyncStatus);
+          }
+          throw new AlterSDKError(message);
         }
         if (pollData.status === "expired") {
           throw new AlterSDKError("Authentication session expired");
@@ -14145,10 +14488,13 @@ ${label}:${value}`;
         (resolve5) => setTimeout(resolve5, Math.min(pollIntervalMs, remaining))
       );
     }
-    throw new ConnectTimeoutError("Authentication timed out", {
-      timeoutMs,
-      reason: "poll_deadline_elapsed"
-    });
+    throw new ConnectTimeoutError(
+      `Authentication timed out after ${timeoutMs}ms. The user may not have completed login in the browser.`,
+      {
+        timeoutMs,
+        reason: "poll_deadline_elapsed"
+      }
+    );
   }
   /**
    * Single sign-in poll attempt (INTERNAL).
@@ -14712,12 +15058,13 @@ ${label}:${value}`;
   async #mapProxyErrorResponse(response) {
     let detail = {};
     try {
-      const errBody = await response.clone().json();
-      detail = errBody.detail || errBody || {};
+      const parsed = await response.clone().json();
+      const payloadDict = isPlainRecord(parsed) ? parsed : {};
+      detail = isPlainRecord(payloadDict.detail) ? payloadDict.detail : payloadDict;
     } catch {
     }
     const errCode = detail.error || "";
-    const msg = detail.message || `/sdk/proxy returned ${response.status}`;
+    const msg = typeof detail.message === "string" && detail.message ? detail.message : `/sdk/proxy returned ${response.status}`;
     if (errCode === "approval_denied")
       throw new ApprovalDeniedError({ message: msg });
     if (errCode === "approval_expired")
@@ -14740,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) {
@@ -14752,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") {
@@ -14801,11 +15183,21 @@ ${label}:${value}`;
    * @throws ApprovalExpiredError on `expired`.
    * @throws ApprovalExecutionFailedError on `failed`.
    * @throws ApprovalTimeoutError if the local wait elapses before any decision.
+   * @throws AlterValueError if `timeoutMs` is not a finite number, or
+   *   `pollIntervalMs` is non-finite or not greater than zero.
    */
   async awaitApproval(approvalId, options = {}) {
     this.#assertNotClosed();
     const timeoutMs = options.timeoutMs ?? 3e5;
     const pollIntervalMs = options.pollIntervalMs ?? 2e3;
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+      throw new AlterValueError("timeoutMs must be a finite number");
+    }
+    if (typeof pollIntervalMs !== "number" || !Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+      throw new AlterValueError(
+        "pollIntervalMs must be a finite number greater than 0"
+      );
+    }
     const deadline = Date.now() + timeoutMs;
     let lastTransient = null;
     while (true) {
@@ -14813,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;
         }
@@ -14831,16 +15253,18 @@ ${label}:${value}`;
             lastTransient
           );
         }
-        const sleep2 = Math.max(
-          100,
-          Math.min(pollIntervalMs, deadline - Date.now())
+        const sleep2 = Math.min(
+          pollIntervalMs,
+          Math.max(0, deadline - Date.now())
         );
         await new Promise((res) => setTimeout(res, sleep2));
         continue;
+      } finally {
+        if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
       }
       lastTransient = null;
       if (status.status === "executed" && !status.hasResult) {
-        const next = Math.max(100, deadline - Date.now());
+        const next = Math.max(0, deadline - Date.now());
         await new Promise((r) => setTimeout(r, Math.min(pollIntervalMs, next)));
         continue;
       }
@@ -14867,9 +15291,9 @@ ${label}:${value}`;
               lastTransient
             );
           }
-          const sleep2 = Math.max(
-            100,
-            Math.min(pollIntervalMs, deadline - Date.now())
+          const sleep2 = Math.min(
+            pollIntervalMs,
+            Math.max(0, deadline - Date.now())
           );
           await new Promise((res) => setTimeout(res, sleep2));
           continue;
@@ -14879,7 +15303,7 @@ ${label}:${value}`;
       if (now >= deadline) {
         throw this.#buildApprovalTimeout(approvalId, timeoutMs, lastTransient);
       }
-      const sleep = Math.max(100, Math.min(pollIntervalMs, deadline - now));
+      const sleep = Math.min(pollIntervalMs, Math.max(0, deadline - now));
       await new Promise((res) => setTimeout(res, sleep));
     }
   }
@@ -15652,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);
@@ -15841,11 +16265,18 @@ var App = class _App {
    * @param options.label - Required sibling address (resolution key:
    *   provider + label). Must be unique among the credential's active
    *   sibling grants.
-   * @param options.grantPolicy - Optional per-grant policy
-   *   (snake_case wire keys — e.g. `expires_at`, `max_ttl_seconds`,
-   *   `restrictions`, `requires_approval`). Validated server-side; an
-   *   invalid policy throws `BackendError` from the 422
-   *   `invalid_grant_policy` response.
+   * @param options.grantPolicy - Optional per-grant policy. `expiresAt`
+   *   and `maxTtlSeconds` are accepted in this SDK's camelCase
+   *   (validated locally and mapped to the snake_case wire keys,
+   *   exactly like `createConnectSession`); the wider policy grammar
+   *   (`restrictions`, `requires_approval`, …) uses the backend's
+   *   snake_case keys and is validated server-side — an invalid policy
+   *   throws `BackendError` from the 422 `invalid_grant_policy`
+   *   response. A default TTL is not part of the mint grammar:
+   *   `defaultTtlSeconds` / `default_ttl_seconds` throws
+   *   `AlterValueError` (it is accepted only by Connect sessions and
+   *   `createManagedSecretGrant`). Supplying both spellings of one
+   *   trio field also throws `AlterValueError`.
    * @param options.grantTags - Optional list of tag strings stored on
    *   the sibling grant.
    * @returns {@link GrantInfo} for the newly minted sibling grant
@@ -15881,7 +16312,7 @@ var App = class _App {
     }
     const wireBody = { label: options.label };
     if (options.grantPolicy !== void 0) {
-      wireBody.grant_policy = options.grantPolicy;
+      wireBody.grant_policy = _mintGrantPolicyToWire(options.grantPolicy);
     }
     if (options.grantTags !== void 0) {
       wireBody.grant_tags = options.grantTags;
@@ -16066,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);
@@ -16323,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.8.0";
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var CLI_VERSION = "0.9.1";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -16569,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);
@@ -17330,7 +17761,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.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.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"
@@ -18485,6 +18916,25 @@ var AuditNamespace = class {
     });
     return expectDict(body, "audit.list", 200);
   }
+  /** Provider facet values present in one app's audit events. Requires
+   *  `dashboard_audit:read`.
+   *
+   * Returns ``{providers}`` — the alphabetized distinct provider ids
+   * (OAuth provider ids, managed-secret template ids — a custom secret's
+   * name-derived slug — and IDP types) actually
+   * present on the app's audit rows; the accepted vocabulary for the
+   * ``--provider`` filters. Data-derived, never a hardcoded shortlist.
+   */
+  async providers(appId) {
+    const query = optionsToQuery({ app_id: appId });
+    const body = await this.#client._call(
+      "GET",
+      "/audit-logs/unified/providers",
+      "audit.providers",
+      { query }
+    );
+    return expectDict(body, "audit.providers", 200);
+  }
   /** List dashboard / CLI admin actions. Requires `dashboard_audit:read`.
    *
    * Returns the canonical envelope ``{items, total, limit, offset, has_more}``
@@ -19281,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();
@@ -19833,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;
@@ -19846,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")`
@@ -19860,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);
@@ -20118,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;
@@ -20312,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;
       }
@@ -20367,6 +20882,7 @@ function buildAgentsCommand() {
           "alter: the api_key field above is shown ONCE and cannot be retrieved later.\n"
         );
         surfaceApproverWarnings(result);
+        surfaceScopeWarnings(result);
       });
     }
   );
@@ -20586,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(
@@ -35607,6 +36124,9 @@ var CONTENT_MATCH_LIMITS = {
 };
 var MAX_RULE_NAME_LEN = 120;
 var MAX_RULE_DESCRIPTION_LEN = 2e3;
+var MAX_RULES_PER_TARGET = 100;
+var MAX_DERIVED_RULES_PER_TARGET = 2;
+var MAX_POLICY_RULE_PAGE_SIZE = MAX_RULES_PER_TARGET + MAX_DERIVED_RULES_PER_TARGET;
 var HITL_NOTIFICATION_CHANNELS = ["email"];
 var HITL_LIMITS = {
   maxApprovers: 10,
@@ -35651,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"]
@@ -36077,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),
@@ -36093,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,
@@ -36608,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)."
@@ -37302,6 +37828,33 @@ function buildAuditCommand() {
       });
     }
   );
+  audit.command("providers").description(
+    "List the provider IDs present in an app's audit events \u2014 the values `--provider` accepts (OAuth provider ids, managed-secret template ids \u2014 a custom secret's name-derived slug \u2014 and IDP types). Derived from the audit data, so providers whose config was since deleted still appear."
+  ).option(
+    APP_FLAG,
+    "App whose audit trail to facet (ID or name; falls back to ALTER_APP_ID / the workspace pin)"
+  ).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(async (options) => {
+    const format = coerceOutputFormat(options.output);
+    const appId = await resolveAppOrExit(options.app);
+    await withClient(async (client) => {
+      const result = await client.audit.providers(appId);
+      const providers = result["providers"];
+      if (!Array.isArray(providers) || !providers.every((p) => typeof p === "string")) {
+        err(
+          'audit.providers: response is missing the "providers" string array. This is a wire-format regression; report it to the backend team.'
+        );
+        process.exit(EXIT_ERROR);
+      }
+      const rows = providers.map((provider_id) => ({ provider_id }));
+      emit2(format, rows, [
+        { label: "PROVIDER", get: (r) => r.provider_id }
+      ]);
+    });
+  });
   audit.command("show <trace-id>").description("Show every event for one trace").option(
     "--output <format>",
     "Output format: json|jsonl|table (default: json)",
@@ -40782,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",
@@ -41186,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;
@@ -41522,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 },
@@ -41991,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)",
@@ -42008,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(
@@ -42120,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"
         );
@@ -42504,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(
@@ -42794,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)",
@@ -42811,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(
@@ -44326,8 +44918,8 @@ function buildRulesSubcommand() {
     )
   ).option(
     "--limit <n>",
-    "Page size (1-100; when omitted the backend default of 100 applies)",
-    parseBoundedInt("--limit", 1, 100)
+    `Page size (1-${MAX_POLICY_RULE_PAGE_SIZE}; when omitted the backend default of ${MAX_POLICY_RULE_PAGE_SIZE} applies)`,
+    parseBoundedInt("--limit", 1, MAX_POLICY_RULE_PAGE_SIZE)
   ).option(
     "--offset <n>",
     "Page offset (default 0)",
@@ -44761,7 +45353,8 @@ async function providerCatalogError(client, providerId, environment, credentialS
   const availableScopes = provider.available_scopes ?? {};
   if (Object.keys(availableScopes).length === 0) {
     if (scopes !== void 0 && scopes.length > 0) {
-      return `alter: provider '${providerId}' publishes no selectable scopes \u2014 omit --scopes (Alter does not send a scope parameter to it)
+      const where = provider.scopes_configured_on_provider === true ? `; its permissions are configured on the ${provider.display_name} app itself` : "";
+      return `alter: provider '${providerId}' publishes no selectable scopes \u2014 omit --scopes (Alter does not send a scope parameter to it${where})
 `;
     }
     return null;