instar 1.3.335 → 1.3.337

package/upgrades/aup-wedge-fresh-api.eli16.md

@@ -0,0 +1,45 @@
+# ELI16 — AUP-Rejection Wedge Signature + Fresh-Respawn API
+
+## What happened
+
+Last night one of my sessions died in a new way. Justin and the session had
+been designing security test scenarios (deliberately-sneaky "try to trick the
+agent" prompts, for the EXO 3.0 test harness). Enough of that content piled up
+in the conversation that the AI provider's safety filter started refusing the
+ENTIRE conversation — every single reply came back "this request appears to
+violate our Usage Policy." Since each reply re-sends the whole conversation,
+every reply failed, forever. From Justin's side it looked like me ignoring him
+for an hour: "✓ Delivered" receipts, no answers.
+
+The watchdog that's supposed to catch dead-but-still-printing sessions (the
+ContextWedgeSentinel) only knew ONE death signature — the "thinking block"
+error from May. This new one sailed right past it. And the only repair lever —
+"restart fresh, do NOT reload the poisoned conversation" — existed solely
+inside the watchdog's own wiring, so fixing it by hand meant editing a state
+file directly.
+
+## What this change does
+
+1. **Teaches the watchdog the second signature.** It now recognizes the
+   policy-rejection loop too, and the audit log says WHICH kind of wedge it
+   caught. Safety detail: one single policy rejection is NOT treated as a
+   wedge — sometimes one message just gets refused and the next works fine,
+   and killing the conversation for that would destroy real state. The loop
+   version always repeats, so we require seeing it more than once.
+
+2. **Adds the repair lever to the API.** `POST /sessions/refresh` now accepts
+   `"fresh": true` — restart this session WITHOUT reloading its conversation.
+   That's the right move whenever a transcript itself is poisoned.
+
+3. **Tells every deployed agent about it.** The CLAUDE.md migration adds the
+   new signature, the API lever, and the prevention rule: keep literal attack
+   payloads in files on disk and reference them by path — never paste them
+   into the conversation itself.
+
+## Why it's safe
+
+Detection alone never kills anything (auto-recovery stays opt-in, unchanged).
+The one-off-vs-loop distinction is tested on both sides with the real pane
+text from the incident. The API param is validated, rate-guarded by the same
+limiter every refresh uses, and reuses the exact internal mode the sentinel
+already exercised in production twice this week.

package/upgrades/side-effects/aup-wedge-fresh-api.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — AUP-Rejection Wedge Signature + Fresh-Respawn API
+
+**Version / slug:** `aup-wedge-fresh-api`
+**Date:** `2026-06-06`
+**Author:** `Echo (instar-dev agent, session-robustness topic per Justin's "work on more robust ways to handle these scenarios")`
+**Second-pass reviewer:** `self-adversarial pass over the one-off-vs-loop boundary (the only place this change could destroy user state)`
+
+## Summary of the change
+
+ContextWedgeSentinel learns a second wedge-signature family — the AUP-rejection
+loop (2026-06-05 EXO incident) — via `classifyWedgeTail()`, which returns the
+matching family for the live tail and tags every event/escalation with `kind`.
+The AUP family requires the signature on >1 line of the capture (the loop
+repeats every turn; a benign one-off rejection appears once). `POST
+/sessions/refresh` forwards a validated `fresh` boolean to
+`SessionRefresh.refreshSession` — the previously-internal-only fresh-mode.
+CLAUDE.md migrator patch teaches deployed agents both additions. Files:
+`ContextWedgeSentinel.ts`, `server.ts` (wiring detail strings), `routes.ts`,
+`PostUpdateMigrator.ts`, spec doc, three test files.
+
+## Decision-point inventory
+
+- AUP tail classification — **add (detector)** — new signal only; same confirm
+  window + same opt-in recovery policy as the existing family.
+- One-line AUP occurrence — **deliberate non-detection** — a benign one-off
+  rejection must never cost a session its conversation; the wedge always
+  repeats, so the second occurrence arrives within one failed turn.
+- `fresh` route param — **add (lever, validated)** — exposes an existing
+  internal mode; same spawnLimiter + SessionRefresh rate-guard as every
+  refresh.
+
+## 1. Over-block
+
+None added. Detection alone never kills anything (autoRecovery ships dark,
+unchanged). The worst over-detection case — a session DISCUSSING the AUP error
+with two quoted copies in its tail — is covered by the same two defenses as the
+thinking-block family (tail gate + 45s no-progress confirm window): a working
+session scrolls the signature out before confirm.
+
+## 2. Under-block
+
+(a) A genuinely-wedged session whose FIRST rejection is the only one on screen
+is not detected until the next inbound message produces the second copy —
+bounded by one message turn; accepted to protect one-off conversations.
+(b) A wedge whose error text the provider rewords escapes both families —
+inherent to signature-based detection; the turn-receipt structural close is
+tracked separately (CMT-1115 follow-up design).
+
+## 3. Level-of-abstraction fit
+
+The family lives inside the existing sentinel (same lifecycle, confirm window,
+recovery, veto integration) rather than a 5th sentinel — the failure shape is
+identical; only the signature differs. `kind` is data on existing events, not
+a new event vocabulary. The route param reuses `RefreshOptions.fresh` which
+SessionRefresh already owned; the route stays a thin validated entry point.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+- [x] No new authority. The detector is a signal; recovery policy (detect-only
+  / dry-run / live) is unchanged and opt-in. The `fresh` param is operator/agent
+  initiative through an already-rate-guarded lever; the route grants no new
+  capability that the sentinel wiring didn't already exercise.
+
+## 5. Interactions
+
+- **SessionReaper veto:** `isRecoveryActive` covers AUP wedges identically
+  (state machine is shared) — the reaper can't kill a session mid-recovery.
+- **Sentinel audit:** `kind` lands in `logs/sentinel-events.jsonl` detail
+  strings; existing consumers parse free-text detail, no schema break.
+- **`fresh` + followUpPrompt:** unchanged interaction — fresh clears the resume
+  entry after the kill persists it; respawner then spawns clean (SessionRefresh
+  ordering, already tested).
+- **Back-compat:** `signatureIsTail()` boolean wrapper preserved — all existing
+  callers/tests pass unmodified (81 green pre-existing + new).
+
+## 6. External surfaces / 7. Rollback
+
+One new accepted body field on an existing authed route (400 on non-boolean);
+response gains `fresh` echo. No schema/config/persistent state; migrator patch
+is append-only + idempotent (marker: 'AUP-rejection wedge'). Rollback = revert;
+the second family goes blind again and fresh-respawn returns to internal-only.

