terminal-pilot 0.0.33 → 0.0.35

package/dist/cli.js

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 
 // src/cli.ts
 import { realpath as realpath3 } from "node:fs/promises";
-import path24 from "node:path";
+import path25 from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 
 // ../toolcraft/src/cli.ts
@@ -920,7 +920,7 @@ function formatColumns(opts) {
       return [`${firstIndent}${row.left}`];
     }
     const rightLines = wrapWords(row.right, rightWidth);
-    if (visibleWidth(row.left) > leftWidth) {
+    if (visibleWidth(row.left) >= leftWidth) {
       return [
         `${firstIndent}${row.left}`,
         ...rightLines.map((line) => `${continuationIndent}${line}`)
@@ -1057,7 +1057,7 @@ function formatColumns2(opts) {
       return [`${firstIndent}${row.left}`];
     }
     const rightLines = wrapWords2(row.right, rightWidth);
-    if (row.left.length > leftWidth) {
+    if (row.left.length >= leftWidth) {
       return [
         `${firstIndent}${row.left}`,
         ...rightLines.map((line) => `${continuationIndent}${line}`)
@@ -1877,9 +1877,9 @@ var GLYPHS = {
   barEnd: glyph("\u2514", "-"),
   radioActive: glyph("\u25CF", ">"),
   radioInactive: glyph("\u25CB", " "),
-  checkboxActive: glyph("\u25FB", "[ ]"),
-  checkboxSelected: glyph("\u25FC", "[+]"),
-  checkboxInactive: glyph("\u25FB", "[ ]"),
+  checkboxActive: "[ ]",
+  checkboxSelected: "[x]",
+  checkboxInactive: "[ ]",
   passwordMask: glyph("\u2022", "*"),
   ellipsis: "..."
 };
@@ -1930,6 +1930,9 @@ function mapKey(name, char) {
   if (char === " ") {
     return "space";
   }
+  if (char !== void 0 && aliases[char] !== void 0) {
+    return aliases[char];
+  }
   if (!name) {
     return void 0;
   }
@@ -2743,17 +2746,17 @@ function validate(schema, value) {
   }
   return { ok: true, value: result.present ? result.value : void 0 };
 }
-function walkSchema(schema, value, path25, state) {
+function walkSchema(schema, value, path26, state) {
   if (schema.kind === "optional") {
-    return walkOptional(schema, value, path25, state);
+    return walkOptional(schema, value, path26, state);
   }
   if (value === missingValue) {
     addIssue(
       state,
-      path25,
+      path26,
       expectedFor(schema),
       "missing",
-      `Expected ${expectedFor(schema)} at ${formatPath(path25)}`
+      `Expected ${expectedFor(schema)} at ${formatPath(path26)}`
     );
     return { present: false };
   }
@@ -2762,149 +2765,149 @@ function walkSchema(schema, value, path25, state) {
   }
   switch (schema.kind) {
     case "string":
-      return walkString(schema, value, path25, state);
+      return walkString(schema, value, path26, state);
     case "number":
-      return walkNumber(schema, value, path25, state);
+      return walkNumber(schema, value, path26, state);
     case "boolean":
-      return walkBoolean(value, path25, state);
+      return walkBoolean(value, path26, state);
     case "enum":
-      return walkEnum(schema, value, path25, state);
+      return walkEnum(schema, value, path26, state);
     case "array":
-      return walkArray(schema, value, path25, state);
+      return walkArray(schema, value, path26, state);
     case "object":
-      return walkObject(schema, value, path25, state);
+      return walkObject(schema, value, path26, state);
     case "oneOf":
-      return walkOneOf(schema, value, path25, state);
+      return walkOneOf(schema, value, path26, state);
     case "union":
-      return walkUnion(schema, value, path25, state);
+      return walkUnion(schema, value, path26, state);
     case "record":
-      return walkRecord(schema, value, path25, state);
+      return walkRecord(schema, value, path26, state);
     case "json":
-      return walkJson(value, path25, state);
+      return walkJson(value, path26, state);
   }
 }
-function walkOptional(schema, value, path25, state) {
+function walkOptional(schema, value, path26, state) {
   if (value === missingValue || value === void 0) {
     const defaultValue = getDefault(schema.inner);
     if (defaultValue.present) {
-      return walkSchema(schema.inner, cloneDefault(defaultValue.value), path25, state);
+      return walkSchema(schema.inner, cloneDefault(defaultValue.value), path26, state);
     }
     return { present: false };
   }
-  return walkSchema(schema.inner, value, path25, state);
+  return walkSchema(schema.inner, value, path26, state);
 }
-function walkString(schema, value, path25, state) {
+function walkString(schema, value, path26, state) {
   if (typeof value !== "string") {
-    addExpectedIssue(state, path25, "string", value);
+    addExpectedIssue(state, path26, "string", value);
     return { present: true, value };
   }
   if (schema.minLength !== void 0 && value.length < schema.minLength) {
     const expected = `string with length at least ${schema.minLength}`;
     addIssue(
       state,
-      path25,
+      path26,
       expected,
       `string with length ${value.length}`,
-      `Expected ${expected} at ${formatPath(path25)}`
+      `Expected ${expected} at ${formatPath(path26)}`
     );
   }
   if (schema.maxLength !== void 0 && value.length > schema.maxLength) {
     const expected = `string with length at most ${schema.maxLength}`;
     addIssue(
       state,
-      path25,
+      path26,
       expected,
       `string with length ${value.length}`,
-      `Expected ${expected} at ${formatPath(path25)}`
+      `Expected ${expected} at ${formatPath(path26)}`
     );
   }
   if (schema.pattern !== void 0) {
     const pattern = compilePattern(schema.pattern);
     if (pattern === void 0 || !pattern.test(value)) {
       const expected = `string matching pattern ${schema.pattern}`;
-      addIssue(state, path25, expected, value, `Expected ${expected} at ${formatPath(path25)}`);
+      addIssue(state, path26, expected, value, `Expected ${expected} at ${formatPath(path26)}`);
     }
   }
   return { present: true, value };
 }
-function walkNumber(schema, value, path25, state) {
+function walkNumber(schema, value, path26, state) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
-    addExpectedIssue(state, path25, schema.jsonType === "integer" ? "integer" : "number", value);
+    addExpectedIssue(state, path26, schema.jsonType === "integer" ? "integer" : "number", value);
     return { present: true, value };
   }
   if (schema.jsonType === "integer" && !Number.isInteger(value)) {
-    addExpectedIssue(state, path25, "integer", value);
+    addExpectedIssue(state, path26, "integer", value);
   }
   if (schema.minimum !== void 0 && value < schema.minimum) {
     const expected = `number greater than or equal to ${schema.minimum}`;
-    addIssue(state, path25, expected, String(value), `Expected ${expected} at ${formatPath(path25)}`);
+    addIssue(state, path26, expected, String(value), `Expected ${expected} at ${formatPath(path26)}`);
   }
   if (schema.maximum !== void 0 && value > schema.maximum) {
     const expected = `number less than or equal to ${schema.maximum}`;
-    addIssue(state, path25, expected, String(value), `Expected ${expected} at ${formatPath(path25)}`);
+    addIssue(state, path26, expected, String(value), `Expected ${expected} at ${formatPath(path26)}`);
   }
   return { present: true, value };
 }
-function walkBoolean(value, path25, state) {
+function walkBoolean(value, path26, state) {
   if (typeof value !== "boolean") {
-    addExpectedIssue(state, path25, "boolean", value);
+    addExpectedIssue(state, path26, "boolean", value);
   }
   return { present: true, value };
 }
-function walkEnum(schema, value, path25, state) {
+function walkEnum(schema, value, path26, state) {
   if (!schema.values.includes(value)) {
     const expected = `one of ${schema.values.join(", ")}`;
     addIssue(
       state,
-      path25,
+      path26,
       expected,
       receivedValue(value),
-      `Expected ${expected} at ${formatPath(path25)}`
+      `Expected ${expected} at ${formatPath(path26)}`
     );
   }
   return { present: true, value };
 }
-function walkArray(schema, value, path25, state) {
+function walkArray(schema, value, path26, state) {
   if (!Array.isArray(value)) {
-    addExpectedIssue(state, path25, "array", value);
+    addExpectedIssue(state, path26, "array", value);
     return { present: true, value };
   }
   if (schema.minItems !== void 0 && value.length < schema.minItems) {
     const expected = `array with at least ${schema.minItems} items`;
     addIssue(
       state,
-      path25,
+      path26,
       expected,
       `array with ${value.length} items`,
-      `Expected ${expected} at ${formatPath(path25)}`
+      `Expected ${expected} at ${formatPath(path26)}`
     );
   }
   if (schema.maxItems !== void 0 && value.length > schema.maxItems) {
     const expected = `array with at most ${schema.maxItems} items`;
     addIssue(
       state,
-      path25,
+      path26,
       expected,
       `array with ${value.length} items`,
-      `Expected ${expected} at ${formatPath(path25)}`
+      `Expected ${expected} at ${formatPath(path26)}`
     );
   }
   const nextValue = value.map((item, index) => {
-    const result = walkSchema(schema.item, item, [...path25, String(index)], state);
+    const result = walkSchema(schema.item, item, [...path26, String(index)], state);
     return result.present ? result.value : item;
   });
   return { present: true, value: nextValue };
 }
-function walkObject(schema, value, path25, state, injectedProperties = {}) {
+function walkObject(schema, value, path26, state, injectedProperties = {}) {
   if (!isPlainRecord(value)) {
-    addExpectedIssue(state, path25, "object", value);
+    addExpectedIssue(state, path26, "object", value);
     return { present: true, value };
   }
   const nextValue = {};
   const allowedKeys = /* @__PURE__ */ new Set([...Object.keys(schema.shape), ...Object.keys(injectedProperties)]);
   for (const [key2, propertySchema] of Object.entries(schema.shape)) {
     const propertyValue = Object.hasOwn(value, key2) ? value[key2] : missingValue;
-    const result = walkSchema(propertySchema, propertyValue, [...path25, key2], state);
+    const result = walkSchema(propertySchema, propertyValue, [...path26, key2], state);
     if (result.present) {
       setOwnValue(nextValue, key2, result.value);
     }
@@ -2923,18 +2926,18 @@ function walkObject(schema, value, path25, state, injectedProperties = {}) {
     if (schema.additionalProperties === true) {
       setOwnValue(nextValue, key2, propertyValue);
     } else {
-      addUnexpectedPropertyIssue(state, [...path25, key2]);
+      addUnexpectedPropertyIssue(state, [...path26, key2]);
     }
   }
   return { present: true, value: nextValue };
 }
-function walkOneOf(schema, value, path25, state) {
+function walkOneOf(schema, value, path26, state) {
   if (!isPlainRecord(value)) {
-    addExpectedIssue(state, path25, "object", value);
+    addExpectedIssue(state, path26, "object", value);
     return { present: true, value };
   }
   const discriminatorValue = value[schema.discriminator];
-  const discriminatorPath = [...path25, schema.discriminator];
+  const discriminatorPath = [...path26, schema.discriminator];
   const branchValues = Object.keys(schema.branches);
   const expected = `one of ${branchValues.join(", ")}`;
   if (!Object.hasOwn(value, schema.discriminator)) {
@@ -2943,7 +2946,7 @@ function walkOneOf(schema, value, path25, state) {
       discriminatorPath,
       expected,
       "missing",
-      `Missing discriminator "${schema.discriminator}" at ${formatPath(path25)}. Expected one of: ${branchValues.join(", ")}.`
+      `Missing discriminator "${schema.discriminator}" at ${formatPath(path26)}. Expected one of: ${branchValues.join(", ")}.`
     );
     return { present: true, value };
   }
@@ -2957,21 +2960,21 @@ function walkOneOf(schema, value, path25, state) {
     );
     return { present: true, value };
   }
-  return walkObject(schema.branches[discriminatorValue], value, path25, state, {
+  return walkObject(schema.branches[discriminatorValue], value, path26, state, {
     [schema.discriminator]: discriminatorValue
   });
 }
-function walkUnion(schema, value, path25, state) {
+function walkUnion(schema, value, path26, state) {
   if (isPlainRecord(value)) {
     const candidateBranches = schema.branches.filter((branch) => hasRequiredKeys(branch, value));
     if (candidateBranches.length === 1) {
-      return walkObject(candidateBranches[0], value, path25, state);
+      return walkObject(candidateBranches[0], value, path26, state);
     }
   }
   const matches = [];
   for (const branch of schema.branches) {
     const branchState = { issues: [] };
-    const result = walkObject(branch, value, path25, branchState);
+    const result = walkObject(branch, value, path26, branchState);
     if (branchState.issues.length === 0 && result.present) {
       matches.push({ fingerprint: getRequiredKeyFingerprint(branch), value: result.value });
     }
@@ -2983,19 +2986,19 @@ function walkUnion(schema, value, path25, state) {
     const branchDescriptions = schema.branches.map((branch) => getRequiredKeyFingerprint(branch));
     addIssueWithMessage(
       state,
-      path25,
+      path26,
       "exactly one union branch",
       "0 matching branches",
-      `No union branch matched at ${formatPath(path25)}. Tried ${schema.branches.length} branches. Expected one of: ${branchDescriptions.join(" | ")}.`
+      `No union branch matched at ${formatPath(path26)}. Tried ${schema.branches.length} branches. Expected one of: ${branchDescriptions.join(" | ")}.`
     );
     return { present: true, value };
   }
   addIssueWithMessage(
     state,
-    path25,
+    path26,
     "exactly one union branch",
     `${matches.length} matching branches`,
-    `Expected exactly one union branch at ${formatPath(path25)}, but matched more than one branch: ${matches.map((match) => match.fingerprint).join(" | ")}`
+    `Expected exactly one union branch at ${formatPath(path26)}, but matched more than one branch: ${matches.map((match) => match.fingerprint).join(" | ")}`
   );
   return { present: true, value };
 }
@@ -3007,25 +3010,25 @@ function hasRequiredKeys(schema, value) {
   }
   return true;
 }
-function walkRecord(schema, value, path25, state) {
+function walkRecord(schema, value, path26, state) {
   if (!isPlainRecord(value)) {
-    addExpectedIssue(state, path25, "object", value);
+    addExpectedIssue(state, path26, "object", value);
     return { present: true, value };
   }
   const nextValue = {};
   for (const [key2, propertyValue] of Object.entries(value)) {
-    const result = walkSchema(schema.value, propertyValue, [...path25, key2], state);
+    const result = walkSchema(schema.value, propertyValue, [...path26, key2], state);
     if (result.present) {
       setOwnValue(nextValue, key2, result.value);
     }
   }
   return { present: true, value: nextValue };
 }
-function walkJson(value, path25, state) {
+function walkJson(value, path26, state) {
   if (isJsonValue(value)) {
     return { present: true, value };
   }
-  addExpectedIssue(state, path25, "JSON value", value);
+  addExpectedIssue(state, path26, "JSON value", value);
   return { present: true, value };
 }
 function getDefault(schema) {
@@ -3103,45 +3106,45 @@ function expectedFor(schema) {
       return expectedFor(schema.inner);
   }
 }
-function addExpectedIssue(state, path25, expected, value) {
+function addExpectedIssue(state, path26, expected, value) {
   addIssue(
     state,
-    path25,
+    path26,
     expected,
     receivedType(value),
-    `Expected ${expected} at ${formatPath(path25)}`
+    `Expected ${expected} at ${formatPath(path26)}`
   );
 }
-function addUnexpectedPropertyIssue(state, path25) {
+function addUnexpectedPropertyIssue(state, path26) {
   addIssue(
     state,
-    path25,
+    path26,
     "no additional properties",
     "unknown property",
-    `Unexpected property ${formatPath(path25)}`
+    `Unexpected property ${formatPath(path26)}`
   );
 }
-function addIssue(state, path25, expected, received, _message) {
+function addIssue(state, path26, expected, received, _message) {
   state.issues.push({
-    path: path25,
+    path: path26,
     expected,
     received,
-    message: formatIssueMessage(expected, path25, received)
+    message: formatIssueMessage(expected, path26, received)
   });
 }
-function addIssueWithMessage(state, path25, expected, received, message2) {
+function addIssueWithMessage(state, path26, expected, received, message2) {
   state.issues.push({
-    path: path25,
+    path: path26,
     expected,
     received,
     message: message2
   });
 }
-function formatIssueMessage(expected, path25, received) {
-  return `Expected ${expected} at ${formatPath(path25)}, got ${received}`;
+function formatIssueMessage(expected, path26, received) {
+  return `Expected ${expected} at ${formatPath(path26)}, got ${received}`;
 }
-function formatPath(path25) {
-  return path25.length === 0 ? "value" : path25.join(".");
+function formatPath(path26) {
+  return path26.length === 0 ? "value" : path26.join(".");
 }
 function compilePattern(pattern) {
   try {
@@ -3309,6 +3312,50 @@ var S = {
   Json
 };
 
+// ../toolcraft/src/runtime-logging.ts
+var LOG_LEVEL_RANK = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+  trace: 5
+};
+var LOG_LEVELS = Object.freeze([
+  "silent",
+  "error",
+  "warn",
+  "info",
+  "debug",
+  "trace"
+]);
+function isLogLevel(value) {
+  return LOG_LEVELS.includes(value);
+}
+function shouldEmitDiagnostic(eventLevel, configuredLevel) {
+  if (eventLevel === "silent" || configuredLevel === "silent") {
+    return false;
+  }
+  return LOG_LEVEL_RANK[eventLevel] <= LOG_LEVEL_RANK[configuredLevel];
+}
+function createRuntimeLogger(options = {}) {
+  const level = options.level ?? "warn";
+  const sink = options.logger;
+  return {
+    level,
+    emit(event) {
+      if (!shouldEmitDiagnostic(event.level, level)) {
+        return;
+      }
+      if (typeof sink === "function") {
+        sink(event);
+        return;
+      }
+      sink?.emit(event);
+    }
+  };
+}
+
 // ../toolcraft/src/package-metadata.ts
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
@@ -7777,13 +7824,13 @@ function formatAvailableApprovalCommandPaths(root) {
 }
 function enumerateApprovalCommandPaths(root) {
   const paths = [];
-  const visit = (node, path25) => {
+  const visit = (node, path26) => {
     if (node.kind === "command") {
-      paths.push(path25.join("."));
+      paths.push(path26.join("."));
       return;
     }
     for (const child of getVisibleCliChildren(node)) {
-      visit(child, [...path25, child.name]);
+      visit(child, [...path26, child.name]);
     }
   };
   if (root.kind === "command") {
@@ -7805,34 +7852,36 @@ function getVisibleCliChildren(root) {
   return root.kind === "group" ? root.children.filter(isNodeVisibleInCli) : [];
 }
 function createHandlerContext(command, params17) {
+  const diagnostics = createRuntimeLogger();
   return {
     params: params17,
     secrets: resolveCommandSecrets(command),
     fetch: globalThis.fetch,
     fs: createFs(),
     env: createEnv(),
-    progress() {
-      return void 0;
+    diagnostics,
+    progress(message2) {
+      diagnostics.emit({ level: "info", message: message2, category: "progress" });
     }
   };
 }
 function createFs() {
   return {
-    readFile: async (path25, encoding = "utf8") => readFile3(path25, { encoding }),
-    writeFile: async (path25, contents, options) => {
-      await writeFile2(path25, contents, options);
+    readFile: async (path26, encoding = "utf8") => readFile3(path26, { encoding }),
+    writeFile: async (path26, contents, options) => {
+      await writeFile2(path26, contents, options);
     },
-    exists: async (path25) => {
+    exists: async (path26) => {
       try {
-        await access(path25);
+        await access(path26);
         return true;
       } catch {
         return false;
       }
     },
-    lstat: async (path25) => lstat(path25),
+    lstat: async (path26) => lstat(path26),
     rename: async (fromPath, toPath) => rename(fromPath, toPath),
-    unlink: async (path25) => unlink(path25)
+    unlink: async (path26) => unlink(path26)
   };
 }
 function createEnv(values = process.env) {
@@ -7885,11 +7934,7 @@ var showParams = S.Object({
   approvalId: S.String()
 });
 var runParams = S.Object({
-  approvalId: S.String(),
-  dryRun: S.Optional(S.Boolean({
-    description: "Preview the approval without prompting or executing it",
-    scope: ["cli"]
-  }))
+  approvalId: S.String()
 });
 var approvalsGroup = markApprovalsBuiltIn(
   defineGroup({
@@ -7946,10 +7991,6 @@ var approvalsGroup = markApprovalsBuiltIn(
         scope: runScope,
         params: runParams,
         handler: async ({ params: params17, runtimeOptions, root }) => {
-          if (params17.dryRun === true) {
-            const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
-            return tasks.get(params17.approvalId);
-          }
           return runApproval(params17.approvalId, runtimeOptions, root);
         },
         render: {
@@ -10348,7 +10389,7 @@ var McpClient = class {
       await onPromptsChanged();
     });
     messageLayer.onNotification("notifications/message", async (params17) => {
-      if (onLog === void 0 || !isObjectRecord5(params17) || !isLogLevel(params17.level)) {
+      if (onLog === void 0 || !isObjectRecord5(params17) || !isLogLevel2(params17.level)) {
         return;
       }
       if (!hasOwn(params17, "data")) {
@@ -11703,7 +11744,7 @@ function hasOwn(value, property) {
 function isRequestId(value) {
   return typeof value === "string" || typeof value === "number";
 }
-function isLogLevel(value) {
+function isLogLevel2(value) {
   return value === "debug" || value === "info" || value === "notice" || value === "warning" || value === "error" || value === "critical" || value === "alert" || value === "emergency";
 }
 function toRequestId(value) {
@@ -11835,13 +11876,13 @@ function convertJsonSchema(schema) {
   }
   return convertSchema(schema, schema, []);
 }
-function convertSchema(schema, root, path25) {
-  const resolvedSchema = resolveReferencedSchema(schema, root, path25);
+function convertSchema(schema, root, path26) {
+  const resolvedSchema = resolveReferencedSchema(schema, root, path26);
   const normalizedSchema = normalizeNullability(resolvedSchema);
   const composition = getComposition(normalizedSchema.schema);
   if (Array.isArray(normalizedSchema.schema.type)) {
     throw new Error(
-      `JSON Schema "${formatJsonSchemaPath(path25)}" has an unsupported type "${formatJsonSchemaType(
+      `JSON Schema "${formatJsonSchemaPath(path26)}" has an unsupported type "${formatJsonSchemaType(
         normalizedSchema.schema.type
       )}". Supported: string, number, integer, boolean, array, object.`
     );
@@ -11853,13 +11894,13 @@ function convertSchema(schema, root, path25) {
     return convertEnumSchema(resolvedSchema, normalizedSchema.nullable);
   }
   if (composition !== void 0) {
-    return convertCompositionSchema(normalizedSchema.schema, root, normalizedSchema.nullable, path25);
+    return convertCompositionSchema(normalizedSchema.schema, root, normalizedSchema.nullable, path26);
   }
   if (isRecordSchema(normalizedSchema.schema)) {
     return applyMetadata(
       S.Record(
         convertSchema(normalizedSchema.schema.additionalProperties, root, [
-          ...path25,
+          ...path26,
           "additionalProperties"
         ])
       ),
@@ -11908,12 +11949,12 @@ function convertSchema(schema, root, path25) {
       if (normalizedSchema.schema.items === void 0) {
         throw new Error(
           `JSON Schema "${formatJsonSchemaPath(
-            path25
+            path26
           )}" is an array but is missing the "items" field. Add "items": { ... } to declare the element type.`
         );
       }
       return S.Array(
-        convertSchema(normalizedSchema.schema.items, root, [...path25, "items"]),
+        convertSchema(normalizedSchema.schema.items, root, [...path26, "items"]),
         createCommonOptions(
           normalizedSchema.schema,
           normalizedSchema.nullable,
@@ -11923,7 +11964,7 @@ function convertSchema(schema, root, path25) {
     case "object":
       return convertObjectSchema(normalizedSchema.schema, root, {
         nullable: normalizedSchema.nullable,
-        path: path25
+        path: path26
       });
     case "null":
       return applyMetadata(S.Json(), normalizedSchema.schema, {
@@ -11938,12 +11979,12 @@ function convertSchema(schema, root, path25) {
       }
       throw new Error(
         `JSON Schema "${formatJsonSchemaPath(
-          path25
+          path26
         )}" must declare one of: "type", "enum", "const", "oneOf", "anyOf", or "allOf".`
       );
   }
   throw new Error(
-    `JSON Schema "${formatJsonSchemaPath(path25)}" has an unsupported type "${formatJsonSchemaType(
+    `JSON Schema "${formatJsonSchemaPath(path26)}" has an unsupported type "${formatJsonSchemaType(
       normalizedSchema.schema.type
     )}". Supported: string, number, integer, boolean, array, object.`
   );
@@ -11987,21 +12028,21 @@ function convertEnumSchema(schema, nullable) {
     )
   });
 }
-function convertCompositionSchema(schema, root, nullable, path25) {
+function convertCompositionSchema(schema, root, nullable, path26) {
   const composition = getComposition(schema);
   const branchSchemas = composition?.branches ?? [];
   const keyword = composition?.keyword ?? "oneOf";
   const branches = branchSchemas.map(
-    (branch, index) => resolveReferencedSchema(branch, root, [...path25, keyword, String(index)])
+    (branch, index) => resolveReferencedSchema(branch, root, [...path26, keyword, String(index)])
   );
-  const discriminator = findDiscriminator(branches, root, path25);
+  const discriminator = findDiscriminator(branches, root, path26);
   if (discriminator !== void 0) {
     const convertedBranches = Object.fromEntries(
       branches.map((branch, index) => [
         getDiscriminatorLiteral(branch, discriminator, root),
         convertObjectSchema(branch, root, {
           omitProperty: discriminator,
-          path: [...path25, keyword, String(index)]
+          path: [...path26, keyword, String(index)]
         })
       ])
     );
@@ -12020,7 +12061,7 @@ function convertCompositionSchema(schema, root, nullable, path25) {
     S.Union(
       branches.map(
         (branch, index) => convertObjectSchema(branch, root, {
-          path: [...path25, keyword, String(index)]
+          path: [...path26, keyword, String(index)]
         })
       )
     ),
@@ -12134,11 +12175,11 @@ function getComposition(schema) {
   }
   return void 0;
 }
-function formatJsonSchemaPath(path25) {
-  if (path25.length === 0) {
+function formatJsonSchemaPath(path26) {
+  if (path26.length === 0) {
     return "#";
   }
-  return `#/${path25.map(escapeJsonPointerSegment).join("/")}`;
+  return `#/${path26.map(escapeJsonPointerSegment).join("/")}`;
 }
 function formatJsonSchemaType(type2) {
   return Array.isArray(type2) ? JSON.stringify(type2) : String(type2);
@@ -12154,11 +12195,11 @@ function isRecordSchema(schema) {
   const propertyKeys = Object.keys(schema.properties ?? {});
   return schema.type === "object" && propertyKeys.length === 0 && typeof schema.additionalProperties === "object" && schema.additionalProperties !== null;
 }
-function findDiscriminator(branches, root, path25) {
+function findDiscriminator(branches, root, path26) {
   const [firstBranch] = branches;
   if (firstBranch === void 0) {
     throw new Error(
-      `JSON Schema "${formatJsonSchemaPath(path25)}" uses oneOf/anyOf/allOf but has no branches.`
+      `JSON Schema "${formatJsonSchemaPath(path26)}" uses oneOf/anyOf/allOf but has no branches.`
     );
   }
   const candidateKeys = Object.keys(firstBranch.properties ?? {});
@@ -12198,19 +12239,19 @@ function getDiscriminatorLiteral(branch, key2, root) {
   }
   return void 0;
 }
-function resolveReferencedSchema(schema, root, path25) {
+function resolveReferencedSchema(schema, root, path26) {
   if (schema.$ref === void 0) {
     return schema;
   }
   const resolvedTarget = resolveLocalRef(root, schema.$ref);
   if (resolvedTarget === void 0) {
     throw new Error(
-      `JSON Schema "${formatJsonSchemaPath(path25)}" uses "$ref": ${schema.$ref}. toolcraft only supports internal refs like "#/components/schemas/Foo".`
+      `JSON Schema "${formatJsonSchemaPath(path26)}" uses "$ref": ${schema.$ref}. toolcraft only supports internal refs like "#/components/schemas/Foo".`
     );
   }
   const { $ref: ignoredRef, ...siblingKeywords } = schema;
   void ignoredRef;
-  const resolvedSchema = resolveReferencedSchema(resolvedTarget, root, path25);
+  const resolvedSchema = resolveReferencedSchema(resolvedTarget, root, path26);
   if (Object.keys(siblingKeywords).length === 0) {
     return resolvedSchema;
   }
@@ -12234,9 +12275,9 @@ function mergeJsonSchemas(base, overlay) {
     ...mergedRequired === void 0 ? {} : { required: mergedRequired }
   };
 }
-function hasSelfReferencingRef(schema, root, path25 = "#", activePaths = /* @__PURE__ */ new Set()) {
+function hasSelfReferencingRef(schema, root, path26 = "#", activePaths = /* @__PURE__ */ new Set()) {
   const nextActivePaths = new Set(activePaths);
-  nextActivePaths.add(path25);
+  nextActivePaths.add(path26);
   const localRefPath = getLocalRefPath(schema.$ref);
   if (localRefPath !== void 0) {
     if (nextActivePaths.has(localRefPath)) {
@@ -12247,13 +12288,13 @@ function hasSelfReferencingRef(schema, root, path25 = "#", activePaths = /* @__P
       return true;
     }
   }
-  if (schema.items !== void 0 && hasSelfReferencingRef(schema.items, root, `${path25}/items`, nextActivePaths)) {
+  if (schema.items !== void 0 && hasSelfReferencingRef(schema.items, root, `${path26}/items`, nextActivePaths)) {
     return true;
   }
   if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null && hasSelfReferencingRef(
     schema.additionalProperties,
     root,
-    `${path25}/additionalProperties`,
+    `${path26}/additionalProperties`,
     nextActivePaths
   )) {
     return true;
@@ -12262,7 +12303,7 @@ function hasSelfReferencingRef(schema, root, path25 = "#", activePaths = /* @__P
     if (hasSelfReferencingRef(
       childSchema,
       root,
-      `${path25}/properties/${escapeJsonPointerSegment(key2)}`,
+      `${path26}/properties/${escapeJsonPointerSegment(key2)}`,
       nextActivePaths
     )) {
       return true;
@@ -12272,24 +12313,24 @@ function hasSelfReferencingRef(schema, root, path25 = "#", activePaths = /* @__P
     if (hasSelfReferencingRef(
       childSchema,
       root,
-      `${path25}/$defs/${escapeJsonPointerSegment(key2)}`,
+      `${path26}/$defs/${escapeJsonPointerSegment(key2)}`,
       nextActivePaths
     )) {
       return true;
     }
   }
   for (const [index, childSchema] of (schema.oneOf ?? []).entries()) {
-    if (hasSelfReferencingRef(childSchema, root, `${path25}/oneOf/${index}`, nextActivePaths)) {
+    if (hasSelfReferencingRef(childSchema, root, `${path26}/oneOf/${index}`, nextActivePaths)) {
       return true;
     }
   }
   for (const [index, childSchema] of (schema.anyOf ?? []).entries()) {
-    if (hasSelfReferencingRef(childSchema, root, `${path25}/anyOf/${index}`, nextActivePaths)) {
+    if (hasSelfReferencingRef(childSchema, root, `${path26}/anyOf/${index}`, nextActivePaths)) {
       return true;
     }
   }
   for (const [index, childSchema] of (schema.allOf ?? []).entries()) {
-    if (hasSelfReferencingRef(childSchema, root, `${path25}/allOf/${index}`, nextActivePaths)) {
+    if (hasSelfReferencingRef(childSchema, root, `${path26}/allOf/${index}`, nextActivePaths)) {
       return true;
     }
   }
@@ -12305,14 +12346,14 @@ function getLocalRefPath(ref) {
   return ref.startsWith("#/") ? ref : void 0;
 }
 function resolveLocalRef(root, ref) {
-  const path25 = getLocalRefPath(ref);
-  if (path25 === void 0) {
+  const path26 = getLocalRefPath(ref);
+  if (path26 === void 0) {
     return void 0;
   }
-  if (path25 === "#") {
+  if (path26 === "#") {
     return root;
   }
-  const segments = path25.slice(2).split("/").map(unescapeJsonPointerSegment);
+  const segments = path26.slice(2).split("/").map(unescapeJsonPointerSegment);
   let current = root;
   for (const segment of segments) {
     if (Array.isArray(current)) {
@@ -13383,6 +13424,125 @@ function getExpectedNumberDescription(schema) {
   return bounds.length === 0 ? type2 : `${type2} ${bounds.join(" and ")}`;
 }
 
+// ../toolcraft/src/api-error-summary.ts
+var REQUEST_ID_FIELDS = ["request_id", "requestId", "id"];
+var CODE_FIELDS = ["code", "error_code", "errorCode", "error"];
+var MESSAGE_FIELDS = ["message", "detail", "title", "error_description"];
+function summarizeHttpError(error3) {
+  const body = redactHttpBody(error3.response.body);
+  const retryAfter = getHeader(error3.response.headers, "retry-after");
+  const message2 = extractMessage(body);
+  const summary = {
+    status: error3.response.status,
+    statusText: error3.response.statusText,
+    requestMethod: error3.request.method,
+    requestUrl: error3.request.url,
+    ...message2 === void 0 ? {} : { message: message2 },
+    ...optionalString("requestId", getHeader(error3.response.headers, "x-request-id") ?? extractFirstString(body, REQUEST_ID_FIELDS)),
+    ...optionalString("code", extractCode(body)),
+    ...optionalString("retryAfter", retryAfter),
+    ...optionalArray("fieldErrors", extractFieldErrors(body)),
+    ...optionalString("hint", createHttpErrorHint(error3.response.status, retryAfter))
+  };
+  return summary;
+}
+function createHttpErrorHint(status, retryAfter) {
+  if (status === 401 || status === 403) {
+    return "Check the configured API credentials and permissions.";
+  }
+  if ((status === 429 || status === 503) && retryAfter !== void 0) {
+    return `Retry after ${retryAfter}.`;
+  }
+  return void 0;
+}
+function extractMessage(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const graphqlMessage = extractGraphQlMessage(body);
+  if (graphqlMessage !== void 0) {
+    return graphqlMessage;
+  }
+  return extractFirstString(body, MESSAGE_FIELDS);
+}
+function extractCode(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const graphqlCode = extractGraphQlCode(body);
+  if (graphqlCode !== void 0) {
+    return graphqlCode;
+  }
+  return extractFirstString(body, CODE_FIELDS);
+}
+function extractGraphQlMessage(body) {
+  const [first] = Array.isArray(body.errors) ? body.errors : [];
+  return isPlainObject4(first) && typeof first.message === "string" ? first.message : void 0;
+}
+function extractGraphQlCode(body) {
+  const [first] = Array.isArray(body.errors) ? body.errors : [];
+  if (!isPlainObject4(first) || !isPlainObject4(first.extensions)) {
+    return void 0;
+  }
+  return typeof first.extensions.code === "string" ? first.extensions.code : void 0;
+}
+function extractFieldErrors(body) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  const candidates = [body.field_errors, body.fieldErrors, body.errors, body.non_field_errors];
+  const flattened = candidates.flatMap((candidate) => flattenFieldErrors(candidate, []));
+  return flattened.length === 0 ? void 0 : flattened;
+}
+function flattenFieldErrors(value, path26) {
+  if (typeof value === "string") {
+    return [{ path: formatPath2(path26), message: value }];
+  }
+  if (Array.isArray(value)) {
+    if (value.every((entry) => typeof entry === "string")) {
+      return value.map((message2) => ({ path: formatPath2(path26), message: message2 }));
+    }
+    return value.flatMap((entry, index) => flattenFieldErrors(entry, [...path26, String(index)]));
+  }
+  if (!isPlainObject4(value)) {
+    return [];
+  }
+  return Object.entries(value).flatMap(([key2, nested]) => flattenFieldErrors(nested, [...path26, key2]));
+}
+function formatPath2(path26) {
+  return path26.length === 0 ? "error" : path26.join(".");
+}
+function extractFirstString(body, fields) {
+  if (!isPlainObject4(body)) {
+    return void 0;
+  }
+  for (const field of fields) {
+    const value = body[field];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function getHeader(headers, name) {
+  const lowerName = name.toLowerCase();
+  for (const [key2, value] of Object.entries(headers)) {
+    if (key2.toLowerCase() === lowerName && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function optionalString(name, value) {
+  return value === void 0 ? {} : { [name]: value };
+}
+function optionalArray(name, value) {
+  return value === void 0 ? {} : { [name]: value };
+}
+function isPlainObject4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // ../toolcraft/src/renderer.ts
 import YAML from "yaml";
 function isObject(value) {
@@ -13430,6 +13590,9 @@ function unwrapMcpEnvelope(result) {
 function isArrayOfObjects(value) {
   return Array.isArray(value) && value.every((entry) => isObject(entry));
 }
+function isNonEmptyArrayOfObjects(value) {
+  return Array.isArray(value) && value.length > 0 && value.every((entry) => isObject(entry));
+}
 function stringifyValue2(value) {
   if (value === void 0) {
     return "";
@@ -13484,10 +13647,26 @@ function detailRows(result, depth = 0) {
       rows.push(...detailRows(value, depth + 1));
       continue;
     }
+    if (isNonEmptyArrayOfObjects(value)) {
+      rows.push({ label, value: "" });
+      rows.push(...arrayObjectDetailRows(value, depth + 1));
+      continue;
+    }
     rows.push({ label, value: displayScalar(value) });
   }
   return rows;
 }
+function arrayObjectDetailRows(value, depth) {
+  return value.flatMap((entry, index) => {
+    if (value.length === 1) {
+      return detailRows(entry, depth);
+    }
+    return [
+      { label: `${"  ".repeat(depth)}${index + 1}`, value: "" },
+      ...detailRows(entry, depth + 1)
+    ];
+  });
+}
 function displayScalar(value) {
   if (typeof value === "boolean") {
     return value ? "Yes" : "No";
@@ -13518,17 +13697,31 @@ function directScalarRows(result) {
 function directObjectSections(result) {
   return Object.entries(result).filter(([, value]) => isObject(value)).map(([key2, value]) => ({ title: humanizeKey(key2), rows: detailRows(value) })).filter((section) => section.rows.length > 0);
 }
+function directArrayObjectSections(result) {
+  return Object.entries(result).flatMap(([key2, value]) => {
+    if (!isNonEmptyArrayOfObjects(value)) {
+      return [];
+    }
+    const title = humanizeKey(key2);
+    return value.map((entry, index) => ({
+      title: value.length === 1 ? title : `${title} ${index + 1}`,
+      rows: detailRows(entry)
+    })).filter((section) => section.rows.length > 0);
+  });
+}
 function renderObjectCard(result, primitives, title) {
   const scalarRows = directScalarRows(result);
   const nestedSections = directObjectSections(result);
-  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value)).map(([key2, value]) => ({ label: humanizeKey(key2), value: displayScalar(value) }));
+  const arrayObjectSections = directArrayObjectSections(result);
+  const listRows = Object.entries(result).filter(([, value]) => Array.isArray(value) && !isNonEmptyArrayOfObjects(value)).map(([key2, value]) => ({ label: humanizeKey(key2), value: displayScalar(value) }));
   return renderDetailCard({
     theme: primitives.getTheme(),
     title,
     sections: [
       { rows: scalarRows },
       ...nestedSections,
-      { title: "Lists", rows: listRows }
+      { title: "Lists", rows: listRows },
+      ...arrayObjectSections
     ]
   });
 }
@@ -13817,11 +14010,12 @@ var RESERVED_SERVICE_NAMES = /* @__PURE__ */ new Set([
   "fetch",
   "fs",
   "env",
+  "diagnostics",
   "progress",
   "runtimeOptions",
   "root"
 ]);
-var RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
+var RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 var NULL_OPTION_VALUE = /* @__PURE__ */ Symbol("toolcraft.cli.null");
 function inferProgramName(argv) {
   const entrypoint = argv[1];
@@ -13886,11 +14080,11 @@ function formatSegment(segment, casing) {
   const separator = casing === "snake" ? "_" : "-";
   return splitWords3(segment).join(separator);
 }
-function toOptionFlag(path25, casing) {
-  return `--${path25.map((segment) => formatSegment(segment, casing)).join(".")}`;
+function toOptionFlag(path26, casing) {
+  return `--${path26.map((segment) => formatSegment(segment, casing)).join(".")}`;
 }
-function toOptionAttribute(path25, casing) {
-  return path25.map((segment) => {
+function toOptionAttribute(path26, casing) {
+  return path26.map((segment) => {
     const formatted = formatSegment(segment, casing);
     if (casing === "snake") {
       return formatted;
@@ -13901,23 +14095,23 @@ function toOptionAttribute(path25, casing) {
     ).join("");
   }).join(".");
 }
-function toDisplayPath(path25) {
-  return path25.join(".");
+function toDisplayPath(path26) {
+  return path26.join(".");
 }
-function toUnionKindControlPath(path25) {
-  if (path25.length === 0) {
+function toUnionKindControlPath(path26) {
+  if (path26.length === 0) {
     return ["kind"];
   }
-  const head = path25.slice(0, -1);
-  const tail = path25[path25.length - 1] ?? "";
+  const head = path26.slice(0, -1);
+  const tail = path26[path26.length - 1] ?? "";
   return [...head, `${tail}Kind`];
 }
-function toUnionKindDisplayPath(path25) {
-  if (path25.length === 0) {
+function toUnionKindDisplayPath(path26) {
+  if (path26.length === 0) {
     return "kind";
   }
-  const head = path25.slice(0, -1);
-  const tail = path25[path25.length - 1] ?? "";
+  const head = path26.slice(0, -1);
+  const tail = path26[path26.length - 1] ?? "";
   return [...head, `${tail}-kind`].join(".");
 }
 function createSyntheticEnumSchema(values) {
@@ -13933,14 +14127,14 @@ function getRequiredBranchFingerprint(branch, casing) {
   const requiredKeys = Object.entries(branch.shape).filter(([, schema]) => schema.kind !== "optional").map(([key2]) => formatSegment(key2, casing)).sort();
   return requiredKeys.join("+");
 }
-function collectFields(schema, casing, globalLongOptionFlags, path25 = [], inheritedOptional = false, variantContext) {
+function collectFields(schema, casing, globalLongOptionFlags, path26 = [], inheritedOptional = false, variantContext) {
   const collected = {
     dynamicFields: [],
     fields: [],
     variants: []
   };
   for (const [key2, rawChildSchema] of Object.entries(schema.shape)) {
-    const nextPath = [...path25, key2];
+    const nextPath = [...path26, key2];
     const runtimeOptional = inheritedOptional || rawChildSchema.kind === "optional";
     const childSchema = unwrapOptional2(rawChildSchema);
     const requiredWhenActive = rawChildSchema.kind !== "optional" && childSchema.default === void 0;
@@ -14126,9 +14320,9 @@ function collectFields(schema, casing, globalLongOptionFlags, path25 = [], inher
   }
   return collected;
 }
-function toCommanderOptionAttribute(path25, casing, globalLongOptionFlags) {
-  const optionAttribute = toOptionAttribute(path25, casing);
-  const optionFlag = toOptionFlag(path25, casing);
+function toCommanderOptionAttribute(path26, casing, globalLongOptionFlags) {
+  const optionAttribute = toOptionAttribute(path26, casing);
+  const optionFlag = toOptionFlag(path26, casing);
   if (!globalLongOptionFlags.has(optionFlag)) {
     return optionAttribute;
   }
@@ -14458,6 +14652,7 @@ function createOption(field, globalLongOptionFlags) {
 function resolveCLIControls(controls) {
   return {
     debug: controls?.debug === true,
+    logLevel: controls?.logLevel === true,
     output: controls?.output === true,
     verbose: controls?.verbose === true,
     yes: controls?.yes === true
@@ -14477,6 +14672,9 @@ function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
   if (controls.debug) {
     flags.push("--debug");
   }
+  if (controls.logLevel) {
+    flags.push("--log-level");
+  }
   if (controls.verbose) {
     flags.push("--verbose");
   }
@@ -14520,6 +14718,9 @@ function createCommanderOption(flags, description, field) {
 function hasHelpFlag(argv) {
   return argv.some((token) => HELP_FLAGS.has(token));
 }
+function normalizeVerboseAlias(argv) {
+  return argv.map((token) => token === "-v" ? "--verbose" : token);
+}
 function resolveHelpOutput(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index] ?? "";
@@ -14567,7 +14768,7 @@ function findVisibleChild(group, token, scope) {
     (child) => child.name === token || child.aliases.includes(token)
   );
 }
-function resolveHelpTarget(root, argv, scope, rootDisplayName) {
+function resolveHelpTarget(root, argv, scope, rootUsageName, rootDisplayName) {
   const breadcrumb = [rootDisplayName ?? root.name];
   let current = root;
   for (const token of argv.slice(2)) {
@@ -14579,7 +14780,9 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
     }
     const child = findVisibleChild(current, token, scope);
     if (child === void 0) {
-      break;
+      throw new UserError(
+        formatUnknownHelpCommandMessage(current, token, scope, rootUsageName, breadcrumb)
+      );
     }
     breadcrumb.push(child.name);
     current = child;
@@ -14589,6 +14792,16 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
     node: current
   };
 }
+function formatUnknownHelpCommandMessage(group, input, scope, rootUsageName, breadcrumb) {
+  const suggestions = suggest(
+    input,
+    getHelpChildren(group, scope).map((child) => child.name)
+  );
+  const commandPath = breadcrumb.slice(1).join(" ");
+  const helpTarget = commandPath.length === 0 ? rootUsageName : `${rootUsageName} ${commandPath}`;
+  return `${formatSuggestionMessage(`Unknown command "${input}".`, suggestions)}
+Run ${helpTarget} --help for usage.`;
+}
 function formatHelpFieldFlags(field, globalLongOptionFlags) {
   if (field.positionalIndex !== void 0) {
     return formatPositionalToken(field);
@@ -14925,11 +15138,17 @@ function formatGlobalOptionsLine(ctx) {
   if (ctx.controls.output) {
     flags.push("--output <format>");
   }
+  if (ctx.controls.verbose) {
+    flags.push("-v, --verbose");
+  }
   if (ctx.showVersion) {
     flags.push("--version");
   }
   return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
 }
+function formatLeafGlobalOptionsLine(ctx) {
+  return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+}
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
   const seen = /* @__PURE__ */ new Map();
   const visit = (node) => {
@@ -15047,6 +15266,10 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     sections.push(`${text.sectionHeader("Options")}
 ${formatHelpOptionList(optionRows)}`);
   }
+  const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
+  if (builtInLine.length > 0) {
+    sections.push(builtInLine);
+  }
   const secretRows = formatSecretRows(command.secrets);
   if (secretRows.length > 0) {
     sections.push(
@@ -15071,6 +15294,91 @@ ${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`
     sections
   });
 }
+function renderJsonHelp(target, root, casing, globalOptions, rootUsageName) {
+  const globalLongOptionFlags = getGlobalLongOptionFlags(
+    globalOptions.presetsEnabled,
+    globalOptions.showVersion,
+    globalOptions.controls
+  );
+  const node = target.node;
+  if (node.kind === "group") {
+    const commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags);
+    const isRoot = node === root;
+    return `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        kind: "group",
+        name: target.breadcrumb.at(-1) ?? rootUsageName,
+        path: target.breadcrumb.filter((segment) => segment.length > 0),
+        usage: buildUsageLine(
+          target.breadcrumb,
+          rootUsageName,
+          formatGroupUsageSuffix(node, "cli", casing, globalLongOptionFlags)
+        ),
+        ...node.description === void 0 ? {} : { description: node.description },
+        commands: commandRows.map((row) => ({ name: row.name, description: row.description })),
+        options: isRoot ? collectSchemaGlobalFieldRows(node, "cli", casing, globalLongOptionFlags).map((row) => ({
+          name: row.flags.split(/[ ,]+/)[0]?.replace(/^--/, "") ?? row.flags,
+          flags: row.flags.split(", "),
+          type: "unknown",
+          description: row.description,
+          required: false
+        })) : []
+      },
+      null,
+      2
+    )}
+`;
+  }
+  const collected = collectFields(node.params, casing, globalLongOptionFlags);
+  const fields = assignPositionals(collected.fields, node.positional);
+  const positionalFields = fields.filter((field) => field.positionalIndex !== void 0);
+  const usageSuffix = positionalFields.length > 0 ? `[OPTIONS] ${positionalFields.map(formatPositionalToken).join(" ")}` : "[OPTIONS]";
+  return `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      kind: "command",
+      name: node.name,
+      path: target.breadcrumb.filter((segment) => segment.length > 0),
+      usage: buildUsageLine(target.breadcrumb, rootUsageName, usageSuffix),
+      ...node.description === void 0 ? {} : { description: node.description },
+      options: fields.filter((field) => field.global !== true).map((field) => formatJsonHelpOption(field, globalLongOptionFlags)),
+      secrets: Object.entries(node.secrets).map(([name, secret]) => ({
+        name,
+        env: secret.env,
+        required: secret.optional !== true,
+        ...secret.description === void 0 ? {} : { description: secret.description }
+      })),
+      examples: node.examples
+    },
+    null,
+    2
+  )}
+`;
+}
+function formatJsonHelpOption(field, globalLongOptionFlags) {
+  return {
+    name: field.displayPath,
+    flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
+    type: formatJsonHelpSchemaType(field.schema),
+    ...field.description === void 0 ? {} : { description: field.description },
+    required: field.requiredWhenActive,
+    ...field.hasDefault ? { default: field.defaultValue } : {},
+    ...field.positionalIndex === void 0 ? {} : { positional: true }
+  };
+}
+function formatJsonHelpSchemaType(schema) {
+  if (schema.kind === "enum") {
+    return "enum";
+  }
+  if (schema.kind === "array") {
+    return "array";
+  }
+  if (schema.kind === "json") {
+    return "json";
+  }
+  return schema.kind;
+}
 function renderHelpDocument(input) {
   const title = input.breadcrumb.filter((segment) => segment.length > 0).join(" ") || input.rootUsageName;
   const description = input.description ?? "";
@@ -15094,11 +15402,27 @@ function renderHelpDocument(input) {
 `;
 }
 async function renderGeneratedHelp(root, argv, options) {
-  const target = resolveHelpTarget(root, argv, "cli", options.rootDisplayName);
   const output = resolveHelpOutput(argv);
   const casing = options.casing ?? "kebab";
   const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
+  const target = resolveHelpTarget(root, argv, "cli", rootUsageName, options.rootDisplayName);
   const controls = resolveCLIControls(options.controls);
+  if (output === "json") {
+    process.stdout.write(
+      renderJsonHelp(
+        target,
+        root,
+        casing,
+        {
+          controls,
+          showVersion: options.version !== void 0,
+          presetsEnabled: options.presets === true
+        },
+        rootUsageName
+      )
+    );
+    return;
+  }
   await withOutputFormat2(output, async () => {
     const rendered = target.node.kind === "group" ? renderGroupHelp(
       target.node,
@@ -15218,9 +15542,11 @@ function addCommanderChild(parent, child, isDefault, siblingNames) {
       parent,
       "_toolcraftHiddenDefaultNames",
       getToolcraftHiddenDefaultNames(parent).concat([
-        ...new Set([Reflect.get(child, "_toolcraftOriginalName"), ...child.aliases()].filter(
-          (name) => typeof name === "string" && name.length > 0
-        ))
+        ...new Set(
+          [Reflect.get(child, "_toolcraftOriginalName"), ...child.aliases()].filter(
+            (name) => typeof name === "string" && name.length > 0
+          )
+        )
       ])
     );
     parent.addCommand(child, { hidden: true, isDefault: true });
@@ -15277,6 +15603,13 @@ function addGlobalOptions(command, presetsEnabled, controls) {
       new Option("--debug [mode]", "Print stack traces for unexpected errors.").preset("trim").argParser(parseDebugStackMode)
     );
   }
+  if (controls.logLevel) {
+    options.push(
+      new Option("--log-level <level>", "Set runtime diagnostic log level.").argParser(
+        parseLogLevel
+      )
+    );
+  }
   if (controls.verbose) {
     options.push(new Option("--verbose", "Print detailed runtime diagnostics."));
   }
@@ -15296,10 +15629,33 @@ function parseDebugStackMode(value) {
     formatInvalidEnumMessage("--debug", String(value), ["raw"], { candidates: ["raw"] })
   );
 }
-function setNestedValue(target, path25, value) {
+function parseLogLevel(value) {
+  if (isLogLevel(value)) {
+    return value;
+  }
+  throw new InvalidArgumentError(
+    formatInvalidEnumMessage("--log-level", value, [...LOG_LEVELS], {
+      candidates: ["warn", "debug", "trace"],
+      threshold: 3
+    })
+  );
+}
+function writeCLIDiagnosticEvent(event) {
+  const transcript = event.data?.transcript;
+  if (typeof transcript === "string") {
+    process.stderr.write(transcript);
+    return;
+  }
+  if (event.category === "progress" || event.level === "trace") {
+    return;
+  }
+  process.stderr.write(`${event.message}
+`);
+}
+function setNestedValue(target, path26, value) {
   let cursor2 = target;
-  for (let index = 0; index < path25.length - 1; index += 1) {
-    const segment = path25[index] ?? "";
+  for (let index = 0; index < path26.length - 1; index += 1) {
+    const segment = path26[index] ?? "";
     const existing = Object.prototype.hasOwnProperty.call(cursor2, segment) ? cursor2[segment] : void 0;
     if (typeof existing === "object" && existing !== null) {
       cursor2 = existing;
@@ -15314,7 +15670,7 @@ function setNestedValue(target, path25, value) {
     });
     cursor2 = next;
   }
-  const leaf = path25[path25.length - 1];
+  const leaf = path26[path26.length - 1];
   if (leaf !== void 0) {
     Object.defineProperty(cursor2, leaf, {
       value,
@@ -15462,21 +15818,21 @@ async function withOutputFormat2(output, fn) {
 }
 function createFs2() {
   return {
-    readFile: async (path25, encoding = "utf8") => readFile5(path25, { encoding }),
-    writeFile: async (path25, contents, options) => {
-      await writeFile5(path25, contents, options);
+    readFile: async (path26, encoding = "utf8") => readFile5(path26, { encoding }),
+    writeFile: async (path26, contents, options) => {
+      await writeFile5(path26, contents, options);
     },
-    exists: async (path25) => {
+    exists: async (path26) => {
       try {
-        await access2(path25);
+        await access2(path26);
         return true;
       } catch {
         return false;
       }
     },
-    lstat: async (path25) => lstat3(path25),
+    lstat: async (path26) => lstat3(path26),
     rename: async (fromPath, toPath) => rename3(fromPath, toPath),
-    unlink: async (path25) => unlink3(path25)
+    unlink: async (path26) => unlink3(path26)
   };
 }
 function createEnv2(values = process.env) {
@@ -15486,15 +15842,15 @@ function createEnv2(values = process.env) {
     }
   };
 }
-function isPlainObject4(value) {
+function isPlainObject5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function hasFieldValue(value) {
   return value !== void 0;
 }
-function hasNestedField(fields, path25) {
+function hasNestedField(fields, path26) {
   return fields.some(
-    (field) => path25.length < field.path.length && path25.every((segment, index) => field.path[index] === segment)
+    (field) => path26.length < field.path.length && path26.every((segment, index) => field.path[index] === segment)
   );
 }
 function describeExpectedPresetValue(schema) {
@@ -15618,14 +15974,14 @@ async function loadPresetValues(fields, presetPath) {
       { cause: error3 }
     );
   }
-  if (!isPlainObject4(parsedPreset)) {
+  if (!isPlainObject5(parsedPreset)) {
     throw new UserError(`Preset file "${presetPath}" must contain a JSON object.`);
   }
   const fieldByPath = new Map(fields.map((field) => [field.displayPath, field]));
   const presetValues = {};
-  function visitObject(current, path25) {
+  function visitObject(current, path26) {
     for (const [key2, value] of Object.entries(current)) {
-      const nextPath = [...path25, key2];
+      const nextPath = [...path26, key2];
       const displayPath = toDisplayPath(nextPath);
       const field = fieldByPath.get(displayPath);
       if (field !== void 0) {
@@ -15637,7 +15993,7 @@ async function loadPresetValues(fields, presetPath) {
           `Preset file "${presetPath}" contains unknown parameter "${displayPath}".`
         );
       }
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         throw new UserError(
           `Preset file "${presetPath}" has an invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
         );
@@ -15680,8 +16036,8 @@ function matchesFixtureValue(expected, actual) {
     }
     return expected.every((item, index) => matchesFixtureValue(item, actual[index]));
   }
-  if (isPlainObject4(expected)) {
-    if (!isPlainObject4(actual)) {
+  if (isPlainObject5(expected)) {
+    if (!isPlainObject5(actual)) {
       return false;
     }
     return Object.entries(expected).every(
@@ -15744,9 +16100,9 @@ function createFixtureFetch(entries) {
   };
 }
 function createFixtureFs(definition) {
-  const fsDefinition = isPlainObject4(definition) ? definition : {};
-  const readFileEntries = isPlainObject4(fsDefinition.readFile) ? fsDefinition.readFile : {};
-  const existsEntries = isPlainObject4(fsDefinition.exists) ? fsDefinition.exists : {};
+  const fsDefinition = isPlainObject5(definition) ? definition : {};
+  const readFileEntries = isPlainObject5(fsDefinition.readFile) ? fsDefinition.readFile : {};
+  const existsEntries = isPlainObject5(fsDefinition.exists) ? fsDefinition.exists : {};
   return {
     readFile: async (filePath) => {
       if (Object.prototype.hasOwnProperty.call(readFileEntries, filePath)) {
@@ -15769,10 +16125,10 @@ function createFixtureFs(definition) {
 function resolveFixtureMethodResult(methodName, definition, args) {
   if (Array.isArray(definition)) {
     for (const entry of definition) {
-      if (!isPlainObject4(entry)) {
+      if (!isPlainObject5(entry)) {
         continue;
       }
-      const explicitMatcher = isPlainObject4(entry.request) ? entry.request : void 0;
+      const explicitMatcher = isPlainObject5(entry.request) ? entry.request : void 0;
       const matcher = explicitMatcher ?? Object.fromEntries(
         Object.entries(entry).filter(
           ([key2]) => key2 !== "result" && key2 !== "response" && key2 !== "error"
@@ -15784,7 +16140,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
         matched = matchesFixtureValue(matcher.args, args);
       } else if (Object.keys(matcher).length === 0) {
         matched = true;
-      } else if (isPlainObject4(firstArg)) {
+      } else if (isPlainObject5(firstArg)) {
         matched = matchesFixtureValue(matcher, firstArg);
       } else if (args.length === 1 && Object.keys(matcher).length === 1) {
         const [[, expectedValue]] = Object.entries(matcher);
@@ -15805,7 +16161,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
       return Promise.resolve(null);
     }
   }
-  if (isPlainObject4(definition)) {
+  if (isPlainObject5(definition)) {
     const firstArg = args[0];
     if (typeof firstArg === "string" && Object.prototype.hasOwnProperty.call(definition, firstArg)) {
       return Promise.resolve(definition[firstArg]);
@@ -15817,7 +16173,7 @@ function resolveFixtureMethodResult(methodName, definition, args) {
   return Promise.resolve(null);
 }
 function createFixtureService(definition) {
-  const methods = isPlainObject4(definition) ? definition : {};
+  const methods = isPlainObject5(definition) ? definition : {};
   return new Proxy(
     {},
     {
@@ -15915,7 +16271,7 @@ async function resolveFixtureRuntime(command, services, requirementOptions, runt
     };
   }
   const scenario = await loadFixtureScenario(command, selector);
-  const scenarioServices = isPlainObject4(scenario.services) ? scenario.services : {};
+  const scenarioServices = isPlainObject5(scenario.services) ? scenario.services : {};
   const customServiceNames = /* @__PURE__ */ new Set([
     ...Object.keys(services),
     ...Object.keys(scenarioServices).filter((name) => !RESERVED_SERVICE_NAMES.has(name))
@@ -15975,6 +16331,19 @@ function renderCliErrorPattern(pattern) {
     process.exitCode = 1;
     return;
   }
+  if (pattern.kind === "definition") {
+    logger2.error(
+      `Command definition error: ${pattern.error.message}
+This is a bug in the generated command definition, not in your command arguments.
+Run with --debug for a stack trace.`
+    );
+    if (pattern.debugStackMode !== void 0 && pattern.error.stack) {
+      process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}
+`);
+    }
+    process.exitCode = 1;
+    return;
+  }
   if (pattern.kind === "toolcraft-bug") {
     logger2.error(
       `toolcraft hit an internal invariant: ${pattern.error.message}
@@ -16005,8 +16374,8 @@ function validateServices(services) {
     }
   }
 }
-function getNestedValue(target, path25) {
-  return path25.reduce(
+function getNestedValue(target, path26) {
+  return path26.reduce(
     (current, segment) => current !== null && typeof current === "object" ? current[segment] : void 0,
     target
   );
@@ -16241,7 +16610,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       if (itemSchema.kind !== "object") {
         return value;
       }
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected indexed object entries, got ${describeReceived(value)}.`
@@ -16276,7 +16645,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       );
     }
     case "object": {
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
@@ -16307,7 +16676,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors2) {
       return result;
     }
     case "record": {
-      if (!isPlainObject4(value)) {
+      if (!isPlainObject5(value)) {
         errors2.push({
           path: displayPath,
           message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
@@ -16637,7 +17006,7 @@ function getResolvedFlags(command) {
   const flags = command.optsWithGlobals();
   return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, onErrorReportContext) {
+async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, diagnosticsOptions, onErrorReportContext) {
   const logger2 = createLogger();
   const primitives = {
     logger: logger2,
@@ -16648,6 +17017,10 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
   const optionValues = state.actionCommand.optsWithGlobals();
   const resolvedFlags = optionValues;
   const output = resolveOutput(resolvedFlags);
+  const diagnostics = createRuntimeLogger({
+    level: resolvedFlags.logLevel ?? (diagnosticsOptions.verboseControlEnabled && resolvedFlags.verbose ? "trace" : diagnosticsOptions.logLevel),
+    logger: diagnosticsOptions.logger ?? writeCLIDiagnosticEvent
+  });
   const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
   const runtime = await resolveFixtureRuntime(
     state.command,
@@ -16661,7 +17034,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
     fetch: runtime.fetch,
     fs: runtime.fs,
     env: runtime.env,
+    diagnostics,
     progress(message2) {
+      diagnostics.emit({ level: "info", message: message2, category: "progress" });
       logger2.info(message2);
     }
   };
@@ -16738,18 +17113,18 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
   }
 }
 function isStringRecord(value) {
-  return isPlainObject4(value) && Object.values(value).every((entry) => typeof entry === "string");
+  return isPlainObject5(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
 function isHttpErrorLike(error3) {
-  if (!isPlainObject4(error3)) {
+  if (!isPlainObject5(error3)) {
     return false;
   }
-  if (error3.name !== "HttpError" || typeof error3.message !== "string") {
+  if (typeof error3.name !== "string" || typeof error3.message !== "string") {
     return false;
   }
   const request = error3.request;
   const response = error3.response;
-  return isPlainObject4(request) && typeof request.method === "string" && typeof request.url === "string" && isStringRecord(request.headers) && isPlainObject4(response) && typeof response.status === "number" && typeof response.statusText === "string" && isStringRecord(response.headers) && hasOwnProperty3(response, "body");
+  return isPlainObject5(request) && typeof request.method === "string" && typeof request.url === "string" && isStringRecord(request.headers) && isPlainObject5(response) && typeof response.status === "number" && typeof response.statusText === "string" && isStringRecord(response.headers) && hasOwnProperty3(response, "body");
 }
 function hasTypedOptionalField(value, field, type2) {
   return !hasOwnProperty3(value, field) || typeof value[field] === type2;
@@ -16758,7 +17133,7 @@ function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
 function isProblemDetailsLike(body) {
-  if (!isPlainObject4(body)) {
+  if (!isPlainObject5(body)) {
     return false;
   }
   if (!hasTypedOptionalField(body, "type", "string")) {
@@ -16779,11 +17154,11 @@ function isProblemDetailsLike(body) {
   return hasOwnNonEmptyString(body, "title") || hasOwnNonEmptyString(body, "detail");
 }
 function isGraphQLErrorEnvelopeLike(body) {
-  if (!isPlainObject4(body) || !Array.isArray(body.errors) || body.errors.length === 0) {
+  if (!isPlainObject5(body) || !Array.isArray(body.errors) || body.errors.length === 0) {
     return false;
   }
   return body.errors.every((error3) => {
-    if (!isPlainObject4(error3) || typeof error3.message !== "string") {
+    if (!isPlainObject5(error3) || typeof error3.message !== "string") {
       return false;
     }
     if (hasOwnProperty3(error3, "path")) {
@@ -16793,7 +17168,7 @@ function isGraphQLErrorEnvelopeLike(body) {
       }
     }
     if (hasOwnProperty3(error3, "extensions")) {
-      if (!isPlainObject4(error3.extensions)) {
+      if (!isPlainObject5(error3.extensions)) {
         return false;
       }
       if (hasOwnProperty3(error3.extensions, "code") && typeof error3.extensions.code !== "string") {
@@ -16876,6 +17251,7 @@ function formatHttpErrorSnippet(body) {
 }
 function renderHttpError(error3, options) {
   const detailed = options.verbose || options.debugStackMode !== void 0;
+  const summary = summarizeHttpError(error3);
   const lines = [
     styleHttpErrorLine(`Request:  ${error3.request.method} ${error3.request.url}`, text.muted)
   ];
@@ -16902,11 +17278,27 @@ function renderHttpError(error3, options) {
       indentHttpErrorBlock(formatHttpErrorBody(error3.response.body))
     );
   } else {
-    lines.push(
-      "",
-      `Response body: ${formatHttpErrorSnippet(error3.response.body)}`,
-      "Re-run with --verbose to see headers and full body."
-    );
+    const summaryLines = [
+      summary.code === void 0 ? void 0 : `Code:     ${summary.code}`,
+      summary.message === void 0 ? void 0 : `Message:  ${summary.message}`,
+      summary.requestId === void 0 ? void 0 : `Request id: ${summary.requestId}`,
+      summary.retryAfter === void 0 ? void 0 : `Retry after: ${summary.retryAfter}`,
+      summary.hint === void 0 ? void 0 : `Hint:     ${summary.hint}`
+    ].filter((line) => line !== void 0);
+    if (summary.fieldErrors !== void 0 && summary.fieldErrors.length > 0) {
+      summaryLines.push(
+        "",
+        "Field errors:",
+        ...summary.fieldErrors.map((fieldError) => `  ${fieldError.path}: ${fieldError.message}`)
+      );
+    }
+    lines.push("");
+    if (summaryLines.length > 0) {
+      lines.push(...summaryLines);
+    } else {
+      lines.push(`Response body: ${formatHttpErrorSnippet(error3.response.body)}`);
+    }
+    lines.push("Re-run with --verbose to see headers and full body.");
   }
   process.stderr.write(`${lines.join("\n")}
 `);
@@ -16921,7 +17313,11 @@ async function handleRunError(error3, options) {
   await withOutputFormat2(options.output, async () => {
     if (error3 instanceof UserError) {
       renderCliErrorPattern(
-        options.userErrorPattern === "usage" ? {
+        options.userErrorPattern === "definition" ? {
+          kind: "definition",
+          error: error3,
+          debugStackMode: options.debugStackMode
+        } : options.userErrorPattern === "usage" ? {
           kind: "usage",
           message: error3.message,
           rootUsageName: options.rootUsageName,
@@ -17159,13 +17555,23 @@ function findUnknownCommanderCommand(program, argv) {
         commandPath: pathSegments.join(" ")
       };
     }
-    if (current.commands.length === 0 || getDefaultCommanderCommandName(current) !== void 0) {
+    if (current.commands.length === 0) {
       return void 0;
     }
     const child = current.commands.find(
       (command) => command.name() === token || command.aliases().includes(token)
     );
     if (child === void 0) {
+      if (getDefaultCommanderCommandName(current) !== void 0) {
+        if (shouldRejectDefaultCommandToken(current, token, pathSegments)) {
+          return {
+            input: token,
+            currentCommand: current,
+            commandPath: pathSegments.join(" ")
+          };
+        }
+        return void 0;
+      }
       return {
         input: token,
         currentCommand: current,
@@ -17177,6 +17583,36 @@ function findUnknownCommanderCommand(program, argv) {
   }
   return void 0;
 }
+function shouldRejectDefaultCommandToken(command, token, pathSegments) {
+  return pathSegments.length === 0 && isBareCommandLikeToken(token) && hasNonDefaultPublicChildCommand(command);
+}
+function hasNonDefaultPublicChildCommand(command) {
+  const defaultName = getDefaultCommanderCommandName(command);
+  return command.commands.some(
+    (child) => child.name() !== defaultName && !isToolcraftHiddenCommander(child) && !getToolcraftReservedChildNames(command).includes(child.name())
+  );
+}
+function isBareCommandLikeToken(token) {
+  if (token.length === 0) {
+    return false;
+  }
+  for (const character of token) {
+    if (!isCommandNameCharacter(character)) {
+      return false;
+    }
+  }
+  return true;
+}
+function isCommandNameCharacter(character) {
+  const code = character.codePointAt(0);
+  if (code === void 0) {
+    return false;
+  }
+  const isLowercaseLetter = code >= 97 && code <= 122;
+  const isUppercaseLetter = code >= 65 && code <= 90;
+  const isDigit = code >= 48 && code <= 57;
+  return isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_";
+}
 function getDefaultCommanderCommandName(command) {
   const candidate = command;
   return typeof candidate._defaultCommandName === "string" ? candidate._defaultCommandName : void 0;
@@ -17195,101 +17631,116 @@ function configureCommanderSuggestionOutput(command) {
 }
 async function runCLI(roots, options = {}) {
   enableSourceMaps();
-  const argv = [...options.argv ?? process.argv];
-  const normalizedRoot = normalizeRoots(roots, argv);
-  const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
-  await resolveMcpProxies(root, { projectRoot: options.projectRoot });
-  const casing = options.casing ?? "kebab";
-  const services = options.services ?? {};
-  const runtimeOptions = options.humanInLoop ?? {};
-  const runtimeFetch = options.fetch ?? globalThis.fetch;
-  const version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
-  const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
   const controls = resolveCLIControls(options.controls);
-  const servicesWithBuiltIns = {
-    ...services,
-    runtimeOptions,
-    root
-  };
-  const requirementOptions = {
-    apiVersion: options.apiVersion
-  };
-  validateServices(services);
-  if (hasHelpFlag(argv)) {
-    await renderGeneratedHelp(root, argv, { ...options, version });
-    return;
-  }
-  const program = new CommanderCommand();
-  program.name(root.name);
-  program.exitOverride();
-  program.showHelpAfterError();
-  program.addHelpCommand(false);
-  const presetsEnabled = options.presets === true;
-  const globalLongOptionFlags = getGlobalLongOptionFlags(
-    presetsEnabled,
-    version !== void 0,
-    controls
-  );
-  addGlobalOptions(program, presetsEnabled, controls);
-  if (version !== void 0) {
-    program.version(version, "--version");
-  }
-  Reflect.set(
-    program,
-    "_toolcraftReservedChildNames",
-    root.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child))
-  );
+  const argv = controls.verbose ? normalizeVerboseAlias([...options.argv ?? process.argv]) : [...options.argv ?? process.argv];
+  const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
   let lastActionCommand;
   let resolvedCommandPath = "";
+  let program;
+  let version;
+  let userErrorPattern = "definition";
   let errorReportContext;
-  const execute = async (state) => {
-    lastActionCommand = state.actionCommand;
-    resolvedCommandPath = formatCliCommandPath(state.commandPath);
-    await executeCommand(
-      state,
-      servicesWithBuiltIns,
-      requirementOptions,
-      runtimeFetch,
+  try {
+    const normalizedRoot = normalizeRoots(roots, argv);
+    const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
+    const casing = options.casing ?? "kebab";
+    const services = options.services ?? {};
+    const runtimeOptions = options.humanInLoop ?? {};
+    const runtimeFetch = options.fetch ?? globalThis.fetch;
+    version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
+    const servicesWithBuiltIns = {
+      ...services,
       runtimeOptions,
-      (context) => {
-        errorReportContext = context;
-      }
-    );
-  };
-  const rootChildNames = new Set(
-    root.children.filter((candidate) => isNodeVisibleInScope(candidate, "cli")).map((candidate) => candidate.name)
-  );
-  for (const child of root.children) {
-    const command = createNodeCommand(
-      child,
-      casing,
-      globalLongOptionFlags,
-      execute,
+      root
+    };
+    const requirementOptions = {
+      apiVersion: options.apiVersion
+    };
+    validateServices(services);
+    if (hasHelpFlag(argv)) {
+      userErrorPattern = "usage";
+      await renderGeneratedHelp(root, argv, { ...options, version });
+      return;
+    }
+    if (argv.length <= 2 && root.default?.scope.includes("cli") !== true) {
+      userErrorPattern = "usage";
+      await renderGeneratedHelp(root, argv, { ...options, version });
+      return;
+    }
+    program = new CommanderCommand();
+    program.name(root.name);
+    program.exitOverride();
+    program.showHelpAfterError();
+    program.addHelpCommand(false);
+    const presetsEnabled = options.presets === true;
+    const globalLongOptionFlags = getGlobalLongOptionFlags(
       presetsEnabled,
+      version !== void 0,
       controls
     );
-    if (command === null) {
-      continue;
+    addGlobalOptions(program, presetsEnabled, controls);
+    if (version !== void 0) {
+      program.version(version, "--version");
     }
-    const isDefaultChild = root.default !== void 0 && root.default.scope.includes("cli") && (command.name() === root.default.name || command.aliases().includes(root.default.name));
-    addCommanderChild(program, command, isDefaultChild, rootChildNames);
-  }
-  configureCommanderSuggestionOutput(program);
-  const unknownCommand = findUnknownCommanderCommand(program, argv);
-  if (unknownCommand !== void 0) {
-    createLogger().error(
-      appendUsagePointer(
-        formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand),
+    Reflect.set(
+      program,
+      "_toolcraftReservedChildNames",
+      root.children.filter((child) => !isNodeVisibleInScope(child, "cli")).flatMap((child) => getNodeCommandNames(child))
+    );
+    const execute = async (state) => {
+      lastActionCommand = state.actionCommand;
+      resolvedCommandPath = formatCliCommandPath(state.commandPath);
+      await executeCommand(
+        state,
+        servicesWithBuiltIns,
+        requirementOptions,
+        runtimeFetch,
+        runtimeOptions,
         {
-          rootUsageName,
-          commandPath: unknownCommand.commandPath
+          logLevel: options.logLevel,
+          logger: options.logger,
+          verboseControlEnabled: controls.verbose
+        },
+        (context) => {
+          errorReportContext = context;
         }
-      )
+      );
+    };
+    const rootChildNames = new Set(
+      root.children.filter((candidate) => isNodeVisibleInScope(candidate, "cli")).map((candidate) => candidate.name)
     );
-    process.exitCode = 1;
-    return;
-  }
-  try {
+    for (const child of root.children) {
+      const command = createNodeCommand(
+        child,
+        casing,
+        globalLongOptionFlags,
+        execute,
+        presetsEnabled,
+        controls
+      );
+      if (command === null) {
+        continue;
+      }
+      const isDefaultChild = root.default !== void 0 && root.default.scope.includes("cli") && (command.name() === root.default.name || command.aliases().includes(root.default.name));
+      addCommanderChild(program, command, isDefaultChild, rootChildNames);
+    }
+    configureCommanderSuggestionOutput(program);
+    const unknownCommand = findUnknownCommanderCommand(program, argv);
+    if (unknownCommand !== void 0) {
+      createLogger().error(
+        appendUsagePointer(
+          formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand),
+          {
+            rootUsageName,
+            commandPath: unknownCommand.commandPath
+          }
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
+    userErrorPattern = "usage";
     await program.parseAsync(argv);
   } catch (error3) {
     if (error3 instanceof ApprovalDeclinedError) {
@@ -17321,7 +17772,7 @@ async function runCLI(roots, options = {}) {
       argv,
       rootUsageName,
       commandPath: resolvedCommandPath,
-      userErrorPattern: errorReportContext?.params === void 0 ? "usage" : "runtime-user"
+      userErrorPattern: errorReportContext?.params === void 0 ? userErrorPattern : "runtime-user"
     });
   }
 }
@@ -19445,22 +19896,22 @@ function prune(obj, shape) {
   }
   return { changed, result };
 }
-function modifyAtPath(content, path25, value) {
+function modifyAtPath(content, path26, value) {
   const indent = detectIndent(content);
   const formattingOptions = {
     tabSize: indent === "	" ? 1 : indent.length,
     insertSpaces: indent !== "	",
     eol: "\n"
   };
-  const edits = jsonc.modify(content, path25, value, { formattingOptions });
+  const edits = jsonc.modify(content, path26, value, { formattingOptions });
   let result = jsonc.applyEdits(content, edits);
   if (!result.endsWith("\n")) {
     result += "\n";
   }
   return result;
 }
-function removeAtPath(content, path25) {
-  return modifyAtPath(content, path25, void 0);
+function removeAtPath(content, path26) {
+  return modifyAtPath(content, path26, void 0);
 }
 function serializeUpdate(content, current, next) {
   let result = content || "{}";
@@ -19470,15 +19921,15 @@ function serializeUpdate(content, current, next) {
   }
   return result;
 }
-function applyObjectUpdate(content, path25, current, next) {
+function applyObjectUpdate(content, path26, current, next) {
   let result = content;
   for (const key2 of Object.keys(current)) {
     if (!hasConfigEntry(next, key2)) {
-      result = removeAtPath(result, [...path25, key2]);
+      result = removeAtPath(result, [...path26, key2]);
     }
   }
   for (const [key2, nextValue] of Object.entries(next)) {
-    const nextPath = [...path25, key2];
+    const nextPath = [...path26, key2];
     const hasCurrent = hasConfigEntry(current, key2);
     const currentValue = hasCurrent ? current[key2] : void 0;
     if (hasCurrent && isConfigObject(currentValue) && isConfigObject(nextValue)) {
@@ -19678,16 +20129,16 @@ function getConfigFormat(pathOrFormat) {
   }
   return formatRegistry[formatName];
 }
-function detectFormat(path25) {
-  const ext = getExtension(path25);
+function detectFormat(path26) {
+  const ext = getExtension(path26);
   return extensionMap[ext];
 }
-function getExtension(path25) {
-  const lastDot = path25.lastIndexOf(".");
+function getExtension(path26) {
+  const lastDot = path26.lastIndexOf(".");
   if (lastDot === -1) {
     return "";
   }
-  return path25.slice(lastDot).toLowerCase();
+  return path26.slice(lastDot).toLowerCase();
 }
 
 // ../config-mutations/src/execution/path-utils.ts
@@ -22305,6 +22756,394 @@ function createTerminalPilotGroup() {
 }
 var terminalPilotGroup = Object.freeze(createTerminalPilotGroup());
 
+// src/commands/daemon-runtime.ts
+import { spawn as spawn7 } from "node:child_process";
+import { createHash as createHash5 } from "node:crypto";
+import { mkdir as mkdir3, unlink as unlink4 } from "node:fs/promises";
+import net from "node:net";
+import os4 from "node:os";
+import path24 from "node:path";
+var RUNTIME_DIR_ENV = "TERMINAL_PILOT_RUNTIME_DIR";
+var DAEMON_ARG = "__daemon";
+var START_TIMEOUT_MS = 5e3;
+var IDLE_SHUTDOWN_MS = 1e3;
+function isTerminalPilotDaemonArgv(argv) {
+  return argv[2] === DAEMON_ARG;
+}
+async function runTerminalPilotDaemon() {
+  const runtime = createTerminalPilotRuntime();
+  const socketPath = resolveSocketPath(process.env);
+  await mkdir3(path24.dirname(socketPath), { recursive: true });
+  if (process.platform !== "win32") {
+    await unlink4(socketPath).catch(() => void 0);
+  }
+  let idleTimer;
+  const server = net.createServer((socket) => {
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      while (true) {
+        const newlineIndex = buffer.indexOf("\n");
+        if (newlineIndex < 0) {
+          break;
+        }
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        void handleRequestLine(runtime, line).then((response) => {
+          socket.write(`${JSON.stringify(response)}
+`);
+          scheduleIdleShutdown();
+        });
+      }
+    });
+  });
+  async function shutdown() {
+    if (idleTimer !== void 0) {
+      clearTimeout(idleTimer);
+      idleTimer = void 0;
+    }
+    await runtime.close();
+    await new Promise((resolve) => {
+      server.close(() => resolve());
+    });
+    if (process.platform !== "win32") {
+      await unlink4(socketPath).catch(() => void 0);
+    }
+  }
+  async function scheduleIdleShutdown() {
+    if (idleTimer !== void 0) {
+      clearTimeout(idleTimer);
+      idleTimer = void 0;
+    }
+    const sessions = await runtime.listSessions();
+    if (sessions.length > 0) {
+      return;
+    }
+    idleTimer = setTimeout(() => {
+      void shutdown().then(() => {
+        process.exit(0);
+      });
+    }, IDLE_SHUTDOWN_MS);
+  }
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+function createDaemonTerminalPilotRuntime() {
+  let nextId = 1;
+  async function request(method, params17) {
+    await ensureDaemon();
+    return sendRequest(method, params17, nextId++);
+  }
+  function proxySession(name, info2) {
+    return {
+      id: info2.id,
+      command: info2.command,
+      pid: info2.pid,
+      exitCode: info2.exitCode,
+      fill: async (text4) => {
+        await request("sessionAction", { name, action: "fill", args: [text4] });
+      },
+      type: async (text4) => {
+        await request("sessionAction", { name, action: "type", args: [text4] });
+      },
+      press: async (key2) => {
+        await request("sessionAction", { name, action: "press", args: [key2] });
+      },
+      signal: async (signal) => {
+        await request("sessionAction", { name, action: "signal", args: [signal] });
+      },
+      waitFor: async (pattern, options) => request("sessionAction", {
+        name,
+        action: "waitFor",
+        args: [serializePattern(pattern), options]
+      }),
+      waitForExit: async (options) => request("sessionAction", { name, action: "waitForExit", args: [options] }),
+      screen: async () => request("sessionAction", { name, action: "screen", args: [] }),
+      history: async (options) => request("sessionAction", { name, action: "history", args: [options] }),
+      resize: async (cols, rows) => {
+        await request("sessionAction", { name, action: "resize", args: [cols, rows] });
+      },
+      close: async () => {
+        const result = await request("closeSession", { name });
+        return result.exitCode;
+      }
+    };
+  }
+  return {
+    async createSession(params17, env) {
+      const result = await request("createSession", {
+        params: params17,
+        envSession: env?.get(SESSION_ENV_VAR)
+      });
+      return { name: result.name, session: proxySession(result.name, result.session) };
+    },
+    async resolveSession(name, env) {
+      const result = await request("resolveSession", {
+        name,
+        envSession: env?.get(SESSION_ENV_VAR)
+      });
+      return { name: result.name, session: proxySession(result.name, result.session) };
+    },
+    async closeSession(name, env) {
+      return request("closeSession", {
+        name,
+        envSession: env?.get(SESSION_ENV_VAR)
+      });
+    },
+    async listSessions() {
+      const sessions = await request("listSessions");
+      return sessions.map((entry) => ({
+        name: entry.name,
+        session: proxySession(entry.name, entry.session)
+      }));
+    },
+    async close() {
+      await request("shutdown").catch(() => void 0);
+    }
+  };
+}
+async function handleRequestLine(runtime, line) {
+  let request;
+  try {
+    request = JSON.parse(line);
+  } catch (error3) {
+    return {
+      id: 0,
+      ok: false,
+      error: { message: error3 instanceof Error ? error3.message : "Invalid request" }
+    };
+  }
+  try {
+    const result = await handleRequest(runtime, request);
+    return { id: request.id, ok: true, result };
+  } catch (error3) {
+    return {
+      id: request.id,
+      ok: false,
+      error: { message: error3 instanceof Error ? error3.message : String(error3) }
+    };
+  }
+}
+async function handleRequest(runtime, request) {
+  const params17 = isRecord6(request.params) ? request.params : {};
+  if (request.method === "ping") {
+    return { ok: true };
+  }
+  if (request.method === "createSession") {
+    const createParams = isRecord6(params17.params) ? params17.params : {};
+    const namedSession = await runtime.createSession(
+      createParams,
+      envFromValue(params17.envSession)
+    );
+    return formatNamedSession(namedSession);
+  }
+  if (request.method === "resolveSession") {
+    const namedSession = await runtime.resolveSession(
+      optionalString2(params17.name),
+      envFromValue(params17.envSession)
+    );
+    return formatNamedSession(namedSession);
+  }
+  if (request.method === "listSessions") {
+    const sessions = await runtime.listSessions();
+    return sessions.map(formatNamedSession);
+  }
+  if (request.method === "closeSession") {
+    return runtime.closeSession(optionalString2(params17.name), envFromValue(params17.envSession));
+  }
+  if (request.method === "sessionAction") {
+    return runSessionAction(runtime, params17);
+  }
+  if (request.method === "shutdown") {
+    await runtime.close();
+    process.exit(0);
+  }
+  throw new UserError(`Unknown terminal-pilot daemon method: ${request.method}`);
+}
+async function runSessionAction(runtime, params17) {
+  const name = optionalString2(params17.name);
+  const action = optionalString2(params17.action);
+  const args = Array.isArray(params17.args) ? params17.args : [];
+  const namedSession = await runtime.resolveSession(name);
+  const session = namedSession.session;
+  if (action === "fill") {
+    await session.fill(String(args[0] ?? ""));
+    return void 0;
+  }
+  if (action === "type") {
+    await session.type(String(args[0] ?? ""));
+    return void 0;
+  }
+  if (action === "press") {
+    await session.press(String(args[0] ?? ""));
+    return void 0;
+  }
+  if (action === "signal") {
+    await session.signal(String(args[0] ?? ""));
+    return void 0;
+  }
+  if (action === "waitFor") {
+    return session.waitFor(deserializePattern(args[0]), optionalRecord(args[1]));
+  }
+  if (action === "waitForExit") {
+    return session.waitForExit(optionalRecord(args[0]));
+  }
+  if (action === "screen") {
+    const screen = await session.screen();
+    return {
+      lines: [...screen.lines],
+      rawLines: [...screen.rawLines],
+      cursor: { ...screen.cursor },
+      size: { ...screen.size }
+    };
+  }
+  if (action === "history") {
+    return session.history(optionalRecord(args[0]));
+  }
+  if (action === "resize") {
+    await session.resize(Number(args[0]), Number(args[1]));
+    return void 0;
+  }
+  throw new UserError(`Unknown terminal-pilot session action: ${action ?? "<missing>"}`);
+}
+async function ensureDaemon() {
+  try {
+    await sendRequest("ping", void 0, 0, { start: false });
+    return;
+  } catch {
+  }
+  const socketPath = resolveSocketPath(process.env);
+  await mkdir3(path24.dirname(socketPath), { recursive: true });
+  if (process.platform !== "win32") {
+    await unlink4(socketPath).catch(() => void 0);
+  }
+  const entryPoint = process.argv[1];
+  if (typeof entryPoint !== "string" || entryPoint.length === 0) {
+    throw new UserError("Cannot start terminal-pilot daemon: entrypoint is unknown.");
+  }
+  const child = spawn7(process.execPath, [...process.execArgv, entryPoint, DAEMON_ARG], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env
+  });
+  child.unref();
+  const startedAt = Date.now();
+  while (Date.now() - startedAt <= START_TIMEOUT_MS) {
+    try {
+      await sendRequest("ping", void 0, 0, { start: false });
+      return;
+    } catch {
+      await sleep2(50);
+    }
+  }
+  throw new UserError("Timed out waiting for terminal-pilot daemon to start.");
+}
+function sendRequest(method, params17, id, options = {}) {
+  const socketPath = resolveSocketPath(process.env);
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let buffer = "";
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      const request = { id, method, params: params17 };
+      socket.write(`${JSON.stringify(request)}
+`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk;
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) {
+        return;
+      }
+      const line = buffer.slice(0, newlineIndex);
+      socket.end();
+      try {
+        const response = JSON.parse(line);
+        if (response.ok) {
+          resolve(response.result);
+        } else {
+          reject(new UserError(response.error.message));
+        }
+      } catch (error3) {
+        reject(error3);
+      }
+    });
+    socket.on("error", (error3) => {
+      if (options.start === false) {
+        reject(error3);
+        return;
+      }
+      reject(new UserError(error3.message));
+    });
+  });
+}
+function resolveSocketPath(env) {
+  const runtimeDir = env[RUNTIME_DIR_ENV] ?? path24.join(os4.tmpdir(), `terminal-pilot-${process.getuid?.() ?? "user"}`);
+  if (process.platform === "win32") {
+    const hash = createHash5("sha256").update(runtimeDir).digest("hex").slice(0, 16);
+    return `\\\\.\\pipe\\terminal-pilot-${hash}`;
+  }
+  return path24.join(runtimeDir, "daemon.sock");
+}
+function formatNamedSession(namedSession) {
+  return {
+    name: namedSession.name,
+    session: formatSession(namedSession.session)
+  };
+}
+function formatSession(session) {
+  return {
+    id: session.id,
+    command: session.command,
+    pid: session.pid,
+    exitCode: session.exitCode
+  };
+}
+function envFromValue(value) {
+  const sessionName = optionalString2(value);
+  if (sessionName === void 0) {
+    return void 0;
+  }
+  return {
+    get(key2) {
+      return key2 === SESSION_ENV_VAR ? sessionName : void 0;
+    }
+  };
+}
+function serializePattern(pattern) {
+  if (typeof pattern === "string") {
+    return { kind: "literal", value: pattern };
+  }
+  return { kind: "regex", source: pattern.source, flags: pattern.flags };
+}
+function deserializePattern(value) {
+  if (!isRecord6(value)) {
+    return String(value ?? "");
+  }
+  if (value.kind === "regex") {
+    return new RegExp(String(value.source ?? ""), String(value.flags ?? ""));
+  }
+  return String(value.value ?? "");
+}
+function optionalRecord(value) {
+  return isRecord6(value) ? value : void 0;
+}
+function optionalString2(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/cli.ts
 configureTheme({ brand: "green", label: "Terminal Pilot" });
 function normalizeArgv(argv) {
@@ -22313,11 +23152,18 @@ function normalizeArgv(argv) {
   }
   return argv;
 }
-async function main(argv = process.argv) {
+async function main(argv = process.argv, options = {}) {
+  if (isTerminalPilotDaemonArgv(argv)) {
+    await runTerminalPilotDaemon();
+    return;
+  }
   const originalArgv = process.argv;
   process.argv = normalizeArgv(argv);
   try {
     await runCLI(createTerminalPilotGroup(), {
+      services: {
+        terminalPilotRuntime: options.terminalPilotRuntime ?? createDaemonTerminalPilotRuntime()
+      },
       controls: {
         debug: true,
         output: true,
@@ -22337,7 +23183,7 @@ async function isDirectExecution(argv) {
   try {
     const modulePath = fileURLToPath5(import.meta.url);
     const [resolvedEntryPoint, resolvedModulePath] = await Promise.all([
-      realpath3(path24.resolve(entryPoint)),
+      realpath3(path25.resolve(entryPoint)),
       realpath3(modulePath)
     ]);
     return resolvedEntryPoint === resolvedModulePath;