Add --session option to focus-tab command

[shanselman]

Summary of the Pull Request

Adds a --session / -s option to the wt focus-tab command that accepts a WT_SESSION GUID. This allows external processes to programmatically focus the exact terminal tab and pane where a specific shell session is running.

Primary use case: AI coding agents (GitHub Copilot CLI, Claude Code, Cursor, Aider, etc.) run long-running tasks in terminal sessions. When the task completes, users have often alt-tabbed away and opened many other tabs. This feature lets agents bring users back to the correct tab automatically:

# Agent saves session at startup
$mySession = $env:WT_SESSION

# ... long task runs, user alt-tabs away ...

# Agent brings user back to the right place
wt focus-tab --session $mySession

References and Relevant Issues

• Fixes Feature Request: Focus/Activate Tab by WT_SESSION #19783
• Related: WT_WINDOWID available as env variable #17963 (WT_WINDOWID discussion)
• Related: Expose an API for modifying components of Windows Terminal #16568 (programmatic terminal API)

Detailed Description of the Pull Request / Additional comments

Usage

wt focus-tab --session $env:WT_SESSION
wt ft -s $env:WT_SESSION

What it does

1. Finds the tab containing the pane with the matching WT_SESSION GUID
2. Switches to that tab (routing to the correct window on the current desktop)
3. Focuses the specific pane if the tab has split panes

Implementation

File	Change
AppCommandlineArgs.cpp	Added --session/-s option with GUID parsing. Auto-sets -w 0. Updated ValidateStartupCommands().
AppCommandlineArgs.h	Added _focusTabSession member
ActionArgs.idl	Extended SwitchToTabArgs with Guid SessionId property
ActionArgs.h	Updated SWITCH_TO_TAB_ARGS macro
AppActionHandlers.cpp	Modified _HandleSwitchToTab() to find session and call FocusPaneBySessionId()
Tab.cpp	Added FocusPaneBySessionId() - walks pane tree, calls _rootPane->FocusPane(pane)
Tab.h	Declaration for FocusPaneBySessionId()
Resources.resw	Added help string
TerminalPage.cpp	Constructor call fix

Design decisions

• GUID format flexibility: Accepts both 12345678-1234-... and {12345678-...} formats
• Implicit window routing: Auto-implies -w 0 since session GUID uniquely identifies a pane
• Pane focus: Focuses specific pane within split tabs
• Mutual exclusion: --session excludes --target, --next, --previous

Validation Steps Performed

• Builds successfully (ARM64 Release)
• wt focus-tab --help shows new --session option
• Single tab focus works
• Multi-tab focus works
• Split pane focus works (focuses specific pane)
• IPC handoff from external process works
• Invalid/non-existent GUID handled gracefully

PR Checklist

• Closes Feature Request: Focus/Activate Tab by WT_SESSION #19783
• Tests added/passed
• Documentation updated
• Schema updated (if necessary)

[DHowett]

As much as I'd like to accept this, I worry about its impact on the Windows application ecosystem in the long-term. I understand the need for long-running tasks to bring the user back to focus on them, but I think allowing them to bring Terminal to the foreground and demand focus for themselves sets the wrong precedent. Even though you're launching it from a notification (good) with user consent (good), Contoso may not be so kind as to ask first. focus-tab --session doesn't let us build in consent.

I'd rather tackle this by allowing VT-compliant applications to natively request notifications (ala OSC 777); that puts Terminal back in control of the interaction. It also works better in remote sessions (SSH, WSL) and moves the ecosystem forward.

[DHowett]

This will also be hampered by #13006 - when a process gets yott into Terminal it doesn't have access to WT_SESSION.

[gaoqiangks]

This is a feature I really want. However, I tried this PR, and it seems to have a bug. In the Windows Terminal compiled from this PR, whenever I click Settings, the program freezes briefly and then exits. Does the version you compiled behave the same way? If not, could you share the compiled binary version with me?