stitchkit 0.90.2 → 0.90.3

package/CHANGELOG.md

@@ -15,6 +15,61 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.90.3] — 2026-09-15
+
+### Added
+
+- **A trailing positional may be a list.** When the last field of a command's
+  declared `positionals` is an array, it takes every remaining argv token,
+  coerced by the element type: `myapp handoff proj a.md b.md` instead of
+  `--files '["a.md","b.md"]'`. One token is a one-element list, so the parsed
+  shape never depends on how many a caller happened to pass, and command help
+  says which field is the list (`<to> <files...>`). The flag form still works;
+  passing both forms in one call is an argument error rather than a silent
+  merge. Only the trailing position is variadic — an array declared earlier
+  keeps taking exactly one JSON token, unchanged.
+- **`globalOptions` — the application's own invocation context.** A CLI's
+  globals were only ever the framework's (`--json`, `--wait`, …), so an app that
+  needed `--caller <key>` or `--root <dir>` had to read an environment variable
+  or parse argv itself, next to the parser it already had. Declare them as a Zod
+  object and `createCli` lifts them out of argv wherever they stand — before or
+  after the command name — validates them, keeps them out of every operation's
+  arguments, and hands them to `resolveAuth(globals)`, `context(auth, globals)`
+  and a native command's `globals`. A name that collides with a framework option
+  or with a field of any command is refused at startup instead of shadowing it
+  silently, and both help levels list them under `Application options:`.
+
+### Fixed
+
+- **Output past the pipe buffer is no longer lost to a slow reader.** The
+  default writer called `writeSync` and ignored the byte count it returns. Once
+  anything in the process has touched `process.stdout` the descriptor is
+  non-blocking, so a write into a pipe whose reader has not started yet stores
+  what the 64 KB buffer takes, returns that count and throws nothing: the tail
+  vanished with exit code `0`, at exactly 65536 bytes — the same number as the
+  truncation the synchronous writer had been introduced to fix, which is why it
+  read as already fixed for so long. A consuming CLI saw `… | jq` fail with
+  "Unfinished string at column 65536" while the same command redirected to a
+  file wrote the whole result. The writer now loops on the returned count and
+  treats a full buffer (`EAGAIN`) as a wait rather than a failure, which is what
+  a blocking write into an undrained pipe is supposed to do; where an exotic
+  descriptor still forces the async fallback, the default `exit` waits for that
+  write instead of cutting it off, and output that could not be delivered at all
+  now exits non-zero.
+- **Help survives a managed surface that cannot resolve.** A CLI whose commands
+  come from a running server declares them with a factory, and the factory needs
+  an identity. When `resolveAuth` failed — server down, key file missing — the
+  rejection escaped `createCli` and `--help` printed *nothing*: not the native
+  commands, which never depended on identity, and not the reason. Calling such a
+  name was worse than silence, because the surface never resolved and the answer
+  would have been `Unknown command` — a claim that the name does not exist when
+  the truth is that it could not be looked up. Top-level help now lists the
+  native commands and one line naming the refusal (`Managed commands are
+  unavailable: UNREACHABLE: socket closed`), and an unresolvable name answers
+  with that refusal and the exit code its error class declares through
+  `exitCodes`. Identity is still resolved at most once per invocation, failure
+  included.
+
 ## [0.90.2] — 2026-09-15
 
 ### Fixed

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-8dph3pw6.js";
+} from "./index-1923shw9.js";
 import"./index-sbdmyz75.js";
 import"./index-wb15909q.js";
 import"./index-2hrfpw2c.js";

package/dist/{index-8dph3pw6.js → index-1923shw9.js}

@@ -9,6 +9,7 @@ import {
   formatToolError
 } from "./index-2hrfpw2c.js";
 import {
+  toolErrorFromResult,
   toolResultFromError
 } from "./index-44ht2790.js";
 import {
@@ -434,10 +435,19 @@ function parseCliArgs(argv, schema, config = {}) {
   }
   const toolArgs = {};
   const fillable = config.positionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...config.positionals];
+  const variadicTail = config.positionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
   let pi = 0;
   for (const key of fillable) {
     if (pi >= positionals.length)
       break;
+    if (key === variadicTail) {
+      if (flags.has(key)) {
+        throw new CliArgumentError(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
+      }
+      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi));
+      pi = positionals.length;
+      break;
+    }
     if (flags.has(key))
       continue;
     const value = positionals[pi++];
