instar 1.3.353 → 1.3.355

package/upgrades/1.3.355.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a false-positive in context-exhaustion detection that could flood a topic with
+duplicate "conversation too long" notices. The detector (`detectContextExhaustion`)
+matched the bare phrase "conversation too long" anywhere in a session's terminal
+output, with no check that it was an actual CLI error versus ordinary content. A
+session that merely discussed the failure mode — or the recovery notice the detector
+itself emits ("Session hit 'conversation too long'…") — re-tripped detection, and
+because the notice text re-enters the pane, one false positive amplified into a flood
+of duplicate notices and spurious respawns on a perfectly healthy session.
+
+The detector now requires the real CLI error framing — the "Press esc twice…" hint or
+an "error during compaction" line — for the bare phrase to count. The bare phrase
+alone is treated as content. Real exhaustion errors always carry that framing, so
+genuine recovery is unaffected; the self-amplifying flood and the content
+false-positive are both eliminated.
+
+## What to Tell Your User
+
+If you ever saw a burst of repeated "conversation too long" messages while your
+session was actually working fine, that was a false alarm — now fixed. Real
+out-of-room recovery still works exactly as before. Nothing for you to do.
+
+## Summary of New Capabilities
+
+- Context-exhaustion detection no longer fires on the phrase appearing as content or
+  in its own recovery notice — it requires the real CLI error framing.
+- Eliminates the self-amplifying "conversation too long" notice flood.
+- No behavior change for genuine context-exhaustion recovery.
+
+## Evidence
+
+- Unit (`tests/unit/context-exhaustion-recovery.test.ts`): real framed error detected;
+  bare phrase rejected; recovery-notice text rejected; agent narration rejected; a
+  mixed pane (narration + real framed error) still detected. 31 passing.
+- Unit (`tests/unit/presence-proxy-context-exhaustion.test.ts`): standby detection on
+  realistic framed snapshots; non-error content not detected. 14 passing.
+- SessionRecovery recovery-behavior tests updated to realistic framed fixtures and
+  still green (recovery still triggers on real exhaustion).
+- Full typecheck clean.

package/upgrades/side-effects/apprenticeship-keystone-dormancy.md

