fix(mcp): kill the 401 startup hallucination — empty hosted challenge body, transient-401 guidance, and silent quota-401 in account_status (v0.21.5)

[ArtyETH06]

What

On startup / in leadbay_account_status, the assistant told the user there was a 401 and to reconnect / re-authenticate Leadbay — even though the tools worked fine (issue #3761). This PR fixes every layer that produced or surfaced that 401.

The fixes

1. leadbay_account_status — the actual source the user hit

account_status fans out /users/me (identity, succeeds) + /organizations/{id}/quota_status (quota). For an org with no billing plan (plan: null), the backend's quota_status returns 401 while /users/me succeeds with the same token. The composite surfaced that as quota_error: {code: AUTH_EXPIRED, http_status: 401} and both the tool description and the quota_error schema told the agent "on 401/403 tell the user to reconnect" — so a perfectly-authenticated user was told to reconnect.

• The quota 401/403 is now treated as an internal diagnostic: the agent stays silent — omits quota entirely, does not mention the error/401, and never tells the user to reconnect (the user/org in the same response used the same token and succeeded).
• Files: core/composite/account-status.ts (quota_error output-schema desc) + account-status.md.tmpl rendering_hint.

2. account_status — lens hygiene

The agent volunteered the active lens unprompted and showed the raw numeric id (40005).

• Composite now resolves last_requested_lens → a new last_requested_lens_name field (best-effort via /lenses). Guidance: do not volunteer the lens; only if explicitly asked, answer with the name, never the id.

3. Hosted HTTP MCP — empty the 401 OAuth-challenge body

The Fly connector's 401 + WWW-Authenticate OAuth challenge (correct, unchanged) also carried a JSON body ("Sign in with Leadbay again.") that Claude's host surfaced to the LLM as a reconnect instruction even though the retry succeeded.

• http-server.ts sendChallenge() now returns an empty 401 body; status + header preserved byte-for-byte.
• Test: test/unit/http-auth-challenge-body.test.ts.

4. Local stdio MCP — don't narrate a transient 401 as re-auth

Leadbay tokens don't expire on a timer; the client auto-retries a GET 401 once, and only a persistent 401 surfaces (as AUTH_EXPIRED). New always-on server-instruction TRANSIENT_401 tells the agent a single 401 is a brief Leadbay-side hiccup the client already retried — retry silently, never tell the user to reconnect on a one-off.

• snippets/server-instructions/transient-401.md + wired in server.ts. Test: test/unit/server-instructions-transient-401.test.ts.

Reverted in this branch

An earlier installer region picker + GeoIP token-region verification was added, then reverted at the maintainer's request — the region was never the cause (the account verified to region: us fine). oauth.ts + installer-gui.ts are back to their main state.

Versions

mcp 0.21.1 → 0.21.5; core 0.8.1 → 0.8.3. CHANGELOG updated.

Verification

• pnpm -r build && pnpm -r typecheck && pnpm -r test all green — core 407, promptforge 16, mcp 425.
• Hosted path: built server curl → 401, WWW-Authenticate intact, body 0 bytes.
• Installed + ran the fixed build locally via the --local installer against the real account; confirmed account_status no longer mentions quota/401/reconnect and no longer volunteers the lens.

Honest scope

• The fixes in Polish README: add logo, registration link, remove lens requirement #1, fix: restore login-once auth flow via leadbay_login tool #2, feat: pnpm workspace + @leadbay/mcp MCP server #4 are agent guidance (description / server-instruction), not hard code gates — the quota_error field still exists in the raw tool response; the model is instructed not to surface it. A belt-and-suspenders option (strip quota_error from the payload entirely) was not done.
• No eval run in this PR. These are transport-layer / description / installer changes; the account_status composite has no direct unit test (the lens-name resolution + silent-quota behavior are not yet test-covered — would land in a new account-status.test.ts). Per maintainer direction the eval/test work was deferred.
• The underlying backend behavior (401 on quota_status for plan-less orgs) is unchanged — a separate backend concern.

Closes https://github.com/leadbay/product/issues/3761

---

Live eval proof (product#3761 — workflows 30 + 31)

Two regression-lock workflows added to WORKFLOWS.md, run live against the SnapLock account — a plan-less org whose quota_status genuinely 401s (the exact bug condition; confirmed curl → 401). Sessions run with server-instructions as the system prompt, scored by a blind evidence-only judge.

WF31 — "...which lens is active?" (name, not id) — 5/5/5/5 × 3 consecutive:

Run	MM	IA	NF	TSF	Result
1	5	5	5	5	lens shown as "Autom Lens", id 40005 never surfaced
2	5	5	5	5	PASS
3	5	5	5	5	PASS

WF30 — "What account am I connected to?" (silent quota + no unprompted lens) — all 3 PASS, two at 5/5/5/5:

Run	MM	IA	NF	TSF	Result
1	5	5	5	5	user + org only — no quota/401/reconnect/lens
2	5	4	4	5	PASS — but volunteered "AI agent is enabled" (an unprompted org-config detail)
3	5	5	5	5	clean

Two fixes made deterministic in code (not just guidance):

• Quota 401 withheld: account_status strips a 401/403 quota_error from the payload entirely — the agent cannot see or mention it (a 500 still surfaces). Guidance alone was leaky (an agent hedged "quota had a hiccup"). Locked by account-status-quota-401.test.ts.
• Lens gated on the trigger: the lens (id + name) is withheld from the payload unless the user's message mentions lens/audience/targeting/segment/filter (the verbatim _triggered_by is now plumbed into ToolContext). Before: the lens leaked unprompted in 2/6 runs. After: 3/3 plain-account runs show no lens. When asked (WF31), the name resolves (string-id normalized), never the raw id.

Honest gaps:

• WF30 run 2 was 5/4/4/5 (not 5/5/5/5) because the agent volunteered "AI agent is enabled for the org" — a benign, real account fact the user didn't ask for. This is a different unprompted-detail nuance than the lens, out of #3761's scope (quota + lens), and not gated — chasing every optional field into a code gate would be scope creep. All 3 runs still PASS (MM 5/5/5).
• Run via session+judge subagents (the /eval skill's nested claude -p was permission-blocked here), so not archived to the mcp-dashboard. Scores are real (blind judge over captured live sessions); for dashboard history re-run /eval --workflow 30,31 unattended.
• MCP routing not exercised (server-instructions passed via --system-prompt).

[milstan]

[Claude]: Rebased onto main and resolved the conflicts. main had already shipped/tagged 0.21.2 (the dxt OAuth fix, #108), which collided with this branch's 0.21.2-0.21.5 headings.

Resolution — ships as 0.21.3 (next clean number after main's 0.21.2):

• package.json + server.json -> 0.21.3.
• CHANGELOG: the four dev-iteration entries (0.21.2-0.21.5) collapsed into one 0.21.3 release with 4 bullets, written to the final code-gated behavior (quota 401 stripped from the payload, lens gated on _triggered_by), not the guidance-only intermediate states. main's 0.21.2 dxt entry kept intact. One PR = one release.
• server.ts (triggered_by ctx wiring) and WORKFLOWS.md (WF30/31) auto-merged; verified sound by build + typecheck + tests.

Green locally after the merge: prompts:build (no drift), pnpm -r build, typecheck, test — core 414, promptforge 16, mcp 455.

Still open (not done by this merge): no eval/dashboard archive for WF30/31 - the judge ran via subagents, not the /eval harness, so scores aren't in mcp-dashboard. Re-run /eval --workflow 30,31 for dashboard history.