instar 1.3.239 → 1.3.241

package/upgrades/1.3.241.md

@@ -0,0 +1,92 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Enforces the dogfooded-channel standard (APPRENTICESHIP-PROGRAM-PROJECT-DESIGN §4a) in
+code. Every `ApprenticeshipCycleStore` record now carries a `channel`
+(`telegram-playwright` | `threadline-backup` | `direct-shortcut` | `unknown`), with an
+idempotent migration for existing DBs. `roleCoverage` now counts a
+`mentor-mentee-differential` cycle toward the keystone axis **only** when it did NOT run
+through a `direct-shortcut` — a shortcut cycle is still recorded (for honesty, surfaced via
+the new `shortcutDifferentialCount`) but can never make the keystone look healthy. Unset /
+pre-field channels are grandfathered as `unknown` and still count, so an already-earned
+keystone is never retroactively un-fired.
+
+Adds a structural dedup at the Telegram→session delivery chokepoint
+(`SessionManager.injectTelegramMessage`). A given Telegram `messageId` now reaches a
+session at most once: the method keeps a small per-`(session, messageId)` ledger (pruned on
+a 10-minute window) and, on a repeat, suppresses the re-injection and logs it instead of
+delivering the same user message again. `messageId` is threaded in from both delivery paths
+— the `/internal/telegram-forward` route (lifeline → server) and the in-process
+`telegram→session` path. Callers that carry no positive `messageId` are unaffected (no
+dedup), preserving back-compat.
+
+This closes an observed bug where a single user message was forwarded to a codex session
+five times over ~50s (upstream re-forward while the session was starting), making the agent
+queue and re-process the same task repeatedly. The suppression is logged so the upstream
+over-forward stays visible for a separate root-cause.
+
+Path 1 of the Threadline A2A continuity fix. Headless one-shot `claude -p` reply
+sessions never report their session id, so the resume entry kept a placeholder
+uuid and every spaced follow-up cold-spawned (a live Echo↔Dawn round-trip proved
+Resumed=0 even after the prior foundation shipped).
+
+Fix: `ThreadlineRouter.spawnNewThread` now mints a uuid and launches the reply
+session with `claude --session-id <uuid>` (so its transcript is created at exactly
+`<uuid>.jsonl`), persisting that uuid as the thread's resume handle.
+`resumeThread` launches the follow-up with `claude --resume <uuid>` — reloading
+the full prior transcript — and sends only the new message + grounding (the
+transcript already holds the history, so re-injecting it is dropped). The
+`sessionId`/`resumeSessionId` options are threaded through
+`SessionManager.spawnSession` (spliced as `--session-id`/`--resume` into the
+claude-code headless argv before `-p`, mutually exclusive, gated on framework) and
+`SpawnRequestManager`. Additive + gated: every non-A2A spawn is unchanged when the
+options are absent; the stale-uuid resume-crash guard falls back to a fresh spawn.
+
+## What to Tell Your User
+
+Nothing user-facing changes. Internally, the apprenticeship now records which channel each
+mentor↔mentee cycle ran through and structurally refuses to let a CLI/API shortcut count as
+real keystone progress — so "is the real mentorship happening?" can't be faked.
+
+Nothing user-facing changes in how you talk to your agent. Under the hood, if a single
+message you send ever got relayed to the agent more than once (a rare hiccup when the agent
+was just starting up), the agent now notices and acts on it only once — so it won't
+double-work a request or burn extra model usage repeating itself. A note is written to the
+log each time a duplicate is caught, so the underlying relay glitch can still be chased down.
+
+When another agent and I have a back-and-forth, I now stay in the same
+conversation across messages instead of forgetting between each one — so the
+realistic turn-based exchange (which the upcoming agent-to-agent feedback work
+relies on) holds its thread. It's an internal robustness fix; nothing to turn on.
+The rapid-fire 3-messages-in-10-seconds case is smoothed by a separate follow-up.
+
+## Summary of New Capabilities
+
+- **Turn-based agent-to-agent continuity:** a peer agent's follow-up message now resumes the SAME conversation (full prior context) instead of cold-spawning a memoryless reply session.
+
+## Evidence
+
+Verified on this machine, before/after.
+
+**Mechanism (directly verified, 2026-06-04):** `claude --session-id
+a6b1c2d3-…-0002 -p "remember BANANA77"` created the transcript at exactly
+`<that-uuid>.jsonl` (29 lines). `claude --resume <that-uuid> -p "what was the
+secret word?"` grew the SAME transcript to 55 lines and the planted word
+`BANANA77` appears in the resumed transcript (6×) — i.e. `--resume` reloaded the
+full prior conversation. So set-then-resume by a known id gives real continuity.
+
+**Before (live A6 round-trip, `echo-dawn-A6-verify-…`, server on v1.3.239):**
+2× `[relay] Spawned session`, 0× `Resumed`; `onSessionComplete` fired + matched
+the thread ("demoted 1 thread(s)") but `claudeSessionId` POST events = 0, so the
+placeholder uuid was never upgraded → `jsonlExists` failed → cold-spawn.
+
+**After (unit):** spawning with `sessionId` emits `--session-id <uuid>` before
+`-p`; with `resumeSessionId` emits `--resume <uuid>`; neither when absent.
+`spawnNewThread` persists the minted uuid as the entry uuid (not a placeholder);
+`resumeThread` forwards `resumeSessionId = entry.uuid`. tsc clean; 1548
+threadline/fixes/continuity tests green. The live Dawn round-trip showing
+`Resumed` (not `Spawned`) runs post-deploy.