@@ -477,6 +487,55 @@ function parseCliArgs(argv, schema, config = {}) {
   }
   return { toolArgs, options };
 }
+function extractCliGlobalOptions(argv, schema) {
+  if (schema === undefined)
+    return { argv: [...argv], globals: {} };
+  const fields = describeSchemaFields(schema);
+  const rest = [];
+  const raw = new Map;
+  let ended = false;
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === undefined)
+      continue;
+    if (!ended && token === "--")
+      ended = true;
+    const option = ended ? undefined : classifyLongOptionToken(token);
+    const info = option && option.globalKind === undefined ? fields.get(option.name) : undefined;
+    if (!option || !info) {
+      rest.push(token);
+      continue;
+    }
+    let { value } = option;
+    if (value === undefined && info.kind === "boolean") {
+      value = "true";
+    } else if (value === undefined) {
+      const next = argv[i + 1];
+      if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
+        value = next;
+        i++;
+      } else {
+        throw new CliArgumentError(`--${option.name} requires a value`);
+      }
+    }
+    const existing = raw.get(option.name);
+    if (existing)
+      existing.push(value);
+    else
+      raw.set(option.name, [value]);
+  }
+  const args = {};
+  for (const [name, values] of raw)
+    args[name] = coerceField(fields.get(name), values);
+  const parsed = schema.safeParse(coerceJsonArgs(args, schema));
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    const field = issue?.path[0];
+    const where = typeof field === "string" ? `--${field}` : "application option";
+    throw new CliArgumentError(`${where}: ${issue?.message ?? "invalid value"}`);
+  }
+  return { argv: rest, globals: parsed.data };
+}
 
 // src/tools/cli-command.ts
 function defineCliCommand(definition) {
@@ -509,7 +568,7 @@ function cliCommandPresentationSchema(definition) {
     unrepresentable: "any"
   });
 }
