Merge origin/main into FRE settings branch

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 983cc47d-6f23-4c84-9a54-1a60ecaaf607

Author: Haonan Tang (from Dev Box)

.github/skills/pr-integration-test/SKILL.md

@@ -20,6 +20,19 @@ checklist.
 
 - Read `test/e2e/README.md` and reuse the ItE2E framework instead of creating a
   parallel harness.
+- Treat the source revision and deployed package as separate decisions. For a
+  PR, test the intended PR head/feature-branch revision through a Dev build by
+  default; a previously installed Dev package is not proof that the PR code ran.
+- Before running any live integration test, identify the target package from
+  the user's request. If the user did not explicitly choose **Dev** or
+  **Store/production**, use `ask_user` and wait for the answer. In a PR context,
+  make **Dev built from the PR head/feature branch** the recommended/default
+  choice. Never select a package solely from installed-package discovery.
+- Use Store only when the user explicitly asks to test the production/shipped
+  build. Store results establish a production baseline; they do not validate
+  unshipped changes in the PR.
+- Pin the chosen package through `$env:ITE2E_PACKAGE = 'Dev'` or
+  `$env:ITE2E_PACKAGE = 'Store'` for every live validation command.
 - Run `pwsh -File test/e2e/bootstrap.ps1 -Check` before live E2E validation.
 
 ## Workflow
@@ -73,12 +86,20 @@ Do not call the work complete until all of these are true:
 
 - Pre-fix evidence identifies the regression, and the fixed path crosses the
   real integration boundary.
+- For PR validation against Dev, the tested package is proven to contain the
+  intended PR head/feature-branch revision.
 - Relevant false positives, replay risks, and existing behavior are covered.
 - The correct build passes related suites and marks new checklist IDs `[x]`;
   every skip is explained.
 
 ## Gotchas
 
+- **Never run a live integration test with an implicit or `Auto` package
+  selector.** Ask first, then pin `ITE2E_PACKAGE`. Installed-package discovery
+  cannot establish user intent or prove that a Dev package contains PR code.
+- **Do not use Store to validate a PR's unshipped code.** Prefer a Dev package
+  built and deployed from the PR head/feature branch. Use Store only for an
+  explicitly requested production baseline and label the result accordingly.
 - **Do not test only the implementation detail named in the PR.** Reconstruct
   the end-to-end user path and assert the observable contract.
 - **Do not duplicate a unit test at E2E level.** Add the missing process,

.github/skills/pr-integration-test/references/workflow.md

@@ -34,6 +34,11 @@ Choose the branch deliberately:
 Verify merge state and a clean worktree before deleting a branch. Squash-merged
 branches may require `git branch -D` because Git cannot infer ancestry.
 
+Record the exact revision whose behavior should be validated. For an open PR,
+prefer the PR head/feature branch, or a validation branch created from that
+head. Do not test an unrelated installed Dev package and describe the result as
+PR validation.
+
 ## 2. Reconstruct the Behavioral Contract
 
 Describe the full path as components and observable handoffs:
@@ -165,16 +170,30 @@ Update the suite table in `test/e2e/README.md` when adding a new feature file.
 
 ## 7. Validate Tests and Report Mapping
 
