pi-lens 4.4.4 → 4.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +45 -3
  3. package/config/biome/core.jsonc +3 -3
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -0
  5. package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
  6. package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
  7. package/dist/chunk-2F47TQOA.js +73 -0
  8. package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
  9. package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
  10. package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
  11. package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
  12. package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
  13. package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
  14. package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
  15. package/dist/chunk-4WX4CTUE.js +57 -0
  16. package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
  17. package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
  18. package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
  19. package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
  20. package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
  21. package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
  22. package/dist/chunk-A3YNG5KP.js +45 -0
  23. package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
  24. package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
  25. package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
  26. package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
  27. package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
  28. package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
  29. package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
  30. package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
  31. package/dist/chunk-CFRQMBGP.js +49 -0
  32. package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
  33. package/dist/chunk-CKEQFGLT.js +32 -0
  34. package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
  35. package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
  36. package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
  37. package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
  38. package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
  39. package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
  40. package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
  41. package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
  42. package/dist/chunk-FJIVKLPH.js +31 -0
  43. package/dist/chunk-G2B7F6ZU.js +88 -0
  44. package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
  45. package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
  46. package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
  47. package/dist/chunk-GTAI2J6U.js +27 -0
  48. package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
  49. package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
  50. package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
  51. package/dist/chunk-IPDG45G5.js +26 -0
  52. package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
  53. package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
  54. package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
  55. package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
  56. package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
  57. package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
  58. package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
  59. package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
  60. package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
  61. package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
  62. package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
  63. package/dist/chunk-NDMCVUYK.js +507 -0
  64. package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
  65. package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
  66. package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
  67. package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
  68. package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
  69. package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
  70. package/dist/chunk-P4QNXS6I.js +27 -0
  71. package/dist/chunk-PKES3ISE.js +297 -0
  72. package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
  73. package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
  74. package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
  75. package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
  76. package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
  77. package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
  78. package/dist/chunk-Q6D6VMI4.js +22 -0
  79. package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
  80. package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
  81. package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
  82. package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
  83. package/dist/chunk-SCIUNBPF.js +44 -0
  84. package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
  85. package/dist/chunk-SXGD4ANG.js +25 -0
  86. package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
  87. package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
  88. package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
  89. package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
  90. package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
  91. package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
  92. package/dist/chunk-UHGF5UT5.js +32 -0
  93. package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
  94. package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
  95. package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
  96. package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
  97. package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
  98. package/dist/chunk-VQH24FIP.js +37 -0
  99. package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
  100. package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
  101. package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
  102. package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
  103. package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
  104. package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
  105. package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
  106. package/dist/chunk-XCUHKYCQ.js +23 -0
  107. package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
  108. package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
  109. package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
  110. package/dist/chunk-YRD4ISED.js +30 -0
  111. package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
  112. package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
  113. package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
  114. package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
  115. package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
  116. package/dist/chunk-ZUUI3ZSA.js +38 -0
  117. package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
  118. package/dist/index.js +32674 -27567
  119. package/dist/mcp/analyze-cli.js +11 -12
  120. package/dist/mcp/cli.js +46 -45
  121. package/dist/mcp/server.js +1210 -574
  122. package/dist/mcp/worker.js +65 -65
  123. package/dist/probes/installer.js +21 -23
  124. package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
  125. package/docs/adr/README.md +1 -0
  126. package/docs/agent-tools.md +28 -7
  127. package/docs/ast-grep_rules_catalog.md +5 -3
  128. package/docs/configuration.md +12 -1
  129. package/docs/defect-shapes.md +738 -0
  130. package/docs/engineering-principles.md +12 -0
  131. package/docs/environment-variables.md +20 -0
  132. package/docs/features.md +16 -1
  133. package/docs/globalconfig.md +37 -8
  134. package/docs/invariants/caches-stores.md +30 -0
  135. package/docs/invariants/dispatch-runners.md +164 -0
  136. package/docs/invariants/git-guard-host.md +53 -0
  137. package/docs/invariants/language-config.md +31 -0
  138. package/docs/invariants/lsp-trust-exec.md +286 -0
  139. package/docs/invariants/paths-os.md +59 -0
  140. package/docs/invariants/session-telemetry.md +74 -0
  141. package/docs/lsp-capability-matrix.md +105 -12
  142. package/docs/lsp-idle-eviction.md +37 -18
  143. package/docs/pi-lens-fixer.md +24 -2
  144. package/docs/pi-lens-investigator.md +14 -0
  145. package/docs/pi-lens-merge-policy.md +32 -17
  146. package/docs/pi-lens-monitor.md +66 -10
  147. package/docs/pi-lens-orchestration.md +41 -0
  148. package/docs/pi-lens-release.md +20 -0
  149. package/docs/pi-lens-retro.md +5 -4
  150. package/docs/pi-lens-reviewer.md +54 -7
  151. package/docs/pi-lens-subagent.md +10 -3
  152. package/docs/release-qa-baseline.md +19 -7
  153. package/docs/servercapabilities.md +47 -47
  154. package/docs/settings.md +9 -5
  155. package/docs/subagent-compat.md +1 -1
  156. package/docs/usage.md +1 -0
  157. package/package.json +8 -5
  158. package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
  159. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
  160. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
  161. package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
  162. package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
  163. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
  164. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
  165. package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
  166. package/rules/rule-catalog.json +25 -1
  167. package/scripts/analyze-pi-lens-logs.mjs +15 -5
  168. package/scripts/lib/is-main-module.mjs +27 -0
  169. package/scripts/lib/scratch-home-env.mjs +21 -0
  170. package/scripts/rpc-load-check.mjs +4 -6
  171. package/scripts/warm-loader-cache.mjs +2 -5
  172. package/dist/chunk-3PTHXJXR.js +0 -28
  173. package/dist/chunk-3QED2P4V.js +0 -31
  174. package/dist/chunk-5WRPDP2A.js +0 -47
  175. package/dist/chunk-ABBOA7UD.js +0 -157
  176. package/dist/chunk-CUHSHSB6.js +0 -273
  177. package/dist/chunk-GL5LUMZE.js +0 -51
  178. package/dist/chunk-HAD7QRQI.js +0 -30
  179. package/dist/chunk-JORED7EX.js +0 -44
  180. package/dist/chunk-KYUB6QDC.js +0 -72
  181. package/dist/chunk-LZSEQW6A.js +0 -57
  182. package/dist/chunk-M2IFVFWU.js +0 -79
  183. package/dist/chunk-M2UD3LPU.js +0 -88
  184. package/dist/chunk-MBKQHGA7.js +0 -39
  185. package/dist/chunk-R7YOCSNV.js +0 -23
  186. package/dist/chunk-SKAMFC7A.js +0 -28
  187. package/dist/chunk-SYE6T2EB.js +0 -28
  188. package/dist/chunk-TRETHTQO.js +0 -26
  189. package/dist/chunk-UA7ZXYDR.js +0 -184
  190. package/dist/chunk-XTFDJI3T.js +0 -24
  191. package/dist/chunk-Z3CCVDUB.js +0 -76
