Merge remote-tracking branch 'origin/main' into dev/yuazha/codex-session

# Conflicts:
#	tools/wta/src/agent_hooks_installer.rs
#	tools/wta/src/agent_sessions.rs
#	tools/wta/src/app.rs

Author: DDKinger

.github/actions/spelling/allow/allow.txt

@@ -152,6 +152,7 @@ parallelizable
 passthrough
 peekable
 perlw
+pkgver
 postmodern
 Powerline
 Prereq

.github/actions/spelling/expect/expect.txt

@@ -962,6 +962,7 @@ maxval
 maxversiontested
 MAXWORD
 maybenull
+mbr
 MBUTTON
 MBUTTONDBLCLK
 MBUTTONDOWN

CLAUDE.md

@@ -55,7 +55,7 @@ WindowEmperor (one WT process, N AppHosts/windows)
   +-- AppHost[] → TerminalWindow → TerminalPage
         |-- CommandPalette (? / & prefixes)
         |-- Per-tab agent pane: ConptyConnection ───► wta-helper (conpty child)
-        |                                            (one helper per agent pane)
+        |                                            (one helper per tab, pre-warmed)
         +-- Protocol bridge (TerminalPage.Protocol.cpp)
 
 External: Agent → wtcli → COM (IProtocolServer) → TerminalProtocolComServer → WindowEmperor
