pi-lens 3.8.73 → 3.8.74

package/README.md

@@ -6,6 +6,10 @@
 
 pi-lens gives AI coding agents fast, language-aware feedback while they write/edit.
 
+> **Working in this project as an AI agent?** Read the [agent guide](docs/agent-guide.md)
+> for how pi-lens surfaces diagnostics (honesty labels, blockers, read-before-edit)
+> and how to respond.
+
 ## What It Does
 
 - LSP diagnostics and navigation across supported languages
@@ -47,6 +51,7 @@ pi install git:github.com/apmantza/pi-lens
 
 ## Documentation
 
+- [Agent guide](docs/agent-guide.md) — how an AI agent should consume and respond to pi-lens
 - [Agent tools](docs/agent-tools.md) — pi tool names, scopes, and arguments
 - [Usage guide](docs/usage.md) — lifecycle, tool behavior, MCP notes, and
   troubleshooting
@@ -56,9 +61,11 @@ pi install git:github.com/apmantza/pi-lens
 - [Tools and commands](docs/tools.md) — runtime flags and slash commands
 - [Diagnostic dispositions](docs/dispositions.md) — triage: false-positive,
   suppress, defer, flagged-to-fix
+- [Settings](docs/settings.md) — the configuration hub: defaults, env vars, CLI
+  flags, and global vs project config at a glance
 - [Configuration](docs/globalconfig.md) — global and project config files
-- [Environment variables](docs/env_variables.md) — common env vars and full
-  reference link
+- [Environment variables](docs/environment-variables.md) — common env vars and
+  full reference
 - [Language coverage](docs/language-coverage.md) — supported languages, runners,
   and formatters
 - [Dependencies](docs/dependencies.md) — auto-install policy and external tools
