instar 1.3.237 → 1.3.239

package/upgrades/side-effects/mentor-tick-cycle-capture.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — Mentor tick keystone cycle capture
+
+**Slug:** `mentor-tick-cycle-capture` · **Date:** `2026-06-04` · **Author:** `echo`
+**Second-pass reviewer:** `not required` (additive, opt-in, no-op by default)
+
+## Summary
+
+`runMentorTick` now (after the existing per-finding ledger capture) records a
+`mentor-mentee-differential` apprenticeship CYCLE via an injected, optional
+`recordCycle`. The host (`AgentServer.buildMentorRunner`) wires it to the
+ApprenticeshipCycleStore ONLY when `mentor.apprenticeshipInstanceId` is set, so it
+is a no-op by default. The mentee's transcript is the cycle's menteeOutput; the
+forensics findings (mapped to titles) are the differential.
+
+## Decision-point inventory
+
+One new branch: record a cycle iff `recordCycle` is wired AND the transcript is
+non-empty. Both sides covered (records on a real tick; skips on empty transcript;
+no-op when unwired).
+
+## 1. Over-block
+
+Rejects nothing real. The transcript guard skips an empty/failed Stage A (not a
+cycle) — intended. Without `apprenticeshipInstanceId`, no cycle is recorded
+(back-compat); the existing finding-capture path is unchanged.
+
+## 2. Under-block
+
+It records ALL of a tick's findings as the differential without de-duping against
+prior cycles (acceptable — each tick is a distinct cycle). The cycle's `task` is a
+generic per-tick descriptor, not the full Stage-A prompt (kept terse on purpose).
+cycleNumber is computed as max-existing+1 (single-writer mentor tick, no race).
+
+## 3. Level-of-abstraction fit
+
+Right layer: the pure tick gets an injected callback (no store dependency in the
+pure core); the store wiring + instance resolution live in `buildMentorRunner`
+beside the existing `capture` wiring, reading the cycle store lazily to dodge the
+boot-order (buildMentorRunner runs before the store is constructed).

package/upgrades/side-effects/parallel-activity-coherence.md

@@ -40,6 +40,15 @@ ParallelWorkSentinel is Phase B (ships dark), a separate PR.
   gates/mutates). 6 tests. The cadence + lease-gating + server wiring + config (ships dark) +
   the nudge→Telegram/sentinel-events routing are the remaining wiring on this branch.
 
+## Phase B wiring (the on-switch)
+- `src/config/ConfigDefaults.ts` — `monitoring.parallelWorkSentinel: { enabled: false }` — ships
+  DARK (false-positive nudge worse than silence; graduate after proven quiet). Add-missing-only
+  via applyDefaults ⇒ free migration; never a destructive sub-flag default.
+- `src/core/types.ts` — `MonitoringConfig.parallelWorkSentinel?: { enabled, cadenceMinutes? }`.
+- `src/server/AgentServer.ts` — when enabled, construct `ParallelWorkSentinel` over the index in
+  its OWN try/catch (cascade isolation), tick on an unref'd cadence (default 15min), audit each
+  transition to `logs/sentinel-events.jsonl`; cleared on `stop()`. Signal-only.
+
 ## Decision-point inventory
 - `ParallelActivityIndex` read aggregation — **add** — pure read over existing state; no
   block/allow surface, no mutation.

package/upgrades/side-effects/threadline-a2a-live-inject.md

