@f5xc-salesdemos/xcsh 18.8.2 → 18.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.8.2",
+	"version": "18.10.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -47,12 +47,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.8.2",
-		"@f5xc-salesdemos/pi-agent-core": "18.8.2",
-		"@f5xc-salesdemos/pi-ai": "18.8.2",
-		"@f5xc-salesdemos/pi-natives": "18.8.2",
-		"@f5xc-salesdemos/pi-tui": "18.8.2",
-		"@f5xc-salesdemos/pi-utils": "18.8.2",
+		"@f5xc-salesdemos/xcsh-stats": "18.10.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.10.0",
+		"@f5xc-salesdemos/pi-ai": "18.10.0",
+		"@f5xc-salesdemos/pi-natives": "18.10.0",
+		"@f5xc-salesdemos/pi-tui": "18.10.0",
+		"@f5xc-salesdemos/pi-utils": "18.10.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/src/config/settings-schema.ts

@@ -657,6 +657,17 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"keybindings.chordTimeout": {
+		type: "number",
+		default: 1000,
+		ui: {
+			tab: "interaction",
+			label: "Chord Timeout",
+			description: "Milliseconds to wait for the second key of a chord binding before abandoning it.",
+			submenu: true,
+		},
+	},
+
 	"startup.quiet": {
 		type: "boolean",
 		default: false,

package/src/config/settings.ts

@@ -356,6 +356,17 @@ export class Settings {
 		return this.get("bashInterceptor.patterns");
 	}
 
+	/**
+	 * Get the chord-binding timeout (milliseconds) clamped to the supported range.
+	 * Values outside [200, 5000] are clamped so a malformed config cannot break the
+	 * chord dispatcher (e.g. 0 => never abandon, huge value => leaked state).
+	 */
+	getChordTimeoutMs(): number {
+		const raw = this.get("keybindings.chordTimeout");
+		const value = typeof raw === "number" && Number.isFinite(raw) ? raw : 1000;
+		return Math.min(5000, Math.max(200, Math.round(value)));
+	}
+
 	/**
 	 * Set a model role (helper for modelRoles record).
 	 */

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.8.2",
-	"commit": "b67646bd5096b169019d794fd0f894f2969696d4",
-	"shortCommit": "b67646b",
+	"version": "18.10.0",
+	"commit": "3b8dbd2bf6b06aab98bbe3bacfd48cd341ab8c06",
+	"shortCommit": "3b8dbd2",
 	"branch": "main",
-	"tag": "v18.8.2",
-	"commitDate": "2026-04-22T19:12:35Z",
-	"buildDate": "2026-04-22T19:48:35.804Z",
+	"tag": "v18.10.0",
+	"commitDate": "2026-04-22T21:59:55Z",
+	"buildDate": "2026-04-22T22:25:06.694Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/b67646bd5096b169019d794fd0f894f2969696d4",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.8.2"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/3b8dbd2bf6b06aab98bbe3bacfd48cd341ab8c06",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.10.0"
 };

package/src/internal-urls/docs-index.generated.ts