@@ -82,120 +89,123 @@ Thanks goes to these wonderful people:
   <tbody>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/apmantza"><img src="https://avatars.githubusercontent.com/u/247365598?v=4" width="100px;" alt=""/><br /><sub><b>Apostolos Mantzaris</b></sub></a><br /><a href="#code-apmantza" title="Code">💻</a> <a href="#doc-apmantza" title="Documentation">📖</a> <a href="#ideas-apmantza" title="Ideas & Planning">🤔</a> <a href="#maintenance-apmantza" title="Maintenance">🚧</a> <a href="#review-apmantza" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/AngriestBird"><img src="https://avatars.githubusercontent.com/u/12663269?v=4" width="100px;" alt=""/><br /><sub><b>Kenneth McCormick</b></sub></a><br /><a href="#bug-AngriestBird" title="Bug reports">🐛</a> <a href="#code-AngriestBird" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/anh-chu"><img src="https://avatars.githubusercontent.com/u/34973633?v=4" width="100px;" alt=""/><br /><sub><b>Anh Chu</b></sub></a><br /><a href="#code-anh-chu" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/loss-and-quick"><img src="https://avatars.githubusercontent.com/u/39405619?v=4" width="100px;" alt=""/><br /><sub><b>minicx</b></sub></a><br /><a href="#code-loss-and-quick" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/silvanshade"><img src="https://avatars.githubusercontent.com/u/11022302?v=4" width="100px;" alt=""/><br /><sub><b>silvanshade</b></sub></a><br /><a href="#code-silvanshade" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tifandotme"><img src="https://avatars.githubusercontent.com/u/33323177?v=4" width="100px;" alt=""/><br /><sub><b>Tifan Dwi Avianto</b></sub></a><br /><a href="#code-tifandotme" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/amit-gshe"><img src="https://avatars.githubusercontent.com/u/7383028?v=4" width="100px;" alt=""/><br /><sub><b>Amit</b></sub></a><br /><a href="#code-amit-gshe" title="Code">💻</a> <a href="#bug-amit-gshe" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/fractiunate"><img src="https://avatars.githubusercontent.com/u/78024279?v=4" width="100px;" alt=""/><br /><sub><b>Fractiunate // David Rahäuser</b></sub></a><br /><a href="#code-fractiunate" title="Code">💻</a></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/fractiunate"><img src="https://avatars.githubusercontent.com/u/78024279?v=4" width="100px;" alt=""/><br /><sub><b>Fractiunate // David Rahäuser</b></sub></a><br /><a href="#code-fractiunate" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/vkarasen"><img src="https://avatars.githubusercontent.com/u/7932536?v=4" width="100px;" alt=""/><br /><sub><b>Vitali Karasenko</b></sub></a><br /><a href="#code-vkarasen" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/rfxlamia"><img src="https://avatars.githubusercontent.com/u/222023708?v=4" width="100px;" alt=""/><br /><sub><b>V</b></sub></a><br /><a href="#code-rfxlamia" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/fabio-dee"><img src="https://avatars.githubusercontent.com/u/10808443?v=4" width="100px;" alt=""/><br /><sub><b>Fabio Dee</b></sub></a><br /><a href="#code-fabio-dee" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/moj02090"><img src="https://avatars.githubusercontent.com/u/57255166?v=4" width="100px;" alt=""/><br /><sub><b>moj02090</b></sub></a><br /><a href="#code-moj02090" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mehalter"><img src="https://avatars.githubusercontent.com/u/1591837?v=4" width="100px;" alt=""/><br /><sub><b>Micah Halter</b></sub></a><br /><a href="#code-mehalter" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JulienEllie"><img src="https://avatars.githubusercontent.com/u/670518?v=4" width="100px;" alt=""/><br /><sub><b>Julien Ellie</b></sub></a><br /><a href="#code-JulienEllie" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Istar-Eldritch"><img src="https://avatars.githubusercontent.com/u/3746468?v=4" width="100px;" alt=""/><br /><sub><b>Ruben Paz</b></sub></a><br /><a href="#code-Istar-Eldritch" title="Code">💻</a> <a href="#bug-Istar-Eldritch" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Istar-Eldritch"><img src="https://avatars.githubusercontent.com/u/3746468?v=4" width="100px;" alt=""/><br /><sub><b>Ruben Paz</b></sub></a><br /><a href="#code-Istar-Eldritch" title="Code">💻</a> <a href="#bug-Istar-Eldritch" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/cjunxiang"><img src="https://avatars.githubusercontent.com/u/26619858?v=4" width="100px;" alt=""/><br /><sub><b>C.Junxiang</b></sub></a><br /><a href="#code-cjunxiang" title="Code">💻</a> <a href="#bug-cjunxiang" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/trvon"><img src="https://avatars.githubusercontent.com/u/6031322?v=4" width="100px;" alt=""/><br /><sub><b>Trevon</b></sub></a><br /><a href="#code-trvon" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/cmptr"><img src="https://avatars.githubusercontent.com/u/32746889?v=4" width="100px;" alt=""/><br /><sub><b>Aaron Bell</b></sub></a><br /><a href="#code-cmptr" title="Code">💻</a> <a href="#bug-cmptr" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/StartupBros"><img src="https://avatars.githubusercontent.com/u/16693591?v=4" width="100px;" alt=""/><br /><sub><b>Will Mitchell</b></sub></a><br /><a href="#code-StartupBros" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/spyrosbazios"><img src="https://avatars.githubusercontent.com/u/37960233?v=4" width="100px;" alt=""/><br /><sub><b>spyrosbazios</b></sub></a><br /><a href="#code-spyrosbazios" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Roman-Galeev"><img src="https://avatars.githubusercontent.com/u/40388226?v=4" width="100px;" alt=""/><br /><sub><b>Roman Galeev</b></sub></a><br /><a href="#code-Roman-Galeev" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jerryfan"><img src="https://avatars.githubusercontent.com/u/2540814?v=4" width="100px;" alt=""/><br /><sub><b>jerryfan</b></sub></a><br /><a href="#code-jerryfan" title="Code">💻</a></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/jerryfan"><img src="https://avatars.githubusercontent.com/u/2540814?v=4" width="100px;" alt=""/><br /><sub><b>jerryfan</b></sub></a><br /><a href="#code-jerryfan" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/shaDmx"><img src="https://avatars.githubusercontent.com/u/91132641?v=4" width="100px;" alt=""/><br /><sub><b>Max L.</b></sub></a><br /><a href="#code-shaDmx" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/radge"><img src="https://avatars.githubusercontent.com/u/129205?v=4" width="100px;" alt=""/><br /><sub><b>David Ryan</b></sub></a><br /><a href="#code-radge" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JayceFreeman"><img src="https://avatars.githubusercontent.com/u/92962110?v=4" width="100px;" alt=""/><br /><sub><b>JayceFreeman</b></sub></a><br /><a href="#code-JayceFreeman" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/bloodf"><img src="https://avatars.githubusercontent.com/u/1626923?v=4" width="100px;" alt=""/><br /><sub><b>Heitor Ramon Ribeiro</b></sub></a><br /><a href="#code-bloodf" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/feoh"><img src="https://avatars.githubusercontent.com/u/330070?v=4" width="100px;" alt=""/><br /><sub><b>Chris Patti</b></sub></a><br /><a href="#code-feoh" title="Code">💻</a> <a href="#bug-feoh" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/chenxin-yan"><img src="https://avatars.githubusercontent.com/u/71162231?v=4" width="100px;" alt=""/><br /><sub><b>Chenxin Yan</b></sub></a><br /><a href="#code-chenxin-yan" title="Code">💻</a> <a href="#doc-chenxin-yan" title="Documentation">📖</a> <a href="#bug-chenxin-yan" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/flowing-abyss"><img src="https://avatars.githubusercontent.com/u/98622217?v=4" width="100px;" alt=""/><br /><sub><b>flowing-abyss</b></sub></a><br /><a href="#code-flowing-abyss" title="Code">💻</a></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/flowing-abyss"><img src="https://avatars.githubusercontent.com/u/98622217?v=4" width="100px;" alt=""/><br /><sub><b>flowing-abyss</b></sub></a><br /><a href="#code-flowing-abyss" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/shaochong-theoai"><img src="https://avatars.githubusercontent.com/u/305592060?v=4" width="100px;" alt=""/><br /><sub><b>shaochong-theoai</b></sub></a><br /><a href="#code-shaochong-theoai" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/xuli500177"><img src="https://avatars.githubusercontent.com/u/62830942?v=4" width="100px;" alt=""/><br /><sub><b>Xu Yili</b></sub></a><br /><a href="#bug-xuli500177" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/xuli500177"><img src="https://avatars.githubusercontent.com/u/62830942?v=4" width="100px;" alt=""/><br /><sub><b>Xu Yili</b></sub></a><br /><a href="#bug-xuli500177" title="Bug reports">🐛</a> <a href="#code-xuli500177" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ricardoraposo"><img src="https://avatars.githubusercontent.com/u/50217712?v=4" width="100px;" alt=""/><br /><sub><b>Ricardo Raposo</b></sub></a><br /><a href="#code-ricardoraposo" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jsmestad"><img src="https://avatars.githubusercontent.com/u/16150?v=4" width="100px;" alt=""/><br /><sub><b>Justin Smestad</b></sub></a><br /><a href="#code-jsmestad" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/anasalsbey-glitch"><img src="https://avatars.githubusercontent.com/u/283609702?v=4" width="100px;" alt=""/><br /><sub><b>anasalsbey-glitch</b></sub></a><br /><a href="#code-anasalsbey-glitch" title="Code">💻</a> <a href="#bug-anasalsbey-glitch" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/PeraSite"><img src="https://avatars.githubusercontent.com/u/19837403?v=4" width="100px;" alt=""/><br /><sub><b>정제훈</b></sub></a><br /><a href="#code-PeraSite" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/carolitascl"><img src="https://avatars.githubusercontent.com/u/26188349?v=4" width="100px;" alt=""/><br /><sub><b>Carolina</b></sub></a><br /><a href="#bug-carolitascl" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ymek"><img src="https://avatars.githubusercontent.com/u/300569?v=4" width="100px;" alt=""/><br /><sub><b>Myke Stubbs</b></sub></a><br /><a href="#code-ymek" title="Code">💻</a> <a href="#bug-ymek" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/JSap0914"><img src="https://avatars.githubusercontent.com/u/116227558?v=4" width="100px;" alt=""/><br /><sub><b>JSap0914</b></sub></a><br /><a href="#code-JSap0914" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/knthmn"><img src="https://avatars.githubusercontent.com/u/60438008?v=4" width="100px;" alt=""/><br /><sub><b>Kent Hou Man</b></sub></a><br /><a href="#code-knthmn" title="Code">💻</a> <a href="#bug-knthmn" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://neumie.dev/"><img src="https://avatars.githubusercontent.com/u/23665482?v=4" width="100px;" alt=""/><br /><sub><b>Jakub Neumann</b></sub></a><br /><a href="#code-neumie" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/cy7372"><img src="https://avatars.githubusercontent.com/u/142197117?v=4" width="100px;" alt=""/><br /><sub><b>CyYu</b></sub></a><br /><a href="#code-cy7372" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/carolitascl"><img src="https://avatars.githubusercontent.com/u/26188349?v=4" width="100px;" alt=""/><br /><sub><b>Carolina</b></sub></a><br /><a href="#bug-carolitascl" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/leakedby"><img src="https://avatars.githubusercontent.com/u/4213260?v=4" width="100px;" alt=""/><br /><sub><b>LeakedBy</b></sub></a><br /><a href="#bug-leakedby" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mdbooth"><img src="https://avatars.githubusercontent.com/u/1318691?v=4" width="100px;" alt=""/><br /><sub><b>Matthew Booth</b></sub></a><br /><a href="#bug-mdbooth" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Wiedzmin89"><img src="https://avatars.githubusercontent.com/u/61706855?v=4" width="100px;" alt=""/><br /><sub><b>Wiedzmin89</b></sub></a><br /><a href="#ideas-Wiedzmin89" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/grodingo"><img src="https://avatars.githubusercontent.com/u/244184972?v=4" width="100px;" alt=""/><br /><sub><b>Virgile</b></sub></a><br /><a href="#bug-grodingo" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/finnvyrn"><img src="https://avatars.githubusercontent.com/u/90801772?v=4" width="100px;" alt=""/><br /><sub><b>Finn</b></sub></a><br /><a href="#ideas-finnvyrn" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ywh555hhh"><img src="https://avatars.githubusercontent.com/u/121592812?v=4" width="100px;" alt=""/><br /><sub><b>Wayne E</b></sub></a><br /><a href="#bug-ywh555hhh" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/RimuruW"><img src="https://avatars.githubusercontent.com/u/59136309?v=4" width="100px;" alt=""/><br /><sub><b>RimuruW</b></sub></a><br /><a href="#ideas-RimuruW" title="Ideas & Planning">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Bjynt"><img src="https://avatars.githubusercontent.com/u/22177300?v=4" width="100px;" alt=""/><br /><sub><b>Bjynt</b></sub></a><br /><a href="#bug-Bjynt" title="Bug reports">🐛</a> <a href="#ideas-Bjynt" title="Ideas & Planning">🤔</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Bjynt"><img src="https://avatars.githubusercontent.com/u/22177300?v=4" width="100px;" alt=""/><br /><sub><b>Bjynt</b></sub></a><br /><a href="#bug-Bjynt" title="Bug reports">🐛</a> <a href="#ideas-Bjynt" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pvtri96"><img src="https://avatars.githubusercontent.com/u/28696888?v=4" width="100px;" alt=""/><br /><sub><b>Tri Van Pham</b></sub></a><br /><a href="#bug-pvtri96" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/BingWuJ"><img src="https://avatars.githubusercontent.com/u/117666511?v=4" width="100px;" alt=""/><br /><sub><b>BingWuJ</b></sub></a><br /><a href="#bug-BingWuJ" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tackleberrybey"><img src="https://avatars.githubusercontent.com/u/156954032?v=4" width="100px;" alt=""/><br /><sub><b>tackleberrybey</b></sub></a><br /><a href="#bug-tackleberrybey" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/TaterDoge"><img src="https://avatars.githubusercontent.com/u/121467933?v=4" width="100px;" alt=""/><br /><sub><b>Mariann Abshire</b></sub></a><br /><a href="#bug-TaterDoge" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ProbabilityEngineer"><img src="https://avatars.githubusercontent.com/u/38498804?v=4" width="100px;" alt=""/><br /><sub><b>ProbabilityEngineer</b></sub></a><br /><a href="#ideas-ProbabilityEngineer" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/LeonardoRick"><img src="https://avatars.githubusercontent.com/u/17517057?v=4" width="100px;" alt=""/><br /><sub><b>Leonardo Rick</b></sub></a><br /><a href="#bug-LeonardoRick" title="Bug reports">🐛</a> <a href="#ideas-LeonardoRick" title="Ideas & Planning">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kenbanks-peng"><img src="https://avatars.githubusercontent.com/u/26904200?v=4" width="100px;" alt=""/><br /><sub><b>Ken Banks</b></sub></a><br /><a href="#bug-kenbanks-peng" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kenbanks-peng"><img src="https://avatars.githubusercontent.com/u/26904200?v=4" width="100px;" alt=""/><br /><sub><b>Ken Banks</b></sub></a><br /><a href="#bug-kenbanks-peng" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/rstacruz"><img src="https://avatars.githubusercontent.com/u/74385?v=4" width="100px;" alt=""/><br /><sub><b>Rico Sta. Cruz</b></sub></a><br /><a href="#ideas-rstacruz" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/acidnik"><img src="https://avatars.githubusercontent.com/u/1227955?v=4" width="100px;" alt=""/><br /><sub><b>Nikita Bilous</b></sub></a><br /><a href="#bug-acidnik" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/av1155"><img src="https://avatars.githubusercontent.com/u/117413846?v=4" width="100px;" alt=""/><br /><sub><b>Andrea Arturo Venti Fuentes</b></sub></a><br /><a href="#bug-av1155" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/dacec354"><img src="https://avatars.githubusercontent.com/u/90093629?v=4" width="100px;" alt=""/><br /><sub><b>dacec354</b></sub></a><br /><a href="#bug-dacec354" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/nodnarbnitram"><img src="https://avatars.githubusercontent.com/u/44812862?v=4" width="100px;" alt=""/><br /><sub><b>Brandon Martin</b></sub></a><br /><a href="#bug-nodnarbnitram" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/alpertarhan"><img src="https://avatars.githubusercontent.com/u/50966980?v=4" width="100px;" alt=""/><br /><sub><b>Alper Tarhan</b></sub></a><br /><a href="#bug-alpertarhan" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/asolopovas"><img src="https://avatars.githubusercontent.com/u/6893216?v=4" width="100px;" alt=""/><br /><sub><b>Andrius Solopovas</b></sub></a><br /><a href="#bug-asolopovas" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/asolopovas"><img src="https://avatars.githubusercontent.com/u/6893216?v=4" width="100px;" alt=""/><br /><sub><b>Andrius Solopovas</b></sub></a><br /><a href="#bug-asolopovas" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/GrahamJenkins"><img src="https://avatars.githubusercontent.com/u/6607975?v=4" width="100px;" alt=""/><br /><sub><b>Graham Jenkins</b></sub></a><br /><a href="#bug-GrahamJenkins" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/wings1848"><img src="https://avatars.githubusercontent.com/u/120104016?v=4" width="100px;" alt=""/><br /><sub><b>Wings Butterfly</b></sub></a><br /><a href="#bug-wings1848" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JohannesKlauss"><img src="https://avatars.githubusercontent.com/u/6214415?v=4" width="100px;" alt=""/><br /><sub><b>Johannes Klauss</b></sub></a><br /><a href="#ideas-JohannesKlauss" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tan-yong-sheng"><img src="https://avatars.githubusercontent.com/u/64836390?v=4" width="100px;" alt=""/><br /><sub><b>Tan Yong Sheng</b></sub></a><br /><a href="#ideas-tan-yong-sheng" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/fmatray"><img src="https://avatars.githubusercontent.com/u/8267716?v=4" width="100px;" alt=""/><br /><sub><b>Frédéric</b></sub></a><br /><a href="#bug-fmatray" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/fuentesjr"><img src="https://avatars.githubusercontent.com/u/9240?v=4" width="100px;" alt=""/><br /><sub><b>Salvador Fuentes Jr</b></sub></a><br /><a href="#bug-fuentesjr" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Viterkim"><img src="https://avatars.githubusercontent.com/u/17838985?v=4" width="100px;" alt=""/><br /><sub><b>Viktor</b></sub></a><br /><a href="#bug-Viterkim" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Viterkim"><img src="https://avatars.githubusercontent.com/u/17838985?v=4" width="100px;" alt=""/><br /><sub><b>Viktor</b></sub></a><br /><a href="#bug-Viterkim" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ortonomy"><img src="https://avatars.githubusercontent.com/u/6688676?v=4" width="100px;" alt=""/><br /><sub><b>Gregory Orton</b></sub></a><br /><a href="#bug-ortonomy" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jimallen"><img src="https://avatars.githubusercontent.com/u/868773?v=4" width="100px;" alt=""/><br /><sub><b>Jim Allen</b></sub></a><br /><a href="#bug-jimallen" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/quantfiction"><img src="https://avatars.githubusercontent.com/u/49965454?v=4" width="100px;" alt=""/><br /><sub><b>quantfiction</b></sub></a><br /><a href="#bug-quantfiction" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Artawower"><img src="https://avatars.githubusercontent.com/u/16963833?v=4" width="100px;" alt=""/><br /><sub><b>Art</b></sub></a><br /><a href="#bug-Artawower" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/chozandrias76"><img src="https://avatars.githubusercontent.com/u/2087677?v=4" width="100px;" alt=""/><br /><sub><b>Colin Swenson-Healey</b></sub></a><br /><a href="#bug-chozandrias76" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JustlyAI"><img src="https://avatars.githubusercontent.com/u/12634140?v=4" width="100px;" alt=""/><br /><sub><b>Laurent Wiesel</b></sub></a><br /><a href="#bug-JustlyAI" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/stark-bit"><img src="https://avatars.githubusercontent.com/u/44064758?v=4" width="100px;" alt=""/><br /><sub><b>Rei Starks</b></sub></a><br /><a href="#bug-stark-bit" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/stark-bit"><img src="https://avatars.githubusercontent.com/u/44064758?v=4" width="100px;" alt=""/><br /><sub><b>Rei Starks</b></sub></a><br /><a href="#bug-stark-bit" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/robertoecf"><img src="https://avatars.githubusercontent.com/u/54923863?v=4" width="100px;" alt=""/><br /><sub><b>Roberto Freitas</b></sub></a><br /><a href="#bug-robertoecf" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tmttodd"><img src="https://avatars.githubusercontent.com/u/160077416?v=4" width="100px;" alt=""/><br /><sub><b>tmttodd</b></sub></a><br /><a href="#bug-tmttodd" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/smaharnav"><img src="https://avatars.githubusercontent.com/u/263328627?v=4" width="100px;" alt=""/><br /><sub><b>smaharnav</b></sub></a><br /><a href="#bug-smaharnav" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/MzaGuille"><img src="https://avatars.githubusercontent.com/u/151482698?v=4" width="100px;" alt=""/><br /><sub><b>Mza.Guille</b></sub></a><br /><a href="#bug-MzaGuille" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://jasonrimmer.com/"><img src="https://avatars.githubusercontent.com/u/629?v=4" width="100px;" alt=""/><br /><sub><b>Jason Rimmer</b></sub></a><br /><a href="#bug-jrimmer" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ArthurHeymans"><img src="https://avatars.githubusercontent.com/u/15137817?v=4" width="100px;" alt=""/><br /><sub><b>Arthur Heymans</b></sub></a><br /><a href="#ideas-ArthurHeymans" title="Ideas & Planning">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Blue-B"><img src="https://avatars.githubusercontent.com/u/55532956?v=4" width="100px;" alt=""/><br /><sub><b>Blue-B</b></sub></a><br /><a href="#bug-Blue-B" title="Bug reports">🐛</a></td>
     </tr>
     <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Blue-B"><img src="https://avatars.githubusercontent.com/u/55532956?v=4" width="100px;" alt=""/><br /><sub><b>Blue-B</b></sub></a><br /><a href="#bug-Blue-B" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/bisko"><img src="https://avatars.githubusercontent.com/u/184938?v=4" width="100px;" alt=""/><br /><sub><b>Biser Perchinkov</b></sub></a><br /><a href="#bug-bisko" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/xificurC"><img src="https://avatars.githubusercontent.com/u/4800719?v=4" width="100px;" alt=""/><br /><sub><b>Peter Nagy</b></sub></a><br /><a href="#bug-xificurC" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/orest-tokovenko-block"><img src="https://avatars.githubusercontent.com/u/190554467?v=4" width="100px;" alt=""/><br /><sub><b>Orest Tokovenko</b></sub></a><br /><a href="#bug-orest-tokovenko-block" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://eisterman.dev/"><img src="https://avatars.githubusercontent.com/u/3028953?v=4" width="100px;" alt=""/><br /><sub><b>Federico Pasqua</b></sub></a><br /><a href="#bug-eisterman" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/ymek"><img src="https://avatars.githubusercontent.com/u/300569?v=4" width="100px;" alt=""/><br /><sub><b>Myke Stubbs</b></sub></a><br /><a href="#code-ymek" title="Code">💻</a> <a href="#bug-ymek" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/black-snow"><img src="https://avatars.githubusercontent.com/u/579733?v=4" width="100px;" alt=""/><br /><sub><b>Ronald</b></sub></a><br /><a href="#bug-black-snow" title="Bug reports">🐛</a></td>
