test(fleet): add a write-containment guard and a two-node facts smoke test

[toasterbook88]

What

A safety boundary for fleet tests (internal/fleettest), plus the first test that uses it: a two-node read-only facts smoke, gated behind //go:build fleet with a make test-fleet target.

Why the guard exists

Fleet tests run real AXIS binaries against real nodes, so whatever AXIS_HOME resolves to is writable by the test. Exporting a suite-wide AXIS_HOME at a live store is enough for config-writing tests to rewrite it — cmd/axis/llm_test.go simulates axis llm configure and writes provider entries. That happened during development of this branch: a live ~/.axis had fixture provider config written into nodes.yaml and a secrets/ directory created.

The guard makes that unrepresentable. A fleet test takes its environment from a Guard, and a Guard cannot be constructed around a path outside its own run root.

Enforcement is programmatic rather than conventional on purpose. The Makefile already documents that AXIS_HOME outranks HOME; a comment does not stop an export on the command line, a constructor that refuses does.

Not a production helper. Nothing under cmd/ imports it — asserted with go list -deps ./cmd/axis — so it never enters the shipped binary and cannot reject a legitimate operator store during normal use. A guard wired into production resolution would either do that or be skipped by any caller that forgot it.

The guard

• creates its own unique run root; resolves run root and AXIS_HOME physically before comparing
• requires strict descendancy — the root itself is rejected
• isolates HOME as well, since persist falls back to it when AXIS_HOME is empty
• rejects empty, whitespace, relative, ..-bearing, symlink-escaping, unresolvable, dangling-link and prefix-lookalike paths
• RemoteCommand re-verifies containment on the far side with POSIX builtins and exits 78 if it cannot confirm — the controller cannot see the remote filesystem
• RemoteRoot derives the remote run root from the local run root's unique suffix, so overlapping runs cannot collide on a shared remote path
• leaves run directories in place; retention is a separate concern

The smoke test

Collects facts from the controller and one remote node concurrently and asserts invariants — arch and hostname non-empty, CollectedAt present and recent, no node reporting complete alongside an error, transport failure surfacing as StatusUnreachable rather than healthy. Writes a structured JSON report under the run root.

Targets come from AXIS_FLEET_TARGET ([user@]host[:port]), with optional AXIS_FLEET_TARGET_NAME and AXIS_FLEET_CONTROLLER. It skips when unset — absent a fleet there is nothing to assert, and failing would report the code as broken when only the environment is missing.

Verification

• make test 42/42; the fleet test does not run there (build tag confirmed)
• skip path verified with no target configured; PASS verified against a configured target
• gofmt and vet clean on both tagged and untagged builds
• Adversarial table of 14 cases; two defects found while writing it — a dangling symlink was accepted, and the .. cases were built with filepath.Join, which normalises .. away before the check sees it. Both fixed
• Mutation-checked against the real code: removing the symlink check, the .. guard, the per-node assertions, or breaking RemoteRoot each fails the corresponding tests

Caveat

Containment requires mkdir -p of a run root on the remote, so this tier is not strictly read-only against a cluster. Writes are confined to /tmp/<run-id>-<node> and never removed, consistent with the no-delete policy. Retention across repeated runs is open.

Note on merge order

Touches Makefile alongside #271 (test-fleet vs install-system/test-install). Whichever merges second will need a trivial conflict resolution.

🤖 Generated with Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.