fix(ocp-cli): replace eval-curl with bash array to preserve JSON body quoting

`eval curl "$_AUTH_HEADER" "$@"` re-tokenizes its argument list according to bash word-splitting rules. When OCP_ADMIN_KEY is set, the JSON body `'{"name": "laptop"}'` (which contains a space) gets split into `'{name:'` and `'laptop}'` — two separate args — so curl receives a malformed body and the server rejects the request. Fix: replace the `_AUTH_HEADER` string + `eval` pattern with a bash array `_AUTH_ARGS`. Array expansion via `"${_AUTH_ARGS[@]}"` preserves word boundaries across substitution with no eval required. Both code paths (OCP_ADMIN_KEY env var and ~/.ocp/admin-key file fallback) and the empty case (no admin key) are preserved unchanged. Verified via `bash -x` trace: Before: `curl … -d '{name:' 'laptop}'` (body split, malformed) After: `curl … -d '{"name": "testkey-pr-c"}'` (body intact, single arg) Identified during fresh-state Round 2 testing on MacBook. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-07-22 13:35:08 +00:00 · 2026-05-09 00:43:45 +10:00
26 changed files with 114 additions and 2629 deletions
@@ -4,46 +4,22 @@
 <!-- One or two sentences describing the change and why it is in scope for OCP. -->
 ## Endpoint Class (REQUIRED)
 Per `ALIGNMENT.md` and ADR 0006, every PR that touches a network-facing endpoint must declare its class. Pick the most specific applicable class (Hybrid covers PRs that touch both A and B):
 - [ ] **Class A** — forwards a `cli.js` operation (e.g., `/v1/messages`, `/api/oauth/*`, or the Anthropic-side wire call inside `/usage`)
 - [ ] **Class B** — extends an OCP-owned compatibility endpoint (per ADR 0006). Sub-bucket:
  - [ ] B.1 — OpenAI-compatibility surface (`/v1/chat/completions`, `/v1/models`)
  - [ ] B.2 — OCP-administrative surface (`/health`, `/dashboard`, `/sessions`, `/logs`, `/status`, `/settings`, `/api/keys*`, `/api/usage`, `/cache*`)
 - [ ] **Hybrid** — touches both classes (e.g., `/usage` if the PR modifies both the Anthropic wire call AND the local synthesis layer). Both evidence sections below must be filled.
 - [ ] **Not endpoint-touching** — refactor / docs / tooling that does not modify any request handler. Skip both evidence sections; explain in Summary.
 ## Claude Code Alignment Evidence (REQUIRED)
-PRs with the relevant evidence section blank or unchecked will receive a `request changes` review and cannot be merged.
+Per `ALIGNMENT.md`, every PR that touches `server.mjs` or any network-facing surface must fill out this section. PRs with this section blank or unchecked will receive a `request changes` review and cannot be merged.
 ### If Class A
 - [ ] **Corresponding `cli.js` reference.** I have identified the `cli.js` function and line range that performs the operation this PR forwards. Citation (format `cli.js:NNNN` or `cli.js vE4 <functionName>`):
  <!-- e.g. cli.js:18423-18467 (function: sendUserMessage)  -->
- [ ] **If `cli.js` does not perform this operation**, I have stated this explicitly below and justified the scope under `ALIGNMENT.md` Rule 2. (Note: in almost all cases this means the PR should be closed, not merged. Proxy layers do not invent endpoints. If the endpoint is in fact Class B, switch the class above and use the Class B section instead.)
+- [ ] **If `cli.js` does not perform this operation**, I have stated this explicitly below and justified the scope under `ALIGNMENT.md` Rule 2. (Note: in almost all cases this means the PR should be closed, not merged. Proxy layers do not invent endpoints.)
  <!-- Justification, if applicable. Empty is fine when cli.js does perform the operation. -->
 - [ ] **Commit message citations.** Every "Claude Code uses X" or "cli.js uses X" assertion in every commit of this PR is immediately followed by a `cli.js:NNNN` or `cli.js vE4 <functionName>` citation. I have verified this by rereading each commit message.
 ### If Class B
 - [ ] **Authorizing ADR.** Cite the ADR number that authorizes the endpoint this PR modifies (e.g., "ADR 0006 — OpenAI shim scope"). For B.1 endpoints (`/v1/chat/completions`, `/v1/models`), this is ADR 0006. For grandfathered B.2 endpoints, this is "ADR 0006 (grandfathered as of v3.16.4)." For new B.2 endpoints, cite the endpoint's own authorizing ADR; if none exists, the PR cannot proceed — the authorizing ADR must be drafted and merged first.
  <!-- e.g., ADR 0006 -->
 - [ ] **Specification citation.** For B.1 endpoints, link to the relevant section of OpenAI's `/v1/chat/completions` specification (https://platform.openai.com/docs/api-reference/chat/create), including the specific field or behaviour being implemented. For B.2 endpoints with their own ADR, cite the ADR section that specifies the behaviour. For grandfathered B.2 endpoints, the PR must be a behaviour-preserving refactor — link the existing handler code being modified.
  <!-- B.1 example: OpenAI chat/completions, `response_format` parameter, https://platform.openai.com/docs/api-reference/chat/create#chat-create-response_format -->
  <!-- B.2 example: ADR 00NN § "Behaviour" -->
 - [ ] **No invention beyond the specification.** I confirm this PR does not introduce any field or behaviour not present in OpenAI's spec for the endpoint (B.1) or beyond the scope of the authorizing ADR (B.2). For grandfathered B.2 endpoints, I confirm the change is behaviour-preserving (no contract drift). If something the user actually wants is not in the spec, the right answer is to close this PR and propose an upstream spec change or a new ADR.
 ## Type of change
