Skip to content

feat(runner): support native Windows execution and guided onboarding - #172

Closed
AaronWangCong wants to merge 14 commits into
Tencent:mainfrom
AaronWangCong:codex/windows-local-runner
Closed

AaronWangCong wants to merge 14 commits into
Tencent:mainfrom
AaronWangCong:codex/windows-local-runner

Conversation

@AaronWangCong

@AaronWangCong AaronWangCong commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

What changed

Windows users can connect their local machine to a remotely deployed Linux platform and execute assigned SOP tasks. Previously, Unix-only process, locking and filesystem operations prevented reliable native Windows Runner execution, and the onboarding page only offered a Bash command.

  • Add native Windows process-tree management, locks, workspace identity, hardlink checks, managed asset snapshots, CLI discovery, long Git Bash scripts and executable Gate MCP helpers, while preserving Unix implementations.
  • Include Windows amd64/arm64 helpers in the build and download paths. Disable Windows self-updates and provide safe manual stop/start upgrades.
  • Add a standalone PowerShell installer served by the platform. It downloads matching Runner and Gate binaries, verifies checksums and PE architecture, and keeps separate per-platform configuration, binding and workspace state. Native execution needs no source checkout, Go toolchain or local Docker installation.
  • Offer accessible macOS / Linux and Windows · PowerShell tabs in “Connect a new machine.” macOS / Linux stays first and is always the default. Switching updates instructions, copy commands and maintenance controls together; expired binding codes cannot be copied.
  • Support Windows PowerShell 5.1 and PowerShell 7, preserve UTF-8 downloads, safely quote process arguments, and check process identity before stopping. Restart retains the existing binding and workspaces.
  • Keep the source-checkout platform/Runner launchers, add installer regressions to the existing Windows CI, and document both onboarding methods.

Scope

  • Platform core / API / runner
  • Public adapter / deployment
  • Classic
  • Portable
  • Shared behavior contract
  • Installer / CLI
  • Documentation only

Compatibility

The platform remains Linux-hosted; the native Windows Runner connects outbound to it. Shell SOP nodes require Git for Windows, project commands need their usual local tools, and Agent nodes require a supported native .exe CLI and its configured authentication. npm batch wrappers are not advertised as native runtimes. Docker sandbox workflows still need their configured Docker environment.

Windows non-interactive SOP execution and workspace operations are supported. Interactive web PTY sessions remain unsupported on Windows. Cancellation terminates the Windows process tree immediately; background descendants do not survive their parent task. Windows amd64 has live coverage; arm64 is cross-compiled. Homepage assistant and requirement clarification retain their existing server-side credential requirements.

No schema migration or Runner protocol change is required. Machine authentication and machine-card authentication-source selection retain their existing behavior. No private adapters or deployment configuration are included.

Validation

Current onboarding follow-up:

  • Built the embedded chatbot and the Linux platform plus native Windows Runner/Gate binaries from this PR branch.
  • Passed 9 standalone installer tests with Windows PowerShell 5.1 and again with PowerShell 7, including raw HTTP bytes/BOM, checksum failure, saved identity, stop/start isolation, argument boundaries and real Windows 8.3 path aliases. Directory assertions compare filesystem identity and resolved paths, so CI temporary-directory aliases cannot produce false failures.
  • Passed the 7 runner UI tests and Go bundle, JavaScript syntax and onboarding checks.
  • Passed Windows Shell → Node → workspace artifact, long-script cancellation and Git Bash/WSL-alias regressions; passed installer/download/authentication-boundary tests on Windows and Linux.
  • Deployed the branch to an isolated Linux/MySQL installation, downloaded and bound a real Windows amd64 Runner, selected it as the default machine, and completed a real script → human approval → script SOP. Downloaded the Windows-generated artifact and verified continuation in the same workspace. Stop/start retained the same registered identity and configuration.
  • Passed Chromium checks for tab order/default, keyboard navigation, clipboard, refresh, both themes, reduced motion, and 1440/390/320 px layouts. Screenshots mask binding codes.
  • Passed the public-content check, secret scan and diff-format check.

Latest follow-up d11a33fa7bfe18458363db60dddab41aa8414abf merges upstream main at 0721241, resolves the browser endpoint conflict, and preserves Windows compatibility with the new Git lock and workspace preview code. Unix file ownership checks retain their existing behavior; Windows file URLs resolve drive paths while workspace containment still rejects outside files and junctions. UNC/device paths remain unsupported.