@@ -51,7 +51,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"sessions/session-tree-plan.md": "---\ntitle: Session Tree Architecture\nsidebar:\n  order: 2\n  label: Tree architecture\n---\n\n# Session tree architecture (current)\n\nReference: [session.md](./session.md)\n\nThis document describes how session tree navigation works today: in-memory tree model, leaf movement rules, branching behavior, and extension/event integration.\n\n## What this subsystem is\n\nThe session is stored as an append-only entry log, but runtime behavior is tree-based:\n\n- Every non-header entry has `id` and `parentId`.\n- The active position is `leafId` in `SessionManager`.\n- Appending an entry always creates a child of the current leaf.\n- Branching does **not** rewrite history; it only changes where the leaf points before the next append.\n\nKey files:\n\n- `src/session/session-manager.ts` — tree data model, traversal, leaf movement, branch/session extraction\n- `src/session/agent-session.ts` — `/tree` navigation flow, summarization, hook/event emission\n- `src/modes/components/tree-selector.ts` — interactive tree UI behavior and filtering\n- `src/modes/controllers/selector-controller.ts` — selector orchestration for `/tree` and `/branch`\n- `src/modes/controllers/input-controller.ts` — command routing (`/tree`, `/branch`, double-escape behavior)\n- `src/session/messages.ts` — conversion of `branch_summary`, `compaction`, and `custom_message` entries into LLM context messages\n\n## Tree data model in `SessionManager`\n\nRuntime indices:\n\n- `#byId: Map<string, SessionEntry>` — fast lookup for any entry\n- `#leafId: string | null` — current position in the tree\n- `#labelsById: Map<string, string>` — resolved labels by target entry id\n\nTree APIs:\n\n- `getBranch(fromId?)` walks parent links to root and returns root→node path\n- `getTree()` returns `SessionTreeNode[]` (`entry`, `children`, `label`)\n  - parent links become children arrays\n  - entries with missing parents are treated as roots\n  - children are sorted oldest→newest by timestamp\n- `getChildren(parentId)` returns direct children\n- `getLabel(id)` resolves current label from `labelsById`\n\n`getTree()` is a runtime projection; persistence remains append-only JSONL entries.\n\n## Leaf movement semantics\n\nThere are three leaf movement primitives:\n\n1. `branch(entryId)`\n   - Validates entry exists\n   - Sets `leafId = entryId`\n   - No new entry is written\n\n2. `resetLeaf()`\n   - Sets `leafId = null`\n   - Next append creates a new root entry (`parentId = null`)\n\n3. `branchWithSummary(branchFromId, summary, details?, fromExtension?)`\n   - Accepts `branchFromId: string | null`\n   - Sets `leafId = branchFromId`\n   - Appends a `branch_summary` entry as child of that leaf\n   - When `branchFromId` is `null`, `fromId` is persisted as `\"root\"`\n\n## `/tree` navigation behavior (same session file)\n\n`AgentSession.navigateTree()` is navigation, not file forking.\n\nFlow:\n\n1. Validate target and compute abandoned path (`collectEntriesForBranchSummary`)\n2. Emit `session_before_tree` with `TreePreparation`\n3. Optionally summarize abandoned entries (hook-provided summary or built-in summarizer)\n4. Compute new leaf target:\n   - selecting a **user** message: leaf moves to its parent, and message text is returned for editor prefill\n   - selecting a **custom_message**: same rule as user message (leaf = parent, text prefills editor)\n   - selecting any other entry: leaf = selected entry id\n5. Apply leaf move:\n   - with summary: `branchWithSummary(newLeafId, ...)`\n   - without summary and `newLeafId === null`: `resetLeaf()`\n   - otherwise: `branch(newLeafId)`\n6. Rebuild agent context from new leaf and emit `session_tree`\n\nImportant: summary entries are attached at the **new navigation position**, not on the abandoned branch tail.\n\n## `/branch` behavior (new session file)\n\n`/branch` and `/tree` are intentionally different:\n\n- `/tree` navigates within the current session file.\n- `/branch` creates a new session branch file (or in-memory replacement for non-persistent mode).\n\nUser-facing `/branch` flow (`SelectorController.showUserMessageSelector` → `AgentSession.branch`):\n\n- Branch source must be a **user message**.\n- Selected user text is extracted for editor prefill.\n- If selected user message is root (`parentId === null`): start a new session via `newSession({ parentSession: previousSessionFile })`.\n- Otherwise: `createBranchedSession(selectedEntry.parentId)` to fork history up to the selected prompt boundary.\n\n`SessionManager.createBranchedSession(leafId)` specifics:\n\n- Builds root→leaf path via `getBranch(leafId)`; throws if missing.\n- Excludes existing `label` entries from copied path.\n- Rebuilds fresh label entries from resolved `labelsById` for entries that remain in path.\n- Persistent mode: writes new JSONL file and switches manager to it; returns new file path.\n- In-memory mode: replaces in-memory entries; returns `undefined`.\n\n## Context reconstruction and summary/custom integration\n\n`buildSessionContext()` (in `session-manager.ts`) resolves the active root→leaf path and builds effective LLM context state:\n\n- Tracks latest thinking/model/mode/ttsr state on path.\n- Handles latest compaction on path:\n  - emits compaction summary first\n  - replays kept messages from `firstKeptEntryId` to compaction point\n  - then replays post-compaction messages\n- Includes `branch_summary` and `custom_message` entries as `AgentMessage` objects.\n\n`session/messages.ts` then maps these message types for model input:\n\n- `branchSummary` and `compactionSummary` become user-role templated context messages\n- `custom`/`hookMessage` become user-role content messages\n\nSo tree movement changes context by changing the active leaf path, not by mutating old entries.\n\n## Labels and tree UI behavior\n\nLabel persistence:\n\n- `appendLabelChange(targetId, label?)` writes `label` entries on the current leaf chain.\n- `labelsById` is updated immediately (set or delete).\n- `getTree()` resolves current label onto each returned node.\n\nTree selector behavior (`tree-selector.ts`):\n\n- Flattens tree for navigation, keeps active-path highlighting, and prioritizes displaying the active branch first.\n- Supports filter modes: `default`, `no-tools`, `user-only`, `labeled-only`, `all`.\n- Supports free-text search over rendered semantic content.\n- `Shift+L` opens inline label editing and writes via `appendLabelChange`.\n\nCommand routing:\n\n- `/tree` always opens tree selector.\n- `/branch` opens user-message selector unless `doubleEscapeAction=tree`, in which case it also uses tree selector UX.\n\n## Extension and hook touchpoints for tree operations\n\nCommand-time extension API (`ExtensionCommandContext`):\n\n- `branch(entryId)` — create branched session file\n- `navigateTree(targetId, { summarize? })` — move within current tree/file\n\nEvents around tree navigation:\n\n- `session_before_tree`\n  - receives `TreePreparation`:\n    - `targetId`\n    - `oldLeafId`\n    - `commonAncestorId`\n    - `entriesToSummarize`\n    - `userWantsSummary`\n  - may cancel navigation\n  - may provide summary payload used instead of built-in summarizer\n  - receives abort `signal` (Escape cancellation path)\n- `session_tree`\n  - emits `newLeafId`, `oldLeafId`\n  - includes `summaryEntry` when a summary was created\n  - `fromExtension` indicates summary origin\n\nAdjacent but related lifecycle hooks:\n\n- `session_before_branch` / `session_branch` for `/branch` flow\n- `session_before_compact`, `session.compacting`, `session_compact` for compaction entries that later affect tree-context reconstruction\n\n## Real constraints and edge conditions\n\n- `branch()` cannot target `null`; use `resetLeaf()` for root-before-first-entry state.\n- `branchWithSummary()` supports `null` target and records `fromId: \"root\"`.\n- Selecting current leaf in tree selector is a no-op.\n- Summarization requires an active model; if absent, summarize navigation fails fast.\n- If summarization is aborted, navigation is cancelled and leaf is unchanged.\n- In-memory sessions never return a branch file path from `createBranchedSession`.\n\n## Legacy compatibility still present\n\nSession migrations still run on load:\n\n- v1→v2 adds `id`/`parentId` and converts compaction index anchor to id anchor\n- v2→v3 migrates legacy `hookMessage` role to `custom`\n\nCurrent runtime behavior is version-3 tree semantics after migration.\n",
 	"sessions/session.md": "---\ntitle: Session Storage and Entry Model\nsidebar:\n  order: 1\n  label: Storage & entry model\n---\n\n# Session Storage and Entry Model\n\nThis document is the source of truth for how coding-agent sessions are represented, persisted, migrated, and reconstructed at runtime.\n\n## Scope\n\nCovers:\n\n- Session JSONL format and versioning\n- Entry taxonomy and tree semantics (`id`/`parentId` + leaf pointer)\n- Migration/compatibility behavior when loading old or malformed files\n- Context reconstruction (`buildSessionContext`)\n- Persistence guarantees, failure behavior, truncation/blob externalization\n- Storage abstractions (`FileSessionStorage`, `MemorySessionStorage`) and related utilities\n\nDoes not cover `/tree` UI rendering behavior beyond semantics that affect session data.\n\n## Implementation Files\n\n- [`src/session/session-manager.ts`](../../packages/coding-agent/src/session/session-manager.ts)\n- [`src/session/messages.ts`](../../packages/coding-agent/src/session/messages.ts)\n- [`src/session/session-storage.ts`](../../packages/coding-agent/src/session/session-storage.ts)\n- [`src/session/history-storage.ts`](../../packages/coding-agent/src/session/history-storage.ts)\n- [`src/session/blob-store.ts`](../../packages/coding-agent/src/session/blob-store.ts)\n\n## On-Disk Layout\n\nDefault session file location:\n\n```text\n~/.xcsh/agent/sessions/--<cwd-encoded>--/<timestamp>_<sessionId>.jsonl\n```\n\n`<cwd-encoded>` is derived from the working directory by stripping leading slash and replacing `/`, `\\\\`, and `:` with `-`.\n\nBlob store location:\n\n```text\n~/.xcsh/agent/blobs/<sha256>\n```\n\nTerminal breadcrumb files are written under:\n\n```text\n~/.xcsh/agent/terminal-sessions/<terminal-id>\n```\n\nBreadcrumb content is two lines: original cwd, then session file path. `continueRecent()` prefers this terminal-scoped pointer before scanning most-recent mtime.\n\n## File Format\n\nSession files are JSONL: one JSON object per line.\n\n- Line 1 is always the session header (`type: \"session\"`).\n- Remaining lines are `SessionEntry` values.\n- Entries are append-only at runtime; branch navigation moves a pointer (`leafId`) rather than mutating existing entries.\n\n### Header (`SessionHeader`)\n\n```json\n{\n  \"type\": \"session\",\n  \"version\": 3,\n  \"id\": \"1f9d2a6b9c0d1234\",\n  \"timestamp\": \"2026-02-16T10:20:30.000Z\",\n  \"cwd\": \"/work/pi\",\n  \"title\": \"optional session title\",\n  \"parentSession\": \"optional lineage marker\"\n}\n```\n\nNotes:\n\n- `version` is optional in v1 files; absence means v1.\n- `parentSession` is an opaque lineage string. Current code writes either a session id or a session path depending on flow (`fork`, `forkFrom`, `createBranchedSession`, or explicit `newSession({ parentSession })`). Treat as metadata, not a typed foreign key.\n\n### Entry Base (`SessionEntryBase`)\n\nAll non-header entries include:\n\n```json\n{\n  \"type\": \"...\",\n  \"id\": \"8-char-id\",\n  \"parentId\": \"previous-or-branch-parent\",\n  \"timestamp\": \"2026-02-16T10:20:30.000Z\"\n}\n```\n\n`parentId` can be `null` for a root entry (first append, or after `resetLeaf()`).\n\n## Entry Taxonomy\n\n`SessionEntry` is the union of:\n\n- `message`\n- `thinking_level_change`\n- `model_change`\n- `compaction`\n- `branch_summary`\n- `custom`\n- `custom_message`\n- `label`\n- `ttsr_injection`\n- `session_init`\n- `mode_change`\n\n### `message`\n\nStores an `AgentMessage` directly.\n\n```json\n{\n  \"type\": \"message\",\n  \"id\": \"a1b2c3d4\",\n  \"parentId\": null,\n  \"timestamp\": \"2026-02-16T10:21:00.000Z\",\n  \"message\": {\n    \"role\": \"assistant\",\n    \"provider\": \"anthropic\",\n    \"model\": \"claude-sonnet-4-5\",\n    \"content\": [{ \"type\": \"text\", \"text\": \"Done.\" }],\n    \"usage\": { \"input\": 100, \"output\": 20, \"cacheRead\": 0, \"cacheWrite\": 0, \"cost\": { \"input\": 0, \"output\": 0, \"cacheRead\": 0, \"cacheWrite\": 0, \"total\": 0 } },\n    \"timestamp\": 1760000000000\n  }\n}\n```\n\n### `model_change`\n\n```json\n{\n  \"type\": \"model_change\",\n  \"id\": \"b1c2d3e4\",\n  \"parentId\": \"a1b2c3d4\",\n  \"timestamp\": \"2026-02-16T10:21:30.000Z\",\n  \"model\": \"openai/gpt-4o\",\n  \"role\": \"default\"\n}\n```\n\n`role` is optional; missing is treated as `default` in context reconstruction.\n\n### `thinking_level_change`\n\n```json\n{\n  \"type\": \"thinking_level_change\",\n  \"id\": \"c1d2e3f4\",\n  \"parentId\": \"b1c2d3e4\",\n  \"timestamp\": \"2026-02-16T10:22:00.000Z\",\n  \"thinkingLevel\": \"high\"\n}\n```\n\n### `compaction`\n\n```json\n{\n  \"type\": \"compaction\",\n  \"id\": \"d1e2f3a4\",\n  \"parentId\": \"c1d2e3f4\",\n  \"timestamp\": \"2026-02-16T10:23:00.000Z\",\n  \"summary\": \"Conversation summary\",\n  \"shortSummary\": \"Short recap\",\n  \"firstKeptEntryId\": \"a1b2c3d4\",\n  \"tokensBefore\": 42000,\n  \"details\": { \"readFiles\": [\"src/a.ts\"] },\n  \"preserveData\": { \"hookState\": true },\n  \"fromExtension\": false\n}\n```\n\n### `branch_summary`\n\n```json\n{\n  \"type\": \"branch_summary\",\n  \"id\": \"e1f2a3b4\",\n  \"parentId\": \"a1b2c3d4\",\n  \"timestamp\": \"2026-02-16T10:24:00.000Z\",\n  \"fromId\": \"a1b2c3d4\",\n  \"summary\": \"Summary of abandoned path\",\n  \"details\": { \"note\": \"optional\" },\n  \"fromExtension\": true\n}\n```\n\nIf branching from root (`branchFromId === null`), `fromId` is the literal string `\"root\"`.\n\n### `custom`\n\nExtension state persistence; ignored by `buildSessionContext`.\n\n```json\n{\n  \"type\": \"custom\",\n  \"id\": \"f1a2b3c4\",\n  \"parentId\": \"e1f2a3b4\",\n  \"timestamp\": \"2026-02-16T10:25:00.000Z\",\n  \"customType\": \"my-extension\",\n  \"data\": { \"state\": 1 }\n}\n```\n\n### `custom_message`\n\nExtension-provided message that does participate in LLM context.\n\n```json\n{\n  \"type\": \"custom_message\",\n  \"id\": \"a2b3c4d5\",\n  \"parentId\": \"f1a2b3c4\",\n  \"timestamp\": \"2026-02-16T10:26:00.000Z\",\n  \"customType\": \"my-extension\",\n  \"content\": \"Injected context\",\n  \"display\": true,\n  \"details\": { \"debug\": false }\n}\n```\n\n### `label`\n\n```json\n{\n  \"type\": \"label\",\n  \"id\": \"b2c3d4e5\",\n  \"parentId\": \"a2b3c4d5\",\n  \"timestamp\": \"2026-02-16T10:27:00.000Z\",\n  \"targetId\": \"a1b2c3d4\",\n  \"label\": \"checkpoint\"\n}\n```\n\n`label: undefined` clears a label for `targetId`.\n\n### `ttsr_injection`\n\n```json\n{\n  \"type\": \"ttsr_injection\",\n  \"id\": \"c2d3e4f5\",\n  \"parentId\": \"b2c3d4e5\",\n  \"timestamp\": \"2026-02-16T10:28:00.000Z\",\n  \"injectedRules\": [\"ruleA\", \"ruleB\"]\n}\n```\n\n### `session_init`\n\n```json\n{\n  \"type\": \"session_init\",\n  \"id\": \"d2e3f4a5\",\n  \"parentId\": \"c2d3e4f5\",\n  \"timestamp\": \"2026-02-16T10:29:00.000Z\",\n  \"systemPrompt\": \"...\",\n  \"task\": \"...\",\n  \"tools\": [\"read\", \"edit\"],\n  \"outputSchema\": { \"type\": \"object\" }\n}\n```\n\n### `mode_change`\n\n```json\n{\n  \"type\": \"mode_change\",\n  \"id\": \"e2f3a4b5\",\n  \"parentId\": \"d2e3f4a5\",\n  \"timestamp\": \"2026-02-16T10:30:00.000Z\",\n  \"mode\": \"plan\",\n  \"data\": { \"planFile\": \"/tmp/plan.md\" }\n}\n```\n\n## Versioning and Migration\n\nCurrent session version: `3`.\n\n### v1 -> v2\n\nApplied when header `version` is missing or `< 2`:\n\n- Adds `id` and `parentId` to each non-header entry.\n- Reconstructs a linear parent chain using file order.\n- Migrates compaction field `firstKeptEntryIndex` -> `firstKeptEntryId` when present.\n- Sets header `version = 2`.\n\n### v2 -> v3\n\nApplied when header `version < 3`:\n\n- For `message` entries: rewrites legacy `message.role === \"hookMessage\"` to `\"custom\"`.\n- Sets header `version = 3`.\n\n### Migration Trigger and Persistence\n\n- Migrations run during session load (`setSessionFile`).\n- If any migration ran, the entire file is rewritten to disk immediately.\n- Migration mutates in-memory entries first, then persists rewritten JSONL.\n\n## Load and Compatibility Behavior\n\n`loadEntriesFromFile(path)` behavior:\n\n- Missing file (`ENOENT`) -> returns `[]`.\n- Non-parseable lines are handled by lenient JSONL parser (`parseJsonlLenient`).\n- If first parsed entry is not a valid session header (`type !== \"session\"` or missing string `id`) -> returns `[]`.\n\n`SessionManager.setSessionFile()` behavior:\n\n- `[]` from loader is treated as empty/nonexistent session and replaced with a new initialized session file at that path.\n- Valid files are loaded, migrated if needed, blob refs resolved, then indexed.\n\n## Tree and Leaf Semantics\n\nThe underlying model is append-only tree + mutable leaf pointer:\n\n- Every append method creates exactly one new entry whose `parentId` is current `leafId`.\n- The new entry becomes the new `leafId`.\n- `branch(entryId)` moves only `leafId`; existing entries remain unchanged.\n- `resetLeaf()` sets `leafId = null`; next append creates a new root entry (`parentId: null`).\n- `branchWithSummary()` sets leaf to branch target and appends a `branch_summary` entry.\n\n`getEntries()` returns all non-header entries in insertion order. Existing entries are not deleted in normal operation; rewrites preserve logical history while updating representation (migrations, move, targeted rewrite helpers).\n\n## Context Reconstruction (`buildSessionContext`)\n\n`buildSessionContext(entries, leafId, byId?)` resolves what is sent to the model.\n\nAlgorithm:\n\n1. Determine leaf:\n   - `leafId === null` -> return empty context.\n   - explicit `leafId` -> use that entry if found.\n   - otherwise fallback to last entry.\n2. Walk `parentId` chain from leaf to root and reverse to root->leaf path.\n3. Derive runtime state across path:\n   - `thinkingLevel` from latest `thinking_level_change` (default `\"off\"`)\n   - model map from `model_change` entries (`role ?? \"default\"`)\n   - fallback `models.default` from assistant message provider/model if no explicit model change\n   - deduplicated `injectedTtsrRules` from all `ttsr_injection` entries\n   - mode/modeData from latest `mode_change` (default mode `\"none\"`)\n4. Build message list:\n   - `message` entries pass through\n   - `custom_message` entries become `custom` AgentMessages via `createCustomMessage`\n   - `branch_summary` entries become `branchSummary` AgentMessages via `createBranchSummaryMessage`\n   - if a `compaction` exists on path:\n     - emit compaction summary first (`createCompactionSummaryMessage`)\n     - emit path entries starting at `firstKeptEntryId` up to the compaction boundary\n     - emit entries after the compaction boundary\n\n`custom` and `session_init` entries do not inject model context directly.\n\n## Persistence Guarantees and Failure Model\n\n### Persist vs in-memory\n\n- `SessionManager.create/open/continueRecent/forkFrom` -> persistent mode (`persist = true`).\n- `SessionManager.inMemory` -> non-persistent mode (`persist = false`) with `MemorySessionStorage`.\n\n### Write pipeline\n\nWrites are serialized through an internal promise chain (`#persistChain`) and `NdjsonFileWriter`.\n\n- `append*` updates in-memory state immediately.\n- Persistence is deferred until at least one assistant message exists.\n  - Before first assistant: entries are retained in memory; no file append occurs.\n  - When first assistant exists: full in-memory session is flushed to file.\n  - Afterwards: new entries append incrementally.\n\nRationale in code: avoid persisting sessions that never produced an assistant response.\n\n### Durability operations\n\n- `flush()` flushes writer and calls `fsync()`.\n- Atomic full rewrites (`#rewriteFile`) write to temp file, flush+fsync, close, then rename over target.\n- Used for migrations, `setSessionName`, `rewriteEntries`, move operations, and tool-call arg rewrites.\n\n### Error behavior\n\n- Persistence errors are latched (`#persistError`) and rethrown on subsequent operations.\n- First error is logged once with session file context.\n- Writer close is best-effort but propagates the first meaningful error.\n\n## Data Size Controls and Blob Externalization\n\nBefore persisting entries:\n\n- Large strings are truncated to `MAX_PERSIST_CHARS` (500,000 chars) with notice:\n  - `\"[Session persistence truncated large content]\"`\n- Transient fields `partialJson` and `jsonlEvents` are removed.\n- If object has both `content` and `lineCount`, line count is recomputed after truncation.\n- Image blocks in `content` arrays with base64 length >= 1024 are externalized to blob refs:\n  - stored as `blob:sha256:<hash>`\n  - raw bytes written to blob store (`BlobStore.put`)\n\nOn load, blob refs are resolved back to base64 for message/custom_message image blocks.\n\n## Storage Abstractions\n\n`SessionStorage` interface provides all filesystem operations used by `SessionManager`:\n\n- sync: `ensureDirSync`, `existsSync`, `writeTextSync`, `statSync`, `listFilesSync`\n- async: `exists`, `readText`, `readTextPrefix`, `writeText`, `rename`, `unlink`, `openWriter`\n\nImplementations:\n\n- `FileSessionStorage`: real filesystem (Bun + node fs)\n- `MemorySessionStorage`: map-backed in-memory implementation for tests/non-persistent sessions\n\n`SessionStorageWriter` exposes `writeLine`, `flush`, `fsync`, `close`, `getError`.\n\n## Session Discovery Utilities\n\nDefined in `session-manager.ts`:\n\n- `getRecentSessions(sessionDir, limit)` -> lightweight metadata for UI/session picker\n- `findMostRecentSession(sessionDir)` -> newest by mtime\n- `list(cwd, sessionDir?)` -> sessions in one project scope\n- `listAll()` -> sessions across all project scopes under `~/.xcsh/agent/sessions`\n\nMetadata extraction reads only a prefix (`readTextPrefix(..., 4096)`) where possible.\n\n## Related but Distinct: Prompt History Storage\n\n`HistoryStorage` (`history-storage.ts`) is a separate SQLite subsystem for prompt recall/search, not session replay.\n\n- DB: `~/.xcsh/agent/history.db`\n- Table: `history(id, prompt, created_at, cwd)`\n- FTS5 index: `history_fts` with trigger-maintained sync\n- Deduplicates consecutive identical prompts using in-memory last-prompt cache\n- Async insertion (`setImmediate`) so prompt capture does not block turn execution\n\nUse session files for conversation graph/state replay; use `HistoryStorage` for prompt history UX.\n",
 	"sessions/ttsr-injection-lifecycle.md": "---\ntitle: TTSR Injection Lifecycle\nsidebar:\n  order: 9\n  label: TTSR injection\n---\n\n# TTSR Injection Lifecycle\n\nThis document covers the current Time Traveling Stream Rules (TTSR) runtime path from rule discovery to stream interruption, retry injection, extension notifications, and session-state handling.\n\n## Implementation files\n\n- [`../src/sdk.ts`](../../packages/coding-agent/src/sdk.ts)\n- [`../src/export/ttsr.ts`](../../packages/coding-agent/src/export/ttsr.ts)\n- [`../src/session/agent-session.ts`](../../packages/coding-agent/src/session/agent-session.ts)\n- [`../src/session/session-manager.ts`](../../packages/coding-agent/src/session/session-manager.ts)\n- [`../src/prompts/system/ttsr-interrupt.md`](../../packages/coding-agent/src/prompts/system/ttsr-interrupt.md)\n- [`../src/capability/index.ts`](../../packages/coding-agent/src/capability/index.ts)\n- [`../src/extensibility/extensions/types.ts`](../../packages/coding-agent/src/extensibility/extensions/types.ts)\n- [`../src/extensibility/hooks/types.ts`](../../packages/coding-agent/src/extensibility/hooks/types.ts)\n- [`../src/extensibility/custom-tools/types.ts`](../../packages/coding-agent/src/extensibility/custom-tools/types.ts)\n- [`../src/modes/controllers/event-controller.ts`](../../packages/coding-agent/src/modes/controllers/event-controller.ts)\n\n## 1. Discovery feed and rule registration\n\nAt session creation, `createAgentSession()` loads all discovered rules and constructs a `TtsrManager`:\n\n```ts\nconst ttsrSettings = settings.getGroup(\"ttsr\");\nconst ttsrManager = new TtsrManager(ttsrSettings);\nconst rulesResult = await loadCapability<Rule>(ruleCapability.id, { cwd });\nfor (const rule of rulesResult.items) {\n  if (rule.ttsrTrigger) ttsrManager.addRule(rule);\n}\n```\n\n### Pre-registration dedupe behavior\n\n`loadCapability(\"rules\")` deduplicates by `rule.name` with first-wins semantics (higher provider priority first). Shadowed duplicates are removed before TTSR registration.\n\n### `TtsrManager.addRule()` behavior\n\nRegistration is skipped when:\n\n- `rule.ttsrTrigger` is absent\n- a rule with the same `rule.name` was already registered in this manager\n- the regex fails to compile (`new RegExp(rule.ttsrTrigger)` throws)\n\nInvalid regex triggers are logged as warnings and ignored; session startup continues.\n\n### Setting caveat\n\n`TtsrSettings.enabled` is loaded into the manager but is not currently checked in runtime gating. If rules exist, matching still runs.\n\n## 2. Streaming monitor lifecycle\n\nTTSR detection runs inside `AgentSession.#handleAgentEvent`.\n\n### Turn start\n\nOn `turn_start`, the stream buffer is reset:\n\n- `ttsrManager.resetBuffer()`\n\n### During stream (`message_update`)\n\nWhen assistant updates arrive and rules exist:\n\n- monitor `text_delta` and `toolcall_delta`\n- append delta into manager buffer\n- call `check(buffer)`\n\n`check()` iterates registered rules and returns all matching rules that pass repeat policy (`#canTrigger`).\n\n## 3. Trigger decision and immediate abort path\n\nWhen one or more rules match:\n\n1. `markInjected(matches)` records rule names in manager injection state.\n2. matched rules are queued in `#pendingTtsrInjections`.\n3. `#ttsrAbortPending = true`.\n4. `agent.abort()` is called immediately.\n5. `ttsr_triggered` event is emitted asynchronously (fire-and-forget).\n6. retry work is scheduled via `setTimeout(..., 50)`.\n\nAbort is not blocked on extension callbacks.\n\n## 4. Retry scheduling, context mode, and reminder injection\n\nAfter the 50ms timeout:\n\n1. `#ttsrAbortPending = false`\n2. read `ttsrManager.getSettings().contextMode`\n3. if `contextMode === \"discard\"`, drop partial assistant output with `agent.popMessage()`\n4. build injection content from pending rules using `ttsr-interrupt.md` template\n5. append a synthetic user message containing one `<system-interrupt ...>` block per rule\n6. call `agent.continue()` to retry generation\n\nTemplate payload is:\n\n```xml\n<system-interrupt reason=\"rule_violation\" rule=\"{{name}}\" path=\"{{path}}\">\n...\n{{content}}\n</system-interrupt>\n```\n\nPending injections are cleared after content generation.\n\n### `contextMode` behavior on partial output\n\n- `discard`: partial/aborted assistant message is removed before retry.\n- `keep`: partial assistant output remains in conversation state; reminder is appended after it.\n\n## 5. Repeat policy and gap logic\n\n`TtsrManager` tracks `#messageCount` and per-rule `lastInjectedAt`.\n\n### `repeatMode: \"once\"`\n\nA rule can trigger only once after it has an injection record.\n\n### `repeatMode: \"after-gap\"`\n\nA rule can re-trigger only when:\n\n- `messageCount - lastInjectedAt >= repeatGap`\n\n`messageCount` increments on `turn_end`, so gap is measured in completed turns, not stream chunks.\n\n## 6. Event emission and extension/hook surfaces\n\n### Session event\n\n`AgentSessionEvent` includes:\n\n```ts\n{ type: \"ttsr_triggered\"; rules: Rule[] }\n```\n\n### Extension runner\n\n`#emitSessionEvent()` routes the event to:\n\n- extension listeners (`ExtensionRunner.emit({ type: \"ttsr_triggered\", rules })`)\n- local session subscribers\n\n### Hook and custom-tool typing\n\n- extension API exposes `on(\"ttsr_triggered\", ...)`\n- hook API exposes `on(\"ttsr_triggered\", ...)`\n- custom tools receive `onSession({ reason: \"ttsr_triggered\", rules })`\n\n### Interactive-mode rendering difference\n\nInteractive mode uses `session.isTtsrAbortPending` to suppress showing the aborted assistant stop reason as a visible failure during TTSR interruption, and renders a `TtsrNotificationComponent` when the event arrives.\n\n## 7. Persistence and resume state (current implementation)\n\n`SessionManager` has full schema support for injected-rule persistence:\n\n- entry type: `ttsr_injection`\n- append API: `appendTtsrInjection(ruleNames)`\n- query API: `getInjectedTtsrRules()`\n- context reconstruction includes `SessionContext.injectedTtsrRules`\n\n`TtsrManager` also supports restoration via `restoreInjected(ruleNames)`.\n\n### Current wiring status\n\nIn the current runtime path:\n\n- `AgentSession` does not append `ttsr_injection` entries when TTSR triggers.\n- `createAgentSession()` does not restore `existingSession.injectedTtsrRules` back into `ttsrManager`.\n\nNet effect: injected-rule suppression is enforced in-memory for the live process, but is not currently persisted/restored across session reload/resume by this path.\n\n## 8. Race boundaries and ordering guarantees\n\n### Abort vs retry callback\n\n- abort is synchronous from TTSR handler perspective (`agent.abort()` called immediately)\n- retry is deferred by timer (`50ms`)\n- extension notification is asynchronous and intentionally not awaited before abort/retry scheduling\n\n### Multiple matches in same stream window\n\n`check()` returns all currently matching eligible rules. They are injected as a batch on the next retry message.\n\n### Between abort and continue\n\nDuring the timer window, state can change (user interruption, mode actions, additional events). The retry call is best-effort: `agent.continue().catch(() => {})` swallows follow-up errors.\n\n## 9. Edge cases summary\n\n- Invalid `ttsr_trigger` regex: skipped with warning; other rules continue.\n- Duplicate rule names at capability layer: lower-priority duplicates are shadowed before registration.\n- Duplicate names at manager layer: second registration is ignored.\n- `contextMode: \"keep\"`: partial violating output can remain in context before reminder retry.\n- Repeat-after-gap depends on turn count increments at `turn_end`; mid-turn chunks do not advance gap counters.\n",
