Planned Python move

Caution

This page describes a plan. Nothing here is built, and the decision is still leaning, not final. Today the factory is PowerShell.

Why

Several PowerShell mistakes parsed fine and failed only at run time. A \b in a path became a control character. An argument list built with @(...) + @(...) passed a bare + as an argument and silently broke every acceptance check for hours. A variable name that differed only in case overwrote a parameter. A wait loop matched the start of a line but every log line started with a time, so a failed session start waited for the full timeout. A callback’s printed output became part of a function’s return value. A typed language with a compiler or a type checker would catch most of these before a run. The repository already guards against some of them with Pester tests, such as a syntax tree test that forbids a bare + argument.

What exists today

About 3,200 lines of PowerShell plus the Python report script scripts/runs.py. The orchestrator is factory.ps1 and its modules. The agent runner is Invoke-Agent.ps1. The VM layer is vm-e2e.ps1, vm-session.ps1, vm-do.ps1, vm-proof.ps1, accept.ps1 and the guest scripts. Tests are Pester under factory2/tests and tests/factory.

The options that were considered

1. Keep PowerShell, guarded by Pester and syntax tree checks.
2. A Python orchestrator with a thin PowerShell layer for Hyper-V. This is the leaning choice. Python is already needed for Graphify, DuckDB and runs.py, and the Claude Agent SDK could replace Invoke-Agent.ps1.
3. C#. It matches the plugin and checks types at compile time, but the Agent SDK is for Python and TypeScript, so it would still shell out to claude.
4. Remove PowerShell from the VM layer too, with a small guest agent in the logged in desktop session that exposes click, type, screenshot, read-UI-tree and install-build over a socket.

What the Agent SDK might add

• Typed tools for the acceptance agent (click, screenshot, read_ui) that call the guest directly. Today it writes step files and runs them through a command allow list, and the permission matcher has cost hours.
• Permission callbacks and hooks in code instead of regular expression rules and stream parsing, with telemetry coming from hooks.
• Structured output and per message cost built in.

Two things to verify first

1. Whether the Agent SDK can use the owner’s local claude login. The factory never uses an API key or a token, and this is believed but not verified.
2. The guest agent protocol, and how Flare’s UI automation behaves under it.

Suggested order

Each stage keeps factory.ps1 working and is proved on a real issue.

1. Verify the login question and write down the requirements in Invoke-Agent.ps1.
2. Port the agent runner to Python behind the same command line, with parity tests.
3. Port the gate, the build module and telemetry, keeping the event names so runs.py keeps working.
4. Port the loop, the VM queue and the claims.
5. Acceptance with typed VM tools and the guest agent.
6. Delete the PowerShell that is left, apart from anything Hyper-V still needs.

Nothing is rewritten while a factory run is going, because a running process keeps the modules it started with.