docs(v2): make runtime handoff procedure explicit

Document the A/B staging and deployment slot roles so smoke builds are launched from the validated deployed artifact.

Describe the complete external interactive-task handoff flow, including precise V2 process selection, request construction, environment setup, result verification, hash validation, and one-shot task cleanup. This gives future agents a positive executable procedure and prevents the handoff launcher from sharing the process tree it replaces.

AGENTS.md

@@ -49,6 +49,13 @@ Behavior for agents:
 - Use the `edit` tool for modifying existing files; prefer it over other editing methods.
 - Use the `write` tool only when creating new files from scratch.
 
+## V2 Runtime Handoff
+- Treat `codenomad-v2-slots/build-{A|B}/release` as build staging and `codenomad-v2-slots/{A|B}` as the runnable deployment slots. Launch the deployed slot recorded by its `deployment.json`.
+- For a first V2 launch, start the deployed executable from PowerShell with the dedicated WebView2 profile, CDP port, Rust backtraces, and Node source maps described in `MIGRATION_V2.md`.
+- To replace a running V2 instance, submit `codenomad-v2-handoff-request.json` to `codenomad-v2-handoff.ps1` through an interactive Windows scheduled task. The task must be owned by the logged-in user so it runs outside the CodeNomad process tree while retaining desktop access.
+- Set `waitForPid` to the top-level CodeNomad window process, `executable` to the deployed target slot, and `fallbackExecutable` to the previously validated slot.
+- Consider the handoff complete after `codenomad-v2-handoff-result.json` reports `status: "started"`. Then verify that the reported PID is running from the requested slot and that the executable hash matches that slot's `deployment.json` before reporting success.
+
 ## Commit Message Guidelines
 - When creating commits, use detailed commit messages: a concise conventional-style subject followed by body paragraphs that explain the user-visible behavior change, the implementation approach, important edge cases or platform considerations, and the validation or test coverage added.
 - Prefer messages that explain why the change exists and how regressions are prevented, not just a list of touched files.

MIGRATION_V2.md

@@ -84,17 +84,63 @@ The final validation should include:
 
 ### Required Parallel UI Smoke
 
-CodeNomad V1 is the working environment and must remain open and untouched. V2 always uses `~/.local/share/opencode2/opencode.db`; launch the V2 build beside V1 from PowerShell with a dedicated CDP port and WebView profile:
+CodeNomad V1 is the working environment and must remain open and untouched. V2 always uses `~/.local/share/opencode2/opencode.db`. Build into `codenomad-v2-slots/build-{A|B}/release`, copy the validated output into the corresponding `codenomad-v2-slots/{A|B}` deployment slot, and record its source, hash, slot, and deployment time in `deployment.json`.
+
+For a first V2 launch, start the deployed slot beside V1 from PowerShell with a dedicated CDP port, WebView profile, Rust backtraces, and Node source maps:
 
 ```powershell
-Start-Process `
-  -FilePath 'D:\CodeNomad-worktrees\opencode-v2-foundation\packages\tauri-app\target\release\codenomad-tauri.exe' `
-  -Environment @{
+$slot = "$env:TEMP\opencode\codenomad-v2-slots\A"
+$environment = @{
     WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = '--remote-debugging-port=9223'
-    WEBVIEW2_USER_DATA_FOLDER = "$env:TEMP\codenomad-webview-v2"
-  }
+    WEBVIEW2_USER_DATA_FOLDER = "$env:TEMP\opencode\codenomad-v2-debug"
+    RUST_BACKTRACE = '1'
+    NODE_OPTIONS = '--enable-source-maps'
+}
+Start-Process -FilePath "$slot\codenomad-tauri.exe" -WorkingDirectory $slot -Environment $environment
 ```
 
+To replace an active V2 instance, write the target slot, validated fallback slot, top-level CodeNomad window PID, and a unique request ID to `$env:TEMP\opencode\codenomad-v2-handoff-request.json`. Run `$env:TEMP\opencode\codenomad-v2-handoff.ps1` through an interactive Windows scheduled task owned by the logged-in user. This gives the handoff an external lifetime and desktop access while it closes the active process, applies the environment above, and starts the target slot:
+
+```powershell
+$root = "$env:TEMP\opencode"
+$targetSlot = Join-Path $root 'codenomad-v2-slots\A'
+$fallbackSlot = Join-Path $root 'codenomad-v2-slots\B'
+$requestPath = Join-Path $root 'codenomad-v2-handoff-request.json'
+$handoffPath = Join-Path $root 'codenomad-v2-handoff.ps1'
+$taskName = 'CodeNomad-V2-Handoff'
+$windowProcess = Get-CimInstance Win32_Process |
+  Where-Object {
+    $_.Name -eq 'codenomad-tauri.exe' -and
+    $_.ExecutablePath -like "$root\codenomad-v2-slots\?\codenomad-tauri.exe" -and
+    $_.CommandLine -notmatch 'internal-cli-launcher'
+  } |
+  Select-Object -First 1
+
+@{
+  mode = 'launch'
+  requestId = [guid]::NewGuid().ToString('N')
+  executable = Join-Path $targetSlot 'codenomad-tauri.exe'
+  fallbackExecutable = Join-Path $fallbackSlot 'codenomad-tauri.exe'
+  waitForPid = $windowProcess.ProcessId
+  closeOldProcess = $true
+  clientStateSeedPath = $null
+  clientStateSeedSha256 = $null
+} | ConvertTo-Json | Set-Content -LiteralPath $requestPath -Encoding utf8
+
+$action = New-ScheduledTaskAction -Execute (Get-Command pwsh).Source -Argument (
+  "-NoProfile -ExecutionPolicy Bypass -File `"$handoffPath`" -RequestPath `"$requestPath`""
+)
+$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(5)
+$principal = New-ScheduledTaskPrincipal `
+  -UserId ([System.Security.Principal.WindowsIdentity]::GetCurrent().Name) `
+  -LogonType Interactive `
+  -RunLevel Limited
+Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Force | Out-Null
+Start-ScheduledTask -TaskName $taskName
+```
+
+Read `$env:TEMP\opencode\codenomad-v2-handoff-result.json` after reconnection. A successful handoff has `status: "started"`; verify its PID runs from the requested slot and compare the executable hash with that slot's `deployment.json` before recording the smoke build as active. Remove the completed one-shot task with `Unregister-ScheduledTask -TaskName 'CodeNomad-V2-Handoff' -Confirm:$false`.
+
 The smoke is complete only after all of these actions succeed in the visible V2 UI:
 
 1. Confirm the selected `opencode2` binary reports the latest version reviewed for this branch.