feat(flows): add the local and ssh environment drivers

[futrime]

Wave 1, unit 4: the environment drivers behind hmz.runtime.flowing.spi.EnvDriver. This PR is based on feat/new-flow-api.

Public API (hmz.runtime.flowing.environments)

• open_env(spec: EnvSpec) -> EnvDriver: local@/abs or ssh@[user@]host[:port]/abs or ssh@host/~/rel. It never touches the network. It raises EnvUnavailable when a local workdir is missing or the ssh destination is invalid (for example, one starting with -).
• local_env(workdir: Path) -> EnvDriver: fills a LocalEnv role.
• probe(driver) -> None (new): connects and learns the machine's resources off the loop, then checks that the workdir exists. It raises EnvUnavailable or EnvConnectionError. The ways in should await it on every root env before checking resource requirements. Until it runs, an ssh env reports available=False and cpu 1, memory 0, gpus 0. It is not in the lazy-export table, because runtime/flowing/__init__.py belongs to unit 2.
• Both drivers are MachineEnvDriver, and each serves every item of ENV_CAPABILITIES.

Semantics the engine relies on

• exec
  • Every command runs in its own process group with stdin empty. stdout and stderr come back separately.
  • A timeout, a cancellation, or close() kills the whole group and ends the wait. This holds even when a setsid daemon keeps the output open.
  • A non-zero exit is returned rather than raised. A process killed by signal N reports 128 + N.
• Holders of temp clones
  • Holders are compared with ==, and they are tracked process-wide.
  • On this machine, an flock also makes other processes' holds TempCloneBusy. Over ssh, exclusivity is per process only.
  • Closing the root drops its holds, so a run resumed in the same process can take them again.
• destroy_* must be called before closing the root. Closing the root is final: every driver on that machine then raises EnvError("... is closed").
• A temp clone is a reflinked copy where the filesystem supports it, .git included, and its repository stands alone:
  • Worktrees nested inside it are repointed to the copy.
  • A linked-worktree workdir is re-cloned with --shared and keeps its index.
  • Gitfiles that lead outside the copy are cut loose.

On disk

Everything lives under humanize's home on that machine: hmz.home() locally, ${HUMANIZE_HOME:-~/.humanize} over ssh.

• envs/<name>-<digest(workdir)>/clones/<id>-<digest>/, plus a .lock file beside each clone.
• envs/<name>-<digest(workdir)>/scratch/<id>-<digest>/.
• envs/<name>-<digest(workdir)>/worktrees/<ref>-<random>/.

Names are deterministic, so a resumed run reattaches. A copy is built next to its final path and renamed into place; removal renames it away before deleting. The whole envs/ directory is safe to delete whenever no run is using it.

SSH

• It uses coganchor's transport: transport.connect(ssh://…, ["/"]) plus RemoteClient, with the zipapp bootstrapped over ssh and ControlMaster giving one master connection per host.
• One probe command reports home, humanize's home, CPUs, memory, and GPUs.
• placement() returns Placement(SSH, provider, workdir, AnchoredConfig(AnchorConfig("ssh://provider", workspace=<abs workdir>))). For a ~ workdir it returns the absolute path once probed, and remote_path="~/…" before that.
• There is one coganchor fix, in its own commit: ExecSession.signal now reaches the group after the leader has exited, so remote timeouts actually kill background children.

Tests

• Unit (tests/unit/flows/test_env_drivers.py): the driver contract over an in-memory machine, plus holds, closing, paths, error mapping, GPU and probe parsing, and building an ssh env without touching the network.
• Integration (tests/integration/flows/test_{local,ssh}_envs.py): check_env_driver(..., repo=True) against real processes and the version-control tool. The ssh path runs through a stand-in ssh with coganchor's real serving half.
• System (tests/system/flows/test_ssh_envs.py): the contract over real ssh. It uses localhost if passwordless ssh works; otherwise it starts a throwaway loopback sshd with its own keys and leaves ~/.ssh untouched. Here it ran against the throwaway sshd: 2 passed.
• uv run pre-commit run --all-files passes, and uv run pytest passes across all three tiers.

🤖 Generated with Claude Code