-async function executeCliCommand(definition, rawArgs, options, writers, coerceJson) {
+async function executeCliCommand(definition, rawArgs, options, writers, coerceJson, globals = {}) {
   let parsed;
   try {
     parsed = definition.input.safeParse(coerceJson ? coerceJsonArgs(rawArgs, definition.input) : rawArgs);
@@ -527,6 +586,7 @@ async function executeCliCommand(definition, rawArgs, options, writers, coerceJs
     const data = await definition.handler({
       input: parsed.data,
       options,
+      globals,
       ...writers
     });
     const checked = validateDeclaredOutput(definition.output, data);
@@ -1190,7 +1250,19 @@ function collectPassthrough(toolArgs, field, knownKeys) {
   const base = passthroughBase(toolArgs[field]);
   toolArgs[field] = base ? { ...base, ...bag } : bag;
 }
-function renderTopHelp(name, version, commands, defaultCommand) {
+function applicationOptionLines(fields) {
+  if (fields.length === 0)
+    return [];
+  const labels = new Map(fields.map((field) => [field.name, `--${field.name} <${typeLabel(field.schema)}>`]));
+  const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
+  return [
+    "",
+    "Application options:",
+    ...fields.map((field) => `  ${padRight(labels.get(field.name) ?? `--${field.name}`, width)}  ${field.description ?? ""}`.trimEnd())
+  ];
+}
+function renderTopHelp(input) {
+  const { name, version, commands, defaultCommand } = input;
   const lines = [
     `${name} ${version}`,
     "",
@@ -1202,29 +1274,35 @@ function renderTopHelp(name, version, commands, defaultCommand) {
   for (const [command, descriptor] of commands) {
     lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}${command === defaultCommand ? " (default)" : ""}`);
   }
+  if (input.unavailable !== undefined) {
+    lines.push("", `Managed commands are unavailable: ${input.unavailable}`);
+  }
   lines.push("", "Global options:");
   const optWidth = Math.max(...GLOBAL_OPTIONS.map(([flag]) => flag.length));
   for (const [flag, desc] of GLOBAL_OPTIONS)
     lines.push(`  ${padRight(flag, optWidth)}  ${desc}`);
+  lines.push(...applicationOptionLines(input.applicationOptions));
   lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
   return `${lines.join(`
 `)}
 `;
 }
-function renderCommandHelp(name, command, descriptor) {
+function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
   const fields = jsonSchemaFields(descriptor.presentationSchema);
   const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+  const kinds = describeSchemaFields(descriptor.argumentSchema);
   const positionals = [];
-  const positionalNames = descriptor.positionals ?? [...describeSchemaFields(descriptor.argumentSchema)].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
+  const positionalNames = descriptor.positionals ?? [...kinds].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
   for (const fieldName of positionalNames) {
     const field = fieldsByName.get(fieldName);
     if (field)
       positionals.push(field);
   }
-  const positionalSyntax = new Map(positionals.map((field) => [
-    field.name,
-    field.required ? `<${field.name}>` : `[${field.name}]`
-  ]));
+  const variadicTail = descriptor.positionals !== undefined && kinds.get(descriptor.positionals[descriptor.positionals.length - 1] ?? "")?.kind === "array" ? descriptor.positionals[descriptor.positionals.length - 1] : undefined;
+  const positionalSyntax = new Map(positionals.map((field) => {
+    const label = field.name === variadicTail ? `${field.name}...` : field.name;
+    return [field.name, field.required ? `<${label}>` : `[${label}]`];
+  }));
   const usage = [
     `Usage: ${name} ${command}`,
     ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
@@ -1248,6 +1326,9 @@ function renderCommandHelp(name, command, descriptor) {
     }
     lines.push("");
   }
+  const applicationLines = applicationOptionLines(applicationOptions);
+  if (applicationLines.length > 0)
+    lines.push(...applicationLines.slice(1), "");
   return `${lines.join(`
 `)}
 `;
@@ -1266,15 +1347,20 @@ function nativeDescriptor(definition) {
     presentationSchema: cliCommandPresentationSchema(definition)
   };
 }
-function assertCommandShape(name, descriptor, exists, passthroughField) {
+function assertCommandShape(name, descriptor, exists, passthroughField, applicationGlobals = new Set) {
   assertUniqueToolName(name, exists, "CLI command");
   if (name === "help" || name === "version") {
     throw new Error(`[stitchkit] CLI command "${name}" is reserved`);
   }
-  const conflicting = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name).filter((field) => RESERVED_CLI_OPTIONS.has(field));
+  const fieldNames = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name);
+  const conflicting = fieldNames.filter((field) => RESERVED_CLI_OPTIONS.has(field));
   if (conflicting.length > 0) {
     throw new Error(`[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`);
   }
+  const shadowed = fieldNames.filter((field) => applicationGlobals.has(field));
+  if (shadowed.length > 0) {
+    throw new Error(`[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`);
+  }
   if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
     throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
   }
@@ -1338,30 +1424,78 @@ async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes
   return succeeded;
 }
 async function createCli(config) {
+  let pendingWrite;
+  let writeFailed = false;
   const writeFd = (fd, text) => {
-    try {
-      writeSync(fd, text);
-    } catch {
-      (fd === 1 ? process.stdout : process.stderr).write(text);
+    const bytes = Buffer.from(text, "utf8");
+    let offset = 0;
+    while (offset < bytes.length) {
+      try {
+        offset += writeSync(fd, bytes, offset, bytes.length - offset);
+      } catch (error) {
+        if (isRecord(error) && error.code === "EAGAIN") {
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+          continue;
+        }
+        const stream = fd === 1 ? process.stdout : process.stderr;
+        const rest = bytes.subarray(offset);
+        pendingWrite = new Promise((resolve2) => {
+          stream.write(rest, (failure) => {
+            if (failure)
+              writeFailed = true;
+            resolve2();
+          });
+        });
+        return;
+      }
     }
   };
   const stdout = config.stdout ?? ((text) => writeFd(1, text));
   const stderr = config.stderr ?? ((text) => writeFd(2, text));
-  const exit = config.exit ?? ((code) => void process.exit(code));
+  const exit = config.exit ?? ((code) => {
+    if (pendingWrite === undefined)
+      process.exit(code);
+    else
+      pendingWrite.then(() => process.exit(writeFailed ? 1 : code));
+  });
   const argv = config.argv ?? process.argv.slice(2);
   const readStdin = config.stdin ?? readPipedStdin;
   if (config.auth !== undefined && config.resolveAuth !== undefined) {
     throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
   }
+  const applicationOptions = config.globalOptions ? jsonSchemaFields(buildToolPresentationSchema({
+    inputSchema: config.globalOptions,
+    unrepresentable: "any"
+  })) : [];
+  const applicationGlobalNames = new Set(applicationOptions.map((field) => field.name));
+  for (const name of applicationGlobalNames) {
+    if (RESERVED_CLI_OPTIONS.has(name)) {
+      throw new Error(`[stitchkit] CLI global option "--${name}" is reserved by the framework`);
+    }
+  }
   const nativeCommands = new Map;
   const nativeHelp = new Map;
   for (const definition of config.commands ?? []) {
     const descriptor2 = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
-    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name]);
+    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
     nativeCommands.set(definition.name, definition);
     nativeHelp.set(definition.name, descriptor2);
   }
-  const route = routeCliArgv(argv, config.defaultCommand);
+  let globals;
+  let routableArgv;
+  try {
+    const lifted = extractCliGlobalOptions(argv, config.globalOptions);
+    globals = lifted.globals;
+    routableArgv = lifted.argv;
+  } catch (error) {
+    if (!(error instanceof CliArgumentError))
+      throw error;
+    stderr(`${error.message}
+`);
+    return exit(2);
+  }
+  const typedGlobals = globals;
+  const route = routeCliArgv(routableArgv, config.defaultCommand);
   if (route.error) {
     stderr(`${route.error}
 `);
@@ -1381,7 +1515,7 @@ async function createCli(config) {
     if (!descriptor2)
       throw new Error("[stitchkit] native CLI descriptor invariant failed");
     if (helpRequested) {
-      stdout(renderCommandHelp(config.name, command, descriptor2));
+      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
       return exit(0);
     }
     const prepared2 = await prepareInvocation(command, commandArgv, descriptor2, config, readStdin);
@@ -1392,7 +1526,7 @@ async function createCli(config) {
     }
     const { toolArgs: toolArgs2, options: options2 } = prepared2;
     if (options2.help) {
-      stdout(renderCommandHelp(config.name, command, descriptor2));
+      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
       return exit(0);
     }
     if (options2.wait) {
@@ -1415,7 +1549,7 @@ async function createCli(config) {
 `);
       return exit(0);
     }
-    const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true);
+    const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true, globals);
     const emission = prepareCliCommandEmission(native, result2, options2);
     let emittedExitCode;
     if (emission.result.ok && emission.presentation !== undefined) {
@@ -1433,12 +1567,26 @@ async function createCli(config) {
   }
   let authPromise;
   const resolveIdentity = () => {
-    authPromise ??= Promise.resolve(config.resolveAuth ? config.resolveAuth() : config.auth);
+    authPromise ??= (async () => config.resolveAuth ? await config.resolveAuth(typedGlobals) : await config.auth)();
     return authPromise;
   };
   const dynamicSurface = typeof config.services === "function" || typeof config.runtimeTools === "function";
   const buildManagedSurface = async (forExecution) => {
-    const auth = dynamicSurface || forExecution ? await resolveIdentity() : undefined;
+    let auth;
+    if (dynamicSurface || forExecution) {
+      try {
+        auth = await resolveIdentity();
+      } catch (error) {
+        const failure = toolResultFromError(error);
+        const normalized = toolErrorFromResult(failure);
+        return {
+          resolved: false,
+          failure,
+          reason: `${normalized.code}: ${normalized.message}`,
+          help: new Map(nativeHelp)
+        };
+      }
+    }
     const services = typeof config.services === "function" ? config.services(auth) : config.services ?? [];
     const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools ?? [];
     const tools = new Map;
@@ -1448,19 +1596,34 @@ async function createCli(config) {
       transport: "CLI"
     })) {
       const descriptor2 = applyCliPresentationPolicy(mountable.name, managedDescriptor(mountable), config);
-      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name), config.passthrough?.[mountable.name]);
+      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
       tools.set(mountable.name, mountable);
       help.set(mountable.name, descriptor2);
     }
     assertCliPoliciesResolved(help, config);
-    return { auth, help, tools };
+    return { resolved: true, auth, help, tools };
   };
   const topLevelHelp = route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h";
   const managed = await buildManagedSurface(!topLevelHelp && !helpRequested);
   if (topLevelHelp) {
-    stdout(renderTopHelp(config.name, config.version, managed.help, config.defaultCommand));
+    stdout(renderTopHelp({
+      name: config.name,
+      version: config.version,
+      commands: managed.help,
+      defaultCommand: config.defaultCommand,
+      applicationOptions,
+      ...managed.resolved ? {} : { unavailable: managed.reason }
+    }));
     return exit(0);
   }
+  if (!managed.resolved) {
+    return exit(emitResult(managed.failure, { stdout, stderr }, {
+      json: beforeSeparator.includes("--json"),
+      toolName: command ?? config.name,
+      errorHint: config.errorHint,
+      exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
+    }));
+  }
   const tool = managed.tools.get(command);
   if (!tool) {
     stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
@@ -1471,7 +1634,7 @@ async function createCli(config) {
   if (!descriptor)
     throw new Error("[stitchkit] managed CLI descriptor invariant failed");
   if (helpRequested) {
-    stdout(renderCommandHelp(config.name, command, descriptor));
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
   const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
@@ -1497,7 +1660,7 @@ async function createCli(config) {
     return exit(2);
   }
   if (options.help) {
-    stdout(renderCommandHelp(config.name, command, descriptor));
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
   if (options.dryRun) {
@@ -1507,7 +1670,7 @@ async function createCli(config) {
   }
   const runTool = createToolRunner({
     source: "cli",
-    context: { ...config.context?.(managed.auth), signal: config.signal },
+    context: { ...config.context?.(managed.auth, typedGlobals), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,

package/dist/tools/cli-args.d.ts

@@ -88,5 +88,32 @@ export declare function parseCliArgs(argv: string[], schema: z.ZodType | undefin
     optionAliases?: ReadonlyMap<string, string>;
     positionals?: readonly string[];
 }): ParsedCliArgs;
+/** The application's own global options, lifted out of one invocation's argv. */
+export interface CliGlobalOptionsParse {
+    /** argv with the application-global tokens removed, ready for routing. */
+    argv: string[];
+    /** The validated values, as the application's own schema types them. */
+    globals: Record<string, unknown>;
+}
+/**
+ * Lift the APPLICATION's global options out of argv, wherever they stand.
+ *
+ * These are not arguments of any operation: which identity key to use, which
+ * checkout a call speaks for, which profile. They belong to the invocation, so
+ * they may precede the command name as easily as follow it — and a command's
+ * own parser must never see them, or an app-global would read as an unknown
+ * flag on every operation that does not declare it.
+ *
+ * Stripping them BEFORE routing is what keeps this one grammar rather than two:
+ * `routeCliArgv` then sees a command where a command is, `parseCliArgs` sees
+ * only operation arguments, and `passthrough` cannot swallow an app-global into
+ * a freeform bag. The token shape is the same `classifyLongOptionToken` the
+ * framework's own globals use, so `--root /x`, `--root=/x` and a bare boolean
+ * `--verbose` all behave as they do everywhere else.
+ *
+ * `--` ends the sweep: past it every token is a literal value, so a positional
+ * that happens to read as `--root` survives intact.
+ */
+export declare function extractCliGlobalOptions(argv: readonly string[], schema: z.ZodObject | undefined): CliGlobalOptionsParse;
 export {};
 //# sourceMappingURL=cli-args.d.ts.map

package/dist/tools/cli-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/tools/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,UAAU,SAAS;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAOD,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AA0BjF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CAsFlF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC;AAuED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AA8FD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAwMf"}
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../../src/tools/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,KAAK,SAAS,GACV,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,UAAU,SAAS;IACjB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAOD,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AA0BjF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CAsFlF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAChC,IAAI,SAAsB;CACpC;AAuED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AA8FD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CA+Nf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CA8CvB"}

package/dist/tools/cli-command.d.ts

@@ -5,6 +5,13 @@ import { type ToolResult } from './execute.js';
 export interface CliCommandContext<TInput extends ZodObject> extends CliWriters {
     input: z.output<TInput>;
     options: Readonly<CliRunOptions>;
+    /**
+     * The application's own global options for this invocation, already validated
+     * against `CliConfig.globalOptions`. Empty when the CLI declares none. Typed
+     * loosely because a command is defined independently of the CLI it is mounted
+     * on — read it through the same schema the application declared.
+     */
+    globals: Readonly<Record<string, unknown>>;
 }
 export interface CliCommandDefinitionBase<TInput extends ZodObject> {
     name: string;
@@ -41,5 +48,5 @@ export interface PreparedCliCommandEmission {
 export declare function prepareCliCommandEmission(definition: CliCommandDefinition, result: ToolResult, options: Readonly<CliRunOptions>): PreparedCliCommandEmission;
 export declare function cliCommandPresentationSchema(definition: CliCommandDefinition): Record<string, unknown>;
 /** Execute a CLI-only definition without inventing a tool operation identity. */
-export declare function executeCliCommand(definition: CliCommandDefinition, rawArgs: Record<string, unknown>, options: CliRunOptions, writers: CliWriters, coerceJson: boolean): Promise<ToolResult>;
+export declare function executeCliCommand(definition: CliCommandDefinition, rawArgs: Record<string, unknown>, options: CliRunOptions, writers: CliWriters, coerceJson: boolean, globals?: Readonly<Record<string, unknown>>): Promise<ToolResult>;
 //# sourceMappingURL=cli-command.d.ts.map

package/dist/tools/cli-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/tools/cli-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../../src/tools/cli-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,WAAW,CAAC;AAGjE,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,SAAS,CAAE,SAAQ,UAAU;IAC7E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;IACjC;;;;;OAKG;IACH,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,wBAAwB,CAAC,MAAM,SAAS,SAAS;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,8BAA8B,CAC7C,MAAM,SAAS,SAAS,EACxB,OAAO,SAAS,OAAO,CACvB,SAAQ,wBAAwB,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CACP,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAC/B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IACpD,0FAA0F;IAC1F,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1B,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;KAClC,KAAK,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,iCAAiC,CAAC,MAAM,SAAS,SAAS,CACzE,SAAQ,wBAAwB,CAAC,MAAM,CAAC;IACxC,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC;IACjB,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,MAAM,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,MAAM,oBAAoB,GAC5B,8BAA8B,CAAC,SAAS,EAAE,OAAO,CAAC,GAClD,iCAAiC,CAAC,SAAS,CAAC,CAAC;AAEjD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,SAAS,EAAE,OAAO,SAAS,OAAO,EAChF,UAAU,EAAE,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,GAC1D,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,SAAS,EACvD,UAAU,EAAE,iCAAiC,CAAC,MAAM,CAAC,GACpD,iCAAiC,CAAC,MAAM,CAAC,CAAC;AAK7C,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,GAC/B,0BAA0B,CAwB5B;AAED,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,OAAO,EACnB,OAAO,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC9C,OAAO,CAAC,UAAU,CAAC,CAoCrB"}

package/dist/tools/cli-policy.d.ts

@@ -13,7 +13,12 @@ export interface CliCommandPresentation {
     presentationSchema: Record<string, unknown>;
     /** Canonical field name → one short alias. */
     aliases: ReadonlyMap<string, string>;
-    /** `undefined` retains automatic non-boolean schema order. */
+    /**
+     * `undefined` retains automatic non-boolean schema order. A trailing ARRAY
+     * field is variadic — it takes every remaining token. An array declared
+     * anywhere else keeps taking exactly one (a JSON-array token), and command
+     * help says which is which: only the variadic tail renders as `<name...>`.
+     */
     positionals?: readonly string[];
 }
 export declare function applyCliPresentationPolicy(command: string, descriptor: Omit<CliCommandPresentation, 'aliases' | 'positionals'>, config: CliPresentationPolicyConfig): CliCommandPresentation;

package/dist/tools/cli-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-policy.d.ts","sourceRoot":"","sources":["../../src/tools/cli-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,6FAA6F;IAC7F,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAkFD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,aAAa,CAAC,EACnE,MAAM,EAAE,2BAA2B,GAClC,sBAAsB,CAexB;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,EACrD,MAAM,EAAE,2BAA2B,GAClC,IAAI,CAWN"}
+{"version":3,"file":"cli-policy.d.ts","sourceRoot":"","sources":["../../src/tools/cli-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGlD,MAAM,WAAW,2BAA2B;IAC1C,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,6FAA6F;IAC7F,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAkFD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,GAAG,aAAa,CAAC,EACnE,MAAM,EAAE,2BAA2B,GAClC,sBAAsB,CAexB;AAED,wFAAwF;AACxF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,EACrD,MAAM,EAAE,2BAA2B,GAClC,IAAI,CAWN"}

package/dist/tools/cli.d.ts

@@ -1,3 +1,4 @@
+import type { ZodObject, z } from 'zod';
 import type { ServiceDef, StitchLogger } from '../server/types.js';
 import { type CliCommandDefinition } from './cli-command.js';
 import { type ExitCodeMap } from './cli-format.js';
@@ -6,7 +7,7 @@ import { type CliWaitConfig } from './cli-wait.js';
 import { type ErrorHintFn, type ToolCallHooks, type ToolLifecycle } from './execute.js';
 import type { RuntimeToolDefinition } from './runtime-tool.js';
 export type CliSurfaceSource<TAuth, TValue> = readonly TValue[] | ((auth: Awaited<TAuth> | undefined) => readonly TValue[]);
-export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>> extends CliPresentationPolicyConfig {
+export interface CliConfig<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>, TGlobals extends ZodObject = ZodObject> extends CliPresentationPolicyConfig {
     /** Program name — shown in help and unknown-command messages. */
     name: string;
     /** Program version — printed by `--version`. */
@@ -23,13 +24,27 @@ export interface CliConfig<TAuth = unknown, TContext extends Record<string, unkn
      * promise of one.
      */
     auth?: TAuth | Promise<TAuth>;
-    /** Lazily resolve identity only when a managed command/surface actually needs it. */
-    resolveAuth?: () => TAuth | Promise<TAuth>;
+    /**
+     * Lazily resolve identity only when a managed command/surface actually needs
+     * it. Receives the application's global options, so `--caller <key>` can
+     * select WHICH identity this invocation speaks as.
+     */
+    resolveAuth?: (globals: z.output<TGlobals>) => TAuth | Promise<TAuth>;
+    /**
+     * The application's OWN global options — invocation context that belongs to
+     * no single operation: which identity key, which checkout, which profile.
+     * Declared as a Zod object of optional fields; `createCli` lifts these flags
+     * out of argv wherever they stand (before or after the command name),
+     * validates them against this schema and keeps them out of every operation's
+     * arguments. A name that collides with a framework option or with a field of
+     * any command is a startup error, never silent shadowing.
+     */
+    globalOptions?: TGlobals;
     /**
      * Context merged into every handler. Typed against the app's context shape
      * when the CLI is built via `createToolkit<AppContext>()`.
      */
-    context?: (auth: Awaited<TAuth> | undefined) => TContext;
+    context?: (auth: Awaited<TAuth> | undefined, globals: z.output<TGlobals>) => TContext;
     /** Explicit cancellation for this invocation; applications may bind SIGINT to it. */
     signal?: AbortSignal;
     /** Tool-call observability hooks — `afterToolCall` fires for every result,
@@ -87,5 +102,5 @@ export interface CliConfig<TAuth = unknown, TContext extends Record<string, unkn
     stdin?: () => Promise<string | null>;
 }
 /** Build and run one mixed contract/runtime/native CLI surface, then exit. */
-export declare function createCli<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>>(config: CliConfig<TAuth, TContext>): Promise<void>;
+export declare function createCli<TAuth = unknown, TContext extends Record<string, unknown> = Record<string, unknown>, TGlobals extends ZodObject = ZodObject>(config: CliConfig<TAuth, TContext, TGlobals>): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/tools/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/tools/cli.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -46,7 +46,7 @@ import {
   fetchPinnedDocument,
   readCapped,
   runWaitOperation
-} from "./index-8dph3pw6.js";
+} from "./index-1923shw9.js";
 import"./index-sbdmyz75.js";
 import {
   collectToolSurface

package/llms-full.txt

@@ -7443,6 +7443,30 @@ command schema. `-f` / `-f=false` are boolean forms; values accept `-n 100` and
 bundles such as `-fn`, attached values such as `-n100`, `--no-f` and unknown
 short flags are rejected. Canonical `--no-follow` remains available.
 
+### A trailing list
+
+When the LAST declared positional is an array field, it takes every remaining
+token, each coerced by the array's element type:
+
+```ts
+positionals: { handoff: ['to', 'files'] }   // files: z.array(z.string())
+```
+
+```
+myapp handoff proj a.md b.md     → { to: 'proj', files: ['a.md', 'b.md'] }
+myapp handoff proj a.md          → { to: 'proj', files: ['a.md'] }
+```
+
+One token is a one-element list, not a scalar, so the parsed shape never depends
+on how many a caller happened to pass. Command help marks it:
+`Usage: myapp handoff <to> <files...>`. The flag form still works
+(`--files '["a.md","b.md"]'`, or a repeated `--files`) — but passing both forms
+in one call is an argument error rather than a silent merge.
+
+Only the trailing position is variadic. An array declared anywhere else in the
+list keeps taking exactly one token (a JSON array), and its help stays `<tags>`,
+so the usage line always says which field is the list.
+
 `positionals` replaces automatic schema-order selection only for the named
 command. An empty array disables argv positionals. Fields remain available as
 long/short options and stdin still fills the first required unset field with the
@@ -7474,6 +7498,68 @@ diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
 …) — override per app with `exitCodes`.
 
+## Application global options
+
+`--json` and friends above are the framework's. An application usually has
+globals of its own — which identity key to use, which checkout a call speaks
+for, which profile — and they belong to no single operation:
+
+```ts
+await createCli({
+  name: 'myapp',
+  version: '1.0.0',
+  globalOptions: z.object({
+    caller: z.string().optional().describe('Identity key file'),
+    root: z.string().optional().describe('Checkout the call speaks for'),
+  }),
+  resolveAuth: (globals) => loadIdentity(globals.caller),
+  context: (auth, globals) => ({ auth, root: globals.root }),
+  runtimeTools: (auth) => catalogFor(auth),
+})
+```
+
+```
+myapp --root /srv/app handoff_read --handoffId u
+myapp handoff_read --root /srv/app --handoffId u   # the same call
+```
+
+These flags are lifted out of argv wherever they stand — before or after the
+command name — validated against the declared schema, and kept out of every
+operation's arguments: `handoff_read` above receives `{ handoffId: 'u' }` and
+nothing else. The values reach `resolveAuth(globals)`, `context(auth, globals)`
+and a native command's `globals`. An invalid value is an argument error naming
+the flag; a name that collides with a framework option, or with a field of any
+command, is refused at startup rather than shadowing it silently. Past a bare
+`--` every token is a literal, so a positional value that reads like a global
+survives intact.
+
+Both help levels list them under `Application options:`.
+
+## When the managed surface cannot resolve
+
+A CLI whose commands come from a running server declares them with a factory,
+and that factory needs an identity. When `resolveAuth` fails — the server is
+down, the key file is missing — the commands it would have named are unknown to
+the CLI, but the native ones are not:
+
+```
+$ myapp --help
+myapp 1.0.0
+...
+Commands:
+  serve  Run the server
+
+Managed commands are unavailable: UNREACHABLE: socket closed
+```
+
+Help still lists what does not depend on identity and says, in one line, why the
+rest is missing. Calling a name the CLI cannot resolve answers with that same
+refusal and the exit code its error class declares through `exitCodes` — never
+`Unknown command`, which would claim the name does not exist when the truth is
+that it could not be looked up. A native command and its help still run: they
+never needed an identity. Identity is still resolved at most once per
+invocation, failure included.
+
 Per-command help derives the positional form from the same resolved policy as
 the argv parser. For example, a required `action` and optional `profile` render as
 `Usage: myapp skill <action> [profile] [--flags]`; the argument table also shows
@@ -16443,14 +16529,14 @@ payload.
 | `AgentToolRegistry` / `AgentToolRegistryBuilder` / `AgentToolRegistryInput` | _type_ | the composed runtime surface and its builder: declared defaults, `replace`/`disable` by name, and the exact `{ tools, names }` a mount receives |
 | `defineToolRegistry` | function | compose runtime tools over one declared default set; an unknown `replace`/`disable` name is refused instead of silently leaving the default in place |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
-| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection and command-scoped `optionAliases` / `positionals` policy |
+| `CliConfig` | _type_ | config for `createCli`, including program-level `defaultCommand` selection, application-wide `globalOptions` and command-scoped `optionAliases` / `positionals` policy |
 | `CliPresentationPolicyConfig` | _type_ | reusable default-command, short-alias and explicit-positional policy inherited by `CliConfig` |
 | `CliSurfaceSource` | _type_ | static managed surface or identity-dependent surface factory for `createCli` |
 | `CliCommandDefinition` | _type_ | Zod-first CLI-only command union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with declared output schema, validated handler result and typed optional `present` / `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | void native command with no output schema |
-| `CliCommandContext` | _type_ | parsed native command input, global options and injected writers |
+| `CliCommandContext` | _type_ | parsed native command input, framework run options, the application's `globals` and injected writers |
 | `CliWaitConfig` | _type_ | `--wait` polling config |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
@@ -16949,14 +17035,14 @@ SDK nor the `ai` peer.
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
 | `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
-| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `optionAliases` and `positionals` define the shared command presentation policy |
+| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
 | `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
 | `CliCommandDefinition` | _type_ | native command definition union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
 | `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
-| `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
+| `CliCommandContext` | _type_ | parsed input, framework run options, the application's `globals` and stdout/stderr writers |
 | `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
 | `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.90.2",
+  "version": "0.90.3",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",