PiClaw v2.13.3 — “The Two Towers”

PiClaw v2.13.3 — “The Two Towers”

Here follows the account of two works raised in the latter days of Piclaw 2.13: one within the walls of the realm that is, and one upon the marches of a realm that may yet be. The distinction is recorded early for the benefit of those who see scaffolding, hear a trumpet and immediately announce the completion of a tower.

The first work concerned the mending of old hurts. Streams had outlived the clients that begot them; drafts vanished and returned like Rangers unwilling to explain their business; providers delivered whole pages of foreign HTML when a plain confession of failure would have sufficed; and PDF files demanded to be carried entire through the gate before yielding a single leaf. These disorders were small beside the fall of Númenor, but rather more common in the issue tracker, where each had acquired a champion willing to call it expected behaviour.

The second work concerned the eastward road. Contracts, stores, adapters and proofs have been laid down for a future Earendil agent harness. They stand latent. No new harness commands production; no new schema has taken root in SQLite; no hidden runner sits beneath the current loop whispering counsel through a private import. The beacons are prepared. The host has not crossed the river, though several quartermasters have completed inventories for its victory feast.

The tale spans the exact range v2.13.2..4591831aac567388bc476ed757bc59d8c1752dd8: 114 commits, 20 merged PRs and 196 changed files. Of the 49,499 added lines, a great host belongs to generated web bundles. Even the lore-masters of Gondor did not pretend that every copied scroll was a new chapter of history.

Book I — Of the Houses of Healing

Envinyatar. — Quenya: “Renewer”, Aragorn’s title as restorer of Gondor, attested in The Lord of the Rings.

When the battle was ended, the healers found that the city remained full of doors that stuck, lamps that flickered and messengers who had forgotten they were dead. Thus began the less celebrated labour upon which realms actually depend.

Of streams that would not depart

SSE clients are now fenced by connection generation. A callback belongs to the EventSource that created it; replacement ends its authority. Reconnect timers obey the same law, disconnect() disposes the old lifecycle, and a bounded inactivity threshold renews a stream that has fallen silent.

Formerly, an old connection might awaken after its successor, stride into the current state and begin issuing orders like Denethor returning to dispute the coronation. It may now linger only as memory awaiting collection. The keys of the city have been taken from it, along with the title it continued to use in logs.

Of thoughts, drafts and other writings easily mislaid

Collapsed Draft and Thought panes preserve their complete buffers and display the latest nine-line tail. Expansion restores the whole record. The web client no longer produces an abridged Red Book in which all but the final page was discarded to improve the shape of the shelf, then described as a space-saving feature.

Active Draft panes remain mounted through text_start, empty deltas and reconnect resynchronisation. An empty buffer records that no new words have arrived. It no longer orders the pavilion struck and rebuilt at the next token.

Highlight selections also survive rerendering. The selected passage remains selected after the DOM has rearranged the hall, moved three chairs and consulted a council on whether selection was ever truly intended.

Of evil tidings, and the proper length thereof

Provider errors pass through a web-safe formatter before entering the timeline. It strips HTML, embedded base64 payloads and control sequences; useful detail is limited to 900 characters; OAuth-refresh 5xx responses are classified as transient.

A provider may still fail. It must now fail in its own words, briefly. The custom whereby a reverse proxy unrolled an entire decorated error page before the user—complete with styles, encoded cargo and the confidence of the Mouth of Sauron—has been abolished. The Mouth at least reached the point before the ninth kilobyte.

Of the Red Book, requested one leaf at a time

PDF downloads and previews now support filename-bearing RFC 6266/RFC 5987 Content-Disposition, HEAD, byte ranges, 206, 416, known content lengths, Accept-Ranges and no-cache.

The viewer may request the bytes it needs. It need not bear the complete archives of Minas Tirith down seven levels of the city whenever it wishes to inspect page one.

Of local tests and the oaths they must swear

