feat(dist): pure-Go releases, a cache preset, --idle-exit, and gateway conformance

[amiddavid]

Implements the proposal in #130, all three stages. Based on docs/local-distribution, so this PR's diff is the implementation only — the spec and its two verification scripts come from #130, which should merge first.

Four decisions were taken before writing anything, and all four are reviewable:

Open question in the spec	Decision
Default routing scope	project-local (.claude/settings.local.json), --global opt-in
--idle-exit default and floor	24h, floor max(2 × store.ttl_seconds, 1h) — enforced at startup
Homebrew tap	skipped. Tarball + checksum + go install; the tap repo and signing are still unowned
Scope	all three stages

Stage 1 — the toolchain gate

Our own docs were the largest one. quickstart-proxy.md, setup.md and hosted.md all told evaluators to install a C toolchain; setup.md additionally named bifrost's tokenizer as a cgo dependency, which it is not.

Re-verified directly on go 1.26.4 rather than taken from the spec: CGO_ENABLED=0 with default tags builds all four release targets (27.1–33.5 MB stripped), file reports "statically linked", ldd reports "not a dynamic executable", the binary starts and answers /healthz, and -tags cg_skeleton fails under CGO_ENABLED=0 with the build-constraints signature — confirming tree-sitter is the only C dependency.

• .goreleaser.yaml: plain GOOS/GOARCH matrix, no cross-toolchains. No brews: block, so nothing depends on a repo that does not exist.
• .github/workflows/release.yaml: a tag publishes; workflow_dispatch builds the same matrix as a snapshot and publishes nothing. Its first step asserts the pure-Go claim with CC=/nonexistent-c-compiler, so a cgo dependency escaping the build tag fails in CI rather than at a stranger's install.
• make build-static. The Makefile keeps CGO_ENABLED=1 because go test -race needs it — reading that as a shipping requirement is how the wrong claim reached the docs, and the comment now says so.
• cache preset = {cachesplit}. Not safe: format/textclean/searchfold are lossless in meaning but still rewrite the JSON, so "we do not touch your context" stops being literally checkable. Confirmed end to end — a released-shape binary logs pipeline=[cachesplit] under PRESET=cache.

Stage 2 — --idle-exit and the plugin

Off by default; a gateway or eval-containers deployment must never self-terminate. A signal and the watchdog converge on the same teardown, so the self-killing path cannot drift from the one known to work.

Two properties are load-bearing:

• The keep-alive inverts "idle." Pinging is what the proxy does precisely while no client traffic arrives — the quiet gap after end_turn, where 83.7% of the recoverable dollars sit. A request-only watchdog would kill the feature in its working window. So a pending ping both vetoes the exit and resets the clock: retiring the last ping buys a full fresh threshold rather than exiting moments later.
• Exit wipes the in-memory store. store.ValidateIdleExit refuses anything below max(2 × ttl, 1h) — ~5h34m at the default — at startup, not in a doc comment. 2× because the TTL is a sliding window. NewMemory now calls the same Options.EffectiveTTL the floor is computed from, so the two cannot drift.

The plugin (/plugin marketplace add rossoctl/context-guru → /context-guru:install) is three skills over three scripts plus a SessionStart hook. The hook self-gates on $ANTHROPIC_BASE_URL matching its own port: the plugin installs at user scope, so its hooks run in every project, and the env value settings already write into the process environment is the per-project enablement signal — no second copy of the port to drift, and it degrades correctly (remove the key by hand and the hook stops firing). It matches the port, not "localhost", so someone routing to litellm on 4000 is not hijacked. Synchronous (closes the race with the first request), idempotent (SessionStart also fires on clear/compact/resume/fork), and exit 0 on every path — a hook that fails here is a plugin that can brick every session on the machine.

settings.py merges exactly one key, backs the file up first, refuses to overwrite a base URL the user already set, removes only a URL it installed, and refuses to rewrite a settings file it cannot parse rather than replacing it.

Stage 3 — gateway conformance

All five items, under the cache preset. Four were already correct and are now pinned; one was missing:

1. SSE is not buffered — asserted against an upstream that withholds its second event until the client has seen the first.
2. Breakpoints are never added. The cap is 4, and a rejected cache_control makes Claude Code disable prompt caching for the rest of the conversation — so a budget mistake silently switches off what the funnel is selling.
3. The attribution block arrives byte-identical, so CLAUDE_CODE_ATTRIBUTION_HEADER=0 is not needed in the installer.
4. Error bodies forwarded byte-for-byte, status and headers included.
5. POST /anthropic/v1/messages/count_tokens — NEW. Absent it, Claude Code counts context by issuing inference requests: billed calls added by a proxy sold on removing them. Forwarded verbatim with no pipeline, because the client budgets its own transcript from the answer.

Verification

Every test was revert-verified, with each mutation asserted to have landed in the source before its result was allowed to count. 14 mutations, each failing with the intended message and passing when restored — full matrix in the commit body.

Doing that properly caught three defects in my own tests:

• One test hung instead of failing (a bare send on a channel the exited watcher no longer drains).
• Its tick channel was buffered, so a send proved nothing about the watcher having run — it seeded its clock after the test advanced it. Fixed in production too: main now stamps the clock at launch rather than relying on goroutine scheduling.
• The attribution test passed under two mutations because its fixture was built with json.Marshal of a map, which sorts keys — so re-encoding produced identical bytes. It now carries Claude Code's real key order ({"type":...,"text":...}), and both mutations fail.

The plugin's shell and Python helpers are tested from Go (context-guru-plugin/plugin_test.go) so go test ./... and CI cover them: settings merge/conflict/removal/backup, and the hook's silence in unrouted projects, idempotence, non-failure when the binary is missing, and its wait for /healthz.

go build ./..., go vet ./..., gofmt -l and the full go test ./... are clean.

Not verified, and one thing deliberately elsewhere

• The plugin has not been installed into a real Claude Code session end to end, because install.sh resolves a GitHub release and no tag has ever been published. Until one is, it reports no_release_found. Cutting a tag is the first thing to do after this merges.
• A stale preset table was found while adding the cache row, and is fixed in a sibling PR (fix/preset-doc-drift) rather than here, because it is unrelated to distribution: three presets were documented as running toon (retired after acting 0 times on 5,752 production requests) and every row omitted textclean/searchfold/linecap, while docs/reference/presets.md was correct at the same moment. This PR adds one row and leaves the rest of that table exactly as it is on main, so whichever PR merges second needs a trivial rebase there.

Still open for you

• Port 8787 (not 4000 — litellm). Configurable via the plugin's userConfig.
• skeleton omitted from releases, source build documented, per the spec's proposal.
• Artifact 27–34 MB; no -slim build, so the demo keeps the dashboard.

🤖 Generated with Claude Code