Local verification for this follow-up passed the Windows CI package-test selection, vet, Runner/Gate builds, PowerShell 5.1/7 installer tests (9 each), 315 chatbot tests and build, 12 onboarding/access tests, and Linux runtime/API/preview regressions. The Linux bind-mount namespace case was skipped by the container environment; hardlink and ownership cases passed. Official CI for this current head passed all 17 checks: Windows Runner and PowerShell, platform core, browser, coverage and vet, E2E, and validation and secret scan.

Previous head 6fd3fe323340fbab43f33daf8d9b80f9e60852b9 passed all 17 official checks, including the required gates (these are historical results, not results for the new merge):

That previous head also passed all four workflows in the fork verification PR. Paid-model and external-service acceptance was not enabled.

Safety

  • I did not include credentials, internal endpoints, production data, or organization-specific infrastructure.
  • I preserved user files and unrelated changes.
  • I updated generated Classic host bundles when applicable.
  • I documented third-party content and licensing changes when applicable.

Classic host bundles and third-party dependencies/assets are unchanged.

@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head c454878fc7a59644085eefd31ae542548f64ade6

Verdict: ⚠️ Verification blocked

  • Diff: 73 files, +2773/-141 — almost entirely Go with unix/windows build-tag splits (internal/processgroup, internal/procwatch, internal/runtime/*_windows.go, internal/preview/archive_links_windows.go, internal/httpapi/*_windows*.go), plus new PowerShell launchers (scripts/start-local.ps1, scripts/start-local-runner.ps1) and a new .github/workflows/windows.yml.
  • CI has not produced results yet on this head SHA: only the opensource-scan check has run; the main platform workflow and the new windows workflow show no check runs at all. Adding/modifying a workflow file (.github/workflows/windows.yml) commonly requires a maintainer to approve running Actions for first-time/external workflow changes — that may be why nothing has started.
  • This sandbox has no Go toolchain and no Windows runtime, so I can't compile or run either the unix-tagged Go tests or the new *_windows_test.go files. scripts/test-windows-startup.py's test class is explicitly @unittest.skipUnless(os.name == "nt" and POWERSHELL, ...) — confirmed by reading the file — so it would just skip here. Spot-read internal/processgroup/process_windows.go and internal/runtime/workspace_lock_windows.go; the golang.org/x/sys/windows usage (Job Objects, LockFileEx/UnlockFileEx) looks structurally sound but can't confirm it builds or behaves correctly without a Windows toolchain.

Missing to resolve: (1) get the platform/windows Actions checks to actually run on this SHA (approve the workflow run if it's pending on maintainer action), and (2) a Go+Windows environment to build and run the new *_windows_test.go suite and scripts/test-windows-startup.py.

@AaronWangCong could you check whether the CI run is stuck pending approval, and let us know once the Windows-side checks have results?

@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head 3f526d4f98e6e65fe70b5ce3fb5e4420a6ba6a67

Verdict: ⚠️ Verification blocked

  • Re-review: head moved from c454878fc7a59644085eefd31ae542548f64ade6 (previously blocked) to 3f526d4f98e6e65fe70b5ce3fb5e4420a6ba6a67. Diffed the two directly: only CI runner-OS pinning (ubuntu-22.04/ubuntu-24.04 to match the Python 3.8 / Playwright 1.55 toolchains after ubuntu-latest moved to 26.04), the Go 1.26.11 security-patch bump (go.mod/Dockerfile/README, GO-2026-6859), and one added Windows-only regression test (8.3 short-path alias + a stricter PATH-prefix assertion in scripts/test-windows-startup.py). No change to the Windows runtime/runner implementation itself since the last review.
  • A Go toolchain is available this time, so I could do what was missing before:
    • go build ./... on Linux → succeeds.
    • GOOS=windows GOARCH=amd64 go build ./... → succeeds for the whole repo — the actual Windows runtime/runner code compiles cleanly.
    • GOOS=windows GOARCH=amd64 go vet on every package this PR touches (internal/processgroup, internal/procwatch, internal/runtime, internal/runner, internal/httpapi, internal/preview) → clean, including the new *_windows_test.go files; go test -c cross-compiles a runnable Windows test binary for each of the 6 packages without error.
    • (Non-blocking FYI: GOOS=windows go vet ./... on the whole repo still fails on an unrelated file this PR doesn't touch, cmd/agentflow/handover_test.go (syscall.Kill with no build tag) — already broken the same way on main before this PR, and outside the package set the new windows.yml actually runs.)
    • Linux-side tests for the same package set: procwatch, runner, preview, httpapi → all pass. internal/runtime has 6 failures, but I confirmed byte-for-byte the same 6 fail on main with this PR reverted (no Docker daemon / no exec-bit preservation / no real git remote available in this sandbox) — pre-existing sandbox limitations, not a regression from this PR.
  • Still missing: this head SHA has only the GITHUB_OPENSOURCE_SCAN_PIPELINE check run; the platform and new windows GitHub Actions workflows have produced no check runs at all (same as the prior review). Since this PR adds/modifies .github/workflows/windows.yml, Actions most likely still needs a maintainer to approve running workflows for it.

Missing to resolve: get the platform/windows Actions checks to actually execute on this SHA (approve the pending workflow run if that's what's stuck) — the engineering-side blocker from the last review (no Go/Windows toolchain) is now cleared with the results above.

@AaronWangCong the implementation now has clean local build/vet/test evidence on both Linux and cross-compiled Windows; the only remaining gap is that CI hasn't produced any results on this SHA yet — could you check whether the windows/platform workflow runs are stuck pending approval?

@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head 9bfc8a576a0045c2976a829b7a1a4c31b9b7ca4b

Verdict: ⚠️ Verification blocked

  • Re-review: head moved from 3f526d4f98e6e65fe70b5ce3fb5e4420a6ba6a67 (previously blocked on missing CI) to 9bfc8a576a0045c2976a829b7a1a4c31b9b7ca4b. 3f526d4f is an ancestor of the new head; the diff in between is fix(runner): disable Windows self-updates before claiming work plus a merge of upstream main (settings-nav consolidation, model catalog, workflow-publish fix, Go security patch fix(deploy): update Go security patch and install missing prerequisites #179) — no changes to the Windows runtime/runner implementation itself.
  • go build ./... (Linux) → succeeds. GOOS=windows GOARCH=amd64 go build ./... → succeeds for the whole repo. GOOS=windows GOARCH=amd64 go vet on every package this PR touches (internal/processgroup, internal/procwatch, internal/runtime, internal/runner, internal/httpapi, internal/preview, cmd/agentflow-runner) → clean; Linux go vet on the same set → clean.
  • Linux tests for the same package set: processgroup (no test files), procwatch, runner, preview → all ok. internal/runtime still has the same 3 failures as before (exec-bit not preserved, no git askpass, Docker idle-reclaim) — re-ran byte-for-byte against base 29fbcc89da9c035a096aac47df2dc8c160803478 and got the identical 3 failures, confirming these are pre-existing sandbox limitations, not a regression from this PR.
  • Still missing: this head SHA's platform, windows, e2e, and validate GitHub Actions workflow runs are all completed / action_required — i.e. awaiting maintainer approval to actually execute; only GITHUB_OPENSOURCE_SCAN_PIPELINE has run. Same gap as the last review.

Missing to resolve: approve the pending platform/windows/e2e/validate workflow runs on this SHA so CI actually produces results — local build/vet/test evidence on both Linux and cross-compiled Windows is already clean.

@AaronWangCong local evidence is unchanged/clean across this increment; the only remaining gap is still CI not being allowed to run on this SHA — could you or a maintainer approve the pending workflow runs?

@AaronWangCong AaronWangCong changed the title feat(runner): support native Windows execution and local startup feat(runner): support native Windows execution and guided onboarding Nov 12, 2026
AaronWangCong and others added 4 commits November 12, 2026 17:27
main Tencent#207 added TerminalPool.HandleSandboxWithGitSSH, which runner and
engine workspace preparation now call; the Windows stub lacked it, so
GOOS=windows go build ./... failed after merging main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head 8fbdc021777175afdd96c9e919bbb431d6e6b2b5
Verdict: ✅ Pass

  • Scope: 96 files, +4091/-210. Adds native Windows Runner support (process-tree/lock/workspace-identity/hardlink/materialize-binding/terminal split into *_windows.go / *_unix.go), a standalone PowerShell installer (deploy/bind-cli.ps1, scripts/start-local*.ps1), a new windows.yml CI job, docs (docs/windows.md), and chatbot UI changes adding a Windows · PowerShell onboarding tab alongside macOS/Linux (which stays first/default).
  • Checked out the head SHA in an isolated, credential-free sandbox (no Docker, no production access): go build ./... and go vet ./... both clean on linux/amd64; cross-compiled clean with GOOS=windows GOARCH=amd64 go build ./..., confirming the new *_windows.go files type-check.
  • go test ./internal/httpapi/... (full suite, 165s) — pass. go test ./internal/processgroup/... ./internal/procwatch/... ./internal/preview/... ./internal/runner/... — pass.
  • go test ./internal/runtime/...: 2 failing (TestMaterializeSkillBinaryFiles, TestHostInsteadOfUsernamePromptThenAskPass). Verified these reproduce identically on main in this same sandbox (filesystem here doesn't preserve the exec bit; the loopback git-auth harness is blocked) — pre-existing sandbox limitation, not introduced by this PR. The Docker-discovery/mask/reclaim tests in that package pass when isolated from that known flake.
  • CI: 17/17 checks green on this SHA (platform-required, e2e-required x4, runner, validate x2, core, secrets, browser, e2e-browser, curl-install, first-run, tcmcp, opensource scan). Note: no physical Windows machine was available in this review sandbox, so native Windows execution wasn't exercised directly here; relying on cross-compilation plus CI's windows.yml job for that coverage.

No blocking issues found.

@AaronWangCong
AaronWangCong dismissed a stale review via 839a9ec November 13, 2026 14:12
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head 839a9ecc23056a8b8c5a1099811c5c99a60efe1a

Verdict: ✅ Pass

No action needed.

@AaronWangCong
AaronWangCong dismissed a stale review via 051b686 November 14, 2026 09:23
@Robert0622

Copy link
Copy Markdown
Collaborator

LoopForge PR Review — head 051b68645d779b43e39392856023576910606648

Verdict: ✅ Pass

  • Re-review: head moved from 839a9ecc23056a8b8c5a1099811c5c99a60efe1a (previously ✅ Pass) to 051b68645d779b43e39392856023576910606648 via "Merge upstream refactors into Windows Runner PR".
  • Checked git diff 839a9ecc..051b6864 (163 files touched overall by the merge) restricted to this PR's own files (internal/runtime/materialize_binding_windows*.go, native_shell_script*.go, process_tree_windows.go, workspace_identity_windows*.go, workspace_lock_windows*.go, workspace_terminal_windows*.go, web/app/runners.js, scripts/start-local*.ps1, scripts/test-windows-*.py, webtest/tests/mcp-sops-runners.test.mjs): byte-identical. The new commit only merges in unrelated upstream refactor/bugfix commits already on main; no change to this PR's own code.
  • GitHub Actions on this exact head: 17/17 checks green (platform-required, e2e-required, core, browser, 4x e2e matrices, e2e-browser, validate 3.8/3.12, secrets, curl-install, first-run, runner, tcmcp, opensource scan).
  • mergeable_state: clean, no conflicts with main.
  • No new risk introduced; previous verdict stands. No action needed from the author this round.

@Yanami-2K Yanami-2K left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

先留评论、不批准:代码可见部分没发现正确性问题,但有几处产品范围和合入顺序的取舍,需要维护者判断。

已核对的部分:internal/processgroup/process_windows.go 用挂起创建 + kill-on-close Job 再恢复线程,子进程在派生后代之前就已入 Job;restart_windows.go 在 Windows 上直接关闭自动更新(fail closed);archive_links_windows.go 不跟随 reparse point,获取元数据失败时中止归档;bind-cli.ps1 会校验 SHA-256 和 PE 架构,并拒绝带凭据的 ServerUrl。Windows CI(runner job)也已通过。

需要维护者确认的问题:

  1. Windows 服务端部署是否纳入支持范围 PR 描述写的是“The platform remains Linux-hosted”,但 docs/windows.md 的“Start the platform”和新增的 scripts/start-local.ps1 支持在 Windows + Docker Desktop 上启动平台,README.md/README.zh-CN.md 也写了“Windows users can use Docker Desktop and the PowerShell launchers”。而 #163 在同一段 README 里写的是“Windows is not supported for server deployment yet”,两者直接矛盾,可见这个产品方向还没统一。请维护者定下口径,然后和 #163 对齐。
  2. 范围偏大 99 个文件、+4162 行,同时包含原生 Windows Runner、Windows 平台启动脚本、独立 PowerShell 安装器、接入页 UI,以及与 Windows 无关的 CI 调整(.github/workflows/e2e.yml 和 validate.yml 把 Python 3.8 锁到 ubuntu-22.04、e2e-browser 锁到 ubuntu-24.04)。建议至少把 CI runner 镜像调整拆成单独的 PR,其余部分由维护者决定是否继续拆。
  3. 后台子进程语义与 Unix 不一致 Windows 上 root 进程退出就会杀掉整个 Job(process_windows.go 里的 WaitForSingleObject 协程),而 Unix 上后台子进程可以继续存活。依赖后台进程的 shell 节点(比如先启动 dev server 再由下一个节点访问)在 Windows 上会表现不同。描述里已说明,请维护者确认是否接受。
  4. 与 #164(x/sys 0.50.0)不冲突,但任一方先合入后,另一方应重新跑 Windows CI。

注:有大量文件的 patch 被省略,包括 internal/runner/daemon.go、detect.go、exec.go、internal/runtime/materialize_binding_windows.go、native_shell_script.go、workspace_terminal_windows.go、scripts/start-local*.ps1、web/app/runners.js 和各 Windows 测试文件,没能逐行审查。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants