Merge main and address hook-routing review findings

Preserve upstream lifecycle, cancellation and settings changes while retaining master-owned hook routing. Resolve the event-dispatch conflict using consistent LF endings. Reconcile shell prompts in the ordered master COM stream so a helper exit cannot overtake a queued birth. Preserve exponential retry delays across unstable subscriptions and measure stability only after readiness. Count all E2E processing records and require currently subscribed helper listeners. Allocate fresh hook checklist IDs C296-C298 without changing upstream IDs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: c6ef3e46-71af-4e5a-82af-a172700ca3ce

Author: DDKinger

.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
 

.github/workflows/winget.yml

@@ -15,6 +15,21 @@ jobs:
     runs-on: windows-latest # Action can only run on Windows
     if: ${{ !github.event.release.prerelease }} # Only publish stable releases to WinGet
     steps:
+      - name: Sync winget-pkgs fork with upstream
+        continue-on-error: true # wingetcreate also attempts a sync; don't fail the run on a transient API error
+        env:
+          GH_TOKEN: ${{ secrets.WINGET_TOKEN }}
+        run: |
+          # wingetcreate can only fast-forward a fork that is not too far behind upstream.
+          # A fork left untouched between releases falls thousands of commits behind and the
+          # submit step then fails with "The forked repository could not be synced with the
+          # upstream commits." Sync it up front so wingetcreate always sees a current fork.
+          $owner = (gh api user --jq '.login')
+          Write-Host "Syncing $owner/winget-pkgs with microsoft/winget-pkgs..."
+          $branch = (gh api "repos/$owner/winget-pkgs" --jq '.default_branch')
+          Write-Host "Default branch is $branch"
+          gh api -X POST "repos/$owner/winget-pkgs/merge-upstream" -f branch=$branch
+
       - name: Publish Intelligent Terminal
         run: |
           $assets = '${{ toJSON(github.event.release.assets) }}' | ConvertFrom-Json

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.
 
 ---