+Before any live command, resolve the package target:
+
+- If the user explicitly requested Dev or Store/production, use that choice.
+- Otherwise call `ask_user` with exactly those choices and wait.
+- In a PR context, label Dev as **built from the PR head/feature branch**, make
+  it the recommended/default choice, and explain that Store is the currently
+  installed production baseline. Outside a PR context, do not infer a choice.
+- Use Store only when the user explicitly selects production. A Store run
+  compares against shipped behavior; it cannot validate unshipped PR code.
+- Set `$env:ITE2E_PACKAGE = 'Dev'` or `'Store'` in the same PowerShell process
+  that invokes the test runner.
+
 Verify prerequisites:
 
 ```powershell
+$env:ITE2E_PACKAGE = 'Dev' # or 'Store', as explicitly selected
 pwsh -NoProfile -File test/e2e/bootstrap.ps1 -Check
 ```
 
 Run the new suite through the report driver:
 
 ```powershell
 $suite = 'test/e2e/tests/Feature.AutofixParser.Tests.ps1'
+$env:ITE2E_PACKAGE = 'Dev' # or 'Store', as explicitly selected
 pwsh -NoProfile -File test/e2e/Invoke-ItE2EReport.ps1 `
   -Path $suite `
   -UpdateReport
@@ -216,11 +235,17 @@ regressions or the PR changes common harness/product infrastructure.
 
 ## 8. Prove the Correct Build Ran
 
-Build and deploy the changed area. For WTA changes, build the explicit target
-matching the package architecture before the C++ package, deploy it, select it
-with `ITE2E_PACKAGE` or `-Package Dev`, and verify a runtime version, path, log,
-or changed observable. Compilation alone does not prove the deployed package
-contains the new `wta.exe` or generated shell integration.
+For PR validation, check out the intended PR head/feature-branch revision,
+record its commit, then build and deploy the changed area into the Dev package.
+Verify a runtime version, path, log, or changed observable that ties the
+deployed package to that revision. A previously installed Dev package or a
+successful compilation does not prove the PR code ran.
+
+For WTA changes, build the explicit target matching the package architecture
+before the C++ package, deploy it, select it with `ITE2E_PACKAGE=Dev`, and prove
+the deployed package contains the refreshed `wta.exe` and generated shell
+integration. Do not substitute a Store run unless the user explicitly asked for
+a production baseline.
 
 ## 9. Deliver the Test PR
 

build/scripts/Verify-AgentHooks.ps1

@@ -5,10 +5,9 @@
     supported agent CLIs (Copilot, Claude, Gemini, Codex).
 
 .DESCRIPTION
-    Wrapper around `wta hooks status --json` / `wta install-hooks` /
-    `wta hooks uninstall --json`. Same JSON contract that the Settings
-    UI's "AI agents → Agent Hooks" section consumes — so the script and
-    the UI can never disagree about install state.
+    Wrapper around `wta hooks status --json` / `wta hooks install` /
+    `wta hooks uninstall --json`. Uses the JSON contracts defined in
+    tools/wta/src/agent_hooks_installer.rs for status and diagnostics.
 
     Internals are factored into named functions
     (Resolve-WtaPath, Get-AgentHooksStatus, Format-AgentHooksTable,
@@ -20,7 +19,7 @@
 .PARAMETER Mode
     Check    — print a colored status table and exit non-zero if any CLI
                  is in an inconsistent state.
-    Install  — run `wta install-hooks`, then run Check.
+    Install  — run `wta hooks install`, then run Check.
     Uninstall— run `wta hooks uninstall --cli=<filter> --json`, then Check.
 
 .PARAMETER CliFilter
@@ -73,8 +72,7 @@ $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
 
 # Schema version this script understands. Mirrors STATUS_SCHEMA_VERSION
-# in tools/wta/src/agent_hooks_installer.rs and SupportedStatusSchemaVersion
-# in src/cascadia/inc/AgentHooksStatus.h. Bump in lockstep.
+# in tools/wta/src/agent_hooks_installer.rs. Bump in lockstep.
 $script:SupportedStatusSchemaVersion = 4
 
 $script:CliDisplayNames = @{
@@ -350,10 +348,10 @@ function Invoke-HooksInstall {
     param([Parameter(Mandatory)][string]$WtaPath)
 
     Write-Host ''
-    Write-Host '→ Running: wta install-hooks' -ForegroundColor Cyan
-    & $WtaPath install-hooks
+    Write-Host '→ Running: wta hooks install' -ForegroundColor Cyan
+    & $WtaPath hooks install
     if ($LASTEXITCODE -ne 0) {
-        throw "wta install-hooks exited with code $LASTEXITCODE"
+        throw "wta hooks install exited with code $LASTEXITCODE"
     }
 }
 

doc/faq.md

@@ -19,18 +19,18 @@ The package manifest sets `MinVersion="10.0.19041.0"` (Windows 10, version 2004)
 
 ## 3. I installed a new agent CLI after the FRE — why isn't it tracked in agent session management?
 
-You completed the FRE with one agent (say, Copilot), then later installed Claude or Codex (or another bring-your-own ACP-compatible CLI) and switched the **agent pane** to it in Settings. The agent pane may not work, or **agent session management** doesn't track its sessions.
+You completed the FRE with one agent (say, Copilot), then later installed Claude or Codex and switched the **agent pane** to it in Settings.
 
-The FRE only sets up the session-tracking hooks for the agents you went through it with. Agents installed *after* the FRE need a one-time manual setup. (The ACP wrapper itself is auto-fetched on demand via `npx`, so there is no wrapper "install" to run — see [Step 3.2.3](./installing-dependencies.md#step-323--acp-wrapper-no-install-action-required) / [Step 3.3.3](./installing-dependencies.md#step-333--acp-wrapper-no-install-action-required) — but you do need to make sure the prerequisites the wrapper depends on are in place.)
+The FRE installs session-tracking hooks only for the agent selected there. With **Session management** enabled, Intelligent Terminal automatically installs or updates hooks for newly detected built-in agents when `wta-master` starts and when you select a different built-in agent.
 
-**Workaround:**
+If the new agent is not tracked:
 
 1. **Make sure the prerequisites are in place.** Follow the steps in [`installing-dependencies.md`](./installing-dependencies.md) that match your agent — install Node.js LTS and the agent's own CLI (via `npm install -g <package>`):
    - Claude: [Steps 3.2.1 – 3.2.3](./installing-dependencies.md#32-claude-code-bring-your-own) — Intelligent Terminal launches Claude through an ACP wrapper that is fetched automatically via `npx` on first launch.
    - Codex: [Steps 3.3.1 – 3.3.3](./installing-dependencies.md#33-openai-codex-bring-your-own) — same wrapper-via-`npx` pattern as Claude.
    - Gemini: [Section 3.4](./installing-dependencies.md#34-gemini-cli-bring-your-own) — Gemini speaks ACP natively, so no wrapper is needed; just install the CLI itself.
 
-2. **Re-install the session-tracking hooks.** Open Intelligent Terminal **Settings → Agent**, scroll to the **Agent session tracking (hooks)** row ("Track sessions across agents. Required for agent session management."), expand it, and click the **Install hooks** button next to *Install agent hook script*. This wires the newly installed CLI into agent session management so its sessions show up in the panel.
+2. Open a fresh Intelligent Terminal window so the new CLI is on `PATH`, confirm **Settings → Agent → Sessions** is on, and select the new built-in agent. Automatic reconciliation runs in the background. For manual repair, run `wta hooks install --cli <agent>`.
 
 ## 4. Can I use a custom ACP-compatible agent (Qwen, Cline, Goose, Cursor, …)?
 

doc/installing-dependencies.md

@@ -337,15 +337,18 @@ up the new credentials.
 parallel conversations on the same tab — is powered by a small bundle of
 **agent hooks** (`wt-agent-hooks`) that the agent CLI loads as a plugin /
 extension. The first-run experience installs these hooks for you the
-first time you save the FRE with **Session management** enabled.
+first time you save the FRE with **Session management** enabled. FRE installs
+only the selected agent's hooks. After FRE, Intelligent Terminal automatically
+reconciles hooks at `wta-master` startup, when Session management changes from
+off to on, and when you select a different built-in agent.
 
 You only need to follow this section if:
 
 - The FRE reported that hooks installation failed (for example because
   the agent CLI was not yet on `PATH`, or your network blocked the agent
   CLI's plugin store).
-- You installed the agent CLI **after** completing the FRE and now want
-  to enable session management.
+- Automatic reconciliation failed and you need to repair the installation
+  manually.
 
 #### Step 3.6.1 — Make sure the agent CLI is installed and on PATH
 
@@ -362,13 +365,17 @@ sub-section above before continuing:
 Verify the CLI you intend to use prints a version number, then close and
 reopen your terminal so any new install directory is on `PATH`.
 
-#### Step 3.6.2 — Run `wta hooks install`
+#### Step 3.6.2 — Let Intelligent Terminal reconcile hooks
 
-Intelligent Terminal ships a `wta hooks install` command that runs the
-same installer the FRE uses. Open a **new** Intelligent Terminal window
-(so `wta` and the agent CLI both pick up the current `PATH`) and run
-**one** of the following — whichever matches the agent you selected in
-the FRE:
+Open a **new** Intelligent Terminal window so `wta-master` and the agent CLI
+pick up the current `PATH`. In **Settings → AI Agents**, turn **Sessions** on
+and select the installed built-in agent. Intelligent Terminal
+checks the agent asynchronously and installs missing hooks or upgrades stale
+ones.
+
+If automatic reconciliation fails, `wta hooks install` remains the supported
+manual retry command. It applies the same smart reconciliation used by
+automatic triggers:
 
 ```powershell
 wta hooks install --cli copilot
