@leanandmean/coding-agent 0.74.1-scramjet.6 → 0.74.1-scramjet.60

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,11 +1013,13 @@ 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.
@@ -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,22 @@ 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.
+
+`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.
@@ -2151,6 +2237,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 +2465,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 +2490,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 +2556,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;
     }
@@ -2548,7 +2666,7 @@ const highlighted = highlightCode(code, lang, theme);
 | 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/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

@@ -91,6 +91,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,11 +196,41 @@ 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.
@@ -305,7 +337,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:

package/docs/quickstart.md

@@ -73,10 +73,7 @@ Scramjet loads context files at startup. Add an `AGENTS.md` file to tell it how
 - Keep responses concise.
 ```
 
-Scramjet loads:
-
-- `~/.scramjet/agent/AGENTS.md` for global instructions
-- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
+Scramjet loads `CLAUDE.md` and `AGENTS.md` from the global agent directory, parent directories, and the current directory. Within each directory, `CLAUDE.md` loads first. If both files there decode to exactly equal text, only `CLAUDE.md` is loaded; equal text in different directories remains independently loaded.
 
 Restart scramjet, or run `/reload`, after changing context files.
 

package/docs/rpc.md

@@ -61,7 +61,7 @@ With images:
 - `"steer"`: Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call.
 - `"followUp"`: Wait until the agent finishes. Message is delivered only when agent stops.
 
-If the agent is streaming and no `streamingBehavior` is specified, the command returns an error.
+If the agent is streaming and no `streamingBehavior` is specified, the command returns an error. During automatic-retry backoff, when the agent is not streaming but the retry chain is still active, a new prompt is rejected; send `abort_retry` before starting unrelated work.
 
 **Extension commands**: If the message is an extension command (e.g., `/mycommand`), it executes immediately even during streaming. Extension commands manage their own LLM interaction via `pi.sendMessage()`.
 
@@ -263,7 +263,7 @@ List all configured models.
 {"type": "get_available_models"}
 ```
 
-Response contains an array of full [Model](#model) objects:
+Response contains an array of full [Model](#model) objects. `RpcClient.getAvailableModels()` types these as `ModelInfo`, including optional `maxInputTokens`; there is no runtime projection:
 ```json
 {
   "type": "response",
@@ -323,8 +323,8 @@ Control how steering messages (from `steer`) are delivered.
 ```
 
 Modes:
-- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls
-- `"one-at-a-time"`: Deliver one steering message per completed assistant turn (default)
+- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls (default)
+- `"one-at-a-time"`: Deliver one steering message per completed assistant turn
 
 Response:
 ```json
@@ -408,7 +408,7 @@ Response:
 
 #### abort_retry
 
-Abort an in-progress retry (cancel the delay and stop retrying).
+Abort an in-progress retry, whether it is waiting in backoff or running the retry continuation.
 
 ```json
 {"type": "abort_retry"}
@@ -533,7 +533,7 @@ Response:
 }
 ```
 
-`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.
+`tokens` contains assistant usage totals for the current session state. `contextUsage.contextWindow` is maximum supported total context and the denominator of `percent`. Compaction uses this same context value with the configured reserve. `contextWindowBudget` has been removed from both model and usage transport contracts; clients must read `contextWindow` instead. See [models.md](models.md#breaking-migration-from-context-budgets).
 
 `contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.
 
@@ -1227,6 +1227,8 @@ Source files:
 }
 ```
 
+`contextWindow` is maximum supported total context. An optional `maxInputTokens` represents only an independently evidenced provider input constraint; it is not another context denominator. The removed budget field is not emitted.
+
 ### UserMessage
 
 ```json

package/docs/sdk.md