@@ -71,6 +71,19 @@ helper events (`agent_state_changed`, `agent_status`, `autofix_state`,
 `_FindTabByStableId` instead of fanning out across every pane / window.
 See `doc/specs/Multi-window-agent-pane.md` §7.
 
+**Helper is pre-warmed per tab.** Every new tab spawns a stashed agent
+pane on creation (`_InitializeTab` → `_AutoCreateHiddenAgentPaneShared`
+with `autoStash=true`, `--start-stashed`), so the helper is running and
+its ACP session connects in the background from the start — even if the
+user never opens the pane. This is what lets autofix work on a tab the
+user hasn't interacted with. The agent CLI itself is spawned once by
+`wta-master` at startup and shared across all helpers (each helper's
+`initialize` is a cached replay; only `session/new` round-trips to the
+CLI). `--start-stashed` only seeds `pane_open=false`; it does not defer
+the handshake. The pre-warm is skipped when wta is unavailable, GPO
+blocks all agents, or the tab arrived with an agent pane via cross-window
+drag-in (`agentLeavesSeen > 0`). See `TabManagement.cpp:366`.
+
 **Agent pane toggle = stash, not destroy.** `Ctrl+Shift+.` /
 `Ctrl+Shift+/` / the bottom-bar button toggle via
 `Tab::StashAgentPane`/`RestoreStashedAgentPane` (built on WT's
@@ -101,49 +114,179 @@ Detects command failures in other panes and auto-suggests fixes via the agent.
 
 **Pipeline**: Shell emits `OSC 133;D;<exit_code>` → `TerminalPage` raises `ProtocolVtSequenceReceived` → COM server forwards to clients → WTA (via `wtcli listen --json`) classifies → `maybe_trigger_autofix()`.
 
-**Requirements**: PowerShell shell integration (OSC 133 marks), agent pane open, `wtcli` on PATH.
+**Requirements**: PowerShell shell integration (OSC 133 marks), a helper
+whose ACP session has reached `Connected`, `wtcli` on PATH. The pane does
+**not** need to be visible — the per-tab pre-warmed helper (see
+Architecture) makes autofix work on a stashed pane. But a failure that
+lands before the helper's session connects (cold start of master/agent
+CLI, in-flight `session/new`, or a `Failed` agent) is **dropped**:
+`trigger_autofix_inner` early-returns when `state != Connected`
+(`app.rs:6820`). The bottom-bar notification banner still shows; only the
+autofix pill / LLM call is skipped, and the failure is not re-triggered
+once the session later connects.
 
 **Key code**: `tools/wta/src/app.rs` (`classify_wt_event`, `maybe_trigger_autofix`), `TerminalPage.cpp:2650-2740` (event handlers), `TerminalProtocolComServer.cpp` (`_ensurePageEventsRegistered`).
 
 **Diag log**: `wta-ensure-host.log` in the WTA log directory — shows event flow, classification, and autofix triggers.
 
-## Logs
-
-WTA writes structured logs to:
+## Hooks plugin auto-upgrade
+
+When IT is installed or upgraded, the bundled `wt-agent-hooks` plugin
+(`tools/wta/wt-agent-hooks/{copilot,claude,gemini-extension}/`) needs to
+re-land into any agent CLI the user already opted into (via Settings UI /
+FRE "Install hooks" or `wta hooks install`). This is handled silently by
+`agent_hooks_installer::upgrade_installed_hooks`, fired once per
+`wta-master` startup on a blocking-pool thread.
+
+**Trigger model — bundle version is the upgrade signal.** A tiny state
+file `<LocalCache>/IntelligentTerminal/hooks-upgrade-state.json` records
+the bundle version this wta process last saw per CLI. At startup we read
+each CLI's bundle `plugin.json` / `gemini-extension.json` (cheap, <5ms)
+and compare; if all match, we return immediately (no spawns, no IO
+beyond the cache compare). Only after the user installs / upgrades IT
+does the bundle version change → cache miss → per-CLI flow runs once,
+then the state file is rewritten and the fast path resumes.
+
+**Opt-in only.** Even on cache miss, CLIs that don't already have
+`wt-agent-hooks` installed are skipped. The auto-upgrade never installs
+into a CLI the user hasn't accepted. Disabled plugins are also skipped
+(`enabled: false` in Copilot's `config.json` / `claude plugin list`).
+
+**Per-CLI strategy.** Copilot and Claude use their `plugin update`
+subcommands; before invoking them we rewrite any stale marketplace
+`source.path` to the current bundle dir (Copilot: existing
+`cleanup_stale_copilot_marketplace`; Claude: new
+`cleanup_stale_claude_marketplace`). Gemini's `extensions update`
+silently returns `NOT_UPDATABLE` when the recorded install source no
+longer exists (typical after an MSIX version-dir bump), so we peek at
+`~/.gemini/extensions/wt-agent-hooks/.gemini-extension-install.json`
+first: if `type==local` AND `source` is still under the current bundle,
+run `extensions update` in place; otherwise fall back to
+uninstall+install while preserving the `isActive` flag.
+
+**Trigger-point caveat.** The agent CLI master spawns concurrently may
+already be past its plugin-load step by the time `plugin update` writes
+the new files — so the freshly upgraded hooks may not take effect until
+the next agent restart. Acceptable because blocking master startup on a
+Node-based `plugin update` (1-30s) would hurt every IT-upgrade boot.
+
+**Diag**: `wta-install-hooks.log` (existing) plus `target=agent_hooks`
++ `target={copilot,gemini}_hooks` trace events in
+`wta-main_master.log` show every per-CLI decision (`upgrade decision`
+log line carries `installed_version`, `bundle_version`, `action`).
+
+## Logs & runtime data layout
+
+WTA runtime data lives under the **package-private** store, split by lifetime
+into two roots (both resolved in `runtime_paths.rs`, both falling back to the
+same bare path when the process has no package identity):
 
 ```
-C:\Users\<user>\AppData\Local\IntelligentTerminal\logs\
+# Packaged (every production wta process — helper is a conpty child of the
+# packaged WindowsTerminal.exe, master is spawned in-package by SharedWta):
+
+  …\Packages\<PackageFamilyName>\LocalState\IntelligentTerminal\   <- STATE root
+      prompts\                      (prompt overrides)             intelligent_terminal_root()
+      agent-pane-sessions.jsonl     (session origin index)
+      master-pipe.txt               (helper↔master rendezvous)
+
+  …\Packages\<PackageFamilyName>\LocalCache\Local\IntelligentTerminal\  <- LOCAL/cache root
+      logs\<pkgver>\                (ALL logs for that build — Rust wta-*.log,
+                                     C++ terminal-agent-pane.log, PS hook-trace.log)
+      hook-bundle-staging\ …        (hook-installer staging)
+      hooks-upgrade-state.json      (per-CLI bundle version cache for the
+                                     hooks auto-upgrade fast-path)
+
+# Unpackaged (dev builds run straight out of the Cargo target dir, tests):
+# BOTH roots collapse to the legacy bare %LOCALAPPDATA%\IntelligentTerminal\.
 ```
 
-The path is built off the `LOCALAPPDATA` env var, which is **not** redirected
-into the package sandbox on Win10/11 (the env-var virtualization that
-hides the regular LOCALAPPDATA was a UWP-era behavior; current Windows
-keeps the env var pointing at the real `\AppData\Local\`). Packaged and
-unpackaged wta processes therefore share the same log directory.
-
-The sandbox path
-`%LOCALAPPDATA%\Packages\IntelligentTerminal_<id>\LocalCache\Local\IntelligentTerminal\logs`
-exists as a transparent virtualization of the same directory (NTFS reparse
-points) — both paths return the same files.
-
-Log level is controlled by `WTA_LOG` env var (default: `info`; set `debug`
-for the noisy traces).
+Rationale for the split: **State** = persistent, must-survive, package-private
+data → `LocalState` (alongside the WT app's own `settings.json` / `state.json`).
+**Local/cache** = transient, regenerable diagnostics → `LocalCache\Local`, the
+cache store that doesn't roam / back up.
+
+Both roots are package-private — removed on uninstall and isolated between the
+dev-sideload family (`IntelligentTerminal_rd9vj3e6a2mbr`) and the store family
+(`Microsoft.IntelligentTerminal_8wekyb3d8bbwe`) — instead of sharing one bare
+`%LOCALAPPDATA%\IntelligentTerminal` directory. The family name comes from
+`GetCurrentPackageFamilyName` (windows-sys); the `Packages\<pfn>\LocalState` and
+`…\LocalCache\Local` paths are what WinRT `ApplicationData.Current.LocalFolder`
+/ `LocalCacheFolder` resolve to, so we construct them directly rather than
+pulling in the WinRT projection.
+
+**All three writers share one per-version dir** `logs\<pkgver>\`, where
+`<pkgver>` is the **package version** (`GetCurrentPackageId`, e.g. `0.8.0.2`) —
+read identically at runtime by Rust (`logging::package_version`) and C++
+(`IntelligentTerminal::PackageVersionDir`), so no build-time version sync is
+needed:
+- Rust wta processes → `logging::log_dir()` (`logs\<pkgver>\wta-*.log`).
+- C++ `AgentPaneLog.h` → `IntelligentTerminal::LogDirVersioned()` →
+  `terminal-agent-pane.log` (renamed from the old `wta-agent-pane.log`).
+- PowerShell hooks (`send-event.ps1`) → `hook-trace.log`, via the
+  `WTA_HOOK_LOG_DIR` env var set to `LogDirVersioned()` (C++ ConptyConnection
+  for shell panes; `spawn.rs` for agent-pane CLIs).
+
+`IntelligentTerminal::LogDir()` stays the **root** (`…\logs`, no version) and is
+used only by the bug-report-zip action so it archives every version at once.
+Unpackaged (dev-from-cargo / tests) has no package identity → all writers fall
+back to the flat bare `…\logs\`.
+
+> Earlier builds wrote everything to the bare `%LOCALAPPDATA%\IntelligentTerminal`
+> regardless of identity (the `LOCALAPPDATA` env var is **not** redirected into
+> the sandbox on Win10/11). There is no migration — old data is left in place
+> and simply ignored.
+
+**Log level** is controlled by the `WTA_LOG` (or `RUST_LOG`) env var. When
+unset, the default comes from the build: **debug builds default to `debug`,
+release builds default to `info`** (`logging::default_filter_directive`). Set
+`WTA_LOG=debug|trace` for the noisy traces, or `WTA_LOG=warn` to quiet a
+release build further.
+
+**Logging is initialized once** in `main()` immediately after arg parsing
+(`logging::init(&process_label(&cli))`), before locale/ETW setup, so even
+early-startup failures land on disk. The non-blocking appender's `WorkerGuard`
+lives in a global and is flushed via `logging::shutdown_flush()` on every exit
+path — including before each `std::process::exit` (which would otherwise skip
+the guard drop and lose buffered records). Every launch mode — including
+short-lived `wtcli`-style commands — now writes a log file (previously only 6
+entry points did).
+
+**Per-version storage + retention** (`logging::housekeeping`): each build's
+logs live in their own subdir, `logs\<pkgver>\` (the package version — see
+above). On every start, `prune_old_version_dirs` keeps **only the current
+version's dir** and deletes all other version dirs wholesale. The current
+version's dir is never a deletion target, so cleanup is **lock-free and
+concurrency-safe** (no process can delete a file another is writing). Within the
+current version's dir, per-PID helper logs older than **3 days** are pruned and
+`wta-cli.log` rotates daily keeping 3 days (`max_log_files`).
 
 ### Log files in the helper+master architecture
 
 ```
-wta-main_master.log    — wta-master process: agent CLI spawn, named pipe accept loop,
-                          per-helper routing, session_to_helper map updates,
-                          agent CLI exit detection
-wta-main_helper.log    — each wta-helper process: pipe connect, ACP initialize,
-                          session/new, prompts sent, agent responses received,
-                          TUI lifecycle
-wta-ensure-host.log    — WT-side background ensure-running diagnostics (kept from
-                          M3-M6 era; remains useful for SharedWta lifecycle)
-wta-acp-debug.log      — low-level ACP JSON-RPC wire trace
-wta-delegate.log       — `?<prompt>` delegation flow (separate from agent pane)
+wta-main_master.log        — wta-master process: agent CLI spawn, named pipe accept
+                              loop, per-helper routing, session_to_helper map updates,
+                              agent CLI exit detection, connection failures
+wta-main_helper-{pid}.log  — each wta-helper process (one file per PID, so concurrent
+                              per-tab helpers don't interleave): pipe connect, ACP
+                              initialize, session/new, prompts, agent responses,
+                              TUI lifecycle, connection failures
+wta-cli.log                — short-lived wtcli-style commands (list-*, capture-pane,
+                              listen, sessions, …); daily-rotated, 3-day retention
+wta-delegate.log           — `?<prompt>` delegation flow (separate from agent pane)
+wta-probe.log              — `probe-models` ACP model-list probe
+wta-install-hooks.log      — `hooks install` agent-hook bridge installation
+wta-ensure-host.log        — WT-side background ensure-running diagnostics (kept from
+                              M3-M6 era; remains useful for SharedWta lifecycle)
+wta-acp-debug.log          — low-level ACP JSON-RPC wire trace
 ```
 
+Two files in the per-version dir are **not** written by the Rust wta binary —
+`hook-trace.log` (PowerShell hooks) and `terminal-agent-pane.log` (C++ side);
+see **All three writers share one per-version dir** above. They live in the
+same `logs\<pkgver>\` and so are cleaned together with the Rust logs when that
+version's dir ages out.
+
 ### Tracking flows by `target` field
 
 All tracing uses structured `target` + key=value fields. Grep patterns for common
@@ -157,6 +300,7 @@ scenarios:
 | Trace one prompt end-to-end | grep `session_id="X"`, look for `step="helper→agent" op="prompt"` (sent) then `step="master→helper" op="session_notification"` (response chunks) |
 | Helper pipe lifecycle | `target=master helper_id=…` shows connect+exit |
 | Agent CLI failures | `target=agent_stderr` |
+| Connection failures (either side) | `"exiting with error"` — `target=master` in `wta-main_master.log`, `target=helper` in `wta-main_helper-{pid}.log`; plus inline `step="acp_initialize"` / `step="pipe_connect"` for the helper handshake |
 | Internal control routing | `target=internal_control` (legacy; mostly empty post-Z) |
 
 ### Example: end-to-end trace of one user prompt

README.md

@@ -39,9 +39,11 @@
 
 Intelligent Terminal is an experimental fork of [Windows Terminal](https://github.com/microsoft/terminal) with native agent integration.
 
-[GitHub Copilot](https://github.com/features/copilot/cli/) is the default agent CLI, but it works with any [Agent Client Protocol (ACP)-compatible](https://agentclientprotocol.com/get-started/agents) agent CLI. All you need is to install your preferred agent CLI on your PC, and Intelligent Terminal should detect it.
+Intelligent Terminal works with any [Agent Client Protocol (ACP)-compatible](https://agentclientprotocol.com/get-started/agents) agent CLI. All you need is to install your preferred agent CLI on your PC. If you don't have a preferred agent, we'll get you setup with [GitHub Copilot CLI](https://github.com/features/copilot/cli/).
 
-Everything else about Intelligent Terminal is the same as Windows Terminal: tabs, profiles, themes, settings, shells, and keyboard shortcuts all work the way you expect.
+Intelligent Terminal takes all the features you love in Windows Terminal such as:  tabs, profiles, themes, settings, shells, and keyboard shortcuts, which all work the way you expect.
+
+Read the [announcement blog post](https://devblogs.microsoft.com/commandline/announcing-intelligent-terminal-version-0-1/) for more details.
 
 ---
 
@@ -79,13 +81,20 @@ winget install --id Microsoft.IntelligentTerminal -e
 
 1. On first launch, choose your agent. Intelligent Terminal auto-detects several [ACP-compatible](https://agentclientprotocol.com/get-started/agents) agent CLIs on your machine (Copilot/Claude/Codex/Gemini). If none are found, it defaults to GitHub Copilot CLI and installs it for you via WinGet.
 3. If you aren't already authenticated, the agent pane walks you through sign-in.
-4. Start asking questions. The agent has context on your shell output, no copy-pasting needed.
+4. Start asking questions and using the agent pane for assistance. The agent has context on your shell output, no copy-pasting needed.
+
+> [!TIP]
+> If you see "running scripts is disabled on this system" or an `UnauthorizedAccess` error in PowerShell, your execution policy is blocking your profile and Intelligent Terminal can't initialize shell integration. Run:
+> ```powershell
+> Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+> ```
+> If you run into any other issues or dependency errors, see [installing-dependencies.md](./doc/installing-dependencies.md).
 
 ---
 
 ## Keyboard Shortcuts
 
-All shortcuts are customizable through terminal settings.
+All shortcuts are customizable through Intelligent Terminal settings.
 
 | Shortcut | Action |
 |----------|--------|
@@ -99,7 +108,7 @@ All shortcuts are customizable through terminal settings.
 
 ## Configuration
 
-Everything is configurable through terminal settings, under "Agent" settings.
+Everything is configurable through Intelligent Terminal settings, under "Agent" settings.
 
 | Setting | Options |
 |---------|---------|
@@ -119,7 +128,7 @@ Everything is configurable through terminal settings, under "Agent" settings.
   <img src="./images/intelligent-terminal-status-bar.png" alt="Screenshot of the agent status bar at the bottom of the terminal window">
 </p>
 
-The agent status bar sits at the bottom of the window and gives you quick access to everything agent-related. On the left: the agent pane toggle and the error detection icon, which lights up when a fixable error is detected. On the right: the agent management icon that opens your session management panel. It's a persistent, minimal control surface so you're never more than one click away from your agents.
+The agent status bar sits at the bottom of the window and gives you quick access to everything agent-related. On the left: the agent pane toggle (hotkey: <kbd>Ctrl+Shift+.</kbd>) and the error detection icon (hotkey: <kbd>Ctrl+Alt+.</kbd>), which lights up when a fixable error is detected. On the right: the agent management icon (hotkey: <kbd>Ctrl+Shift+/</kbd>) that opens your session management panel. It's a persistent, minimal control surface so you're never more than one click away from your agents.
 
 ### Agent Pane
 
@@ -129,6 +138,12 @@ The agent status bar sits at the bottom of the window and gives you quick access
 
 A context-aware, docked pane with your agent CLI of choice. The pane has context on your shell output across all your shells. Toggle with <kbd>Ctrl+Shift+.</kbd>, switch focus with <kbd>Ctrl+Shift+I</kbd>. If the agent needs to do multiple or complex tasks, it spins up background tasks in new tabs so your active shell stays focused.
 
+<p align="center">
+  <img src="./images/intelligent-terminal-agent-focus.png" alt="Screenshot of the agent pane with focus, showing multiple panes">
+</p>
+
+When you have multiple panes active, a small "Agent" indicator will appear on the pane that your agent has "focus" on.
+
 ### Agent Management
 
 <p align="center">