@moda-ai/cli 1.55.25 → 1.55.27

package/dist/cli.js

@@ -1,11 +1,31 @@
 #!/usr/bin/env node
 import {
-  MODA_INTELLIGENCE_V1_JSON_SCHEMA
-} from "./cli-bb7133m7.js";
+  BATCH_CONCURRENCY,
+  BATCH_MAX_TARGETS,
+  MODA_INTELLIGENCE_V1_JSON_SCHEMA,
+  asNumber,
+  asRecord,
+  asString,
+  collectBatchTargets,
+  compactProblemDossier,
+  contextTarget,
+  embeddedWindowSize,
+  frustrationsFromEmotions,
+  mapWithConcurrency,
+  parseBatchTarget,
+  trimToolFailureConversations,
+  withFrustrationAnchors,
+  withToolFailureAnchors,
+  withoutDetectionWindows
+} from "./cli-vdkwkkp5.js";
 import {
   createCommandContext,
-  parseBooleanFlagValue
-} from "./cli-qvg26twp.js";
+  envOptOutSet,
+  envSwitchedOff,
+  optOutFlagSet,
+  parseBooleanFlagValue,
+  withoutFlag
+} from "./cli-v8q7sd7g.js";
 import {
   AuditSchema,
   COMMAND_FLAG_SPECS,
@@ -29,6 +49,7 @@ import {
   assertPositionals,
   buildFeedbackRequest,
   closestMatches,
+  describeField,
   describeSpecFlags,
   flagSpecFor,
   isFeedbackRefFlag,
@@ -43,17 +64,17 @@ import {
   specFlagKeys,
   specFlagNames,
   subcommandHelpFlags,
-  unknownSignalsSubcommandError
-} from "./cli-dn91fb56.js";
+  unknownSignalsSubcommandError,
+  usageLine,
+  writeDryRun
+} from "./cli-wzds257x.js";
 import {
   ApiError,
   callControlAPI,
   callDataAPI
-} from "./cli-9btx12wp.js";
+} from "./cli-pg5qfmqc.js";
 import {
   AGENT_ERROR_CODES,
-  BATCH_CONCURRENCY,
-  BATCH_MAX_TARGETS,
   CliAccessError,
   CliAuthError,
   CliCancellationError,
@@ -73,19 +94,11 @@ import {
   agentMaxOutputBytes,
   apiErrorStatus,
   apiKeyHeaders,
-  asNumber,
-  asRecord,
-  asString,
   attachInputDetails,
   canonicalCommandText,
-  collectBatchTargets,
-  compactProblemDossier,
-  contextTarget,
   createCliOutput,
   embeddedTenantIdFromApiKey,
-  embeddedWindowSize,
   errorToAgentError,
-  frustrationsFromEmotions,
   getApiRequestCount,
   getModaDir,
   inputDetailsOf,
@@ -93,24 +106,20 @@ import {
   isNetworkLikeError,
   isPlatformApiKey,
   loadProfileConfig,
-  mapWithConcurrency,
-  parseBatchTarget,
   resetApiRequestCount,
   resolveApiKey,
   resolveApiTenantId,
   resolveModaBaseUrl,
+  resolveModaBaseUrlStrict,
   resolveOutputMode,
   safeWriteStderr,
   safeWriteStdout,
   setAgentUpdateNotice,
   setPlatformTenantOverride,
-  trimToolFailureConversations,
+  shellArg,
   validateConfig,
-  wasOutputCancelled,
-  withFrustrationAnchors,
-  withToolFailureAnchors,
-  withoutDetectionWindows
-} from "./cli-dve50x7p.js";
+  wasOutputCancelled
+} from "./cli-r5pp7qny.js";
 import {
   __require
 } from "./cli-0v6na3yp.js";
@@ -299,16 +308,91 @@ async function runReplaysCommand(context) {
 }
 
 // src/telemetry.ts
+import { spawn as spawn2 } from "node:child_process";
+
+// src/detached.ts
 import { spawn } from "node:child_process";
+var INSPECTOR_VALUE_OPTIONS = new Set(["--inspect-port", "--debug-port", "--inspect-publish-uid"]);
+function nodeOptionTokens(nodeOptions) {
+  const tokens = [];
+  let start = -1;
+  let quoted = false;
+  for (let i = 0;i < nodeOptions.length; i += 1) {
+    const ch = nodeOptions[i];
+    if (start === -1) {
+      if (/\s/.test(ch))
+        continue;
+      start = i;
+    }
+    if (quoted && ch === "\\") {
+      i += 1;
+    } else if (ch === '"') {
+      quoted = !quoted;
+    } else if (!quoted && /\s/.test(ch)) {
+      tokens.push(nodeOptions.slice(start, i));
+      start = -1;
+    }
+  }
+  if (start !== -1)
+    tokens.push(nodeOptions.slice(start));
+  return tokens;
+}
+function withoutInspectorOptions(nodeOptions) {
+  const tokens = nodeOptionTokens(nodeOptions);
+  const kept = [];
+  for (let i = 0;i < tokens.length; i += 1) {
+    const name = tokens[i].split("=")[0];
+    if (!name.startsWith("--inspect") && name !== "--debug-port") {
+      kept.push(tokens[i]);
+      continue;
+    }
+    if (INSPECTOR_VALUE_OPTIONS.has(tokens[i]) && tokens[i + 1] && !tokens[i + 1].startsWith("-"))
+      i += 1;
+  }
+  return kept.join(" ");
+}
+function spawnDetachedNode(script, options = {}, spawnImpl = spawn) {
+  try {
+    const env = { ...process.env, ...options.env };
+    for (const key of options.dropEnv ?? [])
+      delete env[key];
+    if (env.NODE_OPTIONS?.includes("--inspect")) {
+      const kept = withoutInspectorOptions(env.NODE_OPTIONS);
+      if (kept)
+        env.NODE_OPTIONS = kept;
+      else
+        delete env.NODE_OPTIONS;
+    }
+    const child = spawnImpl(process.execPath, ["-e", script], {
+      detached: true,
+      stdio: [options.stdin === undefined ? "ignore" : "pipe", "ignore", "ignore"],
+      windowsHide: true,
+      env
+    });
+    child.on("error", () => {});
+    if (child.pid === undefined)
+      return false;
+    if (options.stdin !== undefined && child.stdin) {
+      child.stdin.on("error", () => {});
+      child.stdin.end(options.stdin);
+    }
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/telemetry.ts
 import { randomUUID } from "node:crypto";
 var INLINE_TELEMETRY_TIMEOUT_MS = 500;
 var DETACHED_TELEMETRY_TIMEOUT_MS = 5000;
 var INVOCATION_ID = randomUUID();
 var TELEMETRY_FLAG = "no-telemetry";
-var TELEMETRY_REQUEST_ENV = "MODA_CLI_TELEMETRY_REQUEST";
 var TELEMETRY_TRANSPORT_ENV = "MODA_CLI_TELEMETRY_TRANSPORT";
 var MAX_TELEMETRY_DURATION_MS = 86400000;
 var MAX_TELEMETRY_API_REQUEST_COUNT = 1e6;
+var MAX_UNKNOWN_FLAG_COUNT = 1000;
 var SEARCH_SURFACE_BY_COMMAND = {
   search: "message",
   conversations: "conversation",
@@ -410,11 +494,10 @@ function serializeAdoption(adoption) {
   return out;
 }
 function stripTelemetryFlag(flags) {
-  const { [TELEMETRY_FLAG]: _drop, ...rest } = flags;
-  return rest;
+  return withoutFlag(flags, TELEMETRY_FLAG);
 }
-function isTelemetryDisabled(flags) {
-  return flags[TELEMETRY_FLAG] === "true" || process.env.MODA_CLI_TELEMETRY === "0" || process.env.DO_NOT_TRACK === "1";
+function isTelemetryDisabled(flags, env = process.env) {
+  return optOutFlagSet(flags, TELEMETRY_FLAG) || envSwitchedOff(env.MODA_CLI_TELEMETRY) || envOptOutSet(env.DO_NOT_TRACK);
 }
 var VALIDATION_REASON_MAX = 128;
 var DEGRADE_REASON_MAX = 64;
@@ -425,88 +508,78 @@ function sanitizeReasonCode(reason, max) {
 function sanitizeValidationReason(reason) {
   return sanitizeReasonCode(reason, VALIDATION_REASON_MAX);
 }
-function sanitizedFlagNames(flags) {
-  return Object.keys(stripTelemetryFlag(flags)).sort();
+var MAX_FLAG_NAMES = 50;
+var FLAG_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+var SECRET_PATTERNS = [
+  /moda_sk_/i,
+  /(?:^|[^A-Za-z0-9])sk-[A-Za-z0-9_-]{8,}/,
+  /(?:^|[^A-Za-z0-9])(?:sk|pk|rk)_(?:live|test)_/i,
+  /gh[pousr]_[A-Za-z0-9]{16,}/,
+  /github_pat_/i,
+  /xox[abprs]-/i,
+  /AKIA[0-9A-Z]{16}/,
+  /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY/,
+  /[^\s@]+@[^\s@]+\.[A-Za-z]{2,}/,
+  /[A-Za-z0-9+/=]{32,}/
+];
+function looksSecret(value) {
+  return SECRET_PATTERNS.some((pattern) => pattern.test(value));
+}
+function reportedFlagNames(flags, acceptedFlags = new Set) {
+  const names = new Set;
+  let unknownCount = 0;
+  for (const key of Object.keys(stripTelemetryFlag(flags))) {
+    if (acceptedFlags.has(key.replace(/_/g, "-")) && FLAG_NAME_RE.test(key) && !looksSecret(key))
+      names.add(key);
+    else
+      unknownCount += 1;
+  }
+  const sorted = [...names].sort();
+  return { names: sorted.slice(0, MAX_FLAG_NAMES), unknownCount: unknownCount + Math.max(0, sorted.length - MAX_FLAG_NAMES) };
+}
+function reportedValidationReason(reason, knownFlags = new Set) {
+  let code = reason;
+  const unknownFlag = code ? /^unknown_flag:(.*)$/s.exec(code) : null;
+  if (unknownFlag) {
+    const name = unknownFlag[1].replace(/_/g, "-");
+    code = knownFlags.has(name) && FLAG_NAME_RE.test(name) ? `unknown_flag:${name}` : "unknown_flag";
+  }
+  const cleaned = sanitizeValidationReason(code);
+  if (!cleaned || !looksSecret(cleaned))
+    return cleaned;
+  const head = cleaned.split(":")[0];
+  return head && !looksSecret(head) ? head : undefined;
+}
+function safeCode(value) {
+  return value && !looksSecret(value) ? value : undefined;
 }
 var TELEMETRY_SENDER_SCRIPT = [
   "try {",
-  `  const raw = process.env.${TELEMETRY_REQUEST_ENV};`,
-  `  delete process.env.${TELEMETRY_REQUEST_ENV};`,
-  "  const r = raw ? JSON.parse(raw) : null;",
-  "  if (r && typeof r.url === 'string' && typeof fetch === 'function') {",
-  "    const c = new AbortController();",
-  `    const t = setTimeout(() => c.abort(), ${DETACHED_TELEMETRY_TIMEOUT_MS});`,
-  "    fetch(r.url, { method: 'POST', headers: r.headers, body: r.body, signal: c.signal })",
-  "      .then((res) => (res.body && res.body.cancel ? res.body.cancel() : undefined))",
-  "      .catch(() => {})",
-  "      .finally(() => clearTimeout(t));",
-  "  }",
+  "  let raw = '';",
+  `  const quit = setTimeout(() => process.exit(0), ${DETACHED_TELEMETRY_TIMEOUT_MS + 1000});`,
+  "  const done = () => clearTimeout(quit);",
+  "  process.stdin.setEncoding('utf8');",
+  "  process.stdin.on('error', () => {});",
+  "  process.stdin.on('data', (chunk) => { raw += chunk; });",
+  "  process.stdin.on('end', () => {",
+  "    try {",
+  "      const r = raw ? JSON.parse(raw) : null;",
+  "      raw = '';",
+  "      if (!r || typeof r.url !== 'string' || typeof fetch !== 'function') return done();",
+  "      const c = new AbortController();",
+  `      const t = setTimeout(() => c.abort(), ${DETACHED_TELEMETRY_TIMEOUT_MS});`,
+  "      fetch(r.url, { method: 'POST', headers: r.headers, body: r.body, signal: c.signal })",
+  "        .then((res) => (res.body && res.body.cancel ? res.body.cancel() : undefined))",
+  "        .catch(() => {})",
+  "        .finally(() => { clearTimeout(t); done(); });",
+  "    } catch { done(); }",
+  "  });",
   "} catch {}"
 ].join(`
 `);
-var INSPECTOR_VALUE_OPTIONS = new Set(["--inspect-port", "--debug-port", "--inspect-publish-uid"]);
-function nodeOptionTokens(nodeOptions) {
-  const tokens = [];
-  let start = -1;
-  let quoted = false;
-  for (let i = 0;i < nodeOptions.length; i += 1) {
-    const ch = nodeOptions[i];
-    if (start === -1) {
-      if (/\s/.test(ch))
-        continue;
-      start = i;
-    }
-    if (quoted && ch === "\\") {
-      i += 1;
-    } else if (ch === '"') {
-      quoted = !quoted;
-    } else if (!quoted && /\s/.test(ch)) {
-      tokens.push(nodeOptions.slice(start, i));
-      start = -1;
-    }
-  }
-  if (start !== -1)
-    tokens.push(nodeOptions.slice(start));
-  return tokens;
-}
-function withoutInspectorOptions(nodeOptions) {
-  const tokens = nodeOptionTokens(nodeOptions);
-  const kept = [];
-  for (let i = 0;i < tokens.length; i += 1) {
-    const name = tokens[i].split("=")[0];
-    if (!name.startsWith("--inspect") && name !== "--debug-port") {
-      kept.push(tokens[i]);
-      continue;
-    }
-    if (INSPECTOR_VALUE_OPTIONS.has(tokens[i]) && tokens[i + 1] && !tokens[i + 1].startsWith("-"))
-      i += 1;
-  }
-  return kept.join(" ");
-}
-function spawnDetachedTelemetrySender(request, spawnImpl = spawn) {
-  try {
-    const env = { ...process.env, [TELEMETRY_REQUEST_ENV]: JSON.stringify(request) };
-    if (env.NODE_OPTIONS?.includes("--inspect")) {
-      const kept = withoutInspectorOptions(env.NODE_OPTIONS);
-      if (kept)
-        env.NODE_OPTIONS = kept;
-      else
-        delete env.NODE_OPTIONS;
-    }
-    const child = spawnImpl(process.execPath, ["-e", TELEMETRY_SENDER_SCRIPT], {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: true,
-      env
-    });
-    child.on("error", () => {});
-    if (child.pid === undefined)
-      return false;
-    child.unref();
-    return true;
-  } catch {
-    return false;
-  }
+function spawnDetachedTelemetrySender(request, spawnImpl = spawn2) {
+  return spawnDetachedNode(TELEMETRY_SENDER_SCRIPT, { stdin: JSON.stringify(request), dropEnv: ["MODA_API_KEY"] }, spawnImpl);
 }
 async function sendInline(request) {
   const controller = new AbortController;
@@ -526,16 +599,25 @@ async function sendInline(request) {
   }
 }
 function buildCliUsageRequest(input) {
-  const validationReason = sanitizeValidationReason(input.validationReason);
+  const baseUrl = resolveModaBaseUrlStrict(input.profile ? { profile: input.profile } : {});
+  if (!baseUrl)
+    return;
+  const validationReason = reportedValidationReason(input.validationReason, input.knownFlags);
+  const flagNames = reportedFlagNames(input.flags, input.acceptedFlags);
+  const adoption = serializeAdoption(input.adoption);
+  for (const key of ["subcommand", "degrade_reason", "skill_version"]) {
+    if (typeof adoption[key] === "string" && looksSecret(adoption[key]))
+      delete adoption[key];
+  }
   return {
-    url: `${resolveModaBaseUrl({ profile: input.profile })}/api/v1/data/cli-usage`,
+    url: `${baseUrl}/api/v1/data/cli-usage`,
     headers: {
       ...apiKeyHeaders(input.apiKey),
       "Content-Type": "application/json"
     },
     body: JSON.stringify({
       invocation_id: INVOCATION_ID,
-      command: input.command.slice(0, 64),
+      command: safeCode(input.command.slice(0, 64)) ?? "unknown",
       status: input.status,
       error_type: input.errorType,
       ...validationReason ? { validation_reason: validationReason } : {},
@@ -547,10 +629,11 @@ function buildCliUsageRequest(input) {
       platform: process.platform,
       arch: process.arch,
       flags_json: {
-        names: sanitizedFlagNames(input.flags),
-        ...((alias) => alias ? { legacy_alias: alias } : {})(sanitizeReasonCode(input.legacyAlias?.replace(/ /g, ":"), 64))
+        names: flagNames.names,
+        ...flagNames.unknownCount > 0 ? { unknown_count: Math.min(flagNames.unknownCount, MAX_UNKNOWN_FLAG_COUNT) } : {},
+        ...((alias) => alias ? { legacy_alias: alias } : {})(safeCode(sanitizeReasonCode(input.legacyAlias?.replace(/ /g, ":"), 64)))
       },
-      ...serializeAdoption(input.adoption)
+      ...adoption
     })
   };
 }
@@ -560,6 +643,8 @@ async function sendCliUsageTelemetry(input) {
       return;
     }
     const request = buildCliUsageRequest({ ...input, apiKey: input.apiKey });
+    if (!request)
+      return;
     if (process.env[TELEMETRY_TRANSPORT_ENV] !== "inline" && spawnDetachedTelemetrySender(request)) {
       return;
     }
@@ -576,11 +661,10 @@ var REGISTRY_TIMEOUT_MS = 1500;
 var REGISTRY_LATEST_URL = "https://registry.npmjs.org/@moda-ai/cli/latest";
 var SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 function stripUpdateCheckFlag(flags) {
-  const { [UPDATE_CHECK_FLAG]: _drop, ...rest } = flags;
-  return rest;
+  return withoutFlag(flags, UPDATE_CHECK_FLAG);
 }
 function isUpdateCheckDisabled(flags, env = process.env) {
-  return flags[UPDATE_CHECK_FLAG] === "true" || env.MODA_CLI_UPDATE_CHECK === "0" || env.DO_NOT_TRACK === "1" || env.CI !== undefined && env.CI !== "" && env.CI !== "false" && env.CI !== "0";
+  return optOutFlagSet(flags, UPDATE_CHECK_FLAG) || envSwitchedOff(env.MODA_CLI_UPDATE_CHECK) || envOptOutSet(env.DO_NOT_TRACK) || envOptOutSet(env.CI);
 }
 function cachePath(options = {}) {
   return join(getModaDir(options), "update-check.json");
@@ -613,9 +697,39 @@ function isNewerVersion(candidate, current) {
   }
   return false;
 }
-async function startUpdateCheck(options = {}, now = Date.now()) {
+var UPDATE_CHECK_URL_ENV = "MODA_CLI_UPDATE_CHECK_URL";
+var UPDATE_CHECK_CACHE_ENV = "MODA_CLI_UPDATE_CHECK_CACHE";
+var DETACHED_REGISTRY_TIMEOUT_MS = 1e4;
+var UPDATE_CHECK_SCRIPT = [
+  "try {",
+  `  const url = process.env.${UPDATE_CHECK_URL_ENV};`,
+  `  const path = process.env.${UPDATE_CHECK_CACHE_ENV};`,
+  `  const semver = new RegExp(${JSON.stringify(SEMVER_RE.source)});`,
+  "  if (url && path && typeof fetch === 'function') {",
+  "    const c = new AbortController();",
+  `    const t = setTimeout(() => c.abort(), ${DETACHED_REGISTRY_TIMEOUT_MS});`,
+  "    fetch(url, { headers: { Accept: 'application/json' }, signal: c.signal })",
+  "      .then((res) => (res.ok ? res.json() : null))",
+  "      .then((body) => {",
+  "        if (body && typeof body.version === 'string' && semver.test(body.version)) {",
+  "          require('fs').writeFileSync(path, JSON.stringify({ checked_at: Date.now(), latest: body.version }, null, 2) + '\\n', 'utf8');",
+  "        }",
+  "      })",
+  "      .catch(() => {})",
+  "      .finally(() => clearTimeout(t));",
+  "  }",
+  "} catch {}"
+].join(`
+`);
+async function startUpdateCheck(options = {}, now = Date.now(), mode = {}) {
   const cache = readCache(options);
-  if (cache && now - cache.checked_at < CHECK_INTERVAL_MS) {
+  if (cache && cache.checked_at <= now && now - cache.checked_at < CHECK_INTERVAL_MS) {
+    return;
+  }
+  const known = cache && SEMVER_RE.test(cache.latest) ? cache.latest : "";
+  writeCache({ checked_at: now, latest: known }, options);
+  if (mode.detached) {
+    spawnDetachedNode(UPDATE_CHECK_SCRIPT, { env: { [UPDATE_CHECK_URL_ENV]: REGISTRY_LATEST_URL, [UPDATE_CHECK_CACHE_ENV]: cachePath(options) }, dropEnv: ["MODA_API_KEY"] }, mode.spawnImpl);
     return;
   }
   const controller = new AbortController;
@@ -640,16 +754,16 @@ async function startUpdateCheck(options = {}, now = Date.now()) {
 }
 function getAvailableUpdate(options = {}) {
   const cache = readCache(options);
-  return cache && isNewerVersion(cache.latest, VERSION) ? cache.latest : undefined;
+  return cache && SEMVER_RE.test(cache.latest) && isNewerVersion(cache.latest, VERSION) ? cache.latest : undefined;
 }
 function getUpdateNotice(options = {}) {
-  const cache = readCache(options);
-  if (!cache || !isNewerVersion(cache.latest, VERSION)) {
+  const latest = getAvailableUpdate(options);
+  if (!latest) {
     return;
   }
   return [
     "",
-    `Update available: moda-cli ${VERSION} → ${cache.latest}`,
+    `Update available: moda-cli ${VERSION} → ${latest}`,
     "Run `npm install -g @moda-ai/cli@latest` to update."
   ].join(`
 `);
@@ -2249,6 +2363,7 @@ function buildManifest(commands) {
       "--agent",
       "--stream",
       "--json",
+      "--pretty",
       "--human",
       "--profile <name>",
       "--quiet",
@@ -2275,7 +2390,7 @@ function buildManifest(commands) {
     exit_codes: [
       { code: 0, name: "ok", meaning: "Command completed successfully." },
       { code: 1, name: "error", meaning: "Command, input, API, network, or unexpected failure." },
-      { code: 3, name: "degraded", meaning: "Degraded result: `moda ask` local fallback." },
+      { code: 3, name: "degraded", meaning: "Degraded result: `moda ask` local fallback, or `investigate`/`failures` with some sources unavailable (`data.failedSources`)." },
       { code: 4, name: "auth_required", meaning: "Run login_command, then resume." },
       { code: 5, name: "input_required", meaning: "Choose from input_request choices, then resume." },
       { code: 130, name: "cancelled", meaning: "Interrupted or output consumer closed." }
@@ -2390,6 +2505,8 @@ function event(name, when, terminal, deprecated = false) {
 function exitCodesForCommand(command) {
   if (command === "ask")
     return [0, 1, 3, 4, 5, 130];
+  if (command === "investigate" || command === "failures")
+    return [0, 1, 3, 4, 130];
   if (command === "init" || command === "harness")
     return [0, 1, 4, 5, 130];
   return [0, 1, 4, 130];
@@ -2522,46 +2639,46 @@ function leafManifestFields(leaf, commands) {
 import { fileURLToPath } from "url";
 import { realpathSync } from "fs";
 async function runPromptsCommand(...args) {
-  return (await import("./prompts-3h5jcjrw.js")).runPromptsCommand(...args);
+  return (await import("./prompts-17wyrst6.js")).runPromptsCommand(...args);
 }
 async function runSkillsCommand(...args) {
-  return (await import("./skills-vq3njc8a.js")).runSkillsCommand(...args);
+  return (await import("./skills-ccdbqghj.js")).runSkillsCommand(...args);
 }
 async function runFixCommand(...args) {
-  return (await import("./fix-0qdtdz5h.js")).runFixCommand(...args);
+  return (await import("./fix-75s9s0d6.js")).runFixCommand(...args);
 }
 async function runFixesCommand(...args) {
-  return (await import("./fix-0qdtdz5h.js")).runFixesCommand(...args);
+  return (await import("./fix-75s9s0d6.js")).runFixesCommand(...args);
 }
 async function runHarnessCommand(...args) {
-  return (await import("./harness-vzy7n7ea.js")).runHarnessCommand(...args);
+  return (await import("./harness-a7tb9a23.js")).runHarnessCommand(...args);
 }
 async function runSyncCommand(...args) {
-  return (await import("./sync-hq9dpqpr.js")).runSyncCommand(...args);
+  return (await import("./sync-hkxce5zh.js")).runSyncCommand(...args);
 }
 async function runRegistryCommand(...args) {
-  return (await import("./registry-s2vdsfw8.js")).runRegistryCommand(...args);
+  return (await import("./registry-fpzhjznj.js")).runRegistryCommand(...args);
 }
 async function runDoctorCommand(...args) {
-  return (await import("./doctor-q21mr5ya.js")).runDoctorCommand(...args);
+  return (await import("./doctor-wmre3mr7.js")).runDoctorCommand(...args);
 }
 async function runStatusCommand(...args) {
-  return (await import("./doctor-q21mr5ya.js")).runStatusCommand(...args);
+  return (await import("./doctor-wmre3mr7.js")).runStatusCommand(...args);
 }
 async function runAuthCommand(...args) {
-  return (await import("./profile-commands-6e2dgv72.js")).runAuthCommand(...args);
+  return (await import("./profile-commands-49yn02yg.js")).runAuthCommand(...args);
 }
 async function runConfigCommand(...args) {
-  return (await import("./profile-commands-6e2dgv72.js")).runConfigCommand(...args);
+  return (await import("./profile-commands-49yn02yg.js")).runConfigCommand(...args);
 }
 async function runProfilesCommand(...args) {
-  return (await import("./profile-commands-6e2dgv72.js")).runProfilesCommand(...args);
+  return (await import("./profile-commands-49yn02yg.js")).runProfilesCommand(...args);
 }
 async function runAgentCommand(...args) {
-  return (await import("./agent-t7dxmpdq.js")).runAgentCommand(...args);
+  return (await import("./agent-vp9prdma.js")).runAgentCommand(...args);
 }
 async function runProductionCommand(...args) {
-  return (await import("./production-intelligence-c8e0xw3n.js")).runProductionCommand(...args);
+  return (await import("./production-intelligence-7nqddd4f.js")).runProductionCommand(...args);
 }
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -2575,10 +2692,10 @@ function parseArgs(argv) {
   let endOfOptions = false;
   while (i < args.length) {
     const arg = args[i];
-    if (!endOfOptions && arg === "--" && command !== "") {
+    if (!endOfOptions && arg === "--" && command === "") {} else if (!endOfOptions && arg === "--") {
       endOfOptions = true;
     } else if (!endOfOptions && arg.startsWith("--")) {
-      i = parseFlag(args, i, flags, command === "", bareFlags, parseCommandFor(command, positional));
+      i = parseFlag(args, i, flags, command === "", bareFlags, command, positional);
     } else if (!endOfOptions && command !== "" && /^-[A-Za-z]/.test(arg)) {
       shortFlags.push(arg);
     } else if (command === "") {
@@ -2655,7 +2772,8 @@ var RAW_BOOLEAN_FLAGS = new Set([
   "tui",
   "no-tui",
   "no-telemetry",
-  "no-update-check"
+  "no-update-check",
+  "pretty"
 ]);
 var GLOBAL_BOOLEAN_FLAGS = new Set([
   "agent",
@@ -2671,7 +2789,8 @@ var GLOBAL_BOOLEAN_FLAGS = new Set([
   "dry-run",
   "stream",
   "tui",
-  "no-tui"
+  "no-tui",
+  "pretty"
 ]);
 var BOOLEAN_WORDS = new Set(["true", "false", "yes", "no", "on", "off"]);
 var META_SWITCHES = new Set([
@@ -2685,14 +2804,64 @@ var META_SWITCHES = new Set([
   "tui",
   "no-tui",
   "no-telemetry",
-  "no-update-check"
+  "no-update-check",
+  "pretty"
 ]);
 var AGENT_VALUE_COMMANDS = new Set(["harness", "sync"]);
-var COMMAND_BOOLEAN_FLAGS = {
-  context: new Set(["all", "metadata-only"])
-};
-function parseFlag(args, index, flags, beforeCommand, bareFlags, command = "") {
-  const set = (key2, value, bare) => {
+function canonicalFlagKey(key) {
+  return key.replace(/_/g, "-");
+}
+function canonicalizeFlagKeys(flags, bareFlags) {
+  const entries = Object.entries(flags);
+  for (const [key] of entries)
+    delete flags[key];
+  for (const [key, value] of entries)
+    flags[canonicalFlagKey(key)] = value;
+  if (bareFlags) {
+    const canonical = [...new Set(bareFlags.map(canonicalFlagKey))];
+    bareFlags.splice(0, bareFlags.length, ...canonical);
+  }
+}
+function parseHandlersFor(command, verb) {
+  if (command === "review")
+    return leafHandlers(leafFor("review", undefined));
+  if (CANONICAL_NOUNS.includes(command) && verb !== undefined) {
+    const leaf = leafFor(command, verb);
+    if (leaf)
+      return leaf.path === "problems unexplained" ? ["problems"] : leafHandlers(leaf);
+  }
+  return [commandRegistry.find(command)?.name ?? command];
+}
+function specsOf(name) {
+  const spec = flagSpecFor(name);
+  return spec ? [spec, ...Object.values(spec.subcommands ?? {})] : [];
+}
+var switchFlagCache = new Map;
+function commandSwitchFlags(command, verb) {
+  const handlers = parseHandlersFor(command, verb);
+  const cacheKey = handlers.join(",");
+  const cached = switchFlagCache.get(cacheKey);
+  if (cached)
+    return cached;
+  const booleans = new Set;
+  const valued = new Set;
+  for (const handler of handlers) {
+    for (const spec of specsOf(handler)) {
+      for (const flag of describeSpecFlags(spec)) {
+        (flag.type === "boolean" ? booleans : valued).add(flag.name.slice(2));
+      }
+    }
+  }
+  const switches = new Set([...booleans].filter((name) => !valued.has(name)));
+  switchFlagCache.set(cacheKey, switches);
+  return switches;
+}
+function takesIdPositional(command, verb) {
+  return parseHandlersFor(command, verb).some((handler) => specsOf(handler).some((spec) => (spec.positionals ?? []).some((positional) => !positional.variadic)));
+}
+function parseFlag(args, index, flags, beforeCommand, bareFlags, command = "", verb) {
+  const set = (rawKey, value, bare) => {
+    const key2 = canonicalFlagKey(rawKey);
     flags[key2] = value;
     const at = bareFlags.indexOf(key2);
     if (at !== -1)
@@ -2708,17 +2877,19 @@ function parseFlag(args, index, flags, beforeCommand, bareFlags, command = "") {
   }
   const key = arg.slice(2);
   const next = args[index + 1];
-  if (beforeCommand && GLOBAL_BOOLEAN_FLAGS.has(key)) {
+  if (beforeCommand && GLOBAL_BOOLEAN_FLAGS.has(canonicalFlagKey(key))) {
     set(key, "true", true);
     return index;
   }
-  const switchName = key.replace(/_/g, "-");
-  if (META_SWITCHES.has(switchName) || switchName === "agent" && !AGENT_VALUE_COMMANDS.has(command)) {
+  const switchName = canonicalFlagKey(key);
+  const parseCommand = parseCommandFor(command, verb);
+  if (META_SWITCHES.has(switchName) || switchName === "agent" && !AGENT_VALUE_COMMANDS.has(parseCommand)) {
     set(key, "true", true);
     return index;
   }
-  const idFollows = COMMAND_BOOLEAN_FLAGS[command]?.has(switchName) === true;
-  const isSwitch = RAW_BOOLEAN_FLAGS.has(switchName) || idFollows;
+  const schemaSwitch = !beforeCommand && commandSwitchFlags(command, verb).has(switchName);
+  const isSwitch = RAW_BOOLEAN_FLAGS.has(switchName) || schemaSwitch;
+  const idFollows = schemaSwitch && takesIdPositional(command, verb);
   const takesNext = BOOLEAN_WORDS.has(next?.toLowerCase() ?? "") || !idFollows && (next === "0" || next === "1");
   if (!beforeCommand && isSwitch && !takesNext) {
     set(key, "true", true);
@@ -2750,9 +2921,32 @@ function flagsToArgs(flags, positionalKey, positionalValue) {
     result[positionalKey] = positionalValue;
   }
   for (const [key, value] of Object.entries(flags)) {
-    const snakeKey = key.replace(/-/g, "_");
-    const num = Number(value);
-    result[snakeKey] = isNaN(num) || value === "true" ? value : num;
+    result[key.replace(/-/g, "_")] = value;
+  }
+  return result;
+}
+var DECIMAL_TEXT = /^[+-]?(?:\d+\.?\d*|\.\d+)$/;
+function coerceNumericFlags(schema, args, command) {
+  const shape = schemaShape(schema);
+  const result = { ...args };
+  for (const [key, value] of Object.entries(args)) {
+    if (typeof value !== "string" || !Object.hasOwn(shape, key))
+      continue;
+    const info = describeField(shape[key]);
+    if (info.type !== "integer" && info.type !== "number")
+      continue;
+    const text = value.trim();
+    if (!DECIMAL_TEXT.test(text)) {
+      const flag = kebabFlag(key);
+      const kind = info.type === "integer" ? "a whole number" : "a number";
+      const range = info.min !== undefined && info.max !== undefined ? ` from ${info.min} to ${info.max}` : "";
+      throw new CliInputError(`${flag} must be ${kind}${range} (got '${value}'), so nothing was sent.`, `Pass digits only, e.g. ${flag}=${info.min ?? 1}. See '${canonicalCommandText(`moda ${command}`)} --help'.`, `bad_number:${flag.slice(2)}`, {
+        field: flag,
+        ...info.min !== undefined || info.max !== undefined ? { range: { ...info.min !== undefined ? { min: info.min } : {}, ...info.max !== undefined ? { max: info.max } : {} } } : {},
+        suggestedCommands: [`${canonicalCommandText(`moda ${command}`)} --help`]
+      });
+    }
+    result[key] = Number(text);
   }
   return result;
 }
@@ -2820,6 +3014,7 @@ Silent aliases: conversations = traces list, cluster-conversations = cluster-tra
 
 Output: piped stdout, CI or an agent env (CLAUDECODE/CURSOR/MODA_AGENT) => agent JSON; a terminal => prose.
   --json | --agent [--stream] | --human  Force an output mode (or MODA_FORMAT=human|json|agent|agent-stream)
+  --json is compact when piped; --pretty indents it (indented by default on a terminal)
   --profile=NAME --quiet --no-update-check --version --json-schemas
 Exit codes: 0 ok, 1 error (errors[0].code says which), 3 degraded, 4 auth required, 5 input required, 130 cancelled.
 A command rejects any flag it does not take; the error lists errors[0].allowed and errors[0].did_you_mean.`);
@@ -3082,8 +3277,27 @@ function legacyNamesHelpLine() {
   return lines.join(`
 `);
 }
-async function attachWindows(rows, windowSize) {
-  return Promise.all(rows.map(async (row) => {
+var ENRICH_CONCURRENCY = BATCH_CONCURRENCY;
+function enrichedRowBytes(row) {
+  const window = asRecord(row.window);
+  if (window && !("error" in window)) {
+    const { conversation: _conversation, ...rest } = row;
+    return jsonByteLength(rest);
+  }
+  return jsonByteLength(row);
+}
+async function enrichWithinBudget(rows, enrich, budgetBytes, skipKey) {
+  let spent = 0;
+  const enriched = await mapWithConcurrency(rows, ENRICH_CONCURRENCY, async (row) => {
+    const out = await enrich(row);
+    if (budgetBytes !== undefined)
+      spent += enrichedRowBytes(out);
+    return out;
+  }, budgetBytes === undefined ? {} : { shouldStart: () => spent <= budgetBytes });
+  return [...enriched, ...rows.slice(enriched.length).map((row) => ({ ...row, [skipKey]: "agent_output_budget" }))];
+}
+async function attachWindows(rows, windowSize, budgetBytes) {
+  return enrichWithinBudget(rows, async (row) => {
     const anchor = asRecord(row.anchor);
     if (!anchor || anchor.no_anchor === true) {
       return { ...row, window: null };
@@ -3112,7 +3326,7 @@ async function attachWindows(rows, windowSize) {
       const message = err instanceof Error ? err.message : String(err);
       return { ...row, window: { error: message } };
     }
-  }));
+  }, budgetBytes, "window_skipped");
 }
 var TOOL_FAILURE_DETAIL_DEFAULT_LIMIT = 5;
 var TOOL_FAILURE_AGENT_SUBTYPES = 20;
@@ -3121,7 +3335,8 @@ async function printWithOptionalWindows(enriched, listKey, includeWindow, window
   let data = enriched;
   if (includeWindow) {
     const list = Array.isArray(enriched[listKey]) ? enriched[listKey] : [];
-    data = { ...enriched, [listKey]: await attachWindows(list, windowSize) };
+    const agentMode = output.mode === "agent" || output.mode === "agent-stream";
+    data = { ...enriched, [listKey]: await attachWindows(list, windowSize, agentMode ? agentMaxOutputBytes() : undefined) };
   }
   if (finalize)
     data = finalize(data, allWarnings);
@@ -3179,8 +3394,10 @@ function auditCapStatus(data, limit) {
   const nextCursor = typeof cursorValue === "string" && cursorValue ? cursorValue : null;
   return { rowsCapped, spansCapped, hasMoreKnown: hasMore, rows, spans, reason, nextCursor };
 }
-var AUDIT_MIN_PAGE_BYTES = 32768;
 var AUDIT_AGENT_RESERVE_BYTES = 16384;
+function auditMaxBytes(budgetBytes) {
+  return Math.max(1, budgetBytes - Math.min(AUDIT_AGENT_RESERVE_BYTES, Math.floor(budgetBytes / 4)));
+}
 async function fetchAudit(id, query2, maxBytes) {
   const pageQuery = new URLSearchParams(query2);
   if (maxBytes !== undefined)
@@ -3188,16 +3405,22 @@ async function fetchAudit(id, query2, maxBytes) {
   const queryString = pageQuery.toString() ? `?${pageQuery.toString()}` : "";
   return callDataAPI(`/audit/${encodeURIComponent(id)}${queryString}`);
 }
-function auditOutput(command, params, data) {
-  const capped = auditCapStatus(data, params.limit ?? AUDIT_DEFAULT_LIMIT);
+function auditOutput(command, params, data, keep) {
   const auditRecord = asRecord(data);
-  if (!capped || !auditRecord) {
-    return { data: auditRecord ? { ...auditRecord, truncated: false, has_more: false, next_cursor: null } : data, options: {} };
-  }
+  const pageSpans = Array.isArray(auditRecord?.spans) ? auditRecord.spans : [];
+  const offset = params.span_offset ?? 0;
+  const end = Math.max(offset, keep === undefined ? pageSpans.length : Math.min(pageSpans.length, offset + keep));
+  const sliced = offset > 0 || end < pageSpans.length;
+  const shown = Math.max(0, Math.min(end, pageSpans.length) - offset);
+  const partial = end < pageSpans.length;
+  const record = auditRecord && sliced ? {
+    ...auditRecord,
+    spans: pageSpans.slice(offset, end),
+    span_offset: offset,
+    page_spans: pageSpans.length,
+    ...partial ? { next_span_offset: end } : {}
+  } : auditRecord;
   const limit = params.limit ?? AUDIT_DEFAULT_LIMIT;
-  const perTrace = "audit one OTLP trace at a time with `moda traces spans <trace_id> --kind=trace` (ids in summary.trace_ids)";
-  const warnings = [];
-  const nextCommands = [];
   const auditFlags = (extra) => [
     `${canonicalCommandText(`moda ${command}`)} ${shellArg(params.id)}`,
     params.kind && params.kind !== "auto" ? `--kind=${params.kind}` : "",
@@ -3205,29 +3428,75 @@ function auditOutput(command, params, data) {
     params.include_bodies === true ? "--include-bodies" : "",
     ...extra
   ].filter(Boolean).join(" ");
+  const sliceWarnings = [];
+  if (offset > 0 && offset >= pageSpans.length) {
+    sliceWarnings.push(`--span-offset=${offset} is past the ${pageSpans.length} span(s) of this page, so no spans are shown.`);
+  } else if (sliced && !partial) {
+    sliceWarnings.push(`Showing spans ${offset}-${end - 1}, the last part of the ${pageSpans.length} span(s) in this page.`);
+  }
+  if (partial && record) {
+    const continueWith = auditFlags([
+      params.limit ? `--limit=${params.limit}` : "",
+      params.cursor ? `--cursor=${shellArg(params.cursor)}` : "",
+      params.page_bytes ? `--page-bytes=${params.page_bytes}` : "",
+      `--span-offset=${end}`
+    ]);
+    const summary = asRecord(record.summary);
+    return {
+      data: {
+        ...record,
+        truncated: true,
+        has_more: true,
+        next_cursor: null,
+        ...summary ? { summary: { ...summary, has_more: true, next_cursor: null } } : {}
+      },
+      options: {
+        warnings: [
+          `Showing spans ${offset}-${end - 1} of the ${pageSpans.length} in this page to stay under the agent output byte limit (--json has no limit). Read the next ${pageSpans.length - end} with: ${continueWith}. next_cursor is withheld until the last spans of this page are read. Orphan/duplicate analysis covers the whole page.`
+        ],
+        nextCommands: [{
+          command: continueWith,
+          purpose: `Read spans ${end}-${pageSpans.length - 1} of this page (left out to fit the agent byte limit).`,
+          mutability: "read",
+          requires_approval: false
+        }]
+      }
+    };
+  }
+  const capped = auditCapStatus(data, limit);
+  if (!capped || !record) {
+    return {
+      data: record ? { ...record, truncated: false, has_more: false, next_cursor: null } : data,
+      options: sliceWarnings.length > 0 ? { warnings: sliceWarnings } : {}
+    };
+  }
+  const perTrace = "audit one OTLP trace at a time with `moda traces spans <trace_id> --kind=trace` (ids in summary.trace_ids)";
+  const shownText = sliced ? `${shown} shown here (${pageSpans.length} in this page)` : `${capped.spans} shown`;
+  const warnings = [...sliceWarnings];
+  const nextCommands = [];
   if (capped.nextCursor) {
     nextCommands.push({
-      command: auditFlags([params.limit ? `--limit=${params.limit}` : "", `--cursor=${capped.nextCursor}`]),
+      command: auditFlags([params.limit ? `--limit=${params.limit}` : "", `--cursor=${shellArg(capped.nextCursor)}`]),
       purpose: "Read the next page of ingest rows of this trace.",
       mutability: "read",
       requires_approval: false
     });
   }
   if (capped.reason === "byte_limit") {
-    warnings.push(`Spans were capped: the response reached the server's size budget after ${capped.rows} ingest row(s), so this trace has more spans than the ${capped.spans} shown. Continue with the next_cursor page${params.include_bodies === true ? ", or drop --include-bodies to fit more rows per page" : ""}. Orphan/duplicate analysis covers this page only.`);
+    warnings.push(`Spans were capped: the response reached the server's size budget after ${capped.rows} ingest row(s), so this trace has more spans than the ${shownText}. Continue with the next_cursor page${params.include_bodies === true ? ", or drop --include-bodies to fit more rows per page" : ""}. Orphan/duplicate analysis covers this page only.`);
   } else if (capped.reason === "span_limit" && capped.nextCursor) {
-    warnings.push(`Spans were capped: the page reached the server's per-page span cap after ${capped.rows} ingest row(s), so this trace has more spans than the ${capped.spans} shown. Continue with the next_cursor page. Orphan/duplicate analysis covers this page only.`);
+    warnings.push(`Spans were capped: the page reached the server's per-page span cap after ${capped.rows} ingest row(s), so this trace has more spans than the ${shownText}. Continue with the next_cursor page. Orphan/duplicate analysis covers this page only.`);
   } else if (capped.rowsCapped) {
     const bigger = Math.min(AUDIT_MAX_LIMIT, limit * 5);
-    warnings.push(`Spans were capped: read ${capped.rows} ingest row(s), the --limit=${limit} maximum, so this trace ${capped.hasMoreKnown ? "has" : "may have"} more spans than the ${capped.spans} shown. ` + (capped.nextCursor ? "Page on with the next_cursor command, or " : "") + (limit < AUDIT_MAX_LIMIT ? `${capped.nextCursor ? "rerun" : "Rerun"} with --limit=${bigger} (max ${AUDIT_MAX_LIMIT}), or ${perTrace}.` : capped.nextCursor ? `${perTrace}.` : `${perTrace[0].toUpperCase()}${perTrace.slice(1)}.`));
-    if (limit < AUDIT_MAX_LIMIT && !params.cursor) {
+    warnings.push(`Spans were capped: read ${capped.rows} ingest row(s), the --limit=${limit} maximum, so this trace ${capped.hasMoreKnown ? "has" : "may have"} more spans than the ${shownText}. ` + (capped.nextCursor ? "Page on with the next_cursor command, or " : "") + (limit < AUDIT_MAX_LIMIT ? `${capped.nextCursor ? "rerun" : "Rerun"} with --limit=${bigger} (max ${AUDIT_MAX_LIMIT}), or ${perTrace}.` : capped.nextCursor ? `${perTrace}.` : `${perTrace[0].toUpperCase()}${perTrace.slice(1)}.`));
+    if (limit < AUDIT_MAX_LIMIT && !params.cursor && !sliced) {
       nextCommands.push({ command: auditFlags([`--limit=${bigger}`]), purpose: "Read more ingest rows of this trace.", mutability: "read", requires_approval: false });
     }
   } else {
     warnings.push(`Spans were capped: the server returned ${capped.spans} span(s) and marked the response truncated. ${perTrace[0].toUpperCase()}${perTrace.slice(1)}.`);
   }
   return {
-    data: { ...auditRecord, truncated: true, has_more: capped.rowsCapped, next_cursor: capped.nextCursor },
+    data: { ...record, truncated: true, has_more: capped.rowsCapped, next_cursor: capped.nextCursor },
     options: { warnings, ...nextCommands.length > 0 ? { nextCommands } : {} }
   };
 }
@@ -3416,8 +3685,8 @@ async function runTailCommand(params, context) {
     await new Promise((resolve) => setTimeout(resolve, intervalMs));
   }
 }
-async function attachWorldState(rows) {
-  return Promise.all(rows.map(async (row) => {
+async function attachWorldState(rows, budgetBytes) {
+  return enrichWithinBudget(rows, async (row) => {
     const conv_id = asString(row.conversation_id) ?? "";
     if (!conv_id) {
       return { ...row, world_state: null };
@@ -3429,7 +3698,7 @@ async function attachWorldState(rows) {
       const message = err instanceof Error ? err.message : String(err);
       return { ...row, world_state: { error: message } };
     }
-  }));
+  }, budgetBytes, "world_state_skipped");
 }
 function recordSearchTelemetry(context, data) {
   const record = asRecord(data);
@@ -3539,7 +3808,7 @@ function parseCommandFlags(schema, args, command, options = {}) {
   ]);
   const unknown = Object.keys(args).filter((key) => !known.has(key));
   if (unknown.includes("dry_run")) {
-    throw new CliInputError(`'moda ${command}' has no dry-run mode, so nothing was sent.`, `Remove --dry-run to run it for real. Commands with a real dry-run: sync, registry push, harness sync/delete/register, prompts sync/decide, skills sync/policy, signals <write subcommands>, problem-reopen.`, "unsupported_dry_run");
+    throw new CliInputError(`'moda ${command}' has no dry-run mode (it does not write), so nothing was sent.`, `Remove --dry-run. Every write takes --dry-run: problems feedback|reopen|link, review, feedback, signals <write subcommands>, sync, registry push, harness sync/delete/register, prompts sync/decide, skills sync/policy.`, "unsupported_dry_run");
   }
   if (unknown.length > 0) {
     const flagKeys = [
@@ -3575,8 +3844,9 @@ function parseCommandFlags(schema, args, command, options = {}) {
       suggestedCommands: [helpCommand]
     });
   }
+  const typed = coerceNumericFlags(schema, args, command);
   try {
-    return schema.parse(args);
+    return schema.parse(typed);
   } catch (error) {
     if (error instanceof z.ZodError)
       attachFlagDetails(error, schema, command);
@@ -3608,20 +3878,6 @@ function specParseOptions(spec) {
     ...spec.flagAliases ? { flagAliases: spec.flagAliases } : {}
   };
 }
-function withStringIdFlags(args, flags) {
-  for (const flag of ["user-id", "conversation-id"]) {
-    if (flags[flag] !== undefined)
-      args[flag.replace(/-/g, "_")] = flags[flag];
-  }
-  return args;
-}
-function shellArg(value) {
-  if (/^[A-Za-z0-9_.,:@%+\/=-]+$/.test(value))
-    return value;
-  if (!/["$`\\!]/.test(value))
-    return `"${value}"`;
-  return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function semanticIndexCoverage(coverage) {
   const ratio = asRecord(asRecord(coverage)?.semantic_index)?.coverage_ratio;
   if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio < 0 || ratio > 1)
@@ -3722,8 +3978,7 @@ async function searchFallbackToTraces(params) {
     return;
   const pagination = asRecord(traces.pagination);
   const total = asNumber(pagination?.total) ?? rows.length;
-  const nextOffset = offset + rows.length;
-  const hasMore = pagination?.has_more === true || (asNumber(pagination?.total) ?? 0) > nextOffset;
+  const serverHasMore = pagination?.has_more === true;
   const traceMode = asString(traces.search_mode) ?? "keyword";
   const literal = traceMode === "keyword";
   if (params.mode === "keyword" && !literal) {
@@ -3745,33 +4000,46 @@ async function searchFallbackToTraces(params) {
   }));
   const first = asString(rows[0].conversation_id);
   const describe = literal ? "trace-level keyword matches (each trace contains the words)" : `trace-level ${traceMode}-ranked related traces (they may not contain the exact words; fallback.total is the candidate pool, not a match count)`;
-  const nextCommands = [];
-  if (first) {
-    nextCommands.push({ command: `moda traces spans ${first}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
-  }
-  if (hasMore) {
-    nextCommands.push({ command: `${tracesCommand} --offset=${nextOffset}`, purpose: "Page through further trace-level results.", mutability: "read", requires_approval: false });
-  }
-  return {
-    kind: "results",
-    hasMore,
-    data: {
-      results,
-      fallback: {
-        source: "traces_search",
-        reason: "message_index_empty",
-        grain: "trace",
-        search_mode: traceMode,
-        total,
-        total_kind: literal ? "matches" : "candidate_pool",
-        has_more: hasMore,
-        ...offset > 0 ? { offset } : {},
-        ...hasMore ? { next_offset: nextOffset } : {}
-      }
-    },
-    warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. Each result is a whole trace, not a message, with no score or message index. Open one with \`moda traces spans <conversation_id>\` or \`moda traces get <conversation_id>\` to find the matching turn.` + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
-    nextCommands
+  const page = (kept) => {
+    const omitted = rows.length - kept;
+    const nextOffset = offset + kept;
+    const hasMore = omitted > 0 || serverHasMore || total > nextOffset;
+    const nextCommands = [];
+    if (first) {
+      nextCommands.push({ command: `moda traces spans ${shellArg(first)}`, purpose: "Open the top trace to locate the relevant message.", mutability: "read", requires_approval: false });
+    }
+    if (hasMore) {
+      nextCommands.push({
+        command: `${tracesCommand} --offset=${nextOffset}`,
+        purpose: omitted > 0 ? `Read the ${omitted} trace-level result(s) left out to fit the agent byte limit, and the ones after them.` : "Page through further trace-level results.",
+        mutability: "read",
+        requires_approval: false
+      });
+    }
+    return {
+      returned: kept,
+      offset,
+      hasMore,
+      data: {
+        results: results.slice(0, kept),
+        fallback: {
+          source: "traces_search",
+          reason: "message_index_empty",
+          grain: "trace",
+          search_mode: traceMode,
+          total,
+          total_kind: literal ? "matches" : "candidate_pool",
+          has_more: hasMore,
+          ...offset > 0 ? { offset } : {},
+          ...hasMore ? { next_offset: nextOffset } : {},
+          ...omitted > 0 ? { omitted_for_byte_limit: omitted } : {}
+        }
+      },
+      warning: `Message-level search returned 0 results, so these are ${describe}, from \`moda traces --search\`. Each result is a whole trace, not a message, with no score or message index. Open one with \`moda traces spans <conversation_id>\` or \`moda traces get <conversation_id>\` to find the matching turn.` + (omitted > 0 ? ` ${kept} of the ${rows.length} trace-level results read are shown, to stay under the agent output byte limit (--json has no limit); the rest start at --offset=${nextOffset}.` : "") + (hasMore ? " More exist: page with the suggested `moda traces --search ... --offset` command." : ""),
+      nextCommands
+    };
   };
+  return { kind: "results", rows: rows.length, page };
 }
 function capProblemsBlocks(data, limit) {
   const truncated = {};
@@ -3822,6 +4090,31 @@ var NO_POSITIONAL_COMMANDS = new Set([
   "tail",
   "problem-impact"
 ]);
+function rejectInapplicableFlags(command, params, keys, why) {
+  const given = keys.filter((key) => params[key] !== undefined);
+  if (given.length === 0)
+    return;
+  const names = given.map(kebabFlag);
+  const shown = canonicalCommandText(`moda ${command}`);
+  throw new CliInputError(`${names.join(", ")} ${given.length > 1 ? "do" : "does"} not apply ${why}, so nothing was sent.`, `Drop ${names.join(", ")}, or pick the mode that uses ${given.length > 1 ? "them" : "it"}. See '${shown} --help'.`, `inapplicable_flag:${names[0].slice(2)}`, { field: names[0], suggestedCommands: [`${shown} --help`] });
+}
+var BATCH_POSITIONAL_COMMANDS = new Set(["context", "audit", "trace"]);
+function assertPositionalArity(command, positionals) {
+  const spec = flagSpecFor(command);
+  const expected = spec?.positionals ?? [];
+  if (expected.length === 0 || expected.some((entry) => entry.variadic))
+    return;
+  if (BATCH_POSITIONAL_COMMANDS.has(command))
+    return;
+  if (command === "problem" && positionals[0] === "remainder")
+    return;
+  if (positionals.length <= expected.length)
+    return;
+  const extra = positionals.slice(expected.length);
+  const shown = canonicalCommandText(`moda ${command}`);
+  const takes = expected.map((entry) => `<${entry.name}>`).join(" ");
+  throw new CliInputError(`Unexpected argument${extra.length > 1 ? "s" : ""} '${extra.join(" ")}' for '${shown}', which takes ${takes}, so nothing was sent.`, `Quote a value that has spaces, and pass free text as a flag value (e.g. --reason="..."). Usage: ${canonicalCommandText(usageLine(command, spec))}`, "unexpected_positional", { field: `<${expected[expected.length - 1].name}>`, suggestedCommands: [`${shown} --help`] });
+}
 function assertHandParsedFlags(command, flags, positionals) {
   if (command === "signals" && positionals[0]) {
     if (SIGNALS_MANAGEMENT_SUBCOMMANDS.has(positionals[0]))
@@ -3831,6 +4124,7 @@ function assertHandParsedFlags(command, flags, positionals) {
   if (NO_POSITIONAL_COMMANDS.has(command) && positionals.length > 0) {
     throw new CliInputError(`'moda ${command}' takes no arguments, but got '${positionals.join(" ")}'.`, `Nothing was run. See 'moda ${command} --help' for its flags.`);
   }
+  assertPositionalArity(command, positionals);
   const hand = handParsedFlags(command);
   if (!hand)
     return;
@@ -3959,6 +4253,10 @@ async function readContextMetadataOnly(contextPath, query2) {
 }
 var FULL_TRANSCRIPT_DEFAULT_MAX_MESSAGES = 500;
 var CONTEXT_RANGE_PAGE_SIZE = 200;
+var CONTEXT_BUDGET_BYTES_PER_FIRST_PAGE_MESSAGE = 480;
+function jsonByteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value) ?? "", "utf8");
+}
 var LEGACY_WINDOW_MAX_MESSAGES = 100;
 var CONTEXT_MESSAGE_TRUNCATE_CHARS = 500;
 var LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g;
@@ -3996,8 +4294,15 @@ async function readFullTranscript(conversationId, opts = {}) {
   let nextFrom = null;
   let legacy = false;
   let cursor = start;
+  let readBytes = 0;
+  const byteBudget = opts.fits ? opts.maxBytes : undefined;
   for (;; ) {
-    const count = Math.min(CONTEXT_RANGE_PAGE_SIZE, requested - messages.length);
+    let count = Math.min(CONTEXT_RANGE_PAGE_SIZE, requested - messages.length);
+    if (byteBudget !== undefined) {
+      const average = messages.length > 0 ? readBytes / messages.length : 0;
+      const estimate = average > 0 ? Math.ceil(Math.max(0, byteBudget - readBytes) / average) + 1 : Math.max(1, Math.floor(byteBudget / CONTEXT_BUDGET_BYTES_PER_FIRST_PAGE_MESSAGE));
+      count = Math.max(1, Math.min(count, estimate));
+    }
     let page;
     try {
       page = asRecord(await callDataAPI(`${path}?from=${cursor}&count=${count}`)) ?? {};
@@ -4015,10 +4320,14 @@ async function readFullTranscript(conversationId, opts = {}) {
     }
     const batch = pageMessages(page);
     messages.push(...batch);
+    if (byteBudget !== undefined)
+      readBytes += batch.reduce((sum, message) => sum + jsonByteLength(message) + 1, 0);
     const next = asNumber(page.next_from);
     nextFrom = page.has_more === true && next !== null && next !== undefined && next > cursor ? next : null;
     if (nextFrom === null || batch.length === 0 || messages.length >= requested)
       break;
+    if (byteBudget !== undefined && readBytes > byteBudget)
+      break;
     cursor = nextFrom;
   }
   if (legacy) {
@@ -4115,12 +4424,14 @@ async function readFullTranscript(conversationId, opts = {}) {
   }
   return build(low);
 }
-async function readContextItem(command, params, inputWarnings, fits) {
+async function readContextItem(command, params, inputWarnings, budget) {
+  const fits = budget?.fits;
   if (params.all === true) {
     const full = await readFullTranscript(params.conversation_id, {
       from: params.from,
       maxMessages: params.max_messages,
-      fits: fits ? (page) => fits(page.data, { warnings: page.warnings, nextCommands: page.nextCommands }) : undefined
+      fits: fits ? (page) => fits(page.data, { warnings: page.warnings, nextCommands: page.nextCommands }) : undefined,
+      maxBytes: budget?.maxBytes
     });
     const fullWarnings = [...inputWarnings, ...full.warnings];
     return {
@@ -4154,13 +4465,85 @@ async function readContextItem(command, params, inputWarnings, fits) {
     warnings.push(`--window=${params.window} is above the maximum of ${CONTEXT_MAX_WINDOW}, so this shows ±${CONTEXT_MAX_WINDOW} messages. For a wider slice run: ${wide}`);
     nextCommands.push({ command: wide, purpose: `Read ±${params.window} messages around the anchor.`, mutability: "read", requires_approval: false });
   }
-  return {
-    data,
-    options: {
-      ...warnings.length > 0 ? { warnings } : {},
-      ...nextCommands.length > 0 ? { nextCommands } : {}
+  const options = (extraWarnings = [], extraNext = []) => {
+    const allWarnings = [...warnings, ...extraWarnings];
+    const allNext = [...nextCommands, ...extraNext];
+    return {
+      ...allWarnings.length > 0 ? { warnings: allWarnings } : {},
+      ...allNext.length > 0 ? { nextCommands: allNext } : {}
+    };
+  };
+  if (fits && params.metadata_only !== true && !fits(data, options())) {
+    const trimmed = trimContextWindow(params.conversation_id, ctxRecord, params.msg_index, (page, extraWarnings, extraNext) => fits(page, options(extraWarnings, extraNext)));
+    if (trimmed)
+      return { data: trimmed.data, options: options(trimmed.warnings, trimmed.nextCommands) };
+  }
+  return { data, options: options() };
+}
+function trimContextWindow(conversationId, record, requestedAnchor, fits) {
+  const ctx = asRecord(record.context);
+  const messages = Array.isArray(ctx?.messages) ? ctx.messages : [];
+  if (!ctx || messages.length <= 1)
+    return;
+  const firstIndex = asNumber(ctx.from_index) ?? asNumber(asRecord(messages[0])?.index) ?? 0;
+  const indexed = messages.map((message, position) => ({
+    message,
+    index: asNumber(asRecord(message)?.index) ?? firstIndex + position
+  }));
+  const center = asNumber(ctx.center_index) ?? requestedAnchor ?? indexed[Math.floor(indexed.length / 2)].index;
+  const requestedFrom = Math.min(asNumber(ctx.from_index) ?? indexed[0].index, indexed[0].index);
+  const requestedTo = Math.max(asNumber(ctx.to_index) ?? indexed[indexed.length - 1].index, indexed[indexed.length - 1].index);
+  const order = [...indexed].sort((left, right) => Math.abs(left.index - center) - Math.abs(right.index - center) || right.index - left.index);
+  const target = shellArg(contextTarget(conversationId));
+  const build = (kept) => {
+    const returned = order.slice(0, kept).sort((left, right) => left.index - right.index);
+    const from = returned[0].index;
+    const to = returned[returned.length - 1].index;
+    const before = from - requestedFrom;
+    const after = requestedTo - to;
+    const nextCommands = [];
+    if (before > 0) {
+      nextCommands.push({
+        command: `moda traces get ${target} --all --from=${requestedFrom} --max-messages=${before}`,
+        purpose: `Read the ${before} message(s) before ${from} that were left out to fit the agent byte limit.`,
+        mutability: "read",
+        requires_approval: false
+      });
     }
+    if (after > 0) {
+      nextCommands.push({
+        command: `moda traces get ${target} --all --from=${to + 1} --max-messages=${after}`,
+        purpose: `Read the ${after} message(s) after ${to} that were left out to fit the agent byte limit.`,
+        mutability: "read",
+        requires_approval: false
+      });
+    }
+    const warnings = kept < order.length ? [
+      `Window cut to messages ${from}-${to} around anchor ${center} to stay under the agent output byte limit (--json has no limit); requested ${requestedFrom}-${requestedTo}. Read the rest with: ${nextCommands.map((next) => next.command).join(" and ")}.`
+    ] : [];
+    const data = {
+      ...record,
+      context: {
+        ...ctx,
+        from_index: from,
+        to_index: to,
+        messages: returned.map((entry) => entry.message),
+        ...kept < order.length ? { requested_from_index: requestedFrom, requested_to_index: requestedTo, omitted_for_byte_limit: order.length - kept } : {}
+      }
+    };
+    return { data, warnings, nextCommands };
   };
+  let low = 1;
+  let high = order.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const page = build(mid);
+    if (fits(page.data, page.warnings, page.nextCommands))
+      low = mid;
+    else
+      high = mid - 1;
+  }
+  return build(low);
 }
 var AUDIT_USAGE = "Usage: moda traces spans <conversation_id|trace_id> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] [--cursor=<next_cursor>]";
 var AUDIT_BATCH_USAGE = `Usage: moda traces spans <id> <id> ... | --ids-from=-|<file> [--kind=auto|trace|conversation] [--include-raw] [--include-bodies] [--limit=N] (max ${BATCH_MAX_TARGETS} targets)`;
@@ -4176,16 +4559,31 @@ async function readAuditItem(command, params, budget) {
     query2.set("limit", params.limit.toString());
   if (params.cursor)
     query2.set("cursor", params.cursor);
-  let maxBytes = budget?.maxBytes;
-  let page = auditOutput(command, params, await fetchAudit(params.id, query2, maxBytes));
-  while (budget && maxBytes !== undefined && maxBytes > AUDIT_MIN_PAGE_BYTES && !budget.fits(page.data, page.options)) {
-    maxBytes = Math.max(AUDIT_MIN_PAGE_BYTES, Math.floor(maxBytes / 2));
-    page = auditOutput(command, params, await fetchAudit(params.id, query2, maxBytes));
+  const pageBytes = params.page_bytes ?? (budget ? auditMaxBytes(budget.maxBytes) : undefined);
+  const raw = await fetchAudit(params.id, query2, pageBytes);
+  params = { ...params, page_bytes: pageBytes };
+  const whole = auditOutput(command, params, raw);
+  if (!budget || budget.fits(whole.data, whole.options))
+    return whole;
+  const spans = asRecord(raw)?.spans;
+  const available = (Array.isArray(spans) ? spans.length : 0) - (params.span_offset ?? 0);
+  if (available <= 0)
+    return whole;
+  let low = 1;
+  let high = available;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const page2 = auditOutput(command, params, raw, mid);
+    if (budget.fits(page2.data, page2.options))
+      low = mid;
+    else
+      high = mid - 1;
   }
-  if (budget && !budget.fits(page.data, page.options)) {
+  const page = auditOutput(command, params, raw, low);
+  if (low === 1 && !budget.fits(page.data, page.options)) {
     page.options.warnings = [
       ...page.options.warnings ?? [],
-      "This page is larger than the agent output budget even at the smallest page the server returns, so some of its spans are cut from this output. Rerun this command with --json (no byte limit) or a higher MODA_AGENT_MAX_OUTPUT_BYTES to see the whole row before following next_cursor."
+      "One span of this page is larger than the agent output budget, so agent output shortens it. Rerun this command with --json (no byte limit) or a higher MODA_AGENT_MAX_OUTPUT_BYTES to see it whole."
     ];
   }
   return page;
@@ -4202,6 +4600,16 @@ function singleContextTarget(positional, flags) {
   }
   return [target.id, { ...flags, "msg-index": String(target.msgIndex) }];
 }
+async function withAnchorHint(target, read) {
+  try {
+    return await read();
+  } catch (error) {
+    if (!(error instanceof CliNotFoundError) || target.msgIndex === undefined || target.raw.startsWith("{"))
+      throw error;
+    const verbatim = JSON.stringify({ id: target.raw });
+    throw new CliNotFoundError(error.entity, error.id, `${error.message} '${target.raw}' was read as trace "${target.id}" anchored at message ${target.msgIndex} (the @N suffix is a message index). If "${target.raw}" is the whole trace id, pass it as ${shellArg(verbatim)} or --conversation-id=${shellArg(target.raw)}.`, `moda traces get ${shellArg(verbatim)}`);
+  }
+}
 function isBatchRead(positionals, flags) {
   return positionals.length > 1 || IDS_FROM_KEYS.some((key) => flags[key] !== undefined);
 }
@@ -4216,14 +4624,41 @@ function splitIdsFrom(flags) {
   }
   return { idsFrom, rest };
 }
-function auditItemByteShare(count) {
-  return Math.max(AUDIT_MIN_PAGE_BYTES, Math.floor((agentMaxOutputBytes() - AUDIT_AGENT_RESERVE_BYTES) / count));
-}
 var BATCH_ENVELOPE_RESERVE_BYTES = 4096;
-var BATCH_ENVELOPE_RESERVE_PER_TARGET_BYTES = 256;
-function contextItemByteShare(count) {
-  const reserve = BATCH_ENVELOPE_RESERVE_BYTES + BATCH_ENVELOPE_RESERVE_PER_TARGET_BYTES * count;
-  return Math.max(1, Math.floor((agentMaxOutputBytes() - reserve) / count));
+function batchTargetReserveBytes(target) {
+  return 3 * (jsonByteLength(target.raw) + 4) + 16;
+}
+var BATCH_MIN_ITEM_SHARE_BYTES = 4096;
+async function readBatchTargets(targets, agentMode, read) {
+  if (!agentMode) {
+    return mapWithConcurrency(targets, BATCH_CONCURRENCY, (target) => readBatchItem(target, () => read(target, undefined)));
+  }
+  const reserve = targets.reduce((sum, target) => sum + batchTargetReserveBytes(target), BATCH_ENVELOPE_RESERVE_BYTES);
+  const available = Math.max(1, agentMaxOutputBytes() - reserve);
+  const fair = Math.max(BATCH_MIN_ITEM_SHARE_BYTES, Math.floor(available / targets.length));
+  let used = 0;
+  let reserved = 0;
+  const shares = new Map;
+  return mapWithConcurrency(targets, BATCH_CONCURRENCY, async (target, index) => {
+    const share = shares.get(index) ?? fair;
+    try {
+      const result = await readBatchItem(target, () => read(target, { fits: fitsShare(share), maxBytes: share }));
+      used += jsonByteLength(result) + 1;
+      return result;
+    } finally {
+      reserved -= share;
+    }
+  }, {
+    shouldStart: (index) => {
+      const free = available - used - reserved;
+      if (index > 0 && free < BATCH_MIN_ITEM_SHARE_BYTES)
+        return false;
+      const share = Math.max(1, Math.min(fair, free));
+      shares.set(index, share);
+      reserved += share;
+      return true;
+    }
+  });
 }
 function fitsShare(share) {
   return (data, options) => Buffer.byteLength(JSON.stringify({ data, ...options }) ?? "", "utf8") <= share;
@@ -4335,27 +4770,25 @@ async function runContextBatch(command, positionals, flags, context) {
     throw new CliInputError(`${base.all === true ? "--all reads whole traces" : "--metadata-only reads no messages"}, so targets cannot carry an @msg_index anchor; drop the flag or the anchors.`, CONTEXT_BATCH_USAGE, "flag_conflict");
   }
   const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
-  const share = agentMode ? contextItemByteShare(targets.length) : undefined;
-  const results = await mapWithConcurrency(targets, BATCH_CONCURRENCY, (target) => readBatchItem(target, () => {
+  const results = await readBatchTargets(targets, agentMode, (target, budget) => {
     const params = {
       ...base,
       conversation_id: target.id,
       ...target.msgIndex !== undefined ? { msg_index: target.msgIndex } : {}
     };
-    return readContextItem(command, params, [], share !== undefined ? fitsShare(share) : undefined);
-  }));
+    return withAnchorHint(target, () => readContextItem(command, params, [], budget));
+  });
   return writeBatchResult(command, context, targets, results, inputWarnings, rest);
 }
 async function runAuditBatch(command, positionals, flags, context) {
   const { idsFrom, rest } = splitIdsFrom(flags);
-  if (rest.cursor !== undefined) {
-    throw new CliInputError("--cursor continues one trace, so it cannot be used with several ids; follow each item's next_commands instead.", AUDIT_BATCH_USAGE, "flag_conflict");
+  if (rest.cursor !== undefined || Object.keys(rest).some((key) => key.replace(/_/g, "-") === "span-offset")) {
+    throw new CliInputError(`${rest.cursor !== undefined ? "--cursor" : "--span-offset"} continues one trace, so it cannot be used with several ids; follow each item's next_commands instead.`, AUDIT_BATCH_USAGE, "flag_conflict");
   }
   const targets = await collectBatchTargets(positionals, idsFrom, { anchors: false, usage: AUDIT_BATCH_USAGE, command });
   const base = parseCommandFlags(AuditSchema, flagsToArgs(rest, "id", targets[0].id), command, { positionalKey: "id" });
   const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
-  const share = agentMode ? auditItemByteShare(targets.length) : undefined;
-  const results = await mapWithConcurrency(targets, BATCH_CONCURRENCY, (target) => readBatchItem(target, () => readAuditItem(command, { ...base, id: target.id }, share !== undefined ? { maxBytes: Math.max(AUDIT_MIN_PAGE_BYTES, share), fits: fitsShare(share) } : undefined)));
+  const results = await readBatchTargets(targets, agentMode, (target, budget) => readAuditItem(command, { ...base, id: target.id }, budget));
   return writeBatchResult(command, context, targets, results, [], rest);
 }
 async function runCommand(command, positional, flags, positionals = positional ? [positional] : [], context = createCommandContext({ command, positional, positionals, flags })) {
@@ -4378,6 +4811,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const args = flagsToArgs(flags);
       const params = parseSpecFlags("clusters", args, command);
       if (params.search !== undefined || params.node_id !== undefined) {
+        rejectInapplicableFlags(command, params, ["parent_id", "time_range"], "to a cluster search (--search/--node-id); they page the cluster hierarchy");
         const query3 = new URLSearchParams;
         if (params.search !== undefined)
           query3.set("q", params.search);
@@ -4394,6 +4828,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
         context.output.writeData(data2, warnings.length > 0 ? { warnings } : undefined);
         break;
       }
+      rejectInapplicableFlags(command, params, ["mode", "limit"], "without --search or --node-id; they shape a cluster search");
       const query2 = new URLSearchParams;
       if (params.parent_id)
         query2.set("parent_id", params.parent_id);
@@ -4425,7 +4860,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "traces":
     case "conversations": {
-      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const args = flagsToArgs(flags);
       const params = parseSpecFlags("traces", args, command);
       const query2 = new URLSearchParams;
       if (params.search)
@@ -4476,7 +4911,8 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (params.include_world_state === true) {
         const enriched = asRecord(data) ?? {};
         const list = Array.isArray(enriched.conversations) ? enriched.conversations : [];
-        const withState = await attachWorldState(list);
+        const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
+        const withState = await attachWorldState(list, agentMode ? agentMaxOutputBytes() : undefined);
         context.output.writeData({ ...enriched, conversations: withState }, writeOptions);
       } else {
         context.output.writeData(data, writeOptions);
@@ -4484,10 +4920,11 @@ async function runCommand(command, positional, flags, positionals = positional ?
       break;
     }
     case "search": {
-      if (!positional || positional.trim() === "") {
+      const queryText = positionals.join(" ");
+      if (queryText.trim() === "") {
         throw new CliInputError("<query> is required", 'Usage: moda traces search "<query>" [--mode=keyword|semantic|hybrid] [--user-id=ID] [--conversation-id=ID] [--time-range=RANGE] [--since=DATE] [--until=DATE] [--include-tool-io] [--limit=N]');
       }
-      const args = withStringIdFlags(flagsToArgs(flags, "q", positional), flags);
+      const args = flagsToArgs(flags, "q", queryText);
       const params = parseSpecFlags("search", args, command);
       const query2 = new URLSearchParams;
       query2.set("q", params.q);
@@ -4524,15 +4961,42 @@ async function runCommand(command, positional, flags, positionals = positional ?
           break;
         }
         if (fallback?.kind === "results") {
-          warnings.push(fallback.warning);
-          const fallbackResults = fallback.data.results;
-          const merged = {
-            ...searchRecord,
-            ...fallback.data,
-            pagination: { ...asRecord(searchRecord.pagination) ?? {}, returned: fallbackResults.length, has_more: fallback.hasMore }
+          const write = (kept2) => {
+            const page2 = fallback.page(kept2);
+            const merged = {
+              ...searchRecord,
+              ...page2.data,
+              pagination: {
+                ...asRecord(searchRecord.pagination) ?? {},
+                returned: page2.returned,
+                has_more: page2.hasMore,
+                offset: page2.offset,
+                ...page2.returned < fallback.rows ? { omitted_for_byte_limit: fallback.rows - page2.returned } : {}
+              }
+            };
+            return { data: merged, options: { warnings: [...warnings, page2.warning], nextCommands: page2.nextCommands } };
+          };
+          const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
+          let kept = fallback.rows;
+          const fitsAgent = (count) => {
+            const page2 = write(count);
+            return agentEnvelopeFits(command, page2.data, page2.options);
           };
-          recordSearchTelemetry(context, merged);
-          context.output.writeData(merged, { warnings, nextCommands: fallback.nextCommands });
+          if (agentMode && kept > 1 && !fitsAgent(kept)) {
+            let low = 1;
+            let high = kept - 1;
+            while (low < high) {
+              const mid = Math.ceil((low + high) / 2);
+              if (fitsAgent(mid))
+                low = mid;
+              else
+                high = mid - 1;
+            }
+            kept = low;
+          }
+          const page = write(kept);
+          recordSearchTelemetry(context, page.data);
+          context.output.writeData(page.data, page.options);
           break;
         }
       }
@@ -4590,7 +5054,8 @@ async function runCommand(command, positional, flags, positionals = positional ?
         return runContextBatch(command, positionals, flags, context);
       const { params, warnings: inputWarnings } = parseContextRequest(...singleContextTarget(positional, flags));
       const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
-      const item = await readContextItem(command, params, inputWarnings, agentMode ? (data, options) => agentEnvelopeFits(command, data, options) : undefined);
+      const read = () => readContextItem(command, params, inputWarnings, agentMode ? { fits: (data, options) => agentEnvelopeFits(command, data, options), maxBytes: agentMaxOutputBytes() } : undefined);
+      const item = positional === undefined ? await read() : await withAnchorHint(parseBatchTarget(positional, true, CONTEXT_USAGE), read);
       context.output.writeData(item.data, item.options);
       break;
     }
@@ -4604,15 +5069,12 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const args = flagsToArgs(flags, "id", positional);
       const params = parseSpecFlags("audit", args, command);
       const agentMode = context.output.mode === "agent" || context.output.mode === "agent-stream";
-      const page = await readAuditItem(command, params, agentMode ? {
-        maxBytes: Math.max(AUDIT_MIN_PAGE_BYTES, agentMaxOutputBytes() - AUDIT_AGENT_RESERVE_BYTES),
-        fits: (data, options) => agentEnvelopeFits(command, data, options)
-      } : undefined);
+      const page = await readAuditItem(command, params, agentMode ? { maxBytes: agentMaxOutputBytes(), fits: (data, options) => agentEnvelopeFits(command, data, options) } : undefined);
       context.output.writeData(page.data, page.options);
       break;
     }
     case "frustrations": {
-      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const args = flagsToArgs(flags);
       const params = parseSpecFlags("frustrations", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
@@ -4775,6 +5237,11 @@ async function runCommand(command, positional, flags, positionals = positional ?
       if (view !== undefined && params.full === true) {
         throw new CliInputError("--full applies to the dossier only; the --evidence/--reports/--traces/--feedback pages are always whole.", "Usage: moda problems get <problem_id> [--full] | moda problems get <problem_id> --evidence|--reports|--traces|--feedback");
       }
+      if (view === undefined) {
+        rejectInapplicableFlags(command, params, ["limit", "cursor", "family", "door"], "to the dossier; they page --evidence/--reports/--traces/--feedback");
+      } else if (view !== "conversations") {
+        rejectInapplicableFlags(command, params, ["family", "door"], `to --${view}; they filter --traces`);
+      }
       if (view === undefined) {
         const data2 = await callDataAPI(`/problems/${encodeURIComponent(params.id)}`);
         const record = asRecord(data2) ?? {};
@@ -4844,15 +5311,21 @@ async function runCommand(command, positional, flags, positionals = positional ?
           throw new CliInputError("--attribution-id must be a UUID.");
         }
       }
-      const data = await callDataAPI(`/problems/${params.id}/feedback`, {
+      const feedbackPath = `/problems/${params.id}/feedback`;
+      const feedbackBody = {
+        action: params.action,
+        ...reason !== "" ? { reason } : {},
+        ...params.attribution_id ? { attribution_id: params.attribution_id } : {},
+        ...params.new_name ? { new_display_name: params.new_name } : {},
+        actor: params.actor ?? "moda-cli"
+      };
+      if (context.dryRun) {
+        writeDryRun(context, { plane: "data", method: "POST", path: feedbackPath, body: feedbackBody });
+        break;
+      }
+      const data = await callDataAPI(feedbackPath, {
         method: "POST",
-        body: JSON.stringify({
-          action: params.action,
-          ...reason !== "" ? { reason } : {},
-          ...params.attribution_id ? { attribution_id: params.attribution_id } : {},
-          ...params.new_name ? { new_display_name: params.new_name } : {},
-          actor: params.actor ?? "moda-cli"
-        }),
+        body: JSON.stringify(feedbackBody),
         headers: { "Content-Type": "application/json" }
       }, { retries: 0 });
       context.output.writeData(data);
@@ -4870,10 +5343,10 @@ async function runCommand(command, positional, flags, positionals = positional ?
       });
       const link = asRecord(data)?.link;
       const summary = describeLinearLink(link);
-      const nextCommands = link ? [] : [`moda problems link ${positional}`];
+      const nextCommands = link ? [] : [`moda problems link ${shellArg(positional)}`];
       if (context.outputMode === "human" && !context.quiet) {
         safeWriteStderr(link ? `${summary}
-` : `${summary} File one with: moda problems link ${positional}
+` : `${summary} File one with: moda problems link ${shellArg(positional)}
 `);
       }
       context.output.writeData(data, { summary, nextCommands });
@@ -4903,13 +5376,19 @@ async function runCommand(command, positional, flags, positionals = positional ?
       }
       const title = params.title?.trim() ?? "";
       const teamId = params.team_id?.trim() ?? "";
-      const data = await callDataAPI(`/problems/${params.id}/linear`, {
+      const linearPath = `/problems/${params.id}/linear`;
+      const linearBody = issue !== "" ? { issue } : {
+        ...teamId !== "" ? { team_id: teamId } : {},
+        ...title !== "" ? { title } : {},
+        ...params.priority !== undefined ? { priority: params.priority } : {}
+      };
+      if (context.dryRun) {
+        writeDryRun(context, { plane: "data", method: "POST", path: linearPath, body: linearBody });
+        break;
+      }
+      const data = await callDataAPI(linearPath, {
         method: "POST",
-        body: JSON.stringify(issue !== "" ? { issue } : {
-          ...teamId !== "" ? { team_id: teamId } : {},
-          ...title !== "" ? { title } : {},
-          ...params.priority !== undefined ? { priority: params.priority } : {}
-        }),
+        body: JSON.stringify(linearBody),
         headers: { "Content-Type": "application/json" }
       }, { retries: 0 }).catch((error) => {
         throw linearApiError(error);
@@ -4941,6 +5420,7 @@ async function runCommand(command, positional, flags, positionals = positional ?
       const params = parseSpecFlags("signal", args, command);
       const id = encodeURIComponent(params.id);
       if (params.detections !== true) {
+        rejectInapplicableFlags(command, params, ["days_back", "limit", "offset"], "to the signal summary; they page its hits (--detections)");
         const data2 = await callDataAPI(`/custom-signals/${id}`);
         context.output.writeData(data2);
         break;
@@ -4979,15 +5459,21 @@ async function runCommand(command, positional, flags, positionals = positional ?
         ...flags["msg-dedup-token"] !== undefined ? { msg_dedup_token: flags["msg-dedup-token"] } : {}
       });
       const note = params.note?.trim() ?? "";
-      const data = await callDataAPI(`/custom-signals/${encodeURIComponent(params.id)}/labels`, {
+      const labelPath = `/custom-signals/${encodeURIComponent(params.id)}/labels`;
+      const labelBody = {
+        conversation_id: params.conversation_id,
+        label: params.label,
+        ...note !== "" ? { note } : {},
+        ...params.msg_index !== undefined ? { msg_index: params.msg_index } : {},
+        ...params.msg_dedup_token ? { msg_dedup_token: params.msg_dedup_token } : {}
+      };
+      if (context.dryRun) {
+        writeDryRun(context, { plane: "data", method: "POST", path: labelPath, body: labelBody });
+        break;
+      }
+      const data = await callDataAPI(labelPath, {
         method: "POST",
-        body: JSON.stringify({
-          conversation_id: params.conversation_id,
-          label: params.label,
-          ...note !== "" ? { note } : {},
-          ...params.msg_index !== undefined ? { msg_index: params.msg_index } : {},
-          ...params.msg_dedup_token ? { msg_dedup_token: params.msg_dedup_token } : {}
-        }),
+        body: JSON.stringify(labelBody),
         headers: { "Content-Type": "application/json" }
       }, { retries: 0 });
       context.output.writeData(data);
@@ -5019,15 +5505,20 @@ async function runCommand(command, positional, flags, positionals = positional ?
         ...flags.note !== undefined ? { note: flags.note } : {}
       });
       const note = params.verdict === "clear" ? "" : params.note?.trim() ?? "";
-      const data = await callDataAPI(`/problems/${params.id}/detection-reviews`, {
+      const reviewPath = `/problems/${params.id}/detection-reviews`;
+      const reviewBody = {
+        conversation_id: params.conversation_id,
+        attribution_id: params.attribution_id,
+        verdict: params.verdict,
+        ...note !== "" ? { note } : {}
+      };
+      if (context.dryRun) {
+        writeDryRun(context, { plane: "data", method: "POST", path: reviewPath, body: reviewBody, generatedFields: ["request_nonce"] });
+        break;
+      }
+      const data = await callDataAPI(reviewPath, {
         method: "POST",
-        body: JSON.stringify({
-          conversation_id: params.conversation_id,
-          attribution_id: params.attribution_id,
-          verdict: params.verdict,
-          ...note !== "" ? { note } : {},
-          request_nonce: randomUUID2()
-        }),
+        body: JSON.stringify({ ...reviewBody, request_nonce: randomUUID2() }),
         headers: { "Content-Type": "application/json" }
       });
       context.output.writeData(data);
@@ -5054,50 +5545,77 @@ async function runCommand(command, positional, flags, positionals = positional ?
         ...flags["msg-dedup-token"] !== undefined ? { msg_dedup_token: flags["msg-dedup-token"] } : {}
       });
       const reason = params.reason?.trim() ?? "";
-      const post = (path, body, retries) => callDataAPI(path, { method: "POST", body: JSON.stringify(body), headers: { "Content-Type": "application/json" } }, retries === undefined ? undefined : { retries });
-      let data;
+      let request;
       switch (params.kind) {
         case "problem":
-          data = await post(`/problems/${params.target}/feedback`, { action: "dismiss", reason, actor: "moda-cli" }, 0);
+          request = { method: "POST", path: `/problems/${params.target}/feedback`, body: { action: "dismiss", reason, actor: "moda-cli" }, retries: 0 };
           break;
         case "problem-detection":
-          data = await post(`/problems/${params.target}/detection-reviews`, {
-            conversation_id: params.conversation_id,
-            attribution_id: params.attribution_id,
-            verdict: params.undo ? "clear" : "false_positive",
-            ...params.undo ? {} : { note: reason },
-            request_nonce: randomUUID2()
-          });
+          request = {
+            method: "POST",
+            path: `/problems/${params.target}/detection-reviews`,
+            body: {
+              conversation_id: params.conversation_id,
+              attribution_id: params.attribution_id,
+              verdict: params.undo ? "clear" : "false_positive",
+              ...params.undo ? {} : { note: reason }
+            },
+            nonce: true
+          };
           break;
         case "custom-signal":
-          if (params.undo) {
-            data = await callDataAPI(`/custom-signals/${encodeURIComponent(params.target)}/labels/${encodeURIComponent(params.conversation_id ?? "")}`, { method: "DELETE" }, { retries: 0 });
-            break;
-          }
-          data = await post(`/custom-signals/${encodeURIComponent(params.target)}/labels`, {
-            conversation_id: params.conversation_id,
-            label: "does_not_fit",
-            note: reason,
-            ...params.msg_index !== undefined ? { msg_index: params.msg_index } : {},
-            ...params.msg_dedup_token ? { msg_dedup_token: params.msg_dedup_token } : {}
-          }, 0);
+          request = params.undo ? {
+            method: "DELETE",
+            path: `/custom-signals/${encodeURIComponent(params.target)}/labels/${encodeURIComponent(params.conversation_id ?? "")}`,
+            retries: 0
+          } : {
+            method: "POST",
+            path: `/custom-signals/${encodeURIComponent(params.target)}/labels`,
+            body: {
+              conversation_id: params.conversation_id,
+              label: "does_not_fit",
+              note: reason,
+              ...params.msg_index !== undefined ? { msg_index: params.msg_index } : {},
+              ...params.msg_dedup_token ? { msg_dedup_token: params.msg_dedup_token } : {}
+            },
+            retries: 0
+          };
           break;
         default: {
           const apiKind = { quote: "frustration_quote", tool: "tool_call", laziness: "laziness", hallucination: "hallucination" }[params.kind];
-          data = await post("/false-positives", {
-            kind: apiKind,
-            verdict: params.undo ? "clear" : "false_positive",
-            ...params.undo ? {} : { note: reason },
-            conversation_id: params.target,
-            ...params.kind === "tool" ? {
-              tool_name: params.tool,
-              ...params.tool_use_id ? { tool_use_id: params.tool_use_id } : { msg_index: params.msg_index }
-            } : {},
-            ...params.kind === "quote" ? { family: params.family, turn: params.turn, quote: params.quote } : {},
-            request_nonce: randomUUID2()
-          });
+          request = {
+            method: "POST",
+            path: "/false-positives",
+            body: {
+              kind: apiKind,
+              verdict: params.undo ? "clear" : "false_positive",
+              ...params.undo ? {} : { note: reason },
+              conversation_id: params.target,
+              ...params.kind === "tool" ? {
+                tool_name: params.tool,
+                ...params.tool_use_id ? { tool_use_id: params.tool_use_id } : { msg_index: params.msg_index }
+              } : {},
+              ...params.kind === "quote" ? { family: params.family, turn: params.turn, quote: params.quote } : {}
+            },
+            nonce: true
+          };
         }
       }
+      if (context.dryRun) {
+        writeDryRun(context, {
+          plane: "data",
+          method: request.method,
+          path: request.path,
+          ...request.body ? { body: request.body } : {},
+          ...request.nonce ? { generatedFields: ["request_nonce"] } : {}
+        });
+        break;
+      }
+      const sentBody = request.body && request.nonce ? { ...request.body, request_nonce: randomUUID2() } : request.body;
+      const data = await callDataAPI(request.path, {
+        method: request.method,
+        ...sentBody ? { body: JSON.stringify(sentBody), headers: { "Content-Type": "application/json" } } : {}
+      }, request.retries === undefined ? undefined : { retries: request.retries });
       context.output.writeData(data);
       break;
     }
@@ -5125,12 +5643,13 @@ async function runCommand(command, positional, flags, positionals = positional ?
         context.output.writeData(data2);
         break;
       }
+      rejectInapplicableFlags(command, { kind: flags.kind, limit: flags.limit, all: flags.all === "false" ? undefined : flags.all }, ["kind", "limit", "all"], "to one trace's marks (every mark on the trace is listed); they filter the workspace list");
       const data = await callDataAPI(`/conversations/${encodeURIComponent(positional)}/false-positives`);
       context.output.writeData(data);
       break;
     }
     case "emotions": {
-      const args = withStringIdFlags(flagsToArgs(flags), flags);
+      const args = flagsToArgs(flags);
       const params = parseSpecFlags("emotions", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
@@ -5158,9 +5677,6 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "laziness": {
       const args = flagsToArgs(flags);
-      if (flags["conversation-id"] !== undefined) {
-        args.conversation_id = flags["conversation-id"];
-      }
       const params = parseSpecFlags("laziness", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
@@ -5180,9 +5696,6 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "hallucinations": {
       const args = flagsToArgs(flags);
-      if (flags["conversation-id"] !== undefined) {
-        args.conversation_id = flags["conversation-id"];
-      }
       const params = parseSpecFlags("hallucinations", args, command);
       const query2 = new URLSearchParams;
       if (params.days_back)
@@ -5223,17 +5736,22 @@ async function runCommand(command, positional, flags, positionals = positional ?
     }
     case "feedback": {
       const { category, severity, note, refs, warnings } = buildFeedbackRequest(positionals, flags, context.bareFlags);
+      const feedbackBody = {
+        category,
+        severity,
+        source: "cli",
+        agent: detectCallerAgent(process.env),
+        cli_version: VERSION,
+        note,
+        ...Object.keys(refs).length > 0 ? { refs } : {}
+      };
+      if (context.dryRun) {
+        writeDryRun(context, { plane: "data", method: "POST", path: "/feedback", body: feedbackBody });
+        break;
+      }
       const data = await callDataAPI("/feedback", {
         method: "POST",
-        body: JSON.stringify({
-          category,
-          severity,
-          source: "cli",
-          agent: detectCallerAgent(process.env),
-          cli_version: VERSION,
-          note,
-          ...Object.keys(refs).length > 0 ? { refs } : {}
-        })
+        body: JSON.stringify(feedbackBody)
       }, { retries: 0 });
       context.output.writeData({ submitted: true, category, severity, ...asRecord(data) ?? {} }, {
         summary: "Feedback submitted. Thank you for helping us improve!",
@@ -5382,7 +5900,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runInit } = await import("./index-4b1ybz51.js");
+      const { runInit } = await import("./index-91bpc8g8.js");
       if (context.outputMode === "agent-stream") {
         context.output.writeEvent({
           event: "started",
@@ -5432,7 +5950,7 @@ var commandRegistry = createCommandRegistry([
     resetApiRequestCountBeforeRun: true,
     telemetry: "result-and-error",
     handler: async (context) => {
-      const { runProvision } = await import("./provision-q86phh4a.js");
+      const { runProvision } = await import("./provision-bc3h68e1.js");
       return runProvision(context, {
         resumeCommand: buildResumeCommand("provision", context.rawFlags)
       });
@@ -6454,6 +6972,9 @@ ${error.suggestions.map((s) => `  ${s}`).join(`
 `)}
 `);
     }
+  } else if (error instanceof ApiError && error.statusCode === 404) {
+    safeWriteStderr2(`${errorToAgentError(error).message}
+`);
   } else if (error instanceof ApiError) {
     safeWriteStderr2(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}
 `);
@@ -6506,6 +7027,46 @@ function printAgentCliError(command, error, mode = "agent") {
   });
   output.writeError(error);
 }
+function flagNamesInLabel(label) {
+  return [...label.matchAll(/--([A-Za-z0-9][A-Za-z0-9-]*)/g)].map((match) => match[1]);
+}
+function specFlagNamesDeep(spec) {
+  if (!spec)
+    return [];
+  return [...specFlagNames(spec), ...Object.values(spec.subcommands ?? {}).flatMap((sub) => specFlagNames(sub))];
+}
+function telemetryAcceptedFlags(definition, route) {
+  const names = new Set([...GLOBAL_FLAG_NAMES, ...GLOBAL_BOOLEAN_FLAGS]);
+  const add = (list) => {
+    for (const name of list)
+      names.add(name);
+  };
+  if (definition) {
+    add(specFlagNamesDeep(flagSpecFor(definition.name)));
+    for (const flag of definition.documentedFlags ?? [])
+      add(flagNamesInLabel(flag.name));
+    for (const sub of definition.subcommands ?? [])
+      for (const flag of sub.flags ?? [])
+        add(flagNamesInLabel(flag.name));
+  }
+  if (route) {
+    add(route.allowedFlags ?? []);
+    add(Object.keys(route.flagAliases ?? {}));
+    add(specFlagNamesDeep(leafFlagSpec(route.leaf)));
+  }
+  return names;
+}
+var knownFlagNames;
+function telemetryKnownFlags() {
+  if (!knownFlagNames) {
+    knownFlagNames = new Set(RAW_BOOLEAN_FLAGS);
+    for (const definition of commandRegistry.all()) {
+      for (const name of telemetryAcceptedFlags(definition, undefined))
+        knownFlagNames.add(name);
+    }
+  }
+  return knownFlagNames;
+}
 function existingFlagProfile(flags) {
   const name = flags.profile;
   if (!name || name === "true")
@@ -6548,6 +7109,50 @@ function assertRoutedFlags(route, flags) {
   const args = Object.fromEntries(Object.keys(flags).filter((flag) => !aliases.has(flag.replace(/_/g, "-"))).map((flag) => [flag.replace(/-/g, "_"), true]));
   parseCommandFlags(shape.passthrough(), args, route.label, route.flagAliases ? { flagAliases: route.flagAliases } : {});
 }
+var EMPTY_VALUE_ALLOWED = {
+  context: new Set(["msg-index", "message-index"])
+};
+var EXAMPLE_CLEARABLE_FLAGS = new Set(["note", "blurb"]);
+function assertFlagValues(handler, positionals, typedFlags, bareFlags, route) {
+  const name = route?.handler ?? handler;
+  const spec = flagSpecFor(name);
+  if (spec?.idRefFlags)
+    return;
+  const bare = new Set(bareFlags ?? []);
+  const empty = new Set(Object.keys(typedFlags).filter((key) => String(typedFlags[key]).trim() === ""));
+  if (bare.size === 0 && empty.size === 0)
+    return;
+  const handlerPositionals = route?.positionals ?? positionals;
+  const managementSubcommand = name === "signals" && SIGNALS_MANAGEMENT_SUBCOMMANDS.has(handlerPositionals[0] ?? "");
+  const examplesUpdate = name === "signals" && handlerPositionals[0] === "examples" && handlerPositionals.includes("update");
+  const valued = new Set;
+  const switches = new Set(RAW_BOOLEAN_FLAGS);
+  for (const entry of specsOf(name)) {
+    for (const flag of describeSpecFlags(entry))
+      (flag.type === "boolean" ? switches : valued).add(flag.name.slice(2));
+    for (const positional of entry.positionals ?? [])
+      if (positional.key)
+        valued.add(positional.key.replace(/_/g, "-"));
+  }
+  for (const flag of route?.allowedFlags ?? [])
+    if (!switches.has(flag))
+      valued.add(flag);
+  for (const [key, value] of Object.entries(typedFlags)) {
+    const isBare = bare.has(key) && value === "true";
+    if (!isBare && !empty.has(key))
+      continue;
+    if (!isBare && EMPTY_VALUE_ALLOWED[name]?.has(key))
+      continue;
+    if (!isBare && examplesUpdate && EXAMPLE_CLEARABLE_FLAGS.has(key))
+      continue;
+    const target = route?.flagAliases?.[key] ?? key;
+    const takesValue = valued.has(key) || valued.has(target) || managementSubcommand && !switches.has(key) && !GLOBAL_FLAG_NAMES.has(key);
+    if (!takesValue || switches.has(key))
+      continue;
+    const shown = canonicalCommandText(`moda ${route?.leaf.path ?? handler}`);
+    throw new CliInputError(`--${key} needs a value, so nothing was sent.`, `Pass it as --${key}=VALUE (an empty shell variable leaves the flag without one). See '${shown} --help'.`, `missing_value:${key}`, { field: `--${key}`, suggestedCommands: [`${shown} --help`] });
+  }
+}
 function renameErrorCommands(error, renames) {
   if (error instanceof CliInputError) {
     const details2 = error.details;
@@ -6565,6 +7170,7 @@ function renameErrorCommands(error, renames) {
 }
 async function dispatchParsedCommandInner(typedParsed, startedAt) {
   const { command, flags } = typedParsed;
+  canonicalizeFlagKeys(flags, typedParsed.bareFlags);
   const switchError = normalizeBooleanFlags(flags);
   const typedFlags = stripUpdateCheckFlag(stripTelemetryFlag(flags));
   const telemetryDisabled = isTelemetryDisabled(flags);
@@ -6577,6 +7183,15 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
     if (command && printTreeHelp(typedParsed))
       return 0;
     const helpTarget = command && command !== "--help" && command !== "-h" ? commandRegistry.find(command) : undefined;
+    if (!helpTarget && command && command !== "--help" && command !== "-h") {
+      const mode = resolveOutputMode(typedFlags, { isTTY: process.stdout.isTTY, env: process.env });
+      const error = unknownCommandError(command);
+      if (mode === "agent" || mode === "agent-stream" || mode === "json")
+        printAgentCliError(command, error, mode);
+      else
+        printCliError(error);
+      return 1;
+    }
     if (helpTarget) {
       const subcommandName = typedParsed.positional;
       const subcommandEntry = subcommandName ? helpTarget.subcommands?.find((entry) => entry.name === subcommandName) : undefined;
@@ -6624,6 +7239,8 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
     if (!handlerTelemetry)
       return;
     const telemetryProfile = existingFlagProfile(typedFlags);
+    if (typedFlags.profile !== undefined && telemetryProfile === undefined)
+      return;
     const adoption = buildSearchAdoptionTelemetry({
       command: handlerTelemetry,
       positional: parsed.positional,
@@ -6651,12 +7268,14 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
       durationMs: Date.now() - startedAt,
       apiRequestCount: input.apiRequestCount,
       adoption,
-      ...identity2?.legacyAlias ? { legacyAlias: identity2.legacyAlias } : {}
+      ...identity2?.legacyAlias ? { legacyAlias: identity2.legacyAlias } : {},
+      acceptedFlags: telemetryAcceptedFlags(definition2, route),
+      knownFlags: telemetryKnownFlags()
     });
   };
   const failEarly = (error, commandDefinition, identity2) => {
     const mode = outputModeFor();
-    const telemetryOptOut = telemetryDisabled || flags["no-telemetry"] !== undefined && flags["no-telemetry"] !== "false";
+    const telemetryOptOut = telemetryDisabled || optOutFlagSet(flags, "no-telemetry", false);
     const reports = commandDefinition ? commandDefinition.telemetry === "result-and-error" : identity2 !== undefined;
     if (reports && !telemetryOptOut) {
       reportUsage({
@@ -6691,14 +7310,14 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
   }
   if (switchError)
     return failEarly(switchError, definition, identity);
-  if (route) {
-    try {
+  try {
+    if (route)
       assertRoutedFlags(route, typedFlags);
-    } catch (error) {
-      if (!(error instanceof CliInputError))
-        throw error;
-      return failEarly(error, definition, identity);
-    }
+    assertFlagValues(definition.name, parsed.positionals, typedFlags, typedParsed.bareFlags, route);
+  } catch (error) {
+    if (!(error instanceof CliInputError))
+      throw error;
+    return failEarly(error, definition, identity);
   }
   if (commandFlags.profile === "true" || commandFlags.profile === "") {
     return failEarly(new CliInputError("--profile needs a value, e.g. --profile=prod.", "List profiles with 'moda profiles list'.", "missing_value:profile"), definition, identity);
@@ -6708,7 +7327,7 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
     const known = Object.keys(loadProfileConfig({ env: process.env }).profiles);
     if (!known.includes(requestedProfile)) {
       const source = commandFlags.profile ? `--profile=${requestedProfile}` : `MODA_PROFILE=${requestedProfile}`;
-      return failEarly(new CliInputError(`Moda profile '${requestedProfile}' does not exist (from ${source}), so nothing was run.`, `Known profiles: ${known.join(", ")}. Create it with 'moda profiles create ${requestedProfile}' or fix the name.`, "unknown_profile"), definition, identity);
+      return failEarly(new CliInputError(`Moda profile '${requestedProfile}' does not exist (from ${source}), so nothing was run.`, `Known profiles: ${known.join(", ")}. Create it with 'moda profiles create ${shellArg(requestedProfile)}' or fix the name.`, "unknown_profile"), definition, identity);
     }
     if (commandFlags.profile)
       process.env.MODA_PROFILE = commandFlags.profile;
@@ -6717,7 +7336,7 @@ async function dispatchParsedCommandInner(typedParsed, startedAt) {
     commandFlags.agent = "true";
   }
   if (!updateCheckDisabled) {
-    startUpdateCheck();
+    startUpdateCheck({}, Date.now(), { detached: outputModeFor() !== "human" });
     setAgentUpdateNotice(() => {
       const latest = getAvailableUpdate();
       return latest ? `moda-cli ${VERSION} is out of date (latest ${latest}); commands and flags may differ from the docs. Update: npm install -g @moda-ai/cli@latest` : undefined;
@@ -6857,6 +7476,7 @@ if (isMain) {
 }
 export {
   unknownCommandError,
+  trimContextWindow,
   telemetrySubcommandNames,
   telemetryCommandName,
   stripLoneSurrogates,
@@ -6876,10 +7496,14 @@ export {
   dispatchParsedCommand,
   detectCallerAgent,
   describeLinearLink,
+  commandSwitchFlags,
   commandRegistry,
+  coerceNumericFlags,
   cliValidationReason,
   classifyCliError,
   capProblemsBlocks,
+  canonicalizeFlagKeys,
+  canonicalFlagKey,
   buildResumeCommand,
   auditCapStatus,
   TELEMETRY_EXEMPT_COMMANDS,