docs: handoff as of 2026-10-10 [DO NOT MERGE — DSR v4 HOLD]

[jhfnetboy]

⛔ DO NOT MERGE — DSR execution instruction v4: "DVT 不 merge/rebuild/redeploy、不写 Sepolia". This PR exists so the handoff is reviewable and findable on a branch; merge it once the HOLD lifts.

Adds docs/HANDOFF.md — the single entry point for whoever picks this repo up next.

What's in it

• §1 the governing instruction (v4) quoted verbatim, with a concrete allowed/forbidden table. ⚠️ v3 and v4 exist only as Seeder CC-122 comments — not in the DSR handoff directory.
• §2 current state: three different version numbers (master / package.json 1.15.0 / 1.13.1 actually running), runtime topology and self-heal layers, and why the committee validator 0x7ac7E9d4 is fail-closed on purpose since epoch 184283 — with the exact restore order (dedicated EOA first, then two epochs observed, per v4).
• §3 milestones: the CC-122 sequence with each stage's status (A2/A2a NOT ACCEPTED, A3a NO-GO), DVT's own ordered path once the HOLD lifts, and a note that docs/ROADMAP.md is stale.
• §4 open PRs · §5 problems ranked ([security] confirmSlashableAtBlock 用 hasRole 授权不可逆 slash —— 被罚到 0 的成员永久可罚，构成共签流水线 griefing 面（含跨仓约定：准入一律读 effectiveStake） #376 first — the only defence left after the author declined a Registry fix) · §6 every Seeder task involving dvt · §7 document index · §8 operational traps · §9 first commands to run.

How it was checked

• Every fact was re-read from its live source on 2026-10-10 (chain, GitHub, launchd, Seeder), not carried over from notes.
• All 27 relative links are present in origin/master's git tree (checked against the tree, with a control — not against the local filesystem); prettier --check passes.
  • Correction: the first revision claimed "every relative link resolves" after checking only the local filesystem. CLAUDE.md exists locally but is excluded via .git/info/exclude and was never committed, so its link 404'd on GitHub — caught by pr-daemon, fixed in ec59b09.
• One claim drafted from memory was wrong and was corrected before commit: Security Audit is not "red on master" — master's last CI run (2026-09-05) passed it, but that run predates the multer advisories behind [tech-debt] Security Audit 闸门长红：multer 需 overrides（升级修不掉）+ lockfile 混源让本地 audit 成为坏掉的量具 + Trivy 未产出 sarif #338.

Also done alongside (local only, not in this diff): #378's format:check blocker fixed (5f2b514); 51 redundant local branches and 2 agent worktrees removed after proving every commit reachable from a remote or GitHub PR ref; the only two branches holding unpushed commits were resolved — opt/validator-gas-safe pushed to origin as an archive (no PR; it is the declined CC-96 optimisation), pr-244 deleted (superseded by the merged b97e533). See §9.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pdq9rgkZq9M4JFeTZD7yYs

[clestons]

REQUEST_CHANGES — #382

意图：纯文档交接 PR（docs/HANDOFF.md，398 行新文件），明确标注 [DO NOT MERGE — DSR v4 HOLD]，仅供审阅/留存，不要求本轮合并。按文档类 PR 的审查标准（只有"实质性事实错误"才构成阻塞）审查。

亲自抽查的事实性声称——3/3 命中，1 处失实

• master HEAD：文档声称 1991e92（2026-09-05）——git rev-parse origin/master 确认逐字匹配。
• package.json 版本号：文档声称 1.15.0——git show origin/master:package.json 确认逐字匹配。
• #376 的代码位置与逻辑：文档声称 confirmSlashableAtBlock() 在 audit.service.ts:791-808，只检查 hasRole（成员资格）不检查 stake——读了实际代码：函数确实从第 791 行开始，逐条检查 this.watchlist.includes 和 hasRole，从未读取任何 stake 相关字段，逐字匹配文档的描述。

🔴 阻塞项：CLAUDE.md 链接 404，与文档自称的"每个相对链接都能解析"矛盾

文档 §7 文档索引表里「Agent / developer guide」一行链接到 [`CLAUDE.md`](../CLAUDE.md)——../ 相对 docs/HANDOFF.md 应解析到仓库根目录的 CLAUDE.md。我核实了整个仓库在这个 head 上根本不存在任何 CLAUDE.md/AGENTS.md（git ls-tree -r 全仓搜索零命中）。

文档正文明确声称（"How it was checked"一节）：「Every relative link resolves」——这条声称本身是假的，至少这一处链接会 404。虽然是接手文档里一个不起眼的角落，但正是"交接文档"这个文体最依赖的信任点——下一个接手的人会直接点这个链接去找开发指南，点不开。

要求的修复

把 §7 表格里那一行的链接改成实际存在的文件（或者如果这个仓库确实没有 agent/开发者指南文档，就去掉这一行，不要留一个死链接），顺手复核一遍其余链接（我只抽查了 5 条，4 条命中，这一条没中——建议作者自己过一遍全部链接，而不是只信"跑过检查"这句话）。

CI 现查：Code Quality pass（prettier --check 的声称这条机械验证过了）；Security Audit/CI Success 红是既有 multer 欠账，与本 PR 无关，不算阻塞。

本评审只给结论，不做合并（PR 本身也明确标注不要合并）。

---

🤖 pr-daemon · [2-round：纯文档PR，R1a按ABSOLUTE CONSTRAINT #5结构性豁免跳过；本会话亲自抽查5条可验证声称——master HEAD/package.json版本/#376代码位置逐字匹配(3/3)，CLAUDE.md相对链接404(1处失实，与文档自称"每个链接都能解析"矛盾)；REQUEST_CHANGES仅针对这一处死链接，其余内容核实准确]

[clestons]

Round 2 — APPROVE（阻塞项已修复，验证方式本身也做得对）

head: 32b87812f46ae906ff653d9e3877d483604501ca
reviewed: 2026-10-10

阻塞项已修复(ec59b09):§7表格里的CLAUDE.md死链接已改成指向README.md/CONTRIBUTING.md,并补充说明"agent指南CLAUDE.md是本机本地文件(经.git/info/exclude排除,从未提交),不在仓库里"。这条解释本身也核实为真:CLAUDE.md从未进入git树,不是遗漏提交而是故意本地专属。commit message自述这次改用origin/master的树重新核对了全部27条相对链接,并用CLAUDE.md本身作对照组确认现在能正确报告"不存在"。方法论的修正本身就值得记一笔:验证链接必须对着远程仓库的树,不能对着本机工作区。

第二个commit(32b8781)顺带修正了§9两条此前"本机专属、建议删除"的分支状态——opt/validator-gas-safe已推送到origin作为存档(我git ls-remote origin核实确实存在,commit sha与声称的8848937一致),pr-244已标记删除。均为合理的交接记录更新,没有新的事实性问题。

CI现查:Code Quality pass;Security Audit/CI Success仍红但是既有欠账(与本PR无关)。

此前阻塞项:已修复。确认裁决:APPROVE。

本评审只给结论,不做合并(PR本身也明确标注不要合并)。

[clestons]

APPROVE — docs/HANDOFF.md (head 32b87812f46ae906ff653d9e3877d483604501ca)

Head: 32b87812f46ae906ff653d9e3877d483604501ca · base master · round label: [2-round — docs path; R1a+R1b DeepSeek ran, verdict restated because the head is byte-identical to the tree already approved in this PR's previous round; no Opus R2 / Codex R3 / Opus R4 round was run]

APPROVE 表示这份 diff 本身可以合；PR 自己声明在 DSR v4 HOLD 解除前不 merge，合并时机由作者决定。

为什么会出现第三轮（我们的记账 bug，不是 PR 变了）

head 自上一轮 APPROVE 以来没有移动过（32b87812… 与当时记录在案的是同一个 sha），PR 仍然 OPEN / MERGEABLE。这一轮被重新排进队列，是因为 PR-Daemon 自己的 pr_watch_targets.last_reviewed_head_oid 是 NULL —— 上一轮 Step 7 的记账 UPDATE 没写进去，扫描器于是每轮都判它"未审"。这是我们的状态 bug，不是这个 PR 的新工作。因为 commit sha 在密码学上钉住了整棵树，字节同一性由此得证，不需要再拿产物比对。

意图（T1）

作者想达成的是：在 DSR v4 HOLD 期间，把这份仓库的运维状态沉淀成一份"下一任接手者第一眼就能用"的单入口 handoff，放在分支上可评审、可检索，而不是等解冻。 —— 由 PR body + 标题里的 [DO NOT MERGE — DSR v4 HOLD] + diff 实际只增一个 docs/HANDOFF.md 三者交叉读出。按这个意图衡量，diff 达成了它：单文件、单入口、§1 起就把治理指令原文放最前。没有任何阻塞项来自"意图没达成"。

机械核验（本轮实跑，逐条可复现）

声称	我怎么核的	结果
PR 只动 docs/HANDOFF.md	git diff --name-only origin/master...HEAD	✅ 仅此一文件，+400
27 条相对链接在 origin/master 的 git tree 里都存在	对 origin/master 的 tree 逐个解析（带正对照：一个不存在的路径必须报 missing，control=True）	✅ 27/27，与 PR body 自述一致（作者用同一口径独立做过）
_isStaked 引在 AAStarValidator.sol:950	读 946-951	✅ 精确命中：return r.hasRole(ROLE_DVT, op) && r.getEffectiveStake(op, ROLE_DVT) >= minStake; —— §5.1"合约已合规"属实
§5.1 说 confirmSlashableAtBlock 靠 hasRole 授权、读失败即 fail-closed	读 789-812	✅ 实质属实（watchlist → derivedSetIsFresh → hasRole 循环；catch 里 return false）。范围终点见下方建议①
snapshotEpoch 无 onlyOwner / 无 msg.sender	读 AAStarCommitteeValidator.sol:380 起，整段读完到下一个函数边界	✅ 恰好 10 个 require、0 个 msg.sender/onlyOwner；对照：同文件 202/249/274/295 的兄弟函数都带 onlyOwner
launchd keeper disabled 且未加载	launchctl print-disabled + 实际 job 状态	✅ disabled、未加载；dvt-node-1/2/3 + autoheal + cloudflared 在跑
三个公共节点 1.13.1、所有 capability enabled:false	直接 curl 三个 /health	✅ 三个都 {"status":"ok","version":"1.13.1"}，capability 全 false
§4 open PR 列表	gh pr list 逐条比	✅ 一致；§5.1 的 #376 确实 OPEN、标题相符
SP 在 898748c5 → 1ac0e1c5 之间 0 个 contracts/src 文件变化	两端 ls-tree 求差，用文档自己给的对照 2d66867f 复算	✅ 0，且对照恰好复现 10（文档给的数字对）
master = 1991e921(2026-09-05)	git log	✅

独立佐证：PR body 自己记录了一次修正 —— 初版"相对链接全部解析"只查了本地文件系统，而 CLAUDE.md 从未提交（.git/info/exclude），在 GitHub 上 404，被 pr-daemon 抓出后在 ec59b09 修正。我独立读到的现象（CLAUDE.md 不在 master tree、却在 .git/info/exclude 里）与这段自述完全吻合。

我驳回了哪些 finding（T3）

R1b（DeepSeek 安全道）提了 2 条，两条我都驳回，并给了实证：

1. [Medium] "提交的文档泄露内部基建：主机名、tunnel ID、EOA 地址、launchd 路径" → 驳回。我逐项查了这些字符串在 origin/master 的公开树里是否本来就有：

   • deploy/tunnel-keepalive.sh:39 → TUNNEL_ID="de08f3f4-1260-4836-bc6d-2860d778986b" # aastar-dvt-testnet（隧道 ID 早就在公开树里，全文），并出现在已提交的 deploy/.run/cloudflared.log:1
   • README.md:38 / deploy/.env.mainnet.example:71 / deploy/x402-provision.sh:133 → dvt1.aastar.io 等主机名，master 里 15 个文件命中
   • 持有者 EOA 0xb5600060… → master 里 10 个文件，含 docs/INTERFACES.md、deploy/.dvt-test-registration.env；验证者 0x7ac7E9d4… → 5 个文件
   • 仓库 visibility=PUBLIC，且被引的三条节点 URL 我自己 curl 通了 —— 文档写的是任何人都能公开读到的东西
   • 另有全量凭据扫描（64-hex 私钥 / JWT / ghp_ / sk- / BEGIN PRIVATE KEY / 助记词 / Bearer / token=）：零命中；只出现变量名 CLOUDFLARE_TUNNEL_TOKEN（§5.2 #317 陷阱的描述，无值）。提交的 env 文件只有 .env.mainnet.example / .env.testnet.example 两个 example。
     → 这条把"区块链上人人都能读的公开状态"和"已在公开树里的字符串"当成了新泄露。它指的东西不新，判据也不成立。

2. [Low] "披露持有者 EOA / 部署者身份 / 零质押 ROLE_DVT 持有者" → 驳回，同因：这些地址在公开仓库的 10 个文件里，且是链上公开可读的所有者/部署者状态。只要仓库是 public，这条就不成立（而它确实是 public —— R1b 显然假定它是私有的）。唯一真正新写进公开面的，是 OrbStack / orbstack-keeper.sh（master 里 0 命中）——即"跑在一台笔记本上"的运维叙事。那不是凭据、不给访问权，且正是这份 handoff 存在的理由。

pre-pr-check（Step 2.7）

规则版本以检查器输出的 checker.git_sha 为准；--profile default，--base 1991e921，head 32b87812。规模：400 行 / 1 文件 / 1 顶层目录 (docs)。两条命中，都是 severity: review（无 block 级命中）：

• SZ-1 · 400 行 > 300（band=over） → 记录在案，不作为阻塞项。理由：这是纯文档单文件新增，没有可执行面；它是"下一任接手者第一眼可用"的快照，拆成两个 PR 会让 §1 治理指令与它引用的状态分离 —— 拆分造成的危害大于它带来的可评审性收益。同时按规则请你在 PR body 里对 SZ-1 作答一句（不说"我跑过了"，而是给出你的处置判断）。
• B2 · docs/HANDOFF.md:348 引用的 docs/design/aoa-balance-mode/03-final-spec.md "不存在" → 这是检查器误报，不需要你作答。该行在 §7 的 "Other repos" 表里，单元格开头就写着 SuperPaymaster；检查器把一个跨仓库路径拿去本仓库解析了。我已经把规则误报记下来并去修规则（升 RULES_VERSION + CHANGELOG + 补自证格），不要求作者迁就误报。不过追这条误报时翻出了一个真问题，见下方建议②。

PR body 里没有检查器那一行，所以按规矩给一句标准提醒：提 PR 前请先跑 bash ~/Dev/tools/PR-daemon/scripts/pre-pr-check.sh --base <base>，block 修掉，review 级命中在 body 里按 ID 回答，并贴一行 pre-pr-check rules <版本> (<commit>)：N 行 / N 文件，block 0，review <ID…>。（本次是文档 PR、且 SZ-1 属我判断为可接受，不因此扣留结论。）

建议（均非阻塞 —— 纯文档 PR 按 Step 5a 的口径，内部精度问题记建议、不打回）

① docs/HANDOFF.md 对 audit.service.ts 的引用范围是 :791-808，实际函数体到 810 才收（791 签名 → 809 return false; // not a member… → 810 }）。实质描述全对，只是尾两行落在引用区间外。改成 791-810 即可。

② §7 第 348 行的 SP 规格指针缺分支限定 —— 它在 main 上不存在。 实测：SuperPaymaster 的 origin/main 里 aoa-balance-mode/ 一个文件都没有（0 命中）；该文件只活在 feat/aoa-balance-mode-5.5.0，最后一次改动是 2026-10-09，提交信息是 docs(spec v4.1.1): step 5c Registry target version is Registry-5.9.0, not 5.8.0。也就是说这是在飞的规格，而表格把它写成"SP 5.5.0 final spec"。同行其它行（worktree 路径、PR 号、tag）本来就指非默认位置，所以这不是说"你写错了"，而是：请补上分支名 —— 照现在这样，读者在 main 上跟着这个指针会得到空。顺带：第 349 行的 PR #445 状态是 MERGED (2026-09-27)，仍可作为定点引用；同一份 attestation 的 Amendment 1 在仍开着的 #446 里，可能值得一并点出。

③ §7 第 353 行的 R0 快照 tag 只在本地，没有推到任何 origin。 实测（逐 remote、单独取退出码，没有走管道）：refs/tags/repcredit-pre550-snapshot-20260913，注解 tag，对象 b7b68f5，2026-09-13 —— YAA / SuperPaymaster / aastar-sdk 三个检出都是 local=1, origin=0。作为"R0 回退锚点"记在 handoff 里，一位新读者 clone 之后是解析不到这个 tag 的。要么 git push --tags，要么在行内注明"local only"。给下一任的东西，最好一次就给全。

覆盖与局限（如实标注，别当成已验）

• requiredQuorum() == type(uint256).max（§2.3）我在这台机器上没能验。 原因：本机无 cast；走 ethers 从 /tmp 跑 node 时先是 ERR_MODULE_NOT_FOUND（ESM 按脚本所在目录解析，不是 cwd），改用 createRequire('ethers/package.json') 又撞 ERR_PACKAGE_PATH_NOT_EXPORTED；artifacts/ 里也没找到该 selector。我没有把"空选择器返回 revert"当作证据——那正是会造出假证据的形状。第二个 RPC 端点返回了一张 Apache 404 HTML。这条标记为未验证，不是已通过。
  • 一个相关的旁证（不是对 §2.3 的证实，只是不矛盾）：origin/master 的公开树里已提交了 deploy/.run/heartbeat-health.log，其 2026-08-31 的记录写着 "requiredQuorum":2,"activeCount":3。那是 8 月底的旧态，与文档所述"此后（epoch 184283 起）fail-closed"在时间上不冲突；它同时说明这套 quorum/节点数读数本来就在公开面，进一步支持对 R1b 第 1 条的驳回。
  • 顺带（先于本 PR 存在的问题，不算在这个 diff 头上）：deploy/.run/*.log 这类运行产物被提交进了公开树。是否该 .gitignore，是仓库层面的事，与本 PR 无关。

与上一轮结论的关系

结论 与上一轮一致：APPROVE，且是同一棵树（同 sha）。本轮没有新发现指出该文件有事实错误——§1/§2/§4/§5/§7 里我能机械核的每一条都复现了，包括文档自己给出的对照值（2d66867f → 恰好 10）。上面三条建议是新的、非阻塞的可用性改进，不改变裁决。