Farrow 0.2.0

Farrow 0.2.0 is a correctness and hygiene release on top of 0.1.0. It changes
how every command behaves at its boundary — under signals, in --json/--yaml
output, and when given misspelled input — and adds the gates that keep those
boundaries in place. The engine contract, the inventory format, the on-disk
state layout under $FARROW_HOME, and the embedded image catalog
(revision 2026082903, 9 families, 27 artifacts) are unchanged. 0.1.0
deployments continue to work without migration.

Highlights

• VPN split routes no longer block a healthy lab. A less-specific route
  such as MonoProxy's physical-interface 10.0.0.0/8 exclusion cannot beat
  Farrow's owned 10.10.10.0/24, so preflight now permits it. Equal and
  more-specific foreign routes, overlapping interfaces, occupied addresses,
  and a missing owned /24 remain hard failures.
• Guest host markers converge on deployment terminology. New and
  recreated guests delete both # farrow-project-host and
  # farrow-deployment-host rows before writing only the deployment marker,
  so upgrading never duplicates Farrow-owned /etc/hosts entries.
• Selected scale-out is truly selected. farrow up u24-1 no longer
  downloads every image named elsewhere in the inventory. Desired peers that
  have not been created are reported as absent; port/UUID allocation,
  stop/start/destroy, persistent-disk validation, and generated SSH/hosts
  integrations all operate on committed nodes without losing the full desired
  inventory used by later incremental up.
• Clean cancellation. SIGINT/SIGTERM cancel long-running commands
  through one context: the progress line stops, held locks are released, and
  the command exits 130 with exactly one structured result
  ({"error":"cancelled"}). An interrupted up, recreate, or destroy
  still appends its event to events.jsonl, so the audit trail shows what the
  signal cut short. Ctrl-C inside an SSH session stays remote.
• reload is one operation. Definition drift and removed inventory nodes
  are refused before any node stops, so a configuration that needs
  recreate or destroy never takes a healthy lab down; --json emits a
  single document instead of one per phase.
• Misspelled nodes are refused, not executed. farrow ssh metaa -- uptime
  is a usage error instead of running metaa uptime on the control node.
  Unknown or repeated node selectors on any lifecycle command exit 2 before
  host preflight or a confirmation prompt. The ambiguous no--- form warns
  once; -- remains the unambiguous and recommended remote-command boundary.
• Confirmations are exact. destroy asks for the same destroy token
  whether or not nodes are selected and prints the exact scope (nodes,
  persistent disks, keys, state) first. setup treats end of input at its
  [Y/n] prompt as a cancellation; only an answered prompt defaults to yes.
• Structured output keeps its reasons. Every failure that used to be
  written straight to stderr now reaches the --json payload with its
  category; presentation flags never change an exit status. Verbose
  diagnostics redact credentials and query strings from source URLs.
• Smaller dependency graph. Viper and its nine transitive modules are gone;
  the shipped license inventory drops from 19 modules to 9 and the binaries
  read FARROW_OUTPUT/FARROW_VERBOSE directly.
• Installer retention. install.sh and development builds keep at most
  three verified release directories under .farrow-releases
  (FARROW_INSTALL_KEEP=N, 0 disables); current is never touched.

Compatibility notes

• 0.1.0 deployments remain readable without an on-disk format migration. After
  upgrading, run farrow status while each retained VM is live so any
  pre-release process-birth identity can be rewritten from native evidence.
• A pre-0.1 development deployment whose resolved network is user is not a
  released format. Preserve any required disks, destroy that development
  deployment explicitly, and rebuild it on the fixed-IP network.
• Existing guests keep their current /etc/hosts bytes until they are
  recreated. Every 0.2 seed removes both the 0.1.0 project marker and the new
  deployment marker before writing the current rows.
• New exit code 130: interrupted by SIGINT/SIGTERM, or a confirmation was
  declined. Scripts that checked for 2 after a mismatched destroy token or
  4 after answering no to setup must accept 130; a missing --yes or
  --force on a pipe remains 2.
• farrow logs --source events rejects a node argument; it is the
  deployment-wide log.
• farrow image list help now says what the command always did: every
  architecture is listed; info and pull select the native one.
• Diagnostics say deployment where they used to say project. JSON keys and
  file names are unchanged.

Validated boundary

The current source ran a real macOS arm64/HVF replay with MonoProxy's covering
10.0.0.0/8 route present: selected u24-1 creation, SSH, stop/start,
incremental cached el9-1 creation, whole-deployment status with five absent
desired peers, both SSH connections, and full destroy/SSH-fragment cleanup all
passed. On Ubuntu 26.04 amd64/KVM, the current Linux binary audited an existing
four-node deployment as live and reached its control guest over the persisted
SSH identity without mutating that host. make check, the source CI, and the
packaging workflow — including race, four-target builds, installer boundaries,
SBOM/package verification, and the development archive — are green.

For contributors: deadcode (four-target intersection), errcheck, and a
maintenance-inventory check are part of make check; CONTRIBUTING.md
carries an expiry table for every pre-0.1 compatibility path.

Start

Download the archive or native Linux package for your host from this Release.
The release install.sh performs a user-scoped archive install after checking
the selected asset against the checksums.txt generated by GitHub Actions:

chmod +x install.sh
FARROW_VERSION=0.2.0 ./install.sh
farrow setup --dry-run
farrow setup --yes
farrow up

Upgrading from 0.1.0 is the same command; the installer switches the current
link atomically and prunes older release directories beyond the retention
bound. Review the installation and privilege boundary before applying setup:
https://farrow.pgsty.com/docs/start/tutorial/.