windows-remote-bootstrap

Windows Remote Bootstrap

Purpose

Remote Windows work fails most often at handoff boundaries: wrong directory, stale payload, hidden prompt, nested quote stripping, missing PATH entries, orphaned child processes, blocked elevation, or silent success without proof. Make every step absolute-path, failure-loud, and independently verifiable.

Standard Workflow

1. Confirm the intended target before staging. If your environment documents its canonical VM and physical-runner targets, lane gates, and fail-closed states (a runner-registry skill, an AGENTS.md block, or a runner manifest), read that first and treat it as authoritative.
2. Stage payloads in a fixed directory such as C:\AgentInstallers\<task>\<stamp> or C:\CodexRunner\bootstrap.
3. Transfer, then prove freshness with filename, size, timestamp, and preferably SHA-256.
4. Invoke transferred .ps1 files with an absolute -File path:

   powershell -NoProfile -ExecutionPolicy Bypass -File C:\path\payload.ps1
   

   If the script parameter is a live PowerShell object such as [pscredential], invoke the script in the current PowerShell session with & C:\path\payload.ps1 -Credential $cred instead of launching a nested powershell.exe -File; native process boundaries stringify objects and can cause false authentication failures.
5. Put complex remote logic in the payload, not in an inline SSH -Command string.
6. Print a final status line and write JSON/log artifacts under a known run root.
7. Make reruns idempotent, or explicitly remove only a verified task-owned workspace.

SSH To Windows

• Assume the remote SSH shell may be cmd.exe or another shell that strips nested quotes before PowerShell sees them.
• Prefer scp payload.ps1 plus powershell -File C:\absolute\payload.ps1.
• Stage large or complex payloads as files. Windows SSH command lines can fail with The command line is too long long before the script logic runs.
• If inline execution is unavoidable, run a tiny quoting probe first that prints received arguments exactly.
• Avoid PowerShell $() syntax in remote one-liners unless it is protected from local-shell expansion.
• For long runs, write timestamped step logs before and after external commands so hangs identify the boundary.