pi-lens 4.4.6 → 4.4.8

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 (174) hide show
  1. package/CHANGELOG.md +232 -0
  2. package/README.md +17 -3
  3. package/config/markdownlint/run-no-fix.mjs +36 -0
  4. package/dist/{chunk-ZQ6NZZTB.js → chunk-2453RRJ2.js} +44 -6
  5. package/dist/{chunk-GZE7WOI4.js → chunk-2BKUFQKR.js} +696 -330
  6. package/dist/chunk-2TS4GLOJ.js +31 -0
  7. package/dist/{chunk-2DMLM3ZO.js → chunk-2ZE3AUJQ.js} +12 -14
  8. package/dist/{chunk-OJLTLYHB.js → chunk-35WKJWO5.js} +51 -33
  9. package/dist/chunk-3JAHQBSY.js +27 -0
  10. package/dist/{chunk-PO45POGF.js → chunk-3O5EII3W.js} +2 -2
  11. package/dist/chunk-447YZL4S.js +25 -0
  12. package/dist/{chunk-TIYGSODX.js → chunk-4B2YFN4U.js} +28 -22
  13. package/dist/{chunk-OSTKYB55.js → chunk-4BKU7PV3.js} +1 -1
  14. package/dist/{chunk-XQCSWV2G.js → chunk-4LL2VRNY.js} +27 -28
  15. package/dist/{chunk-MA77RSFN.js → chunk-4NBWFYWW.js} +9 -9
  16. package/dist/{chunk-75SY4F24.js → chunk-4QG55RRC.js} +12 -12
  17. package/dist/{chunk-K2YGBXOA.js → chunk-4W52ZKZX.js} +2 -2
  18. package/dist/{chunk-Z2XAOKHK.js → chunk-565VRUP4.js} +2 -2
  19. package/dist/{chunk-CFRQMBGP.js → chunk-57X2CDRX.js} +23 -23
  20. package/dist/{chunk-XAIT2YGS.js → chunk-5F3XF3SX.js} +7 -15
  21. package/dist/{chunk-UHGF5UT5.js → chunk-5RNB4HVK.js} +1 -1
  22. package/dist/{chunk-Q4EMRFNA.js → chunk-5T5A6YAJ.js} +35 -34
  23. package/dist/{chunk-W5LGKNET.js → chunk-6FIRFP6A.js} +12 -12
  24. package/dist/{chunk-KLQVC3XC.js → chunk-6GMGEKQN.js} +36 -9
  25. package/dist/{chunk-UN4TEBWN.js → chunk-6LJOJ6EO.js} +20 -15
  26. package/dist/{chunk-HK6JVFZC.js → chunk-6YUNI7B5.js} +3 -3
  27. package/dist/{chunk-PKES3ISE.js → chunk-7ANZ7XDD.js} +2 -2
  28. package/dist/{chunk-VQH24FIP.js → chunk-7CGIDRIK.js} +16 -15
  29. package/dist/{chunk-SCIUNBPF.js → chunk-7MAD5ZAY.js} +16 -17
  30. package/dist/{chunk-OOU2WZZE.js → chunk-7TNILKGY.js} +1 -1
  31. package/dist/{chunk-LEJOJDXL.js → chunk-A5GRLYPZ.js} +9 -9
  32. package/dist/{chunk-AE37FEGH.js → chunk-AGGUWKRK.js} +1 -1
  33. package/dist/{chunk-BWYQUPOS.js → chunk-BBET6HD6.js} +1 -1
  34. package/dist/{chunk-GAACZY6R.js → chunk-BHWW6FAX.js} +14 -13
  35. package/dist/{chunk-A3YNG5KP.js → chunk-BOPDQ7AZ.js} +23 -21
  36. package/dist/{chunk-MKVZQUEG.js → chunk-BQG2QFVO.js} +215 -134
  37. package/dist/{chunk-EVDGNG4F.js → chunk-BUZIQDFS.js} +3 -3
  38. package/dist/{chunk-2PHMIAKO.js → chunk-CM73PPGD.js} +4 -4
  39. package/dist/{chunk-63RIVFQI.js → chunk-CUDD35TW.js} +10 -9
  40. package/dist/{chunk-BM5GS6ZH.js → chunk-CZL44WFN.js} +2 -2
  41. package/dist/{chunk-QGSTQH4D.js → chunk-DIWK3LBC.js} +12 -15
  42. package/dist/{chunk-JL6CXUMW.js → chunk-DYRZGUMA.js} +2 -2
  43. package/dist/{chunk-NDMCVUYK.js → chunk-FHEV6T4L.js} +22 -18
  44. package/dist/{chunk-4PCQCU47.js → chunk-FRLAUP2B.js} +4 -4
  45. package/dist/{chunk-RZOXUSPC.js → chunk-G5GV2Q7K.js} +2 -2
  46. package/dist/{chunk-2RLWJO5K.js → chunk-G6JKM4O7.js} +7 -7
  47. package/dist/chunk-GGYOZWHW.js +27 -0
  48. package/dist/{chunk-DC4CFXM5.js → chunk-GIRBSBGL.js} +6 -5
  49. package/dist/{chunk-PQJFG24Z.js → chunk-GMROJJRN.js} +1292 -946
  50. package/dist/{chunk-ZUUI3ZSA.js → chunk-HHR7WGCI.js} +3 -3
  51. package/dist/{chunk-TIQJPRDD.js → chunk-HKIL6DCL.js} +3 -2
  52. package/dist/{chunk-VPBIMOAQ.js → chunk-HUAM7QG3.js} +15 -13
  53. package/dist/{chunk-ZYNI26MI.js → chunk-HXFUTMX2.js} +2 -2
  54. package/dist/{chunk-W5R5SABV.js → chunk-I22THIHI.js} +12 -12
  55. package/dist/chunk-IE5D3RA5.js +58 -0
  56. package/dist/{chunk-MT6BVNFW.js → chunk-IYVYZQRL.js} +10 -16
  57. package/dist/{chunk-ARD426WI.js → chunk-JBP7KESM.js} +1 -1
  58. package/dist/{chunk-MN7MHUXQ.js → chunk-JE6HKLC7.js} +2 -2
  59. package/dist/{chunk-3MYEA7QD.js → chunk-JPRDTY5S.js} +85 -3
  60. package/dist/{chunk-CJYKEW2L.js → chunk-JYLOYTZD.js} +17 -1
  61. package/dist/{chunk-5APMQ2IJ.js → chunk-JZRP4DGP.js} +2 -2
  62. package/dist/{chunk-AMXIUN2R.js → chunk-KZ4ALBCH.js} +2 -2
  63. package/dist/{chunk-W2V54OCL.js → chunk-L3CLUGDY.js} +3 -3
  64. package/dist/{chunk-DMSLNKF7.js → chunk-L4NEVZ4T.js} +28 -27
  65. package/dist/chunk-LPYTPNOJ.js +22 -0
  66. package/dist/{chunk-BI5LAQ3Y.js → chunk-LSFXZLPW.js} +2071 -1725
  67. package/dist/{chunk-2DDDCJDL.js → chunk-MC6VB2E5.js} +4 -4
  68. package/dist/{chunk-U2SDMG7C.js → chunk-NM2NWH55.js} +5 -5
  69. package/dist/{chunk-Q4FCYCRE.js → chunk-NSPVR3FN.js} +19 -18
  70. package/dist/{chunk-VG5JS5SW.js → chunk-O2ARHQKF.js} +2 -2
  71. package/dist/{chunk-KSR7RGQY.js → chunk-O4N5BQ3T.js} +10 -10
  72. package/dist/{chunk-5ZR3APIM.js → chunk-OC7VWJBZ.js} +39 -40
  73. package/dist/chunk-OFNMHPBT.js +89 -0
  74. package/dist/{chunk-YSBHPOY6.js → chunk-OWTG6UMO.js} +21 -21
  75. package/dist/{chunk-7RQXA5GG.js → chunk-OY7WZI7Q.js} +13 -12
  76. package/dist/{chunk-5CV5ITZF.js → chunk-OZWXLJMX.js} +2 -2
  77. package/dist/{chunk-F6X3YJWD.js → chunk-PIQQM32Y.js} +2 -2
  78. package/dist/chunk-PKLB2XJL.js +8 -0
  79. package/dist/{chunk-DQXSPYRI.js → chunk-PKSUMEPT.js} +17 -4
  80. package/dist/{chunk-YISME6ON.js → chunk-PPKECBPP.js} +1 -1
  81. package/dist/{chunk-4AVZ3TG7.js → chunk-R2QQC33W.js} +14 -14
  82. package/dist/{chunk-GMTFDAOK.js → chunk-R4QWJQ2H.js} +11 -11
  83. package/dist/{chunk-V63BC55Q.js → chunk-RGGH6M34.js} +1 -1
  84. package/dist/{chunk-SJJYRZB4.js → chunk-RZG472YW.js} +116 -26
  85. package/dist/{chunk-NIU2IPC5.js → chunk-SDFKOLSF.js} +6 -6
  86. package/dist/{chunk-H7HTEQUZ.js → chunk-SFLHSL5R.js} +9 -9
  87. package/dist/{chunk-FA5LDARD.js → chunk-SP4TFY5F.js} +14 -13
  88. package/dist/{chunk-J6JP25XU.js → chunk-SQC7K3SP.js} +4 -3
  89. package/dist/{chunk-T7FTXGS3.js → chunk-T2S3FNNJ.js} +44 -42
  90. package/dist/{chunk-S67UJDGQ.js → chunk-TV6RXRYH.js} +10 -10
  91. package/dist/{chunk-GNSIWBAT.js → chunk-U3AS2FR6.js} +3 -3
  92. package/dist/{chunk-WIZWZR4C.js → chunk-UHHLR2VY.js} +43 -41
  93. package/dist/chunk-UYXV5NIS.js +20 -0
  94. package/dist/{chunk-VSFLRN5Y.js → chunk-VLQ7UKZH.js} +1 -1
  95. package/dist/{chunk-FFL3A2VP.js → chunk-VN3L2JWZ.js} +46 -72
  96. package/dist/{chunk-Z7IGUAXL.js → chunk-VOP4PJKA.js} +12 -8
  97. package/dist/{chunk-F5Z6URKM.js → chunk-VOXTCULR.js} +2 -2
  98. package/dist/{chunk-NNKXDXXS.js → chunk-VPLBLWFO.js} +14 -8
  99. package/dist/chunk-W3BGKBBK.js +27 -0
  100. package/dist/{chunk-ZKXQKGWZ.js → chunk-WC6WRNQT.js} +4 -3
  101. package/dist/{chunk-Q3UZHW6N.js → chunk-WMDUT4KH.js} +1150 -1138
  102. package/dist/{chunk-KXF5R4UN.js → chunk-WQV6BI4Q.js} +1 -1
  103. package/dist/chunk-WXUDRAG6.js +24 -0
  104. package/dist/{chunk-OLAWH5UQ.js → chunk-X35S7HSB.js} +29 -10
  105. package/dist/{chunk-YBSONGSZ.js → chunk-X66YJ2SS.js} +40 -34
  106. package/dist/{chunk-U6OC3QEM.js → chunk-XOMGO63G.js} +22 -21
  107. package/dist/{chunk-WQOIR3QY.js → chunk-XWIME22V.js} +13 -13
  108. package/dist/{chunk-3WEPUD2V.js → chunk-XYLC35E4.js} +202 -103
  109. package/dist/{chunk-UCGQT677.js → chunk-YHGYAEFH.js} +18 -18
  110. package/dist/{chunk-V3APN3DY.js → chunk-ZFORSIED.js} +13 -13
  111. package/dist/{chunk-BHUWL2Y3.js → chunk-ZKLTNLAW.js} +64 -73
  112. package/dist/chunk-ZONZ6YY3.js +74 -0
  113. package/dist/chunk-ZSM35JF4.js +30 -0
  114. package/dist/{chunk-PPIBVH4R.js → chunk-ZZDIOAAJ.js} +15 -6
  115. package/dist/index.js +8817 -6239
  116. package/dist/mcp/analyze-cli.js +10 -10
  117. package/dist/mcp/cli.js +44 -42
  118. package/dist/mcp/server.js +2236 -861
  119. package/dist/mcp/worker.js +62 -61
  120. package/dist/probes/installer.js +20 -19
  121. package/docs/adr/0003-git-guard-latch-writer.md +11 -6
  122. package/docs/agent-tools.md +29 -11
  123. package/docs/alignment-families.md +29 -0
  124. package/docs/ast-grep_rules_catalog.md +6 -4
  125. package/docs/ci-bot-pr-checks.md +126 -0
  126. package/docs/configuration.md +99 -3
  127. package/docs/defect-shapes.md +68 -11
  128. package/docs/dependencies.md +1 -0
  129. package/docs/engineering-principles.md +27 -2
  130. package/docs/environment-variables.md +14 -0
  131. package/docs/features.md +13 -3
  132. package/docs/globalconfig.md +12 -1
  133. package/docs/invariants/git-guard-host.md +38 -0
  134. package/docs/invariants/language-config.md +15 -4
  135. package/docs/invariants/lsp-trust-exec.md +22 -2
  136. package/docs/invariants/paths-os.md +4 -2
  137. package/docs/invariants/session-telemetry.md +42 -2
  138. package/docs/lsp-capability-matrix.md +208 -84
  139. package/docs/lsp-idle-eviction.md +3 -5
  140. package/docs/merge-queue-rollout.md +1 -1
  141. package/docs/pi-lens-fixer.md +31 -17
  142. package/docs/pi-lens-merge-policy.md +27 -15
  143. package/docs/pi-lens-monitor.md +9 -0
  144. package/docs/pi-lens-orchestration.md +4 -1
  145. package/docs/pi-lens-reviewer.md +5 -5
  146. package/docs/pi-lens-subagent.md +13 -7
  147. package/docs/public-api-stability.md +18 -2
  148. package/docs/schema/pi-lens-config-v1.json +33 -0
  149. package/docs/servercapabilities.md +1 -1
  150. package/docs/settings.md +15 -6
  151. package/docs/usage.md +5 -0
  152. package/docs/word-index.md +17 -5
  153. package/package.json +5 -3
  154. package/rules/ast-grep-rules/rule-tests/no-accumulating-spread-js-test.yml +37 -0
  155. package/rules/ast-grep-rules/rule-tests/ts-redundant-filter-map-test.yml +12 -1
  156. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-js-test.yml +12 -0
  157. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-test.yml +25 -0
  158. package/rules/ast-grep-rules/rules/no-accumulating-spread-js.yml +49 -1
  159. package/rules/ast-grep-rules/rules/ts-redundant-filter-map.yml +9 -1
  160. package/rules/ast-grep-rules/rules-disabled/filter-then-map-js.yml +17 -0
  161. package/rules/ast-grep-rules/rules-disabled/filter-then-map.yml +36 -0
  162. package/rules/ast-grep-rules/self-scan-baseline.json +1 -1
  163. package/dist/chunk-2F47TQOA.js +0 -73
  164. package/dist/chunk-2X4VLOCC.js +0 -55
  165. package/dist/chunk-4WX4CTUE.js +0 -57
  166. package/dist/chunk-FJIVKLPH.js +0 -31
  167. package/dist/chunk-G2B7F6ZU.js +0 -88
  168. package/dist/chunk-GTAI2J6U.js +0 -27
  169. package/dist/chunk-IPDG45G5.js +0 -26
  170. package/dist/chunk-P4QNXS6I.js +0 -27
  171. package/dist/chunk-Q6D6VMI4.js +0 -22
  172. package/dist/chunk-SXGD4ANG.js +0 -25
  173. package/dist/chunk-XCUHKYCQ.js +0 -23
  174. package/dist/chunk-YRD4ISED.js +0 -30