@@ -0,0 +1,60 @@
+# Side-Effects Review — Threadline A2A live-inject (keep resume entry when session alive)
+
+**Version / slug:** `threadline-a2a-live-inject`
+**Date:** `2026-06-04`
+**Author:** `Echo (instar dev agent)`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+`ThreadResumeMap.get()` is the lookup `ThreadlineRouter.handleInboundMessage` uses to decide whether an inbound A2A message injects into a live session, resumes with history, or cold-spawns. Its resume guard nulled the entire entry whenever the session JSONL transcript was absent (`!jsonlExists(uuid)`), for any non-topic-bound, non-pinned thread. Because relay/pipe-spawned A2A sessions never get their placeholder uuid upgraded to a real transcript id, the guard nulled every peer-to-peer thread entry — discarding the still-valid live `sessionName` along with the placeholder uuid — so every follow-up cold-spawned a memoryless session (the production continuity break proven by the live Echo↔Dawn round-trip: 2 Spawned / 0 Resumed). The fix has two parts. **(1)** `get()` adds one branch: when the transcript is absent, return the entry anyway IF its tmux session is currently alive (new protected `sessionAlive()`, exact-match `tmux has-session -t =name`), so the existing `tryInjectIntoLiveSession`/`resumeThread` path can deliver into / resume the running session. **(2)** Part 1 was a no-op without the real session name: `spawnNewThread` persisted `spawnResult.tmuxSession` as the entry's `sessionName`, but the `spawnSession` callback returned only the bare instar session id, so `tmuxSession` was always undefined and a useless fallback name (`thread-<id8>`) was stored — which `sessionAlive()` and `onSessionComplete`'s `getBySessionName` could never match. The `spawnSession` callback contract now returns `string | { sessionId, tmuxSession }`; `SpawnRequestManager.evaluate` normalizes both forms and forwards `tmuxSession`; the relay spawn impl returns the real `session.tmuxSession`. Files: `src/threadline/ThreadResumeMap.ts`, `src/messaging/SpawnRequestManager.ts`, `src/commands/server.ts`, `tests/unit/threadline/ThreadResumeMap.test.ts`, `tests/unit/threadline-fixes.test.ts`, `tests/integration/threadline-live-inject-real-tmux.test.ts`.
+
+## Decision-point inventory
+
+- `ThreadResumeMap.get()` resume guard (`src/threadline/ThreadResumeMap.ts`) — **modify** — when transcript absent, keep the entry if its session is alive (was: always null).
+- `ThreadResumeMap.sessionAlive()` — **add** — protected tmux-liveness helper; only consulted on the transcript-absent branch.
+- `SpawnRequestManager.spawnSession` callback contract (`src/messaging/SpawnRequestManager.ts`) — **modify** — return type widened to `string | { sessionId, tmuxSession }` (back-compatible); `evaluate` normalizes + forwards `tmuxSession`.
+- Relay `spawnSession` impl (`src/commands/server.ts`) — **modify** — returns `{ sessionId, tmuxSession }` so the real tmux name reaches the resume entry.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None — the change only *widens* what `get()` returns; it never rejects anything it previously accepted. The healthy path (real transcript exists) short-circuits before the new branch (verified by the "does NOT consult liveness when a real JSONL exists" test), so well-formed resume entries behave exactly as before. No new rejection surface.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The idle-gap case: when an A2A session has fully exited AND no real transcript was captured, `get()` still returns null → cold-spawn with no history. This is unchanged by this slice and is the next slice (capture the real transcript id / resume-with-history for dead sessions). This change does not regress it; it only fixes the live-session case. Also: a stale `sessionName` whose tmux name was recycled to an unrelated session could in principle be injected into — bounded because A2A session names are unique per spawn (`msg-spawn-<timestamp>`/thread-scoped) and the delivery layer validates the target.
+
+## 3. Level-of-abstraction fit
+
+The fix lives in `ThreadResumeMap.get()` — the single chokepoint every router branch consults — rather than scattering liveness checks across `handleInboundMessage`. The liveness primitive (`tmux has-session -t =name`) matches the existing idiom used at `ThreadResumeMap` line ~305 and `cli.ts`. Correct layer: the storage lookup already owns the transcript-existence guard, so it should own the "but the session is alive" exception too.
+
+## 4. Signal vs authority compliance
+
+Not a gate/authority change. `get()` is a lookup, not an approval surface; this does not create or relax any authority. The trust gates on the inbound path (relay trust tiers, spawn evaluation) are untouched — a thread only has a resume entry because it already passed those gates on first contact.
+
+## 5. Interactions
+
+- `ThreadlineRouter.handleInboundMessage` (line ~554): now reaches `tryInjectIntoLiveSession` for non-topic-bound threads with a live session. That method already fails gracefully (returns null → falls through) if the session is dead, so the race window is safe.
+- `server.ts` pipe-spawn guard (`!threadResumeMap.get(...)`): now correctly skips pipe-spawn when a live session exists — desirable.
+- `isTopicBoundReply` check: unaffected (originTopicId still undefined for these entries).
+- 1511 threadline unit tests pass; tsc clean.
+
+## 6. External surfaces
+
+No new HTTP routes, no config, no migration, no template/CLAUDE.md change. Pure internal routing behavior. No user-facing surface. `sessionAlive()` shells out to `tmux has-session` only on the (rare) transcript-absent branch — bounded subprocess cost, gated behind a failed `jsonlExists`.
+
+## 7. Rollback cost
+
+Trivial — single-file revert of `ThreadResumeMap.get()` + the helper. No state migration, no persisted format change, no external dependency. Behavior reverts to cold-spawn (the prior, known-broken-but-safe state).
+
+## Conclusion
+
+Low-risk, surgical fix that activates already-built inject machinery for the dominant rapid-fire A2A case. The only behavioral change is `get()` returning an entry it previously discarded, strictly when the session is alive. No over-block, no authority surface, trivial rollback. Idle-gap continuity is explicitly out of scope (next slice).
+
+## Second-pass review (if required)
+
+Not required — Tier 1 (30 LOC, single file, risk floor 1).

