fix+release(v0.4.1): D74 post-Phase-4 hotfix batch — 5 maintainer-review findings (#46)

* fix+release(v0.4.1): D74 post-Phase-4 hotfix batch — maintainer-review findings

Patch release fixing 5 issues caught by maintainer post-v0.4.0 independent
review (main / v0.4.0 / commit ee4d945). All five are real runtime bugs
the per-D-day fresh-context opus reviewers missed because they checked
spec text instead of runtime contracts (default auth.allow_anonymous:
false, real /health payload shape, real /cache/stats payload shape, real
/v0/management/dashboard-data payload shape).

Phase 4 process learning: every implementation D-day MUST include at
least one test that boots the server with default production config and
exercises the new feature end-to-end. D74 Suite 36 pins the wire-
contract shapes so a future D-day refactor can't silently re-break the
CLI / plugin / docs.

## P1-1 — olp doctor false-negative on auth-required /health

lib/doctor.mjs: buildBuiltinChecks() accepts opts.authHeaders and passes
to httpGet for both server.running + server.version probes. The
server.running check now distinguishes 401/403 ("server up, bearer token
missing or invalid — set OLP_API_KEY") from "server unreachable" so the
kind discriminator routes to a clean fix-auth path instead of fix_server
when operator just forgot to export the env var.

bin/olp.mjs cmdDoctor: threads authHeaders() through to runDoctor.

## P1-2 — olp-connect token validation + shell-quoting

bin/olp-connect: validate_olp_token() enforces ^olp_[A-Za-z0-9_-]{43}$
(per ADR 0007 § 3 token format) at THREE input sites: --key arg,
/health.anonymousKey server-advertised consumption, interactive prompt
fallback. shell_quote() POSIX-single-quote-wraps with embedded-quote
escape per:
  foo'bar  →  'foo'\''bar'
Applied to all rc-file writes + dry-run output. systemd
environment.d/olp.conf write additionally rejects embedded newlines.
Hostile or malformed keys can no longer persist as shell startup
injection.

## P2-3 — olp usage + olp cache human formatter wire-contract fix

bin/olp.mjs cmdUsage previously read body.usage_24h.requests /
body.providers / body.top_fallback_chains — none of which exist in the
real server payload (server.mjs:2027 + lib/audit-query.mjs). Users saw
"requests: ?" + missing per-provider quota + missing top-chains. Now
reads body.window_24h.request_count / body.cache_hit_24h.hit_rate /
body.quota / body.top_fallback_chains_24h.

bin/olp.mjs cmdCache previously read body.entries / body.bytes /
body.maxBytes (OCP-era field names). Real CacheStore.stats() returns
{hits, misses, size, inflightCount}. Now reads body.size /
body.inflightCount + computes hit rate from hits/(hits+misses).

## P2-4 — olp-plugin/ fmtHealth iterates providers.status

olp-plugin/index.js: previously walked Object.entries(body.providers)
which surfaced `enabled` / `available` / `status` as pseudo-providers
(chat showed "🟢 status" instead of "🟢 anthropic"). Now extracts the
real provider map from body.providers.status, renders enabled/available
counts in a header line, lists per-provider names with activeSpawns when
present. Falls back to flat body.providers.* for older OCP shape
(backwards compat).

## P3-5 — stale v0.3.0-era doc strings updated

README.md: header status line + Implementation Status § now reflect
v0.4.0 shipped + Phase 5 open. Known-limitations Phase 3 line moved out
of "pending v0.3.0" state; new Phase 4 line added with full deliverable
list.

server.mjs: startup banner no longer hardcodes "Phase 1 in progress"
(now just lists version + provider count). Banner derives state from
VERSION so future Phase boundaries don't need touch-ups here.

## Test count

696 (v0.4.0) → 704 (v0.4.1). +8 D74 regression tests in Suite 36:

- 36a: runDoctor accepts authHeaders + threads to checks
- 36b: server.running distinguishes 401 (auth) from "server down"
- 36c: olp-connect rejects malformed --key (validator fires before rc write)
- 36d: olp-connect accepts properly-formed olp_ token
- 36e: CacheStore.stats() shape pin + cmdCache source pin
- 36f: dashboard-data payload shape pin + cmdUsage source pin
- 36g: olp-plugin fmtHealth iterates providers.status not providers.*
- 36h: server.mjs banner doesn't hardcode stale phase

## Authority

- Maintainer independent review of main / v0.4.0 / commit ee4d945
  (2026-05-26 session — 5 findings P1×2 + P2×2 + P3×1)
- Iron Rule 第二律 (evidence over "should work") — runtime smoke
  against default production config now mandatory per Suite 36 pattern
- CLAUDE.md release_kit.phase_rolling_mode cross-Phase discipline
  ("hotfix to a shipped Phase N deliverable → bump patch, tag, release
  before next push")
- ADR 0007 § 3 (token format ^olp_[A-Za-z0-9_-]{43}$) — D74 P1-2
  validator authority

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix: Suite 36 paths use import.meta.dirname for CI portability (was hardcoded /Users/taodeng/olp/)

---------

Co-authored-by: dtzp555 <dtzp555@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

lib/doctor.mjs

@@ -144,6 +144,15 @@ export function buildBuiltinChecks(opts = {}) {
   const olpHome = resolveOlpHome(opts);
   const configPath = join(olpHome, 'config.json');
   const proxyUrl = resolveProxyUrl(opts);
+  // D74 P1-1 fix: server.running and server.version probe /health, which
+  // under default production posture (auth.allow_anonymous: false) requires
+  // an Authorization: Bearer header. Without it, the probe gets 401 and
+  // doctor falsely reports the server down. Caller passes the resolved
+  // bearer token via opts.authHeaders (a `{Authorization: 'Bearer ...'}`
+  // object). Empty headers means "no token configured" — the probe still
+  // fires but a 401 response is treated as "auth misconfigured" rather
+  // than "server down" (see server.running check below).
+  const authHeaders = opts.authHeaders ?? {};
 
   const checks = [];
 
@@ -298,7 +307,9 @@ export function buildBuiltinChecks(opts = {}) {
       id: 'server.running',
       category: 'server',
       async run() {
-        const r = await httpGet(`${proxyUrl}/health`, { timeoutMs: 3000 });
+        // D74 P1-1: pass authHeaders so the probe works under the default
+        // production posture (auth.allow_anonymous: false).
+        const r = await httpGet(`${proxyUrl}/health`, { timeoutMs: 3000, headers: authHeaders });
         if (!r.ok) {
           return {
             status: 'fail',
@@ -311,6 +322,25 @@ export function buildBuiltinChecks(opts = {}) {
             },
           };
         }
+        // 401: server is up but the caller has no/wrong bearer token. NOT a
+        // "server down" condition — distinguish so the kind discriminator
+        // doesn't route to fix_server when the user just needs OLP_API_KEY.
+        if (r.status === 401 || r.status === 403) {
+          return {
+            status: 'fail',
+            message: `${proxyUrl}/health returned ${r.status} — server is up but the bearer token is missing or invalid. Set OLP_API_KEY env to an owner-tier token (npx olp-keys list).`,
+            evidence: {
+              fix_commands: [
+                'echo "set OLP_API_KEY=<your owner token> or OLP_OWNER_TOKEN=<...> then rerun olp doctor"',
+              ],
+              human_required: [
+                'Locate an owner-tier OLP API key plaintext (or run `npx olp-keys keygen --owner` to mint a new one — printed ONCE).',
+                'Export it: `export OLP_API_KEY=olp_...`',
+              ],
+              reference: 'docs/adr/0007-multi-key-auth.md § 9.1 + README § Environment Variables',
+            },
+          };
+        }
         if (r.status !== 200) {
           return { status: 'fail', message: `${proxyUrl}/health returned status=${r.status}` };
         }
@@ -333,7 +363,8 @@ export function buildBuiltinChecks(opts = {}) {
         } catch {
           return { status: 'warn', message: 'Could not read local package.json — skipping version comparison' };
         }
-        const r = await httpGet(`${proxyUrl}/health`, { timeoutMs: 3000 });
+        // D74 P1-1: same auth-headers fix as server.running.
+        const r = await httpGet(`${proxyUrl}/health`, { timeoutMs: 3000, headers: authHeaders });
         if (!r.ok || r.status !== 200) {
           return { status: 'warn', message: `Could not fetch /health to compare version (${r.error ?? `status ${r.status}`})` };
         }