stitchkit 0.111.3 → 0.112.1

package/CHANGELOG.md

@@ -15,6 +15,22 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.112.1] - 2026-10-25
+
+### Fixed
+
+- `stitchkit/agent-runtime` — an empty or control-only failed assistant now retains its non-success marker when explicitly included with `evidencePolicy.failedAssistant: 'assistant-marked'`. The default still omits failed evidence. The compaction guide explains the existing failed-prefix recovery policy, status-aware summarization, and why a closed tool exchange cannot settle an external effect. → ADR 0269
+  **Affects:** `stitchkit/agent-runtime` projectAgentHistory, projectAgentHistoryDetailed
+
+## [0.112.0] - 2026-10-24
+
+### ⚠️ Breaking changes
+
+**Who must act:** scripts that combine named array options with bare positional arguments without an explicit `positionals` policy must name the scalar fields or declare their destinations. Flag-only calls and explicitly declared positional policies need no migration.
+
+- `stitchkit/cli` — **array options require named arguments or an explicit positional policy.** Without a declared `positionals` policy, a named array option together with any bare positional is now a usage error before dispatch. Schema-order inference could mistake the array's remaining elements for unrelated optional fields and execute a different call. Before: `app resolve --references alpha.md beta.md gamma.md` could assign `beta.md` and `gamma.md` to other fields. After: `app resolve --references alpha.md --references beta.md --references gamma.md`, or `app resolve --references:='["alpha.md","beta.md","gamma.md"]'`. Name scalar fields with flags too, or declare their exact positional policy. Command help describes one element per option; only a declared trailing positional array is variadic. See [ADR 0268](docs/decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md) and the [migration](docs/guide/upgrading.md).
+  **Affects:** `stitchkit/cli` createCli, parseCliArgs
+
 ## [0.111.3] - 2026-10-20
 
 ### Fixed

package/dist/agent-runtime/history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAsB,MAAM,IAAI,CAAC;AAO1E,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAyB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,mBAAmB,CAAC;AAE3B,KAAK,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,WAAW,CAAC,CACV,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;CACpE;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,MAAM,EACF,WAAW,GACX,iBAAiB,GACjB,OAAO,GACP,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;IACjB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS,8BAA8B,EAAE,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAyMD,wEAAwE;AACxE,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CA4GvC;AAED,4EAA4E;AAC5E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAsB,MAAM,IAAI,CAAC;AAO1E,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAyB,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,KAAK,0BAA0B,EAEhC,MAAM,mBAAmB,CAAC;AAE3B,KAAK,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAEzC,MAAM,WAAW,6BAA6B;IAC5C,cAAc,CAAC,EAAE,0BAA0B,CAAC;IAC5C,WAAW,CAAC,CACV,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EACjD,OAAO,EAAE,YAAY,GACpB,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3C,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC9C,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,oBAAoB,CAAC,EAAE,kBAAkB,GAAG,aAAa,GAAG,MAAM,CAAC;CACpE;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAChC,MAAM,EACF,WAAW,GACX,iBAAiB,GACjB,OAAO,GACP,mBAAmB,GACnB,sBAAsB,GACtB,aAAa,GACb,YAAY,CAAC;IACjB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,SAAS,EAAE,SAAS,8BAA8B,EAAE,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AA2MD,wEAAwE;AACxE,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,CA4GvC;AAED,4EAA4E;AAC5E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,YAAY,EAAE,CAAC,CAEzB"}

package/dist/entrypoints/agent-runtime/harness.js

@@ -5,7 +5,7 @@ import"../../index-8kzct1d6.js";
 import {
   composeAgentPrompt2,
   createAgentRuntime2
-} from "../../index-5as18gs2.js";
+} from "../../index-a0vj9edp.js";
 import"../../index-qaet40b2.js";
 import"../../index-mnkk1ffz.js";
 import"../../index-fynr93w4.js";

package/dist/entrypoints/agent-runtime.js

@@ -123,7 +123,7 @@ import {
   agentGoalStateSlot2,
   agentTodoStateSlot2,
   createAgentRuntime2
-} from "../index-5as18gs2.js";
+} from "../index-a0vj9edp.js";
 import {
   AgentConversationSummarySchema2,
   AgentConversationPageSchema2,

package/dist/entrypoints/cli.js

@@ -16,7 +16,7 @@ import {
   renderCliView2,
   pollUntilDone2,
   createCli2
-} from "../index-jprxv2an.js";
+} from "../index-bd7spznx.js";
 import"../index-fynr93w4.js";
 import"../index-ct75c3at.js";
 import"../index-h7accrrv.js";

package/dist/entrypoints/tools.js

@@ -74,7 +74,7 @@ import {
   WaitTimeoutError,
   runWaitOperation,
   createCli2
-} from "../index-jprxv2an.js";
+} from "../index-bd7spznx.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2

package/dist/{index-5as18gs2.js → index-a0vj9edp.js}

@@ -490,7 +490,7 @@ function assistantMessages(message, marker) {
       rendered.add("tool-approval-response");
     }
   }