@@ -93,6 +93,9 @@ interface AgentSession {
   cycleModel(): Promise<ModelCycleResult | undefined>;
   cycleThinkingLevel(): ThinkingLevel | undefined;
 
+  // Harness-originated tool execution (resolves after the tool-result is persisted)
+  invokeHarnessTool(name: string, args: unknown, options?: { toolCallId?: string }): Promise<void>;
+
   // State access
   agent: Agent;
   model: Model | undefined;
@@ -117,6 +120,8 @@ interface AgentSession {
 
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
+`invokeHarnessTool(name, args, options?)` runs a registered tool as a harness-originated call (not model-requested) through the real execution pipeline — same events, persistence, and hooks, but no run/turn framing. Its promise resolves only after the resulting tool-result message has been persisted to the session, so a consumer can `await` it before replacing or tearing down the session. It rejects on unknown tool, a matching event failing to persist, disposal before settlement or a call after disposal, or a malformed or duplicate explicit `toolCallId`; rejection does not prove the artifact is absent, so do not blindly retry. A tool's own `execute()` error resolves as an `isError` result rather than rejecting.
+
 ### createAgentSessionRuntime() and AgentSessionRuntime
 
 Use the runtime API when you need to replace the active session and rebuild cwd-bound runtime state.
@@ -360,7 +365,7 @@ const { session } = await createAgentSession({
   - `.scramjet/skills/`
   - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
 - Project prompts (`.scramjet/prompts/`)
-- Context files (`AGENTS.md` walking up from cwd)
+- Context files (`CLAUDE.md` and `AGENTS.md` walking up from cwd)
 - Session directory naming
 
 `agentDir` is used by `DefaultResourceLoader` for:
@@ -369,7 +374,7 @@ const { session } = await createAgentSession({
   - `skills/` under `agentDir` (for example `~/.scramjet/agent/skills/`)
   - `~/.agents/skills/`
 - Global prompts (`prompts/`)
-- Global context file (`AGENTS.md`)
+- Global context files (`CLAUDE.md` and `AGENTS.md`)
 - Settings (`settings.json`)
 - Custom models (`models.json`)
 - Credentials (`auth.json`)
@@ -420,12 +425,24 @@ If no model is provided:
 
 `cacheRetention` controls prompt-cache retention on providers that support it (Anthropic: `long` -> 1h cache TTL where the model supports it, `short` -> the default 5m TTL, `none` -> no caching). Precedence: the `cacheRetention` option (or the `--cache-retention` CLI flag), then the `PI_CACHE_RETENTION` environment variable, then the built-in default `long`. Short-lived sessions such as subagents should pass `short` since a 1h cache write costs more than a 5m one and rarely pays off for a single run.
 
-Scramjet builds the system prompt as ordered sections and isolates the volatile environment tail (current date, working directory) into a final uncached section. On Anthropic, the stable sections are folded into a single system block carrying the cache breakpoint, so the cached prefix survives across turns even though the tail varies between sessions. Extensions can contribute stable sections via `before_agent_start` — see [extensions.md](extensions.md#system-prompt-sections).
+Scramjet builds the system prompt as ordered sections and isolates the volatile environment tail (current date, working directory, session journal path) into a final uncached section. On Anthropic, the stable sections are folded into a single system block carrying the cache breakpoint, so the cached prefix survives across turns even though the tail varies between sessions. Extensions can contribute stable sections via `before_agent_start` — see [extensions.md](extensions.md#system-prompt-sections).
+
+Within one accepted top-level prompt, changing the active tools regenerates the generated tool guidance while preserving that run's `before_agent_start` composition. Contributed sections are reapplied once against the regenerated base; an authoritative `systemPrompt` string remains byte-identical and receives no generated guidance. The same composition remains in effect for intra-run continuations and automatic retries. Each later accepted top-level prompt runs `before_agent_start` against a fresh generated base, and a successful same-session reload clears the prior extension instance's composition before rebuilding the runtime. Tree navigation changes messages only; the next accepted prompt performs the normal fresh composition.
+
+For each built-in provider request, `createAgentSession()` binds the current extension runner when `before_provider_call` begins, then carries that runner through provider-neutral preparation, serialization, payload rewriting, and observation. It also captures a request-local copy of provider-neutral tool names, a bounded routed-model identity (`provider`, `id`, and `api` only), and the run-captured public `Agent.onPayload` callback without changing that callback's signature. Payload processing order is public callback → captured runner's `before_provider_request` chain → immutable `provider_request_tool_inventory` observation → transport. The public callback runs exactly once; `undefined` keeps its input unchanged, while any other return value becomes the input to extension handlers. If successful reload supersedes the captured runner before payload dispatch, the public callback still runs but the old request skips extension rewriting and observation rather than entering the replacement runtime; if replacement occurs while the old runner's chain is already in flight, its completed replacement reaches transport and only observation is suppressed. The wrapper inspects only tool names from the actual final payload and returns that exact same value to transport. Known malformed shapes expose only a bounded reason, custom APIs are `unsupported`, and custom providers that never invoke `onPayload` provide no final-schema proof. The observation does not prove transport or model behavior; see [extensions.md](extensions.md#provider_request_tool_inventory). Because this adds a member to the exported `ExtensionEvent` union, exhaustive TypeScript switches must handle it or include a default/unknown-event branch.
 
 > Before sectioned system prompts landed, the effective default was `short` (the env var could only upgrade it to `long`). Sessions created through the SDK or CLI now default to `long`; set `PI_CACHE_RETENTION=short` or pass `cacheRetention: "short"` to restore the old behavior.
 
 > See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
 
+### Context and output allocation
+
+Models and usage expose one authoritative total `contextWindow`; `contextWindowBudget` and `getContextWindowBudget()` are removed. See [the migration guide](models.md#breaking-migration-from-context-budgets) before updating external model definitions or consumers.
+
+The `createAgentSession()` stream path checks the current request's estimated input against any genuine `maxInputTokens`, then bounds output by remaining total context and the applicable output maximum. It does not subtract compaction reserve again. The same accounting applies to both built-in summarizer implementations. These are approximate checks, not exact serialized-payload tokenization; custom stream functions and later payload rewrites must honor their own constraints.
+
+OpenRouter's implicit aggregate output maximum is omitted because it can exclude the long-context endpoint; explicit summary output limits are retained. Vercel's Anthropic route still requires an output limit. Codex still omits `max_output_tokens`. Aggregate route compatibility is not guaranteed by scalar metadata. Anthropic/Bedrock simple adapters treat explicit `maxTokens` as a combined output ceiling including thinking, rather than increasing it for reasoning.
+
 ### API Keys and OAuth
 
 API key resolution priority (handled by AuthStorage):
@@ -652,6 +669,8 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 ### Context Files
 
+Default discovery loads context broadest-to-most-specific and orders `CLAUDE.md` before `AGENTS.md` within each directory. When both same-directory files decode to exactly equal text, only `CLAUDE.md` is retained; equality suppression never crosses directory boundaries.
+
 ```typescript
 import { createAgentSession, DefaultResourceLoader } from "@leanandmean/coding-agent";
 

package/docs/session-format.md

@@ -81,6 +81,7 @@ interface UserMessage {
 interface AssistantMessage {
   role: "assistant";
   content: (TextContent | ThinkingContent | ToolCall)[];
+  origin?: "provider" | "harness";  // Explicit for new messages; absent in legacy sessions
   api: string;
   provider: string;
   model: string;
@@ -203,7 +204,7 @@ A message in the conversation. The `message` field contains an `AgentMessage`.
 
 ```json
 {"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}
-{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}}
+{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"origin":"provider","provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}}
 {"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2024-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"call_123","toolName":"bash","content":[{"type":"text","text":"output"}],"isError":false}}
 ```