package/upgrades/apprenticeship-channel-enforcement.eli16.md

@@ -0,0 +1,16 @@
+# Enforcing the dogfooded channel — explained simply
+
+The apprenticeship rule (just documented) is: a mentor must drive its mentee through
+the REAL Telegram UX (via Playwright), because experiencing the user experience IS the
+test. A shortcut — calling the mentee's CLI directly — gets an answer but skips the
+thing we're actually testing.
+
+A doc alone is a wish. This makes it a guarantee: every recorded apprenticeship cycle
+now writes down WHICH channel it actually ran through. And the keystone check — the one
+that tells us the real mentor↔mentee work is happening — only counts a cycle if it ran
+through the real channel (Telegram-Playwright, or the backup). A shortcut cycle is still
+saved (so we're honest it happened), but it does NOT light up the keystone. So a shortcut
+can never make the program look healthier than it is.
+
+Older cycles (recorded before this field existed) are grandfathered in — they still
+count, so this never retroactively "un-fires" a keystone we already earned.

package/upgrades/side-effects/apprenticeship-channel-enforcement.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — Apprenticeship dogfooded-channel enforcement
+
+**Slug:** `apprenticeship-channel-enforcement` · **Date:** `2026-06-04` · **Author:** `echo`
+**Second-pass reviewer:** `not required` (additive field + a counting gate; grandfathered)
+
+## Summary
+
+Adds a `channel` field to ApprenticeshipCycleStore records (`telegram-playwright` |
+`threadline-backup` | `direct-shortcut` | `unknown`), an idempotent ALTER-TABLE migration
+for existing DBs (default `unknown`), and a `roleCoverage` gate: a
+`mentor-mentee-differential` cycle on `direct-shortcut` is recorded but does NOT count
+toward the keystone axis (surfaced via a new `shortcutDifferentialCount`). Enforces the
+§4a dogfooded-channel standard in code.
+
+## Decision-point inventory
+
+One new branch in `roleCoverage`: a mentor-mentee-differential cycle is skipped from axis
+tallying iff `channel === 'direct-shortcut'`. Covered both-sides (dogfooded fires; shortcut
+doesn't + increments the counter; grandfathered/backup fire).
+
+## 1. Over-block
+
+Rejects nothing. Garbage/unset channels normalize to `unknown`, which COUNTS (grandfathered)
+— so it never retroactively un-fires an earned keystone (cycle #4, recorded pre-field, holds).
+Only an EXPLICIT `direct-shortcut` is gated, and even then the cycle is still stored + listed.
+
+## 2. Under-block
+
+The mentor tick (#743) records cycles without setting `channel` → they default to `unknown`
+→ count. That is intentionally grandfathered for now; aligning the automated tick to set
+`direct-shortcut` (or to drive via Playwright, the real fix) is the follow-on once Codey's
+Playwright driving capability exists. The gate is per-axis-tally; it does not retro-rewrite
+stored rows.
+
+## 3. Level-of-abstraction fit
+
+Right layer: the enforcement lives in the cycle store's `roleCoverage` (the single place the
+keystone is computed), reusing the existing axis-tally loop. No route/server change — the
+existing `GET /apprenticeship/instances/:id/role-coverage` surfaces the new field for free.

package/upgrades/side-effects/telegram-delivery-dedup.md

@@ -0,0 +1,69 @@
+# Side-Effects Review — Telegram delivery-chokepoint dedup
+
+**Version / slug:** `telegram-delivery-dedup`
+**Date:** `2026-06-03`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`SessionManager.injectTelegramMessage` gains an optional trailing `messageId` param and a
+structural dedup: a `(tmuxSession, messageId)` ledger (pruned on a 10-minute window) ensures
+a given Telegram message reaches a session at most once. A repeat is suppressed (returns
+`true` — already delivered) and logged via `console.warn`. `messageId` is threaded from the
+two delivery callers: the `/internal/telegram-forward` route and the in-process
+`telegram→session` path (derived from `pipeline.id` = `tg-{messageId}`).
+
+## Decision-point inventory
+
+One decision: "have I already delivered this `(session, messageId)` within the window?"
+→ suppress + log, else record + deliver. Gated on `messageId` being a positive number.
+
+## 1. Over-block
+
+**What legitimate inputs does this reject?** Only a re-delivery of the SAME Telegram
+`messageId` to the SAME session within 10 minutes — which is, by definition, a duplicate of
+a message already delivered (Telegram `message_id` is unique per chat; a genuine re-send is a
+NEW id). The first delivery always lands. Distinct messages (distinct ids), messages to
+different sessions, and any caller that supplies no positive `messageId` (e.g. `0`/undefined)
+are never deduped. So no legitimate distinct user message is dropped.
+
+## 2. Under-block
+
+**What does this still miss?** It does not fix the *upstream* cause of the over-forward
+(lifeline re-forward / PendingRelayStore re-drive / sentinel pause+resume) — it is a
+chokepoint backstop. The suppression `console.warn` is deliberately retained so the upstream
+multiplicity remains observable for a follow-up root-cause. It also does not dedupe non-
+Telegram delivery paths (WhatsApp/iMessage inject have their own methods, out of scope).
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. `injectTelegramMessage` is the single server→session delivery
+chokepoint that writes the `/tmp/instar-telegram` file and does the tmux inject; every
+Telegram delivery path funnels through it. Guarding there means the dedup holds regardless of
+which upstream component over-forwards (defense-in-depth, Structure > Willpower). The two
+callers only thread the id through.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+The dedup is an authority (it suppresses a delivery), but a tightly-scoped and conservative
+one: it acts only on an exact `(session, messageId)` duplicate within a short window, and
+returns success (the message WAS delivered on the first call), so callers see no failure. The
+`console.warn` preserves the signal of the upstream over-forward for diagnosis. No user
+message is lost.
+
+## 5. Reversibility / blast radius
+
+Bounded. The ledger is an in-memory `Map` pruned on a 10-minute window (naturally bounded by
+message volume). No persistence, no schema, no config, no migration. If the dedup ever
+misbehaved, the change is a few lines in one method plus two one-line caller edits; reverting
+is trivial. The only behavioral change is "the exact same Telegram message is not injected
+into the same session twice within 10 minutes."
+
+## 6. Test coverage
+
+`tests/unit/session-telegram-inject.test.ts` — both sides of the boundary with realistic
+input: repeat id → suppressed (one file); distinct id → delivered (two files); no id →
+no dedup (two files); id `0` → no dedup; same id to two sessions → both deliver.

package/upgrades/side-effects/threadline-a2a-resume-session-id.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Threadline A2A resume via deterministic session-id
+
+**Version / slug:** `threadline-a2a-resume-session-id`
+**Date:** `2026-06-04`
+**Author:** `Echo (instar dev agent)`
+**Second-pass reviewer:** `not required (Tier 1)`
+
+## Summary of the change
+
+Path 1 of the A2A continuity fix. Headless `claude -p` reply sessions never reported their session id, so `onSessionComplete` left the resume entry's uuid as a placeholder and resume-after-exit cold-spawned. Fix: when `ThreadlineRouter.spawnNewThread` spawns the first reply session it mints a uuid and passes it as `claude --session-id <uuid>` (so the transcript is created at exactly `<uuid>.jsonl`), and persists that uuid as the resume entry. `resumeThread` spawns the follow-up with `claude --resume <uuid>` (reloading the full transcript) and a minimal prompt (new message + grounding only — the transcript already holds history). Threaded through: `SessionManager.spawnSession` (new `sessionId?`/`resumeSessionId?` options → `--session-id`/`--resume` spliced into the claude-code headless argv before `-p`, mutually exclusive, gated on framework), `SpawnRequestManager` (forwards both from `SpawnRequest` → callback), the relay `spawnSession` callback in `server.ts`. Files: `src/core/SessionManager.ts`, `src/messaging/SpawnRequestManager.ts`, `src/commands/server.ts`, `src/threadline/ThreadlineRouter.ts` + tests.
+
+## Decision-point inventory
+
+- `SessionManager.spawnSession` headless argv (`src/core/SessionManager.ts`) — **modify (additive)** — splice `--session-id`/`--resume` when the new options are set; no change when absent.
+- `ThreadlineRouter.spawnNewThread` resume-entry uuid (`src/threadline/ThreadlineRouter.ts`) — **modify** — save the real minted uuid instead of the placeholder.
+- `ThreadlineRouter.resumeThread` prompt + spawn (`src/threadline/ThreadlineRouter.ts`) — **modify** — pass `resumeSessionId` + minimal prompt (drop re-injected history).
+- `SpawnRequest`/`SpawnRequestManager.evaluate` forwarding — **modify (additive)** — carry `sessionId`/`resumeSessionId`.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None — no allow/block surface. The flags only set/resume the conversation id. No message is rejected. When the new options are absent (every non-A2A spawn), behavior is unchanged. "No block/allow surface — over-block not applicable."
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+Rapid-fire (multiple messages while the reply session is still running): `--resume` on a still-busy session, or a fresh spawn hitting the 30s cooldown, is unchanged by this slice — that is the warm-session follow-up. Also: a `--resume` against a transcript that was deleted/rotated falls back to a fresh spawn (handled by the existing stale-uuid guard), losing that thread's history — acceptable + lossless beyond history.
+
+## 3. Level-of-abstraction fit
+
+The uuid is minted + owned by `ThreadlineRouter` (which owns the resume entry) and threaded down to the spawn primitive — the right layering. `SessionManager` only learns "set/resume this id," mirroring its existing `--resume` (triage) and `extraClaudeFlags` patterns.
+
+## 4. Signal vs authority compliance
+
+Not a gate/authority change. No approval surface added or relaxed. Trust gates on the inbound path are untouched.
+
+## 5. Interactions
+
+- Builds on shipped slices 1+2 (router finds the live session + real tmux name). With this, `get()`'s `jsonlExists(uuid)` now passes legitimately (the transcript exists at the minted id) → resume path fires for spaced follow-ups.
+- The relay `spawnSession` callback keeps `codexAllowMcpTools: true` + all MCP/permission flags → the A2A worker still replies via `threadline_send`.
+- 1548 threadline/fixes/continuity unit tests pass; tsc clean. One obsolete test (`includes thread history in resume prompt`) replaced — it asserted the now-removed history-re-injection behavior.
+
+## 6. External surfaces
+
+No new HTTP routes, no config defaults, no template/CLAUDE.md change. Pure internal session-lifecycle behavior. Migration-parity: nothing to migrate (no config/hook/template surface).
+
+## 7. Rollback cost
+
+Low — revert the four source files. No persisted-format change (the resume entry already had a `uuid` field; it now holds a real id instead of a placeholder — old placeholder entries simply fail `jsonlExists` and cold-spawn as before). No external dependency.
+
+## Conclusion
+
+Low-risk, additive, deterministic fix that completes the realistic turn-based A2A continuity case on top of the shipped foundation. The mechanism (`--session-id` set + `--resume` reload) was empirically verified before coding. Rapid-fire smoothness is explicitly out of scope.
+
+## Second-pass review (if required)
+
+Not required — Tier 1 (additive, gated, ~single-concern).

package/upgrades/threadline-a2a-resume-session-id.eli16.md

@@ -0,0 +1,28 @@
+# Why agent-to-agent conversations can now actually remember
+
+## The one-sentence version
+When another agent sends me several messages over a conversation, each of my replies used to run as a throwaway that finished and forgot everything — so the next message met a stranger. Now I give each reply session a **known name tag** when it starts, write that tag down, and on the next message I **re-open the exact same conversation by its tag** — so I pick up right where we left off, with the full history.
+
+## What was broken (proven live)
+A real round-trip with Dawn showed every follow-up still cold-spawned a memoryless session. The deep reason: each reply ran as a headless one-shot Claude that **never reports its own session id back to me**, so when it finished I had no handle to reconnect to. My earlier fix made the router *try* to reconnect, but there was nothing to reconnect to.
+
+## The fix (deterministic, no guessing)
+Claude lets you (a) **set** a session's id when you launch it (`--session-id <uuid>`) and (b) **re-open** a session by that id later (`--resume <uuid>`). I verified both directly: setting an id creates the transcript under that exact id, and resuming it reloads the whole prior conversation (I planted a secret word in turn 1 and the resumed session recalled it).
+
+So now:
+- When a peer's first message spawns a reply session, I **mint a fresh id and pass it as `--session-id`**, then store that id as the thread's resume handle.
+- When the next message arrives, I spawn with **`--resume <that id>`** so the session reloads the full prior transcript and continues — and I send it only the new message (the transcript already holds the history, so re-pasting it would just duplicate it).
+
+## The safety rails
+1. **Additive + off by default.** The new options do nothing unless set. Every other kind of session (jobs, your topic sessions, Codex) is byte-for-byte unchanged.
+2. **Claude-code only, and the two flags are mutually exclusive** — a launch either sets a new id or resumes one, never both.
+3. **A stale id can't wedge me.** If a transcript no longer exists, the existing resume-crash guard falls back to a fresh spawn instead of hanging.
+4. **The reply path is untouched.** Setting/resuming the conversation id doesn't change tools or permissions, so the agent still replies normally over the secure channel.
+5. **Built on the shipped foundation** (the router already finds the live session + carries the real session name); this adds the missing piece — the real, resumable id.
+
+## What it does NOT yet fix
+The *rapid-fire* case (three messages in ten seconds, while the reply is still being written) still isn't smooth — that needs the bigger persistent-session work. This fixes the realistic **turn-based** conversation (you reply, I reply, you reply a minute later), which is exactly what the agent-to-agent feedback migration needs.
+
+---
+
+**Rendered (verified) view:** _set below after creating the tunnel view._