- [ ] Bug fix (alignment with existing `cli.js` behavior, or with the cited spec / ADR for Class B)
+- [ ] Bug fix (alignment with existing `cli.js` behavior)
- [ ] Feature (new `cli.js` behavior now surfaced through OCP, or new field already in OpenAI's spec for Class B)
+- [ ] Feature (new `cli.js` behavior now surfaced through OCP)
 - [ ] Refactor (no wire-level behavior change)
 - [ ] Deletion (unalignable feature removal per `ALIGNMENT.md` Unalignable Policy)
 - [ ] Documentation / governance
@@ -52,16 +28,14 @@ PRs with the relevant evidence section blank or unchecked will receive a `reques
 Reviewers: this section is for you, not the author. Do not approve until every box is checked.
- [ ] If Class A, I opened `cli.js` at the cited line range and confirmed the operation matches. If Class B, I opened the OpenAI spec at the cited section (B.1) or the authorizing ADR (B.2) and confirmed the behaviour described in this PR matches the cited reference.
+- [ ] I opened `cli.js` at the cited line range and confirmed the operation matches.
 - [ ] I ran (or confirmed CI ran) `.github/workflows/alignment.yml` and it passed.
 - [ ] I am not the commit author of any commit in this PR (Iron Rule 10).
- [ ] If the PR asserts scope without a `cli.js` citation (Class A) or without an ADR (Class B), I confirmed the justification is sound per `ALIGNMENT.md` Rule 2 and ADR 0006.
+- [ ] If the PR asserts scope without a `cli.js` citation, I confirmed the justification is sound per `ALIGNMENT.md` Rule 2.
 - [ ] If the PR is Class B and adds a new endpoint or new method, I confirmed the authorizing ADR lands in the same merge or before this PR.
 ## Related
- `ALIGNMENT.md` Rule(s) invoked: <!-- e.g. Rule 3, or Rule 3 (Class B mapping) -->
+- `ALIGNMENT.md` Rule(s) invoked: <!-- e.g. Rule 3 -->
 - Authorizing ADR (Class B only): <!-- e.g. ADR 0006 -->
 - Related issue / prior PR: <!-- #NNN -->
 - Historical lesson reference (if relevant): <!-- e.g. 2026-04-11 drift, b87992f -->
@@ -4,11 +4,6 @@ on:
  pull_request:
    paths:
      - 'server.mjs'
      - 'setup.mjs'
      - 'scripts/**'
      - 'lib/**'
      - 'ocp'
      - 'ocp-connect'
      - '.github/workflows/alignment.yml'
 jobs:
@@ -71,80 +66,6 @@ jobs:
          echo "Blacklist scan clean."
  port-spot:
    name: port literal SPOT (hard fail)
    # Background: from 2026-05-08 (PR #71 dogfood accident) through 2026-05-13
    # a hardcoded "3478" in scripts/upgrade.mjs + scripts/doctor.mjs cascaded
    # into wrong baseUrl writes for the OpenClaw "claude-local" provider,
    # taking out the "大内总管" Telegram agent.
    #
    # Rule: the only places allowed to write a literal port number in source
    # are (a) lib/constants.mjs (the SPOT), (b) bash scripts ocp / ocp-connect
    # (which can't import .mjs and must keep the literal in sync — flagged
    # with a `// keep in sync with lib/constants.mjs` style comment), and
    # (c) test-features.mjs (intentionally pins historical ports for plist /
    # systemd parser tests). Everything else MUST import from lib/constants.mjs.
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Scan for hardcoded port literals outside SPOT
        shell: bash
        run: |
          set -euo pipefail
          # Files/paths exempt from the SPOT requirement.
          EXEMPT_REGEX='^(lib/constants\.mjs|test-features\.mjs|ocp|ocp-connect|CHANGELOG\.md|README\.md|docs/|\.github/workflows/alignment\.yml)'
          # Hardcoded port literals to forbid in non-exempt source.
          FORBIDDEN_PORTS=("3478" "3456")
          FAIL=0
          for port in "${FORBIDDEN_PORTS[@]}"; do
            HITS="$(git ls-files | grep -E '\.(mjs|js|ts|json)$' \
              | xargs grep -n -E "[^0-9]${port}[^0-9]" 2>/dev/null \
              | grep -v -E "${EXEMPT_REGEX}" \
              || true)"
            if [ -n "$HITS" ]; then
              echo "::error::Hardcoded port literal '${port}' found outside lib/constants.mjs:"
              echo "$HITS"
              FAIL=1
            fi
          done
          if [ "$FAIL" -ne 0 ]; then
            cat <<'EOF'
          ============================================================
          PORT LITERAL SPOT VIOLATION
          ============================================================
          A hardcoded TCP port literal was found in a source file
          that should import from lib/constants.mjs instead.
          Background: this rule exists because between 2026-05-08 and
          2026-05-13 a stray hardcoded "3478" in scripts/upgrade.mjs
          and scripts/doctor.mjs cascaded into downstream OpenClaw
          config writes, taking out the OpenClaw Telegram agent.
          See v3.16.3 CHANGELOG and lib/constants.mjs header comment.
          Required action:
            1. Import DEFAULT_PORT (or related constant) from
               lib/constants.mjs instead of hardcoding the literal.
            2. If the file genuinely cannot import .mjs (e.g. bash
               script), add it to EXEMPT_REGEX in this workflow and
               add a `keep in sync with lib/constants.mjs` comment
               at the reference.
            3. For test files that intentionally pin historical ports
               (test-features.mjs), the regex already exempts them.
          ============================================================
          EOF
            exit 1
          fi
          echo "Port SPOT scan clean."
  commit-citation:
    name: commit message citation (soft check)
    runs-on: ubuntu-latest
@@ -8,14 +8,10 @@
 OCP (Open Claude Proxy) is a **proxy layer** for the Claude Code CLI. It forwards, observes, and multiplexes the traffic that `cli.js` already emits. It is **not** an extension layer. If `cli.js` does not perform a given operation, or performs it differently, OCP does not invent one.
 This Core Principle applies in full to **Class A** endpoints (the `cli.js`-mirror surface). A second class of endpoint — **Class B**, the OCP-owned compatibility surface — has its own scope discipline anchored to its own specification authority. See "Scope Clarification: OCP-Owned Compatibility Endpoints (Class B)" below and ADR 0006.
 ---
 ## Rules
 The following Rules apply to **Class A operations** (the `cli.js`-mirror surface — the inbound `/v1/messages` forwarding route, the outbound `/v1/messages` wire call used by `handleUsage()` for rate-limit-header extraction, the OAuth bearer machinery, and any future operations OCP forwards from `cli.js` to Anthropic). For the Class B mapping of each rule, see the Class B section below.
 1. **Rule 1 (Grep First).** Before adding, renaming, or changing any endpoint, header, parameter, or response shape, the author must `grep` the reference `cli.js` and record the exact line numbers in the commit message and PR body. An absent grep hit is itself a finding and must be declared.
 2. **Rule 2 (No Invention).** OCP must not introduce endpoints, headers, request fields, or response fields that are not present in `cli.js`. Speculative "Claude Code probably uses X" statements are prohibited. If the behavior is not observable in `cli.js`, the feature is out of scope.
@@ -72,78 +68,20 @@ On 2026-04-11, commit `b87992f` ("fix: use dedicated /api/oauth/usage endpoint f
 ## Unalignable Policy
-A feature is **unalignable** if, after a good-faith search, it cannot be mapped to a specific `cli.js` line range or function (Class A) or to a specific OpenAI specification section AND an authorizing ADR (Class B).
+A feature is **unalignable** if, after a good-faith search, it cannot be mapped to a specific `cli.js` line range or function.
 - Unalignable features are **deleted**, not disabled, not feature-flagged, not deprecated.
 - Deletion is the default outcome of an alignment audit finding. The burden of proof is on the feature, not on the auditor.
 - A deletion PR does not require user-facing deprecation notice, because the feature was never legitimately in scope.
- If a user workflow depended on an unalignable feature, the correct remediation is to upstream the behavior into `cli.js` (Class A) or into OpenAI's spec (Class B) or to move it out of OCP into a separate tool. OCP does not retain it.
+- If a user workflow depended on an unalignable feature, the correct remediation is to upstream the behavior into `cli.js` or to move it out of OCP into a separate tool. OCP does not retain it.
 ---
 ## Scope Clarification: OCP-Owned Compatibility Endpoints (Class B)
 OCP has two classes of endpoint. Rules 1–5 above were drafted in the aftermath of the 2026-04-11 forwarding drift and are written in the language of a one-to-one proxy; they apply verbatim to **Class A** endpoints. **Class B** endpoints — the OCP-owned compatibility surface where `cli.js` is not the wire authority — have their own scope discipline, anchored to their own specification authority. The full rationale lives in **ADR 0006 (OpenAI Shim Scope)**.
 **Class A** — `cli.js`-mirror endpoints. The endpoint exists because `cli.js` performs the equivalent operation and OCP forwards, observes, or multiplexes that operation. Rules 1–5 above apply verbatim. Citation format: `cli.js:NNNN` or `cli.js vE4 <functionName>`.
 **Class B** — OCP-owned compatibility endpoints. The endpoint exists because OCP itself surfaces it, with no `cli.js` analogue. Two sub-buckets: **B.1** (OpenAI-compatibility surface — protocol authority is OpenAI's `/v1/chat/completions` specification) and **B.2** (OCP-administrative surface — authority is the ADR that authorized the endpoint's existence).
 ### Grandfather provision for existing B.2 inventory
 ADR 0006 retroactively authorizes the B.2 endpoints listed in the inventory table below, **frozen at their current behaviour as of v3.16.4**. This is a one-time provision; it does not extend to new B.2 endpoints or to B.1 endpoints. Any change to the contract (request shape, response shape, semantics) of a grandfathered B.2 endpoint is treated as a new authorization request and requires either a behaviour-preserving refactor PR or its own ADR. Any new B.2 endpoint, or any new method on a grandfathered B.2 endpoint, requires its own ADR before merge.
 ### Current Class B inventory
 | Endpoint | Method | Sub-bucket | Authorizing ADR |
 |---|---|---|---|
 | `/v1/chat/completions` | POST | B.1 (OpenAI-compat) | ADR 0006 |
 | `/v1/models` | GET | B.1 (OpenAI-compat) | ADR 0006; content sourced from `models.json` per ADR 0003 |
 | `/health` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/dashboard` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/sessions` | GET, DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/logs` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/status` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/settings` | GET, PATCH | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys` | GET, POST | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys/:id` | DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys/:id/quota` | GET, PATCH | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/usage` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/cache/stats` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/cache` | DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 **Hybrid note.** `/usage` is a hybrid endpoint: the underlying call to `api.anthropic.com/v1/messages` (used to extract `anthropic-ratelimit-unified-*` headers, per the in-file comment block at `server.mjs` line 845–849) is Class A and requires the standard `cli.js` citation; the local synthesis layer that adds `proxy:` stats and `models:` snapshot is Class B and is authorized by ADR 0006. A PR touching only the wire-call layer is Class A; a PR touching only the synthesis layer is Class B; a PR touching both must satisfy both citation requirements.
 ### Class B citation requirement
 Class B PRs cite **the relevant specification section + the authorizing ADR**, in place of `cli.js:NNNN`. Examples:
 - B.1: "OpenAI `chat/completions` API, `response_format` parameter (https://platform.openai.com/docs/api-reference/chat/create), authorized by ADR 0006."
 - B.2 (grandfathered): "Authorized by ADR 0006 (grandfathered as of v3.16.4)."
 - B.2 (with its own ADR): "Authorized by ADR 00NN (the ADR that originally authorized the endpoint)."
 ### Rule mapping for Class B
 | Class A rule | Class B mapping |
 |---|---|
 | Rule 1 (Grep First) | Read the cited OpenAI spec section (B.1) or the authorizing ADR (B.2) before writing code. Record the spec URL and ADR number in the PR body. |
 | Rule 2 (No Invention) | OCP must not introduce fields or behaviour not present in OpenAI's spec for the endpoint (B.1) or outside the scope of the authorizing ADR (B.2). For grandfathered B.2 endpoints, "scope" is the v3.16.4 behaviour snapshot. |
 | Rule 3 (Match the Implementation) | Match OpenAI's spec wire-format (B.1) or the ADR's specified behaviour (B.2). |
 | Rule 4 (Unalignable Features Are Deleted) | A Class B endpoint that maps to nothing in OpenAI's spec **and** lacks an authorizing ADR (including not being in the grandfather inventory) is unalignable and is deleted on the same terms as a Class A unalignable feature. |
 | Rule 5 (Cite Line Numbers in Commits) | Cite the OpenAI spec section URL + authorizing ADR number in the commit body (B.1) or the authorizing ADR number alone (B.2). |
 ### New Class B endpoint procedure
 Any new Class B endpoint, or any new method on an existing Class B endpoint (including grandfathered ones), requires its own ADR before merge. An "ADR-less" new Class B endpoint is itself an alignment finding under Rule 4.
 ---
 ## Annual Alignment Audit
 - **Date:** 11 April each year (the anniversary of the `b87992f` drift).
- **Scope (Class A):** Diff the current `cli.js` against the pinned SHA-256 in the Golden Reference section. For every network call in `server.mjs`, re-verify that the corresponding `cli.js` reference still exists at the cited line numbers (adjust citations if line numbers shifted across Claude Code versions).
+- **Scope:** Diff the current `cli.js` against the pinned SHA-256 in the Golden Reference section. For every network call in `server.mjs`, re-verify that the corresponding `cli.js` reference still exists at the cited line numbers (adjust citations if line numbers shifted across Claude Code versions).
- **Scope (Class B):** Audit B.1 endpoints against OpenAI's current `/v1/chat/completions` specification snapshot. Audit B.2 endpoints against their authorizing ADR — for grandfathered endpoints, verify the endpoint behaviour still matches its v3.16.4 snapshot; for ADR-specific endpoints, verify behaviour still matches the ADR. The B.1 specification pin lives in `docs/openai-compat-pin.md` (created alongside the first B.1 audit; not required for ADR 0006 to land).
+- **Output:** A signed audit note committed to `docs/alignment-audits/YYYY-04-11.md`, updating the pin.
 - **Output:** A signed audit note committed to `docs/alignment-audits/YYYY-04-11.md`, updating the Class A pin and (once `docs/openai-compat-pin.md` exists) the B.1 pin.
 - **Failure mode:** Any audit finding that cannot be reconciled triggers an immediate deletion PR per the Unalignable Policy.
 ---
@@ -1,194 +1,5 @@
 # Changelog
 ## v3.16.4 — 2026-05-13
 ### Refactor — port-literal SPOT + CI guardrail
 Closes the structural side of the port-drift cascade addressed by v3.16.2
 and v3.16.3. Those two releases reverted plist / plugin / scripts back to
 3456 line-by-line, but the underlying invitation to drift — a hardcoded
 port literal scattered across six source files — was still intact.
 Changes:
 - **New `lib/constants.mjs`** — single source of truth for shared literals.
  Exports `DEFAULT_PORT = 3456`, `LOCAL_HOST = "127.0.0.1"`,
  `OPENAI_API_BASE = "/v1"`, `LOCAL_PROXY_URL`.
 - **`server.mjs:127`, `setup.mjs:36`, `scripts/upgrade.mjs:137`,
  `scripts/doctor.mjs:84` + `:205`, `scripts/sync-openclaw.mjs:73`** —
  all replaced with imports from `lib/constants.mjs`. Behavior is
  identical; the literal `3456` now exists in exactly one place per
  language (`lib/constants.mjs` for `.mjs`, `ocp` + `ocp-connect` for
  bash, `test-features.mjs` for pinned historical-port tests).
 - **`.github/workflows/alignment.yml`** — extended the path filter to
  `setup.mjs`, `scripts/**`, `lib/**`, `ocp`, `ocp-connect`. Added a new
  `port-spot` hard-fail job that greps for any hardcoded `3478` or `3456`
  literal in `.mjs/.js/.ts/.json` outside the EXEMPT_REGEX (which lists
  `lib/constants.mjs`, `test-features.mjs`, the bash CLIs, docs, and the
  workflow itself). Any future PR re-introducing a hardcoded port
  literal will be blocked at CI before it can cascade.
 - Doc comments in `server.mjs` env-var summary and `setup.mjs` usage
  banner reworded so the literal `3456` no longer appears as
  documentation text (CI grep is intentionally aggressive — it does not
  parse comments — so doc strings reference `DEFAULT_PORT from
  lib/constants.mjs` instead).
 No behavior change for any user. `CLAUDE_PROXY_PORT` env var remains
 the runtime override; the only difference is the unset-env fallback
 now flows through one shared constant.
 ALIGNMENT.md hard-requirements: this PR modifies `server.mjs` (one-line
 import + one literal swap, mechanical). No cli.js operation changed;
 the citation requirement does not apply. SPOT principle (Rule 2 spirit)
 is the entire motivation.
 ## v3.16.3 — 2026-05-13
 ### Fixes — completes v3.16.2 port-drift revert
 v3.16.2 reverted the plugin / `openclaw.plugin.json` / README / Mac mini
 plist back to `3456` (the historical source default since `593d0dc`), but
 missed three places in `scripts/` that still defaulted to `3478`. Those
 three lines were the residual cascade source: every time `ocp doctor` or
 `ocp upgrade` ran without `CLAUDE_PROXY_PORT` in the env, they probed
 `3478`, reported "OCP not responding" against a healthy 3456 instance,
 and (in the case of OpenClaw sync follow-ups on the maintainer's host)
 re-introduced 3478 into downstream config.
 Changes:
 - `scripts/upgrade.mjs:137` — default port `3478` → `3456`.
 - `scripts/doctor.mjs:84` — default port `3478` → `3456`.
 - `scripts/doctor.mjs:205` — default port `3478` → `3456`.
 No behavior change for users who set `CLAUDE_PROXY_PORT` explicitly; env
 still takes precedence. The fix only affects the unset-env fallback,
 which now matches `server.mjs:126` and the rest of the codebase.
 Test plan: existing `test-features.mjs` cases that pin
 `CLAUDE_PROXY_PORT=3478` continue to pass — they use the env path, not
 the default.
 ## v3.16.2 — 2026-05-12
 ### Fixes — corrects v3.16.1
 The v3.16.1 fix was directionally correct (plugin now reads env first, falls back to a hardcoded default) but **the narrative and the hardcoded default were both wrong**.
 What v3.16.1 said: "OCP server moved to 3478 default in v3.14+; plugin lagged at 3456."
 What is actually true:
 - **OCP server source default has been `3456` since `593d0dc` (initial release) and has never changed.** Every line in `server.mjs`, `setup.mjs`, and the `ocp` CLI still uses `3456` as the documented and code-level default.
 - The single OCP installation observed on `3478` is the maintainer's Mac mini, whose plist was rewritten with `--port 3478` during a PR #71 dogfood smoke-test accident on 2026-05-08 (see `~/.cc-rules/memory/learnings/subagent_setup_mjs_prod_host_collision.md`). The plist drift was never reconciled back to source default, and v3.16.1 incorrectly canonised the post-accident value as if it had been a release decision.
 This release:
 - Restores the plugin fallback to `http://127.0.0.1:3456` to match server source default.
 - Updates `openclaw.plugin.json` `configSchema.proxyUrl.default` back to `3456`.
 - Restores README §"Environment Variables" `CLAUDE_PROXY_PORT` default to `3456`.
 - Plugin reads `OCP_PROXY_URL` env (full URL) first, then `CLAUDE_PROXY_PORT` env (port only), then falls back to `3456`. Hosts whose OCP plist injects a non-default port must also inject the same `CLAUDE_PROXY_PORT` into the OpenClaw plist for the plugin to follow.
 - Maintainer's Mac mini plist was reverted from `3478` to `3456` as part of this release deploy (no source change reflects this; it was a one-host correction).
 ### Governance
 - No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
 ## v3.16.1 — 2026-05-12 (superseded — narrative incorrect; see v3.16.2 erratum)
 ### Fixes (as shipped — note erratum above)
 - **OCP plugin port lag** — `ocp-plugin/index.js` hard-coded `http://127.0.0.1:3456`. ~~While OCP server moved to 3478 in v3.14+,~~ **(corrected v3.16.2: no such move ever happened.)** The Mac mini's plist was on `3478` only as residue from a dogfood accident. Result: `/ocp` slash commands from the home Telegram bot returned "OCP error: fetch failed". v3.16.1 changed the plugin default to `3478` (wrong direction; v3.16.2 reverts to `3456`).
 ### Governance
 - No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
 ## v3.16.0 — 2026-05-10
 ### Features
 - **`ocp doctor --check oauth`** (PR #93) — fast path that runs only the OAuth check, skipping
  version detection / from-version / git operations / models endpoint. ~50ms vs. full doctor's
  ~200-500ms. Use cases: AI agent repair loops, post-`claude auth login` verify, quick health
  gates. Help text in `cmd_doctor_help` now reflects working behaviour.
 - **`ocp update --rollback --gc`** — manually garbage-collect old upgrade snapshots.
  Retention policy: keep last 5 snapshots OR snapshots newer than 30 days OR the single most
  recent (always-keep safety net). `--dry-run` previews. Successful `ocp update` runs auto-GC
  at the end of the full path; light path does not (no snapshot created there).
 ### Behavior changes
 - After a successful cross-minor `ocp update`, the auto-GC emits `[gc] removed N old snapshots`
  to stderr if any were collected. Safe to ignore; manual gc is `ocp update --rollback --gc`.
 ### Governance
 - No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
 - PR #93 (--check oauth) merged separately; this release bundles it with the GC feature.
 ## v3.15.1 — 2026-05-10
 ### Fixes
 - **doctor: dynamic `latest_version` from `origin/main:package.json`** — v3.15.0 doctor used a hard-coded `latest = "v3.14.0"` fallback, which made any v3.15.0+ install report `kind = upgrade` (against a stale value). `ocp update` would then attempt `git checkout v3.14.0` — a downgrade. Doctor now fetches `git -C ~/ocp show origin/main:package.json` to determine the actual latest version; on failure (offline, fresh clone with no remote), falls back to `currentVersion` so `kind = noop` instead of recommending a downgrade.
 ## v3.15.0 — 2026-05-10
 ### Features
 - **`ocp doctor`** — health & upgrade-readiness check; primary entry for AI-driven debugging.
  `--json` mode emits a `next_action` with `ai_executable[]` for agents to run verbatim
  and `human_required[]` for steps requiring the user (typically only OAuth).
 - **`ocp update` cross-version path** — for cross-minor jumps (e.g. v3.10 → v3.14),
  `ocp update` now runs doctor → snapshot → `setup.mjs` (with the plist env-merge from
  PR #90) → service restart → post-flight `/health` + `/v1/models` verification.
  Same-patch updates retain the existing light path; users see no change for routine
  patch bumps.
 - **`ocp update --rollback`** — restore the most recent (or specified) upgrade snapshot.
  Snapshots are saved to `~/.ocp/upgrade-snapshot-<ISO-ts>/` and never auto-deleted.
 - **Fresh-install routing** — `ocp update` on installations < v3.4.0 routes to a fresh-install
  flow (with `--yes` to skip confirmation; AI agents pass this). OAuth survives via Claude
  Code's credential store; users do not re-OAuth unless their token was independently broken.
 - **AI prompt blocks in README** — §Installation, §Upgrading, and §Troubleshooting each
  start with a copy-paste prompt for Claude Code / Cursor / Copilot, so users can drive
  install / setup / upgrade through their existing AI assistant.
 ### Behavior changes
 - `ocp update` may take 10–30s longer when a cross-minor jump triggers the full path
  (snapshot + post-flight). Patch bumps are unchanged.
 - Pre-v3.4.0 installs are routed to fresh-install rather than failing silently or
  half-migrating.
 ### Governance
 - No `cli.js` citation needed (no `server.mjs` change). ALIGNMENT.md Rule 2 not engaged.
 - Depends on PR #90 (plist env merge bug fix; merged before this release).
 ## v3.14.0 — 2026-05-10
 ### Features (security hardening)
 - **Per-key session isolation** (PR #86, S1) — the `sessions` Map in `server.mjs` is now keyed by `${keyName}|${conversationId}` instead of bare `conversationId`. Before this fix, two clients using distinct API keys but the same `session_id` value (e.g. both defaulting to `"default"`) would share the same `cli.js` subprocess and conversation history, creating a cross-tenant leak path. Post-fix each (key, session) pair is isolated end-to-end, extending the per-key cache isolation shipped in v3.13.0 D1 to the session layer.
 - **On-disk credential file modes 0700/0600** (PR #87, S2) — `setup.mjs` now creates `~/.ocp` at mode 0700 and both `admin-key` and `ocp.db` at mode 0600. An idempotent `reconcileFileModes()` call in `server.mjs` startup tightens any existing installation to these modes automatically on every launch, so existing prod boxes fix themselves without manual `chmod`. Before this fix, all three files were created at the process's default umask (typically world-readable 0644 / 0755), leaving plaintext credentials readable by other local users.
 - **`/api/usage` default scope = self; admin all-keys requires `?all=true`** (PR #88, S3) — the usage endpoint now applies a least-privilege default: anonymous callers receive only their own rows, non-admin authenticated callers receive only their own rows, and admin callers receive only their own rows unless they explicitly pass `?all=true`. When `?all=true` is used, an audit log line is emitted. Before this fix, any admin-token holder could silently enumerate usage data for every key on the server.
 ### Behavior changes
 - **Breaking change for admin tooling**: `/api/usage` no longer returns all-keys data by default. Existing cron jobs, dashboards, or scripts that rely on the admin token seeing all-keys output must add `?all=true` to their request URL after upgrading to v3.14.0.
 - **File mode reconcile at server startup** logs a one-line notice per path when mode is tightened (e.g. `[security] tightened ~/.ocp/ocp.db → 0600`). No action is required from the operator; the reconcile is idempotent and silent when modes are already correct.
 - **`sessions` Map key is now `${keyName}|${conversationId}` internally.** No client-visible wire change — the `session_id` field in request/response is unchanged.
 ### Verification
 - Stress-test pass: 11/11 phases including S1/S2/S3 security regression checks (Phase E, I, J). 35-minute sustained run, 60 calls, 0 errors, 0 timeouts. RSS dropped 51→47 MB across the window. Per-key cache isolation, singleflight, cache_control bypass, quota enforcement, file-mode reconcile, and scope guard against escalation all verified against running code.
 ### Governance
 - All three PRs (#86, #87, #88) include the explicit `cli.js`-citation-not-applicable disclaimer (per PR #75 pattern) since they are OCP-internal access-control, session-state, and file-permission changes with no corresponding `cli.js` operation to cite.
 ### No new env vars / no public API surface change beyond the documented breaking change
 This release adds no new env vars or endpoints. The only externally visible change is the `/api/usage` scope guard (breaking for admin all-keys consumers; see Behavior changes above).
 ## v3.13.0 — 2026-05-07
 ### Features (cache layer hardening)
@@ -6,8 +6,6 @@
 *Open source from day one, used daily by my family, maintained on nights and weekends. If OCP saves you money too, you can [☕ buy me a coffee](https://buymeacoffee.com/dtzp555) — [full story below](#support-ocp).*
 *If OCP saves you a setup, a ⭐ helps other folks discover it. Issue reports are even more useful — that's the highest-quality feedback this project gets.*
 OCP turns your Claude Pro/Max subscription into a standard OpenAI-compatible API on localhost. Any tool that speaks the OpenAI protocol can use it — no separate API key, no extra billing.
 ```
@@ -69,20 +67,6 @@ Any tool that accepts `OPENAI_BASE_URL` works with OCP:
 ## Installation
 The simplest path: ask your AI.
  Paste this prompt to Claude Code / Cursor / Copilot:
  ```
  Install OCP for me. Read README §Manual Installation and follow it.
  Tell me when I need to run `claude auth login`.
  ```
 The AI will run `git clone`, `npm install`, `node setup.mjs`, and tell you
 when to OAuth.
 ### Manual Installation
 OCP has two roles: **Server** (runs the proxy, needs Claude CLI) and **Client** (connects to a server, zero dependencies).
 ```
@@ -201,8 +185,7 @@ The setup script will:
 1. Verify Claude CLI is installed and authenticated
 2. Start the proxy on port 3456
 3. Install auto-start (launchd on macOS, systemd on Linux)
-
+4. Symlink `ocp` to `/usr/local/bin` for CLI access
 After install the `ocp` CLI lives at `~/ocp/ocp`. To put it on your PATH, either symlink it manually (`ln -sf ~/ocp/ocp ~/.local/bin/ocp` if `~/.local/bin` is on your PATH, or `sudo ln -sf ~/ocp/ocp /usr/local/bin/ocp` for a system-wide symlink) or add an alias (`alias ocp=~/ocp/ocp`). Otherwise invoke it as `~/ocp/ocp <subcommand>`. The rest of this README assumes `ocp` is on your PATH.
 **Single-machine use** — just set your IDE to use the proxy:
 ```bash
@@ -406,23 +389,17 @@ ocp keys revoke son-ipad   # Revoke a key
 | `shared` | `CLAUDE_AUTH_MODE=shared` + `PROXY_API_KEY=xxx` | Everyone shares one key |
 | `multi` | `CLAUDE_AUTH_MODE=multi` + `OCP_ADMIN_KEY=xxx` | Per-person keys with usage tracking (recommended) |
 > **Usage scope (v3.14.0+):** `/api/usage` returns the caller's own rows by default. Admin callers must pass `?all=true` to retrieve data for all keys; doing so emits an audit log line.
 ### Anonymous Access (optional)
 In `multi` mode, the admin can designate a single well-known "anonymous" key that bypasses `validateKey()` and grants public read/write access. This is useful for letting LAN users (or clients like OpenClaw multi-agent setups) connect without individual per-user keys.
 **Enable**:
 The anonymous key is wired into the service unit (launchd plist on macOS, systemd unit on Linux) at install time. Export `PROXY_ANONYMOUS_KEY` in your shell before running `setup.mjs`, and `setup.mjs` will write it into the service unit env so the auto-started proxy picks it up:
 ```bash
 export PROXY_ANONYMOUS_KEY=ocp_public_anon   # or any string of your choice
-node setup.mjs --bind 0.0.0.0 --auth-mode multi
+ocp start                                    # or however you start the server
 ```
 If OCP is already installed without it, re-export the env var and re-run `node setup.mjs` (the installer is idempotent — it refreshes the service unit). Then `ocp restart` so the running proxy picks up the new env. Setting `PROXY_ANONYMOUS_KEY` only in your interactive shell **does not** affect the auto-started proxy — the service unit is the source of truth for its environment.
 **Client side**: the anonymous key value is exposed via `GET /health` as the field `anonymousKey` (null when not set). Clients like `ocp-connect` can auto-discover and use it, so the end user doesn't need to get a personal key from the admin.
 **Security note**: setting this env var is an **opt-in** to public access — anyone who can reach your OCP endpoint can use it, up to any rate limits you configure. Don't enable this on internet-exposed OCP instances without additional protection.
@@ -476,7 +453,6 @@ When a key exceeds its quota, OCP returns HTTP 429 with a structured error:
 - Keys are stored in `~/.ocp/ocp.db` (SQLite, zero external dependencies)
 - Admin key is required for key management API endpoints
 - The dashboard (`/dashboard`) and health check (`/health`) are always public
 - File modes for `~/.ocp` (0700), `admin-key` + `ocp.db` (0600) are auto-tightened at server startup as of v3.14.0
 ## Built-in Usage Monitoring
@@ -515,7 +491,6 @@ ocp keys               List all API keys (multi mode)
 ocp keys add <name>    Create a new API key
 ocp keys revoke <name> Revoke an API key
 ocp connect <ip>       One-command LAN client setup
 ocp doctor             Health & upgrade-readiness check; primary entry for AI-driven debugging. --json produces a next_action for AI agents.
 ocp lan                Show LAN connection info & IP
 ocp settings           View tunable settings
 ocp settings <k> <v>   Update a setting at runtime
@@ -542,57 +517,17 @@ ocp --help
 > **Cloud/Linux servers:** If `ocp: command not found`, the binary isn't in PATH. Full path: `~/.openclaw/projects/ocp/ocp`
-## Upgrading
+### Self-Update
 The simplest path: ask your AI.
  Paste this prompt:
  ```
  Upgrade my OCP. Run `ocp update` and follow whatever it says.
  If it tells me to run `claude auth login`, I'll do that.
  ```
 What `ocp update` does:
 - **Patch bump** (e.g. `v3.14.0 → v3.14.1`):
  light path (git pull + npm install + restart).
 - **Cross-minor** (e.g. `v3.10 → v3.14`):
  full path: pre-flight check, snapshot, `setup.mjs` (with plist env-merge),
  service restart, post-flight `/health` and `/v1/models` verification.
 - **Old version** (< v3.4.0):
  fresh-install. Pre-v3.4 lacked admin-key/usage-db, so there is nothing to
  migrate. Your OAuth token (managed by the Claude Code CLI, not OCP) is
  preserved; you do not need to re-OAuth unless your token expired
  separately.
 Snapshots are saved to `~/.ocp/upgrade-snapshot-<ISO-ts>/` and never
 auto-deleted. Clean old ones with `rm -rf ~/.ocp/upgrade-snapshot-*` once
 you're confident the upgrade is stable.
 ### Manual upgrade — same command, no AI
 ```bash
-ocp update                  # smart-pick path
+# Check if a new version is available
-ocp update --check          # show available updates, don't apply
+ocp update --check
-ocp update --dry-run        # preview plan
+
-ocp update --target v3.13.0 # pin a specific version
+# Pull latest, sync plugin, restart proxy — one command
-ocp update --rollback --yes # restore most recent snapshot (--yes confirms)
+ocp update
 ocp update --rollback --list      # list snapshots, no mutation
 ocp update --rollback --dry-run   # preview rollback plan
 ```
-### When upgrade fails
+`ocp update` runs (in order): `git pull` → `npm install` → plugin sync → **OpenClaw model registry sync** (v3.11.0+) → proxy restart → health check.
 `ocp update` prints a recovery line on failure. To restore from the snapshot:
 ```bash
 ocp update --rollback --yes   # --yes confirms the destructive restore
 ocp doctor
 ```
 If `ocp doctor` still reports problems after rollback, open a GitHub issue
 with the snapshot path and the doctor JSON output (`ocp doctor --json`).
 ### OpenClaw Auto-Sync (v3.11.0+)
@@ -715,7 +650,7 @@ The canonical list lives in [`models.json`](./models.json) — the single source
 | `/api/keys` | GET/POST | List or create API keys (admin only) |
 | `/api/keys/:id` | DELETE | Revoke an API key (admin only) |
 | `/api/keys/:id/quota` | GET/PATCH | View or set per-key quota (admin only) |
-| `/api/usage` | GET | Per-key usage stats (`?since=&until=&hours=&limit=`); returns self only by default — pass `?all=true` (admin only) for all-keys data |
+| `/api/usage` | GET | Per-key usage stats (`?since=&until=&hours=&limit=`) |
 | `/cache/stats` | GET | Cache statistics (admin only) |
 | `/cache` | DELETE | Clear response cache (admin only) |
@@ -765,21 +700,6 @@ After installing the gateway plugin, use `/ocp` slash commands in your chat:
 ## Troubleshooting
 The simplest path: ask your AI.
  Paste this prompt:
  ```
  Run `ocp doctor` and follow its `next_action`. Tell me if you hit
  anything that needs human input.
  ```
 The doctor produces a JSON `next_action` with `ai_executable[]` (commands
 the agent runs verbatim) and `human_required[]` (steps that need you,
 typically just OAuth).
 ### Manual debugging
 ### Setup fails with "claude: command not found"
 `setup.mjs` requires the Claude CLI to be on `PATH`. Install it via the [official guide](https://docs.anthropic.com/en/docs/claude-cli), confirm with `which claude`, then run `claude auth login` before re-running `node setup.mjs`.
@@ -855,8 +775,7 @@ Future `ocp update` invocations sync automatically.
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CLAUDE_PROXY_PORT` | `3456` | Listen port (server-side). Also consumed by the OpenClaw `ocp-plugin` to dial the local proxy. |
+| `CLAUDE_PROXY_PORT` | `3456` | Listen port |
 | `OCP_PROXY_URL` | *(unset)* | Plugin-side full URL override (e.g. `http://10.0.0.5:3456`). Wins over `CLAUDE_PROXY_PORT` when both are set. Read by `ocp-plugin/index.js` only — server ignores it. |
 | `CLAUDE_BIND` | `127.0.0.1` | Bind address (`0.0.0.0` for LAN access) |
 | `CLAUDE_AUTH_MODE` | `none` | Auth mode: `none`, `shared`, or `multi` |
 | `OCP_ADMIN_KEY` | *(unset)* | Admin key for key management (multi mode) |
@@ -55,13 +55,7 @@
 </div>
 <div class="section">
-  <div class="flex" style="justify-content: space-between; align-items: center;">
+  <h2>Usage by Key</h2>
    <h2 style="margin: 0;">Usage by Key</h2>
    <label id="usage-scope-toggle" class="flex" style="display:none; gap: 0.4rem; font-size: 0.8rem; color: #94a3b8; cursor: pointer;">
      <input type="checkbox" id="usage-show-all" style="cursor: pointer;">
      <span>Show all keys</span>
    </label>
  </div>
  <table id="key-usage-table">
    <thead><tr><th>Key</th><th>Requests</th><th>OK</th><th>Err</th><th>Avg Time</th><th>Last Request</th></tr></thead>
    <tbody></tbody>
@@ -176,8 +170,7 @@ async function refreshStatus() {
 async function refreshUsage() {
  try {
-    const showAll = localStorage.getItem("ocp_usage_show_all") === "1";
+    const data = await api("/api/usage");
    const data = await api(showAll ? "/api/usage?all=true" : "/api/usage");
    const tbody = document.querySelector("#key-usage-table tbody");
    tbody.innerHTML = (data.byKey || []).map(k => `
      <tr>
@@ -211,8 +204,6 @@ async function refreshKeys() {
  try {
    const data = await api("/api/keys");
    document.getElementById("key-mgmt-section").style.display = "";
    // Admin-only "Show all keys" toggle for /api/usage scope.
    document.getElementById("usage-scope-toggle").style.display = "flex";
    const tbody = document.querySelector("#keys-table tbody");
    tbody.innerHTML = (data.keys || []).map(k => `
      <tr>
@@ -249,16 +240,6 @@ async function refreshAll() {
  document.getElementById("refresh-indicator").textContent = `Updated ${new Date().toLocaleTimeString()}`;
 }
 // Wire "Show all keys" toggle (visibility gated to admin via refreshKeys()).
 (function setupUsageScopeToggle() {
  const cb = document.getElementById("usage-show-all");
  cb.checked = localStorage.getItem("ocp_usage_show_all") === "1";
  cb.addEventListener("change", () => {
    localStorage.setItem("ocp_usage_show_all", cb.checked ? "1" : "0");
    refreshUsage();
  });
 })();
 refreshAll();
 setInterval(refreshAll, 30000);
 </script>
@@ -1,132 +0,0 @@
 # 0006 — OpenAI Shim Scope: Class A vs Class B Endpoints
 - **Date**: 2026-05-20
 - **Status**: Proposed — owner reviewing
 - **Authors**: project maintainer (with AI drafting assistance)
 - **Related**: `ALIGNMENT.md` (the constitution); ADR 0002 (Alignment Constitution provenance, PR #20, commit 2853088); PR #99 by external contributor (triggering incident — OpenAI `response_format` honoring on `/v1/chat/completions`)
 ## Context
 `ALIGNMENT.md` was drafted in the aftermath of the 2026-04-11 drift (commit `b87992f` — fabricated `/api/oauth/usage` endpoint) and ratified in PR #20 / commit 2853088. Its five Rules are written in the language of a one-to-one proxy: Rule 1 (Grep First), Rule 2 (No Invention), Rule 3 (Match the Implementation), Rule 4 (Unalignable Features Are Deleted), Rule 5 (Cite Line Numbers in Commits). All five anchor explicitly on `cli.js` as the golden reference. This is correct and binding for the endpoints OCP was originally designed to forward — `/v1/messages`, `/api/oauth/*`, and the rate-limit-header extraction path that backs `/usage` — because for those, `cli.js` is the literal wire authority and any deviation is a drift risk.
 OCP also exposes a second class of endpoint that the constitution does not currently distinguish: **OpenAI-compatible surface** that exists so non-Claude-Code clients (Honcho, OpenWebUI, OpenAI SDK consumers, BYO scripts) can talk to claude via OCP. The flagship is `/v1/chat/completions`, which translates between OpenAI's request/response schema and `cli.js`'s native protocol. `cli.js` never speaks OpenAI's wire format — by construction it cannot, because OpenAI and Anthropic are different vendors with different protocols. There is no `cli.js:NNNN` to cite for OpenAI's `messages[].role` field handling, OpenAI's streaming `delta` shape, OpenAI's `stop` event names, or OpenAI's `response_format` parameter. The protocol authority for these is OpenAI's published specification, not `cli.js`.
 The structural gap surfaced when PR #99 (external contributor `jaekwon-park`) added support for the OpenAI `response_format` request field on `/v1/chat/completions`. A strict reading of Rule 2 ("OCP must not introduce request fields that are not present in `cli.js`") blocks the PR. But the same strict reading also blocks the existence of `/v1/chat/completions` itself — every OpenAI-shaped field on that endpoint is, by definition, not in `cli.js`. The endpoint has been in OCP since before the constitution was written and is used by real downstream consumers. The constitution and the endpoint cannot both be correct under the current reading.
 The 2026-04-11 drift remains the cautionary tale that drove the constitution and remains binding. The drift was not "OCP exposed an endpoint that wasn't in `cli.js`" — it was specifically "OCP claimed to forward `cli.js`'s `/api/oauth/usage` call when no such call exists in `cli.js`." That is a Class A failure mode: a forwarding endpoint that lied about what it was forwarding. The fix to that failure mode (Rules 1, 2, 3, 5; CI blacklist; reviewer gate) was correct then and is correct now. This ADR does not relitigate that decision and does not soften Rules 1–5 for the class of endpoint they were designed to discipline.
 What this ADR does is acknowledge that OCP has two classes of endpoint, and that the discipline that fits Class A does not fit Class B without distortion. Class B needs its own anchor (OpenAI's specification) and its own authorization gate (an ADR per endpoint), so contributors know exactly which rule set applies to their PR and so Class B never becomes a backdoor for "OCP can do anything OpenAI-shaped."
 ## Decision
 Introduce an explicit two-class taxonomy of OCP endpoints:
 - **Class A — `cli.js`-mirror endpoints.** Endpoints that exist because `cli.js` performs the equivalent operation and OCP forwards, observes, or multiplexes that operation. Rules 1–5 of `ALIGNMENT.md` apply verbatim. The citation requirement is `cli.js:NNNN` (or `cli.js vE4 <functionName>`).
 - **Class B — OCP-owned compatibility endpoints.** Endpoints that exist because OCP itself surfaces them, with no `cli.js` analogue. They fall into two sub-buckets:
  - **B.1 — OpenAI-compatibility surface.** Endpoints implementing OpenAI's published API contract so non-Anthropic clients can use OCP. The protocol authority is OpenAI's specification.
  - **B.2 — OCP-administrative surface.** Endpoints that exist purely to operate the proxy itself (health, dashboard, key management, cache control). The authority for these is the ADR that authorized the endpoint's existence.
 For Class B endpoints, the citation requirement shifts from `cli.js:NNNN` to **(a)** the relevant specification section (OpenAI spec section for B.1, or the authorizing ADR for B.2) **and (b)** the ADR that authorized the endpoint's existence in the first place.
 ### Grandfather provision for existing B.2 inventory
 ADR 0006 retroactively authorizes the existing B.2 endpoints listed in the inventory table below, **frozen at their current behaviour as of v3.16.4**. This is a one-time grandfather provision intended to avoid a 12-ADR back-fill burden for endpoints that have existed in OCP since before any constitutional governance was written.
 The grandfather provision is narrowly scoped:
 - It covers only the B.2 endpoints enumerated in the inventory table as of this ADR's merge date.
 - It freezes those endpoints at their **current behaviour**. Any change to the request shape, response shape, or semantics of a grandfathered B.2 endpoint is treated as a new authorization request and requires either (a) a behaviour-preserving refactor PR with no contract change, or (b) its own ADR.
 - It does **not** authorize new B.2 endpoints. Any new B.2 endpoint, or any new method on a grandfathered B.2 endpoint, requires its own ADR before merge.
 - It does **not** extend to B.1 (OpenAI-compat) endpoints. B.1 endpoints are bounded by OpenAI's published specification, not by a behaviour snapshot — there is no grandfather equivalent for them.
 The structural intent is: take the one-time hit of declaring "current B.2 surface is authorized" cleanly, then make every future addition pay the ADR-per-endpoint cost. This prevents Class B from becoming a backdoor for general OCP-owned-surface invention while not blocking the present ADR on twelve back-fill PRs.
 ### Current Class B inventory (enumerated from `server.mjs`)
 The following endpoints exist today in `server.mjs` and are Class B (no `cli.js` analogue):
 | Endpoint | Method | Sub-bucket | Authorizing ADR |
 |---|---|---|---|
 | `/v1/chat/completions` | POST | B.1 (OpenAI-compat) | ADR 0006 |
 | `/v1/models` | GET | B.1 (OpenAI-compat) | ADR 0006; content sourced from `models.json` per ADR 0003 |
 | `/health` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/dashboard` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/sessions` | GET, DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/logs` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/status` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/settings` | GET, PATCH | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys` | GET, POST | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys/:id` | DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/keys/:id/quota` | GET, PATCH | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/api/usage` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/cache/stats` | GET | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 | `/cache` | DELETE | B.2 (administrative) | ADR 0006 (grandfathered as of v3.16.4) |
 For Class A reference, the current Class A inventory is `/v1/messages` (forwarded directly to `api.anthropic.com/v1/messages`) and the OAuth bearer / rate-limit-header machinery used by `handleUsage()` (which calls `https://api.anthropic.com/v1/messages` to extract `anthropic-ratelimit-unified-*` headers, per the in-file comment at line 845–849). The `GET /usage` endpoint surface itself is Class B (administrative augmentation: it adds `proxy:` and `models:` blocks not present in any upstream API), but the data fetch underlying it is Class A — see "Hybrid endpoints" below.
 ### Hybrid endpoints
 `/usage` is a hybrid: the wire call out to `api.anthropic.com/v1/messages` is Class A and must continue to cite `cli.js`; the local synthesis on top (`proxy:` stats block, `models:` snapshot, response shape) is Class B and is authorized by this ADR. Any future change strictly to the wire-call layer is Class A; any change strictly to the synthesis layer is Class B. A PR touching both must satisfy both citation requirements.
 ## What does NOT change
 The following continue to apply verbatim and are not weakened by this ADR:
 - **Rules 1, 2, 3, 4, 5 of `ALIGNMENT.md`** for all Class A endpoints. The 2026-04-11 drift discipline is unchanged. Class A PRs still require `cli.js:NNNN` citations, still must match `cli.js`'s wire format byte-for-byte, and still face the Unalignable Policy if the citation cannot be produced.
 - **CI blacklist** (`.github/workflows/alignment.yml`). The known-hallucinated token list (currently `api.anthropic.com/api/oauth/usage`) continues to be greppable-and-failable on every PR.
 - **Reviewer gate** (CLAUDE.md hard requirements + Iron Rule 10). Implementation author may not self-approve; a fresh-context reviewer opens `cli.js` at the cited lines for Class A PRs.
 - **Annual Alignment Audit** on 11 April. The Class A audit (re-verify each `server.mjs` Class A reference against the pinned `cli.js` SHA-256) continues unchanged.
 - **Unalignable Policy.** A Class A endpoint that cannot be traced to a `cli.js` reference is still deleted, not deprecated.
 - **Historical Lesson section in `ALIGNMENT.md`.** The 2026-04-11 drift remains the named cautionary incident, with commit SHAs intact.
 ## What additionally applies to Class B
 The following are new and apply only to Class B endpoints:
 1. **OpenAI specification as protocol authority (B.1).** The OpenAI compatibility surface follows OpenAI's published `/v1/chat/completions` specification (https://platform.openai.com/docs/api-reference/chat/create) — not OCP imagination, not "OpenAI probably does X," not generalization from adjacent OpenAI endpoints. The same anti-invention discipline that Rule 2 imposes for `cli.js` applies, with OpenAI's spec substituted as the reference.
 2. **ADR-authorized endpoint existence.** Any new Class B endpoint, or any new Class B endpoint method, requires its own ADR before merge. The grandfather provision above covers existing B.2 inventory only. An "ADR-less" Class B endpoint added after this ADR merges is itself an alignment finding and is subject to deletion under a Class B equivalent of the Unalignable Policy (see Rule 4 mapping in `ALIGNMENT.md`'s new section).
 3. **Class B citation format.** Class B PRs cite (a) the relevant specification section and (b) the authorizing ADR. Example for B.1: "OpenAI `chat/completions` API, `response_format` parameter (https://platform.openai.com/docs/api-reference/chat/create), authorized by ADR 0006." Example for B.2: "Authorized by ADR 0006 (grandfathered)" for grandfathered endpoints, or "Authorized by ADR 00NN" for endpoints with their own ADR.
 4. **Class B audit cadence.** Class B endpoints are audited annually alongside the Class A audit. B.1 endpoints are audited against OpenAI's current `/v1/chat/completions` specification snapshot. B.2 endpoints (grandfathered or ADR-specific) are audited against their authorizing ADR — for grandfathered endpoints, the audit verifies the endpoint behaviour still matches its v3.16.4 snapshot; for ADR-specific endpoints, the audit verifies behaviour still matches the ADR. The B.1 specification pin lives in `docs/openai-compat-pin.md` (to be created alongside the first B.1 audit; not a prerequisite for this ADR to land).
 5. **Reviewer expectation.** The fresh-context reviewer for a Class B PR opens the cited OpenAI spec section (B.1) or the authorizing ADR (B.2) instead of opening `cli.js`. The "I am not the commit author" rule and the "explicit approval comment naming the verified reference" rule continue.
 ## Consequences
 **Positive**
 - PR #99 becomes mergeable with a one-line scope declaration ("Class B — extends `/v1/chat/completions` per ADR 0006") plus the existing alignment-evidence section adapted to Class B citation format. The structural ambiguity that blocked it is removed.
 - Future Class B contributors have a clear template and a defensible scope: "extend `/v1/chat/completions` for an OpenAI-spec field that's already in OpenAI's spec" is a well-formed PR; "add a new OCP-invented field that looks OpenAI-shaped" is not, and the same anti-invention discipline that protects Class A protects Class B.
 - The Class A surface is structurally unchanged. Reviewers reading the new `ALIGNMENT.md` see a clean Class A regime with all five Rules intact, plus an enumerated and explicitly scoped Class B carve-out.
 - The administrative endpoint surface (B.2) is no longer in a "is this even allowed under the constitution?" limbo. The grandfather provision cleanly authorizes the current inventory; new B.2 endpoints must earn their ADR.
 **Negative**
 - OCP now maintains a second alignment surface. OpenAI's `/v1/chat/completions` specification is also a moving target (OpenAI ships changes more than once per year, including breaking ones), so the B.1 audit has real work attached.
 - The grandfather provision freezes the current B.2 behaviour. If a grandfathered B.2 endpoint has a latent bug or undesirable behaviour, "fixing" it is a contract change and now requires an ADR (or a behaviour-preserving refactor). This is intentional friction to prevent silent contract drift.
 - Contributors must now choose Class A or Class B on every PR. Some will misclassify. The PR template's required Class A/B radio (see PR template update) and the reviewer's spec-or-cli verification step are the structural counter-measures.
 **Mitigations**
 - The Class B inventory is small (currently 14 endpoints) and is enumerated explicitly in `ALIGNMENT.md`. New entries require an ADR per item 2 above, so the inventory cannot grow silently.
 - Anthropic-side change frequency (which drives Class A audit cost) is structurally higher than OpenAI's `chat/completions` shape, which has been stable across multiple OpenAI API versions. The marginal B.1 audit cost is low. The grandfathered B.2 audit cost is also low — most of those endpoints have not changed in months.
 - The B.1 specification pin in `docs/openai-compat-pin.md` lets the audit anchor on a specific OpenAI spec snapshot, the same way the Class A pin anchors on a specific `cli.js` SHA-256. Drift detection then works the same way for both classes.
 ## Historical Lesson — explicit non-relitigation
 This ADR does not relitigate the 2026-04-11 drift. The drift commit `b87992f` was Class A — it claimed `cli.js` forwarded a call that `cli.js` did not in fact make. The fix (constitution + CI blacklist + reviewer gate) was correct and remains binding for Class A. This ADR carves out Class B because the discipline that fits Class A does not fit a class of endpoint where `cli.js` is not the wire authority — not because the discipline was wrong, and not because the drift lesson is any less load-bearing.
 A reviewer or future maintainer reading this ADR should not infer: "OCP relaxed its alignment rules." The Class A regime is structurally identical to the version that shipped in PR #20. What changed is that the constitution now names the scope of that regime precisely (the class of endpoint for which `cli.js` is the wire authority) instead of implicitly applying it to every endpoint, including ones the regime was never designed for.
 ## Alternatives considered
 **(a) Refuse Class B as a category; close PR #99 and delete `/v1/chat/completions`.** This would resolve the structural ambiguity by enforcing Rule 2 maximally — if `cli.js` doesn't speak OpenAI's protocol, neither does OCP. Rejected: there is an existing user base on the OpenAI-compat surface, the surface is genuinely useful (it is OCP's bridge to non-Claude-Code agents), and deletion would be a load-bearing user-facing breakage in service of a doctrinal point that the constitution was never designed to make. The constitution was a response to the 2026-04-11 forwarding drift, not a charter against any OCP-owned surface.
 **(b) Soften Rule 2 to "OCP must not introduce surface area not present in `cli.js` OR not authorized by an ADR."** This is the obvious diff and would unblock PR #99 with the smallest possible textual change. Rejected because it loses the precision that Class A needs. A combined Rule 2 means a Class A reviewer has to read the PR description twice to figure out which authority applies. The Class A/B split makes the question explicit at the PR-template level (the author picks the class) and at the reviewer level (the reviewer opens the appropriate reference). The cost of the split is one new section in `ALIGNMENT.md`; the benefit is no ambiguity in either class.
 **(c) Move `/v1/chat/completions` and all OpenAI-compat surface out of OCP into a separate "ocp-openai-shim" repository.** This would cleanly resolve the scope question by moving Class B out of OCP entirely. Rejected as premature: the maintainer is one person, the OpenAI-compat surface today is a single endpoint plus its support, and the operational cost of two repositories (separate releases, separate CI, separate version coordination) exceeds the cost of one constitution with two named classes. If the OpenAI-compat surface ever grows to the size where a separate repo is justified, ADR 0006 is the natural pivot point — at that future date, the carve-out becomes a separation.
 **(d) Twelve-ADR back-fill for the existing B.2 inventory before this ADR can merge.** Considered and rejected on cost grounds. Each back-fill ADR would be a short paragraph explaining what an existing endpoint does and why it's allowed; the educational value is low and the merge friction is high (12 PRs through the reviewer gate). The grandfather provision above achieves the same authorization outcome in one paragraph, while still requiring an ADR for any future B.2 endpoint. The trade-off: grandfathered endpoints are not individually documented to ADR-depth. Mitigation: the inventory table in `ALIGNMENT.md` lists every grandfathered endpoint by path and method, so the audit surface remains explicit.
@@ -22,7 +22,6 @@ New ADRs increment from the highest existing number. Filenames are
 | [0003](0003-models-json-spot.md) | `models.json` as SPOT | Why model IDs / aliases / context windows live in a single JSON file (not duplicated in `server.mjs` and `setup.mjs` arrays). v3.11.0 refactor. |
 | [0004](0004-openclaw-auto-sync.md) | OpenClaw Auto-Sync | Why `scripts/sync-openclaw.mjs` runs on `ocp update`, what its scope boundary is (writes only `models.providers["claude-local"].models` and `agents.defaults.models["claude-local/*"]`), and the idempotency contract. |
 | [0005](0005-no-multi-provider.md) | No Multi-Provider | Why OCP stays single-provider (Anthropic-via-cli.js) and does not extend to OpenAI / Gemini / OpenRouter. Cost estimate: ~7 weeks for a v1 that buys neither moat nor commercial readiness. Separate commercial work starts in a separate repo. |
 | [0006](0006-openai-shim-scope.md) | OpenAI Shim Scope | The Class A / Class B taxonomy. Class A endpoints (`cli.js`-mirror) keep Rules 1–5 verbatim; Class B endpoints (OCP-owned compatibility surface — `/v1/chat/completions`, `/v1/models`, admin endpoints) are anchored to OpenAI's spec (B.1) or to an authorizing ADR (B.2). Triggered by PR #99 (external `response_format` honoring). Grandfathers the existing B.2 inventory at v3.16.4. |
 ## When to write a new ADR
@@ -1,11 +0,0 @@
 # OpenAI Compatibility Pin (Class B.1)
 **Status:** Placeholder — populated at first B.1 audit per ADR 0006 §"Class B audit cadence".
 This file is the Class B.1 counterpart to the Class A `cli.js` audit pin in `ALIGNMENT.md` §"Golden Reference". When the first annual alignment audit covers Class B (per `ALIGNMENT.md` §"Annual Alignment Audit"), this file will be populated with:
 - The OpenAI `/v1/chat/completions` specification snapshot date being audited against (and the source URL the snapshot was taken from).
 - The list of B.1 endpoints (currently `/v1/chat/completions`, `/v1/models`) and, for each one, the specific OpenAI spec fields and behaviours it honors.
 - Drift detection notes for any OpenAI spec changes since the previous audit, and any OCP code changes required to track those changes.
 Until populated, this file's existence is only a forward reference so that the link in `ALIGNMENT.md` does not 404. The actual audit procedure is defined in `ALIGNMENT.md` §"Annual Alignment Audit" (Class B scope) and ADR 0006 §"Class B audit cadence".
@@ -1,268 +0,0 @@
 # OCP Anthropic-Only Sandbox Strategy — Handoff Document
 **Status:** Forward-looking planning doc (not yet a decision)
 **Date:** 2026-05-29
 **Audience:** future OCP maintainer / session picking up multi-tenant security work
 **Provenance:** authored during OLP Phase 7 PR-B re-evaluation; OLP's parallel analysis (multi-provider) lives at `dtzp555-max/olp` `docs/adr/0014-sandbox-runtime-integration.md` Amendment 1 (pending). This OCP-side doc strips the multi-LLM generalization and keeps only what applies to OCP's single-provider (anthropic) deployment.
 ---
 ## 1. Why this doc exists
 OCP is in maintenance mode (per OLP ADR 0001 supersession of OCP ADR 0005). It is not under active development for new features. However, two things may eventually drive sandbox work in OCP:
 1. **Multi-key OCP deployments.** `OCP_OWNER_TOKEN` + per-key cache namespace already shipped (OCP `lib/keys.mjs`). If multiple human users share an OCP instance, the same multi-tenant filesystem-isolation gap that motivated OLP Phase 7 also exists here.
 2. **Cloud or shared-host OCP deployments.** Any deployment beyond "single user on their own machine" inherits the threat surface.
 If/when that work starts, this doc is the prior-art capture so the maintainer doesn't repeat OLP's PR-B path (which has a documented dead-end — see § 3.2 below).
 This doc is anthropic-only by design — codex/mistral/etc. multi-LLM concerns are out of scope per OCP ADR 0005.
 ---
 ## 2. The multi-tenant gap (OCP-specific)
 OCP spawns `claude -p` as the OCP-process user. Every spawned claude instance runs with the OCP user's filesystem permissions. Consequences for a multi-key OCP deployment:
 1. **Cross-key lateral read.** A prompt-injected `cat ~/.ocp/keys/<other-key>.json` reads any other key's manifest (token hash, owner_tier, providers_enabled — not catastrophic since it's only the *hash*, but still identity-attribution surface).
 2. **OAuth credential exposure.** `~/.claude/.credentials.json` is the Anthropic OAuth refresh token. A prompt-injected read of this file = stealing the subscription that OCP exists to pool.
 3. **SSH identity exposure.** `~/.ssh/id_*` reachable for lateral movement to other hosts the OCP user can reach.
 4. **Other host secrets.** Anything else under the OCP user's home is reachable.
 OCP's `ALIGNMENT.md` Class A/B endpoint discipline does not address this — that discipline is wire-level honesty (`cli.js` mirror), not host-level isolation.
 The threat model assumes prompt-injection capability — any caller with a valid OCP key + ability to craft a prompt that elicits a tool call. Default `claude -p` mode includes Read/Bash/etc. tool descriptions in the system prompt; the model is **eager** to use them.
 ---
 ## 3. Why OLP Phase 7 PR-B is the wrong path to copy
 OLP attempted to wrap `claude -p` spawn in `@anthropic-ai/sandbox-runtime` (outer bubblewrap on Linux, sandbox-exec on macOS). This produced four binding problems documented during OLP's re-evaluation:
 ### 3.1 Anthropic's design doesn't expect external sandboxing
 Per Anthropic's [engineering blog on Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing), `sandbox-runtime` is designed to be invoked **by claude code itself** to sandbox **its own** Bash tool / MCP servers / spawn children. It is **not** designed to sandbox claude code as an externally-wrapped process.
 Concretely: claude CLI assumes it can freely read+write its own `$HOME`-derived paths (`~/.claude.json`, `~/.claude/.credentials.json`, `~/.config/claude/`, future state files). When wrapped in `bwrap --ro-bind / /`, those writes hit `EROFS` and claude silently exits with no stdout.
 ### 3.2 `~/.claude.json` upstream status is "closed not planned"
 claude CLI writes `~/.claude.json` non-atomically at startup. Upstream issues #28842, #29162, #29217, #28837, #29051, #29250, #7243 all document this. **#29250 is closed as "not planned / duplicate"** — Anthropic is not going to make this file atomic-write because their mental model is that claude runs in an environment that can write its `$HOME`.
 For OCP, this means: any outer-sandbox approach that uses `--ro-bind` on `$HOME` will be a **permanent maintenance treadmill** — every new claude CLI version that adds a state file outside the patched mount paths breaks OCP. OLP's PR-B fold-in tried to patch this by promoting `~/.claude/` to rw, which was insufficient (the actual file is `~/.claude.json` at $HOME root, not inside `~/.claude/`).
 ### 3.3 The threat model doesn't justify the cost
 OCP is, per ADR 0005, a personal-and-family-scale tool. The realistic threat surface is misbehaving prompts from family members or self-injected via dependent agents, not adversarial external attackers. The blast radius of a successful cross-key read is bounded (token *hash*, OAuth that's pooled-by-design across all OCP keys).
 A maintenance-mode project investing weeks into outer-sandboxing for a hypothetical threat is a poor cost/benefit. There are cheaper architectures (§ 4 below) that get most of the protection.
 ### 3.4 OLP-specific reason that does NOT apply to OCP
 OLP also hit a multi-provider conflict: codex CLI has its own inner bubblewrap that breaks when wrapped in an outer bwrap (openai/codex#16018). **This is not an OCP concern** — OCP only spawns claude. So the multi-provider forcing function for OLP doesn't apply here. The other three reasons (§ 3.1–3.3) are sufficient on their own.
 ---
 ## 4. Three viable approaches for OCP
 Ranked by "engineering cost vs isolation strength" — pick by deployment context.
 ### 4.1 Approach A — Ephemeral `$HOME` via env var (recommended starting point)
 Per-spawn setup:
 ```
 ephemeralRoot=/tmp/ocp-spawn/<keyId>/<reqId>/home
 mkdir -p $ephemeralRoot/.claude
 ln -s ~/.claude/.credentials.json $ephemeralRoot/.claude/.credentials.json
 HOME=$ephemeralRoot claude -p --output-format stream-json ...
 ```
 Mechanics:
 - claude CLI uses Node's `os.homedir()` which reads `$HOME` env first.
 - `~/.claude.json` written by claude on startup → lands in `/tmp/ocp-spawn/<keyId>/<reqId>/home/.claude.json` (tmpfs, discarded after spawn).
 - `~/.claude/.credentials.json` is the OAuth file claude needs — symlinked in read-only from the real one.
 - Any new state file claude CLI introduces in a future version → also lands in the ephemeral home, no patch needed.
 Threat coverage:
 - ✅ Solves EROFS upgrade tax permanently — any claude state-file location works because they all land in tmpfs.
 - ✅ Cross-key OAuth credential isolation — keyA's ephemeral home has only keyA's symlink, but here the symlink target is the SAME real file because OCP shares OAuth (this is fine: shared OAuth is OCP's design, the symlink just keeps the file inaccessible via `cat ~/.claude/.credentials.json` from a different keyId's ephemeral root).
 - ❌ Does NOT solve cross-key lateral filesystem read via absolute paths. A prompt-injected `cat /home/<ocp-user>/.ocp/keys/<otherKey>.json` still works — `os.homedir()` override doesn't affect absolute-path reads.
 5-minute spike before adopting:
 ```bash
 HOME=/tmp/fake-home-spike claude --print "echo PONG" --no-session-persistence 2>&1
 ls -la /tmp/fake-home-spike  # expect: .claude.json + .claude/ created here
 find ~/.claude ~/.claude.json -newer /tmp/spike-marker 2>/dev/null  # expect: empty
 ```
 If claude falls back to `os.userInfo().homedir` (uses getpwuid_r, ignores HOME env), this approach degrades — fall back to Approach B.
 **Engineering cost:** ~50 LOC in OCP's spawn pipeline (mkdir + symlink + env merge + cleanup-on-exit). No new dependencies.
 ### 4.2 Approach B — Outer bubblewrap with `--tmpfs $HOME` + `--ro-bind` credentials
 ```
 bwrap \
  --ro-bind / / \
  --tmpfs /home/<ocp-user> \
  --ro-bind /home/<ocp-user>/.claude/.credentials.json /home/<ocp-user>/.claude/.credentials.json \
  --ro-bind /home/<ocp-user>/.ocp/keys/<thisKeyId>.json /home/<ocp-user>/.ocp/keys/<thisKeyId>.json \
  --dev /dev --proc /proc --tmpfs /tmp \
  claude -p ...
 ```
 This is the canonical bwrap pattern (Flatpak uses exactly this for every sandboxed app — see [Bubblewrap ArchWiki Examples](https://wiki.archlinux.org/title/Bubblewrap/Examples)).
 Threat coverage:
 - ✅ Solves EROFS upgrade tax (tmpfs accepts any write path).
 - ✅ Cross-key lateral read prevention — only the current key's manifest is bind-mounted in, others are simply absent from the sandbox view.
 - ✅ `~/.ssh` and similar identity material absent from sandbox.
 Trade-offs:
 - bwrap dependency: install `bubblewrap` apt package on host.
 - Bypasses `@anthropic-ai/sandbox-runtime` library — direct bwrap arg composition. Worth it because sandbox-runtime's outer-wrap design is for short-lived claude-internal subprocesses, not long-running claude CLI itself (per § 3.1).
 - macOS: not supported by bwrap (macOS would need separate `sandbox-exec` profile, ~50-100 LOC additional work). OCP cross-machine maintainer deploys mostly on Mac mini + Oracle ARM VM — both Linux on the cloud side, Mac mini side may remain unsandboxed if family-trust-zone.
 **Engineering cost:** ~150 LOC for the spawn wrapper + deployment doc updates to require `apt install bubblewrap`. macOS support is a separate ~100 LOC if/when needed.
 ### 4.3 Approach C — OverlayFS lowerdir (read-only) + tmpfs upperdir (writable)
 ```
 mount -t overlay overlay \
  -o lowerdir=/home/<ocp-user>/.claude,upperdir=/tmp/ocp-spawn/<reqId>/upper,workdir=/tmp/ocp-spawn/<reqId>/work \
  /tmp/ocp-spawn/<reqId>/merged-claude
 HOME=/tmp/ocp-spawn/<reqId>/home claude -p ...
 # After spawn: umount + rm -rf
 ```
 Most elegant — claude sees a view identical to its real `~/.claude/`, all writes go to tmpfs upperdir, real `~/.claude/` is never touched.
 Trade-offs:
 - Requires `CAP_SYS_ADMIN` or rootless-overlayfs (kernel ≥5.11 + user-ns enabled). OCP currently runs as the maintainer's user — no SYS_ADMIN — so this would require either running OCP as root (bad) or rootless-overlayfs setup.
 - More moving parts (mount/umount per spawn, work-dir lifetime, cleanup-on-crash).
 Better fit if OCP ever moves to a dedicated `ocp` system user with `CAP_SYS_ADMIN` capability via systemd.
 **Engineering cost:** ~120 LOC + kernel/permission preflight check.
 ---
 ## 5. Cross-key isolation orthogonal layer
 The three approaches above all solve `~/.claude.json` EROFS + state-write isolation. None of them alone solve **cross-key lateral filesystem read via absolute paths** (e.g. prompt-injected `cat /home/<user>/.ocp/keys/<otherKey>.json`).
 For that, two options compose with any of A/B/C:
 ### 5.1 Per-spawn `sandbox-runtime` customConfig with `denyRead`
 `@anthropic-ai/sandbox-runtime`'s `wrapWithSandbox(command, binShell?, customConfig?, abortSignal?)` accepts per-call override:
 ```
 const otherKeysWorkspaces = listAllKeyManifestsExcept(thisKeyId)
 const wrapped = await SandboxManager.wrapWithSandbox(claudeCommand, undefined, {
  filesystem: {
    denyRead: [
      ...otherKeysWorkspaces,          // all keys except current
      '/home/<ocp-user>/.ssh',
      '/home/<ocp-user>/.gnupg',
      '/home/<ocp-user>/.aws',
    ],
    allowWrite: [ephemeralRoot, '/tmp'],
  },
 })
 ```
 This adds bwrap deny-paths per-spawn (after sandbox-runtime singleton init). Works in combination with Approach A (the `HOME` env-var override is independent of sandbox-runtime's restrictions).
 Caveat: this re-introduces the outer-bwrap concern from § 3.1 — claude CLI is now wrapped after all. Mitigation: use this only for **cross-key isolation**, not for `$HOME` restriction. The `denyRead` paths are all outside `$HOME`, so claude's `~/.claude.json` write is unaffected.
 ### 5.2 Per-OS-user OCP spawning
 Each OCP key gets a dedicated Linux user (`ocp-<keyId>`). Spawn claude as that user via `runuser` or `sudo -u`. OAuth credential shared via Linux group permissions or bind-mount.
 True kernel-level uid isolation. Most robust answer for OCP-as-shared-host scenarios.
 Trade-offs:
 - Setup script complexity (one-time per key).
 - Linux-only.
 - Doesn't fit Mac mini deployment.
 Best fit for a cloud OCP deployment where per-tenant trust isolation matters.
 ---
 ## 6. Trust model framing
 OCP's authentication layer (`lib/keys.mjs`) provides **attribution** (per-key audit, per-key cache namespace). It does NOT, by itself, provide **isolation** (per-key trust boundary against prompt-injection lateral reads).
 This distinction is worth making explicit in OCP's README "Security" section (it currently isn't). The three tiers:
 | Tier | Trust Model | Sandbox requirement |
 |---|---|---|
 | **Single-user** | maintainer's own machine, single OCP token | None — system-user permissions are sufficient |
 | **Family-trust-zone** | maintainer + family members on shared OCP instance, all parties trusted not to attack each other | Optional — Approach A (ephemeral $HOME) gives cleanup hygiene without changing trust assumptions |
 | **Shared-host / cloud / external callers** | OCP keys handed to potentially-adversarial callers (CI runners, third-party agents, public demo) | Required — Approach B or C + § 5 cross-key isolation |
 The current OCP deployment fits tier 1 or 2. The work in this doc applies only when promoting to tier 3.
 ---
 ## 7. Recommendation if/when this work starts
 **Phase 1 — Approach A (ephemeral `$HOME`) only.**
 - ~50 LOC, no apt deps, works on Mac mini + Linux
 - Solves the EROFS upgrade tax structurally
 - Closes cross-key OAuth-credential-file lateral read
 - Cost-effective hygiene improvement
 **Phase 2 — Approach B (outer bwrap) gated by deployment config.**
 - Add `~/.ocp/config.json` field `security.sandbox: 'off' | 'tmpfs-home'`
 - Default off (preserves Mac mini family deployment)
 - Operator opts in on Linux cloud deployments
 - Apt prereq documented in deployment guide
 **Phase 3 — § 5 cross-key isolation (only if tier 3 deployment is planned).**
 - Layer per-spawn customConfig denyRead OR per-OS-user spawning
 - Treat as separate ADR amendment with its own threat-model evidence
 **Skip Approach C** unless a future requirement forces overlay (low likelihood for OCP scope).
 ---
 ## 8. Authority citations
 This doc claims findings about claude CLI / `@anthropic-ai/sandbox-runtime` behavior. Sources for verification:
 - [Anthropic engineering — Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) (sandbox-runtime design intent)
 - [Anthropic sandbox-runtime GitHub](https://github.com/anthropic-experimental/sandbox-runtime) (wrapWithSandbox API + customConfig per-call signature)
 - [claude-code#29250 — `.claude.json` non-atomic-write closed-not-planned](https://github.com/anthropics/claude-code/issues/29250)
 - [claude-code#29162 — read-only `~/.claude.json` startup hang](https://github.com/anthropics/claude-code/issues/29162)
 - [claude-code#29217 — concurrent-write corruption](https://github.com/anthropics/claude-code/issues/29217)
 - [claude-code#28842 — Windows startup race](https://github.com/anthropics/claude-code/issues/28842)
 - [claude-code#7243 — "the .claude.json elephant in the room"](https://github.com/anthropics/claude-code/issues/7243)
 - [Bubblewrap README](https://github.com/containers/bubblewrap)
 - [Bubblewrap ArchWiki — Examples section, --tmpfs HOME pattern](https://wiki.archlinux.org/title/Bubblewrap/Examples)
 - [Sandboxing CLI tools with Bubblewrap — botmonster](https://botmonster.com/self-hosting/sandbox-linux-apps-cli-tools-bubblewrap/)
 - [OverlayFS kernel documentation](https://docs.kernel.org/filesystems/overlayfs.html)
 - [OverlayFS ArchWiki](https://wiki.archlinux.org/title/Overlay_filesystem)
 OLP's parallel work (multi-provider generalization of this strategy, including the codex inner-bwrap conflict that does not apply to OCP):
 - `dtzp555-max/olp` `docs/adr/0014-sandbox-runtime-integration.md` (PR-B as-shipped) + Amendment 1 (pending — Solution 1 architecture)
 - `dtzp555-max/olp` `docs/plans/cloud-deployment-family.md` § 5 (deployment-side trust tier mapping)
 - archive branch `dtzp555-max/olp:phase-7-pr-b-outer-bwrap-snapshot` captures the outer-bwrap approach as snapshot if anyone wants to revisit it
 ---
 ## 9. What this doc is NOT
 - Not an ADR. ADRs are decisions; this is a forward-facing strategy doc that becomes an ADR only when work starts and a decision is made.
 - Not a binding spec. The three approaches are alternatives; the recommendation in § 7 is the maintainer's lean from prior-art analysis, not a constitution.
 - Not authority for any code change. OCP `ALIGNMENT.md` still requires citation per Class A/B; no sandbox code lands without proper authority pinning when the work eventually starts.
 - Not a security audit. The threat model is informal — based on prior-art search + incident memory from OLP's parallel session. A real cloud deployment should commission an independent threat model.
 ---
 **Authors:** project maintainer (handoff prepared with AI drafting assistance during OLP Phase 7 PR-B re-evaluation, 2026-05-29).
@@ -3,13 +3,11 @@
 import { DatabaseSync } from "node:sqlite";
 import { randomBytes, createHash } from "node:crypto";
 import { join } from "node:path";
-import { mkdirSync, chmodSync } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 const OCP_DIR = join(homedir(), ".ocp");
-mkdirSync(OCP_DIR, { recursive: true, mode: 0o700 });
+mkdirSync(OCP_DIR, { recursive: true });
 // Tighten the directory mode in case it already existed with broader permissions.
 try { chmodSync(OCP_DIR, 0o700); } catch { /* ignore EPERM on pre-existing dirs */ }
 const DB_PATH = join(OCP_DIR, "ocp.db");
 let db;
@@ -20,8 +18,6 @@ export function getDb() {
    db.exec("PRAGMA journal_mode = WAL");
    db.exec("PRAGMA foreign_keys = ON");
    initSchema();
    // Tighten mode on the DB file (0600) after creation / first open.
    try { chmodSync(DB_PATH, 0o600); } catch { /* ignore — same-user access still works */ }
  }
  return db;
 }
