Skip to content

Vector Session Launcher ("Start on Vector")

URL: https://mkdocs.justinsforge.com/memory/general/reference_vector_session_launcher/

Spawns a Claude Code Remote Control session ON Vector (Windows PC) from the chat.justinsforge.com New Session sheet. Built and e2e-verified 2026-07-01 (16s checkbox-to-URL). Plan: vector-session-launcher-2026-07-01.

Architecture: pull, not push

Console NEVER holds SSH keys into Vector (trust model in reference_vector_claude_code.md). Instead the Vector daemon polls Console's job queue every 15s over Vector's own standing SSH client access:

Piece Where
Job queue + contract forge/data/vector-launcher/{queue,claimed,results}/ + heartbeat.json; schemas in the dir README
API scripts/forge_session_launcher_api.py, POST /api/sessions with target:"vector"; heartbeat >60s stale = instant "Vector not reachable"
UI "Start on Vector" checkbox, sites/justinsforge.com/chat/launcher.js (assets v19)
Vector daemon C:\Users\Justi\forge-vector-local\session-launcher\forge_vector_session_launcher.ps1, canonical source scripts/vector/session-launcher/
Scheduled task ForgeVectorSessionLauncher (ONLOGON, hidden poll loop; launched sessions open visible windows)
Vector logs C:\Users\Justi\forge-vector-local\logs\launcher-daemon.log + rc-<job>.log per session

Flow: checkbox -> API writes queue/<id>.json -> daemon claims (atomic mv to claimed/) -> opens a visible powershell window running claude --model <id> --dangerously-skip-permissions --remote-control <name> --debug-file <log> [prompt] in C:\Users\Justi\forge-vector-local\ -> parses the bridge id from the debug log -> writes results/<id>.json -> API surfaces the claude.ai/code URL in the UI. Sessions are named vector-<name>.

Deploy / upgrade / kill

Edit canonical source on Console, then on Vector in an ADMIN PowerShell:

mkdir $env:TEMP\vector-launcher -Force
scp console:/home/justinwieb/forge/scripts/vector/session-launcher/forge_vector_session_launcher.ps1 console:/home/justinwieb/forge/scripts/vector/session-launcher/watchdog.ps1 console:/home/justinwieb/forge/scripts/vector/session-launcher/run-hidden.vbs console:/home/justinwieb/forge/scripts/vector/session-launcher/Fix-Launcher.bat console:/home/justinwieb/forge/scripts/vector/session-launcher/install.ps1 $env:TEMP\vector-launcher\
powershell -ExecutionPolicy Bypass -File $env:TEMP\vector-launcher\install.ps1

Installer is idempotent (/End old instance, /Create /F, /Run) and now registers BOTH tasks plus drops the desktop button. Must run in an ELEVATED PowerShell (ONLOGON /Create throws "Access is denied" otherwise). Kill switch: install.ps1 -Uninstall (removes both tasks + desktop button), or schtasks /End /TN ForgeVectorSessionLauncher. Verify from Console: cat forge/data/vector-launcher/heartbeat.json (fresh ts, daemon_pid changes on reinstall).

Self-heal: watchdog + desktop button (added 2026-07-09)

The launcher is ONLOGON-only, so a logoff / crash / wedged poll leaves it dead with no auto-restart, surfacing as "Vector not reachable." Fixed with a watchdog:

Piece Where
Watchdog task ForgeVectorLauncherWatchdog, /SC MINUTE /MO 5 (checks every 5 min)
Watchdog script scripts/vector/session-launcher/watchdog.ps1 (canonical)
Liveness signal daemon writes logs/daemon-heartbeat.local on Vector each poll, BEFORE the Console SSH call; watchdog restarts the launcher if that file's mtime is >120s stale. Local-only on purpose: a Console outage must not trigger a needless restart.
Manual override Fix-Launcher.bat on the Desktop, double-click for an instant restart instead of waiting up to ~5 min
Watchdog log logs/watchdog.log on Vector

Self-heal verified e2e 2026-07-09: schtasks /End the launcher, wait past 120s, watchdog restarts it (daemon_pid changes on Console heartbeat).

Installer gotcha (fixed): schtasks /End on a not-yet-existing task writes to stderr, and under $EAP=Stop a native command's stderr throws NativeCommandError, which halted the FIRST install right before the watchdog /Create. Fixed by routing every /End and /Delete through cmd /c "... >nul 2>&1" (helper Stop-TaskQuiet) so stderr never reaches PowerShell. Same family as the PS 5.1 2>$null-under-EAP-Stop gotcha below.

Gotchas (all hit during the 2026-07-01 build)

  • Scheduled tasks with a powershell.exe action flash a visible console window on every run, even with -WindowStyle Hidden (conhost spawns before PowerShell parses the flag). With the watchdog on a 5-min repeat this popped a cmd window every 5 minutes (reported 2026-07-11). Fix: both task actions route through run-hidden.vbs via wscript.exe (windowless GUI host, window style 0, zero flash). Do not revert the actions to bare powershell.exe.
  • wt.exe silent-fails from scheduled-task contexts (MSIX execution alias). Daemon uses plain Start-Process powershell.exe; do not "upgrade" it to Windows Terminal.
  • schtasks /Create /SC ONLOGON needs an elevated shell ("Access is denied" otherwise). PowerShell *-ScheduledTask* cmdlets stay banned over SSH (reference_sshrequest_vector_schtasks_gotcha).
  • Local 2>$null under $ErrorActionPreference=Stop throws in PS 5.1; remote-side 2>/dev/null inside the ssh command string instead.
  • The claim is mv queue -> claimed (atomic, same fs); daemon restarts cannot double-launch.
  • Claim happens on the NEXT poll tick, so checkbox-to-URL is typically 15-45s.

Security posture

Standing channel is launch-Claude-only, never arbitrary shell; every launch logs to launcher-daemon.log and opens a visible window (plus best-effort toast). One schtasks /Delete kills the channel. Vector sessions run --dangerously-skip-permissions like Console workers.

Known limitations

  • Vector sessions do NOT appear in the launcher's Active list (it reads Console tmux sockets); you get the URL at spawn time only.
  • No Wake-on-LAN: Vector asleep = "Vector not reachable" within seconds. The watchdog does NOT cover this (it can't restart a launcher when Vector is off); it covers logoff / crash / wedged-loop while Vector is up.
  • resume and Advanced Prompt are Console-only (API 400s the combo).
  • Fail-fast verified for the no-heartbeat case; daemon-stopped-stale + watchdog self-heal both exercised e2e 2026-07-09.
  • Found dead during this build: Forge-WatchSSHRequests task on Vector never showed the /sshrequest approval dialog; grant flow is broken until repaired.

[Claude Code]