fix(wrap): replace stale-proxy detection with Vite-style port fallback

AGENTS.md

@@ -0,0 +1,84 @@
+# headroom AGENTS.md
+
+> headroomlabs-ai/headroom — AI Proxy 的 OSS 贡献项目
+> Fork: lennney/headroom → upstream: headroomlabs-ai/headroom
+
+## 技术栈
+
+- Python 3.12+, uv 包管理
+- CLI: `headroom` 命令行工具
+- 项目结构: `headroom/` 核心库, `tests/` pytest, `docs/` Nextra MDX
+
+## 常用命令
+
+```bash
+# 同步上游
+git fetch upstream main && git checkout main && git merge upstream/main
+
+# 开新分支（必须从最新 main 开）
+git checkout main && git pull upstream main && git checkout -b fix/xxx
+
+# 本地测试
+uv run pytest tests/ -x -q
+uv run ruff check headroom/
+
+# 检查 PR 分支干净度
+git diff upstream/main...HEAD --name-only | grep -v 'uv\.lock$'
+
+# 运行 PR governance 检查（本地模拟）
+# PR body 必须有 6 个 section，见下方 PR Governance
+```
+
+## 当前 PR 状态
+
+| PR | 分支 | 标题 | 状态 |
+|---|---|---|---|
+| #1406 | `fix/wrap-port-fallback` | fix(wrap): port fallback | APPROVED |
+| #1708 | `docs/pipeline-extension-recipe` | docs: pipeline extension recipe | ready for review |
+| #1707 | `docs/fix-lean-ctx-reversible` | docs(readme): fix lean-ctx column | ready for review |
+| #1666 | `fix/transformers-5.3.0-cve-2026-4372` | fix(deps): bump transformers | ready for review |
+
+## PR Governance（红线）
+
+headroom 用 bot 自动检查 PR body，6 个 section 一个不能少：
+
+```
+## Description          ← ≥10 chars, 包含 Closes #
+## Type of Change        ← 至少一个 - [x] checkbox
+## Changes Made          ← 非空 bullets
+## Testing               ← checkboxes + 代码块（真实输出）
+## Real Behavior Proof   ← 4 个子字段（精确标签）：
+  - Environment:
+  - Exact command / steps:
+  - Observed result:
+  - Not tested:
+## Review Readiness      ← 2 个 checkbox（精确标签）：
+  - [x] I have performed a self-review
+  - [x] This PR is ready for human review
+```
+
+**关键坑：**
+- Bot 做**精确字符串匹配**，`"Verification:"` ≠ `"Exact command / steps:"`
+- 修改 PR body **不会**触发 re-check，必须 push commit
+- Review Readiness 的 checkbox 标签必须一字不差
+
+## 分支干净度
+
+每个 PR push 前必须检查：
+
+```bash
+git diff upstream/main...HEAD --name-only | grep -E '(AGENTS\.md|HANDOVER\.md|\.hermes/|docs/plans/|solutions/|\.cursorrules|CLAUDE\.md)'
+# 有输出 = 脏分支，必须清理
+```
+
+## 边界
+
+- ✅ **Always**: 跑测试、修 lint、更新 HANDOVER.md、PR 前查分支干净度
+- ⚠️ **Ask first**: 改公共接口、加新依赖、关闭安全机制
+- 🚫 **Never**: 硬编码密钥、改系统级配置（/etc/）、跳过 PR governance 模板
+
+## 已知陷阱
+
+1. **#1406 的 7 轮 review** — 端口 fallback 后配置消费者不同步（TOCTOU race）、Codex prepare-only 路径误启动 proxy、bypass pattern 绕过 `_ensure_proxy`。详见 code-review skill 的 pitfall #15-22。
+2. **3 个 docs PR 全被 governance bot 挡** — 没填模板就直接提 PR。教训：先读 `.github/PULL_REQUEST_TEMPLATE.md`。
+3. **#1666 脏分支** — 从包含 #1406 改动的分支出去了，diff 里混入 6 个无关文件。教训：永远从 `upstream/main` 开分支。