@@ -1,33 +0,0 @@
 /**
 * OCP shared constants — single source of truth.
 *
 * Any literal that appears in more than one place across server.mjs, setup.mjs,
 * scripts/* belongs here so port-drift / URL-drift cascades cannot recur.
 *
 * Background: from 2026-05-08 (PR #71 dogfood accident) through 2026-05-13
 * (v3.16.3) a single hardcoded "3478" in scripts/upgrade.mjs + scripts/doctor.mjs
 * cascaded into every downstream config write, ultimately taking out the
 * OpenClaw "大内总管" Telegram agent. See CHANGELOG v3.16.2 and v3.16.3.
 *
 * Adding a new constant: prefer ALL_CAPS_SNAKE_CASE. Document the consumers.
 * If a literal is referenced from a shell script (ocp, ocp-connect, setup.sh)
 * that can't import .mjs, add a `// keep in sync with lib/constants.mjs` note
 * at the shell-script reference; CI grep prevents drift.
 */
 // Default TCP port the OCP HTTP proxy listens on. Set by env CLAUDE_PROXY_PORT
 // at runtime; this is the fallback when env is unset.
 // Consumers: server.mjs, setup.mjs, scripts/upgrade.mjs, scripts/doctor.mjs,
 // scripts/sync-openclaw.mjs. Shell scripts ocp / ocp-connect keep the literal
 // "3456" in sync with this value (see CI gate in .github/workflows/alignment.yml).
 export const DEFAULT_PORT = 3456;
 // Localhost bind for client-side fetches (curl, health checks).
 export const LOCAL_HOST = "127.0.0.1";
 // OpenAI-compatible API base path appended to the proxy URL.
 export const OPENAI_API_BASE = "/v1";
 // Convenience: full local URL the OCP proxy listens on by default.
 // scripts that want to probe locally can use this directly.
 export const LOCAL_PROXY_URL = `http://${LOCAL_HOST}:${DEFAULT_PORT}`;
