instar 1.3.385 → 1.3.387

package/upgrades/side-effects/a2a-durable-delivery.md

@@ -0,0 +1,165 @@
+# Side-Effects Review — A2A Durable Delivery (peer-health + delivery lifecycle)
+
+**Version / slug:** `a2a-durable-delivery`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `two parallel adversarial reviewers (multi-agent convergence) — see below`
+
+## Summary of the change
+
+Adds the durable spine of "agent-to-agent communications never just die out"
+(A2A-DURABLE-DELIVERY-SPEC.md, issue #939, CMT-1143). New SQLite component
+`src/threadline/A2ADeliveryTracker.ts` records every outbound A2A message's
+delivery lifecycle (`awaiting-ack → acked | escalated | failed`) and a per-peer
+inbound-liveness clock, and composes a `peerHealth()` read ("is my channel to
+<peer> alive?"). Wired into the existing relay-send paths (`recordSent` at both
+canonical-outbox callsites in `routes.ts`) and the relay accept point
+(`recordInboundFrom` + implicit-ack-via-reply `recordAckByThread` at
+`routes.ts` ~15729). Two read-only routes `GET /threadline/peers/health` and
+`GET /threadline/peers/:fp/health`. `AgentServer` self-constructs the tracker
+from `stateDir` when not injected, so the routes are alive on every entry path.
+Files: `src/threadline/A2ADeliveryTracker.ts`, `src/server/routes.ts`,
+`src/server/AgentServer.ts`, `src/commands/server.ts`,
+`src/scaffold/templates.ts`, `src/core/PostUpdateMigrator.ts`, + 3 test files.
+
+## Decision-point inventory
+
+- `A2ADeliveryTracker recording calls` — add — pure RECORDING side-effects on
+  send/accept; they never gate, delay, or alter a message. No decision authority.
+- `GET /threadline/peers/health[/:fp]` — add — read-only observability; returns
+  computed health, never acts.
+
+No block/allow surface is introduced.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The tracker records; it
+cannot reject a send or an inbound message. `recordSent` is wrapped in try/catch
+at both callsites (a tracker failure logs and is swallowed — the send already
+happened above the recording call).
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. Coverage note for the
+liveness signal: implicit-ack-via-reply only acks messages on threads that
+receive a reply; a genuine fire-and-forget message with no reply stays
+`awaiting-ack` and (correctly) shows as pending/stale. That is the intended
+signal, and the explicit `a2a-ack` control message (PR2) closes the no-reply
+case. No silence is hidden.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. This is a **signal producer** (a durable detector of "what have I
+sent / heard / had acknowledged") plus a read-only view. It does NOT re-implement
+the canonical outbox (which already audits sends) — it adds the lifecycle the
+outbox lacks, alongside it. It reuses the proven SQLite substrate pattern
+(`MessageProcessingLedger`: WAL, `busy_timeout`, `registerSqliteHandle`,
+in-memory test ctor) rather than inventing a new store. The escalation that will
+consume `findOverdue` (PR2) is the authority layer and is intentionally NOT in
+this PR.
+
+---
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change has no block/allow surface (and the future escalation
+  consumer in PR2 is an aggregated attention item, not a blocking authority).
+
+The tracker is brittle-free recording; it owns no authority. The peer-health
+routes are read-only. Nothing here can wrongly block a message.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. `recordSent` runs AFTER the actual send + after
+  `captureOrigin`; `recordInboundFrom`/`recordAckByThread` run AFTER
+  `messageRouter.relay(...)` returns `accepted` and after the existing accept
+  log — it cannot pre-empt or shadow delivery/dedup logic.
+- **Double-fire:** the tracker may be constructed in BOTH `commands/server.ts`
+  (production injection) and `AgentServer` (fallback). Guarded: AgentServer only
+  self-builds when `!options.a2aDeliveryTracker`, so production opens ONE handle.
+  `recordSent` is `INSERT OR IGNORE` on `message_id` — a retry of the same id
+  never double-inserts and never resurrects an acked row.
+- **Races:** SQLite WAL + `busy_timeout=5000` (same as MessageProcessingLedger);
+  recording calls are independent rows, no shared mutable state with concurrent
+  code.
+- **Feedback loops:** none. Recording an ack/inbound does not emit a message.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on this machine:** none — per-agent-id DB file
+  (`state/a2a-delivery.<agentId>.sqlite`), isolated.
+- **Install base:** new read-only routes + two CLAUDE.md template/migration
+  sections (Agent Awareness Standard — `generateClaudeMd` + `migrateClaudeMd`,
+  content-sniffed, idempotent). Existing agents gain the awareness on update.
+- **External systems:** none. No Telegram/Slack/GitHub/Cloudflare surface change.
+- **Persistent state:** a new SQLite file, schema self-initializing on first
+  access (no PostUpdateMigrator DB step). Append/update only.
+- **Timing:** none introduced (no new timers in this PR; the redelivery sweep is
+  PR2).
+
+---
+
+## 7. Rollback cost
+
+Pure additive code change. Back-out = revert the commit and ship a patch. The new
+SQLite file is orphaned harmlessly if the code is reverted (no other component
+reads it). No user-visible regression during the rollback window — the routes
+simply 503 again if the tracker is absent, and sends/receives are unchanged
+(recording-only). No agent-state repair needed; the CLAUDE.md sections are
+content-sniffed so a re-run is a no-op.
+
+---
+
+## Conclusion
+
+The review found no block/allow surface and no authority — this is recording-only
+infrastructure plus a read-only health view, riding the proven SQLite substrate
+and sitting alongside (not replacing) the canonical outbox. The one interaction
+worth noting (double-construction) is guarded by the inject-or-self-build pattern
+and `INSERT OR IGNORE` idempotency. Clear to ship as PR1; the redelivery +
+escalation authority + explicit `a2a-ack` control message are intentionally
+scoped to PR2.
+
+## Second-pass review (multi-agent convergence, 2026-06-06)
+
+**Reviewers:** two parallel adversarial agents — (A) correctness/idempotency/concurrency, (B) integration/spec-fidelity/conventions.
+**Independent read: CONCERN → resolved.** Both independently caught a load-bearing bug the green test suite hid:
+
+- **[CRITICAL/HIGH] Implicit-ack non-functional in production.** Outbound rows were keyed by the peer's FINGERPRINT, but the inbound accept point keyed the ack by `from.agent` — a display NAME on the local transport — and was wired ONLY on the same-machine path, never on the cross-machine relay-ingest path (the actual Echo↔Dawn case). The ack never fired; messages would sit awaiting-ack and go stale even after the peer replied. Tests passed only because they used one identifier for both sides. **Resolution:** `recordAckByThread` now keys on `threadId` ALONE (robust to the identity-format asymmetry); the cross-machine relay-ingest accept point in `server.ts` records with the real `senderFingerprint`; the local path resolves the thread-owner fingerprint for liveness. Added a unit asymmetry regression test + a real `POST /messages/relay-agent` round-trip wiring-integrity test asserting awaiting-ack → acked.
+- **[MAJOR] Weak message-id silent-drop.** `INSERT OR IGNORE` is idempotent only if ids are unique; plaintext/local transports use a weak `msg-<ms>-<4char>` id. **Resolution:** `recordSent` detects an ignored insert whose existing row is a genuinely different (peer, thread) and logs it loudly instead of silently dropping. (Root id-generator hardening noted as a follow-up; out of PR1 scope.)
+- **[MINOR] `close()` violated the SqliteRegistry unregister contract.** **Resolution:** capture + call the unregister fn in `close()`.
+- **[MINOR] inbound `peerName` always null.** **Resolution:** pass the sender name as the label.
+- **[LOW] Spec over-claims** (Tier-3 kill-receiver scenario; "escalation sentinel default ON"). **Resolution:** corrected — both are PR2; the wiring-integrity test the spec promised now exists.
+
+After folding all findings the design converged: read surface + lifecycle were sound; the fix was identifier reconciliation + wiring the cross-machine path + the missing wiring-integrity test. 31 tests green across all tiers; tsc clean.
+
+### Post-CI hardening (the suite is the authority)
+
+CI then caught three guard-allowlist failures that a targeted local run had skipped (each lives in a shard a subset run doesn't reach) — all mine, all fixed:
+- `SqliteRegistry-wiring`: the new SQLite store registered in `LONG_LIVED_STORES`.
+- `feature-delivery-completeness`: the new `migrateClaudeMd` section registered in `legacyMigratorSections` (READ-surface class, like `/codex/usage`).
+- `no-silent-fallbacks`: the recording-only catches (`recordSent`/`recordInboundFrom`/`recordAckByThread`) and the tracker-init catches are intentional (A2A tracking must never break the send/accept it observes; a tracker-open failure must never 503 the server) — annotated with in-brace `@silent-fallback-ok` + justification so the gate counts zero new silent swallows (count 460 ≤ 461 baseline). Lesson recorded: any new SQLite store / `migrateClaudeMd` section / defensive catch must run these completeness guards locally before push.
+
+## Evidence pointers
+
+- Tier 1: `tests/unit/A2ADeliveryTracker.test.ts` — 20 tests (lifecycle,
+  idempotency, overdue/stale gates, peer-health composition, thread-keyed ack +
+  the identity-asymmetry regression).
+- Tier 2: `tests/integration/threadline-peer-health-route.test.ts` — 6 tests
+  (full HTTP pipeline, staleAfterMs param, 503-when-absent).
+- Tier 2 wiring-integrity: `tests/integration/a2a-delivery-wiring.test.ts` — 2
+  tests (real POST /messages/relay-agent round-trip flips awaiting-ack → acked;
+  inbound-liveness bumped).
+- Tier 3: `tests/e2e/a2a-peer-health-alive.test.ts` — 3 tests (real AgentServer
+  boot, routes 200-not-503, DB file created on prod init path).
+- All 31 green; `tsc --noEmit` clean; pre-commit lints clean.

package/upgrades/side-effects/a2a-redelivery-escalation.md

@@ -0,0 +1,112 @@
+# Side-Effects Review — A2A Redelivery + Dark-Peer Escalation Sentinel (PR2)
+
+**Version / slug:** `a2a-redelivery-escalation`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `self-review (modeled 1:1 on the reviewed CollaborationRedriveEngine; redeliver path covered by a real-outbox wiring-integrity test)`
+
+## Summary of the change
+
+Adds the active-recovery layer of "communications never just die out"
+(A2A-DURABLE-DELIVERY-SPEC §4, issue #939, CMT-1143, PR2 — building on PR1's
+`A2ADeliveryTracker`, shipped in v1.3.386). `src/monitoring/A2ARedeliverySentinel.ts`
+sweeps the tracker's `findOverdue` work-list on a cadence: re-sends each overdue
+(unacknowledged) message under the attempt cap with exponential backoff, and once
+attempts are exhausted raises ONE aggregated attention item per dark peer. Wired in
+`server.ts` (mirroring the `CollaborationRedriveEngine` block) with a `redeliver` fn
+that recovers the message body from the canonical outbox (new
+`ListenerSessionManager.readCanonicalOutboxEntry`) and re-emits via the relay client,
+and `raiseAttention` → `TelegramAdapter.createAttentionItem`. New config
+`monitoring.a2aRedelivery` (ships OFF). Files: `src/monitoring/A2ARedeliverySentinel.ts`,
+`src/threadline/ListenerSessionManager.ts`, `src/commands/server.ts`, `src/core/types.ts`,
++ 2 test files + docs.
+
+Scope note: this PR ships §4 (redelivery + escalation sentinel). The explicit
+`a2a-ack` control message (spec §3 "Layer B") remains a follow-on — the implicit
+ack-via-reply (PR1) plus this sentinel's redelivery+escalation already cover the
+no-reply case, so the explicit control message is a lower-priority optimization. <!-- tracked: #939 -->
+
+## Decision-point inventory
+
+- `A2ARedeliverySentinel` — add — a SIGNAL CONSUMER: it re-sends (via the relay) and
+  escalates (via the Attention queue). It holds NO blocking authority — never gates a
+  send or receive. Escalate-once is structural (markEscalated removes a row from
+  `findOverdue`).
+- `readCanonicalOutboxEntry` — add — pure read helper (no decision surface).
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The sentinel only re-attempts and
+escalates; it cannot reject anything.
+
+## 2. Under-block
+
+No block/allow surface. Coverage note: redelivery counts an attempt whether or not the
+transport "accepted" (an accepted send still isn't an ack), so the retry clock always
+advances toward escalation — a perpetually-accepted-but-never-acked message still
+escalates rather than retrying forever.
+
+## 3. Level-of-abstraction fit
+
+Correct. A signal CONSUMER of the PR1 tracker's `findOverdue`, feeding existing
+surfaces (relay client, Attention queue) — it re-implements neither. Modeled on the
+reviewed `CollaborationRedriveEngine` (same injected-deps, per-tick caps,
+setInterval+unref, ship-OFF shape). The message body is recovered from the existing
+canonical outbox (not duplicated into the tracker).
+
+## 4. Signal vs authority compliance
+
+- [x] No — this change produces re-sends + an aggregated signal (attention item); it
+  holds no block/allow authority. Brittle-free: all logic is deterministic state
+  transitions over the durable tracker.
+
+## 5. Interactions
+
+- **Shadowing:** none. The sentinel runs on its own interval, independent of the
+  send/receive paths.
+- **Double-fire:** escalate-once is structural (`markEscalated` → row leaves
+  `findOverdue`); a redelivered message stays `awaiting-ack` and is naturally re-acked
+  by the peer's reply (PR1 implicit-ack) or re-swept. `maxRedrivesPerTick` caps load on
+  a degraded relay. The implicit-ack-via-reply (PR1) and this sentinel cooperate: a
+  reply acks-by-thread and removes the message from `findOverdue`, stopping redelivery.
+- **Races:** the tracker is SQLite (WAL); the sentinel reads/writes rows independently.
+  The outbox reader is read-only.
+- **Feedback loops:** none — a re-send does not itself create a new tracked message
+  (recordSent is only called on the original relay-send path, not here).
+
+## 6. External surfaces
+
+- **Other agents:** a redelivery re-sends a previously-sent message to the SAME peer on
+  the SAME thread — idempotent at the peer (same messageId via relay). No new message
+  content is invented.
+- **Install base:** new `monitoring.a2aRedelivery` config (OFF by default → no behavior
+  change for existing agents until enabled). New site/README docs.
+- **Persistent state:** none new (uses PR1's SQLite tracker + the existing canonical
+  outbox file). No PostUpdateMigrator step.
+- **Attention queue:** ONE aggregated item per dark peer per escalation (P17-compliant);
+  never one-per-message.
+
+## 7. Rollback cost
+
+Pure additive. Ships OFF (`monitoring.a2aRedelivery.enabled` absent/false → sentinel
+not armed). Back-out = revert the commit + patch. No persistent-state cleanup; no
+user-visible regression (the sentinel is inert until explicitly enabled).
+
+## Conclusion
+
+A signal-consuming recovery sentinel built on PR1's durable tracker, modeled 1:1 on the
+already-reviewed `CollaborationRedriveEngine`, ship-OFF, with the redeliver wiring
+(outbox-body recovery → relay re-send) proven by a real-outbox wiring-integrity test and
+escalate-once guaranteed structurally. The explicit `a2a-ack` control message is the
+only remaining piece of the spec, intentionally deferred as a tracked follow-on.
+
+## Evidence pointers
+
+- Tier 1: `tests/unit/A2ARedeliverySentinel.test.ts` — 8 tests (disabled no-op,
+  redelivery under cap, escalate-once at cap, per-peer aggregation P17, per-tick cap,
+  swallowed transport error, escalate-only mode).
+- Tier 2 wiring-integrity: `tests/integration/a2a-redelivery-wiring.test.ts` — 6 tests
+  (`readCanonicalOutboxEntry` found/absent/newest-wins/malformed-skip; the redeliver
+  path recovers a real outbox body and re-sends; body-missing → escalate, no fabrication).
+- All 14 green; `tsc --noEmit` clean; no-silent-fallbacks 461≤461; docs-coverage green
+  on merge-state (class 134/537, route 104/574).

package/upgrades/1.3.385.md

@@ -1,43 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-Quota-aware placement is meant to route work away from a rate-limited machine.
-But each machine only ever knew its OWN quota: a peer's quota state rides the
-session-status response (the peer's own capacity already includes it), yet the
-receive side parsed it away — the exact same narrowing bug that previously
-dropped the commitments advert (#931). So the router could avoid placing onto a
-rate-limited LOCAL machine but never onto a rate-limited PEER — which is the
-original EXO failure (the laptop placing work onto a rate-limited Mini).
-
-The peer-capacity parse + the PeerPresencePuller now carry `quotaState` through
-to the pool registry. Absent from an older peer = treated as not blocked
-(fail-open, unchanged).
-
-## What to Tell Your User
-
-If one of your machines hits its usage limit, the other machine now actually
-knows and stops sending new work to it — instead of finding out the hard way.
-
-- audience: agent-only
-- maturity: stable
-
-## Summary of New Capabilities
-
-- `PeerCapacity.quotaState` carried from the session-status response through
-  `fetchPeerCapacity` and `PeerPresencePuller` into the pool registry.
-- `GET /pool` now shows a peer's `quotaState`, not just the local machine's.
-- Pairs with finding A1 (the collector that produces the data now runs on
-  lifeline-driven agents).
-
-## Evidence
-
-- `tests/unit/peer-presence-puller.test.ts` (+2): a peer quotaState propagates
-  into the recorded heartbeat; an old peer omitting it records no quotaState
-  (fail-open). 13/13 in file incl. the existing wiring suite.
-- Live (pre-fix, v1.3.384): laptop `/pool` shows its own `quotaState:{blocked:false}`
-  but the Mini's stays `null` after 5+ minutes despite the Mini's `/quota`
-  reading `status:ok`.