-	"tui/theme.md": "---\ntitle: Theming Reference\nsidebar:\n  order: 3\n  label: Theming\n---\n\n# Theming Reference\n\nThis document describes how theming works in the coding-agent today: schema, loading, runtime behavior, and failure modes.\n\n## What the theme system controls\n\nThe theme system drives:\n\n- foreground/background color tokens used across the TUI\n- markdown styling adapters (`getMarkdownTheme()`)\n- selector/editor/settings list adapters (`getSelectListTheme()`, `getEditorTheme()`, `getSettingsListTheme()`)\n- symbol preset + symbol overrides (`unicode`, `nerd`, `ascii`)\n- syntax highlighting colors used by native highlighter (`@f5xc-salesdemos/pi-natives`)\n- status line segment colors\n\nPrimary implementation: `src/modes/theme/theme.ts`.\n\n## Theme JSON shape\n\nTheme files are JSON objects validated against the runtime schema in `theme.ts` (`ThemeJsonSchema`) and mirrored by `src/modes/theme/theme-schema.json`.\n\nTop-level fields:\n\n- `name` (required)\n- `colors` (required; all color tokens required)\n- `vars` (optional; reusable color variables)\n- `export` (optional; HTML export colors)\n- `symbols` (optional)\n  - `preset` (optional: `unicode | nerd | ascii`)\n  - `overrides` (optional: key/value overrides for `SymbolKey`)\n\nColor values accept:\n\n- hex string (`\"#RRGGBB\"`)\n- 256-color index (`0..255`)\n- variable reference string (resolved through `vars`)\n- empty string (`\"\"`) meaning terminal default (`\\x1b[39m` fg, `\\x1b[49m` bg)\n\n## Required color tokens (current)\n\nAll tokens below are required in `colors`.\n\n### Core text and borders (11)\n\n`accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText`\n\n### Background blocks (7)\n\n`selectedBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `statusLineBg`\n\n### Message/tool text (5)\n\n`userMessageText`, `customMessageText`, `customMessageLabel`, `toolTitle`, `toolOutput`\n\n### Markdown (10)\n\n`mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet`\n\n### Tool diff + syntax highlighting (12)\n\n`toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`,\n`syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`\n\n### Mode/thinking borders (8)\n\n`thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `bashMode`, `pythonMode`\n\n### Status line segment colors (14)\n\n`statusLineSep`, `statusLineModel`, `statusLinePath`, `statusLineGitClean`, `statusLineGitDirty`, `statusLineContext`, `statusLineSpend`, `statusLineStaged`, `statusLineDirty`, `statusLineUntracked`, `statusLineOutput`, `statusLineCost`, `statusLineSubagents`\n\n## Optional tokens\n\n### `export` section (optional)\n\nUsed for HTML export theming helpers:\n\n- `export.pageBg`\n- `export.cardBg`\n- `export.infoBg`\n\nIf omitted, export code derives defaults from resolved theme colors.\n\n### `symbols` section (optional)\n\n- `symbols.preset` sets a theme-level default symbol set.\n- `symbols.overrides` can override individual `SymbolKey` values.\n\nRuntime precedence:\n\n1. settings `symbolPreset` override (if set)\n2. theme JSON `symbols.preset`\n3. fallback `\"unicode\"`\n\nInvalid override keys are ignored and logged (`logger.debug`).\n\n## Built-in vs custom theme sources\n\nTheme lookup order (`loadThemeJson`):\n\n1. built-in embedded themes (`defaults/xcsh-dark.json` and `defaults/xcsh-light.json` compiled into `defaultThemes`)\n2. custom theme file: `<customThemesDir>/<name>.json`\n\nCustom themes directory comes from `getCustomThemesDir()`:\n\n- default: `~/.xcsh/agent/themes`\n- overridden by `PI_CODING_AGENT_DIR` (`$PI_CODING_AGENT_DIR/themes`)\n\n`getAvailableThemes()` returns merged built-in + custom names, sorted, with built-ins taking precedence on name collision.\n\n## Loading, validation, and resolution\n\nFor custom theme files:\n\n1. read JSON\n2. parse JSON\n3. validate against `ThemeJsonSchema`\n4. resolve `vars` references recursively\n5. convert resolved values to ANSI by terminal capability mode\n\nValidation behavior:\n\n- missing required color tokens: explicit grouped error message\n- bad token types/values: validation errors with JSON path\n- unknown theme file: `Theme not found: <name>`\n\nVar reference behavior:\n\n- supports nested references\n- throws on missing variable reference\n- throws on circular references\n\n## Terminal color mode behavior\n\nColor mode detection (`detectColorMode`):\n\n- `COLORTERM=truecolor|24bit` => truecolor\n- `WT_SESSION` => truecolor\n- `TERM` in `dumb`, `linux`, or empty => 256color\n- otherwise => truecolor\n\nConversion behavior:\n\n- hex -> `Bun.color(..., \"ansi-16m\" | \"ansi-256\")`\n- numeric -> `38;5` / `48;5` ANSI\n- `\"\"` -> default fg/bg reset\n\n## Runtime switching behavior\n\n### Initial theme (`initTheme`)\n\n`main.ts` initializes theme with settings:\n\n- `symbolPreset`\n- `colorBlindMode`\n- `theme.dark`\n- `theme.light`\n\nAuto theme slot selection uses `COLORFGBG` background detection:\n\n- parse background index from `COLORFGBG`\n- `< 8` => dark slot (`theme.dark`)\n- `>= 8` => light slot (`theme.light`)\n- parse failure => dark slot\n\nCurrent defaults from settings schema:\n\n- `theme.dark = \"xcsh-dark\"`\n- `theme.light = \"xcsh-light\"`\n- `symbolPreset = \"unicode\"`\n- `colorBlindMode = false`\n\n### Explicit switching (`setTheme`)\n\n- loads selected theme\n- updates global `theme` singleton\n- optionally starts watcher\n- triggers `onThemeChange` callback\n\nOn failure:\n\n- falls back to built-in `dark`\n- returns `{ success: false, error }`\n\n### Preview switching (`previewTheme`)\n\n- applies temporary preview theme to global `theme`\n- does **not** change persisted settings by itself\n- returns success/error without fallback replacement\n\nSettings UI uses this for live preview and restores prior theme on cancel.\n\n## Watchers and live reload\n\nWhen watcher is enabled (`setTheme(..., true)` / interactive init):\n\n- only watches custom file path `<customThemesDir>/<currentTheme>.json`\n- built-ins are effectively not watched\n- file `change`: attempts reload (debounced)\n- file `rename`/delete: falls back to `dark`, closes watcher\n\nAuto mode also installs a `SIGWINCH` listener and can re-evaluate dark/light slot mapping when terminal state changes.\n\n## Color-blind mode behavior\n\n`colorBlindMode` changes only one token at runtime:\n\n- `toolDiffAdded` is HSV-adjusted (green shifted toward blue)\n- adjustment is applied only when resolved value is a hex string\n\nOther tokens are unchanged.\n\n## Where theme settings are persisted\n\nTheme-related settings are persisted by `Settings` to global config YAML:\n\n- path: `<agentDir>/config.yml`\n- default agent dir: `~/.xcsh/agent`\n- effective default file: `~/.xcsh/agent/config.yml`\n\nPersisted keys:\n\n- `theme.dark`\n- `theme.light`\n- `symbolPreset`\n- `colorBlindMode`\n\nLegacy migration exists: old flat `theme: \"name\"` is migrated to nested `theme.dark` or `theme.light` based on luminance detection.\n\n## Creating a custom theme (practical)\n\n1. Create file in custom themes dir, e.g. `~/.xcsh/agent/themes/my-theme.json`.\n2. Include `name`, optional `vars`, and **all required** `colors` tokens.\n3. Optionally include `symbols` and `export`.\n4. Select the theme in Settings (`Display -> Dark theme` or `Display -> Light theme`) depending on which auto slot you want.\n\nMinimal skeleton:\n\n```json\n{\n  \"name\": \"my-theme\",\n  \"vars\": {\n    \"accent\": \"#7aa2f7\",\n    \"muted\": 244\n  },\n  \"colors\": {\n    \"accent\": \"accent\",\n    \"border\": \"#4c566a\",\n    \"borderAccent\": \"accent\",\n    \"borderMuted\": \"muted\",\n    \"success\": \"#9ece6a\",\n    \"error\": \"#f7768e\",\n    \"warning\": \"#e0af68\",\n    \"muted\": \"muted\",\n    \"dim\": 240,\n    \"text\": \"\",\n    \"thinkingText\": \"muted\",\n\n    \"selectedBg\": \"#2a2f45\",\n    \"userMessageBg\": \"#1f2335\",\n    \"userMessageText\": \"\",\n    \"customMessageBg\": \"#24283b\",\n    \"customMessageText\": \"\",\n    \"customMessageLabel\": \"accent\",\n    \"toolPendingBg\": \"#1f2335\",\n    \"toolSuccessBg\": \"#1f2d2a\",\n    \"toolErrorBg\": \"#2d1f2a\",\n    \"toolTitle\": \"\",\n    \"toolOutput\": \"muted\",\n\n    \"mdHeading\": \"accent\",\n    \"mdLink\": \"accent\",\n    \"mdLinkUrl\": \"muted\",\n    \"mdCode\": \"#c0caf5\",\n    \"mdCodeBlock\": \"#c0caf5\",\n    \"mdCodeBlockBorder\": \"muted\",\n    \"mdQuote\": \"muted\",\n    \"mdQuoteBorder\": \"muted\",\n    \"mdHr\": \"muted\",\n    \"mdListBullet\": \"accent\",\n\n    \"toolDiffAdded\": \"#9ece6a\",\n    \"toolDiffRemoved\": \"#f7768e\",\n    \"toolDiffContext\": \"muted\",\n\n    \"syntaxComment\": \"#565f89\",\n    \"syntaxKeyword\": \"#bb9af7\",\n    \"syntaxFunction\": \"#7aa2f7\",\n    \"syntaxVariable\": \"#c0caf5\",\n    \"syntaxString\": \"#9ece6a\",\n    \"syntaxNumber\": \"#ff9e64\",\n    \"syntaxType\": \"#2ac3de\",\n    \"syntaxOperator\": \"#89ddff\",\n    \"syntaxPunctuation\": \"#9aa5ce\",\n\n    \"thinkingOff\": 240,\n    \"thinkingMinimal\": 244,\n    \"thinkingLow\": \"#7aa2f7\",\n    \"thinkingMedium\": \"#2ac3de\",\n    \"thinkingHigh\": \"#bb9af7\",\n    \"thinkingXhigh\": \"#f7768e\",\n\n    \"bashMode\": \"#2ac3de\",\n    \"pythonMode\": \"#bb9af7\",\n\n    \"statusLineBg\": \"#16161e\",\n    \"statusLineSep\": 240,\n    \"statusLineModel\": \"#bb9af7\",\n    \"statusLinePath\": \"#7aa2f7\",\n    \"statusLineGitClean\": \"#9ece6a\",\n    \"statusLineGitDirty\": \"#e0af68\",\n    \"statusLineContext\": \"#2ac3de\",\n    \"statusLineSpend\": \"#7dcfff\",\n    \"statusLineStaged\": \"#9ece6a\",\n    \"statusLineDirty\": \"#e0af68\",\n    \"statusLineUntracked\": \"#f7768e\",\n    \"statusLineOutput\": \"#c0caf5\",\n    \"statusLineCost\": \"#ff9e64\",\n    \"statusLineSubagents\": \"#bb9af7\"\n  }\n}\n```\n\n## Testing custom themes\n\nUse this workflow:\n\n1. Start interactive mode (watcher enabled from startup).\n2. Open settings and preview theme values (live `previewTheme`).\n3. For custom theme files, edit the JSON while running and confirm auto-reload on save.\n4. Exercise critical surfaces:\n   - markdown rendering\n   - tool blocks (pending/success/error)\n   - diff rendering (added/removed/context)\n   - status line readability\n   - thinking level border changes\n   - bash/python mode border colors\n5. Validate both symbol presets if your theme depends on glyph width/appearance.\n\n## Real constraints and caveats\n\n- All `colors` tokens are required for custom themes.\n- `export` and `symbols` are optional.\n- `$schema` in theme JSON is informational; runtime validation is enforced by compiled TypeBox schema in code.\n- `setTheme` failure falls back to `dark`; `previewTheme` failure does not replace current theme.\n- File watcher reload errors keep the current loaded theme until a successful reload or fallback path is triggered.\n",
+	"tui/theme.md": "---\ntitle: Theming Reference\nsidebar:\n  order: 3\n  label: Theming\n---\n\n# Theming Reference\n\nThis document describes how theming works in the coding-agent today: schema, loading, runtime behavior, and failure modes.\n\n## What the theme system controls\n\nThe theme system drives:\n\n- foreground/background color tokens used across the TUI\n- markdown styling adapters (`getMarkdownTheme()`)\n- selector/editor/settings list adapters (`getSelectListTheme()`, `getEditorTheme()`, `getSettingsListTheme()`)\n- symbol preset + symbol overrides (`unicode`, `nerd`, `ascii`)\n- syntax highlighting colors used by native highlighter (`@f5xc-salesdemos/pi-natives`)\n- status line segment colors\n\nPrimary implementation: `src/modes/theme/theme.ts`.\n\n## Theme JSON shape\n\nTheme files are JSON objects validated against the runtime schema in `theme.ts` (`ThemeJsonSchema`) and mirrored by `src/modes/theme/theme-schema.json`.\n\nTop-level fields:\n\n- `name` (required)\n- `colors` (required; all color tokens required)\n- `vars` (optional; reusable color variables)\n- `export` (optional; HTML export colors)\n- `symbols` (optional)\n  - `preset` (optional: `unicode | nerd | ascii`)\n  - `overrides` (optional: key/value overrides for `SymbolKey`)\n\nColor values accept:\n\n- hex string (`\"#RRGGBB\"`)\n- 256-color index (`0..255`)\n- variable reference string (resolved through `vars`)\n- empty string (`\"\"`) meaning terminal default (`\\x1b[39m` fg, `\\x1b[49m` bg)\n\n## Required color tokens (current)\n\nAll tokens below are required in `colors`.\n\n### Core text and borders (11)\n\n`accent`, `border`, `borderAccent`, `borderMuted`, `success`, `error`, `warning`, `muted`, `dim`, `text`, `thinkingText`\n\n### Background blocks (7)\n\n`selectedBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`, `statusLineBg`\n\n### Message/tool text (5)\n\n`userMessageText`, `customMessageText`, `customMessageLabel`, `toolTitle`, `toolOutput`\n\n### Markdown (10)\n\n`mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet`\n\n### Tool diff + syntax highlighting (12)\n\n`toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext`,\n`syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation`\n\n### Mode/thinking borders (8)\n\n`thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `bashMode`, `pythonMode`\n\n### Status line segment colors (14)\n\n`statusLineSep`, `statusLineModel`, `statusLinePath`, `statusLineGitClean`, `statusLineGitDirty`, `statusLineContext`, `statusLineSpend`, `statusLineStaged`, `statusLineDirty`, `statusLineUntracked`, `statusLineOutput`, `statusLineCost`, `statusLineSubagents`\n\n## Optional tokens\n\n### `export` section (optional)\n\nUsed for HTML export theming helpers:\n\n- `export.pageBg`\n- `export.cardBg`\n- `export.infoBg`\n\nIf omitted, export code derives defaults from resolved theme colors.\n\n### `symbols` section (optional)\n\n- `symbols.preset` sets a theme-level default symbol set.\n- `symbols.overrides` can override individual `SymbolKey` values.\n\nRuntime precedence:\n\n1. settings `symbolPreset` override (if set)\n2. theme JSON `symbols.preset`\n3. fallback `\"unicode\"`\n\nInvalid override keys are ignored and logged (`logger.debug`).\n\n## Built-in vs custom theme sources\n\nTheme lookup order (`loadThemeJson`):\n\n1. built-in embedded themes (`defaults/xcsh-dark.json` and `defaults/xcsh-light.json` compiled into `defaultThemes`)\n2. custom theme file: `<customThemesDir>/<name>.json`\n\nCustom themes directory comes from `getCustomThemesDir()`:\n\n- default: `~/.xcsh/agent/themes`\n- overridden by `PI_CODING_AGENT_DIR` (`$PI_CODING_AGENT_DIR/themes`)\n\n`getAvailableThemes()` returns merged built-in + custom names, sorted, with built-ins taking precedence on name collision.\n\n## Loading, validation, and resolution\n\nFor custom theme files:\n\n1. read JSON\n2. parse JSON\n3. validate against `ThemeJsonSchema`\n4. resolve `vars` references recursively\n5. convert resolved values to ANSI by terminal capability mode\n\nValidation behavior:\n\n- missing required color tokens: explicit grouped error message\n- bad token types/values: validation errors with JSON path\n- unknown theme file: `Theme not found: <name>`\n\nVar reference behavior:\n\n- supports nested references\n- throws on missing variable reference\n- throws on circular references\n\n## Terminal color mode behavior\n\nColor mode detection (`detectColorMode`):\n\n- `COLORTERM=truecolor|24bit` => truecolor\n- `WT_SESSION` => truecolor\n- `TERM` in `dumb`, `linux`, or empty => 256color\n- otherwise => truecolor\n\nConversion behavior:\n\n- hex -> `Bun.color(..., \"ansi-16m\" | \"ansi-256\")`\n- numeric -> `38;5` / `48;5` ANSI\n- `\"\"` -> default fg/bg reset\n\n## Runtime switching behavior\n\n### Initial theme (`initTheme`)\n\n`main.ts` initializes theme with settings:\n\n- `symbolPreset`\n- `colorBlindMode`\n- `theme.dark`\n- `theme.light`\n\nAuto theme slot selection uses `COLORFGBG` background detection:\n\n- parse background index from `COLORFGBG`\n- `< 8` => dark slot (`theme.dark`)\n- `>= 8` => light slot (`theme.light`)\n- parse failure => dark slot\n\nCurrent defaults from settings schema:\n\n- `theme.dark = \"xcsh-dark\"`\n- `theme.light = \"xcsh-light\"`\n- `symbolPreset = \"unicode\"`\n- `colorBlindMode = false`\n\n### Explicit switching (`setTheme`)\n\n- loads selected theme\n- updates global `theme` singleton\n- optionally starts watcher\n- triggers `onThemeChange` callback\n\nOn failure:\n\n- falls back to built-in `dark`\n- returns `{ success: false, error }`\n\n### Preview switching (`previewTheme`)\n\n- applies temporary preview theme to global `theme`\n- does **not** change persisted settings by itself\n- returns success/error without fallback replacement\n\nSettings UI uses this for live preview and restores prior theme on cancel.\n\n## Watchers and live reload\n\nWhen watcher is enabled (`setTheme(..., true)` / interactive init):\n\n- only watches custom file path `<customThemesDir>/<currentTheme>.json`\n- built-ins are effectively not watched\n- file `change`: attempts reload (debounced)\n- file `rename`/delete: falls back to `dark`, closes watcher\n\nAuto mode also installs a `SIGWINCH` listener and can re-evaluate dark/light slot mapping when terminal state changes.\n\n## Color-blind mode behavior\n\n`colorBlindMode` changes only one token at runtime:\n\n- `toolDiffAdded` is HSV-adjusted (green shifted toward blue)\n- adjustment is applied only when resolved value is a hex string\n\nOther tokens are unchanged.\n\n## Where theme settings are persisted\n\nTheme-related settings are persisted by `Settings` to global config YAML:\n\n- path: `<agentDir>/config.yml`\n- default agent dir: `~/.xcsh/agent`\n- effective default file: `~/.xcsh/agent/config.yml`\n\nPersisted keys:\n\n- `theme.dark`\n- `theme.light`\n- `symbolPreset`\n- `colorBlindMode`\n\nLegacy migration exists: old flat `theme: \"name\"` is migrated to nested `theme.dark` or `theme.light` based on luminance detection.\n\n## Creating a custom theme (practical)\n\n1. Create file in custom themes dir, e.g. `~/.xcsh/agent/themes/my-theme.json`.\n2. Include `name`, optional `vars`, and **all required** `colors` tokens.\n3. Optionally include `symbols` and `export`.\n4. Select the theme in Settings (`Display -> Dark theme` or `Display -> Light theme`) depending on which auto slot you want.\n\nMinimal skeleton. Every key in `colors` is required — the runtime validator\n(`additionalProperties: false`) rejects both missing keys and unknown keys.\nFor the shipped reference implementations see\n[`packages/coding-agent/src/modes/theme/defaults/xcsh-dark.json`](../../packages/coding-agent/src/modes/theme/defaults/xcsh-dark.json)\nand [`xcsh-light.json`](../../packages/coding-agent/src/modes/theme/defaults/xcsh-light.json).\n\nThe status line has two parallel color systems documented in issue #242:\n\n- Hex text colors (`statusLinePath`, `statusLineGitClean`, `statusLineGitDirty`,\n  `statusLineStaged`, `statusLineDirty`, `statusLineUntracked`) drive non-powerline\n  rendering.\n- 256-color palette indices (`statusLine<Segment>Bg` / `statusLine<Segment>Fg`)\n  drive powerline segment fills. They are independent of the hex keys above —\n  both must be set.\n\n```json\n{\n  \"name\": \"my-theme\",\n  \"vars\": {\n    \"accent\": \"#7aa2f7\",\n    \"muted\": 244\n  },\n  \"colors\": {\n    \"accent\": \"accent\",\n    \"chromeAccent\": \"accent\",\n    \"spinnerAccent\": \"accent\",\n    \"contentAccent\": \"muted\",\n    \"border\": \"#4c566a\",\n    \"borderAccent\": \"accent\",\n    \"borderMuted\": \"muted\",\n    \"success\": \"#9ece6a\",\n    \"error\": \"#f7768e\",\n    \"warning\": \"#e0af68\",\n    \"muted\": \"muted\",\n    \"dim\": 240,\n    \"gutterSuccess\": \"#7dcfff\",\n    \"gutterWarning\": \"#e0af68\",\n    \"text\": \"\",\n    \"thinkingText\": \"muted\",\n\n    \"selectedBg\": \"#2a2f45\",\n    \"userMessageBg\": \"#1f2335\",\n    \"userMessageText\": \"\",\n    \"customMessageBg\": \"#24283b\",\n    \"customMessageText\": \"\",\n    \"customMessageLabel\": \"accent\",\n    \"toolPendingBg\": \"#1f2335\",\n    \"toolSuccessBg\": \"#1f2d2a\",\n    \"toolErrorBg\": \"#2d1f2a\",\n    \"toolTitle\": \"\",\n    \"toolOutput\": \"muted\",\n\n    \"mdHeading\": \"accent\",\n    \"mdLink\": \"accent\",\n    \"mdLinkUrl\": \"muted\",\n    \"mdCode\": \"#c0caf5\",\n    \"mdCodeBlock\": \"#c0caf5\",\n    \"mdCodeBlockBorder\": \"muted\",\n    \"mdQuote\": \"muted\",\n    \"mdQuoteBorder\": \"muted\",\n    \"mdHr\": \"muted\",\n    \"mdListBullet\": \"accent\",\n\n    \"toolDiffAdded\": \"#9ece6a\",\n    \"toolDiffRemoved\": \"#f7768e\",\n    \"toolDiffContext\": \"muted\",\n\n    \"syntaxComment\": \"#565f89\",\n    \"syntaxKeyword\": \"#bb9af7\",\n    \"syntaxFunction\": \"#7aa2f7\",\n    \"syntaxVariable\": \"#c0caf5\",\n    \"syntaxString\": \"#9ece6a\",\n    \"syntaxNumber\": \"#ff9e64\",\n    \"syntaxType\": \"#2ac3de\",\n    \"syntaxOperator\": \"#89ddff\",\n    \"syntaxPunctuation\": \"#9aa5ce\",\n    \"syntaxControl\": \"#bb9af7\",\n\n    \"thinkingOff\": 240,\n    \"thinkingMinimal\": 244,\n    \"thinkingLow\": \"#7aa2f7\",\n    \"thinkingMedium\": \"#2ac3de\",\n    \"thinkingHigh\": \"#bb9af7\",\n    \"thinkingXhigh\": \"#f7768e\",\n\n    \"bashMode\": \"#2ac3de\",\n    \"pythonMode\": \"#bb9af7\",\n\n    \"statusLineBg\": \"#16161e\",\n    \"statusLineSep\": 240,\n    \"statusLineModel\": \"#bb9af7\",\n    \"statusLinePath\": \"#7aa2f7\",\n    \"statusLineGitClean\": \"#9ece6a\",\n    \"statusLineGitDirty\": \"#e0af68\",\n    \"statusLineContext\": \"#2ac3de\",\n    \"statusLineSpend\": \"#7dcfff\",\n    \"statusLineStaged\": \"#9ece6a\",\n    \"statusLineDirty\": \"#e0af68\",\n    \"statusLineUntracked\": \"#f7768e\",\n    \"statusLineOutput\": \"#c0caf5\",\n    \"statusLineCost\": \"#ff9e64\",\n    \"statusLineSubagents\": \"#bb9af7\",\n\n    \"statusLineOsIconBg\": 7,\n    \"statusLineOsIconFg\": 232,\n    \"statusLinePathBg\": 4,\n    \"statusLinePathFg\": 254,\n    \"statusLineGitCleanBg\": 2,\n    \"statusLineGitCleanFg\": 0,\n    \"statusLineGitDirtyBg\": 3,\n    \"statusLineGitDirtyFg\": 0,\n    \"statusLineGitStagedBg\": 64,\n    \"statusLineGitStagedFg\": 0,\n    \"statusLineGitUntrackedBg\": 39,\n    \"statusLineGitUntrackedFg\": 0,\n    \"statusLineGitConflictBg\": 1,\n    \"statusLineGitConflictFg\": 7,\n    \"statusLinePlanModeBg\": 236,\n    \"statusLinePlanModeFg\": 117,\n    \"statusLineContextPctBg\": 238,\n    \"statusLineContextPctFg\": 255,\n    \"statusLineContextPctNormalBg\": 17,\n    \"statusLineContextPctWarningBg\": 22,\n    \"statusLineContextPctPurpleBg\": 94,\n    \"statusLineContextPctErrorBg\": 88,\n    \"statusLineProfileF5xcBg\": \"accent\",\n    \"statusLineProfileF5xcFg\": 231\n  }\n}\n```\n\n## Testing custom themes\n\nUse this workflow:\n\n1. Start interactive mode (watcher enabled from startup).\n2. Open settings and preview theme values (live `previewTheme`).\n3. For custom theme files, edit the JSON while running and confirm auto-reload on save.\n4. Exercise critical surfaces:\n   - markdown rendering\n   - tool blocks (pending/success/error)\n   - diff rendering (added/removed/context)\n   - status line readability\n   - thinking level border changes\n   - bash/python mode border colors\n5. Validate both symbol presets if your theme depends on glyph width/appearance.\n\n## Real constraints and caveats\n\n- All `colors` tokens are required for custom themes.\n- `export` and `symbols` are optional.\n- `$schema` in theme JSON is informational; runtime validation is enforced by compiled TypeBox schema in code.\n- `setTheme` failure falls back to `dark`; `previewTheme` failure does not replace current theme.\n- File watcher reload errors keep the current loaded theme until a successful reload or fallback path is triggered.\n",
 	"tui/tree.md": "---\ntitle: Tree Command Reference\nsidebar:\n  order: 4\n  label: /tree command\n---\n\n# `/tree` Command Reference\n\n`/tree` opens the interactive **Session Tree** navigator. It lets you jump to any entry in the current session file and continue from that point.\n\nThis is an in-file leaf move, not a new session export.\n\n## What `/tree` does\n\n- Builds a tree from current session entries (`SessionManager.getTree()`)\n- Opens `TreeSelectorComponent` with keyboard navigation, filters, and search\n- On selection, calls `AgentSession.navigateTree(targetId, { summarize, customInstructions })`\n- Rebuilds visible chat from the new leaf path\n- Optionally prefills editor text when selecting a user/custom message\n\nPrimary implementation:\n\n- `src/modes/controllers/input-controller.ts` (`/tree`, keybinding wiring, double-escape behavior)\n- `src/modes/controllers/selector-controller.ts` (tree UI launch + summary prompt flow)\n- `src/modes/components/tree-selector.ts` (navigation, filters, search, labels, rendering)\n- `src/session/agent-session.ts` (`navigateTree` leaf switching + optional summary)\n- `src/session/session-manager.ts` (`getTree`, `branch`, `branchWithSummary`, `resetLeaf`, label persistence)\n\n## How to open it\n\nAny of the following opens the same selector:\n\n- `/tree`\n- configured keybinding action `tree`\n- double-escape on empty editor when `doubleEscapeAction = \"tree\"` (default)\n- `/branch` when `doubleEscapeAction = \"tree\"` (routes to tree selector instead of user-only branch picker)\n\n## Tree UI model\n\nThe tree is rendered from session entry parent pointers (`id` / `parentId`).\n\n- Children are sorted by timestamp ascending (older first, newer lower)\n- Active branch (path from root to current leaf) is marked with a bullet\n- Labels (if present) render as `[label]` before node text\n- If multiple roots exist (orphaned/broken parent chains), they are shown under a virtual branching root\n\n```text\nExample tree view (active path marked with •):\n\n├─ user: \"Start task\"\n│  └─ assistant: \"Plan\"\n│     ├─ • user: \"Try approach A\"\n│     │  └─ • assistant: \"A result\"\n│     │     └─ • [milestone] user: \"Continue A\"\n│     └─ user: \"Try approach B\"\n│        └─ assistant: \"B result\"\n```\n\nThe selector recenters around current selection and shows up to:\n\n- `max(5, floor(terminalHeight / 2))` rows\n\n## Keybindings inside tree selector\n\n- `Up` / `Down`: move selection (wraps)\n- `Left` / `Right`: page up / page down\n- `Enter`: select node\n- `Esc`: clear search if active; otherwise close selector\n- `Ctrl+C`: close selector\n- `Type`: append to search query\n- `Backspace`: delete search character\n- `Shift+L`: edit/clear label on selected entry\n- `Ctrl+O`: cycle filter forward\n- `Shift+Ctrl+O`: cycle filter backward\n- `Alt+D/T/U/L/A`: jump directly to specific filter mode\n\n## Filters and search semantics\n\nFilter modes (`TreeList`):\n\n1. `default`\n2. `no-tools`\n3. `user-only`\n4. `labeled-only`\n5. `all`\n\n### `default`\n\nShows most conversational nodes, but hides bookkeeping entry types:\n\n- `label`\n- `custom`\n- `model_change`\n- `thinking_level_change`\n\n### `no-tools`\n\nSame as `default`, plus hides `toolResult` messages.\n\n### `user-only`\n\nOnly `message` entries where role is `user`.\n\n### `labeled-only`\n\nOnly entries that currently resolve to a label.\n\n### `all`\n\nEverything in the session tree, including bookkeeping/custom entries.\n\n### Tool-only assistant node behavior\n\nAssistant messages that contain **only tool calls** (no text) are hidden by default in all filtered views unless:\n\n- message is error/aborted (`stopReason` not `stop`/`toolUse`), or\n- it is the current leaf (always kept visible)\n\n### Search behavior\n\n- Query is tokenized by spaces\n- Matching is case-insensitive\n- All tokens must match (AND semantics)\n- Searchable text includes label, role, and type-specific content (message text, branch summary text, custom type, tool command snippets, etc.)\n\n## Selection outcomes (important)\n\n`navigateTree` computes new leaf behavior from selected entry type:\n\n### Selecting `user` message\n\n- New leaf becomes selected entry’s `parentId`\n- If parent is `null` (root user message), leaf resets to root (`resetLeaf()`)\n- Selected message text is copied to editor for editing/resubmit\n\n### Selecting `custom_message`\n\n- Same leaf rule as user messages (`parentId`)\n- Text content is extracted and copied to editor\n\n### Selecting non-user node (assistant/tool/summary/compaction/custom bookkeeping/etc.)\n\n- New leaf becomes selected node id\n- Editor is not prefilled\n\n### Selecting current leaf\n\n- No-op; selector closes with “Already at this point”\n\n```text\nSelection decision (simplified):\n\nselected node\n   │\n   ├─ is current leaf? ── yes ──> close selector (no-op)\n   │\n   ├─ is user/custom_message? ── yes ──> leaf := parentId (or resetLeaf for root)\n   │                                     + prefill editor text\n   │\n   └─ otherwise ──> leaf := selected node id\n                    + no editor prefill\n```\n\n## Summary-on-switch flow\n\nSummary prompt is controlled by `branchSummary.enabled` (default: `false`).\n\nWhen enabled, after picking a node the UI asks:\n\n- `No summary`\n- `Summarize`\n- `Summarize with custom prompt`\n\nFlow details:\n\n- Escape in summary prompt reopens tree selector\n- Custom prompt cancellation returns to summary choice loop\n- During summarization, UI shows loader and binds `Esc` to `abortBranchSummary()`\n- If summarization aborts, tree selector reopens and no move is applied\n\n`navigateTree` internals:\n\n- Collects abandoned-branch entries from old leaf to common ancestor\n- Emits `session_before_tree` (extensions can cancel or inject summary)\n- Uses default summarizer only if requested and needed\n- Applies move with:\n  - `branchWithSummary(...)` when summary exists\n  - `branch(newLeafId)` for non-root move without summary\n  - `resetLeaf()` for root move without summary\n- Replaces agent conversation with rebuilt session context\n- Emits `session_tree`\n\nNote: if user requests summary but there is nothing to summarize, navigation proceeds without creating a summary entry.\n\n## Labels\n\nLabel edits in tree UI call `appendLabelChange(targetId, label)`.\n\n- non-empty label sets/updates resolved label\n- empty label clears it\n- labels are stored as append-only `label` entries\n- tree nodes display resolved label state, not raw label-entry history\n\n## `/tree` vs adjacent operations\n\n| Operation | Scope | Result |\n|---|---|---|\n| `/tree` | Current session file | Moves leaf to selected point (same file) |\n| `/branch` | Usually current session file -> new session file | By default branches from selected **user** message into a new session file; if `doubleEscapeAction = \"tree\"`, `/branch` opens tree navigation UI instead |\n| `/fork` | Whole current session | Duplicates session into a new persisted session file |\n| `/resume` | Session list | Switches to another session file |\n\nKey distinction: `/tree` is a navigation/repositioning tool inside one session file. `/branch`, `/fork`, and `/resume` all change session-file context.\n\n## Operator workflows\n\n### Re-run from an earlier user prompt without losing current branch\n\n1. `/tree`\n2. search/select earlier user message\n3. choose `No summary` (or summarize if needed)\n4. edit prefilled text in editor\n5. submit\n\nEffect: new branch grows from selected point within same session file.\n\n### Leave current branch with context breadcrumb\n\n1. enable `branchSummary.enabled`\n2. `/tree` and select target node\n3. choose `Summarize` (or custom prompt)\n\nEffect: a `branch_summary` entry is appended at the target position before continuing.\n\n### Investigate hidden bookkeeping entries\n\n1. `/tree`\n2. press `Alt+A` (all)\n3. search for `model`, `thinking`, `custom`, or labels\n\nEffect: inspect full internal timeline, not just conversational nodes.\n\n### Bookmark pivot points for later jumps\n\n1. `/tree`\n2. move to entry\n3. `Shift+L` and set label\n4. later use `Alt+L` (`labeled-only`) to jump quickly\n\nEffect: fast navigation among durable branch landmarks.\n",
 	"tui/tui-runtime-internals.md": "---\ntitle: TUI Runtime Internals\nsidebar:\n  order: 2\n  label: Runtime internals\n---\n\n# TUI runtime internals\n\nThis document maps the non-theme runtime path from terminal input to rendered output in interactive mode. It focuses on behavior in `packages/tui` and its integration from `packages/coding-agent` controllers.\n\n## Runtime layers and ownership\n\n- **`packages/tui` engine**: terminal lifecycle, stdin normalization, focus routing, render scheduling, differential painting, overlay composition, hardware cursor placement.\n- **`packages/coding-agent` interactive mode**: builds component tree, binds editor callbacks and keymaps, reacts to agent/session events, and translates domain state (streaming, tool execution, retries, plan mode) into UI components.\n\nBoundary rule: the TUI engine is message-agnostic. It only knows `Component.render(width)`, `handleInput(data)`, focus, and overlays. Agent semantics stay in interactive controllers.\n\n## Implementation files\n\n- [`../src/modes/interactive-mode.ts`](../../packages/coding-agent/src/modes/interactive-mode.ts)\n- [`../src/modes/controllers/event-controller.ts`](../../packages/coding-agent/src/modes/controllers/event-controller.ts)\n- [`../src/modes/controllers/input-controller.ts`](../../packages/coding-agent/src/modes/controllers/input-controller.ts)\n- [`../src/modes/components/custom-editor.ts`](../../packages/coding-agent/src/modes/components/custom-editor.ts)\n- [`../../tui/src/tui.ts`](../../packages/tui/src/tui.ts)\n- [`../../tui/src/terminal.ts`](../../packages/tui/src/terminal.ts)\n- [`../../tui/src/editor-component.ts`](../../packages/tui/src/editor-component.ts)\n- [`../../tui/src/stdin-buffer.ts`](../../packages/tui/src/stdin-buffer.ts)\n- [`../../tui/src/components/loader.ts`](../../packages/tui/src/components/loader.ts)\n\n## Boot and component tree assembly\n\n`InteractiveMode` constructs `TUI(new ProcessTerminal(), showHardwareCursor)` and creates persistent containers:\n\n- `chatContainer`\n- `pendingMessagesContainer`\n- `statusContainer`\n- `todoContainer`\n- `statusLine`\n- `editorContainer` (holds `CustomEditor`)\n\n`init()` wires the tree in that order, focuses the editor, registers input handlers via `InputController`, starts TUI, and requests a forced render.\n\nA forced render (`requestRender(true)`) resets previous-line caches and cursor bookkeeping before repainting.\n\n## Terminal lifecycle and stdin normalization\n\n`ProcessTerminal.start()`:\n\n1. Enables raw mode and bracketed paste.\n2. Attaches resize handler.\n3. Creates a `StdinBuffer` to split partial escape chunks into complete sequences.\n4. Queries Kitty keyboard protocol support (`CSI ? u`), then enables protocol flags if supported.\n5. On Windows, attempts VT input enablement via `kernel32` mode flags.\n\n`StdinBuffer` behavior:\n\n- Buffers fragmented escape sequences (CSI/OSC/DCS/APC/SS3).\n- Emits `data` only when a sequence is complete or timeout-flushed.\n- Detects bracketed paste and emits a `paste` event with raw pasted text.\n\nThis prevents partial escape chunks from being misinterpreted as normal keypresses.\n\n## Input routing and focus model\n\nInput path:\n\n`stdin -> ProcessTerminal -> StdinBuffer -> TUI.#handleInput -> focusedComponent.handleInput`\n\nRouting details:\n\n1. TUI runs registered input listeners first (`addInputListener`), allowing consume/transform behavior.\n2. TUI handles global debug shortcut (`shift+ctrl+d`) before component dispatch.\n3. If focused component belongs to an overlay that is now hidden/invisible, TUI reassigns focus to next visible overlay or saved pre-overlay focus.\n4. Key release events are filtered unless focused component sets `wantsKeyRelease = true`.\n5. After dispatch, TUI schedules render.\n\n`setFocus()` also toggles `Focusable.focused`, which controls whether components emit `CURSOR_MARKER` for hardware cursor placement.\n\n## Key handling split: editor vs controller\n\n`CustomEditor` intercepts high-priority combos first (escape, ctrl-c/d/z, ctrl-v, ctrl-p variants, ctrl-t, alt-up, extension custom keys) and delegates the rest to base `Editor` behavior (text editing, history, autocomplete, cursor movement).\n\n`InputController.setupKeyHandlers()` then binds editor callbacks to mode actions:\n\n- cancellation / mode exits on `Escape`\n- shutdown on double `Ctrl+C` or empty-editor `Ctrl+D`\n- suspend/resume on `Ctrl+Z`\n- slash-command and selector hotkeys\n- follow-up/dequeue toggles and expansion toggles\n\nThis keeps key parsing/editor mechanics in `packages/tui` and mode semantics in coding-agent controllers.\n\n## Render loop and diffing strategy\n\n`TUI.requestRender()` is debounced to one render per tick using `process.nextTick`. Multiple state changes in the same turn coalesce.\n\n`#doRender()` pipeline:\n\n1. Render root component tree to `newLines`.\n2. Composite visible overlays (if any).\n3. Extract and strip `CURSOR_MARKER` from visible viewport lines.\n4. Append segment reset suffixes for non-image lines.\n5. Choose full repaint vs differential patch:\n   - first frame\n   - width change\n   - shrink with `clearOnShrink` enabled and no overlays\n   - edits above previous viewport\n6. For differential updates, patch only changed line range and clear stale trailing lines when needed.\n7. Reposition hardware cursor for IME support.\n\nRender writes use synchronized output mode (`CSI ? 2026 h/l`) to reduce flicker/tearing.\n\n## Render safety constraints\n\nCritical safety checks in `TUI`:\n\n- Non-image rendered lines must not exceed terminal width; overflow throws and writes crash diagnostics.\n- Overlay compositing includes defensive truncation and post-composite width verification.\n- Width changes force full redraw because wrapping semantics change.\n- Cursor position is clamped before movement.\n\nThese constraints are runtime enforcement, not just conventions.\n\n## Resize handling\n\nResize events are event-driven from `ProcessTerminal` to `TUI.requestRender()`.\n\nEffects:\n\n- Any width change triggers full redraw.\n- Viewport/top tracking (`#previousViewportTop`, `#maxLinesRendered`) avoids invalid relative cursor math when content or terminal size changes.\n- Overlay visibility can depend on terminal dimensions (`OverlayOptions.visible`); focus is corrected when overlays become non-visible after resize.\n\n## Streaming and incremental UI updates\n\n`EventController` subscribes to `AgentSessionEvent` and updates UI incrementally:\n\n- `agent_start`: starts loader in `statusContainer`.\n- `message_start` assistant: creates `streamingComponent` and mounts it.\n- `message_update`: updates streaming assistant content; creates/updates tool execution components as tool calls appear.\n- `tool_execution_update/end`: updates tool result components and completion state.\n- `message_end`: finalizes assistant stream, handles aborted/error annotations, marks pending tool args complete on normal stop.\n- `agent_end`: stops loaders, clears transient stream state, flushes deferred model switch, issues completion notification if backgrounded.\n\nRead-tool grouping is intentionally stateful (`#lastReadGroup`) to coalesce consecutive read tool calls into one visual block until a non-read break occurs.\n\n## Status and loader orchestration\n\nStatus lane ownership:\n\n- `statusContainer` holds transient loaders (`loadingAnimation`, `autoCompactionLoader`, `retryLoader`).\n- `statusLine` renders persistent status/hooks/plan indicators and drives editor top border updates.\n\nLoader behavior:\n\n- `Loader` updates every 80ms via interval and requests render each frame.\n- Escape handlers are temporarily overridden during auto-compaction and auto-retry to cancel those operations.\n- On end/cancel paths, controllers restore prior escape handlers and stop/clear loader components.\n\n## Mode transitions and backgrounding\n\n### Bash/Python input modes\n\nInput text prefixes toggle editor border mode flags:\n\n- `!` -> bash mode\n- `$` (non-template literal prefix) -> python mode\n\nEscape exits inactive mode by clearing editor text and restoring border color; when execution is active, escape aborts the running task instead.\n\n### Plan mode\n\n`InteractiveMode` tracks plan mode flags, status-line state, active tools, and model switching. Enter/exit updates session mode entries and status/UI state, including deferred model switch if streaming is active.\n\n### Suspend/resume (`Ctrl+Z`)\n\n`InputController.handleCtrlZ()`:\n\n1. Registers one-shot `SIGCONT` handler to restart TUI and force render.\n2. Stops TUI before suspend.\n3. Sends `SIGTSTP` to process group.\n\n### Background mode (`/background` or `/bg`)\n\n`handleBackgroundCommand()`:\n\n- Rejects when idle.\n- Switches tool UI context to non-interactive (`hasUI=false`) so interactive UI tools fail fast.\n- Stops loaders/status line and unsubscribes foreground event handler.\n- Subscribes background event handler (primarily waits for `agent_end`).\n- Stops TUI and sends `SIGTSTP` (POSIX job control path).\n\nOn `agent_end` in background with no queued work, controller sends completion notification and shuts down.\n\n## Cancellation paths\n\nPrimary cancellation inputs:\n\n- `Escape` during active stream loader: restores queued messages to editor and aborts agent.\n- `Escape` during bash/python execution: aborts running command.\n- `Escape` during auto-compaction/retry: invokes dedicated abort methods through temporary escape handlers.\n- `Ctrl+C` single press: clear editor; double press within 500ms: shutdown.\n\nCancellation is state-conditional; same key can mean abort, mode-exit, selector trigger, or no-op depending on runtime state.\n\n## Event-driven vs throttled behavior\n\nEvent-driven updates:\n\n- Agent session events (`EventController`)\n- Key input callbacks (`InputController`)\n- terminal resize callback\n- theme/branch watchers in `InteractiveMode`\n\nThrottled/debounced paths:\n\n- TUI rendering is tick-debounced (`requestRender` coalescing).\n- Loader animation is fixed-interval (80ms), each frame requesting render.\n- Editor autocomplete updates (inside `Editor`) use debounce timers, reducing recompute churn during typing.\n\nThe runtime therefore mixes event-driven state transitions with bounded render cadence to keep interactivity responsive without repaint storms.\n",
 	"tui/tui.md": "---\ntitle: TUI Integration for Extensions and Custom Tools\nsidebar:\n  order: 1\n  label: Extension integration\n---\n\n# TUI integration for extensions and custom tools\n\nThis document covers the **current** TUI contract used by `packages/coding-agent` and `packages/tui` for extension UI, custom tool UI, and custom renderers.\n\n## What this subsystem is\n\nThe runtime has two layers:\n\n- **Rendering engine (`packages/tui`)**: differential terminal renderer, input dispatch, focus, overlays, cursor placement.\n- **Integration layer (`packages/coding-agent`)**: mounts extension/custom-tool components, wires keybindings/theme, and restores editor state.\n\n## Runtime behavior by mode\n\n| Mode | `ctx.ui.custom(...)` availability | Notes |\n| --- | --- | --- |\n| Interactive TUI | Supported | Component is mounted in the editor area, focused, and must call `done(result)` to resolve. |\n| Background/headless | Not interactive | UI context is no-op (`hasUI === false`). |\n| RPC mode | Not supported | `custom()` returns `Promise<never>` and does not mount TUI components. |\n\nIf your extension/tool can run in non-interactive mode, guard with `ctx.hasUI` / `pi.hasUI`.\n\n## Core component contract (`@f5xc-salesdemos/pi-tui`)\n\n`packages/tui/src/tui.ts` defines:\n\n```ts\nexport interface Component {\n  render(width: number): string[];\n  handleInput?(data: string): void;\n  wantsKeyRelease?: boolean;\n  invalidate(): void;\n}\n```\n\n`Focusable` is separate:\n\n```ts\nexport interface Focusable {\n  focused: boolean;\n}\n```\n\nCursor behavior uses `CURSOR_MARKER` (not `getCursorPosition`). Focused components emit the marker in rendered text; `TUI` extracts it and positions the hardware cursor.\n\n## Rendering constraints (terminal safety)\n\nYour `render(width)` output must be terminal-safe:\n\n1. **Never exceed `width` on any line**. The renderer throws if a non-image line overflows.\n2. **Measure visual width**, not string length: use `visibleWidth()`.\n3. **Truncate/wrap ANSI-aware text** with `truncateToWidth()` / `wrapTextWithAnsi()`.\n4. **Sanitize tabs/content** from external sources using `replaceTabs()` (and higher-level sanitizers in coding-agent render paths).\n\nMinimal pattern:\n\n```ts\nimport { replaceTabs, truncateToWidth } from \"@f5xc-salesdemos/pi-tui\";\n\nrender(width: number): string[] {\n  return this.lines.map(line => truncateToWidth(replaceTabs(line), width));\n}\n```\n\n## Input handling and keybindings\n\n### Raw key matching\n\nUse `matchesKey(data, \"...\")` for navigation keys and combos.\n\n### Respect user-configured app keybindings\n\nExtension UI factories receive a `KeybindingsManager` (interactive mode) so you can honor mapped actions instead of hardcoding keys:\n\n```ts\nif (keybindings.matches(data, \"interrupt\")) {\n  done(undefined);\n  return;\n}\n```\n\n### Key release/repeat events\n\nKey release events are filtered unless your component sets:\n\n```ts\nwantsKeyRelease = true;\n```\n\nThen use `isKeyRelease()` / `isKeyRepeat()` if needed.\n\n## Focus, overlays, and cursor\n\n- `TUI.setFocus(component)` routes input to that component.\n- Overlay APIs exist in `TUI` (`showOverlay`, `OverlayHandle`), but extension `ctx.ui.custom` mounting in interactive mode currently replaces the editor component area directly.\n- The `custom(..., options?: { overlay?: boolean })` option exists in extension types; interactive extension mounting currently ignores this option.\n\n## Mount points and return contracts\n\n## 1) Extension UI (`ExtensionUIContext`)\n\nCurrent signature (`extensibility/extensions/types.ts`):\n\n```ts\ncustom<T>(\n  factory: (\n    tui: TUI,\n    theme: Theme,\n    keybindings: KeybindingsManager,\n    done: (result: T) => void,\n  ) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,\n  options?: { overlay?: boolean },\n): Promise<T>\n```\n\nBehavior in interactive mode (`extension-ui-controller.ts`):\n\n- Saves editor text.\n- Replaces editor component with your component.\n- Focuses your component.\n- On `done(result)`: calls `component.dispose?.()`, restores editor + text, focuses editor, resolves promise.\n\nSo `done(...)` is mandatory for completion.\n\n## 2) Hook/custom-tool UI context (legacy typing)\n\n`HookUIContext.custom` is typed as `(tui, theme, done)` in hook/custom-tool types.\nUnderlying interactive implementation calls factories with `(tui, theme, keybindings, done)`. JS consumers can use the extra arg; type-level compatibility still reflects the 3-arg legacy signature.\n\nCustom tools typically use the same UI entrypoint via the factory-scoped `pi.ui` object, then return the selected value in normal tool content:\n\n```ts\nasync execute(toolCallId, params, onUpdate, ctx, signal) {\n  if (!pi.hasUI) {\n    return { content: [{ type: \"text\", text: \"UI unavailable\" }] };\n  }\n\n  const picked = await pi.ui.custom<string | undefined>((tui, theme, done) => {\n    const component = new MyPickerComponent(done, signal);\n    return component;\n  });\n\n  return { content: [{ type: \"text\", text: picked ? `Picked: ${picked}` : \"Cancelled\" }] };\n}\n```\n\n## 3) Custom tool call/result renderers\n\nCustom tools and extension tools can return components from:\n\n- `renderCall(args, theme)`\n- `renderResult(result, options, theme, args?)`\n\n`options` currently includes:\n\n- `expanded: boolean`\n- `isPartial: boolean`\n- `spinnerFrame?: number`\n\nThese renderers are mounted by `ToolExecutionComponent`.\n\n## Lifecycle and cancellation\n\n- `dispose()` is optional at type level but should be implemented when you own timers, subprocesses, watchers, sockets, or overlays.\n- `done(...)` should be called exactly once from your component flow.\n- For cancellable long-running UI, pair `CancellableLoader` with `AbortSignal` and call `done(...)` from `onAbort`.\n\nExample cancellation pattern:\n\n```ts\nconst loader = new CancellableLoader(tui, theme.fg(\"accent\"), theme.fg(\"muted\"), \"Working...\");\nloader.onAbort = () => done(undefined);\nvoid doWork(loader.signal).then(result => done(result));\nreturn loader;\n```\n\n## Realistic custom component example (extension command)\n\n```ts\nimport type { Component } from \"@f5xc-salesdemos/pi-tui\";\nimport { SelectList, matchesKey, replaceTabs, truncateToWidth } from \"@f5xc-salesdemos/pi-tui\";\nimport { getSelectListTheme, type ExtensionAPI } from \"@f5xc-salesdemos/xcsh\";\n\nclass Picker implements Component {\n  list: SelectList;\n  keybindings: any;\n  done: (value: string | undefined) => void;\n\n  constructor(\n    items: Array<{ value: string; label: string }>,\n    keybindings: any,\n    done: (value: string | undefined) => void,\n  ) {\n    this.list = new SelectList(items, 8, getSelectListTheme());\n    this.keybindings = keybindings;\n    this.done = done;\n    this.list.onSelect = item => this.done(item.value);\n    this.list.onCancel = () => this.done(undefined);\n  }\n\n  handleInput(data: string): void {\n    if (this.keybindings.matches(data, \"interrupt\")) {\n      this.done(undefined);\n      return;\n    }\n    this.list.handleInput(data);\n  }\n\n  render(width: number): string[] {\n    return this.list.render(width).map(line => truncateToWidth(replaceTabs(line), width));\n  }\n\n  invalidate(): void {\n    this.list.invalidate();\n  }\n}\n\nexport default function extension(pi: ExtensionAPI): void {\n  pi.registerCommand(\"pick-model\", {\n    description: \"Pick a model profile\",\n    handler: async (_args, ctx) => {\n      if (!ctx.hasUI) return;\n\n      const selected = await ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) => {\n        const items = [\n          { value: \"fast\", label: theme.fg(\"accent\", \"Fast\") },\n          { value: \"balanced\", label: \"Balanced\" },\n          { value: \"quality\", label: \"Quality\" },\n        ];\n        return new Picker(items, keybindings, done);\n      });\n\n      if (selected) ctx.ui.notify(`Selected profile: ${selected}`, \"info\");\n    },\n  });\n}\n```\n\n## Key implementation files\n\n- `packages/tui/src/tui.ts` — `Component`, `Focusable`, cursor marker, focus, overlay, input dispatch.\n- `packages/tui/src/utils.ts` — width/truncation/sanitization primitives.\n- `packages/tui/src/keys.ts` / `keybindings.ts` — key parsing and configurable action mapping.\n- `packages/coding-agent/src/modes/controllers/extension-ui-controller.ts` — interactive mounting/unmounting for extension/hook/custom-tool UI.\n- `packages/coding-agent/src/extensibility/extensions/types.ts` — extension UI and renderer contracts.\n- `packages/coding-agent/src/extensibility/hooks/types.ts` — hook UI contract (legacy custom signature).\n- `packages/coding-agent/src/extensibility/custom-tools/types.ts` — custom tool execute/render contracts.\n- `packages/coding-agent/src/modes/components/tool-execution.ts` — mounting `renderCall`/`renderResult` components and partial-state options.\n- `packages/coding-agent/src/tools/context.ts` — tool UI context propagation (`hasUI`, `ui`).\n",