-  if (marker && (messages.length > 0 || content.length > 0)) {
+  if (marker === "failed" || marker && (messages.length > 0 || content.length > 0)) {
     append("assistant", {
       type: "text",
       text: marker === "interrupted" ? INTERRUPTION_NOTE : FAILURE_NOTE

package/dist/{index-jprxv2an.js → index-bd7spznx.js}

@@ -1102,6 +1102,12 @@ function resolveCliView(flags, ascending) {
 // src/tools/cli/args.ts
 function buildToolArgs(tokens, fields, fieldFor, declaredPositionals, allowUnknown) {
   const { flags, jsonFields, literalBooleanFlags, positionals } = tokens;
+  if (declaredPositionals === undefined && positionals.length > 0) {
+    const arrayFlag = [...flags.keys()].find((key) => fieldFor(key)?.kind === "array");
+    if (arrayFlag !== undefined) {
+      throw new CliArgumentError2(`--${arrayFlag} cannot be combined with automatic positional arguments. Repeat --${arrayFlag} for each element or use --${arrayFlag}:=JSON; name other fields with flags, or declare a positional policy.`);
+    }
+  }
   const toolArgs = {};
   const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
   const variadicTail = declaredPositionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
@@ -1660,7 +1666,7 @@ function typeLabel(schema) {
   if (Array.isArray(schema.enum))
     return schema.enum.join("|");
   if (schema.type === "array")
-    return "value…";
+    return "value";
   if (typeof schema.type === "string")
     return schema.type;
   return "value";
@@ -1822,6 +1828,13 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
     if (flag !== undefined) {
       lines.push("", `A boolean flag is on alone or takes true/false: --${flag}, --${flag} false, --no-${flag}`);
     }
+    const arrays = [...kinds].filter(([, info]) => info.kind === "array");
+    for (const [field] of arrays) {
+      lines.push("", `Repeat --${field} <value> for each element, or assign the whole array with --${field}:=JSON.`);
+    }
+    if (arrays.length > 0 && descriptor.positionals === undefined) {
+      lines.push("Array options cannot be combined with automatic positional arguments; name other fields with flags.");
+    }
     lines.push("", ...jsonValueHelp(fields), "");
   }
   const applicationLines = applicationOptionLines(applicationOptions);

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

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAMjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA6GD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAyDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAMjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAwHD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAsBf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAyDvB"}

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,CA6DR"}
+{"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"}

package/llms/agent-runtime.2.txt

@@ -7,7 +7,7 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
@@ -615,6 +615,62 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Recovering a prefix after a failed turn
+
+The default evidence policy omits failed assistants. A failed turn therefore stops the
+compactable prefix, including completed turns after it. A terminal failure is not an
+unanswered tool call, but opting its partial evidence into a summary is an explicit host
+decision. Use the existing `evidencePolicy: { failedAssistant: 'assistant-marked' }` on
+`structuredCompaction` (or `selectCompactableHistory`) when that evidence is wanted.
+The same policy belongs on the summarizer's history projection and on any corresponding
+token-budget selection. Stored statuses remain unchanged.
+
+The summarizer receives **raw** `eligibleMessages`, not provider messages and not an
+automatic failure marker. Project them with the same policy before sending them to a
+model, and preserve failed outcomes in the application's structured summary and prompt:
+
+```ts
+const evidencePolicy: AgentHistoryEvidencePolicy = {
+  failedAssistant: 'assistant-marked',
+}
+
+// Inside structuredCompaction({ evidencePolicy, ... }).summarize:
+const projected = await projectAgentHistoryDetailed(eligibleMessages, {
+  evidencePolicy,
+  incompleteToolTurn: 'error',
+})
+const failedMessageIds = eligibleMessages
+  .filter(message => message.role === 'assistant' && message.status === 'failed')
+  .map(message => message.id)
+// Pass projected.messages, projected.system and failedMessageIds to the host's
+// summarizer. Its schema/prompt must retain failures and uncertain effects as
+// such, merge previousSummary, and never describe partial output as success.
+```
+
+An opted-in failed assistant projects an explicit non-success marker even when it has
+no text or only control parts. A dangling call, unresolved approval, invalid result
+chronology or a user input with no assistant remains a barrier under either policy.
+Raw whole-turn completeness does not guarantee that every record can be projected:
+for example, a call and its result split across records may be rejected by the projector.
+`incompleteToolTurn: 'error'` makes that rejection stop summarization; the original history
+stays canonical. A host with such records must use a status-aware summarizer that explicitly
+represents every relevant record, or retain the range. Do not silently summarize an omitted
+exchange, filter the failed record out of the replacement range, rewrite its status or skip
+over an incomplete turn. The replacement remains one contiguous prefix under snapshot CAS.
+
+Provider chronology and external effect authority answer different questions (ADR 0269).
+A matching `tool-result` with `outcome: 'error'` and an application code such as `UNKNOWN`
+closes the provider exchange; it does **not** prove the external effect failed or succeeded.
+Compaction changes the model-history projection, not the canonical event journal or the
+retained terminal admission receipt. The `durability/effect` intent, accepted proof and
+uncertain outcome remain available after compaction and archive restore. A reconstructed
+`createLocalStepDurability` using the original `(conversationId, runId, effectName)` returns
+the accepted proof, reconciles a bare intent, or returns `uncertain` without calling `run`
+again. It does not deduplicate a new run or a newly named effect. Standalone effect callers
+still own the exclusive execution lease; sharing a ledger is not an atomic claim.
+An application-owned receipt outside that journal retains its own recovery rules and must
+not be discarded because a history turn became compactable.
+
 ### Compacting without the store
 
 The *selection* inside compaction needs no store, no version and no runtime, so
@@ -772,105 +828,3 @@ first mutation**, so an adapter whose runtime rows reference an application-owne
 can provision those parents; the optional `cleanup(context)` removes them again, and runs once
 whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
 keeps working unchanged.
-
-## Plain completions and shared invocation receipts
-
-Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
-completion and an agent must share causal provider evidence. It uses the existing
-runtime store, not a second database. The completion path sends exactly one user
-prompt, no framework instructions and no tools. It never starts an agent loop.
-
-```ts
-import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
-
-const invocations = createModelInvocationLedger({
-  store, // the same AgentRuntimeStore object passed to createAgentRuntime
-  models, // an existing defineModelRegistry result
-  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
-  authorize: async ({ context, conversationId, action, trace }) => {
-    const session = await authenticate(context);
-    await authorizeConversation(session, conversationId, action, trace);
-    return { subject: session.subject }; // verified identity, never a body field
-  },
-});
-
-const completion = await invocations.complete({
-  conversationId: 'evaluation-42',
-  idempotencyKey: 'summary-case-3',
-  trace: {
-    operationId: 'summary-42', purpose: 'summarize', project: 'example',
-    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
-  },
-  prompt: 'Summarize these supplied facts.',
-  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
-  settings: { maxOutputTokens: 500 },
-  timeoutMs: 30_000,
-}, authenticatedContext);
-
-// Add to the existing createAgentRuntime configuration:
-const receiptConfig = {
-  ledger: invocations,
-  trace: ({ run }) => ({
-    operationId: run.id, purpose: 'assistant-turn', project: 'example',
-  }),
-};
-// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
-
-const page = await invocations.read({
-  conversationId: 'evaluation-42', limit: 100,
-}, authenticatedContext);
-// Continue with fromSeq: page.nextSeq while it is defined.
-```
-
-`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
-returns the existing ID without provider execution or replaying plaintext. Changed
-input, trace or caller under the same key is a conflict. Model attempts are explicit
-and bounded to eight; SDK retries are disabled. Only provider failures trigger the
-next attempt. Abort, audit refusal and configuration errors do not. An admitted call
-whose process died stays claimed: inspect the receipt before choosing a new key.
-
-The agent retains its existing prompt, tools and loop. Both modes produce
-`invocation/started`, `provider/request`, `provider/response` and
-`invocation/finished` records through `read`. Each attempt has its own ID; response
-usage is counted once and keeps `unavailable` distinct from measured zero. Requested
-registry selection, sent adapter identity and effective provider identity are
-separate. Effective identity is null when not reported. A gateway's hidden retries
-are not visible as additional attempts.
-
-`currentModelInvocationAttempt()` returns the causal context inside a provider's
-`fetch` callback or streamed read. Use it to join a host transport audit to
-`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
-`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
-SDK payload hashes are not represented as hashes of HTTP wire bytes.
-
-Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
-hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
-`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
-bytes and is copied at construction. Keep it outside the event store/backups; retain
-the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
-(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
-that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
-the answer itself is never cut. A receipt that cannot be written never changes an
-outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
-answer keeps its `text`. Request headers
-are excluded. Protect existing agent history independently: enabling receipts does
-not encrypt its ordinary conversation records.
-
-The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
-must implement its once-only check and append atomically, returning the original
-event on a duplicate key scoped by conversation and kind. A factory without this
-capability refuses receipt setup. The driver-backed implementation finds the keyed
-event by its identity through the driver's optional `events.find` — one index probe
-in SQLite — so admission costs the same on a long conversation as on a new one; a
-custom driver without `find` falls back to paging the log in one transaction.
-`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
-Invocation payload artifacts are keyed by their artifact id the same way.
-
-### Migration from direct SDK completions
-
-**Who must act:** applications opting into shared completion/agent receipts.
-Replace the direct `generateText` call with `invocations.complete`, configure host
-authorization and a retained payload key, and pass the same ledger in the agent's
-`invocations` option. Use the returned invocation ID and the paginated `read` method
-for receipt queries; do not import runtime internals. Available since 0.100.0;
-existing runtime configurations need no migration.

package/llms/agent-runtime.3.txt

@@ -6,7 +6,113 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
+==============================================================================
+
+## Plain completions and shared invocation receipts
+
+Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
+completion and an agent must share causal provider evidence. It uses the existing
+runtime store, not a second database. The completion path sends exactly one user
+prompt, no framework instructions and no tools. It never starts an agent loop.
+
+```ts
+import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
+
+const invocations = createModelInvocationLedger({
+  store, // the same AgentRuntimeStore object passed to createAgentRuntime
+  models, // an existing defineModelRegistry result
+  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
+  authorize: async ({ context, conversationId, action, trace }) => {
+    const session = await authenticate(context);
+    await authorizeConversation(session, conversationId, action, trace);
+    return { subject: session.subject }; // verified identity, never a body field
+  },
+});
+
+const completion = await invocations.complete({
+  conversationId: 'evaluation-42',
+  idempotencyKey: 'summary-case-3',
+  trace: {
+    operationId: 'summary-42', purpose: 'summarize', project: 'example',
+    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
+  },
+  prompt: 'Summarize these supplied facts.',
+  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
+  settings: { maxOutputTokens: 500 },
+  timeoutMs: 30_000,
+}, authenticatedContext);
+
+// Add to the existing createAgentRuntime configuration:
+const receiptConfig = {
+  ledger: invocations,
+  trace: ({ run }) => ({
+    operationId: run.id, purpose: 'assistant-turn', project: 'example',
+  }),
+};
+// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
+
+const page = await invocations.read({
+  conversationId: 'evaluation-42', limit: 100,
+}, authenticatedContext);
+// Continue with fromSeq: page.nextSeq while it is defined.
+```
+
+`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
+returns the existing ID without provider execution or replaying plaintext. Changed
+input, trace or caller under the same key is a conflict. Model attempts are explicit
+and bounded to eight; SDK retries are disabled. Only provider failures trigger the
+next attempt. Abort, audit refusal and configuration errors do not. An admitted call
+whose process died stays claimed: inspect the receipt before choosing a new key.
+
+The agent retains its existing prompt, tools and loop. Both modes produce
+`invocation/started`, `provider/request`, `provider/response` and
+`invocation/finished` records through `read`. Each attempt has its own ID; response
+usage is counted once and keeps `unavailable` distinct from measured zero. Requested
+registry selection, sent adapter identity and effective provider identity are
+separate. Effective identity is null when not reported. A gateway's hidden retries
+are not visible as additional attempts.
+
+`currentModelInvocationAttempt()` returns the causal context inside a provider's
+`fetch` callback or streamed read. Use it to join a host transport audit to
+`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
+`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
+SDK payload hashes are not represented as hashes of HTTP wire bytes.
+
+Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
+hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
+`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
+bytes and is copied at construction. Keep it outside the event store/backups; retain
+the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
+(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
+that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
+the answer itself is never cut. A receipt that cannot be written never changes an
+outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
+answer keeps its `text`. Request headers
+are excluded. Protect existing agent history independently: enabling receipts does
+not encrypt its ordinary conversation records.
+
+The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
+must implement its once-only check and append atomically, returning the original
+event on a duplicate key scoped by conversation and kind. A factory without this
+capability refuses receipt setup. The driver-backed implementation finds the keyed
+event by its identity through the driver's optional `events.find` — one index probe
+in SQLite — so admission costs the same on a long conversation as on a new one; a
+custom driver without `find` falls back to paging the log in one transaction.
+`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
+Invocation payload artifacts are keyed by their artifact id the same way.
+
+### Migration from direct SDK completions
+
+**Who must act:** applications opting into shared completion/agent receipts.
+Replace the direct `generateText` call with `invocations.complete`, configure host
+authorization and a retained payload key, and pass the same ledger in the agent's
+`invocations` option. Use the returned invocation ID and the paginated `read` method
+for receipt queries; do not import runtime internals. Available since 0.100.0;
+existing runtime configurations need no migration.
 
 ==============================================================================
 # API reference: `stitchkit/agent-runtime`  (docs/api/reference.md)
@@ -244,6 +350,16 @@ projection, budgeting and structured compaction; `isAssistantHistoryEvidence` ap
 compatibility default omits it. Approval message schemas are
 `AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
 
+With `failedAssistant: 'assistant-marked'`, `selectCompactableHistory` and
+`structuredCompaction` admit a failed prefix only when the entire turn's tool chronology
+is complete. `eligibleMessages` stays raw: the summarizer must use the same policy in
+`projectAgentHistoryDetailed` and preserve non-success/uncertain outcomes in its summary.
+Even an empty opted-in failed assistant carries a non-success marker in that projection.
+Use `incompleteToolTurn: 'error'` to refuse a range the projector cannot represent.
+Compaction never deletes canonical effect events or the retained terminal receipt;
+chronological completeness does not settle an external effect. See the
+[failed-prefix recovery contract](../guide/agent-runtime.md#recovering-a-prefix-after-a-failed-turn).
+
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 `AgentModelCapabilitySchema`, `AgentModelDescriptor`,
 `AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,

package/llms/agent-runtime.txt

@@ -7,7 +7,7 @@
 Parts of this slice:
 - `llms/agent-runtime.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 - `llms/agent-runtime.2.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md)
-- `llms/agent-runtime.3.txt`: API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
+- `llms/agent-runtime.3.txt`: Guide: Agent application runtime  (docs/guide/agent-runtime.md) · API reference: `stitchkit/agent-runtime`  (docs/api/reference.md) · API reference: `stitchkit-tui`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)

package/llms/cli.2.txt

@@ -281,7 +281,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `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 (advanced) |
+| `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) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms/cli.txt

@@ -247,6 +247,15 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+An array option takes **one value per occurrence**, never a bare list after the flag.
+Repeat it (`--tag a --tag b`) or assign the whole array (`--tag:='["a","b"]'`).
+Without an explicit command `positionals` policy, combining any named array option
+with bare positionals is refused before dispatch: schema-order inference could otherwise
+assign the remaining array elements to unrelated fields. This includes short aliases,
+dotted array leaves, whole-array JSON and tokens after `--`, regardless of token order.
+Name the scalar fields too, or declare their exact positional destinations. An explicitly
+declared trailing positional array is the variadic form described below.
+
 Use the inline `:=` form to assign a whole JSON value without scalar coercion:
 
 ```bash
@@ -522,7 +531,7 @@ Declared aliases render beside their canonical options, for example
 
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
-`<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
+`<value> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
 and `<=` include the endpoint; a zero limit is displayed too. Only limits the
 schema declares are shown: the safe-integer range every `z.int()` carries is the
 type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and

package/llms/stitchkit.txt

@@ -85,12 +85,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 56 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 57 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 56 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 57 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -102,7 +102,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 56 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 57 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/{upgrading-0.101.0-0.111.0.txt → upgrading-0.103.0-0.112.0.txt}

@@ -1,14 +1,45 @@
-# Upgrading 0.101.0 → 0.111.0 — stitchkit docs slice
+# Upgrading 0.103.0 → 0.112.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.103.0 → 0.112.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.103.0 → 0.112.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.112.0
+
+**Who must act:** scripts using an array option together with bare positional arguments without a declared `positionals` policy, including calls to `parseCliArgs`.
+
+An array flag consumes one value. Automatic schema-order positionals cannot distinguish additional array elements from values intended for unrelated fields, so the combination is refused before any handler or stdin read. The rule is independent of token order, includes aliases, dotted array leaves and whole-array JSON, and `--` does not bypass it. See [ADR 0268](../decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md).
+
+```sh
+# before: the last two words could populate unrelated fields
+app resolve --references alpha.md beta.md gamma.md
+# after: repeat the option or assign the whole array
+app resolve --references alpha.md --references beta.md --references gamma.md
+app resolve --references:='["alpha.md","beta.md","gamma.md"]'
+
+# before: even an intended scalar positional has an implicit destination
+app resolve project-one --references alpha.md
+# after: name it
+app resolve --projectId project-one --references alpha.md
+```
+
+Applications that intend positional syntax declare its destinations on the available command:
+
+```ts
+createCli({ ...config, positionals: { resolve: ['projectId'] } })
+// app resolve project-one --references alpha.md
+
+createCli({ ...config, positionals: { resolve: ['references'] } })
+// app resolve alpha.md beta.md gamma.md
+```
+
+A declared trailing array accepts all remaining positional elements. Giving that same field both a flag and positional elements remains an error. An empty policy accepts flags only. Policies still target exact available command names: a partial dynamic catalogue needs no policy for an unavailable command to enforce this admission rule.
+
 ## Released migration: 0.111.0
 
 **Who must act:** applications whose raw routes call `parseBody` on JSON larger than 1 MiB, and applications whose OAuth clients send `/register` or `/token` bodies larger than 64 KiB.
@@ -874,63 +905,3 @@ For archive inspection, replace ad hoc line parsing with `readDiagnosticJournal`
 from the same filesystem leaf. Handle its `frame | anomaly` stream explicitly;
 missing files, permissions and unsafe paths still throw. See the
 [journal guide](application-kernel.md#bounded-local-diagnostic-journal).
-
-## Released migration: 0.102.0
-
-### `view_file` receives an array, not an array encoded as text
-
-**Who must act:** callers sending `paths` as a JSON-encoded array string, or
-matching the former media-extension refusal for that input. Managed MCP,
-Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
-reports an input-validation error. Correct single paths and arrays need no change.
-
-```ts
-// Before
-{ paths: '["image.png"]' }
-// After
-{ paths: ['image.png'] }
-// One file may also be a string
-{ paths: 'image.png' }
-```
-
-The same rule applies to an array element containing another encoded array.
-Do not change generic string-union coercion: path strings remain strings.
-A legitimate filename such as `[preview].PNG` is still accepted. Local
-unsupported-extension errors now include the caller's path and extension;
-match the error code rather than the former generic message.
-
-## Released migration: 0.101.0
-
-### `TelegramInitDataUser` is `TelegramUser`
-
-**Who must act:** code that names the type `TelegramInitDataUser` from
-`stitchkit/telegram`. The record is the same; its name now says it is any
-Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
-too.
-
-```ts
-// Before
-import type { TelegramInitDataUser } from 'stitchkit/telegram'
-function ensureAccount(user: TelegramInitDataUser) {}
-// After
-import type { TelegramUser } from 'stitchkit/telegram'
-function ensureAccount(user: TelegramUser) {}
-```
-
-### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
-
-**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
-whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
-the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
-every logger on it mask bot tokens by shape; remove the pattern from
-`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
-your own.
-
-```ts
-// Before
-createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
-text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
-// After
-createJsonLogger({})
-redactTelegramBotToken(text)
-```

package/llms/{upgrading-0.61.0-0.73.0.txt → upgrading-0.61.0-0.74.0.txt}

@@ -1,14 +1,75 @@
-# Upgrading 0.61.0 → 0.73.0 — stitchkit docs slice
+# Upgrading 0.61.0 → 0.74.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.61.0 → 0.73.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.74.0
+
+One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
+planning the request, before anything was sent. A server refusal is unchanged.
+
+### If you match on the text of a client-side refusal
+
+A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
+invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
+arrive as an `ApiError` in the same shape a server validation failure uses.
+
+```ts
+// before
+catch (e) {
+  if (/Missing path param/.test(e.message)) …
+}
+
+// after
+catch (e) {
+  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
+}
+// e.details.issues[0].path === 'id'
+```
+
+`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
+reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
+
+| | `code` | `status` |
+|---|---|---|
+| the client refused your arguments | `VALIDATION_ERROR` | `0` |
+| the server refused your arguments | `VALIDATION_ERROR` | `400` |
+
+`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
+and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
+`stitchkit/server`.
+
+### If you are on `createHttpClient` and your call site relied on a synchronous throw
+
+This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
+**synchronously** on the Ky-backed client — before the call returned a promise — so
+`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
+client rejected normally. They now reject on both.
+
+```ts
+// before, on createHttpClient only
+try {
+  api.upload({})            // threw here
+} catch (e) { … }
+
+// after, on both transports
+await api.upload({}).catch(handler)
+```
+
+A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
+longer catches anything — which was already true on the other transport.
+
+Not a migration, but worth knowing: a missing multipart file used to be reported as
+`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
+where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
+validation stays on the server.
+
 ## Released migration: 0.73.0
 
 Two breaking changes. Nothing you send to a server changed, and only one of these

package/llms/{upgrading-0.74.0-0.100.0.txt → upgrading-0.75.0-0.102.0.txt}

@@ -1,14 +1,74 @@
-# Upgrading 0.74.0 → 0.100.0 — stitchkit docs slice
+# Upgrading 0.75.0 → 0.102.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.75.0 → 0.102.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.102.0
+
+### `view_file` receives an array, not an array encoded as text
+
+**Who must act:** callers sending `paths` as a JSON-encoded array string, or
+matching the former media-extension refusal for that input. Managed MCP,
+Agent and CLI surfaces now reject it as `VALIDATION_ERROR` before IO; raw MCP
+reports an input-validation error. Correct single paths and arrays need no change.
+
+```ts
+// Before
+{ paths: '["image.png"]' }
+// After
+{ paths: ['image.png'] }
+// One file may also be a string
+{ paths: 'image.png' }
+```
+
+The same rule applies to an array element containing another encoded array.
+Do not change generic string-union coercion: path strings remain strings.
+A legitimate filename such as `[preview].PNG` is still accepted. Local
+unsupported-extension errors now include the caller's path and extension;
+match the error code rather than the former generic message.
+
+## Released migration: 0.101.0
+
+### `TelegramInitDataUser` is `TelegramUser`
+
+**Who must act:** code that names the type `TelegramInitDataUser` from
+`stitchkit/telegram`. The record is the same; its name now says it is any
+Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
+too.
+
+```ts
+// Before
+import type { TelegramInitDataUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramInitDataUser) {}
+// After
+import type { TelegramUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramUser) {}
+```
+
+### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
+
+**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
+whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
+the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
+every logger on it mask bot tokens by shape; remove the pattern from
+`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
+your own.
+
+```ts
+// Before
+createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
+text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
+// After
+createJsonLogger({})
+redactTelegramBotToken(text)
+```
+
 ## Released migration: 0.100.0
 
 ### watch capacity and session/live/delivery adoption
@@ -1026,64 +1086,3 @@ schema.
 `stitchkit/live`, the watch hub, the keyspace and the trust fence are all
 additive. Adopt them when you want them; the guide is
 [Live data](./live.md).
-
-## Released migration: 0.74.0
-
-One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
-planning the request, before anything was sent. A server refusal is unchanged.
-
-### If you match on the text of a client-side refusal
-
-A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
-invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
-arrive as an `ApiError` in the same shape a server validation failure uses.
-
-```ts
-// before
-catch (e) {
-  if (/Missing path param/.test(e.message)) …
-}
-
-// after
-catch (e) {
-  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
-}
-// e.details.issues[0].path === 'id'
-```
-
-`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
-reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
-
-| | `code` | `status` |
-|---|---|---|
-| the client refused your arguments | `VALIDATION_ERROR` | `0` |
-| the server refused your arguments | `VALIDATION_ERROR` | `400` |
-
-`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
-and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
-`stitchkit/server`.
-
-### If you are on `createHttpClient` and your call site relied on a synchronous throw
-
-This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
-**synchronously** on the Ky-backed client — before the call returned a promise — so
-`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
-client rejected normally. They now reject on both.
-
-```ts
-// before, on createHttpClient only
-try {
-  api.upload({})            // threw here
-} catch (e) { … }
-
-// after, on both transports
-await api.upload({}).catch(handler)
-```
-
-A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
-longer catches anything — which was already true on the other transport.
-
-Not a migration, but worth knowing: a missing multipart file used to be reported as
-`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
-where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
-validation stays on the server.

package/llms/upgrading.txt

@@ -11,9 +11,9 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.101.0 → 0.111.0: `llms/upgrading-0.101.0-0.111.0.txt`
-- 0.74.0 → 0.100.0: `llms/upgrading-0.74.0-0.100.0.txt`
-- 0.61.0 → 0.73.0: `llms/upgrading-0.61.0-0.73.0.txt`
+- 0.103.0 → 0.112.0: `llms/upgrading-0.103.0-0.112.0.txt`
+- 0.75.0 → 0.102.0: `llms/upgrading-0.75.0-0.102.0.txt`
+- 0.61.0 → 0.74.0: `llms/upgrading-0.61.0-0.74.0.txt`
 - 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
 - 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`
 

package/llms-full.txt

@@ -77,12 +77,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 56 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 57 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 56 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 57 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -94,7 +94,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 56 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 57 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -6706,6 +6706,62 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Recovering a prefix after a failed turn
+
+The default evidence policy omits failed assistants. A failed turn therefore stops the
+compactable prefix, including completed turns after it. A terminal failure is not an
+unanswered tool call, but opting its partial evidence into a summary is an explicit host
+decision. Use the existing `evidencePolicy: { failedAssistant: 'assistant-marked' }` on
+`structuredCompaction` (or `selectCompactableHistory`) when that evidence is wanted.
+The same policy belongs on the summarizer's history projection and on any corresponding
+token-budget selection. Stored statuses remain unchanged.
+
+The summarizer receives **raw** `eligibleMessages`, not provider messages and not an
+automatic failure marker. Project them with the same policy before sending them to a
+model, and preserve failed outcomes in the application's structured summary and prompt:
+
+```ts
+const evidencePolicy: AgentHistoryEvidencePolicy = {
+  failedAssistant: 'assistant-marked',
+}
+
+// Inside structuredCompaction({ evidencePolicy, ... }).summarize:
+const projected = await projectAgentHistoryDetailed(eligibleMessages, {
+  evidencePolicy,
+  incompleteToolTurn: 'error',
+})
+const failedMessageIds = eligibleMessages
+  .filter(message => message.role === 'assistant' && message.status === 'failed')
+  .map(message => message.id)
+// Pass projected.messages, projected.system and failedMessageIds to the host's
+// summarizer. Its schema/prompt must retain failures and uncertain effects as
+// such, merge previousSummary, and never describe partial output as success.
+```
+
+An opted-in failed assistant projects an explicit non-success marker even when it has
+no text or only control parts. A dangling call, unresolved approval, invalid result
+chronology or a user input with no assistant remains a barrier under either policy.
+Raw whole-turn completeness does not guarantee that every record can be projected:
+for example, a call and its result split across records may be rejected by the projector.
+`incompleteToolTurn: 'error'` makes that rejection stop summarization; the original history
+stays canonical. A host with such records must use a status-aware summarizer that explicitly
+represents every relevant record, or retain the range. Do not silently summarize an omitted
+exchange, filter the failed record out of the replacement range, rewrite its status or skip
+over an incomplete turn. The replacement remains one contiguous prefix under snapshot CAS.
+
+Provider chronology and external effect authority answer different questions (ADR 0269).
+A matching `tool-result` with `outcome: 'error'` and an application code such as `UNKNOWN`
+closes the provider exchange; it does **not** prove the external effect failed or succeeded.
+Compaction changes the model-history projection, not the canonical event journal or the
+retained terminal admission receipt. The `durability/effect` intent, accepted proof and
+uncertain outcome remain available after compaction and archive restore. A reconstructed
+`createLocalStepDurability` using the original `(conversationId, runId, effectName)` returns
+the accepted proof, reconciles a bare intent, or returns `uncertain` without calling `run`
+again. It does not deduplicate a new run or a newly named effect. Standalone effect callers
+still own the exclusive execution lease; sharing a ledger is not an atomic claim.
+An application-owned receipt outside that journal retains its own recovery rules and must
+not be discarded because a history turn became compactable.
+
 ### Compacting without the store
 
 The *selection* inside compaction needs no store, no version and no runtime, so
@@ -9941,6 +9997,15 @@ string, the schema says what it should be:
 | `z.record(z.string(), z.unknown())` | `--data '{"code":"007"}'` or `--data.code=007` → `"007"` |
 | `.optional()` / `.default()` | not required                           |
 
+An array option takes **one value per occurrence**, never a bare list after the flag.
+Repeat it (`--tag a --tag b`) or assign the whole array (`--tag:='["a","b"]'`).
+Without an explicit command `positionals` policy, combining any named array option
+with bare positionals is refused before dispatch: schema-order inference could otherwise
+assign the remaining array elements to unrelated fields. This includes short aliases,
+dotted array leaves, whole-array JSON and tokens after `--`, regardless of token order.
+Name the scalar fields too, or declare their exact positional destinations. An explicitly
+declared trailing positional array is the variadic form described below.
+
 Use the inline `:=` form to assign a whole JSON value without scalar coercion:
 
 ```bash
@@ -10216,7 +10281,7 @@ Declared aliases render beside their canonical options, for example
 
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
-`<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
+`<value> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
 and `<=` include the endpoint; a zero limit is displayed too. Only limits the
 schema declares are shown: the safe-integer range every `z.int()` carries is the
 type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and
@@ -16193,6 +16258,37 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.112.0
+
+**Who must act:** scripts using an array option together with bare positional arguments without a declared `positionals` policy, including calls to `parseCliArgs`.
+
+An array flag consumes one value. Automatic schema-order positionals cannot distinguish additional array elements from values intended for unrelated fields, so the combination is refused before any handler or stdin read. The rule is independent of token order, includes aliases, dotted array leaves and whole-array JSON, and `--` does not bypass it. See [ADR 0268](../decisions/0268-named-cli-arrays-require-explicit-positional-destinations.md).
+
+```sh
+# before: the last two words could populate unrelated fields
+app resolve --references alpha.md beta.md gamma.md
+# after: repeat the option or assign the whole array
+app resolve --references alpha.md --references beta.md --references gamma.md
+app resolve --references:='["alpha.md","beta.md","gamma.md"]'
+
+# before: even an intended scalar positional has an implicit destination
+app resolve project-one --references alpha.md
+# after: name it
+app resolve --projectId project-one --references alpha.md
+```
+
+Applications that intend positional syntax declare its destinations on the available command:
+
+```ts
+createCli({ ...config, positionals: { resolve: ['projectId'] } })
+// app resolve project-one --references alpha.md
+
+createCli({ ...config, positionals: { resolve: ['references'] } })
+// app resolve alpha.md beta.md gamma.md
+```
+
+A declared trailing array accepts all remaining positional elements. Giving that same field both a flag and positional elements remains an error. An empty policy accepts flags only. Policies still target exact available command names: a partial dynamic catalogue needs no policy for an unavailable command to enforce this admission rule.
+
 ## Released migration: 0.111.0
 
 **Who must act:** applications whose raw routes call `parseBody` on JSON larger than 1 MiB, and applications whose OAuth clients send `/register` or `/token` bodies larger than 64 KiB.
@@ -22248,6 +22344,16 @@ projection, budgeting and structured compaction; `isAssistantHistoryEvidence` ap
 compatibility default omits it. Approval message schemas are
 `AgentToolApprovalRequestPartSchema` and `AgentToolApprovalResponsePartSchema`.
 
+With `failedAssistant: 'assistant-marked'`, `selectCompactableHistory` and
+`structuredCompaction` admit a failed prefix only when the entire turn's tool chronology
+is complete. `eligibleMessages` stays raw: the summarizer must use the same policy in
+`projectAgentHistoryDetailed` and preserve non-success/uncertain outcomes in its summary.
+Even an empty opted-in failed assistant carries a non-success marker in that projection.
+Use `incompleteToolTurn: 'error'` to refuse a range the projector cannot represent.
+Compaction never deletes canonical effect events or the retained terminal receipt;
+chronological completeness does not settle an external effect. See the
+[failed-prefix recovery contract](../guide/agent-runtime.md#recovering-a-prefix-after-a-failed-turn).
+
 Model exports are `AgentLanguageModelProvider`, `AgentModelCapability`,
 `AgentModelCapabilitySchema`, `AgentModelDescriptor`,
 `AgentModelDescriptorSchema`, `AgentModelRegistry`, `AgentModelRegistryConfig`,
@@ -23410,7 +23516,7 @@ SDK nor the `ai` peer.
 |--------|------|---------|
 | `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
 | `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 (advanced) |
+| `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) |
 | `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
 | `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, including discovered MCP object guards restored from JSON Schema, without the `stitchkit/tools` barrel |

package/llms.txt

@@ -18,14 +18,14 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.8 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 44.6 KB → [llms/cli.2.txt](llms/cli.2.txt) 21.3 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 45.3 KB → [llms/cli.2.txt](llms/cli.2.txt) 21.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.7 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 42.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 35.6 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 42.7 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 44.8 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.1 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 11.0 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 5.0 KB
@@ -64,9 +64,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.7 KB
-- **Upgrading 0.101.0 → 0.111.0**: [llms/upgrading-0.101.0-0.111.0.txt](llms/upgrading-0.101.0-0.111.0.txt) 46.9 KB
-- **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 45.1 KB
-- **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
+- **Upgrading 0.103.0 → 0.112.0**: [llms/upgrading-0.103.0-0.112.0.txt](llms/upgrading-0.103.0-0.112.0.txt) 46.6 KB
+- **Upgrading 0.75.0 → 0.102.0**: [llms/upgrading-0.75.0-0.102.0.txt](llms/upgrading-0.75.0-0.102.0.txt) 44.8 KB
+- **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 KB
 - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
 - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
 

package/package.json

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