package/upgrades/threadline-a2a-live-inject.eli16.md

@@ -0,0 +1,30 @@
+# Why agent-to-agent conversations stopped forgetting themselves mid-thread
+
+## The one-sentence version
+When another agent (like Dawn) sent me several messages in a row, every message after the first was being handled by a **brand-new, memoryless copy of me** instead of the one already in the conversation. This fix lets a follow-up message land in the session that's *already talking* — so the conversation stays one coherent thread instead of a crowd of strangers wearing my name.
+
+## Picture it
+Imagine you're on a phone call. You say something, and instead of the person you were talking to answering, a **fresh person who has never heard of you** picks up a new phone and says "Hi, who's this?" Then you add a detail — and *another* stranger picks up. That's what was happening to every agent-to-agent thread: each incoming message spun up a new session that had zero memory of the previous ones.
+
+The machinery to "hand the message to the person already on the call" was **already built** — it just never ran, because of one overly-strict check.
+
+## What changed, precisely
+- Every thread has a saved "resume entry" that remembers which live session is handling it.
+- Before delivering a follow-up, the router looks that entry up. The lookup had a guard: *"only return the entry if a saved transcript file exists on disk."*
+- For agent-to-agent threads, the saved id was a **placeholder** (the real transcript id was never written back — a separate, known gap). So the guard found no transcript and threw the **entire entry away** — including the perfectly-good name of the session that was *still running right then*.
+- With a null entry, the router skipped the "deliver into the live session" path and the "resume with history" path, and **cold-spawned a fresh memoryless session** every single time.
+- The fix has two halves. **(1)** When there's no transcript file, don't discard the entry if its **tmux session is still alive** — hand it back so the follow-up routes into the running session (live-inject, or a resume that carries the full conversation history) instead of cold-spawning. **(2)** The bookkeeping that records *which* session is handling a thread was writing down a **made-up name** instead of the real one (the spawn helper only handed back an internal id, never the actual session name), so step 1 could never find the session. Now the real session name is passed through and recorded — so the liveness check actually matches, and the resume bookkeeping can later attach the real transcript too.
+
+## The safety rails (why this won't break anything)
+1. **Only triggers on the exact broken case** — a non-topic-bound thread whose transcript is missing. The healthy path (real transcript exists) is untouched and never even runs the liveness check.
+2. **Dead session → unchanged.** If the session is gone *and* there's no transcript, it still returns nothing → cold-spawn, exactly like before.
+3. **Topic-bound and pinned threads** keep their existing exemptions — no change.
+4. **The injection path already protects itself.** If the session dies in the split-second between the check and the delivery, the delivery fails gracefully and falls through to a fresh session *with the conversation history in its prompt* — which is still coherent, never a crash.
+5. **Exact session match only** (`=name`) — no fuzzy/prefix matching that could deliver to the wrong session.
+
+## Why it matters
+This is the core of "an Instar agent is one coherent individual." Agent-to-agent collaboration — the foundation the whole feedback-process migration rides on — was silently incoherent: each reply came from an amnesiac. This makes a live thread behave like one continuous mind, which is the bar we set.
+
+---
+
+**Rendered (verified) view:** _set below after creating the tunnel view._