instar 1.3.336 → 1.3.338

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/owner-suspect-breaker.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — Owner-Suspect Breaker
+
+**Version / slug:** `owner-suspect-breaker`
+**Date:** `2026-06-06`
+**Author:** `Echo (instar-dev agent, autonomous session per Justin's direction)`
+**Second-pass reviewer:** `adversarial reviewer subagent — OBJECT on probe 1 (forever-suspect under load), CONFIRMED BY REPRODUCTION and fixed in-review (absolute per-episode TTL + regression test); probes 2–5 CONCUR`
+
+## Summary of the change
+
+Wires the SessionRouter's previously-inert `markOwnerSuspect` hook into a real per-peer circuit: `OwnerSuspectBreaker` (pure core; absolute-TTL half-open windows, default 30s; per-peer `FailureEpisodeLatch` for first-log/one-signal/recovery accounting; state deleted on success). Wiring composes `!isSuspect` into `isMachineAlive`, filters suspect machines from placement candidates (all-suspect → unfiltered fallback), and the new `onOwnerResponsive` router dep closes windows on any delivery ack. Plus the router `chains`-map leak fix (entries deleted when their tail settles while current). Files: `OwnerSuspectBreaker.ts` (new), `SessionRouter.ts` (two small additions), `server.ts` wiring block, tests.
+
+## Decision-point inventory
+
+- `isMachineAlive` composition — **modify** — a suspect peer reads as not-alive for ROUTING, sending its sessions down the EXISTING failover re-place path. The decision of where they land is unchanged (placement); the decision of when a peer is suspect is new (retry exhaustion, the signal the router already emitted).
+- Placement candidate filter — **modify** — suspect machines excluded unless that empties the set.
+- `OwnerSuspectBreaker` — **add** — per-peer state machine consuming the router's existing exhaustion signal.
+- `chains` cleanup + `onOwnerResponsive` — **add (hygiene/signal)**.
+
+## 1. Over-block
+
+The reviewer's probe-1 OBJECT was exactly an over-block: with window-extension semantics, a steady <TTL message stream re-marked a suspect peer on every dispatch (no delivery is attempted while suspect → `recordSuccess` unreachable → TTL the only exit → extended forever). Reproduced: a peer healthy from t=40s stayed suspect at t=10min with 31 forced failovers. **Fixed in-review**: `markSuspect` no longer extends an open window (absolute per-episode TTL) — half-open is reached on schedule regardless of traffic, regression-tested. Residual over-block: a genuinely-healthy peer that failed one message's retries pays one 30s window — bounded, and any successful delivery (e.g. a different session's forward in the half-open probe) clears it instantly.
+
+## 2. Under-block
+
+(a) Suspect-window message POLICY is deliberately out of scope: messages still take the existing re-place path (the only message-preserving path while `queueMessage` is a production no-op). The queue-vs-replace stability trade — and the durable-queue investment it requires — is an operator decision; lettered options go to Justin <!-- tracked: CMT-1109 -->. (b) The no-op `queueMessage` also affects the `placing/transferring` branch (pre-existing; surfaced in the options message). (c) `spawnOnMachine` remains un-breakered (reviewer probe 3: deliberate — the all-suspect fallback depends on it attempting, and it throws-to-caller on failure).
+
+## 3. Level-of-abstraction fit / 4. Signal vs authority
+
+The breaker consumes the router's OWN exhaustion signal and feeds the router's OWN aliveness dep — no new decision-maker, no second routing brain; placement, CAS, and ownership semantics untouched. Per `docs/signal-vs-authority.md`: the suspect window is a routing-availability signal with bounded lifetime; the failover authority it triggers is the pre-existing path. Composition lives in the wiring (the router stays pure/dep-shaped).
+
+## 5. Interactions
+
+- **Swap count ("fewer swaps" directive):** unchanged — a session moves at most once per peer-down episode; the breaker removes the OTHER sessions' retry tax, not adds moves (reviewer probe 1 trace, post-fix).
+- **Pins:** a HARD-pinned session does not migrate during a suspect window (placement returns `hard-pin-unavailable`; resolves in place after the TTL — reviewer probe 2).
+- **All-suspect fallback:** placement proceeds unfiltered; `spawnOnMachine` is not `isMachineAlive`-gated so it attempts and throws-to-caller — no wedge (probe 3).
+- **Stale-ownership acks** close the window — correct: the breaker measures transport health to the peer, which any ack proves (probe 4).
+- **Chains cleanup race:** identity-check guard preserves per-session serialization under concurrent re-route; traced clean (probe 5).
+- **Sustained-suspicion signal:** one DegradationReporter record per 10min episode per peer (`SessionPool.ownerDelivery`); reporter's internal cooldown bounds user-facing volume.
+
+## 6. External surfaces / 7. Rollback
+
+Logs + degradation records only; no API/schema/config/persistent state; no migration. Rollback = revert (the wiring block removal restores the inert-hook status quo; the leak and retry-tax return).
+
+## Conclusion
+
+The audit's vaguest lead ("load-shedding") resolved into the sharpest finding of the night: a fully-designed breaker hook shipped dead at the wiring layer. The fix is composition, not invention — and the adversarial pass caught a genuine inversion (the busier a recovered peer, the longer it stayed exiled) before it ever ran. Policy beyond the existing semantics goes to the operator, as it should.
+
+---
+
+## Phase 5 — Second-pass review (routing authority → required)
+
+The adversarial reviewer ran six probes at line level with live reproduction: (1) forever-suspect under steady traffic — OBJECT, reproduced (peer healthy at t=40s still suspect at t=10min, 31 forced failovers), fixed in-review (absolute per-episode TTL in `markSuspect`) + regression test; (2) swap-count + pin behavior — no added moves; pinned sessions hold through windows; (3) all-suspect fallback — cannot wedge (`spawnOnMachine` un-gated, throws-to-caller); (4) stale-ack window-clearing — semantically correct for a transport-health breaker; (5) chains-cleanup serialization — identity guard traced clean; (6) ran breaker/router unit + dispatch integration + session-pool e2e suites and tsc — all green. **Verdict: CONCUR with the applied fix.**