@@ -692,35 +692,25 @@ for e in d.get('errors', []):
 # ── update ──────────────────────────────────────────────────────────────
 cmd_update_help() {
  cat <<'EOF'
-ocp update — Smart upgrade dispatcher
+ocp update — Update OCP to the latest version
-Runs `ocp doctor` internally to choose the right path:
+Pulls the latest code from GitHub, restarts the proxy service,
-  • Patch bump (same minor):     light path (git pull + npm install + restart)
+and optionally syncs the plugin to the OpenClaw extensions directory.
  • Cross-minor (e.g. v3.10→v3.14): full path with snapshot + post-flight
  • Old version (< v3.4.0):       fresh-install (asks first; AI passes --yes)
 Usage:
-  ocp update                          Smart auto-pick path
+  ocp update             Pull latest and restart
-  ocp update --check                  Show available updates, don't apply
+  ocp update --check     Check for updates without applying
  ocp update --dry-run                Preview the plan, don't mutate
  ocp update --target v3.13.0         Pin a specific version
  ocp update --yes                    Skip y/N prompts (AI agents pass this)
  ocp update --rollback               Restore the most recent upgrade snapshot
  ocp update --rollback --list        List available snapshots
  ocp update --rollback <path>        Restore a specific snapshot
  ocp update --rollback --dry-run     Preview rollback plan
  ocp update --rollback --gc          Delete old snapshots (keep last 5, or <30 days)
  ocp update --rollback --gc --dry-run    Preview what would be deleted
 EOF
 }
 cmd_update() {
  local script_dir self
  self="${BASH_SOURCE[0]}"
  # Resolve symlinks (e.g. ~/.local/bin/ocp → real location)
  while [[ -L "$self" ]]; do self="$(readlink "$self")"; done
  script_dir="$(cd "$(dirname "$self")" && pwd)"
-  # Pass through --check fast path (existing behaviour)
+  # Check-only mode
  if [[ "${1:-}" == "--check" ]]; then
    cd "$script_dir"
    git fetch origin main --quiet 2>/dev/null || true
@@ -737,104 +727,71 @@ cmd_update() {
      echo "  Status:   ✓ Up to date"
    else
      echo "  Status:   $behind commit(s) behind"
      echo ""
      echo "  Run 'ocp update' to apply."
    fi
    return 0
  fi
-  # Rollback path
+  echo "Updating OCP..."
-  if [[ "${1:-}" == "--rollback" ]]; then
+  echo ""
    shift
    exec node "$script_dir/scripts/upgrade.mjs" --rollback "$@"
  fi
-  # Doctor-driven path selection
+  # 1. Pull latest
  local kind
  kind=$(node "$script_dir/scripts/doctor.mjs" --json 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin)['next_action']['kind'])" 2>/dev/null || echo "unknown")
  case "$kind" in
    noop)
      echo "Already at latest. Nothing to do."
      return 0
      ;;
    update)
      _cmd_update_light "$script_dir"
      ;;
    upgrade|fresh_install)
      exec node "$script_dir/scripts/upgrade.mjs" "$@"
      ;;
    fix_oauth|fix_service)
      echo "Pre-upgrade check failed: $kind"
      echo "Run \`ocp doctor\` for details and ai_executable steps."
      return 1
      ;;
    *)
      echo "Unknown doctor kind: $kind. Run \`ocp doctor --json\` to inspect."
      return 1
      ;;
  esac
 }
 # Existing light-path body extracted into a helper so cmd_update can call it conditionally.
 _cmd_update_light() {
  local script_dir="$1"
  echo "Updating OCP (light path)..."
  cd "$script_dir"
-  local old_ver new_ver
+  local old_ver
  old_ver=$(python3 -c "import json; print(json.load(open('package.json'))['version'])" 2>/dev/null || echo "?")
  echo "  Pulling latest from GitHub..."
  if ! git pull origin main --ff-only 2>&1 | sed 's/^/    /'; then
    echo "  ✗ Git pull failed. Resolve conflicts manually in: $script_dir"
    return 1
  fi
  local new_ver
  new_ver=$(python3 -c "import json; print(json.load(open('package.json'))['version'])" 2>/dev/null || echo "?")
  if [[ "$old_ver" == "$new_ver" ]]; then
    echo "  ✓ Already at latest (v$new_ver)"
  else
    echo "  ✓ Updated v$old_ver → v$new_ver"
  fi
-  # Sync plugin (existing logic preserved)
+  # 2. Sync plugin to extensions dir
  local ext_dir="$HOME/.openclaw/extensions/ocp"
  if [[ -d "$ext_dir" && -d "$script_dir/ocp-plugin" ]]; then
    echo ""
    echo "  Syncing OCP plugin..."
    cp "$script_dir/ocp-plugin/index.js" "$ext_dir/index.js" 2>/dev/null
    cp "$script_dir/ocp-plugin/package.json" "$ext_dir/package.json" 2>/dev/null
    cp "$script_dir/ocp-plugin/openclaw.plugin.json" "$ext_dir/openclaw.plugin.json" 2>/dev/null
-    echo "  ✓ Plugin synced"
+    echo "  ✓ Plugin synced to $ext_dir"
  fi
  # 3. Sync OpenClaw registry from models.json (non-fatal)
  if command -v node >/dev/null 2>&1 && [[ -f "$script_dir/scripts/sync-openclaw.mjs" ]]; then
    echo ""
    echo "  Syncing OpenClaw registry..."
-    node "$script_dir/scripts/sync-openclaw.mjs" 2>&1 | sed 's/^/    /' || echo "  ⚠ OpenClaw sync failed (non-fatal)"
+    if ! node "$script_dir/scripts/sync-openclaw.mjs" 2>&1 | sed 's/^/  /'; then
      echo "  ⚠ OpenClaw sync failed (non-fatal, continuing)"
    fi
  fi
  # 4. Restart proxy
  echo ""
  echo "  Restarting proxy..."
  cmd_restart > /dev/null 2>&1
-}
+  sleep 2
-cmd_doctor_help() {
+  if curl -sf --max-time 5 "$PROXY/health" > /dev/null 2>&1; then
-  cat <<'EOF'
+    local running_ver
-ocp doctor — Health & upgrade-readiness check
+    running_ver=$(curl -sf --max-time 5 "$PROXY/health" | python3 -c "import sys,json; print(json.loads(sys.stdin.read())['version'])" 2>/dev/null || echo "?")
    echo "  ✓ Proxy running (v$running_ver)"
  else
    echo "  ⚠ Proxy not responding — check: ocp health"
  fi
-Runs a series of checks (Node version, git state, service health,
+  echo ""
-OAuth token, plist customisation, OpenClaw provider) and emits either
+  echo "Done."
 human-readable PASS/WARN/FAIL output or a JSON next_action that
 AI agents can execute.
 Usage:
  ocp doctor              Human-readable output
  ocp doctor --json       JSON for AI agents and ocp update internal use
  ocp doctor --check oauth    Fast path: OAuth check only
 EOF
 }
 cmd_doctor() {
  local script_dir self
  self="${BASH_SOURCE[0]}"
  while [[ -L "$self" ]]; do self="$(readlink "$self")"; done
  script_dir="$(cd "$(dirname "$self")" && pwd)"
  exec node "$script_dir/scripts/doctor.mjs" "$@"
 }
 # ── help ─────────────────────────────────────────────────────────────────
