stitchkit 0.113.1 → 0.113.3

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

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

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

@@ -12,7 +12,7 @@
  * still parsing a success.
  */
 import type { ErrorHintFn } from '../execute-hooks.js';
-import type { ToolResult } from '../execute-result.js';
+import type { ToolFailure, ToolResult } from '../execute-result.js';
 /** Map a `ToolResult.code` to a process exit code. */
 export type ExitCodeMap = Record<string, number>;
 /**
@@ -47,4 +47,8 @@ export interface EmitOptions {
  */
 export declare function cliExitCode(result: ToolResult, exitCodes?: ExitCodeMap): number;
 export declare function emitResult(result: ToolResult, writers: CliWriters, opts: EmitOptions): number;
+/** A presentation failure cannot erase a successfully completed operation. */
+export declare function emitPresentationFailure(result: Extract<ToolResult, {
+    ok: true;
+}>, failure: ToolFailure, writers: CliWriters, opts: EmitOptions): number;
 //# sourceMappingURL=format.d.ts.map

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/tools/cli/run-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA+Df"}
+{"version":3,"file":"run-native.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/run-native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,EACL,KAAK,oBAAoB,EAG1B,MAAM,WAAW,CAAC;AAInB,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAkB,MAAM,WAAW,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EACL,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,QAAQ,SAAS,SAAS,EAE1B,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAC9C,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAyEf"}

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

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

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

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

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

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

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

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

package/llms/cli.2.txt

@@ -11,6 +11,287 @@ Parts of this slice:
 # Guide: CLI  (docs/guide/cli.md)  (continued)
 ==============================================================================
 
