stitchkit 0.113.1 → 0.113.2

package/dist/{index-fytsnhzj.js → index-xtc8k5n9.js}

@@ -1,6 +1,6 @@
 import {
   validateDeclaredOutput
-} from "./index-fynr93w4.js";
+} from "./index-e40rzw1m.js";
 import {
   jsonSchemaObjectCoercionMembers
 } from "./index-dsa676h8.js";
@@ -14,15 +14,15 @@ import {
   objectShapeKeys,
   assertUniqueToolName,
   buildToolPresentationSchema
-} from "./index-jgwqc38k.js";
+} from "./index-vf9c59t3.js";
 import {
   toolResultFromError,
   toolErrorFromResult
-} from "./index-tg2q89ps.js";
+} from "./index-a31p9ekx.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-v6mzw27b.js";
+} from "./index-0gbn42hr.js";
 import {
   fetchGuarded,
   readCapped
@@ -35,7 +35,7 @@ import {
 } from "./index-eemvahkc.js";
 import {
   collectToolSurface
-} from "./index-emrmgq3s.js";
+} from "./index-2s7wv547.js";
 import {
   isUnsafeKey,
   safeJsonParse
@@ -43,6 +43,10 @@ import {
 import {
   formatZodError2
 } from "./index-1eeqpadm.js";
+import {
+  AppError2,
+  STITCH_ERROR_STATUS2
+} from "./index-pd578538.js";
 import {
   isRecord
 } from "./index-9jfdm5tg.js";
@@ -137,6 +141,7 @@ var DEFAULT_EXIT_CODES2 = {
   CONNECTION_REQUEST_FAILED: 1,
   UPSTREAM_TOOL_ERROR: 1,
   WAIT_FAILED: 1,
+  CLI_COMMAND_UNAVAILABLE: 1,
   INTERNAL_SERVER_ERROR: 1
 };
 function cliExitCode2(result, exitCodes) {
@@ -653,19 +658,25 @@ async function runNativeCommand(definition, args, config, globals) {
     written: { ...out !== "" && { stdout: out }, ...err !== "" && { stderr: err } }
   };
 }
-function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertShape) {
+function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, shapeIssue) {
   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;
   const help = new Map(nativeHelp);
-  for (const { mountable } of collectToolSurface({
+  for (const { kind, mountable } of collectToolSurface({
     surface: { services, runtimeTools },
     transport: "CLI"
   })) {
     const descriptor = applyCliPresentationPolicy(mountable.name, managedCliDescriptor(mountable), config);
-    assertShape?.(mountable.name, descriptor, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
-    tools.set(mountable.name, mountable);
-    help.set(mountable.name, descriptor);
+    const issue = shapeIssue?.(mountable.name, descriptor, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
+    if (issue !== undefined) {
+      if (kind !== "runtime")
+        throw new Error(issue);
+      help.set(mountable.name, { ...descriptor, unavailableReason: issue });
+    } else {
+      tools.set(mountable.name, mountable);
+      help.set(mountable.name, descriptor);
+    }
   }
   assertCliPoliciesResolved(help, config);
   return { tools, help };
@@ -1765,7 +1776,10 @@ function renderTopHelp(input) {
   ];
   const width = Math.max(0, ...[...commands.keys()].map((key) => key.length));
   for (const [command, descriptor] of commands) {
-    lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}${command === defaultCommand ? " (default)" : ""}`);
+    lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}${command === defaultCommand ? " (default)" : ""}${descriptor.unavailableReason !== undefined ? " [unavailable]" : ""}`);
+    if (descriptor.unavailableReason !== undefined) {
+      lines.push(`    Unavailable: ${descriptor.unavailableReason}`);
+    }
   }
   if (input.unavailable !== undefined) {
     lines.push("", `Managed commands are unavailable: ${input.unavailable}`);
@@ -1809,6 +1823,9 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
     "[--flags]"
   ].join(" ");
   const lines = [descriptor.description, "", usage, ""];
+  if (descriptor.unavailableReason !== undefined) {
+    lines.push(`Unavailable: ${descriptor.unavailableReason}`, "");
+  }
   if (fields.length > 0) {
     lines.push("Arguments:");
     const labels = new Map(fields.map((field) => {
@@ -1845,115 +1862,25 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
 `;
 }
 
-// src/tools/cli/session.ts
-function nativeDescriptor(definition) {
-  return {
-    description: definition.description,
-    argumentSchema: definition.input,
-    presentationSchema: cliCommandPresentationSchema(definition)
-  };
-}
-function assertCommandShape(name, descriptor, exists, passthroughField, applicationGlobals = new Set) {
+// src/tools/cli/command-shape.ts
+function commandShapeIssue(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`);
   }
+  if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
+    throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
+  }
   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(", ")}`);
+    return `[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}"`);
+    return `[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`;
   }
 }
-function createCliSession(config, io) {
-  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 descriptor = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
-    assertCommandShape(definition.name, descriptor, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
-    nativeCommands.set(definition.name, definition);
-    nativeHelp.set(definition.name, descriptor);
-  }
-  return {
-    config,
-    io,
-    applicationOptions,
-    applicationGlobalNames,
-    nativeCommands,
-    nativeHelp
-  };
-}
-function resolveCliRoute(session, argv) {
-  const { config } = session;
-  const { stdout, stderr, exit } = session.io;
-  let globals;
-  let routableArgv;
-  try {
-    const lifted = extractCliGlobalOptions2(argv, config.globalOptions);
-    globals = lifted.globals;
-    routableArgv = lifted.argv;
-  } catch (error) {
-    if (!(error instanceof CliArgumentError2))
-      throw error;
-    stderr(`${error.message}
-`);
-    exit(2);
-    return;
-  }
-  const typedGlobals = globals;
-  const route = routeCliArgv2(routableArgv, config.defaultCommand);
-  if (route.error) {
-    stderr(`${route.error}
-`);
-    exit(2);
-    return;
-  }
-  const { command, commandArgv } = route;
-  if (route.version || command === "--version" || command === "version") {
-    stdout(`${config.name} ${config.version}
-`);
-    exit(0);
-    return;
-  }
-  const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
-  const helpRequested = beforeSeparator.includes("--help") || beforeSeparator.includes("-h");
-  return {
-    globals,
-    typedGlobals,
-    route,
-    command,
-    commandArgv,
-    beforeSeparator,
-    helpRequested
-  };
-}
-function emitOptionsFor(config, json, toolName) {
-  return {
-    json,
-    toolName,
-    errorHint: config.errorHint,
-    exitCodes: { ...DEFAULT_EXIT_CODES2, ...config.exitCodes }
-  };
-}
 
 // src/tools/cli/managed-surface.ts
 async function buildManagedSurface(session, typedGlobals, forExecution) {
@@ -1979,7 +1906,7 @@ async function buildManagedSurface(session, typedGlobals, forExecution) {
       };
     }
   }
-  const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertCommandShape);
+  const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, commandShapeIssue);
   return { resolved: true, auth, help, tools };
 }
 
