@leanandmean/coding-agent 0.74.1-scramjet.7 → 0.74.1-scramjet.71

package/docs/extensions.md

@@ -288,8 +288,13 @@ user sends prompt ────────────────────
   │   ┌─── turn (repeats while LLM calls tools) ───┐       │
   │   │                                            │       │
   │   ├─► turn_start                               │       │
+  │   ├─► routing refresh                          │       │
   │   ├─► context (can modify messages)            │       │
+  │   ├─► before_provider_call (can replace request-local system prompt)
+  │   ├─► provider serialization                   │       │
   │   ├─► before_provider_request (can inspect or replace payload)
+  │   ├─► provider_request_tool_inventory (observe final tool names)
+  │   ├─► transport                                │       │
   │   ├─► after_provider_response (status + headers, before stream consume)
   │   │                                            │       │
   │   │   LLM responds, may call tools:            │       │
@@ -336,6 +341,16 @@ exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
   └─► session_shutdown
 ```
 
+### Required Scramjet Builtin
+
+Scramjet initializes as a **required builtin** through the resource loader (`builtinInit`), separately from optional disk-discovered extensions. Its successful initialization is a product invariant across **startup, reload, and every session replacement** (`/new`, resume, fork, clone, import):
+
+- The candidate runtime's loader is validated **before** any irreversible live mutation. On reload the loader runs before `session_shutdown` and `resetApiProviders()`; on session replacement the candidate is prepared before the current session is torn down.
+- If the Scramjet builtin fails to initialize, the loader throws a product-attributed `RequiredBuiltinInitError` (preserving the original failure as `cause`). The transition aborts, no `session_shutdown` fires, and the current runtime — runner, resources, providers — is left intact. At initial startup the same failure is fatal and exits non-zero.
+- This is distinct from optional-extension failures: a throwing disk or inline extension remains a non-fatal diagnostic and never aborts the session. Only the required product builtin fails fast.
+
+Extension authors do not interact with this directly, but it explains why a broken product init never leaves a session running without Scramjet.
+
 ### Resource Events
 
 #### resources_discover
@@ -477,7 +492,7 @@ pi.on("before_agent_start", async (event, ctx) => {
   //   (includes changes from earlier before_agent_start handlers)
   // event.systemPromptSections - read-only view of the base system prompt
   //   sections for this turn, before extension contributions; the volatile
-  //   environment tail (current date/cwd) is the section with
+  //   environment tail (current date/cwd/session journal) is the section with
   //   cacheRetention: "none"
   // event.systemPromptOptions - structured options used to build the system prompt
   //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
@@ -486,6 +501,7 @@ pi.on("before_agent_start", async (event, ctx) => {
   //   .promptGuidelines - custom guideline bullets
   //   .appendSystemPrompt - text from --append-system-prompt flags
   //   .cwd - working directory
+  //   .sessionFile - current session file path (undefined when sessions are disabled)
   //   .contextFiles - AGENTS.md files and other loaded context files
   //   .skills - loaded skills
 
@@ -510,7 +526,7 @@ Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` bo
 
 ##### System prompt sections
 
-Scramjet assembles the system prompt as ordered sections (`SystemPromptSection { id, text, cacheRetention?: "none" }` from `@leanandmean/ai`; ids are informational, and `"none"` is the only per-section retention — request-level retention applies otherwise) so providers can cache the stable prefix independently of the volatile tail. The last base section holds the current date and working directory and is marked `cacheRetention: "none"`; on Anthropic, everything before it is folded into a single cached system block and the volatile tail trails uncached.
+Scramjet assembles the system prompt as ordered sections (`SystemPromptSection { id, text, cacheRetention?: "none" }` from `@leanandmean/ai`; ids are informational, and `"none"` is the only per-section retention — request-level retention applies otherwise) so providers can cache the stable prefix independently of the volatile tail. The last base section holds the current date, working directory, and session journal path and is marked `cacheRetention: "none"`; on Anthropic, everything before it is folded into a single cached system block and the volatile tail trails uncached.
 
 Returning `systemPromptSection` contributes a section for the current turn without replacing Scramjet's prompt assembly:
 
@@ -619,14 +635,29 @@ pi.on("context", async (event, ctx) => {
 });
 ```
 
+#### before_provider_call
+
+Fired after request routing and message-context transformation, immediately before provider serialization. `event.model` is an immutable, handler-isolated snapshot of the exact model routed for this call, and `event.systemPrompt` is its request-local provider-neutral prompt (`string` or `SystemPromptSection[]`). Return `{ systemPrompt }` to replace only this call's prompt. Replacements chain in extension load order and never accumulate in session state.
+
+```typescript
+pi.on("before_provider_call", (event) => {
+  return {
+    systemPrompt: typeof event.systemPrompt === "string"
+      ? `${event.systemPrompt}\n\nRequest routed to ${event.model.provider}/${event.model.id}`
+      : [...event.systemPrompt, { id: "routed-model", text: `\n\nRequest routed to ${event.model.provider}/${event.model.id}` }],
+  };
+});
+```
+
 #### before_provider_request
 
-Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
+Fired after the provider-specific payload is built, right before transport. `event.model` is a fresh immutable snapshot of the same exact routed model exposed by `before_provider_call`; mutating one handler's snapshot cannot affect later handlers or transport routing. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
 
-This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Scramjet's system prompt string rather than the final serialized provider payload.
+This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Scramjet's stored system prompt string rather than request-local `before_provider_call` changes or the final serialized provider payload.
 
 ```typescript
