Sync Boatstack from Intelligence Flow Labs @ 76a1339c3bfb

[operator-stack-publisher]

What this sync releases

The safety guard auto-hydrates a missing shared runtime, so a version bump no longer strands every teammate

Boatstack never commits the runtime binary: only pointers travel through Git — the guard's baked version path and the committed version pin — while the bytes live in a gitignored, per-version shared slot under the Git common directory, delivered out of band by the tag-pinned, checksum-verified installer. The consequence was a clone-wide lockout: a teammate who pulled a merged version bump, or cloned fresh, held the new pointers but an empty slot, so their very next tool call hit the guard's [[ ! -x "$HELPER" ]] deny — "shared runtime is missing" — before any Go could run. Every version bump stranded every teammate until each manually re-ran the installer. It is the cross-clone cousin of the shared-runtime lockout.

The guard now self-heals. On an absent slot it runs the pinned, checksum-verifying installer in a new branch-free hydrate mode, serialized clone-wide by an atomic mkdir lock (peers wait briefly for the slot to appear) and bounded by a timeout, then falls through to the existing checks. This is purely additive: the missing / symlink / manifest / checksum gates remain the sole authority for exec and stay fail-closed, so a disabled, timed-out, or failed hydration simply denies — now with the exact one-line self-heal command embedded in the message.

Hydration is a new slot-only hydrate-runtime helper subcommand. Unlike update, it requires no dedicated branch and rewrites no committed generated file — it only populates the gitignored shared slot and the worktree's ignored bin/. It refuses to populate a slot whose identity disagrees with the worktree's committed pin, and because the installer downloads the exact pinned version before invoking it, running equals installed by construction; the runtime-cache write's own re-hash-and-rollback is the backstop. So a version-labeled slot can never durably hold another version's bytes.

This is a deliberate security-posture change — the guard now runs a fetched installer on cold start — bounded by: the tag-pinned installer URL over HTTPS, the release .sha256 sidecar verified inside the installer, the guard's own checksum gate re-verifying the slot before exec, the clone-wide lock, the timeout, and a BOATSTACK_AUTO_HYDRATE=0 kill switch (plus a BOATSTACK_HYDRATE_COMMAND override). A conformance suite pins the boundaries: auto-hydration proceeds on success, fails closed on installer failure, is skipped when disabled, always invokes the hydrator with the pinned provenance, and runs at most once under concurrent first use; the hydrate-runtime primitive is idempotent, refuses a running-vs-pin mismatch, and touches no committed generated file. The failure-move catalog records the class as Cross-clone runtime-absence lockout.

update -binary installs the passed binary's own verified version — a mislabeled runtime can no longer fail-close a whole clone

update -binary <path> did not upgrade to the passed binary's version. It re-stamped the running helper's version onto the passed bytes: an operator running v0.7.54 who ran update -binary <v0.7.57 binary> got v0.7.57 bytes written into the v0.7.54 slot, under a runtime.lock.json declaring boatstack_version: v0.7.54 with the v0.7.57 checksum. The lock was internally consistent, so both checksum gates passed — but the binary self-reports v0.7.57, so the version gate fail-closed. Because the verified runtime is shared across a Git clone, every worktree's guard denied at once, with no in-host way back (the guard denies before it can parse the recovery command).

The root cause is a cross-origin identity/checksum split: the write path took the artifact's declared identity (version, commit) from one origin — the running process's compile-time globals — while binding its integrity proof (checksum) to a different origin — the passed bytes. A checksum proves these bytes match this lock; it never proves this binary is the version it claims.

The fix moves provenance enforcement to the one boundary that writes it:

• Cross-version update -binary re-execs the candidate. Each helper embeds its own version-bound generated bundle and constants, so an older helper cannot correctly install a newer one in-process. When the passed -binary self-reports a different identity (read by executing its version subcommand), the entire update is handed off to that binary, which installs itself. Running then equals installed, so its bundle, constants, version-keyed slot path, and durable receipt are authoritative by construction, and the hand-off terminates in a single hop.
• init/update -binary refuse a directly-passed mismatched binary rather than stamping this process's version onto foreign bytes, naming the mismatch and pointing at the target binary's own updater.
• The runtime-cache write re-hashes the freshly written slot against its manifest and rolls back (removing the slot) on any mismatch, so a version-labeled slot can never durably hold another version's bytes even under a mid-write race or tamper.
• Read-boundary messages now guide an operator to re-run the verified installer to repopulate or repair a bad slot. Identity is deliberately not re-derived by executing the cached binary on every guard event — that hydration path stays checksum-only for cost, because provenance is now guaranteed where it is written.

A new runtime_provenance_test.go conformance suite pins the boundaries as named-property tests: cross-version update re-execs instead of installing in-process, a mismatched init -binary refuses and writes nothing, a matching -binary adopts the verified identity, normal self-install is unaffected, and version-output parsing is covered. The failure-move catalog records the class as Provenance-blind runtime install.

Projection provenance

Generated from operatorstack/intelligence-flow@76a1339c3bfb8c7a75cc3e3f7a408cf8736b5e75.
Review provenance, tests, and examples before merging.