@@ -15,7 +15,7 @@ respawned server reports every finding it reported before eviction; the
15
15
  content-bound coverage check the auxiliary freeze depends on. A server that
16
16
  cannot demonstrate it is never proposed for eviction on perf grounds alone.
17
17
 
18
- _Last generated: 2026-10-18 on linux; 49 registry servers: 17 eligible, 0 vetoed, 18 inconclusive, 14 unavailable (0 not reached: budget)._
18
+ _Last generated: 2026-10-25 on linux; 49 registry servers: 33 eligible, 0 vetoed, 2 inconclusive, 14 unavailable (0 not reached: budget)._
19
19
 
20
20
  ## Per-server rows
21
21
 
@@ -35,59 +35,78 @@ step log only, because it flaps.
35
35
 
36
36
  | server | role | declared | result | reason | respawn | coverage |
37
37
  |---|---|---|---|---|---|---|
38
- | ast-grep | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
38
+ | ast-grep | auxiliary | unmeasured | eligible | · | ok | preserved |
39
39
  | bash | primary | transparent | eligible | · | ok | preserved |
40
40
  | clojure | primary | transparent | eligible | · | ok | preserved |
41
41
  | cmake | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
42
42
  | cpp | primary | transparent | eligible | · | ok | preserved |
43
43
  | csharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
44
44
  | css | primary | transparent | eligible | · | ok | preserved |
45
- | cue | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
45
+ | cue | primary | unmeasured | eligible | · | ok | preserved |
46
46
  | dart | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
47
47
  | deno | primary | transparent | eligible | · | ok | preserved |
48
48
  | docker | primary | transparent | eligible | · | ok | preserved |
49
- | docker-official | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
49
+ | docker-official | primary | unmeasured | eligible | · | ok | preserved |
50
50
  | elixir | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
51
- | expert | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
51
+ | expert | primary | unmeasured | eligible | · | ok | preserved |
52
52
  | fish | primary | transparent | eligible | · | ok | preserved |
53
53
  | fsharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
54
- | gleam | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
54
+ | gleam | primary | unmeasured | eligible | · | ok | preserved |
55
55
  | go | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
56
56
  | haskell | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
57
57
  | html | primary | transparent | eligible | · | ok | preserved |
58
58
  | java | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
59
59
  | json | primary | transparent | eligible | · | ok | preserved |
60
- | kotlin | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
60
+ | kotlin | primary | unmeasured | eligible | · | ok | preserved |
61
61
  | lean | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
62
- | lua | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
62
+ | lua | primary | unmeasured | eligible | · | ok | preserved |
63
63
  | marksman | primary | transparent | eligible | · | ok | preserved |
64
64
  | nix | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
65
65
  | ocaml | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
66
66
  | omnisharp | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
67
67
  | opengrep | auxiliary | transparent | eligible | · | ok | preserved |
68
68
  | php | primary | transparent | eligible | · | ok | preserved |
69
- | powershell | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
69
+ | powershell | primary | unmeasured | eligible | · | ok | preserved |
70
70
  | prisma | primary | transparent | eligible | · | ok | preserved |
71
71
  | python | primary | transparent | eligible | · | ok | preserved |
72
72
  | python-jedi | primary | transparent | eligible | · | ok | preserved |
73
73
  | ruby | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
74
- | rust | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
74
+ | rust | primary | unmeasured | eligible | · | ok | preserved |
75
75
  | shuck | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
76
- | svelte | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
76
+ | svelte | primary | unmeasured | eligible | · | ok | preserved |
77
77
  | swift | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
78
- | terraform | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
79
- | tinymist | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
80
- | toml | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
78
+ | terraform | primary | unmeasured | eligible | · | ok | preserved |
79
+ | tinymist | primary | unmeasured | eligible | · | ok | preserved |
80
+ | toml | primary | unmeasured | eligible | · | ok | preserved |
81
81
  | typescript | primary | transparent | eligible | · | ok | preserved |
82
- | typos | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
82
+ | typos | auxiliary | unmeasured | eligible | · | ok | preserved |
83
83
  | vue | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
84
84
  | yaml | primary | transparent | eligible | · | ok | preserved |
85
- | zig | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
86
- | zizmor | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
85
+ | zig | primary | unmeasured | eligible | · | ok | preserved |
86
+ | zizmor | auxiliary | unmeasured | eligible | · | ok | preserved |
87
87
 
88
88
  ## Declared versus measured
89
89
 
90
- No divergence between declared policy and this run's measurement.
90
+ `drift` means the registry evicts a server the measurement vetoes. A `proposal`
91
+ or `info` line is for a maintainer to act on in a follow-up; this run changed
92
+ nothing.
93
+
94
+ - **ast-grep** [proposal] declared unmeasured but eviction and respawn preserved its findings
95
+ - **cue** [proposal] declared unmeasured but eviction and respawn preserved its findings
96
+ - **docker-official** [proposal] declared unmeasured but eviction and respawn preserved its findings
97
+ - **expert** [proposal] declared unmeasured but eviction and respawn preserved its findings
98
+ - **gleam** [proposal] declared unmeasured but eviction and respawn preserved its findings
99
+ - **kotlin** [proposal] declared unmeasured but eviction and respawn preserved its findings
100
+ - **lua** [proposal] declared unmeasured but eviction and respawn preserved its findings
101
+ - **powershell** [proposal] declared unmeasured but eviction and respawn preserved its findings
102
+ - **rust** [proposal] declared unmeasured but eviction and respawn preserved its findings
103
+ - **svelte** [proposal] declared unmeasured but eviction and respawn preserved its findings
104
+ - **terraform** [proposal] declared unmeasured but eviction and respawn preserved its findings
105
+ - **tinymist** [proposal] declared unmeasured but eviction and respawn preserved its findings
106
+ - **toml** [proposal] declared unmeasured but eviction and respawn preserved its findings
107
+ - **typos** [proposal] declared unmeasured but eviction and respawn preserved its findings
108
+ - **zig** [proposal] declared unmeasured but eviction and respawn preserved its findings
109
+ - **zizmor** [proposal] declared unmeasured but eviction and respawn preserved its findings
91
110
 