@@ -179,9 +179,12 @@ file-scoped worklist and receives no project-wide scanner output.
179
179
  decides only delivery, and a run with no verdict (failed, unanswered, in
180
180
  flight) observes nothing, so neither retires a recorded blocker. A skip
181
181
  has a verdict only with a stated not-applicable reason
182
- (`RUNNER_SKIP_REASONS`). A recorded blocker is still observed only at its
183
- own line, aligned to the current bytes: another occurrence of the same
184
- rule is not it. A fallback for missing evidence narrows what retires:
182
+ (`RUNNER_SKIP_REASONS`). `not-enabled` (an opt-in runner left off, #5042)
183
+ is the one stated reason that stays a no-verdict: admitting it would retire
184
+ recorded helm-render blockers and stop their owed ranges. A recorded blocker
185
+ is still observed only at its own line, aligned to the current bytes:
186
+ another occurrence of the same rule is not it. A fallback for missing
187
+ evidence narrows what retires:
185
188
  with no alignment, its identity anywhere keeps it. It stays a per-write
186
189
  hold and never widens what counts as the same finding: the match still
187
190
  needs the entry's own line text, and owed lines are matched by content,
@@ -195,6 +198,18 @@ file-scoped worklist and receives no project-wide scanner output.
195
198
  kept entry with no place in a write's bytes is recorded as such
196
199
  (`positionStale`), never inferred later from one line's hash, and a line
197
200
  with no word character owes nothing by its text.
201
+ A non-authoritative answer never stands in for a primary that never
202
+ answered: a `fallbackFor` alternate (python-jedi beside a pyright that was
203
+ trust-refused, failed to start, sat in a breaker cool-down or was not
204
+ installed) is not its owner, so the file reads unavailable with the owner
205
+ named, never "confirmed clean" (#5014). The rule admits the known-good
206
+ forms (a non-alternate primary acquired, an alternate standing in for an
207
+ owner the operator disabled, an alternate whose owner resolved no root) in
208
+ `unansweredPrimaries` (`clients/lsp/index.ts`); every other cause, listed or
209
+ not, lands unconfirmed. Screen: can a file read clean when its primary
210
+ never answered? Population enforcer:
211
+ `tests/clients/lsp/unanswered-primaries-fallback-5014.test.ts` (every
212
+ registered `fallbackFor` alternate).
198
213
  Enforced by `tests/clients/dispatch/runners/run-outcome-ratchet.test.ts`,
199
214
  `tests/clients/dispatch/runners/parsed-nothing-sweep.test.ts` and
200
215
  `tests/clients/delivery-surface-ratchet.test.ts` (partial: no detector
@@ -605,11 +620,13 @@ file-scoped worklist and receives no project-wide scanner output.
605
620
  the lane's timeout scale and is refused; a same-named local constant is
606
621
  admitted and an import alias of the shared one is refused (no live member
607
622
  either way). Screen: does this case call a walker or read a binding one
608
- produced, and is its third argument one of those two forms? Census: 151 in
609
- `tests/config`, all budgeted; 79 outside it still keep the default (a probe,
610
- not a command). Enforcer: `tests/config/tree-census-timeout.test.ts` (it
611
- derives the declaration callee from the file's vitest imports, resolves
612
- walker aliases, and counts a test-shaped call it cannot trace as a census).
623
+ produced, and is its third argument one of those two forms? Census: 244
624
+ under `tests/` (154 in `tests/config`, all budgeted; 90 outside it, of which
625
+ 87 are refused and admitted by name in
626
+ `tests/config/tree-census-timeout.baseline.json`, and 3 budgeted). Enforcer:
627
+ `tests/config/tree-census-timeout.test.ts` (it derives the declaration
628
+ callee from the file's vitest imports, resolves walker aliases, and counts a
629
+ test-shaped call it cannot trace as a census).
613
630
  It does not read a walker reached through a helper in another module, a
614
631
  variable-bound arrow-function walker, a local spawn wrapper, or a walk named
615
632
  only by an enclosing `describe.each` or loop; `Unit tests Windows` is the
@@ -622,8 +639,15 @@ file-scoped worklist and receives no project-wide scanner output.
622
639
  (`tests/clients/interleaving-kit.ts`), which reads a real-clock deadline
623
640
  scaled by `PI_LENS_TEST_TIMEOUT_SCALE`, and give the test a timeout above
624
641
  that deadline. Screen: does the wait end on the event it waits for or on a
625
- real-clock deadline, never on a count? Enforcer: none yet; the detector is
626
- tracked in #4865. Instances and dates: `HISTORY.md`.
642
+ real-clock deadline, never on a count? Enforcer: the governance ast-grep
643
+ rules `turn-count-wait` and `turn-count-wait-test-hook`
644
+ (`scripts/governance-rules/`, run by `npm run astgrep:self-scan`), with a
645
+ reasoned baseline. It does not see a count loop with no exit besides the
646
+ count (a pure `for (N) await yield` flush), a wait spelled as recursion, a
647
+ count written as iteration over a generated range
648
+ (`for (const _ of Array.from({ length: N }))`), or a loop that compares a
649
+ clock value for some other purpose.
650
+ Instances and dates: `HISTORY.md`.
627
651
 
628
652
  </important>
629
653
 
@@ -707,7 +731,40 @@ file-scoped worklist and receives no project-wide scanner output.
707
731
  session's value for the whole process answers for whichever session wrote
708
732
  last, so a second live session overwrites what another one read. Key the
709
733
  state by session identity, or decide from live membership. Instances:
710
- #4554 (fixed by #4563, still open) and #4564. No guard yet: not scanned.
734
+ #4554 (fixed by #4563, still open) and #4564. Screen: whose data is the
735
+ store, not what its key is? Seam: a session's state lives on a scope cell
736
+ (`scopeCell`, `clients/session-scope.ts`, #3609); a caller that holds only
737
+ a session id reaches the cell through `sessionCell`, which names live
738
+ scopes only. Enforcer: the `ownerKey` column of
739
+ `tests/support/session-state-registry.ts`, audited by
740
+ `tests/clients/session-state-conformance.test.ts` ("owner key (#4965)"):
741
+ every entry names `session`, `repository`, `project` or `process-wide:
742
+ <reason>`, and a `session` owner states `sessionSeamException`, why a scope
743
+ cell cannot hold it yet. A moved store has no process container and no
744
+ entry; `scanScopeCellKeys` pins every cell by file and key
745
+ (`SESSION_CELL_KEYS`). The same `auditOwnerKeys` reads all three lists:
746
+ `SESSION_STATE_REGISTRY`, the file-level `EXEMPT_SESSION_STATE_FILES` rows
747
+ and the declared `SESSION_STORE_REGISTRY` rows (#5027); a file with several
748
+ owners states the narrowest. The scan behind them
749
+ (`scanSessionStateCandidates`) flags a file for a module-level container
750
+ with or without a reset, except one admitted constant: an UPPER_SNAKE
751
+ built-in `Map`/`Set`/`WeakMap`/`WeakSet` declared `const` whose every use
752
+ in `clients/`, `tools/`, `mcp/` and `index.ts` is a read; and for a class
753
+ field or `this.x` assignment bound to `new <container or clients/ class>`
754
+ or `[]`, or a depth-1 `key: new <container>` member of a module-level
755
+ object literal (`globalState = { reads: new Map() }`). An admitted
756
+ constant removes the symbol, not the file: a file that also exports a
757
+ reset stays a candidate with a 0 pin. One symbol-count pin counts the
758
+ containers, fields and members. Partial: it walks `clients/`;
759
+ `tools/` holds no candidate today, `index.ts` is censused by
760
+ `tests/config/session-scope-sweep.test.ts` (#3611), and `mcp/server.ts`
761
+ (`lspReadyCwds`) is outside the scan root. A field built by a factory call,
762
+ through another binding or an aliased constructor is not read, and an
763
+ admitted constant's `forEach` callback or stored value can be mutated
764
+ unseen (`SWEEP_HEURISTIC_LIMITS`; live population 0), and the owner value
765
+ itself is a judgment the audit only forces to be stated.
766
+
767
+ 87. **Factory-time read of a host value set later:** pi applies an extension flag's command-line value after every factory has run, so a flag read while the factory runs answers the registered default. Screen: does any flag read run while the factory runs, and does the host test apply the value after the factory, as pi does? Read it in a handler, a command or a tool, or once in `session_start`. Enforcer: `tests/config/factory-flag-read-sweep.test.ts` (partial: a reader handed to a callee that invokes it synchronously is not seen). Instances and dates: `HISTORY.md`.
711
768
 
712
769
  **Expired successor hand-off:** an expired successor marker may authorize
713
770
  its named interrupted successor only for the fixed retention window in
@@ -50,6 +50,7 @@ Auto-install behavior depends on gate type:
50
50
  | `gitleaks` | Committed-secret session scan | Auto-install | Opt-in (config / hook / dep) |
51
51
  | `govulncheck` | Go reachable-CVE session scan | `go install` | Auto (`go.mod` present) |
52
52
  | `trivy` | Dependency-CVE session scan | Auto-install | Explicit opt-in (`trivy.enabled`) |
53
+ | `fallow-lsp` | JS/TS unused-code, duplication and cycle advisories | Auto-install | Explicit opt-in (`fallow.enabled`, pinned GitHub release) |
53
54
  | `psscriptanalyzer` | PowerShell linting | Manual | — |
54
55
 
55
56
  Lean LSP is launched as `lake serve` from the detected Lake project root, so elan selects the toolchain from that project's `lean-toolchain` file and Lake supplies its project environment. pi-lens does not install or manage Lean/elan; install Lean and Lake separately and ensure `lake` is on `PATH`.
@@ -72,8 +72,10 @@ verdict (a trust check, a lint, a census, a body check), it admits a short list
72
72
  of known-good forms and refuses everything else. It never enumerates known-bad
73
73
  spellings. Each review of an enumerated gate finds the next spelling it missed;
74
74
  one gate took sixteen rounds that way. Once a second round finds a new
75
- spelling, stop patching and redesign. Screen: can an input nobody planned for
76
- pass the gate?
75
+ spelling, stop patching and redesign. A value the gate cannot resolve to a
76
+ known-good literal (computed, concatenated, aliased, templated, reached through
77
+ an indirection) is unrecognized: it counts as a hit, never a pass. Screen: can
78
+ an input nobody planned for pass the gate?
77
79
 
78
80
  **Blast radius as a call-tree diff.** For any change to a shared seam, list the
79
81
  changed symbol, its callers above, its callees below, with plus and minus on the
@@ -115,6 +117,13 @@ it, and paste the red. A checked box with no transcript is treated as false. A
115
117
  mutation that fails to compile proves nothing about the test; redo it as a
116
118
  compile-valid change. A guard that cannot be made to red does not need to exist.
117
119
 
120
+ **A precision figure names its judgement and an outside sample.** A claim that
121
+ a rule, check or heuristic is N% precise states what counts as a true positive,
122
+ and someone other than its author judges a random sample. "The pattern matched"
123
+ is not "the finding is worth acting on": one rule reported 611 of 611 hits real
124
+ on a type check, and an independent sample of 58 found none worth the rewrite.
125
+ Below the stated bar, the rule ships disabled with the count recorded.
126
+
118
127
  **Tautological tests are harmful.** A test observes behaviour through the real
119
128
  seam and asserts an independent effect. It never restates the implementation,
120
129
  never asserts a value its own setup supplied, and never swaps a real in-process
@@ -138,6 +147,13 @@ thing is required, a registry entry, a baseline row and lane membership. A
138
147
  mocked seam is not a real spawn and gets an exemption with its reason, never an
139
148
  admission.
140
149
 
150
+ **A gate judges the actor's delta, not inherited state.** A check run on an
151
+ artifact someone edits (a tracker body, a shared file, a long-lived record)
152
+ judges only what that edit adds or changes. Inherited violations belong in a
153
+ baseline that shrinks on purpose. Refusing an honest edit for debt it did not
154
+ create blocks the work or invites routing around the gate. If the gate cannot
155
+ compute the delta, it checks the whole artifact, failing closed.
156
+
141
157
  **A new ratchet sweeps the open changes before it lands.** A governance test
142
158
  that rejects a new pattern fails every open change that already adds one, and
143
159
  none of them conflict textually, so nothing warns. Before merging a ratchet,
@@ -219,6 +235,15 @@ cleanup, triage and status upkeep. The script surfaces unfinished work and
219
235
  never hides it: stalled work is restarted, not unassigned, archived or deleted.
220
236
  Screen: is this the second time this step was done by hand?
221
237
 
238
+ **Process carries the net-count rule too.** A new guard, hook, script, lint
239
+ rule, ratchet or scheduled routine retires one of the same kind in the same
240
+ change, or it cites fire data showing what the existing ones miss. Each rule
241
+ must also earn its keep: count how often it fired, and what each fire led to
242
+ (a real fix, a wording edit, or a route-around). One that never fired in its
243
+ window and names no recurrence is demoted or deleted. Process cost is paid on
244
+ every change, while the bug a rule prevents may never arrive. Screen: what
245
+ does this rule retire, and when did the last one like it fire?
246
+
222
247
  ## 4. Honesty and records
223
248
 
224
249
  **Closes versus refs follows delivery, not optimism.** Close only when every
@@ -208,6 +208,20 @@ Unset or `0` preserves the prior local-LSP behavior exactly. Any transport,
208
208
  schema, freshness, deadline, or incumbent-liveness failure permanently falls
209
209
  back to a local LSP fleet for that session.
210
210
 
211
+ ## Variables pi-lens sets for its child processes
212
+
213
+ ### `GIT_OPTIONAL_LOCKS`
214
+
215
+ pi-lens starts the child processes it runs through its spawn seam (its
216
+ background `git status` reads included) with `GIT_OPTIONAL_LOCKS=0`, so a read
217
+ does not refresh the index and cannot leave `.git/index.lock` behind after a
218
+ timeout or a host exit. The value you export in your shell does not change this
219
+ for those children, and your own git commands are unaffected. A caller that
220
+ passes its own environment to a child keeps its value. Language servers are
221
+ launched separately and inherit your environment unchanged. On a checkout whose
222
+ index is stat-dirty, each status read re-hashes the dirty files until one of
223
+ your own git commands refreshes the index.
224
+
211
225
  ## Language-specific
212
226
 
213
227
  ### Ambient Python environments (`VIRTUAL_ENV`, `CONDA_PREFIX`, `UV_PROJECT_ENVIRONMENT`)
package/docs/features.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ### LSP Support
4
4
 
5
- pi-lens includes **49 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server with a managed installer is not installed, pi-lens offers an interactive install prompt; toolchain-bundled servers, such as Lean's `lake`, are PATH-only, and pi-lens never installs or manages them.
5
+ pi-lens includes **50 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — and one opt-in, JS/TS-only auxiliary, fallow, off unless `fallow.enabled` is set; see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server with a managed installer is not installed, pi-lens offers an interactive install prompt; toolchain-bundled servers, such as Lean's `lake`, are PATH-only, and pi-lens never installs or manages them.
6
6
 
7
7
  **LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
8
8
 
@@ -22,6 +22,16 @@ pi-lens includes **49 language server definitions** (including four cross-cuttin
22
22
  LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Lean, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Shuck (zsh-aware shell language server), Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
23
23
 
24
24
 
25
+ ### TypeScript and JavaScript server
26
+
27
+ pi-lens picks the launch for JS/TS files in this order. The first two steps use only the project's own `node_modules`:
28
+
29
+ 1. **Effect language service** — when the nearest `node_modules/typescript` is version 7 or newer and the same `node_modules` holds `@effect/tsgo`, pi-lens runs the project's `effect-tsgo tsc --lsp --stdio`. Installing the package is the opt-in; there is no pi-lens setting. A malformed `@effect/tsgo` (no readable version, no `bin`) or a failure to start the process falls back to the next step; a server that starts and then fails to initialize does not fall back, and pi-lens never installs `@effect/tsgo`.
30
+ 2. **Native TypeScript 7** — the project's `node_modules/.bin/tsc --lsp --stdio`.
31
+ 3. **Classic** — `typescript-language-server` with a `tsserver.js`, when the nearest TypeScript is version 6 or older or no step above applies. This step can also use a server and TypeScript found on `PATH` or installed by pi-lens.
32
+
33
+ The nearest installed `typescript` decides: an ancestor's TypeScript 7 never replaces a nearer, older or malformed install. The project's own compiler and launcher run only when pi has marked the project trusted (see [Configuring pi-lens](configuration.md)); otherwise the launch falls through to the next step.
34
+
25
35
  ### Python: interpreter and syntax level
26
36
 
27
37
  Python carries two separate declarations, and pi-lens reads both from the project rather than from whichever interpreter happens to run a checker.
@@ -154,7 +164,7 @@ instead of a flat blob of source. See
154
164
  [`module-report-read-symbol.md`](module-report-read-symbol.md)
155
165
  for the full design and token-efficiency numbers.
156
166
 
157
- **`module_report(filePath, maxRefsPerSymbol?, focus?, view?, blastRadius?, blastRadiusDepth?)`** —
167
+ **`module_report(path, maxRefsPerSymbol?, focus?, view?, blastRadius?, blastRadiusDepth?)`** —
158
168
  returns a structured outline: every symbol's name/kind/startLine/endLine/signature
159
169
  (plus a first-line `doc` summary when a doc comment is attached — #512),
160
170
  exported vs internal split (with class/interface members nested under their
@@ -174,7 +184,7 @@ instead of JSON — same data, opt-in. Tree-sitter extract + cached review-graph
174
184
  lookup; never builds the graph, never calls LSP on this path.
175
185
  `semantic.source` reports what backed the data (`review-graph` | `none`).
176
186
 
177
- **`read_symbol(filePath, symbol)`** — returns the verbatim body of one
187
+ **`read_symbol(path, symbol)`** — returns the verbatim body of one
178
188
  named symbol plus a one-line header (`<kind> <name> <basename>:<startLine>-<endLine>`).
179
189
  Records the read against the read-guard so a follow-up edit anywhere in
180
190
  that symbol's range passes the read-before-edit check (an outline from
@@ -18,6 +18,10 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
18
18
  | `--no-tests` | `tests.enabled` | `true` |
19
19
  | `--no-delta` | `delta.enabled` | `true` |
20
20
  | `--no-opengrep` | `opengrep.enabled` | `true` |
21
+ | `--no-ast-grep` | `astGrep.enabled` | `true` |
22
+ | `--no-zizmor` | `zizmor.enabled` | `true` |
23
+ | `--no-typos` | `typos.enabled` | `true` |
24
+ | `--lens-spotbugs` | `spotbugs.enabled` | `false` |
21
25
  | `--no-read-guard` | `readGuard.enabled` | `true` |
22
26
  | `--no-autoformat` | `format.enabled` | `true` |
23
27
  | `--no-autofix` | `autofix.enabled` | `true` |
@@ -37,6 +41,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
37
41
  | `--lens-compact-widget` | `ui.compactWidget` | `false` |
38
42
  | `--no-lazy-tools` | `tools.lazy` | `true` |
39
43
  | `--lens-turn-end-madge` | `turnEnd.madge.enabled` | `false` |
44
+ | `--lens-fallow` | `fallow.enabled` | `false` |
40
45
  | `--no-knip` | `knip.enabled` | `true` |
41
46
  | `--no-jscpd` | `jscpd.enabled` | `true` |
42
47
  | `--no-madge` | `madge.enabled` | `true` |
@@ -147,6 +152,8 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
147
152
 
148
153
  `turnEnd.madge.enabled` (default `false`) runs the per-turn-end madge circular-dependency check on import-changed files. It is off by default because that pass only writes debug output — user-facing madge diagnostics come from the session-start scan cache and the `lens_diagnostics` extractor — and its subprocess spawns dominated the turn-end latency tail (#766). Enable it with `--lens-turn-end-madge` or `turnEnd.madge.enabled: true` if you want the per-edit circular-dependency note.
149
154
 
155
+ `fallow.enabled` (default `false`, or `--lens-fallow`) runs [fallow](https://github.com/fallow-rs/fallow)'s `fallow-lsp` beside the TypeScript server on JS/TS files (`.ts .tsx .js .jsx .mjs .cjs .mts .cts`; no other file ever attaches it). It reports unused files, exports and dependencies, duplication and cycles as advisory warnings and never blocks. It overlaps knip, jscpd and madge, which keep running either way. Only the exact value `true` turns it on: an absent, misspelled or non-boolean value leaves it off, and pi-lens installs and launches nothing. On first use pi-lens downloads the pinned fallow release into `~/.pi-lens/tools/fallow-lsp` (a `fallow-lsp` already on `PATH` wins); the install is refused on a checksum mismatch. The per-edit diagnostics path runs it; the aggregate all-server checks (`lens_diagnostics source=lsp`, workspace sweeps) do not start it.
156
+
150
157
  `ignore` is an array of gitignore-style glob patterns excluded from pi-lens scans across **every** project — the global counterpart to the per-project `.pi-lens.json` `ignore` below. Precedence is lowest: a project `.gitignore` or `.pi-lens.json` (including a `!negation`) overrides it, so you can globally hide e.g. `scratch/**` and still re-include it in one repo.
151
158
 
152
159
  Turn subsystems off globally instead of retyping flags every session:
@@ -156,12 +163,16 @@ Turn subsystems off globally instead of retyping flags every session:
156
163
  "lsp": { "enabled": false },
157
164
  "tests": { "enabled": false },
158
165
  "opengrep": { "enabled": false },
166
+ "astGrep": { "enabled": false },
167
+ "zizmor": { "enabled": false },
168
+ "typos": { "enabled": false },
169
+ "spotbugs": { "enabled": true },
159
170
  "readGuard": { "enabled": false },
160
171
  "guard": { "enabled": true }
161
172
  }
162
173
  ```
163
174
 
164
- `lens.enabled: false` starts every session with pi-lens off (the `--no-lens` equivalent); `/lens-toggle` still re-enables it for one session. `lsp.enabled: false` falls back to language-specific checkers such as pyright. `tests.enabled: false` skips the on-write test runner. `delta.enabled: false` reports every diagnostic rather than only ones introduced this turn. `opengrep.enabled: false` detaches the Opengrep security scanner. `readGuard.enabled: false` turns off the read-before-edit monitor. `guard.enabled: true` opts into the experimental commit/push blocker.
175
+ `lens.enabled: false` starts every session with pi-lens off (the `--no-lens` equivalent); `/lens-toggle` still re-enables it for one session. `lsp.enabled: false` falls back to language-specific checkers such as pyright. `tests.enabled: false` skips the on-write test runner. `delta.enabled: false` reports every diagnostic rather than only ones introduced this turn. `opengrep.enabled: false` detaches the Opengrep security scanner. `astGrep.enabled: false` detaches the ast-grep auxiliary server. `zizmor.enabled: false` and `typos.enabled: false` detach the zizmor and typos auxiliary servers. `spotbugs.enabled: true` opts into SpotBugs on Java and Kotlin files (it also needs a Java build descriptor and a compiled `.class` directory). `readGuard.enabled: false` turns off the read-before-edit monitor. `guard.enabled: true` opts into the experimental commit/push blocker.
165
176
 
166
177
  The `tools.<name>.enabled` setting controls each model-facing tool. Valid names
167
178
  include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
@@ -39,6 +39,44 @@
39
39
  `record_retired` row (#4725). A dispatch that never answered
40
40
  (`pipeline_crash`, `pipeline_error`) is latched per file, apart from the
41
41
  record's latch, and only that file's own returning dispatch clears it.
42
+ - Inline blockers have owners (#4921). A blocker belongs to the turn session
43
+ whose write recorded it; a record with no `session` is the coordinator's.
44
+ The commit gate reads every record, whoever owns it, because the tree is
45
+ shared. A turn end reads only its own session's records: it delivers,
46
+ sweeps, re-judges and consumes those, and files its guard section under its
47
+ own id. The gate reads every record but retires only its own session's: its
48
+ missing-file sweep (#5020) persists into the cache of the acting session's
49
+ own records, whose cache is the coordinator root's cache or the session
50
+ cwd's, whichever wrote them, so another session's dead-cite row waits for
51
+ that session's own gate or turn end. Only a write by the coordinator's
52
+ session latches `session_mismatch`; a concurrent session's write leaves
53
+ another session's record and the latch alone.
54
+ - The commit gate is keyed by the repository being committed (#4941), not by
55
+ session. A commit/push is judged by the unresolved blockers whose files lie
56
+ in the git checkout it targets (`resolveGitCheckout`, the seam the review
57
+ graph and the analysis root use) or in a checkout nested inside it, whoever
58
+ wrote them; a linked worktree of the committed repository is a checkout of
59
+ its own, never the parent's. This covers every reader the gate has: the
60
+ inline-blocker latch memo, the stale-suppression scan, the dispatches that
61
+ never answered, and the record-failure latch, which holds one reason per
62
+ project (a failure or a write about repository B never replaces or clears
63
+ repository A's). A sub-agent committing in repository B is not refused for a
64
+ blocker in repository A; one committing where the blocker is still is. The
65
+ target comes from `resolveCommitScope` and fails closed: only plain `git`
66
+ segments (spelled `git` or a system path such as `/usr/bin/git`; global
67
+ option `-C <existing, unexpanded directory>` only) beside a short list of
68
+ neutral commands (`echo`, `tail`, ...) are placed in a tree, and only in a
69
+ process whose environment sets none of `GIT_DIR`, `GIT_WORK_TREE`,
70
+ `GIT_COMMON_DIR`. The gate never resolves PATH, so a bare `git` is trusted
71
+ whatever executable the shell finds under that name. `cd`, an assignment,
72
+ `--git-dir`, `--work-tree`, `-c`, a wrapper or any other path named `git`, a
73
+ `~` operand, a substitution that runs git, any other command in the chain,
74
+ or a directory outside a checkout leaves the command unscoped, and an unscoped command, a verdict that names no
75
+ file, and a caller that passes no command are judged by every blocker. The
76
+ persisted `turn-end-findings` record stays the committing session's
77
+ project's (`cwd`): for `git -C <other repo> commit` it is not read for the
78
+ targeted repository, so that record's blocker can be missed (a gap that
79
+ predates #4941).
42
80
  - The shared-checkout guard refuses unsafe worktree mutation when another live
43
81
  session and uncommitted work are both proven. It never auto-stashes.
44
82
  - `mcp/server.ts` talks to pi-lens through `clients/lens-engine.ts`. A mirrored
@@ -19,10 +19,21 @@
19
19
  legacy migrations, and namespaces live in the config-location/schema modules.
20
20
  A new config key or environment flag needs a forcing function, stability tier,
21
21
  diagnostic code, tests, and docs.
22
- - `rules.<id>.ignorePaths` is an experimental, project-relative path denial
23
- resolved by config-core with array-union semantics: global entries cannot be
24
- cleared by project config. Ast-grep and tree-sitter apply it before scanning;
25
- other runner output uses the shared rule-policy filter.
22
+ - `rules.<id>.ignorePaths` is an experimental path denial resolved by
23
+ config-core with array-union semantics: global entries cannot be cleared by
24
+ project config. Each entry is a gitignore line, matched as the `ignore` field
25
+ matches (#783: last match wins, `!` re-includes, a leading `/` roots it, a
26
+ trailing `/` is directory-only) through `isIgnoredByGitignoreLines`
27
+ (`clients/file-utils.ts`), relative to the directory of the file that
28
+ declares it (the project root for a global entry). Each file is its own
29
+ scope and a path is carved out when any scope ignores it, so a `!` never
30
+ lifts another file's carve-out. A rule's own YAML `ignores:` stays on the
31
+ ast-grep glob matcher (`isRuleIgnoredForPath`), which mirrors
32
+ `ast-grep scan`. Ast-grep and tree-sitter apply `ignorePaths` before
33
+ scanning; other runner output uses the shared rule-policy filter.
34
+ - `rules` and `dispatch.disabledRunners` are read per file from its config
35
+ owner (`resolveDispatchPolicyConfigForFile`, `loadProjectRulePolicy`), so a
36
+ nested `.pi-lens.json` governs its own files on every surface.
26
37
  - `lens_diagnostics` has one model-facing diagnostic surface. `source` is
27
38
  `session` or `lsp`; `scope` is `paths` or `workspace`; explicit paths always
28
39
  win. Severity is a threshold. Retired compatibility names must not widen a
@@ -5,6 +5,12 @@
5
5
  - `safeSpawnAsync` is the subprocess seam. It carries ambient abort behavior,
6
6
  process-tree cleanup, output caps, typed failure kinds, and bounded timeouts.
7
7
  Installs pass `ignoreAmbientSignal: true` and remain trust-gated.
8
+ The seam defaults `GIT_OPTIONAL_LOCKS=0`, so unless a caller `env` override
9
+ sets it, no child takes git's optional index lock that a timeout or host exit
10
+ could orphan (#4930). The cost of the default: git does not write back its
11
+ refreshed stat cache, so
12
+ on a stat-dirty checkout each status read re-hashes the dirty set until the
13
+ user's own git command refreshes the index.
8
14
  It is also the lookup chokepoint. Under pi trust other than
9
15
  `trusted`, every child's search path loses the session repository's own
10
16
  directories, and a bare command that still resolves into them is refused
@@ -96,8 +102,9 @@
96
102
  timers on every removal path.
97
103
  - Production callers use the grouped experimental `LspCapabilities` adapter in
98
104
  `clients/lsp/capabilities.ts`; direct `LSPService` module imports are limited
99
- to that adapter and are enforced by
100
- `tests/config/lsp-capabilities-import-sweep.test.ts` (#2372/#277).
105
+ to that adapter and are enforced by oxlint's `no-restricted-imports` in
106
+ `.oxlintrc.json` (`npm run lint:js`, #2372/#277; it replaced the
107
+ `lsp-capabilities-import-sweep` test in #4865).
101
108
  - Idle-eviction policy is the registry's `idleEviction` field, declared per
102
109
  server. The nightly (`scripts/measure-lsp-idle-eviction.mjs`) measures every
103
110
  registry server's eviction cost and respawn safety into
@@ -181,6 +188,19 @@
181
188
  - Per-path LSP notifications serialize read/build/send/record work. Pull
182
189
  cancellation blocks a same-path replacement until settlement. Waits are
183
190
  deadline- and abort-bounded, and silence is never clean.
191
+ - A cached answer is evidence about the state it was published for, never about a
192
+ later change. `touchFile` skips a notify for bytes the server already holds
193
+ (see the debounce bullet below), so the diagnostics it reports can be an
194
+ entry the server published before the caller's edit; it names that case
195
+ (`TouchFileResult.reusedAnswer`, server plus publish stamp) and never claims
196
+ it as the touch's own answer. The cascade reads it (`isPreEditAnswer`,
197
+ `clients/dispatch/integration.ts`): an answer published before the run's edit
198
+ is unconfirmed, never clean, exactly as `isPostEditObservation` already rules
199
+ for the passive snapshot and both fallbacks. An answer published after the
200
+ edit (a push or pull inside the touch, the `typescript.tsserverRequest` sync
201
+ confirm, or a server that republished for the file after the edit) keeps its
202
+ verdict. A client that cannot date its cache reports no reuse and keeps the
203
+ pre-#5040 verdict.
184
204
  - Document line addressing has one owner, `clients/lsp/content-scan.ts`: the
185
205
  `\n` count behind the `lsp_document_send` record's `contentLineCount` and the
186
206
  LSP sync bound (`countLfNewlines`), the last LSP-addressable line an
@@ -15,8 +15,10 @@
15
15
  base expansion) or `resolveToolCallFilePath` (base plus pi's variant
16
16
  ladder), never a bare `path.resolve(base, raw)`; see shape 74.
17
17
  - Windows-shaped paths use `path.win32` functions. Use `toPosix`,
18
- `splitPathSegments`, `isUnderDir`, `isSameOrWithin`, and
19
- `isAtOrAboveHomeDir` instead of inline separator or containment logic.
18
+ `splitPathSegments`, `isUnderDir`, `isSameOrWithin`, `relativeInside`
19
+ (lexical containment with the relative text), `isWithinIdentity`
20
+ (containment on the identity axis), and `isAtOrAboveHomeDir` instead of
21
+ inline separator or containment logic.
20
22
  - Data and log locations follow **Data directories and logs**; never hardcode
21
23
  `.pi-lens` paths in writes or user-facing text.
22
24
  - Probes and child processes pin `PI_LENS_HOME`, `PILENS_DATA_DIR`, `HOME`, and
@@ -27,8 +27,25 @@
27
27
  write-order turn and change window only for its own session, and per-turn
28
28
  warnings are partitioned by the session that recorded them. Every
29
29
  producer and reader passes that id (`tool_result`, a partial apply's
30
- pipeline, `turn_end`). A concurrent secondary still shares the read guard
31
- and the turn-end worklist (the open half of #3613). State `turn_end` parks
30
+ pipeline, `turn_end`). The read guard is the turn's session's too (#4942,
31
+ the half of #3613 this paragraph used to leave open):
32
+ `RuntimeCoordinator.readGuardFor(sessionId)` answers with the coordinator's
33
+ own guard for a turn with no session id of its own, and with a guard of its
34
+ own, built on first use and dropped at its shutdown or at the coordinator's
35
+ own reset, for a concurrent secondary. It keys that guard by the opaque owner
36
+ the inline blockers use
37
+ (#4921, `recordSession`), so an edit is judged by the reads and writes of
38
+ the session that edits. The coordinator's own guard is the primary's only
39
+ while the ctx's stable session id equals the pinned telemetry id
40
+ (`setSessionLifecycle`); a start that cannot read its id would leave the
41
+ primary's turns on a foreign guard, where a primary `/tree` no longer
42
+ filters their reads (a hypothesis, reproduced only as a composite probe,
43
+ #4955 review F3).
44
+ A read or write reported through the mutation or
45
+ read bridge is credited to the coordinator's guard, even when the
46
+ mutation entry names a session (`BridgeMutationEntry.sessionId` routes
47
+ only the turn state and the change log, #4955 review F11). A concurrent
48
+ secondary still shares the turn-end worklist. State `turn_end` parks
32
49
  in a scope cell for a later turn lives on the activation's own scope
33
50
  (`TurnEndDeps.sessionScope`, passed by `index.ts`), never on
34
51
  `runtime.sessionScope`, which is the primary's during a secondary's turn
@@ -37,6 +54,29 @@
37
54
  the coordinator's for the coordinator and module stores a secondary
38
55
  shares, the activation's for its own scope cell. One store never answers
39
56
  to two scopes, and a secondary's end fences only its cell.
57
+ - The project's one turn-end delivery slot (`turn-end-findings`'s
58
+ `content`) is addressed (#4943): the composer stamps `deliverTo` with its
59
+ turn's session, a commit-gate rewrite of the content leaves it out so the
60
+ record's owner (`sessionId`) is the addressee, and the `context` hook
61
+ consumes only a record addressed to its own session (the composer's id
62
+ expression); any other request leaves it untouched and writes one
63
+ `turn-end-delivery-addressed-elsewhere` ledger record per addressee. A
64
+ record with neither field goes to whoever asks. The sibling
65
+ `test-runner-findings` slot is read with the same id
66
+ (`deliveryEligible.sessionId`): a concurrent secondary never pins the
67
+ coordinator id. The MCP host stages to one address shared by every server
68
+ process (`MCP_DELIVERY_ADDRESS`) and reads as that address, with its
69
+ coordinator id, reassigned at each session start, for a record whose rewrite
70
+ left only the owner: a restarted server still delivers what the last one
71
+ staged, and neither its Stop pass nor its acknowledge takes a pi session's
72
+ message. The exception is a record a commit-gate rewrite replaced: it holds
73
+ only the owner id, so a server whose id was reassigned since (a restart, or
74
+ a later `pilens_session_start`) skips it and leaves it in place (accepted
75
+ residual, #4973).
76
+ A staged message another writer replaces before its owner asks is not
77
+ kept; the owner's next turn end composes its unresolved blockers again,
78
+ since the dedupe's last writer was the other session, but a one-shot
79
+ advisory is not composed again.
40
80
  - Every session-scope hand-off decision leaves one `latency.log` row per
41
81
  lifecycle event, never one per occurrence in a loop (#3873):
42
82
  `session_handoff_slot`, `session_handoff_adopt`, `session_store_action`