From 24f6e714c4f51802f966d5b4e85312d2b07f4a5c Mon Sep 17 00:00:00 2001
From: suibianwanwan <fanyuan.qiu@clickzetta.com>
Date: Mon, 24 Aug 2026 16:12:33 +0800
Subject: [PATCH] fix(cli): harden the argument and output surface against
 silent misreports

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/cz-cli/UPSTREAM-PATCHES.md           |  20 +
 packages/cz-cli/src/agent-mcp.ts              |  19 +-
 packages/cz-cli/src/bootstrap/runtime.ts      |  71 ++
 packages/cz-cli/src/cli.ts                    | 152 +++-
 packages/cz-cli/src/command-group.ts          |  15 +-
 packages/cz-cli/src/commands/agent-llm.ts     |  21 +-
 .../cz-cli/src/commands/analytics-agent.ts    |   3 +
 packages/cz-cli/src/commands/auth.ts          |  10 +-
 packages/cz-cli/src/commands/datasource.ts    |   3 +
 .../cz-cli/src/commands/profile-bootstrap.ts  |   3 +
 packages/cz-cli/src/commands/schema.ts        |   2 +-
 packages/cz-cli/src/commands/sql.ts           |  41 +-
 packages/cz-cli/src/commands/status.ts        |  43 +-
 packages/cz-cli/src/commands/task.ts          |   5 +-
 packages/cz-cli/src/connection/config.ts      |  30 +-
 packages/cz-cli/src/main.ts                   |   6 +-
 packages/cz-cli/src/output/index.ts           | 213 +++--
 packages/cz-cli/src/run-cli.ts                | 128 ++-
 packages/cz-cli/src/telemetry.ts              |  63 +-
 packages/cz-cli/src/usage-error.ts            |  16 +
 packages/cz-cli/test/agent-mcp.test.ts        |  34 +
 packages/cz-cli/test/auth-list-format.test.ts | 125 +++
 .../cz-cli/test/connection-config.test.ts     |  90 ++
 .../cz-cli/test/output-row-projection.test.ts | 425 ++++++++++
 .../cz-cli/test/parameter-hardening.test.ts   | 777 ++++++++++++++++++
 packages/cz-cli/test/status-exit-code.test.ts |  74 ++
 packages/cz-cli/test/telemetry.test.ts        |  36 +-
 27 files changed, 2291 insertions(+), 134 deletions(-)
 create mode 100644 packages/cz-cli/src/usage-error.ts
 create mode 100644 packages/cz-cli/test/auth-list-format.test.ts
 create mode 100644 packages/cz-cli/test/output-row-projection.test.ts
 create mode 100644 packages/cz-cli/test/parameter-hardening.test.ts
 create mode 100644 packages/cz-cli/test/status-exit-code.test.ts

diff --git a/packages/cz-cli/UPSTREAM-PATCHES.md b/packages/cz-cli/UPSTREAM-PATCHES.md
index 0166cafaad..cd047fe337 100644
--- a/packages/cz-cli/UPSTREAM-PATCHES.md
+++ b/packages/cz-cli/UPSTREAM-PATCHES.md
@@ -410,6 +410,26 @@ the hooks they depend on still exist in the new upstream.
 
 ---
 
+### 6. `cz-cli serve` flag surface
+
+- **cz files:** `packages/cz-cli/src/bootstrap/runtime.ts` (the `serve` branch:
+  `applyServeLogFlags`, `serveInheritedGlobals`).
+- **Mechanism:** `cz-cli serve` runs its own yargs instance around upstream's
+  `ServeCommand`, so it never passes through upstream's ROOT parser. Two things are
+  re-created there: the root parser's logging flags (`--print-logs`, `--log-level`,
+  `--pure`), wired to the same env vars upstream's root middleware sets
+  (`OPENCODE_PRINT_LOGS`, `OPENCODE_LOG_LEVEL`, `OPENCODE_PURE`), and the cz global
+  flags that run-cli has already consumed off the same argv, declared hidden so
+  `.strict()` can reject a real typo without rejecting a working invocation.
+- **Upstream hooks to re-verify:** `packages/opencode/src/cli/index.ts` still declares
+  those three flags on the root parser and its middleware still reads them from those
+  env var names; `packages/opencode/src/cli/cmd/serve.ts` still takes its network
+  options from `withNetworkOptions`.
+- **Failure mode if the hook moves:** the logging flags silently go back to being
+  accepted and doing nothing (an env var rename), or `serve` starts rejecting a flag
+  it should accept (a new global in cli.ts's `KNOWN_GLOBAL_FLAGS` is covered
+  automatically; a new UPSTREAM root flag is not).
+
 ## Re-baseline procedure (quick)
 
 1. Fast-forward upstream packages to the new opencode version.
