feat(scripts): mechanize verify-lock acquisition into a capped, FIFO, self-reporting entry point (#9921)

* feat(scripts): mechanize verify-lock acquisition into a capped, FIFO, self-reporting entry point

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AeA3nU1B5Q2pgxqxgUrexd

* docs(agents,ci): point os-dev's lock etiquette at the entry point, and self-test it in CI

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AeA3nU1B5Q2pgxqxgUrexd

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

.claude/agents/os-dev.md

@@ -66,13 +66,13 @@ JSON,所以终报消息就是 JSON 本身,别无其它。
 
 ## 资源纪律 —— 并行 agents 共享同一个容器
 
-1. **重活串行 —— 共享验证锁是具名约定。** 每容器一把锁,`/tmp/os-heavy-verify.lock`,包
-   住每次 build/test:`flock -E 99 -w 540 /tmp/os-heavy-verify.lock -c '<command>'`。纪
-   律:**释放归 `flock`**(fd 持有,命令进程树退出即释放 —— 永不手搓 lockfile);只包
-   **命令本身**,不包你的阅读与判断;保留 **`-E 99`**,让排队超时与测试失败可区分。
-   `-w` 要压在一次前台调用之内(本 harness 单次调用上限 10 分钟),循环重试获取 —— 盲等
-   不能比承载它的调用活得久,为逃上限把它丢后台正是规则 7 要止的停摆。排队是常态,不是
-   挂死。
+1. **重活串行 —— 共享验证锁只有一个入口。** 每次 build/test 都从这里走:
+   `bash scripts/pm/os-verify-lock.sh -c '<command>'`(或 `-- <argv>`)。⛔ 永不手搓
+   `flock`/lockfile —— 手写的 `-w` 正是「守约者饿死、越界者通吃」的来源(实测:同一容器
+   五个等待者、三个越界 6 倍;越界者只凭「一直在场」就 12/12 赢走交接)。入口点保证:等待
+   预算钉死在一次前台调用之内(更长的表达不出来)· 按到达顺序授予 · 99 仍专指「没排到」·
+   收尾打印本次持锁时长,过长自己喊出来。只包**命令本身**,不包你的阅读与判断;结论读它
+   印的 VERDICT 行,不读裸 `$?`。排队是常态,不是挂死。
 2. **压住堆**:重命令前缀 `NODE_OPTIONS=--max-old-space-size=4096`(要抬需给理由)。
 3. **定向,不扫全**:只 build/test 受影响的包(`pnpm --filter <pkg> …`),vitest
    `--maxWorkers=2`,turbo `--concurrency=2`。
@@ -85,13 +85,13 @@ JSON,所以终报消息就是 JSON 本身,别无其它。
    对那个 PID 操作。
 6. **整条流水线在前台跑。** build 与 test 都是本任务的步骤:阻塞运行、读真实输出、继续。
    ⛔ 永不把验证挂在后台 watcher 上然后停轮(禁令与两种合法终态见「干净收尾」)。唯一合
-   法的长等待是规则 1 的 `flock` 排队——主动、在轮内(规则 7),从不是停轮的理由。
+   法的长等待是规则 1 的锁排队——主动、在轮内(规则 7),从不是停轮的理由。
 7. **排队不是停摆 —— 在轮内主动等。** 持锁的是你不拥有的进程,它的完成不会以任何方式唤
    醒你:⛔ 永不为「等锁」结束一轮(实测:这么做的每个 agent 都无通知地停摆,赔进一轮探
-   活)。循环:限时获取 ⇒ 退出码 99 时把间隔花在无锁工作上(写测试、changeset、PR 正
-   文、包内 `typecheck`)⇒ 再获取。**排队 ~20 分钟无进展 ⇒ 先看这次检查能否收窄到不必持锁
-   (收窄要申报,见「干净收尾」);收窄不了就停下报 `blocked` 并点名持锁者**:`fuser -v /tmp/os-heavy-verify.lock`(或 `lsof`)打印其 PID 与命令 —— 一动不动
-   的持锁者本身就是真发现。报告它;沉默是唯一错误答案。
+   活)。循环:拿到 99 就把间隔花在无锁工作上(写测试、changeset、PR 正文、包内
+   `typecheck`)⇒ 再跑一次。**排队 ~20 分钟无进展 ⇒ 先看这次检查能否收窄到不必持锁(收窄
+   要申报,见「干净收尾」);收窄不了就停下报 `blocked` 并点名持锁者** —— `os-verify-lock.sh
+   --status` 打印持锁者、已持时长与队列;一动不动的持锁者本身就是真发现。沉默是唯一错误答案。
 
 ## Toolchain traps(每条都至少让一个 agent 白跑一轮)
 

.github/workflows/lint.yml

@@ -343,6 +343,28 @@ jobs:
       - name: Release-rehearsal clone preflight self-test
         run: node scripts/pm/release-rehearsal-clone.mjs --self-test
 
+      # Verify-lock entry-point self-test (#9661). `scripts/pm/os-verify-lock.sh`
+      # is the ONE way an agent takes the container's shared heavy-verify lock,
+      # and it is the enforcement of a rule that used to live only in prose: the
+      # acquisition budget os-dev.md declares is now unrepresentable above its
+      # cap, grants are ordered by a ticket file, and every run reports how long
+      # it held. Measured before it existed, in one container: five live waiters,
+      # three of them 6x over the declared cap, and the compliant ones were the
+      # ones not verifying — a convention whose violators win is not a convention.
+      #
+      # Nothing in CI *uses* the lock (GitHub runners are one job per machine),
+      # so this step exists to keep the mechanism honest rather than to serialise
+      # anything: 29 cases over the budget clamp, ticket liveness (dead pid,
+      # REUSED pid, over-age), fd hygiene, exit-code passthrough, and real
+      # multi-process contention — queue timeout, legacy free-hand coexistence in
+      # both directions, and three staggered waiters acquiring in arrival order.
+      # It runs entirely on a private lock under a temp dir; it never touches
+      # /tmp/os-heavy-verify.lock, so a runner and an agent container behave the
+      # same. Unconditional and un-`if:`-ed, like the self-tests above — an
+      # exemption is what a self-test must not have. No network, ~15 s.
+      - name: Verify-lock entry-point self-test
+        run: bash scripts/pm/os-verify-lock.sh --self-test
+
       # Docs/skills authoring guard (#2035 / ADR-0059): TS code blocks in
       # Markdown/MDX are not type-checked or ESLinted, so skills/ and
       # content/docs/ can drift back to teaching the bare `: Page = {}` literal