design dsh client version gate

Design: dsh client version gate (issue #46)

Status: SHIPPED (branch feat/46-dsh-0.2, 2026-10-13). User directive (verbatim intent): dsh 本身迭代很快，我们不做兼容，只按最新的来；在合适的地方 对 Agent 客户端版本做限制，不在兼容范围内不连接，提示升级。 Context: design-phase-9-w7-native-sessions.md § #46 addendum (the v4 session-log switch this gate rides with), design-phase-9-w7.1-dsh-event- tap.md § #46 addendum (tap v2).

Problem

dsh's integration surfaces (session-log format, streaming buses, ACP dialect) move with the client, and #46 chose NO back-compat: the daemon reads one ground-truth version line (0.2.0-rc.2). Without a gate, an out-of-range client meets the integration as silent misbehavior — an empty session rail, dropped history, no token stream, or garbage tool output — with nothing telling the user their client is simply too old.

Decision

Refuse to CONNECT below a per-target floor, with an actionable upgrade hint. The floor lives on the ACP adapter table (one place; targets that iterate slowly carry none and are unaffected):

• adapters.ts — AcpAdapterSpec.minVersion (deepseek: '0.2.0-rc.2').
• acpMinVersion(target, env) — the floor to enforce, or null: no floor, or an HN_ACP_COMMAND_<TARGET> override owns the command line. An operator-pinned install is managed by hand and the daemon must not gate it (this also keeps test fixtures riding the override ungated — a fixture is not a dsh).

Check (acp/version-gate.ts): checkAcpVersion(target, env) probes <bin> --version through the W1 runtime probe (probeRuntime, 4s bound, pathEnv from the caller's env) and compares with shared's compareVersions (prerelease-aware: 0.2.0-rc.1 < 0.2.0-rc.2 ≤ 0.2.1-alpha.1 ≤ 0.2.0 non-prerelease). The first whitespace-separated token is parsed. Absent or unparseable versions never block — the spawn itself then fails with its own, more specific error; the gate only rules on versions it can actually read. Refusal message: dsh <v> is not supported (minimum <min>) — upgrade with: npm install -g @deepseek-ai/dsh@latest (HARNESS_PACKAGES supplies the package name).

Wiring (chat.ts):

• Channel open (chat:session.start): the gate runs BEFORE any spawn — right after the adapter command resolves, before prewarm consumption. A refusal answers chat:session.ready {error: message} (the same channel the spawn failures use), so the web session page shows the upgrade hint as the open error. No adapter process is ever spawned, no ledger entry written.
• Prewarm pool: spawn gates too — an out-of-range client is never warmed (the pool is a cache: a miss is silent; the channel open surfaces the message).
• Injectable ChatHandlersOptions.versionGate for tests (the default is the real check).

Non-goals

• Not a semver range engine: one floor per target, compared with the existing compareVersions. A ceiling is deliberately absent — newer dsh is expected to work until proven otherwise; if a release breaks the integration, the floor bumps and the gate carries the upgrade hint.
• Not applied to targets without a floor (claude-code/codex/opencode/ hermes/pi today). Adding one later is a table row + tests.
• Not an inventory-side warning (yet): the gate speaks at the point of failure, where the user is. The harness job's own hints (dshNodeWarning) keep their separate role.

Verification

• test/version-gate.test.ts (7 cases): floor declaration + override skip; prerelease-aware refusals across the 0.1.x/0.2.0-rc.1 line and passes from 0.2.0-rc.2 up; decorated version strings; absent/unparseable pass-through; no probe for override/ungated targets.
• test/chat.test.ts (#46 describe): an out-of-range client is refused at open AND never pre-warmed (injected gate + zero ledger entries), and the DEFAULT gate refuses a real (fake) old dsh on PATH end-to-end with the upgrade hint in the ready error.
• Repo typecheck + all four package suites green; pnpm format.