pi-braid 0.42.0 → 0.42.1

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