package/src/modes/components/settings-defs.ts

@@ -221,6 +221,15 @@ const OPTION_PROVIDERS: Partial<Record<SettingPath, OptionProvider>> = {
 		{ value: "15", label: "15 items" },
 		{ value: "20", label: "20 items" },
 	],
+	// Chord binding timeout (clamped to [200, 5000] ms at read time)
+	"keybindings.chordTimeout": [
+		{ value: "200", label: "200 ms", description: "Minimum — fastest abandon" },
+		{ value: "500", label: "500 ms", description: "Snappy" },
+		{ value: "1000", label: "1 second", description: "Default" },
+		{ value: "2000", label: "2 seconds", description: "Relaxed" },
+		{ value: "3000", label: "3 seconds" },
+		{ value: "5000", label: "5 seconds", description: "Maximum" },
+	],
 	// Ask timeout
 	"ask.timeout": [
 		{ value: "0", label: "Disabled" },

package/src/modes/components/status-line/segments.ts

@@ -174,17 +174,20 @@ const gitSegment: StatusLineSegment = {
 
 		if (!content) return { content: "", visible: false };
 
-		// State priority: conflicted > modified > untracked > clean (matches p10k)
+		// State priority: conflicted > unstaged(dirty) > staged-only > untracked > clean (issue #242)
 		const hasConflict = gitStatus && gitStatus.conflicted > 0;
-		const hasModified = gitStatus && (gitStatus.staged > 0 || gitStatus.unstaged > 0);
+		const hasUnstaged = gitStatus && gitStatus.unstaged > 0;
+		const hasStaged = gitStatus && gitStatus.staged > 0;
 		const hasUntracked = gitStatus && gitStatus.untracked > 0;
 		const [bgToken, fgToken] = hasConflict
 			? (["statusLineGitConflictBg", "statusLineGitConflictFg"] as const)
-			: hasModified
+			: hasUnstaged
 				? (["statusLineGitDirtyBg", "statusLineGitDirtyFg"] as const)
-				: hasUntracked
-					? (["statusLineGitUntrackedBg", "statusLineGitUntrackedFg"] as const)
-					: (["statusLineGitCleanBg", "statusLineGitCleanFg"] as const);
+				: hasStaged
+					? (["statusLineGitStagedBg", "statusLineGitStagedFg"] as const)
+					: hasUntracked
+						? (["statusLineGitUntrackedBg", "statusLineGitUntrackedFg"] as const)
+						: (["statusLineGitCleanBg", "statusLineGitCleanFg"] as const);
 
 		return {
 			content: theme.fg(fgToken, content),

package/src/modes/components/status-line.ts

@@ -3,6 +3,7 @@ import type { AssistantMessage } from "@f5xc-salesdemos/pi-ai";
 import { type Component, truncateToWidth, visibleWidth } from "@f5xc-salesdemos/pi-tui";
 import { formatCount, getShellPwd } from "@f5xc-salesdemos/pi-utils";
 import { $ } from "bun";
+import { formatKeyHint } from "../../config/keybindings";
 import { settings } from "../../config/settings";
 import type { StatusLinePreset, StatusLineSegmentId, StatusLineSeparatorStyle } from "../../config/settings-schema";
 import { theme } from "../../modes/theme/theme";
@@ -62,6 +63,10 @@ export class StatusLineComponent implements Component {
 	#sessionStartTime: number = Date.now();
 	#planModeStatus: { enabled: boolean; paused: boolean } | null = null;
 	#cwd: string = getShellPwd();
+	// Display text for a pending chord leader (e.g. "Ctrl+X-") or null when no
+	// chord is pending. Populated by the InputController's ChordDispatcher
+	// callbacks; rendered as a dim right-aligned segment in the top border.
+	#chordPending: string | null = null;
 
 	// Git status caching (1s TTL)
 	#cachedGitStatus: {
@@ -116,6 +121,33 @@ export class StatusLineComponent implements Component {
 		this.#planModeStatus = status ?? null;
 	}
 
+	/**
+	 * Called by the InputController's ChordDispatcher when a chord leader is
+	 * pressed. Displays e.g. "Ctrl+X-" in the top border so the user knows a
+	 * partial chord is active and the dispatcher is waiting for the 2nd key.
+	 */
+	setChordPending(leader: string): void {
+		// formatKeyHint's param type is KeyId (a template-literal union) but its
+		// implementation only needs a "+"-separated key string, which is exactly
+		// what the chord dispatcher hands us. Cast so callers can pass a plain
+		// string without having to thread KeyId through the controller API.
+		const next = `${formatKeyHint(leader as Parameters<typeof formatKeyHint>[0])}-`;
+		if (this.#chordPending === next) return;
+		this.#chordPending = next;
+		this.#onStatusChanged?.();
+	}
+
+	/**
+	 * Called when the chord is dispatched, abandoned, or times out. Clears the
+	 * pending indicator. No-op when no chord is pending (avoids spurious
+	 * re-renders).
+	 */
+	clearChordPending(): void {
+		if (this.#chordPending === null) return;
+		this.#chordPending = null;
+		this.#onStatusChanged?.();
+	}
+
 	setHookStatus(key: string, text: string | undefined): void {
 		if (text === undefined) {
 			this.#hookStatuses.delete(key);
@@ -486,6 +518,18 @@ export class StatusLineComponent implements Component {
 			});
 		}
 
+		// Chord-pending indicator: rightmost segment, dim style. Appended last
+		// so it visually sits at the far right of the top border (after any
+		// background-jobs indicator). Swallowed by truncation-from-right in the
+		// sizing loop below if the terminal is too narrow, which is acceptable.
+		if (this.#chordPending !== null) {
+			rightParts.push({
+				content: theme.fg("dim", this.#chordPending),
+				bg: defaultBg,
+				fg: defaultFg,
+			});
+		}
+
 		const topFillWidth = Math.max(0, width);
 		const left = [...leftParts];
 		const right = [...rightParts];

package/src/modes/controllers/chord-routing.ts

@@ -0,0 +1,37 @@
+import type { ChordResult } from "@f5xc-salesdemos/pi-tui";
+
+/**
+ * Sinks invoked by routeChordResult. Exactly one of these fires per call
+ * (or neither, for pending / abandoned — which are intentionally swallowed
+ * so the user's partial chord never leaks into the editor buffer).
+ */
+export interface ChordRouteSinks {
+	action: (actionId: string) => void;
+	editor: (key: string) => void;
+}
+
+/**
+ * Pure routing: given a ChordResult, dispatch to the right sink.
+ *
+ * - `dispatched` → action sink (keybinding matched a complete chord)
+ * - `passthrough` → editor sink (key is not a chord leader or match)
+ * - `pending` / `abandoned` → swallowed (Emacs convention: an abandoned
+ *   leader does not emit the second key into the buffer)
+ *
+ * Extracted so tests can exercise routing logic without constructing a
+ * full InputController.
+ */
+export function routeChordResult(result: ChordResult, key: string, sinks: ChordRouteSinks): void {
+	switch (result.kind) {
+		case "dispatched":
+			sinks.action(result.action);
+			return;
+		case "passthrough":
+			sinks.editor(key);
+			return;
+		case "pending":
+		case "abandoned":
+			// Swallowed — Emacs convention for abandoned leaders.
+			return;
+	}
+}

package/src/modes/controllers/input-controller.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import { type AgentMessage, ThinkingLevel } from "@f5xc-salesdemos/pi-agent-core";
 import { sanitizeText } from "@f5xc-salesdemos/pi-natives";
-import type { AutocompleteProvider, SlashCommand } from "@f5xc-salesdemos/pi-tui";
+import { type AutocompleteProvider, ChordDispatcher, type SlashCommand } from "@f5xc-salesdemos/pi-tui";
 import { $env } from "@f5xc-salesdemos/pi-utils";
 import { settings } from "../../config/settings";
 import { createStreamingAssistantGutter } from "../../modes/components/gutter-block";
@@ -26,9 +26,63 @@ function isExpandable(obj: unknown): obj is Expandable {
 }
 
 export class InputController {
+	#dispatcher: ChordDispatcher | null = null;
+
 	constructor(private ctx: InteractiveModeContext) {}
 
+	/**
+	 * Rebuild the chord dispatcher from the current keybindings + settings.
+	 * Called from setupKeyHandlers so a subsequent keybindings reload / settings
+	 * change can re-init without leaking the previous pending-timer.
+	 *
+	 * The dispatcher callbacks drive the status-line chord-pending indicator.
+	 * Optional-chaining is deliberate: Task 11 adds setChordPending/clearChordPending
+	 * on StatusLineComponent, so this wiring stays safe before Task 11 lands.
+	 */
+	#initChordDispatcher(): void {
+		this.#dispatcher?.dispose();
+		this.#dispatcher = null;
+		// Feature-detect the context: partial mocks in tests may omit these methods.
+		// Production always satisfies both interfaces (see config/keybindings.ts,
+		// config/settings.ts), so the no-op branch here only protects test fakes.
+		const getBindings = this.ctx.keybindings?.getChordBindings?.bind(this.ctx.keybindings);
+		const getTimeout = this.ctx.settings?.getChordTimeoutMs?.bind(this.ctx.settings);
+		if (!getBindings || !getTimeout) return;
+		const bindings = getBindings();
+		const timeoutMs = getTimeout();
+		// Optional-chaining on methods that Task 11 adds to StatusLineComponent.
+		// Typed loosely so Task 10 can ship before Task 11 wires the methods.
+		const statusLine = this.ctx.statusLine as
+			| {
+					setChordPending?: (leader: string) => void;
+					clearChordPending?: () => void;
+			  }
+			| undefined;
+		this.#dispatcher = new ChordDispatcher(bindings, timeoutMs, {
+			onPending: leader => statusLine?.setChordPending?.(leader),
+			onCleared: () => statusLine?.clearChordPending?.(),
+		});
+	}
+
+	/**
+	 * Dispose of the chord dispatcher (clears any pending chord timer).
+	 * Exposed for tests and for the outer controller lifecycle.
+	 */
+	dispose(): void {
+		this.#dispatcher?.dispose();
+		this.#dispatcher = null;
+	}
+
+	/**
+	 * Exposed for tests: returns the current dispatcher instance (or null if
+	 * setupKeyHandlers has not been called yet).
+	 */
+	getChordDispatcher(): ChordDispatcher | null {
+		return this.#dispatcher;
+	}
+
 	setupKeyHandlers(): void {
+		this.#initChordDispatcher();
 		this.ctx.editor.setActionKeys("app.interrupt", this.ctx.keybindings.getKeys("app.interrupt"));
 		this.ctx.editor.shouldBypassAutocompleteOnEscape = () =>
 			Boolean(

package/src/modes/theme/defaults/xcsh-dark.json

@@ -90,11 +90,12 @@
 		"statusLinePathFg": 254,
 		"statusLineGitCleanBg": 2,
 		"statusLineGitDirtyBg": 3,
+		"statusLineGitStagedBg": 64,
 		"statusLineGitUntrackedBg": 39,
 		"statusLineGitConflictBg": 1,
-		"statusLineGitFg": 0,
 		"statusLineGitCleanFg": 0,
 		"statusLineGitDirtyFg": 0,
+		"statusLineGitStagedFg": 0,
 		"statusLineGitUntrackedFg": 0,
 		"statusLineGitConflictFg": 7,
 		"statusLinePlanModeBg": 236,

package/src/modes/theme/defaults/xcsh-light.json

@@ -86,27 +86,28 @@
 		"statusLineOutput": "f5DarkRed",
 		"statusLineCost": "#ffb347",
 		"statusLineSubagents": "f5Red",
-		"statusLineOsIconBg": 7,
-		"statusLineOsIconFg": 232,
-		"statusLinePathBg": 4,
-		"statusLinePathFg": 254,
-		"statusLineGitCleanBg": 2,
-		"statusLineGitDirtyBg": 3,
-		"statusLineGitUntrackedBg": 39,
-		"statusLineGitConflictBg": 1,
-		"statusLineGitFg": 0,
-		"statusLineGitCleanFg": 0,
-		"statusLineGitDirtyFg": 0,
-		"statusLineGitUntrackedFg": 0,
-		"statusLineGitConflictFg": 7,
-		"statusLinePlanModeBg": 236,
-		"statusLinePlanModeFg": 117,
-		"statusLineContextPctBg": 238,
-		"statusLineContextPctFg": 255,
-		"statusLineContextPctNormalBg": 17,
-		"statusLineContextPctWarningBg": 22,
-		"statusLineContextPctPurpleBg": 94,
-		"statusLineContextPctErrorBg": 88,
+		"statusLineOsIconBg": 236,
+		"statusLineOsIconFg": 255,
+		"statusLinePathBg": 24,
+		"statusLinePathFg": 255,
+		"statusLineGitCleanBg": 28,
+		"statusLineGitDirtyBg": 136,
+		"statusLineGitStagedBg": 100,
+		"statusLineGitUntrackedBg": 26,
+		"statusLineGitConflictBg": 88,
+		"statusLineGitCleanFg": 255,
+		"statusLineGitDirtyFg": 255,
+		"statusLineGitStagedFg": 255,
+		"statusLineGitUntrackedFg": 255,
+		"statusLineGitConflictFg": 255,
+		"statusLinePlanModeBg": 223,
+		"statusLinePlanModeFg": 238,
+		"statusLineContextPctBg": 253,
+		"statusLineContextPctFg": 238,
+		"statusLineContextPctNormalBg": 189,
+		"statusLineContextPctWarningBg": 194,
+		"statusLineContextPctPurpleBg": 225,
+		"statusLineContextPctErrorBg": 224,
 		"statusLineProfileF5xcBg": "f5Red",
 		"statusLineProfileF5xcFg": 231,
 		"pythonMode": "warningAmber",

package/src/modes/theme/theme-schema.json

@@ -101,7 +101,36 @@
 				"statusLineUntracked",
 				"statusLineOutput",
 				"statusLineCost",
-				"statusLineSubagents"
+				"statusLineSubagents",
+				"chromeAccent",
+				"spinnerAccent",
+				"contentAccent",
+				"gutterSuccess",
+				"gutterWarning",
+				"statusLineOsIconBg",
+				"statusLineOsIconFg",
+				"statusLinePathBg",
+				"statusLinePathFg",
+				"statusLineGitCleanBg",
+				"statusLineGitCleanFg",
+				"statusLineGitDirtyBg",
+				"statusLineGitDirtyFg",
+				"statusLineGitStagedBg",
+				"statusLineGitStagedFg",
+				"statusLineGitUntrackedBg",
+				"statusLineGitUntrackedFg",
+				"statusLineGitConflictBg",
+				"statusLineGitConflictFg",
+				"statusLinePlanModeBg",
+				"statusLinePlanModeFg",
+				"statusLineContextPctBg",
+				"statusLineContextPctFg",
+				"statusLineContextPctNormalBg",
+				"statusLineContextPctWarningBg",
+				"statusLineContextPctPurpleBg",
+				"statusLineContextPctErrorBg",
+				"statusLineProfileF5xcBg",
+				"statusLineProfileF5xcFg"
 			],
 			"properties": {
 				"accent": {
@@ -338,15 +367,15 @@
 				},
 				"statusLinePath": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line path segment"
+					"description": "Status line path text color (hex). Used for non-powerline rendering. See 'statusLinePathBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineGitClean": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line git clean"
+					"description": "Status line git clean text color (hex). Used for non-powerline rendering. See 'statusLineGitCleanBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineGitDirty": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line git dirty"
+					"description": "Status line git dirty text color (hex). Used for non-powerline rendering. See 'statusLineGitDirtyBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineContext": {
 					"$ref": "#/$defs/colorValue",
@@ -358,15 +387,15 @@
 				},
 				"statusLineStaged": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line git staged"
+					"description": "Status line git staged count text color (hex). Used for non-powerline rendering. See 'statusLineGitStagedBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineDirty": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line git dirty count"
+					"description": "Status line git dirty count text color (hex). Used for non-powerline rendering. See 'statusLineGitDirtyBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineUntracked": {
 					"$ref": "#/$defs/colorValue",
-					"description": "Status line git untracked"
+					"description": "Status line git untracked text color (hex). Used for non-powerline rendering. See 'statusLineGitUntrackedBg'/'Fg' for the corresponding powerline palette indices."
 				},
 				"statusLineOutput": {
 					"$ref": "#/$defs/colorValue",
@@ -379,6 +408,118 @@
 				"statusLineSubagents": {
 					"$ref": "#/$defs/colorValue",
 					"description": "Status line subagents segment"
+				},
+				"chromeAccent": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Chrome / UI accent color (non-content accent). Defaults to `accent` when omitted — but in this project it is always overridden per theme."
+				},
+				"spinnerAccent": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Spinner accent color. Defaults to `accent` when omitted — but in this project it is always overridden per theme."
+				},
+				"contentAccent": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Content accent color (distinct from UI chrome). Defaults to `accent` when omitted — but in this project it is always overridden per theme."
+				},
+				"gutterWarning": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Done-state tool/command gutter dot color for warning outcomes. Defaults to `warning` when omitted — but in this project it is always overridden per theme."
+				},
+				"statusLineOsIconBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline OS icon segment background. Independent from hex-based text colors used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineOsIconFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline OS icon segment foreground. Independent from hex-based text colors used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLinePathBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline path segment background. Independent from the hex-based `statusLinePath` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLinePathFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline path segment foreground. Independent from the hex-based `statusLinePath` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitCleanBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-clean segment background. Independent from the hex-based `statusLineGitClean` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitCleanFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-clean segment foreground. Independent from the hex-based `statusLineGitClean` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitDirtyBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-dirty (unstaged) segment background. Independent from the hex-based `statusLineGitDirty` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitDirtyFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-dirty (unstaged) segment foreground. Independent from the hex-based `statusLineGitDirty` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitStagedBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-staged-only segment background. Rendered when the repo has staged changes but no unstaged or conflicted changes. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitStagedFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-staged-only segment foreground. Rendered when the repo has staged changes but no unstaged or conflicted changes. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitUntrackedBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-untracked-only segment background. Independent from the hex-based `statusLineUntracked` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitUntrackedFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-untracked-only segment foreground. Independent from the hex-based `statusLineUntracked` text color used for non-powerline rendering. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitConflictBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-conflict segment background. See issue #242 for the two-domain color model."
+				},
+				"statusLineGitConflictFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline git-conflict segment foreground. See issue #242 for the two-domain color model."
+				},
+				"statusLinePlanModeBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline plan-mode segment background. See issue #242 for the two-domain color model."
+				},
+				"statusLinePlanModeFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline plan-mode segment foreground. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment default background. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment default foreground. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctNormalBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment background in the normal tier. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctWarningBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment background in the warning tier. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctPurpleBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment background in the purple tier. See issue #242 for the two-domain color model."
+				},
+				"statusLineContextPctErrorBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline context-percent segment background in the error tier. See issue #242 for the two-domain color model."
+				},
+				"statusLineProfileF5xcBg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index OR color reference for the powerline F5 XC profile segment background. Stays F5 brand red across light and dark themes. See issue #242 for the two-domain color model."
+				},
+				"statusLineProfileF5xcFg": {
+					"$ref": "#/$defs/colorValue",
+					"description": "256-color palette index for the powerline F5 XC profile segment foreground. See issue #242 for the two-domain color model."
 				}
 			},
 			"additionalProperties": false

package/src/modes/theme/theme.ts

@@ -826,114 +826,118 @@ const ThemeJsonSchema = Type.Object({
 	$schema: Type.Optional(Type.String()),
 	name: Type.String(),
 	vars: Type.Optional(Type.Record(Type.String(), ColorValueSchema)),
-	colors: Type.Object({
-		// Core UI (12 colors)
-		accent: ColorValueSchema,
-		chromeAccent: Type.Optional(ColorValueSchema),
-		spinnerAccent: Type.Optional(ColorValueSchema),
-		contentAccent: Type.Optional(ColorValueSchema),
-		border: ColorValueSchema,
-		borderAccent: ColorValueSchema,
-		borderMuted: ColorValueSchema,
-		success: ColorValueSchema,
-		error: ColorValueSchema,
-		warning: ColorValueSchema,
-		muted: ColorValueSchema,
-		dim: ColorValueSchema,
-		gutterSuccess: Type.Optional(ColorValueSchema),
-		gutterError: Type.Optional(ColorValueSchema),
-		gutterWarning: Type.Optional(ColorValueSchema),
-		text: ColorValueSchema,
-		thinkingText: ColorValueSchema,
-		// Backgrounds & Content Text (11 colors)
-		selectedBg: ColorValueSchema,
-		userMessageBg: ColorValueSchema,
-		userMessageText: ColorValueSchema,
-		customMessageBg: ColorValueSchema,
-		customMessageText: ColorValueSchema,
-		customMessageLabel: ColorValueSchema,
-		toolPendingBg: ColorValueSchema,
-		toolSuccessBg: ColorValueSchema,
-		toolErrorBg: ColorValueSchema,
-		toolTitle: ColorValueSchema,
-		toolOutput: ColorValueSchema,
-		// Markdown (10 colors)
-		mdHeading: ColorValueSchema,
-		mdLink: ColorValueSchema,
-		mdLinkUrl: ColorValueSchema,
-		mdCode: ColorValueSchema,
-		mdCodeBlock: ColorValueSchema,
-		mdCodeBlockBorder: ColorValueSchema,
-		mdQuote: ColorValueSchema,
-		mdQuoteBorder: ColorValueSchema,
-		mdHr: ColorValueSchema,
-		mdListBullet: ColorValueSchema,
-		// Tool Diffs (3 colors)
-		toolDiffAdded: ColorValueSchema,
-		toolDiffRemoved: ColorValueSchema,
-		toolDiffContext: ColorValueSchema,
-		// Syntax Highlighting (9 colors)
-		syntaxComment: ColorValueSchema,
-		syntaxKeyword: ColorValueSchema,
-		syntaxFunction: ColorValueSchema,
-		syntaxVariable: ColorValueSchema,
-		syntaxString: ColorValueSchema,
-		syntaxNumber: ColorValueSchema,
-		syntaxType: ColorValueSchema,
-		syntaxOperator: ColorValueSchema,
-		syntaxPunctuation: ColorValueSchema,
-		syntaxControl: ColorValueSchema,
-		// Thinking Level Borders (6 colors)
-		thinkingOff: ColorValueSchema,
-		thinkingMinimal: ColorValueSchema,
-		thinkingLow: ColorValueSchema,
-		thinkingMedium: ColorValueSchema,
-		thinkingHigh: ColorValueSchema,
-		thinkingXhigh: ColorValueSchema,
-		// Bash Mode (1 color)
-		bashMode: ColorValueSchema,
-		// Python Mode (1 color)
-		pythonMode: ColorValueSchema,
-		// Footer Status Line
-		statusLineBg: ColorValueSchema,
-		statusLineSep: ColorValueSchema,
-		statusLineModel: ColorValueSchema,
-		statusLinePath: ColorValueSchema,
-		statusLineGitClean: ColorValueSchema,
-		statusLineGitDirty: ColorValueSchema,
-		statusLineContext: ColorValueSchema,
-		statusLineSpend: ColorValueSchema,
-		statusLineStaged: ColorValueSchema,
-		statusLineDirty: ColorValueSchema,
-		statusLineUntracked: ColorValueSchema,
-		statusLineOutput: ColorValueSchema,
-		statusLineCost: ColorValueSchema,
-		statusLineSubagents: ColorValueSchema,
-		// Powerline segment backgrounds
-		statusLineOsIconBg: Type.Optional(ColorValueSchema),
-		statusLineOsIconFg: Type.Optional(ColorValueSchema),
-		statusLinePathBg: Type.Optional(ColorValueSchema),
-		statusLinePathFg: Type.Optional(ColorValueSchema),
-		statusLineGitCleanBg: Type.Optional(ColorValueSchema),
-		statusLineGitDirtyBg: Type.Optional(ColorValueSchema),
-		statusLineGitUntrackedBg: Type.Optional(ColorValueSchema),
-		statusLineGitConflictBg: Type.Optional(ColorValueSchema),
-		statusLineGitFg: Type.Optional(ColorValueSchema),
-		statusLineGitCleanFg: Type.Optional(ColorValueSchema),
-		statusLineGitDirtyFg: Type.Optional(ColorValueSchema),
-		statusLineGitUntrackedFg: Type.Optional(ColorValueSchema),
-		statusLineGitConflictFg: Type.Optional(ColorValueSchema),
-		statusLinePlanModeBg: Type.Optional(ColorValueSchema),
-		statusLinePlanModeFg: Type.Optional(ColorValueSchema),
-		statusLineContextPctBg: Type.Optional(ColorValueSchema),
-		statusLineContextPctFg: Type.Optional(ColorValueSchema),
-		statusLineContextPctNormalBg: Type.Optional(ColorValueSchema),
-		statusLineContextPctWarningBg: Type.Optional(ColorValueSchema),
-		statusLineContextPctPurpleBg: Type.Optional(ColorValueSchema),
-		statusLineContextPctErrorBg: Type.Optional(ColorValueSchema),
-		statusLineProfileF5xcBg: Type.Optional(ColorValueSchema),
-		statusLineProfileF5xcFg: Type.Optional(ColorValueSchema),
-	}),
+	colors: Type.Object(
+		{
+			// Core UI (12 colors)
+			accent: ColorValueSchema,
+			chromeAccent: ColorValueSchema,
+			spinnerAccent: ColorValueSchema,
+			contentAccent: ColorValueSchema,
+			border: ColorValueSchema,
+			borderAccent: ColorValueSchema,
+			borderMuted: ColorValueSchema,
+			success: ColorValueSchema,
+			error: ColorValueSchema,
+			warning: ColorValueSchema,
+			muted: ColorValueSchema,
+			dim: ColorValueSchema,
+			gutterSuccess: ColorValueSchema,
+			gutterError: Type.Optional(ColorValueSchema),
+			gutterWarning: ColorValueSchema,
+			text: ColorValueSchema,
+			thinkingText: ColorValueSchema,
+			// Backgrounds & Content Text (11 colors)
+			selectedBg: ColorValueSchema,
+			userMessageBg: ColorValueSchema,
+			userMessageText: ColorValueSchema,
+			customMessageBg: ColorValueSchema,
+			customMessageText: ColorValueSchema,
+			customMessageLabel: ColorValueSchema,
+			toolPendingBg: ColorValueSchema,
+			toolSuccessBg: ColorValueSchema,
+			toolErrorBg: ColorValueSchema,
+			toolTitle: ColorValueSchema,
+			toolOutput: ColorValueSchema,
+			// Markdown (10 colors)
+			mdHeading: ColorValueSchema,
+			mdLink: ColorValueSchema,
+			mdLinkUrl: ColorValueSchema,
+			mdCode: ColorValueSchema,
+			mdCodeBlock: ColorValueSchema,
+			mdCodeBlockBorder: ColorValueSchema,
+			mdQuote: ColorValueSchema,
+			mdQuoteBorder: ColorValueSchema,
+			mdHr: ColorValueSchema,
+			mdListBullet: ColorValueSchema,
+			// Tool Diffs (3 colors)
+			toolDiffAdded: ColorValueSchema,
+			toolDiffRemoved: ColorValueSchema,
+			toolDiffContext: ColorValueSchema,
+			// Syntax Highlighting (9 colors)
+			syntaxComment: ColorValueSchema,
+			syntaxKeyword: ColorValueSchema,
+			syntaxFunction: ColorValueSchema,
+			syntaxVariable: ColorValueSchema,
+			syntaxString: ColorValueSchema,
+			syntaxNumber: ColorValueSchema,
+			syntaxType: ColorValueSchema,
+			syntaxOperator: ColorValueSchema,
+			syntaxPunctuation: ColorValueSchema,
+			syntaxControl: ColorValueSchema,
+			// Thinking Level Borders (6 colors)
+			thinkingOff: ColorValueSchema,
+			thinkingMinimal: ColorValueSchema,
+			thinkingLow: ColorValueSchema,
+			thinkingMedium: ColorValueSchema,
+			thinkingHigh: ColorValueSchema,
+			thinkingXhigh: ColorValueSchema,
+			// Bash Mode (1 color)
+			bashMode: ColorValueSchema,
+			// Python Mode (1 color)
+			pythonMode: ColorValueSchema,
+			// Footer Status Line
+			statusLineBg: ColorValueSchema,
+			statusLineSep: ColorValueSchema,
+			statusLineModel: ColorValueSchema,
+			statusLinePath: ColorValueSchema,
+			statusLineGitClean: ColorValueSchema,
+			statusLineGitDirty: ColorValueSchema,
+			statusLineContext: ColorValueSchema,
+			statusLineSpend: ColorValueSchema,
+			statusLineStaged: ColorValueSchema,
+			statusLineDirty: ColorValueSchema,
+			statusLineUntracked: ColorValueSchema,
+			statusLineOutput: ColorValueSchema,
+			statusLineCost: ColorValueSchema,
+			statusLineSubagents: ColorValueSchema,
+			// Powerline segment backgrounds
+			statusLineOsIconBg: ColorValueSchema,
+			statusLineOsIconFg: ColorValueSchema,
+			statusLinePathBg: ColorValueSchema,
+			statusLinePathFg: ColorValueSchema,
+			statusLineGitCleanBg: ColorValueSchema,
+			statusLineGitDirtyBg: ColorValueSchema,
+			statusLineGitStagedBg: ColorValueSchema,
+			statusLineGitUntrackedBg: ColorValueSchema,
+			statusLineGitConflictBg: ColorValueSchema,
+			statusLineGitCleanFg: ColorValueSchema,
+			statusLineGitDirtyFg: ColorValueSchema,
+			statusLineGitStagedFg: ColorValueSchema,
+			statusLineGitUntrackedFg: ColorValueSchema,
+			statusLineGitConflictFg: ColorValueSchema,
+			statusLinePlanModeBg: ColorValueSchema,
+			statusLinePlanModeFg: ColorValueSchema,
+			statusLineContextPctBg: ColorValueSchema,
+			statusLineContextPctFg: ColorValueSchema,
+			statusLineContextPctNormalBg: ColorValueSchema,
+			statusLineContextPctWarningBg: ColorValueSchema,
+			statusLineContextPctPurpleBg: ColorValueSchema,
+			statusLineContextPctErrorBg: ColorValueSchema,
+			statusLineProfileF5xcBg: ColorValueSchema,
+			statusLineProfileF5xcFg: ColorValueSchema,
+		},
+		{ additionalProperties: false },
+	),
 	export: Type.Optional(
 		Type.Object({
 			pageBg: Type.Optional(ColorValueSchema),
@@ -1022,13 +1026,14 @@ export type ThemeColor =
 	| "statusLinePathFg"
 	| "statusLineGitCleanBg"
 	| "statusLineGitDirtyBg"
+	| "statusLineGitStagedBg"
 	| "statusLineGitUntrackedBg"
 	| "statusLineGitConflictBg"
 	| "statusLineGitCleanFg"
 	| "statusLineGitDirtyFg"
+	| "statusLineGitStagedFg"
 	| "statusLineGitUntrackedFg"
 	| "statusLineGitConflictFg"
-	| "statusLineGitFg"
 	| "statusLinePlanModeBg"
 	| "statusLinePlanModeFg"
 	| "statusLineContextPctBg"
@@ -1114,11 +1119,12 @@ const THEME_COLOR_RECORD = {
 	statusLinePathFg: true,
 	statusLineGitCleanBg: true,
 	statusLineGitDirtyBg: true,
+	statusLineGitStagedBg: true,
 	statusLineGitUntrackedBg: true,
 	statusLineGitConflictBg: true,
-	statusLineGitFg: true,
 	statusLineGitCleanFg: true,
 	statusLineGitDirtyFg: true,
+	statusLineGitStagedFg: true,
 	statusLineGitUntrackedFg: true,
 	statusLineGitConflictFg: true,
 	statusLinePlanModeBg: true,
@@ -1342,38 +1348,8 @@ export class Theme {
 		for (const [key, value] of Object.entries(fgColors) as [ThemeColor, string | number][]) {
 			this.#fgColors[key] = fgAnsi(value, mode);
 		}
-		// Fallback: chromeAccent and contentAccent inherit from accent when not defined
-		this.#fgColors.chromeAccent ??= this.#fgColors.accent;
-		this.#fgColors.spinnerAccent ??= this.#fgColors.accent;
-		// Gutter outcome colors inherit from success/error unless a theme overrides them
-		this.#fgColors.gutterSuccess ??= this.#fgColors.success;
+		// gutterError remains optional — neither shipped theme carries it
 		this.#fgColors.gutterError ??= this.#fgColors.error;
-		this.#fgColors.gutterWarning ??= this.#fgColors.warning;
-		// Powerline segment bg/fg fallbacks
-		this.#fgColors.statusLineOsIconBg ??= this.#fgColors.muted;
-		this.#fgColors.statusLineOsIconFg ??= this.#fgColors.text;
-		this.#fgColors.statusLinePathBg ??= this.#fgColors.statusLinePath;
-		this.#fgColors.statusLinePathFg ??= this.#fgColors.text;
-		this.#fgColors.statusLineGitCleanBg ??= this.#fgColors.statusLineGitClean;
-		this.#fgColors.statusLineGitDirtyBg ??= this.#fgColors.statusLineGitDirty;
-		this.#fgColors.statusLineGitUntrackedBg ??= this.#fgColors.statusLineUntracked;
-		this.#fgColors.statusLineGitConflictBg ??= this.#fgColors.error;
-		this.#fgColors.statusLineGitFg ??= this.#fgColors.text;
-		this.#fgColors.statusLineGitCleanFg ??= this.#fgColors.statusLineGitFg;
-		this.#fgColors.statusLineGitDirtyFg ??= this.#fgColors.statusLineGitFg;
-		this.#fgColors.statusLineGitUntrackedFg ??= this.#fgColors.statusLineGitFg;
-		this.#fgColors.statusLineGitConflictFg ??= this.#fgColors.statusLineGitFg;
-		this.#fgColors.statusLinePlanModeBg ??= this.#fgColors.muted;
-		this.#fgColors.statusLinePlanModeFg ??= this.#fgColors.text;
-		this.#fgColors.statusLineContextPctBg ??= this.#fgColors.muted;
-		this.#fgColors.statusLineContextPctFg ??= this.#fgColors.text;
-		this.#fgColors.statusLineContextPctNormalBg ??= this.#fgColors.statusLineContextPctBg;
-		this.#fgColors.statusLineContextPctWarningBg ??= this.#fgColors.statusLineContextPctBg;
-		this.#fgColors.statusLineContextPctPurpleBg ??= this.#fgColors.statusLineContextPctBg;
-		this.#fgColors.statusLineContextPctErrorBg ??= this.#fgColors.statusLineContextPctBg;
-		this.#fgColors.statusLineProfileF5xcBg ??= this.#fgColors.muted;
-		this.#fgColors.statusLineProfileF5xcFg ??= this.#fgColors.text;
-		this.#fgColors.contentAccent ??= this.#fgColors.accent;
 		this.#bgColors = {} as Record<ThemeBg, string>;
 		for (const [key, value] of Object.entries(bgColors) as [ThemeBg, string | number][]) {
 			this.#bgColors[key] = bgAnsi(value, mode);