Merge remote-tracking branch 'origin/codex/goal-session' into codex/commands

# Conflicts:
#	packages/examples/stdio-demo/README.md
#	packages/ui/tui/README.md

packages/ui/tui/README.md

@@ -47,15 +47,31 @@ The palette uses the standard 16-color ANSI foregrounds and SGR attributes, whic
 
 ### Interactive prompt input
 
-**What the model sees**: Each non-empty ordinary editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. Slash commands and keybindings are TUI-only; command results remain terminal notices.
+#### What the model sees
 
-**Token effect**: Submitted text is retained under the agent loop's normal session-history and compaction rules. Headers, cards, Markdown rendering, status lines, plans, and help text add no tokens.
+Each non-empty ordinary editor submission becomes one text block, sent with `agent.send()` while the target agent is idle and `agent.steer()` while it is running. Slash commands and keybindings are TUI-only; command results remain terminal notices.
+
+#### Token effect
+
+Submitted text is retained under the agent loop's normal session-history and compaction rules. Headers, cards, Markdown rendering, status lines, plans, and help text add no tokens.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ### Interactive user-question answers
 
-**What the model sees**: When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels or `custom` text. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`.
+#### What the model sees
 
-**Token effect**: Waiting and terminal overlays add no tokens; the resolved answer or error is model-visible only through the calling tool or plugin's result.
+When a consumer calls `ctx.userInteraction.ask()`, this provider presents each question in order and returns selected option labels or `custom` text. Abort, cancellation, or UI disposal becomes `Error: ask_user_question was interrupted before the user answered` through `dsh-tool-ask-user`.
+
+#### Token effect
+
+Waiting and terminal overlays add no tokens; the resolved answer or error is model-visible only through the calling tool or plugin's result.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
 ## Known Limitations and Deferred Work
 

packages/ui/tui/tests/headless-terminal.ts

@@ -286,7 +286,7 @@ export class HeadlessTerminal implements Terminal {
     return violations
   }
 
-  /** Serialize terminal cells and metadata into a stable, reviewable golden. */
+  /** Serialize terminal cells and metadata into a stable, reviewable expected output. */
   async snapshot(options: TerminalSnapshotOptions = {}): Promise<string> {
     await this.flush()
     const buffer = this.emulator.buffer.active

packages/ui/tui/tests/tui.snapshot.ts

@@ -52,7 +52,7 @@ async function checkpoint(
   observedCheckpoints.add(name)
   expect(terminal.themeViolations(), `${name} must remain theme-agnostic`).toEqual([])
   const snapshot = await terminal.snapshot(options)
-  const path = join(SNAPSHOTS_DIR, `${name}.golden.txt`)
+  const path = join(SNAPSHOTS_DIR, `${name}.expected.txt`)
   if (REFRESHING) {
     await mkdir(SNAPSHOTS_DIR, { recursive: true })
     await writeFile(path, snapshot)
@@ -493,7 +493,7 @@ describe('TUI terminal-state snapshots', () => {
 afterAll(async () => {
   expect([...observedCheckpoints].sort()).toEqual([...CHECKPOINTS].sort())
   const files = (await readdir(SNAPSHOTS_DIR))
-    .filter(file => file.endsWith('.golden.txt'))
+    .filter(file => file.endsWith('.expected.txt'))
     .sort()
-  expect(files).toEqual(CHECKPOINTS.map(name => `${name}.golden.txt`).sort())
+  expect(files).toEqual(CHECKPOINTS.map(name => `${name}.expected.txt`).sort())
 })