@knightcodeai/cli-darwin-x64 0.6.1 → 0.6.2

package/bin/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @knightcodeai/cli
 
+## 0.6.2
+
+### Added
+
+- Added the Environment Variables reference to the documentation navigation, which previously only reached that page through inline links.
+
+- Added `ctx.modelRegistry.stream()` and `streamSimple()` so extensions can make model calls through configured providers with resolved authentication, including providers registered by extensions.
+
+- Added Ctrl+D as a reliable alternative to Ctrl+S for saving the default model and thinking level. Many terminals (including Windows Terminal) swallow Ctrl+S as XON/XOFF flow control, so the keystroke never reached the app and the default was never saved. Ctrl+S still works where the terminal delivers it.
+
+- Added `compaction.modelOverrides`, per-model `reserveTokens` and `keepRecentTokens` budgets keyed by exact `"provider/modelId"`, so a million-token model can hold a large response reserve without inflating it for every other model. Each field falls back independently to the ordinary setting and then the built-in default, and the resolved values drive manual compaction, threshold checks, overflow recovery, and the `session_before_compact` payload.
+
+### Changed
+
+- Changed the DeepSeek catalog to advertise `deepseek-flash` for DeepSeek V4.1 Flash, which accepts images and reasoning levels, in place of the retired `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` aliases, and refreshed DeepSeek input, output, and cache-read pricing.
+
+- Changed OpenRouter requests to send the `x-session-id` affinity header by default on both Chat Completions and Anthropic-compatible models, so cached prompts keep hitting the same upstream replica; setting `sendSessionAffinityHeaders: false` or disabling prompt caching still opts out.
+
+- Changed the compaction, branch summarization, and retry spinners to render in the editor border alongside the working indicator; custom editors opt in for all four with the same `embedWorkingStatus` flag.
+
+- Changed the runtime dependencies to current releases, including the Anthropic, Bedrock and Google GenAI SDKs, the proxy agents, TypeBox, undici, chalk, marked, ignore, minimatch, semver, esbuild and grok-mermaid. Google's new `TOO_MANY_TOOL_CALLS` finish reason now maps to an error stop reason.
+
+### Removed
+
+- Removed GPT-5.4 and GPT-5.4 mini from the OpenAI Codex catalog after ChatGPT accounts lost access to them; selecting either now fails at model resolution instead of at the first request.
+
+### Fixed
+
+- Fixed agent-level retry backoff doubling without a ceiling, which left the agent asleep for hours after a long provider outage. Assistant and summarization retries now cap each delay at the new `retry.maxAgentDelayMs` setting, defaulting to 60 seconds.
+
+- Fixed OpenAI Codex requests omitting the reasoning effort when thinking is off, so models that need an explicit Off level fell back to the provider default; the model's mapped Off effort is now sent, and models that map Off to `null` still send nothing.
+
+- Fixed GitHub Copilot GPT models other than GPT-5 being routed to the completions endpoint, which Copilot does not serve them from.
+
+- Fixed the event stream draining its buffered events with `Array.shift()`, which made delivery quadratic on long streams; both the event queue and the waiting-consumer queue now use an amortized O(1) FIFO.
+
+- Fixed Fireworks Messages models losing their thinking blocks on replay and collapsing native reasoning effort to a budget-based fallback; the catalog now takes effort levels from provider metadata, allows unsigned thinking, and stops advertising GLM 5.2 and Kimi K3 aliases that map onto the same level.
+
+- Fixed Mistral-hosted GLM-5.2 reasoning requests sending `prompt_mode`, which that model ignores, so thinking never turned on; they now send `reasoning_effort`.
+
+- Fixed Mistral Medium reasoning requests sending the unsupported `prompt_mode` instead of `reasoning_effort` for reasoning-capable `mistral-medium-*` model IDs such as `mistral-medium-latest`.
+
+- Fixed OpenCode and OpenCode Go requests dropping the `x-opencode-session` routing header; every API adapter now maps `sessionId` onto it while leaving an explicit caller override alone.
+
+- Fixed extension tools registered without an object parameter schema being accepted, which broke provider request serialization later; registration now rejects them with an error naming the tool and the extension.
+
+- Fixed steering and follow-up messages bypassing extension `input` handlers, so extensions could neither transform nor intercept a message queued while the agent was already streaming; both paths now run the handlers and carry their real input source.
+
+- Fixed session tree navigation starting while a compaction or another navigation was still running; it now rejects instead of moving the active leaf.
+
+- Fixed a rejected `/tree` navigation replacing the running operation's escape handler and status spinner; the compaction or summarization it collided with now keeps its own UI.
+
+- Fixed the compiled Windows executable inheriting Bun's own PE resources, so `knightcode.exe` shipped with no icon and a `FileDescription` of "Bun" — the string Windows shows as the process name in Task Manager and the taskbar. The win32 build now embeds KnightCode's own title, publisher, copyright, version, and icon.
+
+- Fixed fullscreen mode reserving a blank row for a custom footer that renders nothing.
+
 ## 0.6.1
 
 ### Added