+## Distribution and self-update
+
+`createCli` ships no executable, and that is right — but the step after the
+executable is not application logic either. It is the same problem for every
+consumer, with the same three traps:
+
+1. **The installer cannot parse the manifest.** A `curl … | sh` runs on a
+   machine where nothing is installed yet, including `jq`. So the installer is
+   generated *from* the manifest, server-side, with the URL and digest already
+   substituted — it parses no JSON at all.
+2. **Replacing a running binary is a rename, not a write.** Anything else can
+   leave a half-written executable on someone's PATH when the connection drops.
+3. **The digest covers the decompressed bytes** — the file that will actually be
+   executed, not the archive that was transferred.
+
+The framework owns the manifest shape, the installer generation and the update
+primitive. The application owns where the assets live, which platforms it
+publishes and who may download them.
+
+```ts
+import {
+  CliBuildManifestSchema, assertCliPublishable, renderCliInstaller,
+  selectCliBuildAsset, checkCliUpdate, applyCliUpdate,
+} from 'stitchkit/cli'
+
+// Publishing: refuse to republish one version from a different commit —
+// otherwise everyone who already installed it never receives the fix.
+assertCliPublishable(previous, next)
+
+// Serving: omit `asset` and one script covers every published target, selecting
+// by uname at run time — otherwise that dispatch is the last hand-written piece
+// of the install path, and every publisher writes the same x86_64 → x64 table.
+renderCliInstaller({ manifest, binaryName: 'myapp' })
+// Or pin one target explicitly:
+renderCliInstaller({ manifest, asset: selectCliBuildAsset(manifest, target), binaryName: 'myapp' })
+
+// Checking: bounded, at most once per interval, silent on any failure.
+const check = await checkCliUpdate({ manifestUrl, currentVersion, lastCheckedAt })
+if (check.status === 'outdated' && check.asset) {
+  // Replacing is always an explicit command, never a side effect of a check.
+  await applyCliUpdate({ asset: check.asset })
+}
+```
+
+`checkCliUpdate` has **four** answers, not three: `skipped`, `current`,
+`outdated` and `unknown`. "Could not ask" is not "up to date" — collapsing them
+is how a tool goes quiet about its own staleness for months. It never throws,
+and a command still exits with the code it earned.
+
+Carry the build stamp inside the binary (`CliBuildStampSchema`,
+`formatCliBuildStamp`) so the tool can say what it is rather than leaving the
+reader to infer it from behaviour.
+
+#### A manifest inside your own network
+
+The check goes through the same SSRF boundary every outbound fetch does, so a
+manifest served from `10.x`, `localhost` or a `.internal` name is refused and
+the answer is `unknown`. For a self-hosted deployment that is a wrong answer
+dressed as a careful one, and the refusal says so — it names the field that
+lifts it rather than reading like a timeout:
+
+```text
+refusing to fetch an internal host — the manifest endpoint is not public.
+Set `allowPrivateHosts` if it is your own deployment; the download keeps its
+own setting, because an asset URL comes from the document.
+```
+
+```ts
+const check = await checkCliUpdate({ manifestUrl, currentVersion, allowPrivateHosts: true })
+```
+
+Set it from whether **your** endpoint is private, not as a blanket switch, and
+leave `applyCliUpdate` at its default. The two are not the same decision: the
+manifest URL is configuration you wrote, while an asset URL arrives inside a
+document the endpoint served, and a document is exactly what an SSRF boundary
+exists to distrust.
+
+### Publishing a complete version
+
+`publishCli` is an opt-in publisher for a local application-owned distribution
+directory. It commits every target and its version manifest before atomically
+replacing the public `manifest.json`. It ships from its own evolving entrypoint,
+`stitchkit/cli/publish`: release infrastructure follows how distributions are
+published, so it is not held to the stable promise of `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
+manifest, signatures, installer and updater it writes for stay in
+`stitchkit/cli`. Your application selects the CLI source identity and admits
+that snapshot at each phase:
+
+```ts
+import { publishCli } from 'stitchkit/cli/publish'
+
+const result = await publishCli({
+  storageRoot: '/srv/myapp/cli',
+  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
+  baseUrl: 'https://downloads.example.com/cli/',
+  targets: [{ platform: 'linux', arch: 'x64' }],
+  signal,
+  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
+  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
+})
+// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
+```
+
+The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
+executable. Every target receives the same immutable `{ version, commit,
+builtAt }` stamp; carry it inside the binary. The publisher owns staging,
+gzip assets, paths and manifests. Callbacks receive the cancellation signal and
+run under the publication lock. Admission phases are `prepare`, each target's
+`build`, `commit`, and `promote`; validate the selected source through commit
+and promotion. A backend release can explicitly select an unchanged older CLI
+identity. The helper never substitutes a different commit or rebuilds an
+existing version under a new identity.
+
+Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
+`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
+the exact bytes and `builtAt`, requires the same target set and base URL, and
+returns `existing` without invoking the builder. A version committed before a
+failed promotion is recovered and promoted without rebuilding. Conflicting
+same-version commits, downgrades, unsafe components, corrupt manifests and
+assets are refused. Version/name/target components are validated before any
+build; `storageRoot` is absolute and its existing parent must be trusted.
+
+All limits are finite positive safe integers; `limits` overrides these defaults:
+
+| Field | Default | Enforced boundary |
+| --- | --- | --- |
+| `maxTargets` | 16 | Requested and verified target count |
+| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
+| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
+| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
+| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
+| `maxStoredVersions` | 16 | Verified publisher-owned history |
+| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
+| `timeoutMs` | 600,000 | Whole publication deadline |
+
+`retention` defaults to 2 and keeps the current and previous published versions.
+It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
+recovery slot. Older versions are pruned only after their own identity, exact
+layout, raw size and digest are verified. Runtime folders and foreign semver
+directories remain untouched. A full or unverifiable store refuses further
+publication; repeated completed candidates stay inside the owned history cap.
+Cancelled or failed incomplete staging is removed only while its root and
+directory generations still match. The shared asynchronous gzip decoder also
+bounds updater expansion by the declared raw size and configured byte cap.
+
+The publisher rejects symlink roots/versions/assets, non-regular files and
+multiply linked files, and checks held-lock, root and prior-pointer generations
+before commit and promotion. This is cooperative publication under a trusted
+parent directory. Portable path checks do not provide an atomic comparison with
+a hostile process replacing ancestors between syscalls. Durability uses file
+and directory sync on POSIX; Windows publication is refused. A deadline stops
+callback/stream waits and blocks late promotion; trusted callbacks remain
+responsible for cancelling their own subprocesses and external effects.
+
+A failure after an immutable commit reports that the publication outcome must
+be checked. A failure after public-pointer rename may already have published;
+`AtomicFilePublicationError.published` remains available when the atomic writer
+reports that boundary. Read the durable manifest and retry the admitted same
+identity to recover; an error does not promise rollback. Optional `signing` and
+`trust` reuse the Ed25519 contract below. The generated shell installer checks
+raw digest and size; the updater checks manifest authorship when given a trust
+root.
+
+### Proving who built it — signing the manifest
+
+The asset digest proves the bytes that arrived are the bytes the manifest named.
+It proves nothing about who named them: the manifest and the assets come from
+one origin, so whoever can replace one can replace the other. Authorship needs a
+key the build carries and the server never holds.
+
+```ts
+// Publishing — the only side that holds a private key.
+const signature = signCliManifest(manifest, { keyId: 'release-2026', privateKey })
+publish({ ...manifest, signature })
+
+// Installing — the trust root is compiled into the binary. One fetched at run
+// time from the same origin as the manifest would prove nothing.
+const trust = { keys: { 'release-2026': PUBLISHED_KEY } }
+const check = await checkCliUpdate({ manifestUrl, currentVersion, trust })
+if (check.status === 'outdated' && check.asset) {
+  await applyCliUpdate({ asset: check.asset, manifest: check.manifest, trust, backupPath })
+}
+```
+
+The signature covers `{name, version, commit, builtAt, assets[]}` with **every
+asset's digest**, so the chain closes on the file that will execute rather than
+on the document describing it; moving an asset to a new URL does not invalidate
+it, changing what an asset contains does.
+
+Five verdicts, and `unenforced` is the one that earns its keep: a build with no
+pinned key keeps updating, and the fact that nothing was checked is *visible*
+rather than assumed. `missing`, `unknown-key` and `invalid` are distinguished
+because they need different answers — a key you forgot to pin is not a forged
+signature.
+
+A bad verdict does not produce a fifth status. `outdated` is an instruction to
+install, and a manifest that failed its signature has not established that there
+is a newer build worth installing — only that a document claims one. The check
+answers `unknown` with the verdict in its reason, so it is never mistaken for a
+network failure. `applyCliUpdate` checks again and refuses **before** the
+download: a signature verified after the bytes are on the machine produces a
+cleanup problem rather than a refusal.
+
+### A way back — `backupPath` and `rollbackCliUpdate`
+
+Rolling back is a property of updating, not of the application:
+
+```ts
+const applied = await applyCliUpdate({ asset, targetPath, backupPath })
+// …the new build turns out to be wrong. `backupSha256` is absent when there was
+// nothing to keep — a first install — and that is the case with nothing to roll
+// back to:
+if (applied.backupSha256) {
+  rollbackCliUpdate({ targetPath, backupPath, expectedSha256: applied.backupSha256 })
+}
+```
+
+The copy is taken between "the new bytes verified" and the replacement — earlier
+would preserve a binary about to be replaced by a download that then failed its
+digest, later has nothing left to copy — and it carries the target's file mode,
+because a backup that cannot be executed is not a way back. A first install has
+nothing to keep, which is not a failure.
+
+`expectedSha256` is required, not optional. A rollback that installs whatever
+happens to be at the backup path is a second install of an unverified binary,
+and the day it is used is the day nobody is in a position to check.
+
+### Run it before it replaces anything — `verify`
+
+A digest proves the bytes are the ones published, not that they load. A tool
+that updates itself unattended — a daemon — and installs a build that does not
+start takes its own updater down with it, and every machine is then repaired by
+hand. `verify` is the step between "digest matched" and "target replaced":
+
+```ts
+await applyCliUpdate({
+  asset, targetPath, backupPath,
+  verify: async (candidate, signal) => {
+    const child = Bun.spawn(['bun', candidate, 'version'], { signal, stdout: 'pipe' })
+    const printed = (await new Response(child.stdout).text()).trim()
+    if ((await child.exited) !== 0 || printed !== check.version) {
+      throw new Error(`printed ${printed}, expected ${check.version}`)
+    }
+  },
+  verifyTimeoutMs: 15_000,   // default 30 000
+})
+```
+
+The verified bytes are written beside the target as an executable candidate
+with the target's extension, and `verify` gets its path — a path rather than a
+command, because a JavaScript bundle is started through its runtime. It runs
+before the backup and the replacement. If it throws or outlives
+`verifyTimeoutMs` (its `signal` aborts at the deadline), the candidate is
+removed, the target and any earlier backup are untouched, and the update is
+refused with the reason as its cause. The target is written from the checked
+bytes in memory, never from the candidate file, so nothing the candidate did
+while it ran can change what is installed.
+
+### Two release tracks
+
+`assertCliPublishable` takes one manifest **or every manifest already
+published**:
+
+```ts
+assertCliPublishable([stableManifest, betaManifest], next)
+```
+
+With a single argument and two tracks the check is silently useless: `1.2.3`
+goes to beta from one commit and to stable from another, the function is called
+with the track being published and sees no conflict, and the person who
+installed the beta is told they are current forever. Nothing on their machine
+looks wrong.
+
+**The channel itself is not an argument of the framework, and will not become
+one.** The framework has no model of how your URLs are built and should not: an
+asset's address comes from the manifest, and the manifest's address belongs to
+your server. A channel is two documents at two addresses — which of them a build
+consults is your decision, and `assertCliPublishable` is told about all of them
+rather than taught the shape of any.
+
 ## One operation per line — `createCliInvoker`
 
 The most common way an agent drives a CLI is not one command: it is a stream —
@@ -290,7 +571,7 @@ SDK nor the `ai` peer.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `createCli` | function | build and run a CLI from contracts; a runtime catalogue field conflicting with reserved/global argv options disables only that entry, retained in help with its reason; invocation returns `CLI_COMMAND_UNAVAILABLE` before side effects — [guide](../guide/cli.md#when-one-runtime-command-cannot-be-represented-in-argv) |
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
 | `parseCliArgs` | function | argv → typed tool args against a schema; inline `--field:=JSON` assigns a whole JSON value, including null, while ordinary string flags remain lexical; named array options together with bare positionals require an explicit `positionals` policy (advanced) |
 | `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |