Report a stale client and refuse an unreadable newer server

Exchange a build/protocol identity so an older CLI can no longer talk to a
newer native server silently:

- protocol carries ProtocolVersion and every server frame (including the
  unsolicited welcome) is stamped with the server build and protocol, so a
  client that never pings still learns the server identity.
- buildinfo.Compare classifies the relationship as InSync/Warn/Refuse and
  names both builds; the client Watch reports one warning per connection and
  returns a hard error when the server speaks a newer, uninterpretable
  protocol so the caller never acts on the frame.
- client.ReceiveNotice decodes the raw frame so an unmodeled top-level field
  produces a one-time "unrecognized field(s)" notice instead of being dropped
  silently (the case that hid the artifacts field).
- CLI routes warnings to stderr, keeps machine JSON stdout clean and fails
  non-zero on a refused mismatch; ping/connection print the client/server
  relationship. The TUI surfaces the same notices through the shared log.
- scripts/setup-native.py now warns when an older `pipelines` earlier on PATH
  shadows prefix/bin/pipelines, naming both paths and versions, without
  installing or modifying anything else.
- Docs, the packaged debugging skill reference and README no longer imply the
  installed CLI always matches the server.

Tests cover the comparison table, unknown-field detection and caching, the
server identity stamping on pong and welcome, the CLI/TUI reporting paths and
the installer PATH shadowing warning.
This commit is contained in:
2026-10-16 18:37:01 +01:00
parent 98bbc2deac
commit 8c1eea53a9
25 changed files with 1239 additions and 81 deletions
+56
View File
@@ -203,6 +203,61 @@ class Setup:
if result.returncode:
raise ValueError(f"go build failed for ./cmd/{command}; the native install is incomplete")
# --- stale-CLI-on-PATH guard -----------------------------------------
def check_path_shadow(self, prefix):
"""Warn when a different ``pipelines`` earlier on PATH shadows this install.
Detection is read-only and bounded: one ``shutil.which`` check plus one
bounded ``version --json`` read per binary. The installer never modifies,
moves, deletes or upgrades the other binary; it only names the shadowing
path and both versions so an older CLI is not used silently in front of
the freshly built server. Naming both versions requires reading each
binary once, so a detected shadow costs exactly two short, read-only
subprocesses (none when the prefix binary is the one PATH already
resolves). Returns the shadowing path, or None when the prefix binary is
the one PATH resolves.
"""
installed = prefix / "bin/pipelines"
found = shutil.which("pipelines")
if not found:
return None
found_path = Path(found).resolve()
try:
if found_path == installed.resolve():
return None
except OSError:
pass
other = self._binary_version(found_path)
current = self._binary_version(installed)
print(
f"WARNING: a different pipelines resolves earlier on PATH than the freshly "
f"installed CLI: {found_path} (version {other}) shadows {installed} "
f"(version {current}); the installer left it untouched. Put {prefix / 'bin'} "
"first on PATH so the CLI matches the running server.")
return found_path
def _binary_version(self, path):
"""Read a binary's ``version --json`` once; never a hot path."""
if not Path(path).is_file():
return "unknown"
try:
result = self.runner([str(path), "version", "--json"], capture_output=True, text=True)
except OSError:
return "unknown"
if result.returncode:
return "unknown"
text = (result.stdout or "").strip()
try:
data = json.loads(text)
except ValueError:
return text or "unknown"
if not isinstance(data, dict):
return "unknown"
version = data.get("version") or "unknown"
commit = data.get("commit")
return f"{version} (commit {commit})" if commit else str(version)
def install_skill(self, prefix):
result = self.runner([str(prefix / "bin/pipelines"), "skill", "install"], cwd=str(self.directory))
if result.returncode:
@@ -453,6 +508,7 @@ class Setup:
else:
resolution = self.resolve_ntfy()
self.build(prefix)
self.check_path_shadow(prefix)
self.install_skill(prefix)
# The native install launches host harnesses, so write host profiles for
# the detected harnesses and clear any Docker-era link. Uses only the