@@ -902,7 +859,6 @@ case "$subcmd" in
  lan)      cmd_lan ;;
  connect)  cmd_connect "$@" ;;
  restart)  cmd_restart "${1:-}" ;;
-  doctor)   cmd_doctor "$@" ;;
+  update)   cmd_update "${1:-}" ;;
  update)   cmd_update "$@" ;;
  *)        echo "Unknown command: $subcmd"; echo ""; cmd_help; exit 1 ;;
 esac
@@ -582,19 +582,11 @@ print(k if k else '')
  if [[ "${SHELL:-}" == */fish ]]; then
    echo "  Note: fish shell detected. Writing to ~/.bashrc — add to fish config manually."
    rc_files+=("$HOME/.bashrc")
  elif $is_mac; then
    # macOS: default shell since Catalina (2019) is zsh.
    # Always write ~/.zshrc (create if absent — zsh tolerates an empty file).
    # Only write ~/.bashrc if it already exists (don't surprise users with new files).
    [[ -f "$HOME/.bashrc" ]] && rc_files+=("$HOME/.bashrc")
    # zshrc: always include on macOS; create the file if it doesn't exist yet
    [[ -f "$HOME/.zshrc" ]] || touch "$HOME/.zshrc"
    rc_files+=("$HOME/.zshrc")
  else
-    # Linux / other: write to whichever rc files already exist or match current shell
+    # Always write both on macOS (default shell is zsh but some tools source bashrc)
    [[ -f "$HOME/.bashrc" || "${SHELL:-}" == */bash ]] && rc_files+=("$HOME/.bashrc")
    [[ -f "$HOME/.zshrc" || "${SHELL:-}" == */zsh ]] && rc_files+=("$HOME/.zshrc")
-    # If neither exists, fall back to creating one for the current shell
+    # If neither exists, create for current shell
    [[ ${#rc_files[@]} -eq 0 ]] && rc_files+=("$HOME/.${SHELL##*/}rc")
  fi
@@ -713,9 +705,7 @@ PYEOF
  echo ""
  echo "  Done. Reload your shell to apply:"
  for rc_file in "${rc_files[@]}"; do
  echo "    source $rc_file"
  done
 }
 main "$@"
@@ -1,19 +1,9 @@
 /**
 * OCP Plugin — registers /ocp as a native slash command in OpenClaw gateway.
- * Calls the local claude-proxy and formats the response.
+ * Calls the local claude-proxy at http://127.0.0.1:3456 and formats the response.
 *
 * Port resolution (in priority order):
 *   1. OCP_PROXY_URL env (full URL, e.g. http://10.0.0.5:3456)
 *   2. CLAUDE_PROXY_PORT env (port only; localhost assumed)
 *   3. Fallback: http://127.0.0.1:3456 (OCP server source default since v1.0)
 *
 * If a particular host's OCP plist injects a non-default CLAUDE_PROXY_PORT,
 * the OpenClaw launchd plist for that host must also inject the same
 * CLAUDE_PROXY_PORT into the plugin's env, or the plugin will fall back to
 * 3456 and miss the server.
 */
-const PROXY = process.env.OCP_PROXY_URL
+
-  || (process.env.CLAUDE_PROXY_PORT ? `http://127.0.0.1:${process.env.CLAUDE_PROXY_PORT}` : "http://127.0.0.1:3456");
+const PROXY = "http://127.0.0.1:3456";
 // Wrap output in monospace code block for Telegram/Discord alignment
 function mono(text) { return "```\n" + text + "\n```"; }
@@ -2,7 +2,7 @@
  "id": "ocp",
  "name": "OCP Commands",
  "description": "Slash commands for the OpenClaw Proxy — /ocp usage, /ocp settings, /ocp health, etc.",
-  "version": "3.16.2",
+  "version": "3.12.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
@@ -10,7 +10,7 @@
      "proxyUrl": {
        "type": "string",
        "default": "http://127.0.0.1:3456",
-        "description": "URL of the Claude proxy. Overridable via OCP_PROXY_URL or CLAUDE_PROXY_PORT env."
+        "description": "URL of the Claude proxy"
      }
    }
  }