@@ -0,0 +1,62 @@
+# Side-effects review — keystoneBalance dormancy dimension
+
+**Change:** add an orthogonal `dormant` flag (+ `lastKeystoneAgeMs`,
+`dormancyThresholdMs`) to the observe-only `keystoneBalance` block, plus a
+`?keystoneDormancyMs` route knob, template awareness, and a migration.
+
+**Signal vs authority (Phase 1):** This change involves **no decision point**. It
+adds read-only computed fields to an existing observe-only signal. It never gates,
+blocks, filters, or constrains any agent behavior. It is a pure signal-producer —
+the consumer (a human, or a future cadence job) decides what to do with `dormant`.
+`docs/signal-vs-authority.md` compliance: trivially satisfied (no authority held).
+
+1. **Over-block:** N/A — nothing is blocked. The only "false positive" risk is
+   reporting `dormant: true` for a layer that is intentionally idle. That is the
+   correct report (the layer IS dormant); acting on it remains a human/cadence
+   judgment. A future-dated keystone clamps age to 0, so clock skew cannot
+   manufacture false dormancy.
+
+2. **Under-block:** N/A — nothing is blocked. The signal still cannot see a layer
+   that was *never* registered as an instance (the separate fragmentation finding,
+   filed to the framework ledger as `apprenticeship-cycle-instance-no-referential-integrity`,
+   tracked for a follow-up decision). Dormancy is scoped to a single instance's
+   keystone axis by design.
+
+3. **Level-of-abstraction fit:** Correct layer. Dormancy is computed inside
+   `ApprenticeshipCycleStore.computeKeystoneBalance` alongside `starved`, from the
+   same already-tallied timestamps + the store's injectable `now()`. No new store,
+   no cross-store wiring, no new dependency. It belongs exactly where `starved`
+   already lives.
+
+4. **Signal vs authority compliance:** Compliant. Pure signal; zero blocking
+   authority. Both knobs (`?oversightStarvationThreshold`, `?keystoneDormancyMs`)
+   are observe-only tuning, not gates.
+
+5. **Interactions:** `dormant` is orthogonal to `starved` (both can be true; unit
+   test pins this). It does not shadow or get shadowed by `starved`, `driftWarning`,
+   or the §4a direct-shortcut exclusion. The migration interacts with the prior
+   layer-balance migration: the full-line insert fires only when `keystoneBalance`
+   is absent (now appends the dormant-aware shape); the new in-place upgrade fires
+   only when the pre-dormancy shape is present. The two are mutually exclusive and
+   each idempotent (tested).
+
+6. **External surfaces:** The `role-coverage` JSON response gains three fields and
+   the route accepts one new query param — purely additive, no removed/renamed
+   fields. The CLAUDE.md template + migration change what installed agents read
+   (one awareness line). No timing/runtime dependence beyond the store's `now()`,
+   which is injectable and tested with a fixed clock.
+
+7. **Rollback cost:** Trivial. Observe-only and additive — reverting the commit
+   removes the fields with no data migration, no agent-state repair, no hot-fix
+   urgency (nothing depends on `dormant` to function). The CLAUDE.md awareness line
+   is cosmetic and harmless if left.
+
+**Tier:** 1 (observe-only computed fields on an existing endpoint; all three test
+tiers green plus migration-parity tests). Below the risk-floor signal (2, raised
+by the PostUpdateMigrator touch) — acknowledged: the migrator change is the
+established idempotent doc-awareness pattern from #893, not a data migration.
+
+**No deferrals:** the feature ships complete — code, three test tiers, template
+awareness, and migration parity (new + already-migrated agents) all in this commit.
+The separate cycle-instance fragmentation finding is a distinct issue (filed to the
+ledger), not a deferred part of this change.

package/upgrades/side-effects/context-exhaustion-false-positive.md

