instar 1.3.57 → 1.3.59

package/upgrades/side-effects/mentor-cycle-smoothness.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — mentor cycle smoothness (capture + busy-gate)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side. The two
+fast-follows from the live round-trip: reply-capture reliability + the
+remote-mentee safe-window.
+
+**Change:** new `src/monitoring/SessionReplyExtractor.ts` (pure extractors) +
+`src/server/AgentServer.ts` (`extractMenteeReplyFromTranscript` helper, wired
+into the mentee handler as transcript-first/tmux-fallback; `isMenteeBusy`
+gates on OutstandingPromptTracker) + unit tests.
+
+## What changed
+1. `extractCodexFinalMessage` / `extractClaudeFinalMessage` — pure, tolerant
+   parsers returning the final assistant prose (null when absent).
+2. `extractMenteeReplyFromTranscript(session, spawnTs)` — codex: newest rollout
+   written ≥ spawn → task_complete.last_agent_message; claude: the
+   `<claudeSessionId>.jsonl` under ~/.claude/projects → last assistant text.
+3. Mentee handler: after the bounded-wait, prefer the transcript reply; keep
+   the existing capture-while-alive tmux read as the only fallback.
+4. `isMenteeBusy`: `!getOrCreateMentorOutstanding().canSendTo(menteeAgent).ok`
+   instead of Echo's local session count.
+
+## The seven questions
+1. **Over-block.** isMenteeBusy now blocks LESS (only when a real prompt is
+   outstanding) — it was over-blocking before (always busy). Correct direction;
+   the anti-ping-pong invariant is preserved (one outstanding prompt per mentee).
+2. **Under-block.** The outstanding-prompt gate still prevents concurrent
+   prompts to the same mentee. Transcript reading is read-only (no new writes).
+3. **Level-of-abstraction fit.** Extractors are pure + isolated; the helper
+   reuses findRecentRolloutFiles (existing). isMenteeBusy reuses the existing
+   tracker. No new infrastructure.
+4. **Signal vs authority.** Extractors are pure signal; the handler decides.
+   isMenteeBusy is a gate input to the existing safe-window decision.
+5. **Interactions.** Reads ~/.codex/sessions + ~/.claude/projects (read-only).
+   Reuses OutstandingPromptTracker (shared with deliverToMentee — consistent
+   semantics). No new shared mutable state.
+6. **External surfaces.** None new. mentor-replies.jsonl now carries clean
+   prose instead of stream JSON (content-quality change, same schema).
+7. **Rollback cost.** Trivial — revert restores tmux-only capture + the local
+   session-count busy check.
+
+## Testing
+10 new unit tests (SessionReplyExtractor) green; mentor-runner + mentor/mentee/
+inbox suites green; tsc clean. Live tick-driven round-trip with clean-prose
+capture verified post-release (the autonomous run's completion criterion).
+
+## Migration parity
+No config keys, no state schema change. Pure code. No PostUpdateMigrator change.

package/upgrades/side-effects/topic-intent-arccheck-wiring.md

@@ -0,0 +1,101 @@
+# Side-effects review — topic-intent ArcCheck wiring (Layer 3)
+
+Spec: `docs/specs/topic-intent-arccheck-wiring.md` (approved by justin 2026-05-28).
+
+## What this change does
+
+Wires the topic-intent ArcCheck (Layer 3) classifier, which existed but was
+never connected. Two dead spots are closed:
+
+1. `createTopicIntentRoutes` was constructed with no classifier, so the
+   `/topic-intent/:topicId/arccheck` route always returned a degrade-open
+   `{fire:false}` verdict.
+2. No production caller invoked ArcCheck on the outbound path, so the agent
+   never got a signal when a draft contradicted a tracked ref.
+
+Live evidence the gap was real: `arccheck_fired = 0` on every topic, including
+topic 13481 (258 turns, 81 refs). The founding drift ("we need a second
+machine" while a SETTLED ref said the mac-mini was already configured) is the
+exact `contradicts-settled` verdict ArcCheck was designed to emit.
+
+## Files changed (in-scope) and their blast radius
+
+- `src/core/TopicIntentArcCheck.ts` — ADD `createArcCheckClassifyFn(intelligence, onDegrade)`.
+  Pure addition mirroring `createLlmExtractFn`. Degrade-safe: returns an empty
+  classification (→ `{fire:false}`) on no-intelligence or throw, so it can
+  never fire a false signal. Subscription transport (`model: 'fast'`,
+  attribution `TopicIntentArcCheck`). No existing export changed.
+
+- `src/server/topicIntentRoutes.ts` — route now accepts an `arcCheck` ArcCheck
+  instance directly; KEEPS the legacy `arcCheckClassify` param (constructs a
+  per-route instance from it) so all pre-existing callers/tests keep working
+  unchanged. Backward-compatible; no behaviour change when neither is passed
+  (still degrade-open).
+
+- `src/server/AgentServer.ts` — ADD optional `topicIntentArcCheck` to
+  `AgentServerOptions` + `RouteContext`; forward it into
+  `createTopicIntentRoutes`. Additive; null/undefined preserves prior behaviour.
+
+- `src/server/routes.ts` — `checkOutboundMessage` now collects an ArcCheck
+  signal in-process (when `options.topicId` and `ctx.topicIntentArcCheck` are
+  both present) under a 200ms hard timeout via `Promise.race`. On timeout or
+  throw the signal is simply omitted — identical fail-skip shape to the
+  existing dedup detector. ArcCheck is SIGNAL-ONLY: it populates
+  `signals.arcCheck`; the MessagingToneGate retains all block authority. No
+  new block path. Delivery is never slowed (concurrent-eligible + bounded).
+
+- `src/core/MessagingToneGate.ts` — ADD `arcCheck` field to `ToneReviewSignals`
+  + render it in `renderSignals`. Only renders when `fire === true`. The gate
+  may fold the rewrite hint into its review; it does NOT gain a new block rule.
+
+- `src/config/ConfigDefaults.ts` + `src/core/types.ts` — ADD
+  `topicIntent.arccheck.enabled` (default `true`). Migration parity: existing
+  agents pick it up via the canonical `applyDefaults` path in
+  `PostUpdateMigrator.migrateConfig` (existence-checked, idempotent). Kill
+  switch: `false` leaves the route mounted but the classifier dark and skips
+  the in-process call.
+
+- `src/commands/server.ts` — construct ONE `ArcCheck` instance (gated on
+  `sharedIntelligence && topicIntent.arccheck.enabled`), reusing the same
+  queued-intelligence transport as the capture loop, declared at outer scope
+  so it reaches the `AgentServer` constructor. Sets
+  `globalThis.__instarTopicIntentArcCheckWired` for the wiring-integrity test.
+
+## Failure modes considered
+
+- **Outbound latency regression** — bounded by the 200ms `Promise.race`
+  timeout; ArcCheck runs concurrent-eligible with other signal collection and
+  is wrapped in try/catch. Worst case: the signal is absent and the gate
+  behaves exactly as today.
+- **False block** — impossible by construction: ArcCheck is signal-only; the
+  tone gate has no new block rule keyed on `signals.arcCheck`.
+- **Cost** — second always-on per-turn LLM path (capture being the first).
+  Bounded by the shared `LlmQueue` background lane + daily cap; degrades to a
+  no-op on cap breach.
+- **Prompt injection** — `buildArcCheckPrompt` renders refs in a structured
+  block; the classifier is conservative-by-prompt and parse-tolerant
+  (`parseArcCheckResponse` returns empty arrays on malformed output).
+
+## Migration parity
+
+Server-side only. One new config default via the canonical defaults path. No
+hook/template/skill/settings change. No `PostUpdateMigrator` surgery beyond the
+config default.
+
+## Rollback
+
+Flip `topicIntent.arccheck.enabled = false` (classifier construction is gated;
+in-process call is skipped). Code rollback: remove the AgentServer wire, the
+classifier creator, and the `signals.arcCheck` channel — everything else
+reverts to inert, as today.
+
+## Tests
+
+- Unit: `createArcCheckClassifyFn` degrade paths + transport attribution
+  (tests/unit/TopicIntent-arccheck.test.ts, +4).
+- Unit: MessagingToneGate renders/omits the ArcCheck signal
+  (tests/unit/MessagingToneGate.test.ts, +2).
+- E2E: mac-mini-drift regression pin + wiring-integrity source guards
+  (tests/e2e/topic-intent-arccheck-lifecycle.test.ts, new, 5 tests).
+- All 7 pre-existing topic-intent test files remain green after the
+  backward-compatible route reshape.