Merge recover-all branch into main

.github/scripts/check-open-items-fragmented-parity.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+report="docs/reports/fragemented/OPEN_ITEMS_VALIDATION_2026-02-22.md"
+if [[ ! -f "$report" ]]; then
+  echo "[FAIL] Missing report: $report"
+  exit 1
+fi
+
+section="$(awk '/Issue #258/{flag=1} flag{print} /^- (Issue|PR) #[0-9]+/{if(flag && $0 !~ /Issue #258/) exit}' "$report")"
+if [[ -z "$section" ]]; then
+  echo "[FAIL] $report missing Issue #258 section."
+  exit 1
+fi
+
+if echo "$section" | rg -q "Partial:"; then
+  echo "[FAIL] $report still marks #258 as Partial; update to implemented status with current evidence."
+  exit 1
+fi
+
+if ! echo "$section" | rg -qi "implemented"; then
+  echo "[FAIL] $report missing implemented status text for #258."
+  exit 1
+fi
+
+if ! rg -n "pkg/llmproxy/translator/codex/openai/chat-completions/codex_openai_request.go" "$report" >/dev/null 2>&1; then
+  echo "[FAIL] $report missing codex variant fallback evidence path."
+  exit 1
+fi
+
+echo "[OK] fragmented open-items report parity checks passed"

.gitignore

@@ -44,3 +44,4 @@ _bmad-output/*
 .DS_Store
 ._*
 *.bak
+pkg/llmproxy/api/logs/

Taskfile.yml

@@ -123,7 +123,7 @@ tasks:
     desc: "Format and lint staged files only"
     cmds:
       - |
-        mapfile -t go_files < <(git diff --cached --name-only -- '*.go')
+        mapfile -t go_files < <(git diff --cached --name-only --diff-filter=ACMR -- '*.go')
         if [ "${#go_files[@]}" -eq 0 ]; then
           echo "[SKIP] No staged Go files to format/lint."
           exit 0
@@ -141,9 +141,9 @@ tasks:
     cmds:
       - |
         if [ -n "${QUALITY_DIFF_RANGE:-}" ]; then
-          mapfile -t go_files < <(git diff --name-only "$QUALITY_DIFF_RANGE" -- '*.go' | sort -u)
+          mapfile -t go_files < <(git diff --name-only --diff-filter=ACMR "$QUALITY_DIFF_RANGE" -- '*.go' | sort -u)
         else
-          mapfile -t go_files < <(git diff --cached --name-only -- '*.go')
+          mapfile -t go_files < <(git diff --cached --name-only --diff-filter=ACMR -- '*.go')
         fi
         if [ "${#go_files[@]}" -eq 0 ]; then
           echo "[SKIP] No staged or diff Go files to check."
@@ -267,6 +267,12 @@ tasks:
         go test "${test_packages[@]}"
       - task: test:provider-smoke-matrix:test
 
+  quality:pre-push:
+    desc: "Pre-push hook quality gate"
+    deps: [preflight, cache:unlock]
+    cmds:
+      - task: quality:quick:check
+
   quality:shellcheck:
     desc: "Run shellcheck on shell scripts (best-effort, no-op when shellcheck missing)"
     cmds:
@@ -327,8 +333,14 @@ tasks:
     desc: "Validate release-facing config examples and docs snippets"
     cmds:
       - task: preflight
+      - task: quality:docs-open-items-parity
       - ./.github/scripts/release-lint.sh
 
+  quality:docs-open-items-parity:
+    desc: "Prevent stale status drift in fragmented open-items report"
+    cmds:
+      - ./.github/scripts/check-open-items-fragmented-parity.sh
+
   test:smoke:
     desc: "Run smoke tests for startup and control-plane surfaces"
     deps: [preflight, cache:unlock]

docs/planning/issue-wave-codescan-progress-2026-02-23.md

@@ -0,0 +1,44 @@
+# Code Scanning Execution Progress (2026-02-23)
+
+## Scope
+
+- Source: `KooshaPari/cliproxyapi-plusplus` code-scanning alerts/issues
+- Execution model: lane branches + dedicated worktrees
+- Goal: process alerts in fixed-size waves with commit evidence
+
+## Batch 1 Completed (`6 x 5 = 30`)
+
+- `codescan-b1-l1` -> `7927c78a`
+- `codescan-b1-l2` -> `93b81eeb`
+- `codescan-b1-l3` -> `23439b2e`
+- `codescan-b1-l4` -> `5f23c009`
+- `codescan-b1-l5` -> `a2ea9029`
+- `codescan-b1-l6` -> `60664328`
+
+## Batch 2 Completed (`6 x 10 = 60`)
+
+- `codescan-b2-l1` -> `7901c676`
+- `codescan-b2-l2` -> `6fd3681b`
+- `codescan-b2-l3` -> `cf6208ee`
+- `codescan-b2-l4` -> `bb7daafe`
+- `codescan-b2-l5` -> `5a945cf9`
+- `codescan-b2-l6` -> `7017b33d`
+
+## Total Completed So Far
+
+- `90` issues executed in lane branches (`30 + 60`)
+
+## Known Cross-Lane Environment Blockers
+
+- Shared concurrent lint lock during hooks: `parallel golangci-lint is running`
+- Existing module/typecheck issues in untouched areas can fail package-wide test runs:
+  - missing `internal/...` module references (for some package-level invocations)
+  - unrelated typecheck failures outside lane-owned files
+
+## Next Wave Template
+
+- Batch size: `6 x 10 = 60` (or smaller by request)
+- Required per lane:
+  - focused tests for touched surfaces
+  - one commit on lane branch
+  - push branch to `origin`

docs/planning/reports/issue-wave-cpb-0138-0147-lane-1.md

@@ -0,0 +1,123 @@
+# Issue Wave CPB-0138..0147 Lane 1 Plan
+
+## Scope
+- Lane: `1`
+- Target items: `CPB-0138`..`CPB-0147`
+- Worktree: `/Users/kooshapari/temp-PRODVERCEL/485/kush/cliproxyapi-plusplus`
+- Date: 2026-02-23
+- Focus: document implementable deltas and verification commands for these ten items; other lanes can ignore unrelated edits in the repository.
+
+## Per-Item Plan
+
+### CPB-0138 Define non-subprocess integration path
+- Status: `planned`
+- Implementation deltas:
+  - Extend `docs/sdk-usage.md` so the `Integration Contract` section walks through the recommended in-process `sdk/cliproxy.NewBuilder()` lifecycle, the HTTP fallback (`/v1/*`, `/v0/management/config`), and the capability/version negotiation probes (`/health`, `/v1/models`, `remote-management.secret-key`).
+  - Add a troubleshooting row that highlights the version sniffing steps and points to the HTTP fallback endpoints exposed by `cmd/server` and `sdk/api/handlers`.
+  - Capture the benchmark plan called for in the board by recording the pre-change `task test:baseline` results and explaining that the same command will be rerun after the implementable delta.
+- Planned files:
+  - `docs/sdk-usage.md`
+  - `docs/troubleshooting.md`
+- Notes: keep the focus on documentation and observable experience; no deep runtime refactor is scheduled yet.
+
+### CPB-0139 Gemini CLI rollout safety guardrails
+- Status: `planned`
+- Implementation deltas:
+  - Add table-driven API contract tests in `pkg/llmproxy/executor/gemini_cli_executor_test.go` that exercise missing credential fields, legacy vs. new parameter mixes, and the `statusErr` path that surfaces the upstream `额度获取失败` message.
+  - Extend `pkg/llmproxy/auth/gemini/gemini_auth_test.go` with fixtures that simulate malformed tokens (missing `refresh_token`, expired credential struct) so the CLI can surface `请检查凭证状态` before hitting production.
+  - Reference the new guardrails in `docs/troubleshooting.md` (Gemini CLI section) and the `Gemini` quickstart so operators know which fields to check during a rollout.
+- Planned files:
+  - `pkg/llmproxy/executor/gemini_cli_executor_test.go`
+  - `pkg/llmproxy/auth/gemini/gemini_auth_test.go`
+  - `docs/troubleshooting.md`
+  - `docs/provider-quickstarts.md`
+
+### CPB-0140 Normalize 403 metadata/naming
+- Status: `planned`
+- Implementation deltas:
+  - Add a canonical `403` troubleshooting entry that maps each provider alias to the metadata fields we record (e.g., `provider`, `alias`, `model`, `reason`) so repeated 403 patterns can be channeled into the same remediation path.
+  - Bake a short migration note in `docs/FEATURE_CHANGES_PLUSPLUS.md` (or the nearest changelog) that restates the compatibility guarantee when renaming aliases or metadata fields.
+- Planned files:
+  - `docs/troubleshooting.md`
+  - `docs/FEATURE_CHANGES_PLUSPLUS.md`
+
+### CPB-0141 iFlow compatibility gap closure
+- Status: `planned`
+- Implementation deltas:
+  - Introduce a normalization helper inside `pkg/llmproxy/executor/iflow_executor.go` (e.g., `normalizeIFlowModelName`) so requests that carry alternate suffixes or casing are converted before we apply thinking/translators.
+  - Emit a mini telemetry log (reusing `recordAPIRequest` or `reporter.publish`) that tags the normalized `model` and whether a suffix translation was applied; this will be used by future telemetry dashboards.
+  - Add focused tests in `pkg/llmproxy/executor/iflow_executor_test.go` covering the normalized inputs and ensuring the telemetry hook fires when normalization occurs.
+- Planned files:
+  - `pkg/llmproxy/executor/iflow_executor.go`
+  - `pkg/llmproxy/executor/iflow_executor_test.go`
+
+### CPB-0142 Harden Kimi OAuth
+- Status: `planned`
+- Implementation deltas:
+  - Tighten validation in `pkg/llmproxy/auth/kimi/kimi.go` so empty `refresh_token`, `client_id`, or `client_secret` values fail fast with a clear error and default to safer timeouts.
+  - Add regression tests in `pkg/llmproxy/auth/kimi/kimi_test.go` that assert each missing field path returns the new error and that a simulated provider fallback metric increments.
+  - Document the new validation expectations in `docs/troubleshooting.md` under the Kimi section.
+- Planned files:
+  - `pkg/llmproxy/auth/kimi/kimi.go`
+  - `pkg/llmproxy/auth/kimi/kimi_test.go`
+  - `docs/troubleshooting.md`
+
+### CPB-0143 Operationalize Grok OAuth
+- Status: `planned`
+- Implementation deltas:
+  - Update `docs/provider-operations.md` with a Grok OAuth observability subsection that lists the thresholds (latency, failure budget) operators should watch and ties each alert to a specific remediation script or CLI command.
+  - Add deterministic remediation text with command examples to the `docs/troubleshooting.md` Grok row.
+  - Mention the same commands in the `docs/provider-operations.md` runbook so alerts can point to this lane’s work when Grok authentication misbehaves.
+- Planned files:
+  - `docs/provider-operations.md`
+  - `docs/troubleshooting.md`
+
+### CPB-0144 Provider-agnostic token refresh runbook
+- Status: `planned`
+- Implementation deltas:
+  - Document the provider-agnostic `token refresh failed` sequence in `docs/provider-quickstarts.md` and `docs/troubleshooting.md`, including the `stop/relogin/management refresh/canary` choreography and sample request/response payloads.
+  - Reference the existing translation utilities (`pkg/llmproxy/thinking`) to highlight how they already canonicalize the error so every provider can look at the same diagnostics.
+- Planned files:
+  - `docs/provider-quickstarts.md`
+  - `docs/troubleshooting.md`
+
+### CPB-0145 Process-compose/HMR deterministic refresh
+- Status: `planned`
+- Implementation deltas:
+  - Extend `docs/install.md` with a step-by-step process-compose/HMR refresh workflow (touch `config.yaml`, poll `/health`, probe `/v1/models`, run `cliproxy reload`) using precise commands.
+  - Introduce a small helper script under `scripts/process_compose_refresh.sh` that encapsulates the workflow and can be run from CI/local dev loops.
+  - Explain the workflow in `docs/troubleshooting.md` so operators have a deterministic repro for `Gemini 3` refresh failures.
+- Planned files:
+  - `docs/install.md`
+  - `scripts/process_compose_refresh.sh`
+  - `docs/troubleshooting.md`
+
+### CPB-0146 Cursor root-cause UX/logs
+- Status: `planned`
+- Implementation deltas:
+  - Add a Cursor-specific quickstart entry in `docs/provider-quickstarts.md` that walks through the `cursor login` flow, the key indicators of a root-cause `cursor` error, and the commands to surface structured logs.
+  - Inject structured logging fields (`cursor_status`, `config_path`, `response_code`) inside `pkg/llmproxy/cmd/cursor_login.go` so the new quickstart can point operators to log lines that capture the symptom.
+  - Mention the new log fields in `docs/troubleshooting.md` so the runbook references the exact columns in logs when diagnosing the `cursor` root cause.
+- Planned files:
+  - `docs/provider-quickstarts.md`
+  - `pkg/llmproxy/cmd/cursor_login.go`
+  - `docs/troubleshooting.md`
+
+### CPB-0147 ENABLE_TOOL_SEARCH QA
+- Status: `planned`
+- Implementation deltas:
+  - Add QA scenarios to `pkg/llmproxy/executor/claude_executor_test.go` that exercise the `ENABLE_TOOL_SEARCH` flag for both stream and non-stream flows; mock the MCP response that returns `tools unavailable 400` and assert the fallback behavior.
+  - Expose the `claude.enable_tool_search` toggle in `config.example.yaml` (under the Claude section) and document it in `docs/provider-quickstarts.md`/`docs/troubleshooting.md` so rollouts can be staged via config toggles.
+  - Capture the config toggle in tests by seeding `pkg/llmproxy/config/config_test.go` or a new fixture file.
+- Planned files:
+  - `pkg/llmproxy/executor/claude_executor_test.go`
+  - `config.example.yaml`
+  - `docs/provider-quickstarts.md`
+  - `docs/troubleshooting.md`
+
+## Verification Strategy
+1. `go test ./pkg/llmproxy/executor -run 'TestIFlow.*|TestGeminiCLI.*|TestClaude.*ToolSearch'`
+2. `go test ./pkg/llmproxy/auth/gemini ./pkg/llmproxy/auth/kimi -run 'TestGeminiAuth|TestKimi'`
+3. `task test:baseline` (captures the latency/memory snapshot required by CPB-0138 before/after the doc-driven change).
+4. `rg -n "ENABLE_TOOL_SEARCH" config.example.yaml docs/provider-quickstarts.md docs/troubleshooting.md`
+5. `rg -n "cursor_status" pkg/llmproxy/cmd/cursor_login.go docs/troubleshooting.md` (ensures the new structured logging message is documented).

docs/planning/reports/issue-wave-cpb-0176-0245-lane-1.md

@@ -9,14 +9,14 @@
 ## Status Snapshot
 
 - `planned`: 0
-- `implemented`: 0
-- `in_progress`: 10
+- `implemented`: 9
+- `in_progress`: 1
 - `blocked`: 0
 
 ## Per-Item Status
 
 ### CPB-0176 – Expand docs and examples for "After logging in with iFlowOAuth, most models cannot be used, only non-CLI models can be used." with copy-paste quickstart and troubleshooting section.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `provider-model-registry`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1499`
 - Rationale:
@@ -28,7 +28,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0177 – Add QA scenarios for "为什么我请求了很多次,但是使用统计里仍然显示使用为0呢?" including stream/non-stream parity and edge-case payloads.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `websocket-and-streaming`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1497`
 - Rationale:
@@ -52,7 +52,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0179 – Ensure rollout safety for "最近几个版本，好像轮询失效了" via feature flags, staged defaults, and migration notes.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `websocket-and-streaming`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1495`
 - Rationale:
@@ -64,7 +64,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0180 – Standardize metadata and naming conventions touched by "iFlow error" across both repos.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `error-handling-retries`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1494`
 - Rationale:
@@ -76,7 +76,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0181 – Follow up on "Feature request [allow to configure RPM, TPM, RPD, TPD]" by closing compatibility gaps and preventing regressions in adjacent providers.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `provider-model-registry`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1493`
 - Rationale:
@@ -88,7 +88,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0182 – Harden "Antigravity using Ultra plan: Opus 4.6 gets 429 on CLIProxy but runs with Opencode-Auth" with clearer validation, safer defaults, and defensive fallbacks.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `thinking-and-reasoning`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1486`
 - Rationale:
@@ -100,7 +100,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0183 – Operationalize "gemini在cherry studio的openai接口无法控制思考长度" with observability, alerting thresholds, and runbook updates.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `thinking-and-reasoning`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1484`
 - Rationale:
@@ -112,7 +112,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0184 – Define non-subprocess integration path related to "codex5.3什么时候能获取到啊" (Go bindings surface + HTTP fallback contract + version negotiation).
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `integration-api-bindings`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1482`
 - Rationale:
@@ -124,7 +124,7 @@
 - Next action: add reproducible payload/regression case, then implement in assigned workstream.
 
 ### CPB-0185 – Add DX polish around "Amp code doesn't route through CLIProxyAPI" through improved command ergonomics and faster feedback loops.
-- Status: `in_progress`
+- Status: `implemented`
 - Theme: `provider-model-registry`
 - Source: `https://github.com/router-for-me/CLIProxyAPI/issues/1481`
 - Rationale:
@@ -138,7 +138,12 @@
 ## Evidence & Commands Run
 
 - `rg -n "CPB-0176|CPB-0245" docs/planning/CLIPROXYAPI_1000_ITEM_BOARD_2026-02-22.csv`
-- No repository code changes were performed in this lane in this pass; planning only.
+- `go test ./pkg/llmproxy/runtime/executor -run 'ParseOpenAI(StreamUsageSSE|StreamUsageNoUsage|ResponsesStreamUsageSSE|ResponsesUsageTotalFallback)' -count=1`
+- `go test ./pkg/llmproxy/runtime/executor -run 'IFlow|iflow' -count=1`
+- `go test ./pkg/llmproxy/api/handlers/management -run 'IFlow|Auth' -count=1`
+- `go test ./pkg/llmproxy/api -run 'TestServer_SetupRoutes_IsIdempotent|TestServer_SetupRoutes_ResponsesWebsocketFlag' -count=1`
+- `go test ./pkg/llmproxy/ratelimit -run 'TestParseRateLimitConfigFromMap_AliasKeys' -count=1`
+- `go test ./pkg/llmproxy/translator/antigravity/claude -run 'TestConvertClaudeRequestToAntigravity_MaxTokensClamped' -count=1`
 
 ## Next Actions
-- Move item by item from `planned` to `implemented` only when regression tests and code updates are committed.
+- Complete CPB-0178 by implementing provider-agnostic management quota endpoint(s) with Claude-specific aggregation.