pi-braid 0.42.0 → 0.43.0

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 (102) hide show
  1. package/CHANGELOG.md +1077 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
  6. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  7. package/dist/extensions/core/polyfill/index.js +34 -131
  8. package/dist/extensions/core/skills-tool/index.js +47 -26
  9. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  10. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  11. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  12. package/dist/extensions/enforcement/session-health.js +75 -5
  13. package/dist/extensions/enforcement/whisper.js +15 -1
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  18. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  19. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  20. package/dist/extensions/manifest.js +6 -0
  21. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  22. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  23. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  24. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  25. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  26. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  27. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  28. package/dist/extensions/self/path-miss/detect.d.ts +30 -0
  29. package/dist/extensions/self/path-miss/detect.js +67 -0
  30. package/dist/extensions/self/path-miss/index.d.ts +33 -0
  31. package/dist/extensions/self/path-miss/index.js +118 -0
  32. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  33. package/dist/extensions/self/watchdog/engine.js +25 -2
  34. package/dist/extensions/self/watchdog/index.js +14 -1
  35. package/dist/lib/ai/llm-call.js +23 -0
  36. package/dist/lib/ai/model-resolver.d.ts +11 -10
  37. package/dist/lib/ai/model-resolver.js +16 -19
  38. package/dist/lib/ai/presend-budget.d.ts +68 -0
  39. package/dist/lib/ai/presend-budget.js +83 -0
  40. package/dist/lib/config/braid-settings.d.ts +38 -0
  41. package/dist/lib/config/braid-settings.js +84 -0
  42. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  43. package/dist/lib/config/per-tool-settings.js +4 -4
  44. package/dist/lib/core/event-names.d.ts +1 -0
  45. package/dist/lib/core/event-names.js +1 -0
  46. package/dist/lib/detection/context-tiers.d.ts +18 -5
  47. package/dist/lib/detection/context-tiers.js +51 -33
  48. package/dist/lib/detection/context-usage.d.ts +62 -1
  49. package/dist/lib/detection/context-usage.js +158 -1
  50. package/dist/lib/errors/llm-error.d.ts +14 -0
  51. package/dist/lib/errors/llm-error.js +44 -1
  52. package/dist/lib/state/global-state.d.ts +4 -8
  53. package/dist/lib/state/global-state.js +11 -28
  54. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  55. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  56. package/dist/lib/utils/argument-report.d.ts +41 -0
  57. package/dist/lib/utils/argument-report.js +95 -0
  58. package/dist/lib/utils/wake-gate.d.ts +6 -0
  59. package/dist/lib/utils/wake-gate.js +52 -4
  60. package/docs/SETUP.md +7 -6
  61. package/package.json +11 -13
  62. package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
  63. package/src/extensions/core/polyfill/index.ts +29 -157
  64. package/src/extensions/core/skills-tool/index.ts +60 -37
  65. package/src/extensions/enforcement/AGENTS.md +38 -1
  66. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  67. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  68. package/src/extensions/enforcement/session-health.ts +94 -5
  69. package/src/extensions/enforcement/whisper.ts +15 -1
  70. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  71. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  72. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  73. package/src/extensions/manifest.ts +6 -0
  74. package/src/extensions/memory/AGENTS.md +37 -38
  75. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  76. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  77. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  78. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  79. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  80. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  81. package/src/extensions/self/AGENTS.md +2 -1
  82. package/src/extensions/self/path-miss/AGENTS.md +39 -0
  83. package/src/extensions/self/path-miss/detect.ts +78 -0
  84. package/src/extensions/self/path-miss/index.ts +135 -0
  85. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  86. package/src/extensions/self/watchdog/engine.ts +30 -2
  87. package/src/extensions/self/watchdog/index.ts +13 -1
  88. package/src/lib/ai/AGENTS.md +2 -0
  89. package/src/lib/ai/llm-call.ts +30 -0
  90. package/src/lib/ai/model-resolver.ts +16 -19
  91. package/src/lib/ai/presend-budget.ts +117 -0
  92. package/src/lib/config/braid-settings.ts +125 -0
  93. package/src/lib/config/per-tool-settings.ts +4 -4
  94. package/src/lib/core/event-names.ts +1 -0
  95. package/src/lib/detection/context-tiers.ts +52 -41
  96. package/src/lib/detection/context-usage.ts +211 -2
  97. package/src/lib/errors/llm-error.ts +55 -1
  98. package/src/lib/state/global-state.ts +11 -29
  99. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  100. package/src/lib/utils/AGENTS.md +1 -0
  101. package/src/lib/utils/argument-report.ts +105 -0
  102. package/src/lib/utils/wake-gate.ts +59 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,1077 @@