[OsherElhadad]

Reviewed against main e88f5d8: full diff, both build paths, the full test suite, mkdocs build --strict, hand-verification of the release config, settings.py exercised against copies in temp
dirs (the real ~/.claude/settings.json was never written to), and 11 real claude sessions
through the integrated build with main as control.

The headline claim holds, and the compaction core is sound. CGO_ENABLED=0 builds, the binary is
statically linked, and all 15 presets start and answer /healthz on the CGO-free binary — no
unknown component "skeleton". Invariant 5 (frozen byte-identical replay) held byte-exactly across 8
real turns; invariant 3 round-tripped byte-exactly. In-flight requests are not dropped at
shutdown (SIGTERM at t=2.5s of a real inference → client got HTTP 200 in 5.557995s, complete body,
port released). The .goreleaser.yaml seam most likely to be silently wrong is right: goreleaser
emits context-guru_{{.Version}}_{{.Os}}_{{.Arch}}.tar.gz and install.sh:66-67 reconstructs
exactly that. Workflow permissions are correct (top-level contents: read, job-level
contents: write, GITHUB_TOKEN, no PAT). The purego assert step genuinely fails when it should.

Almost everything below is in the plugin shell, not the core.

1. Blocking — /context-guru:uninstall kills the user's Claude Code session and leaves the proxy running

context-guru-plugin/skills/uninstall/SKILL.md:44-46:

pkill -f "context-guru-proxy.*${PORT}"

start-proxy.sh:67-69 passes the port through the LISTEN_ADDR environment variable, never on
the command line — so the port never appears in the proxy's cmdline and this pattern cannot match
it. The only process whose command line does contain the pattern is the shell running the pkill,
i.e. the Claude Code session's own Bash tool. pkill -f does not exclude its parent:

pid=1116481 cmdline='context-guru-proxy --idle-exit=24h '                      matches: False  <- the proxy
pid=1116473 cmdline='/bin/bash -c ... pkill -f "context-guru-proxy.*4160" ...' matches: True
listener pid=1116481 cmdline='context-guru-proxy --idle-exit=24h '   <- no port anywhere

A user runs uninstall because their sessions are broken. This kills the session mid-command (exit
143), reports nothing removed, and the proxy still holds the port. The skill's verification step then
prints STILL RUNNING, and the obvious next move — broadening the pattern to context-guru-proxy —
would match a host's long-running production service. The skill's own comment warns against the
broad pattern; the narrower guard it offers instead never matches anything.

Resolve the PID from the socket owner, which needs no pattern:

pid=$(ss -lntpH "sport = :${PORT}" | grep -o 'pid=[0-9]*' | cut -d= -f2 | head -1)
[ -n "$pid" ] && kill "$pid" || echo "(nothing listening on ${PORT})"

Or have start-proxy.sh write a pidfile. Either way delete the pkill -f — it is unfixable as a
pattern, because the pattern is in the command that runs it.

2. Blocking — install.sh cannot install anything today, and its documented fallback is not in the script

platform=linux/amd64   version=v0.1.0
curl: (22) The requested URL returned error: 404
result=error  reason=download_failed: .../v0.1.0/context-guru_0.1.0_linux_amd64.tar.gz
GitHub API: tag v0.1.0  draft: False  assets: (NONE)

Three separate problems: (a) the release tag resolves but has zero assets, so the script reaches
download_failed, which is not in install/SKILL.md's outcome table (it documents
present/installed/no_release_found/checksum_mismatch); (b) grep -n "go install" install.sh matches
only the header comment — the option-3 source fallback is documented but absent, on a box with Go
1.26.4 on PATH; (c) the raw curl: (22) on stdout breaks the script's own "every fact is key=value"
contract. The idempotent path also misreports, because there is no --version flag despite
buildinfo.Version being compiled in: result=present ... version=Usage of context-guru-proxy:
(install.sh:39 takes head -1 of --help).

Since this PR is the one-command-trial PR, the trial currently cannot complete.

3. Blocking — a dead proxy is a silent indefinite hang, and /context-guru:status cannot run in the session that needs it

env HOME=$TH CLAUDE_CONFIG_DIR=$TH/.claude timeout 100 claude -p 'say OK'
exit=124 (my timeout)   stdout: (empty)   stderr: (empty)

Nothing on either stream, indefinitely — this is the state after any crash, reboot or idle-exit.
(The "issue with the selected model" message appears only in the different case where the base URL
is missing the /anthropic prefix.) status/SKILL.md's "Set, nothing answering" branch has the
right diagnosis — but invoking a skill needs Claude to respond, which needs an API call, which is
the broken thing.

A UserPromptSubmit hook that probes /healthz and prints the diagnosis would reach the user with
no model turn. At minimum, install/SKILL.md's "requests in the routed scope fail" should say how
they fail (silent hang), because that is the only clue the user gets.

4. Blocking — the cache preset injects context_guru_expand, the model calls it, and under this preset the call can only fail

Five places promise otherwise: config/config.go:365, docs/reference/presets.md:15,
docs/how-to/choose-a-preset.md:52, docs/how-to/install-plugin.md:60, skills/install/SKILL.md:27.
Measured on the real gateway route (note: /compact does not run the injection path, which is
why this is easy to miss):

tools SENT by client    : ['Read', 'Bash']
tools FORWARDED upstream: ['Read', 'Bash', 'context_guru_expand']

Root cause is a code-vs-its-own-comment contradiction: proxy/proxy.go:85-87 documents the gate as
requiring the request to "carry an expandable marker"; expand/inject.go:86 says "No marker
condition, deliberately." The real conditions are mode ≠ never, store persists, tool_choice
absent, and hasTools — nothing about markers or whether the pipeline has any Offload at all.

And it is not merely cosmetic. In a real session with marker-shaped text in a file (realistic — this
repo's own docs contain literal <<cg:HASH>>), the model called it unprompted:

req 2  model_called=['context_guru_expand']
req 3  TOOL_RESULT: '[expand: original for id c6a2c7911fb10bc8 is no longer available]'
       expand_unresolved_missing=1

cache mints no markers, so 100% of expand calls under it must fail. Cost is one wasted round
trip and one step of the user's turn. The repair path handles it honestly (is_error cleared, named
id, counted) — the defect is that the path exists at all.

Bounded fairly: forwarded bytes are identical on repeat, so invariant 5 holds and there is no cache
regression; it is idempotent if the client already declares the tool; and the <<cg: reaching
upstream is inside the injected tool's own description, so "no <<cg:HASH>> markers in your
content" stays literally true. HIGH, not critical — but this preset exists specifically so a
stranger can verify one claim by reading one line, and
install-plugin.md:66 says "You can check that claim in one line of config/config.go." They will
get the wrong answer.

