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
+90
View File
@@ -1,6 +1,8 @@
import importlib.util
import io
import json
import os
from contextlib import redirect_stdout
from pathlib import Path
import subprocess
import tempfile
@@ -410,6 +412,94 @@ class SetupNativeTests(unittest.TestCase):
self.assertTrue(installer._valid_model(saved["profiles"][name]["model"]))
self.assertEqual(saved["profiles"]["opencode"]["executable"], "/usr/bin/opencode")
def _fake_pipelines(self, path, version, commit):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(f'#!/bin/sh\necho \'{{"version":"{version}","commit":"{commit}"}}\'\n')
path.chmod(0o755)
return path
def test_check_path_shadow_warns_naming_path_and_both_versions(self):
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "new-version", "bbbb")
shadow_dir = directory / "earlier"
shadow = self._fake_pipelines(shadow_dir / "pipelines", "old-version", "aaaa")
before = shadow.read_bytes()
installer = setup_native.Setup(directory, prefix=prefix, runner=subprocess.run,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", side_effect=lambda name: str(shadow) if name == "pipelines" else None):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(prefix)
warning = output.getvalue()
self.assertEqual(result, shadow.resolve())
self.assertIn("WARNING", warning)
self.assertIn(str(shadow), warning)
self.assertIn("old-version", warning)
self.assertIn("new-version", warning)
# The shadowing binary is only read; it is never modified or replaced.
self.assertEqual(shadow.read_bytes(), before)
self.assertEqual(installed.read_bytes().count(b"new-version"), 1)
def test_check_path_shadow_is_silent_when_prefix_binary_wins(self):
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "same-version", "cccc")
installer = setup_native.Setup(directory, prefix=prefix, runner=subprocess.run,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=str(installed)):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(prefix)
self.assertIsNone(result)
self.assertEqual(output.getvalue(), "")
def test_check_path_shadow_is_silent_without_a_path_binary(self):
with tempfile.TemporaryDirectory() as directory:
installer = setup_native.Setup(directory, prefix=Path(directory) / "prefix",
runner=subprocess.run, resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=None):
output = io.StringIO()
with redirect_stdout(output):
result = installer.check_path_shadow(Path(directory) / "prefix")
self.assertIsNone(result)
self.assertEqual(output.getvalue(), "")
def test_check_path_shadow_reads_each_binary_at_most_once(self):
class VersionRunner:
def __init__(self):
self.commands = []
def __call__(self, command, **kwargs):
command = list(command)
self.commands.append(command)
version = "old-version" if "earlier" in command[0] else "new-version"
return subprocess.CompletedProcess(command, 0,
stdout=f'{{"version":"{version}","commit":"ab"}}', stderr="")
with tempfile.TemporaryDirectory() as directory:
directory = Path(directory)
prefix = directory / "prefix"
installed = self._fake_pipelines(prefix / "bin/pipelines", "new-version", "bbbb")
shadow = self._fake_pipelines(directory / "earlier/pipelines", "old-version", "aaaa")
runner = VersionRunner()
installer = setup_native.Setup(directory, prefix=prefix, runner=runner,
resolver=resolution, environ={})
with patch.object(setup_native.shutil, "which", return_value=str(shadow)):
output = io.StringIO()
with redirect_stdout(output):
installer.check_path_shadow(prefix)
# A detected shadow costs exactly one bounded, read-only `version`
# read per binary (the shadow and the freshly installed CLI) so both
# versions can be named; no other subprocess runs.
self.assertEqual(len(runner.commands), 2)
self.assertTrue(all(command[1:] == ["version", "--json"] for command in runner.commands))
self.assertIn("old-version", output.getvalue())
self.assertIn("new-version", output.getvalue())
self.assertEqual(installed.read_bytes().count(b"new-version"), 1)
def test_full_run_migrates_docker_harness_config_to_host(self):
with tempfile.TemporaryDirectory() as directory:
recorder = Recorder()