-    </tr>
-    <tr>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/JSap0914"><img src="https://avatars.githubusercontent.com/u/116227558?v=4" width="100px;" alt=""/><br /><sub><b>JSap0914</b></sub></a><br /><a href="#code-JSap0914" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/AngriestBird"><img src="https://avatars.githubusercontent.com/u/12663269?v=4" width="100px;" alt=""/><br /><sub><b>Kenneth McCormick</b></sub></a><br /><a href="#bug-AngriestBird" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/knthmn"><img src="https://avatars.githubusercontent.com/u/60438008?v=4" width="100px;" alt=""/><br /><sub><b>Kent Hou Man</b></sub></a><br /><a href="#code-knthmn" title="Code">💻</a> <a href="#bug-knthmn" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/aaronkyriesenbach"><img src="https://avatars.githubusercontent.com/u/12665860?v=4" width="100px;" alt=""/><br /><sub><b>Aaron Ky-Riesenbach</b></sub></a><br /><a href="#bug-aaronkyriesenbach" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/LovelyLoong"><img src="https://avatars.githubusercontent.com/u/54889641?v=4" width="100px;" alt=""/><br /><sub><b>可爱的龙</b></sub></a><br /><a href="#bug-LovelyLoong" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pppobear"><img src="https://avatars.githubusercontent.com/u/21952175?v=4" width="100px;" alt=""/><br /><sub><b>pppobear</b></sub></a><br /><a href="#bug-pppobear" title="Bug reports">🐛</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://neumie.dev/"><img src="https://avatars.githubusercontent.com/u/23665482?v=4" width="100px;" alt=""/><br /><sub><b>Jakub Neumann</b></sub></a><br /><a href="#code-neumie" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>
@@ -205,4 +215,10 @@ Thanks goes to these wonderful people:
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
+The following commit identities also appear in `git shortlog -sne HEAD` but are
+not represented in the generated table above: Anas Alsbei, Claude,
+Christopher Patti,
+dependabot[bot], Fabio-D, github-actions[bot], JSup, Kenny McCormick,
+Max Lupus, Moritz Hofmann, ricardo, and root.
+
 If you land a pull request or report an issue that gets fixed, we'll add you here.