92
111
  ## Reasons
93
112
 
@@ -14,11 +14,29 @@ Before mocking a `clients/` module, look for its test seam (`set*`, `adopt*`, or
14
14
  `reset*`). The pre-flight must list the mock dependents of any module whose
15
15
  exports change.
16
16
 
17
+ A new test starts from `tests/support/`: a registration question (flags,
18
+ tools, commands, declarations) goes through tier 1
19
+ (`tests/support/pi-runner.ts`, a real `ExtensionRunner`), a session-flow case
20
+ through tier 2 (`tests/support/pi-session.ts`), and a JSON-lines sink through
21
+ `readNdjsonRows` (`tests/support/ndjson-rows.ts`), asserting `skipped === 0`
22
+ when the claim needs the complete output. No fake of an in-process store or
23
+ registry; other doubles only as `AGENTS.md` admits them.
24
+
17
25
  - Trace the production entry point and reproduce the defect through it
18
26
  (principles §1, "Premise first"). Name no seam before the reproduction; the
19
27
  red reproduction is your feedback loop, built before any theory of the fix.
28
+ Reproduce on the reporter's pi host and pi-lens version, taken from the
29
+ report or its session log. When that version cannot be installed, name the
30
+ one you used instead; never substitute the latest silently. Report
31
+ `confirmed`, `partially confirmed` (name what differed), `not reproduced`
32
+ (name what you tried), or `blocked` (name the missing access or state).
20
33
  - Climb the minimalism ladder before screening against the `AGENTS.md`
21
34
  catalog: the catalog says what must not break, never what to add.
35
+ - Mechanism for a race, security edge case or failure nobody has reproduced is
36
+ not built in the round (principles §1, speculative robustness). Name its
37
+ trigger path, evidence and cost under scope at the top of the hand-back, and
38
+ leave the decision to the maintainer. Validation, error handling and security
39
+ at a real trust boundary are still required.
22
40
  - Check which open PRs touch your files (`gh pr list`, `gh pr diff`), design to
23
41
  compose, and flag merge order in the PR body. Branch `fix/<N>-<slug>` from
24
42
  `origin/master` unless the brief names a branch. Preserve contributor