package/bin/docs/compaction.md

@@ -288,7 +288,7 @@ knightcode.on("session_before_compact", async (event, ctx) => {
   // preparation.fileOps - extracted file operations
   // preparation.tokensBefore - context tokens before compaction
   // preparation.firstKeptEntryId - where kept messages start
-  // preparation.settings - compaction settings
+  // preparation.settings - effective settings after applying model overrides
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
@@ -416,3 +416,29 @@ Configure compaction in `~/.knightcode/agent/settings.json` or `<project-dir>/.k
 | `keepRecentTokens` | `20000` | Recent tokens to keep (not summarized) |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
+
+### Per-model overrides
+
+Use `compaction.modelOverrides` to tune token budgets for different models:
+
+```json
+{
+  "compaction": {
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000,
+    "modelOverrides": {
+      "some-provider/big-model": {
+        "reserveTokens": 400000
+      }
+    }
+  }
+}
+```
+
+For a model with a 1M context window, this override triggers compaction above 600K tokens and keeps the ordinary 20000 recent tokens. Other models retain the ordinary 16384-token reserve. `reserveTokens` also influences summarization output limits, capped by the model's maximum output tokens; it is not solely a trigger threshold.
+
+Keys are exact, case-sensitive `provider/modelId` values, including any slashes within the model ID. Each `reserveTokens` and `keepRecentTokens` value falls back independently from the model override to the ordinary setting to the built-in default. Values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. Only omitted ordinary values use built-in defaults. `enabled` remains global, not model-specific.
+
+These resolved values are used for manual compaction, all automatic threshold checks, overflow recovery, and extension-visible `preparation.settings`. Model switches affect subsequent checks and compactions without changing ordinary settings. Compaction already in progress uses the model and settings captured for that operation. Branch summarization settings are unaffected.
+
+Overrides work in both global and project settings. The files merge recursively before lookup, so a global model-specific value beats a project-wide fallback; a project must override that model entry to change it. See [settings.md](settings.md#per-model-compaction-overrides) for details.

package/bin/docs/custom-provider.md

@@ -764,6 +764,7 @@ interface ProviderModelConfig {
     supportsEagerToolInputStreaming?: boolean;
     supportsLongCacheRetention?: boolean;
     sendSessionAffinityHeaders?: boolean;
+    sessionAffinityFormat?: "openrouter";
     supportsCacheControlOnTools?: boolean;
     forceAdaptiveThinking?: boolean;
     allowEmptySignature?: boolean;

package/bin/docs/docs.json

@@ -81,6 +81,10 @@
     {
       "title": "Reference",
       "items": [
+        {
+          "title": "Environment Variables",
+          "path": "environment-variables.md"
+        },
         {
           "title": "Session Format",
           "path": "session-format.md"

package/bin/docs/extensions.md

@@ -1016,6 +1016,12 @@ Access to models, providers, and resolved authentication. `ctx.modelRegistry.get
 
 `ctx.scopedModels` is the read-only list of models scoped to the current session — the same set the `/scoped-models` command shows. It is resolved at session start from the `--models` CLI flag and the `enabledModels` setting (matched against the available catalogue with minimatch on `provider/modelId` or a bare `modelId`). It is empty when no scoping is configured, meaning every available model is usable. Each entry is `{ model, thinkingLevel? }`, where `thinkingLevel` is set only when a pattern pinned it (e.g. `anthropic/*:high`). Use it to populate a model picker that mirrors the built-in one instead of enumerating the whole catalogue via `ctx.modelRegistry.getAvailable()`.
 
+#### Streaming model calls
+
+Use `ctx.modelRegistry.streamSimple(model, context, options)` for provider-neutral options such as `reasoning`, or `stream()` for API-specific options. Both use configured providers and resolve authentication, including for providers registered with `knightcode.registerProvider()`. Use these instead of `@knightcode/ai/compat` streaming functions, which cannot see extension provider registrations.
+
+Both return an `AssistantMessageEventStream`. Iterate it for response events and await `.result()` for the final message. Setup failures produce error events and error results.
+
 ### ctx.signal
 
 The current agent abort signal, or `undefined` when no agent turn is active.
@@ -1197,7 +1203,7 @@ Options:
 
 ### ctx.navigateTree(targetId, options?)
 
-Navigate to a different point in the session tree:
+Navigate to a different point in the session tree. Rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. These conflicts leave the active branch unchanged and reject the promise rather than returning `{ cancelled: true }`. Wait for the active operation to finish (for example, with `await ctx.waitForIdle()` in a command handler) and retry:
 
 ```typescript
 const result = await ctx.navigateTree("entry-id-456", {

package/bin/docs/index.md

@@ -15,7 +15,7 @@ npm install -g --ignore-scripts @knightcodeai/cli
 On Linux or macOS, you can also use the installer:
 
 ```bash
-curl -fsSL https://knightcode.raghavseth.in/install.sh | sh
+curl -fsSL https://knightcode.dev/install.sh | sh
 ```
 
 To uninstall knightcode itself, use npm for curl and npm installs:

package/bin/docs/keybindings.md

@@ -151,9 +151,9 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.model.select` | `ctrl+l` | Open model selector |
 | `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
 | `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
-| `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
+| `app.models.save` | `ctrl+s`, `ctrl+d` | Save the selected default model or scoped model configuration to settings (`ctrl+d` because many terminals swallow `ctrl+s`) |
 | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
-| `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
+| `app.thinking.save` | `ctrl+s`, `ctrl+d` | Save current thinking level to settings (`ctrl+d` because many terminals swallow `ctrl+s`) |
 | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
 
 ### Display and Message Queue

package/bin/docs/models.md

@@ -429,7 +429,8 @@ Built-in Anthropic models enable `supportsStrictTools` in their model metadata.
 |-------|-------------|
 | `supportsEagerToolInputStreaming` | Whether the provider accepts per-tool `eager_input_streaming`. Default: `true`. Set to `false` to omit that field and use the legacy fine-grained tool streaming beta header on tool-enabled requests. |
 | `supportsLongCacheRetention` | Whether the provider accepts Anthropic long cache retention (`cache_control.ttl: "1h"`) when cache retention is `long`. Default: `true`. |
-| `sendSessionAffinityHeaders` | Whether to send `x-session-affinity` from the session id when caching is enabled. Default: auto-detected for known providers. |
+| `sendSessionAffinityHeaders` | Whether to send a session-affinity header from the session id when caching is enabled. Default: `true` for OpenRouter endpoints, auto-detected for other known providers. |
+| `sessionAffinityFormat` | Session-affinity header name: `openrouter` sends `x-session-id`. When unset, `x-session-affinity` is sent. Default: `openrouter` for OpenRouter endpoints. |
 | `supportsCacheControlOnTools` | Whether the provider accepts Anthropic-style `cache_control` markers on tool definitions. Default: `true`. |
 | `forceAdaptiveThinking` | Whether to send adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) for this model. Built-in adaptive models set this automatically. Default: `false`. |
 | `supportsMidConvoEffort` | Whether the exact Claude model transport supports per-turn effort system messages and thinking binding controls. KnightCode persists native effort levels and always sends `drop_block` when enabled. Default: `false`. |
@@ -477,7 +478,7 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `thinkingTokenBudgetField` | Top-level request field used to cap reasoning tokens from `thinkingBudgets`, clamped so at least 1024 tokens remain for the answer. `"thinking_token_budget"` (vLLM), `"thinking_budget"` (Qwen/DashScope/SGLang), `"thinking_budget_tokens"` (llama.cpp). Off by default; not set on the generated catalog. |
 | `supportsThinkingTokenBudget` | Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: `false`. |
 | `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. |
-| `sendSessionAffinityHeaders` | For `openai-completions`, send session-affinity headers from the session id when caching is enabled. Default: `false`. |
+| `sendSessionAffinityHeaders` | For `openai-completions`, send session-affinity headers from the session id when caching is enabled. Default: `true` for OpenRouter endpoints, `false` otherwise. |
 | `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
 | `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
 | `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |

package/bin/docs/packages.md

@@ -134,7 +134,7 @@ Paths are relative to the package root. Arrays support glob patterns and `!exclu
 
 ### Gallery Metadata
 
-The [package gallery](https://knightcode.raghavseth.in/packages) displays packages tagged with `knightcode-package`. Add `video` or `image` fields to show a preview:
+The [package gallery](https://knightcode.dev/packages) displays packages tagged with `knightcode-package`. Add `video` or `image` fields to show a preview:
 
 ```json
 {

package/bin/docs/quickstart.md

@@ -129,7 +129,7 @@ The command output is sent to the model. Use `!!command` to run a command withou
 
 ### Switch models
 
-Use `/model` or Ctrl+L to choose a model for the current session. Press Ctrl+S in the model picker to save the highlighted model as the startup default. Use `/thinking` to choose a thinking level for the current session, or Ctrl+S in that picker to save the startup default thinking level. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
+Use `/model` or Ctrl+L to choose a model for the current session. Press Ctrl+S (or Ctrl+D, if your terminal swallows Ctrl+S) in the model picker to save the highlighted model as the startup default. Use `/thinking` to choose a thinking level for the current session, or Ctrl+S / Ctrl+D in that picker to save the startup default thinking level. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
 
 ### Continue later
 

package/bin/docs/sdk.md

@@ -111,6 +111,8 @@ interface AgentSession {
 }
 ```
 
+`session.navigateTree()` rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. It does not queue navigation or return `{ cancelled: true }` for these conflicts. Wait for the active operation to finish (for example, with `await session.waitForIdle()`) and retry. Rejection leaves the active branch unchanged.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime

package/bin/docs/session-format.md

@@ -5,10 +5,10 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
 ## File Location
 
 ```
-~/.knightcode/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
+~/.knightcode/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl
 ```
 
-Where `<path>` is the working directory with `/` replaced by `-`.
+By default, `<session-id>` is a UUID. Callers can supply a custom ID through the SDK or `--session-id`. For `<path>`, KnightCode removes the leading path separator and replaces `/`, `\\`, and `:` with `-`.
 
 ## Deleting Sessions
 
@@ -29,8 +29,8 @@ Existing sessions are automatically migrated to the current version (v3) when lo
 ## Source Files
 
 Source on GitHub ([knightcode](https://github.com/KnightCodeAI/knightcode)):
-- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
-- [`packages/coding-agent/src/core/messages.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
+- [`packages/cli/src/core/session-manager.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/session-manager.ts) - Session entry types and SessionManager
+- [`packages/cli/src/core/messages.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/cli/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
 - [`packages/ai/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
 - [`packages/agent/src/types.ts`](https://github.com/KnightCodeAI/knightcode/blob/main/packages/agent/src/types.ts) - AgentMessage union type
 
@@ -48,6 +48,7 @@ Messages contain arrays of typed content blocks:
 interface TextContent {
   type: "text";
   text: string;
+  textSignature?: string;
 }
 
 interface ImageContent {
@@ -59,6 +60,8 @@ interface ImageContent {
 interface ThinkingContent {
   type: "thinking";
   thinking: string;
+  thinkingSignature?: string;
+  redacted?: boolean;
 }
 
 interface ToolCall {
@@ -66,6 +69,8 @@ interface ToolCall {
   id: string;
   name: string;
   arguments: Record<string, any>;
+  thoughtSignature?: string;
+  namespace?: string;
 }
 ```
 
@@ -84,9 +89,16 @@ interface AssistantMessage {
   api: string;
   provider: string;
   model: string;
+  responseModel?: string;
+  responseId?: string;
+  providerThinkingLevel?: string;
+  diagnostics?: AssistantMessageDiagnostic[];
   usage: Usage;
-  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
+  stopReason: "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
+  deferred?: DeferredHandle;
   errorMessage?: string;
+  rawStopReason?: string;
+  endTurn?: boolean;
   timestamp: number;
 }
 
@@ -97,6 +109,7 @@ interface ToolResultMessage {
   content: (TextContent | ImageContent)[];
   details?: any;      // Tool-specific metadata
   usage?: Usage;      // Nested LLM work performed by the tool
+  addedToolNames?: string[];
   isError: boolean;
   timestamp: number;
 }
@@ -106,6 +119,8 @@ interface Usage {
   output: number;
   cacheRead: number;
   cacheWrite: number;
+  cacheWrite1h?: number;
+  reasoning?: number;
   totalTokens: number;
   cost: {
     input: number;
@@ -117,7 +132,7 @@ interface Usage {
 }
 ```
 
-The exported @knightcode/ai `StopReason` type also includes `"pending"`, but that value is reserved for partial messages in streaming events. Terminal `done`/`error` messages replace it with a completion reason before knightcode persists the assistant message, so `"pending"` should never appear in session JSONL.
+`"pending"` is reserved for partial messages in streaming events. Terminal events replace it with a completion reason before knightcode persists the assistant message, so `"pending"` should never appear in session JSONL. `"deferred"` is a terminal reason for a provider response that will complete later; its `deferred` handle contains the provider data needed to retrieve that response.
 
 ### Extended Message Types (from @knightcodeai/cli)
 
@@ -146,7 +161,7 @@ interface CustomMessage {
 interface BranchSummaryMessage {
   role: "branchSummary";
   summary: string;
-  fromId: string;                // Entry we branched from
+  fromId: string | null;         // Previous leaf whose abandoned path was summarized
   timestamp: number;
 }
 
@@ -178,8 +193,8 @@ All entries (except `SessionHeader`) extend `SessionEntryBase`:
 ```typescript
 interface SessionEntryBase {
   type: string;
-  id: string;           // 8-char hex ID
-  parentId: string | null;  // Parent entry ID (null for first entry)
+  id: string;           // Usually an 8-char hex ID; may fall back to a full UUID
+  parentId: string | null;  // Parent entry ID (null for a root entry)
   timestamp: string;    // ISO timestamp
 }
 ```
@@ -205,9 +220,9 @@ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ pare
 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":"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}}
+{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello","timestamp":1733234401000}}
+{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"api":"anthropic-messages","provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop","timestamp":1733234402000}}
+{"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,"timestamp":1733234403000}}
 ```
 
 ### ModelChangeEntry
@@ -234,18 +249,12 @@ Created when context is compacted. Stores a summary of earlier messages.
 {"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
 ```
 
-Newer harness-generated compactions embed the retained post-compaction context directly on the entry, instead of `firstKeptEntryId`:
-
-```json
-{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","tokensBefore":50000,"retainedTail":[{"role":"user","content":"latest request"},{"role":"assistant","content":[{"type":"text","text":"latest reply"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}]}
-```
+`firstKeptEntryId` is required. It identifies the first entry retained from before the compaction entry. When rebuilding context, KnightCode replaces older summarized entries with the compaction summary and keeps the range beginning at this entry.
 
 Optional fields:
 - `usage`: LLM usage from generating the summary; included in session token and cost totals
-- `retainedTail`: Materialized `AgentMessage[]` kept after compaction. This is optional only for backward compatibility with older sessions. Newer harness-generated compactions include it so we can rebuild context from this checkpoint without walking older entries before the compaction entry.
 - `details`: Implementation-specific data (e.g., `{ readFiles: string[], modifiedFiles: string[] }` for default, or custom data for extensions)
 - `fromHook`: `true` if generated by an extension, `false`/`undefined` if knightcode-generated (legacy field name)
-- `firstKeptEntryId`: for compatibility with old entry format.
 
 ### BranchSummaryEntry
 
@@ -255,6 +264,8 @@ Created when switching branches via `/tree` with an LLM generated summary of the
 {"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:15:00.000Z","fromId":"f6g7h8i9","summary":"Branch explored approach A..."}
 ```
 
+`parentId` is the entry from which the new branch continues. `fromId` is the previous leaf whose abandoned path was summarized.
+
 Optional fields:
 - `usage`: LLM usage from generating the summary; included in session token and cost totals
 - `details`: File tracking data (`{ readFiles: string[], modifiedFiles: string[] }`) for default, or custom data for extensions
@@ -305,11 +316,12 @@ The session name is displayed in the session selector (`/resume`) instead of the
 
 ## Tree Structure
 
-Entries form a tree:
-- First entry has `parentId: null`
-- Each subsequent entry points to its parent via `parentId`
+Entries normally form one tree, but navigation APIs can create multiple roots:
+- A root entry has `parentId: null`; the first entry is initially the root
+- Each non-root entry points to its parent via `parentId`
 - Branching creates new children from an earlier entry
 - The "leaf" is the current position in the tree
+- Calling `resetLeaf()` or `branchWithSummary(null, ...)` allows a later entry to become another root
 
 ```
 [user msg] ─── [assistant] ─── [user msg] ─── [assistant] ─┬─ [user msg] ← current leaf
@@ -322,11 +334,10 @@ Entries form a tree:
 `buildContextEntries()` walks from the current leaf to the root, producing the active entry list while honoring compaction:
 
 1. Collects all entries on the path
-2. If a `CompactionEntry` is on the path:
+2. If one or more `CompactionEntry` values are on the path, uses the latest one:
    - Includes the compaction entry first
-   - If `retainedTail` is present, it acts as a self-contained checkpoint and entries after the compaction are included
-   - Otherwise entries from `firstKeptEntryId` to the compaction are included
-   - Then entries after compaction are included
+   - Includes entries from `firstKeptEntryId` up to, but not including, the compaction entry
+   - Includes entries after the compaction entry
 3. Preserves non-message entries in the selected range so interactive mode can render them
 
 `buildSessionContext()` builds on that entry list to produce the message list for the LLM:
@@ -334,12 +345,12 @@ Entries form a tree:
 1. Extracts current model and thinking level settings from the full path
 2. Converts selected entries to messages:
    - `message` -> stored `AgentMessage`
-   - `compaction` -> `compactionSummary` plus `retainedTail` when present
+   - `compaction` -> `compactionSummary`
    - `branch_summary` -> `branchSummary`
    - `custom_message` -> `CustomMessage`
    - `custom` -> no context message
 
-This makes newer compactions act like self-contained checkpoints. `retainedTail` is optional only so older sessions that only store `firstKeptEntryId` continue to load correctly.
+The compaction summary replaces entries before `firstKeptEntryId`. The retained entries and all entries after the compaction remain available to the LLM.
 
 ## Parsing Example
 
@@ -388,18 +399,19 @@ for (const line of lines) {
 Key methods for working with sessions programmatically.
 
 ### Static Creation Methods
-- `SessionManager.create(cwd, sessionDir?)` - New session
-- `SessionManager.open(path, sessionDir?)` - Open existing session file
+- `SessionManager.create(cwd, sessionDir?, options?)` - New session; `options` can set `id` and `parentSession`
+- `SessionManager.open(path, sessionDir?, cwdOverride?)` - Open existing session file
 - `SessionManager.continueRecent(cwd, sessionDir?)` - Continue most recent or create new
-- `SessionManager.inMemory(cwd?)` - No file persistence
-- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?)` - Fork session from another project
+- `SessionManager.inMemory(cwd?, options?, entries?)` - No file persistence, optionally initialized from entries
+- `SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?, options?)` - Fork session from another project
 
 ### Static Listing Methods
 - `SessionManager.list(cwd, sessionDir?, onProgress?)` - List sessions for a directory
 - `SessionManager.listAll(onProgress?)` - List all sessions across all projects
+- `SessionManager.listAll(sessionDir?, onProgress?)` - List sessions from a custom session root
 
 ### Instance Methods - Session Management
-- `newSession(options?)` - Start a new session (options: `{ parentSession?: string }`)
+- `newSession(options?)` - Start a new session (options: `{ id?: string, parentSession?: string }`)
 - `setSessionFile(path)` - Switch to a different session file
 - `createBranchedSession(leafId)` - Extract branch to new session file
 
@@ -407,7 +419,7 @@ Key methods for working with sessions programmatically.
 - `appendMessage(message)` - Add message
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?)` - Add compaction
+- `appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?, usage?)` - Add compaction
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)
@@ -423,7 +435,7 @@ Key methods for working with sessions programmatically.
 - `getLabel(id)` - Get label for entry
 - `branch(entryId)` - Move leaf to earlier entry
 - `resetLeaf()` - Reset leaf to null (before any entries)
-- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
+- `branchWithSummary(entryId, summary, details?, fromHook?, usage?)` - Branch with context summary; `entryId` may be `null` to branch from the root
 
 ### Instance Methods - Context & Info
 - `buildContextEntries()` - Get active branch entries with compaction applied

package/bin/docs/sessions.md

@@ -70,6 +70,8 @@ Named sessions are easier to find in `/resume` and `knightcode -r`.
 
 Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
 
+Selecting a point while the model is responding cancels that response. Navigation cannot proceed while compaction or another tree navigation is still running; wait for it to finish and retry.
+
 <p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
 
 Example shape:

package/bin/docs/settings.md

@@ -66,7 +66,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
-| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
+| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Fullscreen captures the mouse and owns text selection, so dragging copies to the clipboard; regular leaves selection and copying to the terminal emulator (see [Text selection and copy](terminal-setup.md#text-selection-and-copy)). Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
 | `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` prints the final transcript and resume hint, while `"resume-hint"` restores the previous screen and prints only the resume hint. Has no effect in regular TUI mode |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling or while the pointer is over its rightmost-column track, `"always"` reserves that column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
 | `fullscreenCopyOnSelect` | boolean | `true` | Automatically copy selected text in fullscreen mode. When disabled, selections stay highlighted and `Ctrl+X` copies the active selection. Has no effect in regular TUI mode |
@@ -81,7 +81,7 @@ For VS Code, include `--wait` so knightcode resumes after the editor exits:
 
 ### Telemetry and update checks
 
-`enableInstallTelemetry` controls the anonymous install/update ping to `https://knightcode.raghavseth.in/api/report-install` and KnightCode attribution headers for OpenRouter, NVIDIA NIM, and Cloudflare provider requests. Opting out disables both. It does not disable update checks; KnightCode can still fetch `https://knightcode.raghavseth.in/api/latest-version` to look for the latest version.
+`enableInstallTelemetry` controls the anonymous install/update ping to `https://knightcode.dev/api/report-install` and KnightCode attribution headers for OpenRouter, NVIDIA NIM, and Cloudflare provider requests. Opting out disables both. It does not disable update checks; KnightCode can still fetch `https://knightcode.dev/api/latest-version` to look for the latest version.
 
 Set `KNIGHTCODE_SKIP_VERSION_CHECK=1` to disable the KnightCode version update check. Use `--offline` or `KNIGHTCODE_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
 
@@ -118,6 +118,7 @@ Set `KNIGHTCODE_SKIP_VERSION_CHECK=1` to disable the KnightCode version update c
 | `compaction.enabled` | boolean | `true` | Enable auto-compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for LLM response |
 | `compaction.keepRecentTokens` | number | `20000` | Recent tokens to keep (not summarized) |
+| `compaction.modelOverrides` | object | - | Per-model `reserveTokens` and `keepRecentTokens` overrides keyed by exact `"provider/modelId"` |
 
 ```json
 {
@@ -129,6 +130,37 @@ Set `KNIGHTCODE_SKIP_VERSION_CHECK=1` to disable the KnightCode version update c
 }
 ```
 
+#### Per-model compaction overrides
+
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "reserveTokens": 16384,
+    "keepRecentTokens": 20000,
+    "modelOverrides": {
+      "some-provider/big-model": {
+        "reserveTokens": 400000
+      },
+      "local/small-model": {
+        "reserveTokens": 2048,
+        "keepRecentTokens": 4096
+      }
+    }
+  }
+}
+```
+
+Keys match exact, case-sensitive `provider/modelId` values, not names or glob patterns. Model IDs may contain slashes (for example, `openrouter/anthropic/claude-sonnet-4`).
+
+Each token setting resolves independently: matching model override → ordinary `compaction` setting → built-in default. In the example, `some-provider/big-model` keeps the ordinary 20000 recent tokens. Token values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. Only omitted ordinary values use built-in defaults. Zero is accepted, but `reserveTokens: 0` leaves no response margin and also sets the summarization output budget to zero.
+
+Global and project settings merge recursively **before** model lookup. A project can override one field for a model without replacing its other fields or other models. A global model-specific value takes precedence over a project-wide fallback; override the same model entry in the project to change it.
+
+`enabled` is not model-specific. The active model's token settings apply to manual compaction, automatic threshold checks (including between assistant turns), and overflow recovery. Switching models takes effect on the next check or compaction. Configure overrides in JSON; `/settings` retains the ordinary auto-compaction toggle.
+
+See [compaction.md](compaction.md) for trigger and summarization behavior.
+
 ### Branch Summary
 
 | Setting | Type | Default | Description |
@@ -143,10 +175,13 @@ Set `KNIGHTCODE_SKIP_VERSION_CHECK=1` to disable the KnightCode version update c
 | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
 | `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
 | `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
+| `retry.maxAgentDelayMs` | number | `60000` | Max agent-level retry delay (60s) |
 | `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
 | `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
 | `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
 
+Agent-level retries use exponential backoff capped by `retry.maxAgentDelayMs`, so long retry runs stay responsive after prolonged outages.
+
 When a provider requests a retry delay longer than `retry.provider.maxRetryDelayMs`, the request fails immediately with an informative error instead of waiting silently. Set it to `0` to disable the limit.
 
 Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before KnightCode sees them, which may block the agent until the provider quota resets in some circumstances.
@@ -157,6 +192,7 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
     "enabled": true,
     "maxRetries": 3,
     "baseDelayMs": 2000,
+    "maxAgentDelayMs": 60000,
     "provider": {
       "timeoutMs": 3600000,
       "maxRetries": 0,

package/bin/docs/terminal-setup.md

@@ -14,6 +14,14 @@ KnightCode auto-detects OSC 8 hyperlinks, inline image protocols, and truecolor.
 
 Settings take precedence over environment variables; unset or `auto` preserves detection. Only force capabilities supported by the complete terminal path, since unsupported escape sequences can corrupt rendering.
 
+## Text Selection and Copy
+
+Which side owns a mouse drag depends on the [TUI mode](usage.md#other-options).
+
+In `fullscreen` mode, knightcode enables mouse reporting and owns text selection itself. Dragging with the primary button selects, and the selection is copied to the clipboard on release. Set `fullscreenCopyOnSelect` to `false` to keep the selection highlighted and copy it with `Ctrl+X` instead. To reach the terminal's own selection while knightcode captures the mouse, hold the terminal's bypass modifier — usually `Shift`, `Option` in iTerm2, and `Shift+Command`/`Shift+Ctrl` in Ghostty.
+
+In `regular` mode, knightcode never enables mouse reporting, so a drag is the terminal emulator's own selection and knightcode is not involved in copying it. Use the terminal's copy shortcut — `Ctrl+Shift+C` on most Linux and Windows terminals, `Command+C` on macOS — or enable the terminal's copy-on-select option. Dragging alone does not reach the clipboard in terminals where that option is off by default, which includes Windows Terminal (`copyOnSelect` defaults to `false`) and Apple Terminal, which has no such option. Switch to `fullscreen` if you want drag-to-copy without depending on the terminal.
+
 ## Kitty
 
 Works out of the box.

package/bin/docs/tui.md

@@ -930,7 +930,7 @@ export default function (knightcode: ExtensionAPI) {
 
 - **Extend `CustomEditor`** (not base `Editor`) to get app keybindings (escape to abort, ctrl+d to exit, model switching, etc.)
 - **Call `super.handleInput(data)`** for keys you don't handle
-- **Working status**: custom editors keep the standalone working row by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to use the built-in editor-border spinner instead.
+- **Status spinners**: custom editors keep standalone status rows by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to embed working, compaction, branch summarization, and retry spinners in the editor border instead.
 - **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
 - **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
 

package/bin/docs/usage.md

@@ -38,8 +38,8 @@ Type `/` in the editor to open command completion. Extensions can register custo
 |---------|-------------|
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
 | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
-| `/model` | Switch models; Ctrl+S in the picker saves the startup default |
-| `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
+| `/model` | Switch models; Ctrl+S or Ctrl+D in the picker saves the startup default |
+| `/thinking` | Switch thinking level; Ctrl+S or Ctrl+D in the picker saves the startup default |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Theme, message delivery, transport, and other preferences |
 | `/resume` | Pick from previous sessions |
@@ -249,7 +249,7 @@ knightcode --no-extensions -e ./my-extension.ts
 | `-h`, `--help` | Show help |
 | `-v`, `--version` | Show version |
 
-In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, knightcode uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. See [Terminal setup](terminal-setup.md) for terminal-specific settings and workarounds.
+In `fullscreen` mode, the transcript scrolls inside the terminal viewport while queued messages, working status, extension widgets, editor, and footer remain fixed at the bottom. Mouse/trackpad input scrolls the region under the pointer; keyboard viewport actions always remain available. Inline images work in terminals that support the Kitty graphics protocol, including Kitty and Ghostty. In iTerm2 they render as text placeholders because its inline-image protocol cannot delete or crop placements during application-owned scrolling. In `regular` mode, knightcode uses the main screen and terminal-owned scrollback, and iTerm2 inline images continue to render normally. Text selection differs between the two modes: fullscreen captures the mouse and owns selection, so dragging copies to the clipboard on release, while regular mode never captures the mouse and leaves both selecting and copying to the terminal emulator. See [Text selection and copy](terminal-setup.md#text-selection-and-copy) for the per-terminal shortcuts, and [Terminal setup](terminal-setup.md) for other terminal-specific settings and workarounds.
 
 Set **TUI mode** in `/settings` to switch between `regular` and `fullscreen` immediately and choose the default for future sessions. **Fullscreen exit output** controls whether exiting fullscreen prints the final transcript or restores the previous screen and prints only the session resume hint.
 

package/bin/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@knightcodeai/cli",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "KnightCode — a local, BYOK terminal coding agent powered by OpenRouter.",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "https://github.com/KnightCodeAI/knightcode.git"
   },
-  "homepage": "https://knightcode.raghavseth.in",
+  "homepage": "https://knightcode.dev",
   "license": "MIT",
   "knightcodeConfig": {
     "configDir": ".knightcode"
@@ -37,11 +37,11 @@
     "test": "vitest --run"
   },
   "optionalDependencies": {
-    "@knightcodeai/cli-linux-x64": "0.6.1",
-    "@knightcodeai/cli-linux-arm64": "0.6.1",
-    "@knightcodeai/cli-darwin-x64": "0.6.1",
-    "@knightcodeai/cli-darwin-arm64": "0.6.1",
-    "@knightcodeai/cli-win32-x64": "0.6.1"
+    "@knightcodeai/cli-linux-x64": "0.6.2",
+    "@knightcodeai/cli-linux-arm64": "0.6.2",
+    "@knightcodeai/cli-darwin-x64": "0.6.2",
+    "@knightcodeai/cli-darwin-arm64": "0.6.2",
+    "@knightcodeai/cli-win32-x64": "0.6.2"
   },
   "devDependencies": {
     "@knightcode/agent": "workspace:*",
@@ -56,19 +56,20 @@
     "@types/hosted-git-info": "3.0.5",
     "@types/proper-lockfile": "4.1.4",
     "@types/semver": "7.7.1",
-    "chalk": "5.6.2",
+    "chalk": "6.0.0",
     "cross-spawn": "7.0.6",
     "diff": "8.0.4",
-    "grok-mermaid": "0.2.2",
+    "grok-mermaid": "0.2.3",
     "highlight.js": "10.7.3",
     "hosted-git-info": "9.0.3",
-    "ignore": "7.0.5",
+    "ignore": "7.0.8",
     "jiti": "2.7.0",
-    "minimatch": "10.2.5",
+    "marked": "18.0.11",
+    "minimatch": "10.2.6",
     "proper-lockfile": "4.1.2",
-    "semver": "7.8.0",
-    "typebox": "1.3.7",
-    "undici": "8.9.0",
+    "semver": "7.8.5",
+    "typebox": "1.3.27",
+    "undici": "8.10.2",
     "yaml": "2.9.0"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knightcodeai/cli-darwin-x64",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "license": "MIT",
   "repository": {
     "type": "git",