-pi.on("before_provider_request", (event, ctx) => {
+pi.on("before_provider_request", (event) => {
+  console.log(`${event.model.provider}/${event.model.id}`);
   console.log(JSON.stringify(event.payload, null, 2));
 
   // Optional: replace payload
@@ -634,7 +665,34 @@ pi.on("before_provider_request", (event, ctx) => {
 });
 ```
 
-This is mainly useful for debugging provider serialization and cache behavior.
+The complete request order is routing refresh → `context` transformation → `before_provider_call` → provider serialization → public `Agent.onPayload` callback → `before_provider_request` → `provider_request_tool_inventory` → transport. The public callback runs exactly once; `undefined` keeps its input unchanged, while any other return value becomes the input to extension payload handlers. One extension runner is bound when `before_provider_call` begins and owns the request through preparation, payload hooks, and observation. If reload supersedes it during provider-neutral preparation or before payload dispatch begins, the public callback still runs but the old request skips extension rewriting and observation instead of entering the replacement runtime. This is mainly useful for request-local prompt preparation and debugging provider serialization or cache behavior.
+
+#### provider_request_tool_inventory
+
+Fired after the complete `before_provider_request` replacement chain and before the final payload is returned to provider transport. This event is observation-only: handlers have no return value and cannot change the outgoing request.
+
+```typescript
+pi.on("provider_request_tool_inventory", (event) => {
+  // Immutable, bounded identity of the exact routed model.
+  console.log(`${event.model.provider}/${event.model.id} (${event.model.api})`);
+  // Frozen copy from this request's provider-neutral context.
+  console.log(event.requestContextToolNames);
+
+  if (event.inventory.status === "observed") {
+    // Sorted, deduplicated names from the final serialized payload.
+    console.log(event.inventory.toolNames);
+  } else {
+    // "malformed" includes a bounded reason; "unsupported" does not inspect payload fields.
+    console.log(event.inventory.status);
+  }
+});
+```
+
+The event and all nested fields are frozen. The model snapshot contains only `provider`, `id`, and `api`; it excludes model headers, credentials, URLs, and other configuration. Supported built-in shape families are OpenAI Responses/Azure/Codex, OpenAI completions, Mistral conversations, Anthropic messages, Google Generative AI/Vertex function declarations, and Bedrock tool specifications. A missing optional tool container or valid empty list is observed as an empty inventory; malformed known shapes report only a bounded reason, never raw payload content. Custom API identifiers report `unsupported` when their provider invokes `onPayload`; a custom provider that does not invoke `onPayload` produces no final-schema observation.
+
+This boundary proves only what was present in the final pre-transport payload value after the public callback and extension rewrite chain. It does not prove transport success, response parsing, assistant completion, persistence, or model tool selection. If successful reload replaces the request's extension runner during provider-neutral preparation or before payload dispatch begins, extension rewriting and observation are skipped while the independent public callback still applies. If replacement occurs while the old runner's rewrite chain is already in flight, its completed replacement is preserved and the observation is suppressed. Observer failures use normal extension error isolation and do not alter the outgoing payload.
+
+**TypeScript compatibility:** Adding this event extends the exported `ExtensionEvent` union. Consumers with exhaustive switches over that union must add this member or a default/unknown-event branch; ordinary `pi.on(...)` registrations remain compatible.
 
 #### after_provider_response
 
@@ -880,7 +938,7 @@ UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
 
 ### ctx.hasUI
 
-`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client. Some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
+`false` in print mode (`-p`) and JSON mode. `true` in interactive and RPC mode. This is a transport-level signal, not a guarantee that every UI method is supported. In RPC mode, dialog methods (`select`, `confirm`, `input`, `editor`) work via the extension UI sub-protocol, and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) emit requests to the client, but TUI-only `custom()` resolves `undefined`. Other TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)). Extensions that require a specific UI method must handle that method's documented unsupported result.
 
 ### ctx.cwd
 
@@ -955,14 +1013,16 @@ Returns current context usage for the active model. Uses last assistant usage wh
 
 ```typescript
 const usage = ctx.getContextUsage();
-if (usage && usage.tokens > 100_000) {
+if (usage && usage.tokens !== null && usage.tokens > usage.contextWindow * 0.8) {
   // ...
 }
 ```
 
+`usage.contextWindow` is maximum supported total context and the denominator of `usage.percent`. Tokens and percent remain `null` when usage is unknown after compaction. The former `contextWindowBudget` field and `getContextWindowBudget()` export are removed; replace those reads with `contextWindow`. Model registrations may separately represent a genuine provider input constraint with `maxInputTokens`, not a discretionary budget. See [models.md](models.md#breaking-migration-from-context-budgets) for the breaking migration, validation, and preserved configuration/OAuth fallback behavior.
+
 ### ctx.compact()
 
-Trigger compaction without awaiting completion. Use `onComplete` and `onError` for follow-up actions.
+Trigger compaction without awaiting completion. Use `onComplete` and `onError` for follow-up actions. Competing manual/automatic compaction, branch summarization, or executing idle-origin harness work causes immediate refusal through `onError`; retry deliberately after conflicting work and its persistence settle. The admitted owner drains final `message_end` hooks and persistence while suppressing queued/new run/turn lifecycle continuation. New session harness invocations reject during manual ownership. See [manual admission and terminal drain](compaction.md#manual-admission-and-terminal-drain).
 
 ```typescript
 ctx.compact({
@@ -982,6 +1042,7 @@ Returns Scramjet's current system prompt string.
 
 - During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
 - It does not include later `context` message mutations.
+- It does not include request-local `before_provider_call` prompt replacements.
 - It does not include `before_provider_request` payload rewrites.
 - If later-loaded extensions run after yours, they can still change what is ultimately sent.
 
@@ -1516,10 +1577,17 @@ if (pi.getFlag("plan")) {
 Execute a shell command.
 
 ```typescript
-const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
-// result.stdout, result.stderr, result.code, result.killed
+const result = await pi.exec("gh", ["api", "--method", "POST", "--input", "-", endpoint], {
+  signal,
+  timeout: 5000,
+  stdin: JSON.stringify(payload),
+});
+// result.stdout, result.stderr, result.code, result.killed,
+// result.spawnError, result.stdinError, result.stdoutError, result.stderrError
 ```
 
+When `stdin` is supplied, `pi.exec` writes that exact UTF-8 string once and closes standard input without adding a newline. `spawnError` is present only when the command failed before spawning; `stdinError` reports a write or close failure; `stdoutError` and `stderrError` report output-pipe failures after spawn. Each error contains a safe `message` and optional system `code`, never stdin or process output content. Once the child has spawned, callers must use command-specific semantics to decide whether a failed execution may have produced side effects.
+
 ### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
 
 Manage active tools. This works for both built-in tools and dynamically registered tools.
@@ -1539,6 +1607,8 @@ const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.
 pi.setActiveTools(["read", "bash"]); // Switch to read-only
 ```
 
+Changes made by an awaited `turn_end` handler settle before the next provider request snapshots active tools and generated guidance.
+
 `pi.getAllTools()` returns `name`, `description`, `parameters`, and `sourceInfo`.
 
 Typical `sourceInfo.source` values:
@@ -1546,6 +1616,24 @@ Typical `sourceInfo.source` values:
 - `sdk` for tools passed via `createAgentSession({ customTools })`
 - extension source metadata for tools registered by extensions
 
+### pi.invokeHarnessTool(name, args, options?)
+
+Execute a registered tool as a **harness-originated** call — one the harness makes itself, not one the model requested. The tool runs through the identical prepare/execute/finalize pipeline as a model tool call: it produces the same live `tool_execution_*`/message events, persisted session entries, and `tool_call`/`tool_result` hooks, but emits **no** run/turn framing (`agent_start`/`turn_*`/`agent_end`), so it is invisible to `agent_end`-keyed logic. The tool is resolved from the full registry, so a `"harness-only"` tool (never provider-visible) can still be executed. When the agent is idle the call executes immediately; mid-run it is queued and drained before the next intra-run LLM call.
+
+```typescript
+// Record a harness-originated event as a real, replayable tool row, then proceed only once it exists.
+await pi.invokeHarnessTool("my_notice_tool", { text: "model changed to X" });
+// The tool-result row is now persisted in the session transcript.
+```
+
+The returned promise **resolves only after the resulting tool-result message has been persisted** to the session — a stronger guarantee than "the tool ran". A consumer that must not replace or tear down the session (e.g. before starting a fresh session) until the record row exists can safely `await` it. The promise **rejects** if no tool with `name` is registered, if a matching event fails to process/persist, if the session is disposed before it settles or is called after disposal, or if an explicit `options.toolCallId` is malformed or already pending. Rejection means the pipeline did not complete — it does **not** prove the artifact is absent (state and persistence may have partially completed), so do not blindly retry. A tool's own `execute()` error is not a rejection: it resolves normally as an `isError` result.
+
+New invocations also reject during manual compaction ownership, before allocating an id or persistence acknowledgement or executing a tool. Already-admitted active-run/queued invocations drain normally; manual compaction refuses existing idle-origin execution rather than pretending `Agent.waitForIdle()` covers it. This session-local admission policy does not guard direct underlying Agent calls.
+
+`options.toolCallId` (optional) sets an explicit tool-call id (must be provider-safe: 1-64 characters of `[a-zA-Z0-9_-]`); a provider-safe id is generated when omitted.
+
+Do not `await` this from work whose return is required for the agent to reach the mid-run drain point or for the event queue to persist the result (a model-callable `execute`, `beforeToolBatch`/`beforeToolCall`/`afterToolCall`/`prepareNextTurn`, or an awaited event handler) — that would deadlock. Start the promise, return from the gating callback, and await it from an independent continuation.
+
 ### pi.setModel(model)
 
 Set the current model. Returns `false` if no API key is available for the model. See [models.md](models.md) for configuring custom models.
@@ -1798,7 +1886,13 @@ pi.registerTool({
 });
 ```
 
-**Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
+**Signaling errors:** Throw an error from `execute`, or return `isError: true` alongside `content` and `details`. Returned failures retain their structured details and are reported to the LLM as errors. Omitted `isError` preserves normal success; `tool_result` hooks may still override the final error flag.
+
+**Reported cost:** Results and `onUpdate` partials may include `cost: number`, the invocation's cumulative reported USD including descendants but excluding the requesting assistant. Each finite, nonnegative report replaces the previous amount; zero is authoritative, omission is not a new report, and malformed values are ignored. The latest reported cost survives a final result that omits it and `tool_result` content/details patches; hooks cannot override cost through their patch interface. On an execution throw, the latest cost-bearing partial's details and cost accompany the error text, even after a content-only update. On an after-tool hook failure, executed accounting-bearing details and cost accompany the error text. Neither failure inherits a termination hint. Non-accounting throws retain their existing empty-details behavior.
+
+**Historical cost interpretation:** A tool definition may supply synchronous, read-only `getHistoricalCost(details: unknown): number | undefined` to recover costs from older saved details. It must tolerate untrusted historical data, return only a finite nonnegative amount or `undefined`, and never execute work or call a renderer. It stays on the definition, not the executable Agent tool; consumers own aggregation and prefer valid generic message cost, including zero, over this fallback. `AgentSession.getRecordedSessionCost()` and the default footer include all journal assistant/tool costs plus live reports awaiting final append. The interpreter remains available on discovered definitions even when a tool is inactive or excluded by the execution allowlist, following the same definition collision winners without enabling execution. Missing definitions cannot recover legacy schemas. Interpreter exceptions use the extension error channel and do not break presentation.
+
+Session accounting captures scalar reports before asynchronous event hooks. A final `message_end` replacement can change tool content/details but cannot override the captured cost. Live cost transfers to recorded cost only after a successful append; append failure retains the observation in memory and uses existing persistence/settlement error reporting, without automatic retry or a durability claim. Disposal clears live ownership; ordinary abort does not discard it. Compaction/tree navigation retain whole-journal recorded totals, and forks count only copied records. This does not redefine `/session`, RPC statistics, or custom footers.
 
 **Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](../examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
 
@@ -2151,6 +2245,16 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
 - Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
 - Custom footers (setFooter)
 
+### Retained viewport and input ownership
+
+InteractiveMode uses the existing component presentation in an alternate-screen retained viewport. Ordinary `render(width)`, tool `renderCall`/`renderResult`, result/session schemas and HTML export contracts are unchanged. Render the complete logical text rather than clipping it to terminal height. Components receive terminal width minus the reserved scrollbar column; images alone may use the optional `setViewportHeight` bound. Standard Container/Box propagate it; custom image wrappers must forward it. Unrecognized custom graphics envelopes display a placeholder rather than an unsafe clipped placement.
+
+`ctx.ui.onTerminalInput()` listeners run after the viewport listener. They do not receive consumed pointer packets, selection-copy keys, Ctrl+Home/Ctrl+End transcript navigation or detached PageUp/PageDown/Escape when the input owner permits viewport navigation. Ordinary Home/End pass through for editor line-start/end behavior. Do not use raw listeners to compete for transcript pointer ownership. Focused overlays keep keyboard precedence, and conflicting selector bindings precede configurable Alt+PageUp/Alt+PageDown transcript actions. Focus-in/out reports are consumed rather than delivered as ordinary input. The viewport keeps no session-journal state; session reconstruction discards browsing/selection state.
+
+The input area is docked by default, with widgets preserving their above/below-editor placement. Docking can change live without replacing component instances. Non-fitting extension content remains reachable in an explained undocked retained flow. Custom editors can implement `setHeightLimit(limits)`, where the callback returns `{ rows, text }` for the current total input budget and maximum wrapped text rows. Respect the budget without losing draft content, keep the cursor and active completion choice visible, and use the effective text-window height for paging. This is separate from the image-only `setViewportHeight` API. Editors with completion menus can also expose optional `isShowingAutocomplete(): boolean`; InteractiveMode then reveals a hidden editor slot independently of its hardware cursor and consumes acceptance until the slot is visible and its current paint has flushed. Built-in `CustomEditor` inherits this capability. See [tui.md](tui.md#retained-viewport-api) for projection, selection and geometry contracts.
+
+Kitty-capable viewport terminals explicitly encode printable keys as well as modified keys. Match actions against raw input with `matchesKey()`/the injected keybinding manager before using `decodeKittyPrintable(data) ?? data` for printable-mode mappings; decoding first can obscure special-key identities such as keypad Enter. Do not assume a printable key is one raw byte. Raw listeners must ignore `isKeyRelease(data)` unless they intentionally handle releases; focused components filter releases by default. The shipped [modal editor](../examples/extensions/modal-editor.ts) demonstrates the printable-key migration. No blanket compatibility claim is made for external raw-byte listeners or graphics wrappers; see [tui.md](tui.md) for exact viewport APIs and [terminal-setup.md](terminal-setup.md#native-compatibility-evidence) for tested configurations.
+
 ### Dialogs
 
 ```typescript
@@ -2369,18 +2473,18 @@ See [github-issue-autocomplete.ts](../examples/extensions/github-issue-autocompl
 For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
 
 ```typescript
-import { Text, Component } from "@leanandmean/tui";
+import { Text } from "@leanandmean/tui";
 
-const result = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
+const result = await ctx.ui.custom<boolean>((_tui, _theme, keybindings, done) => {
   const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);
-
-  text.onKey = (key) => {
-    if (key === "return") done(true);
-    if (key === "escape") done(false);
-    return true;
+  return {
+    render: (width) => text.render(width),
+    invalidate: () => text.invalidate(),
+    handleInput(data) {
+      if (keybindings.matches(data, "tui.select.confirm")) done(true);
+      else if (keybindings.matches(data, "tui.select.cancel")) done(false);
+    },
   };
-
-  return text;
 });
 
 if (result) {
@@ -2394,6 +2498,28 @@ The callback receives:
 - `keybindings` - App keybinding manager (for checking shortcuts)
 - `done(value)` - Call to close component and return value
 
+Ordinary editor-slot custom UI can opt into actual layout allocation with `ctx.ui.custom(factory, { onAvailableHeight(rows) { maximumRows = rows; } })`, where `maximumRows` is invocation-local state read during rendering. The callback receives `undefined` at mounting/release and a numeric row budget before each allocated render; it can run more than once per frame. It must not request another render or change focus, and allocation does not certify docking, visibility or flushing. Retained undocked rendering can allocate rows too; committed rendering has no numeric allocation. Below-minimum geometry skips rendering rather than delivering a temporary budget, and recovery supplies a fresh allocation. Other components are unchanged unless they explicitly opt in. The option is incompatible with overlays and tool-attached context and is rejected before the factory runs; it is separate from image-only `setViewportHeight` and editor text-height preferences. Allocation-notification errors reject the owning custom UI request and release/dispose its control; release-notification errors are reported without stranding completion. See [allocated custom input height](tui.md#allocated-custom-input-height).
+
+A pending sequential tool can attach immutable long-form context to its own tool row before compact controls become interactive. Pass the current `toolCallId` from the tool's `execute()` method:
+
+```typescript
+const result = await ctx.ui.custom(
+  (_tui, _theme, _keybindings, done) => new ApprovalSelector(done),
+  {
+    toolAttachedContext: {
+      toolCallId,
+      render: (_tui, theme) => new Text(theme.fg("muted", completeContext), 0, 0),
+    },
+  },
+);
+```
+
+The complete immutable context is installed at that pending tool's transcript position. In both renderer modes, the editor is defocused and a required initial flush must succeed before controls receive focus. Missing/non-leading/settled tool rows, context replaced before that flush settles, and missing or failed flushing reject the request through attachment cleanup. Context is visual-only, not persisted or sent to the model. Use this only from the sequential tool whose id is supplied.
+
+In default **retained mode**, the context remains browseable through Scramjet's scrollbar even when taller than the screen; it need not all be simultaneously visible or emitted into native scrollback. Controls require current-paint flush evidence, complete rendering of the full context and controls, and whole-control visibility. Clipped context (including offscreen rows) or controls that cannot fit fail closed. If browsing hides controls, the first activation reveals and flushes them without approving; only subsequent input can authorize. Attachment currentness and these presentation guards are rechecked on input.
+
+With startup-only **`tuiMode: "committed"`**, `commitNow({ requireFlush: true })` emits the complete context into committed native history and waits for the initial flush before focusing controls. The mutable canvas remains tail-windowed; this mode does **not** provide Scramjet scrollbar access, retained render-completeness/whole-control-visibility checks, or reveal-before-subsequent-activation protection. Do not rely on those retained-only guarantees when supporting committed compatibility mode.
+
 See [tui.md](tui.md) for the full component API.
 
 #### Overlay Mode (Experimental)
@@ -2438,7 +2564,7 @@ class VimEditor extends CustomEditor {
       this.mode = "normal";
       return;
     }
-    if (this.mode === "normal" && data === "i") {
+    if (this.mode === "normal" && matchesKey(data, "i")) {
       this.mode = "insert";
       return;
     }
@@ -2541,14 +2667,14 @@ const highlighted = highlightCode(code, lang, theme);
 
 - Extension errors are logged, agent continues
 - `tool_call` errors block the tool (fail-safe)
-- Tool `execute` errors must be signaled by throwing; the thrown error is caught, reported to the LLM with `isError: true`, and execution continues
+- Tool `execute` errors may be signaled by throwing or returning `isError: true`; failures are reported to the LLM and execution continues unless the finalized batch explicitly terminates
 
 ## Mode Behavior
 
 | Mode | UI Methods | Notes |
 |------|-----------|-------|
 | Interactive | Full TUI | Normal operation |
-| RPC (`--mode rpc`) | JSON protocol | Host handles UI, see [rpc.md](rpc.md) |
+| RPC (`--mode rpc`) | JSON protocol | Host handles supported UI methods; TUI-only `custom()` resolves `undefined`, see [rpc.md](rpc.md) |
 | JSON (`--mode json`) | No-op | Event stream to stdout, see [json.md](json.md) |
 | Print (`-p`) | No-op | Extensions run but can't prompt |
 

package/docs/json.md

@@ -6,6 +6,12 @@ scramjet --mode json "Your prompt"
 
 Outputs all session events as JSON lines to stdout. Useful for integrating Scramjet into other tools or custom UIs.
 
+## Invocation-scoped models and failures
+
+`--mode json` accepts `--model-definition '<JSON>'` or `--model-definition-env NAME` for a process-local compatible route. See [the complete contract](models.md#invocation-scoped-headless-models) for required deployment-evidenced limits, strict environment credentials, conflicts and persistence. The definition is not automatically activated by ambient environment variables.
+
+Invalid definition/environment input fails startup with nonzero status. Generation failures may still exit zero in JSON mode: inspect finalized assistant `message_end` entries for `stopReason: "error"`/`"aborted"`, their `errorMessage`/diagnostics, and retry outcomes rather than treating process exit or `agent_end` as success. Explicit request failures do not silently switch routes; existing same-route recovery remains. Text print errors retain nonzero status; [RPC](rpc.md) separately distinguishes prompt acceptance from generation success. No new event shape or exit policy is introduced.
+
 ## Event Types
 
 Events are defined in [`AgentSessionEvent`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/agent-session.ts#L102):
@@ -55,6 +61,8 @@ Extended messages from [`packages/coding-agent/src/core/messages.ts`](https://gi
 - `BranchSummaryMessage` (line 55)
 - `CompactionSummaryMessage` (line 62)
 
+Tool execution updates (`partialResult.cost`), execution-end results (`result.cost`), and final `toolResult` messages (`message.cost`) may carry optional finite, nonnegative cumulative invocation USD, including descendants but excluding the requesting assistant. Reports replace prior amounts rather than representing additional expenditures; zero is authoritative and omission is not a new report. Final costs remain present for reported failures (`isError: true`). These are additive fields in JSON and RPC events; closed-schema clients must allow them. Existing tools may omit them.
+
 ## Output Format
 
 Each line is a JSON object. The first line is the session header:

package/docs/keybindings.md

@@ -1,6 +1,6 @@
 # Keybindings
 
-All keyboard shortcuts can be customized via `~/.scramjet/agent/keybindings.json`. Each action can be bound to one or more keys.
+Action keybindings can be customized via `~/.scramjet/agent/keybindings.json`. Each action can be bound to one or more keys.
 
 The config file uses the same namespaced keybinding ids that Scramjet uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
 
@@ -20,8 +20,30 @@ After editing `keybindings.json`, run `/reload` in Scramjet to apply the changes
 
 Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1`, etc.
 
+## Transcript browsing precedence
+
+Interactive mode's retained viewport owns mouse wheel/trackpad scrolling, the rightmost draggable scrollbar and ordinary drag selection. Right-click a nonempty selection or use `tui.input.copy` (Ctrl+C by default) to copy displayed text. Without a transcript selection, the same key keeps its focused-component/application behavior. Escape clears selection and returns to the live tail.
+
+While detached from the tail with the editor owning input, the viewport consumes this fixed set before editor bindings; focused selectors retain their own navigation and cancellation bindings:
+
+| Key | Browsing action |
+|-----|-----------------|
+| PageUp / PageDown | Scroll one viewport page |
+| Escape | Return to the live tail |
+
+Home/End retain editor line-start/end behavior at every transcript position. Ctrl+Home goes to the transcript beginning and Ctrl+End goes to its bottom and resumes following, whether currently following or detached. Docked input and configured tool/thinking presentation toggles preserve the transcript anchor; undocked ordinary editing reveals the editor cursor. Submitting nonempty editor input resumes following before command routing or queueing, including Enter and Alt+Enter. New user-message delivery also resumes following; passive output does not. At the tail, unmodified paging retains its editor/list meanings. Focused overlays take precedence, and focused selector bindings take precedence over both fixed and configurable viewport actions. In particular, Escape cancels a focused settings selector rather than merely returning its transcript to the tail. If tool-attached approval controls are hidden by browsing, the first activation reveals and flushes them without approving; a later activation can approve.
+
+The fixed detached-only keys above remain separate from `tui.viewport.pageUp` and `tui.viewport.pageDown`, which default to Alt+PageUp and Alt+PageDown and work from the tail as well as while browsing. Terminal/desktop interception can require remapping these configurable actions. See [terminal-setup.md](terminal-setup.md#transcript-browsing-and-copying) for terminal-menu and clipboard requirements.
+
 ## All Actions
 
+### Transcript Navigation
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `tui.viewport.pageUp` | `alt+pageUp` | Browse one transcript page upward, including from the tail |
+| `tui.viewport.pageDown` | `alt+pageDown` | Browse one transcript page downward |
+
 ### TUI Editor Cursor Movement
 
 | Keybinding id | Default | Description |
@@ -114,6 +136,8 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
 | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
 
+`app.thinking.cycle` also works while Scramjet next-step and structured confirm/select dialogs are open. Those dialogs display the usable configured shortcut, apply effort changes immediately, and retain them when cancelled. Dialog navigation, confirmation, cancellation, and next-step model arrows take precedence if bindings conflict; freetext and headless interactions are unchanged.
+
 ### Display and Message Queue
 
 | Keybinding id | Default | Description |

package/docs/models.md

@@ -4,6 +4,7 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.scram
 
 ## Table of Contents
 
+- [Invocation-scoped Headless Models](#invocation-scoped-headless-models)
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Supported APIs](#supported-apis)
@@ -14,6 +15,72 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.scram
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
+## Invocation-scoped Headless Models
+
+Use one model definition for a single headless invocation without editing `models.json` or installing an extension:
+
+- `--model-definition '<JSON>'` supplies strict JSON directly.
+- `--model-definition-env NAME` reads strict JSON from the named environment variable only when explicitly selected.
+
+Both selectors accept `=value` forms. Missing values, repeated selectors, using both selectors, or combining either with `--provider`, `--model`, `--models` or `--api-key` are errors. Ambient definition variables alone never activate a route. Use `--thinking` separately: the model `id` is a nonblank literal backend ID, preserving case, slashes and colons without fuzzy matching, provider-prefix parsing or thinking-suffix interpretation.
+
+Supported execution modes are `--print`, `--mode json`, `--mode rpc`, and print mode selected by redirected stdin. Actual interactive execution is rejected. Help/version need no credentials; `--list-models` can inspect a supplied definition without resolving its credential.
+
+### Definition fields
+
+| Field | Requirement and meaning |
+|-------|-------------------------|
+| `api` | Required: `openai-completions`, `openai-responses`, `anthropic-messages`, or `google-generative-ai` |
+| `baseUrl` | Required absolute HTTP(S) URL with a host; no userinfo, query, fragment, controls or whitespace. Supply the adapter-appropriate base path; there is no endpoint/version discovery. |
+| `id` | Required nonblank literal backend model ID |
+| `apiKeyEnv` | Required environment variable identifier containing a nonblank credential at startup |
+| `contextWindow` | Required positive finite maximum supported total context; positive fractional values remain accepted |
+| `maxTokens` | Required positive safe-integer maximum output allowance |
+| `name` | Optional nonempty label; defaults to `id` |
+| `reasoning` | Optional boolean; defaults to `false` |
+| `input` | Optional array of `text`/`image` modalities; defaults to `["text"]` |
+| `thinkingLevelMap` | Optional existing [thinking-level mapping](#thinking-level-map) |
+| `compat` | Optional existing API-valid [OpenAI](#openai-compatibility) or [Anthropic](#anthropic-messages-compatibility) compatibility overrides; API-incompatible fields are rejected |
+| `cost` | Optional complete finite-number `input`, `output`, `cacheRead`, `cacheWrite` estimates per million tokens; defaults to zero estimates |
+| `maxInputTokens` | Optional positive finite independent input constraint, evidenced for the supplied route |
+| `requestLimits` | Optional nonempty array of existing [joint endpoint constraints](#joint-endpoint-constraints) |
+
+Unknown fields, including nested unsupported keys/values, are rejected. Credential literals, headers, provider identity, OAuth, custom stream functions, provider collections/overrides, file references and discovery configuration are not supported. JSON comments and trailing commas are rejected; input is never loaded from a file or evaluated as a shell command.
+
+Obtain limits and capabilities from the actual deployment's applicable documentation/account metadata. `contextWindow` stays the total-context denominator; input constraints and output allocation remain separate. Output need not be less than total context: existing request-local allocation bounds feasible output without changing either scalar maximum. These estimates/checks do not establish backend acceptance, entitlement or exact serialized token counts. Omitted capabilities are client defaults, not capability evidence; zero cost estimates do not mean free billing. Existing adapter compatibility defaults still apply.
+
+### Example using caller deployment metadata
+
+For a deployment confirmed to implement Chat Completions, set `DEPLOYMENT_BASE_URL`, `DEPLOYMENT_MODEL_ID`, `DEPLOYMENT_CONTEXT_WINDOW` and `DEPLOYMENT_MAX_OUTPUT` from its metadata, and export `ROUTE_API_KEY` from your credential source. Then, using `jq` to construct JSON:
+
+```sh
+export ROUTE_DEFINITION="$(jq -n \
+  --arg baseUrl "$DEPLOYMENT_BASE_URL" \
+  --arg id "$DEPLOYMENT_MODEL_ID" \
+  --argjson contextWindow "$DEPLOYMENT_CONTEXT_WINDOW" \
+  --argjson maxTokens "$DEPLOYMENT_MAX_OUTPUT" \
+  '{api:"openai-completions",baseUrl:$baseUrl,id:$id,apiKeyEnv:"ROUTE_API_KEY",contextWindow:$contextWindow,maxTokens:$maxTokens}')"
+scramjet --print --model-definition-env ROUTE_DEFINITION "Summarize this project"
+# Equivalent inline selector, without putting the credential in JSON:
+scramjet --mode json --model-definition "$ROUTE_DEFINITION" "Summarize this project"
+```
+
+Both environment names must be valid identifiers with nonblank values. The credential is captured once, preserving its bytes; it is never interpreted as a shell command, second variable name or literal fallback. Missing credentials fail startup instead of borrowing saved/provider credentials. For an unauthenticated server, the caller may supply a nonblank placeholder in the named credential variable; Scramjet does not invent one. Definition metadata, including the URL, is nonsecret and normally visible through RPC/model output. Controlled input errors omit raw JSON, rejected URL contents and credential values; arbitrary remote echoes and trusted extensions are not covered by a universal redaction guarantee.
+
+### Lifetime, selection and persistence
+
+Each invocation registers a fresh non-vendor `invocation-<UUID>` provider identity in memory and selects its exact model, bypassing saved startup defaults and scopes. Discover this generated identity through RPC `get_state`/`get_available_models`; concurrent invocations using the same backend ID remain independent. Credentials stay in runtime auth overrides, not model metadata or configuration.
+
+Refresh/reload retain the registration. Replacement registries re-register the same captured definition/key. `new_session` inherits the live model/thinking after a deliberate switch; non-inherited session switch/fork/import selection uses the supplied definition. Explicit later model switching remains allowed: this is not a route lock or protection against arbitrary trusted extensions. No automatic forwarding of the complete route to subagents is provided.
+
+All sessions created by a definition invocation opt out of saving model/thinking defaults, including later setters/cycling, replacements and switches to other models. Live state, events and ordinary journal model/thinking entries still change. Auth/model configuration remains unchanged; unrelated settings, journals and observational files may still be written. Use `--no-session` to disable journal saving, not as a general filesystem sandbox.
+
+Endpoints/keys/limits are not revived from journal model identity. Resupply the definition in each fresh process. Reopening without selectors uses ordinary unavailable-model restoration warnings and default/available-model fallback; it is **not** fail-closed ordinary resume. An explicit invocation startup records its effective branch-local model/thinking identity using existing journal shapes.
+
+Invalid definition/environment input fails before migrations/runtime construction with nonzero status. Explicit registration or request failures do not silently select a substitute route; existing retries/compaction may retry the same selected route. Text generation failures report errors and nonzero status. JSON generation errors can accompany exit zero: inspect finalized assistant error events. RPC prompt acceptance is not generation success: inspect subsequent events. See [JSON](json.md), [RPC](rpc.md) and [SDK preference persistence](sdk.md#model-preference-persistence).
+
+`google-generative-ai` explicitly pins the generic API even when `GOOGLE_GENAI_USE_VERTEXAI` or `GOOGLE_GENAI_USE_ENTERPRISE` is set. This also applies to configured/dynamic models and direct generic AI streams. Vertex routing requires the existing explicit `google-vertex` API/configuration, which is outside invocation-definition support. Compatibility with every enterprise endpoint is not established; ambient cloud flags are not a supported migration mechanism.
+
 ## Minimal Example
 
 For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
@@ -91,6 +158,8 @@ Override defaults when you need specific values:
 
 The file reloads each time you open `/model`. Edit during session; no restart needed.
 
+When valid history exists, `/model` and `/scoped-models` append a recent median output-rate estimate to the requested provider/model row. The estimate uses normalized final output usage over first-to-last generated output, excluding time to first token and trailing completion latency; no placeholder is shown for models without history.
+
 ## Google AI Studio Example
 
 Use `google-generative-ai` with a `baseUrl` to add models from Google AI Studio, including custom Gemma 4 entries:
@@ -194,24 +263,54 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
 | `reasoning` | No | `false` | Supports extended thinking |
 | `thinkingLevelMap` | No | omitted | Maps scramjet thinking levels to provider values and marks unsupported levels (see below) |
 | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
-| `contextWindow` | No | `128000` | Context window size in tokens |
+| `contextWindow` | No | `128000` | Maximum supported total context for this provider/model, in tokens |
+| `maxInputTokens` | No | omitted | Genuine independently enforced provider input limit, only when evidenced for this route |
+| `requestLimits` | No | omitted | Non-empty array of provider-declared joint endpoint token constraints (see below) |
 | `maxTokens` | No | `16384` | Maximum output tokens |
 | `cost` | No | all zeros | `{"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}` (per million tokens) |
 | `compat` | No | provider `compat` | Provider compatibility overrides. Merged with provider-level `compat` when both are set. |
 
+`contextWindow` is the sole total-context authority for usage percentages, the footer, listings, and compaction. Do not reduce it for pricing, presumed quality, or speculative conservatism. `maxTokens` is an independent output allowance; configurable compaction reserves remain separate. Custom-model defaults are client defaults, not evidence of your backend's maximum—set the actual deployment value.
+
+Final `contextWindow` and any `maxInputTokens` must be positive finite numbers after configuration merges, dynamic registration, and OAuth transformations; positive fractional context values remain accepted. An input constraint above total context is non-binding, not a reason to increase total context. Only assign input constraints from applicable provider evidence, never by subtracting maximum output or copying an old budget. Aggregate endpoint maxima may not be jointly available under custom routing or account restrictions. OpenRouter generation reads endpoint input constraints and retains the largest permitted input across all reported routes, only when that is independently below total context. A route without a separate input limit contributes its total context, not a guessed output reservation. Empty endpoint lists provide no input-limit evidence. This does not guarantee that the maximum input, output, tools, and other requested capabilities are jointly available on one endpoint.
+
+### Joint endpoint constraints
+
+`requestLimits` preserves input/output combinations that independent scalar maxima cannot express. Each entry has required positive finite `maxTotalTokens` and boolean `supportsTools`, plus optional positive finite `maxInputTokens` and `maxOutputTokens`. These are endpoint request constraints, not another model context denominator. Omitted input/output fields add no independent bound; they are not output reservations or proof of unlimited backend capacity. An absent array adds no joint check; an empty or malformed array is rejected at configuration, dynamic/OAuth registration, and Faux boundaries.
+
+For example, a long-context endpoint can accept 98,304 input tokens but only 8,192 output tokens, while another endpoint allows longer output only within a 40,960-token total. Coding-agent sessions and both built-in summarizers filter these declarations by estimated input and required tool support, then cap explicit output at the largest remaining allowance from a compatible entry. They reject requests with no compatible entry rather than selecting a provider, truncating the prompt, or globally reducing `contextWindow` or `maxTokens`. Ordinary OpenRouter output remains omitted when not explicitly requested. Direct AI streams and ordinary standalone Agent/AgentHarness streams do not automatically run this allocation; their callers own request constraints.
+
+OpenRouter and Vercel generation deduplicates equivalent declarations and omits joint metadata when a tool-capable endpoint already admits the entire scalar envelope. Empty or unavailable discovery is not a verified envelope. These declarations do not encode custom routing preferences, account restrictions, modalities, or every requested capability, and do not guarantee provider acceptance. If changing the route, supply applicable constraints through an override or replace the model definition rather than assuming inherited declarations describe the new backend. Overrides replace the entire array, not individual entries.
+
+### Breaking migration from context budgets
+
+`contextWindowBudget` and the exported `getContextWindowBudget()` resolver have been removed, without aliases. Replace resolver calls and usage-budget reads with `contextWindow`; `ContextUsage` is now `{ tokens, percent, contextWindow }`. Remove the obsolete key from model definitions, `models.json` overrides, dynamic providers, Faux definitions, and OAuth-produced models—even when it equals total context. Registration/configuration diagnostics identify the provider/model and explain removal. No user files are rewritten and no old value is automatically copied into `contextWindow` or `maxInputTokens`.
+
+Invalid configuration retains built-ins while rejecting its request settings; an invalid OAuth transformation is diagnosed and its untransformed candidate models remain. This preserves existing fallback behavior, not a guarantee that requests are blocked until configuration is repaired.
+
+Built-in metadata is not proof of endpoint acceptance. The provider audit in [issue #525](https://github.com/LeanAndMean/scramjet/issues/525) retains unresolved numerical/route dispositions, including some Codex maxima and aggregate input/output combinations; retained values are not newly verified by this migration. Tests use static metadata and synthetic usage, not paid maximum-context requests. Built-in `cost` values are scalar usage **estimates**, not billing guarantees: the September 2026 refresh reused same-route Pi or prior catalog values where source cache prices were absent. A zero estimate is not proof that a provider bills nothing for cache activity; check the applicable provider/account pricing when monetary accuracy matters. Some built-in model IDs retired or disappeared from both the live source and upstream Pi; a missing feed entry does not prove a custom deployment or account has retired it. Removed IDs no longer appear in selectors: saved selections may fall back to another available model, a configured default that no longer resolves reports the missing ID and chosen fallback at startup, unmatched scopes are skipped, and `modelOverrides` cannot recreate an absent built-in. If a custom deployment still serves one, define it in `models.json` with applicable API, limits and cost metadata, then update saved selections and scopes rather than assuming an alias. An Azure Responses listing for `gpt-realtime-2.1` was removed from an intermediate PR head (it was absent from the committed baseline). Azure Responses GPT-6 Astra, Luna and Sol are now built-ins because Microsoft's own Responses model list, model-limit table and deployment-tier pricing supply route-specific evidence; direct OpenAI limits and prices were not used as Azure proof. Azure region and deployment entitlement still vary. See the [built-in catalog provenance](../../ai/catalog-provenance.md) for dated sources, scoped removal groups, retentions, and exclusions.
+
+GPT-6 Astra through the public OpenAI API stores the standard scalar rates of $10 input, $50 output, $1 cache read, and $12.50 cache write per million tokens. Requests above 272,000 input tokens use higher rates for the whole request, which the current scalar estimator cannot represent, so its monetary estimate may be too low while its token counts remain valid. The September 2026 refresh likewise uses the current [OpenAI base-tier prices](https://developers.openai.com/api/docs/pricing) for public GPT-5.6 Sol ($4/$20 input/output), Terra ($2/$12) and Luna ($0.20/$1.20) per million tokens; their long-context tiers can cost more without reducing their 1.05M total context. The `openai-codex` and `github-copilot` records carry scalar values only as usage estimates; those subscription providers do not imply marginal per-request API charges.
+
+`openai-codex/gpt-6-sol` and `/gpt-6-luna` use the Codex OAuth route and its published 872K maximum context, not the direct API's 1.05M. Codex's public model catalog does not declare their maximum output; their 128K `maxTokens` values are an explicitly authorized, **provisional** reuse of the direct-API allowance, not a verified Codex-route ceiling. Scalar dollar costs likewise proxy public API usage, not Codex subscription credits or account entitlement. `gpt-5.4` and `gpt-5.4-mini` retired from Codex with ChatGPT sign-in; saved Codex selections of either ID may fall back, with a warning where enabled, but direct OpenAI remains a distinct route. Google's Vertex-specific audit added six tool-capable 3.x models and removed its two documented-retired 2.0 models; the 3.6–3.8 Flash introductory rates expire after December 2026. See the [route audit](../../ai/catalog-provenance.md#hand-maintained-and-derived-route-audit-2026-09-24) for source and retention qualifications.
+
+The GitHub Copilot records for `gpt-6-sol`, `gpt-6-luna`, and `claude-opus-5.5` use models.dev and an authenticated individual-account Copilot `GET /models` response observed on 2026-09-23. Where those sources conflicted, the account-scoped Copilot route governed: each record uses 1,000,000 total context, an independent 872,000 input limit, and a 128,000 output limit. These are metadata observations, not paid invocation or maximum-boundary acceptance tests.
+
+GitHub Copilot catalog visibility requires configured Copilot authentication, but a listed model is not proof that the current account is entitled to use it or that the endpoint will accept a request. Copilot prices are scalar default/low-context usage estimates for a subscription route, not guaranteed marginal charges, and cannot encode separately reported long-context tiers. Grok's separate long-context rates likewise cannot be represented by the scalar estimator, so estimates for long requests may be too low while token counts remain valid.
+
 Current behavior:
 - `/model` and `--list-models` list entries by model `id`.
 - The configured `name` is used for model matching and detail/status text.
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are scramjet thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are scramjet thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`.
 
 Values are tristate:
 
 | Value | Meaning |
 |-------|---------|
-| omitted | Level is supported and uses the provider's default mapping |
+| omitted | Ordinary levels use the provider's default mapping; `xhigh` and `max` require explicit string mappings to be supported |
 | string | Level is supported and this value is sent to the provider |
 | `null` | Level is unsupported and hidden/skipped/clamped away |
 
@@ -305,7 +404,7 @@ Use `modelOverrides` to customize specific built-in models without replacing the
 }
 ```
 
-`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`.
+`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxInputTokens`, `requestLimits`, `maxTokens`, `headers`, `compat`.
 
 Behavior notes:
 - `modelOverrides` are applied to built-in provider models.

package/docs/packages.md

@@ -38,6 +38,8 @@ scramjet update --extension npm:@foo/bar
 
 By default, `install` and `remove` write to global settings (`~/.scramjet/agent/settings.json`). Use `-l` to write to project settings (`.scramjet/settings.json`) instead. Project settings can be shared with your team, and scramjet installs any missing packages automatically on startup.
 
+For a globally package-manager-managed CLI, self-update resolves one current npm release, installs that exact package version with the owning package manager, and verifies the managed package metadata before reporting success. This verification does not inspect or repair duplicate installations selected through `PATH`.
+
 To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
 
 ```bash

package/docs/prompt-templates.md

@@ -4,6 +4,8 @@
 
 Prompt templates are Markdown snippets that expand into full prompts. Type `/name` in the editor to invoke a template, where `name` is the filename without `.md`.
 
+A template expansion is an ordinary user prompt, not a Scramjet command. It does not receive `<scramjet-command>` framing, command lifecycle association, declared next-step behavior, or a guarantee that the agent must execute it as an active command. Skills are on-demand capability packages rather than ordinary prompt expansions, but they likewise do not carry the Scramjet command guarantee. When template-derived information supports an active command, that command's explicit Goals (or inferred outcomes for a legacy command), user decisions, trust boundaries, consumer contracts, and required side effects remain controlling. See the [Scramjet command authoring guide](../../scramjet/docs/command-authoring.md) for the command contract.
+
 ## Locations
 
 Scramjet loads prompt templates from: