diff --git a/.claude/agents/os-dev.md b/.claude/agents/os-dev.md
index 016caf1896..9ebc826f0e 100644
--- a/.claude/agents/os-dev.md
+++ b/.claude/agents/os-dev.md
@@ -75,8 +75,8 @@ JSON,所以终报消息就是 JSON 本身,别无其它。
    收尾打印本次持锁时长,过长自己喊出来。只包**命令本身**,不包你的阅读与判断;结论读它
    印的 VERDICT 行,不读裸 `$?`。排队是常态,不是挂死。
 2. **压住堆**:重命令前缀 `NODE_OPTIONS=--max-old-space-size=4096`(要抬需给理由)。
-3. **定向,不扫全**:只 build/test 受影响的包(`pnpm --filter <pkg> …`),vitest
-   `--maxWorkers=2`,turbo `--concurrency=2`。
+3. **定向,不扫全**:只 build/test 受影响的包 —— `pnpm --filter <pkg> exec vitest run --maxWorkers=2 <file>`,turbo `--concurrency=2`。
+   ⛔ 参数永不经裸 `--` 转交:`--` 之后的一切被 vitest 静默丢弃,文件模式与 `--maxWorkers` 一并失效,整包跑完、退出码 0、读起来像一次通过。
 4. **清理是任务的一步**:PR 开出后,
    `rm -rf <path>/node_modules && git worktree remove <path>` —— **不加 force**。⛔ 永不
    上来就 `--force`:node_modules 已删的情况下,拒绝移除说明里面有东西没提交 —— 你自己
diff --git a/AGENTS.md b/AGENTS.md
index 775fcc4422..7785a2f80b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -127,7 +127,7 @@ pays its first load at module top; `pnpm check:test-source-alias` gates it.
 
 `--fresh`: ephemeral tempdir (auto-deleted on exit) + `--seed-admin` (POSTs sign-up, prints creds — default `admin@objectos.ai` / `admin123`, override via `--admin-email`/`--admin-password`). The seeded admin is auto-promoted to **platform admin** (the system seed identity `usr_system` is skipped), so Setup/Studio are reachable on first login.
 
-Rules: never run two backends on port 3000; for backend tasks pick a random port and tear it down; **never kill a server you didn't start** (other agents/the user may be using it — see Multi-agent discipline §8); always use a `pnpm dev`/`dev:crm`/`dev:showcase` script (flags after `--` are forwarded), not raw `pnpm --filter`.
+Rules: never run two backends on port 3000; for backend tasks pick a random port and tear it down; **never kill a server you didn't start** (other agents/the user may be using it — see Multi-agent discipline §8); always use a `pnpm dev`/`dev:crm`/`dev:showcase` script, not raw `pnpm --filter` — but note what pnpm actually does with `--`: it forwards the **separator itself** into the child's argv, so this spelling only works where the receiving CLI tolerates a leading `--`. ⛔ Do not carry it over to test commands — vitest silently discards everything after a bare `--` (measured; see `.claude/agents/os-dev.md` → Toolchain traps).
 
 ```bash
 pnpm dev:crm -- --fresh -p 38421   # start; debug via curl