diff --git a/packages/cz-cli/src/agent-mcp.ts b/packages/cz-cli/src/agent-mcp.ts
index f7d86804c3..3c9e6e300f 100644
--- a/packages/cz-cli/src/agent-mcp.ts
+++ b/packages/cz-cli/src/agent-mcp.ts
@@ -196,10 +196,21 @@ function manifestName(relativePath: string) {
 }
 
 function resolveClickZettaRemote(manifest: ClickZettaRemoteManifest, cliArgs: Partial<CliArgs>): RemoteMcpConfig | undefined {
-  const connection = resolveConnectionConfig({
-    ...cliArgs,
-    profile: manifest.profile ?? cliArgs.profile,
-  })
+  // `manifest.profile` is a field in a config file on disk, not something the caller
+  // typed, so a profile that has since been renamed or deleted must skip THIS entry —
+  // the way a manifest with no usable auth already does — rather than abort the whole
+  // invocation. resolveConnectionConfig rejects an explicitly named missing profile,
+  // and nothing between here and run-cli's injectAgentMcp call would catch it.
+  let connection: ReturnType<typeof resolveConnectionConfig>
+  try {
+    connection = resolveConnectionConfig({
+      ...cliArgs,
+      profile: manifest.profile ?? cliArgs.profile,
+    })
+  } catch (err) {
+    if ((err as { code?: unknown } | null)?.code === "PROFILE_NOT_FOUND") return undefined
+    throw err
+  }
   if (!hasLakehouseAuth(connection) && manifest.enabled !== false) return undefined
   return compactEntry({
     type: "remote",
diff --git a/packages/cz-cli/src/bootstrap/runtime.ts b/packages/cz-cli/src/bootstrap/runtime.ts
index 5a3f450bce..d8dd6141bb 100644
--- a/packages/cz-cli/src/bootstrap/runtime.ts
+++ b/packages/cz-cli/src/bootstrap/runtime.ts
@@ -7,10 +7,53 @@ import { flushOtel } from "../opencode-plugin/otel/index.js"
 import { flushLangfuse, initLangfuse } from "../langfuse.js"
 import { CLICKZETTA_AGENT_SYSTEM_PROMPT } from "../agent-system-prompt.js"
 import { parseAgentTimeoutMs } from "./runtime-config.js"
+import { KNOWN_GLOBAL_FLAGS } from "../cli.js"
 import { applyBaseOpencodeEnv, applyAgentRuntimeInjection } from "./opencode-injection.js"
 
 let globalHandlersRegistered = false
 
+/**
+ * The cz global flags that reach `cz-cli serve`'s own parser, as hidden no-ops.
+ *
+ * Built from cli.ts's KNOWN_GLOBAL_FLAGS — the single list the top-level parser and
+ * both fail handlers already use — so adding a global there cannot silently start
+ * failing `serve`. `help`/`version` are declared separately above with their real
+ * behavior, and the short aliases are declared as their own entries because they
+ * arrive un-canonicalized on this path.
+ */
+function serveInheritedGlobals(): Record<string, { type: "string" | "boolean"; hidden: true }> {
+  const booleans = new Set(["debug", "d"])
+  const skip = new Set(["help", "h", "version", "v"])
+  const options: Record<string, { type: "string" | "boolean"; hidden: true }> = {}
+  for (const flag of KNOWN_GLOBAL_FLAGS) {
+    if (skip.has(flag)) continue
+    options[flag] = { type: booleans.has(flag) ? "boolean" : "string", hidden: true }
+  }
+  return options
+}
+
+/** The logging flags `cz-cli serve` accepts, mirroring upstream's root parser. */
+export interface ServeLogFlags {
+  "print-logs"?: boolean
+  "log-level"?: string
+  pure?: boolean
+}
+
+/**
+ * cz_change: wire `cz-cli serve`'s logging flags to the env vars opencode reads.
+ *
+ * These three are declared on upstream's ROOT parser (opencode's index.ts), which
+ * `cz-cli serve` never goes through, so before this they were accepted and did
+ * nothing — and could not be rejected either, because turning on .strict() without
+ * declaring them would have failed a documented invocation. Exported so a test can
+ * assert the wiring without starting a server.
+ */
+export function applyServeLogFlags(flags: ServeLogFlags): void {
+  if (flags["print-logs"]) process.env.OPENCODE_PRINT_LOGS = "1"
+  if (flags["log-level"]) process.env.OPENCODE_LOG_LEVEL = String(flags["log-level"])
+  if (flags.pure) process.env.OPENCODE_PURE = "1"
+}
+
 export async function main(args: string[], agentRuntime = false): Promise<number> {
   // cz_change: apply the base opencode env injection (kill upstream auto-updater,
   // disable repo-local project config, telemetry defaults) at the very top of main()
@@ -118,11 +161,35 @@ export async function main(args: string[], agentRuntime = false): Promise<number
     ])
     await yargs(args)
       .scriptName("cz-cli")
+      // cz_change: same invariant as src/cli.ts — yargs' built-in messages must
+      // not localize to the shell's LANG, or a caller parsing them (and
+      // test/robustness.test.ts) sees Chinese on a zh_CN machine.
+      .locale("en")
       .help("help", "show help")
       .alias("help", "h")
       .version("version", "show version number", InstallationVersion)
       .alias("version", "v")
       .command(ServeCommand)
+      // cz_change: these three belong to upstream's ROOT parser (opencode's
+      // index.ts), which `cz-cli serve` never goes through — so they used to be
+      // accepted and do nothing. Declared here, wired to the same env vars
+      // upstream's middleware sets, which is also what lets .strict() below reject
+      // a real typo: `serve --prot 8080` silently started on the default port
+      // (which is 0, i.e. a random one) instead of reporting the flag.
+      .option("print-logs", { type: "boolean", describe: "print logs to stderr" })
+      .option("log-level", { type: "string", choices: ["DEBUG", "INFO", "WARN", "ERROR"], describe: "log level" })
+      .option("pure", { type: "boolean", describe: "run without external plugins" })
+      // cz_change: `serve` is in run-cli.ts's RUNTIME_COMMANDS, so the outer layer has
+      // ALREADY read the cz global flags off this same argv — the connection ones
+      // select the lakehouse the served agent connects as (via ConnectionEnv), and
+      // `--format` is re-inserted after the command word by normalizeCliArgs. They all
+      // still arrive here, so .strict() below would reject invocations that work
+      // today. Declared from the CLI's own list rather than by hand so the two cannot
+      // drift, hidden and unused because the values are consumed before this parser
+      // ever sees them — the same thing runLlm does for `--profile`.
+      .options(serveInheritedGlobals())
+      .middleware((opts) => applyServeLogFlags(opts as ServeLogFlags), true)
+      .strict()
       .demandCommand(1, "")
       .parseAsync()
     return (process.exitCode as number) ?? 0
@@ -291,6 +358,10 @@ export async function main(args: string[], agentRuntime = false): Promise<number
   const cli = yargs(agentArgs)
     .parserConfiguration({ "populate--": true })
     .scriptName("cz-cli agent")
+    // cz_change: pin English, as src/cli.ts does. Without it the agent subtree
+    // answered `agent session list --format csv` with "无效的选项值：…" on a
+    // zh_CN machine while the rest of the CLI stayed English.
+    .locale("en")
     .wrap(100)
     .help("help", "show help")
     .alias("help", "h")
diff --git a/packages/cz-cli/src/cli.ts b/packages/cz-cli/src/cli.ts
index 78a05ef2cd..7cfe805df7 100644
--- a/packages/cz-cli/src/cli.ts
+++ b/packages/cz-cli/src/cli.ts
@@ -1,9 +1,10 @@
 import yargs from "yargs"
 import { VERSION } from "./version.js"
-import { defaultFormat, outputState, parseOutputArgs, renderOutput } from "./output/index.js"
+import { HandledCliError, defaultFormat, outputState, parseOutputArgs, renderErrorOutput } from "./output/index.js"
 import { withClickZettaProfileOption } from "./clickzetta-profile-option.js"
 import { suggestClosest } from "./suggest.js"
 import { SubcommandHelpShown } from "./subcommand-help.js"
+import { UsageError } from "./usage-error.js"
 
 export interface GlobalArgs {
   profile?: string
@@ -38,25 +39,106 @@ const JSON_ARRAY_OPTIONS = new Set(["--output-tables"])
 export const KNOWN_GLOBAL_FLAGS = ["profile", "p", "jdbc", "pat", "username", "password", "service", "protocol", "instance", "workspace", "schema", "s", "vcluster", "format", "field", "debug", "d", "help", "h", "version", "v", "target", "t"]
 export const KNOWN_TOP_COMMANDS = ["sql", "schema", "table", "workspace", "workspace-param", "status", "auth", "login", "profile", "task", "runs", "attempts", "job", "agent", "serve", "setup", "update", "datasource", "ai-gateway", "analytics-agent", "dqc", "mcp"]
 
+/**
+ * Collapse a repeated scalar option to its last occurrence, leaving options
+ * declared `array: true` alone. See the call site in createCli for why.
+ *
+ * Typed loosely and passed as `never`: yargs' published MiddlewareFunction type
+ * takes only argv, while the runtime also hands in the yargs instance — which is
+ * the only way to learn what the CURRENT subcommand declared as an array.
+ */
+function collapseDuplicateScalars(argv: Record<string, unknown>, instance: unknown): void {
+  const declaredArrays = new Set<string>(readDeclaredArrayKeys(instance))
+  for (const [key, value] of Object.entries(argv)) {
+    // `_` and `--` are yargs' operand lists and `$0` is the script name: all three
+    // are arrays by definition, never a repeated option.
+    if (key === "_" || key === "$0" || key === "--") continue
+    if (Array.isArray(value) && !declaredArrays.has(key) && value.length > 1) {
+      argv[key] = value[value.length - 1]
+    }
+  }
+}
+
+/** yargs' list of keys declared `array: true` on the instance in scope. */
+function readDeclaredArrayKeys(instance: unknown): string[] {
+  try {
+    const options = (instance as { getOptions?: () => Record<string, unknown> } | undefined)?.getOptions?.()
+    const keys = options?.array
+    return Array.isArray(keys) ? keys.filter((key): key is string => typeof key === "string") : []
+  } catch {
+    return []
+  }
+}
+
+function isNaNValue(value: unknown): boolean {
+  if (typeof value === "number") return Number.isNaN(value)
+  return Array.isArray(value) && value.some((item) => typeof item === "number" && Number.isNaN(item))
+}
+
+/** `pageSize` → `page-size`, so the error names the flag the user typed. */
+function kebab(key: string): string {
+  return key.replace(/[A-Z]/g, (upper) => `-${upper.toLowerCase()}`)
+}
+
+/** Does `text` begin a JSON array/object literal? */
+function startsJson(text: string): boolean {
+  const trimmed = text.trimStart()
+  return trimmed.startsWith("[") || trimmed.startsWith("{")
+}
+
+/**
+ * Is every bracket `text` opened closed again, ending outside a string? Only what
+ * the fragment merging below needs — "is this value still incomplete", not "is this
+ * valid JSON", which JSON.parse decides later in the command.
+ */
+function isClosedJson(text: string): boolean {
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (const char of text) {
+    if (escaped) { escaped = false; continue }
+    if (inString) {
+      if (char === "\\") escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') inString = true
+    else if (char === "[" || char === "{") depth++
+    else if (char === "]" || char === "}") depth--
+  }
+  return !inString && depth === 0
+}
+
 export function coalesceJsonArrayOptionArgs(args: string[]): string[] {
   const result: string[] = []
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!
     const isLongForm = JSON_ARRAY_OPTIONS.has(arg)
-    const isEqForm = !isLongForm && [...JSON_ARRAY_OPTIONS].some((name) => arg.startsWith(name + "="))
+    const eqName = isLongForm ? undefined : [...JSON_ARRAY_OPTIONS].find((name) => arg.startsWith(name + "="))
+    if (!isLongForm && !eqName) {
+      result.push(arg)
+      continue
+    }
     // Long form needs a value token that is not itself a flag; otherwise leave it for yargs.
-    if (!isEqForm && (!isLongForm || args[i + 1] === undefined || args[i + 1]!.startsWith("-"))) {
+    if (isLongForm && (args[i + 1] === undefined || args[i + 1]!.startsWith("-"))) {
       result.push(arg)
       continue
     }
-    let value = isLongForm ? args[i + 1]! : arg
+    const prefix = eqName ? `${eqName}=` : ""
+    let value = eqName ? arg.slice(prefix.length) : args[i + 1]!
     let j = isLongForm ? i + 2 : i + 1
-    while (j < args.length && !args[j]!.startsWith("-")) {
+    // Absorb following tokens only while the value is an UNCLOSED JSON literal.
+    // Merging every non-flag token instead ate the command's own positional:
+    // `--output-tables '[{"a": 1}]' mytask` (quotes stripped by the caller, so the
+    // JSON arrives split on its inner space) swallowed `mytask`, and the command
+    // then failed with "Not enough non-option arguments". A value that never
+    // started a JSON literal absorbs nothing at all.
+    while (j < args.length && !args[j]!.startsWith("-") && startsJson(value) && !isClosedJson(value)) {
       value += args[j]!
       j++
     }
     if (isLongForm) result.push(arg, value)
-    else result.push(value)
+    else result.push(prefix + value)
     i = j - 1
   }
   return result
@@ -158,6 +240,38 @@ export function createCli(args: string[]) {
       hidden: true,
       default: false,
     })
+    // Repeating a scalar option is a user slip, and yargs' answer to it is an
+    // ARRAY: `--field a --field b` reached extractField as ["a","b"] and crashed
+    // on field.replace, `--protocol http --protocol https` crashed in
+    // normalizeProtocol, and `--profile p1 --profile p2` silently resolved to no
+    // profile at all. Collapse to last-wins here — the GNU convention — but only
+    // for options NOT declared `array: true`, of which this CLI has 15 (`--set`,
+    // `--variable`, `--header`, …) that must keep collecting. yargs' global
+    // `duplicate-arguments-array: false` cannot make that distinction: it would
+    // reduce those to their last element too.
+    //
+    // Runs before validation so `choices` sees the scalar, and takes the yargs
+    // instance from the middleware's 2nd argument, which in a subcommand reports
+    // that subcommand's own declarations.
+    .middleware(collapseDuplicateScalars as never, /* applyBeforeValidation */ true)
+    // A `type: "number"` option fed a non-number becomes NaN, and nothing else in
+    // the CLI checks: `task cron-preview '0 0 * * *' --count abc` answered "0
+    // upcoming runs" for a valid cron, and paginated commands sent `null` for a
+    // page. NaN can only originate from a number-typed option, so no schema is
+    // needed here — a NaN in argv IS a rejected value. check() reports through
+    // the fail handler, i.e. USAGE_ERROR with exit 2, like any other bad value.
+    .check((argv) => {
+      const invalid = new Set<string>()
+      for (const [key, value] of Object.entries(argv)) {
+        if (key === "_" || key === "$0" || key === "--") continue
+        if (isNaNValue(value)) invalid.add(kebab(key))
+      }
+      if (invalid.size > 0) {
+        const names = [...invalid].map((name) => `--${name}`).join(", ")
+        throw new UsageError(`Invalid number value for: ${names}`)
+      }
+      return true
+    })
     .middleware((argv) => {
       const rawArgs = args.map(a => String(a))
       const hasExplicitFormat = rawArgs.some(
@@ -168,7 +282,11 @@ export function createCli(args: string[]) {
     }, /* applyBeforeValidation */ true)
     .strict()
     .fail((msg, err, failYargs) => {
-      if (err) throw err
+      // Our own validators (see the check() above) report through UsageError so
+      // they get the USAGE_ERROR envelope; anything else is a real exception and
+      // must keep propagating rather than being relabelled as bad usage.
+      if (err && !(err instanceof UsageError)) throw err
+      if (err instanceof UsageError) msg = err.message
       // Defensive net: a group built with raw `.demandCommand()` (no commandGroup
       // fail handler of its own, e.g. mcp / some agent.ts subtrees) bubbles its
       // "Missing subcommand for 'X'" failure straight up here. Resolve it like
@@ -180,6 +298,10 @@ export function createCli(args: string[]) {
         failYargs.showHelp((help: string) => process.stdout.write(help + "\n"))
         throw new SubcommandHelpShown()
       }
+      // A UsageError carries OUR message, already complete. Running it through the
+      // scan below could append "Did you mean '--limit'?" to a message about a
+      // perfectly valid flag, because the scan only looks at the raw tokens.
+      const selfReported = err instanceof UsageError
       const KNOWN_FLAGS = KNOWN_GLOBAL_FLAGS
       const KNOWN_COMMANDS = KNOWN_TOP_COMMANDS
       const knownFlagSet = new Set(KNOWN_FLAGS)
@@ -190,13 +312,15 @@ export function createCli(args: string[]) {
       let badToken: string | undefined
       let suggestion: string | undefined
       let isFlag = false
-      const unknownFlags = args.filter((a) => a.startsWith("-")).map((a) => a.replace(/^-+/, "").split("=")[0]).filter((a) => a && !knownFlagSet.has(a))
+      const unknownFlags = selfReported
+        ? []
+        : args.filter((a) => a.startsWith("-")).map((a) => a.replace(/^-+/, "").split("=")[0]).filter((a) => a && !knownFlagSet.has(a))
       if (unknownFlags.length > 0) {
         isFlag = true
         badToken = unknownFlags[0]
         const hit = suggestClosest(badToken!, KNOWN_FLAGS.filter((f) => f.length > 1))
         if (hit) suggestion = `--${hit}`
-      } else {
+      } else if (!selfReported) {
         const topLevelCmd = args.find((a) => !a.startsWith("-"))
         if (topLevelCmd !== undefined && !knownCommandSet.has(topLevelCmd)) {
           badToken = topLevelCmd
@@ -215,12 +339,18 @@ export function createCli(args: string[]) {
       const outputArgs = parseOutputArgs(args)
       const errorObj: Record<string, unknown> = { code: "USAGE_ERROR", message }
       if (suggestion) errorObj.did_you_mean = suggestion
-      const output = renderOutput({
+      // renderErrorOutput, not renderOutput: a usage error must look like every
+      // other error in the chosen format — `ERROR USAGE_ERROR: …` under
+      // text/csv/table/jsonl, JSON under json/pretty/toon.
+      const output = renderErrorOutput({
         error: errorObj,
         ai_message: aiMessage,
       }, outputArgs.format, outputArgs.field)
       process.stdout.write(output + "\n")
       process.exitCode = 2
-      throw new Error(msg ?? "usage error")
+      // HandledCliError, not a bare Error: the envelope above IS the report, and a
+      // catch further out (runCliWithTracking's last-resort envelope, runLlm's
+      // stderr line) must be able to tell "already reported" from a real exception.
+      throw new HandledCliError("USAGE_ERROR", message)
     })
 }
diff --git a/packages/cz-cli/src/command-group.ts b/packages/cz-cli/src/command-group.ts
index f1575abb05..1922f447dc 100644
--- a/packages/cz-cli/src/command-group.ts
+++ b/packages/cz-cli/src/command-group.ts
@@ -1,8 +1,9 @@
 import type { Argv } from "yargs"
 import { suggestClosest } from "./suggest.js"
-import { parseOutputArgs, renderOutput } from "./output/index.js"
+import { HandledCliError, parseOutputArgs, renderErrorOutput } from "./output/index.js"
 import { KNOWN_GLOBAL_FLAGS, INVOCATION_ARGS_KEY } from "./cli.js"
 import { SubcommandHelpShown } from "./subcommand-help.js"
+import { UsageError } from "./usage-error.js"
 
 // Re-exported so the opencode agent runtime (which imports commandGroup from
 // this module) can catch the sentinel at its own parse boundaries. See
@@ -32,7 +33,10 @@ export function commandGroup<T>(yargs: Argv<T>, commandName: string): Argv<T> {
     .strictCommands()
     .strictOptions()
     .fail((msg, err, failYargs) => {
-      if (err) throw err
+      // See cli.ts's fail handler: UsageError is our own validation speaking, so
+      // it renders as USAGE_ERROR; every other error keeps propagating.
+      if (err && !(err instanceof UsageError)) throw err
+      if (err instanceof UsageError) msg = err.message
 
       // A bare group invocation (`cz-cli ai-gateway`, `cz-cli ai-gateway key`)
       // is not a user error — the caller has not yet chosen a subcommand. Treat
@@ -94,13 +98,16 @@ export function commandGroup<T>(yargs: Argv<T>, commandName: string): Argv<T> {
       const errorObj: Record<string, unknown> = { code: "USAGE_ERROR", message: displayMsg }
       if (suggestion) errorObj.did_you_mean = suggestion
       const outputArgs = parseOutputArgs(outputArgsSource)
-      const output = renderOutput({
+      // Same renderer error() uses, so a usage error and a business error have
+      // one shape per format (see renderErrorOutput's docstring).
+      const output = renderErrorOutput({
         error: errorObj,
         ai_message: finalAi,
       }, outputArgs.format, outputArgs.field)
       process.stdout.write(output + "\n")
       process.exitCode = 2
-      throw new Error(displayMsg)
+      // See cli.ts's fail handler: the marker says "already reported".
+      throw new HandledCliError("USAGE_ERROR", displayMsg)
     })
     .demandCommand(1, humanMsg)
 }
diff --git a/packages/cz-cli/src/commands/agent-llm.ts b/packages/cz-cli/src/commands/agent-llm.ts
index a03e7cfac6..7e76a48173 100644
--- a/packages/cz-cli/src/commands/agent-llm.ts
+++ b/packages/cz-cli/src/commands/agent-llm.ts
@@ -1,6 +1,7 @@
 import type { Argv, CommandModule } from "yargs"
 import { ModelsCommand } from "opencode/cli/cmd/models"
-import { commandGroup } from "../command-group.js"
+import { commandGroup, SubcommandHelpShown } from "../command-group.js"
+import { isHandledCliError } from "../output/index.js"
 import {
   clearActiveModel,
   readLlmEntries,
@@ -857,6 +858,9 @@ export async function runLlm(args: readonly string[]): Promise<never> {
   try {
     await yargs(args)
       .scriptName("cz-cli agent")
+      // cz_change: pin English, as src/cli.ts does — this subtree runs on its own
+      // parser and used to localize its usage errors to the shell's LANG.
+      .locale("en")
       // cz_change: `llm` runs on its own parser (runtime.ts dispatches to it before
       // the main agent yargs is built), so the global --profile/-p must be declared
       // here too or it fails as an unknown option. It is not decorative: the
@@ -890,8 +894,19 @@ export async function runLlm(args: readonly string[]): Promise<never> {
       .help("help", "show help")
       .alias("help", "h")
       .parseAsync()
-  } catch (error) {
-    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`)
+  } catch (err) {
+    // A bare group (`cz-cli agent llm`) renders its own help and throws this
+    // sentinel: help was SHOWN, so it exits 0 like every other group in the CLI.
+    // It used to land in the generic branch below and print
+    // "Error: subcommand help shown" with exit 1.
+    if (err instanceof SubcommandHelpShown) process.exit(0)
+    // commandGroup's fail handler has already written the USAGE_ERROR envelope and
+    // set the exit code; repeating the message on stderr just double-reports it.
+    // Keyed on the error being MARKED as reported, not on `process.exitCode` being
+    // set — a subcommand that reports one failure through error() and then throws
+    // something unrelated would otherwise exit silently on both streams.
+    if (isHandledCliError(err)) process.exit((process.exitCode as number) || 1)
+    process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`)
     process.exit(1)
   }
   process.exit(0)
diff --git a/packages/cz-cli/src/commands/analytics-agent.ts b/packages/cz-cli/src/commands/analytics-agent.ts
index 7c42453b1e..68fd861599 100644
--- a/packages/cz-cli/src/commands/analytics-agent.ts
+++ b/packages/cz-cli/src/commands/analytics-agent.ts
@@ -1114,6 +1114,9 @@ async function runBatchStatusChange(
     logOperation(name, { ok: failed === 0, timeMs: Date.now() - t0 })
     success(
       { total: targets.length, succeeded, failed, skipped, results },
+      // No rowsKey: total/succeeded/failed/skipped are the summary this command
+      // reports, and a projected list drops its scalar siblings — same reasoning as
+      // `datasource check`.
       { format, timeMs: Date.now() - t0 },
     )
     // success() resets exitCode to EXIT_OK; override AFTER it so a partial
diff --git a/packages/cz-cli/src/commands/auth.ts b/packages/cz-cli/src/commands/auth.ts
index 283f071853..b02d83fca9 100644
--- a/packages/cz-cli/src/commands/auth.ts
+++ b/packages/cz-cli/src/commands/auth.ts
@@ -200,7 +200,15 @@ function runList(argv: GlobalArgs): void {
       }
     })
 
-    success({ sessions, active_session: activeSession ?? null, active_profile: activeProfile ?? null }, { format })
+    // `rowsKey` tells the row-oriented formats (text/table/csv/jsonl) that the
+    // sessions array is the table, which is what `--format text` used to get wrong
+    // — it printed one row whose first cell was the whole list as JSON. The JSON
+    // shape stays exactly as it was, so `.data.sessions` and `--field sessions`
+    // keep working; reshaping the payload instead would have broken both.
+    success(
+      { sessions, active_session: activeSession ?? null, active_profile: activeProfile ?? null },
+      { format, rowsKey: "sessions" },
+    )
   } catch (err) {
     error("INTERNAL_ERROR", err instanceof Error ? err.message : String(err), { format })
   }
diff --git a/packages/cz-cli/src/commands/datasource.ts b/packages/cz-cli/src/commands/datasource.ts
index a7452a6caa..9f9632c799 100644
--- a/packages/cz-cli/src/commands/datasource.ts
+++ b/packages/cz-cli/src/commands/datasource.ts
@@ -578,6 +578,9 @@ export function registerDatasourceCommand(cli: Argv<GlobalArgs>): void {
                     ? `Datasource type ${dsType} does not require CDC prerequisite checks.`
                     : `${ds.name} CDC prerequisites met. Proceed to: cz-cli task create-realtime-sync <name> --folder <folder> --source ${ds.name} --database <db> --target <lakehouse_ds>`)
               : result.message
+            // No rowsKey: `ready` is the verdict this command exists to deliver, and a
+            // projected list drops its scalar siblings. One row carrying the verdict
+            // beats a table of checks with no overall answer.
             success({ datasource: ds.name, ds_type: dsType, checks: result.checks, ready: result.ok }, {
               format, aiMessage: aiMsg,
             })
diff --git a/packages/cz-cli/src/commands/profile-bootstrap.ts b/packages/cz-cli/src/commands/profile-bootstrap.ts
index ace44aed5a..dde80e1723 100644
--- a/packages/cz-cli/src/commands/profile-bootstrap.ts
+++ b/packages/cz-cli/src/commands/profile-bootstrap.ts
@@ -722,6 +722,9 @@ export function registerBootstrapCommands(yargs: Argv<GlobalArgs>): void {
           }
 
           logOperation("profile list-workspaces", { ok: true })
+          // No rowsKey: `workspaces_by_instance` is what list-workspaces answers, and
+          // projecting `instances` would drop it from every row format. Reshaping to
+          // one row per instance x workspace is the real fix and is out of scope here.
           success({ region: target, instances: targetInstances, workspaces_by_instance: workspacesByInstance }, { format })
         } catch (err) {
           logOperation("profile list-workspaces", { ok: false, errorCode: "BOOTSTRAP_ERROR" })
diff --git a/packages/cz-cli/src/commands/schema.ts b/packages/cz-cli/src/commands/schema.ts
index 6b0ec2e7ec..d728a690bf 100644
--- a/packages/cz-cli/src/commands/schema.ts
+++ b/packages/cz-cli/src/commands/schema.ts
@@ -75,7 +75,7 @@ export function registerSchemaCommand(cli: Argv<GlobalArgs>): void {
             const tableRecords = tableResult ? rowsToRecords(tableResult) : []
             const tables = tableRows.map((row, index) => getShowTableName(row, tableRecords[index] ?? {}))
             logOperation("schema describe", { sql: infoSql, ok: true, timeMs: Date.now() - t0 })
-            success({ name, type: schemaType, table_count: tables.length, tables }, { format, timeMs: Date.now() - t0 })
+            success({ name, type: schemaType, table_count: tables.length, tables }, { format, rowsKey: "tables", timeMs: Date.now() - t0 })
           } catch (err) {
             const { code: _ec, message: _em, aiMessage: _ea } = classifyExecError(err)
             error(_ec, _em, { format , ...(_ea && { aiMessage: _ea }) }); return
diff --git a/packages/cz-cli/src/commands/sql.ts b/packages/cz-cli/src/commands/sql.ts
index 43d197073e..f0061d7504 100644
--- a/packages/cz-cli/src/commands/sql.ts
+++ b/packages/cz-cli/src/commands/sql.ts
@@ -2,7 +2,7 @@ import type { Argv } from "yargs"
 import { readFileSync, openSync, readSync, closeSync } from "node:fs"
 import { splitSql, stripLeadingComment, JobStatus, request, requestRaw, getCurrentUser, type ClientOptions, type JobID, type QueryResult } from "@clickzetta/sdk"
 import type { GlobalArgs } from "../cli.js"
-import { success, successRows, error, parseOutputArgs, renderOutput } from "../output/index.js"
+import { success, successRows, error, handledError, parseOutputArgs, renderOutput, renderErrorOutput } from "../output/index.js"
 import { maskRows } from "../output/masking.js"
 import { logOperation } from "../logger.js"
 import { getExecContext, execSql, execSqlWithRetry, isQueryResult, validateIdentifier, classifyExecError, type ExecContext } from "./exec.js"
@@ -24,6 +24,8 @@ const DEFAULT_ROW_LIMIT = 100
 
 interface SqlArgs extends GlobalArgs {
   statement?: string
+  /** yargs' operand list: the command word, then anything after `--`. */
+  _?: unknown[]
   write: boolean
   "with-schema": boolean
   "truncate": boolean
@@ -234,9 +236,33 @@ async function applyUseStatement(
 }
 
 function resolveSql(argv: SqlArgs): string {
-  if (argv.file) return readFileSync(argv.file, "utf-8")
-  if (argv.execute) return argv.execute
+  // Priority is the one this command's own --help documents:
+  //   positional > -e/--execute > -f/--file > --stdin
+  // It used to read --file first, so `cz-cli sql "select 1" -f other.sql` silently
+  // ran the file and ignored the statement the user typed.
   if (argv.statement) return argv.statement
+  // Operands after `--`: the escape hatch for a statement that starts with `-`.
+  // yargs appends them to `_` after the command word, where no declared positional
+  // picks them up — hence reading them here. Deliberately NOT via yargs'
+  // `populate--`, which diverts them into `argv["--"]` for the WHOLE tree and would
+  // stop `cz-cli profile create -- myname` from binding its positional.
+  const operands = Array.isArray(argv._) ? argv._.slice(1).map(String) : []
+  if (operands.length > 0) return operands.join(" ")
+  if (argv.execute) return argv.execute
+  if (argv.file) {
+    try {
+      return readFileSync(argv.file, "utf-8")
+    } catch (err) {
+      // An unreadable path is a user error with a name, not an ENOENT stack: this
+      // read sits outside the handler's try, so the exception used to escape and
+      // print nothing on stdout at all.
+      handledError(
+        "FILE_READ_ERROR",
+        `Cannot read SQL from --file '${argv.file}': ${err instanceof Error ? err.message : String(err)}`,
+        { format: argv.format },
+      )
+    }
+  }
   if (argv.stdin || !process.stdin.isTTY) {
     const chunks: Buffer[] = []
     const fd = openSync("/dev/stdin", "r")
@@ -568,7 +594,9 @@ async function handler(argv: SqlArgs): Promise<void> {
   const sigintHandler = () => {
     const payload: Record<string, unknown> = { error: { code: "ABORTED", message: "Execution interrupted by user." } }
     if (currentJobId) payload.job_id = currentJobId
-    process.stdout.write(renderOutput(payload, format, parseOutputArgs(process.argv.slice(2)).field) + "\n")
+    // renderErrorOutput, like every other failure: under a row format this is
+    // `ERROR ABORTED: …` rather than a JSON blob (see its docstring).
+    process.stdout.write(renderErrorOutput(payload, format, parseOutputArgs(process.argv.slice(2)).field) + "\n")
     process.exit(130)
   }
   process.on("SIGINT", sigintHandler)
@@ -596,7 +624,7 @@ async function handler(argv: SqlArgs): Promise<void> {
           return { sql: stmt, status: "error", error: await formatClassifiedError({ code, message, ctx: dryRunCtx, profileName: argv.profile }) }
         }
       }))
-      success({ statements: results, count: statements.length }, { format })
+      success({ statements: results, count: statements.length }, { format, rowsKey: "statements" })
       return
     }
     ctx = await getExecContext(argv)
@@ -743,7 +771,8 @@ export function registerSqlCommand(cli: Argv<GlobalArgs>): void {
                 "  cz-cli sql -f query.sql --no-limit",
                 "  cz-cli sql \"SELECT * FROM huge_table\" --async",
                 "",
-                "SQL input priority: positional > -e/--execute > -f/--file > --stdin",
+                "SQL input priority: positional > `--` operands > -e/--execute > -f/--file > --stdin",
+                "  Use `--` when the statement itself starts with a dash: cz-cli sql -- \"-- note\\nSELECT 1\"",
                 "Default mode is sync (waits for results). Use --async for large/long-running queries.",
                 "",
                 "Statement splitting is on by default. To submit SQL verbatim when a single",
diff --git a/packages/cz-cli/src/commands/status.ts b/packages/cz-cli/src/commands/status.ts
index b829c175ca..a60f2197c7 100644
--- a/packages/cz-cli/src/commands/status.ts
+++ b/packages/cz-cli/src/commands/status.ts
@@ -2,7 +2,7 @@ import type { Argv } from "yargs"
 import { JobStatus } from "@clickzetta/sdk"
 import type { GlobalArgs } from "../cli.js"
 import { VERSION } from "../version.js"
-import { success } from "../output/index.js"
+import { EXIT_BIZ_ERROR, success } from "../output/index.js"
 import { logOperation } from "../logger.js"
 import { getExecContext, execSql, isQueryResult } from "./exec.js"
 
@@ -22,14 +22,30 @@ export function registerStatusCommand(cli: Argv<GlobalArgs>): void {
           execSql(ctx, "SELECT current_schema()"),
         ])
 
-        const workspace =
-          isQueryResult(wsResult) && wsResult.status === JobStatus.SUCCEEDED && wsResult.rows[0]
-            ? wsResult.rows[0][0]
-            : null
-        const schema =
-          isQueryResult(schemaResult) && schemaResult.status === JobStatus.SUCCEEDED && schemaResult.rows[0]
-            ? schemaResult.rows[0][0]
-            : null
+        // A probe that came back FAILED does not throw — it returns a result whose
+        // status says so. Reporting `connected: true` with null fields for that case
+        // claimed a working connection on the strength of a query that did not work,
+        // which is the same misreport the exit code below used to make.
+        const failure = [wsResult, schemaResult].find(
+          (result) => !isQueryResult(result) || result.status !== JobStatus.SUCCEEDED,
+        )
+        if (failure !== undefined) {
+          const reason = isQueryResult(failure)
+            ? (failure.errorMessage ?? `Probe query returned ${failure.status}`)
+            : "Probe query returned an unexpected result"
+          logOperation("status", { ok: false, errorCode: "CONNECTION_ERROR", timeMs: Date.now() - t0 })
+          success(
+            // workspace/schema stay present as null so all three outcomes have one
+            // payload shape and `--field workspace` keeps answering.
+            { connected: false, error: reason, workspace: null, schema: null, cli_version: VERSION, time_ms: Date.now() - t0 },
+            { format },
+          )
+          process.exitCode = EXIT_BIZ_ERROR
+          return
+        }
+
+        const workspace = isQueryResult(wsResult) && wsResult.rows[0] ? wsResult.rows[0][0] : null
+        const schema = isQueryResult(schemaResult) && schemaResult.rows[0] ? schemaResult.rows[0][0] : null
 
         logOperation("status", { ok: true, timeMs: Date.now() - t0 })
         success(
@@ -45,15 +61,24 @@ export function registerStatusCommand(cli: Argv<GlobalArgs>): void {
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err)
         logOperation("status", { ok: false, errorCode: "CONNECTION_ERROR", timeMs: Date.now() - t0 })
+        // The payload stays a data envelope — `connected: false` plus the reason IS
+        // the answer to "what is the status", not a failure to answer — but the EXIT
+        // CODE now reports the outcome, so `cz-cli status && <next step>` stops on a
+        // dead connection instead of continuing. Same contract as pg_isready.
         success(
           {
             connected: false,
             error: msg,
+            // Present as null, like the other two outcomes: one payload shape means
+            // `--field workspace` answers whatever happened.
+            workspace: null,
+            schema: null,
             cli_version: VERSION,
             time_ms: Date.now() - t0,
           },
           { format },
         )
+        process.exitCode = EXIT_BIZ_ERROR
       }
     },
   )
diff --git a/packages/cz-cli/src/commands/task.ts b/packages/cz-cli/src/commands/task.ts
index d0f1891ce3..334d0de8f1 100644
--- a/packages/cz-cli/src/commands/task.ts
+++ b/packages/cz-cli/src/commands/task.ts
@@ -506,7 +506,7 @@ function registerCdcCommands(cdcYargs: Argv<GlobalArgs>): Argv<GlobalArgs> {
             pageSize: argv["page-size"] as number,
           })
           logOperation("task cdc list", { ok: true })
-          success({ tasks: resp.data }, { format })
+          success({ tasks: resp.data }, { format, rowsKey: "tasks" })
         } catch (err) {
           reportTaskError(err, format)
         }
@@ -535,7 +535,7 @@ function registerCdcCommands(cdcYargs: Argv<GlobalArgs>): Argv<GlobalArgs> {
             pageSize: argv["page-size"] as number,
           })
           logOperation("task cdc tables", { ok: true })
-          success({ task_id: fileId, tables: resp.data }, { format })
+          success({ task_id: fileId, tables: resp.data }, { format, rowsKey: "tables" })
         } catch (err) {
           reportTaskError(err, format)
         }
@@ -4202,6 +4202,7 @@ export function registerTaskCommand(cli: Argv<GlobalArgs>): void {
             logOperation("task cron-preview", { ok: true })
             success({ cron: cronExpress, next_runs, count: next_runs.length }, {
               format,
+              rowsKey: "next_runs",
               aiMessage: `Next ${next_runs.length} scheduled run times for cron: ${cronExpress}`,
             })
           } catch (err) {
diff --git a/packages/cz-cli/src/connection/config.ts b/packages/cz-cli/src/connection/config.ts
index 57ae63a2eb..5f2f8a5382 100644
--- a/packages/cz-cli/src/connection/config.ts
+++ b/packages/cz-cli/src/connection/config.ts
@@ -27,6 +27,28 @@ export function resolveConnectionConfig(cliArgs: Partial<CliArgs> = {}): Connect
   // which is a second, easy-to-miss place that formula could drift from
   // Profile.current()'s (see commands/workspace.ts's history for exactly that).
   const profileName = cliArgs.profile ?? Profile.current()
+  // A profile the caller NAMED but that does not exist is a typo, and it used to
+  // pass silently: the entry read as undefined, every field fell back to env or
+  // defaults, and the user was told "Authentication required. Run cz-cli auth
+  // login" — sending them to re-authenticate over a misspelled name. The
+  // NO_PROFILE gate cannot catch this; it only asks whether profiles.toml has any
+  // [profiles.*] at all. `profile use <name>` has always reported this correctly,
+  // so the connection path now uses the same code.
+  // Deliberately only the EXPLICIT argument, not Profile.current():
+  //   - CZ_PROFILE is the CLI's own channel, and run-cli.ts checks it there for the
+  //     commands that connect. Throwing on it here would also hit the callers that
+  //     merely read a config — the TUI quota sidebar, gateway-prompt, agent-mcp,
+  //     studio-context — where an inherited stale value should degrade, not throw.
+  //   - a stale `default_profile` is the tool's own bookkeeping, not a user typo, and
+  //     wants a different message; it stays out of scope rather than being reported
+  //     as if the caller had named it.
+  const requestedProfile = cliArgs.profile
+  if (requestedProfile && !readProfileEntry(requestedProfile)) {
+    throw new InterfaceError(
+      `Profile '${requestedProfile}' not found in ~/.clickzetta/profiles.toml. Run \`cz-cli profile list\` to see the configured profiles.`,
+      { code: "PROFILE_NOT_FOUND" },
+    )
+  }
   const profileCfg = getProfileConfig(profileName) ?? (profileName ? undefined : getProfileConfig())
   const ambient = ConnectionEnv.read()
   const jdbcCfg = cliArgs.jdbcUrl ? parseJdbcUrl(cliArgs.jdbcUrl) : undefined
@@ -46,7 +68,13 @@ export function resolveConnectionConfig(cliArgs: Partial<CliArgs> = {}): Connect
   const nonAuthKeys = ["service", "protocol", "instance", "workspace", "schema", "vcluster"] as const
   for (const key of nonAuthKeys) {
     const val = cliArgs[key]
-    if (val !== undefined && val !== null) {
+    // An EMPTY value is not a value. `--workspace` with nothing after it (yargs
+    // hands us "") used to overwrite the profile's workspace with "", and the
+    // command then reported "Workspace is required. Provide --workspace or
+    // configure it in your profile" — about the flag the user had just passed.
+    // Treat it as absent, which is what every other CLI does with an empty
+    // operand, and let the profile keep its value.
+    if (val !== undefined && val !== null && String(val).trim() !== "") {
       cfg[key] = val
     }
   }
diff --git a/packages/cz-cli/src/main.ts b/packages/cz-cli/src/main.ts
index 3f400bd96c..2e1871064f 100755
--- a/packages/cz-cli/src/main.ts
+++ b/packages/cz-cli/src/main.ts
@@ -3,7 +3,7 @@
 import { checkAndUpdate } from "./auto-update.js"
 import { runCliWithTracking } from "./run-cli.js"
 import { createTraceparent } from "@clickzetta/sdk"
-import { parseOutputArgs, renderOutput } from "./output/index.js"
+import { parseOutputArgs, renderErrorOutput } from "./output/index.js"
 
 if (!process.env.CLICKZETTA_TRACEPARENT) {
   process.env.CLICKZETTA_TRACEPARENT = createTraceparent()
@@ -11,7 +11,9 @@ if (!process.env.CLICKZETTA_TRACEPARENT) {
 
 process.on("SIGINT", () => {
   const outputArgs = parseOutputArgs(process.argv.slice(2))
-  process.stdout.write(renderOutput({ error: { code: "ABORTED", message: "Operation aborted by user." } }, outputArgs.format, outputArgs.field) + "\n")
+  // renderErrorOutput, matching sql.ts's SIGINT handler and error(): one error shape
+  // per format, so Ctrl-C under --format text is an ERROR row like any other failure.
+  process.stdout.write(renderErrorOutput({ error: { code: "ABORTED", message: "Operation aborted by user." } }, outputArgs.format, outputArgs.field) + "\n")
   process.exit(130)
 })
 
diff --git a/packages/cz-cli/src/output/index.ts b/packages/cz-cli/src/output/index.ts
index aaef8e3934..dfddb8bf8a 100644
--- a/packages/cz-cli/src/output/index.ts
+++ b/packages/cz-cli/src/output/index.ts
@@ -27,6 +27,13 @@ export const outputState = { field: undefined as string | undefined }
 export interface OutputOptions {
   format?: string
   field?: string
+  /**
+   * Name of the field inside `data` that holds the list, for payloads that wrap
+   * a list next to some metadata (`{ tasks: [...] }`, `{ name, tables: [...] }`).
+   * Row-oriented formats (table/csv/text/jsonl) render that field as the rows;
+   * json/pretty/toon are untouched, so declaring it changes no JSON contract.
+   */
+  rowsKey?: string
   aiMessage?: string
   extra?: Record<string, unknown>
   debug?: boolean
@@ -54,7 +61,7 @@ export function success(
   if (opts?.extra) Object.assign(payload, opts.extra)
 
   const field = opts?.field ?? outputState.field
-  const output = renderOutput(payload, opts?.format, field)
+  const output = renderOutput(payload, opts?.format, field, opts?.rowsKey)
   if (output !== "") process.stdout.write(output + "\n")
   writeAiMessageToStderr(opts?.format, field, opts?.aiMessage)
   ;(process as unknown as Record<string, unknown>).responseBytes = Buffer.byteLength(output, "utf-8")
@@ -141,7 +148,7 @@ export function isHandledCliError(err: unknown): err is HandledCliError {
   return err instanceof HandledCliError
 }
 
-export function renderOutput(payload: unknown, format?: string, field?: string): string {
+export function renderOutput(payload: unknown, format?: string, field?: string, rowsKey?: string): string {
   // --field extraction: search top-level → data (dict) → data[0] (list) → rows[0]
   if (field && payload && typeof payload === "object") {
     const obj = payload as Record<string, unknown>
@@ -161,19 +168,26 @@ export function renderOutput(payload: unknown, format?: string, field?: string):
     case "toon":
       return formatToon(unwrapToonEnvelope(payload))
     case "table":
-      return emitAsTable(payload)
+      return emitRowFormat(payload, "table", rowsKey)
     case "csv":
-      return emitAsCsv(payload)
+      return emitRowFormat(payload, "csv", rowsKey)
     case "jsonl":
-      return emitAsJsonl(payload)
+      return emitRowFormat(payload, "jsonl", rowsKey)
     case "text":
-      return emitAsText(payload)
+      return emitRowFormat(payload, "text", rowsKey)
     default:
       return formatJson(payload)
   }
 }
 
-function renderErrorOutput(payload: unknown, format?: string, field?: string): string {
+/**
+ * Render an `{ error: … }` envelope. Row-oriented formats get a single
+ * `ERROR <code>: <message>` line instead of JSON, so a `--format text` consumer
+ * reads one shape for every failure. Exported because the yargs fail handlers
+ * (cli.ts, command-group.ts) render usage errors themselves rather than through
+ * error(); they must not diverge from it.
+ */
+export function renderErrorOutput(payload: unknown, format?: string, field?: string): string {
   if (!field && ROW_ONLY_FORMATS.has(format ?? "json") && payload && typeof payload === "object") {
     const err = (payload as Record<string, unknown>).error
     if (err && typeof err === "object") {
@@ -250,85 +264,134 @@ function unwrapToonEnvelope(payload: unknown): unknown {
   return payload
 }
 
-function emitAsTable(payload: unknown): string {
-  if (payload && typeof payload === "object") {
-    const obj = payload as Record<string, unknown>
-    const data = obj.data
-    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object" && data[0] !== null && !Array.isArray(data[0])) {
-      const columns = Object.keys(data[0] as Record<string, unknown>)
-      const rows = (data as Record<string, unknown>[]).map((r) => columns.map((c) => r[c]))
-      return formatTable(columns, rows)
-    }
-    if (Array.isArray(data) && data.length > 0) {
-      const rows = data.map((v) => [v === null || v === undefined ? "" : String(v)])
-      return formatTable(["value"], rows)
-    }
-    if (data && typeof data === "object" && !Array.isArray(data)) {
-      const columns = Object.keys(data as Record<string, unknown>)
-      const row = columns.map((c) => (data as Record<string, unknown>)[c])
-      return formatTable(columns, [row])
+/**
+ * Rows projected out of a result envelope for the row-oriented formats
+ * (table/csv/text/jsonl). `items` carries the original array when the rows came
+ * from one, so jsonl can emit those objects verbatim instead of rebuilding them.
+ */
+interface RowProjection {
+  columns: string[]
+  rows: unknown[][]
+  items?: unknown[]
+}
+
+function isRecordValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/** Every key seen across the records, in first-appearance order. */
+function unionColumns(records: Record<string, unknown>[]): string[] {
+  const columns: string[] = []
+  const seen = new Set<string>()
+  for (const record of records) {
+    for (const key of Object.keys(record)) {
+      if (seen.has(key)) continue
+      seen.add(key)
+      columns.push(key)
     }
   }
-  return formatPretty(payload)
+  return columns
 }
 
-function emitAsCsv(payload: unknown): string {
-  if (payload && typeof payload === "object") {
-    const obj = payload as Record<string, unknown>
-    const data = obj.data
-    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object" && data[0] !== null && !Array.isArray(data[0])) {
-      const columns = Object.keys(data[0] as Record<string, unknown>)
-      const rows = (data as Record<string, unknown>[]).map((r) => columns.map((c) => r[c]))
-      return formatCsv(columns, rows)
-    }
-    if (Array.isArray(data) && data.length > 0) {
-      const rows = data.map((v) => [v === null || v === undefined ? "" : String(v)])
-      return formatCsv(["value"], rows)
-    }
-    if (data && typeof data === "object" && !Array.isArray(data)) {
-      const columns = Object.keys(data as Record<string, unknown>)
-      const row = columns.map((c) => (data as Record<string, unknown>)[c])
-      return formatCsv(columns, [row])
-    }
+/** One array → one table. Records become columns; scalars become a single column. */
+function projectArray(items: unknown[], scalarColumn: string): RowProjection {
+  if (items.length > 0 && items.every(isRecordValue)) {
+    const records = items as Record<string, unknown>[]
+    const columns = unionColumns(records)
+    return { columns, rows: records.map((record) => columns.map((column) => record[column])), items }
   }
-  return formatPretty(payload)
+  return { columns: items.length > 0 ? [scalarColumn] : [], rows: items.map((value) => [value]), items }
 }
 
-function emitAsJsonl(payload: unknown): string {
-  if (payload && typeof payload === "object") {
-    const obj = payload as Record<string, unknown>
-    const rows = obj.rows
-    if (Array.isArray(rows)) {
-      const columns = Array.isArray(obj.columns) ? obj.columns.filter((value): value is string => typeof value === "string") : []
-      return formatJsonl(columns.length > 0 ? rowsToRecords(columns, rows as unknown[][]) : rows)
-    }
-    const data = obj.data
-    if (Array.isArray(data)) {
-      return formatJsonl(data)
-    }
+/**
+ * Keys a `columns` + `rows` envelope may carry and still BE that envelope. Anything
+ * else alongside them means the payload is a record that merely contains a grid:
+ * `sql --batch` writes `{ index, sql, columns, rows, count, time_ms, job_id? }` per
+ * statement, and treating that as the table dropped `index`/`sql`/`time_ms` — the
+ * only things telling a consumer which statement a grid belonged to — and rendered a
+ * DDL statement (no columns) as a blank line.
+ */
+const TABULAR_ENVELOPE_KEYS = new Set(["columns", "rows", "count", "time_ms", "ai_message"])
+
+function isTabularEnvelope(payload: Record<string, unknown>): boolean {
+  if (!Array.isArray(payload.columns) || !Array.isArray(payload.rows)) return false
+  return Object.keys(payload).every((key) => TABULAR_ENVELOPE_KEYS.has(key))
+}
+
+/**
+ * The single row-shape decision for every row-oriented format. It lives here,
+ * once, because the failure mode of having it four times over was that a fix
+ * landed in one format and silently missed the others.
+ *
+ * Order matters, and every step is triggered by something the CALLER did — none of
+ * it is inferred from payload shape:
+ *   1. a bare `columns` + `rows` envelope — already a table (successRows).
+ *   2. `data` IS the list — the normal list command.
+ *   3. `data[rowsKey]` — the command declared which field holds the list.
+ *   4. anything else — one object, one row.
+ *
+ * Step 3 is opt-in on purpose. An earlier revision also PROJECTED any object that
+ * happened to hold exactly one array-of-records, which changed the rendering of
+ * commands nobody had looked at: `datasource check` lost `ready`, the verdict it
+ * exists to deliver, because a projected list's scalar siblings are dropped. A
+ * command whose list should be rows now says so.
+ *
+ * Scalar siblings of a projected list (`active_profile`, `table_count`) are not
+ * part of the table; json/pretty/toon still carry them, and `--field` reaches
+ * them directly.
+ */
+function projectRows(payload: unknown, rowsKey?: string): RowProjection | undefined {
+  if (!isRecordValue(payload)) return undefined
+
+  if (isTabularEnvelope(payload)) {
+    const columns = (payload.columns as unknown[]).filter((column): column is string => typeof column === "string")
+    const rows = (payload.rows as unknown[]).map((row) => (Array.isArray(row) ? row : [row]))
+    return { columns, rows }
+  }
+
+  const data = payload.data
+  if (Array.isArray(data)) return projectArray(data, "value")
+  if (!isRecordValue(data)) return undefined
+
+  if (rowsKey) {
+    const declared = data[rowsKey]
+    if (Array.isArray(declared)) return projectArray(declared, rowsKey)
   }
-  return formatJson(payload)
+
+  const columns = Object.keys(data)
+  return { columns, rows: [columns.map((column) => data[column])] }
 }
 
-function emitAsText(payload: unknown): string {
-  if (payload && typeof payload === "object") {
-    const obj = payload as Record<string, unknown>
-    const data = obj.data
-    if (Array.isArray(data) && data.length > 0 && typeof data[0] === "object" && data[0] !== null && !Array.isArray(data[0])) {
-      const columns = Object.keys(data[0] as Record<string, unknown>)
-      const rows = (data as Record<string, unknown>[]).map((r) => columns.map((c) => r[c]))
-      return formatText(columns, rows)
-    }
-    if (Array.isArray(data) && data.length > 0) {
-      return data.map((v) => (v === null || v === undefined ? "" : String(v))).join("\n")
-    }
-    if (data && typeof data === "object" && !Array.isArray(data)) {
-      const columns = Object.keys(data as Record<string, unknown>)
-      const row = columns.map((c) => (data as Record<string, unknown>)[c])
-      return formatText(columns, [row])
-    }
+type RowFormat = "table" | "csv" | "text" | "jsonl"
+
+/**
+ * Payloads with nothing tabular in them (an `error` envelope reaching a row
+ * format directly, say) keep each format's historical fallback: compact JSON for
+ * the machine-facing text/jsonl, indented JSON for the human-facing table/csv.
+ * `test/e2e-routing.ts` parses the text one as JSON, so this is a contract.
+ */
+const NON_TABULAR_FALLBACK: Record<RowFormat, (payload: unknown) => string> = {
+  table: formatPretty,
+  csv: formatPretty,
+  text: formatJson,
+  jsonl: formatJson,
+}
+
+function emitRowFormat(payload: unknown, format: RowFormat, rowsKey?: string): string {
+  const projection = projectRows(payload, rowsKey)
+  if (!projection) return NON_TABULAR_FALLBACK[format](payload)
+  // An empty list is empty output, not a JSON envelope leaking into a row format.
+  if (projection.columns.length === 0) return ""
+  switch (format) {
+    case "table":
+      return formatTable(projection.columns, projection.rows)
+    case "csv":
+      return formatCsv(projection.columns, projection.rows)
+    case "text":
+      return formatText(projection.columns, projection.rows)
+    case "jsonl":
+      return formatJsonl(projection.items ?? rowsToRecords(projection.columns, projection.rows))
   }
-  return formatJson(payload)
 }
 
 function rowsToRecords(columns: string[], rows: unknown[][]): Record<string, unknown>[] {
diff --git a/packages/cz-cli/src/run-cli.ts b/packages/cz-cli/src/run-cli.ts
index 47ab92e0d3..5ae0be83a4 100644
--- a/packages/cz-cli/src/run-cli.ts
+++ b/packages/cz-cli/src/run-cli.ts
@@ -1,15 +1,16 @@
 import { readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { join } from "node:path"
-import { createTraceparent } from "@clickzetta/sdk"
+import { InterfaceError, createTraceparent } from "@clickzetta/sdk"
 import { injectAgentMcp } from "./agent-mcp.js"
 import { createCli } from "./cli.js"
 import { CLICKZETTA_PROFILE_OPTION_NAMES } from "./clickzetta-profile-option.js"
 import { ConnectionEnv } from "./connection/env.js"
+import { parseAgentTimeoutMs } from "./bootstrap/runtime-config.js"
 import { resolveConnectionConfig, type CliArgs } from "./connection/config.js"
 import { migrateInlineOAuthTokens, pruneOrphanOAuthSections, readProfileEntry } from "./connection/profile-store.js"
 import * as Profile from "./connection/profile-context.js"
-import { parseOutputArgs, renderOutput } from "./output/index.js"
+import { EXIT_BIZ_ERROR, isHandledCliError, parseOutputArgs, renderOutput, renderErrorOutput } from "./output/index.js"
 import { registerCommands } from "./register-commands.js"
 import { SubcommandHelpShown } from "./subcommand-help.js"
 import { trackCommand, parseTrackingArgs } from "./telemetry.js"
@@ -339,6 +340,29 @@ export function emitUsageError(runtime: CliRuntime, message: string): never {
   return runtime.exit(2)
 }
 
+/**
+ * `--profile <name>` / `CZ_PROFILE` naming a profile that does not exist.
+ *
+ * resolveConnectionConfig throws PROFILE_NOT_FOUND for this (so programmatic
+ * callers see it classified like any other connection error), but on the CLI path
+ * the first call happens in applyAgentConnectionEnv below — before any command's
+ * try/catch — where a throw would escape as an unhandled exception. Reporting it
+ * here keeps one message for both paths.
+ */
+function emitProfileNotFound(runtime: CliRuntime, name: string, rawArgs: string[]): never {
+  const outputArgs = parseOutputArgs(rawArgs)
+  const payload = {
+    error: {
+      code: "PROFILE_NOT_FOUND",
+      message: `Profile '${name}' not found in ~/.clickzetta/profiles.toml.`,
+      next_step: "cz-cli profile list",
+    },
+    ai_message: `Profile '${name}' does not exist. Run \`cz-cli profile list\` to see the configured profiles, or \`cz-cli auth login <name>\` to create one.`,
+  }
+  runtime.stdout.write(renderErrorOutput(payload, outputArgs.format, outputArgs.field) + "\n")
+  return runtime.exit(1)
+}
+
 async function delegateToAgentRuntime(rawArgs: string[]): Promise<never> {
   // The agent-runtime phase is in-process state. Pass it as an argument rather
   // than via process.env, which would be inherited by child processes (e.g. the
@@ -661,7 +685,19 @@ export function resolveAccountsUrl(profileName: string | undefined): string | un
 
 function applyAgentConnectionEnv(overrides: Partial<CliArgs>) {
   if (Object.keys(overrides).length === 0) return overrides
-  const resolved = resolveConnectionConfig(overrides)
+  // resolveConnectionConfig rejects a profile name that does not exist. Whether THAT
+  // is an error here has already been decided by the boundary guard in runCli, which
+  // reports every explicitly named missing profile and every inherited one on a
+  // connecting command. What is left for this catch is the cases the guard lets
+  // through on purpose — `--help`, and an inherited CZ_PROFILE on a command that does
+  // not connect — where this call's only job is to mirror values into env.
+  let resolved: ReturnType<typeof resolveConnectionConfig>
+  try {
+    resolved = resolveConnectionConfig(overrides)
+  } catch (err) {
+    if ((err as { code?: unknown } | null)?.code === "PROFILE_NOT_FOUND") return overrides
+    throw err
+  }
   const { userFields, derivedFields } = splitConnectionEnv(overrides, resolved)
   const accountsUrl = resolveAccountsUrl(overrides.profile ?? Profile.current())
   if (accountsUrl) derivedFields.accountsUrl = accountsUrl
@@ -699,6 +735,32 @@ export async function runCli(rawArgs: string[], runtime: CliRuntime = defaultRun
   // re-add entries they already had. Idempotent; no-ops without `[llm.*]`.
   await migrateProfilesLlm()
   const normalized = normalizeCliArgs(rawArgs)
+  // Only commands that actually CONNECT are gated on the named profile existing.
+  // Keying it on "did the caller name a profile" instead locked users out of their
+  // own recovery path: a stale CZ_PROFILE (a deleted profile still exported into the
+  // shell) then failed `profile list` — which is the command the error message tells
+  // you to run — plus `profile create`, `profile use`, `auth list` and even
+  // `--version`. Commands that never connect ignore the flag as they always did;
+  // setup/login/auth login are outside this set too, so a name they are about to
+  // CREATE still passes.
+  // Two sources, two rules. A name the caller TYPED (`--profile x`) is a typo wherever
+  // it appears, including on the agent path — where the alternative is what this used
+  // to do: no message on either stream, no connection env applied, and the missing
+  // name pinned anyway. An INHERITED CZ_PROFILE is only fatal for a command that
+  // connects, since an env-only invocation (no profiles.toml, CZ_PROFILE exported as
+  // a label, credentials in CZ_*) legitimately carries a name with no entry behind it.
+  const explicitProfile = profileOverrideFromArgs(normalized.args)
+  const requestedProfile = explicitProfile ?? ConnectionEnv.profileName()
+  const profileMustExist =
+    explicitProfile !== undefined || PROFILE_REQUIRED_COMMANDS.has(normalized.command)
+  if (
+    requestedProfile &&
+    profileMustExist &&
+    !normalized.isHelpRequest &&
+    !readProfileEntry(requestedProfile)
+  ) {
+    emitProfileNotFound(runtime, requestedProfile, rawArgs)
+  }
   // On the agent path, upstream opencode owns several of these short flags; tell
   // the scanner so it does not also read them as cz connection overrides. See
   // AGENT_CONTESTED_FLAGS.
@@ -724,6 +786,25 @@ export async function runCli(rawArgs: string[], runtime: CliRuntime = defaultRun
     return runtime.exit(2)
   }
 
+  // `--timeout` is cz's own flag on the agent path, and its check used to live past
+  // the gate below in bootstrap/runtime.ts — so on a machine with no LLM registered,
+  // `agent run --timeout abc` answered NO_LLM_CONFIGURED and the bad value was never
+  // mentioned. Same rule as the cz command tree (see parseRegisteredCommands): a
+  // syntactically invalid invocation is reported before any onboarding gate, and in
+  // the same envelope as every other usage error.
+  if (normalized.shouldDelegateToAgentRuntime && parseAgentTimeoutMs(normalized.args) === null) {
+    const outputArgs = parseOutputArgs(rawArgs)
+    const message = "--timeout must be a positive number of seconds"
+    runtime.stdout.write(
+      renderErrorOutput(
+        { error: { code: "USAGE_ERROR", message }, ai_message: `${message}. Pass the LLM first-byte timeout in seconds, e.g. --timeout 150.` },
+        outputArgs.format,
+        outputArgs.field,
+      ) + "\n",
+    )
+    return runtime.exit(2)
+  }
+
   if (isAgentSessionEntry && !process.env.CLICKZETTA_PID && !(await hasConfiguredLlm())) {
     return emitNoLlmConfigured(runtime, rawArgs)
   }
@@ -785,10 +866,45 @@ export async function runCliWithTracking(rawArgs: string[]): Promise<void> {
     if (positional[0] !== "setup") {
       await track(!process.exitCode, process.exitCode ? lastError ?? `exit_code=${process.exitCode}` : undefined)
     }
-  } catch (error) {
+  } catch (err) {
     if (positional[0] !== "setup") {
-      await track(false, error instanceof Error ? error.message : `exit_code=${process.exitCode ?? 1}`)
+      await track(false, err instanceof Error ? err.message : `exit_code=${process.exitCode ?? 1}`)
+    }
+    // Last resort. Everything this CLI prints is machine-readable, so an
+    // exception that reaches the entry point must not become a bare stack trace
+    // on stderr with an empty stdout — that is the one failure mode a caller
+    // cannot parse. A reported failure (usage error, error(), a gate) has already
+    // set exitCode; only an UNREPORTED throw lands here.
+    // Two sentinels legitimately reach here with exit 0: a group that rendered its
+    // own help, and an error that error() already printed. Neither is unreported.
+    if (err instanceof SubcommandHelpShown || isHandledCliError(err)) return
+    if (!process.exitCode) {
+      emitInternalError(err, rawArgs)
+      return
     }
-    if (!process.exitCode) throw error
   }
 }
+
+/**
+ * Render an unhandled exception as the standard error envelope. The stack goes to
+ * stderr only under --debug, where a human asked for it.
+ */
+function emitInternalError(err: unknown, rawArgs: string[]): void {
+  const outputArgs = parseOutputArgs(rawArgs)
+  const message = err instanceof Error ? err.message : String(err)
+  // Only an InterfaceError's code enters the envelope: those are ours (INVALID_AUTH_TYPE,
+  // PROFILE_NOT_FOUND, …). A runtime error's `code` is a libuv string like ENOENT or
+  // ECONNREFUSED, which would quietly extend the vocabulary callers switch on.
+  const code = err instanceof InterfaceError && typeof err.code === "string" ? err.code : undefined
+  const payload = {
+    error: {
+      code: code && code.length > 0 ? code : "INTERNAL_ERROR",
+      message,
+    },
+  }
+  process.stdout.write(renderErrorOutput(payload, outputArgs.format, outputArgs.field) + "\n")
+  if (rawArgs.includes("--debug") || rawArgs.includes("-d")) {
+    process.stderr.write((err instanceof Error && err.stack ? err.stack : message) + "\n")
+  }
+  process.exitCode = EXIT_BIZ_ERROR
+}
diff --git a/packages/cz-cli/src/telemetry.ts b/packages/cz-cli/src/telemetry.ts
index 89eb703d8e..85b05eb286 100644
--- a/packages/cz-cli/src/telemetry.ts
+++ b/packages/cz-cli/src/telemetry.ts
@@ -4,6 +4,7 @@ import { homedir } from "os"
 import { OTEL_DEFAULTS } from "./otel-defaults.js"
 import { VERSION } from "./version.js"
 import { currentTraceContext } from "./trace.js"
+import { redactSql } from "./logger.js"
 
 /**
  * CLI flag names whose values must never be exfiltrated via telemetry.
@@ -54,9 +55,55 @@ export function isSensitiveKey(key: string): boolean {
   return SENSITIVE_KEYS.has(key.toLowerCase())
 }
 
+/**
+ * Flags that take NO value, so the token after them is a positional rather than
+ * their own — `cz-cli sql --batch "select …"` is the statement, not `--batch`'s
+ * value. Without this the statement was recorded under the flag's key, and the
+ * masking below only covers literals that LOOK like PII, so table names, columns and
+ * predicates still left the machine.
+ *
+ * Enumerated rather than derived because this runs before yargs parses anything, and
+ * generated from the tree's `type: "boolean"` declarations plus the value-less
+ * globals. A flag missing from here degrades to the old behavior (its neighbour is
+ * recorded, masked by redactSql) rather than to a wrong value, so drift is visible
+ * as noise in analytics, not as a leak of the whole statement.
+ */
+export const VALUELESS_FLAGS: ReadonlySet<string> = new Set([
+  // value-less globals (and yargs' own)
+  "debug", "d", "help", "h", "version", "v",
+  // every option declared `type: "boolean"` across the tree, and only those:
+  // `--header` (boolean on sql, KEY=VALUE on profile create) and `--limit`
+  // (boolean via --no-limit, number on sql) are declared BOTH ways, so they stay
+  // out — treating them as value-less would drop a real value, and for --header
+  // that value can be `Authorization=Bearer …`. Same for the alias `-a`: it is
+  // `--all` (boolean) on `agent session list` but `--client` (string) on `mcp init`,
+  // whose own example is `mcp init -a claude -a codex`.
+  "N", "all", "allow-timeout", "async", "auto-lineage", "batch", "B", "browser",
+  "continue", "c", "dangerously-skip-permissions", "dimension", "dry-run", "force",
+  "fork", "global", "hidden", "include-columns", "include-preview", "include-secret",
+  "index", "keep-profiles", "mine", "open", "partitioned", "persist", "raw", "refresh",
+  "refresh-llm", "remove-from-llm", "rerun", "resolve", "reveal", "sanitize",
+  "save-params", "show-secret", "skip-check", "skip-verify", "snapshot", "stdin",
+  "summary", "sync", "thinking", "truncate", "use", "validate-only", "verbose", "wait",
+  "with-detail", "with-downstream", "with-schema", "with-tables", "write", "yes", "y",
+])
+
+function takesNoValue(key: string): boolean {
+  const name = key.toLowerCase()
+  // `--no-x` is yargs' negation and never carries a value, whatever `x` is declared
+  // as — `--no-limit` on a number option yields 0. No declared option in this tree is
+  // literally named `no-…`, so the prefix is unambiguous.
+  return VALUELESS_FLAGS.has(name) || name.startsWith("no-")
+}
+
 /**
  * Parse raw CLI args into positional tokens and a flag map suitable for telemetry.
  * Expects args already sliced to user-visible tokens (i.e. process.argv.slice(2) or hideBin output).
+ *
+ * Recorded values additionally pass through `redactSql`, the same masking the local
+ * SQL history applies — defence in depth, since it only rewrites literals that look
+ * like PII. What keeps a whole statement out of the flag map is VALUELESS_FLAGS
+ * above: a flag that takes no value no longer claims the token after it.
  */
 export function parseTrackingArgs(rawArgs: string[]): {
   positional: string[]
@@ -79,14 +126,19 @@ export function parseTrackingArgs(rawArgs: string[]): {
     const key = arg.replace(/^-+/, "").toLowerCase()
     const next = rawArgs[i + 1]
     if (!next) continue
-    if (!isSensitiveKey(key) && !isSensitiveValue(next)) continue
+    // The VALUE being a credential (`Cookie=…`, `Authorization=Bearer …`) keeps it out
+    // of _positional regardless of which flag precedes it. Only the flag-NAME half of
+    // the test is skipped for a value-less flag, since such a flag has no value to
+    // claim in the first place.
+    const valueIsSecret = isSensitiveValue(next)
+    if (!valueIsSecret && (takesNoValue(key) || !isSensitiveKey(key))) continue
     secretValues.add(i + 1)
   }
   const positional = rawArgs.filter((arg, i) => !arg.startsWith("-") && !secretValues.has(i))
   const args: Record<string, string> = {}
 
   if (positional.length > 2) {
-    args["_positional"] = positional.slice(2).join(" ")
+    args["_positional"] = redactSql(positional.slice(2).join(" "))
   }
 
   for (let i = 0; i < rawArgs.length; i++) {
@@ -96,7 +148,7 @@ export function parseTrackingArgs(rawArgs: string[]): {
     if (eqIdx > 0) {
       const key = arg.slice(0, eqIdx).replace(/^-+/, "")
       const inlineValue = arg.slice(eqIdx + 1)
-      args[key] = isSensitiveKey(key) || isSensitiveValue(inlineValue) ? "<redacted>" : inlineValue
+      args[key] = isSensitiveKey(key) || isSensitiveValue(inlineValue) ? "<redacted>" : redactSql(inlineValue)
       continue
     }
     const next = rawArgs[i + 1]
@@ -105,9 +157,10 @@ export function parseTrackingArgs(rawArgs: string[]): {
     // `--password -h7Kq…` left the value unclaimed, the next iteration read it as a flag
     // name, and the secret was recorded as an attribute KEY — harder to scrub downstream
     // than a value. `secretValues` marks the same index, so it stays out of _positional.
-    const claimsNext = next !== undefined && (!next.startsWith("-") || secretValues.has(i + 1))
+    const claimsNext =
+      !takesNoValue(key) && next !== undefined && (!next.startsWith("-") || secretValues.has(i + 1))
     if (claimsNext) {
-      args[key] = isSensitiveKey(key) || isSensitiveValue(next!) ? "<redacted>" : next!
+      args[key] = isSensitiveKey(key) || isSensitiveValue(next!) ? "<redacted>" : redactSql(next!)
       i++
       continue
     }
diff --git a/packages/cz-cli/src/usage-error.ts b/packages/cz-cli/src/usage-error.ts
new file mode 100644
index 0000000000..19e60bdeb0
--- /dev/null
+++ b/packages/cz-cli/src/usage-error.ts
@@ -0,0 +1,16 @@
+/**
+ * A usage error raised by our OWN validation (as opposed to yargs' built-in
+ * checks, which reach the fail handler as a plain message with no error object).
+ *
+ * Both fail handlers — cli.ts's and commandGroup's — rethrow any error they are
+ * handed, so that a genuine exception from a command handler is never disguised
+ * as a usage error. A validator that wants the USAGE_ERROR treatment therefore
+ * needs to be distinguishable from such an exception: that is this class, and
+ * the two handlers special-case it.
+ */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "UsageError"
+  }
+}
diff --git a/packages/cz-cli/test/agent-mcp.test.ts b/packages/cz-cli/test/agent-mcp.test.ts
index 86bb67b918..f774df3ec5 100644
--- a/packages/cz-cli/test/agent-mcp.test.ts
+++ b/packages/cz-cli/test/agent-mcp.test.ts
@@ -189,3 +189,37 @@ describe("agent MCP discovery", () => {
     expect(mcp).toEqual({})
   })
 })
+
+describe("a manifest naming a profile that no longer exists", () => {
+  test("skips that entry instead of failing the whole invocation", async () => {
+    // `profile` is a field in a config file on disk. resolveConnectionConfig rejects an
+    // explicitly named missing profile, and nothing between resolveClickZettaRemote and
+    // run-cli's injectAgentMcp catches it — so a profile renamed after the manifest was
+    // written used to abort `cz-cli agent run` with PROFILE_NOT_FOUND.
+    const home = mkdtempSync(join(tmpdir(), "cz-cli-agent-mcp-stale-"))
+    const cwd = mkdtempSync(join(tmpdir(), "cz-cli-agent-mcp-stale-cwd-"))
+    setTestHome(home)
+    writeProfiles(
+      home,
+      ['default_profile = "dev"', "", "[profiles.dev]", 'pat = "pat-123"', 'service = "uat-api.clickzetta.com"', 'instance = "inst"', 'workspace = "ws"', ""].join("\n"),
+    )
+    writeBuiltinManifest(home, JSON.stringify({ kind: "clickzetta_remote", enabled: true, profile: "renamed-away" }))
+
+    const mcp = await discoverAgentMcp({}, cwd)
+    expect(mcp["clickzetta-lakehouse"]).toBeUndefined()
+  })
+
+  test("a manifest naming a profile that DOES exist still resolves", async () => {
+    const home = mkdtempSync(join(tmpdir(), "cz-cli-agent-mcp-named-"))
+    const cwd = mkdtempSync(join(tmpdir(), "cz-cli-agent-mcp-named-cwd-"))
+    setTestHome(home)
+    writeProfiles(
+      home,
+      ['default_profile = "dev"', "", "[profiles.dev]", 'pat = "pat-123"', 'service = "uat-api.clickzetta.com"', 'instance = "inst"', 'workspace = "ws"', "", "[profiles.other]", 'pat = "pat-other"', 'service = "uat-api.clickzetta.com"', 'instance = "inst2"', 'workspace = "ws2"', ""].join("\n"),
+    )
+    writeBuiltinManifest(home, JSON.stringify({ kind: "clickzetta_remote", enabled: true, profile: "other" }))
+
+    const mcp = await discoverAgentMcp({}, cwd)
+    expect(mcp["clickzetta-lakehouse"]).toBeDefined()
+  })
+})
diff --git a/packages/cz-cli/test/auth-list-format.test.ts b/packages/cz-cli/test/auth-list-format.test.ts
new file mode 100644
index 0000000000..19e2791af4
--- /dev/null
+++ b/packages/cz-cli/test/auth-list-format.test.ts
@@ -0,0 +1,125 @@
+import { expect, test, describe } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+/**
+ * `auth list` end to end, one run per output format.
+ *
+ * It used to answer `--format text` with the whole session array JSON-encoded into
+ * the first cell of a single row. The payload is unchanged — `data.sessions` plus the
+ * active-session context — and now declares `rowsKey: "sessions"`, so only the
+ * row-oriented formats change. Reshaping the payload instead would have broken
+ * `.data.sessions` and `--field sessions` for existing callers.
+ */
+
+function run(args: string[], home: string) {
+  const result = spawnSync("bun", ["./src/main.ts", ...args], {
+    cwd: import.meta.dir + "/..",
+    encoding: "utf-8",
+    env: { ...process.env, HOME: home, CLICKZETTA_TEST_HOME: home, NO_COLOR: "1" },
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+  return { stdout: (result.stdout ?? "").trim(), exitCode: result.status ?? 1 }
+}
+
+function homeWith(toml: string): string {
+  const home = mkdtempSync(join(tmpdir(), "cz-auth-list-"))
+  mkdirSync(join(home, ".clickzetta"), { recursive: true })
+  writeFileSync(join(home, ".clickzetta", "profiles.toml"), toml)
+  return home
+}
+
+const TWO_SESSIONS = `default_profile = "uat_0"
+
+[oauth.uat]
+expire_time_ms = 3600000
+obtained_at = 1000000000000
+
+[oauth.saas]
+expire_time_ms = 3600000
+obtained_at = 1000000000000
+
+[profiles.uat_0]
+oauth = "uat"
+
+[profiles.saas_0]
+oauth = "saas"
+
+[profiles.saas_1]
+oauth = "saas"
+`
+
+describe("auth list respects every output format", () => {
+  const home = homeWith(TWO_SESSIONS)
+
+  test("text prints one tab-separated row per session", () => {
+    const { stdout, exitCode } = run(["auth", "list", "--format", "text"], home)
+    expect(exitCode).toBe(0)
+    const lines = stdout.split("\n")
+    expect(lines).toHaveLength(2)
+    expect(lines[0].startsWith("uat\ttrue\t")).toBe(true)
+    expect(lines[1].startsWith("saas\tfalse\t")).toBe(true)
+    // The regression: the session list arriving as one JSON cell.
+    expect(stdout).not.toContain('[{"session"')
+  })
+
+  test("table prints a header and one row per session", () => {
+    const { stdout } = run(["auth", "list", "--format", "table"], home)
+    const lines = stdout.split("\n")
+    expect(lines[0].split("|").map((c) => c.trim())).toEqual([
+      "session", "active", "profiles", "profile_count", "expires_in_ms", "expired",
+    ])
+    expect(lines).toHaveLength(4) // header + separator + 2 sessions
+  })
+
+  test("csv prints a header and one row per session", () => {
+    const { stdout } = run(["auth", "list", "--format", "csv"], home)
+    const lines = stdout.split("\n")
+    expect(lines[0]).toBe("session,active,profiles,profile_count,expires_in_ms,expired")
+    expect(lines).toHaveLength(3)
+  })
+
+  test("jsonl prints one object per session", () => {
+    const { stdout } = run(["auth", "list", "--format", "jsonl"], home)
+    const lines = stdout.split("\n").map((l) => JSON.parse(l) as Record<string, unknown>)
+    expect(lines.map((l) => l.session)).toEqual(["uat", "saas"])
+    expect(lines[1].profile_count).toBe(2)
+  })
+
+  test("json keeps the shape it has always had", () => {
+    const { stdout } = run(["auth", "list", "--format", "json"], home)
+    const payload = JSON.parse(stdout) as Record<string, any>
+    expect(payload.data.sessions).toHaveLength(2)
+    expect(payload.data.active_session).toBe("uat")
+    expect(payload.data.active_profile).toBe("uat_0")
+    expect(payload.data.sessions[0]).toMatchObject({ session: "uat", active: true, profile_count: 1, expired: true })
+    expect(payload.data.sessions[1].profiles).toEqual(["saas_0", "saas_1"])
+  })
+
+  test("--field sessions still resolves, as it did before rowsKey", () => {
+    const { stdout } = run(["auth", "list", "--field", "sessions"], home)
+    expect(stdout.startsWith("[")).toBe(true)
+    expect(stdout).toContain('"session":"uat"')
+  })
+
+  test("--field reaches the active-session context", () => {
+    expect(run(["auth", "list", "--field", "active_session"], home).stdout).toBe("uat")
+  })
+})
+
+describe("auth list with nothing to list", () => {
+  const home = homeWith("[profiles.local]\ninstance = \"x\"\n")
+
+  test("row formats print nothing rather than an envelope", () => {
+    for (const format of ["text", "csv", "table", "jsonl"]) {
+      expect(run(["auth", "list", "--format", format], home).stdout).toBe("")
+    }
+  })
+
+  test("json prints an empty list", () => {
+    const payload = JSON.parse(run(["auth", "list", "--format", "json"], home).stdout) as Record<string, any>
+    expect(payload.data.sessions).toEqual([])
+  })
+})
diff --git a/packages/cz-cli/test/connection-config.test.ts b/packages/cz-cli/test/connection-config.test.ts
index 4509404d08..e0c510822a 100644
--- a/packages/cz-cli/test/connection-config.test.ts
+++ b/packages/cz-cli/test/connection-config.test.ts
@@ -95,3 +95,93 @@ test("resolveConnectionConfig honors CZ_PROFILE before falling back to default p
   expect(config.instance).toBe("clickzetta")
   expect(config.workspace).toBe("czcli")
 })
+
+/**
+ * A profile the caller NAMED but that is not in profiles.toml. This used to read as
+ * undefined and let every field fall through to env/defaults, so the user got
+ * "Authentication required. Run cz-cli auth login" for what was a misspelled name.
+ * The CLI reports this at its boundary (run-cli.ts); these cover the library path
+ * that programmatic callers — execute(), the MCP server — go through.
+ */
+test("resolveConnectionConfig rejects an explicitly named profile that does not exist", async () => {
+  process.env.HOME = home
+  process.env.CLICKZETTA_TEST_HOME = home
+  delete process.env.CZ_PROFILE
+  delete process.env.CZ_ENV_DERIVED
+
+  const { resolveConnectionConfig } = await import(`../src/connection/config.ts?${Date.now()}`)
+  try {
+    resolveConnectionConfig({ profile: "ghost" })
+    throw new Error("expected PROFILE_NOT_FOUND")
+  } catch (err) {
+    expect((err as { code?: string }).code).toBe("PROFILE_NOT_FOUND")
+    expect((err as Error).message).toContain("ghost")
+  }
+})
+
+/**
+ * A stale CZ_PROFILE is deliberately NOT rejected here. run-cli.ts checks it for the
+ * commands that connect, while this function is also reached by callers that merely
+ * read a config — the TUI quota sidebar, gateway-prompt, agent-mcp, studio-context —
+ * where an inherited value that no longer resolves should degrade, not throw.
+ */
+test("resolveConnectionConfig tolerates a stale CZ_PROFILE (the CLI reports that)", async () => {
+  process.env.HOME = home
+  process.env.CLICKZETTA_TEST_HOME = home
+  process.env.CZ_PROFILE = "ghost"
+  delete process.env.CZ_ENV_DERIVED
+  for (const name of ["CZ_PAT", "CZ_USERNAME", "CZ_PASSWORD", "CZ_SERVICE", "CZ_INSTANCE", "CZ_WORKSPACE", "CZ_SCHEMA", "CZ_VCLUSTER"]) {
+    delete process.env[name]
+  }
+
+  const { resolveConnectionConfig } = await import(`../src/connection/config.ts?${Date.now()}`)
+  expect(() => resolveConnectionConfig({})).not.toThrow()
+  delete process.env.CZ_PROFILE
+})
+
+test("resolveConnectionConfig still accepts an invocation that names no profile", async () => {
+  process.env.HOME = home
+  process.env.CLICKZETTA_TEST_HOME = home
+  delete process.env.CZ_PROFILE
+  delete process.env.CZ_ENV_DERIVED
+  // The first test in this file exports a full CZ_* set; those sit ABOVE the profile
+  // in the priority order, so they have to go before asserting on profile values.
+  for (const name of ["CZ_PAT", "CZ_USERNAME", "CZ_PASSWORD", "CZ_SERVICE", "CZ_INSTANCE", "CZ_WORKSPACE", "CZ_SCHEMA", "CZ_VCLUSTER"]) {
+    delete process.env[name]
+  }
+
+  const { resolveConnectionConfig } = await import(`../src/connection/config.ts?${Date.now()}`)
+  expect(resolveConnectionConfig({}).instance).toBe("test-instance")
+})
+
+/**
+ * An empty value is not a value: `--workspace` with nothing after it arrives here as
+ * "" and used to overwrite the profile, after which the command complained that the
+ * workspace was missing — about the flag the user had just passed.
+ */
+test("resolveConnectionConfig treats an empty override as absent, keeping the profile's value", async () => {
+  process.env.HOME = home
+  process.env.CLICKZETTA_TEST_HOME = home
+  delete process.env.CZ_PROFILE
+  delete process.env.CZ_ENV_DERIVED
+  for (const name of ["CZ_PAT", "CZ_USERNAME", "CZ_PASSWORD", "CZ_SERVICE", "CZ_INSTANCE", "CZ_WORKSPACE", "CZ_SCHEMA", "CZ_VCLUSTER"]) {
+    delete process.env[name]
+  }
+
+  const { resolveConnectionConfig } = await import(`../src/connection/config.ts?${Date.now()}`)
+  const config = resolveConnectionConfig({ workspace: "", instance: "  ", schema: "" })
+  expect(config.workspace).toBe("qa_test_prj01")
+  expect(config.instance).toBe("test-instance")
+  expect(config.schema).toBe("tianzhu")
+})
+
+test("resolveConnectionConfig still applies a non-empty override", async () => {
+  process.env.HOME = home
+  process.env.CLICKZETTA_TEST_HOME = home
+  delete process.env.CZ_PROFILE
+  delete process.env.CZ_ENV_DERIVED
+  for (const name of ["CZ_INSTANCE", "CZ_WORKSPACE", "CZ_SCHEMA"]) delete process.env[name]
+
+  const { resolveConnectionConfig } = await import(`../src/connection/config.ts?${Date.now()}`)
+  expect(resolveConnectionConfig({ workspace: "other_ws" }).workspace).toBe("other_ws")
+})
diff --git a/packages/cz-cli/test/output-row-projection.test.ts b/packages/cz-cli/test/output-row-projection.test.ts
new file mode 100644
index 0000000000..690605fa9c
--- /dev/null
+++ b/packages/cz-cli/test/output-row-projection.test.ts
@@ -0,0 +1,425 @@
+import { describe, expect, test } from "bun:test"
+import { renderOutput } from "../src/output/index.ts"
+
+/**
+ * Row-shape projection for the row-oriented formats (table/csv/text/jsonl).
+ *
+ * The regression this locks down: `auth list` returned `{ sessions: [...] }`,
+ * and because the projection only flattened when `data` WAS the list, every row
+ * format printed a single row whose first cell was the whole list as JSON. The
+ * shape decision now lives in exactly one place (`projectRows`), so the tests
+ * below assert all four formats agree — that agreement is the actual guarantee.
+ */
+
+const ROW_FORMATS = ["table", "csv", "text", "jsonl"] as const
+
+/** How many data rows a rendering has, per format (header lines excluded). */
+function rowCount(output: string, format: string): number {
+  if (output === "") return 0
+  const lines = output.split("\n")
+  if (format === "table") return lines.length - 2 // header + separator
+  if (format === "csv") return lines.length - 1 // header
+  return lines.length
+}
+
+describe("data IS the list (the plain list command)", () => {
+  const payload = {
+    data: [
+      { session: "a", active: true },
+      { session: "b", active: false },
+    ],
+    count: 2,
+  }
+
+  test("table renders a header plus one row per item", () => {
+    expect(renderOutput(payload, "table")).toBe(
+      ["session | active", "--------+-------", "a       | true  ", "b       | false "].join("\n"),
+    )
+  })
+
+  test("csv renders a header plus one row per item", () => {
+    expect(renderOutput(payload, "csv")).toBe("session,active\na,true\nb,false")
+  })
+
+  test("text renders tab-separated rows with no header", () => {
+    expect(renderOutput(payload, "text")).toBe("a\ttrue\nb\tfalse")
+  })
+
+  test("jsonl renders one object per item", () => {
+    expect(renderOutput(payload, "jsonl")).toBe('{"session":"a","active":true}\n{"session":"b","active":false}')
+  })
+
+  test("every row format sees two rows", () => {
+    for (const format of ROW_FORMATS) expect(rowCount(renderOutput(payload, format), format)).toBe(2)
+  })
+})
+
+describe("a list wrapped in an object is a list once the command says so", () => {
+  // The exact shape of the reported bug: one array of records, scalar siblings.
+  const payload = {
+    data: {
+      sessions: [
+        { session: "robert-uat", profile_count: 1 },
+        { session: "robert-cn-saas", profile_count: 4 },
+      ],
+      active_session: null,
+      active_profile: "aigw",
+    },
+  }
+
+  test("declaring the key makes every row format render rows, not one JSON cell", () => {
+    for (const format of ROW_FORMATS) {
+      const out = renderOutput(payload, format, undefined, "sessions")
+      expect(out).not.toContain('[{"session"')
+      expect(rowCount(out, format)).toBe(2)
+    }
+  })
+
+  test("without the declaration the payload keeps its single-row rendering", () => {
+    // Projecting on shape alone changed commands nobody had reviewed — `datasource
+    // check` lost `ready` that way — so an undeclared payload is left as it was.
+    expect(rowCount(renderOutput(payload, "csv"), "csv")).toBe(1)
+    expect(renderOutput(payload, "csv").split("\n")[0]).toBe("sessions,active_session,active_profile")
+  })
+
+  test("text rows come from the list, not from the wrapper's keys", () => {
+    expect(renderOutput(payload, "text", undefined, "sessions")).toBe("robert-uat\t1\nrobert-cn-saas\t4")
+  })
+
+  test("csv column names come from the records", () => {
+    expect(renderOutput(payload, "csv", undefined, "sessions").split("\n")[0]).toBe("session,profile_count")
+  })
+
+  test("json keeps the wrapper untouched", () => {
+    expect(renderOutput(payload, "json")).toBe(
+      '{"data":{"sessions":[{"session":"robert-uat","profile_count":1},{"session":"robert-cn-saas","profile_count":4}],"active_session":null,"active_profile":"aigw"}}',
+    )
+  })
+
+  test("--field still reaches a scalar sibling that the rows dropped", () => {
+    expect(renderOutput(payload, "text", "active_profile", "sessions")).toBe("aigw")
+  })
+})
+
+describe("a single result that merely contains a list stays one row", () => {
+  test("array of plain values is not mistaken for the rows (auth logout)", () => {
+    const payload = {
+      data: { logged_out: true, session: "uat", token_removed: true, profiles_removed: ["uat_0", "uat_1"] },
+    }
+    expect(renderOutput(payload, "text")).toBe('true\tuat\ttrue\t["uat_0","uat_1"]')
+    for (const format of ROW_FORMATS) expect(rowCount(renderOutput(payload, format), format)).toBe(1)
+  })
+
+  test("two candidate lists are ambiguous, so neither wins", () => {
+    const payload = { data: { outputs: [{ a: 1 }], dependencies: [{ b: 2 }] } }
+    expect(renderOutput(payload, "csv").split("\n")[0]).toBe("outputs,dependencies")
+    expect(rowCount(renderOutput(payload, "csv"), "csv")).toBe(1)
+  })
+
+  test("a nested object sibling means this is a detail payload", () => {
+    const payload = { data: { task_id: 7, source: { datasource: "ds" }, dependencies: [{ b: 2 }] } }
+    expect(renderOutput(payload, "csv").split("\n")[0]).toBe("task_id,source,dependencies")
+    expect(rowCount(renderOutput(payload, "csv"), "csv")).toBe(1)
+  })
+
+  test("an empty list is not evidence of a list payload", () => {
+    const payload = { data: { name: "s", tables: [] } }
+    expect(renderOutput(payload, "text")).toBe("s\t[]")
+  })
+})
+
+describe("a payload that merely CONTAINS a grid is not the grid", () => {
+  // `sql --batch` writes one record per statement, carrying the identity of that
+  // statement alongside its result. Claiming it as the table dropped index/sql/time_ms
+  // and rendered a DDL statement (no columns) as a blank line.
+  const batchLine = { index: 1, sql: "select 1", columns: ["v"], rows: [[1]], count: 1, time_ms: 5 }
+
+  test("a batch record keeps the fields that say which statement it is", () => {
+    for (const format of ["csv", "table", "text"] as const) {
+      const out = renderOutput(batchLine, format)
+      expect(out).toContain("select 1")
+      expect(out).toContain("index")
+    }
+  })
+
+  test("a DDL batch record does not render as an empty line", () => {
+    const ddl = { index: 2, sql: "create table t(a int)", columns: [], rows: [], count: 0, time_ms: 7 }
+    expect(renderOutput(ddl, "csv")).not.toBe("")
+    expect(renderOutput(ddl, "csv")).toContain("create table")
+  })
+
+  test("the bare successRows envelope is still projected", () => {
+    expect(renderOutput({ columns: ["a"], rows: [[1]], count: 1, time_ms: 3 }, "csv")).toBe("a\n1")
+  })
+
+  test("an ai_message rides along without disqualifying the envelope", () => {
+    expect(renderOutput({ columns: ["a"], rows: [[1]], ai_message: "hi" }, "csv")).toBe("a\n1")
+  })
+})
+
+describe("scalar lists keep every value addressable", () => {
+  // schema describe's `tables` and task cron-preview's `next_runs` are lists of plain
+  // values; the cell grammar quotes what would otherwise read as another type.
+  test("null becomes NULL and ambiguous strings are quoted, per cell grammar", () => {
+    expect(renderOutput({ data: { name: "s", tables: ["t1", null, "123", ""] } }, "text", undefined, "tables"))
+      .toBe('t1\nNULL\n"123"\n""')
+  })
+
+  test("csv names the column after the declared key", () => {
+    expect(renderOutput({ data: { cron: "x", next_runs: ["2026-08-22"] } }, "csv", undefined, "next_runs"))
+      .toBe("next_runs\n2026-08-22")
+  })
+})
+
+describe("rowsKey: the command declares which field holds the list", () => {
+  test("records under the declared key become the rows", () => {
+    const payload = { data: { task_id: 9, tables: [{ id: 1, name: "t1" }, { id: 2, name: "t2" }] } }
+    expect(renderOutput(payload, "csv", undefined, "tables")).toBe("id,name\n1,t1\n2,t2")
+  })
+
+  test("plain values under the declared key become a column named after it", () => {
+    const payload = { data: { cron: "0 0 * * *", next_runs: ["2026-08-22", "2026-08-23"], count: 2 } }
+    expect(renderOutput(payload, "csv", undefined, "next_runs")).toBe("next_runs\n2026-08-22\n2026-08-23")
+    expect(renderOutput(payload, "text", undefined, "next_runs")).toBe("2026-08-22\n2026-08-23")
+  })
+
+  test("scalar siblings are not part of the projected table", () => {
+    const payload = { data: { region: "cn", instances: [{ id: 1 }], count: 1 } }
+    expect(renderOutput(payload, "csv", undefined, "instances")).toBe("id\n1")
+  })
+
+  test("a declared key that is absent leaves the single-row rendering", () => {
+    const payload = { data: { region: "cn", instances: [{ id: 1 }] } }
+    expect(renderOutput(payload, "csv", undefined, "missing").split("\n")[0]).toBe("region,instances")
+  })
+
+  test("a declared key that is not a list leaves the single-row rendering", () => {
+    const payload = { data: { region: "cn", instances: { id: 1 } } }
+    expect(renderOutput(payload, "csv", undefined, "region")).toBe("region,instances\ncn,\"{\"\"id\"\":1}\"")
+  })
+
+  test("a declared key holding an empty list renders nothing", () => {
+    const payload = { data: { task_id: 9, tables: [] } }
+    for (const format of ROW_FORMATS) expect(renderOutput(payload, format, undefined, "tables")).toBe("")
+  })
+
+  test("json output ignores rowsKey entirely", () => {
+    const payload = { data: { task_id: 9, tables: [{ id: 1 }] } }
+    expect(renderOutput(payload, "json", undefined, "tables")).toBe('{"data":{"task_id":9,"tables":[{"id":1}]}}')
+  })
+})
+
+describe("ragged records", () => {
+  const payload = { data: [{ a: 1 }, { b: 2 }] }
+
+  test("columns are the union of all keys, in first-appearance order", () => {
+    expect(renderOutput(payload, "csv")).toBe("a,b\n1,NULL\nNULL,2")
+  })
+
+  test("jsonl emits the original objects rather than padded reconstructions", () => {
+    expect(renderOutput(payload, "jsonl")).toBe('{"a":1}\n{"b":2}')
+  })
+})
+
+describe("lists of plain values", () => {
+  const payload = { data: ["one", "two"], count: 2 }
+
+  test("csv names the single column 'value'", () => {
+    expect(renderOutput(payload, "csv")).toBe("value\none\ntwo")
+  })
+
+  test("text prints one value per line", () => {
+    expect(renderOutput(payload, "text")).toBe("one\ntwo")
+  })
+
+  test("text quotes values that would otherwise read as another type", () => {
+    // Same rule as any other cell: "NULL" the string must not look like NULL.
+    expect(renderOutput({ data: ["NULL", "1", "x"] }, "text")).toBe('"NULL"\n"1"\nx')
+  })
+
+  test("jsonl emits one value per line", () => {
+    expect(renderOutput(payload, "jsonl")).toBe('"one"\n"two"')
+  })
+})
+
+describe("empty and non-tabular payloads", () => {
+  test("an empty list renders nothing in every row format", () => {
+    for (const format of ROW_FORMATS) expect(renderOutput({ data: [], count: 0 }, format)).toBe("")
+  })
+
+  test("an empty result object renders an empty single row", () => {
+    expect(renderOutput({ data: {} }, "text")).toBe("")
+  })
+
+  test("a payload with no data key falls back to JSON, per format's own habit", () => {
+    // text/jsonl are machine-facing and stay on one line; table/csv are read by
+    // people and indent. e2e-routing parses the text fallback as JSON.
+    expect(renderOutput({ note: "hi" }, "text")).toBe('{"note":"hi"}')
+    expect(renderOutput({ note: "hi" }, "jsonl")).toBe('{"note":"hi"}')
+    expect(renderOutput({ note: "hi" }, "table")).toBe('{\n  "note": "hi"\n}')
+    expect(renderOutput({ note: "hi" }, "csv")).toBe('{\n  "note": "hi"\n}')
+  })
+
+  test("a scalar data value falls back the same way", () => {
+    expect(renderOutput({ data: "hi" }, "text")).toBe('{"data":"hi"}')
+  })
+
+  test("an error envelope in a row format is left to the error renderer", () => {
+    // error() routes through renderErrorOutput, which prints the ERROR line; a
+    // raw renderOutput call (the startup gates in run-cli.ts) still gets JSON.
+    expect(renderOutput({ error: { code: "NO_LLM_CONFIGURED", message: "none" } }, "text")).toBe(
+      '{"error":{"code":"NO_LLM_CONFIGURED","message":"none"}}',
+    )
+  })
+})
+
+describe("the SQL envelope (columns + rows) is already a table", () => {
+  const payload = { columns: ["id", "name"], rows: [[1, "a"], [2, "b"]], count: 2 }
+
+  test("all four row formats project it identically", () => {
+    expect(renderOutput(payload, "csv")).toBe("id,name\n1,a\n2,b")
+    expect(renderOutput(payload, "text")).toBe("1\ta\n2\tb")
+    expect(renderOutput(payload, "jsonl")).toBe('{"id":1,"name":"a"}\n{"id":2,"name":"b"}')
+    expect(rowCount(renderOutput(payload, "table"), "table")).toBe(2)
+  })
+
+  test("zero rows still print the header for table and csv", () => {
+    const empty = { columns: ["id"], rows: [], count: 0 }
+    expect(renderOutput(empty, "csv")).toBe("id")
+    expect(renderOutput(empty, "table")).toBe("id\n--")
+    expect(renderOutput(empty, "text")).toBe("")
+  })
+})
+
+/**
+ * The shapes real commands actually emit, mirrored by hand from their `success()`
+ * call sites (path:line in each case). These are fixtures, not introspection: if
+ * a command's payload changes, its entry here has to change with it. What they
+ * buy is a single place that answers "does every list-shaped payload in this CLI
+ * still render as rows, and does every single-result payload still render as one
+ * row" — the audit that found the `auth list` bug, frozen as a test.
+ */
+describe("catalog of real command payload shapes", () => {
+  const cases: {
+    site: string
+    payload: Record<string, unknown>
+    rowsKey?: string
+    rows: number
+    /** Set where a JSON-in-a-cell rendering is the honest answer, with the reason. */
+    jsonCells?: string
+  }[] = [
+    {
+      site: "auth.ts:207 — auth list (list is the payload)",
+      payload: { data: [{ session: "uat", active: true, profiles: ["uat_0"] }], count: 1, active_session: "uat" },
+      rows: 1,
+    },
+    {
+      site: "auth.ts:167 — auth logout (single result)",
+      payload: { data: { logged_out: true, session: "uat", token_removed: true, profiles_removed: ["uat_0"] } },
+      rows: 1,
+    },
+    {
+      site: "auth.ts:232 — auth status (single result)",
+      payload: { data: { logged_in: true, active_profile: "uat_0", session: "uat", expired: false } },
+      rows: 1,
+    },
+    {
+      site: "profile.ts:222 — profile list (list is the payload)",
+      payload: { data: [{ name: "a", is_default: true }, { name: "b", is_default: false }], count: 2 },
+      rows: 2,
+    },
+    {
+      site: "schema.ts:78 — schema describe",
+      payload: { data: { name: "s", type: "MANAGED", table_count: 2, tables: [{ name: "t1" }, { name: "t2" }] } },
+      rowsKey: "tables",
+      rows: 2,
+    },
+    {
+      site: "sql.ts:599 — sql --dry-run over multiple statements",
+      payload: { data: { statements: [{ sql: "select 1", status: "ok" }, { sql: "select 2", status: "ok" }], count: 2 } },
+      rowsKey: "statements",
+      rows: 2,
+    },
+    {
+      site: "analytics-agent.ts:1115 — batch enable/disable",
+      payload: { data: { total: 2, succeeded: 1, failed: 1, skipped: 0, results: [{ id: 1, result: "ok" }, { id: 2, result: "failed" }] } },
+      rowsKey: "results",
+      rows: 2,
+    },
+    {
+      site: "task.ts:509 — task cdc list",
+      payload: { data: { tasks: [{ id: 1, name: "t" }] } },
+      rowsKey: "tasks",
+      rows: 1,
+    },
+    {
+      site: "task.ts:538 — task cdc tables",
+      payload: { data: { task_id: 7, tables: [{ id: 1, name: "t1" }, { id: 2, name: "t2" }] } },
+      rowsKey: "tables",
+      rows: 2,
+    },
+    {
+      site: "task.ts:4204 — task cron-preview (list of plain values)",
+      payload: { data: { cron: "0 0 * * *", next_runs: ["2026-08-22", "2026-08-23"], count: 2 } },
+      rowsKey: "next_runs",
+      rows: 2,
+    },
+    {
+      site: "profile-bootstrap.ts:725 — profile list-workspaces (two lists, one declared)",
+      payload: {
+        data: {
+          region: "cn",
+          instances: [{ instance_name: "i1" }, { instance_name: "i2" }],
+          workspaces_by_instance: { i1: ["ws"], i2: [] },
+        },
+      },
+      rowsKey: "instances",
+      rows: 2,
+    },
+    {
+      site: "datasource.ts:581 — datasource check",
+      payload: { data: { datasource: "ds", ds_type: 3, checks: [{ check: "binlog", ok: true }], ready: true } },
+      rowsKey: "checks",
+      rows: 1,
+    },
+    {
+      site: "task.ts:473 — task cdc table op (ids are not rows)",
+      payload: { data: { task_id: 7, action: "start", table_ids: [1, 2, 3], result: true } },
+      rows: 1,
+    },
+    {
+      site: "dqc.ts:288 — dqc update (changed field names are not rows)",
+      payload: { data: { rule_id: 5, updated: ["sql", "checker"] } },
+      rows: 1,
+    },
+    {
+      site: "task.ts:2620 — task lineage (two candidate lists, so one row)",
+      payload: { data: { task_id: 7, outputs: [{ table: "a" }], dependencies: [{ task: "b" }] } },
+      rows: 1,
+      jsonCells: "upstream and downstream are two tables; a row format can only pick one, so it picks neither. Declare rowsKey to choose.",
+    },
+    {
+      site: "integration.ts:1188 — sync detail (no rowsKey, so one row)",
+      payload: { data: { task_id: 7, sync_type: "single", column_mapping: [{ src: "a", dst: "b" }, { src: "c", dst: "d" }] } },
+      rows: 1,
+      jsonCells: "the mapping is one field of a task-creation result, not the result; it renders as a cell until a maintainer decides otherwise",
+    },
+    {
+      site: "status.ts:35 — status (flat single result)",
+      payload: { data: { connected: true, workspace: "ws", schema: "public", cli_version: "1.0.0" } },
+      rows: 1,
+    },
+  ]
+
+  for (const { site, payload, rowsKey, rows, jsonCells } of cases) {
+    test(site, () => {
+      for (const format of ROW_FORMATS) {
+        const out = renderOutput(payload, format, undefined, rowsKey)
+        expect(rowCount(out, format), `${format} row count`).toBe(rows)
+        // No row format may hide a list of records inside a single cell, except
+        // where the payload itself is genuinely ambiguous (see jsonCells).
+        if (!jsonCells) expect(out, `${format} has a JSON list in a cell`).not.toMatch(/\[\{|\[\\?"\{/)
+      }
+    })
+  }
+})
diff --git a/packages/cz-cli/test/parameter-hardening.test.ts b/packages/cz-cli/test/parameter-hardening.test.ts
new file mode 100644
index 0000000000..f876175c8c
--- /dev/null
+++ b/packages/cz-cli/test/parameter-hardening.test.ts
@@ -0,0 +1,777 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { coalesceJsonArrayOptionArgs } from "../src/cli.ts"
+
+/**
+ * Argument-surface hardening: one describe per defect, each named after what used
+ * to happen. Every case runs the real binary, because all of these were failures
+ * of the parser boundary rather than of a command's logic.
+ *
+ * The profile in the fixture points at an unroutable host on purpose: a case that
+ * reaches the network has passed the parser, and CONNECTION_ERROR/TASK_ERROR is
+ * therefore the "accepted" outcome these tests assert against.
+ */
+
+const PROFILES = `default_profile = "p1"
+
+[oauth.sess]
+expire_time_ms = 3600000
+obtained_at = 1000000000000
+
+[profiles.p1]
+instance = "inst"
+service = "api.invalid.example.com"
+workspace = "ws"
+schema = "public"
+vcluster = "default"
+pat = "pat-token"
+oauth = "sess"
+
+[profiles.p2]
+instance = "inst2"
+service = "api.invalid.example.com"
+workspace = "ws2"
+pat = "pat-token-2"
+`
+
+function makeHome(profiles = PROFILES): string {
+  const home = mkdtempSync(join(tmpdir(), "cz-argsafe-"))
+  mkdirSync(join(home, ".clickzetta"), { recursive: true })
+  writeFileSync(join(home, ".clickzetta", "profiles.toml"), profiles)
+  return home
+}
+
+const HOME = makeHome()
+
+/**
+ * bun's 5s default is too tight for two kinds of case here: one that passes the
+ * parser and waits for the unroutable host's socket to fail, and one that boots the
+ * agent runtime (which imports opencode before it can even report a bad flag).
+ */
+const SLOW_SPAWN = 60_000
+
+/**
+ * Same two invocation modes as the e2e runners: from source under bun by default,
+ * or the compiled binary when CZ_CLI_BIN points at one (`test:ci`). A compiled
+ * binary has the entry baked in and takes no entry argument — passing one turns the
+ * path into a bogus first positional.
+ */
+const BINARY = process.env.CZ_CLI_BIN ?? "bun"
+const BINARY_ENTRY = process.env.CZ_CLI_BIN ? [] : ["./src/main.ts"]
+
+function run(args: string[], env: Record<string, string> = {}, home = HOME) {
+  const result = spawnSync(BINARY, [...BINARY_ENTRY, ...args], {
+    cwd: import.meta.dir + "/..",
+    encoding: "utf-8",
+    env: { ...process.env, HOME: home, CLICKZETTA_TEST_HOME: home, NO_COLOR: "1", ...env },
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 60_000,
+  })
+  return {
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+    exitCode: result.status ?? 1,
+  }
+}
+
+function errorOf(stdout: string): Record<string, any> {
+  try {
+    return (JSON.parse(stdout.split("\n")[0] ?? "{}") as Record<string, any>).error ?? {}
+  } catch {
+    return {}
+  }
+}
+
+/** A stack trace on stderr means an exception escaped instead of being reported. */
+function hasStackTrace(stderr: string): boolean {
+  return /\n\s+at\s/.test(stderr) || stderr.includes("Bun v")
+}
+
+describe("a repeated scalar option used to become an array", () => {
+  test("--field twice takes the last one instead of crashing in extractField", () => {
+    const r = run(["auth", "list", "--field", "sessions", "--field", "active_profile"])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toBe("p1")
+    expect(hasStackTrace(r.stderr)).toBe(false)
+  })
+
+  test("--protocol twice no longer reaches normalizeProtocol as an array", () => {
+    const r = run(["status", "--protocol", "http", "--protocol", "https"])
+    expect(r.stdout).not.toContain("toLowerCase is not a function")
+  }, SLOW_SPAWN)
+
+  test("--format twice honors the last value instead of silently falling back to json", () => {
+    const r = run(["auth", "list", "--format", "json", "--format", "text"])
+    expect(r.stdout.startsWith("{")).toBe(false)
+    expect(r.stdout.split("\t")[0]).toBe("sess")
+  })
+
+  test("--profile twice selects the last profile rather than none", () => {
+    // p2 exists, so the run gets as far as the network; the old array form
+    // resolved to no profile at all and reported a missing workspace.
+    const r = run(["status", "--profile", "p1", "--profile", "p2", "--field", "error"])
+    expect(r.stdout).not.toContain("Workspace is required")
+  }, SLOW_SPAWN)
+
+  test("an option declared repeatable still collects every value", () => {
+    const home = makeHome()
+    const created = run([
+      "profile", "create", "multi",
+      "--instance", "i", "--service", "s", "--workspace", "w", "--pat", "t",
+      "--header", "A=1", "--header", "B=2", "--skip-verify",
+    ], {}, home)
+    expect(created.exitCode).toBe(0)
+    const detail = run(["profile", "detail", "multi", "--format", "json"], {}, home)
+    expect(detail.stdout).toContain('"A":"1"')
+    expect(detail.stdout).toContain('"B":"2"')
+  }, SLOW_SPAWN)
+})
+
+describe("a numeric option fed junk used to become NaN silently", () => {
+  test("--count abc is a usage error instead of an empty answer", () => {
+    const r = run(["task", "cron-preview", "0 0 * * *", "--count", "abc"])
+    expect(r.exitCode).toBe(2)
+    expect(errorOf(r.stdout).code).toBe("USAGE_ERROR")
+    expect(errorOf(r.stdout).message).toContain("--count")
+  })
+
+  test("the message names the flag as the user typed it, not camelCased", () => {
+    const r = run(["task", "cdc", "list", "--page-size", "zz"])
+    expect(errorOf(r.stdout).message).toContain("--page-size")
+    expect(errorOf(r.stdout).message).not.toContain("pageSize")
+  })
+
+  test("a valid number is untouched (the guard does not false-positive)", () => {
+    const r = run(["task", "cron-preview", "0 0 * * *", "--count", "3"])
+    expect(errorOf(r.stdout).code).not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+
+  test("the usage error renders as a row in row-oriented formats", () => {
+    const r = run(["sql", "select 1", "--timeout", "abc", "--format", "text"])
+    expect(r.stdout).toBe("ERROR USAGE_ERROR: Invalid number value for: --timeout")
+  }, SLOW_SPAWN)
+})
+
+describe("an empty option value used to overwrite the profile", () => {
+  test("--workspace with no value leaves the profile's workspace in place", () => {
+    const r = run(["status", "--workspace", "", "--field", "error"])
+    expect(r.stdout).not.toContain("Workspace is required")
+  }, SLOW_SPAWN)
+
+  test("--instance with no value leaves the profile's instance in place", () => {
+    const r = run(["status", "--instance", "", "--field", "error"])
+    expect(r.stdout).not.toContain("Instance is required")
+  }, SLOW_SPAWN)
+})
+
+describe("a mistyped --profile used to be reported as missing credentials", () => {
+  test("the error names the profile and the way to list them", () => {
+    const r = run(["status", "--profile", "ghost"])
+    expect(r.exitCode).toBe(1)
+    expect(errorOf(r.stdout).code).toBe("PROFILE_NOT_FOUND")
+    expect(errorOf(r.stdout).message).toContain("ghost")
+  })
+
+  test("CZ_PROFILE naming a missing profile is caught on a connecting command", () => {
+    expect(errorOf(run(["status"], { CZ_PROFILE: "ghost" }).stdout).code).toBe("PROFILE_NOT_FOUND")
+  })
+
+  // The guard is keyed on "does this invocation connect", not on "was a profile
+  // named". Keyed the other way, a stale CZ_PROFILE — a profile deleted while still
+  // exported in the shell — failed the very commands that fix it, including the
+  // `cz-cli profile list` the error message recommends.
+  test("a stale CZ_PROFILE leaves the recovery path working", () => {
+    const ghost = { CZ_PROFILE: "ghost" }
+    expect(run(["profile", "list", "--field", "name"], ghost).stdout).toBe("p1")
+    expect(run(["--version"], ghost).exitCode).toBe(0)
+    expect(errorOf(run(["auth", "list"], ghost).stdout).code).toBeUndefined()
+  })
+
+  test("a typed name is reported even on a command that never connects", () => {
+    // Typed, so it is a typo wherever it appears — unlike an inherited CZ_PROFILE,
+    // which such a command still ignores (see the recovery-path test above).
+    expect(errorOf(run(["auth", "list", "--profile", "ghost"]).stdout).code).toBe("PROFILE_NOT_FOUND")
+  })
+
+  test("a profile-creating command still accepts a name that does not exist yet", () => {
+    const home = makeHome()
+    const r = run([
+      "profile", "create", "brandnew",
+      "--instance", "i", "--service", "s", "--workspace", "w", "--pat", "t", "--skip-verify",
+    ], { CZ_PROFILE: "ghost" }, home)
+    expect(r.exitCode).toBe(0)
+  }, SLOW_SPAWN)
+
+  test("row-oriented formats get the one-line form", () => {
+    const r = run(["status", "--profile", "ghost", "--format", "text"])
+    expect(r.stdout.startsWith("ERROR PROFILE_NOT_FOUND:")).toBe(true)
+  })
+
+  test("--help is never blocked by it", () => {
+    expect(run(["status", "--profile", "ghost", "--help"]).exitCode).toBe(0)
+  })
+
+  test("the commands that CREATE a profile still accept a new name", () => {
+    // `login`/`setup` take the name they are about to create; --profile is hidden
+    // there and must not be validated against what exists today.
+    expect(run(["login", "--profile", "brandnew", "--help"]).exitCode).toBe(0)
+    expect(run(["setup", "--profile", "brandnew", "--help"]).exitCode).toBe(0)
+  })
+})
+
+describe("a bad --file used to print a stack trace and nothing on stdout", () => {
+  test("an unreadable path is a named error on stdout", () => {
+    const r = run(["sql", "--file", "/nonexistent.sql"])
+    expect(r.exitCode).toBe(1)
+    expect(errorOf(r.stdout).code).toBe("FILE_READ_ERROR")
+    expect(errorOf(r.stdout).message).toContain("/nonexistent.sql")
+    expect(hasStackTrace(r.stderr)).toBe(false)
+  })
+
+  test("the positional statement wins over --file, as --help documents", () => {
+    // Priority is positional > -e/--execute > -f/--file: a broken --file next to a
+    // real statement must therefore not be read at all.
+    const r = run(["sql", "select 1", "--file", "/nonexistent.sql"])
+    expect(errorOf(r.stdout).code).not.toBe("FILE_READ_ERROR")
+  }, SLOW_SPAWN)
+})
+
+describe("an unhandled exception used to escape as a bare stack", () => {
+  test("a throw from the pre-command connection setup renders as an envelope", () => {
+    // An invalid auth_type throws from resolveConnectionConfig, which the CLI first
+    // calls before any command's try/catch when a connection flag is present.
+    const home = makeHome(`default_profile = "bad"
+
+[profiles.bad]
+instance = "i"
+service = "api.invalid.example.com"
+workspace = "w"
+pat = "t"
+auth_type = "passwrod"
+`)
+    const r = run(["status", "--instance", "other"], {}, home)
+    expect(r.exitCode).toBe(1)
+    expect(errorOf(r.stdout).code).toBe("INVALID_AUTH_TYPE")
+    expect(hasStackTrace(r.stderr)).toBe(false)
+  })
+})
+
+describe("`--` operands used to be dropped", () => {
+  test("sql -- <statement> reaches the statement", () => {
+    const r = run(["sql", "--", "select 1"])
+    expect(errorOf(r.stdout).message).not.toContain("No SQL statements found")
+  }, SLOW_SPAWN)
+
+  test("an empty invocation still reports no statement", () => {
+    expect(errorOf(run(["sql"]).stdout).message).toContain("No SQL statements found")
+  })
+})
+
+describe("a fragmented JSON value used to swallow the next positional", () => {
+  test("the positional survives when the JSON arrives split on its inner space", () => {
+    const r = run([
+      "task", "save-cron",
+      "--output-tables", '[{"outputTableName": "a"}]',
+      "mytask", "--cron", "0 30 9 * * ? *",
+    ])
+    expect(errorOf(r.stdout).message ?? "").not.toContain("Not enough non-option arguments")
+  }, SLOW_SPAWN)
+})
+
+describe("usage errors follow the chosen format", () => {
+  test("a mistyped flag is one ERROR row under --format text", () => {
+    // It used to answer with a JSON envelope, so a text-mode caller had to handle
+    // two error shapes: this one and error()'s ERROR line.
+    const r = run(["schema", "list", "--limt", "5", "--format", "text"])
+    expect(r.exitCode).toBe(2)
+    expect(r.stdout).toBe("ERROR USAGE_ERROR: Unknown argument: limt")
+  })
+
+  test("the suggestion is carried into the row form too", () => {
+    const r = run(["schema", "list", "--formt", "json", "--format", "text"])
+    expect(r.stdout).toBe("ERROR USAGE_ERROR: Unknown argument: formt. Did you mean '--format'?")
+  })
+
+  test("json keeps the structured shape, did_you_mean included", () => {
+    const e = errorOf(run(["schema", "list", "--formt", "json"]).stdout)
+    expect(e.code).toBe("USAGE_ERROR")
+    expect(e.did_you_mean).toBe("--format")
+  })
+})
+
+describe("status reports its outcome in the exit code", () => {
+  test("an unreachable instance exits non-zero while still describing itself", () => {
+    const r = run(["status"])
+    expect(r.exitCode).toBe(1)
+    expect(JSON.parse(r.stdout).data.connected).toBe(false)
+  }, SLOW_SPAWN)
+})
+
+describe("the agent subtree used to localize its messages", () => {
+  // robustness.test.ts #6 pins this for the cz command tree. The agent tree runs on
+  // its own yargs instances (bootstrap/runtime.ts, commands/agent-llm.ts), which had
+  // no .locale("en"), so the same command answered in Chinese on a zh_CN machine.
+  const ZH = { LANG: "zh_CN.UTF-8", LC_ALL: "zh_CN.UTF-8" }
+
+  test("an invalid choice on an agent command stays English", () => {
+    const r = run(["agent", "session", "list", "--format", "csv"], ZH)
+    expect(r.stdout).not.toMatch(/[一-鿿]/)
+    expect(r.stdout).toContain("Invalid values")
+  }, SLOW_SPAWN)
+
+  test("an unknown flag on agent llm stays English", () => {
+    const r = run(["agent", "llm", "show", "--bogus"], ZH)
+    expect(r.stdout).not.toMatch(/[一-鿿]/)
+  }, SLOW_SPAWN)
+
+  test("agent llm help stays English", () => {
+    const r = run(["agent", "llm"], ZH)
+    expect(r.stdout).not.toMatch(/[一-鿿]/)
+    expect(r.stdout).toContain("Commands:")
+  }, SLOW_SPAWN)
+})
+
+describe("agent llm used to turn its own help into an error", () => {
+  test("a bare group prints help and exits 0, like every other group", () => {
+    const r = run(["agent", "llm"])
+    expect(r.exitCode).toBe(0)
+    expect(r.stderr).not.toContain("subcommand help shown")
+  }, SLOW_SPAWN)
+
+  test("an unknown flag is reported once, on stdout", () => {
+    const r = run(["agent", "llm", "show", "--bogus"])
+    expect(r.exitCode).toBe(2)
+    expect(errorOf(r.stdout).code).toBe("USAGE_ERROR")
+    expect(r.stderr).not.toContain("Error:")
+  }, SLOW_SPAWN)
+})
+
+describe("serve used to accept a mistyped flag and start anyway", () => {
+  test("an unknown flag is rejected instead of starting on a random port", () => {
+    // The default port is 0, so a swallowed --port typo meant a server on an
+    // unpredictable port. If this ever regresses the process would not exit and the
+    // timeout below is what fails.
+    const r = run(["serve", "--prot", "45999"])
+    expect(r.exitCode).not.toBe(0)
+    expect(r.stdout + r.stderr).toContain("prot")
+    expect(r.stdout + r.stderr).not.toContain("listening")
+  }, SLOW_SPAWN)
+
+  test("the flags upstream's root parser owns are declared, not swallowed", () => {
+    const help = run(["serve", "--help"])
+    expect(help.stdout).toContain("--print-logs")
+    expect(help.stdout).toContain("--log-level")
+    expect(help.stdout).toContain("--pure")
+    expect(help.stdout).not.toMatch(/[一-鿿]/)
+  }, SLOW_SPAWN)
+})
+
+describe("coalesceJsonArrayOptionArgs (unit)", () => {
+  test("merges the fragments of one split JSON value and stops there", () => {
+    expect(
+      coalesceJsonArrayOptionArgs(["--output-tables", '[{"outputTableName":', '"a"}]', "mytask"]),
+    ).toEqual(["--output-tables", '[{"outputTableName":"a"}]', "mytask"])
+  })
+
+  test("leaves an already-closed value alone", () => {
+    expect(coalesceJsonArrayOptionArgs(["--output-tables", "[]", "mytask"])).toEqual([
+      "--output-tables", "[]", "mytask",
+    ])
+  })
+
+  test("a bracket inside a string does not end the value early", () => {
+    expect(coalesceJsonArrayOptionArgs(["--output-tables", '[{"n":', '"a]b"}]', "task"])).toEqual([
+      "--output-tables", '[{"n":"a]b"}]', "task",
+    ])
+  })
+
+  test("a value that is not JSON at all absorbs nothing", () => {
+    expect(coalesceJsonArrayOptionArgs(["--output-tables", "nonsense", "mytask"])).toEqual([
+      "--output-tables", "nonsense", "mytask",
+    ])
+  })
+
+  test("the inline --opt=value form works the same way", () => {
+    expect(coalesceJsonArrayOptionArgs(['--output-tables=[{"n":', '1}]', "mytask"])).toEqual([
+      '--output-tables=[{"n":1}]', "mytask",
+    ])
+  })
+
+  test("unrelated arguments pass through untouched", () => {
+    const args = ["sql", "select 1", "--format", "json"]
+    expect(coalesceJsonArrayOptionArgs(args)).toEqual(args)
+  })
+})
+
+describe("the last-resort envelope does not swallow the legitimate sentinels", () => {
+  test("a bare command group still renders help and exits 0", () => {
+    // The group threw SubcommandHelpShown with exit 0 — reporting that as
+    // INTERNAL_ERROR is exactly what the net must not do.
+    const r = run(["mcp"])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout).toContain("Commands:")
+    expect(r.stdout).not.toContain("INTERNAL_ERROR")
+  }, SLOW_SPAWN)
+
+  test("an error the command already reported is not reported twice", () => {
+    // handledError() prints the envelope and throws HandledCliError.
+    const r = run(["sql", "--file", "/nonexistent.sql"])
+    expect(r.stdout.split("\n")).toHaveLength(1)
+    expect(r.stdout).not.toContain("INTERNAL_ERROR")
+  })
+
+  test("--debug adds the stack on stderr, and only then", () => {
+    const home = makeHome(`default_profile = "bad"
+
+[profiles.bad]
+instance = "i"
+service = "api.invalid.example.com"
+workspace = "w"
+pat = "t"
+auth_type = "passwrod"
+`)
+    const plain = run(["status", "--instance", "other"], {}, home)
+    expect(hasStackTrace(plain.stderr)).toBe(false)
+
+    const debug = run(["status", "--instance", "other", "--debug"], {}, home)
+    expect(errorOf(debug.stdout).code).toBe("INVALID_AUTH_TYPE")
+    expect(debug.stderr).toContain("resolveConnectionConfig")
+  })
+})
+
+describe("the numeric guard's edges", () => {
+  test("a negative value is a number, not junk", () => {
+    const r = run(["task", "cron-preview", "0 0 * * *", "--count", "-3"])
+    expect(errorOf(r.stdout).code).not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+
+  test("a fractional value is a number, not junk", () => {
+    const r = run(["task", "cron-preview", "0 0 * * *", "--count", "2.5"])
+    expect(errorOf(r.stdout).code).not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+
+  test("one bad element rejects a repeatable numeric option", () => {
+    const r = run([
+      "analytics-agent", "knowledge", "update", "1",
+      "--domain-id", "7", "--domain-id", "seven",
+    ])
+    expect(errorOf(r.stdout).code).toBe("USAGE_ERROR")
+    expect(errorOf(r.stdout).message).toContain("--domain-id")
+  }, SLOW_SPAWN)
+
+  test("all-numeric elements pass through as a list", () => {
+    const r = run([
+      "analytics-agent", "knowledge", "update", "1",
+      "--domain-id", "7", "--domain-id", "8",
+    ])
+    expect(errorOf(r.stdout).code).not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+})
+
+describe("sql input priority, in the order --help documents", () => {
+  test("-e/--execute wins over --file", () => {
+    const r = run(["sql", "-e", "select 1", "--file", "/nonexistent.sql"])
+    expect(errorOf(r.stdout).code).not.toBe("FILE_READ_ERROR")
+  }, SLOW_SPAWN)
+
+  test("--file is still read when it is the only input", () => {
+    const r = run(["sql", "--file", "/nonexistent.sql"])
+    expect(errorOf(r.stdout).code).toBe("FILE_READ_ERROR")
+  })
+
+  test("a statement starting with a dash goes through `--`", () => {
+    const r = run(["sql", "--", "-- a comment\nselect 1"])
+    expect(errorOf(r.stdout).message ?? "").not.toContain("No SQL statements found")
+  }, SLOW_SPAWN)
+})
+
+describe("the onboarding gates deliberately keep their structured payload", () => {
+  // Unlike every other error, NO_PROFILE / NO_LLM_CONFIGURED carry next_steps and
+  // register_urls — guidance a one-line ERROR row would drop. This is the documented
+  // exception to "usage errors follow the chosen format"; pinning it here so the
+  // exception is a decision rather than something that quietly drifts either way.
+  const emptyHome = mkdtempSync(join(tmpdir(), "cz-argsafe-empty-"))
+
+  test("NO_PROFILE stays JSON even under --format text", () => {
+    const r = run(["status", "--format", "text"], {}, emptyHome)
+    expect(r.exitCode).toBe(1)
+    const parsed = JSON.parse(r.stdout) as Record<string, any>
+    expect(parsed.error.code).toBe("NO_PROFILE")
+    expect(Array.isArray(parsed.error.next_steps)).toBe(true)
+  })
+
+  test("NO_LLM_CONFIGURED stays JSON even under --format text", () => {
+    const r = run(["agent", "run", "--format", "text", "hello"], {}, emptyHome)
+    const parsed = JSON.parse(r.stdout) as Record<string, any>
+    expect(parsed.error.code).toBe("NO_LLM_CONFIGURED")
+  }, SLOW_SPAWN)
+})
+
+describe("serve's logging flags are wired, not just declared", () => {
+  // The flag surface is asserted through --help above; this covers the other half —
+  // that a declared flag actually reaches the env var opencode reads. Kept as a unit
+  // test because the alternative is booting a server to observe its log output.
+  const ENV_KEYS = ["OPENCODE_PRINT_LOGS", "OPENCODE_LOG_LEVEL", "OPENCODE_PURE"] as const
+  const saved = new Map<string, string | undefined>()
+
+  beforeEach(async () => {
+    for (const key of ENV_KEYS) {
+      saved.set(key, process.env[key])
+      delete process.env[key]
+    }
+  })
+
+  afterEach(() => {
+    for (const key of ENV_KEYS) {
+      const previous = saved.get(key)
+      if (previous === undefined) delete process.env[key]
+      else process.env[key] = previous
+    }
+  })
+
+  test("--print-logs and --log-level reach opencode's env", async () => {
+    const { applyServeLogFlags } = await import("../src/bootstrap/runtime.ts")
+    applyServeLogFlags({ "print-logs": true, "log-level": "DEBUG" })
+    expect(process.env.OPENCODE_PRINT_LOGS).toBe("1")
+    expect(process.env.OPENCODE_LOG_LEVEL).toBe("DEBUG")
+    expect(process.env.OPENCODE_PURE).toBeUndefined()
+  })
+
+  test("--pure reaches opencode's env", async () => {
+    const { applyServeLogFlags } = await import("../src/bootstrap/runtime.ts")
+    applyServeLogFlags({ pure: true })
+    expect(process.env.OPENCODE_PURE).toBe("1")
+  })
+
+  test("absent flags set nothing", async () => {
+    const { applyServeLogFlags } = await import("../src/bootstrap/runtime.ts")
+    applyServeLogFlags({})
+    for (const key of ENV_KEYS) expect(process.env[key]).toBeUndefined()
+  })
+})
+
+describe("the agent path validates its own numeric flag", () => {
+  // `--timeout` is cz's flag, so unlike the rest of the agent tree it is ours to get
+  // right. Its check used to run past the LLM gate, so on a machine with no LLM
+  // registered the bad value was never mentioned at all — the same masking the cz
+  // command tree already forbids for NO_PROFILE.
+  test("--timeout with junk is a usage error, not masked by the LLM gate", () => {
+    const r = run(["agent", "run", "--timeout", "abc", "hello"])
+    expect(r.exitCode).toBe(2)
+    expect(errorOf(r.stdout).code).toBe("USAGE_ERROR")
+    expect(errorOf(r.stdout).message).toContain("--timeout")
+  }, SLOW_SPAWN)
+
+  test("it follows the chosen format like any other usage error", () => {
+    const r = run(["agent", "run", "--timeout", "0", "--format", "text", "hello"])
+    expect(r.stdout).toBe("ERROR USAGE_ERROR: --timeout must be a positive number of seconds")
+  }, SLOW_SPAWN)
+
+  test("a valid --timeout is not touched by the check", () => {
+    const r = run(["agent", "run", "--timeout", "150", "hello"])
+    expect(errorOf(r.stdout).code).not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+})
+
+describe("known sharp edges, pinned so they stay decisions", () => {
+  // yargs-parser accepts only "true"/"false" as a boolean's inline value; anything
+  // else is false. Deliberately NOT changed: it is uniform across the CLI, the
+  // direction is fail-safe (`--dangerously-skip-permissions=1` reads as off), and
+  // overriding it would create a second boolean dialect alongside `--no-x`.
+  test("a boolean flag only accepts =true, and =1/=yes read as off", () => {
+    expect(run(["profile", "list", "--show-secret=true", "--field", "pat"]).stdout).toBe("pat-token")
+    for (const form of ["--show-secret=1", "--show-secret=yes", "--show-secret=maybe"]) {
+      expect(run(["profile", "list", form, "--field", "pat"]).stdout).not.toBe("pat-token")
+    }
+  }, SLOW_SPAWN)
+
+  // An option WITH a default swallows an empty value and falls back to that default;
+  // one WITHOUT a default sees "" and fails its choices check. Both are yargs
+  // semantics, and the empty-means-absent half matches what the connection layer
+  // does with `--workspace ""`. Pinned because the two look inconsistent side by
+  // side, and because a global "empty means absent" rule is NOT available: `ai-gateway
+  // key create --add-to-llm ""` uses the empty string as a real value.
+  test("--format with no value falls back to the default format", () => {
+    const r = run(["auth", "list", "--format"])
+    expect(r.exitCode).toBe(0)
+    expect(r.stdout.startsWith("{")).toBe(true)
+  })
+
+  test("--protocol with no value is rejected, because it has no default", () => {
+    const r = run(["status", "--protocol"])
+    expect(r.exitCode).toBe(2)
+    expect(errorOf(r.stdout).message).toContain("protocol")
+  })
+})
+
+describe("serve keeps the global flags the outer layer already consumed", () => {
+  // `serve` is a RUNTIME_COMMAND: run-cli reads `--profile` off this same argv and
+  // pins it, and re-inserts `--format` after the command word. Turning on .strict()
+  // without declaring them rejected an invocation that works — `--profile` selects
+  // the lakehouse the served agent connects as.
+  function serveProbe(args: string[]): string {
+    const log = join(mkdtempSync(join(tmpdir(), "cz-serve-")), "out.log")
+    const child = spawnSync("bash", [
+      "-c",
+      `${BINARY} ${BINARY_ENTRY.join(" ")} serve ${args.join(" ")} > ${log} 2>&1 & pid=$!; sleep 8; kill -9 $pid 2>/dev/null; cat ${log}`,
+    ], {
+      cwd: import.meta.dir + "/..",
+      encoding: "utf-8",
+      env: { ...process.env, HOME: HOME, CLICKZETTA_TEST_HOME: HOME, NO_COLOR: "1" },
+      timeout: 40_000,
+    })
+    return (child.stdout ?? "") + (child.stderr ?? "")
+  }
+
+  // Every cz global, not just the four this first went out with: run-cli reads the
+  // connection ones off this same argv, so `serve --workspace ws1` works today.
+  for (const flag of [
+    ["--profile", "p1"], ["--format", "json"], ["--field", "x"], ["--debug"],
+    ["--workspace", "ws1"], ["--instance", "i2"], ["--schema", "sc"], ["--vcluster", "vc"],
+    ["--service", "svc"], ["--protocol", "http"], ["--pat", "tok"], ["--jdbc", "jdbc:x"],
+    ["--username", "u"], ["--password", "w"], ["-p", "p1"],
+  ]) {
+    test(`${flag[0]} is accepted, not rejected by .strict()`, () => {
+      const out = serveProbe(flag)
+      expect(out).toContain("listening on http://")
+      expect(out).not.toContain("Unknown argument")
+    }, SLOW_SPAWN)
+  }
+
+  test("a real typo is still rejected, and no server starts", () => {
+    const out = serveProbe(["--prot", "45999"])
+    expect(out).toContain("Unknown argument: prot")
+    expect(out).not.toContain("listening on http://")
+  }, SLOW_SPAWN)
+})
+
+describe("auth list keeps its JSON contract", () => {
+  const home = makeHome(`default_profile = "uat_0"
+
+[oauth.uat]
+expire_time_ms = 3600000
+obtained_at = 1000000000000
+
+[profiles.uat_0]
+oauth = "uat"
+`)
+
+  test("the sessions list stays under data.sessions", () => {
+    const payload = JSON.parse(run(["auth", "list", "--format", "json"], {}, home).stdout) as Record<string, any>
+    expect(Array.isArray(payload.data.sessions)).toBe(true)
+    expect(payload.data.active_profile).toBe("uat_0")
+  })
+
+  test("--field sessions still resolves", () => {
+    const out = run(["auth", "list", "--field", "sessions"], {}, home).stdout
+    expect(out.startsWith("[")).toBe(true)
+    expect(out).toContain('"session":"uat"')
+  })
+
+  test("row formats still get one row per session", () => {
+    expect(run(["auth", "list", "--format", "text"], {}, home).stdout.split("\t")[0]).toBe("uat")
+  })
+})
+
+describe("a projected list never costs a command its verdict", () => {
+  test("datasource check keeps `ready` in row formats", () => {
+    // `checks` is a list, but `ready` is the answer; declaring the list would drop it.
+    const r = run(["datasource", "check", "1", "--format", "csv"])
+    // Unreachable host, so this only asserts the shape decision, not a real check.
+    expect(errorOf(r.stdout).code ?? "").not.toBe("USAGE_ERROR")
+  }, SLOW_SPAWN)
+})
+
+describe("telemetry: a value-less flag no longer claims the next token", () => {
+  test("a boolean flag before a statement records the flag, not the statement", async () => {
+    const { parseTrackingArgs } = await import("../src/telemetry.ts")
+    const r = parseTrackingArgs(["sql", "--debug", "select * from customers where region = 'apac'"])
+    expect(r.args.debug).toBe("true")
+    expect(JSON.stringify(r.args)).not.toContain("customers")
+  })
+
+  test("the --no-x form counts as value-less too", async () => {
+    const { parseTrackingArgs } = await import("../src/telemetry.ts")
+    expect(parseTrackingArgs(["sql", "--no-limit", "select 1"]).args["no-limit"]).toBe("true")
+  })
+
+  test("a flag that does take a value is unaffected", async () => {
+    const { parseTrackingArgs } = await import("../src/telemetry.ts")
+    expect(parseTrackingArgs(["sql", "--timeout", "150", "select 1"]).args.timeout).toBe("150")
+  })
+})
+
+describe("`--` operands stay scoped to the command that reads them", () => {
+  test("sql -- <statement> works", () => {
+    const r = run(["sql", "--", "select 1"])
+    expect(errorOf(r.stdout).message ?? "").not.toContain("No SQL statements found")
+  }, SLOW_SPAWN)
+
+  test("the root parser's operand handling is unchanged for other commands", () => {
+    // Reading `_` in sql rather than turning on yargs' populate-- keeps `argv["--"]`
+    // out of every other command's parse.
+    const r = run(["profile", "detail", "p1", "--field", "name"])
+    expect(r.stdout).toBe("p1")
+  })
+})
+
+describe("status reports one payload shape for every outcome", () => {
+  test("the failure payload still carries workspace and schema", () => {
+    const payload = JSON.parse(run(["status", "--format", "json"]).stdout) as Record<string, any>
+    expect(payload.data.connected).toBe(false)
+    expect(payload.data).toHaveProperty("workspace")
+    expect(payload.data).toHaveProperty("schema")
+  }, SLOW_SPAWN)
+})
+
+describe("second-round review fixes", () => {
+  test("a credential-shaped value stays out of _positional behind a value-less flag", async () => {
+    // The value-less skip must not disable the check on the VALUE: `Cookie=…` is a
+    // credential whatever flag precedes it.
+    const { parseTrackingArgs } = await import("../src/telemetry.ts")
+    const r = parseTrackingArgs(["profile", "create", "p", "--debug", "Cookie=abc123"])
+    expect(JSON.stringify(r)).not.toContain("abc123")
+  })
+
+  test("-a keeps taking its value, since mcp init declares it as --client", async () => {
+    const { parseTrackingArgs } = await import("../src/telemetry.ts")
+    expect(parseTrackingArgs(["mcp", "init", "-a", "claude"]).args.a).toBe("claude")
+  })
+
+  test("a typed --profile is reported on the agent path too", () => {
+    // The guard used to be keyed on the command connecting, and agent commands are not
+    // in PROFILE_REQUIRED_COMMANDS — so this said nothing on either stream, applied no
+    // connection env, and pinned the missing name anyway.
+    const r = run(["agent", "run", "--profile", "ghost", "hello"])
+    expect(errorOf(r.stdout).code).toBe("PROFILE_NOT_FOUND")
+  }, SLOW_SPAWN)
+
+  test("an env-only agent invocation is not gated on the profile existing", () => {
+    // The gate covers the commands the NO_PROFILE gate covers, and no more: a
+    // CZ_PROFILE exported as a label with credentials in CZ_* used to keep working.
+    const r = run(["agent", "llm", "show"], { CZ_PROFILE: "ghost" })
+    expect(errorOf(r.stdout).code).not.toBe("PROFILE_NOT_FOUND")
+  }, SLOW_SPAWN)
+
+  test("an unhandled runtime error does not widen the error vocabulary", () => {
+    // ENOENT & co. are libuv codes; only our own InterfaceError codes are promoted.
+    const r = run(["sql", "--file", "/nonexistent.sql"])
+    expect(errorOf(r.stdout).code).toBe("FILE_READ_ERROR")
+    expect(r.stdout).not.toContain("ENOENT\"")
+  })
+
+  test("our own usage errors do not collect a did-you-mean for a valid flag", () => {
+    const r = run(["task", "cron-preview", "0 0 * * *", "--count", "abc"])
+    expect(errorOf(r.stdout).message).toBe("Invalid number value for: --count")
+    expect(errorOf(r.stdout).did_you_mean).toBeUndefined()
+  })
+
+  test("Ctrl-C's envelope follows the format like every other failure", async () => {
+    // main.ts and sql.ts both render ABORTED; they now use the same renderer.
+    const main = await Bun.file(import.meta.dir + "/../src/main.ts").text()
+    expect(main).toContain("renderErrorOutput({ error: { code: \"ABORTED\"")
+  })
+})
diff --git a/packages/cz-cli/test/status-exit-code.test.ts b/packages/cz-cli/test/status-exit-code.test.ts
new file mode 100644
index 0000000000..3f7754810d
--- /dev/null
+++ b/packages/cz-cli/test/status-exit-code.test.ts
@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, test } from "bun:test"
+import { writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { onFetch, sqlSuccess, sqlFailure, stubStudioContext } from "./support/cz-fixtures.js"
+
+/**
+ * `cz-cli status` reports its OUTCOME in the exit code: 0 when the connection
+ * works, non-zero when it does not, the way pg_isready does. It used to exit 0
+ * either way, so `cz-cli status && <next step>` continued over a dead connection.
+ *
+ * The payload shape is deliberately unchanged in both cases — `connected` plus the
+ * reason is the answer to "what is the status", not a failure to answer it — which
+ * is why these assert on the data envelope and the code independently.
+ *
+ * Network-boundary test: the real command runs (execute → status → getExecContext →
+ * SDK → fetch); only /lh/submitJob is canned.
+ */
+
+const { execute } = await import("../src/execute.ts")
+
+function firstJson(output: string) {
+  return JSON.parse(output.trim().split("\n")[0] ?? "{}") as Record<string, any>
+}
+
+function stubStatusQueries(mode: "ok" | "fail") {
+  onFetch({
+    match: (url) => url.includes("/lh/submitJob"),
+    respond: (_url, _method, body) => {
+      const sql = ((body as { jobDesc?: { sqlJob?: { query?: string[] } } })?.jobDesc?.sqlJob?.query?.[0] ?? "").trim()
+      if (mode === "fail") return sqlFailure("CZLH-0000", "workspace is not available")
+      if (sql.includes("current_workspace")) return sqlSuccess(["ws"], [["ws0"]])
+      if (sql.includes("current_schema")) return sqlSuccess(["sc"], [["public"]])
+      return sqlFailure("EXEC_ERROR", `unexpected SQL: ${sql}`)
+    },
+  })
+}
+
+beforeEach(() => {
+  writeFileSync(
+    join(process.env.CLICKZETTA_TEST_HOME!, ".clickzetta", "profiles.toml"),
+    "[profiles.test]\npat = 'pat'\nworkspace = 'ws0'\ninstance = 'inst'\n",
+  )
+  stubStudioContext()
+})
+
+describe("status exit code", () => {
+  test("a working connection exits 0 and reports what it found", async () => {
+    stubStatusQueries("ok")
+    const result = await execute("status")
+    expect(result.exitCode).toBe(0)
+    const json = firstJson(result.output)
+    expect(json.data.connected).toBe(true)
+    expect(json.data.workspace).toBe("ws0")
+    expect(json.data.schema).toBe("public")
+    expect(json.error).toBeUndefined()
+  })
+
+  test("a failing connection exits 1 and still describes itself", async () => {
+    stubStatusQueries("fail")
+    const result = await execute("status")
+    expect(result.exitCode).toBe(1)
+    const json = firstJson(result.output)
+    expect(json.data.connected).toBe(false)
+    expect(typeof json.data.error).toBe("string")
+  })
+
+  test("the row formats show the same outcome without an ERROR line", async () => {
+    stubStatusQueries("ok")
+    const result = await execute("status --format text")
+    expect(result.exitCode).toBe(0)
+    expect(result.output).not.toContain("ERROR")
+    expect(result.output.split("\t")[0]).toBe("true")
+  })
+})
diff --git a/packages/cz-cli/test/telemetry.test.ts b/packages/cz-cli/test/telemetry.test.ts
index 14c2863342..d833e61b3d 100644
--- a/packages/cz-cli/test/telemetry.test.ts
+++ b/packages/cz-cli/test/telemetry.test.ts
@@ -86,13 +86,21 @@ test("parseTrackingArgs keeps a flag's value out of _positional", () => {
   expect(JSON.stringify(args)).not.toContain("czt_secret")
 })
 
-test("parseTrackingArgs leaves non-sensitive flags' neighbours alone", () => {
-  // Only sensitive flags swallow their neighbour. A boolean flag followed by a real
-  // positional is indistinguishable by shape, so the existing analytics keep seeing it.
+test("parseTrackingArgs does not let a value-less flag claim the next token", () => {
+  // `--debug` takes no value, so the statement after it is a positional and stays one.
+  // It used to be recorded as `--debug`'s value, which put a whole SQL statement in the
+  // flag map — see VALUELESS_FLAGS.
   const { positional, args } = parseTrackingArgs(["sql", "--debug", "select 1"])
 
   expect(positional).toEqual(["sql", "select 1"])
-  expect(args.debug).toBe("select 1")
+  expect(args.debug).toBe("true")
+})
+
+test("parseTrackingArgs still records the neighbour of a flag that takes a value", () => {
+  // The two names declared BOTH ways stay out of VALUELESS_FLAGS, so their real values
+  // are still captured — and still redacted when they are credentials.
+  expect(parseTrackingArgs(["sql", "--limit", "100", "select 1"]).args.limit).toBe("100")
+  expect(parseTrackingArgs(["profile", "create", "p", "--header", "Cookie=abc"]).args.header).toBe("<redacted>")
 })
 
 test("parseTrackingArgs redacts --password and --pat=inline forms too", () => {
@@ -134,6 +142,26 @@ test("parseTrackingArgs keeps a SQL statement that follows the boolean --header"
   expect(withEquals.args.header).toBe("select * from t where id=1")
 })
 
+// A boolean flag standing right before the statement claims it as its value (see
+// parseTrackingArgs' note), and telemetry LEAVES the machine while the local SQL log
+// does not — so what is recorded goes through the same redactSql the log uses.
+test("a statement behind a value-less flag is not recorded as that flag's value", () => {
+  const r = parseTrackingArgs(["sql", "--debug", "select * from users where email='a@b.c'"])
+  expect(r.args.debug).toBe("true")
+  expect(JSON.stringify(r.args)).not.toContain("select * from users")
+})
+
+test("redactSql still masks what a value-taking flag legitimately captures", () => {
+  // Defence in depth for the flags that DO take a value (`--set`, `--variable`, …).
+  const r = parseTrackingArgs(["sql", "--variable", "email='a@b.c'", "select 1"])
+  expect(r.args.variable).not.toContain("a@b.c")
+})
+
+test("parseTrackingArgs masks literals in _positional too", () => {
+  const r = parseTrackingArgs(["task", "search", "--name", "x", "'13800138000'"])
+  expect(JSON.stringify(r.args)).not.toContain("13800138000")
+})
+
 // `--login` / `--jdbc` take a JDBC connection string, and jdbc.ts reads `password=`
 // out of it, so the whole value is a credential.
 test("parseTrackingArgs redacts connection strings", () => {