Gate InjectAuto on the pipeline containing at least one Offload — it is known at the call site.
TestCachePresetIsCachesplitAlone (config/config_more_test.go:239) passes throughout, because it
asserts the preset map and PresetPipeline("cache") while both injections happen in proxy.go after
apply returns. It needs a sibling that posts a body and diffs the forwarded tools.

(#137 adds a second unconditional injection, so on the merged tree cache forwards three tools —
including on off, the A/B control arm. Raised on that PR.)

5. Blocking — settings.py's backup destroys the user's undo, and uninstall does not restore what it replaced

The design is otherwise genuinely careful: atomic (temp + os.replace, never truncate-in-place),
idempotent (result=unchanged), preserves unknown keys and nesting, refuses malformed JSON
(result=error reason=unparseable_json, rc 3, file byte-identical afterwards), conflict → rc 2
rather than silent overwrite, env: {} cleaned up when the last key goes. Two defects undo that:

(a) The backup clobbers itself. stamp = strftime("%Y%m%d-%H%M%S") is one-second granularity and
shutil.copy2 overwrites. An install→uninstall round trip runs well inside one second:

add --force: backup=...settings.json.context-guru-backup-20260831-214032
remove     : backup=...settings.json.context-guru-backup-20260831-214032   # same path
ls: one backup file.  grep -c corp-gateway -> 0

The survivor holds the post-add state. install/SKILL.md:86 tells the user to report that path
as their undo.

(b) Uninstall does not restore the previous value. cmd_remove deletes the key. It records
replaced=<old value> at add time but never persists or reuses it, so after a --force install over
a user's own gateway, uninstall leaves them with no ANTHROPIC_BASE_URL at all:

FINAL env: {"ANTHROPIC_AUTH_TOKEN": "...", "ANTHROPIC_MODEL": "..."}   # corp-gateway gone

Combined with (a), the backup that held it is gone too. Microsecond stamps (or
os.open(dest, O_CREAT|O_EXCL)) fix (a); persisting and reusing replaced fixes (b).

6. Should be fixed — the atomic write widens the mode of a credential-bearing file

The temp file is created fresh, so os.replace takes the umask mode rather than the replaced file's:

before: 600   ->   after add (umask 022): 644     (file contains ANTHROPIC_AUTH_TOKEN)
backup: 600   (backup() uses copy2, which does preserve mode)

Umask 022 is the common default, so this is the normal case. shutil.copymode(path, tmp) before
os.replace, or an explicit chmod 0600.

7. Should be fixed — --idle-exit is defeated by any health probe, including the dashboard the skills tell you to open

Proven, not read. A 1h-threshold proxy:

21:55:10 idle-exit armed after=1h0m0s check_every=3m0s
23:58:10 shutting down reason="idle for 1h3m0s (--idle-exit 1h0m0s)"

