fix: make amplifier-agent work on native Windows (stdio encoding, getsid, fcntl, git prerequisite)

[David Koleczek (DavidKoleczek)]

Makes amplifier-agent actually run on a bare native Windows host. Three independent code defects, each on its own commit, plus the documentation gap that made the failure unrecoverable for a new user.

What this fixes

1. UnicodeEncodeError after the turn had already completed.

Python picks the console code page for stdio, which on Windows is a legacy single-byte encoding (cp1252 on the guests we tested). Writing a reply containing any character outside that page raised at the final write — after the model call had run and been billed. main() now reconfigures stdout/stderr to UTF-8 before dispatch, honoring an explicit PYTHONIOENCODING and skipping streams already UTF-8 or not reconfigurable.

Not gated on platform: the trigger is a stdio encoding that cannot represent the payload, not the OS. POSIX under LC_ALL=C PYTHONCOERCECLOCALE=0 PYTHONUTF8=0 fails identically. On a normal UTF-8 host this is a no-op.

Two corrections to the original report, confirmed while fixing it. First, the exposed surface is exactly one line — single_turn.py's text-mode reply write. The JSON envelope paths are ASCII by construction via json.dumps(ensure_ascii=True), jsonrpc.write_message encodes to UTF-8 itself, and click.echo does its own encoding and never raises. Second, an em dash is not the trigger; U+2014 is representable in cp1252. What actually crashes is a character with no cp1252 mapping, such as U+2713 or CJK.

2. AttributeError: module 'os' has no attribute 'getsid'.

The session-leader step at the top of run called a POSIX-only API unconditionally.

3. fcntl imported at module scope in migration.py.

fcntl is Unix-only, and the module says so in its own docstring — the defect was expressing that scope as a bare import, which broke the entire CLI rather than the one command that cannot work there. fcntl is now imported optionally and file_lock raises MigrationUnsupportedError when it is absent. amplifier-agent migrate on such a platform exits 1 with {"error": "migration-unsupported: ..."} rather than crashing the CLI.

Refusing rather than locking as a no-op is deliberate: the migrations move user data and re-check their preconditions under the lock, so running unlocked would trade a documented platform limitation for a data-loss race. No behavior change on Linux or macOS.

4. git was a silent, undocumented requirement.

install.sh checked for uv and curl but not git, and neither README.md nor docs/INSTALL.md listed it. git is not a build-time nicety — bundles and modules are fetched by cloning git repositories, so a machine without git on PATH fails twice: while priming the cache during install, and every subsequent time a bundle is mounted at run time. On a bare Windows host, where git is not present by default, this surfaced as an opaque clone failure naming neither the missing dependency nor the remedy.

README.md and docs/INSTALL.md now list git alongside uv and curl, noting that it is needed at run time and that Git for Windows supplies both git and the bash the shell tool looks for.

The documentation is what carries this on Windows, and the distinction is worth stating plainly: install.sh is a bash script, and on Windows bash is itself supplied by Git for Windows — so a user who can run the installer at all necessarily already has git, and an installer-side check can never fire for them. install.sh did also gain an up-front check with a per-platform install hint, but its real coverage is the environments where bash is present without git: minimal Linux containers, slim CI images, and fresh WSL distributions.

Scope: what this deliberately does NOT do

An earlier revision of this PR also swapped the shell tool on Windows, mounting tool-pwsh (from amplifier-bundle-windows-shell) instead of tool-bash. That commit has been reverted and is no longer part of this PR.

Why it was pulled out:

• It was a feature riding inside a bugfix PR, and much the largest and riskiest part of the diff.
• It depended on amplifier-bundle-windows-shell, a single-commit proof-of-concept repo with no tags and no CI, pinned by commit SHA.
• It changed the tool name the model sees (bash → pwsh) on one platform. That is a behavioral fork with real blast radius: anything matching the shell by literal tool name has to name both, and the shipped plan and brainstorm mode tool policies had to be edited or the shell would have been unpoliced on Windows.
• It cost every POSIX user an extra clone during cold-prepare, because the manifest is static and its sha256 is the prepared-cache key, so there is no conditional form — both tools had to be declared and installed.

The underlying Windows shell problem is real, and is being fixed in tool-bash itself, where it belongs:

• fix: Windows Job Object process linkage for tool subprocess isolation amplifier-module-tool-bash#15 fixed the foreground path — a missing bash now yields an actionable "install Git for Windows or WSL" error instead of a bare [WinError 2] The system cannot find the file specified.
• fix: close the background-path gap where missing bash silently ran commands with no shell amplifier-module-tool-bash#17 closes the matching gap on the background path, which fix(ts-wrapper): remove prepublishOnly to unblock CI publish #15 missed. That path still fell through to a no-shell Popen, which either produced the same bare OS error or — worse — launched successfully and reported success=True while silently discarding &&, pipes, ~, and $VAR.

Combined with the git prerequisite documented here — Git for Windows supplies the bash that tool-bash looks for — a Windows user gets a working shell without a platform-forked tool name.

Verification

The three code defects were each reproduced on a Windows 11 guest before the fix and confirmed after; the per-commit messages record the console code page, the failing traceback, and the post-fix behavior. The installer's git check was exercised directly by running install.sh under a PATH with git removed, confirming it refuses with the per-platform hint and exits 1. main has been merged into the branch and it is conflict-free.