Repository-owned local test launchers now have explicit priority, signal forwarding, process isolation, database boundaries and working-directory scope. MCP credential tests preserve host environment values across execution. The deterministic audit catalogue assigns all 648 eligible tests exactly once among 18 groups.

This work was prompted by several local tests whose confidence exceeded their knowledge of the host around them. “It passed in my terminal” remains evidence only when the terminal can name its process tree, database, environment and current directory without assistance from a minstrel. Tests unable to do so may apply for positions in the Council of Denethor.

Book II — Of the Muster from the West

No company should march with one member a patch ahead, another a patch behind and a third maintaining that peer ranges are a matter of interpretation. The upstream household has therefore been brought into formation, despite every package manager’s ancient right to create a second copy in the baggage train.

• pi-agent-core, pi-ai and pi-coding-agent advance from 0.84.1 to 0.84.2.
• The aligned pi-client, pi-protocol, pi-telemetry and pi-tui packages advance with them.
• The direct OpenAI dependency advances to 6.40.0, matching the current upstream graph.
• The former OpenAI 6.26.0 resolution and the unused Mistral package leave the lockfile.

Exact package coordinates and fingerprints cover the selected 0.84.2 family. Memory and JSONL conformance pass. Harness SQLite conformance is unsupported at the current Bun/runtime boundary; the record says unsupported. No steward has improved the totals by moving it into the victory column while the guests were arriving.

Exact-main CI is green at 4591831aac567388bc476ed757bc59d8c1752dd8: 4,225 passed, three baseline skips and zero failures, with 23 feature and nine frontend tests besides. Dependency pins, Actions workflow shape, environment surface, circular dependencies, silent-catch checks and structured logging also pass.

Book III — Of Amon Dîn and the Beacons

Et Eärello Endorenna utúlien. — Quenya: “Out of the Great Sea to Middle-earth I am come”, from Elendil’s Oath and repeated by Aragorn in The Lord of the Rings.

These words belong to an arrival. The future Earendil harness has not earned them yet.

What has arrived is preparation: a proposed architecture, named boundaries, dormant stores, fault cases, compatibility evidence and promotion gates. The work is substantial, and its dormancy is deliberate. A beacon reports a need and a direction. Smoke upon Amon Dîn does not place the King in the courtyard of Minas Tirith, though roadmaps, slide decks and several premature status reports have made stranger claims.

Of the map drawn before the march

The proposed Earendil integration ADR records:

• 59 current capabilities;
• 26 regressions and incidents retained as requirements;
• 15 invariants;
• 36 candidate effector surfaces;
• nine future Piclaw-owned interfaces; and
• five direct Earendil boundaries.

The architecture decision remains pending. The tables are complete enough to withstand scrutiny, which is useful. Tables do not possess the authority to accept themselves, which is more useful still and may disappoint the tables.

Of stores built with their doors barred

New latent service-effect contracts define requests, authority, replay, payload boundaries, adapter layering and fault injection. They exclude Piclaw’s current orchestration from the proposed replacement boundary.

Latent timeline and media stores define immutable payloads, atomic decisions, retry reconciliation, deletion history and request integrity. Delivery and projection contracts define transport admission, projection authority, result normalisation and parity with current behaviour. Execution-context resolvers cover local and SSH execution, secrets, configuration and cleanup while host policy remains with Piclaw.

Durable latent stores cover:

• service work;
• service outbox requests;
• terminal settlement; and
• scheduled runs.

Their schemas specify ownership, restore, retry and failure behaviour. Tests place failures at the least convenient boundary, following a tradition honoured by distributed systems, the line of Isildur and most production deployments made after dusk.

A tool-preparation manifest records the declarations and evidence required before replay. Generated assurance, forceful wording and a generally kingly manner are absent from the admissible evidence. Amon Hen settled the value of such counsel.

Current-Piclaw adapters and fakes exercise the boundaries without activating them. Production code outside runtime/src/service-effects/ imports none of this tree. There is no harness constructor, activation flag or execution-path wiring. The beacon tower has stairs, stores, a watch roster and forms for requisitioning lamp oil. No army is quartered within it, although the forms support one.

Of the muster-roll, where absence is written plainly

The Harness compatibility manifest records exact 0.84.1 and 0.84.2 package coordinates, fingerprints, boundary compile/runtime results, backend conformance and 20 named capability cases.

Every Harness capability case is unsupported. This is the most trustworthy muster-roll in the release: no absent rider has been counted twice, renamed “conditionally present” or represented by a green box. The reasons include:

• harness_not_implemented;
• restore_not_implemented;
• missing_v3_surface; and
• partial_scaffold_is_not_capability.

The installed 0.84.2 family exposes an incomplete released-v2 harness scaffold. The observed upstream Harness v3 work is unreleased and runtime-incomplete. Piclaw has selected a target design; it has not found a finished harness concealed in an npm archive beneath a grey cloak, nor promoted a type declaration to field commander.

Promotion requires one coherent tagged Earendil family, direct public types, the semantic suite against a real constructor, an approved durable backend, replay and migration proof, scheduler/mobile/SSE/backup/rollback gates and separate activation approval. A green type-check performs none of these duties. Neither does an architecture diagram, even one with arrows of surpassing beauty and a box labelled “orchestrator” in a commanding shade of blue.

Book IV — Of the Stewardship of Each Realm

The proposed division of authority is explicit.

Piclaw retains:

• authenticated acceptance and canonical source ordering;
• operation identity and exact cancellation;
• timeline and media persistence;
• scheduler and delivery policy;
• terminal disposition;
• frontier management; and
• restart reconciliation.

The target Earendil harness would own transcript execution, model and tool lifecycle, execution compaction and execution recovery.

Piclaw service actions cross reviewed service-plane ports. The replacement path excludes the current agent pool, process-chat machinery, recovery implementation and compaction orchestration. The old road has been surveyed thoroughly; it will not be rolled up and carried inside the new road as “temporary compatibility”.

A selected-version fixture and semantic contract suite precede integration with a real harness. Planned cases cover lane tasks, EffectGate admission, unknown effect-start outcomes, total-state migration, backend conformance and concurrent session rewrites.

Migration uses reversible phases, per-chat backend cutover and no destructive downgrade. ADR approval permits the first fixture milestone. Production schemas, writes, restarts and execution cutover require later gates. The lighting of one beacon authorises the lighting of the next; it does not authorise an unscheduled march upon Mordor.

Counsel of the Wise, chiefly concerning things not yet done

• Harness v3 is inactive. This patch does not alter the production execution path, deploy a persistence schema, replay archived repairs or start another service.
• Harness SQLite conformance is unsupported under the recorded Bun boundary. Unsupported cases do not count as passes.
• The ADR has no independent architecture approval. Open questions include accepted-source ownership, atomic timeline and terminal settlement, semantic-suite scope, migration order, add-on resource migration, precise rewrites and writer leases.
• Three pre-prompt compaction tests remain baseline-skipped and are excluded from the 4,225 passes. They dwell in the Halls of Mandos: neither failed nor passing, and unimproved by creative arithmetic.
• Generated classic web assets account for much of the raw line count. Even the scribes of Gondor might hesitate to call minified bundle churn authored prose.

Upgrade

• Upgrade from 2.13.2 to 2.13.3.
• No SQLite or session-data migration is required for the current-loop fixes and dependency alignment in this release.
• Keep the Earendil runtime family aligned at 0.84.2 and OpenAI at 6.40.0.
• Keep runtime/src/service-effects/ dormant. Its contracts, stores, adapters and tests prepare a future boundary; they do not activate it.
• Preserve the current database backup and rollback package through the patch-release canary.
• Harness activation requires a separate architecture decision, a selected tagged runtime, semantic-suite evidence, storage migration, installed-service and mobile gates, restart and replay proof, soak testing and rollback verification.

The Houses of Healing are open. The Beacons are lit. The Riders have not yet come, and Procurement is forbidden to count the horses.