2h03m of wall clock reporting 1h03m of idleness — the clock was last stamped an hour after launch, by
nothing but a /healthz poller that stopped then. stampActivity wraps h.Mux() wholesale
(main.go:578), so /healthz, /metrics, /stats and /dashboard/* all count as activity. A
Kubernetes liveness probe or a Prometheus scrape makes --idle-exit never fire, and
dash/ui/app.js:4798's setInterval(…, 30000) means a left-open dashboard tab prevents the exit
forever — while both skills tell the user to open it.

The author documents this deliberately (idleexit.go:39-47) and for the hosted case it is arguably
the right default. But it is accidental safety: nothing refuses --idle-exit when --upstreams is
set. A one-line guard beside the floor check would make the stated intent enforceable.

Related nit: the fatal floor refusal logs at INFO, after a context-guru-proxy listening line
(validation at main.go:570, log at :563), so it reads as a started proxy.

The floor itself is sound and I want to say so: at ≥2×TTL of idleness the provider's cache entry is
long dead, so an idle-exit destroys nothing billable. And the Store-loss worry does not
materialise — marker ids are content-hashed and Claude Code re-sends the original from its own
transcript, so the first post-restart turn re-mints the same id into an empty store. Verified: expand
worked after a kill-and-restart with a fresh store.

8. Should be fixed — scripts/gate-a-purego.sh is cited as proof in five places and is not in this PR

git ls-files finds no such file, yet it is named at docs/setup.md:12,
docs/get-started/quickstart-proxy.md:23, .goreleaser.yaml:5, Makefile:13 and install.sh:4 —
two of those are user-facing docs this PR edits. It is added by #130, so either declare that
dependency or cite the workflow's purego assert step, which does exist and works.

9. Should be fixed — nothing runs the test suite before a release publishes, and CI never tests the shipped configuration

A tag push builds and publishes without go test. Worse, ci.yaml:15 runs the suite only with
CGO_ENABLED: "1", so TestEveryPresetBuilds — which passes with CGO off and guards exactly the
artifact this PR ships — is never executed in the configuration being released. One line in the
assert step: CGO_ENABLED=0 go test ./config/ -run TestEveryPresetBuilds.

10. count_tokens — the behaviour is right, the consequence is undocumented

It returns a count of the original body; no pipeline runs (verified: the route is absent from the
requests counter and leaves cachesplit runs unchanged).

upstream gateway DIRECT      : {"input_tokens":115933}
through the proxy /anthropic : {"input_tokens":115933}    <- byte-identical
what the proxy actually forwards: tokens_before=115853 tokens_after=32802 saved=83051

Keep this. Returning the compacted count would be smaller, the client would believe it has more
room, and because fail-open can revert a component at any moment the next request could forward the
full body and 400. Over-reporting is the safe direction and the literal API answer.

But the cost is real and documented nowhere: Claude Code uses this to decide when to run its own
compaction, so a routed session self-compacts roughly 3.5× earlier than necessary, paying for a
summarization call and discarding transcript the proxy was handling for free. It also excludes the
tool declarations the proxy will add. Suggest exposing count_tokens_forwarded alongside so the
divergence is measurable, and one line in docs/reference/routes.md — where the route is currently
absent entirely.

Two smaller things on it: the hosted tenancy branch (:35-53) is coded correctly but wholly
untested — both conformance tests build h.Mux() with Tenants == nil, and Mux() has one caller
shared with hosted (main.go:576), so the multi-tenant service serves this route with zero coverage
on the branch standing between it and an unmetered open forwarder. Auth handling is correct and leaks
nothing (copyHeaders strips x-context-guru-* and Cookie; setUpstreamAuth deletes
Authorization/x-api-key/x-goog-api-key before injecting; the nil-key path forwards a caller's
own OAuth token untouched, so the "no API key needed" claim survives). Fail-open is appropriate — a
transport failure returns 502 with a fixed string rather than err.Error(), specifically so a
*url.Error cannot publish the upstream address.

Smaller items

• os.replace replaces a symlinked settings.json with a regular file. Verified: the symlink is
  gone and the dotfiles copy still holds the old content, so the edit never reached the user's repo.
  Dotfile-managed settings is a common setup; os.path.realpath before writing fixes it.
• start-proxy.sh:76 prints a dead link. It announces Dashboard: http://127.0.0.1:PORT/dashboard/
  but line 69 never passes --dashboard (curl -o /dev/null -w '%{http_code}' → 404).
  install-plugin.md:96 and status/SKILL.md:56 advertise the same URL. It is the first line the
  plugin ever prints and the only clickable thing in it.
• Backups accumulate forever — one per add and per remove, nothing prunes; 20 cycles leaves 40
  files in ~/.claude/.
• settings.py cannot recognise its own previous URL, so changing userConfig.port and
  re-running install reports a conflict against context-guru itself. Match
  http://(127.0.0.1|localhost|\[::1\]):\d+/anthropic$ as ours.
• --idle-exit is in no flag table — neither README's nor docs/reference/config.md's — and the
  startup validator that refuses values below 2 × store.ttl_seconds (20000s / 5h33m20s at defaults)
  is documented nowhere in the reference. install-plugin.md:88's "--idle-exit (default 24h)" is
  the plugin's value; the flag's default is 0 = never.
• The -34.1% justification is measured in the wrong regime for this preset. The A/B genuinely
  isolates cachesplit (cacheinject.md:185-211, placement contributes $0) — but :209 says "one
  task measured three times, not a fleet average", and dashboard.md:219 records that it "ran tasks
  back-to-back inside the TTL", so it is not a paired one-timeline measurement. This repo's own
  interactive figure is dashboard.md:204: $0.0298 across 1,127 sessions / 11,361 requests. The
  env snapshot is captured once per session, 1,105 of 1,127 first requests read zero from cache,
  cachesplit does nothing at all for an agent outside a git repo or under the 1,024-token
  minSplitTokens floor, and config/config.go:379-380 concedes it is a no-op on vLLM/llm-d. A
  first-run plugin user is definitionally the cold case. Suggested replacement for
  presets.md:15: "Best case ~$0.03 across 1,127 sessions of real interactive traffic, and zero if
  you are outside a git repo, on a short system prompt, or on a non-Anthropic backend. The −34.1%
  figure comes from benchmark harnesses running tasks back-to-back inside the cache TTL, which is not
  how an interactive session behaves." Also, both presets.md:15 and choose-a-preset.md:58 cite
  results/context-guru.md, which contains neither number.
• README now gives three answers for the default preset on one page. :120's "The default preset
  is cache" is correctly plugin-scoped, but :126 and :147 say codesmart and the binary
  actually ships house (main.go:46). Saying "the plugin installs with --preset cache" removes
  the ambiguity in your own diff; the two wrong claims are pre-existing and filed as docs: preset facts outside docdrift's scope are stale — wrong default preset in 5 places, stale README pipeline lists #145.
• .goreleaser.yaml floats its actions on tags (checkout@v4, setup-go@v5,
  goreleaser-action@v6) rather than SHAs. Repo-wide convention, so consistent rather than a
  regression — but this is the one workflow that publishes unsigned binaries users curl down, so it
  is where pinning would buy something.
• NIT counttokens.go:67 — strings.NewReader(string(body)) copies twice; bytes.NewReader(body).
• Real-world caveat, not this PR's fault: against the IBM LiteLLM gateway count_tokens answers
  {"input_tokens":13} for a body whose system prompt alone is ~7,929 tokens. Calling the gateway
  directly gives the same 13, so the undercount is upstream's — but the route's justification (cheap
  client-side budgeting) does not work on that upstream.

Please split this PR

It bundles five independent things: pure-Go releases, a new cache preset, --idle-exit, a Claude
Code plugin, and gateway conformance tests. The release plumbing and the conformance tests are
clean and could land today. The plugin has three blocking defects and is where all the risk is. As
one PR, the good parts are held hostage by the plugin shell. Suggested split: (1) goreleaser +
workflow + the CGO_ENABLED=0 go test gate; (2) conformance tests + count_tokens + its docs;
(3) the cache preset with the expand-injection gate and an honest presets.md:15; (4) --idle-exit
with the --upstreams guard and a flag-table row; (5) the plugin, after items 1, 2, 3 and 5 above.

Verdict

Needs changes, and worth splitting. The engineering underneath is good — the pure-Go claim is
real and verified across all 15 presets, graceful shutdown works, settings.py's conservative half is
well judged, and the release config's trickiest seam is correct. But as it stands a new user cannot
install it, and if they could, uninstalling would kill their session rather than the proxy.

[OsherElhadad]

Two additional findings that landed after my main review, both in install.sh, both HIGH. The first
is a security defect.

11. Blocking — the checksum verification is fail-open, so an unverified binary installs and runs

install.sh:78-93. A checksum mismatch is fatal, but an absent or unfetchable checksums.txt
emits one advisory line and falls through to tar xzf + install -m 755. Proven with a stubbed
curl that serves the tarball and 404s the checksum file:

checksum=unavailable
result=installed
rc=0
$ .../dest/context-guru-proxy   ->  THIS BINARY WAS NEVER CHECKSUM-VERIFIED

An unverified binary landed on a PATH directory and executed — and this binary then handles all of
the user's LLM traffic and holds their API key.

Three things make it worse than a missing check:

• The file's own comment at :76 says "a failure here is fatal, never a warning." The code
  contradicts it.
• install/SKILL.md:40-48 enumerates four outcomes for the skill to react to, and
  checksum=unavailable is not among them — so the skill reads result=installed and reports
  success to the user.
• There is no signature anywhere. (Acknowledged in the PR: signing ownership is an open question. But
  that is the argument for making the checksum path strict, not lenient.)

Fix: die in both else branches. An install that cannot verify should refuse, not warn.

12. Blocking — there is no upgrade path, on the PR that creates the release channel

install.sh:36-41 — any context-guru-proxy on PATH yields result=present, rc 0, regardless of
version. CONTEXT_GURU_VERSION is read after that early return, so nothing can force an
upgrade. And because there is no --version flag, the version it reports is garbage:

result=present
version=Usage of context-guru-proxy:

(install.sh:39 takes head -1 of --help; buildinfo.Version is compiled in and exposed at
/stats, so the data exists — the flag does not.)

For the PR whose purpose is a release channel, "installs once, never upgradable" is the gap that
matters most after finding 2. Add a --version flag, compare it against the resolved tag, and honour
CONTEXT_GURU_VERSION before the early return.

Addendum on the pkill finding (finding 1)

A second reviewer reached it independently and supplied the other half of the mechanism, which
strengthens the fix: the same SKILL.md uses the bracket trick correctly three lines later —
pgrep -af "context-guru-prox[y]" — so the self-match hazard was known to the author and missed in
the one place it bites.

That points at a cleaner fix than the socket lookup I suggested: pass --listen 127.0.0.1:$PORT as a
flag so the port lands in argv, and a bracketed pattern can then match it. Better still, there
is no /shutdown route — adding one would remove the need to pattern-match a process at all.

Two corrections to my own review, for the record

• I wrote that --idle-exit's interaction with a dashboard tab was a hazard. Sharpening it: the
  "proxy dies under a watching user" half is impossible — nothing can age out while the tab polls
  every 30s. What remains is only that the feature silently never fires while any tab or
  Prometheus scrape is alive, and logs idle-exit armed once and then nothing forever. MEDIUM, not
  HIGH.
• On the cache preset's savings visibility, worth adding because it affects how you'd verify a fix:
  on a run where cachesplit demonstrably worked (mutated: 2, verdict: moved), /stats still
  reported acted: 0, saved_tokens: 0, savings_pct: 0. acted is the wrong probe for a Reformat that
  relocates a breakpoint — the only positive signals are components.cachesplit.verdict and the
  billed-tier shift. install/SKILL.md:129 sends the evaluator to /context-guru:status "for the
  numbers", and the status skill does correctly lead with billed tiers — so it routes around the
  problem, but the metric and the docs disagree and that should be stated somewhere.

Also worth knowing for the "why does my first run show nothing" case: the plugin detects none of the
three zero-value conditions. Grepped context-guru-plugin/ for git rev-parse, vllm, llm-d,
minSplit, 1024 — no runtime check anywhere.

Zero-value condition	Detected	Documented
Non-Anthropic backend	no	yes (install-plugin.md:67, status/SKILL.md:71)
System prompt under the 1,024-token floor	no	no
Not a git repository	no	nowhere

Row 3 is the common case for a casual trial, and it reproduces live: non-git cwd →
cachesplit mutated=0 verdict=skipped; the same task inside a git repo → mutated=2 verdict=moved.
status/SKILL.md:65-73 lists four honest reasons the numbers may be flat and the one that actually
applies is not among them — so a first-run user outside a git repo is shown a zero and told the cache
warms on later turns. True in general, wrong there. A fifth bullet plus
git rev-parse --is-inside-work-tree in the status skill closes it.

[amiddavid]

Thank you — this was an unusually useful review, and three of the findings were things no test of mine would have caught. Split as you asked, into this PR (core) and #160 (the plugin): every blocking finding was in the plugin, so nothing clean is held behind it. I went with two rather than five because main.go carries both the idle-exit wiring and the --listen/--version flags, so a finer split could not be done by path without inventing artificial commits.

Where each finding went:

#	Finding	Where	Status
1	pkill kills the user's session	#160	fixed — pidfile + socket-owner fallback, --listen puts the port in argv (flag added here)
2	install.sh cannot install; go install fallback absent	#160	fixed, incl. download_failed as an outcome and --version (flag added here)
3	Dead proxy hangs silently; status unreachable	#160	fixed — UserPromptSubmit hook, since a skill needs the broken thing
4	cache injects context_guru_expand	here	fixed — gated on the pipeline containing an Offload
5	Backup clobbers itself; uninstall does not restore	#160	fixed — O_EXCL + µs stamps; replaced value recorded and restored
6	Mode widened on a credential file	#160	fixed, plus the symlink case
7	--idle-exit defeated by any probe	here	fixed — /healthz and /metrics no longer count; --upstreams now refuses --idle-exit outright
8	gate-a-purego.sh cited but not present	here	fixed — cites the workflow's assert step instead
9	No tests before publish; CI never tests CGO-off	here	fixed — CGO-off suite plus the full suite before publishing
10	count_tokens consequence undocumented; hosted branch untested	here	both fixed
11	Checksum verification fail-open	#160	fixed — refuses in every branch
12	No upgrade path	#160	fixed — CONTEXT_GURU_UPGRADE / CONTEXT_GURU_VERSION, and --version to compare against

I verified finding 4 before fixing it rather than taking it on faith, and got your result exactly: [Read Bash] in, [Read Bash context_guru_expand] out. Two things fell out of fixing it that are worth flagging:

• Ten existing expand tests changed fixture. They hand-seed the Store to simulate an offload but built their handler with pipeline: [] — a pipeline that cannot offload. Harmless while injection ignored the pipeline; now they use [linecap], which does not act on their short bodies. No assertion was weakened, but it is a real diff in tests you did not ask me to touch, so please look.
• I added the mirror-image mutation (HasOffload always false) to prove the gate did not trade one silent defect for another: an offloader whose output nothing can expand.

Two places I did not do what you suggested, both with reasons:

1. is_ours by URL shape. Your regex ((127.0.0.1|localhost|[::1]):\d+/anthropic) makes litellm's default — http://127.0.0.1:4000/anthropic — read as ours, which would let uninstall delete somebody else's routing; TestSettingsRemoveTakesOnlyOurKey failed the moment I tried it. add now records the URL it wrote and later runs read that record, which fixes the port-change case you identified without the claim.
2. The probe/viewer asymmetry. You sharpened this to "it silently never fires", and I agree, but I did not simply stop counting all non-chat routes: /healthz and /metrics no longer count, while the dashboard's polling still does. A probe is a machine asking whether the process is up; a tab is a person watching. Exiting under the latter is the worse failure. The --upstreams refusal is what makes the gateway case enforceable rather than accidentally safe — and it needed to be, precisely because I removed the accident.

On the −34.1% figure — you were right and it mattered. Both numbers are now stated with their regimes, along with the three zero cases; the old citation pointed at docs/results/context-guru.md, which contains neither figure. The "not a git repository" case is now checked at runtime by the status skill (#160), since that is the commonest first-run case and was documented nowhere.

Not fixed, deliberately: count_tokens still answers about the original body, for the reason you gave — over-reporting is recoverable, under-reporting costs a failed turn when a fail-open component reverts. The cost is now documented in docs/reference/routes.md, where the route was previously absent entirely. I did not add count_tokens_forwarded; happy to if you want the divergence measurable rather than merely stated.

Still unverified, and the thing I would not paper over: the plugin has never been installed into a real Claude Code session, because install.sh resolves a GitHub release and no tag has published assets. Cutting a tag after this merges is the gate for #160.

Also from your review: the stale preset tables are #142 (now guarded by a set-equality drift test), and the prose instances the guard cannot reach are #143.

[amiddavid]

Restructured per your ask: the pre-existing defects are now #161, and this PR keeps only distribution work.

#161 carries the expand-tool gate (including off, the A/B control arm, which was forwarding an extra tool declaration — so every measurement against that baseline compared arms differing by more than the pipeline), the missing count_tokens route, the C-toolchain claim our own docs got wrong in three files, and the preset facts from #143/#145 — including one neither I nor the subagent had spotted: the binary defaults to house and five documented sites said codesmart, two of which I had edited here without noticing.

It also adds a purego CI job, which is where that claim belongs: build-test runs exclusively with CGO_ENABLED=1 because the race detector needs it, so TestEveryPresetBuilds had never executed in the configuration a user would actually build.

Two things from doing the split that you should know, both mine:

• I clobbered fix(dash): report unpriced components in tokens, state the cache-frozen ceiling, and export the counters that only reached /stats #155 and a test caught me. Copying proxy/proxy.go wholesale from this older branch onto current main silently reverted its effPreset/notePreset work; TestCompactRowNamesThePresetThatRan failed with "the dashboard names a pipeline that did not run". Restored from main with my two edits re-applied on top — fix(dash): report unpriced components in tokens, state the cache-frozen ceiling, and export the counters that only reached /stats #155 is intact and verified.
• My own test premise about mcp was wrong. smartcrush implements components.Offload, so that pipeline does mint markers and does need the tool. The case now asserts the opposite with the reason recorded.

Also filed #162: TestConcurrentCallsDoNotRaceOnTheGateHistogram failed once in a full-suite run ("the race was never exercised"), then passed 8/8 in isolation, twice more in full suites here, and in a full suite on clean main. Unrelated to any of this, reported rather than left in a transcript.

#143 duplicates #145 and should be closed in its favour — I filed it without checking the tracker.

[amiddavid]

Second pass, over 69cb2be..92a04e5 (3 commits, 20 files). No Go toolchain in the review worktree, so nothing was executed — static read of every hunk plus proxy/keepalive.go, proxy/proxy.go, config/docdrift_test.go, Makefile, store/store.go.

None of the ten findings from the first pass resurfaced — f2b3d6e addresses all of them. But three of the five new findings are consequences of those fixes, so they are worth reading as follow-ups rather than as fresh territory: the envDuration fatal now catches --version/--help (the highest-severity item here), the trailing-slash hole in probeRoutes, and the floor being skipped entirely rather than reduced when the store is off.

Verified correct this pass: pendingPings reads stopped/pol/pings under k.mu, matching markStopped/record1, so no race; why has capacity 2 for exactly its two senders and stopWatch is closed only by the single consumer, so no double-close or blocked send; checkIdleExit still runs after --store/--config resolution, so cfg.Store is the same Options that reaches NewMemory (config.go:670); IdleExitFloor's > at the 1h boundary is value-equivalent; the cache preset survives TestPresetDocsDoNotDrift in both doc formats and the other range presets tests; and set -e does not abort the CI readiness loops.

[amiddavid]

This fatal fires before flag.Parse(), so it breaks --version and --help. Every call site is a default expression inside main's var (...) block, which Go evaluates before flag.Parse() and therefore before the new --version short-circuit at main.go:217. So IDLE_EXIT=86400 context-guru-proxy --version — precisely the unitless mistake this fatal was added to catch — exits 1 with a parse error instead of printing the version. That defeats the stated reason for adding the flag ("an installer asks a binary what it is, and it must be able to ask without starting a server or needing a config"), and the release workflow's own --version | grep -q context-guru-proxy gate fails the same way in a shell that exports a bad value.

The blast radius is wider than IDLE_EXIT: this helper also backs UPSTREAM_HEADER_TIMEOUT, DASHBOARD_RETENTION, ARCHIVE_CONTENT_AFTER, ARCHIVE_SESSION_AFTER and ARCHIVE_INTERVAL, so an existing deployment carrying a malformed value for any of those now refuses to start where it previously fell back to the default — and it dies before logging.Setup(), so the message never reaches CG_LOG_FILE.

Suggest making the parse lazy (validate after flag.Parse(), past the --version return) or scoping the fatal to IDLE_EXIT.

[amiddavid]

/healthz/ is not exempt, so a trailing-slash probe keeps the process alive forever. This is an exact r.URL.Path match, and http.ServeMux answers /healthz/ with a 301 to /healthz — which a Kubernetes httpGet probe (and most monitoring loops) treats as healthy. Since stampActivity stamps on entry, before the mux ever sees the request, a probe configured with a trailing slash refreshes the clock and --idle-exit never fires, silently, with idle-exit armed as the only log line. That is exactly the failure the comment above says was measured and fixed.

Same for any 404: a port scanner or a stray /health probe counts as use. Matching on the cleaned path, or on a small prefix set, would close both.

[amiddavid]

Skipping the floor when the store is off removed it entirely, and one consequence is a startup panic. With --store=false / STORE=false, ValidateIdleExit is never called, so no floor is enforced at all — not even the 1h term.

(a) idleCheckInterval (idleexit.go:175) now has no lower clamp, and its comment reasons that "checkIdleExit refuses any threshold below an hour, so threshold/20 is at least three minutes for every value that reaches here" — untrue on this path. STORE=false --idle-exit=10ns yields threshold/20 == 0, and time.NewTicker(0) panics, converting an intended startup refusal into a crash.

(b) README.md:150 and docs/reference/config.md:83 both state the floor unconditionally ("Refused at startup below max(2 × store.ttl_seconds, 1h)") with no mention of the store-off exemption, so the documented invariant does not hold.

Keeping the bare 1h term when the store is off — or at minimum clamping the interval to a positive value — plus a sentence in the two tables would fix both halves.

[amiddavid]

Missing -p 1. ci.yaml's purego job runs this identical package set and carries a comment explaining that omitting -p 1 on a 2-core runner provoked a real flake (TestCtlGetCampaignAggregatesPredictedAndRealPerTenant, #163) and that serialising "costs about a minute and removes the contention this job added". This workflow additionally runs go test ./... a few steps down, so the contention is at least as bad — a tag push can flake and block the publish for a cause already diagnosed and mitigated one file over.

[amiddavid]

Leftover from the edit: the old doc line above (// envDuration reads a Go duration environment variable (e.g. "72h").) was not removed, so the function now has two consecutive doc comments. Cosmetic, but it is a stale first line on a function whose semantics this PR changed, and some doc linters flag the duplicated identifier prefix.

[amiddavid]

Not filed as a defect, but the doc claim is slightly stronger than the code: pendingPings reproduces due() minus the timing term, but not due's companion gate — sweep also drops entries whose pingable() has gone false, and only once now >= startedAt + Idle. In that window pendingPings counts an entry that will never be pinged, which resets the activity clock and delays exit by up to one Idle. So "a live entry is by construction one we intend to ping" holds outside that window, not inside it. Bounded by the retire timer and immaterial at a 24h threshold.

[amiddavid]

Docs judgement call rather than a defect: this section correctly notes the savings land in usage limits, but not that routing subscription-authenticated Claude Code through the proxy means the proxy receives and (for keep-alive) retains the claude.ai OAuth credential, and that pings spend against those same limits. Worth a caveat given the section directly below is titled "Keep the API key out of Claude Code" — a reader can come away thinking the no-API-key path hands the proxy less.

[amiddavid]

All five plus both notes. Your framing is the part I want to acknowledge first: three of these are the first review's fixes' blast radius, and all three were mine. In each case the fix was right and the reach was not measured.

envDuration before flag.Parse — you were right about the severity

I added --version last round specifically so an installer could ask the binary what it is, then added a fatal that made IDLE_EXIT=86400 context-guru-proxy --version exit 1. The release workflow's own --version | grep gate would have failed the same way. And your point about logging.Setup() is the one I would have missed: it died before the log sink, so the message never reached CG_LOG_FILE.

Fixed by keeping the loudness and moving the moment rather than by scoping to IDLE_EXIT: envDuration records a bad value and returns the default; checkEnvDurations refuses after flag.Parse, past the --version return, once the sink exists, and before anything is opened. It reports all of them at once — the blast radius you listed (UPSTREAM_HEADER_TIMEOUT, DASHBOARD_RETENTION, the three ARCHIVE_*) is the argument for reporting them together, not for going back to silence.

/healthz/ — one character from re-breaking what I had just fixed

Taken, and taken the way you suggested rather than by normalising by hand: stampActivity now asks the mux which pattern matches. ServeMux.Handler reports the post-redirect pattern for internally-generated redirects, so /healthz/ resolves to /healthz, and the empty pattern for an unmatched path, so your second case — a 404, a port scanner, a stray /health — is closed by the same question. One matcher, the one that actually routes the request, instead of a second copy of the rules.

The floor exemption, both halves

You are right that skipping the check removed it entirely rather than reducing it, and the NewTicker(0) panic is the part that makes it more than tidiness: an intended startup refusal became a crash. Only the 2 × ttl_seconds term was ever about the store; the 1h minimum now always applies, so STORE=false --idle-exit=10ns is refused with a message that says which term does and does not apply. idleCheckInterval also cannot return a non-positive value now, whatever its caller does — worth having as a guard given that its previous comment reasoned "checkIdleExit refuses anything below an hour" and was then reached with 10ns through the path I had opened.

On (b): the README and docs/reference/config.md sentences are now true again without needing a caveat, because the floor is once more unconditional in the sense they state — the 1h minimum always holds, and the TTL term is what varies.

The rest

-p 1 added to release.yaml, with the reason pointed at ci.yaml's comment. Stale doc line gone.

pendingPings — narrowed to "outside that window", naming the sweep/pingable() gap you identified. I also recorded why erring toward counting is right regardless: over-counting delays an exit by minutes, under-counting kills the process during the quiet gap the keep-alive exists to work in.

use-with-claude-code.md — taken, and thank you for it; it is the most user-visible item here. The section now says the proxy receives the claude.ai OAuth credential on every request, retains it in memory for a tracked session when keep-alive is on, and that those pings spend the same usage limits — with the zeroisation and no-disk facts alongside, so it reads as a stated trade rather than a warning.

One thing I did that you did not ask for

My first attempt at this round failed on my own test from the previous round: TestCheckIdleExitSkipsTheFloorWithNoStore, whose name asserts the behaviour you just showed was wrong. I deleted it rather than editing it into shape, and folded its still-valid cases into the test named for the corrected behaviour. A test named for a defect is worse than no test — it argues for the defect on every future read.

Verification

exact-path probe match -> TestProbeExemptionSurvivesATrailingSlash FAIL on all five
   /healthz/, /metrics/, //healthz, /health (404), /nope (404) all counted as activity
floor skipped entirely -> TestCheckIdleExitKeepsTheOneHourMinimumWithNoStore FAIL
   accepted --idle-exit=10ns, 1ms and 30m with the store disabled
no panic guard         -> TestIdleCheckIntervalIsAlwaysPositive FAIL
   idleCheckInterval(0s) = 0s; time.NewTicker would panic

Finding 1 is verified by reading, not by test, and I would rather say so: asserting it needs a subprocess running the built binary with a bad env var and --version. The fix is a position — the refusal now sits after flag.Parse and after the --version return — which no unit test in this package can observe. Say the word if you want the subprocess harness; it is the one item here where "I read it carefully" is the whole of the evidence.

Full go test ./..., go vet, gofmt -l clean. #160 restacked on this.

[amiddavid]

Third pass, over 69cb2be..6590033. Read in full: cmd/context-guru-proxy/idleexit.go, cmd/context-guru-proxy/main.go, store/store.go, proxy/keepalive.go, config/config.go, .goreleaser.yaml, both workflows, the new tests and the docs. No go on PATH in the review worktree, so nothing was compiled — findings are from reading, cross-checked against net/http.ServeMux's actual matching rules and the surrounding call sites.

The two envDuration findings and the -p 1/floor items from the last pass are resolved. What is left is one live hole (the Bob-mode catch-all re-opens the trailing-slash gap the mux.Handler fix was written to close), two messages/comments that misstate their own mechanism, and two packaging/doc items.

Checked and found correct: checkIdleExit runs after the --store override folds into cfg.Store (main.go:244 → 256) and before any database is opened, so the "no WAL left behind" claim holds, and hosted mode is unreachable without --upstreams so the gateway refusal does cover it; the monotonic reasoning in activityClock is sound (CLOCK_MONOTONIC/mach_absolute_time both stop across suspend, so a lid-open does not read as idleness); idleCheckInterval cannot return <= 0 for any value checkIdleExit admits, and the guard is still correct defensively; why is buffered 2 for exactly two senders and stopWatch is closed exactly once (a second signal during shutdown being ignored is pre-existing, not a regression); PendingPings/pendingPings are nil-safe against a real *keeper field, take k.mu, and their documented divergence from sweep's pingable() gate errs toward not exiting; Options.EffectiveTTL is genuinely the single source since NewMemory calls it; the cache preset satisfies TestPresetDocsDoNotDrift in both tables (the regex skips the "Your workload" row because its first cell is not a backticked name), PresetNames() derives from the map so the settings page picks it up, and the gofmt de-alignment of "off": is correct; and the release workflow's health loop is set -e-safe with the trailing curl … | grep -q ok failing the step if the server never came up.

[amiddavid]

The remediation is backwards, and the derivation is false whenever the 1h term binds. The floor is max(2*ttl, 1h), so "raise store.ttl_seconds if the short lifetime is deliberate" tells the operator to do the one thing that raises the floor — they follow the advice and get the same refusal with a larger number. It should be to lower ttl_seconds, or raise --idle-exit.

Separately, the message unconditionally attributes the floor to 2x the store's %s entry lifetime: with store.ttl_seconds: 30 and --idle-exit=30m it prints floor of 1h0m0s (2x the store's 30s entry lifetime) — 2x30s is 1m, not 1h. The single number the operator has to act on is credited to arithmetic that does not produce it. Worth getting exactly right because this path is startup-fatal, so the message is the only evidence anyone gathers.

[amiddavid]

Bob mode has a / catch-all, so every unmatched path counts as activity and --idle-exit silently never fires. proxy.Mux() registers m.HandleFunc("/", h.passthrough(...)) whenever BobUpstream != "" || Tenants != nil (proxy/proxy.go:408), and --bob-upstream does not trigger checkIdleExit's gateway refusal — that only fires on upstreamsPath != "" — so --bob-upstream=… --idle-exit=24h is an accepted configuration.

In it, mux.Handler(r) returns pattern "/" for /healthz/, /health, /nope and every port-scan path. "/" is not in probeRoutes, so use is true and the clock is stamped. Concretely: a monitoring loop doing GET /healthz/ every 60s against a Bob-mode proxy holds the clock up forever, and the only log line is idle-exit armed at startup — exactly the silent failure lines 60-68 say was measured and fixed.

probeMux() (idleexit_test.go:448) registers no catch-all, so no test covers this shape.

[amiddavid]

The stated mechanism is wrong: ServeMux does not 301 /healthz/ to /healthz. cleanPath re-appends a trailing slash after path.Clean, and matchOrRedirect only ever adds a slash (/tree → /tree/), never strips one. With the default route table /healthz/ is a plain 404 with an empty pattern — so the exemption does hold, but through the 404 branch described below, not the redirect branch.

The same inaccuracy is in idleexit_test.go:461 and the "301 to /healthz" / "301 to /metrics" case labels at :470 and :472 — those rows pass for a different reason than they document.

Worth correcting because this comment is the justification for choosing mux.Handler(r) over a path compare, and because the redirect Go does generate (subtree root) returns an empty pattern from Handler — the opposite of "the pattern that will match after following it". Anything built on that claim for an added-slash redirect would be wrong.

[amiddavid]

No wrap_in_directory, so the documented untar command clobbers the user's files. archives[0].files puts LICENSE, README.md and THIRD-PARTY-NOTICES at the archive root (GoReleaser defaults wrap_in_directory to false), and both the release footer (:95) and docs/get-started/quickstart-proxy.md tell the evaluator to run tar xzf context-guru_*_darwin_arm64.tar.gz && install -m 755 context-guru-proxy ~/.local/bin/ — with no -C.

Run in a project directory, which is exactly where someone evaluating a proxy for their agent is standing, that silently overwrites their own README.md and LICENSE. Either set wrap_in_directory: true, or make the documented command extract into a temp dir.

[amiddavid]

Two lines below this, the table still documents only LISTEN_ADDR — the --listen flag this PR adds is missing from the row. docs/reference/config.md:81 was updated to --listen / LISTEN_ADDR; the README row was not, in the same table where these --idle-exit and --version rows landed. A README reader cannot discover the flag whose stated reason for existing is discoverability in ps.

[amiddavid]

All five. Two of them are corrections to things I wrote, one was a hole I left open, and one would have destroyed a user's files — so this round is mostly me being wrong rather than incomplete, and it is worth saying that plainly.

The Bob catch-all — you found the hole my own fix left

You are right, and the mechanism is worse than "one flag was missed": proxy.Mux mounts / whenever BobUpstream is set, so mux.Handler answers pattern "/" for everything. That defeats the entire mux.Handler approach I adopted last round, not just the probe list — /nope, /healthz/, every port-scan path becomes "a matched real route". And --bob-upstream never reached the gateway refusal, so the combination was accepted.

Fixed by construction: the refusal now covers --bob-upstream, and the message names whichever flag the operator actually passed. So a proxy with a catch-all cannot also have a watchdog. I added a catch-all exclusion in the stamp decision as well — not because it is reachable now, but because the two rules live in different files, and if they ever drift the asymmetric failure matters: over-counting / as "not use" errs toward exiting a laptop proxy, under-counting errs toward a gateway that never exits, which is the one nobody notices.

TestCheckIdleExitRefusesBobModeToo and TestCatchAllRouteIsNotActivity cover both, and the second registers the catch-all your note pointed out probeMux() was missing.

The ServeMux mechanism — I invented it

This is the finding I am most glad you wrote down. I claimed a 301 from /healthz/ to /healthz, and that Handler reports the post-redirect pattern. Both false: cleanPath re-appends the trailing slash, matchOrRedirect only ever adds one, and the subtree-root redirect Go does generate returns an empty pattern — the opposite. So the exemption works through the 404 branch, and my justification for choosing mux.Handler over a path compare was fiction that happened to sit next to correct behaviour.

Corrected in the comment and in the three test labels, which were passing for a reason they did not document. The comment now states what actually exempts each row and warns explicitly that nothing may assume a redirect resolves to its post-redirect pattern.

The refusal message

Both halves taken. It now branches on which term binds: when the store term does, it says "2x the store's %s entry lifetime" and offers LOWER ttl_seconds or raise --idle-exit; when the absolute term does, it says so, does not name ttl_seconds as a lever at all, and prints what the 2x-TTL floor would have been (1m0s for your ttl_seconds: 30 example) so the arithmetic is checkable rather than asserted. TestValidateIdleExitMessageNamesTheBindingTerm pins all of that, including that the string "raise store.ttl_seconds" is gone.

Your point about it being startup-fatal is the reason I went further than a wording fix: the message is the entire diagnostic surface for that path.

The archive

wrap_in_directory: true, and both documented commands updated to install -m 755 context-guru_*/context-guru-proxy. This was the most user-hostile item in the review — silently overwriting the README.md and LICENSE of the directory somebody is standing in, and that directory is their project by construction.

It has a consequence you did not have to tell me about, and I checked rather than assumed: #160's install.sh does [ -f "$TMP/$BIN" ], which a wrapped archive breaks with binary_not_in_tarball — at a stranger's first install, reading like a broken release rather than a moved file. Fixed there in a separate commit (find the binary rather than assume its path, so either layout works), and the plugin tests pass against it.

README

--listen row added. You are right that it was conspicuous: it went into docs/reference/config.md in the same pass that added --idle-exit and --version rows to the README table beside it.

---

go test ./... and gofmt -l clean; #160 restacked with its own fix. Findings 4 and 5 are packaging and documentation, verified by reading the rendered command and the table rather than by test — the archive layout itself is only provable by a real goreleaser run, which is still the one part of this PR that has never executed.

[OsherElhadad]

@copilot Review the code