1
+ <!-- status: current -->
2
+
3
+ # Changelog
4
+
5
+ Curated release notes, newest first. This replaces the earlier auto-generated
6
+ per-commit dump (5.5k lines). The commit-by-commit record lives in git — the
7
+ public `main` is one consolidated commit since the 2026-10-12 consolidation;
8
+ the per-iteration series it replaces is archived locally (see "Repository
9
+ history" below). Milestones before the 2026-08-29 monorepo snapshot are
10
+ summarized below without per-commit references. Deep narrative history is in
11
+ [`packages/core/docs/HISTORY.md`](packages/core/docs/HISTORY.md).
12
+
13
+ Two tag roles, one namespace per package. The namespaces are enforced by
14
+ `packages/core/scripts/tag-prerelease.mjs` and `check-release.mjs`: core owns
15
+ the bare `v`, every sibling owns `<workspace>-v*`, so a tag names its package
16
+ and a tag on one line cannot block another.
17
+
18
+ - **Core** — legacy `v0.1.1 … v0.39.0`, then the `0.40.0` line: iteration tags
19
+ `v0.40.0-main.N` (package.json `0.40.0-main.N`), release tag `v0.40.0`
20
+ (package.json `0.40.0`). Ordering: `v0.39.0 < v0.40.0-main.1 < v0.40.0`.
21
+ - **Providers** — `1.0.x` line; iteration tags `providers-v1.0.x-main.N`,
22
+ release tag `providers-v1.0.x`.
23
+ - **Telegram** — `0.1.x` line; iteration tags `telegram-v0.1.x-main.N`,
24
+ release tag `telegram-v0.1.x`.
25
+ - **Skills** — `0.2.x` line; iteration tags `skills-v0.2.x-main.N`, release tag
26
+ `skills-v0.2.x`.
27
+ - **Contrib** — `0.1.x` line; iteration tags `contrib-v0.1.x-main.N`, release
28
+ tag `contrib-v0.1.x`.
29
+
30
+ Nothing is retagged retroactively. The legacy core names (`v0.1.4`, `v0.2.0` …)
31
+ stay core history and no longer occupy a sibling's release name: past a bare
32
+ `v`, the tag path reads only the package's own namespace.
33
+
34
+ ## Repository history
35
+
36
+ `main` carries a single consolidated commit as of the 2026-10-12 consolidation.
37
+ The per-iteration series it replaces (380 commits) is kept outside this
38
+ repository, in a local-only ref (`refs/archive/main-pre-squash`) plus an
39
+ all-refs bundle; a public clone has the consolidated commit only, so a checkout
40
+ that needs line history needs access to that local archive. This file and
41
+ [`packages/core/docs/HISTORY.md`](packages/core/docs/HISTORY.md) are the
42
+ reader-facing record; the tag scheme above applies unchanged.
43
+
44
+ ---
45
+
46
+ ## Core — 0.43.0 (2026-10-28: a long session stops killing itself, and the pages stop describing what is not there)
47
+
48
+ One release for everything after `0.42.1`. The versions between were base bumps: they were never tagged, so no reader
49
+ could install them, and their sections are folded here.
50
+
51
+ ### Core
52
+
53
+ - **The context meter measures what the provider counts.** It reported "the tokens that will be sent on the next
54
+ request" while computing a character walk at four characters per token over a partial span. A live session read 51%
55
+ while the wire carried 1,147,002 tokens against a 1,048,576 window, so the arm thresholds, the 0.90W backstop and the
56
+ emergency offload were all reading a number that could not reach them. The estimate now calibrates against the
57
+ provider's own usage (median of the last eight pairs, ratio clamped) and every rendered number carries its
58
+ provenance, `measured` or `estimated`. The measured error: 78.9% of the branch's mass outside the walk, 2.55
59
+ characters per token against the assumed 4.00, and 14 image blocks counted as zero.
60
+ - **A request that cannot fit is refused before it is sent.** `presend-budget` compares the calibrated payload plus the
61
+ requested output budget against the resolved window and refuses with one line naming the numbers, the window, the
62
+ overage and the remedy. It runs the chunked compaction once, re-measures, and only then allows the send. A
63
+ context-length 400 is classified as request-shape and is never retried as transient.
64
+ - **The compaction queue drains only where the loop cannot dispatch.** The `turn_end` drain and the arm-time fire are
65
+ gone; arming only queues, and `agent_settled` is the unconditional drain. Below the 0.90W backstop a queued steer at
66
+ a turn boundary started a request the armed drain then aborted, which the session reported as an API error. The
67
+ 0.90W backstop survives as the one deliberate exception, because a run kept alive by continuous steers never settles
68
+ and overflow costs more than the turn the deliberate abort can lose.
69
+ - **A self-started wake stops feeding a failing route.** A monotonic per-session counter of consecutive run-ending
70
+ provider errors is asked through the existing turn-start predicate; above the threshold, timer wakes, watchdog
71
+ escalations and waking whispers are demoted to non-waking delivery. The content still arrives and one line announces
72
+ the episode. Five existing signals re-open the gate, plus a floor sparser than the observed retry cadence.
73
+ - **One delivery prints one snapshot.** A heartbeat could print a configured tier boundary (`Context at 30%`) beside a
74
+ live measurement, and an agent then repeated the contradiction in its own reasoning. A delivery now carries a single
75
+ measurement taken at delivery, its label is that measurement, percentages carry the meter's provenance word, numbers
76
+ that change no decision are dropped, and a collapsed family is re-labelled from the newest arrival rather than the
77
+ first.
78
+ - **The publish step compares the artifact it served.** `pack-compare` unpacks the checkout's pack and the registry
79
+ tarball for the same version and reports what differs. The step reads the registry, never a rendering surface: its
80
+ first version inferred from the job's step summary and reported success while comparing nothing.
81
+ - **Gates report the population they actually scanned.** `check-placement` and `check-doc-links` skipped their own
82
+ file, so the first printed `1017 of 1018` and a worker transcribing that line into gate evidence was refused by the
83
+ merge rule. Both now count their own file and list it as a documented exclusion from matching, and a fixture asserts
84
+ the two numbers stay equal.
85
+
86
+ ### The package surface
87
+
88
+ - **The skills README describes the skills that ship.** It documented a 31-row catalogue while the package carries
89
+ eight, so most of the page described another package's files and one row described a skill that exists in no tree.
90
+ The page now has one row per shipped skill, taken from each `SKILL.md`'s own trigger, and it names which three carry
91
+ `status: deprecated` and where their successors live.
92
+ - **Descriptions say what a reader can do.** "Standalone", "markdown-only" and "no runtime dependencies" are true of
93
+ every package in the catalogue and useful to no reader; the private gateway no longer appears in published metadata.
94
+ Internal material left the public pages rather than being softened in place.
95
+ - **Every count on the surface is derived.** Where a README states a number, the report carries the command that
96
+ produced it.
97
+ - **Two skills could not fire, and now they can.** `adversarial-engagement` and `socratic-irony` carried trigger tails
98
+ of 222 and 212 characters against the trigger parser's 200-character cutoff, so both loaded with zero triggers.
99
+ Rewritten, they parse ten and six phrases, and a pack fixture fails on a description that cannot fire or on a tool
100
+ name no installed package declares.
101
+ - **`design-system` uses the CLI it had called aspirational.** `@google/design.md` is published; the skill had been
102
+ building a manual workaround around its supposed absence.
103
+
104
+ ### Removed
105
+
106
+ - **`/vision-model` and `/max-power-model` are removed.** Both shipped with a one-release warning and two have passed
107
+ since. Image analysis resolves through the current model when it accepts images, else the merged role's first
108
+ image-capable entry, and `model-resolver` no longer reads the vision key at all.
109
+
110
+ ### Also in this line
111
+
112
+ - **`SETUP.md` told readers the pi peers were unconstrained.** All five manifests carry `^1.2.0`; a wildcard accepts
113
+ any pi, a caret says which SDK surface the extension was written against.
114
+ - **A test fixture no longer hangs instead of reporting.** `fleet/test-drain-atomicity` attached its exit listener after
115
+ the kill, so a child that finished first left the promise unsettled and node exited 13 with every assertion green.
116
+
117
+ ## Core — 0.42.1 (2026-10-27: the package carries its changelog, a publish checks what it served, and two measured friction classes lose their cause)
118
+
119
+ ### Core
120
+
121
+ - **The changelog ships with the package.** `npm`'s `files` allowlist is package-relative and the repository keeps
122
+ one changelog at its root, above `packages/core`, so no allowlist entry could name it and an installed `pi-braid`
123
+ carried no changelog at all. A `prepack` step now stages that file at the package root and a `postpack` step removes
124
+ it, so the artifact carries the released tree's own notes rather than a second copy that can drift. The staged path
125
+ is gitignored, so an interrupted pack cannot leave a checkout reading as dirty, and the bytes in the tarball are the
126
+ bytes of the root file.
127
+ - **A publish now compares what it served.** `pack-compare.mjs` unpacks two tarballs, normalises the one field that
128
+ cannot be reproducible (`build-info.json`'s `packedAt`) and reports what else differs, with three exit codes so
129
+ "equal", "different" and "could not read" stay distinguishable. `publish.yml` runs it after the publish and after
130
+ the release entry, tag runs only, and **warns** rather than fails: a byte comparison would be permanently red here
131
+ (two packs of one tree differ in hash and size), while the content comparison is exact. The step becomes blocking
132
+ when it has a record of being right on this repository.
133
+ - **The provenance writer must be last.** A lifecycle step of the package's own (the changelog staging above) may now
134
+ run before the writer, and the checker identifies the writer by the script that reaches the shared generator rather
135
+ than by whichever `node` script the body runs first. A body that still leaves a command after the writer is refused,
136
+ because anything after it can mutate the record it computed.
137
+ - **A missed path names the cheaper instrument.** One steer line per turn, in the whisper family that already
138
+ carries error bursts, when a tool result shows the path did not exist: it names the path and the instrument that
139
+ would have found it (`ls`, `find`, `explore_paths`). Measured before this change: missing-path failures were the
140
+ largest single tool class in this machine's transcripts, two thirds of them in sessions that never listed a tree.
141
+ - **Two schemas stop making the model guess.** `list_skills` treats a paging-only call as `action: "list"` instead of
142
+ failing, and argument validation now names the values it would have accepted (the `think` tool's enum and its
143
+ required `decision` field were the two most frequent victims) instead of only saying validation failed.
144
+
145
+ ### Also in this line
146
+
147
+ - **The session scanner can name its window.** `session-scan.mjs` gained `--since <ISO>`, filtering on each session's
148
+ own recorded start rather than the file's modification time, and every report now prints the cutoff it applied. A
149
+ resumed session's mtime moves while its first prompt does not, which is why a release-window measurement could not
150
+ be re-cut to the same population before this.
151
+
152
+ ## Core — 0.42.0 (2026-10-25: the skills catalog is in the prompt, and work that moves re-points it)
153
+
154
+ ### Core
155
+
156
+ - **The skills catalog is rendered in the prompt** - the `skills-loading` section
157
+ now lists every visible skill as one `- name: description` row, with the read
158
+ path derived from the skills' own file paths, so a domain match is in front of
159
+ the model instead of behind a tool call it has to decide to make. A thin
160
+ opening prompt carries no domain vocabulary for the keyword scorer, and the
161
+ measured consequence on the class of sessions those prompts open is a skill
162
+ load rate of zero. The section measures 8,903 bytes / 2,226 estimated tokens on
163
+ this repository's 22-skill pack at this repository's own 58-character skills
164
+ path, and 11,366 bytes / 2,842 tokens on a live 27-skill two-pack catalog (a
165
+ 55-character install path plus the user-global skills directory), against 756
166
+ bytes / 189 tokens before it: braid suppresses pi's own catalog, so the floor is
167
+ an addition of 8,147 to 10,610 bytes on every request rather than a swap. Both
168
+ are renders, not constants. The section states the catalog's own read root, so
169
+ the byte count follows that root one byte per character — the 55-character
170
+ install path renders 8,900, a 66-character local-packages path 8,911, and a
171
+ path 43 characters longer renders 43 bytes longer — and the worked examples it
172
+ derives from the active tool set move it too: a different tool representing a
173
+ family the section already illustrates is a byte (8,902 with `herdr_agent`
174
+ where this render names `herdr_layout`), and a family joining or leaving the
175
+ active set is a whole example.
176
+ - **Work that moves re-points the catalog** - a drift trigger in the `tool_result`
177
+ handler fires one steer line when the session's own read/edit/write calls
178
+ accumulate entries in a new work area, so a catalog rendered against one
179
+ directory re-points at itself when the work moves. Its bounds (two entries,
180
+ twelve calls between fires, three per session, quiet for the same window after
181
+ a skill surface) sit beside the text they point at.
182
+ - **The floor has an instrument** - `packages/core/test/runtime/core/session-scan.mjs`
183
+ scans session transcripts and reports the thin-prompt read rate, drift latency,
184
+ and the bytes of skill surface injected per session; the floor text, the drift
185
+ sequence, the instrument and its twin labelled cases are each pinned by a test.
186
+
187
+ ## Core — 0.41.2 (2026-10-25: the runtime floor is Node 24, and a red file prints its own output)
188
+
189
+ ### Core
190
+
191
+ - **The declared runtime floor is Node 24** - `engines` promised `>=22.19.0` in
192
+ all six manifests while the release ran on the 24 line, so the gate that
193
+ reports red and the gate that decides a release were never the same runtime.
194
+ The floor is `>=24.0.0` in the six manifests, the `ci.yml` matrix runs the line
195
+ `publish.yml` uses, and three requirement tables, two sentences of the telegram
196
+ README and one comment in its client follow it. `node:sqlite` says it is
197
+ experimental, once per process at import, on every 24 release before 24.15, so
198
+ on the floor `fleet status` answered correctly and still wrote a warning nobody
199
+ documented: `journal.mjs` withholds that one warning for the length of its
200
+ import, and is now the fleet's only importer of the module. The CI job's
201
+ timeout goes from 15 to 30 minutes, the allowance the release path already
202
+ gives the same chain.
203
+ - **A failing test file prints its own output** - the runner named a red file and
204
+ its totals and dropped the assertion text with the child's streams, so reading
205
+ a red run meant repeating it, through a container on CI. A failing or timed-out
206
+ file now prints the end of its own output under its line, bounded to 40 lines
207
+ and 4,000 characters, with the number of lines it left out and the command that
208
+ prints the rest.
209
+
210
+ ## Core — 0.41.1 (2026-10-25: delivery by the queue section, a lease column nothing reads, a store version)
211
+
212
+ ### Core
213
+
214
+ - **A queued message is retired only by the section that carried it** - the
215
+ carrier tested the body anywhere in the prompt, so a charter that repeated the
216
+ instruction word for word was read as a delivery even with the queue section
217
+ dropped. Each prompt builder now returns the section it appended together with
218
+ that section's ids, and the carrier checks the section's own sentence and each
219
+ message's line against the prompt. A turn kind that appends nothing carries
220
+ nothing, and the same plant leaves the row `recorded` with no delivery columns.
221
+ - **The lease keeps `expires_at`, and no code reads it** - `liveLease` filtered on
222
+ state alone, so a lease a minute past its expiry still kept a second supervisor
223
+ off the node. Making the column authoritative would hand one node to two
224
+ drivers, since a legitimate tick ran 32.7s under write contention against the
225
+ 30s the column is written with. It stays nullable and unwritten because the
226
+ schema-1 build names it in its lease INSERT, so dropping it would leave every
227
+ store this build writes unopenable by a rollback.
228
+ - **The store records the shape it has and refuses a newer one** - a store
229
+ carrying a schema version above this build's is refused with one sentence,
230
+ rather than opened and failing inside a statement.
231
+ - **A deferral is recorded beside the store** - a maintenance pass that met the
232
+ write lock deferred in memory only, the tick then threw `database is locked`
233
+ from the sweep after it, and an overdue ask stayed open with nothing an operator
234
+ could read. Both passes now share a bounded wait and record the deferral in
235
+ `store-deferred.json`, the one place writable while the journal is not; the
236
+ first pass that gets through copies it into the journal and removes the file,
237
+ and `status` prints the deferral it can read and exits non-zero on a store it
238
+ cannot open, so the reason the fleet is idle survives the state that produced
239
+ it.
240
+
241
+ ## Core — 0.41.0 / Telegram — 0.1.6 (2026-10-24: the supervisor fleet ships)
242
+
243
+ ### Core
244
+
245
+ - **The fleet ships as a command** - `packages/core/scripts/fleet` was in the
246
+ repository and in no tarball: the manifest's allowlist stopped at `dist`,
247
+ `src`, `docs`, `skills` and four top-level files, so the supervisor and its
248
+ four operator commands existed only in a checkout. The allowlist now names
249
+ `scripts/fleet/**`, and a `bin` entry puts them on PATH as `pi-braid-fleet`,
250
+ named for the package because a bare `fleet` can be shadowed by unrelated
251
+ tooling. That entry exposed an entry-point test that could only be true in a
252
+ checkout: npm links a bin as a symlink, so `process.argv[1]` keeps the link's
253
+ spelling while `import.meta.url` names its target, which had made an installed
254
+ command load, match nothing and exit 0 in silence. The guide is
255
+ `packages/core/docs/FLEET.md`.
256
+ - **The duplicated-effect guard refuses before the call runs** - a tool call whose
257
+ effect may already have applied is refused, within the run being resumed; a
258
+ queued message is consumed only when a turn's prompt carried it; and tier A is
259
+ written only from a driver's own delivery event rather than guessed at, so a
260
+ steer that was not delivered leaves its message to the next turn.
261
+ - **The control channel and the asks** - the control channel keeps its ownership
262
+ straight in and out, an expired ask is claimed and its default queued in one
263
+ transaction, a live owner keeps its turn, and an idle supervisor leaves.
264
+ - **A drain waits out the store lock instead of throwing** - the journal installs
265
+ its busy handler before anything that can block, and the drain records what it
266
+ did when it gets through.
267
+ - **Packaging is held to a real artifact** - `test-pack-ships.mjs` packs the
268
+ manifest through `npm pack`, reads the tarball's file list, extracts it outside
269
+ the repository, and drives the four commands and a supervisor start from there.
270
+
271
+ ### Telegram
272
+
273
+ - **The owner's reply reaches the envelope** - `IncomingOwnerMessage` carries an
274
+ optional `replyTo`: the replied message id, whether that message was ours or the
275
+ owner's, and a one-line excerpt capped at 120 characters, read once from the
276
+ update the poller already holds and inherited by every delivery variant (plain
277
+ text, photo, voice, document, and text+document). The envelope renders it
278
+ directly under the sender line, as prose the agent can quote back rather than a
279
+ field to parse, and the excerpt comes from `reply_to_message` itself rather than
280
+ a `getMessage` round trip, so the receive path gains no new failure mode. A
281
+ missing or malformed reply field degrades the reference and leaves the delivery
282
+ untouched.
283
+
284
+ ## Core — 0.40.6 (2026-10-23: version truth, post-compaction resume, the journal, fleet v0, self-tooling fixes)
285
+
286
+ ### Core
287
+
288
+ - **The instance line names the running pi-core** - it read `pi-core vunknown` on
289
+ every session: the version came from a filesystem walk that resolves the running
290
+ entrypoint and searches its ancestors, and the managed install keeps that
291
+ entrypoint as a plain shell shim in `bin/` with the package in a sibling
292
+ `install/releases/<version>/node_modules` subtree, so the walk always
293
+ exhausted. It now reads the `VERSION` export, which names the library braid is
294
+ loaded into; the walk still supplies the binary, the package folder, and a
295
+ fallback version when the export is absent. The same pass re-derives the
296
+ extension-API guard's frozen surface from the installed declarations (seven
297
+ members it lacked) and removes a fabricated `ExtensionContext` augmentation
298
+ that declared members existing in neither version, inviting calls that would
299
+ compile and do nothing.
300
+ - **The journal** - an append-only record a replacement seat can act on. The
301
+ writer owns the sequence number, assigned under the scratchpad's cross-process
302
+ store lock, the write time and the provenance, and refuses a decision without
303
+ its reason, a constraint without an expiry, or an evidence list that is empty
304
+ and not flagged unverified; supersession appends, leaving the earlier line
305
+ byte-identical. A separate checker with its own parser fails per structural
306
+ defect, and with `STALE` when a task was closed with no entry for it. The path
307
+ is derived once, so the writer, the checker and the session-start pointer
308
+ cannot name different files.
309
+ - **Deferred compaction obeys one turn-boundary rule** - the rule that decides
310
+ whether a deferred `ctx.compact()` may abort a run at a turn end existed twice,
311
+ as a local predicate and as an inline copy, and both read a missing stop reason
312
+ as loop-done. It moves to `lib/events/turn-boundary.ts`, an allow-list over
313
+ `stopReason`; an unreadable or unrecognized boundary parks, and a caller holding
314
+ no boundary keeps the prior contract. The heartbeat's hand-off into the arm path
315
+ had no witness (deleting the argument left the suite green), so a fixture now
316
+ drives the real scheduler handler and reddens on exactly that deletion.
317
+ - **The post-compaction resume** - `resume.json` is filled from the scratchpad
318
+ checkpoint log, and the resume wake stays above the whisper cap that had been
319
+ swallowing it.
320
+ - **Fleet v0** - a journal-backed supervisor with four commands and a crash drill
321
+ that measures duplication, in `packages/core/scripts/fleet`.
322
+ - **The presend guard joins by normalized id and can cap request bytes** - the
323
+ guard looked a request's model id up under the catalog's own spelling, so a
324
+ route sending `deepseek-v4.1-flash` against a catalog id `deepseek-v4-1-flash`
325
+ resolved to no window, and the arm that exists to stop a doomed send never ran
326
+ for that model. The index answers exact ids first and a lowercased dash-form key
327
+ second, dropping a normalized key that two catalog models would answer
328
+ differently with. A declared `maxRequestBytes` adds a byte arm over the
329
+ serialized payload, and one warn line per request above `reportBytesAbove`
330
+ carries the byte count, the model id and whether a cap exists.
331
+ - **One compact instance line** - the line repeated the working directory pi
332
+ injects natively as `<cwd>` and had lost the fields that made older blocks
333
+ useful. It carries the loaded braid install root, the session model and
334
+ provider, the PID, the session id and true skill and memory counts under a
335
+ 320-byte cap. The rule is written at the renderer and pinned by fixtures: the
336
+ system prompt is a cached prefix, so only process-stable facts belong there, and
337
+ the volatile statistics stay in the `system_info` tool.
338
+ - **Three self-tooling reports that were untrue** - the heartbeat's verification
339
+ counter recognised tool names, so a session whose investigation ran through
340
+ `bash` probes counted as zero; the orchestrator's population-stamp parser
341
+ accepted one lowercase word as a unit, so a real stamp read as unreadable and a
342
+ merge ran with no recorded population; and the turn-end hygiene latch re-armed
343
+ against a 50% bar while the arm that fired was 45%, so one whisper re-injected
344
+ on every turn and the percent ladder never rendered from 45% upward.
345
+ - **Reach before the read** - `list_skills` rows carry the price of the read they
346
+ name (lines, bytes, chars, estimated tokens, the file's headings with line
347
+ numbers, and the section count). The heading parse is fence-aware, because 45
348
+ of the pack's 293 heading-shaped lines sit inside code blocks, and measurements
349
+ are memoized on mtime and size, with read failures left uncached.
350
+ - **A local voice path, measured** - `scripts/voice-spike/` holds the recorder,
351
+ the resident synthesiser and the batch harness that time the speech path end to
352
+ end on this machine: native throughout (`whisper.cpp`, AudioQueue), because
353
+ neither torch nor onnxruntime installs on Intel macOS.
354
+
355
+ ## Core — 0.40.5 (2026-10-20: package discovery metadata)
356
+
357
+ ### Core
358
+
359
+ - **The published manifest carries the discovery keyword** - `pi-coding-agent` is
360
+ what npm-driven package directories index on. It had been added to the repo root
361
+ manifest, which is private and never publishes, so the shipped `pi-braid` package
362
+ carried `pi-package` but not this one while all four sibling packages carried both.
363
+ The keyword now lives in `packages/core/package.json`, the manifest the registry
364
+ receives. No code, no behavior, no API change.
365
+
366
+ ## Core — 0.40.3 / Contrib — 0.1.2 (2026-10-20: blank tool inputs, npm: entry resolution)
367
+
368
+ Two packages moved since the 0.40.2 train. Skills, providers and telegram are
369
+ unchanged, and the publish workflow skips them as already on the registry.
370
+
371
+ ### Core
372
+
373
+ - **npm-pinned extensions are discovered again** - `discoverTopLevelExtensions`
374
+ resolved `npm:` specs only inside the managed install tree of the pi runtime,
375
+ so a workspace whose extensions are pinned by `npm:` name (the supported
376
+ install path) resolved nothing and braid reported no top-level extensions at
377
+ all. The managed root is now searched ahead of the global root and the global
378
+ root is kept as the fallback; a live probe went from 0 discovered to 9 against
379
+ real settings.
380
+ - **Blank tool inputs are read as absent, and blank required inputs are refused
381
+ by name** - a client that emits every schema key sends `""` for the unused
382
+ ones. In eight tools that blank was consumed as a value: a blank `limit` and a
383
+ blank `minAge` converted to `0` and disabled the cap they were meant to apply,
384
+ a blank `tag` was stored and rendered as an empty group, a blank `claimId`
385
+ became the tracking key for the rest of the session, a blank `summary` recorded
386
+ an unfindable task as done, a blank `output` answered "no topic drift" for a
387
+ check that never ran, blank `explore_paths` hypotheses produced an empty report
388
+ instead of a usable error. Optional selectors now fall back to their documented
389
+ defaults and required ones are refused with the parameter named.
390
+ - **Schema pointers and source contracts stop binding to line numbers** - the
391
+ schema generator resolved each row's evidence on one exact line, so any edit
392
+ above that line failed the build for a key that had not changed; three rows had
393
+ already drifted and `release:check` was blocked behind them. The named line is
394
+ tried first and the file is searched after it, the evidence must still live in
395
+ the named file, and the published `x-source` names the line it was found on.
396
+ The browser screenshot contract asserted a constant that had moved into the
397
+ shared resolver, and its replacement form was satisfied by the import line
398
+ alone; it now asserts the delegation, the resolver's fallback expression and
399
+ the shipped default.
400
+ - **Ecosystem crawlers can find the package** - the root manifest carries the
401
+ `pi-coding-agent` keyword the sibling packages already carried, which is what
402
+ the `pi-package` directory source indexes on.
403
+
404
+ ### Contrib
405
+
406
+ - **Blank tool inputs across the contrib modules** - the browser tools, the
407
+ codebase and diff tools and the healthcheck tool read a blank selector as a
408
+ value, so an empty `query`, an empty path or an empty quality reached the
409
+ implementation; each now resolves through one shared input reader that treats
410
+ a blank field as absent. JPEG capture quality continues to default to 75.
411
+
412
+ ## Core — 0.40.2 / Telegram — 0.1.5 / Providers — 1.0.6 / Contrib — 0.1.1 (2026-10-17: orchestrator close gates, npm-first docs, multi-client tunnels)
413
+
414
+ The four packages whose shipped content moved since the 0.40.1 train.
415
+ `pi-braid-skills` 0.2.2 is the first single-package release of the npm
416
+ trusted-publishing path, sequenced separately from this train (its own section
417
+ below); its outcome decides whether this section is ever tagged.
418
+
419
+ ### Core
420
+
421
+ - **The release path is the publish workflow** - `CONTRIBUTING.md` step 5 and
422
+ the `release-pipeline` skill name the tag that releases: `npm install` at the
423
+ root after the manifest bumps, `npm run ci:check` before the tag, an annotated
424
+ `v<core version>` published by `.github/workflows/publish.yml` through npm
425
+ trusted publishing (OIDC, no token in any repository file), and the iteration
426
+ tags (`v<version>-main.N`, `<workspace>-v<version>`) that never publish.
427
+ - **Orchestrator close gates** - a close's `files` row that carries a
428
+ population stamp is read against the tree at the revision the stamp names,
429
+ and a count below that revision's tracked-entry census refuses the merge
430
+ before any ref moves; a recorded production write is refused unless the same
431
+ close records every preflight piece its class names; every gate row is read
432
+ for well-formedness at close, in shadow mode by default under the new
433
+ `braid.orchestrator.closeGateWellFormedness` setting. The tool surface prints
434
+ the population comparison beside the outcome line.
435
+ - **Provenance in the tarball** - `prepack`/`postpack` write `build-info.json`
436
+ (package name, packed version, commit sha and branch, dirty flag, pack time)
437
+ into every artifact and remove it afterwards, and each manifest's `files`
438
+ allowlist ships it. `packages/core/docs/LOCAL_DEV.md` states the reading rule: `sha` plus
439
+ `dirty == false` is what says a tarball is a clean checkout of a named
440
+ commit.
441
+ - **Peer ranges state the pi floor** - the manifests carry `^1.2.0` for the
442
+ `@earendil-works/*` peers and `^1.1.38` for `typebox` instead of `*`, and the
443
+ update pipeline rewrites those ranges alongside the exact pins, so the floor
444
+ moves with the runtime instead of drifting behind it.
445
+ - **Docs** - `CONTRIBUTING.md` leads with `pi install npm:pi-braid` (one
446
+ command, no clone, no build) before the contributor flow; cross-package links
447
+ label their target by repository path; the README badge states the peer rule
448
+ instead of a stale minimum; the `TOOLS.md` document rewrites its enablement
449
+ reference, adds a Command catalog of extension slash commands, and gains a
450
+ `network-monitor` row naming `braid.contrib.networkMonitor`; `ROADMAP.md`
451
+ records the per-package tag namespaces and the `tunnel-control` verdict.
452
+
453
+ ### Telegram
454
+
455
+ - **HTML parse mode auto-selects only on a tag Telegram parses** -
456
+ `hasHtmlTags` now requires a well-formed tag whose name is in Telegram's tag
457
+ set, so a body carrying `<n>` or `<b/>` goes out as plain text, where those
458
+ characters reach the reader literally, instead of selecting HTML and being
459
+ refused whole as an unsupported start tag.
460
+ - **Docs and manifest** - the README leads with the `pi install` one-liner, and
461
+ the manifest carries the provenance pair and the peer ranges above.
462
+
463
+ ### Providers
464
+
465
+ - **README and manifest only** - no source file changed in this release: the
466
+ delta is the README's `pi install npm:pi-braid-providers` one-liner and the
467
+ manifest's version, peer ranges (`*` to `^1.2.0`), provenance pair and
468
+ `build-info.json` entry. The release spends a version number on prose and
469
+ manifest metadata rather than on source.
470
+
471
+ ### Contrib
472
+
473
+ - **`network-monitor` speaks two clients** - the v2RayTun-only probe becomes a
474
+ client-adapter split (`clients.ts`, `tunnel.ts`), so the watcher reconnects
475
+ v2RayTun over app deep links and Happ over its network-extension profile
476
+ (`scutil --nc stop|start`); `outageThreshold` (default three consecutive
477
+ failed probes) keeps one failed probe from toggling the tunnel, and the
478
+ `braid.contrib.networkMonitor` block is re-read while the extension runs.
479
+ - **The per-module off switch holds on both loading paths** - the new shipped
480
+ `module-toggle.ts` reads `braid.contrib.<name>` inside each extension's own
481
+ factory, because pi loads the `pi.extensions` entries directly and never runs
482
+ the bundle; only a literal `false` disables, and an absent key or an
483
+ unreadable settings file reads as enabled.
484
+ - **Docs and manifest** - the README's module table names the second client and
485
+ its settings table gains the `networkMonitor` row and the literal-`false`
486
+ rule; the manifest carries the provenance pair and the peer ranges above.
487
+
488
+ ## Skills — 0.2.2 (2026-10-17: pack provenance and README repairs)
489
+
490
+ - **Provenance in the tarball** — `prepack`/`postpack` write `build-info.json` (name, version, full and short commit sha, branch, dirty flag, pack time) into the pack and remove it after, and the manifest's `files` list ships it, so a packed `pi-braid-skills` names the commit it was packed from.
491
+ - **Cross-package README paths** — the prose that says where sibling skills live labels them by their repository path (`packages/core/skills/…`), the form the link rows and the other READMEs already use, instead of the checkout-relative `../core/skills/…`.
492
+ - **`v2raytun-reconnect` becomes `tunnel-control`** — the skill gains its second and third clients (Happ, Incy; the v2RayTun arm is validated, the other two refuse until validated), and the README row carries the new name, the three-client description and the `KEEP` verdict.
493
+
494
+ ## Core — 0.40.1 / Providers — 1.0.5 / Skills — 0.2.1 (2026-10-15: gallery metadata repairs)
495
+
496
+ - **Core README badge** — the pi-coding-agent minimum states `1.2.0` (the current pi line), not the stale `0.85`.
497
+ - **Cross-package README links** — links that left their own package in the `pi-braid` and `pi-braid-skills` READMEs now point at the repository on GitHub, so they resolve on the package gallery instead of breaking or landing on unrelated content.
498
+ - **Providers manifest** — `pi-braid-providers` declares an `exports` entry, matching its sibling packages.
499
+ - **Release date** — the first-public-release heading below carries the true publication date, 2026-10-15.
500
+
501
+ ## Core — 0.40.0 / Telegram — 0.1.4 / Providers — 1.0.4 / Skills — 0.2.0 / Contrib — 0.1.0 (2026-10-15: first public release)
502
+
503
+ The first npm publication: all five packages go out together at the versions
504
+ above.
505
+
506
+ ### Core
507
+
508
+ - **Prerelease tags come from the derivation, and a check guards the pair** —
509
+ `packages/core/scripts/tag-prerelease.mjs` writes the annotated
510
+ `v<derived version>` tag at HEAD, refusing a detached HEAD, a dirty tree, an
511
+ existing tag, a name that is not a version, and a version that does not sort
512
+ strictly above the highest existing `v*` tag. The derivation moves to
513
+ `packages/core/scripts/lib/version-derivation.mjs`, which the publish path
514
+ imports, so a tarball and its tag cannot disagree about the version they
515
+ name; `release:check` joins `ci:check` and validates the tag against
516
+ `package.json` (annotated, agreeing, ordered per semver.org 2.0.0, build
517
+ metadata ignored). The core base moves to `0.40.0`, above the last released
518
+ tag, and the tag scheme is the one recorded at the top of this file.
519
+ - **Vision and document tools offloaded to installed packages** — the contrib
520
+ `vision` extension (`analyze_image`) and `read-document` extension
521
+ (`read_document`, `render_pdf_page`) are removed. Image and document
522
+ capabilities come from the installed `@getpipher/vision` (`describe_image`)
523
+ and `pi-docparser` (`document_parse`, `document_search`,
524
+ `document_screenshot`) instead. Every internal reference — the path-security
525
+ read allowlist, the enforcement investigation/routing/probe sets, SOP
526
+ extraction, the task-boundary signal, heartbeat verification sets, browser
527
+ guidance, tool profiles, and the docs — points at the replacement names, and
528
+ the now-unused `pdf-parse` dependency is dropped.
529
+ - **Role merge: maxPowerModel folds into utilityModel** — one key, one
530
+ resolver, one auxiliary tier per chain. Every caller chain drops the
531
+ duplicate tier: verify/hypothesize/think try the merged role first, the
532
+ judges and claim extraction keep it as the cheap first tier, and
533
+ `judge-budget` walks session → utility. The classifier's four
534
+ `modelPreference` values collapse to two orders: `quality` (session first)
535
+ and everything else (role first); `max` and `speed` stay accepted but now
536
+ equal `balanced`. The `"max-power"` tier label leaves
537
+ `ClassificationResult` and critic stats.
538
+ - **maxPowerModel deprecated alias** — a settings file that only carries the
539
+ legacy key still loads it under `utilityModel` for one release, with a
540
+ once-per-process notice; the first role write removes the legacy key in the
541
+ same settings transaction, and `/max-power-model` set/show/clear operate on
542
+ the canonical key.
543
+ - **visionModel deprecated alias** — `resolveVisionModel` keeps its name and
544
+ the legacy key keeps priority for one release. Without it the chain is the
545
+ session model when image-capable → the merged role's first image-capable,
546
+ route-usable entry → the first available image-capable model. The
547
+ `/vision-model` command warns on use and is removed next release.
548
+
549
+ - **pi 1.2.0 across the family** — the pinned `@earendil-works/pi-agent-core`,
550
+ `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` family moves
551
+ to `1.2.0` in the root manifest and the providers package. The
552
+ whisper-delivery branch test re-points its third-branch stub at 1.2.0's
553
+ run-start entry and asserts that entry exists on the prototype before
554
+ stubbing it, so the next rename is a named failure in the fixture instead
555
+ of a stack trace from inside pi-core (`8dd7fd82`, `c6d40853`).
556
+ - **Runtime state resolves through the braid root at call time** — every
557
+ writer that folded `os.homedir()` into a module-load constant now resolves
558
+ `BRAID_HOME` (else `<home>/.pi/agent/braid`) per call, so a pin set after
559
+ import is honoured; a relative or blank `HOME`/`BRAID_HOME` is refused
560
+ with the offending variable named instead of creating state inside the
561
+ current project. The write-decision log, episode, scratchpad, semantic,
562
+ orchestrator lock and worker registries, checkpoints, error log, evidence
563
+ pool, degradation state, analytics metrics, hints, workspace snapshots and
564
+ skills-adoption stores all follow; the adherence, telemetry, tags and
565
+ sessions sinks move under the root; the heartbeat report compares
566
+ realpaths for its entry guard; the error-tracking listener drains its
567
+ refused store at warn instead of surfacing an unhandled rejection; and
568
+ readers that can miss (the error list, the semantic load, the adoption
569
+ rollup) degrade instead of throwing (`5bbdb77f`, `eead4ff3`, `30bcb697`,
570
+ `45066f58`).
571
+ - **Module toggles persist in braid's store** — a toggle writes
572
+ `braid.modules` to `braidDir()/projects/<project>/module-overrides.json`
573
+ (temp-file-plus-rename, siblings preserved) instead of creating
574
+ `<cwd>/.pi/settings.json` in a stranger's repository. Reads merge pi's
575
+ agent-directory settings file with braid's store, later wins per key; the
576
+ project-scoped `braid.modules` block is no longer a source, because it is
577
+ pi's file behind pi's project-trust gate and that answer is not available
578
+ while extensions load (`5bbdb77f`, `eead4ff3`).
579
+ - **State paths are held by checks, not convention** — a new
580
+ `check-write-scope` scan fails the chain on a production write whose
581
+ target can resolve into the cwd unless the call carries a reasoned
582
+ allowlist entry; containment children drive each package's real writers
583
+ under a pinned `BRAID_HOME` and assert the project tree and the default
584
+ HOME tree stay untouched; and the four copies of the braid-root rule
585
+ (core, telegram, providers, contrib) are compared shape by shape, so one
586
+ package's guard cannot drift from the others (`e91ca9d6`, `f14cb5ef`,
587
+ `f029fb35`).
588
+ - **Rotation size notice lands at the turn-end flush** — while a run is
589
+ streaming the notice is sent as a park-class steer, so it is delivered at
590
+ the same turn end instead of queuing on the one-message-per-run-stop lane
591
+ (median delivery latency on the session corpus was about 12 minutes, and
592
+ most notices landed after the agent had already acted on them). An
593
+ unresolved-advisory registry, retired by the message append events, keeps
594
+ a second notice of the same kind from stacking, with a 30-minute TTL for a
595
+ lost event and a clean map at session shutdown; the notice body states the
596
+ age rule, so a header stamp older than the last `context_compress` or
597
+ `finalize` reads as already satisfied (`5038b448`).
598
+ - **Once-per-session whisper slot claimed before the first await** — the
599
+ guard was read before an awaited delivery batch and written after it, so
600
+ two overlapping prompt builds both delivered every once-per-session
601
+ whisper and a session start could see the hygiene line twice; the slot is
602
+ now claimed synchronously at block entry (`26fd5e0f`).
603
+ - **Doc references and instruction strings are derived, then repaired** —
604
+ `check-doc-drift` derives its subject set from the docs' inline code spans
605
+ and resolves every strong identifier against the source, with a
606
+ `doc-ref-exempt` annotation for deliberate mentions and recorded host and
607
+ package names; a new `check-instruction-strings` walk of emitted string
608
+ units fails on a tool name that is not registered, an action outside its
609
+ tool's enum, or an action quoted for a tool with no action parameter. Both
610
+ run inside `ci:check` and print their counts. The pre-existing findings
611
+ were recorded as baselines (seven doc-reference rows, eleven instruction
612
+ rows) and then repaired: the tool descriptions name
613
+ `context_compress(action=archive)` and `context_navigate(action=...)`
614
+ instead of the retired names, and the docs point at the live `signals.ts`
615
+ exports, the `tool_call` event, `ClassificationResult`,
616
+ `setGlobalLogLevel` and `typeRoots` (`195a8c89`, `199883e0`).
617
+
618
+ ### Telegram
619
+
620
+ - **MarkdownV2 emphasis converts to HTML, one entity per pair** — a body
621
+ carrying `**bold**`, `__underline__`, `~strikethrough~` or `||spoiler||`
622
+ under `parse_mode: "Markdown"` shipped its markers literal, because the
623
+ guard checked delimiter balance rather than dialect; the delivery format
624
+ now rewrites balanced pairs to `<b>`, `<u>`, `<s>`, `<tg-spoiler>` and
625
+ `<code>`, escapes HTML-reserved characters outside author markup and code
626
+ spans, and reports a per-kind conversion count. A `__x__` pair emits `<u>`
627
+ (it used to emit `<i>`, which no MarkdownV2 pair means); unbalanced or
628
+ identifier-like markers stay literal; the parse_mode schema and tool
629
+ descriptions name the legacy dialect and point at HTML; and an over-cap
630
+ render splits to fit instead of failing at the API (`7e649f5c`,
631
+ `22fe46e6`).
632
+ - **State root** — media and pause state move from pi's agent directory to
633
+ `braidDir()/telegram`, with a read fallback to the pre-move files; the
634
+ voice download, poller lock, media, pause and live-update defaults resolve
635
+ through the same root and refuse a root that is not absolute
636
+ (`e91ca9d6`, `f14cb5ef`).
637
+ - **Peer dependencies declared** — `@earendil-works/pi-ai` (whose `/compat`
638
+ subpath the pinned `1.2.0` exports) and `typebox` join
639
+ `@earendil-works/pi-coding-agent` as peers, matching core and contrib, so
640
+ a strict-layout install resolves every value import the shipped sources
641
+ make (`typebox` had been a devDependency only).
642
+
643
+ ### Providers
644
+
645
+ - **State files refuse a root they cannot resolve** — the
646
+ `HOME || USERPROFILE || "."` fallback is gone; a base that is not absolute
647
+ is refused and the caller warns or stays in memory instead of writing
648
+ beside the cwd, the presend flush skips with one warn when the root is
649
+ underivable, and the presend root, key ring and route state resolve
650
+ `BRAID_HOME` at call time (`5bbdb77f`, `eead4ff3`, `f14cb5ef`,
651
+ `f029fb35`).
652
+
653
+ ### Contrib
654
+
655
+ - **State paths follow the package's braid-root mirror** — observatory
656
+ recordings, browser screenshots, the scraping profile, the reconnect lock
657
+ and the healthcheck probes resolve through the mirror and refuse a
658
+ relative or blank home; the healthcheck writers resolve core's live
659
+ `healthcheckDir()` through `pi-braid/lib` instead of binding the default
660
+ at module load, and the report CLI refuses a relative root with exit 2
661
+ (`e91ca9d6`, `f2413cde`, `f029fb35`).
662
+ - **`pi-braid` declared as a peer** — the shipped sources import
663
+ `pi-braid/lib` for the shared classifier, the event and session-start
664
+ helpers, `getExtensionState` and `healthcheckDir`; the package now
665
+ declares the dependency instead of relying on the monorepo's tsconfig
666
+ path mapping.
667
+
668
+ ## Core — 0.3.2-main.18 (2026-09-18: configured context window end to end)
669
+
670
+ Everything since core `0.3.2-main.17` ships in this release; telegram is
671
+ unchanged at `0.1.4-main.3`.
672
+
673
+ ### Core
674
+
675
+ - **Configured context window enforced end to end** — the configured cap
676
+ (`braid.context.contextLimitTokens`) is plumbed into the session model at
677
+ run start so pi-core's own threshold compaction and overflow detection
678
+ execute the cap; the turn-end act's deterministic slide fires regardless
679
+ of `compaction.enabled`; the single pending-compaction slot became a
680
+ bounded drain-and-coalesce queue that keeps archive anchors; one shared
681
+ token formatter across whispers, context_inspect, and tool feedback; and
682
+ read-only surfaces read other extensions' state through the real session
683
+ store (`6dfd3f67`).
684
+ - **Memory write gate** — a review-before-write predicate now fronts the
685
+ episode writers: signal-free tasks are rejected, dead solution fields are
686
+ repaired from the task, and exact/near-repeat (task, solution) pairs are
687
+ deduped against recent episodes (`32de2aba`, `5c319a77`, `2a5ef5fe`).
688
+ Configurable via `braid.memory.writeGate` (enforce/warn, per-site opt-outs);
689
+ an append-only write-decision log plus metrics and junk-scan scripts make
690
+ gate health measurable (`0b1aa6c9`, `cd5e2387`).
691
+ - **Recalled memory fencing** — memories recalled into a session are fenced
692
+ as non-user context, so stored notes can no longer masquerade as operator
693
+ instructions (`f76c2d80`).
694
+ - **Context management** — live context usage is measured per turn and acted
695
+ on before sessions grow (`698c168e`); compactions only run when the agent
696
+ loop is done (`84b3fad9`); slide and archive move the live working set
697
+ (`7dc0eb25`); a manual compaction is a full stop — the queued flush replay
698
+ is held and swallowed so no assistant turn resumes from pre-compaction
699
+ input (`7203dd73`).
700
+ - **Prompt identity refresh** — senior-craft wording, new
701
+ PLACEMENT_DISCIPLINE and SELF_AUDIT blocks, policy sections relocated
702
+ (`0a5246ba`); scanner-clean self-audit wording (`803a45ae`); mirror guard
703
+ and result schema in worker identity (`b66f69ef`).
704
+ - **Orchestrator tooling** — worker registry with atomic writes and a
705
+ duplicate guard (`f1bd20ca`); structured worker lifecycle actions and a
706
+ check-worker verdict (`312e7cb7`); the verification judge gained a
707
+ self-state claim class — delivery/liveness claims must cite a probe,
708
+ honest hedging stays exempt (`dad58772`).
709
+ - **Skills** — settings-driven session profiles and a boot hint
710
+ (`5226e368`); one-shot skills-boot whisper (`7b8fdad6`); new
711
+ probe-evaluation, misdirection-audit, and placement-discipline skills
712
+ (`3832df99`); the skills package joined the local publish pipeline
713
+ (`6f6b6b66`).
714
+ - **Timer recovery scoped to the owning session** — persisted-timer
715
+ restoration no longer crosses session boundaries (`7d3c6f89`).
716
+ - **Classifier empty-label fix** on reasoning-capable session models
717
+ (`7e0813f6`); edge/WAF challenge-page dumps redacted from internal request
718
+ bodies (`959ce4e0`).
719
+ - **Coverage** — root typecheck and lint now cover all four code packages,
720
+ with surfaced findings fixed (`103f7e79`); dead verification module
721
+ dropped (`c7d5ace1`).
722
+ - **Hygiene** — whole-tree private-data scan (`1929e02b`); placement checker
723
+ for provenance tokens, domain literals, and home paths (`8a1b408c`);
724
+ session provenance stripped from comments, tests, and docs, with
725
+ comment-discipline and commit-subject rules added to CONTRIBUTING
726
+ (`599ae15f`); knip dead-code detector adopted report-only (`737f6363`).
727
+ - **Docs** — compaction message-loss investigation preserved as a historical
728
+ record (`050e80f9`); skill/suite counts drift-proofed (`61b35d1e`,
729
+ `b6b80f8d`); setup requirements and security policy corrected
730
+ (`9d9b166f`).
731
+
732
+ ### Telegram
733
+
734
+ - **Voice STT hardening** — an ordered key pool (explicit key, `BRAID_TG_STT_KEYS`, macOS keyring, env candidates) advances on 401/403/429 and quota-class failures and remembers the winner; transcription is bounded to two passes with an ffmpeg-amplified retry; the chat-mode model default moved to a stable performer; the failure line carries diagnostics, never key material (`38bb5ba6`).
735
+ - **Long-by-default owner messages** — settings-driven caps replace the one-size truncation (`e8190b4b`).
736
+ - **Awareness catalog honesty** — the TG inbound row reports the live poller state instead of asserting unconditional reachability (`82bd2f83`).
737
+
738
+ ### Providers
739
+
740
+ - **OpenRouter removed** — venice (a0 proxy) is the only registered provider (`bc672e35`).
741
+ - **Reasoning-model fixes** — thinking "off" maps to wire-level none (`fcb3e4d9`); developer-role-incompatible qwen backends are marked per model (`0656aa36`).
742
+ - **Venice catalog robustness** — cost is always emitted as a finite number so unpriced models can't break the usage path (`0ec40974`).
743
+
744
+ ## Core — 0.3.2-main.17 / Telegram — 0.1.4-main.3 (2026-09-11: swallow-catch triage, dead-export removal, poller self-heal)
745
+
746
+ - **Swallow-catch triage** — 176 repo-wide swallow sites triaged to zero unexplained; 4 real silent persistence failures now logged (timer savePendingTimers/persistTimerToDisk, enforcement tag persist, budget double-swallow), 39 boilerplate catch comments upgraded to real whys (`fccfef81`); **dead-export removal** — 68 unreferenced exports deleted across 35 files, −717 lines (`6f0daebb` + `ae7a05d4`/`22036a12` follow-ups).
747
+ - **Poller self-heal across reloads** — pi-core emits session_shutdown on every agent-session reload; the telegram poller now survives it (intent flag + session_start re-arm) and telegram_send warns when the inbound poller is off at send time (`2937941e`).
748
+
749
+ ## Core — 0.3.2-main.16 (2026-09-11: scanner HOME hardening, legacy-comment cleanup)
750
+
751
+ - **Scanner HOME hardening** — `check-private-data` throws on missing HOME, providers typescript pin aligned to 6.0.2 (`5f404c82`); **legacy-comment cleanup** — deleted legacy echo comments and step narration from `src/**`, shrinking the shipped dist (`ffd3f2df`).
752
+
753
+ ## Core — 0.3.2-main.15 (2026-09-11: wake-retry hardening, wake-window proof, publish-readiness fixes)
754
+
755
+ - **Wake-retry hardening** — wake outcome timeout 60s→240s; redelivery deferred during
756
+ pi-core auto-retry via bounded `retryHoldUntil`; wake attempts capped 5→3 with
757
+ `braid.timers.maxWakeAttempts` setting; wake-gate arms on idle input only (`1b0cfed1`).
758
+ - **Wake-window proof** — empirical stress fixture (407 lines) proving the prompt-entry
759
+ wake window closed under load: no lost wake, no double delivery, no cross-run leak, hold
760
+ semantics verified. Scheduling pi-core-independence audit: 10 paths INDEPENDENT, 1 ADAPTED,
761
+ 2 accepted tested invariants; zero code changes required (`498b3a73`).
762
+ - **Publish-readiness** — core tarball: dead `CHANGELOG.md` files entry removed, `docs/`
763
+ now shipped; skills catalog corrected 23→27 in README/AGENTS/SETUP (`effd859e`).
764
+
765
+ ## Telegram — 0.1.4-main.2 (2026-09-11)
766
+
767
+ - **telegram_send description rewrite** — 1659→983 chars, decision-first with worked
768
+ examples; targets concise-path misprediction (7 mispredicts observed 2026-09-10) (`c22f79c7`).
769
+
770
+ ## Core — 0.3.2-main.14 (2026-09-09: skills rollup, judge chunked evidence, WAF excerpt redaction, surface discipline)
771
+
772
+ - **Skills rollup** — claimed-vs-actual load counters split, `scoreSkill` retuned,
773
+ needs-refresh descriptions refreshed (`e47e1036`); durable per-session adoption
774
+ records + monthly adoption-rate rollup split worker|orchestrator (`334afdd4`).
775
+ - **Judge chunked evidence** — RLM-style chunk summaries for task evidence beyond
776
+ the cap (`955ce1c2`).
777
+ - **WAF excerpt redaction** — Venice WAF challenge-page excerpts stripped from
778
+ stored history and the warn sink (`c8255b33`, providers-side `ring-lifecycle.ts`).
779
+ - **Surface discipline** — `SURFACE_DISCIPLINE` identity block with lockstep test
780
+ and slop diff-scanner shadow (`bed9b39a`).
781
+
782
+ ## Core — 0.3.2-main.13 (2026-09-05: prompt-builder hygiene + stale-toolResult offloader)
783
+
784
+ - **Prompt-builder hygiene** — the resources catalog section collapsed to a `list_skills` pointer,
785
+ memory-section counts removed, threshold literals cut from the prompt (they live in the owning
786
+ config), and herdr tool one-liners gated behind herdr availability (−1001 chars baseline).
787
+ - **Stale-toolResult offloader** — new `braid.context.staleToolResultOffload` setting, **default
788
+ OFF**: stale tool results are offloaded losslessly to disk and replaced in-context by a stub;
789
+ idempotent and bounded.
790
+ - **Hermetic test re-baseline** — 97/97 suites pass with temp-HOME fixtures (no dependence on the
791
+ live agent home).
792
+ - **Durable skill adoption counters** — per-skill suggested/loaded counts + lastAt persist across
793
+ sessions in `skills-usage.json`; `skill_stats` gains an all-time section; best-effort writes that
794
+ can never break the suggestion path.
795
+ - **Prettier drift cleared repo-wide**; `format:check` added to `ci:check` (root and core);
796
+ config-example documents both context settings (`contextLimitTokens`, `staleToolResultOffload`).
797
+ - **Telegram voice STT 401 fix** — chat-mode STT now derives its default baseUrl from the
798
+ userland venice catalog (`venice-catalog-base-url.ts`, mirroring the providers reader) so the
799
+ deployed gateway-era `A0_VENICE_API_KEY` pairs with the gateway that accepts it;
800
+ `BRAID_TG_STT_BASE_URL` still wins, transcriptions mode unchanged.
801
+ - **Small-correctness batch** — `prompt_inspect` includeTools/includeSkills now actually
802
+ exclude their sections in braid-composed prompts (the old patterns never matched the braid
803
+ prompt shape and always reported "0 lines removed"); `v2raytun_reconnect`'s rendered one-liner
804
+ no longer truncates mid-sentence; the watchdog tunnel canary probes `getMe` on getUpdates
805
+ failure so sibling-consumer conflicts no longer bark tunnel-down at healthy pollers;
806
+ `context_inspect` surfaces last-compaction loss counters (compacted → kept) in the loss line;
807
+ `context_compress` deep_clean feedback reports an estimated cut like archive/slide.
808
+
809
+ ---
810
+
811
+ ## Core — 0.3.2-main.12 (2026-09-04: config-tunable context limit)
812
+
813
+ A config-tunable context limit — `braid.context.contextLimitTokens`
814
+ (in `~/.pi/agent/settings.json`) caps the effective window braid computes against, while the
815
+ provider catalog keeps model truth. One pure resolver (`resolveContextLimitTokens` /
816
+ `getResolvedContextWindow` in `lib/config/braid-settings.ts`) owns the precedence: owner cap →
817
+ model/provider window → caller default; invalid values are ignored with a once-per-process
818
+ warning. All three window consumers read through it:
819
+
820
+ - **Density evaluator hardcode fixed** — the fast density path divided by a hardcoded 100k
821
+ window and fired density triggers ~3x too early at a 262k window; it now uses the resolved
822
+ effective window (100k only when neither the cap nor the provider window is known).
823
+ - **Percent math honors the cap** — context tiers and percent-of-window gates divide by the
824
+ effective window, so percent advisories stay meaningful under an owner cap instead of
825
+ referencing a window the owner has deliberately shrunk.
826
+ - New config test `test-context-limit-config.mjs` covers resolver precedence and consumer
827
+ wiring.
828
+
829
+ ---
830
+
831
+ ## Core — 0.3.2-main.11 (2026-09-03: token-gated advisories, heartbeat self-state, rollback guard)
832
+
833
+ Token-gated advisories plus a heartbeat self-state line, fixing three confirmed production
834
+ findings from long-session audits — most importantly that percent-of-window gating is
835
+ unreachable on 1M-token windows, where a measured session fired zero high-context advisories
836
+ across 154 turns at 150-238k tokens. The agent's self-identity now states honesty explicitly:
837
+ "an honest self-aware agent with a metacognitive suite and extras on top of pi."
838
+
839
+ - **Token-gated advisory path** — the context-lifecycle proposal real-need gate and the
840
+ urgent-bypass were percent-of-window only; at a 1M window they are unreachable. Gates now
841
+ open on EITHER arm — percent (sub-1M windows) or tokens (min(percent, token) semantics):
842
+ actionable at ≥ USAGE_TOKENS_CRITICAL (100k), urgent at ≥ HYGIENE_AUTO_COMPACT_HARD_BACKSTOP
843
+ (140k), escalated wording (archive-or-handoff) at ≥ new USAGE_TOKENS_ESCALATE (200k) — single
844
+ owner context-thresholds.ts. The compact-nudge message and the context-manager audit
845
+ recommendations / branching trigger carry the same token arms. Acting path (auto-compact
846
+ ACT ladder) untouched.
847
+ - **Heartbeat self-state line** — every heartbeat summary (tick batcher and the delayed-flush
848
+ builder) gains ONE ≤40-token self-state line right after the clock:
849
+ `self-state: ctx 213K tok · cache 96% · dup 39 · tps-ema 87`. Context tokens are a live read;
850
+ cache-hit share (cacheRead/(input+cacheRead)) is captured per assistant message and lands in
851
+ the context-heartbeat JSONL telemetry; near-duplicate count comes from the density evaluator;
852
+ tok/s trend is the existing EMA. An unavailable metric renders `n/a`, never zero.
853
+ - **Auto-rollback test-debug guard** — new `lib/detection/test-burst.ts`
854
+ keeps a bounded per-session ring of tool outcomes fed from the enforcement tool_result handler
855
+ and classifies test-runner bursts (runner commands, pass/fail counts, assertion errors).
856
+ autoRollback — the single DECISION point — now withholds the destructive rewind when the burst
857
+ is test-dominated (≥3 errors, every one test-marked, ZERO non-test failures) and downgrades to
858
+ whisper-only: the degradation advisory still fires (heartbeat + enforcement paths),
859
+ degradation state is not cleared, and genuine degradation with non-test errors rolls back
860
+ exactly as before.
861
+ - **Tests (metric pinning)** — `test-advisory-token-gate.mjs` (source scan: advisory gates
862
+ reference token constants; functional: proposal fires at 20%/120k tokens, suppressed at 20%/80k,
863
+ urgent at ≥140k), `test-heartbeat-self-state.mjs` (line format, n/a tolerance, summary
864
+ integration, cache telemetry), `test-test-burst-rollback-guard.mjs` (classifier cases,
865
+ suppression on test-dominated bursts, no suppression when errors span non-test tools,
866
+ autoRollback end-to-end both ways).
867
+
868
+ ---
869
+
870
+ ## Core — 0.3.2-main.10 (2026-09-03: time-awareness)
871
+
872
+ One owner-timezone clock for everything braid renders, plus the telegram truncation contract
873
+ and inbound timestamps. Companion telegram release `0.1.4-main.1`.
874
+
875
+ - **One local-time formatter** — new `lib/utils/local-time.ts`:
876
+ `formatLocalTime()` renders `HH:MM TZ (UTC±X)` (with optional `YYYY-MM-DD` date) in
877
+ the owner time zone — `braid.timezone` in settings.json, default `Europe/Moscow` —
878
+ and `formatWhisperClock()` renders the compact `HH:MM TZ` header form. Fixed-offset
879
+ abbreviation map (MSK, YEKT, …) because CLDR renders Europe/Moscow as "GMT+3". Every
880
+ braid-facing time string now routes through it; the scattered
881
+ `toLocaleTimeString()` call sites (timer set/list text, timer-reminder "Fired at:")
882
+ are gone.
883
+ - **Whisper header timestamps** — the central envelope builder
884
+ `formatWhisperEnvelope()` (whisper-format.ts) renders
885
+ `[braid-whisper - <subsystem> @ 17:05 MSK]`, so every `sendTrackedMessage` whisper
886
+ and the telegram inbound builders carry the generation/send clock: the agent can
887
+ tell a fresh whisper from a stale re-injection. A source-tree scan test pins that
888
+ no hand-built envelope literal can bypass the formatter.
889
+ - **Fresh clock** — every heartbeat summary (both builders) prepends
890
+ `now: <YYYY-MM-DD HH:MM TZ (UTC±X)>`; the prompt-builder gains a 30-minute datetime
891
+ drift guard: when >30 min have passed since the last datetime anchor, a one-line
892
+ `datetime-refresh` whisper re-anchors the clock (the re-anchor IS the rate limit —
893
+ exactly one refresh per window). Fixes long sessions reasoning on a
894
+ session-start-stale clock.
895
+ - **Timer honesty** — timer fire text now reads
896
+ `set for 16:58 MSK (UTC+3), fired 17:05 MSK (UTC+3) — drift 7m`; the
897
+ set-confirmation and `timer list` render the owner-TZ wall clock with the date.
898
+ - **Reachability catalog** — the once-per-session hygiene whisper gains a
899
+ 6-channel "can reach you" block (enforcement whispers, heartbeat, watchdog, timers,
900
+ context-lifecycle proposals, TG inbound) with rough cadences, ≤80 tokens.
901
+ - **Identity reword** — IDENTITY_INTRO now reads "You are Braid, a
902
+ self-aware agent with a metacognitive suite and extras on top of pi"; README
903
+ taglines match.
904
+ - **Telegram truncation contract (telegram 0.1.4-main.1)** —
905
+ `telegram_send` gains explicit `limit` (chars) and `strategy` ("truncate" | "error")
906
+ params. Over-limit WITHOUT an explicit choice now errors to the agent (stating the
907
+ limit + the options: rich:true / shorter text / explicit strategy) — the silent hard
908
+ truncation fallback is gone (zero silent truncations; the crafting distillation
909
+ stays). An explicit `strategy: "truncate"` is the only hard-truncate path and skips
910
+ crafting; `rich:true` split-to-fit is unchanged. Tool description states the limits
911
+ explicitly.
912
+ - **Telegram inbound timestamps** — `TelegramUpdate.date` now renders as
913
+ `@ HH:MM TZ` in the `[braid-whisper - telegram]` header of BOTH inbound builders
914
+ (poller + agentic inbox), using the telegram-local mirror of the core formatter
915
+ (the package cannot import core — established watchdog-tunnel mirror pattern;
916
+ parity pinned by its own test).
917
+ - Version bump: `0.3.2-main.10`. Telegram version: `0.1.4-main.1` (corrected: a
918
+ `0.1.3-main.1` would have been a semver downgrade from `0.1.4-main.0`).
919
+
920
+ ---
921
+
922
+ ## Core — 0.3.2-main.9 (2026-09-03: context-hygiene enforcement)
923
+
924
+ - **Real heartbeat telemetry** — the heartbeat tick fed
925
+ `recordTurnMetrics` constants (`avgTurnDurationMs: 1000`, `inputTokens: 0`,
926
+ `memoryUsagePercent: 50`); the entire degradation pipeline ran on
927
+ placeholders. New `lib/telemetry/context-heartbeat.ts` collects live
928
+ context tokens/percent/window (`ctx.getContextUsage`), RSS + heap,
929
+ session-file size, per-class char deltas since the previous tick (density
930
+ walk), injected-whisper pressure, and tokens/sec from the assistant
931
+ message window — one append-only scalar-only JSONL line per tick at
932
+ `~/.pi/agent/braid/telemetry/context-heartbeat.jsonl`. A second hook emits
933
+ the same line on the watchdog engine's wall-clock cadence so idle processes
934
+ are covered. Sink failures are non-fatal; entries are scalar-whitelisted at
935
+ the boundary.
936
+ - **Watchdog flap latch + escalation budget** — preserved the
937
+ owner-endorsed first-bark wake-up; killed the repeat storm (measured:
938
+ 143 escalations, 55 byte-identical, 33.6k chars = 5.1% of peak context).
939
+ A transient close no longer re-fires the threshold bark nor resets the
940
+ milestone ladder; re-arm requires a 3-consecutive success streak (healthy
941
+ evaluations or LLM successes). A per-session per-condition injection
942
+ budget (12, `WATCHDOG_ESCALATION_BUDGET_PER_SESSION`) leaves only the
943
+ 500-milestone rung active once exhausted. Tunnel recovers via its genuine
944
+ `up` event (explicit success); turn-stall's long-cooldown behavior is
945
+ unchanged.
946
+ - **Token re-arm for turn-end auto-compact** — the 15-turn
947
+ cooldown allowed 190-415k-token regrowth between compactions (measured
948
+ peaks 191-261k). The turn-end ACT now re-arms whenever tokens ≥ 100k and
949
+ ≥ 3 turns passed since the last attempt, plus an UNCONDITIONAL hard
950
+ backstop at ≥ 140k tokens (`HYGIENE_AUTO_COMPACT_HARD_BACKSTOP`) that
951
+ ignores all spacing — bounds runaway single-tool-result growth. Pre-save
952
+ resume.json + compact mechanics untouched.
953
+ - **Auth/balance health recovery** — `recordLlmSuccess` never
954
+ cleared the `auth`/`balance` modes and the probe tick only fired on
955
+ errors, so one 401 burst latched a session forever and heartbeat
956
+ consolidation was skipped permanently (live: the orchestrator session
957
+ latched auth ~19 minutes). Both modes now clear via a bounded probe
958
+ (5-min quiet window → next success proves recovery; a fresh 401
959
+ re-latches instantly — initial escalation NOT weakened) or a 10-success
960
+ streak. New `consolidationSkipsByMode` counter on SessionHealthState
961
+ tracks skipped consolidations per mode.
962
+
963
+ ---
964
+
965
+ ## Core — 0.3.2-main.8 (2026-08-29: pre-publication polish)
966
+
967
+ - **OOM crash fix (2026-09-01 hotfix)** — pi-core 0.84.4 removed
968
+ `settingsManager` from ExtensionContext; the degradation-detector
969
+ `isCtx()` guard keyed on it, so every heartbeat tick treated the ENTIRE
970
+ ctx object as a metrics entry — embedding the full session graph AND the
971
+ modelRegistry (credentials) into `degradation.json` until
972
+ `JSON.stringify` exceeded the V8 string limit ("Invalid string length")
973
+ and processes grew to multi-GB heaps overnight. Fix: ctx detection now
974
+ keys on `sessionManager`/`modelRegistry` (present in both old and new
975
+ pi-core); metrics entries are built by a scalar WHITELIST copy instead of
976
+ spreading the argument; async-storage refuses to serialize state files
977
+ above 10MB (skips with a loud error instead of OOM-ing); regression test
978
+ `test-degradation-ctx-guard.mjs` pins all three invariants. The polluted
979
+ 87MB→525MB `degradation.json` was purged (it also contained live API keys
980
+ — credential sprawl closed).
981
+
982
+ - **Tool-instruction ownership inversion** — per-tool inventory lines resolve
983
+ by priority: the tool's OWNING package `promptGuidelines` (pi-core native
984
+ seam) → static `TOOL_GUIDELINES` (strategy-only `when / when-not / key
985
+ args / caveat` one-liners for all 32 documented tools, synced 1:1 with
986
+ `TOOLS.md` via lockstep test) → `EXTERNAL_TOOL_GUIDELINES` last-resort map
987
+ for unpatched third-party packages (herdr, pi-smart-fetch) → first sentence
988
+ of the tool's own description. No duplication with description text.
989
+ - **SKILLS_LOADING strategy contract** — pointer rule (catalog
990
+ one-liner is metadata, not content), mid-task re-list trigger (paginated
991
+ catalog), never-act-from-memory rule, and an explicit when-not test.
992
+ Mechanics (offset clause) deduplicated into the `read` guideline.
993
+ - **Telegram double-message fix** — agent-delivery flag: explicit
994
+ `telegram_send` marks the message delivered; live-update `finish()`
995
+ suppresses its auto summary when flagged (`0.1.3-main.0` companion).
996
+ - **Watchdog tolerance widened** — poll timeout 30→50 s, `tunnelFailures`
997
+ 3→5 (config-overridable).
998
+
999
+ ## Core — 0.3.2-main.7 (2026-08-27)
1000
+
1001
+ - prompt-builder archaeology debloat — removed dead whisper/pointer material.
1002
+ - Compaction originals archive is fully lossless and append-only.
1003
+ - Telegram inline-keyboard pause/resume landed in the same release.
1004
+ - Companion telegram release 0.1.3-main.0 shipped together.
1005
+
1006
+ ## Core — 0.3.2-main.1 … 0.3.2-main.6 (2026-07-27 → 2026-08-25)
1007
+
1008
+ - **Monorepo migration** — all five packages (`core`, `skills`, `contrib`,
1009
+ `providers`, `telegram`) under npm workspaces; 333 duplicate root files
1010
+ removed.
1011
+ - **API key ring** — generalized multi-key provider rotation with exponential
1012
+ backoff, persisted exhaustion state, and self-healing turn retry.
1013
+ - provider registration rewritten on `createProvider` + request-time key-ring
1014
+ auth resolution.
1015
+ - prompt-builder overhaul — discovery stance, tool-usage pipelines, and a
1016
+ once-per-session awareness whisper.
1017
+ - **Compaction upgrades** — speaker attribution and sliding-window compaction
1018
+ (`action=slide`).
1019
+ - **Skills verdicts applied** — KEEP/IMPROVE/DEPRECATE/MOVE from the
1020
+ skills-usage research, with freshness markers.
1021
+ - `packages/lib` retired into `core/src/lib`; `packages/telegram` added as a
1022
+ workspace.
1023
+
1024
+ ## Core — v0.3.x (v0.3.0 → v0.3.2, 2026-07-23 → 2026-07-25)
1025
+
1026
+ - Versioned **local publish pipeline** (`publish-local.mjs`) — `base-branch.iteration`
1027
+ scheme, auto-reverts the version bump.
1028
+ - **v0.3.2** release plus a compact >70% release guard.
1029
+ - Definition-of-Done invariant and turn-end hygiene/discoverability
1030
+ improvements.
1031
+
1032
+ ## Core — legacy v0.1.1 … v0.39.0 (2026-04-17 → 2026-05-15)
1033
+
1034
+ The pre-monorepo line that built the foundation. Highlights:
1035
+
1036
+ - Repo carved out of the pi-mono/pi-braid lineage (2026-04-13).
1037
+ - **Native `web_fetch` + CDP browser automation** with zero external deps.
1038
+ - Typed **event bus** for cross-extension signals — proactive context
1039
+ projection and analytics.
1040
+ - **Three-memory-stores** — episodes / semantic / heuristics deep merge with
1041
+ cross-search and session recall.
1042
+ - prompt-builder decomposed into `PromptSection` fragments + pointer blocks;
1043
+ behavior-modes system dropped for static identity invariants.
1044
+ - Skills reorg across core/contrib/pack boundaries and contrib split out then
1045
+ re-merged.
1046
+ - pi-ai v0.80 compat — Models-instance holder replaces direct child access.
1047
+
1048
+ ---
1049
+
1050
+ ## Providers — 1.0.4-main.1 (2026-09-09: WAF excerpt redaction)
1051
+
1052
+ - **WAF excerpt redaction** — Venice WAF challenge-page excerpts no longer reach
1053
+ stored history or the warn sink (`c8255b33`); direct-call warn excerpts redacted
1054
+ and the self-heal test synthesizes its WAF body (`63782887`); release bump to
1055
+ `1.0.4-main.1` from flat `1.0.3` (`e6d9f984`).
1056
+
1057
+ ---
1058
+
1059
+ ## Telegram — 0.1.4-main.0 (2026-09-01)
1060
+
1061
+ - **Idempotent edit fix** — `editMessageText` treats Telegram's 400
1062
+ "message is not modified" as success instead of warning (re-tapping the
1063
+ pause-control status button is a no-op, not a failure); regression test
1064
+ added.
1065
+ - **Poller/inbox discipline in promptGuidelines** — `telegram_inbox` and
1066
+ `telegram_poller` now carry the getUpdates-singleton rule: while the
1067
+ poller runs, manual inbox calls conflict (expected, not a bug); the
1068
+ owner's `/telegram enable|disable` commands own the same singleton —
1069
+ never blindly re-enable over an explicit disable.
1070
+
1071
+ ## Telegram — 0.1.x (0.1.0 → 0.1.3-main.0)
1072
+
1073
+ - **0.1.0** — bidirectional channel: fetch-based client, `telegram_send`
1074
+ tool, inbound long-poll injector.
1075
+ - **0.1.1** — release refresh.
1076
+ - **0.1.2** — voice inbound + STT; photo inbound.
1077
+ - **0.1.3-main.0** — inline-keyboard **pause/resume** control.