[EthanBlazkowicz]

Problem

Since the last alignment (command-code@1.53.1), npm has moved to 1.88.2, so every startup warns:

CC CLI version drift: protocol may have changed, re-align from the npm package {"implemented":"1.53.1","latest":"1.88.2"}

The repo's stated rule is to report the protocol version actually implemented and never silently bump the claimed version, so this can only be resolved by re-reading the npm package and verifying the wire surface - not by changing the number.

What changed

Re-verified every protocol surface this proxy emulates against command-code@1.88.2 (dist/cli.mjs, diffed against 1.53.1):

Unchanged - buildCommandAuthHeaders / buildCommandApiHeaders; /alpha/generate 9-key envelope and params; toWireMessages / toWireSystem / toWireTools / toWireThreadId / toWirePermissionMode; stream event vocabulary; device fingerprint (salt command-code:device-fingerprint:v1, hashSignal, thumbmark seed, components, collectorVersion: 1); lifecycle endpoint and cli_session_exists metadata; buildServerConfig; default max_tokens (64e3); User-Agent: cli.

New in 1.88.2, off the emulated path - x-cli-surface header (only sent in acp/rpc surfaces), /alpha/artifacts, expanded /alpha/sandbox/*, /provider/v1/systemone. The one new stream event, cache-write-tokens, is now in the silent lists so it does not log as unknown.

Mirrored the new observable request - the provider catalog refresh now matches createModelCatalogManager.fetchOnce: an anonymous bare fetch (no Authorization, no version/environment headers, no fabricated cli UA) that sends accept: application/json plus if-none-match: "<catalogVersion>" once a version is known, treats 304 as "reuse cache", and retries unconditionally if a 304 arrives with no cached catalog. Request URL is /provider/v1/models?view=client.

Version - CC_PROTOCOL_VERSION is now 1.88.2. Since the implemented dialect is the 1.88.2 dialect, the claim is truthful again and the drift warning clears. README.md / README_zh.md version references updated.

Resulting behavior

Startup logs CC CLI version in sync {"version":"1.88.2"} instead of the drift warning; generation/fingerprint/lifecycle requests keep the same header set, now with x-command-code-version: 1.88.2.

Scope

6 files, +116/-28: proxy.mjs (version constant, catalog refresh, silent lists), README.md, README_zh.md, and three test files. No client-facing API behavior changes.

Linked issues

None - the drift warning is only visible in the startup log; no issue tracks it.

Test commands and results

Windows 11, Node v26.13.0, head 1165b3d:

node --check proxy.mjs   # pass
npm test                 # 147/147 pass
git diff --check         # clean

Regression coverage

• Catalog request shape: path + view=client via URLSearchParams equality, accept, and absence of Authorization / x-command-code-version / fabricated cli UA.
• Conditional refresh: a second request (1 ms refresh window set through config.json) must carry if-none-match: "\"catalog-2026-10-30.1\""; a mocked 304 must keep serving the cached list without a fallback warning.
• Exact reported version 1.88.2 asserted in the envelope test.
• The unknown-event test feeds cache-write-tokens; verified it fails without the silent-list fix.

Adversarial review

Independent review agent (separate context; did not author the change). Round 1 reviewed eec8204, findings and handling:

• MAJOR: catalog request did not match 1.88.2. The real fetchOnce is an anonymous bare fetch with accept + quoted if-none-match, 304-aware. Fixed: fetchModels now mirrors that; tests assert it.
• MINOR: cache-write-tokens logged as unknown. Added to all five silent lists; covered by the no-warning test (fails without the fix).
• MINOR: coverage gaps. Exact version assertion, catalog header assertions, and 1.88.2 catalog fixture added.
• NIT: includes('view=client') accepts view=clients. Replaced with URLSearchParams equality.

Recheck of f33098f: VERDICT: APPROVE - all findings closed; four non-blocking follow-ups raised. Handling:

• Conditional/304 path untested - fixed: added the second-request test described above.
• Cacheless 304 falls through to the fallback warning - fixed: clears the cached version and retries unconditionally.
• Real CLI always sends if-none-match from its embedded catalogVersion - not adopted: this proxy has no embedded catalog to source a version from, and inventing one would be a fabricated value (worse fidelity than omitting it, per RFC 9110 conditional-request semantics). One-request-per-process difference only.
• PR2-only nits - handled in feat: log timestamps use plain local time #71.

Remaining limitations

• 1.88.2's new feature endpoints (/alpha/artifacts, /alpha/sandbox/*, /provider/v1/systemone) are not emulated - out of scope.
• x-cli-surface is deliberately not sent: the real CLI only sets it in acp/rpc modes, which this proxy does not emulate.
• The first catalog fetch per process is unconditional (no if-none-match), unlike the real CLI which always has an embedded version to send.

Checklist

• Branch is based on the latest canonical master (972828a, fetched and checked before push)
• Diff is focused; no secrets, local data, or unrelated changes
• Tests included and passing for the final revision
• README files updated where applicable
• Independent adversarial review recorded; findings resolved
• PR description matches the final implementation
• Screenshots - not applicable (no UI/dashboard change)
• Merge - maintainer decision

Base commit: 972828a; tested head: 1165b3d.