lua-cli 3.32.4 → 3.32.6

package/dist/index.js

@@ -65,6 +65,16 @@ var init_auth_error = __esm({
 });
 
 // src/errors/cli.error.ts
+function apiErrorDetail(error) {
+  return {
+    serverCode: error?.code,
+    issues: error?.issues,
+    upstream: error?.upstream,
+    requestId: error?.requestId,
+    vendor: error?.vendor,
+    retryAfterSeconds: error?.retryAfterSeconds
+  };
+}
 function isTypedCliError(error) {
   return CliError.isCliError(error) || AuthenticationError.isAuthenticationError(error);
 }
@@ -93,6 +103,17 @@ function debugEnabled() {
   const v = process.env.LUA_DEBUG;
   return debugFlag || v === "1" || v === "true" || v === "yes";
 }
+function upstreamUnavailableHint(upstream, requestId) {
+  const service = typeof upstream === "string" && upstream ? `its ${upstream} service` : "a service behind it";
+  const ref = typeof requestId === "string" && requestId ? ` If it persists, quote request ${requestId}.` : "";
+  return `The Lua API is up, but ${service} is temporarily unavailable (503 UPSTREAM_UNAVAILABLE) \u2014 retry in a moment.${ref}`;
+}
+function vendorUnavailableHint(vendor, requestId, retryAfterSeconds) {
+  const name = typeof vendor === "string" && vendor ? VENDOR_LABELS[vendor] ?? vendor : "a vendor it depends on";
+  const ref = typeof requestId === "string" && requestId ? ` If it persists, quote request ${requestId}.` : "";
+  const retry = typeof retryAfterSeconds === "number" ? "retry in a moment" : "the request may have applied at the vendor \u2014 check before retrying";
+  return `The Lua API is up, but ${name} is temporarily unavailable (503 VENDOR_UNAVAILABLE) \u2014 ${retry}.${ref}`;
+}
 function authHint(error) {
   if (error.suppressDefaultRemediation) return void 0;
   if (error.reason === "no_agent_access") {
@@ -116,7 +137,10 @@ function classifyCliError(error) {
       code: error.code,
       exitCode: error.exitCode,
       message: error.message,
-      hint: error.hint
+      hint: error.hint,
+      statusCode: error.statusCode,
+      serverCode: error.serverCode,
+      issues: error.issues
     };
   }
   if (AuthenticationError.isAuthenticationError(error)) {
@@ -138,30 +162,36 @@ function classifyCliError(error) {
   }
   const status = numericStatus(e);
   if (status !== void 0) {
+    const statusCode = status;
     if (status === 401) return {
       code: "auth",
       exitCode: CLI_EXIT.AUTH,
-      message
+      message,
+      statusCode
     };
     if (status === 403) return {
       code: "forbidden",
       exitCode: CLI_EXIT.FORBIDDEN,
-      message
+      message,
+      statusCode
     };
     if (status === 404) return {
       code: "not_found",
       exitCode: CLI_EXIT.NOT_FOUND,
-      message
+      message,
+      statusCode
     };
     if (status >= 400 && status < 500) return {
       code: `http_${status}`,
       exitCode: CLI_EXIT.FORBIDDEN,
-      message
+      message,
+      statusCode
     };
     if (status >= 500 || status === 0) return {
       code: "unavailable",
       exitCode: CLI_EXIT.UNAVAILABLE,
-      message
+      message,
+      statusCode
     };
   }
   const causeCode = e.cause?.code;
@@ -179,9 +209,18 @@ function classifyCliError(error) {
     message
   };
 }
+function issueLines(issues) {
+  return (issues ?? []).map((issue) => {
+    const where = issue.path !== void 0 ? `${issue.path || "/"}: ` : "";
+    const what = issue.message ?? issue.code ?? "invalid";
+    const tag = issue.message && issue.code ? ` (${issue.code})` : "";
+    return `   \u2022 ${where}${what}${tag}`;
+  });
+}
 function renderCliError(reported, options = {}) {
   const lines = [
-    `\u2716 ${reported.code}: ${reported.message}`
+    `\u2716 ${reported.code}: ${reported.message}`,
+    ...issueLines(reported.issues)
   ];
   for (const hint of [
     reported.hint,
@@ -193,9 +232,30 @@ function renderCliError(reported, options = {}) {
   if (options.stack) lines.push("", options.stack);
   return lines;
 }
+function cliErrorEnvelope(error) {
+  const reported = classifyCliError(error);
+  return {
+    success: false,
+    error: {
+      code: reported.serverCode ?? reported.code,
+      ...reported.statusCode !== void 0 ? {
+        statusCode: reported.statusCode
+      } : {},
+      message: reported.message,
+      ...reported.issues?.length ? {
+        issues: reported.issues
+      } : {}
+    }
+  };
+}
 function reportCliError(error, options = {}) {
   const reported = classifyCliError(error);
   const stack = debugEnabled() && error instanceof Error ? error.stack : void 0;
+  if (options.json) {
+    console.log(JSON.stringify(cliErrorEnvelope(error), null, 2));
+    if (stack) console.error(stack);
+    return reported;
+  }
   for (const line of renderCliError(reported, {
     extraHint: options.extraHint,
     stack
@@ -224,7 +284,7 @@ function reportUnhandledCliError(error) {
   process.exitCode = reported.exitCode;
   return reported.exitCode;
 }
-var CLI_EXIT, CliError, HandledCliError, debugFlag, NETWORK_ERRNO, NETWORK_MESSAGE, UNAVAILABLE_HINT, CLI_EXIT_CODE_HELP;
+var CLI_EXIT, CliError, HandledCliError, debugFlag, NETWORK_ERRNO, NETWORK_MESSAGE, UNAVAILABLE_HINT, VENDOR_LABELS, CLI_EXIT_CODE_HELP;
 var init_cli_error = __esm({
   "src/errors/cli.error.ts"() {
     "use strict";
@@ -238,6 +298,7 @@ var init_cli_error = __esm({
       FORBIDDEN: 10,
       UNAVAILABLE: 11
     };
+    __name(apiErrorDetail, "apiErrorDetail");
     CliError = class _CliError extends Error {
       static {
         __name(this, "CliError");
@@ -247,6 +308,8 @@ var init_cli_error = __esm({
       exitCode;
       hint;
       statusCode;
+      serverCode;
+      issues;
       constructor(code, message, options = {}) {
         super(message);
         this.name = "CliError";
@@ -254,6 +317,8 @@ var init_cli_error = __esm({
         this.exitCode = options.exitCode ?? CLI_EXIT.ERROR;
         this.hint = options.hint;
         this.statusCode = options.statusCode;
+        this.serverCode = options.serverCode;
+        this.issues = options.issues?.length ? options.issues : void 0;
         if (Error.captureStackTrace) Error.captureStackTrace(this, _CliError);
       }
       /** Bad arguments, an unknown action, no project — exit 2. */
@@ -282,19 +347,23 @@ var init_cli_error = __esm({
       /**
       * An API refusal the site already holds the status of (LUA-766) — classified by the same table the top-level
       * classifier applies to an untyped error: 401 auth · 403 forbidden · 404 not_found · other 4xx `http_<status>`
-      * (10) · 5xx / 0 unavailable (11, with the network hint unless the site gives its own) · no status `error` (1).
+      * (10) · 5xx / 0 unavailable (11, with the network hint unless the site gives its own — or the body's code
+      * picks one: a 503 UPSTREAM_UNAVAILABLE names the Lua service behind the API, LUA-810) · no status `error` (1).
       * A command that reads `response.error.statusCode` throws through here, so `lua logs` on a 503 exits 11 like
       * every other verb instead of printing the message itself and then throwing an exit-1 `Error`.
       */
-      static fromStatus(statusCode, message, hint) {
+      static fromStatus(statusCode, message, hint, detail = {}) {
         const reported = classifyCliError(Object.assign(new Error(message), {
           statusCode
         }));
+        const codeHint = detail.serverCode === "UPSTREAM_UNAVAILABLE" ? upstreamUnavailableHint(detail.upstream, detail.requestId) : detail.serverCode === "VENDOR_UNAVAILABLE" ? vendorUnavailableHint(detail.vendor, detail.requestId, detail.retryAfterSeconds) : void 0;
         const classHint = reported.exitCode === CLI_EXIT.UNAVAILABLE ? UNAVAILABLE_HINT : reported.hint;
         return new _CliError(reported.code, message, {
           exitCode: reported.exitCode,
-          hint: hint ?? classHint,
-          statusCode
+          hint: hint ?? codeHint ?? classHint,
+          statusCode,
+          serverCode: detail.serverCode,
+          issues: detail.issues
         });
       }
       static isCliError(error) {
@@ -340,10 +409,20 @@ var init_cli_error = __esm({
     ]);
     NETWORK_MESSAGE = /fetch failed|socket hang up|network request failed|request timeout|ECONNREFUSED|ENOTFOUND/i;
     UNAVAILABLE_HINT = "The Lua API could not be reached \u2014 check your network and https://status.heylua.ai, then retry.";
+    __name(upstreamUnavailableHint, "upstreamUnavailableHint");
+    VENDOR_LABELS = {
+      unified: "Unified.to",
+      github: "GitHub",
+      pusher: "Pusher",
+      google: "Google"
+    };
+    __name(vendorUnavailableHint, "vendorUnavailableHint");
     __name(authHint, "authHint");
     __name(numericStatus, "numericStatus");
     __name(classifyCliError, "classifyCliError");
+    __name(issueLines, "issueLines");
     __name(renderCliError, "renderCliError");
+    __name(cliErrorEnvelope, "cliErrorEnvelope");
     __name(reportCliError, "reportCliError");
     __name(commanderExitCode, "commanderExitCode");
     __name(reportUnhandledCliError, "reportUnhandledCliError");
@@ -1066,6 +1145,18 @@ function modelUnresolvedMessage(r) {
   }
   return r.candidates.length ? `model "${r.requested}" does not resolve to an approved model \u2014 accepted forms: ${r.candidates.join(", ")}` : `model "${r.requested}" does not resolve to an approved model \u2014 accepted forms are the registry's provider-prefixed ids (provider/model) or a bare id that names exactly one of them`;
 }
+function providerModelId(code) {
+  const requested = typeof code === "string" ? code.trim() : "";
+  if (!requested || isModelIdSentinel(requested)) return requested;
+  const slash = requested.indexOf("/");
+  if (slash <= 0) return requested;
+  const provider = requested.slice(0, slash).toLowerCase();
+  if (MODEL_ID_BYOK_PROVIDERS.includes(provider)) return requested;
+  return requested.slice(slash + 1);
+}
+function providerModelFamily(code) {
+  return providerModelId(code).toLowerCase().replace(MODEL_SNAPSHOT_SUFFIX, "");
+}
 function isImplicitModelSelectionSource(source) {
   return source !== void 0 && IMPLICIT_MODEL_SELECTION_SOURCES.includes(source);
 }
@@ -1179,6 +1270,11 @@ function isDeviceCredentialPrincipal(context) {
 function hasDeviceCredentialType(value3) {
   return DeviceCredentialClaimSchema.safeParse(value3).success;
 }
+function sessionAuthTime(context) {
+  if (!context || context.credential.type !== "firstPartySession") return void 0;
+  const authTime = context.authTime;
+  return typeof authTime === "number" && Number.isInteger(authTime) && authTime >= 0 && authTime <= SESSION_AUTH_TIME_MAX_S ? authTime : void 0;
+}
 function isTypedApiKeyPrincipal(context) {
   return context?.subject.subjectType === "apiKey" && context.credential.type === "apiKey" && !context.compatibility;
 }
@@ -1351,6 +1447,39 @@ function scheduledWorkflowRunId(jobId, scheduledTime) {
   const key = typeof scheduledTime === "number" ? String(scheduledTime) : scheduledTimeKey(scheduledTime);
   return `${WORKFLOW_SCHEDULED_RUN_ID_PREFIX}${jobId}_${key}`;
 }
+function renderWorkflowScheduleKeyTemplate(template3, ctx) {
+  if (!template3) return void 0;
+  const read = /* @__PURE__ */ __name2((path25) => path25.split(".").reduce((o, k) => o && typeof o === "object" ? o[k] : void 0, ctx.input), "read");
+  let unresolved = false;
+  const out = template3.replace(/\$\{\s*([a-zA-Z0-9_.]+)\s*\}/g, (_m, expr) => {
+    let v = "";
+    if (expr === "scheduledTime") v = ctx.scheduledTime ?? "";
+    else if (expr.startsWith("input.")) v = read(expr.slice("input.".length));
+    const s = v === void 0 || v === null ? "" : String(v);
+    if (s === "") unresolved = true;
+    return s;
+  });
+  if (unresolved) return void 0;
+  const key = out.slice(0, WORKFLOW_SCHEDULE_KEY_MAX);
+  return key && /^[A-Za-z0-9:_\-.\/]+$/.test(key) ? key : void 0;
+}
+function scheduledWorkflowIdempotencyKey(jobId, rendered) {
+  const head = `${WORKFLOW_SCHEDULE_IDEMPOTENCY_KEY_PREFIX}${jobId}:`;
+  if (head.length + rendered.length <= WORKFLOW_SCHEDULE_KEY_MAX) return `${head}${rendered}`;
+  const digest = stableKeyDigest(rendered);
+  const room = WORKFLOW_SCHEDULE_KEY_MAX - head.length - digest.length - 1;
+  return `${head}${rendered.slice(0, Math.max(0, room))}~${digest}`;
+}
+function stableKeyDigest(s) {
+  let a = 2166136261;
+  let b = 84696351;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    a = Math.imul(a ^ c, 16777619);
+    b = Math.imul(b ^ c, 16777619) ^ b >>> 13;
+  }
+  return (a >>> 0).toString(16).padStart(8, "0") + (b >>> 0).toString(16).padStart(8, "0");
+}
 function workflowOperationId(runId, stepId, billingEpoch) {
   return `${WORKFLOW_OPERATION_ID_PREFIX}${runId}:${stepId}:${billingEpoch}`;
 }
@@ -1654,7 +1783,59 @@ function extractSingleJsonValue(text) {
     };
   }
 }
-var __defProp2, __name2, REVIEWABLE_ACTION_EXECUTE_TOOL_ALLOWLIST, REVIEWABLE_MCP_SEND_TOOL_SUFFIX, MCP_TOOL_READ_VERB_RE, MCP_DRAFT_CREATE_VERBS, NON_INTERACTIVE_CHANNELS, RICH_PARTS_MESSAGE_ID_PREFIX, SCREENSHOT_MESSAGE_ID_PREFIX, BROWSER_COMMANDS, BROWSER_COMMAND_NAMES, DESKTOP_FILE_COMMANDS, DESKTOP_FILE_COMMAND_SET, MODEL_ID_BYOK_PROVIDERS, REASONING_EFFORT_VALUES, IMPLICIT_MODEL_SELECTION_SOURCES, PLATFORM_FALLBACK_MODEL_SOURCE, AGENT_NAME_TOKEN, DEFAULT_PERSONA_GUIDE, PERSONAL_SPACE_STARTING_PERSONA, AGENT_LOG_SOURCES, CORE_DRAINING_CODE, CORE_DRAINING_DEFAULT_RETRY_MS, CORE_DRAINING_MAX_RETRY_MS, VoiceNameSchema, PluginProviderSchema, RealtimeProviderSchema, PluginClassSchema, ModelDescriptorSchema, InferenceModelSchema, PluginModelSchema, RealtimeModelSchema, LuaVoiceModelSchema, TurnDetectionSchema, InterruptionSchema, BuiltinAudioClipSchema, AudioConfigSchema, BackgroundAudioEntrySchema, BackgroundAudioSchema, LuaVoiceConfigInnerSchema, LuaVoiceConfigSchema, LuaVoiceRefSchema, EventType, LUA_JOB_DEFAULT_TIMEOUT_SECONDS, LUA_JOB_MIN_TIMEOUT_SECONDS, LUA_JOB_MAX_TIMEOUT_SECONDS, TEMPLATE_TRIGGER_URL_ENV_PREFIX, SUBJECT_TYPES, SubjectTypeSchema, CREDENTIAL_TYPES, CredentialTypeSchema, DEVICE_OPERATIONS, DeviceOperationSchema, DEVICE_SCOPE_BY_OPERATION, DeviceBindingSchema, TYPED_API_KEY, IdSchema, PrincipalDescriptorSchema, ActorDescriptorSchema, PrincipalOwnerSchema, CredentialLifecycleSchema, GeneralCredentialDescriptorSchema, DeviceCredentialDescriptorSchema, GeneralPrincipalContextSchema, DeviceCredentialPrincipalContextSchema, RawPrincipalContextSchema, PrincipalContextSchema, DeviceCredentialClaimSchema, LUA_CLIENT_HEADER, LUA_CLIENT_APPS, SEMVER_PATTERN, WEB_RELEASE_PATTERN, CLIENT_HEADER_PATTERN, AUTHZ_PROJECTION_VERSION, ProjectedScopeSchema, DisplayRoleSchema, AuthorizationPrincipalSchema, CredentialContextSchema, ProjectionAnomalySchema, ProjectedOrgSchema, ProjectedResourceSchema, CapabilityProfilesSchema, RoleCatalogSchema, EffectiveAuthorizationSchema, ResourcePageSchema, SYSTEM_USER_PREFIX, WORKFLOW_RUN_IN_FLIGHT, WORKFLOW_RUN_IDLE, WORKFLOW_RUN_TERMINAL, WORKFLOW_RUN_STATUSES, WORKFLOW_STEP_STATUSES, WORKFLOW_STEP_IN_FLIGHT, ARCHIVE_WINDOW_MARGIN_DAYS, WORKFLOW_ORG_PURGING_TTL_S, WORKFLOW_ORG_PURGE_FORCE_AFTER_MS, IDEMPOTENCY_HOLDING_STATUSES, WORKFLOW_SCHEDULED_RUN_ID_PREFIX, CLOUD_TASK_RUN_ID_PREFIX, WORKFLOW_OPERATION_ID_PREFIX, WORKFLOW_JOURNAL_PROTOCOL_VERSION, WORKFLOW_CONNECTION_KEY_RE, WORKFLOW_SIGNAL_PAYLOAD_MAX_BYTES, WORKFLOW_RESOLVE_OUTPUT_MAX_BYTES, WORKFLOW_RETRY_BACKOFFS, WORKFLOW_RETRY_MIN_ATTEMPTS, WORKFLOW_RETRY_POLICY_KEYS, WORKFLOW_RETRY_MAX_ATTEMPTS, WORKFLOW_RETRY_ENGINE_KEYS, WORKFLOW_JOB_RESOURCES, WORKFLOW_SIDE_EFFECTS, WORKFLOW_JOB_RANGES, WORKFLOW_JOB_RANGE_MEMBERS, WORKFLOW_SINGLE_STEP_TYPES, WORKFLOW_HITL_ENTRY_TYPES, WORKFLOW_ARM_ENTRY_TYPES, WORKFLOW_HITL_ARM_CONTAINERS, WORKFLOW_GRAPH_ENTRY_STEP_KINDS, WORKFLOW_ARM_ENTRY_STEP_KINDS, WORKFLOW_BUDGET_MAX_DURATION_SECONDS, REDACTED_PLACEHOLDER, PROVIDER_MESSAGE_MAX_CHARS, ERROR_MESSAGE_MAX_CHARS, SECRET_LITERAL_PATTERNS, SECRET_NAME, SECRET_PAIR_PATTERNS, GROUP_COUNT, WORKFLOW_SECRET_KEY_RE, WORKFLOW_RESERVED_SECRET_KEYS, SCRUB_INPUT_MAX_CHARS, SCRUB_CUT_BACKOFF_CHARS, WORKFLOW_AUDIT_EVENTS, WORKFLOW_AUDIT_METADATA_MAX_BYTES, INDENT, WRAP_WIDTH, NOUNS, GET_TOOL_NAMES, PREAMBLE, WORKFLOW_APPROVAL_OUTPUT_DECISIONS, WORKFLOW_APPROVAL_OUTPUT_SCHEMA, JSON_FENCE_RE;
+function agentFeatureCatalogDefault(featureName) {
+  return DEFAULT_ON_AGENT_FEATURES.includes(featureName);
+}
+function hasExplicitFeatureActive(row2) {
+  return typeof row2?.active === "boolean";
+}
+function effectiveFeatureActive(row2, catalogDefault) {
+  return hasExplicitFeatureActive(row2) ? row2.active : catalogDefault;
+}
+function resolveEffectiveFeature(row2, catalogDefault) {
+  return hasExplicitFeatureActive(row2) ? {
+    active: row2.active,
+    source: "agent",
+    default: catalogDefault
+  } : {
+    active: catalogDefault,
+    source: "default",
+    default: catalogDefault
+  };
+}
+function isFeatureRow(value3) {
+  return typeof value3 === "object" && value3 !== null;
+}
+function effectiveAgentFeatureRows(base, override) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const [name, row2] of Object.entries(base ?? {})) {
+    if (isFeatureRow(row2)) merged.set(name, {
+      row: row2,
+      origin: "baseAgent"
+    });
+  }
+  for (const [name, row2] of Object.entries(override ?? {})) {
+    if (isFeatureRow(row2)) merged.set(name, {
+      row: row2,
+      origin: "subAgent"
+    });
+  }
+  return {
+    rows: Object.fromEntries([
+      ...merged
+    ].map(([name, e]) => [
+      name,
+      e.row
+    ])),
+    origins: Object.fromEntries([
+      ...merged
+    ].map(([name, e]) => [
+      name,
+      e.origin
+    ]))
+  };
+}
+var __defProp2, __name2, REVIEWABLE_ACTION_EXECUTE_TOOL_ALLOWLIST, REVIEWABLE_MCP_SEND_TOOL_SUFFIX, MCP_TOOL_READ_VERB_RE, MCP_DRAFT_CREATE_VERBS, NON_INTERACTIVE_CHANNELS, RICH_PARTS_MESSAGE_ID_PREFIX, SCREENSHOT_MESSAGE_ID_PREFIX, BROWSER_COMMANDS, BROWSER_COMMAND_NAMES, DESKTOP_FILE_COMMANDS, DESKTOP_FILE_COMMAND_SET, MODEL_ID_BYOK_PROVIDERS, MODEL_SNAPSHOT_SUFFIX, REASONING_EFFORT_VALUES, IMPLICIT_MODEL_SELECTION_SOURCES, PLATFORM_FALLBACK_MODEL_SOURCE, AGENT_NAME_TOKEN, DEFAULT_PERSONA_GUIDE, PERSONAL_SPACE_STARTING_PERSONA, AGENT_LOG_SOURCES, CORE_DRAINING_CODE, CORE_DRAINING_DEFAULT_RETRY_MS, CORE_DRAINING_MAX_RETRY_MS, VoiceNameSchema, PluginProviderSchema, RealtimeProviderSchema, PluginClassSchema, ModelDescriptorSchema, InferenceModelSchema, PluginModelSchema, RealtimeModelSchema, LuaVoiceModelSchema, TurnDetectionSchema, InterruptionSchema, BuiltinAudioClipSchema, AudioConfigSchema, BackgroundAudioEntrySchema, BackgroundAudioSchema, LuaVoiceConfigInnerSchema, LuaVoiceConfigSchema, LuaVoiceRefSchema, EventType, LUA_JOB_DEFAULT_TIMEOUT_SECONDS, LUA_JOB_MIN_TIMEOUT_SECONDS, LUA_JOB_MAX_TIMEOUT_SECONDS, TEMPLATE_TRIGGER_URL_ENV_PREFIX, SUBJECT_TYPES, SubjectTypeSchema, CREDENTIAL_TYPES, CredentialTypeSchema, DEVICE_OPERATIONS, DeviceOperationSchema, DEVICE_SCOPE_BY_OPERATION, DeviceBindingSchema, TYPED_API_KEY, IdSchema, SESSION_AUTH_TIME_MAX_S, PrincipalDescriptorSchema, ActorDescriptorSchema, PrincipalOwnerSchema, CredentialLifecycleSchema, GeneralCredentialDescriptorSchema, DeviceCredentialDescriptorSchema, GeneralPrincipalContextSchema, DeviceCredentialPrincipalContextSchema, RawPrincipalContextSchema, PrincipalContextSchema, DeviceCredentialClaimSchema, LUA_CLIENT_HEADER, LUA_CLIENT_APPS, SEMVER_PATTERN, WEB_RELEASE_PATTERN, CLIENT_HEADER_PATTERN, AUTHZ_PROJECTION_VERSION, ProjectedScopeSchema, DisplayRoleSchema, AuthorizationPrincipalSchema, CredentialContextSchema, ProjectionAnomalySchema, ProjectedOrgSchema, ProjectedResourceSchema, CapabilityProfilesSchema, RoleCatalogSchema, EffectiveAuthorizationSchema, ResourcePageSchema, SYSTEM_USER_PREFIX, WORKFLOW_RUN_IN_FLIGHT, WORKFLOW_RUN_IDLE, WORKFLOW_RUN_TERMINAL, WORKFLOW_RUN_STATUSES, WORKFLOW_STEP_STATUSES, WORKFLOW_STEP_IN_FLIGHT, ARCHIVE_WINDOW_MARGIN_DAYS, WORKFLOW_ORG_PURGING_TTL_S, WORKFLOW_ORG_PURGE_FORCE_AFTER_MS, IDEMPOTENCY_HOLDING_STATUSES, WORKFLOW_SCHEDULED_RUN_ID_PREFIX, CLOUD_TASK_RUN_ID_PREFIX, WORKFLOW_SCHEDULE_KEY_MAX, WORKFLOW_SCHEDULE_IDEMPOTENCY_KEY_PREFIX, WORKFLOW_OPERATION_ID_PREFIX, WORKFLOW_JOURNAL_PROTOCOL_VERSION, WORKFLOW_CONNECTION_KEY_RE, WORKFLOW_SIGNAL_PAYLOAD_MAX_BYTES, WORKFLOW_RESOLVE_OUTPUT_MAX_BYTES, WORKFLOW_RETRY_BACKOFFS, WORKFLOW_RETRY_MIN_ATTEMPTS, WORKFLOW_RETRY_POLICY_KEYS, WORKFLOW_RETRY_MAX_ATTEMPTS, WORKFLOW_RETRY_ENGINE_KEYS, WORKFLOW_JOB_RESOURCES, WORKFLOW_SIDE_EFFECTS, WORKFLOW_JOB_RANGES, WORKFLOW_JOB_RANGE_MEMBERS, WORKFLOW_SINGLE_STEP_TYPES, WORKFLOW_HITL_ENTRY_TYPES, WORKFLOW_ARM_ENTRY_TYPES, WORKFLOW_HITL_ARM_CONTAINERS, WORKFLOW_GRAPH_ENTRY_STEP_KINDS, WORKFLOW_ARM_ENTRY_STEP_KINDS, WORKFLOW_BUDGET_MAX_DURATION_SECONDS, REDACTED_PLACEHOLDER, PROVIDER_MESSAGE_MAX_CHARS, ERROR_MESSAGE_MAX_CHARS, SECRET_LITERAL_PATTERNS, SECRET_NAME, SECRET_PAIR_PATTERNS, GROUP_COUNT, WORKFLOW_SECRET_KEY_RE, WORKFLOW_RESERVED_SECRET_KEYS, SCRUB_INPUT_MAX_CHARS, SCRUB_CUT_BACKOFF_CHARS, WORKFLOW_AUDIT_EVENTS, WORKFLOW_AUDIT_METADATA_MAX_BYTES, INDENT, WRAP_WIDTH, NOUNS, GET_TOOL_NAMES, PREAMBLE, WORKFLOW_APPROVAL_OUTPUT_DECISIONS, WORKFLOW_APPROVAL_OUTPUT_SCHEMA, JSON_FENCE_RE, DEFAULT_ON_AGENT_FEATURES;
 var init_dist = __esm({
   "../shared-types/dist/index.mjs"() {
     "use strict";
@@ -1972,6 +2153,11 @@ var init_dist = __esm({
     __name2(normalizeModelId, "normalizeModelId");
     __name(modelUnresolvedMessage, "modelUnresolvedMessage");
     __name2(modelUnresolvedMessage, "modelUnresolvedMessage");
+    __name(providerModelId, "providerModelId");
+    __name2(providerModelId, "providerModelId");
+    MODEL_SNAPSHOT_SUFFIX = /(?:[-@](?:19|20)\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])|-(?:19|20)\d{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01]))$/;
+    __name(providerModelFamily, "providerModelFamily");
+    __name2(providerModelFamily, "providerModelFamily");
     REASONING_EFFORT_VALUES = [
       "off",
       "minimal",
@@ -2431,6 +2617,7 @@ This text is who you are for this person. As you learn them, their name, their w
     });
     TYPED_API_KEY = /^api_([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.([A-Za-z0-9_-]{43})$/;
     IdSchema = z2.string().min(1).max(256);
+    SESSION_AUTH_TIME_MAX_S = 4102444800;
     PrincipalDescriptorSchema = z2.object({
       subjectType: SubjectTypeSchema,
       subjectId: IdSchema
@@ -2479,7 +2666,8 @@ This text is who you are for this person. As you learn them, their name, their w
       owner: PrincipalOwnerSchema.optional(),
       compatibility: z2.object({
         mode: z2.literal("legacy-owner-delegation")
-      }).strict().optional()
+      }).strict().optional(),
+      authTime: z2.number().int().nonnegative().max(SESSION_AUTH_TIME_MAX_S).optional()
     }).strict();
     DeviceCredentialPrincipalContextSchema = z2.object({
       version: z2.literal(1),
@@ -2535,6 +2723,8 @@ This text is who you are for this person. As you learn them, their name, their w
     }).passthrough();
     __name(hasDeviceCredentialType, "hasDeviceCredentialType");
     __name2(hasDeviceCredentialType, "hasDeviceCredentialType");
+    __name(sessionAuthTime, "sessionAuthTime");
+    __name2(sessionAuthTime, "sessionAuthTime");
     __name(isTypedApiKeyPrincipal, "isTypedApiKeyPrincipal");
     __name2(isTypedApiKeyPrincipal, "isTypedApiKeyPrincipal");
     __name(typedApiKeyPrincipalId, "typedApiKeyPrincipalId");
@@ -2766,6 +2956,14 @@ This text is who you are for this person. As you learn them, their name, their w
     __name2(isScheduledWorkflowRunId, "isScheduledWorkflowRunId");
     __name(scheduledWorkflowRunId, "scheduledWorkflowRunId");
     __name2(scheduledWorkflowRunId, "scheduledWorkflowRunId");
+    WORKFLOW_SCHEDULE_KEY_MAX = 128;
+    __name(renderWorkflowScheduleKeyTemplate, "renderWorkflowScheduleKeyTemplate");
+    __name2(renderWorkflowScheduleKeyTemplate, "renderWorkflowScheduleKeyTemplate");
+    WORKFLOW_SCHEDULE_IDEMPOTENCY_KEY_PREFIX = "sched:";
+    __name(scheduledWorkflowIdempotencyKey, "scheduledWorkflowIdempotencyKey");
+    __name2(scheduledWorkflowIdempotencyKey, "scheduledWorkflowIdempotencyKey");
+    __name(stableKeyDigest, "stableKeyDigest");
+    __name2(stableKeyDigest, "stableKeyDigest");
     WORKFLOW_OPERATION_ID_PREFIX = "wf:";
     __name(workflowOperationId, "workflowOperationId");
     __name2(workflowOperationId, "workflowOperationId");
@@ -3212,6 +3410,23 @@ listed here; never invent a target.`;
     JSON_FENCE_RE = /```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n?```/g;
     __name(extractSingleJsonValue, "extractSingleJsonValue");
     __name2(extractSingleJsonValue, "extractSingleJsonValue");
+    DEFAULT_ON_AGENT_FEATURES = [
+      "workflows",
+      "workflowCompose",
+      "observationalMemory"
+    ];
+    __name(agentFeatureCatalogDefault, "agentFeatureCatalogDefault");
+    __name2(agentFeatureCatalogDefault, "agentFeatureCatalogDefault");
+    __name(hasExplicitFeatureActive, "hasExplicitFeatureActive");
+    __name2(hasExplicitFeatureActive, "hasExplicitFeatureActive");
+    __name(effectiveFeatureActive, "effectiveFeatureActive");
+    __name2(effectiveFeatureActive, "effectiveFeatureActive");
+    __name(resolveEffectiveFeature, "resolveEffectiveFeature");
+    __name2(resolveEffectiveFeature, "resolveEffectiveFeature");
+    __name(isFeatureRow, "isFeatureRow");
+    __name2(isFeatureRow, "isFeatureRow");
+    __name(effectiveAgentFeatureRows, "effectiveAgentFeatureRows");
+    __name2(effectiveAgentFeatureRows, "effectiveAgentFeatureRows");
   }
 });
 
@@ -4098,7 +4313,7 @@ function fillHitl(node) {
     if (a.onTimeout === void 0) a.onTimeout = "deny";
     if (a.onDeny === void 0) a.onDeny = "continue";
     if (a.excludeInitiator === void 0) a.excludeInitiator = false;
-    if (a.editable === void 0) a.editable = false;
+    if (a.editable === void 0) a.editable = approvalEditable(a);
     return;
   }
   const w = node;
@@ -4342,7 +4557,7 @@ function validateLuaExtensions(g, caps = WORKFLOW_CAPS_DEFAULT, opts = {
     const id = singleId(node);
     const unknown = unknownWorkflowRetryMembers(r);
     if (unknown.length) err("invalid-envelope", workflowRetryUnknownMembersMessage(unknown), `${path25}.retry`, id);
-    if (r.maxAttempts !== void 0 && !isWithinWorkflowRetryAttempts(r.maxAttempts)) {
+    if (!isWithinWorkflowRetryAttempts(r.maxAttempts)) {
       const over = typeof r.maxAttempts === "number" && r.maxAttempts > WORKFLOW_RETRY_MAX_ATTEMPTS;
       err(over ? "cap-exceeded" : "invalid-envelope", workflowRetryMaxAttemptsMessage(r.maxAttempts), `${path25}.retry.maxAttempts`, id);
     }
@@ -4580,7 +4795,7 @@ function validateLuaExtensions(g, caps = WORKFLOW_CAPS_DEFAULT, opts = {
     }
     const a = node;
     checkId(a.id, path25);
-    if (a.approver === "creator" && a.excludeInitiator === true) {
+    if ((a.approver ?? "creator") === "creator" && a.excludeInitiator === true) {
       err("approver-excludes-only-candidate", "approver:'creator' with excludeInitiator:true always excludes the only candidate", path25, a.id);
     }
     const editable = approvalEditable(a);
@@ -5883,6 +6098,7 @@ function runErrorIssues(issues) {
 function runNextAction(run) {
   if (isTerminalRunStatus(run.status)) return "none";
   if (run.status === "suspended" && run.gate?.kind === "budget") return "raise_budget";
+  if (run.status === "suspended" && run.gate?.kind === "billing") return "top_up";
   if (!run.cancel?.requestedAt) return "none";
   const forceAt = run.cancel.forceAfter ?? run.cancel.requestedAt + FORCE_CANCEL_STALE_MS;
   return Date.now() >= forceAt ? "force" : "cancel_again";
@@ -5910,6 +6126,12 @@ function runCountsFromStepStatuses(statuses) {
   for (const s of statuses) tally[s] = (tally[s] ?? 0) + 1;
   return runCountsFromStatusTally(tally);
 }
+function isBillingHeldStep(row2) {
+  return row2.status === "ready" && row2.billingHold === true;
+}
+function stepEffectiveStatus(row2) {
+  return isBillingHeldStep(row2) ? "suspended" : row2.status;
+}
 function runCounts(counts) {
   const c = counts ?? {};
   const rawInFlight = c.dispatched !== void 0 || c.claimed !== void 0 || c.running !== void 0 || c.cancellation_requested !== void 0;
@@ -6596,6 +6818,53 @@ function rebaseItemPointer(pointer, itemsPath, index) {
   const base = `/${itemsPath.split(".").map(escapePointer).join("/")}/${index}`;
   return pointer === "/" || pointer === "" ? base : `${base}${pointer}`;
 }
+function validateWorkflowSchedule(schedule, path25 = "/schedule") {
+  if (schedule === void 0 || schedule === null) return [];
+  const issue = /* @__PURE__ */ __name3((at, detail) => [
+    {
+      code: WORKFLOW_SCHEDULE_SHAPE_ISSUE,
+      severity: "error",
+      path: at,
+      message: `${detail} \u2014 ${WORKFLOW_SCHEDULE_SHAPES_HINT}`
+    }
+  ], "issue");
+  if (!isObject(schedule)) {
+    return issue(path25, `\`schedule\` is ${Array.isArray(schedule) ? "an array" : `a ${typeof schedule}`}, not a typed schedule object`);
+  }
+  const type = schedule.type;
+  if (type === void 0) {
+    const keys = Object.keys(schedule);
+    const seen = keys.length ? ` (got { ${keys.join(", ")} })` : " (got {})";
+    return issue(path25, `\`schedule\` carries no \`type\` discriminator${seen}`);
+  }
+  if (typeof type !== "string" || !WORKFLOW_SCHEDULE_TYPES.includes(type)) {
+    return issue(path25, `\`schedule.type\` ${JSON.stringify(type)} is not one of ${WORKFLOW_SCHEDULE_TYPES.map((t) => `'${t}'`).join(" | ")}`);
+  }
+  switch (type) {
+    case "cron": {
+      if (typeof schedule.expression !== "string" || schedule.expression.trim().length === 0) {
+        return issue(`${path25}/expression`, "a { type: 'cron' } schedule needs a non-empty string `expression`");
+      }
+      if (schedule.timezone !== void 0 && (typeof schedule.timezone !== "string" || schedule.timezone.length === 0)) {
+        return issue(`${path25}/timezone`, "a { type: 'cron' } schedule's `timezone`, when given, is a non-empty IANA string");
+      }
+      return [];
+    }
+    case "interval": {
+      const s = schedule.seconds;
+      if (typeof s !== "number" || !Number.isFinite(s) || s <= 0) {
+        return issue(`${path25}/seconds`, "a { type: 'interval' } schedule needs a positive number `seconds`");
+      }
+      return [];
+    }
+    case "once": {
+      if (typeof schedule.executeAt !== "string" || Number.isNaN(Date.parse(schedule.executeAt))) {
+        return issue(`${path25}/executeAt`, "a { type: 'once' } schedule needs an ISO-8601 string `executeAt`");
+      }
+      return [];
+    }
+  }
+}
 function collectEnvTemplateKeys(value22) {
   const keys = /* @__PURE__ */ new Set();
   const walk22 = /* @__PURE__ */ __name3((v) => {
@@ -6885,7 +7154,7 @@ function needsInheritedWorkspace(graph) {
   }
   return false;
 }
-var __defProp3, __name3, WorkflowTemplateError, TEMPLATE_PLACEHOLDER, TEMPLATE_NAMESPACES, MAP_DESCRIPTOR_KEYS, MAP_MEMBER_MALFORMED_CODE, fromInit, fromStep, value, template, fromRequest, rows, fromKnowledge, SideEffectsSchema, JobResourcesSchema, APPROVER_SPEC_MAX_USERS, ESCALATION_MAX_HOPS, TemplateBindingSchema, ApproverSpecSchema, FourEyesSchema, EscalationHopSchema, TerminalOutcomeSchema, ApprovalOnTimeoutSchema, APPROVER_SPEC_SHAPES, APPROVER_WRITTEN_MAX, USER_ID_SHAPED_RE, BINDING_ROOTS, WORKSPACE_TEMPLATE_EXPR_RE, SLEEP_UNTIL_REPLACEMENT, WORKFLOW_CAPS_DEFAULT, WORKFLOW_STEP_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_AGENT_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_JOB_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_FOREACH_DEFAULT_CONCURRENCY, WORKFLOW_FOREACH_DEFAULT_MAX_ITEMS, WORKFLOW_LOOP_DEFAULT_MAX_ITERATIONS, WORKFLOW_SUSPEND_DEFAULT_TIMEOUT_HOURS, WORKFLOW_SIGNAL_DEFAULT_SOURCES, clone, CONNECTION_ID_HEX_RE, WORKFLOW_JOB_TOOLS, WORKFLOW_JOB_MAX_WORKTREE_ARMS, workspaceOf, mountsWorkspace, isJobTier, jobToolsOf, schemaIsArray, isHitlNode, isSingleStep, singleId, armId, TEMPLATE_STEP_REF, EDITABLE_PATH_RE, PREDICATE_OPS, isPredicateScalar, GRAPH_HASH_PREFIX, WorkflowPlanError, isArmStep, armStepId, armStepKind, joinIdOf, containerIdOf, PATH_PLACEHOLDER, MISSING, stepIdOf, cmp, eq, ne, gt, gte, lt, lte, inSet, notIn, exists, notExists, truthy, falsy, and, or, not, CONTINUED_FAILURE_TAG, CONTINUED_FAILURE_DEFAULT_CODE, CONTINUED_FAILURE_OUTPUT_SCHEMA, CONTINUED_FAILURE_LEAF_PATHS, isHitlNode2, nodeIdOf, GOAL_JUDGE_STEP_ID, NON_LEAF_KINDS, CONDITIONAL_JOIN_ID, branchArmId, canonical, sortKeys, JOIN, entryOfJoin, FORCE_CANCEL_STALE_MS, TERMINAL, WORKFLOW_INLINE_RUN_TAG, RUN_ERROR_ISSUES_MAX, IN_FLIGHT, n, STEP_ERROR_DETAIL_KEYS, STEP_ERROR_DETAIL_MAX_BYTES, DETAIL_MAX_DEPTH, DETAIL_MAX_ITEMS, MAX_HOLIDAYS, MAX_WALK_DAYS, HHMM, YMD, MS_PER_MIN, MS_PER_DAY, MON_FRI, supportedTz, fmtCache, WEEKDAYS, JSON_PATCH_OPS, JSON_PATCH_MAX_OPS, JSON_PATCH_MAX_VALUE_BYTES, JSON_PATCH_MAX_TOTAL_BYTES, SEGMENT_RE, WORKFLOW_ENV_OVERLAY_MAX_KEYS, WORKFLOW_ENV_OVERLAY_MAX_VALUE_BYTES, WORKFLOW_ENV_TEMPLATE_SECRET_KEY_RE, isEnvRef, looksLikeEmbeddedJson, ZERO, isRecord2;
+var __defProp3, __name3, WorkflowTemplateError, TEMPLATE_PLACEHOLDER, TEMPLATE_NAMESPACES, MAP_DESCRIPTOR_KEYS, MAP_MEMBER_MALFORMED_CODE, fromInit, fromStep, value, template, fromRequest, rows, fromKnowledge, SideEffectsSchema, JobResourcesSchema, APPROVER_SPEC_MAX_USERS, ESCALATION_MAX_HOPS, TemplateBindingSchema, ApproverSpecSchema, FourEyesSchema, EscalationHopSchema, TerminalOutcomeSchema, ApprovalOnTimeoutSchema, APPROVER_SPEC_SHAPES, APPROVER_WRITTEN_MAX, USER_ID_SHAPED_RE, BINDING_ROOTS, WORKSPACE_TEMPLATE_EXPR_RE, SLEEP_UNTIL_REPLACEMENT, WORKFLOW_CAPS_DEFAULT, WORKFLOW_STEP_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_AGENT_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_JOB_DEFAULT_TIMEOUT_SECONDS, WORKFLOW_FOREACH_DEFAULT_CONCURRENCY, WORKFLOW_FOREACH_DEFAULT_MAX_ITEMS, WORKFLOW_LOOP_DEFAULT_MAX_ITERATIONS, WORKFLOW_SUSPEND_DEFAULT_TIMEOUT_HOURS, WORKFLOW_SIGNAL_DEFAULT_SOURCES, clone, CONNECTION_ID_HEX_RE, WORKFLOW_JOB_TOOLS, WORKFLOW_JOB_MAX_WORKTREE_ARMS, workspaceOf, mountsWorkspace, isJobTier, jobToolsOf, schemaIsArray, isHitlNode, isSingleStep, singleId, armId, TEMPLATE_STEP_REF, EDITABLE_PATH_RE, PREDICATE_OPS, isPredicateScalar, GRAPH_HASH_PREFIX, WorkflowPlanError, isArmStep, armStepId, armStepKind, joinIdOf, containerIdOf, PATH_PLACEHOLDER, MISSING, stepIdOf, cmp, eq, ne, gt, gte, lt, lte, inSet, notIn, exists, notExists, truthy, falsy, and, or, not, CONTINUED_FAILURE_TAG, CONTINUED_FAILURE_DEFAULT_CODE, CONTINUED_FAILURE_OUTPUT_SCHEMA, CONTINUED_FAILURE_LEAF_PATHS, isHitlNode2, nodeIdOf, GOAL_JUDGE_STEP_ID, NON_LEAF_KINDS, CONDITIONAL_JOIN_ID, branchArmId, canonical, sortKeys, JOIN, entryOfJoin, FORCE_CANCEL_STALE_MS, TERMINAL, WORKFLOW_INLINE_RUN_TAG, RUN_ERROR_ISSUES_MAX, IN_FLIGHT, n, STEP_ERROR_DETAIL_KEYS, STEP_ERROR_DETAIL_MAX_BYTES, DETAIL_MAX_DEPTH, DETAIL_MAX_ITEMS, MAX_HOLIDAYS, MAX_WALK_DAYS, HHMM, YMD, MS_PER_MIN, MS_PER_DAY, MON_FRI, supportedTz, fmtCache, WEEKDAYS, JSON_PATCH_OPS, JSON_PATCH_MAX_OPS, JSON_PATCH_MAX_VALUE_BYTES, JSON_PATCH_MAX_TOTAL_BYTES, SEGMENT_RE, WORKFLOW_SCHEDULE_TYPES, WORKFLOW_SCHEDULE_SHAPE_ISSUE, WORKFLOW_SCHEDULE_SHAPES_HINT, isObject, WORKFLOW_ENV_OVERLAY_MAX_KEYS, WORKFLOW_ENV_OVERLAY_MAX_VALUE_BYTES, WORKFLOW_ENV_TEMPLATE_SECRET_KEY_RE, isEnvRef, looksLikeEmbeddedJson, ZERO, isRecord2;
 var init_dist2 = __esm({
   "../workflow-graph/dist/index.mjs"() {
     "use strict";
@@ -7440,6 +7709,10 @@ var init_dist2 = __esm({
     __name3(runCountsFromStatusTally, "runCountsFromStatusTally");
     __name(runCountsFromStepStatuses, "runCountsFromStepStatuses");
     __name3(runCountsFromStepStatuses, "runCountsFromStepStatuses");
+    __name(isBillingHeldStep, "isBillingHeldStep");
+    __name3(isBillingHeldStep, "isBillingHeldStep");
+    __name(stepEffectiveStatus, "stepEffectiveStatus");
+    __name3(stepEffectiveStatus, "stepEffectiveStatus");
     n = /* @__PURE__ */ __name3((v) => typeof v === "number" && Number.isFinite(v) ? v : 0, "n");
     __name(runCounts, "runCounts");
     __name3(runCounts, "runCounts");
@@ -7591,6 +7864,16 @@ var init_dist2 = __esm({
     __name3(applyJsonPatch, "applyJsonPatch");
     __name(rebaseItemPointer, "rebaseItemPointer");
     __name3(rebaseItemPointer, "rebaseItemPointer");
+    WORKFLOW_SCHEDULE_TYPES = [
+      "cron",
+      "interval",
+      "once"
+    ];
+    WORKFLOW_SCHEDULE_SHAPE_ISSUE = "schedule-shape-invalid";
+    WORKFLOW_SCHEDULE_SHAPES_HINT = "`schedule` must be one of { type: 'cron', expression: '<5-field cron>', timezone?: '<IANA tz>' } | { type: 'interval', seconds: <n> } | { type: 'once', executeAt: '<ISO-8601>' }";
+    isObject = /* @__PURE__ */ __name3((v) => typeof v === "object" && v !== null && !Array.isArray(v), "isObject");
+    __name(validateWorkflowSchedule, "validateWorkflowSchedule");
+    __name3(validateWorkflowSchedule, "validateWorkflowSchedule");
     WORKFLOW_ENV_OVERLAY_MAX_KEYS = 64;
     WORKFLOW_ENV_OVERLAY_MAX_VALUE_BYTES = 4096;
     WORKFLOW_ENV_TEMPLATE_SECRET_KEY_RE = /(SECRET|TOKEN|KEY|PASSWORD)$/;
@@ -7860,7 +8143,7 @@ var init_workflow = __esm({
     }, "assertPredicate");
     assertRetry = /* @__PURE__ */ __name((r, id) => {
       if (!r) return;
-      if (r.maxAttempts !== void 0 && !isWithinWorkflowRetryAttempts(r.maxAttempts)) {
+      if (!isWithinWorkflowRetryAttempts(r.maxAttempts)) {
         const over = typeof r.maxAttempts === "number" && r.maxAttempts > WORKFLOW_RETRY_MAX_ATTEMPTS;
         throw new LuaWorkflowBuildError(over ? "cap-exceeded" : "invalid-envelope", `"${id}": ${workflowRetryMaxAttemptsMessage(r.maxAttempts)}`);
       }
@@ -8381,9 +8664,12 @@ var init_workflow = __esm({
         if (opts.approver === "creator" && opts.excludeInitiator === true) {
           throw new LuaWorkflowBuildError("approver-excludes-only-candidate", `"${id}": approver:'creator' with excludeInitiator:true always excludes the only candidate`);
         }
-        if (opts.fourEyes !== void 0 && opts.editable !== true) throw new LuaWorkflowBuildError("four-eyes-requires-editable", `"${id}": fourEyes requires editable:true`);
-        if ((opts.editablePaths !== void 0 || opts.editedPayloadSchema !== void 0) && opts.editable !== true) {
-          throw new LuaWorkflowBuildError("editable-path-invalid", `"${id}": editablePaths / editedPayloadSchema require editable:true`);
+        const editable = approvalEditable(opts);
+        if (opts.fourEyes !== void 0 && !editable) throw new LuaWorkflowBuildError("four-eyes-requires-editable", `"${id}": \`fourEyes\` requires editable:true`);
+        if (opts.editable === false && Array.isArray(opts.editablePaths) && opts.editablePaths.length > 0) {
+          throw new LuaWorkflowBuildError("editable-path-invalid", `"${id}": \`editablePaths\` beside editable:false is contradictory \u2014 drop the paths or set editable:true`);
+        } else if ((opts.editablePaths !== void 0 || opts.editedPayloadSchema !== void 0) && !editable) {
+          throw new LuaWorkflowBuildError("editable-path-invalid", `"${id}": \`editablePaths\` / \`editedPayloadSchema\` require editable:true (a non-empty editablePaths implies it)`);
         }
         for (const p of opts.editablePaths ?? []) {
           if (!EDITABLE_PATH_RE2.test(p)) throw new LuaWorkflowBuildError("editable-path-invalid", `"${id}": editablePaths entry "${p}" is outside the grammar seg(.seg)* with [*]/[n] selectors`);
@@ -8719,6 +9005,71 @@ var init_types = __esm({
 
 // src/api/http.client.ts
 import { randomUUID as randomUUID3 } from "crypto";
+async function classifyErrorResponse(response) {
+  let errorData;
+  try {
+    errorData = await response.json();
+  } catch (jsonError) {
+    errorData = {};
+  }
+  if (response.status === 401) {
+    const serverMessage = typeof errorData.message === "string" ? errorData.message : void 0;
+    if (serverMessage && /not an admin/i.test(serverMessage)) {
+      throw new AuthenticationError(`Access denied for this agent: ${serverMessage}`, "no_agent_access", serverMessage);
+    }
+    const isExplicitCredential = !!serverMessage && /(invalid|expired|missing|no)\s+(api[\s_-]?key|token|credential)/i.test(serverMessage);
+    const isBareAuthRejection = !serverMessage || /^unauthorized$/i.test(serverMessage);
+    if (isExplicitCredential || isBareAuthRejection) {
+      throw new AuthenticationError("Authentication failed. Your Lua credential may be invalid or expired.", "invalid_credentials", serverMessage);
+    }
+    throw new AuthenticationError(`Authentication failed: ${serverMessage}`, "unknown", serverMessage);
+  }
+  if (response.status === 403) {
+    const detail = errorData.message || "You do not have permission to access this resource.";
+    const serverCode = serverCodeOf(errorData.code, errorData.error);
+    throw new CliError("forbidden", `Access denied (403): ${detail}${serverCode ? ` (${serverCode})` : ""}`, {
+      exitCode: CLI_EXIT.FORBIDDEN,
+      statusCode: 403,
+      serverCode,
+      issues: Array.isArray(errorData.issues) ? errorData.issues : void 0,
+      hint: "Check that your Lua login has access to this agent or organization."
+    });
+  }
+  return {
+    success: false,
+    error: {
+      message: errorData.message || `HTTP ${response.status}: ${response.statusText}`,
+      statusCode: response.status,
+      error: errorData.error,
+      retryAfterSeconds: parseRetryAfter(response.headers.get("retry-after")),
+      ...errorData
+    }
+  };
+}
+function serverCodeOf(code, error) {
+  if (typeof code === "string" && code.length > 0) return code;
+  if (typeof error === "string" && /^[A-Z0-9][A-Z0-9_]*$/.test(error)) return error;
+  return void 0;
+}
+async function refusalFromResponse(response) {
+  const { error } = await classifyErrorResponse(response);
+  const serverCode = serverCodeOf(error?.code, error?.error);
+  return CliError.fromStatus(
+    error?.statusCode ?? response.status,
+    error?.message ?? `HTTP ${response.status}: ${response.statusText}`,
+    void 0,
+    // LUA-810: `fromStatus` picks the UPSTREAM_UNAVAILABLE hint from the body's `upstream` / `requestId`.
+    // LUA-812: and the VENDOR_UNAVAILABLE hint from `vendor` / `retryAfterSeconds` (whether a blind retry is safe).
+    {
+      serverCode,
+      issues: error?.issues,
+      upstream: error?.upstream,
+      requestId: error?.requestId,
+      vendor: error?.vendor,
+      retryAfterSeconds: error?.retryAfterSeconds
+    }
+  );
+}
 async function* parseSseStream(body, signal) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -8899,42 +9250,7 @@ var init_http_client = __esm({
       * @private
       */
       async classifyErrorResponse(response) {
-        let errorData;
-        try {
-          errorData = await response.json();
-        } catch (jsonError) {
-          errorData = {};
-        }
-        if (response.status === 401) {
-          const serverMessage = typeof errorData.message === "string" ? errorData.message : void 0;
-          if (serverMessage && /not an admin/i.test(serverMessage)) {
-            throw new AuthenticationError(`Access denied for this agent: ${serverMessage}`, "no_agent_access", serverMessage);
-          }
-          const isExplicitCredential = !!serverMessage && /(invalid|expired|missing|no)\s+(api[\s_-]?key|token|credential)/i.test(serverMessage);
-          const isBareAuthRejection = !serverMessage || /^unauthorized$/i.test(serverMessage);
-          if (isExplicitCredential || isBareAuthRejection) {
-            throw new AuthenticationError("Authentication failed. Your Lua credential may be invalid or expired.", "invalid_credentials", serverMessage);
-          }
-          throw new AuthenticationError(`Authentication failed: ${serverMessage}`, "unknown", serverMessage);
-        }
-        if (response.status === 403) {
-          const detail = errorData.message || "You do not have permission to access this resource.";
-          throw new CliError("forbidden", `Access denied (403): ${detail}`, {
-            exitCode: CLI_EXIT.FORBIDDEN,
-            statusCode: 403,
-            hint: "Check that your Lua login has access to this agent or organization."
-          });
-        }
-        return {
-          success: false,
-          error: {
-            message: errorData.message || `HTTP ${response.status}: ${response.statusText}`,
-            statusCode: response.status,
-            error: errorData.error,
-            retryAfterSeconds: parseRetryAfter(response.headers.get("retry-after")),
-            ...errorData
-          }
-        };
+        return classifyErrorResponse(response);
       }
       /**
       * Checks if an HTTP status code is retryable
@@ -8958,6 +9274,21 @@ var init_http_client = __esm({
         return Math.max(100, Math.random() * exponential);
       }
       /**
+      * The wait before the next attempt: the client's jittered exponential backoff, floored by the server's
+      * `retryAfterSeconds` on a 429 (the limiter's word is final) and on an idempotent read (GET / HEAD). LUA-810: a
+      * POST / PUT / PATCH / DELETE that met a 5xx keeps the client's own backoff — every 503 body carries
+      * `retryAfterSeconds: 5` (`CONTROL_UNAVAILABLE`, `UPSTREAM_UNAVAILABLE`), which floored all three waits at 5 s:
+      * a ≥15 s stall on a write that may already have landed, and retrying an ambiguous write harder does not make
+      * it less ambiguous. The client's own schedule is ≤1 s + ≤2 s + ≤4 s.
+      */
+      retryDelayMs(attempt, error, method) {
+        const own = this.calculateBackoff(attempt);
+        const advised = Number(error?.retryAfterSeconds ?? 0) * 1e3;
+        const verb = (method ?? "GET").toUpperCase();
+        const honourAdvice = error?.statusCode === 429 || verb === "GET" || verb === "HEAD";
+        return honourAdvice ? Math.max(own, advised) : own;
+      }
+      /**
       * Wraps request with retry logic for transient failures
       * @param url - The full URL to request
       * @param options - Fetch API request options
@@ -8991,8 +9322,7 @@ var init_http_client = __esm({
             throw error;
           }
           if (attempt < maxRetries) {
-            const serverDelay = Number(lastResult?.error?.retryAfterSeconds ?? 0) * 1e3;
-            const backoff = Math.max(this.calculateBackoff(attempt), serverDelay);
+            const backoff = this.retryDelayMs(attempt, lastResult?.error, options.method);
             await new Promise((resolve7) => setTimeout(resolve7, backoff));
           }
         }
@@ -9142,6 +9472,9 @@ var init_http_client = __esm({
         };
       }
     };
+    __name(classifyErrorResponse, "classifyErrorResponse");
+    __name(serverCodeOf, "serverCodeOf");
+    __name(refusalFromResponse, "refusalFromResponse");
     __name(parseSseStream, "parseSseStream");
     __name(parseRetryAfter, "parseRetryAfter");
     __name(isCoreDrainApiError, "isCoreDrainApiError");
@@ -11568,8 +11901,14 @@ async function withErrorHandling(commandFn, commandName, opts) {
       } catch {
       }
     }
+    let json = false;
+    try {
+      json = typeof opts?.json === "function" ? !!opts.json() : !!opts?.json;
+    } catch {
+    }
     const reported = reportCliError(error, {
-      extraHint
+      extraHint,
+      json
     });
     process.exitCode = reported.exitCode;
     await showUpdateWarningIfNeeded(versionCheckPromise);
@@ -25850,6 +26189,7 @@ var init_job_api_service = __esm({
   "src/api/job.api.service.ts"() {
     "use strict";
     init_http_client();
+    init_cli_error();
     init_job_instance();
     JobApi = class extends HttpClient {
       static {
@@ -25906,7 +26246,7 @@ var init_job_api_service = __esm({
         if (response.success && response.data) {
           return new JobInstance(this, response.data);
         }
-        throw new Error(response.error?.message || "Failed to get job");
+        throw CliError.fromStatus(response.error?.statusCode, response.error?.message || "Failed to get job", void 0, apiErrorDetail(response.error));
       }
       /**
       * Creates a new job for the agent.
@@ -27381,7 +27721,7 @@ async function fetchApprovedModelsOrThrow(apiKey, agentId, orgId) {
   const agentApi = new AgentApi(BASE_URLS.API, apiKey);
   const result = await agentApi.getApprovedModels(void 0, agentId, orgId);
   if (!result.success) {
-    throw CliError.fromStatus(result.error?.statusCode, `Could not fetch models from the server: ${result.error?.message || "Unknown error"}`);
+    throw CliError.fromStatus(result.error?.statusCode, `Could not fetch models from the server: ${result.error?.message || "Unknown error"}`, void 0, apiErrorDetail(result.error));
   }
   return result.data ?? [];
 }
@@ -29752,7 +30092,7 @@ async function handleAgentSwitch(credential, organizations, apiKey, existingYaml
   });
   writeSuccess("\u2705 lua.skill.yaml updated successfully!");
   writeSuccess("\u2705 LuaAgent configuration updated!");
-  writeInfo("\n\u{1F4A1} Your project now uses the new agent. Run 'lua compile' to update your skills.\n");
+  writeInfo("\n\u{1F4A1} Your project now uses the new agent. Run 'lua sync' (or 'lua push all') to reconcile your skills.\n");
   trackEvent("cli_init_agent_switched", {
     model_selected: !!selectedModel,
     model: selectedModel
@@ -30137,7 +30477,9 @@ async function syncCommand(options) {
     let syncCompletedSuccessfully = false;
     try {
       writeProgress("\u{1F504} Compiling to get latest local state...");
-      await compileCommand();
+      await compileCommand({
+        serverSync: true
+      });
       writeProgress("\u{1F504} Checking for drift between server and local code...");
       const { agentId, apiKey } = await initializeCommand({
         showProgress: false
@@ -34877,7 +35219,8 @@ var WorkflowHandler = class extends BaseVersionedHandler {
       success: response.success,
       error: response.error?.message,
       statusCode: response.error?.statusCode,
-      code: response.error?.code ?? response.error?.error
+      code: response.error?.code ?? response.error?.error,
+      issues: response.error?.issues
     };
   }
   /**
@@ -35083,7 +35426,7 @@ async function compileCommand(options) {
     const debugMode = options?.debug || debugEnabled();
     const verboseMode = options?.verbose || debugMode;
     const doSync = options?.sync === true;
-    const doServerSync = options?.serverSync !== false;
+    const doServerSync = options?.serverSync === true;
     if (debugMode) {
       console.log("\u{1F41B} Debug mode enabled");
     }
@@ -35180,7 +35523,7 @@ async function compileCommand(options) {
     let syncConfig = readYamlConfig();
     const agentId = syncConfig?.agent?.agentId;
     if (!doServerSync) {
-      writeInfo("\u2139\uFE0F  Server sync skipped (offline verb) \u2014 `lua push` when you are ready to publish.");
+      writeInfo("\u2139\uFE0F  Server sync skipped \u2014 nothing was sent to the server; `lua push` publishes.");
     } else if (apiKey && agentId) {
       writeProgress("\u{1F504} Syncing with server...");
       const fetchResults = await Promise.all(syncableHandlers.map((h) => h.fetchServerState(apiKey, agentId)));
@@ -38458,7 +38801,8 @@ async function pushBackupCommand(options = {}) {
       }
       writeInfo("No compilation output found. Running compile first...");
       await compileCommand({
-        sync: false
+        sync: false,
+        serverSync: true
       });
     }
     writeProgress("Pushing backup...");
@@ -39156,12 +39500,24 @@ function formatPushFailureSummary(failedItems) {
   return lines.join("\n");
 }
 __name(formatPushFailureSummary, "formatPushFailureSummary");
+function pushRefusalError(handler, name, result) {
+  const reason = result.error || "Unknown error";
+  const isVersionConflict = reason.toLowerCase().includes("already exists");
+  return new CliError("error", `${handler.displayName.toLowerCase()} "${name}" is not pushed: ${reason}`, {
+    exitCode: CLI_EXIT.ERROR,
+    statusCode: result.statusCode,
+    serverCode: result.code,
+    issues: result.issues,
+    hint: isVersionConflict ? `Version conflict \u2014 this version already exists on the server. Auto-bump: lua push ${handler.kind} --force \xB7 or push all: lua push all --force` : void 0
+  });
+}
+__name(pushRefusalError, "pushRefusalError");
 function stalePushEntryError(handler, name, entityId, serverMessage) {
   const field = handler.yamlConfig.idField;
   return new CliError("not_found", `${handler.displayName} "${name}" (${entityId}) no longer exists on the server${serverMessage ? ` \u2014 ${serverMessage}` : ""}`, {
     exitCode: CLI_EXIT.NOT_FOUND,
     statusCode: 404,
-    hint: `lua.skill.yaml still holds ${field}: ${entityId} for "${name}". Run \`lua compile\` \u2014 the server sync clears a deleted id and registers the definition afresh \u2014 then push again; or remove the ${field} line by hand.`
+    hint: `lua.skill.yaml still holds ${field}: ${entityId} for "${name}". Remove that ${field}: line from lua.skill.yaml, then run \`lua push ${handler.displayName}\` again \u2014 its compile step registers the definition afresh and writes the new id.`
   });
 }
 __name(stalePushEntryError, "stalePushEntryError");
@@ -39310,7 +39666,9 @@ __name(shouldDeployAfterPush, "shouldDeployAfterPush");
 async function pushVersionedPrimitive(handler, options = {}) {
   try {
     writeProgress("\u{1F4E6} Compiling project...");
-    await compileCommand();
+    await compileCommand({
+      serverSync: true
+    });
     writeSuccess("\u2705 Compilation complete");
     const apiKey = await authenticateOrFail();
     const config = readYamlConfig();
@@ -39332,7 +39690,7 @@ async function pushVersionedPrimitive(handler, options = {}) {
     });
     const entityId = selected[handler.yamlConfig.idField];
     if (!entityId) {
-      throw new Error(`${handler.displayName} "${selected.name}" has no server ID. Run 'lua compile' first.`);
+      throw new Error(`${handler.displayName} "${selected.name}" has no server ID \u2014 the create above failed. Fix it and run 'lua push ${handler.displayName}' again.`);
     }
     const manifest = loadManifest();
     const bundleAccumulator = /* @__PURE__ */ new Map();
@@ -39363,24 +39721,7 @@ async function pushVersionedPrimitive(handler, options = {}) {
     });
     if (!result.success) {
       if (result.statusCode === 404) throw stalePushEntryError(handler, selected.name, entityId, result.error);
-      const isVersionConflict = result.error?.toLowerCase().includes("already exists");
-      if (isVersionConflict) {
-        writeHintBlock({
-          headline: "Version conflict \u2014 this version already exists on the server.",
-          lines: [
-            {
-              label: "Auto-bump:",
-              command: `lua push ${handler.kind} --force`
-            },
-            {
-              label: "Or push all:",
-              command: "lua push all --force"
-            }
-          ],
-          when: "error"
-        });
-      }
-      throw new Error(`Push Error: ${result.error || "Unknown error"}`);
+      throw pushRefusalError(handler, selected.name, result);
     }
     writeSuccess(`
 \u2705 Successfully pushed ${selected.name} v${confirmedVersion}
@@ -39726,7 +40067,9 @@ async function runIncludeSourceHook(apiKey, agentId, selectedType) {
 __name(runIncludeSourceHook, "runIncludeSourceHook");
 async function pushAgentVersion(options = {}) {
   writeProgress("\u{1F504} Compiling...");
-  await compileCommand();
+  await compileCommand({
+    serverSync: true
+  });
   const config = readYamlConfig();
   if (!config || !config.agent?.agentId) {
     throw new Error("No agent configuration found. Please run 'lua init' first.");
@@ -39833,7 +40176,9 @@ __name(deployPersonaVersionAfterPush, "deployPersonaVersionAfterPush");
 async function pushMCPServer(options = {}) {
   try {
     writeProgress("\u{1F4E6} Compiling project...");
-    await compileCommand();
+    await compileCommand({
+      serverSync: true
+    });
     writeSuccess("\u2705 Compilation complete");
     const apiKey = await authenticateOrFail();
     writeSuccess("\u2705 Authentication verified");
@@ -39886,7 +40231,9 @@ async function pushAllCommand(options) {
     writeInfo("\u{1F680} Auto-deploy to production is ENABLED\n");
   }
   writeProgress("\u{1F4E6} Compiling project...");
-  await compileCommand();
+  await compileCommand({
+    serverSync: true
+  });
   const config = readYamlConfig();
   if (!config?.agent?.agentId) {
     throw new Error('No agent ID found in lua.skill.yaml. Run "lua init" first.');
@@ -39974,7 +40321,7 @@ ${icon} Pushing ${items.length} ${handler.displayName}(s)...`);
         }
         const entityId = item[handler.yamlConfig.idField];
         if (!entityId) {
-          console.warn(`\u26A0\uFE0F  ${handler.displayName} "${item.name}" has no server ID, skipping. Run 'lua compile' first.`);
+          console.warn(`\u26A0\uFE0F  ${handler.displayName} "${item.name}" has no server ID, skipping \u2014 the create above failed. Fix it and run 'lua push ${handler.displayName}' again.`);
           continue;
         }
         if (!item.version) {
@@ -41921,7 +42268,9 @@ __name(chatCommand, "chatCommand");
 async function setupChatEnvironment(chatEnv, config) {
   writeProgress("\u{1F504} Setting up sandbox environment...");
   writeProgress("\u{1F504} Compiling skill...");
-  await compileCommand();
+  await compileCommand({
+    serverSync: true
+  });
   const manifest = loadManifest();
   const skills = getPrimitivesByKind(manifest, PrimitiveKind.SKILL);
   let sandboxIds = {};
@@ -45026,7 +45375,7 @@ function channelCreateError(error, alreadyConnected) {
     return CliError.fromStatus(400, "Channel already exists", `${alreadyConnected}
 Use 'lua channels' to list existing channels.`);
   }
-  return CliError.fromStatus(error?.statusCode, error?.message || "Unknown error", error?.error);
+  return CliError.fromStatus(error?.statusCode, error?.message || "Unknown error", error?.error, apiErrorDetail(error));
 }
 __name(channelCreateError, "channelCreateError");
 async function fetchChannelsCore(agentApi, agentId) {
@@ -45962,7 +46311,7 @@ async function nonInteractiveLogs(logsApi, agentId, apiKey, options) {
   }
   const response = await logsApi.getAgentLogs(agentId, options.limit || 20, options.page || 1, filters);
   if (!response.success) {
-    throw CliError.fromStatus(response.error?.statusCode, response.error?.message || "Unknown error");
+    throw CliError.fromStatus(response.error?.statusCode, response.error?.message || "Unknown error", void 0, apiErrorDetail(response.error));
   }
   const data = response.data;
   if (options.json) {
@@ -46174,7 +46523,7 @@ async function viewAgentLogsInteractive(logsApi, agentId, filters = {}) {
   while (keepViewing) {
     const response = await logsApi.getAgentLogs(agentId, limit, currentPage, filters);
     if (!response.success) {
-      throw CliError.fromStatus(response.error?.statusCode, response.error?.message || "Unknown error");
+      throw CliError.fromStatus(response.error?.statusCode, response.error?.message || "Unknown error", void 0, apiErrorDetail(response.error));
     }
     const data = response.data;
     displayLogsCore(data.logs, data.pagination, "All Agent Logs", true);
@@ -49703,7 +50052,7 @@ async function jobsCommand(action, cmdObj) {
   }, "jobs");
 }
 __name(jobsCommand, "jobsCommand");
-async function displayJobsCore(context, jobs) {
+async function displayJobsCore(context, jobs, opts = {}) {
   console.log("\n" + "=".repeat(60));
   console.log("\u2699\uFE0F  Production Jobs");
   console.log("=".repeat(60) + "\n");
@@ -49726,7 +50075,14 @@ async function displayJobsCore(context, jobs) {
       }
       console.log();
     } catch (error) {
-      displayJobError(job, "Error loading info");
+      if (CliError.isCliError(error) && error.statusCode === 404) {
+        if (opts.single) {
+          throw CliError.notFound(`Job "${job.name}" (${job.jobId}) no longer exists on the server \u2014 ${error.message}`, "lua.skill.yaml still lists it; `lua sync` reconciles the local config with the server.");
+        }
+        displayJobError(job, "not found on the server");
+        continue;
+      }
+      throw error;
     }
   }
   console.log("=".repeat(60));
@@ -49994,7 +50350,13 @@ async function executeNonInteractive7(context, config, action, options) {
       console.log("\u2139\uFE0F  No jobs found in configuration.");
       return;
     }
-    await displayJobsCore(context, jobs);
+    const viewed = options.jobName ? jobs.filter((j) => j.jobId === options.jobName || j.name === options.jobName) : jobs;
+    if (viewed.length === 0) {
+      throw CliError.notFound(`Job "${options.jobName}" not found`, listHint("Available jobs in local config:", jobs.map((j) => `${j.name} (${j.jobId})`)));
+    }
+    await displayJobsCore(context, viewed, {
+      single: !!options.jobName
+    });
     return;
   }
   if (!options.jobName) {
@@ -50500,69 +50862,77 @@ function exitCodeForRunStatus(status) {
 }
 __name(exitCodeForRunStatus, "exitCodeForRunStatus");
 async function workflowsCommand(action, target, extra, cmdObj) {
-  return withErrorHandling(async () => {
-    const options = {
-      ...cmdObj ?? {}
-    };
-    const json = !!options.json;
-    let resolved;
-    if (action) {
-      resolved = validateOrSuggest("workflows.action", action);
-    } else {
-      const answer = await safePrompt([
-        {
-          type: "list",
-          name: "action",
-          message: "What would you like to do?",
-          choices: [
-            {
-              name: "\u{1F4CB} List workflows",
-              value: "list"
-            },
-            {
-              name: "\u{1F9ED} Run a workflow locally",
-              value: "run"
-            },
-            {
-              name: "\u25B6\uFE0F  Start a run",
-              value: "start"
-            },
-            {
-              name: "\u{1F5C2}\uFE0F  List runs",
-              value: "runs"
-            }
-          ]
-        }
-      ]);
-      if (!answer) return;
-      resolved = answer.action;
-    }
-    if (resolved === "run") {
-      const outcome = await runWorkflowLocalFromProject(target ?? options.workflowName ?? null, options);
-      process.exitCode = outcome.exitCode;
+  return withErrorHandling(
+    async () => {
+      const options = {
+        ...cmdObj ?? {}
+      };
+      const json = !!options.json;
+      let resolved;
+      if (action) {
+        resolved = validateOrSuggest("workflows.action", action);
+      } else {
+        const answer = await safePrompt([
+          {
+            type: "list",
+            name: "action",
+            message: "What would you like to do?",
+            choices: [
+              {
+                name: "\u{1F4CB} List workflows",
+                value: "list"
+              },
+              {
+                name: "\u{1F9ED} Run a workflow locally",
+                value: "run"
+              },
+              {
+                name: "\u25B6\uFE0F  Start a run",
+                value: "start"
+              },
+              {
+                name: "\u{1F5C2}\uFE0F  List runs",
+                value: "runs"
+              }
+            ]
+          }
+        ]);
+        if (!answer) return;
+        resolved = answer.action;
+      }
+      if (resolved === "run") {
+        const outcome = await runWorkflowLocalFromProject(target ?? options.workflowName ?? null, options);
+        process.exitCode = outcome.exitCode;
+        trackEvent("cli_workflows_action", {
+          action: "run",
+          non_interactive: !!action
+        });
+        return;
+      }
+      const { agentId, apiKey } = await initializeCommand({
+        showProgress: !json
+      });
+      const ctx = {
+        agentId,
+        apiKey,
+        api: new WorkflowApi(BASE_URLS.API, apiKey, agentId),
+        json
+      };
+      const code = await executeAction(ctx, resolved, target, extra, options);
+      if (code !== void 0 && code !== 0) process.exitCode = code;
       trackEvent("cli_workflows_action", {
-        action: "run",
-        non_interactive: !!action
+        action: resolved,
+        non_interactive: !!action,
+        exit_code: code ?? 0
       });
-      return;
+    },
+    "workflows",
+    // LUA-803: a typed refusal that escapes a verb under `--json` (a 403 the client threw, an unreachable host) is
+    // the envelope on stdout — the same shape `apiFailure` prints for a refused verb — never the `✖` line.
+    {
+      json: /* @__PURE__ */ __name(() => !!cmdObj?.json, "json")
     }
-    const { agentId, apiKey } = await initializeCommand({
-      showProgress: !json
-    });
-    const ctx = {
-      agentId,
-      apiKey,
-      api: new WorkflowApi(BASE_URLS.API, apiKey, agentId),
-      json
-    };
-    const code = await executeAction(ctx, resolved, target, extra, options);
-    if (code !== void 0 && code !== 0) process.exitCode = code;
-    trackEvent("cli_workflows_action", {
-      action: resolved,
-      non_interactive: !!action,
-      exit_code: code ?? 0
-    });
-  }, "workflows");
+  );
 }
 __name(workflowsCommand, "workflowsCommand");
 async function executeAction(ctx, action, target, extra, o) {
@@ -50664,18 +51034,12 @@ async function executeAction(ctx, action, target, extra, o) {
 }
 __name(executeAction, "executeAction");
 async function requireName(name, verb, fn) {
-  if (!name) {
-    console.error(`\u274C ${verb}: a workflow name is required \u2014 lua workflows ${verb} <name> (or -i <name>)`);
-    return WORKFLOW_EXIT.USAGE;
-  }
+  if (!name) throw CliError.usage(`${verb}: a workflow name is required`, `lua workflows ${verb} <name> (or -i <name>)`);
   return fn();
 }
 __name(requireName, "requireName");
 async function requireRun(runId, verb, fn) {
-  if (!runId) {
-    console.error(`\u274C ${verb}: a run id is required \u2014 lua workflows ${verb} <runId> (or -r <runId>)`);
-    return WORKFLOW_EXIT.USAGE;
-  }
+  if (!runId) throw CliError.usage(`${verb}: a run id is required`, `lua workflows ${verb} <runId> (or -r <runId>)`);
   return fn();
 }
 __name(requireRun, "requireRun");
@@ -50683,46 +51047,80 @@ function emitJson(ctx, res) {
   if (ctx.json) console.log(JSON.stringify(res, null, 2));
 }
 __name(emitJson, "emitJson");
-function apiFailure(ctx, res, verb) {
-  emitJson(ctx, res);
+var SCHEDULE_PROVISION_FAILED_HINT = "The schedule provider (EventBridge) refused this schedule \u2014 the reason above names what to change; re-run after fixing it. This is not a connectivity problem.";
+function refusalExitCode(status) {
+  if (status === 0 || status !== void 0 && status >= 500) return WORKFLOW_EXIT.UNAVAILABLE;
+  if (status === 404) return WORKFLOW_EXIT.NOT_FOUND;
+  return WORKFLOW_EXIT.API;
+}
+__name(refusalExitCode, "refusalExitCode");
+function apiRefusal(res, verb, detail = {}) {
   const err = res.error;
   const status = err?.statusCode;
   const code = err?.code ?? err?.error;
-  const message = `${verb} failed${code ? ` (${code})` : ""}: ${err?.message ?? "Unknown error"}`;
-  if (status === 0 || status !== void 0 && status >= 500) {
-    throw CliError.fromStatus(status, message, status === 503 && code === "CONTROL_UNAVAILABLE" ? CONTROL_UNAVAILABLE_HINT : void 0);
+  const reason = code === "SCHEDULE_PROVISION_FAILED" ? err?.reason : void 0;
+  const serverMessage = `${err?.message ?? "Unknown error"}${typeof reason === "string" && reason ? `: ${reason}` : ""}`;
+  const message = detail.message ? code ? `${detail.message} (${code})` : detail.message : code ? serverMessage === code ? `${verb} failed (${code})` : `${verb} failed (${code}): ${serverMessage}` : `${verb} failed: ${serverMessage}`;
+  const issues = detail.issues ?? err?.issues;
+  const exitCode = refusalExitCode(status);
+  if (exitCode === WORKFLOW_EXIT.UNAVAILABLE) {
+    return CliError.fromStatus(
+      status,
+      message,
+      status === 503 && code === "CONTROL_UNAVAILABLE" ? CONTROL_UNAVAILABLE_HINT : code === "SCHEDULE_PROVISION_FAILED" ? SCHEDULE_PROVISION_FAILED_HINT : detail.hint,
+      // LUA-810: `fromStatus` picks the UPSTREAM_UNAVAILABLE hint from `upstream` / `requestId` itself.
+      // LUA-812: and the VENDOR_UNAVAILABLE hint from `vendor` / `retryAfterSeconds`.
+      {
+        serverCode: code,
+        issues,
+        upstream: err?.upstream,
+        requestId: err?.requestId,
+        vendor: err?.vendor,
+        retryAfterSeconds: err?.retryAfterSeconds
+      }
+    );
+  }
+  return new CliError(exitCode === WORKFLOW_EXIT.NOT_FOUND ? "not_found" : "error", message, {
+    exitCode,
+    statusCode: status,
+    serverCode: code,
+    issues,
+    hint: detail.hint
+  });
+}
+__name(apiRefusal, "apiRefusal");
+function apiFailure(ctx, res, verb, detail = {}) {
+  if (ctx.json) {
+    emitJson(ctx, res);
+    return refusalExitCode(res.error?.statusCode);
   }
-  if (!ctx.json) console.error(`\u274C ${message}`);
-  if (status === 404) return WORKFLOW_EXIT.NOT_FOUND;
-  return WORKFLOW_EXIT.API;
+  throw apiRefusal(res, verb, detail);
 }
 __name(apiFailure, "apiFailure");
 async function resolveWorkflow(ctx, nameOrId) {
-  const list = await loadWorkflowList(ctx);
-  return list && pickWorkflow(list, nameOrId);
+  return pickWorkflow(await loadWorkflowList(ctx), nameOrId);
 }
 __name(resolveWorkflow, "resolveWorkflow");
 async function loadWorkflowList(ctx) {
   const res = await ctx.api.getWorkflows({
     includeDynamic: true
   });
-  if (!res.success || !res.data) {
-    console.error(`\u274C Failed to list workflows: ${res.error?.message ?? "Unknown error"}`);
-    return void 0;
-  }
+  if (!res.success || !res.data) throw apiRefusal(res, "list");
   return res.data.workflows;
 }
 __name(loadWorkflowList, "loadWorkflowList");
 function pickWorkflow(list, nameOrId) {
   const wf = list.find((w) => w.name === nameOrId) ?? list.find((w) => w.id === nameOrId);
   if (!wf) {
-    console.error(`\u274C Workflow "${nameOrId}" not found`);
-    const names = list.map((w) => w.name);
-    if (names.length) console.log(`   Available: ${names.join(", ")}`);
+    throw CliError.notFound(`Workflow "${nameOrId}" not found`, listHint("Available:", list.map((w) => w.name)));
   }
   return wf;
 }
 __name(pickWorkflow, "pickWorkflow");
+function isDefinitionId(nameOrId) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(nameOrId);
+}
+__name(isDefinitionId, "isDefinitionId");
 var shortHash = /* @__PURE__ */ __name((h) => h ? h.replace(/^sha256-cj1:/, "").slice(0, 12) : "\u2014", "shortHash");
 var when = /* @__PURE__ */ __name((iso) => iso ? new Date(iso).toLocaleString() : "\u2014", "when");
 var clockOf = /* @__PURE__ */ __name((at) => {
@@ -50735,6 +51133,15 @@ var parseIntFlag = /* @__PURE__ */ __name((v, flag) => {
   if (!Number.isFinite(n2)) throw new WorkflowLocalUsageError("usage", `${flag}: expected a number (got "${v}")`);
   return n2;
 }, "parseIntFlag");
+function parsedOrUsage(parse) {
+  try {
+    return parse();
+  } catch (e) {
+    if (e instanceof WorkflowLocalUsageError) throw CliError.usage(e.message);
+    throw e;
+  }
+}
+__name(parsedOrUsage, "parsedOrUsage");
 async function listCore(ctx, opts) {
   const res = await ctx.api.getWorkflows({
     includeDynamic: opts.all
@@ -50921,35 +51328,22 @@ function startResultLine(d, requestedName) {
 }
 __name(startResultLine, "startResultLine");
 async function startCore(ctx, name, o) {
-  const wf = await resolveWorkflow(ctx, name);
-  if (!wf) return WORKFLOW_EXIT.NOT_FOUND;
-  let input = {};
-  let waitSeconds;
-  let budgetCredits;
-  try {
-    if (o.input) input = parseJsonOrFile(o.input, "--input");
-    waitSeconds = parseIntFlag(o.wait, "--wait");
-    budgetCredits = parseIntegerFlag(o.budgetCredits, "--budget-credits", {
-      min: 1
-    });
-  } catch (e) {
-    if (e instanceof WorkflowLocalUsageError) {
-      console.error(`\u274C ${e.message}`);
-      return WORKFLOW_EXIT.USAGE;
-    }
-    throw e;
-  }
+  const input = parsedOrUsage(() => o.input ? parseJsonOrFile(o.input, "--input") : {});
+  const waitSeconds = parsedOrUsage(() => parseIntFlag(o.wait, "--wait"));
+  const budgetCredits = parsedOrUsage(() => parseIntegerFlag(o.budgetCredits, "--budget-credits", {
+    min: 1
+  }));
   if (waitSeconds !== void 0 && (waitSeconds < 0 || waitSeconds > 55)) {
-    console.error("\u274C --wait must be 0..55 (a server long-poll; the CLI raises its own deadline to wait+10 s)");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("--wait must be 0..55 (a server long-poll; the CLI raises its own deadline to wait+10 s)");
   }
   const tags = o.tag === void 0 ? void 0 : Array.isArray(o.tag) ? o.tag : [
     o.tag
   ];
-  if (tags && tags.length > 10) {
-    console.error("\u274C --tag: at most 10 tags");
-    return WORKFLOW_EXIT.USAGE;
-  }
+  if (tags && tags.length > 10) throw CliError.usage("--tag: at most 10 tags");
+  const wf = isDefinitionId(name) ? {
+    id: name,
+    name
+  } : await resolveWorkflow(ctx, name);
   let workflowVersionId;
   if (o.workflowVersion) {
     const ref = await resolveVersionRef(ctx, wf, o.workflowVersion, "start");
@@ -51021,8 +51415,7 @@ async function runsCore(ctx, o) {
   try {
     limit = parseIntFlag(o.limit, "--limit");
   } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`${e.message}`);
   }
   const res = await ctx.api.getRuns({
     workflowId,
@@ -51160,6 +51553,8 @@ function printRun(run, withSteps) {
       console.log(`
 \u23F8\uFE0F  Paused \u2014 run budget reached (${budgetCopy(run)}):`);
       console.log(`   lua workflows raise-budget ${id} --credits <n>`);
+    } else if (kind === "billing") {
+      for (const line of billingParkLines(run)) console.log(line);
     } else {
       console.log(`   Gate:     ${kind}${run.gate.reason ? ` (${run.gate.reason})` : ""}${run.gate.since ? ` since ${when(run.gate.since)}` : ""}`);
     }
@@ -51208,6 +51603,23 @@ function printRun(run, withSteps) {
   }
 }
 __name(printRun, "printRun");
+function billingParkLines(run) {
+  const id = runIdOf(run);
+  const gate = run.gate ?? {
+    kind: "billing"
+  };
+  const what = gate.code === "out_of_actions" ? "the workspace is out of actions" : "the workspace has no credits left";
+  const step3 = gate.stepId ? ` before step ${gate.stepId}` : "";
+  const out = [
+    `
+\u23F8\uFE0F  Paused \u2014 payment required (${what})${step3}:`
+  ];
+  out.push("   top up the workspace (or ask a workspace admin to) \u2014 the run resumes on its own within a few minutes of the top-up");
+  out.push(`   to resume it right away after topping up: lua workflows retry-step ${id} --step ${gate.stepId ?? "<stepId>"}`);
+  if (typeof gate.expiresAt === "number") out.push(`   still unpaid at ${when(gate.expiresAt)} \u21D2 the run fails`);
+  return out;
+}
+__name(billingParkLines, "billingParkLines");
 function stepAttemptLines(s) {
   const out = [];
   const cause = stepFailureLine(s.error);
@@ -51315,15 +51727,8 @@ function attemptCountersLine(c) {
 }
 __name(attemptCountersLine, "attemptCountersLine");
 async function watchCore(ctx, runId, o) {
-  let afterSeq;
-  let timeoutS;
-  try {
-    afterSeq = parseIntFlag(o.after, "--after");
-    timeoutS = parseIntFlag(o.timeout, "--timeout");
-  } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
-  }
+  const afterSeq = parsedOrUsage(() => parseIntFlag(o.after, "--after"));
+  const timeoutS = parsedOrUsage(() => parseIntFlag(o.timeout, "--timeout"));
   const controller = new AbortController();
   let timedOut = false;
   const timer = timeoutS ? setTimeout(() => (timedOut = true, controller.abort()), timeoutS * 1e3) : void 0;
@@ -51332,7 +51737,7 @@ async function watchCore(ctx, runId, o) {
   let lastEventId = afterSeq !== void 0 ? String(afterSeq) : void 0;
   let exit;
   let reconnects = 0;
-  const throttled = /* @__PURE__ */ new Map();
+  const state3 = createWatchState();
   try {
     while (exit === void 0 && !controller.signal.aborted) {
       const res = await ctx.api.watchEvents(runId, {
@@ -51347,7 +51752,7 @@ async function watchCore(ctx, runId, o) {
       let sawEnd = false;
       for await (const frame of res.data) {
         if (frame.id !== void 0) lastEventId = frame.id;
-        const verdict = handleWatchFrame(ctx, runId, frame, o, throttled);
+        const verdict = await handleWatchFrame(ctx, runId, frame, o, state3);
         if (verdict === "reconnect") break;
         if (typeof verdict === "number") {
           exit = verdict;
@@ -51357,10 +51762,10 @@ async function watchCore(ctx, runId, o) {
       }
       if (exit !== void 0 || controller.signal.aborted || sawEnd) break;
       reconnects += 1;
-      if (reconnects > 20) {
-        console.error("\u274C watch: too many reconnects");
-        return WORKFLOW_EXIT.API;
-      }
+      resetWatchReplay(state3);
+      if (reconnects > 20) throw new CliError("error", "watch: too many reconnects", {
+        exitCode: WORKFLOW_EXIT.API
+      });
       if (!ctx.json) console.error(`\u2026 reconnecting (Last-Event-ID ${lastEventId ?? "none"})`);
       await new Promise((r) => setTimeout(r, Math.min(5e3, 250 * 2 ** reconnects)));
     }
@@ -51385,7 +51790,55 @@ function throttledLine(throttled) {
   ].map(([k, n2]) => `${k} \xD7${n2}`).join(" \xB7 ")}`;
 }
 __name(throttledLine, "throttledLine");
-function handleWatchFrame(ctx, runId, frame, o, throttled) {
+function createWatchState() {
+  return {
+    throttled: /* @__PURE__ */ new Map(),
+    signalNames: /* @__PURE__ */ new Map()
+  };
+}
+__name(createWatchState, "createWatchState");
+function resetWatchReplay(state3) {
+  state3.truth = void 0;
+  state3.pending = void 0;
+}
+__name(resetWatchReplay, "resetWatchReplay");
+async function readWatchTruth(ctx, runId) {
+  try {
+    const res = await ctx.api.getRun(runId);
+    if (!res?.success || !res.data) return null;
+    const run = res.data;
+    return {
+      parked: run.status === "suspended" || run.status === "gated",
+      watermark: typeof run.eventSeq === "number" && Number.isFinite(run.eventSeq) ? run.eventSeq : void 0
+    };
+  } catch {
+    return null;
+  }
+}
+__name(readWatchTruth, "readWatchTruth");
+function frameSeq(frame, ev) {
+  const fromId = frame.id === void 0 ? NaN : Number(frame.id);
+  if (Number.isFinite(fromId)) return fromId;
+  return typeof ev.seq === "number" ? ev.seq : void 0;
+}
+__name(frameSeq, "frameSeq");
+async function watchBoundary(ctx, runId, state3, seq, line, code, emit2) {
+  if (state3.truth === void 0 || state3.truth !== null && state3.truth.watermark === void 0) {
+    state3.truth = await readWatchTruth(ctx, runId);
+  }
+  const truth = state3.truth;
+  if (truth === null) return emit2(line, code);
+  if (truth.watermark === void 0 || seq === void 0) return truth.parked ? emit2(line, code) : void 0;
+  if (seq > truth.watermark) return emit2(line, code);
+  if (!truth.parked) return void 0;
+  state3.pending = {
+    line,
+    code
+  };
+  return void 0;
+}
+__name(watchBoundary, "watchBoundary");
+async function handleWatchFrame(ctx, runId, frame, o, state3) {
   const data = frame.data ?? {};
   if (o.events || ctx.json) console.log(JSON.stringify({
     id: frame.id,
@@ -51398,10 +51851,17 @@ function handleWatchFrame(ctx, runId, frame, o, throttled) {
     if (!ctx.json) console.error("   --wait-for-human: still following \u2014 Ctrl+C or --timeout to stop");
     return void 0;
   }, "humanBoundary");
+  const flushPending = /* @__PURE__ */ __name(() => {
+    const pending = state3.pending;
+    if (!pending) return void 0;
+    state3.pending = void 0;
+    return humanBoundary(pending.line, pending.code);
+  }, "flushPending");
   switch (frame.event) {
     case "heartbeat":
-      return void 0;
+      return flushPending();
     case "reconnect":
+      resetWatchReplay(state3);
       return "reconnect";
     case "error": {
       const code = String(data.code ?? "unknown");
@@ -51418,10 +51878,15 @@ function handleWatchFrame(ctx, runId, frame, o, throttled) {
       const type = frame.event || ev.type;
       if (type === "step.throttled") {
         const kind = String(ev.data?.kind ?? "throttled");
-        throttled.set(kind, (throttled.get(kind) ?? 0) + 1);
-        if (!ctx.json && !o.events) process.stdout.write(`\r  ${throttledLine(throttled)}`);
+        state3.throttled.set(kind, (state3.throttled.get(kind) ?? 0) + 1);
+        if (!ctx.json && !o.events) process.stdout.write(`\r  ${throttledLine(state3.throttled)}`);
         return void 0;
       }
+      if (type === "step.suspended") {
+        const d = ev.data;
+        const stepId = ev.stepId ?? (typeof d?.stepId === "string" ? d.stepId : void 0);
+        if (stepId && typeof d?.signalName === "string") state3.signalNames.set(stepId, d.signalName);
+      }
       if (!ctx.json && !o.events) {
         const at = clockOf(ev.ts);
         const subrun = subrunEventDetail({
@@ -51431,39 +51896,58 @@ function handleWatchFrame(ctx, runId, frame, o, throttled) {
         const detail = subrun ? ` \xB7 ${subrun}` : ev.data ? ` ${JSON.stringify(scrubEventData(ev.data)).slice(0, 160)}` : "";
         console.log(`[${at}] ${type}${ev.stepId ? ` \xB7 ${ev.stepId}` : ""}${detail}`);
       }
-      if (type === "run.gated") {
-        const gate = ev.data?.gate;
-        const stepId = ev.data?.stepId;
-        if (gate === "exception") {
-          return humanBoundary(`\u26A0\uFE0F  run parked on an exception gate \u2014 a human decides next: lua workflows status ${runId}`, WORKFLOW_EXIT.RUN_PARKED);
-        }
-        if (gate === "billing") {
-          return humanBoundary(`\u23F8\uFE0F  run parked on a billing gate \u2014 top up, then: lua workflows retry-step ${runId} --step ${stepId ?? "<stepId>"}`, WORKFLOW_EXIT.RUN_PARKED);
-        }
-        if (gate === "budget") {
-          return humanBoundary(`\u23F8\uFE0F  run budget reached \u2014 lua workflows raise-budget ${runId} --credits <n> (lua workflows status ${runId} says what a credit buys)`, WORKFLOW_EXIT.RUN_PARKED);
-        }
-        return humanBoundary(`\u23F8\uFE0F  run gated (${gate ?? "consent"}) \u2014 approve it from the desktop; then: lua workflows watch ${runId}`, WORKFLOW_EXIT.RUN_GATED);
-      }
-      if (type === "run.suspended") {
-        const kind = ev.data?.kind;
-        const stepId = ev.data?.stepId ?? ev.stepId;
-        if (kind === "approval" || kind === "input" || kind === "signal") {
-          const verb = kind === "approval" ? `lua workflows approve ${runId} --approval <id> --decision approve|deny` : kind === "input" ? `lua workflows resume ${runId} --step ${stepId ?? "<stepId>"} --data <json>` : `lua workflows signal ${runId} <name> --payload <json>`;
-          return humanBoundary(`\u23F8\uFE0F  run waits for a person (${kind}${stepId ? ` \xB7 ${stepId}` : ""}) \u2014 ${verb}; then: lua workflows watch ${runId}`, WORKFLOW_EXIT.RUN_PARKED);
-        }
-      }
-      if (type === "run.budget_parked") {
-        return humanBoundary(`\u23F8\uFE0F  run budget reached \u2014 lua workflows raise-budget ${runId} --credits <n> (lua workflows status ${runId} says what a credit buys)`, WORKFLOW_EXIT.RUN_PARKED);
-      }
-      if (type === "run.completed") return WORKFLOW_EXIT.OK;
-      if (type === "run.failed" || type === "run.timed_out") return WORKFLOW_EXIT.RUN_FAILED;
-      if (type === "run.cancelled" || type === "run.abandoned") return WORKFLOW_EXIT.RUN_CANCELLED;
+      if (type === "run.resumed") state3.pending = void 0;
+      const seq = frameSeq(frame, ev);
+      const boundary = /* @__PURE__ */ __name((line, code) => watchBoundary(ctx, runId, state3, seq, line, code, humanBoundary), "boundary");
+      const verdict = await boundaryVerdict(runId, {
+        ...ev,
+        type
+      }, state3, boundary);
+      if (verdict !== void 0) return verdict;
+      const watermark = state3.truth?.watermark;
+      if (watermark !== void 0 && seq !== void 0 && seq >= watermark) return flushPending();
       return void 0;
     }
   }
 }
 __name(handleWatchFrame, "handleWatchFrame");
+async function boundaryVerdict(runId, ev, state3, boundary) {
+  const type = ev.type;
+  if (type === "run.gated") {
+    const gate = ev.data?.gate;
+    const stepId = ev.data?.stepId;
+    if (gate === "exception") {
+      return boundary(`\u26A0\uFE0F  run parked on an exception gate \u2014 a human decides next: lua workflows status ${runId}`, WORKFLOW_EXIT.RUN_PARKED);
+    }
+    if (gate === "billing") {
+      return boundary(`\u23F8\uFE0F  run parked on a billing gate \u2014 top up the workspace; it resumes within a few minutes (right away: lua workflows retry-step ${runId} --step ${stepId ?? "<stepId>"})`, WORKFLOW_EXIT.RUN_PARKED);
+    }
+    if (gate === "budget") {
+      return boundary(`\u23F8\uFE0F  run budget reached \u2014 lua workflows raise-budget ${runId} --credits <n> (lua workflows status ${runId} says what a credit buys)`, WORKFLOW_EXIT.RUN_PARKED);
+    }
+    return boundary(`\u23F8\uFE0F  run gated (${gate ?? "consent"}) \u2014 approve it from the desktop; then: lua workflows watch ${runId}`, WORKFLOW_EXIT.RUN_GATED);
+  }
+  if (type === "run.suspended") {
+    const kind = ev.data?.kind;
+    const stepId = ev.data?.stepId ?? ev.stepId;
+    if (kind === "billing") {
+      return boundary(`\u23F8\uFE0F  run parked on a billing gate \u2014 top up the workspace; it resumes within a few minutes (right away: lua workflows retry-step ${runId} --step ${stepId ?? "<stepId>"})`, WORKFLOW_EXIT.RUN_PARKED);
+    }
+    if (kind === "approval" || kind === "input" || kind === "signal") {
+      const signalName = stepId ? state3.signalNames.get(stepId) : void 0;
+      const verb = kind === "approval" ? `lua workflows approve ${runId} --approval <id> --decision approve|deny` : kind === "input" ? `lua workflows resume ${runId} --step ${stepId ?? "<stepId>"} --data <json>` : `lua workflows signal ${runId} ${signalName ?? "<name>"} --payload <json>`;
+      return boundary(`\u23F8\uFE0F  run waits for a person (${kind}${stepId ? ` \xB7 ${stepId}` : ""}) \u2014 ${verb}; then: lua workflows watch ${runId}`, WORKFLOW_EXIT.RUN_PARKED);
+    }
+  }
+  if (type === "run.budget_parked") {
+    return boundary(`\u23F8\uFE0F  run budget reached \u2014 lua workflows raise-budget ${runId} --credits <n> (lua workflows status ${runId} says what a credit buys)`, WORKFLOW_EXIT.RUN_PARKED);
+  }
+  if (type === "run.completed") return WORKFLOW_EXIT.OK;
+  if (type === "run.failed" || type === "run.timed_out") return WORKFLOW_EXIT.RUN_FAILED;
+  if (type === "run.cancelled" || type === "run.abandoned") return WORKFLOW_EXIT.RUN_CANCELLED;
+  return void 0;
+}
+__name(boundaryVerdict, "boundaryVerdict");
 async function cancelCore(ctx, runId, o) {
   const res = await ctx.api.cancelRun(runId, {
     mode: o.force ? "force" : "request",
@@ -51486,45 +51970,48 @@ async function cancelCore(ctx, runId, o) {
 }
 __name(cancelCore, "cancelCore");
 async function resumeCore(ctx, runId, o) {
-  if (!o.step) {
-    console.error("\u274C resume: --step <id> is required");
-    return WORKFLOW_EXIT.USAGE;
-  }
-  let resumeData = {};
-  try {
-    if (o.data) resumeData = parseJsonOrFile(o.data, "--data");
-  } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
-  }
+  if (!o.step) throw CliError.usage("resume: --step <id> is required");
+  const resumeData = parsedOrUsage(() => o.data ? parseJsonOrFile(o.data, "--data") : {});
   const res = await ctx.api.resumeRun(runId, o.step, {
     resumeData
   });
-  const resumeCode = !res.success ? res.error?.code ?? res.error?.error : void 0;
-  const resumeDetail = res.error;
-  if (!ctx.json && res.error?.statusCode === 400 && resumeCode === "RESUME_SCHEMA_INVALID") {
-    console.error(`\u274C resume rejected \u2014 --data does not match the resumeSchema step "${resumeDetail?.stepId ?? o.step}" declares:`);
-    for (const issue of resumeDetail?.issues ?? []) console.error(`   \u2022 ${issue.path || "/"}: ${issue.message ?? "invalid"}`);
-    console.error("   fix the data and resume again (the step is still waiting for input)");
-  } else if (!ctx.json && res.error?.statusCode === 422 && resumeCode === "RESUME_SCHEMA_UNCOMPILABLE") {
-    console.error(`\u274C resume could not be checked \u2014 the resumeSchema step "${resumeDetail?.stepId ?? o.step}" declares does not compile:`);
-    for (const issue of resumeDetail?.issues ?? []) console.error(`   \u2022 ${issue.message ?? "schema does not compile"}`);
-    console.error("   this is a workflow definition defect, not a data problem \u2014 fix the `resumeSchema` on the step in the workflow source, push a new version, then resume again");
-  }
   if (!res.success || !res.data) {
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 404 && code === "STEP_NOT_FOUND") {
-      console.error(`\u274C step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`);
-    } else if (!ctx.json && res.error?.statusCode === 409) {
-      if (code === "approval_requires_human" || code === "APPROVAL_REQUIRES_HUMAN") {
-        console.error(`\u274C step "${o.step}" is an approval \u2014 resolve it with: lua workflows approve ${runId} --approval ${o.step} --decision approve`);
-      } else if (code === "use_signal_route" || code === "USE_SIGNAL_ROUTE") {
-        console.error(`\u274C step "${o.step}" waits for a signal \u2014 deliver it with: lua workflows signal ${runId} <name> --payload '{}'`);
-      } else if (code === "NOT_SUSPENDED") {
-        console.error(`\u274C step "${o.step}" is not suspended${res.error?.status ? ` (it is ${res.error.status})` : ""} \u2014 nothing to resume: lua workflows status ${runId} --steps`);
-      }
+    const status = res.error?.statusCode;
+    const stepOf3 = res.error?.stepId ?? o.step;
+    let detail = {};
+    if (status === 400 && code === "RESUME_SCHEMA_INVALID") {
+      detail = {
+        message: `resume rejected \u2014 --data does not match the resumeSchema step "${stepOf3}" declares`,
+        issues: res.error?.issues,
+        hint: "fix the data and resume again (the step is still waiting for input)"
+      };
+    } else if (status === 422 && code === "RESUME_SCHEMA_UNCOMPILABLE") {
+      detail = {
+        message: `resume could not be checked \u2014 the resumeSchema step "${stepOf3}" declares does not compile`,
+        issues: (res.error?.issues ?? []).map((issue) => ({
+          message: issue.message ?? "schema does not compile"
+        })),
+        hint: "this is a workflow definition defect, not a data problem \u2014 fix the `resumeSchema` on the step in the workflow source, push a new version, then resume again"
+      };
+    } else if (status === 404 && code === "STEP_NOT_FOUND") {
+      detail = {
+        message: `step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`
+      };
+    } else if (status === 409 && (code === "approval_requires_human" || code === "APPROVAL_REQUIRES_HUMAN")) {
+      detail = {
+        message: `step "${o.step}" is an approval \u2014 resolve it with: lua workflows approve ${runId} --approval ${o.step} --decision approve`
+      };
+    } else if (status === 409 && (code === "use_signal_route" || code === "USE_SIGNAL_ROUTE")) {
+      detail = {
+        message: `step "${o.step}" waits for a signal \u2014 deliver it with: lua workflows signal ${runId} <name> --payload '{}'`
+      };
+    } else if (status === 409 && code === "NOT_SUSPENDED") {
+      detail = {
+        message: `step "${o.step}" is not suspended${res.error?.status ? ` (it is ${res.error.status})` : ""} \u2014 nothing to resume: lua workflows status ${runId} --steps`
+      };
     }
-    return apiFailure(ctx, res, "resume");
+    return apiFailure(ctx, res, "resume", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51539,8 +52026,7 @@ async function resumeCore(ctx, runId, o) {
 __name(resumeCore, "resumeCore");
 async function retryStepCore(ctx, runId, o) {
   if (!o.step) {
-    console.error("\u274C --step <id> is required: lua workflows retry-step <runId> --step <id> [--note <text>]");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("--step <id> is required: lua workflows retry-step <runId> --step <id> [--note <text>]");
   }
   const res = await ctx.api.retryStep(runId, o.step, {
     ...o.note ? {
@@ -51548,21 +52034,30 @@ async function retryStepCore(ctx, runId, o) {
     } : {}
   });
   if (!res.success || !res.data) {
+    let detail = {};
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 404 && code === "STEP_NOT_FOUND") {
-      console.error(`\u274C step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`);
-    } else if (res.error?.statusCode === 409 && !ctx.json) {
-      if (code === "STEP_NOT_PARKED" || code === "step_not_parked") console.error(`\u274C step "${o.step}" is not parked (running, pending or already re-armed) \u2014 nothing to retry`);
-      else if (code === "RUN_TERMINAL" || code === "run_terminal") console.error(`\u274C run ${runId} is terminal \u2014 start a new run instead`);
+    if (res.error?.statusCode === 404 && code === "STEP_NOT_FOUND") {
+      detail = {
+        message: `step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`
+      };
+    } else if (res.error?.statusCode === 409) {
+      if (code === "STEP_NOT_PARKED" || code === "step_not_parked") detail = {
+        message: `step "${o.step}" is not parked (running, pending or already re-armed) \u2014 nothing to retry`
+      };
+      else if (code === "RUN_TERMINAL" || code === "run_terminal") detail = {
+        message: `run ${runId} is terminal \u2014 start a new run instead`
+      };
       else if (code === "STEP_RETRY_CAP" || code === "step_retry_cap") {
         const cap = res.error;
         const at = typeof cap?.attempt === "number" && typeof cap?.maxAttempts === "number" ? ` (attempt ${cap.attempt} of ${cap.maxAttempts})` : "";
-        console.error(`\u274C step "${o.step}" has reached the retry cap${at} \u2014 resolve it or repair the run:
-   lua workflows resolve-step ${runId} --step ${o.step} --outcome skip|complete|fail
-   to start a repair run instead, decide it from the desktop run page`);
+        detail = {
+          message: `step "${o.step}" has reached the retry cap${at} \u2014 resolve it or repair the run`,
+          hint: `lua workflows resolve-step ${runId} --step ${o.step} --outcome skip|complete|fail
+to start a repair run instead, decide it from the desktop run page`
+        };
       }
     }
-    return apiFailure(ctx, res, "retry-step");
+    return apiFailure(ctx, res, "retry-step", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51585,29 +52080,24 @@ __name(refusalIssues, "refusalIssues");
 async function resolveStepCore(ctx, runId, o) {
   const usage = "lua workflows resolve-step <runId> --step <id> --outcome skip|complete|fail [--output <json|@file>] [--note <text>]";
   if (!o.step) {
-    console.error(`\u274C --step <id> is required: ${usage}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`--step <id> is required: ${usage}`);
   }
   const raw = (o.outcome ?? o.action)?.trim().toLowerCase();
   if (raw !== "skip" && raw !== "complete" && raw !== "fail") {
-    console.error(`\u274C --outcome must be skip|complete|fail${raw ? ` (got "${raw}")` : ""}: ${usage}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`--outcome must be skip|complete|fail${raw ? ` (got "${raw}")` : ""}: ${usage}`);
   }
   const outcome = raw;
   let output;
   try {
     if (o.output !== void 0) output = parseJsonOrFile(o.output, "--output");
   } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`${e.message}`);
   }
   if (outcome === "complete" && output === void 0) {
-    console.error(`\u274C --outcome complete needs --output <json|@file> (the output the step would have produced): ${usage}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`--outcome complete needs --output <json|@file> (the output the step would have produced): ${usage}`);
   }
   if (outcome !== "complete" && output !== void 0) {
-    console.error(`\u274C --output rides with --outcome complete only (a ${outcome} carries no output)`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`--output rides with --outcome complete only (a ${outcome} carries no output)`);
   }
   const dto = {
     outcome,
@@ -51620,27 +52110,43 @@ async function resolveStepCore(ctx, runId, o) {
   };
   const res = await ctx.api.resolveStep(runId, o.step, dto);
   if (!res.success || !res.data) {
+    let detail = {};
     const err = res.error;
     const code = err?.code ?? err?.error;
     const status = err?.statusCode;
-    if (!ctx.json && err) {
+    if (err) {
       if (status === 404 && code === "STEP_NOT_FOUND") {
-        console.error(`\u274C step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`);
+        detail = {
+          message: `step "${o.step}" does not exist on run ${runId} \u2014 list its steps: lua workflows status ${runId} --steps`
+        };
       } else if (status === 409 && (code === "STEP_NOT_PARKED" || code === "step_not_parked")) {
-        console.error(`\u274C step "${o.step}" is not parked (running, pending or already decided) \u2014 nothing to resolve`);
+        detail = {
+          message: `step "${o.step}" is not parked (running, pending or already decided) \u2014 nothing to resolve`
+        };
       } else if (status === 409 && (code === "RUN_TERMINAL" || code === "run_terminal")) {
-        console.error(`\u274C run ${runId} is terminal \u2014 start a new run instead`);
+        detail = {
+          message: `run ${runId} is terminal \u2014 start a new run instead`
+        };
       } else if (status === 400 && code === "RESOLVE_OUTPUT_INVALID") {
-        console.error(`\u274C --output does not satisfy the outputSchema of step "${o.step}":`);
-        for (const i of refusalIssues(err)) console.error(`   \u2022 ${i.path ?? "$"}: ${i.message ?? i.code}`);
+        detail = {
+          message: `--output does not satisfy the outputSchema of step "${o.step}"`,
+          issues: refusalIssues(err).map((i) => ({
+            path: i.path ?? "$",
+            message: i.message ?? i.code
+          }))
+        };
       } else if (status === 403 && code === "APPROVAL_REQUIRES_HUMAN") {
-        console.error("\u274C resolve-step is a person's decision \u2014 sign in (lua login) instead of an API key");
+        detail = {
+          message: "resolve-step is a person's decision \u2014 sign in (lua login) instead of an API key"
+        };
       } else if (status === 413 && code === "OUTPUT_TOO_LARGE") {
         const { bytes, maxBytes } = err;
-        console.error(`\u274C --output is over the cap (${bytes ?? "?"} of ${maxBytes ?? 262144} bytes serialized)`);
+        detail = {
+          message: `--output is over the cap (${bytes ?? "?"} of ${maxBytes ?? 262144} bytes serialized)`
+        };
       }
     }
-    return apiFailure(ctx, res, "resolve-step");
+    return apiFailure(ctx, res, "resolve-step", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51702,24 +52208,33 @@ async function raiseBudgetCore(ctx, runId, o) {
   }
   const res = await ctx.api.raiseBudget(runId, dto);
   if (!res.success || !res.data) {
+    let detail = {};
     const err = res.error;
     const code = err?.code ?? err?.error;
     const status = err?.statusCode;
-    if (!ctx.json && err) {
+    if (err) {
       if (status === 400 && code === "CAP_EXCEEDED") {
         const { cap, value: value3, ceiling } = err;
-        console.error(`\u274C ${budgetCapFlag(cap)} ${value3 ?? "?"} is above the org ceiling${ceiling !== void 0 ? ` (${ceiling})` : ""} \u2014 ask an org admin to raise the org cap, or cancel the run`);
+        detail = {
+          message: `${budgetCapFlag(cap)} ${value3 ?? "?"} is above the org ceiling${ceiling !== void 0 ? ` (${ceiling})` : ""} \u2014 ask an org admin to raise the org cap, or cancel the run`
+        };
       } else if (status === 400 && code === "VALIDATION_FAILED") {
-        for (const i of refusalIssues(err)) console.error(`   ${i.code}${i.path ? ` at ${i.path}` : ""}${i.message ? ` \u2014 ${i.message}` : ""}`);
-        console.error(`   the raise must be above the current cap \u2014 lua workflows status ${runId} shows it`);
+        detail = {
+          issues: refusalIssues(err),
+          hint: `the raise must be above the current cap \u2014 lua workflows status ${runId} shows it`
+        };
       } else if (status === 409 && code === "BUDGET_NOT_RAISABLE") {
         const { status: runStatus, notRaisableReason } = err;
-        console.error(notRaisableReason === "raise_cap" ? `\u274C run ${runId} has reached its raise cap \u2014 cancel it, or start a new run with a larger --budget-credits` : `\u274C run ${runId} is ${runStatus ?? "not parked on its budget"} \u2014 only a run parked on its budget takes a raise`);
+        detail = {
+          message: notRaisableReason === "raise_cap" ? `run ${runId} has reached its raise cap \u2014 cancel it, or start a new run with a larger --budget-credits` : `run ${runId} is ${runStatus ?? "not parked on its budget"} \u2014 only a run parked on its budget takes a raise`
+        };
       } else if (status === 403 && code === "NOT_RUN_CREATOR") {
-        console.error("\u274C only the run creator or an org admin can raise a run budget");
+        detail = {
+          message: "only the run creator or an org admin can raise a run budget"
+        };
       }
     }
-    return apiFailure(ctx, res, "raise-budget");
+    return apiFailure(ctx, res, "raise-budget", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51746,24 +52261,20 @@ function approveResultLine(d) {
 __name(approveResultLine, "approveResultLine");
 async function approveCore(ctx, runId, o) {
   if (!o.approval) {
-    console.error("\u274C approve: --approval <id> is required");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("approve: --approval <id> is required");
   }
   const decision = o.decision ?? "approve";
   if (decision !== "approve" && decision !== "deny") {
-    console.error("\u274C approve: --decision must be approve|deny");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("approve: --decision must be approve|deny");
   }
   let editedPayload;
   try {
     if (o.edit) editedPayload = parseJsonOrFile(o.edit, "--edit");
   } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`${e.message}`);
   }
   if (editedPayload !== void 0 && !o.fingerprint) {
-    console.error("\u274C approve: --fingerprint <f> is mandatory with --edit (the payloadFingerprint from approval-payload)");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("approve: --fingerprint <f> is mandatory with --edit (the payloadFingerprint from approval-payload)");
   }
   const res = await ctx.api.resolveApproval(runId, o.approval, {
     decision,
@@ -51772,15 +52283,22 @@ async function approveCore(ctx, runId, o) {
     expectedFingerprint: o.fingerprint
   });
   if (!res.success || !res.data) {
+    let detail = {};
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 404 && code === "APPROVAL_NOT_FOUND") {
-      console.error(`\u274C approval "${o.approval}" not found on run ${runId} \u2014 pass the pending approval's wfa_\u2026 id: lua workflows status ${runId} --steps --json shows it as the suspended step's suspend.approvalId`);
-    } else if (!ctx.json && res.error?.statusCode === 409 && code === "PAYLOAD_MISMATCH") {
-      console.error(`\u274C the payload changed since you looked \u2014 refetch: lua workflows approval-payload ${runId} --approval ${o.approval}`);
-    } else if (!ctx.json && res.error?.statusCode === 403 && code === "STEP_UP_REQUIRED") {
-      console.error("\u274C approve from the desktop with a fresh login (step-up required)");
+    if (res.error?.statusCode === 404 && code === "APPROVAL_NOT_FOUND") {
+      detail = {
+        message: `approval "${o.approval}" not found on run ${runId} \u2014 pass the pending approval's wfa_\u2026 id: lua workflows status ${runId} --steps --json shows it as the suspended step's suspend.approvalId`
+      };
+    } else if (res.error?.statusCode === 409 && code === "PAYLOAD_MISMATCH") {
+      detail = {
+        message: `the payload changed since you looked \u2014 refetch: lua workflows approval-payload ${runId} --approval ${o.approval}`
+      };
+    } else if (res.error?.statusCode === 403 && code === "STEP_UP_REQUIRED") {
+      detail = {
+        message: "approve from the desktop with a fresh login (step-up required)"
+      };
     }
-    return apiFailure(ctx, res, "approve");
+    return apiFailure(ctx, res, "approve", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51794,8 +52312,7 @@ var indentBlock = /* @__PURE__ */ __name((text, pad2 = "     ") => text.split("\
 var APPROVAL_PAYLOAD_PAGE_MAX = 100;
 async function approvalPayloadCore(ctx, runId, o) {
   if (!o.approval) {
-    console.error("\u274C approval-payload: --approval <id> is required \u2014 lua workflows approval-payload <runId> --approval <wfa_\u2026> [--path <array.path>]");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("approval-payload: --approval <id> is required \u2014 lua workflows approval-payload <runId> --approval <wfa_\u2026> [--path <array.path>]");
   }
   let limit;
   try {
@@ -51808,8 +52325,7 @@ async function approvalPayloadCore(ctx, runId, o) {
     throw e;
   }
   if ((o.cursor || limit !== void 0) && !o.path) {
-    console.error("\u274C approval-payload: --cursor / --limit page one array \u2014 pass --path <array.path> with them");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("approval-payload: --cursor / --limit page one array \u2014 pass --path <array.path> with them");
   }
   const res = await ctx.api.getApprovalPayload(runId, o.approval, {
     path: o.path,
@@ -51817,13 +52333,18 @@ async function approvalPayloadCore(ctx, runId, o) {
     limit
   });
   if (!res.success || !res.data) {
+    let detail = {};
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 404 && code === "APPROVAL_NOT_FOUND") {
-      console.error(`\u274C approval "${o.approval}" not found on run ${runId} \u2014 lua workflows status ${runId} --steps --json shows the suspended step's suspend.approvalId`);
-    } else if (!ctx.json && res.error?.statusCode === 413 && code === "PAYLOAD_PAGE_REQUIRED") {
-      console.error("\u274C the payload is too large to read whole \u2014 page an array with --path <array.path> [--limit <n>] [--cursor <c>]");
+    if (res.error?.statusCode === 404 && code === "APPROVAL_NOT_FOUND") {
+      detail = {
+        message: `approval "${o.approval}" not found on run ${runId} \u2014 lua workflows status ${runId} --steps --json shows the suspended step's suspend.approvalId`
+      };
+    } else if (res.error?.statusCode === 413 && code === "PAYLOAD_PAGE_REQUIRED") {
+      detail = {
+        message: "the payload is too large to read whole \u2014 page an array with --path <array.path> [--limit <n>] [--cursor <c>]"
+      };
     }
-    return apiFailure(ctx, res, "approval-payload");
+    return apiFailure(ctx, res, "approval-payload", detail);
   }
   emitJson(ctx, res);
   if (!ctx.json) {
@@ -51887,16 +52408,9 @@ function reservedSecretKeyPaths(value3, path25 = "", depth = 0, out = []) {
 __name(reservedSecretKeyPaths, "reservedSecretKeyPaths");
 async function signalCore(ctx, runId, name, o) {
   if (!name) {
-    console.error("\u274C signal: usage \u2014 lua workflows signal <runId> <name> [--payload <json|@file>]");
-    return WORKFLOW_EXIT.USAGE;
-  }
-  let payload;
-  try {
-    if (o.payload) payload = parseJsonOrFile(o.payload, "--payload");
-  } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("signal: a signal name is required", "lua workflows signal <runId> <name> [--payload <json|@file>]");
   }
+  const payload = parsedOrUsage(() => o.payload ? parseJsonOrFile(o.payload, "--payload") : void 0);
   const reserved = reservedSecretKeyPaths(payload);
   if (reserved.length > 0) {
     const many = reserved.length > 1;
@@ -51908,22 +52422,24 @@ async function signalCore(ctx, runId, name, o) {
   });
   if (!res.success || !res.data) {
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 400 && code === "SIGNAL_SCHEMA_INVALID") {
-      const where = res.error?.stepId ? `step "${res.error.stepId}"` : "the waiting step";
-      console.error(`\u274C signal "${name}" rejected \u2014 the payload does not match the schema ${where} declares:`);
-      for (const issue of res.error?.issues ?? []) {
-        console.error(`   \u2022 ${issue.path || "/"}: ${issue.message ?? "invalid"}`);
-      }
-      console.error("   fix the payload and send it again (a --dedupe-key is not consumed by a rejected signal)");
-    } else if (!ctx.json && res.error?.statusCode === 422 && code === "SIGNAL_SCHEMA_UNCOMPILABLE") {
-      const where = res.error?.stepId ? `step "${res.error.stepId}"` : "the waiting step";
-      console.error(`\u274C signal "${name}" could not be checked \u2014 the schema ${where} declares does not compile:`);
-      for (const issue of res.error?.issues ?? []) {
-        console.error(`   \u2022 ${issue.message ?? "schema does not compile"}`);
-      }
-      console.error(`   this is a workflow definition defect, not a payload problem \u2014 fix the \`schema\` on the waitForSignal node in the workflow source, push a new version, then send the signal again`);
+    const where = res.error?.stepId ? `step "${res.error.stepId}"` : "the waiting step";
+    let detail = {};
+    if (res.error?.statusCode === 400 && code === "SIGNAL_SCHEMA_INVALID") {
+      detail = {
+        message: `signal "${name}" rejected \u2014 the payload does not match the schema ${where} declares`,
+        issues: res.error?.issues,
+        hint: "fix the payload and send it again (a --dedupe-key is not consumed by a rejected signal)"
+      };
+    } else if (res.error?.statusCode === 422 && code === "SIGNAL_SCHEMA_UNCOMPILABLE") {
+      detail = {
+        message: `signal "${name}" could not be checked \u2014 the schema ${where} declares does not compile`,
+        issues: (res.error?.issues ?? []).map((issue) => ({
+          message: issue.message ?? "schema does not compile"
+        })),
+        hint: "this is a workflow definition defect, not a payload problem \u2014 fix the `schema` on the waitForSignal node in the workflow source, push a new version, then send the signal again"
+      };
     }
-    return apiFailure(ctx, res, "signal");
+    return apiFailure(ctx, res, "signal", detail);
   }
   emitJson(ctx, res);
   const r = res.data;
@@ -51936,8 +52452,7 @@ async function signalCore(ctx, runId, name, o) {
 __name(signalCore, "signalCore");
 async function replayCore(ctx, runId, o) {
   if (!o.local) {
-    console.error("\u274C replay: only `--local` is available (server-side replay is not a v1 route)");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("replay: only `--local` is available (server-side replay is not a v1 route)");
   }
   const runRes = await ctx.api.getRun(runId);
   if (!runRes.success || !runRes.data) return apiFailure(ctx, runRes, "replay");
@@ -51946,8 +52461,7 @@ async function replayCore(ctx, runId, o) {
   try {
     manifestWorkflows = getPrimitivesByKind(loadManifest(), PrimitiveKind.WORKFLOW);
   } catch (e) {
-    console.error(`\u274C replay --local needs a compiled project: ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`replay --local needs a compiled project: ${e.message}`);
   }
   const wf = (o.workflowName ? manifestWorkflows.find((w) => w.name === o.workflowName) : void 0) ?? manifestWorkflows.find((w) => w.graphHash === run.graphHash);
   if (!wf) {
@@ -52193,11 +52707,11 @@ async function deleteRunCore(ctx, runId, o) {
   const res = await ctx.api.eraseRun(runId);
   if (!res.success || !res.data) {
     const code = res.error?.code ?? res.error?.error;
-    if (!ctx.json && res.error?.statusCode === 409 && code === "RUN_NOT_TERMINAL") {
+    if (res.error?.statusCode === 409 && code === "RUN_NOT_TERMINAL") {
       const status = res.error.status;
-      console.error(`\u274C run is \`${status ?? "live"}\`; cancel it first: lua workflows cancel ${runId}`);
-      emitJson(ctx, res);
-      return WORKFLOW_EXIT.API;
+      return apiFailure(ctx, res, "delete-run", {
+        message: `run is \`${status ?? "live"}\`; cancel it first: lua workflows cancel ${runId}`
+      });
     }
     return apiFailure(ctx, res, "delete-run");
   }
@@ -52315,17 +52829,14 @@ async function archiveRunsCore(ctx, o) {
   const now = Date.now();
   const since = parseSinceFlag(o.since, now);
   if (!Number.isFinite(since)) {
-    console.error("\u274C archive-runs: --since <iso|dur> is required (e.g. --since 8d)");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("archive-runs: --since <iso|dur> is required (e.g. --since 8d)");
   }
   const until = o.until ? Date.parse(o.until) : void 0;
   if (o.until && !Number.isFinite(until)) {
-    console.error(`\u274C archive-runs: --until is not an ISO timestamp ("${o.until}")`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`archive-runs: --until is not an ISO timestamp ("${o.until}")`);
   }
   if (!o.out) {
-    console.error("\u274C archive-runs: --out <dir> is required");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("archive-runs: --out <dir> is required");
   }
   if (/^(s3|gs):\/\//.test(o.out)) {
     console.error(`\u274C archive-runs: remote sinks (${o.out}) need the org storage connection (--connection) \u2014 not wired in this build; archive to a local dir and sync it`);
@@ -52589,11 +53100,14 @@ async function workspaceCore(ctx, runId, o) {
       note: o.note
     } : {});
     if (!res2.success || !res2.data) {
-      if (res2.error?.statusCode === 409 && !ctx.json) {
+      let detail = {};
+      if (res2.error?.statusCode === 409) {
         const stepId = res2.error.stepId;
-        console.error(`\u274C Workspace of ${runId} is in use${stepId ? ` by step ${stepId}` : ""} \u2014 cancel the run or wait for the step to finish`);
+        detail = {
+          message: `Workspace of ${runId} is in use${stepId ? ` by step ${stepId}` : ""} \u2014 cancel the run or wait for the step to finish`
+        };
       }
-      return apiFailure(ctx, res2, "workspace");
+      return apiFailure(ctx, res2, "workspace", detail);
     }
     emitJson(ctx, res2);
     if (!ctx.json) {
@@ -52674,14 +53188,12 @@ function printJobHeader(v) {
 __name(printJobHeader, "printJobHeader");
 async function jobLogsCore(ctx, runId, stepId, o) {
   if (!stepId) {
-    console.error(`\u274C job-logs: a step id is required \u2014 lua workflows job-logs ${runId} <stepId>`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`job-logs: a step id is required \u2014 lua workflows job-logs ${runId} <stepId>`);
   }
   const attempt = o.attempt !== void 0 && o.attempt !== "" ? Number(o.attempt) : void 0;
   const tail = o.tail !== void 0 && o.tail !== "" ? Number(o.tail) : JOB_LOG_TAIL_DEFAULT;
   if (attempt !== void 0 && !(Number.isInteger(attempt) && attempt >= 1) || !(Number.isInteger(tail) && tail >= 1 && tail <= JOB_LOG_TAIL_MAX)) {
-    console.error(`\u274C job-logs: --attempt must be \u2265 1 and --tail an integer in 1..${JOB_LOG_TAIL_MAX}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`job-logs: --attempt must be \u2265 1 and --tail an integer in 1..${JOB_LOG_TAIL_MAX}`);
   }
   let printed = 0;
   let first = true;
@@ -52691,18 +53203,18 @@ async function jobLogsCore(ctx, runId, stepId, o) {
       tail
     });
     if (!res.success || !res.data) {
-      if (res.error?.statusCode === 404 && res.error?.code === "JOB_NOT_FOUND" && !ctx.json) {
-        console.error(`\u274C ${stepId} is not a Job-tier step of ${runId} (try: lua workflows jobs ${runId})`);
-      }
-      if (res.error?.statusCode === 404 && res.error?.code === "JOB_LOGS_NOT_PERSISTED") {
-        emitJson(ctx, res);
-        if (!ctx.json) {
-          console.error(`\u274C job-logs: ${res.error.message}`);
-          writeInfo(`   lua workflows status ${runId} --steps shows the step error; --attempt <n> reads another attempt.`);
-        }
-        return WORKFLOW_EXIT.NOT_FOUND;
+      let detail = {};
+      if (res.error?.statusCode === 404 && res.error?.code === "JOB_NOT_FOUND") {
+        detail = {
+          message: `${stepId} is not a Job-tier step of ${runId} (try: lua workflows jobs ${runId})`
+        };
+      } else if (res.error?.statusCode === 404 && res.error?.code === "JOB_LOGS_NOT_PERSISTED") {
+        detail = {
+          message: `job-logs: ${res.error.message}`,
+          hint: `lua workflows status ${runId} --steps shows the step error; --attempt <n> reads another attempt.`
+        };
       }
-      return apiFailure(ctx, res, "job-logs");
+      return apiFailure(ctx, res, "job-logs", detail);
     }
     const v = res.data;
     if (ctx.json && !o.follow) {
@@ -52965,38 +53477,54 @@ function subVerb(group, noun, raw, verbs) {
 }
 __name(subVerb, "subVerb");
 function goalFailure(ctx, res, verb, ref) {
+  let detail = {};
   const err = res.error;
   const code = err?.code ?? err?.error;
   const status = err?.statusCode;
-  if (!ctx.json && err) {
+  if (err) {
     if (status === 409 && code === "GOAL_NOT_ACTIVE") {
       const now = err.status ?? "not active";
       const rule = verb === "goals resume" ? "only a paused goal resumes" : verb === "goals pause" ? "only an active goal pauses" : "a done/closed goal stays closed (a lingering cadence Job goes with `lua workflows schedules delete <jobId>`)";
-      console.error(`\u274C goal ${ref ?? ""} is ${now} \u2014 ${rule}`);
-      if (verb === "goals resume" && now === "paused") console.error(`   ${goalRaiseHint(ref ?? "<goalId>")}`);
+      detail = {
+        message: `goal ${ref ?? ""} is ${now} \u2014 ${rule}`,
+        hint: verb === "goals resume" && now === "paused" ? goalRaiseHint(ref ?? "<goalId>") : void 0
+      };
     } else if (status === 400 && code === "GOAL_RAISE_BELOW_SPENT") {
       const { field, value: value3, spent } = err;
       const flag = field === "maxRuns" ? "--max-runs" : "--max-credits";
       const used = field === "maxRuns" ? "run(s) already used" : "credit(s) already spent";
-      console.error(`\u274C ${flag} ${value3 ?? "?"} is not above the ${spent ?? "?"} ${used} \u2014 raise it past ${spent ?? "?"}`);
+      detail = {
+        message: `${flag} ${value3 ?? "?"} is not above the ${spent ?? "?"} ${used} \u2014 raise it past ${spent ?? "?"}`
+      };
     } else if (status === 409 && code === "GOAL_VERSION_CONFLICT") {
       const at = err.updatedAt;
-      console.error(`\u274C goal ${ref ?? ""} changed since it was read${at ? ` (updatedAt ${at})` : ""} \u2014 re-run lua workflows goals get ${ref ?? "<goalId>"} and retry${at ? ` with --if-match ${at}` : ""}`);
+      detail = {
+        message: `goal ${ref ?? ""} changed since it was read${at ? ` (updatedAt ${at})` : ""} \u2014 re-run lua workflows goals get ${ref ?? "<goalId>"} and retry${at ? ` with --if-match ${at}` : ""}`
+      };
     } else if (status === 409 && code === "GOAL_CAP") {
-      console.error(`\u274C goal cap reached (${err.cap ?? "?"} per agent) \u2014 close or finish one first: lua workflows goals list --status active`);
+      detail = {
+        message: `goal cap reached (${err.cap ?? "?"} per agent) \u2014 close or finish one first: lua workflows goals list --status active`
+      };
     } else if (status === 400 && code === "VALIDATION_FAILED") {
-      const issues = err.issues ?? [];
-      for (const i of issues) console.error(`   ${i.code}${i.path ? ` at ${i.path}` : ""}${i.message ? ` \u2014 ${i.message}` : ""}`);
+      detail = {
+        issues: refusalIssues(err)
+      };
     } else if (status === 400 && code === "GOAL_MAX_RUNS_INVALID") {
-      console.error(`\u274C --max-runs must be 1..${GOAL_MAX_RUNS_CAP}`);
+      detail = {
+        message: `--max-runs must be 1..${GOAL_MAX_RUNS_CAP}`
+      };
     } else if (status === 400 && code === "WORKFLOW_NOT_ON_AGENT") {
-      console.error(`\u274C that workflow belongs to another agent \u2014 goals are scoped to ${ctx.agentId}`);
+      detail = {
+        message: `that workflow belongs to another agent \u2014 goals are scoped to ${ctx.agentId}`
+      };
     } else if (status === 409 && code === "GOAL_SCHEDULE") {
       const goalId = err.goalId ?? "?";
-      console.error(`\u274C GOAL_SCHEDULE: ${goalScheduleRefusal(ref ?? "<jobId>", goalId)}`);
+      detail = {
+        message: `GOAL_SCHEDULE: ${goalScheduleRefusal(ref ?? "<jobId>", goalId)}`
+      };
     }
   }
-  return apiFailure(ctx, res, verb);
+  return apiFailure(ctx, res, verb, detail);
 }
 __name(goalFailure, "goalFailure");
 async function goalsCore(ctx, target, extra, o) {
@@ -53005,8 +53533,7 @@ async function goalsCore(ctx, target, extra, o) {
   if (verb === "list") return goalsListCore(ctx, o, extra);
   if (verb === "create") return goalsCreateCore(ctx, o, extra);
   if (!extra) {
-    console.error(`\u274C goals ${verb}: a goal id is required \u2014 lua workflows goals ${verb} <goalId>`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`goals ${verb}: a goal id is required \u2014 lua workflows goals ${verb} <goalId>`);
   }
   if (verb === "get") return goalsGetCore(ctx, extra);
   if (verb === "edit") return goalsEditCore(ctx, extra, o);
@@ -53016,8 +53543,7 @@ async function goalsCore(ctx, target, extra, o) {
 __name(goalsCore, "goalsCore");
 async function goalsListCore(ctx, o, positional) {
   if (o.status && !GOAL_STATUSES.includes(o.status)) {
-    console.error(`\u274C goals list: --status must be ${GOAL_STATUSES.join("|")} (got "${o.status}")`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`goals list: --status must be ${GOAL_STATUSES.join("|")} (got "${o.status}")`);
   }
   let limit;
   try {
@@ -53026,8 +53552,7 @@ async function goalsListCore(ctx, o, positional) {
       max: GOAL_PAGE_LIMIT
     });
   } catch (e) {
-    console.error(`\u274C ${e.message}`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`${e.message}`);
   }
   const list = await loadWorkflowList(ctx);
   if (!list) return WORKFLOW_EXIT.API;
@@ -53188,8 +53713,7 @@ async function goalsEditCore(ctx, goalId, o) {
     if (Object.keys(dto).filter((k) => k !== "ifMatch").length === 0) throw usage("nothing to change \u2014 pass --objective, --judge-predicate, --cadence | --every, --max-runs, --max-credits <n|none> or --note");
   } catch (e) {
     if (e instanceof WorkflowLocalUsageError) {
-      console.error(`\u274C goals edit: ${e.message}`);
-      return WORKFLOW_EXIT.USAGE;
+      throw CliError.usage(`goals edit: ${e.message}`);
     }
     throw e;
   }
@@ -53221,8 +53745,7 @@ async function goalsRaiseCore(ctx, goalId, o) {
     if (ifMatch !== void 0) dto.ifMatch = ifMatch;
   } catch (e) {
     if (e instanceof WorkflowLocalUsageError) {
-      console.error(`\u274C goals raise: ${e.message}`);
-      return WORKFLOW_EXIT.USAGE;
+      throw CliError.usage(`goals raise: ${e.message}`);
     }
     throw e;
   }
@@ -53308,20 +53831,16 @@ __name(parseCadenceFlag, "parseCadenceFlag");
 async function goalsCreateCore(ctx, o, positional) {
   const target = positional ?? o.workflowName ?? o.workflow;
   if (!target) {
-    console.error("\u274C goals create: a workflow is required \u2014 lua workflows goals create <workflow> (or -i <workflow>)");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("goals create: a workflow is required \u2014 lua workflows goals create <workflow> (or -i <workflow>)");
   }
   if (!o.objective?.trim()) {
-    console.error("\u274C goals create: --objective <text> is required");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("goals create: --objective <text> is required");
   }
   if (o.judgeAgent === "") {
-    console.error("\u274C goals create: --judge-agent is empty \u2014 an unquoted $self is expanded by the shell to nothing; write '$self' (quoted) or self");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("goals create: --judge-agent is empty \u2014 an unquoted $self is expanded by the shell to nothing; write '$self' (quoted) or self");
   }
   if (!o.judgePredicate && !o.judgeAgent) {
-    console.error("\u274C goals create: one of --judge-predicate <spec> | --judge-agent <agentId|'$self'> is required");
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage("goals create: one of --judge-predicate <spec> | --judge-agent <agentId|'$self'> is required");
   }
   const usage = /* @__PURE__ */ __name((m) => new WorkflowLocalUsageError("usage", m), "usage");
   let dto;
@@ -53381,8 +53900,7 @@ async function goalsCreateCore(ctx, o, positional) {
     };
   } catch (e) {
     if (e instanceof WorkflowLocalUsageError) {
-      console.error(`\u274C ${e.message}`);
-      return WORKFLOW_EXIT.USAGE;
+      throw CliError.usage(`${e.message}`);
     }
     throw e;
   }
@@ -53424,8 +53942,7 @@ async function schedulesCore(ctx, target, extra, o) {
   if (verb === "list") return schedulesListCore(ctx, o);
   if (verb === "create") return schedulesCreateCore(ctx, o, extra);
   if (!extra) {
-    console.error(`\u274C schedules ${verb}: a schedule (job) id is required \u2014 lua workflows schedules ${verb} <jobId>`);
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage(`schedules ${verb}: a schedule (job) id is required \u2014 lua workflows schedules ${verb} <jobId>`);
   }
   if (verb === "delete") return schedulesDeleteCore(ctx, extra, o);
   return schedulesPatchCore(ctx, extra, verb, o);
@@ -53480,17 +53997,19 @@ async function schedulesDeleteCore(ctx, jobId, o) {
     const goalRes = await ctx.api.getGoal(goalId);
     if (goalRes.success && goalRes.data) goalStatus = goalRes.data.status;
     else if (goalRes.error?.statusCode !== 404) {
-      if (!ctx.json) console.error(`\u274C cannot prove goal ${goalId} of ${jobId} has ended (goal unreadable) \u2014 refusing to delete`);
-      return apiFailure(ctx, goalRes, "schedules delete");
+      return apiFailure(ctx, goalRes, "schedules delete", {
+        message: `cannot prove goal ${goalId} of ${jobId} has ended (goal unreadable) \u2014 refusing to delete`
+      });
     }
   } else {
     const goals = await loadGoals(ctx, row2.workflowId);
     if (goals.error) {
-      if (!ctx.json) console.error(`\u274C cannot prove ${jobId} is not a goal's cadence (goals unavailable) \u2014 refusing to delete`);
       return apiFailure(ctx, {
         success: false,
         error: goals.error
-      }, "schedules delete");
+      }, "schedules delete", {
+        message: `cannot prove ${jobId} is not a goal's cadence (goals unavailable) \u2014 refusing to delete`
+      });
     }
     const owner = goals.items.find((g) => g.jobId === jobId);
     goalId = owner?.goalId;
@@ -53541,8 +54060,7 @@ var SCHEDULE_NOTIFY = [
 async function schedulesCreateCore(ctx, o, positional) {
   const target = positional ?? o.workflowName ?? o.workflow;
   if (!target) {
-    console.error('\u274C schedules create: a workflow is required \u2014 lua workflows schedules create <workflow> --cadence "0 9 * * 1" --timezone Europe/London');
-    return WORKFLOW_EXIT.USAGE;
+    throw CliError.usage('schedules create: a workflow is required \u2014 lua workflows schedules create <workflow> --cadence "0 9 * * 1" --timezone Europe/London');
   }
   let draft;
   try {
@@ -53669,11 +54187,12 @@ async function schedulesPatchCore(ctx, jobId, verb, o) {
   if (!rowRes.success || !rowRes.data) return apiFailure(ctx, rowRes, label);
   const owner = await scheduleGoalOwner(ctx, rowRes.data);
   if (owner.error) {
-    if (!ctx.json) console.error(`\u274C cannot prove ${jobId} is not a goal's cadence (goals unavailable) \u2014 refusing to ${verb}`);
     return apiFailure(ctx, {
       success: false,
       error: owner.error
-    }, label);
+    }, label, {
+      message: `cannot prove ${jobId} is not a goal's cadence (goals unavailable) \u2014 refusing to ${verb}`
+    });
   }
   if (owner.goalId) {
     const message = `Schedule ${jobId} is the cadence of goal ${owner.goalId} and was NOT changed. Pause or resume the goal instead: lua workflows goals pause ${owner.goalId} / lua workflows goals resume ${owner.goalId} \u2014 a goal's Job follows its goal, never the other way round.`;
@@ -55353,6 +55872,7 @@ init_cli();
 // src/api/marketplace.api.service.ts
 init_constants();
 init_lua_fetch();
+init_http_client();
 init_request_credential();
 var MarketplaceApiService = class {
   static {
@@ -55377,8 +55897,7 @@ var MarketplaceApiService = class {
       headers
     });
     if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`API Error: ${response.status} ${response.statusText} - ${errorText}`);
+      throw await refusalFromResponse(response);
     }
     if (response.status === 204) {
       return null;
@@ -55501,6 +56020,7 @@ import { readFileSync as readFileSync14 } from "fs";
 // src/api/template.api.service.ts
 init_constants();
 init_lua_fetch();
+init_http_client();
 init_request_credential();
 var TemplateApiService = class {
   static {
@@ -55523,8 +56043,7 @@ var TemplateApiService = class {
       headers
     });
     if (!response.ok) {
-      const errorText = await response.text();
-      throw new Error(`API Error: ${response.status} ${response.statusText} - ${errorText}`);
+      throw await refusalFromResponse(response);
     }
     if (response.status === 204) {
       return null;
@@ -55747,6 +56266,11 @@ function sleep2(ms) {
   return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 __name(sleep2, "sleep");
+function missingVersionOrRethrow(error) {
+  if (CliError.isCliError(error) && error.statusCode === 404) return null;
+  throw error;
+}
+__name(missingVersionOrRethrow, "missingVersionOrRethrow");
 async function resolveTemplateId(templateApi, options, message) {
   if (options.templateId) return options.templateId;
   writeProgress("\u{1F504} Loading your templates...");
@@ -56123,8 +56647,8 @@ async function templateViewAction(templateApi, options) {
     if (!Number.isFinite(versionNum) || versionNum <= 0) {
       throw new Error(`Invalid --version "${options.version}": must be a positive integer.`);
     }
-    const version = await templateApi.getVersion(templateId, versionNum).catch(() => null);
-    if (!version) throw new Error(`Version v${versionNum} not found for this template.`);
+    const version = await templateApi.getVersion(templateId, versionNum).catch(missingVersionOrRethrow);
+    if (!version) throw CliError.notFound(`Version v${versionNum} not found for this template.`);
     if (options.json) {
       console.log(JSON.stringify(version, null, 2));
       return;
@@ -56288,8 +56812,8 @@ async function templateApplyAction(templateApi, options) {
     throw new Error("This template has no published versions. Run `lua marketplace template publish` first.");
   }
   const versionNum = options.version ? Number.parseInt(options.version, 10) : template3.latestVersion;
-  const versionObj = await templateApi.getVersion(templateId, versionNum).catch(() => null);
-  if (!versionObj) throw new Error(`Version v${versionNum} not found for this template.`);
+  const versionObj = await templateApi.getVersion(templateId, versionNum).catch(missingVersionOrRethrow);
+  if (!versionObj) throw CliError.notFound(`Version v${versionNum} not found for this template.`);
   if (!options.force) {
     console.log(`
 Apply plan:`);
@@ -56540,45 +57064,57 @@ var SKILL_ACTION_LABELS = {
   org: "View this organization's owned skills"
 };
 async function marketplaceCommand(noun, action, options = {}) {
-  return withErrorHandling(async () => {
-    let domain;
-    if (noun) {
-      domain = validateOrSuggest("marketplace.noun", noun);
-    } else {
-      const domainAnswer = await safePrompt([
-        {
-          type: "list",
-          name: "domain",
-          message: "What would you like to browse?",
-          choices: [
-            {
-              name: "Skills",
-              value: "skill"
-            },
-            {
-              name: "Agent templates",
-              value: "template"
-            },
-            {
-              name: "Exit",
-              value: "exit"
-            }
-          ]
-        }
-      ]);
-      if (!domainAnswer || domainAnswer.domain === "exit") {
-        console.log("\n\u{1F44B} Goodbye!\n");
-        return;
-      }
-      domain = domainAnswer.domain;
-    }
-    if (domain === "template") {
-      return templateCommand(action, options);
+  return withErrorHandling(
+    async () => {
+      await marketplaceDispatch(noun, action, options);
+    },
+    "marketplace",
+    // LUA-803: under `--json` an escaped refusal (a template 403 / 404, a network failure) is the typed envelope on
+    // stdout, not the `✖` line.
+    {
+      json: /* @__PURE__ */ __name(() => !!options.json, "json")
     }
-    return skillMarketplaceCommand(action, options);
-  }, "marketplace");
+  );
 }
 __name(marketplaceCommand, "marketplaceCommand");
+async function marketplaceDispatch(noun, action, options) {
+  let domain;
+  if (noun) {
+    domain = validateOrSuggest("marketplace.noun", noun);
+  } else {
+    const domainAnswer = await safePrompt([
+      {
+        type: "list",
+        name: "domain",
+        message: "What would you like to browse?",
+        choices: [
+          {
+            name: "Skills",
+            value: "skill"
+          },
+          {
+            name: "Agent templates",
+            value: "template"
+          },
+          {
+            name: "Exit",
+            value: "exit"
+          }
+        ]
+      }
+    ]);
+    if (!domainAnswer || domainAnswer.domain === "exit") {
+      console.log("\n\u{1F44B} Goodbye!\n");
+      return;
+    }
+    domain = domainAnswer.domain;
+  }
+  if (domain === "template") {
+    return templateCommand(action, options);
+  }
+  return skillMarketplaceCommand(action, options);
+}
+__name(marketplaceDispatch, "marketplaceDispatch");
 async function skillMarketplaceCommand(action, options = {}) {
   const { config, apiKey } = await initializeCommand();
   const marketplaceApi = new MarketplaceApiService(apiKey, config.agent?.orgId);
@@ -56735,7 +57271,7 @@ async function listSkillNonInteractive(marketplaceApi, config, apiKey, options)
   writeProgress("\u{1F504} Verifying skill...");
   const agentSkillsResponse = await skillApi.getSkills();
   if (!agentSkillsResponse.success || !agentSkillsResponse.data) {
-    throw CliError.fromStatus(agentSkillsResponse.error?.statusCode, `Failed to fetch agent skills: ${agentSkillsResponse.error?.message ?? agentSkillsResponse.message ?? "Unknown error"}`);
+    throw CliError.fromStatus(agentSkillsResponse.error?.statusCode, `Failed to fetch agent skills: ${agentSkillsResponse.error?.message ?? agentSkillsResponse.message ?? "Unknown error"}`, void 0, apiErrorDetail(agentSkillsResponse.error));
   }
   const skill = agentSkillsResponse.data.skills?.find((s) => s.name === skillName);
   if (!skill) {
@@ -64712,7 +65248,7 @@ Examples:
   $ lua init --from-agent-id baseAgent_agent_xxx                  Duplicate agent + scaffold project
   $ lua init --from-agent-id baseAgent_agent_xxx --org-id <id>    Cross-org duplicate
 `).action(initCommand);
-  program2.command("compile").description("\u{1F4E6} Compile skill to deployable format").option("--verbose", "Show detailed progress output").option("--debug", "Enable debug mode with extra verbose logging and temp file preservation").option("--sync", "Run drift detection check before compiling").action((opts) => compileCommand({
+  program2.command("compile").description("\u{1F4E6} Compile skill to deployable format").option("--verbose", "Show detailed progress output").option("--debug", "Enable debug mode with extra verbose logging and temp file preservation").option("--sync", "Check for drift against the server before compiling (reads only \u2014 nothing is written)").action((opts) => compileCommand({
     ...opts,
     topLevel: true
   }));