@@ -2056,6 +1983,128 @@ async function prepareInvocation(command, commandArgv, descriptor, config, readS
   return { ok: true, toolArgs, options };
 }
 
+// src/tools/cli/session.ts
+function nativeDescriptor(definition) {
+  return {
+    description: definition.description,
+    argumentSchema: definition.input,
+    presentationSchema: cliCommandPresentationSchema(definition)
+  };
+}
+function createCliSession(config, io) {
+  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 descriptor = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
+    const issue = commandShapeIssue(definition.name, descriptor, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
+    if (issue !== undefined)
+      throw new Error(issue);
+    nativeCommands.set(definition.name, definition);
+    nativeHelp.set(definition.name, descriptor);
+  }
+  return {
+    config,
+    io,
+    applicationOptions,
+    applicationGlobalNames,
+    nativeCommands,
+    nativeHelp
+  };
+}
+function resolveCliRoute(session, argv) {
+  const { config } = session;
+  const { stdout, stderr, exit } = session.io;
+  let globals;
+  let routableArgv;
+  try {
+    const lifted = extractCliGlobalOptions2(argv, config.globalOptions);
+    globals = lifted.globals;
+    routableArgv = lifted.argv;
+  } catch (error) {
+    if (!(error instanceof CliArgumentError2))
+      throw error;
+    stderr(`${error.message}
+`);
+    exit(2);
+    return;
+  }
+  const typedGlobals = globals;
+  const route = routeCliArgv2(routableArgv, config.defaultCommand);
+  if (route.error) {
+    stderr(`${route.error}
+`);
+    exit(2);
+    return;
+  }
+  const { command, commandArgv } = route;
+  if (route.version || command === "--version" || command === "version") {
+    stdout(`${config.name} ${config.version}
+`);
+    exit(0);
+    return;
+  }
+  const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
+  const helpRequested = beforeSeparator.some((token) => {
+    if (token === "--help" || token === "-h")
+      return true;
+    const option = classifyLongOptionToken(token);
+    return option?.name === "help" && option.value !== undefined && isReservedBoolWord(option.value) && parseReservedBool("help", option.value);
+  });
+  return {
+    globals,
+    typedGlobals,
+    route,
+    command,
+    commandArgv,
+    beforeSeparator,
+    helpRequested
+  };
+}
+function emitOptionsFor(config, json, toolName) {
+  return {
+    json,
+    toolName,
+    errorHint: config.errorHint,
+    exitCodes: { ...DEFAULT_EXIT_CODES2, ...config.exitCodes }
+  };
+}
+
+// src/tools/cli/unavailable.ts
+function unavailableCommand(reason) {
+  return toolResultFromError(new AppError2("CLI_COMMAND_UNAVAILABLE", {
+    message: reason,
+    status: STITCH_ERROR_STATUS2.CLI_COMMAND_UNAVAILABLE,
+    retryable: false
+  }));
+}
+function unavailableCommandJson(argv) {
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--")
+      break;
+    if (token === undefined)
+      continue;
+    const option = classifyLongOptionToken(token);
+    if (option?.name !== "json")
+      continue;
+    return option.value === undefined ? separateBoolValue(argv[i + 1]) ?? true : isReservedBoolWord(option.value) && parseReservedBool("json", option.value);
+  }
+  return false;
+}
+
 // src/tools/cli/run-managed.ts
 async function runManagedInvocation(session, route) {
   const { config } = session;
@@ -2077,7 +2126,7 @@ function respondTopLevelHelp(session, route, managed) {
   const helpFilter = route.route.helpFilter ?? (command !== undefined ? commandArgv[0] : undefined);
   const filter = helpFilter !== undefined && !helpFilter.startsWith("-") ? helpFilter : undefined;
   if (filter !== undefined && filterCommands(managed.help, filter).size === 0) {
-    stderr(`no command matches "${filter}" (${managed.help.size} available)
+    stderr(`no command matches "${filter}" (${[...managed.help.values()].filter((entry) => entry.unavailableReason === undefined).length} available)
 ` + (managed.resolved ? "" : `Managed commands are unavailable: ${managed.reason}
 `));
     const codes = { ...DEFAULT_EXIT_CODES2, ...config.exitCodes };
@@ -2098,19 +2147,22 @@ function respondTopLevelHelp(session, route, managed) {
 async function runManagedCommand(session, route, command, managed) {
   const { config, applicationOptions } = session;
   const { stdout, stderr, exit, readStdin } = session.io;
-  const tool = managed.tools.get(command);
-  if (!tool) {
+  const descriptor = managed.help.get(command);
+  if (!descriptor) {
     stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
 `);
     return exit(1);
   }
-  const descriptor = managed.help.get(command);
-  if (!descriptor)
-    throw new Error("[stitchkit] managed CLI descriptor invariant failed");
   if (route.helpRequested) {
     stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
+  if (descriptor.unavailableReason !== undefined) {
+    return exit(emitResult2(unavailableCommand(descriptor.unavailableReason), { stdout, stderr }, emitOptionsFor(config, unavailableCommandJson(route.commandArgv), command)));
+  }
+  const tool = managed.tools.get(command);
+  if (!tool)
+    throw new Error("[stitchkit] managed CLI executable invariant failed");
   const prepared = await prepareInvocation(command, route.commandArgv, descriptor, config, readStdin);
   if (!prepared.ok) {
     stderr(`${prepared.message}
@@ -2171,6 +2223,9 @@ async function executeManagedTool(session, route, command, managed, tool, { tool
       initial: result,
       wait: waitConfig,
       call: async (toolName, args) => {
+        const unavailable = managed.help.get(toolName)?.unavailableReason;
+        if (unavailable !== undefined)
+          return unavailableCommand(unavailable);
         const pollTool = managed.tools.get(toolName);
         if (!pollTool) {
           return {

package/dist/{index-k0zfcxf5.js → index-z8fnfj42.js}

@@ -17,7 +17,7 @@ import {
   replaceMessage,
   ArchiveSpillSchema,
   createAgentRuntimeStore2
-} from "./index-yjnmac9b.js";
+} from "./index-09dyy94r.js";
 
 // src/agent-runtime/store-memory.ts
 import { z as z2 } from "zod";

package/dist/{index-gz9jf461.js → index-zbs0g0v2.js}

@@ -19,7 +19,7 @@ import {
   appendEventIn,
   ArchiveProjectionSchema,
   createAgentRuntimeStore2
-} from "./index-yjnmac9b.js";
+} from "./index-09dyy94r.js";
 import {
   AgentConversationPageSchema2,
   AgentConversationMessagePageSchema2

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

@@ -0,0 +1,4 @@
+import type { CliCommandPresentation } from './policy.js';
+/** Local configuration faults throw; only argv field conflicts become unavailable. */
+export declare function commandShapeIssue(name: string, descriptor: CliCommandPresentation, exists: boolean, passthroughField?: string, applicationGlobals?: ReadonlySet<string>): string | undefined;
+//# sourceMappingURL=command-shape.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command-shape.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/command-shape.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,sFAAsF;AACtF,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,sBAAsB,EAClC,MAAM,EAAE,OAAO,EACf,gBAAgB,CAAC,EAAE,MAAM,EACzB,kBAAkB,GAAE,WAAW,CAAC,MAAM,CAAa,GAClD,MAAM,GAAG,SAAS,CAwBpB"}

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

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAiBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAkBhC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,WAAW,GAAG,MAAM,CAY/E;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE,WAAW,GAChB,MAAM,CAeR"}

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

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAkIvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAsCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CAyER"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAkIvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAyCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA4ER"}

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

@@ -135,7 +135,7 @@ export declare function createCliInvoker<TAuth = unknown, TContext extends Recor
  * empty map — the uniqueness and shape checks have to see both halves, or a
  * managed command could silently shadow a native one.
  */
-export declare function buildCliSurface<TAuth, TContext extends Record<string, unknown>, TGlobals extends ZodObject>(config: CliInvokerConfig<TAuth, TContext, TGlobals>, auth: Awaited<TAuth> | undefined, nativeHelp: Map<string, CliCommandPresentation>, applicationGlobalNames: ReadonlySet<string>, assertShape?: (name: string, descriptor: CliCommandPresentation, exists: boolean, passthroughField: string | undefined, globalNames: ReadonlySet<string>) => void): {
+export declare function buildCliSurface<TAuth, TContext extends Record<string, unknown>, TGlobals extends ZodObject>(config: CliInvokerConfig<TAuth, TContext, TGlobals>, auth: Awaited<TAuth> | undefined, nativeHelp: Map<string, CliCommandPresentation>, applicationGlobalNames: ReadonlySet<string>, shapeIssue?: (name: string, descriptor: CliCommandPresentation, exists: boolean, passthroughField: string | undefined, globalNames: ReadonlySet<string>) => string | undefined): {
     tools: Map<string, MountableTool>;
     help: Map<string, CliCommandPresentation>;
 };

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

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

package/dist/tools/cli/managed-surface.d.ts

@@ -2,7 +2,7 @@ import type { ZodObject, z } from 'zod';
 import { type ToolResult } from '../execute-result.js';
 import type { MountableTool } from '../mount.js';
 import type { CliCommandPresentation } from './policy.js';
-import { type CliSession } from './session.js';
+import type { CliSession } from './session.js';
 /**
  * The managed surface, or the reason there isn't one.
  *
@@ -11,7 +11,8 @@ import { type CliSession } from './session.js';
  * and it knows why the rest are missing. Letting the rejection escape printed
  * neither, and answering `Unknown command` would be a lie: the name is not
  * unknown, it is unresolvable. Only identity resolution is caught here; a
- * configuration fault in the surface itself is still a startup error.
+ * local configuration fault is still a startup error; runtime argv field
+ * conflicts remain discoverable as unavailable commands.
  */
 export type ManagedSurface<TAuth> = {
     resolved: true;

package/dist/tools/cli/managed-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"managed-surface.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/managed-surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EAAE,KAAK,UAAU,EAA4C,MAAM,mBAAmB,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAC5B;IACE,QAAQ,EAAE,IAAI,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC1C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACnC,GACD;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,EAAE,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CAC3C,CAAC;AAEN,wBAAsB,mBAAmB,CACvC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAChC,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAuChC"}
+{"version":3,"file":"managed-surface.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/managed-surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EAAE,KAAK,UAAU,EAA4C,MAAM,mBAAmB,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAC5B;IACE,QAAQ,EAAE,IAAI,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC1C,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACnC,GACD;IACE,QAAQ,EAAE,KAAK,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE;QAAE,EAAE,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CAC3C,CAAC;AAEN,wBAAsB,mBAAmB,CACvC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAChC,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAuChC"}

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

@@ -9,6 +9,8 @@ export interface CliPresentationPolicyConfig {
 }
 export interface CliCommandPresentation {
     description: string;
+    /** An argv field conflict in a runtime catalogue entry; never executable. */
+    unavailableReason?: string;
     argumentSchema: Parameters<typeof describeSchemaFields>[0];
     presentationSchema: Record<string, unknown>;
     /** Canonical field name → one short alias. */

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

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,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"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/policy.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,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,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,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/run-managed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-managed.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-managed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAWrC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAO3E,wFAAwF;AACxF,wBAAsB,oBAAoB,CACxC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAC1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC1F"}
+{"version":3,"file":"run-managed.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-managed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAWrC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAQ3E,wFAAwF;AACxF,wBAAsB,oBAAoB,CACxC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAC1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC1F"}

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

@@ -10,7 +10,6 @@ import type { CliConfig } from './config.js';
 import { type EmitOptions } from './format.js';
 import type { CliIo } from './io.js';
 import { type CliCommandPresentation } from './policy.js';
-export declare function assertCommandShape(name: string, descriptor: CliCommandPresentation, exists: boolean, passthroughField?: string, applicationGlobals?: ReadonlySet<string>): void;
 export interface CliSession<TAuth, TContext extends Record<string, unknown>, TGlobals extends ZodObject> {
     config: CliConfig<TAuth, TContext, TGlobals>;
     io: CliIo;

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

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAIvF,OAAO,EAAE,KAAK,YAAY,EAAsC,MAAM,cAAc,CAAC;AAErF,OAAO,EAAE,KAAK,oBAAoB,EAAgC,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,EAA8B,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAYnF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,sBAAsB,EAClC,MAAM,EAAE,OAAO,EACf,gBAAgB,CAAC,EAAE,MAAM,EACzB,kBAAkB,GAAE,WAAW,CAAC,MAAM,CAAa,GAClD,IAAI,CA4BN;AAED,MAAM,WAAW,UAAU,CACzB,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS;IAE1B,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC7C,EAAE,EAAE,KAAK,CAAC;IACV,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAClD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACjD;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAC9B,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC5C,EAAE,EAAE,KAAK,GACR,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAgDvC;AAED,MAAM,WAAW,QAAQ,CAAC,QAAQ,SAAS,SAAS;IAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,IAAI,EAAE,MAAM,EAAE,GACb,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,CAmDhC;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC,EAClD,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,WAAW,CAOb"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAIvF,OAAO,EACL,KAAK,YAAY,EAIlB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,oBAAoB,EAAgC,MAAM,WAAW,CAAC;AAEpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,EAA8B,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAYnF,MAAM,WAAW,UAAU,CACzB,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS;IAE1B,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC7C,EAAE,EAAE,KAAK,CAAC;IACV,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,sBAAsB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAClD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;CACjD;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAC9B,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC5C,EAAE,EAAE,KAAK,GACR,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAiDvC;AAED,MAAM,WAAW,QAAQ,CAAC,QAAQ,SAAS,SAAS;IAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,IAAI,EAAE,MAAM,EAAE,GACb,QAAQ,CAAC,QAAQ,CAAC,GAAG,SAAS,CA4DhC;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,CAAC,EAClD,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,WAAW,CAOb"}

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

@@ -0,0 +1,10 @@
+import { type ToolFailure } from '../execute-result.js';
+/** One refusal for direct dispatch and a known, unavailable --wait target. */
+export declare function unavailableCommand(reason: string): ToolFailure;
+/**
+ * Choose only the error's format, without admitting arguments of a command that
+ * cannot run. Its availability refusal takes precedence over argument errors.
+ * Reuse the framework's token/boolean vocabulary; after -- everything is data.
+ */
+export declare function unavailableCommandJson(argv: readonly string[]): boolean;
+//# sourceMappingURL=unavailable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unavailable.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/unavailable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,WAAW,EAAuB,MAAM,mBAAmB,CAAC;AAI1E,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAQ9D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAYvE"}

package/llms/cli.2.txt

@@ -290,7 +290,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |

package/llms/cli.txt

@@ -490,13 +490,42 @@ 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
+the flag. An application global that collides with a framework option is refused
+at startup. Field collisions in authored commands are configuration errors;
+runtime catalogue entries are isolated as described below. 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 one runtime command cannot be represented in argv
+
+A `runtimeTools` catalogue can change independently of the CLI application. An
+entry whose input declares a framework option such as `json`, or a field shadowed
+by an application global such as `caller`, cannot receive that field through argv.
+Only that entry becomes unavailable. Other commands still run, and top-level,
+filtered and command-specific help retain the entry and its full reason:
+
+```text
+  inspect  Inspect an operation [unavailable]
+    Unavailable: [stitchkit] CLI command "inspect" declares field(s) shadowed by application global options: caller
+```
+
+Calling it returns `CLI_COMMAND_UNAVAILABLE`, `retryable: false`, and the same
+reason in `details.message` on stderr; the default exit code is 1. `--json`
+compacts the error as usual; `exitCodes` and `errorHint` apply. The refusal precedes
+command argument parsing, stdin, context, hooks and the handler; `--dry-run` cannot
+turn it into success. A known unavailable `--wait` target returns the same refusal;
+an unknown target keeps `NOT_FOUND`.
+
+This isolates only reserved/global **field** conflicts in `runtimeTools`.
+Native commands and contract-defined `services` still fail at startup for those
+conflicts. Duplicate or reserved command names and invalid local aliases,
+positionals or passthrough policies remain configuration errors for every entry.
+`createCliInvoker` receives globals and command input separately and has no argv
+projection, so its own `caller` or `json` input stays callable without renaming.
+See [ADR 0273](../decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md).
+
 ## When the managed surface cannot resolve
 
 A CLI whose commands come from a running server declares them with a factory,

package/llms/server.4.txt

@@ -553,7 +553,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,