fix: address 10 confirmed review findings from the 0.6.17-0.6.20 range

[jeffyaw]

Implements all 10 confirmed findings from an adversarially-verified review of the f7b7cb3..a736200 range (the 0.6.17-0.6.20 release-flow and tooling work). Each finding was independently confirmed against the code before being fixed.

release.sh

1. Tag-drift guard dies silently on git ls-remote failure -- under set -euo pipefail, a network/auth failure inside the command substitution killed the script with only the generic ERR-trap line, git's actual error discarded by 2>/dev/null. Now: stderr passes through and an explicit || fail names the cause.
2. Non-tty runs released unconditionally -- the tty-gate's else-branch proceeded without confirmation, so echo n | ./release.sh X.Y.Z (which used to abort) ran a full npm publish + tag push. Now: non-interactive runs require RELEASE_YES=1 or a piped y; a piped decline (or no reply within 5s) aborts. Behavioral change: agent-driven release invocations must set RELEASE_YES=1.
3. SKIP_LINT comment claimed "CI catches lint regressions anyway" -- false since release.yml was dropped; with SKIP_LINT=1 lint runs nowhere. Comment corrected + a loud upfront warning when the hatch is active.
4. warn() wrote to stdout -- the pre-commit path's npm run lint:fix >/dev/null swallowed the SKIP_LINT noop notice, making the skipped formatting gate invisible. warn() now writes to stderr.
5. gh-token fallback misattributed login failures -- an operator who never set MCP_REGISTRY_TOKEN was told to check its scopes, with mcp-publisher's own diagnostic suppressed. Now: the token source is tracked, the gh-cli path suggests gh auth refresh -h github.com -s read:org, and the publisher's stderr passes through.

src

6. api.ts getPool() doc claimed an operator can flip ALLOW_WRITES between tool calls without a restart -- impossible for a stdio server whose env is fixed at spawn. Reworded to the real rationale (in-process callers/tests; keeps the flag out of the pool snapshot).
7. api.ts typeNameCache concurrency comment described an impossible interleaving (double bootstrap-SELECT, last-writer-wins). The null-check and assignment are synchronous; the real race is a duplicate targeted miss-fill merging into the shared map. Comment now says so.
8. explain.ts error-message regression -- the over-qualified guard ran before the double-quote check, so public."odd.name" lost the actionable "pass plain identifier names without pre-quoting" message. The raw string is now checked for " before the dot-split (per-piece quote check folded into it); the test assertion that had been loosened to tolerate the regression is re-tightened.

tests

9. tools.test.ts always-true assertion -- the "round-trips declared keys" loop could never fail once safeParse succeeded (Zod echoes supplied declared keys), and the comment claimed a schema/handler-drift guard the test never performed. Loop dropped, comment rewritten to what the test actually guards.

changelog

10. Published versions 0.6.17-0.6.19 had no CHANGELOG sections (the file jumped 0.6.20 -> 0.6.16). Backfilled from the commit history.

Checks: biome check clean, tsc --noEmit clean, 214/214 unit tests pass.

🤖 Generated with Claude Code

[HighviewOne]

Reviewed all 10 findings. Each fix is correct; notes below.

release.sh

Finding 1 — ls-remote error suppression: Removing 2>/dev/null and adding || fail is the right call. One thing worth confirming: set -euo pipefail is active (line 17), so a failing git ls-remote | awk pipeline propagates non-zero through the $() substitution and triggers the || fail guard. Verified — this works as intended.

Finding 2 — Non-tty unconditional release: The IFS= read -r -t 5 -n 1 REPLY || true approach is correct. echo y | ./release.sh reads y, passes; echo n | ./release.sh reads n, fails; an empty pipe times out in 5s, REPLY stays "", fails. RELEASE_YES=1 check in the elif branch covers agent-driven invocations cleanly.

Finding 3 — SKIP_LINT comment: Corrected and the upfront warn() on activation is a nice addition — flags the gap before lint would have run, not silently after.

Finding 4 — warn() to stderr: Straightforward and correct.

Finding 5 — gh-token fallback: Tracking TOKEN_SOURCE and threading mcp-publisher's stderr through gives actionable errors instead of hiding the real failure. The gh auth refresh -h github.com -s read:org hint is exactly what an operator would need.

src/api.ts

Finding 6 — getPool() doc: The old comment was actively wrong — a stdio server's env is fixed at spawn. New wording is accurate.

Finding 7 — typeNameCache concurrency comment: Verified against the code: typeNameCache = new Map() (line 169) is synchronous and runs before the await client.query(...) bootstrap, so a second concurrent caller sees a non-null map and correctly goes to targeted miss-fills, not a duplicate full bootstrap. New comment matches the actual behavior.

src/tools/explain.ts

Finding 8 — double-quote check order: This is a genuine regression fix. public."odd.name" splits into 3 pieces on ., hitting the over-qualified branch first — the caller gets no hint that removing quotes is the fix. Moving the raw-string " check above the split restores the actionable message. Test assertion tightened to match: /double-quote|pre-quoting/i (over-qualified removed). Correct.

src/tools/tools.test.ts

Finding 9 — always-true loop: The observation is exactly right. z.object().safeParse() always echoes declared fields in the output when it succeeds — name in result.data can never be false after a successful parse. The loop was dead code. Test title update is accurate.

CHANGELOG.md

Finding 10 — backfilled 0.6.17–0.6.19: Clean, matches the commit history.

---

LGTM. All 10 fixes are correct. No blocking issues.