@@ -384,8 +391,8 @@ Or install for every agent CLI that is currently on `PATH` in one go:
 wta hooks install
 ```
 
-Under the hood this runs each agent CLI's native plugin / extension
-command against the `wt-agent-hooks` bundle shipped inside the
+When reconciliation selects Install, it runs the agent CLI's native plugin /
+extension command against the `wt-agent-hooks` bundle shipped inside the
 Intelligent Terminal package:
 
 | Agent          | Native commands invoked by `wta hooks install`                                                                              |
@@ -406,6 +413,17 @@ You do not need to run these directly — `wta hooks install` is the
 supported entry point and handles bundle staging, idempotency, and
 diagnostic logging for you.
 
+If status looks healthy but the hooks still do not run, use the explicit
+force-recovery path:
+
+```powershell
+wta hooks install --force --cli codex
+```
+
+`--force` reruns the first-install flow even when the hook bridge already
+appears installed. Close running sessions for that agent first so its plugin
+manager cannot overwrite the registration while it is being repaired.
+
 > [!IMPORTANT]
 > **Codex needs a one-time `/hooks` trust step.** After
 > `wta hooks install --cli codex` succeeds, hook events will not fire
@@ -414,7 +432,7 @@ diagnostic logging for you.
 > requirement that no external installer can satisfy on your behalf;
 > the other four CLIs do not need this step.
 
-#### Step 3.6.3 — Verify the install and re-enable session management
+#### Step 3.6.3 — Verify the install
 
 Check the status report to confirm each agent CLI is wired up:
 
@@ -427,10 +445,7 @@ installed hook version (for example `v0.1.5`). When a CLI's hooks were
 registered by a different build, the row also names the version this
 Intelligent Terminal ships — `v0.1.4 (bundle v0.1.5)` means the CLI is
 loading older hooks and should be reinstalled with `wta hooks install`.
-Then, back in
-**Settings → AI Agents**, turn **Session management** back on (the FRE
-turns it off when hooks installation fails so you can save and continue
-without it) and restart Intelligent Terminal once.
+If Session management is off, turn it on to retry automatic reconciliation.
 
 > [!TIP]
 > If `wta hooks install` still fails, diagnostics are written to
@@ -451,9 +466,9 @@ without it) and restart Intelligent Terminal once.
 > [!WARNING]
 > If your organization disables agent session hooks through Group
 > Policy, the **Session management** toggle in the FRE and in
-> **Settings → AI Agents** is locked off and the FRE will not run the
-> hooks installer for you. Contact your IT administrator if you
-> believe this is in error.
+> **Settings → AI Agents** is locked off and neither FRE nor automatic
+> reconciliation will run the hooks installer. Contact your IT administrator
+> if you believe this is in error.
 
 ---