package/dist/clients/atomic-write.js

@@ -30,7 +30,7 @@
  */
 import * as fs from "node:fs";
 /**
- * Synchronous atomic write: `fs.writeFileSync` to `${targetPath}.tmp-${pid}`,
+ * Synchronous atomic write of text or binary data to `${targetPath}.tmp-${pid}`,
  * then `fs.renameSync` over `targetPath`. On any failure (from either step),
  * attempts a best-effort `fs.rmSync(tmp, { force: true })` cleanup, then
  * either swallows (default) or rethrows per `options.bestEffort`.
@@ -43,7 +43,7 @@ export function writeFileAtomic(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
     const tmpPath = `${targetPath}.tmp-${process.pid}`;
     try {
-        fs.writeFileSync(tmpPath, data, "utf-8");
+        fs.writeFileSync(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         fs.renameSync(tmpPath, targetPath);
     }
     catch (err) {
@@ -67,7 +67,7 @@ export async function writeFileAtomicAsync(targetPath, data, options) {
     const bestEffort = options?.bestEffort ?? true;
     const tmpPath = `${targetPath}.tmp-${process.pid}`;
     try {
-        await fs.promises.writeFile(tmpPath, data, "utf-8");
+        await fs.promises.writeFile(tmpPath, data, typeof data === "string" ? "utf-8" : undefined);
         await fs.promises.rename(tmpPath, targetPath);
     }
     catch (err) {

package/dist/clients/bus-events-logger.js

@@ -36,8 +36,12 @@ import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
+import { getMaxLogSizeMB } from "./log-cleanup.js";
 const BUS_EVENTS_LOG_FILE = path.join(getGlobalPiLensDir(), "bus-events.log");
-const writer = createNdjsonLogger({ filePath: BUS_EVENTS_LOG_FILE });
+const writer = createNdjsonLogger({
+    filePath: BUS_EVENTS_LOG_FILE,
+    maxBytes: getMaxLogSizeMB() * 1024 * 1024,
+});
 export function logBusEvent(entry) {
     if (isTestMode()) {
         return;

package/dist/clients/cache/rule-cache.js

@@ -9,11 +9,24 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "../file-utils.js";
 import { readJsonCache } from "../json-cache-read.js";
-const CACHE_VERSION = "v3";
+// v4: cache skip_test_files + fix_action — v3 entries silently dropped them,
+// and ruleHash (rule-file mtimes) never invalidates on a code-only fix.
+// v5 (#675): rule SELECTION changed in code — javascript no longer inherits the
+// typescript rule set and tsx now does. A v4 entry holds the old merge, and
+// queries now compile against the file's parse language, so replaying it would
+// fire typescript rules on javascript trees for real this time.
+// v6 (#878): the ruleHash FINGERPRINT now covers the full effective rule set —
+// inherited rule-source directories (tsx also runs typescript rules), not just
+// the language's own. A v5 tsx entry was hashed over tsx files only, so a
+// typescript-rule edit never invalidated it; v5 entries self-miss anyway (the
+// hash input set changed), the bump just makes the semantics break explicit.
+export const CACHE_VERSION = "v6";
 export class RuleCache {
     cacheFile;
     cacheDir;
+    language;
     constructor(language, rootDir = process.cwd()) {
+        this.language = language;
         this.cacheDir = path.join(getProjectDataDir(rootDir), "cache");
         this.cacheFile = path.join(this.cacheDir, `${language}-rules-${CACHE_VERSION}.json`);
     }
@@ -40,7 +53,8 @@ export class RuleCache {
             const currentHash = this.computeRuleHash(ruleFiles);
             const cached = readJsonCache(this.cacheFile, (parsed) => {
                 const entry = parsed;
-                if (entry.version !== CACHE_VERSION || entry.ruleHash !== currentHash) {
+                if (entry.version !== CACHE_VERSION ||
+                    entry.ruleHash !== currentHash) {
                     return undefined; // Cache invalid
                 }
                 return entry;
@@ -61,11 +75,38 @@ export class RuleCache {
                 queries,
             };
             fs.writeFileSync(this.cacheFile, JSON.stringify(entry, null, 2));
+            this.pruneStaleVersions();
         }
         catch {
             // Cache write failure is non-fatal
         }
     }
+    // Orphaned `<language>-rules-v<N>.json` files from a prior CACHE_VERSION
+    // (e.g. v3 entries left behind by the #448 v3→v4 bump) never got cleaned up
+    // on their own — nothing ever read or removed them again once the version
+    // bumped. Delete every sibling for this language that isn't the current file.
+    pruneStaleVersions() {
+        const currentName = path.basename(this.cacheFile);
+        const pattern = new RegExp(`^${this.language}-rules-v\\d+\\.json$`);
+        let dirents;
+        try {
+            dirents = fs.readdirSync(this.cacheDir);
+        }
+        catch {
+            return;
+        }
+        for (const name of dirents) {
+            if (name === currentName || !pattern.test(name))
+                continue;
+            try {
+                fs.unlinkSync(path.join(this.cacheDir, name));
+            }
+            catch {
+                // Best-effort; ENOENT (already gone) or any other removal failure
+                // shouldn't undo the write that already succeeded above.
+            }
+        }
+    }
     clear() {
         try {
             if (fs.existsSync(this.cacheFile)) {

package/dist/clients/cache-observability.js

@@ -0,0 +1,211 @@
+/**
+ * Prompt-cache observability (#1018).
+ *
+ * Two provider-independent signals, both sinking into ~/.pi-lens/latency.log
+ * via {@link logLatency} (matching the neighboring `type: "phase"` records):
+ *
+ *   1. Response-side cache usage (`cache_usage`) — on each assistant
+ *      `message_end`, record the provider-reported token/cost breakdown so a
+ *      session's actual cacheRead/cacheWrite behavior is queryable after the
+ *      fact. This is what the provider DID, not what we hoped it would do.
+ *
+ *   2. Request-side prefix stability (`cache_prefix_break`) — a content hash of
+ *      `messages[0]` observed on every `context` call. After #1016 the first
+ *      message must stay byte-stable across a whole session; a logged CHANGE
+ *      flags that something (pi-lens or otherwise) broke the cache prefix, which
+ *      would silently invalidate the entire prompt-cache on every prefix-caching
+ *      provider. Pure observation — it never alters context injection.
+ *
+ * Both paths are defensive: `usage` (and its fields) may be absent on older
+ * hosts or non-assistant messages, so every access is guarded and the handlers
+ * never throw — on error they `dbg(...)` and no-op, like the other index.ts
+ * event handlers.
+ */
+import { createHash } from "node:crypto";
+import { logLatency } from "./latency-logger.js";
+/**
+ * Part 1 — log one `cache_usage` record for an assistant `message_end` that
+ * carries a `usage`. Provider/model come straight off the message itself
+ * (`AssistantMessage.provider` / `.model` in pi-ai) — no dependency on the
+ * runtime telemetry identity. Skips silently (no record) when the message is
+ * not an assistant message or has no usage; never logs a zeros-only record for
+ * a message that simply lacks usage.
+ */
+export function logCacheUsage(message, dbg) {
+    try {
+        if (!message || typeof message !== "object")
+            return;
+        const msg = message;
+        // Only assistant messages carry LLM usage; tool-result / user messages
+        // (and unknown custom AgentMessage variants) are skipped.
+        if (msg.role !== "assistant")
+            return;
+        const usage = msg.usage;
+        if (!usage || typeof usage !== "object")
+            return;
+        const u = usage;
+        logLatency({
+            type: "phase",
+            filePath: "<pi-lens>",
+            phase: "cache_usage",
+            durationMs: 0,
+            metadata: {
+                provider: typeof msg.provider === "string" ? msg.provider : undefined,
+                model: typeof msg.model === "string" ? msg.model : undefined,
+                cacheRead: u.cacheRead,
+                cacheWrite: u.cacheWrite,
+                input: u.input,
+                output: u.output,
+                // `Usage.cost` is a breakdown object; the total is the headline number.
+                cost: u.cost?.total,
+            },
+        });
+    }
+    catch (err) {
+        dbg?.(`cache-usage: failed to log message_end usage: ${err}`);
+    }
+}
+/**
+ * Content hash of the first transcript message. Stable for identical content
+ * (role + content are serialized in a fixed order), so a changing hash means
+ * `messages[0]` actually changed byte-for-byte.
+ */
+function hashFirstMessage(first) {
+    const serialized = JSON.stringify({ role: first.role, content: first.content });
+    return createHash("sha256").update(serialized).digest("hex");
+}
+/**
+ * Per-session baseline hash of `messages[0]`, keyed by the STABLE pi session id
+ * (`ctx.sessionManager.getSessionId()`). A single module-scoped var was wrong:
+ * in ONE process, multiple logical conversations touch this module, and they
+ * must not share a baseline —
+ *   - new / fork / a concurrent in-process subagent (#473) is a DIFFERENT id →
+ *     its OWN independent baseline, never compared against another id's (else a
+ *     benign session boundary logs a spurious `cache_prefix_break`, and a
+ *     concurrent subagent + its parent stomp each other's baseline, each
+ *     emitting a false positive — fatal for a signal whose value is trust);
+ *   - an IN-PROCESS reload / resume reuses the SAME id → the baseline is still in
+ *     this map, so a genuine break is caught (no blinding reset). NOTE: a full
+ *     process restart (quit → `pi --session <id>`) starts a NEW process with an
+ *     empty map, so the first post-restart `context` re-anchors a fresh baseline
+ *     rather than comparing across the restart. That's acceptable here — this is a
+ *     pure observability signal (at worst a missed `cache_prefix_break` log on the
+ *     first post-restart turn, never a user-facing action) — unlike genuine
+ *     session state (read guard #1041, widget #190) which IS rehydrated from the
+ *     sidecar.
+ *
+ * Bounded as an insertion-ordered LRU (evict oldest-inserted past the cap) so a
+ * long-lived process cycling through many sessions can't grow this unbounded.
+ */
+const MAX_TRACKED_SESSIONS = 32;
+const prefixHashBySession = new Map();
+/**
+ * Bucket key used when no session id is available (undefined/empty). Degrades
+ * gracefully to the old single-var semantics — one shared baseline — rather than
+ * throwing or dropping the signal.
+ */
+const NO_SESSION_KEY = "<no-session>";
+/**
+ * Store `hash` for `key`, refreshing its LRU recency (re-insert moves it to the
+ * newest position since `Map` preserves insertion order) and evicting the
+ * oldest-inserted entries once the cap is exceeded.
+ */
+function recordSessionHash(key, hash) {
+    prefixHashBySession.delete(key);
+    prefixHashBySession.set(key, hash);
+    while (prefixHashBySession.size > MAX_TRACKED_SESSIONS) {
+        const oldest = prefixHashBySession.keys().next().value;
+        if (oldest === undefined)
+            break;
+        prefixHashBySession.delete(oldest);
+    }
+}
+/**
+ * Part 2 — observe `messages[0]` stability turn-over-turn, keyed by session id.
+ * Logs a baseline the first time it sees a non-empty transcript FOR A GIVEN
+ * session id, then logs a `cache_prefix_break` whenever that same session's
+ * first-message hash changes. Pure observation: it never inspects or mutates
+ * anything but its own per-session hash map, and never throws.
+ *
+ * `sessionId` should be pi's STABLE id (`ctx.sessionManager.getSessionId()`),
+ * which uniquely identifies the CURRENTLY-firing session: a concurrent
+ * in-process subagent runs its own `AgentSession`/`sessionManager`, so its
+ * `context` calls carry a DIFFERENT id than the parent's and get their own
+ * baseline. (`runtime.telemetrySessionId` cannot be used here: per the #473
+ * guard a concurrent secondary skips `updateRuntimeIdentityFromEvent`, so that
+ * process-global singleton stays pinned to the PARENT — it would collapse
+ * parent and subagent onto one baseline.) Residual limitation: if the host ever
+ * does NOT supply a stable id, all such sessions collapse onto `NO_SESSION_KEY`
+ * and behave like the old single-var (a concurrent subagent could then still
+ * cross-contaminate) — accepted as graceful degradation, not silently perfect.
+ *
+ * Does nothing on an empty transcript (nothing to anchor a prefix to yet).
+ */
+export function observeCachePrefix(messages, turnIndex, sessionId, sessionRole, dbg) {
+    try {
+        if (!messages || messages.length === 0)
+            return;
+        const first = messages[0];
+        if (!first || typeof first !== "object")
+            return;
+        const key = sessionId?.trim() ? sessionId.trim() : NO_SESSION_KEY;
+        const currentHash = hashFirstMessage(first);
+        const previousHash = prefixHashBySession.get(key);
+        if (previousHash === undefined) {
+            // Baseline: record this session's starting prefix so a later break has a
+            // reference point in the log. `previousHash: null` marks the baseline.
+            recordSessionHash(key, currentHash);
+            logLatency({
+                type: "phase",
+                filePath: "<pi-lens>",
+                phase: "cache_prefix_break",
+                durationMs: 0,
+                metadata: {
+                    turnIndex,
+                    previousHash: null,
+                    currentHash,
+                    baseline: true,
+                    sessionId: key,
+                    sessionRole,
+                },
+            });
+            return;
+        }
+        if (currentHash !== previousHash) {
+            logLatency({
+                type: "phase",
+                filePath: "<pi-lens>",
+                phase: "cache_prefix_break",
+                durationMs: 0,
+                metadata: {
+                    turnIndex,
+                    previousHash,
+                    currentHash,
+                    sessionId: key,
+                    sessionRole,
+                },
+            });
+        }
+        // Refresh recency (and update the stored hash after a break) so an active
+        // session stays warm in the LRU and isn't evicted while still in use.
+        recordSessionHash(key, currentHash);
+    }
+    catch (err) {
+        dbg?.(`cache-prefix: failed to observe messages[0]: ${err}`);
+    }
+}
+/**
+ * Drop a single session's prefix baseline. Called from the `session_shutdown`
+ * handler (primary path only — the concurrent-secondary guard there returns
+ * first, and the LRU cap backstops any secondary entry left behind) so an ended
+ * conversation's entry is reclaimed promptly rather than only when the LRU
+ * evicts it. Idempotent and never throws.
+ */
+export function clearCachePrefixSession(sessionId) {
+    const key = sessionId?.trim() ? sessionId.trim() : NO_SESSION_KEY;
+    prefixHashBySession.delete(key);
+}
+/** Clear all per-session prefix hashes. For tests / session boundaries. */
+export function resetCachePrefixObservation() {
+    prefixHashBySession.clear();
+}