@@ -1,6 +1,6 @@
 {
  "name": "open-claude-proxy",
-  "version": "3.16.4",
+  "version": "3.13.0",
  "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.",
  "type": "module",
  "bin": {
@@ -1,301 +0,0 @@
 #!/usr/bin/env node
 /**
 * scripts/doctor.mjs — OCP health & upgrade-readiness check.
 *
 * Usage:
 *   ocp doctor                  human-readable PASS/WARN/FAIL
 *   ocp doctor --json           machine-readable JSON for AI agents + ocp update
 *   ocp doctor --check oauth    fast path: only OAuth check
 *
 * Exit codes:
 *   0  all PASS or WARN-only
 *   1  any FAIL
 */
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { DEFAULT_PORT } from "../lib/constants.mjs";
 const SCHEMA_VERSION = "1";
 function semverParts(v) {
  const m = String(v).replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
  if (!m) return null;
  return { major: +m[1], minor: +m[2], patch: +m[3] };
 }
 function semverCompare(a, b) {
  const A = semverParts(a), B = semverParts(b);
  if (!A || !B) return 0;
  if (A.major !== B.major) return A.major - B.major;
  if (A.minor !== B.minor) return A.minor - B.minor;
  return A.patch - B.patch;
 }
 export async function runDoctor(opts = {}) {
  const checks = [];
  const push = (id, level, message, extra = {}) =>
    checks.push({ id, level, message, ...extra });
  // --- fast path: --check oauth ---
  if (opts.checkOnly === "oauth") {
    return runOauthOnly(opts, checks, push);
  }
  // --- version detection ---
  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
  let currentVersion = opts.mockVersion;
  if (!currentVersion) {
    try {
      const pkg = JSON.parse(readFileSync(join(ocpDir, "package.json"), "utf8"));
      currentVersion = `v${pkg.version}`;
    } catch {
      currentVersion = "unknown";
    }
  }
  // Resolve latest from origin/main (cheap: `git show origin/main:package.json`).
  // Falls back to current_version when network/git unavailable, so kind = noop instead
  // of recommending a downgrade against a stale hardcoded value.
  let latestVersion = opts.mockLatest;
  if (!latestVersion) {
    try {
      const out = execSync(`git -C ${ocpDir} show origin/main:package.json 2>/dev/null`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
      const remotePkg = JSON.parse(out);
      latestVersion = `v${remotePkg.version}`;
    } catch {
      latestVersion = currentVersion;
    }
  }
  push("current_version", "PASS", `current=${currentVersion}`);
  // --- from-version supported? ---
  const fromSupported = !!semverParts(currentVersion) && semverCompare(currentVersion, "v3.4.0") >= 0;
  push("from_version_supported", fromSupported ? "PASS" : "FAIL",
       fromSupported ? "≥ v3.4.0" : `${currentVersion} < v3.4.0; in-place upgrade not supported`);
  // --- service health check (mockable) ---
  let healthOk = true, oauthOk = true;
  if (!opts.skipNetwork) {
    let health;
    if (opts.mockHealth !== undefined) {
      health = opts.mockHealth;
    } else {
      try {
        const port = process.env.CLAUDE_PROXY_PORT || String(DEFAULT_PORT);
        const out = execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/health`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
        health = { status: 200, body: JSON.parse(out) };
      } catch (e) {
        health = { error: String(e.message || e) };
      }
    }
    if (health.error || health.status !== 200) {
      healthOk = false;
      push("service_running", "FAIL", `service unreachable: ${health.error || `status ${health.status}`}`);
    } else if (!health.body || typeof health.body !== "object") {
      healthOk = false;
      push("service_running", "FAIL", "service /health returned 200 but empty/non-JSON body");
    } else {
      push("service_running", "PASS", "service responding on /health");
      const authOk = health.body?.auth?.ok;
      if (!authOk) {
        oauthOk = false;
        push("oauth_ok", "FAIL", `auth.ok=false: ${health.body?.auth?.message || "unknown"}`);
      } else {
        push("oauth_ok", "PASS", "OAuth token valid");
      }
    }
  }
  // --- determine next_action.kind (priority: fresh_install > fix_service > fix_oauth > noop > update > upgrade) ---
  let kind;
  if (!fromSupported) {
    kind = "fresh_install";
  } else if (!opts.skipNetwork && !healthOk) {
    kind = "fix_service";
  } else if (!opts.skipNetwork && !oauthOk) {
    kind = "fix_oauth";
  } else {
    const cur = semverParts(currentVersion), lat = semverParts(latestVersion);
    if (!cur) {
      kind = "fresh_install";
    } else if (semverCompare(currentVersion, latestVersion) === 0) {
      kind = "noop";
    } else if (lat && cur.major === lat.major && cur.minor === lat.minor) {
      kind = "update";
    } else {
      kind = "upgrade";
    }
  }
  // --- next_action shape ---
  let next_action;
  if (kind === "fresh_install") {
    next_action = {
      kind,
      human_required: ["claude auth login (only if OAuth becomes invalid after reinstall)"],
      ai_executable: [
        `launchctl bootout gui/$(id -u)/ai.openclaw.proxy 2>/dev/null || true`,
        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
        `mv ${join(homedir(), ".ocp")} ${join(homedir(), ".ocp.backup-")}$(date +%s) 2>/dev/null || true`,
        `rm -rf ${ocpDir}`,
        `git clone https://github.com/dtzp555-max/ocp ${ocpDir}`,
        `cd ${ocpDir} && npm install --no-audit --no-fund && node setup.mjs`,
        `${ocpDir}/ocp doctor`
      ],
      verify: "ocp doctor expects PASS on all checks"
    };
  } else if (kind === "noop") {
    next_action = { kind, human_required: [], ai_executable: [], verify: "already at latest" };
  } else if (kind === "fix_oauth") {
    next_action = {
      kind,
      human_required: [],
      ai_executable: [
        `cd "$(npm root -g)/@anthropic-ai/claude-code" && node install.cjs`,
        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
        `${ocpDir}/ocp doctor`
      ],
      verify: "ocp doctor expects oauth_ok=PASS",
      reference: "~/.cc-rules/memory/learnings/ocp_claude_native_binary_postinstall.md"
    };
  } else if (kind === "fix_service") {
    next_action = {
      kind,
      human_required: [],
      ai_executable: [
        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
        `${ocpDir}/ocp doctor`
      ],
      verify: "ocp doctor expects service_running=PASS"
    };
  } else {
    next_action = {
      kind,
      human_required: [],
      ai_executable: [`${ocpDir}/ocp update --yes`],
      verify: "ocp doctor expects PASS on all checks"
    };
  }
  const fail_count = checks.filter(c => c.level === "FAIL").length;
  const warn_count = checks.filter(c => c.level === "WARN").length;
  return {
    schema_version: SCHEMA_VERSION,
    timestamp: new Date().toISOString(),
    ready_to_upgrade: fail_count === 0,
    current_version: currentVersion,
    latest_version: latestVersion,
    from_version_supported: fromSupported,
    fail_count,
    warn_count,
    checks,
    next_action
  };
 }
 function runOauthOnly(opts, checks, push) {
  let healthOk = true, oauthOk = true;
  let health;
  if (opts.mockHealth !== undefined) {
    health = opts.mockHealth;
  } else {
    try {
      const port = process.env.CLAUDE_PROXY_PORT || String(DEFAULT_PORT);
      const out = execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/health`, { stdio: ["pipe", "pipe", "pipe"] }).toString();
      health = { status: 200, body: JSON.parse(out) };
    } catch (e) {
      health = { error: String(e.message || e) };
    }
  }
  if (health.error || health.status !== 200) {
    healthOk = false;
    push("oauth_ok", "FAIL", `service unreachable: ${health.error || `status ${health.status}`}`);
  } else if (!health.body || typeof health.body !== "object") {
    healthOk = false;
    push("oauth_ok", "FAIL", "service /health returned 200 but empty/non-JSON body");
  } else if (!health.body?.auth?.ok) {
    oauthOk = false;
    push("oauth_ok", "FAIL", `auth.ok=false: ${health.body?.auth?.message || "unknown"}`);
  } else {
    push("oauth_ok", "PASS", "OAuth token valid");
  }
  const kind = !healthOk ? "fix_service" : !oauthOk ? "fix_oauth" : "noop";
  let next_action;
  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
  if (kind === "noop") {
    next_action = { kind, human_required: [], ai_executable: [], verify: "OAuth healthy" };
  } else if (kind === "fix_oauth") {
    next_action = {
      kind,
      human_required: [],
      ai_executable: [
        `cd "$(npm root -g)/@anthropic-ai/claude-code" && node install.cjs`,
        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
        `${ocpDir}/ocp doctor --check oauth`
      ],
      verify: "ocp doctor --check oauth expects PASS",
      reference: "~/.cc-rules/memory/learnings/ocp_claude_native_binary_postinstall.md"
    };
  } else {
    next_action = {
      kind,
      human_required: [],
      ai_executable: [
        `launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`,
        `launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`,
        `${ocpDir}/ocp doctor --check oauth`
      ],
      verify: "ocp doctor --check oauth expects service_running=PASS"
    };
  }
  const fail_count = checks.filter(c => c.level === "FAIL").length;
  // "skipped" = --check oauth fast path intentionally omits version detection.
  // AI agents should NOT semver-compare against current_version/latest_version when
  // either equals "skipped"; the full path provides those fields when needed.
  return {
    schema_version: SCHEMA_VERSION,
    timestamp: new Date().toISOString(),
    ready_to_upgrade: fail_count === 0,
    current_version: opts.mockVersion || "skipped",
    latest_version: opts.mockLatest || "skipped",
    from_version_supported: true,
    fail_count,
    warn_count: 0,
    checks,
    next_action
  };
 }
 // CLI entrypoint — use fileURLToPath + realpath to handle symlinked install paths
 // (e.g. /tmp/ → /private/tmp/ on macOS would otherwise miss the guard).
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 function _isMain() {
  if (!process.argv[1]) return false;
  try {
    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
  } catch { return false; }
 }
 if (_isMain()) {
  const wantJson = process.argv.includes("--json");
  const checkIdx = process.argv.indexOf("--check");
  const checkOnly = checkIdx !== -1 ? process.argv[checkIdx + 1] : undefined;
  const result = await runDoctor({ checkOnly });
  if (wantJson) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(`OCP doctor — ${result.current_version} → ${result.latest_version}`);
    for (const c of result.checks) console.log(`  [${c.level}] ${c.id}: ${c.message}`);
    console.log(`\nSummary: ${result.fail_count} FAIL, ${result.warn_count} WARN`);
    console.log(`Next action: ${result.next_action.kind}`);
  }
  process.exit(result.fail_count === 0 ? 0 : 1);
 }
@@ -1,86 +0,0 @@
 // scripts/lib/plist-merge.mjs
 //
 // Preserves user-customised env vars when setup.mjs rewrites the unit file.
 //
 // Rule:
 //   - keys present in NEW template → template value wins (template is source of truth)
 //   - keys ONLY in EXISTING (not in template) → preserved verbatim
 //
 // No new dependencies — regex-based, plist <key>X</key><string>Y</string> shape
 // is stable enough for our hand-written templates in setup.mjs.
 const PLIST_KV_RE = /<key>([^<]+)<\/key>\s*<string>([^<]*)<\/string>/g;
 export function parsePlistEnv(plistContent) {
  if (!plistContent) return {};
  if (Buffer.isBuffer(plistContent)) plistContent = plistContent.toString("utf8");
  // Restrict to the EnvironmentVariables dict to avoid catching Label, etc.
  const envBlock = plistContent.match(/<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/);
  if (!envBlock) return {};
  const out = {};
  let m;
  PLIST_KV_RE.lastIndex = 0;
  while ((m = PLIST_KV_RE.exec(envBlock[1])) !== null) {
    out[m[1]] = m[2];
  }
  return out;
 }
 export function mergePlistEnv(existing, template) {
  if (!existing) return template;
  const existingEnv = parsePlistEnv(existing);
  const templateEnv = parsePlistEnv(template);
  const KNOWN = new Set(Object.keys(templateEnv));
  const preserved = {};
  for (const [k, v] of Object.entries(existingEnv)) {
    if (!KNOWN.has(k)) preserved[k] = v;
  }
  if (Object.keys(preserved).length === 0) return template;
  const lines = Object.entries(preserved)
    .map(([k, v]) => `    <key>${k}</key>\n    <string>${v}</string>`)
    .join("\n");
  // Inject before the closing </dict> of EnvironmentVariables
  return template.replace(
    /(<key>EnvironmentVariables<\/key>\s*<dict>[\s\S]*?)(\n\s*<\/dict>)/,
    `$1\n${lines}$2`
  );
 }
 const SYSTEMD_KV_RE = /^Environment=([^=]+)=(.*)$/gm;
 export function parseSystemdEnv(serviceContent) {
  if (!serviceContent) return {};
  if (Buffer.isBuffer(serviceContent)) serviceContent = serviceContent.toString("utf8");
  const out = {};
  let m;
  SYSTEMD_KV_RE.lastIndex = 0;
  while ((m = SYSTEMD_KV_RE.exec(serviceContent)) !== null) {
    out[m[1]] = m[2];
  }
  return out;
 }
 export function mergeSystemdEnv(existing, template) {
  if (!existing) return template;
  const existingEnv = parseSystemdEnv(existing);
  const templateEnv = parseSystemdEnv(template);
  const KNOWN = new Set(Object.keys(templateEnv));
  const preservedLines = Object.entries(existingEnv)
    .filter(([k]) => !KNOWN.has(k))
    .map(([k, v]) => `Environment=${k}=${v}`);
  if (preservedLines.length === 0) return template;
  // Guard: if template has no Environment= anchor, cannot inject — return template as-is.
  // (In practice the OCP systemd template always has Environment= lines.)
  if (!/^Environment=/m.test(template)) return template;
  // Inject after the last existing Environment= line in the template
  return template.replace(
    /(^Environment=[^\n]+\n)((?!Environment=).*$)/ms,
    `$1${preservedLines.join("\n")}\n$2`
  );
 }
@@ -1,115 +0,0 @@
 import { mkdirSync, writeFileSync, readFileSync, copyFileSync, existsSync, readdirSync, statSync, rmSync } from "node:fs";
 import { join } from "node:path";
 export function writeSnapshot({ homeDir, fromCommit, fromVersion, toVersion, extraFiles = [] }) {
  const ts = new Date().toISOString().replace(/\.\d+Z$/, "Z");
  const root = join(homeDir, ".ocp", `upgrade-snapshot-${ts}`);
  mkdirSync(root, { recursive: true });
  // Standard manifest files
  writeFileSync(join(root, "from-commit.txt"), fromCommit + "\n");
  writeFileSync(join(root, "from-version.txt"), fromVersion + "\n");
  writeFileSync(join(root, "to-version.txt"), toVersion + "\n");
  // Optional captures (best-effort, never fatal)
  const tryCopy = (src, dst) => {
    try {
      if (existsSync(src)) copyFileSync(src, dst);
    } catch (err) {
      console.error(`[snapshot] warn: could not copy ${src} (${err.code || err.message})`);
    }
  };
  tryCopy(join(homeDir, "Library", "LaunchAgents", "dev.ocp.proxy.plist"), join(root, "plist"));
  tryCopy(join(homeDir, ".config", "systemd", "user", "ocp-proxy.service"), join(root, "service"));
  tryCopy(join(homeDir, ".ocp", "ocp.db"), join(root, "db.bak"));
  tryCopy(join(homeDir, ".ocp", "admin-key"), join(root, "admin-key"));
  tryCopy(join(homeDir, ".openclaw", "openclaw.json"), join(root, "openclaw.json"));
  for (const { src, name } of extraFiles) tryCopy(src, join(root, name));
  return root;
 }
 export function readSnapshot(snapshotPath) {
  const read = (n) => {
    try { return readFileSync(join(snapshotPath, n), "utf8").trim(); } catch { return null; }
  };
  return {
    path: snapshotPath,
    fromCommit: read("from-commit.txt"),
    fromVersion: read("from-version.txt"),
    toVersion: read("to-version.txt")
  };
 }
 export function listSnapshots(homeDir) {
  const root = join(homeDir, ".ocp");
  if (!existsSync(root)) return [];
  return readdirSync(root)
    .filter(name => name.startsWith("upgrade-snapshot-"))
    .map(name => ({ name, path: join(root, name), mtime: statSync(join(root, name)).mtimeMs }))
    .sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
 * Garbage-collect old upgrade snapshots.
 *
 * Retention rule (a snapshot is KEPT if any of these is true):
 *   - It is among the last `keepCount` snapshots (sorted oldest→newest)
 *   - Its timestamp is within `keepDays` of `now`
 *   - It is the single most-recent snapshot (always-keep safety net)
 *
 * @param {string} homeDir - Root containing ~/.ocp/
 * @param {object} opts
 * @param {number} [opts.keepCount=5] - Minimum count to keep
 * @param {number} [opts.keepDays=30] - Keep snapshots newer than N days
 * @param {boolean} [opts.dryRun=false] - If true, report plan but don't delete
 * @param {Date} [opts.now=new Date()] - Override clock for testing
 * @returns {{kept: Array, removed: Array, dryRun: boolean}}
 */
 export function gcSnapshots(homeDir, opts = {}) {
  const keepCount = opts.keepCount ?? 5;
  const keepDays = opts.keepDays ?? 30;
  const dryRun = !!opts.dryRun;
  const now = opts.now || new Date();
  const all = listSnapshots(homeDir);  // sorted oldest→newest
  if (all.length === 0) return { kept: [], removed: [], dryRun };
  if (all.length === 1) return { kept: all, removed: [], dryRun };  // always keep most recent
  const cutoffMs = now.getTime() - keepDays * 24 * 60 * 60 * 1000;
  const lastN = new Set(all.slice(-keepCount).map(s => s.path));
  const kept = [], removed = [];
  for (let i = 0; i < all.length; i++) {
    const s = all[i];
    const isMostRecent = i === all.length - 1;
    const isInLastN = lastN.has(s.path);
    const isWithinDays = parseSnapshotTimestamp(s.name) >= cutoffMs;
    if (isMostRecent || isInLastN || isWithinDays) {
      kept.push(s);
    } else {
      removed.push(s);
    }
  }
  if (!dryRun) {
    for (const s of removed) {
      try {
        rmSync(s.path, { recursive: true, force: true });
      } catch (err) {
        console.error(`[snapshot] warn: could not remove ${s.path} (${err.code || err.message})`);
      }
    }
  }
  return { kept, removed, dryRun };
 }
 function parseSnapshotTimestamp(name) {
  // upgrade-snapshot-2026-05-11T08:30:00Z → epoch ms
  const m = name.match(/upgrade-snapshot-(.+)$/);
  if (!m) return 0;
  const t = Date.parse(m[1]);
  return Number.isFinite(t) ? t : 0;
 }
@@ -9,7 +9,6 @@ import { readFileSync, writeFileSync, existsSync, copyFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { DEFAULT_PORT, LOCAL_HOST, OPENAI_API_BASE } from "../lib/constants.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = join(__dirname, "..");
@@ -71,7 +70,7 @@ if (!config.models.providers) config.models.providers = {};
 if (!config.models.providers[PROVIDER_NAME]) {
  // First-time registration
  config.models.providers[PROVIDER_NAME] = {
-    baseUrl: `http://${LOCAL_HOST}:${DEFAULT_PORT}${OPENAI_API_BASE}`,
+    baseUrl: "http://127.0.0.1:3456/v1",
    api: "openai-completions",
    authHeader: false,
    models: desiredModels,
@@ -1,345 +0,0 @@
 #!/usr/bin/env node
 /**
 * scripts/upgrade.mjs — OCP unified upgrade dispatcher.
 *
 * Paths:
 *   noop          current == latest, exit 0
 *   light         same major.minor, patch bump only (existing fast path; delegated to bash)
 *   full          cross-minor (snapshot + setup.mjs + post-flight)
 *   fresh_install from-version < v3.4.0 (--yes required for non-interactive)
 *   rollback      restore from snapshot
 */
 import { runDoctor } from "./doctor.mjs";
 import { execSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { existsSync, copyFileSync } from "node:fs";
 import { writeSnapshot, listSnapshots, readSnapshot, gcSnapshots } from "./lib/snapshot.mjs";
 import { DEFAULT_PORT } from "../lib/constants.mjs";
 export async function runUpgrade(opts = {}) {
  const dryRun = !!opts.dryRun;
  const yes = !!opts.yes;
  // yes is reserved for Bundle 3 (fresh-install / rollback interactive gate); not used in upgrade-path here.
  const plan = [];
  // --- rollback path (no doctor needed; snapshot is authoritative) ---
  if (opts.rollback) {
    return await runRollback(opts);
  }
  // --- doctor pre-flight ---
  const doctor = opts.mockDoctor || await runDoctor();
  if (!doctor.ready_to_upgrade && doctor.next_action.kind !== "fresh_install") {
    throw new Error(`doctor FAIL: ${doctor.next_action.kind} (run "ocp doctor" for details)`);
  }
  const kind = doctor.next_action.kind;
  plan.push(`[doctor] from=${doctor.current_version} to=${doctor.latest_version} kind=${kind}`);
  // --- noop ---
  if (kind === "noop") {
    plan.push(`[noop] already at latest (${doctor.latest_version})`);
    return { path: "noop", executed: true, changed: false, plan };
  }
  // --- dry-run early exit ---
  if (dryRun) {
    plan.push(`[plan] would proceed with ${kind} path`);
    if (kind === "upgrade") {
      plan.push(`[plan] phase 1: snapshot to ~/.ocp/upgrade-snapshot-<ts>/`);
      plan.push(`[plan] phase 2: git checkout ${doctor.latest_version} && npm install`);
      plan.push(`[plan] phase 3: node setup.mjs`);
      plan.push(`[plan] phase 4: launchctl bootout/bootstrap`);
      plan.push(`[plan] phase 5: post-flight /health + /v1/models`);
    } else if (kind === "update") {
      plan.push(`[plan] light path: git pull + npm install + restart`);
    } else if (kind === "fresh_install") {
      plan.push(`[plan] fresh-install ai_executable[]:`);
      for (const cmd of doctor.next_action.ai_executable) plan.push(`  - ${cmd}`);
    }
    return { path: kind, executed: false, plan };
  }
  // --- non-dry-run paths ---
  if (kind === "update") {
    return { path: "update", executed: true, changed: true, plan: [...plan, "[light] delegated to bash cmd_update existing logic"] };
  }
  if (kind === "upgrade") {
    return await runFullUpgrade({ doctor, opts });
  }
  if (kind === "fresh_install") {
    return await runFreshInstall({ doctor, opts });
  }
  throw new Error(`path ${kind} not yet implemented`);
 }
 async function runFullUpgrade({ doctor, opts }) {
  const phases = [];
  let snapshotPath = null;
  const exec = (cmd, label) => {
    if (opts.mockExec) {
      phases.push({ name: label, cmd, status: "skipped-mock" });
      return "";
    }
    try {
      const out = execSync(cmd, { stdio: ["pipe", "pipe", "pipe"] }).toString();
      phases.push({ name: label, cmd, status: "ok" });
      return out;
    } catch (err) {
      const detail = err.stderr?.toString().trim();
      phases.push({ name: label, cmd, status: "fail", stderr: detail });
      throw Object.assign(
        new Error(`phase ${label} failed: ${detail || err.message}`),
        { phases, cmd }
      );
    }
  };
  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
  try {
    // phase 1: pre-flight (doctor already passed; just record)
    phases.push({ name: "pre-flight", status: "ok", note: `kind=upgrade from=${doctor.current_version} to=${doctor.latest_version}` });
    // phase 2: snapshot
    const fromCommit = opts.mockExec
      ? "mock-commit"
      : execSync(`git -C ${ocpDir} rev-parse HEAD`).toString().trim();
    snapshotPath = opts.mockExec
      ? "/tmp/mock-snapshot"
      : writeSnapshot({ homeDir: homedir(), fromCommit, fromVersion: doctor.current_version, toVersion: doctor.latest_version });
    phases.push({ name: "snapshot", path: snapshotPath, status: "ok" });
    // phase 3: fetch + install
    exec(`git -C ${ocpDir} fetch --tags --quiet`, "fetch+install");
    exec(`git -C ${ocpDir} checkout ${doctor.latest_version}`, "fetch+install");
    exec(`npm --prefix ${ocpDir} install --no-audit --no-fund`, "fetch+install");
    // phase 4: reconfigure
    exec(`node ${ocpDir}/setup.mjs`, "reconfigure");
    // phase 5: restart (heads-up note printed before invoking)
    if (!opts.mockExec) {
      console.error(`[heads-up] restarting OCP service in 3s — expect ~5–10s blip on requests in flight.`);
      await new Promise(r => setTimeout(r, 3000));
    }
    if (process.platform === "darwin") {
      exec(`launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`, "restart");
      exec(`launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`, "restart");
    } else {
      exec(`systemctl --user restart ocp-proxy.service`, "restart");
    }
    // phase 6: post-flight (10s budget; skipped under mockExec)
    if (!opts.mockExec) {
      const port = process.env.CLAUDE_PROXY_PORT || String(DEFAULT_PORT);
      let ok = false;
      for (let i = 0; i < 10; i++) {
        try {
          const out = execSync(`curl -sf --max-time 2 http://127.0.0.1:${port}/health`).toString();
          const body = JSON.parse(out);
          if (body.auth?.ok === true) { ok = true; break; }
        } catch { /* retry */ }
        await new Promise(r => setTimeout(r, 1000));
      }
      if (!ok) {
        phases.push({ name: "post-flight", status: "fail", message: "health did not return auth.ok=true within 10s" });
        throw new Error("post-flight failed");
      }
      execSync(`curl -sf --max-time 3 http://127.0.0.1:${port}/v1/models > /dev/null`);
      phases.push({ name: "post-flight", status: "ok" });
    } else {
      phases.push({ name: "post-flight", status: "skipped-mock" });
    }
    // Auto-GC old snapshots after successful upgrade (best-effort, never throws).
    try {
      const gc = gcSnapshots(homedir(), { keepCount: 5, keepDays: 30 });
      if (gc.removed.length > 0) {
        console.error(`[gc] removed ${gc.removed.length} old snapshots; kept ${gc.kept.length}`);
      }
    } catch (e) {
      console.error(`[gc] warn: snapshot GC failed: ${e.message}`);
    }
    return { path: "upgrade", executed: true, changed: true, snapshotPath, phases };
  } catch (err) {
    if (snapshotPath && !err.snapshotPath) {
      Object.assign(err, {
        snapshotPath,
        phases,
        hint: "Working tree may be at new version. Run `ocp update --rollback` to restore from snapshot."
      });
    }
    throw err;
  }
 }
 async function runFreshInstall({ doctor, opts }) {
  if (!opts.yes) {
    throw new Error("fresh_install requires --yes for non-interactive execution (or run interactively and answer y)");
  }
  const steps = [];
  for (const cmd of doctor.next_action.ai_executable) {
    if (opts.mockExec) {
      steps.push({ cmd, status: "skipped-mock" });
    } else {
      try {
        execSync(cmd, { stdio: "inherit" });
        steps.push({ cmd, status: "ok" });
      } catch (e) {
        const detail = e.stderr?.toString().trim() || e.message;
        steps.push({ cmd, status: "fail", error: String(detail) });
        throw Object.assign(new Error(`fresh_install step failed: ${cmd} — ${detail}`), { steps });
      }
    }
  }
  return { path: "fresh_install", executed: true, changed: true, steps };
 }
 async function runRollback(opts) {
  const homeDir = opts.homeDir || homedir();
  const snapshots = opts.mockSnapshots ?? listSnapshots(homeDir);
  if (opts.gc) {
    const result = gcSnapshots(homeDir, { dryRun: opts.dryRun });
    return { path: opts.dryRun ? "rollback-gc-dry-run" : "rollback-gc", ...result };
  }
  if (opts.list) {
    return { path: "rollback-list", snapshots };
  }
  if (snapshots.length === 0) {
    throw new Error("no upgrade snapshots found in ~/.ocp/upgrade-snapshot-*");
  }
  const target = opts.snapshotPath
    ? snapshots.find(s => s.path === opts.snapshotPath)
    : snapshots[snapshots.length - 1];
  if (!target) throw new Error(`snapshot not found: ${opts.snapshotPath} (must be inside ~/.ocp/upgrade-snapshot-*)`);
  const meta = opts.mockSnapshotMeta ?? readSnapshot(target.path);
  if (!meta.fromCommit) throw new Error(`snapshot ${target.path} has no from-commit.txt`);
  const phases = [];
  if (opts.dryRun) {
    return {
      path: "rollback-dry-run",
      executed: false,
      target: target.path,
      plan: [
        `git checkout ${meta.fromCommit}`,
        `cp ${target.path}/plist ~/Library/LaunchAgents/dev.ocp.proxy.plist`,
        `cp ${target.path}/db.bak ~/.ocp/ocp.db`,
        `launchctl bootout/bootstrap`,
        `ocp doctor`
      ]
    };
  }
  if (!opts.yes) throw new Error("rollback requires --yes for non-interactive execution");
  const exec = (cmd, label) => {
    if (opts.mockExec) {
      phases.push({ name: label, cmd, status: "skipped-mock" });
      return "";
    }
    try {
      execSync(cmd, { stdio: ["pipe", "pipe", "pipe"] });
      phases.push({ name: label, cmd, status: "ok" });
    } catch (err) {
      const detail = err.stderr?.toString().trim();
      phases.push({ name: label, cmd, status: "fail", stderr: detail });
      throw Object.assign(
        new Error(`rollback phase ${label} failed: ${detail || err.message}`),
        { phases, target: target.path }
      );
    }
  };
  const ocpDir = opts.ocpDir || join(homedir(), "ocp");
  exec(`git -C ${ocpDir} checkout ${meta.fromCommit}`, "git-checkout");
  if (!opts.mockExec) {
    const tryCopy = (src, dst) => {
      try {
        if (existsSync(src)) copyFileSync(src, dst);
      } catch (err) {
        console.error(`[rollback] warn: could not restore ${src} → ${dst} (${err.code || err.message})`);
      }
    };
    tryCopy(join(target.path, "plist"), join(homeDir, "Library", "LaunchAgents", "dev.ocp.proxy.plist"));
    tryCopy(join(target.path, "service"), join(homeDir, ".config", "systemd", "user", "ocp-proxy.service"));
    tryCopy(join(target.path, "db.bak"), join(homeDir, ".ocp", "ocp.db"));
    tryCopy(join(target.path, "admin-key"), join(homeDir, ".ocp", "admin-key"));
    phases.push({ name: "restore-files", status: "ok" });
  } else {
    phases.push({ name: "restore-files", status: "skipped-mock" });
  }
  exec(`npm --prefix ${ocpDir} install --no-audit --no-fund`, "npm-install");
  if (!opts.mockExec) {
    console.error(`[heads-up] restarting OCP service in 3s — expect ~5–10s blip on requests in flight.`);
    await new Promise(r => setTimeout(r, 3000));
  }
  if (process.platform === "darwin") {
    exec(`launchctl bootout gui/$(id -u)/dev.ocp.proxy 2>/dev/null || true`, "restart");
    exec(`launchctl bootstrap gui/$(id -u) ${join(homedir(), "Library", "LaunchAgents", "dev.ocp.proxy.plist")}`, "restart");
  } else {
    exec(`systemctl --user restart ocp-proxy.service`, "restart");
  }
  return { path: "rollback", executed: true, changed: true, target: target.path, phases };
 }
 // CLI entrypoint — use fileURLToPath + realpath to handle symlinked install paths.
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 function _isMain() {
  if (!process.argv[1]) return false;
  try {
    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
  } catch { return false; }
 }
 if (_isMain()) {
  const args = process.argv.slice(2);
  const dryRun = args.includes("--dry-run");
  const yes = args.includes("--yes");
  const rollback = args.includes("--rollback");
  const list = args.includes("--list");
  const gc = args.includes("--gc");
  const targetIdx = args.indexOf("--target");
  const target = targetIdx !== -1 ? args[targetIdx + 1] : undefined;
  // First non-flag positional after --rollback is the snapshot path
  let snapshotPath;
  if (rollback) {
    const rb = args.indexOf("--rollback");
    const cand = args[rb + 1];
    if (cand && !cand.startsWith("--")) snapshotPath = cand;
  }
  try {
    const result = await runUpgrade({ dryRun, yes, rollback, list, gc, snapshotPath, target });
    if (result.plan) for (const line of result.plan) console.log(line);
    if (result.phases) for (const p of result.phases) console.log(`[${p.name}] ${p.status}${p.cmd ? `: ${p.cmd}` : ""}`);
    if (result.steps) for (const s of result.steps) console.log(`  ${s.status === "ok" ? "✓" : s.status === "skipped-mock" ? "·" : "✗"} ${s.cmd}`);
    if (result.snapshots) {
      console.log(`Found ${result.snapshots.length} snapshots:`);
      for (const s of result.snapshots) console.log(`  ${s.name}`);
    }
    if (result.removed && result.kept) {
      console.log(`Snapshots: kept ${result.kept.length}, ${result.dryRun ? "would remove" : "removed"} ${result.removed.length}`);
      for (const s of result.removed) console.log(`  - ${s.name}`);
    }
    process.exit(0);
  } catch (e) {
    console.error(`✗ ${e.message}`);
    if (e.snapshotPath) console.error(`   snapshot: ${e.snapshotPath}`);
    if (e.target) console.error(`   target: ${e.target}`);
    if (e.hint) console.error(`   hint: ${e.hint}`);
    process.exit(1);
  }
 }
@@ -11,7 +11,7 @@
 * This matches LiteLLM, OpenAI SDK, and other major LLM proxies.
 *
 * Env vars:
- *   CLAUDE_PROXY_PORT            — listen port (default: DEFAULT_PORT from lib/constants.mjs)
+ *   CLAUDE_PROXY_PORT            — listen port (default: 3456)
 *   CLAUDE_BIN                   — path to claude binary (default: auto-detect)
 *   CLAUDE_TIMEOUT               — per-request timeout in ms (default: 600000)
 *   CLAUDE_ALLOWED_TOOLS         — comma-separated tools to allow (default: expanded set)
@@ -30,60 +30,19 @@
 import { createServer } from "node:http";
 import { spawn, execFileSync } from "node:child_process";
 import { randomUUID, timingSafeEqual } from "node:crypto";
-import { readFileSync, readdirSync, accessSync, existsSync, constants, chmodSync, statSync } from "node:fs";
+import { readFileSync, accessSync, existsSync, constants } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { validateKey, recordUsage, getUsageByKey, getUsageTimeline, getRecentUsage, createKey, listKeys, revokeKey, closeDb, checkQuota, updateKeyQuota, getKeyQuota, findKey, cacheHash, getCachedResponse, setCachedResponse, clearCache, getCacheStats, hasCacheControl, singleflight, getInflightStats } from "./keys.mjs";
 import { DEFAULT_PORT } from "./lib/constants.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
 const modelsConfig = JSON.parse(readFileSync(join(__dirname, "models.json"), "utf8"));
 // ── Resolve claude binary ───────────────────────────────────────────────
-// Priority: CLAUDE_BIN env > well-known paths > nvm/fnm/asdf user-local
+// Priority: CLAUDE_BIN env > well-known paths > which lookup
-// installs > which lookup. Fail-fast if not found — never start with an
+// Fail-fast if not found — never start with an unresolvable binary.
 // unresolvable binary.
 function _listVersionDirs(parent) {
  try { return readdirSync(parent); } catch { return []; }
 }
 function _collectNodeManagerCandidates(home) {
  if (!home) return [];
  const out = [];
  // nvm: $HOME/.nvm/versions/node/<version>/bin/claude
  const nvmRoot = join(home, ".nvm/versions/node");
  for (const v of _listVersionDirs(nvmRoot)) {
    out.push(join(nvmRoot, v, "bin/claude"));
  }
  // nvm default alias: resolve $HOME/.nvm/aliases/default if it points to a version
  try {
    const aliasFile = join(home, ".nvm/aliases/default");
    const aliasVer = readFileSync(aliasFile, "utf8").trim();
    if (aliasVer) {
      const direct = join(nvmRoot, aliasVer, "bin/claude");
      if (!out.includes(direct)) out.unshift(direct);
    }
  } catch {}
  // fnm: $HOME/.fnm/node-versions/<version>/installation/bin/claude
  const fnmRoot = join(home, ".fnm/node-versions");
  for (const v of _listVersionDirs(fnmRoot)) {
    out.push(join(fnmRoot, v, "installation/bin/claude"));
  }
  // asdf: $HOME/.asdf/installs/nodejs/<version>/bin/claude
  const asdfRoot = join(home, ".asdf/installs/nodejs");
  for (const v of _listVersionDirs(asdfRoot)) {
    out.push(join(asdfRoot, v, "bin/claude"));
  }
  // npm prefix-relocated: $HOME/.npm-global/bin/claude
  out.push(join(home, ".npm-global/bin/claude"));
  return out;
 }
 function resolveClaude() {
  if (process.env.CLAUDE_BIN) {
    try {
@@ -95,13 +54,11 @@ function resolveClaude() {
    }
  }
  const home = process.env.HOME || "";
  const candidates = [
    "/opt/homebrew/bin/claude",
    "/usr/local/bin/claude",
    "/usr/bin/claude",
-    join(home, ".local/bin/claude"),
+    join(process.env.HOME || "", ".local/bin/claude"),
    ..._collectNodeManagerCandidates(home),
  ];
  for (const p of candidates) {
    try { accessSync(p, constants.X_OK); console.warn(`[init] CLAUDE_BIN not set, resolved to ${p}`); return p; } catch {}
@@ -115,8 +72,6 @@ function resolveClaude() {
  console.error(
    "FATAL: claude binary not found.\n" +
    "  Set CLAUDE_BIN=/path/to/claude or ensure claude is in PATH.\n" +
    "  Hint: if you use nvm/fnm/asdf, set CLAUDE_BIN to the absolute path\n" +
    "  shown by `which claude` in your interactive shell.\n" +
    "  Checked: " + candidates.join(", ")
  );
  process.exit(1);
@@ -124,7 +79,7 @@ function resolveClaude() {
 // ── Configuration ───────────────────────────────────────────────────────
 // Settings marked with `let` can be changed at runtime via PATCH /settings.
-const PORT = parseInt(process.env.CLAUDE_PROXY_PORT || String(DEFAULT_PORT), 10);
+const PORT = parseInt(process.env.CLAUDE_PROXY_PORT || "3456", 10);
 const CLAUDE = resolveClaude();
 let TIMEOUT = parseInt(process.env.CLAUDE_TIMEOUT || "600000", 10);
 const PROXY_API_KEY = process.env.PROXY_API_KEY || "";
@@ -168,44 +123,6 @@ function logEvent(level, event, data = {}) {
  }
 }
 // ── Startup file-mode reconciliation ───────────────────────────────────
 // Idempotently tightens OCP credential-bearing files to 700/600 so that
 // existing installs (created before this fix) are hardened on next restart.
 // Wrapped in try/catch — chmod failure must never crash startup.
 // Does NOT touch systemd units or launchd plists; those are managed by setup.mjs.
 function _tightenFileModesIfPossible() {
  const ocpDir = join(homedir(), ".ocp");
  const targets = [
    { path: ocpDir,                      mode: 0o700, label: "~/.ocp (dir)" },
    { path: join(ocpDir, "admin-key"),   mode: 0o600, label: "~/.ocp/admin-key" },
    { path: join(ocpDir, "ocp.db"),      mode: 0o600, label: "~/.ocp/ocp.db" },
  ];
  let tightened = 0;
  let alreadyOk = 0;
  for (const { path, mode, label } of targets) {
    try {
      const st = statSync(path);
      const current = st.mode & 0o777;
      if (current !== mode) {
        chmodSync(path, mode);
        tightened++;
      } else {
        alreadyOk++;
      }
    } catch (e) {
      if (e.code !== "ENOENT") {
        // File exists but chmod failed (e.g. EPERM) — log and move on
        logEvent("warn", "file_mode_tighten_failed", { path: label, error: e.message });
      }
      // ENOENT is fine — file doesn't exist yet
    }
  }
  if (tightened > 0) {
    logEvent("info", "file_modes_tightened", { tightened, alreadyOk });
  }
 }
 _tightenFileModesIfPossible();
 // ── Circuit breaker (DISABLED) ──────────────────────────────────────────
 // Disabled: CLI proxy has its own retry logic, and the breaker was causing
 // cascading failures — once API got briefly slow, ALL agents lost connectivity
@@ -241,36 +158,25 @@ const MODEL_MAP = Object.fromEntries([
 const MODELS = modelsConfig.models.map(m => ({ id: m.id, name: m.displayName }));
 // ── Session management ──────────────────────────────────────────────────
-// Maps namespaced session keys to Claude CLI session UUIDs.
+// Maps conversation IDs (from caller) to Claude CLI session UUIDs.
 // Key format: "${keyName}|${conversationId}" — prevents cross-key collision
 // when two callers (different API keys or anon + authenticated) use the same
 // session_id string. Anonymous callers use "anon"; admin uses "admin".
 // Enables --resume for multi-turn conversations, reducing token waste.
-const sessions = new Map(); // `${keyName}|${conversationId}` → { uuid, messageCount, lastUsed, model }
+const sessions = new Map(); // conversationId → { uuid, messageCount, lastUsed, model }
 // Build the namespaced key used for all sessions Map operations.
 // Returns null when conversationId is falsy (one-off requests bypass session tracking).
 function _sessionKey(conversationId, keyName) {
  return conversationId ? `${keyName || "anon"}|${conversationId}` : null;
 }
 const sessionCleanupInterval = setInterval(() => {
  const now = Date.now();
  for (const [id, s] of sessions) {
    const idleMs = now - s.lastUsed;
    const ageMs = s.firstSeen ? now - s.firstSeen : null;
    // id is "${keyName}|${conversationId}"; strip prefix for log output
    const convIdShort = id.includes("|") ? id.slice(id.indexOf("|") + 1, id.indexOf("|") + 13) : id.slice(0, 12);
    if (idleMs > SESSION_TTL) {
      sessions.delete(id);
-      console.log(`[session] expired ${convIdShort}... (idle ${Math.round(idleMs / 60000)}m)`);
+      console.log(`[session] expired ${id.slice(0, 12)}... (idle ${Math.round(idleMs / 60000)}m)`);
-      logEvent("info", "session_expired", { conversationId: convIdShort + "...", idleMs, ageMs });
+      logEvent("info", "session_expired", { conversationId: id.slice(0, 12) + "...", idleMs, ageMs });
    } else if (ageMs !== null && ageMs > 4 * SESSION_TTL) {
      // #42 evidence-gathering: a session whose firstSeen is more than 4× TTL old
      // but whose lastUsed keeps getting bumped (never idle long enough to expire)
      // is the suspected bug. Log without action so the pattern can be confirmed
      // in /logs. Do NOT enforce an absolute age cap here speculatively.
-      logEvent("warn", "session_long_lived", { conversationId: convIdShort + "...", idleMs, ageMs });
+      logEvent("warn", "session_long_lived", { conversationId: id.slice(0, 12) + "...", idleMs, ageMs });
    }
  }
 }, 60000);
@@ -477,7 +383,7 @@ function getModelTier(cliModel) {
 // ── Spawn claude CLI (shared setup) ─────────────────────────────────────
 // Resolves session logic, builds CLI args, spawns the process, and sets up
 // timeouts. Returns context object or throws synchronously.
-function spawnClaudeProcess(model, messages, conversationId, keyName) {
+function spawnClaudeProcess(model, messages, conversationId) {
  if (stats.activeRequests >= MAX_CONCURRENT) {
    throw new Error(`concurrency limit reached (${stats.activeRequests}/${MAX_CONCURRENT})`);
  }
@@ -493,11 +399,8 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
  let prompt;
  // ── Session logic ──
-  // sessionKey namespaces the Map key by keyName to prevent cross-caller collision
+  if (conversationId && sessions.has(conversationId)) {
-  // when two callers with different API keys share the same conversationId string.
+    const session = sessions.get(conversationId);
  const sessionKey = _sessionKey(conversationId, keyName);
  if (sessionKey && sessions.has(sessionKey)) {
    const session = sessions.get(sessionKey);
    session.lastUsed = Date.now();
    sessionInfo = { uuid: session.uuid, resume: true };
    stats.sessionHits++;
@@ -508,17 +411,17 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
      : "";
    session.messageCount = messages.length;
-    console.log(`[session] resume conv=${conversationId.slice(0, 12)}... key=${keyName || "anon"} uuid=${session.uuid.slice(0, 8)}... msgs=${messages.length} prompt_chars=${prompt.length}`);
+    console.log(`[session] resume conv=${conversationId.slice(0, 12)}... uuid=${session.uuid.slice(0, 8)}... msgs=${messages.length} prompt_chars=${prompt.length}`);
-  } else if (sessionKey) {
+  } else if (conversationId) {
    const uuid = randomUUID();
    const now = Date.now();
-    sessions.set(sessionKey, { uuid, messageCount: messages.length, firstSeen: now, lastUsed: now, model: cliModel });
+    sessions.set(conversationId, { uuid, messageCount: messages.length, firstSeen: now, lastUsed: now, model: cliModel });
    sessionInfo = { uuid, resume: false };
    stats.sessionMisses++;
    prompt = messagesToPrompt(messages);
-    console.log(`[session] new conv=${conversationId.slice(0, 12)}... key=${keyName || "anon"} uuid=${uuid.slice(0, 8)}... msgs=${messages.length}`);
+    console.log(`[session] new conv=${conversationId.slice(0, 12)}... uuid=${uuid.slice(0, 8)}... msgs=${messages.length}`);
  } else {
    stats.oneOffRequests++;
@@ -563,11 +466,11 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
  proc.once("exit", cleanup);
  function handleSessionFailure() {
-    if (sessionInfo?.resume && sessionKey) {
+    if (sessionInfo?.resume && conversationId) {
      console.warn(`[session] resume failed for ${conversationId.slice(0, 12)}..., removing stale session`);
      logEvent("warn", "session_failure", { mode: "resume", conversationId: conversationId.slice(0, 12) + "...", action: "deleted" });
-      sessions.delete(sessionKey);
+      sessions.delete(conversationId);
-    } else if (sessionInfo && !sessionInfo.resume && sessionKey) {
+    } else if (sessionInfo && !sessionInfo.resume && conversationId) {
      // #41 evidence-gathering: session-create failures currently leave a stale entry
      // in the sessions map. Log without action so the staleness pattern can be
      // confirmed in /logs before any code change. Do NOT delete here speculatively.
@@ -610,11 +513,11 @@ function spawnClaudeProcess(model, messages, conversationId, keyName) {
 // On-demand spawning: each request spawns a fresh `claude -p` process.
 // No pool = no crash loops, no stale workers, no degraded states.
 // Stdin is written immediately so there's no 3s stdin timeout issue.
-function callClaude(model, messages, conversationId, keyName) {
+function callClaude(model, messages, conversationId) {
  return new Promise((resolve, reject) => {
    let ctx;
    try {
-      ctx = spawnClaudeProcess(model, messages, conversationId, keyName);
+      ctx = spawnClaudeProcess(model, messages, conversationId);
    } catch (err) {
      return reject(err);
    }
@@ -694,7 +597,7 @@ function callClaudeStreaming(model, messages, conversationId, res, authInfo = {}
  let ctx;
  try {
-    ctx = spawnClaudeProcess(model, messages, conversationId, authInfo.keyName);
+    ctx = spawnClaudeProcess(model, messages, conversationId);
  } catch (err) {
    return jsonResponse(res, 500, { error: { message: err.message, type: "proxy_error" } });
  }
@@ -1377,7 +1280,7 @@ async function handleChatCompletions(req, res) {
        // will re-read the freshly-populated cache entry here rather than spawning.
        const recheck = getCachedResponse(req._cacheHash, CACHE_TTL);
        if (recheck) return recheck.response;
-        const c = await callClaude(model, messages, conversationId, req._authKeyName);
+        const c = await callClaude(model, messages, conversationId);
        try { setCachedResponse(req._cacheHash, model, c); } catch (e) { logEvent("error", "cache_write_failed", { error: e.message }); }
        return c;
      });
@@ -1399,7 +1302,7 @@ async function handleChatCompletions(req, res) {
  // Fallback: cache disabled (CACHE_TTL=0) or no _cacheHash — original path untouched.
  try {
-    const content = await callClaude(model, messages, conversationId, req._authKeyName);
+    const content = await callClaude(model, messages, conversationId);
    const id = `chatcmpl-${randomUUID()}`;
    completionResponse(res, id, model, content);
    try { recordUsage({ keyId: req._authKeyId, keyName: req._authKeyName, model, promptChars, responseChars: content.length, elapsedMs: Date.now() - t0Usage, success: true }); } catch (e) { logEvent("error", "usage_record_failed", { error: e.message }); }
@@ -1533,10 +1436,8 @@ const server = createServer(async (req, res) => {
    const uptimeMs = Date.now() - START_TIME;
    const sessionList = [];
    for (const [id, s] of sessions) {
      // id is "${keyName}|${conversationId}"; expose only the public-facing conversationId
      const convId = id.includes("|") ? id.slice(id.indexOf("|") + 1) : id;
      sessionList.push({
-        id: convId.slice(0, 12) + "...",
+        id: id.slice(0, 12) + "...",
        model: s.model,
        messages: s.messageCount,
        idleMs: Date.now() - s.lastUsed,
@@ -1581,9 +1482,7 @@ const server = createServer(async (req, res) => {
  if (req.url === "/sessions" && req.method === "GET") {
    const list = [];
    for (const [id, s] of sessions) {
-      // id is "${keyName}|${conversationId}"; expose only the public-facing conversationId
+      list.push({ id, uuid: s.uuid, model: s.model, messages: s.messageCount, lastUsed: new Date(s.lastUsed).toISOString() });
      const convId = id.includes("|") ? id.slice(id.indexOf("|") + 1) : id;
      list.push({ id: convId, uuid: s.uuid, model: s.model, messages: s.messageCount, lastUsed: new Date(s.lastUsed).toISOString() });
    }
    return jsonResponse(res, 200, { sessions: list });
  }
@@ -1673,45 +1572,14 @@ const server = createServer(async (req, res) => {
  }
  if (req.url?.startsWith("/api/usage") && req.method === "GET") {
-    // Least-privilege scope rules (security audit follow-up):
+    if (!isAdmin) return jsonResponse(res, 403, { error: "Admin access required" });
    //   - non-admin authenticated key  → only own rows
    //   - anonymous (PROXY_ANONYMOUS_KEY) → only "anonymous" rows; ?all=true ignored
    //   - admin without ?all=true       → only own ("admin") rows
    //   - admin with    ?all=true       → full byKey/recent (legacy behavior); audited
    // Authenticated callers are required (anyone reaching here passed the auth gate above);
    // remote+no-auth requests would have been rejected before this point.
    const url = new URL(req.url, `http://${BIND_ADDRESS}:${PORT}`);
    const since = url.searchParams.get("since");
    const until = url.searchParams.get("until");
    const wantAll = url.searchParams.get("all") === "true";
    const callerName = req._authKeyName;
    // Anonymous callers may never opt into all-keys view, even if they pass ?all=true.
    const isAnonCaller = callerName === "anonymous";
    const fullScope = isAdmin && wantAll && !isAnonCaller;
    // scopeName === null when fullScope is true (no filter); otherwise the key_name to filter by.
    const scopeName = fullScope ? null : callerName;
    if (fullScope) {
      logEvent("info", "admin_usage_full_scope", { caller: callerName, ip: req.socket.remoteAddress || null });
    }
    const byKeyAll = getUsageByKey({ since, until });
    const recentAll = getRecentUsage(Math.min(parseInt(url.searchParams.get("limit") || "50", 10), 500));
    const timeline = getUsageTimeline({
      keyName: scopeName || undefined,
      hours: Math.min(parseInt(url.searchParams.get("hours") || "24", 10), 720),
    });
    const byKey = scopeName ? byKeyAll.filter((row) => row.key_name === scopeName) : byKeyAll;
    const recent = scopeName ? recentAll.filter((row) => row.key_name === scopeName) : recentAll;
    return jsonResponse(res, 200, {
-      byKey,
+      byKey: getUsageByKey({ since, until }),
-      timeline,
+      timeline: getUsageTimeline({ hours: Math.min(parseInt(url.searchParams.get("hours") || "24", 10), 720) }),
-      recent,
+      recent: getRecentUsage(Math.min(parseInt(url.searchParams.get("limit") || "50", 10), 500)),
      scope: { self: scopeName, all: fullScope },
    });
  }
@@ -3,8 +3,7 @@
 * OCP (Open Claude Proxy) setup
 *
 * Automatically configures OpenClaw to use Claude CLI as a model provider.
- * Run: node setup.mjs [--port N] [--default-model opus|sonnet|haiku] [--dry-run]
+ * Run: node setup.mjs [--port 3456] [--default-model opus|sonnet|haiku] [--dry-run]
 *      (default port = DEFAULT_PORT from lib/constants.mjs)
 *
 * What it does:
 *   1. Verifies claude CLI is installed and authenticated
@@ -13,13 +12,11 @@
 *   4. Creates start.sh for easy launch
 *   5. Optionally starts the proxy
 */
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync, chmodSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync } from "node:fs";
 import { mergePlistEnv, mergeSystemdEnv } from "./scripts/lib/plist-merge.mjs";
 import { execSync } from "node:child_process";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { DEFAULT_PORT } from "./lib/constants.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -34,7 +31,7 @@ const opt = (name, fallback) => {
  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
 };
-const PORT = parseInt(opt("port", String(DEFAULT_PORT)), 10);
+const PORT = parseInt(opt("port", "3456"), 10);
 const DEFAULT_MODEL = opt("default-model", "opus"); // opus | sonnet | haiku
 const DRY_RUN = flag("dry-run");
 const SKIP_START = flag("no-start");
@@ -42,29 +39,6 @@ const PROVIDER_NAME = opt("provider-name", "claude-local");
 const BIND_ADDRESS = opt("bind", "127.0.0.1");
 const AUTH_MODE_CONFIG = opt("auth-mode", "none");
 // ── Service-env injection: CLAUDE_BIN, OCP_ADMIN_KEY, PROXY_ANONYMOUS_KEY ──
 // These are read from the user's shell env at install time and written into
 // the service unit (plist / systemd) so the daemon picks them up on boot.
 // CLAUDE_BIN — detect at install time; omit if not found (server.mjs fallback)
 let CLAUDE_BIN_INJECT = null;
 if (process.env.CLAUDE_BIN) {
  CLAUDE_BIN_INJECT = process.env.CLAUDE_BIN;
 } else {
  try {
    const detected = execSync("which claude 2>/dev/null", { encoding: "utf-8" }).trim();
    if (detected && existsSync(detected)) {
      CLAUDE_BIN_INJECT = detected;
    }
  } catch { /* which not available or claude not on PATH — omit */ }
 }
 // OCP_ADMIN_KEY — omit entirely when empty/unset; don't write empty string
 const OCP_ADMIN_KEY_INJECT = process.env.OCP_ADMIN_KEY || null;
 // PROXY_ANONYMOUS_KEY — same pattern
 const PROXY_ANON_KEY_INJECT = process.env.PROXY_ANONYMOUS_KEY || null;
 // ── Models: derived from models.json (single source of truth) ──────────
 const modelsConfig = JSON.parse(readFileSync(join(__dirname, "models.json"), "utf-8"));
@@ -312,29 +286,6 @@ banner.push(`╚═════════════════════
 console.log("\n" + banner.join("\n") + "\n");
 // ── Step 7: Install auto-start on boot ──────────────────────────────────
 // Log service-env injection plan (shown in both dry-run and live mode)
 console.log("\n🔧 Service unit env vars to inject:\n");
 if (CLAUDE_BIN_INJECT) {
  log(`CLAUDE_BIN: ${CLAUDE_BIN_INJECT}`);
 } else {
  log(`CLAUDE_BIN: (not found — server.mjs will auto-detect at runtime)`);
 }
 if (OCP_ADMIN_KEY_INJECT) {
  log(`OCP_ADMIN_KEY: injected (length: ${OCP_ADMIN_KEY_INJECT.length})`);
 } else {
  log(`OCP_ADMIN_KEY: (unset — admin endpoints disabled)`);
 }
 if (PROXY_ANON_KEY_INJECT) {
  log(`PROXY_ANONYMOUS_KEY: injected (set)`);
 } else {
  log(`PROXY_ANONYMOUS_KEY: (unset — anonymous access disabled)`);
 }
 if (DRY_RUN) {
  console.log("\n  [dry-run] would write service unit with above env vars\n");
 }
 if (!DRY_RUN) {
  console.log("\n🔄 Installing auto-start on login...\n");
@@ -407,13 +358,7 @@ if (!DRY_RUN) {
    <key>CLAUDE_BIND</key>
    <string>${BIND_ADDRESS}</string>
    <key>CLAUDE_AUTH_MODE</key>
-    <string>${AUTH_MODE_CONFIG}</string>${CLAUDE_BIN_INJECT ? `
+    <string>${AUTH_MODE_CONFIG}</string>
    <key>CLAUDE_BIN</key>
    <string>${CLAUDE_BIN_INJECT}</string>` : ""}${OCP_ADMIN_KEY_INJECT ? `
    <key>OCP_ADMIN_KEY</key>
    <string>${OCP_ADMIN_KEY_INJECT}</string>` : ""}${PROXY_ANON_KEY_INJECT ? `
    <key>PROXY_ANONYMOUS_KEY</key>
    <string>${PROXY_ANON_KEY_INJECT}</string>` : ""}
  </dict>
  <key>RunAtLoad</key>
  <true/>
@@ -427,15 +372,8 @@ if (!DRY_RUN) {
 </plist>
 `;
-    const existingPlist = existsSync(plistPath) ? readFileSync(plistPath, "utf8") : null;
+    writeFileSync(plistPath, plistXml);
-    const finalPlistXml = mergePlistEnv(existingPlist, plistXml);
+    log(`Plist written: ${plistPath}`);
    writeFileSync(plistPath, finalPlistXml);
    chmodSync(plistPath, 0o600);
    if (existingPlist && finalPlistXml !== plistXml) {
      log(`Plist written: ${plistPath} (mode 600, preserved user env vars)`);
    } else {
      log(`Plist written: ${plistPath} (mode 600)`);
    }
    // Bootout first (in case it was already loaded) then bootstrap
    try { execSync(`launchctl bootout gui/$(id -u) "${plistPath}" 2>/dev/null`); } catch { /* ignore */ }
@@ -458,7 +396,7 @@ After=network.target
 ExecStart=${nodeBin} ${serverPath}
 Environment=CLAUDE_PROXY_PORT=${PORT}
 Environment=CLAUDE_BIND=${BIND_ADDRESS}
-Environment=CLAUDE_AUTH_MODE=${AUTH_MODE_CONFIG}${CLAUDE_BIN_INJECT ? `\nEnvironment=CLAUDE_BIN=${CLAUDE_BIN_INJECT}` : ""}${OCP_ADMIN_KEY_INJECT ? `\nEnvironment=OCP_ADMIN_KEY=${OCP_ADMIN_KEY_INJECT}` : ""}${PROXY_ANON_KEY_INJECT ? `\nEnvironment=PROXY_ANONYMOUS_KEY=${PROXY_ANON_KEY_INJECT}` : ""}
+Environment=CLAUDE_AUTH_MODE=${AUTH_MODE_CONFIG}
 Restart=always
 RestartSec=5
 StandardOutput=append:${logPath}
@@ -468,15 +406,8 @@ StandardError=append:${logPath}
 WantedBy=default.target
 `;
-    const existingService = existsSync(servicePath) ? readFileSync(servicePath, "utf8") : null;
+    writeFileSync(servicePath, serviceUnit);
-    const finalServiceUnit = mergeSystemdEnv(existingService, serviceUnit);
+    log(`Service file written: ${servicePath}`);
    writeFileSync(servicePath, finalServiceUnit);
    chmodSync(servicePath, 0o600);
    if (existingService && finalServiceUnit !== serviceUnit) {
      log(`Service file written: ${servicePath} (mode 600, preserved user env vars)`);
    } else {
      log(`Service file written: ${servicePath} (mode 600)`);
    }
    execSync(`systemctl --user daemon-reload`);
    execSync(`systemctl --user enable ocp-proxy`);
@@ -454,503 +454,6 @@ async function runSingleflightTests() {
 await runSingleflightTests();
 // ── Plist Env Merge Tests ──
 import { mergePlistEnv, mergeSystemdEnv } from "./scripts/lib/plist-merge.mjs";
 console.log("\nPlist env merge:");
 const SAMPLE_TEMPLATE_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
  <key>Label</key>
  <string>dev.ocp.proxy</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>CLAUDE_PROXY_PORT</key>
    <string>3478</string>
    <key>CLAUDE_BIND</key>
    <string>127.0.0.1</string>
    <key>CLAUDE_AUTH_MODE</key>
    <string>multi</string>
  </dict>
 </dict>
 </plist>`;
 const SAMPLE_EXISTING_PLIST = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
  <key>Label</key>
  <string>dev.ocp.proxy</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>CLAUDE_PROXY_PORT</key>
    <string>3456</string>
    <key>CLAUDE_BIND</key>
    <string>127.0.0.1</string>
    <key>CLAUDE_AUTH_MODE</key>
    <string>none</string>
    <key>CLAUDE_HEARTBEAT_INTERVAL</key>
    <string>2000</string>
    <key>CLAUDE_CACHE_TTL</key>
    <string>600</string>
  </dict>
 </dict>
 </plist>`;
 test("mergePlistEnv preserves unknown user keys", () => {
  const merged = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
  assert.match(merged, /<key>CLAUDE_HEARTBEAT_INTERVAL<\/key>\s*<string>2000<\/string>/);
  assert.match(merged, /<key>CLAUDE_CACHE_TTL<\/key>\s*<string>600<\/string>/);
 });
 test("mergePlistEnv overrides known template keys", () => {
  const merged = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
  assert.match(merged, /<key>CLAUDE_PROXY_PORT<\/key>\s*<string>3478<\/string>/);
  assert.match(merged, /<key>CLAUDE_AUTH_MODE<\/key>\s*<string>multi<\/string>/);
 });
 test("mergePlistEnv first-install returns template unchanged when existing is null", () => {
  const merged = mergePlistEnv(null, SAMPLE_TEMPLATE_PLIST);
  assert.equal(merged, SAMPLE_TEMPLATE_PLIST);
 });
 test("mergePlistEnv first-install returns template unchanged when existing is empty", () => {
  const merged = mergePlistEnv("", SAMPLE_TEMPLATE_PLIST);
  assert.equal(merged, SAMPLE_TEMPLATE_PLIST);
 });
 const SAMPLE_TEMPLATE_SYSTEMD = `[Unit]
 Description=OCP — Open Claude Proxy
 After=network.target
 [Service]
 ExecStart=/usr/bin/node /home/u/ocp/server.mjs
 Environment=CLAUDE_PROXY_PORT=3478
 Environment=CLAUDE_BIND=127.0.0.1
 Environment=CLAUDE_AUTH_MODE=multi
 Restart=always
 `;
 const SAMPLE_EXISTING_SYSTEMD = `[Unit]
 Description=OCP — Open Claude Proxy
 After=network.target
 [Service]
 ExecStart=/usr/bin/node /home/u/ocp/server.mjs
 Environment=CLAUDE_PROXY_PORT=3456
 Environment=CLAUDE_BIND=127.0.0.1
 Environment=CLAUDE_AUTH_MODE=none
 Environment=CLAUDE_HEARTBEAT_INTERVAL=2000
 Environment=CLAUDE_CACHE_TTL=600
 Restart=always
 `;
 test("mergeSystemdEnv preserves unknown user Environment lines", () => {
  const merged = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
  assert.match(merged, /Environment=CLAUDE_HEARTBEAT_INTERVAL=2000/);
  assert.match(merged, /Environment=CLAUDE_CACHE_TTL=600/);
 });
 test("mergeSystemdEnv overrides known template keys", () => {
  const merged = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
  assert.match(merged, /Environment=CLAUDE_PROXY_PORT=3478/);
  assert.match(merged, /Environment=CLAUDE_AUTH_MODE=multi/);
 });
 test("mergeSystemdEnv first-install returns template unchanged", () => {
  assert.equal(mergeSystemdEnv(null, SAMPLE_TEMPLATE_SYSTEMD), SAMPLE_TEMPLATE_SYSTEMD);
  assert.equal(mergeSystemdEnv("", SAMPLE_TEMPLATE_SYSTEMD), SAMPLE_TEMPLATE_SYSTEMD);
 });
 test("mergePlistEnv is idempotent", () => {
  const r1 = mergePlistEnv(SAMPLE_EXISTING_PLIST, SAMPLE_TEMPLATE_PLIST);
  assert.equal(mergePlistEnv(r1, SAMPLE_TEMPLATE_PLIST), r1);
 });
 test("mergeSystemdEnv is idempotent", () => {
  const r1 = mergeSystemdEnv(SAMPLE_EXISTING_SYSTEMD, SAMPLE_TEMPLATE_SYSTEMD);
  assert.equal(mergeSystemdEnv(r1, SAMPLE_TEMPLATE_SYSTEMD), r1);
 });
 // ── Doctor JSON Contract Tests ──
 import { runDoctor } from "./scripts/doctor.mjs";
 console.log("\nDoctor:");
 test("doctor --json shape: required top-level keys", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
  for (const k of ["schema_version", "ready_to_upgrade", "current_version", "latest_version",
                   "from_version_supported", "fail_count", "warn_count", "checks", "next_action"]) {
    assert.ok(k in result, `missing key: ${k}`);
  }
  assert.equal(result.schema_version, "1");
 });
 test("doctor detects from-version < v3.4.0 → fresh_install", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.2.0", mockLatest: "v3.14.0" });
  assert.equal(result.from_version_supported, false);
  assert.equal(result.next_action.kind, "fresh_install");
  assert.ok(Array.isArray(result.next_action.ai_executable));
  assert.ok(result.next_action.ai_executable.length > 0);
 });
 test("doctor next_action.kind enum is one of allowed values", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
  const ALLOWED = ["noop", "update", "upgrade", "fresh_install", "fix_oauth", "fix_service"];
  assert.ok(ALLOWED.includes(result.next_action.kind), `kind=${result.next_action.kind} not in enum`);
 });
 test("doctor noop when current==latest", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.0" });
  assert.equal(result.next_action.kind, "noop");
  assert.equal(result.ready_to_upgrade, true);
 });
 test("doctor patch-bump same minor → update kind", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.14.0", mockLatest: "v3.14.1" });
  assert.equal(result.next_action.kind, "update");
 });
 test("doctor cross-minor → upgrade kind", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "v3.10.0", mockLatest: "v3.14.0" });
  assert.equal(result.next_action.kind, "upgrade");
 });
 test("doctor OAuth FAIL → fix_oauth kind", async () => {
  const result = await runDoctor({
    skipNetwork: false,
    mockVersion: "v3.10.0",
    mockLatest: "v3.14.0",
    mockHealth: { status: 200, body: { auth: { ok: false, message: "ENOEXEC" } } }
  });
  assert.equal(result.next_action.kind, "fix_oauth");
  assert.ok(result.next_action.ai_executable.some(c => c.includes("install.cjs")));
 });
 test("doctor service down → fix_service kind", async () => {
  const result = await runDoctor({
    skipNetwork: false,
    mockVersion: "v3.10.0",
    mockLatest: "v3.14.0",
    mockHealth: { error: "ECONNREFUSED" }
  });
  assert.equal(result.next_action.kind, "fix_service");
 });
 test("doctor unparseable version → fresh_install", async () => {
  const result = await runDoctor({ skipNetwork: true, mockVersion: "garbage", mockLatest: "v3.14.0" });
  assert.equal(result.from_version_supported, false);
  assert.equal(result.next_action.kind, "fresh_install");
 });
 test("doctor empty health body → fix_service (not fix_oauth)", async () => {
  const result = await runDoctor({
    skipNetwork: false,
    mockVersion: "v3.10.0",
    mockLatest: "v3.14.0",
    mockHealth: { status: 200, body: null }
  });
  assert.equal(result.next_action.kind, "fix_service");
 });
 test("doctor falls back to currentVersion when origin/main unreachable (no stale latest)", async () => {
  // Use a non-existent ocpDir so git command fails; without the fix this would still
  // hard-code v3.14.0 as latest and recommend a downgrade for a future v3.15.0+ user.
  const result = await runDoctor({
    skipNetwork: true,
    mockVersion: "v3.15.0",
    ocpDir: "/nonexistent-ocp-dir-for-test"
  });
  assert.equal(result.latest_version, "v3.15.0");
  assert.equal(result.next_action.kind, "noop");
 });
 // ── Upgrade Tests ──
 import { runUpgrade } from "./scripts/upgrade.mjs";
 console.log("\nUpgrade:");
 test("upgrade --dry-run prints plan, no side effects", async () => {
  const result = await runUpgrade({
    dryRun: true,
    yes: true,
    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" }, current_version: "v3.10.0", latest_version: "v3.14.0" }
  });
  assert.equal(result.executed, false);
  assert.ok(result.plan.length > 0);
  assert.ok(result.plan.some(line => line.toLowerCase().includes("snapshot")));
 });
 test("upgrade noop returns early when current==latest", async () => {
  const result = await runUpgrade({
    yes: true,
    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "noop" }, current_version: "v3.14.0", latest_version: "v3.14.0" }
  });
  assert.equal(result.path, "noop");
  assert.equal(result.executed, true);
  assert.equal(result.changed, false);
 });
 test("upgrade aborts on doctor FAIL", async () => {
  await assert.rejects(async () => {
    await runUpgrade({
      yes: true,
      mockDoctor: { ready_to_upgrade: false, fail_count: 1, next_action: { kind: "fix_oauth" } }
    });
  }, /doctor FAIL/);
 });
 test("upgrade full path executes 5 phases", async () => {
  const result = await runUpgrade({
    yes: true,
    dryRun: false,
    mockExec: true,
    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
                  current_version: "v3.10.0", latest_version: "v3.14.0" }
  });
  assert.equal(result.path, "upgrade");
  // Plan asks for 6 phases by name; verify each appears as a phase entry
  const phaseNames = result.phases.map(p => p.name);
  for (const expected of ["pre-flight", "snapshot", "fetch+install", "reconfigure", "restart", "post-flight"]) {
    assert.ok(phaseNames.includes(expected), `missing phase: ${expected}; got ${phaseNames.join(",")}`);
  }
 });
 // ── Snapshot Tests ──
 import { writeSnapshot, readSnapshot, listSnapshots, gcSnapshots } from "./scripts/lib/snapshot.mjs";
 import { mkdtempSync, rmSync, mkdirSync as tMkdirSync, writeFileSync as testWriteFile, existsSync as testExistsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join as testJoin } from "node:path";
 console.log("\nSnapshot:");
 test("writeSnapshot creates dir + manifest files", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-test-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  testWriteFile(testJoin(dotOcp, "ocp.db"), "fake-sqlite-bytes");
  const path = writeSnapshot({
    homeDir: root,
    fromCommit: "abc1234",
    fromVersion: "v3.10.0",
    toVersion: "v3.14.0",
    extraFiles: []
  });
  const m = readSnapshot(path);
  assert.equal(m.fromCommit, "abc1234");
  assert.equal(m.fromVersion, "v3.10.0");
  rmSync(root, { recursive: true, force: true });
 });
 test("listSnapshots returns sorted by ISO timestamp", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-snap-list-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  for (const ts of ["2026-05-01T10:00:00Z", "2026-05-02T10:00:00Z", "2026-05-03T10:00:00Z"]) {
    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
  }
  const list = listSnapshots(root);
  assert.equal(list.length, 3);
  assert.ok(list[0].path.includes("2026-05-01"));
  assert.ok(list[2].path.includes("2026-05-03"));
  rmSync(root, { recursive: true, force: true });
 });
 test("upgrade error after snapshot carries snapshotPath + hint", async () => {
  // Use mockExec=true so no real commands are run.
  // Verify the success path returns a snapshotPath (Fix B regression guard).
  const result = await runUpgrade({
    yes: true,
    dryRun: false,
    mockExec: true,
    mockDoctor: { ready_to_upgrade: true, next_action: { kind: "upgrade" },
                  current_version: "v3.10.0", latest_version: "v3.14.0" }
  });
  assert.ok(result.snapshotPath, "successful upgrade returns snapshotPath");
  assert.equal(result.path, "upgrade");
  assert.equal(result.executed, true);
 });
 test("upgrade fresh_install requires --yes for non-interactive", async () => {
  await assert.rejects(async () => {
    await runUpgrade({
      yes: false,
      mockExec: true,
      mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
                    next_action: { kind: "fresh_install", ai_executable: ["echo would-rm-rf"] },
                    current_version: "v3.2.0", latest_version: "v3.14.0" }
    });
  }, /requires --yes/);
 });
 test("upgrade fresh_install with --yes runs ai_executable", async () => {
  const result = await runUpgrade({
    yes: true,
    mockExec: true,
    mockDoctor: { ready_to_upgrade: false, from_version_supported: false,
                  next_action: { kind: "fresh_install",
                                 ai_executable: ["echo step-1", "echo step-2", "echo step-3"] },
                  current_version: "v3.2.0", latest_version: "v3.14.0" }
  });
  assert.equal(result.path, "fresh_install");
  assert.equal(result.steps.length, 3);
 });
 test("rollback --list returns snapshots", async () => {
  const result = await runUpgrade({
    rollback: true,
    list: true,
    mockSnapshots: [
      { name: "upgrade-snapshot-2026-05-01T10:00:00Z", path: "/tmp/snap-1" },
      { name: "upgrade-snapshot-2026-05-02T10:00:00Z", path: "/tmp/snap-2" }
    ]
  });
  assert.equal(result.path, "rollback-list");
  assert.equal(result.snapshots.length, 2);
 });
 test("rollback with no snapshots fails clearly", async () => {
  await assert.rejects(async () => {
    await runUpgrade({ rollback: true, dryRun: true, mockSnapshots: [] });
  }, /no upgrade snapshots/);
 });
 test("rollback --dry-run produces a plan without mutation", async () => {
  const result = await runUpgrade({
    rollback: true,
    dryRun: true,
    mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
    mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
  });
  assert.equal(result.path, "rollback-dry-run");
  assert.equal(result.executed, false);
  assert.ok(result.plan.length > 0);
 });
 test("rollback latest snapshot restores files (mockExec)", async () => {
  const result = await runUpgrade({
    rollback: true,
    yes: true,
    mockExec: true,
    mockSnapshots: [{ name: "upgrade-snapshot-2026-05-11T08:30:00Z", path: "/tmp/snap-x" }],
    mockSnapshotMeta: { fromCommit: "abc1234", fromVersion: "v3.10.0", toVersion: "v3.14.0", path: "/tmp/snap-x" }
  });
  assert.equal(result.path, "rollback");
  assert.equal(result.executed, true);
  assert.ok(result.phases.some(p => p.name === "git-checkout"));
 });
 test("gcSnapshots keeps last N regardless of age", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-test-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-04-30T10:00:00Z", "2026-05-01T10:00:00Z", "2026-05-10T10:00:00Z"]) {
    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
  }
  const result = gcSnapshots(root, { keepCount: 3, keepDays: 0, now: new Date("2026-05-11T00:00:00Z") });
  assert.equal(result.kept.length, 3);
  assert.equal(result.removed.length, 2);
  assert.ok(result.kept[0].name.includes("2026-04-30"));
  assert.ok(result.kept[2].name.includes("2026-05-10"));
  rmSync(root, { recursive: true, force: true });
 });
 test("gcSnapshots keeps snapshots newer than keepDays regardless of count", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-days-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-04-30T10:00:00Z", "2026-05-01T10:00:00Z", "2026-05-10T10:00:00Z"]) {
    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
  }
  // keepCount=1 but keepDays=15 means anything from after 2026-04-26 is kept too
  const result = gcSnapshots(root, { keepCount: 1, keepDays: 15, now: new Date("2026-05-11T00:00:00Z") });
  // Kept: 2026-04-30 (within 15 days), 2026-05-01 (within 15 days), 2026-05-10 (within 15 days)
  assert.ok(result.kept.length >= 3);
  // Removed: 2026-04-01, 2026-04-15
  assert.ok(result.removed.some(s => s.name.includes("2026-04-01")));
 });
 test("gcSnapshots never deletes the most recent snapshot", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-recent-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  tMkdirSync(testJoin(dotOcp, "upgrade-snapshot-2026-01-01T10:00:00Z"));
  // Even with keepCount=0 and keepDays=0, the most recent must survive
  const result = gcSnapshots(root, { keepCount: 0, keepDays: 0, now: new Date("2026-05-11T00:00:00Z") });
  assert.equal(result.kept.length, 1);
  assert.equal(result.removed.length, 0);
  rmSync(root, { recursive: true, force: true });
 });
 test("gcSnapshots --dry-run reports plan without deleting", () => {
  const root = mkdtempSync(testJoin(tmpdir(), "ocp-gc-dryrun-"));
  const dotOcp = testJoin(root, ".ocp");
  tMkdirSync(dotOcp, { recursive: true });
  for (const ts of ["2026-04-01T10:00:00Z", "2026-04-15T10:00:00Z", "2026-05-10T10:00:00Z"]) {
    tMkdirSync(testJoin(dotOcp, `upgrade-snapshot-${ts}`));
  }
  const result = gcSnapshots(root, { keepCount: 1, keepDays: 0, dryRun: true, now: new Date("2026-05-11T00:00:00Z") });
  assert.equal(result.dryRun, true);
  assert.equal(result.removed.length, 2);
  // Files still exist
  assert.ok(testExistsSync(testJoin(dotOcp, "upgrade-snapshot-2026-04-01T10:00:00Z")));
  rmSync(root, { recursive: true, force: true });
 });
 // ── Doctor --check oauth fast path tests ──
 console.log("\nDoctor --check oauth:");
 await asyncTest("doctor --check oauth runs only oauth check (skips version/from-version)", async () => {
  const result = await runDoctor({
    checkOnly: "oauth",
    mockVersion: "v3.10.0",
    mockLatest: "v3.14.0",
    mockHealth: { status: 200, body: { auth: { ok: true, message: "authenticated" } } }
  });
  // Should still produce a valid result object
  assert.equal(result.schema_version, "1");
  // checks[] should only contain oauth_ok (no current_version, no from_version_supported)
  const ids = result.checks.map(c => c.id);
  assert.deepEqual(ids, ["oauth_ok"]);
  assert.equal(result.next_action.kind, "noop");
 });
 await asyncTest("doctor --check oauth + OAuth FAIL → fix_oauth", async () => {
  const result = await runDoctor({
    checkOnly: "oauth",
    mockHealth: { status: 200, body: { auth: { ok: false, message: "ENOEXEC" } } }
  });
  const ids = result.checks.map(c => c.id);
  assert.deepEqual(ids, ["oauth_ok"]);
  assert.equal(result.next_action.kind, "fix_oauth");
  assert.equal(result.fail_count, 1);
 });
 await asyncTest("doctor --check oauth + service down → fix_service", async () => {
  const result = await runDoctor({
    checkOnly: "oauth",
    mockHealth: { error: "ECONNREFUSED" }
  });
  const ids = result.checks.map(c => c.id);
  assert.deepEqual(ids, ["oauth_ok"]);
  assert.equal(result.next_action.kind, "fix_service");
  assert.equal(result.fail_count, 1);
 });
 await asyncTest("doctor --check oauth + 200 with null body → fix_service", async () => {
  const result = await runDoctor({
    checkOnly: "oauth",
    mockHealth: { status: 200, body: null }
  });
  const ids = result.checks.map(c => c.id);
  assert.deepEqual(ids, ["oauth_ok"]);
  assert.equal(result.next_action.kind, "fix_service");
  assert.equal(result.fail_count, 1);
 });
 // ── Cleanup ──
 closeDb();