package/upgrades/side-effects/sibling-transport-brakes.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — Sibling-Transport Brakes
+
+**Version / slug:** `sibling-transport-brakes`
+**Date:** `2026-06-06`
+**Author:** `Echo (instar-dev agent, autonomous session per Justin's direction)`
+**Second-pass reviewer:** `focused adversarial reviewer subagent — CONCUR on all four probes (the #874 pattern itself carries tonight's line-level CONCUR)`
+
+## Summary of the change
+
+The #874 brake pattern applied verbatim to the two remaining mesh transports: `HttpLiveTailTransport` and `ReplyMarkerTransport` get `AbortSignal.timeout` (30s default, the #874-corrected sizing above the fleet's 5–40s receiver-stall envelope) on their fetches, and `PeerFailureLogGate` state-change failure logging (live-tail N=360; reply-marker N=50 for reply cadence) replacing per-attempt lines, with non-ok responses now gated-logged. Files: both transports, one test file.
+
+## Decision-point inventory
+
+- Both transports' `broadcast()` — **modify (bounded)** — same requests, same return semantics; failures abort at the timeout instead of hanging; logging gated.
+
+## 1. Over-block / 2. Under-block
+
+(a) A 30s abort can drop a reply-marker a slower wait might have delivered — widening the marker's documented Two-Generals residual. Reviewer-traced: `broadcast()`'s return is void-discarded at its ONLY callsite (fire-and-forget by design); provider redelivery + the dedup gate + git-committed ledger state are the explicit backstops. Pre-accepted, not new risk. (b) Perfectly alternating ok/fail logs one transition pair per cycle — at reply cadence this is bounded and is diagnostic signal for a genuinely unstable peer (reviewer: not a blocker; an across-resets suppressor would mask real instability). (c) A local `encryptFor` throw logs under the peer's key — imprecise label, but the error detail (the real exception message) disambiguates and the operational meaning ("this peer's flush did not deliver") is identical. (d) Remaining audit item is the SessionRouter design <!-- tracked: CMT-1109 -->.
+
+## 3. Level-of-abstraction fit / 4. Signal vs authority
+
+Brakes in the transports that generate the cost; cadence stays with callers; reuses the canonical gate class rather than re-implementing. **Signal-only** per `docs/signal-vs-authority.md`: log shaping + failure-timing bounds. Critically verified: neither transport feeds lease renewal/suspend (`.isReachable()`'s only src consumer is `LeaseCoordinator` via the LEASE transport) — the #874 reviewer's false-self-suspend concern structurally cannot apply here.
+
+## 5. Interactions
+
+- **Exactly-once (the marker's job):** unchanged — the timeout affects only the best-effort fast path; the dedup gate and ledger sync carry correctness (reviewer probe 1).
+- **#867's per-topic backoff:** composes — backoff bounds live-tail attempt RATE per topic; the gate bounds LOG volume per peer across topics.
+- **Old format pins:** none — pre-existing transport suites pass untouched.
+- **Node engines / AbortSignal-vs-test-clocks:** identical to #874 (verified there; same package.json).
+
+## 6. External surfaces / 7. Rollback
+
+Logs only; no API/schema/config/persistent state; no migration (in-code defaults). Rollback = revert; the hang exposure and per-attempt logging return.
+
+## Conclusion
+
+Completes the mesh-transport brake set: all four cross-machine wires (lease #874, heartbeat #881, live-tail and reply-marker here) now carry P19's brakes. Mechanical extension of a twice-validated pattern, with the one novel risk (marker-drop under timeout) traced to a documented, backstopped design acceptance.
+
+---
+
+## Phase 5 — Second-pass review (cross-machine exactly-once adjacency → performed)
+
+A focused adversarial pass probed only what is novel beyond #874's reviewed pattern: (1) the Two-Generals widening from a 30s marker abort — traced `broadcast()`'s only callsite (void-discarded, fire-and-forget, comment-documented backstops): pre-accepted by design; (2) gate key granularity + alternating ok/fail behavior — peer-bounded memory, transition chatter acceptable-and-diagnostic at reply cadence; (3) local `encryptFor` throws misattributed to the peer — disambiguated by the error detail, operationally equivalent; (4) ran the new + pre-existing transport suites (15/15) and tsc (clean). **Verdict: CONCUR.**