@@ -236,7 +254,10 @@ rigor (#2599).
236
254
  `## Observability` (a record literal from the runtime diff, `none: <reason>`,
237
255
  or exactly `No new failure path; no record added.`, which a new decision
238
256
  branch on a session, lifecycle or delivery seam refuses, #3875),
239
- `## Class sweep`, and `## Test assessment`. A brief that names only some
257
+ `## Class sweep`, `## Fold check` (one line per candidate, `#N folded`,
258
+ `#N not folded` or `#N sequenced`, then its reason, or `none: <reason>`;
259
+ the body lint owns the form and the local script owns the candidate list,
260
+ #4711), and `## Test assessment`. A brief that names only some
240
261
  headings does not shorten this list. The closing keyword lives in the body;
241
262
  GitHub ignores it in a title.
242
263
  - Run `node scripts/check-pr-body.mjs --lint-local PR_BODY.md` and
@@ -272,7 +293,8 @@ rigor (#2599).
272
293
  (#4439).
273
294
  - A `Shape: new: <name>` is a proposal, not a catalog entry: write the
274
295
  proposed shape text in the PR body under "Proposed contract change
275
- (maintainer decision)" and never edit `AGENTS.md`. Catalog shapes and rule
296
+ (maintainer decision)" and never edit `docs/defect-shapes.md`. Catalog shapes
297
+ and rule
276
298
  changes are the maintainer's decision; the orchestrator lands an approved
277
299
  one in its own change (#4577's fixer added shape 74 unasked, and the
278
300
  governance suites redded).
@@ -17,6 +17,12 @@ issue and the requested evidence surface.
17
17
 
18
18
  ## Evidence sources
19
19
 
20
+ The log root is the monitored process's, resolved as in
21
+ `docs/pi-lens-monitor.md` "Inputs": a non-empty `PI_LENS_HOME`, then any
22
+ probe-home redirect, then `~/.pi-lens`. The paths below assume the default.
23
+ Rotation also writes timestamped archives; pass `--archived` to the analyzer
24
+ to read them.
25
+
20
26
  - `~/.pi-lens/latency.log` and its `.1` rotation: per-touch records
21
27
  (`lsp_touch_file`, `lsp_aux_wait_outcome`, `availability_decision`,
22
28
  `lsp_scanner_coverage_gap`, breaker and deferral events). Rotation is by size:
@@ -62,6 +68,14 @@ issue and the requested evidence surface.
62
68
 
63
69
  ## Reproducible behavior
64
70
 
71
+ Reproduce on the reporter's pi host version and pi-lens version, taken from
72
+ the report or its session log. When you cannot install that version, say so
73
+ and name the version you used instead. Never substitute the latest silently.
74
+ Report one of four outcomes: confirmed, partially confirmed (name what
75
+ differed), not reproduced (name what you tried), or blocked (name the missing
76
+ access or state). Our bugs often depend on the host version; #4690 raises the
77
+ certified floor to 0.86.1.
78
+
65
79
  When the symptom reproduces, the loop comes before the reading. Build the
66
80
  tightest loop that goes red on the symptom (a failing test, a minimal driver, a
67
81
  differential run), confirm it matches the reporter's exact symptom, and
@@ -21,9 +21,9 @@ reachable.
21
21
 
22
22
  Every PR body starts with `## Why`, `## Notes for the reviewer`, and
23
23
  `## Change outline`, followed by the existing `## Summary`, `## Tests`,
24
- `## Blast radius`, `## Class sweep`, and `## Observability` sections. The
25
- change outline is the changed symbol's caller/callee tree with `+`/`-` on
26
- moved lines; include only structural views that changed.
24
+ `## Blast radius`, `## Class sweep`, `## Observability`, and `## Fold check`
25
+ sections. The change outline is the changed symbol's caller/callee tree with
26
+ `+`/`-` on moved lines; include only structural views that changed.
27
27
 
28
28
  ## The loop, per PR
29
29
 
@@ -186,12 +186,12 @@ bound helper because the brief deferred the fold without a reason.
186
186
 
187
187
  ## External reports (orchestrator)
188
188
 
189
- The contract lives in AGENTS.md, "Issue triage (standing rule)" — assess the
189
+ This section is the contract; AGENTS.md "Issue triage & labels" holds the labels only. Assess the
190
190
  report against the code before accepting or dispatching, ask the one or two
191
191
  facts that would change the design, **do not dispatch work that depends on an
192
192
  unanswered load-bearing question**, mirror the answer on the issue and point
193
193
  the worker there rather than at a paraphrase, and cite the reporter's reasoning
194
- as authority. Read it there; this section only points at it.
194
+ as authority. The steps above are the whole contract.
195
195
 
196
196
  The train-specific consequence: an external lane's first dispatch is often
197
197
  worth delaying by one exchange. On 2026-09-12 a fixer was dispatched on #3000
@@ -236,6 +236,9 @@ re-verification; small code folds carry a red-first test and return to the same
236
236
  reviewer. File only different-seam, blocked, decision-dependent, untouched
237
237
  pre-existing, or risk-class-changing items, as one consolidated issue per PR.
238
238
 
239
+ Folds also decide the issue list itself, one step earlier than a review
240
+ finding: `docs/pi-lens-orchestration.md` states that check.
241
+
239
242
  A brief carries the lane's facts and the task, and points at the role
240
243
  contract for everything else. Lane facts are the worktree, branch, base,
241
244
  TMPDIR, test-worker cap, Git grant, and deliverable path. It never restates
@@ -258,15 +261,15 @@ These are the habits the train depends on. They live here, not in any one
258
261
  operator's private notes, so a different orchestrator can run the same train.
259
262
 
260
263
  - **Contracts move in the same session.** When a review or a dogfood finding
261
- reveals a defect CLASS (not an instance), add a numbered shape to AGENTS.md's
262
- catalog with the issue ref and a one-line screen, extend the fixer's screen
264
+ reveals a defect CLASS (not an instance), add a numbered shape to the defect-shape
265
+ catalog (`docs/defect-shapes.md`) with the issue ref and a one-line screen, extend the fixer's screen
263
266
  list, and cite the number in the next brief — before the next dispatch. "To
264
267
  err twice is not the mark of a wise man." (2026-09-03: shapes 28–36 came out
265
268
  of one day's reviews this way.)
266
269
  - **Second instance of a catalogued shape opens the consolidation lane, not a
267
270
  third instance fix (2026-09-09).** The trigger is the shape recurring at all,
268
271
  not only twice in one session: when a review, an issue or a dogfood finding
269
- is the second member of a shape already in AGENTS.md's catalog, the
272
+ is the second member of a shape already in the defect-shape catalog, the
270
273
  orchestrator files the consolidation lane BEFORE the second instance merges,
271
274
  with three fixed deliverables: one seam every consumer calls, one log line
272
275
  per resolution (which value was chosen and why, throttled once per key per
@@ -309,7 +312,7 @@ operator's private notes, so a different orchestrator can run the same train.
309
312
  | a change that touches identifier uses of a glossary-retired synonym | run `tests/config/glossary-synonym-sweep.test.ts` on the head AND on the merge with `origin/master`, then re-pin in the PR from the sweep's own `UNPINNED`/`STALE` output — #3279, #3283, #3284, #3288 |
310
313
  | a new `vi.mock` in a test file | run `tests/config/vi-mock-export-sweep.test.ts`; whole-module mocks of a production module must spread `importOriginal` — PR #3268's CI red, fixed by trailing commit `621d61c5c` |
311
314
  | a changelog fragment | front matter `section: <Section>` plus `audience: user` or `audience: internal` and exactly one top-level entry; new user entries open with a bold lead of at most 100 characters (refs excluded), never `CHANGELOG.md`, validated by `node scripts/check-changelog-fragments.mjs` — PR #3268 r1 shipped `category:` and a paragraph |
312
- | a PR body | the header gate: exactly one-sentence `## Why`, `## Notes for the reviewer`, `## Change outline`, plus Summary / Tests with `### Test assessment` / Blast radius / Class sweep / Observability; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
315
+ | a PR body | the header gate: exactly one-sentence `## Why`, `## Notes for the reviewer`, `## Change outline`, plus Summary / Tests with `### Test assessment` / Blast radius / Class sweep / Fold check / Observability; run `node scripts/check-pr-body.mjs --lint-local` before pushing — three PRs this week needed orchestrator body edits |
313
316
  | a whole-tree docs restructure of `AGENTS.md` | every governance test that reads `AGENTS.md`, with markers on their own lines — PR #3265 r1 |
314
317
  | a raw poll in a test | the flake-shape ratchet; the fix is the governed wait, never a header admission — #2781 r1 |
315
318
  | a new, renamed or deleted rule file under `rules/` | `npm run docs:rule-catalogs` and commit the generated catalog; `tests/scripts/rule-catalogs.test.ts` is a strict consumer of every rule file, not of rule ids — #3214 r1 |
@@ -432,7 +435,8 @@ operator's private notes, so a different orchestrator can run the same train.
432
435
  `final-review`; NOT borrowed from it: auto-fixing null checks, error
433
436
  handling or cleanup hooks, which change meaning.
434
437
  - **Allocate the catalog number at MERGE, not at dispatch (2026-09-15).**
435
- AGENTS.md's defect-shape catalog is a markdownlint MD029 ordered list: the
438
+ The defect-shape catalog (`docs/defect-shapes.md`) is a markdownlint MD029
439
+ ordered list: the
436
440
  number is the list position, so dispatch-time reservations create a gap on
437
441
  branches whose holder has not merged. The orchestrator owns allocation; a
438
442
  lane may draft a shape but must not claim a number. At merge, insert or
@@ -460,8 +464,8 @@ operator's private notes, so a different orchestrator can run the same train.
460
464
  (so `Ast-grep self-scan` or `Audit production dependencies` reads as what
461
465
  it is, not as a test failure), its `FAIL` and assertion lines and the
462
466
  `Tests` summary with the ANSI codes stripped, the gating and advisory
463
- counts on separate lines (advisory reds never gate, and are read before
464
- merging), and the remedy hint: `gh run rerun <run>` for a cancelled or
467
+ counts on separate lines (an advisory red gates only when master is green
468
+ on that lane, and every red is read before merging), and the remedy hint: `gh run rerun <run>` for a cancelled or
465
469
  superseded run, the `gh api -X POST .../approve` command for fork
466
470
  approval, `gh pr update-branch <pr>` when the failed merge's base is no
467
471
  longer master's head (a rerun replays the old merge commit, #3660). A job
@@ -508,7 +512,7 @@ operator's private notes, so a different orchestrator can run the same train.
508
512
  Apart from `--approve-fork`, `--rerun-cancelled` and `--sync-main`, which you
509
513
  pass by name, it never approves, reruns or updates a branch: it prints the
510
514
  command.
511
- - **Read the advisory rows before merging, even though they never gate
515
+ - **Read the advisory rows before merging, even where they do not gate
512
516
  (2026-09-12).** The exit-code rule above is right and stays: never text-match
513
517
  the verdict table for `failure`, because advisory rows print `failure` on a
514
518
  green PR. But "does not gate" is not "carries no information", and filtering
@@ -559,7 +563,8 @@ operator's private notes, so a different orchestrator can run the same train.
559
563
  If that layer does not exist, file it as an issue with the bug as
560
564
  its named recurrence — the same standard shapes are held to. The lesson
561
565
  names the defect SHAPE and its tree-wide enforcer, not only a test for the
562
- instance: the Gap names the `AGENTS.md` catalog shape (or a new shape) and
566
+ instance: the Gap names the `docs/defect-shapes.md` catalog shape (or a new
567
+ shape) and
563
568
  either a test that scans the whole population, an issue to build one, or
564
569
  `judgment-only` with the reason. A one-bug test is the fix's regression
565
570
  test, not the closed gap (lint half: #4439). The ledger
@@ -677,6 +682,10 @@ Each row cost a lane at least once; the prose above carries the record.
677
682
  | Dispatching a fixer on an issue's text without checking it against the code | Grep the claimed gap on master before the brief. A stale premise turns the lane into a no-op or a witness-only PR |
678
683
  | Writing off a worker's reds as "sandbox" without a same-env base run | Accept a sandbox attribution only with the same test names red on origin/master under the same env vars. Hundreds of guard reds can hide one real red |
679
684
  | Folding a reviewer's remedy after running only the file the reviewer named | Run every test that references the changed symbol (`rg -l <symbol> tests`) before pushing a fold |
685
+ | Refreshing a census or matrix cell from a probe artifact | shape 76: the row must come from the subject's own emitter, never from an order-sensitive drain (#4615) |
686
+ | Reading a cancelled shard as a failure, or assuming a rerun clears it | shape 77: check the shard's own step conclusions and its measured runtime against the cap (#4672) |
687
+ | Admitting a third-party cache directory at the shared tmp root by name | shape 78: pin the loader's cache off and keep a planted sibling red (#4673) |
688
+ | Writing bytes ahead of the newest message (a returned `context` list, a tool-set change) without measuring the provider prefix | shape 79: write at the tail only, count a tool-set change as one full rewrite on a collapsing model, and compare the head and pi-ai's collapsed head across two real-session requests |
680
689
  | Pushing with `-q` or a grep filter, then landing on whatever the PR head is | Read the push result unfiltered, check `git merge-base --is-ancestor <intended> origin/<branch>`, and land with `EXPECT_HEAD=<intended or its merge>` |
681
690
  | Gating a background step on `until ! pgrep -f '<pattern>'` | That command line matches itself and never exits. Chain the steps in one command, or wait on a PID |
682
691
  | Editing an orchestrator script while a chain or monitor runs it | Stop the chain first, or write a new file and `mv` it into place |
@@ -795,7 +804,7 @@ Each row cost a lane at least once; the prose above carries the record.
795
804
  | Matching a flake on text that CI never prints | The unmatched CI output was noticed during review; the matcher test should have used a captured CI transcript. The flake matcher now keys on the classifier's actual output. |
796
805
  | Letting keyword-title lint contradict the repository convention | The title gate review found the contradiction; the title-convention test should have pinned the accepted form. The lint rule now follows the repository's title convention. |
797
806
  | Relaying a shard failure to a fixer without mirroring it on the PR | The fixer noticed the missing scope record; the scope-mirror hook should have rejected the handoff. The handoff path now records the scope on the PR before dispatch. |
798
- | Treating a repeatedly red advisory lane as harmless | The maintainer's retrospective found the 21% flake after a misleading PR draw; the advisory policy and newest-master comparison should have held the PR. `land.sh` now holds a PR-red/master-green advisory unless `ADVISORY_OK=1`. |
807
+ | Treating a repeatedly red advisory lane as harmless | The maintainer's retrospective found the 21% flake after a misleading PR draw. The advisory policy and newest-master comparison should have held the PR. `merge-on-green.sh` now holds any advisory check red on the PR and green on master. `ADVISORY_OK='<lane>: <reason>'` must name the judgment; it refuses a bare `1`. #4540 (2026-10-17) and #4848 (2026-10-25) landed past such a red. |
799
808
  | Forgetting to arm the landing chain after a trailing fix | A later PR-GREEN event exposed that the fix was waiting unarmed; the trailing-fix command should have verified arming. Rule: after a trailing fix, arm `land.sh` in the same step (not yet mechanised). |
800
809
  | Accepting an identity trade-off without a complete timing-cell table | Cloud verification found primary-item loss after the trade-off was accepted from prose; the fixer's state table and review should have enumerated every timing cell. The brief now requires the complete state table before accepting the trade-off. |
801
810
  | Letting a scoped test exceed Vitest's default timeout | A repeated cloud review caught the timeout; the local targeted run should have exercised the test under its default timeout. Rule: a scoped review runs new tests under the default Vitest timeout before passing them (not yet mechanised). |
@@ -814,7 +823,7 @@ Each row cost a lane at least once; the prose above carries the record.
814
823
  | Routing on the word "governance" instead of the risk | #4350 (a CodeQL pin-equality test) went to Opus as "governance authoring"; the Opus rule is for source-scanning detectors only. |
815
824
  | Leaving the `dist/` precondition undeclared | At least 5 lanes (#4417, #4418, the #4422 verify, the #4410 r1 review, the #4423 review F5) each ruled out the same 3 census reds that need `npm run build:dist` (2026-10-14). Mechanical: fail fast when a selected test needs `dist/` and it is missing or stale (#4436); `CLAUDE.md` names `npm run build:dist` for those files meanwhile |
816
825
  | A wait helper with a fixed wall-clock budget | `interleaving-kit` `waitFor` ran out at 3000 ms under CI load (run 38618401454, `tests/clients/fix-run-restore.test.ts:378`); the file passed alone and under 3 shuffle seeds, so the red read as a flake. Mechanical, filed as #4437 |
817
- | Briefing a worker to "report the size first" before a large migration | A worker cannot wait for a reply, so the #4432 fixer did the migration anyway (2026-10-14). A brief authorizes the conditional branch with its bound, or tells the worker to stop and hand back; `AGENTS.md` "Orchestration and delegated work" |
826
+ | Briefing a worker to "report the size first" before a large migration | A worker cannot wait for a reply, so the #4432 fixer did the migration anyway (2026-10-14). A brief authorizes the conditional branch with its bound, or tells the worker to stop and hand back; `docs/pi-lens-orchestration.md` |
818
827
  | Naming a file by basename in a brief | "index.ts" meant `clients/lsp/index.ts`; a Haiku measurement pass searched the root `index.ts` and reported the #2052 comment missing (2026-10-14). Name every file by its repo path |
819
828
  | Sending a lane that must find its own failure space to Haiku | #4342 rounds 1 and 2 left three review findings (a wall-clock bound, a wrong offline premise, a 13-vs-20 population); a fresh Opus round with a state table passed verify first time (#4410 round 3). Haiku folds with a prescribed remedy (#4340, #4341, #4345, #4356, #4368, #4372, #4374, #4417) landed first try. Haiku takes only a prescribed change; `AGENTS.md` "Orchestration and delegated work" |
820
829
  | Listing a blast radius without the changed result's callers | #4411 round 3 changed `touchFile`'s result and the body omitted the cascade neighbour caller (`clients/dispatch/integration.ts:2139`), which then printed an uncaused "inconclusive" line every turn (review N2). `AGENTS.md` already requires `module_report` with `blastRadius: true` before and after; run it for the changed result and quote every caller, then read each one |
@@ -823,7 +832,7 @@ Each row cost a lane at least once; the prose above carries the record.
823
832
  | Concluding "no existing seam does this" from a search of your own call names | #4528 searched `notifyExternalFileChange\(` and missed six freshness modules in `clients/`; five detectors ended up wiring their own consumers (#4535). Search by primitive (`docs/pi-lens-fixer.md` "Before code"); the reviewer widens the query (`docs/pi-lens-reviewer.md`, #4536) |
824
833
  | Importing `dist/` from a script a workflow runs before any build | #4525's `scripts/assert-evaluated.mjs` reached `dist/` through `lib/clean-signal.mjs`, so `tool-smoke-prs` would fail on every refresh PR. #4531 pins the import graph with a test and plants |
825
834
  | Pinning workflow step shell as text instead of running it | #4531 r1: four mutations of the Swift, APFS and handshake shell survived, including deleting `set +e`. Run the extracted step shell against stubs in a test |
826
- | Filing gap after gap on one mechanism without an audit | Eleven freshness gaps went into #4532 before anyone asked why there were eleven; the cause was one missing fan-out (#4535). Three issues on one mechanism open a consolidation audit (`AGENTS.md` "Orchestration and delegated work") |
835
+ | Filing gap after gap on one mechanism without an audit | Eleven freshness gaps went into #4532 before anyone asked why there were eleven; the cause was one missing fan-out (#4535). Three issues on one mechanism open a consolidation audit (`docs/pi-lens-orchestration.md`) |
827
836
  | Landing with an unresolved bot review thread | #4548 and #4558 merged with open Greptile threads (2026-10-17); each one's disposition arrived or never did, and nothing held the land. Every bot thread gets a disposition reply and is resolved before the merge (step 1 and step 4 of "The loop, per PR") |
828
837
  | Pushing a worker tree on a stale "failed" settlement | The #4575 r5 settlement read as failed while its resumed turn was live and about to push (plegma #752). The orchestrator's push-verify now refuses a tree with a live agent process, and its wait loop takes a `turnId`. |
829
838
  | Settling a fix round with unpushed commits | #4582 r1 settled with the commits still local and nobody noticed (plegma #753). The settlement hook now prints `UNPUSHED` or `DIRTY` for the tree it just settled. |
@@ -837,3 +846,9 @@ Each row cost a lane at least once; the prose above carries the record.
837
846
  | Pushing to a PR branch while a fix round is queued against its old head | Merging master into #4594 staled the queued round's lease; the worker pushed a diverged copy to its handle branch (plegma #723). The orchestrator's push-verify refuses while a round still publishes to that branch. |
838
847
  | Resuming a reviewer without naming the deliverable | The resumed verifies of #4575 and #4593 inherited report names that did not match the brief, so the hand-back missed the report. Every resumed round names its `deliverables` explicitly. |
839
848
  | Calling an issue "blocked on a release" without reproducing it on master | #4554 waited on a release; 58 runs on master did not reproduce it, and it closed crediting #4563. Reproduce on master before naming a blocker. |
849
+ | Bolding a residual bullet (`- **p3 (LOW, live 0):**`) under `## Accepted residuals` | The tracker parser read only a bare `p3`, so #4832's three residuals were recorded as "none" (2026-10-25). `known-gap-add.sh` now reads the bold form, pinned by its test case (g) |
850
+ | Planning a tracker layout before measuring the platform's limits | An 11-issue pinned split was proposed and dispatched; GitHub pins 3 issues per repository, and the assumed 65k body cap was already exceeded by #4626 at 91k (2026-10-25). Measure the limit first, then plan |
851
+ | Pasting the `claude-lane.sh` header into a brief | The header began `Worktree (created, ...):`, the brief guard wants `Worktree:`, and two dispatches were refused (2026-10-25). The header now starts with `Worktree:`, pinned by `test-claude-lane-header.sh` |
852
+ | Linting a PR body in the main checkout | The main checkout sits on another branch, so citations resolved against the wrong tree; three edits needed a hand-built head tree (2026-10-25). `pr-body.sh edit` without `--tree` now builds a temp tree at the PR head |
853
+ | Guessing issue labels (`area:ci`, `area:formal`, `chore`) | Three filings were refused, and the refusal listed only priority labels (2026-10-25). `file-issue.sh` now lists the known type, area and priority labels |
854
+ | Reaping a lane whose issue is closed while its ledger row is live | Two maintainer-ordered lanes on closed issues (#4714, #4691) were flagged for TaskStop (2026-10-25). `agent-reap.sh` now skips a closed issue with a live ledger row |
@@ -5,8 +5,8 @@ maintainer does not have to. The monitor observes; it never edits code,
5
5
  never restarts anything, and never touches the session it is reading.
6
6
 
7
7
  Read first: the engineering principles (`docs/engineering-principles.md`),
8
- then `AGENTS.md` (the "Recurring defect shapes" catalog, especially shape 41:
9
- a fixed bound reached at p50 is a design defect), then
8
+ then `AGENTS.md` and the defect-shape catalog (`docs/defect-shapes.md`,
9
+ especially shape 41: a fixed bound reached at p50 is a design defect), then
10
10
  `docs/pi-lens-subagent.md` and `docs/pi-lens-investigator.md` for the
11
11
  forensics conventions this role inherits. This contract adds the standing
12
12
  readout.
@@ -34,25 +34,62 @@ memory growth:
34
34
  row in latency.log records the release and its trigger).
35
35
  - samplerDurationMs measures the sampler's own record-assembly wall time,
36
36
  excluding the surrounding turn.
37
+ - idle is false on the periodic sample. It is true on the one sample written
38
+ at a session's first turn start after its own turn end, when that gap is
39
+ longer than the TS idle-evict window (`getLspIdleEvictMs()`, 20 minutes by
40
+ default). That record also carries idleMs, the measured gap. The heap
41
+ reading is process-wide; the gap belongs to the session whose turn started.
37
42
 
38
43
  All fields are in the existing record and are O(1) reads or latest-value
39
44
  snapshots; no additional telemetry sink is created.
40
45
 
41
46
  ## Inputs
42
47
 
43
- - `~/.pi-lens/latency.log` and `~/.pi-lens/extension.log` (JSON lines; every
44
- row carries `pid` and `ts`). The session is the `pid` the brief names, or the
45
- newest pid with rows in the last hour when the brief says "live".
48
+ Read the monitored process's log directory, resolved by `getGlobalPiLensLogDir()`
49
+ in `clients/probe-home-state.ts`: a non-empty `PI_LENS_HOME` wins, otherwise
50
+ any applicable probe-home redirect, otherwise `~/.pi-lens`. Do not infer this
51
+ from the monitor's own environment. The brief names the root. When it does
52
+ not, a `PI_LENS_HOME` in the monitored pid's environment (`/proc/<pid>/environ`
53
+ on Linux, `ps eww -p <pid>` on macOS) settles it; otherwise a probe-home
54
+ redirect may have chosen the root from that process's working directory, so
55
+ ask the orchestrator for the root instead of reading `~/.pi-lens`. Pass that directory as `--root` to
56
+ `scripts/analyze-pi-lens-logs.mjs`, whose default is `~/.pi-lens`.
57
+
58
+ - `latency.log` and `extension.log` (JSON lines; every row carries `pid`
59
+ and `ts`). The session is the `pid` the brief names, or the newest pid with
60
+ rows in the last hour when the brief says "live".
61
+ - `cascade.log` (JSON lines with `ts`, `phase`, and `filePath`,
62
+ but no `pid` or `type`). Use the selected time window and `filePath` to
63
+ narrow by project. Label counts as project/time-window evidence, not
64
+ pid-attributed evidence; flag shared-project and non-path rows as
65
+ attribution-ambiguous.
46
66
  - The previous readout for the same project when one exists (an issue comment
47
67
  the brief links, or a file under the scratch directory). Every number is
48
68
  reported as a delta against it when available.
49
69
 
70
+ Read active files, retained numbered siblings (for example, `cascade.log.1`),
71
+ and date-only archives (for example, `cascade.log.2026-03-01`), plus timestamped
72
+ archives that overlap the selected window. The analyzer includes numbered and
73
+ date-only siblings by default; use `--archived` for timestamped archive names
74
+ containing `T` (for example, `cascade.2026-03-01T12-00-00Z.log`, the form session-start cleanup writes). Filter rows by
75
+ the selected window in every file. A missing active file does not make its
76
+ retained siblings empty; flag incomplete retention when the files do not cover
77
+ the requested window.
78
+
50
79
  ## The readout (fixed shape, one comment or file, never stdout to the session)
51
80
 
52
81
  1. **Session line**: pid, project root, first/last row timestamps, row count,
53
82
  pi-lens version if a session-start row carries it.
54
- 2. **Phase table**: for every `type:"phase"` value, `n | p50 | p95 | max |
55
- total_ms`, sorted by total, top 15. Durations in ms, from `durationMs`.
83
+ 2. **Phase table**: group `latency.log` rows with `type:"phase"` and
84
+ `cascade.log` rows from all selected files by `source | phase`, using the
85
+ log family as `source` across active and archived siblings. Report
86
+ `n | timed_n | p50 | p95 | max | total_ms`, sorted by total, top 15.
87
+ Count every row in `n`; compute
88
+ timing columns only from numeric `durationMs`, in ms, with `timed_n`
89
+ showing that sample count. Show `-` when no durations exist. List count-only
90
+ phases separately so the timing top 15 cannot hide `cascade_carry_rendered`;
91
+ include its `metadata.carriedRunsRendered` and `metadata.labeledAdvisories`
92
+ totals.
56
93
  3. **Bounds reached at p50** (shape 41): every phase whose p50 is within 10%
57
94
  of a declared budget or timeout in its metadata (`budgetMs`, `timeoutMs`,
58
95
  `elapsedMs` ≈ budget). Name the constant when it is known
@@ -113,7 +150,12 @@ snapshots; no additional telemetry sink is created.
113
150
  displaced is another; a subagent beside a live primary writes none)
114
151
  transitions,
115
152
  `session_end_fence_rollup` (one per primary shutdown: `sources[]` with
116
- `guarded` and `dropped`, plus totals), `lsp_created_import_scan_rollup`
153
+ `guarded` and `dropped`, plus totals), `session_handoff_turn_state` (#4751:
154
+ one per primary that takes the turn-state worklist at its turn_start;
155
+ `arm` `predecessor` (from an in-process predecessor: `from`, its files kept
156
+ as `filesKept`), `evicted` (from a predecessor past the stale bound: `from`,
157
+ its files dropped as `filesDropped`) or `empty`, and `to`),
158
+ `lsp_created_import_scan_rollup`
117
159
  (one per primary shutdown when the created-module producer ran: `calls`,
118
160
  `importers`, `targets`, `capped`, `oversized`, `totalMs`, `maxMs`). Read `read_guard_branch_retained` with
119
161
  `payloadReads`: `kept 0, dropped 0` is a missing payload when `payloadReads`
@@ -153,8 +195,22 @@ snapshots; no additional telemetry sink is created.
153
195
  - File nothing yourself unless the brief grants `gh`; then one comment on the
154
196
  issue the brief names, never a new issue: the orchestrator decides what
155
197
  becomes a lane.
156
- - A worker that finds the logs empty or the pid absent reports exactly that
157
- with the `ls -la` of the two files and stops.
198
+ - The analyzer reads discovered sources independently and does not apply a
199
+ pid-evidence stop rule. It reports per-family file and row counts
200
+ (`filesScanned`, `rowsSeen`, `parseErrors`) but cannot classify each input
201
+ as absent, empty, unreadable, or out-of-window.
202
+ Missing files and unreadable directories can yield no discovered input;
203
+ empty files and out-of-window rows contribute no rows. A discovered file
204
+ read error fails the command instead of producing an empty report. Do not
205
+ infer absent or empty inputs from zero counts alone.
206
+ - Apply the evidence policy in the monitor's own readout: if the pid is absent
207
+ from the selected latency/extension rows, report that and stop only
208
+ pid-attributed analysis. Continue the project/time-window cascade readout,
209
+ including carry counters, without claiming pid ownership. Inspect the inputs
210
+ separately and report absent, empty, unreadable, or out-of-window states as
211
+ observed, with a bounded `ls -la` inventory of the resolved active files and
212
+ retained archives. After reporting those limits, stop the whole readout only
213
+ when neither kind of evidence is available.
158
214
 
159
215
  ## Deliverable
160
216
 
@@ -0,0 +1,41 @@
1
+ # Orchestration procedure
2
+
3
+ The orchestrator-only half of `AGENTS.md` "Orchestration and delegated work":
4
+ brief authoring, review intake, the fold check, and the merge gate's CI read.
5
+ The delegation and hand-back rules a worker obeys stay in `AGENTS.md`; the
6
+ per-PR loop itself is `docs/pi-lens-merge-policy.md`.
7
+
8
+ - A brief never asks a worker to wait for an answer ("report the size first"):
9
+ a worker cannot wait for a reply. It either authorizes the conditional
10
+ branch with its bound, or tells the worker to stop and hand back there.
11
+ - A brief names every file by its repo path (`clients/lsp/index.ts`, never
12
+ `index.ts`): a bare basename resolves to another file in a read-only pass.
13
+ - After every completion, push, verdict, merge, or status request, trigger the
14
+ next named owner in the same pass, and keep the handoff (exact head, verdict,
15
+ dispositions, next owner) on the PR or the ledger.
16
+ - Review intake generalizes before it routes. For every HIGH, MEDIUM or
17
+ CRITICAL finding, name the defect shape, grep the tree for other members, and
18
+ record a verdict before the fix round dispatches: contained in this PR (with
19
+ the sweep), sibling issue filed with the member list, or none (with the
20
+ grep). The fix brief carries it as a `Shape:` line. History: `HISTORY.md`,
21
+ 2026-10-10.
22
+ - Plegma reads are token-budgeted (#417): settlements via `watch --next --mine`,
23
+ `result` only when the transcript or handoff artifact is needed.
24
+ - Every regroup, merged bug fix, second round on one shape, and incident runs
25
+ the retrospective in `docs/pi-lens-retro.md`.
26
+ - Three open issues on one mechanism, in any seam groups, open a consolidation
27
+ audit across every consumer of that mechanism before the next one is filed
28
+ (history: `HISTORY.md`, 2026-10-16).
29
+ - Run the **fold check** as soon as a lane's mechanism is known, which is when
30
+ the brief is written: read every open issue against that mechanism and decide
31
+ each candidate as folded into this PR (one `Closes #…` per folded issue) or
32
+ not folded, with the reason (two hazards in one review, a maintainer decision,
33
+ a blocked dependency, a different seam). The brief carries the candidate list
34
+ and its decisions, and the PR body records them under `## Fold check`.
35
+ Planning precedes filing: a new issue is the answer for p2+ work no lane can
36
+ carry, never for a p3 the lane could fold (history: `HISTORY.md`, 2026-10-20).
37
+ - The per-PR loop (review, verify, auto-merge on green), round routing, the
38
+ merge gate and the Common mistakes table live in `docs/pi-lens-merge-policy.md`.
39
+ - Read CI with `node scripts/ci-verdict.mjs <pr|sha>` (exact head, all pages).
40
+ Never merge on absent, stale, or advisory-only checks.
41
+
@@ -0,0 +1,20 @@
1
+ <important if="building, packaging, or releasing">
2
+
3
+ ## Build, packaging, and release
4
+
5
+ `main` and `pi.extensions` point to `dist/index.js`; `dist/` is generated and
6
+ not committed. `prepare` builds it for git and package installs. `build:dist`
7
+ bundles pure-JS dependencies while keeping host-provided and lazy native
8
+ packages external. Package-root resource resolution is depth-robust; pi
9
+ resolves `pi.skills` entries relative to the package root, so manifests use
10
+ `"./skills"` and never an escaping path.
11
+
12
+ Runtime imports must be production dependencies. The pi SDK is an optional
13
+ peer/dev dependency and must be imported type-only. Lockfiles use the pinned
14
+ npm version. Release notes use one `.changelog/<slug>.md` fragment per PR
15
+ (`audience: user` or `internal`; the release body lists only `user`); never
16
+ edit `CHANGELOG.md` for ordinary PR notes.
17
+ New user-facing fragments begin with a bold lead of at most 100 characters
18
+ (issue references are excluded from the count); internal fragments are exempt.
19
+
20
+ </important>
@@ -8,7 +8,8 @@ output of this role. Source of truth for every rule here is this file and
8
8
 
9
9
  Read first: the engineering principles (`docs/engineering-principles.md`),
10
10
  then `AGENTS.md` ("Recurring defect shapes", "Orchestration and delegated
11
- work", "Test requirements"), then `docs/pi-lens-subagent.md` when delegated,
11
+ work", "Test requirements"), the shape entries it indexes
12
+ (`docs/defect-shapes.md`), then `docs/pi-lens-subagent.md` when delegated,
12
13
  then this contract and `docs/pi-lens-merge-policy.md` ("Common mistakes"),
13
14
  which is where mistake rows land.
14
15
 
@@ -25,8 +26,8 @@ which is where mistake rows land.
25
26
  ## Inputs (primary sources, never memory)
26
27
 
27
28
  The lane ledger, the session transcripts, PR bodies and review verdicts, CI
28
- job logs on the exact head, `~/.pi-lens/latency.log` when runtime behaviour
29
- is involved. Every finding cites the source it came from.
29
+ job logs on the exact head, `latency.log` under the resolved log root (`docs/pi-lens-monitor.md`
30
+ "Inputs") when runtime behaviour is involved. Every finding cites the source it came from.
30
31
 
31
32
  ## Procedure
32
33
 
@@ -61,7 +62,7 @@ is involved. Every finding cites the source it came from.
61
62
  exactly as a regression test would; a check without a red is a proposal and
62
63
  is filed as an issue naming the incident as its recurrence, not merged.
63
64
  4. **Judgement candidates become one line in the right place.** A defect shape
64
- goes into the `AGENTS.md` catalog as a lean screen, and its issues, PRs and
65
+ goes into the catalog (`docs/defect-shapes.md`) as a lean screen, and its issues, PRs and
65
66
  examples go to `HISTORY.md`, under a heading that names the shape, such as
66
67
  `## 2026-10-14 - title (shape N)`: a lean entry cites no issue, and
67
68
  `tests/config/shape-history-governance.test.ts` finds the record by that