instar 1.3.245 → 1.3.246

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T18:14:33.049Z",
-  "instarVersion": "1.3.245",
+  "generatedAt": "2026-06-04T18:56:49.668Z",
+  "instarVersion": "1.3.246",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -1506,7 +1506,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "d01eb671ddb9e21b1aeef11fb0b79a63db7a088baf94352fce58a3f0a7c4fd60",
+      "contentHash": "4d50cc3ebd4b430069d5957fbed44bdadd487c17386b680f0cafe66a33c381e2",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.3.246.md

@@ -0,0 +1,97 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Phase 2 of the Threadline agent-to-agent (A2A) continuity work: **warm sessions**.
+
+The turn-based fix (#746) made a peer's spaced follow-up *resume* the same
+conversation via `claude --resume`. But rapid-fire bursts (several messages in
+seconds) still cold-spawned, because each A2A reply ran as a throwaway `-p`
+session that answered once and exited — there was nothing alive to hand the next
+message to — and a fresh thread could even hit the 30s per-peer spawn cooldown.
+
+This change keeps the reply session **alive between messages** for a warm-enabled
+peer and **injects** follow-ups into it:
+
+- The first message from a verified, non-topic-bound peer spawns a **persistent
+  interactive** reply session (not a throwaway `-p`), carrying the full grounded
+  prompt as its first turn, and registers it in a new `WarmSessionPool` keyed by
+  threadId (caps: globalCap 3, perPeerCap 1, ttlMs 600000, trustFloor `verified`).
+- The next message on that thread is **injected** into the same live session — no
+  cold-spawn, no cooldown — and refreshes its TTL.
+- A periodic reap tick evicts on TTL/pressure; on eviction the **next message
+  falls back losslessly to the proven `--resume` path (#746)** — nothing is lost.
+
+Three correctness/security fixes ride along, each independently load-bearing:
+
+- **`claude.exe` allowlist fix** — live macOS Claude panes report
+  `pane_current_command = claude.exe`, which the inject allowlist
+  (`ALLOWED_INJECTION_PROCESSES`) did not contain, so A2A live-inject was
+  **dead-on-arrival on macOS**. Added `claude.exe`.
+- **Grounding-on-inject** — injected follow-ups are now wrapped in the same
+  untrusted-data grounding preamble used on spawn/resume (they previously injected
+  the raw envelope body).
+- **Per-thread isolation + peer-conflict guard** — each thread gets its own
+  private session (no shared listener, nothing to leak across peers), and
+  `WarmSessionPool.admit` throws `WarmSessionPeerConflictError` rather than letting
+  a different peer hijack an existing thread's warm session; a pre-spawn `peek`
+  check makes the conflict path fall back to a normal cold-spawn.
+
+Dark-shipped behind `threadline.warmSessionA2A.enabled`, resolved via the
+`developmentAgent` dev-gate (`enabled ?? !!config.developmentAgent`): **live on the
+development agent, dark on the fleet**. With the flag absent and `developmentAgent`
+false, behavior is byte-for-byte the current cold-spawn path.
+
+**Framework-general (not Claude-specific).** The warm worker runs in the LOCAL
+agent's framework (claude-code / codex-cli / gemini-cli / future), not hardcoded
+Claude: the inject allowlist is now DERIVED from a per-framework process-name
+registry (`Record<IntelligenceFramework, …>`), and the warm spawn passes the local
+framework so the right CLI + resume mechanism applies. Enforced by compiler
+exhaustiveness + `tests/unit/framework-agnosticism.test.ts` + a new `/instar-dev`
+precommit gate that requires any launch/inject-abstraction change to state its
+framework generality (standard: **Framework-Agnostic — and Framework-Optimizing**).
+
+## What to Tell Your User
+
+When another agent and I go back and forth quickly, I now keep the same live
+conversation open and type each new message into it — instead of starting a fresh,
+memoryless reply every time. So a rapid exchange holds its thread end-to-end, not
+just the slower turn-by-turn case. It's an internal robustness improvement that
+ships active only on the development agent (dark on everyone else) and falls back
+to the already-shipped resume path if a warm session is ever retired. Nothing to
+turn on.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Warm A2A sessions (keep-alive + inject) | Automatic for verified, non-topic-bound Threadline peers when `threadline.warmSessionA2A.enabled` is on (defaults to the `developmentAgent` flag). Rapid follow-ups inject into the live session instead of cold-spawning. |
+| Tunable warm-session pool | `.instar/config.json` → `threadline.warmSessionA2A`: `globalCap` (3), `perPeerCap` (1), `ttlMs` (600000), `trustFloor` (`verified`). |
+| Lossless eviction fallback | On TTL/pressure eviction, the next message resumes via the `--resume` path (#746) — no continuity lost. |
+
+## Evidence
+
+**The `claude.exe` bug (reproduced in dev):** `ALLOWED_INJECTION_PROCESSES`
+(`src/messaging/types.ts`) listed `claude` but not `claude.exe`. On macOS a live
+Claude pane reports `pane_current_command = claude.exe`, so the inject guard
+`isInjectableProcess()` returned **false for every live A2A reply session** —
+agent-to-agent live-inject was dead-on-arrival on macOS.
+
+- *Before:* the prior live Echo↔Dawn round-trip recorded `2× Spawned, 0× Resumed,
+  1× spawn-denied (cooldown)` on a fresh thread — every follow-up cold-started; the
+  inject path was never reachable because the allowlist check rejected `claude.exe`.
+- *After:* unit test asserts `claude.exe ∈ ALLOWED_INJECTION_PROCESSES`; the
+  integration test "2nd message on a thread with a live warm session → inject (no
+  2nd spawn, no cooldown)" passes — the inject path is now reachable and exercised.
+
+**Test evidence (re-run on top of current main, v1.3.243):** tsc `--noEmit` clean;
+warm-session unit (105) + integration (5: incl. flag-on inject, flag-off
+byte-identical cold-spawn, peer-conflict → cold fallback) + e2e (1: continuity then
+evict → resume via #746) all green; esm / no-empty-catch / no-direct-destructive /
+no-silent-fallbacks gates green (warm fail-opens annotated `@silent-fallback-ok`,
+net silent-fallback count unchanged). The live Echo↔Dawn production round-trip
+("Resumed not Spawned" + rapid inject with no cooldown) is the post-deploy
+standards-met gate, run by the orchestrator after merge.

package/upgrades/side-effects/threadline-warm-session-a2a.md

@@ -0,0 +1,146 @@
+# Side-Effects Review — Threadline Warm-Session A2A Integration
+
+**Version / slug:** `threadline-warm-session-a2a`
+**Date:** `2026-06-04`
+**Author:** `Echo (instar dev agent)`
+**Second-pass reviewer:** `not required (Tier 1 — additive + dark-gated)`
+
+## Summary of the change
+
+Phase 2 of A2A continuity: keep a verified peer's reply session **alive** between
+messages and **inject** follow-ups, instead of cold-spawning each time. The first
+message spawns a persistent **interactive** session (not throwaway `-p`), registered
+in a new `WarmSessionPool` keyed by threadId; subsequent messages inject into the
+live session (no spawn, no 30s cooldown); a reap tick evicts on TTL/pressure; on
+eviction the next message falls back losslessly to the shipped `--resume` path
+(#746). Three correctness/security fixes ride along: `claude.exe` added to the
+inject allowlist (live macOS Claude panes report `claude.exe`, so live-inject was
+dead-on-arrival); grounding-on-inject (wrap injected body in the untrusted-data
+preamble); per-thread isolation + `WarmSessionPeerConflictError` guard.
+
+Dark-shipped behind `threadline.warmSessionA2A.enabled ?? !!config.developmentAgent`.
+Files: `src/messaging/types.ts`, `src/threadline/WarmSessionPool.ts`,
+`src/threadline/ThreadlineRouter.ts`, `src/commands/server.ts`,
+`src/config/ConfigDefaults.ts`, `src/core/types.ts`,
+`src/messaging/SpawnRequestManager.ts`, `src/core/SessionManager.ts`,
+`src/core/frameworkSessionLaunch.ts` + unit/integration/e2e tests.
+
+## Decision-point inventory
+
+- `ALLOWED_INJECTION_PROCESSES` (`src/messaging/types.ts`) — **modify (additive)** — add `claude.exe`. Widens which live panes accept an injected message; only matters for the A2A inject path (Telegram uses a different non-allowlisted path).
+- `WarmSessionPool.admit` (`src/threadline/WarmSessionPool.ts`) — **new** — throws `WarmSessionPeerConflictError` if a different peer owns the thread; caps/TTL/LRU eviction.
+- `ThreadlineRouter.tryInjectIntoLiveSession` (`src/threadline/ThreadlineRouter.ts`) — **modify** — wrap injected body in grounding preamble; `pool.touch` on success.
+- `ThreadlineRouter.handleInboundMessage` new-spawn path — **modify (gated)** — when `preferWarmSession`, request an interactive keep-alive spawn + `pool.admit`; pre-spawn `peek` conflict → cold-spawn fallback.
+- `server.ts` relay decision + `spawnSession` callback + reap tick — **modify (gated)** — resolve `warmEnabled`, construct pool (null when off), branch the spawn callback on `opts.interactive`, periodic `reapExpired` + `killWarmSessionByName`, `.unref()`, cleared on shutdown.
+- `ConfigDefaults` / `ThreadlineConfig` — **new (additive)** — `warmSessionA2A` caps with no `enabled` (resolved via dev-gate).
+- `SessionManager.spawnInteractiveSession` + `frameworkSessionLaunch` — **modify (additive)** — new `sessionId?` option → `--session-id` on the interactive claude launch (mutually exclusive with `--resume`).
+
+## 1. Over-block
+
+The new `WarmSessionPeerConflictError` could *withhold* a warm session from a
+legitimate same-thread message if peerId were computed inconsistently. Mitigation:
+peerId is the same stable sender fingerprint used for the thread's trust/ownership
+checks; same-peer refresh is explicitly tested as allowed. On any conflict the
+message is **not dropped** — it falls back to a normal cold-spawn. So the worst
+"over-block" outcome is "no warm speedup," never "message rejected." The trust
+floor (`verified`) gates *warmth*, not *delivery*: a below-floor peer still gets the
+unchanged cold-spawn reply.
+
+## 2. Under-block
+
+`claude.exe` widens the inject allowlist — could an unintended process now be
+injected into? No: inject is keyed on the pool's own `sessionName` (a session this
+agent spawned + admitted), not a free scan of panes; the allowlist is a
+defense-in-depth process-name check on top of an already-owned session handle. The
+grounding-on-inject wrap closes the prior gap where a peer's raw body reached the
+session without untrusted-data framing. Residual: a malicious *verified* peer can
+still keep one warm session pinned (bounded by perPeerCap 1 + ttl 600s + globalCap
+3) — a resource bound, not a content-leak (per-thread isolation means nothing to
+leak across peers).
+
+## 3. Level-of-abstraction fit
+
+`WarmSessionPool` is a pure registry (no I/O); the router owns the
+spawn/admit/inject/touch decisions; the server owns process construction + the kill
+primitive (`killWarmSessionByName` resolves tmux-name → session-id → kill, because
+`killSession` keys by session id). The interactive `sessionId` option lives at the
+launch builder, mirroring the existing `--resume` plumbing. Correct layering — the
+pool never touches tmux, the router never builds argv.
+
+## 4. Signal vs authority compliance
+
+The trust floor is a **resource** control (who may keep a session warm), not a new
+authority/approval surface. No gate is relaxed. Inbound trust gates are untouched.
+Trust comparison uses an explicit `TRUST_ORDER` index (never string `>=`, which
+would make `'verified' >= 'trusted'` true alphabetically) — guarded by a test.
+
+## 5. Interactions
+
+- Builds on #746: on eviction, `get()` + `jsonlExists(uuid)` resume the thread via
+  `--resume` — the e2e test forces an evict and asserts the next message resumes
+  (entry intact). `onSessionComplete` demote/persist is unchanged.
+- The interactive worker keeps project MCP (does **not** set `disableProjectMcp`),
+  matching the `-p` path, so `threadline_send` is available — the warm worker can
+  actually reply.
+- Re-verified after rebasing onto current main (v1.3.243, which added #747 Telegram
+  delivery dedupe + #748 duplicate-response guard): tsc clean; warm unit (105) +
+  integration (5) + e2e (1) + esm/empty-catch/no-direct-destructive/no-silent-
+  fallbacks gates all green. No-silent-fallbacks net count unchanged (warm
+  fail-opens annotated `@silent-fallback-ok`).
+
+## 6. External surfaces
+
+New config block `threadline.warmSessionA2A` (additive; `applyDefaults` deep-merges
+nested objects — verified by test, no `PostUpdateMigrator` patch needed). No new
+HTTP route. CLAUDE.md/template: warm sessions are internal robustness — no
+agent-facing capability surface added. Migration-parity: config is additive +
+existence-checked; dark by default on the fleet (developmentAgent gate).
+
+## 7. Rollback cost
+
+Low. Flag-off (or `developmentAgent` false) is byte-for-byte the current cold-spawn
+path — proven by flag-off tests. Full revert = the listed source files; no persisted
+format change (the pool is in-memory only). `claude.exe` allowlist + grounding-on-
+inject are independently safe to keep even if the warm path is reverted.
+
+## Framework generality
+
+Per the **Framework-Agnostic — and Framework-Optimizing** standard, the warm path
+must work for EVERY agentic framework (claude-code / codex-cli / gemini-cli /
+future), not just Claude. Two parts were initially Claude-leaning and are now
+routed through the framework abstraction:
+
+- **Inject allowlist.** `ALLOWED_INJECTION_PROCESSES` was a hardcoded shells +
+  `claude`/`claude.exe` list — a non-Claude warm worker's pane process (`codex`,
+  `gemini`) would be refused. It is now DERIVED: `shells ∪ FRAMEWORK_INJECTION_
+  PROCESS_NAMES` (new `src/core/frameworkInjectionProcesses.ts`), a
+  `Record<IntelligenceFramework, …>` so the compiler forces an entry per framework.
+- **Warm spawn framework.** The interactive keep-alive spawn now passes
+  `framework: _defaultFramework` (the local agent's framework) to
+  `spawnInteractiveSession`, so a codex/gemini agent's warm worker launches in its
+  own framework with its own MCP/permission flags. The deterministic `sessionId`
+  is mapped per-framework by `frameworkSessionLaunch` (claude pins `--session-id`;
+  codex/gemini ignore it and resume by their own mechanism) — not a Claude
+  assumption, it's the abstraction's job.
+
+**Enforced (structure, not willpower):** (1) compiler exhaustiveness on the two
+`Record<IntelligenceFramework, …>` maps; (2) `tests/unit/framework-agnosticism.test.ts`
+fails if any framework's injection-process entry is empty, a launch builder is
+missing, or the allowlist drifts from `shells ∪ registry`; (3) the `/instar-dev`
+precommit gate (`assertFrameworkGenerality`) requires this very section for any
+change to the launch/inject abstraction surface.
+
+## Conclusion
+
+Low-risk, additive, dark-gated. Completes the rapid-fire A2A continuity case on top
+of the shipped turn-based foundation, with per-thread isolation removing the shared-
+listener leak concern entirely. Both sides of every boundary are tested (warm-on
+inject vs flag-off cold-spawn; same-peer refresh vs peer-conflict fallback; evict →
+resume). Live Echo↔Dawn production round-trip is the orchestrator's standards-met
+gate (post-deploy).
+
+## Second-pass review (if required)
+
+Not required — Tier 1 (additive, dark-gated, single subsystem). The subsystem-scale
+shape (a new pool + lifecycle wiring) was handled via spec-converge + an ELI16
+review surfaced to the operator before merge, per the A4 ceremony.

package/upgrades/threadline-warm-session-a2a.eli16.md

@@ -0,0 +1,63 @@
+# Warm sessions: how rapid agent-to-agent threads stop cold-starting
+
+## The problem in one breath
+When another agent and I have a back-and-forth, each of my replies used to run as
+a **throwaway**: it answered once and exited. So when a second message arrived a
+moment later, there was nothing alive to hand it to — I'd cold-start a brand-new,
+memoryless reply. The turn-based fix I already shipped (#746) handles the *slow*
+case by re-opening the same conversation with `--resume`. But *rapid-fire* (a few
+messages in seconds) still cold-started, and on a fresh thread could even hit a
+30-second spawn cooldown.
+
+## A real bug I found while grounding this
+While reading the code I found that even when a reply session *was* briefly alive,
+my "type the next message into it" path was being **refused every single time**.
+The safety check only allows a short list of program names, and it lists `claude`
+— but on this Mac the live program actually shows up as **`claude.exe`**. So the
+check never matched, and agent-to-agent live-typing has been **dead on arrival on
+macOS**. One-line fix: allow `claude.exe`. (This is exactly why "ground before you
+assert" matters — the feature looked wired but wasn't.)
+
+## The fix (reuses what's already shipped)
+Keep the reply session **alive** between messages — exactly like my normal chat
+sessions with you, which stay open and get messages typed into them:
+- The first message from a peer spawns a **persistent** reply session (not a
+  throwaway), tracked in a small pool keyed by the thread.
+- The next message is **typed into that same live session** (now that the
+  `claude.exe` fix lets it through) — no cold-start, no cooldown.
+- The pool has tight caps (3 sessions total, 1 per peer) and a 10-minute timeout
+  so a chatty peer can't pin a pile of live sessions; when one is evicted, the
+  **next message just falls back to the proven `--resume` path** — nothing lost.
+
+## The nice surprise: the security question dissolved
+An earlier draft worried about letting "verified" peers into a **single shared**
+listener — one peer's content could mix into a session handling others. The new
+design gives **each conversation its own private session**, so there's nothing
+shared to leak. The trust gate stops being a secrecy control and becomes a simple
+"who's allowed to keep a session warm" resource control. Injected follow-ups also
+now get the same untrusted-data grounding wrapper that spawns/resumes already use.
+
+## Works for every framework — not just Claude (your note)
+
+The first cut leaned Claude-specific in two spots, and both are now routed through
+the framework abstraction so a Codex or Gemini agent gets the same warm sessions:
+- The "is this process safe to type into?" allowlist used to be hardcoded to
+  `claude`/`claude.exe`. It's now **derived** from a per-framework registry
+  (`claude → claude/claude.exe`, `codex → codex`, `gemini → gemini`), typed so the
+  compiler refuses to add a framework without giving it a process name.
+- The warm worker now launches in **the local agent's framework**, not always
+  Claude — so on a Codex agent it spins up a Codex session, with Codex's own
+  resume mechanism.
+
+And — the part you actually asked for — this is enforced by the **review process**,
+not by remembering: a CI test fails if any framework lacks coverage or the allowlist
+drifts, and the `/instar-dev` precommit gate makes any change to the launch/inject
+layer state, in writing, whether it works for Codex and Gemini. So "works for all
+frameworks" is now a gate, not a good intention.
+
+## How it ships
+Dark on the fleet, **live only on the development agent**, behind a flag, with the
+proven resume path as the fallback if a warm session is ever evicted. With the flag
+off, behavior is byte-for-byte the current cold-spawn path. Full unit + integration
++ e2e tests cover both sides: warm inject when enabled, byte-identical cold-spawn
+when disabled, peer-conflict → cold fallback, and evict → resume continuity.