@@ -0,0 +1,62 @@
+# Side-effects review — context-exhaustion false-positive fix
+
+**Change:** `detectContextExhaustion` (QuotaExhaustionDetector) now requires the
+real CLI error framing ("press esc twice" or "error during compaction") for the
+bare "conversation (is) too long" phrase. The bare phrase as content no longer
+matches.
+
+**Signal vs authority (Phase 1):** This IS a decision point — the detector's verdict
+gates a destructive action (SessionMonitor kills + respawns the session and notifies
+the user). It is a SIGNAL feeding the SessionMonitor authority; this change makes the
+signal correct, it does not add or move authority. The fix narrows a brittle
+substring match that was producing false positives with blocking-equivalent
+consequences (forced respawns + user notices) — exactly the "brittle check with
+real-world authority" failure `docs/signal-vs-authority.md` warns about.
+
+1. **Over-block (false positive — the bug):** FIXED. Before, the bare phrase as
+   content (a session discussing the failure mode, a quoted error, or the recovery
+   notice itself) was flagged as live exhaustion → spurious respawn + user notice,
+   self-amplifying into a flood (RUN-2 2026-06-06, topic 13435, ~27 notices on a
+   healthy session). Now the bare phrase without CLI framing is not matched.
+
+2. **Under-block (could a REAL error now be missed?):** No real loss. Every
+   realistic exhaustion fixture in the unit tests carries the CLI framing ("press
+   esc twice" and/or "error during compaction") — that is how Claude Code actually
+   renders the error. The guard only removes matches that lack any framing, which
+   are content, not live errors. Residual: if a future Claude Code version renders
+   the error WITHOUT the esc hint or compaction line, it would be missed — the frame
+   list is a one-line extension and is documented as the tuning point.
+
+3. **Level-of-abstraction fit:** Correct layer. The fix is in the detector (the pure
+   function that decides), not in SessionMonitor (the actor). One change fixes every
+   consumer (SessionMonitor, PresenceProxy standby). The soft, non-phrase patterns
+   (context limit, token limit) are deliberately left unchanged — they are not the
+   observed bug and gating them risks under-detection; scoped to the live bug, not
+   a hypothetical.
+
+4. **Signal vs authority compliance:** Compliant. Detector stays a signal; the fix
+   reduces its false-positive rate without changing where authority lives.
+
+5. **Interactions:** The same `detectContextExhaustion` feeds SessionMonitor's
+   proactive check and PresenceProxy. Both now benefit. The self-amplification path
+   (recovery notice → pane → re-detect) is closed because the notice lacks CLI
+   framing. classifySessionDeath (the POST-death classifier) shares the bare-phrase
+   pattern but runs on a dead session's final output where the flood/respawn harm
+   does not apply; left as-is to keep this fix scoped to the live false-positive
+   (noted as a known sibling, not a deferral of THIS bug).
+
+6. **External surfaces:** Reduces user-facing noise (fewer false "conversation too
+   long" notices). No API/schema change. Behavior depends on tmux pane content,
+   which is what it already read; no new timing/runtime dependence.
+
+7. **Rollback cost:** Trivial — revert the commit. Pure-function change, no data
+   migration, no state. Worst case on revert is the original false-positive returns.
+
+**Tier:** 1 (a guard added to one pure function + realistic test fixtures; no route,
+no migration, no persistent state). No CLAUDE.md template change: this is an internal
+detector hardening, not a new agent-invocable capability.
+
+**No deferrals:** the fix is complete — detector guard + both-sides unit coverage
+(real-error-detected, bare-phrase-rejected, recovery-notice-rejected, narration-
+rejected, mixed-pane-still-detected) + updated realistic fixtures. classifySessionDeath
+is a distinct surface (post-death), not a withheld part of this fix.

package/upgrades/1.3.353.md

@@ -1,40 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-Wired the merged `TopicOperatorStore` (#904) into the live `AgentServer` and
-exposed it over HTTP (Know Your Principal standard, security-build increment 2b).
-The store is now composed into the server under the `stateDir` guard (fail-safe:
-`null` → routes `503`, never a crash) and reachable via four Bearer-gated routes.
-This is the runtime arm of the operator-binding spec (#897); the store had no
-consumers before this.
-
-## What to Tell Your User
-
-Nothing user-facing changes yet. This is foundation wiring (experimental) for the
-Caroline identity-bleed security fix — it adds routes the system can use but does
-not alter any current conversational behavior. The automatic session-start
-injection of the verified operator is a later increment.
-
-## Summary of New Capabilities
-
-- `GET /topic-operator` — all bound operators (names + uids).
-- `GET /topic-operator/:topicId` — one topic's verified operator (or null).
-- `GET /topic-operator/session-context?topicId=N` — the `<topic-operator>`
-  session-start injection block (`{ present:false }` when unbound).
-- `POST /topic-operator` — bind a topic operator from the AUTHENTICATED sender
-  `{ topicId, platform?, uid (required), displayName? }`; a blank uid is refused
-  `400` (a content name can never become the operator).
-- `CapabilityIndex` entry `topicOperator` (prefix `/topic-operator`).
-
-## Evidence
-
-Verified by 10 Tier-2 integration tests (full HTTP pipeline over a real
-file-backed store, incl. the blank-uid refusal and the store-not-wired `503`
-degradation) and 6 Tier-3 E2E lifecycle tests (feature-alive on the real
-`AgentServer` boot path — `200` not `503` — full bind→read→inject lifecycle,
-durable-write proof, and the over-the-wire blank-uid refusal). Tier-1 unit
-coverage shipped in #904. Clean `tsc --noEmit`.