instar 1.3.79 → 1.3.81

package/upgrades/side-effects/mentor-stagea-full-exchange-surface.md

@@ -0,0 +1,90 @@
+# Side-Effects Review — Mentor Stage-A full exchange surface
+
+**Version / slug:** `mentor-stagea-full-exchange-surface`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `Justin review requested in PR`
+
+## Summary of the change
+
+This change completes the mentor Stage-A conversation surface by logging mentor-sent prompt content after successful delivery and interleaving those turns with mentee replies. `src/monitoring/MentorStageA.ts` adds `MentorSentLine`, `parseMentorSent`, and timestamp interleaving in the pure `buildConversationSurface` function. `src/server/AgentServer.ts` appends successful mentor sends to `mentor-sent.jsonl`, reads that log for `getSurface`, and continues reading mentee replies from `mentor-replies.jsonl`. `tests/unit/MentorStageA.test.ts` covers the new parser and the interleave boundary.
+
+## Decision-point inventory
+
+- `MentorStageA.buildConversationSurface` — modify — determines what user-visible conversation Stage A sees.
+- `AgentServer.deliverToMentee` — modify — writes mentor-sent prompt content only after delivery succeeds.
+- `AgentServer.getSurface` wiring — modify — feeds parsed mentor-sent turns plus parsed mentee-reply turns into the pure surface builder.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The parsers drop malformed or empty log rows, but that only removes unusable history from Stage-A context; it does not reject user input, messages, or actions.
+
+---
+
+## 2. Under-block
+
+The main remaining miss is a send that succeeds but crashes before the append finishes. In that case the next surface may still lack the mentor-side prompt. The append is intentionally best-effort and non-fatal so delivery is not turned into a filesystem-dependent operation. Rows without timestamps or text are skipped rather than guessed.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The pure parser and interleave logic belong in `MentorStageA.ts`, which already owns the Stage-A boundary and has focused unit tests. File I/O belongs in `AgentServer`, which already reads the reply log and owns delivery. The change uses the existing a2a transport and outstanding prompt tracker rather than adding a second delivery path.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context (LLM-backed with recent history or equivalent).
+- [ ] Yes, with brittle logic — STOP. Reshape the design. Brittle detectors must not own block authority.
+
+This change expands the data surface visible to Stage A with mentor-owned, user-visible conversation text. It does not add a new blocker, filter, or authority.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The sent-log parser does not replace the reply parser. Both feed the same pure surface builder.
+- **Double-fire:** The sent log is independent from the metadata-only a2a sent ledger. It is intentionally content-bearing because the existing ledger cannot provide prompt text.
+- **Races:** Delivery can succeed while appending the sent row fails. The next surface loses that mentor-side turn, but no transport or reply tracking is broken.
+- **Feedback loops:** Logging occurs only after `deliverA2aMessage` returns true. Failed sends do not create fake conversation history.
+
+---
+
+## 6. External surfaces
+
+The new external surface is a local state JSONL file containing mentor prompt content. It stays under the agent state directory and is not published or sent elsewhere by this change. Stage-A prompt content changes because it can now include both sides of the mentor exchange. The a2a wire format, Telegram behavior, scheduling policy, and reply capture remain unchanged.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a hot-fix release that reverts the MentorStageA, AgentServer, and test changes. The JSONL file can remain on disk; older versions ignore it. No database migration or agent state repair is required.
+
+---
+
+## Conclusion
+
+The change closes the half-history limitation without weakening the two-hats boundary. Stage A still receives only user-visible conversation and the mentor's own agenda, but now that visible conversation includes both mentor prompts and mentee replies. Clear to ship for PR review.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** Justin review requested in PR
+**Independent read of the artifact: pending external review**
+
+This changes a mentor information-flow surface, so the PR is intentionally opened for Justin review before merge.
+
+---
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/MentorStageA.test.ts`
+- `npm run lint`

package/upgrades/side-effects/tokenledger-503-alive-regression.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — TokenLedger 503 Alive Regression Guard
+
+**Version / slug:** `tokenledger-503-alive-regression`
+**Date:** `2026-05-29`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds an integration regression test for the TokenLedger 503 recovery paths and a narrow TokenLedger constructor seam used only by tests. The test seeds an old pre-attribution SQLite database, opens it through the real ledger, wires the real token route, and verifies `/tokens/summary` returns HTTP 200 with data. It also simulates a prior successful native sqlite heal by another subsystem and proves TokenLedger retries open cheaply and the route remains alive.
+
+## Decision-point inventory
+
+No runtime decision point is added or modified. The existing route decision of returning 503 when no ledger is configured is unchanged. The added constructor seam only changes how tests inject a database opener.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The test does not cover every TokenLedger route; it targets the summary route because that is the smallest alive signal for the two known 503 causes.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The test sits at the integration layer because the failure was endpoint unavailability, not only an internal helper result. The constructor seam is lower-level and narrowly scoped to the SQLite open boundary, which is the only place the native heal timing can be simulated without mutating installed dependencies.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+The change does not add a detector or an authority. It adds coverage for existing recovery behavior and one dependency injection seam.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** No existing route behavior is shadowed. The route still checks for a configured ledger before reading summaries.
+- **Double-fire:** The native-heal test asserts the opposite of double-fire: the simulated prior rebuild is consumed once, and TokenLedger does not start a second rebuild.
+- **Races:** Temporary databases are per-test files. The NativeModuleHealer singleton is reset after each test.
+- **Feedback loops:** None identified. The test does not feed production telemetry or persisted agent state.
+
+---
+
+## 6. External surfaces
+
+No user-facing API shape changes. The only production type-surface change is the optional `databaseFactory` field on `TokenLedgerOptions`, which existing callers do not pass. Persistent state behavior is unchanged except that the test verifies the existing schema migration writes the missing column.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal revert. No production migration is added by this change. If the seam proved undesirable, removing it would only require deleting the integration test or replacing the injection strategy.
+
+---
+
+## Conclusion
+
+The change is clear to ship. It strengthens coverage at the level where the regression was visible while keeping production behavior unchanged.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** `not required`
+**Independent read of the artifact:** `not required`
+
+---
+
+## Evidence pointers
+
+- `tests/integration/tokens-503-regression.test.ts`